@elabs-ai/components-process 4.1.0

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

@@ -0,0 +1,128 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, within } from "storybook/test";
+import { ProcessKpiStrip } from "./process-kpi-strip";
+
+const meta = {
+  title: "Process/ProcessKpiStrip",
+  component: ProcessKpiStrip,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Six KPI tiles for a process-mining session, built on `@elabs-ai/components-charts`' " +
+          "`MetricGrid`/`MetricCard` rather than authoring a new tile (ADR 0012). Cases, " +
+          "events, variants, median throughput, and rework rate always have a real number; " +
+          "conformance is the one tile that can genuinely have no value yet — no conformance " +
+          "checking has run — and renders a 'Not available' state rather than a fabricated 0%.",
+      },
+    },
+  },
+} satisfies Meta<typeof ProcessKpiStrip>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const kpis = {
+  cases: 240,
+  events: 1_842,
+  variants: 37,
+  medianThroughput: 3 * 24 * 60 * 60 * 1000,
+  reworkRate: 0.18,
+};
+
+/** All six tiles with real values, including a measured conformance score. */
+export const Default: Story = {
+  args: { kpis, conformance: 0.91 },
+};
+
+/** No conformance model has run yet — a genuine "not available" state, not a fabricated 0%. */
+export const ConformanceUnavailable: Story = {
+  args: { kpis, conformance: null },
+};
+
+/**
+ * Every tile carries a trend sparkline alongside its headline number (#359: all six, not
+ * five — a missing `medianThroughput` series used to leave that one tile with no mark).
+ */
+export const WithTrends: Story = {
+  args: {
+    kpis,
+    conformance: 0.91,
+    trends: {
+      cases: [180, 190, 205, 198, 220, 232, 240],
+      events: [1200, 1350, 1480, 1520, 1690, 1780, 1842],
+      variants: [22, 25, 28, 30, 33, 35, 37],
+      medianThroughput: [
+        4 * 24 * 60 * 60 * 1000,
+        3.6 * 24 * 60 * 60 * 1000,
+        3.4 * 24 * 60 * 60 * 1000,
+        3.2 * 24 * 60 * 60 * 1000,
+        3.1 * 24 * 60 * 60 * 1000,
+        3.05 * 24 * 60 * 60 * 1000,
+        3 * 24 * 60 * 60 * 1000,
+      ],
+      reworkRate: [0.24, 0.22, 0.21, 0.2, 0.19, 0.18, 0.18],
+      conformance: [0.82, 0.84, 0.86, 0.87, 0.89, 0.9, 0.91],
+    },
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    // #359 lock: every sparkline's accessible name describes the trend, never repeats the
+    // tile's own label.
+    for (const label of [
+      "Cases",
+      "Events",
+      "Variants",
+      "Median throughput",
+      "Rework rate",
+      "Conformance",
+    ]) {
+      const sparkline = canvas.getByRole("img", { name: new RegExp(`^${label}, `) });
+      await expect(sparkline).not.toHaveAccessibleName(label);
+    }
+  },
+};
+
+/** No data yet — `loading` reserves every tile's final shape (`MetricGrid`'s own skeleton). */
+export const Loading: Story = {
+  args: { kpis, conformance: 0.91, loading: true },
+};
+
+/**
+ * Regression lock (RM-052 round 2, #227, F3): the conformance tile must occupy the SAME
+ * box height whether or not a conformance score has actually been measured. Before the
+ * fix, `description` was only ever given a value in the "not available" branch, so the
+ * measured and unavailable states rendered different heights — the tile visibly reflowed
+ * depending on which conformance state a reader happened to see. Renders both states
+ * side by side and asserts the conformance tile's own box is pixel-identical between
+ * them.
+ */
+export const ReflowRegressionLock: Story = {
+  render: () => (
+    <div className="flex flex-col gap-6">
+      <ProcessKpiStrip kpis={kpis} conformance={0.91} data-testid="measured" />
+      <ProcessKpiStrip kpis={kpis} conformance={null} data-testid="unavailable" />
+    </div>
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const measuredStrip = canvas.getByTestId("measured");
+    const unavailableStrip = canvas.getByTestId("unavailable");
+
+    const conformanceTileHeight = (strip: HTMLElement): number => {
+      const label = within(strip).getByText("Conformance");
+      const tile = label.closest('[class*="rounded-lg"]');
+      if (!tile) throw new Error("Could not locate the conformance tile's own card element");
+      return tile.getBoundingClientRect().height;
+    };
+
+    const measuredHeight = conformanceTileHeight(measuredStrip);
+    const unavailableHeight = conformanceTileHeight(unavailableStrip);
+
+    // Pixel-identical, not merely "close" — both states render the exact same DOM shape
+    // (a `<p>` wrapping either a visible or an `invisible` copy of the same hint string),
+    // so nothing here should be able to introduce even a sub-pixel difference.
+    await expect(measuredHeight).toBe(unavailableHeight);
+    await expect(measuredHeight).toBeGreaterThan(0);
+  },
+};

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

@@ -0,0 +1,106 @@
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+import { ProcessKpiStrip, type ProcessKpiStripKpis } from "./process-kpi-strip";
+
+afterEach(cleanup);
+
+const kpis: ProcessKpiStripKpis = {
+  cases: 240,
+  events: 1_842,
+  variants: 37,
+  medianThroughput: 3 * 24 * 60 * 60 * 1000,
+  reworkRate: 0.18,
+};
+
+describe("ProcessKpiStrip — rendering", () => {
+  it("renders all six KPI labels", () => {
+    render(<ProcessKpiStrip kpis={kpis} conformance={0.91} />);
+    expect(screen.getByText("Cases")).toBeInTheDocument();
+    expect(screen.getByText("Events")).toBeInTheDocument();
+    expect(screen.getByText("Variants")).toBeInTheDocument();
+    expect(screen.getByText("Median throughput")).toBeInTheDocument();
+    expect(screen.getByText("Rework rate")).toBeInTheDocument();
+    expect(screen.getByText("Conformance")).toBeInTheDocument();
+  });
+});
+
+describe("ProcessKpiStrip — conformance unavailable (the RM-052 acceptance criterion)", () => {
+  it("renders a real 'not available' state instead of a fabricated 0% when conformance is null", () => {
+    render(<ProcessKpiStrip kpis={kpis} conformance={null} />);
+    expect(screen.getByText("Not available")).toBeInTheDocument();
+    expect(screen.getByText("Run conformance checking to see this metric.")).toBeInTheDocument();
+    // Never render a numeric 0% in the gap — that would read as a real, alarming measurement.
+    expect(screen.queryByText("0%")).not.toBeInTheDocument();
+  });
+
+  it("renders a real percentage once conformance has actually been measured", () => {
+    render(<ProcessKpiStrip kpis={kpis} conformance={0.91} />);
+    expect(screen.queryByText("Not available")).not.toBeInTheDocument();
+    expect(screen.getByText("91%")).toBeInTheDocument();
+  });
+});
+
+describe("ProcessKpiStrip — loading", () => {
+  it("does not throw and reserves the region's live-announcement role while loading", () => {
+    render(<ProcessKpiStrip kpis={kpis} conformance={0.91} loading />);
+    expect(screen.getByRole("status")).toBeInTheDocument();
+  });
+});
+
+// #359 — a sparkline's accessible name must describe the TREND, not repeat the tile's own
+// label. Passing the label straight through overrides Sparkline's own, more informative
+// default, so a screen-reader user hears the tile's name twice and learns nothing about
+// the series.
+describe("ProcessKpiStrip — trend sparkline accessible names (#359)", () => {
+  const DAY = 24 * 60 * 60 * 1000;
+  const trends = {
+    cases: [180, 190, 205, 198, 220, 232, 240],
+    events: [1200, 1350, 1480, 1520, 1690, 1780, 1842],
+    variants: [22, 25, 28, 30, 33, 35, 37],
+    medianThroughput: [4 * DAY, 3.6 * DAY, 3.4 * DAY, 3.2 * DAY, 3.1 * DAY, 3.05 * DAY, 3 * DAY],
+    reworkRate: [0.24, 0.22, 0.21, 0.2, 0.19, 0.18, 0.18],
+    conformance: [0.82, 0.84, 0.86, 0.87, 0.89, 0.9, 0.91],
+  };
+
+  it("never names a sparkline the same as its tile's own label", () => {
+    render(<ProcessKpiStrip kpis={kpis} conformance={0.91} trends={trends} />);
+    for (const label of [
+      "Cases",
+      "Events",
+      "Variants",
+      "Median throughput",
+      "Rework rate",
+      "Conformance",
+    ]) {
+      const sparkline = screen.getByRole("img", { name: new RegExp(`^${label}, `) });
+      expect(sparkline).not.toHaveAccessibleName(label);
+    }
+  });
+
+  it("describes the direction and the formatted first/last values, using each tile's own formatter", () => {
+    render(<ProcessKpiStrip kpis={kpis} conformance={0.91} trends={trends} />);
+
+    expect(screen.getByRole("img", { name: /^Cases,/ })).toHaveAccessibleName(
+      "Cases, 7-period trend, rising from 180 to 240",
+    );
+    expect(screen.getByRole("img", { name: /^Events,/ })).toHaveAccessibleName(
+      "Events, 7-period trend, rising from 1,200 to 1,842",
+    );
+    expect(screen.getByRole("img", { name: /^Variants,/ })).toHaveAccessibleName(
+      "Variants, 7-period trend, rising from 22 to 37",
+    );
+    // Duration, formatted with the same `formatDurationMs` the tile's own value uses —
+    // not a raw millisecond figure.
+    expect(screen.getByRole("img", { name: /^Median throughput,/ })).toHaveAccessibleName(
+      "Median throughput, 7-period trend, falling from 4.0 d to 3.0 d",
+    );
+    // Percentage, formatted the same way the tile's `valueFormat="percent"` renders it —
+    // not the raw 0..1 fraction.
+    expect(screen.getByRole("img", { name: /^Rework rate,/ })).toHaveAccessibleName(
+      "Rework rate, 7-period trend, falling from 24% to 18%",
+    );
+    expect(screen.getByRole("img", { name: /^Conformance,/ })).toHaveAccessibleName(
+      "Conformance, 7-period trend, rising from 82% to 91%",
+    );
+  });
+});

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

@@ -0,0 +1,237 @@
+"use client";
+
+/**
+ * ProcessKpiStrip — the six numbers every process-mining session opens with (RM-052,
+ * issue #227): cases, events, variants, median throughput, rework rate, and conformance.
+ *
+ * Built entirely on `MetricGrid`/`MetricCard` (`@elabs-ai/components-charts` /
+ * `@elabs-ai/components-ui`) — this file authors no grid, no live region and no
+ * loading skeleton of its own. `MetricGrid`'s own `loading` prop already forwards
+ * `loading`/`announceLoading={false}` to every `MetricCard` child and owns the single
+ * region-level `role="status"` announcement (loading-states.md §a11y, "one live region
+ * per region, not per box") — reusing it is what keeps this component from re-deriving
+ * that convention badly.
+ *
+ * ## Conformance never fabricates a number
+ *
+ * `conformance` is `number | null | undefined` on purpose: a fraction (0..1) once a
+ * conformance model has actually been fitted against the log, or `null`/`undefined`
+ * when none has. Rendering `0` in the gap would read as "0% conformant" — a real,
+ * alarming measurement — when the honest state is "not measured". The unavailable
+ * state renders a muted icon + word instead of a number, and carries its own
+ * `description` explaining why.
+ *
+ * ## The conformance tile never reflows across states (RM-052 round 2, #227, F3)
+ *
+ * `MetricCard` only reserves a description line when it is GIVEN a `description` — so
+ * passing `description={hasConformance ? undefined : hint}` (the naive reading) made the
+ * tile's own box height depend on the very state it's rendering: measured shorter with a
+ * conformance score, taller in the "not available" state. The fix keeps the description
+ * SLOT present in every state — loading, measured, and unavailable all pass a `description`
+ * — but only the unavailable state's text is visible; the measured state's copy of the same
+ * string is rendered `invisible` (`visibility: hidden` + `aria-hidden`), which reserves the
+ * identical line height without showing misleading or duplicated copy to a sighted or
+ * screen-reader user.
+ */
+import { type HTMLAttributes } from "react";
+import { CircleSlash2 } from "lucide-react";
+import { MetricCard, type LocaleContextValue } from "@elabs-ai/components-ui";
+import { useLocale } from "@elabs-ai/components-ui";
+import { MetricGrid } from "@elabs-ai/components-charts";
+import { Sparkline } from "@elabs-ai/components-charts";
+import { formatDurationMs } from "../process-map/map-model";
+
+export interface ProcessKpiStripKpis {
+  cases: number;
+  events: number;
+  variants: number;
+  medianThroughput: number;
+  reworkRate: number;
+}
+
+export type ProcessKpiStripTrendKey = keyof ProcessKpiStripKpis | "conformance";
+
+export interface ProcessKpiStripProps extends HTMLAttributes<HTMLDivElement> {
+  kpis: ProcessKpiStripKpis;
+  /** `0..1`, or `null`/`undefined` when no conformance model has been fitted. */
+  conformance?: number | null;
+  /** Optional per-tile trend series (oldest -> newest), keyed by KPI. */
+  trends?: Partial<Record<ProcessKpiStripTrendKey, number[]>>;
+  loading?: boolean;
+}
+
+/** How a trend's two endpoints are formatted — mirrors each tile's own headline format. */
+type TrendValueFormat = "count" | "duration" | "percent";
+
+/** The trend's direction, as the locale key for its word ("rising"/"falling"/"steady"). */
+function trendDirectionKey(
+  first: number,
+  last: number,
+):
+  | "process.kpiStrip.trendRising"
+  | "process.kpiStrip.trendFalling"
+  | "process.kpiStrip.trendSteady" {
+  if (last > first) return "process.kpiStrip.trendRising";
+  if (last < first) return "process.kpiStrip.trendFalling";
+  return "process.kpiStrip.trendSteady";
+}
+
+/** Format one trend endpoint the same way the tile's own headline value is formatted. */
+function formatTrendValue(
+  formatNumber: LocaleContextValue["formatNumber"],
+  value: number,
+  format: TrendValueFormat,
+): string {
+  switch (format) {
+    case "duration":
+      return formatDurationMs(value);
+    case "percent":
+      return formatNumber(value, { style: "percent", maximumFractionDigits: 1 });
+    case "count":
+    default:
+      return formatNumber(value);
+  }
+}
+
+/**
+ * A sparkline's text alternative (#359): the subject plus what the picture shows, not the
+ * subject alone — the tile's own label already names the subject, and `Sparkline`'s own
+ * default (which describes the series) is strictly more informative than repeating it.
+ * Numbers are formatted the same way the tile's own headline value is, so the visible and
+ * accessible readings never disagree (a raw 0.18 beside a tile printing 18% would).
+ */
+function trendVisual(
+  values: number[] | undefined,
+  subject: string,
+  format: TrendValueFormat,
+  t: LocaleContextValue["t"],
+  formatNumber: LocaleContextValue["formatNumber"],
+) {
+  if (!values || values.length === 0) return undefined;
+  const first = values[0]!;
+  const last = values[values.length - 1]!;
+  const label = t("process.kpiStrip.trendAlt", {
+    subject,
+    periods: values.length,
+    direction: t(trendDirectionKey(first, last)),
+    first: formatTrendValue(formatNumber, first, format),
+    last: formatTrendValue(formatNumber, last, format),
+  });
+  return <Sparkline values={values} label={label} />;
+}
+
+export function ProcessKpiStrip({
+  kpis,
+  conformance,
+  trends,
+  loading = false,
+  className,
+  ...props
+}: ProcessKpiStripProps) {
+  const { t, formatNumber } = useLocale();
+
+  const hasConformance = conformance !== null && conformance !== undefined;
+  const conformanceHint = t("process.kpiStrip.conformanceUnavailableHint");
+
+  return (
+    <div data-slot="process-kpi-strip" className={className} {...props}>
+      <MetricGrid columns={3} loading={loading}>
+        <MetricCard
+          label={t("process.kpiStrip.cases")}
+          value={kpis.cases}
+          announceLoading={false}
+          visual={trendVisual(trends?.cases, t("process.kpiStrip.cases"), "count", t, formatNumber)}
+        />
+        <MetricCard
+          label={t("process.kpiStrip.events")}
+          value={kpis.events}
+          announceLoading={false}
+          visual={trendVisual(
+            trends?.events,
+            t("process.kpiStrip.events"),
+            "count",
+            t,
+            formatNumber,
+          )}
+        />
+        <MetricCard
+          label={t("process.kpiStrip.variants")}
+          value={kpis.variants}
+          announceLoading={false}
+          visual={trendVisual(
+            trends?.variants,
+            t("process.kpiStrip.variants"),
+            "count",
+            t,
+            formatNumber,
+          )}
+        />
+        <MetricCard
+          label={t("process.kpiStrip.medianThroughput")}
+          value={formatDurationMs(kpis.medianThroughput)}
+          announceLoading={false}
+          visual={trendVisual(
+            trends?.medianThroughput,
+            t("process.kpiStrip.medianThroughput"),
+            "duration",
+            t,
+            formatNumber,
+          )}
+        />
+        <MetricCard
+          label={t("process.kpiStrip.reworkRate")}
+          value={kpis.reworkRate}
+          valueFormat="percent"
+          announceLoading={false}
+          visual={trendVisual(
+            trends?.reworkRate,
+            t("process.kpiStrip.reworkRate"),
+            "percent",
+            t,
+            formatNumber,
+          )}
+        />
+        <MetricCard
+          label={t("process.kpiStrip.conformance")}
+          value={
+            hasConformance ? (
+              (conformance as number)
+            ) : (
+              <span
+                data-slot="process-kpi-strip-conformance-unavailable"
+                className="text-title inline-flex items-center gap-1.5 text-muted-foreground"
+              >
+                <CircleSlash2 aria-hidden="true" className="size-5" />
+                {t("process.kpiStrip.conformanceUnavailable")}
+              </span>
+            )
+          }
+          valueFormat={hasConformance ? "percent" : undefined}
+          description={
+            hasConformance ? (
+              // Same slot, same height, every state (F3) — invisible rather than absent, so
+              // the tile's box never reflows depending on whether conformance was measured.
+              <span aria-hidden="true" className="invisible">
+                {conformanceHint}
+              </span>
+            ) : (
+              conformanceHint
+            )
+          }
+          announceLoading={false}
+          visual={
+            hasConformance
+              ? trendVisual(
+                  trends?.conformance,
+                  t("process.kpiStrip.conformance"),
+                  "percent",
+                  t,
+                  formatNumber,
+                )
+              : undefined
+          }
+        />
+      </MetricGrid>
+    </div>
+  );
+}

package/src/process-map/index.ts

@@ -0,0 +1,13 @@
+/**
+ * The process map (RM-051) — public surface.
+ *
+ * Only what a consumer composes with: the three components, the hover context two of them
+ * read, the layout hook, and the whole `map-model` vocabulary (the model is what keeps the
+ * canvas and the `tableView` twin printing identical numbers, so it is public on purpose).
+ */
+export * from "./map-model";
+export * from "./process-map";
+export * from "./process-map-context";
+export * from "./process-activity-node";
+export * from "./process-transition-edge";
+export * from "./use-process-layout";