@mosaicag/common-ui

A comprehensive UI component library built on top of Hero UI for the Mosaic project. This package provides a collection of reusable React components with consistent styling and behavior.

Features

• 🎨 Built on Hero UI (NextUI) for modern, accessible components
• 📦 Tree-shakable exports for optimal bundle size
• 🔧 TypeScript support with full type definitions
• 🎯 Custom component variants and extensions
• 🚀 Ready-to-use in any React application

Installation

This package is part of the Mosaic monorepo. To use it in other packages within the workspace:

# Install dependencies (from monorepo root)
pnpm install

# Build the UI package
cd packages/ui && pnpm build

Usage

Basic Import

Import HeroUI primitives from the main package:

import { Button, Card, Input } from '@mosaicag/common-ui';

function MyComponent() {
  return (
    <Card>
      <Input placeholder='Enter text' />
      <Button color='primary'>Submit</Button>
    </Card>
  );
}

Import custom web3 components from the web3 subpath:

import {
  TokenProvider,
  TokenName,
  TokenSymbol,
  TokenIcon,
} from '@mosaicag/common-ui/web3';

function TokenDisplay() {
  return (
    <TokenProvider id='0x123...'>
      <div className='relative'>
        <TokenIcon className='h-5 w-5' />
        <TokenVerifyBadge />
      </div>
      <TokenName /> (<TokenSymbol />)
    </TokenProvider>
  );
}

Mixed Import (Not Recommended)

While you can import both HeroUI and web3 components from their respective paths, it's recommended to use separate imports for clarity:

import { Button, Card, Input } from '@mosaicag/common-ui';
import { TokenProvider } from '@mosaicag/common-ui/web3';

Provider Setup

Wrap your app with the NextUIProvider:

import { NextUIProvider } from '@mosaicag/common-ui';

function App() {
  return <NextUIProvider>{/* Your app content */}</NextUIProvider>;
}

Available Components

HeroUI Components (@mosaicag/common-ui)

The main package exports all Hero UI components, including:

Layout & Navigation

• Navbar, NavbarBrand, NavbarContent, NavbarItem, NavbarMenu
• Breadcrumbs, BreadcrumbItem
• Divider, Spacer

Form Controls

• Button, Input, Textarea, Select, SelectItem
• Checkbox, Radio, RadioGroup, Switch, Slider

Data Display

• Card, CardHeader, CardBody, CardFooter
• Table, TableHeader, TableBody, TableColumn, TableRow, TableCell
• Avatar, Badge, Chip, Image, User
• Progress, Skeleton, Spinner

Feedback

• Modal, ModalContent, ModalHeader, ModalBody, ModalFooter
• Tooltip, Dropdown, DropdownTrigger, DropdownMenu, DropdownItem

Utilities

• Accordion, AccordionItem
• Tabs, Tab
• Pagination
• Snippet, Code, Kbd

Web3 Components (@mosaicag/common-ui/web3)

TokenProvider

Provider component for token data with compound pattern:

import {
  TokenProvider,
  TokenName,
  TokenSymbol,
  TokenIcon,
  TokenPrice,
  TokenBalance,
} from '@mosaicag/common-ui/web3';

function TokenCard() {
  return (
    <TokenProvider
      id='0x123...'
      fallback={<div>Token not found</div>}
      loadingFallback={<div>Loading...</div>}
    >
      <div className='flex items-center gap-2'>
        <div className='relative'>
          <TokenIcon className='h-8 w-8' />
          <TokenVerifyBadge height={16} width={16} />
        </div>
        <div>
          <TokenName /> (<TokenSymbol />)
          <TokenPrice>{price => <span>${price.price}</span>}</TokenPrice>
          <TokenBalance>
            {balance => <span>Balance: {balance}</span>}
          </TokenBalance>
        </div>
      </div>
    </TokenProvider>
  );
}

CustomButton

A custom button component with predefined styling variants:

import { CustomButton } from '@mosaicag/common-ui/web3';

<CustomButton customVariant="primary">Primary Button</CustomButton>
<CustomButton customVariant="secondary">Secondary Button</CustomButton>
<CustomButton customVariant="success">Success Button</CustomButton>
<CustomButton customVariant="danger">Danger Button</CustomButton>

Development

Running the Demo

cd packages/ui
pnpm dev

This will start a development server showcasing all available components.

Building

cd packages/ui
pnpm build

Adding Custom Components

1. Create your component in src/components/
2. Export it from src/components/index.ts
3. The component will be automatically available through the main package export

Type Safety

All components come with full TypeScript support. Import types as needed:

// HeroUI component types
import type { ButtonProps, CardProps, InputProps } from '@mosaicag/common-ui';

// Web3 component types
import type { CustomButtonProps } from '@mosaicag/common-ui/web3';

Package Structure

packages/ui/
├── src/
│   ├── components/          # Custom web3 components
│   │   ├── custom-button.tsx
│   │   ├── token.tsx
│   │   └── index.ts
│   ├── web3.ts             # Custom web3 components export
│   ├── index.ts            # HeroUI primitives export
│   ├── App.tsx             # Demo application
│   └── main.tsx            # Demo entry point
├── dist/                   # Built files
│   ├── web3.js             # Web3 components bundle
│   └── index.js            # HeroUI primitives bundle
├── package.json
├── tsconfig.build.json     # Build configuration
└── tsup.config.ts          # Build tool configuration

Export Structure

The package now supports tree-shakable exports:

• @mosaicag/common-ui - HeroUI primitive components only
• @mosaicag/common-ui/web3 - Custom web3-specific components

Contributing

When adding new components:

1. Follow the existing patterns for component structure
2. Include TypeScript types
3. Update the main index.ts export
4. Add examples to the demo app
5. Update this README if needed

License

Part of the Mosaic project.