@usevyre/ai-context 1.3.0 → 1.4.0

package/dist/cheat-sheets/statgroup.md

@@ -0,0 +1,23 @@
+# StatGroup — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Evenly-split row of <Stat> with subtle dividers between items. Each Stat flexes to equal width.**
+
+```ts
+import { Stat, StatGroup } from "@usevyre/react"
+```
+
+## Common AI Mistakes
+
+- ❌ `Putting non-Stat children in StatGroup`
+  → Only place <Stat> elements inside StatGroup
+
+## Examples
+
+**Three KPIs in a row**
+```tsx
+<StatGroup>
+  <Stat label="MRR" value="$9.6k" delta="+5%" trend="up" />
+  <Stat label="Refunds" value="32" delta="+8" trend="down" />
+</StatGroup>
+```

package/dist/cheat-sheets/step.md

@@ -0,0 +1,8 @@
+# Step — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**One step indicator inside <StepperNav>. State (completed/current/upcoming) derives from the Stepper's active index automatically.**
+
+```ts
+import { Stepper, StepperNav, Step, StepPanel } from "@usevyre/react"
+```

package/dist/cheat-sheets/steppanel.md

@@ -0,0 +1,8 @@
+# StepPanel — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Content for one step. Renders its children only when its index equals the Stepper's active step.**
+
+```ts
+import { Stepper, StepperNav, Step, StepPanel } from "@usevyre/react"
+```

package/dist/cheat-sheets/stepper.md

@@ -0,0 +1,59 @@
+# Stepper — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Multi-step flow indicator + controller (onboarding/checkout/wizard). CONTROLLED by a 0-based index. Compose StepperNav (with Step indicators) and StepPanel (content shown when its index == active). Step/StepPanel take an explicit 0-based `index`. Not Tabs — Stepper is an ORDERED linear flow with completed/current/upcoming states.**
+
+```ts
+import { Stepper, StepperNav, Step, StepPanel } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `orientation` | `"horizontal"` \| `"vertical"` | `horizontal` |
+| `clickable` | `true` \| `false` | `false` |
+
+## Common AI Mistakes
+
+- ❌ `Using Tabs for a wizard / checkout flow`
+  → Use <Stepper> with StepperNav + Step + StepPanel
+- ❌ `onChange={(e) => set(e.target.value)}`
+  → onChange={(index) => setStep(index)}
+- ❌ `Manually toggling which panel is visible`
+  → Give each StepPanel an index; Stepper shows the active one
+- ❌ `<Step> or <StepPanel> outside <Stepper>`
+  → Nest Step inside StepperNav, StepPanel inside Stepper
+
+## Examples
+
+**Three-step wizard with Back/Next**
+```tsx
+const [step, setStep] = useState(0);
+
+<Stepper value={step} onChange={setStep}>
+  <StepperNav>
+    <Step index={0} label="Account" />
+    <Step index={1} label="Profile" />
+    <Step index={2} label="Done" />
+  </StepperNav>
+  <StepPanel index={0}><AccountForm /></StepPanel>
+  <StepPanel index={1}><ProfileForm /></StepPanel>
+  <StepPanel index={2}><Summary /></StepPanel>
+  <Stack direction="row" gap="sm" justify="between">
+    <Button onClick={() => setStep((s) => s - 1)} disabled={step === 0}>Back</Button>
+    <Button variant="primary" onClick={() => setStep((s) => s + 1)}>Next</Button>
+  </Stack>
+</Stepper>
+```
+
+**Vertical with descriptions**
+```tsx
+<Stepper orientation="vertical" defaultValue={1}>
+  <StepperNav>
+    <Step index={0} label="Cart" description="2 items" />
+    <Step index={1} label="Shipping" description="Enter address" />
+    <Step index={2} label="Payment" />
+  </StepperNav>
+</Stepper>
+```

package/dist/cheat-sheets/steppernav.md

@@ -0,0 +1,8 @@
+# StepperNav — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Container for Step indicators inside <Stepper>. Lays them out per the Stepper's orientation.**
+
+```ts
+import { Stepper, StepperNav, Step, StepPanel } from "@usevyre/react"
+```

package/dist/cheat-sheets/timeline.md

@@ -0,0 +1,40 @@
+# Timeline — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Vertical activity feed for audit logs and history. Presentational — a status dot per item plus a connector line. Pass `items` for plain logs, or TimelineItem children for rich per-item content. Timeline does NOT reorder; pass items in the order you want shown.**
+
+```ts
+import { Timeline, TimelineItem } from "@usevyre/react"
+```
+
+## Common AI Mistakes
+
+- ❌ `Building an activity log with a <ul> + manual dots/lines`
+  → Use <Timeline items={[...]} /> or TimelineItem children
+- ❌ `Using Stepper for a history/audit feed`
+  → Use <Timeline> for logs/history; Stepper for wizards
+- ❌ `Expecting Timeline to sort by time`
+  → Sort the array yourself (newest- or oldest-first)
+
+## Examples
+
+**Plain audit log via items**
+```tsx
+<Timeline
+  items={[
+    { title: "Deployed v2.1", time: "2m ago", status: "success" },
+    { title: "Build started", time: "5m ago", status: "info" },
+    { title: "Push to main", time: "6m ago" },
+  ]}
+/>
+```
+
+**Rich content via children**
+```tsx
+<Timeline>
+  <TimelineItem title="Invoice paid" time="Apr 2" status="success">
+    <Text size="sm">$1,200 — <a href="#">view receipt</a></Text>
+  </TimelineItem>
+  <TimelineItem title="Invoice sent" time="Mar 28" status="info" />
+</Timeline>
+```

package/dist/cheat-sheets/timelineitem.md

@@ -0,0 +1,28 @@
+# TimelineItem — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**One entry in a <Timeline>. Renders a status-colored dot (or a custom icon), a title, an optional time, and optional rich content.**
+
+```ts
+import { Timeline, TimelineItem } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `status` | `"default"` \| `"success"` \| `"warning"` \| `"danger"` \| `"info"` | `default` |
+
+## Common AI Mistakes
+
+- ❌ `<TimelineItem> outside <Timeline>`
+  → Always nest TimelineItem inside Timeline
+
+## Examples
+
+**Item with rich content**
+```tsx
+<TimelineItem title="Comment added" time="1h ago" status="default">
+  <Text size="sm">“Looks good to me 👍”</Text>
+</TimelineItem>
+```

package/dist/cheat-sheets/togglegroup.md

@@ -0,0 +1,55 @@
+# ToggleGroup — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Segmented control. CONTROLLED — the group owns the value. onChange emits the VALUE (not an event). type=single → value:string|null; type=multiple → value:string[]. Provide options[] for simple lists or <ToggleItem value> children for custom content. Distinct from Switch (boolean), ButtonGroup (layout only), RadioGroup (form radios, single only).**
+
+```ts
+import { ToggleGroup, ToggleItem } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `type` | `"single"` \| `"multiple"` | `single` |
+| `size` | `"sm"` \| `"md"` \| `"lg"` | `md` |
+| `orientation` | `"horizontal"` \| `"vertical"` | `horizontal` |
+| `disabled` | `true` \| `false` | `false` |
+
+## Common AI Mistakes
+
+- ❌ `onChange={(e) => set(e.target.value)}`
+  → onChange={(value) => set(value)} — string|null (single) or string[] (multiple)
+- ❌ `Using ToggleGroup for a single on/off setting`
+  → Use <Switch> for on/off; ToggleGroup is for choosing among options
+- ❌ `type="multiple" with a string value`
+  → value={['a','b']} and onChange receives string[]
+- ❌ `<ToggleItem> outside <ToggleGroup>`
+  → Always nest ToggleItem inside ToggleGroup (or use options)
+
+## Examples
+
+**Single-select view switcher (options)**
+```tsx
+const [view, setView] = useState<string | null>("grid");
+
+<ToggleGroup
+  value={view}
+  onChange={setView}
+  options={[
+    { value: "grid", label: "Grid" },
+    { value: "list", label: "List" },
+  ]}
+/>
+```
+
+**Multiple-select formatting (composable)**
+```tsx
+const [fmt, setFmt] = useState<string[]>(["bold"]);
+
+<ToggleGroup type="multiple" value={fmt} onChange={setFmt}>
+  <ToggleItem value="bold">B</ToggleItem>
+  <ToggleItem value="italic">I</ToggleItem>
+  <ToggleItem value="underline">U</ToggleItem>
+</ToggleGroup>
+```

package/dist/cheat-sheets/toggleitem.md

@@ -0,0 +1,29 @@
+# ToggleItem — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**A single toggle button inside <ToggleGroup>. Reads selection state from the group via context.**
+
+```ts
+import { ToggleItem } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `disabled` | `true` \| `false` | `false` |
+
+## Common AI Mistakes
+
+- ❌ `Tracking selected state on ToggleItem yourself`
+  → Only set value; the group controls selected state
+
+## Examples
+
+**Composable items**
+```tsx
+<ToggleGroup value={v} onChange={setV}>
+  <ToggleItem value="left">Left</ToggleItem>
+  <ToggleItem value="center">Center</ToggleItem>
+</ToggleGroup>
+```

package/dist/cheat-sheets/tree.md

@@ -0,0 +1,48 @@
+# Tree — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Hierarchical tree view for file explorers and nested navigation. DATA-DRIVEN and CONTROLLED — pass a nested `data` array; the Tree renders recursively. Single selection. A node WITH children is a folder (click toggles expand); a leaf fires onSelect. Keyboard: ArrowUp/Down move, ArrowRight/Left expand/collapse, Enter/Space select.**
+
+```ts
+import { Tree } from "@usevyre/react"
+```
+
+## Common AI Mistakes
+
+- ❌ `Rendering a nested <ul> tree by hand with manual expand state`
+  → Pass a nested `data` array to <Tree> and control expandedIds/selectedId
+- ❌ `onSelect={(e) => ...}`
+  → onSelect={(id) => setSelected(id)}
+- ❌ `Mutating the data array to expand/collapse`
+  → Track expandedIds in state (or use defaultExpandedIds)
+- ❌ `Using DropdownMenu submenus for a file tree`
+  → Use <Tree> for file explorers / nested nav
+
+## Examples
+
+**File explorer, controlled selection**
+```tsx
+const [sel, setSel] = useState<string | null>("src/a.ts");
+
+<Tree
+  data={[
+    { id: "src", label: "src", children: [
+      { id: "src/a.ts", label: "a.ts" },
+      { id: "src/b", label: "b", children: [
+        { id: "src/b/c.ts", label: "c.ts" },
+      ]},
+    ]},
+    { id: "README.md", label: "README.md" },
+  ]}
+  selectedId={sel}
+  onSelect={setSel}
+  defaultExpandedIds={["src"]}
+/>
+```
+
+**Fully controlled expansion**
+```tsx
+const [open, setOpen] = useState<string[]>(["root"]);
+
+<Tree data={tree} expandedIds={open} onExpandedChange={setOpen} />
+```