@usevyre/ai-context 1.2.2 → 1.4.0

package/dist/cursor-rules.md

@@ -4,7 +4,7 @@ alwaysApply: true
 ---
 
 # useVyre Design System — Cursor Rules
-# Version: 1.2.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.
@@ -93,6 +93,7 @@ Never do:
 - ❌ color="..." → ✅ Use variant prop instead
 - ❌ icon={...} → ✅ 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
 
 ## Calendar
 Inline date-grid widget (always visible, no input). mode: single | range | multiple, optional time picker. For an input + popover use DatePicker; for start/end ranges with presets use DateRangePicker.
@@ -125,6 +126,7 @@ Valid props:
 
 Never do:
 - ❌ 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
 
 ## Checkbox
 Binary toggle for boolean form values.
@@ -198,6 +200,7 @@ Never do:
 - ❌ size="icon" → ✅ Use size="sm" | "md" | "lg"
 - ❌ type="search" for search UI → ✅ 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
 
 ## Label
 Accessible form label. Associate with input via htmlFor.
@@ -445,6 +448,271 @@ Never do:
 - ❌ composer without onSend (React) / @send (Vue) → ✅ Provide onSend / @send to append the message to value
 - ❌ Treating onSend as (text) only when using allowAttachments → ✅ Handle onSend(text, files) — map files to message attachments and append
 
+## Stack
+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`).
+Import: `import { Stack } from "@usevyre/react"`
+
+Valid props:
+- direction: "row" | "column" | "row-reverse" | "column-reverse" [default: row]
+- gap: "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" [default: md]
+- rowGap: "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl"
+- columnGap: "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl"
+- align: "start" | "center" | "end" | "stretch" | "baseline" [default: stretch]
+- justify: "start" | "center" | "end" | "between" | "around" | "evenly" [default: start]
+- alignContent: "start" | "center" | "end" | "stretch" | "between" | "around" | "evenly"
+- alignSelf: "auto" | "start" | "center" | "end" | "stretch" | "baseline"
+- wrap: "nowrap" | "wrap" | "wrap-reverse" [default: 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"
+
+Never do:
+- ❌ <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.
+
+## Grid
+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`).
+Import: `import { Grid, GridItem } from "@usevyre/react"`
+
+Valid props:
+- flow: "row" | "column" | "dense" | "row-dense" | "column-dense"
+- gap: "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" [default: md]
+- rowGap: "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl"
+- columnGap: "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl"
+- align: "start" | "center" | "end" | "stretch" [default: 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"
+
+Never do:
+- ❌ <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.
+
+## GridItem
+Child placement inside <Grid>. Sets column/row span and start lines. Renders a plain <div> (or `as`).
+Import: `import { GridItem } from "@usevyre/react"`
+
+Valid props:
+
+Never do:
+- ❌ GridItem outside a Grid → ✅ Place <GridItem> directly inside <Grid>
+
+## Box
+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`).
+Import: `import { Box } from "@usevyre/react"`
+
+Valid props:
+- 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"
+
+Never do:
+- ❌ <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.
+
+## 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"`