@elabs-ai/components-process 4.2.0 → 5.1.0

package/src/dotted-chart/index.ts

@@ -0,0 +1,23 @@
+/**
+ * DottedChart (RM-059) — public surface: the chart, its labels, and the pure model a host
+ * can reuse (row order, brush enumeration, category colouring).
+ */
+export { DOTTED_CHART_DOT_RADIUS, DottedChart } from "./dotted-chart";
+export type {
+  DottedChartColor,
+  DottedChartDatum,
+  DottedChartFilterIntent,
+  DottedChartProps,
+} from "./dotted-chart";
+export { DOTTED_CHART_DEFAULT_LABELS } from "./dotted-chart-labels";
+export type { DottedChartLabels } from "./dotted-chart-labels";
+export { casesInBrush, computeDots, rankCategoryColors } from "./compute-dots";
+export type {
+  ComputeDotsOptions,
+  DottedChartCategory,
+  DottedChartDot,
+  DottedChartModel,
+  DottedChartRow,
+  DottedChartSort,
+  DottedChartX,
+} from "./compute-dots";

package/src/dotted-chart/use-element-size.ts

@@ -0,0 +1,33 @@
+"use client";
+
+import { useLayoutEffect, useState } from "react";
+
+/**
+ * The CSS-pixel size of an element, re-measured whenever it resizes. `0 × 0` until measured.
+ *
+ * Returns a CALLBACK ref (a state setter), so an element that mounts after the first render
+ * (a loading or table view switching to the plot) is still observed.
+ */
+export function useElementSize<E extends HTMLElement>() {
+  const [node, setNode] = useState<E | null>(null);
+  const [size, setSize] = useState({ width: 0, height: 0 });
+
+  useLayoutEffect(() => {
+    if (!node) return;
+    const measure = () => {
+      const rect = node.getBoundingClientRect();
+      const width = Math.round(rect.width);
+      const height = Math.round(rect.height);
+      setSize((current) =>
+        current.width === width && current.height === height ? current : { width, height },
+      );
+    };
+    measure();
+    if (typeof ResizeObserver !== "function") return;
+    const observer = new ResizeObserver(measure);
+    observer.observe(node);
+    return () => observer.disconnect();
+  }, [node]);
+
+  return [setNode, size] as const;
+}

package/src/happy-path-editor/happy-path-editor-context.ts

@@ -0,0 +1,81 @@
+"use client";
+
+/**
+ * The seam between `HappyPathEditor` and its step nodes (RM-062).
+ *
+ * React Flow renders a node from `data` alone, so the edit actions and the labels reach a
+ * step through this context rather than through per-node callbacks in `data` — node data
+ * stays the step itself, and the actions keep one identity per edit.
+ */
+import { createContext, use } from "react";
+import type { HappyPathStep } from "../core/reference-model";
+
+/** Every user-visible string of the editor. `{name}` placeholders are filled at render. */
+export interface HappyPathEditorLabels {
+  /** Accessible name of the canvas. `{path}` — the happy path's label. */
+  canvas: string;
+  /** Eyebrow above a step. `{n}` — the one-based position. */
+  step: string;
+  /** Accessible name of a step node. `{n}`, `{activity}`, `{flags}`. */
+  stepName: string;
+  /** Shown as a step's title while its activity is empty. */
+  untitled: string;
+  /** Accessible name of a step's activity field. `{n}`. */
+  activity: string;
+  /** Placeholder of the free-text activity field. */
+  activityPlaceholder: string;
+  optional: string;
+  repeatable: string;
+  /** Accessible name of a step's optional switch. `{activity}`. */
+  optionalFor: string;
+  /** Accessible name of a step's repeatable switch. `{activity}`. */
+  repeatableFor: string;
+  remove: string;
+  /** Accessible name of a step's remove button. `{activity}`. */
+  removeFor: string;
+  /** Accessible name of an edge's insert button. `{before}`, `{after}`. */
+  insertStep: string;
+  /** Label of the tail placeholder that appends a step. */
+  addStep: string;
+}
+
+/** The shipped English labels. */
+export const HAPPY_PATH_EDITOR_DEFAULT_LABELS: Readonly<HappyPathEditorLabels> = Object.freeze({
+  canvas: "Happy path editor — {path}",
+  step: "Step {n}",
+  stepName: "Step {n}: {activity}{flags}",
+  untitled: "Untitled step",
+  activity: "Activity for step {n}",
+  activityPlaceholder: "Activity name",
+  optional: "Optional",
+  repeatable: "Repeatable",
+  optionalFor: "Optional — {activity}",
+  repeatableFor: "Repeatable — {activity}",
+  remove: "Remove",
+  removeFor: "Remove {activity}",
+  insertStep: "Insert a step between {before} and {after}",
+  addStep: "Add step",
+});
+
+/** What a step node reads from its editor. */
+export interface HappyPathEditorContextValue {
+  labels: HappyPathEditorLabels;
+  availableActivities: readonly string[] | undefined;
+  updateStep: (index: number, patch: Partial<HappyPathStep>) => void;
+  removeStep: (index: number) => void;
+}
+
+const NOOP_CONTEXT: HappyPathEditorContextValue = {
+  labels: HAPPY_PATH_EDITOR_DEFAULT_LABELS,
+  availableActivities: undefined,
+  updateStep: () => {},
+  removeStep: () => {},
+};
+
+/** Provided by `HappyPathEditor`; a step rendered on its own reads inert defaults. */
+export const HappyPathEditorContext = createContext<HappyPathEditorContextValue>(NOOP_CONTEXT);
+
+/** Read the editor's labels and actions. */
+export function useHappyPathEditor(): HappyPathEditorContextValue {
+  return use(HappyPathEditorContext);
+}

package/src/happy-path-editor/happy-path-editor.stories.tsx

@@ -0,0 +1,116 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import "@xyflow/react/dist/style.css";
+import { useState } from "react";
+import { expect, fn, userEvent, waitFor, within } from "storybook/test";
+import type { HappyPath } from "../core/reference-model";
+import { HappyPathEditor, type HappyPathEditorProps } from "./happy-path-editor";
+
+const orderPath: HappyPath = {
+  id: "order",
+  label: "Order to cash",
+  steps: [{ activity: "Register" }, { activity: "Approve" }, { activity: "Pay" }],
+};
+const available = ["Register", "Check credit", "Approve", "Pay", "Escalate"];
+
+/** Owns the path the way an app would, so every edit is visible on the canvas. */
+function Stateful({ value: initial, onChange, ...props }: HappyPathEditorProps) {
+  const [value, setValue] = useState(initial);
+  return (
+    <HappyPathEditor
+      {...props}
+      value={value}
+      onChange={(next) => {
+        onChange(next);
+        setValue(next);
+      }}
+    />
+  );
+}
+
+const meta = {
+  title: "Process/HappyPathEditor",
+  component: HappyPathEditor,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "fullscreen",
+    docs: {
+      description: {
+        component:
+          "Edits the reference model token replay checks a log against. Steps are `FlowNode`s " +
+          "on a `CanvasShell`; the `FlowButtonEdge` between two steps inserts one, the tail " +
+          "placeholder appends one, and each step toggles `optional` and `repeatable`. Every " +
+          "edit fires `onChange` with a complete `HappyPath` — the editor holds no copy.",
+      },
+    },
+  },
+  decorators: [
+    (Story) => (
+      <div className="h-[48rem] w-full bg-background">
+        <Story />
+      </div>
+    ),
+  ],
+  args: { value: orderPath, onChange: fn(), availableActivities: available },
+  render: (args) => <Stateful {...args} />,
+} satisfies Meta<typeof HappyPathEditor>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** Insert on an edge, then mark the new step repeatable. */
+export const Default: Story = {
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement);
+    const insert = await canvas.findByRole(
+      "button",
+      { name: "Insert a step between Register and Approve" },
+      { timeout: 5000 },
+    );
+    await userEvent.click(insert);
+    await expect(args.onChange).toHaveBeenLastCalledWith({
+      ...orderPath,
+      steps: [
+        { activity: "Register" },
+        { activity: "Check credit" },
+        { activity: "Approve" },
+        { activity: "Pay" },
+      ],
+    });
+
+    const repeatable = await canvas.findByRole("switch", { name: "Repeatable — Check credit" });
+    await userEvent.click(repeatable);
+    await waitFor(() => expect(repeatable).toBeChecked());
+    await expect(args.onChange).toHaveBeenLastCalledWith(
+      expect.objectContaining({
+        steps: [
+          { activity: "Register" },
+          { activity: "Check credit", repeatable: true },
+          { activity: "Approve" },
+          { activity: "Pay" },
+        ],
+      }),
+    );
+  },
+};
+
+/** Free-text activity names when the app has no activity list to offer. */
+export const FreeText: Story = {
+  args: { availableActivities: undefined },
+};
+
+/** A new path: only the placeholder that adds the first step. */
+export const Empty: Story = {
+  args: { value: { id: "new", label: "New path", steps: [] } },
+  play: async ({ canvasElement, args }) => {
+    const add = await within(canvasElement).findByRole(
+      "button",
+      { name: "Add step" },
+      { timeout: 5000 },
+    );
+    await userEvent.click(add);
+    await expect(args.onChange).toHaveBeenLastCalledWith({
+      id: "new",
+      label: "New path",
+      steps: [{ activity: "Register" }],
+    });
+  },
+};

package/src/happy-path-editor/happy-path-editor.test.tsx

@@ -0,0 +1,142 @@
+import { cleanup, fireEvent, render, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { useState } from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { liftHappyPath, type HappyPath } from "../core/reference-model";
+import { replayActivities } from "../core/token-replay";
+import {
+  HappyPathEditor,
+  insertHappyPathStep,
+  nextHappyPathActivity,
+  removeHappyPathStep,
+  updateHappyPathStep,
+} from "./happy-path-editor";
+
+// React Flow needs `DOMMatrixReadOnly` to mount; jsdom lacks it (see process-map.test.tsx).
+if (typeof globalThis.DOMMatrixReadOnly === "undefined") {
+  class DOMMatrixReadOnlyPolyfill {
+    m22 = 1;
+    constructor(_init?: unknown) {}
+  }
+  globalThis.DOMMatrixReadOnly = DOMMatrixReadOnlyPolyfill as unknown as typeof DOMMatrixReadOnly;
+}
+
+afterEach(cleanup);
+
+/**
+ * Find a control by its `aria-label`. React Flow keeps nodes `visibility: hidden` until
+ * measured — which never happens under jsdom — so role and accessible-name queries see
+ * nothing inside the canvas here. The computed names are asserted in the browser, by the
+ * story's play function.
+ */
+async function byLabel(name: string): Promise<HTMLElement> {
+  return waitFor(() => {
+    const found = document.querySelector<HTMLElement>(`[aria-label="${name}"]`);
+    if (!found) throw new Error(`no element labelled "${name}"`);
+    return found;
+  });
+}
+
+const path: HappyPath = {
+  id: "p",
+  label: "Order",
+  steps: [{ activity: "Register" }, { activity: "Approve" }],
+};
+const available = ["Register", "Check credit", "Approve", "Pay"];
+
+describe("happy-path edits", () => {
+  it("inserting via an edge point then toggling repeatable replays a repeat without deviation", () => {
+    // What the FlowButtonEdge between Register and Approve does (index 1).
+    const inserted = insertHappyPathStep(path, 1, {
+      activity: nextHappyPathActivity(path, available),
+    });
+    expect(inserted.steps.map((s) => s.activity)).toEqual(["Register", "Check credit", "Approve"]);
+
+    const repeatable = updateHappyPathStep(inserted, 1, { repeatable: true });
+    const model = liftHappyPath(repeatable);
+    const result = replayActivities(
+      "c",
+      ["Register", "Check credit", "Check credit", "Check credit", "Approve"],
+      model,
+    );
+    expect(result.deviations).toEqual([]);
+    expect(result.fitness).toBe(1);
+
+    // Without the flag the same trace deviates — the toggle is what the model reads.
+    const strict = replayActivities(
+      "c",
+      ["Register", "Check credit", "Check credit", "Approve"],
+      liftHappyPath(inserted),
+    );
+    expect(strict.deviations.length).toBeGreaterThan(0);
+  });
+
+  it("removing a step reconnects its neighbours and clearing a flag drops it", () => {
+    const three = insertHappyPathStep(path, 1, { activity: "Check credit", optional: true });
+    expect(removeHappyPathStep(three, 1)).toEqual(path);
+    expect(updateHappyPathStep(three, 1, { optional: false }).steps[1]).toEqual({
+      activity: "Check credit",
+    });
+  });
+
+  it("picks the first unused available activity for a new step", () => {
+    expect(nextHappyPathActivity(path, available)).toBe("Check credit");
+    expect(nextHappyPathActivity(path, undefined)).toBe("");
+  });
+});
+
+function Controlled({ onChange }: { onChange: (path: HappyPath) => void }) {
+  const [value, setValue] = useState(path);
+  return (
+    <div style={{ width: 600, height: 800 }}>
+      <HappyPathEditor
+        value={value}
+        onChange={(next) => {
+          onChange(next);
+          setValue(next);
+        }}
+      />
+    </div>
+  );
+}
+
+describe("HappyPathEditor", () => {
+  it("fires a complete HappyPath on toggle, rename and remove", async () => {
+    const onChange = vi.fn();
+    const user = userEvent.setup();
+    render(<Controlled onChange={onChange} />);
+
+    const repeatable = await byLabel("Repeatable — Approve");
+    await user.click(repeatable);
+    expect(onChange).toHaveBeenLastCalledWith({
+      ...path,
+      steps: [{ activity: "Register" }, { activity: "Approve", repeatable: true }],
+    });
+
+    const field = await byLabel("Activity for step 1");
+    await user.type(field, "!");
+    expect(onChange).toHaveBeenLastCalledWith(
+      expect.objectContaining({
+        steps: [{ activity: "Register!" }, { activity: "Approve", repeatable: true }],
+      }),
+    );
+
+    fireEvent.click(await byLabel("Remove Register!"));
+    await waitFor(() =>
+      expect(onChange).toHaveBeenLastCalledWith({
+        ...path,
+        steps: [{ activity: "Approve", repeatable: true }],
+      }),
+    );
+  });
+
+  it("appends a step from the tail placeholder", async () => {
+    const onChange = vi.fn();
+    render(<Controlled onChange={onChange} />);
+    fireEvent.click(await byLabel("Add step"));
+    expect(onChange).toHaveBeenLastCalledWith({
+      ...path,
+      steps: [...path.steps, { activity: "" }],
+    });
+  });
+});

package/src/happy-path-editor/happy-path-editor.tsx

@@ -0,0 +1,239 @@
+"use client";
+
+/**
+ * HappyPathEditor — draw the reference sequence conformance is checked against (RM-062).
+ *
+ * An editable `CanvasShell` (`@elabs-ai/components-flow`): each step is a
+ * {@link HappyPathStepNode} (a `FlowNode` with the step's controls), consecutive steps are
+ * chained by `FlowButtonEdge`s whose "+" inserts a step between them, and a
+ * `FlowPlaceholderNode` at the tail appends one. Removing a step reconnects the chain,
+ * because the chain is re-derived from the step list.
+ *
+ * ## Controlled, and stateless on purpose
+ *
+ * `value` in, a complete `HappyPath` out through `onChange` on every edit — insert,
+ * remove, rename (per keystroke), toggle. The editor keeps no state `HappyPath` does not
+ * already model, so a host can run `liftHappyPath` + `tokenReplay` on every change and
+ * the canvas can never disagree with the model it drew.
+ */
+import { forwardRef, useCallback, useMemo, type HTMLAttributes } from "react";
+import type { Edge } from "@xyflow/react";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+import {
+  CanvasShell,
+  FlowButtonEdge,
+  FlowEdge,
+  FlowPlaceholderNode,
+  type BrandFlowButtonEdge,
+  type BrandFlowPlaceholderNode,
+} from "@elabs-ai/components-flow";
+import type { HappyPath, HappyPathStep } from "../core/reference-model";
+import { fillLabel } from "../variant-explorer/variant-explorer-model";
+import {
+  HAPPY_PATH_EDITOR_DEFAULT_LABELS,
+  HappyPathEditorContext,
+  type HappyPathEditorContextValue,
+  type HappyPathEditorLabels,
+} from "./happy-path-editor-context";
+import { HappyPathStepNode, type HappyPathStepFlowNode } from "./happy-path-step-node";
+
+const NODE_TYPES = { "happy-path-step": HappyPathStepNode, placeholder: FlowPlaceholderNode };
+const EDGE_TYPES = { button: FlowButtonEdge, tail: FlowEdge };
+
+/** Vertical distance between consecutive steps, in flow units. */
+const STEP_SPACING = 260;
+/** Id of the tail placeholder node. */
+const TAIL_ID = "happy-path-tail";
+
+/** Id of the node for the step at `index`. */
+export function happyPathStepNodeId(index: number): string {
+  return `happy-path-step-${index}`;
+}
+
+/**
+ * The activity a newly inserted step starts with: the first available activity the path
+ * does not use yet, else the first available one, else empty (typed in afterwards).
+ */
+export function nextHappyPathActivity(
+  path: HappyPath,
+  availableActivities: readonly string[] | undefined,
+): string {
+  if (!availableActivities || availableActivities.length === 0) return "";
+  const used = new Set(path.steps.map((step) => step.activity));
+  return availableActivities.find((activity) => !used.has(activity)) ?? availableActivities[0]!;
+}
+
+/** `path` with a new step inserted at `index`. */
+export function insertHappyPathStep(
+  path: HappyPath,
+  index: number,
+  step: HappyPathStep,
+): HappyPath {
+  const steps = [...path.steps];
+  steps.splice(index, 0, step);
+  return { ...path, steps };
+}
+
+/** `path` without the step at `index`. The neighbours become consecutive. */
+export function removeHappyPathStep(path: HappyPath, index: number): HappyPath {
+  return { ...path, steps: path.steps.filter((_, i) => i !== index) };
+}
+
+/** `path` with the step at `index` patched. `false` flags are dropped, not stored. */
+export function updateHappyPathStep(
+  path: HappyPath,
+  index: number,
+  patch: Partial<HappyPathStep>,
+): HappyPath {
+  return {
+    ...path,
+    steps: path.steps.map((step, i) => {
+      if (i !== index) return step;
+      const next: HappyPathStep = { ...step, ...patch };
+      if (!next.optional) delete next.optional;
+      if (!next.repeatable) delete next.repeatable;
+      return next;
+    }),
+  };
+}
+
+/** Props for {@link HappyPathEditor}. `onChange` carries a path, so the DOM one is omitted. */
+export interface HappyPathEditorProps extends Omit<HTMLAttributes<HTMLDivElement>, "onChange"> {
+  value: HappyPath;
+  /** Fires with the complete path after every edit. */
+  onChange: (path: HappyPath) => void;
+  /** Activities a step may pick from (e.g. the log's). Omit for free-text activities. */
+  availableActivities?: string[];
+  /** Override any user-visible string. */
+  labels?: Partial<HappyPathEditorLabels>;
+}
+
+type EditorNode = HappyPathStepFlowNode | BrandFlowPlaceholderNode;
+type EditorEdge = BrandFlowButtonEdge | Edge;
+
+/**
+ * The happy-path editor.
+ *
+ * @example
+ * ```tsx
+ * const [path, setPath] = useState<HappyPath>({ id: "p", label: "Order", steps: [] });
+ * const conformance = useMemo(() => tokenReplay(log, liftHappyPath(path)), [log, path]);
+ * <HappyPathEditor value={path} onChange={setPath} availableActivities={activities} />
+ * ```
+ */
+export const HappyPathEditor = forwardRef<HTMLDivElement, HappyPathEditorProps>(
+  function HappyPathEditor(
+    { value, onChange, availableActivities, labels: labelOverrides, className, ...props },
+    ref,
+  ) {
+    const labels = useMemo<HappyPathEditorLabels>(
+      () => ({ ...HAPPY_PATH_EDITOR_DEFAULT_LABELS, ...labelOverrides }),
+      [labelOverrides],
+    );
+
+    const insertAt = useCallback(
+      (index: number) =>
+        onChange(
+          insertHappyPathStep(value, index, {
+            activity: nextHappyPathActivity(value, availableActivities),
+          }),
+        ),
+      [value, onChange, availableActivities],
+    );
+
+    const context = useMemo<HappyPathEditorContextValue>(
+      () => ({
+        labels,
+        availableActivities,
+        updateStep: (index, patch) => onChange(updateHappyPathStep(value, index, patch)),
+        removeStep: (index) => onChange(removeHappyPathStep(value, index)),
+      }),
+      [labels, availableActivities, value, onChange],
+    );
+
+    const nodes = useMemo<EditorNode[]>(() => {
+      const stepNodes: EditorNode[] = value.steps.map((step, index) => {
+        const flags = [
+          step.optional ? labels.optional.toLowerCase() : null,
+          step.repeatable ? labels.repeatable.toLowerCase() : null,
+        ].filter(Boolean);
+        return {
+          id: happyPathStepNodeId(index),
+          type: "happy-path-step",
+          position: { x: 0, y: index * STEP_SPACING },
+          data: { index, step },
+          draggable: false,
+          ariaLabel: fillLabel(labels.stepName, {
+            n: index + 1,
+            activity: step.activity || labels.untitled,
+            flags: flags.length > 0 ? `, ${flags.join(", ")}` : "",
+          }),
+        };
+      });
+      stepNodes.push({
+        id: TAIL_ID,
+        type: "placeholder",
+        position: { x: 0, y: value.steps.length * STEP_SPACING },
+        data: { label: labels.addStep, onActivate: () => insertAt(value.steps.length) },
+        draggable: false,
+      });
+      return stepNodes;
+    }, [value.steps, labels, insertAt]);
+
+    const edges = useMemo<EditorEdge[]>(() => {
+      const chain: EditorEdge[] = [];
+      value.steps.forEach((step, index) => {
+        const next = value.steps[index + 1];
+        if (next) {
+          chain.push({
+            id: `${happyPathStepNodeId(index)}->${happyPathStepNodeId(index + 1)}`,
+            source: happyPathStepNodeId(index),
+            target: happyPathStepNodeId(index + 1),
+            type: "button",
+            data: {
+              label: fillLabel(labels.insertStep, {
+                before: step.activity || labels.untitled,
+                after: next.activity || labels.untitled,
+              }),
+              onInsert: () => insertAt(index + 1),
+            },
+          });
+        } else {
+          chain.push({
+            id: `${happyPathStepNodeId(index)}->${TAIL_ID}`,
+            source: happyPathStepNodeId(index),
+            target: TAIL_ID,
+            type: "tail",
+          });
+        }
+      });
+      return chain;
+    }, [value.steps, labels, insertAt]);
+
+    return (
+      <div
+        ref={ref}
+        data-slot="happy-path-editor"
+        data-steps={value.steps.length}
+        className={cn("relative size-full min-h-80", className)}
+        {...props}
+      >
+        <HappyPathEditorContext value={context}>
+          <CanvasShell<EditorNode, EditorEdge>
+            nodes={nodes}
+            edges={edges}
+            nodeTypes={NODE_TYPES}
+            edgeTypes={EDGE_TYPES}
+            nodesDraggable={false}
+            nodesConnectable={false}
+            edgesFocusable={false}
+            deleteKeyCode={null}
+            fitView
+            fitViewKey={value.steps.length}
+            aria-label={fillLabel(labels.canvas, { path: value.label })}
+          />
+        </HappyPathEditorContext>
+      </div>
+    );
+  },
+);