@usevyre/ai-context 0.1.1 → 0.2.0

package/dist/anti-patterns.json

@@ -0,0 +1,222 @@
+{
+  "version": "0.2.0",
+  "rules": [
+    {
+      "component": "Accordion",
+      "pattern": "Accordion without AccordionItem",
+      "reason": "Accordion requires AccordionItem as direct child",
+      "fix": "Always compose: Accordion > AccordionItem > AccordionTrigger + AccordionContent",
+      "severity": "error"
+    },
+    {
+      "component": "Alert",
+      "pattern": "variant=\"error\"",
+      "reason": "No 'error' variant exists",
+      "fix": "Use variant=\"danger\"",
+      "severity": "error"
+    },
+    {
+      "component": "Alert",
+      "pattern": "variant=\"primary\"",
+      "reason": "Alert uses severity variants, not brand variants",
+      "fix": "Use variant=\"info\" | \"success\" | \"warning\" | \"danger\"",
+      "severity": "error"
+    },
+    {
+      "component": "Avatar",
+      "pattern": "size=\"xs\"",
+      "reason": "Minimum size is 'sm'",
+      "fix": "Use size=\"sm\"",
+      "severity": "error"
+    },
+    {
+      "component": "Avatar",
+      "pattern": "size=\"2xl\"",
+      "reason": "Maximum size is 'xl'",
+      "fix": "Use size=\"xl\"",
+      "severity": "error"
+    },
+    {
+      "component": "Badge",
+      "pattern": "variant=\"primary\"",
+      "reason": "Badge has no 'primary' variant",
+      "fix": "Use variant=\"accent\" for brand color",
+      "severity": "error"
+    },
+    {
+      "component": "Badge",
+      "pattern": "variant=\"error\"",
+      "reason": "No 'error' variant exists",
+      "fix": "Use variant=\"danger\"",
+      "severity": "error"
+    },
+    {
+      "component": "Badge",
+      "pattern": "variant=\"info\"",
+      "reason": "No 'info' variant on Badge (use Alert for info messages)",
+      "fix": "Use variant=\"teal\" for info-like styling",
+      "severity": "error"
+    },
+    {
+      "component": "Breadcrumb",
+      "pattern": "Using plain <a> tags inside Breadcrumb",
+      "reason": "Use BreadcrumbLink for correct styling and accessibility",
+      "fix": "Use BreadcrumbItem > BreadcrumbLink for each crumb",
+      "severity": "error"
+    },
+    {
+      "component": "Button",
+      "pattern": "variant=\"blue\"",
+      "reason": "No 'blue' variant exists",
+      "fix": "Use variant=\"accent\" for brand amber, or variant=\"teal\" for teal",
+      "severity": "error"
+    },
+    {
+      "component": "Button",
+      "pattern": "size=\"xl\"",
+      "reason": "Maximum size is 'lg'",
+      "fix": "Use size=\"lg\"",
+      "severity": "error"
+    },
+    {
+      "component": "Button",
+      "pattern": "color=\"...\"",
+      "reason": "No color prop exists on Button",
+      "fix": "Use variant prop instead",
+      "severity": "error"
+    },
+    {
+      "component": "Button",
+      "pattern": "icon={...}",
+      "reason": "No 'icon' prop for inserting icons",
+      "fix": "Use leftIcon={...} or rightIcon={...}",
+      "severity": "error"
+    },
+    {
+      "component": "Button",
+      "pattern": "size=\"icon\" without aria-label",
+      "reason": "Icon-only buttons have no visible text — screen readers need aria-label",
+      "fix": "Add aria-label describing the action",
+      "severity": "error"
+    },
+    {
+      "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",
+      "severity": "error"
+    },
+    {
+      "component": "Card",
+      "pattern": "variant=\"primary\"",
+      "reason": "Card has no 'primary' variant",
+      "fix": "Use variant=\"elevated\" | \"outlined\" | \"ghost\" | \"accent\"",
+      "severity": "error"
+    },
+    {
+      "component": "Checkbox",
+      "pattern": "size=\"lg\"",
+      "reason": "Maximum size is 'md'",
+      "fix": "Use size=\"md\"",
+      "severity": "error"
+    },
+    {
+      "component": "Command",
+      "pattern": "Using Input type=\"search\" for search UI",
+      "reason": "Command component is the correct pattern for search-first UI",
+      "fix": "Use Command + CommandInput + CommandList + CommandItem",
+      "severity": "error"
+    },
+    {
+      "component": "DropdownMenu",
+      "pattern": "DropdownItem variant=\"primary\"",
+      "reason": "DropdownItem only has 'default' and 'danger' variants",
+      "fix": "Use variant=\"danger\" for destructive items only",
+      "severity": "error"
+    },
+    {
+      "component": "Field",
+      "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",
+      "severity": "error"
+    },
+    {
+      "component": "Input",
+      "pattern": "size=\"icon\"",
+      "reason": "'icon' size is only valid for Button, not Input",
+      "fix": "Use size=\"sm\" | \"md\" | \"lg\"",
+      "severity": "error"
+    },
+    {
+      "component": "Input",
+      "pattern": "type=\"search\" for search UI",
+      "reason": "Use Command component for search-first interfaces",
+      "fix": "Import Command from @usevyre/react for search palettes",
+      "severity": "error"
+    },
+    {
+      "component": "Modal",
+      "pattern": "size=\"xl\"",
+      "reason": "Maximum size is 'full'",
+      "fix": "Use size=\"lg\" or size=\"full\"",
+      "severity": "error"
+    },
+    {
+      "component": "Popover",
+      "pattern": "placement=\"top-center\"",
+      "reason": "No 'top-center' — center alignment is the default when no suffix is given",
+      "fix": "Use placement=\"top\" for centered placement",
+      "severity": "error"
+    },
+    {
+      "component": "Progress",
+      "pattern": "value > 100",
+      "reason": "Value is clamped to 0–100",
+      "fix": "Normalize your value to 0–100 range before passing",
+      "severity": "error"
+    },
+    {
+      "component": "Select",
+      "pattern": "Passing strings directly as children",
+      "reason": "Select uses options prop, not children",
+      "fix": "Pass options={[{ value: 'a', label: 'Option A' }]}",
+      "severity": "error"
+    },
+    {
+      "component": "Toast",
+      "pattern": "Rendering <Toast> directly in JSX",
+      "reason": "Toast is triggered via the useToast hook, not rendered directly",
+      "fix": "Use: const { toast } = useToast(); then toast({ title, variant })",
+      "severity": "error"
+    },
+    {
+      "component": "Toast",
+      "pattern": "variant=\"error\"",
+      "reason": "No 'error' variant",
+      "fix": "Use variant=\"danger\"",
+      "severity": "error"
+    },
+    {
+      "component": "Toast",
+      "pattern": "variant=\"info\"",
+      "reason": "No 'info' variant on Toast",
+      "fix": "Use variant=\"default\"",
+      "severity": "error"
+    },
+    {
+      "component": "Tooltip",
+      "pattern": "Using Tooltip for rich content (forms, buttons, etc.)",
+      "reason": "Tooltip is for short text labels only",
+      "fix": "Use Popover for rich interactive content",
+      "severity": "error"
+    },
+    {
+      "component": "Typography",
+      "pattern": "Using raw <h1>, <p> tags instead of Typography components",
+      "reason": "Typography components apply the correct token-based styles",
+      "fix": "Use <Heading>, <Text>, <Lead> from @usevyre/react",
+      "severity": "error"
+    }
+  ]
+}

package/dist/cheat-sheets/accordion.md

@@ -0,0 +1,25 @@
+# Accordion — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Vertically stacked collapsible sections. Compose with AccordionItem, AccordionTrigger, AccordionContent.**
+
+```ts
+import { Accordion, AccordionItem, AccordionTrigger, AccordionContent } from "@usevyre/react"
+```
+
+## Common AI Mistakes
+
+- ❌ `Accordion without AccordionItem`
+  → Always compose: Accordion > AccordionItem > AccordionTrigger + AccordionContent
+
+## Examples
+
+**Basic accordion**
+```tsx
+<Accordion>
+  <AccordionItem value="item-1">
+    <AccordionTrigger>Section Title</AccordionTrigger>
+    <AccordionContent>Content goes here.</AccordionContent>
+  </AccordionItem>
+</Accordion>
+```

package/dist/cheat-sheets/alert.md

@@ -0,0 +1,35 @@
+# Alert — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Inline feedback message for info, success, warning, or danger states.**
+
+```ts
+import { Alert } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `variant` | `"info"` \| `"success"` \| `"warning"` \| `"danger"` | `info` |
+
+## Common AI Mistakes
+
+- ❌ `variant="error"`
+  → Use variant="danger"
+- ❌ `variant="primary"`
+  → Use variant="info" | "success" | "warning" | "danger"
+
+## Examples
+
+**Warning with close button**
+```tsx
+<Alert variant="warning" title="Heads up" onClose={() => setOpen(false)}>
+  This action cannot be undone.
+</Alert>
+```
+
+**Success state**
+```tsx
+<Alert variant="success" title="Saved!">Your changes have been saved.</Alert>
+```

package/dist/cheat-sheets/avatar.md

@@ -0,0 +1,34 @@
+# Avatar — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**User profile image with fallback initials or icon.**
+
+```ts
+import { Avatar } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `size` | `"sm"` \| `"md"` \| `"lg"` \| `"xl"` | `md` |
+| `status` | `"online"` \| `"offline"` \| `"busy"` \| `"away"` | — |
+
+## Common AI Mistakes
+
+- ❌ `size="xs"`
+  → Use size="sm"
+- ❌ `size="2xl"`
+  → Use size="xl"
+
+## Examples
+
+**Avatar with image and online status**
+```tsx
+<Avatar src="/user.png" alt="Jane Doe" size="lg" status="online" />
+```
+
+**Fallback initials**
+```tsx
+<Avatar fallback="JD" size="md" />
+```

package/dist/cheat-sheets/badge.md

@@ -0,0 +1,41 @@
+# Badge — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Small label for status, category, or count. Use dot prop for live status indicator.**
+
+```ts
+import { Badge } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `variant` | `"default"` \| `"accent"` \| `"teal"` \| `"success"` \| `"warning"` \| `"danger"` | `default` |
+| `dot` | `true` \| `false` | `false` |
+
+## Common AI Mistakes
+
+- ❌ `variant="primary"`
+  → Use variant="accent" for brand color
+- ❌ `variant="error"`
+  → Use variant="danger"
+- ❌ `variant="info"`
+  → Use variant="teal" for info-like styling
+
+## Examples
+
+**Live status with dot**
+```tsx
+<Badge variant="success" dot>Online</Badge>
+```
+
+**Warning badge**
+```tsx
+<Badge variant="warning">Beta</Badge>
+```
+
+**Danger badge**
+```tsx
+<Badge variant="danger">Error</Badge>
+```

package/dist/cheat-sheets/breadcrumb.md

@@ -0,0 +1,26 @@
+# Breadcrumb — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Navigation trail showing current page location in hierarchy.**
+
+```ts
+import { Breadcrumb, BreadcrumbItem, BreadcrumbLink, BreadcrumbSeparator } from "@usevyre/react"
+```
+
+## Common AI Mistakes
+
+- ❌ `Using plain <a> tags inside Breadcrumb`
+  → Use BreadcrumbItem > BreadcrumbLink for each crumb
+
+## Examples
+
+**Basic breadcrumb**
+```tsx
+<Breadcrumb>
+  <BreadcrumbItem><BreadcrumbLink href="/">Home</BreadcrumbLink></BreadcrumbItem>
+  <BreadcrumbSeparator />
+  <BreadcrumbItem><BreadcrumbLink href="/docs">Docs</BreadcrumbLink></BreadcrumbItem>
+  <BreadcrumbSeparator />
+  <BreadcrumbItem aria-current="page">Button</BreadcrumbItem>
+</Breadcrumb>
+```

package/dist/cheat-sheets/button.md

@@ -0,0 +1,63 @@
+# Button — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Triggers actions and navigation. The most commonly used interactive element.**
+
+```ts
+import { Button } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `variant` | `"primary"` \| `"secondary"` \| `"ghost"` \| `"accent"` \| `"teal"` \| `"danger"` | `secondary` |
+| `size` | `"sm"` \| `"md"` \| `"lg"` \| `"icon"` | `md` |
+| `loading` | `true` \| `false` | `false` |
+| `disabled` | `true` \| `false` | `false` |
+
+## Common AI Mistakes
+
+- ❌ `variant="blue"`
+  → Use variant="accent" for brand amber, or variant="teal" for teal
+- ❌ `size="xl"`
+  → Use size="lg"
+- ❌ `color="..."`
+  → Use variant prop instead
+- ❌ `icon={...}`
+  → Use leftIcon={...} or rightIcon={...}
+- ❌ `size="icon" without aria-label`
+  → Add aria-label describing the action
+
+## Examples
+
+**Primary CTA**
+```tsx
+<Button variant="primary">Get Started</Button>
+```
+
+**Large accent button**
+```tsx
+<Button variant="accent" size="lg">Launch App</Button>
+```
+
+**Loading state**
+```tsx
+<Button variant="danger" loading>Deleting...</Button>
+```
+
+**Link button**
+```tsx
+<Button as="a" href="/docs" variant="secondary">Read Docs</Button>
+```
+
+**Icon-only button**
+```tsx
+<Button variant="ghost" size="icon" aria-label="Close">
+  <X size={16} />
+</Button>
+```
+
+## Accessibility
+
+- Always add aria-label when using size='icon' (no visible text)

package/dist/cheat-sheets/calendar.md

@@ -0,0 +1,27 @@
+# Calendar — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Date picker calendar widget for selecting single dates or ranges.**
+
+```ts
+import { Calendar } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `disabled` | `true` \| `false` | `false` |
+
+## Common AI Mistakes
+
+- ❌ `Using Calendar for time selection`
+  → Combine with a separate time Input if time selection is needed
+
+## Examples
+
+**Controlled date picker**
+```tsx
+const [date, setDate] = useState(null);
+<Calendar value={date} onChange={setDate} />
+```

package/dist/cheat-sheets/card.md

@@ -0,0 +1,37 @@
+# Card — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Content container with optional header, body, and footer sections.**
+
+```ts
+import { Card, CardHeader, CardBody, CardFooter } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `variant` | `"default"` \| `"elevated"` \| `"outlined"` \| `"ghost"` \| `"accent"` | `default` |
+| `hoverable` | `true` \| `false` | `false` |
+| `clickable` | `true` \| `false` | `false` |
+
+## Common AI Mistakes
+
+- ❌ `variant="primary"`
+  → Use variant="elevated" | "outlined" | "ghost" | "accent"
+
+## Examples
+
+**Elevated card with sections**
+```tsx
+<Card variant="elevated">
+  <CardHeader><Badge variant="teal">New</Badge></CardHeader>
+  <CardBody>
+    <h3>Card Title</h3>
+    <p>Description text.</p>
+  </CardBody>
+  <CardFooter>
+    <Button variant="ghost" size="sm">Learn more</Button>
+  </CardFooter>
+</Card>
+```

package/dist/cheat-sheets/checkbox.md

@@ -0,0 +1,32 @@
+# Checkbox — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Binary toggle for boolean form values.**
+
+```ts
+import { Checkbox } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `size` | `"sm"` \| `"md"` | `md` |
+| `checked` | `true` \| `false` | — |
+| `disabled` | `true` \| `false` | `false` |
+| `indeterminate` | `true` \| `false` | `false` |
+
+## Common AI Mistakes
+
+- ❌ `size="lg"`
+  → Use size="md"
+
+## Examples
+
+**Labeled checkbox**
+```tsx
+<label style={{ display: 'flex', alignItems: 'center', gap: 'var(--vyre-spacing-2)' }}>
+  <Checkbox checked={agreed} onChange={e => setAgreed(e.target.checked)} />
+  I agree to the terms
+</label>
+```

package/dist/cheat-sheets/command.md

@@ -0,0 +1,29 @@
+# Command — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Command palette / search dialog. Use for search-first navigation or quick actions.**
+
+```ts
+import { Command, CommandInput, CommandList, CommandEmpty, CommandGroup, CommandItem, CommandDialog } from "@usevyre/react"
+```
+
+## Common AI Mistakes
+
+- ❌ `Using Input type="search" for search UI`
+  → Use Command + CommandInput + CommandList + CommandItem
+
+## Examples
+
+**Basic command palette**
+```tsx
+<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>
+```

package/dist/cheat-sheets/dropdownmenu.md

@@ -0,0 +1,25 @@
+# DropdownMenu — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Contextual menu triggered by a button. Supports items, separators, checkbox items, radio groups, and sub-menus.**
+
+```ts
+import { DropdownMenu, DropdownItem, DropdownSeparator, DropdownCheckboxItem, DropdownRadioGroup, DropdownRadioItem, DropdownSub } from "@usevyre/react"
+```
+
+## Common AI Mistakes
+
+- ❌ `DropdownItem variant="primary"`
+  → Use variant="danger" for destructive items only
+
+## Examples
+
+**Dropdown with danger item**
+```tsx
+<DropdownMenu trigger={<Button variant="secondary">Options</Button>}>
+  <DropdownItem onSelect={() => handleEdit()}>Edit</DropdownItem>
+  <DropdownItem onSelect={() => handleDuplicate()}>Duplicate</DropdownItem>
+  <DropdownSeparator />
+  <DropdownItem variant="danger" onSelect={() => handleDelete()}>Delete</DropdownItem>
+</DropdownMenu>
+```

package/dist/cheat-sheets/field.md

@@ -0,0 +1,36 @@
+# Field — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Form field wrapper providing label, hint text, and validation state for Input or Textarea.**
+
+```ts
+import { Field, Input, Textarea } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `state` | `"idle"` \| `"error"` \| `"success"` \| `"warning"` | `idle` |
+| `required` | `true` \| `false` | `false` |
+
+## Common AI Mistakes
+
+- ❌ `Applying state prop directly to Input`
+  → Wrap Input in <Field state="error"> to apply validation styling
+
+## Examples
+
+**Error state field**
+```tsx
+<Field label="Email" state="error" hint="Invalid email format">
+  <Input type="email" placeholder="you@example.com" />
+</Field>
+```
+
+**Search field with left icon**
+```tsx
+<Field label="Search">
+  <Input leftElement={<SearchIcon />} placeholder="Search..." />
+</Field>
+```

package/dist/cheat-sheets/index.md

@@ -0,0 +1,34 @@
+# useVyre Component Cheat Sheets
+
+Quick reference for AI agents — one file per component.
+
+- [Accordion](accordion.md) — Vertically stacked collapsible sections. Compose with AccordionItem, AccordionTrigger, AccordionContent.
+- [Alert](alert.md) — Inline feedback message for info, success, warning, or danger states.
+- [Avatar](avatar.md) — User profile image with fallback initials or icon.
+- [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.
+- [Card](card.md) — Content container with optional header, body, and footer sections.
+- [Checkbox](checkbox.md) — Binary toggle for boolean form values.
+- [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.
+- [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.
+- [Pagination](pagination.md) — Page navigation for paginated lists or tables.
+- [Popover](popover.md) — Floating content panel anchored to a trigger element. For simple labels use Tooltip instead.
+- [Progress](progress.md) — Visual progress indicator for tasks, uploads, or completion status.
+- [Select](select.md) — Dropdown for selecting one option from a list.
+- [Separator](separator.md) — Horizontal or vertical divider line.
+- [Sheet](sheet.md) — Side panel (drawer) that slides in from the edge. For forms, detail views, or settings.
+- [Sidebar](sidebar.md) — App navigation sidebar. Use AppLayout as the root layout wrapper.
+- [Skeleton](skeleton.md) — Loading placeholder that mimics the shape of content while data loads.
+- [Slider](slider.md) — Range input for selecting a numeric value within a range.
+- [Switch](switch.md) — Toggle switch for boolean on/off settings.
+- [Table](table.md) — Data table with optional sorting. Compose with TableHeader, TableRow, TableCell.
+- [Tabs](tabs.md) — Tabbed navigation for switching between content panels.
+- [Toast](toast.md) — Transient notification. Use the useToast hook to trigger toasts imperatively.
+- [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.