npm package: @rowa-labs/ui
Description: A comprehensive UI component library built with React, Radix UI, and Tailwind CSS.
Latest version: 0.2.4

# @rowa-labs/ui

A comprehensive UI component library built with React, Radix UI, and Tailwind CSS.

## About

This package is based on [shadcn/ui](https://ui.shadcn.com), customized for ROWA with our own color palette and typography. The component APIs and usage patterns are identical to shadcn/ui, so you can refer to the [shadcn/ui documentation](https://ui.shadcn.com/docs) for detailed component usage examples.

**Key differences from shadcn/ui:**

- ✅ Pre-configured with ROWA's color palette and typography
- ✅ Published as an npm package (no need to install components individually)
- ✅ Ready to use without external shadcn/ui setup
- ✅ Same component APIs and props as shadcn/ui

## 📋 [Changelog](./CHANGELOG.md)

See [CHANGELOG.md](./CHANGELOG.md) for a list of changes and migration guides.

## Installation

```bash
npm install @rowa-labs/ui
# or
pnpm add @rowa-labs/ui
# or
yarn add @rowa-labs/ui
```

## Peer Dependencies

Make sure you have these installed:

```bash
npm install react react-dom react-hook-form
# or
pnpm add react react-dom react-hook-form
# or
yarn add react react-dom react-hook-form
```

## Setup

### 1. Install Tailwind CSS v4

**⚠️ Tailwind CSS v4 is required.**

This package requires Tailwind CSS v4. If you haven't set it up yet:

```bash
npm install -D tailwindcss@^4.0.0
# or
pnpm add -D tailwindcss@^4.0.0
```

### 2. Configure Global CSS

**Important:** Your project's `global.css` (or `globals.css`) should only contain these imports:

```css
@import 'tailwindcss';
@import '@rowa-labs/ui/global.css';
```

**Note:** The `@source` directives are already included in `@rowa-labs/ui/global.css`, so you don't need to add them to your project's CSS file.

**Next.js (App Router):**

```css
/* app/globals.css */
@import 'tailwindcss';
@import '@rowa-labs/ui/global.css';
```

Then import it in your layout:

```tsx
// app/layout.tsx
import './globals.css';
```

**Next.js (Pages Router):**

```css
/* styles/globals.css */
@import 'tailwindcss';
@import '@rowa-labs/ui/global.css';
```

```tsx
// pages/_app.tsx
import '../styles/globals.css';
```

**Vite/React:**

```css
/* src/index.css */
@import 'tailwindcss';
@import '@rowa-labs/ui/global.css';
```

```tsx
// src/main.tsx
import './index.css';
```

**Create React App:**

```css
/* src/index.css */
@import 'tailwindcss';
@import '@rowa-labs/ui/global.css';
```

```tsx
// src/index.tsx
import './index.css';
```

## Usage

### Component API Reference

Since this package is based on shadcn/ui, all components follow the same API and usage patterns. For detailed component documentation, examples, and props, refer to the [shadcn/ui documentation](https://ui.shadcn.com/docs/components).

### Import Components Individually

**Import components individually for optimal performance:**

```tsx
// ✅ Server Component - Card doesn't need 'use client'
import { Card, CardContent, CardHeader } from '@rowa-labs/ui/components/card';

// ✅ Client Component - Form needs 'use client' (preserved automatically)
import { Form, FormField } from '@rowa-labs/ui/components/form';

export default function Page() {
  return (
    <Card>
      <CardHeader>Title</CardHeader>
      <CardContent>Content</CardContent>
    </Card>
  );
}
```

### Complete Example (Next.js)

```tsx
// app/page.tsx (Server Component)
import {
  Card,
  CardContent,
  CardHeader,
  CardTitle
} from '@rowa-labs/ui/components/card';
import { Button } from '@rowa-labs/ui/components/button';

export default function HomePage() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>Welcome</CardTitle>
      </CardHeader>
      <CardContent>
        <Button>Get Started</Button>
      </CardContent>
    </Card>
  );
}
```

### Complete Example (React with Client Component)

```tsx
// components/ContactForm.tsx
'use client'; // Required for interactive components

import {
  Form,
  FormField,
  FormItem,
  FormLabel,
  FormControl
} from '@rowa-labs/ui/components/form';
import { Input } from '@rowa-labs/ui/components/input';
import { Button } from '@rowa-labs/ui/components/button';
import { useForm } from 'react-hook-form';

export function ContactForm() {
  const form = useForm();

  return (
    <Form {...form}>
      <form onSubmit={form.handleSubmit(onSubmit)}>
        <FormField
          control={form.control}
          name="email"
          render={({ field }) => (
            <FormItem>
              <FormLabel>Email</FormLabel>
              <FormControl>
                <Input {...field} />
              </FormControl>
            </FormItem>
          )}
        />
        <Button type="submit">Submit</Button>
      </form>
    </Form>
  );
}
```

## Benefits of Individual Imports

- ✅ **Preserves `'use client'` directives automatically** - Works perfectly with Next.js Server Components
- ✅ **Better tree-shaking** - Only imports what you use, smaller bundles
- ✅ **Optimal performance** - No unnecessary code in your bundle
- ✅ **Type-safe** - Full TypeScript support
- ✅ **No build step** - Uses source files directly

## TypeScript Support

This package is written in TypeScript and includes type definitions. No additional setup needed!

```tsx
import { Button } from '@rowa-labs/ui/components/button';
// Button is fully typed ✅
```

## Available Components

> 💡 **Tip:** For detailed component documentation, props, examples, and usage patterns, visit the [shadcn/ui components documentation](https://ui.shadcn.com/docs/components). All components in this package follow the same API and behavior.

### Layout & Structure

- `components/card` - Card container with header, content, footer
- `components/separator` - Visual divider
- `components/sheet` - Slide-over panel
- `components/drawer` - Bottom drawer

### Forms & Inputs

- `components/button` - Button with variants
- `components/input` - Text input
- `components/textarea` - Multi-line text input
- `components/select` - Dropdown select
- `components/checkbox` - Checkbox input
- `components/radio-group` - Radio button group
- `components/switch` - Toggle switch
- `components/slider` - Range slider
- `components/form` - Form wrapper with react-hook-form integration
- `components/label` - Form label
- `components/field` - Form field wrapper

### Overlays & Dialogs

- `components/dialog` - Modal dialog
- `components/alert-dialog` - Confirmation dialog
- `components/popover` - Popover tooltip
- `components/tooltip` - Tooltip
- `components/hover-card` - Hover card
- `components/dropdown-menu` - Dropdown menu
- `components/context-menu` - Right-click menu

### Navigation

- `components/breadcrumb` - Breadcrumb navigation
- `components/pagination` - Page navigation
- `components/tabs` - Tab navigation
- `components/navigation-menu` - Navigation menu
- `components/sidebar` - Sidebar navigation

### Data Display

- `components/table` - Data table
- `components/badge` - Status badge
- `components/avatar` - User avatar
- `components/empty` - Empty state
- `components/skeleton` - Loading skeleton
- `components/progress` - Progress bar
- `components/chart` - Charts and graphs

### Interactive

- `components/accordion` - Collapsible sections
- `components/collapsible` - Collapsible content
- `components/calendar` - Date picker calendar
- `components/carousel` - Image/content carousel
- `components/command` - Command palette
- `components/toggle` - Toggle button
- `components/toggle-group` - Toggle button group

### Feedback

- `components/alert` - Alert message
- `components/sonner` - Toast notifications (Toaster component)

### Utilities

- `components/button-group` - Button group container
- `components/input-group` - Input with addons
- `components/input-otp` - OTP input
- `components/item` - List item component
- `components/kbd` - Keyboard shortcut display
- `components/menubar` - Menu bar
- `components/resizable` - Resizable panels
- `components/scroll-area` - Custom scrollbar
- `components/spinner` - Loading spinner
- `components/stepper` - Multi-step wizard
- `components/aspect-ratio` - Maintain aspect ratio

## Hooks

```tsx
import { useIsMobile } from '@rowa-labs/ui/hooks/use-mobile';

function MyComponent() {
  const isMobile = useIsMobile();
  return <div>{isMobile ? 'Mobile' : 'Desktop'}</div>;
}
```

## Utilities

```tsx
import { cn } from '@rowa-labs/ui/lib/utils';

// Merge Tailwind classes with conflict resolution
const className = cn('text-red-500', isActive && 'text-blue-500');
```

## Framework Support

### ✅ Next.js (App Router)

Fully supported with Server Components. Use individual imports for optimal performance.

### ✅ Next.js (Pages Router)

Works perfectly. Import styles in `_app.tsx`.

### ✅ Vite + React

Fully supported. Import styles in your entry file.

### ✅ Create React App

Works with CRA. Import styles in `index.tsx`.

### ✅ Remix

Fully supported. Import styles in `root.tsx`.

## Troubleshooting

### Styles not applying?

- Make sure you're using **Tailwind CSS v4** (required)
- Ensure your `global.css` contains only:
  ```css
  @import 'tailwindcss';
  @import '@rowa-labs/ui/global.css';
  ```
- Verify the CSS file is imported in your app entry point
- Note: The `@source` directives are already included in `@rowa-labs/ui/global.css`, so you don't need to add them manually

### TypeScript errors?

- Ensure you have `@types/react` and `@types/react-dom` installed
- Check that your TypeScript version is 5.0+

### `react-hook-form` errors?

- Make sure `react-hook-form` is installed (it's a peer dependency)
- Use individual imports: `@rowa-labs/ui/components/form`

### Next.js Server Component errors?

- Use individual imports (they preserve `'use client'` directives)
- Don't use barrel exports in Server Components

## Component Documentation

Since this package is based on shadcn/ui, you can find comprehensive documentation for all components at:

- **[shadcn/ui Components](https://ui.shadcn.com/docs/components)** - Full component documentation with examples
- **[shadcn/ui Examples](https://ui.shadcn.com/examples)** - Real-world usage examples
- **[shadcn/ui Installation](https://ui.shadcn.com/docs/installation)** - Additional setup information (though you're using this package instead)

All components maintain the same API, props, and behavior as shadcn/ui - only the styling (colors, typography) has been customized for ROWA.

## Contributing

Contributions are welcome! Please see our contributing guidelines.

## License

[Your License Here]