entangle-ui 0.9.0 → 0.11.0

package/dist/esm/components/editor/NodeGraph/NodeGraphPort.js

@@ -0,0 +1,191 @@
+"use client";
+import { jsx } from 'react/jsx-runtime';
+import React, { useRef, useCallback, useMemo, useSyncExternalStore, useLayoutEffect } from 'react';
+import { useViewportStore } from '../../primitives/viewport/ViewportContext.js';
+import '../../../utils/devWarn.js';
+import { useResizeObserver } from '../../../hooks/useResizeObserver/useResizeObserver.js';
+import '../../../hooks/useBreakpoint/useBreakpoint.js';
+import './../../../assets/src/theme/lightTheme.css.ts.vanilla-Ct6f9Iym.css';
+import '@vanilla-extract/css';
+import './../../../assets/src/theme/darkTheme.css.ts.vanilla-BHZ3ecRn.css';
+import './../../../assets/src/theme/globalScrollbars.css.ts.vanilla-BAJwnUEJ.css';
+import '../../../hooks/useNavigationHistory/useNavigationHistory.js';
+import { cx } from '../../../utils/cx.js';
+import { portSlotRecipe } from './NodeGraph.css.js';
+import { useNodeGraphStore } from './NodeGraphContext.js';
+import { useNodeGraphNodeContext } from './NodeGraphNodeContext.js';
+import { useNodeGraphNodeSection } from './NodeGraphNodeSectionContext.js';
+import { NodeGraphPortVisual } from './NodeGraphPortVisual.js';
+import { useStoreSlice } from './useStoreSlice.js';
+
+const EMPTY_VISUAL = {
+    isSource: false,
+    isCandidate: false,
+    isInvalid: false,
+    isHovered: false,
+};
+function visualEqual(a, b) {
+    return (a.isSource === b.isSource &&
+        a.isCandidate === b.isCandidate &&
+        a.isInvalid === b.isInvalid &&
+        a.isHovered === b.isHovered);
+}
+/**
+ * `<NodeGraph.Port>` — compound slot that declares a connection endpoint
+ * for the current node. Render it anywhere inside `renderNode`; the
+ * library measures its DOM position, registers it as the anchor for any
+ * edge that references this port id, and wires pointer events so the
+ * user can drag from it to start a connection.
+ *
+ * The slot renders a single `<span>` with `display: inline-flex` — drop
+ * it inline next to a label and it will sit beside the text. The wrapper
+ * carries the default UE-style circle / exec-triangle visual; pass
+ * `children` to replace the chrome entirely (state for theming is
+ * exposed via `data-port-*` attributes).
+ *
+ * @example
+ * ```tsx
+ * <NodeGraph.Port id="in" side="left" dataType="exec" />
+ * ```
+ *
+ * Wrapped in `React.memo` — ports re-mount on every consumer `renderNode`
+ * call by default, so memoization only helps consumers who memoize their
+ * own node body. When they do, ports skip re-renders on unrelated store
+ * updates entirely.
+ */
+function NodeGraphPortImpl({ id, side, dataType, shape = 'circle', color, filled, children, label, className, style, }) {
+    const { nodeId, onPortPointerDown } = useNodeGraphNodeContext();
+    const { collapsed } = useNodeGraphNodeSection();
+    const store = useNodeGraphStore();
+    const viewportStore = useViewportStore();
+    const elementRef = useRef(null);
+    // ── Connected state (slice subscription — only flips re-render) ──
+    // The store recomputes the connected-ports index when edges change, so
+    // each port re-renders only when its own connected-ness actually flips.
+    const connected = useStoreSlice(store.subscribeConnectedPorts, store.getConnectedPorts, () => store.isPortConnected(nodeId, id));
+    // ── Per-port visual state (slice subscription — no re-render storm) ──
+    const visual = useStoreSlice(store.subscribeInteraction, store.getInteraction, interaction => {
+        if (interaction.kind !== 'connect')
+            return EMPTY_VISUAL;
+        const isSource = interaction.source.node === nodeId && interaction.source.port === id;
+        const isCandidate = interaction.candidate !== null &&
+            interaction.candidate.node === nodeId &&
+            interaction.candidate.port === id;
+        if (!isSource && !isCandidate)
+            return EMPTY_VISUAL;
+        return {
+            isSource,
+            isCandidate,
+            isInvalid: isCandidate && interaction.invalid,
+            isHovered: false,
+        };
+    }, visualEqual);
+    const hoverState = useStoreSlice(store.subscribeHover, store.getHover, hover => ({
+        ...EMPTY_VISUAL,
+        isHovered: hover.hoveredPort !== null &&
+            hover.hoveredPort.node === nodeId &&
+            hover.hoveredPort.port === id,
+    }), visualEqual);
+    const isHovered = hoverState.isHovered;
+    const isSource = visual.isSource;
+    const isCandidate = visual.isCandidate;
+    const isInvalid = visual.isInvalid;
+    // ── DOM measurement → store ──
+    //
+    // Run synchronously before paint so first frame's edges anchor at the
+    // correct point. `useResizeObserver` picks up later size changes on the
+    // port itself, and the per-node layout-version subscription below picks
+    // up layout shifts inside the node body that move the port without
+    // resizing it (e.g. a sibling row expands).
+    //
+    // `closest('[data-node-id]:not([data-port-id])')` skips the slot itself
+    // — the slot wrapper carries `data-node-id` too (so connection-drop
+    // hit-tests can walk up from any descendant), so a plain `[data-node-id]`
+    // would match the port and report position (~6, ~6) for every port.
+    const measure = useCallback(() => {
+        // Inside a collapsed section the port is hidden; drop its registered
+        // position so its edges hide too (re-registers on expand). The component
+        // stays mounted, so no remount churn.
+        if (collapsed) {
+            store.removePortPosition(nodeId, id);
+            return;
+        }
+        const el = elementRef.current;
+        if (!el)
+            return;
+        const wrapper = el.closest('[data-node-id]:not([data-port-id])');
+        if (!wrapper)
+            return;
+        const portRect = el.getBoundingClientRect();
+        const nodeRect = wrapper.getBoundingClientRect();
+        // Convert from screen pixels to node-local world units. `ViewportWorld`
+        // applies `transform: scale(zoom)` to all node wrappers, so the rects
+        // we just read are scaled by `zoom`. Dividing brings us back to the
+        // un-scaled layout pixels, which are 1:1 with world units inside a node.
+        const zoom = viewportStore.getTransform().zoom || 1;
+        const x = (portRect.left + portRect.width / 2 - nodeRect.left) / zoom;
+        const y = (portRect.top + portRect.height / 2 - nodeRect.top) / zoom;
+        store.setPortPosition(nodeId, id, { x, y, side, dataType });
+    }, [store, viewportStore, nodeId, id, side, dataType, collapsed]);
+    // Re-measure triggers (the per-port `ResizeObserver` only fires when
+    // the port's own size changes, which misses layout shifts inside the
+    // node body that move the port without resizing it — e.g. a sibling
+    // row expanding). Subscribing to the per-node measured size makes this
+    // component re-render on every wrapper resize, and the layout effect
+    // below re-runs the measurement.
+    const getMeasuredForNode = useMemo(() => () => store.getMeasuredSize(nodeId), [store, nodeId]);
+    const measuredSize = useSyncExternalStore(store.subscribeMeasuredSizes, getMeasuredForNode);
+    useLayoutEffect(() => {
+        measure();
+    }, [measure, measuredSize]);
+    useResizeObserver(elementRef, () => {
+        measure();
+    });
+    // Unregister on unmount / id change.
+    useLayoutEffect(() => {
+        return () => {
+            store.removePortPosition(nodeId, id);
+        };
+    }, [store, nodeId, id]);
+    // ── Hover wiring ──
+    //
+    // Update the store's `hoveredPort` slice on enter/leave so node bodies,
+    // edges, and other ports can react. Library guards against duplicate
+    // notifications when the value doesn't actually change.
+    const onPointerEnter = useCallback(() => {
+        const current = store.getHover();
+        if (current.hoveredPort?.node === nodeId && current.hoveredPort.port === id)
+            return;
+        store.setHover({ ...current, hoveredPort: { node: nodeId, port: id } });
+    }, [store, nodeId, id]);
+    const onPointerLeave = useCallback(() => {
+        const current = store.getHover();
+        if (current.hoveredPort?.node !== nodeId || current.hoveredPort.port !== id)
+            return;
+        store.setHover({ ...current, hoveredPort: null });
+    }, [store, nodeId, id]);
+    const handlePointerDown = useCallback((event) => {
+        onPortPointerDown(event, id);
+    }, [onPortPointerDown, id]);
+    const hasCustomVisual = children !== undefined && children !== null;
+    const isFilled = filled ?? connected;
+    // Route the consumer's `color` into the slot via a CSS custom property so
+    // the built-in visual (which paints with `currentColor`) picks it up,
+    // while the source / candidate / invalid recipe variants can still
+    // override `color` to keep connection-drag feedback visible.
+    const portStyle = color !== undefined
+        ? { ['--etui-ng-port-color']: color, ...style }
+        : style;
+    return (jsx("span", { ref: elementRef, role: "button", tabIndex: -1, "aria-label": label ?? `${side} port ${id}`, "data-node-id": nodeId, "data-port-id": id, "data-port-side": side, "data-port-data-type": dataType, "data-port-source": isSource || undefined, "data-port-candidate": isCandidate || undefined, "data-port-invalid": isInvalid || undefined, "data-port-hovered": isHovered || undefined, "data-port-connected": connected || undefined, className: cx(portSlotRecipe({
+            side,
+            custom: hasCustomVisual,
+            source: isSource,
+            candidate: isCandidate,
+            invalid: isInvalid,
+        }), className), style: portStyle, onPointerDown: handlePointerDown, onPointerEnter: onPointerEnter, onPointerLeave: onPointerLeave, children: hasCustomVisual ? (children) : (jsx(NodeGraphPortVisual, { shape: shape, filled: isFilled })) }));
+}
+const NodeGraphPort = React.memo(NodeGraphPortImpl);
+NodeGraphPort.displayName = 'NodeGraphPort';
+
+export { NodeGraphPort };
+//# sourceMappingURL=NodeGraphPort.js.map

package/dist/esm/components/editor/NodeGraph/NodeGraphPort.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"NodeGraphPort.js","sources":["src/components/editor/NodeGraph/NodeGraphPort.tsx"],"sourcesContent":["'use client';\n\nimport React, {\n  useCallback,\n  useLayoutEffect,\n  useMemo,\n  useRef,\n  useSyncExternalStore,\n} from 'react';\n\nimport { useViewportStore } from '@/components/primitives/viewport/ViewportContext';\nimport { useResizeObserver } from '@/hooks';\nimport { cx } from '@/utils/cx';\n\nimport { portSlotRecipe } from './NodeGraph.css';\nimport { useNodeGraphStore } from './NodeGraphContext';\nimport { useNodeGraphNodeContext } from './NodeGraphNodeContext';\nimport { useNodeGraphNodeSection } from './NodeGraphNodeSectionContext';\nimport { NodeGraphPortVisual } from './NodeGraphPortVisual';\nimport { useStoreSlice } from './useStoreSlice';\n\nimport type { NodeGraphPortSlotProps } from './NodeGraph.types';\n\ninterface PortVisualState {\n  isSource: boolean;\n  isCandidate: boolean;\n  isInvalid: boolean;\n  isHovered: boolean;\n}\n\nconst EMPTY_VISUAL: PortVisualState = {\n  isSource: false,\n  isCandidate: false,\n  isInvalid: false,\n  isHovered: false,\n};\n\nfunction visualEqual(a: PortVisualState, b: PortVisualState): boolean {\n  return (\n    a.isSource === b.isSource &&\n    a.isCandidate === b.isCandidate &&\n    a.isInvalid === b.isInvalid &&\n    a.isHovered === b.isHovered\n  );\n}\n\n/**\n * `<NodeGraph.Port>` — compound slot that declares a connection endpoint\n * for the current node. Render it anywhere inside `renderNode`; the\n * library measures its DOM position, registers it as the anchor for any\n * edge that references this port id, and wires pointer events so the\n * user can drag from it to start a connection.\n *\n * The slot renders a single `<span>` with `display: inline-flex` — drop\n * it inline next to a label and it will sit beside the text. The wrapper\n * carries the default UE-style circle / exec-triangle visual; pass\n * `children` to replace the chrome entirely (state for theming is\n * exposed via `data-port-*` attributes).\n *\n * @example\n * ```tsx\n * <NodeGraph.Port id=\"in\" side=\"left\" dataType=\"exec\" />\n * ```\n *\n * Wrapped in `React.memo` — ports re-mount on every consumer `renderNode`\n * call by default, so memoization only helps consumers who memoize their\n * own node body. When they do, ports skip re-renders on unrelated store\n * updates entirely.\n */\nfunction NodeGraphPortImpl({\n  id,\n  side,\n  dataType,\n  shape = 'circle',\n  color,\n  filled,\n  children,\n  label,\n  className,\n  style,\n}: NodeGraphPortSlotProps): React.ReactElement {\n  const { nodeId, onPortPointerDown } = useNodeGraphNodeContext();\n  const { collapsed } = useNodeGraphNodeSection();\n  const store = useNodeGraphStore();\n  const viewportStore = useViewportStore();\n  const elementRef = useRef<HTMLSpanElement>(null);\n\n  // ── Connected state (slice subscription — only flips re-render) ──\n  // The store recomputes the connected-ports index when edges change, so\n  // each port re-renders only when its own connected-ness actually flips.\n  const connected = useStoreSlice(\n    store.subscribeConnectedPorts,\n    store.getConnectedPorts,\n    () => store.isPortConnected(nodeId, id)\n  );\n\n  // ── Per-port visual state (slice subscription — no re-render storm) ──\n  const visual = useStoreSlice(\n    store.subscribeInteraction,\n    store.getInteraction,\n    interaction => {\n      if (interaction.kind !== 'connect') return EMPTY_VISUAL;\n      const isSource =\n        interaction.source.node === nodeId && interaction.source.port === id;\n      const isCandidate =\n        interaction.candidate !== null &&\n        interaction.candidate.node === nodeId &&\n        interaction.candidate.port === id;\n      if (!isSource && !isCandidate) return EMPTY_VISUAL;\n      return {\n        isSource,\n        isCandidate,\n        isInvalid: isCandidate && interaction.invalid,\n        isHovered: false,\n      };\n    },\n    visualEqual\n  );\n\n  const hoverState = useStoreSlice(\n    store.subscribeHover,\n    store.getHover,\n    hover => ({\n      ...EMPTY_VISUAL,\n      isHovered:\n        hover.hoveredPort !== null &&\n        hover.hoveredPort.node === nodeId &&\n        hover.hoveredPort.port === id,\n    }),\n    visualEqual\n  );\n\n  const isHovered = hoverState.isHovered;\n  const isSource = visual.isSource;\n  const isCandidate = visual.isCandidate;\n  const isInvalid = visual.isInvalid;\n\n  // ── DOM measurement → store ──\n  //\n  // Run synchronously before paint so first frame's edges anchor at the\n  // correct point. `useResizeObserver` picks up later size changes on the\n  // port itself, and the per-node layout-version subscription below picks\n  // up layout shifts inside the node body that move the port without\n  // resizing it (e.g. a sibling row expands).\n  //\n  // `closest('[data-node-id]:not([data-port-id])')` skips the slot itself\n  // — the slot wrapper carries `data-node-id` too (so connection-drop\n  // hit-tests can walk up from any descendant), so a plain `[data-node-id]`\n  // would match the port and report position (~6, ~6) for every port.\n  const measure = useCallback((): void => {\n    // Inside a collapsed section the port is hidden; drop its registered\n    // position so its edges hide too (re-registers on expand). The component\n    // stays mounted, so no remount churn.\n    if (collapsed) {\n      store.removePortPosition(nodeId, id);\n      return;\n    }\n    const el = elementRef.current;\n    if (!el) return;\n    const wrapper = el.closest('[data-node-id]:not([data-port-id])');\n    if (!wrapper) return;\n    const portRect = el.getBoundingClientRect();\n    const nodeRect = wrapper.getBoundingClientRect();\n    // Convert from screen pixels to node-local world units. `ViewportWorld`\n    // applies `transform: scale(zoom)` to all node wrappers, so the rects\n    // we just read are scaled by `zoom`. Dividing brings us back to the\n    // un-scaled layout pixels, which are 1:1 with world units inside a node.\n    const zoom = viewportStore.getTransform().zoom || 1;\n    const x = (portRect.left + portRect.width / 2 - nodeRect.left) / zoom;\n    const y = (portRect.top + portRect.height / 2 - nodeRect.top) / zoom;\n    store.setPortPosition(nodeId, id, { x, y, side, dataType });\n  }, [store, viewportStore, nodeId, id, side, dataType, collapsed]);\n\n  // Re-measure triggers (the per-port `ResizeObserver` only fires when\n  // the port's own size changes, which misses layout shifts inside the\n  // node body that move the port without resizing it — e.g. a sibling\n  // row expanding). Subscribing to the per-node measured size makes this\n  // component re-render on every wrapper resize, and the layout effect\n  // below re-runs the measurement.\n  const getMeasuredForNode = useMemo(\n    () => () => store.getMeasuredSize(nodeId),\n    [store, nodeId]\n  );\n  const measuredSize = useSyncExternalStore(\n    store.subscribeMeasuredSizes,\n    getMeasuredForNode\n  );\n\n  useLayoutEffect(() => {\n    measure();\n  }, [measure, measuredSize]);\n\n  useResizeObserver(elementRef, () => {\n    measure();\n  });\n\n  // Unregister on unmount / id change.\n  useLayoutEffect(() => {\n    return () => {\n      store.removePortPosition(nodeId, id);\n    };\n  }, [store, nodeId, id]);\n\n  // ── Hover wiring ──\n  //\n  // Update the store's `hoveredPort` slice on enter/leave so node bodies,\n  // edges, and other ports can react. Library guards against duplicate\n  // notifications when the value doesn't actually change.\n  const onPointerEnter = useCallback((): void => {\n    const current = store.getHover();\n    if (current.hoveredPort?.node === nodeId && current.hoveredPort.port === id)\n      return;\n    store.setHover({ ...current, hoveredPort: { node: nodeId, port: id } });\n  }, [store, nodeId, id]);\n\n  const onPointerLeave = useCallback((): void => {\n    const current = store.getHover();\n    if (current.hoveredPort?.node !== nodeId || current.hoveredPort.port !== id)\n      return;\n    store.setHover({ ...current, hoveredPort: null });\n  }, [store, nodeId, id]);\n\n  const handlePointerDown = useCallback(\n    (event: React.PointerEvent<HTMLSpanElement>): void => {\n      onPortPointerDown(event, id);\n    },\n    [onPortPointerDown, id]\n  );\n\n  const hasCustomVisual = children !== undefined && children !== null;\n  const isFilled = filled ?? connected;\n\n  // Route the consumer's `color` into the slot via a CSS custom property so\n  // the built-in visual (which paints with `currentColor`) picks it up,\n  // while the source / candidate / invalid recipe variants can still\n  // override `color` to keep connection-drag feedback visible.\n  const portStyle: React.CSSProperties | undefined =\n    color !== undefined\n      ? { ['--etui-ng-port-color' as string]: color, ...style }\n      : style;\n\n  return (\n    <span\n      ref={elementRef}\n      role=\"button\"\n      tabIndex={-1}\n      aria-label={label ?? `${side} port ${id}`}\n      data-node-id={nodeId}\n      data-port-id={id}\n      data-port-side={side}\n      data-port-data-type={dataType}\n      data-port-source={isSource || undefined}\n      data-port-candidate={isCandidate || undefined}\n      data-port-invalid={isInvalid || undefined}\n      data-port-hovered={isHovered || undefined}\n      data-port-connected={connected || undefined}\n      className={cx(\n        portSlotRecipe({\n          side,\n          custom: hasCustomVisual,\n          source: isSource,\n          candidate: isCandidate,\n          invalid: isInvalid,\n        }),\n        className\n      )}\n      style={portStyle}\n      onPointerDown={handlePointerDown}\n      onPointerEnter={onPointerEnter}\n      onPointerLeave={onPointerLeave}\n    >\n      {hasCustomVisual ? (\n        children\n      ) : (\n        <NodeGraphPortVisual shape={shape} filled={isFilled} />\n      )}\n    </span>\n  );\n}\n\nexport const NodeGraphPort = React.memo(NodeGraphPortImpl);\nNodeGraphPort.displayName = 'NodeGraphPort';\n"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;AA8BA;AACE;AACA;AACA;AACA;;AAGF;AACE;AAEE;AACA;AACA;AAEJ;AAEA;;;;;;;;;;;;;;;;;;;;;;AAsBG;AACH;;AAaE;AACA;AACA;AACA;;;;;;AAYA;AAII;AAAoC;AACpC;AAEA;AAEE;AACA;AACF;AAA+B;;;;AAI7B;AACA;;;AAMN;AAII;AACA;AAEE;AACA;;AAKN;AACA;AACA;AACA;;;;;;;;;;;;;AAcA;;;;;AAKI;;;AAGF;AACA;;;AAEA;;AACA;AACA;;;;;;AAMA;AACA;AACA;AACF;;;;;;;;;;AAkBE;AACF;AAEA;AACE;AACF;;;AAIE;AACE;AACF;;;;;;;AAQF;AACE;AACA;;;;AAKF;AACE;AACA;;AAEA;;AAGF;AAEI;AACF;;AAKF;;;;;AAMA;;;;;AAuBQ;AACA;AACA;AACA;;AAgBV;AAEO;AACP;;"}

package/dist/esm/components/editor/NodeGraph/NodeGraphPortVisual.js

@@ -0,0 +1,46 @@
+"use client";
+import { jsx } from 'react/jsx-runtime';
+
+// All shapes are authored in a 16×16 user space and scaled to `size`, so a
+// single stroke width reads consistently across shapes.
+const VIEW = 16;
+const STROKE = 2;
+function shapeElement(shape, stroke, fill) {
+    const common = {
+        stroke,
+        fill,
+        strokeWidth: STROKE,
+        strokeLinejoin: 'round',
+    };
+    switch (shape) {
+        case 'square':
+            return jsx("rect", { x: 3, y: 3, width: 10, height: 10, rx: 1.5, ...common });
+        case 'diamond':
+            return jsx("polygon", { points: "8,2 14,8 8,14 2,8", ...common });
+        case 'triangle':
+            // Right-pointing exec/flow arrow (UE Blueprint convention).
+            return jsx("polygon", { points: "3,2.5 13.5,8 3,13.5", ...common });
+        case 'circle':
+        default:
+            return jsx("circle", { cx: 8, cy: 8, r: 5, ...common });
+    }
+}
+/**
+ * Presentational handle shape for a node-graph port. Rendered by
+ * `<NodeGraph.Port>` when no `children` are supplied, and exported so
+ * consumers can reuse the exact handle look inside fully custom port
+ * visuals (e.g. a coloured ring beside a typed label).
+ *
+ * The shape paints with `currentColor` unless `color` is set, which lets
+ * the port slot drive the colour from its `color` prop and override it on
+ * the connection-drag states without this component knowing about them.
+ */
+function NodeGraphPortVisual({ shape = 'circle', color, filled = false, size = 14, className, style, }) {
+    const stroke = color ?? 'currentColor';
+    const fill = filled ? (color ?? 'currentColor') : 'none';
+    return (jsx("svg", { width: size, height: size, viewBox: `0 0 ${VIEW} ${VIEW}`, className: className, style: { display: 'block', overflow: 'visible', ...style }, "aria-hidden": "true", focusable: "false", children: shapeElement(shape, stroke, fill) }));
+}
+NodeGraphPortVisual.displayName = 'NodeGraphPortVisual';
+
+export { NodeGraphPortVisual };
+//# sourceMappingURL=NodeGraphPortVisual.js.map

package/dist/esm/components/editor/NodeGraph/NodeGraphPortVisual.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"NodeGraphPortVisual.js","sources":["src/components/editor/NodeGraph/NodeGraphPortVisual.tsx"],"sourcesContent":["'use client';\n\nimport React from 'react';\n\nimport type { NodeGraphPortShape } from './NodeGraph.types';\n\nexport interface NodeGraphPortVisualProps {\n  /**\n   * Handle shape. @default 'circle'\n   */\n  shape?: NodeGraphPortShape;\n  /**\n   * Stroke / fill colour. Defaults to `currentColor` so the parent\n   * `<NodeGraph.Port>` can route its colour prop and interaction-state\n   * colours (source / candidate / invalid) into the shape via the CSS\n   * `color` cascade. Pass an explicit colour when using the visual\n   * standalone (outside a port slot).\n   */\n  color?: string;\n  /**\n   * Filled (`true`) paints the interior; hollow (`false`) draws an outline\n   * only — the standard \"wired vs unwired pin\" convention.\n   * @default false\n   */\n  filled?: boolean;\n  /**\n   * Box size in CSS pixels. @default 14\n   */\n  size?: number;\n  className?: string;\n  style?: React.CSSProperties;\n}\n\n// All shapes are authored in a 16×16 user space and scaled to `size`, so a\n// single stroke width reads consistently across shapes.\nconst VIEW = 16;\nconst STROKE = 2;\n\nfunction shapeElement(\n  shape: NodeGraphPortShape,\n  stroke: string,\n  fill: string\n): React.ReactElement {\n  const common = {\n    stroke,\n    fill,\n    strokeWidth: STROKE,\n    strokeLinejoin: 'round' as const,\n  };\n  switch (shape) {\n    case 'square':\n      return <rect x={3} y={3} width={10} height={10} rx={1.5} {...common} />;\n    case 'diamond':\n      return <polygon points=\"8,2 14,8 8,14 2,8\" {...common} />;\n    case 'triangle':\n      // Right-pointing exec/flow arrow (UE Blueprint convention).\n      return <polygon points=\"3,2.5 13.5,8 3,13.5\" {...common} />;\n    case 'circle':\n    default:\n      return <circle cx={8} cy={8} r={5} {...common} />;\n  }\n}\n\n/**\n * Presentational handle shape for a node-graph port. Rendered by\n * `<NodeGraph.Port>` when no `children` are supplied, and exported so\n * consumers can reuse the exact handle look inside fully custom port\n * visuals (e.g. a coloured ring beside a typed label).\n *\n * The shape paints with `currentColor` unless `color` is set, which lets\n * the port slot drive the colour from its `color` prop and override it on\n * the connection-drag states without this component knowing about them.\n */\nexport function NodeGraphPortVisual({\n  shape = 'circle',\n  color,\n  filled = false,\n  size = 14,\n  className,\n  style,\n}: NodeGraphPortVisualProps): React.ReactElement {\n  const stroke = color ?? 'currentColor';\n  const fill = filled ? (color ?? 'currentColor') : 'none';\n  return (\n    <svg\n      width={size}\n      height={size}\n      viewBox={`0 0 ${VIEW} ${VIEW}`}\n      className={className}\n      style={{ display: 'block', overflow: 'visible', ...style }}\n      aria-hidden=\"true\"\n      focusable=\"false\"\n    >\n      {shapeElement(shape, stroke, fill)}\n    </svg>\n  );\n}\n\nNodeGraphPortVisual.displayName = 'NodeGraphPortVisual';\n"],"names":[],"mappings":";;;AAiCA;AACA;AACA;AACA;AAEA;AAKE;;;AAGE;AACA;;;AAGA;;AAEA;AACE;AACF;;AAEE;AACF;AACA;AACE;;AAEN;AAEA;;;;;;;;;AASG;AACG;AAQJ;AACA;;AAcF;AAEA;;"}

package/dist/esm/components/editor/NodeGraph/NodeGraphSlots.js

@@ -0,0 +1,50 @@
+import { NODE_GRAPH_SLOT } from './NodeGraph.types.js';
+
+/**
+ * Marker behind `<NodeGraph.Minimap>` — returns `null` and carries a Symbol
+ * the parent uses to identify it inside `children`. The actual minimap is
+ * mounted by `NodeGraph` itself as `<NodeGraphMinimapInner>`.
+ *
+ * Pure marker, no hooks — kept out of any `'use client'` boundary so RSC
+ * frameworks can keep the type-level slot identity on the server.
+ */
+const NodeGraphMinimapImpl = () => null;
+const NodeGraphMinimap = Object.assign(NodeGraphMinimapImpl, {
+    displayName: 'NodeGraph.Minimap',
+    [NODE_GRAPH_SLOT]: 'minimap',
+});
+/**
+ * Marker behind `<NodeGraph.Background>` — see {@link NodeGraphMinimap} for
+ * the rationale. The parent picks this up and mounts the background canvas
+ * layer in the correct position in the layer stack.
+ */
+const NodeGraphBackgroundImpl = () => null;
+const NodeGraphBackground = Object.assign(NodeGraphBackgroundImpl, {
+    displayName: 'NodeGraph.Background',
+    [NODE_GRAPH_SLOT]: 'background',
+});
+/**
+ * Marker behind `<NodeGraph.Toolbar>` — picked up from `<NodeGraph>` children
+ * and mounted into the viewport overlay layer at the requested
+ * placement. Children render via `<NodeGraphToolbarInner>` which keeps
+ * the toolbar positioned over the graph.
+ */
+const NodeGraphToolbarImpl = () => null;
+const NodeGraphToolbar = Object.assign(NodeGraphToolbarImpl, {
+    displayName: 'NodeGraph.Toolbar',
+    [NODE_GRAPH_SLOT]: 'toolbar',
+});
+/**
+ * Marker behind `<NodeGraph.SpawnPalette>` — picked up by the parent
+ * and mounted as a portal-rendered fuzzy-search palette. Auto-opens on
+ * right-click of empty / group targets via the store's spawn-request
+ * channel.
+ */
+const NodeGraphSpawnPaletteImpl = () => null;
+const NodeGraphSpawnPalette = Object.assign(NodeGraphSpawnPaletteImpl, {
+    displayName: 'NodeGraph.SpawnPalette',
+    [NODE_GRAPH_SLOT]: 'spawn-palette',
+});
+
+export { NodeGraphBackground, NodeGraphMinimap, NodeGraphSpawnPalette, NodeGraphToolbar };
+//# sourceMappingURL=NodeGraphSlots.js.map

package/dist/esm/components/editor/NodeGraph/NodeGraphSlots.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"NodeGraphSlots.js","sources":["src/components/editor/NodeGraph/NodeGraphSlots.ts"],"sourcesContent":["import { NODE_GRAPH_SLOT } from './NodeGraph.types';\n\nimport type {\n  NodeGraphBackgroundSlotProps,\n  NodeGraphMinimapSlotProps,\n  NodeGraphSlotMarker,\n  NodeGraphSpawnPaletteSlotProps,\n  NodeGraphToolbarSlotProps,\n} from './NodeGraph.types';\n\n/**\n * Marker behind `<NodeGraph.Minimap>` — returns `null` and carries a Symbol\n * the parent uses to identify it inside `children`. The actual minimap is\n * mounted by `NodeGraph` itself as `<NodeGraphMinimapInner>`.\n *\n * Pure marker, no hooks — kept out of any `'use client'` boundary so RSC\n * frameworks can keep the type-level slot identity on the server.\n */\nconst NodeGraphMinimapImpl: (props: NodeGraphMinimapSlotProps) => null = () =>\n  null;\n\nexport const NodeGraphMinimap = Object.assign(NodeGraphMinimapImpl, {\n  displayName: 'NodeGraph.Minimap',\n  [NODE_GRAPH_SLOT]: 'minimap' as const,\n}) as unknown as ((props: NodeGraphMinimapSlotProps) => null) &\n  NodeGraphSlotMarker & { displayName: string };\n\n/**\n * Marker behind `<NodeGraph.Background>` — see {@link NodeGraphMinimap} for\n * the rationale. The parent picks this up and mounts the background canvas\n * layer in the correct position in the layer stack.\n */\nconst NodeGraphBackgroundImpl: (\n  props: NodeGraphBackgroundSlotProps\n) => null = () => null;\n\nexport const NodeGraphBackground = Object.assign(NodeGraphBackgroundImpl, {\n  displayName: 'NodeGraph.Background',\n  [NODE_GRAPH_SLOT]: 'background' as const,\n}) as unknown as ((props: NodeGraphBackgroundSlotProps) => null) &\n  NodeGraphSlotMarker & { displayName: string };\n\n/**\n * Marker behind `<NodeGraph.Toolbar>` — picked up from `<NodeGraph>` children\n * and mounted into the viewport overlay layer at the requested\n * placement. Children render via `<NodeGraphToolbarInner>` which keeps\n * the toolbar positioned over the graph.\n */\nconst NodeGraphToolbarImpl: (props: NodeGraphToolbarSlotProps) => null = () =>\n  null;\n\nexport const NodeGraphToolbar = Object.assign(NodeGraphToolbarImpl, {\n  displayName: 'NodeGraph.Toolbar',\n  [NODE_GRAPH_SLOT]: 'toolbar' as const,\n}) as unknown as ((props: NodeGraphToolbarSlotProps) => null) &\n  NodeGraphSlotMarker & { displayName: string };\n\n/**\n * Marker behind `<NodeGraph.SpawnPalette>` — picked up by the parent\n * and mounted as a portal-rendered fuzzy-search palette. Auto-opens on\n * right-click of empty / group targets via the store's spawn-request\n * channel.\n */\nconst NodeGraphSpawnPaletteImpl: (\n  props: NodeGraphSpawnPaletteSlotProps\n) => null = () => null;\n\nexport const NodeGraphSpawnPalette = Object.assign(NodeGraphSpawnPaletteImpl, {\n  displayName: 'NodeGraph.SpawnPalette',\n  [NODE_GRAPH_SLOT]: 'spawn-palette' as const,\n}) as unknown as ((props: NodeGraphSpawnPaletteSlotProps) => null) &\n  NodeGraphSlotMarker & { displayName: string };\n"],"names":[],"mappings":";;AAUA;;;;;;;AAOG;AACH,MAAM,oBAAoB,GAA+C,MACvE,IAAI;MAEO,gBAAgB,GAAG,MAAM,CAAC,MAAM,CAAC,oBAAoB,EAAE;AAClE,IAAA,WAAW,EAAE,mBAAmB;IAChC,CAAC,eAAe,GAAG,SAAkB;AACtC,CAAA;AAGD;;;;AAIG;AACH,MAAM,uBAAuB,GAEjB,MAAM,IAAI;MAET,mBAAmB,GAAG,MAAM,CAAC,MAAM,CAAC,uBAAuB,EAAE;AACxE,IAAA,WAAW,EAAE,sBAAsB;IACnC,CAAC,eAAe,GAAG,YAAqB;AACzC,CAAA;AAGD;;;;;AAKG;AACH,MAAM,oBAAoB,GAA+C,MACvE,IAAI;MAEO,gBAAgB,GAAG,MAAM,CAAC,MAAM,CAAC,oBAAoB,EAAE;AAClE,IAAA,WAAW,EAAE,mBAAmB;IAChC,CAAC,eAAe,GAAG,SAAkB;AACtC,CAAA;AAGD;;;;;AAKG;AACH,MAAM,yBAAyB,GAEnB,MAAM,IAAI;MAET,qBAAqB,GAAG,MAAM,CAAC,MAAM,CAAC,yBAAyB,EAAE;AAC5E,IAAA,WAAW,EAAE,wBAAwB;IACrC,CAAC,eAAe,GAAG,eAAwB;AAC5C,CAAA;;;;"}

package/dist/esm/components/editor/NodeGraph/NodeGraphSpawnPalette.js

@@ -0,0 +1,70 @@
+"use client";
+import { jsx } from 'react/jsx-runtime';
+import { useState, useEffect, useMemo, useCallback } from 'react';
+import { CommandPalette } from '../../feedback/CommandPalette/CommandPalette.js';
+import { useNodeGraphStore } from './NodeGraphContext.js';
+import { generateNodeId } from './nodeGraphIds.js';
+
+/**
+ * Live renderer for `<NodeGraph.SpawnPalette>`. Mounted by the parent
+ * when the slot is present in `<NodeGraph>` children. Subscribes to the
+ * store's spawn-request channel — the main `NodeGraph` component fires
+ * the request when the user right-clicks empty space or a group, so
+ * the consumer doesn't need to wire context-menu state through React.
+ *
+ * Selection on a template:
+ *   1. Calls `template.build(worldPoint)` to get the node body
+ *   2. Assigns a unique id
+ *   3. Hands the full node to `onSpawn(node, ctx)` — typically appends
+ *      to the consumer's `nodes` state
+ *   4. Closes the palette
+ */
+function NodeGraphSpawnPaletteInner({ templates, onSpawn, placeholder = 'Search nodes…', recentKey, width = 400, maxHeight = 360, }) {
+    const store = useNodeGraphStore();
+    const [open, setOpen] = useState(false);
+    const [spawnAt, setSpawnAt] = useState(null);
+    // Listen for "user wants to spawn a node here" pings from the main
+    // NodeGraph component (fired from its handleContextMenu for empty /
+    // group targets). Multiple subscribers is fine — the store fans out.
+    useEffect(() => {
+        return store.subscribeSpawnRequest(info => {
+            setSpawnAt(info);
+            setOpen(true);
+        });
+    }, [store]);
+    const items = useMemo(() => {
+        return templates.map(t => ({
+            id: t.id,
+            label: t.title,
+            ...(t.subtitle !== undefined ? { description: t.subtitle } : {}),
+            ...(t.group !== undefined ? { group: t.group } : {}),
+            ...(t.keywords !== undefined ? { keywords: [...t.keywords] } : {}),
+            ...(t.icon !== undefined ? { icon: t.icon } : {}),
+        }));
+    }, [templates]);
+    const handleClose = useCallback(() => {
+        setOpen(false);
+        setSpawnAt(null);
+    }, []);
+    const handleSelect = useCallback((item) => {
+        const template = templates.find(t => t.id === item.id);
+        if (!template || !spawnAt)
+            return;
+        const worldPoint = spawnAt.worldPoint;
+        const draft = template.build(worldPoint);
+        const node = {
+            ...draft,
+            id: generateNodeId(template.id),
+        };
+        const ctx = {
+            worldPoint,
+            screenPoint: spawnAt.screenPoint,
+        };
+        onSpawn(node, ctx);
+        handleClose();
+    }, [templates, spawnAt, onSpawn, handleClose]);
+    return (jsx(CommandPalette, { open: open, onClose: handleClose, items: items, onSelect: handleSelect, placeholder: placeholder, ...(recentKey !== undefined ? { recentKey } : {}), width: width, maxHeight: maxHeight }));
+}
+
+export { NodeGraphSpawnPaletteInner };
+//# sourceMappingURL=NodeGraphSpawnPalette.js.map

package/dist/esm/components/editor/NodeGraph/NodeGraphSpawnPalette.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"NodeGraphSpawnPalette.js","sources":["src/components/editor/NodeGraph/NodeGraphSpawnPalette.tsx"],"sourcesContent":["'use client';\n\nimport React, { useCallback, useEffect, useMemo, useState } from 'react';\n\nimport { CommandPalette } from '@/components/feedback/CommandPalette/CommandPalette';\n\nimport { useNodeGraphStore } from './NodeGraphContext';\nimport { generateNodeId } from './nodeGraphIds';\n\nimport type {\n  NodeGraphNode,\n  NodeGraphSpawnContext,\n  NodeGraphSpawnPaletteSlotProps,\n} from './NodeGraph.types';\nimport type { CommandItem } from '@/components/feedback/CommandPalette/CommandPalette.types';\nimport type { Point2D } from '@/components/primitives/canvas/canvas.types';\n\n/**\n * Live renderer for `<NodeGraph.SpawnPalette>`. Mounted by the parent\n * when the slot is present in `<NodeGraph>` children. Subscribes to the\n * store's spawn-request channel — the main `NodeGraph` component fires\n * the request when the user right-clicks empty space or a group, so\n * the consumer doesn't need to wire context-menu state through React.\n *\n * Selection on a template:\n *   1. Calls `template.build(worldPoint)` to get the node body\n *   2. Assigns a unique id\n *   3. Hands the full node to `onSpawn(node, ctx)` — typically appends\n *      to the consumer's `nodes` state\n *   4. Closes the palette\n */\nexport function NodeGraphSpawnPaletteInner({\n  templates,\n  onSpawn,\n  placeholder = 'Search nodes…',\n  recentKey,\n  width = 400,\n  maxHeight = 360,\n}: NodeGraphSpawnPaletteSlotProps): React.ReactElement {\n  const store = useNodeGraphStore();\n  const [open, setOpen] = useState(false);\n  const [spawnAt, setSpawnAt] = useState<{\n    worldPoint: Point2D;\n    screenPoint: Point2D;\n  } | null>(null);\n\n  // Listen for \"user wants to spawn a node here\" pings from the main\n  // NodeGraph component (fired from its handleContextMenu for empty /\n  // group targets). Multiple subscribers is fine — the store fans out.\n  useEffect(() => {\n    return store.subscribeSpawnRequest(info => {\n      setSpawnAt(info);\n      setOpen(true);\n    });\n  }, [store]);\n\n  const items = useMemo<CommandItem[]>(() => {\n    return templates.map(t => ({\n      id: t.id,\n      label: t.title,\n      ...(t.subtitle !== undefined ? { description: t.subtitle } : {}),\n      ...(t.group !== undefined ? { group: t.group } : {}),\n      ...(t.keywords !== undefined ? { keywords: [...t.keywords] } : {}),\n      ...(t.icon !== undefined ? { icon: t.icon } : {}),\n    }));\n  }, [templates]);\n\n  const handleClose = useCallback(() => {\n    setOpen(false);\n    setSpawnAt(null);\n  }, []);\n\n  const handleSelect = useCallback(\n    (item: CommandItem): void => {\n      const template = templates.find(t => t.id === item.id);\n      if (!template || !spawnAt) return;\n      const worldPoint = spawnAt.worldPoint;\n      const draft = template.build(worldPoint);\n      const node: NodeGraphNode = {\n        ...draft,\n        id: generateNodeId(template.id),\n      };\n      const ctx: NodeGraphSpawnContext = {\n        worldPoint,\n        screenPoint: spawnAt.screenPoint,\n      };\n      onSpawn(node, ctx);\n      handleClose();\n    },\n    [templates, spawnAt, onSpawn, handleClose]\n  );\n\n  return (\n    <CommandPalette\n      open={open}\n      onClose={handleClose}\n      items={items}\n      onSelect={handleSelect}\n      placeholder={placeholder}\n      {...(recentKey !== undefined ? { recentKey } : {})}\n      width={width}\n      maxHeight={maxHeight}\n    />\n  );\n}\n"],"names":[],"mappings":";;;;;;;AAiBA;;;;;;;;;;;;;AAaG;AACG;AAQJ;;;;;;;AAWE;;;AAGA;AACF;AAEA;;;;;;;;AAQG;AACH;AAEA;;;;AAKA;AAEI;AACA;;AACA;;AAEA;AACE;AACA;;AAEF;;;;AAIA;AACA;;;AAiBN;;"}