@exegia/corpora-ui 0.29.0 → 1.0.0

package/src/components/composed/chat/flowchart/default.tsx

@@ -0,0 +1,230 @@
+"use client"
+
+import { useEffect, useLayoutEffect, useRef, useState } from "react"
+import { Minus, Plus } from "lucide-react"
+import type { FlowchartProps, StepNode } from "./types"
+import { FlowchartContext, useFlowchart } from "./hooks"
+import { AMBER, PURPLE } from "./constant"
+import { Connector } from "./connector"
+import { ChartNode } from "./chart-node"
+import { EdgeToolbar } from "./edge-toolbar"
+import { midpoint } from "./utils"
+import { IconButton } from "@/components/ui/chat"
+import { Button } from "@/components/ui/button"
+import {
+  AlertDialog,
+  AlertDialogClose,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogPopup,
+  AlertDialogTitle,
+} from "@/components/ui/alert-dialog"
+import { cn } from "@/lib/utils"
+
+const NODES: StepNode[] = [
+  {
+    id: "trigger",
+    row: 0,
+    x: 0.5,
+    w: 300,
+    kind: { label: "Trigger", hue: PURPLE },
+    hue: PURPLE,
+    title: "Iliad corpus loaded",
+    caption: "Homer · Greek epic corpus",
+  },
+  {
+    id: "cond",
+    row: 1,
+    x: 0.5,
+    w: 356,
+    kind: { label: "Text node", hue: AMBER },
+    hue: AMBER,
+    title: "μῆνιν ἄειδε, θεά",
+    caption: "Iliad 1.1 · 18 characters",
+  },
+]
+
+/**
+ * Dot-grid canvas of draggable, selectable step cards joined by bezier connectors.
+ *
+ * @sketch "Component / Flowchart"
+ */
+export default function Flowchart({ steps = NODES, edges, readOnly, zoomable, height, onDrag, onAdd, onRemove, onEdgeRemove, onEdgeConnect, onEdgeChange, onRename, onDuplicate, className, children }: FlowchartProps) {
+  const canvasRef = useRef<HTMLDivElement>(null)
+  const nodeRefs = useRef(new Map<string, HTMLElement>())
+  const chart = useFlowchart({ steps, edges, readOnly, zoomable, onDrag, onAdd, onRemove, onEdgeRemove, onEdgeConnect, onEdgeChange, onRename, onDuplicate, canvasRef })
+  const {
+    updateHeights, updateFrame, canvasHeight, worldHeight, isLit, bezierCurve, connectorWidth, scale, view, zoomBy, resetZoom, pendingRemove, commitRemove, cancelRemove,
+    onCanvasPointerDown, onCanvasPointerMove, onCanvasPointerUp, isPanning,
+    editableEdges, selectedEdge, selectEdge, edgeDrag, edgeEnds, onEdgeHandleDown, onEdgeHandleMove, onEdgeHandleUp, ghostCurve, removeEdge,
+  } = chart
+  // The canvas fills its parent; its floor is the content height it loaded with
+  // (or `height`), so zooming out or removing a card never collapses it.
+  const [floor, setFloor] = useState<number | null>(null)
+  if (floor === null && chart.frame.w > 0) setFloor(canvasHeight)
+  const minHeight = height ?? floor ?? canvasHeight
+  const selectedEdgeObj = chart.edges.find((e) => e.id === selectedEdge)
+  const selectedEnds = selectedEdgeObj ? edgeEnds(selectedEdgeObj) : null
+
+  useLayoutEffect(() => {
+    const canvas = canvasRef.current
+    if (!canvas) return
+
+    const measure = () => {
+      updateFrame(canvas.clientWidth, canvas.clientHeight)
+      updateHeights((prev) => {
+        const next = { ...prev }
+        let changed = false
+        nodeRefs.current.forEach((el, id) => {
+          const h = el.offsetHeight
+          if (h && Math.abs(h - (next[id] ?? 0)) > 0.5) {
+            next[id] = h
+            changed = true
+          }
+        })
+        return changed ? next : prev
+      })
+    }
+
+    measure()
+    if (typeof ResizeObserver === "undefined") return
+    const observer = new ResizeObserver(measure)
+    observer.observe(canvas)
+    nodeRefs.current.forEach((el) => observer.observe(el))
+    return () => observer.disconnect()
+  }, [updateHeights, updateFrame, steps])
+
+  // React's onWheel is passive, so preventDefault (no page scroll while zooming) needs a native listener.
+  useEffect(() => {
+    const canvas = canvasRef.current
+    if (!canvas || !zoomable) return
+    const onWheel = (event: WheelEvent) => {
+      if (!event.ctrlKey && !event.metaKey) return
+      event.preventDefault()
+      zoomBy(event.deltaY < 0 ? 1.1 : 1 / 1.1)
+    }
+    canvas.addEventListener("wheel", onWheel, { passive: false })
+    return () => canvas.removeEventListener("wheel", onWheel)
+  }, [zoomable, zoomBy])
+
+  return (
+    <FlowchartContext.Provider value={chart}>
+      <div
+        ref={canvasRef}
+        data-slot="flowchart"
+        data-readonly={readOnly || undefined}
+        className={cn(
+          "rounded-card bg-page shadow-hairline relative h-full w-full touch-none overflow-hidden select-none",
+          "transition-[background-size,background-position] duration-300 ease-[var(--ease-out-strong)] motion-reduce:transition-none",
+          isPanning() ? "cursor-grabbing" : "cursor-grab",
+          className,
+        )}
+        onPointerDown={onCanvasPointerDown}
+        onPointerMove={onCanvasPointerMove}
+        onPointerUp={onCanvasPointerUp}
+        onPointerCancel={onCanvasPointerUp}
+        style={{
+          minHeight,
+          backgroundImage: "radial-gradient(var(--line-strong) 1px, transparent 1.25px)",
+          backgroundSize: `${22 * scale}px ${22 * scale}px`,
+          backgroundPosition: `${view.x}px ${view.y}px`,
+        }}
+      >
+        {children}
+        <div
+          data-slot="flowchart-world"
+          className={cn("absolute top-0 left-0 origin-top-left", !isPanning() && "transition-transform duration-300 ease-[var(--ease-out-strong)] motion-reduce:transition-none")}
+          style={{ width: connectorWidth, height: worldHeight, transform: `translate(${view.x}px, ${view.y}px) scale(${scale})` }}
+        >
+          <svg width={connectorWidth} height={worldHeight} className="pointer-events-none absolute inset-0 overflow-visible">
+            {chart.edges.map((edge) => (
+              <Connector
+                key={edge.id}
+                edge={edge}
+                isLit={isLit(edge)}
+                selected={selectedEdge === edge.id}
+                onPick={editableEdges ? selectEdge : undefined}
+                d={bezierCurve(edge)}
+              />
+            ))}
+          </svg>
+          {selectedEdgeObj && selectedEnds ? (
+            <EdgeToolbar
+              edge={selectedEdgeObj}
+              at={midpoint(selectedEnds.from, selectedEnds.to)}
+              onChange={onEdgeChange}
+              onRemove={onEdgeRemove ? removeEdge : undefined}
+            />
+          ) : null}
+          {steps.map((node, index) => (
+            <ChartNode
+              key={node.id}
+              index={index}
+              node={node}
+              onRef={(el) => {
+                if (el) nodeRefs.current.set(node.id, el)
+                else nodeRefs.current.delete(node.id)
+              }}
+            />
+          ))}
+          {/* Above the cards, so the grab handles are reachable at a card's edge. */}
+          <svg width={connectorWidth} height={worldHeight} className="pointer-events-none absolute inset-0 z-10 overflow-visible">
+            {edgeDrag ? (
+              <path data-edge-ghost fill="none" stroke="var(--accent-default)" strokeWidth={1.5} strokeDasharray="4 3" d={ghostCurve()} />
+            ) : null}
+            {selectedEdgeObj && selectedEnds && onEdgeConnect
+              ? (["source", "target"] as const).map((end) => {
+                  const p = end === "source" ? selectedEnds.from : selectedEnds.to
+                  return (
+                    <g key={end}>
+                      <circle cx={p.x} cy={p.y} r={5} fill="var(--surface)" stroke="var(--accent-default)" strokeWidth={1.5} />
+                      {/* Generous invisible grab target over the 5px dot. */}
+                      <circle
+                        data-edge-handle={end}
+                        cx={p.x}
+                        cy={p.y}
+                        r={12}
+                        fill="transparent"
+                        className="pointer-events-auto cursor-grab touch-none active:cursor-grabbing"
+                        onPointerDown={onEdgeHandleDown(selectedEdgeObj, end)}
+                        onPointerMove={onEdgeHandleMove}
+                        onPointerUp={onEdgeHandleUp}
+                      />
+                    </g>
+                  )
+                })
+              : null}
+          </svg>
+        </div>
+        {zoomable ? (
+          <div data-ui className="absolute right-2 bottom-2 flex items-center gap-0.5 rounded-md bg-surface p-0.5 shadow-btn">
+            <IconButton aria-label="Zoom out" onClick={() => zoomBy(1 / 1.25)}><Minus /></IconButton>
+            <button type="button" onClick={resetZoom} className="min-w-10 text-center text-[11px] tabular-nums text-ink-2">
+              {Math.round(scale * 100)}%
+            </button>
+            <IconButton aria-label="Zoom in" onClick={() => zoomBy(1.25)}><Plus /></IconButton>
+          </div>
+        ) : null}
+      </div>
+      <AlertDialog open={pendingRemove !== null} onOpenChange={(open) => { if (!open) cancelRemove() }}>
+        <AlertDialogPopup>
+          <AlertDialogHeader>
+            <AlertDialogTitle>Delete this node?</AlertDialogTitle>
+            <AlertDialogDescription>
+              {pendingRemove?.orphans.length === 1
+                ? "One child node has no other parent and will be left orphaned."
+                : `${pendingRemove?.orphans.length ?? 0} child nodes have no other parent and will be left orphaned.`}
+            </AlertDialogDescription>
+          </AlertDialogHeader>
+          <AlertDialogFooter>
+            <AlertDialogClose render={<Button variant="ghost" />}>Cancel</AlertDialogClose>
+            <Button variant="destructive" onClick={() => pendingRemove && commitRemove(pendingRemove.id)}>
+              Delete anyway
+            </Button>
+          </AlertDialogFooter>
+        </AlertDialogPopup>
+      </AlertDialog>
+    </FlowchartContext.Provider>
+  )
+}

package/src/components/composed/chat/flowchart/edge-toolbar.tsx

@@ -0,0 +1,73 @@
+import { Unlink } from "lucide-react"
+import { IconButton } from "@/components/ui/chat"
+import { cn } from "@/lib/utils"
+import type { Edge } from "./types"
+import type { Point } from "./utils"
+
+const WIDTHS = [1.25, 2, 3]
+const COLORS = ["var(--line-strong)", "var(--tag-purple-text)", "var(--tag-amber-text)", "var(--tag-blue-text)", "var(--tag-green-text)"]
+
+/** Floats at a selected connector's midpoint: stroke widths, colours, disconnect. */
+export function EdgeToolbar({
+  edge,
+  at,
+  onChange,
+  onRemove,
+}: {
+  edge: Edge
+  at: Point
+  onChange?: (id: string, patch: Pick<Edge, "strokeWidth" | "color">) => void
+  onRemove?: (id: string) => void
+}) {
+  const width = edge.strokeWidth ?? 1.25
+  const color = edge.color ?? COLORS[0]
+  return (
+    <div
+      data-ui
+      data-slot="edge-toolbar"
+      role="toolbar"
+      aria-label="Connector"
+      onClick={(event) => event.stopPropagation()}
+      className="absolute z-20 flex -translate-x-1/2 -translate-y-1/2 items-center gap-1 rounded-md bg-surface p-1 shadow-btn"
+      style={{ left: at.x, top: at.y }}
+    >
+      {onChange
+        ? WIDTHS.map((w) => (
+            <button
+              key={w}
+              type="button"
+              aria-label={`Stroke ${w}`}
+              aria-pressed={width === w}
+              onClick={() => onChange(edge.id, { strokeWidth: w })}
+              className={cn("flex size-6 items-center justify-center rounded-sm hover:bg-hover-2", width === w && "bg-hover-2")}
+            >
+              <span className="w-3.5 rounded-full bg-ink" style={{ height: w }} />
+            </button>
+          ))
+        : null}
+      {onChange ? <span aria-hidden className="mx-0.5 h-4 w-px bg-line" /> : null}
+      {onChange
+        ? COLORS.map((c) => (
+            <button
+              key={c}
+              type="button"
+              aria-label={`Colour ${c}`}
+              aria-pressed={color === c}
+              onClick={() => onChange(edge.id, { color: c })}
+              className={cn("flex size-6 items-center justify-center rounded-sm hover:bg-hover-2", color === c && "bg-hover-2")}
+            >
+              <span className="size-3 rounded-full" style={{ background: c }} />
+            </button>
+          ))
+        : null}
+      {onRemove ? (
+        <>
+          {onChange ? <span aria-hidden className="mx-0.5 h-4 w-px bg-line" /> : null}
+          <IconButton aria-label="Disconnect" onClick={() => onRemove(edge.id)}>
+            <Unlink />
+          </IconButton>
+        </>
+      ) : null}
+    </div>
+  )
+}

package/src/components/composed/chat/flowchart/hooks.tsx

@@ -0,0 +1,345 @@
+import React, { createContext, useCallback, useContext, useMemo, useRef, useState } from "react";
+import type { Edge, EdgeEnd, FlowchartProps, StepNode } from "./types";
+import { anchors, bezier, canvasH, curve, cw, edgePoints, place, rowH, rows, rowYs, type Heights, type Layout, type Offsets, type Point } from "./utils";
+import { EST_H, SNAP_RADIUS } from "./constant";
+import { toastManager } from "@/components/ui/toast";
+
+export const ZOOM_MIN = 0.25;
+export const ZOOM_MAX = 2;
+
+type Options = Pick<FlowchartProps, "edges" | "readOnly" | "zoomable" | "onDrag" | "onAdd" | "onRemove" | "onEdgeRemove" | "onEdgeConnect" | "onEdgeChange" | "onRename" | "onDuplicate"> & {
+  steps: StepNode[];
+  canvasRef: React.RefObject<HTMLDivElement | null>;
+};
+
+/** A connector end being dragged towards a new card; `snap` is the card whose anchor is in range. */
+export type EdgeDrag = { id: string; end: EdgeEnd; point: Point; snap?: string };
+
+/** Pill text: explicit name, else the kind label, else "Node n" (conditions always count). */
+export const nodeLabel = (node: StepNode, index: number) =>
+  node.name ?? (node.condition || !node.kind ? `Node ${index + 1}` : node.kind.label);
+
+/** Default connectors: a chain through the steps in order. */
+export const chainEdges = (steps: StepNode[]): Edge[] =>
+  steps.slice(1).map((n, i) => ({ id: `${steps[i].id}->${n.id}`, source: steps[i].id, target: n.id }));
+
+export const useFlowchart = ({ steps, edges: edgesProp, readOnly = false, zoomable = false, onDrag, onAdd, onRemove, onEdgeRemove, onEdgeConnect, onEdgeChange, onRename, onDuplicate, canvasRef }: Options) => {
+  /** Visible canvas box; the world behind it is twice this size. */
+  const [frame, setFrame] = useState({ w: 0, h: 0 });
+  const [heights, setHeights] = useState<Heights>(EST_H);
+  const [selected, setSelected] = useState<string | null>(null);
+  const [offsets, setOffsets] = useState<Offsets>({});
+  /** Zoom and pan of the world inside the frame (pan in frame px). */
+  const [view, setView] = useState({ scale: 1, x: 0, y: 0 });
+  const scale = view.scale;
+  const pan = useRef<{ startX: number; startY: number; baseX: number; baseY: number; moved: boolean } | null>(null);
+  const [pendingRemove, setPendingRemove] = useState<{ id: string; orphans: string[] } | null>(null);
+  const [selectedEdge, setSelectedEdge] = useState<string | null>(null);
+  const [edgeDrag, setEdgeDrag] = useState<EdgeDrag | null>(null);
+  /** Card highlighted while the user browses "Connect to…" in the context menu. */
+  const [previewNode, setPreviewNode] = useState<string | null>(null);
+  const drag = useRef<{
+    id: string;
+    startX: number;
+    startY: number;
+    baseDx: number;
+    baseDy: number;
+    moved: boolean;
+  } | null>(null);
+
+  const edges = useMemo(() => edgesProp ?? chainEdges(steps), [edgesProp, steps]);
+  const rowHeight = useMemo(() => rowH(steps, heights), [heights, steps]);
+  // The world is twice the frame so there is always hidden canvas to drag into view.
+  const width = frame.w * 2;
+  const layout = useMemo<Layout>(() => {
+    const _rows = rows(steps);
+    return { width, offsets, rows: _rows, rowY: rowYs(rowHeight), heights };
+  }, [steps, width, offsets, rowHeight, heights]);
+  const canvasHeight = useMemo(() => canvasH(layout.rowY, rowHeight), [layout.rowY, rowHeight]);
+  const connectorWidth = cw(width);
+  const worldHeight = Math.max(canvasHeight, frame.h * 2);
+
+  /** Keep the world covering the frame: clamp when it is larger, centre it when smaller. */
+  const clampPan = useCallback(
+    (x: number, y: number, s: number, f = frame) => {
+      const fit = (offset: number, visible: number, content: number) =>
+        content <= visible ? (visible - content) / 2 : Math.min(0, Math.max(visible - content, offset));
+      return { x: fit(x, f.w, connectorWidth * s), y: fit(y, f.h, worldHeight * s) };
+    },
+    [frame, connectorWidth, worldHeight],
+  );
+
+  const updateHeights = useCallback((callback: (prev: Heights) => Heights) => setHeights(callback), []);
+  const updateFrame = useCallback((w: number, h: number) => {
+    setFrame((prev) => (prev.w === w && prev.h === h ? prev : { w, h }));
+    // First measurement centres the world horizontally, top-aligned; later
+    // width changes scale the pan so the view stays put as the world resizes.
+    const prevW = frame.w;
+    setView((v) => {
+      if (w <= 0 || w === prevW) return v;
+      return prevW === 0 ? { ...v, x: (w - w * 2 * v.scale) / 2, y: 0 } : { ...v, x: (v.x * w) / prevW };
+    });
+  }, [frame.w]);
+  const updateSelected = (id: string | null) => {
+    setSelected((prev) => (prev === id ? prev : id));
+    if (id !== null) setSelectedEdge(null);
+  };
+  const editableEdges = !readOnly && Boolean(onEdgeRemove || onEdgeConnect || onEdgeChange);
+  const selectEdge = (id: string | null) => {
+    if (!editableEdges) return;
+    setSelectedEdge(id);
+    if (id !== null) setSelected(null);
+  };
+  /** Zoom about the frame centre so what is in the middle stays there. */
+  const zoomTo = useCallback(
+    (next: number) =>
+      setView((v) => {
+        const s = Math.min(ZOOM_MAX, Math.max(ZOOM_MIN, +next.toFixed(3)));
+        const cx = frame.w / 2;
+        const cy = frame.h / 2;
+        const k = s / v.scale;
+        return { scale: s, ...clampPan(cx - (cx - v.x) * k, cy - (cy - v.y) * k, s) };
+      }),
+    [frame, clampPan],
+  );
+  const zoomBy = useCallback((factor: number) => zoomTo(scale * factor), [zoomTo, scale]);
+  const resetZoom = useCallback(() => zoomTo(1), [zoomTo]);
+
+  /** Dragging empty canvas pans the world; a still click clears the selection. */
+  const onCanvasPointerDown = (event: React.PointerEvent<HTMLDivElement>) => {
+    if (event.button !== 0) return;
+    const target = event.target as Element;
+    if (target.closest("[data-node], [data-ui], [data-edge-handle], [data-edge]")) return;
+    pan.current = { startX: event.clientX, startY: event.clientY, baseX: view.x, baseY: view.y, moved: false };
+    event.currentTarget.setPointerCapture(event.pointerId);
+  };
+  const onCanvasPointerMove = (event: React.PointerEvent<HTMLDivElement>) => {
+    const p = pan.current;
+    if (!p) return;
+    const dx = event.clientX - p.startX;
+    const dy = event.clientY - p.startY;
+    if (!p.moved && Math.hypot(dx, dy) < 3) return;
+    p.moved = true;
+    setView((v) => ({ ...v, ...clampPan(p.baseX + dx, p.baseY + dy, v.scale) }));
+  };
+  const onCanvasPointerUp = () => {
+    const p = pan.current;
+    pan.current = null;
+    if (p && !p.moved) {
+      setSelected(null);
+      setSelectedEdge(null);
+    }
+  };
+  const isPanning = () => pan.current?.moved === true;
+
+  const onPointerDown = (node: StepNode) => (event: React.PointerEvent<HTMLDivElement>) => {
+    // Left button only: a right-press belongs to the context menu.
+    if (readOnly || event.button !== 0) return;
+    if ((event.target as Element).closest("[data-ui]")) return;
+    const off = offsets[node.id];
+    drag.current = {
+      id: node.id,
+      startX: event.clientX,
+      startY: event.clientY,
+      baseDx: off?.dx ?? 0,
+      baseDy: off?.dy ?? 0,
+      moved: false,
+    };
+    (event.currentTarget as HTMLElement).setPointerCapture(event.pointerId);
+  };
+
+  const onPointerMove = (node: StepNode) => (event: React.PointerEvent<HTMLDivElement>) => {
+    const d = drag.current;
+    if (!d || d.id !== node.id) return;
+    const dx = d.baseDx + (event.clientX - d.startX) / scale;
+    const dy = d.baseDy + (event.clientY - d.startY) / scale;
+    if (!d.moved && Math.hypot(dx - d.baseDx, dy - d.baseDy) < 3) return;
+    d.moved = true;
+
+    // keep the card inside the canvas
+    const { w } = place(node, layout);
+    const h = heights[node.id] ?? 90;
+    const baseCx = node.x * connectorWidth;
+    const baseTop = layout.rowY[layout.rows.indexOf(node.row)] ?? 0;
+    const cx = Math.min(Math.max(baseCx + dx, w / 2 + 8), connectorWidth - w / 2 - 8);
+    const top = Math.min(Math.max(baseTop + dy, 8), worldHeight - h - 8);
+    setOffsets((current) => ({ ...current, [node.id]: { dx: cx - baseCx, dy: top - baseTop } }));
+  };
+
+  const onPointerUp = (node: StepNode) => () => {
+    const d = drag.current;
+    if (d?.id !== node.id) return;
+    if (d.moved) {
+      onDrag?.(node.id, offsets[node.id] ?? { dx: 0, dy: 0 });
+      // a real drag shouldn't also toggle selection
+      setTimeout(() => (drag.current = null), 0);
+    } else drag.current = null;
+  };
+
+  const wasDragged = () => drag.current?.moved === true;
+  const isLit = (edge: Edge) => selected === edge.source || selected === edge.target || selectedEdge === edge.id;
+
+  /** Client → unscaled canvas coordinates. */
+  const toCanvas = (clientX: number, clientY: number): Point => {
+    const rect = canvasRef.current?.getBoundingClientRect();
+    return { x: (clientX - (rect?.left ?? 0) - view.x) / scale, y: (clientY - (rect?.top ?? 0) - view.y) / scale };
+  };
+  const edgeEnds = (edge: Edge) => edgePoints({ from: edge.source, to: edge.target }, steps, layout);
+
+  const onEdgeHandleDown = (edge: Edge, end: EdgeEnd) => (event: React.PointerEvent<SVGElement>) => {
+    if (!onEdgeConnect) return;
+    event.stopPropagation();
+    (event.currentTarget as Element).setPointerCapture(event.pointerId);
+    setEdgeDrag({ id: edge.id, end, point: toCanvas(event.clientX, event.clientY) });
+  };
+  /** Nearest anchor of another card within SNAP_RADIUS: top anchors for a target end, bottom for a source end. */
+  const snapCandidate = (edge: Edge, end: EdgeEnd, point: Point) => {
+    const other = end === "source" ? edge.target : edge.source;
+    let best: { id: string; d: number } | null = null;
+    for (const node of steps) {
+      if (node.id === other) continue;
+      const a = anchors(node, layout);
+      const p = end === "source" ? a.bottom : a.top;
+      const d = Math.hypot(p.x - point.x, p.y - point.y);
+      if (d <= SNAP_RADIUS && (!best || d < best.d)) best = { id: node.id, d };
+    }
+    return best?.id;
+  };
+  const onEdgeHandleMove = (event: React.PointerEvent<SVGElement>) => {
+    if (!edgeDrag) return;
+    const point = toCanvas(event.clientX, event.clientY);
+    const edge = edges.find((e) => e.id === edgeDrag.id);
+    const snap = edge ? snapCandidate(edge, edgeDrag.end, point) : undefined;
+    setEdgeDrag({ ...edgeDrag, point, snap });
+  };
+  const onEdgeHandleUp = (event: React.PointerEvent<SVGElement>) => {
+    if (!edgeDrag) return;
+    const edge = edges.find((e) => e.id === edgeDrag.id);
+    const card = document.elementFromPoint(event.clientX, event.clientY)?.closest<HTMLElement>("[data-node]");
+    const target = edgeDrag.snap ?? card?.dataset.node;
+    setEdgeDrag(null);
+    if (!edge || !target) return;
+    const other = edgeDrag.end === "source" ? edge.target : edge.source;
+    if (target === other || target === edge[edgeDrag.end]) return;
+    onEdgeConnect?.({ ...edge, [edgeDrag.end]: target });
+  };
+  /** Path of the connector being re-routed, following the pointer. */
+  const ghostCurve = () => {
+    if (!edgeDrag) return "";
+    const edge = edges.find((e) => e.id === edgeDrag.id);
+    const pts = edge && edgeEnds(edge);
+    if (!pts) return "";
+    const snapNode = edgeDrag.snap ? steps.find((n) => n.id === edgeDrag.snap) : undefined;
+    const point = snapNode ? anchors(snapNode, layout)[edgeDrag.end === "source" ? "bottom" : "top"] : edgeDrag.point;
+    return edgeDrag.end === "source" ? curve(point, pts.to) : curve(pts.from, point);
+  };
+  /** "Connect to…": a new connector from `source` to `target`, unless one exists. */
+  const connectTo = (source: string, target: string) => {
+    if (source === target || edges.some((e) => e.source === source && e.target === target)) return;
+    onEdgeConnect?.({ id: `${source}->${target}`, source, target });
+  };
+  const renameNode = (id: string, name: string) => {
+    onRename?.(id, name);
+    toastManager.add({ title: "Node renamed", description: name, type: "success" });
+  };
+  const duplicateNode = (id: string) => onDuplicate?.(id);
+  const snapTarget = edgeDrag?.snap ?? null;
+  const removeEdge = (id: string) => {
+    setSelectedEdge(null);
+    onEdgeRemove?.(id);
+  };
+  const bezierCurve = (edge: Edge) => bezier({ from: edge.source, to: edge.target }, steps, layout);
+  const handlePlace = (node: StepNode) => place(node, layout);
+
+  /** Children that would lose their only parent if `id` were removed. */
+  const orphansOf = (id: string) =>
+    edges
+      .filter((e) => e.source === id)
+      .map((e) => e.target)
+      .filter((child) => !edges.some((e) => e.target === child && e.source !== id));
+
+  const commitRemove = (id: string) => {
+    if (selected === id) setSelected(null);
+    setPendingRemove(null);
+    onRemove?.(id);
+  };
+
+  /** Removes outright, or parks the id in `pendingRemove` for Root's AlertDialog when children would be orphaned. */
+  const removeNode = (id: string) => {
+    const orphans = orphansOf(id);
+    if (orphans.length) setPendingRemove({ id, orphans });
+    else commitRemove(id);
+  };
+  const cancelRemove = () => setPendingRemove(null);
+
+  return {
+    steps,
+    edges,
+    readOnly,
+    zoomable,
+    scale,
+    view,
+    zoomBy,
+    resetZoom,
+    onCanvasPointerDown,
+    onCanvasPointerMove,
+    onCanvasPointerUp,
+    isPanning,
+    frame,
+    worldHeight,
+    onAdd,
+    removeNode,
+    commitRemove,
+    cancelRemove,
+    pendingRemove,
+    orphansOf,
+    updateHeights,
+    offsets,
+    width,
+    selected,
+    drag,
+    updateSelected,
+    updateFrame,
+    onPointerDown,
+    onPointerMove,
+    onPointerUp,
+    wasDragged,
+    isLit,
+    editableEdges,
+    selectedEdge,
+    selectEdge,
+    edgeDrag,
+    edgeEnds,
+    onEdgeHandleDown,
+    onEdgeHandleMove,
+    onEdgeHandleUp,
+    ghostCurve,
+    removeEdge,
+    onEdgeChange,
+    snapTarget,
+    previewNode,
+    setPreviewNode,
+    connectTo,
+    renameNode,
+    duplicateNode,
+    canRename: Boolean(onRename),
+    canDuplicate: Boolean(onDuplicate),
+    canConnect: Boolean(onEdgeConnect),
+    rowHeight,
+    canvasHeight,
+    connectorWidth,
+    bezierCurve,
+    handlePlace,
+  };
+};
+
+export type FlowchartController = ReturnType<typeof useFlowchart>;
+
+/** Root owns the one `useFlowchart` instance; nodes read it from here. */
+export const FlowchartContext = createContext<FlowchartController | null>(null);
+
+export const useFlowchartContext = () => {
+  const ctx = useContext(FlowchartContext);
+  if (!ctx) throw new Error("Flowchart.ChartNode must render inside Flowchart.Root");
+  return ctx;
+};

package/src/components/composed/chat/flowchart/index.ts

@@ -0,0 +1,14 @@
+import Root from "./default"
+import { Connector } from "./connector"
+import { ChartNode } from "./chart-node"
+
+export type * from "./types"
+export * from "./hooks"
+
+export const Flowchart = {
+  Root,
+  Connector,
+  ChartNode,
+}
+
+export default Root