@usevyre/react 1.3.0 → 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/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>;

package/dist/components/Timeline/Timeline.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @usevyre/react — Timeline + TimelineItem
+ *
+ * AI CONTEXT:
+ * ┌──────────────────────────────────────────────────────────────────┐
+ * │ Component:  Timeline (+ TimelineItem)                             │
+ * │ Import:     import { Timeline, TimelineItem } from "@usevyre/react"│
+ * │                                                                   │
+ * │ Vertical activity feed for audit logs / history. Presentational.  │
+ * │ A marker dot per item + a connector line between them.            │
+ * │                                                                   │
+ * │   <Timeline items={[{ title, time?, description?, status?,        │
+ * │                       icon? }]} />                                 │
+ * │   — OR —                                                          │
+ * │   <Timeline>                                                      │
+ * │     <TimelineItem title="…" time="…" status="success">            │
+ * │       rich content (links, badges, …)                             │
+ * │     </TimelineItem>                                               │
+ * │   </Timeline>                                                     │
+ * │                                                                   │
+ * │   status = "default"|"success"|"warning"|"danger"|"info"          │
+ * │            (colors the dot)                                        │
+ * │   icon   = ReactNode (overrides the dot)                           │
+ * │                                                                   │
+ * │ Use `items` for plain logs; use TimelineItem children for rich    │
+ * │ per-item content. Newest-first or oldest-first is up to you —     │
+ * │ Timeline does not reorder.                                         │
+ * └──────────────────────────────────────────────────────────────────┘
+ *
+ * @example
+ * <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" },
+ *   ]}
+ * />
+ *
+ * @example
+ * <Timeline>
+ *   <TimelineItem title="Invoice paid" time="Apr 2" status="success">
+ *     <Text size="sm">$1,200 — <a href="#">view receipt</a></Text>
+ *   </TimelineItem>
+ * </Timeline>
+ */
+import React from "react";
+import type { BaseProps } from "../../types";
+export type TimelineStatus = "default" | "success" | "warning" | "danger" | "info";
+export interface TimelineItemData {
+    title: React.ReactNode;
+    time?: React.ReactNode;
+    description?: React.ReactNode;
+    status?: TimelineStatus;
+    icon?: React.ReactNode;
+}
+export interface TimelineProps extends React.HTMLAttributes<HTMLOListElement>, BaseProps {
+    /** Plain items — alternative to TimelineItem children */
+    items?: TimelineItemData[];
+    children?: React.ReactNode;
+}
+export declare const Timeline: React.ForwardRefExoticComponent<TimelineProps & React.RefAttributes<HTMLOListElement>>;
+export interface TimelineItemProps extends Omit<React.LiHTMLAttributes<HTMLLIElement>, "title">, BaseProps {
+    title: React.ReactNode;
+    time?: React.ReactNode;
+    status?: TimelineStatus;
+    /** Overrides the status dot */
+    icon?: React.ReactNode;
+    children?: React.ReactNode;
+}
+export declare const TimelineItem: React.ForwardRefExoticComponent<TimelineItemProps & React.RefAttributes<HTMLLIElement>>;

package/dist/components/ToggleGroup/ToggleGroup.d.ts

@@ -0,0 +1,79 @@
+/**
+ * @usevyre/react — ToggleGroup + ToggleItem
+ *
+ * AI CONTEXT:
+ * ┌──────────────────────────────────────────────────────────────────┐
+ * │ Component:  ToggleGroup (+ ToggleItem)                            │
+ * │ Import:     import { ToggleGroup, ToggleItem } from "@usevyre/react"│
+ * │                                                                   │
+ * │ Segmented control. CONTROLLED — the group owns the value.         │
+ * │ onChange emits the VALUE (string|null or string[]), not an event. │
+ * │                                                                   │
+ * │   type     = "single"(default) | "multiple"                       │
+ * │     single   → value: string | null, onChange(string | null)      │
+ * │     multiple → value: string[],      onChange(string[])           │
+ * │   options? = { value; label?; icon?; disabled? }[]                │
+ * │   size     = "sm" | "md"(default) | "lg"                          │
+ * │   disabled = boolean (disables the whole group)                   │
+ * │                                                                   │
+ * │ Use `options` for simple lists, or <ToggleItem value> children    │
+ * │ for custom content. Keyboard: arrows move, Space/Enter toggles.   │
+ * │                                                                   │
+ * │ NOT Switch (boolean), NOT ButtonGroup (layout only),              │
+ * │ NOT RadioGroup (form radios, single only).                        │
+ * └──────────────────────────────────────────────────────────────────┘
+ *
+ * @example
+ * const [view, setView] = useState<string | null>("grid");
+ * <ToggleGroup
+ *   value={view}
+ *   onChange={setView}
+ *   options={[
+ *     { value: "grid", label: "Grid" },
+ *     { value: "list", label: "List" },
+ *   ]}
+ * />
+ *
+ * @example  // multiple, composable
+ * const [fmt, setFmt] = useState<string[]>(["bold"]);
+ * <ToggleGroup type="multiple" value={fmt} onChange={setFmt}>
+ *   <ToggleItem value="bold">B</ToggleItem>
+ *   <ToggleItem value="italic">I</ToggleItem>
+ * </ToggleGroup>
+ */
+import React from "react";
+import type { BaseProps } from "../../types";
+export interface ToggleOption {
+    value: string;
+    label?: React.ReactNode;
+    icon?: React.ReactNode;
+    disabled?: boolean;
+}
+type ToggleSize = "sm" | "md" | "lg";
+type SingleProps = {
+    type?: "single";
+    value?: string | null;
+    onChange?: (value: string | null) => void;
+};
+type MultipleProps = {
+    type: "multiple";
+    value?: string[];
+    onChange?: (value: string[]) => void;
+};
+export type ToggleGroupProps = (SingleProps | MultipleProps) & BaseProps & {
+    options?: ToggleOption[];
+    size?: ToggleSize;
+    disabled?: boolean;
+    orientation?: "horizontal" | "vertical";
+    /** Accessible label for the group */
+    "aria-label"?: string;
+    children?: React.ReactNode;
+};
+export declare const ToggleGroup: React.ForwardRefExoticComponent<ToggleGroupProps & React.RefAttributes<HTMLDivElement>>;
+export interface ToggleItemProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "value"> {
+    value: string;
+    icon?: React.ReactNode;
+    disabled?: boolean;
+}
+export declare const ToggleItem: React.ForwardRefExoticComponent<ToggleItemProps & React.RefAttributes<HTMLButtonElement>>;
+export {};

package/dist/components/Tree/Tree.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @usevyre/react — Tree
+ *
+ * AI CONTEXT:
+ * ┌──────────────────────────────────────────────────────────────────┐
+ * │ Component:  Tree                                                  │
+ * │ Import:     import { Tree } from "@usevyre/react"                  │
+ * │                                                                   │
+ * │ Hierarchical tree view (file explorer / nested nav). DATA-DRIVEN  │
+ * │ and CONTROLLED. Pass a nested array; the Tree renders recursively.│
+ * │                                                                   │
+ * │   data = TreeNode[]  where TreeNode = {                            │
+ * │     id: string; label: ReactNode;                                 │
+ * │     icon?: ReactNode; disabled?: boolean;                          │
+ * │     children?: TreeNode[]                                          │
+ * │   }                                                               │
+ * │   expandedIds?        = string[]  (controlled)                    │
+ * │   defaultExpandedIds  = string[]  (uncontrolled)                  │
+ * │   onExpandedChange?   = (ids: string[]) => void                   │
+ * │   selectedId?         = string | null  (controlled)               │
+ * │   defaultSelectedId   = string | null  (uncontrolled)             │
+ * │   onSelect?           = (id: string) => void                      │
+ * │                                                                   │
+ * │ Single selection. A node with `children` is a folder (toggles     │
+ * │ expand on click); a leaf fires onSelect. Keyboard: ↑/↓ move,      │
+ * │ →/← expand/collapse, Enter/Space select.                          │
+ * └──────────────────────────────────────────────────────────────────┘
+ *
+ * @example
+ * const [sel, setSel] = useState<string | null>("a/b.ts");
+ * <Tree
+ *   data={[
+ *     { id: "src", label: "src", children: [
+ *       { id: "a.ts", label: "a.ts" },
+ *       { id: "b", label: "b", children: [{ id: "b/c.ts", label: "c.ts" }] },
+ *     ]},
+ *     { id: "readme", label: "README.md" },
+ *   ]}
+ *   selectedId={sel}
+ *   onSelect={setSel}
+ *   defaultExpandedIds={["src"]}
+ * />
+ */
+import React from "react";
+import type { BaseProps } from "../../types";
+export interface TreeNode {
+    id: string;
+    label: React.ReactNode;
+    icon?: React.ReactNode;
+    disabled?: boolean;
+    children?: TreeNode[];
+}
+export interface TreeProps extends Omit<React.HTMLAttributes<HTMLUListElement>, "onSelect">, BaseProps {
+    data: TreeNode[];
+    expandedIds?: string[];
+    defaultExpandedIds?: string[];
+    onExpandedChange?: (ids: string[]) => void;
+    selectedId?: string | null;
+    defaultSelectedId?: string | null;
+    onSelect?: (id: string) => void;
+}
+export declare const Tree: React.ForwardRefExoticComponent<TreeProps & React.RefAttributes<HTMLUListElement>>;