@nqlib/nqui 0.3.3 → 0.4.1

package/docs/components/nqui-select.md

@@ -1,6 +1,16 @@
 # nqui Select
 
-> Dropdown select. Enhanced with 3D shadow, frosted glass content.
+> **1 selection** from options. Dropdown. Use when 5+ options or no space for inline.
+
+## When to Use
+
+- **Selection:** Single
+- **Options:** 5+ (or any count when space is limited)
+- **Layout:** Dropdown (collapsed until open)
+
+**Choose Select when:** Too many options for ToggleGroup, or UI space is tight. User picks from a list that opens on click.
+
+**Use ToggleGroup instead** when 2–4 options and space for inline display. **Use Combobox** when user needs to search/filter options.
 
 ## Import
 
@@ -11,7 +21,7 @@ import { Select, SelectTrigger, SelectValue, SelectContent, SelectItem, SelectGr
 ## Basic
 
 ```tsx
-<Select>
+<Select value={value} onValueChange={setValue}>
   <SelectTrigger><SelectValue placeholder="Pick" /></SelectTrigger>
   <SelectContent>
     <SelectItem value="a">A</SelectItem>
@@ -36,15 +46,8 @@ import { Select, SelectTrigger, SelectValue, SelectContent, SelectItem, SelectGr
 </SelectContent>
 ```
 
-## Controlled
-
-```tsx
-<Select value={value} onValueChange={setValue}>
-  ...
-</Select>
-```
-
 ## Notes
 
 - Injects CSS at mount; client-only in SSR.
 - Use `SelectScrollUpButton` / `SelectScrollDownButton` for long lists.
+- `CoreSelect*` for plain styling.

package/docs/components/nqui-separator.md

@@ -1,6 +1,6 @@
 # nqui Separator
 
-> Divider. Horizontal or vertical.
+> Horizontal or vertical divider with multiple visual variants.
 
 ## Import
 
@@ -14,3 +14,35 @@ import { Separator } from "@nqlib/nqui"
 <Separator />
 <Separator orientation="vertical" />
 ```
+
+## Variants
+
+Single component with `variant` prop. No separate Enhanced/Core—use `variant="solid"` for plain style.
+
+| Variant | Description |
+|---------|-------------|
+| `default` | Fade at ends (gradient) |
+| `solid` | Solid line |
+| `shadow-outset` | Outset shadow |
+| `shadow-inset` | Inset shadow |
+| `dotted` | Dotted line |
+| `dashed` | Dashed line |
+| `double` | Double line |
+| `glow` | Glow effect |
+| `thick` | 2px line |
+| `gradient` | Primary→accent gradient |
+| `fade-strong` | Stronger fade, reduced opacity |
+| `arrow-down` | Decorative arrow center |
+| `tab-down` | Rounded tab center |
+| `stopper` | Rectangular stopper center |
+| `dot` | Circular dot center |
+| `text-decoration` | Text in center (use `textContent`) |
+| `shiny-corner` | Lighting on edges |
+| `shiny-edge` | Softer edge highlight |
+
+```tsx
+<Separator variant="default" />
+<Separator variant="solid" />
+<Separator variant="shadow-outset" />
+<Separator variant="text-decoration" textContent="OR" />
+```

package/docs/components/nqui-snippet.md

@@ -8,7 +8,7 @@
 import {
   Snippet, SnippetHeader, SnippetTabsList, SnippetTabsTrigger,
   SnippetTabsContent, SnippetCopyButton
-} from "@nqlib/nqui"
+} from "@nqlib/nqcode"
 ```
 
 ## Basic

package/docs/components/nqui-table.md

@@ -0,0 +1,43 @@
+# nqui Table
+
+> Semantic table layout. Shadcn Table primitives; use DataTable for sorting/filtering/pagination.
+
+## Import
+
+```tsx
+import {
+  Table, TableHeader, TableBody, TableFooter,
+  TableHead, TableRow, TableCell, TableCaption
+} from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<Table>
+  <TableHeader>
+    <TableRow>
+      <TableHead>Name</TableHead>
+      <TableHead>Status</TableHead>
+    </TableRow>
+  </TableHeader>
+  <TableBody>
+    {data.map((row) => (
+      <TableRow key={row.id}>
+        <TableCell>{row.name}</TableCell>
+        <TableCell>{row.status}</TableCell>
+      </TableRow>
+    ))}
+  </TableBody>
+</Table>
+```
+
+## Use Case
+
+- Static/simple data tables
+- Layout structure for custom table logic
+- When you need semantic `<table>` without DataTable features
+
+## Core vs Enhanced
+
+Table is core shadcn only. For sorting, filtering, pagination, row selection, use DataTable (requires `@tanstack/react-table`).

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

@@ -1,21 +1,65 @@
 # nqui ToggleGroup
 
-> Group of toggle buttons. Single or multiple selection.
+> **Single or multiple selection** from 2–5 options. Inline. **Default for toolbar/inline UI** (view mode, format bar, size picker).
+
+## When to Use
+
+- **Selection:** Single (`type="single"`) or Multiple (`type="multiple"`)
+- **Options:** 2–5
+- **Layout:** Inline
+
+**Design is inferred from type:**
+- `type="single"` – Segmented style (primary fill on selected). E.g. view mode, scale type (Linear/Log).
+- `type="multiple"` – Outline style (muted fill on selected). E.g. format toolbar (bold, italic, underline).
+
+**Examples:**
+- Single: view mode, scale type (Linear/Log), size (Small/Medium/Large)
+- Multiple: format toolbar (bold, italic, underline)
+
+**Use Select** when 5+ options or no space.
 
 ## Import
 
 ```tsx
-import { ToggleGroup, ToggleGroupItem } from "@nqlib/nqui"
+import { ToggleGroup, ToggleGroupItem, ToggleGroupSeparator } from "@nqlib/nqui"
 ```
 
 ## Basic
 
 ```tsx
+{/* Single (segmented, primary fill) */}
 <ToggleGroup type="single" value={v} onValueChange={setV}>
-  <ToggleGroupItem value="a">A</ToggleGroupItem>
-  <ToggleGroupItem value="b">B</ToggleGroupItem>
+  <ToggleGroupItem value="linear">Linear</ToggleGroupItem>
+  <ToggleGroupItem value="log">Log</ToggleGroupItem>
 </ToggleGroup>
+
+{/* Multiple (outline) */}
 <ToggleGroup type="multiple" value={vals} onValueChange={setVals}>
-  ...
+  <ToggleGroupItem value="bold"><BoldIcon /></ToggleGroupItem>
+  <ToggleGroupItem value="italic"><ItalicIcon /></ToggleGroupItem>
+</ToggleGroup>
+```
+
+## With manual separators
+
+Dividers are shown via item borders by default (using `foreground/20` for theme-safe visibility). Use `ToggleGroupSeparator` (nqui Separator) when `separator={false}` or `spacing>0` for explicit separator placement:
+
+```tsx
+<ToggleGroup type="single" variant="outline" separator={false}>
+  <ToggleGroupItem value="left">Left</ToggleGroupItem>
+  <ToggleGroupSeparator />
+  <ToggleGroupItem value="center">Center</ToggleGroupItem>
+  <ToggleGroupSeparator />
+  <ToggleGroupItem value="right">Right</ToggleGroupItem>
 </ToggleGroup>
 ```
+
+## Context
+
+Place in realistic app context (document toolbar, chart settings panel). Never show in isolation. Reference: `src/pages/ComponentShowcase.tsx` → Toggle & ToggleGroup section (document editor, chart settings).
+
+## Notes
+
+- `spacing={0}` (default) = shared border, no gap, dividers between items (border using `foreground/20`). `spacing={2}` = gap between items, no dividers.
+- Selected: default/outline → `bg-secondary` + gradient + shadow; segmented → `bg-primary` + gradient + shadow. Ensures visibility on card, sidebar, varied backgrounds.
+- Pass `variant="outline"` to override single’s default segmented style.

package/docs/components/nqui-toggle.md

@@ -1,6 +1,17 @@
 # nqui Toggle
 
-> Toggle button. Core Radix.
+> **One on/off state.** Not a group. E.g. bold in editor.
+
+## When to Use
+
+- **State:** Single boolean (on/off)
+- **Context:** Standalone, or one item in a toolbar
+
+**Choose Toggle when:** One independent switch (bold, mute, pin). User toggles one thing.
+
+**Use ToggleGroup when:** Multiple related toggles (bold + italic + underline) or single/multi selection from options.
+
+**Use Switch when:** Form setting (dark mode, notifications). Toggle = formatting/tool state. Switch = app preference.
 
 ## Import
 
@@ -11,5 +22,17 @@ import { Toggle } from "@nqlib/nqui"
 ## Basic
 
 ```tsx
-<Toggle pressed={pressed} onPressedChange={setPressed}>Toggle</Toggle>
+<Toggle aria-label="Bold" pressed={isBold} onPressedChange={setIsBold}>
+  <BoldIcon />
+</Toggle>
 ```
+
+## Variants
+
+- **default** – Off: subtle border (`border-input/60`), shadow. On: `bg-secondary` + gradient + shadow (secondary-like layering).
+- **outline** – Off: border, shadow. On: same secondary layering.
+- **segmented** – Primary fill when on (used in ToggleGroup single). Gradient + shadow when selected.
+
+## Context
+
+Place in realistic app context (toolbar, panel). Reference: `src/pages/ComponentShowcase.tsx` → Toggle & ToggleGroup section.

package/docs/internal-notes/APP_BUILDER_PACKAGE.md

@@ -0,0 +1,86 @@
+# App Builder Package (@nqlib/nqappbuilder)
+
+## Overview
+
+The App Builder has been extracted from nqui into a separate package `@nqlib/nqappbuilder` to reduce nqui's bundle size and allow independent versioning. The visual app builder includes a drag-and-drop canvas, widget palette, configurator, and registry system.
+
+## Installation
+
+```bash
+pnpm add @nqlib/nqappbuilder @nqlib/nqui
+# or
+npm install @nqlib/nqappbuilder @nqlib/nqui
+```
+
+## Peer Dependencies
+
+- `react` (^18.2.0)
+- `react-dom` (^18.2.0)
+- `@nqlib/nqui` (required) — provides UI components, design tokens, and utilities
+
+Consumers must install these alongside nqappbuilder.
+
+## Usage
+
+```tsx
+import {
+  AppBuilder,
+  AppBuilderProvider,
+  AppCanvas,
+  WidgetPalette,
+  WidgetConfigurator,
+  defaultRegistry,
+} from "@nqlib/nqappbuilder"
+
+// All-in-one component
+export default function MyAppBuilder() {
+  return (
+    <AppBuilderProvider registry={defaultRegistry}>
+      <AppBuilder />
+    </AppBuilderProvider>
+  )
+}
+
+// Or compose manually
+export default function CustomLayout() {
+  return (
+    <AppBuilderProvider registry={defaultRegistry}>
+      <aside>
+        <WidgetPalette />
+      </aside>
+      <main>
+        <AppCanvas showToolbar enableCollisionDetection />
+      </main>
+      <WidgetConfigurator />
+    </AppBuilderProvider>
+  )
+}
+```
+
+## Extending the Registry
+
+Use `createWidgetRegistry`, `extendRegistry`, or pass a custom `registry` to `AppBuilderProvider`:
+
+```tsx
+import {
+  createWidgetRegistry,
+  extendRegistry,
+  defaultRegistry,
+  buttonWidget,
+  containerWidget,
+} from "@nqlib/nqappbuilder"
+
+const myRegistry = extendRegistry(defaultRegistry, [
+  buttonWidget,
+  containerWidget,
+  myCustomWidget,
+])
+
+<AppBuilderProvider registry={myRegistry}>
+  <AppBuilder />
+</AppBuilderProvider>
+```
+
+## Documentation App
+
+Documentation maintainers: add a section or page for nqappbuilder in the documentation app. Link to this note for package details and migration context.