@jacshuo/onyx 2.1.0 → 2.2.0

package/README.md

@@ -3,6 +3,9 @@
   <img src="https://img.shields.io/npm/l/@jacshuo/onyx?style=flat-square" alt="license" />
   <img src="https://img.shields.io/github/actions/workflow/status/jacshuo/OnyxUI/ci.yml?branch=main&style=flat-square&label=CI" alt="CI" />
   <img src="https://img.shields.io/npm/dm/@jacshuo/onyx?color=10b981&style=flat-square" alt="downloads" />
+  <img src="https://img.shields.io/badge/React-18%2B-61dafb?style=flat-square&logo=react" alt="React 18+" />
+  <img src="https://img.shields.io/badge/Tailwind_CSS-v4-38bdf8?style=flat-square&logo=tailwindcss" alt="Tailwind CSS v4" />
+  <img src="https://img.shields.io/badge/TypeScript-strict-3178c6?style=flat-square&logo=typescript" alt="TypeScript" />
 </p>
 
 <p align="right">
@@ -11,9 +14,9 @@
 
 # @jacshuo/onyx
 
-A **React UI component library** built with Tailwind CSS v4 — crafted for responsive web apps and Electron desktop applications alike. Ships tree-shakeable ESM + CJS bundles with per-component subpath exports, modular CSS, and full TypeScript declarations.
+A **cross-platform React UI component library** built on Tailwind CSS v4 — designed for responsive web apps, content-rich dashboards, and Electron desktop applications. Ships 55+ production-ready components as individually tree-shakeable ESM + CJS bundles with full TypeScript declarations.
 
-Born from a passion for **polished cross-platform experiences**, Onyx delivers a consistent look and feel from mobile screens to 4K displays — with dark mode, keyboard navigation, and touch interactions built in from day one.
+Born from a passion for **polished cross-platform experiences**, Onyx delivers a consistent look and feel from mobile screens to 4K displays — with dark mode, keyboard navigation, accessible form wiring, and touch interactions built in from day one.
 
 > **Live Demo →** [jacshuo.github.io/OnyxUI](https://jacshuo.github.io/OnyxUI)
 
@@ -21,29 +24,39 @@ Born from a passion for **polished cross-platform experiences**, Onyx delivers a
 
 ## Why Onyx?
 
-- **Responsive by design** — Every component adapts from a phone screen to a 4K display without a single extra media query from you. Headers fold to hamburger menus, sidebars slide to icon-only or drawer modes, dialogs become bottom sheets — all built in. Size variants (`sm` / `md` / `lg`) and semantic CSS tokens make density adjustments trivial.
-- **Desktop & Electron first-class support** — Onyx is crafted with Electron and desktop apps as a primary use case. Components are optimized for keyboard navigation, pointer interactions, and content-dense layouts that most mobile-first libraries struggle to deliver.
-- **Production-ready out of the box** — Dark mode, design tokens, accessibility, touch gestures, and keyboard shortcuts are built in from day one — not bolted on as an afterthought.
-- **Minimal footprint, maximum control** — No runtime CSS-in-JS. Just Tailwind CSS v4 utility classes and CSS custom properties. Override any token without ejecting or fighting specificity wars.
-- **Rich, specialized components** — Beyond the usual buttons and inputs, Onyx includes `CinePlayer`, `MiniPlayer`, `FileExplorer`, and `DataTable` — components that are hard to find in general-purpose libraries but essential for media-rich and desktop-class applications.
+### Responsive without compromise
+Every component adapts from a phone screen to a 4K display — without a single extra media query from you. Headers fold to hamburger menus, sidebars become draggable mobile drawers, dialogs become bottom sheets, and table layouts reflow gracefully. Size variants (`sm` / `md` / `lg`) and CSS custom property tokens make density adjustments trivial.
+
+### Desktop & Electron — first-class
+Onyx treats Electron and desktop apps as primary targets. Components are optimized for keyboard navigation, pointer interactions, content-dense layouts, and drag interactions — territory where most mobile-first libraries underdeliver. `CinePlayer`, `MiniPlayer`, `FileExplorer`, `CommandPalette`, `RibbonBar`, and `FilmReel` are purpose-built for desktop-class applications.
+
+### Accessible by construction
+`FormItem` automatically injects `id`, `aria-describedby`, and `aria-invalid` into child controls — no manual wiring. Every interactive component follows WCAG label-for semantics. Screen readers, keyboard users, and autofill all work correctly out of the box.
+
+### Zero-config theming
+No build tool plugins. No `tailwind.config.js`. Override any design decision via `@theme {}` tokens or CSS custom properties — including at media query breakpoints. Dark mode is class-based (`.dark` on any ancestor) and works everywhere.
+
+### Minimal footprint, maximum control
+No runtime CSS-in-JS. No styled-components. Just Tailwind CSS v4 utility classes and CSS custom properties. Import only what you use — per-component subpath exports ensure unused components never reach your bundle.
 
 ---
 
-## Features
-
-- 🎨 **30+ components** — from Button → DataTable → CinePlayer → CodeBlock
-- 📱 **Responsive by default** — built-in breakpoint layouts, touch-friendly tap targets, and adaptive component modes (hamburger nav, drawer sidebar, bottom-sheet dialog)
-- 🌗 **Dark / Light mode** — class-based, works out of the box
-- 🎯 **CSS variable design tokens** — override any design decision via CSS custom properties, including at media query breakpoints
-- ⚡ **Tailwind CSS v4** — zero config, `@theme` tokens, `color-mix()` accent support
-- 📦 **Tree-shakeable** — Per-component ESM entries with code splitting; import only what you use
-- 🗂️ **On-demand imports** — Subpath exports (`@jacshuo/onyx/Button`) for maximum control
-- 🎨 **Modular CSS** — Full bundle, base-only, or per-component CSS — pick exactly what you need
-- 🖥️ **Cross-platform** — built for web & Electron desktop apps
-- ⌨️ **Keyboard-first** — comprehensive keyboard shortcuts for CinePlayer, FileExplorer, and more
-- 👆 **Touch & gesture support** — tap-to-reveal, focus-visible states, and touch-optimized interactions across all interactive components
-- 🔤 **Full TypeScript** — every prop, event, and variant is typed
-- 🧩 **Composable API** — compound component patterns (e.g., `Dialog` → `DialogContent` + `DialogHeader` + `DialogFooter`) let you assemble exactly what you need
+## Features at a Glance
+
+| | |
+|---|---|
+| 🧩 **55+ components** | Primitives → Charts → CinePlayer → DataTable, covering the full UI spectrum |
+| 📱 **Responsive by default** | Built-in breakpoint layouts, adaptive component modes, touch-friendly tap targets |
+| ♿ **Accessible by default** | WCAG label-for, ARIA roles, keyboard navigation, and sr-only wiring throughout |
+| 🌗 **Dark / Light mode** | Class-based dark mode, works on any subtree |
+| 📊 **Charts included** | BarChart, LineChart, PieChart, ScatterChart — no extra charting library needed |
+| ⚡ **Tailwind CSS v4** | Zero config — `@theme` tokens, pure CSS design system |
+| 📦 **Tree-shakeable** | Per-component ESM subpath exports — import only what you use |
+| 🎨 **Modular CSS** | Full bundle, base-only, or per-component CSS — pick what you need |
+| 🖥️ **Electron ready** | Keyboard shortcuts, drag interactions, content-dense layouts |
+| 🔤 **Full TypeScript** | Every prop, variant, and event is strictly typed |
+| 🧩 **Composable API** | Compound component patterns for full layout control |
+| ✅ **519 tests** | 36 test files — Vitest + jsdom + Testing Library |
 
 ---
 
@@ -57,13 +70,7 @@ pnpm add @jacshuo/onyx
 yarn add @jacshuo/onyx
 ```
 
-### Peer Dependencies
-
-```bash
-npm install react react-dom
-```
-
-> Requires **React ≥ 18.0.0**.
+Requires **React ≥ 18.0.0** and **react-dom ≥ 18.0.0**.
 
 ---
 
@@ -72,7 +79,6 @@ npm install react react-dom
 **1. Import the stylesheet** (once, at your app entry point):
 
 ```tsx
-// main.tsx or App.tsx
 import '@jacshuo/onyx/styles.css';
 ```
 
@@ -99,140 +105,211 @@ function App() {
 
 ## Import Strategies
 
-Onyx supports multiple import styles — pick the one that best fits your bundler and performance requirements.
+Choose the style that fits your bundler and performance requirements.
 
-### Full import (simplest)
+### Flat import (simplest)
 
-Import everything from the barrel entry. Modern bundlers (Vite, Next.js, webpack 5) will tree-shake unused components automatically.
+Modern bundlers (Vite, Next.js, webpack 5) tree-shake unused components automatically.
 
 ```tsx
-import { Button, Dialog, Tabs } from '@jacshuo/onyx';
+import { Button, Dialog, Tabs, Form, FormItem, Input } from '@jacshuo/onyx';
 import '@jacshuo/onyx/styles.css';
 ```
 
 ### Per-component import (maximum tree-shaking)
 
-Import each component from its own subpath. This guarantees only the code you use is included, even with bundlers that don't tree-shake well.
-
-Components are organized under category subpaths (`Primitives`, `Overlay`, `Disclosure`, `DataDisplay`, `Navigation`, `Layout`, `Feedback`, `Forms`, `Extras`):
+Guarantees only the code you use is included, even with bundlers that don't tree-shake well.
 
 ```tsx
-// Individual component
 import { Button } from '@jacshuo/onyx/Primitives/Button';
 import { Dialog, DialogContent } from '@jacshuo/onyx/Overlay/Dialog';
-import { Tabs, TabList, TabTrigger } from '@jacshuo/onyx/Disclosure/Tabs';
+import { LineChart } from '@jacshuo/onyx/Chart/LineChart';
+```
+
+### Category namespace
+
+```tsx
+import { Primitives, Overlay, Chart } from '@jacshuo/onyx';
 
-// Or import everything from a category at once
-import { Button, Input, Badge } from '@jacshuo/onyx/Primitives';
-import { Alert } from '@jacshuo/onyx/Feedback';
+<Primitives.Button intent="primary">Save</Primitives.Button>
+<Chart.BarChart data={data} />
 ```
 
 ### CSS options
 
-| Import | Size | Description |
-|---|---|---|
-| `@jacshuo/onyx/styles.css` | ~102 KB | Full pre-compiled bundle — all utilities + all component CSS. Simplest setup. |
-| `@jacshuo/onyx/styles/base.css` | ~95 KB | Tailwind utilities + core design tokens. No component-specific keyframes. |
-| `@jacshuo/onyx/styles/tailwind.css` | ~4 KB | **For projects with their own Tailwind CSS v4.** Includes `@source` directive, tokens & dark mode variant. |
-| `@jacshuo/onyx/styles/tokens.css` | ~4 KB | Raw `@theme` tokens only — no `@source`, no Tailwind import. |
-| `@jacshuo/onyx/styles/CinePlayer.css` | ~2.5 KB | CinePlayer keyframes & `--cp-*` design tokens |
-| `@jacshuo/onyx/styles/MiniPlayer.css` | ~2.2 KB | MiniPlayer keyframes & `--mp-*` design tokens |
-| `@jacshuo/onyx/styles/FileExplorer.css` | ~1.6 KB | FileExplorer `--fe-*` design tokens |
-| `@jacshuo/onyx/styles/FilmReel.css` | ~0.6 KB | FilmReel keyframes |
-
-#### Using with your own Tailwind CSS v4 setup
+| Import | Description |
+|---|---|
+| `@jacshuo/onyx/styles.css` | Full pre-compiled bundle — all utilities + all component CSS. Simplest setup. |
+| `@jacshuo/onyx/styles/base.css` | Tailwind utilities + core design tokens. No component-specific keyframes. |
+| `@jacshuo/onyx/styles/tailwind.css` | **For projects with their own Tailwind CSS v4.** Includes `@source` + tokens + dark variant. |
+| `@jacshuo/onyx/styles/tokens.css` | Raw `@theme` tokens only. |
+| `@jacshuo/onyx/styles/CinePlayer.css` | CinePlayer keyframes & `--cp-*` tokens |
+| `@jacshuo/onyx/styles/MiniPlayer.css` | MiniPlayer keyframes & `--mp-*` tokens |
+| `@jacshuo/onyx/styles/FileExplorer.css` | FileExplorer `--fe-*` tokens |
+| `@jacshuo/onyx/styles/FilmReel.css` | FilmReel keyframes |
 
-If your project already runs Tailwind CSS v4 and you want to import only the tokens (not the full pre-compiled bundle), you **must** use `tailwind.css` so that Tailwind scans the library's JS files for class names:
+#### Using alongside your own Tailwind CSS v4
 
 ```css
 /* your app's CSS entry */
 @import "tailwindcss";
 @import "@jacshuo/onyx/styles/tailwind.css";
 
-/* optionally add per-component CSS for CinePlayer, MiniPlayer, etc. */
+/* add per-component CSS as needed */
 @import "@jacshuo/onyx/styles/CinePlayer.css";
 ```
 
-> **Why?** Onyx components use Tailwind utility classes defined in JavaScript (via CVA). Without `@source`, your Tailwind build won't know about these classes and they won't be generated. The `tailwind.css` file includes `@source ".."` which tells Tailwind v4 to scan the library's compiled JS.
->
-> **Do NOT** use `tokens.css` alone — it only provides design tokens without the `@source` directive, so component styles will be incomplete.
-
-**Example — minimal setup with CinePlayer only:**
-
-```tsx
-import '@jacshuo/onyx/styles/base.css';
-import '@jacshuo/onyx/styles/CinePlayer.css';
-import { CinePlayer } from '@jacshuo/onyx/Extras/CinePlayer';
-```
+> Use `tailwind.css` — not `tokens.css` — so that Tailwind's scanner picks up class names from Onyx's compiled JS via the included `@source` directive.
 
 ---
 
-## Components
+## Component Library
 
 ### Primitives
 
 | Component | Description |
 |---|---|
-| **Button** | Primary, secondary, danger, warning, ghost, outline intents with sm/md/lg sizes |
-| **Input** | Styled text input with variant support |
+| **Button** | 6 intents (primary, secondary, danger, warning, ghost, outline) × 3 sizes |
+| **Input** | Text input with prefix, suffix, action button, and size variants |
+| **TextBox** | Textarea with live word/character count and CJK-aware counting |
+| **Dropdown** | Single & multi-select with search, grouped options, clearable, and keyboard nav |
+| **Checkbox** | Tri-state (checked, unchecked, indeterminate) with label |
+| **Radio / RadioGroup** | Grouped radio buttons with intent and size variants |
+| **Switch** | Toggle switch with checked/unchecked slot content |
+| **Slider / SliderRange** | Single-value and range sliders with keyboard control |
+| **Badge** | Inline status badge with dot, outline, and pill variants |
+| **Tag / Chip** | Dismissible tag for selections and filters |
 | **Label** | Form label with size variants |
-| **Badge** | Inline status badges |
-| **Dropdown** | Single & multi-select dropdowns |
-| **DropdownButton** | Button with a dropdown menu |
+| **Avatar** | User avatar with image, initials fallback, and status indicator |
+| **Indicator** | Numeric badge overlay for icons and avatars |
 
 ### Layout
 
 | Component | Description |
 |---|---|
-| **Card** | Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter |
-| **HorizontalCard** | Side-by-side image + content card |
-| **ImageCard** | Image-first card with overlay actions |
-| **Panel** | Collapsible panel with header |
+| **Card** | `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter` |
+| **ImageCard** | Image-first card with overlay actions and hover states |
+| **Panel** | Collapsible content panel with header |
 
 ### Data Display
 
 | Component | Description |
 |---|---|
-| **Table** | Basic table primitives (Table, TableHeader, TableBody, TableRow, etc.) |
-| **SortableTable** | Click-to-sort column headers |
-| **DataTable** | Full-featured data table with sorting, selection, pagination |
-| **List / ListItem** | Styled list component |
-| **Tree / TreeItem** | Expandable tree view |
-| **Chat** | Chat message list with sent/received styling |
-| **CodeBlock** | Syntax-highlighted code block powered by Shiki, supports 20+ languages, line numbers, and live editable mode |
+| **Table / DataTable** | Basic table primitives + full-featured sortable/selectable/paginated data table |
+| **List / ListItem** | Styled list with leading icon/avatar, title, description, and trailing action |
+| **Tree / TreeItem** | Expandable tree view with keyboard navigation |
+| **Chat** | Chat message thread with sent/received bubbles and timestamps |
+| **CodeBlock** | Shiki-powered syntax highlighting — 20+ languages, line numbers, live-editable mode |
+| **MetricCard** | KPI card with trend indicator and sparkline slot |
+| **Stat** | Compact statistic display with label, value, and change indicator |
 
 ### Navigation
 
 | Component | Description |
 |---|---|
-| **SideNav** | Collapsible sidebar with icons, sections, and multiple collapse modes |
-| **Header** | App header with nav items and action buttons |
-| **NavLink** | Semantic text link (`<a>`) with auto external-link detection, intent/size/underline variants |
-| **Tabs** | Tab bar with sliding indicator animation |
+| **Header** | App header with responsive hamburger collapse, nav items, and action buttons |
+| **SideNav** | Collapsible sidebar — expanded / icon-only / rail modes; mobile drawer with draggable pull-tab and `mobileDrawerSlot` |
+| **NavLink** | Semantic link with auto external-link detection, intent/size/underline variants |
+| **Breadcrumb** | Breadcrumb trail with truncation |
+| **Pagination** | Page number navigation with first/last/prev/next |
+| **RibbonBar** | Office-style ribbon toolbar with grouped commands |
 
 ### Disclosure
 
 | Component | Description |
 |---|---|
-| **Accordion** | Expandable accordion sections |
-| **Tabs** | TabList, TabTrigger, TabPanels, TabContent |
+| **Accordion** | Expandable sections with animated open/close |
+| **Tabs** | `TabList`, `TabTrigger`, `TabPanels`, `TabContent` with sliding indicator |
 
 ### Overlay
 
 | Component | Description |
 |---|---|
-| **Dialog** | Modal dialog with stacking support, backdrop click, ESC handling |
-| **Tooltip** | Hover tooltip with configurable placement |
-| **Alert** | Toast-style alert system with `useAlert()` hook |
+| **Dialog** | Modal dialog — centered on desktop, bottom sheet on mobile; stacking support |
+| **Drawer** | Side drawer with responsive swipe-to-dismiss |
+| **Tooltip** | Hover tooltip with configurable placement and delay |
+| **ContextMenu** | Right-click context menu with submenus |
+
+### Feedback
+
+| Component | Description |
+|---|---|
+| **Alert / useAlert()** | Toast-style alerts with `useAlert()` hook — success, error, warning, info |
+| **ProgressBar** | Determinate and indeterminate progress |
+| **Skeleton** | Loading placeholder with pulse animation |
+| **Spin** | Spinner with intent and size variants |
+| **Toast** | Standalone toast notification |
+
+### Forms
+
+| Component | Description |
+|---|---|
+| **Form / FormItem / FormSection** | Stacked & inline layouts, card/inset appearance, auto `id`/`aria-describedby` injection, bulk validation via `onValues` |
+| **Select** | Native-style accessible select with custom styling |
+
+### Charts
+
+| Component | Description |
+|---|---|
+| **BarChart** | Vertical/horizontal bar chart with tooltip and legend |
+| **LineChart** | Multi-series line chart with area fill option |
+| **PieChart** | Pie/donut chart with animated segments |
+| **ScatterChart** | Scatter plot with configurable point size and color |
 
 ### Extras
 
 | Component | Description |
 |---|---|
-| **FilmReel** | Cinematic photo gallery with lightbox |
-| **MiniPlayer** | Floating mini music player with dock, playlist, shuffle, loop |
-| **CinePlayer** | Full video player with cinema mode, playlist, keyboard shortcuts |
-| **FileExplorer** | Sci-fi themed file explorer with drag, resize, dock, multi-select, Delete key |
+| **CinePlayer** | Full-featured video player — cinema mode, playlist, keyboard shortcuts, accent color |
+| **MiniPlayer** | Floating music player — dock, playlist, shuffle, loop, accent color |
+| **FileExplorer** | File manager — drag-select, resize, dock, multi-select, `Delete` key with confirmation |
+| **FilmReel** | Cinematic photo gallery with lightbox and keyboard navigation |
+| **CommandPalette** | Spotlight-style command palette with fuzzy search |
+| **DateTimePicker** | Date and time picker with calendar grid and time sliders |
+| **Timeline** | Vertical timeline with icon, status, and time slots |
+| **Masonry** | Responsive masonry grid layout |
+| **TypewriterText** | Animated typewriter text with configurable speed and cursor |
+
+---
+
+## Forms & Accessibility
+
+`FormItem` is the connectivity layer between labels and controls. It injects `id`, `aria-describedby`, and `aria-invalid` into its first child automatically — every labelable control (`Input`, `TextBox`, `Dropdown`, `Switch`, `Checkbox`, `Slider`) receives correct WCAG label-for wiring without any manual props.
+
+```tsx
+import { Form, FormItem, Input, Dropdown, Switch, Button } from '@jacshuo/onyx';
+
+<Form layout="inline">
+  <FormItem label="Email" required>
+    <Input type="email" placeholder="you@example.com" />
+  </FormItem>
+
+  <FormItem label="Role">
+    <Dropdown options={roles} placeholder="Select a role…" />
+  </FormItem>
+
+  <FormItem label="Notifications">
+    {/* id injected directly onto Switch's native <input> */}
+    <Switch label="Receive email notifications" />
+  </FormItem>
+</Form>
+```
+
+### Validation
+
+```tsx
+<FormItem
+  label="Username"
+  required
+  onValidate={(value) =>
+    value.length >= 3
+      ? { result: true, reason: 'Username is available.' }
+      : { result: false, reason: 'Must be at least 3 characters.' }
+  }
+>
+  <Input placeholder="jane_doe" />
+</FormItem>
+```
 
 ---
 
@@ -240,55 +317,50 @@ import { CinePlayer } from '@jacshuo/onyx/Extras/CinePlayer';
 
 ### Dark Mode
 
-The library uses Tailwind's **class-based** dark mode. Add `class="dark"` to your `<html>` or any ancestor element:
+Class-based dark mode — add `.dark` to any ancestor:
 
 ```html
 <html class="dark">
-  <!-- all OnyxUI components render in dark mode -->
+  <!-- all Onyx components render in dark mode -->
 </html>
 ```
 
-### Accent Colors
-
-Many components accept an `accent` prop (any CSS color string):
-
-```tsx
-<MiniPlayer accent="#3b82f6" playlist={tracks} />
-<CinePlayer accent="#f43f5e" playlist={videos} />
-<FileExplorer accent="#10b981" files={files} />
-```
+### Override Design Tokens
 
-### CSS Custom Properties
-
-All component colors are defined as CSS custom properties in `:root` and `.dark`, making them fully overridable:
+All colors, spacing, and sizing values are CSS custom properties overridable without ejecting:
 
 ```css
-/* Override CinePlayer colors */
-:root {
-  --cp-bg: #111;
-  --cp-text: rgba(255, 255, 255, 0.8);
-  --cp-surface-hover: rgba(255, 255, 255, 0.15);
+/* Widen label column on desktop */
+@media (min-width: 768px) {
+  :root {
+    --form-label-w-md: 9rem;
+    --form-item-gap-md: 1rem;
+  }
 }
 
-/* Override MiniPlayer colors */
+/* Retheme CinePlayer */
 :root {
-  --mp-bg: rgba(255, 255, 255, 0.95);
-  --mp-text: #1e293b;
-}
-.dark {
-  --mp-bg: rgba(20, 18, 30, 0.95);
-  --mp-text: #ffffff;
+  --cp-bg: #0a0a0a;
+  --cp-surface-hover: rgba(255, 255, 255, 0.15);
 }
 
-/* Override FileExplorer colors */
-:root {
-  --fe-bg: linear-gradient(145deg, #fff, #f8f8fc);
-  --fe-text: #475569;
-}
+/* Retheme MiniPlayer */
+:root            { --mp-bg: rgba(255, 255, 255, 0.92); }
+.dark            { --mp-bg: rgba(18, 15, 28, 0.96); }
+```
+
+### Accent Colors
+
+Media-rich components accept a CSS color string for branding consistency:
+
+```tsx
+<CinePlayer  accent="#f43f5e" playlist={videos} />
+<MiniPlayer  accent="#8b5cf6" playlist={tracks} />
+<FileExplorer accent="#10b981" files={files} />
 ```
 
 <details>
-<summary><strong>Full token reference</strong></summary>
+<summary><strong>Full component token reference</strong></summary>
 
 #### CinePlayer (`--cp-*`)
 | Token | Default | Description |
@@ -333,176 +405,104 @@ All component colors are defined as CSS custom properties in `:root` and `.dark`
 
 ## Responsive Design
 
-Onyx components handle responsive behavior internally — you get adaptive layouts without writing media queries yourself.
-
-### Responsive Header
+Onyx handles responsive behavior internally — you don't write breakpoint logic.
 
-`Header` automatically collapses nav items into a hamburger drawer on mobile. No extra config needed:
+### Header — automatic hamburger collapse
 
 ```tsx
-import { Header } from '@jacshuo/onyx';
-
-// On ≥md screens: full nav bar + action buttons
-// On <md screens:  hamburger menu (nav) + overflow menu (actions) — automatic
 <Header
   brand="My App"
   mobileMenu
   navItems={[
     { label: 'Home', href: '/' },
     { label: 'Docs', href: '/docs' },
-    { label: 'Changelog', href: '/changelog' },
-  ]}
-  actions={[
-    { icon: <UserIcon />, 'aria-label': 'Sign in', onClick: () => navigate('/login') },
   ]}
+  actions={[{ icon: <SearchIcon />, 'aria-label': 'Search', onClick: openSearch }]}
 />
+// ≥md: full nav bar   <md: hamburger menu — no extra props
 ```
 
-### Responsive Sidebar
-
-`SideNav` ships with three collapse modes. Wire them to a responsive state to get a desktop-to-mobile transition with one state variable:
+### SideNav — mobile drawer with draggable pull-tab
 
 ```tsx
-import { useState } from 'react';
-import { SideNav, type SideNavCollapseMode } from '@jacshuo/onyx';
-
-function AppShell() {
-  const [mode, setMode] = useState<SideNavCollapseMode>('expanded');
-
-  return (
-    <div className="flex h-screen">
-      {/* Hidden on mobile; collapsible on desktop */}
-      <aside className="hidden md:block shrink-0">
-        <SideNav
-          items={navItems}
-          collapsible
-          collapseMode={mode}
-          onCollapseModeChange={setMode}
-        />
-      </aside>
-
-      {/* Slide-over drawer on mobile */}
-      <aside className="md:hidden">
-        <SideNav items={navItems} />
-      </aside>
-
-      <main className="flex-1 overflow-y-auto p-4 md:p-8">
-        {/* page content */}
-      </main>
-    </div>
-  );
-}
+<SideNav
+  items={navItems}
+  collapsible
+  mobileDrawerSlot={
+    <Input prefix={<SearchIcon />} placeholder="Search…" />
+  }
+/>
+// Desktop: expanded / icon-only / rail collapse modes
+// Mobile:  slide-out drawer, draggable repositionable pull-tab
 ```
 
-### Dialog — Bottom Sheet on Mobile
-
-`Dialog` automatically renders as a bottom sheet on small screens, keeping the dismiss-by-swipe pattern users expect on mobile:
+### Dialog — bottom sheet on mobile
 
 ```tsx
-import { Dialog, DialogContent, DialogHeader, DialogTitle, Button } from '@jacshuo/onyx';
-
-// On ≥md screens: centered modal dialog
-// On <md screens: slides up from bottom as a full-width sheet — no extra props
 <Dialog open={open} onOpenChange={setOpen}>
   <DialogContent size="sm">
-    <DialogHeader>
-      <DialogTitle>Confirm Action</DialogTitle>
-    </DialogHeader>
-    <p>Are you sure you want to proceed?</p>
-    <div className="flex justify-end gap-2">
+    <DialogHeader><DialogTitle>Confirm</DialogTitle></DialogHeader>
+    <p>Are you sure?</p>
+    <DialogFooter>
       <Button intent="ghost" onClick={() => setOpen(false)}>Cancel</Button>
       <Button intent="primary" onClick={() => setOpen(false)}>Confirm</Button>
-    </div>
+    </DialogFooter>
   </DialogContent>
 </Dialog>
+// ≥md: centered modal   <md: slides up from bottom
 ```
 
-### Size Variants for Density Control
-
-All components expose a `size` prop (`sm` / `md` / `lg`) for adapting density to the target context — tight mobile layouts or spacious desktop dashboards:
-
-```tsx
-import { DataTable, Button, Tabs, TabList, TabTrigger } from '@jacshuo/onyx';
-
-// Compact for mobile
-<DataTable columns={columns} data={rows} size="sm" />
-
-// Comfortable for desktop
-<DataTable columns={columns} data={rows} size="lg" />
-
-// Mix sizes to match your layout density
-<Tabs defaultValue="a">
-  <TabList size="sm">          {/* compact tabs */}
-    <TabTrigger value="a">Tab A</TabTrigger>
-    <TabTrigger value="b">Tab B</TabTrigger>
-  </TabList>
-</Tabs>
-```
-
-### Token Overrides at Breakpoints
-
-All sizing and spacing values are CSS custom properties. Override them at any breakpoint for precisely tuned responsive behavior:
+### Token overrides at breakpoints
 
 ```css
-/* Default (mobile-first) form layout */
+/* Mobile-first defaults */
 :root {
   --form-label-w-md: 5rem;
   --form-item-gap-md: 0.5rem;
-  --form-row-gap-md: 0.75rem;
 }
 
-/* Wider label column and increased spacing on desktop */
+/* Wider labels and more breathing room on desktop */
 @media (min-width: 768px) {
   :root {
-    --form-label-w-md: 7rem;
-    --form-item-gap-md: 0.75rem;
-    --form-row-gap-md: 1.25rem;
+    --form-label-w-md: 9rem;
+    --form-item-gap-md: 1rem;
   }
 }
 ```
 
 ---
 
-## Usage Examples
+## Selected Usage Examples
 
-### Button
+### Charts
 
 ```tsx
-import { Button } from '@jacshuo/onyx';
-
-<Button intent="primary" size="lg">Save</Button>
-<Button intent="danger">Delete</Button>
-<Button intent="ghost">Cancel</Button>
-<Button intent="outline">Settings</Button>
-```
-
-### Dialog
+import { BarChart, LineChart, PieChart } from '@jacshuo/onyx';
 
-```tsx
-import { useState } from 'react';
-import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogFooter, Button } from '@jacshuo/onyx';
+<BarChart
+  data={[
+    { label: 'Jan', value: 420 },
+    { label: 'Feb', value: 380 },
+    { label: 'Mar', value: 510 },
+  ]}
+/>
 
-function ConfirmDialog() {
-  const [open, setOpen] = useState(false);
+<LineChart
+  series={[
+    { name: 'Revenue', data: [120, 180, 240, 310] },
+    { name: 'Costs',   data: [80,  100, 130, 160] },
+  ]}
+  labels={['Q1', 'Q2', 'Q3', 'Q4']}
+/>
 
-  return (
-    <>
-      <Button onClick={() => setOpen(true)}>Open Dialog</Button>
-      <Dialog open={open} onOpenChange={setOpen}>
-        <DialogContent size="sm">
-          <DialogHeader>
-            <DialogTitle>Confirm Action</DialogTitle>
-          </DialogHeader>
-          <p>Are you sure you want to proceed?</p>
-          <DialogFooter>
-            <Button intent="ghost" onClick={() => setOpen(false)}>Cancel</Button>
-            <Button intent="primary" onClick={() => setOpen(false)}>Confirm</Button>
-          </DialogFooter>
-        </DialogContent>
-      </Dialog>
-    </>
-  );
-}
+<PieChart
+  segments={[
+    { label: 'Product A', value: 45 },
+    { label: 'Product B', value: 30 },
+    { label: 'Other',     value: 25 },
+  ]}
+  donut
+/>
 ```
 
 ### DataTable
@@ -510,15 +510,42 @@ function ConfirmDialog() {
 ```tsx
 import { DataTable, type ColumnDef } from '@jacshuo/onyx';
 
-type User = { id: number; name: string; email: string };
+type User = { id: number; name: string; email: string; role: string };
 
 const columns: ColumnDef<User>[] = [
-  { key: 'id', header: 'ID', width: 60 },
-  { key: 'name', header: 'Name', sortable: true },
+  { key: 'id',    header: 'ID',    width: 60 },
+  { key: 'name',  header: 'Name',  sortable: true },
   { key: 'email', header: 'Email', sortable: true },
+  { key: 'role',  header: 'Role' },
 ];
 
-<DataTable columns={columns} data={users} selectionMode="multi" pageSize={10} />
+<DataTable
+  columns={columns}
+  data={users}
+  selectionMode="multi"
+  pageSize={10}
+/>
+```
+
+### Alert (Toast)
+
+```tsx
+import { useAlert, Button } from '@jacshuo/onyx';
+
+function SaveButton() {
+  const alert = useAlert();
+
+  return (
+    <Button
+      intent="primary"
+      onClick={() =>
+        alert({ title: 'Saved!', description: 'Your changes have been saved.', variant: 'success' })
+      }
+    >
+      Save
+    </Button>
+  );
+}
 ```
 
 ### Tabs
@@ -538,22 +565,6 @@ import { Tabs, TabList, TabTrigger, TabPanels, TabContent } from '@jacshuo/onyx'
 </Tabs>
 ```
 
-### Alert (Toast)
-
-```tsx
-import { useAlert, Button } from '@jacshuo/onyx';
-
-function NotifyButton() {
-  const alert = useAlert();
-
-  return (
-    <Button onClick={() => alert({ title: 'Saved!', description: 'Your changes have been saved.', variant: 'success' })}>
-      Save
-    </Button>
-  );
-}
-```
-
 ### NavLink
 
 ```tsx
@@ -562,28 +573,20 @@ import { NavLink } from '@jacshuo/onyx';
 {/* Internal link */}
 <NavLink href="/about">About</NavLink>
 
-{/* Auto-detected external — shows icon + sets target="_blank" automatically */}
+{/* Auto-detected external — shows icon + sets target="_blank" */}
 <NavLink href="https://github.com">GitHub</NavLink>
 
-{/* Suppress external icon */}
-<NavLink href="https://example.com" external={false}>Example</NavLink>
-
 {/* Variants */}
 <NavLink href="/docs" intent="secondary" size="lg" underline="always">Docs</NavLink>
 ```
 
 ### CodeBlock
 
-> **Note:** `CodeBlock` uses [Shiki](https://shiki.style/) for syntax highlighting. Shiki is included as a direct dependency and installed automatically with Onyx — no extra steps needed.
-
 ```tsx
 import { CodeBlock } from '@jacshuo/onyx';
 
-{/* Basic syntax highlighting */}
-<CodeBlock code={`const x = 42;`} language="typescript" />
-
-{/* With line numbers */}
-<CodeBlock code={sourceCode} language="tsx" lineNumbers />
+{/* Syntax highlighting (Shiki — included, no extra install) */}
+<CodeBlock code={`const x: number = 42;`} language="typescript" lineNumbers />
 
 {/* Live editable editor */}
 function Editor() {
@@ -600,22 +603,35 @@ function Editor() {
 }
 ```
 
+### CommandPalette
+
+```tsx
+import { CommandPalette } from '@jacshuo/onyx';
+
+<CommandPalette
+  open={open}
+  onOpenChange={setOpen}
+  commands={[
+    { id: 'new-file',   label: 'New File',       icon: <FileIcon />,    action: newFile },
+    { id: 'open-prefs', label: 'Preferences',    icon: <SettingsIcon />, action: openPrefs },
+    { id: 'git-commit', label: 'Commit Changes', icon: <GitIcon />,     action: commit },
+  ]}
+/>
+```
+
 ### MiniPlayer
 
 ```tsx
 import { MiniPlayer } from '@jacshuo/onyx';
 
-const tracks = [
-  { title: 'Midnight City', artist: 'M83', src: '/audio/midnight.mp3', cover: '/covers/m83.jpg' },
-  { title: 'Intro', artist: 'The xx', src: '/audio/intro.mp3' },
-];
-
 <MiniPlayer
-  playlist={tracks}
+  playlist={[
+    { title: 'Midnight City', artist: 'M83', src: '/audio/midnight.mp3', cover: '/covers/m83.jpg' },
+    { title: 'Intro',         artist: 'The xx', src: '/audio/intro.mp3' },
+  ]}
   position="bottom-right"
   accent="#8b5cf6"
   shuffle
-  autoPlay
 />
 ```
 
@@ -624,14 +640,10 @@ const tracks = [
 ```tsx
 import { CinePlayer } from '@jacshuo/onyx';
 
-const videos = [
-  { title: 'Big Buck Bunny', src: 'https://example.com/bunny.mp4', subtitle: 'Open source' },
-];
-
 <CinePlayer
-  playlist={videos}
+  playlist={[{ title: 'Product Demo', src: '/video/demo.mp4' }]}
   accent="#f43f5e"
-  onPlayChange={(playing, index) => console.log(playing, index)}
+  onPlayChange={(playing, index) => trackAnalytics(playing, index)}
 />
 ```
 
@@ -641,7 +653,7 @@ const videos = [
 import { FileExplorer, type FileExplorerItem } from '@jacshuo/onyx';
 
 const files: FileExplorerItem[] = [
-  { name: 'src', path: '/src', type: 'directory' },
+  { name: 'src',      path: '/src',          type: 'directory' },
   { name: 'index.ts', path: '/src/index.ts', type: 'file', size: 2048, extension: '.ts' },
 ];
 
@@ -649,8 +661,8 @@ const files: FileExplorerItem[] = [
   files={files}
   accent="#10b981"
   dockable
-  onFileOpen={(f) => console.log('Open', f.name)}
-  onDelete={(items) => console.log('Delete', items)}
+  onFileOpen={(f) => openEditor(f.path)}
+  onDelete={(items) => confirmDelete(items)}
 />
 ```
 
@@ -658,49 +670,41 @@ const files: FileExplorerItem[] = [
 
 ## Keyboard Shortcuts
 
-### FileExplorer
-| Key | Action |
-|---|---|
-| `Click` | Select file |
-| `Ctrl+Click` | Multi-select |
-| `Ctrl+A` | Select all |
-| `Delete` | Delete selected (with confirmation dialog) |
-| `Escape` | Clear selection |
-| `Double-click` | Open file / Navigate directory |
-
 ### CinePlayer
 | Key | Action |
 |---|---|
 | `Space` | Play / Pause |
-| `←` / `→` | Seek ±5s |
-| `↑` / `↓` | Volume ±5% |
+| `← / →` | Seek ±5 s |
+| `↑ / ↓` | Volume ±5% |
 | `F` | Toggle fullscreen |
 | `C` | Toggle cinema mode |
 | `L` | Toggle playlist |
 | `M` | Mute / Unmute |
-| `N` | Next track |
-| `P` | Previous track |
+| `N / P` | Next / Previous track |
 | `S` | Toggle shuffle |
 
+### FileExplorer
+| Key | Action |
+|---|---|
+| `Click` | Select |
+| `Ctrl+Click` | Multi-select |
+| `Ctrl+A` | Select all |
+| `Delete` | Delete selected (with confirmation) |
+| `Escape` | Clear selection |
+| `Double-click` | Open file / navigate directory |
+
 ---
 
 ## Development
 
 ```bash
-# Install dependencies
-npm install
-
-# Start demo dev server (http://localhost:8080)
-npm run dev
-
-# Production library build (dist/)
-npm run dist
-
-# Build demo site (dist-demo/)
-npm run build:demo
-
-# Typecheck
-npm run typecheck
+npm install          # install dependencies
+npm run dev          # demo dev server → http://localhost:3001
+npm run build        # library build → dist/
+npm run build:demo   # demo site build → dist-demo/
+npm run test         # run all 519 tests (Vitest)
+npm run typecheck    # tsc --noEmit
+npm run lint         # eslint src demo
 ```
 
 ---
@@ -708,33 +712,30 @@ npm run typecheck
 ## Project Structure
 
 ```
-OnyxUI/
-├── src/
-│   ├── components/      # All React components
-│   ├── lib/utils.ts     # cn() utility (clsx + tailwind-merge)
-│   └── styles/
-│       ├── index.css    # Full CSS entry (Tailwind + all tokens + all component CSS)
-│       ├── base.css     # Tailwind + core tokens only
-│       ├── tokens.css   # @theme semantic tokens & core keyframes
-│       ├── theme.ts     # CVA variant definitions
-│       └── components/  # Per-component CSS (keyframes & design tokens)
-│           ├── CinePlayer.css
-│           ├── MiniPlayer.css
-│           ├── FileExplorer.css
-│           └── FilmReel.css
-├── demo/                # Demo site (GitHub Pages)
-│   ├── App.tsx
-│   ├── main.tsx
-│   └── pages/           # Per-component demo pages
-├── .github/workflows/
-│   ├── ci.yml           # PR/push: typecheck + build
-│   └── release.yml      # Manual: version bump → npm → GitHub Release → Pages
-├── dist/                # Library build output (ESM + CJS + DTS + CSS)
-│   ├── *.js / *.cjs     # Per-component entry points
-│   ├── chunks/          # Shared code (auto-extracted by tsup)
-│   ├── styles.css       # Full pre-compiled CSS bundle
-│   └── styles/          # Modular CSS files
-└── dist-demo/           # Demo build output
+src/
+├── components/        55+ components across 10 categories
+│   ├── Primitives/    Button, Input, Dropdown, Switch, Slider, Checkbox, Radio…
+│   ├── Layout/        Card, ImageCard, Panel
+│   ├── DataDisplay/   Table, DataTable, List, Tree, Chat, CodeBlock, MetricCard…
+│   ├── Navigation/    Header, SideNav, NavLink, Breadcrumb, RibbonBar, Pagination
+│   ├── Disclosure/    Accordion, Tabs
+│   ├── Overlay/       Dialog, Drawer, Tooltip, ContextMenu
+│   ├── Feedback/      Alert, ProgressBar, Skeleton, Spin, Toast
+│   ├── Forms/         Form, FormItem, FormSection, Select
+│   ├── Extras/        CinePlayer, MiniPlayer, FileExplorer, CommandPalette…
+│   └── Chart/         BarChart, LineChart, PieChart, ScatterChart
+├── styles/
+│   ├── tokens/core.css         @theme semantic color tokens
+│   ├── tokens/animations.css   Shared keyframes & animation utilities
+│   ├── theme/                  CVA variant functions (one file per category)
+│   ├── index.css               Full bundle entry
+│   └── tailwind.css            Consumer integration entry
+└── __tests__/                  36 test files, 519 tests
+demo/                           Interactive demo site (GitHub Pages)
+.github/
+├── workflows/ci.yml            PR checks: typecheck + build
+└── workflows/release.yml       Manual release: patch / minor / major
+dist/                           Published library (ESM + CJS + DTS + CSS)
 ```
 
 ---
@@ -742,16 +743,12 @@ OnyxUI/
 ## Contributing
 
 1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/my-feature`)
-3. Commit your changes (`git commit -m 'feat: add new component'`)
-4. Push to the branch (`git push origin feature/my-feature`)
-5. Open a Pull Request
-
-### Community & Security
+2. Create a feature branch: `git checkout -b feat/my-feature`
+3. Commit your changes following [Conventional Commits](https://www.conventionalcommits.org/)
+4. Push and open a Pull Request
 
 - Contribution guide: [CONTRIBUTING.md](./CONTRIBUTING.md)
-- Code of conduct: [CODE_OF_CONDUCT.md](./.github/CODE_OF_CONDUCT.md)
-- Security policy: [SECURITY.md](./.github/SECURITY.md)
+- Security policy: [SECURITY.md](./SECURITY.md)
 
 ---