@nqlib/nqui 0.3.2 → 0.4.0

package/docs/components/nqui-snippet.md

@@ -0,0 +1,28 @@
+# nqui Snippet
+
+> Tabbed code display. SnippetHeader, SnippetTabsList, SnippetTabsTrigger, SnippetTabsContent, SnippetCopyButton.
+
+## Import
+
+```tsx
+import {
+  Snippet, SnippetHeader, SnippetTabsList, SnippetTabsTrigger,
+  SnippetTabsContent, SnippetCopyButton
+} from "@nqlib/nqcode"
+```
+
+## Basic
+
+```tsx
+<Snippet defaultValue="tsx">
+  <SnippetHeader>
+    <SnippetTabsList>
+      <SnippetTabsTrigger value="tsx">TSX</SnippetTabsTrigger>
+      <SnippetTabsTrigger value="jsx">JSX</SnippetTabsTrigger>
+    </SnippetTabsList>
+    <SnippetCopyButton value={code} />
+  </SnippetHeader>
+  <SnippetTabsContent value="tsx">{code}</SnippetTabsContent>
+  <SnippetTabsContent value="jsx">{code}</SnippetTabsContent>
+</Snippet>
+```

package/docs/components/nqui-sortable.md

@@ -0,0 +1,46 @@
+# nqui Sortable
+
+> Drag-and-drop reorder. Import from `@nqlib/nqui` or `@/components/ui/sortable`.
+
+## Import
+
+```tsx
+import {
+  Sortable, SortableContent, SortableItem, SortableItemHandle, SortableOverlay
+} from "@/components/ui/sortable"
+// Or if exported: import { ... } from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<Sortable value={items} onValueChange={setItems} orientation="vertical">
+  <SortableContent asChild>
+    <div>
+      {items.map((item) => (
+        <SortableItem key={item} value={item} asChild>
+          <div>
+            <SortableItemHandle asChild><button>⋮⋮</button></SortableItemHandle>
+            {item}
+          </div>
+        </SortableItem>
+      ))}
+    </div>
+  </SortableContent>
+  <SortableOverlay>
+    {({ value }) => <div>Dragging: {value}</div>}
+  </SortableOverlay>
+</Sortable>
+```
+
+## Object Array
+
+```tsx
+<Sortable value={objects} onValueChange={setObjects} getItemValue={(o) => o.id}>
+  ...
+</Sortable>
+```
+
+## orientation
+
+`vertical` | `horizontal` | `mixed`

package/docs/components/nqui-spinner.md

@@ -0,0 +1,16 @@
+# nqui Spinner
+
+> Loading spinner.
+
+## Import
+
+```tsx
+import { Spinner } from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<Spinner />
+<Spinner className="size-6" />
+```

package/docs/components/nqui-switch.md

@@ -0,0 +1,15 @@
+# nqui Switch
+
+> Toggle switch. Core Radix.
+
+## Import
+
+```tsx
+import { Switch } from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<Switch checked={checked} onCheckedChange={setChecked} />
+```

package/docs/components/nqui-table-of-contents.md

@@ -0,0 +1,37 @@
+# nqui TableOfContents
+
+> TOC from headings. Auto-detect or manual items. Scroll spy.
+
+## Import
+
+```tsx
+import { TableOfContents } from "@nqlib/nqui"
+```
+
+## Auto-detect
+
+```tsx
+<TableOfContents
+  autoDetect
+  headingSelector="h2"
+  enableScrollSpy
+  container={contentRef}
+  title="Contents"
+/>
+```
+
+## Manual Items
+
+```tsx
+<TableOfContents
+  items={[{ id: "s1", label: "Section 1", level: 1 }]}
+  enableScrollSpy
+  variant="normal"
+/>
+```
+
+## Notes
+
+- Headings need `id` for anchor links.
+- container: scoped scroll container. Omit for full page.
+- variant: "normal" | "clerk" | "circuit".

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-tabs.md

@@ -0,0 +1,35 @@
+# nqui Tabs
+
+> Tabbed content. Sliding indicator. Enhanced.
+
+## Import
+
+```tsx
+import { Tabs, TabsList, TabsTrigger, TabsContent } from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<Tabs defaultValue="tab1">
+  <TabsList>
+    <TabsTrigger value="tab1">Tab 1</TabsTrigger>
+    <TabsTrigger value="tab2">Tab 2</TabsTrigger>
+  </TabsList>
+  <TabsContent value="tab1">Content 1</TabsContent>
+  <TabsContent value="tab2">Content 2</TabsContent>
+</Tabs>
+```
+
+## Controlled
+
+```tsx
+<Tabs value={value} onValueChange={setValue}>
+  ...
+</Tabs>
+```
+
+## Notes
+
+- Sliding indicator needs `position: relative` on TabsList container.
+- Use `EnhancedTabsList` props for additional customization.

package/docs/components/nqui-textarea.md

@@ -0,0 +1,15 @@
+# nqui Textarea
+
+> Multi-line text input. Core.
+
+## Import
+
+```tsx
+import { Textarea } from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<Textarea placeholder="Message..." />
+```

package/docs/components/nqui-toaster.md

@@ -0,0 +1,44 @@
+# nqui Toaster
+
+> Toast notifications (sonner). Semantic types, promise pattern.
+
+## Import
+
+```tsx
+import { Toaster, toast } from "@nqlib/nqui"
+```
+
+## Setup
+
+```tsx
+// Add once (e.g. layout)
+<Toaster />
+```
+
+## Types
+
+```tsx
+toast.success("Saved")
+toast.error("Failed")
+toast.warning("Warning")
+toast.info("Info")
+toast("Default")
+toast.loading("Loading...")
+```
+
+## Promise
+
+```tsx
+toast.promise(fetchData(), {
+  loading: "Loading...",
+  success: "Done",
+  error: "Failed"
+})
+```
+
+## Options
+
+```tsx
+toast.success("Msg", { duration: 5000 })
+// Toaster: position, richColors, etc.
+```

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

@@ -0,0 +1,65 @@
+# nqui ToggleGroup
+
+> **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, ToggleGroupSeparator } from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+{/* Single (segmented, primary fill) */}
+<ToggleGroup type="single" value={v} onValueChange={setV}>
+  <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

@@ -0,0 +1,38 @@
+# nqui Toggle
+
+> **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
+
+```tsx
+import { Toggle } from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<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/components/nqui-tooltip.md

@@ -0,0 +1,24 @@
+# nqui Tooltip
+
+> Hover tooltip. Wrap app in TooltipProvider.
+
+## Import
+
+```tsx
+import { Tooltip, TooltipTrigger, TooltipContent, TooltipProvider } from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<TooltipProvider>
+  <Tooltip>
+    <TooltipTrigger asChild><Button>Hover</Button></TooltipTrigger>
+    <TooltipContent>Tooltip text</TooltipContent>
+  </Tooltip>
+</TooltipProvider>
+```
+
+## Provider
+
+Place once at app root (or layout).

package/docs/components/nqui-tracker.md

@@ -0,0 +1,38 @@
+# nqui Tracker
+
+> GitHub-style block strip. Activity/status visualization. Tooltips.
+
+## Import
+
+```tsx
+import { Tracker } from "@nqlib/nqui"
+import type { TrackerBlockProps } from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<Tracker
+  data={[
+    { color: "bg-emerald-600", tooltip: "Active" },
+    { color: "bg-red-600", tooltip: "Error" },
+    { tooltip: "No data" }
+  ]}
+/>
+```
+
+## Options
+
+```tsx
+<Tracker
+  data={data}
+  hoverEffect
+  defaultBackgroundColor="bg-muted"
+/>
+```
+
+## Notes
+
+- `color` must be Tailwind class (e.g. `bg-emerald-600`), not hex.
+- Wrap in `TooltipProvider` for tooltips.
+- Blocks without `color` use `defaultBackgroundColor`.

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.