@tensor_1/react 2.17.0 → 2.18.0

package/README.md

@@ -61,4 +61,33 @@ traversal, three-way JSON diffing, metric parsing/stepping, color conversion and
 contrast checks, plus brand-profile apply/restore helpers. No graph or date
 runtime dependency is required.
 
+### RelationshipGraph layouts
+
+`RelationshipGraph` has two layouts:
+- `radial` (the default): a small neighbourhood ringed around the selection.
+- `layered` (ADR-0003): reads left to right by distance from `rootId`.
+
+Layered mode draws shared nodes once, marks cycles, collapses leaf fan-outs into clusters and labels edges. It adds structural keyboard traversal (←/→ along edges, ↑/↓ in a column, Home, End), pan and Ctrl/⌘-wheel zoom.
+
+```tsx
+<RelationshipGraph
+  layout="layered"
+  rootId={root.id}
+  nodes={nodes}            // { id, label, type?, description?, depth? }
+  edges={edges}            // { id, source, target, type?, label?, arrow?, emphasis? }
+  labels={translatedLabels} // Partial<RelationshipGraphLabels>
+  renderNode={(node) => <MyNodeBody node={node} />}
+  nodeAriaLabel={(node) => `${node.label}, ${riskText(node)}`}
+  onSelect={openPeek}
+  height="clamp(360px, 60vh, 640px)"
+/>
+```
+
+Rules the component cannot enforce for you:
+
+- **Whatever `renderNode` / `renderCluster` shows must also be in the accessible name.** Pass `nodeAriaLabel` whenever the node body carries meaning beyond `label`, `type` and `description`.
+- **Keep the equivalent list.** `showList={false}` is allowed only when the same labelled region renders a complete equivalent: every node, its relations and its state.
+- **Dimming is not a signal.** `dimmedNodeIds` must be accompanied by text that says what is dimmed and why.
+- **Localise everything.** Every visible and announced string comes from `labels`; the English defaults live in `DEFAULT_RELATIONSHIP_GRAPH_LABELS`.
+
 Ships **ESM + CJS + types**, with per-file `"use client"` so it's safe under React Server Components. Part of the **[UIx v2 styleguide](https://github.com/COx-ORG-H/UIx)**.

package/dist/components/RelationshipGraph.d.ts

@@ -1,10 +1,54 @@
 import * as react from 'react';
-import { RelationshipGraphNode, RelationshipGraphEdge } from '../relationship-graph-model.js';
+import { ReactNode } from 'react';
+import { RelationshipGraphNode, RelationshipGraphEdge, RelationshipGraphCluster } from '../relationship-graph-model.js';
 
 interface RelationshipGraphLegendItem {
     id: string;
     label: string;
 }
+/** Every visible or announced string. Pass translations; English defaults fill the gaps. */
+interface RelationshipGraphLabels {
+    graph: string;
+    controls: string;
+    list: string;
+    listHeading: string;
+    legend: string;
+    panLeft: string;
+    panRight: string;
+    panUp: string;
+    panDown: string;
+    left: string;
+    right: string;
+    up: string;
+    down: string;
+    zoomIn: string;
+    zoomOut: string;
+    fit: string;
+    reset: string;
+    zoomLevel: (percent: number) => string;
+    bounded: (shown: number, omitted: number) => string;
+    graphSummary: (nodes: number, edges: number) => string;
+    relationship: string;
+    conflict: string;
+    connectedTo: (names: string) => string;
+    noConnections: string;
+    expandNeighbors: string;
+    openDetails: string;
+    /** Layered column header, e.g. "2 hops · 14". */
+    column: (depth: number, count: number) => string;
+    cluster: (count: number, type: string | undefined, edgeLabel: string | undefined) => string;
+    expandCluster: string;
+    collapseCluster: (count: number, type: string | undefined) => string;
+    cycle: string;
+    relationships: (count: number) => string;
+    roleDescription: string;
+    keyboardHint: string;
+    loading: string;
+    retry: string;
+    emptyTitle: string;
+    emptyHint: string;
+}
+declare const DEFAULT_RELATIONSHIP_GRAPH_LABELS: RelationshipGraphLabels;
 interface RelationshipGraphProps {
     nodes: RelationshipGraphNode[];
     edges: RelationshipGraphEdge[];
@@ -12,6 +56,7 @@ interface RelationshipGraphProps {
     onSelect?: (node: RelationshipGraphNode) => void;
     onExpandNeighbors?: (node: RelationshipGraphNode) => void;
     onOpenDetails?: (node: RelationshipGraphNode) => void;
+    /** Node budget. Default 40 (radial) or 400 (layered). */
     maxNodes?: number;
     density?: 'compact' | 'standard';
     highlightedNodeIds?: ReadonlySet<string>;
@@ -23,8 +68,41 @@ interface RelationshipGraphProps {
     error?: string;
     onRetry?: () => void;
     className?: string;
+    /** `radial` (default) rings around the selection; `layered` reads left to right by distance from `rootId`. */
+    layout?: 'radial' | 'layered';
+    /** Layered: the column-0 node (default: the first node). */
+    rootId?: string;
+    labels?: Partial<RelationshipGraphLabels>;
+    /** Layered: node body. Whatever it shows must also be in `nodeAriaLabel`. */
+    renderNode?: (node: RelationshipGraphNode, state: {
+        selected: boolean;
+        dimmed: boolean;
+    }) => ReactNode;
+    /** Layered: full accessible name for a node. */
+    nodeAriaLabel?: (node: RelationshipGraphNode) => string;
+    /** Layered: cluster body. Whatever it shows must also be in the cluster's accessible name. */
+    renderCluster?: (cluster: RelationshipGraphCluster) => ReactNode;
+    /** Layered: minimum leaf-sibling group that collapses into a cluster. Default 6; 0 disables. */
+    clusterThreshold?: number;
+    /** Layered: controlled set of expanded cluster ids. */
+    expandedClusterIds?: ReadonlySet<string>;
+    onToggleCluster?: (clusterId: string, expanded: boolean) => void;
+    /** Layered: nodes drawn muted (state must also be stated in text by the consumer). */
+    dimmedNodeIds?: ReadonlySet<string>;
+    /** Layered: when edge labels show. `auto` = emphasised edges, small fan-outs, and edges of the active node. */
+    edgeLabels?: 'auto' | 'always' | 'never';
+    /** Render the built-in equivalent list. Set false ONLY when an equivalent list is rendered in the same region. */
+    showList?: boolean;
+    /** Layered: CSS length for the viewport height. */
+    height?: string;
+    /** Layered: controlled roving focus. */
+    focusId?: string;
+    onFocusChange?: (id: string) => void;
 }
 /** Bounded, deterministic SVG relationship view with an equivalent accessible list. */
-declare function RelationshipGraph({ nodes, edges, selectedId, onSelect, onExpandNeighbors, onOpenDetails, maxNodes, density, highlightedNodeIds, conflictedNodeIds, highlightedEdgeIds, conflictedEdgeIds, legend, loading, error, onRetry, className, }: RelationshipGraphProps): react.JSX.Element;
+declare function RelationshipGraph(props: RelationshipGraphProps): react.JSX.Element;
+type ResolvedRelationshipGraphProps = Omit<RelationshipGraphProps, 'labels'> & {
+    labels: RelationshipGraphLabels;
+};
 
-export { RelationshipGraph, type RelationshipGraphLegendItem, type RelationshipGraphProps };
+export { DEFAULT_RELATIONSHIP_GRAPH_LABELS, RelationshipGraph, type RelationshipGraphLabels, type RelationshipGraphLegendItem, type RelationshipGraphProps, type ResolvedRelationshipGraphProps };

package/dist/components/RelationshipGraph.js

@@ -1,11 +1,70 @@
 "use client";
 import { jsx, jsxs } from "react/jsx-runtime";
 import { useMemo, useRef, useState } from "react";
-import { boundRelationshipGraph, layoutRelationshipGraph, relationshipNeighbors, traverseRelationshipNode } from "../relationship-graph-model.js";
+import { boundRelationshipGraph, layoutRelationshipGraph, traverseRelationshipNode } from "../relationship-graph-model.js";
 import { cx } from "../cx.js";
+import { LayeredRelationshipGraph } from "./RelationshipGraphLayered.js";
+import { EquivalentRelationshipList } from "./RelationshipGraphList.js";
+const DEFAULT_RELATIONSHIP_GRAPH_LABELS = {
+  graph: "Relationship graph",
+  controls: "Graph view controls",
+  list: "Accessible relationship list",
+  listHeading: "Relationship list",
+  legend: "Relationship types",
+  panLeft: "Pan left",
+  panRight: "Pan right",
+  panUp: "Pan up",
+  panDown: "Pan down",
+  left: "Left",
+  right: "Right",
+  up: "Up",
+  down: "Down",
+  zoomIn: "Zoom in",
+  zoomOut: "Zoom out",
+  fit: "Fit",
+  reset: "Reset view",
+  zoomLevel: (percent) => `Zoom ${percent}%`,
+  bounded: (shown, omitted) => `Showing ${shown} nodes; ${omitted} outside this bounded neighborhood.`,
+  graphSummary: (nodes, edges) => `Graph with ${nodes} nodes and ${edges} relationships`,
+  relationship: "Relationship",
+  conflict: "conflict",
+  connectedTo: (names) => `Connected to ${names}`,
+  noConnections: "No visible connections",
+  expandNeighbors: "Expand neighbors",
+  openDetails: "Open details",
+  column: (depth, count) => `${depth === 0 ? "Start" : `${depth} ${depth === 1 ? "hop" : "hops"}`} \xB7 ${count}`,
+  cluster: (count, type, edgeLabel) => `${count} \xD7 ${type ?? "items"}${edgeLabel ? ` \xB7 ${edgeLabel}` : ""}`,
+  expandCluster: "Show all",
+  collapseCluster: (count, type) => `Collapse ${count} ${type ?? "items"}`,
+  cycle: "cycle",
+  relationships: (count) => `${count} ${count === 1 ? "relationship" : "relationships"}`,
+  roleDescription: "relationship map",
+  keyboardHint: "Arrow keys move between connected items, Enter selects, Home returns to the start.",
+  loading: "Loading relationships\u2026",
+  retry: "Try again",
+  emptyTitle: "No relationships to display.",
+  emptyHint: "Adjust the neighborhood or filters to include a node."
+};
 const EMPTY_IDS = /* @__PURE__ */ new Set();
 const EMPTY_LEGEND = [];
-function RelationshipGraph({
+function RelationshipGraph(props) {
+  const labels = useMemo(() => ({ ...DEFAULT_RELATIONSHIP_GRAPH_LABELS, ...props.labels }), [props.labels]);
+  const stateClass = cx("uix-relationship-graph uix-relationship-graph--state", props.className);
+  if (props.loading) return /* @__PURE__ */ jsx("div", { className: stateClass, role: "status", children: labels.loading });
+  if (props.error) {
+    return /* @__PURE__ */ jsxs("div", { className: stateClass, role: "alert", children: [
+      /* @__PURE__ */ jsx("p", { children: props.error }),
+      props.onRetry && /* @__PURE__ */ jsx("button", { type: "button", className: "uix-btn uix-btn--secondary", onClick: props.onRetry, children: labels.retry })
+    ] });
+  }
+  if (props.nodes.length === 0) return /* @__PURE__ */ jsxs("div", { className: stateClass, children: [
+    /* @__PURE__ */ jsx("p", { children: labels.emptyTitle }),
+    /* @__PURE__ */ jsx("p", { children: labels.emptyHint })
+  ] });
+  if (props.layout === "layered") return /* @__PURE__ */ jsx(LayeredRelationshipGraph, { ...props, labels });
+  return /* @__PURE__ */ jsx(RadialRelationshipGraph, { ...props, labels });
+}
+function RadialRelationshipGraph({
   nodes,
   edges,
   selectedId,
@@ -19,10 +78,9 @@ function RelationshipGraph({
   highlightedEdgeIds = EMPTY_IDS,
   conflictedEdgeIds = EMPTY_IDS,
   legend = EMPTY_LEGEND,
-  loading,
-  error,
-  onRetry,
-  className
+  className,
+  labels,
+  showList = true
 }) {
   const bounded = useMemo(() => boundRelationshipGraph(nodes, edges, maxNodes), [nodes, edges, maxNodes]);
   const positioned = useMemo(() => layoutRelationshipGraph(bounded.nodes, bounded.edges, selectedId), [bounded, selectedId]);
@@ -53,49 +111,30 @@ function RelationshipGraph({
     setZoom(1);
     setPan({ x: 0, y: 0 });
   };
-  if (loading) return /* @__PURE__ */ jsx("div", { className: cx("uix-relationship-graph uix-relationship-graph--state", className), role: "status", children: "Loading relationships\u2026" });
-  if (error) return /* @__PURE__ */ jsxs("div", { className: cx("uix-relationship-graph uix-relationship-graph--state", className), role: "alert", children: [
-    /* @__PURE__ */ jsx("p", { children: error }),
-    onRetry && /* @__PURE__ */ jsx("button", { type: "button", className: "uix-btn uix-btn--secondary", onClick: onRetry, children: "Try again" })
-  ] });
-  if (bounded.nodes.length === 0) return /* @__PURE__ */ jsxs("div", { className: cx("uix-relationship-graph uix-relationship-graph--state", className), children: [
-    /* @__PURE__ */ jsx("p", { children: "No relationships to display." }),
-    /* @__PURE__ */ jsx("p", { children: "Adjust the neighborhood or filters to include a node." })
-  ] });
-  return /* @__PURE__ */ jsxs("section", { className: cx("uix-relationship-graph", `uix-relationship-graph--${density}`, className), "aria-label": "Relationship graph", children: [
-    /* @__PURE__ */ jsxs("div", { className: "uix-relationship-graph__toolbar", "aria-label": "Graph view controls", children: [
-      /* @__PURE__ */ jsx("button", { type: "button", onClick: () => setPan((value) => ({ ...value, x: value.x - 24 })), "aria-label": "Pan left", children: "Left" }),
-      /* @__PURE__ */ jsx("button", { type: "button", onClick: () => setPan((value) => ({ ...value, y: value.y - 24 })), "aria-label": "Pan up", children: "Up" }),
-      /* @__PURE__ */ jsx("button", { type: "button", onClick: () => setPan((value) => ({ ...value, y: value.y + 24 })), "aria-label": "Pan down", children: "Down" }),
-      /* @__PURE__ */ jsx("button", { type: "button", onClick: () => setPan((value) => ({ ...value, x: value.x + 24 })), "aria-label": "Pan right", children: "Right" }),
-      /* @__PURE__ */ jsx("button", { type: "button", onClick: () => setZoom((value) => Math.min(2, Number((value + 0.2).toFixed(1)))), "aria-label": "Zoom in", children: "Zoom in" }),
-      /* @__PURE__ */ jsx("button", { type: "button", onClick: () => setZoom((value) => Math.max(0.5, Number((value - 0.2).toFixed(1)))), "aria-label": "Zoom out", children: "Zoom out" }),
-      /* @__PURE__ */ jsx("button", { type: "button", onClick: reset, children: "Reset view" }),
-      /* @__PURE__ */ jsxs("span", { "aria-live": "polite", children: [
-        "Zoom ",
-        Math.round(zoom * 100),
-        "%"
-      ] })
-    ] }),
-    bounded.omittedNodeCount > 0 && /* @__PURE__ */ jsxs("p", { className: "uix-relationship-graph__bounded", role: "status", children: [
-      "Showing ",
-      bounded.nodes.length,
-      " nodes; ",
-      bounded.omittedNodeCount,
-      " outside this bounded neighborhood."
+  return /* @__PURE__ */ jsxs("section", { className: cx("uix-relationship-graph", `uix-relationship-graph--${density}`, className), "aria-label": labels.graph, children: [
+    /* @__PURE__ */ jsxs("div", { className: "uix-relationship-graph__toolbar", "aria-label": labels.controls, children: [
+      /* @__PURE__ */ jsx("button", { type: "button", onClick: () => setPan((value) => ({ ...value, x: value.x - 24 })), "aria-label": labels.panLeft, children: labels.left }),
+      /* @__PURE__ */ jsx("button", { type: "button", onClick: () => setPan((value) => ({ ...value, y: value.y - 24 })), "aria-label": labels.panUp, children: labels.up }),
+      /* @__PURE__ */ jsx("button", { type: "button", onClick: () => setPan((value) => ({ ...value, y: value.y + 24 })), "aria-label": labels.panDown, children: labels.down }),
+      /* @__PURE__ */ jsx("button", { type: "button", onClick: () => setPan((value) => ({ ...value, x: value.x + 24 })), "aria-label": labels.panRight, children: labels.right }),
+      /* @__PURE__ */ jsx("button", { type: "button", onClick: () => setZoom((value) => Math.min(2, Number((value + 0.2).toFixed(1)))), "aria-label": labels.zoomIn, children: labels.zoomIn }),
+      /* @__PURE__ */ jsx("button", { type: "button", onClick: () => setZoom((value) => Math.max(0.5, Number((value - 0.2).toFixed(1)))), "aria-label": labels.zoomOut, children: labels.zoomOut }),
+      /* @__PURE__ */ jsx("button", { type: "button", onClick: reset, children: labels.reset }),
+      /* @__PURE__ */ jsx("span", { "aria-live": "polite", children: labels.zoomLevel(Math.round(zoom * 100)) })
     ] }),
-    /* @__PURE__ */ jsx("div", { className: "uix-relationship-graph__visual", children: /* @__PURE__ */ jsx("svg", { ref: svgRef, viewBox: "0 0 600 400", role: "group", "aria-label": `Graph with ${bounded.nodes.length} nodes and ${bounded.edges.length} relationships`, children: /* @__PURE__ */ jsxs("g", { transform: `translate(${pan.x} ${pan.y}) scale(${zoom})`, children: [
+    bounded.omittedNodeCount > 0 && /* @__PURE__ */ jsx("p", { className: "uix-relationship-graph__bounded", role: "status", children: labels.bounded(bounded.nodes.length, bounded.omittedNodeCount) }),
+    /* @__PURE__ */ jsx("div", { className: "uix-relationship-graph__visual", children: /* @__PURE__ */ jsx("svg", { ref: svgRef, viewBox: "0 0 600 400", role: "group", "aria-label": labels.graphSummary(bounded.nodes.length, bounded.edges.length), children: /* @__PURE__ */ jsxs("g", { transform: `translate(${pan.x} ${pan.y}) scale(${zoom})`, children: [
       bounded.edges.map((edge) => {
         const source = positionedById.get(edge.source);
         const target = positionedById.get(edge.target);
-        return /* @__PURE__ */ jsx("line", { x1: source.x * 6, y1: source.y * 4, x2: target.x * 6, y2: target.y * 4, className: "uix-relationship-graph__edge", "data-highlighted": highlightedEdgeIds.has(edge.id) || void 0, "data-conflicted": conflictedEdgeIds.has(edge.id) || void 0, children: /* @__PURE__ */ jsx("title", { children: edge.label ?? edge.type ?? "Relationship" }) }, edge.id);
+        return /* @__PURE__ */ jsx("line", { x1: source.x * 6, y1: source.y * 4, x2: target.x * 6, y2: target.y * 4, className: "uix-relationship-graph__edge", "data-highlighted": highlightedEdgeIds.has(edge.id) || void 0, "data-conflicted": conflictedEdgeIds.has(edge.id) || void 0, children: /* @__PURE__ */ jsx("title", { children: edge.label ?? edge.type ?? labels.relationship }) }, edge.id);
       }),
       positioned.map((node) => /* @__PURE__ */ jsxs(
         "g",
         {
           transform: `translate(${node.x * 6} ${node.y * 4})`,
           role: "button",
-          "aria-label": `${node.label}${node.type ? `, ${node.type}` : ""}${conflictedNodeIds.has(node.id) ? ", conflict" : ""}`,
+          "aria-label": `${node.label}${node.type ? `, ${node.type}` : ""}${conflictedNodeIds.has(node.id) ? `, ${labels.conflict}` : ""}`,
           tabIndex: focusedId === node.id ? 0 : -1,
           "data-node-id": node.id,
           className: "uix-relationship-graph__node",
@@ -113,26 +152,11 @@ function RelationshipGraph({
         node.id
       ))
     ] }) }) }),
-    legend.length > 0 && /* @__PURE__ */ jsx("ul", { className: "uix-relationship-graph__legend", "aria-label": "Relationship types", children: legend.map((item) => /* @__PURE__ */ jsx("li", { "data-type": item.id, children: item.label }, item.id)) }),
-    /* @__PURE__ */ jsxs("div", { className: "uix-relationship-graph__list", role: "region", "aria-label": "Accessible relationship list", children: [
-      /* @__PURE__ */ jsx("h3", { children: "Relationship list" }),
-      /* @__PURE__ */ jsx("ul", { children: bounded.nodes.map((node) => {
-        const neighbors = relationshipNeighbors(node.id, bounded.edges).map((id) => bounded.nodes.find((item) => item.id === id)?.label ?? id);
-        return /* @__PURE__ */ jsxs("li", { "data-selected": selectedId === node.id || void 0, children: [
-          /* @__PURE__ */ jsxs("button", { type: "button", onClick: () => select(node.id), "aria-pressed": selectedId === node.id, children: [
-            /* @__PURE__ */ jsx("strong", { children: node.label }),
-            node.type && /* @__PURE__ */ jsx("span", { children: node.type }),
-            /* @__PURE__ */ jsx("span", { children: neighbors.length ? `Connected to ${neighbors.join(", ")}` : "No visible connections" })
-          ] }),
-          /* @__PURE__ */ jsxs("span", { className: "uix-relationship-graph__list-actions", children: [
-            onExpandNeighbors && /* @__PURE__ */ jsx("button", { type: "button", onClick: () => onExpandNeighbors(node), children: "Expand neighbors" }),
-            onOpenDetails && /* @__PURE__ */ jsx("button", { type: "button", onClick: () => onOpenDetails(node), children: "Open details" })
-          ] })
-        ] }, node.id);
-      }) })
-    ] })
+    legend.length > 0 && /* @__PURE__ */ jsx("ul", { className: "uix-relationship-graph__legend", "aria-label": labels.legend, children: legend.map((item) => /* @__PURE__ */ jsx("li", { "data-type": item.id, children: item.label }, item.id)) }),
+    showList && /* @__PURE__ */ jsx(EquivalentRelationshipList, { nodes: bounded.nodes, edges: bounded.edges, selectedId, labels, onSelect: select, onExpandNeighbors, onOpenDetails })
   ] });
 }
 export {
+  DEFAULT_RELATIONSHIP_GRAPH_LABELS,
   RelationshipGraph
 };

package/dist/components/RelationshipGraphLayered.d.ts

@@ -0,0 +1,8 @@
+import * as react from 'react';
+import { ResolvedRelationshipGraphProps } from './RelationshipGraph.js';
+import '../relationship-graph-model.js';
+
+/** `RelationshipGraph layout="layered"` (ADR-0003). Internal — reached through RelationshipGraph. */
+declare function LayeredRelationshipGraph({ nodes, edges, selectedId, onSelect, onExpandNeighbors, onOpenDetails, maxNodes, density, highlightedNodeIds, conflictedNodeIds, highlightedEdgeIds, conflictedEdgeIds, legend, className, labels, rootId, renderNode, nodeAriaLabel, renderCluster, clusterThreshold, expandedClusterIds, onToggleCluster, dimmedNodeIds, edgeLabels, showList, height, focusId, onFocusChange, }: ResolvedRelationshipGraphProps): react.JSX.Element;
+
+export { LayeredRelationshipGraph };