npm package: @mosaicag/common-ui
Description: 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.
Latest version: 1.0.1

# @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:

```bash
# 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:

```tsx
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:

```tsx
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:

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

### Provider Setup

Wrap your app with the NextUIProvider:

```tsx
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:

```tsx
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:

```tsx
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

```bash
cd packages/ui
pnpm dev
```

This will start a development server showcasing all available components.

### Building

```bash
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:

```tsx
// 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.