@mond-design-system/react 1.0.0-alpha.0

package/dist/index.d.ts

@@ -0,0 +1,942 @@
+import * as react from 'react';
+import { CSSProperties, HTMLAttributes, JSX, ReactElement, ReactNode, ButtonHTMLAttributes, ElementType, Ref, AnchorHTMLAttributes, InputHTMLAttributes, TextareaHTMLAttributes, SelectHTMLAttributes, LiHTMLAttributes, MouseEventHandler, RefObject, KeyboardEvent } from 'react';
+
+/**
+ * Join class names, dropping anything falsy.
+ *
+ * Every component takes a `className` from the call site and owns one of its
+ * own from a CSS Module, so the merge happens in one place rather than in
+ * forty slightly different inline expressions.
+ */
+declare function cx(...parts: Array<string | false | null | undefined>): string;
+/**
+ * A style object that may also carry CSS custom properties.
+ *
+ * `React.CSSProperties` has no index signature, so `{ '--mds-x': 1 }` is a
+ * type error against it. Values that genuinely vary per render (a slider's
+ * percent, an avatar's pixel size) belong in a custom property the stylesheet
+ * reads — this types that without an assertion.
+ */
+type CSSVars = CSSProperties & Record<`--${string}`, string | number>;
+
+type TextVariant = "body" | "label" | "note" | "meta" | "eyebrow";
+type TextTone = "primary" | "secondary" | "muted" | "inverse" | "accent" | "on-media" | "danger" | "warning" | "success";
+interface TextProps extends HTMLAttributes<HTMLElement> {
+    /** Type role from the core scale. Default "body". */
+    variant?: TextVariant;
+    /** Element override when the default doesn't fit the markup. */
+    as?: keyof JSX.IntrinsicElements;
+    /** Semantic color. Variants carry sensible defaults. */
+    tone?: TextTone;
+    align?: "left" | "center" | "right";
+    /** Single-line ellipsis. */
+    truncate?: boolean;
+}
+/**
+ * Body-copy primitive. One class per type role — screens never hand-roll styled tags.
+ *
+ * ```tsx
+ * <Text>Body copy.</Text>
+ * <Text variant="label" as="span">Field label</Text>
+ * <Text variant="meta" tone="muted">Updated 2h ago</Text>
+ * <Text truncate>Very long single line…</Text>
+ * ```
+ */
+declare function Text({ variant, as, tone, align, truncate, className, ...rest }: TextProps): ReactElement;
+
+type HeadingVariant = "display" | "title" | "subtitle";
+type HeadingLevel = 1 | 2 | 3 | 4;
+type HeadingTone = "primary" | "secondary" | "inverse" | "accent" | "on-media";
+interface HeadingProps extends HTMLAttributes<HTMLHeadingElement> {
+    /** Document outline level → h1–h4, with a matching default type role. Default 2. */
+    level?: HeadingLevel;
+    /** Type role override — outline level and visual size are separate concerns. */
+    variant?: HeadingVariant;
+    tone?: HeadingTone;
+}
+/**
+ * Brand headings on the core roles. `level` = semantics, `variant` = size.
+ *
+ * ```tsx
+ * <Heading level={1}>Sessions</Heading>
+ * <Heading level={2} variant="subtitle" tone="secondary">This week</Heading>
+ * ```
+ */
+declare function Heading({ level, variant, tone, className, ...rest }: HeadingProps): ReactElement;
+
+interface SpinnerProps extends HTMLAttributes<HTMLSpanElement> {
+    /** Diameter in px. Default 20. */
+    size?: number;
+    /** Accessible label. Default "Loading". */
+    label?: string;
+}
+/**
+ * Indeterminate loading ring. Arc takes currentColor, so it matches whatever
+ * text it sits beside. Keyframe is local: CSS Modules localizes
+ * animation-name, a global one resolves to nothing. base.css stops it under
+ * prefers-reduced-motion.
+ *
+ * ```tsx
+ * <Spinner label="Loading sessions" />
+ * ```
+ */
+declare function Spinner({ size, label, className, style, ...rest }: SpinnerProps): ReactElement;
+
+interface IconRenderProps {
+    /** Pixel size of the requested step. */
+    size: number;
+}
+/** Brand-owned glyph resolver: name → rendered glyph (svg, font ligature, …). */
+type IconRender = (name: string, props: IconRenderProps) => ReactNode;
+interface IconProviderProps {
+    render: IconRender;
+    children: ReactNode;
+}
+/**
+ * Registry seam. The system never bundles an icon set — the app registers its
+ * own (lucide, Material Symbols, …) once, at the root. Iconography is brand,
+ * like color.
+ *
+ * ```tsx
+ * // App root: map names to your icon set once.
+ * <IconProvider render={(name, { size }) => <MyGlyph name={name} width={size} />}>
+ *   <App />
+ * </IconProvider>
+ *
+ * // Anywhere below:
+ * <Icon name="check" size="sm" />
+ * ```
+ */
+declare function IconProvider({ render, children }: IconProviderProps): ReactElement;
+type IconSize = "sm" | "md" | "lg";
+interface IconProps extends HTMLAttributes<HTMLSpanElement> {
+    /** Glyph name in the app's registered set. */
+    name: string;
+    /** Default "md". */
+    size?: IconSize;
+    /** Accessible name. Omitted = decorative (aria-hidden). */
+    label?: string;
+}
+/** A glyph from the app-registered set, sized on the core scale. */
+declare function Icon({ name, size, label, className, ...rest }: IconProps): ReactElement;
+
+type ButtonVariant = "primary" | "secondary" | "ghost" | "danger";
+type ButtonSize = "sm" | "md" | "lg";
+interface ButtonBaseProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "type"> {
+    variant?: ButtonVariant;
+    size?: ButtonSize;
+    /** Glyph slots — pass an <Icon> or any node. Agnostic of icon set. */
+    iconLeft?: ReactNode;
+    iconRight?: ReactNode;
+    /** Spinner replaces the left slot; disables and announces busy. */
+    loading?: boolean;
+    fullWidth?: boolean;
+    type?: "button" | "submit" | "reset";
+    /** Renders an <a> — for navigation styled as a button. */
+    href?: string;
+    /** Element override, e.g. a router's Link. */
+    as?: ElementType;
+    ref?: Ref<HTMLButtonElement>;
+}
+type IconOnlyEnforcement = {
+    iconOnly: true;
+    "aria-label": string;
+} | {
+    iconOnly?: false | undefined;
+};
+type ButtonProps = ButtonBaseProps & IconOnlyEnforcement;
+/**
+ * The tappable action. Semantics: button by default, link when `href`/`as` says so.
+ *
+ * ```tsx
+ * <Button onClick={save}>Save</Button>
+ * <Button variant="secondary" size="sm">Cancel</Button>
+ * <Button variant="danger" loading={deleting} onClick={remove}>Delete</Button>
+ * <Button iconOnly aria-label="Close" variant="ghost"><Icon name="close" /></Button>
+ * <Button href="/settings">Settings</Button>
+ * ```
+ */
+declare function Button({ variant, size, iconLeft, iconRight, loading, disabled, fullWidth, iconOnly, type, href, as, className, children, ...rest }: ButtonProps): ReactElement;
+
+type LinkVariant = "inline" | "standalone";
+interface LinkProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
+    /** inline = underlined, lives in running text. standalone = nav/action link. */
+    variant?: LinkVariant;
+    /** Opens in a new tab with rel protection. */
+    external?: boolean;
+    /** Element override, e.g. a router's Link. */
+    as?: ElementType;
+    ref?: Ref<HTMLAnchorElement>;
+}
+/**
+ * Text link. Inline links keep their underline: color alone fails WCAG 1.4.1
+ * for links inside prose.
+ *
+ * ```tsx
+ * <Text>Read the <Link href="/terms">terms</Link>.</Text>
+ * <Link variant="standalone" href="https://example.com" external>Docs</Link>
+ * <Link as={NextLink} href="/about">About</Link>
+ * ```
+ */
+declare function Link({ variant, external, as: Element, className, ...rest }: LinkProps): ReactElement;
+
+type AvatarSize = "sm" | "md" | "lg";
+interface AvatarProps extends HTMLAttributes<HTMLSpanElement> {
+    /** Person's display name — accessible name and initials source. */
+    name: string;
+    /** Image URL; initials render when absent or empty. */
+    src?: string;
+    size?: AvatarSize;
+}
+/**
+ * Person marker. Image when available, initials otherwise — never an empty circle.
+ *
+ * ```tsx
+ * <Avatar name="Ada Lovelace" src="/ada.jpg" />
+ * <Avatar name="Grace Hopper" size="lg" />
+ * ```
+ */
+declare function Avatar({ name, src, size, className, ...rest }: AvatarProps): ReactElement;
+
+interface AvatarGroupProps extends HTMLAttributes<HTMLDivElement> {
+    /** Avatar children. */
+    children: ReactNode;
+    /** Visible cap; the rest collapse into "+N". Default 4. */
+    max?: number;
+    /** Sizes the overflow chip to match the avatars. Default "md". */
+    size?: AvatarSize;
+}
+/**
+ * Overlapping stack of avatars with a "+N" chip past `max`.
+ *
+ * ```tsx
+ * <AvatarGroup max={3}>
+ *   <Avatar name="Ada Lovelace" />
+ *   <Avatar name="Grace Hopper" />
+ *   <Avatar name="Margaret Hamilton" />
+ *   <Avatar name="Katherine Johnson" />
+ * </AvatarGroup>
+ * ```
+ */
+declare function AvatarGroup({ children, max, size, className, ...rest }: AvatarGroupProps): ReactElement;
+
+type BadgeTone = "neutral" | "accent" | "danger" | "warning" | "success";
+interface BadgeProps extends HTMLAttributes<HTMLSpanElement> {
+    tone?: BadgeTone;
+}
+/**
+ * Small status marker — counts, "new", state words. Soft fill, strong text.
+ *
+ * ```tsx
+ * <Badge tone="success">Paid</Badge>
+ * <Badge tone="danger">3</Badge>
+ * ```
+ */
+declare function Badge({ tone, className, ...rest }: BadgeProps): ReactElement;
+
+type TagTone = "neutral" | "accent";
+interface TagProps extends HTMLAttributes<HTMLSpanElement> {
+    children: ReactNode;
+    tone?: TagTone;
+    /** Renders a labelled ✕ button. Label reads "Remove <content>" when content is text. */
+    onRemove?: () => void;
+}
+/**
+ * Content label chip — categories, filters, topics.
+ *
+ * ```tsx
+ * <Tag>Design</Tag>
+ * <Tag tone="accent" onRemove={() => remove(id)}>Beginner</Tag>
+ * ```
+ */
+declare function Tag({ children, tone, onRemove, className, ...rest }: TagProps): ReactElement;
+
+interface DividerProps extends HTMLAttributes<HTMLDivElement> {
+    orientation?: "horizontal" | "vertical";
+}
+/**
+ * Visual separator. Semantic separator role via <hr>-equivalent div.
+ *
+ * ```tsx
+ * <Divider />
+ * <Divider orientation="vertical" />
+ * ```
+ */
+declare function Divider({ orientation, className, ...rest }: DividerProps): ReactElement;
+
+type SkeletonVariant = "text" | "rect" | "circle";
+interface SkeletonProps extends HTMLAttributes<HTMLSpanElement> {
+    variant?: SkeletonVariant;
+    /** Any CSS length. Text defaults to full width, one line tall. */
+    width?: string;
+    height?: string;
+}
+/**
+ * Loading placeholder. aria-hidden — the loading announcement belongs to the
+ * region (aria-busy), not to each shimmering box.
+ *
+ * ```tsx
+ * <div aria-busy={loading}>
+ *   {loading ? (
+ *     <Stack gap="tight">
+ *       <Skeleton width="40%" />
+ *       <Skeleton />
+ *       <Skeleton variant="rect" height="8rem" />
+ *     </Stack>
+ *   ) : (
+ *     content
+ *   )}
+ * </div>
+ * ```
+ */
+declare function Skeleton({ variant, width, height, className, style, ...rest }: SkeletonProps): ReactElement;
+
+interface ProgressBarProps extends HTMLAttributes<HTMLDivElement> {
+    /** 0–100; clamped. Ignored when indeterminate. */
+    value?: number;
+    /** Accessible name — required. A bare bar announces nothing useful. */
+    label: string;
+    indeterminate?: boolean;
+}
+/**
+ * Determinate or indeterminate progress track.
+ *
+ * ```tsx
+ * <ProgressBar label="Upload" value={64} />
+ * <ProgressBar label="Syncing" indeterminate />
+ * ```
+ */
+declare function ProgressBar({ value, label, indeterminate, className, style, ...rest }: ProgressBarProps): ReactElement;
+
+interface FieldContextValue {
+    /** Control id — the label points here. */
+    id: string;
+    /** Space-joined ids of hint/error, for aria-describedby. */
+    describedBy: string | undefined;
+    invalid: boolean;
+}
+/** Controls call this to pick up Field wiring. Null outside a Field. */
+declare function useFieldContext(): FieldContextValue | null;
+interface FieldProps {
+    label: string;
+    children: ReactNode;
+    /** Guidance under the control. */
+    hint?: string;
+    /** Validation message; replaces the hint and flags the control invalid. */
+    error?: string;
+    required?: boolean;
+    className?: string;
+}
+/**
+ * Label + control + hint/error, wired for assistive tech. The control inside
+ * (Input, Textarea, Select, …) picks up id, aria-describedby and aria-invalid
+ * from context — no manual plumbing at call sites.
+ *
+ * ```tsx
+ * <Field label="Email" hint="Work email preferred" error={errors.email} required>
+ *   <Input type="email" value={email} onChange={(e) => setEmail(e.target.value)} />
+ * </Field>
+ * ```
+ */
+declare function Field({ label, children, hint, error, required, className }: FieldProps): ReactElement;
+
+type InputSize = "sm" | "md" | "lg";
+interface InputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "size"> {
+    size?: InputSize;
+    ref?: Ref<HTMLInputElement>;
+}
+/**
+ * Single-line text input. Inside a Field it inherits id/description/invalid.
+ *
+ * ```tsx
+ * <Field label="Name">
+ *   <Input value={name} onChange={(e) => setName(e.target.value)} />
+ * </Field>
+ *
+ * <Input aria-label="Amount" type="number" size="sm" />
+ * ```
+ */
+declare function Input({ size, className, ...rest }: InputProps): ReactElement;
+
+type PasswordInputProps = Omit<InputProps, "type">;
+/**
+ * Password field with a reveal toggle. Composes Input, so inside a Field it
+ * inherits id/description/invalid the same way.
+ *
+ * ```tsx
+ * <Field label="Password" hint="At least 12 characters">
+ *   <PasswordInput autoComplete="new-password" />
+ * </Field>
+ * ```
+ */
+declare function PasswordInput({ className, ...rest }: PasswordInputProps): ReactElement;
+
+interface TextareaProps extends TextareaHTMLAttributes<HTMLTextAreaElement> {
+    /** Character counter under the control; pairs with native maxLength. */
+    showCount?: boolean;
+    ref?: Ref<HTMLTextAreaElement>;
+}
+/**
+ * Multi-line text input. Inside a Field it inherits id/description/invalid.
+ *
+ * ```tsx
+ * <Field label="Bio">
+ *   <Textarea maxLength={160} showCount />
+ * </Field>
+ * ```
+ */
+declare function Textarea({ rows, showCount, className, ...rest }: TextareaProps): ReactElement;
+
+type SelectSize = "sm" | "md" | "lg";
+interface SelectProps extends Omit<SelectHTMLAttributes<HTMLSelectElement>, "size"> {
+    size?: SelectSize;
+    ref?: Ref<HTMLSelectElement>;
+}
+/**
+ * Native select, styled. Native = free keyboard, mobile pickers, screen
+ * reader behavior; a custom popover earns its complexity only when options
+ * need rich content.
+ *
+ * ```tsx
+ * <Field label="Language">
+ *   <Select value={lang} onChange={(e) => setLang(e.target.value)}>
+ *     <option value="de">Deutsch</option>
+ *     <option value="en">English</option>
+ *   </Select>
+ * </Field>
+ * ```
+ */
+declare function Select({ size, className, children, ...rest }: SelectProps): ReactElement;
+
+interface CheckboxProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "type" | "size"> {
+    /** Inline label — part of the click target. */
+    label: string;
+    ref?: Ref<HTMLInputElement>;
+}
+/**
+ * Native checkbox, styled box. Label is the touch target too.
+ *
+ * ```tsx
+ * <Checkbox label="Remember me" defaultChecked />
+ * <Checkbox
+ *   label="Accept terms"
+ *   checked={accepted}
+ *   onChange={(e) => setAccepted(e.target.checked)}
+ * />
+ * ```
+ */
+declare function Checkbox({ label, className, ...rest }: CheckboxProps): ReactElement;
+
+interface RadioProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "type" | "size"> {
+    /** Inline label — part of the click target. */
+    label: string;
+    ref?: Ref<HTMLInputElement>;
+}
+/**
+ * Native radio, styled dot. Group by `name`; wrap the group in
+ * `<fieldset>`/`<legend>` for a group label.
+ *
+ * ```tsx
+ * <fieldset>
+ *   <legend>Plan</legend>
+ *   <Radio name="plan" label="Free" checked={plan === "free"} onChange={() => setPlan("free")} />
+ *   <Radio name="plan" label="Pro" checked={plan === "pro"} onChange={() => setPlan("pro")} />
+ * </fieldset>
+ * ```
+ */
+declare function Radio({ label, className, ...rest }: RadioProps): ReactElement;
+
+interface SwitchProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "type" | "size"> {
+    /** Inline label — part of the click target. */
+    label: string;
+    ref?: Ref<HTMLInputElement>;
+}
+/**
+ * On/off toggle. Checkbox under the hood with role="switch" — native
+ * semantics and forms integration, switch announcement.
+ *
+ * ```tsx
+ * <Switch
+ *   label="Notifications"
+ *   checked={enabled}
+ *   onChange={(e) => setEnabled(e.target.checked)}
+ * />
+ * ```
+ */
+declare function Switch({ label, className, ...rest }: SwitchProps): ReactElement;
+
+interface SegmentOption<T extends string = string> {
+    value: T;
+    label: string;
+}
+interface SegmentedControlProps<T extends string = string> {
+    /** Accessible group name. */
+    label: string;
+    options: readonly SegmentOption<T>[];
+    value: T;
+    onChange: (value: T) => void;
+    className?: string;
+}
+/**
+ * Exclusive choice among few visible options. Native radios under the hood —
+ * free keyboard model and semantics.
+ *
+ * ```tsx
+ * <SegmentedControl
+ *   label="View"
+ *   options={[
+ *     { value: "list", label: "List" },
+ *     { value: "grid", label: "Grid" },
+ *   ]}
+ *   value={view}
+ *   onChange={setView}
+ * />
+ * ```
+ */
+declare function SegmentedControl<T extends string = string>({ label, options, value, onChange, className, }: SegmentedControlProps<T>): ReactElement;
+
+interface SearchFieldProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "type" | "size" | "value" | "onChange"> {
+    /** Accessible name. */
+    label: string;
+    value: string;
+    /** Receives the new text — "" when cleared. */
+    onChange: (value: string) => void;
+    ref?: Ref<HTMLInputElement>;
+}
+/**
+ * Controlled search input with a clear affordance once there is text.
+ *
+ * ```tsx
+ * <SearchField label="Search sessions" value={query} onChange={setQuery} />
+ * ```
+ */
+declare function SearchField({ label, value, onChange, className, ...rest }: SearchFieldProps): ReactElement;
+
+interface ListGroupProps extends HTMLAttributes<HTMLUListElement> {
+    children: ReactNode;
+}
+/**
+ * Card-styled list container for ListItems.
+ *
+ * ```tsx
+ * <ListGroup>
+ *   <ListItem
+ *     title="Profile"
+ *     description="Name, avatar"
+ *     leading={<Icon name="user" />}
+ *     href="/profile"
+ *   />
+ *   <ListItem title="Log out" onClick={logout} />
+ * </ListGroup>
+ * ```
+ */
+declare function ListGroup({ className, ...rest }: ListGroupProps): ReactElement;
+interface ListItemProps extends Omit<LiHTMLAttributes<HTMLLIElement>, "title" | "onClick"> {
+    title: string;
+    description?: string;
+    /** Slot before the text — Avatar, Icon, … */
+    leading?: ReactNode;
+    /** Slot after the text — Badge, chevron, … */
+    trailing?: ReactNode;
+    /** Makes the whole row a button. */
+    onClick?: () => void;
+    /** Makes the whole row a link. Wins over onClick. */
+    href?: string;
+}
+/** One row. Static by default; interactive as one whole-row button/link. */
+declare function ListItem({ title, description, leading, trailing, onClick, href, className, ...rest }: ListItemProps): ReactElement;
+
+interface EmptyStateProps {
+    title: string;
+    description?: string;
+    /** Illustration or Icon slot. */
+    icon?: ReactNode;
+    /** Usually a Button. */
+    action?: ReactNode;
+    className?: string;
+}
+/**
+ * Nothing-here view: explains the empty screen and offers the next step.
+ *
+ * ```tsx
+ * <EmptyState
+ *   icon={<Icon name="inbox" size="lg" />}
+ *   title="No sessions yet"
+ *   description="Create your first session to get started."
+ *   action={<Button onClick={create}>New session</Button>}
+ * />
+ * ```
+ */
+declare function EmptyState({ title, description, icon, action, className }: EmptyStateProps): ReactElement;
+
+interface TabsProps {
+    value: string;
+    onChange: (value: string) => void;
+    children: ReactNode;
+}
+/**
+ * Controlled tabs root. Compose with TabList, Tab, TabPanel.
+ *
+ * ```tsx
+ * <Tabs value={tab} onChange={setTab}>
+ *   <TabList label="Session details">
+ *     <Tab value="info">Info</Tab>
+ *     <Tab value="notes">Notes</Tab>
+ *   </TabList>
+ *   <TabPanel value="info">…</TabPanel>
+ *   <TabPanel value="notes">…</TabPanel>
+ * </Tabs>
+ * ```
+ */
+declare function Tabs({ value, onChange, children }: TabsProps): ReactElement;
+interface TabListProps extends HTMLAttributes<HTMLDivElement> {
+    /** Accessible name for the tab set. */
+    label: string;
+    children: ReactNode;
+}
+declare function TabList({ label, className, children, ...rest }: TabListProps): ReactElement;
+interface TabProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "value" | "type"> {
+    value: string;
+    children: ReactNode;
+}
+declare function Tab({ value, className, children, ...rest }: TabProps): ReactElement;
+interface TabPanelProps extends HTMLAttributes<HTMLDivElement> {
+    value: string;
+    children: ReactNode;
+}
+declare function TabPanel({ value, className, children, ...rest }: TabPanelProps): ReactElement;
+
+type ToastTone = "neutral" | "success" | "danger";
+interface ToastOptions {
+    title: string;
+    description?: string | undefined;
+    tone?: ToastTone | undefined;
+    /** ms until auto-dismiss. 0 = stays until dismissed. Default 5000. */
+    duration?: number | undefined;
+}
+interface ToastContextValue {
+    toast: (options: ToastOptions) => number;
+    dismiss: (id: number) => void;
+}
+declare function useToast(): ToastContextValue;
+interface ToastProviderProps {
+    children: ReactNode;
+}
+/**
+ * Mount once near the root. Renders the notification region itself.
+ *
+ * ```tsx
+ * // App root
+ * <ToastProvider>
+ *   <App />
+ * </ToastProvider>
+ *
+ * // Anywhere below
+ * const { toast } = useToast();
+ * toast({ title: "Saved", tone: "success" });
+ * ```
+ */
+declare function ToastProvider({ children }: ToastProviderProps): ReactElement;
+
+type StackGap = "hairline" | "tight" | "base" | "loose" | "section";
+type StackAlign = "start" | "center" | "end" | "stretch";
+interface StackProps extends HTMLAttributes<HTMLElement> {
+    /** Space between children, on the gap scale. Default "base". */
+    gap?: StackGap;
+    /** Cross-axis alignment. Default "stretch". */
+    align?: StackAlign;
+    /** Element to render. Default div. */
+    as?: ElementType;
+}
+/**
+ * Vertical flow. The parent owns spacing between siblings via gap —
+ * children carry no outer margins. Token-bounded on purpose: no arbitrary
+ * lengths, no style prop.
+ *
+ * ```tsx
+ * <Stack gap="base">
+ *   <Heading level={2}>Profile</Heading>
+ *   <Text tone="secondary">Public information</Text>
+ * </Stack>
+ * ```
+ */
+declare function Stack({ gap, align, as, className, ...rest }: StackProps): ReactElement;
+
+type InlineGap = "hairline" | "tight" | "base" | "loose";
+type InlineAlign = "start" | "center" | "end" | "baseline";
+type InlineJustify = "start" | "center" | "end" | "between";
+interface InlineProps extends HTMLAttributes<HTMLElement> {
+    /** Space between children, on the gap scale. Default "base". */
+    gap?: InlineGap;
+    /** Cross-axis alignment. Default "center". */
+    align?: InlineAlign;
+    /** Main-axis distribution. Default "start". */
+    justify?: InlineJustify;
+    /** Allow wrapping onto new lines. */
+    wrap?: boolean;
+    /** Element to render. Default div. */
+    as?: ElementType;
+}
+/**
+ * Horizontal flow — Stack's row twin. Same token-bounded contract.
+ *
+ * ```tsx
+ * <Inline gap="tight" align="center" justify="between">
+ *   <Text variant="label">Total</Text>
+ *   <Text>42</Text>
+ * </Inline>
+ * ```
+ */
+declare function Inline({ gap, align, justify, wrap, as, className, ...rest }: InlineProps): ReactElement;
+
+type ContainerWidth = "content" | "wide";
+interface ContainerProps extends HTMLAttributes<HTMLElement> {
+    /** content = reading column, wide = desktop shell. Default "content". */
+    width?: ContainerWidth;
+    /** Element to render. Default div. */
+    as?: ElementType;
+}
+/**
+ * Centered max-width column with page-edge padding.
+ *
+ * ```tsx
+ * <Container>
+ *   <Stack gap="section">…</Stack>
+ * </Container>
+ * ```
+ */
+declare function Container({ width, as, className, ...rest }: ContainerProps): ReactElement;
+
+type CardVariant = "card" | "raised";
+interface CardProps extends Omit<HTMLAttributes<HTMLElement>, "onClick"> {
+    children: ReactNode;
+    /** card = flat on border, raised = elevated. Default "card". */
+    variant?: CardVariant;
+    /** Makes the whole card a button. */
+    onClick?: () => void;
+    /** Makes the whole card a link. Wins over onClick. */
+    href?: string;
+}
+/**
+ * Surface container. Compose with CardHeader/CardBody/CardFooter — the card
+ * owns internal spacing, sections own their content.
+ *
+ * ```tsx
+ * <Card>
+ *   <CardHeader><Heading level={3}>Next session</Heading></CardHeader>
+ *   <CardBody><Text>Tomorrow, 19:00</Text></CardBody>
+ *   <CardFooter><Button size="sm">Join</Button></CardFooter>
+ * </Card>
+ *
+ * <Card href="/items/42" variant="flat">…</Card>
+ * ```
+ */
+declare function Card({ children, variant, onClick, href, className, ...rest }: CardProps): ReactElement;
+type CardSectionProps = HTMLAttributes<HTMLDivElement>;
+/** Top slot — title row, media, tabs. */
+declare function CardHeader({ className, ...rest }: CardSectionProps): ReactElement;
+/** Main content slot. */
+declare function CardBody({ className, ...rest }: CardSectionProps): ReactElement;
+/** Bottom slot — actions, meta. */
+declare function CardFooter({ className, ...rest }: CardSectionProps): ReactElement;
+
+interface ModalProps {
+    open: boolean;
+    onClose: () => void;
+    /** Accessible name of the dialog. */
+    label: string;
+    /** Scrim click dismisses. Default true. */
+    closeOnScrimClick?: boolean;
+    children: ReactNode;
+}
+/**
+ * Centered dialog. Escape, scrim click (`closeOnScrimClick`), and focus trap
+ * are handled. Compose the sections:
+ *
+ * ```tsx
+ * <Modal open={open} onClose={() => setOpen(false)} label="Edit session">
+ *   <ModalHeader>Edit session</ModalHeader>
+ *   <ModalBody>…</ModalBody>
+ *   <ModalFooter><Button onClick={save}>Save</Button></ModalFooter>
+ * </Modal>
+ * ```
+ */
+declare function Modal({ open, onClose, label, closeOnScrimClick, children }: ModalProps): react.JSX.Element;
+declare function ModalHeader({ children }: {
+    children: ReactNode;
+}): react.JSX.Element;
+declare function ModalBody({ children }: {
+    children: ReactNode;
+}): react.JSX.Element;
+declare function ModalFooter({ children }: {
+    children: ReactNode;
+}): react.JSX.Element;
+
+interface SheetProps {
+    open: boolean;
+    onClose: () => void;
+    /** Accessible name of the dialog. */
+    label: string;
+    /** Scrim click dismisses. Default true. */
+    closeOnScrimClick?: boolean;
+    children: ReactNode;
+}
+/**
+ * Bottom sheet. Same composition and dismissal model as Modal:
+ *
+ * ```tsx
+ * <Sheet open={open} onClose={() => setOpen(false)} label="Filters">
+ *   <SheetHeader>Filters</SheetHeader>
+ *   <SheetBody>…</SheetBody>
+ *   <SheetFooter><Button onClick={apply}>Apply</Button></SheetFooter>
+ * </Sheet>
+ * ```
+ */
+declare function Sheet({ open, onClose, label, closeOnScrimClick, children }: SheetProps): react.JSX.Element;
+declare function SheetHeader({ children }: {
+    children: ReactNode;
+}): react.JSX.Element;
+declare function SheetBody({ children }: {
+    children: ReactNode;
+}): react.JSX.Element;
+declare function SheetFooter({ children }: {
+    children: ReactNode;
+}): react.JSX.Element;
+
+interface ConfirmDialogProps {
+    open: boolean;
+    onClose: () => void;
+    onConfirm: () => void;
+    title: string;
+    description?: string | undefined;
+    confirmLabel: string;
+    cancelLabel?: string | undefined;
+    /** Style the confirm action as destructive. */
+    danger?: boolean | undefined;
+}
+/**
+ * Pre-composed Modal for the confirm/cancel pattern.
+ *
+ * ```tsx
+ * <ConfirmDialog
+ *   open={open}
+ *   onClose={() => setOpen(false)}
+ *   onConfirm={deleteItem}
+ *   title="Delete item?"
+ *   description="This cannot be undone."
+ *   confirmLabel="Delete"
+ *   danger
+ * />
+ * ```
+ */
+declare function ConfirmDialog({ open, onClose, onConfirm, title, description, confirmLabel, cancelLabel, danger, }: ConfirmDialogProps): react.JSX.Element;
+
+/**
+ * Page scaffold. Compose:
+ *
+ * ```tsx
+ * <Screen>
+ *   <AppBar title="Sessions" />
+ *   <ScreenContent>…</ScreenContent>
+ *   <TabBar label="Primary">…</TabBar>
+ * </Screen>
+ * ```
+ */
+declare function Screen({ children }: {
+    children: ReactNode;
+}): react.JSX.Element;
+/** The scrollable main region of a Screen. */
+declare function ScreenContent({ children }: {
+    children: ReactNode;
+}): react.JSX.Element;
+
+interface AppBarProps {
+    title?: string | undefined;
+    /** Left slot — typically a back icon-only Button. */
+    leading?: ReactNode;
+    /** Right slot — actions. */
+    trailing?: ReactNode;
+}
+/**
+ * Top app bar. Sticky, one per screen; the title is the page h1.
+ *
+ * ```tsx
+ * <AppBar
+ *   title="Sessions"
+ *   trailing={
+ *     <Button iconOnly aria-label="Settings" variant="ghost" onClick={openSettings}>
+ *       <Icon name="settings" />
+ *     </Button>
+ *   }
+ * />
+ * ```
+ */
+declare function AppBar({ title, leading, trailing }: AppBarProps): react.JSX.Element;
+
+interface TabBarProps {
+    /** Accessible name of the navigation landmark. */
+    label: string;
+    children: ReactNode;
+}
+/**
+ * Bottom navigation. Items are links (or buttons for non-route actions);
+ * they stay in the natural tab order — roving focus is for composite
+ * widgets, not navigation landmarks.
+ *
+ * ```tsx
+ * <TabBar label="Primary">
+ *   <TabBarItem label="Home" icon={<Icon name="home" />} href="/" active />
+ *   <TabBarItem label="Search" icon={<Icon name="search" />} href="/search" />
+ * </TabBar>
+ * ```
+ */
+declare function TabBar({ label, children }: TabBarProps): react.JSX.Element;
+interface TabBarItemProps {
+    label: string;
+    icon: ReactNode;
+    href?: string | undefined;
+    onClick?: MouseEventHandler | undefined;
+    active?: boolean | undefined;
+}
+declare function TabBarItem({ label, icon, href, onClick, active }: TabBarItemProps): react.JSX.Element;
+
+interface UseOverlayOptions {
+    open: boolean;
+    onClose: () => void;
+}
+/**
+ * Shared modal-surface behaviour: focus capture and restore, Escape to
+ * close, Tab cycling inside the panel, body scroll lock. Attach the
+ * returned ref to the dialog element (it needs tabIndex={-1}).
+ *
+ * Anchor-positioned overlays (Tooltip/Popover) will extend this hook with
+ * a floating-ui middleware pass; the options object leaves room for that.
+ */
+declare function useOverlay<T extends HTMLElement>(options: UseOverlayOptions): RefObject<T | null>;
+
+interface Presence {
+    /** Keep the element in the DOM (true during exit animation). */
+    mounted: boolean;
+    /** Drive the visual state — false during exit. */
+    visible: boolean;
+}
+/**
+ * Exit-animation helper. `open` flips instantly; `mounted` lags by
+ * `durationMs` on close so the exit transition can play.
+ */
+declare function usePresence(open: boolean, durationMs: number): Presence;
+
+interface RovingGroupOptions {
+    /** Selector for the focusable items inside the container. */
+    selector: string;
+    /** Arrow axis. Default "horizontal". */
+    orientation?: "horizontal" | "vertical" | "both";
+}
+/**
+ * Arrow-key focus movement for composite widgets (toolbars, menus, tab bars).
+ * Wraps at the edges; Home/End jump. Returns a keydown handler for the
+ * container.
+ */
+declare function useRovingGroup(ref: RefObject<HTMLElement | null>, { selector, orientation }: RovingGroupOptions): (event: KeyboardEvent<HTMLElement>) => void;
+
+export { AppBar, type AppBarProps, Avatar, AvatarGroup, type AvatarGroupProps, type AvatarProps, type AvatarSize, Badge, type BadgeProps, type BadgeTone, Button, type ButtonProps, type ButtonSize, type ButtonVariant, type CSSVars, Card, CardBody, CardFooter, CardHeader, type CardProps, type CardSectionProps, type CardVariant, Checkbox, type CheckboxProps, ConfirmDialog, type ConfirmDialogProps, Container, type ContainerProps, type ContainerWidth, Divider, type DividerProps, EmptyState, type EmptyStateProps, Field, type FieldContextValue, type FieldProps, Heading, type HeadingLevel, type HeadingProps, type HeadingTone, Icon, type IconProps, IconProvider, type IconProviderProps, type IconRender, type IconRenderProps, type IconSize, Inline, type InlineAlign, type InlineGap, type InlineJustify, type InlineProps, Input, type InputProps, type InputSize, Link, type LinkProps, type LinkVariant, ListGroup, type ListGroupProps, ListItem, type ListItemProps, Modal, ModalBody, ModalFooter, ModalHeader, type ModalProps, PasswordInput, type PasswordInputProps, type Presence, ProgressBar, type ProgressBarProps, Radio, type RadioProps, type RovingGroupOptions, Screen, ScreenContent, SearchField, type SearchFieldProps, type SegmentOption, SegmentedControl, type SegmentedControlProps, Select, type SelectProps, type SelectSize, Sheet, SheetBody, SheetFooter, SheetHeader, type SheetProps, Skeleton, type SkeletonProps, type SkeletonVariant, Spinner, type SpinnerProps, Stack, type StackAlign, type StackGap, type StackProps, Switch, type SwitchProps, Tab, TabBar, TabBarItem, type TabBarItemProps, type TabBarProps, TabList, type TabListProps, TabPanel, type TabPanelProps, type TabProps, Tabs, type TabsProps, Tag, type TagProps, type TagTone, Text, type TextProps, type TextTone, type TextVariant, Textarea, type TextareaProps, type ToastOptions, ToastProvider, type ToastProviderProps, type ToastTone, type UseOverlayOptions, cx, useFieldContext, useOverlay, usePresence, useRovingGroup, useToast };