npm package: @saint-giong/bamboo-ui
Description: A comprehensive React UI component library built with Radix UI and Tailwind CSS
Latest version: 0.6.0

# @saint-giong/bamboo-ui

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

## Installation

```bash
npm install @saint-giong/bamboo-ui
# or
yarn add @saint-giong/bamboo-ui
# or
pnpm add @saint-giong/bamboo-ui
# or
bun add @saint-giong/bamboo-ui
```

## Prerequisites

This library requires the following peer dependencies:

- React 18.0.0 or higher
- React DOM 18.0.0 or higher
- TypeScript 5.0.0 or higher

## Setup

This library requires **Tailwind CSS v4** in your project.

### Option A: Integrate with your existing Tailwind setup (Recommended)

If you already have Tailwind CSS configured in your project:

**1. Update your CSS file** (e.g., `app/globals.css`):

```css
@import "tailwindcss";
@import "tw-animate-css";
@import "@saint-giong/bamboo-ui/theme.css";
@source "../node_modules/@saint-giong/bamboo-ui/dist";

/* Your custom styles... */
```

**2. Import your CSS in layout** (e.g., `app/layout.tsx`):

```tsx
import "./globals.css";
```

This approach:

- Uses `theme.css` which contains only theme variables (no duplicate Tailwind)
- Uses `@source` to tell Tailwind to scan the library's components for class names
- Gives you full control over your Tailwind configuration

### Option B: Use library's complete CSS

For new projects or if you want the library to manage Tailwind:

```tsx
// app/layout.tsx
import "@saint-giong/bamboo-ui/globals.css";
```

This imports a complete CSS file with Tailwind, theme variables, and animations included.

## Usage

### Basic Example

```tsx
import { Button } from "@saint-giong/bamboo-ui";

function App() {
  return <Button onClick={() => alert("Clicked!")}>Click me</Button>;
}
```

### Available Components

The library includes a comprehensive set of UI components:

#### Layout & Navigation

- `Breadcrumb` - Navigation breadcrumbs
- `NavigationMenu` - Complex navigation menus
- `Sidebar` - Application sidebar layouts
- `Separator` - Visual dividers

#### Form Components

- `Button`, `ButtonGroup` - Buttons with variants
- `Input`, `InputGroup` - Text inputs with grouping
- `Textarea` - Multi-line text input
- `Select` - Dropdown selection
- `Checkbox` - Checkbox inputs
- `RadioGroup` - Radio button groups
- `Switch` - Toggle switches
- `Slider` - Range sliders
- `Calendar` - Date selection
- `InputOTP` - One-time password input
- `Field`, `Form` - Form utilities with react-hook-form integration

#### Display Components

- `Card` - Content cards
- `Badge` - Status badges
- `Avatar` - User avatars
- `Table` - Data tables
- `Alert` - Alert messages
- `Empty` - Empty state placeholder
- `Skeleton` - Loading skeletons
- `Progress` - Progress bars
- `Spinner` - Loading spinner
- `Kbd` - Keyboard shortcuts display

#### Overlay Components

- `Dialog` - Modal dialogs
- `AlertDialog` - Confirmation dialogs
- `Sheet` - Side panels
- `Drawer` - Bottom drawers
- `Popover` - Popovers
- `HoverCard` - Hover cards
- `Tooltip` - Tooltips
- `ContextMenu` - Context menus
- `DropdownMenu` - Dropdown menus
- `Menubar` - Menu bars
- `Command` - Command palette

#### Interactive Components

- `Accordion` - Collapsible content
- `Collapsible` - Toggle visibility
- `Tabs` - Tabbed interfaces
- `Toggle`, `ToggleGroup` - Toggle buttons
- `Carousel` - Image/content carousels
- `ScrollArea` - Custom scrollbars
- `Resizable` - Resizable panels

#### Data Visualization

- `Chart` - Chart components (powered by recharts)
- `Pagination` - Pagination controls

#### Notifications

- `Toaster` - Toast notifications (powered by sonner)

### Using Utilities

Import the utility functions:

```tsx
import { cn } from "@saint-giong/bamboo-ui/utils";

// Merge classes with tailwind-merge
const classes = cn("bg-red-500", "bg-blue-500"); // Results in "bg-blue-500"
```

### Using Hooks

```tsx
import { useIsMobile } from "@saint-giong/bamboo-ui";

function MyComponent() {
  const isMobile = useIsMobile();

  return <div>{isMobile ? "Mobile view" : "Desktop view"}</div>;
}
```

### Dark Mode Support

The library includes built-in dark mode support through CSS variables. Use with `next-themes` or any theme provider:

```tsx
import { ThemeProvider } from "next-themes";
import "@saint-giong/bamboo-ui/globals.css";

function App({ children }) {
  return (
    <ThemeProvider attribute="class" defaultTheme="system">
      {children}
    </ThemeProvider>
  );
}
```

## Component Examples

### Button with Variants

```tsx
import { Button } from "@saint-giong/bamboo-ui";

<Button variant="default">Default</Button>
<Button variant="destructive">Destructive</Button>
<Button variant="outline">Outline</Button>
<Button variant="secondary">Secondary</Button>
<Button variant="ghost">Ghost</Button>
<Button variant="link">Link</Button>
```

### Dialog

```tsx
import {
  Dialog,
  DialogContent,
  DialogDescription,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@saint-giong/bamboo-ui";

<Dialog>
  <DialogTrigger asChild>
    <Button>Open Dialog</Button>
  </DialogTrigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Dialog Title</DialogTitle>
      <DialogDescription>Dialog description goes here.</DialogDescription>
    </DialogHeader>
    {/* Dialog content */}
  </DialogContent>
</Dialog>;
```

### Form with Validation

```tsx
import { useForm } from "react-hook-form";
import { zodResolver } from "@hookform/resolvers/zod";
import * as z from "zod";
import {
  Form,
  FormControl,
  FormField,
  FormItem,
  FormLabel,
  FormMessage,
  Input,
  Button,
} from "@saint-giong/bamboo-ui";

const formSchema = z.object({
  username: z.string().min(2).max(50),
});

function MyForm() {
  const form = useForm({
    resolver: zodResolver(formSchema),
    defaultValues: { username: "" },
  });

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

## TypeScript Support

This library is written in TypeScript and includes type definitions out of the box.

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Support

For issues and questions, please visit the [GitHub Issues](https://github.com/saint-giong/bamboo-ui/issues) page.