@usevyre/ai-context 1.3.0 → 1.4.0

package/dist/anti-patterns.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.6.0",
+  "version": "1.16.0",
   "rules": [
     {
       "component": "Accordion",
@@ -610,6 +610,293 @@
       "fix": "Use the width / height prop: width=\"full\", width=\"md\", height=\"screen\", etc.",
       "severity": "error"
     },
+    {
+      "component": "Form",
+      "pattern": "Manually tracking each field's error state with useState",
+      "reason": "Form already validates and maps errors into Field automatically",
+      "fix": "Wrap controls in <FormField name rules> and let Form manage errors",
+      "severity": "error"
+    },
+    {
+      "component": "Form",
+      "pattern": "Adding a validation library (zod/yup) just for basic rules",
+      "reason": "Form ships zero-dependency built-in rules",
+      "fix": "Use rules={{ required, minLength, pattern, email, validate }}",
+      "severity": "error"
+    },
+    {
+      "component": "Form",
+      "pattern": "<FormField> with multiple control children",
+      "reason": "FormField clones a single child to inject name/value/onChange",
+      "fix": "Use one control per FormField (Input/Textarea/Select/etc.)",
+      "severity": "error"
+    },
+    {
+      "component": "Form",
+      "pattern": "<FormField> outside a <Form>",
+      "reason": "FormField reads form context",
+      "fix": "Always nest FormField inside <Form>",
+      "severity": "error"
+    },
+    {
+      "component": "FormField",
+      "pattern": "Putting onChange/value manually on the control inside FormField",
+      "reason": "FormField already injects them; manual props can desync from form state",
+      "fix": "Let FormField wire the control; only pass static props (type, placeholder)",
+      "severity": "error"
+    },
+    {
+      "component": "NumberInput",
+      "pattern": "onChange={(e) => set(e.target.value)}",
+      "reason": "NumberInput emits a number, not an event — there is no e.target",
+      "fix": "onChange={(value) => set(value)} — value is number | null",
+      "severity": "error"
+    },
+    {
+      "component": "NumberInput",
+      "pattern": "Using <Input type=\"number\"> for numeric fields",
+      "reason": "Native number input has no token-styled stepper, no clamp, returns a string",
+      "fix": "Use <NumberInput value onChange min max step />",
+      "severity": "error"
+    },
+    {
+      "component": "NumberInput",
+      "pattern": "Parsing the value with Number() in form state",
+      "reason": "NumberInput already emits a real number (or null)",
+      "fix": "Store the value directly; it is already number | null",
+      "severity": "error"
+    },
+    {
+      "component": "ToggleGroup",
+      "pattern": "onChange={(e) => set(e.target.value)}",
+      "reason": "ToggleGroup emits the value, not an event",
+      "fix": "onChange={(value) => set(value)} — string|null (single) or string[] (multiple)",
+      "severity": "error"
+    },
+    {
+      "component": "ToggleGroup",
+      "pattern": "Using ToggleGroup for a single on/off setting",
+      "reason": "That is a boolean toggle",
+      "fix": "Use <Switch> for on/off; ToggleGroup is for choosing among options",
+      "severity": "error"
+    },
+    {
+      "component": "ToggleGroup",
+      "pattern": "type=\"multiple\" with a string value",
+      "reason": "multiple mode requires an array value",
+      "fix": "value={['a','b']} and onChange receives string[]",
+      "severity": "error"
+    },
+    {
+      "component": "ToggleGroup",
+      "pattern": "<ToggleItem> outside <ToggleGroup>",
+      "reason": "ToggleItem reads group context",
+      "fix": "Always nest ToggleItem inside ToggleGroup (or use options)",
+      "severity": "error"
+    },
+    {
+      "component": "ToggleItem",
+      "pattern": "Tracking selected state on ToggleItem yourself",
+      "reason": "Selection is owned by ToggleGroup",
+      "fix": "Only set value; the group controls selected state",
+      "severity": "error"
+    },
+    {
+      "component": "Stepper",
+      "pattern": "Using Tabs for a wizard / checkout flow",
+      "reason": "Tabs are peer panels; a step flow is ordered with completed/current/upcoming state",
+      "fix": "Use <Stepper> with StepperNav + Step + StepPanel",
+      "severity": "error"
+    },
+    {
+      "component": "Stepper",
+      "pattern": "onChange={(e) => set(e.target.value)}",
+      "reason": "Stepper emits the index number, not an event",
+      "fix": "onChange={(index) => setStep(index)}",
+      "severity": "error"
+    },
+    {
+      "component": "Stepper",
+      "pattern": "Manually toggling which panel is visible",
+      "reason": "StepPanel renders itself only when its index === active",
+      "fix": "Give each StepPanel an index; Stepper shows the active one",
+      "severity": "error"
+    },
+    {
+      "component": "Stepper",
+      "pattern": "<Step> or <StepPanel> outside <Stepper>",
+      "reason": "They read Stepper context",
+      "fix": "Nest Step inside StepperNav, StepPanel inside Stepper",
+      "severity": "error"
+    },
+    {
+      "component": "EmptyState",
+      "pattern": "Building an empty placeholder with a bare <div> + centered text",
+      "reason": "Inconsistent spacing/typography; AI reinvents it each time",
+      "fix": "Use <EmptyState title description variant>",
+      "severity": "error"
+    },
+    {
+      "component": "EmptyState",
+      "pattern": "action / cta prop",
+      "reason": "There is no action prop; the CTA is composed",
+      "fix": "Put the Button as children of EmptyState",
+      "severity": "error"
+    },
+    {
+      "component": "EmptyState",
+      "pattern": "Using EmptyState for a loading state",
+      "reason": "EmptyState is for no-data, not in-progress",
+      "fix": "Use <Skeleton> while loading; EmptyState when the result set is empty",
+      "severity": "error"
+    },
+    {
+      "component": "Stat",
+      "pattern": "Assuming trend flips the arrow direction",
+      "reason": "Arrow direction comes from the delta sign; trend only sets color",
+      "fix": "delta=\"-0.4%\" always shows a down arrow; trend=\"up\" just colors it green",
+      "severity": "error"
+    },
+    {
+      "component": "Stat",
+      "pattern": "Building a KPI card with Card + manual layout",
+      "reason": "Inconsistent value/label/delta styling; AI reinvents it",
+      "fix": "Use <Stat label value delta trend />",
+      "severity": "error"
+    },
+    {
+      "component": "Stat",
+      "pattern": "Laying out a KPI row with custom flex + dividers",
+      "reason": "StatGroup already splits evenly with dividers",
+      "fix": "Wrap the Stats in <StatGroup>",
+      "severity": "error"
+    },
+    {
+      "component": "StatGroup",
+      "pattern": "Putting non-Stat children in StatGroup",
+      "reason": "Dividers/equal-split styling target .vyre-stat",
+      "fix": "Only place <Stat> elements inside StatGroup",
+      "severity": "error"
+    },
+    {
+      "component": "Timeline",
+      "pattern": "Building an activity log with a <ul> + manual dots/lines",
+      "reason": "Inconsistent markers/spacing; AI reinvents it each time",
+      "fix": "Use <Timeline items={[...]} /> or TimelineItem children",
+      "severity": "error"
+    },
+    {
+      "component": "Timeline",
+      "pattern": "Using Stepper for a history/audit feed",
+      "reason": "Stepper is an ordered flow with completed/current/upcoming; a feed is just past events",
+      "fix": "Use <Timeline> for logs/history; Stepper for wizards",
+      "severity": "error"
+    },
+    {
+      "component": "Timeline",
+      "pattern": "Expecting Timeline to sort by time",
+      "reason": "Timeline renders items in given order",
+      "fix": "Sort the array yourself (newest- or oldest-first)",
+      "severity": "error"
+    },
+    {
+      "component": "TimelineItem",
+      "pattern": "<TimelineItem> outside <Timeline>",
+      "reason": "Marker/connector layout assumes the Timeline list context",
+      "fix": "Always nest TimelineItem inside Timeline",
+      "severity": "error"
+    },
+    {
+      "component": "Tree",
+      "pattern": "Rendering a nested <ul> tree by hand with manual expand state",
+      "reason": "Reinvents recursion, keyboard nav, and a11y roles every time",
+      "fix": "Pass a nested `data` array to <Tree> and control expandedIds/selectedId",
+      "severity": "error"
+    },
+    {
+      "component": "Tree",
+      "pattern": "onSelect={(e) => ...}",
+      "reason": "Tree emits the node id, not an event",
+      "fix": "onSelect={(id) => setSelected(id)}",
+      "severity": "error"
+    },
+    {
+      "component": "Tree",
+      "pattern": "Mutating the data array to expand/collapse",
+      "reason": "Expansion is controlled via expandedIds, not the data",
+      "fix": "Track expandedIds in state (or use defaultExpandedIds)",
+      "severity": "error"
+    },
+    {
+      "component": "Tree",
+      "pattern": "Using DropdownMenu submenus for a file tree",
+      "reason": "Submenus are transient menus; a tree is persistent hierarchical content",
+      "fix": "Use <Tree> for file explorers / nested nav",
+      "severity": "error"
+    },
+    {
+      "component": "OTPInput",
+      "pattern": "onChange={(e) => set(e.target.value)}",
+      "reason": "OTPInput emits the code string, not an event — there is no e.target",
+      "fix": "onChange={(value) => setCode(value)}",
+      "severity": "error"
+    },
+    {
+      "component": "OTPInput",
+      "pattern": "Six separate <Input> boxes wired by hand",
+      "reason": "Reinvents paste, auto-advance, backspace and focus management",
+      "fix": "Use <OTPInput length={6} value onChange />",
+      "severity": "error"
+    },
+    {
+      "component": "OTPInput",
+      "pattern": "Reading completion by comparing length yourself",
+      "reason": "onComplete already fires when the code is full",
+      "fix": "Use onComplete={(code) => verify(code)}",
+      "severity": "error"
+    },
+    {
+      "component": "OTPInput",
+      "pattern": "type=\"password\" to hide digits",
+      "reason": "There is no type=password; masking is a dedicated prop",
+      "fix": "Use mask (type stays numeric/alphanumeric)",
+      "severity": "error"
+    },
+    {
+      "component": "Carousel",
+      "pattern": "onChange={(e) => set(e.target.value)}",
+      "reason": "Carousel emits the slide index number, not an event",
+      "fix": "onChange={(index) => setIndex(index)}",
+      "severity": "error"
+    },
+    {
+      "component": "Carousel",
+      "pattern": "Putting raw elements directly in Carousel",
+      "reason": "Slides must be CarouselSlide so snap/indices/aria work",
+      "fix": "Wrap each slide in <CarouselSlide>",
+      "severity": "error"
+    },
+    {
+      "component": "Carousel",
+      "pattern": "Building a slider with manual scroll + dot state",
+      "reason": "Reinvents snap, keyboard, autoplay-pause and a11y roles",
+      "fix": "Use <Carousel> with CarouselSlide children",
+      "severity": "error"
+    },
+    {
+      "component": "Carousel",
+      "pattern": "autoPlay without considering reduced motion / pausing",
+      "reason": "Autoplay can be an accessibility problem if it never pauses",
+      "fix": "Carousel already pauses on hover/focus; keep interval reasonable or omit autoPlay",
+      "severity": "error"
+    },
+    {
+      "component": "CarouselSlide",
+      "pattern": "<CarouselSlide> outside <Carousel>",
+      "reason": "Snap/measurement/aria depend on the Carousel context",
+      "fix": "Always nest CarouselSlide inside Carousel",
+      "severity": "error"
+    },
     {
       "component": "DateRangePicker",
       "pattern": "value={[from, to]}",

package/dist/cheat-sheets/carousel.md

@@ -0,0 +1,50 @@
+# Carousel — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**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).**
+
+```ts
+import { Carousel, CarouselSlide } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `loop` | `true` \| `false` | `false` |
+| `autoPlay` | `true` \| `false` | `false` |
+| `showArrows` | `true` \| `false` | `true` |
+| `showIndicators` | `true` \| `false` | `true` |
+
+## Common AI Mistakes
+
+- ❌ `onChange={(e) => set(e.target.value)}`
+  → onChange={(index) => setIndex(index)}
+- ❌ `Putting raw elements directly in Carousel`
+  → Wrap each slide in <CarouselSlide>
+- ❌ `Building a slider with manual scroll + dot state`
+  → Use <Carousel> with CarouselSlide children
+- ❌ `autoPlay without considering reduced motion / pausing`
+  → Carousel already pauses on hover/focus; keep interval reasonable or omit autoPlay
+
+## Examples
+
+**Image gallery with loop**
+```tsx
+const [i, setI] = useState(0);
+
+<Carousel value={i} onChange={setI} loop>
+  <CarouselSlide><img src="/a.jpg" alt="A" /></CarouselSlide>
+  <CarouselSlide><img src="/b.jpg" alt="B" /></CarouselSlide>
+  <CarouselSlide><img src="/c.jpg" alt="C" /></CarouselSlide>
+</Carousel>
+```
+
+**Onboarding, autoplay, no arrows**
+```tsx
+<Carousel autoPlay interval={4000} showArrows={false}>
+  <CarouselSlide><Welcome /></CarouselSlide>
+  <CarouselSlide><Features /></CarouselSlide>
+  <CarouselSlide><GetStarted /></CarouselSlide>
+</Carousel>
+```

package/dist/cheat-sheets/carouselslide.md

@@ -0,0 +1,22 @@
+# CarouselSlide — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**One slide inside <Carousel>. Holds arbitrary content (image, Card, testimonial). Slide order determines its index.**
+
+```ts
+import { Carousel, CarouselSlide } from "@usevyre/react"
+```
+
+## Common AI Mistakes
+
+- ❌ `<CarouselSlide> outside <Carousel>`
+  → Always nest CarouselSlide inside Carousel
+
+## Examples
+
+**Card slide**
+```tsx
+<CarouselSlide>
+  <Card><CardBody>“Best tool ever.” — Ada</CardBody></Card>
+</CarouselSlide>
+```

package/dist/cheat-sheets/emptystate.md

@@ -0,0 +1,48 @@
+# EmptyState — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**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.**
+
+```ts
+import { EmptyState } from "@usevyre/react"
+```
+
+## Valid Props
+
+| Prop | Values | Default |
+|------|--------|---------|
+| `variant` | `"default"` \| `"search"` \| `"error"` | `default` |
+| `size` | `"sm"` \| `"md"` \| `"lg"` | `md` |
+
+## Common AI Mistakes
+
+- ❌ `Building an empty placeholder with a bare <div> + centered text`
+  → Use <EmptyState title description variant>
+- ❌ `action / cta prop`
+  → Put the Button as children of EmptyState
+- ❌ `Using EmptyState for a loading state`
+  → Use <Skeleton> while loading; EmptyState when the result set is empty
+
+## Examples
+
+**Empty search results with a reset CTA**
+```tsx
+<EmptyState
+  variant="search"
+  title="No results"
+  description="Try a different search term."
+>
+  <Button variant="secondary" onClick={reset}>Clear filters</Button>
+</EmptyState>
+```
+
+**Full-page empty list**
+```tsx
+<EmptyState
+  size="lg"
+  title="No projects yet"
+  description="Create your first project to get started."
+>
+  <Button variant="primary">New project</Button>
+</EmptyState>
+```

package/dist/cheat-sheets/form.md

@@ -0,0 +1,50 @@
+# Form — AI Cheat Sheet
+> Quick reference for Claude / Cursor / Copilot
+
+**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.**
+
+```ts
+import { Form, FormField } from "@usevyre/react"
+```
+
+## Common AI Mistakes
+
+- ❌ `Manually tracking each field's error state with useState`
+  → Wrap controls in <FormField name rules> and let Form manage errors
+- ❌ `Adding a validation library (zod/yup) just for basic rules`
+  → Use rules={{ required, minLength, pattern, email, validate }}
+- ❌ `<FormField> with multiple control children`
+  → Use one control per FormField (Input/Textarea/Select/etc.)
+- ❌ `<FormField> outside a <Form>`
+  → Always nest FormField inside <Form>
+
+## Examples
+
+**Controlled sign-in form with built-in rules**
+```tsx
+const [values, setValues] = useState({ email: "", password: "" });
+
+<Form values={values} onChange={setValues} onSubmit={(v) => signIn(v)}>
+  <FormField name="email" label="Email" rules={{ required: true, email: true }}>
+    <Input type="email" />
+  </FormField>
+  <FormField name="password" label="Password" rules={{ required: true, minLength: 8 }}>
+    <Input type="password" />
+  </FormField>
+  <Button type="submit" variant="primary">Sign in</Button>
+</Form>
+```
+
+**Custom cross-field validation**
+```tsx
+<FormField
+  name="confirm"
+  label="Confirm password"
+  rules={{
+    required: true,
+    validate: (v, all) => v === all.password ? null : "Passwords do not match",
+  }}
+>
+  <Input type="password" />
+</FormField>
+```

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/index.md

@@ -49,4 +49,22 @@ Quick reference for AI agents — one file per component.
 - [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/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/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" />
+```