@cloudraker/reki 2.6.1

package/ai/USAGE.md

@@ -0,0 +1,201 @@
+# @cloudraker/reki — AI Usage Guide
+
+> Cloudflare's React component library built on [Base UI](https://base-ui.com) + Tailwind CSS v4.
+
+## Quick Start
+
+### CSS setup (required)
+
+In your main CSS file (e.g. `global.css`), add **all three lines in this order**:
+
+```css
+@source "path/to/node_modules/@cloudraker/reki/dist/**/*.{js,jsx,ts,tsx}";
+@import "@cloudraker/reki/styles";
+@import "tailwindcss";
+```
+
+- **`@source`** — Tells Tailwind to scan reki's compiled JS for class names. Without this, reki component internals will be unstyled. Adjust the relative path so it resolves to your project's `node_modules/`.
+- **Import order matters** — `@cloudraker/reki/styles` must come **before** `@import "tailwindcss"` so reki's `@theme` tokens are registered first.
+
+### Component usage
+
+```tsx
+import { Button, Input, Dialog } from "@cloudraker/reki";
+```
+
+## Critical Rules
+
+1. **Semantic tokens only** — use `bg-reki-base`, `text-reki-default`, etc. Never use raw Tailwind colors (`bg-blue-500`).
+2. **No `dark:` variant** — light/dark mode is handled automatically via CSS `light-dark()`. Never add `dark:` prefixes.
+3. **Merge classes with `cn()`** — import from `@cloudraker/reki` and use it to combine class names.
+4. **Compound components** — many components use a dot-notation API: `<Dialog.Root>`, `<Dialog.Trigger>`, etc.
+
+## Component Quick Reference
+
+| Component | Category | Description | Key Props |
+|-----------|----------|-------------|-----------|
+| `Badge` | Display | Status/label indicator | `variant`: primary, secondary, destructive, outline, beta |
+| `Banner` | Feedback | Page-level alert message | `variant`: default, alert, error; `icon`, `onDismiss` |
+| `Breadcrumbs` | Display | Navigation breadcrumb trail | Compound: `.Link` (with `href`), `.Separator`, `.Current`; `size`: sm, base |
+| `Button` | Action | Clickable action trigger | `variant`: primary, secondary, ghost, destructive, secondary-destructive, outline; `size`, `shape`, `icon`, `loading` |
+| `Checkbox` | Input | Toggle or multi-select control | `checked`, `onCheckedChange`, `label`, `indeterminate` |
+| `Checkbox.Group` | Input | Group of checkboxes with fieldset | `legend`, `orientation`, `allValues`, `value`, `onValueChange` |
+| `ClipboardText` | Action | Copy-to-clipboard text display | `value`, `label` |
+| `Code` | Display | Inline code or multi-line code block | `children`; use `CodeBlock` for multi-line with copy |
+| `Collapsible` | Display | Expandable/collapsible section | `title`, `defaultOpen` |
+| `Combobox` | Input | Autocomplete input with dropdown | `items`, `value`, `onValueChange`, `multiple`, `label` |
+| `CommandPalette` | Navigation | Spotlight-style search overlay | `.Root`, `.Input`, `.List`, `.Item`, `.ResultItem` |
+| `DateRangePicker` | Input | Dual-calendar date range selector | `onStartDateChange`, `onEndDateChange`, `size`, `timezone` |
+| `Dialog` | Overlay | Modal dialog with backdrop | `size`: sm, base, lg, xl; uses `.Root`, `.Trigger`, `.Title`, `.Close` |
+| `DropdownMenu` | Overlay | Context/action menu | `.Trigger`, `.Content`, `.Item`; item `variant`: default, danger |
+| `Empty` | Display | Empty state placeholder | `icon`, `title`, `description`, `commandLine`, `contents` |
+| `Field` | Input | Form field wrapper with label/error | `label`, `description`, `error`, `required`, `labelTooltip` |
+| `Grid` | Layout | Responsive CSS grid | `variant`: 2up, side-by-side, 2-1, 1-2, 1-3up, 3up, 4up, 1-2-4up; `gap`: none, sm, base, lg |
+| `Input` | Input | Text input field | `size`: xs, sm, base, lg; `variant`: default, error; `label`, `error` |
+| `Label` | Other | Form label with optional tooltip | `children`, `tooltip`, `required` |
+| `LayerCard` | Display | Card with header and collapsible body | `title`, `tag`, `actions`, `icon` |
+| `Link` | Other | Styled anchor/router link | `variant`: inline, current, plain; `href`, `external` |
+| `Loader` | Feedback | Animated loading spinner | `size`: number (default 16) |
+| `MenuBar` | Navigation | Horizontal icon toolbar | `isActive`, `options: { icon, tooltip, onClick }[]` |
+| `Meter` | Display | Progress/usage meter bar | `value`, `max`, `label`, `size` |
+| `Pagination` | Navigation | Page navigation controls | `page`, `setPage`, `perPage`, `totalCount`; `controls`: full, simple |
+| `Popover` | Overlay | Popup content anchored to trigger | `.Trigger`, `.Content`, `.Title`, `.Description`, `.Close`; `side`, `align` |
+| `Radio` | Input | Single-select radio group | `.Group` with `legend`, `.Item` with `label`, `value` |
+| `Select` | Input | Dropdown select menu | `value`, `onValueChange`, `label`, `hideLabel` (default: true); children: `<Select.Option value="…">` |
+| `SensitiveInput` | Input | Input with show/hide toggle | `label`, `size`, `variant` |
+| `Surface` | Layout | Themed container panel | `variant`: flat, raised; `as` for polymorphic rendering |
+| `Switch` | Input | Toggle switch control | `checked`, `onCheckedChange`, `label`, `size` |
+| `Table` | Display | Data table with selection | `.Header`, `.Head`, `.Body`, `.Row`, `.Cell`, `.Footer`, `.CheckCell`, `.CheckHead`, `.ResizeHandle`; `layout`: auto, fixed |
+| `Tabs` | Navigation | Tabbed navigation | `tabs: { value, label, render? }[]`; `variant`: segmented, underline; `value`, `onValueChange` |
+| `Text` | Display | Themed text with semantic variants | `variant`: heading1, heading2, heading3, body, secondary, success, error, mono, mono-secondary; `size`: xs, sm, base, lg; `as` |
+| `Toast` / `Toasty` | Feedback | Toast notification system | Wrap app with `<Toasty>`, use `Toast.useToastManager().notify()` |
+| `Tooltip` | Overlay | Hover/focus tooltip | `content`, `side`, `align`, `asChild` |
+
+## Semantic Token Reference
+
+### Surface Hierarchy
+| Token | Purpose |
+|-------|---------|
+| `bg-reki-canvas` | The outermost page background — sits behind everything |
+| `bg-reki-base` | Default component background |
+| `bg-reki-elevated` | Slightly elevated surface, e.g. `LayerCard.Secondary` |
+| `bg-reki-recessed` | Recessed surface with a subtly darker fill, e.g. segmented `Tabs` background |
+| `bg-reki-tint` | Subtle tinted background for tables or hover states |
+| `bg-reki-contrast` | High-contrast, inverted background |
+
+### Brand
+| Token | Purpose |
+|-------|---------|
+| `bg-reki-brand` | Primary brand background |
+| `bg-reki-brand-hover` | Hover state for brand backgrounds |
+
+### Semantic Status Colors
+| Token | Purpose |
+|-------|---------|
+| `bg-reki-info` | Info indicator (icon, dot, bar) |
+| `bg-reki-success` | Success indicator |
+| `bg-reki-warning` | Warning indicator |
+| `bg-reki-danger` | Error/destructive indicator |
+
+Use the solid token on icons, status dots, and progress fills. Banners and badges use the solid fills with a reduced opacity.
+
+### Text Colors
+| Token | Purpose |
+|-------|---------|
+| `text-reki-default` | Primary body text |
+| `text-reki-strong` | Secondary text with slightly less contrast than default |
+| `text-reki-subtle` | Muted text for descriptions, captions, or secondary labels |
+| `text-reki-inactive` | Disabled or inactive text |
+| `text-reki-placeholder` | Placeholder text in inputs |
+| `text-reki-inverse` | Text intended for use on high-contrast or inverted backgrounds |
+| `text-reki-link` | Link text |
+| `text-reki-info` | Info-colored text |
+| `text-reki-success` | Success-colored text |
+| `text-reki-warning` | Warning-colored text |
+| `text-reki-danger` | Error/destructive text |
+
+### Borders & Rings
+| Token | Purpose |
+|-------|---------|
+| `reki-hairline` | A border/ring color to distinguish between flat surfaces where no shadow is present (i.e. `LayerCard`). |
+| `reki-line` | A thicker border/ring color that defines the edge of an elevated surface alongside a shadow. |
+
+## Icons
+
+Reki uses **[Phosphor Icons](https://phosphoricons.com/)** via `@phosphor-icons/react`:
+
+```tsx
+import { PlusIcon, TrashIcon, GearIcon } from "@phosphor-icons/react";
+
+<Button icon={PlusIcon}>Add Worker</Button>
+<DropdownMenu.Item icon={TrashIcon} variant="danger">Delete</DropdownMenu.Item>
+```
+
+## Controlled State Reference
+
+| Component | Value Prop | Change Callback | Default Prop |
+|-----------|-----------|-----------------|-------------|
+| `Input` | `value` | `onChange` | `defaultValue` |
+| `Select` | `value` | `onValueChange` | `defaultValue` |
+| `Combobox` | `value` | `onValueChange` | `defaultValue` |
+| `Switch` | `checked` | `onCheckedChange` | `defaultChecked` |
+| `Checkbox` | `checked` | `onCheckedChange` | `defaultChecked` |
+| `Checkbox.Group` | `value` | `onValueChange` | `defaultValue` |
+| `Radio.Group` | `value` | `onValueChange` | `defaultValue` |
+| `Tabs` | `value` | `onValueChange` | `selectedValue` |
+
+## Common Patterns
+
+### Field Wrapper (label + description + error)
+Most input components accept `label`, `description`, and `error` props that automatically wrap the input in a `<Field>`:
+
+```tsx
+<Input label="Email" description="We'll never share your email" error="Required" variant="error" />
+<Select label="Region" hideLabel={false} error="Please select a region">
+  <Select.Option value="us">US East</Select.Option>
+  <Select.Option value="eu">EU West</Select.Option>
+</Select>
+<Combobox label="Tags" items={tags} multiple />
+```
+
+> **Note:** `Select` defaults to `hideLabel={true}` (label is screen-reader only). Pass `hideLabel={false}` for a visible label.
+
+### Compound Components
+Many components use a compound/dot-notation API via `Object.assign`:
+
+```tsx
+<Dialog.Root>
+  <Dialog.Trigger render={(p) => <Button {...p}>Open</Button>} />
+  <Dialog size="lg" className="p-8">
+    <Dialog.Title>Confirm</Dialog.Title>
+    <Dialog.Description>Are you sure?</Dialog.Description>
+    <Dialog.Close render={(p) => <Button {...p}>Cancel</Button>} />
+  </Dialog>
+</Dialog.Root>
+```
+
+### Loading States
+Buttons support a `loading` prop that shows a spinner and disables interaction:
+
+```tsx
+<Button loading>Saving...</Button>
+```
+
+### Polymorphic Rendering
+Some components accept an `as` prop or Base UI's `render` prop:
+
+```tsx
+<Surface as="section" variant="raised">Content</Surface>
+<Text variant="heading1" as="h2">Custom heading level</Text>
+<Dialog.Trigger render={(p) => <Button {...p}>Open</Button>} />
+```
+
+## Full Registry
+
+For complete prop details, variant values, Tailwind classes, and code examples for every component, see:
+
+```
+@cloudraker/reki/ai/component-registry.json
+```
+
+This JSON file contains structured metadata for all components, optimized for AI/agent consumption.