@stll/ui 0.65.0 → 0.66.0

package/dist/calendar/day-calendar.d.ts

@@ -1,11 +1,17 @@
 import { DayCalendarGranularity, DayCalendarRange } from "./day-calendar.logic.js";
 import { ReactElement, ReactNode } from "react";
-//#region src/calendar/day-calendar.d.ts
-/** A block paints in its matter's colour, or in the neutral surface tone. */
+/**
+ * A block paints in its matter's colour; in a topic's colour, a lighter tint
+ * from the same palette keyed by a stable topic key and without the matter's
+ * edge; or in the neutral surface tone.
+ */
 export type DayCalendarTone = {
   color: string | null;
   matterId: string;
   type: "matter";
+} | {
+  key: string;
+  type: "topic";
 } | {
   type: "neutral";
 };
@@ -91,5 +97,4 @@ type DayCalendarProps = {
   timeZone: string;
 };
 export declare const DayCalendar: ({ ariaLabel, columns, date, granularity, hours, locale, nowMs, onSelectRange, selection, timeZone }: DayCalendarProps) => ReactElement;
-//#endregion
 export {};

package/dist/calendar/day-calendar.js

@@ -1,12 +1,12 @@
 import { cn } from "../lib/utils.js";
 import { Tooltip, TooltipContent as TooltipPopup, TooltipTrigger } from "../components/tooltip.js";
 import { DAY_CALENDAR_SLOT_HEIGHT_PX, boundsHeight, extendRange, getDayBounds, getHourTicks, isRepeatedWallTime, layoutOverlaps, moveRange, offsetToTime, rangeFromDrag, slotAt, timeToOffset } from "./day-calendar.logic.js";
-import { resolveMatterColor } from "../lib/matter-colors.js";
+import { getMatterColor, resolveMatterColor } from "../lib/matter-colors.js";
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { useState } from "react";
 import { panic } from "better-result";
 import { Temporal } from "temporal-polyfill/full";
-//#region src/calendar/day-calendar.tsx
+// src/calendar/day-calendar.tsx
 const isSameDraftView = (left, right) => left.date === right.date && left.endHour === right.endHour && left.granularity === right.granularity && left.startHour === right.startHour && left.timeZone === right.timeZone;
 /**
 * A draft's range belongs to the day and grid it was made on; once they
@@ -367,27 +367,25 @@ const DayCalendarBlockView = ({ block, grid, lane, range }) => {
 		})] })
 	});
 };
-const MIXED_STRIPES = "repeating-linear-gradient(135deg, var(--muted) 0 6px, transparent 6px 12px)";
 /** A suggestion's tint is half an entry's, so proposed time reads lighter. */
 const TONE_TINT_PERCENT = {
 	entry: 16,
 	suggestion: 8
 };
+/** A topic is not a matter yet: its tint sits between a suggestion's and an
+* entry's. */
+const TOPIC_TINT_PERCENT = 12;
 function blockSurfaceStyle(block) {
 	const tone = block.tone;
-	const stripes = block.kind === "mixed" ? MIXED_STRIPES : void 0;
 	const suggestion = block.kind === "entry" && block.state === "suggestion";
 	switch (tone.type) {
-		case "neutral": return {
-			backgroundColor: suggestion ? "transparent" : void 0,
-			backgroundImage: stripes
-		};
+		case "neutral": return { backgroundColor: suggestion ? "transparent" : void 0 };
+		case "topic": return { backgroundColor: `color-mix(in srgb, ${getMatterColor(tone.key)} ${String(TOPIC_TINT_PERCENT)}%, var(--card))` };
 		case "matter": {
 			const color = resolveMatterColor(tone.matterId, tone.color);
 			const tint = suggestion ? TONE_TINT_PERCENT.suggestion : TONE_TINT_PERCENT.entry;
 			return {
 				backgroundColor: `color-mix(in srgb, ${color} ${String(tint)}%, var(--card))`,
-				backgroundImage: stripes,
 				borderColor: suggestion ? color : void 0,
 				borderInlineStartColor: color
 			};
@@ -493,5 +491,4 @@ const LockedColumnBody = ({ action }) => /* @__PURE__ */ jsxs("div", {
 function assertDayCalendarContract(columns) {
 	if (new Set(columns.map(({ id }) => id)).size !== columns.length) panic("Day calendar column ids must be unique");
 }
-//#endregion
 export { DayCalendar };

package/dist/calendar/day-calendar.logic.d.ts

@@ -1,4 +1,3 @@
-//#region src/calendar/day-calendar.logic.d.ts
 export declare const DAY_CALENDAR_GRANULARITIES: readonly [15, 30, 60];
 export type DayCalendarGranularity = (typeof DAY_CALENDAR_GRANULARITIES)[number];
 /** Below this height a block cannot hold one line of its label, so it draws
@@ -112,5 +111,4 @@ export declare const mergeShortSegments: <Segment extends DayCalendarRange & {
 }>(segments: readonly Segment[], { thresholdMs }: {
   thresholdMs: number;
 }) => MergedSegment<Segment>[];
-//#endregion
 export {};

package/dist/calendar/day-calendar.logic.js

@@ -1,6 +1,6 @@
 import { Result, panic } from "better-result";
 import { Temporal } from "temporal-polyfill/full";
-//#region src/calendar/day-calendar.logic.ts
+// src/calendar/day-calendar.logic.ts
 const DAY_CALENDAR_GRANULARITIES = [
 	15,
 	30,
@@ -234,5 +234,4 @@ function compareIds(left, right) {
 	if (left < right) return -1;
 	return left > right ? 1 : 0;
 }
-//#endregion
 export { DAY_CALENDAR_GRANULARITIES, DAY_CALENDAR_ONE_LINE_BLOCK_MIN_PX, DAY_CALENDAR_SLOT_HEIGHT_PX, boundsHeight, clampToBounds, extendRange, getDayBounds, getHourTicks, granularityMs, isRepeatedWallTime, layoutOverlaps, mergeShortSegments, moveRange, offsetToTime, rangeFromDrag, slotAt, snapToGrid, timeToOffset };

package/dist/calendar/primitives.d.ts

@@ -1,9 +1,7 @@
 import * as React$1 from "react";
-//#region src/calendar/primitives.d.ts
 export declare const CalendarGrid: ({ className, ...props }: React$1.ComponentProps<"div">) => React$1.JSX.Element;
 export declare const CalendarHeaderRow: ({ className, ...props }: React$1.ComponentProps<"div">) => React$1.JSX.Element;
 export declare const CalendarHeaderCell: ({ className, ...props }: React$1.ComponentProps<"div">) => React$1.JSX.Element;
 export declare const CalendarCell: ({ className, ...props }: React$1.ComponentProps<"div">) => React$1.JSX.Element;
 export declare const CalendarEntryButton: ({ className, ...props }: React$1.ComponentProps<"button">) => React$1.JSX.Element;
-export declare const CalendarEntrySurface: ({ className, ...props }: React$1.ComponentProps<"article">) => React$1.JSX.Element;
-//#endregion
+export declare const CalendarEntrySurface: ({ className, ...props }: React$1.ComponentProps<"article">) => React$1.JSX.Element;

package/dist/calendar/primitives.js

@@ -1,6 +1,6 @@
 import { cn } from "../lib/utils.js";
 import { jsx } from "react/jsx-runtime";
-//#region src/calendar/primitives.tsx
+// src/calendar/primitives.tsx
 const CalendarGrid = ({ className, ...props }) => /* @__PURE__ */ jsx("div", {
 	className: cn("grid", className),
 	"data-slot": "calendar-grid",
@@ -32,5 +32,4 @@ const CalendarEntrySurface = ({ className, ...props }) => /* @__PURE__ */ jsx("a
 	"data-slot": "calendar-entry",
 	...props
 });
-//#endregion
 export { CalendarCell, CalendarEntryButton, CalendarEntrySurface, CalendarGrid, CalendarHeaderCell, CalendarHeaderRow };

package/dist/calendar/resource-calendar.d.ts

@@ -1,5 +1,4 @@
 import { ReactElement, ReactNode } from "react";
-//#region src/calendar/resource-calendar.d.ts
 export type ResourceCalendarColumn = {
   date: string;
   label: ReactNode;
@@ -31,5 +30,4 @@ type ResourceCalendarProps = {
   resources: readonly ResourceCalendarResource[];
 };
 export declare const ResourceCalendar: ({ ariaLabel, columns, empty, entries, onSelectEntry, resourceHeader, resources }: ResourceCalendarProps) => ReactElement;
-//#endregion
 export {};

package/dist/calendar/resource-calendar.js

@@ -4,7 +4,7 @@ import { assertConsecutiveCalendarDates, layoutResourceCalendarEntries, nextCale
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { useId } from "react";
 import { panic } from "better-result";
-//#region src/calendar/resource-calendar.tsx
+// src/calendar/resource-calendar.tsx
 const ResourceCalendar = ({ ariaLabel, columns, empty, entries, onSelectEntry, resourceHeader, resources }) => {
 	assertResourceCalendarContract({
 		columns,
@@ -181,5 +181,4 @@ const assertResourceCalendarContract = ({ columns, entries, resources }) => {
 	const orphan = entries.find(({ resourceId }) => !resourceIds.has(resourceId));
 	if (orphan !== void 0) panic(`Resource calendar entry ${orphan.id} references an unknown resource`);
 };
-//#endregion
 export { ResourceCalendar };

package/dist/calendar/resource-calendar.logic.d.ts

@@ -1,4 +1,3 @@
-//#region src/calendar/resource-calendar.logic.d.ts
 export type CalendarDateRange = {
   endDateExclusive: string;
   startDate: string;
@@ -23,5 +22,4 @@ export declare const assertConsecutiveCalendarDates: (dates: readonly string[])
 export declare const nextCalendarDate: (value: string) => string;
 export declare const layoutResourceCalendarEntries: (entries: readonly (CalendarDateRange & {
   id: string;
-})[], visibleRange: CalendarDateRange) => ResourceCalendarLaneLayout;
-//#endregion
+})[], visibleRange: CalendarDateRange) => ResourceCalendarLaneLayout;

package/dist/calendar/resource-calendar.logic.js

@@ -1,6 +1,6 @@
 import { Result, panic } from "better-result";
 import { Temporal } from "temporal-polyfill/full";
-//#region src/calendar/resource-calendar.logic.ts
+// src/calendar/resource-calendar.logic.ts
 const ISO_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/u;
 const toPlainDate = (value) => {
 	if (!ISO_DATE_PATTERN.test(value)) return null;
@@ -83,5 +83,4 @@ const layoutResourceCalendarEntries = (entries, visibleRange) => {
 		rowCount: Math.max(1, laneEnds.length)
 	};
 };
-//#endregion
 export { assertConsecutiveCalendarDates, getResourceCalendarPlacement, layoutResourceCalendarEntries, nextCalendarDate };

package/dist/components/accordion.d.ts

@@ -1,6 +1,13 @@
 import { Accordion as Accordion$1 } from "@base-ui/react/accordion";
-//#region src/components/accordion.d.ts
-declare const Accordion: <Value = unknown>(props: Accordion$1.Root.Props<Value>) => import("react").JSX.Element;
+/**
+ * Closed panels stay in the document. Once mounted they are
+ * `hidden="until-found"`, so find-in-page reaches their content and opens
+ * the section, as it would a native `<details>`; server-rendered markup
+ * carries a plain `hidden` until hydration. Pass `hiddenUntilFound={false}` (here, or on one
+ * `AccordionPanel`) to unmount closed content instead: a heavy panel that
+ * should not render until asked for.
+ */
+declare const Accordion: <Value = unknown>({ hiddenUntilFound, ...props }: Accordion$1.Root.Props<Value>) => import("react").JSX.Element;
 declare const AccordionItem: ({ className, ...props }: Accordion$1.Item.Props) => import("react").JSX.Element;
 /**
  * - `default`: a section heading of a page or panel.
@@ -15,12 +22,19 @@ type AccordionSize = "default" | "sm" | "compact";
  *   hover, for a disclosure that is secondary to what is around it.
  */
 type AccordionTriggerVariant = "default" | "muted";
-declare const AccordionTrigger: ({ className, children, size, variant, ...props }: Accordion$1.Trigger.Props & {
+declare const AccordionTrigger: ({ className, children, size, variant, trailing, ...props }: Accordion$1.Trigger.Props & {
   size?: AccordionSize;
   variant?: AccordionTriggerVariant;
+  /**
+   * Status at the end of the row, before the chevron: a count, "2 unsaved",
+   * a last-updated date. It is part of the trigger, so it is read with the
+   * heading. It is typed as text so it can never be a control: a button
+   * inside the trigger's button is unreachable and its click would toggle
+   * the panel.
+   */
+  trailing?: string | number;
 }) => import("react").JSX.Element;
 declare const AccordionPanel: ({ className, children, size, ...props }: Accordion$1.Panel.Props & {
   size?: AccordionSize;
 }) => import("react").JSX.Element;
-//#endregion
 export { Accordion, AccordionPanel as AccordionContent, AccordionPanel, AccordionItem, AccordionTrigger };

package/dist/components/accordion.js

@@ -3,9 +3,18 @@ import { ChevronDownIcon } from "../icons.js";
 import { cn } from "../lib/utils.js";
 import { Accordion as Accordion$1 } from "@base-ui/react/accordion";
 import { jsx, jsxs } from "react/jsx-runtime";
-//#region src/components/accordion.tsx
-const Accordion = (props) => /* @__PURE__ */ jsx(Accordion$1.Root, {
+// src/components/accordion.tsx
+/**
+* Closed panels stay in the document. Once mounted they are
+* `hidden="until-found"`, so find-in-page reaches their content and opens
+* the section, as it would a native `<details>`; server-rendered markup
+* carries a plain `hidden` until hydration. Pass `hiddenUntilFound={false}` (here, or on one
+* `AccordionPanel`) to unmount closed content instead: a heavy panel that
+* should not render until asked for.
+*/
+const Accordion = ({ hiddenUntilFound = true, ...props }) => /* @__PURE__ */ jsx(Accordion$1.Root, {
 	"data-slot": "accordion",
+	hiddenUntilFound,
 	...props
 });
 const AccordionItem = ({ className, ...props }) => /* @__PURE__ */ jsx(Accordion$1.Item, {
@@ -27,20 +36,28 @@ const TRIGGER_VARIANT_CLASS_NAME = {
 	default: "font-medium",
 	muted: "text-muted-foreground hover:text-foreground font-normal"
 };
-const AccordionTrigger = ({ className, children, size = "default", variant = "default", ...props }) => /* @__PURE__ */ jsx(Accordion$1.Header, {
+const AccordionTrigger = ({ className, children, size = "default", variant = "default", trailing, ...props }) => /* @__PURE__ */ jsx(Accordion$1.Header, {
 	className: "flex",
 	children: /* @__PURE__ */ jsxs(Accordion$1.Trigger, {
 		className: cn("focus-visible:ring-ring flex flex-1 cursor-pointer items-start justify-between gap-4 rounded-md text-start outline-none focus-visible:ring-[3px] disabled:pointer-events-none disabled:opacity-64 data-panel-open:*:data-[slot=accordion-indicator]:rotate-180", TRIGGER_SIZE_CLASS_NAME[size], TRIGGER_VARIANT_CLASS_NAME[variant], className),
 		"data-slot": "accordion-trigger",
 		...props,
-		children: [children, /* @__PURE__ */ jsx(ChevronDownIcon, {
-			className: "pointer-events-none size-4 shrink-0 translate-y-0.5 opacity-80 transition-transform duration-200 ease-in-out",
-			"data-slot": "accordion-indicator"
-		})]
+		children: [
+			children,
+			trailing === void 0 ? null : /* @__PURE__ */ jsx("span", {
+				className: "text-muted-foreground ms-auto min-w-0 text-end text-xs font-normal tabular-nums",
+				"data-slot": "accordion-trigger-trailing",
+				children: trailing
+			}),
+			/* @__PURE__ */ jsx(ChevronDownIcon, {
+				className: "pointer-events-none size-4 shrink-0 translate-y-0.5 opacity-80 transition-transform duration-200 ease-in-out",
+				"data-slot": "accordion-indicator"
+			})
+		]
 	})
 });
 const AccordionPanel = ({ className, children, size = "default", ...props }) => /* @__PURE__ */ jsx(Accordion$1.Panel, {
-	className: "text-muted-foreground h-(--accordion-panel-height) overflow-hidden text-sm transition-[height] duration-200 ease-in-out data-ending-style:h-0 data-starting-style:h-0",
+	className: "text-muted-foreground h-(--accordion-panel-height) overflow-hidden text-sm transition-[height] duration-200 ease-in-out data-ending-style:h-0 data-starting-style:h-0 motion-reduce:transition-none [&[hidden]:not([hidden=until-found])]:hidden",
 	"data-slot": "accordion-panel",
 	...props,
 	children: /* @__PURE__ */ jsx("div", {
@@ -48,5 +65,4 @@ const AccordionPanel = ({ className, children, size = "default", ...props }) =>
 		children
 	})
 });
-//#endregion
 export { Accordion, AccordionPanel as AccordionContent, AccordionPanel, AccordionItem, AccordionTrigger };

package/dist/components/ai-label.d.ts

@@ -1,4 +1,3 @@
-//#region src/components/ai-label.d.ts
 type AiLabelProps = {
   /**
    * The words the mark shows ("AI", "AI topics"), already translated. They
@@ -30,5 +29,4 @@ type AiLabelProps = {
  * technology.
  */
 export declare const AiLabel: ({ label, disclosure, className }: AiLabelProps) => import("react").JSX.Element;
-//#endregion
 export {};

package/dist/components/ai-label.js

@@ -3,7 +3,7 @@ import { SparklesIcon } from "../icons.js";
 import { cn } from "../lib/utils.js";
 import { Popover, PopoverContent as PopoverPopup, PopoverDescription, PopoverTrigger } from "./popover.js";
 import { jsx, jsxs } from "react/jsx-runtime";
-//#region src/components/ai-label.tsx
+// src/components/ai-label.tsx
 /**
 * The mark on content a model wrote, and the one place a reader learns what
 * that means.
@@ -38,5 +38,4 @@ const AiLabel = ({ label, disclosure, className }) => /* @__PURE__ */ jsxs(Popov
 		children: disclosure
 	})
 })] });
-//#endregion
 export { AiLabel };

package/dist/components/alert-dialog.d.ts

@@ -1,7 +1,6 @@
 import * as React$1 from "react";
 import { AlertDialog as AlertDialog$1 } from "@base-ui/react/alert-dialog";
 import { OverlayLayer } from "../lib/overlay-layer.js";
-//#region src/components/alert-dialog.d.ts
 declare const AlertDialogCreateHandle: typeof AlertDialog$1.createHandle;
 declare const AlertDialog: typeof AlertDialog$1.Root;
 declare const AlertDialogPortal: React$1.ForwardRefExoticComponent<Omit<import("@base-ui/react").DialogPortalProps, "ref"> & React$1.RefAttributes<HTMLDivElement>>;
@@ -28,5 +27,4 @@ declare const AlertDialogDescription: ({ className, ...props }: AlertDialog$1.De
 declare function AlertDialogClose({ tooltip, ...props }: AlertDialog$1.Close.Props & {
   tooltip?: React$1.ReactNode;
 }): React$1.JSX.Element;
-//#endregion
 export { AlertDialog, AlertDialogBackdrop, AlertDialogBackdrop as AlertDialogOverlay, AlertDialogClose, AlertDialogPopup as AlertDialogContent, AlertDialogPopup, AlertDialogCreateHandle, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogPanel, AlertDialogPortal, AlertDialogTitle, AlertDialogTrigger, AlertDialogViewport };

package/dist/components/alert-dialog.js

@@ -5,7 +5,7 @@ import { SAFE_AREA_OVERLAY_GUTTER_CLASS_NAME } from "../lib/safe-area.js";
 import { renderTooltipTrigger } from "./tooltip-trigger-helper.js";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { AlertDialog as AlertDialog$1 } from "@base-ui/react/alert-dialog";
-//#region src/components/alert-dialog.tsx
+// src/components/alert-dialog.tsx
 const AlertDialogCreateHandle = AlertDialog$1.createHandle;
 const AlertDialog = AlertDialog$1.Root;
 const AlertDialogPortal = AlertDialog$1.Portal;
@@ -72,5 +72,4 @@ function AlertDialogClose({ tooltip, ...props }) {
 		})
 	});
 }
-//#endregion
 export { AlertDialog, AlertDialogBackdrop, AlertDialogBackdrop as AlertDialogOverlay, AlertDialogClose, AlertDialogPopup as AlertDialogContent, AlertDialogPopup, AlertDialogCreateHandle, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogPanel, AlertDialogPortal, AlertDialogTitle, AlertDialogTrigger, AlertDialogViewport };

package/dist/components/animated-count.d.ts

@@ -1,4 +1,3 @@
-//#region src/components/animated-count.d.ts
 /**
  * A formatted number whose changed characters fade in. The caller formats
  * (locale digits, units); the glyphs stay plain inline text so bidirectional
@@ -9,5 +8,4 @@ declare const AnimatedCount: ({ className, value }: {
   className?: string;
   value: string;
 }) => import("react").JSX.Element;
-//#endregion
 export { AnimatedCount };

package/dist/components/animated-count.js

@@ -2,7 +2,7 @@
 import { cn } from "../lib/utils.js";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { useState } from "react";
-//#region src/components/animated-count.tsx
+// src/components/animated-count.tsx
 /**
 * Aligns characters from the end, where digits keep their place value, so
 * 99 → 100 changes every glyph but 120 → 121 only the last one. An unchanged
@@ -59,5 +59,4 @@ const AnimatedCount = ({ className, value }) => {
 		})]
 	});
 };
-//#endregion
 export { AnimatedCount };

package/dist/components/animated-preview.css

@@ -0,0 +1,152 @@
+/*
+ * AnimatedPreview (animated-preview.tsx): the one animation system for
+ * previews that explain a feature by playing it.
+ *
+ * A frame stacks its stages in one grid cell. Stage `i` comes in at
+ * `i * hold` after the frame starts and goes out one hold later, cross-fading
+ * with its neighbour. A frame starts with the stage that holds it (plus its
+ * own stagger), so nested frames play inside their stage. Everything runs on
+ * CSS time; only a looping frame restarts itself, from JavaScript, once its
+ * last stage has gone out. With reduced motion nothing animates and the
+ * component renders only the final stage.
+ */
+
+[data-slot="animated-preview"] {
+  --animated-preview-crossfade: 208ms;
+  --animated-preview-frame-start: calc(
+    var(--animated-preview-stage-start, 0ms) +
+      var(--animated-preview-stagger, 0) * 160ms
+  );
+
+  display: grid;
+}
+
+span[data-slot="animated-preview"] {
+  display: inline-grid;
+  justify-items: start;
+}
+
+[data-slot="animated-preview-stage"] {
+  --animated-preview-stage-start: calc(
+    var(--animated-preview-frame-start) + var(--animated-preview-stage-index) *
+      var(--animated-preview-hold)
+  );
+
+  grid-area: 1 / 1;
+}
+
+[data-pace="glance"] {
+  --animated-preview-hold: 1664ms;
+}
+
+[data-pace="read"] {
+  --animated-preview-hold: 2600ms;
+}
+
+[data-pace="beat"] {
+  --animated-preview-hold: 640ms;
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  [data-slot="animated-preview-stage"][data-incoming] {
+    animation: animated-preview-fade-in var(--animated-preview-crossfade) linear
+      var(--animated-preview-stage-start) both;
+  }
+
+  /* `forwards` only: a backwards fill would hold the stage visible before
+     it has come in. */
+  [data-slot="animated-preview-stage"][data-outgoing] {
+    animation: animated-preview-fade-out var(--animated-preview-crossfade)
+      linear
+      calc(var(--animated-preview-stage-start) + var(--animated-preview-hold))
+      forwards;
+  }
+
+  [data-slot="animated-preview-stage"][data-incoming][data-outgoing] {
+    animation:
+      animated-preview-fade-in var(--animated-preview-crossfade) linear
+        var(--animated-preview-stage-start) both,
+      animated-preview-fade-out var(--animated-preview-crossfade) linear
+        calc(var(--animated-preview-stage-start) + var(--animated-preview-hold))
+        forwards;
+  }
+
+  /* The carry lands as the frame inside crosses from its first stage to its
+     second: that crossover sits at 64% of the gesture. */
+  [data-slot="animated-preview-motion"][data-motion="full"] {
+    animation: animated-preview-carry calc(var(--animated-preview-hold) / 0.64)
+      ease-in-out var(--animated-preview-stage-start, 0ms) forwards;
+  }
+}
+
+[data-slot="animated-preview-motion"][data-motion="reduced"] {
+  transform: translate(
+    var(--animated-preview-carry-x),
+    var(--animated-preview-carry-y)
+  );
+}
+
+@keyframes animated-preview-fade-in {
+  from {
+    opacity: 0;
+  }
+
+  to {
+    opacity: 1;
+  }
+}
+
+@keyframes animated-preview-fade-out {
+  from {
+    opacity: 1;
+  }
+
+  to {
+    opacity: 0;
+  }
+}
+
+/*
+ * Picked up (a small nudge, a 0.375rem lift, tilt and shadow), carried to the
+ * caller's target, and put down there. The caller sets
+ * `--animated-preview-carry-x` and `--animated-preview-carry-y`.
+ */
+@keyframes animated-preview-carry {
+  0%,
+  28% {
+    transform: none;
+    filter: none;
+  }
+
+  38% {
+    transform: translate(
+        0.25rem,
+        calc(var(--animated-preview-carry-y) - 0.375rem)
+      )
+      rotate(2.5deg) scale(1.05);
+    filter: drop-shadow(
+      0 8px 10px color-mix(in srgb, var(--color-black) 28%, transparent)
+    );
+  }
+
+  64% {
+    transform: translate(
+        var(--animated-preview-carry-x),
+        calc(var(--animated-preview-carry-y) - 0.375rem)
+      )
+      rotate(2.5deg) scale(1.05);
+    filter: drop-shadow(
+      0 8px 10px color-mix(in srgb, var(--color-black) 28%, transparent)
+    );
+  }
+
+  74%,
+  100% {
+    transform: translate(
+        var(--animated-preview-carry-x),
+        var(--animated-preview-carry-y)
+      )
+      rotate(0deg) scale(1);
+    filter: none;
+  }
+}

package/dist/components/animated-preview.d.ts

@@ -0,0 +1,75 @@
+import * as React$1 from "react";
+/**
+ * The one animation system for previews that explain a feature by playing it:
+ * a frame of ordered stages that cross-fade into each other, an optional
+ * carry gesture around a frame, and a hover card that hosts a preview beside
+ * the control it explains.
+ *
+ * The styles live in `animated-preview.css`, shipped through
+ * `@stll/ui/theme.css`. A stage's clock is CSS only: stage `i` comes in at
+ * `i` holds after its frame starts and goes out one hold later, so a frame
+ * nested inside a stage starts when that stage does. With reduced motion a
+ * frame renders only its final stage, statically.
+ */
+/**
+ * `once` plays the stages through and rests on the last one. `loop` lets the
+ * last stage go out and starts again from the first.
+ */
+export type AnimatedPreviewPlayback = "once" | "loop";
+/**
+ * How long each stage holds before the next one crosses over: `glance` for a
+ * gesture read at a glance, `read` for a stage carrying a sentence, `beat` for
+ * a step inside a stage.
+ */
+export type AnimatedPreviewPace = "glance" | "read" | "beat";
+export type AnimatedPreviewStage = {
+  id: string;
+  content: React$1.ReactNode;
+};
+type AnimatedPreviewProps = {
+  stages: readonly [AnimatedPreviewStage, ...AnimatedPreviewStage[]];
+  playback?: AnimatedPreviewPlayback;
+  pace?: AnimatedPreviewPace;
+  /**
+   * Steps this frame waits after the stage holding it comes in, so frames
+   * nested in one stage can follow each other.
+   */
+  stagger?: number;
+  /** Lays the frame out inline, to sit inside a sentence. */
+  inline?: boolean;
+  className?: string;
+};
+export declare const AnimatedPreview: ({ stages, playback, pace, stagger, inline, className }: AnimatedPreviewProps) => React$1.JSX.Element;
+type AnimatedPreviewMotionProps = React$1.ComponentProps<"div"> & {
+  pace?: AnimatedPreviewPace;
+};
+/**
+ * Carries its content along: picked up (lift, tilt, shadow), moved, and put
+ * down as the frame inside it crosses from its first stage to its second.
+ * The caller places the drop with `--animated-preview-carry-x` and
+ * `--animated-preview-carry-y`; with reduced motion the content rests there.
+ */
+export declare const AnimatedPreviewMotion: ({ className, pace, ...props }: AnimatedPreviewMotionProps) => React$1.JSX.Element;
+/** How long a pointer or keyboard focus rests on the trigger before the card opens. */
+export declare const ANIMATED_PREVIEW_CARD_DELAY_MS = 400;
+type AnimatedPreviewCardProps = React$1.PropsWithChildren<{
+  /**
+   * The control the card explains. It must take the props it is handed, as a
+   * `Button` does: the card opens from its hover and focus events.
+   */
+  trigger: React$1.ReactElement;
+  /**
+   * One line on what the control does. Shown under the preview and read as
+   * the control's description, so the moving preview itself stays out of the
+   * accessibility tree.
+   */
+  description: React$1.ReactNode;
+  className?: string;
+}>;
+/**
+ * A preview card opened by hovering or focusing a control. It takes no focus
+ * and traps none: the card describes the control, and the control stays the
+ * thing that is used.
+ */
+export declare const AnimatedPreviewCard: ({ trigger, description, className, children }: AnimatedPreviewCardProps) => React$1.JSX.Element;
+export {};