@usevyre/react 1.2.1 → 1.4.0

package/dist/components/Carousel/Carousel.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @usevyre/react — Carousel + CarouselSlide
+ *
+ * AI CONTEXT:
+ * ┌──────────────────────────────────────────────────────────────────┐
+ * │ Component:  Carousel (+ CarouselSlide)                            │
+ * │ Import: import { Carousel, CarouselSlide } from "@usevyre/react"  │
+ * │                                                                   │
+ * │ Accessible content slider (galleries / onboarding / testimonials).│
+ * │ CONTROLLED by a 0-based slide index. Slide order = index.         │
+ * │                                                                   │
+ * │   <Carousel>                                                      │
+ * │     value?        = number  (controlled active slide)             │
+ * │     defaultValue  = number  (uncontrolled, default 0)             │
+ * │     onChange?     = (index: number) => void                       │
+ * │     loop?         = boolean  (wrap past the ends)                 │
+ * │     autoPlay?     = boolean  interval = ms (default 5000)         │
+ * │     showArrows?   = boolean (default true)                        │
+ * │     showIndicators= boolean (default true)                        │
+ * │     <CarouselSlide> any content </CarouselSlide>                  │
+ * │                                                                   │
+ * │ Snap scrolling, clickable dot indicators, ←/→ keyboard,           │
+ * │ autoplay pauses on hover/focus.                                    │
+ * └──────────────────────────────────────────────────────────────────┘
+ *
+ * @example
+ * 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>
+ * </Carousel>
+ */
+import React from "react";
+import type { BaseProps } from "../../types";
+export interface CarouselSlideProps extends BaseProps {
+    children?: React.ReactNode;
+}
+export declare const CarouselSlide: React.ForwardRefExoticComponent<CarouselSlideProps & React.RefAttributes<HTMLDivElement>>;
+export interface CarouselProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onChange">, BaseProps {
+    value?: number;
+    defaultValue?: number;
+    onChange?: (index: number) => void;
+    loop?: boolean;
+    autoPlay?: boolean;
+    /** Autoplay interval in ms */
+    interval?: number;
+    showArrows?: boolean;
+    showIndicators?: boolean;
+    children?: React.ReactNode;
+    "aria-label"?: string;
+}
+export declare const Carousel: React.ForwardRefExoticComponent<CarouselProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/EmptyState/EmptyState.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @usevyre/react — EmptyState
+ *
+ * AI CONTEXT:
+ * ┌──────────────────────────────────────────────────────────────────┐
+ * │ Component:  EmptyState                                            │
+ * │ Import:     import { EmptyState } from "@usevyre/react"            │
+ * │                                                                   │
+ * │ Presentational placeholder for empty lists, tables, and search    │
+ * │ results. No state. The optional call-to-action goes in children.  │
+ * │                                                                   │
+ * │   title        = string (required)                                │
+ * │   description?  = string                                          │
+ * │   variant       = "default"(box) | "search"(magnifier)            │
+ * │                  | "error"(warning) — picks a preset icon         │
+ * │   icon?         = ReactNode (overrides the preset)                 │
+ * │   size          = "sm" | "md"(default) | "lg"                     │
+ * │   children?     = the CTA (Button, or two buttons in a Stack)     │
+ * └──────────────────────────────────────────────────────────────────┘
+ *
+ * @example
+ * <EmptyState
+ *   variant="search"
+ *   title="No results"
+ *   description="Try a different search term."
+ * >
+ *   <Button variant="secondary" onClick={reset}>Clear filters</Button>
+ * </EmptyState>
+ */
+import React from "react";
+import type { BaseProps } from "../../types";
+declare const PRESET_ICONS: {
+    readonly default: () => import("react/jsx-runtime").JSX.Element;
+    readonly search: () => import("react/jsx-runtime").JSX.Element;
+    readonly error: () => import("react/jsx-runtime").JSX.Element;
+};
+export type EmptyStateVariant = keyof typeof PRESET_ICONS;
+export interface EmptyStateProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "title">, BaseProps {
+    /** Headline (required) */
+    title: string;
+    /** Supporting text under the title */
+    description?: string;
+    /** Picks a preset icon */
+    variant?: EmptyStateVariant;
+    /** Custom icon, overrides the variant preset */
+    icon?: React.ReactNode;
+    size?: "sm" | "md" | "lg";
+}
+export declare const EmptyState: React.ForwardRefExoticComponent<EmptyStateProps & React.RefAttributes<HTMLDivElement>>;
+export {};

package/dist/components/Form/Form.d.ts

@@ -0,0 +1,96 @@
+/**
+ * @usevyre/react — Form + FormField
+ *
+ * AI CONTEXT:
+ * ┌──────────────────────────────────────────────────────────────────┐
+ * │ Components: Form, FormField                                        │
+ * │ Import:     import { Form, FormField } from "@usevyre/react"       │
+ * │                                                                   │
+ * │ 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).   │
+ * │                                                                   │
+ * │ <Form>                                                            │
+ * │   values?       = Record<string, any>      (controlled)           │
+ * │   defaultValues?= Record<string, any>      (uncontrolled)         │
+ * │   onChange?     = (values) => void                                │
+ * │   onSubmit      = (values) => void | Promise<void>  (valid only)  │
+ * │   onInvalid?    = (errors: Record<string,string>) => void         │
+ * │                                                                   │
+ * │ <FormField name="email" label="Email" rules={{ ... }}>            │
+ * │   <Input type="email" />   ← single control child                 │
+ * │ </FormField>                                                      │
+ * │   rules = { required?: boolean | string,                          │
+ * │             minLength?, maxLength?, min?, max?: number,           │
+ * │             pattern?: RegExp, email?: boolean,                    │
+ * │             validate?: (value, allValues) => string | null }      │
+ * │                                                                   │
+ * │ FormField injects name / value / onChange / onBlur into its       │
+ * │ child and wraps it in <Field label state hint>.                   │
+ * └──────────────────────────────────────────────────────────────────┘
+ *
+ * @example
+ * 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>
+ */
+import React from "react";
+export interface FormRules {
+    /** Non-empty required. Pass a string to use it as the message. */
+    required?: boolean | string;
+    /** Minimum string length */
+    minLength?: number;
+    /** Maximum string length */
+    maxLength?: number;
+    /** Minimum numeric value */
+    min?: number;
+    /** Maximum numeric value */
+    max?: number;
+    /** Must match this pattern */
+    pattern?: RegExp;
+    /** Must be a valid email address */
+    email?: boolean;
+    /** Custom validator — return an error message string, or null if valid */
+    validate?: (value: unknown, allValues: Record<string, unknown>) => string | null | undefined;
+}
+type Values = Record<string, unknown>;
+type Errors = Record<string, string>;
+export interface FormProps extends Omit<React.FormHTMLAttributes<HTMLFormElement>, "onSubmit" | "onChange" | "onInvalid"> {
+    /** Controlled values map */
+    values?: Values;
+    /** Initial values when uncontrolled */
+    defaultValues?: Values;
+    /** Called whenever any field value changes */
+    onChange?: (values: Values) => void;
+    /** Called with the values when the form is submitted AND valid */
+    onSubmit?: (values: Values) => void | Promise<void>;
+    /** Called with the error map when submitted but invalid */
+    onInvalid?: (errors: Errors) => void;
+}
+export declare const Form: React.ForwardRefExoticComponent<FormProps & React.RefAttributes<HTMLFormElement>>;
+export interface FormFieldProps {
+    /** Key into the form's values map */
+    name: string;
+    /** Label rendered by the wrapping Field */
+    label?: string;
+    /** Helper text shown when there is no error */
+    hint?: string;
+    /** Validation rules */
+    rules?: FormRules;
+    /** Single form control element (Input, Textarea, Select, …) */
+    children: React.ReactElement;
+    className?: string;
+}
+export declare const FormField: React.FC<FormFieldProps>;
+export {};

package/dist/components/Layout/Layout.d.ts

@@ -0,0 +1,184 @@
+/**
+ * @usevyre/react — Layout primitives (Stack, Grid, GridItem, Box)
+ *
+ * AI CONTEXT:
+ * ┌──────────────────────────────────────────────────────────────────┐
+ * │ Components: Stack, Grid, GridItem, Box                             │
+ * │ Import: import { Stack, Grid, GridItem, Box } from "@usevyre/react"│
+ * │                                                                   │
+ * │ USE THESE INSTEAD OF <div style={{ display: "flex" }}>.           │
+ * │ Every spacing value is a design token — never a raw px/rem number.│
+ * │                                                                   │
+ * │ Stack/Grid/Box share width/height (avoids inline width style):    │
+ * │   width|height = "auto"|"full"|"fit"|"screen"                     │
+ * │                  | xs|sm|md|lg|xl|2xl  (fixed rem sizes)          │
+ * │                                                                   │
+ * │ <Stack>  full one-dimensional flex layout                         │
+ * │   direction   = "row"(default)|"column"|"row-reverse"             │
+ * │                 |"column-reverse"                                  │
+ * │   inline      = boolean (display:inline-flex)                      │
+ * │   gap         = token; rowGap / columnGap = token (per-axis)      │
+ * │   align       = items: start|center|end|stretch|baseline          │
+ * │   justify     = content: start|center|end|between|around|evenly   │
+ * │   alignContent= multi-line: start|center|end|stretch|between      │
+ * │                 |around|evenly                                     │
+ * │   alignSelf   = auto|start|center|end|stretch|baseline            │
+ * │   wrap        = "nowrap"(default)|"wrap"|"wrap-reverse"            │
+ * │   grow shrink = number    basis = token|"auto"|"content"|"0"      │
+ * │   as          = any HTML tag (default: "div")                      │
+ * │                                                                   │
+ * │ <Grid>  two-dimensional CSS grid                                  │
+ * │   columns = number (1-12) | "auto-fit" (default: 1)               │
+ * │   rows    = number | "auto"                                        │
+ * │   flow    = "row"|"column"|"dense"|"row-dense"|"column-dense"      │
+ * │   gap / rowGap / columnGap = token                                 │
+ * │   align   = align-items     justify = justify-items               │
+ * │   as      = any HTML tag (default: "div")                          │
+ * │ <GridItem>  child placement                                       │
+ * │   colSpan rowSpan colStart rowStart = number                      │
+ * │                                                                   │
+ * │ <Box>  spacing-only container + controlled escape hatch           │
+ * │   padding  paddingX paddingY                                       │
+ * │   paddingTop paddingRight paddingBottom paddingLeft = token       │
+ * │   margin   marginX  marginY                                        │
+ * │   marginTop marginRight marginBottom marginLeft = token           │
+ * │   (per-side overrides the X/Y/shorthand it belongs to)            │
+ * │   as = any HTML tag (default: "div")                               │
+ * │   style = ANTI-PATTERN escape hatch — prefer tokens.              │
+ * │                                                                   │
+ * │ All render a plain <div> (or `as`) in the browser.                │
+ * └──────────────────────────────────────────────────────────────────┘
+ *
+ * @example
+ * <Stack direction="column" gap="md" align="center">
+ *   <Avatar src={user.avatar} />
+ *   <Text>{user.name}</Text>
+ * </Stack>
+ *
+ * @example
+ * <Grid columns={3} gap="lg">
+ *   <GridItem colSpan={2}><Card>Wide</Card></GridItem>
+ *   <Card>…</Card>
+ * </Grid>
+ */
+import React from "react";
+/** Semantic spacing scale — maps to --vyre-spacing-* tokens. */
+export type SpaceToken = "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl";
+export type StackDirection = "row" | "column" | "row-reverse" | "column-reverse";
+export type StackWrap = "nowrap" | "wrap" | "wrap-reverse";
+export type StackAlign = "start" | "center" | "end" | "stretch" | "baseline";
+export type StackJustify = "start" | "center" | "end" | "between" | "around" | "evenly";
+export type StackAlignContent = "start" | "center" | "end" | "stretch" | "between" | "around" | "evenly";
+export type StackAlignSelf = "auto" | "start" | "center" | "end" | "stretch" | "baseline";
+export type StackBasis = SpaceToken | "auto" | "content" | "0";
+export type GridAlign = "start" | "center" | "end" | "stretch";
+export type GridFlow = "row" | "column" | "dense" | "row-dense" | "column-dense";
+export type GridColumns = number | "auto-fit";
+/**
+ * Sizing scale for width / height.
+ * - Keywords: "auto" | "full" (100%) | "fit" (fit-content) | "screen"
+ *   (100vw for width, 100vh for height)
+ * - Token sizes (fixed rem): xs 8 · sm 12 · md 16 · lg 24 · xl 32 · 2xl 42
+ */
+export type SizeToken = "auto" | "full" | "fit" | "screen" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl";
+interface SizingProps {
+    /** Width — keyword or token size. Avoids an inline width style. */
+    width?: SizeToken;
+    /** Height — keyword or token size. Avoids an inline height style. */
+    height?: SizeToken;
+}
+type PolymorphicProps<P> = P & {
+    /** HTML element to render. Always a real DOM element in the browser. */
+    as?: keyof JSX.IntrinsicElements;
+    className?: string;
+    /**
+     * Inline styles. Prefer the token props above; use this only for values
+     * the design system genuinely cannot express. Flagged as an anti-pattern
+     * by @usevyre/eslint-plugin (no-inline-layout-styles).
+     */
+    style?: React.CSSProperties;
+    children?: React.ReactNode;
+};
+export interface StackProps extends PolymorphicProps<React.HTMLAttributes<HTMLElement>>, SizingProps {
+    /** Main axis direction (flex-direction) */
+    direction?: StackDirection;
+    /** Render as inline-flex instead of flex */
+    inline?: boolean;
+    /** Space between children — design token */
+    gap?: SpaceToken;
+    /** Row gap override — design token */
+    rowGap?: SpaceToken;
+    /** Column gap override — design token */
+    columnGap?: SpaceToken;
+    /** Cross-axis alignment of items (align-items) */
+    align?: StackAlign;
+    /** Main-axis distribution (justify-content) */
+    justify?: StackJustify;
+    /** Multi-line cross-axis distribution (align-content) */
+    alignContent?: StackAlignContent;
+    /** This element's own cross-axis alignment (align-self) */
+    alignSelf?: StackAlignSelf;
+    /** Wrapping behaviour (flex-wrap). `true` is treated as "wrap". */
+    wrap?: StackWrap | boolean;
+    /** flex-grow */
+    grow?: number;
+    /** flex-shrink */
+    shrink?: number;
+    /** flex-basis — token, "auto", "content", or "0" */
+    basis?: StackBasis;
+}
+export declare const Stack: React.ForwardRefExoticComponent<StackProps & React.RefAttributes<HTMLElement>>;
+export interface GridProps extends PolymorphicProps<React.HTMLAttributes<HTMLElement>>, SizingProps {
+    /** Number of equal columns (1–12) or responsive "auto-fit" */
+    columns?: GridColumns;
+    /** Explicit row count, or "auto" */
+    rows?: number | "auto";
+    /** Auto-placement flow (grid-auto-flow) */
+    flow?: GridFlow;
+    /** Space between cells — design token */
+    gap?: SpaceToken;
+    /** Row gap override — design token */
+    rowGap?: SpaceToken;
+    /** Column gap override — design token */
+    columnGap?: SpaceToken;
+    /** Cross-axis alignment of cells (align-items) */
+    align?: GridAlign;
+    /** Inline-axis alignment of cells (justify-items) */
+    justify?: GridAlign;
+}
+export declare const Grid: React.ForwardRefExoticComponent<GridProps & React.RefAttributes<HTMLElement>>;
+export interface GridItemProps extends PolymorphicProps<React.HTMLAttributes<HTMLElement>> {
+    /** Number of columns this item spans */
+    colSpan?: number;
+    /** Number of rows this item spans */
+    rowSpan?: number;
+    /** 1-based column line this item starts at */
+    colStart?: number;
+    /** 1-based row line this item starts at */
+    rowStart?: number;
+}
+export declare const GridItem: React.ForwardRefExoticComponent<GridItemProps & React.RefAttributes<HTMLElement>>;
+export interface BoxProps extends PolymorphicProps<React.HTMLAttributes<HTMLElement>>, SizingProps {
+    /** Inner spacing (all sides) — design token */
+    padding?: SpaceToken;
+    /** Inner spacing left+right — design token */
+    paddingX?: SpaceToken;
+    /** Inner spacing top+bottom — design token */
+    paddingY?: SpaceToken;
+    paddingTop?: SpaceToken;
+    paddingRight?: SpaceToken;
+    paddingBottom?: SpaceToken;
+    paddingLeft?: SpaceToken;
+    /** Outer spacing (all sides) — design token */
+    margin?: SpaceToken;
+    /** Outer spacing left+right — design token */
+    marginX?: SpaceToken;
+    /** Outer spacing top+bottom — design token */
+    marginY?: SpaceToken;
+    marginTop?: SpaceToken;
+    marginRight?: SpaceToken;
+    marginBottom?: SpaceToken;
+    marginLeft?: SpaceToken;
+}
+export declare const Box: React.ForwardRefExoticComponent<BoxProps & React.RefAttributes<HTMLElement>>;
+export {};

package/dist/components/NumberInput/NumberInput.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @usevyre/react — NumberInput
+ *
+ * AI CONTEXT:
+ * ┌──────────────────────────────────────────────────────────────────┐
+ * │ Component:  NumberInput                                           │
+ * │ Import:     import { NumberInput } from "@usevyre/react"           │
+ * │                                                                   │
+ * │ 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 automatically).     │
+ * │                                                                   │
+ * │   value     = number | null   (controlled)                        │
+ * │   onChange  = (value: number | null) => void                      │
+ * │   min max step = number   (step default 1)                        │
+ * │   precision = number   (decimal places to round to)               │
+ * │   size      = "sm" | "md"(default) | "lg"                         │
+ * │   disabled readOnly = boolean                                     │
+ * │                                                                   │
+ * │ Clamps to min/max on blur. Keyboard: ArrowUp/Down ±step,          │
+ * │ Shift+Arrow ±step×10. Empty input → null.                         │
+ * └──────────────────────────────────────────────────────────────────┘
+ *
+ * @example
+ * const [qty, setQty] = useState<number | null>(1);
+ * <NumberInput value={qty} onChange={setQty} min={1} max={99} />
+ *
+ * @example
+ * <FormField name="age" label="Age" rules={{ required: true, min: 18 }}>
+ *   <NumberInput min={0} max={120} />
+ * </FormField>
+ */
+import React from "react";
+import type { Size, BaseProps } from "../../types";
+export interface NumberInputProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "size" | "value" | "onChange" | "defaultValue" | "type">, BaseProps {
+    /** Controlled value. null = empty. */
+    value?: number | null;
+    /** Uncontrolled initial value */
+    defaultValue?: number | null;
+    /** Called with the parsed number, or null when the field is empty */
+    onChange?: (value: number | null) => void;
+    min?: number;
+    max?: number;
+    /** Increment/decrement amount (default 1) */
+    step?: number;
+    /** Decimal places to round to */
+    precision?: number;
+    size?: Exclude<Size, "icon">;
+    disabled?: boolean;
+    readOnly?: boolean;
+}
+export declare const NumberInput: React.ForwardRefExoticComponent<NumberInputProps & React.RefAttributes<HTMLInputElement>>;

package/dist/components/OTPInput/OTPInput.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @usevyre/react — OTPInput
+ *
+ * AI CONTEXT:
+ * ┌──────────────────────────────────────────────────────────────────┐
+ * │ Component:  OTPInput                                              │
+ * │ Import:     import { OTPInput } from "@usevyre/react"              │
+ * │                                                                   │
+ * │ Segmented one-time-code input (verification / 2FA). CONTROLLED.   │
+ * │ onChange emits the STRING value (not an event) — drops into       │
+ * │ <FormField>. Paste-aware, auto-advance/backspace, arrow keys.     │
+ * │                                                                   │
+ * │   value      = string   (controlled, length ≤ `length`)           │
+ * │   onChange   = (value: string) => void                            │
+ * │   onComplete?= (value: string) => void  (all slots filled)        │
+ * │   length     = number   (default 6)                               │
+ * │   type       = "numeric"(default) | "alphanumeric"                │
+ * │   mask       = boolean  (dots instead of chars, like a password)  │
+ * │   size       = "sm" | "md"(default) | "lg"                        │
+ * │   disabled   = boolean   autoFocus = boolean                      │
+ * │                                                                   │
+ * │ Pasting a full code fills every slot. Backspace on an empty slot  │
+ * │ moves to the previous one.                                         │
+ * └──────────────────────────────────────────────────────────────────┘
+ *
+ * @example
+ * const [code, setCode] = useState("");
+ * <OTPInput value={code} onChange={setCode} onComplete={verify} />
+ *
+ * @example
+ * <FormField name="otp" label="Verification code"
+ *            rules={{ required: true, minLength: 6 }}>
+ *   <OTPInput length={6} />
+ * </FormField>
+ */
+import React from "react";
+import type { BaseProps } from "../../types";
+export interface OTPInputProps extends BaseProps {
+    value?: string;
+    defaultValue?: string;
+    onChange?: (value: string) => void;
+    /** Fired once when every slot is filled */
+    onComplete?: (value: string) => void;
+    length?: number;
+    type?: "numeric" | "alphanumeric";
+    /** Render dots instead of characters */
+    mask?: boolean;
+    size?: "sm" | "md" | "lg";
+    disabled?: boolean;
+    autoFocus?: boolean;
+    /** Forwarded to FormField wiring (used as the field name) */
+    name?: string;
+    onBlur?: React.FocusEventHandler<HTMLInputElement>;
+}
+export declare const OTPInput: React.ForwardRefExoticComponent<OTPInputProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/Stat/Stat.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @usevyre/react — Stat + StatGroup
+ *
+ * AI CONTEXT:
+ * ┌──────────────────────────────────────────────────────────────────┐
+ * │ Component:  Stat (+ StatGroup)                                    │
+ * │ Import:     import { Stat, StatGroup } from "@usevyre/react"       │
+ * │                                                                   │
+ * │ Presentational dashboard KPI. No state.                           │
+ * │                                                                   │
+ * │   label        = string (required)                                │
+ * │   value        = string | number (required, large)                │
+ * │   delta?       = string | number  (the change amount)             │
+ * │   trend?       = "up" | "down" | "neutral"  (CONTROLS the color   │
+ * │                   — up=success, down=danger, neutral=muted)        │
+ * │   deltaLabel?  = string  (e.g. "vs last month")                   │
+ * │   icon?        = ReactNode                                         │
+ * │   size         = "sm" | "md"(default) | "lg"                      │
+ * │                                                                   │
+ * │ trend is EXPLICIT so "churn down = good" can stay green.          │
+ * │ Wrap several in <StatGroup> for an evenly-split row with dividers.│
+ * └──────────────────────────────────────────────────────────────────┘
+ *
+ * @example
+ * <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>
+ */
+import React from "react";
+import type { BaseProps } from "../../types";
+export type StatTrend = "up" | "down" | "neutral";
+export interface StatProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "title">, BaseProps {
+    /** Metric name (required) */
+    label: string;
+    /** The headline figure (required) */
+    value: string | number;
+    /** The change amount, e.g. "+12%" or 24 */
+    delta?: string | number;
+    /** Explicitly sets the delta color — up=success, down=danger, neutral=muted */
+    trend?: StatTrend;
+    /** Context for the delta, e.g. "vs last month" */
+    deltaLabel?: string;
+    /** Optional leading icon */
+    icon?: React.ReactNode;
+    size?: "sm" | "md" | "lg";
+}
+export declare const Stat: React.ForwardRefExoticComponent<StatProps & React.RefAttributes<HTMLDivElement>>;
+export interface StatGroupProps extends React.HTMLAttributes<HTMLDivElement>, BaseProps {
+    children?: React.ReactNode;
+}
+export declare const StatGroup: React.ForwardRefExoticComponent<StatGroupProps & React.RefAttributes<HTMLDivElement>>;

package/dist/components/Stepper/Stepper.d.ts

@@ -0,0 +1,76 @@
+/**
+ * @usevyre/react — Stepper + Step + StepPanel
+ *
+ * AI CONTEXT:
+ * ┌──────────────────────────────────────────────────────────────────┐
+ * │ Component:  Stepper (+ StepperNav, Step, StepPanel)              │
+ * │ Import: import { Stepper, StepperNav, Step, StepPanel }           │
+ * │         from "@usevyre/react"                                     │
+ * │                                                                   │
+ * │ Multi-step flow indicator + controller (onboarding/checkout/      │
+ * │ wizard). CONTROLLED by a 0-based index. Indices come from order.  │
+ * │                                                                   │
+ * │   <Stepper>                                                       │
+ * │     value?       = number  (controlled active index)              │
+ * │     defaultValue = number  (uncontrolled, default 0)              │
+ * │     onChange?    = (index: number) => void                        │
+ * │     orientation  = "horizontal"(default) | "vertical"             │
+ * │     clickable?   = boolean  (click a completed Step to go back)   │
+ * │   <StepperNav> <Step label description? icon? /> … </StepperNav>  │
+ * │   <StepPanel> … </StepPanel>   ← rendered when its order == active │
+ * │                                                                   │
+ * │ Each Step auto-gets state completed | current | upcoming.         │
+ * │ NOT Tabs (peer panels) — Stepper is an ORDERED linear flow.       │
+ * └──────────────────────────────────────────────────────────────────┘
+ *
+ * @example
+ * const [step, setStep] = useState(0);
+ * <Stepper value={step} onChange={setStep}>
+ *   <StepperNav>
+ *     <Step label="Account" />
+ *     <Step label="Profile" />
+ *     <Step label="Done" />
+ *   </StepperNav>
+ *   <StepPanel><AccountForm /></StepPanel>
+ *   <StepPanel><ProfileForm /></StepPanel>
+ *   <StepPanel><Summary /></StepPanel>
+ * </Stepper>
+ */
+import React from "react";
+import type { BaseProps } from "../../types";
+export interface StepperProps extends BaseProps {
+    /** Controlled active step (0-based) */
+    value?: number;
+    /** Initial active step when uncontrolled */
+    defaultValue?: number;
+    /** Called with the new active index */
+    onChange?: (index: number) => void;
+    orientation?: "horizontal" | "vertical";
+    /** Allow clicking a completed Step to jump back to it */
+    clickable?: boolean;
+    children?: React.ReactNode;
+}
+export declare const Stepper: React.ForwardRefExoticComponent<StepperProps & React.RefAttributes<HTMLDivElement>>;
+export interface StepperNavProps extends BaseProps {
+    children?: React.ReactNode;
+}
+export declare const StepperNav: React.ForwardRefExoticComponent<StepperNavProps & React.RefAttributes<HTMLDivElement>>;
+export interface StepProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "title"> {
+    label?: React.ReactNode;
+    description?: React.ReactNode;
+    /** Custom indicator content (defaults to step number / ✓ when done) */
+    icon?: React.ReactNode;
+    /** Explicit 0-based index. Optional — inferred from order otherwise. */
+    index?: number;
+    /** @internal injected by StepperNav */
+    __index?: number;
+}
+export declare const Step: React.ForwardRefExoticComponent<StepProps & React.RefAttributes<HTMLDivElement>>;
+export interface StepPanelProps extends BaseProps {
+    children?: React.ReactNode;
+    /** Explicit 0-based index. Optional — inferred from order otherwise. */
+    index?: number;
+    /** @internal injected by Stepper */
+    __index?: number;
+}
+export declare const StepPanel: React.FC<StepPanelProps>;