@mithrl/design-system 0.3.0 → 0.4.1

package/dist/components/approval-card/ApprovalCard.d.ts

@@ -0,0 +1,61 @@
+import { type FormHTMLAttributes } from "react";
+
+export type ApprovalCardMode = "single" | "multi";
+export type ApprovalCardOption = {
+    id: string;
+    title: string;
+    subtitle?: string;
+    disabled?: boolean;
+};
+export type ApprovalCardQuestion = {
+    id: string;
+    title: string;
+    mode: ApprovalCardMode;
+    options: readonly ApprovalCardOption[];
+};
+export type ApprovalCardAnswer = {
+    selectedOptionIds: readonly string[];
+    customValue: string;
+};
+export type ApprovalCardNavigationReason = "previous" | "next" | "continue" | "auto";
+export type ApprovalCardLabels = {
+    customAnswer: string;
+    previousQuestion: string;
+    nextQuestion: string;
+    skip: string;
+    continue: string;
+    submit: string;
+    submitting: string;
+};
+type NativeApprovalCardProps = Omit<FormHTMLAttributes<HTMLFormElement>, "children" | "onSubmit">;
+export type ApprovalCardProps = NativeApprovalCardProps & {
+    questions: readonly ApprovalCardQuestion[];
+    activeQuestionId: string;
+    answers: Readonly<Record<string, ApprovalCardAnswer | undefined>>;
+    onAnswerChange: (questionId: string, answer: ApprovalCardAnswer) => void;
+    onActiveQuestionChange: (questionId: string, reason: ApprovalCardNavigationReason) => void;
+    onSubmit: (answers: Readonly<Record<string, ApprovalCardAnswer | undefined>>) => void;
+    onSkip?: (questionId: string) => void;
+    error?: string;
+    submitting?: boolean;
+    disabled?: boolean;
+    showSkip?: boolean;
+    autoAdvanceSingle?: boolean;
+    labels?: Partial<ApprovalCardLabels>;
+};
+export declare const ApprovalCard: import("react").ForwardRefExoticComponent<NativeApprovalCardProps & {
+    questions: readonly ApprovalCardQuestion[];
+    activeQuestionId: string;
+    answers: Readonly<Record<string, ApprovalCardAnswer | undefined>>;
+    onAnswerChange: (questionId: string, answer: ApprovalCardAnswer) => void;
+    onActiveQuestionChange: (questionId: string, reason: ApprovalCardNavigationReason) => void;
+    onSubmit: (answers: Readonly<Record<string, ApprovalCardAnswer | undefined>>) => void;
+    onSkip?: (questionId: string) => void;
+    error?: string;
+    submitting?: boolean;
+    disabled?: boolean;
+    showSkip?: boolean;
+    autoAdvanceSingle?: boolean;
+    labels?: Partial<ApprovalCardLabels>;
+} & import("react").RefAttributes<HTMLFormElement>>;
+export {};

package/dist/components/code-block/CodeBlock.d.ts

@@ -0,0 +1,64 @@
+import { type HTMLAttributes, type ReactNode } from "react";
+
+export type CodeBlockVariant = "code" | "diff";
+export type CodeLineKind = "context" | "added" | "removed";
+export type CodeLine = {
+    /** Raw line text. Rendered verbatim in the mono column. */
+    content: string;
+    /** Diff classification. Ignored by the `code` variant. */
+    kind?: CodeLineKind;
+};
+export type CodeBlockRenderLineArgs = {
+    /** Raw line text. */
+    content: string;
+    /** Resolved diff classification. */
+    kind: CodeLineKind;
+    /** One-based line number as shown in the gutter. */
+    number: number;
+    /** Variant the line is being rendered for. */
+    variant: CodeBlockVariant;
+};
+export type CodeBlockLabels = {
+    copy: string;
+    copied: string;
+    copyFailed: string;
+    codeTab: string;
+    diffTab: string;
+    listing: string;
+};
+type CodeBlockOwnProps = {
+    /** Source text. Split on newlines into the listing. */
+    code?: string;
+    /** Pre-split lines, required for diff rendering. Wins over `code`. */
+    lines?: readonly CodeLine[];
+    /** Language label rendered as a Tag in the header. */
+    language?: string;
+    /** File path or name rendered as the header title. */
+    fileName?: string;
+    /** Listing mode. Ignored when `tabs` is enabled. */
+    variant?: CodeBlockVariant;
+    /** Renders a Code/Diff segmented control. Requires `code` and `lines`. */
+    tabs?: boolean;
+    /** Controlled tab value when `tabs` is enabled. */
+    activeTab?: CodeBlockVariant;
+    /** Called when the Code/Diff segmented control changes. */
+    onTabChange?: (variant: CodeBlockVariant) => void;
+    /** Hides the line-number column. */
+    hideLineNumbers?: boolean;
+    /** Called with the text placed on the clipboard. */
+    onCopy?: (text: string) => void;
+    /** Injects highlighted nodes for a line. Defaults to plain mono text. */
+    renderLine?: (line: CodeBlockRenderLineArgs) => ReactNode;
+    labels?: Partial<CodeBlockLabels>;
+    className?: string;
+};
+export type CodeBlockProps = Omit<HTMLAttributes<HTMLDivElement>, keyof CodeBlockOwnProps | "children"> & CodeBlockOwnProps;
+/**
+ * A notebook-tier code surface: a titled header rail with an optional
+ * language Tag and copy action, and a line-numbered, horizontally scrolling
+ * listing. The `diff` variant renders unified diff lines with semantic
+ * tinting. CodeBlock ships no syntax highlighting engine — pass `renderLine`
+ * to inject already-highlighted nodes.
+ */
+export declare const CodeBlock: import("react").ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLDivElement>, "children" | keyof CodeBlockOwnProps> & CodeBlockOwnProps & import("react").RefAttributes<HTMLDivElement>>;
+export {};

package/dist/components/command-search/CommandSearch.d.ts

@@ -0,0 +1,121 @@
+import { type HTMLAttributes, type ReactNode } from "react";
+
+export type CommandSearchItem = {
+    /** Stable identity used for keys and active-descendant wiring. */
+    id: string;
+    /** Visible command label; match highlighting applies to this text. */
+    label: string;
+    /** Optional group heading the item is filed under. */
+    group?: string;
+    /** Optional trailing hint such as a shortcut or destination. */
+    hint?: string;
+    /** Invoked on Enter or click. */
+    onSelect?: (item: CommandSearchItem) => void;
+    /** Removes the item from keyboard navigation and selection. */
+    disabled?: boolean;
+    /**
+     * Opaque consumer payload, carried untouched through selection and
+     * `renderItem`. CommandSearch never reads it — it exists so a caller does not
+     * have to keep a parallel id-to-record map just to draw an icon or route a
+     * command.
+     */
+    data?: unknown;
+};
+/** State handed to `renderItem` for one row. */
+export type CommandSearchItemState = {
+    /** This row currently carries the roving highlight. */
+    active: boolean;
+    /** This row is not selectable and is skipped by keyboard navigation. */
+    disabled: boolean;
+    /** The live query, for a consumer highlighting its own text. */
+    query: string;
+};
+export type CommandSearchProps = Omit<HTMLAttributes<HTMLDivElement>, "children" | "onSelect"> & {
+    items: readonly CommandSearchItem[];
+    /** Required accessible name for the search field. */
+    label: string;
+    placeholder?: string;
+    /** Controlled query. Omit for uncontrolled use. */
+    query?: string;
+    defaultQuery?: string;
+    onQueryChange?: (query: string) => void;
+    /** Called after any item is chosen, in addition to the item's own handler. */
+    onSelect?: (item: CommandSearchItem) => void;
+    /** Called when Escape is pressed on a field that is already empty. */
+    onEscape?: () => void;
+    /** Renders group headings when items carry a `group`. */
+    grouped?: boolean;
+    /** Secondary line shown under the empty-state title. */
+    emptyHint?: ReactNode;
+    /**
+     * Run the built-in label/group/hint substring filter. @default true
+     *
+     * Set `false` when the caller already filtered — an alias-aware catalog or a
+     * server content search, say. Every item then renders exactly as supplied
+     * and nothing is hidden, so a result that matched on something CommandSearch
+     * cannot see (an alias, a synonym, document body text) still appears. Match
+     * highlighting is unaffected: a label that happens to contain the query is
+     * still marked, and one that does not simply renders plain.
+     */
+    filter?: boolean;
+    /**
+     * Replaces the content of a row — icon, label, status, shortcut, whatever the
+     * surface needs. CommandSearch keeps ownership of the listbox and option
+     * semantics around it: ids, `role`, `aria-selected`, active handling, pointer
+     * and click wiring, and disabled skipping are all unchanged, so a custom row
+     * cannot break keyboard navigation.
+     *
+     * Default row content (marked label plus hint) is used when this is omitted.
+     */
+    renderItem?: (item: CommandSearchItem, state: CommandSearchItemState) => ReactNode;
+};
+/**
+ * A command palette search surface. CommandSearch renders inline as an
+ * embedded panel and can be composed inside a Dialog by the consumer; it owns
+ * filtering, match highlighting, and roving keyboard selection only.
+ *
+ * Both halves of that are optional. A surface whose catalog already knows about
+ * aliases, or whose results come back from a server search, passes
+ * `filter={false}` and keeps the listbox semantics without the second,
+ * narrower filter running behind it. A surface needing richer rows than
+ * label-plus-hint passes `renderItem` and keeps the keyboard model.
+ */
+export declare const CommandSearch: import("react").ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLDivElement>, "children" | "onSelect"> & {
+    items: readonly CommandSearchItem[];
+    /** Required accessible name for the search field. */
+    label: string;
+    placeholder?: string;
+    /** Controlled query. Omit for uncontrolled use. */
+    query?: string;
+    defaultQuery?: string;
+    onQueryChange?: (query: string) => void;
+    /** Called after any item is chosen, in addition to the item's own handler. */
+    onSelect?: (item: CommandSearchItem) => void;
+    /** Called when Escape is pressed on a field that is already empty. */
+    onEscape?: () => void;
+    /** Renders group headings when items carry a `group`. */
+    grouped?: boolean;
+    /** Secondary line shown under the empty-state title. */
+    emptyHint?: ReactNode;
+    /**
+     * Run the built-in label/group/hint substring filter. @default true
+     *
+     * Set `false` when the caller already filtered — an alias-aware catalog or a
+     * server content search, say. Every item then renders exactly as supplied
+     * and nothing is hidden, so a result that matched on something CommandSearch
+     * cannot see (an alias, a synonym, document body text) still appears. Match
+     * highlighting is unaffected: a label that happens to contain the query is
+     * still marked, and one that does not simply renders plain.
+     */
+    filter?: boolean;
+    /**
+     * Replaces the content of a row — icon, label, status, shortcut, whatever the
+     * surface needs. CommandSearch keeps ownership of the listbox and option
+     * semantics around it: ids, `role`, `aria-selected`, active handling, pointer
+     * and click wiring, and disabled skipping are all unchanged, so a custom row
+     * cannot break keyboard navigation.
+     *
+     * Default row content (marked label plus hint) is used when this is omitted.
+     */
+    renderItem?: (item: CommandSearchItem, state: CommandSearchItemState) => ReactNode;
+} & import("react").RefAttributes<HTMLDivElement>>;

package/dist/components/context-cards/ContextCards.d.ts

@@ -0,0 +1,53 @@
+import { type HTMLAttributes, type ReactNode } from "react";
+
+/** File types a retrieved chunk can come from. */
+export type ContextFileType = "PDF" | "CSV" | "XLSX" | "TXT";
+export interface FileTypeChipProps {
+    /** The chunk's source file type. */
+    fileType: ContextFileType;
+}
+/**
+ * A tinted three-or-four letter file-type marker. Each type gets a distinct
+ * semantic tint so a mixed list is scannable at a glance without reading
+ * filenames.
+ */
+export declare function FileTypeChip({ fileType }: FileTypeChipProps): import("react/jsx-runtime").JSX.Element;
+export interface ContextCardProps extends Omit<HTMLAttributes<HTMLElement>, "title"> {
+    /** Chunk heading — usually the section or table it was taken from. */
+    title: ReactNode;
+    /** Retrieved text. Clamped to three lines and faded, never truncated mid-word with an ellipsis. */
+    excerpt: ReactNode;
+    /** Character count of the full chunk, shown as retrieval metadata. */
+    characterCount?: number;
+    /** File the chunk came from. */
+    fileName: string;
+    /** File type of `fileName`. */
+    fileType: ContextFileType;
+    /**
+     * Optional page or row provenance, e.g. `"p. 4"` or `"rows 120–184"`.
+     */
+    locator?: string;
+}
+/**
+ * One retrieved knowledge chunk. Presentational: the card is not a control, so
+ * it carries no role or tab stop. Wrap it in a button or link at the call site
+ * if opening the source is supported there.
+ */
+export declare const ContextCard: import("react").ForwardRefExoticComponent<ContextCardProps & import("react").RefAttributes<HTMLElement>>;
+export interface ContextCardListProps extends Omit<HTMLAttributes<HTMLElement>, "title"> {
+    /** Group heading. @default "All chunks" */
+    title?: ReactNode;
+    /**
+     * Number shown in the count Tag. Defaults to the number of rendered cards,
+     * so pass it explicitly only when the list is paged or virtualised.
+     */
+    count?: number;
+    /** `ContextCard` children. */
+    children: ReactNode;
+}
+/**
+ * A labelled group of retrieved chunks. Rendered as a `<section>` with its
+ * heading wired through `aria-labelledby`, and the cards themselves in a
+ * `<ul>` so assistive technology announces the group size.
+ */
+export declare const ContextCardList: import("react").ForwardRefExoticComponent<ContextCardListProps & import("react").RefAttributes<HTMLElement>>;

package/dist/components/disclosure/Disclosure.d.ts

@@ -0,0 +1,38 @@
+import { type HTMLAttributes, type ReactNode } from "react";
+
+export type DisclosureProps = Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
+    /** Whether the region is expanded. Disclosure is always controlled. */
+    open: boolean;
+    /** Region content. Padding belongs on the content, never on Disclosure. */
+    children?: ReactNode;
+};
+/**
+ * An animated, controlled disclosure region.
+ *
+ * Disclosure animates its own height between collapsed and expanded using the
+ * `grid-template-rows: 0fr -> 1fr` technique, so content of any size animates
+ * without JavaScript measurement. Open animates over
+ * `--motion-duration-moderate` on `--motion-easing-enter`; close animates over
+ * the shorter `--motion-duration-standard` on `--motion-easing-exit`, matching
+ * the foundations asymmetry rule and the Dialog precedent.
+ *
+ * Boundary — Disclosure is presentational and owns the region only. It does
+ * **not** own the trigger, the chevron, focus management, `aria-expanded`, or
+ * `aria-controls`; the caller already owns those and keeps them on its own
+ * trigger. Pass `id` here and reference it from the trigger's `aria-controls`.
+ *
+ * While closed the content is hidden from the accessibility tree and from the
+ * tab order twice over: `visibility: hidden` is deferred behind the collapse
+ * transition (the pattern already used by `secondary-panel.css` and
+ * `workspace-app-shell.css`), and `inert` is applied immediately so nothing
+ * inside can be focused during the closing transition.
+ *
+ * Under `prefers-reduced-motion: reduce` the height animation is dropped
+ * entirely and the region crossfades at `--motion-duration-fast`.
+ */
+export declare const Disclosure: import("react").ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
+    /** Whether the region is expanded. Disclosure is always controlled. */
+    open: boolean;
+    /** Region content. Padding belongs on the content, never on Disclosure. */
+    children?: ReactNode;
+} & import("react").RefAttributes<HTMLDivElement>>;

package/dist/components/dot-field/DotField.d.ts

@@ -0,0 +1,102 @@
+import { type CSSProperties, type RefObject } from "react";
+
+/**
+ * A plain rectangle in the field's own coordinate space — CSS pixels measured
+ * from the top-left of the canvas, not from the viewport. Stored as a plain
+ * object rather than a `DOMRect` so the exclusion maths can be tested without
+ * a DOM.
+ */
+export interface DotFieldRect {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+}
+/**
+ * Spotlight falloff at `distance` from the pointer, in `[0, 1]`.
+ *
+ * Quadratic rather than linear: the brightened region reads as a soft pool of
+ * light with no visible rim, because the derivative goes to zero at the edge.
+ * `0` at and beyond `radius`, `1` exactly under the pointer.
+ *
+ * A non-positive radius disables the spotlight entirely rather than dividing
+ * by zero.
+ */
+export declare function dotFieldFalloff(distance: number, radius: number): number;
+/** Grow a rectangle equally on all sides. */
+export declare function dotFieldInflateRect(rect: DotFieldRect, padding: number): DotFieldRect;
+/**
+ * Shortest distance from a point to a rectangle. Zero when the point is inside
+ * or on the boundary.
+ */
+export declare function dotFieldDistanceToRect(x: number, y: number, rect: DotFieldRect): number;
+/**
+ * How much of a dot survives the exclusion halo, in `[0, 1]`.
+ *
+ * `0` anywhere inside an already-inflated rect — no dot is drawn at all — then
+ * a linear ramp back to `1` over `feather` pixels outside it, so the halo has
+ * no hard cut. With several rects the smallest value wins, which is what makes
+ * overlapping halos merge into one hole instead of cancelling each other out.
+ *
+ * Rects are expected pre-inflated; `dotFieldInflateRect` does that separately
+ * so the padding is applied once per layout rather than once per dot.
+ */
+export declare function dotFieldExclusionAlpha(x: number, y: number, rects: readonly DotFieldRect[], feather: number): number;
+export interface DotFieldProps {
+    /** Lattice pitch in CSS pixels. @default 24 */
+    spacing?: number;
+    /** Radius of a resting dot in CSS pixels. @default 0.5 */
+    dotRadius?: number;
+    /** Opacity of the resting lattice. @default 0.14 */
+    baseAlpha?: number;
+    /** Opacity directly under the pointer. @default 0.75 */
+    peakAlpha?: number;
+    /** Spotlight reach in CSS pixels. @default 180 */
+    radius?: number;
+    /** Dot scale directly under the pointer. @default 2.6 */
+    peakScale?: number;
+    /**
+     * Element whose pointer movement drives the field. Defaults to the host's
+     * own parent, which is the common case: the field is the background layer of
+     * the section it reacts to.
+     */
+    containerRef?: RefObject<HTMLElement | null>;
+    /**
+     * Element the lattice makes room for. Its bounding box, inflated by
+     * `exclusionPadding` and feathered, renders no dots. One element means one
+     * collective halo, however many children it wraps.
+     */
+    exclusionRef?: RefObject<HTMLElement | null>;
+    /**
+     * Static exclusion rects in the field's own coordinate space, as an
+     * alternative to `exclusionRef`. Combined with it when both are given.
+     */
+    exclusionRects?: readonly DotFieldRect[];
+    /** Inflation applied to every exclusion rect. @default 24 */
+    exclusionPadding?: number;
+    /** Alpha ramp width at the exclusion edge. @default 40 */
+    exclusionFeather?: number;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Cursor-reactive dot lattice, as a full-bleed background layer.
+ *
+ * At rest it is a dim monotone grid of dots. Under the pointer a soft pool of
+ * light brightens and enlarges the dots it covers, trailing the cursor by a
+ * frame or two so the surface feels physical rather than pinned. An optional
+ * exclusion element punches a feathered hole in the lattice, so content
+ * floating above the field keeps a clean field of its own.
+ *
+ * Performance: the resting lattice is rasterised once to an offscreen canvas
+ * and blitted each frame, so per-frame work is bounded by the spotlight's
+ * footprint (a few hundred dots) rather than the page's (several thousand).
+ * The rAF loop runs only while the pointer is inside and until the eased
+ * pointer settles; an untouched field costs nothing.
+ *
+ * Colour is resolved from `--color-foreground` at draw time and re-resolved
+ * when `data-theme` changes, so the field is monotone and correct in both
+ * themes without a theme prop. It is decorative: `aria-hidden` and inert to
+ * pointer events.
+ */
+export declare function DotField({ spacing, dotRadius, baseAlpha, peakAlpha, radius, peakScale, containerRef, exclusionRef, exclusionRects, exclusionPadding, exclusionFeather, className, style, }: DotFieldProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/field-message/FieldMessage.d.ts

@@ -13,6 +13,18 @@ export type FieldMessageProps = Omit<HTMLAttributes<HTMLParagraphElement>, "chil
 /**
  * Supporting or validation text for one form control. The consumer owns the
  * ID, ARIA relationship, live-region policy, and validation behavior.
+ *
+ * The message reveals itself on mount rather than popping in: an outer grid
+ * wrapper animates `grid-template-rows: 0fr -> 1fr` from a CSS
+ * `@starting-style` rule, so surrounding layout eases open instead of jumping.
+ * The wrapper is purely presentational — every prop, the `className`, the
+ * forwarded ref, `role="alert"`, and the ARIA relationship stay on the same
+ * `<p>` element they were on before, so nothing about the announcement is
+ * delayed, duplicated, or moved. Browsers without `@starting-style` simply
+ * show the message immediately.
+ *
+ * Exit is owned by the consumer, because the consumer owns the unmount. Wrap
+ * FieldMessage in `Disclosure` and keep it mounted to animate it away.
  */
 export declare const FieldMessage: import("react").ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLParagraphElement>, "children" | "className"> & VariantProps<(props?: ({
     tone?: "error" | "helper" | "warning" | null | undefined;

package/dist/components/filter-table/FilterTable.d.ts

@@ -0,0 +1,61 @@
+import { type HTMLAttributes } from "react";
+
+export declare const filterTableStatuses: readonly ["to-do", "in-progress", "completed"];
+export type FilterTableStatus = (typeof filterTableStatuses)[number];
+export type FilterTableRow = {
+    /** Stable row identity. */
+    id: string;
+    /** Primary task name. */
+    name: string;
+    /** Preformatted date string; rendered with tabular figures. */
+    date: string;
+    status: FilterTableStatus;
+    /** Person or team accountable for the task. */
+    owner: string;
+    /** Optional secondary line under the task name. */
+    detail?: string;
+};
+export type FilterTableProps = Omit<HTMLAttributes<HTMLDivElement>, "children" | "onChange"> & {
+    rows: readonly FilterTableRow[];
+    /** Required accessible name for the table. */
+    caption: string;
+    /** Controlled filter. `null` shows every row. */
+    filter?: FilterTableStatus | null;
+    /** Initial filter for uncontrolled use. */
+    defaultFilter?: FilterTableStatus | null;
+    onFilterChange?: (filter: FilterTableStatus | null) => void;
+    /** Label used on the "show everything" chip. */
+    allLabel?: string;
+    /** Column headers, in render order. */
+    headers?: {
+        name: string;
+        date: string;
+        status: string;
+        owner: string;
+    };
+};
+/**
+ * A light task table whose status chips reorganize the visible rows in place.
+ * Row movement is animated with a FLIP pass that only touches `transform`.
+ */
+export declare const FilterTable: import("react").ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLDivElement>, "children" | "onChange"> & {
+    rows: readonly FilterTableRow[];
+    /** Required accessible name for the table. */
+    caption: string;
+    /** Controlled filter. `null` shows every row. */
+    filter?: FilterTableStatus | null;
+    /** Initial filter for uncontrolled use. */
+    defaultFilter?: FilterTableStatus | null;
+    onFilterChange?: (filter: FilterTableStatus | null) => void;
+    /** Label used on the "show everything" chip. */
+    allLabel?: string;
+    /** Column headers, in render order. */
+    headers?: {
+        name: string;
+        date: string;
+        status: string;
+        owner: string;
+    };
+} & import("react").RefAttributes<HTMLDivElement>>;
+export type FilterTableStatusLabelMap = Record<FilterTableStatus, string>;
+export declare const filterTableStatusLabels: FilterTableStatusLabelMap;

package/dist/components/flap-text/FlapText.d.ts

@@ -0,0 +1,68 @@
+import { type CSSProperties } from "react";
+
+/**
+ * Milliseconds one cell spends flipping. Mirrors `--motion-duration-moderate`;
+ * the CSS reads the token directly and only falls back to this number when the
+ * caller overrides `flapDuration`.
+ */
+export declare const FLAP_TEXT_DEFAULT_DURATION_MS = 220;
+/** Milliseconds each successive cell waits before it starts flipping. */
+export declare const FLAP_TEXT_DEFAULT_STAGGER_MS = 18;
+export type FlapTextElement = "span" | "div" | "p" | "strong" | "em";
+export type FlapTextAlign = "start" | "center" | "end";
+export interface FlapTextProps {
+    /** The string to display. Changing it flips the characters that differ. */
+    text: string;
+    /** Host element. @default "span" */
+    as?: FlapTextElement;
+    /** Per-character delay, in milliseconds. @default 18 */
+    stagger?: number;
+    /** Flip duration, in milliseconds. @default `--motion-duration-moderate` */
+    flapDuration?: number;
+    /** Horizontal alignment of the rendered line. @default "start" */
+    align?: FlapTextAlign;
+    className?: string;
+    style?: CSSProperties;
+}
+export type FlapCell = {
+    /** Glyph shown once the cell settles. */
+    char: string;
+    /** Glyph rotating out, or `null` when the cell is new or settled. */
+    previous: string | null;
+    /** Whether this cell is mid-flip. */
+    flap: boolean;
+    /** Trailing cell that disappears when the text got shorter. */
+    exiting: boolean;
+};
+/**
+ * A Solari board only moves the cells whose glyph actually changed. Identical
+ * characters at the same index stay perfectly still, which is both faithful and
+ * far calmer to read.
+ */
+export declare function flapTextCells(previous: string, next: string): FlapCell[];
+/**
+ * Split-flap text.
+ *
+ * Each character is its own cell. When `text` changes, only the cells whose
+ * glyph differs flip: the old glyph rotates away around the horizontal midline
+ * while the new one rotates in behind it, staggered left to right.
+ *
+ * Sharpness: cells are inline-block with `preserve-3d` and hidden backfaces,
+ * `will-change: transform` is present only while a cell is actually flipping,
+ * and settled cells carry `transform: none` exactly — never an identity matrix
+ * — so the browser re-rasterises the glyph at full fidelity. No scale is ever
+ * applied, and the component sets no font property, so text metrics are the
+ * caller's.
+ *
+ * Accessibility: cells are `aria-hidden`, the host carries `aria-label={text}`,
+ * and a visually hidden polite live region announces one clean string.
+ *
+ * Reduced motion: no 3D at all — a fast opacity crossfade swaps the glyph.
+ */
+export declare function FlapText({ text, as, stagger, flapDuration, align, className, style, }: FlapTextProps): import("react").DetailedReactHTMLElement<{
+    className: string;
+    style: CSSProperties | undefined;
+    "aria-label": string;
+    "data-align": FlapTextAlign;
+    "data-flapping": string;
+}, HTMLElement>;