@windforge/ui 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1195 @@
+import { ClassValue } from 'clsx';
+import * as class_variance_authority_types from 'class-variance-authority/types';
+import * as React from 'react';
+import { VariantProps } from 'class-variance-authority';
+import * as LabelPrimitive from '@radix-ui/react-label';
+import * as SeparatorPrimitive from '@radix-ui/react-separator';
+import * as SwitchPrimitives from '@radix-ui/react-switch';
+import * as CheckboxPrimitive from '@radix-ui/react-checkbox';
+import * as RadioGroupPrimitive from '@radix-ui/react-radio-group';
+import * as TabsPrimitive from '@radix-ui/react-tabs';
+import * as TooltipPrimitive from '@radix-ui/react-tooltip';
+import * as SelectPrimitive from '@radix-ui/react-select';
+import * as DialogPrimitive from '@radix-ui/react-dialog';
+import * as AccordionPrimitive from '@radix-ui/react-accordion';
+import * as AvatarPrimitive from '@radix-ui/react-avatar';
+import * as ProgressPrimitive from '@radix-ui/react-progress';
+import * as SliderPrimitive from '@radix-ui/react-slider';
+import * as PopoverPrimitive from '@radix-ui/react-popover';
+import * as DropdownMenuPrimitive from '@radix-ui/react-dropdown-menu';
+import { DayPicker } from 'react-day-picker';
+import { EChartsCoreOption } from 'echarts/core';
+import { LucideIcon } from 'lucide-react';
+export * from '@windforge/tokens';
+
+/**
+ * DETERMINISTIC LAYOUT PRIMITIVES — `Box` and `Stack`.
+ *
+ * Layout is a CLOSED set of intent-named, conventionally-named props, not free-form
+ * CSS. An AI (or a human) picks from a finite vocabulary — `direction="row"`,
+ * `gap="card"`, `padding="lg"`, `borderRadius="xl"` — and `cva` maps each choice to
+ * exactly one on-scale Tailwind class at build time. There is no path to an
+ * off-scale value like `padding-[13px]` or a random hex, so output is always
+ * on-system and reviewable.
+ *
+ * No JS runtime: thin wrappers that concatenate class strings — no `sx`-style
+ * computation at render.
+ *
+ * Spacing accepts the generic steps (none·xs·sm·md·lg·xl·2xl) AND the practical
+ * Windforge spacing tokens (nbsp·card·gutter·section·page).
+ *
+ *   <Box padding="lg" background="subtle" borderRadius="xl" border="default">…</Box>
+ *   <Stack direction="row" gap="card" align="center" justify="between">…</Stack>
+ *
+ * `asChild` makes either polymorphic (the replacement for MUI `component=`):
+ *   <Box asChild padding="md"><section/></Box>
+ */
+declare const surface: (props?: ({
+    padding?: "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "nbsp" | "card" | "gutter" | "section" | "page" | null | undefined;
+    paddingX?: "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "nbsp" | "card" | "gutter" | "section" | "page" | null | undefined;
+    paddingY?: "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "nbsp" | "card" | "gutter" | "section" | "page" | null | undefined;
+    background?: "none" | "surface" | "subtle" | "inset" | "inverse" | "brand" | null | undefined;
+    border?: "none" | "subtle" | "default" | "strong" | null | undefined;
+    borderRadius?: "none" | "sm" | "md" | "lg" | "xl" | "2xl" | "full" | null | undefined;
+    boxShadow?: "none" | "sm" | "md" | "lg" | "xl" | null | undefined;
+    maxWidth?: "sm" | "md" | "lg" | "xl" | "full" | "prose" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+type SurfaceProps = VariantProps<typeof surface>;
+declare const flex: (props?: ({
+    direction?: "row" | "column" | null | undefined;
+    gap?: "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "nbsp" | "card" | "gutter" | "section" | "page" | null | undefined;
+    align?: "start" | "center" | "end" | "stretch" | "baseline" | null | undefined;
+    justify?: "start" | "center" | "end" | "between" | "around" | null | undefined;
+    wrap?: boolean | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+type FlexProps = VariantProps<typeof flex>;
+interface BoxProps extends React.HTMLAttributes<HTMLDivElement>, SurfaceProps {
+    asChild?: boolean;
+}
+declare const Box: React.ForwardRefExoticComponent<BoxProps & React.RefAttributes<HTMLDivElement>>;
+interface StackProps extends React.HTMLAttributes<HTMLDivElement>, FlexProps, SurfaceProps {
+    asChild?: boolean;
+}
+declare const Stack: React.ForwardRefExoticComponent<StackProps & React.RefAttributes<HTMLDivElement>>;
+declare const grid: (props?: ({
+    cols?: 1 | 2 | 3 | 4 | 5 | 6 | 12 | null | undefined;
+    mdCols?: 1 | 2 | 3 | 4 | 5 | 6 | 12 | null | undefined;
+    gap?: "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "nbsp" | "card" | "gutter" | "section" | "page" | null | undefined;
+    align?: "start" | "center" | "end" | "stretch" | null | undefined;
+    justify?: "start" | "center" | "end" | "stretch" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+interface GridProps extends React.HTMLAttributes<HTMLDivElement>, VariantProps<typeof grid> {
+    asChild?: boolean;
+}
+declare const Grid: React.ForwardRefExoticComponent<GridProps & React.RefAttributes<HTMLDivElement>>;
+/**
+ * The machine-readable layout contract. An AI/registry reads this to know the
+ * exact allowed values for every layout prop — so generated layouts are picked
+ * from a closed set, never invented. Spacing mixes generic steps with the
+ * practical Windforge spacing tokens.
+ */
+declare const layoutVocabulary: {
+    readonly spacing: readonly ["none", "xs", "sm", "md", "lg", "xl", "2xl", "nbsp", "card", "gutter", "section", "page"];
+    readonly direction: readonly ["row", "column"];
+    readonly align: readonly ["start", "center", "end", "stretch", "baseline"];
+    readonly justify: readonly ["start", "center", "end", "between", "around"];
+    readonly background: readonly ["none", "surface", "subtle", "inset", "inverse", "brand"];
+    readonly border: readonly ["none", "default", "subtle", "strong"];
+    readonly borderRadius: readonly ["none", "sm", "md", "lg", "xl", "2xl", "full"];
+    readonly boxShadow: readonly ["none", "sm", "md", "lg", "xl"];
+    readonly maxWidth: readonly ["sm", "md", "lg", "xl", "prose", "full"];
+    readonly gridCols: readonly [1, 2, 3, 4, 5, 6, 12];
+};
+
+/**
+ * catalog.ts — machine-readable component registry for @windforge/ui.
+ *
+ * An AI or code-generation tool reads this to know the exact closed set of
+ * components and the allowed values for every enum prop. Values are extracted
+ * directly from the cva variant definitions in each component file; nothing
+ * is invented here.
+ */
+
+interface ComponentSpec {
+    /** one-line purpose */
+    summary: string;
+    /** closed-vocabulary props → their allowed values (enums only) */
+    props?: Record<string, readonly string[]>;
+    /** notable boolean/other props, name → short note */
+    flags?: Record<string, string>;
+}
+
+declare const catalog: Record<string, ComponentSpec>;
+
+/**
+ * `cn` — merge conditional class lists and resolve Tailwind conflicts.
+ * The one utility every component uses to compose token-driven classes.
+ */
+declare function cn(...inputs: ClassValue[]): string;
+
+/** Subscribe to a media query; SSR-safe (returns false until mounted). */
+declare function useMediaQuery(query: string): boolean;
+
+/**
+ * RECIPES — named class-fragment bundles shared across components.
+ *
+ * These collapse the utility groups that repeat verbatim across many primitives
+ * (focus rings, floating surfaces, menu rows, overlays) into one named class
+ * each, so a component reads as `cn(floatingPanel, '…specifics…')` instead of a
+ * wall of utilities. Compose them with `cn()` — because `cn` runs tailwind-merge,
+ * a component can override any piece simply by adding the conflicting utility
+ * after the recipe (e.g. `cn(floatingPanel, 'rounded-xl shadow-lg')`).
+ *
+ * Every utility here resolves to a token (`var(--wf-*)`), so these stay
+ * theme- and accent-aware: the class is stable, the values move underneath it.
+ */
+/** Keyboard focus ring for standalone interactive controls (buttons, triggers, thumbs). */
+declare const focusRing: string;
+/** Focus ring with no offset — for controls that sit flush inside a container. */
+declare const focusRingInset = "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring";
+/** Focus treatment for text fields — recolors the border and adds a ring. */
+declare const focusRingField = "focus-visible:outline-none focus-visible:border-focus focus-visible:ring-2 focus-visible:ring-ring";
+/**
+ * Floating surface for popovers / menus / listboxes. Radius (`rounded-lg`) and
+ * shadow (`shadow-md`) are sensible defaults — override per component via `cn`.
+ * Padding, width, max-height and entrance animation are left to the caller.
+ */
+declare const floatingPanel = "z-50 rounded-lg border border-border bg-surface text-primary shadow-md outline-none";
+/**
+ * Structural recipe for a selectable row inside a menu / listbox. Intentionally
+ * carries no focus colors or padding — those differ per surface (dropdown and
+ * select both use `focus:bg-surface-inset`; autocomplete highlights the same way).
+ */
+declare const menuItem: string;
+/** Full-screen scrim behind modal surfaces (dialog, sheet). */
+declare const overlayBackdrop = "fixed inset-0 z-50 bg-overlay animate-fade-in";
+/** The corner dismiss (×) button shared by dialog and sheet. Pair with `focusRingInset`. */
+declare const dismissButton = "absolute right-4 top-4 rounded-md p-1 text-secondary opacity-70 transition-opacity hover:opacity-100";
+
+/** Strip the styling escape hatch. Applied to every component except the
+ *  layout/building-block primitives (Box, Stack, Grid). */
+type NoStyle<T> = Omit<T, 'className' | 'style'>;
+
+/**
+ * Button — emphasis comes from a three-tier hierarchy (primary / secondary /
+ * tertiary), never from hue. `destructive` is the one semantic exception.
+ * Every colour is a token; nothing here is a raw value.
+ */
+declare const buttonVariants: (props?: ({
+    variant?: "link" | "primary" | "secondary" | "tertiary" | "destructive" | null | undefined;
+    size?: "sm" | "md" | "lg" | "icon" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+interface ButtonProps extends NoStyle<React.ButtonHTMLAttributes<HTMLButtonElement>>, VariantProps<typeof buttonVariants> {
+    asChild?: boolean;
+}
+declare const Button: React.ForwardRefExoticComponent<ButtonProps & React.RefAttributes<HTMLButtonElement>>;
+
+/**
+ * ButtonGroup — joins a row of Buttons into one segmented control: shared edges,
+ * single outer radius, collapsed seams. Put `<Button>`s (any variant) inside.
+ */
+declare const ButtonGroup: React.ForwardRefExoticComponent<NoStyle<React.HTMLAttributes<HTMLDivElement>> & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * ToggleButtonGroup / ToggleButton — a segmented control. `type="single"` keeps
+ * one value selected; `type="multiple"` keeps an array. Controlled via
+ * `value`/`onValueChange`. Buttons share edges like a ButtonGroup.
+ */
+type SingleProps = {
+    type?: 'single';
+    value: string | null;
+    onValueChange: (value: string | null) => void;
+};
+type MultipleProps = {
+    type: 'multiple';
+    value: string[];
+    onValueChange: (value: string[]) => void;
+};
+type ToggleButtonGroupProps = (SingleProps | MultipleProps) & NoStyle<Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange'>>;
+declare function ToggleButtonGroup({ type, value, onValueChange, children, ...props }: ToggleButtonGroupProps): React.JSX.Element;
+interface ToggleButtonProps extends NoStyle<React.ButtonHTMLAttributes<HTMLButtonElement>> {
+    value: string;
+}
+declare const ToggleButton: React.ForwardRefExoticComponent<ToggleButtonProps & React.RefAttributes<HTMLButtonElement>>;
+
+declare const badgeVariants: (props?: ({
+    variant?: "subtle" | "brand" | "neutral" | "outline" | "success" | "warning" | "error" | "info" | null | undefined;
+    size?: "sm" | "md" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+interface BadgeProps extends NoStyle<React.HTMLAttributes<HTMLSpanElement>>, VariantProps<typeof badgeVariants> {
+}
+declare function Badge({ variant, size, ...props }: BadgeProps): React.JSX.Element;
+
+/**
+ * Chip — an interactive pill: clickable (filter/selection) and optionally
+ * deletable. Distinct from `Badge`, which is a static label. Set `selected` for
+ * the active state and pass `onDelete` to show a trailing ✕.
+ */
+declare const chip: (props?: ({
+    selected?: boolean | null | undefined;
+    clickable?: boolean | null | undefined;
+    size?: "sm" | "md" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+interface ChipProps extends NoStyle<Omit<React.HTMLAttributes<HTMLElement>, 'onClick'>>, VariantProps<typeof chip> {
+    onClick?: React.MouseEventHandler<HTMLButtonElement>;
+    /** When provided, renders a trailing ✕ that calls this instead of selecting. */
+    onDelete?: () => void;
+    disabled?: boolean;
+    icon?: React.ReactNode;
+}
+declare const Chip: React.ForwardRefExoticComponent<ChipProps & React.RefAttributes<HTMLElement>>;
+
+/**
+ * Text — the typography primitive (our `Typography`). Size, weight, tone and
+ * alignment are a closed token vocabulary; nothing renders off-scale. Renders a
+ * `<p>` by default; use `asChild` for the right semantic element:
+ *
+ *   <Text size="3xl" weight="bold" asChild><h1>Title</h1></Text>
+ *   <Text tone="muted">Body copy</Text>
+ *   <Text span weight="medium">inline label</Text>   // inline <span>, not a block <p>
+ *   <Text variant="inline-code">defaultOpen</Text>   // inline <code> within prose
+ */
+declare const text: (props?: ({
+    size?: "sm" | "lg" | "xl" | "2xl" | "base" | "3xl" | "4xl" | "5xl" | "6xl" | null | undefined;
+    weight?: "bold" | "light" | "regular" | "medium" | "semibold" | null | undefined;
+    tone?: "subtle" | "inverse" | "brand" | "default" | "link" | "muted" | "disabled" | "gradient" | null | undefined;
+    align?: "center" | "left" | "right" | null | undefined;
+    truncate?: boolean | null | undefined;
+    mono?: boolean | null | undefined;
+    variant?: "inline-code" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+interface TextProps extends NoStyle<React.HTMLAttributes<HTMLElement>>, VariantProps<typeof text> {
+    asChild?: boolean;
+    /** Render inline as a `<span>` instead of a block `<p>` — for labels, chips and text inside flex rows. */
+    span?: boolean;
+}
+declare const Text: React.ForwardRefExoticComponent<TextProps & React.RefAttributes<HTMLElement>>;
+/**
+ * Headings — semantic `H1`–`H6` components. Each picks the right element and a
+ * sensible default size; override `size`/`weight`/`tone` to decouple visual
+ * scale from document outline.
+ *
+ *   <H1>Page title</H1>
+ *   <H3 size="lg">Section</H3>
+ */
+interface HeadingProps extends NoStyle<React.HTMLAttributes<HTMLHeadingElement>>, Pick<VariantProps<typeof text>, 'size' | 'weight' | 'tone' | 'align' | 'truncate'> {
+}
+declare const H1: React.ForwardRefExoticComponent<HeadingProps & React.RefAttributes<HTMLHeadingElement>>;
+declare const H2: React.ForwardRefExoticComponent<HeadingProps & React.RefAttributes<HTMLHeadingElement>>;
+declare const H3: React.ForwardRefExoticComponent<HeadingProps & React.RefAttributes<HTMLHeadingElement>>;
+declare const H4: React.ForwardRefExoticComponent<HeadingProps & React.RefAttributes<HTMLHeadingElement>>;
+declare const H5: React.ForwardRefExoticComponent<HeadingProps & React.RefAttributes<HTMLHeadingElement>>;
+declare const H6: React.ForwardRefExoticComponent<HeadingProps & React.RefAttributes<HTMLHeadingElement>>;
+
+/**
+ * Link — an inline anchor in the link color (blue). Use `asChild` to wrap a
+ * router link while keeping the styling:  <Link asChild><RouterLink to="…"/></Link>
+ */
+declare const link: (props?: ({
+    underline?: "none" | "hover" | "always" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+interface LinkProps extends NoStyle<React.AnchorHTMLAttributes<HTMLAnchorElement>>, VariantProps<typeof link> {
+    asChild?: boolean;
+}
+declare const Link: React.ForwardRefExoticComponent<LinkProps & React.RefAttributes<HTMLAnchorElement>>;
+
+/**
+ * Card — a surface that groups related content. Pass `title`, `description`,
+ * an optional `headerAction` (e.g. a Badge opposite the title), `footer`
+ * actions, and the body as `children`; there are no sub-components to assemble.
+ * Under the hood it's a `Box` with the universal surface preset, so any Box prop
+ * (`boxShadow`, `borderRadius`, …) still applies.
+ *
+ *   <Card title="Deploy preview" description="Pushed 4 minutes ago"
+ *         footer={<Button>Visit preview</Button>}>
+ *     Vercel finished building your branch.
+ *   </Card>
+ */
+type CardPadding = NonNullable<BoxProps['padding']>;
+interface CardProps extends Omit<NoStyle<BoxProps>, 'title' | 'paddingX' | 'paddingY'> {
+    title?: React.ReactNode;
+    description?: React.ReactNode;
+    /** Trailing header content — sits opposite the title (e.g. a status Badge). */
+    headerAction?: React.ReactNode;
+    /** Footer content — typically buttons. */
+    footer?: React.ReactNode;
+    /** Inset for the header/body/footer sections. Overrides (never stacks on) the
+     *  default; defaults to the `card` spacing token. */
+    padding?: CardPadding;
+}
+declare const Card: React.ForwardRefExoticComponent<CardProps & React.RefAttributes<HTMLDivElement>>;
+
+interface InputProps extends NoStyle<React.InputHTMLAttributes<HTMLInputElement>> {
+    /** Error state — red control outline + aria-invalid. Usually set for you by FormField. */
+    invalid?: boolean;
+}
+declare const Input: React.ForwardRefExoticComponent<InputProps & React.RefAttributes<HTMLInputElement>>;
+
+interface TextareaProps extends NoStyle<React.TextareaHTMLAttributes<HTMLTextAreaElement>> {
+    /** Error state — red control outline + aria-invalid. Usually set for you by FormField. */
+    invalid?: boolean;
+}
+declare const Textarea: React.ForwardRefExoticComponent<TextareaProps & React.RefAttributes<HTMLTextAreaElement>>;
+
+declare const Label: React.ForwardRefExoticComponent<NoStyle<Omit<LabelPrimitive.LabelProps & React.RefAttributes<HTMLLabelElement>, "ref">> & React.RefAttributes<HTMLLabelElement>>;
+
+/**
+ * FormField — the on-system way to assemble a labelled control. For the common
+ * case it renders the field for you: pass `label`, `description`, `placeholder`,
+ * and `type` and it owns an `Input`. To wrap a different control (Textarea,
+ * Select, Autocomplete) pass it as the single child instead. Either way FormField
+ * generates the ids and wires `htmlFor`, `aria-describedby`, `aria-invalid`, and
+ * the error/required state — so accessible, validated forms stay a one-liner and
+ * never drift.
+ *
+ *   <FormField label="Email" description="We'll only use this to sign you in."
+ *              type="email" placeholder="you@example.com" error={errors.email} required />
+ *
+ *   <FormField label="Notes" description="Optional.">
+ *     <Textarea rows={3} />
+ *   </FormField>
+ *
+ * Per the system's hue policy, the error MESSAGE text stays the normal foreground;
+ * only the leading icon (and the control's outline) carry the status hue — matching
+ * Alert and Toast. The state is never conveyed by color alone (icon + border + text).
+ */
+interface FormFieldProps extends NoStyle<Omit<React.HTMLAttributes<HTMLDivElement>, 'children'>> {
+    label?: React.ReactNode;
+    /** Helper text below the label. Kept as normal foreground — meant to be read. */
+    description?: React.ReactNode;
+    /** Placeholder forwarded onto the control. A prop set directly on a child wins. */
+    placeholder?: string;
+    /** Input type for the default control (text, email, password, …). Forwarded onto the control. */
+    type?: React.HTMLInputTypeAttribute;
+    /** Error message. Its presence puts the control into the invalid state. */
+    error?: React.ReactNode;
+    required?: boolean;
+    /** Escape hatch: a non-Input control to wrap. Omit to let FormField render an Input. */
+    children?: React.ReactElement;
+}
+declare const FormField: React.ForwardRefExoticComponent<FormFieldProps & React.RefAttributes<HTMLDivElement>>;
+
+declare const Separator: React.ForwardRefExoticComponent<NoStyle<Omit<SeparatorPrimitive.SeparatorProps & React.RefAttributes<HTMLDivElement>, "ref">> & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Skeleton — a fluid loading placeholder. It fills its parent (`h-full w-full`),
+ * so you size it by wrapping it in a Box: `<Box className="h-4 w-2/3"><Skeleton/></Box>`.
+ */
+declare function Skeleton({ ...props }: NoStyle<React.HTMLAttributes<HTMLDivElement>>): React.JSX.Element;
+
+/**
+ * CodeBlock — the on-system, syntax-highlighted code surface. One source of truth
+ * for every snippet in the system (docs, examples, anywhere). Highlighting runs
+ * locally via prism-react-renderer — no network, no API. The token theme below is
+ * built from `var(--wf-*)` references, so colors resolve live: the code re-skins
+ * with light/dark and with a brand swap automatically, no JS reactivity needed.
+ *
+ * Takes no className by design — its surface is fixed so every snippet in a product
+ * renders identically.
+ *
+ *   <CodeBlock code={src} language="tsx" filename="button.tsx" showLineNumbers />
+ */
+interface CodeBlockProps {
+    code: string;
+    /** Prism language id. Default 'tsx'. */
+    language?: string;
+    /** Optional header filename; shown left of the language label. */
+    filename?: string;
+    /** Render a left gutter with 1-based line numbers. */
+    showLineNumbers?: boolean;
+    /** 1-based line numbers to emphasize. */
+    highlightLines?: number[];
+    /** Soft-wrap long lines instead of scrolling horizontally. */
+    wrap?: boolean;
+    /** Max height before vertical scroll, e.g. '24rem'. */
+    maxHeight?: string;
+    /** Show the copy button (default true). */
+    copyable?: boolean;
+}
+declare function CodeBlock({ code, language, filename, showLineNumbers, highlightLines, wrap, maxHeight, copyable, }: CodeBlockProps): React.JSX.Element;
+
+declare const alertVariants: (props?: ({
+    variant?: "neutral" | "success" | "warning" | "error" | "info" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+/**
+ * Alert — an inline status message. Pass `title`, `description`, an optional
+ * leading `icon`, and optional `actions`; there are no sub-components to
+ * assemble. For a fully custom body, use `children` instead of `description`.
+ *
+ *   <Alert variant="info" icon={<Info />} title="Heads up"
+ *          description="Your trial ends in 5 days." />
+ */
+interface AlertProps extends Omit<NoStyle<React.HTMLAttributes<HTMLDivElement>>, 'title'>, VariantProps<typeof alertVariants> {
+    title?: React.ReactNode;
+    description?: React.ReactNode;
+    /** Leading status icon (a lucide element). Inherits the variant hue. */
+    icon?: React.ReactNode;
+    /** Trailing actions — typically buttons or links. */
+    actions?: React.ReactNode;
+}
+declare const Alert: React.ForwardRefExoticComponent<AlertProps & React.RefAttributes<HTMLDivElement>>;
+
+declare const Switch: React.ForwardRefExoticComponent<NoStyle<Omit<SwitchPrimitives.SwitchProps & React.RefAttributes<HTMLButtonElement>, "ref">> & React.RefAttributes<HTMLButtonElement>>;
+
+declare const Checkbox: React.ForwardRefExoticComponent<NoStyle<Omit<CheckboxPrimitive.CheckboxProps & React.RefAttributes<HTMLButtonElement>, "ref">> & React.RefAttributes<HTMLButtonElement>>;
+
+declare const RadioGroup: React.ForwardRefExoticComponent<NoStyle<Omit<RadioGroupPrimitive.RadioGroupProps & React.RefAttributes<HTMLDivElement>, "ref">> & React.RefAttributes<HTMLDivElement>>;
+declare const RadioGroupItem: React.ForwardRefExoticComponent<NoStyle<Omit<RadioGroupPrimitive.RadioGroupItemProps & React.RefAttributes<HTMLButtonElement>, "ref">> & React.RefAttributes<HTMLButtonElement>>;
+
+/**
+ * Tabs — pass an `items` array for the common case (the component renders the
+ * list, triggers, and panels for you), or compose `TabsList`/`TabsTrigger`/
+ * `TabsContent` by hand for full control.
+ *
+ *   <Tabs defaultValue="overview" items={[
+ *     { value: 'overview', label: 'Overview', content: <Overview /> },
+ *     { value: 'usage', label: 'Usage', content: <Usage /> },
+ *   ]} />
+ */
+interface TabItem {
+    value: string;
+    label: React.ReactNode;
+    content: React.ReactNode;
+    disabled?: boolean;
+}
+interface TabsProps extends NoStyle<React.ComponentPropsWithoutRef<typeof TabsPrimitive.Root>> {
+    /** Declarative tabs. Omit to compose the primitives as children instead. */
+    items?: TabItem[];
+}
+declare const Tabs: React.ForwardRefExoticComponent<TabsProps & React.RefAttributes<HTMLDivElement>>;
+declare const TabsList: React.ForwardRefExoticComponent<NoStyle<Omit<TabsPrimitive.TabsListProps & React.RefAttributes<HTMLDivElement>, "ref">> & React.RefAttributes<HTMLDivElement>>;
+declare const TabsTrigger: React.ForwardRefExoticComponent<NoStyle<Omit<TabsPrimitive.TabsTriggerProps & React.RefAttributes<HTMLButtonElement>, "ref">> & React.RefAttributes<HTMLButtonElement>>;
+declare const TabsContent: React.ForwardRefExoticComponent<NoStyle<Omit<TabsPrimitive.TabsContentProps & React.RefAttributes<HTMLDivElement>, "ref">> & React.RefAttributes<HTMLDivElement>>;
+
+declare const TooltipProvider: React.FC<TooltipPrimitive.TooltipProviderProps>;
+declare const Tooltip: React.FC<TooltipPrimitive.TooltipProps>;
+declare const TooltipTrigger: React.ForwardRefExoticComponent<TooltipPrimitive.TooltipTriggerProps & React.RefAttributes<HTMLButtonElement>>;
+declare const TooltipContent: React.ForwardRefExoticComponent<NoStyle<Omit<TooltipPrimitive.TooltipContentProps & React.RefAttributes<HTMLDivElement>, "ref">> & React.RefAttributes<HTMLDivElement>>;
+
+declare const SelectGroup: React.ForwardRefExoticComponent<SelectPrimitive.SelectGroupProps & React.RefAttributes<HTMLDivElement>>;
+declare const SelectValue: React.ForwardRefExoticComponent<SelectPrimitive.SelectValueProps & React.RefAttributes<HTMLSpanElement>>;
+/**
+ * Select — pass an `options` array for the common case (the component renders
+ * the trigger, value, and items), or compose `SelectTrigger`/`SelectContent`/
+ * `SelectItem` by hand for groups, labels, or custom triggers. Value props
+ * (`value`/`defaultValue`/`onValueChange`) pass through to the Radix root.
+ *
+ *   <Select placeholder="Pick one" options={[
+ *     { value: 'a', label: 'Apple' },
+ *     { value: 'b', label: 'Banana' },
+ *   ]} />
+ */
+interface SelectOption {
+    value: string;
+    label: React.ReactNode;
+    disabled?: boolean;
+}
+interface SelectProps extends React.ComponentPropsWithoutRef<typeof SelectPrimitive.Root> {
+    /** Declarative options. Omit to compose the primitives as children instead. */
+    options?: SelectOption[];
+    placeholder?: string;
+    /** Error state — red trigger outline + aria-invalid. Usually set by FormField. */
+    invalid?: boolean;
+    /** Forwarded to the trigger so FormField can wire label/description/error. */
+    id?: string;
+    'aria-describedby'?: string;
+}
+declare function Select({ options, placeholder, invalid, id, children, ...props }: SelectProps): React.JSX.Element;
+declare const SelectTrigger: React.ForwardRefExoticComponent<NoStyle<Omit<SelectPrimitive.SelectTriggerProps & React.RefAttributes<HTMLButtonElement>, "ref">> & {
+    invalid?: boolean;
+} & React.RefAttributes<HTMLButtonElement>>;
+declare const SelectContent: React.ForwardRefExoticComponent<NoStyle<Omit<SelectPrimitive.SelectContentProps & React.RefAttributes<HTMLDivElement>, "ref">> & React.RefAttributes<HTMLDivElement>>;
+declare const SelectLabel: React.ForwardRefExoticComponent<NoStyle<Omit<SelectPrimitive.SelectLabelProps & React.RefAttributes<HTMLDivElement>, "ref">> & React.RefAttributes<HTMLDivElement>>;
+declare const SelectItem: React.ForwardRefExoticComponent<NoStyle<Omit<SelectPrimitive.SelectItemProps & React.RefAttributes<HTMLDivElement>, "ref">> & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Autocomplete — a searchable single-select combobox. Type to filter; arrow keys
+ * move the highlight, Enter selects, Escape closes. Controlled via
+ * `value`/`onValueChange`. Positioning/portalling come from the shared Radix
+ * popper (same engine as Select/Tooltip/Popover); the combobox logic and
+ * `listbox`/`option` ARIA are ours.
+ */
+interface AutocompleteOption {
+    value: string;
+    label: string;
+}
+interface AutocompleteProps {
+    options: AutocompleteOption[];
+    value?: string | null;
+    onValueChange?: (value: string | null) => void;
+    placeholder?: string;
+    emptyText?: string;
+    disabled?: boolean;
+    id?: string;
+    /** Error state — red field outline + aria-invalid. Usually set by FormField. */
+    invalid?: boolean;
+    'aria-describedby'?: string;
+}
+declare function Autocomplete({ options, value, onValueChange, placeholder, emptyText, disabled, id, invalid, 'aria-describedby': ariaDescribedBy, }: AutocompleteProps): React.JSX.Element;
+
+/**
+ * Modal — the low-level, fully composable overlay primitive (Radix Dialog under
+ * the hood). Compose freely: `Modal > ModalTrigger + ModalContent`. For the
+ * common title/description/actions case, reach for `Dialog`, the props-based
+ * convenience built on this — there are no header/title/footer sub-components.
+ */
+declare const Modal: React.FC<DialogPrimitive.DialogProps>;
+declare const ModalTrigger: React.ForwardRefExoticComponent<DialogPrimitive.DialogTriggerProps & React.RefAttributes<HTMLButtonElement>>;
+declare const ModalClose: React.ForwardRefExoticComponent<DialogPrimitive.DialogCloseProps & React.RefAttributes<HTMLButtonElement>>;
+declare const ModalPortal: React.FC<DialogPrimitive.DialogPortalProps>;
+declare const ModalOverlay: React.ForwardRefExoticComponent<NoStyle<Omit<DialogPrimitive.DialogOverlayProps & React.RefAttributes<HTMLDivElement>, "ref">> & React.RefAttributes<HTMLDivElement>>;
+declare const modalContent: (props?: ({
+    size?: "sm" | "md" | "lg" | "xl" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+interface ModalContentProps extends NoStyle<React.ComponentPropsWithoutRef<typeof DialogPrimitive.Content>>, VariantProps<typeof modalContent> {
+    /** Hide the default corner close button. */
+    hideClose?: boolean;
+}
+declare const ModalContent: React.ForwardRefExoticComponent<ModalContentProps & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Dialog — the opinionated, props-based convenience built on `Modal`. Pass
+ * `title`, `description`, and `actions` (buttons) as nodes; body goes in
+ * `children`. There are no header/title/footer sub-components to assemble — for
+ * full control over structure, drop down to the `Modal` primitives directly.
+ *
+ *   <Dialog
+ *     trigger={<Button>Delete</Button>}
+ *     title="Delete project?"
+ *     description="This can't be undone."
+ *     actions={<><Button variant="secondary">Cancel</Button><Button variant="destructive">Delete</Button></>}
+ *   />
+ */
+interface DialogProps {
+    title: React.ReactNode;
+    description?: React.ReactNode;
+    /** Footer content — typically buttons. */
+    actions?: React.ReactNode;
+    /** The element that opens the dialog. Omit for fully controlled use. */
+    trigger?: React.ReactNode;
+    children?: React.ReactNode;
+    size?: ModalContentProps['size'];
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+}
+declare function Dialog({ title, description, actions, trigger, children, size, open, defaultOpen, onOpenChange, }: DialogProps): React.JSX.Element;
+
+/**
+ * Pagination — controlled page navigation. `page` is 1-based; `count` is the
+ * total number of pages. Renders first/last, a window of siblings around the
+ * current page, and ellipses. Emits `onPageChange`.
+ */
+interface PaginationProps extends NoStyle<Omit<React.HTMLAttributes<HTMLElement>, 'onChange'>> {
+    page: number;
+    count: number;
+    onPageChange: (page: number) => void;
+    siblingCount?: number;
+}
+declare function Pagination({ page, count, onPageChange, siblingCount, ...props }: PaginationProps): React.JSX.Element;
+
+/**
+ * Stepper — progress through a sequence of steps. `activeStep` is the 0-based
+ * index of the current step; earlier steps render as completed (✓). Horizontal
+ * by default; pass `orientation="vertical"` for a stacked flow.
+ */
+interface Step {
+    label: string;
+    description?: string;
+}
+interface StepperProps extends NoStyle<React.HTMLAttributes<HTMLOListElement>> {
+    steps: Step[];
+    activeStep: number;
+    orientation?: 'horizontal' | 'vertical';
+}
+declare function Stepper({ steps, activeStep, orientation, ...props }: StepperProps): React.JSX.Element;
+
+/**
+ * Toast / Snackbar — a transient message. Call `toast({...})` from anywhere
+ * (event handlers, effects, outside React), and render `<Toaster />` once near
+ * the app root. Text stays the normal foreground; only the icon carries the
+ * status hue (matching Alert).
+ */
+type ToastVariant = 'neutral' | 'success' | 'error' | 'warning' | 'info';
+interface ToastOptions {
+    title?: React.ReactNode;
+    description?: React.ReactNode;
+    variant?: ToastVariant;
+    duration?: number;
+    action?: React.ReactNode;
+}
+declare function toast(options: ToastOptions): number;
+declare function dismissToast(id: number): void;
+declare function Toaster(): React.ReactPortal | null;
+
+/**
+ * Accordion — pass an `items` array for the common case (the component renders
+ * each item, trigger, and panel), or compose `AccordionItem`/`AccordionTrigger`/
+ * `AccordionContent` by hand. `type`/`collapsible`/`defaultValue` pass through
+ * to the underlying Radix root.
+ *
+ *   <Accordion type="single" collapsible items={[
+ *     { value: 'a', trigger: 'What is Windforge?', content: <p>…</p> },
+ *   ]} />
+ */
+interface AccordionItemData {
+    value: string;
+    trigger: React.ReactNode;
+    content: React.ReactNode;
+    disabled?: boolean;
+}
+type AccordionProps = React.ComponentPropsWithoutRef<typeof AccordionPrimitive.Root> & {
+    /** Declarative items. Omit to compose the primitives as children instead. */
+    items?: AccordionItemData[];
+};
+declare const Accordion: React.ForwardRefExoticComponent<AccordionProps & React.RefAttributes<HTMLDivElement>>;
+declare const AccordionItem: React.ForwardRefExoticComponent<NoStyle<Omit<AccordionPrimitive.AccordionItemProps & React.RefAttributes<HTMLDivElement>, "ref">> & React.RefAttributes<HTMLDivElement>>;
+declare const AccordionTrigger: React.ForwardRefExoticComponent<NoStyle<Omit<AccordionPrimitive.AccordionTriggerProps & React.RefAttributes<HTMLButtonElement>, "ref">> & React.RefAttributes<HTMLButtonElement>>;
+declare const AccordionContent: React.ForwardRefExoticComponent<NoStyle<Omit<AccordionPrimitive.AccordionContentProps & React.RefAttributes<HTMLDivElement>, "ref">> & React.RefAttributes<HTMLDivElement>>;
+
+declare const Avatar: React.ForwardRefExoticComponent<NoStyle<Omit<AvatarPrimitive.AvatarProps & React.RefAttributes<HTMLSpanElement>, "ref">> & VariantProps<(props?: ({
+    size?: "sm" | "md" | "lg" | "xl" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string> & React.RefAttributes<HTMLSpanElement>>;
+declare const AvatarImage: React.ForwardRefExoticComponent<NoStyle<Omit<AvatarPrimitive.AvatarImageProps & React.RefAttributes<HTMLImageElement>, "ref">> & React.RefAttributes<HTMLImageElement>>;
+declare const AvatarFallback: React.ForwardRefExoticComponent<NoStyle<Omit<AvatarPrimitive.AvatarFallbackProps & React.RefAttributes<HTMLSpanElement>, "ref">> & React.RefAttributes<HTMLSpanElement>>;
+
+declare const Progress: React.ForwardRefExoticComponent<NoStyle<Omit<ProgressPrimitive.ProgressProps & React.RefAttributes<HTMLDivElement>, "ref">> & {
+    value?: number;
+    /** Looping animation for work of unknown duration; ignores `value`. */
+    indeterminate?: boolean;
+} & React.RefAttributes<HTMLDivElement>>;
+
+declare const Slider: React.ForwardRefExoticComponent<NoStyle<Omit<SliderPrimitive.SliderProps & React.RefAttributes<HTMLSpanElement>, "ref">> & React.RefAttributes<HTMLSpanElement>>;
+
+declare const Popover: React.FC<PopoverPrimitive.PopoverProps>;
+declare const PopoverTrigger: React.ForwardRefExoticComponent<PopoverPrimitive.PopoverTriggerProps & React.RefAttributes<HTMLButtonElement>>;
+declare const PopoverAnchor: React.ForwardRefExoticComponent<PopoverPrimitive.PopoverAnchorProps & React.RefAttributes<HTMLDivElement>>;
+declare const PopoverContent: React.ForwardRefExoticComponent<NoStyle<Omit<PopoverPrimitive.PopoverContentProps & React.RefAttributes<HTMLDivElement>, "ref">> & React.RefAttributes<HTMLDivElement>>;
+
+declare const DropdownMenuTrigger: React.ForwardRefExoticComponent<DropdownMenuPrimitive.DropdownMenuTriggerProps & React.RefAttributes<HTMLButtonElement>>;
+declare const DropdownMenuGroup: React.ForwardRefExoticComponent<DropdownMenuPrimitive.DropdownMenuGroupProps & React.RefAttributes<HTMLDivElement>>;
+declare const DropdownMenuPortal: React.FC<DropdownMenuPrimitive.DropdownMenuPortalProps>;
+declare const DropdownMenuSub: React.FC<DropdownMenuPrimitive.DropdownMenuSubProps>;
+declare const DropdownMenuRadioGroup: React.ForwardRefExoticComponent<DropdownMenuPrimitive.DropdownMenuRadioGroupProps & React.RefAttributes<HTMLDivElement>>;
+declare const DropdownMenuContent: React.ForwardRefExoticComponent<NoStyle<Omit<DropdownMenuPrimitive.DropdownMenuContentProps & React.RefAttributes<HTMLDivElement>, "ref">> & React.RefAttributes<HTMLDivElement>>;
+declare const DropdownMenuItem: React.ForwardRefExoticComponent<NoStyle<Omit<DropdownMenuPrimitive.DropdownMenuItemProps & React.RefAttributes<HTMLDivElement>, "ref">> & {
+    inset?: boolean;
+} & React.RefAttributes<HTMLDivElement>>;
+declare const DropdownMenuCheckboxItem: React.ForwardRefExoticComponent<NoStyle<Omit<DropdownMenuPrimitive.DropdownMenuCheckboxItemProps & React.RefAttributes<HTMLDivElement>, "ref">> & React.RefAttributes<HTMLDivElement>>;
+declare const DropdownMenuRadioItem: React.ForwardRefExoticComponent<NoStyle<Omit<DropdownMenuPrimitive.DropdownMenuRadioItemProps & React.RefAttributes<HTMLDivElement>, "ref">> & React.RefAttributes<HTMLDivElement>>;
+declare const DropdownMenuLabel: React.ForwardRefExoticComponent<NoStyle<Omit<DropdownMenuPrimitive.DropdownMenuLabelProps & React.RefAttributes<HTMLDivElement>, "ref">> & {
+    inset?: boolean;
+} & React.RefAttributes<HTMLDivElement>>;
+declare const DropdownMenuSeparator: React.ForwardRefExoticComponent<NoStyle<Omit<DropdownMenuPrimitive.DropdownMenuSeparatorProps & React.RefAttributes<HTMLDivElement>, "ref">> & React.RefAttributes<HTMLDivElement>>;
+declare function DropdownMenuShortcut({ ...props }: NoStyle<React.HTMLAttributes<HTMLSpanElement>>): React.JSX.Element;
+declare const DropdownMenuSubTrigger: React.ForwardRefExoticComponent<NoStyle<Omit<DropdownMenuPrimitive.DropdownMenuSubTriggerProps & React.RefAttributes<HTMLDivElement>, "ref">> & {
+    inset?: boolean;
+} & React.RefAttributes<HTMLDivElement>>;
+declare const DropdownMenuSubContent: React.ForwardRefExoticComponent<NoStyle<Omit<DropdownMenuPrimitive.DropdownMenuSubContentProps & React.RefAttributes<HTMLDivElement>, "ref">> & React.RefAttributes<HTMLDivElement>>;
+/**
+ * DropdownMenu — pass a `trigger` and an `items` array for the common case (the
+ * component renders the content, items, labels, and separators), or compose the
+ * primitives (`DropdownMenuTrigger`/`DropdownMenuContent`/…) by hand for
+ * submenus, checkbox/radio groups, and other advanced layouts.
+ *
+ *   <DropdownMenu trigger={<Button>Open</Button>} items={[
+ *     { label: 'Profile', icon: <User />, shortcut: '⇧⌘P', onSelect: goProfile },
+ *     { type: 'separator' },
+ *     { label: 'Log out', onSelect: logout },
+ *   ]} />
+ */
+type DropdownMenuItemData = {
+    type?: 'item';
+    label: React.ReactNode;
+    icon?: React.ReactNode;
+    shortcut?: string;
+    onSelect?: () => void;
+    disabled?: boolean;
+} | {
+    type: 'separator';
+} | {
+    type: 'label';
+    label: React.ReactNode;
+};
+interface DropdownMenuProps extends React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.Root> {
+    /** The element that opens the menu (rendered via asChild). */
+    trigger?: React.ReactNode;
+    /** Declarative items. Omit to compose the primitives as children instead. */
+    items?: DropdownMenuItemData[];
+}
+declare function DropdownMenu({ trigger, items, children, ...props }: DropdownMenuProps): React.JSX.Element;
+
+declare const alignClass: {
+    readonly left: "text-left";
+    readonly center: "text-center";
+    readonly right: "text-right";
+};
+type Align$1 = keyof typeof alignClass;
+/**
+ * Table — pass `columns` + `data` for the common case (the component renders the
+ * header, rows, and cells), or compose `TableHeader`/`TableRow`/`TableCell` by
+ * hand for full control. Each column's `accessor` is a row key or a render
+ * function for custom cells (badges, buttons, …).
+ *
+ *   <Table
+ *     columns={[
+ *       { header: 'Name', accessor: 'name' },
+ *       { header: 'Status', accessor: (r) => <Badge>{r.status}</Badge> },
+ *       { header: 'Amount', accessor: 'amount', align: 'right' },
+ *     ]}
+ *     data={rows}
+ *   />
+ */
+interface TableColumn<Row = Record<string, React.ReactNode>> {
+    header: React.ReactNode;
+    /** A key into the row, or a render function returning the cell content. */
+    accessor: keyof Row | ((row: Row) => React.ReactNode);
+    align?: Align$1;
+}
+interface TableProps<Row = Record<string, React.ReactNode>> extends NoStyle<React.HTMLAttributes<HTMLTableElement>> {
+    columns?: TableColumn<Row>[];
+    data?: readonly Row[];
+    caption?: React.ReactNode;
+}
+declare const Table: (<Row extends Record<string, React.ReactNode>>(props: TableProps<Row> & {
+    ref?: React.ForwardedRef<HTMLTableElement>;
+}) => React.ReactElement) & {
+    displayName?: string;
+};
+declare const TableHeader: React.ForwardRefExoticComponent<NoStyle<React.HTMLAttributes<HTMLTableSectionElement>> & React.RefAttributes<HTMLTableSectionElement>>;
+declare const TableBody: React.ForwardRefExoticComponent<NoStyle<React.HTMLAttributes<HTMLTableSectionElement>> & React.RefAttributes<HTMLTableSectionElement>>;
+declare const TableFooter: React.ForwardRefExoticComponent<NoStyle<React.HTMLAttributes<HTMLTableSectionElement>> & React.RefAttributes<HTMLTableSectionElement>>;
+declare const TableRow: React.ForwardRefExoticComponent<NoStyle<React.HTMLAttributes<HTMLTableRowElement>> & React.RefAttributes<HTMLTableRowElement>>;
+declare const TableHead: React.ForwardRefExoticComponent<Omit<NoStyle<React.ThHTMLAttributes<HTMLTableCellElement>>, "align"> & {
+    align?: Align$1;
+} & React.RefAttributes<HTMLTableCellElement>>;
+declare const TableCell: React.ForwardRefExoticComponent<Omit<NoStyle<React.TdHTMLAttributes<HTMLTableCellElement>>, "align"> & {
+    align?: Align$1;
+} & React.RefAttributes<HTMLTableCellElement>>;
+declare const TableCaption: React.ForwardRefExoticComponent<NoStyle<React.HTMLAttributes<HTMLTableCaptionElement>> & React.RefAttributes<HTMLTableCaptionElement>>;
+
+/**
+ * DataTable — the batteries-included table: column sorting, row selection, and
+ * optional client-side pagination, built on the Table primitives so it stays
+ * on-system. Pass `columns` + `data` + a `rowKey`; opt into `selectable` and
+ * `pageSize`. For a purely presentational table, use Table directly.
+ *
+ *   <DataTable rowKey={(r) => r.id} selectable pageSize={10}
+ *     columns={[
+ *       { header: 'Name', accessor: 'name', sortable: true },
+ *       { header: 'Amount', accessor: 'amount', align: 'right', sortable: true },
+ *     ]}
+ *     data={rows}
+ *   />
+ */
+type Align = 'left' | 'center' | 'right';
+interface DataTableColumn<Row> {
+    header: React.ReactNode;
+    /** A row key, or a render function returning the cell content. */
+    accessor: keyof Row | ((row: Row) => React.ReactNode);
+    align?: Align;
+    sortable?: boolean;
+    /** Sort value when `accessor` is a render function (or to sort by something else). */
+    sortAccessor?: (row: Row) => string | number;
+}
+interface DataTableProps<Row> {
+    columns: DataTableColumn<Row>[];
+    data: readonly Row[];
+    /** Stable id per row — required for selection and React keys. */
+    rowKey: (row: Row) => string;
+    caption?: React.ReactNode;
+    selectable?: boolean;
+    /** Controlled selection (ids). Omit for uncontrolled. */
+    selected?: string[];
+    onSelectedChange?: (ids: string[]) => void;
+    /** Enable client-side pagination at this page size. */
+    pageSize?: number;
+    /** Empty-state content when there are no rows. */
+    emptyState?: React.ReactNode;
+}
+declare function DataTable<Row>({ columns, data, rowKey, caption, selectable, selected, onSelectedChange, pageSize, emptyState, }: DataTableProps<Row>): React.JSX.Element;
+
+/**
+ * Breadcrumb — the path to the current page. Pass an `items` array; the last
+ * item renders as the (non-link) current page, the rest as links. `label` is a
+ * ReactNode, so a crumb can carry an icon. Override `separator` to change the
+ * glyph between crumbs.
+ *
+ *   <Breadcrumb items={[
+ *     { label: 'Home', href: '/' },
+ *     { label: 'Projects', href: '/projects' },
+ *     { label: 'Windforge' },
+ *   ]} />
+ */
+interface BreadcrumbItemData {
+    label: React.ReactNode;
+    /** Link target. Omit on the final crumb (the current page). */
+    href?: string;
+}
+interface BreadcrumbProps extends NoStyle<React.ComponentPropsWithoutRef<'nav'>> {
+    items: BreadcrumbItemData[];
+    /** Separator between crumbs; defaults to a chevron. */
+    separator?: React.ReactNode;
+}
+declare const Breadcrumb: React.ForwardRefExoticComponent<BreadcrumbProps & React.RefAttributes<HTMLElement>>;
+
+declare const Sheet: React.FC<DialogPrimitive.DialogProps>;
+declare const SheetTrigger: React.ForwardRefExoticComponent<DialogPrimitive.DialogTriggerProps & React.RefAttributes<HTMLButtonElement>>;
+declare const SheetClose: React.ForwardRefExoticComponent<DialogPrimitive.DialogCloseProps & React.RefAttributes<HTMLButtonElement>>;
+declare const SheetPortal: React.FC<DialogPrimitive.DialogPortalProps>;
+declare const sheetVariants: (props?: ({
+    side?: "left" | "right" | "top" | "bottom" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+/**
+ * SheetContent — the sliding panel. Pass `title`, `description`, and `footer`
+ * actions as props (no header/title/footer sub-components to assemble); the
+ * body goes in `children`. `title`/`description` render as accessible Radix
+ * Dialog nodes.
+ */
+interface SheetContentProps extends Omit<NoStyle<React.ComponentPropsWithoutRef<typeof DialogPrimitive.Content>>, 'title'>, VariantProps<typeof sheetVariants> {
+    title?: React.ReactNode;
+    description?: React.ReactNode;
+    /** Footer content pinned to the bottom — typically buttons. */
+    footer?: React.ReactNode;
+}
+declare const SheetContent: React.ForwardRefExoticComponent<SheetContentProps & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * MultiSelect — a searchable multi-value combobox. Selected values render as
+ * removable tags in the field; the dropdown filters as you type and toggles
+ * options with the keyboard (↑/↓ move, Enter toggles, Backspace removes the last
+ * tag on an empty query). Controlled via `value`/`onValueChange`. Shares the Radix
+ * popper and floating-panel recipe with Select/Autocomplete.
+ */
+interface MultiSelectOption {
+    value: string;
+    label: string;
+}
+interface MultiSelectProps {
+    options: MultiSelectOption[];
+    value: string[];
+    onValueChange: (value: string[]) => void;
+    placeholder?: string;
+    emptyText?: string;
+    disabled?: boolean;
+    invalid?: boolean;
+    id?: string;
+    'aria-describedby'?: string;
+}
+declare function MultiSelect({ options, value, onValueChange, placeholder, emptyText, disabled, invalid, id, 'aria-describedby': ariaDescribedBy, }: MultiSelectProps): React.JSX.Element;
+
+/**
+ * Command — a fast, filterable command menu / palette (cmdk under the hood),
+ * token-styled to match the system. Compose `Command` > `CommandInput` +
+ * `CommandList` (`CommandEmpty`/`CommandGroup`/`CommandItem`/`CommandSeparator`),
+ * or drop the whole thing into `CommandDialog` for a ⌘K palette.
+ *
+ *   <CommandDialog open={open} onOpenChange={setOpen}>
+ *     <CommandInput placeholder="Type a command…" />
+ *     <CommandList>
+ *       <CommandEmpty>No results.</CommandEmpty>
+ *       <CommandGroup heading="Actions">
+ *         <CommandItem onSelect={…}>New file</CommandItem>
+ *       </CommandGroup>
+ *     </CommandList>
+ *   </CommandDialog>
+ */
+declare const Command: React.ForwardRefExoticComponent<NoStyle<Omit<{
+    children?: React.ReactNode;
+} & Pick<Pick<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "key" | keyof React.HTMLAttributes<HTMLDivElement>> & {
+    ref?: React.Ref<HTMLDivElement>;
+} & {
+    asChild?: boolean;
+}, "asChild" | "key" | keyof React.HTMLAttributes<HTMLDivElement>> & {
+    label?: string;
+    shouldFilter?: boolean;
+    filter?: (value: string, search: string, keywords?: string[]) => number;
+    defaultValue?: string;
+    value?: string;
+    onValueChange?: (value: string) => void;
+    loop?: boolean;
+    disablePointerSelection?: boolean;
+    vimBindings?: boolean;
+} & React.RefAttributes<HTMLDivElement>, "ref">> & React.RefAttributes<HTMLDivElement>>;
+declare const CommandInput: React.ForwardRefExoticComponent<NoStyle<Omit<Omit<Pick<Pick<React.DetailedHTMLProps<React.InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, "key" | keyof React.InputHTMLAttributes<HTMLInputElement>> & {
+    ref?: React.Ref<HTMLInputElement>;
+} & {
+    asChild?: boolean;
+}, "asChild" | "key" | keyof React.InputHTMLAttributes<HTMLInputElement>>, "onChange" | "value" | "type"> & {
+    value?: string;
+    onValueChange?: (search: string) => void;
+} & React.RefAttributes<HTMLInputElement>, "ref">> & React.RefAttributes<HTMLInputElement>>;
+declare const CommandList: React.ForwardRefExoticComponent<NoStyle<Omit<{
+    children?: React.ReactNode;
+} & Pick<Pick<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "key" | keyof React.HTMLAttributes<HTMLDivElement>> & {
+    ref?: React.Ref<HTMLDivElement>;
+} & {
+    asChild?: boolean;
+}, "asChild" | "key" | keyof React.HTMLAttributes<HTMLDivElement>> & {
+    label?: string;
+} & React.RefAttributes<HTMLDivElement>, "ref">> & React.RefAttributes<HTMLDivElement>>;
+declare const CommandEmpty: React.ForwardRefExoticComponent<NoStyle<Omit<{
+    children?: React.ReactNode;
+} & Pick<Pick<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "key" | keyof React.HTMLAttributes<HTMLDivElement>> & {
+    ref?: React.Ref<HTMLDivElement>;
+} & {
+    asChild?: boolean;
+}, "asChild" | "key" | keyof React.HTMLAttributes<HTMLDivElement>> & React.RefAttributes<HTMLDivElement>, "ref">> & React.RefAttributes<HTMLDivElement>>;
+declare const CommandGroup: React.ForwardRefExoticComponent<NoStyle<Omit<{
+    children?: React.ReactNode;
+} & Omit<Pick<Pick<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "key" | keyof React.HTMLAttributes<HTMLDivElement>> & {
+    ref?: React.Ref<HTMLDivElement>;
+} & {
+    asChild?: boolean;
+}, "asChild" | "key" | keyof React.HTMLAttributes<HTMLDivElement>>, "heading" | "value"> & {
+    heading?: React.ReactNode;
+    value?: string;
+    forceMount?: boolean;
+} & React.RefAttributes<HTMLDivElement>, "ref">> & React.RefAttributes<HTMLDivElement>>;
+declare const CommandSeparator: React.ForwardRefExoticComponent<NoStyle<Omit<Pick<Pick<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "key" | keyof React.HTMLAttributes<HTMLDivElement>> & {
+    ref?: React.Ref<HTMLDivElement>;
+} & {
+    asChild?: boolean;
+}, "asChild" | "key" | keyof React.HTMLAttributes<HTMLDivElement>> & {
+    alwaysRender?: boolean;
+} & React.RefAttributes<HTMLDivElement>, "ref">> & React.RefAttributes<HTMLDivElement>>;
+declare const CommandItem: React.ForwardRefExoticComponent<NoStyle<Omit<{
+    children?: React.ReactNode;
+} & Omit<Pick<Pick<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "key" | keyof React.HTMLAttributes<HTMLDivElement>> & {
+    ref?: React.Ref<HTMLDivElement>;
+} & {
+    asChild?: boolean;
+}, "asChild" | "key" | keyof React.HTMLAttributes<HTMLDivElement>>, "onSelect" | "disabled" | "value"> & {
+    disabled?: boolean;
+    onSelect?: (value: string) => void;
+    value?: string;
+    keywords?: string[];
+    forceMount?: boolean;
+} & React.RefAttributes<HTMLDivElement>, "ref">> & React.RefAttributes<HTMLDivElement>>;
+declare function CommandShortcut({ ...props }: NoStyle<React.HTMLAttributes<HTMLSpanElement>>): React.JSX.Element;
+interface CommandDialogProps {
+    open?: boolean;
+    onOpenChange?: (open: boolean) => void;
+    children: React.ReactNode;
+    /** Accessible label for the palette dialog. */
+    label?: string;
+}
+declare function CommandDialog({ open, onOpenChange, children, label }: CommandDialogProps): React.JSX.Element;
+
+/**
+ * Calendar — the date grid (react-day-picker), styled entirely from tokens (no
+ * vendor CSS imported). Use it directly for inline pickers and ranges, or via the
+ * DatePicker (which pairs it with a Popover + field). Pass any react-day-picker
+ * prop — `mode="single" | "range" | "multiple"`, `selected`, `onSelect`, etc.
+ */
+type CalendarProps = React.ComponentProps<typeof DayPicker>;
+declare function Calendar({ showOutsideDays, classNames, ...props }: CalendarProps): React.JSX.Element;
+declare namespace Calendar {
+    var displayName: string;
+}
+
+/**
+ * DatePicker — a single-date field: a token-styled trigger that opens the Calendar
+ * in a Popover. Controlled via `value`/`onValueChange`. For ranges or multi-select,
+ * use the Calendar directly inside a Popover.
+ *
+ *   <DatePicker value={date} onValueChange={setDate} />
+ */
+interface DatePickerProps {
+    value?: Date;
+    onValueChange?: (date?: Date) => void;
+    placeholder?: string;
+    disabled?: boolean;
+    invalid?: boolean;
+    id?: string;
+    'aria-describedby'?: string;
+    /** Intl format for the displayed value. Default { dateStyle: 'medium' }. */
+    formatOptions?: Intl.DateTimeFormatOptions;
+}
+declare function DatePicker({ value, onValueChange, placeholder, disabled, invalid, id, 'aria-describedby': ariaDescribedBy, formatOptions, }: DatePickerProps): React.JSX.Element;
+
+/**
+ * Chart — a token-driven ECharts surface. Pass a standard ECharts `option`; the
+ * series palette, axes, grid, tooltip, and fonts are themed from the live `--wf-*`
+ * tokens, so charts re-skin with the brand and flip with light/dark automatically
+ * (no ThemeProvider required — it watches the document root). Auto-resizes.
+ *
+ *   <Chart option={{ xAxis: { type: 'category', data: months },
+ *                    yAxis: { type: 'value' },
+ *                    series: [{ type: 'line', data: revenue }] }} />
+ *
+ * ECharts is the one canvas dependency; everything else stays DOM + tokens.
+ */
+interface ChartProps {
+    /** A standard ECharts option object. */
+    option: EChartsCoreOption;
+    /** Pixel or CSS height (width always fills the container). Default 320. */
+    height?: number | string;
+    /** Replace the previous option wholesale instead of merging. Default true. */
+    notMerge?: boolean;
+    /** ECharts events to bind, e.g. `{ click: (p) => … }`. */
+    onEvents?: Record<string, (params: unknown) => void>;
+}
+declare function Chart({ option, height, notMerge, onEvents }: ChartProps): React.JSX.Element;
+
+interface ForgeIconProps extends React.SVGProps<SVGSVGElement> {
+}
+declare const ForgeIcon: React.ForwardRefExoticComponent<Omit<ForgeIconProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+interface WindforgeLogoProps {
+    className?: string;
+    /** Hide the wordmark, show only the mark. */
+    markOnly?: boolean;
+}
+declare function WindforgeLogo({ className, markOnly }: WindforgeLogoProps): React.JSX.Element;
+
+interface SVGIconProps extends React.SVGProps<SVGSVGElement> {
+    /** SVG viewBox — defaults to the 24×24 grid lucide draws on, so custom icons
+     *  line up with the rest of the set. */
+    viewBox?: string;
+    /** Accessible label. Omit for a purely decorative icon (rendered aria-hidden). */
+    label?: string;
+}
+/**
+ * SVGIcon — render a custom icon with the same conventions as the supported
+ * lucide set: a 24×24 viewBox, 2px round strokes painted in `currentColor`, and
+ * sizing through h-/w- utilities. Pass the shape as children; override `stroke`,
+ * `fill`, or `strokeWidth` for a filled or heavier glyph.
+ *
+ *   <SVGIcon label="Spark" className="h-5 w-5 text-brand">
+ *     <path d="M12 2 4 7v10l8 5 8-5V7z" />
+ *   </SVGIcon>
+ */
+declare const SVGIcon: React.ForwardRefExoticComponent<Omit<SVGIconProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+
+/**
+ * COMMONLY-USED LUCIDE ICONS — a reference selection, grouped by purpose.
+ *
+ * lucide-react is the design system's supported icon library; consumers import
+ * icons directly from it. These are NOT re-exported as Windforge icons — this
+ * map just powers a browsable, on-brand subset on the Iconography page (the ones
+ * the system actually uses plus the obvious gaps), with an escape hatch to the
+ * full library for the long tail. Object-shorthand keys keep each entry's name in
+ * sync with its component, and the explicit imports keep this list tree-shakeable.
+ */
+declare const commonIconGroups: {
+    label: string;
+    icons: Record<string, LucideIcon>;
+}[];
+/** The flat name → component map across all groups. */
+declare const commonIcons: Record<string, LucideIcon>;
+
+type ColorMode = 'light' | 'dark' | 'system';
+type ResolvedMode = 'light' | 'dark';
+/**
+ * Inline this in <head> BEFORE the app bundle to set the color mode on first
+ * paint and avoid a flash of the wrong theme (SSR/SPA alike). Mirrors the mode
+ * resolution below; reads the persisted `wf-mode`, falls back to system.
+ *
+ *   <script dangerouslySetInnerHTML={{ __html: themeInitScript() }} />
+ */
+declare function themeInitScript(storageKey?: string): string;
+interface ThemeContextValue {
+    mode: ColorMode;
+    resolvedMode: ResolvedMode;
+    setMode: (mode: ColorMode) => void;
+    cycleMode: () => void;
+}
+interface ThemeProviderProps {
+    children: React.ReactNode;
+    defaultMode?: ColorMode;
+    /**
+     * Runtime token overrides — a `--wf-*` → value map applied as custom properties
+     * on the document root, so the whole app (including portaled overlays) re-skins
+     * with no rebuild. Pass a function to stay mode-aware:
+     * `tokens={(mode) => brandVars(ramp, mode)}`. For more than color, use
+     * `themeVars({ brand, fontSans, radius, … }, mode)`. For a site's fixed identity,
+     * prefer a static CSS `:root` override instead.
+     */
+    tokens?: Record<string, string> | ((mode: ResolvedMode) => Record<string, string>);
+    persist?: boolean;
+}
+declare function ThemeProvider({ children, defaultMode, tokens, persist }: ThemeProviderProps): React.JSX.Element;
+declare function useTheme(): ThemeContextValue;
+
+interface AppShellContextValue {
+    /** Toggle the sidebar — collapses it on desktop, opens/closes the drawer on mobile. */
+    toggleNav: () => void;
+    /** Close the mobile drawer (no-op on desktop). */
+    closeNav: () => void;
+}
+/** Read the AppShell coordination handles. Returns null outside an AppShell. */
+declare const useAppShell: () => AppShellContextValue | null;
+interface AppShellProps {
+    /** The top bar slot — typically an `<AppBar>`. Rendered inside the shell so it
+     *  can drive the nav via {@link useAppShell}. */
+    header?: React.ReactNode;
+    /** The side navigation slot — typically a `<SideNav>`. */
+    sidebar?: React.ReactNode;
+    children: React.ReactNode;
+    fullBleed?: boolean;
+    /** Whether the desktop sidebar starts expanded. Set `false` to open collapsed
+     *  — e.g. a personal site where the nav is secondary. The menu button (and
+     *  `useAppShell().toggleNav`) flips it. Defaults to `true`. */
+    defaultNavOpen?: boolean;
+}
+/**
+ * AppShell — the guaranteed-layout chrome: a fixed sidebar on desktop, a Sheet
+ * drawer on mobile, a sticky bar, and a scrollable main. `header` and `sidebar`
+ * are slots (their own components, `AppBar` and `SideNav`); AppShell only owns
+ * the responsive frame and exposes toggle/close handles via {@link useAppShell}.
+ */
+declare function AppShell({ header, sidebar, children, fullBleed, defaultNavOpen }: AppShellProps): React.JSX.Element;
+
+interface NavLeafItem {
+    type?: 'item';
+    label: string;
+    path?: string;
+    icon?: React.ReactNode;
+    badge?: React.ReactNode;
+    onClick?: () => void;
+    disabled?: boolean;
+}
+interface NavGroupItem {
+    type: 'group';
+    label: string;
+    icon?: React.ReactNode;
+    children: NavItem[];
+    defaultOpen?: boolean;
+}
+interface NavSectionItem {
+    type: 'section';
+    label: string;
+    items: NavItem[];
+}
+interface NavDividerItem {
+    type: 'divider';
+}
+type NavItem = NavLeafItem | NavGroupItem | NavSectionItem | NavDividerItem;
+interface SideNavProps {
+    items: NavItem[];
+    activePath?: string;
+    onNavigate?: (path: string) => void;
+    logo?: React.ReactNode;
+}
+declare function SideNav({ items, activePath, onNavigate, logo }: SideNavProps): React.JSX.Element;
+
+declare const appBarVariants: (props?: ({
+    variant?: "glass" | "solid" | null | undefined;
+    color?: "surface" | "subtle" | "inset" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+interface AppBarProps extends VariantProps<typeof appBarVariants> {
+    title?: string;
+    logo?: React.ReactNode;
+    actions?: React.ReactNode;
+    /** Override the menu-button handler. Inside an AppShell it defaults to toggling the nav. */
+    onMenuClick?: () => void;
+}
+/**
+ * ModeToggle — the light/dark/system switch, as a standalone control. Drop it
+ * into an AppBar's `actions` (or anywhere else); it reads and cycles the theme
+ * from the surrounding ThemeProvider.
+ */
+declare function ModeToggle(): React.JSX.Element;
+declare function AppBar({ title, logo, actions, onMenuClick, variant, color, }: AppBarProps): React.JSX.Element;
+
+export { Accordion, AccordionContent, AccordionItem, type AccordionItemData, type AccordionProps, AccordionTrigger, Alert, type AlertProps, AppBar, type AppBarProps, AppShell, type AppShellProps, Autocomplete, type AutocompleteOption, type AutocompleteProps, Avatar, AvatarFallback, AvatarImage, Badge, type BadgeProps, Box, type BoxProps, Breadcrumb, type BreadcrumbItemData, type BreadcrumbProps, Button, ButtonGroup, type ButtonProps, Calendar, type CalendarProps, Card, type CardProps, Chart, type ChartProps, Checkbox, Chip, type ChipProps, CodeBlock, type CodeBlockProps, type ColorMode, Command, CommandDialog, type CommandDialogProps, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, CommandSeparator, CommandShortcut, type ComponentSpec, DataTable, type DataTableColumn, type DataTableProps, DatePicker, type DatePickerProps, Dialog, type DialogProps, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, type DropdownMenuItemData, DropdownMenuLabel, DropdownMenuPortal, type DropdownMenuProps, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuShortcut, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, ForgeIcon, type ForgeIconProps, FormField, type FormFieldProps, Grid, type GridProps, H1, H2, H3, H4, H5, H6, type HeadingProps, Input, type InputProps, Label, Link, type LinkProps, Modal, ModalClose, ModalContent, type ModalContentProps, ModalOverlay, ModalPortal, ModalTrigger, ModeToggle, MultiSelect, type MultiSelectOption, type MultiSelectProps, type NavDividerItem, type NavGroupItem, type NavItem, type NavLeafItem, type NavSectionItem, Pagination, type PaginationProps, Popover, PopoverAnchor, PopoverContent, PopoverTrigger, Progress, RadioGroup, RadioGroupItem, type ResolvedMode, SVGIcon, type SVGIconProps, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, type SelectOption, type SelectProps, SelectTrigger, SelectValue, Separator, Sheet, SheetClose, SheetContent, type SheetContentProps, SheetPortal, SheetTrigger, SideNav, type SideNavProps, Skeleton, Slider, Stack, type StackProps, type Step, Stepper, type StepperProps, Switch, type TabItem, Table, TableBody, TableCaption, TableCell, type TableColumn, TableFooter, TableHead, TableHeader, type TableProps, TableRow, Tabs, TabsContent, TabsList, type TabsProps, TabsTrigger, Text, type TextProps, Textarea, type TextareaProps, ThemeProvider, type ThemeProviderProps, type ToastOptions, type ToastVariant, Toaster, ToggleButton, ToggleButtonGroup, type ToggleButtonGroupProps, type ToggleButtonProps, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, WindforgeLogo, type WindforgeLogoProps, badgeVariants, buttonVariants, catalog, chip as chipVariants, cn, commonIconGroups, commonIcons, dismissButton, dismissToast, floatingPanel, focusRing, focusRingField, focusRingInset, layoutVocabulary, link as linkVariants, menuItem, modalContent, overlayBackdrop, text as textVariants, themeInitScript, toast, useAppShell, useMediaQuery, useTheme };