@elabs-ai/components-process 4.2.0 → 5.1.0

package/src/process-replay/process-replay.tsx

@@ -0,0 +1,285 @@
+"use client";
+
+/**
+ * ProcessReplay — cases replayed as tokens moving over the process map (RM-065).
+ *
+ * A composition, not a new map: `ProcessMap` (read-only — no `onSelect`), with the tokens
+ * handed to its own transition edges through {@link ProcessReplayTokensContext}. The edges
+ * draw them with `@elabs-ai/components-flow`'s `FlowEdgeTokens`, which owns every SVG mark;
+ * this component owns only the clock.
+ *
+ * - **Time.** `replayTimeline` buckets the log; the playhead is a controllable `time`, driven
+ *   by a `requestAnimationFrame` loop while `playing`. At 1× the whole timeline plays in
+ *   {@link REPLAY_PLAYBACK_MS}. Reaching the end pauses.
+ * - **Congestion without colour.** One token per in-flight case, so a busy edge carries more
+ *   tokens; each token's radius grows with its edge's congestion in the current bucket
+ *   (`replayTokenRadius`). {@link CongestionHeat} states the ranking in words beside the map.
+ *   The weighted-edge value ramp is deliberately not used.
+ * - **Motion.** Never starts on its own under reduced motion: `defaultPlaying` and a
+ *   parent's `playing` are both held until the reader presses play. The tokens then jump
+ *   rather than glide (the flow primitive drops its transition).
+ * - **Text alternative.** The tokens are `aria-hidden`. One polite live region announces the
+ *   playhead and the in-flight case count whenever the replay is paused or scrubbed — not
+ *   frame by frame while it plays.
+ */
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  type HTMLAttributes,
+} from "react";
+import { StatePanel } from "@elabs-ai/components-ui";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+import { useReducedMotion } from "@elabs-ai/components-tokens";
+import type { FlowEdgeToken, FlowLayoutDirection } from "@elabs-ai/components-flow";
+import { replayFrameAt, replayTimeline, replayTokenRadius } from "../core/replay-timeline";
+import type { EventLog, ProcessGraph } from "../core/types";
+import type { ProcessMetricSpec } from "../process-map/map-model";
+import { ProcessMap } from "../process-map/process-map";
+import { fillLabel } from "../variant-explorer/variant-explorer-model";
+import { CongestionHeat } from "./congestion-heat";
+import { ReplayControls } from "./replay-controls";
+import {
+  PROCESS_REPLAY_DEFAULT_LABELS,
+  useReplayTimeFormatter,
+  type ProcessReplayLabels,
+} from "./replay-format";
+import { ProcessReplayTokensContext, type ProcessReplayTokens } from "./replay-tokens-context";
+import { useControllableValue } from "./use-controllable-value";
+
+/** Wall-clock length of a full replay at 1×, in ms. */
+export const REPLAY_PLAYBACK_MS = 30_000;
+
+/** The metric the map paints when none is given: case frequency on both marks. */
+export const PROCESS_REPLAY_DEFAULT_METRIC: ProcessMetricSpec = Object.freeze({
+  node: "absolute_case",
+  edge: "absolute",
+}) as ProcessMetricSpec;
+
+/** Props for {@link ProcessReplay}. `onSelect` is not offered: the map is read-only. */
+export interface ProcessReplayProps extends HTMLAttributes<HTMLDivElement> {
+  /** The discovered graph to replay over. */
+  graph: ProcessGraph;
+  /** The log the graph came from — tokens need per-case timing, not just the aggregate. */
+  log: EventLog;
+  /** Align every case's start to `t = 0` instead of the wall clock. @default false */
+  synchronizedStart?: boolean;
+  /** Bucket width in ms for congestion. @default the log span / 300 */
+  bucketMs?: number;
+  /** Which readings the nodes and edges print. @default case frequency */
+  metric?: ProcessMetricSpec;
+  /** @default "TB" */
+  direction?: FlowLayoutDirection;
+  /** Controlled playing state. Held while reduced motion is on until the reader presses play. */
+  playing?: boolean;
+  /** Initial playing state when uncontrolled. Ignored under reduced motion. @default false */
+  defaultPlaying?: boolean;
+  onPlayingChange?: (playing: boolean) => void;
+  /** Controlled playhead, ms relative to the timeline origin. */
+  time?: number;
+  /** @default 0 */
+  defaultTime?: number;
+  onTimeChange?: (time: number) => void;
+  /** Controlled playback multiplier. */
+  speed?: number;
+  /** @default 1 */
+  defaultSpeed?: number;
+  onSpeedChange?: (speed: number) => void;
+  /** How many transitions the congestion list ranks. @default 5 */
+  congestionLimit?: number;
+  /** No log yet. Renders the loading panel. */
+  loading?: boolean;
+  /** Override any user-visible string. */
+  labels?: Partial<ProcessReplayLabels>;
+}
+
+/**
+ * The process replay.
+ *
+ * @example
+ * ```tsx
+ * const graph = useMemo(() => discoverGraph(log), [log]);
+ * <ProcessReplay graph={graph} log={log} synchronizedStart />
+ * ```
+ */
+export const ProcessReplay = forwardRef<HTMLDivElement, ProcessReplayProps>(function ProcessReplay(
+  {
+    graph,
+    log,
+    synchronizedStart = false,
+    bucketMs,
+    metric = PROCESS_REPLAY_DEFAULT_METRIC,
+    direction,
+    playing: playingProp,
+    defaultPlaying = false,
+    onPlayingChange,
+    time: timeProp,
+    defaultTime = 0,
+    onTimeChange,
+    speed: speedProp,
+    defaultSpeed = 1,
+    onSpeedChange,
+    congestionLimit = 5,
+    loading = false,
+    labels: labelOverrides,
+    className,
+    ...props
+  },
+  ref,
+) {
+  const labels = useMemo<ProcessReplayLabels>(
+    () => ({ ...PROCESS_REPLAY_DEFAULT_LABELS, ...labelOverrides }),
+    [labelOverrides],
+  );
+  const reducedMotion = useReducedMotion();
+  const timeline = useMemo(
+    () => replayTimeline(log, { bucketMs, synchronizedStart }),
+    [log, bucketMs, synchronizedStart],
+  );
+  const { duration } = timeline;
+
+  const [playingRequested, setPlaying] = useControllableValue(
+    playingProp,
+    defaultPlaying,
+    onPlayingChange,
+  );
+  const [rawTime, setTime] = useControllableValue(timeProp, defaultTime, onTimeChange);
+  const [speed, setSpeed] = useControllableValue(speedProp, defaultSpeed, onSpeedChange);
+  const time = Math.min(Math.max(rawTime, 0), duration);
+
+  // Reduced motion: nothing moves until the reader asks for it with the play button.
+  const [readerStarted, setReaderStarted] = useState(false);
+  const playing = playingRequested && duration > 0 && (!reducedMotion || readerStarted);
+
+  const timeRef = useRef(time);
+  useLayoutEffect(() => {
+    timeRef.current = time;
+  });
+
+  useEffect(() => {
+    if (!playing) return;
+    let handle = 0;
+    let last: number | null = null;
+    const tick = (now: number) => {
+      if (last !== null) {
+        const advance = ((now - last) * duration * speed) / REPLAY_PLAYBACK_MS;
+        const next = Math.min(timeRef.current + advance, duration);
+        timeRef.current = next;
+        setTime(next);
+        if (next >= duration) {
+          setPlaying(false);
+          return;
+        }
+      }
+      last = now;
+      handle = requestAnimationFrame(tick);
+    };
+    handle = requestAnimationFrame(tick);
+    return () => cancelAnimationFrame(handle);
+  }, [playing, duration, speed, setTime, setPlaying]);
+
+  const handlePlayingChange = useCallback(
+    (next: boolean) => {
+      if (next) {
+        setReaderStarted(true);
+        if (timeRef.current >= duration) setTime(0);
+      }
+      setPlaying(next);
+    },
+    [duration, setPlaying, setTime],
+  );
+
+  const frame = useMemo(() => replayFrameAt(timeline, time), [timeline, time]);
+  const tokensByEdge = useMemo<ProcessReplayTokens>(() => {
+    const map = new Map<string, FlowEdgeToken[]>();
+    for (const token of frame.tokens) {
+      let list = map.get(token.edgeId);
+      if (!list) map.set(token.edgeId, (list = []));
+      list.push({
+        id: token.caseId,
+        progress: token.progress,
+        radius: replayTokenRadius(frame.congestion[token.edgeId] ?? 0, timeline.peakCongestion),
+      });
+    }
+    return map;
+  }, [frame, timeline.peakCongestion]);
+
+  const formatTime = useReplayTimeFormatter(timeline, labels.relativeTime);
+  const inFlight = frame.tokens.length;
+
+  // The map element is memoized on its own inputs, so a playhead tick re-renders only the
+  // edges that read the tokens context — never the layout or the model.
+  const map = useMemo(
+    () => <ProcessMap graph={graph} metric={metric} direction={direction} label={labels.map} />,
+    [graph, metric, direction, labels.map],
+  );
+
+  if (loading) {
+    return (
+      <div
+        ref={ref}
+        data-slot="process-replay"
+        data-state="loading"
+        className={className}
+        {...props}
+      >
+        <StatePanel kind="loading" title={labels.loading} />
+      </div>
+    );
+  }
+
+  if (timeline.segments.length === 0 && duration === 0) {
+    return (
+      <div ref={ref} data-slot="process-replay" data-state="empty" className={className} {...props}>
+        <StatePanel kind="empty" title={labels.empty} description={labels.emptyBody} />
+      </div>
+    );
+  }
+
+  return (
+    <div
+      ref={ref}
+      role="region"
+      aria-label={labels.region}
+      data-slot="process-replay"
+      data-state={playing ? "playing" : "paused"}
+      data-synchronized-start={synchronizedStart ? "true" : undefined}
+      className={cn("flex size-full min-h-0 flex-col gap-3", className)}
+      {...props}
+    >
+      <ReplayControls
+        playing={playing}
+        onPlayingChange={handlePlayingChange}
+        time={time}
+        onTimeChange={setTime}
+        duration={duration}
+        step={timeline.bucketMs}
+        speed={speed}
+        onSpeedChange={setSpeed}
+        inFlight={inFlight}
+        formatTime={formatTime}
+        labels={labels}
+      />
+      <p role="status" aria-live="polite" data-slot="process-replay-status" className="sr-only">
+        {playing
+          ? labels.playing
+          : fillLabel(labels.readout, { time: formatTime(time), count: inFlight })}
+      </p>
+      <div className="flex min-h-0 flex-1 flex-col gap-3 lg:flex-row">
+        <div data-slot="process-replay-map" data-in-flight={inFlight} className="min-h-64 flex-1">
+          <ProcessReplayTokensContext value={tokensByEdge}>{map}</ProcessReplayTokensContext>
+        </div>
+        <CongestionHeat
+          timeline={timeline}
+          limit={congestionLimit}
+          labels={labels}
+          className="shrink-0 lg:w-72"
+        />
+      </div>
+    </div>
+  );
+});

package/src/process-replay/replay-controls.tsx

@@ -0,0 +1,147 @@
+"use client";
+
+/**
+ * ReplayControls — the transport bar of `ProcessReplay` (RM-065).
+ *
+ * Presentational and fully controlled: a play/pause button, a time slider and a speed select,
+ * all native-keyboard components from `@elabs-ai/components-ui` (Space/Enter on the button,
+ * arrows/Home/End/PageUp/PageDown on the slider, arrows and typeahead in the select), plus a
+ * visible readout of the playhead and the in-flight case count. The readout is NOT a live
+ * region — `ProcessReplay` owns the one announcement per region.
+ */
+import { forwardRef, useMemo, type HTMLAttributes } from "react";
+import { Pause, Play } from "lucide-react";
+import {
+  Button,
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+  Slider,
+  useLocale,
+} from "@elabs-ai/components-ui";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+import { fillLabel } from "../variant-explorer/variant-explorer-model";
+import { PROCESS_REPLAY_DEFAULT_LABELS, type ProcessReplayLabels } from "./replay-format";
+
+/** The speed multipliers the select offers. */
+export const REPLAY_SPEEDS = Object.freeze([0.5, 1, 2, 4] as const);
+
+/** Props for {@link ReplayControls}. */
+export interface ReplayControlsProps extends HTMLAttributes<HTMLDivElement> {
+  playing: boolean;
+  onPlayingChange: (playing: boolean) => void;
+  /** Playhead, ms relative to the timeline origin. */
+  time: number;
+  onTimeChange: (time: number) => void;
+  /** Timeline length in ms — the slider's maximum. */
+  duration: number;
+  /** Slider step in ms (one bucket). */
+  step: number;
+  speed: number;
+  onSpeedChange: (speed: number) => void;
+  /** Cases in flight at {@link time}. */
+  inFlight: number;
+  /** Formats a playhead for the readout and the slider's value text. */
+  formatTime: (time: number) => string;
+  /** Disable every control (an empty timeline). */
+  disabled?: boolean;
+  labels?: Partial<ProcessReplayLabels>;
+}
+
+/** Play/pause, time slider, speed select and a readout. */
+export const ReplayControls = forwardRef<HTMLDivElement, ReplayControlsProps>(
+  function ReplayControls(
+    {
+      playing,
+      onPlayingChange,
+      time,
+      onTimeChange,
+      duration,
+      step,
+      speed,
+      onSpeedChange,
+      inFlight,
+      formatTime,
+      disabled = false,
+      labels: labelOverrides,
+      className,
+      ...props
+    },
+    ref,
+  ) {
+    const { formatNumber } = useLocale();
+    const labels = useMemo<ProcessReplayLabels>(
+      () => ({ ...PROCESS_REPLAY_DEFAULT_LABELS, ...labelOverrides }),
+      [labelOverrides],
+    );
+    const timeText = formatTime(time);
+    const PlayIcon = playing ? Pause : Play;
+
+    return (
+      <div
+        ref={ref}
+        data-slot="replay-controls"
+        data-playing={playing ? "true" : "false"}
+        className={cn("flex flex-wrap items-center gap-3", className)}
+        {...props}
+      >
+        <Button
+          data-slot="replay-controls-play"
+          variant="outline"
+          size="icon"
+          disabled={disabled}
+          aria-label={playing ? labels.pause : labels.play}
+          onClick={() => onPlayingChange(!playing)}
+        >
+          <PlayIcon aria-hidden="true" />
+        </Button>
+        <Slider
+          data-slot="replay-controls-time"
+          className="min-w-40 flex-1"
+          min={0}
+          max={Math.max(duration, step)}
+          step={step}
+          value={[time]}
+          disabled={disabled}
+          aria-label={labels.time}
+          aria-valuetext={timeText}
+          onValueChange={([next]) => {
+            if (next !== undefined) onTimeChange(Math.min(next, duration));
+          }}
+        />
+        {/* A `SelectTrigger` is full-width by default, which in this wrapping row claimed a
+            line of its own — a speed picker as wide as the map. Its box is the speed, no more. */}
+        <div className="w-24 shrink-0">
+          <Select
+            value={String(speed)}
+            disabled={disabled}
+            onValueChange={(value) => onSpeedChange(Number(value))}
+          >
+            <SelectTrigger
+              data-slot="replay-controls-speed"
+              className="min-w-20"
+              aria-label={labels.speed}
+            >
+              <SelectValue />
+            </SelectTrigger>
+            <SelectContent>
+              {REPLAY_SPEEDS.map((option) => (
+                <SelectItem key={option} value={String(option)}>
+                  {fillLabel(labels.speedOption, { speed: formatNumber(option) })}
+                </SelectItem>
+              ))}
+            </SelectContent>
+          </Select>
+        </div>
+        <p
+          data-slot="replay-controls-readout"
+          className="text-meta text-muted-foreground tabular-nums"
+        >
+          {fillLabel(labels.readout, { time: timeText, count: formatNumber(inFlight) })}
+        </p>
+      </div>
+    );
+  },
+);

package/src/process-replay/replay-format.ts

@@ -0,0 +1,83 @@
+"use client";
+
+/**
+ * Words and time formatting shared by the replay parts (RM-065).
+ */
+import { useCallback } from "react";
+import { useLocale } from "@elabs-ai/components-ui";
+import type { ReplayTimeline } from "../core/replay-timeline";
+import { formatDurationMs } from "../process-map/map-model";
+
+/** Every user-visible string in `ProcessReplay` and its parts. `{…}` are placeholders. */
+export interface ProcessReplayLabels {
+  /** Accessible name of the replay region. */
+  region: string;
+  /** Accessible name of the map canvas. */
+  map: string;
+  play: string;
+  pause: string;
+  /** The time slider. */
+  time: string;
+  /** The speed select. */
+  speed: string;
+  /** `{speed}` — one speed option. */
+  speedOption: string;
+  /** `{time}`, `{count}` — the readout and the paused announcement. */
+  readout: string;
+  /** Announced while the replay runs (the time is not announced frame by frame). */
+  playing: string;
+  /** `{duration}` — a playhead in synchronized-start mode. */
+  relativeTime: string;
+  congestionTitle: string;
+  /** `{source}`, `{target}`. */
+  congestionTransition: string;
+  /** `{peak}`, `{time}` — one ranked transition. */
+  congestionPeak: string;
+  /** `{source}`, `{target}`, `{peak}`, `{time}` — the one-line summary of the busiest transition. */
+  congestionSummary: string;
+  congestionEmpty: string;
+  loading: string;
+  empty: string;
+  emptyBody: string;
+}
+
+/** The shipped English labels. */
+export const PROCESS_REPLAY_DEFAULT_LABELS: Readonly<ProcessReplayLabels> = Object.freeze({
+  region: "Process replay",
+  map: "Process map with case tokens",
+  play: "Play replay",
+  pause: "Pause replay",
+  time: "Replay time",
+  speed: "Playback speed",
+  speedOption: "{speed}×",
+  readout: "{time} · {count} in flight",
+  playing: "Replay playing",
+  relativeTime: "+{duration}",
+  congestionTitle: "Most congested transitions",
+  congestionTransition: "{source} → {target}",
+  congestionPeak: "Peak {peak} cases at {time}",
+  congestionSummary: "Busiest: {source} → {target}, {peak} cases at {time}",
+  congestionEmpty: "No case moves along a transition.",
+  loading: "Preparing the replay…",
+  empty: "No cases to replay",
+  emptyBody: "Load an event log with at least one case to replay it.",
+});
+
+/**
+ * Formats a playhead: a medium date and short time in wall-clock mode, `+duration` since each
+ * case's start in synchronized-start mode.
+ */
+export function useReplayTimeFormatter(
+  timeline: Pick<ReplayTimeline, "origin" | "synchronizedStart">,
+  relativeTemplate: string = PROCESS_REPLAY_DEFAULT_LABELS.relativeTime,
+): (t: number) => string {
+  const { formatDate } = useLocale();
+  const { origin, synchronizedStart } = timeline;
+  return useCallback(
+    (t: number) =>
+      synchronizedStart
+        ? relativeTemplate.replace("{duration}", formatDurationMs(t))
+        : formatDate(origin + t, { dateStyle: "medium", timeStyle: "short" }),
+    [formatDate, origin, synchronizedStart, relativeTemplate],
+  );
+}

package/src/process-replay/replay-tokens-context.ts

@@ -0,0 +1,30 @@
+"use client";
+
+/**
+ * The replay channel into the process map (RM-065).
+ *
+ * `ProcessMap` fixes its own edge types, so a replay cannot hand tokens to an edge through
+ * props. `ProcessReplay` provides this context above the map instead, keyed by edge id
+ * (`processEdgeId`); `ProcessTransitionEdge` reads its own entry and passes it on as the flow
+ * edge's `data.tokens`. Without a provider the read answers `undefined` and the edge's data
+ * is exactly what it was before this channel existed.
+ *
+ * Kept in its own tiny module so the edge imports no replay component.
+ */
+import { createContext, use } from "react";
+import type { FlowEdgeToken } from "@elabs-ai/components-flow";
+
+/** Edge id → the tokens on that edge right now. An edge with no entry carries none. */
+export type ProcessReplayTokens = ReadonlyMap<string, readonly FlowEdgeToken[]>;
+
+/** Provided by `ProcessReplay`. `null` (the default) means no replay is running. */
+export const ProcessReplayTokensContext = createContext<ProcessReplayTokens | null>(null);
+
+/** The tokens on one edge, or `undefined` outside a replay. */
+export function useProcessReplayEdgeTokens(edgeId: string): readonly FlowEdgeToken[] | undefined {
+  const tokens = use(ProcessReplayTokensContext);
+  if (tokens === null) return undefined;
+  return tokens.get(edgeId) ?? EMPTY_TOKENS;
+}
+
+const EMPTY_TOKENS: readonly FlowEdgeToken[] = Object.freeze([]);

package/src/process-replay/use-controllable-value.ts

@@ -0,0 +1,30 @@
+"use client";
+
+/**
+ * Controlled/uncontrolled state with a STABLE setter (RM-065).
+ *
+ * Mirrors `useControllableState` in `@elabs-ai/components-ui` (mode locked on mount,
+ * `onChange` always called), which that package does not export. The one difference is the
+ * point of this copy: the setter's identity never changes, even when a consumer passes an
+ * inline `onChange`, so the replay's animation-frame loop does not restart every frame.
+ */
+import { useCallback, useLayoutEffect, useRef, useState } from "react";
+
+export function useControllableValue<T>(
+  controlledValue: T | undefined,
+  defaultValue: T,
+  onChange?: (value: T) => void,
+): [T, (next: T) => void] {
+  const isControlledRef = useRef(controlledValue !== undefined);
+  const [internal, setInternal] = useState<T>(defaultValue);
+  const value = isControlledRef.current ? (controlledValue as T) : internal;
+  const onChangeRef = useRef(onChange);
+  useLayoutEffect(() => {
+    onChangeRef.current = onChange;
+  });
+  const setValue = useCallback((next: T) => {
+    if (!isControlledRef.current) setInternal(next);
+    onChangeRef.current?.(next);
+  }, []);
+  return [value, setValue];
+}