@leavepulse/ui 0.69.0 → 0.70.1

package/dist/components/scramble.d.ts

@@ -0,0 +1,68 @@
+/** Random number in [0, 1). Injected so frames are reproducible under test. */
+export type Random = () => number;
+/** Glyphs a position cycles through before it settles. Upper case and digits read as "code". */
+export declare const SCRAMBLE_GLYPHS = "ABCDEFGHJKLMNPQRSTUVWXYZ0123456789#%&*+=?@$";
+export interface ScrambleOptions {
+    /** Total travel time in ms, from the first glyph to the last position settling. */
+    duration: number;
+    /**
+     * `sequential` settles left to right, which reads as decoding; `together`
+     * holds every position until near the end and lands them in a short burst,
+     * which reads as a lock opening.
+     */
+    order?: "sequential" | "together";
+    /** Glyph pool. */
+    glyphs?: string;
+    /**
+     * Characters that never scramble: a space or a dash in a key keeps the
+     * grouping visible while the rest churns, so the reader sees the shape of
+     * what is coming.
+     */
+    keep?: (char: string) => boolean;
+}
+export interface ScrambleCell {
+    /** The character settled into, or "" for a position the new value no longer has. */
+    final: string;
+    /** The character shown before the run started (sizes a position the value is losing). */
+    initial: string;
+    /** Ms from the start of the run when this position shows `final`. */
+    settleAt: number;
+    /** Never churns (see `keep`). */
+    fixed: boolean;
+}
+export interface ScrambleFrameCell {
+    /** What to draw now. */
+    char: string;
+    /** The character that gives the position its width: the final one, or the old one while it is leaving. */
+    sizer: string;
+    settled: boolean;
+}
+/**
+ * Splits into user-perceived characters, so an emoji or an accented letter is
+ * one position rather than two halves that scramble separately.
+ */
+export declare function graphemes(text: string): string[];
+/**
+ * When each position stops churning (all of them start at once).
+ *
+ * `sequential`: positions start together and settle on a ramp across the last
+ * 70% of the run, so the left of the value is readable while the right still
+ * moves. `together`: every position settles within the last 15%, with a
+ * little random spread so they do not land as one flat click.
+ */
+export declare function planScramble(from: string, to: string, options: ScrambleOptions, random?: Random): ScrambleCell[];
+/** A glyph from the pool. */
+export declare function randomGlyph(random: Random, glyphs?: string): string;
+/**
+ * The text at `elapsed` ms into the run. A churning position draws a fresh
+ * random glyph each call; the caller decides how often to call (the glyph
+ * re-roll rate), not this.
+ */
+export declare function scrambleFrame(cells: ScrambleCell[], elapsed: number, random?: Random, glyphs?: string): ScrambleFrameCell[];
+/** The cells of a value at rest, for the first paint and for reduced motion. */
+export declare function settledCells(text: string): ScrambleFrameCell[];
+/**
+ * A small seeded generator (mulberry32), for tests and for a scramble that
+ * should look the same every time it plays (a demo, a screenshot).
+ */
+export declare function seededRandom(seed: number): Random;

package/dist/components/scramble.js

@@ -0,0 +1,58 @@
+const SCRAMBLE_GLYPHS = "ABCDEFGHJKLMNPQRSTUVWXYZ0123456789#%&*+=?@$";
+const defaultKeep = (char) => /\s/.test(char);
+function graphemes(text) {
+  const Segmenter = Intl.Segmenter;
+  if (Segmenter) return Array.from(new Segmenter(void 0, { granularity: "grapheme" }).segment(text), (s) => s.segment);
+  return Array.from(text);
+}
+function planScramble(from, to, options, random = Math.random) {
+  const keep = options.keep ?? defaultKeep;
+  const a = graphemes(from);
+  const b = graphemes(to);
+  const length = Math.max(a.length, b.length);
+  const duration = Math.max(0, options.duration);
+  const cells = [];
+  for (let i = 0; i < length; i++) {
+    const final = b[i] ?? "";
+    const initial = a[i] ?? "";
+    let settleAt;
+    if (options.order === "together") settleAt = duration * (0.85 + 0.15 * random());
+    else settleAt = length === 1 ? duration : duration * (0.3 + 0.7 * i / (length - 1));
+    const fixed = final !== "" && keep(final) && (initial === final || initial === "");
+    cells.push({ final, initial, settleAt: fixed ? 0 : settleAt, fixed });
+  }
+  return cells;
+}
+function randomGlyph(random, glyphs = SCRAMBLE_GLYPHS) {
+  const pool = graphemes(glyphs);
+  return pool[Math.min(pool.length - 1, Math.floor(random() * pool.length))] ?? "";
+}
+function scrambleFrame(cells, elapsed, random = Math.random, glyphs = SCRAMBLE_GLYPHS) {
+  return cells.map((cell) => {
+    const sizer = cell.final || cell.initial;
+    if (cell.fixed || elapsed >= cell.settleAt) return { char: cell.final, sizer: cell.final, settled: true };
+    return { char: randomGlyph(random, glyphs), sizer, settled: false };
+  });
+}
+function settledCells(text) {
+  return graphemes(text).map((char) => ({ char, sizer: char, settled: true }));
+}
+function seededRandom(seed) {
+  let state = seed >>> 0;
+  return () => {
+    state = state + 1831565813 >>> 0;
+    let t = state;
+    t = Math.imul(t ^ t >>> 15, t | 1);
+    t ^= t + Math.imul(t ^ t >>> 7, t | 61);
+    return ((t ^ t >>> 14) >>> 0) / 4294967296;
+  };
+}
+export {
+  SCRAMBLE_GLYPHS,
+  graphemes,
+  planScramble,
+  randomGlyph,
+  scrambleFrame,
+  seededRandom,
+  settledCells
+};

package/dist/components/shaderBackdrop.d.ts

@@ -0,0 +1,20 @@
+export type ShaderPreset = "aurora" | "silk" | "grain" | "dots";
+export interface PresetDef {
+    /** Body of the fragment shader, after the shared header. */
+    fragment: string;
+    /** Rendering resolution relative to CSS pixels × pixel ratio. Soft looks lose nothing at half. */
+    scale: number;
+    /** CSS `background` of the still that stands in for the look. */
+    fallback: string;
+}
+export declare const VERTEX_SHADER = "\nattribute vec2 p;\nvoid main() { gl_Position = vec4(p, 0.0, 1.0); }\n";
+export declare const FRAGMENT_HEADER = "\nprecision mediump float;\nuniform vec2 u_res;\nuniform float u_time;\nuniform float u_px;\nuniform float u_k;\nuniform vec3 u_bg;\nuniform vec3 u_brand;\nuniform vec3 u_accent;\nuniform vec3 u_action;\nuniform vec3 u_ink;\n";
+export declare const PRESETS: Record<ShaderPreset, PresetDef>;
+export declare const PRESET_NAMES: ShaderPreset[];
+/** Whether enough time has passed for the next frame at `fps`. Frames land on the display's beat, so allow a little early. */
+export declare function frameDue(now: number, last: number, fps: number): boolean;
+export declare function tooSlow(intervals: readonly number[], fps: number): boolean;
+/** A colour in 0–1 sRGB channels, as a shader takes it. */
+export type Vec3 = [number, number, number];
+/** Move `from` toward `to` by share `k` (0–1): theme changes blend over a few frames instead of snapping. */
+export declare function approach(from: Vec3, to: Vec3, k: number): Vec3;

package/dist/components/shaderBackdrop.js

@@ -0,0 +1,156 @@
+const VERTEX_SHADER = `
+attribute vec2 p;
+void main() { gl_Position = vec4(p, 0.0, 1.0); }
+`;
+const FRAGMENT_HEADER = `
+precision mediump float;
+uniform vec2 u_res;
+uniform float u_time;
+uniform float u_px;
+uniform float u_k;
+uniform vec3 u_bg;
+uniform vec3 u_brand;
+uniform vec3 u_accent;
+uniform vec3 u_action;
+uniform vec3 u_ink;
+`;
+const mix = (token, share) => `color-mix(in oklab, var(--color-${token}) ${share}%, transparent)`;
+const NOISE = `url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='160' height='160'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.9' numOctaves='2' stitchTiles='stitch'/%3E%3CfeColorMatrix values='0 0 0 0 0.5 0 0 0 0 0.5 0 0 0 0 0.5 0 0 0 0.35 0'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)'/%3E%3C/svg%3E")`;
+const PRESETS = {
+  /*
+   * Curtains of light across the upper part: each band has a sharp upper
+   * edge and a long fall-off below it, waves sideways, and is striated by
+   * fine vertical rays that drift.
+   */
+  aurora: {
+    scale: 0.5,
+    fragment: `
+float band(vec2 uv, float x, float off, float sp) {
+  float y = 0.66 + off + 0.09 * sin(x * 1.9 + u_time * sp + off * 9.0) + 0.04 * sin(x * 4.7 - u_time * sp * 1.7 + off * 4.0);
+  float d = uv.y - y;
+  float body = exp(-d * d * (d > 0.0 ? 160.0 : 22.0));
+  float rays = 0.86 + 0.14 * sin(x * 70.0 + 6.0 * sin(x * 2.3 + u_time * 0.4));
+  return body * rays;
+}
+void main() {
+  vec2 uv = gl_FragCoord.xy / u_res;
+  float x = gl_FragCoord.x / u_res.y;
+  vec3 col = u_bg;
+  col = mix(col, u_brand, band(uv, x, 0.0, 0.35) * 0.7 * u_k);
+  col = mix(col, u_accent, band(uv, x, -0.18, 0.27) * 0.45 * u_k);
+  col = mix(col, u_action, band(uv, x, 0.12, 0.43) * 0.45 * u_k);
+  gl_FragColor = vec4(col, 1.0);
+}`,
+    fallback: [
+      `radial-gradient(70% 38% at 30% 28%, ${mix("brand", 42)}, transparent 70%)`,
+      `radial-gradient(55% 30% at 72% 44%, ${mix("accent", 30)}, transparent 70%)`,
+      `radial-gradient(50% 26% at 55% 18%, ${mix("action", 26)}, transparent 70%)`
+    ].join(", ")
+  },
+  /*
+   * A sheet of fabric: diagonal folds that slowly ripple, the brand colour
+   * in the body and a narrow highlight running along each crest.
+   */
+  silk: {
+    scale: 0.5,
+    fragment: `
+void main() {
+  vec2 uv = gl_FragCoord.xy / u_res;
+  vec2 p = (gl_FragCoord.xy - 0.5 * u_res) / u_res.y * 2.2;
+  float t = u_time * 0.6;
+  float f = p.x * 0.9 + p.y * 0.5 + 0.6 * sin(p.y * 1.7 + t) + 0.35 * sin(p.x * 2.3 - t * 0.8 + p.y);
+  float fold = sin(f * 3.4);
+  float sheen = pow(0.5 + 0.5 * fold, 6.0);
+  vec3 tint = mix(u_brand, u_accent, clamp(uv.x * 0.7 + 0.15 * sin(t * 0.5), 0.0, 1.0));
+  vec3 col = mix(u_bg, tint, (0.22 + 0.14 * fold) * u_k);
+  col += sheen * mix(u_brand, vec3(1.0), 0.4) * 0.28 * u_k;
+  gl_FragColor = vec4(col, 1.0);
+}`,
+    fallback: [
+      `linear-gradient(115deg, transparent 12%, ${mix("brand", 30)} 30%, transparent 46%, ${mix("accent", 22)} 64%, transparent 80%)`,
+      `linear-gradient(160deg, ${mix("brand", 16)}, transparent 70%)`
+    ].join(", ")
+  },
+  /*
+   * Two soft colour pools drifting over the surface, under moving film
+   * grain. The grain is per device pixel and refreshes a dozen-odd times a
+   * second, like film, rather than every frame, which would read as static.
+   */
+  grain: {
+    scale: 1,
+    fragment: `
+float hash(vec2 q) { return fract(sin(dot(q, vec2(12.9898, 78.233))) * 43758.5453); }
+void main() {
+  vec2 uv = gl_FragCoord.xy / u_res;
+  float aspect = u_res.x / u_res.y;
+  vec2 p = vec2(uv.x * aspect, uv.y);
+  float t = u_time * 0.25;
+  vec2 a = vec2((0.3 + 0.2 * sin(t)) * aspect, 0.7 + 0.15 * cos(t * 1.3));
+  vec2 b = vec2((0.75 + 0.15 * cos(t * 0.8)) * aspect, 0.3 + 0.2 * sin(t * 1.1));
+  float da = exp(-dot(p - a, p - a) * 3.0);
+  float db = exp(-dot(p - b, p - b) * 4.0);
+  vec3 col = mix(u_bg, u_brand, da * 0.6 * u_k);
+  col = mix(col, u_accent, db * 0.5 * u_k);
+  col = mix(col, u_action, (1.0 - uv.y) * 0.12 * u_k);
+  vec2 cell = floor(gl_FragCoord.xy / max(1.0, u_px));
+  float g = hash(cell + vec2(floor(u_time * 14.0) * 17.31, 0.0)) - 0.5;
+  col += g * 0.09;
+  gl_FragColor = vec4(col, 1.0);
+}`,
+    fallback: [
+      NOISE,
+      `radial-gradient(55% 55% at 28% 30%, ${mix("brand", 40)}, transparent 70%)`,
+      `radial-gradient(50% 50% at 76% 72%, ${mix("accent", 32)}, transparent 70%)`,
+      `linear-gradient(to top, ${mix("action", 10)}, transparent 60%)`
+    ].join(", ")
+  },
+  /*
+   * A dot grid with a slow ripple travelling out from the middle: dots on
+   * the crest swell and take the brand colour, the rest stay small and quiet.
+   */
+  dots: {
+    scale: 1,
+    fragment: `
+void main() {
+  float cell = 22.0 * u_px;
+  vec2 g = gl_FragCoord.xy / cell;
+  vec2 id = floor(g);
+  vec2 f = fract(g) - 0.5;
+  float dist = length(id + 0.5 - 0.5 * u_res / cell);
+  float wave = pow(0.5 + 0.5 * sin(dist * 0.5 - u_time * 1.6), 3.0);
+  float r = 0.08 + 0.07 * wave * u_k;
+  float aa = 1.0 / cell;
+  float dotMask = 1.0 - smoothstep(r - aa, r + aa, length(f));
+  vec3 rest = mix(u_bg, u_ink, 0.2);
+  vec3 col = mix(u_bg, u_brand, wave * 0.03 * u_k);
+  col = mix(col, mix(rest, u_brand, wave * u_k), dotMask);
+  gl_FragColor = vec4(col, 1.0);
+}`,
+    fallback: [
+      `radial-gradient(circle, ${mix("ink", 22)} 1.5px, transparent 2.2px) center / 22px 22px`,
+      `radial-gradient(45% 45% at 50% 50%, ${mix("brand", 16)}, transparent 75%)`
+    ].join(", ")
+  }
+};
+const PRESET_NAMES = Object.keys(PRESETS);
+function frameDue(now, last, fps) {
+  return now - last >= 1e3 / Math.max(1, fps) - 2;
+}
+function tooSlow(intervals, fps) {
+  if (intervals.length < 20) return false;
+  const sorted = [...intervals].sort((a, b) => a - b);
+  const median = sorted[Math.floor(sorted.length / 2)];
+  return median > Math.max(2 * 1e3 / Math.max(1, fps), 80);
+}
+function approach(from, to, k) {
+  return [from[0] + (to[0] - from[0]) * k, from[1] + (to[1] - from[1]) * k, from[2] + (to[2] - from[2]) * k];
+}
+export {
+  FRAGMENT_HEADER,
+  PRESETS,
+  PRESET_NAMES,
+  VERTEX_SHADER,
+  approach,
+  frameDue,
+  tooSlow
+};

package/dist/components/slider.d.ts

@@ -0,0 +1,5 @@
+export declare const SLIDER_GLIDE = "[&_[style*=left]]:transition-[left,right] [&_[style*=left]]:duration-(--duration-medium) [&_[style*=left]]:ease-(--ease-emphasized) data-[dragging]:[&_[style*=left]]:transition-none motion-reduce:[&_[style*=left]]:transition-none";
+export declare function useSliderDrag(): {
+    dragging: import("vue").Ref<boolean, boolean>;
+    onPointerDown: (event: PointerEvent) => void;
+};

package/dist/components/slider.js

@@ -0,0 +1,24 @@
+import { ref, onBeforeUnmount } from "vue";
+const SLIDER_GLIDE = "[&_[style*=left]]:transition-[left,right] [&_[style*=left]]:duration-(--duration-medium) [&_[style*=left]]:ease-(--ease-emphasized) data-[dragging]:[&_[style*=left]]:transition-none motion-reduce:[&_[style*=left]]:transition-none";
+function useSliderDrag() {
+  const dragging = ref(false);
+  let view = null;
+  const end = () => {
+    dragging.value = false;
+    view?.removeEventListener("pointerup", end);
+    view?.removeEventListener("pointercancel", end);
+    view = null;
+  };
+  function onPointerDown(event) {
+    dragging.value = true;
+    view = event.currentTarget.ownerDocument.defaultView;
+    view?.addEventListener("pointerup", end);
+    view?.addEventListener("pointercancel", end);
+  }
+  onBeforeUnmount(end);
+  return { dragging, onPointerDown };
+}
+export {
+  SLIDER_GLIDE,
+  useSliderDrag
+};

package/dist/components/slotText.d.ts

@@ -0,0 +1,2 @@
+import { type Slot } from "vue";
+export declare function slotText(slot: Slot | undefined): string | null;

package/dist/components/slotText.js

@@ -0,0 +1,9 @@
+import { Text } from "vue";
+function slotText(slot) {
+  const nodes = slot?.() ?? [];
+  if (!nodes.length || !nodes.every((node) => node.type === Text)) return null;
+  return nodes.map((node) => String(node.children ?? "")).join("").trim() || null;
+}
+export {
+  slotText
+};

package/dist/components/status.d.ts

@@ -0,0 +1,14 @@
+import type { MeterTone } from "./meter";
+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 declare const STATUS_LOOK: Record<StatusKind, StatusLook>;
+export declare const STATUS_LABELS: Record<StatusKind, string>;

package/dist/components/status.js

@@ -0,0 +1,22 @@
+const STATUS_LOOK = {
+  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 }
+};
+const STATUS_LABELS = {
+  online: "Online",
+  offline: "Offline",
+  degraded: "Degraded",
+  down: "Down",
+  maintenance: "Maintenance",
+  starting: "Starting",
+  unknown: "Unknown"
+};
+export {
+  STATUS_LABELS,
+  STATUS_LOOK
+};

package/dist/components/tableFacets.d.ts

@@ -0,0 +1,8 @@
+export declare function useTableFacets<T extends Record<string, unknown>>(options: {
+    rows: () => T[];
+    columns: () => string[];
+    hidden: () => Record<string, ReadonlySet<unknown>>;
+}): {
+    distinct: (key: string) => unknown[];
+    counts: (key: string) => Map<unknown, number> | undefined;
+};

package/dist/components/tableFacets.js

@@ -0,0 +1,19 @@
+import { computed } from "vue";
+import { countValues } from "./tableFilter.js";
+function useTableFacets(options) {
+  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) => columns.value.get(key)?.distinct.value ?? [],
+    counts: (key) => columns.value.get(key)?.counts.value
+  };
+}
+export {
+  useTableFacets
+};

package/dist/components/textSplit.d.ts

@@ -0,0 +1,17 @@
+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 declare function splitText(text: string, by: "word" | "letter"): TextPiece[];
+/** Keys of the words in `pieces`. */
+export declare function wordKeys(pieces: TextPiece[]): Set<string>;

package/dist/components/textSplit.js

@@ -0,0 +1,24 @@
+import { graphemes } from "./scramble.js";
+function splitText(text, by) {
+  const pieces = [];
+  const seen = /* @__PURE__ */ new Map();
+  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;
+}
+function wordKeys(pieces) {
+  return new Set(pieces.filter((p) => p.kind === "word").map((p) => p.key));
+}
+export {
+  splitText,
+  wordKeys
+};

package/dist/components/timeSpan.d.ts

@@ -0,0 +1,78 @@
+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 declare const DEFAULT_UNIT_LABELS: TimeUnitLabels;
+/**
+ * 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";
+/** Splits a span into calendar-free parts. Negative spans count as zero. */
+export declare function splitTime(ms: number): TimeSplit;
+/** 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 declare function ceilToSecond(ms: number): number;
+/** Which of `clock` and `units` an `auto` span resolves to. */
+export declare function resolveFormat(ms: number, format: TimeFormat): "clock" | "units";
+/**
+ * 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 declare function timeParts(ms: number, format?: TimeFormat, labels?: TimeUnitLabels, places?: number): TimePart[];
+/** Pads a part's number the way the clock prints it. */
+export declare function padPart(part: Pick<TimePart, "value" | "pad">): string;
+/** The span as one string — for titles, aria text and anything not animated. */
+export declare function formatTime(ms: number, format?: TimeFormat, labels?: TimeUnitLabels, places?: number): string;
+/**
+ * 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 declare function formatElapsed(ms: number, labels?: TimeUnitLabels): string;
+/**
+ * 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 declare function msToNextSecond(remaining: number): number;
+/**
+ * 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 declare const DEFAULT_MILESTONES: number[];
+export declare function crossedMilestone(before: number, after: number, milestones?: readonly number[]): number | null;
+/** A date-ish input as epoch milliseconds, or NaN when it is not one. */
+export declare function toEpoch(value: Date | string | number | null | undefined): number;

package/dist/components/timeSpan.js

@@ -0,0 +1,85 @@
+const DEFAULT_UNIT_LABELS = { d: "d", h: "h", m: "m", s: "s" };
+const SECOND = 1e3;
+const MINUTE = 60 * SECOND;
+const HOUR = 60 * MINUTE;
+const DAY = 24 * HOUR;
+function splitTime(ms) {
+  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
+  };
+}
+function ceilToSecond(ms) {
+  if (!Number.isFinite(ms) || ms <= 0) return 0;
+  return Math.ceil(ms / SECOND) * SECOND;
+}
+function resolveFormat(ms, format) {
+  if (format !== "auto") return format;
+  return ms >= HOUR ? "units" : "clock";
+}
+function timeParts(ms, format = "auto", labels = DEFAULT_UNIT_LABELS, places = 2) {
+  const t = splitTime(ms);
+  if (resolveFormat(ms, format) === "clock") {
+    const hours = t.days * 24 + t.hours;
+    const parts = [];
+    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 = [["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)).filter(([, v], i) => i === 0 || v > 0).map(([unit, value]) => ({ unit, value, pad: 1, after: labels[unit] }));
+}
+function padPart(part) {
+  return String(part.value).padStart(part.pad, "0");
+}
+function formatTime(ms, format = "auto", labels = DEFAULT_UNIT_LABELS, places = 2) {
+  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(" ");
+}
+function formatElapsed(ms, labels = DEFAULT_UNIT_LABELS) {
+  if (!Number.isFinite(ms) || ms < 0) return "";
+  if (ms < SECOND) return `${Math.round(ms)}ms`;
+  return formatTime(ms, "units", labels);
+}
+function msToNextSecond(remaining) {
+  if (!Number.isFinite(remaining) || remaining <= 0) return SECOND;
+  const rest = remaining % SECOND;
+  return rest === 0 ? SECOND : rest;
+}
+const DEFAULT_MILESTONES = [36e5, 18e5, 6e5, 3e5, 6e4, 3e4, 1e4];
+function crossedMilestone(before, after, milestones = DEFAULT_MILESTONES) {
+  if (!(after < before)) return null;
+  let hit = null;
+  for (const mark of milestones) {
+    if (before > mark && after <= mark) hit = hit === null ? mark : Math.min(hit, mark);
+  }
+  return hit;
+}
+function toEpoch(value) {
+  if (value === null || value === void 0 || value === "") return Number.NaN;
+  if (value instanceof Date) return value.getTime();
+  if (typeof value === "number") return value;
+  return new Date(value).getTime();
+}
+export {
+  DEFAULT_MILESTONES,
+  DEFAULT_UNIT_LABELS,
+  ceilToSecond,
+  crossedMilestone,
+  formatElapsed,
+  formatTime,
+  msToNextSecond,
+  padPart,
+  resolveFormat,
+  splitTime,
+  timeParts,
+  toEpoch
+};

package/dist/components/tone.d.ts

@@ -0,0 +1,43 @@
+/** 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 declare const TONE_ALIASES: Readonly<Record<ToneName, Tone>>;
+/** 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.
+     */
+    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 declare const TONES: Readonly<Record<Tone, ToneLook>>;
+/**
+ * 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 declare function toneOf(name: string | null | undefined, fallback?: Tone): Tone;
+/** How a tone is painted, by any of its names. */
+export declare function toneLook(name: string | null | undefined, fallback?: Tone): ToneLook;