@pauloricca/spagbol 0.0.0-stage → 0.1.1

package/src/react/SpagbolNodeFrame.tsx

@@ -0,0 +1,330 @@
+import { graphPortStates, emptyPortState } from "./portState.js";
+import { SpagbolNodeGroupPortAdd } from "./SpagbolNodeGroupPortAdd.js";
+import { SpagbolNodeGroupPort } from "./SpagbolNodeGroupPort.js";
+import {
+  Handle,
+  Position,
+  NodeResizer,
+  useUpdateNodeInternals,
+  useNodeId,
+} from "@xyflow/react";
+import { useEffect, useMemo, useRef, useState, type PointerEvent as ReactPointerEvent, type CSSProperties, type Ref, type ReactNode } from "react";
+import {
+  portsFor,
+  graphAt,
+  isGroupBoundary,
+  spagbolGroupKinds,
+  spagbolNewPortId,
+  groupPanelLayout,
+  type GraphNode,
+  type PortDefinition,
+} from "../core/index.js";
+import {
+  GraphContext,
+  useEditorSelector,
+  useSpagbol,
+  type SpagbolNodeViewProps,
+} from "./context.js";
+import { SpagbolControlNumber } from "./SpagbolControlNumber.js";
+import { SpagbolNodeFrameTypePicker } from './SpagbolNodeFrameTypePicker.js';
+import { nodeFlowId, sourceHandle, targetHandle } from "./geometry.js";
+
+export interface SpagbolNodePortProps {
+  port: PortDefinition;
+  connectable?: boolean;
+  style?: CSSProperties;
+  position?: Position;
+  className?: string;
+}
+/** Also usable in a completely custom node renderer. */
+export function SpagbolNodePort({ port, connectable = true, style, position, className }: SpagbolNodePortProps) {
+  const { editor } = useSpagbol();
+  const mode = useEditorSelector(editor, snapshot => snapshot.mode);
+  const flowId = useNodeId();
+  const nodeId = flowId?.startsWith('node:') ? flowId.slice(5) : undefined;
+  const reconnecting = useEditorSelector(editor, snapshot => {
+    if (snapshot.mode !== 'edit' || snapshot.selection.linkIds.length !== 1) return false;
+    const link = graphAt(snapshot.document, snapshot.path).links.find(link => link.id === snapshot.selection.linkIds[0]);
+    return !!link && (port.direction === 'output'
+      ? link.source.nodeId === nodeId && link.source.portId === port.id
+      : link.target.type === 'port' && link.target.nodeId === nodeId && link.target.portId === port.id);
+  });
+  const direction = port.direction;
+  return (
+    <Handle
+      id={direction === "input" ? targetHandle(port.id) : sourceHandle(port.id)}
+      type={direction === "input" ? "target" : "source"}
+      position={position ?? (direction === "input" ? Position.Left : Position.Right)}
+      className={`spagbol-node-port${reconnecting ? ' spagbol-node-port-selected-link' : ''} ${className ?? ""}`}
+      isConnectable={
+        mode === "edit" && port.connectable !== false && connectable
+      }
+      style={style}
+      aria-label={`${port.label} ${direction}`}
+    />
+  );
+}
+export interface SpagbolNodeFrameProps extends SpagbolNodeViewProps {
+  children?: ReactNode;
+  overlay?: ReactNode;
+  rootRef?: Ref<HTMLDivElement>;
+  title?: ReactNode;
+  className?: string;
+  hidePorts?: boolean;
+  headerOutput?: boolean;
+  portVisible?(port: PortDefinition): boolean;
+  style?: CSSProperties;
+  /** Domain widgets inside a shared port row. The canvas owns handles and gestures. */
+  renderPortContent?(port: PortDefinition): ReactNode;
+  portExtras?: ReactNode;
+  portsHeader?: ReactNode;
+  forceCompact?: boolean;
+}
+export function SpagbolNodeFrame(props: SpagbolNodeFrameProps) {
+  const { node, selected, projected, children } = props;
+  const { editor, views, features, connecting, diagnostics } = useSpagbol();
+  const [pointerOver, setPointerOver] = useState(false);
+  const updateInternals = useUpdateNodeInternals();
+  const flowId = useNodeId();
+  const singleSelected = useEditorSelector(editor, snapshot => snapshot.selection.nodeIds.length === 1 && snapshot.selection.nodeIds[0] === node.id);
+  const selectedPortId = useEditorSelector(editor, snapshot => snapshot.selection.port?.nodeId === node.id ? snapshot.selection.port.portId : undefined);
+  const mode = useEditorSelector(editor, snapshot => snapshot.mode);
+  const path = useEditorSelector(editor, snapshot => snapshot.path);
+  const boundary = isGroupBoundary(node);
+  const reorder = useRef<{ pointer: number; portId: string; element: HTMLElement } | null>(null);
+  const ports = portsFor(node, editor.nodes);
+  const inputPorts = ports.filter((port) => port.direction === "input" && props.portVisible?.(port) !== false);
+  const outputPorts = ports.filter((port) => port.direction === "output" && props.portVisible?.(port) !== false);
+  const compact = !projected && views[node.kind]?.compact !== false && features.compact && (props.forceCompact || node.compact) && !(selected && singleSelected) && !(connecting && pointerOver);
+  const headerInput = !boundary ? inputPorts.find(port => port.label === 'signal') : undefined;
+  const headerOutput = !boundary && props.headerOutput !== false ? outputPorts.find(port => port.label === 'signal') ?? (outputPorts.length === 1 ? outputPorts[0] : undefined) : undefined;
+  const portState = useEditorSelector(editor, snapshot => graphPortStates(graphAt(snapshot.document, snapshot.path)).get(node.id) ?? emptyPortState);
+  const connectedInputs = portState.inputs;
+  const connectedOutputs = portState.outputs;
+  const visibleInputs = inputPorts.filter(port => port !== headerInput && (!compact || connectedInputs.has(port.id)));
+  const visibleOutputs = outputPorts.filter(port => port !== headerOutput && (!compact || connectedOutputs.has(port.id)));
+  const definition = editor.nodes.get(node.kind);
+  const view = views[node.kind];
+  const newPortDirection = boundary ? (node.kind === spagbolGroupKinds.inputs ? "output" : "input") : definition?.editablePorts;
+  const newPortLabel = definition?.newPortLabel ?? (node.kind === spagbolGroupKinds.inputs ? "new input" : "new output");
+  const errors = diagnostics.filter((item) => item.nodeId === node.id);
+  const portKey = ports
+    .map((port) => `${port.direction}:${port.id}:${port.label}`)
+    .join("|");
+  useEffect(() => {
+    if (projected || !flowId) return;
+    const frame = requestAnimationFrame(() => updateInternals(flowId));
+    return () => cancelAnimationFrame(frame);
+  }, [flowId, portKey, compact, projected, updateInternals]);
+  const setInput = portState.replaced;
+  function movePort(event: ReactPointerEvent<HTMLDivElement>) {
+    const drag = reorder.current;
+    if (!drag || drag.pointer !== event.pointerId) return;
+    event.preventDefault(); event.stopPropagation();
+    const rows = Array.from(event.currentTarget.querySelectorAll<HTMLElement>('[data-group-port]'));
+    const target = rows.findIndex(row => event.clientY < row.getBoundingClientRect().bottom);
+    editor.moveBoundaryPort(node.id, drag.portId, target < 0 ? rows.length - 1 : target);
+  }
+  function endPort(event: ReactPointerEvent<HTMLDivElement>, cancel = false) {
+    const drag = reorder.current;
+    if (!drag || drag.pointer !== event.pointerId) return;
+    event.stopPropagation(); reorder.current = null;
+    if (drag.element.hasPointerCapture(event.pointerId)) drag.element.releasePointerCapture(event.pointerId);
+    if (cancel) editor.cancelGesture(); else editor.commitGesture();
+  }
+  function row(port: PortDefinition, index: number) {
+    const input = port.direction === "input";
+    return (
+      <div
+        className={`spagbol-node-port-row spagbol-node-port-row-${port.direction}`}
+        key={`${port.direction}:${port.id}`}
+        data-group-port={boundary ? port.id : undefined}
+        style={{ gridColumn: boundary || input || inputPorts.length === 0 ? 1 : 2, gridRow: index + 1 + (props.portsHeader ? 1 : 0) }}
+      >
+        {!projected && !props.hidePorts && <SpagbolNodePort port={port} />}
+        {props.renderPortContent ? props.renderPortContent(port) : <>{boundary && !projected ? <SpagbolNodeGroupPort name={port.label} editable={editor.editing && !props.readOnly} draggable={editor.editing && !props.readOnly} selected={selectedPortId === port.id} onChange={label => { try { editor.renameBoundaryPort(node.id, port.id, label); } catch { /* Keep the valid label. */ } }} onPointerDown={event => {
+          if (!editor.editing || props.readOnly || event.button !== 0) return;
+          event.preventDefault(); event.stopPropagation();
+          editor.select({ nodeIds: [node.id], port: { nodeId: node.id, portId: port.id, direction: port.direction } });
+          editor.beginGesture('Reorder group ports');
+          reorder.current = { pointer: event.pointerId, portId: port.id, element: event.currentTarget };
+          event.currentTarget.setPointerCapture(event.pointerId);
+        }} /> : <span className="spagbol-node-port-name" title={port.label}>{port.label}</span>}
+        {((input && node.kind !== spagbolGroupKinds.outputs) || node.kind === spagbolGroupKinds.inputs) && port.valueEditor !== false && (
+          <SpagbolControlNumber
+            value={node.values[port.id] ?? port.defaultValue ?? 0}
+            onChange={(value) => props.setValue(port.id, value)}
+            label={`${node.label ?? definition?.label ?? node.kind}: ${port.label}`}
+            min={port.min}
+            max={port.max}
+            step={port.step}
+            integer={port.integer}
+            disabled={props.readOnly}
+            replaced={setInput.has(port.id)}
+            onGestureStart={() => props.beginGesture(`Change ${port.label}`)}
+            onGestureEnd={(cancel) => props.endGesture(cancel)}
+          />
+        )}</>}
+      </div>
+    );
+  }
+  return (
+    <div
+      onPointerEnter={() => setPointerOver(true)} onPointerLeave={() => setPointerOver(false)}
+      ref={props.rootRef}
+      style={{ ...props.style, ...(node.scale ? { zoom: node.scale, width: view?.autoWidth ? props.style?.width ?? "max-content" : `${100 / node.scale}%`, height: `${100 / node.scale}%` } : view?.autoWidth ? { width: props.style?.width ?? "max-content" } : {}) }}
+      onPointerMove={movePort} onPointerUp={event => endPort(event)} onPointerCancel={event => endPort(event, true)}
+      className={`spagbol-node-frame${selected ? " spagbol-node-frame-selected" : ""}${node.enabled === false ? " spagbol-node-frame-disabled" : ""}${compact ? " spagbol-node-frame-compact" : ""}${props.forceCompact ? " spagbol-node-frame-auto-compact" : ""}${projected ? " spagbol-node-frame-projected nodrag nopan" : ""} ${props.className ?? ""}`}
+    >
+      {!projected && view?.resizable && editor.editing && (
+        <NodeResizer
+          isVisible={selected && !compact}
+          minWidth={view.minWidth ?? 180}
+          minHeight={view.minHeight ?? 80}
+          onResizeStart={() => props.beginGesture("Resize node")}
+          onResize={(_, size) =>
+            editor.updateNode(
+              node.id,
+              {
+                size: { width: size.width / (node.scale ?? 1), height: size.height / (node.scale ?? 1) },
+                position: { x: size.x, y: size.y },
+              },
+              "layout",
+            )
+          }
+          onResizeEnd={() => props.endGesture()}
+        />
+      )}
+      <div
+        style={{ position: "relative" }}
+        className="spagbol-node-frame-header spagbol-canvas-drag-handle"
+        onDoubleClickCapture={event => { if (projected && props.resetOverride) { event.preventDefault(); event.stopPropagation(); props.resetOverride(); } }}
+      >
+        {!projected && !props.hidePorts && headerInput && <SpagbolNodePort port={headerInput} style={{ top: "50%" }} />}
+        {!projected && !props.hidePorts && headerOutput && <SpagbolNodePort port={headerOutput} style={{ top: "50%" }} />}
+        <span className="spagbol-node-frame-title">
+          {props.title ?? <SpagbolNodeFrameTypePicker node={node} compact={!!compact} selected={selected} disabled={projected || props.readOnly || !editor.editing} />}
+        </span>
+        {!projected && <button className="spagbol-node-frame-enabled" type="button" aria-label={node.enabled === false ? 'Enable node' : 'Disable node'} title={node.enabled === false ? 'Enable node' : 'Disable node'} aria-pressed={node.enabled !== false} disabled={!editor.editing || props.readOnly} onPointerDown={event => event.stopPropagation()} onDoubleClick={event => event.stopPropagation()} onClick={event => { event.preventDefault(); event.stopPropagation(); editor.updateNode(node.id, { enabled: node.enabled === false }, 'structure'); }}><span className="spagbol-node-frame-enabled-icon" aria-hidden="true" /></button>}
+        {!projected && features.compact && !props.forceCompact && view?.compact !== false && (
+          <button
+            className="spagbol-node-frame-header-button nodrag nopan"
+            aria-label={node.compact ? "Expand ports" : "Compact ports"}
+            title={node.compact ? "Expand ports" : "Compact ports"}
+            disabled={!editor.editing}
+            onClick={(event) => {
+              event.stopPropagation();
+              editor.updateNode(node.id, { compact: !node.compact }, "layout");
+            }}
+          >
+            {node.compact ? "+" : "−"}
+          </button>
+        )}
+        {!projected && node.graph && features.nestedGraphs && (
+          <button
+            className="spagbol-node-frame-header-button nodrag nopan"
+            aria-label="Enter nested graph"
+            title="Enter nested graph"
+            onClick={(event) => {
+              event.stopPropagation();
+              editor.enter(node.id);
+            }}
+          >
+            ↳
+          </button>
+        )}
+      </div>
+      <>
+          {children && (
+            <div
+              className="spagbol-node-frame-body nodrag nopan"
+              onPointerDown={(event) => event.stopPropagation()}
+            >
+              {children}
+            </div>
+          )}
+          {!props.hidePorts && (visibleInputs.length > 0 || visibleOutputs.length > 0 || newPortDirection) && (
+            <div style={inputPorts.length === 0 || outputPorts.length === 0 ? { gridTemplateColumns: "minmax(0, 1fr)" } : undefined} className={`spagbol-node-frame-ports${boundary ? " spagbol-node-frame-ports-boundary" : ""}`}>
+              {props.portsHeader}
+          {visibleInputs.map(row)}
+              {visibleOutputs.map(row)}
+              {newPortDirection && !projected && editor.editing && <div style={{ gridColumn: newPortDirection === "input" || inputPorts.length === 0 ? 1 : 2, gridRow: ports.length + 1 + (props.portsHeader ? 1 : 0), position: "relative" }}><SpagbolNodePort port={{ id: spagbolNewPortId, label: newPortLabel, direction: newPortDirection }} style={{ top: "50%" }} /><SpagbolNodeGroupPortAdd label={newPortLabel} onAdd={label => { try { editor.addBoundaryPort(node.id, label); } catch { /* Keep the valid boundary. */ } }} /></div>}
+            </div>
+          )}
+          {!compact && props.portExtras}
+          {errors.length > 0 && (
+            <div
+              className="spagbol-node-frame-diagnostics"
+              role="status"
+              title={errors.map((error) => error.message).join("\n")}
+            >
+              {errors[0]?.message}
+            </div>
+          )}
+      </>
+      {props.overlay}
+    </div>
+  );
+}
+
+export function useNodeViewProps(
+  node: GraphNode,
+  selected = false,
+  projected = false,
+  groupId?: string,
+): SpagbolNodeViewProps {
+  const { editor, projection } = useSpagbol();
+  const owner = projection?.groupId ?? groupId;
+  const controlPath = projection?.path ?? [node.id];
+  const mode = useEditorSelector(editor, snapshot => snapshot.mode);
+  const path = useEditorSelector(editor, snapshot => snapshot.path);
+  return useMemo(
+    () => ({
+      node,
+      selected,
+      projected,
+      path: projection ? [...path, projection.groupId, ...projection.path.slice(0, -1)] : path,
+      resetOverride: owner ? () => editor.resetOverride(owner, controlPath) : undefined,
+      readOnly: mode === "readonly",
+      setValue: (portId: string, value: number) =>
+        owner
+          ? editor.setOverride(owner, controlPath, portId, value)
+          : editor.setValue(node.id, portId, value),
+      patchData: (data: Partial<GraphNode["data"]>, structural = false) => {
+        if (projected) { if (!structural && owner) editor.setDataOverride(owner, controlPath, data); return; }
+        editor.updateNode(
+          node.id,
+          { data: { ...node.data, ...data } as GraphNode["data"] },
+          structural ? "structure" : "values",
+        );
+      },
+      beginGesture: (label = "Edit control") => {
+        if (!editor.getSnapshot().gesture) editor.beginGesture(label);
+      },
+      endGesture: (cancel = false) =>
+        cancel ? editor.cancelGesture() : editor.commitGesture(),
+    }),
+    [editor, owner, projection, node, projected, selected, mode, path],
+  );
+}
+
+export function SpagbolNodePanel({ group }: { group: GraphNode }) {
+  const context = useSpagbol();
+  const layout = groupPanelLayout(group);
+  if (!layout) return null;
+  return <div className="spagbol-node-panel nodrag nopan" style={{ position: 'relative', width: layout.size.width, height: layout.size.height }} aria-label="Instance controls" onPointerDown={event => event.stopPropagation()}>
+    {layout.nodes.map(node => <GraphContext.Provider key={node.id} value={{ ...context, projection: { groupId: context.projection?.groupId ?? group.id, path: [...(context.projection?.path ?? []), node.id] } }}>
+      <div className="spagbol-node-panel-item" style={{ position: 'absolute', left: node.position.x - layout.position.x, top: node.position.y - layout.position.y, width: context.views[node.kind]?.autoWidth ? "max-content" : (node.size?.width ?? 220) * (node.scale ?? 1) }}>
+        <SpagbolNodePanelItem node={node} />
+      </div>
+    </GraphContext.Provider>)}
+  </div>;
+}
+function SpagbolNodePanelItem({ node }: { node: GraphNode }) {
+  const { views } = useSpagbol();
+  const props = useNodeViewProps(node, false, true);
+  const Renderer = views[node.kind]?.projected ?? views[node.kind]?.render;
+  if (Renderer) return <Renderer {...props} />;
+  const Body = views[node.kind]?.body;
+  return <SpagbolNodeFrame {...props} hidePorts={!!Body}>{Body ? <Body {...props} /> : null}</SpagbolNodeFrame>;
+}

package/src/react/SpagbolNodeFrameTypePicker.tsx

@@ -0,0 +1,51 @@
+import { useEffect, useMemo, useRef, useState } from 'react';
+import type { GraphNode } from '../core/index.js';
+import { useSpagbol } from './context.js';
+
+/** Teia's inline type-editing interaction, backed by the host's node catalogue. */
+export function SpagbolNodeFrameTypePicker({ node, compact, selected, disabled }: { node: GraphNode; compact: boolean; selected: boolean; disabled: boolean }) {
+  const { editor, nodeKinds, features, changeNodeKind } = useSpagbol();
+  const typeLabel = node.label ?? editor.nodes.get(node.kind)?.label ?? node.kind;
+  const label = compact && node.compactLabel?.trim() ? node.compactLabel : typeLabel;
+  const press = useRef({ time: 0, compact: false });
+  const [editingLabel, setEditingLabel] = useState(false);
+  const [open, setOpen] = useState(false);
+  const [query, setQuery] = useState(label);
+  const [highlight, setHighlight] = useState(0);
+  const input = useRef<HTMLInputElement>(null);
+  const menu = useRef<HTMLDivElement>(null);
+  const options = useMemo(() => [...editor.nodes.list().filter(item => !nodeKinds || nodeKinds.includes(item.kind)), ...(features.areas ? [{ kind: 'spagbol.area', label: 'Area' }] : [])].filter(item =>
+    `${item.kind} ${item.label}`.toLowerCase().includes(query.trim().toLowerCase())
+  ).sort((a, b) => Number(b.label.toLowerCase().startsWith(query.toLowerCase())) - Number(a.label.toLowerCase().startsWith(query.toLowerCase()))), [editor, query, nodeKinds, features.areas]);
+  useEffect(() => { if (!selected || disabled) setOpen(false); }, [selected, disabled]);
+  useEffect(() => { if (open) { input.current?.focus({ preventScroll: true }); input.current?.select(); } }, [open]);
+  useEffect(() => { menu.current?.querySelector('[aria-selected="true"]')?.scrollIntoView({ block: 'nearest' }); }, [highlight]);
+  function commitLabel() { editor.updateNode(node.id, { compactLabel: query.trim() }, "metadata"); setOpen(false); }
+  function choose(kind: string) { if (kind === 'spagbol.area') editor.convertNodeToArea(node.id); else if (changeNodeKind) void changeNodeKind(node.id, kind); else editor.changeNodeKind(node.id, kind); setOpen(false); }
+  return <span className="spagbol-node-frame-type-picker">
+    {!open ? <button type="button" className="spagbol-node-frame-type-picker-button" onPointerDown={() => { const now = performance.now(); if (now - press.current.time > 500) press.current = { time: now, compact }; }} onDoubleClick={event => {
+      event.preventDefault(); event.stopPropagation();
+      if (disabled || !selected) return;
+      const rename = press.current.compact; setEditingLabel(rename);
+      setQuery(rename ? node.compactLabel ?? "" : typeLabel); setHighlight(0); setOpen(true);
+    }}>{label}</button> : <>
+      <span className="spagbol-node-frame-type-picker-placeholder" aria-hidden="true">{label}</span>
+      <div className="spagbol-node-frame-type-picker-editor nodrag nopan nowheel" onMouseDown={event => event.stopPropagation()}>
+        <input ref={input} className="spagbol-node-frame-type-picker-input" aria-label={editingLabel ? "Node label" : "Node type"} role="combobox" aria-expanded="true" aria-controls={`node-type-${node.id}`} aria-autocomplete="list" value={query} spellCheck={false}
+          onChange={event => { setQuery(event.target.value); setHighlight(0); }} onBlur={() => editingLabel ? commitLabel() : setOpen(false)}
+          onPointerDown={event => event.stopPropagation()} onDoubleClick={event => event.stopPropagation()}
+          onKeyDown={event => {
+            event.stopPropagation();
+            if (event.key === 'ArrowDown') { event.preventDefault(); setHighlight(i => Math.min(i + 1, Math.max(0, options.length - 1))); }
+            if (event.key === 'ArrowUp') { event.preventDefault(); setHighlight(i => Math.max(0, i - 1)); }
+            if (event.key === 'Enter') { event.preventDefault(); if (editingLabel) { commitLabel(); return; } const item = options[highlight] ?? options[0]; if (item) choose(item.kind); }
+            if (event.key === 'Escape') { event.preventDefault(); setOpen(false); }
+          }} />
+        {!editingLabel && <div ref={menu} className="spagbol-node-frame-type-picker-menu nowheel" id={`node-type-${node.id}`} role="listbox" onMouseDown={event => { event.preventDefault(); event.stopPropagation(); }} onWheel={event => event.stopPropagation()}>
+          {options.map((item, index) => <button key={item.kind} type="button" role="option" aria-selected={index === highlight} className={index === highlight ? 'active' : ''} onMouseDown={event => { event.preventDefault(); event.stopPropagation(); choose(item.kind); }}>{item.label}</button>)}
+          {!options.length && <div className="spagbol-node-frame-type-picker-empty">no match</div>}
+        </div>}
+      </div>
+    </>}
+  </span>;
+}

package/src/react/SpagbolNodeGroupPort.tsx

@@ -0,0 +1,111 @@
+import { useEffect, useRef, useState, type PointerEvent } from "react";
+interface SpagbolNodeGroupPortProps {
+  name: string;
+  editable: boolean;
+  draggable?: boolean;
+  selected?: boolean;
+  preview?: boolean;
+  activeDragTarget?: boolean;
+  activeDragSource?: boolean;
+  onPointerDown?: (event: PointerEvent<HTMLSpanElement>) => void;
+  onChange: (nextName: string) => void;
+}
+
+export function SpagbolNodeGroupPort({
+  name,
+  editable,
+  draggable = false,
+  selected = false,
+  preview = false,
+  activeDragTarget = false,
+  activeDragSource = false,
+  onPointerDown,
+  onChange,
+}: SpagbolNodeGroupPortProps) {
+  const [editing, setEditing] = useState(false);
+  const [draft, setDraft] = useState(name);
+  const inputRef = useRef<HTMLInputElement | null>(null);
+
+  useEffect(() => {
+    if (!editing) {
+      setDraft(name);
+    }
+  }, [editing, name]);
+
+  useEffect(() => {
+    if (!editing) return;
+
+    const animationFrame = requestAnimationFrame(() => {
+      inputRef.current?.focus();
+      inputRef.current?.select();
+    });
+    return () => cancelAnimationFrame(animationFrame);
+  }, [editing]);
+
+  function commitDraft() {
+    onChange(draft);
+    setEditing(false);
+  }
+
+  function cancelDraft() {
+    setDraft(name);
+    setEditing(false);
+  }
+
+  if (editing) {
+    return (
+      <input
+        ref={inputRef}
+        className="spagbol-node-group-port-editor nodrag nopan"
+        value={draft}
+        onChange={(event) => setDraft(event.currentTarget.value)}
+        onBlur={commitDraft}
+        onKeyDown={(event) => {
+          event.stopPropagation();
+          if (event.key === 'Enter') {
+            commitDraft();
+          }
+          if (event.key === 'Escape') {
+            cancelDraft();
+          }
+        }}
+        onPointerDown={(event) => event.stopPropagation()}
+        onMouseDown={(event) => event.stopPropagation()}
+        onDoubleClick={(event) => event.stopPropagation()}
+        spellCheck={false}
+      />
+    );
+  }
+
+  return (
+    <span
+      className={[
+        'spagbol-node-group-port',
+        editable ? 'spagbol-node-group-port-editable' : '',
+        draggable ? 'spagbol-node-group-port-draggable nodrag nopan' : '',
+          selected ? 'spagbol-node-group-port-selected' : '',
+          preview ? 'spagbol-node-group-port-preview' : '',
+        activeDragTarget ? 'spagbol-node-group-port-drag-target' : '',
+        activeDragSource ? 'spagbol-node-group-port-drag-source' : '',
+      ].filter(Boolean).join(' ')}
+      draggable={draggable}
+        title={preview
+          ? 'Drop a connection here to create this port'
+          : editable
+            ? 'Drag to reorder. Double-click to rename'
+            : undefined}
+        onPointerDown={(event) => {
+          onPointerDown?.(event);
+        }}
+      onDoubleClick={(event) => {
+        if (!editable) return;
+        event.preventDefault();
+        event.stopPropagation();
+        setEditing(true);
+      }}
+    >
+      {name}
+    </span>
+  );
+}
+

package/src/react/SpagbolNodeGroupPortAdd.tsx

@@ -0,0 +1,48 @@
+import { useEffect, useRef, useState } from "react";
+export function SpagbolNodeGroupPortAdd({ label, onAdd }: { label: string; onAdd: (name: string) => void }) {
+  const [editing, setEditing] = useState(false);
+  const [draft, setDraft] = useState('');
+  const inputRef = useRef<HTMLInputElement | null>(null);
+
+  useEffect(() => {
+    if (editing) inputRef.current?.focus();
+  }, [editing]);
+
+  function finish() {
+    if (draft.trim()) onAdd(draft);
+    setDraft('');
+    setEditing(false);
+  }
+
+  return (
+    <div className="spagbol-node-group-port-add nodrag nopan">
+      {editing ? (
+        <input
+          ref={inputRef}
+          className="spagbol-node-group-port-add-editor nodrag nopan"
+          aria-label={label}
+          value={draft}
+          onChange={(event) => setDraft(event.currentTarget.value)}
+          onBlur={finish}
+          onKeyDown={(event) => {
+            event.stopPropagation();
+            if (event.key === 'Enter') finish();
+            if (event.key === 'Escape') { setDraft(''); setEditing(false); }
+          }}
+          onPointerDown={(event) => event.stopPropagation()}
+          onDoubleClick={(event) => event.stopPropagation()}
+          spellCheck={false}
+        />
+      ) : (
+        <button
+          type="button"
+          className="spagbol-node-group-port-add-placeholder nodrag nopan"
+          onPointerDown={(event) => event.stopPropagation()}
+          onClick={(event) => { event.stopPropagation(); setEditing(true); }}
+          onDoubleClick={(event) => event.stopPropagation()}
+        >{label}</button>
+      )}
+    </div>
+  );
+}
+