@elabs-ai/components-flow 4.0.0 → 4.1.0

package/src/flow-weighted-edge/back-edge-geometry.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from "vitest";
+import { backEdgeDetour, type BackEdgeNodeRect } from "./back-edge-geometry";
+
+/** Three cards on one rank, the shape a rework edge has to get around. */
+const rank: BackEdgeNodeRect[] = [
+  { x: 0, y: 200, width: 176, height: 83 },
+  { x: 220, y: 200, width: 176, height: 83 },
+  { x: 440, y: 200, width: 176, height: 83 },
+];
+
+describe("backEdgeDetour", () => {
+  it("clears the OUTERMOST card in the band, not just the edge's own two nodes", () => {
+    // The edge runs between the rank above (y 0) and the rank at y 200. Clearing only
+    // its own endpoints would put the leg at 396 + 40 — inside the third card.
+    expect(backEdgeDetour(rank, "vertical", [283, 100], 40)).toBe(656);
+  });
+
+  it("ignores a card on another rank entirely", () => {
+    const withFarRank = [...rank, { x: 2000, y: 600, width: 176, height: 83 }];
+    expect(backEdgeDetour(withFarRank, "vertical", [283, 100], 40)).toBe(656);
+  });
+
+  it("includes a card the span only touches at its edge", () => {
+    // Span ends exactly on the rank's top edge: the leg still has to pass it.
+    expect(backEdgeDetour(rank, "vertical", [100, 200], 40)).toBe(656);
+  });
+
+  it("measures along the other axis in a left-to-right layout", () => {
+    // Ranks advance horizontally, so the return leg runs BELOW the cards.
+    expect(backEdgeDetour(rank, "horizontal", [0, 616], 40)).toBe(323);
+  });
+
+  it("skips unmeasured cards rather than treating them as zero-size boxes at the origin", () => {
+    const unmeasured = [{ x: 900, y: 200, width: 0, height: 0 }, ...rank];
+    expect(backEdgeDetour(unmeasured, "vertical", [283, 100], 40)).toBe(656);
+  });
+
+  it("returns null when nothing is measured, so React Flow's own midpoint stands", () => {
+    expect(backEdgeDetour([], "vertical", [283, 100], 40)).toBeNull();
+    expect(
+      backEdgeDetour([{ x: 0, y: 0, width: 0, height: 0 }], "vertical", [0, 1], 40),
+    ).toBeNull();
+  });
+
+  it("reads the span in either order", () => {
+    expect(backEdgeDetour(rank, "vertical", [100, 283], 40)).toBe(
+      backEdgeDetour(rank, "vertical", [283, 100], 40),
+    );
+  });
+
+  it("returns null when every card sits outside the span", () => {
+    expect(backEdgeDetour(rank, "vertical", [400, 500], 40)).toBeNull();
+  });
+});

package/src/flow-weighted-edge/back-edge-geometry.ts

@@ -0,0 +1,60 @@
+/**
+ * Where a back edge's return leg runs, so it stays VISIBLE.
+ *
+ * A back edge is drawn as a smoothstep with one long cross-segment running against the
+ * layout direction. React Flow puts that segment halfway between the two handles by
+ * default, and a fixed nudge off the midpoint does not help: in a top-down layout the
+ * midpoint of a rework edge sits between two ranks, i.e. squarely inside the column of
+ * cards it is supposed to run past. Edges paint UNDER nodes, so the segment vanishes
+ * behind the cards and all the reader is left with is a dashed stub below one node and
+ * another above the other — which reads as a stray rectangle, not as a loop back.
+ *
+ * So the leg is placed OUTSIDE every card it would otherwise pass behind: past the far
+ * side of every node whose extent overlaps the span the edge crosses. That is how a
+ * process-mining tool draws a rework loop — out, around the rank, back in — and it is
+ * the only placement that is correct for a graph rather than for a pair of nodes.
+ */
+
+/** One node's laid-out box, in flow coordinates. */
+export interface BackEdgeNodeRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/** Which axis the layout's ranks advance along. */
+export type BackEdgeAxis = "vertical" | "horizontal";
+
+/**
+ * The `centerX` (vertical layout) or `centerY` (horizontal layout) to hand
+ * `getSmoothStepPath`, or `null` when nothing is measured yet and React Flow's own
+ * midpoint should stand.
+ *
+ * @param rects  Every laid-out node on the canvas. Nodes that cannot be hit are filtered
+ *               out here rather than by the caller, so the caller stays a plain map.
+ * @param span   The interval the edge crosses on the RANK axis (`[min, max]` of the two
+ *               handle coordinates) — a node outside it is never behind this edge.
+ * @param clearance  Gap left between the leg and the outermost card it clears.
+ */
+export function backEdgeDetour(
+  rects: readonly BackEdgeNodeRect[],
+  axis: BackEdgeAxis,
+  span: readonly [number, number],
+  clearance: number,
+): number | null {
+  const [lo, hi] = span[0] <= span[1] ? span : [span[1], span[0]];
+  let far = Number.NEGATIVE_INFINITY;
+
+  for (const rect of rects) {
+    if (!(rect.width > 0) || !(rect.height > 0)) continue;
+    // Overlap on the RANK axis (the one the edge travels along): a node beside the
+    // corridor but on another rank cannot be crossed by this leg.
+    const [near, beyond] =
+      axis === "vertical" ? [rect.y, rect.y + rect.height] : [rect.x, rect.x + rect.width];
+    if (beyond < lo || near > hi) continue;
+    far = Math.max(far, axis === "vertical" ? rect.x + rect.width : rect.y + rect.height);
+  }
+
+  return Number.isFinite(far) ? far + clearance : null;
+}

package/src/flow-weighted-edge/edge-aria.test.ts

@@ -0,0 +1,108 @@
+import { describe, expect, it } from "vitest";
+import { buildWeightedEdgeAriaLabel, withWeightedEdgeAria } from "./edge-aria";
+import type { BrandFlowWeightedEdge } from "./flow-weighted-edge";
+
+/** Minimal edge factory — only the fields `buildWeightedEdgeAriaLabel` reads. */
+function makeEdge(overrides: Partial<BrandFlowWeightedEdge> = {}): BrandFlowWeightedEdge {
+  return {
+    id: "e1",
+    source: "n1",
+    target: "n2",
+    type: "weighted",
+    data: {},
+    ...overrides,
+  } as BrandFlowWeightedEdge;
+}
+
+describe("buildWeightedEdgeAriaLabel", () => {
+  it("composes weight only", () => {
+    const edge = makeEdge({ data: { weight: 4 } });
+    expect(buildWeightedEdgeAriaLabel(edge)).toBe("Edge from n1 to n2, weight 4");
+  });
+
+  it("composes weight plus value", () => {
+    const edge = makeEdge({ data: { weight: 4, value: 7, valueDomain: [0, 10] } });
+    expect(buildWeightedEdgeAriaLabel(edge)).toBe("Edge from n1 to n2, weight 4, value 7");
+  });
+
+  it("appends the pill text when label/secondaryLabel are present", () => {
+    const edge = makeEdge({ data: { weight: 1, label: "min", secondaryLabel: "1×" } });
+    expect(buildWeightedEdgeAriaLabel(edge)).toBe("Edge from n1 to n2, weight 1, min 1×");
+  });
+
+  it("appends only the label present when the other pill field is absent", () => {
+    const edge = makeEdge({ data: { weight: 4, secondaryLabel: "avg 2d" } });
+    expect(buildWeightedEdgeAriaLabel(edge)).toBe("Edge from n1 to n2, weight 4, avg 2d");
+  });
+
+  it("an explicit edge.ariaLabel always wins, untouched", () => {
+    const edge = makeEdge({
+      ariaLabel: "Custom name",
+      data: { weight: 4, value: 7, label: "x" },
+    });
+    expect(buildWeightedEdgeAriaLabel(edge)).toBe("Custom name");
+  });
+
+  it("returns undefined when the edge carries no weight, value or labels — the untouched default", () => {
+    const edge = makeEdge({ data: {} });
+    expect(buildWeightedEdgeAriaLabel(edge)).toBeUndefined();
+  });
+
+  it("returns undefined for an edge with no data at all", () => {
+    const edge = makeEdge({ data: undefined });
+    expect(buildWeightedEdgeAriaLabel(edge)).toBeUndefined();
+  });
+
+  it("uses nameOf to resolve endpoint display names", () => {
+    const edge = makeEdge({ source: "n1", target: "n2", data: { weight: 2 } });
+    const nameOf = (id: string) => ({ n1: "Order placed", n2: "Picked" })[id]!;
+    expect(buildWeightedEdgeAriaLabel(edge, { nameOf })).toBe(
+      "Edge from Order placed to Picked, weight 2",
+    );
+  });
+
+  it("honors weightLabel/valueLabel/formatNumber overrides", () => {
+    const edge = makeEdge({ data: { weight: 4.5, value: 2, valueDomain: [0, 10] } });
+    expect(
+      buildWeightedEdgeAriaLabel(edge, {
+        weightLabel: "frequency",
+        valueLabel: "duration",
+        formatNumber: (n) => n.toFixed(1),
+      }),
+    ).toBe("Edge from n1 to n2, frequency 4.5, duration 2.0");
+  });
+});
+
+describe("withWeightedEdgeAria", () => {
+  it("stamps ariaLabel onto every edge that has none", () => {
+    const edges = [
+      makeEdge({ id: "e1", data: { weight: 1 } }),
+      makeEdge({ id: "e2", data: { weight: 8 } }),
+    ];
+    const result = withWeightedEdgeAria(edges);
+    expect(result.map((e) => e.ariaLabel)).toEqual([
+      "Edge from n1 to n2, weight 1",
+      "Edge from n1 to n2, weight 8",
+    ]);
+  });
+
+  it("never overwrites a caller-supplied ariaLabel", () => {
+    const edges = [makeEdge({ id: "e1", ariaLabel: "Kept", data: { weight: 9 } })];
+    const result = withWeightedEdgeAria(edges);
+    expect(result[0]!.ariaLabel).toBe("Kept");
+    // Untouched — same reference, not just an equal string.
+    expect(result[0]).toBe(edges[0]);
+  });
+
+  it("leaves an edge with nothing to add untouched (identity preserved)", () => {
+    const edges = [makeEdge({ id: "e1", data: {} })];
+    const result = withWeightedEdgeAria(edges);
+    expect(result[0]!.ariaLabel).toBeUndefined();
+    expect(result[0]).toBe(edges[0]);
+  });
+
+  it("returns a new array", () => {
+    const edges = [makeEdge({ id: "e1", data: { weight: 1 } })];
+    expect(withWeightedEdgeAria(edges)).not.toBe(edges);
+  });
+});

package/src/flow-weighted-edge/edge-aria.ts

@@ -0,0 +1,117 @@
+/**
+ * edge-aria — pure, framework-free "edge data → accessible name" naming seam
+ * for `FlowWeightedEdge`, mirroring `weight-scale.ts`'s shape (no React, no
+ * DOM, trivially unit-testable).
+ *
+ * `FlowWeightedEdge` encodes `data.weight` as stroke width and, optionally,
+ * `data.value` as stroke colour — both purely visual. React Flow's own
+ * `EdgeWrapper` sources an edge's accessible name from `edge.ariaLabel`
+ * (`edge` object, not the edge COMPONENT — see issue #285), so the component
+ * has no channel to set it. This module is the seam a caller runs their
+ * `edges` array through instead.
+ *
+ * Naming contract (a decision, not an accident):
+ *  1. An explicit `edge.ariaLabel` always wins — never overwritten.
+ *  2. Otherwise compose `"Edge from <source> to <target>, weight <n>"`,
+ *     appending `", <valueLabel> <n>"` when `data.value` is set and the pill
+ *     text (`data.label`/`data.secondaryLabel`, space-joined) when either is
+ *     present.
+ *  3. When an edge carries none of `weight`/`value`/`label`/`secondaryLabel`,
+ *     return `undefined` so React Flow's own default
+ *     ("Edge from <source> to <target>") survives untouched. That quoted
+ *     string is `@xyflow/react`'s output, not ours — the `e-bare` edge in
+ *     `flow-weighted-edge.stories.tsx`'s `NamingContractEdges` story (#327)
+ *     is the browser lock for it: it renders a measure-less edge against a
+ *     real `CanvasShell` and asserts the default name via
+ *     `toHaveAccessibleName`. If that story goes red after a dependency
+ *     bump, read it as a signal that React Flow's default changed, not as a
+ *     flake to silence.
+ */
+
+import type { BrandFlowWeightedEdge } from "./flow-weighted-edge";
+
+export interface WeightedEdgeAriaOptions {
+  /** Word used for the width measure in the composed name. @default "weight" */
+  weightLabel?: string;
+  /** Word used for the colour measure in the composed name. @default "value" */
+  valueLabel?: string;
+  /**
+   * Map a node id to its display name, so the composed name says
+   * "Edge from Order placed to Picked" rather than "Edge from n1 to n2". The
+   * caller owns node display names (this module never reaches into a `nodes`
+   * array), so it is a hook, not an automatic lookup.
+   */
+  nameOf?: (nodeId: string) => string;
+  /** Format a numeric measure for display. @default String(n) */
+  formatNumber?: (n: number) => string;
+}
+
+const DEFAULT_WEIGHT_LABEL = "weight";
+const DEFAULT_VALUE_LABEL = "value";
+
+function defaultNameOf(nodeId: string): string {
+  return nodeId;
+}
+
+function defaultFormatNumber(n: number): string {
+  return String(n);
+}
+
+/**
+ * Derive one edge's accessible name from its weight/value/labels. Pure — no
+ * React, no DOM. Returns:
+ *  - the edge's own `ariaLabel`, unchanged, when the caller already set one;
+ *  - a composed string when the edge carries `weight`, `value`, `label` or
+ *    `secondaryLabel`;
+ *  - `undefined` when there is nothing to add (so the default announcement
+ *    from React Flow's `EdgeWrapper` survives untouched).
+ */
+export function buildWeightedEdgeAriaLabel(
+  edge: BrandFlowWeightedEdge,
+  opts: WeightedEdgeAriaOptions = {},
+): string | undefined {
+  if (edge.ariaLabel) return edge.ariaLabel;
+
+  const { weight, value, label, secondaryLabel } = edge.data ?? {};
+  if (weight === undefined && value === undefined && !label && !secondaryLabel) {
+    return undefined;
+  }
+
+  const {
+    weightLabel = DEFAULT_WEIGHT_LABEL,
+    valueLabel = DEFAULT_VALUE_LABEL,
+    nameOf = defaultNameOf,
+    formatNumber = defaultFormatNumber,
+  } = opts;
+
+  const parts = [`Edge from ${nameOf(edge.source)} to ${nameOf(edge.target)}`];
+  if (weight !== undefined) parts.push(`${weightLabel} ${formatNumber(weight)}`);
+  if (value !== undefined) parts.push(`${valueLabel} ${formatNumber(value)}`);
+
+  const pillText = [label, secondaryLabel].filter(Boolean).join(" ");
+  if (pillText) parts.push(pillText);
+
+  return parts.join(", ");
+}
+
+/**
+ * Stamp `ariaLabel` onto every weighted edge that has none, per
+ * `buildWeightedEdgeAriaLabel`'s naming contract. An edge that already
+ * carries an `ariaLabel` is returned unchanged (never overwritten); an edge
+ * with nothing to add is also returned unchanged, so an unrelated edge type
+ * sharing this array keeps its identity.
+ *
+ * Returns a NEW array — memoize the call when used inline in render (e.g.
+ * `useMemo(() => withWeightedEdgeAria(edges), [edges])`), or a consumer hands
+ * React Flow a new `edges` identity every frame.
+ */
+export function withWeightedEdgeAria<E extends BrandFlowWeightedEdge>(
+  edges: E[],
+  opts?: WeightedEdgeAriaOptions,
+): E[] {
+  return edges.map((edge) => {
+    if (edge.ariaLabel) return edge;
+    const ariaLabel = buildWeightedEdgeAriaLabel(edge, opts);
+    return ariaLabel === undefined ? edge : { ...edge, ariaLabel };
+  });
+}

package/src/flow-weighted-edge/edge-label-pill.test.tsx

@@ -0,0 +1,65 @@
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("@xyflow/react", () => ({
+  // Real EdgeLabelRenderer portals into a fixed container; a passthrough is
+  // enough here since we only assert the brand component's own output.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  EdgeLabelRenderer: ({ children }: { children: any }) => children,
+}));
+
+import { EdgeLabelPill } from "./edge-label-pill";
+
+afterEach(cleanup);
+
+describe("EdgeLabelPill", () => {
+  it("renders nothing when neither label nor secondaryLabel is set", () => {
+    const { container } = render(<EdgeLabelPill x={0} y={0} />);
+    expect(container).toBeEmptyDOMElement();
+  });
+
+  it("renders a real, focusable button", () => {
+    render(<EdgeLabelPill x={0} y={0} label="128×" />);
+    const button = screen.getByRole("button");
+    expect(button.tagName).toBe("BUTTON");
+    expect(button).toHaveAttribute("type", "button");
+  });
+
+  it("combines label + secondaryLabel into one accessible name", () => {
+    render(<EdgeLabelPill x={0} y={0} label="128×" secondaryLabel="3.4d avg" />);
+    expect(screen.getByRole("button", { name: "128× · 3.4d avg" })).toBeInTheDocument();
+  });
+
+  it("uses only label when secondaryLabel is absent", () => {
+    render(<EdgeLabelPill x={0} y={0} label="128×" />);
+    expect(screen.getByRole("button", { name: "128×" })).toBeInTheDocument();
+  });
+
+  it("uses only secondaryLabel when label is absent", () => {
+    render(<EdgeLabelPill x={0} y={0} secondaryLabel="3.4d avg" />);
+    expect(screen.getByRole("button", { name: "3.4d avg" })).toBeInTheDocument();
+  });
+
+  it("is pointer-clickable without a pointer-events-none ancestor blocking it", () => {
+    render(<EdgeLabelPill x={0} y={0} label="128×" />);
+    const button = screen.getByRole("button");
+    expect(button.className).toContain("pointer-events-auto");
+  });
+
+  // #351 — `className`/`...props` is the seam a composing package (e.g.
+  // `@elabs-ai/components-process`'s `ProcessTransitionEdge`) reaches this
+  // pill's root button through from outside `@elabs-ai/components-flow`,
+  // without a new semantic prop on this component.
+  it("merges a caller className onto the root button, after its own utility classes", () => {
+    render(<EdgeLabelPill x={0} y={0} label="128×" className="border-dashed" />);
+    const button = screen.getByRole("button");
+    expect(button.className).toContain("border-dashed");
+    // The pill's own classes are still present — className extends, not replaces.
+    expect(button.className).toContain("pointer-events-auto");
+  });
+
+  it("spreads arbitrary props (e.g. data-selection) onto the root button", () => {
+    render(<EdgeLabelPill x={0} y={0} label="128×" data-selection="excluded" />);
+    expect(screen.getByRole("button")).toHaveAttribute("data-selection", "excluded");
+  });
+});

package/src/flow-weighted-edge/edge-label-pill.tsx

@@ -0,0 +1,82 @@
+import type { ComponentPropsWithoutRef } from "react";
+import { EdgeLabelRenderer } from "@xyflow/react";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+
+export interface EdgeLabelPillProps extends ComponentPropsWithoutRef<"button"> {
+  /** Primary label, e.g. a frequency count ("128×"). */
+  label?: string;
+  /** Secondary label rendered alongside the primary, e.g. a duration ("3.4d avg"). */
+  secondaryLabel?: string;
+  /** Label anchor, from `getBezierPath`/`getSmoothStepPath`'s `labelX`/`labelY`. */
+  x: number;
+  y: number;
+  /** Matches the parent edge's `selected` state. */
+  selected?: boolean;
+}
+
+/**
+ * A small HTML pill (via `EdgeLabelRenderer`, not SVG `<text>`) anchored at an
+ * edge's label point — so it can theme, wrap, and carry two values, unlike a
+ * bare SVG text node. Renders nothing when neither label is set. Real
+ * `<button>` so it is a genuine keyboard tab stop with a visible focus ring;
+ * `pointer-events: auto` on an otherwise `nodrag nopan` wrapper so it doesn't
+ * drag/pan the canvas, and doesn't block hovering the edge underneath it (the
+ * wrapper is sized to the pill itself, not the whole edge).
+ *
+ * `className`/`...props` spread onto the root `<button>` (`data-slot="edge-label-pill"`)
+ * so a consumer that composes this pill from outside `@elabs-ai/components-flow` —
+ * `@elabs-ai/components-process`'s `ProcessTransitionEdge` is the reference caller —
+ * can reach it directly (a dashed frame, a `data-selection` attribute) without a new
+ * semantic prop on this component. `className` merges LAST via `cn()`, so a caller can
+ * override any of the pill's own utility classes; omitting both leaves every existing
+ * caller's rendered markup unchanged.
+ */
+export function EdgeLabelPill({
+  label,
+  secondaryLabel,
+  x,
+  y,
+  selected,
+  className,
+  ...props
+}: EdgeLabelPillProps) {
+  if (!label && !secondaryLabel) return null;
+
+  const accessibleName = [label, secondaryLabel].filter(Boolean).join(" · ");
+
+  return (
+    <EdgeLabelRenderer>
+      <div
+        style={{
+          position: "absolute",
+          transform: `translate(-50%, -50%) translate(${x}px, ${y}px)`,
+          pointerEvents: "none",
+        }}
+        className="nodrag nopan"
+        data-slot="edge-label-pill-anchor"
+      >
+        <button
+          type="button"
+          aria-label={accessibleName}
+          data-slot="edge-label-pill"
+          {...props}
+          className={cn(
+            "pointer-events-auto flex items-center gap-1 rounded-full border bg-flow-node px-2 py-0.5",
+            "text-meta font-medium text-flow-node-foreground shadow-sm",
+            "transition-colors duration-fast ease-standard",
+            "focus-ring",
+            selected ? "border-ring" : "border-flow-group-border",
+            className,
+          )}
+        >
+          {label ? <span aria-hidden="true">{label}</span> : null}
+          {secondaryLabel ? (
+            <span aria-hidden="true" className="text-flow-node-foreground/70 tabular-nums">
+              {secondaryLabel}
+            </span>
+          ) : null}
+        </button>
+      </div>
+    </EdgeLabelRenderer>
+  );
+}