@usevyre/ai-context 1.0.1 → 1.2.0

package/dist/schema.json

@@ -1,14 +1,24 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "version": "1.0.0",
-  "generatedAt": "2026-05-13",
+  "version": "1.2.0",
+  "generatedAt": "2026-05-16",
   "package": "@usevyre/react",
-  "packageVersion": "1.0.0",
+  "packageVersion": "1.1.0",
   "validFor": [
-    "@usevyre/react@1.0.0+",
-    "@usevyre/vue@1.0.0+"
+    "@usevyre/react@1.1.0+",
+    "@usevyre/vue@1.1.0+"
   ],
   "changelog": {
+    "1.2.0": {
+      "date": "2026-05-16",
+      "breaking": false,
+      "summary": "Added Item layout primitive, DateRangePicker (dual-month range picker with presets, built on Calendar) and Kanban (controlled drag-and-drop board); Calendar gained additive defaultMonth prop; DatePicker split into its own documented component/entry"
+    },
+    "1.1.0": {
+      "date": "2026-05-15",
+      "breaking": false,
+      "summary": "Added 6 components: ButtonGroup, TagsInput, Combobox, DataGrid, Tag, TagGroup"
+    },
     "1.0.0": {
       "date": "2026-05-13",
       "breaking": true,
@@ -344,7 +354,7 @@
       ]
     },
     "Calendar": {
-      "description": "Date picker calendar widget for selecting single dates or ranges.",
+      "description": "Inline date-grid widget (always visible, no input). mode: single | range | multiple, optional time picker. For an input + popover use DatePicker; for start/end ranges with presets use DateRangePicker.",
       "import": "import { Calendar } from \"@usevyre/react\"",
       "props": {
         "value": {
@@ -358,13 +368,22 @@
         "disabled": {
           "type": "boolean",
           "default": false
+        },
+        "defaultMonth": {
+          "type": "Date",
+          "description": "Month to display initially when value is empty (uncontrolled view). Used by DateRangePicker for the second month."
         }
       },
       "antiPatterns": [
         {
-          "pattern": "Using Calendar for time selection",
-          "reason": "Calendar handles date only, not time",
-          "fix": "Combine with a separate time Input if time selection is needed"
+          "pattern": "Calendar for an input field that opens a popover",
+          "reason": "Calendar renders an always-visible grid, not a trigger",
+          "fix": "Use <DatePicker /> (single date) or <DateRangePicker /> (range)"
+        },
+        {
+          "pattern": "value as tuple for mode=\"single\"",
+          "reason": "value type must match mode: Date for single, [Date,Date] for range, Date[] for multiple",
+          "fix": "Pass value matching mode; use mode=\"range\" for [start,end]"
         }
       ],
       "examples": [
@@ -374,6 +393,87 @@
         }
       ]
     },
+    "DatePicker": {
+      "description": "Input trigger that opens a Calendar in a popover. Same modes as Calendar (single | range | multiple) plus a placeholder. Use this for a compact date field; use Calendar for an always-visible grid, or DateRangePicker for start/end ranges with presets.",
+      "import": "import { DatePicker } from \"@usevyre/react\"",
+      "props": {
+        "value": {
+          "type": "Date | [Date, Date] | Date[] | null",
+          "description": "Selected value (controlled). Type must match mode."
+        },
+        "onChange": {
+          "type": "function",
+          "description": "Callback when the selection changes; argument shape matches mode"
+        },
+        "mode": {
+          "type": "enum",
+          "values": [
+            "single",
+            "range",
+            "multiple"
+          ],
+          "default": "single",
+          "description": "Selection mode"
+        },
+        "placeholder": {
+          "type": "string",
+          "default": "Pick a date",
+          "description": "Trigger text when nothing is selected"
+        },
+        "showTime": {
+          "type": "boolean",
+          "default": false,
+          "description": "Adds an HH:MM time picker (single mode)"
+        },
+        "minDate": {
+          "type": "Date",
+          "description": "Earliest selectable date"
+        },
+        "maxDate": {
+          "type": "Date",
+          "description": "Latest selectable date"
+        },
+        "disabled": {
+          "type": "function",
+          "description": "(date: Date) => boolean — disable specific dates"
+        },
+        "weekStartsOn": {
+          "type": "enum",
+          "values": [
+            0,
+            1
+          ],
+          "default": 1,
+          "description": "0 = Sunday, 1 = Monday"
+        },
+        "inputClassName": {
+          "type": "string",
+          "description": "Class on the trigger button"
+        }
+      },
+      "antiPatterns": [
+        {
+          "pattern": "DatePicker mode=\"range\" for { from, to } object",
+          "reason": "DatePicker range mode emits a [Date, Date] tuple, not a { from, to } object",
+          "fix": "Use <DateRangePicker /> for the { from, to } object API + presets + dual month"
+        },
+        {
+          "pattern": "DatePicker without value/onChange",
+          "reason": "DatePicker is controlled — it has no internal selected state",
+          "fix": "Provide value and onChange (e.g. from useState)"
+        }
+      ],
+      "examples": [
+        {
+          "description": "Single date field",
+          "code": "const [date, setDate] = useState(null);\n<DatePicker value={date} onChange={setDate} placeholder=\"Pick a date\" />"
+        },
+        {
+          "description": "Date + time",
+          "code": "<DatePicker value={date} onChange={setDate} showTime />"
+        }
+      ]
+    },
     "Card": {
       "description": "Content container with optional header, body, and footer sections.",
       "import": "import { Card, CardHeader, CardBody, CardFooter } from \"@usevyre/react\"",
@@ -464,6 +564,150 @@
         }
       ]
     },
+    "RadioGroup": {
+      "description": "Controlled single-choice group. RadioGroup owns the selected value; render it data-driven via the options array OR with composable <Radio> children for custom content. role=radiogroup with proper labelling. For multi-select use Checkbox; for a compact dropdown use Select.",
+      "import": "import { RadioGroup, Radio } from \"@usevyre/react\"",
+      "subcomponents": [
+        "Radio"
+      ],
+      "props": {
+        "value": {
+          "type": "string",
+          "description": "Selected value (controlled). Vue: v-model."
+        },
+        "defaultValue": {
+          "type": "string",
+          "description": "Initial value (uncontrolled, React only)"
+        },
+        "onChange": {
+          "type": "function",
+          "description": "(value: string) => void. Vue: update:modelValue / v-model."
+        },
+        "name": {
+          "type": "string",
+          "description": "Radio input name; auto-generated if omitted"
+        },
+        "disabled": {
+          "type": "boolean",
+          "default": false,
+          "description": "Disable the whole group"
+        },
+        "size": {
+          "type": "enum",
+          "values": [
+            "sm",
+            "md"
+          ],
+          "default": "md",
+          "description": "Control size"
+        },
+        "orientation": {
+          "type": "enum",
+          "values": [
+            "vertical",
+            "horizontal"
+          ],
+          "default": "vertical",
+          "description": "Layout direction"
+        },
+        "options": {
+          "type": "{ value: string; label?: string; description?: string; disabled?: boolean }[]",
+          "description": "Data-driven options. Omit to pass <Radio> children instead."
+        }
+      },
+      "antiPatterns": [
+        {
+          "pattern": "<Radio> used outside a <RadioGroup>",
+          "reason": "Radio reads selection + name from RadioGroup context; it throws without a provider",
+          "fix": "Always wrap <Radio> in <RadioGroup>"
+        },
+        {
+          "pattern": "RadioGroup without value/onChange (React) or v-model (Vue)",
+          "reason": "RadioGroup is controlled; selection won't update",
+          "fix": "Bind value + onChange (React) or v-model (Vue); or defaultValue for uncontrolled in React"
+        },
+        {
+          "pattern": "Using Checkbox for mutually-exclusive choices",
+          "reason": "Radio expresses single-choice semantics + keyboard model",
+          "fix": "Use RadioGroup + Radio (or options) for one-of-many"
+        }
+      ],
+      "examples": [
+        {
+          "description": "Data-driven",
+          "code": "<RadioGroup\n  value={plan}\n  onChange={setPlan}\n  options={[\n    { value: \"free\", label: \"Free\", description: \"For hobby projects\" },\n    { value: \"pro\",  label: \"Pro\",  description: \"For teams\" },\n  ]}\n/>"
+        },
+        {
+          "description": "Composable children",
+          "code": "<RadioGroup value={plan} onChange={setPlan} orientation=\"horizontal\">\n  <Radio value=\"free\" label=\"Free\" />\n  <Radio value=\"pro\"  label=\"Pro\" />\n</RadioGroup>"
+        }
+      ]
+    },
+    "RichTextEditor": {
+      "description": "Controlled WYSIWYG editor. value is an HTML string; you own it in state and set it in onChange (React) / v-model (Vue). Native contentEditable + execCommand — zero dependencies. Toolbar: bold, italic, underline, strike, h1-h3, ordered/unordered lists, quote, code block, link, clear formatting.",
+      "import": "import { RichTextEditor } from \"@usevyre/react\"",
+      "props": {
+        "value": {
+          "type": "string",
+          "description": "HTML content (controlled). React: value + onChange. Vue: v-model."
+        },
+        "onChange": {
+          "type": "function",
+          "description": "(html: string) => void. Vue: update:modelValue / v-model."
+        },
+        "placeholder": {
+          "type": "string",
+          "default": "Write something…",
+          "description": "Shown when the editor is empty"
+        },
+        "disabled": {
+          "type": "boolean",
+          "default": false,
+          "description": "Not editable, dimmed; toolbar disabled"
+        },
+        "readOnly": {
+          "type": "boolean",
+          "default": false,
+          "description": "Not editable; toolbar hidden entirely"
+        },
+        "toolbar": {
+          "type": "RichTextTool[]",
+          "description": "Which buttons to show. Default = all. Tools: \"bold\"|\"italic\"|\"underline\"|\"strike\"|\"h1\"|\"h2\"|\"h3\"|\"ul\"|\"ol\"|\"quote\"|\"code\"|\"link\"|\"clear\""
+        },
+        "minHeight": {
+          "type": "string",
+          "default": "10rem",
+          "description": "CSS min-height of the editable area"
+        }
+      },
+      "antiPatterns": [
+        {
+          "pattern": "RichTextEditor without value/onChange (React) or v-model (Vue)",
+          "reason": "It is fully controlled; edits won't persist",
+          "fix": "Keep the HTML string in state and update it in onChange / v-model"
+        },
+        {
+          "pattern": "Rendering value as text or with dangerouslySetInnerHTML elsewhere without sanitising",
+          "reason": "value is raw HTML the user typed",
+          "fix": "Sanitise (e.g. DOMPurify) before re-rendering untrusted RTE output"
+        },
+        {
+          "pattern": "toolbar=\"bold\" (string)",
+          "reason": "toolbar is an array of tool ids",
+          "fix": "Pass an array, e.g. toolbar={[\"bold\",\"italic\",\"link\"]}"
+        }
+      ],
+      "examples": [
+        {
+          "description": "Controlled editor",
+          "code": "const [html, setHtml] = useState(\"<p>Hello <strong>world</strong></p>\");\n<RichTextEditor value={html} onChange={setHtml} placeholder=\"Write…\" />"
+        },
+        {
+          "description": "Minimal toolbar",
+          "code": "<RichTextEditor\n  value={html}\n  onChange={setHtml}\n  toolbar={[\"bold\", \"italic\", \"link\"]}\n/>"
+        }
+      ]
+    },
     "Command": {
       "description": "Command palette / search dialog. Use for search-first navigation or quick actions.",
       "import": "import { Command, CommandInput, CommandList, CommandEmpty, CommandGroup, CommandItem, CommandDialog } from \"@usevyre/react\"",
@@ -533,7 +777,7 @@
       ]
     },
     "Field": {
-      "description": "Form field wrapper providing label, hint text, and validation state for Input or Textarea.",
+      "description": "Form field wrapper. Two ways to use it (both supported): (1) props-based — pass label/hint/state/required for the common case; (2) composable — use the parts FieldLabel, FieldDescription, FieldError, FieldGroup, FieldSet for richer layouts (multiple controls, custom error placement). The props-based API is unchanged and still works.",
       "import": "import { Field, Input, Textarea } from \"@usevyre/react\"",
       "props": {
         "label": {
@@ -566,6 +810,11 @@
           "pattern": "Applying state prop directly to Input",
           "reason": "state belongs on Field, not on the Input itself",
           "fix": "Wrap Input in <Field state=\"error\"> to apply validation styling"
+        },
+        {
+          "pattern": "Mixing props label/hint AND FieldLabel/FieldError for the same field",
+          "reason": "Duplicates the label / message",
+          "fix": "Pick one: either props-based (label/hint/state) OR composable parts"
         }
       ],
       "examples": [
@@ -576,13 +825,28 @@
         {
           "description": "Search field with left icon",
           "code": "<Field label=\"Search\">\n  <Input leftElement={<SearchIcon />} placeholder=\"Search...\" />\n</Field>"
+        },
+        {
+          "description": "Composable field with explicit parts",
+          "code": "<Field>\n  <FieldLabel required htmlFor=\"email\">Email</FieldLabel>\n  <Input id=\"email\" type=\"email\" />\n  <FieldDescription>We\\u2019ll never share it.</FieldDescription>\n  <FieldError>{errors.email}</FieldError>\n</Field>\n\n// Two controls side by side\n<FieldGroup orientation=\"horizontal\">\n  <Field label=\"First name\"><Input /></Field>\n  <Field label=\"Last name\"><Input /></Field>\n</FieldGroup>"
         }
+      ],
+      "subcomponents": [
+        "FieldLabel",
+        "FieldDescription",
+        "FieldError",
+        "FieldGroup",
+        "FieldSet"
       ]
     },
     "Input": {
       "description": "Text input field. Wrap in Field for labels and validation. Use leftElement/rightElement for icons.",
       "import": "import { Input } from \"@usevyre/react\"",
       "props": {
+        "modelValue": {
+          "type": "string | number",
+          "description": "Vue only: enables v-model (two-way binding). React: use native value + onChange. Native input attrs (type, placeholder, disabled…) work in both."
+        },
         "size": {
           "type": "enum",
           "values": [
@@ -612,6 +876,11 @@
           "pattern": "type=\"search\" for search UI",
           "reason": "Use Command component for search-first interfaces",
           "fix": "Import Command from @usevyre/react for search palettes"
+        },
+        {
+          "pattern": "Vue: binding Input/Textarea value without v-model",
+          "reason": "Vue Input & Textarea support v-model (modelValue); manual :value alone won't update",
+          "fix": "Use v-model on <Input>/<Textarea> in Vue; in React use value + onChange"
         }
       ],
       "examples": [
@@ -1278,6 +1547,656 @@
           "code": "<Heading size=\"2xl\" as=\"h1\">Dashboard</Heading>\n<Lead>Welcome back. Here's what's happening today.</Lead>\n<Text size=\"sm\" style={{ color: 'var(--vyre-color-semantic-text-muted)' }}>Last updated 5 minutes ago.</Text>"
         }
       ]
+    },
+    "ButtonGroup": {
+      "description": "Groups multiple Button components into one visual unit (toolbar, segmented control). Pure layout — no internal state.",
+      "import": "import { ButtonGroup, Button } from \"@usevyre/react\"",
+      "props": {
+        "orientation": {
+          "type": "enum",
+          "values": [
+            "horizontal",
+            "vertical"
+          ],
+          "default": "horizontal",
+          "description": "Layout direction of grouped buttons"
+        },
+        "attached": {
+          "type": "boolean",
+          "default": false,
+          "description": "Remove gap so buttons share collapsed borders (segmented control look)"
+        },
+        "size": {
+          "type": "enum",
+          "values": [
+            "sm",
+            "md",
+            "lg",
+            "icon"
+          ],
+          "description": "Size forwarded to all child buttons"
+        }
+      },
+      "antiPatterns": [
+        {
+          "pattern": "ButtonGroup variant=\"...\"",
+          "reason": "ButtonGroup has no variant prop — variant goes on each child Button",
+          "fix": "Set variant on each <Button> inside the group"
+        },
+        {
+          "pattern": "ButtonGroup without Button children",
+          "reason": "ButtonGroup is a layout wrapper for Button elements",
+          "fix": "Place <Button> elements as direct children"
+        }
+      ],
+      "examples": [
+        {
+          "description": "Segmented control",
+          "code": "<ButtonGroup attached>\n  <Button variant=\"secondary\">Day</Button>\n  <Button variant=\"secondary\">Week</Button>\n  <Button variant=\"secondary\">Month</Button>\n</ButtonGroup>"
+        },
+        {
+          "description": "Vertical group",
+          "code": "<ButtonGroup orientation=\"vertical\" attached>\n  <Button variant=\"secondary\">Top</Button>\n  <Button variant=\"secondary\">Bottom</Button>\n</ButtonGroup>"
+        }
+      ]
+    },
+    "TagsInput": {
+      "description": "Multi-tag input. Type and press Enter or comma to add a tag, click x to remove, Backspace on empty input removes the last tag. Controlled.",
+      "import": "import { TagsInput } from \"@usevyre/react\"",
+      "props": {
+        "value": {
+          "type": "string[]",
+          "description": "Controlled list of tags (required)"
+        },
+        "onChange": {
+          "type": "(tags: string[]) => void",
+          "description": "Called with the new tag array on every change. React only — Vue uses v-model"
+        },
+        "placeholder": {
+          "type": "string",
+          "description": "Input placeholder, hidden when max is reached"
+        },
+        "disabled": {
+          "type": "boolean",
+          "default": false,
+          "description": "Disables all interaction"
+        },
+        "max": {
+          "type": "number",
+          "description": "Maximum number of tags; input is disabled when reached"
+        },
+        "size": {
+          "type": "enum",
+          "values": [
+            "sm",
+            "md",
+            "lg"
+          ],
+          "default": "md",
+          "description": "Size scale"
+        }
+      },
+      "antiPatterns": [
+        {
+          "pattern": "TagsInput value={string}",
+          "reason": "value must be a string array, not a string",
+          "fix": "Pass an array: value={['react','vue']}"
+        },
+        {
+          "pattern": "TagsInput without onChange",
+          "reason": "TagsInput is controlled — it needs onChange to update",
+          "fix": "Provide value and onChange (React) or v-model (Vue)"
+        }
+      ],
+      "examples": [
+        {
+          "description": "Basic tags input",
+          "code": "const [tags, setTags] = useState<string[]>([]);\n<TagsInput value={tags} onChange={setTags} placeholder=\"Add a tag…\" />"
+        },
+        {
+          "description": "Limited to 5 tags",
+          "code": "<TagsInput value={tags} onChange={setTags} max={5} />"
+        }
+      ]
+    },
+    "Combobox": {
+      "description": "Searchable single-select dropdown with typeahead filtering and keyboard navigation. Use when the list is long enough to need search. Differs from Select (no search) and Command (palette).",
+      "import": "import { Combobox } from \"@usevyre/react\"",
+      "props": {
+        "options": {
+          "type": "{ value: string; label: string; disabled?: boolean }[]",
+          "description": "Selectable options (required)"
+        },
+        "value": {
+          "type": "string | null",
+          "description": "Controlled selected value; null clears selection (required)"
+        },
+        "onChange": {
+          "type": "(value: string | null) => void",
+          "description": "Called when selection changes. React only — Vue uses v-model"
+        },
+        "placeholder": {
+          "type": "string",
+          "default": "\"Search…\"",
+          "description": "Input placeholder when nothing is selected"
+        },
+        "disabled": {
+          "type": "boolean",
+          "default": false,
+          "description": "Disables the combobox"
+        },
+        "size": {
+          "type": "enum",
+          "values": [
+            "sm",
+            "md",
+            "lg"
+          ],
+          "default": "md",
+          "description": "Height scale"
+        },
+        "emptyText": {
+          "type": "string",
+          "default": "\"No results\"",
+          "description": "Text shown when search matches no options"
+        }
+      },
+      "antiPatterns": [
+        {
+          "pattern": "Combobox value=\"\"",
+          "reason": "Empty selection must be null, not empty string",
+          "fix": "Use value={null} for no selection"
+        },
+        {
+          "pattern": "Combobox options={string[]}",
+          "reason": "options must be objects with value and label",
+          "fix": "Use [{ value: 'ts', label: 'TypeScript' }]"
+        },
+        {
+          "pattern": "Using Combobox for command palette",
+          "reason": "Combobox is single-value select, not an action palette",
+          "fix": "Use Command for command palettes"
+        }
+      ],
+      "examples": [
+        {
+          "description": "Searchable language picker",
+          "code": "const [lang, setLang] = useState<string | null>(null);\n<Combobox\n  options={[{ value: \"ts\", label: \"TypeScript\" }, { value: \"go\", label: \"Go\" }]}\n  value={lang}\n  onChange={setLang}\n  placeholder=\"Search language…\"\n/>"
+        }
+      ]
+    },
+    "DataGrid": {
+      "description": "Table with built-in column sorting, loading skeletons, and empty state. Filtering and pagination are out of scope — compose with the Pagination component.",
+      "import": "import { DataGrid } from \"@usevyre/react\"",
+      "props": {
+        "columns": {
+          "type": "{ key: string; label: string; sortable?: boolean; width?: string }[]",
+          "description": "Column definitions (required)"
+        },
+        "rows": {
+          "type": "Record<string, unknown>[]",
+          "description": "Row data; each object keyed by column key (required)"
+        },
+        "sortKey": {
+          "type": "string",
+          "description": "Controlled active sort column key"
+        },
+        "sortDir": {
+          "type": "enum",
+          "values": [
+            "asc",
+            "desc"
+          ],
+          "description": "Controlled sort direction"
+        },
+        "onSort": {
+          "type": "(key: string, dir: 'asc' | 'desc') => void",
+          "description": "Called when a sortable header is clicked. React only — Vue emits sort + v-model:sortKey/sortDir"
+        },
+        "loading": {
+          "type": "boolean",
+          "default": false,
+          "description": "Show skeleton placeholder rows"
+        },
+        "emptyText": {
+          "type": "string",
+          "default": "\"No data\"",
+          "description": "Message shown when rows is empty"
+        },
+        "stickyHeader": {
+          "type": "boolean",
+          "default": false,
+          "description": "Keep the header visible while scrolling"
+        }
+      },
+      "antiPatterns": [
+        {
+          "pattern": "DataGrid expecting built-in pagination",
+          "reason": "DataGrid does not paginate — it only sorts",
+          "fix": "Slice rows yourself and use the Pagination component"
+        },
+        {
+          "pattern": "DataGrid expecting built-in filtering",
+          "reason": "DataGrid does not filter rows",
+          "fix": "Filter the rows array before passing it in"
+        },
+        {
+          "pattern": "sortable without onSort",
+          "reason": "Sorting is controlled — the grid does not sort data itself",
+          "fix": "Handle onSort and sort the rows array in your state"
+        }
+      ],
+      "examples": [
+        {
+          "description": "Sortable grid",
+          "code": "const cols = [{ key: \"name\", label: \"Name\", sortable: true }];\n<DataGrid\n  columns={cols}\n  rows={people}\n  sortKey={sortKey}\n  sortDir={sortDir}\n  onSort={(k, d) => { setSortKey(k); setSortDir(d); }}\n/>"
+        },
+        {
+          "description": "Loading state",
+          "code": "<DataGrid columns={cols} rows={[]} loading />"
+        }
+      ]
+    },
+    "Tag": {
+      "description": "Standalone display tag/chip for categories, labels, or filter chips. NOT an input — for tag input use TagsInput. Group multiple with TagGroup.",
+      "import": "import { Tag } from \"@usevyre/react\"",
+      "props": {
+        "variant": {
+          "type": "enum",
+          "values": [
+            "default",
+            "accent",
+            "danger"
+          ],
+          "default": "default",
+          "description": "Visual style. default=neutral, accent=brand, danger=destructive/error"
+        },
+        "size": {
+          "type": "enum",
+          "values": [
+            "sm",
+            "md",
+            "lg"
+          ],
+          "default": "md",
+          "description": "Size scale"
+        },
+        "onRemove": {
+          "type": "() => void",
+          "description": "React only. When provided, renders a × remove button. Vue: use `removable` prop + @remove event"
+        },
+        "onClick": {
+          "type": "() => void",
+          "description": "React only. When provided, makes the whole tag interactive (keyboard accessible). Vue: use `clickable` prop + @click event"
+        },
+        "disabled": {
+          "type": "boolean",
+          "default": false,
+          "description": "Disables interaction (only relevant with onClick/onRemove)"
+        }
+      },
+      "antiPatterns": [
+        {
+          "pattern": "Tag variant=\"success\"",
+          "reason": "Tag only has default, accent, danger variants (unlike Badge which has more)",
+          "fix": "Use Badge for success/warning/teal status colors; Tag is for categories/filters"
+        },
+        {
+          "pattern": "Using Tag for tag input",
+          "reason": "Tag is display-only, it does not accept typed input",
+          "fix": "Use TagsInput for adding/removing tags via keyboard"
+        },
+        {
+          "pattern": "Tag size=\"xl\"",
+          "reason": "Maximum size is 'lg'",
+          "fix": "Use size=\"lg\""
+        }
+      ],
+      "examples": [
+        {
+          "description": "Category tags in a group",
+          "code": "<TagGroup>\n  <Tag>Design</Tag>\n  <Tag variant=\"accent\">Featured</Tag>\n  <Tag>Engineering</Tag>\n</TagGroup>"
+        },
+        {
+          "description": "Removable filter chip (React)",
+          "code": "<Tag onRemove={() => removeFilter(\"react\")}>react</Tag>"
+        },
+        {
+          "description": "Clickable toggle tag (React)",
+          "code": "<Tag onClick={() => toggleFilter(\"vue\")}>vue</Tag>"
+        }
+      ]
+    },
+    "TagGroup": {
+      "description": "Read-only container that lays out multiple Tag elements with automatic wrapping and consistent spacing. For tag input use TagsInput.",
+      "import": "import { TagGroup, Tag } from \"@usevyre/react\"",
+      "props": {
+        "gap": {
+          "type": "enum",
+          "values": [
+            "sm",
+            "md",
+            "lg"
+          ],
+          "default": "md",
+          "description": "Spacing between tags"
+        },
+        "wrap": {
+          "type": "boolean",
+          "default": true,
+          "description": "Wrap tags onto multiple lines when they overflow; set false for single-line scroll"
+        }
+      },
+      "antiPatterns": [
+        {
+          "pattern": "TagGroup without Tag children",
+          "reason": "TagGroup is a layout wrapper for Tag elements",
+          "fix": "Place <Tag> elements as direct children"
+        },
+        {
+          "pattern": "Using TagGroup for tag input",
+          "reason": "TagGroup is display-only",
+          "fix": "Use TagsInput for an editable tag field"
+        }
+      ],
+      "examples": [
+        {
+          "description": "Tag group with mixed variants",
+          "code": "<TagGroup gap=\"sm\">\n  <Tag>React</Tag>\n  <Tag>Vue</Tag>\n  <Tag variant=\"accent\">TypeScript</Tag>\n</TagGroup>"
+        }
+      ]
+    },
+    "Item": {
+      "description": "Layout primitive for list rows, settings rows, and notification rows. Denser than Card — use Item (not Card) for repeated list rows.",
+      "import": "import { Item, ItemMedia, ItemContent, ItemTitle, ItemDescription, ItemActions, ItemGroup } from \"@usevyre/react\"",
+      "subcomponents": [
+        "ItemGroup",
+        "ItemMedia",
+        "ItemContent",
+        "ItemTitle",
+        "ItemDescription",
+        "ItemActions"
+      ],
+      "props": {
+        "variant": {
+          "type": "enum",
+          "values": [
+            "default",
+            "outlined",
+            "muted",
+            "plain"
+          ],
+          "default": "default",
+          "description": "Visual style of the row. plain = transparent + no border (use when composing Item inside another surface like Card or a Kanban card to avoid a double background)."
+        },
+        "size": {
+          "type": "enum",
+          "values": [
+            "sm",
+            "md",
+            "lg"
+          ],
+          "default": "md",
+          "description": "Vertical density / text size of the row"
+        },
+        "clickable": {
+          "type": "boolean",
+          "default": false,
+          "description": "Adds pointer cursor, hover background, focus ring, and role=button"
+        }
+      },
+      "antiPatterns": [
+        {
+          "pattern": "Card used for repeated list rows",
+          "reason": "Card is a content container; Item is the dense list-row primitive",
+          "fix": "Use <Item> (optionally inside <ItemGroup separated>) for list/settings rows"
+        },
+        {
+          "pattern": "Item variant=\"primary\"",
+          "reason": "Item has no 'primary' variant",
+          "fix": "Use variant=\"default\" | \"outlined\" | \"muted\""
+        },
+        {
+          "pattern": "raw text directly inside Item",
+          "reason": "Item lays out media/content/actions columns; bare text breaks alignment",
+          "fix": "Wrap text in <ItemContent><ItemTitle>…</ItemTitle></ItemContent>"
+        }
+      ],
+      "examples": [
+        {
+          "description": "Settings row with media, content and a trailing switch",
+          "code": "<Item>\n  <ItemMedia><BellIcon /></ItemMedia>\n  <ItemContent>\n    <ItemTitle>Notifications</ItemTitle>\n    <ItemDescription>Receive an email when someone mentions you.</ItemDescription>\n  </ItemContent>\n  <ItemActions>\n    <Switch defaultChecked />\n  </ItemActions>\n</Item>"
+        },
+        {
+          "description": "Grouped clickable list with dividers",
+          "code": "<ItemGroup separated>\n  <Item clickable>\n    <ItemContent><ItemTitle>Profile</ItemTitle></ItemContent>\n  </Item>\n  <Item clickable>\n    <ItemContent><ItemTitle>Billing</ItemTitle></ItemContent>\n  </Item>\n</ItemGroup>"
+        }
+      ]
+    },
+    "Kanban": {
+      "description": "Drag-and-drop board: cards move between columns (or reorder within a column). CONTROLLED & data-driven like DataGrid. While dragging, a placeholder shows the exact drop position. Each card is wrapped in a Card (variant=\"outlined\"); renderCard (React) / #card slot (Vue) can render ANY content incl. complex components (Avatar/Badge/Progress). Columns and cards accept an optional semantic color tint. Native HTML5 DnD, zero deps.",
+      "import": "import { Kanban } from \"@usevyre/react\"",
+      "props": {
+        "value": {
+          "type": "KanbanColumn[]",
+          "description": "Controlled board data. KanbanColumn = { id, title, cards: KanbanCard[], color? }; KanbanCard = { id, title, description?, color? }. Extra app fields may ride along on cards and be read in renderCard. color = \"default\"|\"accent\"|\"teal\"|\"success\"|\"warning\"|\"danger\" (token-based tint). Card ids must be unique across the whole board."
+        },
+        "onChange": {
+          "type": "function",
+          "description": "(next: KanbanColumn[]) => void — called with the next columns array after a drag move. Required; set it back into your state."
+        },
+        "renderCard": {
+          "type": "function",
+          "description": "(card, column) => ReactNode — custom card body, rendered inside the wrapping <Card>. Vue: #card scoped slot. Can return any components (Avatar, Badge, Progress, etc.); attach extra fields to the card object and read them here."
+        },
+        "onCardClick": {
+          "type": "function",
+          "description": "(card, column) => void — fired on click/Enter/Space (not after a drag). Vue: @card-click."
+        }
+      },
+      "antiPatterns": [
+        {
+          "pattern": "Kanban without onChange (or ignoring it)",
+          "reason": "Kanban holds no internal data state; dropped cards won't move unless you apply onChange",
+          "fix": "Store columns in state and setColumns in onChange (v-model in Vue)"
+        },
+        {
+          "pattern": "Duplicate card ids across columns",
+          "reason": "Card moves are resolved by id; duplicates corrupt the move",
+          "fix": "Use globally-unique card ids across the entire board"
+        },
+        {
+          "pattern": "Mutating value in place then calling onChange",
+          "reason": "React/Vue need a new array reference to re-render reliably",
+          "fix": "Pass the new array Kanban gives you straight to setState / v-model"
+        },
+        {
+          "pattern": "color=\"blue\" (or any non-semantic value)",
+          "reason": "color is a fixed semantic set, not an arbitrary CSS color",
+          "fix": "Use one of: \"default\" | \"accent\" | \"teal\" | \"success\" | \"warning\" | \"danger\""
+        }
+      ],
+      "examples": [
+        {
+          "description": "Controlled board",
+          "code": "const [columns, setColumns] = useState([\n  { id: \"todo\",  title: \"To Do\",       cards: [{ id: \"1\", title: \"Spec API\" }] },\n  { id: \"doing\", title: \"In Progress\", cards: [] },\n  { id: \"done\",  title: \"Done\",        cards: [{ id: \"2\", title: \"Kickoff\" }] },\n]);\n<Kanban value={columns} onChange={setColumns} />"
+        },
+        {
+          "description": "Custom card body + click handler",
+          "code": "<Kanban\n  value={columns}\n  onChange={setColumns}\n  onCardClick={(card) => openDetail(card.id)}\n  renderCard={(card) => (\n    <><strong>{card.title}</strong><Badge>{card.id}</Badge></>\n  )}\n/>"
+        },
+        {
+          "description": "Tinted columns/cards + complex card content",
+          "code": "const [cols, setCols] = useState([\n  { id: \"doing\", title: \"In Progress\", color: \"teal\", cards: [\n    { id: \"t1\", title: \"OAuth\", assignee: \"AK\", progress: 60, color: \"warning\" },\n  ]},\n]);\n<Kanban\n  value={cols}\n  onChange={setCols}\n  renderCard={(card) => (\n    <><strong>{card.title}</strong><Progress value={card.progress} /></>\n  )}\n/>"
+        }
+      ]
+    },
+    "Conversation": {
+      "description": "Chat / inbox message thread. CONTROLLED & data-driven like Kanban — you own `value` (messages array) and append in your own send handler; Conversation holds no message state. Consecutive messages from the same author are grouped (avatar + name shown once), day separators are inserted on date change, and outgoing messages (authorId === currentUserId) align right.",
+      "import": "import { Conversation } from \"@usevyre/react\"",
+      "props": {
+        "value": {
+          "type": "ConversationMessage[]",
+          "description": "Ordered messages. ConversationMessage = { id, authorId, text?, authorName?, authorAvatar?, timestamp?: Date|string|number, status?: \"sending\"|\"sent\"|\"delivered\"|\"read\", attachments?: ConversationAttachment[] }. ConversationAttachment = { kind: \"image\"|\"audio\"|\"video\"|\"file\", url, name?, size? } — rendered inside the bubble. Required & controlled."
+        },
+        "currentUserId": {
+          "type": "string",
+          "description": "Whose messages are outgoing (aligned right). Required — match against message.authorId."
+        },
+        "composer": {
+          "type": "boolean",
+          "default": false,
+          "description": "Show the built-in input + Send button. Pair with onSend."
+        },
+        "onSend": {
+          "type": "function",
+          "description": "(text: string, files: File[]) => void — called when the built-in composer submits. files holds anything staged via the attach button (empty array unless allowAttachments). You own the upload + turning staged files into message attachments. Vue: @send."
+        },
+        "placeholder": {
+          "type": "string",
+          "default": "Write a message…",
+          "description": "Composer input placeholder."
+        },
+        "typing": {
+          "type": "boolean | string",
+          "default": false,
+          "description": "Show an incoming typing indicator. Pass a string to label it."
+        },
+        "allowAttachments": {
+          "type": "boolean",
+          "default": false,
+          "description": "Show a 📎 attach button + staged-file chips in the built-in composer. Files come back via onSend's second arg."
+        },
+        "accept": {
+          "type": "string",
+          "description": "Forwarded to the file input's accept attribute, e.g. \"image/*\"."
+        },
+        "renderMessage": {
+          "type": "function",
+          "description": "(message, meta) => ReactNode — custom bubble body. meta = { outgoing, isGroupStart, isGroupEnd }. Vue: #message scoped slot."
+        },
+        "renderComposer": {
+          "type": "function",
+          "description": "(api) => ReactNode — replace the composer entirely. api = { value, setValue, files, setFiles, send }. Vue: #composer scoped slot."
+        }
+      },
+      "antiPatterns": [
+        {
+          "pattern": "Conversation without currentUserId",
+          "reason": "Alignment (incoming vs outgoing) is decided by authorId === currentUserId",
+          "fix": "Always pass currentUserId matching one of the message authorId values"
+        },
+        {
+          "pattern": "Expecting Conversation to store/append messages",
+          "reason": "Conversation is controlled & stateless for data, like Kanban/DataGrid",
+          "fix": "Append to your own state in onSend (or @send) and pass it back via value"
+        },
+        {
+          "pattern": "composer without onSend (React) / @send (Vue)",
+          "reason": "The built-in composer emits text; nothing happens unless you handle it",
+          "fix": "Provide onSend / @send to append the message to value"
+        },
+        {
+          "pattern": "Treating onSend as (text) only when using allowAttachments",
+          "reason": "With allowAttachments, staged files arrive as the 2nd arg; ignoring it drops attachments",
+          "fix": "Handle onSend(text, files) — map files to message attachments and append"
+        }
+      ],
+      "examples": [
+        {
+          "description": "Controlled thread with built-in composer",
+          "code": "const [messages, setMessages] = useState([\n  { id: \"1\", authorId: \"sam\", authorName: \"Sam\", text: \"Hey!\" },\n  { id: \"2\", authorId: \"me\", text: \"Hi \\ud83d\\udc4b\", status: \"read\" },\n]);\n<Conversation\n  value={messages}\n  currentUserId=\"me\"\n  composer\n  onSend={(t) => setMessages((m) => [...m, { id: crypto.randomUUID(), authorId: \"me\", text: t }])}\n/>"
+        },
+        {
+          "description": "Typing indicator + custom bubble",
+          "code": "<Conversation\n  value={messages}\n  currentUserId=\"me\"\n  typing=\"Sam is typing\"\n  renderMessage={(m) => <strong>{m.text}</strong>}\n/>"
+        },
+        {
+          "description": "Message with image + file attachments",
+          "code": "const messages = [\n  { id: \"1\", authorId: \"sam\", authorName: \"Sam\", text: \"Moodboard \\ud83d\\udc47\",\n    attachments: [{ kind: \"image\", url: \"/board.png\", name: \"board.png\" }] },\n  { id: \"2\", authorId: \"me\", text: \"Specs:\", status: \"read\",\n    attachments: [{ kind: \"file\", url: \"/spec.pdf\", name: \"spec.pdf\", size: \"2.4 MB\" }] },\n];\n<Conversation value={messages} currentUserId=\"me\" />"
+        }
+      ]
+    },
+    "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\"",
+      "props": {
+        "value": {
+          "type": "{ from: Date | null; to: Date | null } | null",
+          "description": "Selected range (controlled). Pass an OBJECT, not a tuple."
+        },
+        "onChange": {
+          "type": "function",
+          "description": "Callback (range: { from, to }) => void when the range changes"
+        },
+        "placeholder": {
+          "type": "string",
+          "default": "Pick a date range",
+          "description": "Trigger text when no range is selected"
+        },
+        "numberOfMonths": {
+          "type": "enum",
+          "values": [
+            1,
+            2
+          ],
+          "default": 2,
+          "description": "How many month calendars to show side-by-side"
+        },
+        "presets": {
+          "type": "boolean | DateRangePreset[]",
+          "default": false,
+          "description": "true shows built-in presets (Today, Yesterday, Last 7/30 days, This/Last month); or pass a custom array of { label, range() }"
+        },
+        "minDate": {
+          "type": "Date",
+          "description": "Earliest selectable date"
+        },
+        "maxDate": {
+          "type": "Date",
+          "description": "Latest selectable date"
+        },
+        "disabled": {
+          "type": "function",
+          "description": "(date: Date) => boolean — disable specific dates"
+        },
+        "weekStartsOn": {
+          "type": "enum",
+          "values": [
+            0,
+            1
+          ],
+          "default": 1,
+          "description": "0 = Sunday, 1 = Monday"
+        }
+      },
+      "antiPatterns": [
+        {
+          "pattern": "value={[from, to]}",
+          "reason": "DateRangePicker uses a { from, to } object, not a [Date, Date] tuple like Calendar mode=range",
+          "fix": "Use value={{ from, to }} and read range.from / range.to"
+        },
+        {
+          "pattern": "DateRangePicker for a single date",
+          "reason": "DateRangePicker always selects a start AND end",
+          "fix": "Use <DatePicker /> for a single date"
+        },
+        {
+          "pattern": "presets=\"true\" (string)",
+          "reason": "presets is a boolean or an array, not a string",
+          "fix": "Use the bare prop: presets  (or presets={true})"
+        }
+      ],
+      "examples": [
+        {
+          "description": "Range picker with built-in presets",
+          "code": "const [range, setRange] = useState({ from: null, to: null });\n<DateRangePicker value={range} onChange={setRange} presets />"
+        },
+        {
+          "description": "Single month, no presets",
+          "code": "<DateRangePicker value={range} onChange={setRange} numberOfMonths={1} />"
+        }
+      ]
     }
   }
 }