@nqlib/nqui 0.4.3 → 0.4.4

package/docs/components/nqui-checkbox.md

@@ -11,9 +11,31 @@ import { Checkbox } from "@nqlib/nqui"
 ## Basic
 
 ```tsx
-<Checkbox checked={checked} onCheckedChange={setChecked} />
+const [checked, setChecked] = useState(false)
+
+<Checkbox checked={checked} onCheckedChange={setChecked}>Accept terms</Checkbox>
+```
+
+## With Label
+
+Checkbox automatically wraps in a label when children are provided:
+
+```tsx
+<Checkbox>Accept terms</Checkbox>
+```
+
+## Gap
+
+Control the gap between checkbox and label:
+
+```tsx
+<Checkbox gap={2}>Compact gap (8px)</Checkbox>
+<Checkbox gap={3}>Default gap (12px)</Checkbox>
+<Checkbox gap={4}>Loose gap (16px)</Checkbox>
 ```
 
+Options: `0`, `1`, `2`, `3`, `4` (maps to Tailwind gap-0 through gap-4).
+
 ## Variants
 
 ```tsx
@@ -27,8 +49,23 @@ import { Checkbox } from "@nqlib/nqui"
 <Checkbox checked="indeterminate" onCheckedChange={...} />
 ```
 
+## Hit area (expanded pointer target)
+
+nqui ships [Bazza **hit-area** utilities](https://bazza.dev/craft/2026/hit-area) in library CSS (`hit-area-*`, `hit-area-x-*`, `hit-area-debug`, etc.). They extend the clickable region with a `::before` layer without changing layout.
+
+**Enhanced checkbox:** The checkmark is drawn with `::after` on the control root so `::before` stays free for `hit-area-*` on the **same** element. Add a class when you want a larger target (e.g. padded table cells):
+
+```tsx
+<Checkbox className="hit-area-6" checked={rowSelected} onCheckedChange={...} aria-label="Select row" />
+```
+
+**Label hover pill:** `.checkbox-animated-label::before` is on the **label** wrapper only; it does not conflict with `hit-area-*` on the checkbox button.
+
+**Without hit-area:** You can still wrap the control in `<span className="relative hit-area-6">` if you prefer the expanded area on a wrapper.
+
 ## Notes
 
+- Implementation: **`packages/nqui/src/components/ui/checkbox.tsx`** (enhanced + core in one module).
 - Injects `<style>` at mount. Use client-only guard for SSR.
 - 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-color-slider.md

@@ -10,10 +10,12 @@ import { ColorSlider } from "@nqlib/nqui"
 
 ## Types
 
+Built on **`Slider`** from `ui/slider` (white thumb + shadow). For **non-controlled** demos, prefer **`defaultValue`** so the thumb stays draggable.
+
 ```tsx
-<ColorSlider sliderType="hue" value={[240]} onValueChange={setVal} min={0} max={360} />
-<ColorSlider sliderType="saturation" value={[0.5]} onValueChange={setVal} min={0} max={1} step={0.01} />
-<ColorSlider sliderType="lightness" value={[0.6]} onValueChange={setVal} min={0} max={1} step={0.01} />
+<ColorSlider sliderType="hue" defaultValue={[240]} onValueChange={setVal} min={0} max={360} />
+<ColorSlider sliderType="saturation" defaultValue={[0.5]} onValueChange={setVal} min={0} max={1} step={0.01} />
+<ColorSlider sliderType="lightness" defaultValue={[0.6]} onValueChange={setVal} min={0} max={1} step={0.01} />
 ```
 
 ## Custom

package/docs/components/nqui-combobox.md

@@ -1,73 +1,94 @@
 # nqui Combobox
 
-> **Searchable** select. Single or multi-select. Use when user types to filter options.
+> **Searchable** select (Base UI). User types to filter options. Single or multiple selection.
 
 ## When to Use
 
-- **Selection:** Single or multiple
-- **Key feature:** User searches/filters options by typing
-- **Options:** Many (dozens, hundreds)
+- **Selection:** Single (default) or multiple (`multiple` on root)
+- **Key feature:** Filter list by typing in the input
+- **Options:** Many rows; use **`items`** on `Combobox` + render prop on `ComboboxList` for built-in filtering
 
-**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.
+**Choose Combobox when:** Users need search. Use **Select** when a plain dropdown is enough.
 
 ## Import
 
 ```tsx
 import {
-  Combobox, ComboboxInput, ComboboxContent, ComboboxList,
-  ComboboxItem, ComboboxEmpty, ComboboxChips, ComboboxChip,
-  ComboboxTrigger, ComboboxValue, ComboboxCollection, ComboboxGroup,
-  ComboboxLabel, ComboboxSeparator
+  Combobox,
+  ComboboxInput,
+  ComboboxContent,
+  ComboboxList,
+  ComboboxItem,
+  ComboboxEmpty,
+  ComboboxGroup,
+  ComboboxLabel,
+  ComboboxSeparator,
+  ComboboxCollection,
+  ComboboxChips,
+  ComboboxChip,
+  ComboboxChipsInput,
+  ComboboxTrigger,
+  ComboboxValue,
+  ComboboxClear,
+  useComboboxAnchor,
 } from "@nqlib/nqui"
 ```
 
-## Basic
+## Single selection + type-to-filter (recommended)
+
+Pass **`items`** to `Combobox` and use a **render function** as the only child of `ComboboxList`. Place **`ComboboxEmpty`** next to `ComboboxList` (both under `ComboboxContent`), not inside `ComboboxList` alongside the function.
 
 ```tsx
-<Combobox options={items} value={value} onChange={setValue}>
+const fruits = ["Apple", "Banana", "Cherry", "Date", "Elderberry"]
+
+<Combobox items={fruits}>
   <ComboboxInput placeholder="Search..." />
   <ComboboxContent>
+    <ComboboxEmpty>No results found.</ComboboxEmpty>
     <ComboboxList>
-      {items.map((item) => (
-        <ComboboxItem key={item.value} value={item.value}>{item.label}</ComboboxItem>
-      ))}
+      {(item) => (
+        <ComboboxItem key={item} value={item}>
+          {item}
+        </ComboboxItem>
+      )}
     </ComboboxList>
-    <ComboboxEmpty>No results</ComboboxEmpty>
   </ComboboxContent>
 </Combobox>
 ```
 
-## showClear
+## Static list (no `items` filter)
 
-```tsx
-<Combobox showClear ... />
-```
-
-## Multi-select chips
+You can still render `ComboboxItem` children manually when you control filtering yourself.
 
 ```tsx
-<Combobox multiSelect value={selected} onChange={setSelected}>
-  <ComboboxChips placeholder="Select...">
-    {(vals) => vals.map((v) => <ComboboxChip key={v} value={v} onRemove={...} />)}
-  </ComboboxChips>
-  ...
+<Combobox>
+  <ComboboxInput placeholder="Search..." />
+  <ComboboxContent>
+    <ComboboxList>
+      <ComboboxItem value="a">A</ComboboxItem>
+      <ComboboxItem value="b">B</ComboboxItem>
+    </ComboboxList>
+  </ComboboxContent>
 </Combobox>
 ```
 
-## Groups
+## Clear button
 
 ```tsx
-<ComboboxCollection>
-  <ComboboxGroup>
-    <ComboboxLabel>Group A</ComboboxLabel>
-    <ComboboxItem value="a">A</ComboboxItem>
-  </ComboboxGroup>
-  <ComboboxSeparator />
-  ...
-</ComboboxCollection>
+<ComboboxInput showClear placeholder="Search..." />
 ```
 
+## Multiple selection
+
+Use **`multiple`** on `Combobox` (see [Base UI Combobox](https://base-ui.com/react/components/combobox)). Combine with **`ComboboxChips`**, **`ComboboxChip`**, **`ComboboxChipsInput`** as needed for chip UI.
+
+## Implementation
+
+- **Source:** `packages/nqui/src/components/ui/combobox.tsx`
+- **Public API:** exported from `@nqlib/nqui` (same as `CoreCombobox*` aliases in the barrel if you need the unprefixed base re-exports)
+- **Styling:** Input group uses injected CSS once per page (`nqui-combobox-styles-v1`) for trigger depth/shadow; component is `"use client"`.
+
 ## Notes
 
-- Injects CSS at mount; client-only in SSR.
-- `useComboboxAnchor` for PopoverAnchor positioning.
+- **`useComboboxAnchor`:** ref for anchoring `ComboboxContent` when using chips / custom layout.
+- **Dropdown items:** spacing/hover treatment aligns with **Select** (`SelectItem`-style density).

package/docs/components/nqui-drawer.md

@@ -1,6 +1,6 @@
 # nqui Drawer
 
-> Bottom drawer. DrawerTrigger, DrawerContent, DrawerHeader, DrawerTitle, DrawerDescription, DrawerFooter.
+> **Vaul** drawer. **DrawerContent** keeps an **inset rounded card** (`before:bg-card`, `before:inset-2`, `before:rounded-xl`) so the panel does not read as a full-bleed slab—surface follows **`card`** tokens in both themes.
 
 ## Import
 

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

@@ -18,13 +18,56 @@ import { RadioGroup, RadioGroupItem } from "@nqlib/nqui"
 
 ## Basic
 
+RadioGroupItem now automatically wraps the radio button with a label when children are provided:
+
 ```tsx
+const [value, setValue] = useState("a")
+
 <RadioGroup value={value} onValueChange={setValue}>
-  <RadioGroupItem value="a" /> A
-  <RadioGroupItem value="b" /> B
+  <RadioGroupItem value="a">Option A</RadioGroupItem>
+  <RadioGroupItem value="b">Option B</RadioGroupItem>
 </RadioGroup>
 ```
 
+## With Complex Content
+
+```tsx
+<RadioGroup value={value} onValueChange={setValue}>
+  <RadioGroupItem value="email">
+    <div>
+      <div className="font-medium">Email</div>
+      <div className="text-sm text-muted-foreground">Receive notifications via email</div>
+    </div>
+  </RadioGroupItem>
+  <RadioGroupItem value="sms">
+    <div>
+      <div className="font-medium">SMS</div>
+      <div className="text-sm text-muted-foreground">Receive notifications via SMS</div>
+    </div>
+  </RadioGroupItem>
+</RadioGroup>
+```
+
+## Spacing
+
+Control the gap between radio items with the `gap` prop on RadioGroup:
+
+```tsx
+<RadioGroup gap={0}>No gap</RadioGroup>
+<RadioGroup gap={1}>4px gap</RadioGroup>
+<RadioGroup gap={2}>Compact (8px)</RadioGroup>
+<RadioGroup gap={3}>Default (12px)</RadioGroup>
+<RadioGroup gap={4}>Loose (16px)</RadioGroup>
+```
+
+Control the gap between radio button and label with the `spacing` prop on RadioGroupItem:
+
+```tsx
+<RadioGroupItem value="a" spacing="compact">Tight spacing (8px)</RadioGroupItem>
+<RadioGroupItem value="b" spacing="default">Default spacing (12px)</RadioGroupItem>
+<RadioGroupItem value="c" spacing="comfortable">Loose spacing (16px)</RadioGroupItem>
+```
+
 ## Variants
 
 ```tsx

package/docs/components/nqui-scroll-area.md

@@ -1,6 +1,6 @@
 # nqui ScrollArea
 
-> Custom scrollbar. fadeMask (enhanced), horizontal scroll.
+> Default export is **EnhancedScrollArea** (fade mask, orientation). Underlying primitive: **`CoreScrollArea`** / `ScrollBar` from **`ui/scroll-area`**. Core scrollbar uses a **thinner** track/thumb (drawer-like).
 
 ## Import
 

package/docs/components/nqui-select.md

@@ -48,6 +48,6 @@ import { Select, SelectTrigger, SelectValue, SelectContent, SelectItem, SelectGr
 
 ## Notes
 
-- Injects CSS at mount; client-only in SSR.
+- **Content:** FrostedGlass + popover surface; **items** use relaxed row spacing (hover `accent`, margins) for dropdown parity with **Combobox** list items.
 - Use `SelectScrollUpButton` / `SelectScrollDownButton` for long lists.
-- `CoreSelect*` for plain styling.
+- **`CoreSelect*`** for the same primitives without the enhanced trigger chrome (re-exported from the same `ui/select` module).

package/docs/components/nqui-sheet.md

@@ -1,6 +1,6 @@
 # nqui Sheet
 
-> Side panel. SheetTrigger, SheetContent, SheetHeader, SheetTitle, SheetDescription, SheetFooter. side: top|right|bottom|left.
+> Side panel (Radix **Dialog** pattern). **SheetContent** uses an **inset card** panel: transparent outer shell + `before:bg-card` block inset with **rounded corners** (matches drawer-style “card floating in the viewport”). **No edge borders** on the sheet shell (divider lines removed in favor of the card shape).
 
 ## Import
 

package/docs/components/nqui-slider.md

@@ -14,3 +14,16 @@ import { Slider } from "@nqlib/nqui"
 <Slider value={[50]} onValueChange={([v]) => setVal(v)} />
 <Slider value={[20, 80]} onValueChange={setRange} />
 ```
+
+## Sizes
+
+```tsx
+<Slider size="sm" defaultValue={[40]} />
+<Slider size="default" defaultValue={[40]} />
+<Slider size="lg" defaultValue={[40]} />
+```
+
+## Notes
+
+- **Thumb:** white, rounded-full, subtle shadow (aligned with **Switch** thumb language).
+- **`size`:** `sm` | `default` | `lg` (control scale heights).

package/docs/components/nqui-spinner.md

@@ -1,6 +1,6 @@
 # nqui Spinner
 
-> Loading spinner.
+> Dual-arc loader (primary **`linearGradient`** strokes, rotating shell). Keyframes live in **`packages/nqui/src/index.css`** (`.nqui-spinner-*`).
 
 ## Import
 
@@ -14,3 +14,8 @@ import { Spinner } from "@nqlib/nqui"
 <Spinner />
 <Spinner className="size-6" />
 ```
+
+## Notes
+
+- Root is a `div` with `role="status"` and `aria-label="Loading"`.
+- Strokes use `var(--primary)` and `color-mix(in oklch, var(--primary) …, white)` so light/dark themes stay on-brand.

package/docs/components/nqui-switch.md

@@ -1,6 +1,6 @@
 # nqui Switch
 
-> Toggle switch. Core Radix.
+> Toggle switch. **Radix** primitive with **size** variants and **capsule thumb** (white, shadow). Sizes align with control scale: `sm` / `default` / `lg`.
 
 ## Import
 
@@ -13,3 +13,25 @@ import { Switch } from "@nqlib/nqui"
 ```tsx
 <Switch checked={checked} onCheckedChange={setChecked} />
 ```
+
+## Sizes
+
+```tsx
+<Switch size="sm" />
+<Switch size="default" />
+<Switch size="lg" />
+```
+
+## Hit area
+
+The switch root has no `::before` styling, so you can add [hit-area utilities](https://bazza.dev/craft/2026/hit-area) on the same element:
+
+```tsx
+<Switch className="hit-area-4" id="notifications" />
+```
+
+Use sparingly in dense toolbars so expanded targets do not overlap.
+
+## Notes
+
+- Thumb travel and track sizes are fixed per `size`; overriding height on the root without matching thumb classes may look off.

package/docs/components/nqui-tabs.md

@@ -31,5 +31,15 @@ import { Tabs, TabsList, TabsTrigger, TabsContent } from "@nqlib/nqui"
 
 ## Notes
 
-- Sliding indicator needs `position: relative` on TabsList container.
+- **Sliding indicator:** Requires `position: relative` on TabsList container (handled automatically by the component).
+- **Responsive behavior:** On small screens, TabsList can overflow horizontally. Use `overflow-x-auto` on parent if needed.
+- **Container requirements:** For the sliding indicator to work correctly, the TabsList container needs:
+  ```css
+  .sliding-indicator-container {
+    position: relative;
+    overflow: hidden;
+    min-width: 0;
+  }
+  ```
+- **Resize handling:** The indicator recalculates position on window resize (built-in).
 - Use `EnhancedTabsList` props for additional customization.

package/docs/components/nqui-toaster.md

@@ -1,6 +1,6 @@
 # nqui Toaster
 
-> Toast notifications (sonner). Semantic types, promise pattern.
+> Toast notifications via **Sonner**. Default toast is **pill-shaped**; default **normal** toast uses **inverted** surface (dark fill in light theme, light fill in dark theme) using `--foreground` / `--background`. Implemented in **`packages/nqui/src/components/ui/sonner.tsx`** (`Toaster`). Compatibility aliases: `EnhancedSonner`, `CoreToaster` → same component.
 
 ## Import
 
@@ -42,3 +42,7 @@ toast.promise(fetchData(), {
 toast.success("Msg", { duration: 5000 })
 // Toaster: position, richColors, etc.
 ```
+
+## Notes
+
+- **Subpath import:** `@nqlib/nqui/sonner` re-exports the same `Toaster`.

package/docs/internal-notes/PUBLISHING.md

@@ -230,15 +230,57 @@ If a version had bugs (e.g. init-cursor routed to wrong script, skills not worki
    npm deprecate @nqlib/nqui@0.4.1 "Use 0.4.2 instead. See changelog."
    ```
 
-4. **Unpublish** (rare, npm restrictions apply):
-   - Must be within 72 hours of publish
-   - No other packages can depend on it
-   - `npm unpublish @nqlib/nqui@0.4.1 --force`
+4. **Unpublish** (rare, npm restrictions apply): See [Unpublishing](#unpublishing) below.
 
 **Recommendation:** Usually deprecate + publish patch. Unpublish only for security issues.
 
 ---
 
+## Unpublishing
+
+### npmjs.com
+
+**Rules:**
+- **Within 72 hours of publish**: You can unpublish. The version is then available for re-publish.
+- **After 72 hours**: Unpublish is disallowed. Versions are permanently locked. Use deprecation instead.
+
+**Unpublish a specific version** (within 72 hours):
+```bash
+cd packages/nqui
+npm unpublish @nqlib/nqui@0.4.1 --force --registry=https://registry.npmjs.com
+```
+
+**Unpublish entire package** (within 72 hours, removes all versions):
+```bash
+npm unpublish @nqlib/nqui --force --registry=https://registry.npmjs.com
+```
+
+**After 72 hours – deprecate instead:**
+```bash
+npm deprecate @nqlib/nqui@0.4.1 "Superseded by 0.4.2. Use npm install @nqlib/nqui@0.4.2"
+```
+
+### GitHub Packages
+
+**Rules:**
+- You can delete any version at any time.
+- Deleted versions can be re-published (unlike npm).
+
+**Delete via GitHub UI:**
+1. Go to your repo → **Packages** (right sidebar) or `https://github.com/ORG/REPO/packages`
+2. Click the package `nqui`
+3. **Manage package** → **Delete package** (entire package) or **Manage versions** → delete specific versions
+
+**Delete via GitHub API** (for automation):
+```bash
+# Requires GITHUB_TOKEN with delete:packages
+curl -X DELETE -H "Authorization: token $GITHUB_TOKEN" \
+  "https://api.github.com/orgs/nqlib/packages/npm/nqui/versions/VERSION_ID"
+```
+(Get `VERSION_ID` from the package page or API.)
+
+---
+
 ## Version Management
 
 The `npm version` command automatically:

package/docs/nqui-skills/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: nqui Components
+description: Component implementation guide for nqui. Use when building UI, designing app layouts, or implementing components with @nqlib/nqui.
+---
+
+# nqui Components Guide
+
+Reference `packages/nqui/docs/components/README.md` for the full component index and implementation rules.
+
+## Quick Reference
+
+1. **Main index:** `packages/nqui/docs/components/README.md` - all components, use cases, prerequisites
+2. **Per-component:** `packages/nqui/docs/components/nqui-<name>.md` - import, examples, variants
+3. **Design system:** this folder - sizing, grouped controls
+
+## App Design Rule: Inline Selection → ToggleGroup
+
+When designing app UI (toolbars, headers, inline controls):
+
+| Context | Use | NOT |
+|---------|-----|-----|
+| View mode (List/Grid/Table), scale (Linear/Log), size (S/M/L) | **ToggleGroup** `type="single"` | RadioGroup |
+| Format toolbar (Bold/Italic/Underline), multi-toggle | **ToggleGroup** `type="multiple"` | Multiple Checkboxes |
+| Toolbar actions (Undo/Redo, align) | **ButtonGroup** | - |
+| Single on/off (Bold, Mute) | **Toggle** | - |
+
+**Rule:** Inline/toolbar selection = ToggleGroup. Use RadioGroup only for form context (settings page, modal form, stacked list).
+
+## App Design Rule: Context-First (Toolbar in Real Environment)
+
+**Rule:** Never show Toggle/ToggleGroup/ButtonGroup in isolation. Always place them in realistic app context.
+
+| Context | Layout | Reference |
+|---------|--------|-----------|
+| Document editor | Toolbar above content; `bg-muted/30` container; `Separator` between groups | ComponentShowcase → Toggle & ToggleGroup |
+| Chart/settings | Label + inline controls; `rounded-lg border bg-muted/30 p-3` | ComponentShowcase → Chart settings |
+| Standalone | Inline with related UI | ComponentShowcase → Standalone toggle |
+
+**Canonical implementation:** `packages/nqui/src/pages/ComponentShowcase.tsx` — Toggle & ToggleGroup section.
+
+## Design System Conventions
+
+See **`design-system.md`** in this folder for sizing, grouped controls (including pill **ButtonGroup** / **ToggleGroup** shells), and file paths under `packages/nqui/src/components/ui/`.
+
+### Control Sizing
+- sm = h-6
+- default = h-7
+- lg = h-8
+
+### Z-Index
+Always use CSS variables from elevation.css:
+- `--z-content` (10) - standard content
+- `--z-sticky-content` (15) - sticky within containers
+- `--z-sticky-page` (20) - page-level sticky
+- `--z-floating` (30) - floating panels
+- `--z-modal-backdrop` (40)
+- `--z-modal` (50)
+- `--z-popover` (60)
+- `--z-tooltip` (70)
+
+### Component Naming
+- Default exports are the enhanced/polished variants; use **Core\*** for plain primitives
+- Implementations are consolidated under **`ui/`** (not separate `custom/enhanced-*` per component for Button, Badge, Checkbox, Select, Combobox, Sonner)
+- File names: kebab-case
+- Component names: PascalCase
+
+### Hit area (optional)
+
+Library CSS includes [Bazza hit-area](https://bazza.dev/craft/2026/hit-area) utilities. For **Checkbox** / **Switch** in padded tables or lists, pass **`className="hit-area-6"`** (or `hit-area-4`, axis variants) on the **component root**, not on a wrapper-only parent. Opt-in only; use **`hit-area-debug`** while tuning. Details: `packages/nqui/docs/components/nqui-checkbox.md`, `nqui-switch.md`; examples: `ComponentShowcase` Checkbox + Switch sections.
+
+## Key Dependencies
+
+Required peer dependencies:
+- `@hugeicons/react`
+- `@hugeicons/core-free-icons`
+
+Optional:
+- `next-themes` - for theme toggle
+- `tw-animate-css` - for animations
+
+## Installation & Setup
+
+```bash
+# Quick setup
+npx @nqlib/nqui init-css
+
+# App setup with sidebar
+npx @nqlib/nqui init-css --sidebar
+
+# Install peer dependencies
+npx @nqlib/nqui install-peers
+```
+
+## CSS Variables
+
+All components use CSS variables. Key ones:
+- `--background`, `--foreground`
+- `--muted`, `--muted-foreground`
+- `--accent`, `--accent-foreground`
+- `--border`, `--ring`
+- `--primary`, `--primary-foreground`
+- `--destructive`, `--destructive-foreground`