@nqlib/nqui 0.3.2 → 0.4.0

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

@@ -0,0 +1,23 @@
+# nqui InputOTP
+
+> OTP/code input. Group, slots, separator.
+
+## Import
+
+```tsx
+import { InputOTP, InputOTPGroup, InputOTPSlot, InputOTPSeparator } from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<InputOTP value={value} onChange={setValue}>
+  <InputOTPGroup>
+    <InputOTPSlot index={0} />
+    <InputOTPSlot index={1} />
+    <InputOTPSeparator />
+    <InputOTPSlot index={2} />
+    <InputOTPSlot index={3} />
+  </InputOTPGroup>
+</InputOTP>
+```

package/docs/components/nqui-input.md

@@ -0,0 +1,25 @@
+# nqui Input
+
+> Text input. Core component.
+
+## Import
+
+```tsx
+import { Input } from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<Input placeholder="Email" type="email" />
+<Input type="password" disabled />
+```
+
+## With Label
+
+```tsx
+<div>
+  <Label htmlFor="email">Email</Label>
+  <Input id="email" type="email" />
+</div>
+```

package/docs/components/nqui-item.md

@@ -0,0 +1,25 @@
+# nqui Item
+
+> List item layout. Media, content, actions. ItemGroup, ItemSeparator, ItemHeader, ItemFooter.
+
+## Import
+
+```tsx
+import {
+  Item, ItemMedia, ItemContent, ItemActions, ItemTitle, ItemDescription,
+  ItemGroup, ItemSeparator, ItemHeader, ItemFooter
+} from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<Item>
+  <ItemMedia><Avatar /></ItemMedia>
+  <ItemContent>
+    <ItemTitle>Title</ItemTitle>
+    <ItemDescription>Desc</ItemDescription>
+  </ItemContent>
+  <ItemActions><Button>...</Button></ItemActions>
+</Item>
+```

package/docs/components/nqui-kbd.md

@@ -0,0 +1,25 @@
+# nqui Kbd
+
+> Keyboard key indicator for shortcuts.
+
+## Import
+
+```tsx
+import { Kbd } from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+Press <Kbd>⌘</Kbd> + <Kbd>K</Kbd> to open
+<Kbd>Esc</Kbd> to close
+<Kbd>Ctrl</Kbd> + <Kbd>Shift</Kbd> + <Kbd>P</Kbd>
+```
+
+## KbdGroup
+
+```tsx
+import { Kbd } from "@nqlib/nqui"
+// KbdGroup: import from @/components/ui/kbd if needed
+<div><Kbd>Ctrl</Kbd>+<Kbd>K</Kbd></div>
+```

package/docs/components/nqui-label.md

@@ -0,0 +1,16 @@
+# nqui Label
+
+> Form label. Associates with form controls via htmlFor.
+
+## Import
+
+```tsx
+import { Label } from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<Label htmlFor="email">Email</Label>
+<Input id="email" />
+```

package/docs/components/nqui-logo.md

@@ -0,0 +1,16 @@
+# nqui NquiLogo
+
+> Theme-aware logo. Adapts to light/dark.
+
+## Import
+
+```tsx
+import { NquiLogo } from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<NquiLogo />
+<NquiLogo className="size-12" />
+```

package/docs/components/nqui-menubar.md

@@ -0,0 +1,22 @@
+# nqui Menubar
+
+> Horizontal menu bar. MenubarMenu, MenubarTrigger, MenubarContent, MenubarItem.
+
+## Import
+
+```tsx
+import { Menubar, MenubarMenu, MenubarTrigger, MenubarContent, MenubarItem } from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<Menubar>
+  <MenubarMenu>
+    <MenubarTrigger>File</MenubarTrigger>
+    <MenubarContent>
+      <MenubarItem>New</MenubarItem>
+    </MenubarContent>
+  </MenubarMenu>
+</Menubar>
+```

package/docs/components/nqui-native-select.md

@@ -0,0 +1,28 @@
+# nqui NativeSelect
+
+> Native HTML select.
+
+## Import
+
+```tsx
+import { NativeSelect, NativeSelectOption, NativeSelectOptGroup } from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<NativeSelect>
+  <NativeSelectOption value="">Select...</NativeSelectOption>
+  <NativeSelectOption value="1">One</NativeSelectOption>
+</NativeSelect>
+```
+
+## OptGroup
+
+```tsx
+<NativeSelect>
+  <NativeSelectOptGroup label="Group">
+    <NativeSelectOption value="a">A</NativeSelectOption>
+  </NativeSelectOptGroup>
+</NativeSelect>
+```

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

@@ -0,0 +1,25 @@
+# nqui NavigationMenu
+
+> Nav with content panels. NavigationMenuList, NavigationMenuItem, NavigationMenuTrigger, NavigationMenuContent, NavigationMenuLink.
+
+## Import
+
+```tsx
+import {
+  NavigationMenu, NavigationMenuList, NavigationMenuItem,
+  NavigationMenuTrigger, NavigationMenuContent, NavigationMenuLink
+} from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<NavigationMenu>
+  <NavigationMenuList>
+    <NavigationMenuItem>
+      <NavigationMenuTrigger>Item</NavigationMenuTrigger>
+      <NavigationMenuContent>Panel content</NavigationMenuContent>
+    </NavigationMenuItem>
+  </NavigationMenuList>
+</NavigationMenu>
+```

package/docs/components/nqui-pagination.md

@@ -0,0 +1,25 @@
+# nqui Pagination
+
+> Pagination. PaginationContent, PaginationItem, PaginationLink, PaginationPrevious, PaginationNext, PaginationEllipsis.
+
+## Import
+
+```tsx
+import {
+  Pagination, PaginationContent, PaginationItem, PaginationLink,
+  PaginationPrevious, PaginationNext, PaginationEllipsis
+} from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<Pagination>
+  <PaginationContent>
+    <PaginationItem><PaginationPrevious href="#" /></PaginationItem>
+    <PaginationItem><PaginationLink href="#">1</PaginationLink></PaginationItem>
+    <PaginationItem><PaginationEllipsis /></PaginationItem>
+    <PaginationItem><PaginationNext href="#" /></PaginationItem>
+  </PaginationContent>
+</Pagination>
+```

package/docs/components/nqui-popover.md

@@ -0,0 +1,34 @@
+# nqui Popover
+
+> Floating panel. PopoverAnchor decouples trigger from anchor position.
+
+## Import
+
+```tsx
+import { Popover, PopoverTrigger, PopoverContent, PopoverAnchor } from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<Popover>
+  <PopoverTrigger asChild><Button>Open</Button></PopoverTrigger>
+  <PopoverContent>Content</PopoverContent>
+</Popover>
+```
+
+## PopoverAnchor
+
+Position relative to anchor, not trigger:
+
+```tsx
+<Popover>
+  <PopoverAnchor asChild><div ref={anchorRef}>Anchor area</div></PopoverAnchor>
+  <PopoverTrigger asChild><Button>Open</Button></PopoverTrigger>
+  <PopoverContent>Content</PopoverContent>
+</Popover>
+```
+
+## Notes
+
+- PopoverAnchor: content positions by anchor, not trigger.

package/docs/components/nqui-progress.md

@@ -0,0 +1,22 @@
+# nqui Progress
+
+> Progress bar. Dash and solid variants.
+
+## Import
+
+```tsx
+import { Progress } from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<Progress value={60} />
+```
+
+## Variants
+
+```tsx
+<Progress value={60} variant="solid" />
+<Progress value={60} variant="dash" />
+```

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

@@ -0,0 +1,42 @@
+# nqui RadioGroup
+
+> **1 selection** from options. Form context. Stacked or horizontal.
+
+## When to Use
+
+- **Selection:** Single
+- **Context:** Form (settings, preferences)
+- **Layout:** Stacked list or horizontal row
+
+**Choose RadioGroup when:** Form with single-choice question. Traditional form UX. **Do not use RadioGroup for toolbars or inline UI** — use ToggleGroup instead. Use Select for 5+ options or tight space.
+
+## Import
+
+```tsx
+import { RadioGroup, RadioGroupItem } from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<RadioGroup value={value} onValueChange={setValue}>
+  <RadioGroupItem value="a" /> A
+  <RadioGroupItem value="b" /> B
+</RadioGroup>
+```
+
+## Variants
+
+```tsx
+<RadioGroup variant="animated" />
+<RadioGroup variant="sliding" />
+<RadioGroup variant="bar-left" />
+<RadioGroup variant="bar-right" />
+```
+
+## Orientation / Disabled
+
+```tsx
+<RadioGroup orientation="horizontal" />
+<RadioGroupItem value="a" disabled />
+```

package/docs/components/nqui-rating.md

@@ -0,0 +1,35 @@
+# nqui Rating
+
+> Star rating. Half-star, maxRating, tooltipContent. Injects style.
+
+## Import
+
+```tsx
+import { Rating } from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<Rating value={3.5} onChange={setVal} />
+```
+
+## maxRating / starSize
+
+```tsx
+<Rating value={val} onChange={setVal} maxRating={10} starSize={24} />
+```
+
+## tooltipContent
+
+```tsx
+<Rating
+  value={val}
+  onChange={setVal}
+  tooltipContent={(v) => `${v} stars`}
+/>
+```
+
+## Notes
+
+- Injects inline style for SVG mask. Client-only in SSR.

package/docs/components/nqui-resizable.md

@@ -0,0 +1,23 @@
+# nqui Resizable
+
+> Resizable panels. Container: ResizablePanelGroup. Peer: react-resizable-panels.
+
+## Import
+
+```tsx
+import { ResizablePanelGroup, ResizablePanel, ResizableHandle } from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<ResizablePanelGroup direction="horizontal">
+  <ResizablePanel defaultSize={25}>Panel 1</ResizablePanel>
+  <ResizableHandle />
+  <ResizablePanel defaultSize={75}>Panel 2</ResizablePanel>
+</ResizablePanelGroup>
+```
+
+## Notes
+
+- Peer: `react-resizable-panels`.

package/docs/components/nqui-sandbox.md

@@ -0,0 +1,27 @@
+# nqui Sandbox
+
+> Live code playground. SandboxProvider, SandboxLayout, SandboxCodeEditor, SandboxPreview. Peer: @codesandbox/sandpack-react.
+
+## Import
+
+```tsx
+import {
+  SandboxProvider, SandboxLayout, SandboxCodeEditor,
+  SandboxPreview
+} from "@nqlib/nqcode"
+```
+
+## Basic
+
+```tsx
+<SandboxProvider theme="dark" template="react" files={{ "/App.tsx": "..." }}>
+  <SandboxLayout>
+    <SandboxCodeEditor showTabs />
+    <SandboxPreview />
+  </SandboxLayout>
+</SandboxProvider>
+```
+
+## Notes
+
+- Peer: @codesandbox/sandpack-react. Heavy dependency.

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

@@ -0,0 +1,32 @@
+# nqui ScrollArea
+
+> Custom scrollbar. fadeMask (enhanced), horizontal scroll.
+
+## Import
+
+```tsx
+import { ScrollArea, ScrollBar } from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<ScrollArea className="h-[200px]">
+  <div>Content</div>
+  <ScrollBar orientation="vertical" />
+</ScrollArea>
+```
+
+## Horizontal
+
+```tsx
+<ScrollArea orientation="horizontal">
+  <div className="flex gap-4 min-w-max">...</div>
+</ScrollArea>
+```
+
+## fadeMask
+
+```tsx
+<ScrollArea fadeMask>...</ScrollArea>
+```

package/docs/components/nqui-select.md

@@ -0,0 +1,53 @@
+# nqui Select
+
+> **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
+
+```tsx
+import { Select, SelectTrigger, SelectValue, SelectContent, SelectItem, SelectGroup, SelectLabel, SelectSeparator } from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<Select value={value} onValueChange={setValue}>
+  <SelectTrigger><SelectValue placeholder="Pick" /></SelectTrigger>
+  <SelectContent>
+    <SelectItem value="a">A</SelectItem>
+    <SelectItem value="b">B</SelectItem>
+  </SelectContent>
+</Select>
+```
+
+## Grouped
+
+```tsx
+<SelectContent>
+  <SelectGroup>
+    <SelectLabel>Fruits</SelectLabel>
+    <SelectItem value="apple">Apple</SelectItem>
+  </SelectGroup>
+  <SelectSeparator />
+  <SelectGroup>
+    <SelectLabel>Veggies</SelectLabel>
+    <SelectItem value="carrot">Carrot</SelectItem>
+  </SelectGroup>
+</SelectContent>
+```
+
+## 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

@@ -0,0 +1,48 @@
+# nqui Separator
+
+> Horizontal or vertical divider with multiple visual variants.
+
+## Import
+
+```tsx
+import { Separator } from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<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-sheet.md

@@ -0,0 +1,27 @@
+# nqui Sheet
+
+> Side panel. SheetTrigger, SheetContent, SheetHeader, SheetTitle, SheetDescription, SheetFooter. side: top|right|bottom|left.
+
+## Import
+
+```tsx
+import {
+  Sheet, SheetTrigger, SheetContent, SheetHeader,
+  SheetTitle, SheetDescription, SheetFooter
+} from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<Sheet>
+  <SheetTrigger asChild><Button>Open</Button></SheetTrigger>
+  <SheetContent side="right">
+    <SheetHeader>
+      <SheetTitle>Title</SheetTitle>
+      <SheetDescription>Desc</SheetDescription>
+    </SheetHeader>
+    ...
+  </SheetContent>
+</Sheet>
+```

package/docs/components/nqui-sidebar.md

@@ -0,0 +1,45 @@
+# nqui Sidebar
+
+> App sidebar. Collapsible. SidebarProvider must wrap entire layout.
+
+## Import
+
+```tsx
+import {
+  SidebarProvider, Sidebar, SidebarTrigger, SidebarInset,
+  SidebarHeader, SidebarContent, SidebarGroup, SidebarGroupLabel,
+  SidebarGroupContent, SidebarMenu, SidebarMenuItem, SidebarMenuButton,
+  SidebarRail, SidebarSeparator
+} from "@nqlib/nqui"
+```
+
+## Layout
+
+```tsx
+<SidebarProvider>
+  <Sidebar collapsible="icon">
+    <SidebarHeader>...</SidebarHeader>
+    <SidebarContent>
+      <SidebarGroup>
+        <SidebarGroupLabel>Label</SidebarGroupLabel>
+        <SidebarGroupContent>
+          <SidebarMenu>
+            <SidebarMenuItem><SidebarMenuButton>Item</SidebarMenuButton></SidebarMenuItem>
+          </SidebarMenu>
+        </SidebarGroupContent>
+      </SidebarGroup>
+    </SidebarContent>
+    <SidebarRail />
+  </Sidebar>
+  <SidebarInset>
+    <SidebarTrigger />
+    {/* Main content */}
+  </SidebarInset>
+</SidebarProvider>
+```
+
+## Notes
+
+- **Critical:** SidebarProvider wraps full layout (sidebar + content), not just Sidebar.
+- collapsible: "offcanvas" | "icon" | "none".
+- Sidebar uses fixed positioning; one per app.

package/docs/components/nqui-skeleton.md

@@ -0,0 +1,15 @@
+# nqui Skeleton
+
+> Loading placeholder. Core.
+
+## Import
+
+```tsx
+import { Skeleton } from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<Skeleton className="h-12 w-full" />
+```

package/docs/components/nqui-slider.md

@@ -0,0 +1,16 @@
+# nqui Slider
+
+> Range slider. Supports single and range values.
+
+## Import
+
+```tsx
+import { Slider } from "@nqlib/nqui"
+```
+
+## Basic
+
+```tsx
+<Slider value={[50]} onValueChange={([v]) => setVal(v)} />
+<Slider value={[20, 80]} onValueChange={setRange} />
+```