@elabs-ai/components-process 4.1.0 → 5.0.0

package/src/violation-list/index.ts

@@ -0,0 +1,2 @@
+/** ViolationList (RM-062) — public surface. */
+export * from "./violation-list";

package/src/violation-list/violation-list.stories.tsx

@@ -0,0 +1,73 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, fn, userEvent, within } from "storybook/test";
+import { liftHappyPath } from "../core/reference-model";
+import { emptyDeviationCounts, tokenReplay } from "../core/token-replay";
+import {
+  CONFORMANCE_FIXTURE_LOG,
+  CONFORMANCE_FIXTURE_PATH,
+} from "../conformance-overlay/conformance-fixture";
+import { ViolationList } from "./violation-list";
+
+const conformance = tokenReplay(CONFORMANCE_FIXTURE_LOG, liftHappyPath(CONFORMANCE_FIXTURE_PATH));
+
+const meta = {
+  title: "Process/ViolationList",
+  component: ViolationList,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "padded",
+    docs: {
+      description: {
+        component:
+          "Deviations from a token-replay result, grouped by type and ranked by count, with " +
+          "each type’s share of cases and a final conforming row. Choosing a row emits a " +
+          '`{ kind: "cases", ids }` filter intent for exactly the cases that deviated that ' +
+          "way — the component never filters anything itself.",
+      },
+    },
+  },
+  args: { conformance, onFilterIntent: fn() },
+} satisfies Meta<typeof ViolationList>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** Ranked deviation types; a row click or Enter emits that row’s case ids. */
+export const Default: Story = {
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    await userEvent.click(canvas.getByRole("button", { name: /Skipped step/ }));
+    await expect(args.onFilterIntent).toHaveBeenLastCalledWith({
+      kind: "cases",
+      ids: ["c07", "c08"],
+    });
+    canvas.getByRole("button", { name: /Undesired activity/ }).focus();
+    await userEvent.keyboard("{Enter}");
+    await expect(args.onFilterIntent).toHaveBeenLastCalledWith({ kind: "cases", ids: ["c09"] });
+  },
+};
+
+/** Without `onFilterIntent` the rows are read-only — no buttons. */
+export const ReadOnly: Story = {
+  args: { onFilterIntent: undefined },
+  play: async ({ canvasElement }) => {
+    await expect(within(canvasElement).queryByRole("button")).toBeNull();
+  },
+};
+
+/** A replay over zero cases. */
+export const Empty: Story = {
+  args: {
+    conformance: {
+      overallFitness: 0,
+      traces: [],
+      deviationCounts: emptyDeviationCounts(),
+      perActivity: {},
+      perEdge: {},
+    },
+  },
+};
+
+/** Replay still running. */
+export const Loading: Story = {
+  args: { loading: true },
+};

package/src/violation-list/violation-list.test.tsx

@@ -0,0 +1,84 @@
+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 { liftHappyPath } from "../core/reference-model";
+import { emptyDeviationCounts, tokenReplay } from "../core/token-replay";
+import {
+  CONFORMANCE_FIXTURE_LOG,
+  CONFORMANCE_FIXTURE_PATH,
+} from "../conformance-overlay/conformance-fixture";
+import { ViolationList, violationRows } from "./violation-list";
+
+afterEach(cleanup);
+
+const conformance = tokenReplay(CONFORMANCE_FIXTURE_LOG, liftHappyPath(CONFORMANCE_FIXTURE_PATH));
+
+describe("violationRows", () => {
+  it("orders types by deviation count descending, then the conforming row", () => {
+    expect(violationRows(conformance).map((row) => row.kind)).toEqual([
+      "skipped",
+      "undesired",
+      "incomplete",
+      "conforming",
+    ]);
+  });
+
+  it("row case counts sum to the number of replayed cases (one type per case here)", () => {
+    const sum = violationRows(conformance).reduce((total, row) => total + row.caseIds.length, 0);
+    expect(sum).toBe(conformance.traces.length);
+  });
+
+  it("resolves exactly the case ids whose replay found that type", () => {
+    const rows = violationRows(conformance);
+    const expected = (type: string) =>
+      conformance.traces
+        .filter((trace) => trace.deviations.some((d) => d.type === type))
+        .map((trace) => trace.caseId);
+    for (const row of rows) {
+      if (row.kind === "conforming") continue;
+      expect(row.caseIds).toEqual(expected(row.kind));
+    }
+    expect(rows.find((row) => row.kind === "skipped")?.caseIds).toEqual(["c07", "c08"]);
+    expect(rows.find((row) => row.kind === "skipped")?.share).toBeCloseTo(0.2);
+  });
+});
+
+describe("ViolationList", () => {
+  it("emits a cases filter intent with that row's ids, from pointer and keyboard", async () => {
+    const onFilterIntent = vi.fn();
+    const user = userEvent.setup();
+    render(<ViolationList conformance={conformance} onFilterIntent={onFilterIntent} />);
+
+    await user.click(screen.getByRole("button", { name: /Skipped step/ }));
+    expect(onFilterIntent).toHaveBeenLastCalledWith({ kind: "cases", ids: ["c07", "c08"] });
+
+    screen.getByRole("button", { name: /Undesired activity/ }).focus();
+    await user.keyboard("{Enter}");
+    expect(onFilterIntent).toHaveBeenLastCalledWith({ kind: "cases", ids: ["c09"] });
+    expect(onFilterIntent).toHaveBeenCalledTimes(2);
+  });
+
+  it("prints share and case count per row, and the conforming total in the caption", () => {
+    render(<ViolationList conformance={conformance} />);
+    const row = screen.getByRole("row", { name: /Skipped step/ });
+    expect(within(row).getByText("20%")).toBeInTheDocument();
+    expect(within(row).getByText("2")).toBeInTheDocument();
+    expect(screen.getByText(/6 of 10 cases conform/)).toBeInTheDocument();
+    expect(screen.queryByRole("button")).toBeNull();
+  });
+
+  it("shows an empty panel for an empty replay and a loading panel while loading", () => {
+    const empty = {
+      overallFitness: 0,
+      traces: [],
+      deviationCounts: emptyDeviationCounts(),
+      perActivity: {},
+      perEdge: {},
+    };
+    const { unmount } = render(<ViolationList conformance={empty} />);
+    expect(screen.getByText("No cases replayed")).toBeInTheDocument();
+    unmount();
+    render(<ViolationList conformance={conformance} loading />);
+    expect(screen.getByRole("status")).toBeInTheDocument();
+  });
+});

package/src/violation-list/violation-list.tsx

@@ -0,0 +1,259 @@
+"use client";
+
+/**
+ * ViolationList — why cases lost fitness, one row per deviation type (RM-062).
+ *
+ * A `Table` (`@elabs-ai/components-ui`) over a `ConformanceResult` (RM-061): the deviation
+ * type, the share of cases carrying it and the number of those cases. Rows with at least
+ * one deviation are sorted by `deviationCounts` descending (ties keep `DEVIATION_TYPES`
+ * order); a final "Conforming" row counts the cases with no deviation at all, so the
+ * conforming vs non-conforming pair analysis §2 asks for reads off the same table.
+ *
+ * Choosing a row emits `{ kind: "cases", ids }` — exactly the case ids whose replay found
+ * that type — which a host hands straight to `filterLog`. The row's type cell is a real
+ * `<button>`, so the same action is keyboard-operable; the component never filters itself.
+ */
+import { forwardRef, useCallback, useMemo, type HTMLAttributes } from "react";
+import { ListFilter } from "lucide-react";
+import {
+  Button,
+  StatePanel,
+  Table,
+  TableBody,
+  TableCaption,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+  useLocale,
+} from "@elabs-ai/components-ui";
+import type { ConformanceResult } from "../core/conformance";
+import type { FilterSpec } from "../core/filter-log";
+import { DEVIATION_TYPES, type DeviationType } from "../core/token-replay";
+import { fillLabel } from "../variant-explorer/variant-explorer-model";
+
+/** What a row stands for: a deviation type, or the cases with none. */
+export type ViolationRowKind = DeviationType | "conforming";
+
+/** One row of {@link ViolationList}. */
+export interface ViolationRow {
+  kind: ViolationRowKind;
+  /** Deviations of this type across all cases (`0` for `"conforming"`). */
+  deviations: number;
+  /** Ids of the cases carrying at least one deviation of this type, in log order. */
+  caseIds: string[];
+  /** `caseIds.length / traces.length`; `0` for an empty log. */
+  share: number;
+}
+
+/** The filter a row emits — a strict subset of `/core`'s `FilterSpec`. */
+export type ViolationFilterIntent = Extract<FilterSpec, { kind: "cases" }>;
+
+/**
+ * The rows {@link ViolationList} renders, in order: every type with deviations, by count
+ * descending, then `"conforming"`.
+ */
+export function violationRows(conformance: ConformanceResult): ViolationRow[] {
+  const total = conformance.traces.length;
+  const byType = new Map<DeviationType, string[]>(DEVIATION_TYPES.map((type) => [type, []]));
+  const conforming: string[] = [];
+  for (const trace of conformance.traces) {
+    if (trace.deviations.length === 0) {
+      conforming.push(trace.caseId);
+      continue;
+    }
+    const seen = new Set<DeviationType>();
+    for (const deviation of trace.deviations) {
+      if (seen.has(deviation.type)) continue;
+      seen.add(deviation.type);
+      byType.get(deviation.type)?.push(trace.caseId);
+    }
+  }
+  const share = (count: number) => (total === 0 ? 0 : count / total);
+  const rows = DEVIATION_TYPES.filter((type) => conformance.deviationCounts[type] > 0)
+    .map((type, order) => ({ type, order }))
+    .sort(
+      (a, b) =>
+        conformance.deviationCounts[b.type] - conformance.deviationCounts[a.type] ||
+        a.order - b.order,
+    )
+    .map(({ type }): ViolationRow => {
+      const caseIds = byType.get(type) ?? [];
+      return {
+        kind: type,
+        deviations: conformance.deviationCounts[type],
+        caseIds,
+        share: share(caseIds.length),
+      };
+    });
+  rows.push({
+    kind: "conforming",
+    deviations: 0,
+    caseIds: conforming,
+    share: share(conforming.length),
+  });
+  return rows;
+}
+
+/** Every user-visible string. `{name}` placeholders are filled at render. */
+export interface ViolationListLabels {
+  undesired: string;
+  skipped: string;
+  wrongOrder: string;
+  wrongStart: string;
+  incomplete: string;
+  conforming: string;
+  columnType: string;
+  columnShare: string;
+  columnCases: string;
+  /** `{conforming}`, `{total}`. */
+  caption: string;
+  /** Appended to the caption when rows can be chosen. */
+  captionFilter: string;
+  loading: string;
+  empty: string;
+  emptyBody: string;
+}
+
+/** The shipped English labels. */
+export const VIOLATION_LIST_DEFAULT_LABELS: Readonly<ViolationListLabels> = Object.freeze({
+  undesired: "Undesired activity",
+  skipped: "Skipped step",
+  wrongOrder: "Wrong order",
+  wrongStart: "Wrong start",
+  incomplete: "Incomplete case",
+  conforming: "Conforming",
+  columnType: "Deviation",
+  columnShare: "Share of cases",
+  columnCases: "Cases",
+  caption: "Deviations by type — {conforming} of {total} cases conform.",
+  captionFilter: "Choose a row to filter the log to its cases.",
+  loading: "Replaying cases…",
+  empty: "No cases replayed",
+  emptyBody: "Replay an event log against a happy path to list its deviations.",
+});
+
+/** Props for {@link ViolationList}. */
+export interface ViolationListProps extends HTMLAttributes<HTMLDivElement> {
+  /** The replay result (`tokenReplay`). */
+  conformance: ConformanceResult;
+  /** When given, each row emits `{ kind: "cases", ids }` for its cases. */
+  onFilterIntent?: (intent: ViolationFilterIntent) => void;
+  /** No replay yet. Renders the loading panel rather than an empty table. */
+  loading?: boolean;
+  /** Override any user-visible string. */
+  labels?: Partial<ViolationListLabels>;
+}
+
+/**
+ * The violation list.
+ *
+ * @example
+ * ```tsx
+ * <ViolationList
+ *   conformance={tokenReplay(log, liftHappyPath(path))}
+ *   onFilterIntent={(intent) => explorer.applyIntent(intent)}
+ * />
+ * ```
+ */
+export const ViolationList = forwardRef<HTMLDivElement, ViolationListProps>(function ViolationList(
+  { conformance, onFilterIntent, loading = false, labels: labelOverrides, className, ...props },
+  ref,
+) {
+  const { formatNumber } = useLocale();
+  const labels = useMemo<ViolationListLabels>(
+    () => ({ ...VIOLATION_LIST_DEFAULT_LABELS, ...labelOverrides }),
+    [labelOverrides],
+  );
+  const rows = useMemo(() => violationRows(conformance), [conformance]);
+  const emit = useCallback(
+    (row: ViolationRow) => onFilterIntent?.({ kind: "cases", ids: row.caseIds }),
+    [onFilterIntent],
+  );
+
+  if (loading) {
+    return (
+      <div
+        ref={ref}
+        data-slot="violation-list"
+        data-state="loading"
+        className={className}
+        {...props}
+      >
+        <StatePanel kind="loading" title={labels.loading} />
+      </div>
+    );
+  }
+
+  const total = conformance.traces.length;
+  if (total === 0) {
+    return (
+      <div ref={ref} data-slot="violation-list" data-state="empty" className={className} {...props}>
+        <StatePanel kind="empty" title={labels.empty} description={labels.emptyBody} />
+      </div>
+    );
+  }
+
+  const conformingCount = rows[rows.length - 1]?.caseIds.length ?? 0;
+  const interactive = onFilterIntent !== undefined;
+
+  return (
+    <div ref={ref} data-slot="violation-list" className={className} {...props}>
+      <Table data-slot="violation-list-table">
+        <TableCaption>
+          {fillLabel(labels.caption, {
+            conforming: formatNumber(conformingCount),
+            total: formatNumber(total),
+          })}
+          {interactive ? ` ${labels.captionFilter}` : null}
+        </TableCaption>
+        <TableHeader>
+          <TableRow>
+            <TableHead scope="col">{labels.columnType}</TableHead>
+            <TableHead scope="col" className="text-end">
+              {labels.columnShare}
+            </TableHead>
+            <TableHead scope="col" className="text-end">
+              {labels.columnCases}
+            </TableHead>
+          </TableRow>
+        </TableHeader>
+        <TableBody>
+          {rows.map((row) => (
+            <TableRow
+              key={row.kind}
+              data-slot="violation-list-row"
+              data-kind={row.kind}
+              onClick={interactive ? () => emit(row) : undefined}
+            >
+              <TableHead scope="row" className="font-normal">
+                {interactive ? (
+                  // The row's click handler receives this button's click (keyboard Enter/Space
+                  // included) — one action, one handler, reachable without a pointer.
+                  <Button
+                    type="button"
+                    variant="ghost"
+                    size="sm"
+                    data-slot="violation-list-filter"
+                    className="-ms-3 gap-1.5"
+                  >
+                    <ListFilter aria-hidden="true" className="size-3.5" />
+                    {labels[row.kind]}
+                  </Button>
+                ) : (
+                  labels[row.kind]
+                )}
+              </TableHead>
+              <TableCell className="text-end tabular-nums">
+                {formatNumber(row.share, { style: "percent", maximumFractionDigits: 1 })}
+              </TableCell>
+              <TableCell className="text-end tabular-nums">
+                {formatNumber(row.caseIds.length)}
+              </TableCell>
+            </TableRow>
+          ))}
+        </TableBody>
+      </Table>
+    </div>
+  );
+});