@elabs-ai/components-flow 4.0.0 → 4.1.0

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

@@ -0,0 +1,308 @@
+import { useCallback, useMemo } from "react";
+import {
+  Position,
+  getBezierPath,
+  getSmoothStepPath,
+  useEdges,
+  useStore,
+  type Edge,
+  type EdgeProps,
+  type ReactFlowState,
+} from "@xyflow/react";
+import { resolveTokenColor } from "@elabs-ai/components-tokens";
+import { FlowEdgePath } from "../flow-edge-path";
+import { EdgeLabelPill, type EdgeLabelPillProps } from "./edge-label-pill";
+import { backEdgeDetour, type BackEdgeNodeRect } from "./back-edge-geometry";
+import {
+  computeEdgeWeightScale,
+  DEFAULT_EDGE_WIDTH_RANGE,
+  type WeightedEdgeLike,
+} from "./weight-scale";
+
+/** Stable empty array for the forward branch of the node subscription below. */
+const NO_NODES: ReactFlowState["nodes"] = [];
+
+export interface FlowWeightedEdgeData extends Record<string, unknown> {
+  /** Frequency/volume this edge carries. Scaled into stroke width — see `computeEdgeWeightScale`. */
+  weight?: number;
+  /** Edges sharing a `scaleGroup` share one min-max width domain. @default all edges in the flow */
+  scaleGroup?: string;
+  /** A second, continuous measure (e.g. average duration). Colours the stroke — needs `valueDomain` too. */
+  value?: number;
+  /** `[min, max]` domain `value` is interpolated across, from `--flow-edge-weak` to `--flow-edge-strong`. */
+  valueDomain?: [number, number];
+  /** Primary edge-label-pill text, e.g. a frequency count. */
+  label?: string;
+  /** Secondary edge-label-pill text, e.g. a duration. */
+  secondaryLabel?: string;
+  /** Path geometry. Ignored when `variant` is `"back"`, which always routes smoothstep. @default "bezier" */
+  path?: "bezier" | "smoothstep";
+  /**
+   * Whether this edge advances the process (`"forward"`) or runs against the
+   * layout direction (`"back"` — a rework/retry edge, as reported by
+   * `layoutFlow`'s `backEdges`).
+   *
+   * `"back"` is distinguished by SHAPE, not colour: a dashed stroke, and a
+   * smoothstep route pushed clear of the forward edge between the same pair of
+   * nodes so the two never overlap. It also carries a real accessible name, so
+   * the direction reaches assistive technology as text rather than only as a
+   * `data-variant` attribute.
+   *
+   * @default "forward"
+   */
+  variant?: "forward" | "back";
+  /**
+   * Overrides the accessible name given to a `"back"` edge's graphic. Defaults
+   * to "Back edge — runs against the process direction".
+   */
+  variantLabel?: string;
+  /**
+   * Passed straight through to the rendered `EdgeLabelPill`'s `className`/`...props`
+   * (see `EdgeLabelPillProps`) — the seam a composing package (e.g.
+   * `@elabs-ai/components-process`'s `ProcessTransitionEdge`) uses to reach the pill's
+   * own root button from outside this component, without a new semantic prop here.
+   */
+  labelProps?: Omit<EdgeLabelPillProps, "label" | "secondaryLabel" | "x" | "y" | "selected">;
+}
+
+export type BrandFlowWeightedEdge = Edge<FlowWeightedEdgeData, "weighted">;
+
+// Approximate hex fallbacks for `--flow-edge-weak`/`--flow-edge-strong`, used
+// only when the CSS custom property can't be read (SSR, or the tokens
+// stylesheet isn't loaded yet) — resolveTokenColor() reads the live theme
+// value whenever a `document` is available.
+const FALLBACK_WEAK = "#6085a1";
+const FALLBACK_STRONG = "#496d89";
+
+/**
+ * Shape channel for `variant="back"`: a dash pattern plus a reduced stroke
+ * opacity on the same `--flow-edge` token. Dashes are readable in greyscale
+ * and under any theme, so the back edge never depends on hue (WCAG 1.4.1).
+ */
+const BACK_EDGE_DASHARRAY = "6 4";
+const BACK_EDGE_OPACITY = 0.7;
+/**
+ * Clearance, in px, between a back edge and everything it must stay clear OF.
+ *
+ * Two uses. As `getSmoothStepPath`'s `offset` it is how far the path runs straight out of
+ * a handle before it turns, which is what keeps it off the forward edge joining the same
+ * two nodes. As the gap in {@link backEdgeDetour} it is how far past the outermost card
+ * the return leg sits — see that function for why a card-relative placement, rather than
+ * a nudge off the midpoint, is the only one that stays visible.
+ */
+const BACK_EDGE_CLEARANCE = 40;
+
+const DEFAULT_BACK_EDGE_LABEL = "Back edge — runs against the process direction";
+
+function clamp01(t: number): number {
+  return Math.min(1, Math.max(0, t));
+}
+
+function hexToRgb(hex: string): [number, number, number] {
+  const m = /^#?([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})/i.exec(hex);
+  if (!m) return [0, 0, 0];
+  return [parseInt(m[1]!, 16), parseInt(m[2]!, 16), parseInt(m[3]!, 16)];
+}
+
+function toHexByte(n: number): string {
+  return Math.round(Math.min(255, Math.max(0, n)))
+    .toString(16)
+    .padStart(2, "0");
+}
+
+/** Linear RGB interpolation between two hex colors — pure, no DOM. */
+function mixHex(a: string, b: string, t: number): string {
+  const [ar, ag, ab] = hexToRgb(a);
+  const [br, bg, bb] = hexToRgb(b);
+  const r = ar + (br - ar) * t;
+  const g = ag + (bg - ag) * t;
+  const bl = ab + (bb - ab) * t;
+  return `#${toHexByte(r)}${toHexByte(g)}${toHexByte(bl)}`;
+}
+
+/**
+ * Resolve `data.value`/`data.valueDomain` into a stroke color interpolated
+ * between the `--flow-edge-weak`/`--flow-edge-strong` tokens. Returns
+ * `undefined` when either input is missing, so the caller can fall back to
+ * the plain `--flow-edge` token (unweighted-looking) edge color.
+ */
+function resolveValueStrokeColor(
+  value: number | undefined,
+  domain: [number, number] | undefined,
+): string | undefined {
+  if (value === undefined || !domain) return undefined;
+  const [lo, hi] = domain;
+  const t = hi === lo ? 1 : clamp01((value - lo) / (hi - lo));
+  const weak = resolveTokenColor("--flow-edge-weak", { fallback: FALLBACK_WEAK });
+  const strong = resolveTokenColor("--flow-edge-strong", { fallback: FALLBACK_STRONG });
+  return mixHex(weak, strong, t);
+}
+
+/**
+ * Branded weighted edge: `data.weight` scales stroke width (min-maxed per
+ * `data.scaleGroup` across every edge in the flow — see `computeEdgeWeightScale`,
+ * exported so a sibling like a continuous `Legend` renders the same ramp);
+ * `data.value` + `data.valueDomain` interpolate stroke colour between
+ * `--flow-edge-weak` and `--flow-edge-strong`; `data.label`/`data.secondaryLabel`
+ * render as an `EdgeLabelPill`. An edge with none of this data renders exactly
+ * like `FlowEdge` (fixed 1.5px, `--flow-edge` token) — fully backward-compatible.
+ * Register it in `edgeTypes={{ weighted: FlowWeightedEdge }}` and create edges
+ * with `type: "weighted"` and `data: FlowWeightedEdgeData`.
+ *
+ * `weight`/`value` are VISUAL ONLY — stroke width and colour reach no screen
+ * reader. This component cannot set its own accessible name: React Flow's
+ * `EdgeWrapper` sources it from `edge.ariaLabel` on the edge OBJECT, one level
+ * above the component it renders as a child (issue #285). Run your `edges`
+ * through `withWeightedEdgeAria` (from `./edge-aria`, or set `edge.ariaLabel`
+ * yourself) before handing them to `<CanvasShell>`/`<ReactFlow>` — otherwise
+ * the measure this component exists to show reaches no assistive technology,
+ * and the edge announces only React Flow's generic "Edge from n1 to n2".
+ * `withWeightedEdgeAria` returns a new array each call — memoize it
+ * (`useMemo(() => withWeightedEdgeAria(edges), [edges])`) if you call it
+ * inline in render.
+ *
+ * `data-weight`/`data-value` are also stamped onto the rendered `<path>` (raw
+ * `data.weight`/`data.value`, not the scaled stroke width) — a stable
+ * selector for tests/consumers, independent of the naming seam above.
+ *
+ * `data.variant: "back"` marks an edge that runs against the process direction
+ * (dagre's reversed edges — see `layoutFlow`'s `backEdges`). It is dashed and
+ * routed clear of the forward edge between the same two nodes, and carries a
+ * real accessible name; the default `"forward"` renders exactly as before.
+ *
+ * Selected state uses `--ring` (matching the `ring-ring` treatment `FlowNode`/
+ * `FlowGroupNode` use), overriding weight/value-derived width and colour so a
+ * selected edge always reads clearly. No stroke-dasharray animation — reduced
+ * motion is respected because there is no motion to reduce.
+ *
+ * KEYBOARD FOCUS is a separate state, drawn by `FlowEdgePath` (#286): selection
+ * needs a consumer's `onEdgesChange` to ever become true, so it can never be the
+ * indicator a tab stop owes its user.
+ */
+export function FlowWeightedEdge({
+  id,
+  sourceX,
+  sourceY,
+  targetX,
+  targetY,
+  sourcePosition,
+  targetPosition,
+  markerEnd,
+  style,
+  selected,
+  data,
+}: EdgeProps<BrandFlowWeightedEdge>) {
+  const edges = useEdges();
+  const widthByEdgeId = useMemo(
+    () => computeEdgeWeightScale(edges as unknown as WeightedEdgeLike[]),
+    [edges],
+  );
+
+  const variant = data?.variant ?? "forward";
+  const isBack = variant === "back";
+  // Only a BACK edge needs the node rects (to route its return leg around the cards it
+  // crosses). `useNodes()` would subscribe every edge to the whole nodes array, which the
+  // store replaces on each drag frame, selection and resize — so every forward edge on
+  // the canvas re-rendered on any node change anywhere. The forward branch hands back one
+  // frozen constant, which `useStore`'s default `Object.is` compares equal every time.
+  const nodes = useStore(
+    useCallback((s: ReactFlowState) => (isBack ? s.nodes : NO_NODES), [isBack]),
+  );
+  const pathType = data?.path ?? "bezier";
+
+  // Ranks advance vertically when the handles are on the top/bottom faces. Read from the
+  // TARGET side: `sourcePosition` on a self-connecting or hand-placed edge can disagree,
+  // and it is the incoming face that decides which way the last leg must approach from.
+  const axis =
+    targetPosition === Position.Top || targetPosition === Position.Bottom
+      ? "vertical"
+      : "horizontal";
+  const rects = useMemo<BackEdgeNodeRect[]>(() => {
+    if (!isBack) return [];
+    const out: BackEdgeNodeRect[] = [];
+    for (const node of nodes) {
+      // A child node's `position` is parent-relative, so it is not comparable with the
+      // absolute handle coordinates this edge is placed against. Skipping one only costs
+      // a little clearance; mixing coordinate spaces would move the leg somewhere wrong.
+      if (node.parentId) continue;
+      const width = node.measured?.width ?? node.width;
+      const height = node.measured?.height ?? node.height;
+      if (!width || !height) continue;
+      out.push({ x: node.position.x, y: node.position.y, width, height });
+    }
+    return out;
+  }, [isBack, nodes]);
+  const detour = isBack
+    ? backEdgeDetour(
+        rects,
+        axis,
+        axis === "vertical" ? [sourceY, targetY] : [sourceX, targetX],
+        BACK_EDGE_CLEARANCE,
+      )
+    : null;
+
+  const [edgePath, labelX, labelY] = isBack
+    ? getSmoothStepPath({
+        sourceX,
+        sourceY,
+        sourcePosition,
+        targetX,
+        targetY,
+        targetPosition,
+        offset: BACK_EDGE_CLEARANCE,
+        ...(detour === null ? {} : axis === "vertical" ? { centerX: detour } : { centerY: detour }),
+      })
+    : pathType === "smoothstep"
+      ? getSmoothStepPath({ sourceX, sourceY, sourcePosition, targetX, targetY, targetPosition })
+      : getBezierPath({ sourceX, sourceY, sourcePosition, targetX, targetY, targetPosition });
+
+  const scaledWidth = widthByEdgeId.get(id) ?? DEFAULT_EDGE_WIDTH_RANGE[0];
+  const valueColor = useMemo(
+    () => resolveValueStrokeColor(data?.value, data?.valueDomain),
+    [data?.value, data?.valueDomain],
+  );
+
+  const stroke = selected ? "var(--ring)" : (valueColor ?? "var(--flow-edge)");
+  const strokeWidth = selected ? scaledWidth + 1.5 : scaledWidth;
+
+  const edge = (
+    <FlowEdgePath
+      id={id}
+      path={edgePath}
+      markerEnd={markerEnd}
+      data-slot="flow-weighted-edge"
+      data-variant={variant}
+      data-weight={data?.weight}
+      data-value={data?.value}
+      stroke={stroke}
+      strokeWidth={strokeWidth}
+      strokeDasharray={isBack ? BACK_EDGE_DASHARRAY : undefined}
+      strokeOpacity={isBack ? BACK_EDGE_OPACITY : undefined}
+      style={style}
+    />
+  );
+
+  return (
+    <>
+      {isBack ? (
+        // A `data-variant` is invisible to assistive technology, so the back
+        // edge's meaning is also published as a named graphic. Only the back
+        // variant is wrapped — a forward edge's DOM is unchanged from before
+        // this prop existed.
+        <g role="img" aria-label={data?.variantLabel ?? DEFAULT_BACK_EDGE_LABEL}>
+          {edge}
+        </g>
+      ) : (
+        edge
+      )}
+      <EdgeLabelPill
+        label={data?.label}
+        secondaryLabel={data?.secondaryLabel}
+        x={labelX}
+        y={labelY}
+        selected={selected}
+        {...data?.labelProps}
+      />
+    </>
+  );
+}

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

@@ -0,0 +1,18 @@
+export {
+  FlowWeightedEdge,
+  type FlowWeightedEdgeData,
+  type BrandFlowWeightedEdge,
+} from "./flow-weighted-edge";
+export { EdgeLabelPill, type EdgeLabelPillProps } from "./edge-label-pill";
+export { backEdgeDetour, type BackEdgeAxis, type BackEdgeNodeRect } from "./back-edge-geometry";
+export {
+  computeEdgeWeightScale,
+  DEFAULT_EDGE_WIDTH_RANGE,
+  type EdgeWeightScaleOptions,
+  type WeightedEdgeLike,
+} from "./weight-scale";
+export {
+  buildWeightedEdgeAriaLabel,
+  withWeightedEdgeAria,
+  type WeightedEdgeAriaOptions,
+} from "./edge-aria";

package/src/flow-weighted-edge/weight-scale.test.ts

@@ -0,0 +1,92 @@
+import { describe, expect, it } from "vitest";
+import {
+  computeEdgeWeightScale,
+  DEFAULT_EDGE_WIDTH_RANGE,
+  type WeightedEdgeLike,
+} from "./weight-scale";
+
+describe("computeEdgeWeightScale", () => {
+  it("spans exactly the default [1.5, 8] range, linearly, for weights 1..10", () => {
+    const edges: WeightedEdgeLike[] = Array.from({ length: 10 }, (_, i) => ({
+      id: `e${i + 1}`,
+      data: { weight: i + 1 },
+    }));
+    const scale = computeEdgeWeightScale(edges);
+    expect(scale.get("e1")).toBeCloseTo(1.5);
+    expect(scale.get("e10")).toBeCloseTo(8);
+    // Linear: the midpoint weight (5.5) lands at the midpoint width.
+    const mid = (1.5 + 8) / 2;
+    const w5 = scale.get("e5")!;
+    const w6 = scale.get("e6")!;
+    expect((w5 + w6) / 2).toBeCloseTo(mid, 1);
+  });
+
+  it("gives an edge with no data.weight the range floor (matches the existing fixed 1.5px edge)", () => {
+    const edges: WeightedEdgeLike[] = [
+      { id: "unweighted" },
+      { id: "weighted", data: { weight: 4 } },
+    ];
+    const scale = computeEdgeWeightScale(edges);
+    expect(scale.get("unweighted")).toBe(DEFAULT_EDGE_WIDTH_RANGE[0]);
+  });
+
+  it("scales edges sharing a scaleGroup against one domain, independent of other groups", () => {
+    const edges: WeightedEdgeLike[] = [
+      { id: "a1", data: { weight: 1, scaleGroup: "a" } },
+      { id: "a2", data: { weight: 2, scaleGroup: "a" } },
+      { id: "b1", data: { weight: 100, scaleGroup: "b" } },
+      { id: "b2", data: { weight: 200, scaleGroup: "b" } },
+    ];
+    const scale = computeEdgeWeightScale(edges);
+    expect(scale.get("a1")).toBeCloseTo(1.5);
+    expect(scale.get("a2")).toBeCloseTo(8);
+    expect(scale.get("b1")).toBeCloseTo(1.5);
+    expect(scale.get("b2")).toBeCloseTo(8);
+  });
+
+  it("groups edges with no scaleGroup into one shared default domain", () => {
+    const edges: WeightedEdgeLike[] = [
+      { id: "x", data: { weight: 0 } },
+      { id: "y", data: { weight: 10 } },
+    ];
+    const scale = computeEdgeWeightScale(edges);
+    expect(scale.get("x")).toBeCloseTo(1.5);
+    expect(scale.get("y")).toBeCloseTo(8);
+  });
+
+  it("gives the sole member of a group (no variance) the midpoint of the range", () => {
+    const edges: WeightedEdgeLike[] = [{ id: "solo", data: { weight: 42, scaleGroup: "only" } }];
+    const scale = computeEdgeWeightScale(edges);
+    expect(scale.get("solo")).toBeCloseTo((1.5 + 8) / 2);
+  });
+
+  it("honours a custom widthRange", () => {
+    const edges: WeightedEdgeLike[] = [
+      { id: "a", data: { weight: 0 } },
+      { id: "b", data: { weight: 10 } },
+    ];
+    const scale = computeEdgeWeightScale(edges, { widthRange: [2, 20] });
+    expect(scale.get("a")).toBeCloseTo(2);
+    expect(scale.get("b")).toBeCloseTo(20);
+  });
+
+  it("restricting to a scaleGroup excludes edges from other groups from the result", () => {
+    const edges: WeightedEdgeLike[] = [
+      { id: "a1", data: { weight: 1, scaleGroup: "a" } },
+      { id: "b1", data: { weight: 100, scaleGroup: "b" } },
+    ];
+    const scale = computeEdgeWeightScale(edges, { scaleGroup: "a" });
+    expect(scale.has("a1")).toBe(true);
+    expect(scale.has("b1")).toBe(false);
+  });
+
+  it("is pure — the same input always produces equal output", () => {
+    const edges: WeightedEdgeLike[] = [
+      { id: "a", data: { weight: 3 } },
+      { id: "b", data: { weight: 7 } },
+    ];
+    const first = computeEdgeWeightScale(edges);
+    const second = computeEdgeWeightScale(edges);
+    expect([...first.entries()]).toEqual([...second.entries()]);
+  });
+});

package/src/flow-weighted-edge/weight-scale.ts

@@ -0,0 +1,86 @@
+/**
+ * weight-scale — pure, framework-free "edge weight → stroke width" scale.
+ *
+ * `FlowWeightedEdge` calls this with every edge in the flow (via `useEdges()`,
+ * memoized) so a group of edges can be min-maxed against ONE shared domain
+ * instead of each edge picking its own arbitrary width. No React, no DOM: a
+ * sibling (e.g. RM-045's continuous `Legend`) can call it directly to render
+ * the same ramp the edges use, and it is trivially unit-testable.
+ */
+
+/** Minimal edge shape the scale needs — a subset of `Edge<FlowWeightedEdgeData>`. */
+export interface WeightedEdgeLike {
+  id: string;
+  data?: {
+    weight?: number;
+    scaleGroup?: string;
+  };
+}
+
+export interface EdgeWeightScaleOptions {
+  /** Output stroke-width range, in px. @default [1.5, 8] */
+  widthRange?: [number, number];
+  /**
+   * Restrict the domain calculation (and the returned map) to edges whose
+   * `data.scaleGroup` equals this value — edges in a different group are
+   * skipped entirely. Omit to compute one scale per distinct `scaleGroup`
+   * present in `edges` (edges with no `scaleGroup` share one implicit
+   * default group, so a flow that never sets it still gets one shared
+   * domain — "all edges in the same `<ReactFlow>`").
+   */
+  scaleGroup?: string;
+}
+
+/** Matches today's fixed 1.5px `FlowEdge` stroke, so an unweighted edge is unchanged. */
+export const DEFAULT_EDGE_WIDTH_RANGE: [number, number] = [1.5, 8];
+
+const DEFAULT_SCALE_GROUP = "__default__";
+
+/**
+ * Resolve every edge's `data.weight` into a stroke-width, linearly min-maxed
+ * into `widthRange` per `scaleGroup`. An edge with no `data.weight` gets the
+ * range floor — the existing fixed 1.5px `FlowEdge` already draws, so a plain
+ * edge renders unchanged. An edge that is the only member of its group (or
+ * whose group has zero weight variance) gets the midpoint of the range —
+ * there is no domain to compare it against.
+ */
+export function computeEdgeWeightScale(
+  edges: WeightedEdgeLike[],
+  opts: EdgeWeightScaleOptions = {},
+): Map<string, number> {
+  const [minWidth, maxWidth] = opts.widthRange ?? DEFAULT_EDGE_WIDTH_RANGE;
+  const result = new Map<string, number>();
+  const groups = new Map<string, { id: string; weight: number }[]>();
+
+  for (const edge of edges) {
+    const weight = edge.data?.weight;
+    if (weight === undefined) {
+      result.set(edge.id, minWidth);
+      continue;
+    }
+    const group = edge.data?.scaleGroup ?? DEFAULT_SCALE_GROUP;
+    if (opts.scaleGroup !== undefined && group !== opts.scaleGroup) continue;
+    const list = groups.get(group);
+    if (list) list.push({ id: edge.id, weight });
+    else groups.set(group, [{ id: edge.id, weight }]);
+  }
+
+  for (const list of groups.values()) {
+    let min = Infinity;
+    let max = -Infinity;
+    for (const { weight } of list) {
+      if (weight < min) min = weight;
+      if (weight > max) max = weight;
+    }
+    const span = max - min;
+    for (const { id, weight } of list) {
+      const width =
+        span === 0
+          ? (minWidth + maxWidth) / 2
+          : minWidth + ((weight - min) / span) * (maxWidth - minWidth);
+      result.set(id, width);
+    }
+  }
+
+  return result;
+}

package/src/index.ts

@@ -5,8 +5,11 @@
  *   import "@xyflow/react/dist/style.css";
  */
 export * from "./canvas-shell";
+export * from "./flow-handle";
 export * from "./flow-node";
 export * from "./flow-edge";
+// The shared edge path + keyboard focus indicator every edge type draws through (#286).
+export * from "./flow-edge-path";
 export * from "./flow-smart-edge";
 export * from "./flow-floating-edge";
 export * from "./flow-placeholder-node";
@@ -35,3 +38,9 @@ export {
   addEdge,
 } from "@xyflow/react";
 export type { Node, Edge, Connection, NodeProps, EdgeProps } from "@xyflow/react";
+
+// FlowWeightedEdge — RM-043
+export * from "./flow-weighted-edge";
+
+// FlowSelfLoopEdge — RM-044
+export * from "./flow-self-loop-edge";

package/src/inspector-panel/inspector-panel.stories.tsx

@@ -93,7 +93,7 @@ function CollapsibleDemo() {
           type="button"
           aria-expanded={open}
           onClick={() => setOpen((o) => !o)}
-          className="rounded-md border border-input px-3 py-1.5 text-body hover:bg-accent focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+          className="rounded-md border border-input px-3 py-1.5 text-body hover:bg-accent focus-ring"
         >
           Toggle inspector
         </button>

package/src/inspector-panel/inspector-panel.test.tsx

@@ -79,4 +79,24 @@ describe("InspectorPanel", () => {
     // Content stays mounted (the width tween needs a mounted node).
     expect(screen.getByText("Details")).toBeInTheDocument();
   });
+
+  it("keeps its scrollable body reachable by keyboard, selected or not", () => {
+    // A region that scrolls but holds nothing focusable is readable with a mouse and
+    // unreachable without one (axe `scrollable-region-focusable`). Inspector content is
+    // usually exactly that — text, a definition list, a chart — so the container itself
+    // has to take focus. Asserted in BOTH branches: the empty message scrolls too.
+    const { container, rerender } = render(
+      <InspectorPanel hasSelection={false} emptyMessage="Nothing selected.">
+        <p>Hidden while nothing is selected.</p>
+      </InspectorPanel>,
+    );
+    expect(container.querySelector(".overflow-y-auto")).toHaveAttribute("tabindex", "0");
+
+    rerender(
+      <InspectorPanel hasSelection>
+        <p>Plain text, nothing focusable.</p>
+      </InspectorPanel>,
+    );
+    expect(container.querySelector(".overflow-y-auto")).toHaveAttribute("tabindex", "0");
+  });
 });

package/src/inspector-panel/inspector-panel.tsx

@@ -90,7 +90,7 @@ export function InspectorPanel({
                 type="button"
                 aria-label="Close inspector"
                 onClick={onClose}
-                className="rounded-sm p-1 text-muted-foreground hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+                className="rounded-sm p-1 text-muted-foreground hover:text-foreground focus-ring"
               >
                 <svg
                   width="14"
@@ -108,17 +108,27 @@ export function InspectorPanel({
               </button>
             ) : null}
           </div>
+          {/*
+            `tabIndex={0}` on a scroll container, in both branches: a region that scrolls
+            but contains nothing focusable is unreachable by keyboard — a mouse user can
+            read the overflow and a keyboard user cannot (axe
+            `scrollable-region-focusable`). An inspector body is exactly that shape
+            whenever its content is plain text, a definition list or a chart, which is
+            most of the time. It carries `focus-ring` because anything that can take
+            focus has to show it.
+          */}
           {hasSelection ? (
             <Reveal
               key={selectionKey}
               appear="fade"
               speed="fast"
-              className="flex-1 overflow-y-auto p-4 text-body"
+              tabIndex={0}
+              className="focus-ring flex-1 overflow-y-auto p-4 text-body"
             >
               {children}
             </Reveal>
           ) : (
-            <div className="flex-1 overflow-y-auto p-4 text-body">
+            <div tabIndex={0} className="focus-ring flex-1 overflow-y-auto p-4 text-body">
               <p className="text-muted-foreground">{emptyMessage}</p>
             </div>
           )}

package/src/legend/index.ts

@@ -1 +1,7 @@
-export { Legend, type LegendProps, type LegendItem } from "./legend";
+export {
+  Legend,
+  type LegendProps,
+  type LegendItem,
+  type LegendCategoricalProps,
+  type LegendScaleProps,
+} from "./legend";