xertica-ui 2.2.1 → 2.4.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`)