@usevyre/ai-context 1.0.1 → 1.2.0

package/dist/cheat-sheets/index.md

@@ -8,12 +8,15 @@ Quick reference for AI agents — one file per component.
 - [Badge](badge.md) — Small label for status, category, or count. Use dot prop for live status indicator.
 - [Breadcrumb](breadcrumb.md) — Navigation trail showing current page location in hierarchy.
 - [Button](button.md) — Triggers actions and navigation. The most commonly used interactive element.
-- [Calendar](calendar.md) — Date picker calendar widget for selecting single dates or ranges.
+- [Calendar](calendar.md) — 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.
+- [DatePicker](datepicker.md) — 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.
 - [Card](card.md) — Content container with optional header, body, and footer sections.
 - [Checkbox](checkbox.md) — Binary toggle for boolean form values.
+- [RadioGroup](radiogroup.md) — 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.
+- [RichTextEditor](richtexteditor.md) — 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.
 - [Command](command.md) — Command palette / search dialog. Use for search-first navigation or quick actions.
 - [DropdownMenu](dropdownmenu.md) — Contextual menu triggered by a button. Supports items, separators, checkbox items, radio groups, and sub-menus.
-- [Field](field.md) — Form field wrapper providing label, hint text, and validation state for Input or Textarea.
+- [Field](field.md) — 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.
 - [Input](input.md) — Text input field. Wrap in Field for labels and validation. Use leftElement/rightElement for icons.
 - [Label](label.md) — Accessible form label. Associate with input via htmlFor.
 - [Modal](modal.md) — Dialog overlay for confirmations, forms, or focused content.
@@ -32,3 +35,13 @@ Quick reference for AI agents — one file per component.
 - [Toast](toast.md) — Transient notification. Use the useToast hook to trigger toasts imperatively. React: wrap app in <ToastProvider>. Vue: place <ToastViewport /> once in app root.
 - [Tooltip](tooltip.md) — Short label that appears on hover/focus. For rich content use Popover instead.
 - [Typography](typography.md) — Text rendering components with semantic scale. Includes Text, Heading, Lead, Code, Blockquote.
+- [ButtonGroup](buttongroup.md) — Groups multiple Button components into one visual unit (toolbar, segmented control). Pure layout — no internal state.
+- [TagsInput](tagsinput.md) — Multi-tag input. Type and press Enter or comma to add a tag, click x to remove, Backspace on empty input removes the last tag. Controlled.
+- [Combobox](combobox.md) — 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).
+- [DataGrid](datagrid.md) — Table with built-in column sorting, loading skeletons, and empty state. Filtering and pagination are out of scope — compose with the Pagination component.
+- [Tag](tag.md) — Standalone display tag/chip for categories, labels, or filter chips. NOT an input — for tag input use TagsInput. Group multiple with TagGroup.
+- [TagGroup](taggroup.md) — Read-only container that lays out multiple Tag elements with automatic wrapping and consistent spacing. For tag input use TagsInput.
+- [Item](item.md) — Layout primitive for list rows, settings rows, and notification rows. Denser than Card — use Item (not Card) for repeated list rows.
+- [Kanban](kanban.md) — 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.
+- [Conversation](conversation.md) — 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.
+- [DateRangePicker](daterangepicker.md) — 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.

package/dist/cheat-sheets/input.md

@@ -19,6 +19,8 @@ import { Input } from "@usevyre/react"
   → 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
 
 ## Examples
 

package/dist/cheat-sheets/item.md

@@ -0,0 +1,53 @@
+# Item — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Layout primitive for list rows, settings rows, and notification rows. Denser than Card — use Item (not Card) for repeated list rows.**
+
+```ts
+import { Item, ItemMedia, ItemContent, ItemTitle, ItemDescription, ItemActions, ItemGroup } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `variant` | `"default"` \| `"outlined"` \| `"muted"` \| `"plain"` | `default` |
+| `size` | `"sm"` \| `"md"` \| `"lg"` | `md` |
+| `clickable` | `true` \| `false` | `false` |
+
+## Common AI 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>
+
+## Examples
+
+**Settings row with media, content and a trailing switch**
+```tsx
+<Item>
+  <ItemMedia><BellIcon /></ItemMedia>
+  <ItemContent>
+    <ItemTitle>Notifications</ItemTitle>
+    <ItemDescription>Receive an email when someone mentions you.</ItemDescription>
+  </ItemContent>
+  <ItemActions>
+    <Switch defaultChecked />
+  </ItemActions>
+</Item>
+```
+
+**Grouped clickable list with dividers**
+```tsx
+<ItemGroup separated>
+  <Item clickable>
+    <ItemContent><ItemTitle>Profile</ItemTitle></ItemContent>
+  </Item>
+  <Item clickable>
+    <ItemContent><ItemTitle>Billing</ItemTitle></ItemContent>
+  </Item>
+</ItemGroup>
+```

package/dist/cheat-sheets/kanban.md

@@ -0,0 +1,59 @@
+# Kanban — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**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.**
+
+```ts
+import { Kanban } from "@usevyre/react"
+```
+
+## Common AI 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"
+
+## Examples
+
+**Controlled board**
+```tsx
+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} />
+```
+
+**Custom card body + click handler**
+```tsx
+<Kanban
+  value={columns}
+  onChange={setColumns}
+  onCardClick={(card) => openDetail(card.id)}
+  renderCard={(card) => (
+    <><strong>{card.title}</strong><Badge>{card.id}</Badge></>
+  )}
+/>
+```
+
+**Tinted columns/cards + complex card content**
+```tsx
+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} /></>
+  )}
+/>
+```

package/dist/cheat-sheets/radiogroup.md

@@ -0,0 +1,47 @@
+# RadioGroup — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**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.**
+
+```ts
+import { RadioGroup, Radio } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `size` | `"sm"` \| `"md"` | `md` |
+| `orientation` | `"vertical"` \| `"horizontal"` | `vertical` |
+| `disabled` | `true` \| `false` | `false` |
+
+## Common AI 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
+
+## Examples
+
+**Data-driven**
+```tsx
+<RadioGroup
+  value={plan}
+  onChange={setPlan}
+  options={[
+    { value: "free", label: "Free", description: "For hobby projects" },
+    { value: "pro",  label: "Pro",  description: "For teams" },
+  ]}
+/>
+```
+
+**Composable children**
+```tsx
+<RadioGroup value={plan} onChange={setPlan} orientation="horizontal">
+  <Radio value="free" label="Free" />
+  <Radio value="pro"  label="Pro" />
+</RadioGroup>
+```

package/dist/cheat-sheets/richtexteditor.md

@@ -0,0 +1,41 @@
+# RichTextEditor — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**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.**
+
+```ts
+import { RichTextEditor } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `disabled` | `true` \| `false` | `false` |
+| `readOnly` | `true` \| `false` | `false` |
+
+## Common AI 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"]}
+
+## Examples
+
+**Controlled editor**
+```tsx
+const [html, setHtml] = useState("<p>Hello <strong>world</strong></p>");
+<RichTextEditor value={html} onChange={setHtml} placeholder="Write…" />
+```
+
+**Minimal toolbar**
+```tsx
+<RichTextEditor
+  value={html}
+  onChange={setHtml}
+  toolbar={["bold", "italic", "link"]}
+/>
+```

package/dist/cheat-sheets/tag.md

@@ -0,0 +1,46 @@
+# Tag — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Standalone display tag/chip for categories, labels, or filter chips. NOT an input — for tag input use TagsInput. Group multiple with TagGroup.**
+
+```ts
+import { Tag } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `variant` | `"default"` \| `"accent"` \| `"danger"` | `default` |
+| `size` | `"sm"` \| `"md"` \| `"lg"` | `md` |
+| `disabled` | `true` \| `false` | `false` |
+
+## Common AI Mistakes
+
+- ❌ `Tag variant="success"`
+  → Use Badge for success/warning/teal status colors; Tag is for categories/filters
+- ❌ `Using Tag for tag input`
+  → Use TagsInput for adding/removing tags via keyboard
+- ❌ `Tag size="xl"`
+  → Use size="lg"
+
+## Examples
+
+**Category tags in a group**
+```tsx
+<TagGroup>
+  <Tag>Design</Tag>
+  <Tag variant="accent">Featured</Tag>
+  <Tag>Engineering</Tag>
+</TagGroup>
+```
+
+**Removable filter chip (React)**
+```tsx
+<Tag onRemove={() => removeFilter("react")}>react</Tag>
+```
+
+**Clickable toggle tag (React)**
+```tsx
+<Tag onClick={() => toggleFilter("vue")}>vue</Tag>
+```

package/dist/cheat-sheets/taggroup.md

@@ -0,0 +1,33 @@
+# TagGroup — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Read-only container that lays out multiple Tag elements with automatic wrapping and consistent spacing. For tag input use TagsInput.**
+
+```ts
+import { TagGroup, Tag } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `gap` | `"sm"` \| `"md"` \| `"lg"` | `md` |
+| `wrap` | `true` \| `false` | `true` |
+
+## Common AI Mistakes
+
+- ❌ `TagGroup without Tag children`
+  → Place <Tag> elements as direct children
+- ❌ `Using TagGroup for tag input`
+  → Use TagsInput for an editable tag field
+
+## Examples
+
+**Tag group with mixed variants**
+```tsx
+<TagGroup gap="sm">
+  <Tag>React</Tag>
+  <Tag>Vue</Tag>
+  <Tag variant="accent">TypeScript</Tag>
+</TagGroup>
+```

package/dist/cheat-sheets/tagsinput.md

@@ -0,0 +1,35 @@
+# TagsInput — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Multi-tag input. Type and press Enter or comma to add a tag, click x to remove, Backspace on empty input removes the last tag. Controlled.**
+
+```ts
+import { TagsInput } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `size` | `"sm"` \| `"md"` \| `"lg"` | `md` |
+| `disabled` | `true` \| `false` | `false` |
+
+## Common AI Mistakes
+
+- ❌ `TagsInput value={string}`
+  → Pass an array: value={['react','vue']}
+- ❌ `TagsInput without onChange`
+  → Provide value and onChange (React) or v-model (Vue)
+
+## Examples
+
+**Basic tags input**
+```tsx
+const [tags, setTags] = useState<string[]>([]);
+<TagsInput value={tags} onChange={setTags} placeholder="Add a tag…" />
+```
+
+**Limited to 5 tags**
+```tsx
+<TagsInput value={tags} onChange={setTags} max={5} />
+```