@nqlib/nqui 0.3.2 → 0.4.0

package/docs/components/nqui-carousel.md

@@ -0,0 +1,22 @@
+# nqui Carousel
+
+> Carousel. CarouselContent, CarouselItem, CarouselPrevious, CarouselNext.
+
+## Import
+
+```tsx
+import { Carousel, CarouselContent, CarouselItem, CarouselPrevious, CarouselNext } from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<Carousel>
+  <CarouselContent>
+    <CarouselItem>Slide 1</CarouselItem>
+    <CarouselItem>Slide 2</CarouselItem>
+  </CarouselContent>
+  <CarouselPrevious />
+  <CarouselNext />
+</Carousel>
+```

package/docs/components/nqui-checkbox.md

@@ -0,0 +1,34 @@
+# nqui Checkbox
+
+> Enhanced checkbox. Variants: square (default), round (circular).
+
+## Import
+
+```tsx
+import { Checkbox } from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<Checkbox checked={checked} onCheckedChange={setChecked} />
+```
+
+## Variants
+
+```tsx
+<Checkbox variant="square" />
+<Checkbox variant="round" />
+```
+
+## Indeterminate
+
+```tsx
+<Checkbox checked="indeterminate" onCheckedChange={...} />
+```
+
+## Notes
+
+- 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-code-block.md

@@ -0,0 +1,41 @@
+# nqui CodeBlock
+
+> Syntax-highlighted code. Multi-file tabs, copy button. From `@nqlib/nqcode`.
+
+## Import
+
+```tsx
+import {
+  CodeBlock, CodeBlockHeader, CodeBlockFiles, CodeBlockFilename,
+  CodeBlockCopyButton, CodeBlockBody, CodeBlockItem, CodeBlockContent
+} from "@nqlib/nqcode"
+```
+
+Requires: `@nqlib/nqui`, `shiki`, `@shikijs/transformers`
+
+## Basic
+
+```tsx
+<CodeBlock defaultValue="ts" data={[{ language: "ts", filename: "x.ts", code: "..." }]}>
+  <CodeBlockHeader>
+    <CodeBlockFiles>
+      {(item) => <CodeBlockFilename value={item.language}>{item.filename}</CodeBlockFilename>}
+    </CodeBlockFiles>
+    <CodeBlockCopyButton />
+  </CodeBlockHeader>
+  <CodeBlockBody>
+    {(item) => (
+      <CodeBlockItem value={item.language}>
+        <CodeBlockContent language={item.language} syntaxHighlighting>
+          {item.code}
+        </CodeBlockContent>
+      </CodeBlockItem>
+    )}
+  </CodeBlockBody>
+</CodeBlock>
+```
+
+## Notes
+
+- Peer: shiki, @shikijs/transformers for syntax highlighting.
+- CodeBlockContentServer (async/RSC): `import { CodeBlockContentServer } from "@nqlib/nqcode/server"`

package/docs/components/nqui-code-editor.md

@@ -0,0 +1,21 @@
+# nqui CodeEditor
+
+> Animated code editor. Client-side only.
+
+## Import
+
+```tsx
+import { CodeEditor } from "@nqlib/nqcode"
+```
+
+## Basic
+
+```tsx
+<CodeEditor lang="typescript" header dots title="file.ts" copyButton>
+  {`const x = 1`}
+</CodeEditor>
+```
+
+## Notes
+
+- Client-only. Use dynamic import with ssr: false in Next.js.

package/docs/components/nqui-collapsible.md

@@ -0,0 +1,18 @@
+# nqui Collapsible
+
+> Toggle content visibility. CollapsibleTrigger, CollapsibleContent.
+
+## Import
+
+```tsx
+import { Collapsible, CollapsibleTrigger, CollapsibleContent } from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<Collapsible open={open} onOpenChange={setOpen}>
+  <CollapsibleTrigger asChild><Button>Toggle</Button></CollapsibleTrigger>
+  <CollapsibleContent>Content</CollapsibleContent>
+</Collapsible>
+```

package/docs/components/nqui-color-picker.md

@@ -0,0 +1,38 @@
+# nqui ColorPicker
+
+> OKLCH color picker. Popover or inline. Value is OKLCH string.
+
+## Import
+
+```tsx
+import { ColorPicker } from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<ColorPicker
+  value={color}
+  onChange={setColor}
+  variant="popover"
+/>
+```
+
+## Inline
+
+```tsx
+<ColorPicker value={color} onChange={setColor} variant="inline" />
+```
+
+## Value Format
+
+OKLCH string: `"oklch(0.75 0.15 240)"` (L, C, H). Not hex/RGB.
+
+```tsx
+const [color, setColor] = useState("oklch(0.5 0.15 240)")
+```
+
+## Notes
+
+- Store/pass OKLCH. Convert to hex for APIs if needed.
+- Component includes hex display and copy.

package/docs/components/nqui-color-slider.md

@@ -0,0 +1,23 @@
+# nqui ColorSlider
+
+> Slider for hue/saturation/lightness. Used by ColorPicker; usable standalone.
+
+## Import
+
+```tsx
+import { ColorSlider } from "@nqlib/nqui"
+```
+
+## Types
+
+```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} />
+```
+
+## Custom
+
+```tsx
+<ColorSlider sliderType="custom" gradientBackground="..." value={[50]} onValueChange={...} />
+```

package/docs/components/nqui-combobox.md

@@ -0,0 +1,73 @@
+# nqui Combobox
+
+> **Searchable** select. Single or multi-select. Use when user types to filter options.
+
+## When to Use
+
+- **Selection:** Single or multiple
+- **Key feature:** User searches/filters options by typing
+- **Options:** Many (dozens, hundreds)
+
+**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.
+
+## Import
+
+```tsx
+import {
+  Combobox, ComboboxInput, ComboboxContent, ComboboxList,
+  ComboboxItem, ComboboxEmpty, ComboboxChips, ComboboxChip,
+  ComboboxTrigger, ComboboxValue, ComboboxCollection, ComboboxGroup,
+  ComboboxLabel, ComboboxSeparator
+} from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<Combobox options={items} value={value} onChange={setValue}>
+  <ComboboxInput placeholder="Search..." />
+  <ComboboxContent>
+    <ComboboxList>
+      {items.map((item) => (
+        <ComboboxItem key={item.value} value={item.value}>{item.label}</ComboboxItem>
+      ))}
+    </ComboboxList>
+    <ComboboxEmpty>No results</ComboboxEmpty>
+  </ComboboxContent>
+</Combobox>
+```
+
+## showClear
+
+```tsx
+<Combobox showClear ... />
+```
+
+## Multi-select chips
+
+```tsx
+<Combobox multiSelect value={selected} onChange={setSelected}>
+  <ComboboxChips placeholder="Select...">
+    {(vals) => vals.map((v) => <ComboboxChip key={v} value={v} onRemove={...} />)}
+  </ComboboxChips>
+  ...
+</Combobox>
+```
+
+## Groups
+
+```tsx
+<ComboboxCollection>
+  <ComboboxGroup>
+    <ComboboxLabel>Group A</ComboboxLabel>
+    <ComboboxItem value="a">A</ComboboxItem>
+  </ComboboxGroup>
+  <ComboboxSeparator />
+  ...
+</ComboboxCollection>
+```
+
+## Notes
+
+- Injects CSS at mount; client-only in SSR.
+- `useComboboxAnchor` for PopoverAnchor positioning.

package/docs/components/nqui-command-palette.md

@@ -0,0 +1,29 @@
+# nqui CommandPalette
+
+> Global command palette (Cmd+K). Wraps Command with shortcut.
+
+## Import
+
+```tsx
+import { CommandPalette } from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<CommandPalette open={open} onOpenChange={setOpen} shortcutEnabled>
+  <CommandInput placeholder="Search..." />
+  <CommandList>...</CommandList>
+</CommandPalette>
+```
+
+## Programmatic Only
+
+```tsx
+<CommandPalette shortcutEnabled={false} ... />
+```
+
+## Notes
+
+- Keyboard listener on window. May conflict with other global shortcuts.
+- Custom title/description for accessibility.

package/docs/components/nqui-command.md

@@ -0,0 +1,39 @@
+# nqui Command
+
+> Command palette filter list. CommandInput, CommandList, CommandEmpty, CommandGroup, CommandItem, CommandSeparator, CommandShortcut. CommandDialog for modal.
+
+## Import
+
+```tsx
+import {
+  Command, CommandInput, CommandList, CommandEmpty, CommandGroup,
+  CommandItem, CommandSeparator, CommandShortcut, CommandDialog
+} from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<Command>
+  <CommandInput placeholder="Search..." />
+  <CommandList>
+    <CommandEmpty>No results</CommandEmpty>
+    <CommandGroup heading="Suggestions">
+      <CommandItem>Item</CommandItem>
+    </CommandGroup>
+    <CommandSeparator />
+    <CommandGroup heading="Other">
+      <CommandItem>Other<CommandShortcut>⌘K</CommandShortcut></CommandItem>
+    </CommandGroup>
+  </CommandList>
+</Command>
+```
+
+## CommandDialog
+
+```tsx
+<CommandDialog open={open} onOpenChange={setOpen}>
+  <CommandInput />
+  <CommandList>...</CommandList>
+</CommandDialog>
+```

package/docs/components/nqui-context-menu.md

@@ -0,0 +1,33 @@
+# nqui ContextMenu
+
+> Right-click menu. Checkbox, radio, submenus, shortcuts.
+
+## Import
+
+```tsx
+import {
+  ContextMenu, ContextMenuTrigger, ContextMenuContent,
+  ContextMenuItem, ContextMenuCheckboxItem, ContextMenuRadioGroup,
+  ContextMenuRadioItem, ContextMenuSub, ContextMenuSubTrigger,
+  ContextMenuSubContent, ContextMenuShortcut
+} from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<ContextMenu>
+  <ContextMenuTrigger>Right-click here</ContextMenuTrigger>
+  <ContextMenuContent>
+    <ContextMenuItem>Copy</ContextMenuItem>
+    <ContextMenuCheckboxItem checked={x} onCheckedChange={setX}>Option</ContextMenuCheckboxItem>
+    <ContextMenuRadioGroup value={v} onValueChange={setV}>
+      <ContextMenuRadioItem value="a">A</ContextMenuRadioItem>
+    </ContextMenuRadioGroup>
+    <ContextMenuSub>
+      <ContextMenuSubTrigger>More</ContextMenuSubTrigger>
+      <ContextMenuSubContent>...</ContextMenuSubContent>
+    </ContextMenuSub>
+  </ContextMenuContent>
+</ContextMenu>
+```

package/docs/components/nqui-data-table.md

@@ -0,0 +1,46 @@
+# nqui DataTable
+
+> Full-featured data table: sorting, filtering, pagination, row selection, inline editing.
+
+## Import
+
+DataTable is in `packages/nqui/src/components/table/`. For app usage: `import { DataTable } from "@/components/table"`. Requires `@tanstack/react-table` peer. Not currently exported from main `@nqlib/nqui` entry.
+
+## Peer Dependency
+
+```bash
+pnpm add @tanstack/react-table
+```
+
+## Basic
+
+```tsx
+const columns: ColumnDef<User>[] = [
+  { accessorKey: "name", header: "Name" },
+  { accessorKey: "email", header: "Email" },
+]
+<DataTable columns={columns} data={users} />
+```
+
+## Props
+
+| Prop | Default | Use |
+|------|---------|-----|
+| enableSorting | true | Column header sort |
+| enableFiltering | true | Global search |
+| enablePagination | true | Page controls |
+| enableRowSelection | false | Checkboxes |
+| enableEditing | false | Inline edit |
+| pageSize | 10 | Rows per page |
+
+## Use Case
+
+- Admin panels, dashboards
+- Tabular data with sort/filter/paginate
+- When Table primitives aren't enough
+
+## Notes
+
+- DataTable lives in `components/table/`; may require path alias.
+- Uses createColumnHelper, createSelectColumn from data-table-helpers.
+- Keyboard: Arrow keys, Enter for navigation.

package/docs/components/nqui-dialog.md

@@ -0,0 +1,36 @@
+# nqui Dialog
+
+> Modal dialog. Core Radix primitive.
+
+## Import
+
+```tsx
+import { Dialog, DialogTrigger, DialogContent, DialogHeader, DialogTitle, DialogDescription, DialogFooter } from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<Dialog>
+  <DialogTrigger asChild><Button>Open</Button></DialogTrigger>
+  <DialogContent>
+    <DialogHeader>
+      <DialogTitle>Title</DialogTitle>
+      <DialogDescription>Description</DialogDescription>
+    </DialogHeader>
+    <p>Body</p>
+    <DialogFooter>
+      <Button variant="outline">Cancel</Button>
+      <Button>Save</Button>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+```
+
+## Controlled
+
+```tsx
+<Dialog open={open} onOpenChange={setOpen}>
+  ...
+</Dialog>
+```

package/docs/components/nqui-drawer.md

@@ -0,0 +1,27 @@
+# nqui Drawer
+
+> Bottom drawer. DrawerTrigger, DrawerContent, DrawerHeader, DrawerTitle, DrawerDescription, DrawerFooter.
+
+## Import
+
+```tsx
+import {
+  Drawer, DrawerTrigger, DrawerContent, DrawerHeader,
+  DrawerTitle, DrawerDescription, DrawerFooter
+} from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<Drawer>
+  <DrawerTrigger asChild><Button>Open</Button></DrawerTrigger>
+  <DrawerContent>
+    <DrawerHeader>
+      <DrawerTitle>Title</DrawerTitle>
+      <DrawerDescription>Desc</DrawerDescription>
+    </DrawerHeader>
+    <DrawerFooter><Button>Save</Button></DrawerFooter>
+  </DrawerContent>
+</Drawer>
+```

package/docs/components/nqui-dropdown-menu.md

@@ -0,0 +1,56 @@
+# nqui DropdownMenu
+
+> Context menu. Checkbox/radio items, submenus, shortcuts.
+
+## Import
+
+```tsx
+import {
+  DropdownMenu, DropdownMenuTrigger, DropdownMenuContent,
+  DropdownMenuItem, DropdownMenuCheckboxItem, DropdownMenuRadioItem,
+  DropdownMenuRadioGroup, DropdownMenuLabel, DropdownMenuSeparator,
+  DropdownMenuSub, DropdownMenuSubTrigger, DropdownMenuSubContent,
+  DropdownMenuShortcut
+} from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<DropdownMenu>
+  <DropdownMenuTrigger asChild><Button>Open</Button></DropdownMenuTrigger>
+  <DropdownMenuContent>
+    <DropdownMenuItem>Item</DropdownMenuItem>
+    <DropdownMenuSeparator />
+    <DropdownMenuItem>Another</DropdownMenuItem>
+  </DropdownMenuContent>
+</DropdownMenu>
+```
+
+## Checkbox / Radio
+
+```tsx
+<DropdownMenuCheckboxItem checked={x} onCheckedChange={setX}>
+  Toggle
+</DropdownMenuCheckboxItem>
+<DropdownMenuRadioGroup value={v} onValueChange={setV}>
+  <DropdownMenuRadioItem value="a">A</DropdownMenuRadioItem>
+</DropdownMenuRadioGroup>
+```
+
+## Submenu
+
+```tsx
+<DropdownMenuSub>
+  <DropdownMenuSubTrigger>More</DropdownMenuSubTrigger>
+  <DropdownMenuSubContent>
+    <DropdownMenuItem>Sub item</DropdownMenuItem>
+  </DropdownMenuSubContent>
+</DropdownMenuSub>
+```
+
+## Shortcut
+
+```tsx
+<DropdownMenuItem>Save<DropdownMenuShortcut>⌘S</DropdownMenuShortcut></DropdownMenuItem>
+```

package/docs/components/nqui-empty.md

@@ -0,0 +1,22 @@
+# nqui Empty
+
+> Empty state. Header, title, description, media, content.
+
+## Import
+
+```tsx
+import { Empty, EmptyHeader, EmptyTitle, EmptyDescription, EmptyContent, EmptyMedia } from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<Empty>
+  <EmptyHeader>
+    <EmptyTitle>No items</EmptyTitle>
+    <EmptyDescription>Add something to get started</EmptyDescription>
+  </EmptyHeader>
+  <EmptyMedia>{/* icon */}</EmptyMedia>
+  <EmptyContent><Button>Add</Button></EmptyContent>
+</Empty>
+```

package/docs/components/nqui-field.md

@@ -0,0 +1,42 @@
+# nqui Field
+
+> Form field layout. Label, description, error. FieldGroup, FieldSet, FieldLegend.
+
+## Import
+
+```tsx
+import {
+  Field, FieldLabel, FieldDescription, FieldError,
+  FieldGroup, FieldSet, FieldLegend, FieldContent, FieldTitle, FieldSeparator
+} from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<Field>
+  <FieldLabel>Email</FieldLabel>
+  <FieldDescription>We'll never share it</FieldDescription>
+  <Input id="email" />
+  <FieldError>Invalid email</FieldError>
+</Field>
+```
+
+## FieldGroup
+
+```tsx
+<FieldGroup>
+  <Field>...</Field>
+  <FieldSeparator />
+  <Field>...</Field>
+</FieldGroup>
+```
+
+## FieldSet
+
+```tsx
+<FieldSet>
+  <FieldLegend>Section</FieldLegend>
+  <FieldContent>...</FieldContent>
+</FieldSet>
+```

package/docs/components/nqui-frosted-glass.md

@@ -0,0 +1,19 @@
+# nqui FrostedGlass
+
+> Frosted glass blur effect. For sticky headers, overlays.
+
+## Import
+
+```tsx
+import { FrostedGlass } from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<FrostedGlass blur={16} borderRadius={0} />
+```
+
+## Props
+
+blur, borderRadius, opacity. Use in sticky header with z-index.

package/docs/components/nqui-hover-card.md

@@ -0,0 +1,18 @@
+# nqui HoverCard
+
+> Hover panel. HoverCardTrigger, HoverCardContent.
+
+## Import
+
+```tsx
+import { HoverCard, HoverCardTrigger, HoverCardContent } from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<HoverCard>
+  <HoverCardTrigger asChild><span>Hover</span></HoverCardTrigger>
+  <HoverCardContent>Content</HoverCardContent>
+</HoverCard>
+```

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

@@ -0,0 +1,30 @@
+# nqui InputGroup
+
+> Input with prefix/suffix. Use InputGroupAddon + InputGroupText for addons, InputGroupInput for the control.
+
+## Import
+
+```tsx
+import { InputGroup, InputGroupAddon, InputGroupText, InputGroupInput } from "@nqlib/nqui"
+```
+
+## Basic
+
+Wrap addons in `InputGroupAddon` with `align` to control position. Use `InputGroupInput` (not `Input`) so borders and padding align correctly.
+
+```tsx
+<InputGroup>
+  <InputGroupAddon align="inline-start">
+    <InputGroupText>@</InputGroupText>
+  </InputGroupAddon>
+  <InputGroupInput placeholder="Username" />
+</InputGroup>
+<InputGroup>
+  <InputGroupInput placeholder="Amount" />
+  <InputGroupAddon align="inline-end">
+    <InputGroupText>.00</InputGroupText>
+  </InputGroupAddon>
+</InputGroup>
+```
+
+Padding follows design system (px-3, py-1.5) for balanced addons and inputs.