@usevyre/ai-context 1.3.0 → 1.4.0

package/dist/cursor-rules.md

@@ -4,7 +4,7 @@ alwaysApply: true
 ---
 
 # useVyre Design System — Cursor Rules
-# Version: 1.6.0
+# Version: 1.16.0
 
 You are working in a project using the useVyre design system (@usevyre/react).
 Follow these rules strictly when generating any UI code.
@@ -528,6 +528,191 @@ Never do:
 - ❌ 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.
 
+## Form
+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.
+Import: `import { Form, FormField } from "@usevyre/react"`
+
+Valid props:
+
+Never do:
+- ❌ 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>
+
+## FormField
+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).
+Import: `import { FormField } from "@usevyre/react"`
+
+Valid props:
+
+Never do:
+- ❌ Putting onChange/value manually on the control inside FormField → ✅ Let FormField wire the control; only pass static props (type, placeholder)
+
+## NumberInput
+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.
+Import: `import { NumberInput } from "@usevyre/react"`
+
+Valid props:
+- size: "sm" | "md" | "lg" [default: md]
+
+Never do:
+- ❌ 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
+
+## ToggleGroup
+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).
+Import: `import { ToggleGroup, ToggleItem } from "@usevyre/react"`
+
+Valid props:
+- type: "single" | "multiple" [default: single]
+- size: "sm" | "md" | "lg" [default: md]
+- orientation: "horizontal" | "vertical" [default: horizontal]
+
+Never do:
+- ❌ 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)
+
+## ToggleItem
+A single toggle button inside <ToggleGroup>. Reads selection state from the group via context.
+Import: `import { ToggleItem } from "@usevyre/react"`
+
+Valid props:
+
+Never do:
+- ❌ Tracking selected state on ToggleItem yourself → ✅ Only set value; the group controls selected state
+
+## Stepper
+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.
+Import: `import { Stepper, StepperNav, Step, StepPanel } from "@usevyre/react"`
+
+Valid props:
+- orientation: "horizontal" | "vertical" [default: horizontal]
+
+Never do:
+- ❌ 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
+
+## StepperNav
+Container for Step indicators inside <Stepper>. Lays them out per the Stepper's orientation.
+Import: `import { Stepper, StepperNav, Step, StepPanel } from "@usevyre/react"`
+
+## Step
+One step indicator inside <StepperNav>. State (completed/current/upcoming) derives from the Stepper's active index automatically.
+Import: `import { Stepper, StepperNav, Step, StepPanel } from "@usevyre/react"`
+
+Valid props:
+
+## StepPanel
+Content for one step. Renders its children only when its index equals the Stepper's active step.
+Import: `import { Stepper, StepperNav, Step, StepPanel } from "@usevyre/react"`
+
+Valid props:
+
+## EmptyState
+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.
+Import: `import { EmptyState } from "@usevyre/react"`
+
+Valid props:
+- variant: "default" | "search" | "error" [default: default]
+- size: "sm" | "md" | "lg" [default: md]
+
+Never do:
+- ❌ 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
+
+## Stat
+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.
+Import: `import { Stat, StatGroup } from "@usevyre/react"`
+
+Valid props:
+- trend: "up" | "down" | "neutral" [default: neutral]
+- size: "sm" | "md" | "lg" [default: md]
+
+Never do:
+- ❌ 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>
+
+## StatGroup
+Evenly-split row of <Stat> with subtle dividers between items. Each Stat flexes to equal width.
+Import: `import { Stat, StatGroup } from "@usevyre/react"`
+
+Never do:
+- ❌ Putting non-Stat children in StatGroup → ✅ Only place <Stat> elements inside StatGroup
+
+## Timeline
+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.
+Import: `import { Timeline, TimelineItem } from "@usevyre/react"`
+
+Valid props:
+
+Never do:
+- ❌ 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)
+
+## TimelineItem
+One entry in a <Timeline>. Renders a status-colored dot (or a custom icon), a title, an optional time, and optional rich content.
+Import: `import { Timeline, TimelineItem } from "@usevyre/react"`
+
+Valid props:
+- status: "default" | "success" | "warning" | "danger" | "info" [default: default]
+
+Never do:
+- ❌ <TimelineItem> outside <Timeline> → ✅ Always nest TimelineItem inside Timeline
+
+## Tree
+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.
+Import: `import { Tree } from "@usevyre/react"`
+
+Valid props:
+
+Never do:
+- ❌ 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
+
+## OTPInput
+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>.
+Import: `import { OTPInput } from "@usevyre/react"`
+
+Valid props:
+- type: "numeric" | "alphanumeric" [default: numeric]
+- size: "sm" | "md" | "lg" [default: md]
+
+Never do:
+- ❌ 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)
+
+## Carousel
+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).
+Import: `import { Carousel, CarouselSlide } from "@usevyre/react"`
+
+Valid props:
+
+Never do:
+- ❌ 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
+
+## CarouselSlide
+One slide inside <Carousel>. Holds arbitrary content (image, Card, testimonial). Slide order determines its index.
+Import: `import { Carousel, CarouselSlide } from "@usevyre/react"`
+
+Never do:
+- ❌ <CarouselSlide> outside <Carousel> → ✅ Always nest CarouselSlide inside Carousel
+
 ## DateRangePicker
 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.
 Import: `import { DateRangePicker } from "@usevyre/react"`