@elabs-ai/components-process 4.1.0 → 5.0.0

package/src/process-map/use-process-layout.ts

@@ -39,7 +39,7 @@
  */
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import type { XYPosition } from "@xyflow/react";
-import { layoutFlow, type FlowLayoutDirection } from "@elabs-ai/components-flow";
+import { layoutFlow, layoutFlowElk, type FlowLayoutDirection } from "@elabs-ai/components-flow";
 import type { ProcessMapEdge, ProcessMapNode } from "./map-model";
 
 /**
@@ -145,6 +145,12 @@ export interface UseProcessLayoutOptions {
   direction: FlowLayoutDirection;
   /** @default {@link DEFAULT_LAYOUT_DEBOUNCE_MS} */
   debounceMs?: number;
+  // elkjs adapter — RM-067
+  /**
+   * Which layout engine runs. `"elk"` calls `layoutFlowElk` (async, lazily loaded, falls
+   * back to dagre when elkjs is not installed) instead of `layoutFlow`. @default "dagre"
+   */
+  layoutEngine?: "dagre" | "elk";
 }
 
 /** What {@link useProcessLayout} answers. */
@@ -217,8 +223,10 @@ export function useProcessLayout({
   structureKey,
   direction,
   debounceMs = DEFAULT_LAYOUT_DEBOUNCE_MS,
+  layoutEngine = "dagre",
 }: UseProcessLayoutOptions): UseProcessLayoutResult {
-  const cacheKey = `${structureKey}::${direction}`;
+  // The engine joins the key only when it is not the default, so dagre keys are unchanged.
+  const cacheKey = `${structureKey}::${direction}${layoutEngine === "elk" ? "::elk" : ""}`;
   const cache = useRef(new Map<string, ProcessLayoutSnapshot>());
   const runs = useRef(0);
   // The layout the render below reads. Held in state (not a ref) because producing a new
@@ -231,17 +239,30 @@ export function useProcessLayout({
   const compute = useCallback(
     (key: string, currentNodes: ProcessMapNode[], currentEdges: ProcessMapEdge[]) => {
       const started = performance.now();
-      const result = layoutFlow<ProcessMapNode, ProcessMapEdge>(currentNodes, currentEdges, {
+      const layoutOptions = {
         direction,
         nodeSpacing: NODE_SPACING,
         rankSpacing: RANK_SPACING[direction],
-      });
-      const snapshot = toSnapshot(result, performance.now() - started);
-      runs.current += 1;
-      cache.current.set(key, snapshot);
-      setApplied({ key, snapshot });
+      };
+      const settle = (result: ReturnType<typeof layoutFlow<ProcessMapNode, ProcessMapEdge>>) => {
+        const snapshot = toSnapshot(result, performance.now() - started);
+        runs.current += 1;
+        cache.current.set(key, snapshot);
+        setApplied({ key, snapshot });
+      };
+      // elkjs adapter — RM-067: async, lazily loaded; `layoutFlowElk` never rejects (it
+      // falls back to dagre itself), and a result for a key no longer current still caches.
+      if (layoutEngine === "elk") {
+        void layoutFlowElk<ProcessMapNode, ProcessMapEdge>(
+          currentNodes,
+          currentEdges,
+          layoutOptions,
+        ).then(settle);
+        return;
+      }
+      settle(layoutFlow<ProcessMapNode, ProcessMapEdge>(currentNodes, currentEdges, layoutOptions));
     },
-    [direction],
+    [direction, layoutEngine],
   );
 
   // The nodes/edges the (possibly debounced) layout should run against. Held in a ref so

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

@@ -0,0 +1,107 @@
+"use client";
+
+/**
+ * CongestionHeat — the replay's congestion, as a ranked text list (RM-065).
+ *
+ * The map shows congestion without colour — more tokens on a busy edge, each drawn larger —
+ * and this list states it in words: the transitions that held the most cases at once, with
+ * the peak count and when it happened, plus a relative bar whose LENGTH (not hue) repeats the
+ * peak. It is static (the whole timeline, not the playhead), so it is also the complete
+ * reading for anyone who never presses play, including under reduced motion.
+ */
+import { forwardRef, useId, useMemo, type HTMLAttributes } from "react";
+import { useLocale } from "@elabs-ai/components-ui";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+import { rankReplayCongestion, type ReplayTimeline } from "../core/replay-timeline";
+import { fillLabel } from "../variant-explorer/variant-explorer-model";
+import {
+  PROCESS_REPLAY_DEFAULT_LABELS,
+  useReplayTimeFormatter,
+  type ProcessReplayLabels,
+} from "./replay-format";
+
+/** Props for {@link CongestionHeat}. */
+export interface CongestionHeatProps extends HTMLAttributes<HTMLElement> {
+  /** The replay timeline (`replayTimeline`). */
+  timeline: ReplayTimeline;
+  /** How many transitions to list. @default 5 */
+  limit?: number;
+  labels?: Partial<ProcessReplayLabels>;
+}
+
+/** The most congested transitions of a replay, ranked. */
+export const CongestionHeat = forwardRef<HTMLElement, CongestionHeatProps>(function CongestionHeat(
+  { timeline, limit = 5, labels: labelOverrides, className, ...props },
+  ref,
+) {
+  const { formatNumber } = useLocale();
+  const labels = useMemo<ProcessReplayLabels>(
+    () => ({ ...PROCESS_REPLAY_DEFAULT_LABELS, ...labelOverrides }),
+    [labelOverrides],
+  );
+  const formatTime = useReplayTimeFormatter(timeline, labels.relativeTime);
+  const ranked = useMemo(() => rankReplayCongestion(timeline, limit), [timeline, limit]);
+  const titleId = useId();
+  const top = ranked[0];
+
+  return (
+    <section
+      ref={ref}
+      data-slot="congestion-heat"
+      aria-labelledby={titleId}
+      className={cn("flex min-w-0 flex-col gap-2", className)}
+      {...props}
+    >
+      <h3 id={titleId} data-slot="congestion-heat-title" className="text-subtitle">
+        {labels.congestionTitle}
+      </h3>
+      {top ? (
+        <>
+          <p data-slot="congestion-heat-summary" className="text-caption text-muted-foreground">
+            {fillLabel(labels.congestionSummary, {
+              source: top.source,
+              target: top.target,
+              peak: formatNumber(top.peak),
+              time: formatTime(top.peakAt),
+            })}
+          </p>
+          <ol data-slot="congestion-heat-list" className="flex flex-col gap-2">
+            {ranked.map((entry) => (
+              <li
+                key={entry.edgeId}
+                data-slot="congestion-heat-item"
+                data-edge-id={entry.edgeId}
+                data-peak={entry.peak}
+                className="flex min-w-0 flex-col gap-1"
+              >
+                <span className="text-body truncate">
+                  {fillLabel(labels.congestionTransition, {
+                    source: entry.source,
+                    target: entry.target,
+                  })}
+                </span>
+                <span className="text-meta text-muted-foreground tabular-nums">
+                  {fillLabel(labels.congestionPeak, {
+                    peak: formatNumber(entry.peak),
+                    time: formatTime(entry.peakAt),
+                  })}
+                </span>
+                <span aria-hidden="true" className="h-1 w-full rounded-full bg-muted">
+                  <span
+                    data-slot="congestion-heat-bar"
+                    className="block h-full rounded-full bg-primary"
+                    style={{ width: `${(entry.peak / top.peak) * 100}%` }}
+                  />
+                </span>
+              </li>
+            ))}
+          </ol>
+        </>
+      ) : (
+        <p data-slot="congestion-heat-empty" className="text-caption text-muted-foreground">
+          {labels.congestionEmpty}
+        </p>
+      )}
+    </section>
+  );
+});

package/src/process-replay/index.ts

@@ -0,0 +1,14 @@
+/** ProcessReplay (RM-065) — public surface. */
+export * from "./process-replay";
+export * from "./replay-controls";
+export * from "./congestion-heat";
+export {
+  PROCESS_REPLAY_DEFAULT_LABELS,
+  useReplayTimeFormatter,
+  type ProcessReplayLabels,
+} from "./replay-format";
+export {
+  ProcessReplayTokensContext,
+  useProcessReplayEdgeTokens,
+  type ProcessReplayTokens,
+} from "./replay-tokens-context";

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

@@ -0,0 +1,168 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import "@xyflow/react/dist/style.css";
+import { expect, userEvent, waitFor, within } from "storybook/test";
+import { discoverGraph } from "../core/discover-graph";
+import fixture from "../core/fixtures/order-to-cash-small.json";
+import type { EventLog } from "../core/types";
+import { processEdgeId } from "../process-map/map-model";
+import { ProcessReplay } from "./process-replay";
+
+const log = fixture as EventLog;
+const graph = discoverGraph(log);
+const HOUR = 3_600_000;
+
+const tokenEls = (root: HTMLElement) => [
+  ...root.querySelectorAll<SVGCircleElement>('[data-slot="flow-edge-tokens-token"]'),
+];
+
+const readout = (root: HTMLElement) =>
+  root.querySelector<HTMLElement>('[data-slot="replay-controls-readout"]');
+
+const meta = {
+  title: "Process/ProcessReplay",
+  component: ProcessReplay,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "fullscreen",
+    docs: {
+      description: {
+        component:
+          "Cases replayed as tokens moving along the process map’s own transitions, with a " +
+          "time slider, play/pause, a speed select and a live in-flight case count. " +
+          "Congestion is never colour alone: a busy transition carries more tokens, each " +
+          "drawn larger, and a ranked list beside the map names the busiest transitions " +
+          "and when they peaked. Under reduced motion nothing starts on its own.",
+      },
+    },
+  },
+  decorators: [
+    (Story) => (
+      <div className="h-[40rem] w-full bg-background p-4">
+        <Story />
+      </div>
+    ),
+  ],
+  args: { graph, log, synchronizedStart: true, defaultTime: 1.5 * HOUR },
+} satisfies Meta<typeof ProcessReplay>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/**
+ * Paused at 1.5 h after each case’s start: one token per in-flight case, and the busiest
+ * transition (two cases on Check Credit → Approve Order) draws the largest tokens.
+ */
+export const Paused: Story = {
+  play: async ({ canvasElement }) => {
+    await waitFor(() => expect(tokenEls(canvasElement)).toHaveLength(5), { timeout: 5000 });
+    const radii = tokenEls(canvasElement).map((token) => Number(token.getAttribute("r")));
+    const busiestId = processEdgeId("Check Credit", "Approve Order");
+    const busiest = [...canvasElement.querySelectorAll(".react-flow__edge")].find(
+      (edge) => edge.getAttribute("data-id") === busiestId,
+    );
+    const busiestTokens = [
+      ...(busiest?.querySelectorAll('[data-slot="flow-edge-tokens-token"]') ?? []),
+    ];
+    await expect(busiestTokens).toHaveLength(2);
+    const busiestRadius = Math.max(
+      ...busiestTokens.map((token) => Number(token.getAttribute("r"))),
+    );
+    await expect(busiestRadius).toBe(Math.max(...radii));
+    await expect(Math.min(...radii)).toBeLessThan(busiestRadius);
+    const canvas = within(canvasElement);
+    await expect(canvas.getByRole("button", { name: "Play replay" })).toBeVisible();
+    await expect(readout(canvasElement)).toHaveTextContent("+1.5 h · 5 in flight");
+  },
+};
+
+/**
+ * Playing from the start: the playhead advances and tokens move along edges. The test browser
+ * runs with reduced motion, where `defaultPlaying` is held, so the play function presses play
+ * the way a reader would.
+ */
+export const Playing: Story = {
+  args: { defaultTime: 0, defaultPlaying: true },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const play = canvas.queryByRole("button", { name: "Play replay" });
+    if (play) await userEvent.click(play);
+    const slider = canvas.getByRole("slider", { name: "Replay time" });
+    await waitFor(() => expect(Number(slider.getAttribute("aria-valuenow"))).toBeGreaterThan(0), {
+      timeout: 5000,
+    });
+    await expect(canvas.getByRole("button", { name: "Pause replay" })).toBeVisible();
+    await userEvent.click(canvas.getByRole("button", { name: "Pause replay" }));
+    await expect(canvas.getByRole("button", { name: "Play replay" })).toBeVisible();
+  },
+};
+
+/** Synchronized start: every case begins at t = 0, so all five tokens share the first edge. */
+export const SynchronizedStart: Story = {
+  args: { defaultTime: 0 },
+  play: async ({ canvasElement }) => {
+    await waitFor(() => expect(tokenEls(canvasElement)).toHaveLength(5), { timeout: 5000 });
+    await expect(readout(canvasElement)).toHaveTextContent("+0 s · 5 in flight");
+  },
+};
+
+/** Wall-clock time: cases start on different days, so the readout shows dates. */
+export const WallClock: Story = {
+  args: { synchronizedStart: false, defaultTime: 0 },
+  play: async ({ canvasElement }) => {
+    await waitFor(() => expect(tokenEls(canvasElement)).toHaveLength(1), { timeout: 5000 });
+  },
+};
+
+/** The speed select and the time slider, driven from the keyboard. */
+export const SpeedControl: Story = {
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const speed = canvas.getByRole("combobox", { name: "Playback speed" });
+    speed.focus();
+    await userEvent.keyboard("{Enter}");
+    const option = await within(canvasElement.ownerDocument.body).findByRole("option", {
+      name: "4×",
+    });
+    await userEvent.click(option);
+    await waitFor(() => expect(speed).toHaveTextContent("4×"));
+
+    const slider = canvas.getByRole("slider", { name: "Replay time" });
+    slider.focus();
+    await userEvent.keyboard("{Home}");
+    await expect(slider).toHaveAttribute("aria-valuetext", "+0 s");
+    await expect(readout(canvasElement)).toHaveTextContent("+0 s · 5 in flight");
+  },
+};
+
+/**
+ * Reduced motion: `defaultPlaying` is ignored — nothing moves until the reader presses play —
+ * and the ranked congestion list carries the whole reading in text.
+ */
+export const ReducedMotion: Story = {
+  args: { defaultPlaying: true },
+  globals: { motionPref: "reduced" },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByRole("button", { name: "Play replay" })).toBeVisible();
+    await expect(canvasElement.querySelectorAll("animateMotion")).toHaveLength(0);
+    const heat = canvas.getByRole("region", { name: "Most congested transitions" });
+    await expect(heat).toHaveTextContent(/Busiest: Create Order → Check Credit, 5 cases/);
+    await expect(within(heat).getAllByRole("listitem").length).toBeGreaterThan(0);
+  },
+};
+
+/** A log with no cases. */
+export const Empty: Story = {
+  args: { log: { events: [] } },
+  play: async ({ canvasElement }) => {
+    await expect(canvasElement.querySelector('[data-slot="process-replay"]')).toHaveAttribute(
+      "data-state",
+      "empty",
+    );
+    await expect(within(canvasElement).getByText("No cases to replay")).toBeInTheDocument();
+  },
+};
+
+/** No log yet. */
+export const Loading: Story = {
+  args: { loading: true },
+};

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

@@ -0,0 +1,170 @@
+import { act, cleanup, fireEvent, render, screen, within } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { discoverGraph } from "../core/discover-graph";
+import { EDGE_KEY_SEPARATOR } from "../core/discover-graph";
+import fixture from "../core/fixtures/order-to-cash-small.json";
+import type { EventLog } from "../core/types";
+import { CongestionHeat } from "./congestion-heat";
+import { ProcessReplay } from "./process-replay";
+import { replayTimeline } from "../core/replay-timeline";
+import {
+  ProcessReplayTokensContext,
+  useProcessReplayEdgeTokens,
+  type ProcessReplayTokens,
+} from "./replay-tokens-context";
+
+// jsdom has no `DOMMatrixReadOnly`, which React Flow's transform math needs to mount the
+// canvas at all — the same missing-browser-API fill `process-map.test.tsx` documents.
+if (typeof globalThis.DOMMatrixReadOnly === "undefined") {
+  class DOMMatrixReadOnlyPolyfill {
+    m22 = 1;
+    constructor(_init?: unknown) {}
+  }
+  globalThis.DOMMatrixReadOnly = DOMMatrixReadOnlyPolyfill as unknown as typeof DOMMatrixReadOnly;
+}
+
+const log = fixture as EventLog;
+const graph = discoverGraph(log);
+const HOUR = 3_600_000;
+const status = () => document.querySelector('[data-slot="process-replay-status"]');
+
+let reduced = false;
+let frames: FrameRequestCallback[] = [];
+
+function flushFrame(now: number) {
+  const queued = frames;
+  frames = [];
+  act(() => queued.forEach((callback) => callback(now)));
+}
+
+beforeEach(() => {
+  reduced = false;
+  frames = [];
+  vi.stubGlobal("matchMedia", (query: string) => ({
+    matches: query.includes("reduce") ? reduced : false,
+    media: query,
+    addEventListener: () => {},
+    removeEventListener: () => {},
+    addListener: () => {},
+    removeListener: () => {},
+  }));
+  vi.stubGlobal("requestAnimationFrame", (callback: FrameRequestCallback) => {
+    frames.push(callback);
+    return frames.length;
+  });
+  vi.stubGlobal("cancelAnimationFrame", () => {
+    frames = [];
+  });
+});
+
+afterEach(() => {
+  cleanup();
+  vi.unstubAllGlobals();
+});
+
+describe("ProcessReplay", () => {
+  it("renders the controls, the paused announcement and the ranked congestion list", () => {
+    render(<ProcessReplay graph={graph} log={log} synchronizedStart bucketMs={HOUR} />);
+    expect(screen.getByRole("button", { name: "Play replay" })).toBeInTheDocument();
+    expect(screen.getByRole("slider", { name: "Replay time" })).toHaveAttribute(
+      "aria-valuetext",
+      "+0 s",
+    );
+    expect(screen.getByRole("combobox", { name: "Playback speed" })).toBeInTheDocument();
+    expect(status()).toHaveTextContent("+0 s · 5 in flight");
+
+    const heat = screen.getByRole("region", { name: "Most congested transitions" });
+    const items = within(heat).getAllByRole("listitem");
+    expect(items[0]).toHaveTextContent("Create Order → Check Credit");
+    expect(items[0]).toHaveAttribute("data-peak", "5");
+    expect(heat).toHaveTextContent("Busiest: Create Order → Check Credit, 5 cases at +0 s");
+  });
+
+  it("scrubs with the keyboard, one bucket per arrow press", () => {
+    const onTimeChange = vi.fn();
+    render(
+      <ProcessReplay
+        graph={graph}
+        log={log}
+        synchronizedStart
+        bucketMs={HOUR}
+        onTimeChange={onTimeChange}
+      />,
+    );
+    fireEvent.keyDown(screen.getByRole("slider", { name: "Replay time" }), { key: "ArrowRight" });
+    expect(onTimeChange).toHaveBeenLastCalledWith(HOUR);
+    expect(status()).toHaveTextContent("+1.0 h · 5 in flight");
+  });
+
+  it("advances the playhead on animation frames and cancels the loop on pause", () => {
+    const onTimeChange = vi.fn();
+    render(
+      <ProcessReplay
+        graph={graph}
+        log={log}
+        synchronizedStart
+        bucketMs={HOUR}
+        onTimeChange={onTimeChange}
+      />,
+    );
+    fireEvent.click(screen.getByRole("button", { name: "Play replay" }));
+    expect(status()).toHaveTextContent("Replay playing");
+    flushFrame(0);
+    flushFrame(3000); // 10% of the 30 s playback at 1×.
+    expect(onTimeChange).toHaveBeenLastCalledWith(HOUR);
+
+    fireEvent.click(screen.getByRole("button", { name: "Pause replay" }));
+    expect(frames).toHaveLength(0);
+    expect(status()).toHaveTextContent("+1.0 h · 5 in flight");
+  });
+
+  it("never autoplays under reduced motion, but plays when the reader presses play", () => {
+    reduced = true;
+    render(<ProcessReplay graph={graph} log={log} bucketMs={HOUR} defaultPlaying />);
+    expect(screen.getByRole("button", { name: "Play replay" })).toBeInTheDocument();
+    expect(frames).toHaveLength(0);
+    fireEvent.click(screen.getByRole("button", { name: "Play replay" }));
+    expect(frames).toHaveLength(1);
+  });
+
+  it("renders the loading and empty panels", () => {
+    const { rerender } = render(<ProcessReplay graph={graph} log={log} loading />);
+    expect(document.querySelector('[data-slot="process-replay"]')).toHaveAttribute(
+      "data-state",
+      "loading",
+    );
+    rerender(<ProcessReplay graph={graph} log={{ events: [] }} />);
+    expect(screen.getByText("No cases to replay")).toBeInTheDocument();
+  });
+});
+
+describe("CongestionHeat", () => {
+  it("says so when no case moves", () => {
+    render(<CongestionHeat timeline={replayTimeline({ events: [] })} />);
+    expect(screen.getByText("No case moves along a transition.")).toBeInTheDocument();
+  });
+});
+
+describe("replay tokens context", () => {
+  function Probe({ edgeId }: { edgeId: string }) {
+    const tokens = useProcessReplayEdgeTokens(edgeId);
+    return <output>{tokens === undefined ? "none" : tokens.length}</output>;
+  }
+  const edgeId = `Create Order${EDGE_KEY_SEPARATOR}Check Credit`;
+
+  it("answers undefined without a provider, so the edge data stays unchanged", () => {
+    render(<Probe edgeId={edgeId} />);
+    expect(screen.getByRole("status")).toHaveTextContent("none");
+  });
+
+  it("answers the edge's tokens, or an empty list, inside a replay", () => {
+    const tokens: ProcessReplayTokens = new Map([[edgeId, [{ id: "case-1", progress: 0.5 }]]]);
+    render(
+      <ProcessReplayTokensContext value={tokens}>
+        <Probe edgeId={edgeId} />
+        <Probe edgeId="elsewhere" />
+      </ProcessReplayTokensContext>,
+    );
+    expect(screen.getAllByRole("status").map((el) => el.textContent)).toEqual(["1", "0"]);
+  });
+});