@devfellowship/components 3.1.0 → 3.2.0

package/dist/canvas.cjs

@@ -0,0 +1,305 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/canvas/index.ts
+var canvas_exports = {};
+__export(canvas_exports, {
+  DEFAULT_NODE_HEIGHT: () => DEFAULT_NODE_HEIGHT,
+  DEFAULT_NODE_SEPARATION: () => DEFAULT_NODE_SEPARATION,
+  DEFAULT_NODE_WIDTH: () => DEFAULT_NODE_WIDTH,
+  DEFAULT_RANK_SEPARATION: () => DEFAULT_RANK_SEPARATION,
+  FlowCanvas: () => FlowCanvas,
+  layoutGraph: () => layoutGraph
+});
+module.exports = __toCommonJS(canvas_exports);
+
+// src/canvas/FlowCanvas.tsx
+var import_react = require("react");
+var import_react2 = require("@xyflow/react");
+
+// src/lib/utils.ts
+var import_clsx = require("clsx");
+var import_tailwind_merge = require("tailwind-merge");
+function cn(...inputs) {
+  return (0, import_tailwind_merge.twMerge)((0, import_clsx.clsx)(inputs));
+}
+
+// src/canvas/layout.ts
+var import_dagre = __toESM(require("@dagrejs/dagre"), 1);
+var DEFAULT_NODE_WIDTH = 240;
+var DEFAULT_NODE_HEIGHT = 202;
+var DEFAULT_NODE_SEPARATION = 48;
+var DEFAULT_RANK_SEPARATION = 120;
+function layoutGraph(nodes, edges, options = {}) {
+  const {
+    direction = "LR",
+    nodeWidth = DEFAULT_NODE_WIDTH,
+    nodeHeight = DEFAULT_NODE_HEIGHT,
+    nodeSeparation = DEFAULT_NODE_SEPARATION,
+    rankSeparation = DEFAULT_RANK_SEPARATION
+  } = options;
+  const known = new Set(nodes.map((n) => n.id));
+  const usable = edges.filter((e) => known.has(e.source) && known.has(e.target));
+  const g = new import_dagre.default.graphlib.Graph();
+  g.setDefaultEdgeLabel(() => ({}));
+  g.setGraph({ rankdir: direction, nodesep: nodeSeparation, ranksep: rankSeparation, marginx: 24, marginy: 24 });
+  for (const n of nodes) g.setNode(n.id, { width: nodeWidth, height: nodeHeight });
+  for (const e of usable) g.setEdge(e.source, e.target);
+  import_dagre.default.layout(g);
+  const rfNodes = nodes.map((n) => {
+    const laid = g.node(n.id);
+    return {
+      id: n.id,
+      type: "flowCanvasCard",
+      position: {
+        x: laid ? laid.x - nodeWidth / 2 : 0,
+        y: laid ? laid.y - nodeHeight / 2 : 0
+      },
+      data: { node: n },
+      // Explicit width/height, not just post-mount measurement: React Flow's
+      // MiniMap only draws a node rect once the node "has dimensions"
+      // (`measured` OR explicit width/height — see @xyflow/system
+      // nodeHasDimensions). Without this the minimap renders zero rects and
+      // reads as an empty panel.
+      width: nodeWidth,
+      height: nodeHeight
+    };
+  });
+  const pairCounts = /* @__PURE__ */ new Map();
+  for (const e of usable) {
+    const key = pairKey(e);
+    pairCounts.set(key, (pairCounts.get(key) ?? 0) + 1);
+  }
+  const pairSeen = /* @__PURE__ */ new Map();
+  const rfEdges = usable.map((e) => {
+    const key = pairKey(e);
+    const pairIndex = pairSeen.get(key) ?? 0;
+    pairSeen.set(key, pairIndex + 1);
+    return {
+      id: e.id,
+      source: e.source,
+      target: e.target,
+      label: e.label,
+      type: "flowCanvasChip",
+      data: { pairIndex, pairCount: pairCounts.get(key) ?? 1 }
+    };
+  });
+  return { nodes: rfNodes, edges: rfEdges };
+}
+function pairKey(e) {
+  return [e.source, e.target].sort().join("|");
+}
+
+// src/canvas/FlowCanvas.tsx
+var import_jsx_runtime = require("react/jsx-runtime");
+var DEFAULT_CARD_CONTENT_HEIGHT = 130;
+var MINIMAP_NODE_COLOR = "#E07A4A";
+var MINIMAP_MASK_COLOR = "rgba(10,9,8,0.72)";
+var MINIMAP_BG_COLOR = "#141210";
+var FlowCanvasContext = (0, import_react.createContext)(null);
+function useFlowCanvas() {
+  const ctx = (0, import_react.useContext)(FlowCanvasContext);
+  if (!ctx) throw new Error("FlowCanvas internals rendered outside of <FlowCanvas>");
+  return ctx;
+}
+function FlowCanvasCard({ data }) {
+  const { renderCard, renderCaption, clickable, nodeWidth, cardContentHeight, horizontal, testIdPrefix } = useFlowCanvas();
+  const node = data.node;
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
+    "div",
+    {
+      className: cn(
+        "overflow-hidden rounded-lg border border-s-brand-ring bg-card shadow-lg shadow-black/40",
+        clickable && "cursor-pointer"
+      ),
+      style: { width: nodeWidth },
+      "data-testid": `${testIdPrefix}-node`,
+      "data-node-id": node.id,
+      children: [
+        /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+          import_react2.Handle,
+          {
+            type: "target",
+            position: horizontal ? import_react2.Position.Left : import_react2.Position.Top,
+            className: "!h-2 !w-2 !border-none !bg-primary"
+          }
+        ),
+        /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+          "div",
+          {
+            className: "flex w-full items-center justify-center overflow-hidden border-b border-border bg-muted",
+            style: { height: cardContentHeight },
+            "data-testid": `${testIdPrefix}-node-content`,
+            children: renderCard(node)
+          }
+        ),
+        /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: "px-3 py-2 text-xs", "data-testid": `${testIdPrefix}-node-caption`, children: renderCaption ? renderCaption(node) : /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(import_jsx_runtime.Fragment, { children: [
+          /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: "truncate font-semibold text-foreground", title: node.title, children: node.title }),
+          node.subtitle ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: "truncate font-mono text-muted-foreground", title: node.subtitle, children: node.subtitle }) : null
+        ] }) }),
+        /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+          import_react2.Handle,
+          {
+            type: "source",
+            position: horizontal ? import_react2.Position.Right : import_react2.Position.Bottom,
+            className: "!h-2 !w-2 !border-none !bg-primary"
+          }
+        )
+      ]
+    }
+  );
+}
+function FlowCanvasChipEdge({
+  id,
+  sourceX,
+  sourceY,
+  targetX,
+  targetY,
+  sourcePosition,
+  targetPosition,
+  label,
+  data
+}) {
+  const { testIdPrefix } = useFlowCanvas();
+  const [edgePath, labelX, labelY] = (0, import_react2.getSmoothStepPath)({
+    sourceX,
+    sourceY,
+    targetX,
+    targetY,
+    sourcePosition,
+    targetPosition
+  });
+  const pairIndex = data?.pairIndex ?? 0;
+  const pairCount = data?.pairCount ?? 1;
+  const offsetY = pairCount > 1 ? (pairIndex - (pairCount - 1) / 2) * 22 : 0;
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(import_jsx_runtime.Fragment, { children: [
+    /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_react2.BaseEdge, { id, path: edgePath, style: { stroke: "var(--s-brand-ring)", strokeWidth: 1.5 } }),
+    label ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_react2.EdgeLabelRenderer, { children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+      "div",
+      {
+        className: "nodrag nopan pointer-events-none absolute rounded-md border border-s-brand-ring bg-popover px-1.5 py-0.5 text-[10px] font-semibold text-foreground",
+        style: { transform: `translate(-50%, -50%) translate(${labelX}px, ${labelY + offsetY}px)` },
+        "data-testid": `${testIdPrefix}-edge-label`,
+        children: label
+      }
+    ) }) : null
+  ] });
+}
+var nodeTypes = { flowCanvasCard: FlowCanvasCard };
+var edgeTypes = { flowCanvasChip: FlowCanvasChipEdge };
+function FlowCanvas({
+  nodes,
+  edges,
+  renderCard,
+  renderCaption,
+  onNodeClick,
+  direction = "LR",
+  nodeWidth = DEFAULT_NODE_WIDTH,
+  nodeHeight = DEFAULT_NODE_HEIGHT,
+  cardContentHeight = DEFAULT_CARD_CONTENT_HEIGHT,
+  nodeSeparation,
+  rankSeparation,
+  colorMode = "dark",
+  miniMap = true,
+  controls = true,
+  background = true,
+  testIdPrefix = "flow",
+  className,
+  ariaLabel = "Flow canvas"
+}) {
+  const graph = (0, import_react.useMemo)(
+    () => layoutGraph(nodes, edges, { direction, nodeWidth, nodeHeight, nodeSeparation, rankSeparation }),
+    [nodes, edges, direction, nodeWidth, nodeHeight, nodeSeparation, rankSeparation]
+  );
+  const byId = (0, import_react.useMemo)(() => new Map(nodes.map((n) => [n.id, n])), [nodes]);
+  const ctx = (0, import_react.useMemo)(
+    () => ({
+      renderCard,
+      renderCaption,
+      clickable: Boolean(onNodeClick),
+      nodeWidth,
+      cardContentHeight,
+      horizontal: direction === "LR",
+      testIdPrefix
+    }),
+    [renderCard, renderCaption, onNodeClick, nodeWidth, cardContentHeight, direction, testIdPrefix]
+  );
+  const miniMapColors = typeof miniMap === "object" ? miniMap : {};
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(FlowCanvasContext.Provider, { value: ctx, children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+    "div",
+    {
+      className: cn(
+        "h-[70vh] min-h-[520px] w-full overflow-hidden rounded-lg border border-border bg-card",
+        className
+      ),
+      "data-testid": `${testIdPrefix}-canvas`,
+      role: "region",
+      "aria-label": ariaLabel,
+      children: /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
+        import_react2.ReactFlow,
+        {
+          nodes: graph.nodes,
+          edges: graph.edges,
+          nodeTypes,
+          edgeTypes,
+          colorMode,
+          fitView: true,
+          proOptions: { hideAttribution: true },
+          onNodeClick: onNodeClick ? (event, rfNode) => {
+            const node = byId.get(rfNode.id);
+            if (node) onNodeClick(node, event);
+          } : void 0,
+          children: [
+            background ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_react2.Background, {}) : null,
+            controls ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_react2.Controls, { showInteractive: false }) : null,
+            miniMap ? /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+              import_react2.MiniMap,
+              {
+                pannable: true,
+                zoomable: true,
+                nodeColor: miniMapColors.nodeColor ?? MINIMAP_NODE_COLOR,
+                maskColor: miniMapColors.maskColor ?? MINIMAP_MASK_COLOR,
+                bgColor: miniMapColors.bgColor ?? MINIMAP_BG_COLOR
+              }
+            ) : null
+          ]
+        }
+      )
+    }
+  ) });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_NODE_HEIGHT,
+  DEFAULT_NODE_SEPARATION,
+  DEFAULT_NODE_WIDTH,
+  DEFAULT_RANK_SEPARATION,
+  FlowCanvas,
+  layoutGraph
+});

package/dist/canvas.d.cts

@@ -0,0 +1,175 @@
+import * as React from 'react';
+import { ReactNode, MouseEvent } from 'react';
+import { Node, Edge } from '@xyflow/react';
+
+/**
+ * A node the canvas can lay out and draw a card for.
+ *
+ * The canvas reads exactly three things: `id` (identity, edge endpoints, React
+ * keys), `title` and `subtitle` (the caption). Everything else a lens needs
+ * travels in `data`, which the canvas NEVER inspects — it only hands it back to
+ * `renderCard` and `onNodeClick`. That opacity is the whole point: a card can
+ * draw a low-fidelity wireframe, a real screenshot, a coverage heat cell or a
+ * diff badge, and the canvas cannot tell the difference.
+ */
+interface FlowCanvasNode<TData = unknown> {
+    /** Stable identity. Edges point at it and React keys off it. */
+    id: string;
+    /** First caption line. */
+    title: string;
+    /** Second caption line, rendered monospaced. Typically a route or a path. */
+    subtitle?: string;
+    /** Opaque to the canvas. Handed back to `renderCard` and `onNodeClick`. */
+    data?: TData;
+}
+/** A directed edge between two `FlowCanvasNode.id`s. */
+interface FlowCanvasEdge {
+    /** Stable identity. Two edges between the same pair must still differ here. */
+    id: string;
+    source: string;
+    target: string;
+    /** Drawn as a chip on the path midpoint. Omit for an unlabelled edge. */
+    label?: string;
+}
+/** Layout direction. `LR` reads as a journey, `TB` as a hierarchy. */
+type FlowCanvasDirection = "LR" | "TB";
+/**
+ * MiniMap colours. React Flow's MiniMap takes colour STRINGS (it writes them
+ * onto SVG `fill`/`stroke` attributes), so it cannot take a Tailwind class or a
+ * CSS custom property reliably. The defaults are the DFL sand/amber values
+ * written out literally for that reason — not because the tokens were ignored.
+ */
+interface FlowCanvasMiniMapColors {
+    nodeColor?: string;
+    maskColor?: string;
+    bgColor?: string;
+}
+interface FlowCanvasProps<TData = unknown> {
+    /** The graph. Positions are computed here — do not pre-position. */
+    nodes: FlowCanvasNode<TData>[];
+    edges: FlowCanvasEdge[];
+    /**
+     * THE CARD-CONTENT SLOT. Fills the card's content area, above the caption.
+     *
+     * This is the seam that keeps the canvas reusable: the consuming lens decides
+     * what a card shows. Return a sketch, an `<img>`, a chart, a placeholder —
+     * the canvas renders the frame around it and nothing else.
+     */
+    renderCard: (node: FlowCanvasNode<TData>) => ReactNode;
+    /**
+     * Optional override for the caption under the card content. The default
+     * renders `title` over `subtitle`, which is what makes every lens's canvas
+     * read as the same map. Override it when a lens needs a badge or a marker
+     * in the caption row.
+     */
+    renderCaption?: (node: FlowCanvasNode<TData>) => ReactNode;
+    /**
+     * Click handler for a card. The node comes first because that is what a lens
+     * acts on; the DOM event is there for modifier keys.
+     *
+     * When omitted the cards are not interactive and no pointer affordance is
+     * drawn — a canvas whose cards do nothing must not look clickable.
+     */
+    onNodeClick?: (node: FlowCanvasNode<TData>, event: MouseEvent) => void;
+    /** @default "LR" */
+    direction?: FlowCanvasDirection;
+    /** Card width in px. Also the box dagre lays out around. @default 240 */
+    nodeWidth?: number;
+    /** Card height in px, caption included. @default 202 */
+    nodeHeight?: number;
+    /** Height of the card-content area in px. @default 130 */
+    cardContentHeight?: number;
+    /** Horizontal gap between siblings in a rank. @default 48 */
+    nodeSeparation?: number;
+    /** Gap between ranks. @default 120 */
+    rankSeparation?: number;
+    /** @default "dark" */
+    colorMode?: "dark" | "light" | "system";
+    /** `false` hides the MiniMap. An object overrides its colours. @default true */
+    miniMap?: boolean | FlowCanvasMiniMapColors;
+    /** @default true */
+    controls?: boolean;
+    /** @default true */
+    background?: boolean;
+    /**
+     * Prefix for every `data-testid` this component emits:
+     * `<prefix>-canvas`, `<prefix>-node`, `<prefix>-node-content`,
+     * `<prefix>-node-caption`, `<prefix>-edge-label`.
+     *
+     * A page with two canvases needs two prefixes, and a consumer whose suite
+     * already names the canvas can keep its selectors. @default "flow"
+     */
+    testIdPrefix?: string;
+    /** Applied to the canvas frame (the bordered box), not to the viewport. */
+    className?: string;
+    /** Accessible name for the canvas region. @default "Flow canvas" */
+    ariaLabel?: string;
+}
+
+/**
+ * FlowCanvas — a spatial, auto-laid-out graph of cards.
+ *
+ * ONE CANVAS, N LENSES. The canvas owns the map: layout, ranking, edge routing,
+ * the card frame, the caption, the minimap and the controls. The consuming lens
+ * owns what a card SHOWS (`renderCard`) and what a click DOES (`onNodeClick`).
+ * The canvas never inspects `node.data`, so a lens can put a low-fidelity
+ * wireframe in one card and a production screenshot in the next without the
+ * canvas learning about either. Duplicate the lens; never duplicate the canvas.
+ *
+ * ## Peer dependencies
+ * `@xyflow/react` and `@dagrejs/dagre` are OPTIONAL peer dependencies —
+ * install them only if you import this entry point. Consumers of
+ * `@devfellowship/components` who never draw a canvas pay nothing.
+ *
+ * ## Stylesheets the consumer must import
+ * ```css
+ * @import "@xyflow/react/dist/style.css";   /* React Flow's own base styles *​/
+ * @import "@devfellowship/components/canvas.css"; /* DS skin for its chrome *​/
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <FlowCanvas
+ *   nodes={screens.map((s) => ({ id: s.id, title: s.name, subtitle: s.route, data: s }))}
+ *   edges={transitions}
+ *   renderCard={(node) => <WireframePreview screen={node.data} />}
+ *   onNodeClick={(node) => select(node.id)}
+ * />
+ * ```
+ */
+declare function FlowCanvas<TData = unknown>({ nodes, edges, renderCard, renderCaption, onNodeClick, direction, nodeWidth, nodeHeight, cardContentHeight, nodeSeparation, rankSeparation, colorMode, miniMap, controls, background, testIdPrefix, className, ariaLabel, }: FlowCanvasProps<TData>): React.JSX.Element;
+
+declare const DEFAULT_NODE_WIDTH = 240;
+declare const DEFAULT_NODE_HEIGHT = 202;
+declare const DEFAULT_NODE_SEPARATION = 48;
+declare const DEFAULT_RANK_SEPARATION = 120;
+interface LayoutOptions {
+    direction?: FlowCanvasDirection;
+    nodeWidth?: number;
+    nodeHeight?: number;
+    nodeSeparation?: number;
+    rankSeparation?: number;
+}
+/**
+ * Directional auto-layout for the flow canvas.
+ *
+ * Ranks nodes by dagre's layered algorithm, which computes rank AND in-rank
+ * order at once, so it also minimises edge crossings between ranks. The naive
+ * alternative — BFS level to column, insertion order to row — overlaps boxes as
+ * soon as the number of nodes per level varies.
+ *
+ * ⚠️ Do NOT inject a synthetic "super-source" edge to pull entry nodes to the
+ * front. It pushes genuine entry nodes one rank to the RIGHT of disconnected
+ * orphan nodes, which keep dagre's default rank 0 — so an orphan renders as if
+ * it came BEFORE the entry point. Plain ranking from the real edges already
+ * gives every node with no incoming edge rank 0, which is the correct result.
+ *
+ * The function is PURE and side-effect free, which is what makes it testable
+ * without a DOM: same graph in, same coordinates out.
+ */
+declare function layoutGraph<TData>(nodes: FlowCanvasNode<TData>[], edges: FlowCanvasEdge[], options?: LayoutOptions): {
+    nodes: Node[];
+    edges: Edge[];
+};
+
+export { DEFAULT_NODE_HEIGHT, DEFAULT_NODE_SEPARATION, DEFAULT_NODE_WIDTH, DEFAULT_RANK_SEPARATION, FlowCanvas, type FlowCanvasDirection, type FlowCanvasEdge, type FlowCanvasMiniMapColors, type FlowCanvasNode, type FlowCanvasProps, type LayoutOptions, layoutGraph };

package/dist/canvas.d.ts

@@ -0,0 +1,175 @@
+import * as React from 'react';
+import { ReactNode, MouseEvent } from 'react';
+import { Node, Edge } from '@xyflow/react';
+
+/**
+ * A node the canvas can lay out and draw a card for.
+ *
+ * The canvas reads exactly three things: `id` (identity, edge endpoints, React
+ * keys), `title` and `subtitle` (the caption). Everything else a lens needs
+ * travels in `data`, which the canvas NEVER inspects — it only hands it back to
+ * `renderCard` and `onNodeClick`. That opacity is the whole point: a card can
+ * draw a low-fidelity wireframe, a real screenshot, a coverage heat cell or a
+ * diff badge, and the canvas cannot tell the difference.
+ */
+interface FlowCanvasNode<TData = unknown> {
+    /** Stable identity. Edges point at it and React keys off it. */
+    id: string;
+    /** First caption line. */
+    title: string;
+    /** Second caption line, rendered monospaced. Typically a route or a path. */
+    subtitle?: string;
+    /** Opaque to the canvas. Handed back to `renderCard` and `onNodeClick`. */
+    data?: TData;
+}
+/** A directed edge between two `FlowCanvasNode.id`s. */
+interface FlowCanvasEdge {
+    /** Stable identity. Two edges between the same pair must still differ here. */
+    id: string;
+    source: string;
+    target: string;
+    /** Drawn as a chip on the path midpoint. Omit for an unlabelled edge. */
+    label?: string;
+}
+/** Layout direction. `LR` reads as a journey, `TB` as a hierarchy. */
+type FlowCanvasDirection = "LR" | "TB";
+/**
+ * MiniMap colours. React Flow's MiniMap takes colour STRINGS (it writes them
+ * onto SVG `fill`/`stroke` attributes), so it cannot take a Tailwind class or a
+ * CSS custom property reliably. The defaults are the DFL sand/amber values
+ * written out literally for that reason — not because the tokens were ignored.
+ */
+interface FlowCanvasMiniMapColors {
+    nodeColor?: string;
+    maskColor?: string;
+    bgColor?: string;
+}
+interface FlowCanvasProps<TData = unknown> {
+    /** The graph. Positions are computed here — do not pre-position. */
+    nodes: FlowCanvasNode<TData>[];
+    edges: FlowCanvasEdge[];
+    /**
+     * THE CARD-CONTENT SLOT. Fills the card's content area, above the caption.
+     *
+     * This is the seam that keeps the canvas reusable: the consuming lens decides
+     * what a card shows. Return a sketch, an `<img>`, a chart, a placeholder —
+     * the canvas renders the frame around it and nothing else.
+     */
+    renderCard: (node: FlowCanvasNode<TData>) => ReactNode;
+    /**
+     * Optional override for the caption under the card content. The default
+     * renders `title` over `subtitle`, which is what makes every lens's canvas
+     * read as the same map. Override it when a lens needs a badge or a marker
+     * in the caption row.
+     */
+    renderCaption?: (node: FlowCanvasNode<TData>) => ReactNode;
+    /**
+     * Click handler for a card. The node comes first because that is what a lens
+     * acts on; the DOM event is there for modifier keys.
+     *
+     * When omitted the cards are not interactive and no pointer affordance is
+     * drawn — a canvas whose cards do nothing must not look clickable.
+     */
+    onNodeClick?: (node: FlowCanvasNode<TData>, event: MouseEvent) => void;
+    /** @default "LR" */
+    direction?: FlowCanvasDirection;
+    /** Card width in px. Also the box dagre lays out around. @default 240 */
+    nodeWidth?: number;
+    /** Card height in px, caption included. @default 202 */
+    nodeHeight?: number;
+    /** Height of the card-content area in px. @default 130 */
+    cardContentHeight?: number;
+    /** Horizontal gap between siblings in a rank. @default 48 */
+    nodeSeparation?: number;
+    /** Gap between ranks. @default 120 */
+    rankSeparation?: number;
+    /** @default "dark" */
+    colorMode?: "dark" | "light" | "system";
+    /** `false` hides the MiniMap. An object overrides its colours. @default true */
+    miniMap?: boolean | FlowCanvasMiniMapColors;
+    /** @default true */
+    controls?: boolean;
+    /** @default true */
+    background?: boolean;
+    /**
+     * Prefix for every `data-testid` this component emits:
+     * `<prefix>-canvas`, `<prefix>-node`, `<prefix>-node-content`,
+     * `<prefix>-node-caption`, `<prefix>-edge-label`.
+     *
+     * A page with two canvases needs two prefixes, and a consumer whose suite
+     * already names the canvas can keep its selectors. @default "flow"
+     */
+    testIdPrefix?: string;
+    /** Applied to the canvas frame (the bordered box), not to the viewport. */
+    className?: string;
+    /** Accessible name for the canvas region. @default "Flow canvas" */
+    ariaLabel?: string;
+}
+
+/**
+ * FlowCanvas — a spatial, auto-laid-out graph of cards.
+ *
+ * ONE CANVAS, N LENSES. The canvas owns the map: layout, ranking, edge routing,
+ * the card frame, the caption, the minimap and the controls. The consuming lens
+ * owns what a card SHOWS (`renderCard`) and what a click DOES (`onNodeClick`).
+ * The canvas never inspects `node.data`, so a lens can put a low-fidelity
+ * wireframe in one card and a production screenshot in the next without the
+ * canvas learning about either. Duplicate the lens; never duplicate the canvas.
+ *
+ * ## Peer dependencies
+ * `@xyflow/react` and `@dagrejs/dagre` are OPTIONAL peer dependencies —
+ * install them only if you import this entry point. Consumers of
+ * `@devfellowship/components` who never draw a canvas pay nothing.
+ *
+ * ## Stylesheets the consumer must import
+ * ```css
+ * @import "@xyflow/react/dist/style.css";   /* React Flow's own base styles *​/
+ * @import "@devfellowship/components/canvas.css"; /* DS skin for its chrome *​/
+ * ```
+ *
+ * @example
+ * ```tsx
+ * <FlowCanvas
+ *   nodes={screens.map((s) => ({ id: s.id, title: s.name, subtitle: s.route, data: s }))}
+ *   edges={transitions}
+ *   renderCard={(node) => <WireframePreview screen={node.data} />}
+ *   onNodeClick={(node) => select(node.id)}
+ * />
+ * ```
+ */
+declare function FlowCanvas<TData = unknown>({ nodes, edges, renderCard, renderCaption, onNodeClick, direction, nodeWidth, nodeHeight, cardContentHeight, nodeSeparation, rankSeparation, colorMode, miniMap, controls, background, testIdPrefix, className, ariaLabel, }: FlowCanvasProps<TData>): React.JSX.Element;
+
+declare const DEFAULT_NODE_WIDTH = 240;
+declare const DEFAULT_NODE_HEIGHT = 202;
+declare const DEFAULT_NODE_SEPARATION = 48;
+declare const DEFAULT_RANK_SEPARATION = 120;
+interface LayoutOptions {
+    direction?: FlowCanvasDirection;
+    nodeWidth?: number;
+    nodeHeight?: number;
+    nodeSeparation?: number;
+    rankSeparation?: number;
+}
+/**
+ * Directional auto-layout for the flow canvas.
+ *
+ * Ranks nodes by dagre's layered algorithm, which computes rank AND in-rank
+ * order at once, so it also minimises edge crossings between ranks. The naive
+ * alternative — BFS level to column, insertion order to row — overlaps boxes as
+ * soon as the number of nodes per level varies.
+ *
+ * ⚠️ Do NOT inject a synthetic "super-source" edge to pull entry nodes to the
+ * front. It pushes genuine entry nodes one rank to the RIGHT of disconnected
+ * orphan nodes, which keep dagre's default rank 0 — so an orphan renders as if
+ * it came BEFORE the entry point. Plain ranking from the real edges already
+ * gives every node with no incoming edge rank 0, which is the correct result.
+ *
+ * The function is PURE and side-effect free, which is what makes it testable
+ * without a DOM: same graph in, same coordinates out.
+ */
+declare function layoutGraph<TData>(nodes: FlowCanvasNode<TData>[], edges: FlowCanvasEdge[], options?: LayoutOptions): {
+    nodes: Node[];
+    edges: Edge[];
+};
+
+export { DEFAULT_NODE_HEIGHT, DEFAULT_NODE_SEPARATION, DEFAULT_NODE_WIDTH, DEFAULT_RANK_SEPARATION, FlowCanvas, type FlowCanvasDirection, type FlowCanvasEdge, type FlowCanvasMiniMapColors, type FlowCanvasNode, type FlowCanvasProps, type LayoutOptions, layoutGraph };

package/dist/canvas.js

@@ -0,0 +1,273 @@
+// src/canvas/FlowCanvas.tsx
+import { createContext, useContext, useMemo } from "react";
+import {
+  ReactFlow,
+  Background,
+  Controls,
+  MiniMap,
+  Handle,
+  Position,
+  BaseEdge,
+  EdgeLabelRenderer,
+  getSmoothStepPath
+} from "@xyflow/react";
+
+// src/lib/utils.ts
+import { clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+function cn(...inputs) {
+  return twMerge(clsx(inputs));
+}
+
+// src/canvas/layout.ts
+import dagre from "@dagrejs/dagre";
+var DEFAULT_NODE_WIDTH = 240;
+var DEFAULT_NODE_HEIGHT = 202;
+var DEFAULT_NODE_SEPARATION = 48;
+var DEFAULT_RANK_SEPARATION = 120;
+function layoutGraph(nodes, edges, options = {}) {
+  const {
+    direction = "LR",
+    nodeWidth = DEFAULT_NODE_WIDTH,
+    nodeHeight = DEFAULT_NODE_HEIGHT,
+    nodeSeparation = DEFAULT_NODE_SEPARATION,
+    rankSeparation = DEFAULT_RANK_SEPARATION
+  } = options;
+  const known = new Set(nodes.map((n) => n.id));
+  const usable = edges.filter((e) => known.has(e.source) && known.has(e.target));
+  const g = new dagre.graphlib.Graph();
+  g.setDefaultEdgeLabel(() => ({}));
+  g.setGraph({ rankdir: direction, nodesep: nodeSeparation, ranksep: rankSeparation, marginx: 24, marginy: 24 });
+  for (const n of nodes) g.setNode(n.id, { width: nodeWidth, height: nodeHeight });
+  for (const e of usable) g.setEdge(e.source, e.target);
+  dagre.layout(g);
+  const rfNodes = nodes.map((n) => {
+    const laid = g.node(n.id);
+    return {
+      id: n.id,
+      type: "flowCanvasCard",
+      position: {
+        x: laid ? laid.x - nodeWidth / 2 : 0,
+        y: laid ? laid.y - nodeHeight / 2 : 0
+      },
+      data: { node: n },
+      // Explicit width/height, not just post-mount measurement: React Flow's
+      // MiniMap only draws a node rect once the node "has dimensions"
+      // (`measured` OR explicit width/height — see @xyflow/system
+      // nodeHasDimensions). Without this the minimap renders zero rects and
+      // reads as an empty panel.
+      width: nodeWidth,
+      height: nodeHeight
+    };
+  });
+  const pairCounts = /* @__PURE__ */ new Map();
+  for (const e of usable) {
+    const key = pairKey(e);
+    pairCounts.set(key, (pairCounts.get(key) ?? 0) + 1);
+  }
+  const pairSeen = /* @__PURE__ */ new Map();
+  const rfEdges = usable.map((e) => {
+    const key = pairKey(e);
+    const pairIndex = pairSeen.get(key) ?? 0;
+    pairSeen.set(key, pairIndex + 1);
+    return {
+      id: e.id,
+      source: e.source,
+      target: e.target,
+      label: e.label,
+      type: "flowCanvasChip",
+      data: { pairIndex, pairCount: pairCounts.get(key) ?? 1 }
+    };
+  });
+  return { nodes: rfNodes, edges: rfEdges };
+}
+function pairKey(e) {
+  return [e.source, e.target].sort().join("|");
+}
+
+// src/canvas/FlowCanvas.tsx
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+var DEFAULT_CARD_CONTENT_HEIGHT = 130;
+var MINIMAP_NODE_COLOR = "#E07A4A";
+var MINIMAP_MASK_COLOR = "rgba(10,9,8,0.72)";
+var MINIMAP_BG_COLOR = "#141210";
+var FlowCanvasContext = createContext(null);
+function useFlowCanvas() {
+  const ctx = useContext(FlowCanvasContext);
+  if (!ctx) throw new Error("FlowCanvas internals rendered outside of <FlowCanvas>");
+  return ctx;
+}
+function FlowCanvasCard({ data }) {
+  const { renderCard, renderCaption, clickable, nodeWidth, cardContentHeight, horizontal, testIdPrefix } = useFlowCanvas();
+  const node = data.node;
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      className: cn(
+        "overflow-hidden rounded-lg border border-s-brand-ring bg-card shadow-lg shadow-black/40",
+        clickable && "cursor-pointer"
+      ),
+      style: { width: nodeWidth },
+      "data-testid": `${testIdPrefix}-node`,
+      "data-node-id": node.id,
+      children: [
+        /* @__PURE__ */ jsx(
+          Handle,
+          {
+            type: "target",
+            position: horizontal ? Position.Left : Position.Top,
+            className: "!h-2 !w-2 !border-none !bg-primary"
+          }
+        ),
+        /* @__PURE__ */ jsx(
+          "div",
+          {
+            className: "flex w-full items-center justify-center overflow-hidden border-b border-border bg-muted",
+            style: { height: cardContentHeight },
+            "data-testid": `${testIdPrefix}-node-content`,
+            children: renderCard(node)
+          }
+        ),
+        /* @__PURE__ */ jsx("div", { className: "px-3 py-2 text-xs", "data-testid": `${testIdPrefix}-node-caption`, children: renderCaption ? renderCaption(node) : /* @__PURE__ */ jsxs(Fragment, { children: [
+          /* @__PURE__ */ jsx("div", { className: "truncate font-semibold text-foreground", title: node.title, children: node.title }),
+          node.subtitle ? /* @__PURE__ */ jsx("div", { className: "truncate font-mono text-muted-foreground", title: node.subtitle, children: node.subtitle }) : null
+        ] }) }),
+        /* @__PURE__ */ jsx(
+          Handle,
+          {
+            type: "source",
+            position: horizontal ? Position.Right : Position.Bottom,
+            className: "!h-2 !w-2 !border-none !bg-primary"
+          }
+        )
+      ]
+    }
+  );
+}
+function FlowCanvasChipEdge({
+  id,
+  sourceX,
+  sourceY,
+  targetX,
+  targetY,
+  sourcePosition,
+  targetPosition,
+  label,
+  data
+}) {
+  const { testIdPrefix } = useFlowCanvas();
+  const [edgePath, labelX, labelY] = getSmoothStepPath({
+    sourceX,
+    sourceY,
+    targetX,
+    targetY,
+    sourcePosition,
+    targetPosition
+  });
+  const pairIndex = data?.pairIndex ?? 0;
+  const pairCount = data?.pairCount ?? 1;
+  const offsetY = pairCount > 1 ? (pairIndex - (pairCount - 1) / 2) * 22 : 0;
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsx(BaseEdge, { id, path: edgePath, style: { stroke: "var(--s-brand-ring)", strokeWidth: 1.5 } }),
+    label ? /* @__PURE__ */ jsx(EdgeLabelRenderer, { children: /* @__PURE__ */ jsx(
+      "div",
+      {
+        className: "nodrag nopan pointer-events-none absolute rounded-md border border-s-brand-ring bg-popover px-1.5 py-0.5 text-[10px] font-semibold text-foreground",
+        style: { transform: `translate(-50%, -50%) translate(${labelX}px, ${labelY + offsetY}px)` },
+        "data-testid": `${testIdPrefix}-edge-label`,
+        children: label
+      }
+    ) }) : null
+  ] });
+}
+var nodeTypes = { flowCanvasCard: FlowCanvasCard };
+var edgeTypes = { flowCanvasChip: FlowCanvasChipEdge };
+function FlowCanvas({
+  nodes,
+  edges,
+  renderCard,
+  renderCaption,
+  onNodeClick,
+  direction = "LR",
+  nodeWidth = DEFAULT_NODE_WIDTH,
+  nodeHeight = DEFAULT_NODE_HEIGHT,
+  cardContentHeight = DEFAULT_CARD_CONTENT_HEIGHT,
+  nodeSeparation,
+  rankSeparation,
+  colorMode = "dark",
+  miniMap = true,
+  controls = true,
+  background = true,
+  testIdPrefix = "flow",
+  className,
+  ariaLabel = "Flow canvas"
+}) {
+  const graph = useMemo(
+    () => layoutGraph(nodes, edges, { direction, nodeWidth, nodeHeight, nodeSeparation, rankSeparation }),
+    [nodes, edges, direction, nodeWidth, nodeHeight, nodeSeparation, rankSeparation]
+  );
+  const byId = useMemo(() => new Map(nodes.map((n) => [n.id, n])), [nodes]);
+  const ctx = useMemo(
+    () => ({
+      renderCard,
+      renderCaption,
+      clickable: Boolean(onNodeClick),
+      nodeWidth,
+      cardContentHeight,
+      horizontal: direction === "LR",
+      testIdPrefix
+    }),
+    [renderCard, renderCaption, onNodeClick, nodeWidth, cardContentHeight, direction, testIdPrefix]
+  );
+  const miniMapColors = typeof miniMap === "object" ? miniMap : {};
+  return /* @__PURE__ */ jsx(FlowCanvasContext.Provider, { value: ctx, children: /* @__PURE__ */ jsx(
+    "div",
+    {
+      className: cn(
+        "h-[70vh] min-h-[520px] w-full overflow-hidden rounded-lg border border-border bg-card",
+        className
+      ),
+      "data-testid": `${testIdPrefix}-canvas`,
+      role: "region",
+      "aria-label": ariaLabel,
+      children: /* @__PURE__ */ jsxs(
+        ReactFlow,
+        {
+          nodes: graph.nodes,
+          edges: graph.edges,
+          nodeTypes,
+          edgeTypes,
+          colorMode,
+          fitView: true,
+          proOptions: { hideAttribution: true },
+          onNodeClick: onNodeClick ? (event, rfNode) => {
+            const node = byId.get(rfNode.id);
+            if (node) onNodeClick(node, event);
+          } : void 0,
+          children: [
+            background ? /* @__PURE__ */ jsx(Background, {}) : null,
+            controls ? /* @__PURE__ */ jsx(Controls, { showInteractive: false }) : null,
+            miniMap ? /* @__PURE__ */ jsx(
+              MiniMap,
+              {
+                pannable: true,
+                zoomable: true,
+                nodeColor: miniMapColors.nodeColor ?? MINIMAP_NODE_COLOR,
+                maskColor: miniMapColors.maskColor ?? MINIMAP_MASK_COLOR,
+                bgColor: miniMapColors.bgColor ?? MINIMAP_BG_COLOR
+              }
+            ) : null
+          ]
+        }
+      )
+    }
+  ) });
+}
+export {
+  DEFAULT_NODE_HEIGHT,
+  DEFAULT_NODE_SEPARATION,
+  DEFAULT_NODE_WIDTH,
+  DEFAULT_RANK_SEPARATION,
+  FlowCanvas,
+  layoutGraph
+};

package/dist/styles/canvas.css

@@ -0,0 +1,31 @@
+/* DS skin for React Flow's own chrome, used by <FlowCanvas> from
+   @devfellowship/components/canvas.
+
+   React Flow ships its Controls and MiniMap with a light-grey default look that
+   fights the DFL sand palette. These rules re-point that chrome at the DS
+   surface tokens. They live here, beside the component, so a second consumer of
+   FlowCanvas gets the same canvas rather than an unskinned one.
+
+   IMPORT ORDER MATTERS — this sheet overrides React Flow's base styles, so it
+   must come after them:
+
+     @import "@xyflow/react/dist/style.css";
+     @import "@devfellowship/components/canvas.css";
+
+   Deliberately NOT part of theme.css: these selectors are only meaningful on a
+   page that renders a canvas, and the design system must not push React Flow
+   rules into every consumer's stylesheet. */
+
+.react-flow__controls-button {
+  background: var(--s-surface-raised);
+  border-bottom: 1px solid var(--s-border-subtle);
+  color: var(--s-ink-secondary);
+}
+
+.react-flow__controls-button:hover {
+  background: var(--s-surface-elevated);
+}
+
+.react-flow__controls-button svg {
+  fill: currentColor;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devfellowship/components",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "DFL Design System — UI components, hooks, utils and providers",
   "type": "module",
   "sideEffects": [
@@ -32,6 +32,12 @@
       "import": "./dist/testing.js",
       "require": "./dist/testing.cjs"
     },
+    "./canvas": {
+      "types": "./dist/canvas.d.ts",
+      "import": "./dist/canvas.js",
+      "require": "./dist/canvas.cjs"
+    },
+    "./canvas.css": "./dist/styles/canvas.css",
     "./styles": "./dist/styles/theme.css",
     "./shadcn": "./dist/styles/shadcn.css",
     "./tokens": "./dist/styles/tokens.css",
@@ -58,10 +64,13 @@
     "storybook": "storybook dev -p 6006",
     "build-storybook": "storybook build",
     "lint:no-docs": "node scripts/check-no-storybook-docs.mjs",
-    "check:cli-offline": "node scripts/check-cli-bundle-offline.mjs"
+    "check:cli-offline": "node scripts/check-cli-bundle-offline.mjs",
+    "check:canvas-isolated": "node scripts/check-canvas-entry-isolated.mjs"
   },
   "peerDependencies": {
+    "@dagrejs/dagre": ">=3.0.0",
     "@supabase/supabase-js": ">=2.0.0",
+    "@xyflow/react": ">=12.0.0",
     "react": ">=18.0.0",
     "react-dom": ">=18.0.0",
     "tailwindcss": ">=4.0.0"
@@ -72,11 +81,18 @@
     },
     "@supabase/supabase-js": {
       "optional": true
+    },
+    "@xyflow/react": {
+      "optional": true
+    },
+    "@dagrejs/dagre": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@changesets/changelog-github": "^0.7.0",
     "@changesets/cli": "^2.31.0",
+    "@dagrejs/dagre": "^3.1.1",
     "@storybook/addon-a11y": "^9.1.20",
     "@storybook/addon-themes": "^9.1.20",
     "@storybook/react": "^9.1.20",
@@ -89,6 +105,7 @@
     "@types/react": "^18.3.28",
     "@types/react-dom": "^18.3.7",
     "@vitejs/plugin-react": "^4.7.0",
+    "@xyflow/react": "^12.11.3",
     "jsdom": "^26.1.0",
     "react": "^18.3.0",
     "react-dom": "^18.3.0",