@leavepulse/ui 0.68.0 → 0.70.0

package/dist/components/masonry.js

@@ -0,0 +1,40 @@
+function masonryColumnCount(width, options) {
+  const { columns, minColumnWidth, maxColumns, gap } = options;
+  if (typeof columns === "number") return Math.max(1, Math.floor(columns));
+  if (columns) {
+    let picked = 1;
+    let best = -Infinity;
+    for (const [min, count] of Object.entries(columns)) {
+      const at = Number(min);
+      if (width >= at && at > best) {
+        best = at;
+        picked = count;
+      }
+    }
+    return Math.max(1, Math.floor(picked));
+  }
+  const fit = Math.floor((width + gap) / (Math.max(1, minColumnWidth) + gap));
+  return Math.max(1, Math.min(fit, maxColumns ?? Infinity));
+}
+function placeMasonry(heights, count, width, gap) {
+  const columns = Math.max(1, count);
+  const columnWidth = Math.max(0, (width - gap * (columns - 1)) / columns);
+  const bottoms = new Array(columns).fill(0);
+  const x = [];
+  const y = [];
+  const column = [];
+  for (const height of heights) {
+    let shortest = 0;
+    for (let c = 1; c < columns; c += 1) if (bottoms[c] < bottoms[shortest] - 0.5) shortest = c;
+    x.push(shortest * (columnWidth + gap));
+    y.push(bottoms[shortest]);
+    column.push(shortest);
+    bottoms[shortest] = bottoms[shortest] + Math.max(0, height) + gap;
+  }
+  const tallest = Math.max(0, ...bottoms);
+  return { x, y, column, columnWidth, height: heights.length ? tallest - gap : 0 };
+}
+export {
+  masonryColumnCount,
+  placeMasonry
+};

package/dist/components/menuWhen.js

@@ -1,5 +1,5 @@
 import { defineComponent, h } from "vue";
-import { _ as _sfc_main } from "../chunks/LpContextMenu-CRnjoqSt.js";
+import { _ as _sfc_main } from "../chunks/LpContextMenu-COwOwRgI.js";
 const MenuWhen = defineComponent({
   name: "MenuWhen",
   inheritAttrs: false,

package/dist/components/meter.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The semantic tones a meter speaks in. They name what the reading MEANS, not
+ * which colour it is: a theme decides the colour, and `ok` stays the "fine"
+ * colour whatever that happens to be.
+ */
+export type MeterTone = "ok" | "warning" | "danger" | "brand" | "neutral";
+/** One step of a scale: from `at` (in the meter's own units) upward, `tone`. */
+export interface MeterThreshold {
+    at: number;
+    tone: MeterTone;
+}
+/** The solid colour of a tone, as a CSS value a style or an SVG stroke takes. */
+export declare const TONE_COLOR: Record<MeterTone, string>;
+/** The tinted background of a tone, for pills and highlighted rows. */
+export declare const TONE_SOFT: Record<MeterTone, string>;
+/**
+ * Where `value` sits between `min` and `max`, as 0–1. An empty or inverted
+ * range (no limit known yet) reads as empty rather than as NaN or Infinity,
+ * which would otherwise reach an SVG attribute and draw nothing at all.
+ */
+export declare function meterFraction(value: number, min: number, max: number): number;
+/**
+ * The capacity scale every finite resource is read against: comfortable well
+ * past half, uncomfortable in the last fifth, urgent in the last tenth. The
+ * same breakpoints LpProgress's `auto` tone uses, so the two never disagree
+ * about one disk.
+ */
+export declare function capacityThresholds(min: number, max: number, warnAt?: number, dangerAt?: number): MeterThreshold[];
+/**
+ * The tone a reading earns on a scale. Thresholds are steps, not bands: each
+ * one holds from its `at` until the next, and below the first the reading is
+ * `base`. Sorted here, so a caller can list them in whatever order reads best.
+ *
+ * Steps go either way, which is what lets one shape describe both "higher is
+ * worse" (load: ok → warning → danger) and "higher is better" (a score:
+ * danger from 0, warning from 50, ok from 80).
+ */
+export declare function toneAt(value: number, thresholds: readonly MeterThreshold[], base?: MeterTone): MeterTone;
+/**
+ * The track a bar meter fills, shared so LpProgress's bar and LpQuota's read as
+ * one family. Each adds its own clipping: a progress bar clips its fill, a
+ * quota lets its limit mark stand out past the track.
+ */
+export declare const METER_TRACK = "h-1.5 w-full rounded-pill bg-surface-soft";
+/** The row above a bar: what is measured at the start, the reading at the end. Each sets its own size and gap. */
+export declare const METER_HEADER = "flex items-baseline justify-between";
+/**
+ * A point on a circle, with the angle in degrees clockwise from twelve
+ * o'clock — the way a dial is read, so -90 is nine o'clock and 90 is three.
+ */
+export declare function polar(cx: number, cy: number, r: number, deg: number): {
+    x: number;
+    y: number;
+};
+/** An SVG path along a circle from one angle to another, clockwise. */
+export declare function arcPath(cx: number, cy: number, r: number, from: number, to: number): string;
+/**
+ * The sweep of each gauge shape, as [start, end] angles. A semicircle reads
+ * left to right across the top; the full dial opens at the bottom, a 270°
+ * sweep, because a closed circle has no visible start or end and that is
+ * LpProgress's ring, a different thing (progress toward done, not a reading
+ * within a range).
+ */
+export declare const GAUGE_SWEEP: Record<"semi" | "full", readonly [number, number]>;

package/dist/components/meter.js

@@ -0,0 +1,53 @@
+import { TONES, TONE_ALIASES } from "./tone.js";
+const METER_TONES = ["ok", "warning", "danger", "brand", "neutral"];
+const byMeterTone = (pick) => Object.fromEntries(METER_TONES.map((t) => [t, pick(TONES[TONE_ALIASES[t]])]));
+const TONE_COLOR = byMeterTone((look) => look.color);
+const TONE_SOFT = byMeterTone((look) => look.soft);
+function meterFraction(value, min, max) {
+  const span = max - min;
+  if (!(span > 0) || !Number.isFinite(value)) return 0;
+  return Math.max(0, Math.min(1, (value - min) / span));
+}
+function capacityThresholds(min, max, warnAt = 0.8, dangerAt = 0.9) {
+  const span = max - min;
+  return [
+    { at: min + span * warnAt, tone: "warning" },
+    { at: min + span * dangerAt, tone: "danger" }
+  ];
+}
+function toneAt(value, thresholds, base = "ok") {
+  let tone = base;
+  for (const step of [...thresholds].sort((a, b) => a.at - b.at)) {
+    if (value >= step.at) tone = step.tone;
+  }
+  return tone;
+}
+const METER_TRACK = "h-1.5 w-full rounded-pill bg-surface-soft";
+const METER_HEADER = "flex items-baseline justify-between";
+function polar(cx, cy, r, deg) {
+  const rad = deg * Math.PI / 180;
+  return { x: cx + r * Math.sin(rad), y: cy - r * Math.cos(rad) };
+}
+function arcPath(cx, cy, r, from, to) {
+  const a = polar(cx, cy, r, from);
+  const b = polar(cx, cy, r, to);
+  const large = to - from > 180 ? 1 : 0;
+  const f = (n) => Number(n.toFixed(3));
+  return `M ${f(a.x)} ${f(a.y)} A ${f(r)} ${f(r)} 0 ${large} 1 ${f(b.x)} ${f(b.y)}`;
+}
+const GAUGE_SWEEP = {
+  semi: [-90, 90],
+  full: [-135, 135]
+};
+export {
+  GAUGE_SWEEP,
+  METER_HEADER,
+  METER_TRACK,
+  TONE_COLOR,
+  TONE_SOFT,
+  arcPath,
+  capacityThresholds,
+  meterFraction,
+  polar,
+  toneAt
+};

package/dist/components/otp.d.ts

@@ -4,4 +4,4 @@ export declare function joinCells(cells: OtpCells): string;
 /** Cells for a code given from outside, one character each. */
 export declare function splitCode(code: string | undefined, length: number): string[];
 export declare function upperCells<T extends OtpCells>(cells: T): T;
-export declare function groupBreaks(length: number, group: number | undefined): Set<number>;
+export declare function groupBreaks(length: number, group: number | number[] | undefined): Set<number>;

package/dist/components/otp.js

@@ -1,3 +1,4 @@
+import { groupCode } from "./fieldText.js";
 function joinCells(cells) {
   return Array.from(cells, (c) => c === void 0 ? "" : String(c)).join("");
 }
@@ -14,8 +15,12 @@ function upperCells(cells) {
 }
 function groupBreaks(length, group) {
   const breaks = /* @__PURE__ */ new Set();
-  if (!group || group < 1 || group >= length) return breaks;
-  for (let i = group; i < length; i += group) breaks.add(i - 1);
+  if (Array.isArray(group) ? !group.some((n) => n > 0) : !group || group < 1) return breaks;
+  let at = 0;
+  for (const block of groupCode("x".repeat(Math.max(0, length)), group)) {
+    at += block.length;
+    if (at < length) breaks.add(at - 1);
+  }
   return breaks;
 }
 export {

package/dist/components/pipeline.d.ts

@@ -0,0 +1,55 @@
+export type StepStatus = "pending" | "running" | "success" | "failed" | "skipped" | "cancelled";
+export interface PipelineStep {
+    label: string;
+    /** Stable id: what `expanded` and the `step` slot address. Defaults to the index. */
+    key?: string;
+    status: StepStatus;
+    /** A line under the label: the command, the host, the reason it was skipped. */
+    description?: string;
+    /** Replaces the glyph while the step is pending (a step that is "deploy" more than "3"). */
+    icon?: string;
+    /**
+     * Time the step took, in ms. When it is not known yet, `startedAt` (and
+     * `finishedAt`) let the pipeline work it out — and keep a running step's
+     * clock ticking without the app re-sending it every second.
+     */
+    duration?: number;
+    startedAt?: Date | string | number;
+    finishedAt?: Date | string | number;
+    /** Jobs inside this one, shown when the step is expanded (vertical layout). */
+    steps?: PipelineStep[];
+}
+/** Done, one way or another: nothing more will happen to the step. */
+export declare function isSettled(status: StepStatus): boolean;
+/**
+ * Whether the line leaving a step is drawn as travelled. A step that passed
+ * or was skipped hands over to the next; one that failed or was cancelled is
+ * where the run stopped, so the line after it stays empty — the break in the
+ * line is the place to look.
+ */
+export declare function connectorFilled(status: StepStatus): boolean;
+/**
+ * The step a viewer is following: the running one, else the first that has
+ * not run yet after something has, else the last failure. -1 when the run has
+ * not started or is cleanly over.
+ */
+export declare function currentStepIndex(steps: readonly Pick<PipelineStep, "status">[]): number;
+/**
+ * What the run amounts to. A failure anywhere outranks everything (one red
+ * job fails the build), then work in progress, then a cancellation; a run of
+ * passes and skips is a pass. Nothing started is pending.
+ */
+export declare function overallStatus(steps: readonly Pick<PipelineStep, "status">[]): StepStatus;
+/**
+ * Ms a step has taken, as of `now`. An explicit `duration` wins; otherwise
+ * from `startedAt` to `finishedAt`, or to `now` while it is still running.
+ * null when there is nothing to say (pending, or no times given).
+ */
+export declare function stepElapsed(step: PipelineStep, now: number): number | null;
+/** "2/5": finished children out of all, for a step whose inside is folded away. */
+export declare function childProgress(step: PipelineStep): {
+    done: number;
+    total: number;
+} | null;
+/** The key a step is addressed by. */
+export declare function stepKey(step: Pick<PipelineStep, "key">, index: number): string;

package/dist/components/pipeline.js

@@ -0,0 +1,51 @@
+import { toEpoch } from "./timeSpan.js";
+function isSettled(status) {
+  return status !== "pending" && status !== "running";
+}
+function connectorFilled(status) {
+  return status === "success" || status === "skipped";
+}
+function currentStepIndex(steps) {
+  const running = steps.findIndex((s) => s.status === "running");
+  if (running !== -1) return running;
+  const failed = steps.findIndex((s) => s.status === "failed");
+  if (failed !== -1) return failed;
+  const started = steps.some((s) => isSettled(s.status));
+  if (!started) return -1;
+  return steps.findIndex((s) => s.status === "pending");
+}
+function overallStatus(steps) {
+  if (steps.length === 0) return "pending";
+  const has = (s) => steps.some((step) => step.status === s);
+  if (has("failed")) return "failed";
+  if (has("running")) return "running";
+  if (has("cancelled")) return "cancelled";
+  if (steps.every((s) => s.status === "skipped")) return "skipped";
+  if (steps.every((s) => s.status === "success" || s.status === "skipped")) return "success";
+  if (steps.some((s) => isSettled(s.status))) return "running";
+  return "pending";
+}
+function stepElapsed(step, now) {
+  if (typeof step.duration === "number" && Number.isFinite(step.duration)) return Math.max(0, step.duration);
+  const start = toEpoch(step.startedAt);
+  if (Number.isNaN(start)) return null;
+  const end = toEpoch(step.finishedAt);
+  if (!Number.isNaN(end)) return Math.max(0, end - start);
+  return step.status === "running" ? Math.max(0, now - start) : null;
+}
+function childProgress(step) {
+  if (!step.steps?.length) return null;
+  return { done: step.steps.filter((s) => isSettled(s.status)).length, total: step.steps.length };
+}
+function stepKey(step, index) {
+  return step.key ?? String(index);
+}
+export {
+  childProgress,
+  connectorFilled,
+  currentStepIndex,
+  isSettled,
+  overallStatus,
+  stepElapsed,
+  stepKey
+};

package/dist/components/quota.d.ts

@@ -0,0 +1,57 @@
+import { type MeterTone } from "./meter";
+/** One part of what is used, for a stacked bar ("Images 12 GB, Backups 30 GB"). */
+export interface QuotaPart {
+    label: string;
+    value: number;
+    /** Any CSS colour. Unset parts take the chart palette in order, like LpChart's series (minus danger). */
+    color?: string;
+}
+/**
+ * How amounts are written. `"bytes"` scales to the largest whole unit (1 536 →
+ * 1.5 KB) in binary steps, the way storage limits are sold and shown; any
+ * other string is a plain suffix ("seats", "req/min"); a function says it its
+ * own way.
+ */
+export type QuotaUnit = "bytes" | string | ((value: number) => string);
+export interface QuotaState {
+    /** Share of the limit used, 0–1 and beyond: 1.25 is a quarter over. */
+    ratio: number;
+    /** What is left; zero once over. */
+    remaining: number;
+    /** By how much the limit is exceeded; zero within it. */
+    over: number;
+    /** False when there is no limit to measure against (unset, zero, Infinity). */
+    limited: boolean;
+    tone: MeterTone;
+}
+/**
+ * Where a quota stands. Thresholds are shares of the limit, read on the same
+ * capacity scale (and with the same defaults) as LpProgress's `auto` tone and
+ * LpGauge, so a quota and a gauge of one disk turn red together; anything past
+ * the limit is danger whatever they say, because "over" is the one state a
+ * quota must never paint as merely amber.
+ */
+export declare function quotaState(used: number, limit: number | null | undefined, warnAt?: number, dangerAt?: number): QuotaState;
+/**
+ * An amount in its unit, locale-aware. Bytes go through `formatBytes`, whose
+ * unit names come from Intl, so a Russian app reads "1,5 ГБ" without a
+ * translation table of its own.
+ */
+export declare function formatAmount(value: number, unit?: QuotaUnit, locale?: string): string;
+export interface QuotaSegment extends QuotaPart {
+    color: string;
+    /** Share of the bar's width, 0–1. */
+    share: number;
+}
+/**
+ * The parts laid out along the bar. Within the limit the bar's width IS the
+ * limit, so a part's share is its value over the limit and the rest of the
+ * track is what remains. Over it, the bar stretches to hold everything used and
+ * the limit becomes a mark partway along (`limitAt`), so the overflow reads as
+ * the part of the bar beyond the line rather than as a bar that simply stopped
+ * at full.
+ */
+export declare function quotaSegments(parts: readonly QuotaPart[], limit: number | null | undefined): {
+    segments: QuotaSegment[];
+    limitAt: number | null;
+};

package/dist/components/quota.js

@@ -0,0 +1,40 @@
+import { CHART_PALETTE } from "./chart.js";
+import { formatBytes } from "./format.js";
+import { toneAt, capacityThresholds } from "./meter.js";
+function quotaState(used, limit, warnAt = 0.8, dangerAt = 0.9) {
+  const safeUsed = Number.isFinite(used) ? Math.max(0, used) : 0;
+  const limited = limit != null && Number.isFinite(limit) && limit > 0;
+  if (!limited) return { ratio: 0, remaining: Infinity, over: 0, limited, tone: "ok" };
+  const ratio = safeUsed / limit;
+  const tone = ratio > 1 ? "danger" : toneAt(ratio, capacityThresholds(0, 1, warnAt, dangerAt));
+  return {
+    ratio,
+    remaining: Math.max(0, limit - safeUsed),
+    over: Math.max(0, safeUsed - limit),
+    limited,
+    tone
+  };
+}
+function formatAmount(value, unit, locale) {
+  if (typeof unit === "function") return unit(value);
+  if (unit === "bytes") return formatBytes(Math.max(0, value), locale);
+  const number = new Intl.NumberFormat(locale, { maximumFractionDigits: value < 10 ? 1 : 0 }).format(value);
+  return unit ? `${number} ${unit}` : number;
+}
+const PART_PALETTE = CHART_PALETTE.filter((c) => !c.includes("danger"));
+function quotaSegments(parts, limit) {
+  const total = parts.reduce((sum, p) => sum + Math.max(0, p.value), 0);
+  const limited = limit != null && Number.isFinite(limit) && limit > 0;
+  const scale = limited ? Math.max(limit, total) : total;
+  const segments = parts.map((p, i) => ({
+    ...p,
+    color: p.color ?? PART_PALETTE[i % PART_PALETTE.length],
+    share: scale > 0 ? Math.max(0, p.value) / scale : 0
+  }));
+  return { segments, limitAt: limited && total > limit ? limit / total : null };
+}
+export {
+  formatAmount,
+  quotaSegments,
+  quotaState
+};

package/dist/components/relativeTime.d.ts

@@ -0,0 +1,24 @@
+export type RelativeUnit = "second" | "minute" | "hour" | "day" | "week" | "month" | "year";
+export interface RelativeTimeOptions {
+    locale?: string;
+    /** Intl's width: `long` "3 minutes ago", `short` "3 min. ago", `narrow` "3m ago". */
+    style?: Intl.RelativeTimeFormatStyle;
+    /**
+     * Under this many ms either side of now, say "now" instead of counting
+     * seconds. Counting seconds is churn nobody reads; a countdown that needs
+     * them wants a timer, not this.
+     */
+    nowWithin?: number;
+}
+export interface RelativeTime {
+    text: string;
+    unit: RelativeUnit;
+    /** Signed: negative is the past. */
+    value: number;
+    /**
+     * Milliseconds until `text` would read differently. A ticker sleeps this
+     * long instead of waking every second for a date three weeks away.
+     */
+    refreshIn: number;
+}
+export declare function formatRelativeTime(date: Date | string | number, now?: number, options?: RelativeTimeOptions): RelativeTime;

package/dist/components/relativeTime.js

@@ -0,0 +1,56 @@
+import { toEpoch } from "./timeSpan.js";
+const SECOND = 1e3;
+const MINUTE = 60 * SECOND;
+const HOUR = 60 * MINUTE;
+const DAY = 24 * HOUR;
+const WEEK = 7 * DAY;
+const MONTH = 30.4375 * DAY;
+const YEAR = 365.25 * DAY;
+const SCALE = [
+  { unit: "second", ms: SECOND, until: 45 * SECOND },
+  { unit: "minute", ms: MINUTE, until: 45 * MINUTE },
+  { unit: "hour", ms: HOUR, until: 22 * HOUR },
+  { unit: "day", ms: DAY, until: 6.5 * DAY },
+  { unit: "week", ms: WEEK, until: 26 * DAY },
+  { unit: "month", ms: MONTH, until: 320 * DAY },
+  { unit: "year", ms: YEAR, until: Infinity }
+];
+const formatters = /* @__PURE__ */ new Map();
+function formatterFor(locale, style) {
+  const key = `${locale ?? ""}|${style}`;
+  let f = formatters.get(key);
+  if (!f) {
+    f = new Intl.RelativeTimeFormat(locale, { numeric: "auto", style });
+    formatters.set(key, f);
+  }
+  return f;
+}
+const MAX_REFRESH = HOUR;
+const MIN_REFRESH = SECOND;
+function formatRelativeTime(date, now = Date.now(), options = {}) {
+  const { locale, style = "long", nowWithin = 45 * SECOND } = options;
+  const at = toEpoch(date);
+  const fmt = formatterFor(locale, style);
+  if (!Number.isFinite(at)) return { text: "", unit: "second", value: 0, refreshIn: MAX_REFRESH };
+  const diff = at - now;
+  const abs = Math.abs(diff);
+  if (abs < nowWithin) {
+    const refreshIn2 = diff >= 0 ? diff + nowWithin : nowWithin - abs;
+    return { text: fmt.format(0, "second"), unit: "second", value: 0, refreshIn: clampRefresh(refreshIn2) };
+  }
+  const index = SCALE.findIndex((s) => abs < s.until);
+  const step = SCALE[index];
+  const count = Math.max(1, Math.round(abs / step.ms));
+  const value = diff < 0 ? -count : count;
+  const units = abs / step.ms;
+  const boundary = diff < 0 ? (Math.floor(units + 0.5) + 0.5) * step.ms : (Math.ceil(units - 0.5) - 0.5) * step.ms;
+  const unitChange = diff < 0 ? step.until - abs : index > 0 ? abs - SCALE[index - 1].until : Infinity;
+  const refreshIn = Math.min(diff < 0 ? boundary - abs : abs - boundary, unitChange);
+  return { text: fmt.format(value, step.unit), unit: step.unit, value, refreshIn: clampRefresh(refreshIn) };
+}
+function clampRefresh(ms) {
+  return Math.min(MAX_REFRESH, Math.max(MIN_REFRESH, Math.ceil(ms)));
+}
+export {
+  formatRelativeTime
+};

package/dist/components/reveal.d.ts

@@ -0,0 +1,18 @@
+export type RevealPreset = "fade" | "rise" | "blur" | "scale";
+export type RevealDirection = "up" | "down" | "left" | "right";
+/**
+ * The hidden state an entrance starts from; the end state is always "as laid
+ * out", so the keyframes only describe where the content comes FROM.
+ *
+ * `direction` is the way the content travels: `up` starts below and rises.
+ * Every preset fades — motion without a fade reads as a layout jump.
+ */
+export declare function revealFrom(preset: RevealPreset, direction: RevealDirection, distance: number): Keyframe;
+/** The resting state matching `revealFrom`'s properties. */
+export declare function revealTo(from: Keyframe): Keyframe;
+/**
+ * Delay of the `index`-th child. The steps stop growing after `cap` children:
+ * a list of eighty would otherwise take seconds to finish arriving, and the
+ * last rows would still be invisible when the user starts reading them.
+ */
+export declare function staggerDelay(index: number, delay: number, stagger: number, cap?: number): number;

package/dist/components/reveal.js

@@ -0,0 +1,32 @@
+function revealFrom(preset, direction, distance) {
+  const offset = (d) => ({
+    up: `translate3d(0, ${d}px, 0)`,
+    down: `translate3d(0, ${-d}px, 0)`,
+    left: `translate3d(${d}px, 0, 0)`,
+    right: `translate3d(${-d}px, 0, 0)`
+  })[direction];
+  switch (preset) {
+    case "fade":
+      return { opacity: 0 };
+    case "rise":
+      return { opacity: 0, transform: offset(distance) };
+    case "blur":
+      return { opacity: 0, filter: "blur(8px)", transform: offset(distance / 2) };
+    case "scale":
+      return { opacity: 0, transform: "scale(0.94)" };
+  }
+}
+function revealTo(from) {
+  const to = { opacity: 1 };
+  if ("transform" in from) to.transform = "none";
+  if ("filter" in from) to.filter = "blur(0px)";
+  return to;
+}
+function staggerDelay(index, delay, stagger, cap = 10) {
+  return delay + Math.min(Math.max(0, index), cap) * Math.max(0, stagger);
+}
+export {
+  revealFrom,
+  revealTo,
+  staggerDelay
+};

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
+};