@usevyre/ai-context 1.1.0 → 1.2.0

package/dist/schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "version": "1.1.0",
-  "generatedAt": "2026-05-15",
+  "version": "1.2.0",
+  "generatedAt": "2026-05-16",
   "package": "@usevyre/react",
   "packageVersion": "1.1.0",
   "validFor": [
@@ -9,6 +9,11 @@
     "@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,
@@ -349,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": {
@@ -363,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": [
@@ -379,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\"",
@@ -469,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\"",
@@ -538,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": {
@@ -571,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": [
@@ -581,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": [
@@ -617,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": [
@@ -1641,6 +1905,298 @@
           "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} />"
+        }
+      ]
     }
   }
 }

package/dist/tokens.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://usevyre.com/schemas/ai-tokens-v1.json",
   "version": "1.0.0",
-  "generatedAt": "2026-05-13T00:36:55.284Z",
+  "generatedAt": "2026-05-17T04:12:37.293Z",
   "description": "useVyre design tokens — machine-readable reference for AI agents. Use semantic color tokens; never use primitive tokens directly in components.",
   "naming": {
     "convention": "--vyre-[category]-[subcategory]-[variant]",