@matheusrizzati/ui 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,300 @@
+# @matheusrizzati/ui
+
+A premium React UI component library built for modern SaaS applications. Features a dual light/dark theme (Obsidian), 39 production-ready components, and a flexible token-based design system.
+
+## ✨ Features
+
+- 🎨 **Dual Theme** — Light mode + Obsidian dark mode with seamless toggle
+- 📦 **39 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 |
+
+### 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 |
+
+### 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 |
+| `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 |
+
+### 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 |
+
+### 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