@cueplusplus/ui 0.13.0

package/dist/layout/resizable.js

@@ -0,0 +1,68 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import * as React from "react";
+import { jsx, jsxs } from "react/jsx-runtime";
+import { Group, Panel, Separator } from "react-resizable-panels";
+//#region src/layout/resizable.tsx
+/**
+* The group's axis, published to the handles.
+*
+* `react-resizable-panels` keeps its orientation in an internal context and
+* stamps no attribute for it, so a `Resizable.Handle` cannot tell from the DOM
+* whether it should be 4px wide or 4px tall. This is that one missing bit.
+*/
+const ResizableOrientationContext = React.createContext("horizontal");
+/**
+* Split panes the user can drag, on `react-resizable-panels`.
+*
+* `react-resizable-panels` is an **optional peer**: import this from
+* `@cueplusplus/ui/layout/resizable`, never from the core barrel, so an app
+* with no split view never installs one.
+*
+* @example
+* <Resizable.Group orientation="horizontal">
+*   <Resizable.Panel id="tree" defaultSize={25} minSize={15}>…</Resizable.Panel>
+*   <Resizable.Handle withGrip />
+*   <Resizable.Panel id="editor">…</Resizable.Panel>
+* </Resizable.Group>
+*/
+const Resizable = {
+	Group: React.forwardRef(function ResizableGroup({ className, orientation = "horizontal", elementRef, children, ...elementProps }, ref) {
+		return /* @__PURE__ */ jsx(ResizableOrientationContext.Provider, {
+			value: orientation,
+			children: /* @__PURE__ */ jsx(Group, {
+				elementRef: elementRef ?? ref,
+				orientation,
+				"data-slot": "resizable-group",
+				"data-orientation": orientation,
+				className: cn("min-h-0 min-w-0", className),
+				...elementProps,
+				children
+			})
+		});
+	}),
+	Panel: React.forwardRef(function ResizablePanel({ className, elementRef, ...elementProps }, ref) {
+		return /* @__PURE__ */ jsx(Panel, {
+			elementRef: elementRef ?? ref,
+			"data-slot": "resizable-panel",
+			className: cn("min-h-0 min-w-0", className),
+			...elementProps
+		});
+	}),
+	Handle: React.forwardRef(function ResizableHandle({ className, withGrip = false, elementRef, children, ...elementProps }, ref) {
+		const orientation = React.useContext(ResizableOrientationContext);
+		return /* @__PURE__ */ jsxs(Separator, {
+			elementRef: elementRef ?? ref,
+			"data-slot": "resizable-handle",
+			className: cn("relative flex items-center justify-center bg-border transition-colors duration-150 outline-none data-[separator=hover]:bg-accent data-[separator=active]:bg-accent data-[separator=focus]:bg-accent focus-visible:outline-2 focus-visible:outline-solid focus-visible:-outline-offset-2 focus-visible:outline-accent data-[separator=disabled]:opacity-40 motion-reduce:transition-none", orientation === "vertical" ? "h-[0.25rem] w-full" : "w-[0.25rem] self-stretch", className),
+			...elementProps,
+			children: [withGrip ? /* @__PURE__ */ jsx("span", {
+				"data-slot": "resizable-grip",
+				"aria-hidden": "true",
+				className: cn("pointer-events-none rounded-full bg-border-strong", orientation === "vertical" ? "h-px w-(--cue-space-6)" : "h-(--cue-space-6) w-px")
+			}) : null, children]
+		});
+	})
+};
+//#endregion
+export { Resizable };

package/dist/layout/sidebar.d.ts

@@ -0,0 +1,105 @@
+import * as React from "react";
+import { useRender } from "@base-ui/react/use-render";
+//#region src/layout/sidebar.d.ts
+interface SidebarContextValue {
+  collapsed: boolean;
+  toggle: () => void;
+}
+/**
+ * Read the collapse state of the nearest {@link SidebarRoot}.
+ *
+ * Hands back `{ collapsed, toggle }`: whether the column is at its narrow
+ * width, and the same valve `Sidebar.Rail` pulls. It is for the part the kit
+ * does not ship — a footer that drops its labels when the column narrows, a
+ * keyboard shortcut, a collapse control somewhere other than the rail.
+ *
+ * Outside a `Sidebar.Root` it reports `collapsed: false` and a `toggle` that
+ * does nothing, rather than throwing. A row rendered on its own — in a test, on
+ * a docs page, in a menu that reuses the same markup — is a legitimate thing,
+ * and the honest answer for it is that nothing is collapsed.
+ *
+ * @example
+ * const { collapsed } = useSidebar();
+ * <Button variant="ghost" icon={Plus} aria-label="New scene">
+ *   {collapsed ? null : "New scene"}
+ * </Button>
+ */
+declare function useSidebar(): SidebarContextValue;
+/**
+ * Which landmark a navigation column announces as.
+ *
+ * `"navigation"` renders `<nav>`, `"complementary"` renders `<aside>`. Two
+ * values rather than a free `role`, because those are the only two a column of
+ * destinations can honestly be — and naming the landmark keeps the element and
+ * the role from ever disagreeing.
+ */
+type SidebarLandmark = "navigation" | "complementary";
+interface SidebarRootProps extends React.ComponentPropsWithoutRef<"aside"> {
+  /**
+   * Which landmark the column is. Defaults to `"navigation"`, rendering
+   * `<nav>`; `"complementary"` renders `<aside>` instead.
+   *
+   * A column of `Sidebar.Item`s is a list of destinations, one of which carries
+   * `aria-current="page"` — that is primary navigation, and announcing it as
+   * complementary tells a screen-reader user the site's main map is an aside.
+   * `"complementary"` is there for the column that genuinely is one: a filter
+   * rail, an inspector, a related-links strip.
+   */
+  landmark?: SidebarLandmark;
+  /** Collapsed state when controlled. Pass with `onCollapsedChange`. */
+  collapsed?: boolean;
+  /** Initial collapsed state when uncontrolled. Defaults to `false`. */
+  defaultCollapsed?: boolean;
+  /** Called with the new collapsed state whenever the rail is pressed. */
+  onCollapsedChange?: (collapsed: boolean) => void;
+  /** Width while expanded. Any CSS length. Defaults to `"14rem"`. */
+  width?: string;
+  /** Width while collapsed. Any CSS length. Defaults to `"3rem"`. */
+  collapsedWidth?: string;
+}
+interface SidebarSectionProps extends React.ComponentPropsWithoutRef<"div"> {
+  /**
+   * The group caption, in the mono micro idiom. Dropped entirely while the
+   * sidebar is collapsed — at rail width a caption has nothing left to caption.
+   */
+  label?: React.ReactNode;
+}
+interface SidebarItemProps extends React.ComponentPropsWithoutRef<"button"> {
+  /** Optional leading icon component (e.g. a lucide icon), drawn `aria-hidden`. */
+  icon?: React.ElementType;
+  /** Mark this item as the current destination. */
+  active?: boolean;
+  /** Trailing slot: a count, a status dot. Hidden while collapsed. */
+  badge?: React.ReactNode;
+  /**
+   * Replace the rendered element (Base UI render prop) — normally a router
+   * link: `render={<NextLink href="/patch" />}`.
+   */
+  render?: useRender.RenderProp;
+}
+interface SidebarRailProps extends Omit<React.ComponentPropsWithoutRef<"button">, "children"> {
+  /** Accessible name while expanded. Defaults to `"Collapse sidebar"`. */
+  collapseLabel?: string;
+  /** Accessible name while collapsed. Defaults to `"Expand sidebar"`. */
+  expandLabel?: string;
+}
+/**
+ * The console's navigation column: sections of items, a scroller of its own,
+ * and a rail that collapses the whole thing to icons.
+ *
+ * @example
+ * <Sidebar.Root defaultCollapsed aria-label="Main">
+ *   <Sidebar.Section label="Console">
+ *     <Sidebar.Item render={<NextLink href="/patch" />} active>Patch</Sidebar.Item>
+ *   </Sidebar.Section>
+ *   <Sidebar.Rail />
+ * </Sidebar.Root>
+ */
+declare const Sidebar: {
+  Root: React.ForwardRefExoticComponent<SidebarRootProps & React.RefAttributes<HTMLElement>>;
+  Section: React.ForwardRefExoticComponent<SidebarSectionProps & React.RefAttributes<HTMLDivElement>>;
+  Item: React.ForwardRefExoticComponent<SidebarItemProps & React.RefAttributes<HTMLButtonElement>>;
+  Rail: React.ForwardRefExoticComponent<SidebarRailProps & React.RefAttributes<HTMLButtonElement>>;
+};
+//#endregion
+export { Sidebar, SidebarItemProps, SidebarLandmark, SidebarRailProps, SidebarRootProps, SidebarSectionProps, useSidebar };

package/dist/layout/sidebar.js

@@ -0,0 +1,158 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import * as React from "react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { useRender } from "@base-ui/react/use-render";
+//#region src/layout/sidebar.tsx
+/**
+* Collapse state, published to the parts.
+*
+* A `Sidebar.Item` two levels down has to know whether to show its label, and a
+* `Sidebar.Rail` has to know which way it toggles. Context rather than props so
+* a call site can nest sections and items freely without threading a boolean.
+*/
+const SidebarContext = React.createContext({
+	collapsed: false,
+	toggle: () => {}
+});
+/**
+* Read the collapse state of the nearest {@link SidebarRoot}.
+*
+* Hands back `{ collapsed, toggle }`: whether the column is at its narrow
+* width, and the same valve `Sidebar.Rail` pulls. It is for the part the kit
+* does not ship — a footer that drops its labels when the column narrows, a
+* keyboard shortcut, a collapse control somewhere other than the rail.
+*
+* Outside a `Sidebar.Root` it reports `collapsed: false` and a `toggle` that
+* does nothing, rather than throwing. A row rendered on its own — in a test, on
+* a docs page, in a menu that reuses the same markup — is a legitimate thing,
+* and the honest answer for it is that nothing is collapsed.
+*
+* @example
+* const { collapsed } = useSidebar();
+* <Button variant="ghost" icon={Plus} aria-label="New scene">
+*   {collapsed ? null : "New scene"}
+* </Button>
+*/
+function useSidebar() {
+	return React.useContext(SidebarContext);
+}
+/** The element each landmark is spelled with. */
+const LANDMARK_ELEMENTS = {
+	navigation: "nav",
+	complementary: "aside"
+};
+/**
+* The console's navigation column: sections of items, a scroller of its own,
+* and a rail that collapses the whole thing to icons.
+*
+* @example
+* <Sidebar.Root defaultCollapsed aria-label="Main">
+*   <Sidebar.Section label="Console">
+*     <Sidebar.Item render={<NextLink href="/patch" />} active>Patch</Sidebar.Item>
+*   </Sidebar.Section>
+*   <Sidebar.Rail />
+* </Sidebar.Root>
+*/
+const Sidebar = {
+	Root: React.forwardRef(function SidebarRoot({ className, landmark = "navigation", collapsed: collapsedProp, defaultCollapsed = false, onCollapsedChange, width = "14rem", collapsedWidth = "3rem", style, children, ...elementProps }, ref) {
+		const Element = LANDMARK_ELEMENTS[landmark];
+		const [uncontrolled, setUncontrolled] = React.useState(defaultCollapsed);
+		const collapsed = collapsedProp ?? uncontrolled;
+		const toggle = React.useCallback(() => {
+			const next = !(collapsedProp ?? uncontrolled);
+			if (collapsedProp === void 0) setUncontrolled(next);
+			onCollapsedChange?.(next);
+		}, [
+			collapsedProp,
+			uncontrolled,
+			onCollapsedChange
+		]);
+		const context = React.useMemo(() => ({
+			collapsed,
+			toggle
+		}), [collapsed, toggle]);
+		return /* @__PURE__ */ jsx(SidebarContext.Provider, {
+			value: context,
+			children: /* @__PURE__ */ jsx(Element, {
+				ref,
+				"data-slot": "sidebar",
+				"data-collapsed": collapsed ? "" : void 0,
+				className: cn("group/sidebar relative flex h-full min-h-0 shrink-0 flex-col border-r border-border bg-surface-1 transition-[width] duration-150 ease-out motion-reduce:transition-none", className),
+				style: {
+					width: collapsed ? collapsedWidth : width,
+					...style
+				},
+				...elementProps,
+				children: /* @__PURE__ */ jsx("div", {
+					"data-slot": "sidebar-scroller",
+					className: "flex min-h-0 flex-1 flex-col gap-(--cue-space-4) overflow-y-auto py-(--cue-space-4)",
+					children
+				})
+			})
+		});
+	}),
+	Section: React.forwardRef(function SidebarSection({ className, label, children, ...elementProps }, ref) {
+		const { collapsed } = useSidebar();
+		return /* @__PURE__ */ jsxs("div", {
+			ref,
+			"data-slot": "sidebar-section",
+			className: cn("flex flex-col gap-(--cue-space-1) px-(--cue-space-2)", className),
+			...elementProps,
+			children: [label === void 0 || collapsed ? null : /* @__PURE__ */ jsx("div", {
+				"data-slot": "sidebar-section-label",
+				className: "flex h-control-sm items-center px-(--cue-space-2) font-mono text-(length:--cue-text-label) tracking-[0.15em] text-fg-subtle uppercase",
+				children: label
+			}), children]
+		});
+	}),
+	Item: React.forwardRef(function SidebarItem({ className, icon: Icon, active = false, badge, render, type, children, ...elementProps }, ref) {
+		return useRender({
+			render,
+			ref,
+			defaultTagName: "button",
+			props: {
+				...render === void 0 ? { type: type ?? "button" } : type === void 0 ? {} : { type },
+				...elementProps,
+				"data-slot": "sidebar-item",
+				"data-active": active ? "" : void 0,
+				"aria-current": active ? "page" : void 0,
+				className: cn("relative flex h-control-md w-full cursor-pointer items-center gap-(--cue-space-3) rounded-(--radius-control) border-0 bg-transparent px-(--cue-space-3) text-left font-mono text-(length:--cue-text-ui) text-fg-muted no-underline transition-colors duration-150 outline-none select-none hover:bg-surface-2 hover:text-fg focus-visible:outline-2 focus-visible:outline-solid focus-visible:-outline-offset-1 focus-visible:outline-accent data-[active]:bg-accent-soft data-[active]:text-accent disabled:pointer-events-none disabled:opacity-40", className),
+				children: /* @__PURE__ */ jsxs(Fragment, { children: [
+					Icon === void 0 ? null : /* @__PURE__ */ jsx(Icon, {
+						"aria-hidden": "true",
+						className: "size-icon-md shrink-0"
+					}),
+					/* @__PURE__ */ jsx("span", {
+						"data-slot": "sidebar-item-label",
+						className: "min-w-0 flex-1 truncate group-data-[collapsed]/sidebar:sr-only",
+						children
+					}),
+					badge === void 0 ? null : /* @__PURE__ */ jsx("span", {
+						"data-slot": "sidebar-item-badge",
+						className: "shrink-0 group-data-[collapsed]/sidebar:hidden",
+						children: badge
+					})
+				] })
+			}
+		});
+	}),
+	Rail: React.forwardRef(function SidebarRail({ className, collapseLabel = "Collapse sidebar", expandLabel = "Expand sidebar", onClick, ...elementProps }, ref) {
+		const { collapsed, toggle } = useSidebar();
+		return /* @__PURE__ */ jsx("button", {
+			ref,
+			type: "button",
+			"data-slot": "sidebar-rail",
+			"aria-label": collapsed ? expandLabel : collapseLabel,
+			"aria-expanded": !collapsed,
+			onClick: (event) => {
+				onClick?.(event);
+				if (!event.defaultPrevented) toggle();
+			},
+			className: cn("absolute inset-y-0 right-0 w-[0.25rem] translate-x-1/2 cursor-ew-resize border-0 bg-transparent p-0 transition-colors duration-150 outline-none hover:bg-accent focus-visible:outline-2 focus-visible:outline-solid focus-visible:-outline-offset-2 focus-visible:outline-accent motion-reduce:transition-none", className),
+			...elementProps
+		});
+	})
+};
+//#endregion
+export { Sidebar, useSidebar };

package/dist/layout/stack.d.ts

@@ -0,0 +1,46 @@
+import * as React from "react";
+//#region src/layout/stack.d.ts
+/**
+ * A rung of the density space ladder, or `0` for no gap at all.
+ *
+ * The prop is a number rather than a class string so a layout can never spend a
+ * gap this system does not own: there is no `gap-[13px]` to reach for.
+ */
+type SpaceStep = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
+/** Cross-axis alignment. */
+type StackAlign = "start" | "center" | "end" | "stretch" | "baseline";
+/** Main-axis distribution. */
+type StackJustify = "start" | "center" | "end" | "between";
+interface StackProps extends React.ComponentPropsWithoutRef<"div"> {
+  /** `"column"` (default) or `"row"`. */
+  direction?: "row" | "column";
+  /** Which rung of the density space ladder to spend between children. Defaults to `4`. */
+  gap?: SpaceStep;
+  /** Cross-axis alignment. Omit to inherit the flex default (`stretch`). */
+  align?: StackAlign;
+  /** Main-axis distribution. Omit to inherit the flex default (`start`). */
+  justify?: StackJustify;
+  /** Let a row wrap onto more lines. */
+  wrap?: boolean;
+  /** Lay out as `inline-flex`, so the stack sits in a line of text. */
+  inline?: boolean;
+}
+/**
+ * One-dimensional layout: the flex row or column, with the gap tokenised.
+ *
+ * Exists so that spacing between siblings is a density decision rather than a
+ * per-call-site guess. A `Stack gap={4}` is 8px at normal density and 6px at
+ * ultra-compact without touching the markup, which is the whole point of the
+ * density system — and something `flex gap-2` written by hand quietly opts out
+ * of.
+ *
+ * Static markup — no `"use client"`.
+ *
+ * @example
+ * <Stack gap={5}><Panel /><Panel /></Stack>
+ * @example
+ * <Stack direction="row" gap={2} align="center"><StatusDot tone="ok" />Online</Stack>
+ */
+declare const Stack: React.ForwardRefExoticComponent<StackProps & React.RefAttributes<HTMLDivElement>>;
+//#endregion
+export { SpaceStep, Stack, StackAlign, StackJustify, StackProps };

package/dist/layout/stack.js

@@ -0,0 +1,62 @@
+import { cn } from "../lib/cn.js";
+import * as React from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/layout/stack.tsx
+/**
+* Static class per rung — Tailwind scans source text, so a computed
+* `gap-(--cue-space-${n})` would never be generated.
+*
+* @internal Shared with `grid.tsx`.
+*/
+const GAP_CLASSES = {
+	0: "",
+	1: "gap-(--cue-space-1)",
+	2: "gap-(--cue-space-2)",
+	3: "gap-(--cue-space-3)",
+	4: "gap-(--cue-space-4)",
+	5: "gap-(--cue-space-5)",
+	6: "gap-(--cue-space-6)",
+	7: "gap-(--cue-space-7)",
+	8: "gap-(--cue-space-8)"
+};
+/** @internal Shared with `grid.tsx`. */
+const ALIGN_CLASSES = {
+	start: "items-start",
+	center: "items-center",
+	end: "items-end",
+	stretch: "items-stretch",
+	baseline: "items-baseline"
+};
+/** @internal Shared with `grid.tsx`. */
+const JUSTIFY_CLASSES = {
+	start: "justify-start",
+	center: "justify-center",
+	end: "justify-end",
+	between: "justify-between"
+};
+/**
+* One-dimensional layout: the flex row or column, with the gap tokenised.
+*
+* Exists so that spacing between siblings is a density decision rather than a
+* per-call-site guess. A `Stack gap={4}` is 8px at normal density and 6px at
+* ultra-compact without touching the markup, which is the whole point of the
+* density system — and something `flex gap-2` written by hand quietly opts out
+* of.
+*
+* Static markup — no `"use client"`.
+*
+* @example
+* <Stack gap={5}><Panel /><Panel /></Stack>
+* @example
+* <Stack direction="row" gap={2} align="center"><StatusDot tone="ok" />Online</Stack>
+*/
+const Stack = React.forwardRef(function Stack({ className, direction = "column", gap = 4, align, justify, wrap = false, inline = false, ...elementProps }, ref) {
+	return /* @__PURE__ */ jsx("div", {
+		ref,
+		"data-slot": "stack",
+		className: cn(inline ? "inline-flex" : "flex", direction === "row" ? "flex-row" : "flex-col", GAP_CLASSES[gap], align === void 0 ? null : ALIGN_CLASSES[align], justify === void 0 ? null : JUSTIFY_CLASSES[justify], wrap ? "flex-wrap" : null, className),
+		...elementProps
+	});
+});
+//#endregion
+export { ALIGN_CLASSES, GAP_CLASSES, JUSTIFY_CLASSES, Stack };

package/dist/layout/stepper.d.ts

@@ -0,0 +1,49 @@
+import * as React from "react";
+//#region src/layout/stepper.d.ts
+/** One step of a {@link Stepper}. */
+interface StepperStep {
+  /** Stable identity, matched against `current`. */
+  id: string;
+  /** What the step says. Keep it to one or two words — this is a trail, not a list. */
+  label: React.ReactNode;
+}
+/** Where a step sits relative to the current one. */
+type StepperState = "complete" | "current" | "upcoming";
+interface StepperProps extends Omit<React.ComponentPropsWithoutRef<"nav">, "children" | "onChange"> {
+  /** The steps, in order. */
+  steps: readonly StepperStep[];
+  /** The `id` of the step in progress. An unknown id leaves every step upcoming. */
+  current: string;
+  /**
+   * Called with the `id` of a step the user asked to go back to. Passing it
+   * turns the finished steps into buttons; leaving it off keeps the trail
+   * static, which is the honest rendering when the earlier steps cannot be
+   * revisited.
+   */
+  onStepChange?: (id: string) => void;
+  /** What sits between steps. Defaults to `"·"`. */
+  separator?: React.ReactNode;
+  /** The nav's accessible name. Defaults to `"Progress"`. */
+  label?: string;
+}
+/**
+ * The step trail: `1 target · 2 preview · 3 apply`.
+ *
+ * Deliberately a line of mono text rather than the usual row of numbered discs
+ * joined by rules. A stepper drawn as circles-and-lines is 60px tall and says
+ * exactly as much as one line of 9px type — and in a console that vertical
+ * space belongs to the thing being configured, not to the wizard chrome around
+ * it. Only the numbers carry the accent, so the trail reads as one sentence
+ * with the position marked, which is what a progress indicator is for.
+ *
+ * Forward steps are never buttons: a step you have not reached is not a place
+ * you can go, and offering it as a control is a promise the flow cannot keep.
+ *
+ * @example
+ * <Stepper steps={[{ id: "target", label: "target" }, { id: "preview", label: "preview" }]} current="preview" />
+ * @example
+ * <Stepper steps={steps} current={step} onStepChange={setStep} />
+ */
+declare const Stepper: React.ForwardRefExoticComponent<StepperProps & React.RefAttributes<HTMLElement>>;
+//#endregion
+export { Stepper, StepperProps, StepperState, StepperStep };

package/dist/layout/stepper.js

@@ -0,0 +1,81 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import * as React from "react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+//#region src/layout/stepper.tsx
+/** Ink per state: done recedes, now is full strength, later is barely there. */
+const STEP_TONES = {
+	complete: "text-fg-muted",
+	current: "text-fg",
+	upcoming: "text-fg-subtle"
+};
+/** The number carries the accent for everything you have reached. */
+const INDEX_TONES = {
+	complete: "text-accent",
+	current: "text-accent",
+	upcoming: "text-fg-subtle"
+};
+const STEP_BUTTON_CLASSES = "inline-flex cursor-pointer items-center gap-(--cue-space-2) rounded-(--radius-control) border-0 bg-transparent p-0 font-mono text-[length:inherit] tracking-[inherit] text-inherit uppercase transition-colors duration-150 outline-none hover:text-fg focus-visible:outline-2 focus-visible:outline-solid focus-visible:outline-offset-2 focus-visible:outline-accent";
+/**
+* The step trail: `1 target · 2 preview · 3 apply`.
+*
+* Deliberately a line of mono text rather than the usual row of numbered discs
+* joined by rules. A stepper drawn as circles-and-lines is 60px tall and says
+* exactly as much as one line of 9px type — and in a console that vertical
+* space belongs to the thing being configured, not to the wizard chrome around
+* it. Only the numbers carry the accent, so the trail reads as one sentence
+* with the position marked, which is what a progress indicator is for.
+*
+* Forward steps are never buttons: a step you have not reached is not a place
+* you can go, and offering it as a control is a promise the flow cannot keep.
+*
+* @example
+* <Stepper steps={[{ id: "target", label: "target" }, { id: "preview", label: "preview" }]} current="preview" />
+* @example
+* <Stepper steps={steps} current={step} onStepChange={setStep} />
+*/
+const Stepper = React.forwardRef(function Stepper({ className, steps, current, onStepChange, separator = "·", label = "Progress", ...elementProps }, ref) {
+	const currentIndex = steps.findIndex((step) => step.id === current);
+	return /* @__PURE__ */ jsx("nav", {
+		ref,
+		"data-slot": "stepper",
+		"aria-label": label,
+		className: cn("min-w-0", className),
+		...elementProps,
+		children: /* @__PURE__ */ jsx("ol", {
+			className: "m-0 flex list-none flex-wrap items-center gap-(--cue-space-3) p-0 font-mono text-(length:--cue-text-label) tracking-[0.1em] uppercase",
+			children: steps.map((step, index) => {
+				const state = currentIndex === -1 || index > currentIndex ? "upcoming" : index === currentIndex ? "current" : "complete";
+				const navigable = onStepChange !== void 0 && state === "complete";
+				const body = /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx("span", {
+					"data-slot": "stepper-index",
+					className: cn("tabular-nums", INDEX_TONES[state]),
+					children: index + 1
+				}), /* @__PURE__ */ jsx("span", {
+					"data-slot": "stepper-label",
+					className: "truncate",
+					children: step.label
+				})] });
+				return /* @__PURE__ */ jsxs(React.Fragment, { children: [index === 0 ? null : /* @__PURE__ */ jsx("li", {
+					"data-slot": "stepper-separator",
+					"aria-hidden": "true",
+					className: "text-fg-subtle select-none",
+					children: separator
+				}), /* @__PURE__ */ jsx("li", {
+					"data-slot": "stepper-step",
+					"data-state": state,
+					"aria-current": state === "current" ? "step" : void 0,
+					className: cn("inline-flex min-w-0 items-center gap-(--cue-space-2)", STEP_TONES[state]),
+					children: navigable ? /* @__PURE__ */ jsx("button", {
+						type: "button",
+						onClick: () => onStepChange(step.id),
+						className: STEP_BUTTON_CLASSES,
+						children: body
+					}) : body
+				})] }, step.id);
+			})
+		})
+	});
+});
+//#endregion
+export { Stepper };

package/dist/layout/timeline.d.ts

@@ -0,0 +1,43 @@
+import { StatusTone } from "../primitives/status-dot.js";
+import * as React from "react";
+//#region src/layout/timeline.d.ts
+/** Props for {@link TimelineRoot}: the native `<ol>` surface plus `className`. */
+type TimelineRootProps = React.ComponentPropsWithoutRef<"ol">;
+/** Props for {@link TimelineItem}: the native `<li>` surface plus `className`. */
+type TimelineItemProps = React.ComponentPropsWithoutRef<"li">;
+interface TimelineMarkerProps extends Omit<React.ComponentPropsWithoutRef<"span">, "children"> {
+  /** Which state this event is in. The shared `StatusDot` vocabulary. */
+  tone: StatusTone;
+  /** Screen-reader text for the dot. Defaults to the tone name. */
+  label?: string;
+  /** Pulse the dot for an event still in progress. */
+  pulse?: boolean;
+}
+/** Props for {@link TimelineContent}: the native `<div>` surface plus `className`. */
+type TimelineContentProps = React.ComponentPropsWithoutRef<"div">;
+/**
+ * A vertical run of events on one rail: a run log, a cue history, a deploy
+ * trail.
+ *
+ * Static markup — no `"use client"`.
+ *
+ * @example
+ * <Timeline.Root>
+ *   <Timeline.Item>
+ *     <Timeline.Marker tone="ok" label="Patched" />
+ *     <Timeline.Content>Patched universe 1</Timeline.Content>
+ *   </Timeline.Item>
+ *   <Timeline.Item>
+ *     <Timeline.Marker tone="busy" label="Focusing" pulse />
+ *     <Timeline.Content>Focusing front truss</Timeline.Content>
+ *   </Timeline.Item>
+ * </Timeline.Root>
+ */
+declare const Timeline: {
+  Root: React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.OlHTMLAttributes<HTMLOListElement>, HTMLOListElement>, "ref"> & React.RefAttributes<HTMLOListElement>>;
+  Item: React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.LiHTMLAttributes<HTMLLIElement>, HTMLLIElement>, "ref"> & React.RefAttributes<HTMLLIElement>>;
+  Marker: React.ForwardRefExoticComponent<TimelineMarkerProps & React.RefAttributes<HTMLSpanElement>>;
+  Content: React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
+};
+//#endregion
+export { Timeline, TimelineContentProps, TimelineItemProps, TimelineMarkerProps, TimelineRootProps };