@usevyre/ai-context 1.2.1 → 1.3.0

package/dist/anti-patterns.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.2.0",
+  "version": "1.6.0",
   "rules": [
     {
       "component": "Accordion",
@@ -22,6 +22,27 @@
       "fix": "Use variant=\"info\" | \"success\" | \"warning\" | \"danger\"",
       "severity": "error"
     },
+    {
+      "component": "AlertDialog",
+      "pattern": "AlertDialog without open/onOpenChange (React) or v-model (Vue)",
+      "reason": "It is controlled; it never shows/closes without state",
+      "fix": "Drive open from state; close in onOpenChange / via v-model",
+      "severity": "error"
+    },
+    {
+      "component": "AlertDialog",
+      "pattern": "Using Alert (inline banner) for a confirm/cancel decision",
+      "reason": "Alert is non-blocking inline feedback, has no confirm flow",
+      "fix": "Use AlertDialog for blocking confirmation; Alert for passive messages",
+      "severity": "error"
+    },
+    {
+      "component": "AlertDialog",
+      "pattern": "variant=\"success\" or \"error\"",
+      "reason": "AlertDialog variant is \"danger\" | \"warning\" | \"info\" only",
+      "fix": "Use \"danger\" for destructive, \"warning\" to caution, \"info\" otherwise",
+      "severity": "error"
+    },
     {
       "component": "Avatar",
       "pattern": "size=\"xs\"",
@@ -99,6 +120,13 @@
       "fix": "Add aria-label describing the action",
       "severity": "error"
     },
+    {
+      "component": "Button",
+      "pattern": "padding / margin / marginTop (any spacing prop) on a useVyre component",
+      "reason": "Components have NO spacing props by design — internal spacing is fixed by tokens for visual consistency",
+      "fix": "Space BETWEEN components with <Stack gap> / <Grid gap>; space AROUND a block with <Box padding/margin> wrapping it",
+      "severity": "error"
+    },
     {
       "component": "Calendar",
       "pattern": "Calendar for an input field that opens a popover",
@@ -134,6 +162,13 @@
       "fix": "Use variant=\"elevated\" | \"outlined\" | \"ghost\" | \"accent\"",
       "severity": "error"
     },
+    {
+      "component": "Card",
+      "pattern": "padding / margin / marginTop (any spacing prop) on a useVyre component",
+      "reason": "Components have NO spacing props by design — internal spacing is fixed by tokens for visual consistency",
+      "fix": "Space BETWEEN components with <Stack gap> / <Grid gap>; space AROUND a block with <Box padding/margin> wrapping it",
+      "severity": "error"
+    },
     {
       "component": "Checkbox",
       "pattern": "size=\"lg\"",
@@ -232,6 +267,13 @@
       "fix": "Use v-model on <Input>/<Textarea> in Vue; in React use value + onChange",
       "severity": "error"
     },
+    {
+      "component": "Input",
+      "pattern": "padding / margin / marginTop (any spacing prop) on a useVyre component",
+      "reason": "Components have NO spacing props by design — internal spacing is fixed by tokens for visual consistency",
+      "fix": "Space BETWEEN components with <Stack gap> / <Grid gap>; space AROUND a block with <Box padding/margin> wrapping it",
+      "severity": "error"
+    },
     {
       "component": "Modal",
       "pattern": "size=\"xl\"",
@@ -484,6 +526,90 @@
       "fix": "Handle onSend(text, files) — map files to message attachments and append",
       "severity": "error"
     },
+    {
+      "component": "Stack",
+      "pattern": "<div style={{ display: 'flex', gap: 12 }}>",
+      "reason": "Inline flex styles bypass the design system and use magic-number spacing",
+      "fix": "Use <Stack gap=\"md\"> — gap is a token",
+      "severity": "error"
+    },
+    {
+      "component": "Stack",
+      "pattern": "gap={12} or gap=\"12px\"",
+      "reason": "Stack gap is a closed token enum",
+      "fix": "Use gap=\"none|xs|sm|md|lg|xl|2xl\"",
+      "severity": "error"
+    },
+    {
+      "component": "Stack",
+      "pattern": "direction=\"vertical\" / \"horizontal\"",
+      "reason": "Stack mirrors CSS flex-direction names",
+      "fix": "Use direction=\"row\" or \"column\" (also row-reverse / column-reverse)",
+      "severity": "error"
+    },
+    {
+      "component": "Stack",
+      "pattern": "style={{ width: \"100%\" }} / style={{ height: 320 }}",
+      "reason": "Inline width/height bypass the design system and use magic numbers",
+      "fix": "Use the width / height prop: width=\"full\", width=\"md\", height=\"screen\", etc.",
+      "severity": "error"
+    },
+    {
+      "component": "Grid",
+      "pattern": "<div style={{ display:'grid', gridTemplateColumns:'1fr 1fr 1fr' }}>",
+      "reason": "Inline grid styles bypass the design system",
+      "fix": "Use <Grid columns={3} gap=\"md\">",
+      "severity": "error"
+    },
+    {
+      "component": "Grid",
+      "pattern": "columns=\"3\" (string)",
+      "reason": "columns is a number or the literal 'auto-fit'",
+      "fix": "Use columns={3} or columns=\"auto-fit\"",
+      "severity": "error"
+    },
+    {
+      "component": "Grid",
+      "pattern": "Nested div with inline grid-column for spanning",
+      "reason": "Spanning has a dedicated primitive",
+      "fix": "Wrap the cell in <GridItem colSpan={2}>",
+      "severity": "error"
+    },
+    {
+      "component": "Grid",
+      "pattern": "style={{ width: \"100%\" }} / style={{ height: 320 }}",
+      "reason": "Inline width/height bypass the design system and use magic numbers",
+      "fix": "Use the width / height prop: width=\"full\", width=\"md\", height=\"screen\", etc.",
+      "severity": "error"
+    },
+    {
+      "component": "GridItem",
+      "pattern": "GridItem outside a Grid",
+      "reason": "GridItem only has effect as a direct child of Grid",
+      "fix": "Place <GridItem> directly inside <Grid>",
+      "severity": "error"
+    },
+    {
+      "component": "Box",
+      "pattern": "<Box style={{ padding: 16 }}>",
+      "reason": "padding is a token prop; style is a last resort",
+      "fix": "Use <Box padding=\"md\"> (or paddingX/paddingTop/...)",
+      "severity": "error"
+    },
+    {
+      "component": "Box",
+      "pattern": "Using Box for flex/grid layout",
+      "reason": "Box is spacing-only and has no layout props",
+      "fix": "Use <Stack> or <Grid>",
+      "severity": "error"
+    },
+    {
+      "component": "Box",
+      "pattern": "style={{ width: \"100%\" }} / style={{ height: 320 }}",
+      "reason": "Inline width/height bypass the design system and use magic numbers",
+      "fix": "Use the width / height prop: width=\"full\", width=\"md\", height=\"screen\", etc.",
+      "severity": "error"
+    },
     {
       "component": "DateRangePicker",
       "pattern": "value={[from, to]}",

package/dist/cheat-sheets/alertdialog.md

@@ -0,0 +1,41 @@
+# AlertDialog — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Blocking confirmation modal (focus-trapped). Controlled via open + onOpenChange (React) / v-model (Vue). Use for destructive or irreversible actions that need explicit confirm/cancel. For non-blocking inline feedback use Alert; for general dialogs use Modal.**
+
+```ts
+import { AlertDialog } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `variant` | `"danger"` \| `"warning"` \| `"info"` | `info` |
+| `open` | `true` \| `false` | — |
+
+## Common AI Mistakes
+
+- ❌ `AlertDialog without open/onOpenChange (React) or v-model (Vue)`
+  → Drive open from state; close in onOpenChange / via v-model
+- ❌ `Using Alert (inline banner) for a confirm/cancel decision`
+  → Use AlertDialog for blocking confirmation; Alert for passive messages
+- ❌ `variant="success" or "error"`
+  → Use "danger" for destructive, "warning" to caution, "info" otherwise
+
+## Examples
+
+**Destructive confirmation**
+```tsx
+const [open, setOpen] = useState(false);
+<Button variant="danger" onClick={() => setOpen(true)}>Delete</Button>
+<AlertDialog
+  open={open}
+  onOpenChange={setOpen}
+  variant="danger"
+  title="Delete project?"
+  description="This cannot be undone."
+  confirmLabel="Delete"
+  onConfirm={() => deleteProject()}
+/>
+```

package/dist/cheat-sheets/box.md

@@ -0,0 +1,52 @@
+# Box — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Spacing-only container plus a controlled escape hatch. Token padding/margin with shorthand, per-axis (X/Y) and per-side (Top/Right/Bottom/Left) overrides. The `style` prop is an explicit anti-pattern escape hatch. Renders a plain <div> (or `as`).**
+
+```ts
+import { Box } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `padding` | `"none"` \| `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"` \| `"2xl"` | — |
+| `paddingX` | `"none"` \| `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"` \| `"2xl"` | — |
+| `paddingY` | `"none"` \| `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"` \| `"2xl"` | — |
+| `paddingTop` | `"none"` \| `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"` \| `"2xl"` | — |
+| `paddingRight` | `"none"` \| `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"` \| `"2xl"` | — |
+| `paddingBottom` | `"none"` \| `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"` \| `"2xl"` | — |
+| `paddingLeft` | `"none"` \| `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"` \| `"2xl"` | — |
+| `margin` | `"none"` \| `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"` \| `"2xl"` | — |
+| `marginX` | `"none"` \| `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"` \| `"2xl"` | — |
+| `marginY` | `"none"` \| `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"` \| `"2xl"` | — |
+| `marginTop` | `"none"` \| `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"` \| `"2xl"` | — |
+| `marginRight` | `"none"` \| `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"` \| `"2xl"` | — |
+| `marginBottom` | `"none"` \| `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"` \| `"2xl"` | — |
+| `marginLeft` | `"none"` \| `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"` \| `"2xl"` | — |
+| `width` | `"auto"` \| `"full"` \| `"fit"` \| `"screen"` \| `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"` \| `"2xl"` | — |
+| `height` | `"auto"` \| `"full"` \| `"fit"` \| `"screen"` \| `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"` \| `"2xl"` | — |
+
+## Common AI Mistakes
+
+- ❌ `<Box style={{ padding: 16 }}>`
+  → Use <Box padding="md"> (or paddingX/paddingTop/...)
+- ❌ `Using Box for flex/grid layout`
+  → Use <Stack> or <Grid>
+- ❌ `style={{ width: "100%" }} / style={{ height: 320 }}`
+  → Use the width / height prop: width="full", width="md", height="screen", etc.
+
+## Examples
+
+**Asymmetric padding**
+```tsx
+<Box as="section" paddingX="lg" paddingY="md">
+  <Heading>Settings</Heading>
+</Box>
+```
+
+**Vertical rhythm via margin-top**
+```tsx
+<Box marginTop="xl"><Separator /></Box>
+```

package/dist/cheat-sheets/button.md

@@ -28,6 +28,8 @@ import { Button } from "@usevyre/react"
   → Use leftIcon={...} or rightIcon={...}
 - ❌ `size="icon" without aria-label`
   → Add aria-label describing the action
+- ❌ `padding / margin / marginTop (any spacing prop) on a useVyre component`
+  → Space BETWEEN components with <Stack gap> / <Grid gap>; space AROUND a block with <Box padding/margin> wrapping it
 
 ## Examples
 

package/dist/cheat-sheets/card.md

@@ -19,6 +19,8 @@ import { Card, CardHeader, CardBody, CardFooter } from "@usevyre/react"
 
 - ❌ `variant="primary"`
   → Use variant="elevated" | "outlined" | "ghost" | "accent"
+- ❌ `padding / margin / marginTop (any spacing prop) on a useVyre component`
+  → Space BETWEEN components with <Stack gap> / <Grid gap>; space AROUND a block with <Box padding/margin> wrapping it
 
 ## Examples
 

package/dist/cheat-sheets/grid.md

@@ -0,0 +1,50 @@
+# Grid — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Two-dimensional CSS grid primitive. Explicit column/row counts (or auto-fit), auto-flow control, token gap. Pair with GridItem for cell spanning/placement. Renders a plain <div> (or `as`).**
+
+```ts
+import { Grid, GridItem } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `flow` | `"row"` \| `"column"` \| `"dense"` \| `"row-dense"` \| `"column-dense"` | — |
+| `gap` | `"none"` \| `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"` \| `"2xl"` | `md` |
+| `rowGap` | `"none"` \| `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"` \| `"2xl"` | — |
+| `columnGap` | `"none"` \| `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"` \| `"2xl"` | — |
+| `align` | `"start"` \| `"center"` \| `"end"` \| `"stretch"` | `stretch` |
+| `justify` | `"start"` \| `"center"` \| `"end"` \| `"stretch"` | — |
+| `width` | `"auto"` \| `"full"` \| `"fit"` \| `"screen"` \| `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"` \| `"2xl"` | — |
+| `height` | `"auto"` \| `"full"` \| `"fit"` \| `"screen"` \| `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"` \| `"2xl"` | — |
+
+## Common AI Mistakes
+
+- ❌ `<div style={{ display:'grid', gridTemplateColumns:'1fr 1fr 1fr' }}>`
+  → Use <Grid columns={3} gap="md">
+- ❌ `columns="3" (string)`
+  → Use columns={3} or columns="auto-fit"
+- ❌ `Nested div with inline grid-column for spanning`
+  → Wrap the cell in <GridItem colSpan={2}>
+- ❌ `style={{ width: "100%" }} / style={{ height: 320 }}`
+  → Use the width / height prop: width="full", width="md", height="screen", etc.
+
+## Examples
+
+**Three-column grid with a wide first cell**
+```tsx
+<Grid columns={3} gap="lg">
+  <GridItem colSpan={2}><Card>Wide</Card></GridItem>
+  <Card>Two</Card>
+  <Card>Three</Card>
+</Grid>
+```
+
+**Responsive auto-fit grid**
+```tsx
+<Grid columns="auto-fit" gap="md">
+  {items.map((i) => <Card key={i.id}>{i.title}</Card>)}
+</Grid>
+```

package/dist/cheat-sheets/griditem.md

@@ -0,0 +1,24 @@
+# GridItem — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Child placement inside <Grid>. Sets column/row span and start lines. Renders a plain <div> (or `as`).**
+
+```ts
+import { GridItem } from "@usevyre/react"
+```
+
+## Common AI Mistakes
+
+- ❌ `GridItem outside a Grid`
+  → Place <GridItem> directly inside <Grid>
+
+## Examples
+
+**Span two columns**
+```tsx
+<Grid columns={4} gap="md">
+  <GridItem colSpan={2}>Featured</GridItem>
+  <div>a</div>
+  <div>b</div>
+</Grid>
+```

package/dist/cheat-sheets/index.md

@@ -4,6 +4,7 @@ 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.
+- [AlertDialog](alertdialog.md) — Blocking confirmation modal (focus-trapped). Controlled via open + onOpenChange (React) / v-model (Vue). Use for destructive or irreversible actions that need explicit confirm/cancel. For non-blocking inline feedback use Alert; for general dialogs use Modal.
 - [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.
@@ -44,4 +45,8 @@ Quick reference for AI agents — one file per component.
 - [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.
+- [Stack](stack.md) — Full one-dimensional flex layout primitive. USE INSTEAD OF <div style={{display:'flex'}}>. Covers the whole CSS flexbox surface (direction incl. reverse, wrap, align/justify/alignContent/alignSelf, grow/shrink/basis, per-axis gap) with token-locked spacing. Renders a plain <div> (or `as`).
+- [Grid](grid.md) — Two-dimensional CSS grid primitive. Explicit column/row counts (or auto-fit), auto-flow control, token gap. Pair with GridItem for cell spanning/placement. Renders a plain <div> (or `as`).
+- [GridItem](griditem.md) — Child placement inside <Grid>. Sets column/row span and start lines. Renders a plain <div> (or `as`).
+- [Box](box.md) — Spacing-only container plus a controlled escape hatch. Token padding/margin with shorthand, per-axis (X/Y) and per-side (Top/Right/Bottom/Left) overrides. The `style` prop is an explicit anti-pattern escape hatch. Renders a plain <div> (or `as`).
 - [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

@@ -21,6 +21,8 @@ import { Input } from "@usevyre/react"
   → 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
+- ❌ `padding / margin / marginTop (any spacing prop) on a useVyre component`
+  → Space BETWEEN components with <Stack gap> / <Grid gap>; space AROUND a block with <Box padding/margin> wrapping it
 
 ## Examples
 

package/dist/cheat-sheets/stack.md

@@ -0,0 +1,55 @@
+# Stack — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Full one-dimensional flex layout primitive. USE INSTEAD OF <div style={{display:'flex'}}>. Covers the whole CSS flexbox surface (direction incl. reverse, wrap, align/justify/alignContent/alignSelf, grow/shrink/basis, per-axis gap) with token-locked spacing. Renders a plain <div> (or `as`).**
+
+```ts
+import { Stack } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `direction` | `"row"` \| `"column"` \| `"row-reverse"` \| `"column-reverse"` | `row` |
+| `gap` | `"none"` \| `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"` \| `"2xl"` | `md` |
+| `rowGap` | `"none"` \| `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"` \| `"2xl"` | — |
+| `columnGap` | `"none"` \| `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"` \| `"2xl"` | — |
+| `align` | `"start"` \| `"center"` \| `"end"` \| `"stretch"` \| `"baseline"` | `stretch` |
+| `justify` | `"start"` \| `"center"` \| `"end"` \| `"between"` \| `"around"` \| `"evenly"` | `start` |
+| `alignContent` | `"start"` \| `"center"` \| `"end"` \| `"stretch"` \| `"between"` \| `"around"` \| `"evenly"` | — |
+| `alignSelf` | `"auto"` \| `"start"` \| `"center"` \| `"end"` \| `"stretch"` \| `"baseline"` | — |
+| `wrap` | `"nowrap"` \| `"wrap"` \| `"wrap-reverse"` | `nowrap` |
+| `basis` | `"none"` \| `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"` \| `"2xl"` \| `"auto"` \| `"content"` \| `"0"` | — |
+| `width` | `"auto"` \| `"full"` \| `"fit"` \| `"screen"` \| `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"` \| `"2xl"` | — |
+| `height` | `"auto"` \| `"full"` \| `"fit"` \| `"screen"` \| `"xs"` \| `"sm"` \| `"md"` \| `"lg"` \| `"xl"` \| `"2xl"` | — |
+| `inline` | `true` \| `false` | `false` |
+
+## Common AI Mistakes
+
+- ❌ `<div style={{ display: 'flex', gap: 12 }}>`
+  → Use <Stack gap="md"> — gap is a token
+- ❌ `gap={12} or gap="12px"`
+  → Use gap="none|xs|sm|md|lg|xl|2xl"
+- ❌ `direction="vertical" / "horizontal"`
+  → Use direction="row" or "column" (also row-reverse / column-reverse)
+- ❌ `style={{ width: "100%" }} / style={{ height: 320 }}`
+  → Use the width / height prop: width="full", width="md", height="screen", etc.
+
+## Examples
+
+**Row, vertically centered, spaced apart**
+```tsx
+<Stack direction="row" gap="md" align="center" justify="between">
+  <Avatar src={user.avatar} />
+  <Text>{user.name}</Text>
+  <Button>Edit</Button>
+</Stack>
+```
+
+**Wrapping grid-ish gallery with per-axis gap**
+```tsx
+<Stack wrap="wrap" rowGap="lg" columnGap="md">
+  {tags.map((t) => <Tag key={t}>{t}</Tag>)}
+</Stack>
+```