@eocrm/design-system 0.0.0-stage → 0.6.18

package/src/components/FlowCanvas/FlowControls.tsx

@@ -0,0 +1,46 @@
+import { Maximize, ZoomIn, ZoomOut } from 'lucide-react';
+import { Button } from '../Button';
+import { useTranslation } from '../../i18n/useTranslation';
+import styles from './FlowCanvas.module.scss';
+
+interface FlowControlsProps {
+  onZoomIn: () => void;
+  onZoomOut: () => void;
+  onFit: () => void;
+}
+
+/** Internal: the bottom-left zoom control cluster. */
+export function FlowControls({ onZoomIn, onZoomOut, onFit }: FlowControlsProps) {
+  const t = useTranslation();
+  return (
+    <div className={styles.controls} data-flow-controls="">
+      <Button
+        variant="secondary"
+        size="sm"
+        iconOnly
+        aria-label={t('flowCanvas.zoomIn')}
+        onClick={onZoomIn}
+      >
+        <ZoomIn size={16} aria-hidden="true" />
+      </Button>
+      <Button
+        variant="secondary"
+        size="sm"
+        iconOnly
+        aria-label={t('flowCanvas.zoomOut')}
+        onClick={onZoomOut}
+      >
+        <ZoomOut size={16} aria-hidden="true" />
+      </Button>
+      <Button
+        variant="secondary"
+        size="sm"
+        iconOnly
+        aria-label={t('flowCanvas.zoomToFit')}
+        onClick={onFit}
+      >
+        <Maximize size={16} aria-hidden="true" />
+      </Button>
+    </div>
+  );
+}

package/src/components/FlowCanvas/FlowEdge.tsx

@@ -0,0 +1,58 @@
+import { memo } from 'react';
+import type { MouseEvent as ReactMouseEvent, PointerEvent as ReactPointerEvent } from 'react';
+import type { EdgeGeometry } from './edgePath';
+import type { FlowCanvasEdge } from './types';
+import styles from './FlowCanvas.module.scss';
+
+interface FlowEdgeProps {
+  edge: FlowCanvasEdge;
+  geometry: EdgeGeometry;
+  active: boolean; // selected or focused — thicker accent stroke
+  markerId: string;
+  markerActiveId: string;
+  ariaLabel: string;
+  roleDescription: string;
+  registerEl: (id: string, el: SVGPathElement | null) => void;
+  onEdgePointerDown: (id: string, event: ReactPointerEvent<SVGPathElement>) => void;
+  onEdgeDoubleClick: (id: string, event: ReactMouseEvent<SVGPathElement>) => void;
+}
+
+/** Internal: one edge — visible path plus a wide transparent hit/focus path. */
+export const FlowEdge = memo(function FlowEdge({
+  edge,
+  geometry,
+  active,
+  markerId,
+  markerActiveId,
+  ariaLabel,
+  roleDescription,
+  registerEl,
+  onEdgePointerDown,
+  onEdgeDoubleClick,
+}: FlowEdgeProps) {
+  return (
+    <g>
+      <path
+        className={styles.edgePath}
+        d={geometry.path}
+        data-active={active || undefined}
+        markerEnd={`url(#${active ? markerActiveId : markerId})`}
+      />
+      <path
+        ref={(el) => registerEl(edge.id, el)}
+        className={styles.edgeHit}
+        d={geometry.path}
+        role="button"
+        tabIndex={-1}
+        aria-roledescription={roleDescription}
+        aria-label={ariaLabel}
+        data-flow-edge={edge.id}
+        onPointerDown={(event) => onEdgePointerDown(edge.id, event)}
+        onDoubleClick={(event) => {
+          event.stopPropagation();
+          onEdgeDoubleClick(edge.id, event);
+        }}
+      />
+    </g>
+  );
+});

package/src/components/FlowCanvas/FlowNode.tsx

@@ -0,0 +1,76 @@
+import { memo } from 'react';
+import type {
+  CSSProperties,
+  MouseEvent as ReactMouseEvent,
+  PointerEvent as ReactPointerEvent,
+} from 'react';
+import type { FlowCanvasNode, FlowCanvasPoint } from './types';
+import styles from './FlowCanvas.module.scss';
+
+interface FlowNodeProps {
+  node: FlowCanvasNode;
+  position: FlowCanvasPoint;
+  selected: boolean;
+  dragging: boolean;
+  connectTarget: boolean;
+  /** Whether connecting is enabled — gates the connect handle. */
+  canConnect: boolean;
+  roleDescription: string;
+  registerEl: (id: string, el: HTMLDivElement | null) => void;
+  onNodePointerDown: (id: string, event: ReactPointerEvent<HTMLDivElement>) => void;
+  onNodeDoubleClick: (id: string, event: ReactMouseEvent<HTMLDivElement>) => void;
+  onHandlePointerDown: (id: string, event: ReactPointerEvent<HTMLElement>) => void;
+}
+
+/** Internal: one node card. Positioned absolutely on the stage. */
+export const FlowNode = memo(function FlowNode({
+  node,
+  position,
+  selected,
+  dragging,
+  connectTarget,
+  canConnect,
+  roleDescription,
+  registerEl,
+  onNodePointerDown,
+  onNodeDoubleClick,
+  onHandlePointerDown,
+}: FlowNodeProps) {
+  const style: CSSProperties = { left: position.x, top: position.y };
+  if (node.color) (style as Record<string, string | number>)['--flow-node-color'] = node.color;
+  return (
+    // role=button: activatable via Enter (open); roledescription localizes "node".
+    <div
+      ref={(el) => registerEl(node.id, el)}
+      role="button"
+      tabIndex={-1}
+      aria-roledescription={roleDescription}
+      aria-label={node.label}
+      data-flow-node={node.id}
+      data-selected={selected || undefined}
+      data-dragging={dragging || undefined}
+      data-connect-target={connectTarget || undefined}
+      className={styles.node}
+      style={style}
+      onPointerDown={(event) => onNodePointerDown(node.id, event)}
+      onDoubleClick={(event) => {
+        event.stopPropagation();
+        onNodeDoubleClick(node.id, event);
+      }}
+    >
+      <span className={styles.nodeLabel}>{node.label}</span>
+      {node.adornment != null ? <span>{node.adornment}</span> : null}
+      {canConnect ? (
+        <span
+          aria-hidden="true"
+          className={styles.handle}
+          data-flow-handle=""
+          onPointerDown={(event) => {
+            event.stopPropagation();
+            onHandlePointerDown(node.id, event);
+          }}
+        />
+      ) : null}
+    </div>
+  );
+});

package/src/components/FlowCanvas/edgePath.ts

@@ -0,0 +1,85 @@
+/** Axis-aligned rectangle in canvas coordinates. */
+export interface Rect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/** Point in canvas coordinates. */
+export interface Point {
+  x: number;
+  y: number;
+}
+
+/** SVG path plus the chip anchor point for one edge. */
+export interface EdgeGeometry {
+  /** `d` attribute for the SVG `<path>`. */
+  path: string;
+  /** True cubic midpoint (t = 0.5) — where the label chip is anchored. */
+  midpoint: Point;
+  /** Source anchor point (on the source node's facing side). */
+  source: Point;
+  /** Target anchor point (on the target node's facing side). */
+  target: Point;
+}
+
+const MIN_STRENGTH = 40; // minimum control-point pull so short edges still curve
+const PAIR_SHIFT = 8; // endpoint offset when a reverse edge exists
+const PAIR_BOW = 24; // extra control-point bow for reverse pairs
+
+function cubic(p0: Point, c1: Point, c2: Point, p3: Point): EdgeGeometry {
+  return {
+    path: `M ${p0.x} ${p0.y} C ${c1.x} ${c1.y}, ${c2.x} ${c2.y}, ${p3.x} ${p3.y}`,
+    // De Casteljau at t = 0.5: (p0 + 3·c1 + 3·c2 + p3) / 8
+    midpoint: {
+      x: (p0.x + 3 * c1.x + 3 * c2.x + p3.x) / 8,
+      y: (p0.y + 3 * c1.y + 3 * c2.y + p3.y) / 8,
+    },
+    source: p0,
+    target: p3,
+  };
+}
+
+/**
+ * Bezier between two node rects. Anchors on the facing sides (horizontal when
+ * |dx| ≥ |dy|, else vertical). `curvature` (±1) separates an A→B / B→A pair:
+ * pass opposite signs so the two edges bow apart; 0 for a lone edge.
+ */
+export function edgeGeometry(source: Rect, target: Rect, curvature: -1 | 0 | 1 = 0): EdgeGeometry {
+  const sc = { x: source.x + source.width / 2, y: source.y + source.height / 2 };
+  const tc = { x: target.x + target.width / 2, y: target.y + target.height / 2 };
+  const dx = tc.x - sc.x;
+  const dy = tc.y - sc.y;
+  const bow = curvature * PAIR_BOW;
+
+  if (Math.abs(dx) >= Math.abs(dy)) {
+    const sign = dx >= 0 ? 1 : -1;
+    const p0 = { x: sc.x + (sign * source.width) / 2, y: sc.y + curvature * PAIR_SHIFT };
+    const p3 = { x: tc.x - (sign * target.width) / 2, y: tc.y + curvature * PAIR_SHIFT };
+    const strength = Math.max(MIN_STRENGTH, Math.abs(p3.x - p0.x) / 2);
+    return cubic(
+      p0,
+      { x: p0.x + sign * strength, y: p0.y + bow },
+      { x: p3.x - sign * strength, y: p3.y + bow },
+      p3,
+    );
+  }
+  const sign = dy >= 0 ? 1 : -1;
+  const p0 = { x: sc.x + curvature * PAIR_SHIFT, y: sc.y + (sign * source.height) / 2 };
+  const p3 = { x: tc.x + curvature * PAIR_SHIFT, y: tc.y - (sign * target.height) / 2 };
+  const strength = Math.max(MIN_STRENGTH, Math.abs(p3.y - p0.y) / 2);
+  return cubic(
+    p0,
+    { x: p0.x + bow, y: p0.y + sign * strength },
+    { x: p3.x + bow, y: p3.y - sign * strength },
+    p3,
+  );
+}
+
+/** Small loop arcing over a node's top-right corner, for self-referencing edges. */
+export function selfLoopGeometry(rect: Rect): EdgeGeometry {
+  const p0 = { x: rect.x + rect.width * 0.75, y: rect.y };
+  const p3 = { x: rect.x + rect.width, y: rect.y + rect.height * 0.25 };
+  return cubic(p0, { x: p0.x + 10, y: p0.y - 48 }, { x: p3.x + 48, y: p3.y - 10 }, p3);
+}

package/src/components/FlowCanvas/index.ts

@@ -0,0 +1,4 @@
+export { FlowCanvas } from './FlowCanvas';
+export { arrangeNodes } from './layout';
+export type { FlowCanvasProps } from './FlowCanvas';
+export type { FlowCanvasPoint, FlowCanvasNode, FlowCanvasEdge, FlowCanvasSelection } from './types';

package/src/components/FlowCanvas/layout.ts

@@ -0,0 +1,148 @@
+import type { FlowCanvasEdge, FlowCanvasNode, FlowCanvasPoint } from './types';
+
+/** Measured (or estimated) rendered size of a node, in canvas units. */
+export interface NodeSize {
+  width: number;
+  height: number;
+}
+
+/** Fallback node size used before ResizeObserver reports real ones (and in jsdom). */
+export const ESTIMATED_NODE_SIZE: NodeSize = { width: 160, height: 40 };
+
+const RANK_GAP = 96; // horizontal gap between rank columns
+const NODE_GAP = 32; // vertical gap between nodes within a rank
+
+/**
+ * Layered auto-layout: longest-path ranks from the graph's sources flow
+ * left → right; one barycenter pass orders nodes within a rank to reduce edge
+ * crossings; ranks are vertically centered against the tallest rank.
+ * Pure, deterministic, and cycle-safe (back-edges to on-stack nodes are
+ * skipped). Self-loops and edges to unknown nodes are ignored.
+ * Only nodes without an explicit `position` are laid out; a node WITH a
+ * `position` is pinned by the consumer and is ignored here — it neither
+ * occupies layout space nor anchors edges, so it never shifts the others.
+ */
+export function computeLayout(
+  nodes: readonly FlowCanvasNode[],
+  edges: readonly FlowCanvasEdge[],
+  sizes?: ReadonlyMap<string, NodeSize>,
+): Map<string, FlowCanvasPoint> {
+  const result = new Map<string, FlowCanvasPoint>();
+  if (nodes.length === 0) return result;
+
+  // Only nodes WITHOUT an explicit position participate in auto-layout. Pinned
+  // nodes are placed by the consumer and must not perturb the others' ranking
+  // or centering; edges touching a pinned node fall through the unknown-node
+  // guard below (the pinned id is absent from `ids`).
+  const autoNodes = nodes.filter((node) => node.position === undefined);
+  if (autoNodes.length === 0) return result;
+
+  const ids = new Set(autoNodes.map((node) => node.id));
+  const out = new Map<string, string[]>();
+  const incoming = new Map<string, string[]>();
+  const indegree = new Map<string, number>();
+  for (const node of autoNodes) {
+    out.set(node.id, []);
+    incoming.set(node.id, []);
+    indegree.set(node.id, 0);
+  }
+  for (const edge of edges) {
+    if (!ids.has(edge.from) || !ids.has(edge.to) || edge.from === edge.to) continue;
+    out.get(edge.from)!.push(edge.to);
+    incoming.get(edge.to)!.push(edge.from);
+    indegree.set(edge.to, indegree.get(edge.to)! + 1);
+  }
+
+  // Longest-path ranks, cycle-safe.
+  const rank = new Map<string, number>();
+  const onStack = new Set<string>();
+  const visit = (id: string, r: number): void => {
+    if (onStack.has(id)) return; // back-edge in a cycle
+    const prev = rank.get(id);
+    if (prev !== undefined && prev >= r) return;
+    rank.set(id, r);
+    onStack.add(id);
+    for (const next of out.get(id)!) visit(next, r + 1);
+    onStack.delete(id);
+  };
+  const sources = autoNodes.filter((node) => indegree.get(node.id) === 0);
+  for (const source of sources.length > 0 ? sources : [autoNodes[0]]) visit(source.id, 0);
+  // Cycle components unreachable from any source: seed a DFS from each still-
+  // unranked node so their internal edges keep flowing left → right.
+  for (const node of autoNodes) if (!rank.has(node.id)) visit(node.id, 0);
+
+  // Bucket by rank in input order.
+  const ranks: FlowCanvasNode[][] = [];
+  for (const node of autoNodes) {
+    const r = rank.get(node.id)!;
+    (ranks[r] ??= []).push(node);
+  }
+  const orderIndex = new Map<string, number>();
+  for (const bucket of ranks) bucket?.forEach((node, i) => orderIndex.set(node.id, i));
+
+  // One barycenter pass: order each rank by the average order of predecessors.
+  for (let r = 1; r < ranks.length; r++) {
+    const bucket = ranks[r];
+    if (!bucket) continue;
+    const score = (node: FlowCanvasNode): number => {
+      const preds = incoming.get(node.id)!;
+      if (preds.length === 0) return orderIndex.get(node.id)!;
+      return preds.reduce((sum, p) => sum + (orderIndex.get(p) ?? 0), 0) / preds.length;
+    };
+    bucket.sort((a, b) => score(a) - score(b) || orderIndex.get(a.id)! - orderIndex.get(b.id)!);
+    bucket.forEach((node, i) => orderIndex.set(node.id, i));
+  }
+
+  // Position: x per rank column, y stacked and centered per rank.
+  const sizeOf = (id: string): NodeSize => sizes?.get(id) ?? ESTIMATED_NODE_SIZE;
+  const rankHeights = ranks.map((bucket) =>
+    (bucket ?? []).reduce(
+      (sum, node, i) => sum + sizeOf(node.id).height + (i > 0 ? NODE_GAP : 0),
+      0,
+    ),
+  );
+  const maxHeight = Math.max(0, ...rankHeights);
+  let x = 0;
+  for (let r = 0; r < ranks.length; r++) {
+    const bucket = ranks[r] ?? [];
+    let y = (maxHeight - (rankHeights[r] ?? 0)) / 2;
+    let maxWidth = 0;
+    for (const node of bucket) {
+      result.set(node.id, { x, y });
+      y += sizeOf(node.id).height + NODE_GAP;
+      maxWidth = Math.max(maxWidth, sizeOf(node.id).width);
+    }
+    x += (maxWidth || ESTIMATED_NODE_SIZE.width) + RANK_GAP;
+  }
+  return result;
+}
+
+/**
+ * Lay out every node into the layered left→right auto-layout and return the
+ * nodes with `position` filled in — for a consumer-driven "re-arrange / tidy"
+ * action. Unlike {@link computeLayout} (which only places nodes without an
+ * explicit `position`), this re-flows ALL nodes, overwriting any existing
+ * `position`. Pure and deterministic; every other node field is preserved.
+ *
+ * Uses estimated node sizes, so vertical centering can differ by a few pixels
+ * from the live in-canvas layout (a standalone function cannot measure the
+ * rendered DOM). Fine for a tidy action.
+ *
+ * @example
+ * // A "Re-arrange" button in your own UI (e.g. the FlowCanvas `controls` slot):
+ * <Button onClick={() => setNodes((prev) => arrangeNodes(prev, edges))}>Re-arrange</Button>
+ */
+export function arrangeNodes(
+  nodes: readonly FlowCanvasNode[],
+  edges: readonly FlowCanvasEdge[],
+): FlowCanvasNode[] {
+  // Strip positions so the whole graph is treated as auto and re-laid-out.
+  const layout = computeLayout(
+    nodes.map((node) => ({ ...node, position: undefined })),
+    edges,
+  );
+  return nodes.map((node) => {
+    const position = layout.get(node.id);
+    return position ? { ...node, position } : node;
+  });
+}

package/src/components/FlowCanvas/spatialNav.ts

@@ -0,0 +1,76 @@
+import type { Rect } from './edgePath';
+
+/** Arrow-key direction for spatial node navigation. */
+export type NavDirection = 'up' | 'down' | 'left' | 'right';
+
+function center(rect: Rect): { x: number; y: number } {
+  return { x: rect.x + rect.width / 2, y: rect.y + rect.height / 2 };
+}
+
+/**
+ * Nearest node in an arrow direction, judged by rect centers. Candidates must
+ * lie strictly in that direction; off-axis distance is penalized 2× so
+ * aligned neighbors win over closer diagonal ones. Returns null when nothing
+ * lies that way.
+ */
+export function nearestInDirection(
+  currentId: string,
+  rects: ReadonlyMap<string, Rect>,
+  direction: NavDirection,
+): string | null {
+  const current = rects.get(currentId);
+  if (!current) return null;
+  const cc = center(current);
+  let best: string | null = null;
+  let bestScore = Infinity;
+  for (const [id, rect] of rects) {
+    if (id === currentId) continue;
+    const c = center(rect);
+    const dx = c.x - cc.x;
+    const dy = c.y - cc.y;
+    let primary: number;
+    let secondary: number;
+    switch (direction) {
+      case 'right':
+        primary = dx;
+        secondary = Math.abs(dy);
+        break;
+      case 'left':
+        primary = -dx;
+        secondary = Math.abs(dy);
+        break;
+      case 'down':
+        primary = dy;
+        secondary = Math.abs(dx);
+        break;
+      case 'up':
+        primary = -dy;
+        secondary = Math.abs(dx);
+        break;
+    }
+    if (primary <= 0.5) continue;
+    const score = primary + secondary * 2;
+    if (score < bestScore) {
+      bestScore = score;
+      best = id;
+    }
+  }
+  return best;
+}
+
+/** Topmost node, ties broken by leftmost — the initial arrow-key focus target. */
+export function topLeftMost(rects: ReadonlyMap<string, Rect>): string | null {
+  let best: string | null = null;
+  let bestRect: Rect | null = null;
+  for (const [id, rect] of rects) {
+    if (
+      bestRect === null ||
+      rect.y < bestRect.y ||
+      (rect.y === bestRect.y && rect.x < bestRect.x)
+    ) {
+      best = id;
+      bestRect = rect;
+    }
+  }
+  return best;
+}

package/src/components/FlowCanvas/types.ts

@@ -0,0 +1,59 @@
+import type { ReactNode } from 'react';
+
+/** A point in canvas coordinates (px at zoom 1, origin at the stage's top-left). */
+export interface FlowCanvasPoint {
+  /** Horizontal offset in canvas units. */
+  x: number;
+  /** Vertical offset in canvas units. */
+  y: number;
+}
+
+/** One node (vertex) on the canvas. */
+export interface FlowCanvasNode {
+  /** Stable unique id. Referenced by edges and every intent callback. */
+  id: string;
+  /**
+   * Plain-text label rendered inside the node. Also used verbatim for
+   * screen-reader announcements — keep it human-readable.
+   */
+  label: string;
+  /**
+   * Accent color for the node's left bar as a CSS color (typically `#RRGGBB`).
+   * Defaults to the accent token when omitted.
+   */
+  color?: string;
+  /**
+   * Position in canvas coordinates. When omitted the node is auto-laid-out
+   * (layered, left → right) and remains user-draggable for the session.
+   * A node with an explicit `position` is *pinned*: it stays where you place it
+   * and does not participate in — or perturb — the auto-layout of the other
+   * nodes. Use `arrangeNodes(nodes, edges)` to re-flow the whole graph.
+   */
+  position?: FlowCanvasPoint;
+  /**
+   * Slot rendered after the label — badges, icons, counters. Not announced to
+   * screen readers; keep essential state in `label` or the consumer's own UI.
+   * Avoid interactive elements (buttons, inputs): the node itself is a
+   * `role="button"`, so nested controls are invisible to assistive tech
+   * (nested-interactive) even though their keystrokes are let through.
+   */
+  adornment?: ReactNode;
+}
+
+/** One directed edge between two nodes. */
+export interface FlowCanvasEdge {
+  /** Stable unique id. Referenced by selection and intent callbacks. */
+  id: string;
+  /** Source node id. */
+  from: string;
+  /** Target node id. */
+  to: string;
+  /**
+   * Slot rendered as a chip at the edge midpoint (e.g. a "Guard" badge).
+   * Not announced to screen readers.
+   */
+  label?: ReactNode;
+}
+
+/** Current single selection: a node, an edge, or nothing. */
+export type FlowCanvasSelection = { type: 'node' | 'edge'; id: string } | null;

package/src/components/FlowCanvas/useViewport.ts

@@ -0,0 +1,122 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import type { RefObject } from 'react';
+
+/** Stage transform: translation in px plus a uniform scale. */
+export interface Viewport {
+  tx: number;
+  ty: number;
+  z: number;
+}
+
+export const MIN_ZOOM = 0.25;
+export const MAX_ZOOM = 2;
+export const ZOOM_STEP = 1.2;
+export const PAN_STEP = 40;
+
+/** Canvas-space bounding box that {@link useViewport}'s `fitTo` centers on. */
+export interface FitBounds {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+// Wheel deltas arrive in pixels (Chrome, deltaMode 0), lines (Firefox mouse
+// wheels, deltaMode 1, ~3 per notch), or pages (deltaMode 2). Normalize to
+// pixels so pan/zoom speed matches across browsers.
+const WHEEL_LINE_PX = 16;
+const WHEEL_PAGE_PX = 800;
+const wheelDeltaToPixels = (delta: number, deltaMode: number): number => {
+  if (deltaMode === 1) return delta * WHEEL_LINE_PX;
+  if (deltaMode === 2) return delta * WHEEL_PAGE_PX;
+  return delta;
+};
+
+// Continuous ctrl/cmd-wheel zoom: one mouse notch (~100px) multiplies the
+// zoom by ZOOM_STEP, while a trackpad pinch (a rapid stream of small
+// fractional ctrlKey deltas) scales proportionally per event instead of
+// slamming a full step each time.
+const WHEEL_ZOOM_SENSITIVITY = Math.log(ZOOM_STEP) / 100;
+
+/**
+ * Pan/zoom state for the canvas stage. Wheel: plain scroll pans, ctrl/cmd
+ * zooms toward the cursor (native non-passive listener — React's onWheel
+ * can't preventDefault reliably). `fitTo` returns whether it applied — it's
+ * a no-op returning `false` when the root or bounds have no measurable size
+ * (jsdom, display: none), so callers can retry once measurable.
+ */
+export function useViewport(rootRef: RefObject<HTMLDivElement | null>) {
+  const [viewport, setViewport] = useState<Viewport>({ tx: 0, ty: 0, z: 1 });
+
+  const panBy = useCallback((dx: number, dy: number) => {
+    setViewport((v) => ({ ...v, tx: v.tx + dx, ty: v.ty + dy }));
+  }, []);
+
+  const zoomBy = useCallback(
+    (factor: number, clientCenter?: { x: number; y: number }) => {
+      const rect = rootRef.current?.getBoundingClientRect();
+      setViewport((v) => {
+        const z = Math.min(MAX_ZOOM, Math.max(MIN_ZOOM, v.z * factor));
+        if (z === v.z) return v;
+        const cx = clientCenter && rect ? clientCenter.x - rect.left : (rect?.width ?? 0) / 2;
+        const cy = clientCenter && rect ? clientCenter.y - rect.top : (rect?.height ?? 0) / 2;
+        // Keep the canvas point under (cx, cy) stationary while scaling.
+        const px = (cx - v.tx) / v.z;
+        const py = (cy - v.ty) / v.z;
+        return { tx: cx - px * z, ty: cy - py * z, z };
+      });
+    },
+    [rootRef],
+  );
+
+  const fitTo = useCallback(
+    (bounds: FitBounds | null): boolean => {
+      const rect = rootRef.current?.getBoundingClientRect();
+      if (!bounds || !rect || rect.width === 0 || rect.height === 0) return false;
+      if (bounds.width === 0 || bounds.height === 0) return false;
+      const pad = 32;
+      const z = Math.min(
+        1,
+        Math.max(
+          MIN_ZOOM,
+          Math.min((rect.width - pad * 2) / bounds.width, (rect.height - pad * 2) / bounds.height),
+        ),
+      );
+      setViewport({
+        tx: (rect.width - bounds.width * z) / 2 - bounds.x * z,
+        ty: (rect.height - bounds.height * z) / 2 - bounds.y * z,
+        z,
+      });
+      return true;
+    },
+    [rootRef],
+  );
+
+  // Native wheel listener: React attaches wheel passively, so preventDefault
+  // (needed to stop page scroll/browser zoom) requires a manual listener.
+  const zoomByRef = useRef(zoomBy);
+  zoomByRef.current = zoomBy;
+  const panByRef = useRef(panBy);
+  panByRef.current = panBy;
+  useEffect(() => {
+    const el = rootRef.current;
+    if (!el) return;
+    const onWheel = (event: WheelEvent) => {
+      event.preventDefault();
+      const deltaX = wheelDeltaToPixels(event.deltaX, event.deltaMode);
+      const deltaY = wheelDeltaToPixels(event.deltaY, event.deltaMode);
+      if (event.ctrlKey || event.metaKey) {
+        zoomByRef.current(Math.exp(-deltaY * WHEEL_ZOOM_SENSITIVITY), {
+          x: event.clientX,
+          y: event.clientY,
+        });
+      } else {
+        panByRef.current(-deltaX, -deltaY);
+      }
+    };
+    el.addEventListener('wheel', onWheel, { passive: false });
+    return () => el.removeEventListener('wheel', onWheel);
+  }, [rootRef]);
+
+  return { viewport, panBy, zoomBy, fitTo, setViewport };
+}

package/src/components/FormRow/FormRow.module.scss

@@ -0,0 +1,2 @@
+// FormRow delegates all grid layout to <Grid> — no additional styles needed.
+// This file exists to satisfy the repo's four-file rule (structure.test.ts).