@elabs-ai/components-process 4.2.0 → 5.0.0

package/src/use-process-explorer/use-process-explorer.ts

@@ -62,7 +62,7 @@ import { discoverGraph } from "../core/discover-graph";
 import { durationStats } from "../core/duration-stats";
 import { extractVariants, variantKey } from "../core/extract-variants";
 import type { FilterSpec } from "../core/filter-log";
-import { filterLog } from "../core/filter-log";
+import { filterLog, filterNormalizedLog } from "../core/filter-log";
 import { reconcileGraph } from "../core";
 import type { EventLog, FrequencyMode, PerformanceAgg, ProcessGraph, Variant } from "../core/types";
 import {
@@ -95,8 +95,15 @@ export interface ProcessExplorerMetricSpec {
  * variant selection — a case a click on the process map can never produce, but a click on a
  * variant row can. The widening is local to this hook's own type alias; it does not touch
  * `ProcessFilterIntent` or `ProcessMap`'s menu, which still only ever emits the original four.
+ *
+ * `{ kind: "cases" }` joins it for the same reason: `DottedChart` (RM-059) and
+ * `PerformanceSpectrum` (RM-060) brush a set of case ids, so their `onFilterIntent` can be
+ * wired straight to `applyIntent`.
  */
-export type FilterIntent = ProcessFilterIntent | Extract<FilterSpec, { kind: "variant" }>;
+export type FilterIntent =
+  | ProcessFilterIntent
+  | Extract<FilterSpec, { kind: "variant" }>
+  | Extract<FilterSpec, { kind: "cases" }>;
 
 /** Options for {@link useProcessExplorer}. */
 export interface ProcessExplorerOptions {
@@ -138,6 +145,17 @@ export interface UseProcessExplorerResult {
   applyIntent(intent: FilterIntent): void;
   clearIntent(index: number): void;
   intents: FilterIntent[];
+  /**
+   * How many cases EACH active intent alone excludes — parallel to {@link intents} (same
+   * index), for `ProcessFilterBar` (RM-056, #205)'s per-chip "excluded N" count. For intent
+   * `i`, this is the case count filtered by every intent BEFORE `i` minus the case count
+   * filtered by every intent up to and including `i` — so it isolates what `i` itself
+   * removes from the chain, not what the whole chain removes. `[]` when no intents are
+   * active. Computed with one `filterNormalizedLog` call per prefix (`n + 1` calls for `n`
+   * intents, reusing each prefix's count for both the term it ends and the term it starts),
+   * never `n²` — additive field, `intents`/`applyIntent`/`clearIntent` are unchanged.
+   */
+  excludedByIntent: number[];
   filteredLog: EventLog;
   /**
    * Per-element states the active filter contributes — pass straight into `ProcessMap`'s
@@ -419,6 +437,19 @@ export function useProcessExplorer(
     [log, intents],
   );
 
+  // One `filterNormalizedLog` call per prefix (`0..intents.length`, so `n + 1` for `n`
+  // intents) — `prefixCaseCounts[i]` is the case count after applying only the first `i`
+  // intents. Each intent's own excluded count is then just the drop between two adjacent
+  // prefixes, so nothing here is O(intents²) (RM-056, #205).
+  const excludedByIntent = useMemo(() => {
+    if (intents.length === 0) return [];
+    const prefixCaseCounts: number[] = [];
+    for (let i = 0; i <= intents.length; i += 1) {
+      prefixCaseCounts.push(filterNormalizedLog(log, intents.slice(0, i)).totals.cases);
+    }
+    return intents.map((_, i) => prefixCaseCounts[i]! - prefixCaseCounts[i + 1]!);
+  }, [log, intents]);
+
   // Two independent discoveries — see the module docblock. `variants`, `kpis` and `rework`
   // read the FILTERED one; `graph` reads BOTH, full first through abstraction, then
   // reconciled against filtered (Invariant F: filtering re-inks, never removes).
@@ -529,6 +560,7 @@ export function useProcessExplorer(
     applyIntent,
     clearIntent,
     intents,
+    excludedByIntent,
     filteredLog,
     selectionStates,
     hiddenCounts: graph.hidden,

package/src/variant-explorer/coverage-bar.tsx

@@ -0,0 +1,36 @@
+"use client";
+
+/**
+ * A variant's share of cases as a bar plus its printed percentage (RM-054).
+ *
+ * Composes `@elabs-ai/components-ui`'s `Progress` rather than drawing a bar. The bar is
+ * `aria-hidden`: the same number is printed beside it and is part of the row's accessible
+ * name, so a progressbar per row would only add 2 000 redundant announcements.
+ */
+import { forwardRef, type HTMLAttributes } from "react";
+import { Progress } from "@elabs-ai/components-ui";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+
+export interface VariantCoverageBarProps extends HTMLAttributes<HTMLDivElement> {
+  /** `0..1`. */
+  share: number;
+  /** The share, already formatted for display. */
+  valueLabel: string;
+}
+
+export const VariantCoverageBar = forwardRef<HTMLDivElement, VariantCoverageBarProps>(
+  function VariantCoverageBar({ share, valueLabel, className, ...props }, ref) {
+    const percent = Math.min(100, Math.max(0, share * 100));
+    return (
+      <div
+        ref={ref}
+        data-slot="variant-explorer-coverage"
+        className={cn("flex min-w-0 items-center gap-2", className)}
+        {...props}
+      >
+        <Progress aria-hidden="true" value={percent} className="h-1.5 min-w-8 flex-1" />
+        <span className="w-12 shrink-0 text-end text-meta tabular-nums">{valueLabel}</span>
+      </div>
+    );
+  },
+);

package/src/variant-explorer/index.ts

@@ -0,0 +1,16 @@
+/**
+ * VariantExplorer (RM-054) — public surface: the explorer, its labels, and the pure
+ * coverage-selection helper a host can reuse to preselect "the top N % of paths".
+ */
+export {
+  VARIANT_EXPLORER_DEFAULT_LABELS,
+  VARIANT_EXPLORER_ROW_HEIGHT,
+  VariantExplorer,
+} from "./variant-explorer";
+export type {
+  VariantExplorerLabels,
+  VariantExplorerProps,
+  VariantSelectMode,
+} from "./variant-explorer";
+export { selectVariantsByCoverage, VARIANT_EXPLORER_COLUMNS } from "./variant-explorer-model";
+export type { VariantExplorerColumn } from "./variant-explorer-model";

package/src/variant-explorer/sequence-chips.tsx

@@ -0,0 +1,103 @@
+"use client";
+
+/**
+ * One variant's activity sequence as a row of chips (RM-054).
+ *
+ * Each chip is an activity: an identity swatch painted from the shared
+ * `ActivityColorScale` (the same `activityAccentStyle` `ProcessActivityNode` uses, so the
+ * two views cannot disagree) plus the activity's label — or, in the abbreviated
+ * "DNA strip", its two-character code. Colour is never the only channel: the text always
+ * names the activity, and the whole strip is one `role="img"` whose accessible name lists
+ * the full sequence, so an abbreviated code never reaches a screen reader in place of a
+ * name. HTML spans, not SVG — nothing here needs a coordinate system.
+ */
+import { forwardRef, type HTMLAttributes } from "react";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+import type { ActivityColorScale } from "../core/activity-color-scale";
+import { activityAccentStyle } from "../process-map/activity-accent";
+
+export interface VariantSequenceChipsProps extends HTMLAttributes<HTMLDivElement> {
+  sequence: readonly string[];
+  colorScale: ActivityColorScale;
+  /** Two-character codes instead of full labels. */
+  abbreviate?: boolean;
+  /**
+   * `"swatch"` drops the text and draws each activity as one identity block — the densest
+   * strip, for a narrow rail where even two-character codes leave room for three steps.
+   * The strip's own accessible name (and `title`) still lists the full sequence, and each
+   * block carries its activity as `title`, so a name is always one hover away. Wins over
+   * `abbreviate`. @default "text"
+   */
+  display?: "text" | "swatch";
+  /** Accessible name for the strip — the full sequence in words. */
+  label: string;
+}
+
+export const VariantSequenceChips = forwardRef<HTMLDivElement, VariantSequenceChipsProps>(
+  function VariantSequenceChips(
+    { sequence, colorScale, abbreviate = false, display = "text", label, className, ...props },
+    ref,
+  ) {
+    return (
+      <div
+        ref={ref}
+        role="img"
+        aria-label={label}
+        title={label}
+        data-slot="variant-explorer-sequence"
+        data-abbreviated={abbreviate ? "true" : undefined}
+        data-display={display === "swatch" ? "swatch" : undefined}
+        className={cn(
+          "flex min-w-0 flex-nowrap items-center overflow-hidden",
+          display === "swatch" || abbreviate ? "gap-0.5" : "gap-1",
+          className,
+        )}
+        {...props}
+      >
+        {sequence.map((activityId, position) => {
+          const color = colorScale.colorFor(activityId);
+          if (display === "swatch") {
+            return (
+              <span
+                key={`${position}:${activityId}`}
+                data-slot="variant-explorer-chip"
+                data-activity={activityId}
+                data-color-token={color.token}
+                data-pattern={color.pattern}
+                title={colorScale.labelFor(activityId)}
+                className="h-4 w-2 shrink-0 rounded-sm"
+                style={activityAccentStyle(color)}
+              />
+            );
+          }
+          return (
+            <span
+              // A sequence may repeat an activity (rework), so the id alone is not unique;
+              // the position within an immutable sequence is the stable identity here.
+              key={`${position}:${activityId}`}
+              data-slot="variant-explorer-chip"
+              data-activity={activityId}
+              data-color-token={color.token}
+              data-pattern={color.pattern}
+              className={cn(
+                "inline-flex shrink-0 items-center gap-1 rounded-sm border border-border bg-card text-meta text-foreground",
+                abbreviate ? "px-1 font-mono tabular-nums" : "max-w-40 px-1.5",
+              )}
+            >
+              <span
+                data-slot="variant-explorer-chip-swatch"
+                data-color-token={color.token}
+                data-pattern={color.pattern}
+                className="size-2 shrink-0 rounded-sm"
+                style={activityAccentStyle(color)}
+              />
+              <span className="truncate">
+                {abbreviate ? colorScale.codeFor(activityId) : colorScale.labelFor(activityId)}
+              </span>
+            </span>
+          );
+        })}
+      </div>
+    );
+  },
+);

package/src/variant-explorer/variant-explorer-model.ts

@@ -0,0 +1,42 @@
+/**
+ * Pure helpers behind `VariantExplorer` (RM-054) — no React, so the selection semantics
+ * are unit-testable on their own and identical on every render.
+ */
+import type { Variant } from "../core/types";
+
+/** The optional numeric columns a variant row can show, in display order. */
+export type VariantExplorerColumn = "cases" | "coverage" | "medianDuration";
+
+/** Every column, in the order the explorer renders them. */
+export const VARIANT_EXPLORER_COLUMNS: readonly VariantExplorerColumn[] = Object.freeze([
+  "cases",
+  "coverage",
+  "medianDuration",
+]);
+
+/**
+ * The smallest prefix of `variants` whose `cumulativeShare` reaches `target`.
+ *
+ * `variants` is expected in `extractVariants` order (count descending, fully tie-broken),
+ * so the prefix is the set of most frequent paths that together cover `target` of the
+ * cases. Deterministic: the same variants and target always yield the same id list. A
+ * target of `0` or less selects nothing; a target above the last variant's share selects
+ * every variant. A tiny epsilon absorbs float noise in `cumulativeShare` so a `0.5`
+ * target is met by a variant whose share prints as exactly 50 %.
+ */
+export function selectVariantsByCoverage(variants: readonly Variant[], target: number): string[] {
+  if (!(target > 0)) return [];
+  const ids: string[] = [];
+  for (const variant of variants) {
+    ids.push(variant.id);
+    if (variant.cumulativeShare >= target - 1e-9) break;
+  }
+  return ids;
+}
+
+/** Fill `{name}` placeholders in a labels string. Unknown names are left as written. */
+export function fillLabel(template: string, vars: Record<string, string | number>): string {
+  return template.replace(/\{(\w+)\}/g, (match, key: string) =>
+    key in vars ? String(vars[key]) : match,
+  );
+}

package/src/variant-explorer/variant-explorer.stories.tsx

@@ -0,0 +1,226 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { useCallback, useMemo, useState } from "react";
+import { expect, userEvent, waitFor, within } from "storybook/test";
+import { activityColorScale } from "../core/activity-color-scale";
+import { discoverGraph } from "../core/discover-graph";
+import { extractVariants } from "../core/extract-variants";
+import { generateBpi2012Subset } from "../core/fixtures/generate-bpi-2012-subset";
+import { generateSyntheticLog } from "../core/fixtures/synthetic-log";
+import type { Variant } from "../core/types";
+import {
+  VariantExplorer,
+  type VariantExplorerProps,
+  type VariantSelectMode,
+} from "./variant-explorer";
+
+const log = generateSyntheticLog({ cases: 400, seed: 42 });
+const graph = discoverGraph(log);
+const variants = extractVariants(log);
+const colorScale = activityColorScale(graph);
+
+const loanLog = generateBpi2012Subset({ cases: 300, seed: 3 });
+const loanVariants = extractVariants(loanLog);
+const loanColorScale = activityColorScale(discoverGraph(loanLog));
+
+/** 2 000 synthetic variants — the virtualization acceptance size. */
+const manyVariants: Variant[] = (() => {
+  const total = 2000;
+  const cases = (total * (total + 1)) / 2;
+  let cumulative = 0;
+  return Array.from({ length: total }, (_, i) => {
+    const base = variants[i % variants.length]!;
+    const count = total - i;
+    cumulative += count;
+    return {
+      ...base,
+      id: `${base.id}-${i}`,
+      count,
+      share: count / cases,
+      cumulativeShare: cumulative / cases,
+    };
+  });
+})();
+
+/** Owns the selection a playbook would own, so the stories are interactive. */
+function Stateful(
+  props: Omit<VariantExplorerProps, "onSelect" | "selectionStates"> & {
+    initialSelected?: string[];
+  },
+) {
+  const { initialSelected = [], ...rest } = props;
+  const [selected, setSelected] = useState<string[]>(initialSelected);
+  const onSelect = useCallback((ids: string[], mode: VariantSelectMode) => {
+    setSelected((current) => {
+      if (mode === "replace") return ids;
+      const next = new Set(current);
+      for (const id of ids) {
+        if (next.has(id)) next.delete(id);
+        else next.add(id);
+      }
+      return [...next];
+    });
+  }, []);
+  const selectionStates = useMemo(
+    () => ({ variants: Object.fromEntries(selected.map((id) => [id, "selected" as const])) }),
+    [selected],
+  );
+  return <VariantExplorer {...rest} selectionStates={selectionStates} onSelect={onSelect} />;
+}
+
+const meta = {
+  title: "Process/VariantExplorer",
+  component: VariantExplorer,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "padded",
+    docs: {
+      description: {
+        component:
+          "The ranked list of activity sequences in an event log. Each row shows the sequence as " +
+          "colour-keyed chips (the same colours `ProcessMap` paints when it gets the same " +
+          "`colorScale`), the number of cases, the share of cases covered and the median " +
+          "duration. It only emits `onSelect` — a playbook turns that into a variant filter. " +
+          "Rows are virtualized; the checkboxes form one roving tab stop (arrows, Page Up/Down, " +
+          "Home/End move; Space and Enter toggle).",
+      },
+    },
+  },
+  args: {
+    variants,
+    colorScale,
+    onSelect: () => {},
+  },
+  render: (args) => (
+    <div className="w-full max-w-4xl">
+      <Stateful {...args} />
+    </div>
+  ),
+} satisfies Meta<typeof VariantExplorer>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** The ten most frequent paths with every column. */
+export const TopTen: Story = {
+  args: { variants: variants.slice(0, 10) },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const rows = canvasElement.querySelectorAll('[data-slot="variant-explorer-row"]');
+    await expect(rows.length).toBe(10);
+    // Row click toggles the variant.
+    const firstSequence = within(rows[0] as HTMLElement).getByRole("img");
+    await userEvent.click(firstSequence);
+    await waitFor(() => expect(canvas.getAllByRole("checkbox")[0]).toBeChecked());
+  },
+};
+
+/**
+ * "Variant DNA": two-letter chips so long sequences fit; full names stay in the accessible
+ * name. A loan-application log with more than eleven activities, so the rarer activities
+ * share the hatched "other" swatch.
+ */
+export const DnaStrip: Story = {
+  args: { variants: loanVariants, colorScale: loanColorScale, abbreviate: true },
+  play: async ({ canvasElement }) => {
+    await expect(canvasElement.querySelector('[data-pattern="other"]')).not.toBeNull();
+  },
+};
+
+/**
+ * `sequenceDisplay="swatch"`: every step is one identity block with no text — the densest
+ * strip, for a rail too narrow for codes. Hover a block for its activity; the strip's
+ * accessible name still lists the full sequence.
+ */
+export const SwatchStrip: Story = {
+  args: {
+    variants: loanVariants,
+    colorScale: loanColorScale,
+    sequenceDisplay: "swatch",
+    columns: ["cases"],
+  },
+  decorators: [
+    (StoryFn) => (
+      <div className="w-80">
+        <StoryFn />
+      </div>
+    ),
+  ],
+};
+
+/** The coverage slider selects the fewest paths that cover the target share of cases. */
+export const CoverageSlider: Story = {
+  args: { coverageTarget: 0.8, onFilterIntent: () => {} },
+};
+
+/** Two variants already selected; keyboard selection with arrows and Space. */
+export const WithSelection: Story = {
+  render: (args) => (
+    <div className="w-full max-w-4xl">
+      <Stateful {...args} initialSelected={[variants[0]!.id, variants[2]!.id]} />
+    </div>
+  ),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const boxes = canvas.getAllByRole("checkbox");
+    await expect(boxes[0]).toBeChecked();
+    await expect(boxes[2]).toBeChecked();
+
+    boxes[0]!.focus();
+    await userEvent.keyboard("{ArrowDown}");
+    const second = canvasElement.querySelector<HTMLElement>(
+      '[data-index="1"] [data-slot="checkbox"]',
+    );
+    await waitFor(() => expect(second).toHaveFocus());
+    await userEvent.keyboard(" ");
+    await waitFor(() => expect(second).toBeChecked());
+  },
+};
+
+/** The accessible table twin — the same numbers as the list, as a real table. */
+export const TableView: Story = {
+  args: { variants: variants.slice(0, 12), tableView: true },
+};
+
+/** Waiting for variants. */
+export const Loading: Story = {
+  args: { variants: [], loading: true },
+};
+
+/** A filter left no cases. */
+export const Empty: Story = {
+  args: { variants: [] },
+};
+
+/**
+ * 2 000 variants. The play test scrolls the list and asserts the number of mounted rows
+ * stays bounded — the virtualization that keeps scrolling smooth. It does not time frames,
+ * which is too noisy to gate CI on.
+ */
+export const TwoThousandVariants: Story = {
+  args: { variants: manyVariants, abbreviate: true },
+  play: async ({ canvasElement }) => {
+    const rows = () => canvasElement.querySelectorAll('[data-slot="variant-explorer-row"]').length;
+    await waitFor(() => expect(rows()).toBeGreaterThan(0));
+    const initial = rows();
+    await expect(initial).toBeLessThan(60);
+
+    const viewport = canvasElement.querySelector<HTMLElement>(
+      '[data-slot="variant-explorer-viewport"]',
+    )!;
+    for (const top of [8_000, 40_000, 79_000]) {
+      viewport.scrollTop = top;
+      await waitFor(() =>
+        expect(
+          canvasElement.querySelector(`[data-index="${Math.floor(top / 40) + 1}"]`),
+        ).not.toBeNull(),
+      );
+      await expect(rows()).toBeLessThan(60);
+    }
+  },
+};
+
+/** Decoration dial at 10 — chips and bars are marks inside a control-like row, so they stay put. */
+export const HighDecoration: Story = {
+  tags: ["!dev"],
+  globals: { decoration: "10" },
+  args: { variants: variants.slice(0, 10), coverageTarget: 0.5 },
+};