@matheusrizzati/ui 0.1.1 → 0.1.3

package/README.md

@@ -1,166 +1,307 @@
 # @matheusrizzati/ui
 
-A lightweight, premium dark-themed React UI library for modern SaaS dashboards. Built with React, Tailwind CSS, and Radix 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.
 
-![License](https://img.shields.io/npm/l/@matheusrizzati/ui)
-![Version](https://img.shields.io/npm/v/@matheusrizzati/ui)
+## ✨ Features
 
-## 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
 
-- 🌑 **Premium Dark Theme**: Designed for modern, dark-mode first applications.
-- 🎨 **Tailwind CSS**: Built on top of Tailwind for easy customization.
-- 🧩 **Radix UI Primitives**: Accessible and robust interactive components.
-- ⚡ **Lightweight**: Tree-shakable ESM and CJS builds.
-- ⌨️ **Typed**: Written in TypeScript with full type definitions.
+---
 
-## Installation
+## 📥 Installation
 
 ```bash
 npm install @matheusrizzati/ui
-# or
-yarn add @matheusrizzati/ui
-# or
-pnpm add @matheusrizzati/ui
 ```
 
-## Setup
-
-### 1. Configure Tailwind CSS
-
-Add the library's content path and tokens to your `tailwind.config.ts` (or `.js`):
-
-```ts
-// tailwind.config.ts
-import type { Config } from "tailwindcss";
-
-const config: Config = {
-  content: [
-    "./src/**/*.{js,ts,jsx,tsx}",
-    // Add this line to include the library's components
-    "./node_modules/@matheusrizzati/ui/dist/**/*.{js,ts,jsx,tsx}",
-  ],
-  theme: {
-    extend: {},
-  },
-  plugins: [],
-};
-
-export default config;
+**Peer dependencies:**
+```bash
+npm install react react-dom
 ```
 
-### 2. Import Styles
+---
 
-Import the CSS tokens in your global CSS file (e.g., `src/index.css` or `src/globals.css`):
+## 🚀 Setup
 
-```css
-@import "@matheusrizzati/ui/tokens.css";
+### 1. Import the CSS
 
-@tailwind base;
-@tailwind components;
-@tailwind utilities;
-```
+In your app's entry file (e.g., `main.tsx` or `layout.tsx`):
 
-## Usage
+```tsx
+import "@matheusrizzati/ui/tokens.css";
+```
 
-### Button
+### 2. Add the ThemeProvider
 
 ```tsx
-import { Button } from "@matheusrizzati/ui";
+import { ThemeProvider } from "@matheusrizzati/ui";
 
-export function App() {
+function App() {
   return (
-    <div className="flex gap-4">
-      <Button variant="primary">Primary Action</Button>
-      <Button variant="secondary">Secondary</Button>
-      <Button variant="outline">Outline</Button>
-      <Button variant="ghost">Ghost</Button>
-      <Button variant="danger">Delete</Button>
-    </div>
+    <ThemeProvider defaultTheme="system">
+      {/* your app */}
+    </ThemeProvider>
   );
 }
 ```
 
-### Input
+The `ThemeProvider` supports three modes:
+- `"light"` — Light theme
+- `"dark"` — Obsidian dark theme
+- `"system"` — Follows OS preference (default)
+
+### 3. Toggle themes
 
 ```tsx
-import { Input } from "@matheusrizzati/ui";
+import { useTheme } from "@matheusrizzati/ui";
 
-export function LoginForm() {
+function ThemeToggle() {
+  const { resolvedTheme, toggleTheme } = useTheme();
   return (
-    <div className="space-y-4">
-      <Input label="Email" placeholder="hello@example.com" type="email" />
-      <Input label="Password" type="password" />
-    </div>
+    <button onClick={toggleTheme}>
+      {resolvedTheme === "dark" ? "☀️" : "🌙"}
+    </button>
   );
 }
 ```
 
-### Card
+### 4. Tailwind CSS (if using)
 
-```tsx
-import { Card, CardHeader, CardBody, CardFooter, Button } from "@matheusrizzati/ui";
+Add `darkMode: "class"` to your `tailwind.config.ts` and include the library in `content`:
 
-export function PricingCard() {
-  return (
-    <Card>
-      <CardHeader>
-        <h3 className="text-lg font-medium text-text-primary">Pro Plan</h3>
-      </CardHeader>
-      <CardBody>
-        <p className="text-text-secondary">Access to all premium features.</p>
-      </CardBody>
-      <CardFooter>
-        <Button className="w-full">Upgrade</Button>
-      </CardFooter>
-    </Card>
-  );
-}
+```ts
+export default {
+  darkMode: "class",
+  content: [
+    "./src/**/*.{ts,tsx}",
+    "./node_modules/@matheusrizzati/ui/dist/**/*.{js,cjs}",
+  ],
+};
 ```
 
-### Sidebar
+---
+
+## 📚 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 { 
-  Sidebar, 
-  SidebarHeader, 
-  SidebarContent, 
-  SidebarItem, 
-  SidebarToggle, 
-  LayoutDashboard, 
-  Settings 
-} from "@matheusrizzati/ui"; // Note: Icons like LayoutDashboard need to be installed separately (e.g. lucide-react)
-
-export function DashboardLayout({ children }) {
+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 (
-    <div className="flex h-screen bg-bg">
+    <AppShell>
       <Sidebar>
-        <SidebarHeader logo={<MyLogo />} />
+        <SidebarHeader>My App</SidebarHeader>
         <SidebarContent>
-          <SidebarItem active>Dashboard</SidebarItem>
-          <SidebarItem>Settings</SidebarItem>
+          <SidebarSection label="Menu">
+            <SidebarItem active>Dashboard</SidebarItem>
+            <SidebarItem>Users</SidebarItem>
+            <SidebarItem>Settings</SidebarItem>
+          </SidebarSection>
         </SidebarContent>
-        <SidebarToggle />
       </Sidebar>
-      <main className="flex-1 p-6">{children}</main>
-    </div>
+
+      <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>
   );
 }
 ```
 
-## Theming
+---
 
-The library uses CSS variables for theming. You can override these in your `:root` or a specific scope to change the appearance.
+## 🎨 Customizing Tokens
+
+Override CSS variables in your own stylesheet to customize the theme:
 
 ```css
 :root {
-  /* Override primary color to Blue */
-  --color-primary: #3b82f6; 
-  --color-primary-hover: #60a5fa;
-  --color-primary-active: #2563eb;
-  
-  /* Override radius */
-  --radius: 8px;
+  /* 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;
 }
 ```
 
-See all available tokens in `node_modules/@matheusrizzati/ui/dist/tokens.css`.
+---
+
+## 🛠️ 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