@nqlib/nqui 0.4.3 → 0.4.5

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>
+```

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

@@ -0,0 +1,192 @@
+# Styling & Customization
+
+nqui uses Tailwind CSS v4 with semantic CSS variables. See customization docs for theming and CSS variables.
+
+## Contents
+
+- Semantic colors
+- Built-in variants first
+- className for layout only
+- No space-x-* / space-y-*
+- Prefer size-* over w-* h-* when equal
+- Prefer truncate shorthand
+- No manual dark: color overrides
+- Use cn() for conditional classes
+- No manual z-index on overlay components (use elevation.css)
+
+---
+
+## Semantic colors
+
+**Incorrect:**
+
+```tsx
+<div className="bg-blue-500 text-white">
+  <p className="text-gray-600">Secondary text</p>
+</div>
+```
+
+**Correct:**
+
+```tsx
+<div className="bg-primary text-primary-foreground">
+  <p className="text-muted-foreground">Secondary text</p>
+</div>
+```
+
+---
+
+## No raw color values for status/state indicators
+
+For positive, negative, or status indicators, use Badge variants, semantic tokens like `text-destructive`, or define custom CSS variables — don't reach for raw Tailwind colors.
+
+**Incorrect:**
+
+```tsx
+<span className="text-emerald-600">+20.1%</span>
+<span className="text-green-500">Active</span>
+<span className="text-red-600">-3.2%</span>
+```
+
+**Correct:**
+
+```tsx
+<Badge variant="secondary">+20.1%</Badge>
+<Badge>Active</Badge>
+<span className="text-destructive">-3.2%</span>
+```
+
+---
+
+## Built-in variants first
+
+**Incorrect:**
+
+```tsx
+<Button className="border border-input bg-transparent hover:bg-accent">
+  Click me
+</Button>
+```
+
+**Correct:**
+
+```tsx
+<Button variant="outline">Click me</Button>
+```
+
+---
+
+## className for layout only
+
+Use `className` for layout (e.g. `max-w-md`, `mx-auto`, `mt-4`), **not** for overriding component colors or typography. To change colors, use semantic tokens, built-in variants, or CSS variables.
+
+**Incorrect:**
+
+```tsx
+<Card className="bg-blue-100 text-blue-900 font-bold">
+  <CardContent>Dashboard</CardContent>
+</Card>
+```
+
+**Correct:**
+
+```tsx
+<Card className="max-w-md mx-auto">
+  <CardContent>Dashboard</CardContent>
+</Card>
+```
+
+To customize a component's appearance, prefer these approaches in order:
+1. **Built-in variants** — `variant="outline"`, `variant="destructive"`, etc.
+2. **Semantic color tokens** — `bg-primary`, `text-muted-foreground`.
+3. **CSS variables** — define custom colors in the global CSS file.
+
+---
+
+## No space-x-* / space-y-*
+
+Use `gap-*` instead. `space-y-4` → `flex flex-col gap-4`. `space-x-2` → `flex gap-2`.
+
+```tsx
+<div className="flex flex-col gap-4">
+  <Input />
+  <Input />
+  <Button>Submit</Button>
+</div>
+```
+
+---
+
+## Prefer size-* over w-* h-* when equal
+
+`size-10` not `w-10 h-10`. Applies to icons, avatars, skeletons, etc.
+
+---
+
+## Prefer truncate shorthand
+
+`truncate` not `overflow-hidden text-ellipsis whitespace-nowrap`.
+
+---
+
+## No manual dark: color overrides
+
+Use semantic tokens — they handle light/dark via CSS variables. `bg-background text-foreground` not `bg-white dark:bg-gray-950`.
+
+---
+
+## Use cn() for conditional classes
+
+Use the `cn()` utility from nqui for conditional or merged class names. Don't write manual ternaries in className strings.
+
+**Incorrect:**
+
+```tsx
+<div className={`flex items-center ${isActive ? "bg-primary text-primary-foreground" : "bg-muted"}`}>
+```
+
+**Correct:**
+
+```tsx
+import { cn } from "@/lib/utils"
+
+<div className={cn("flex items-center", isActive ? "bg-primary text-primary-foreground" : "bg-muted")}>
+```
+
+---
+
+## No manual z-index on overlay components (use elevation.css)
+
+`Dialog`, `Sheet`, `Drawer`, `AlertDialog`, `DropdownMenu`, `Popover`, `Tooltip`, `HoverCard` handle their own stacking. Use the centralized z-index system from `elevation.css`.
+
+**Incorrect:**
+
+```tsx
+<div className="z-50">
+<Dialog>...</Dialog>
+</div>
+```
+
+**Correct:**
+
+```tsx
+import { cn } from "@/lib/utils"
+
+<div className={cn("z-[var(--z-modal)]")}>
+  <Dialog>...</Dialog>
+</div>
+```
+
+Reference: [elevation.css](../src/styles/elevation.css)
+
+| Variable | Value | Use Case |
+|----------|-------|----------|
+| `--z-base` | 0 | Base layer |
+| `--z-content` | 10 | Standard content |
+| `--z-sticky-content` | 15 | Sticky content within containers |
+| `--z-sticky-page` | 20 | Page-level sticky elements |
+| `--z-floating` | 30 | Floating panels, sidebars |
+| `--z-modal-backdrop` | 40 | Modal backdrops |
+| `--z-modal` | 50 | Modal content |
+| `--z-popover` | 60 | Dropdowns, select menus |
+| `--z-tooltip` | 70 | Tooltips |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nqlib/nqui",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "description": "A React component library with enhanced UI components and developer tools",
   "type": "module",
   "main": "./dist/nqui.cjs.js",
@@ -47,6 +47,11 @@
       "require": "./dist/styles.css",
       "default": "./dist/styles.css"
     },
+    "./debug": {
+      "types": "./dist/entries/debug.d.ts",
+      "import": "./dist/debug.es.js",
+      "require": "./dist/debug.cjs.js"
+    },
     "./debug.css": "./dist/nqui.css"
   },
   "files": [
@@ -65,7 +70,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/nqlib/nqui.git"
+    "url": "git+https://github.com/nqlib/nqui.git"
   },
   "keywords": [
     "ui",
@@ -103,18 +108,21 @@
     "build-storybook": "storybook build",
     "test-storybook": "test-storybook",
     "test-storybook:ci": "test-storybook --ci",
-    "test-storybook:coverage": "test-storybook --coverage"
+    "test-storybook:coverage": "test-storybook --coverage",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "nqui:init": "npx @nqlib/nqui install-peers && npx @nqlib/nqui init-cursor && npx @nqlib/nqui init-skills && npx @nqlib/nqui init-css --sidebar --force"
   },
   "bin": {
-    "nqui": "./scripts/cli.js",
-    "nqui-init-css": "./scripts/init-css.js",
-    "nqui-init-cursor": "./scripts/init-cursor.js",
-    "nqui-install-peers": "./scripts/install-peers.js",
-    "nqui-init-debug": "./scripts/init-debug-css.js",
-    "nqui-setup": "./scripts/post-install.js"
+    "nqui": "scripts/cli.js",
+    "nqui-init-css": "scripts/init-css.js",
+    "nqui-init-cursor": "scripts/init-cursor.js",
+    "nqui-init-skills": "scripts/download-skills.js",
+    "nqui-install-peers": "scripts/install-peers.js",
+    "nqui-init-debug": "scripts/init-debug-css.js",
+    "nqui-setup": "scripts/post-install.js"
   },
   "dependencies": {
-    "@nqlib/nqcode": "workspace:*",
     "@codesandbox/sandpack-react": "^2.20.0",
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/modifiers": "^9.0.0",
@@ -123,7 +131,6 @@
     "@fontsource-variable/inter": "^5.2.8",
     "@hugeicons/core-free-icons": "^3.1.1",
     "@hugeicons/react": "^1.1.4",
-    "@nqlib/nqappbuilder": "workspace:*",
     "@radix-ui/react-avatar": "^1.1.11",
     "@radix-ui/react-checkbox": "^1.3.3",
     "@radix-ui/react-collapsible": "^1.1.12",
@@ -240,6 +247,8 @@
     "@storybook/react-vite": "^10.1.11",
     "@storybook/test-runner": "^0.24.2",
     "@storybook/testing-library": "^0.2.2",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.1.0",
     "@types/lodash.throttle": "^4.1.9",
     "@types/node": "^24.10.1",
     "@types/react": "^19.0.0",
@@ -255,6 +264,8 @@
     "storybook": "^10.1.11",
     "typescript": "~5.9.3",
     "typescript-eslint": "^8.46.4",
-    "vite": "^7.2.4"
+    "vite": "^7.2.4",
+    "vitest": "^3.1.4",
+    "jsdom": "^26.1.0"
   }
 }

package/scripts/build-styles.js

@@ -19,6 +19,7 @@ const projectRoot = resolve(__dirname, '..');
 const indexCssPath = join(projectRoot, 'src', 'index.css');
 const colorsCssPath = join(projectRoot, 'src', 'styles', 'colors.css');
 const elevationCssPath = join(projectRoot, 'src', 'styles', 'elevation.css');
+const hitAreaCssPath = join(projectRoot, 'src', 'styles', 'hit-area.css');
 const outputPath = join(projectRoot, 'dist', 'styles.css');
 
 function extractStandaloneCSS() {
@@ -30,6 +31,11 @@ function extractStandaloneCSS() {
     throw new Error(`Colors CSS file not found: ${colorsCssPath}`);
   }
 
+  let hitAreaCss = '';
+  if (existsSync(hitAreaCssPath)) {
+    hitAreaCss = readFileSync(hitAreaCssPath, 'utf-8').trimEnd();
+  }
+
   let indexCss = readFileSync(indexCssPath, 'utf-8');
   let colorsCss = readFileSync(colorsCssPath, 'utf-8');
   let elevationCss = '';
@@ -110,14 +116,23 @@ function extractStandaloneCSS() {
     .replace(/@import\s+["']@fontsource-variable\/inter["'];?\s*\n/g, '')
     .replace(/@import\s+["']\.\/styles\/colors\.css["'];?\s*\n/g, '')
     .replace(/@import\s+["']\.\/styles\/elevation\.css["'];?\s*\n/g, '')
+    .replace(/@import\s+["']\.\/styles\/hit-area\.css["'];?\s*\n/g, '')
     .replace(/\/\*\s*Import enhanced color system\s*\*\//g, '')
     .replace(/\/\*\s*Import elevation system\s*\*\//g, '')
+    .replace(/\/\*\s*Hit-area utilities \(expanded pointer targets\)\s*\*\/\s*\n/g, '')
     // Remove @source inline() directives (already extracted above) - must match multiline
     .replace(/\/\*[^*]*\*+(?:[^/*][^*]*\*+)*\/\s*@source\s+inline\([\s\S]*?\)\s*;/g, '')
     // Remove other @source directives (non-inline ones)
     .replace(/@source\s+(?!inline\()[^;]+;?\s*\n/g, '')
     .replace(/@custom-variant\s+[^;]+;?\s*\n/g, '');
 
+  if (hitAreaCss) {
+    indexCss = indexCss.replace(
+      /@theme inline\s*\{/,
+      `/* Hit-area — https://bazza.dev/craft/2026/hit-area */\n${hitAreaCss}\n\n@theme inline {`
+    );
+  }
+
   // Extract :root and .dark blocks from index.css
   const indexRootMatch = indexCss.match(/:root\s*\{([^}]+(?:\{[^}]*\}[^}]*)*)\}/s);
   const indexDarkMatch = indexCss.match(/\.dark\s*\{([^}]+(?:\{[^}]*\}[^}]*)*)\}/s);
@@ -232,6 +247,7 @@ function extractStandaloneCSS() {
  * - Light and dark mode support
  * - Base layer styles
  * - Utility animations
+ * - Hit-area @utility blocks (inlined from src/styles/hit-area.css)
  * - @source inline() directives for zero-config Tailwind utility generation
  *
  * Generated by: npm run build:lib

package/scripts/cli.js

@@ -20,6 +20,7 @@ const subcommand = process.argv[2];
 
 const routes = {
   'init-cursor': './init-cursor.js',
+  'init-skills': './download-skills.js',
   'install-peers': './install-peers.js',
   'init-debug': './init-debug-css.js',
   'init-debug-css': './init-debug-css.js',