@refraction-ui/react 0.13.0 → 0.15.0

package/dist/internal/react-terminal/index.d.ts

@@ -0,0 +1,39 @@
+import * as React from 'react';
+import { TerminalLine } from '../terminal/index.js';
+export { TerminalLine, TerminalLineKind } from '../terminal/index.js';
+
+/** Height cap for the scrollable terminal surface. */
+type TerminalMaxHeight = 'sm' | 'md' | 'lg' | 'none';
+interface TerminalProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** Lines to render in order. Each line's `kind` determines its styling. */
+    lines: TerminalLine[];
+    /**
+     * Prompt symbol prepended to `command` lines.
+     * @default '$'
+     */
+    promptSymbol?: string;
+    /**
+     * Maximum height of the scroll region before it becomes scrollable.
+     * @default 'md'
+     */
+    maxHeight?: TerminalMaxHeight;
+    /** Accessible label for the live region (e.g. `'Run output'`). */
+    'aria-label'?: string;
+}
+/**
+ * Terminal — a read-only output console panel.
+ *
+ * Renders a monospaced scroll region (`role="log"`, `aria-live="polite"`) with
+ * each line styled by its semantic kind:
+ * - `command` — foreground bold, prefixed with the prompt symbol
+ * - `stdout`  — foreground
+ * - `stderr`  — destructive (error token)
+ * - `info`    — muted-foreground
+ * - `success` — emerald / success token
+ *
+ * This is a presentational component — it has no internal state and does not
+ * handle keyboard input (v1). Pass new lines from the parent to stream output.
+ */
+declare const Terminal: React.ForwardRefExoticComponent<TerminalProps & React.RefAttributes<HTMLDivElement>>;
+
+export { Terminal, type TerminalMaxHeight, type TerminalProps };

package/dist/internal/react-test-results/index.d.ts

@@ -0,0 +1,21 @@
+import * as React from 'react';
+import { TestResultData } from '../test-results/index.js';
+export { TestResultData, TestStatus } from '../test-results/index.js';
+
+interface TestResultsProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'results'> {
+    /** Array of test case results to display. */
+    results: TestResultData[];
+    /** When true, renders a summary bar showing "{passed}/{total} passed". */
+    showSummary?: boolean;
+}
+/**
+ * TestResults — displays a list of test case results with pass/fail/skip
+ * status, optional expected/actual diff for failures, and an optional summary
+ * bar.
+ *
+ * Renders `role="list"` on the container; each row has `role="listitem"`.
+ * Logic and styles come from the headless `@refraction-ui/test-results` core.
+ */
+declare const TestResults: React.ForwardRefExoticComponent<TestResultsProps & React.RefAttributes<HTMLDivElement>>;
+
+export { TestResults, type TestResultsProps };

package/dist/internal/react-timeline/index.d.ts

@@ -0,0 +1,35 @@
+import * as React from 'react';
+import { TimelineItemData, TimelineOrientation } from '../timeline/index.js';
+export { TimelineItemData, TimelineItemStatus, TimelineOrientation } from '../timeline/index.js';
+
+interface TimelineItemProps {
+    /** The normalised item data. */
+    item: Required<TimelineItemData>;
+    /** Orientation inherited from the parent Timeline. */
+    orientation: TimelineOrientation;
+    /** True when this is the last item (hides the trailing connector). */
+    isLast: boolean;
+}
+/** A single event entry inside a Timeline. */
+declare const TimelineItem: React.ForwardRefExoticComponent<TimelineItemProps & React.RefAttributes<HTMLLIElement>>;
+interface TimelineProps extends Omit<React.HTMLAttributes<HTMLUListElement>, 'children'> {
+    /** Ordered list of events to render. */
+    items: TimelineItemData[];
+    /** Layout direction. Defaults to `'vertical'`. */
+    orientation?: TimelineOrientation;
+    /**
+     * Optional render-prop override for a single item.
+     * Receives the normalised item and its index; return a React node.
+     */
+    renderItem?: (item: Required<TimelineItemData>, index: number, isLast: boolean) => React.ReactNode;
+}
+/**
+ * Timeline — a time-ordered list of events with a marker rail.
+ *
+ * Renders `role="list"`; each item carries `role="listitem"`.
+ * Supports vertical (default) and horizontal orientations.
+ * Pass `renderItem` to take full control of individual entries.
+ */
+declare const Timeline: React.ForwardRefExoticComponent<TimelineProps & React.RefAttributes<HTMLUListElement>>;
+
+export { Timeline, TimelineItem, type TimelineItemProps, type TimelineProps };

package/dist/internal/react-video-grid/index.d.ts

@@ -0,0 +1,33 @@
+import * as React from 'react';
+import { VideoGridLayout } from '../video-grid/index.js';
+export { VideoGridLayout } from '../video-grid/index.js';
+import { VideoTileData } from '../react-video-tile/index.js';
+export { VideoTileData } from '../react-video-tile/index.js';
+
+interface VideoGridProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'color' | 'content'> {
+    /** List of participant data to render as tiles. */
+    participants: VideoTileData[];
+    /**
+     * Grid layout mode.
+     * - 'auto'    — grid unless ≤1 participant (falls back to speaker)
+     * - 'grid'    — always uniform CSS grid
+     * - 'speaker' — spotlight for `spotlightId` (or first participant) + filmstrip
+     */
+    layout?: VideoGridLayout;
+    /**
+     * Participant `id` to spotlight in speaker view.
+     * Falls back to the first participant when omitted.
+     */
+    spotlightId?: string;
+}
+/**
+ * VideoGrid — adaptive participant grid for easyloops meetings.
+ *
+ * Composes `<VideoTile>` tiles in a responsive CSS grid (1→6 columns based on
+ * participant count) or a speaker-view layout (spotlight + filmstrip). The
+ * column math lives in the headless `@refraction-ui/video-grid` core so it is
+ * shared with the Astro adapter.
+ */
+declare const VideoGrid: React.ForwardRefExoticComponent<VideoGridProps & React.RefAttributes<HTMLDivElement>>;
+
+export { VideoGrid, type VideoGridProps };

package/dist/internal/react-video-tile/index.d.ts

@@ -0,0 +1,41 @@
+import * as React from 'react';
+import { VideoTileMicState } from '../video-tile/index.js';
+export { VideoTileData, VideoTileMicState } from '../video-tile/index.js';
+
+interface VideoTileProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'content' | 'color'> {
+    /** Participant display name — shown in the name chip and used for initials. */
+    name: string;
+    /** Current microphone state. Defaults to 'on'. */
+    micState?: VideoTileMicState;
+    /** Whether the participant is actively speaking. Adds an emerald ring. */
+    speaking?: boolean;
+    /** Whether the tile is pinned in the grid. Adds a primary ring. */
+    pinned?: boolean;
+    /** URL of the participant's avatar image, used in the fallback circle. */
+    avatarUrl?: string;
+    /**
+     * Media slot — pass a `<video>` element (or any ReactNode) to render as the
+     * tile's background media layer. When omitted, an avatar fallback is shown.
+     */
+    mediaSlot?: React.ReactNode;
+    /** Optional emoji/reaction badge rendered at the top-right of the tile. */
+    reaction?: React.ReactNode;
+}
+/**
+ * VideoTile — a single participant tile for a video meeting grid.
+ *
+ * Renders a `role="group"` container with an aspect-video aspect ratio.
+ * If a `mediaSlot` is provided it fills the tile; otherwise an avatar fallback
+ * with initials is centred on a muted background.
+ *
+ * Overlays:
+ * - Name chip (bottom-left) with optional mic-muted indicator
+ * - Speaking ring (emerald) when `speaking` is true
+ * - Pinned ring (primary) when `pinned` is true
+ * - Reaction badge (top-right) when `reaction` is provided
+ *
+ * Logic and styles come from the headless `@refraction-ui/video-tile` core.
+ */
+declare const VideoTile: React.ForwardRefExoticComponent<VideoTileProps & React.RefAttributes<HTMLDivElement>>;
+
+export { VideoTile, type VideoTileProps };

package/dist/internal/react-wizard/index.d.ts

@@ -0,0 +1,59 @@
+import * as React from 'react';
+import { WizardStep, WizardOrientation } from '../wizard/index.js';
+export { WizardOrientation, WizardStep } from '../wizard/index.js';
+
+interface WizardContextValue {
+    currentIndex: number;
+    steps: WizardStep[];
+    orientation: WizardOrientation;
+}
+interface WizardProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange' | 'children'> {
+    /** Step definitions for the rail. */
+    steps: WizardStep[];
+    /** Controlled current step index (0-based). */
+    step?: number;
+    /** Initial step index for uncontrolled usage. */
+    defaultStep?: number;
+    /** Called when the current step changes (Back/Next). */
+    onStepChange?: (index: number) => void;
+    /** Called when the user completes the final step. */
+    onComplete?: () => void;
+    /** Orientation of the step rail. Default `'vertical'`. */
+    orientation?: WizardOrientation;
+    /** Label for the Next button. */
+    nextLabel?: React.ReactNode;
+    /** Label for the Back button. */
+    backLabel?: React.ReactNode;
+    /** Label for the button on the final step. */
+    completeLabel?: React.ReactNode;
+    /** Label for the Skip button (shown on optional steps only). */
+    skipLabel?: React.ReactNode;
+    /**
+     * Content for the active step. Either pass a render prop that receives the
+     * current step index, or plain children shown for every step.
+     */
+    children?: React.ReactNode | ((currentIndex: number) => React.ReactNode);
+}
+/**
+ * Wizard — a multi-step flow orchestration component.
+ *
+ * Renders a step rail (vertical by default) alongside the active step content
+ * and a footer with Back / Skip (optional steps) / Next-or-Complete actions.
+ * Supports controlled (`step` / `onStepChange`) and uncontrolled
+ * (`defaultStep`) usage. Logic and styles come from the headless
+ * `@refraction-ui/wizard` core.
+ *
+ * @example
+ * ```tsx
+ * <Wizard steps={steps} onComplete={handleComplete}>
+ *   {(index) => <StepContent stepIndex={index} />}
+ * </Wizard>
+ * ```
+ */
+declare const Wizard: React.ForwardRefExoticComponent<WizardProps & React.RefAttributes<HTMLDivElement>>;
+/**
+ * Access wizard state from within a child component rendered inside `<Wizard>`.
+ */
+declare function useWizard(): WizardContextValue;
+
+export { Wizard, type WizardProps, useWizard };

package/dist/internal/section-head/index.d.ts

@@ -0,0 +1,36 @@
+/** Horizontal alignment of the section head cluster. */
+type SectionHeadAlign = 'center' | 'left';
+interface SectionHeadProps {
+    /** Alignment of the kicker, title, and lede. */
+    align?: SectionHeadAlign;
+}
+interface SectionHeadAPI {
+    /** Data attributes for styling hooks. */
+    dataAttributes: Record<string, string>;
+}
+/**
+ * Build the framework-agnostic data attributes for a SectionHead.
+ *
+ * Returns data-align so adapters can apply styles via CSS or Tailwind
+ * variants. All visual logic (classes, cva) lives in `section-head.styles.ts`.
+ */
+declare function createSectionHead(props?: SectionHeadProps): SectionHeadAPI;
+
+/**
+ * Container variant that controls the alignment of the whole cluster.
+ * Center: auto-margins + text-center + constrained max-width for comfortable
+ * line length. Left: no margin constraint, flush left.
+ */
+declare const sectionHeadVariants: (props?: ({
+    align?: "center" | "left" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+/** Small-caps eyebrow label above the title. */
+declare const sectionHeadKickerClass = "text-[11px] uppercase tracking-widest text-primary font-semibold";
+/** Primary h2 heading. */
+declare const sectionHeadTitleClass = "text-3xl sm:text-4xl font-bold tracking-tight text-foreground";
+/** Optional lede paragraph below the title. */
+declare const sectionHeadLedeClass = "mt-3 text-muted-foreground leading-relaxed";
+
+export { type SectionHeadAPI, type SectionHeadAlign, type SectionHeadProps, createSectionHead, sectionHeadKickerClass, sectionHeadLedeClass, sectionHeadTitleClass, sectionHeadVariants };

package/dist/internal/stat-grid/index.d.ts

@@ -0,0 +1,45 @@
+/** A single stat callout displayed in the grid. */
+type StatItem = {
+    /** The primary value displayed prominently (e.g. "10k+", "$4.2M"). */
+    value: string;
+    /** The descriptive label shown below the value. */
+    label: string;
+};
+interface StatGridAPI {
+    /** ARIA attributes to spread on the grid container element (`role="list"`). */
+    ariaProps: {
+        role: 'list';
+    };
+    /** Data attributes for styling hooks. */
+    dataAttributes: Record<string, string>;
+}
+/**
+ * Compute the number of grid columns for a stat grid.
+ *
+ * - 1 item  → 1 column
+ * - 2 items → 2 columns
+ * - 3 or more items → capped at `max` (default 3)
+ */
+declare function statColumns(count: number, max?: number): number;
+/**
+ * Build the framework-agnostic container props for a stat grid.
+ *
+ * Returns `role="list"` and data attributes; adapters spread these onto their
+ * container element and render the items themselves.
+ */
+declare function createStatGrid(): StatGridAPI;
+
+/** Grid container that lays out stat items. */
+declare const statGridVariants: (props?: ({
+    columns?: "1" | "2" | "3" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+/** Individual stat item container (role="listitem"). */
+declare const statItemClass = "flex flex-col";
+/** The large bold value of the stat. */
+declare const statValueClass = "text-xl sm:text-2xl font-bold text-primary";
+/** The descriptive label below the value. */
+declare const statLabelClass = "mt-1 text-sm text-muted-foreground leading-snug";
+
+export { type StatGridAPI, type StatItem, createStatGrid, statColumns, statGridVariants, statItemClass, statLabelClass, statValueClass };

package/dist/internal/sticky-note/index.d.ts

@@ -0,0 +1,49 @@
+/** The available color variants for a sticky note. */
+type StickyNoteColor = 'yellow' | 'pink' | 'blue' | 'green' | 'purple' | 'orange';
+/** Ordered list of all sticky note colors — used for cycling and iteration. */
+declare const STICKY_NOTE_COLORS: StickyNoteColor[];
+/**
+ * Returns the next color in the cycle. Wraps from the last color back to the
+ * first. Useful for "add note" flows that auto-assign colors in sequence.
+ */
+declare function nextStickyColor(color: StickyNoteColor): StickyNoteColor;
+interface CreateStickyNoteOptions {
+    /** Color of the note. */
+    color: StickyNoteColor;
+}
+interface StickyNoteAPI {
+    /** Data attributes for styling hooks; spread onto the note container. */
+    dataAttributes: {
+        'data-color': StickyNoteColor;
+    };
+    /** ARIA props for the note container. */
+    ariaProps: {
+        role: 'group';
+    };
+}
+/**
+ * Build the framework-agnostic props for a sticky note container.
+ *
+ * Returns `role="group"` plus the `data-color` attribute that adapters use
+ * as a styling hook. Logic is pure and SSR-safe — no Math.random, no Date.
+ */
+declare function createStickyNote(options: CreateStickyNoteOptions): StickyNoteAPI;
+
+/**
+ * Note container with color variant.
+ *
+ * Sticky notes are intrinsically colorful — an approved exception to the
+ * semantic-token-only rule. Each color maps to a soft tint background with a
+ * readable dark text.
+ */
+declare const stickyNoteVariants: (props?: ({
+    color?: "yellow" | "pink" | "blue" | "green" | "purple" | "orange" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+/** Class for the editable/static text area inside the note. */
+declare const stickyNoteTextClass = "flex-1 w-full resize-none bg-transparent text-sm leading-relaxed placeholder:opacity-60 outline-none";
+/** Class for the author chip rendered in the note footer. */
+declare const stickyNoteAuthorClass = "mt-auto text-xs font-medium opacity-70 truncate";
+
+export { type CreateStickyNoteOptions, STICKY_NOTE_COLORS, type StickyNoteAPI, type StickyNoteColor, createStickyNote, nextStickyColor, stickyNoteAuthorClass, stickyNoteTextClass, stickyNoteVariants };

package/dist/internal/terminal/index.d.ts

@@ -0,0 +1,65 @@
+/** The semantic kind of a terminal output line. */
+type TerminalLineKind = 'command' | 'stdout' | 'stderr' | 'info' | 'success';
+/** A single line displayed in the terminal output panel. */
+interface TerminalLine {
+    /** Optional stable key for list rendering. */
+    id?: string;
+    /** Semantic kind — drives styling and screen-reader announcements. */
+    kind: TerminalLineKind;
+    /** Text content of the line. */
+    text: string;
+}
+interface TerminalAPI {
+    /**
+     * ARIA attributes to spread on the terminal container element.
+     * - `role="log"` semantics: assistive technologies announce appended content.
+     * - `aria-live="polite"` so new output does not interrupt the user mid-action.
+     */
+    ariaProps: {
+        role: 'log';
+        'aria-live': 'polite';
+        'aria-label'?: string;
+    };
+    /** Data attributes for styling hooks. */
+    dataAttributes: Record<string, string>;
+}
+/**
+ * Build the prompt string shown before a command line.
+ *
+ * @param promptSymbol - The shell prompt character(s), e.g. `'$'` or `'❯'`.
+ * @param command - The command text that follows the prompt.
+ * @returns The formatted prompt string, e.g. `'$ python solution.py'`.
+ */
+declare function formatPrompt(promptSymbol: string, command: string): string;
+/**
+ * Build the framework-agnostic ARIA and data props for a terminal output panel.
+ *
+ * Returns `role="log"` (live region semantics for streaming output) plus data
+ * attributes; adapters spread these onto their scroll container.
+ */
+declare function createTerminal(options?: {
+    label?: string;
+}): TerminalAPI;
+
+/**
+ * The outer scroll container — a dark monospaced surface that houses all
+ * terminal lines. Uses semantic card tokens so it inherits the active theme.
+ */
+declare const terminalVariants: (props?: ({
+    maxHeight?: "sm" | "md" | "lg" | "none" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+/**
+ * A single terminal line. The `kind` variant maps each semantic category to
+ * the appropriate semantic token class — no raw color values inline.
+ */
+declare const terminalLineVariants: (props?: ({
+    kind?: "command" | "stdout" | "stderr" | "info" | "success" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+/** The prompt symbol (`$`, `❯`, …) preceding a command line. */
+declare const terminalPromptClass = "select-none mr-2 text-muted-foreground";
+
+export { type TerminalAPI, type TerminalLine, type TerminalLineKind, createTerminal, formatPrompt, terminalLineVariants, terminalPromptClass, terminalVariants };

package/dist/internal/test-results/index.d.ts

@@ -0,0 +1,97 @@
+import { AccessibilityProps } from '../shared/index.js';
+
+/** The execution status of a single test case. */
+type TestStatus = 'pass' | 'fail' | 'skip';
+/** Data for a single test case result. */
+interface TestResultData {
+    /** Unique identifier for the test. */
+    id: string;
+    /** Human-readable test name. */
+    name: string;
+    /** Execution status. */
+    status: TestStatus;
+    /** How long the test took to run, in milliseconds. */
+    durationMs?: number;
+    /** Expected value (shown in diff when the test fails). */
+    expected?: string;
+    /** Actual value received (shown in diff when the test fails). */
+    actual?: string;
+    /** Optional message — error message on failure, skip reason, etc. */
+    message?: string;
+}
+/** Aggregate counts derived from a list of test results. */
+interface TestSummary {
+    total: number;
+    passed: number;
+    failed: number;
+    skipped: number;
+    /** True when every test passed (failed === 0 and skipped === 0). */
+    allPassed: boolean;
+}
+interface TestResultsAPI {
+    /** ARIA attributes to spread on the list container (`role="list"`). */
+    ariaProps: Partial<AccessibilityProps>;
+    /** Data attributes for styling hooks. */
+    dataAttributes: Record<string, string>;
+}
+/**
+ * Compute aggregate summary counts from a list of {@link TestResultData}.
+ *
+ * Pure function — no side effects, safe to call during SSR.
+ */
+declare function summarizeTests(results: TestResultData[]): TestSummary;
+/**
+ * Build the framework-agnostic container props for a test results list.
+ *
+ * Returns `role="list"` plus data attributes that adapters spread onto their
+ * container element. The adapter is responsible for rendering individual items
+ * with `role="listitem"`.
+ */
+declare function createTestResults(): TestResultsAPI;
+
+/** Outer container that wraps the summary bar and the test row list. */
+declare const testResultsContainerVariants: (props?: ({} & {
+    className?: string;
+}) | undefined) => string;
+/**
+ * Summary bar ("2 / 3 passed").
+ *
+ * The `outcome` variant maps to a semantic color token so the bar turns green
+ * when everything passes, red when there are failures.
+ */
+declare const testResultsSummaryVariants: (props?: ({
+    outcome?: "pass" | "fail" | "skip" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+/** A single test row in the list. */
+declare const testRowVariants: (props?: ({
+    status?: "pass" | "fail" | "skip" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+/** Status icon / badge inside a test row (the PASS / FAIL / SKIP pill). */
+declare const testStatusBadgeVariants: (props?: ({
+    status?: "pass" | "fail" | "skip" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+/** Test name text inside a row. */
+declare const testNameClass = "font-medium text-foreground";
+/** Duration text ("12 ms") inside a row. */
+declare const testDurationClass = "text-xs text-muted-foreground";
+/**
+ * Expected / actual diff block shown beneath a failing test row.
+ *
+ * The `side` variant sets the left-border accent color to distinguish the two
+ * sides of the diff.
+ */
+declare const testDiffBlockVariants: (props?: ({
+    side?: "expected" | "actual" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+/** Error / skip message text beneath a test row. */
+declare const testMessageClass = "text-xs text-muted-foreground italic";
+
+export { type TestResultData, type TestResultsAPI, type TestStatus, type TestSummary, createTestResults, summarizeTests, testDiffBlockVariants, testDurationClass, testMessageClass, testNameClass, testResultsContainerVariants, testResultsSummaryVariants, testRowVariants, testStatusBadgeVariants };

package/dist/internal/timeline/index.d.ts

@@ -0,0 +1,111 @@
+import { AccessibilityProps } from '../shared/index.js';
+
+/** Layout orientation of the timeline. */
+type TimelineOrientation = 'vertical' | 'horizontal';
+/** Visual status of a single timeline item. */
+type TimelineItemStatus = 'done' | 'current' | 'upcoming' | 'default';
+/** Data describing a single event in the timeline. */
+interface TimelineItemData {
+    /** Unique identifier for the item. */
+    id: string;
+    /** Primary label shown beside the marker. */
+    title: string;
+    /** Optional timestamp / date string shown near the marker. */
+    time?: string;
+    /** Additional detail text rendered below the title. */
+    description?: string;
+    /** Visual status of this item. Defaults to `'default'` when omitted. */
+    status?: TimelineItemStatus;
+}
+interface TimelineProps {
+    /** Ordered list of events to display. */
+    items: TimelineItemData[];
+    /** Layout direction. */
+    orientation?: TimelineOrientation;
+}
+interface TimelineAPI {
+    /** ARIA attributes to spread on the list container (`role="list"`). */
+    ariaProps: Partial<AccessibilityProps>;
+    /** Data attributes for styling hooks. */
+    dataAttributes: Record<string, string>;
+}
+/**
+ * Build the framework-agnostic container props for a timeline.
+ *
+ * Returns `role="list"` (the items carry `role="listitem"`) plus a
+ * `data-orientation` attribute. The function is JSX-free so it can run in
+ * any environment including server-side Node and Astro SSR.
+ */
+declare function createTimeline(props?: Pick<TimelineProps, 'orientation'>): TimelineAPI;
+/**
+ * Accessibility props for a single timeline item.
+ *
+ * Every item gets `role="listitem"` regardless of status so screen readers
+ * announce the full list correctly.
+ */
+declare function getTimelineItemAria(): Partial<AccessibilityProps>;
+/**
+ * Normalise a raw list of timeline items so every entry has an explicit
+ * `status`. Items without a status receive `'default'`.
+ *
+ * This is the single source of truth shared by every adapter — call it once
+ * at render time and iterate over the result.
+ */
+declare function resolveTimelineItems(items: TimelineItemData[]): Required<TimelineItemData>[];
+
+/**
+ * Outer rail / list container.
+ *
+ * Vertical: a single column; horizontal: a row so items sit side-by-side.
+ */
+declare const timelineVariants: (props?: ({
+    orientation?: "vertical" | "horizontal" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+/**
+ * A single event row / column.
+ *
+ * In vertical mode items stack with a left gutter for the marker + connector.
+ * In horizontal mode each item takes equal width and the connector runs above.
+ */
+declare const timelineItemVariants: (props?: ({
+    orientation?: "vertical" | "horizontal" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+/**
+ * The marker / dot that represents the event on the rail.
+ *
+ * Status variants map directly to semantic token colours so theming is
+ * handled at the design-token level, not inline.
+ */
+declare const timelineMarkerVariants: (props?: ({
+    status?: "done" | "current" | "upcoming" | "default" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+/**
+ * The connector line drawn between adjacent markers.
+ *
+ * Vertical: a thin vertical stripe anchored to the left gutter.
+ * Horizontal: a thin horizontal stripe anchored above the content row.
+ * The last item hides its connector so the rail terminates cleanly.
+ */
+declare const timelineConnectorVariants: (props?: ({
+    orientation?: "vertical" | "horizontal" | undefined;
+} & {
+    className?: string;
+}) | undefined) => string;
+/** Wrapper that holds the marker + connector in the gutter column/row. */
+declare const timelineGutterClass = "relative flex flex-col items-center";
+/** Time / date label rendered near the marker. */
+declare const timelineTimeClass = "text-xs text-muted-foreground tabular-nums";
+/** Primary event title. */
+declare const timelineTitleClass = "text-sm font-medium text-foreground leading-snug";
+/** Secondary description text. */
+declare const timelineDescriptionClass = "mt-0.5 text-xs text-muted-foreground leading-relaxed";
+/** Content block (title + description) next to or below the marker. */
+declare const timelineContentClass = "flex flex-col min-w-0";
+
+export { type TimelineAPI, type TimelineItemData, type TimelineItemStatus, type TimelineOrientation, type TimelineProps, createTimeline, getTimelineItemAria, resolveTimelineItems, timelineConnectorVariants, timelineContentClass, timelineDescriptionClass, timelineGutterClass, timelineItemVariants, timelineMarkerVariants, timelineTimeClass, timelineTitleClass, timelineVariants };