@elabs-ai/components-process 4.1.0

package/src/core/worker/create-process-worker.ts

@@ -0,0 +1,211 @@
+/**
+ * Off-thread discovery — RM-050.
+ *
+ * Discovering a graph from a raw log is O(events) with a couple of hash lookups per event;
+ * on a 200 000-row import that is long enough to drop frames, and a dropped frame during a
+ * file import is exactly the moment an app reads as broken. So the derivation moves to a
+ * worker — but ONLY as an optimization: the caller never branches on the environment.
+ *
+ * **Degrade, never fail.** When there is no `Worker` (a server render, a Node test, an
+ * embedded webview), when constructing one throws, or when a live one errors, the same
+ * functions run inline on the calling thread and the promise still resolves with the same
+ * answer. `handleProcessRequest` is literally shared with the worker entry, so "the inline
+ * path agrees with the worker path" is a property of the code, not of a test.
+ *
+ * **Normalize once.** Every method takes an `AnyLog`; hand it an already-normalized log
+ * (`asNormalizedLog`) and neither side re-parses. A `NormalizedLog` is plain data and
+ * clones across `postMessage` unchanged.
+ */
+import type { DiscoverGraphOptions } from "../discover-graph";
+import type { AnyLog } from "../event-log";
+import type { ProcessGraph, Variant } from "../types";
+import {
+  handleProcessRequest,
+  type ProcessWorkerRequest,
+  type ProcessWorkerResponse,
+} from "./process-worker";
+
+/**
+ * The slice of the `Worker` interface this module uses.
+ *
+ * Narrow on purpose: it is the seam a test (or a bundler with its own worker construction)
+ * substitutes, and demanding the full DOM `Worker` surface for that would be pointless
+ * ceremony. A real `Worker` satisfies it.
+ */
+export interface ProcessWorkerLike {
+  postMessage(message: unknown): void;
+  terminate(): void;
+  addEventListener(
+    type: "message" | "error" | "messageerror",
+    listener: (event: unknown) => void,
+  ): void;
+}
+
+/** Options for {@link createProcessWorker}. */
+export interface CreateProcessWorkerOptions {
+  /** Skip the worker entirely and run inline. Useful for benchmarks and for tests. */
+  forceInline?: boolean;
+  /**
+   * Build the worker yourself.
+   *
+   * The default construction is
+   * `new Worker(new URL("./process-worker.ts", import.meta.url), { type: "module" })`.
+   * A bundler compiling THIS SOURCE (Vite, webpack) rewrites that literal itself; a
+   * consumer of the BUILT package gets `dist/core/process-worker.js`, which
+   * `tsup.config.ts` emits as its own pass and points the built bundle at — a bundler
+   * rewrites the source it compiles, never a `dist` it merely consumes, so that file has
+   * to be real. A host that needs its own URL supplies this instead. Throwing from it is
+   * safe: the handle falls back to the inline path.
+   */
+  createWorker?: () => ProcessWorkerLike;
+}
+
+/** What {@link createProcessWorker} hands back. */
+export interface ProcessWorkerHandle {
+  /** Discover a directly-follows graph. */
+  discover(log: AnyLog, options?: DiscoverGraphOptions): Promise<ProcessGraph>;
+  /** Group the log's cases into variants. */
+  variants(log: AnyLog): Promise<Variant[]>;
+  /** Stop the worker. Pending promises reject, and so does every later call. */
+  terminate(): void;
+  /**
+   * `true` when work is currently running on the CALLING thread — either because the
+   * environment has no worker, or because one failed and the handle degraded.
+   */
+  readonly inline: boolean;
+}
+
+interface Pending {
+  request: ProcessWorkerRequest;
+  settle: (response: ProcessWorkerResponse) => void;
+}
+
+function workerConstructible(): boolean {
+  return typeof Worker !== "undefined" && typeof URL !== "undefined";
+}
+
+/**
+ * Create a handle that computes off-thread when it can and inline when it cannot.
+ *
+ * The worker is created LAZILY, on the first request, so constructing a handle costs
+ * nothing in an environment that never uses it.
+ */
+export function createProcessWorker(options: CreateProcessWorkerOptions = {}): ProcessWorkerHandle {
+  const construct = options.createWorker;
+  let inline = options.forceInline === true || (construct === undefined && !workerConstructible());
+  let terminated = false;
+  let worker: ProcessWorkerLike | undefined;
+  let nextId = 0;
+  const pending = new Map<number, Pending>();
+
+  /** Give up on the worker and answer everything outstanding on this thread. */
+  function degrade(): void {
+    inline = true;
+    const stale = [...pending.values()];
+    pending.clear();
+    if (worker !== undefined) {
+      const dying = worker;
+      worker = undefined;
+      try {
+        dying.terminate();
+      } catch {
+        // A worker that cannot be terminated is already gone; nothing to recover.
+      }
+    }
+    for (const entry of stale) entry.settle(handleProcessRequest(entry.request));
+  }
+
+  function onMessage(event: unknown): void {
+    const response = (event as { data?: unknown }).data as ProcessWorkerResponse | undefined;
+    if (response === undefined || typeof response.id !== "number") return;
+    const entry = pending.get(response.id);
+    if (entry === undefined) return;
+    pending.delete(response.id);
+    entry.settle(response);
+  }
+
+  function ensureWorker(): ProcessWorkerLike | undefined {
+    if (inline || terminated) return undefined;
+    if (worker !== undefined) return worker;
+    try {
+      worker =
+        construct === undefined
+          ? (new Worker(new URL("./process-worker.ts", import.meta.url), {
+              type: "module",
+            }) as unknown as ProcessWorkerLike)
+          : construct();
+    } catch {
+      degrade();
+      return undefined;
+    }
+    worker.addEventListener("message", onMessage);
+    worker.addEventListener("error", degrade);
+    worker.addEventListener("messageerror", degrade);
+    return worker;
+  }
+
+  function send(build: (id: number) => ProcessWorkerRequest): Promise<ProcessWorkerResponse> {
+    if (terminated) return Promise.reject(new Error("process worker terminated"));
+    nextId += 1;
+    const request = build(nextId);
+    const active = ensureWorker();
+    if (active === undefined) {
+      // Inline, but still a microtask later, so the caller's own frame returns first.
+      return Promise.resolve().then(() => handleProcessRequest(request));
+    }
+    return new Promise<ProcessWorkerResponse>((resolve, reject) => {
+      pending.set(request.id, { request, settle: resolve });
+      try {
+        active.postMessage(request);
+      } catch {
+        pending.delete(request.id);
+        degrade();
+        try {
+          resolve(handleProcessRequest(request));
+        } catch (error) {
+          reject(error instanceof Error ? error : new Error(String(error)));
+        }
+      }
+    });
+  }
+
+  function unwrap<T>(response: ProcessWorkerResponse, read: (ok: ProcessWorkerResponse) => T): T {
+    if (!response.ok) throw new Error(response.error);
+    return read(response);
+  }
+
+  return {
+    async discover(log, discoverOptions) {
+      const response = await send((id) =>
+        discoverOptions === undefined
+          ? { id, kind: "discover", log }
+          : { id, kind: "discover", log, options: discoverOptions },
+      );
+      return unwrap(response, (ok) => (ok as { graph: ProcessGraph }).graph);
+    },
+    async variants(log) {
+      const response = await send((id) => ({ id, kind: "variants", log }));
+      return unwrap(response, (ok) => (ok as { variants: Variant[] }).variants);
+    },
+    terminate() {
+      terminated = true;
+      const stale = [...pending.values()];
+      pending.clear();
+      for (const entry of stale) {
+        entry.settle({ id: entry.request.id, ok: false, error: "process worker terminated" });
+      }
+      if (worker !== undefined) {
+        const dying = worker;
+        worker = undefined;
+        try {
+          dying.terminate();
+        } catch {
+          // Already gone.
+        }
+      }
+    },
+    get inline(): boolean {
+      return inline;
+    },
+  };
+}

package/src/core/worker/process-worker.ts

@@ -0,0 +1,80 @@
+/**
+ * The worker entry point — RM-050.
+ *
+ * Two things live here, deliberately in one module: the PURE request handler, and the
+ * `message` bootstrap that runs it inside a real worker. `createProcessWorker` imports the
+ * handler for its inline path, so the code that answers on the main thread and the code
+ * that answers off it are the SAME function — parity is structural, not something a test
+ * has to keep true.
+ *
+ * The bootstrap is guarded by a real worker-scope check, so importing this module from the
+ * main thread registers nothing.
+ */
+import { discoverGraph, type DiscoverGraphOptions } from "../discover-graph";
+import type { AnyLog } from "../event-log";
+import { extractVariants } from "../extract-variants";
+import type { ProcessGraph, Variant } from "../types";
+
+/** What the main thread asks the worker to compute. Structured-cloneable, by construction. */
+export type ProcessWorkerRequest =
+  | { id: number; kind: "discover"; log: AnyLog; options?: DiscoverGraphOptions }
+  | { id: number; kind: "variants"; log: AnyLog };
+
+/** What comes back. `ok: false` carries a message, never an `Error` (which clones poorly). */
+export type ProcessWorkerResponse =
+  | { id: number; ok: true; kind: "discover"; graph: ProcessGraph }
+  | { id: number; ok: true; kind: "variants"; variants: Variant[] }
+  | { id: number; ok: false; error: string };
+
+/**
+ * Answer one request.
+ *
+ * Pure and synchronous: the whole point of the worker is that this is the expensive part,
+ * and moving it off the main thread is the only thing the worker adds. Throwing is
+ * converted to an `ok: false` response so a bad log cannot silently kill the worker and
+ * leave every later request hanging.
+ */
+export function handleProcessRequest(request: ProcessWorkerRequest): ProcessWorkerResponse {
+  try {
+    if (request.kind === "discover") {
+      return {
+        id: request.id,
+        ok: true,
+        kind: "discover",
+        graph: discoverGraph(request.log, request.options ?? {}),
+      };
+    }
+    return { id: request.id, ok: true, kind: "variants", variants: extractVariants(request.log) };
+  } catch (error) {
+    return { id: request.id, ok: false, error: describe(error) };
+  }
+}
+
+function describe(error: unknown): string {
+  if (error instanceof Error) return error.message;
+  return String(error);
+}
+
+/**
+ * Is this module executing INSIDE a worker?
+ *
+ * `self instanceof WorkerGlobalScope` is the specified test. A duck-type on `postMessage`
+ * would be wrong: `window.postMessage` exists on every page, so the main thread would
+ * install a listener that answers its own messages.
+ */
+function inWorkerScope(): boolean {
+  const scope = globalThis as { WorkerGlobalScope?: new () => unknown; self?: unknown };
+  const constructor = scope.WorkerGlobalScope;
+  if (typeof constructor !== "function") return false;
+  return scope.self instanceof constructor;
+}
+
+if (inWorkerScope()) {
+  const scope = self as unknown as {
+    addEventListener: (type: "message", listener: (event: MessageEvent) => void) => void;
+    postMessage: (message: unknown) => void;
+  };
+  scope.addEventListener("message", (event: MessageEvent) => {
+    scope.postMessage(handleProcessRequest(event.data as ProcessWorkerRequest));
+  });
+}

package/src/index.ts

@@ -0,0 +1,29 @@
+/**
+ * `@elabs-ai/components-process` — the React surface of the process-mining package.
+ *
+ * This is a LAYER-3 composite (ADR 0034): it composes `@elabs-ai/components-flow`,
+ * `-charts`, `-data` and `-ui`, and nothing depends on it. The binding rule is
+ * "primitives go down, compositions go up" — a generic edge, mark, table, scale or
+ * control belongs in the base package that owns it, never here. See
+ * `.claude/rules/process-components.md` and `pnpm process:reuse:check`.
+ *
+ * Wave-1 items APPEND their exports at the end of the block below, each under a
+ * `// <Name> — RM-NNN` comment, so concurrent branches merge as appends.
+ *
+ * The framework-free half (event-log types, directly-follows derivation, variant and
+ * conformance math) lives at `@elabs-ai/components-process/core` — see `./core/index.ts`.
+ */
+
+// ── Views (React) ────────────────────────────────────────────────────────────
+// (empty — the wave-0 scaffold ships no components on purpose; RM-049 onward append here)
+
+export {};
+
+// ProcessMap — RM-051
+export * from "./process-map";
+
+// AbstractionControls/MetricLayerSwitch/ProcessKpiStrip/useProcessExplorer — RM-052
+export * from "./abstraction-controls";
+export * from "./metric-layer-switch";
+export * from "./process-kpi-strip";
+export * from "./use-process-explorer";

package/src/metric-layer-switch/index.ts

@@ -0,0 +1,6 @@
+export { MetricLayerSwitch } from "./metric-layer-switch";
+export type {
+  MetricLayer,
+  MetricLayerSwitchMetric,
+  MetricLayerSwitchProps,
+} from "./metric-layer-switch";

package/src/metric-layer-switch/metric-layer-switch.stories.tsx

@@ -0,0 +1,131 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+import { expect, userEvent, waitFor, within } from "storybook/test";
+import {
+  MetricLayerSwitch,
+  type MetricLayer,
+  type MetricLayerSwitchMetric,
+} from "./metric-layer-switch";
+
+function ControlledMetricLayerSwitch({
+  initialLayer,
+  initialMetric,
+  defaultLocked,
+}: {
+  initialLayer: MetricLayer;
+  initialMetric: MetricLayerSwitchMetric;
+  defaultLocked?: boolean;
+}) {
+  const [layer, setLayer] = useState<MetricLayer>(initialLayer);
+  const [metric, setMetric] = useState<MetricLayerSwitchMetric>(initialMetric);
+  return (
+    <div className="max-w-md">
+      <MetricLayerSwitch
+        layer={layer}
+        onLayerChange={setLayer}
+        metric={metric}
+        onMetricChange={(next) => setMetric((prev) => ({ ...prev, ...next }))}
+        defaultLocked={defaultLocked}
+      />
+    </div>
+  );
+}
+
+const meta = {
+  title: "Process/MetricLayerSwitch",
+  component: MetricLayerSwitch,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "The 'what number is this graph drawing' control. A Frequency/Performance/Rework " +
+          "`ToggleGroup` picks a family of readings before two `Select`s narrow to one " +
+          "member of it — one for the activity (node) metric, one for the transition (edge) " +
+          "metric. The lock keeps the two in sync, restricting the edge `Select` to the " +
+          "4-value domain the two sides share while locked. Selecting 'Rework' disables both " +
+          "selects: rework has no frequency/performance READING of its own — it is " +
+          "`ProcessMap`'s own `rework` prop, driven by `detectRework`.",
+      },
+    },
+  },
+} satisfies Meta<typeof MetricLayerSwitch>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** Frequency layer, locked (the default) — both selects share one 4-value domain. */
+export const Default: Story = {
+  render: () => (
+    <ControlledMetricLayerSwitch
+      initialLayer="frequency"
+      initialMetric={{ node: "absolute", edge: "absolute" }}
+    />
+  ),
+};
+
+/** Frequency layer, unlocked — the edge select widens to its own 6-value domain. */
+export const Unlocked: Story = {
+  render: () => (
+    <ControlledMetricLayerSwitch
+      initialLayer="frequency"
+      initialMetric={{ node: "absolute", edge: "relative_antecedent" }}
+      defaultLocked={false}
+    />
+  ),
+};
+
+/** Performance layer — the same 7-value duration-aggregate domain on both sides. */
+export const Performance: Story = {
+  render: () => (
+    <ControlledMetricLayerSwitch
+      initialLayer="performance"
+      initialMetric={{ node: "median", edge: "median" }}
+    />
+  ),
+};
+
+/** Rework layer — both selects and the lock are disabled; rework is not a `ProcessMetric`. */
+export const Rework: Story = {
+  render: () => (
+    <ControlledMetricLayerSwitch
+      initialLayer="rework"
+      initialMetric={{ node: "absolute", edge: "absolute" }}
+    />
+  ),
+};
+
+/**
+ * Switching the node metric while locked carries the edge metric along with it — the
+ * RM-052 acceptance criterion for the lock, exercised as a real click rather than a
+ * direct prop assertion.
+ */
+export const LockSync: Story = {
+  render: () => (
+    <ControlledMetricLayerSwitch
+      initialLayer="frequency"
+      initialMetric={{ node: "absolute", edge: "absolute" }}
+    />
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const body = within(canvasElement.ownerDocument.body);
+
+    const nodeSelect = canvas.getByRole("combobox", { name: "Activity" });
+    await userEvent.click(nodeSelect);
+    await userEvent.click(await body.findByRole("option", { name: "Share of cases" }));
+
+    // Locked: the edge select follows the node select to the same value.
+    const edgeSelect = canvas.getByRole("combobox", { name: "Transition" });
+    await waitFor(() => expect(edgeSelect).toHaveTextContent("Share of cases"));
+
+    // Unlocking, then changing the node metric again, must NOT drag the edge along.
+    const lockToggle = canvas.getByRole("button", {
+      name: "Unlock activity and transition metrics",
+    });
+    await userEvent.click(lockToggle);
+    await userEvent.click(nodeSelect);
+    await userEvent.click(await body.findByRole("option", { name: "Occurrences" }));
+    await waitFor(() => expect(nodeSelect).toHaveTextContent("Occurrences"));
+    expect(edgeSelect).toHaveTextContent("Share of cases");
+  },
+};

package/src/metric-layer-switch/metric-layer-switch.test.tsx

@@ -0,0 +1,102 @@
+import { cleanup, render, screen, within } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { MetricLayer, MetricLayerSwitchMetric } from "./metric-layer-switch";
+import { MetricLayerSwitch } from "./metric-layer-switch";
+
+afterEach(cleanup);
+
+function renderSwitch(
+  overrides: Partial<{
+    layer: MetricLayer;
+    metric: MetricLayerSwitchMetric;
+    defaultLocked: boolean;
+    locked: boolean;
+  }> = {},
+) {
+  const onLayerChange = vi.fn();
+  const onMetricChange = vi.fn();
+  const onLockedChange = vi.fn();
+  const utils = render(
+    <MetricLayerSwitch
+      layer={overrides.layer ?? "frequency"}
+      onLayerChange={onLayerChange}
+      metric={overrides.metric ?? { node: "absolute", edge: "absolute" }}
+      onMetricChange={onMetricChange}
+      defaultLocked={overrides.defaultLocked}
+      locked={overrides.locked}
+      onLockedChange={onLockedChange}
+    />,
+  );
+  return { onLayerChange, onMetricChange, onLockedChange, ...utils };
+}
+
+describe("MetricLayerSwitch — rendering", () => {
+  it("renders the layer toggle group and both metric selects", () => {
+    renderSwitch();
+    expect(screen.getByRole("group", { name: "Metric layer" })).toBeInTheDocument();
+    expect(screen.getByRole("combobox", { name: "Activity" })).toBeInTheDocument();
+    expect(screen.getByRole("combobox", { name: "Transition" })).toBeInTheDocument();
+  });
+
+  it("defaults to locked — the lock toggle announces 'Unlock…'", () => {
+    renderSwitch();
+    expect(
+      screen.getByRole("button", { name: "Unlock activity and transition metrics" }),
+    ).toBeInTheDocument();
+  });
+});
+
+describe("MetricLayerSwitch — Rework layer disables both selects and the lock", () => {
+  it("disables node/edge selects and the lock toggle when layer is 'rework'", () => {
+    renderSwitch({ layer: "rework" });
+    expect(screen.getByRole("combobox", { name: "Activity" })).toBeDisabled();
+    expect(screen.getByRole("combobox", { name: "Transition" })).toBeDisabled();
+    expect(
+      screen.getByRole("button", { name: "Unlock activity and transition metrics" }),
+    ).toBeDisabled();
+  });
+});
+
+describe("MetricLayerSwitch — switching to Performance normalizes the metric", () => {
+  it("requests { node: 'median', edge: 'median' } when leaving a frequency-only value", async () => {
+    const user = userEvent.setup();
+    const { onMetricChange } = renderSwitch({ metric: { node: "absolute", edge: "absolute" } });
+    await user.click(screen.getByRole("radio", { name: "Performance" }));
+    expect(onMetricChange).toHaveBeenCalledWith({ node: "median", edge: "median" });
+  });
+});
+
+describe("MetricLayerSwitch — the lock (RM-052 acceptance criterion)", () => {
+  it("changing the node metric while locked carries the edge metric along", async () => {
+    const user = userEvent.setup();
+    const { onMetricChange } = renderSwitch({ defaultLocked: true });
+    const nodeSelect = screen.getByRole("combobox", { name: "Activity" });
+    await user.click(nodeSelect);
+    const body = within(nodeSelect.ownerDocument.body);
+    await user.click(await body.findByRole("option", { name: "Share of cases" }));
+    expect(onMetricChange).toHaveBeenCalledWith({ node: "relative_case", edge: "relative_case" });
+  });
+
+  it("changing the node metric while unlocked leaves the edge metric alone", async () => {
+    const user = userEvent.setup();
+    const { onMetricChange } = renderSwitch({ defaultLocked: false });
+    const nodeSelect = screen.getByRole("combobox", { name: "Activity" });
+    await user.click(nodeSelect);
+    const body = within(nodeSelect.ownerDocument.body);
+    await user.click(await body.findByRole("option", { name: "Share of cases" }));
+    expect(onMetricChange).toHaveBeenCalledWith({ node: "relative_case" });
+  });
+
+  it("turning the lock ON syncs the edge metric to the node's current value", async () => {
+    const user = userEvent.setup();
+    const { onMetricChange } = renderSwitch({
+      defaultLocked: false,
+      metric: { node: "absolute", edge: "relative_antecedent" },
+    });
+    await user.click(
+      screen.getByRole("button", { name: "Lock activity and transition metrics together" }),
+    );
+    expect(onMetricChange).toHaveBeenCalledWith({ edge: "absolute" });
+  });
+});