@leavepulse/ui 0.68.0 → 0.70.0

package/src/components/status.ts

@@ -0,0 +1,46 @@
+import type { MeterTone } from "./meter"
+
+/*
+ * The states a service, a bot or a person can be in, and what each one looks
+ * like. Named by meaning so a table of servers and a header pill agree on what
+ * "degraded" is without each picking a colour.
+ */
+export type StatusKind =
+  | "online"
+  | "offline"
+  | "degraded"
+  | "down"
+  | "maintenance"
+  | "starting"
+  | "unknown"
+
+export interface StatusLook {
+  tone: MeterTone
+  /**
+   * Whether the light breathes. Reserved for states that are LIVE (online:
+   * something is answering right now) or IN MOTION (starting: it will not stay
+   * like this) or demand attention (down). A pulse on every row would make the
+   * pulse mean nothing, so steady states stay still.
+   */
+  pulse: boolean
+}
+
+export const STATUS_LOOK: Record<StatusKind, StatusLook> = {
+  online: { tone: "ok", pulse: true },
+  offline: { tone: "neutral", pulse: false },
+  degraded: { tone: "warning", pulse: false },
+  down: { tone: "danger", pulse: true },
+  maintenance: { tone: "brand", pulse: false },
+  starting: { tone: "brand", pulse: true },
+  unknown: { tone: "neutral", pulse: false },
+}
+
+export const STATUS_LABELS: Record<StatusKind, string> = {
+  online: "Online",
+  offline: "Offline",
+  degraded: "Degraded",
+  down: "Down",
+  maintenance: "Maintenance",
+  starting: "Starting",
+  unknown: "Unknown",
+}

package/src/components/tableFacets.ts

@@ -0,0 +1,25 @@
+import { computed } from "vue"
+import { countValues } from "./tableFilter"
+
+export function useTableFacets<T extends Record<string, unknown>>(options: {
+  rows: () => T[]
+  columns: () => string[]
+  hidden: () => Record<string, ReadonlySet<unknown>>
+}) {
+  // Each column stays lazy: opening one filter must not compute every other filter.
+  const columns = computed(() => new Map(options.columns().map((key) => [key, {
+    distinct: computed(() => [...new Set(options.rows().map((row) => row[key]))]),
+    counts: computed(() => {
+      const others = Object.entries(options.hidden()).filter(([column, values]) => column !== key && values.size)
+      const rows = others.length
+        ? options.rows().filter((row) => others.every(([column, values]) => !values.has(row[column])))
+        : options.rows()
+      return countValues(rows, key)
+    }),
+  }])))
+
+  return {
+    distinct: (key: string): unknown[] => columns.value.get(key)?.distinct.value ?? [],
+    counts: (key: string): Map<unknown, number> | undefined => columns.value.get(key)?.counts.value,
+  }
+}

package/src/components/textSplit.ts

@@ -0,0 +1,55 @@
+import { graphemes } from "./scramble"
+
+/*
+ * Splitting text into the pieces an entrance animates (LpTextReveal).
+ *
+ * Words are the unit of identity: each gets a key from its text and how many
+ * times that text appeared before it, so when the sentence changes the words
+ * that are still there keep their key (and their DOM node, and do not replay),
+ * and only the new ones animate in. Keying by position instead would replay
+ * every word after an insertion.
+ *
+ * Whitespace is kept as its own piece and is never animated: it stays a real
+ * space in the flow, which is what lets the line wrap between words. Letters
+ * of one word stay inside that word's box, so letter mode never breaks a word
+ * across lines.
+ */
+
+export interface TextWord {
+  kind: "word"
+  /** Stable across edits for the same word in the same order. */
+  key: string
+  text: string
+  /** Letters (graphemes), or the whole word as one piece in word mode. */
+  parts: string[]
+}
+
+export interface TextSpace {
+  kind: "space"
+  key: string
+  text: string
+}
+
+export type TextPiece = TextWord | TextSpace
+
+export function splitText(text: string, by: "word" | "letter"): TextPiece[] {
+  const pieces: TextPiece[] = []
+  const seen = new Map<string, number>()
+  let spaces = 0
+  for (const token of text.split(/(\s+)/)) {
+    if (!token) continue
+    if (/^\s+$/.test(token)) {
+      pieces.push({ kind: "space", key: `s${spaces++}`, text: token })
+      continue
+    }
+    const n = seen.get(token) ?? 0
+    seen.set(token, n + 1)
+    pieces.push({ kind: "word", key: `${token}#${n}`, text: token, parts: by === "letter" ? graphemes(token) : [token] })
+  }
+  return pieces
+}
+
+/** Keys of the words in `pieces`. */
+export function wordKeys(pieces: TextPiece[]): Set<string> {
+  return new Set(pieces.filter((p) => p.kind === "word").map((p) => p.key))
+}

package/src/components/timeSpan.ts

@@ -0,0 +1,183 @@
+/*
+ * Spans of time as people read them: "0:42", "2d 3h", "1m 12s".
+ *
+ * Pure functions, shared by LpCountdown (time left) and LpPipeline (time
+ * taken), so a job that ran for 72 seconds and a code that can be resent in 72
+ * seconds are written the same way. Nothing here reads the clock: callers pass
+ * milliseconds, which is what makes the formatting testable and lets the
+ * components decide how often to look at the time.
+ */
+
+export interface TimeSplit {
+  days: number
+  hours: number
+  minutes: number
+  seconds: number
+  /** Whole milliseconds left over below a second. */
+  ms: number
+}
+
+export type TimeUnit = "d" | "h" | "m" | "s"
+
+/** Unit suffixes, so an app can write "2 д 3 ч" without reformatting. */
+export type TimeUnitLabels = Record<TimeUnit, string>
+
+export const DEFAULT_UNIT_LABELS: TimeUnitLabels = { d: "d", h: "h", m: "m", s: "s" }
+
+/**
+ * How a span is written.
+ *
+ * `clock` is for a short wait the eye follows second by second ("0:42",
+ * "1:05:09"); `units` is for a long one read at a glance ("2d 3h"); `auto` is
+ * clock below an hour and units above it, which is what both examples above
+ * want without the caller choosing.
+ */
+export type TimeFormat = "auto" | "clock" | "units"
+
+const SECOND = 1000
+const MINUTE = 60 * SECOND
+const HOUR = 60 * MINUTE
+const DAY = 24 * HOUR
+
+/** Splits a span into calendar-free parts. Negative spans count as zero. */
+export function splitTime(ms: number): TimeSplit {
+  const total = Number.isFinite(ms) ? Math.max(0, Math.floor(ms)) : 0
+  return {
+    days: Math.floor(total / DAY),
+    hours: Math.floor((total % DAY) / HOUR),
+    minutes: Math.floor((total % HOUR) / MINUTE),
+    seconds: Math.floor((total % MINUTE) / SECOND),
+    ms: total % SECOND,
+  }
+}
+
+/** One printed piece of a span: a number and what follows it. */
+export interface TimePart {
+  unit: TimeUnit
+  value: number
+  /** Digits to pad to: 2 for a clock's minutes and seconds after the first. */
+  pad: number
+  /** Text printed after the number: a unit suffix, or ":" between clock fields. */
+  after: string
+}
+
+/**
+ * A countdown rounds UP: with 41.2 s left it says 0:42, so the display only
+ * reaches 0:00 at the moment the wait is over. Rounding down would show 0:00
+ * for most of the last second while the thing is still not ready.
+ */
+export function ceilToSecond(ms: number): number {
+  if (!Number.isFinite(ms) || ms <= 0) return 0
+  return Math.ceil(ms / SECOND) * SECOND
+}
+
+/** Which of `clock` and `units` an `auto` span resolves to. */
+export function resolveFormat(ms: number, format: TimeFormat): "clock" | "units" {
+  if (format !== "auto") return format
+  return ms >= HOUR ? "units" : "clock"
+}
+
+/**
+ * The parts of a span in the given format.
+ *
+ * Units keep the two largest non-zero places ("2d 3h", not "2d 3h 4m 5s"): a
+ * long wait is read for its size, and the extra places only flicker. A span
+ * under a minute keeps its seconds, and zero is "0s" rather than nothing.
+ * The clock always has minutes and seconds and grows hours when it needs
+ * them; days fold into hours, since a clock reading of days is not a clock.
+ */
+export function timeParts(
+  ms: number,
+  format: TimeFormat = "auto",
+  labels: TimeUnitLabels = DEFAULT_UNIT_LABELS,
+  places = 2,
+): TimePart[] {
+  const t = splitTime(ms)
+  if (resolveFormat(ms, format) === "clock") {
+    const hours = t.days * 24 + t.hours
+    const parts: TimePart[] = []
+    if (hours > 0) parts.push({ unit: "h", value: hours, pad: 1, after: ":" })
+    parts.push({ unit: "m", value: t.minutes, pad: hours > 0 ? 2 : 1, after: ":" })
+    parts.push({ unit: "s", value: t.seconds, pad: 2, after: "" })
+    return parts
+  }
+  const all: Array<[TimeUnit, number]> = [["d", t.days], ["h", t.hours], ["m", t.minutes], ["s", t.seconds]]
+  const first = all.findIndex(([, v]) => v > 0)
+  if (first === -1) return [{ unit: "s", value: 0, pad: 1, after: labels.s }]
+  return all
+    .slice(first, first + Math.max(1, places))
+    // A trailing zero place says nothing ("2d 0h"); a middle one would, but
+    // with two places there is no middle.
+    .filter(([, v], i) => i === 0 || v > 0)
+    .map(([unit, value]) => ({ unit, value, pad: 1, after: labels[unit] }))
+}
+
+/** Pads a part's number the way the clock prints it. */
+export function padPart(part: Pick<TimePart, "value" | "pad">): string {
+  return String(part.value).padStart(part.pad, "0")
+}
+
+/** The span as one string — for titles, aria text and anything not animated. */
+export function formatTime(
+  ms: number,
+  format: TimeFormat = "auto",
+  labels: TimeUnitLabels = DEFAULT_UNIT_LABELS,
+  places = 2,
+): string {
+  const parts = timeParts(ms, format, labels, places)
+  if (resolveFormat(ms, format) === "clock") return parts.map((p) => padPart(p) + p.after).join("")
+  return parts.map((p) => `${p.value}${p.after}`).join(" ")
+}
+
+/**
+ * Time a job took, as a CI log writes it: "850ms" under a second (a step that
+ * fast is still worth telling apart from one that took nothing), then "42s",
+ * "1m 12s", "1h 3m".
+ */
+export function formatElapsed(ms: number, labels: TimeUnitLabels = DEFAULT_UNIT_LABELS): string {
+  if (!Number.isFinite(ms) || ms < 0) return ""
+  if (ms < SECOND) return `${Math.round(ms)}ms`
+  return formatTime(ms, "units", labels)
+}
+
+/**
+ * Milliseconds until the display next changes, so a ticking timer wakes on the
+ * second boundary instead of every 1000 ms from whenever it started. Started
+ * mid-second, a plain interval shows each value late by that fraction — and
+ * keeps drifting as timers fire late. Never zero: a tick that lands exactly on
+ * the boundary waits a whole second rather than spinning.
+ */
+export function msToNextSecond(remaining: number): number {
+  if (!Number.isFinite(remaining) || remaining <= 0) return SECOND
+  const rest = remaining % SECOND
+  return rest === 0 ? SECOND : rest
+}
+
+/**
+ * Remaining time worth saying aloud. A timer re-read every second is noise to
+ * a screen reader; one that speaks when it crosses a round mark ("5 minutes
+ * left", "10 seconds left") is information. Returns the mark crossed going
+ * from `before` to `after`, or null.
+ */
+export const DEFAULT_MILESTONES = [3600_000, 1800_000, 600_000, 300_000, 60_000, 30_000, 10_000]
+
+export function crossedMilestone(
+  before: number,
+  after: number,
+  milestones: readonly number[] = DEFAULT_MILESTONES,
+): number | null {
+  if (!(after < before)) return null
+  let hit: number | null = null
+  for (const mark of milestones) {
+    if (before > mark && after <= mark) hit = hit === null ? mark : Math.min(hit, mark)
+  }
+  return hit
+}
+
+/** A date-ish input as epoch milliseconds, or NaN when it is not one. */
+export function toEpoch(value: Date | string | number | null | undefined): number {
+  if (value === null || value === undefined || value === "") return Number.NaN
+  if (value instanceof Date) return value.getTime()
+  if (typeof value === "number") return value
+  return new Date(value).getTime()
+}

package/src/components/tone.ts

@@ -0,0 +1,144 @@
+/*
+ * The kit's semantic tones, once.
+ *
+ * Badges, alerts, toasts, loaders, meters, log levels and notification rows all
+ * colour themselves by what something MEANS: fine, worrying, broken, brand,
+ * nothing in particular. Each used to keep its own little map from a tone name
+ * to classes, and the maps drifted: a warning badge was tinted `bg-accent/15`
+ * while a warning row used `--color-accent-soft`, and a toaster called it
+ * `error` where an alert called it `danger`. Here every component looks the
+ * tone up, so the same meaning paints the same colour everywhere, and a theme
+ * that recolours `accent` recolours every warning at once.
+ *
+ * Class strings are spelled out whole on purpose. Tailwind finds classes by
+ * scanning source text, so a class assembled at runtime (`bg-${name}`) would
+ * never be emitted and the tone would silently paint nothing.
+ */
+
+/** The canonical tones. Everything else is an alias of one of these. */
+export type Tone = "neutral" | "brand" | "success" | "warning" | "danger"
+
+/**
+ * Every name a component's `tone` prop accepts. The aliases are the names the
+ * kit's components grew up with (a meter says `ok`, a button palette says
+ * `action`, a toast says `error`), kept so no caller has to rename anything.
+ */
+export type ToneName = Tone | "info" | "ok" | "action" | "accent" | "error" | "muted"
+
+/** Which canonical tone each name stands for. */
+export const TONE_ALIASES: Readonly<Record<ToneName, Tone>> = {
+  neutral: "neutral",
+  muted: "neutral",
+  brand: "brand",
+  info: "brand",
+  success: "success",
+  ok: "success",
+  action: "success",
+  warning: "warning",
+  accent: "warning",
+  danger: "danger",
+  error: "danger",
+}
+
+/** What a component needs to paint one tone. */
+export interface ToneLook {
+  /** The solid colour, as a CSS value for a style or an SVG stroke. */
+  color: string
+  /** The tinted background colour, as a CSS value. */
+  soft: string
+  /** The solid colour as text: an icon, a label, a spinner. */
+  text: string
+  /** The solid colour as a fill: a bar, a dot, a rail. */
+  bg: string
+  /** The tinted background alone. */
+  softBg: string
+  /**
+   * A chip: the tinted background with text that reads on it. Not always
+   * `softBg + text`: neutral text on its soft surface steps up to
+   * muted-strong, because plain muted on surface-soft is too faint to read.
+   */
+  //
+  // The text is the tone mixed 60/40 with ink, not the tone itself: a light
+  // theme's green or amber on its own soft tint read at 2.8 to 3.4:1, under
+  // the 4.5 small text needs. Mixed toward ink it darkens on light themes and
+  // lightens on dark ones, and stays recognisably the tone (5.6 to 6.4:1 on
+  // light, higher on dark).
+  chip: string
+  /** The solid colour as a border. */
+  border: string
+  /** A quiet panel in the tone: a faint tint with a faint edge (an alert, a callout). */
+  panel: string
+  /** Selected text highlighted in the tone. */
+  selection: string
+}
+
+export const TONES: Readonly<Record<Tone, ToneLook>> = {
+  neutral: {
+    color: "var(--color-muted)",
+    soft: "var(--color-surface-soft)",
+    text: "text-muted",
+    bg: "bg-muted",
+    softBg: "bg-surface-soft",
+    chip: "bg-surface-soft text-muted-strong",
+    border: "border-line-strong",
+    panel: "border-line bg-surface-soft",
+    selection: "selection:bg-muted/40",
+  },
+  brand: {
+    color: "var(--color-brand)",
+    soft: "var(--color-brand-soft)",
+    text: "text-brand",
+    bg: "bg-brand",
+    softBg: "bg-brand-soft",
+    chip: "bg-brand-soft text-[color-mix(in_oklab,var(--color-brand)_60%,var(--color-ink))]",
+    border: "border-brand",
+    panel: "border-brand/30 bg-brand/10",
+    selection: "selection:bg-brand/40",
+  },
+  success: {
+    color: "var(--color-action)",
+    soft: "var(--color-action-soft)",
+    text: "text-action",
+    bg: "bg-action",
+    softBg: "bg-action-soft",
+    chip: "bg-action-soft text-[color-mix(in_oklab,var(--color-action)_60%,var(--color-ink))]",
+    border: "border-action",
+    panel: "border-action/30 bg-action/10",
+    selection: "selection:bg-action/40",
+  },
+  warning: {
+    color: "var(--color-accent)",
+    soft: "var(--color-accent-soft)",
+    text: "text-accent",
+    bg: "bg-accent",
+    softBg: "bg-accent-soft",
+    chip: "bg-accent-soft text-[color-mix(in_oklab,var(--color-accent)_60%,var(--color-ink))]",
+    border: "border-accent",
+    panel: "border-accent/30 bg-accent/10",
+    selection: "selection:bg-accent/40",
+  },
+  danger: {
+    color: "var(--color-danger)",
+    soft: "var(--color-danger-soft)",
+    text: "text-danger",
+    bg: "bg-danger",
+    softBg: "bg-danger-soft",
+    chip: "bg-danger-soft text-[color-mix(in_oklab,var(--color-danger)_60%,var(--color-ink))]",
+    border: "border-danger",
+    panel: "border-danger/30 bg-danger/10",
+    selection: "selection:bg-danger/40",
+  },
+}
+
+/**
+ * The canonical tone a name stands for. An unknown name (a typo, a tone from a
+ * newer kit read by an older one) falls back rather than painting nothing.
+ */
+export function toneOf(name: string | null | undefined, fallback: Tone = "neutral"): Tone {
+  return (name && TONE_ALIASES[name as ToneName]) || fallback
+}
+
+/** How a tone is painted, by any of its names. */
+export function toneLook(name: string | null | undefined, fallback: Tone = "neutral"): ToneLook {
+  return TONES[toneOf(name, fallback)]
+}

package/src/components/tour.ts

@@ -82,7 +82,8 @@ export function openContextMenu(el: Element): () => void {
   )
   return () => {
     const outside = { bubbles: true, cancelable: true, clientX: 0, clientY: 0 }
-    document.body.dispatchEvent(new PointerEvent("pointerdown", outside))
-    document.body.dispatchEvent(new PointerEvent("pointerup", outside))
+    const body = el.ownerDocument.body
+    body.dispatchEvent(new PointerEvent("pointerdown", outside))
+    body.dispatchEvent(new PointerEvent("pointerup", outside))
   }
 }

package/src/components/typewriter.ts

@@ -0,0 +1,104 @@
+import type { Random } from "./scramble"
+
+/*
+ * The typewriter's timeline as a pure state machine (LpTypewriter).
+ *
+ * One call advances one keystroke and says how long to wait before the next,
+ * so the component only runs a timer, and a test can walk the whole cycle with
+ * a fixed random source. Strings are passed as grapheme arrays: an emoji is one
+ * keystroke, not two halves.
+ */
+
+export interface TypewriterState {
+  /** The string being shown. */
+  index: number
+  /** How many of its characters are shown. */
+  length: number
+  phase: "typing" | "holding" | "erasing" | "done"
+  /** The string to type once erasing has gone far enough. */
+  to: number
+}
+
+export interface TypewriterOptions {
+  /** Ms per typed character, before variance. */
+  speed: number
+  /** Ms per erased character. Erasing is steady: nobody holds backspace unevenly. */
+  eraseSpeed: number
+  /** Ms a finished string stays before it is erased. */
+  hold: number
+  /** Start over after the last string instead of stopping on it. */
+  loop: boolean
+}
+
+export interface TypewriterStep {
+  state: TypewriterState
+  /** Ms until the next call. Infinity: nothing more to do. */
+  wait: number
+  /** Set when this step finished typing a string: its index. */
+  typed?: number
+}
+
+export const typewriterStart = (): TypewriterState => ({ index: 0, length: 0, phase: "typing", to: 0 })
+
+/**
+ * A keystroke's delay: the base speed with some unevenness, and a pause after
+ * punctuation, which is where a person typing actually stops.
+ */
+export function keystrokeDelay(char: string, speed: number, random: Random): number {
+  const jitter = speed * (0.55 + 0.9 * random())
+  if (/[.!?…]/.test(char)) return jitter + speed * 5
+  if (/[,;:]/.test(char)) return jitter + speed * 2.5
+  return jitter
+}
+
+/** Characters two strings share at the start: erasing stops there and typing goes on from it. */
+export function sharedPrefix(a: string[], b: string[]): number {
+  let n = 0
+  while (n < a.length && n < b.length && a[n] === b[n]) n++
+  return n
+}
+
+export function typewriterNext(
+  state: TypewriterState,
+  strings: string[][],
+  options: TypewriterOptions,
+  random: Random = Math.random,
+): TypewriterStep {
+  const count = strings.length
+  if (!count) return { state: { ...state, phase: "done" }, wait: Infinity }
+  const current = strings[state.index] ?? []
+
+  switch (state.phase) {
+    case "typing": {
+      if (state.length >= current.length) return finish(state, count, options)
+      const length = state.length + 1
+      const next = { ...state, length }
+      if (length < current.length) return { state: next, wait: keystrokeDelay(current[length - 1]!, options.speed, random) }
+      return finish(next, count, options)
+    }
+    case "holding": {
+      const to = (state.index + 1) % count
+      return erase({ ...state, phase: "erasing", to }, strings, options)
+    }
+    case "erasing":
+      return erase(state, strings, options)
+    case "done":
+      return { state, wait: Infinity }
+  }
+}
+
+function finish(state: TypewriterState, count: number, options: TypewriterOptions): TypewriterStep {
+  const last = state.index === count - 1
+  if (last && !options.loop) return { state: { ...state, phase: "done" }, wait: Infinity, typed: state.index }
+  return { state: { ...state, phase: "holding" }, wait: options.hold, typed: state.index }
+}
+
+function erase(state: TypewriterState, strings: string[][], options: TypewriterOptions): TypewriterStep {
+  const keep = sharedPrefix(strings[state.index] ?? [], strings[state.to] ?? [])
+  if (state.length > keep) {
+    const length = state.length - 1
+    // The last backspace is followed by a beat before typing starts again.
+    return { state: { ...state, length }, wait: length > keep ? options.eraseSpeed : options.speed * 4 }
+  }
+  return { state: { index: state.to, length: state.length, phase: "typing", to: state.to }, wait: 0 }
+}

package/src/components/videoBackdrop.ts

@@ -3,6 +3,8 @@
  * so they can be tested without a media element.
  */
 
+import { splitTime } from "./timeSpan"
+
 /** The stretch of a clip that loops, and how long two passes overlap at the seam. */
 export interface LoopPlan {
   /** Where every pass starts, in seconds of media time. */
@@ -63,11 +65,10 @@ export function isNativeLoop(plan: LoopPlan, duration: number): boolean {
 
 /** "1:05", "0:07.5": a position on a clip as a range slider labels it. */
 export function formatClipTime(seconds: number, precise = false): string {
-  const safe = Math.max(0, Number.isFinite(seconds) ? seconds : 0)
-  const minutes = Math.floor(safe / 60)
-  const rest = safe - minutes * 60
-  const whole = Math.floor(rest)
-  const tenth = Math.floor((rest - whole) * 10)
-  const secs = String(whole).padStart(2, "0")
+  const t = splitTime(Number.isFinite(seconds) ? seconds * 1000 : 0)
+  // Hours fold into minutes: a slider over a clip reads "75:00", not "1:15:00".
+  const minutes = (t.days * 24 + t.hours) * 60 + t.minutes
+  const secs = String(t.seconds).padStart(2, "0")
+  const tenth = Math.floor(t.ms / 100)
   return precise && tenth ? `${minutes}:${secs}.${tenth}` : `${minutes}:${secs}`
 }

package/src/composables/easing.ts

@@ -27,7 +27,7 @@
  *
  * A plain function, not a reactive composable: it is read at the moment an
  * animation starts, and a component that also needs to RE-RENDER when the
- * setting changes mid-session should use motion-v's `useReducedMotion`.
+ * setting changes mid-session should use `usePrefersReducedMotion`.
  */
 export const prefersReducedMotion = (): boolean =>
   typeof window !== "undefined" &&
@@ -98,3 +98,68 @@ export const easeTravel = (t: number): number => {
   const head = (EDGE * EDGE) / (2 * EDGE) + EDGE * 0.1
   return head + ((t - EDGE) / (1 - 2 * EDGE)) * (1 - 2 * head)
 }
+
+/**
+ * A cubic-bezier as a function of time, solved per call.
+ *
+ * The curves above are hand-shaped stand-ins for tokens a component reaches for
+ * by feel. A tween that has to match a CSS transition running beside it (a
+ * slice's arc easing while its colour and lift move on `--ease-emphasized`)
+ * needs the token's actual curve, and a theme may retune it — so this reads the
+ * four numbers and solves for them rather than approximating one fixed shape.
+ *
+ * Newton's method on x(s) = t, falling back to bisection where the slope is
+ * too flat to step on; a handful of iterations is far below a pixel.
+ */
+export const cubicBezier = (x1: number, y1: number, x2: number, y2: number) => {
+  const cx = 3 * x1
+  const bx = 3 * (x2 - x1) - cx
+  const ax = 1 - cx - bx
+  const cy = 3 * y1
+  const by = 3 * (y2 - y1) - cy
+  const ay = 1 - cy - by
+  const x = (s: number) => ((ax * s + bx) * s + cx) * s
+  const y = (s: number) => ((ay * s + by) * s + cy) * s
+  const dx = (s: number) => (3 * ax * s + 2 * bx) * s + cx
+
+  return (t: number): number => {
+    if (t <= 0) return 0
+    if (t >= 1) return 1
+    let s = t
+    for (let i = 0; i < 6; i++) {
+      const err = x(s) - t
+      if (Math.abs(err) < 1e-5) return y(s)
+      const slope = dx(s)
+      if (Math.abs(slope) < 1e-6) break
+      s -= err / slope
+    }
+    let lo = 0
+    let hi = 1
+    s = t
+    for (let i = 0; i < 20; i++) {
+      const v = x(s)
+      if (Math.abs(v - t) < 1e-5) break
+      if (v < t) lo = s
+      else hi = s
+      s = (lo + hi) / 2
+    }
+    return y(s)
+  }
+}
+
+/**
+ * An easing token as a function, for a value tweened in script.
+ *
+ * Anything the token does not spell as a `cubic-bezier()` (a keyword, a
+ * `linear()` list) falls back to `easeOut`, which has the same "arrives and
+ * settles" intent as every curve the kit defines.
+ */
+export const tokenEase = (
+  name: "ease-emphasized" | "ease-travel" | "ease-settle",
+): ((t: number) => number) => {
+  const match = /cubic-bezier\(([^)]+)\)/.exec(easingToken(name))
+  const n = match?.[1].split(",").map((p) => Number.parseFloat(p))
+  return n && n.length === 4 && n.every(Number.isFinite)
+    ? cubicBezier(n[0], n[1], n[2], n[3])
+    : easeOut
+}