@nqlib/nqui 0.3.2 → 0.4.0

package/docs/components/README.md

@@ -0,0 +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. **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
+
+| Dependency | Version | Notes |
+|------------|---------|-------|
+| **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 (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) |
+
+### Multiple selection (pick zero or more)
+
+| 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` |
+
+### 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 | 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 | 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 | 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 | 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 | 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 | 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 | 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-accordion.md

@@ -0,0 +1,20 @@
+# nqui Accordion
+
+> Collapsible accordion. type: single|multiple, collapsible.
+
+## Import
+
+```tsx
+import { Accordion, AccordionItem, AccordionTrigger, AccordionContent } from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<Accordion type="single" collapsible>
+  <AccordionItem value="1">
+    <AccordionTrigger>Header</AccordionTrigger>
+    <AccordionContent>Content</AccordionContent>
+  </AccordionItem>
+</Accordion>
+```

package/docs/components/nqui-alert-dialog.md

@@ -0,0 +1,31 @@
+# nqui AlertDialog
+
+> Confirmation dialog. AlertDialogTrigger, AlertDialogContent, AlertDialogHeader, AlertDialogFooter, AlertDialogTitle, AlertDialogDescription, AlertDialogAction, AlertDialogCancel.
+
+## Import
+
+```tsx
+import {
+  AlertDialog, AlertDialogTrigger, AlertDialogContent,
+  AlertDialogHeader, AlertDialogFooter, AlertDialogTitle,
+  AlertDialogDescription, AlertDialogAction, AlertDialogCancel
+} from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<AlertDialog>
+  <AlertDialogTrigger asChild><Button>Delete</Button></AlertDialogTrigger>
+  <AlertDialogContent>
+    <AlertDialogHeader>
+      <AlertDialogTitle>Confirm</AlertDialogTitle>
+      <AlertDialogDescription>Are you sure?</AlertDialogDescription>
+    </AlertDialogHeader>
+    <AlertDialogFooter>
+      <AlertDialogCancel>Cancel</AlertDialogCancel>
+      <AlertDialogAction>Confirm</AlertDialogAction>
+    </AlertDialogFooter>
+  </AlertDialogContent>
+</AlertDialog>
+```

package/docs/components/nqui-alert.md

@@ -0,0 +1,19 @@
+# nqui Alert
+
+> Alert banner. Title, description, action.
+
+## Import
+
+```tsx
+import { Alert, AlertTitle, AlertDescription, AlertAction } from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<Alert>
+  <AlertTitle>Title</AlertTitle>
+  <AlertDescription>Description</AlertDescription>
+  <AlertAction asChild><Button>Action</Button></AlertAction>
+</Alert>
+```

package/docs/components/nqui-aspect-ratio.md

@@ -0,0 +1,17 @@
+# nqui AspectRatio
+
+> Fixed aspect ratio container.
+
+## Import
+
+```tsx
+import { AspectRatio } from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<AspectRatio ratio={16/9}>
+  <img src="..." alt="..." />
+</AspectRatio>
+```

package/docs/components/nqui-avatar.md

@@ -0,0 +1,18 @@
+# nqui Avatar
+
+> User avatar. Image + fallback.
+
+## Import
+
+```tsx
+import { Avatar, AvatarImage, AvatarFallback } from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<Avatar>
+  <AvatarImage src="/url" alt="Name" />
+  <AvatarFallback>AB</AvatarFallback>
+</Avatar>
+```

package/docs/components/nqui-badge.md

@@ -0,0 +1,42 @@
+# nqui Badge
+
+> Status labels. 9 variants; ghost/link use CoreBadge.
+
+## Import
+
+```tsx
+import { Badge } from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<Badge>New</Badge>
+<Badge variant="destructive">Error</Badge>
+<Badge variant="secondary">Draft</Badge>
+```
+
+## All Variants
+
+```tsx
+<Badge variant="default" />
+<Badge variant="secondary" />
+<Badge variant="destructive" />
+<Badge variant="success" />
+<Badge variant="warning" />
+<Badge variant="info" />
+<Badge variant="outline" />
+<Badge variant="ghost" />
+<Badge variant="link" />
+```
+
+## asChild
+
+```tsx
+<Badge asChild><a href="#">Link badge</a></Badge>
+```
+
+## Notes
+
+- ghost/link route to CoreBadge (different styling).
+- Use `CoreBadge` for plain shadcn badge.

package/docs/components/nqui-breadcrumb.md

@@ -0,0 +1,24 @@
+# nqui Breadcrumb
+
+> Breadcrumb nav. List, item, link, page, separator, ellipsis.
+
+## Import
+
+```tsx
+import {
+  Breadcrumb, BreadcrumbList, BreadcrumbItem, BreadcrumbLink,
+  BreadcrumbPage, BreadcrumbSeparator, BreadcrumbEllipsis
+} from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<Breadcrumb>
+  <BreadcrumbList>
+    <BreadcrumbItem><BreadcrumbLink href="/">Home</BreadcrumbLink></BreadcrumbItem>
+    <BreadcrumbSeparator />
+    <BreadcrumbItem><BreadcrumbPage>Current</BreadcrumbPage></BreadcrumbItem>
+  </BreadcrumbList>
+</Breadcrumb>
+```

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

@@ -0,0 +1,50 @@
+# nqui ButtonGroup
+
+> **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
+
+```tsx
+import { ButtonGroup, ButtonGroupSeparator, ButtonGroupText } from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<ButtonGroup>
+  <Button variant="outline">Left</Button>
+  <ButtonGroupSeparator />
+  <Button variant="outline">Middle</Button>
+  <ButtonGroupSeparator />
+  <Button variant="outline">Right</Button>
+</ButtonGroup>
+```
+
+## With text (non-button)
+
+```tsx
+<ButtonGroup>
+  <Button variant="outline"><HomeIcon /></Button>
+  <ButtonGroupSeparator />
+  <ButtonGroupText>Text</ButtonGroupText>
+  <ButtonGroupSeparator />
+  <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-button.md

@@ -0,0 +1,56 @@
+# nqui Button
+
+> Enhanced button with 9 variants, gradients, active scale. Default import is EnhancedButton.
+
+## Import
+
+```tsx
+import { Button } from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<Button>Click</Button>
+<Button variant="destructive">Delete</Button>
+```
+
+## Variants
+
+| variant | Notes |
+|---------|-------|
+| default, destructive, secondary | Enhanced 3D |
+| success, warning, info | Semantic |
+| outline, ghost, link | Core fallback |
+| sm, default, lg, icon | size |
+
+```tsx
+<Button variant="success">Save</Button>
+<Button variant="warning">Caution</Button>
+<Button variant="info">Info</Button>
+<Button size="icon"><Icon /></Button>
+```
+
+## asChild
+
+Render as `<a>` or custom element:
+
+```tsx
+<Button asChild>
+  <a href="/page">Link</a>
+</Button>
+```
+
+## Loading
+
+```tsx
+<Button disabled>
+  <Spinner className="mr-2 size-4" />
+  Loading...
+</Button>
+```
+
+## Notes
+
+- Active state uses `scale-95`; avoid parent `transform` overrides.
+- Use `CoreButton` from `@nqlib/nqui` for base shadcn style.

package/docs/components/nqui-calendar.md

@@ -0,0 +1,46 @@
+# nqui Calendar
+
+> Date picker. Single, range, multiple. Touch drag, hover preview (enhanced).
+
+## Import
+
+```tsx
+import { Calendar } from "@nqlib/nqui"
+import type { DateRange } from "react-day-picker"
+```
+
+## Basic
+
+```tsx
+<Calendar mode="single" selected={date} onSelect={setDate} />
+```
+
+## Range
+
+```tsx
+<Calendar mode="range" selected={range} onSelect={setRange} />
+```
+
+## Multiple
+
+```tsx
+<Calendar mode="multiple" selected={dates} onSelect={setDates} />
+```
+
+## numberOfMonths
+
+```tsx
+<Calendar numberOfMonths={2} />
+```
+
+## Disabled
+
+```tsx
+<Calendar disabled={(d) => d < new Date()} />
+```
+
+## Notes
+
+- Peer: `react-day-picker` v9+.
+- Enhanced: touch drag selection, hover preview on drag.
+- Footer slot for custom footer.

package/docs/components/nqui-card.md

@@ -0,0 +1,31 @@
+# nqui Card
+
+> Container. Header, content, footer. Optional stickyHeader.
+
+## Import
+
+```tsx
+import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter } from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<Card>
+  <CardHeader>
+    <CardTitle>Title</CardTitle>
+    <CardDescription>Description</CardDescription>
+  </CardHeader>
+  <CardContent>Body</CardContent>
+  <CardFooter>Footer</CardFooter>
+</Card>
+```
+
+## Sticky Header
+
+```tsx
+<Card stickyHeader className="h-[400px]">
+  <CardHeader>...</CardHeader>
+  <CardContent>Scrollable content</CardContent>
+</Card>
+```