@usevyre/ai-context 1.0.0 → 1.1.0

package/dist/anti-patterns.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.2.0",
+  "version": "1.1.0",
   "rules": [
     {
       "component": "Accordion",
@@ -217,6 +217,111 @@
       "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"
     }
   ]
 }

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/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/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/index.md

@@ -32,3 +32,9 @@ 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.

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} />
+```

package/dist/claude-context.md

@@ -1,5 +1,5 @@
 # useVyre Design System Context
-# Version: 0.2.0
+# Version: 1.1.0
 
 You are working in a codebase that uses the useVyre design system.
 Follow the rules below strictly when writing any UI code.
@@ -887,6 +887,188 @@ import { Text, Heading, Lead, Code, Blockquote } from "@usevyre/react"
 
 ---
 
+### ButtonGroup
+
+Groups multiple Button components into one visual unit (toolbar, segmented control). Pure layout — no internal state.
+
+```tsx
+import { ButtonGroup, Button } from "@usevyre/react"
+
+// Props:
+// orientation    = "horizontal" | "vertical" (default: horizontal)
+// attached       = boolean (default: false)
+// size           = "sm" | "md" | "lg" | "icon"
+
+// Examples:
+<ButtonGroup attached>
+  <Button variant="secondary">Day</Button>
+  <Button variant="secondary">Week</Button>
+  <Button variant="secondary">Month</Button>
+</ButtonGroup>
+<ButtonGroup orientation="vertical" attached>
+  <Button variant="secondary">Top</Button>
+  <Button variant="secondary">Bottom</Button>
+</ButtonGroup>
+```
+
+**Common mistakes:**
+- ❌ `ButtonGroup variant="..."` → Set variant on each <Button> inside the group
+- ❌ `ButtonGroup without Button children` → Place <Button> elements as direct children
+
+---
+
+### TagsInput
+
+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.
+
+```tsx
+import { TagsInput } from "@usevyre/react"
+
+// Props:
+// value          = string[]
+// onChange       = (tags: string[]) => void
+// placeholder    = string
+// disabled       = boolean (default: false)
+// max            = number
+// size           = "sm" | "md" | "lg" (default: md)
+
+// Examples:
+const [tags, setTags] = useState<string[]>([]);
+<TagsInput value={tags} onChange={setTags} placeholder="Add a tag…" />
+<TagsInput value={tags} onChange={setTags} max={5} />
+```
+
+**Common mistakes:**
+- ❌ `TagsInput value={string}` → Pass an array: value={['react','vue']}
+- ❌ `TagsInput without onChange` → Provide value and onChange (React) or v-model (Vue)
+
+---
+
+### Combobox
+
+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).
+
+```tsx
+import { Combobox } from "@usevyre/react"
+
+// Props:
+// options        = { value: string; label: string; disabled?: boolean }[]
+// value          = string | null
+// onChange       = (value: string | null) => void
+// placeholder    = string (default: "Search…")
+// disabled       = boolean (default: false)
+// size           = "sm" | "md" | "lg" (default: md)
+// emptyText      = string (default: "No results")
+
+// Examples:
+const [lang, setLang] = useState<string | null>(null);
+<Combobox
+  options={[{ value: "ts", label: "TypeScript" }, { value: "go", label: "Go" }]}
+  value={lang}
+  onChange={setLang}
+  placeholder="Search language…"
+/>
+```
+
+**Common 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
+
+---
+
+### DataGrid
+
+Table with built-in column sorting, loading skeletons, and empty state. Filtering and pagination are out of scope — compose with the Pagination component.
+
+```tsx
+import { DataGrid } from "@usevyre/react"
+
+// Props:
+// columns        = { key: string; label: string; sortable?: boolean; width?: string }[]
+// rows           = Record<string, unknown>[]
+// sortKey        = string
+// sortDir        = "asc" | "desc"
+// onSort         = (key: string, dir: 'asc' | 'desc') => void
+// loading        = boolean (default: false)
+// emptyText      = string (default: "No data")
+// stickyHeader   = boolean (default: false)
+
+// Examples:
+const cols = [{ key: "name", label: "Name", sortable: true }];
+<DataGrid
+  columns={cols}
+  rows={people}
+  sortKey={sortKey}
+  sortDir={sortDir}
+  onSort={(k, d) => { setSortKey(k); setSortDir(d); }}
+/>
+<DataGrid columns={cols} rows={[]} loading />
+```
+
+**Common 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
+
+---
+
+### Tag
+
+Standalone display tag/chip for categories, labels, or filter chips. NOT an input — for tag input use TagsInput. Group multiple with TagGroup.
+
+```tsx
+import { Tag } from "@usevyre/react"
+
+// Props:
+// variant        = "default" | "accent" | "danger" (default: default)
+// size           = "sm" | "md" | "lg" (default: md)
+// onRemove       = () => void
+// onClick        = () => void
+// disabled       = boolean (default: false)
+
+// Examples:
+<TagGroup>
+  <Tag>Design</Tag>
+  <Tag variant="accent">Featured</Tag>
+  <Tag>Engineering</Tag>
+</TagGroup>
+<Tag onRemove={() => removeFilter("react")}>react</Tag>
+<Tag onClick={() => toggleFilter("vue")}>vue</Tag>
+```
+
+**Common 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"
+
+---
+
+### TagGroup
+
+Read-only container that lays out multiple Tag elements with automatic wrapping and consistent spacing. For tag input use TagsInput.
+
+```tsx
+import { TagGroup, Tag } from "@usevyre/react"
+
+// Props:
+// gap            = "sm" | "md" | "lg" (default: md)
+// wrap           = boolean (default: true)
+
+// Examples:
+<TagGroup gap="sm">
+  <Tag>React</Tag>
+  <Tag>Vue</Tag>
+  <Tag variant="accent">TypeScript</Tag>
+</TagGroup>
+```
+
+**Common mistakes:**
+- ❌ `TagGroup without Tag children` → Place <Tag> elements as direct children
+- ❌ `Using TagGroup for tag input` → Use TagsInput for an editable tag field
+
+---
+
 ## Hallucination Guard — Common AI Mistakes
 
 The following prop values and patterns do NOT exist in useVyre.
@@ -923,6 +1105,21 @@ If you generate these, you are hallucinating.
 - ❌ `<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
 
 ---