@usevyre/ai-context 1.3.0 → 1.4.0

package/dist/schema.json

@@ -1,14 +1,69 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "version": "1.6.0",
+  "version": "1.16.0",
   "generatedAt": "2026-05-18",
   "package": "@usevyre/react",
-  "packageVersion": "1.6.0",
+  "packageVersion": "1.16.0",
   "validFor": [
     "@usevyre/react@1.1.0+",
     "@usevyre/vue@1.1.0+"
   ],
   "changelog": {
+    "1.16.0": {
+      "date": "2026-05-18",
+      "breaking": false,
+      "summary": "Added Carousel + CarouselSlide: accessible controlled content slider with snap scrolling, dot indicators, prev/next arrows, keyboard navigation, optional loop and autoPlay (pauses on hover/focus). Completes the post-1.3 backlog (10/10 components)."
+    },
+    "1.15.0": {
+      "date": "2026-05-18",
+      "breaking": false,
+      "summary": "Added OTPInput: segmented one-time-code input for 2FA/verification with controlled string value, paste-aware fill, auto-advance/backspace, arrow keys, onComplete, type (numeric/alphanumeric), mask and sizes."
+    },
+    "1.14.0": {
+      "date": "2026-05-18",
+      "breaking": false,
+      "summary": "Added Tree: data-driven, controlled hierarchical tree view (file explorer / nested nav) with recursive rendering, controlled expanded/selected state, and full keyboard navigation."
+    },
+    "1.13.0": {
+      "date": "2026-05-18",
+      "breaking": false,
+      "summary": "Added Timeline + TimelineItem: vertical activity feed for audit logs/history with status-colored markers, connector line, and items[] or composable children for rich content."
+    },
+    "1.12.1": {
+      "date": "2026-05-18",
+      "breaking": false,
+      "summary": "Fix Stat: the arrow direction now follows the sign of `delta` (the actual change) instead of `trend`. `trend` controls only the color. So a falling 'lower is better' metric correctly shows a green DOWN arrow."
+    },
+    "1.12.0": {
+      "date": "2026-05-18",
+      "breaking": false,
+      "summary": "Added Stat + StatGroup: presentational dashboard KPI with an explicit trend (up/down/neutral) that controls the delta color, sizes, optional icon, and an evenly-split StatGroup row."
+    },
+    "1.11.0": {
+      "date": "2026-05-18",
+      "breaking": false,
+      "summary": "Added EmptyState: presentational placeholder for empty lists/tables/search with preset variant icons (default/search/error), sizes, and a composed call-to-action."
+    },
+    "1.10.0": {
+      "date": "2026-05-18",
+      "breaking": false,
+      "summary": "Added Stepper + StepperNav + Step + StepPanel: controlled multi-step flow (0-based index) for wizards/onboarding/checkout, horizontal or vertical, with automatic completed/current/upcoming states and optional clickable back-navigation."
+    },
+    "1.9.0": {
+      "date": "2026-05-18",
+      "breaking": false,
+      "summary": "Added ToggleGroup + ToggleItem: controlled segmented control with single/multiple modes (value adapts: string|null vs string[]), options[] or composable children, keyboard navigation. Emits the value, not an event."
+    },
+    "1.8.0": {
+      "date": "2026-05-18",
+      "breaking": false,
+      "summary": "Added NumberInput: controlled numeric input with −/+ stepper, min/max/step/precision, clamp-on-blur and keyboard stepping. Emits number|null (not an event) and composes directly with Form/FormField."
+    },
+    "1.7.0": {
+      "date": "2026-05-18",
+      "breaking": false,
+      "summary": "Added Form + FormField: controlled, data-driven, zero-dependency form with built-in validation rules (required/minLength/maxLength/min/max/pattern/email/custom) that map errors into Field automatically."
+    },
     "1.6.0": {
       "date": "2026-05-18",
       "breaking": false,
@@ -2915,6 +2970,923 @@
         }
       ]
     },
+    "Form": {
+      "description": "Controlled, data-driven form. Zero dependencies. Validation runs on submit and (after the first submit) on blur. Errors map into the wrapped Field automatically (state=error + hint=message). Compose with FormField, which wires name/value/onChange/onBlur into a single control child.",
+      "import": "import { Form, FormField } from \"@usevyre/react\"",
+      "subcomponents": [
+        "FormField"
+      ],
+      "props": {
+        "values": {
+          "type": "Record<string, any>",
+          "description": "Controlled values map. Omit for uncontrolled (use defaultValues)."
+        },
+        "defaultValues": {
+          "type": "Record<string, any>",
+          "description": "Initial values when uncontrolled"
+        },
+        "onChange": {
+          "type": "function",
+          "description": "(values) => void — called whenever any field value changes"
+        },
+        "onSubmit": {
+          "type": "function",
+          "description": "(values) => void | Promise<void> — called ONLY when the form is valid"
+        },
+        "onInvalid": {
+          "type": "function",
+          "description": "(errors: Record<string,string>) => void — called when submitted but invalid"
+        }
+      },
+      "antiPatterns": [
+        {
+          "pattern": "Manually tracking each field's error state with useState",
+          "reason": "Form already validates and maps errors into Field automatically",
+          "fix": "Wrap controls in <FormField name rules> and let Form manage errors"
+        },
+        {
+          "pattern": "Adding a validation library (zod/yup) just for basic rules",
+          "reason": "Form ships zero-dependency built-in rules",
+          "fix": "Use rules={{ required, minLength, pattern, email, validate }}"
+        },
+        {
+          "pattern": "<FormField> with multiple control children",
+          "reason": "FormField clones a single child to inject name/value/onChange",
+          "fix": "Use one control per FormField (Input/Textarea/Select/etc.)"
+        },
+        {
+          "pattern": "<FormField> outside a <Form>",
+          "reason": "FormField reads form context",
+          "fix": "Always nest FormField inside <Form>"
+        }
+      ],
+      "examples": [
+        {
+          "description": "Controlled sign-in form with built-in rules",
+          "code": "const [values, setValues] = useState({ email: \"\", password: \"\" });\n\n<Form values={values} onChange={setValues} onSubmit={(v) => signIn(v)}>\n  <FormField name=\"email\" label=\"Email\" rules={{ required: true, email: true }}>\n    <Input type=\"email\" />\n  </FormField>\n  <FormField name=\"password\" label=\"Password\" rules={{ required: true, minLength: 8 }}>\n    <Input type=\"password\" />\n  </FormField>\n  <Button type=\"submit\" variant=\"primary\">Sign in</Button>\n</Form>"
+        },
+        {
+          "description": "Custom cross-field validation",
+          "code": "<FormField\n  name=\"confirm\"\n  label=\"Confirm password\"\n  rules={{\n    required: true,\n    validate: (v, all) => v === all.password ? null : \"Passwords do not match\",\n  }}\n>\n  <Input type=\"password\" />\n</FormField>"
+        }
+      ]
+    },
+    "FormField": {
+      "description": "A single labelled, validated field inside <Form>. Injects name/value/onChange/onBlur into its one control child and wraps it in <Field> (label + error state + hint).",
+      "import": "import { FormField } from \"@usevyre/react\"",
+      "props": {
+        "name": {
+          "type": "string",
+          "description": "Key into the form's values map (required)"
+        },
+        "label": {
+          "type": "string",
+          "description": "Label rendered by the wrapping Field"
+        },
+        "hint": {
+          "type": "string",
+          "description": "Helper text shown when there is no error"
+        },
+        "rules": {
+          "type": "object",
+          "description": "{ required?: boolean|string, minLength?, maxLength?, min?, max?: number, pattern?: RegExp, email?: boolean, validate?: (value, allValues) => string|null }"
+        }
+      },
+      "antiPatterns": [
+        {
+          "pattern": "Putting onChange/value manually on the control inside FormField",
+          "reason": "FormField already injects them; manual props can desync from form state",
+          "fix": "Let FormField wire the control; only pass static props (type, placeholder)"
+        }
+      ],
+      "examples": [
+        {
+          "description": "Field with a hint",
+          "code": "<FormField name=\"bio\" label=\"Bio\" hint=\"Max 200 characters\" rules={{ maxLength: 200 }}>\n  <Textarea />\n</FormField>"
+        }
+      ]
+    },
+    "NumberInput": {
+      "description": "Controlled numeric input with −/+ stepper buttons. onChange emits a NUMBER (or null when empty) — NOT an event. Drops straight into <FormField> (Form handles the non-event value). Clamps to min/max on blur; keyboard ArrowUp/Down ±step, Shift+Arrow ±step×10.",
+      "import": "import { NumberInput } from \"@usevyre/react\"",
+      "props": {
+        "value": {
+          "type": "number | null",
+          "description": "Controlled value. null = empty. Omit for uncontrolled."
+        },
+        "defaultValue": {
+          "type": "number | null",
+          "default": "null",
+          "description": "Initial value when uncontrolled"
+        },
+        "onChange": {
+          "type": "function",
+          "description": "(value: number | null) => void — emits the parsed number, or null when empty"
+        },
+        "min": {
+          "type": "number",
+          "description": "Minimum; value is clamped to this on blur"
+        },
+        "max": {
+          "type": "number",
+          "description": "Maximum; value is clamped to this on blur"
+        },
+        "step": {
+          "type": "number",
+          "default": 1,
+          "description": "Increment/decrement amount"
+        },
+        "precision": {
+          "type": "number",
+          "description": "Decimal places to round to"
+        },
+        "size": {
+          "type": "enum",
+          "values": [
+            "sm",
+            "md",
+            "lg"
+          ],
+          "default": "md",
+          "description": "Control size"
+        },
+        "disabled": {
+          "type": "boolean",
+          "default": false,
+          "description": "Disable input and steppers"
+        },
+        "readOnly": {
+          "type": "boolean",
+          "default": false,
+          "description": "Read-only (no stepping/typing)"
+        }
+      },
+      "antiPatterns": [
+        {
+          "pattern": "onChange={(e) => set(e.target.value)}",
+          "reason": "NumberInput emits a number, not an event — there is no e.target",
+          "fix": "onChange={(value) => set(value)} — value is number | null"
+        },
+        {
+          "pattern": "Using <Input type=\"number\"> for numeric fields",
+          "reason": "Native number input has no token-styled stepper, no clamp, returns a string",
+          "fix": "Use <NumberInput value onChange min max step />"
+        },
+        {
+          "pattern": "Parsing the value with Number() in form state",
+          "reason": "NumberInput already emits a real number (or null)",
+          "fix": "Store the value directly; it is already number | null"
+        }
+      ],
+      "examples": [
+        {
+          "description": "Quantity selector",
+          "code": "const [qty, setQty] = useState<number | null>(1);\n\n<NumberInput value={qty} onChange={setQty} min={1} max={99} />"
+        },
+        {
+          "description": "Inside a Form",
+          "code": "<FormField name=\"age\" label=\"Age\" rules={{ required: true, min: 18 }}>\n  <NumberInput min={0} max={120} />\n</FormField>"
+        }
+      ]
+    },
+    "ToggleGroup": {
+      "description": "Segmented control. CONTROLLED — the group owns the value. onChange emits the VALUE (not an event). type=single → value:string|null; type=multiple → value:string[]. Provide options[] for simple lists or <ToggleItem value> children for custom content. Distinct from Switch (boolean), ButtonGroup (layout only), RadioGroup (form radios, single only).",
+      "import": "import { ToggleGroup, ToggleItem } from \"@usevyre/react\"",
+      "subcomponents": [
+        "ToggleItem"
+      ],
+      "props": {
+        "type": {
+          "type": "enum",
+          "values": [
+            "single",
+            "multiple"
+          ],
+          "default": "single",
+          "description": "single → value string|null; multiple → value string[]"
+        },
+        "value": {
+          "type": "string | null | string[]",
+          "description": "Controlled selected value. string|null when single, string[] when multiple."
+        },
+        "onChange": {
+          "type": "function",
+          "description": "(value) => void — emits string|null (single) or string[] (multiple). NOT an event."
+        },
+        "options": {
+          "type": "array",
+          "description": "{ value: string; label?; icon?; disabled? }[] — alternative to ToggleItem children"
+        },
+        "size": {
+          "type": "enum",
+          "values": [
+            "sm",
+            "md",
+            "lg"
+          ],
+          "default": "md",
+          "description": "Control size"
+        },
+        "orientation": {
+          "type": "enum",
+          "values": [
+            "horizontal",
+            "vertical"
+          ],
+          "default": "horizontal",
+          "description": "Layout direction"
+        },
+        "disabled": {
+          "type": "boolean",
+          "default": false,
+          "description": "Disable the whole group"
+        }
+      },
+      "antiPatterns": [
+        {
+          "pattern": "onChange={(e) => set(e.target.value)}",
+          "reason": "ToggleGroup emits the value, not an event",
+          "fix": "onChange={(value) => set(value)} — string|null (single) or string[] (multiple)"
+        },
+        {
+          "pattern": "Using ToggleGroup for a single on/off setting",
+          "reason": "That is a boolean toggle",
+          "fix": "Use <Switch> for on/off; ToggleGroup is for choosing among options"
+        },
+        {
+          "pattern": "type=\"multiple\" with a string value",
+          "reason": "multiple mode requires an array value",
+          "fix": "value={['a','b']} and onChange receives string[]"
+        },
+        {
+          "pattern": "<ToggleItem> outside <ToggleGroup>",
+          "reason": "ToggleItem reads group context",
+          "fix": "Always nest ToggleItem inside ToggleGroup (or use options)"
+        }
+      ],
+      "examples": [
+        {
+          "description": "Single-select view switcher (options)",
+          "code": "const [view, setView] = useState<string | null>(\"grid\");\n\n<ToggleGroup\n  value={view}\n  onChange={setView}\n  options={[\n    { value: \"grid\", label: \"Grid\" },\n    { value: \"list\", label: \"List\" },\n  ]}\n/>"
+        },
+        {
+          "description": "Multiple-select formatting (composable)",
+          "code": "const [fmt, setFmt] = useState<string[]>([\"bold\"]);\n\n<ToggleGroup type=\"multiple\" value={fmt} onChange={setFmt}>\n  <ToggleItem value=\"bold\">B</ToggleItem>\n  <ToggleItem value=\"italic\">I</ToggleItem>\n  <ToggleItem value=\"underline\">U</ToggleItem>\n</ToggleGroup>"
+        }
+      ]
+    },
+    "ToggleItem": {
+      "description": "A single toggle button inside <ToggleGroup>. Reads selection state from the group via context.",
+      "import": "import { ToggleItem } from \"@usevyre/react\"",
+      "props": {
+        "value": {
+          "type": "string",
+          "description": "This item's value (required)"
+        },
+        "icon": {
+          "type": "ReactNode",
+          "description": "Optional leading icon"
+        },
+        "disabled": {
+          "type": "boolean",
+          "default": false,
+          "description": "Disable just this item"
+        }
+      },
+      "antiPatterns": [
+        {
+          "pattern": "Tracking selected state on ToggleItem yourself",
+          "reason": "Selection is owned by ToggleGroup",
+          "fix": "Only set value; the group controls selected state"
+        }
+      ],
+      "examples": [
+        {
+          "description": "Composable items",
+          "code": "<ToggleGroup value={v} onChange={setV}>\n  <ToggleItem value=\"left\">Left</ToggleItem>\n  <ToggleItem value=\"center\">Center</ToggleItem>\n</ToggleGroup>"
+        }
+      ]
+    },
+    "Stepper": {
+      "description": "Multi-step flow indicator + controller (onboarding/checkout/wizard). CONTROLLED by a 0-based index. Compose StepperNav (with Step indicators) and StepPanel (content shown when its index == active). Step/StepPanel take an explicit 0-based `index`. Not Tabs — Stepper is an ORDERED linear flow with completed/current/upcoming states.",
+      "import": "import { Stepper, StepperNav, Step, StepPanel } from \"@usevyre/react\"",
+      "subcomponents": [
+        "StepperNav",
+        "Step",
+        "StepPanel"
+      ],
+      "props": {
+        "value": {
+          "type": "number",
+          "description": "Controlled active step (0-based). Omit for uncontrolled."
+        },
+        "defaultValue": {
+          "type": "number",
+          "default": 0,
+          "description": "Initial active step when uncontrolled"
+        },
+        "onChange": {
+          "type": "function",
+          "description": "(index: number) => void — emits the new active index"
+        },
+        "orientation": {
+          "type": "enum",
+          "values": [
+            "horizontal",
+            "vertical"
+          ],
+          "default": "horizontal",
+          "description": "Layout direction"
+        },
+        "clickable": {
+          "type": "boolean",
+          "default": false,
+          "description": "Allow clicking a completed Step to jump back to it"
+        }
+      },
+      "antiPatterns": [
+        {
+          "pattern": "Using Tabs for a wizard / checkout flow",
+          "reason": "Tabs are peer panels; a step flow is ordered with completed/current/upcoming state",
+          "fix": "Use <Stepper> with StepperNav + Step + StepPanel"
+        },
+        {
+          "pattern": "onChange={(e) => set(e.target.value)}",
+          "reason": "Stepper emits the index number, not an event",
+          "fix": "onChange={(index) => setStep(index)}"
+        },
+        {
+          "pattern": "Manually toggling which panel is visible",
+          "reason": "StepPanel renders itself only when its index === active",
+          "fix": "Give each StepPanel an index; Stepper shows the active one"
+        },
+        {
+          "pattern": "<Step> or <StepPanel> outside <Stepper>",
+          "reason": "They read Stepper context",
+          "fix": "Nest Step inside StepperNav, StepPanel inside Stepper"
+        }
+      ],
+      "examples": [
+        {
+          "description": "Three-step wizard with Back/Next",
+          "code": "const [step, setStep] = useState(0);\n\n<Stepper value={step} onChange={setStep}>\n  <StepperNav>\n    <Step index={0} label=\"Account\" />\n    <Step index={1} label=\"Profile\" />\n    <Step index={2} label=\"Done\" />\n  </StepperNav>\n  <StepPanel index={0}><AccountForm /></StepPanel>\n  <StepPanel index={1}><ProfileForm /></StepPanel>\n  <StepPanel index={2}><Summary /></StepPanel>\n  <Stack direction=\"row\" gap=\"sm\" justify=\"between\">\n    <Button onClick={() => setStep((s) => s - 1)} disabled={step === 0}>Back</Button>\n    <Button variant=\"primary\" onClick={() => setStep((s) => s + 1)}>Next</Button>\n  </Stack>\n</Stepper>"
+        },
+        {
+          "description": "Vertical with descriptions",
+          "code": "<Stepper orientation=\"vertical\" defaultValue={1}>\n  <StepperNav>\n    <Step index={0} label=\"Cart\" description=\"2 items\" />\n    <Step index={1} label=\"Shipping\" description=\"Enter address\" />\n    <Step index={2} label=\"Payment\" />\n  </StepperNav>\n</Stepper>"
+        }
+      ]
+    },
+    "StepperNav": {
+      "description": "Container for Step indicators inside <Stepper>. Lays them out per the Stepper's orientation.",
+      "import": "import { Stepper, StepperNav, Step, StepPanel } from \"@usevyre/react\"",
+      "props": {}
+    },
+    "Step": {
+      "description": "One step indicator inside <StepperNav>. State (completed/current/upcoming) derives from the Stepper's active index automatically.",
+      "import": "import { Stepper, StepperNav, Step, StepPanel } from \"@usevyre/react\"",
+      "props": {
+        "index": {
+          "type": "number",
+          "description": "0-based position (required)"
+        },
+        "label": {
+          "type": "ReactNode",
+          "description": "Step label"
+        },
+        "description": {
+          "type": "ReactNode",
+          "description": "Secondary text under the label"
+        },
+        "icon": {
+          "type": "ReactNode",
+          "description": "Custom indicator content (defaults to number, or ✓ when completed)"
+        }
+      }
+    },
+    "StepPanel": {
+      "description": "Content for one step. Renders its children only when its index equals the Stepper's active step.",
+      "import": "import { Stepper, StepperNav, Step, StepPanel } from \"@usevyre/react\"",
+      "props": {
+        "index": {
+          "type": "number",
+          "description": "0-based position matching its Step (required)"
+        }
+      }
+    },
+    "EmptyState": {
+      "description": "Presentational placeholder for empty lists, tables, and search results. No state. title/description/variant/size are props; the optional call-to-action goes in children (React) or the default slot (Vue). variant picks a preset icon (default=box, search=magnifier, error=warning); pass `icon` (or #icon slot) to override.",
+      "import": "import { EmptyState } from \"@usevyre/react\"",
+      "props": {
+        "title": {
+          "type": "string",
+          "description": "Headline (required)"
+        },
+        "description": {
+          "type": "string",
+          "description": "Supporting text under the title"
+        },
+        "variant": {
+          "type": "enum",
+          "values": [
+            "default",
+            "search",
+            "error"
+          ],
+          "default": "default",
+          "description": "Preset icon: default=box, search=magnifier, error=warning"
+        },
+        "icon": {
+          "type": "ReactNode",
+          "description": "Custom icon, overrides the variant preset"
+        },
+        "size": {
+          "type": "enum",
+          "values": [
+            "sm",
+            "md",
+            "lg"
+          ],
+          "default": "md",
+          "description": "sm for inline/in-Card, md default, lg for full-page"
+        },
+        "children": {
+          "type": "ReactNode",
+          "description": "The call-to-action (a Button, or buttons in a Stack)"
+        }
+      },
+      "antiPatterns": [
+        {
+          "pattern": "Building an empty placeholder with a bare <div> + centered text",
+          "reason": "Inconsistent spacing/typography; AI reinvents it each time",
+          "fix": "Use <EmptyState title description variant>"
+        },
+        {
+          "pattern": "action / cta prop",
+          "reason": "There is no action prop; the CTA is composed",
+          "fix": "Put the Button as children of EmptyState"
+        },
+        {
+          "pattern": "Using EmptyState for a loading state",
+          "reason": "EmptyState is for no-data, not in-progress",
+          "fix": "Use <Skeleton> while loading; EmptyState when the result set is empty"
+        }
+      ],
+      "examples": [
+        {
+          "description": "Empty search results with a reset CTA",
+          "code": "<EmptyState\n  variant=\"search\"\n  title=\"No results\"\n  description=\"Try a different search term.\"\n>\n  <Button variant=\"secondary\" onClick={reset}>Clear filters</Button>\n</EmptyState>"
+        },
+        {
+          "description": "Full-page empty list",
+          "code": "<EmptyState\n  size=\"lg\"\n  title=\"No projects yet\"\n  description=\"Create your first project to get started.\"\n>\n  <Button variant=\"primary\">New project</Button>\n</EmptyState>"
+        }
+      ]
+    },
+    "Stat": {
+      "description": "Presentational dashboard KPI. No state. The arrow DIRECTION follows the sign of `delta` (the actual change: -0.4% → down arrow). The arrow/delta COLOR is set explicitly by `trend` (up=success, down=danger, neutral=muted) — so 'churn -0.4%, trend=up' shows a green DOWN arrow. Wrap several in StatGroup for an evenly-split row with dividers.",
+      "import": "import { Stat, StatGroup } from \"@usevyre/react\"",
+      "subcomponents": [
+        "StatGroup"
+      ],
+      "props": {
+        "label": {
+          "type": "string",
+          "description": "Metric name (required)"
+        },
+        "value": {
+          "type": "string | number",
+          "description": "The headline figure (required, rendered large)"
+        },
+        "delta": {
+          "type": "string | number",
+          "description": "The change amount, e.g. \"+12%\" or 24. Its sign sets the arrow direction (+ up, - down, 0/none flat)."
+        },
+        "trend": {
+          "type": "enum",
+          "values": [
+            "up",
+            "down",
+            "neutral"
+          ],
+          "default": "neutral",
+          "description": "Sets only the COLOR — up=success, down=danger, neutral=muted. Does NOT set the arrow direction (that comes from delta's sign)."
+        },
+        "deltaLabel": {
+          "type": "string",
+          "description": "Context for the delta, e.g. \"vs last month\""
+        },
+        "icon": {
+          "type": "ReactNode",
+          "description": "Optional leading icon (Vue: #icon slot)"
+        },
+        "size": {
+          "type": "enum",
+          "values": [
+            "sm",
+            "md",
+            "lg"
+          ],
+          "default": "md",
+          "description": "Value size"
+        }
+      },
+      "antiPatterns": [
+        {
+          "pattern": "Assuming trend flips the arrow direction",
+          "reason": "Arrow direction comes from the delta sign; trend only sets color",
+          "fix": "delta=\"-0.4%\" always shows a down arrow; trend=\"up\" just colors it green"
+        },
+        {
+          "pattern": "Building a KPI card with Card + manual layout",
+          "reason": "Inconsistent value/label/delta styling; AI reinvents it",
+          "fix": "Use <Stat label value delta trend />"
+        },
+        {
+          "pattern": "Laying out a KPI row with custom flex + dividers",
+          "reason": "StatGroup already splits evenly with dividers",
+          "fix": "Wrap the Stats in <StatGroup>"
+        }
+      ],
+      "examples": [
+        {
+          "description": "KPI row; note churn stays green while going down",
+          "code": "<StatGroup>\n  <Stat label=\"Revenue\" value=\"$48.2k\" delta=\"+12%\" trend=\"up\" deltaLabel=\"vs last month\" />\n  <Stat label=\"Churn\" value=\"2.1%\" delta=\"-0.4%\" trend=\"up\" deltaLabel=\"lower is better\" />\n  <Stat label=\"Orders\" value=\"1,204\" delta=\"0%\" trend=\"neutral\" />\n</StatGroup>"
+        },
+        {
+          "description": "Single stat with icon",
+          "code": "<Stat label=\"Active users\" value=\"12,840\" delta=\"+3.2%\" trend=\"up\"\n      icon={<UsersIcon />} size=\"lg\" />"
+        }
+      ]
+    },
+    "StatGroup": {
+      "description": "Evenly-split row of <Stat> with subtle dividers between items. Each Stat flexes to equal width.",
+      "import": "import { Stat, StatGroup } from \"@usevyre/react\"",
+      "props": {},
+      "antiPatterns": [
+        {
+          "pattern": "Putting non-Stat children in StatGroup",
+          "reason": "Dividers/equal-split styling target .vyre-stat",
+          "fix": "Only place <Stat> elements inside StatGroup"
+        }
+      ],
+      "examples": [
+        {
+          "description": "Three KPIs in a row",
+          "code": "<StatGroup>\n  <Stat label=\"MRR\" value=\"$9.6k\" delta=\"+5%\" trend=\"up\" />\n  <Stat label=\"Refunds\" value=\"32\" delta=\"+8\" trend=\"down\" />\n</StatGroup>"
+        }
+      ]
+    },
+    "Timeline": {
+      "description": "Vertical activity feed for audit logs and history. Presentational — a status dot per item plus a connector line. Pass `items` for plain logs, or TimelineItem children for rich per-item content. Timeline does NOT reorder; pass items in the order you want shown.",
+      "import": "import { Timeline, TimelineItem } from \"@usevyre/react\"",
+      "subcomponents": [
+        "TimelineItem"
+      ],
+      "props": {
+        "items": {
+          "type": "array",
+          "description": "{ title, time?, description?, status?, icon? }[] — alternative to TimelineItem children"
+        },
+        "children": {
+          "type": "ReactNode",
+          "description": "TimelineItem elements (use for rich content)"
+        }
+      },
+      "antiPatterns": [
+        {
+          "pattern": "Building an activity log with a <ul> + manual dots/lines",
+          "reason": "Inconsistent markers/spacing; AI reinvents it each time",
+          "fix": "Use <Timeline items={[...]} /> or TimelineItem children"
+        },
+        {
+          "pattern": "Using Stepper for a history/audit feed",
+          "reason": "Stepper is an ordered flow with completed/current/upcoming; a feed is just past events",
+          "fix": "Use <Timeline> for logs/history; Stepper for wizards"
+        },
+        {
+          "pattern": "Expecting Timeline to sort by time",
+          "reason": "Timeline renders items in given order",
+          "fix": "Sort the array yourself (newest- or oldest-first)"
+        }
+      ],
+      "examples": [
+        {
+          "description": "Plain audit log via items",
+          "code": "<Timeline\n  items={[\n    { title: \"Deployed v2.1\", time: \"2m ago\", status: \"success\" },\n    { title: \"Build started\", time: \"5m ago\", status: \"info\" },\n    { title: \"Push to main\", time: \"6m ago\" },\n  ]}\n/>"
+        },
+        {
+          "description": "Rich content via children",
+          "code": "<Timeline>\n  <TimelineItem title=\"Invoice paid\" time=\"Apr 2\" status=\"success\">\n    <Text size=\"sm\">$1,200 — <a href=\"#\">view receipt</a></Text>\n  </TimelineItem>\n  <TimelineItem title=\"Invoice sent\" time=\"Mar 28\" status=\"info\" />\n</Timeline>"
+        }
+      ]
+    },
+    "TimelineItem": {
+      "description": "One entry in a <Timeline>. Renders a status-colored dot (or a custom icon), a title, an optional time, and optional rich content.",
+      "import": "import { Timeline, TimelineItem } from \"@usevyre/react\"",
+      "props": {
+        "title": {
+          "type": "ReactNode",
+          "description": "Entry title (required)"
+        },
+        "time": {
+          "type": "ReactNode",
+          "description": "Timestamp, right-aligned"
+        },
+        "status": {
+          "type": "enum",
+          "values": [
+            "default",
+            "success",
+            "warning",
+            "danger",
+            "info"
+          ],
+          "default": "default",
+          "description": "Colors the marker dot"
+        },
+        "icon": {
+          "type": "ReactNode",
+          "description": "Custom marker, overrides the status dot (Vue: #icon slot)"
+        },
+        "children": {
+          "type": "ReactNode",
+          "description": "Rich content under the title"
+        }
+      },
+      "antiPatterns": [
+        {
+          "pattern": "<TimelineItem> outside <Timeline>",
+          "reason": "Marker/connector layout assumes the Timeline list context",
+          "fix": "Always nest TimelineItem inside Timeline"
+        }
+      ],
+      "examples": [
+        {
+          "description": "Item with rich content",
+          "code": "<TimelineItem title=\"Comment added\" time=\"1h ago\" status=\"default\">\n  <Text size=\"sm\">“Looks good to me 👍”</Text>\n</TimelineItem>"
+        }
+      ]
+    },
+    "Tree": {
+      "description": "Hierarchical tree view for file explorers and nested navigation. DATA-DRIVEN and CONTROLLED — pass a nested `data` array; the Tree renders recursively. Single selection. A node WITH children is a folder (click toggles expand); a leaf fires onSelect. Keyboard: ArrowUp/Down move, ArrowRight/Left expand/collapse, Enter/Space select.",
+      "import": "import { Tree } from \"@usevyre/react\"",
+      "props": {
+        "data": {
+          "type": "TreeNode[]",
+          "description": "Nested: { id: string; label: ReactNode; icon?: ReactNode; disabled?: boolean; children?: TreeNode[] }"
+        },
+        "expandedIds": {
+          "type": "string[]",
+          "description": "Controlled set of expanded node ids. Omit for uncontrolled."
+        },
+        "defaultExpandedIds": {
+          "type": "string[]",
+          "default": "[]",
+          "description": "Initially expanded ids when uncontrolled"
+        },
+        "onExpandedChange": {
+          "type": "function",
+          "description": "(ids: string[]) => void"
+        },
+        "selectedId": {
+          "type": "string | null",
+          "description": "Controlled selected node id. Omit for uncontrolled."
+        },
+        "defaultSelectedId": {
+          "type": "string | null",
+          "default": "null",
+          "description": "Initial selection when uncontrolled"
+        },
+        "onSelect": {
+          "type": "function",
+          "description": "(id: string) => void — fired on click/Enter/Space"
+        }
+      },
+      "antiPatterns": [
+        {
+          "pattern": "Rendering a nested <ul> tree by hand with manual expand state",
+          "reason": "Reinvents recursion, keyboard nav, and a11y roles every time",
+          "fix": "Pass a nested `data` array to <Tree> and control expandedIds/selectedId"
+        },
+        {
+          "pattern": "onSelect={(e) => ...}",
+          "reason": "Tree emits the node id, not an event",
+          "fix": "onSelect={(id) => setSelected(id)}"
+        },
+        {
+          "pattern": "Mutating the data array to expand/collapse",
+          "reason": "Expansion is controlled via expandedIds, not the data",
+          "fix": "Track expandedIds in state (or use defaultExpandedIds)"
+        },
+        {
+          "pattern": "Using DropdownMenu submenus for a file tree",
+          "reason": "Submenus are transient menus; a tree is persistent hierarchical content",
+          "fix": "Use <Tree> for file explorers / nested nav"
+        }
+      ],
+      "examples": [
+        {
+          "description": "File explorer, controlled selection",
+          "code": "const [sel, setSel] = useState<string | null>(\"src/a.ts\");\n\n<Tree\n  data={[\n    { id: \"src\", label: \"src\", children: [\n      { id: \"src/a.ts\", label: \"a.ts\" },\n      { id: \"src/b\", label: \"b\", children: [\n        { id: \"src/b/c.ts\", label: \"c.ts\" },\n      ]},\n    ]},\n    { id: \"README.md\", label: \"README.md\" },\n  ]}\n  selectedId={sel}\n  onSelect={setSel}\n  defaultExpandedIds={[\"src\"]}\n/>"
+        },
+        {
+          "description": "Fully controlled expansion",
+          "code": "const [open, setOpen] = useState<string[]>([\"root\"]);\n\n<Tree data={tree} expandedIds={open} onExpandedChange={setOpen} />"
+        }
+      ]
+    },
+    "OTPInput": {
+      "description": "Segmented one-time-code input for verification / 2FA. CONTROLLED. onChange emits the STRING value (not an event), and onComplete fires once when every slot is filled. Paste-aware (pasting a full code fills all slots), auto-advance on input, backspace moves to the previous slot, arrow keys navigate. Drops straight into <FormField>.",
+      "import": "import { OTPInput } from \"@usevyre/react\"",
+      "props": {
+        "value": {
+          "type": "string",
+          "description": "Controlled value (length ≤ `length`). Omit for uncontrolled."
+        },
+        "defaultValue": {
+          "type": "string",
+          "default": "\"\"",
+          "description": "Initial value when uncontrolled"
+        },
+        "onChange": {
+          "type": "function",
+          "description": "(value: string) => void — emits the combined code string, NOT an event"
+        },
+        "onComplete": {
+          "type": "function",
+          "description": "(value: string) => void — fired once when all slots are filled"
+        },
+        "length": {
+          "type": "number",
+          "default": 6,
+          "description": "Number of slots"
+        },
+        "type": {
+          "type": "enum",
+          "values": [
+            "numeric",
+            "alphanumeric"
+          ],
+          "default": "numeric",
+          "description": "Accepted characters"
+        },
+        "mask": {
+          "type": "boolean",
+          "default": false,
+          "description": "Render dots instead of characters (like a password)"
+        },
+        "size": {
+          "type": "enum",
+          "values": [
+            "sm",
+            "md",
+            "lg"
+          ],
+          "default": "md",
+          "description": "Slot size"
+        },
+        "disabled": {
+          "type": "boolean",
+          "default": false,
+          "description": "Disable all slots"
+        },
+        "autoFocus": {
+          "type": "boolean",
+          "default": false,
+          "description": "Focus the first slot on mount"
+        }
+      },
+      "antiPatterns": [
+        {
+          "pattern": "onChange={(e) => set(e.target.value)}",
+          "reason": "OTPInput emits the code string, not an event — there is no e.target",
+          "fix": "onChange={(value) => setCode(value)}"
+        },
+        {
+          "pattern": "Six separate <Input> boxes wired by hand",
+          "reason": "Reinvents paste, auto-advance, backspace and focus management",
+          "fix": "Use <OTPInput length={6} value onChange />"
+        },
+        {
+          "pattern": "Reading completion by comparing length yourself",
+          "reason": "onComplete already fires when the code is full",
+          "fix": "Use onComplete={(code) => verify(code)}"
+        },
+        {
+          "pattern": "type=\"password\" to hide digits",
+          "reason": "There is no type=password; masking is a dedicated prop",
+          "fix": "Use mask (type stays numeric/alphanumeric)"
+        }
+      ],
+      "examples": [
+        {
+          "description": "2FA code with verify on complete",
+          "code": "const [code, setCode] = useState(\"\");\n\n<OTPInput\n  value={code}\n  onChange={setCode}\n  onComplete={(c) => verify(c)}\n  autoFocus\n/>"
+        },
+        {
+          "description": "Inside a Form",
+          "code": "<FormField name=\"otp\" label=\"Verification code\"\n           rules={{ required: true, minLength: 6 }}>\n  <OTPInput length={6} />\n</FormField>"
+        }
+      ]
+    },
+    "Carousel": {
+      "description": "Accessible content slider for galleries, onboarding, and testimonials. CONTROLLED by a 0-based slide index. Compose CarouselSlide children (slide order = index). Snap scrolling, clickable dot indicators, prev/next arrows, ArrowLeft/Right keyboard, optional loop and autoPlay (autoplay pauses on hover/focus). onChange emits the index (not an event).",
+      "import": "import { Carousel, CarouselSlide } from \"@usevyre/react\"",
+      "subcomponents": [
+        "CarouselSlide"
+      ],
+      "props": {
+        "value": {
+          "type": "number",
+          "description": "Controlled active slide (0-based). Omit for uncontrolled."
+        },
+        "defaultValue": {
+          "type": "number",
+          "default": 0,
+          "description": "Initial slide when uncontrolled"
+        },
+        "onChange": {
+          "type": "function",
+          "description": "(index: number) => void — emits the new active slide index"
+        },
+        "loop": {
+          "type": "boolean",
+          "default": false,
+          "description": "Wrap past the first/last slide"
+        },
+        "autoPlay": {
+          "type": "boolean",
+          "default": false,
+          "description": "Advance automatically; pauses on hover/focus"
+        },
+        "interval": {
+          "type": "number",
+          "default": 5000,
+          "description": "Autoplay interval in ms"
+        },
+        "showArrows": {
+          "type": "boolean",
+          "default": true,
+          "description": "Show prev/next arrow buttons"
+        },
+        "showIndicators": {
+          "type": "boolean",
+          "default": true,
+          "description": "Show clickable dot indicators"
+        }
+      },
+      "antiPatterns": [
+        {
+          "pattern": "onChange={(e) => set(e.target.value)}",
+          "reason": "Carousel emits the slide index number, not an event",
+          "fix": "onChange={(index) => setIndex(index)}"
+        },
+        {
+          "pattern": "Putting raw elements directly in Carousel",
+          "reason": "Slides must be CarouselSlide so snap/indices/aria work",
+          "fix": "Wrap each slide in <CarouselSlide>"
+        },
+        {
+          "pattern": "Building a slider with manual scroll + dot state",
+          "reason": "Reinvents snap, keyboard, autoplay-pause and a11y roles",
+          "fix": "Use <Carousel> with CarouselSlide children"
+        },
+        {
+          "pattern": "autoPlay without considering reduced motion / pausing",
+          "reason": "Autoplay can be an accessibility problem if it never pauses",
+          "fix": "Carousel already pauses on hover/focus; keep interval reasonable or omit autoPlay"
+        }
+      ],
+      "examples": [
+        {
+          "description": "Image gallery with loop",
+          "code": "const [i, setI] = useState(0);\n\n<Carousel value={i} onChange={setI} loop>\n  <CarouselSlide><img src=\"/a.jpg\" alt=\"A\" /></CarouselSlide>\n  <CarouselSlide><img src=\"/b.jpg\" alt=\"B\" /></CarouselSlide>\n  <CarouselSlide><img src=\"/c.jpg\" alt=\"C\" /></CarouselSlide>\n</Carousel>"
+        },
+        {
+          "description": "Onboarding, autoplay, no arrows",
+          "code": "<Carousel autoPlay interval={4000} showArrows={false}>\n  <CarouselSlide><Welcome /></CarouselSlide>\n  <CarouselSlide><Features /></CarouselSlide>\n  <CarouselSlide><GetStarted /></CarouselSlide>\n</Carousel>"
+        }
+      ]
+    },
+    "CarouselSlide": {
+      "description": "One slide inside <Carousel>. Holds arbitrary content (image, Card, testimonial). Slide order determines its index.",
+      "import": "import { Carousel, CarouselSlide } from \"@usevyre/react\"",
+      "props": {},
+      "antiPatterns": [
+        {
+          "pattern": "<CarouselSlide> outside <Carousel>",
+          "reason": "Snap/measurement/aria depend on the Carousel context",
+          "fix": "Always nest CarouselSlide inside Carousel"
+        }
+      ],
+      "examples": [
+        {
+          "description": "Card slide",
+          "code": "<CarouselSlide>\n  <Card><CardBody>“Best tool ever.” — Ada</CardBody></Card>\n</CarouselSlide>"
+        }
+      ]
+    },
     "DateRangePicker": {
       "description": "Start/end date range picker. Built on Calendar (mode=range) with a friendlier { from, to } object API, a two-month side-by-side view, and preset shortcuts. Use this for report/filter date ranges; use DatePicker for a single date.",
       "import": "import { DateRangePicker } from \"@usevyre/react\"",