@mithrl/design-system 0.3.0 → 0.4.0

package/dist/components/insight-cards/InsightCards.d.ts

@@ -0,0 +1,97 @@
+import { type HTMLAttributes, type ReactNode } from "react";
+
+/** Direction of a change, mapped to semantic color. */
+export type InsightTone = "neutral" | "success" | "danger";
+/**
+ * One run of an insight sentence. `text` reads as prose, `entity` names a
+ * cohort, gene, batch, or assay, and `metric` carries a figure or delta.
+ */
+export type InsightSegment = {
+    kind: "text";
+    text: string;
+} | {
+    kind: "entity";
+    text: string;
+} | {
+    kind: "metric";
+    text: string;
+    tone?: InsightTone;
+};
+/** A compact before/after row rendered beneath the sentence. */
+export type InsightComparison = {
+    /** What is being compared, e.g. `Median TPM, responders`. */
+    label: string;
+    /** Signed relative change, already formatted, e.g. `+18.4%`. */
+    delta: string;
+    /** Absolute value, already formatted, e.g. `412.6 TPM`. */
+    value: string;
+    /** Semantic direction. @default "neutral" */
+    tone?: InsightTone;
+};
+/** A single plotted observation for the embedded mini chart. */
+export type InsightChartPoint = {
+    /** Axis label for the scrub readout, e.g. `Day 14`. */
+    label: string;
+    /** Plotted magnitude in the series' own units. */
+    value: number;
+};
+export type InsightChart = {
+    points: readonly InsightChartPoint[];
+    /** Unit suffix shown in the scrub readout, e.g. `TPM`. */
+    unit?: string;
+    /** Accessible summary of the series. Required — the SVG carries no text. */
+    ariaLabel: string;
+};
+export type InsightFollowUp = {
+    /** The suggested next question, phrased as the agent would ask it. */
+    label: string;
+    /** Stable identifier handed back to `onFollowUpSelect`. */
+    id?: string;
+};
+export type Insight = {
+    /** Stable identity for the page. */
+    id: string;
+    /** Short headline for the insight. */
+    title: string;
+    /** The insight itself, composed of prose, entity, and metric runs. */
+    sentence: readonly InsightSegment[];
+    /** Optional comparison rows. */
+    comparisons?: readonly InsightComparison[];
+    /** Optional embedded trend chart. */
+    chart?: InsightChart;
+    /** Optional suggested follow-up rendered in the footer. */
+    followUp?: InsightFollowUp;
+};
+export type InsightCardsProps = Omit<HTMLAttributes<HTMLElement>, "children" | "onSelect"> & {
+    /** The pages, in reading order. At least one is required. */
+    insights: readonly Insight[];
+    /** Header title. @default "Insights" */
+    heading?: ReactNode;
+    /** Controlled page index. */
+    page?: number;
+    /** Initial page index for uncontrolled use. @default 0 */
+    defaultPage?: number;
+    /** Called with the next index whenever the page changes. */
+    onPageChange?: (page: number) => void;
+    /** Called when the footer follow-up chip is activated. */
+    onFollowUpSelect?: (followUp: InsightFollowUp, insight: Insight) => void;
+};
+/**
+ * A paged carousel of agent-authored insights. Each page states one finding
+ * in a sentence built from entity and metric chips, supports it with
+ * comparison rows and a mini trend chart, and offers one follow-up question.
+ */
+export declare const InsightCards: import("react").ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLElement>, "children" | "onSelect"> & {
+    /** The pages, in reading order. At least one is required. */
+    insights: readonly Insight[];
+    /** Header title. @default "Insights" */
+    heading?: ReactNode;
+    /** Controlled page index. */
+    page?: number;
+    /** Initial page index for uncontrolled use. @default 0 */
+    defaultPage?: number;
+    /** Called with the next index whenever the page changes. */
+    onPageChange?: (page: number) => void;
+    /** Called when the footer follow-up chip is activated. */
+    onFollowUpSelect?: (followUp: InsightFollowUp, insight: Insight) => void;
+} & import("react").RefAttributes<HTMLElement>>;

package/dist/components/number-flow/NumberFlow.d.ts

@@ -0,0 +1,93 @@
+import { type CSSProperties } from "react";
+
+/**
+ * Milliseconds one digit spends rolling. Mirrors `--motion-duration-moderate`;
+ * the CSS reads the token directly and only falls back to this number when the
+ * caller overrides `rollDuration`.
+ */
+export declare const NUMBER_FLOW_DEFAULT_DURATION_MS = 220;
+/** Milliseconds each successive cell waits before it starts rolling. */
+export declare const NUMBER_FLOW_DEFAULT_STAGGER_MS = 18;
+export type NumberFlowElement = "span" | "div" | "p" | "strong" | "em";
+export type NumberFlowSize = "small" | "medium" | "large";
+export interface NumberFlowProps {
+    /** The number to display. Changing it rolls the digits that differ. */
+    value: number;
+    /** `Intl.NumberFormat` options. Changing them reformats and animates. */
+    format?: Intl.NumberFormatOptions;
+    /** BCP 47 locale(s) for formatting. Defaults to the runtime locale. */
+    locale?: string | string[];
+    /**
+     * Height of the clipped roll window, as a multiple of the inherited line box.
+     * This is the only size NumberFlow owns — it never sets a font property.
+     * @default "medium"
+     */
+    size?: NumberFlowSize;
+    /** Host element. @default "span" */
+    as?: NumberFlowElement;
+    /** Per-digit delay, in milliseconds. @default 18 */
+    stagger?: number;
+    /** Roll duration, in milliseconds. @default `--motion-duration-moderate` */
+    rollDuration?: number;
+    className?: string;
+    style?: CSSProperties;
+}
+export type NumberFlowDirection = "up" | "down";
+export type NumberFlowCell = {
+    /** Glyph shown once the cell settles. */
+    char: string;
+    /** Glyph leaving the window, or `null` when the cell is new or unchanged. */
+    previous: string | null;
+    /** Digit-to-digit change: a clipped vertical roll. */
+    roll: boolean;
+    /** Any other change (separator, sign, or a brand new place): a crossfade. */
+    fade: boolean;
+    /** Roll direction, taken from the sign of the value delta. */
+    direction: NumberFlowDirection;
+};
+/**
+ * Cells are aligned from the RIGHT, not the left: in a number the units column
+ * is the fixed point, so 99 -> 100 must roll the two nines against the new
+ * tens and units rather than sliding every place one column over.
+ *
+ * Only cells whose glyph actually changed move — the same rule FlapText
+ * applies to characters. A digit replacing a digit rolls; anything else
+ * (a separator appearing, a sign flipping, a brand new leading place) is a
+ * quiet crossfade, because rolling a comma into a digit reads as noise.
+ */
+export declare function numberFlowCells(previous: string, next: string, direction?: NumberFlowDirection): NumberFlowCell[];
+/**
+ * A number that resolves instead of blinking.
+ *
+ * Each character of the formatted value is its own cell. When `value` changes,
+ * only the cells whose glyph differs move: a digit rolls vertically through a
+ * clipped window — the outgoing glyph leaves through one edge as the incoming
+ * one arrives from the other, softened by `--motion-blur-soft` — while
+ * separators and new leading places simply crossfade. Cells are staggered left
+ * to right so the least significant digit is the last to settle.
+ *
+ * This is a short roll, not a slot machine. The spinning-counter recipe's
+ * multi-revolution 0-9 strip, its directional SVG blur filter and its masked
+ * window edges are all deliberately absent: a scientific workspace wants a
+ * number that has clearly *changed*, not one that celebrates.
+ *
+ * Sharpness: settled cells carry `transform: none` exactly — never an identity
+ * matrix — `will-change` is present only while a cell is in flight, no scale is
+ * ever applied, and the component sets no font property, so text metrics are
+ * the caller's. `font-variant-numeric: tabular-nums` keeps the box from
+ * wobbling as digits change width.
+ *
+ * Accessibility: cells are `aria-hidden`, the host carries the formatted value
+ * as `aria-label`, and a visually hidden polite live region announces one clean
+ * string.
+ *
+ * Reduced motion: no roll and no blur — the value swaps instantly behind a
+ * `--motion-duration-fast` opacity crossfade.
+ */
+export declare function NumberFlow({ value, format, locale, size, as, stagger, rollDuration, className, style, }: NumberFlowProps): import("react").DetailedReactHTMLElement<{
+    className: string;
+    style: CSSProperties | undefined;
+    "aria-label": string;
+    "data-size": NumberFlowSize;
+    "data-animating": string;
+}, HTMLElement>;

package/dist/components/progress-indicator/ProgressIndicator.d.ts

@@ -7,8 +7,16 @@ export declare const progressIndicatorVariants: (props?: ({
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 export type ProgressIndicatorSize = NonNullable<VariantProps<typeof progressIndicatorVariants>["size"]>;
 export type ProgressIndicatorTone = NonNullable<VariantProps<typeof progressIndicatorVariants>["tone"]>;
+/**
+ * Loading is the default so every existing usage keeps its current behavior.
+ * Done resolves the same indicator into a drawn completion check.
+ */
+export type ProgressIndicatorState = "loading" | "done";
 type RestrictedProgressIndicatorAttribute = "aria-atomic" | "aria-busy" | "aria-hidden" | "aria-label" | "aria-live" | "children" | "onClick" | "onDoubleClick" | "onKeyDown" | "onKeyUp" | "role" | "tabIndex";
-type ProgressIndicatorBaseProps = Omit<HTMLAttributes<HTMLSpanElement>, RestrictedProgressIndicatorAttribute> & VariantProps<typeof progressIndicatorVariants>;
+type ProgressIndicatorBaseProps = Omit<HTMLAttributes<HTMLSpanElement>, RestrictedProgressIndicatorAttribute> & VariantProps<typeof progressIndicatorVariants> & {
+    /** Completion state. Defaults to `"loading"`. */
+    state?: ProgressIndicatorState;
+};
 type InformativeProgressIndicatorProps = {
     /** Concise accessible name announced through the status live region. */
     label: string;

package/dist/components/prompt-bar/PromptBar.d.ts

@@ -0,0 +1,103 @@
+import { type IconGlyphComponent } from "../icon/Icon";
+
+
+export type PromptBarShape = "rounded" | "pill";
+/** Trigger characters that open the anchored suggestion popover. */
+export type PromptBarTrigger = "@" | "/";
+export type PromptBarSource = {
+    /** Stable identity used for selection and de-duplication. */
+    id: string;
+    /** Visible row label and entity chip label. */
+    label: string;
+    /** Short qualifier rendered beside the label, e.g. "dataset". */
+    kind?: string;
+    /** Optional approved Lucide glyph for the row and the chip. */
+    icon?: IconGlyphComponent;
+};
+export type PromptBarCommand = {
+    /** Stable identity, also inserted as `/{id}` unless `insert` is provided. */
+    id: string;
+    /** Visible row label. */
+    label: string;
+    /** Short qualifier rendered beside the label, e.g. "analysis". */
+    kind?: string;
+    /** Optional approved Lucide glyph for the row. */
+    icon?: IconGlyphComponent;
+    /** Text inserted in place of the `/` token. Defaults to `/{id}`. */
+    insert?: string;
+};
+export type PromptBarModel = {
+    /** Stable identity used for selection. */
+    id: string;
+    /** Visible label in the trigger and in the option list. */
+    label: string;
+    /** Optional short qualifier shown under the label in the option list. */
+    description?: string;
+};
+export type PromptBarLabels = {
+    input: string;
+    submit: string;
+    dictate: string;
+    model: string;
+    attachments: string;
+    removeSource: string;
+    sourceSuggestions: string;
+    commandSuggestions: string;
+    emptySuggestions: string;
+};
+export type PromptBarProps = {
+    /** Controlled prompt text. */
+    value: string;
+    /** Called on every keystroke and on suggestion insertion. */
+    onValueChange: (value: string) => void;
+    /** Called with the trimmed prompt and the sources attached to it. */
+    onSubmit?: (value: string, sources: readonly PromptBarSource[]) => void;
+    /** Rows offered by the `@` popover. */
+    sources?: readonly PromptBarSource[];
+    /** Rows offered by the `/` popover. */
+    commands?: readonly PromptBarCommand[];
+    /** Controlled attachment chips. Omit to let PromptBar own them. */
+    selectedSources?: readonly PromptBarSource[];
+    /** Initial attachment chips for uncontrolled use. */
+    defaultSelectedSources?: readonly PromptBarSource[];
+    /** Called whenever the attachment row changes. */
+    onSelectedSourcesChange?: (sources: readonly PromptBarSource[]) => void;
+    /** Models offered by the footer model picker. */
+    models?: readonly PromptBarModel[];
+    /** Controlled model id. */
+    selectedModel?: string;
+    /** Called with the newly chosen model id. */
+    onModelChange?: (modelId: string) => void;
+    /** Renders the dictation microphone slot. Presentation only. */
+    onDictate?: () => void;
+    /** Geometry of the bar. */
+    shape?: PromptBarShape;
+    placeholder?: string;
+    disabled?: boolean;
+    autoFocus?: boolean;
+    name?: string;
+    labels?: Partial<PromptBarLabels>;
+    className?: string;
+    /** Storybook-only hook that forces the popover open for review. */
+    "data-preview-trigger"?: PromptBarTrigger;
+};
+type TriggerMatch = {
+    trigger: PromptBarTrigger;
+    query: string;
+    start: number;
+    end: number;
+};
+/**
+ * Reads the token immediately before the caret. A token qualifies when it
+ * starts at the beginning of the value or after whitespace, is introduced by
+ * `@` or `/`, and contains no whitespace of its own.
+ */
+export declare function readTriggerAtCaret(value: string, caret: number): TriggerMatch | null;
+/**
+ * Command-style prompt entry with `@` source mentions, `/` commands, an
+ * attachment chip row, and a model rail. PromptBar is a sibling of Composer,
+ * not a replacement: Composer owns conversational entry, PromptBar owns
+ * command-shaped prompting where sources and commands are addressable.
+ */
+export declare const PromptBar: import("react").ForwardRefExoticComponent<PromptBarProps & import("react").RefAttributes<HTMLTextAreaElement>>;
+export {};

package/dist/components/recommendation-card/RecommendationCard.d.ts

@@ -0,0 +1,77 @@
+import { type HTMLAttributes, type ReactNode } from "react";
+import type { MetadataTone } from "../badge/Badge";
+
+/** How sure the agent is about the action it is proposing. */
+export type RecommendationConfidence = "low" | "medium" | "high";
+/** A path the agent considered but did not lead with. */
+export interface RecommendationAlternative {
+    id: string;
+    label: string;
+    /** One sentence on what this path would do differently. */
+    description?: string;
+    /** Short status Tag, e.g. "Needs review" or "No signal". */
+    statusLabel?: string;
+    statusTone?: MetadataTone;
+    disabled?: boolean;
+}
+export interface RecommendationEntityChipProps {
+    children: ReactNode;
+    /** Optional kind shown to assistive tech, e.g. "dataset" or "gene". */
+    kind?: string;
+    className?: string;
+}
+/**
+ * Inline reference to a real object — a dataset, a run, a gene — set inside
+ * the recommendation body so the sentence stays readable.
+ */
+export declare function RecommendationEntityChip({ children, kind, className, }: RecommendationEntityChipProps): import("react/jsx-runtime").JSX.Element;
+type RestrictedRecommendationCardAttribute = "children" | "role" | "title";
+export type RecommendationCardProps = Omit<HTMLAttributes<HTMLElement>, RestrictedRecommendationCardAttribute> & {
+    /** The suggestion, phrased as a question the scientist can answer. */
+    headline: ReactNode;
+    /** What the agent would actually do. Inline entity chips belong here. */
+    body?: ReactNode;
+    confidence: RecommendationConfidence;
+    /** Overrides the default "High confidence" style label. */
+    confidenceLabel?: string;
+    /** Why the agent is this confident. Shown next to the meter. */
+    confidenceReason?: ReactNode;
+    alternatives?: RecommendationAlternative[];
+    alternativesLabel?: string;
+    /** Controlled disclosure state for the alternatives list. */
+    alternativesOpen?: boolean;
+    defaultAlternativesOpen?: boolean;
+    onAlternativesOpenChange?: (open: boolean) => void;
+    onAlternativeSelect?: (alternative: RecommendationAlternative) => void;
+    onAccept?: () => void;
+    acceptLabel?: string;
+    /** Disables the primary action while the proposal is still resolving. */
+    acceptDisabled?: boolean;
+};
+/**
+ * An agent suggestion with its confidence shown plainly, the alternatives it
+ * weighed kept one click away, and a single primary action to accept.
+ */
+export declare const RecommendationCard: import("react").ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLElement>, RestrictedRecommendationCardAttribute> & {
+    /** The suggestion, phrased as a question the scientist can answer. */
+    headline: ReactNode;
+    /** What the agent would actually do. Inline entity chips belong here. */
+    body?: ReactNode;
+    confidence: RecommendationConfidence;
+    /** Overrides the default "High confidence" style label. */
+    confidenceLabel?: string;
+    /** Why the agent is this confident. Shown next to the meter. */
+    confidenceReason?: ReactNode;
+    alternatives?: RecommendationAlternative[];
+    alternativesLabel?: string;
+    /** Controlled disclosure state for the alternatives list. */
+    alternativesOpen?: boolean;
+    defaultAlternativesOpen?: boolean;
+    onAlternativesOpenChange?: (open: boolean) => void;
+    onAlternativeSelect?: (alternative: RecommendationAlternative) => void;
+    onAccept?: () => void;
+    acceptLabel?: string;
+    /** Disables the primary action while the proposal is still resolving. */
+    acceptDisabled?: boolean;
+} & import("react").RefAttributes<HTMLElement>>;
+export {};

package/dist/components/records-table/RecordsTable.d.ts

@@ -0,0 +1,87 @@
+import { type ForwardedRef, type HTMLAttributes, type ReactNode, type TableHTMLAttributes } from "react";
+import type { MetadataTone } from "../badge/Badge";
+
+export type RecordsTableAlign = "start" | "end";
+export type RecordsTableSortDirection = "ascending" | "descending";
+export type RecordsTableSort = {
+    /** Column currently driving row order. */
+    columnId: string;
+    direction: RecordsTableSortDirection;
+};
+export type RecordsTableColumn<Row> = {
+    /** Stable identifier used for sorting and cell keys. */
+    id: string;
+    /** Visible column header text. */
+    header: string;
+    /** Enables the header sort control and aria-sort reporting. */
+    sortable?: boolean;
+    /** Horizontal alignment of the header and its cells. */
+    align?: RecordsTableAlign;
+    /** Cell renderer. Defaults to the raw `sortValue` string. */
+    render?: (row: Row, index: number) => ReactNode;
+    /** Comparable primitive used when this column is sorted. */
+    sortValue?: (row: Row) => string | number;
+    /** Optional fixed column width, e.g. `var(--space-64)`. */
+    width?: string;
+};
+export type RecordsTableProps<Row> = Omit<TableHTMLAttributes<HTMLTableElement>, "children"> & {
+    columns: readonly RecordsTableColumn<Row>[];
+    rows: readonly Row[];
+    /** Stable row identity used for React keys. */
+    getRowId: (row: Row, index: number) => string;
+    /** Required accessible name for the grid. */
+    caption: string;
+    /** Renders the caption above the table instead of only for assistive tech. */
+    captionVisible?: boolean;
+    /** Renders the leading ordinal / group-letter cell. */
+    showIndex?: boolean;
+    /** When provided, alphabetical separator rows are inserted on letter change. */
+    groupLetter?: (row: Row) => string;
+    /** Controlled sort state. */
+    sort?: RecordsTableSort | null;
+    /** Initial sort for uncontrolled use. */
+    defaultSort?: RecordsTableSort | null;
+    onSortChange?: (sort: RecordsTableSort) => void;
+    /** Summary cells rendered in a sticky-free footer row, keyed by column id. */
+    footer?: Partial<Record<string, ReactNode>>;
+    /** Optional label rendered in the footer's leading cell. */
+    footerLabel?: ReactNode;
+};
+/**
+ * A column-configuration driven record grid. RecordsTable owns row order,
+ * sticky header semantics, and optional alphabetical grouping. Cell content
+ * is supplied by the caller, usually through the exported cell primitives.
+ */
+declare function RecordsTableInner<Row>({ columns, rows, getRowId, caption, captionVisible, showIndex, groupLetter, sort, defaultSort, onSortChange, footer, footerLabel, className, ...props }: RecordsTableProps<Row>, ref: ForwardedRef<HTMLTableElement>): import("react/jsx-runtime").JSX.Element;
+export declare const RecordsTable: <Row>(props: RecordsTableProps<Row> & {
+    ref?: ForwardedRef<HTMLTableElement>;
+}) => ReturnType<typeof RecordsTableInner>;
+export type RecordsTableTagsProps = HTMLAttributes<HTMLDivElement> & {
+    /** Category labels rendered as Tag metadata. */
+    tags: readonly string[];
+    /** Number of tags shown before collapsing into a "+N" indicator. */
+    max?: number;
+    tone?: MetadataTone;
+};
+/** Tag cluster cell with a deterministic "+N" overflow indicator. */
+export declare function RecordsTableTags({ tags, max, tone, className, ...props }: RecordsTableTagsProps): import("react/jsx-runtime").JSX.Element;
+export declare const recordsTableStrengthLevels: readonly ["No communication", "Very weak", "Weak", "Strong", "Very strong"];
+export type RecordsTableStrengthLevel = 0 | 1 | 2 | 3 | 4;
+export type RecordsTableStrengthProps = HTMLAttributes<HTMLSpanElement> & {
+    /** Ordinal level from 0 (no communication) through 4 (very strong). */
+    level: RecordsTableStrengthLevel;
+    /** Hides the text label while keeping the accessible name. */
+    hideLabel?: boolean;
+};
+/** Five-step ordinal meter for relationship or signal strength. */
+export declare function RecordsTableStrength({ level, hideLabel, className, ...props }: RecordsTableStrengthProps): import("react/jsx-runtime").JSX.Element;
+export type RecordsTableLinkProps = {
+    href: string;
+    children: ReactNode;
+    /** Marks the destination as external and adds safe rel attributes. */
+    external?: boolean;
+    className?: string;
+};
+/** Destination cell that keeps the external affordance inside the grid. */
+export declare function RecordsTableLink({ href, children, external, className, }: RecordsTableLinkProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/resizable-panels/ResizablePanels.d.ts

@@ -30,6 +30,17 @@ export type ResizablePanelGroupProps = Omit<HTMLAttributes<HTMLDivElement>, "chi
     onSecondarySizeChange?: (size: number) => void;
     /** Reports the final pointer value or each keyboard step in pixels. */
     onSecondarySizeCommit?: (size: number) => void;
+    /**
+     * Reports one drag-to-dismiss intent per pointer drag when the pointer
+     * travels past a panel minimum by more than `dismissThreshold`. Visibility
+     * stays with the consumer; the group never hides a panel on its own.
+     */
+    onCollapseIntent?: (region: "primary" | "secondary") => void;
+    /**
+     * Share of a panel minimum the pointer must cross before a drag counts as a
+     * dismissal request. Defaults to 0.5, i.e. half the minimum width.
+     */
+    dismissThreshold?: number;
     /** Exactly Primary Panel, Handle, and Secondary Panel in that order. */
     children: ReactNode;
 };
@@ -74,6 +85,17 @@ export declare const ResizablePanelGroup: import("react").ForwardRefExoticCompon
     onSecondarySizeChange?: (size: number) => void;
     /** Reports the final pointer value or each keyboard step in pixels. */
     onSecondarySizeCommit?: (size: number) => void;
+    /**
+     * Reports one drag-to-dismiss intent per pointer drag when the pointer
+     * travels past a panel minimum by more than `dismissThreshold`. Visibility
+     * stays with the consumer; the group never hides a panel on its own.
+     */
+    onCollapseIntent?: (region: "primary" | "secondary") => void;
+    /**
+     * Share of a panel minimum the pointer must cross before a drag counts as a
+     * dismissal request. Defaults to 0.5, i.e. half the minimum width.
+     */
+    dismissThreshold?: number;
     /** Exactly Primary Panel, Handle, and Secondary Panel in that order. */
     children: ReactNode;
 } & import("react").RefAttributes<HTMLDivElement>>;

package/dist/components/selection-actions/SelectionActions.d.ts

@@ -0,0 +1,72 @@
+import { type HTMLAttributes, type RefObject } from "react";
+import { type IconGlyphComponent } from "../icon/Icon";
+
+/** A viewport-relative rectangle, matching the shape of `DOMRect`. */
+export interface SelectionRect {
+    top: number;
+    left: number;
+    width: number;
+    height: number;
+}
+export interface UseSelectionRectOptions {
+    /**
+     * Restrict tracking to selections that start and end inside this element.
+     * Omit to track the whole document.
+     */
+    containerRef?: RefObject<HTMLElement | null>;
+    /** Stop tracking without unmounting the caller. @default false */
+    disabled?: boolean;
+}
+/**
+ * Tracks the current document selection and returns its viewport-relative
+ * rectangle, or `null` when nothing is selected.
+ *
+ * Recomputes on `selectionchange` and on scroll/resize so the toolbar stays
+ * pinned to the passage while the page moves under it. Safe during SSR: the
+ * first render returns `null` and tracking starts after mount.
+ */
+export declare function useSelectionRect({ containerRef, disabled, }?: UseSelectionRectOptions): SelectionRect | null;
+export interface SelectionAction {
+    /** Stable identity, passed to `onSelect` and used as the React key. */
+    id: string;
+    /** Visible label. Keep it a single verb where possible. */
+    label: string;
+    /** Optional approved Lucide glyph shown before the label. */
+    icon?: IconGlyphComponent;
+    /**
+     * Emphasis. `primary` actions read as full labelled buttons; `secondary`
+     * actions are compact and sit after a divider.
+     * @default "primary"
+     */
+    emphasis?: "primary" | "secondary";
+    /** Invoked when the action is chosen. */
+    onSelect: () => void;
+    /** Renders the action non-interactive. */
+    disabled?: boolean;
+}
+export interface SelectionActionsProps extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
+    /** Actions offered for the highlighted passage. */
+    actions: SelectionAction[];
+    /**
+     * Viewport-relative rectangle of the passage. Pass the value from
+     * `useSelectionRect()`, or your own rect for a controlled placement. When
+     * `null` the toolbar renders nothing.
+     */
+    anchorRect: SelectionRect | null;
+    /** Called on Escape, on a click outside, or after an action is chosen. */
+    onDismiss?: () => void;
+    /** Accessible name for the toolbar. @default "Actions for the selected text" */
+    label?: string;
+    /** Gap between the passage and the toolbar, in pixels. @default 8 */
+    offset?: number;
+}
+/**
+ * A floating toolbar anchored above a highlighted passage.
+ *
+ * Keyboard contract: the bar is a `role="toolbar"` with roving tabindex — one
+ * tab stop for the whole bar, then Arrow Left/Right to move between actions,
+ * with Home and End jumping to the ends. Escape dismisses without acting, as
+ * does a click outside the bar. Focus is never stolen from the document
+ * selection; the bar becomes reachable by Tab and only takes focus once entered.
+ */
+export declare const SelectionActions: import("react").ForwardRefExoticComponent<SelectionActionsProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/components/skeleton-reveal/SkeletonReveal.d.ts

@@ -0,0 +1,33 @@
+import { type HTMLAttributes, type ReactNode } from "react";
+
+export interface SkeletonRevealProps extends Omit<HTMLAttributes<HTMLDivElement>, "children" | "placeholder"> {
+    /** Whether the real content has arrived. Flipping this plays the hand-off. */
+    loaded: boolean;
+    /** The loading surface — normally one or more `Skeleton` elements. */
+    placeholder: ReactNode;
+    /** The real content. */
+    children: ReactNode;
+}
+/**
+ * Cross-fades a loading placeholder into the content that replaces it, so
+ * arriving data resolves instead of snapping.
+ *
+ * Both layers occupy the same grid cell, so they stack without either one
+ * leaving the flow: the box is as tall as whichever layer is taller and the
+ * swap costs no layout. The outgoing placeholder fades away through
+ * `--motion-blur-soft` while the content fades in from the same blur, the two
+ * crossing through each other over one shared duration.
+ *
+ * The hidden layer is `visibility: hidden`, so it is out of the tab order and
+ * out of the accessibility tree until it is the live one — the visibility
+ * switch is delayed to the end of the fade on the way out and immediate on the
+ * way in.
+ *
+ * `Skeleton` itself is untouched by this: it stays a decorative surface that
+ * rejects children and semantics. The hand-off needs both layers mounted at
+ * once, which a prop on a childless primitive cannot express.
+ *
+ * Reduced motion: no blur and no cross-fade timing — the layers swap behind a
+ * `--motion-duration-fast` opacity change.
+ */
+export declare const SkeletonReveal: import("react").ForwardRefExoticComponent<SkeletonRevealProps & import("react").RefAttributes<HTMLDivElement>>;