npm package: @matheusrizzati/ui
Description: A lightweight, premium dark-themed React UI library for modern SaaS dashboards
Latest version: 0.1.3

# @matheusrizzati/ui

A premium React UI component library built for modern SaaS applications. Features a dual light/dark theme (Obsidian), 45 production-ready components, and a flexible token-based design system.

## ✨ Features

- 🎨 **Dual Theme** — Light mode + Obsidian dark mode with seamless toggle
- 📦 **45 Components** — Forms, data display, overlays, navigation, feedback, and layout
- 🔧 **Token-Based** — Fully customizable via CSS variables
- ♿ **Accessible** — Built on Radix UI primitives where it matters
- 📐 **TypeScript** — Full type safety and IntelliSense
- 🪶 **Lightweight** — Tree-shakeable ESM + CJS output

---

## 📥 Installation

```bash
npm install @matheusrizzati/ui
```

**Peer dependencies:**
```bash
npm install react react-dom
```

---

## 🚀 Setup

### 1. Import the CSS

In your app's entry file (e.g., `main.tsx` or `layout.tsx`):

```tsx
import "@matheusrizzati/ui/tokens.css";
```

### 2. Add the ThemeProvider

```tsx
import { ThemeProvider } from "@matheusrizzati/ui";

function App() {
  return (
    <ThemeProvider defaultTheme="system">
      {/* your app */}
    </ThemeProvider>
  );
}
```

The `ThemeProvider` supports three modes:
- `"light"` — Light theme
- `"dark"` — Obsidian dark theme
- `"system"` — Follows OS preference (default)

### 3. Toggle themes

```tsx
import { useTheme } from "@matheusrizzati/ui";

function ThemeToggle() {
  const { resolvedTheme, toggleTheme } = useTheme();
  return (
    <button onClick={toggleTheme}>
      {resolvedTheme === "dark" ? "☀️" : "🌙"}
    </button>
  );
}
```

### 4. Tailwind CSS (if using)

Add `darkMode: "class"` to your `tailwind.config.ts` and include the library in `content`:

```ts
export default {
  darkMode: "class",
  content: [
    "./src/**/*.{ts,tsx}",
    "./node_modules/@matheusrizzati/ui/dist/**/*.{js,cjs}",
  ],
};
```

---

## 📚 Component Catalog

### Forms & Inputs

| Component | Description | Key Features |
|-----------|-------------|--------------|
| `Button` | Primary action trigger | 5 variants, 3 sizes, loading state, icon support |
| `Input` | Text input field | Start/end icons, clearable (`onClear`), error state |
| `Textarea` | Multi-line text input | Auto-resize, character count |
| `Select` | Custom dropdown select | **Searchable**, clearable, groups, icons, descriptions, keyboard nav |
| `Combobox` | Autocomplete/typeahead | Multi-select, **creatable**, groups, loading state |
| `Checkbox` | Boolean toggle box | Indeterminate state |
| `Radio` | Single selection group | RadioGroup + Radio |
| `Switch` | Toggle switch | Labels, sizes |
| `Slider` | Range input | Pointer drag, keyboard, step snapping, value display |
| `Toggle` | Pressed/unpressed button | Toolbar toggles, view modes |
| `ToggleGroup` | Group of toggles | Single/multiple selection |
| `DatePicker` | Date input with calendar | Popover calendar, clearable, min/max dates |

### Data Display

| Component | Description | Key Features |
|-----------|-------------|--------------|
| `Table` | Basic table primitives | Thead, Tbody, Tr, Th, Td |
| `DataTable` | Feature-rich data table | Sorting, pagination, row selection |
| `Badge` | Status/category label | 6 variants, 3 sizes |
| `Avatar` | User/entity image | Sizes, shapes, status indicator |
| `AvatarGroup` | Stacked avatars | `max` prop, +N overflow counter |
| `Card` | Content container | Elevated, outlined, ghost variants |
| `StatCard` | KPI metric card | Change indicator, icon slot |
| `Skeleton` | Loading placeholder | Pulse animation |
| `Progress` | Progress bar | Variants, sizes, label |
| `Calendar` | Date grid | Month nav, min/max, locale support |

### Navigation

| Component | Description | Key Features |
|-----------|-------------|--------------|
| `Tabs` | Tab switcher | Segmented style |
| `Breadcrumb` | Path navigation | Separator, active state |
| `Pagination` | Page navigation | Page numbers, ellipsis |
| `Sidebar` | App sidebar | Collapsible, sections, active items |
| `Navbar` | Top navigation bar | — |
| `Steps` | Step indicator | Completed/active/upcoming states |

### Overlays

| Component | Description | Key Features |
|-----------|-------------|--------------|
| `Modal` | Dialog window | Radix Dialog, title/description/footer |
| `Drawer` | Slide-out panel | **4 sides**, 5 sizes, header/body/footer |
| `Dropdown` | Context/action menu | Radix DropdownMenu, labels, groups, separators |
| `Tooltip` | Hover info | Radix Tooltip |
| `Popover` | Click popover | Radix Popover |
| `HoverCard` | Rich hover preview | Radix HoverCard, configurable delays |
| `ConfirmDialog` | Destructive action confirm | Danger/primary variants, loading state |

### Feedback

| Component | Description | Key Features |
|-----------|-------------|--------------|
| `Alert` | Inline message | Info, success, warning, danger |
| `Toast` | Notification popup | Provider + `useToast()` hook |
| `EmptyState` | No-data placeholder | Icon, title, description, action |
| `Spinner` | Loading spinner | 5 sizes, primary color |

### Layout

| Component | Description | Key Features |
|-----------|-------------|--------------|
| `AppShell` | Full page layout | Sidebar + content areas |
| `PageHeader` | Page title section | Title, description, action slot |
| `Separator` | Visual divider | Horizontal/vertical |
| `Accordion` | Collapsible sections | Single/multiple mode, smooth animation |
| `Collapsible` | Simple expand/collapse | Controlled/uncontrolled, Trigger + Content |

### Utilities

| Export | Description |
|--------|-------------|
| `ThemeProvider` | Light/dark/system toggle + persistence |
| `useTheme()` | Access theme state and controls |
| `cn()` | Class merging utility (clsx + tailwind-merge) |
| `CommandPalette` | ⌘K search palette |

---

## 🎯 Quick Start Example

```tsx
import {
  ThemeProvider,
  AppShell,
  Sidebar,
  SidebarHeader,
  SidebarContent,
  SidebarSection,
  SidebarItem,
  Navbar,
  PageHeader,
  Button,
  Card,
  CardHeader,
  CardBody,
  StatCard,
  Input,
  Select,
  DataTable,
  useTheme,
} from "@matheusrizzati/ui";

function Dashboard() {
  const { toggleTheme, resolvedTheme } = useTheme();

  return (
    <AppShell>
      <Sidebar>
        <SidebarHeader>My App</SidebarHeader>
        <SidebarContent>
          <SidebarSection label="Menu">
            <SidebarItem active>Dashboard</SidebarItem>
            <SidebarItem>Users</SidebarItem>
            <SidebarItem>Settings</SidebarItem>
          </SidebarSection>
        </SidebarContent>
      </Sidebar>

      <main>
        <Navbar>
          <Button variant="ghost" onClick={toggleTheme}>
            {resolvedTheme === "dark" ? "☀️" : "🌙"}
          </Button>
        </Navbar>

        <div className="p-6">
          <PageHeader
            title="Dashboard"
            description="Overview of your metrics"
          />

          <div className="grid grid-cols-3 gap-4 mb-6">
            <StatCard title="Revenue" value="$12,345" change="+12%" />
            <StatCard title="Users" value="1,234" change="+5%" />
            <StatCard title="Orders" value="567" change="-2%" />
          </div>

          <Card>
            <CardHeader>Recent Orders</CardHeader>
            <CardBody>
              <DataTable
                columns={[
                  { key: "id", header: "ID" },
                  { key: "customer", header: "Customer" },
                  { key: "total", header: "Total" },
                ]}
                data={[
                  { id: "#001", customer: "John Doe", total: "$99.00" },
                  { id: "#002", customer: "Jane Smith", total: "$149.00" },
                ]}
              />
            </CardBody>
          </Card>
        </div>
      </main>
    </AppShell>
  );
}
```

---

## 🎨 Customizing Tokens

Override CSS variables in your own stylesheet to customize the theme:

```css
:root {
  /* Change the primary color to emerald */
  --color-primary-500: #10b981;
  --color-primary-600: #059669;
  --color-primary-700: #047857;
  --color-primary: var(--color-primary-600);
  --color-primary-hover: var(--color-primary-700);

  /* Change the font */
  --font-sans: "Inter", sans-serif;

  /* Adjust border radius */
  --radius: 0.75rem;
}
```

---

## 🛠️ Tech Stack

- **React 18+** with TypeScript
- **Tailwind CSS** for utility classes
- **Radix UI** for accessible primitives (Dialog, Dropdown, Tooltip, Popover, AlertDialog)
- **CVA** (class-variance-authority) for variant management
- **tsup** for building ESM + CJS bundles

---

## 📦 Exports

```
dist/
├── index.js        # ESM
├── index.cjs       # CommonJS
├── index.d.ts      # TypeScript declarations
├── index.d.cts     # CTS declarations  
├── styles.css      # Compiled styles
└── tokens.css      # Design tokens (import this!)
```

## 📄 License

MIT