@usevyre/ai-context 1.0.1 → 1.2.0

package/dist/anti-patterns.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.0",
+  "version": "1.2.0",
   "rules": [
     {
       "component": "Accordion",
@@ -101,9 +101,30 @@
     },
     {
       "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"
     },
     {
@@ -120,6 +141,48 @@
       "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",
@@ -141,6 +204,13 @@
       "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\"",
@@ -155,6 +225,13 @@
       "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\"",
@@ -217,6 +294,209 @@
       "reason": "Typography components apply the correct token-based styles",
       "fix": "Use <Heading>, <Text>, <Lead> from @usevyre/react",
       "severity": "error"
+    },
+    {
+      "component": "ButtonGroup",
+      "pattern": "ButtonGroup variant=\"...\"",
+      "reason": "ButtonGroup has no variant prop — variant goes on each child Button",
+      "fix": "Set variant on each <Button> inside the group",
+      "severity": "error"
+    },
+    {
+      "component": "ButtonGroup",
+      "pattern": "ButtonGroup without Button children",
+      "reason": "ButtonGroup is a layout wrapper for Button elements",
+      "fix": "Place <Button> elements as direct children",
+      "severity": "error"
+    },
+    {
+      "component": "TagsInput",
+      "pattern": "TagsInput value={string}",
+      "reason": "value must be a string array, not a string",
+      "fix": "Pass an array: value={['react','vue']}",
+      "severity": "error"
+    },
+    {
+      "component": "TagsInput",
+      "pattern": "TagsInput without onChange",
+      "reason": "TagsInput is controlled — it needs onChange to update",
+      "fix": "Provide value and onChange (React) or v-model (Vue)",
+      "severity": "error"
+    },
+    {
+      "component": "Combobox",
+      "pattern": "Combobox value=\"\"",
+      "reason": "Empty selection must be null, not empty string",
+      "fix": "Use value={null} for no selection",
+      "severity": "error"
+    },
+    {
+      "component": "Combobox",
+      "pattern": "Combobox options={string[]}",
+      "reason": "options must be objects with value and label",
+      "fix": "Use [{ value: 'ts', label: 'TypeScript' }]",
+      "severity": "error"
+    },
+    {
+      "component": "Combobox",
+      "pattern": "Using Combobox for command palette",
+      "reason": "Combobox is single-value select, not an action palette",
+      "fix": "Use Command for command palettes",
+      "severity": "error"
+    },
+    {
+      "component": "DataGrid",
+      "pattern": "DataGrid expecting built-in pagination",
+      "reason": "DataGrid does not paginate — it only sorts",
+      "fix": "Slice rows yourself and use the Pagination component",
+      "severity": "error"
+    },
+    {
+      "component": "DataGrid",
+      "pattern": "DataGrid expecting built-in filtering",
+      "reason": "DataGrid does not filter rows",
+      "fix": "Filter the rows array before passing it in",
+      "severity": "error"
+    },
+    {
+      "component": "DataGrid",
+      "pattern": "sortable without onSort",
+      "reason": "Sorting is controlled — the grid does not sort data itself",
+      "fix": "Handle onSort and sort the rows array in your state",
+      "severity": "error"
+    },
+    {
+      "component": "Tag",
+      "pattern": "Tag variant=\"success\"",
+      "reason": "Tag only has default, accent, danger variants (unlike Badge which has more)",
+      "fix": "Use Badge for success/warning/teal status colors; Tag is for categories/filters",
+      "severity": "error"
+    },
+    {
+      "component": "Tag",
+      "pattern": "Using Tag for tag input",
+      "reason": "Tag is display-only, it does not accept typed input",
+      "fix": "Use TagsInput for adding/removing tags via keyboard",
+      "severity": "error"
+    },
+    {
+      "component": "Tag",
+      "pattern": "Tag size=\"xl\"",
+      "reason": "Maximum size is 'lg'",
+      "fix": "Use size=\"lg\"",
+      "severity": "error"
+    },
+    {
+      "component": "TagGroup",
+      "pattern": "TagGroup without Tag children",
+      "reason": "TagGroup is a layout wrapper for Tag elements",
+      "fix": "Place <Tag> elements as direct children",
+      "severity": "error"
+    },
+    {
+      "component": "TagGroup",
+      "pattern": "Using TagGroup for tag input",
+      "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"
     }
   ]
 }

package/dist/cheat-sheets/buttongroup.md

@@ -0,0 +1,42 @@
+# ButtonGroup — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Groups multiple Button components into one visual unit (toolbar, segmented control). Pure layout — no internal state.**
+
+```ts
+import { ButtonGroup, Button } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `orientation` | `"horizontal"` \| `"vertical"` | `horizontal` |
+| `size` | `"sm"` \| `"md"` \| `"lg"` \| `"icon"` | — |
+| `attached` | `true` \| `false` | `false` |
+
+## Common AI Mistakes
+
+- ❌ `ButtonGroup variant="..."`
+  → Set variant on each <Button> inside the group
+- ❌ `ButtonGroup without Button children`
+  → Place <Button> elements as direct children
+
+## Examples
+
+**Segmented control**
+```tsx
+<ButtonGroup attached>
+  <Button variant="secondary">Day</Button>
+  <Button variant="secondary">Week</Button>
+  <Button variant="secondary">Month</Button>
+</ButtonGroup>
+```
+
+**Vertical group**
+```tsx
+<ButtonGroup orientation="vertical" attached>
+  <Button variant="secondary">Top</Button>
+  <Button variant="secondary">Bottom</Button>
+</ButtonGroup>
+```

package/dist/cheat-sheets/calendar.md

@@ -1,7 +1,7 @@
 # Calendar — AI Cheat Sheet
 > Quick reference for Claude / Cursor / Copilot
 
-**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.**
 
 ```ts
 import { Calendar } from "@usevyre/react"
@@ -15,8 +15,10 @@ import { Calendar } from "@usevyre/react"
 
 ## Common AI 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]
 
 ## Examples
 

package/dist/cheat-sheets/combobox.md

@@ -0,0 +1,37 @@
+# Combobox — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**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).**
+
+```ts
+import { Combobox } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `size` | `"sm"` \| `"md"` \| `"lg"` | `md` |
+| `disabled` | `true` \| `false` | `false` |
+
+## Common AI Mistakes
+
+- ❌ `Combobox value=""`
+  → Use value={null} for no selection
+- ❌ `Combobox options={string[]}`
+  → Use [{ value: 'ts', label: 'TypeScript' }]
+- ❌ `Using Combobox for command palette`
+  → Use Command for command palettes
+
+## Examples
+
+**Searchable language picker**
+```tsx
+const [lang, setLang] = useState<string | null>(null);
+<Combobox
+  options={[{ value: "ts", label: "TypeScript" }, { value: "go", label: "Go" }]}
+  value={lang}
+  onChange={setLang}
+  placeholder="Search language…"
+/>
+```

package/dist/cheat-sheets/conversation.md

@@ -0,0 +1,63 @@
+# Conversation — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**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.**
+
+```ts
+import { Conversation } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `composer` | `true` \| `false` | `false` |
+| `allowAttachments` | `true` \| `false` | `false` |
+
+## Common AI 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
+
+## Examples
+
+**Controlled thread with built-in composer**
+```tsx
+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 }])}
+/>
+```
+
+**Typing indicator + custom bubble**
+```tsx
+<Conversation
+  value={messages}
+  currentUserId="me"
+  typing="Sam is typing"
+  renderMessage={(m) => <strong>{m.text}</strong>}
+/>
+```
+
+**Message with image + file attachments**
+```tsx
+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" />
+```

package/dist/cheat-sheets/datagrid.md

@@ -0,0 +1,44 @@
+# DataGrid — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Table with built-in column sorting, loading skeletons, and empty state. Filtering and pagination are out of scope — compose with the Pagination component.**
+
+```ts
+import { DataGrid } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `sortDir` | `"asc"` \| `"desc"` | — |
+| `loading` | `true` \| `false` | `false` |
+| `stickyHeader` | `true` \| `false` | `false` |
+
+## Common AI Mistakes
+
+- ❌ `DataGrid expecting built-in pagination`
+  → Slice rows yourself and use the Pagination component
+- ❌ `DataGrid expecting built-in filtering`
+  → Filter the rows array before passing it in
+- ❌ `sortable without onSort`
+  → Handle onSort and sort the rows array in your state
+
+## Examples
+
+**Sortable grid**
+```tsx
+const cols = [{ key: "name", label: "Name", sortable: true }];
+<DataGrid
+  columns={cols}
+  rows={people}
+  sortKey={sortKey}
+  sortDir={sortDir}
+  onSort={(k, d) => { setSortKey(k); setSortDir(d); }}
+/>
+```
+
+**Loading state**
+```tsx
+<DataGrid columns={cols} rows={[]} loading />
+```

package/dist/cheat-sheets/datepicker.md

@@ -0,0 +1,36 @@
+# DatePicker — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**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.**
+
+```ts
+import { DatePicker } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `mode` | `"single"` \| `"range"` \| `"multiple"` | `single` |
+| `weekStartsOn` | `"0"` \| `"1"` | `1` |
+| `showTime` | `true` \| `false` | `false` |
+
+## Common AI 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)
+
+## Examples
+
+**Single date field**
+```tsx
+const [date, setDate] = useState(null);
+<DatePicker value={date} onChange={setDate} placeholder="Pick a date" />
+```
+
+**Date + time**
+```tsx
+<DatePicker value={date} onChange={setDate} showTime />
+```

package/dist/cheat-sheets/daterangepicker.md

@@ -0,0 +1,37 @@
+# DateRangePicker — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**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.**
+
+```ts
+import { DateRangePicker } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `numberOfMonths` | `"1"` \| `"2"` | `2` |
+| `weekStartsOn` | `"0"` \| `"1"` | `1` |
+
+## Common AI 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})
+
+## Examples
+
+**Range picker with built-in presets**
+```tsx
+const [range, setRange] = useState({ from: null, to: null });
+<DateRangePicker value={range} onChange={setRange} presets />
+```
+
+**Single month, no presets**
+```tsx
+<DateRangePicker value={range} onChange={setRange} numberOfMonths={1} />
+```

package/dist/cheat-sheets/field.md

@@ -1,7 +1,7 @@
 # Field — AI Cheat Sheet
 > Quick reference for Claude / Cursor / Copilot
 
-**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.**
 
 ```ts
 import { Field, Input, Textarea } from "@usevyre/react"
@@ -18,6 +18,8 @@ import { Field, Input, Textarea } from "@usevyre/react"
 
 - ❌ `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
 
 ## Examples
 
@@ -34,3 +36,19 @@ import { Field, Input, Textarea } from "@usevyre/react"
   <Input leftElement={<SearchIcon />} placeholder="Search..." />
 </Field>
 ```
+
+**Composable field with explicit parts**
+```tsx
+<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>
+```