# labsUI

> labsUI is a clean, composable React component library with one smooth spring for every motion. You copy components into your project and own the code. Built for Next.js 16 and Tailwind CSS v4; install with npm, pnpm, yarn or Bun (recommended).

## Install

Components are copied into your project (React 19, Tailwind CSS v4, a `@/*` path alias):

```sh
npx @kznlabs/labsui init          # styles, theme, utils, motion provider; imports labsui.css
npx @kznlabs/labsui add button    # a component plus everything it imports
npx @kznlabs/labsui search <words> # find by name, export or intent
npx @kznlabs/labsui view <name>   # exact props, examples, dependencies
npx @kznlabs/labsui diff [name]   # how installed files differ from this version
npx @kznlabs/labsui update [name] # this version's changes, merged with local edits
npx @kznlabs/labsui doctor        # check the setup
npx @kznlabs/labsui mcp           # all of the above as MCP tools (stdio)
```

Every command takes --json. `npx @kznlabs/labsui rules` prints the coding rules for agents.

Registry JSON: https://kznlabs.github.io/labsUI/r/<name>.json, index at https://kznlabs.github.io/labsUI/r/index.json.

Import primitives from `@/components/ui/<file>`. All motion uses one spring: { type: "spring", stiffness: 400, damping: 30 }.

## Components
### Button (button.tsx)
Five variants, four sizes, spring press feedback, an animated loading spinner and in-place success state, a two-step confirm that swaps the label on first click, and a configurable swap direction. Width stays fixed to the longest label.
Docs: https://kznlabs.github.io/labsUI/components/button (Markdown: https://kznlabs.github.io/labsUI/components/button.md)
```tsx
<Button variant="destructive" confirmLabel="Yes, delete my account" onClick={remove}>Delete account</Button>
```
Props:
- <Button>: children?: ReactNode; confirmLabel?: ReactNode; confirmTimeout?: number = 3000; loading?: boolean = false; loadingLabel?: ReactNode; size?: "default" | "sm" | "lg" | "icon"; status?: ButtonStatus = "idle"; successLabel?: ReactNode; swap?: SwapDirection = "left"; variant?: "default" | "secondary" | "outline" | "ghost" | "destructive"
- type ButtonStatus = "idle" | "loading" | "success"
- type SwapDirection = "left" | "right" | "up" | "down"

### Badge & Pill (badge.tsx)
Minimal status tags. Rounded badge or fully rounded pill, with optional dot. pulse adds an expanding live-status ring.
Docs: https://kznlabs.github.io/labsUI/components/badge (Markdown: https://kznlabs.github.io/labsUI/components/badge.md)
```tsx
<Badge variant="success" shape="pill" dot pulse>Live</Badge>
```
Props:
- <Badge> (+ <span> props): dot?: boolean; pulse?: boolean; shape?: "badge" | "pill" = "badge"; variant?: "default" | "secondary" | "outline" | "destructive" | "success" = "default"

### Forms (input.tsx · textarea.tsx · label.tsx · switch.tsx)
Input, Textarea, Label and Switch: smooth focus rings, native :user-invalid validation (red only after interaction), aria-invalid, auto-growing textarea with an optional character count, and a spring switch.
Docs: https://kznlabs.github.io/labsUI/components/forms (Markdown: https://kznlabs.github.io/labsUI/components/forms.md)
```tsx
<Label htmlFor="email">Email</Label><Input id="email" type="email" aria-invalid={err} />
```
Props:
- <Input> (+ <input> props)
- <Textarea> (+ <textarea> props): showCount?: boolean
- <Label> (+ <label> props)
- <Switch> (+ <input> props): checked?: boolean; defaultChecked?: boolean = false; onCheckedChange?: (checked: boolean) => void

### Card (card.tsx)
Composable surface: header, title, description, content and footer. Optional glass.
Docs: https://kznlabs.github.io/labsUI/components/card (Markdown: https://kznlabs.github.io/labsUI/components/card.md)
```tsx
<Card><CardHeader><CardTitle>Revenue</CardTitle></CardHeader><CardContent>…</CardContent></Card>
```
Props:
- <Card> (+ <div> props): glass?: boolean
- <CardHeader> (+ <div> props)
- <CardTitle> (+ <h3> props): as?: "h2" | "h3" | "h4" | "h5" | "h6" | "p" = "h3"
- <CardDescription> (+ <p> props)
- <CardContent> (+ <div> props)
- <CardFooter> (+ <div> props)

### Avatar (avatar.tsx)
Image with initials fallback on error, three sizes and online/away/busy/offline dots.
Docs: https://kznlabs.github.io/labsUI/components/avatar (Markdown: https://kznlabs.github.io/labsUI/components/avatar.md)
```tsx
<Avatar src={url} alt="Jane Doe" status="online" size="lg" />
```
Props:
- <Avatar>: alt: string; fallback?: ReactNode; size?: "sm" | "default" | "lg" = "default"; src?: string; status?: "online" | "away" | "busy" | "offline"

### Accordion (accordion.tsx)
Single or multiple panels with spring height animation. Closed content stays in the DOM for SEO.
Docs: https://kznlabs.github.io/labsUI/components/accordion (Markdown: https://kznlabs.github.io/labsUI/components/accordion.md)
```tsx
<Accordion type="single" defaultValue="a"><AccordionItem value="a"><AccordionTrigger>Q</AccordionTrigger><AccordionContent>A</AccordionContent></AccordionItem></Accordion>
```
Props:
- <Accordion>: children: ReactNode; collapsible?: boolean; defaultValue?: string | string[]; onValueChange?: ((value: string) => void) | ((value: string[]) => void); type?: "single" | "multiple"; value?: string | string[]
- <AccordionItem>: children: ReactNode; value: string
- <AccordionTrigger>: children: ReactNode; as?: "h2" | "h3" | "h4" | "h5" | "h6" = "h3"
- <AccordionContent>: children: ReactNode

### Message Bubble (message-bubble.tsx)
User/assistant chat bubbles with avatar slot, streaming dots and copyable code blocks.
Docs: https://kznlabs.github.io/labsUI/components/chat (Markdown: https://kznlabs.github.io/labsUI/components/chat.md)
```tsx
<MessageBubble from="assistant" avatar={<Avatar … />} streaming>…<Code code={src} language="tsx" /></MessageBubble>
```
Props:
- <MessageBubble>: from: "user" | "assistant"; avatar?: ReactNode; children?: ReactNode; name?: string; streaming?: boolean; time?: string

### Dialog (dialog.tsx)
Portal modal with blurred backdrop, spring scale-in, focus trap, Esc and scroll lock.
Docs: https://kznlabs.github.io/labsUI/components/dialog (Markdown: https://kznlabs.github.io/labsUI/components/dialog.md)
```tsx
<Dialog><DialogTrigger>Open</DialogTrigger><DialogContent><DialogHeader><DialogTitle>…</DialogTitle></DialogHeader></DialogContent></Dialog>
```
Props:
- <Dialog>: children: ReactNode; defaultOpen?: boolean = false; onOpenChange?: (open: boolean) => void; open?: boolean
- <DialogTrigger> (+ Button props): children?: ReactNode; confirmLabel?: ReactNode; confirmTimeout?: number; loading?: boolean; loadingLabel?: ReactNode; size?: "default" | "sm" | "lg" | "icon"; status?: ButtonStatus; successLabel?: ReactNode; swap?: SwapDirection; variant?: "default" | "secondary" | "outline" | "ghost" | "destructive"
- <DialogClose> (+ Button props): children?: ReactNode; confirmLabel?: ReactNode; confirmTimeout?: number; loading?: boolean; loadingLabel?: ReactNode; size?: "default" | "sm" | "lg" | "icon"; status?: ButtonStatus; successLabel?: ReactNode; swap?: SwapDirection; variant?: "default" | "secondary" | "outline" | "ghost" | "destructive" = "outline"
- <DialogContent>: children: ReactNode; alert?: boolean = false; showClose?: boolean = !alert
- <DialogHeader> (+ <div> props)
- <DialogFooter> (+ <div> props)
- <DialogTitle> (+ <h2> props)
- <DialogDescription> (+ <p> props)
- `useDialog() => Ctx`
- `useModal() => RefObject<HTMLDivElement | null>`
- type Ctx = { open: boolean; setOpen: (open: boolean) => void; titleId: string; descId: string }

### Toast (toast.tsx)
Stacked notifications. Hover to expand, swipe to dismiss, timers pause on hover.
Docs: https://kznlabs.github.io/labsUI/components/toast (Markdown: https://kznlabs.github.io/labsUI/components/toast.md)
```tsx
toast.success("Saved", { description: "All changes synced", action: { label: "Undo", onClick } })
```
Props:
- <Toaster>
- `toast(title: ReactNode, opts?: Partial<Omit<ToastData, "id" | "title">>) => number`
- type ToastData = { id: number; title: ReactNode; description?: ReactNode; variant: Variant; duration: number; action?: { label: string; onClick: () => void }; }

### AppWindow (app-window.tsx · segmented-tabs.tsx)
Window container with close / minimize / zoom controls, title, custom header slot and actions. SegmentedTabs is the compact view switcher for its title bar.
Docs: https://kznlabs.github.io/labsUI/components/app-window (Markdown: https://kznlabs.github.io/labsUI/components/app-window.md)
```tsx
<AppWindow title="Preview" header={<SegmentedTabs label="Views" items={views} value={view} onChange={setView} />} actions={<Button size="sm" />} onClose={close}>…</AppWindow>
```
Props:
- <AppWindow> (+ <div> props): actions?: ReactNode; bodyClassName?: string; glass?: boolean; header?: ReactNode; onClose?: () => void; onMaximize?: () => void; onMinimize?: () => void; title?: ReactNode
- <SegmentedTabs>: items: readonly string[]; label: string; onChange: (item: string) => void; value: string

### Theme Toggle (theme-toggle.tsx)
Light/dark icon switch with spring rotate-swap; follows the OS until first use.
Docs: https://kznlabs.github.io/labsUI/components/theme-toggle (Markdown: https://kznlabs.github.io/labsUI/components/theme-toggle.md)
```tsx
<ThemeToggle />
```
Props:
- <ThemeToggle>

### Custom Cursor (custom-cursor.tsx)
Optional spring cursor that expands over interactive elements. Off on touch and reduced motion.
Docs: https://kznlabs.github.io/labsUI/components/cursor (Markdown: https://kznlabs.github.io/labsUI/components/cursor.md)
```tsx
{enabled && <CustomCursor />}
```
Props:
- <CustomCursor>

### CountTo (count-to.tsx)
Springs a number up from a start value once it scrolls into view. Prefix, suffix, decimals and locale.
Docs: https://kznlabs.github.io/labsUI/components/count-to (Markdown: https://kznlabs.github.io/labsUI/components/count-to.md)
```tsx
<CountTo to={48290} prefix="$" />
```
Props:
- <CountTo>: to: number; decimals?: number = 0; from?: number = 0; locale?: string = "en-US"; prefix?: string = ""; suffix?: string = ""

### Reveal (reveal.tsx)
Scroll reveal: content fades and rises on a spring the first time it enters the viewport.
Docs: https://kznlabs.github.io/labsUI/components/reveal (Markdown: https://kznlabs.github.io/labsUI/components/reveal.md)
```tsx
<Reveal delay={0.1}><Card>…</Card></Reveal>
```
Props:
- <Reveal>: delay?: number = 0; y?: number = 24

### AvatarGroup (avatar-group.tsx)
Overlapping avatars with a +N overflow chip. Hover gently enlarges the avatar on a spring, keeping stack order.
Docs: https://kznlabs.github.io/labsUI/components/avatar-group (Markdown: https://kznlabs.github.io/labsUI/components/avatar-group.md)
```tsx
<AvatarGroup users={team} max={4} size="lg" />
```
Props:
- <AvatarGroup>: users: GroupUser[]; max?: number = 4; size?: "sm" | "default" | "lg" = "default"
- type GroupUser = { alt: string; src?: string; id?: string; }

### Quote (quote.tsx)
Semantic figure, blockquote and figcaption. Plain, card and large variants, with author, subtitle, avatar, lang, typewriter and textSwap.
Docs: https://kznlabs.github.io/labsUI/components/quote (Markdown: https://kznlabs.github.io/labsUI/components/quote.md)
```tsx
<Quote variant="card" author="Adam Mickiewicz" subtitle="Pan Tadeusz · tr. G. R. Noyes">Lithuania, my country, thou art like health; how much thou shouldst be prized only he can learn who has lost thee.</Quote>
```
Props:
- <Quote>: children: ReactNode; author?: string; avatar?: ReactNode; lang?: string; subtitle?: string; textSwap?: readonly string[] | { items: readonly string[]; interval?: number | undefined; direction?: "down" | "fade" | "up" | undefined; }; typewriter?: boolean | { speed?: number | undefined; delay?: number | undefined; cursor?: boolean | undefined; }; variant?: "plain" | "card" | "large" = "plain"

### Menubar (menubar.tsx)
Desktop-style menu bar on the WAI-ARIA menubar pattern: one menu open at a time, hovering the next title while one is open switches to it, ← → walk the bar with or without a menu open, one Tab stop. A single highlight springs between titles; menus reuse every DropdownMenu item.
Docs: https://kznlabs.github.io/labsUI/components/menubar (Markdown: https://kznlabs.github.io/labsUI/components/menubar.md)
```tsx
<Menubar aria-label="Editor"><MenubarMenu><MenubarTrigger>File</MenubarTrigger><MenubarContent><MenubarItem shortcut="⌘N" onSelect={create}>New</MenubarItem></MenubarContent></MenubarMenu></Menubar>
```
Props:
- <Menubar> (+ <div> props)
- <MenubarContent>: children: ReactNode; align?: "start" | "end" = "start"
- <MenubarItem>: children: ReactNode; disabled?: boolean; onSelect?: () => void; shortcut?: string; variant?: "default" | "destructive" = "default"
- <MenubarCheckboxItem>: checked: boolean; children: ReactNode; onCheckedChange: (checked: boolean) => void; disabled?: boolean; shortcut?: string
- <MenubarRadioGroup>: children: ReactNode; onValueChange: (value: string) => void; value: string
- <MenubarRadioItem>: children: ReactNode; value: string; disabled?: boolean
- <MenubarLabel> (+ <div> props)
- <MenubarSeparator>
- <MenubarMenu>: children: ReactNode; value?: string
- <MenubarTrigger> (+ <button> props)

### Navigation Menu (navigation-menu.tsx)
Website top navigation on the APG disclosure pattern: plain links and panels of rich links. Hover opens after a beat, then sliding along the bar switches panels at once; every panel shares one viewport that springs to the next panel's size and position while the content slides in from the side you moved toward. Click, Enter, ↓, ← → and Esc work; closed panels keep their links in the HTML for crawlers.
Docs: https://kznlabs.github.io/labsUI/components/navigation-menu (Markdown: https://kznlabs.github.io/labsUI/components/navigation-menu.md)
```tsx
<NavigationMenu aria-label="Main"><NavigationMenuList><NavigationMenuItem><NavigationMenuTrigger>Products</NavigationMenuTrigger><NavigationMenuContent className="w-80"><NavigationMenuLink href="/bot" icon={<Bot />} title="Discord bot" description="Moderation and clips" /></NavigationMenuContent></NavigationMenuItem><NavigationMenuItem><NavigationMenuLink href="/blog" active>Blog</NavigationMenuLink></NavigationMenuItem></NavigationMenuList></NavigationMenu>
```
Props:
- <NavigationMenu> (+ <nav> props): defaultValue?: string = ""; onValueChange?: (value: string) => void; value?: string
- <NavigationMenuList> (+ <ul> props)
- <NavigationMenuItem> (+ <li> props): value?: string | (readonly string[] & string)
- <NavigationMenuTrigger> (+ <button> props)
- <NavigationMenuContent> (+ <div> props)
- <NavigationMenuLink> (+ <a> props): active?: boolean; description?: ReactNode; icon?: ReactNode; title?: string

### Breadcrumb (breadcrumb.tsx)
Navigation trail from a list of items: links up to the current page, which is marked for assistive tech. Server-safe, custom separator.
Docs: https://kznlabs.github.io/labsUI/components/breadcrumb (Markdown: https://kznlabs.github.io/labsUI/components/breadcrumb.md)
```tsx
<Breadcrumb items={[{ label: "Home", href: "/" }, { label: "Components" }]} />
```
Props:
- <Breadcrumb> (+ <nav> props): items: Crumb[]; separator?: ReactNode
- type Crumb = { label: ReactNode; href?: string; onClick?: MouseEventHandler<HTMLAnchorElement>; }

### Button Group (button-group.tsx)
Joins buttons into one strip that shares borders, corners and active states. Horizontal or vertical.
Docs: https://kznlabs.github.io/labsUI/components/button-group (Markdown: https://kznlabs.github.io/labsUI/components/button-group.md)
```tsx
<ButtonGroup><Button variant="outline">Years</Button><Button variant="default">Months</Button></ButtonGroup>
```
Props:
- <ButtonGroup> (+ <div> props): attached?: boolean = true; orientation?: "horizontal" | "vertical" = "horizontal"

### Collapsible (collapsible.tsx)
A single show/hide region with a spring height animation and rotating chevron. Controlled or uncontrolled; closed content stays in the DOM for SEO.
Docs: https://kznlabs.github.io/labsUI/components/collapsible (Markdown: https://kznlabs.github.io/labsUI/components/collapsible.md)
```tsx
<Collapsible><CollapsibleTrigger>Show more</CollapsibleTrigger><CollapsibleContent>…</CollapsibleContent></Collapsible>
```
Props:
- <Collapsible>: children: ReactNode; defaultOpen?: boolean = false; onOpenChange?: (open: boolean) => void; open?: boolean
- <CollapsibleTrigger> (+ <button> props): chevron?: boolean = true
- <CollapsibleContent>: children: ReactNode

### Pagination (pagination.tsx)
Server-safe page links from page and total: previous/next, ellipsis gaps and a sliding active pill, with numbers that swipe the way you moved. Links by default; buttons with onPageChange. The row keeps a fixed width so it never jumps.
Docs: https://kznlabs.github.io/labsUI/components/pagination (Markdown: https://kznlabs.github.io/labsUI/components/pagination.md)
```tsx
<Pagination page={2} total={12} href={(p) => `?page=${p}`} />
```
Props:
- <Pagination> (+ <nav> props): page: number; total: number; href?: (page: number) => string = (page) => `?page=${page}`; labels?: { previous?: ReactNode; next?: ReactNode; }; onPageChange?: (page: number) => void; siblings?: number = 1
- `pageRange(page: number, total: number, siblings?: number) => (number | "…")[]`

### Sidebar (sidebar.tsx)
App navigation from data: header, groups (optionally foldable), badges and pinned footer entries. Collapses to an icon rail on a spring (⌘B / Ctrl+B) with labels kept for assistive tech; below md it is a left drawer.
Docs: https://kznlabs.github.io/labsUI/components/sidebar (Markdown: https://kznlabs.github.io/labsUI/components/sidebar.md)
```tsx
<SidebarLayout><Sidebar groups={[{ label: "Server", items: [{ label: "Home", href: "/", icon: <Home /> }] }]} current="/" /><main><SidebarTrigger />…</main></SidebarLayout>
```
Props:
- <Sidebar>: groups: SidebarGroup[]; current?: string; footer?: SidebarItem[]; header?: ReactNode; label?: string = "Sidebar"; onSelect?: (id: string) => void
- <SidebarLayout> (+ <div> props): collapsed?: boolean; defaultCollapsed?: boolean = false; onCollapsedChange?: (collapsed: boolean) => void; shortcut?: boolean = true
- <SidebarTrigger>
- type SidebarItem = { id?: string; label: string; icon?: ReactNode; href?: string; badge?: ReactNode; }
- type SidebarGroup = { label?: string; items: SidebarItem[]; collapsible?: boolean; defaultOpen?: boolean; }

### Accent Picker (accent-picker.tsx)
Accent color row: eight swatches (red to slate) that retint primary, focus rings, selection, switches and checkboxes app-wide. Persisted, applied before paint, or set your own hue with --accent-hue.
Docs: https://kznlabs.github.io/labsUI/components/accent-picker (Markdown: https://kznlabs.github.io/labsUI/components/accent-picker.md)
```tsx
<AccentPicker />
```
Props:
- <AccentPicker>

### Search Input (search-input.tsx)
Search field built on Input: leading icon, spring-in clear button, Esc to clear, and an optional focus shortcut ("/" or mod+k) with a Kbd hint.
Docs: https://kznlabs.github.io/labsUI/components/search-input (Markdown: https://kznlabs.github.io/labsUI/components/search-input.md)
```tsx
<SearchInput value={q} onValueChange={setQ} shortcut="/" placeholder="Search…" />
```
Props:
- <SearchInput> (+ <input> props): defaultValue?: string = ""; label?: string = "Search"; onValueChange?: (value: string) => void; shortcut?: string; value?: string; variant?: "default" | "ghost" = "default"

### Field (field.tsx)
Label, control, description and error as one unit. Controls inside (Input, Textarea, Select, Checkbox, Switch, RadioGroup) get id, aria-describedby, aria-invalid and required automatically; errors spring in and are announced.
Docs: https://kznlabs.github.io/labsUI/components/field (Markdown: https://kznlabs.github.io/labsUI/components/field.md)
```tsx
<Field label="Email" description="We never share it." error={errors.email} required><Input name="email" type="email" /></Field>
```
Props:
- <Field>: children: ReactNode; description?: ReactNode; disabled?: boolean = false; error?: ReactNode; id?: string; label?: ReactNode; orientation?: "vertical" | "horizontal" = "vertical"; required?: boolean = false
- `useFieldControl(props: Props) => Props`

### Input Group (input-group.tsx)
Server-safe wrapper that fuses an Input with icons, text (https://, USD) or buttons into one field with a shared border and focus ring. Clicking an addon focuses the input.
Docs: https://kznlabs.github.io/labsUI/components/input-group (Markdown: https://kznlabs.github.io/labsUI/components/input-group.md)
```tsx
<InputGroup><InputGroupAddon>https://</InputGroupAddon><Input aria-label="Site" /><InputGroupAddon align="end">.dev</InputGroupAddon></InputGroup>
```
Props:
- <InputGroup> (+ <div> props)
- <InputGroupAddon> (+ <div> props): align?: "start" | "end" = "start"

### Checkbox (checkbox.tsx)
Native checkbox with a spring-drawn check mark and an indeterminate state for select-all rows. Controlled or uncontrolled; submits with forms.
Docs: https://kznlabs.github.io/labsUI/components/checkbox (Markdown: https://kznlabs.github.io/labsUI/components/checkbox.md)
```tsx
<Checkbox id="all" checked={all} indeterminate={some} onCheckedChange={toggleAll} />
```
Props:
- <Checkbox> (+ <input> props): checked?: boolean; defaultChecked?: boolean = false; indeterminate?: boolean = false; onCheckedChange?: (checked: boolean) => void

### Radio Group (radio-group.tsx)
Native radios in a fieldset with a legend: browser arrow keys and form submit, a dot that springs in, optional per-option descriptions, vertical or horizontal.
Docs: https://kznlabs.github.io/labsUI/components/radio-group (Markdown: https://kznlabs.github.io/labsUI/components/radio-group.md)
```tsx
<RadioGroup legend="Plan" defaultValue="pro" name="plan"><RadioGroupItem value="free">Free</RadioGroupItem><RadioGroupItem value="pro" description="Unlimited clips">Pro</RadioGroupItem></RadioGroup>
```
Props:
- <RadioGroup> (+ <fieldset> props): aria-invalid?: boolean; defaultValue?: string = ""; legend?: ReactNode; name?: string; onValueChange?: (value: string) => void; orientation?: "vertical" | "horizontal" = "vertical"; value?: string
- <RadioGroupItem>: children: ReactNode; value: string; description?: ReactNode; disabled?: boolean

### Slider (slider.tsx)
Slider over native range inputs: thin accent track, white knob that lifts while held. One value or two for a range; keyboard, forms, touch and Field wiring come from the platform.
Docs: https://kznlabs.github.io/labsUI/components/slider (Markdown: https://kznlabs.github.io/labsUI/components/slider.md)
```tsx
<Slider value={price} onValueChange={setPrice} min={0} max={250} step={5} />
```
Props:
- <Slider>: aria-describedby?: string; aria-invalid?: boolean; defaultValue?: number[]; disabled?: boolean; id?: string; labels?: string[]; max?: number; min?: number; name?: string; onValueChange?: (value: number[]) => void; step?: number; value?: number[]

### Toggle Group (toggle-group.tsx)
Segmented control of toggle buttons. Single mode slides one pill to the pressed item (view mode, billing period); multiple mode toggles items independently (bold, italic). Arrow keys move between items.
Docs: https://kznlabs.github.io/labsUI/components/toggle-group (Markdown: https://kznlabs.github.io/labsUI/components/toggle-group.md)
```tsx
<ToggleGroup aria-label="View" value={view} onValueChange={setView}><ToggleGroupItem value="grid">Grid</ToggleGroupItem><ToggleGroupItem value="list">List</ToggleGroupItem></ToggleGroup>
```
Props:
- <ToggleGroup> (+ <div> props): defaultValue?: string | string[]; onValueChange?: ((value: string) => void) | ((value: string[]) => void); size?: "sm" | "default"; type?: "single" | "multiple"; value?: string | string[]
- <ToggleGroupItem> (+ <button> props): value: string

### Native Select (native-select.tsx)
A real <select> with option groups: native picker on phones, no-JS forms, native required validation. Where customizable select is supported (appearance: base-select), the open list gets the menu look.
Docs: https://kznlabs.github.io/labsUI/components/native-select (Markdown: https://kznlabs.github.io/labsUI/components/native-select.md)
```tsx
<NativeSelect name="zone" required><NativeSelectGroup label="Europe"><NativeSelectOption value="Europe/Warsaw">Warsaw</NativeSelectOption></NativeSelectGroup></NativeSelect>
```
Props:
- <NativeSelect> (+ <select> props)
- <NativeSelectGroup> (+ <optgroup> props): label: string
- <NativeSelectOption> (+ <option> props)

### Number Input (number-input.tsx)
Native number field with −/+ buttons: arrow keys, min/max/step validation and form submit from the platform; clamps on blur, rounds to the step's precision.
Docs: https://kznlabs.github.io/labsUI/components/number-input (Markdown: https://kznlabs.github.io/labsUI/components/number-input.md)
```tsx
<NumberInput value={qty} onValueChange={setQty} min={1} max={10} name="qty" />
```
Props:
- <NumberInput> (+ <input> props): defaultValue?: number = 0; max?: number; min?: number; onValueChange?: (value: number) => void; step?: number = 1; value?: number

### Select (select.tsx)
Single-choice listbox styled like Input, with groups, icons and disabled options. Native-select keyboard (arrows, typeahead even while closed), flips above the trigger near the viewport edge, submits via a hidden input.
Docs: https://kznlabs.github.io/labsUI/components/select (Markdown: https://kznlabs.github.io/labsUI/components/select.md)
```tsx
<Select id="role" name="role" options={[{ value: "admin", label: "Admin" }]} value={v} onValueChange={setV} placeholder="Pick a role" />
```
Props:
- <Select>: options: SelectGroup[] | SelectOption[]; aria-describedby?: string; aria-invalid?: boolean; aria-label?: string; defaultValue?: string; disabled?: boolean; id?: string; name?: string; onValueChange?: (value: string) => void; placeholder?: string; required?: boolean; value?: string
- type SelectOption = { value: string; label: string; icon?: ReactNode; disabled?: boolean }
- type SelectGroup = { label: string; options: SelectOption[] }

### Popover (popover.tsx)
Non-modal panel anchored to a Button for filters, pickers and quick edits. Focus moves in, Esc returns it, outside clicks close; Selects and menus opened inside don't count as outside.
Docs: https://kznlabs.github.io/labsUI/components/popover (Markdown: https://kznlabs.github.io/labsUI/components/popover.md)
```tsx
<Popover><PopoverTrigger variant="outline">Filters</PopoverTrigger><PopoverContent align="start">…</PopoverContent></Popover>
```
Props:
- <Popover>: children: ReactNode; defaultOpen?: boolean = false; onOpenChange?: (open: boolean) => void; open?: boolean
- <PopoverTrigger> (+ Button props): children?: ReactNode; confirmLabel?: ReactNode; confirmTimeout?: number; loading?: boolean; loadingLabel?: ReactNode; size?: "default" | "sm" | "lg" | "icon"; status?: ButtonStatus; successLabel?: ReactNode; swap?: SwapDirection; variant?: "default" | "secondary" | "outline" | "ghost" | "destructive"
- <PopoverContent>: children: ReactNode; align?: "start" | "center" | "end" = "center"; side?: "top" | "bottom" = "bottom"

### Tooltip (tooltip.tsx)
Short label on hover or keyboard focus, also wired as the trigger's aria-describedby. Warm-up: once one opens, neighbors open instantly. Hoverable, Esc dismisses, ignores touch.
Docs: https://kznlabs.github.io/labsUI/components/tooltip (Markdown: https://kznlabs.github.io/labsUI/components/tooltip.md)
```tsx
<Tooltip content="Bold ⌘B"><Button variant="ghost" size="icon" aria-label="Bold"><Bold /></Button></Tooltip>
```
Props:
- <Tooltip>: children: ReactNode; content: ReactNode; align?: "start" | "center" | "end" = "center"; delay?: number = 500; side?: "top" | "bottom" = "top"; touch?: "press" | "tap" = "press"

### Hover Card (hover-card.tsx)
Rich preview (profile, product, clip) that opens after a hover delay or keyboard focus. The pointer can move into the card; supplementary only.
Docs: https://kznlabs.github.io/labsUI/components/hover-card (Markdown: https://kznlabs.github.io/labsUI/components/hover-card.md)
```tsx
<HoverCard content={<ProfilePreview />}><a href="/u/jane">@jane</a></HoverCard>
```
Props:
- <HoverCard>: children: ReactNode; content: ReactNode; align?: "start" | "center" | "end" = "center"; closeDelay?: number = 200; openDelay?: number = 600; side?: "top" | "bottom" = "bottom"

### Context Menu (context-menu.tsx)
Right-click menu for an area, opening at the pointer and flipping at screen edges. Shares Dropdown Menu's items, checkbox and radio items, keyboard and typeahead; Menu key or Shift+F10 opens it from the keyboard.
Docs: https://kznlabs.github.io/labsUI/components/context-menu (Markdown: https://kznlabs.github.io/labsUI/components/context-menu.md)
```tsx
<ContextMenu><ContextMenuTrigger>…</ContextMenuTrigger><ContextMenuContent><ContextMenuItem onSelect={play}>Play</ContextMenuItem></ContextMenuContent></ContextMenu>
```
Props:
- <ContextMenu>: children: ReactNode; onOpenChange?: (open: boolean) => void
- <ContextMenuContent>: children: ReactNode; align?: "start" | "end" = "start"
- <ContextMenuItem>: children: ReactNode; disabled?: boolean; onSelect?: () => void; shortcut?: string; variant?: "default" | "destructive" = "default"
- <ContextMenuCheckboxItem>: checked: boolean; children: ReactNode; onCheckedChange: (checked: boolean) => void; disabled?: boolean; shortcut?: string
- <ContextMenuRadioGroup>: children: ReactNode; onValueChange: (value: string) => void; value: string
- <ContextMenuRadioItem>: children: ReactNode; value: string; disabled?: boolean
- <ContextMenuLabel> (+ <div> props)
- <ContextMenuSeparator>
- <ContextMenuTrigger> (+ <div> props)

### Alert (alert.tsx)
Server-safe inline banner: tinted surface, colored icon, title, description and an optional action. Info, success, warning and destructive tones follow the accent and status tokens.
Docs: https://kznlabs.github.io/labsUI/components/alert (Markdown: https://kznlabs.github.io/labsUI/components/alert.md)
```tsx
<Alert variant="warning" action={<Button size="sm" variant="outline">Renew</Button>}><AlertTitle>Token expires soon</AlertTitle><AlertDescription>Renew it to keep syncing.</AlertDescription></Alert>
```
Props:
- <Alert> (+ <div> props): action?: ReactNode; icon?: ReactNode; variant?: "default" | "info" | "success" | "warning" | "destructive" = "default"
- <AlertTitle> (+ <p> props)
- <AlertDescription> (+ <div> props)

### Progress (progress.tsx)
Accent bar that springs to each new value, with an optional label and percentage. Leave out value for an indeterminate sweep (static under reduced motion).
Docs: https://kznlabs.github.io/labsUI/components/progress (Markdown: https://kznlabs.github.io/labsUI/components/progress.md)
```tsx
<Progress label="Uploading clip.mp4" value={progress} showValue />
```
Props:
- <Progress>: aria-label?: string; label?: string; max?: number = 100; showValue?: boolean = false; size?: "sm" | "default" = "default"; value?: number

### Dropdown Menu (dropdown-menu.tsx)
Action menu anchored to a Button: items with icons and shortcuts, checkbox and radio items, labels, separators, destructive variant. Arrow keys, typeahead, focus follows the pointer, Esc returns focus.
Docs: https://kznlabs.github.io/labsUI/components/dropdown-menu (Markdown: https://kznlabs.github.io/labsUI/components/dropdown-menu.md)
```tsx
<DropdownMenu><DropdownMenuTrigger variant="outline">Open</DropdownMenuTrigger><DropdownMenuContent align="end"><DropdownMenuItem onSelect={edit} shortcut="⌘E">Edit</DropdownMenuItem></DropdownMenuContent></DropdownMenu>
```
Props:
- <DropdownMenu>: children: ReactNode; defaultOpen?: boolean = false; onOpenChange?: (open: boolean) => void; open?: boolean
- <DropdownMenuTrigger> (+ Button props): children?: ReactNode; confirmLabel?: ReactNode; confirmTimeout?: number; loading?: boolean; loadingLabel?: ReactNode; size?: "default" | "sm" | "lg" | "icon"; status?: ButtonStatus; successLabel?: ReactNode; swap?: SwapDirection; variant?: "default" | "secondary" | "outline" | "ghost" | "destructive"
- <DropdownMenuContent>: children: ReactNode; align?: "start" | "end" = "start"
- <DropdownMenuItem>: children: ReactNode; disabled?: boolean; onSelect?: () => void; shortcut?: string; variant?: "default" | "destructive" = "default"
- <DropdownMenuCheckboxItem>: checked: boolean; children: ReactNode; onCheckedChange: (checked: boolean) => void; disabled?: boolean; shortcut?: string
- <DropdownMenuRadioGroup>: children: ReactNode; onValueChange: (value: string) => void; value: string
- <DropdownMenuRadioItem>: children: ReactNode; value: string; disabled?: boolean
- <DropdownMenuLabel> (+ <div> props)
- <DropdownMenuSeparator>

### Drawer (drawer.tsx)
Edge panel (left, right, top, bottom) that springs in and swipes away. Shares Dialog's focus trap, scroll lock and Esc handling. Sidebar uses it below md.
Docs: https://kznlabs.github.io/labsUI/components/drawer (Markdown: https://kznlabs.github.io/labsUI/components/drawer.md)
```tsx
<Drawer><DrawerTrigger>Cart</DrawerTrigger><DrawerContent side="right"><DrawerHeader><DrawerTitle>Cart</DrawerTitle></DrawerHeader><DrawerBody>…</DrawerBody></DrawerContent></Drawer>
```
Props:
- <Drawer>: children: ReactNode; defaultOpen?: boolean = false; onOpenChange?: (open: boolean) => void; open?: boolean
- <DrawerTrigger> (+ Button props): children?: ReactNode; confirmLabel?: ReactNode; confirmTimeout?: number; loading?: boolean; loadingLabel?: ReactNode; size?: "default" | "sm" | "lg" | "icon"; status?: ButtonStatus; successLabel?: ReactNode; swap?: SwapDirection; variant?: "default" | "secondary" | "outline" | "ghost" | "destructive"
- <DrawerClose> (+ Button props): children?: ReactNode; confirmLabel?: ReactNode; confirmTimeout?: number; loading?: boolean; loadingLabel?: ReactNode; size?: "default" | "sm" | "lg" | "icon"; status?: ButtonStatus; successLabel?: ReactNode; swap?: SwapDirection; variant?: "default" | "secondary" | "outline" | "ghost" | "destructive" = "outline"
- <DrawerTitle> (+ <h2> props)
- <DrawerDescription> (+ <p> props)
- <DrawerContent>: children: ReactNode; showClose?: boolean = side === "left" || side === "right"; side?: Side = "right"
- <DrawerHeader> (+ <div> props)
- <DrawerBody> (+ <div> props)
- <DrawerFooter> (+ <div> props)
- type Side = "left" | "right" | "top" | "bottom"

### Command (command.tsx)
⌘K palette: filterable groups, arrow-key highlight, Enter to run, keyword matching. Inline or as CommandDialog with a global shortcut; the first Esc clears, the second closes.
Docs: https://kznlabs.github.io/labsUI/components/command (Markdown: https://kznlabs.github.io/labsUI/components/command.md)
```tsx
<CommandDialog shortcut="mod+k"><CommandInput /><CommandList><CommandEmpty /><CommandGroup heading="Pages"><CommandItem onSelect={go}>Home</CommandItem></CommandGroup></CommandList></CommandDialog>
```
Props:
- <Command>: children: ReactNode; close?: () => void
- <CommandInput>: label?: string = "Search commands"; placeholder?: string = "Type a command or search…"
- <CommandList>: children: ReactNode; label?: string = "Results"
- <CommandEmpty> (+ <div> props)
- <CommandGroup>: children: ReactNode; heading?: string
- <CommandSeparator>
- <CommandItem>: children: ReactNode; disabled?: boolean; keepOpen?: boolean; keywords?: readonly string[]; onSelect?: (value: string) => void; value?: string
- <CommandDialog>: children: ReactNode; onOpenChange?: (open: boolean) => void; open?: boolean; shortcut?: false | `mod+${string}` = "mod+k"; title?: string = "Command palette"

### Tabs (tabs.tsx)
WAI-ARIA tabs with arrow, Home and End keys. One indicator springs between tabs, segmented or underline. Inactive panels stay in the DOM for SEO; the active one fades in.
Docs: https://kznlabs.github.io/labsUI/components/tabs (Markdown: https://kznlabs.github.io/labsUI/components/tabs.md)
```tsx
<Tabs defaultValue="a"><TabsList aria-label="Views"><TabsTrigger value="a">A</TabsTrigger><TabsTrigger value="b">B</TabsTrigger></TabsList><TabsContent value="a">…</TabsContent><TabsContent value="b">…</TabsContent></Tabs>
```
Props:
- <Tabs> (+ <div> props): defaultValue?: string = ""; onValueChange?: (value: string) => void; value?: string; variant?: "segmented" | "underline" = "segmented"
- <TabsList> (+ <div> props)
- <TabsTrigger> (+ <button> props): value: string
- <TabsContent>: children: ReactNode; value: string

### Kbd (kbd.tsx)
Server-safe key caps for shortcut hints. KbdGroup nests keys per the HTML spec.
Docs: https://kznlabs.github.io/labsUI/components/kbd (Markdown: https://kznlabs.github.io/labsUI/components/kbd.md)
```tsx
<KbdGroup keys={["⌘", "K"]} />
```
Props:
- <Kbd> (+ <kbd> props)
- <KbdGroup> (+ <kbd> props): keys: readonly string[]

### Separator (separator.tsx)
Server-safe hairline, horizontal or vertical, decorative by default, with an optional centered label like "or".
Docs: https://kznlabs.github.io/labsUI/components/separator (Markdown: https://kznlabs.github.io/labsUI/components/separator.md)
```tsx
<Separator label="or" />
```
Props:
- <Separator> (+ <div> props): decorative?: boolean = true; label?: string; orientation?: "horizontal" | "vertical" = "horizontal"

### Meter (meter.tsx)
Server-safe gauge for a value in a known range (storage, quota, server load, password strength). Colors by <meter> thresholds, or stacked segments with a legend, like a storage bar.
Docs: https://kznlabs.github.io/labsUI/components/meter (Markdown: https://kznlabs.github.io/labsUI/components/meter.md)
```tsx
<Meter label="Storage" valueText="71 GB of 100 GB" segments={[{ label: "Clips", value: 48 }, { label: "Backups", value: 14 }]} />
```
Props:
- <Meter>: high?: number = max; label?: ReactNode; low?: number = min; max?: number = 100; min?: number = 0; optimum?: number = (min + max) / 2; segments?: Segment[]; value?: number; valueText?: string
- type Segment = { label: string; value: number; className?: string; }

### Rating (rating.tsx)
Star rating on native radios (arrow keys, forms) with hover preview, or readOnly display with fractional stars for averages.
Docs: https://kznlabs.github.io/labsUI/components/rating (Markdown: https://kznlabs.github.io/labsUI/components/rating.md)
```tsx
<Rating value={stars} onValueChange={setStars} name="stars" /> · <Rating readOnly value={4.6} size="sm" />
```
Props:
- <Rating>: defaultValue?: number = 0; label?: string = "Rating"; max?: number = 5; name?: string; onValueChange?: (value: number) => void; readOnly?: boolean = false; size?: "sm" | "default" = "default"; value?: number

### Relative Time (relative-time.tsx)
Self-updating “5 minutes ago” in a semantic <time> with the full date as its title. Server renders the absolute date (no hydration mismatch); one shared ticker for the whole page.
Docs: https://kznlabs.github.io/labsUI/components/relative-time (Markdown: https://kznlabs.github.io/labsUI/components/relative-time.md)
```tsx
<RelativeTime date={clip.createdAt} />
```
Props:
- <RelativeTime>: date: string | number | Date; locale?: string = "en-US"

### Empty (empty.tsx)
Server-safe empty state: icon tile, title, one helpful sentence and the next action. Bordered variant for empty lists and drop zones.
Docs: https://kznlabs.github.io/labsUI/components/empty (Markdown: https://kznlabs.github.io/labsUI/components/empty.md)
```tsx
<Empty icon={<Film />} title="No clips yet" description="Upload your first clip."><Button size="sm">Upload</Button></Empty>
```
Props:
- <Empty> (+ <div> props): title: ReactNode; bordered?: boolean = false; description?: ReactNode; icon?: ReactNode

### Skeleton (skeleton.tsx)
Server-safe loading placeholders that pulse (static under reduced motion). SkeletonGroup announces one "Loading" to screen readers.
Docs: https://kznlabs.github.io/labsUI/components/skeleton (Markdown: https://kznlabs.github.io/labsUI/components/skeleton.md)
```tsx
<SkeletonGroup><Skeleton className="size-10 rounded-full" /><Skeleton className="h-4 w-32" /></SkeletonGroup>
```
Props:
- <Skeleton> (+ <div> props)
- <SkeletonGroup> (+ <div> props): label?: string = "Loading"

### Typewriter (typewriter.tsx)
Types out text character-by-character with optional phrase cycling and pulsing cursor. Full copy stays in the DOM for SEO.
Docs: https://kznlabs.github.io/labsUI/components/typewriter (Markdown: https://kznlabs.github.io/labsUI/components/typewriter.md)
```tsx
<Typewriter text={["Clean details.", "Delightful springs."]} speed={40} />
```
Props:
- <Typewriter>: text: string | readonly string[]; cursor?: boolean = true; cursorChar?: string = "|"; cursorClassName?: string; delay?: number = 0; deleteSpeed?: number = 24; loop?: boolean = true; onComplete?: () => void; pauseDuration?: number = 2000; speed?: number = 40

### TextSwap (text-swap.tsx)
Spring-powered text morphing and ticker. Auto-cycles phrases or animates whenever children change with blur and slide transitions.
Docs: https://kznlabs.github.io/labsUI/components/text-swap (Markdown: https://kznlabs.github.io/labsUI/components/text-swap.md)
```tsx
<TextSwap items={["Next.js 16", "Tailwind CSS 4", "motion 14"]} direction="up" />
```
Props:
- <TextSwap>: children?: string; direction?: "up" | "down" | "fade" = "up"; index?: number; interval?: number = 3000; items?: readonly string[]; pauseOnHover?: boolean = true

### Table (table.tsx)
Server-safe semantic <table> in a scrolling card: header, body, footer and caption, striped rows, tinted selected rows, and sortable headers that set aria-sort and flip their arrow.
Docs: https://kznlabs.github.io/labsUI/components/table (Markdown: https://kznlabs.github.io/labsUI/components/table.md)
```tsx
<Table striped><TableHeader><TableRow><TableHead sort="ascending" onSort={toggle}>Member</TableHead></TableRow></TableHeader><TableBody><TableRow><TableCell>Jane</TableCell></TableRow></TableBody></Table>
```
Props:
- <Table> (+ <table> props): containerClassName?: string; striped?: boolean = false
- <TableHeader> (+ <thead> props)
- <TableBody> (+ <tbody> props)
- <TableFooter> (+ <tfoot> props)
- <TableRow> (+ <tr> props)
- <TableHead> (+ <th> props): onSort?: () => void; sort?: "ascending" | "descending" | "none"
- <TableCell> (+ <td> props)
- <TableCaption> (+ <caption> props)

### Data Table (data-table.tsx)
Table with columns as data: search across every column, sortable headers, checkbox selection that survives paging, a ⋯ menu per row, bulk actions in the toolbar and pagination. Built from Table, SearchInput, Checkbox, DropdownMenu, Pagination and Empty.
Docs: https://kznlabs.github.io/labsUI/components/data-table (Markdown: https://kznlabs.github.io/labsUI/components/data-table.md)
```tsx
<DataTable label="Members" data={members} columns={[{ id: "name", header: "Member", accessor: (m) => m.name, sortable: true }]} getRowId={(m) => m.id} rowLabel={(m) => m.name} selectable rowActions={(m) => <DropdownMenuItem onSelect={() => kick(m)}>Kick</DropdownMenuItem>} />
```
Props:
- <DataTable>: columns: DataTableColumn<T>[]; data: T[]; getRowId: (row: T) => string; label: string; rowLabel: (row: T) => string; defaultSort?: Sort; onSelectionChange?: (ids: string[]) => void; pageSize?: number = 10; rowActions?: (row: T) => ReactNode; searchable?: boolean = true; searchPlaceholder?: string = "Search…"; selectable?: boolean = false; selection?: string[]; striped?: boolean = false; toolbar?: (selected: T[]) => ReactNode
- type Sort = { id: string; dir: "ascending" | "descending" }
- type DataTableColumn = { id: string; header: ReactNode; accessor?: (row: T) => string | number; cell?: (row: T) => ReactNode; sortable?: boolean; className?: string; }

### Attachment & Dropzone (attachment.tsx)
File chips with image thumbnails or type icons, size, a springing upload bar, error state and remove; the list springs chips in and closes the gap. FileDropzone wraps a real file input: click, keyboard and the native picker work, drop and paste are checked against accept and maxSize, and dropped files land in the input so forms and Server Actions receive them.
Docs: https://kznlabs.github.io/labsUI/components/attachment (Markdown: https://kznlabs.github.io/labsUI/components/attachment.md)
```tsx
<FileDropzone name="clips" multiple accept="video/*" maxSize={50 * 1024 * 1024} onFiles={add} onReject={warn} /><AttachmentList>{files.map((f) => <Attachment key={f.id} name={f.name} size={f.size} type={f.type} progress={f.progress} onRemove={() => remove(f.id)} />)}</AttachmentList>
```
Props:
- <Attachment>: name: string; error?: string; href?: string; locale?: string; onRemove?: () => void; progress?: number; size?: number; src?: string; type?: string
- <AttachmentList> (+ <ul> props)
- <FileDropzone>: accept?: string; aria-describedby?: string; aria-invalid?: boolean; children?: ReactNode; disabled?: boolean; id?: string; maxSize?: number; multiple?: boolean; name?: string; onFiles?: (files: File[]) => void; onReject?: (rejected: Rejection[]) => void; required?: boolean
- `formatBytes(bytes: number, locale?: string) => string`
- type Rejection = { file: File; reason: "type" | "size" }

### Stepper (stepper.tsx)
Multi-step form (questionnaire, checkout, setup wizard). Steps stay mounted so values survive Back and submit together; Continue checks only the current step's native constraints, plus an optional async onNext guard with a spinner. Progress header with springing connectors; works with onSubmit or a Server Action.
Docs: https://kznlabs.github.io/labsUI/components/stepper (Markdown: https://kznlabs.github.io/labsUI/components/stepper.md)
```tsx
<Stepper steps={[{ value: "server", title: "Server" }, { value: "bot", title: "Bot" }]} action={createBot}><StepperList /><StepperStep value="server"><Input name="serverId" required /></StepperStep><StepperStep value="bot">…</StepperStep><StepperFooter submitLabel="Create bot" /></Stepper>
```
Props:
- <Stepper> (+ <form> props): steps: StepInfo[]; defaultValue?: string; onValueChange?: (value: string) => void; value?: string
- <StepperList> (+ <ol> props)
- <StepperStep>: children: ReactNode; value: string; onNext?: Guard
- <StepperFooter>: backLabel?: ReactNode = "Back"; nextLabel?: ReactNode = "Continue"; submitLabel?: ReactNode = "Submit"
- type StepInfo = { value: string; title: string; description?: string }
- type Guard = () => boolean | undefined | Promise<boolean | undefined>

### Calendar (calendar.tsx)
Month grid on the WAI-ARIA date-grid pattern: single date or range with a hover preview, min/max and custom disabled days, months that slide in from the direction of travel. Arrows, Home/End and PageUp/PageDown (+Shift for years). Hydration-safe: today is only marked in the browser.
Docs: https://kznlabs.github.io/labsUI/components/calendar (Markdown: https://kznlabs.github.io/labsUI/components/calendar.md)
```tsx
<Calendar mode="range" value={range} onValueChange={setRange} min={today} isDisabled={(d) => d.getDay() === 0} />
```
Props:
- <Calendar>: autoFocus?: boolean; defaultMonth?: Date; defaultValue?: Date | DateRange | null; isDisabled?: (date: Date) => boolean; locale?: string; max?: Date; min?: Date; mode?: "single" | "range"; month?: Date; onMonthChange?: (month: Date) => void; onValueChange?: ((date: Date) => void) | ((range: DateRange) => void); value?: Date | DateRange | null; weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6
- `key(date: Date) => string`
- type DateRange = { from?: Date; to?: Date }

### Date Picker (date-picker.tsx)
Field-styled button that opens a Calendar in a Popover, focused on the picked day. Single or range, presets such as Last 7 days, closes once the pick is complete, and submits ISO dates through a hidden input. Works inside Field.
Docs: https://kznlabs.github.io/labsUI/components/date-picker (Markdown: https://kznlabs.github.io/labsUI/components/date-picker.md)
```tsx
<Field label="Report period"><DatePicker mode="range" name="period" presets={[{ label: "Last 7 days", value: { from, to } }]} /></Field>
```
Props:
- <DatePicker>: aria-describedby?: string; aria-invalid?: boolean; aria-label?: string; defaultValue?: Date | DateRange | null; disabled?: boolean; id?: string; isDisabled?: (date: Date) => boolean; locale?: string; max?: Date; min?: Date; mode?: "single" | "range"; name?: string; onValueChange?: ((date: Date) => void) | ((range: DateRange) => void); placeholder?: string; presets?: Preset<Date>[] | Preset<DateRange>[]; required?: boolean; value?: Date | DateRange | null; weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6
- type Preset = { label: string; value: Value }

### Confirm (confirm.tsx)
Promise-based confirm dialog called like toast: await confirm({ title, description, destructive }) resolves true or false. Built on Dialog's alert mode, Cancel takes the first focus, Esc cancels, one host mounted in the layout.
Docs: https://kznlabs.github.io/labsUI/components/confirm (Markdown: https://kznlabs.github.io/labsUI/components/confirm.md)
```tsx
if (await confirm({ title: "Delete project?", description: "This cannot be undone.", destructive: true })) remove();
```
Props:
- <Confirmer>
- `confirm(options: ConfirmOptions) => Promise<boolean>`
- type ConfirmOptions = { title: ReactNode; description?: ReactNode; confirmLabel?: ReactNode; cancelLabel?: ReactNode; destructive?: boolean; }

### Chart (chart.tsx)
Line, area and bar (grouped or stacked) charts in SVG with a colorblind-validated eight-color palette that keeps each series' color. Crosshair tooltip listing every series, arrow-key readout, legend that hides series, direct end labels, a table view, and spring transitions between data.
Docs: https://kznlabs.github.io/labsUI/components/chart (Markdown: https://kznlabs.github.io/labsUI/components/chart.md)
```tsx
<Chart type="line" label="Revenue by channel" data={rows} index="month" series={[{ key: "web", label: "Web" }, { key: "app", label: "App" }]} format={{ style: "currency", currency: "USD" }} />
```
Props:
- <Chart> (+ <figure> props): data: Record<string, string | number>[]; index: string; label: string; series: ChartSeries[]; format?: NumberFormatOptions; height?: number = 240; locale?: string = "en-US"; stacked?: boolean = false; type?: "line" | "area" | "bar" = "line"
- type ChartSeries = { key: string; label: string; color?: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8; }

### Carousel (carousel.tsx)
Native scroll-snap row, so touch, trackpad and no-JS scrolling work, with spring-driven arrows, page dots, arrow keys and mouse drag that throws to the next snap point. APG carousel semantics: a labeled region of slides announced as 3 of 8.
Docs: https://kznlabs.github.io/labsUI/components/carousel (Markdown: https://kznlabs.github.io/labsUI/components/carousel.md)
```tsx
<Carousel label="Projects"><CarouselContent className="sm:[--per-view:2]"><CarouselItem>…</CarouselItem></CarouselContent><CarouselPrevious /><CarouselNext /><CarouselDots /></Carousel>
```
Props:
- <Carousel> (+ <section> props): label: string
- <CarouselContent> (+ <div> props)
- <CarouselItem> (+ <div> props)
- <CarouselPrevious>
- <CarouselNext>
- <CarouselDots>

### Marker (marker.tsx)
Highlighter-pen <mark> in four tints that wraps cleanly across lines and can draw itself on, left to right, when it scrolls into view. Highlight marks every match of a search in a string, for transcripts and search results.
Docs: https://kznlabs.github.io/labsUI/components/marker (Markdown: https://kznlabs.github.io/labsUI/components/marker.md)
```tsx
<p>Ship it <Marker draw color="green">today</Marker>.</p> · <Highlight text={line.text} query={search} />
```
Props:
- <Marker>: color?: "primary" | "yellow" | "green" | "red" = "yellow"; delay?: number = 0; draw?: boolean = false
- <Highlight>: query: string | string[]; text: string; color?: "primary" | "yellow" | "green" | "red"

### Code (code.tsx)
Shiki-highlighted code that follows light and dark through light-dark() token colors, as a block, an inline one-liner or a tabbed file panel. Line numbers (from any start line), tinted lines with an accent bar, <mark>ed words or column ranges, and per-line notes in a tooltip that keyboard users can tab to. Optional Prettier at display time; copy hands out exactly what is shown.
Docs: https://kznlabs.github.io/labsUI/components/code (Markdown: https://kznlabs.github.io/labsUI/components/code.md)
```tsx
<Code code={src} language="ts" lineNumbers highlight={[[8, 13]]} marks={["t.Object"]} notes={{ 2: "Remember to add it: bun add @elysiajs/cors" }} />
```
Props:
- <Code>: code: string; format?: boolean; highlight?: LineRange[]; language?: string = "tsx"; lineNumbers?: number | boolean; marks?: CodeMark[]; notes?: Record<number, ReactNode>; tokens?: CodeToken[][]; variant?: "block" | "inline" = "block"
- <CopyButton>: code: string; label?: string = "Copy code"
- <CodePanel>: files: CodeFile[]; collapse?: number; format?: boolean
- type LineRange = number | [from: number, to: number]
- type CodeMark = | string | { text: string; line?: number } | { line: number; start: number; end: number }
- type CodeFile = Annotations & { name: string; code: string; tokens?: CodeToken[][]; }

### Terminal (terminal.tsx)
Terminal window. Snippet mode types install commands once scrolled into view, with the full transcript kept in the DOM for SEO and no-JS; log mode streams lines into a live region that follows the bottom unless you scroll up, then offers a jump back. Status lines carry glyphs, copy grabs the commands.
Docs: https://kznlabs.github.io/labsUI/components/terminal (Markdown: https://kznlabs.github.io/labsUI/components/terminal.md)
```tsx
<Terminal typing lines={[{ kind: "command", text: "bun add motion" }, { kind: "success", text: "1 package installed" }]} />
```
Props:
- <Terminal>: lines: TerminalLine[]; bodyClassName?: string; copyText?: string | false; log?: boolean = false; prompt?: string = "$"; speed?: number = 35; title?: string = "Terminal"; typing?: boolean = false
- type TerminalLine = { id?: string | number; kind?: Kind; text: string; time?: string; }

### Timeline (timeline.tsx)
Server-safe ordered list of events on a rail: icon or dot markers with status colors, machine-readable <time>, title and an optional body. For changelogs, experience and mod logs.
Docs: https://kznlabs.github.io/labsUI/components/timeline (Markdown: https://kznlabs.github.io/labsUI/components/timeline.md)
```tsx
<Timeline><TimelineItem icon={<Rocket />} variant="active" time="Oct 21" dateTime="2026-10-21" title="v0.3 released">Notes</TimelineItem></Timeline>
```
Props:
- <Timeline> (+ <ol> props)
- <TimelineItem> (+ <li> props): title: ReactNode; dateTime?: string; icon?: ReactNode; time?: ReactNode; variant?: "default" | "active" | "success" | "warning" | "destructive" = "default"

### Spinner (spinner.tsx)
Server-safe activity indicator: eight spokes in currentColor, three sizes, its own status label (or silent inside a parent that announces). Holds still under reduced motion.
Docs: https://kznlabs.github.io/labsUI/components/spinner (Markdown: https://kznlabs.github.io/labsUI/components/spinner.md)
```tsx
<Spinner size="sm" label="Loading members" />
```
Props:
- <Spinner> (+ <span> props): label?: string = "Loading"; size?: "sm" | "default" | "lg" = "default"

### Input OTP (input-otp.tsx)
One-time code in separate slots, backed by one real input: paste and SMS autofill work, screen readers hear one field. Grouped slots, numeric or alphanumeric, characters spring in, onComplete to submit. verified turns each character into a check, then merges them into one mark.
Docs: https://kznlabs.github.io/labsUI/components/input-otp (Markdown: https://kznlabs.github.io/labsUI/components/input-otp.md)
```tsx
<InputOTP groups={[3, 3]} value={code} onValueChange={setCode} onComplete={verify} verified={ok} />
```
Props:
- <InputOTP> (+ <input> props): charset?: "numeric" | "alphanumeric" = "numeric"; defaultValue?: string = ""; groups?: number[]; length?: number = 6; onComplete?: (value: string) => void; onValueChange?: (value: string) => void; value?: string; verified?: boolean = false; verifiedLabel?: ReactNode = "Verified"

### Aspect Ratio (aspect-ratio.tsx)
Server-safe box locked to a ratio (16:9 thumbnails, 9:16 clips). A direct image or video child fills it with object-cover.
Docs: https://kznlabs.github.io/labsUI/components/aspect-ratio (Markdown: https://kznlabs.github.io/labsUI/components/aspect-ratio.md)
```tsx
<AspectRatio ratio={9 / 16} className="rounded-xl"><img src={clip.thumb} alt={clip.title} /></AspectRatio>
```
Props:
- <AspectRatio> (+ <div> props): ratio?: number = 16 / 9

### Combobox (combobox.tsx)
A Select you can type into: the query filters by label and keywords (prefix matches first), arrows move, Enter picks. multiple keeps the list open and shows picks as removable tags. Submits through hidden inputs.
Docs: https://kznlabs.github.io/labsUI/components/combobox (Markdown: https://kznlabs.github.io/labsUI/components/combobox.md)
```tsx
<Combobox options={channels} value={channel} onValueChange={setChannel} placeholder="Pick a channel…" />
```
Props:
- <Combobox>: options: ComboboxOption[]; aria-describedby?: string; aria-invalid?: boolean; aria-label?: string; defaultValue?: string | string[]; disabled?: boolean; emptyText?: ReactNode; id?: string; multiple?: boolean; name?: string; onValueChange?: ((value: string) => void) | ((value: string[]) => void); placeholder?: string; required?: boolean; value?: string | string[]
- type ComboboxOption = { value: string; label: string; icon?: ReactNode; keywords?: string[]; disabled?: boolean; }

### Tag Input (tag-input.tsx)
Free-form tags: Enter or a separator adds, Backspace removes the last, pasting a list adds them all. Duplicates, a max and a validate function keep bad tags in the input. One hidden input per tag.
Docs: https://kznlabs.github.io/labsUI/components/tag-input (Markdown: https://kznlabs.github.io/labsUI/components/tag-input.md)
```tsx
<TagInput value={tags} onValueChange={setTags} max={5} validate={(t) => t.length <= 24} />
```
Props:
- <TagInput> (+ <input> props): defaultValue?: string[] = []; max?: number; onValueChange?: (tags: string[]) => void; separators?: string[] = [","]; validate?: (tag: string) => boolean; value?: string[]
- <Tag>: children: ReactNode; disabled?: boolean; onRemove?: () => void

### Scroll Area (scroll-area.tsx)
Overlay scrollbars: thin thumbs that fade in while scrolling or on hover, widen under the pointer and drag. Scrolling stays native; the labeled region is keyboard-focusable.
Docs: https://kznlabs.github.io/labsUI/components/scroll-area (Markdown: https://kznlabs.github.io/labsUI/components/scroll-area.md)
```tsx
<ScrollArea aria-label="Moderation log" className="h-64 rounded-xl border">…</ScrollArea>
```
Props:
- <ScrollArea> (+ <div> props): orientation?: "vertical" | "horizontal" | "both" = "vertical"; viewportClassName?: string

### Resizable (resizable.tsx)
Split panes for admin layouts, docs and editors. Hairline dividers with a wide grab area follow the pointer; collapsible panels snap shut past half their minimum. Dividers are APG window splitters: arrows step, Home/End jump to the limits, Enter or double-click collapses with a spring. Groups nest.
Docs: https://kznlabs.github.io/labsUI/components/resizable (Markdown: https://kznlabs.github.io/labsUI/components/resizable.md)
```tsx
<ResizablePanelGroup direction="horizontal"><ResizablePanel defaultSize={25} minSize={15} collapsible>…</ResizablePanel><ResizableHandle withHandle /><ResizablePanel>…</ResizablePanel></ResizablePanelGroup>
```
Props:
- <ResizablePanelGroup> (+ <div> props): direction?: Direction = "horizontal"; keyboardStep?: number = 5; onLayout?: (sizes: number[]) => void
- <ResizablePanel> (+ <div> props): collapsedSize?: number = 0; collapsible?: boolean = false; defaultSize?: number; maxSize?: number = 100; minSize?: number = 10
- <ResizableHandle> (+ <div> props): withHandle?: boolean
- type Direction = "horizontal" | "vertical"

### Pricing (blocks/pricing.tsx)
Plan cards with a monthly / yearly segmented switch. Prices roll on a spring in the direction they moved; the featured plan is outlined in the accent. Card, Badge, ToggleGroup, Button.
Docs: https://kznlabs.github.io/labsUI/components/pricing (Markdown: https://kznlabs.github.io/labsUI/components/pricing.md)
```tsx
<Pricing yearlyNote="−20%" plans={[{ name: "Pro", price: { monthly: 9, yearly: 7 }, features: ["10 servers"], featured: true, badge: "Popular", cta: <Button className="w-full">Start trial</Button> }]} />
```
Props:
- <Pricing>: plans: Plan[]; currency?: string = "USD"; defaultPeriod?: Period = "monthly"; locale?: string = "en-US"; yearlyNote?: string
- type Period = "monthly" | "yearly"
- type Plan = { name: string; description?: string; price: Record<Period, number>; features: string[]; cta: ReactNode; featured?: boolean; badge?: string; }

### Testimonial (blocks/testimonial.tsx)
A large Quote with its author, and everyone else who agrees as an overlapping AvatarGroup. Server-safe.
Docs: https://kznlabs.github.io/labsUI/components/testimonial (Markdown: https://kznlabs.github.io/labsUI/components/testimonial.md)
```tsx
<Testimonial author="Jane Cooper" subtitle="Moderator" others={fans} othersLabel="and 2,400 others">We replaced three bots with one dashboard.</Testimonial>
```
Props:
- <Testimonial>: author: string; children: ReactNode; avatar?: string; lang?: string; others?: { alt: string; src?: string | undefined; id?: string | undefined; }[]; othersLabel?: ReactNode; subtitle?: string

### Stats Strip (blocks/stats-strip.tsx)
Headline numbers, each card a <dl>: cards rise in turn with Reveal, then each number springs up with CountTo. Final values are in the HTML.
Docs: https://kznlabs.github.io/labsUI/components/stats-strip (Markdown: https://kznlabs.github.io/labsUI/components/stats-strip.md)
```tsx
<StatsStrip stats={[{ label: "Servers", value: 1284, hint: "+32 this week" }, { label: "Revenue", value: 48290, prefix: "$" }]} />
```
Props:
- <StatsStrip>: stats: Stat[]
- type Stat = { label: string; value: number; prefix?: string; suffix?: string; decimals?: number; hint?: string; }

### Product Card (blocks/product-card.tsx)
Shop tile: photos in an AspectRatio (a swipeable Carousel with dots when there are several), sale price, Badge and add-to-cart Button.
Docs: https://kznlabs.github.io/labsUI/components/product-card (Markdown: https://kznlabs.github.io/labsUI/components/product-card.md)
```tsx
<ProductCard name="Clip camera" price={279} compareAt={349} badge="−20%" media={[<img … />, <img … />]} onAddToCart={add} />
```
Props:
- <ProductCard>: media: ReactNode[]; name: string; price: number; addLabel?: ReactNode = "Add to cart"; badge?: string; compareAt?: number; currency?: string = "USD"; href?: string; locale?: string = "en-US"; onAddToCart?: () => void; ratio?: number = 4 / 3

### Clip Card (blocks/clip-card.tsx)
Video tile: AspectRatio thumbnail (16:9 or 9:16), duration Badge, watched Progress along the bottom, and a ContextMenu of actions.
Docs: https://kznlabs.github.io/labsUI/components/clip-card (Markdown: https://kznlabs.github.io/labsUI/components/clip-card.md)
```tsx
<ClipCard title="Insane 1v4 clutch" duration="0:42" watched={65} meta="12.4K views" actions={<ContextMenuItem onSelect={play}>Play</ContextMenuItem>} />
```
Props:
- <ClipCard>: duration: string; title: string; actions?: ReactNode; meta?: ReactNode; ratio?: number = 16 / 9; thumbnail?: ReactNode; watched?: number

### Stat Tile (blocks/stat-tile.tsx)
Admin dashboard metric: value, a delta Badge that is green when the change is good news (invert for errors and latency), and an area Chart of the trend. Server-safe.
Docs: https://kznlabs.github.io/labsUI/components/stat-tile (Markdown: https://kznlabs.github.io/labsUI/components/stat-tile.md)
```tsx
<StatTile label="Revenue" value="$48,290" delta={12.5} period="vs last month" data={rows} index="month" format={{ style: "currency", currency: "USD" }} />
```
Props:
- <StatTile>: label: string; value: ReactNode; data?: Record<string, string | number>[]; dataKey?: string = "value"; delta?: number; format?: NumberFormatOptions; index?: string = "x"; invert?: boolean; period?: string

### Changelog (blocks/changelog.tsx)
Release notes on a Timeline: newest release highlighted, changes typed New / Improved / Fixed with Badges, and a Kbd shortcut to try the headline feature. Server-safe.
Docs: https://kznlabs.github.io/labsUI/components/changelog (Markdown: https://kznlabs.github.io/labsUI/components/changelog.md)
```tsx
<Changelog releases={[{ version: "v0.4", title: "Resizable", date: "Oct 24, 2026", dateTime: "2026-10-24", changes: [{ type: "new", text: "Split panes" }], shortcut: ["⌘", "K"] }]} />
```
Props:
- <Changelog>: releases: Release[]
- type Release = { version: string; title: string; date: string; dateTime?: string; changes: Change[]; shortcut?: string[]; }

### Newsletter (blocks/newsletter.tsx)
Email signup: InputGroup with the submit Button inside, native email validation, a loading → success toast and an in-place success state on the button.
Docs: https://kznlabs.github.io/labsUI/components/newsletter (Markdown: https://kznlabs.github.io/labsUI/components/newsletter.md)
```tsx
<Newsletter title="Release notes" onSubscribe={(email) => subscribe(email)} />
```
Props:
- <Newsletter>: onSubscribe: (email: string) => Promise<unknown>; description?: ReactNode; placeholder?: string = "you@example.com"; submitLabel?: string = "Subscribe"; successMessage?: ReactNode = "Check your inbox to confirm"; title?: ReactNode

### Site Header (blocks/site-header.tsx)
Sticky, translucent site header from one nav array: brand, NavigationMenu panels from md up, a right Drawer with the same links below it, and your actions on the right. The hairline underneath appears only once content scrolls beneath it.
Docs: https://kznlabs.github.io/labsUI/components/site-header (Markdown: https://kznlabs.github.io/labsUI/components/site-header.md)
```tsx
<SiteHeader brand={<a href="/">Acme</a>} current="/blog" nav={[{ label: "Products", items: [{ title: "Bot", href: "/bot", icon: <Bot /> }] }, { label: "Blog", href: "/blog" }]} actions={<ThemeToggle />} />
```
Props:
- <SiteHeader>: brand: ReactNode; nav: (SiteGroup | SiteLink)[]; actions?: ReactNode; current?: string; label?: string = "Main"; onNavigate?: (href: string, event: MouseEvent<HTMLAnchorElement, MouseEvent>) => void
- type SiteLink = { label: string; href: string }
- type SiteGroup = { label: string; items: { title: string; href: string; description?: ReactNode; icon?: ReactNode }[]; columns?: 1 | 2; }