@usevyre/ai-context 1.2.2 → 1.4.0

package/dist/cheat-sheets/formfield.md

@@ -0,0 +1,22 @@
+# FormField — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**A single labelled, validated field inside <Form>. Injects name/value/onChange/onBlur into its one control child and wraps it in <Field> (label + error state + hint).**
+
+```ts
+import { FormField } from "@usevyre/react"
+```
+
+## Common AI Mistakes
+
+- ❌ `Putting onChange/value manually on the control inside FormField`
+  → Let FormField wire the control; only pass static props (type, placeholder)
+
+## Examples
+
+**Field with a hint**
+```tsx
+<FormField name="bio" label="Bio" hint="Max 200 characters" rules={{ maxLength: 200 }}>
+  <Textarea />
+</FormField>
+```

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

@@ -45,4 +45,26 @@ 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`).
+- [Form](form.md) — Controlled, data-driven form. Zero dependencies. Validation runs on submit and (after the first submit) on blur. Errors map into the wrapped Field automatically (state=error + hint=message). Compose with FormField, which wires name/value/onChange/onBlur into a single control child.
+- [FormField](formfield.md) — A single labelled, validated field inside <Form>. Injects name/value/onChange/onBlur into its one control child and wraps it in <Field> (label + error state + hint).
+- [NumberInput](numberinput.md) — Controlled numeric input with −/+ stepper buttons. onChange emits a NUMBER (or null when empty) — NOT an event. Drops straight into <FormField> (Form handles the non-event value). Clamps to min/max on blur; keyboard ArrowUp/Down ±step, Shift+Arrow ±step×10.
+- [ToggleGroup](togglegroup.md) — 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).
+- [ToggleItem](toggleitem.md) — A single toggle button inside <ToggleGroup>. Reads selection state from the group via context.
+- [Stepper](stepper.md) — 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.
+- [StepperNav](steppernav.md) — Container for Step indicators inside <Stepper>. Lays them out per the Stepper's orientation.
+- [Step](step.md) — One step indicator inside <StepperNav>. State (completed/current/upcoming) derives from the Stepper's active index automatically.
+- [StepPanel](steppanel.md) — Content for one step. Renders its children only when its index equals the Stepper's active step.
+- [EmptyState](emptystate.md) — Presentational placeholder for empty lists, tables, and search results. No state. title/description/variant/size are props; the optional call-to-action goes in children (React) or the default slot (Vue). variant picks a preset icon (default=box, search=magnifier, error=warning); pass `icon` (or #icon slot) to override.
+- [Stat](stat.md) — Presentational dashboard KPI. No state. The arrow DIRECTION follows the sign of `delta` (the actual change: -0.4% → down arrow). The arrow/delta COLOR is set explicitly by `trend` (up=success, down=danger, neutral=muted) — so 'churn -0.4%, trend=up' shows a green DOWN arrow. Wrap several in StatGroup for an evenly-split row with dividers.
+- [StatGroup](statgroup.md) — Evenly-split row of <Stat> with subtle dividers between items. Each Stat flexes to equal width.
+- [Timeline](timeline.md) — 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.
+- [TimelineItem](timelineitem.md) — One entry in a <Timeline>. Renders a status-colored dot (or a custom icon), a title, an optional time, and optional rich content.
+- [Tree](tree.md) — 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.
+- [OTPInput](otpinput.md) — Segmented one-time-code input for verification / 2FA. CONTROLLED. onChange emits the STRING value (not an event), and onComplete fires once when every slot is filled. Paste-aware (pasting a full code fills all slots), auto-advance on input, backspace moves to the previous slot, arrow keys navigate. Drops straight into <FormField>.
+- [Carousel](carousel.md) — Accessible content slider for galleries, onboarding, and testimonials. CONTROLLED by a 0-based slide index. Compose CarouselSlide children (slide order = index). Snap scrolling, clickable dot indicators, prev/next arrows, ArrowLeft/Right keyboard, optional loop and autoPlay (autoplay pauses on hover/focus). onChange emits the index (not an event).
+- [CarouselSlide](carouselslide.md) — One slide inside <Carousel>. Holds arbitrary content (image, Card, testimonial). Slide order determines its index.
 - [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/numberinput.md

@@ -0,0 +1,41 @@
+# NumberInput — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Controlled numeric input with −/+ stepper buttons. onChange emits a NUMBER (or null when empty) — NOT an event. Drops straight into <FormField> (Form handles the non-event value). Clamps to min/max on blur; keyboard ArrowUp/Down ±step, Shift+Arrow ±step×10.**
+
+```ts
+import { NumberInput } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `size` | `"sm"` \| `"md"` \| `"lg"` | `md` |
+| `disabled` | `true` \| `false` | `false` |
+| `readOnly` | `true` \| `false` | `false` |
+
+## Common AI Mistakes
+
+- ❌ `onChange={(e) => set(e.target.value)}`
+  → onChange={(value) => set(value)} — value is number | null
+- ❌ `Using <Input type="number"> for numeric fields`
+  → Use <NumberInput value onChange min max step />
+- ❌ `Parsing the value with Number() in form state`
+  → Store the value directly; it is already number | null
+
+## Examples
+
+**Quantity selector**
+```tsx
+const [qty, setQty] = useState<number | null>(1);
+
+<NumberInput value={qty} onChange={setQty} min={1} max={99} />
+```
+
+**Inside a Form**
+```tsx
+<FormField name="age" label="Age" rules={{ required: true, min: 18 }}>
+  <NumberInput min={0} max={120} />
+</FormField>
+```

package/dist/cheat-sheets/otpinput.md

@@ -0,0 +1,51 @@
+# OTPInput — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Segmented one-time-code input for verification / 2FA. CONTROLLED. onChange emits the STRING value (not an event), and onComplete fires once when every slot is filled. Paste-aware (pasting a full code fills all slots), auto-advance on input, backspace moves to the previous slot, arrow keys navigate. Drops straight into <FormField>.**
+
+```ts
+import { OTPInput } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `type` | `"numeric"` \| `"alphanumeric"` | `numeric` |
+| `size` | `"sm"` \| `"md"` \| `"lg"` | `md` |
+| `mask` | `true` \| `false` | `false` |
+| `disabled` | `true` \| `false` | `false` |
+| `autoFocus` | `true` \| `false` | `false` |
+
+## Common AI Mistakes
+
+- ❌ `onChange={(e) => set(e.target.value)}`
+  → onChange={(value) => setCode(value)}
+- ❌ `Six separate <Input> boxes wired by hand`
+  → Use <OTPInput length={6} value onChange />
+- ❌ `Reading completion by comparing length yourself`
+  → Use onComplete={(code) => verify(code)}
+- ❌ `type="password" to hide digits`
+  → Use mask (type stays numeric/alphanumeric)
+
+## Examples
+
+**2FA code with verify on complete**
+```tsx
+const [code, setCode] = useState("");
+
+<OTPInput
+  value={code}
+  onChange={setCode}
+  onComplete={(c) => verify(c)}
+  autoFocus
+/>
+```
+
+**Inside a Form**
+```tsx
+<FormField name="otp" label="Verification code"
+           rules={{ required: true, minLength: 6 }}>
+  <OTPInput length={6} />
+</FormField>
+```

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

package/dist/cheat-sheets/stat.md

@@ -0,0 +1,41 @@
+# Stat — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**Presentational dashboard KPI. No state. The arrow DIRECTION follows the sign of `delta` (the actual change: -0.4% → down arrow). The arrow/delta COLOR is set explicitly by `trend` (up=success, down=danger, neutral=muted) — so 'churn -0.4%, trend=up' shows a green DOWN arrow. Wrap several in StatGroup for an evenly-split row with dividers.**
+
+```ts
+import { Stat, StatGroup } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `trend` | `"up"` \| `"down"` \| `"neutral"` | `neutral` |
+| `size` | `"sm"` \| `"md"` \| `"lg"` | `md` |
+
+## Common AI Mistakes
+
+- ❌ `Assuming trend flips the arrow direction`
+  → delta="-0.4%" always shows a down arrow; trend="up" just colors it green
+- ❌ `Building a KPI card with Card + manual layout`
+  → Use <Stat label value delta trend />
+- ❌ `Laying out a KPI row with custom flex + dividers`
+  → Wrap the Stats in <StatGroup>
+
+## Examples
+
+**KPI row; note churn stays green while going down**
+```tsx
+<StatGroup>
+  <Stat label="Revenue" value="$48.2k" delta="+12%" trend="up" deltaLabel="vs last month" />
+  <Stat label="Churn" value="2.1%" delta="-0.4%" trend="up" deltaLabel="lower is better" />
+  <Stat label="Orders" value="1,204" delta="0%" trend="neutral" />
+</StatGroup>
+```
+
+**Single stat with icon**
+```tsx
+<Stat label="Active users" value="12,840" delta="+3.2%" trend="up"
+      icon={<UsersIcon />} size="lg" />
+```

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