xertica-ui 2.2.1 → 2.3.0

package/docs/ai-usage.md

@@ -1,195 +1,195 @@
-# AI Agent Usage Manual — Xertica UI
-
-> This document is addressed **exclusively to AI agents** (LLMs) operating on projects that use `xertica-ui`. Developers may also read it to understand constraints the system enforces.
-
----
-
-## 1. Knowledge Extraction Protocol
-
-Your knowledge about the library must come from these sources, in priority order:
-
-1. **`docs/llms.md`** — Start here. It contains the component catalog index and critical rules.
-2. **`docs/components/*.md`** — Component-specific documentation with full prop tables and examples.
-3. **`docs/patterns/*.md`** — Pre-validated layout patterns for common page types.
-4. **`components/ui/*.tsx` source files** — Read the TSDoc annotations on interfaces before using any component.
-
-> **Reading source code is for understanding prop contracts, not for remixing implementations.** Do not derive alternative versions of components from the source.
-
----
-
-## 2. Strict Rules
-
-### 2.1 Native HTML Elements Are Forbidden for UI Surfaces
-
-| ❌ Forbidden             | ✅ Required                            |
-| ------------------------ | -------------------------------------- |
-| `<button>`               | `<Button>` from `xertica-ui`           |
-| `<input>`                | `<Input>` from `xertica-ui`            |
-| `<div className="card">` | `<Card>` from `xertica-ui`             |
-| `<a>` for actions        | `<Button asChild>` wrapping a `<Link>` |
-| `<select>`               | `<Select>` from `xertica-ui`           |
-| `<textarea>`             | `<Textarea>` from `xertica-ui`         |
-
-If a validation engine reports `<button> inserted illegally`, it means you used a native HTML element. The fix is to replace it with the `xertica-ui` counterpart — **not to wrap it**.
-
-### 2.2 SVGs and Icons
-
-Never generate raw SVG markup (`<svg><path .../></svg>`). Always use `lucide-react`:
-
-```tsx
-// ❌ Never do this
-<svg xmlns="http://www.w3.org/2000/svg" ...><path .../></svg>
-
-// ✅ Always do this
-import { Settings, Home, LogOut } from 'lucide-react';
-<Settings className="w-4 h-4" />
-```
-
-The standard icon size in UI controls is `w-4 h-4` (`16px`). In hero or empty states, `w-8 h-8` or `w-12 h-12` is acceptable.
-
-### 2.3 Color Tokens — Context-Dependent Rules
-
-Color usage depends on the **semantic context** of the element:
-
-**Always forbidden (all contexts):**
-
-```tsx
-// ❌ Never use raw hex or rgb() values
-<div style={{ backgroundColor: '#3B82F6' }}>
-<div style={{ color: 'rgb(59, 130, 246)' }}>
-```
-
-**Required for semantic/status contexts** (errors, warnings, success states, status badges, danger actions):
-
-```tsx
-// ❌ Wrong — non-semantic color for a semantic state
-<div className="bg-red-500 text-white">Error</div>
-
-// ✅ Required — semantic token responds to theme and dark mode
-<div className="bg-destructive text-destructive-foreground">Error</div>
-```
-
-**Acceptable for layout and general non-semantic UI** (custom components, Storybook stories, decorative elements where no semantic token applies):
-
-```tsx
-// ✅ Acceptable — non-semantic context, no theme dependency needed
-<div className="bg-blue-500 text-white border-gray-200">Custom UI</div>
-
-// ✅ Required for semantic contexts
-<div className="bg-primary text-primary-foreground border-border">Action</div>
-```
-
-The only additional exception is within chart configurations (`recharts`) where literal colors may be required for data series styling.
-
-### 2.4 Prop Inference
-
-Do not assume all native HTML props are forwarded by a Xertica UI component. Some are intentionally blocked by the component's design. Always check the prop table in the component's `.md` file before using a prop.
-
----
-
-## 3. Component Validation Checklist
-
-Before generating code that uses a Xertica UI component, verify:
-
-- [ ] The component is exported from `xertica-ui` (check `docs/llms.md` catalog)
-- [ ] All required props are provided (check the component's `## Props` table)
-- [ ] All passed props are documented — do not invent props
-- [ ] Icons come from `lucide-react`, not inline SVG
-- [ ] Colors use semantic token classes, not raw values
-- [ ] The component is not re-implemented from scratch with Tailwind classes
-
----
-
-## 4. Layout System Rules
-
-The layout state is managed globally by `LayoutContext`. **Never manage sidebar or layout state locally.**
-
-```tsx
-import { useLayout } from 'xertica-ui/hooks';
-
-const { sidebarExpanded, sidebarWidth, toggleSidebar } = useLayout();
-```
-
-The `sidebarWidth` value drives `padding-left` on the main content container:
-
-```tsx
-<div style={{ paddingLeft: sidebarExpanded ? `${sidebarWidth}px` : '80px' }}>
-```
-
-Do not hardcode `pl-64` or `padding-left: 280px`. Read `docs/layout.md` for details.
-
----
-
-## 5. Form Validation Rules
-
-Forms must use `react-hook-form` + `zod`. Never implement manual validation logic.
-
-```tsx
-// ❌ Never do this
-const [error, setError] = useState('');
-if (!email.includes('@')) setError('Invalid email');
-
-// ✅ Always do this
-const schema = z.object({ email: z.string().email() });
-// Errors flow automatically to <FormMessage />
-```
-
-See `docs/patterns/form.md` for the validated full form pattern.
-
----
-
-## 6. Routing Rules
-
-The library supports `react-router-dom` v6. Pass router hooks directly to components that need them:
-
-```tsx
-import { useNavigate, useLocation } from 'react-router-dom';
-
-const navigate = useNavigate();
-const location = useLocation();
-
-<Sidebar navigate={navigate} location={location} ... />
-```
-
-When mocking these in previews/tests, pass empty functions — never string literals:
-
-```tsx
-// ❌ Wrong
-<Sidebar navigate="/home" location="/home" />
-
-// ✅ Correct (mock)
-<Sidebar navigate={() => {}} location={{ pathname: '/home' }} />
-```
-
----
-
-## 7. Anti-Patterns Reference
-
-| Anti-Pattern                                   | Reason                                        | Fix                                       |
-| ---------------------------------------------- | --------------------------------------------- | ----------------------------------------- |
-| `<button>`                                     | Bypasses design system                        | Use `<Button>`                            |
-| `<div className="bg-white rounded shadow">`    | Duplicates Card logic                         | Use `<Card>`                              |
-| `text-red-500` for error states                | Non-semantic — won't adapt to theme/dark mode | Use `text-destructive`                    |
-| `bg-green-500` for success states              | Non-semantic — won't adapt to theme/dark mode | Use `bg-success`                          |
-| Hardcoded `pl-64` for layout                   | Breaks dynamic width                          | Use `sidebarWidth` from `useLayout()`     |
-| Manually managing sidebar state                | Defeats context                               | Use `useLayout()`                         |
-| Custom SVG icons                               | Inconsistent style                            | Use `lucide-react`                        |
-| `style={{ color: '#...' }}`                    | Non-themeable raw value                       | Use semantic token classes                |
-| `#3b82f6` or `rgb(...)` in any className/style | Non-themeable raw value                       | Use semantic tokens or Tailwind utilities |
-| Inventing new component variants               | Breaks design system                          | Use only documented variants              |
-| Wrapping `<XerticaProvider>` per component     | Performance issue                             | Wrap once at app root                     |
-
----
-
-## 8. Emergency Debug Checklist
-
-If components appear unstyled (transparent backgrounds, no borders):
-
-1. Verify `import 'xertica-ui/style.css'` exists in `main.tsx` or `App.tsx`
-2. Verify `<XerticaProvider>` wraps the app root
-3. Verify Tailwind CSS is configured to scan `xertica-ui` files (if using custom setup)
-
-If dialogs/modals don't appear:
-
-1. Verify `<XerticaProvider>` is present (it renders the Radix portal container)
-2. Check that `Toaster` is included (it's auto-injected by `XerticaProvider`)
+# AI Agent Usage Manual — Xertica UI
+
+> This document is addressed **exclusively to AI agents** (LLMs) operating on projects that use `xertica-ui`. Developers may also read it to understand constraints the system enforces.
+
+---
+
+## 1. Knowledge Extraction Protocol
+
+Your knowledge about the library must come from these sources, in priority order:
+
+1. **`docs/llms.md`** — Start here. It contains the component catalog index and critical rules.
+2. **`docs/components/*.md`** — Component-specific documentation with full prop tables and examples.
+3. **`docs/patterns/*.md`** — Pre-validated layout patterns for common page types.
+4. **`components/ui/*.tsx` source files** — Read the TSDoc annotations on interfaces before using any component.
+
+> **Reading source code is for understanding prop contracts, not for remixing implementations.** Do not derive alternative versions of components from the source.
+
+---
+
+## 2. Strict Rules
+
+### 2.1 Native HTML Elements Are Forbidden for UI Surfaces
+
+| ❌ Forbidden             | ✅ Required                            |
+| ------------------------ | -------------------------------------- |
+| `<button>`               | `<Button>` from `xertica-ui`           |
+| `<input>`                | `<Input>` from `xertica-ui`            |
+| `<div className="card">` | `<Card>` from `xertica-ui`             |
+| `<a>` for actions        | `<Button asChild>` wrapping a `<Link>` |
+| `<select>`               | `<Select>` from `xertica-ui`           |
+| `<textarea>`             | `<Textarea>` from `xertica-ui`         |
+
+If a validation engine reports `<button> inserted illegally`, it means you used a native HTML element. The fix is to replace it with the `xertica-ui` counterpart — **not to wrap it**.
+
+### 2.2 SVGs and Icons
+
+Never generate raw SVG markup (`<svg><path .../></svg>`). Always use `lucide-react`:
+
+```tsx
+// ❌ Never do this
+<svg xmlns="http://www.w3.org/2000/svg" ...><path .../></svg>
+
+// ✅ Always do this
+import { Settings, Home, LogOut } from 'lucide-react';
+<Settings className="w-4 h-4" />
+```
+
+The standard icon size in UI controls is `w-4 h-4` (`16px`). In hero or empty states, `w-8 h-8` or `w-12 h-12` is acceptable.
+
+### 2.3 Color Tokens — Context-Dependent Rules
+
+Color usage depends on the **semantic context** of the element:
+
+**Always forbidden (all contexts):**
+
+```tsx
+// ❌ Never use raw hex or rgb() values
+<div style={{ backgroundColor: '#3B82F6' }}>
+<div style={{ color: 'rgb(59, 130, 246)' }}>
+```
+
+**Required for semantic/status contexts** (errors, warnings, success states, status badges, danger actions):
+
+```tsx
+// ❌ Wrong — non-semantic color for a semantic state
+<div className="bg-red-500 text-white">Error</div>
+
+// ✅ Required — semantic token responds to theme and dark mode
+<div className="bg-destructive text-destructive-foreground">Error</div>
+```
+
+**Acceptable for layout and general non-semantic UI** (custom components, Storybook stories, decorative elements where no semantic token applies):
+
+```tsx
+// ✅ Acceptable — non-semantic context, no theme dependency needed
+<div className="bg-blue-500 text-white border-gray-200">Custom UI</div>
+
+// ✅ Required for semantic contexts
+<div className="bg-primary text-primary-foreground border-border">Action</div>
+```
+
+The only additional exception is within chart configurations (`recharts`) where literal colors may be required for data series styling.
+
+### 2.4 Prop Inference
+
+Do not assume all native HTML props are forwarded by a Xertica UI component. Some are intentionally blocked by the component's design. Always check the prop table in the component's `.md` file before using a prop.
+
+---
+
+## 3. Component Validation Checklist
+
+Before generating code that uses a Xertica UI component, verify:
+
+- [ ] The component is exported from `xertica-ui` (check `docs/llms.md` catalog)
+- [ ] All required props are provided (check the component's `## Props` table)
+- [ ] All passed props are documented — do not invent props
+- [ ] Icons come from `lucide-react`, not inline SVG
+- [ ] Colors use semantic token classes, not raw values
+- [ ] The component is not re-implemented from scratch with Tailwind classes
+
+---
+
+## 4. Layout System Rules
+
+The layout state is managed globally by `LayoutContext`. **Never manage sidebar or layout state locally.**
+
+```tsx
+import { useLayout } from 'xertica-ui/hooks';
+
+const { sidebarExpanded, sidebarWidth, toggleSidebar } = useLayout();
+```
+
+The `sidebarWidth` value drives `padding-left` on the main content container:
+
+```tsx
+<div style={{ paddingLeft: sidebarExpanded ? `${sidebarWidth}px` : '80px' }}>
+```
+
+Do not hardcode `pl-64` or `padding-left: 280px`. Read `docs/layout.md` for details.
+
+---
+
+## 5. Form Validation Rules
+
+Forms must use `react-hook-form` + `zod`. Never implement manual validation logic.
+
+```tsx
+// ❌ Never do this
+const [error, setError] = useState('');
+if (!email.includes('@')) setError('Invalid email');
+
+// ✅ Always do this
+const schema = z.object({ email: z.string().email() });
+// Errors flow automatically to <FormMessage />
+```
+
+See `docs/patterns/form.md` for the validated full form pattern.
+
+---
+
+## 6. Routing Rules
+
+The library supports `react-router-dom` v6. Pass router hooks directly to components that need them:
+
+```tsx
+import { useNavigate, useLocation } from 'react-router-dom';
+
+const navigate = useNavigate();
+const location = useLocation();
+
+<Sidebar navigate={navigate} location={location} ... />
+```
+
+When mocking these in previews/tests, pass empty functions — never string literals:
+
+```tsx
+// ❌ Wrong
+<Sidebar navigate="/home" location="/home" />
+
+// ✅ Correct (mock)
+<Sidebar navigate={() => {}} location={{ pathname: '/home' }} />
+```
+
+---
+
+## 7. Anti-Patterns Reference
+
+| Anti-Pattern                                   | Reason                                        | Fix                                       |
+| ---------------------------------------------- | --------------------------------------------- | ----------------------------------------- |
+| `<button>`                                     | Bypasses design system                        | Use `<Button>`                            |
+| `<div className="bg-white rounded shadow">`    | Duplicates Card logic                         | Use `<Card>`                              |
+| `text-red-500` for error states                | Non-semantic — won't adapt to theme/dark mode | Use `text-destructive`                    |
+| `bg-green-500` for success states              | Non-semantic — won't adapt to theme/dark mode | Use `bg-success`                          |
+| Hardcoded `pl-64` for layout                   | Breaks dynamic width                          | Use `sidebarWidth` from `useLayout()`     |
+| Manually managing sidebar state                | Defeats context                               | Use `useLayout()`                         |
+| Custom SVG icons                               | Inconsistent style                            | Use `lucide-react`                        |
+| `style={{ color: '#...' }}`                    | Non-themeable raw value                       | Use semantic token classes                |
+| `#3b82f6` or `rgb(...)` in any className/style | Non-themeable raw value                       | Use semantic tokens or Tailwind utilities |
+| Inventing new component variants               | Breaks design system                          | Use only documented variants              |
+| Wrapping `<XerticaProvider>` per component     | Performance issue                             | Wrap once at app root                     |
+
+---
+
+## 8. Emergency Debug Checklist
+
+If components appear unstyled (transparent backgrounds, no borders):
+
+1. Verify `import 'xertica-ui/style.css'` exists in `main.tsx` or `App.tsx`
+2. Verify `<XerticaProvider>` wraps the app root
+3. Verify Tailwind CSS is configured to scan `xertica-ui` files (if using custom setup)
+
+If dialogs/modals don't appear:
+
+1. Verify `<XerticaProvider>` is present (it renders the Radix portal container)
+2. Check that `Toaster` is included (it's auto-injected by `XerticaProvider`)

package/docs/components/accordion.md

@@ -1,109 +1,109 @@
-# Accordion
-
-## Overview
-
-A vertically stacked set of collapsible sections. Each section has a clickable trigger header that reveals or hides its content. Ideal for FAQs, configuration settings, and dense navigation trees where only one (or a few) section needs to be visible at a time.
-
----
-
-## When to Use
-
-- FAQ sections
-- Settings panels with multiple categories
-- Navigable tree structures inside a sidebar
-- Reducing visual density by hiding supplementary information
-
-## When NOT to Use
-
-- Switching between views — use `<Tabs>` instead.
-- A single expandable section — use `<Collapsible>` instead.
-
----
-
-## Anatomy
-
-```
-<Accordion type="single" collapsible>
-  <AccordionItem value="item-1">
-    <AccordionTrigger>Question or Title</AccordionTrigger>
-    <AccordionContent>Content that is revealed</AccordionContent>
-  </AccordionItem>
-</Accordion>
-```
-
----
-
-## Props
-
-### Accordion
-
-| Prop            | Type                     | Default | Required | Description                                                           |
-| --------------- | ------------------------ | ------- | -------- | --------------------------------------------------------------------- |
-| `type`          | `'single' \| 'multiple'` | —       | **Yes**  | Single: one open at a time. Multiple: all can be open simultaneously. |
-| `collapsible`   | `boolean`                | `false` | No       | When `type="single"`, allows closing the open item by re-clicking.    |
-| `defaultValue`  | `string \| string[]`     | —       | No       | Initially open item(s)                                                |
-| `value`         | `string \| string[]`     | —       | No       | Controlled open item(s)                                               |
-| `onValueChange` | `(v) => void`            | —       | No       | Change handler                                                        |
-
-### AccordionItem
-
-| Prop    | Type     | Required | Description                     |
-| ------- | -------- | -------- | ------------------------------- |
-| `value` | `string` | **Yes**  | Unique identifier for this item |
-
----
-
-## Examples
-
-### FAQ (Single, Collapsible)
-
-```tsx
-import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from 'xertica-ui/ui';
-
-<Accordion type="single" collapsible className="w-full">
-  <AccordionItem value="q-1">
-    <AccordionTrigger>Is this library accessible?</AccordionTrigger>
-    <AccordionContent>
-      Yes. Built entirely on Radix UI with full ARIA support and keyboard navigation.
-    </AccordionContent>
-  </AccordionItem>
-  <AccordionItem value="q-2">
-    <AccordionTrigger>How do I apply custom styles?</AccordionTrigger>
-    <AccordionContent>
-      Override the `className` on triggers or content. Classes are merged via `tailwind-merge`.
-    </AccordionContent>
-  </AccordionItem>
-</Accordion>;
-```
-
-### Multiple Open
-
-```tsx
-<Accordion type="multiple">
-  <AccordionItem value="notifications">
-    <AccordionTrigger>Notification Settings</AccordionTrigger>
-    <AccordionContent>{/* switches */}</AccordionContent>
-  </AccordionItem>
-  <AccordionItem value="privacy">
-    <AccordionTrigger>Privacy Settings</AccordionTrigger>
-    <AccordionContent>{/* options */}</AccordionContent>
-  </AccordionItem>
-</Accordion>
-```
-
----
-
-## AI Rules
-
-- `AccordionItem` **requires** a unique non-empty `value` string — without it, open/close tracking breaks.
-- The animated `ChevronDown` icon is **already built into** `AccordionTrigger`. Do not add another chevron icon.
-- `type` is **required** — never omit it.
-- Use `type="single" collapsible` for FAQ-style lists. Use `type="multiple"` for settings panels where users may need multiple sections open.
-- Do not use Accordion for switching primary views — use `Tabs` for that.
-
----
-
-## Related Components
-
-- [`Collapsible`](./collapsible.md) — For a single expandable section
-- [`Tabs`](./tabs.md) — For view switching
+# Accordion
+
+## Overview
+
+A vertically stacked set of collapsible sections. Each section has a clickable trigger header that reveals or hides its content. Ideal for FAQs, configuration settings, and dense navigation trees where only one (or a few) section needs to be visible at a time.
+
+---
+
+## When to Use
+
+- FAQ sections
+- Settings panels with multiple categories
+- Navigable tree structures inside a sidebar
+- Reducing visual density by hiding supplementary information
+
+## When NOT to Use
+
+- Switching between views — use `<Tabs>` instead.
+- A single expandable section — use `<Collapsible>` instead.
+
+---
+
+## Anatomy
+
+```
+<Accordion type="single" collapsible>
+  <AccordionItem value="item-1">
+    <AccordionTrigger>Question or Title</AccordionTrigger>
+    <AccordionContent>Content that is revealed</AccordionContent>
+  </AccordionItem>
+</Accordion>
+```
+
+---
+
+## Props
+
+### Accordion
+
+| Prop            | Type                     | Default | Required | Description                                                           |
+| --------------- | ------------------------ | ------- | -------- | --------------------------------------------------------------------- |
+| `type`          | `'single' \| 'multiple'` | —       | **Yes**  | Single: one open at a time. Multiple: all can be open simultaneously. |
+| `collapsible`   | `boolean`                | `false` | No       | When `type="single"`, allows closing the open item by re-clicking.    |
+| `defaultValue`  | `string \| string[]`     | —       | No       | Initially open item(s)                                                |
+| `value`         | `string \| string[]`     | —       | No       | Controlled open item(s)                                               |
+| `onValueChange` | `(v) => void`            | —       | No       | Change handler                                                        |
+
+### AccordionItem
+
+| Prop    | Type     | Required | Description                     |
+| ------- | -------- | -------- | ------------------------------- |
+| `value` | `string` | **Yes**  | Unique identifier for this item |
+
+---
+
+## Examples
+
+### FAQ (Single, Collapsible)
+
+```tsx
+import { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from 'xertica-ui/ui';
+
+<Accordion type="single" collapsible className="w-full">
+  <AccordionItem value="q-1">
+    <AccordionTrigger>Is this library accessible?</AccordionTrigger>
+    <AccordionContent>
+      Yes. Built entirely on Radix UI with full ARIA support and keyboard navigation.
+    </AccordionContent>
+  </AccordionItem>
+  <AccordionItem value="q-2">
+    <AccordionTrigger>How do I apply custom styles?</AccordionTrigger>
+    <AccordionContent>
+      Override the `className` on triggers or content. Classes are merged via `tailwind-merge`.
+    </AccordionContent>
+  </AccordionItem>
+</Accordion>;
+```
+
+### Multiple Open
+
+```tsx
+<Accordion type="multiple">
+  <AccordionItem value="notifications">
+    <AccordionTrigger>Notification Settings</AccordionTrigger>
+    <AccordionContent>{/* switches */}</AccordionContent>
+  </AccordionItem>
+  <AccordionItem value="privacy">
+    <AccordionTrigger>Privacy Settings</AccordionTrigger>
+    <AccordionContent>{/* options */}</AccordionContent>
+  </AccordionItem>
+</Accordion>
+```
+
+---
+
+## AI Rules
+
+- `AccordionItem` **requires** a unique non-empty `value` string — without it, open/close tracking breaks.
+- The animated `ChevronDown` icon is **already built into** `AccordionTrigger`. Do not add another chevron icon.
+- `type` is **required** — never omit it.
+- Use `type="single" collapsible` for FAQ-style lists. Use `type="multiple"` for settings panels where users may need multiple sections open.
+- Do not use Accordion for switching primary views — use `Tabs` for that.
+
+---
+
+## Related Components
+
+- [`Collapsible`](./collapsible.md) — For a single expandable section
+- [`Tabs`](./tabs.md) — For view switching