@elabs-ai/components-process 4.1.0 → 5.0.0

package/src/process-compare/compare-kpi-strip.stories.tsx

@@ -0,0 +1,48 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { CompareKpiStrip } from "./compare-kpi-strip";
+
+const HOUR = 60 * 60 * 1000;
+
+const meta = {
+  title: "Process/ProcessCompare/CompareKpiStrip",
+  component: CompareKpiStrip,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "padded",
+    docs: {
+      description: {
+        component:
+          "The KPI pair under `ProcessCompare`: cases and median throughput for each side, " +
+          "with B’s tiles carrying a signed delta against A. Direction is an arrow glyph plus " +
+          "an accessible name, never colour alone.",
+      },
+    },
+  },
+  args: {
+    a: { label: "Before", kpis: { cases: 1200, medianThroughput: 52 * HOUR } },
+    b: { label: "After", kpis: { cases: 1350, medianThroughput: 41 * HOUR } },
+  },
+  render: (args) => (
+    <div className="w-full max-w-4xl">
+      <CompareKpiStrip {...args} />
+    </div>
+  ),
+} satisfies Meta<typeof CompareKpiStrip>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** Both sides carry a log, so cases and median throughput pair up. */
+export const Default: Story = {};
+
+/** A graph-only side has no throughput — the strip falls back to the cases pair alone. */
+export const CasesOnly: Story = {
+  args: {
+    a: { label: "Before", kpis: { cases: 1200 } },
+    b: { label: "After", kpis: { cases: 1100 } },
+  },
+};
+
+/** Not ready yet: `MetricGrid`’s own loading state, same footprint as the resolved strip. */
+export const Loading: Story = {
+  args: { loading: true },
+};

package/src/process-compare/compare-kpi-strip.tsx

@@ -0,0 +1,94 @@
+"use client";
+
+/**
+ * CompareKpiStrip — the one shared reading of "how did B differ from A" (RM-064): cases and
+ * median throughput for each side, paired, with a delta on B's own tile.
+ *
+ * Built entirely on `MetricCard`/`MetricGrid` (`@elabs-ai/components-ui`/`-charts`) — no
+ * local grid, no local delta styling. `MetricCard`'s own `delta`/`deltaDirection` already
+ * carries direction as an arrow glyph AND a "up/down, favorable/unfavorable" accessible
+ * name (never colour alone, see `metric-card.tsx`), so this file adds no channel of its
+ * own — it only decides WHICH two numbers to pair and what counts as favourable.
+ */
+import { forwardRef, type HTMLAttributes } from "react";
+import { MetricCard, useLocale } from "@elabs-ai/components-ui";
+import { MetricGrid } from "@elabs-ai/components-charts";
+import { formatDurationMs } from "../process-map/map-model";
+import type { CompareSideKpis } from "./compare-model";
+
+export interface CompareKpiStripSide {
+  /** The host-supplied name for this side ("Before", "Q1", the log's own file name, …). */
+  label: string;
+  kpis: CompareSideKpis;
+}
+
+export interface CompareKpiStripProps extends HTMLAttributes<HTMLDivElement> {
+  a: CompareKpiStripSide;
+  b: CompareKpiStripSide;
+  loading?: boolean;
+}
+
+interface Delta {
+  text: string;
+  direction: "up" | "down" | "neutral";
+}
+
+/** `b` relative to `a`, as a signed percentage — `null` when `a` is `0` (nothing to divide by). */
+function percentDelta(a: number, b: number): Delta | null {
+  if (a === 0) return null;
+  const fraction = (b - a) / a;
+  const percent = Math.round(fraction * 100);
+  if (percent === 0) return { text: "0%", direction: "neutral" };
+  return { text: `${percent > 0 ? "+" : ""}${percent}%`, direction: percent > 0 ? "up" : "down" };
+}
+
+/** Compact KPI pairs for `ProcessCompare`: cases and median throughput, A vs B. */
+export const CompareKpiStrip = forwardRef<HTMLDivElement, CompareKpiStripProps>(
+  function CompareKpiStrip({ a, b, loading = false, className, ...props }, ref) {
+    const { t } = useLocale();
+    const casesDelta = percentDelta(a.kpis.cases, b.kpis.cases);
+    const hasThroughput =
+      a.kpis.medianThroughput !== undefined && b.kpis.medianThroughput !== undefined;
+    const throughputDelta = hasThroughput
+      ? percentDelta(a.kpis.medianThroughput as number, b.kpis.medianThroughput as number)
+      : null;
+
+    return (
+      <div ref={ref} data-slot="compare-kpi-strip" className={className} {...props}>
+        <MetricGrid columns={hasThroughput ? 4 : 2} loading={loading}>
+          <MetricCard
+            label={t("process.compare.cases", { label: a.label })}
+            value={a.kpis.cases}
+            announceLoading={false}
+          />
+          <MetricCard
+            label={t("process.compare.cases", { label: b.label })}
+            value={b.kpis.cases}
+            announceLoading={false}
+            delta={casesDelta?.text}
+            deltaDirection={casesDelta?.direction}
+          />
+          {hasThroughput ? (
+            <>
+              <MetricCard
+                label={t("process.compare.medianThroughput", { label: a.label })}
+                value={formatDurationMs(a.kpis.medianThroughput as number)}
+                announceLoading={false}
+              />
+              <MetricCard
+                label={t("process.compare.medianThroughput", { label: b.label })}
+                value={formatDurationMs(b.kpis.medianThroughput as number)}
+                announceLoading={false}
+                delta={throughputDelta?.text}
+                deltaDirection={throughputDelta?.direction}
+                // A shorter throughput is the improvement — the inverse of the cases pair
+                // above, where more/fewer cases carries no inherent favourability.
+                positiveIsGood={false}
+              />
+            </>
+          ) : null}
+        </MetricGrid>
+      </div>
+    );
+  },
+);

package/src/process-compare/compare-model.ts

@@ -0,0 +1,83 @@
+/**
+ * compare-model — the presentation-shaping helpers `ProcessCompare`/`CompareKpiStrip` read
+ * from, kept out of `process-compare.tsx` so the render function stays about layout, not
+ * derivation (RM-064).
+ */
+import { asNormalizedLog } from "../core/event-log";
+import { durationStats } from "../core/duration-stats";
+import type { DiffState, ProcessGraphDiff } from "../core/diff-graphs";
+import type { EventLog, ProcessGraph } from "../core/types";
+import { diffStateByActivity } from "./diff-to-graph";
+
+/** One side's raw input — a discovered graph, an event log, or (loading) neither. */
+export interface CompareSideInput {
+  graph?: ProcessGraph;
+  log?: EventLog;
+}
+
+/** The two numbers {@link CompareKpiStrip} reads for one side. */
+export interface CompareSideKpis {
+  cases: number;
+  /** Median case throughput, ms. Omitted when the side has no `log` to derive it from. */
+  medianThroughput?: number;
+}
+
+/**
+ * Cases and median throughput for one side, mirroring `useProcessExplorer`'s own `kpis`
+ * derivation (`cases`/`medianThroughput` from a normalized log's per-case durations).
+ * `medianThroughput` needs case-level duration samples that a bare `ProcessGraph` does not
+ * carry (only per-activity/per-transition aggregates do) — so it is only derivable when the
+ * caller also handed this side a `log`; a `graph`-only side reports cases alone.
+ */
+export function resolveCompareKpis(side: CompareSideInput): CompareSideKpis {
+  if (side.log) {
+    const normalized = asNormalizedLog(side.log);
+    const medianThroughput = durationStats(normalized.cases.map((kase) => kase.duration)).median;
+    return { cases: normalized.totals.cases, medianThroughput };
+  }
+  return { cases: side.graph?.totals.cases ?? 0 };
+}
+
+/** Translator shape this module needs — the same signature `useLocale()` returns. */
+export type Translate = (key: string, vars?: Record<string, string | number>) => string;
+
+/**
+ * The diff-state word for one activity, localized. `"common"` reads as a plain word; the
+ * two single-sided states name the OWNING side by its host-supplied label ("Before only",
+ * "After only") rather than the generic "A"/"B" — the label is what the reader actually
+ * chose to call that side.
+ */
+export function diffStateSuffix(
+  state: DiffState,
+  aLabel: string,
+  bLabel: string,
+  t: Translate,
+): string {
+  if (state === "common") return t("process.compare.diffSuffixCommon");
+  return t("process.compare.diffSuffixOnly", { label: state === "aOnly" ? aLabel : bLabel });
+}
+
+/**
+ * Append the localized diff-state word to every activity's own label — the TEXT channel a
+ * superimposed `ProcessMap` reads as its node title (`map-model.ts`'s `buildProcessMapModel`
+ * always prints `activity.label`), so diff state reaches the reader through real text and
+ * the node's accessible name, not only through {@link diffColorScale}'s accent swatch
+ * (WCAG 1.4.1 — colour is never the only channel).
+ */
+export function withDiffLabels(
+  graph: ProcessGraph,
+  diff: ProcessGraphDiff,
+  aLabel: string,
+  bLabel: string,
+  t: Translate,
+): ProcessGraph {
+  const stateById = diffStateByActivity(diff);
+  return {
+    ...graph,
+    activities: graph.activities.map((activity) => {
+      const state = stateById.get(activity.id) ?? "common";
+      const suffix = diffStateSuffix(state, aLabel, bLabel, t);
+      return { ...activity, label: `${activity.label || activity.id} · ${suffix}` };
+    }),
+  };
+}

package/src/process-compare/compare-side.tsx

@@ -0,0 +1,42 @@
+"use client";
+
+/**
+ * CompareSide — one labeled `ProcessMap` panel inside `ProcessCompare`'s side-by-side mode
+ * (RM-064). Owns nothing beyond a heading and the map itself — `ProcessCompare` lifts
+ * abstraction, metric and table-view state so both sides stay in lockstep, the same
+ * "lift state into the provider" convention a compound component follows, applied to a
+ * fixed pair rather than an open set of children.
+ */
+import { forwardRef, type HTMLAttributes } from "react";
+import { Heading } from "@elabs-ai/components-ui";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+import { ProcessMap, type ProcessMapProps } from "../process-map/process-map";
+
+export interface CompareSideProps extends HTMLAttributes<HTMLDivElement> {
+  /** The host-supplied name for this side ("Before", "Q1", the log's own file name, …). */
+  label: string;
+  /** Forwarded to `ProcessMap` verbatim — everything this side's canvas needs. */
+  map: Omit<ProcessMapProps, "className">;
+}
+
+/** One heading + one `ProcessMap`, stacked to fill its panel. */
+export const CompareSide = forwardRef<HTMLDivElement, CompareSideProps>(function CompareSide(
+  { label, map, className, ...props },
+  ref,
+) {
+  return (
+    <div
+      ref={ref}
+      data-slot="compare-side"
+      className={cn("flex min-h-0 flex-col gap-2", className)}
+      {...props}
+    >
+      <Heading level={3} size="subtitle" data-slot="compare-side-label">
+        {label}
+      </Heading>
+      <div className="min-h-96 flex-1">
+        <ProcessMap {...map} className="size-full" />
+      </div>
+    </div>
+  );
+});

package/src/process-compare/diff-to-graph.ts

@@ -0,0 +1,104 @@
+/**
+ * diffToProcessGraph — turn a `ProcessGraphDiff` (`/core`'s `diffGraphs`, RM-064) into the
+ * ONE `ProcessGraph` `ProcessCompare`'s superimposed mode hands to a single `ProcessMap`,
+ * plus a synthetic `ActivityColorScale` that paints by diff state instead of by identity.
+ *
+ * `ProcessMap` (RM-051) is never forked or given a new prop for this: its existing
+ * `colorScale` prop (RM-054) is the only per-activity colour hook it exposes, and
+ * `ActivityColorScale` is a plain interface — nothing stops a second caller building one
+ * keyed by diff state rather than by rank. Pure, no React; lives beside `process-compare.tsx`
+ * rather than under `/core` because it is presentation shaping for ONE component (label
+ * suffixes, colour tokens), not a reusable process-mining derivation.
+ */
+import type {
+  ActivityColor,
+  ActivityColorLegendEntry,
+  ActivityColorScale,
+} from "../core/activity-color-scale";
+import type { DiffEntry, DiffState, ProcessGraphDiff } from "../core/diff-graphs";
+import type { ActivityStats, ProcessGraph, TransitionStats } from "../core/types";
+
+/** Empty graph — the identity input for a side that has not discovered anything yet. */
+export const EMPTY_PROCESS_GRAPH: ProcessGraph = {
+  activities: [],
+  transitions: [],
+  startActivities: {},
+  endActivities: {},
+  totals: { cases: 0, events: 0, variants: 0 },
+};
+
+/**
+ * The three diff tokens the design asks for (RM-064's spec): `common` reads as success,
+ * `aOnly` as the first chart series, `bOnly` as destructive. Semantic tokens only — no
+ * literal colour is authored (`.claude/rules/conventions.md`'s styling rule).
+ */
+export const DIFF_STATE_TOKEN: Record<DiffState, string> = {
+  common: "--success",
+  aOnly: "--chart-1",
+  bOnly: "--destructive",
+};
+
+/** `b`'s stats when the element survives into `b` (common or bOnly); `a`'s otherwise. */
+function representative<Stats>(entry: DiffEntry<Stats>): Stats {
+  return (entry.b ?? entry.a) as Stats;
+}
+
+/**
+ * The ONE `ProcessGraph` a superimposed `ProcessMap` renders: every activity/transition
+ * either side ever saw, painted with whichever side's stats are the "current" reading (`b`
+ * when present, `a` otherwise). `startActivities`/`endActivities` are recomputed from the
+ * represented activities themselves, so they can never disagree with what `activities`
+ * above actually carries. `totals` prefers `b`'s (the "current" period) and falls back to
+ * `a`'s only when `b` measured nothing at all (e.g. a `b` side still loading).
+ */
+export function diffToProcessGraph(diff: ProcessGraphDiff): ProcessGraph {
+  const activities: ActivityStats[] = diff.activities.map(representative);
+  const transitions: TransitionStats[] = diff.transitions.map(representative);
+  const totals =
+    diff.totals.b.cases > 0 || diff.totals.b.events > 0 ? diff.totals.b : diff.totals.a;
+  return {
+    activities,
+    transitions,
+    startActivities: Object.fromEntries(
+      activities
+        .filter((activity) => activity.isStart)
+        .map((activity) => [activity.id, activity.cases]),
+    ),
+    endActivities: Object.fromEntries(
+      activities
+        .filter((activity) => activity.isEnd)
+        .map((activity) => [activity.id, activity.cases]),
+    ),
+    totals,
+  };
+}
+
+/** Diff state per activity id, straight off {@link ProcessGraphDiff.activities}. */
+export function diffStateByActivity(diff: ProcessGraphDiff): ReadonlyMap<string, DiffState> {
+  return new Map(diff.activities.map((entry) => [entry.id, entry.state]));
+}
+
+/**
+ * A synthetic `ActivityColorScale` that paints every activity by its DIFF STATE rather
+ * than its identity. `colorFor` is the only method `ProcessMap` itself calls (see
+ * `map-model.ts`'s `buildProcessMapModel`); `codeFor`/`labelFor`/`legend` exist only to
+ * satisfy the shared interface.
+ */
+export function diffColorScale(diff: ProcessGraphDiff): ActivityColorScale {
+  const states = diffStateByActivity(diff);
+  const colorFor = (activityId: string): ActivityColor => ({
+    token: DIFF_STATE_TOKEN[states.get(activityId) ?? "common"],
+  });
+  const legend: ActivityColorLegendEntry[] = diff.activities.map((entry) => ({
+    activityId: entry.id,
+    label: entry.id,
+    code: entry.id.slice(0, 2).toUpperCase(),
+    ...colorFor(entry.id),
+  }));
+  return {
+    colorFor,
+    codeFor: (activityId) => activityId.slice(0, 2).toUpperCase(),
+    labelFor: (activityId) => activityId,
+    legend,
+  };
+}

package/src/process-compare/index.ts

@@ -0,0 +1,23 @@
+/**
+ * ProcessCompare (RM-064) — public surface: the compare view, its sub-parts, and the pure
+ * diff-to-graph helpers a host can reuse to build its own superimposed reading.
+ */
+export { ProcessCompare } from "./process-compare";
+export type {
+  ProcessCompareMode,
+  ProcessCompareProps,
+  ProcessCompareSide,
+} from "./process-compare";
+export { CompareSide } from "./compare-side";
+export type { CompareSideProps } from "./compare-side";
+export { CompareKpiStrip } from "./compare-kpi-strip";
+export type { CompareKpiStripProps, CompareKpiStripSide } from "./compare-kpi-strip";
+export { resolveCompareKpis } from "./compare-model";
+export type { CompareSideInput, CompareSideKpis } from "./compare-model";
+export {
+  DIFF_STATE_TOKEN,
+  diffColorScale,
+  diffStateByActivity,
+  diffToProcessGraph,
+  EMPTY_PROCESS_GRAPH,
+} from "./diff-to-graph";

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

@@ -0,0 +1,184 @@
+import "@xyflow/react/dist/style.css";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useState } from "react";
+import { expect, userEvent, waitFor, within } from "storybook/test";
+import { discoverGraph } from "../core/discover-graph";
+import { generateSyntheticLog } from "../core/fixtures/synthetic-log";
+import type { AbstractionOptions } from "../core/abstract-graph";
+import type { ProcessGraph } from "../core/types";
+import { ProcessCompare, type ProcessCompareProps } from "./process-compare";
+
+const beforeLog = generateSyntheticLog({ cases: 240, seed: 42 });
+const afterLog = generateSyntheticLog({ cases: 300, seed: 7 });
+const beforeGraph = discoverGraph(beforeLog);
+const afterGraph = discoverGraph(afterLog);
+
+const IDENTITY_ABSTRACTION: AbstractionOptions = {
+  activities: 1,
+  paths: 1,
+  invert: false,
+  keepConnected: true,
+};
+
+/** A tiny, hand-built graph — used where two SHARED-vocabulary synthetic logs would not do. */
+function tinyGraph(id: string): ProcessGraph {
+  return {
+    activities: [
+      {
+        id,
+        label: id,
+        instances: 5,
+        cases: 5,
+        isStart: true,
+        isEnd: true,
+        duration: { min: 1, max: 1, mean: 1, median: 1, p90: 1, sum: 5, trimmedMean: 1 },
+      },
+    ],
+    transitions: [],
+    startActivities: { [id]: 5 },
+    endActivities: { [id]: 5 },
+    totals: { cases: 5, events: 5, variants: 1 },
+  };
+}
+
+/** Owns `abstraction` the way a real playbook would, so the shared slider is interactive. */
+function Stateful(props: Omit<ProcessCompareProps, "abstraction" | "onAbstractionChange">) {
+  const [abstraction, setAbstraction] = useState<AbstractionOptions>(IDENTITY_ABSTRACTION);
+  return (
+    <ProcessCompare
+      {...props}
+      abstraction={abstraction}
+      onAbstractionChange={(next) => setAbstraction((prev) => ({ ...prev, ...next }))}
+    />
+  );
+}
+
+const meta = {
+  title: "Process/ProcessCompare",
+  component: ProcessCompare,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "fullscreen",
+    docs: {
+      description: {
+        component:
+          "Side-by-side or superimposed diff of two process maps — a before/after run, an " +
+          "A/B cohort, or any two discovered graphs. Both modes compose the shipped " +
+          "`ProcessMap` (twice for `side-by-side`, once over the union for " +
+          "`superimposed`) with ONE shared `AbstractionControls` and a `CompareKpiStrip` " +
+          "underneath. The common/A-only/B-only diff is never colour alone: superimposed " +
+          "mode paints each activity's accent with a diff-state token AND appends the diff " +
+          "state as real text to the activity's own title, read by AT as part of its " +
+          "accessible name — the `Legend` alongside states the same three words. " +
+          "Transitions carry no diff encoding of their own (no per-edge colour hook exists " +
+          "on `ProcessMap` without a change to that component, out of scope here).",
+      },
+    },
+  },
+  args: {
+    a: { label: "Before", graph: beforeGraph, log: beforeLog },
+    b: { label: "After", graph: afterGraph, log: afterLog },
+    metric: { node: "absolute_case", edge: "absolute" },
+  },
+  render: (args) => (
+    <div className="h-[42rem] w-full bg-background p-4">
+      <Stateful {...args} />
+    </div>
+  ),
+} satisfies Meta<typeof ProcessCompare>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** Two independent panes, one shared abstraction slider above both. */
+export const SideBySide: Story = {
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await waitFor(() =>
+      expect(canvas.getAllByRole("heading", { level: 3 }).map((h) => h.textContent)).toEqual([
+        "Before",
+        "After",
+      ]),
+    );
+    // One shared control, not one per side.
+    expect(canvas.getAllByRole("group", { name: "Abstraction" })).toHaveLength(1);
+  },
+};
+
+/** One map over the union of both graphs, with the diff legend and diff-labelled titles. */
+export const Superimposed: Story = {
+  args: { mode: "superimposed" },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await waitFor(() => expect(canvas.getByText("common")).toBeInTheDocument());
+    expect(canvas.getByText("Before only")).toBeInTheDocument();
+    expect(canvas.getByText("After only")).toBeInTheDocument();
+  },
+};
+
+/**
+ * The named use case: a "Before"/"After" pair from the same process, toggled into the
+ * accessible table twin, which both sides always share (RM-064's own contract — the same
+ * numbers the canvas draws, never a second source of truth).
+ */
+export const BeforeAfter: Story = {
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await userEvent.click(canvas.getByRole("switch", { name: "Table view" }));
+    await waitFor(() => expect(canvas.getAllByRole("table")).toHaveLength(4));
+  },
+};
+
+/** Two graphs that share no activity at all — every entry reads A-only or B-only. */
+export const NoOverlap: Story = {
+  args: {
+    a: { label: "Before", graph: tinyGraph("OnlyBefore") },
+    b: { label: "After", graph: tinyGraph("OnlyAfter") },
+    mode: "superimposed",
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await waitFor(() => expect(canvas.getByText("Before only")).toBeInTheDocument());
+    expect(canvas.getByText("After only")).toBeInTheDocument();
+    await userEvent.click(canvas.getByRole("switch", { name: "Table view" }));
+    const activityTable = canvas.getAllByRole("table")[0]!;
+    const rowText = within(activityTable)
+      .getAllByRole("row")
+      .map((row) => row.textContent ?? "");
+    expect(rowText.some((text) => text.includes("common"))).toBe(false);
+  },
+};
+
+/** Neither side has a graph yet — every map's own loading panel, one shared control shell. */
+export const Loading: Story = {
+  args: {
+    a: { label: "Before", graph: undefined },
+    b: { label: "After", graph: undefined },
+    loading: true,
+  },
+};
+
+/** Two graphs with no activities — an abstraction that hid everything, or two empty logs. */
+export const Empty: Story = {
+  args: {
+    a: {
+      label: "Before",
+      graph: {
+        activities: [],
+        transitions: [],
+        startActivities: {},
+        endActivities: {},
+        totals: { cases: 0, events: 0, variants: 0 },
+      },
+    },
+    b: {
+      label: "After",
+      graph: {
+        activities: [],
+        transitions: [],
+        startActivities: {},
+        endActivities: {},
+        totals: { cases: 0, events: 0, variants: 0 },
+      },
+    },
+  },
+};