@elabs-ai/components-flow 4.1.0 → 5.0.0

package/dist/inspector-panel/inspector-panel.js

@@ -0,0 +1,8 @@
+"use client";
+import {
+  InspectorPanel
+} from "../chunk-NAQWNX2A.js";
+export {
+  InspectorPanel
+};
+//# sourceMappingURL=inspector-panel.js.map

package/dist/inspector-panel/inspector-panel.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/legend/index.js

@@ -0,0 +1,10 @@
+"use client";
+import "../chunk-UPV2MT4O.js";
+import {
+  Legend
+} from "../chunk-NVJVWGUS.js";
+import "../chunk-3BTU2VWZ.js";
+export {
+  Legend
+};
+//# sourceMappingURL=index.js.map

package/dist/legend/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/legend/legend.js

@@ -0,0 +1,9 @@
+"use client";
+import {
+  Legend
+} from "../chunk-NVJVWGUS.js";
+import "../chunk-3BTU2VWZ.js";
+export {
+  Legend
+};
+//# sourceMappingURL=legend.js.map

package/dist/legend/legend.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/use-flow-groups/group-operations.js

@@ -0,0 +1,20 @@
+"use client";
+import {
+  FLOW_GROUP_NODE_TYPE,
+  collapseGroup,
+  expandGroup,
+  groupNodes,
+  isFlowGroupProxyEdge,
+  toggleGroupCollapsed,
+  ungroup
+} from "../chunk-TGWPM2CG.js";
+export {
+  FLOW_GROUP_NODE_TYPE,
+  collapseGroup,
+  expandGroup,
+  groupNodes,
+  isFlowGroupProxyEdge,
+  toggleGroupCollapsed,
+  ungroup
+};
+//# sourceMappingURL=group-operations.js.map

package/dist/use-flow-groups/group-operations.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/use-flow-groups/index.js

@@ -0,0 +1,25 @@
+"use client";
+import "../chunk-ELOADZSX.js";
+import {
+  useFlowGroups
+} from "../chunk-LQOZCOK3.js";
+import {
+  FLOW_GROUP_NODE_TYPE,
+  collapseGroup,
+  expandGroup,
+  groupNodes,
+  isFlowGroupProxyEdge,
+  toggleGroupCollapsed,
+  ungroup
+} from "../chunk-TGWPM2CG.js";
+export {
+  FLOW_GROUP_NODE_TYPE,
+  collapseGroup,
+  expandGroup,
+  groupNodes,
+  isFlowGroupProxyEdge,
+  toggleGroupCollapsed,
+  ungroup,
+  useFlowGroups
+};
+//# sourceMappingURL=index.js.map

package/dist/use-flow-groups/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/use-flow-groups/use-flow-groups.js

@@ -0,0 +1,9 @@
+"use client";
+import {
+  useFlowGroups
+} from "../chunk-LQOZCOK3.js";
+import "../chunk-TGWPM2CG.js";
+export {
+  useFlowGroups
+};
+//# sourceMappingURL=use-flow-groups.js.map

package/dist/use-flow-groups/use-flow-groups.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/zoom-controls/index.js

@@ -0,0 +1,9 @@
+"use client";
+import "../chunk-3LK6OOXE.js";
+import {
+  ZoomControls
+} from "../chunk-ATO4LXJF.js";
+export {
+  ZoomControls
+};
+//# sourceMappingURL=index.js.map

package/dist/zoom-controls/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/zoom-controls/zoom-controls.js

@@ -0,0 +1,8 @@
+"use client";
+import {
+  ZoomControls
+} from "../chunk-ATO4LXJF.js";
+export {
+  ZoomControls
+};
+//# sourceMappingURL=zoom-controls.js.map

package/dist/zoom-controls/zoom-controls.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elabs-ai/components-flow",
-  "version": "4.1.0",
+  "version": "5.0.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -30,10 +30,16 @@
   },
   "peerDependencies": {
     "@xyflow/react": "^12.11.1",
+    "elkjs": "^0.12.0",
     "react": "^18.2.0 || ^19.0.0",
     "react-dom": "^18.2.0 || ^19.0.0",
-    "@elabs-ai/components-tokens": "4.1.0",
-    "@elabs-ai/components-ui": "4.1.0"
+    "@elabs-ai/components-tokens": "5.0.0",
+    "@elabs-ai/components-ui": "5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "elkjs": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.6.3",
@@ -44,6 +50,7 @@
     "@types/react-dom": "^19.0.2",
     "@vitejs/plugin-react": "^4.3.4",
     "@xyflow/react": "^12.11.1",
+    "elkjs": "^0.12.0",
     "eslint": "^9.17.0",
     "jsdom": "^25.0.1",
     "react": "^19.0.0",
@@ -51,11 +58,11 @@
     "tsup": "^8.3.5",
     "typescript": "^5.7.3",
     "vitest": "^3.0.2",
-    "@elabs-ai/components-tokens": "4.1.0",
-    "@elabs-ai/components-icons": "4.1.0",
     "@elabs-ai/components-eslint-config": "0.1.0",
-    "@elabs-ai/components-ui": "4.1.0",
-    "@elabs-ai/components-typescript-config": "0.1.0"
+    "@elabs-ai/components-icons": "5.0.0",
+    "@elabs-ai/components-tokens": "5.0.0",
+    "@elabs-ai/components-typescript-config": "0.1.0",
+    "@elabs-ai/components-ui": "5.0.0"
   },
   "scripts": {
     "build": "tsup",

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

@@ -0,0 +1,49 @@
+// GENERATED by scripts/gen-contract-tests.mjs — do not edit; re-run the generator instead.
+/**
+ * Contract probe for InspectorPanel (`packages/flow/src/inspector-panel/inspector-panel.tsx`), derived from its
+ * `Default` story (packages/flow/src/inspector-panel/inspector-panel.stories.tsx). See scripts/gen-contract-tests.mjs.
+ */
+import { describe, it, expect, afterEach } from "vitest";
+import { render, cleanup } from "@testing-library/react";
+import { createRef } from "react";
+import * as stories from "../inspector-panel/inspector-panel.stories";
+import knownFailuresJson from "../../../../scripts/check/contract-known-failures.json";
+
+afterEach(cleanup);
+
+// Every component here has its own prop/ref/element shape; a generated probe
+// stays generic on purpose (loosely typed, not untyped — see
+// scripts/gen-contract-tests.mjs) rather than re-deriving each one.
+const KNOWN_FAILURES: Record<string, string> = knownFailuresJson;
+const meta = stories.default as { component?: unknown; args?: Record<string, unknown> };
+const Default = (stories as { Default?: { args?: Record<string, unknown> } }).Default;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- probe target; see comment above
+const Component = meta.component as any;
+const args = { ...(meta.args ?? {}), ...(Default?.args ?? {}) };
+const isForwardRefComponent = Component?.["$$typeof"] === Symbol.for("react.forward_ref");
+
+/** Wrap a known, tracked failure in `it.fails` so fixing it forces the key's removal. */
+function contractIt(assertion: string, name: string, fn: () => void) {
+  const key = `flow-inspectorpanel--default|jsdom|jsdom|${assertion}`;
+  const reason = KNOWN_FAILURES[key];
+  if (reason) return it.fails(`${name} (known failure: ${reason})`, fn);
+  return it(name, fn);
+}
+
+describe("InspectorPanel contract", () => {
+  it.skipIf(!isForwardRefComponent)("forwards a ref to a DOM element", () => {
+    const ref = createRef<Element>();
+    render(<Component {...args} ref={ref} />);
+    expect(ref.current).toBeInstanceOf(Element);
+  });
+
+  contractIt("className", "merges a caller className onto the root", () => {
+    const { container } = render(<Component {...args} className="contract-probe" />);
+    expect(container.querySelector(".contract-probe")).not.toBeNull();
+  });
+
+  contractIt("data-slot", 'exposes data-slot="inspector-panel" on its root', () => {
+    const { container } = render(<Component {...args} />);
+    expect(container.querySelector('[data-slot="inspector-panel"]')).not.toBeNull();
+  });
+});

package/src/__contract__/legend.contract.test.tsx

@@ -0,0 +1,49 @@
+// GENERATED by scripts/gen-contract-tests.mjs — do not edit; re-run the generator instead.
+/**
+ * Contract probe for Legend (`packages/flow/src/legend/legend.tsx`), derived from its
+ * `Default` story (packages/flow/src/legend/legend.stories.tsx). See scripts/gen-contract-tests.mjs.
+ */
+import { describe, it, expect, afterEach } from "vitest";
+import { render, cleanup } from "@testing-library/react";
+import { createRef } from "react";
+import * as stories from "../legend/legend.stories";
+import knownFailuresJson from "../../../../scripts/check/contract-known-failures.json";
+
+afterEach(cleanup);
+
+// Every component here has its own prop/ref/element shape; a generated probe
+// stays generic on purpose (loosely typed, not untyped — see
+// scripts/gen-contract-tests.mjs) rather than re-deriving each one.
+const KNOWN_FAILURES: Record<string, string> = knownFailuresJson;
+const meta = stories.default as { component?: unknown; args?: Record<string, unknown> };
+const Default = (stories as { Default?: { args?: Record<string, unknown> } }).Default;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- probe target; see comment above
+const Component = meta.component as any;
+const args = { ...(meta.args ?? {}), ...(Default?.args ?? {}) };
+const isForwardRefComponent = Component?.["$$typeof"] === Symbol.for("react.forward_ref");
+
+/** Wrap a known, tracked failure in `it.fails` so fixing it forces the key's removal. */
+function contractIt(assertion: string, name: string, fn: () => void) {
+  const key = `flow-legend--default|jsdom|jsdom|${assertion}`;
+  const reason = KNOWN_FAILURES[key];
+  if (reason) return it.fails(`${name} (known failure: ${reason})`, fn);
+  return it(name, fn);
+}
+
+describe("Legend contract", () => {
+  it.skipIf(!isForwardRefComponent)("forwards a ref to a DOM element", () => {
+    const ref = createRef<Element>();
+    render(<Component {...args} ref={ref} />);
+    expect(ref.current).toBeInstanceOf(Element);
+  });
+
+  contractIt("className", "merges a caller className onto the root", () => {
+    const { container } = render(<Component {...args} className="contract-probe" />);
+    expect(container.querySelector(".contract-probe")).not.toBeNull();
+  });
+
+  contractIt("data-slot", 'exposes data-slot="legend" on its root', () => {
+    const { container } = render(<Component {...args} />);
+    expect(container.querySelector('[data-slot="legend"]')).not.toBeNull();
+  });
+});

package/src/canvas-shell/canvas-shell.stories.tsx

@@ -51,6 +51,7 @@ const edges: Edge[] = [
 const meta = {
   title: "Flow/CanvasShell",
   component: CanvasShell,
+  tags: ["autodocs"],
   parameters: { layout: "fullscreen" },
 } satisfies Meta<typeof CanvasShell>;
 export default meta;

package/src/canvas-shell/canvas-shell.tsx

@@ -15,6 +15,7 @@ import {
 import { cn } from "@elabs-ai/components-ui/lib/cn";
 import { HelperLines } from "../helper-lines/helper-lines";
 import { useHelperLines } from "../helper-lines/use-helper-lines";
+import { clampedFitOffset } from "./clamped-fit-offset";
 import { useMeasuredNodes } from "./use-measured-nodes";
 
 export interface CanvasShellProps<
@@ -52,6 +53,15 @@ export interface CanvasShellProps<
   fitViewKey?: string | number;
   /** Options for the {@link fitViewKey} re-fit. Ignored without one. */
   fitViewKeyOptions?: FitViewOptions;
+  /**
+   * Which nodes a CLAMPED {@link fitViewKey} re-fit keeps in view — typically where the
+   * diagram begins. A fit that cannot shrink far enough (a `minZoom` floor) is pinned to the
+   * content's top-left corner by default, which is where a top-down layout starts; a
+   * left-to-right layout starts at the left edge but at mid-height, so pinning to the top
+   * opens on an empty corner. With anchors, each overflowing axis centres the anchor nodes
+   * instead, without ever scrolling past the content's own edge. Unset: today's corner pin.
+   */
+  fitViewAnchorNodeIds?: readonly string[];
   /** Overlays rendered inside the flow (ZoomControls, Legend, Panels). */
   children?: ReactNode;
   className?: string;
@@ -120,6 +130,7 @@ function CanvasShellBase<NodeType extends Node, EdgeType extends Edge>({
   onNodesChange,
   fitViewKey,
   fitViewKeyOptions,
+  fitViewAnchorNodeIds,
   ...props
 }: CanvasShellInnerProps<NodeType, EdgeType>) {
   const measured = useMeasuredNodes<NodeType>(nodes, onNodesChange);
@@ -135,7 +146,11 @@ function CanvasShellBase<NodeType extends Node, EdgeType extends Edge>({
       >
         {background ? <Background gap={20} size={1} color="var(--canvas-grid)" /> : null}
         {fitViewKey === undefined ? null : (
-          <FitViewOnKey fitViewKey={fitViewKey} options={fitViewKeyOptions} />
+          <FitViewOnKey
+            fitViewKey={fitViewKey}
+            options={fitViewKeyOptions}
+            anchorNodeIds={fitViewAnchorNodeIds}
+          />
         )}
         {children}
       </ReactFlow>
@@ -152,9 +167,11 @@ function CanvasShellBase<NodeType extends Node, EdgeType extends Edge>({
 function FitViewOnKey({
   fitViewKey,
   options,
+  anchorNodeIds,
 }: {
   fitViewKey: string | number;
   options?: FitViewOptions;
+  anchorNodeIds?: readonly string[];
 }) {
   const { fitView, getNodes, getNodesBounds, setViewport } = useReactFlow();
   const store = useStoreApi();
@@ -162,7 +179,14 @@ function FitViewOnKey({
   useEffect(() => {
     if (!nodesInitialized) return;
     void fitView(options).then(() =>
-      anchorToStartWhenClamped(store, setViewport, getNodesBounds, getNodes(), options),
+      anchorToStartWhenClamped(
+        store,
+        setViewport,
+        getNodesBounds,
+        getNodes(),
+        options,
+        anchorNodeIds,
+      ),
     );
     // `options` is deliberately absent: an inline object literal would re-fit on every
     // render, which is a viewport jump under the reader's cursor. The key is the trigger.
@@ -196,6 +220,7 @@ function anchorToStartWhenClamped(
   getNodesBounds: ReturnType<typeof useReactFlow>["getNodesBounds"],
   nodes: Node[],
   options: FitViewOptions | undefined,
+  anchorNodeIds?: readonly string[],
 ): void {
   if (nodes.length === 0) return;
   const { width, height, transform, panZoom } = store.getState();
@@ -213,9 +238,31 @@ function anchorToStartWhenClamped(
   const overflowsY = bounds.height * zoom > height - padY * 2 + 1;
   if (!overflowsX && !overflowsY) return;
 
+  // With anchors: centre them on an overflowing axis, but never scroll past the content's
+  // own start or end. On the axis the diagram runs along, the anchors sit at the content's
+  // start, so this lands exactly where the corner pin does; on the cross axis it keeps the
+  // first rank in view instead of opening on whatever happens to be top-most.
+  const anchors = anchorNodeIds?.length
+    ? nodes.filter((node) => anchorNodeIds.includes(node.id))
+    : [];
+  const anchor = anchors.length > 0 ? getNodesBounds(anchors) : null;
+  const along = (size: number, pad: number, start: number, extent: number, centre: number) =>
+    clampedFitOffset({
+      size,
+      pad,
+      start,
+      extent,
+      zoom,
+      anchorCentre: anchor === null ? undefined : centre,
+    });
+
   const next = {
-    x: overflowsX ? padX - bounds.x * zoom : x,
-    y: overflowsY ? padY - bounds.y * zoom : y,
+    x: overflowsX
+      ? along(width, padX, bounds.x, bounds.width, (anchor?.x ?? 0) + (anchor?.width ?? 0) / 2)
+      : x,
+    y: overflowsY
+      ? along(height, padY, bounds.y, bounds.height, (anchor?.y ?? 0) + (anchor?.height ?? 0) / 2)
+      : y,
     zoom,
   };
   // `setViewport` is a no-op before the pan/zoom instance exists (the very first commit).

package/src/canvas-shell/clamped-fit-offset.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from "vitest";
+import { clampedFitOffset } from "./clamped-fit-offset";
+
+describe("clampedFitOffset", () => {
+  const axis = { size: 1000, pad: 100, start: 0, extent: 4000, zoom: 0.75 };
+
+  it("pins the content's start at the padding when there is no anchor", () => {
+    expect(clampedFitOffset(axis)).toBe(100);
+    expect(clampedFitOffset({ ...axis, start: 200 })).toBe(100 - 200 * 0.75);
+  });
+
+  it("an anchor at the content's start lands exactly where the corner pin does", () => {
+    expect(clampedFitOffset({ ...axis, anchorCentre: 90 })).toBe(100);
+  });
+
+  it("centres an anchor that sits in the middle of the overflowing axis", () => {
+    // Anchor centre at 2000 → 1500 px at zoom 0.75 → offset 500 - 1500.
+    expect(clampedFitOffset({ ...axis, anchorCentre: 2000 })).toBe(-1000);
+  });
+
+  it("never scrolls past the content's end", () => {
+    // End pinned: 1000 - 100 - 4000 * 0.75 = -2100; an anchor at the very end asks for less.
+    expect(clampedFitOffset({ ...axis, anchorCentre: 3990 })).toBe(-2100);
+  });
+});

package/src/canvas-shell/clamped-fit-offset.ts

@@ -0,0 +1,30 @@
+/**
+ * The viewport offset for ONE overflowing axis of a clamped fit (pure; exported for its test).
+ * Without an anchor the content's start is pinned at the padding. With one, the anchor is
+ * centred — but never so far that the pane shows empty space before the content's start or
+ * after its end.
+ */
+export function clampedFitOffset({
+  size,
+  pad,
+  start,
+  extent,
+  zoom,
+  anchorCentre,
+}: {
+  /** Pane size on this axis, px. */
+  size: number;
+  /** Padding the fit keeps on this axis, px. */
+  pad: number;
+  /** Content start and extent on this axis, in flow coordinates. */
+  start: number;
+  extent: number;
+  zoom: number;
+  /** Centre of the anchor nodes on this axis, in flow coordinates. */
+  anchorCentre?: number;
+}): number {
+  const startPinned = pad - start * zoom;
+  if (anchorCentre === undefined) return startPinned;
+  const endPinned = size - pad - (start + extent) * zoom;
+  return Math.min(startPinned, Math.max(endPinned, size / 2 - anchorCentre * zoom));
+}