@nqlib/nqui 0.4.0 → 0.4.2

package/docs/nqui-skills/design-system.md

@@ -0,0 +1,130 @@
+---
+name: nqui-design-system
+description: Design system conventions for nqui component library. Use when creating or modifying nqui UI components to ensure sizing, spacing, and styling consistency.
+---
+
+# nqui Design System
+
+Guidelines for AI agents implementing or modifying nqui components. Follow these rules to maintain visual consistency.
+
+## Control Size Scale
+
+All interactive controls (buttons, toggles, inputs, selects) use a unified scale:
+
+| Size     | Height | Min Width | Use Case                          |
+|----------|--------|-----------|-----------------------------------|
+| `sm`     | h-6 (24px) | min-w-6 | Compact UIs, dense tables, toolbars |
+| `default`| h-7 (28px) | min-w-7 | Standard forms, primary actions       |
+| `lg`     | h-8 (32px) | min-w-8 | Emphasis, secondary actions         |
+
+### Semantic Rule
+
+`size="sm"` on Button MUST produce the same height as `size="sm"` on ToggleGroupItem, SegmentedControlItem, SelectTrigger, etc. Never introduce component-specific scales.
+
+## Layout Heights
+
+| Element | Height | Use Case |
+|---------|--------|----------|
+| Header | h-12 (48px) | Page header, app bar, sticky nav |
+| Sidebar header | h-12 (48px) | Sidebar section title bar |
+
+Fits 4px/8px grid. Default button (h-7) in 48px header leaves 10px top/bottom; h-8 leaves 8px. Use px-4, gap-2 or gap-4 for horizontal spacing.
+
+## Component Size Mapping
+
+| Component | sm | default | lg |
+|-----------|-----|---------|-----|
+| Button | h-6 min-w-6 px-2 text-xs | h-7 min-w-7 px-3 | h-8 min-w-8 px-4 |
+| Button (icon) | — | h-7 w-7 p-0 | — |
+| Toggle | h-6 min-w-6 px-1.5 | h-7 min-w-7 px-2 | h-8 min-w-8 px-2 |
+| ToggleGroupItem | (uses Toggle) | | |
+| SelectTrigger | h-6 | h-7 | — |
+| Input | — | h-7 px-3 py-1.5 text-sm | — |
+| InputGroup | — | h-7 | — |
+
+## Border Radius & Nested Radius
+
+| Token | Formula | Use Case |
+|-------|---------|----------|
+| --radius-sm | calc(--radius - 4px) | Compact controls, kbd |
+| --radius-md | calc(--radius - 2px) | Default (Button, Input, Card) |
+| --radius-lg | var(--radius) | Large surfaces |
+| --radius-xl | calc(--radius + 4px) | Modals, sheets |
+
+**Nested radius formula:** `R_inner = R_outer - offset`. When a smaller element sits inside a larger one with padding, use concentric radius so corners align.
+
+```
+/* Inner card with p-3 (12px) inset inside radius-lg card */
+border-radius: calc(var(--radius-lg) - var(--spacing-3));
+```
+
+- **Standalone** components (Button, Input) use radius tokens directly.
+- **Nested** elements (Card inside Card, panel in modal) use `calc(outer - offset)`.
+- Clamp to avoid negatives: `max(0px, calc(...))` when offset ≥ outer.
+
+## Typography
+
+| Size | Class | Use Case |
+|------|-------|----------|
+| sm | `text-xs` or `text-[0.625rem]` | Compact controls, labels |
+| default | `text-sm` | Body, inputs, buttons |
+| base | `text-base` | Section titles, headings |
+
+Font: `--font-sans` (Inter Variable). Leading: `leading-normal` or `text-xs/relaxed`.
+
+## When Adding a New Component
+
+1. **Use the scale** – If the component has a `size` prop, map `sm`→h-6, `default`→h-7, `lg`→h-8.
+2. **Match padding** – Text controls: px-2–3, py-1.5. Icon-only: p-0 with explicit size.
+3. **Text size** – sm: `text-xs` or `text-[0.625rem]`, default: `text-sm`, lg: `text-sm`.
+4. **Border radius** – Use `rounded-md` (default) or `rounded-[min(var(--radius-md),8px)]` for sm. For nested layouts, use `calc(outer - offset)`.
+
+## Grouped Controls (ButtonGroup, ToggleGroup)
+
+- **Shared border** – Container: `rounded-md border border-input overflow-hidden`
+- **Child borders** – Items: `border-0` (container provides the border)
+- **Dividers** – ToggleGroup: item borders (`border-foreground/20`) between items. Or `ToggleGroupSeparator` when `separator={false}`.
+- **Corners** – First item: rounded-l (or rounded-t vertical), last: rounded-r (or rounded-b)
+
+## Toggle & ToggleGroup Visual Treatment (Visibility on Any Background)
+
+Toggles and ToggleGroup items must remain visible on card, sidebar, and varied backgrounds:
+
+| State | Default/Outline | Segmented (single select) |
+|-------|-----------------|---------------------------|
+| **Off** | `border border-input/60` (or `border-input`), `shadow-sm`, `bg-background/50` (or transparent) | Transparent |
+| **On** | `bg-secondary` + `nqui-button-gradient` + `nqui-button-shadow` (secondary-like layering) | `bg-primary` + gradient + shadow |
+| **Active (pressed)** | `active:shadow-[inset_0_3px_5px_rgba(0,0,0,0.125)]` | Same |
+
+Never use flat `bg-muted` only for selected state; always add gradient + shadow for depth and visibility.
+
+## Toolbar & In-Context Design
+
+**Rule:** Show controls in realistic app context, not isolated. Reference: `packages/nqui/src/pages/ComponentShowcase.tsx` (Toggle & ToggleGroup section).
+
+| Context | Layout | Example |
+|---------|--------|---------|
+| Document editor | Toolbar above content area, `bg-muted/30` container, `Separator` between control groups | Bold/Italic/Underline \| Align Left/Center/Right |
+| Chart/settings panel | Label + inline controls, `rounded-lg border bg-muted/30 p-3` | Y-axis: Linear/Log; Size: S/M/L |
+| Standalone | Inline with related UI, not floating alone | Pin, Mute, single Toggle |
+
+## Customization
+
+- End users override via `className` or `size` when supported.
+- Do NOT hardcode heights in consumer code when the component supports `size`.
+- Prefer semantic sizes over pixel values in component defaults.
+
+## Files to Check for Consistency
+
+- `packages/nqui/src/components/ui/button.tsx`
+- `packages/nqui/src/components/ui/toggle.tsx`
+- `packages/nqui/src/components/ui/toggle-group.tsx`
+- `packages/nqui/src/components/ui/input.tsx`
+- `packages/nqui/src/components/ui/select.tsx`
+- `packages/nqui/src/components/custom/enhanced-button.tsx`
+
+## Anti-Patterns
+
+- **Different heights for same size** – Button h-10 while Toggle h-7 = inconsistent.
+- **Component-specific scales** – Do not add `xs` or `xl` without updating the design system doc.
+- **Overriding in showcase** – If showcase needs `className="h-9"` to look right, the component default is wrong.

package/docs/nqui-skills/rules/composition.md

@@ -0,0 +1,183 @@
+# Component Composition
+
+Best practices for composing nqui components.
+
+## Contents
+
+- Items always inside their Group component
+- Callouts use Alert
+- Empty states use Empty component
+- Toast notifications use sonner
+- Choosing between overlay components
+- Dialog, Sheet, and Drawer always need a Title
+- Card structure
+- TabsTrigger must be inside TabsList
+- Avatar always needs AvatarFallback
+- Use Separator instead of raw hr or border divs
+- Use Skeleton for loading placeholders
+- Use Badge instead of custom styled spans
+
+---
+
+## Items always inside their Group component
+
+Never render items directly inside the content container.
+
+**Incorrect:**
+
+```tsx
+<SelectContent>
+  <SelectItem value="apple">Apple</SelectItem>
+  <SelectItem value="banana">Banana</SelectItem>
+</SelectContent>
+```
+
+**Correct:**
+
+```tsx
+<SelectContent>
+  <SelectGroup>
+    <SelectItem value="apple">Apple</SelectItem>
+    <SelectItem value="banana">Banana</SelectItem>
+  </SelectGroup>
+</SelectContent>
+```
+
+This applies to all group-based components:
+
+| Item | Group |
+|------|-------|
+| `SelectItem`, `SelectLabel` | `SelectGroup` |
+| `DropdownMenuItem`, `DropdownMenuLabel`, `DropdownMenuSub` | `DropdownMenuGroup` |
+| `MenubarItem` | `MenubarGroup` |
+| `ContextMenuItem` | `ContextMenuGroup` |
+| `CommandItem` | `CommandGroup` |
+
+---
+
+## Callouts use Alert
+
+```tsx
+<Alert>
+  <AlertTitle>Warning</AlertTitle>
+  <AlertDescription>Something needs attention.</AlertDescription>
+</Alert>
+```
+
+---
+
+## Empty states use Empty component
+
+```tsx
+<Empty>
+  <EmptyHeader>
+    <EmptyMedia variant="icon"><FolderIcon /></EmptyMedia>
+    <EmptyTitle>No projects yet</EmptyTitle>
+    <EmptyDescription>Get started by creating a new project.</EmptyDescription>
+  </EmptyHeader>
+  <EmptyContent>
+    <Button>Create Project</Button>
+  </EmptyContent>
+</Empty>
+```
+
+---
+
+## Toast notifications use sonner
+
+```tsx
+import { toast } from "sonner"
+
+toast.success("Changes saved.")
+toast.error("Something went wrong.")
+toast("File deleted.", {
+  action: { label: "Undo", onClick: () => undoDelete() },
+})
+```
+
+---
+
+## Choosing between overlay components
+
+| Use case | Component |
+|----------|-----------|
+| Focused task that requires input | `Dialog` |
+| Destructive action confirmation | `AlertDialog` |
+| Side panel with details or filters | `Sheet` |
+| Mobile-first bottom panel | `Drawer` |
+| Quick info on hover | `HoverCard` |
+| Small contextual content on click | `Popover` |
+
+---
+
+## Dialog, Sheet, and Drawer always need a Title
+
+`DialogTitle`, `SheetTitle`, `DrawerTitle` are required for accessibility. Use `className="sr-only"` if visually hidden.
+
+```tsx
+<DialogContent>
+  <DialogHeader>
+    <DialogTitle>Edit Profile</DialogTitle>
+    <DialogDescription>Update your profile.</DialogDescription>
+  </DialogHeader>
+  ...
+</DialogContent>
+```
+
+---
+
+## Card structure
+
+Use full composition — don't dump everything into `CardContent`:
+
+```tsx
+<Card>
+  <CardHeader>
+    <CardTitle>Team Members</CardTitle>
+    <CardDescription>Manage your team.</CardDescription>
+  </CardHeader>
+  <CardContent>...</CardContent>
+  <CardFooter>
+    <Button>Invite</Button>
+  </CardFooter>
+</Card>
+```
+
+---
+
+## TabsTrigger must be inside TabsList
+
+Never render `TabsTrigger` directly inside `Tabs` — always wrap in `TabsList`:
+
+```tsx
+<Tabs defaultValue="account">
+  <TabsList>
+    <TabsTrigger value="account">Account</TabsTrigger>
+    <TabsTrigger value="password">Password</TabsTrigger>
+  </TabsList>
+  <TabsContent value="account">...</TabsContent>
+</Tabs>
+```
+
+---
+
+## Avatar always needs AvatarFallback
+
+Always include `AvatarFallback` for when the image fails to load:
+
+```tsx
+<Avatar>
+  <AvatarImage src="/avatar.png" alt="User" />
+  <AvatarFallback>JD</AvatarFallback>
+</Avatar>
+```
+
+---
+
+## Use existing components instead of custom markup
+
+| Instead of | Use |
+|------------|-----|
+| `<hr>` or `<div className="border-t">` | `<Separator />` |
+| `<div className="animate-pulse">` with styled divs | `<Skeleton className="h-4 w-3/4" />` |
+| `<span className="rounded-full bg-green-100 ...">` | `<Badge variant="secondary">` |

package/docs/nqui-skills/rules/forms.md

@@ -0,0 +1,190 @@
+# Forms & Inputs
+
+nqui provides a comprehensive form system using FieldGroup, Field, InputGroup, and ToggleGroup components.
+
+## Contents
+
+- Forms use FieldGroup + Field
+- InputGroup requires InputGroupInput/InputGroupTextarea
+- Buttons inside inputs use InputGroup + InputGroupAddon
+- Option sets (2–7 choices) use ToggleGroup
+- FieldSet + FieldLegend for grouping related fields
+- Field validation and disabled states
+
+---
+
+## Forms use FieldGroup + Field
+
+Always use `FieldGroup` + `Field` — never raw `div` with `space-y-*`:
+
+```tsx
+<FieldGroup>
+  <Field>
+    <FieldLabel htmlFor="email">Email</FieldLabel>
+    <Input id="email" type="email" />
+  </Field>
+  <Field>
+    <FieldLabel htmlFor="password">Password</FieldLabel>
+    <Input id="password" type="password" />
+  </Field>
+</FieldGroup>
+```
+
+Use `Field orientation="horizontal"` for settings pages. Use `FieldLabel className="sr-only"` for visually hidden labels.
+
+**Choosing form controls:**
+
+- Simple text input → `Input`
+- Dropdown with predefined options → `Select`
+- Searchable dropdown → `Combobox`
+- Boolean toggle → `Switch` (for settings) or `Checkbox` (for forms)
+- Single choice from few options → `RadioGroup`
+- Toggle between 2–5 options → `ToggleGroup` + `ToggleGroupItem`
+- Multi-line text → `Textarea`
+
+---
+
+## InputGroup requires InputGroupInput/InputGroupTextarea
+
+Never use raw `Input` or `Textarea` inside an `InputGroup`.
+
+**Incorrect:**
+
+```tsx
+<InputGroup>
+  <Input placeholder="Search..." />
+</InputGroup>
+```
+
+**Correct:**
+
+```tsx
+import { InputGroup, InputGroupInput } from "@nqlib/nqui"
+
+<InputGroup>
+  <InputGroupInput placeholder="Search..." />
+</InputGroup>
+```
+
+---
+
+## Buttons inside inputs use InputGroup + InputGroupAddon
+
+Never place a `Button` directly inside or adjacent to an `Input` with custom positioning.
+
+**Incorrect:**
+
+```tsx
+<div className="relative">
+  <Input placeholder="Search..." className="pr-10" />
+  <Button className="absolute right-0 top-0" size="icon">
+    <SearchIcon />
+  </Button>
+</div>
+```
+
+**Correct:**
+
+```tsx
+import { InputGroup, InputGroupInput, InputGroupAddon, Button } from "@nqlib/nqui"
+
+<InputGroup>
+  <InputGroupInput placeholder="Search..." />
+  <InputGroupAddon>
+    <Button size="icon">
+      <SearchIcon data-icon="inline-start" />
+    </Button>
+  </InputGroupAddon>
+</InputGroup>
+```
+
+---
+
+## Option sets (2–7 choices) use ToggleGroup
+
+Don't manually loop `Button` components with active state.
+
+**Incorrect:**
+
+```tsx
+const [selected, setSelected] = useState("daily")
+
+<div className="flex gap-2">
+  {["daily", "weekly", "monthly"].map((option) => (
+    <Button
+      key={option}
+      variant={selected === option ? "default" : "outline"}
+      onClick={() => setSelected(option)}
+    >
+      {option}
+    </Button>
+  ))}
+</div>
+```
+
+**Correct:**
+
+```tsx
+import { ToggleGroup, ToggleGroupItem } from "@nqlib/nqui"
+
+<ToggleGroup spacing={2}>
+  <ToggleGroupItem value="daily">Daily</ToggleGroupItem>
+  <ToggleGroupItem value="weekly">Weekly</ToggleGroupItem>
+  <ToggleGroupItem value="monthly">Monthly</ToggleGroupItem>
+</ToggleGroup>
+```
+
+Combine with `Field` for labelled toggle groups:
+
+```tsx
+<Field orientation="horizontal">
+  <FieldTitle id="theme-label">Theme</FieldTitle>
+  <ToggleGroup aria-labelledby="theme-label" spacing={2}>
+    <ToggleGroupItem value="light">Light</ToggleGroup<ToggleGroupItem valueItem>
+    ="dark">Dark</ToggleGroupItem>
+    <ToggleGroupItem value="system">System</ToggleGroupItem>
+  </ToggleGroup>
+</Field>
+```
+
+---
+
+## FieldSet + FieldLegend for grouping related fields
+
+Use `FieldSet` + `FieldLegend` for related checkboxes, radios, or switches — not `div` with a heading:
+
+```tsx
+<FieldSet>
+  <FieldLegend variant="label">Preferences</FieldLegend>
+  <FieldDescription>Select all that apply.</FieldDescription>
+  <FieldGroup className="gap-3">
+    <Field orientation="horizontal">
+      <Checkbox id="dark" />
+      <FieldLabel htmlFor="dark" className="font-normal">Dark mode</FieldLabel>
+    </Field>
+  </FieldGroup>
+</FieldSet>
+```
+
+---
+
+## Field validation and disabled states
+
+Both attributes are needed — `data-invalid`/`data-disabled` styles the field (label, description), while `aria-invalid`/`disabled` styles the control.
+
+```tsx
+// Invalid.
+<Field data-invalid>
+  <FieldLabel htmlFor="email">Email</FieldLabel>
+  <Input id="email" aria-invalid />
+  <FieldDescription>Invalid email address.</FieldDescription>
+</Field>
+
+// Disabled.
+<Field data-disabled>
+  <FieldLabel htmlFor="email">Email</FieldLabel>
+  <Input id="email" disabled />
+</Field>
+```
+
+Works for all controls: `Input`, `Textarea`, `Select`, `Checkbox`, `RadioGroupItem`, `Switch`, `Slider`.

package/docs/nqui-skills/rules/icons.md

@@ -0,0 +1,158 @@
+# Icons
+
+nqui uses Hugeicons as its icon library. This document covers how to use icons correctly in nqui components.
+
+**Always use Hugeicons** for icons in nqui components. Import from `@hugeicons/react` or `@hugeicons/core-free-icons`.
+
+---
+
+## Icons in Button use data-icon attribute
+
+Add `data-icon="inline-start"` (prefix) or `data-icon="inline-end"` (suffix) to the icon. No sizing classes on the icon.
+
+**Incorrect:**
+
+```tsx
+<Button>
+  <SearchIcon className="mr-2 size-4" />
+  Search
+</Button>
+```
+
+**Correct:**
+
+```tsx
+import { SearchIcon } from "@hugeicons/react"
+
+<Button>
+  <SearchIcon data-icon="inline-start" />
+  Search
+</Button>
+
+<Button>
+  Next
+  <ArrowRightIcon data-icon="inline-end"/>
+</Button>
+```
+
+---
+
+## No sizing classes on icons inside components
+
+Components handle icon sizing via CSS. Don't add `size-4`, `w-4 h-4`, or other sizing classes to icons inside `Button`, `DropdownMenuItem`, `Alert`, `Sidebar*`, or other nqui components. Unless the user explicitly asks for custom icon sizes.
+
+**Incorrect:**
+
+```tsx
+<Button>
+  <SearchIcon className="size-4" data-icon="inline-start" />
+  Search
+</Button>
+
+<DropdownMenuItem>
+  <SettingsIcon className="mr-2 size-4" />
+  Settings
+</DropdownMenuItem>
+```
+
+**Correct:**
+
+```tsx
+<Button>
+  <SearchIcon data-icon="inline-start" />
+  Search
+</Button>
+
+<DropdownMenuItem>
+  <SettingsIcon />
+  Settings
+</DropdownMenuItem>
+```
+
+---
+
+## Importing Hugeicons
+
+### Using @hugeicons/react (recommended for React)
+
+```tsx
+import { SearchIcon, SettingsIcon, ArrowRightIcon } from "@hugeicons/react"
+```
+
+### Using @hugeicons/core-free-icons
+
+For tree-shaking individual icons:
+
+```tsx
+import { SearchIcon } from "@hugeicons/core-free-icons"
+```
+
+---
+
+## Icon Usage Patterns
+
+### Icon with label
+
+```tsx
+<Button>
+  <SettingsIcon data-icon="inline-start" />
+  Settings
+</Button>
+```
+
+### Icon only button
+
+```tsx
+<Button size="icon">
+  <SearchIcon />
+</Button>
+```
+
+### Icon in menu items
+
+```tsx
+<DropdownMenuItem>
+  <SettingsIcon />
+  Settings
+</DropdownMenuItem>
+
+<DropdownMenuItem>
+  <UserIcon />
+  Profile
+</DropdownMenuItem>
+```
+
+### Icon in form controls
+
+```tsx
+<InputGroup>
+  <InputGroupAddon>
+    <SearchIcon />
+  </InputGroupAddon>
+  <InputGroupInput placeholder="Search..." />
+</InputGroup>
+```
+
+---
+
+## Migrating from other icon libraries
+
+If you have existing code using other icon libraries (e.g., lucide-react), replace imports:
+
+```tsx
+// Before (lucide-react)
+import { Search, Settings } from "lucide-react"
+
+// After (Hugeicons)
+import { SearchIcon, SettingsIcon } from "@hugeicons/react"
+```
+
+Then add the `data-icon` attribute to icons used in buttons:
+
+```tsx
+// Before
+<Button><Search /> Search</Button>
+
+// After
+<Button><SearchIcon data-icon="inline-start" /> Search</Button>
+```