@nqlib/nqui 0.3.3 → 0.4.0

package/docs/components/README.md

@@ -1,119 +1,309 @@
+---
+name: nqui-components
+description: Component implementation guide for nqui. AI skill for implementing nqui components correctly. Use when building UI with @nqlib/nqui or contributing components.
+---
+
 # nqui Component Instructions
 
-Implementation guides for each component. Optimized for AI/LLM consumption.
+Implementation guides for each component. **AI Skill:** Optimized for AI/LLM consumption when implementing nqui in apps or extending the library.
 
 **Import:** `import { X } from "@nqlib/nqui"`  
 **CSS:** `@import "@nqlib/nqui/styles"` (via `npx @nqlib/nqui init-css`)
 
-## Prerequisites (must-have)
+---
+
+## Prerequisites
 
 | Dependency | Version | Notes |
 |------------|---------|-------|
-| **Tailwind CSS** | ^4.x | Required. Vite: add `@tailwindcss/vite` plugin. Next.js: use `@source` directives in CSS. |
-| **React** | 18+ | Peer dependency. |
+| **React** | 18+ or 19 | nqui supports React 18 and 19 via `^18.0.0 \|\| ^19.0.0` peer. |
+| **Tailwind CSS** | ^4.x | Required. Vite: `@tailwindcss/vite`. Next.js: `@source` directives in CSS. |
 | **tw-animate-css** | — | `@import "tw-animate-css"` in your CSS (added by init-css). |
-| **Radix UI** | — | Bundled with nqui (Dialog, Select, etc.). |
+| **Radix UI** | — | Bundled (Dialog, Select, etc.). |
+| **Hugeicons** | @hugeicons/react, @hugeicons/core-free-icons | Required for icon display in components. |
+
+**Optional peers** (per component): `react-day-picker` (Calendar), `sonner` (Toaster), `react-resizable-panels` (Resizable), `@tanstack/react-table` (DataTable). **Code display** (CodeBlock, Snippet, etc.): use `@nqlib/nqcode` with `shiki`, `@shikijs/transformers`.
+
+---
+
+## Shared Conventions (AI Implementation Rules)
+
+- **Control sizes:** `sm`=h-6, `default`=h-7, `lg`=h-8. Button, Toggle, ToggleGroup, Input, Select use this scale. See `.cursor/skills/nqui-design-system/SKILL.md`.
+- **CSS vars required:** nqui uses `--primary`, `--background`, `--foreground`, etc. Run `npx @nqlib/nqui init-css`.
+- **Enhanced vs Core:** Button, Badge, Checkbox, Select, etc. default to enhanced (3D, animations). Use `CoreButton`, `CoreBadge`, etc. for base shadcn. Separator: single component with `variant` prop (no CoreSeparator).
+- **Grouped controls:** ButtonGroup, ToggleGroup share border; ToggleGroup uses item dividers (`border-foreground/20`) or `ToggleGroupSeparator`.
+- **Toolbar context:** Always show Toggle/ToggleGroup in realistic context (document toolbar, chart settings, etc.). Reference: `src/pages/ComponentShowcase.tsx`.
+- **Style injection:** Checkbox, Rating, Combobox inject `<style>` at mount → client-only guard for SSR.
+- **OKLCH:** ColorPicker expects OKLCH strings (`oklch(0.5 0.15 240)`), not hex.
+- **SidebarProvider:** Must wrap entire layout (sidebar + content).
+- **Z-index:** Use CSS vars from `styles/elevation.css` (e.g. `z-[var(--z-modal)]`). Never hardcode `z-10`, `z-50`, etc.
+- **Keyboard:** Use `Keys`, `isMod`, `shouldIgnoreKeyboardShortcut` from `@/lib/keyboard` for custom shortcuts.
+
+---
+
+## When to Use (Selection & Action Components)
+
+Use these rules to choose the right component. **Selection** = user picks from options. **Action** = user triggers a command.
+
+### App Design Rule: Inline/Toolbar → ToggleGroup
+
+**For toolbars, headers, and inline controls:** Always use ToggleGroup (never RadioGroup). Examples: view mode (List/Grid), scale (Linear/Log), format (Bold/Italic). Use RadioGroup only for form context (settings modal, stacked preference list).
+
+**Context-first design:** Place toolbars in realistic app context (document editor with content area, chart panel with labels). Never show Toggle/ToggleGroup floating alone. Canonical implementation: `src/pages/ComponentShowcase.tsx` → Toggle & ToggleGroup section.
+
+### Single selection (pick one of N)
+
+| If... | Use |
+|-------|-----|
+| 2–4 options, inline, want primary fill on selected | **ToggleGroup** `type="single" variant="segmented"` |
+| 2–5 options, inline, neutral/muted styling | **ToggleGroup** `type="single"` |
+| 5+ options OR limited space | **Select** (dropdown) |
+| Form context, stacked or horizontal list | **RadioGroup** |
+| Need search/filter over options | **Combobox** (single) |
 
-Optional peer deps (for specific components): `react-day-picker` (Calendar), `sonner` (Toaster), `react-resizable-panels` (Resizable), `shiki` (CodeBlock), `@codesandbox/sandpack-react` (Sandbox).
+### Multiple selection (pick zero or more)
 
-## Shared Notes
+| If... | Use |
+|-------|-----|
+| 2–5 options, inline (e.g. bold/italic/underline) | **ToggleGroup** `type="multiple"` |
+| Form context, list of options | **Checkbox** (each option) |
+| Many options, need search | **Combobox** `multiSelect` |
 
-- **CSS vars required:** nqui components use `--primary`, `--background`, `--foreground`, etc. Run `npx @nqlib/nqui init-css`.
-- **Enhanced vs Core:** Button, Badge, Checkbox, Select, etc. default to enhanced (3D, animations). Use `CoreButton`, `CoreBadge`, etc. for base shadcn.
-- **Style injection:** Checkbox, Rating, Combobox inject `<style>` at mount. Use client-only guard for SSR.
-- **OKLCH:** ColorPicker uses OKLCH strings (`oklch(0.5 0.15 240)`), not hex.
-- **SidebarProvider:** Must wrap entire layout (sidebar + content), not just Sidebar.
+### Actions (trigger, not select)
+
+| If... | Use |
+|-------|-----|
+| Single action (save, submit, etc.) | **Button** |
+| Related actions side-by-side (Undo/Redo, align) | **ButtonGroup** |
+| On/off state for one thing (bold, mute) | **Toggle** |
+
+### Quick decision
+
+- **ToggleGroup segmented** → 1 selection only, 2–4 options, primary fill on selected. Example: Linear/Log scale.
+- **ToggleGroup single** → 1 selection, neutral/muted styling.
+- **ToggleGroup multiple** → Multiple selection, e.g. format toolbar.
+- **Select** → 1 selection, many options or no space for inline.
+- **ButtonGroup** → Actions, not selection. Each item does something (click = action).
+
+---
 
 ## Buttons & Actions
-| Component | File |
-|-----------|------|
-| Button | [nqui-button.md](./nqui-button.md) |
-| ButtonGroup | [nqui-button-group.md](./nqui-button-group.md) |
-| Toggle | [nqui-toggle.md](./nqui-toggle.md) |
-| ToggleGroup | [nqui-toggle-group.md](./nqui-toggle-group.md) |
-| SegmentedControl | [nqui-segmented-control.md](./nqui-segmented-control.md) |
+
+| Component | Doc | When to Use |
+|-----------|-----|-------------|
+| Button | [nqui-button.md](./nqui-button.md) | Single action (submit, cancel, icon). Not for selection. |
+| ButtonGroup | [nqui-button-group.md](./nqui-button-group.md) | Related actions side-by-side (toolbar). Each triggers an action. Not for selection. |
+| Toggle | [nqui-toggle.md](./nqui-toggle.md) | One on/off state. E.g. bold in editor. Not a group. |
+| ToggleGroup | [nqui-toggle-group.md](./nqui-toggle-group.md) | **Single** or **multiple** selection. `type="single"` = 1 of N; `type="multiple"` = 0+ of N. Use `variant="segmented"` for primary fill on selected (e.g. view mode, scale type). |
+
+---
+
+## Forms – When to Use
+
+| If... | Use |
+|-------|-----|
+| Free text, single line | **Input** |
+| Free text, multiple lines | **Textarea** |
+| Input with icon/button (search, units) | **InputGroup** |
+| Single choice, 5+ options or no space | **Select** |
+| Single choice, need search | **Combobox** (single) |
+| Single choice, form, small option set | **RadioGroup** |
+| Multiple choice, need search | **Combobox** `multiSelect` |
+| One boolean (agree, subscribe) | **Checkbox** |
+| On/off setting (dark mode, notifications) | **Switch** |
+| Numeric range (volume, opacity) | **Slider** |
+| OTP, verification code | **InputOTP** |
+| Color from swatches | **ColorPicker** |
+| Hue/saturation in color picker | **ColorSlider** |
+| Wrap label + error + input | **Field** |
+
+---
 
 ## Forms
-| Component | File |
-|-----------|------|
-| Input | [nqui-input.md](./nqui-input.md) |
-| InputGroup | [nqui-input-group.md](./nqui-input-group.md) |
-| Textarea | [nqui-textarea.md](./nqui-textarea.md) |
-| Select | [nqui-select.md](./nqui-select.md) |
-| NativeSelect | [nqui-native-select.md](./nqui-native-select.md) |
-| Checkbox | [nqui-checkbox.md](./nqui-checkbox.md) |
-| RadioGroup | [nqui-radio-group.md](./nqui-radio-group.md) |
-| Switch | [nqui-switch.md](./nqui-switch.md) |
-| Slider | [nqui-slider.md](./nqui-slider.md) |
-| Rating | [nqui-rating.md](./nqui-rating.md) |
-| InputOTP | [nqui-input-otp.md](./nqui-input-otp.md) |
-| Field | [nqui-field.md](./nqui-field.md) |
-| Combobox | [nqui-combobox.md](./nqui-combobox.md) |
-| ColorPicker | [nqui-color-picker.md](./nqui-color-picker.md) |
-| ColorSlider | [nqui-color-slider.md](./nqui-color-slider.md) |
-| Label | [nqui-label.md](./nqui-label.md) |
+
+| Component | Doc | When to Use |
+|-----------|-----|-------------|
+| Input | [nqui-input.md](./nqui-input.md) | Single-line text. Email, search, name. |
+| InputGroup | [nqui-input-group.md](./nqui-input-group.md) | Input + addon (icon, button, unit). |
+| Textarea | [nqui-textarea.md](./nqui-textarea.md) | Multi-line text. |
+| Select | [nqui-select.md](./nqui-select.md) | **1 selection** from 5+ options. Dropdown. Use when options don't fit inline or space is tight. |
+| NativeSelect | [nqui-native-select.md](./nqui-native-select.md) | Native `<select>` – simpler, accessible fallback. |
+| Checkbox | [nqui-checkbox.md](./nqui-checkbox.md) | **1 boolean** (agree, subscribe). Or multiple checkboxes for multi-select list. |
+| RadioGroup | [nqui-radio-group.md](./nqui-radio-group.md) | **1 selection** from options in form context. Stacked or inline. |
+| Switch | [nqui-switch.md](./nqui-switch.md) | On/off setting (not formatting). |
+| Slider | [nqui-slider.md](./nqui-slider.md) | Numeric range. |
+| Rating | [nqui-rating.md](./nqui-rating.md) | Star/score (1–5). |
+| InputOTP | [nqui-input-otp.md](./nqui-input-otp.md) | OTP/verification. |
+| Field | [nqui-field.md](./nqui-field.md) | Label + description + error wrapper. |
+| Combobox | [nqui-combobox.md](./nqui-combobox.md) | **Searchable** select. Single or `multiSelect`. Use when user types to filter. |
+| ColorPicker | [nqui-color-picker.md](./nqui-color-picker.md) | Color selection. OKLCH. |
+| ColorSlider | [nqui-color-slider.md](./nqui-color-slider.md) | Hue/saturation (used in ColorPicker). |
+| Label | [nqui-label.md](./nqui-label.md) | Form label. |
+
+---
+
+## Display – When to Use
+
+| If... | Use |
+|-------|-----|
+| Status, count, tag | **Badge** |
+| User/org image | **Avatar** |
+| Inline message (info, warn, error) | **Alert** |
+| Empty list/table | **Empty** |
+| Loading placeholder | **Skeleton** |
+| Loading spinner | **Spinner** |
+| Progress bar | **Progress** |
+| Divider, section split | **Separator** |
+| Content container | **Card** |
+| List row (avatar + title + actions) | **Item** |
+| Show keyboard shortcut | **Kbd** |
+| Activity blocks (e.g. heatmap) | **Tracker** |
+| Glass effect | **FrostedGlass** |
+
+---
 
 ## Display
-| Component | File |
-|-----------|------|
-| Badge | [nqui-badge.md](./nqui-badge.md) |
-| Avatar | [nqui-avatar.md](./nqui-avatar.md) |
-| Alert | [nqui-alert.md](./nqui-alert.md) |
-| Empty | [nqui-empty.md](./nqui-empty.md) |
-| Skeleton | [nqui-skeleton.md](./nqui-skeleton.md) |
-| Spinner | [nqui-spinner.md](./nqui-spinner.md) |
-| Progress | [nqui-progress.md](./nqui-progress.md) |
-| Separator | [nqui-separator.md](./nqui-separator.md) |
-| Card | [nqui-card.md](./nqui-card.md) |
-| Item | [nqui-item.md](./nqui-item.md) |
-| Kbd | [nqui-kbd.md](./nqui-kbd.md) |
-| Tracker | [nqui-tracker.md](./nqui-tracker.md) |
-| FrostedGlass | [nqui-frosted-glass.md](./nqui-frosted-glass.md) |
-| NquiLogo | [nqui-logo.md](./nqui-logo.md) |
+
+| Component | Doc | When to Use |
+|-----------|-----|----------|
+| Badge | [nqui-badge.md](./nqui-badge.md) | Status, count, tag. |
+| Avatar | [nqui-avatar.md](./nqui-avatar.md) | User/profile image. |
+| Alert | [nqui-alert.md](./nqui-alert.md) | Inline message (info, warning, error). |
+| Empty | [nqui-empty.md](./nqui-empty.md) | Empty state when no data. |
+| Skeleton | [nqui-skeleton.md](./nqui-skeleton.md) | Loading placeholder. |
+| Spinner | [nqui-spinner.md](./nqui-spinner.md) | Loading indicator. |
+| Progress | [nqui-progress.md](./nqui-progress.md) | Progress bar. |
+| Separator | [nqui-separator.md](./nqui-separator.md) | Divider. `variant` for fade, solid, decorative. |
+| Card | [nqui-card.md](./nqui-card.md) | Content container. |
+| Item | [nqui-item.md](./nqui-item.md) | List row: media + title + description + actions. |
+| Kbd | [nqui-kbd.md](./nqui-kbd.md) | Keyboard shortcut display. |
+| Tracker | [nqui-tracker.md](./nqui-tracker.md) | Activity blocks (heatmap). |
+| FrostedGlass | [nqui-frosted-glass.md](./nqui-frosted-glass.md) | Glass effect. |
+| NquiLogo | [nqui-logo.md](./nqui-logo.md) | Theme-aware logo. |
+
+---
+
+## Data & Tables – When to Use
+
+| If... | Use |
+|-------|-----|
+| Static table, no sort/filter | **Table** |
+| Table with sort, filter, paginate, select | **DataTable** |
+| List of items (avatar + title + actions) | **Item** |
+
+---
+
+## Data & Tables
+
+| Component | Doc | When to Use |
+|-----------|-----|-------------|
+| Table | [nqui-table.md](./nqui-table.md) | Static table. TableHeader, TableBody, TableRow, TableCell. |
+| DataTable | [nqui-data-table.md](./nqui-data-table.md) | Sort, filter, paginate, select, edit. Requires `@tanstack/react-table`. |
+| Item | [nqui-item.md](./nqui-item.md) | List row with media, title, description, actions. |
+
+---
+
+## Files & Code Display
+
+| Component | Doc | Use Case |
+|-----------|-----|----------|
+| CodeBlock | [nqui-code-block.md](./nqui-code-block.md) | From `@nqlib/nqcode`. Syntax-highlighted code, multi-file, copy. Peer: shiki. |
+| Snippet | [nqui-snippet.md](./nqui-snippet.md) | From `@nqlib/nqcode`. Tabbed code, copy. |
+
+---
+
+## Navigation – When to Use
+
+| If... | Use |
+|-------|-----|
+| Breadcrumb path | **Breadcrumb** |
+| Tabbed panels | **Tabs** |
+| Menu from trigger (avatar, ⋮) | **DropdownMenu** |
+| Right-click menu | **ContextMenu** |
+| Horizontal app menu | **Menubar** |
+| Mega nav / complex nav | **NavigationMenu** |
+| Page 1, 2, 3... | **Pagination** |
+| Search + command list | **Command** / **CommandPalette** |
+| Doc section links | **TableOfContents** |
+
+---
 
 ## Navigation & Menus
-| Component | File |
-|-----------|------|
-| Breadcrumb | [nqui-breadcrumb.md](./nqui-breadcrumb.md) |
-| Tabs | [nqui-tabs.md](./nqui-tabs.md) |
-| DropdownMenu | [nqui-dropdown-menu.md](./nqui-dropdown-menu.md) |
-| ContextMenu | [nqui-context-menu.md](./nqui-context-menu.md) |
-| Menubar | [nqui-menubar.md](./nqui-menubar.md) |
-| NavigationMenu | [nqui-navigation-menu.md](./nqui-navigation-menu.md) |
-| Pagination | [nqui-pagination.md](./nqui-pagination.md) |
-| Command | [nqui-command.md](./nqui-command.md) |
-| CommandPalette | [nqui-command-palette.md](./nqui-command-palette.md) |
-| TableOfContents | [nqui-table-of-contents.md](./nqui-table-of-contents.md) |
+
+| Component | Doc | When to Use |
+|-----------|-----|----------|
+| Breadcrumb | [nqui-breadcrumb.md](./nqui-breadcrumb.md) | Path navigation (Home > Products > Item). |
+| Tabs | [nqui-tabs.md](./nqui-tabs.md) | Switch between panels (Settings, Profile). |
+| DropdownMenu | [nqui-dropdown-menu.md](./nqui-dropdown-menu.md) | Menu from trigger click (avatar, ⋮). |
+| ContextMenu | [nqui-context-menu.md](./nqui-context-menu.md) | Right-click menu. |
+| Menubar | [nqui-menubar.md](./nqui-menubar.md) | Horizontal app menu (File, Edit). |
+| NavigationMenu | [nqui-navigation-menu.md](./nqui-navigation-menu.md) | Mega menu with sub-panels. |
+| Pagination | [nqui-pagination.md](./nqui-pagination.md) | Page 1, 2, 3... navigation. |
+| Command | [nqui-command.md](./nqui-command.md) | Searchable command list. |
+| CommandPalette | [nqui-command-palette.md](./nqui-command-palette.md) | Full Cmd+K palette. |
+| TableOfContents | [nqui-table-of-contents.md](./nqui-table-of-contents.md) | Doc section links from headings. |
+
+---
+
+## Overlays – When to Use
+
+| If... | Use |
+|-------|-----|
+| Modal, blocks page, user must respond | **Dialog** |
+| Confirm/cancel (delete, leave) | **AlertDialog** |
+| Panel from side (mobile-first) | **Sheet** |
+| Panel from bottom, mobile | **Drawer** (vaul) |
+| Floating content near trigger (picker, menu) | **Popover** |
+| Hover to show extra info | **Tooltip** (short) or **HoverCard** (rich) |
+| Non-blocking notification | **Toaster** (sonner) |
+
+---
 
 ## Overlays & Dialogs
-| Component | File |
-|-----------|------|
-| Dialog | [nqui-dialog.md](./nqui-dialog.md) |
-| AlertDialog | [nqui-alert-dialog.md](./nqui-alert-dialog.md) |
-| Drawer | [nqui-drawer.md](./nqui-drawer.md) |
-| Sheet | [nqui-sheet.md](./nqui-sheet.md) |
-| Popover | [nqui-popover.md](./nqui-popover.md) |
-| HoverCard | [nqui-hover-card.md](./nqui-hover-card.md) |
-| Tooltip | [nqui-tooltip.md](./nqui-tooltip.md) |
-| Toaster | [nqui-toaster.md](./nqui-toaster.md) |
+
+| Component | Doc | When to Use |
+|-----------|-----|-------------|
+| Dialog | [nqui-dialog.md](./nqui-dialog.md) | Modal. Blocks interaction until dismissed. |
+| AlertDialog | [nqui-alert-dialog.md](./nqui-alert-dialog.md) | Confirm/cancel. Delete, leave page. |
+| Drawer | [nqui-drawer.md](./nqui-drawer.md) | Slide from bottom. Mobile-friendly. |
+| Sheet | [nqui-sheet.md](./nqui-sheet.md) | Panel from side. |
+| Popover | [nqui-popover.md](./nqui-popover.md) | Floating content anchored to trigger. |
+| HoverCard | [nqui-hover-card.md](./nqui-hover-card.md) | Rich preview on hover. |
+| Tooltip | [nqui-tooltip.md](./nqui-tooltip.md) | Short hint on hover. |
+| Toaster | [nqui-toaster.md](./nqui-toaster.md) | Toast notifications. Requires `sonner`. |
+
+---
 
 ## Layout
-| Component | File |
-|-----------|------|
-| Accordion | [nqui-accordion.md](./nqui-accordion.md) |
-| Collapsible | [nqui-collapsible.md](./nqui-collapsible.md) |
-| ScrollArea | [nqui-scroll-area.md](./nqui-scroll-area.md) |
-| AspectRatio | [nqui-aspect-ratio.md](./nqui-aspect-ratio.md) |
-| Carousel | [nqui-carousel.md](./nqui-carousel.md) |
-| Resizable | [nqui-resizable.md](./nqui-resizable.md) |
-| Sidebar | [nqui-sidebar.md](./nqui-sidebar.md) |
-| Sortable | [nqui-sortable.md](./nqui-sortable.md) |
+
+| Component | Doc | Use Case |
+|-----------|-----|----------|
+| Accordion | [nqui-accordion.md](./nqui-accordion.md) | Collapsible sections. |
+| Collapsible | [nqui-collapsible.md](./nqui-collapsible.md) | Single collapsible. |
+| ScrollArea | [nqui-scroll-area.md](./nqui-scroll-area.md) | Custom scroll with fade mask. |
+| AspectRatio | [nqui-aspect-ratio.md](./nqui-aspect-ratio.md) | Fixed aspect container. |
+| Carousel | [nqui-carousel.md](./nqui-carousel.md) | Image/content carousel. Requires `embla-carousel-react`. |
+| Resizable | [nqui-resizable.md](./nqui-resizable.md) | Resizable panels. Requires `react-resizable-panels`. |
+| Sidebar | [nqui-sidebar.md](./nqui-sidebar.md) | App sidebar. `SidebarProvider` wraps layout. |
+| Sortable | [nqui-sortable.md](./nqui-sortable.md) | Drag-to-reorder. Import from `@nqlib/nqui/sortable`. |
+
+---
 
 ## Advanced
-| Component | File |
-|-----------|------|
-| Calendar | [nqui-calendar.md](./nqui-calendar.md) |
-| CodeBlock | [nqui-code-block.md](./nqui-code-block.md) |
-| CodeEditor | [nqui-code-editor.md](./nqui-code-editor.md) |
-| Sandbox | [nqui-sandbox.md](./nqui-sandbox.md) |
-| Snippet | [nqui-snippet.md](./nqui-snippet.md) |
+
+| Component | Doc | Use Case |
+|-----------|-----|----------|
+| Calendar | [nqui-calendar.md](./nqui-calendar.md) | Date picker. Requires `react-day-picker`, `date-fns`. Import from `@nqlib/nqui/calendar`. |
+
+---
+
+## AI Implementation Checklist
+
+1. **Choose component** – Use "When to Use" tables above. Selection vs action? Single vs multiple? Option count?
+2. **Read doc** – Open `nqui-<name>.md` for import and patterns.
+3. **Size** – Use `sm`/`default`/`lg` per design system. No custom heights.
+4. **Enhanced vs Core** – Prefer default (enhanced); use `Core*` when plain style needed.
+5. **Toolbar/context** – Place Toggle/ToggleGroup in realistic context (document toolbar, chart panel). Reference: `src/pages/ComponentShowcase.tsx`.
+6. **SSR** – Wrap style-injecting components (Checkbox, Rating, Combobox) in client boundary if SSR.
+7. **Z-index** – Use `var(--z-modal)`, `var(--z-popover)`, etc.
+8. **Keyboard** – Use `shouldIgnoreKeyboardShortcut` for global listeners.

package/docs/components/nqui-button-group.md

@@ -1,6 +1,18 @@
 # nqui ButtonGroup
 
-> Grouped buttons with separators.
+> **Related actions** side-by-side. Each item triggers an action. Not for selection.
+
+## When to Use
+
+- **Actions** (not selection) – each click does something
+- **Related** – Undo/Redo, align left/center/right (as actions)
+- **Layout:** Inline, shared border
+
+**Choose ButtonGroup when:** User triggers actions (Undo, Redo, Copy). Each button performs a command. Not for picking a mode or state.
+
+**Use ToggleGroup instead** when user is *selecting* a value (mode, scale, alignment as state). ButtonGroup = actions. ToggleGroup = selection.
+
+**Examples:** Undo | Redo, Left | Center | Right (when each applies an action), Export | Print.
 
 ## Import
 
@@ -14,18 +26,25 @@ import { ButtonGroup, ButtonGroupSeparator, ButtonGroupText } from "@nqlib/nqui"
 <ButtonGroup>
   <Button variant="outline">Left</Button>
   <ButtonGroupSeparator />
+  <Button variant="outline">Middle</Button>
+  <ButtonGroupSeparator />
   <Button variant="outline">Right</Button>
 </ButtonGroup>
 ```
 
-## ButtonGroupText
+## With text (non-button)
 
 ```tsx
 <ButtonGroup>
-  <Button variant="outline"><Icon /></Button>
+  <Button variant="outline"><HomeIcon /></Button>
   <ButtonGroupSeparator />
-  <ButtonGroupText>Label</ButtonGroupText>
+  <ButtonGroupText>Text</ButtonGroupText>
   <ButtonGroupSeparator />
-  <Button variant="outline"><Icon /></Button>
+  <Button variant="outline"><SettingsIcon /></Button>
 </ButtonGroup>
 ```
+
+## Notes
+
+- Uses Button children. Shared border, separators with fade.
+- `ButtonGroupText` for non-clickable label between buttons.

package/docs/components/nqui-checkbox.md

@@ -1,6 +1,6 @@
 # nqui Checkbox
 
-> Enhanced checkbox. Variants: square (default), round (gooey animation).
+> Enhanced checkbox. Variants: square (default), round (circular).
 
 ## Import
 
@@ -30,5 +30,5 @@ import { Checkbox } from "@nqlib/nqui"
 ## Notes
 
 - Injects `<style>` at mount. Use client-only guard for SSR.
-- Round variant uses SVG filter; requires no parent `filter` override.
+- Square and round share the same animation (pulse + checkmark scale); round has no SVG filters.
 - Use `CoreCheckbox` for plain Radix checkbox.

package/docs/components/nqui-code-block.md

@@ -1,6 +1,6 @@
 # nqui CodeBlock
 
-> Syntax-highlighted code. Multi-file tabs, copy button. Peer: shiki.
+> Syntax-highlighted code. Multi-file tabs, copy button. From `@nqlib/nqcode`.
 
 ## Import
 
@@ -8,9 +8,11 @@
 import {
   CodeBlock, CodeBlockHeader, CodeBlockFiles, CodeBlockFilename,
   CodeBlockCopyButton, CodeBlockBody, CodeBlockItem, CodeBlockContent
-} from "@nqlib/nqui"
+} from "@nqlib/nqcode"
 ```
 
+Requires: `@nqlib/nqui`, `shiki`, `@shikijs/transformers`
+
 ## Basic
 
 ```tsx
@@ -35,5 +37,5 @@ import {
 
 ## Notes
 
-- Peer: shiki. Optional for syntax highlighting.
-- CodeBlockContentServer for SSR.
+- Peer: shiki, @shikijs/transformers for syntax highlighting.
+- CodeBlockContentServer (async/RSC): `import { CodeBlockContentServer } from "@nqlib/nqcode/server"`

package/docs/components/nqui-code-editor.md

@@ -5,7 +5,7 @@
 ## Import
 
 ```tsx
-import { CodeEditor } from "@nqlib/nqui"
+import { CodeEditor } from "@nqlib/nqcode"
 ```
 
 ## Basic

package/docs/components/nqui-combobox.md

@@ -1,6 +1,14 @@
 # nqui Combobox
 
-> Autocomplete / searchable select. Multi-select chips, trigger mode, groups.
+> **Searchable** select. Single or multi-select. Use when user types to filter options.
+
+## When to Use
+
+- **Selection:** Single or multiple
+- **Key feature:** User searches/filters options by typing
+- **Options:** Many (dozens, hundreds)
+
+**Choose Combobox when:** Options are too many to scroll, or user knows the name. Type to filter. Use Select when options are few and no search needed.
 
 ## Import
 

package/docs/components/nqui-data-table.md

@@ -0,0 +1,46 @@
+# nqui DataTable
+
+> Full-featured data table: sorting, filtering, pagination, row selection, inline editing.
+
+## Import
+
+DataTable is in `packages/nqui/src/components/table/`. For app usage: `import { DataTable } from "@/components/table"`. Requires `@tanstack/react-table` peer. Not currently exported from main `@nqlib/nqui` entry.
+
+## Peer Dependency
+
+```bash
+pnpm add @tanstack/react-table
+```
+
+## Basic
+
+```tsx
+const columns: ColumnDef<User>[] = [
+  { accessorKey: "name", header: "Name" },
+  { accessorKey: "email", header: "Email" },
+]
+<DataTable columns={columns} data={users} />
+```
+
+## Props
+
+| Prop | Default | Use |
+|------|---------|-----|
+| enableSorting | true | Column header sort |
+| enableFiltering | true | Global search |
+| enablePagination | true | Page controls |
+| enableRowSelection | false | Checkboxes |
+| enableEditing | false | Inline edit |
+| pageSize | 10 | Rows per page |
+
+## Use Case
+
+- Admin panels, dashboards
+- Tabular data with sort/filter/paginate
+- When Table primitives aren't enough
+
+## Notes
+
+- DataTable lives in `components/table/`; may require path alias.
+- Uses createColumnHelper, createSelectColumn from data-table-helpers.
+- Keyboard: Arrow keys, Enter for navigation.

package/docs/components/nqui-input-group.md

@@ -1,22 +1,30 @@
 # nqui InputGroup
 
-> Input with prefix/suffix. InputGroupText, InputGroupInput, etc.
+> Input with prefix/suffix. Use InputGroupAddon + InputGroupText for addons, InputGroupInput for the control.
 
 ## Import
 
 ```tsx
-import { InputGroup, InputGroupText, Input } from "@nqlib/nqui"
+import { InputGroup, InputGroupAddon, InputGroupText, InputGroupInput } from "@nqlib/nqui"
 ```
 
 ## Basic
 
+Wrap addons in `InputGroupAddon` with `align` to control position. Use `InputGroupInput` (not `Input`) so borders and padding align correctly.
+
 ```tsx
 <InputGroup>
-  <InputGroupText>@</InputGroupText>
-  <Input placeholder="Username" />
+  <InputGroupAddon align="inline-start">
+    <InputGroupText>@</InputGroupText>
+  </InputGroupAddon>
+  <InputGroupInput placeholder="Username" />
 </InputGroup>
 <InputGroup>
-  <Input placeholder="Amount" />
-  <InputGroupText>.00</InputGroupText>
+  <InputGroupInput placeholder="Amount" />
+  <InputGroupAddon align="inline-end">
+    <InputGroupText>.00</InputGroupText>
+  </InputGroupAddon>
 </InputGroup>
 ```
+
+Padding follows design system (px-3, py-1.5) for balanced addons and inputs.

package/docs/components/nqui-radio-group.md

@@ -1,6 +1,14 @@
 # nqui RadioGroup
 
-> Radio selection. Variants: animated, sliding, bar-left, bar-right.
+> **1 selection** from options. Form context. Stacked or horizontal.
+
+## When to Use
+
+- **Selection:** Single
+- **Context:** Form (settings, preferences)
+- **Layout:** Stacked list or horizontal row
+
+**Choose RadioGroup when:** Form with single-choice question. Traditional form UX. **Do not use RadioGroup for toolbars or inline UI** — use ToggleGroup instead. Use Select for 5+ options or tight space.
 
 ## Import
 

package/docs/components/nqui-sandbox.md

@@ -8,7 +8,7 @@
 import {
   SandboxProvider, SandboxLayout, SandboxCodeEditor,
   SandboxPreview
-} from "@nqlib/nqui"
+} from "@nqlib/nqcode"
 ```
 
 ## Basic