@usevyre/ai-context 0.1.0 → 0.2.0

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.

package/dist/cheat-sheets/input.md

@@ -0,0 +1,28 @@
+# Input — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Text input field. Wrap in Field for labels and validation. Use leftElement/rightElement for icons.**
+
+```ts
+import { Input } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `size` | `"sm"` \| `"md"` \| `"lg"` | `md` |
+
+## Common AI Mistakes
+
+- ❌ `size="icon"`
+  → Use size="sm" | "md" | "lg"
+- ❌ `type="search" for search UI`
+  → Import Command from @usevyre/react for search palettes
+
+## Examples
+
+**Password input with icon**
+```tsx
+<Input type="password" rightElement={<EyeIcon />} placeholder="Password" />
+```

package/dist/cheat-sheets/label.md

@@ -0,0 +1,22 @@
+# Label — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Accessible form label. Associate with input via htmlFor.**
+
+```ts
+import { Label } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `required` | `true` \| `false` | `false` |
+
+## Examples
+
+**Label with input**
+```tsx
+<Label htmlFor="email">Email address</Label>
+<Input id="email" type="email" />
+```

package/dist/cheat-sheets/modal.md

@@ -0,0 +1,33 @@
+# Modal — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Dialog overlay for confirmations, forms, or focused content.**
+
+```ts
+import { Modal, ModalHeader, ModalBody, ModalFooter } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `size` | `"sm"` \| `"md"` \| `"lg"` \| `"full"` | `md` |
+| `open` | `true` \| `false` | — |
+
+## Common AI Mistakes
+
+- ❌ `size="xl"`
+  → Use size="lg" or size="full"
+
+## Examples
+
+**Confirmation modal**
+```tsx
+<Modal open={isOpen} onClose={() => setIsOpen(false)} title="Confirm Delete" size="sm">
+  <ModalBody>Are you sure you want to delete this item?</ModalBody>
+  <ModalFooter>
+    <Button variant="ghost" onClick={() => setIsOpen(false)}>Cancel</Button>
+    <Button variant="danger" onClick={handleDelete}>Delete</Button>
+  </ModalFooter>
+</Modal>
+```

package/dist/cheat-sheets/pagination.md

@@ -0,0 +1,15 @@
+# Pagination — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Page navigation for paginated lists or tables.**
+
+```ts
+import { Pagination } from "@usevyre/react"
+```
+
+## Examples
+
+**Basic pagination**
+```tsx
+<Pagination page={currentPage} total={totalPages} onChange={setCurrentPage} />
+```

package/dist/cheat-sheets/popover.md

@@ -0,0 +1,32 @@
+# Popover — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Floating content panel anchored to a trigger element. For simple labels use Tooltip instead.**
+
+```ts
+import { Popover } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `placement` | `"top"` \| `"top-start"` \| `"top-end"` \| `"bottom"` \| `"bottom-start"` \| `"bottom-end"` \| `"left"` \| `"left-start"` \| `"left-end"` \| `"right"` \| `"right-start"` \| `"right-end"` | `bottom` |
+| `open` | `true` \| `false` | — |
+| `closeOnOutside` | `true` \| `false` | `true` |
+
+## Common AI Mistakes
+
+- ❌ `placement="top-center"`
+  → Use placement="top" for centered placement
+
+## Examples
+
+**Popover with custom content**
+```tsx
+<Popover trigger={<Button variant="secondary">More info</Button>} placement="bottom-start">
+  <div style={{ padding: 'var(--vyre-spacing-4)' }}>
+    <p>Detailed information here.</p>
+  </div>
+</Popover>
+```

package/dist/cheat-sheets/progress.md

@@ -0,0 +1,27 @@
+# Progress — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Visual progress indicator for tasks, uploads, or completion status.**
+
+```ts
+import { Progress } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `size` | `"sm"` \| `"md"` \| `"lg"` | `md` |
+| `variant` | `"default"` \| `"accent"` \| `"teal"` \| `"success"` \| `"danger"` | `default` |
+
+## Common AI Mistakes
+
+- ❌ `value > 100`
+  → Normalize your value to 0–100 range before passing
+
+## Examples
+
+**Upload progress**
+```tsx
+<Progress value={uploadPercent} variant="accent" size="sm" />
+```

package/dist/cheat-sheets/select.md

@@ -0,0 +1,32 @@
+# Select — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Dropdown for selecting one option from a list.**
+
+```ts
+import { Select } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `size` | `"sm"` \| `"md"` \| `"lg"` | `md` |
+| `disabled` | `true` \| `false` | `false` |
+
+## Common AI Mistakes
+
+- ❌ `Passing strings directly as children`
+  → Pass options={[{ value: 'a', label: 'Option A' }]}
+
+## Examples
+
+**Controlled select**
+```tsx
+<Select
+  options={[{ value: 'react', label: 'React' }, { value: 'vue', label: 'Vue' }]}
+  value={framework}
+  onChange={setFramework}
+  placeholder="Choose framework"
+/>
+```

package/dist/cheat-sheets/separator.md

@@ -0,0 +1,26 @@
+# Separator — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Horizontal or vertical divider line.**
+
+```ts
+import { Separator } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `orientation` | `"horizontal"` \| `"vertical"` | `horizontal` |
+
+## Examples
+
+**Horizontal separator**
+```tsx
+<Separator />
+```
+
+**Vertical separator**
+```tsx
+<Separator orientation="vertical" />
+```

package/dist/cheat-sheets/sheet.md

@@ -0,0 +1,28 @@
+# Sheet — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Side panel (drawer) that slides in from the edge. For forms, detail views, or settings.**
+
+```ts
+import { Sheet, SheetHeader, SheetBody, SheetFooter } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `size` | `"sm"` \| `"md"` \| `"lg"` \| `"full"` | `md` |
+| `side` | `"left"` \| `"right"` | `right` |
+| `open` | `true` \| `false` | — |
+
+## Examples
+
+**Settings sheet from the right**
+```tsx
+<Sheet open={isOpen} onClose={() => setIsOpen(false)} title="Settings" side="right">
+  <SheetBody>Settings content here.</SheetBody>
+  <SheetFooter>
+    <Button variant="accent">Save</Button>
+  </SheetFooter>
+</Sheet>
+```

package/dist/cheat-sheets/sidebar.md

@@ -0,0 +1,33 @@
+# Sidebar — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**App navigation sidebar. Use AppLayout as the root layout wrapper.**
+
+```ts
+import { AppLayout, Sidebar, SidebarHeader, SidebarContent, SidebarSection, SidebarItem, SidebarFooter } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `variant` | `"default"` \| `"floating"` | `default` |
+
+## Examples
+
+**App layout with sidebar**
+```tsx
+<AppLayout>
+  <Sidebar>
+    <SidebarHeader>Logo</SidebarHeader>
+    <SidebarContent>
+      <SidebarSection heading="Main">
+        <SidebarItem href="/" active>Dashboard</SidebarItem>
+        <SidebarItem href="/settings">Settings</SidebarItem>
+      </SidebarSection>
+    </SidebarContent>
+    <SidebarFooter><Avatar fallback="JD" size="sm" /></SidebarFooter>
+  </Sidebar>
+  <main>Page content</main>
+</AppLayout>
+```

package/dist/cheat-sheets/skeleton.md

@@ -0,0 +1,27 @@
+# Skeleton — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Loading placeholder that mimics the shape of content while data loads.**
+
+```ts
+import { Skeleton } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `variant` | `"rect"` \| `"circle"` \| `"text"` | `rect` |
+
+## Examples
+
+**Avatar skeleton**
+```tsx
+<Skeleton variant="circle" width={40} height={40} />
+```
+
+**Text line skeletons**
+```tsx
+<Skeleton variant="text" width="100%" />
+<Skeleton variant="text" width="60%" />
+```

package/dist/cheat-sheets/slider.md

@@ -0,0 +1,22 @@
+# Slider — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Range input for selecting a numeric value within a range.**
+
+```ts
+import { Slider } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `size` | `"sm"` \| `"md"` | `md` |
+| `disabled` | `true` \| `false` | `false` |
+
+## Examples
+
+**Volume slider**
+```tsx
+<Slider value={volume} onChange={setVolume} min={0} max={100} step={5} />
+```

package/dist/cheat-sheets/switch.md

@@ -0,0 +1,26 @@
+# Switch — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Toggle switch for boolean on/off settings.**
+
+```ts
+import { Switch } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `size` | `"sm"` \| `"md"` | `md` |
+| `checked` | `true` \| `false` | — |
+| `disabled` | `true` \| `false` | `false` |
+
+## Examples
+
+**Notifications toggle**
+```tsx
+<label style={{ display: 'flex', alignItems: 'center', gap: 'var(--vyre-spacing-2)' }}>
+  <Switch checked={notifications} onChange={setNotifications} />
+  Enable notifications
+</label>
+```

package/dist/cheat-sheets/table.md

@@ -0,0 +1,28 @@
+# Table — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Data table with optional sorting. Compose with TableHeader, TableRow, TableCell.**
+
+```ts
+import { Table, TableHead, TableBody, TableRow, TableHeader, TableCell } from "@usevyre/react"
+```
+
+## Examples
+
+**Basic data table**
+```tsx
+<Table>
+  <TableHead>
+    <TableRow>
+      <TableHeader>Name</TableHeader>
+      <TableHeader>Status</TableHeader>
+    </TableRow>
+  </TableHead>
+  <TableBody>
+    <TableRow>
+      <TableCell>Alice</TableCell>
+      <TableCell><Badge variant="success">Active</Badge></TableCell>
+    </TableRow>
+  </TableBody>
+</Table>
+```

package/dist/cheat-sheets/tabs.md

@@ -0,0 +1,24 @@
+# Tabs — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Tabbed navigation for switching between content panels.**
+
+```ts
+import { Tabs, TabList, Tab, TabPanels, TabPanel } from "@usevyre/react"
+```
+
+## Examples
+
+**Basic tabs**
+```tsx
+<Tabs defaultIndex={0}>
+  <TabList>
+    <Tab>Overview</Tab>
+    <Tab>Settings</Tab>
+  </TabList>
+  <TabPanels>
+    <TabPanel>Overview content</TabPanel>
+    <TabPanel>Settings content</TabPanel>
+  </TabPanels>
+</Tabs>
+```

package/dist/cheat-sheets/toast.md

@@ -0,0 +1,41 @@
+# Toast — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Transient notification. Use the useToast hook to trigger toasts imperatively.**
+
+```ts
+import { useToast, ToastProvider } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `variant` | `"default"` \| `"success"` \| `"warning"` \| `"danger"` | `default` |
+
+## Common AI Mistakes
+
+- ❌ `Rendering <Toast> directly in JSX`
+  → Use: const { toast } = useToast(); then toast({ title, variant })
+- ❌ `variant="error"`
+  → Use variant="danger"
+- ❌ `variant="info"`
+  → Use variant="default"
+
+## Examples
+
+**Trigger a success toast**
+```tsx
+const { toast } = useToast();
+
+<Button onClick={() => toast({ title: 'Saved!', variant: 'success', duration: 3000 })}>
+  Save
+</Button>
+```
+
+**Setup: wrap app with ToastProvider**
+```tsx
+<ToastProvider>
+  <App />
+</ToastProvider>
+```

package/dist/cheat-sheets/tooltip.md

@@ -0,0 +1,30 @@
+# Tooltip — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Short label that appears on hover/focus. For rich content use Popover instead.**
+
+```ts
+import { Tooltip } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `placement` | `"top"` \| `"bottom"` \| `"left"` \| `"right"` | `top` |
+
+## Common AI Mistakes
+
+- ❌ `Using Tooltip for rich content (forms, buttons, etc.)`
+  → Use Popover for rich interactive content
+
+## Examples
+
+**Tooltip on an icon button**
+```tsx
+<Tooltip content="Close dialog" placement="bottom">
+  <Button variant="ghost" size="icon" aria-label="Close">
+    <X size={16} />
+  </Button>
+</Tooltip>
+```

package/dist/cheat-sheets/typography.md

@@ -0,0 +1,22 @@
+# Typography — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Text rendering components with semantic scale. Includes Text, Heading, Lead, Code, Blockquote.**
+
+```ts
+import { Text, Heading, Lead, Code, Blockquote } from "@usevyre/react"
+```
+
+## Common AI Mistakes
+
+- ❌ `Using raw <h1>, <p> tags instead of Typography components`
+  → Use <Heading>, <Text>, <Lead> from @usevyre/react
+
+## Examples
+
+**Page heading and body text**
+```tsx
+<Heading size="2xl" as="h1">Dashboard</Heading>
+<Lead>Welcome back. Here's what's happening today.</Lead>
+<Text size="sm" style={{ color: 'var(--vyre-color-semantic-text-muted)' }}>Last updated 5 minutes ago.</Text>
+```