@usevyre/ai-context 1.1.0 → 1.2.1

package/dist/index.js

@@ -1,7 +1,7 @@
-// @usevyre/ai-context v1.1.0
+// @usevyre/ai-context v1.2.0
 // Auto-generated — do not edit directly. Edit src/schema/components.json instead.
 
-export const version = "1.1.0";
+export const version = "1.2.0";
 
 export const fullContext = `# useVyre Design System — AI Context
 # Version: 0.2.0
@@ -310,7 +310,7 @@ import { Button } from "@usevyre/react"
 
 ### Calendar
 
-Date picker calendar widget for selecting single dates or ranges.
+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.
 
 \`\`\`tsx
 import { Calendar } from "@usevyre/react"
@@ -319,6 +319,7 @@ import { Calendar } from "@usevyre/react"
 // value          = Date | null
 // onChange       = function
 // disabled       = boolean (default: false)
+// defaultMonth   = Date
 
 // Examples:
 const [date, setDate] = useState(null);
@@ -326,7 +327,39 @@ const [date, setDate] = useState(null);
 \`\`\`
 
 **Common mistakes:**
-- ❌ \`Using Calendar for time selection\` → Combine with a separate time Input if time selection is needed
+- ❌ \`Calendar for an input field that opens a popover\` → Use <DatePicker /> (single date) or <DateRangePicker /> (range)
+- ❌ \`value as tuple for mode="single"\` → Pass value matching mode; use mode="range" for [start,end]
+
+---
+
+### DatePicker
+
+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.
+
+\`\`\`tsx
+import { DatePicker } from "@usevyre/react"
+
+// Props:
+// value          = Date | [Date, Date] | Date[] | null
+// onChange       = function
+// mode           = "single" | "range" | "multiple" (default: single)
+// placeholder    = string (default: Pick a date)
+// showTime       = boolean (default: false)
+// minDate        = Date
+// maxDate        = Date
+// disabled       = function
+// weekStartsOn   = "0" | "1" (default: 1)
+// inputClassName = string
+
+// Examples:
+const [date, setDate] = useState(null);
+<DatePicker value={date} onChange={setDate} placeholder="Pick a date" />
+<DatePicker value={date} onChange={setDate} showTime />
+\`\`\`
+
+**Common mistakes:**
+- ❌ \`DatePicker mode="range" for { from, to } object\` → Use <DateRangePicker /> for the { from, to } object API + presets + dual month
+- ❌ \`DatePicker without value/onChange\` → Provide value and onChange (e.g. from useState)
 
 ---
 
@@ -386,6 +419,78 @@ import { Checkbox } from "@usevyre/react"
 
 ---
 
+### RadioGroup
+
+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.
+
+\`\`\`tsx
+import { RadioGroup, Radio } from "@usevyre/react"
+
+// Props:
+// value          = string
+// defaultValue   = string
+// onChange       = function
+// name           = string
+// disabled       = boolean (default: false)
+// size           = "sm" | "md" (default: md)
+// orientation    = "vertical" | "horizontal" (default: vertical)
+// options        = { value: string; label?: string; description?: string; disabled?: boolean }[]
+
+// Examples:
+<RadioGroup
+  value={plan}
+  onChange={setPlan}
+  options={[
+    { value: "free", label: "Free", description: "For hobby projects" },
+    { value: "pro",  label: "Pro",  description: "For teams" },
+  ]}
+/>
+<RadioGroup value={plan} onChange={setPlan} orientation="horizontal">
+  <Radio value="free" label="Free" />
+  <Radio value="pro"  label="Pro" />
+</RadioGroup>
+\`\`\`
+
+**Common mistakes:**
+- ❌ \`<Radio> used outside a <RadioGroup>\` → Always wrap <Radio> in <RadioGroup>
+- ❌ \`RadioGroup without value/onChange (React) or v-model (Vue)\` → Bind value + onChange (React) or v-model (Vue); or defaultValue for uncontrolled in React
+- ❌ \`Using Checkbox for mutually-exclusive choices\` → Use RadioGroup + Radio (or options) for one-of-many
+
+---
+
+### RichTextEditor
+
+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.
+
+\`\`\`tsx
+import { RichTextEditor } from "@usevyre/react"
+
+// Props:
+// value          = string
+// onChange       = function
+// placeholder    = string (default: Write something…)
+// disabled       = boolean (default: false)
+// readOnly       = boolean (default: false)
+// toolbar        = RichTextTool[]
+// minHeight      = string (default: 10rem)
+
+// Examples:
+const [html, setHtml] = useState("<p>Hello <strong>world</strong></p>");
+<RichTextEditor value={html} onChange={setHtml} placeholder="Write…" />
+<RichTextEditor
+  value={html}
+  onChange={setHtml}
+  toolbar={["bold", "italic", "link"]}
+/>
+\`\`\`
+
+**Common mistakes:**
+- ❌ \`RichTextEditor without value/onChange (React) or v-model (Vue)\` → Keep the HTML string in state and update it in onChange / v-model
+- ❌ \`Rendering value as text or with dangerouslySetInnerHTML elsewhere without sanitising\` → Sanitise (e.g. DOMPurify) before re-rendering untrusted RTE output
+- ❌ \`toolbar="bold" (string)\` → Pass an array, e.g. toolbar={["bold","italic","link"]}
+
+---
+
 ### Command
 
 Command palette / search dialog. Use for search-first navigation or quick actions.
@@ -437,7 +542,7 @@ import { DropdownMenu, DropdownItem, DropdownSeparator, DropdownCheckboxItem, Dr
 
 ### Field
 
-Form field wrapper providing label, hint text, and validation state for Input or Textarea.
+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.
 
 \`\`\`tsx
 import { Field, Input, Textarea } from "@usevyre/react"
@@ -455,10 +560,23 @@ import { Field, Input, Textarea } from "@usevyre/react"
 <Field label="Search">
   <Input leftElement={<SearchIcon />} placeholder="Search..." />
 </Field>
+<Field>
+  <FieldLabel required htmlFor="email">Email</FieldLabel>
+  <Input id="email" type="email" />
+  <FieldDescription>We\u2019ll never share it.</FieldDescription>
+  <FieldError>{errors.email}</FieldError>
+</Field>
+
+// Two controls side by side
+<FieldGroup orientation="horizontal">
+  <Field label="First name"><Input /></Field>
+  <Field label="Last name"><Input /></Field>
+</FieldGroup>
 \`\`\`
 
 **Common mistakes:**
 - ❌ \`Applying state prop directly to Input\` → Wrap Input in <Field state="error"> to apply validation styling
+- ❌ \`Mixing props label/hint AND FieldLabel/FieldError for the same field\` → Pick one: either props-based (label/hint/state) OR composable parts
 
 ---
 
@@ -470,6 +588,7 @@ Text input field. Wrap in Field for labels and validation. Use leftElement/right
 import { Input } from "@usevyre/react"
 
 // Props:
+// modelValue     = string | number
 // size           = "sm" | "md" | "lg" (default: md)
 // leftElement    = ReactNode
 // rightElement   = ReactNode
@@ -481,6 +600,7 @@ import { Input } from "@usevyre/react"
 **Common mistakes:**
 - ❌ \`size="icon"\` → Use size="sm" | "md" | "lg"
 - ❌ \`type="search" for search UI\` → Import Command from @usevyre/react for search palettes
+- ❌ \`Vue: binding Input/Textarea value without v-model\` → Use v-model on <Input>/<Textarea> in Vue; in React use value + onChange
 
 ---
 
@@ -676,6 +796,8 @@ import { AppLayout, Sidebar, SidebarHeader, SidebarContent, SidebarSection, Side
 
 // Props:
 // variant        = "default" | "floating" (default: default)
+// SidebarTrigger.icon = ReactNode
+// SidebarTrigger.collapsedIcon = ReactNode
 
 // Examples:
 <AppLayout>
@@ -691,8 +813,18 @@ import { AppLayout, Sidebar, SidebarHeader, SidebarContent, SidebarSection, Side
   </Sidebar>
   <main>Page content</main>
 </AppLayout>
+<SidebarTrigger icon={<PanelLeftClose />} collapsedIcon={<PanelLeftOpen />} />
+
+// Vue:
+// <SidebarTrigger>
+//   <template #icon><PanelLeftClose /></template>
+//   <template #collapsed-icon><PanelLeftOpen /></template>
+// </SidebarTrigger>
 \`\`\`
 
+**Common mistakes:**
+- ❌ \`Vue: passing icon/collapsedIcon as props on SidebarTrigger\` → Use <template #icon> and <template #collapsed-icon>; React uses icon / collapsedIcon props
+
 ---
 
 ### Skeleton
@@ -1068,6 +1200,180 @@ import { TagGroup, Tag } from "@usevyre/react"
 
 ---
 
+### Item
+
+Layout primitive for list rows, settings rows, and notification rows. Denser than Card — use Item (not Card) for repeated list rows.
+
+\`\`\`tsx
+import { Item, ItemMedia, ItemContent, ItemTitle, ItemDescription, ItemActions, ItemGroup } from "@usevyre/react"
+
+// Props:
+// variant        = "default" | "outlined" | "muted" | "plain" (default: default)
+// size           = "sm" | "md" | "lg" (default: md)
+// clickable      = boolean (default: false)
+
+// Examples:
+<Item>
+  <ItemMedia><BellIcon /></ItemMedia>
+  <ItemContent>
+    <ItemTitle>Notifications</ItemTitle>
+    <ItemDescription>Receive an email when someone mentions you.</ItemDescription>
+  </ItemContent>
+  <ItemActions>
+    <Switch defaultChecked />
+  </ItemActions>
+</Item>
+<ItemGroup separated>
+  <Item clickable>
+    <ItemContent><ItemTitle>Profile</ItemTitle></ItemContent>
+  </Item>
+  <Item clickable>
+    <ItemContent><ItemTitle>Billing</ItemTitle></ItemContent>
+  </Item>
+</ItemGroup>
+\`\`\`
+
+**Common mistakes:**
+- ❌ \`Card used for repeated list rows\` → Use <Item> (optionally inside <ItemGroup separated>) for list/settings rows
+- ❌ \`Item variant="primary"\` → Use variant="default" | "outlined" | "muted"
+- ❌ \`raw text directly inside Item\` → Wrap text in <ItemContent><ItemTitle>…</ItemTitle></ItemContent>
+
+---
+
+### Kanban
+
+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.
+
+\`\`\`tsx
+import { Kanban } from "@usevyre/react"
+
+// Props:
+// value          = KanbanColumn[]
+// onChange       = function
+// renderCard     = function
+// onCardClick    = function
+
+// Examples:
+const [columns, setColumns] = useState([
+  { id: "todo",  title: "To Do",       cards: [{ id: "1", title: "Spec API" }] },
+  { id: "doing", title: "In Progress", cards: [] },
+  { id: "done",  title: "Done",        cards: [{ id: "2", title: "Kickoff" }] },
+]);
+<Kanban value={columns} onChange={setColumns} />
+<Kanban
+  value={columns}
+  onChange={setColumns}
+  onCardClick={(card) => openDetail(card.id)}
+  renderCard={(card) => (
+    <><strong>{card.title}</strong><Badge>{card.id}</Badge></>
+  )}
+/>
+const [cols, setCols] = useState([
+  { id: "doing", title: "In Progress", color: "teal", cards: [
+    { id: "t1", title: "OAuth", assignee: "AK", progress: 60, color: "warning" },
+  ]},
+]);
+<Kanban
+  value={cols}
+  onChange={setCols}
+  renderCard={(card) => (
+    <><strong>{card.title}</strong><Progress value={card.progress} /></>
+  )}
+/>
+\`\`\`
+
+**Common mistakes:**
+- ❌ \`Kanban without onChange (or ignoring it)\` → Store columns in state and setColumns in onChange (v-model in Vue)
+- ❌ \`Duplicate card ids across columns\` → Use globally-unique card ids across the entire board
+- ❌ \`Mutating value in place then calling onChange\` → Pass the new array Kanban gives you straight to setState / v-model
+- ❌ \`color="blue" (or any non-semantic value)\` → Use one of: "default" | "accent" | "teal" | "success" | "warning" | "danger"
+
+---
+
+### Conversation
+
+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.
+
+\`\`\`tsx
+import { Conversation } from "@usevyre/react"
+
+// Props:
+// value          = ConversationMessage[]
+// currentUserId  = string
+// composer       = boolean (default: false)
+// onSend         = function
+// placeholder    = string (default: Write a message…)
+// typing         = boolean | string (default: false)
+// allowAttachments = boolean (default: false)
+// accept         = string
+// renderMessage  = function
+// renderComposer = function
+
+// Examples:
+const [messages, setMessages] = useState([
+  { id: "1", authorId: "sam", authorName: "Sam", text: "Hey!" },
+  { id: "2", authorId: "me", text: "Hi \ud83d\udc4b", status: "read" },
+]);
+<Conversation
+  value={messages}
+  currentUserId="me"
+  composer
+  onSend={(t) => setMessages((m) => [...m, { id: crypto.randomUUID(), authorId: "me", text: t }])}
+/>
+<Conversation
+  value={messages}
+  currentUserId="me"
+  typing="Sam is typing"
+  renderMessage={(m) => <strong>{m.text}</strong>}
+/>
+const messages = [
+  { id: "1", authorId: "sam", authorName: "Sam", text: "Moodboard \ud83d\udc47",
+    attachments: [{ kind: "image", url: "/board.png", name: "board.png" }] },
+  { id: "2", authorId: "me", text: "Specs:", status: "read",
+    attachments: [{ kind: "file", url: "/spec.pdf", name: "spec.pdf", size: "2.4 MB" }] },
+];
+<Conversation value={messages} currentUserId="me" />
+\`\`\`
+
+**Common mistakes:**
+- ❌ \`Conversation without currentUserId\` → Always pass currentUserId matching one of the message authorId values
+- ❌ \`Expecting Conversation to store/append messages\` → Append to your own state in onSend (or @send) and pass it back via value
+- ❌ \`composer without onSend (React) / @send (Vue)\` → Provide onSend / @send to append the message to value
+- ❌ \`Treating onSend as (text) only when using allowAttachments\` → Handle onSend(text, files) — map files to message attachments and append
+
+---
+
+### DateRangePicker
+
+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.
+
+\`\`\`tsx
+import { DateRangePicker } from "@usevyre/react"
+
+// Props:
+// value          = { from: Date | null; to: Date | null } | null
+// onChange       = function
+// placeholder    = string (default: Pick a date range)
+// numberOfMonths = "1" | "2" (default: 2)
+// presets        = boolean | DateRangePreset[] (default: false)
+// minDate        = Date
+// maxDate        = Date
+// disabled       = function
+// weekStartsOn   = "0" | "1" (default: 1)
+
+// Examples:
+const [range, setRange] = useState({ from: null, to: null });
+<DateRangePicker value={range} onChange={setRange} presets />
+<DateRangePicker value={range} onChange={setRange} numberOfMonths={1} />
+\`\`\`
+
+**Common mistakes:**
+- ❌ \`value={[from, to]}\` → Use value={{ from, to }} and read range.from / range.to
+- ❌ \`DateRangePicker for a single date\` → Use <DatePicker /> for a single date
+- ❌ \`presets="true" (string)\` → Use the bare prop: presets  (or presets={true})
+
+---
+
 ## Hallucination Guard — Common AI Mistakes
 
 The following prop values and patterns do NOT exist in useVyre.
@@ -1087,18 +1393,30 @@ If you generate these, you are hallucinating.
 - ❌ \`<Button color="...">\` → Use variant prop instead
 - ❌ \`<Button icon={...}>\` → Use leftIcon={...} or rightIcon={...}
 - ❌ \`<Button size="icon" without aria-label>\` → Add aria-label describing the action
-- ❌ \`<Calendar Using Calendar for time selection>\` → Combine with a separate time Input if time selection is needed
+- ❌ \`<Calendar Calendar for an input field that opens a popover>\` → Use <DatePicker /> (single date) or <DateRangePicker /> (range)
+- ❌ \`<Calendar value as tuple for mode="single">\` → Pass value matching mode; use mode="range" for [start,end]
+- ❌ \`<DatePicker DatePicker mode="range" for { from, to } object>\` → Use <DateRangePicker /> for the { from, to } object API + presets + dual month
+- ❌ \`<DatePicker DatePicker without value/onChange>\` → Provide value and onChange (e.g. from useState)
 - ❌ \`<Card variant="primary">\` → Use variant="elevated" | "outlined" | "ghost" | "accent"
 - ❌ \`<Checkbox size="lg">\` → Use size="md"
+- ❌ \`<RadioGroup <Radio> used outside a <RadioGroup>>\` → Always wrap <Radio> in <RadioGroup>
+- ❌ \`<RadioGroup RadioGroup without value/onChange (React) or v-model (Vue)>\` → Bind value + onChange (React) or v-model (Vue); or defaultValue for uncontrolled in React
+- ❌ \`<RadioGroup Using Checkbox for mutually-exclusive choices>\` → Use RadioGroup + Radio (or options) for one-of-many
+- ❌ \`<RichTextEditor RichTextEditor without value/onChange (React) or v-model (Vue)>\` → Keep the HTML string in state and update it in onChange / v-model
+- ❌ \`<RichTextEditor Rendering value as text or with dangerouslySetInnerHTML elsewhere without sanitising>\` → Sanitise (e.g. DOMPurify) before re-rendering untrusted RTE output
+- ❌ \`<RichTextEditor toolbar="bold" (string)>\` → Pass an array, e.g. toolbar={["bold","italic","link"]}
 - ❌ \`<Command Using Input type="search" for search UI>\` → Use Command + CommandInput + CommandList + CommandItem
 - ❌ \`<DropdownMenu DropdownItem variant="primary">\` → Use variant="danger" for destructive items only
 - ❌ \`<Field Applying state prop directly to Input>\` → Wrap Input in <Field state="error"> to apply validation styling
+- ❌ \`<Field Mixing props label/hint AND FieldLabel/FieldError for the same field>\` → Pick one: either props-based (label/hint/state) OR composable parts
 - ❌ \`<Input size="icon">\` → Use size="sm" | "md" | "lg"
 - ❌ \`<Input type="search" for search UI>\` → Import Command from @usevyre/react for search palettes
+- ❌ \`<Input Vue: binding Input/Textarea value without v-model>\` → Use v-model on <Input>/<Textarea> in Vue; in React use value + onChange
 - ❌ \`<Modal size="xl">\` → Use size="lg" or size="full"
 - ❌ \`<Popover placement="top-center">\` → Use placement="top" for centered placement
 - ❌ \`<Progress value > 100>\` → Normalize your value to 0–100 range before passing
 - ❌ \`<Select Passing strings directly as children>\` → Pass options={[{ value: 'a', label: 'Option A' }]}
+- ❌ \`<Sidebar Vue: passing icon/collapsedIcon as props on SidebarTrigger>\` → Use <template #icon> and <template #collapsed-icon>; React uses icon / collapsedIcon props
 - ❌ \`<Toast Rendering <Toast> directly in JSX>\` → Use: const { toast } = useToast(); then toast({ title, variant })
 - ❌ \`<Toast variant="error">\` → Use variant="danger"
 - ❌ \`<Toast variant="info">\` → Use variant="default"
@@ -1119,6 +1437,20 @@ If you generate these, you are hallucinating.
 - ❌ \`<Tag Tag size="xl">\` → Use size="lg"
 - ❌ \`<TagGroup TagGroup without Tag children>\` → Place <Tag> elements as direct children
 - ❌ \`<TagGroup Using TagGroup for tag input>\` → Use TagsInput for an editable tag field
+- ❌ \`<Item Card used for repeated list rows>\` → Use <Item> (optionally inside <ItemGroup separated>) for list/settings rows
+- ❌ \`<Item Item variant="primary">\` → Use variant="default" | "outlined" | "muted"
+- ❌ \`<Item raw text directly inside Item>\` → Wrap text in <ItemContent><ItemTitle>…</ItemTitle></ItemContent>
+- ❌ \`<Kanban Kanban without onChange (or ignoring it)>\` → Store columns in state and setColumns in onChange (v-model in Vue)
+- ❌ \`<Kanban Duplicate card ids across columns>\` → Use globally-unique card ids across the entire board
+- ❌ \`<Kanban Mutating value in place then calling onChange>\` → Pass the new array Kanban gives you straight to setState / v-model
+- ❌ \`<Kanban color="blue" (or any non-semantic value)>\` → Use one of: "default" | "accent" | "teal" | "success" | "warning" | "danger"
+- ❌ \`<Conversation Conversation without currentUserId>\` → Always pass currentUserId matching one of the message authorId values
+- ❌ \`<Conversation Expecting Conversation to store/append messages>\` → Append to your own state in onSend (or @send) and pass it back via value
+- ❌ \`<Conversation composer without onSend (React) / @send (Vue)>\` → Provide onSend / @send to append the message to value
+- ❌ \`<Conversation Treating onSend as (text) only when using allowAttachments>\` → Handle onSend(text, files) — map files to message attachments and append
+- ❌ \`<DateRangePicker value={[from, to]}>\` → Use value={{ from, to }} and read range.from / range.to
+- ❌ \`<DateRangePicker DateRangePicker for a single date>\` → Use <DatePicker /> for a single date
+- ❌ \`<DateRangePicker presets="true" (string)>\` → Use the bare prop: presets  (or presets={true})
 
 ---
 
@@ -1173,7 +1505,7 @@ alwaysApply: true
 ---
 
 # useVyre Design System — Cursor Rules
-# Version: 1.1.0
+# Version: 1.2.0
 
 You are working in a project using the useVyre design system (@usevyre/react).
 Follow these rules strictly when generating any UI code.
@@ -1252,13 +1584,26 @@ Never do:
 - ❌ size="icon" without aria-label → ✅ Add aria-label describing the action
 
 ## Calendar
-Date picker calendar widget for selecting single dates or ranges.
+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"\`
 
 Valid props:
 
 Never do:
-- ❌ Using Calendar for time selection → ✅ Combine with a separate time Input if time selection is needed
+- ❌ Calendar for an input field that opens a popover → ✅ Use <DatePicker /> (single date) or <DateRangePicker /> (range)
+- ❌ value as tuple for mode="single" → ✅ Pass value matching mode; use mode="range" for [start,end]
+
+## DatePicker
+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"\`
+
+Valid props:
+- mode: "single" | "range" | "multiple" [default: single]
+- weekStartsOn: "0" | "1" [default: 1]
+
+Never do:
+- ❌ DatePicker mode="range" for { from, to } object → ✅ Use <DateRangePicker /> for the { from, to } object API + presets + dual month
+- ❌ DatePicker without value/onChange → ✅ Provide value and onChange (e.g. from useState)
 
 ## Card
 Content container with optional header, body, and footer sections.
@@ -1280,6 +1625,30 @@ Valid props:
 Never do:
 - ❌ size="lg" → ✅ Use size="md"
 
+## RadioGroup
+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"\`
+
+Valid props:
+- size: "sm" | "md" [default: md]
+- orientation: "vertical" | "horizontal" [default: vertical]
+
+Never do:
+- ❌ <Radio> used outside a <RadioGroup> → ✅ Always wrap <Radio> in <RadioGroup>
+- ❌ RadioGroup without value/onChange (React) or v-model (Vue) → ✅ Bind value + onChange (React) or v-model (Vue); or defaultValue for uncontrolled in React
+- ❌ Using Checkbox for mutually-exclusive choices → ✅ Use RadioGroup + Radio (or options) for one-of-many
+
+## RichTextEditor
+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"\`
+
+Valid props:
+
+Never do:
+- ❌ RichTextEditor without value/onChange (React) or v-model (Vue) → ✅ Keep the HTML string in state and update it in onChange / v-model
+- ❌ Rendering value as text or with dangerouslySetInnerHTML elsewhere without sanitising → ✅ Sanitise (e.g. DOMPurify) before re-rendering untrusted RTE output
+- ❌ toolbar="bold" (string) → ✅ Pass an array, e.g. toolbar={["bold","italic","link"]}
+
 ## Command
 Command palette / search dialog. Use for search-first navigation or quick actions.
 Import: \`import { Command, CommandInput, CommandList, CommandEmpty, CommandGroup, CommandItem, CommandDialog } from "@usevyre/react"\`
@@ -1297,7 +1666,7 @@ Never do:
 - ❌ DropdownItem variant="primary" → ✅ Use variant="danger" for destructive items only
 
 ## Field
-Form field wrapper providing label, hint text, and validation state for Input or Textarea.
+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"\`
 
 Valid props:
@@ -1305,6 +1674,7 @@ Valid props:
 
 Never do:
 - ❌ Applying state prop directly to Input → ✅ Wrap Input in <Field state="error"> to apply validation styling
+- ❌ Mixing props label/hint AND FieldLabel/FieldError for the same field → ✅ Pick one: either props-based (label/hint/state) OR composable parts
 
 ## Input
 Text input field. Wrap in Field for labels and validation. Use leftElement/rightElement for icons.
@@ -1316,6 +1686,7 @@ Valid props:
 Never do:
 - ❌ size="icon" → ✅ Use size="sm" | "md" | "lg"
 - ❌ type="search" for search UI → ✅ Import Command from @usevyre/react for search palettes
+- ❌ Vue: binding Input/Textarea value without v-model → ✅ Use v-model on <Input>/<Textarea> in Vue; in React use value + onChange
 
 ## Label
 Accessible form label. Associate with input via htmlFor.
@@ -1392,6 +1763,9 @@ Import: \`import { AppLayout, Sidebar, SidebarHeader, SidebarContent, SidebarSec
 Valid props:
 - variant: "default" | "floating" [default: default]
 
+Never do:
+- ❌ Vue: passing icon/collapsedIcon as props on SidebarTrigger → ✅ Use <template #icon> and <template #collapsed-icon>; React uses icon / collapsedIcon props
+
 ## Skeleton
 Loading placeholder that mimics the shape of content while data loads.
 Import: \`import { Skeleton } from "@usevyre/react"\`
@@ -1523,13 +1897,63 @@ Never do:
 - ❌ TagGroup without Tag children → ✅ Place <Tag> elements as direct children
 - ❌ Using TagGroup for tag input → ✅ Use TagsInput for an editable tag field
 
+## Item
+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"\`
+
+Valid props:
+- variant: "default" | "outlined" | "muted" | "plain" [default: default]
+- size: "sm" | "md" | "lg" [default: md]
+
+Never do:
+- ❌ Card used for repeated list rows → ✅ Use <Item> (optionally inside <ItemGroup separated>) for list/settings rows
+- ❌ Item variant="primary" → ✅ Use variant="default" | "outlined" | "muted"
+- ❌ raw text directly inside Item → ✅ Wrap text in <ItemContent><ItemTitle>…</ItemTitle></ItemContent>
+
+## Kanban
+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"\`
+
+Valid props:
+
+Never do:
+- ❌ Kanban without onChange (or ignoring it) → ✅ Store columns in state and setColumns in onChange (v-model in Vue)
+- ❌ Duplicate card ids across columns → ✅ Use globally-unique card ids across the entire board
+- ❌ Mutating value in place then calling onChange → ✅ Pass the new array Kanban gives you straight to setState / v-model
+- ❌ color="blue" (or any non-semantic value) → ✅ Use one of: "default" | "accent" | "teal" | "success" | "warning" | "danger"
+
+## Conversation
+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"\`
+
+Valid props:
+
+Never do:
+- ❌ Conversation without currentUserId → ✅ Always pass currentUserId matching one of the message authorId values
+- ❌ Expecting Conversation to store/append messages → ✅ Append to your own state in onSend (or @send) and pass it back via value
+- ❌ composer without onSend (React) / @send (Vue) → ✅ Provide onSend / @send to append the message to value
+- ❌ Treating onSend as (text) only when using allowAttachments → ✅ Handle onSend(text, files) — map files to message attachments and append
+
+## DateRangePicker
+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"\`
+
+Valid props:
+- numberOfMonths: "1" | "2" [default: 2]
+- weekStartsOn: "0" | "1" [default: 1]
+
+Never do:
+- ❌ value={[from, to]} → ✅ Use value={{ from, to }} and read range.from / range.to
+- ❌ DateRangePicker for a single date → ✅ Use <DatePicker /> for a single date
+- ❌ presets="true" (string) → ✅ Use the bare prop: presets  (or presets={true})
+
 ## Token Rules
 
 Use --vyre-color-semantic-* for all colors. Never use primitive tokens.
 Use --vyre-spacing-* for all spacing. Never use raw px in component code.
 Use --vyre-border-radius-* for border radius.`;
 export const claudeContext = `# useVyre Design System Context
-# Version: 1.1.0
+# Version: 1.2.0
 
 You are working in a codebase that uses the useVyre design system.
 Follow the rules below strictly when writing any UI code.
@@ -1841,7 +2265,7 @@ import { Button } from "@usevyre/react"
 
 ### Calendar
 
-Date picker calendar widget for selecting single dates or ranges.
+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.
 
 \`\`\`tsx
 import { Calendar } from "@usevyre/react"
@@ -1850,6 +2274,7 @@ import { Calendar } from "@usevyre/react"
 // value          = Date | null
 // onChange       = function
 // disabled       = boolean (default: false)
+// defaultMonth   = Date
 
 // Examples:
 const [date, setDate] = useState(null);
@@ -1857,7 +2282,39 @@ const [date, setDate] = useState(null);
 \`\`\`
 
 **Common mistakes:**
-- ❌ \`Using Calendar for time selection\` → Combine with a separate time Input if time selection is needed
+- ❌ \`Calendar for an input field that opens a popover\` → Use <DatePicker /> (single date) or <DateRangePicker /> (range)
+- ❌ \`value as tuple for mode="single"\` → Pass value matching mode; use mode="range" for [start,end]
+
+---
+
+### DatePicker
+
+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.
+
+\`\`\`tsx
+import { DatePicker } from "@usevyre/react"
+
+// Props:
+// value          = Date | [Date, Date] | Date[] | null
+// onChange       = function
+// mode           = "single" | "range" | "multiple" (default: single)
+// placeholder    = string (default: Pick a date)
+// showTime       = boolean (default: false)
+// minDate        = Date
+// maxDate        = Date
+// disabled       = function
+// weekStartsOn   = "0" | "1" (default: 1)
+// inputClassName = string
+
+// Examples:
+const [date, setDate] = useState(null);
+<DatePicker value={date} onChange={setDate} placeholder="Pick a date" />
+<DatePicker value={date} onChange={setDate} showTime />
+\`\`\`
+
+**Common mistakes:**
+- ❌ \`DatePicker mode="range" for { from, to } object\` → Use <DateRangePicker /> for the { from, to } object API + presets + dual month
+- ❌ \`DatePicker without value/onChange\` → Provide value and onChange (e.g. from useState)
 
 ---
 
@@ -1917,6 +2374,78 @@ import { Checkbox } from "@usevyre/react"
 
 ---
 
+### RadioGroup
+
+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.
+
+\`\`\`tsx
+import { RadioGroup, Radio } from "@usevyre/react"
+
+// Props:
+// value          = string
+// defaultValue   = string
+// onChange       = function
+// name           = string
+// disabled       = boolean (default: false)
+// size           = "sm" | "md" (default: md)
+// orientation    = "vertical" | "horizontal" (default: vertical)
+// options        = { value: string; label?: string; description?: string; disabled?: boolean }[]
+
+// Examples:
+<RadioGroup
+  value={plan}
+  onChange={setPlan}
+  options={[
+    { value: "free", label: "Free", description: "For hobby projects" },
+    { value: "pro",  label: "Pro",  description: "For teams" },
+  ]}
+/>
+<RadioGroup value={plan} onChange={setPlan} orientation="horizontal">
+  <Radio value="free" label="Free" />
+  <Radio value="pro"  label="Pro" />
+</RadioGroup>
+\`\`\`
+
+**Common mistakes:**
+- ❌ \`<Radio> used outside a <RadioGroup>\` → Always wrap <Radio> in <RadioGroup>
+- ❌ \`RadioGroup without value/onChange (React) or v-model (Vue)\` → Bind value + onChange (React) or v-model (Vue); or defaultValue for uncontrolled in React
+- ❌ \`Using Checkbox for mutually-exclusive choices\` → Use RadioGroup + Radio (or options) for one-of-many
+
+---
+
+### RichTextEditor
+
+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.
+
+\`\`\`tsx
+import { RichTextEditor } from "@usevyre/react"
+
+// Props:
+// value          = string
+// onChange       = function
+// placeholder    = string (default: Write something…)
+// disabled       = boolean (default: false)
+// readOnly       = boolean (default: false)
+// toolbar        = RichTextTool[]
+// minHeight      = string (default: 10rem)
+
+// Examples:
+const [html, setHtml] = useState("<p>Hello <strong>world</strong></p>");
+<RichTextEditor value={html} onChange={setHtml} placeholder="Write…" />
+<RichTextEditor
+  value={html}
+  onChange={setHtml}
+  toolbar={["bold", "italic", "link"]}
+/>
+\`\`\`
+
+**Common mistakes:**
+- ❌ \`RichTextEditor without value/onChange (React) or v-model (Vue)\` → Keep the HTML string in state and update it in onChange / v-model
+- ❌ \`Rendering value as text or with dangerouslySetInnerHTML elsewhere without sanitising\` → Sanitise (e.g. DOMPurify) before re-rendering untrusted RTE output
+- ❌ \`toolbar="bold" (string)\` → Pass an array, e.g. toolbar={["bold","italic","link"]}
+
+---
+
 ### Command
 
 Command palette / search dialog. Use for search-first navigation or quick actions.
@@ -1968,7 +2497,7 @@ import { DropdownMenu, DropdownItem, DropdownSeparator, DropdownCheckboxItem, Dr
 
 ### Field
 
-Form field wrapper providing label, hint text, and validation state for Input or Textarea.
+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.
 
 \`\`\`tsx
 import { Field, Input, Textarea } from "@usevyre/react"
@@ -1986,10 +2515,23 @@ import { Field, Input, Textarea } from "@usevyre/react"
 <Field label="Search">
   <Input leftElement={<SearchIcon />} placeholder="Search..." />
 </Field>
+<Field>
+  <FieldLabel required htmlFor="email">Email</FieldLabel>
+  <Input id="email" type="email" />
+  <FieldDescription>We\u2019ll never share it.</FieldDescription>
+  <FieldError>{errors.email}</FieldError>
+</Field>
+
+// Two controls side by side
+<FieldGroup orientation="horizontal">
+  <Field label="First name"><Input /></Field>
+  <Field label="Last name"><Input /></Field>
+</FieldGroup>
 \`\`\`
 
 **Common mistakes:**
 - ❌ \`Applying state prop directly to Input\` → Wrap Input in <Field state="error"> to apply validation styling
+- ❌ \`Mixing props label/hint AND FieldLabel/FieldError for the same field\` → Pick one: either props-based (label/hint/state) OR composable parts
 
 ---
 
@@ -2001,6 +2543,7 @@ Text input field. Wrap in Field for labels and validation. Use leftElement/right
 import { Input } from "@usevyre/react"
 
 // Props:
+// modelValue     = string | number
 // size           = "sm" | "md" | "lg" (default: md)
 // leftElement    = ReactNode
 // rightElement   = ReactNode
@@ -2012,6 +2555,7 @@ import { Input } from "@usevyre/react"
 **Common mistakes:**
 - ❌ \`size="icon"\` → Use size="sm" | "md" | "lg"
 - ❌ \`type="search" for search UI\` → Import Command from @usevyre/react for search palettes
+- ❌ \`Vue: binding Input/Textarea value without v-model\` → Use v-model on <Input>/<Textarea> in Vue; in React use value + onChange
 
 ---
 
@@ -2207,6 +2751,8 @@ import { AppLayout, Sidebar, SidebarHeader, SidebarContent, SidebarSection, Side
 
 // Props:
 // variant        = "default" | "floating" (default: default)
+// SidebarTrigger.icon = ReactNode
+// SidebarTrigger.collapsedIcon = ReactNode
 
 // Examples:
 <AppLayout>
@@ -2222,8 +2768,18 @@ import { AppLayout, Sidebar, SidebarHeader, SidebarContent, SidebarSection, Side
   </Sidebar>
   <main>Page content</main>
 </AppLayout>
+<SidebarTrigger icon={<PanelLeftClose />} collapsedIcon={<PanelLeftOpen />} />
+
+// Vue:
+// <SidebarTrigger>
+//   <template #icon><PanelLeftClose /></template>
+//   <template #collapsed-icon><PanelLeftOpen /></template>
+// </SidebarTrigger>
 \`\`\`
 
+**Common mistakes:**
+- ❌ \`Vue: passing icon/collapsedIcon as props on SidebarTrigger\` → Use <template #icon> and <template #collapsed-icon>; React uses icon / collapsedIcon props
+
 ---
 
 ### Skeleton
@@ -2599,59 +3155,259 @@ import { TagGroup, Tag } from "@usevyre/react"
 
 ---
 
-## Hallucination Guard — Common AI Mistakes
-
-The following prop values and patterns do NOT exist in useVyre.
-If you generate these, you are hallucinating.
+### Item
 
-- ❌ \`<Accordion Accordion without AccordionItem>\` → Always compose: Accordion > AccordionItem > AccordionTrigger + AccordionContent
-- ❌ \`<Alert variant="error">\` → Use variant="danger"
-- ❌ \`<Alert variant="primary">\` → Use variant="info" | "success" | "warning" | "danger"
-- ❌ \`<Avatar size="xs">\` → Use size="sm"
-- ❌ \`<Avatar size="2xl">\` → Use size="xl"
-- ❌ \`<Badge variant="primary">\` → Use variant="accent" for brand color
-- ❌ \`<Badge variant="error">\` → Use variant="danger"
-- ❌ \`<Badge variant="info">\` → Use variant="teal" for info-like styling
-- ❌ \`<Breadcrumb Using plain <a> tags inside Breadcrumb>\` → Use BreadcrumbItem > BreadcrumbLink for each crumb
-- ❌ \`<Button variant="blue">\` → Use variant="accent" for brand amber, or variant="teal" for teal
-- ❌ \`<Button size="xl">\` → Use size="lg"
-- ❌ \`<Button color="...">\` → Use variant prop instead
-- ❌ \`<Button icon={...}>\` → Use leftIcon={...} or rightIcon={...}
-- ❌ \`<Button size="icon" without aria-label>\` → Add aria-label describing the action
-- ❌ \`<Calendar Using Calendar for time selection>\` → Combine with a separate time Input if time selection is needed
-- ❌ \`<Card variant="primary">\` → Use variant="elevated" | "outlined" | "ghost" | "accent"
-- ❌ \`<Checkbox size="lg">\` → Use size="md"
-- ❌ \`<Command Using Input type="search" for search UI>\` → Use Command + CommandInput + CommandList + CommandItem
-- ❌ \`<DropdownMenu DropdownItem variant="primary">\` → Use variant="danger" for destructive items only
-- ❌ \`<Field Applying state prop directly to Input>\` → Wrap Input in <Field state="error"> to apply validation styling
-- ❌ \`<Input size="icon">\` → Use size="sm" | "md" | "lg"
-- ❌ \`<Input type="search" for search UI>\` → Import Command from @usevyre/react for search palettes
-- ❌ \`<Modal size="xl">\` → Use size="lg" or size="full"
-- ❌ \`<Popover placement="top-center">\` → Use placement="top" for centered placement
-- ❌ \`<Progress value > 100>\` → Normalize your value to 0–100 range before passing
-- ❌ \`<Select Passing strings directly as children>\` → Pass options={[{ value: 'a', label: 'Option A' }]}
-- ❌ \`<Toast Rendering <Toast> directly in JSX>\` → Use: const { toast } = useToast(); then toast({ title, variant })
-- ❌ \`<Toast variant="error">\` → Use variant="danger"
-- ❌ \`<Toast variant="info">\` → Use variant="default"
-- ❌ \`<Tooltip Using Tooltip for rich content (forms, buttons, etc.)>\` → Use Popover for rich interactive content
-- ❌ \`<Typography Using raw <h1>, <p> tags instead of Typography components>\` → Use <Heading>, <Text>, <Lead> from @usevyre/react
-- ❌ \`<ButtonGroup ButtonGroup variant="...">\` → Set variant on each <Button> inside the group
-- ❌ \`<ButtonGroup ButtonGroup without Button children>\` → Place <Button> elements as direct children
-- ❌ \`<TagsInput TagsInput value={string}>\` → Pass an array: value={['react','vue']}
-- ❌ \`<TagsInput TagsInput without onChange>\` → Provide value and onChange (React) or v-model (Vue)
-- ❌ \`<Combobox Combobox value="">\` → Use value={null} for no selection
-- ❌ \`<Combobox Combobox options={string[]}>\` → Use [{ value: 'ts', label: 'TypeScript' }]
-- ❌ \`<Combobox Using Combobox for command palette>\` → Use Command for command palettes
-- ❌ \`<DataGrid DataGrid expecting built-in pagination>\` → Slice rows yourself and use the Pagination component
-- ❌ \`<DataGrid DataGrid expecting built-in filtering>\` → Filter the rows array before passing it in
-- ❌ \`<DataGrid sortable without onSort>\` → Handle onSort and sort the rows array in your state
-- ❌ \`<Tag Tag variant="success">\` → Use Badge for success/warning/teal status colors; Tag is for categories/filters
-- ❌ \`<Tag Using Tag for tag input>\` → Use TagsInput for adding/removing tags via keyboard
-- ❌ \`<Tag Tag size="xl">\` → Use size="lg"
-- ❌ \`<TagGroup TagGroup without Tag children>\` → Place <Tag> elements as direct children
-- ❌ \`<TagGroup Using TagGroup for tag input>\` → Use TagsInput for an editable tag field
+Layout primitive for list rows, settings rows, and notification rows. Denser than Card — use Item (not Card) for repeated list rows.
 
----
+\`\`\`tsx
+import { Item, ItemMedia, ItemContent, ItemTitle, ItemDescription, ItemActions, ItemGroup } from "@usevyre/react"
+
+// Props:
+// variant        = "default" | "outlined" | "muted" | "plain" (default: default)
+// size           = "sm" | "md" | "lg" (default: md)
+// clickable      = boolean (default: false)
+
+// Examples:
+<Item>
+  <ItemMedia><BellIcon /></ItemMedia>
+  <ItemContent>
+    <ItemTitle>Notifications</ItemTitle>
+    <ItemDescription>Receive an email when someone mentions you.</ItemDescription>
+  </ItemContent>
+  <ItemActions>
+    <Switch defaultChecked />
+  </ItemActions>
+</Item>
+<ItemGroup separated>
+  <Item clickable>
+    <ItemContent><ItemTitle>Profile</ItemTitle></ItemContent>
+  </Item>
+  <Item clickable>
+    <ItemContent><ItemTitle>Billing</ItemTitle></ItemContent>
+  </Item>
+</ItemGroup>
+\`\`\`
+
+**Common mistakes:**
+- ❌ \`Card used for repeated list rows\` → Use <Item> (optionally inside <ItemGroup separated>) for list/settings rows
+- ❌ \`Item variant="primary"\` → Use variant="default" | "outlined" | "muted"
+- ❌ \`raw text directly inside Item\` → Wrap text in <ItemContent><ItemTitle>…</ItemTitle></ItemContent>
+
+---
+
+### Kanban
+
+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.
+
+\`\`\`tsx
+import { Kanban } from "@usevyre/react"
+
+// Props:
+// value          = KanbanColumn[]
+// onChange       = function
+// renderCard     = function
+// onCardClick    = function
+
+// Examples:
+const [columns, setColumns] = useState([
+  { id: "todo",  title: "To Do",       cards: [{ id: "1", title: "Spec API" }] },
+  { id: "doing", title: "In Progress", cards: [] },
+  { id: "done",  title: "Done",        cards: [{ id: "2", title: "Kickoff" }] },
+]);
+<Kanban value={columns} onChange={setColumns} />
+<Kanban
+  value={columns}
+  onChange={setColumns}
+  onCardClick={(card) => openDetail(card.id)}
+  renderCard={(card) => (
+    <><strong>{card.title}</strong><Badge>{card.id}</Badge></>
+  )}
+/>
+const [cols, setCols] = useState([
+  { id: "doing", title: "In Progress", color: "teal", cards: [
+    { id: "t1", title: "OAuth", assignee: "AK", progress: 60, color: "warning" },
+  ]},
+]);
+<Kanban
+  value={cols}
+  onChange={setCols}
+  renderCard={(card) => (
+    <><strong>{card.title}</strong><Progress value={card.progress} /></>
+  )}
+/>
+\`\`\`
+
+**Common mistakes:**
+- ❌ \`Kanban without onChange (or ignoring it)\` → Store columns in state and setColumns in onChange (v-model in Vue)
+- ❌ \`Duplicate card ids across columns\` → Use globally-unique card ids across the entire board
+- ❌ \`Mutating value in place then calling onChange\` → Pass the new array Kanban gives you straight to setState / v-model
+- ❌ \`color="blue" (or any non-semantic value)\` → Use one of: "default" | "accent" | "teal" | "success" | "warning" | "danger"
+
+---
+
+### Conversation
+
+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.
+
+\`\`\`tsx
+import { Conversation } from "@usevyre/react"
+
+// Props:
+// value          = ConversationMessage[]
+// currentUserId  = string
+// composer       = boolean (default: false)
+// onSend         = function
+// placeholder    = string (default: Write a message…)
+// typing         = boolean | string (default: false)
+// allowAttachments = boolean (default: false)
+// accept         = string
+// renderMessage  = function
+// renderComposer = function
+
+// Examples:
+const [messages, setMessages] = useState([
+  { id: "1", authorId: "sam", authorName: "Sam", text: "Hey!" },
+  { id: "2", authorId: "me", text: "Hi \ud83d\udc4b", status: "read" },
+]);
+<Conversation
+  value={messages}
+  currentUserId="me"
+  composer
+  onSend={(t) => setMessages((m) => [...m, { id: crypto.randomUUID(), authorId: "me", text: t }])}
+/>
+<Conversation
+  value={messages}
+  currentUserId="me"
+  typing="Sam is typing"
+  renderMessage={(m) => <strong>{m.text}</strong>}
+/>
+const messages = [
+  { id: "1", authorId: "sam", authorName: "Sam", text: "Moodboard \ud83d\udc47",
+    attachments: [{ kind: "image", url: "/board.png", name: "board.png" }] },
+  { id: "2", authorId: "me", text: "Specs:", status: "read",
+    attachments: [{ kind: "file", url: "/spec.pdf", name: "spec.pdf", size: "2.4 MB" }] },
+];
+<Conversation value={messages} currentUserId="me" />
+\`\`\`
+
+**Common mistakes:**
+- ❌ \`Conversation without currentUserId\` → Always pass currentUserId matching one of the message authorId values
+- ❌ \`Expecting Conversation to store/append messages\` → Append to your own state in onSend (or @send) and pass it back via value
+- ❌ \`composer without onSend (React) / @send (Vue)\` → Provide onSend / @send to append the message to value
+- ❌ \`Treating onSend as (text) only when using allowAttachments\` → Handle onSend(text, files) — map files to message attachments and append
+
+---
+
+### DateRangePicker
+
+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.
+
+\`\`\`tsx
+import { DateRangePicker } from "@usevyre/react"
+
+// Props:
+// value          = { from: Date | null; to: Date | null } | null
+// onChange       = function
+// placeholder    = string (default: Pick a date range)
+// numberOfMonths = "1" | "2" (default: 2)
+// presets        = boolean | DateRangePreset[] (default: false)
+// minDate        = Date
+// maxDate        = Date
+// disabled       = function
+// weekStartsOn   = "0" | "1" (default: 1)
+
+// Examples:
+const [range, setRange] = useState({ from: null, to: null });
+<DateRangePicker value={range} onChange={setRange} presets />
+<DateRangePicker value={range} onChange={setRange} numberOfMonths={1} />
+\`\`\`
+
+**Common mistakes:**
+- ❌ \`value={[from, to]}\` → Use value={{ from, to }} and read range.from / range.to
+- ❌ \`DateRangePicker for a single date\` → Use <DatePicker /> for a single date
+- ❌ \`presets="true" (string)\` → Use the bare prop: presets  (or presets={true})
+
+---
+
+## Hallucination Guard — Common AI Mistakes
+
+The following prop values and patterns do NOT exist in useVyre.
+If you generate these, you are hallucinating.
+
+- ❌ \`<Accordion Accordion without AccordionItem>\` → Always compose: Accordion > AccordionItem > AccordionTrigger + AccordionContent
+- ❌ \`<Alert variant="error">\` → Use variant="danger"
+- ❌ \`<Alert variant="primary">\` → Use variant="info" | "success" | "warning" | "danger"
+- ❌ \`<Avatar size="xs">\` → Use size="sm"
+- ❌ \`<Avatar size="2xl">\` → Use size="xl"
+- ❌ \`<Badge variant="primary">\` → Use variant="accent" for brand color
+- ❌ \`<Badge variant="error">\` → Use variant="danger"
+- ❌ \`<Badge variant="info">\` → Use variant="teal" for info-like styling
+- ❌ \`<Breadcrumb Using plain <a> tags inside Breadcrumb>\` → Use BreadcrumbItem > BreadcrumbLink for each crumb
+- ❌ \`<Button variant="blue">\` → Use variant="accent" for brand amber, or variant="teal" for teal
+- ❌ \`<Button size="xl">\` → Use size="lg"
+- ❌ \`<Button color="...">\` → Use variant prop instead
+- ❌ \`<Button icon={...}>\` → Use leftIcon={...} or rightIcon={...}
+- ❌ \`<Button size="icon" without aria-label>\` → Add aria-label describing the action
+- ❌ \`<Calendar Calendar for an input field that opens a popover>\` → Use <DatePicker /> (single date) or <DateRangePicker /> (range)
+- ❌ \`<Calendar value as tuple for mode="single">\` → Pass value matching mode; use mode="range" for [start,end]
+- ❌ \`<DatePicker DatePicker mode="range" for { from, to } object>\` → Use <DateRangePicker /> for the { from, to } object API + presets + dual month
+- ❌ \`<DatePicker DatePicker without value/onChange>\` → Provide value and onChange (e.g. from useState)
+- ❌ \`<Card variant="primary">\` → Use variant="elevated" | "outlined" | "ghost" | "accent"
+- ❌ \`<Checkbox size="lg">\` → Use size="md"
+- ❌ \`<RadioGroup <Radio> used outside a <RadioGroup>>\` → Always wrap <Radio> in <RadioGroup>
+- ❌ \`<RadioGroup RadioGroup without value/onChange (React) or v-model (Vue)>\` → Bind value + onChange (React) or v-model (Vue); or defaultValue for uncontrolled in React
+- ❌ \`<RadioGroup Using Checkbox for mutually-exclusive choices>\` → Use RadioGroup + Radio (or options) for one-of-many
+- ❌ \`<RichTextEditor RichTextEditor without value/onChange (React) or v-model (Vue)>\` → Keep the HTML string in state and update it in onChange / v-model
+- ❌ \`<RichTextEditor Rendering value as text or with dangerouslySetInnerHTML elsewhere without sanitising>\` → Sanitise (e.g. DOMPurify) before re-rendering untrusted RTE output
+- ❌ \`<RichTextEditor toolbar="bold" (string)>\` → Pass an array, e.g. toolbar={["bold","italic","link"]}
+- ❌ \`<Command Using Input type="search" for search UI>\` → Use Command + CommandInput + CommandList + CommandItem
+- ❌ \`<DropdownMenu DropdownItem variant="primary">\` → Use variant="danger" for destructive items only
+- ❌ \`<Field Applying state prop directly to Input>\` → Wrap Input in <Field state="error"> to apply validation styling
+- ❌ \`<Field Mixing props label/hint AND FieldLabel/FieldError for the same field>\` → Pick one: either props-based (label/hint/state) OR composable parts
+- ❌ \`<Input size="icon">\` → Use size="sm" | "md" | "lg"
+- ❌ \`<Input type="search" for search UI>\` → Import Command from @usevyre/react for search palettes
+- ❌ \`<Input Vue: binding Input/Textarea value without v-model>\` → Use v-model on <Input>/<Textarea> in Vue; in React use value + onChange
+- ❌ \`<Modal size="xl">\` → Use size="lg" or size="full"
+- ❌ \`<Popover placement="top-center">\` → Use placement="top" for centered placement
+- ❌ \`<Progress value > 100>\` → Normalize your value to 0–100 range before passing
+- ❌ \`<Select Passing strings directly as children>\` → Pass options={[{ value: 'a', label: 'Option A' }]}
+- ❌ \`<Sidebar Vue: passing icon/collapsedIcon as props on SidebarTrigger>\` → Use <template #icon> and <template #collapsed-icon>; React uses icon / collapsedIcon props
+- ❌ \`<Toast Rendering <Toast> directly in JSX>\` → Use: const { toast } = useToast(); then toast({ title, variant })
+- ❌ \`<Toast variant="error">\` → Use variant="danger"
+- ❌ \`<Toast variant="info">\` → Use variant="default"
+- ❌ \`<Tooltip Using Tooltip for rich content (forms, buttons, etc.)>\` → Use Popover for rich interactive content
+- ❌ \`<Typography Using raw <h1>, <p> tags instead of Typography components>\` → Use <Heading>, <Text>, <Lead> from @usevyre/react
+- ❌ \`<ButtonGroup ButtonGroup variant="...">\` → Set variant on each <Button> inside the group
+- ❌ \`<ButtonGroup ButtonGroup without Button children>\` → Place <Button> elements as direct children
+- ❌ \`<TagsInput TagsInput value={string}>\` → Pass an array: value={['react','vue']}
+- ❌ \`<TagsInput TagsInput without onChange>\` → Provide value and onChange (React) or v-model (Vue)
+- ❌ \`<Combobox Combobox value="">\` → Use value={null} for no selection
+- ❌ \`<Combobox Combobox options={string[]}>\` → Use [{ value: 'ts', label: 'TypeScript' }]
+- ❌ \`<Combobox Using Combobox for command palette>\` → Use Command for command palettes
+- ❌ \`<DataGrid DataGrid expecting built-in pagination>\` → Slice rows yourself and use the Pagination component
+- ❌ \`<DataGrid DataGrid expecting built-in filtering>\` → Filter the rows array before passing it in
+- ❌ \`<DataGrid sortable without onSort>\` → Handle onSort and sort the rows array in your state
+- ❌ \`<Tag Tag variant="success">\` → Use Badge for success/warning/teal status colors; Tag is for categories/filters
+- ❌ \`<Tag Using Tag for tag input>\` → Use TagsInput for adding/removing tags via keyboard
+- ❌ \`<Tag Tag size="xl">\` → Use size="lg"
+- ❌ \`<TagGroup TagGroup without Tag children>\` → Place <Tag> elements as direct children
+- ❌ \`<TagGroup Using TagGroup for tag input>\` → Use TagsInput for an editable tag field
+- ❌ \`<Item Card used for repeated list rows>\` → Use <Item> (optionally inside <ItemGroup separated>) for list/settings rows
+- ❌ \`<Item Item variant="primary">\` → Use variant="default" | "outlined" | "muted"
+- ❌ \`<Item raw text directly inside Item>\` → Wrap text in <ItemContent><ItemTitle>…</ItemTitle></ItemContent>
+- ❌ \`<Kanban Kanban without onChange (or ignoring it)>\` → Store columns in state and setColumns in onChange (v-model in Vue)
+- ❌ \`<Kanban Duplicate card ids across columns>\` → Use globally-unique card ids across the entire board
+- ❌ \`<Kanban Mutating value in place then calling onChange>\` → Pass the new array Kanban gives you straight to setState / v-model
+- ❌ \`<Kanban color="blue" (or any non-semantic value)>\` → Use one of: "default" | "accent" | "teal" | "success" | "warning" | "danger"
+- ❌ \`<Conversation Conversation without currentUserId>\` → Always pass currentUserId matching one of the message authorId values
+- ❌ \`<Conversation Expecting Conversation to store/append messages>\` → Append to your own state in onSend (or @send) and pass it back via value
+- ❌ \`<Conversation composer without onSend (React) / @send (Vue)>\` → Provide onSend / @send to append the message to value
+- ❌ \`<Conversation Treating onSend as (text) only when using allowAttachments>\` → Handle onSend(text, files) — map files to message attachments and append
+- ❌ \`<DateRangePicker value={[from, to]}>\` → Use value={{ from, to }} and read range.from / range.to
+- ❌ \`<DateRangePicker DateRangePicker for a single date>\` → Use <DatePicker /> for a single date
+- ❌ \`<DateRangePicker presets="true" (string)>\` → Use the bare prop: presets  (or presets={true})
+
+---
 
 ## Styling Rules for AI Agents
 
@@ -2699,7 +3455,7 @@ If you generate these, you are hallucinating.
 \`\`\`
 `;
 export const windsurfRules = `# useVyre Rules for Windsurf
-# Version: 1.1.0
+# Version: 1.2.0
 
 # useVyre Design System — AI Context
 # Version: 0.2.0
@@ -3008,7 +3764,7 @@ import { Button } from "@usevyre/react"
 
 ### Calendar
 
-Date picker calendar widget for selecting single dates or ranges.
+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.
 
 \`\`\`tsx
 import { Calendar } from "@usevyre/react"
@@ -3017,6 +3773,7 @@ import { Calendar } from "@usevyre/react"
 // value          = Date | null
 // onChange       = function
 // disabled       = boolean (default: false)
+// defaultMonth   = Date
 
 // Examples:
 const [date, setDate] = useState(null);
@@ -3024,7 +3781,39 @@ const [date, setDate] = useState(null);
 \`\`\`
 
 **Common mistakes:**
-- ❌ \`Using Calendar for time selection\` → Combine with a separate time Input if time selection is needed
+- ❌ \`Calendar for an input field that opens a popover\` → Use <DatePicker /> (single date) or <DateRangePicker /> (range)
+- ❌ \`value as tuple for mode="single"\` → Pass value matching mode; use mode="range" for [start,end]
+
+---
+
+### DatePicker
+
+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.
+
+\`\`\`tsx
+import { DatePicker } from "@usevyre/react"
+
+// Props:
+// value          = Date | [Date, Date] | Date[] | null
+// onChange       = function
+// mode           = "single" | "range" | "multiple" (default: single)
+// placeholder    = string (default: Pick a date)
+// showTime       = boolean (default: false)
+// minDate        = Date
+// maxDate        = Date
+// disabled       = function
+// weekStartsOn   = "0" | "1" (default: 1)
+// inputClassName = string
+
+// Examples:
+const [date, setDate] = useState(null);
+<DatePicker value={date} onChange={setDate} placeholder="Pick a date" />
+<DatePicker value={date} onChange={setDate} showTime />
+\`\`\`
+
+**Common mistakes:**
+- ❌ \`DatePicker mode="range" for { from, to } object\` → Use <DateRangePicker /> for the { from, to } object API + presets + dual month
+- ❌ \`DatePicker without value/onChange\` → Provide value and onChange (e.g. from useState)
 
 ---
 
@@ -3084,6 +3873,78 @@ import { Checkbox } from "@usevyre/react"
 
 ---
 
+### RadioGroup
+
+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.
+
+\`\`\`tsx
+import { RadioGroup, Radio } from "@usevyre/react"
+
+// Props:
+// value          = string
+// defaultValue   = string
+// onChange       = function
+// name           = string
+// disabled       = boolean (default: false)
+// size           = "sm" | "md" (default: md)
+// orientation    = "vertical" | "horizontal" (default: vertical)
+// options        = { value: string; label?: string; description?: string; disabled?: boolean }[]
+
+// Examples:
+<RadioGroup
+  value={plan}
+  onChange={setPlan}
+  options={[
+    { value: "free", label: "Free", description: "For hobby projects" },
+    { value: "pro",  label: "Pro",  description: "For teams" },
+  ]}
+/>
+<RadioGroup value={plan} onChange={setPlan} orientation="horizontal">
+  <Radio value="free" label="Free" />
+  <Radio value="pro"  label="Pro" />
+</RadioGroup>
+\`\`\`
+
+**Common mistakes:**
+- ❌ \`<Radio> used outside a <RadioGroup>\` → Always wrap <Radio> in <RadioGroup>
+- ❌ \`RadioGroup without value/onChange (React) or v-model (Vue)\` → Bind value + onChange (React) or v-model (Vue); or defaultValue for uncontrolled in React
+- ❌ \`Using Checkbox for mutually-exclusive choices\` → Use RadioGroup + Radio (or options) for one-of-many
+
+---
+
+### RichTextEditor
+
+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.
+
+\`\`\`tsx
+import { RichTextEditor } from "@usevyre/react"
+
+// Props:
+// value          = string
+// onChange       = function
+// placeholder    = string (default: Write something…)
+// disabled       = boolean (default: false)
+// readOnly       = boolean (default: false)
+// toolbar        = RichTextTool[]
+// minHeight      = string (default: 10rem)
+
+// Examples:
+const [html, setHtml] = useState("<p>Hello <strong>world</strong></p>");
+<RichTextEditor value={html} onChange={setHtml} placeholder="Write…" />
+<RichTextEditor
+  value={html}
+  onChange={setHtml}
+  toolbar={["bold", "italic", "link"]}
+/>
+\`\`\`
+
+**Common mistakes:**
+- ❌ \`RichTextEditor without value/onChange (React) or v-model (Vue)\` → Keep the HTML string in state and update it in onChange / v-model
+- ❌ \`Rendering value as text or with dangerouslySetInnerHTML elsewhere without sanitising\` → Sanitise (e.g. DOMPurify) before re-rendering untrusted RTE output
+- ❌ \`toolbar="bold" (string)\` → Pass an array, e.g. toolbar={["bold","italic","link"]}
+
+---
+
 ### Command
 
 Command palette / search dialog. Use for search-first navigation or quick actions.
@@ -3135,7 +3996,7 @@ import { DropdownMenu, DropdownItem, DropdownSeparator, DropdownCheckboxItem, Dr
 
 ### Field
 
-Form field wrapper providing label, hint text, and validation state for Input or Textarea.
+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.
 
 \`\`\`tsx
 import { Field, Input, Textarea } from "@usevyre/react"
@@ -3153,10 +4014,23 @@ import { Field, Input, Textarea } from "@usevyre/react"
 <Field label="Search">
   <Input leftElement={<SearchIcon />} placeholder="Search..." />
 </Field>
+<Field>
+  <FieldLabel required htmlFor="email">Email</FieldLabel>
+  <Input id="email" type="email" />
+  <FieldDescription>We\u2019ll never share it.</FieldDescription>
+  <FieldError>{errors.email}</FieldError>
+</Field>
+
+// Two controls side by side
+<FieldGroup orientation="horizontal">
+  <Field label="First name"><Input /></Field>
+  <Field label="Last name"><Input /></Field>
+</FieldGroup>
 \`\`\`
 
 **Common mistakes:**
 - ❌ \`Applying state prop directly to Input\` → Wrap Input in <Field state="error"> to apply validation styling
+- ❌ \`Mixing props label/hint AND FieldLabel/FieldError for the same field\` → Pick one: either props-based (label/hint/state) OR composable parts
 
 ---
 
@@ -3168,6 +4042,7 @@ Text input field. Wrap in Field for labels and validation. Use leftElement/right
 import { Input } from "@usevyre/react"
 
 // Props:
+// modelValue     = string | number
 // size           = "sm" | "md" | "lg" (default: md)
 // leftElement    = ReactNode
 // rightElement   = ReactNode
@@ -3179,6 +4054,7 @@ import { Input } from "@usevyre/react"
 **Common mistakes:**
 - ❌ \`size="icon"\` → Use size="sm" | "md" | "lg"
 - ❌ \`type="search" for search UI\` → Import Command from @usevyre/react for search palettes
+- ❌ \`Vue: binding Input/Textarea value without v-model\` → Use v-model on <Input>/<Textarea> in Vue; in React use value + onChange
 
 ---
 
@@ -3374,6 +4250,8 @@ import { AppLayout, Sidebar, SidebarHeader, SidebarContent, SidebarSection, Side
 
 // Props:
 // variant        = "default" | "floating" (default: default)
+// SidebarTrigger.icon = ReactNode
+// SidebarTrigger.collapsedIcon = ReactNode
 
 // Examples:
 <AppLayout>
@@ -3389,8 +4267,18 @@ import { AppLayout, Sidebar, SidebarHeader, SidebarContent, SidebarSection, Side
   </Sidebar>
   <main>Page content</main>
 </AppLayout>
+<SidebarTrigger icon={<PanelLeftClose />} collapsedIcon={<PanelLeftOpen />} />
+
+// Vue:
+// <SidebarTrigger>
+//   <template #icon><PanelLeftClose /></template>
+//   <template #collapsed-icon><PanelLeftOpen /></template>
+// </SidebarTrigger>
 \`\`\`
 
+**Common mistakes:**
+- ❌ \`Vue: passing icon/collapsedIcon as props on SidebarTrigger\` → Use <template #icon> and <template #collapsed-icon>; React uses icon / collapsedIcon props
+
 ---
 
 ### Skeleton
@@ -3766,6 +4654,180 @@ import { TagGroup, Tag } from "@usevyre/react"
 
 ---
 
+### Item
+
+Layout primitive for list rows, settings rows, and notification rows. Denser than Card — use Item (not Card) for repeated list rows.
+
+\`\`\`tsx
+import { Item, ItemMedia, ItemContent, ItemTitle, ItemDescription, ItemActions, ItemGroup } from "@usevyre/react"
+
+// Props:
+// variant        = "default" | "outlined" | "muted" | "plain" (default: default)
+// size           = "sm" | "md" | "lg" (default: md)
+// clickable      = boolean (default: false)
+
+// Examples:
+<Item>
+  <ItemMedia><BellIcon /></ItemMedia>
+  <ItemContent>
+    <ItemTitle>Notifications</ItemTitle>
+    <ItemDescription>Receive an email when someone mentions you.</ItemDescription>
+  </ItemContent>
+  <ItemActions>
+    <Switch defaultChecked />
+  </ItemActions>
+</Item>
+<ItemGroup separated>
+  <Item clickable>
+    <ItemContent><ItemTitle>Profile</ItemTitle></ItemContent>
+  </Item>
+  <Item clickable>
+    <ItemContent><ItemTitle>Billing</ItemTitle></ItemContent>
+  </Item>
+</ItemGroup>
+\`\`\`
+
+**Common mistakes:**
+- ❌ \`Card used for repeated list rows\` → Use <Item> (optionally inside <ItemGroup separated>) for list/settings rows
+- ❌ \`Item variant="primary"\` → Use variant="default" | "outlined" | "muted"
+- ❌ \`raw text directly inside Item\` → Wrap text in <ItemContent><ItemTitle>…</ItemTitle></ItemContent>
+
+---
+
+### Kanban
+
+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.
+
+\`\`\`tsx
+import { Kanban } from "@usevyre/react"
+
+// Props:
+// value          = KanbanColumn[]
+// onChange       = function
+// renderCard     = function
+// onCardClick    = function
+
+// Examples:
+const [columns, setColumns] = useState([
+  { id: "todo",  title: "To Do",       cards: [{ id: "1", title: "Spec API" }] },
+  { id: "doing", title: "In Progress", cards: [] },
+  { id: "done",  title: "Done",        cards: [{ id: "2", title: "Kickoff" }] },
+]);
+<Kanban value={columns} onChange={setColumns} />
+<Kanban
+  value={columns}
+  onChange={setColumns}
+  onCardClick={(card) => openDetail(card.id)}
+  renderCard={(card) => (
+    <><strong>{card.title}</strong><Badge>{card.id}</Badge></>
+  )}
+/>
+const [cols, setCols] = useState([
+  { id: "doing", title: "In Progress", color: "teal", cards: [
+    { id: "t1", title: "OAuth", assignee: "AK", progress: 60, color: "warning" },
+  ]},
+]);
+<Kanban
+  value={cols}
+  onChange={setCols}
+  renderCard={(card) => (
+    <><strong>{card.title}</strong><Progress value={card.progress} /></>
+  )}
+/>
+\`\`\`
+
+**Common mistakes:**
+- ❌ \`Kanban without onChange (or ignoring it)\` → Store columns in state and setColumns in onChange (v-model in Vue)
+- ❌ \`Duplicate card ids across columns\` → Use globally-unique card ids across the entire board
+- ❌ \`Mutating value in place then calling onChange\` → Pass the new array Kanban gives you straight to setState / v-model
+- ❌ \`color="blue" (or any non-semantic value)\` → Use one of: "default" | "accent" | "teal" | "success" | "warning" | "danger"
+
+---
+
+### Conversation
+
+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.
+
+\`\`\`tsx
+import { Conversation } from "@usevyre/react"
+
+// Props:
+// value          = ConversationMessage[]
+// currentUserId  = string
+// composer       = boolean (default: false)
+// onSend         = function
+// placeholder    = string (default: Write a message…)
+// typing         = boolean | string (default: false)
+// allowAttachments = boolean (default: false)
+// accept         = string
+// renderMessage  = function
+// renderComposer = function
+
+// Examples:
+const [messages, setMessages] = useState([
+  { id: "1", authorId: "sam", authorName: "Sam", text: "Hey!" },
+  { id: "2", authorId: "me", text: "Hi \ud83d\udc4b", status: "read" },
+]);
+<Conversation
+  value={messages}
+  currentUserId="me"
+  composer
+  onSend={(t) => setMessages((m) => [...m, { id: crypto.randomUUID(), authorId: "me", text: t }])}
+/>
+<Conversation
+  value={messages}
+  currentUserId="me"
+  typing="Sam is typing"
+  renderMessage={(m) => <strong>{m.text}</strong>}
+/>
+const messages = [
+  { id: "1", authorId: "sam", authorName: "Sam", text: "Moodboard \ud83d\udc47",
+    attachments: [{ kind: "image", url: "/board.png", name: "board.png" }] },
+  { id: "2", authorId: "me", text: "Specs:", status: "read",
+    attachments: [{ kind: "file", url: "/spec.pdf", name: "spec.pdf", size: "2.4 MB" }] },
+];
+<Conversation value={messages} currentUserId="me" />
+\`\`\`
+
+**Common mistakes:**
+- ❌ \`Conversation without currentUserId\` → Always pass currentUserId matching one of the message authorId values
+- ❌ \`Expecting Conversation to store/append messages\` → Append to your own state in onSend (or @send) and pass it back via value
+- ❌ \`composer without onSend (React) / @send (Vue)\` → Provide onSend / @send to append the message to value
+- ❌ \`Treating onSend as (text) only when using allowAttachments\` → Handle onSend(text, files) — map files to message attachments and append
+
+---
+
+### DateRangePicker
+
+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.
+
+\`\`\`tsx
+import { DateRangePicker } from "@usevyre/react"
+
+// Props:
+// value          = { from: Date | null; to: Date | null } | null
+// onChange       = function
+// placeholder    = string (default: Pick a date range)
+// numberOfMonths = "1" | "2" (default: 2)
+// presets        = boolean | DateRangePreset[] (default: false)
+// minDate        = Date
+// maxDate        = Date
+// disabled       = function
+// weekStartsOn   = "0" | "1" (default: 1)
+
+// Examples:
+const [range, setRange] = useState({ from: null, to: null });
+<DateRangePicker value={range} onChange={setRange} presets />
+<DateRangePicker value={range} onChange={setRange} numberOfMonths={1} />
+\`\`\`
+
+**Common mistakes:**
+- ❌ \`value={[from, to]}\` → Use value={{ from, to }} and read range.from / range.to
+- ❌ \`DateRangePicker for a single date\` → Use <DatePicker /> for a single date
+- ❌ \`presets="true" (string)\` → Use the bare prop: presets  (or presets={true})
+
+---
+
 ## Hallucination Guard — Common AI Mistakes
 
 The following prop values and patterns do NOT exist in useVyre.
@@ -3785,18 +4847,30 @@ If you generate these, you are hallucinating.
 - ❌ \`<Button color="...">\` → Use variant prop instead
 - ❌ \`<Button icon={...}>\` → Use leftIcon={...} or rightIcon={...}
 - ❌ \`<Button size="icon" without aria-label>\` → Add aria-label describing the action
-- ❌ \`<Calendar Using Calendar for time selection>\` → Combine with a separate time Input if time selection is needed
+- ❌ \`<Calendar Calendar for an input field that opens a popover>\` → Use <DatePicker /> (single date) or <DateRangePicker /> (range)
+- ❌ \`<Calendar value as tuple for mode="single">\` → Pass value matching mode; use mode="range" for [start,end]
+- ❌ \`<DatePicker DatePicker mode="range" for { from, to } object>\` → Use <DateRangePicker /> for the { from, to } object API + presets + dual month
+- ❌ \`<DatePicker DatePicker without value/onChange>\` → Provide value and onChange (e.g. from useState)
 - ❌ \`<Card variant="primary">\` → Use variant="elevated" | "outlined" | "ghost" | "accent"
 - ❌ \`<Checkbox size="lg">\` → Use size="md"
+- ❌ \`<RadioGroup <Radio> used outside a <RadioGroup>>\` → Always wrap <Radio> in <RadioGroup>
+- ❌ \`<RadioGroup RadioGroup without value/onChange (React) or v-model (Vue)>\` → Bind value + onChange (React) or v-model (Vue); or defaultValue for uncontrolled in React
+- ❌ \`<RadioGroup Using Checkbox for mutually-exclusive choices>\` → Use RadioGroup + Radio (or options) for one-of-many
+- ❌ \`<RichTextEditor RichTextEditor without value/onChange (React) or v-model (Vue)>\` → Keep the HTML string in state and update it in onChange / v-model
+- ❌ \`<RichTextEditor Rendering value as text or with dangerouslySetInnerHTML elsewhere without sanitising>\` → Sanitise (e.g. DOMPurify) before re-rendering untrusted RTE output
+- ❌ \`<RichTextEditor toolbar="bold" (string)>\` → Pass an array, e.g. toolbar={["bold","italic","link"]}
 - ❌ \`<Command Using Input type="search" for search UI>\` → Use Command + CommandInput + CommandList + CommandItem
 - ❌ \`<DropdownMenu DropdownItem variant="primary">\` → Use variant="danger" for destructive items only
 - ❌ \`<Field Applying state prop directly to Input>\` → Wrap Input in <Field state="error"> to apply validation styling
+- ❌ \`<Field Mixing props label/hint AND FieldLabel/FieldError for the same field>\` → Pick one: either props-based (label/hint/state) OR composable parts
 - ❌ \`<Input size="icon">\` → Use size="sm" | "md" | "lg"
 - ❌ \`<Input type="search" for search UI>\` → Import Command from @usevyre/react for search palettes
+- ❌ \`<Input Vue: binding Input/Textarea value without v-model>\` → Use v-model on <Input>/<Textarea> in Vue; in React use value + onChange
 - ❌ \`<Modal size="xl">\` → Use size="lg" or size="full"
 - ❌ \`<Popover placement="top-center">\` → Use placement="top" for centered placement
 - ❌ \`<Progress value > 100>\` → Normalize your value to 0–100 range before passing
 - ❌ \`<Select Passing strings directly as children>\` → Pass options={[{ value: 'a', label: 'Option A' }]}
+- ❌ \`<Sidebar Vue: passing icon/collapsedIcon as props on SidebarTrigger>\` → Use <template #icon> and <template #collapsed-icon>; React uses icon / collapsedIcon props
 - ❌ \`<Toast Rendering <Toast> directly in JSX>\` → Use: const { toast } = useToast(); then toast({ title, variant })
 - ❌ \`<Toast variant="error">\` → Use variant="danger"
 - ❌ \`<Toast variant="info">\` → Use variant="default"
@@ -3817,6 +4891,20 @@ If you generate these, you are hallucinating.
 - ❌ \`<Tag Tag size="xl">\` → Use size="lg"
 - ❌ \`<TagGroup TagGroup without Tag children>\` → Place <Tag> elements as direct children
 - ❌ \`<TagGroup Using TagGroup for tag input>\` → Use TagsInput for an editable tag field
+- ❌ \`<Item Card used for repeated list rows>\` → Use <Item> (optionally inside <ItemGroup separated>) for list/settings rows
+- ❌ \`<Item Item variant="primary">\` → Use variant="default" | "outlined" | "muted"
+- ❌ \`<Item raw text directly inside Item>\` → Wrap text in <ItemContent><ItemTitle>…</ItemTitle></ItemContent>
+- ❌ \`<Kanban Kanban without onChange (or ignoring it)>\` → Store columns in state and setColumns in onChange (v-model in Vue)
+- ❌ \`<Kanban Duplicate card ids across columns>\` → Use globally-unique card ids across the entire board
+- ❌ \`<Kanban Mutating value in place then calling onChange>\` → Pass the new array Kanban gives you straight to setState / v-model
+- ❌ \`<Kanban color="blue" (or any non-semantic value)>\` → Use one of: "default" | "accent" | "teal" | "success" | "warning" | "danger"
+- ❌ \`<Conversation Conversation without currentUserId>\` → Always pass currentUserId matching one of the message authorId values
+- ❌ \`<Conversation Expecting Conversation to store/append messages>\` → Append to your own state in onSend (or @send) and pass it back via value
+- ❌ \`<Conversation composer without onSend (React) / @send (Vue)>\` → Provide onSend / @send to append the message to value
+- ❌ \`<Conversation Treating onSend as (text) only when using allowAttachments>\` → Handle onSend(text, files) — map files to message attachments and append
+- ❌ \`<DateRangePicker value={[from, to]}>\` → Use value={{ from, to }} and read range.from / range.to
+- ❌ \`<DateRangePicker DateRangePicker for a single date>\` → Use <DatePicker /> for a single date
+- ❌ \`<DateRangePicker presets="true" (string)>\` → Use the bare prop: presets  (or presets={true})
 
 ---
 
@@ -3866,7 +4954,7 @@ If you generate these, you are hallucinating.
 \`\`\`
 `;
 export const copilotInstructions = `# useVyre Copilot Instructions
-# Version: 1.1.0
+# Version: 1.2.0
 
 When generating UI code in this project, follow the useVyre design system rules below.
 
@@ -4177,7 +5265,7 @@ import { Button } from "@usevyre/react"
 
 ### Calendar
 
-Date picker calendar widget for selecting single dates or ranges.
+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.
 
 \`\`\`tsx
 import { Calendar } from "@usevyre/react"
@@ -4186,6 +5274,7 @@ import { Calendar } from "@usevyre/react"
 // value          = Date | null
 // onChange       = function
 // disabled       = boolean (default: false)
+// defaultMonth   = Date
 
 // Examples:
 const [date, setDate] = useState(null);
@@ -4193,7 +5282,39 @@ const [date, setDate] = useState(null);
 \`\`\`
 
 **Common mistakes:**
-- ❌ \`Using Calendar for time selection\` → Combine with a separate time Input if time selection is needed
+- ❌ \`Calendar for an input field that opens a popover\` → Use <DatePicker /> (single date) or <DateRangePicker /> (range)
+- ❌ \`value as tuple for mode="single"\` → Pass value matching mode; use mode="range" for [start,end]
+
+---
+
+### DatePicker
+
+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.
+
+\`\`\`tsx
+import { DatePicker } from "@usevyre/react"
+
+// Props:
+// value          = Date | [Date, Date] | Date[] | null
+// onChange       = function
+// mode           = "single" | "range" | "multiple" (default: single)
+// placeholder    = string (default: Pick a date)
+// showTime       = boolean (default: false)
+// minDate        = Date
+// maxDate        = Date
+// disabled       = function
+// weekStartsOn   = "0" | "1" (default: 1)
+// inputClassName = string
+
+// Examples:
+const [date, setDate] = useState(null);
+<DatePicker value={date} onChange={setDate} placeholder="Pick a date" />
+<DatePicker value={date} onChange={setDate} showTime />
+\`\`\`
+
+**Common mistakes:**
+- ❌ \`DatePicker mode="range" for { from, to } object\` → Use <DateRangePicker /> for the { from, to } object API + presets + dual month
+- ❌ \`DatePicker without value/onChange\` → Provide value and onChange (e.g. from useState)
 
 ---
 
@@ -4253,40 +5374,112 @@ import { Checkbox } from "@usevyre/react"
 
 ---
 
-### Command
+### RadioGroup
 
-Command palette / search dialog. Use for search-first navigation or quick actions.
+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.
 
 \`\`\`tsx
-import { Command, CommandInput, CommandList, CommandEmpty, CommandGroup, CommandItem, CommandDialog } from "@usevyre/react"
+import { RadioGroup, Radio } from "@usevyre/react"
+
+// Props:
+// value          = string
+// defaultValue   = string
+// onChange       = function
+// name           = string
+// disabled       = boolean (default: false)
+// size           = "sm" | "md" (default: md)
+// orientation    = "vertical" | "horizontal" (default: vertical)
+// options        = { value: string; label?: string; description?: string; disabled?: boolean }[]
 
 // Examples:
-<Command>
-  <CommandInput placeholder="Search..." />
-  <CommandList>
-    <CommandEmpty>No results found.</CommandEmpty>
-    <CommandGroup heading="Suggestions">
-      <CommandItem onSelect={() => handleSelect('dashboard')}>Dashboard</CommandItem>
-      <CommandItem onSelect={() => handleSelect('settings')}>Settings</CommandItem>
-    </CommandGroup>
-  </CommandList>
-</Command>
+<RadioGroup
+  value={plan}
+  onChange={setPlan}
+  options={[
+    { value: "free", label: "Free", description: "For hobby projects" },
+    { value: "pro",  label: "Pro",  description: "For teams" },
+  ]}
+/>
+<RadioGroup value={plan} onChange={setPlan} orientation="horizontal">
+  <Radio value="free" label="Free" />
+  <Radio value="pro"  label="Pro" />
+</RadioGroup>
 \`\`\`
 
 **Common mistakes:**
-- ❌ \`Using Input type="search" for search UI\` → Use Command + CommandInput + CommandList + CommandItem
+- ❌ \`<Radio> used outside a <RadioGroup>\` → Always wrap <Radio> in <RadioGroup>
+- ❌ \`RadioGroup without value/onChange (React) or v-model (Vue)\` → Bind value + onChange (React) or v-model (Vue); or defaultValue for uncontrolled in React
+- ❌ \`Using Checkbox for mutually-exclusive choices\` → Use RadioGroup + Radio (or options) for one-of-many
 
 ---
 
-### DropdownMenu
+### RichTextEditor
 
-Contextual menu triggered by a button. Supports items, separators, checkbox items, radio groups, and sub-menus.
+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.
 
 \`\`\`tsx
-import { DropdownMenu, DropdownItem, DropdownSeparator, DropdownCheckboxItem, DropdownRadioGroup, DropdownRadioItem, DropdownSub } from "@usevyre/react"
+import { RichTextEditor } from "@usevyre/react"
 
 // Props:
-// trigger        = ReactElement
+// value          = string
+// onChange       = function
+// placeholder    = string (default: Write something…)
+// disabled       = boolean (default: false)
+// readOnly       = boolean (default: false)
+// toolbar        = RichTextTool[]
+// minHeight      = string (default: 10rem)
+
+// Examples:
+const [html, setHtml] = useState("<p>Hello <strong>world</strong></p>");
+<RichTextEditor value={html} onChange={setHtml} placeholder="Write…" />
+<RichTextEditor
+  value={html}
+  onChange={setHtml}
+  toolbar={["bold", "italic", "link"]}
+/>
+\`\`\`
+
+**Common mistakes:**
+- ❌ \`RichTextEditor without value/onChange (React) or v-model (Vue)\` → Keep the HTML string in state and update it in onChange / v-model
+- ❌ \`Rendering value as text or with dangerouslySetInnerHTML elsewhere without sanitising\` → Sanitise (e.g. DOMPurify) before re-rendering untrusted RTE output
+- ❌ \`toolbar="bold" (string)\` → Pass an array, e.g. toolbar={["bold","italic","link"]}
+
+---
+
+### Command
+
+Command palette / search dialog. Use for search-first navigation or quick actions.
+
+\`\`\`tsx
+import { Command, CommandInput, CommandList, CommandEmpty, CommandGroup, CommandItem, CommandDialog } from "@usevyre/react"
+
+// Examples:
+<Command>
+  <CommandInput placeholder="Search..." />
+  <CommandList>
+    <CommandEmpty>No results found.</CommandEmpty>
+    <CommandGroup heading="Suggestions">
+      <CommandItem onSelect={() => handleSelect('dashboard')}>Dashboard</CommandItem>
+      <CommandItem onSelect={() => handleSelect('settings')}>Settings</CommandItem>
+    </CommandGroup>
+  </CommandList>
+</Command>
+\`\`\`
+
+**Common mistakes:**
+- ❌ \`Using Input type="search" for search UI\` → Use Command + CommandInput + CommandList + CommandItem
+
+---
+
+### DropdownMenu
+
+Contextual menu triggered by a button. Supports items, separators, checkbox items, radio groups, and sub-menus.
+
+\`\`\`tsx
+import { DropdownMenu, DropdownItem, DropdownSeparator, DropdownCheckboxItem, DropdownRadioGroup, DropdownRadioItem, DropdownSub } from "@usevyre/react"
+
+// Props:
+// trigger        = ReactElement
 
 // Examples:
 <DropdownMenu trigger={<Button variant="secondary">Options</Button>}>
@@ -4304,7 +5497,7 @@ import { DropdownMenu, DropdownItem, DropdownSeparator, DropdownCheckboxItem, Dr
 
 ### Field
 
-Form field wrapper providing label, hint text, and validation state for Input or Textarea.
+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.
 
 \`\`\`tsx
 import { Field, Input, Textarea } from "@usevyre/react"
@@ -4322,10 +5515,23 @@ import { Field, Input, Textarea } from "@usevyre/react"
 <Field label="Search">
   <Input leftElement={<SearchIcon />} placeholder="Search..." />
 </Field>
+<Field>
+  <FieldLabel required htmlFor="email">Email</FieldLabel>
+  <Input id="email" type="email" />
+  <FieldDescription>We\u2019ll never share it.</FieldDescription>
+  <FieldError>{errors.email}</FieldError>
+</Field>
+
+// Two controls side by side
+<FieldGroup orientation="horizontal">
+  <Field label="First name"><Input /></Field>
+  <Field label="Last name"><Input /></Field>
+</FieldGroup>
 \`\`\`
 
 **Common mistakes:**
 - ❌ \`Applying state prop directly to Input\` → Wrap Input in <Field state="error"> to apply validation styling
+- ❌ \`Mixing props label/hint AND FieldLabel/FieldError for the same field\` → Pick one: either props-based (label/hint/state) OR composable parts
 
 ---
 
@@ -4337,6 +5543,7 @@ Text input field. Wrap in Field for labels and validation. Use leftElement/right
 import { Input } from "@usevyre/react"
 
 // Props:
+// modelValue     = string | number
 // size           = "sm" | "md" | "lg" (default: md)
 // leftElement    = ReactNode
 // rightElement   = ReactNode
@@ -4348,6 +5555,7 @@ import { Input } from "@usevyre/react"
 **Common mistakes:**
 - ❌ \`size="icon"\` → Use size="sm" | "md" | "lg"
 - ❌ \`type="search" for search UI\` → Import Command from @usevyre/react for search palettes
+- ❌ \`Vue: binding Input/Textarea value without v-model\` → Use v-model on <Input>/<Textarea> in Vue; in React use value + onChange
 
 ---
 
@@ -4543,6 +5751,8 @@ import { AppLayout, Sidebar, SidebarHeader, SidebarContent, SidebarSection, Side
 
 // Props:
 // variant        = "default" | "floating" (default: default)
+// SidebarTrigger.icon = ReactNode
+// SidebarTrigger.collapsedIcon = ReactNode
 
 // Examples:
 <AppLayout>
@@ -4558,8 +5768,18 @@ import { AppLayout, Sidebar, SidebarHeader, SidebarContent, SidebarSection, Side
   </Sidebar>
   <main>Page content</main>
 </AppLayout>
+<SidebarTrigger icon={<PanelLeftClose />} collapsedIcon={<PanelLeftOpen />} />
+
+// Vue:
+// <SidebarTrigger>
+//   <template #icon><PanelLeftClose /></template>
+//   <template #collapsed-icon><PanelLeftOpen /></template>
+// </SidebarTrigger>
 \`\`\`
 
+**Common mistakes:**
+- ❌ \`Vue: passing icon/collapsedIcon as props on SidebarTrigger\` → Use <template #icon> and <template #collapsed-icon>; React uses icon / collapsedIcon props
+
 ---
 
 ### Skeleton
@@ -4935,6 +6155,180 @@ import { TagGroup, Tag } from "@usevyre/react"
 
 ---
 
+### Item
+
+Layout primitive for list rows, settings rows, and notification rows. Denser than Card — use Item (not Card) for repeated list rows.
+
+\`\`\`tsx
+import { Item, ItemMedia, ItemContent, ItemTitle, ItemDescription, ItemActions, ItemGroup } from "@usevyre/react"
+
+// Props:
+// variant        = "default" | "outlined" | "muted" | "plain" (default: default)
+// size           = "sm" | "md" | "lg" (default: md)
+// clickable      = boolean (default: false)
+
+// Examples:
+<Item>
+  <ItemMedia><BellIcon /></ItemMedia>
+  <ItemContent>
+    <ItemTitle>Notifications</ItemTitle>
+    <ItemDescription>Receive an email when someone mentions you.</ItemDescription>
+  </ItemContent>
+  <ItemActions>
+    <Switch defaultChecked />
+  </ItemActions>
+</Item>
+<ItemGroup separated>
+  <Item clickable>
+    <ItemContent><ItemTitle>Profile</ItemTitle></ItemContent>
+  </Item>
+  <Item clickable>
+    <ItemContent><ItemTitle>Billing</ItemTitle></ItemContent>
+  </Item>
+</ItemGroup>
+\`\`\`
+
+**Common mistakes:**
+- ❌ \`Card used for repeated list rows\` → Use <Item> (optionally inside <ItemGroup separated>) for list/settings rows
+- ❌ \`Item variant="primary"\` → Use variant="default" | "outlined" | "muted"
+- ❌ \`raw text directly inside Item\` → Wrap text in <ItemContent><ItemTitle>…</ItemTitle></ItemContent>
+
+---
+
+### Kanban
+
+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.
+
+\`\`\`tsx
+import { Kanban } from "@usevyre/react"
+
+// Props:
+// value          = KanbanColumn[]
+// onChange       = function
+// renderCard     = function
+// onCardClick    = function
+
+// Examples:
+const [columns, setColumns] = useState([
+  { id: "todo",  title: "To Do",       cards: [{ id: "1", title: "Spec API" }] },
+  { id: "doing", title: "In Progress", cards: [] },
+  { id: "done",  title: "Done",        cards: [{ id: "2", title: "Kickoff" }] },
+]);
+<Kanban value={columns} onChange={setColumns} />
+<Kanban
+  value={columns}
+  onChange={setColumns}
+  onCardClick={(card) => openDetail(card.id)}
+  renderCard={(card) => (
+    <><strong>{card.title}</strong><Badge>{card.id}</Badge></>
+  )}
+/>
+const [cols, setCols] = useState([
+  { id: "doing", title: "In Progress", color: "teal", cards: [
+    { id: "t1", title: "OAuth", assignee: "AK", progress: 60, color: "warning" },
+  ]},
+]);
+<Kanban
+  value={cols}
+  onChange={setCols}
+  renderCard={(card) => (
+    <><strong>{card.title}</strong><Progress value={card.progress} /></>
+  )}
+/>
+\`\`\`
+
+**Common mistakes:**
+- ❌ \`Kanban without onChange (or ignoring it)\` → Store columns in state and setColumns in onChange (v-model in Vue)
+- ❌ \`Duplicate card ids across columns\` → Use globally-unique card ids across the entire board
+- ❌ \`Mutating value in place then calling onChange\` → Pass the new array Kanban gives you straight to setState / v-model
+- ❌ \`color="blue" (or any non-semantic value)\` → Use one of: "default" | "accent" | "teal" | "success" | "warning" | "danger"
+
+---
+
+### Conversation
+
+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.
+
+\`\`\`tsx
+import { Conversation } from "@usevyre/react"
+
+// Props:
+// value          = ConversationMessage[]
+// currentUserId  = string
+// composer       = boolean (default: false)
+// onSend         = function
+// placeholder    = string (default: Write a message…)
+// typing         = boolean | string (default: false)
+// allowAttachments = boolean (default: false)
+// accept         = string
+// renderMessage  = function
+// renderComposer = function
+
+// Examples:
+const [messages, setMessages] = useState([
+  { id: "1", authorId: "sam", authorName: "Sam", text: "Hey!" },
+  { id: "2", authorId: "me", text: "Hi \ud83d\udc4b", status: "read" },
+]);
+<Conversation
+  value={messages}
+  currentUserId="me"
+  composer
+  onSend={(t) => setMessages((m) => [...m, { id: crypto.randomUUID(), authorId: "me", text: t }])}
+/>
+<Conversation
+  value={messages}
+  currentUserId="me"
+  typing="Sam is typing"
+  renderMessage={(m) => <strong>{m.text}</strong>}
+/>
+const messages = [
+  { id: "1", authorId: "sam", authorName: "Sam", text: "Moodboard \ud83d\udc47",
+    attachments: [{ kind: "image", url: "/board.png", name: "board.png" }] },
+  { id: "2", authorId: "me", text: "Specs:", status: "read",
+    attachments: [{ kind: "file", url: "/spec.pdf", name: "spec.pdf", size: "2.4 MB" }] },
+];
+<Conversation value={messages} currentUserId="me" />
+\`\`\`
+
+**Common mistakes:**
+- ❌ \`Conversation without currentUserId\` → Always pass currentUserId matching one of the message authorId values
+- ❌ \`Expecting Conversation to store/append messages\` → Append to your own state in onSend (or @send) and pass it back via value
+- ❌ \`composer without onSend (React) / @send (Vue)\` → Provide onSend / @send to append the message to value
+- ❌ \`Treating onSend as (text) only when using allowAttachments\` → Handle onSend(text, files) — map files to message attachments and append
+
+---
+
+### DateRangePicker
+
+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.
+
+\`\`\`tsx
+import { DateRangePicker } from "@usevyre/react"
+
+// Props:
+// value          = { from: Date | null; to: Date | null } | null
+// onChange       = function
+// placeholder    = string (default: Pick a date range)
+// numberOfMonths = "1" | "2" (default: 2)
+// presets        = boolean | DateRangePreset[] (default: false)
+// minDate        = Date
+// maxDate        = Date
+// disabled       = function
+// weekStartsOn   = "0" | "1" (default: 1)
+
+// Examples:
+const [range, setRange] = useState({ from: null, to: null });
+<DateRangePicker value={range} onChange={setRange} presets />
+<DateRangePicker value={range} onChange={setRange} numberOfMonths={1} />
+\`\`\`
+
+**Common mistakes:**
+- ❌ \`value={[from, to]}\` → Use value={{ from, to }} and read range.from / range.to
+- ❌ \`DateRangePicker for a single date\` → Use <DatePicker /> for a single date
+- ❌ \`presets="true" (string)\` → Use the bare prop: presets  (or presets={true})
+
+---
+
 ## Hallucination Guard — Common AI Mistakes
 
 The following prop values and patterns do NOT exist in useVyre.
@@ -4954,18 +6348,30 @@ If you generate these, you are hallucinating.
 - ❌ \`<Button color="...">\` → Use variant prop instead
 - ❌ \`<Button icon={...}>\` → Use leftIcon={...} or rightIcon={...}
 - ❌ \`<Button size="icon" without aria-label>\` → Add aria-label describing the action
-- ❌ \`<Calendar Using Calendar for time selection>\` → Combine with a separate time Input if time selection is needed
+- ❌ \`<Calendar Calendar for an input field that opens a popover>\` → Use <DatePicker /> (single date) or <DateRangePicker /> (range)
+- ❌ \`<Calendar value as tuple for mode="single">\` → Pass value matching mode; use mode="range" for [start,end]
+- ❌ \`<DatePicker DatePicker mode="range" for { from, to } object>\` → Use <DateRangePicker /> for the { from, to } object API + presets + dual month
+- ❌ \`<DatePicker DatePicker without value/onChange>\` → Provide value and onChange (e.g. from useState)
 - ❌ \`<Card variant="primary">\` → Use variant="elevated" | "outlined" | "ghost" | "accent"
 - ❌ \`<Checkbox size="lg">\` → Use size="md"
+- ❌ \`<RadioGroup <Radio> used outside a <RadioGroup>>\` → Always wrap <Radio> in <RadioGroup>
+- ❌ \`<RadioGroup RadioGroup without value/onChange (React) or v-model (Vue)>\` → Bind value + onChange (React) or v-model (Vue); or defaultValue for uncontrolled in React
+- ❌ \`<RadioGroup Using Checkbox for mutually-exclusive choices>\` → Use RadioGroup + Radio (or options) for one-of-many
+- ❌ \`<RichTextEditor RichTextEditor without value/onChange (React) or v-model (Vue)>\` → Keep the HTML string in state and update it in onChange / v-model
+- ❌ \`<RichTextEditor Rendering value as text or with dangerouslySetInnerHTML elsewhere without sanitising>\` → Sanitise (e.g. DOMPurify) before re-rendering untrusted RTE output
+- ❌ \`<RichTextEditor toolbar="bold" (string)>\` → Pass an array, e.g. toolbar={["bold","italic","link"]}
 - ❌ \`<Command Using Input type="search" for search UI>\` → Use Command + CommandInput + CommandList + CommandItem
 - ❌ \`<DropdownMenu DropdownItem variant="primary">\` → Use variant="danger" for destructive items only
 - ❌ \`<Field Applying state prop directly to Input>\` → Wrap Input in <Field state="error"> to apply validation styling
+- ❌ \`<Field Mixing props label/hint AND FieldLabel/FieldError for the same field>\` → Pick one: either props-based (label/hint/state) OR composable parts
 - ❌ \`<Input size="icon">\` → Use size="sm" | "md" | "lg"
 - ❌ \`<Input type="search" for search UI>\` → Import Command from @usevyre/react for search palettes
+- ❌ \`<Input Vue: binding Input/Textarea value without v-model>\` → Use v-model on <Input>/<Textarea> in Vue; in React use value + onChange
 - ❌ \`<Modal size="xl">\` → Use size="lg" or size="full"
 - ❌ \`<Popover placement="top-center">\` → Use placement="top" for centered placement
 - ❌ \`<Progress value > 100>\` → Normalize your value to 0–100 range before passing
 - ❌ \`<Select Passing strings directly as children>\` → Pass options={[{ value: 'a', label: 'Option A' }]}
+- ❌ \`<Sidebar Vue: passing icon/collapsedIcon as props on SidebarTrigger>\` → Use <template #icon> and <template #collapsed-icon>; React uses icon / collapsedIcon props
 - ❌ \`<Toast Rendering <Toast> directly in JSX>\` → Use: const { toast } = useToast(); then toast({ title, variant })
 - ❌ \`<Toast variant="error">\` → Use variant="danger"
 - ❌ \`<Toast variant="info">\` → Use variant="default"
@@ -4986,6 +6392,20 @@ If you generate these, you are hallucinating.
 - ❌ \`<Tag Tag size="xl">\` → Use size="lg"
 - ❌ \`<TagGroup TagGroup without Tag children>\` → Place <Tag> elements as direct children
 - ❌ \`<TagGroup Using TagGroup for tag input>\` → Use TagsInput for an editable tag field
+- ❌ \`<Item Card used for repeated list rows>\` → Use <Item> (optionally inside <ItemGroup separated>) for list/settings rows
+- ❌ \`<Item Item variant="primary">\` → Use variant="default" | "outlined" | "muted"
+- ❌ \`<Item raw text directly inside Item>\` → Wrap text in <ItemContent><ItemTitle>…</ItemTitle></ItemContent>
+- ❌ \`<Kanban Kanban without onChange (or ignoring it)>\` → Store columns in state and setColumns in onChange (v-model in Vue)
+- ❌ \`<Kanban Duplicate card ids across columns>\` → Use globally-unique card ids across the entire board
+- ❌ \`<Kanban Mutating value in place then calling onChange>\` → Pass the new array Kanban gives you straight to setState / v-model
+- ❌ \`<Kanban color="blue" (or any non-semantic value)>\` → Use one of: "default" | "accent" | "teal" | "success" | "warning" | "danger"
+- ❌ \`<Conversation Conversation without currentUserId>\` → Always pass currentUserId matching one of the message authorId values
+- ❌ \`<Conversation Expecting Conversation to store/append messages>\` → Append to your own state in onSend (or @send) and pass it back via value
+- ❌ \`<Conversation composer without onSend (React) / @send (Vue)>\` → Provide onSend / @send to append the message to value
+- ❌ \`<Conversation Treating onSend as (text) only when using allowAttachments>\` → Handle onSend(text, files) — map files to message attachments and append
+- ❌ \`<DateRangePicker value={[from, to]}>\` → Use value={{ from, to }} and read range.from / range.to
+- ❌ \`<DateRangePicker DateRangePicker for a single date>\` → Use <DatePicker /> for a single date
+- ❌ \`<DateRangePicker presets="true" (string)>\` → Use the bare prop: presets  (or presets={true})
 
 ---
 
@@ -5037,8 +6457,8 @@ If you generate these, you are hallucinating.
 
 export const schema = {
   "$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": [
@@ -5046,6 +6466,11 @@ export const schema = {
     "@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,
@@ -5386,7 +6811,7 @@ export const schema = {
       ]
     },
     "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": {
@@ -5400,13 +6825,22 @@ export const schema = {
         "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": [
@@ -5416,6 +6850,87 @@ export const schema = {
         }
       ]
     },
+    "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\"",
@@ -5506,6 +7021,150 @@ export const schema = {
         }
       ]
     },
+    "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\"",
@@ -5575,7 +7234,7 @@ export const schema = {
       ]
     },
     "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": {
@@ -5608,6 +7267,11 @@ export const schema = {
           "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": [
@@ -5618,13 +7282,28 @@ export const schema = {
         {
           "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": [
@@ -5654,6 +7333,11 @@ export const schema = {
           "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": [
@@ -5984,7 +7668,8 @@ export const schema = {
         "SidebarContent",
         "SidebarSection",
         "SidebarItem",
-        "SidebarFooter"
+        "SidebarFooter",
+        "SidebarTrigger"
       ],
       "props": {
         "variant": {
@@ -5994,16 +7679,35 @@ export const schema = {
             "floating"
           ],
           "default": "default"
+        },
+        "SidebarTrigger.icon": {
+          "type": "ReactNode",
+          "description": "Icon shown when the sidebar is expanded. Optional — defaults to the built-in menu icon. Vue: #icon slot."
+        },
+        "SidebarTrigger.collapsedIcon": {
+          "type": "ReactNode",
+          "description": "Icon shown when the sidebar is collapsed. Optional — falls back to icon, then the built-in icon. Vue: #collapsed-icon slot. Use a different glyph here to signal collapsed state (common UX pattern)."
         }
       },
       "examples": [
         {
           "description": "App layout with sidebar",
           "code": "<AppLayout>\n  <Sidebar>\n    <SidebarHeader>Logo</SidebarHeader>\n    <SidebarContent>\n      <SidebarSection heading=\"Main\">\n        <SidebarItem href=\"/\" active>Dashboard</SidebarItem>\n        <SidebarItem href=\"/settings\">Settings</SidebarItem>\n      </SidebarSection>\n    </SidebarContent>\n    <SidebarFooter><Avatar fallback=\"JD\" size=\"sm\" /></SidebarFooter>\n  </Sidebar>\n  <main>Page content</main>\n</AppLayout>"
+        },
+        {
+          "description": "SidebarTrigger with distinct open/collapsed icons",
+          "code": "<SidebarTrigger icon={<PanelLeftClose />} collapsedIcon={<PanelLeftOpen />} />\n\n// Vue:\n// <SidebarTrigger>\n//   <template #icon><PanelLeftClose /></template>\n//   <template #collapsed-icon><PanelLeftOpen /></template>\n// </SidebarTrigger>"
         }
-      ]
-    },
-    "Skeleton": {
+      ],
+      "antiPatterns": [
+        {
+          "pattern": "Vue: passing icon/collapsedIcon as props on SidebarTrigger",
+          "reason": "Vue SidebarTrigger customises icons via slots, not props (consistent with SidebarItem)",
+          "fix": "Use <template #icon> and <template #collapsed-icon>; React uses icon / collapsedIcon props"
+        }
+      ]
+    },
+    "Skeleton": {
       "description": "Loading placeholder that mimics the shape of content while data loads.",
       "import": "import { Skeleton } from \"@usevyre/react\"",
       "props": {
@@ -6678,12 +8382,304 @@ export const schema = {
           "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} />"
+        }
+      ]
     }
   }
 };
 
 export const antiPatterns = {
-  "version": "1.1.0",
+  "version": "1.2.0",
   "rules": [
     {
       "component": "Accordion",
@@ -6785,9 +8781,30 @@ export const antiPatterns = {
     },
     {
       "component": "Calendar",
-      "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)",
+      "severity": "error"
+    },
+    {
+      "component": "Calendar",
+      "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]",
+      "severity": "error"
+    },
+    {
+      "component": "DatePicker",
+      "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",
+      "severity": "error"
+    },
+    {
+      "component": "DatePicker",
+      "pattern": "DatePicker without value/onChange",
+      "reason": "DatePicker is controlled — it has no internal selected state",
+      "fix": "Provide value and onChange (e.g. from useState)",
       "severity": "error"
     },
     {
@@ -6804,6 +8821,48 @@ export const antiPatterns = {
       "fix": "Use size=\"md\"",
       "severity": "error"
     },
+    {
+      "component": "RadioGroup",
+      "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>",
+      "severity": "error"
+    },
+    {
+      "component": "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",
+      "severity": "error"
+    },
+    {
+      "component": "RadioGroup",
+      "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",
+      "severity": "error"
+    },
+    {
+      "component": "RichTextEditor",
+      "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",
+      "severity": "error"
+    },
+    {
+      "component": "RichTextEditor",
+      "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",
+      "severity": "error"
+    },
+    {
+      "component": "RichTextEditor",
+      "pattern": "toolbar=\"bold\" (string)",
+      "reason": "toolbar is an array of tool ids",
+      "fix": "Pass an array, e.g. toolbar={[\"bold\",\"italic\",\"link\"]}",
+      "severity": "error"
+    },
     {
       "component": "Command",
       "pattern": "Using Input type=\"search\" for search UI",
@@ -6825,6 +8884,13 @@ export const antiPatterns = {
       "fix": "Wrap Input in <Field state=\"error\"> to apply validation styling",
       "severity": "error"
     },
+    {
+      "component": "Field",
+      "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",
+      "severity": "error"
+    },
     {
       "component": "Input",
       "pattern": "size=\"icon\"",
@@ -6839,6 +8905,13 @@ export const antiPatterns = {
       "fix": "Import Command from @usevyre/react for search palettes",
       "severity": "error"
     },
+    {
+      "component": "Input",
+      "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",
+      "severity": "error"
+    },
     {
       "component": "Modal",
       "pattern": "size=\"xl\"",
@@ -6867,6 +8940,13 @@ export const antiPatterns = {
       "fix": "Pass options={[{ value: 'a', label: 'Option A' }]}",
       "severity": "error"
     },
+    {
+      "component": "Sidebar",
+      "pattern": "Vue: passing icon/collapsedIcon as props on SidebarTrigger",
+      "reason": "Vue SidebarTrigger customises icons via slots, not props (consistent with SidebarItem)",
+      "fix": "Use <template #icon> and <template #collapsed-icon>; React uses icon / collapsedIcon props",
+      "severity": "error"
+    },
     {
       "component": "Toast",
       "pattern": "Rendering <Toast> directly in JSX",
@@ -7006,19 +9086,122 @@ export const antiPatterns = {
       "reason": "TagGroup is display-only",
       "fix": "Use TagsInput for an editable tag field",
       "severity": "error"
+    },
+    {
+      "component": "Item",
+      "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",
+      "severity": "error"
+    },
+    {
+      "component": "Item",
+      "pattern": "Item variant=\"primary\"",
+      "reason": "Item has no 'primary' variant",
+      "fix": "Use variant=\"default\" | \"outlined\" | \"muted\"",
+      "severity": "error"
+    },
+    {
+      "component": "Item",
+      "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>",
+      "severity": "error"
+    },
+    {
+      "component": "Kanban",
+      "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)",
+      "severity": "error"
+    },
+    {
+      "component": "Kanban",
+      "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",
+      "severity": "error"
+    },
+    {
+      "component": "Kanban",
+      "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",
+      "severity": "error"
+    },
+    {
+      "component": "Kanban",
+      "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\"",
+      "severity": "error"
+    },
+    {
+      "component": "Conversation",
+      "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",
+      "severity": "error"
+    },
+    {
+      "component": "Conversation",
+      "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",
+      "severity": "error"
+    },
+    {
+      "component": "Conversation",
+      "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",
+      "severity": "error"
+    },
+    {
+      "component": "Conversation",
+      "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",
+      "severity": "error"
+    },
+    {
+      "component": "DateRangePicker",
+      "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",
+      "severity": "error"
+    },
+    {
+      "component": "DateRangePicker",
+      "pattern": "DateRangePicker for a single date",
+      "reason": "DateRangePicker always selects a start AND end",
+      "fix": "Use <DatePicker /> for a single date",
+      "severity": "error"
+    },
+    {
+      "component": "DateRangePicker",
+      "pattern": "presets=\"true\" (string)",
+      "reason": "presets is a boolean or an array, not a string",
+      "fix": "Use the bare prop: presets  (or presets={true})",
+      "severity": "error"
     }
   ]
 };
 
 export const versionInfo = {
-  "version": "1.1.0",
+  "version": "1.2.0",
   "packageVersion": "1.1.0",
-  "generatedAt": "2026-05-15T15:01:34.101Z",
+  "generatedAt": "2026-05-17T13:24:18.828Z",
   "validFor": [
     "@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,
@@ -7043,252 +9226,301 @@ export const versionInfo = {
   "components": {
     "Accordion": {
       "version": "1.1.0",
-      "lastUpdated": "2026-05-15",
+      "lastUpdated": "2026-05-16",
       "breaking": false,
       "stable": true,
       "changelog": null
     },
     "Alert": {
       "version": "1.1.0",
-      "lastUpdated": "2026-05-15",
+      "lastUpdated": "2026-05-16",
       "breaking": false,
       "stable": true,
       "changelog": null
     },
     "Avatar": {
       "version": "1.1.0",
-      "lastUpdated": "2026-05-15",
+      "lastUpdated": "2026-05-16",
       "breaking": false,
       "stable": true,
       "changelog": null
     },
     "Badge": {
       "version": "1.1.0",
-      "lastUpdated": "2026-05-15",
+      "lastUpdated": "2026-05-16",
       "breaking": false,
       "stable": true,
       "changelog": null
     },
     "Breadcrumb": {
       "version": "1.1.0",
-      "lastUpdated": "2026-05-15",
+      "lastUpdated": "2026-05-16",
       "breaking": false,
       "stable": true,
       "changelog": null
     },
     "Button": {
       "version": "1.1.0",
-      "lastUpdated": "2026-05-15",
+      "lastUpdated": "2026-05-16",
       "breaking": false,
       "stable": true,
       "changelog": null
     },
     "Calendar": {
       "version": "1.1.0",
-      "lastUpdated": "2026-05-15",
+      "lastUpdated": "2026-05-16",
+      "breaking": false,
+      "stable": true,
+      "changelog": null
+    },
+    "DatePicker": {
+      "version": "1.1.0",
+      "lastUpdated": "2026-05-16",
       "breaking": false,
       "stable": true,
       "changelog": null
     },
     "Card": {
       "version": "1.1.0",
-      "lastUpdated": "2026-05-15",
+      "lastUpdated": "2026-05-16",
       "breaking": false,
       "stable": true,
       "changelog": null
     },
     "Checkbox": {
       "version": "1.1.0",
-      "lastUpdated": "2026-05-15",
+      "lastUpdated": "2026-05-16",
+      "breaking": false,
+      "stable": true,
+      "changelog": null
+    },
+    "RadioGroup": {
+      "version": "1.1.0",
+      "lastUpdated": "2026-05-16",
+      "breaking": false,
+      "stable": true,
+      "changelog": null
+    },
+    "RichTextEditor": {
+      "version": "1.1.0",
+      "lastUpdated": "2026-05-16",
       "breaking": false,
       "stable": true,
       "changelog": null
     },
     "Command": {
       "version": "1.1.0",
-      "lastUpdated": "2026-05-15",
+      "lastUpdated": "2026-05-16",
       "breaking": false,
       "stable": true,
       "changelog": null
     },
     "DropdownMenu": {
       "version": "1.1.0",
-      "lastUpdated": "2026-05-15",
+      "lastUpdated": "2026-05-16",
       "breaking": false,
       "stable": true,
       "changelog": null
     },
     "Field": {
       "version": "1.1.0",
-      "lastUpdated": "2026-05-15",
+      "lastUpdated": "2026-05-16",
       "breaking": false,
       "stable": true,
       "changelog": null
     },
     "Input": {
       "version": "1.1.0",
-      "lastUpdated": "2026-05-15",
+      "lastUpdated": "2026-05-16",
       "breaking": false,
       "stable": true,
       "changelog": null
     },
     "Label": {
       "version": "1.1.0",
-      "lastUpdated": "2026-05-15",
+      "lastUpdated": "2026-05-16",
       "breaking": false,
       "stable": true,
       "changelog": null
     },
     "Modal": {
       "version": "1.1.0",
-      "lastUpdated": "2026-05-15",
+      "lastUpdated": "2026-05-16",
       "breaking": false,
       "stable": true,
       "changelog": null
     },
     "Pagination": {
       "version": "1.1.0",
-      "lastUpdated": "2026-05-15",
+      "lastUpdated": "2026-05-16",
       "breaking": false,
       "stable": true,
       "changelog": null
     },
     "Popover": {
       "version": "1.1.0",
-      "lastUpdated": "2026-05-15",
+      "lastUpdated": "2026-05-16",
       "breaking": false,
       "stable": true,
       "changelog": null
     },
     "Progress": {
       "version": "1.1.0",
-      "lastUpdated": "2026-05-15",
+      "lastUpdated": "2026-05-16",
       "breaking": false,
       "stable": true,
       "changelog": null
     },
     "Select": {
       "version": "1.1.0",
-      "lastUpdated": "2026-05-15",
+      "lastUpdated": "2026-05-16",
       "breaking": false,
       "stable": true,
       "changelog": null
     },
     "Separator": {
       "version": "1.1.0",
-      "lastUpdated": "2026-05-15",
+      "lastUpdated": "2026-05-16",
       "breaking": false,
       "stable": true,
       "changelog": null
     },
     "Sheet": {
       "version": "1.1.0",
-      "lastUpdated": "2026-05-15",
+      "lastUpdated": "2026-05-16",
       "breaking": false,
       "stable": true,
       "changelog": null
     },
     "Sidebar": {
       "version": "1.1.0",
-      "lastUpdated": "2026-05-15",
+      "lastUpdated": "2026-05-16",
       "breaking": false,
       "stable": true,
       "changelog": null
     },
     "Skeleton": {
       "version": "1.1.0",
-      "lastUpdated": "2026-05-15",
+      "lastUpdated": "2026-05-16",
       "breaking": false,
       "stable": true,
       "changelog": null
     },
     "Slider": {
       "version": "1.1.0",
-      "lastUpdated": "2026-05-15",
+      "lastUpdated": "2026-05-16",
       "breaking": false,
       "stable": true,
       "changelog": null
     },
     "Switch": {
       "version": "1.1.0",
-      "lastUpdated": "2026-05-15",
+      "lastUpdated": "2026-05-16",
       "breaking": false,
       "stable": true,
       "changelog": null
     },
     "Table": {
       "version": "1.1.0",
-      "lastUpdated": "2026-05-15",
+      "lastUpdated": "2026-05-16",
       "breaking": false,
       "stable": true,
       "changelog": null
     },
     "Tabs": {
       "version": "1.1.0",
-      "lastUpdated": "2026-05-15",
+      "lastUpdated": "2026-05-16",
       "breaking": false,
       "stable": true,
       "changelog": null
     },
     "Toast": {
       "version": "1.1.0",
-      "lastUpdated": "2026-05-15",
+      "lastUpdated": "2026-05-16",
       "breaking": false,
       "stable": true,
       "changelog": null
     },
     "Tooltip": {
       "version": "1.1.0",
-      "lastUpdated": "2026-05-15",
+      "lastUpdated": "2026-05-16",
       "breaking": false,
       "stable": true,
       "changelog": null
     },
     "Typography": {
       "version": "1.1.0",
-      "lastUpdated": "2026-05-15",
+      "lastUpdated": "2026-05-16",
       "breaking": false,
       "stable": true,
       "changelog": null
     },
     "ButtonGroup": {
       "version": "1.1.0",
-      "lastUpdated": "2026-05-15",
+      "lastUpdated": "2026-05-16",
       "breaking": false,
       "stable": true,
       "changelog": null
     },
     "TagsInput": {
       "version": "1.1.0",
-      "lastUpdated": "2026-05-15",
+      "lastUpdated": "2026-05-16",
       "breaking": false,
       "stable": true,
       "changelog": null
     },
     "Combobox": {
       "version": "1.1.0",
-      "lastUpdated": "2026-05-15",
+      "lastUpdated": "2026-05-16",
       "breaking": false,
       "stable": true,
       "changelog": null
     },
     "DataGrid": {
       "version": "1.1.0",
-      "lastUpdated": "2026-05-15",
+      "lastUpdated": "2026-05-16",
       "breaking": false,
       "stable": true,
       "changelog": null
     },
     "Tag": {
       "version": "1.1.0",
-      "lastUpdated": "2026-05-15",
+      "lastUpdated": "2026-05-16",
       "breaking": false,
       "stable": true,
       "changelog": null
     },
     "TagGroup": {
       "version": "1.1.0",
-      "lastUpdated": "2026-05-15",
+      "lastUpdated": "2026-05-16",
+      "breaking": false,
+      "stable": true,
+      "changelog": null
+    },
+    "Item": {
+      "version": "1.1.0",
+      "lastUpdated": "2026-05-16",
+      "breaking": false,
+      "stable": true,
+      "changelog": null
+    },
+    "Kanban": {
+      "version": "1.1.0",
+      "lastUpdated": "2026-05-16",
+      "breaking": false,
+      "stable": true,
+      "changelog": null
+    },
+    "Conversation": {
+      "version": "1.1.0",
+      "lastUpdated": "2026-05-16",
+      "breaking": false,
+      "stable": true,
+      "changelog": null
+    },
+    "DateRangePicker": {
+      "version": "1.1.0",
+      "lastUpdated": "2026-05-16",
       "breaking": false,
       "stable": true,
       "changelog": null
@@ -7303,13 +9535,16 @@ export const cheatSheets = {
   "Badge": "# Badge — AI Cheat Sheet\n> Quick reference for Claude / Cursor / Copilot\n\n**Small label for status, category, or count. Use dot prop for live status indicator.**\n\n```ts\nimport { Badge } from \"@usevyre/react\"\n```\n\n## Valid Props\n\n| Prop | Values | Default |\n|------|--------|---------|\n| `variant` | `\"default\"` \\| `\"accent\"` \\| `\"teal\"` \\| `\"success\"` \\| `\"warning\"` \\| `\"danger\"` | `default` |\n| `dot` | `true` \\| `false` | `false` |\n\n## Common AI Mistakes\n\n- ❌ `variant=\"primary\"`\n  → Use variant=\"accent\" for brand color\n- ❌ `variant=\"error\"`\n  → Use variant=\"danger\"\n- ❌ `variant=\"info\"`\n  → Use variant=\"teal\" for info-like styling\n\n## Examples\n\n**Live status with dot**\n```tsx\n<Badge variant=\"success\" dot>Online</Badge>\n```\n\n**Warning badge**\n```tsx\n<Badge variant=\"warning\">Beta</Badge>\n```\n\n**Danger badge**\n```tsx\n<Badge variant=\"danger\">Error</Badge>\n```\n",
   "Breadcrumb": "# Breadcrumb — AI Cheat Sheet\n> Quick reference for Claude / Cursor / Copilot\n\n**Navigation trail showing current page location in hierarchy.**\n\n```ts\nimport { Breadcrumb, BreadcrumbItem, BreadcrumbLink, BreadcrumbSeparator } from \"@usevyre/react\"\n```\n\n## Common AI Mistakes\n\n- ❌ `Using plain <a> tags inside Breadcrumb`\n  → Use BreadcrumbItem > BreadcrumbLink for each crumb\n\n## Examples\n\n**Basic breadcrumb**\n```tsx\n<Breadcrumb>\n  <BreadcrumbItem><BreadcrumbLink href=\"/\">Home</BreadcrumbLink></BreadcrumbItem>\n  <BreadcrumbSeparator />\n  <BreadcrumbItem><BreadcrumbLink href=\"/docs\">Docs</BreadcrumbLink></BreadcrumbItem>\n  <BreadcrumbSeparator />\n  <BreadcrumbItem aria-current=\"page\">Button</BreadcrumbItem>\n</Breadcrumb>\n```\n",
   "Button": "# Button — AI Cheat Sheet\n> Quick reference for Claude / Cursor / Copilot\n\n**Triggers actions and navigation. The most commonly used interactive element.**\n\n```ts\nimport { Button } from \"@usevyre/react\"\n```\n\n## Valid Props\n\n| Prop | Values | Default |\n|------|--------|---------|\n| `variant` | `\"primary\"` \\| `\"secondary\"` \\| `\"ghost\"` \\| `\"accent\"` \\| `\"teal\"` \\| `\"danger\"` | `secondary` |\n| `size` | `\"sm\"` \\| `\"md\"` \\| `\"lg\"` \\| `\"icon\"` | `md` |\n| `loading` | `true` \\| `false` | `false` |\n| `disabled` | `true` \\| `false` | `false` |\n\n## Common AI Mistakes\n\n- ❌ `variant=\"blue\"`\n  → Use variant=\"accent\" for brand amber, or variant=\"teal\" for teal\n- ❌ `size=\"xl\"`\n  → Use size=\"lg\"\n- ❌ `color=\"...\"`\n  → Use variant prop instead\n- ❌ `icon={...}`\n  → Use leftIcon={...} or rightIcon={...}\n- ❌ `size=\"icon\" without aria-label`\n  → Add aria-label describing the action\n\n## Examples\n\n**Primary CTA**\n```tsx\n<Button variant=\"primary\">Get Started</Button>\n```\n\n**Large accent button**\n```tsx\n<Button variant=\"accent\" size=\"lg\">Launch App</Button>\n```\n\n**Loading state**\n```tsx\n<Button variant=\"danger\" loading>Deleting...</Button>\n```\n\n**Link button**\n```tsx\n<Button as=\"a\" href=\"/docs\" variant=\"secondary\">Read Docs</Button>\n```\n\n**Icon-only button**\n```tsx\n<Button variant=\"ghost\" size=\"icon\" aria-label=\"Close\">\n  <X size={16} />\n</Button>\n```\n\n## Accessibility\n\n- Always add aria-label when using size='icon' (no visible text)\n",
-  "Calendar": "# Calendar — AI Cheat Sheet\n> Quick reference for Claude / Cursor / Copilot\n\n**Date picker calendar widget for selecting single dates or ranges.**\n\n```ts\nimport { Calendar } from \"@usevyre/react\"\n```\n\n## Valid Props\n\n| Prop | Values | Default |\n|------|--------|---------|\n| `disabled` | `true` \\| `false` | `false` |\n\n## Common AI Mistakes\n\n- ❌ `Using Calendar for time selection`\n  → Combine with a separate time Input if time selection is needed\n\n## Examples\n\n**Controlled date picker**\n```tsx\nconst [date, setDate] = useState(null);\n<Calendar value={date} onChange={setDate} />\n```\n",
+  "Calendar": "# Calendar — AI Cheat Sheet\n> Quick reference for Claude / Cursor / Copilot\n\n**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.**\n\n```ts\nimport { Calendar } from \"@usevyre/react\"\n```\n\n## Valid Props\n\n| Prop | Values | Default |\n|------|--------|---------|\n| `disabled` | `true` \\| `false` | `false` |\n\n## Common AI Mistakes\n\n- ❌ `Calendar for an input field that opens a popover`\n  → Use <DatePicker /> (single date) or <DateRangePicker /> (range)\n- ❌ `value as tuple for mode=\"single\"`\n  → Pass value matching mode; use mode=\"range\" for [start,end]\n\n## Examples\n\n**Controlled date picker**\n```tsx\nconst [date, setDate] = useState(null);\n<Calendar value={date} onChange={setDate} />\n```\n",
+  "DatePicker": "# DatePicker — AI Cheat Sheet\n> Quick reference for Claude / Cursor / Copilot\n\n**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.**\n\n```ts\nimport { DatePicker } from \"@usevyre/react\"\n```\n\n## Valid Props\n\n| Prop | Values | Default |\n|------|--------|---------|\n| `mode` | `\"single\"` \\| `\"range\"` \\| `\"multiple\"` | `single` |\n| `weekStartsOn` | `\"0\"` \\| `\"1\"` | `1` |\n| `showTime` | `true` \\| `false` | `false` |\n\n## Common AI Mistakes\n\n- ❌ `DatePicker mode=\"range\" for { from, to } object`\n  → Use <DateRangePicker /> for the { from, to } object API + presets + dual month\n- ❌ `DatePicker without value/onChange`\n  → Provide value and onChange (e.g. from useState)\n\n## Examples\n\n**Single date field**\n```tsx\nconst [date, setDate] = useState(null);\n<DatePicker value={date} onChange={setDate} placeholder=\"Pick a date\" />\n```\n\n**Date + time**\n```tsx\n<DatePicker value={date} onChange={setDate} showTime />\n```\n",
   "Card": "# Card — AI Cheat Sheet\n> Quick reference for Claude / Cursor / Copilot\n\n**Content container with optional header, body, and footer sections.**\n\n```ts\nimport { Card, CardHeader, CardBody, CardFooter } from \"@usevyre/react\"\n```\n\n## Valid Props\n\n| Prop | Values | Default |\n|------|--------|---------|\n| `variant` | `\"default\"` \\| `\"elevated\"` \\| `\"outlined\"` \\| `\"ghost\"` \\| `\"accent\"` | `default` |\n| `hoverable` | `true` \\| `false` | `false` |\n| `clickable` | `true` \\| `false` | `false` |\n\n## Common AI Mistakes\n\n- ❌ `variant=\"primary\"`\n  → Use variant=\"elevated\" | \"outlined\" | \"ghost\" | \"accent\"\n\n## Examples\n\n**Elevated card with sections**\n```tsx\n<Card variant=\"elevated\">\n  <CardHeader><Badge variant=\"teal\">New</Badge></CardHeader>\n  <CardBody>\n    <h3>Card Title</h3>\n    <p>Description text.</p>\n  </CardBody>\n  <CardFooter>\n    <Button variant=\"ghost\" size=\"sm\">Learn more</Button>\n  </CardFooter>\n</Card>\n```\n",
   "Checkbox": "# Checkbox — AI Cheat Sheet\n> Quick reference for Claude / Cursor / Copilot\n\n**Binary toggle for boolean form values.**\n\n```ts\nimport { Checkbox } from \"@usevyre/react\"\n```\n\n## Valid Props\n\n| Prop | Values | Default |\n|------|--------|---------|\n| `size` | `\"sm\"` \\| `\"md\"` | `md` |\n| `checked` | `true` \\| `false` | — |\n| `disabled` | `true` \\| `false` | `false` |\n| `indeterminate` | `true` \\| `false` | `false` |\n\n## Common AI Mistakes\n\n- ❌ `size=\"lg\"`\n  → Use size=\"md\"\n\n## Examples\n\n**Labeled checkbox**\n```tsx\n<label style={{ display: 'flex', alignItems: 'center', gap: 'var(--vyre-spacing-2)' }}>\n  <Checkbox checked={agreed} onChange={e => setAgreed(e.target.checked)} />\n  I agree to the terms\n</label>\n```\n",
+  "RadioGroup": "# RadioGroup — AI Cheat Sheet\n> Quick reference for Claude / Cursor / Copilot\n\n**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.**\n\n```ts\nimport { RadioGroup, Radio } from \"@usevyre/react\"\n```\n\n## Valid Props\n\n| Prop | Values | Default |\n|------|--------|---------|\n| `size` | `\"sm\"` \\| `\"md\"` | `md` |\n| `orientation` | `\"vertical\"` \\| `\"horizontal\"` | `vertical` |\n| `disabled` | `true` \\| `false` | `false` |\n\n## Common AI Mistakes\n\n- ❌ `<Radio> used outside a <RadioGroup>`\n  → Always wrap <Radio> in <RadioGroup>\n- ❌ `RadioGroup without value/onChange (React) or v-model (Vue)`\n  → Bind value + onChange (React) or v-model (Vue); or defaultValue for uncontrolled in React\n- ❌ `Using Checkbox for mutually-exclusive choices`\n  → Use RadioGroup + Radio (or options) for one-of-many\n\n## Examples\n\n**Data-driven**\n```tsx\n<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/>\n```\n\n**Composable children**\n```tsx\n<RadioGroup value={plan} onChange={setPlan} orientation=\"horizontal\">\n  <Radio value=\"free\" label=\"Free\" />\n  <Radio value=\"pro\"  label=\"Pro\" />\n</RadioGroup>\n```\n",
+  "RichTextEditor": "# RichTextEditor — AI Cheat Sheet\n> Quick reference for Claude / Cursor / Copilot\n\n**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.**\n\n```ts\nimport { RichTextEditor } from \"@usevyre/react\"\n```\n\n## Valid Props\n\n| Prop | Values | Default |\n|------|--------|---------|\n| `disabled` | `true` \\| `false` | `false` |\n| `readOnly` | `true` \\| `false` | `false` |\n\n## Common AI Mistakes\n\n- ❌ `RichTextEditor without value/onChange (React) or v-model (Vue)`\n  → Keep the HTML string in state and update it in onChange / v-model\n- ❌ `Rendering value as text or with dangerouslySetInnerHTML elsewhere without sanitising`\n  → Sanitise (e.g. DOMPurify) before re-rendering untrusted RTE output\n- ❌ `toolbar=\"bold\" (string)`\n  → Pass an array, e.g. toolbar={[\"bold\",\"italic\",\"link\"]}\n\n## Examples\n\n**Controlled editor**\n```tsx\nconst [html, setHtml] = useState(\"<p>Hello <strong>world</strong></p>\");\n<RichTextEditor value={html} onChange={setHtml} placeholder=\"Write…\" />\n```\n\n**Minimal toolbar**\n```tsx\n<RichTextEditor\n  value={html}\n  onChange={setHtml}\n  toolbar={[\"bold\", \"italic\", \"link\"]}\n/>\n```\n",
   "Command": "# Command — AI Cheat Sheet\n> Quick reference for Claude / Cursor / Copilot\n\n**Command palette / search dialog. Use for search-first navigation or quick actions.**\n\n```ts\nimport { Command, CommandInput, CommandList, CommandEmpty, CommandGroup, CommandItem, CommandDialog } from \"@usevyre/react\"\n```\n\n## Common AI Mistakes\n\n- ❌ `Using Input type=\"search\" for search UI`\n  → Use Command + CommandInput + CommandList + CommandItem\n\n## Examples\n\n**Basic command palette**\n```tsx\n<Command>\n  <CommandInput placeholder=\"Search...\" />\n  <CommandList>\n    <CommandEmpty>No results found.</CommandEmpty>\n    <CommandGroup heading=\"Suggestions\">\n      <CommandItem onSelect={() => handleSelect('dashboard')}>Dashboard</CommandItem>\n      <CommandItem onSelect={() => handleSelect('settings')}>Settings</CommandItem>\n    </CommandGroup>\n  </CommandList>\n</Command>\n```\n",
   "DropdownMenu": "# DropdownMenu — AI Cheat Sheet\n> Quick reference for Claude / Cursor / Copilot\n\n**Contextual menu triggered by a button. Supports items, separators, checkbox items, radio groups, and sub-menus.**\n\n```ts\nimport { DropdownMenu, DropdownItem, DropdownSeparator, DropdownCheckboxItem, DropdownRadioGroup, DropdownRadioItem, DropdownSub } from \"@usevyre/react\"\n```\n\n## Common AI Mistakes\n\n- ❌ `DropdownItem variant=\"primary\"`\n  → Use variant=\"danger\" for destructive items only\n\n## Examples\n\n**Dropdown with danger item**\n```tsx\n<DropdownMenu trigger={<Button variant=\"secondary\">Options</Button>}>\n  <DropdownItem onSelect={() => handleEdit()}>Edit</DropdownItem>\n  <DropdownItem onSelect={() => handleDuplicate()}>Duplicate</DropdownItem>\n  <DropdownSeparator />\n  <DropdownItem variant=\"danger\" onSelect={() => handleDelete()}>Delete</DropdownItem>\n</DropdownMenu>\n```\n",
-  "Field": "# Field — AI Cheat Sheet\n> Quick reference for Claude / Cursor / Copilot\n\n**Form field wrapper providing label, hint text, and validation state for Input or Textarea.**\n\n```ts\nimport { Field, Input, Textarea } from \"@usevyre/react\"\n```\n\n## Valid Props\n\n| Prop | Values | Default |\n|------|--------|---------|\n| `state` | `\"idle\"` \\| `\"error\"` \\| `\"success\"` \\| `\"warning\"` | `idle` |\n| `required` | `true` \\| `false` | `false` |\n\n## Common AI Mistakes\n\n- ❌ `Applying state prop directly to Input`\n  → Wrap Input in <Field state=\"error\"> to apply validation styling\n\n## Examples\n\n**Error state field**\n```tsx\n<Field label=\"Email\" state=\"error\" hint=\"Invalid email format\">\n  <Input type=\"email\" placeholder=\"you@example.com\" />\n</Field>\n```\n\n**Search field with left icon**\n```tsx\n<Field label=\"Search\">\n  <Input leftElement={<SearchIcon />} placeholder=\"Search...\" />\n</Field>\n```\n",
-  "Input": "# Input — AI Cheat Sheet\n> Quick reference for Claude / Cursor / Copilot\n\n**Text input field. Wrap in Field for labels and validation. Use leftElement/rightElement for icons.**\n\n```ts\nimport { Input } from \"@usevyre/react\"\n```\n\n## Valid Props\n\n| Prop | Values | Default |\n|------|--------|---------|\n| `size` | `\"sm\"` \\| `\"md\"` \\| `\"lg\"` | `md` |\n\n## Common AI Mistakes\n\n- ❌ `size=\"icon\"`\n  → Use size=\"sm\" | \"md\" | \"lg\"\n- ❌ `type=\"search\" for search UI`\n  → Import Command from @usevyre/react for search palettes\n\n## Examples\n\n**Password input with icon**\n```tsx\n<Input type=\"password\" rightElement={<EyeIcon />} placeholder=\"Password\" />\n```\n",
+  "Field": "# Field — AI Cheat Sheet\n> Quick reference for Claude / Cursor / Copilot\n\n**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.**\n\n```ts\nimport { Field, Input, Textarea } from \"@usevyre/react\"\n```\n\n## Valid Props\n\n| Prop | Values | Default |\n|------|--------|---------|\n| `state` | `\"idle\"` \\| `\"error\"` \\| `\"success\"` \\| `\"warning\"` | `idle` |\n| `required` | `true` \\| `false` | `false` |\n\n## Common AI Mistakes\n\n- ❌ `Applying state prop directly to Input`\n  → Wrap Input in <Field state=\"error\"> to apply validation styling\n- ❌ `Mixing props label/hint AND FieldLabel/FieldError for the same field`\n  → Pick one: either props-based (label/hint/state) OR composable parts\n\n## Examples\n\n**Error state field**\n```tsx\n<Field label=\"Email\" state=\"error\" hint=\"Invalid email format\">\n  <Input type=\"email\" placeholder=\"you@example.com\" />\n</Field>\n```\n\n**Search field with left icon**\n```tsx\n<Field label=\"Search\">\n  <Input leftElement={<SearchIcon />} placeholder=\"Search...\" />\n</Field>\n```\n\n**Composable field with explicit parts**\n```tsx\n<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>\n```\n",
+  "Input": "# Input — AI Cheat Sheet\n> Quick reference for Claude / Cursor / Copilot\n\n**Text input field. Wrap in Field for labels and validation. Use leftElement/rightElement for icons.**\n\n```ts\nimport { Input } from \"@usevyre/react\"\n```\n\n## Valid Props\n\n| Prop | Values | Default |\n|------|--------|---------|\n| `size` | `\"sm\"` \\| `\"md\"` \\| `\"lg\"` | `md` |\n\n## Common AI Mistakes\n\n- ❌ `size=\"icon\"`\n  → Use size=\"sm\" | \"md\" | \"lg\"\n- ❌ `type=\"search\" for search UI`\n  → Import Command from @usevyre/react for search palettes\n- ❌ `Vue: binding Input/Textarea value without v-model`\n  → Use v-model on <Input>/<Textarea> in Vue; in React use value + onChange\n\n## Examples\n\n**Password input with icon**\n```tsx\n<Input type=\"password\" rightElement={<EyeIcon />} placeholder=\"Password\" />\n```\n",
   "Label": "# Label — AI Cheat Sheet\n> Quick reference for Claude / Cursor / Copilot\n\n**Accessible form label. Associate with input via htmlFor.**\n\n```ts\nimport { Label } from \"@usevyre/react\"\n```\n\n## Valid Props\n\n| Prop | Values | Default |\n|------|--------|---------|\n| `required` | `true` \\| `false` | `false` |\n\n## Examples\n\n**Label with input**\n```tsx\n<Label htmlFor=\"email\">Email address</Label>\n<Input id=\"email\" type=\"email\" />\n```\n",
   "Modal": "# Modal — AI Cheat Sheet\n> Quick reference for Claude / Cursor / Copilot\n\n**Dialog overlay for confirmations, forms, or focused content.**\n\n```ts\nimport { Modal, ModalHeader, ModalBody, ModalFooter } from \"@usevyre/react\"\n```\n\n## Valid Props\n\n| Prop | Values | Default |\n|------|--------|---------|\n| `size` | `\"sm\"` \\| `\"md\"` \\| `\"lg\"` \\| `\"full\"` | `md` |\n| `open` | `true` \\| `false` | — |\n\n## Common AI Mistakes\n\n- ❌ `size=\"xl\"`\n  → Use size=\"lg\" or size=\"full\"\n\n## Examples\n\n**Confirmation modal**\n```tsx\n<Modal open={isOpen} onClose={() => setIsOpen(false)} title=\"Confirm Delete\" size=\"sm\">\n  <ModalBody>Are you sure you want to delete this item?</ModalBody>\n  <ModalFooter>\n    <Button variant=\"ghost\" onClick={() => setIsOpen(false)}>Cancel</Button>\n    <Button variant=\"danger\" onClick={handleDelete}>Delete</Button>\n  </ModalFooter>\n</Modal>\n```\n",
   "Pagination": "# Pagination — AI Cheat Sheet\n> Quick reference for Claude / Cursor / Copilot\n\n**Page navigation for paginated lists or tables.**\n\n```ts\nimport { Pagination } from \"@usevyre/react\"\n```\n\n## Examples\n\n**Basic pagination**\n```tsx\n<Pagination page={currentPage} total={totalPages} onChange={setCurrentPage} />\n```\n",
@@ -7318,7 +9553,7 @@ export const cheatSheets = {
   "Select": "# Select — AI Cheat Sheet\n> Quick reference for Claude / Cursor / Copilot\n\n**Dropdown for selecting one option from a list.**\n\n```ts\nimport { Select } from \"@usevyre/react\"\n```\n\n## Valid Props\n\n| Prop | Values | Default |\n|------|--------|---------|\n| `size` | `\"sm\"` \\| `\"md\"` \\| `\"lg\"` | `md` |\n| `disabled` | `true` \\| `false` | `false` |\n\n## Common AI Mistakes\n\n- ❌ `Passing strings directly as children`\n  → Pass options={[{ value: 'a', label: 'Option A' }]}\n\n## Examples\n\n**Controlled select**\n```tsx\n<Select\n  options={[{ value: 'react', label: 'React' }, { value: 'vue', label: 'Vue' }]}\n  value={framework}\n  onChange={setFramework}\n  placeholder=\"Choose framework\"\n/>\n```\n",
   "Separator": "# Separator — AI Cheat Sheet\n> Quick reference for Claude / Cursor / Copilot\n\n**Horizontal or vertical divider line.**\n\n```ts\nimport { Separator } from \"@usevyre/react\"\n```\n\n## Valid Props\n\n| Prop | Values | Default |\n|------|--------|---------|\n| `orientation` | `\"horizontal\"` \\| `\"vertical\"` | `horizontal` |\n\n## Examples\n\n**Horizontal separator**\n```tsx\n<Separator />\n```\n\n**Vertical separator**\n```tsx\n<Separator orientation=\"vertical\" />\n```\n",
   "Sheet": "# Sheet — AI Cheat Sheet\n> Quick reference for Claude / Cursor / Copilot\n\n**Side panel (drawer) that slides in from the edge. For forms, detail views, or settings.**\n\n```ts\nimport { Sheet, SheetHeader, SheetBody, SheetFooter } from \"@usevyre/react\"\n```\n\n## Valid Props\n\n| Prop | Values | Default |\n|------|--------|---------|\n| `size` | `\"sm\"` \\| `\"md\"` \\| `\"lg\"` \\| `\"full\"` | `md` |\n| `side` | `\"left\"` \\| `\"right\"` | `right` |\n| `open` | `true` \\| `false` | — |\n\n## Examples\n\n**Settings sheet from the right**\n```tsx\n<Sheet open={isOpen} onClose={() => setIsOpen(false)} title=\"Settings\" side=\"right\">\n  <SheetBody>Settings content here.</SheetBody>\n  <SheetFooter>\n    <Button variant=\"accent\">Save</Button>\n  </SheetFooter>\n</Sheet>\n```\n",
-  "Sidebar": "# Sidebar — AI Cheat Sheet\n> Quick reference for Claude / Cursor / Copilot\n\n**App navigation sidebar. Use AppLayout as the root layout wrapper.**\n\n```ts\nimport { AppLayout, Sidebar, SidebarHeader, SidebarContent, SidebarSection, SidebarItem, SidebarFooter } from \"@usevyre/react\"\n```\n\n## Valid Props\n\n| Prop | Values | Default |\n|------|--------|---------|\n| `variant` | `\"default\"` \\| `\"floating\"` | `default` |\n\n## Examples\n\n**App layout with sidebar**\n```tsx\n<AppLayout>\n  <Sidebar>\n    <SidebarHeader>Logo</SidebarHeader>\n    <SidebarContent>\n      <SidebarSection heading=\"Main\">\n        <SidebarItem href=\"/\" active>Dashboard</SidebarItem>\n        <SidebarItem href=\"/settings\">Settings</SidebarItem>\n      </SidebarSection>\n    </SidebarContent>\n    <SidebarFooter><Avatar fallback=\"JD\" size=\"sm\" /></SidebarFooter>\n  </Sidebar>\n  <main>Page content</main>\n</AppLayout>\n```\n",
+  "Sidebar": "# Sidebar — AI Cheat Sheet\n> Quick reference for Claude / Cursor / Copilot\n\n**App navigation sidebar. Use AppLayout as the root layout wrapper.**\n\n```ts\nimport { AppLayout, Sidebar, SidebarHeader, SidebarContent, SidebarSection, SidebarItem, SidebarFooter } from \"@usevyre/react\"\n```\n\n## Valid Props\n\n| Prop | Values | Default |\n|------|--------|---------|\n| `variant` | `\"default\"` \\| `\"floating\"` | `default` |\n\n## Common AI Mistakes\n\n- ❌ `Vue: passing icon/collapsedIcon as props on SidebarTrigger`\n  → Use <template #icon> and <template #collapsed-icon>; React uses icon / collapsedIcon props\n\n## Examples\n\n**App layout with sidebar**\n```tsx\n<AppLayout>\n  <Sidebar>\n    <SidebarHeader>Logo</SidebarHeader>\n    <SidebarContent>\n      <SidebarSection heading=\"Main\">\n        <SidebarItem href=\"/\" active>Dashboard</SidebarItem>\n        <SidebarItem href=\"/settings\">Settings</SidebarItem>\n      </SidebarSection>\n    </SidebarContent>\n    <SidebarFooter><Avatar fallback=\"JD\" size=\"sm\" /></SidebarFooter>\n  </Sidebar>\n  <main>Page content</main>\n</AppLayout>\n```\n\n**SidebarTrigger with distinct open/collapsed icons**\n```tsx\n<SidebarTrigger icon={<PanelLeftClose />} collapsedIcon={<PanelLeftOpen />} />\n\n// Vue:\n// <SidebarTrigger>\n//   <template #icon><PanelLeftClose /></template>\n//   <template #collapsed-icon><PanelLeftOpen /></template>\n// </SidebarTrigger>\n```\n",
   "Skeleton": "# Skeleton — AI Cheat Sheet\n> Quick reference for Claude / Cursor / Copilot\n\n**Loading placeholder that mimics the shape of content while data loads.**\n\n```ts\nimport { Skeleton } from \"@usevyre/react\"\n```\n\n## Valid Props\n\n| Prop | Values | Default |\n|------|--------|---------|\n| `variant` | `\"rect\"` \\| `\"circle\"` \\| `\"text\"` | `rect` |\n\n## Examples\n\n**Avatar skeleton**\n```tsx\n<Skeleton variant=\"circle\" width={40} height={40} />\n```\n\n**Text line skeletons**\n```tsx\n<Skeleton variant=\"text\" width=\"100%\" />\n<Skeleton variant=\"text\" width=\"60%\" />\n```\n",
   "Slider": "# Slider — AI Cheat Sheet\n> Quick reference for Claude / Cursor / Copilot\n\n**Range input for selecting a numeric value within a range.**\n\n```ts\nimport { Slider } from \"@usevyre/react\"\n```\n\n## Valid Props\n\n| Prop | Values | Default |\n|------|--------|---------|\n| `size` | `\"sm\"` \\| `\"md\"` | `md` |\n| `disabled` | `true` \\| `false` | `false` |\n\n## Examples\n\n**Volume slider**\n```tsx\n<Slider value={volume} onChange={setVolume} min={0} max={100} step={5} />\n```\n",
   "Switch": "# Switch — AI Cheat Sheet\n> Quick reference for Claude / Cursor / Copilot\n\n**Toggle switch for boolean on/off settings.**\n\n```ts\nimport { Switch } from \"@usevyre/react\"\n```\n\n## Valid Props\n\n| Prop | Values | Default |\n|------|--------|---------|\n| `size` | `\"sm\"` \\| `\"md\"` | `md` |\n| `checked` | `true` \\| `false` | — |\n| `disabled` | `true` \\| `false` | `false` |\n\n## Examples\n\n**Notifications toggle**\n```tsx\n<label style={{ display: 'flex', alignItems: 'center', gap: 'var(--vyre-spacing-2)' }}>\n  <Switch checked={notifications} onChange={setNotifications} />\n  Enable notifications\n</label>\n```\n",
@@ -7332,5 +9567,9 @@ export const cheatSheets = {
   "Combobox": "# Combobox — AI Cheat Sheet\n> Quick reference for Claude / Cursor / Copilot\n\n**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).**\n\n```ts\nimport { Combobox } from \"@usevyre/react\"\n```\n\n## Valid Props\n\n| Prop | Values | Default |\n|------|--------|---------|\n| `size` | `\"sm\"` \\| `\"md\"` \\| `\"lg\"` | `md` |\n| `disabled` | `true` \\| `false` | `false` |\n\n## Common AI Mistakes\n\n- ❌ `Combobox value=\"\"`\n  → Use value={null} for no selection\n- ❌ `Combobox options={string[]}`\n  → Use [{ value: 'ts', label: 'TypeScript' }]\n- ❌ `Using Combobox for command palette`\n  → Use Command for command palettes\n\n## Examples\n\n**Searchable language picker**\n```tsx\nconst [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/>\n```\n",
   "DataGrid": "# DataGrid — AI Cheat Sheet\n> Quick reference for Claude / Cursor / Copilot\n\n**Table with built-in column sorting, loading skeletons, and empty state. Filtering and pagination are out of scope — compose with the Pagination component.**\n\n```ts\nimport { DataGrid } from \"@usevyre/react\"\n```\n\n## Valid Props\n\n| Prop | Values | Default |\n|------|--------|---------|\n| `sortDir` | `\"asc\"` \\| `\"desc\"` | — |\n| `loading` | `true` \\| `false` | `false` |\n| `stickyHeader` | `true` \\| `false` | `false` |\n\n## Common AI Mistakes\n\n- ❌ `DataGrid expecting built-in pagination`\n  → Slice rows yourself and use the Pagination component\n- ❌ `DataGrid expecting built-in filtering`\n  → Filter the rows array before passing it in\n- ❌ `sortable without onSort`\n  → Handle onSort and sort the rows array in your state\n\n## Examples\n\n**Sortable grid**\n```tsx\nconst 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/>\n```\n\n**Loading state**\n```tsx\n<DataGrid columns={cols} rows={[]} loading />\n```\n",
   "Tag": "# Tag — AI Cheat Sheet\n> Quick reference for Claude / Cursor / Copilot\n\n**Standalone display tag/chip for categories, labels, or filter chips. NOT an input — for tag input use TagsInput. Group multiple with TagGroup.**\n\n```ts\nimport { Tag } from \"@usevyre/react\"\n```\n\n## Valid Props\n\n| Prop | Values | Default |\n|------|--------|---------|\n| `variant` | `\"default\"` \\| `\"accent\"` \\| `\"danger\"` | `default` |\n| `size` | `\"sm\"` \\| `\"md\"` \\| `\"lg\"` | `md` |\n| `disabled` | `true` \\| `false` | `false` |\n\n## Common AI Mistakes\n\n- ❌ `Tag variant=\"success\"`\n  → Use Badge for success/warning/teal status colors; Tag is for categories/filters\n- ❌ `Using Tag for tag input`\n  → Use TagsInput for adding/removing tags via keyboard\n- ❌ `Tag size=\"xl\"`\n  → Use size=\"lg\"\n\n## Examples\n\n**Category tags in a group**\n```tsx\n<TagGroup>\n  <Tag>Design</Tag>\n  <Tag variant=\"accent\">Featured</Tag>\n  <Tag>Engineering</Tag>\n</TagGroup>\n```\n\n**Removable filter chip (React)**\n```tsx\n<Tag onRemove={() => removeFilter(\"react\")}>react</Tag>\n```\n\n**Clickable toggle tag (React)**\n```tsx\n<Tag onClick={() => toggleFilter(\"vue\")}>vue</Tag>\n```\n",
-  "TagGroup": "# TagGroup — AI Cheat Sheet\n> Quick reference for Claude / Cursor / Copilot\n\n**Read-only container that lays out multiple Tag elements with automatic wrapping and consistent spacing. For tag input use TagsInput.**\n\n```ts\nimport { TagGroup, Tag } from \"@usevyre/react\"\n```\n\n## Valid Props\n\n| Prop | Values | Default |\n|------|--------|---------|\n| `gap` | `\"sm\"` \\| `\"md\"` \\| `\"lg\"` | `md` |\n| `wrap` | `true` \\| `false` | `true` |\n\n## Common AI Mistakes\n\n- ❌ `TagGroup without Tag children`\n  → Place <Tag> elements as direct children\n- ❌ `Using TagGroup for tag input`\n  → Use TagsInput for an editable tag field\n\n## Examples\n\n**Tag group with mixed variants**\n```tsx\n<TagGroup gap=\"sm\">\n  <Tag>React</Tag>\n  <Tag>Vue</Tag>\n  <Tag variant=\"accent\">TypeScript</Tag>\n</TagGroup>\n```\n"
+  "TagGroup": "# TagGroup — AI Cheat Sheet\n> Quick reference for Claude / Cursor / Copilot\n\n**Read-only container that lays out multiple Tag elements with automatic wrapping and consistent spacing. For tag input use TagsInput.**\n\n```ts\nimport { TagGroup, Tag } from \"@usevyre/react\"\n```\n\n## Valid Props\n\n| Prop | Values | Default |\n|------|--------|---------|\n| `gap` | `\"sm\"` \\| `\"md\"` \\| `\"lg\"` | `md` |\n| `wrap` | `true` \\| `false` | `true` |\n\n## Common AI Mistakes\n\n- ❌ `TagGroup without Tag children`\n  → Place <Tag> elements as direct children\n- ❌ `Using TagGroup for tag input`\n  → Use TagsInput for an editable tag field\n\n## Examples\n\n**Tag group with mixed variants**\n```tsx\n<TagGroup gap=\"sm\">\n  <Tag>React</Tag>\n  <Tag>Vue</Tag>\n  <Tag variant=\"accent\">TypeScript</Tag>\n</TagGroup>\n```\n",
+  "Item": "# Item — AI Cheat Sheet\n> Quick reference for Claude / Cursor / Copilot\n\n**Layout primitive for list rows, settings rows, and notification rows. Denser than Card — use Item (not Card) for repeated list rows.**\n\n```ts\nimport { Item, ItemMedia, ItemContent, ItemTitle, ItemDescription, ItemActions, ItemGroup } from \"@usevyre/react\"\n```\n\n## Valid Props\n\n| Prop | Values | Default |\n|------|--------|---------|\n| `variant` | `\"default\"` \\| `\"outlined\"` \\| `\"muted\"` \\| `\"plain\"` | `default` |\n| `size` | `\"sm\"` \\| `\"md\"` \\| `\"lg\"` | `md` |\n| `clickable` | `true` \\| `false` | `false` |\n\n## Common AI Mistakes\n\n- ❌ `Card used for repeated list rows`\n  → Use <Item> (optionally inside <ItemGroup separated>) for list/settings rows\n- ❌ `Item variant=\"primary\"`\n  → Use variant=\"default\" | \"outlined\" | \"muted\"\n- ❌ `raw text directly inside Item`\n  → Wrap text in <ItemContent><ItemTitle>…</ItemTitle></ItemContent>\n\n## Examples\n\n**Settings row with media, content and a trailing switch**\n```tsx\n<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>\n```\n\n**Grouped clickable list with dividers**\n```tsx\n<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>\n```\n",
+  "Kanban": "# Kanban — AI Cheat Sheet\n> Quick reference for Claude / Cursor / Copilot\n\n**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.**\n\n```ts\nimport { Kanban } from \"@usevyre/react\"\n```\n\n## Common AI Mistakes\n\n- ❌ `Kanban without onChange (or ignoring it)`\n  → Store columns in state and setColumns in onChange (v-model in Vue)\n- ❌ `Duplicate card ids across columns`\n  → Use globally-unique card ids across the entire board\n- ❌ `Mutating value in place then calling onChange`\n  → Pass the new array Kanban gives you straight to setState / v-model\n- ❌ `color=\"blue\" (or any non-semantic value)`\n  → Use one of: \"default\" | \"accent\" | \"teal\" | \"success\" | \"warning\" | \"danger\"\n\n## Examples\n\n**Controlled board**\n```tsx\nconst [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} />\n```\n\n**Custom card body + click handler**\n```tsx\n<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/>\n```\n\n**Tinted columns/cards + complex card content**\n```tsx\nconst [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/>\n```\n",
+  "Conversation": "# Conversation — AI Cheat Sheet\n> Quick reference for Claude / Cursor / Copilot\n\n**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.**\n\n```ts\nimport { Conversation } from \"@usevyre/react\"\n```\n\n## Valid Props\n\n| Prop | Values | Default |\n|------|--------|---------|\n| `composer` | `true` \\| `false` | `false` |\n| `allowAttachments` | `true` \\| `false` | `false` |\n\n## Common AI Mistakes\n\n- ❌ `Conversation without currentUserId`\n  → Always pass currentUserId matching one of the message authorId values\n- ❌ `Expecting Conversation to store/append messages`\n  → Append to your own state in onSend (or @send) and pass it back via value\n- ❌ `composer without onSend (React) / @send (Vue)`\n  → Provide onSend / @send to append the message to value\n- ❌ `Treating onSend as (text) only when using allowAttachments`\n  → Handle onSend(text, files) — map files to message attachments and append\n\n## Examples\n\n**Controlled thread with built-in composer**\n```tsx\nconst [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/>\n```\n\n**Typing indicator + custom bubble**\n```tsx\n<Conversation\n  value={messages}\n  currentUserId=\"me\"\n  typing=\"Sam is typing\"\n  renderMessage={(m) => <strong>{m.text}</strong>}\n/>\n```\n\n**Message with image + file attachments**\n```tsx\nconst 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\" />\n```\n",
+  "DateRangePicker": "# DateRangePicker — AI Cheat Sheet\n> Quick reference for Claude / Cursor / Copilot\n\n**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.**\n\n```ts\nimport { DateRangePicker } from \"@usevyre/react\"\n```\n\n## Valid Props\n\n| Prop | Values | Default |\n|------|--------|---------|\n| `numberOfMonths` | `\"1\"` \\| `\"2\"` | `2` |\n| `weekStartsOn` | `\"0\"` \\| `\"1\"` | `1` |\n\n## Common AI Mistakes\n\n- ❌ `value={[from, to]}`\n  → Use value={{ from, to }} and read range.from / range.to\n- ❌ `DateRangePicker for a single date`\n  → Use <DatePicker /> for a single date\n- ❌ `presets=\"true\" (string)`\n  → Use the bare prop: presets  (or presets={true})\n\n## Examples\n\n**Range picker with built-in presets**\n```tsx\nconst [range, setRange] = useState({ from: null, to: null });\n<DateRangePicker value={range} onChange={setRange} presets />\n```\n\n**Single month, no presets**\n```tsx\n<DateRangePicker value={range} onChange={setRange} numberOfMonths={1} />\n```\n"
 };