@tangle-network/sandbox-ui 0.91.5 → 0.93.0

package/dist/workflows.d.ts

@@ -119,14 +119,80 @@ interface WfNode {
     height: number;
     data: WfNodeData;
 }
+/**
+ * Node ids are PUBLIC contract, not an internal detail. A host keys its live
+ * `nodeState` by them, points the graph's `selectedNodeId` at one, and — once it
+ * supplies a declared topology — names its own edge endpoints with them. They
+ * are bare strings, so a host that re-derives the format at the call site gets
+ * no type error when the format changes here; the graph simply renders without
+ * edges. The format is therefore written in exactly one place (these helpers)
+ * and read everywhere else through them.
+ */
+/** The workflow's first (or only) trigger. */
+declare const TRIGGER_NODE_ID = "trigger";
+/** The node for the `index`th entry of a list-form `on:`. Entry 0 IS
+ *  {@link TRIGGER_NODE_ID}, so a single-trigger graph — the overwhelmingly
+ *  common one — keeps the plain id a host may already have persisted.
+ *
+ *  `index` is a position in the definition's `on:` list: a non-negative
+ *  integer. Anything else formats an id no node bears, which a declared
+ *  topology then rejects by name ("…names "trigger:NaN", which this definition
+ *  has no step for") — reported there rather than thrown from here, because
+ *  {@link buildWorkflowGraph} calls this and must never throw. */
+declare function triggerNodeId(index: number): string;
+/** The `on:` entry a trigger node stands for, or null when the id names
+ *  anything else — so a host can tell a trigger from an action without
+ *  matching the id format itself. */
+declare function triggerNodeIndex(nodeId: string): number | null;
+/** The node for the `do` entry at `index`. */
+declare function actionNodeId(index: number): string;
+/** The node for the `branchIndex`th fan-out leaf of the `do` entry at
+ *  `actionIndex` — a `parallel` branch or a `foreach` template. */
+declare function branchNodeId(actionIndex: number, branchIndex: number): string;
 type WfEdgeKind = "spine" | "fork" | "join";
 interface WfEdge {
     id: string;
     source: string;
     target: string;
     /** Spine = trigger→action→action; fork = fan-out into a branch leaf; join =
-     *  a branch leaf reconverging onto the next spine node. Drives edge styling. */
+     *  a branch leaf reconverging onto the next spine node. Drives edge styling.
+     *
+     *  A DECLARED edge ({@link BuildWorkflowGraphOptions.edges}) is a `spine`
+     *  edge: it is the flow. Fork edges survive a declared topology unchanged (a
+     *  branch leaf is this module's own node, which no declared spec addresses);
+     *  join edges do not exist under one, because what follows a fan-out is then
+     *  declared rather than inferred from list position. */
     kind: WfEdgeKind;
+    /** Short, already-human summary of the edge's guard, when it carries one.
+     *  Supplied by {@link WfEdgeSpec.whenLabel} — this module never interprets a
+     *  condition, it only places the label its host wrote. */
+    whenLabel?: string;
+    /** True when this edge closes a cycle: it points back at a node that is
+     *  already on the path reaching it. Rendered distinctly (dashed, with the
+     *  visit budget) because such an edge is the one that can run a node twice. */
+    backEdge?: boolean;
+}
+/**
+ * One edge of a DECLARED topology — the caller's answer to "what actually
+ * connects to what", replacing the positional spine this module would otherwise
+ * infer from `do`-list order.
+ *
+ * Endpoints are node ids from THIS graph, so name them with {@link actionNodeId}
+ * / {@link branchNodeId} / {@link TRIGGER_NODE_ID} rather than by hand. Edges
+ * into a node that has none are how a root is identified: every trigger node
+ * gets an edge to every root, so the caller declares only the topology it owns
+ * and never has to restate what the trigger connects to.
+ *
+ * The guard arrives PRE-SUMMARIZED (`whenLabel`). A condition's schema belongs
+ * to the system that compiles and evaluates it — this library renders graphs and
+ * has no business owning a second, drifting interpretation of one. The same
+ * summary the host writes here is then the one it can show elsewhere (a skipped
+ * step's row), which is what keeps the two readings identical.
+ */
+interface WfEdgeSpec {
+    from: string;
+    to: string;
+    whenLabel?: string;
 }
 interface WfGraph {
     nodes: WfNode[];
@@ -151,12 +217,29 @@ interface BuildWorkflowGraphOptions {
     /** Collapse every node to the fixed icon-tile size, and pitch the layers for
      *  it. Defaults to `false` (the full, expanded card). */
     compact?: boolean;
+    /**
+     * The graph's DECLARED topology. Omit — the default — and edges are inferred
+     * from `do`-list order: a linear spine, which is exactly right for a workflow
+     * that runs as one, and wrong for any workflow whose definition declares its
+     * own edges (`needs`, guards, cycles). Supply it and the inferred spine is
+     * replaced wholesale by these edges, the layout is re-ranked to the shape they
+     * describe (so a diamond reads as a diamond rather than a chain drawn over
+     * one), and cycle-closing edges are marked {@link WfEdge.backEdge}.
+     *
+     * An edge naming a node this graph has no slot for is an ERROR
+     * ({@link WfGraph.error}), never a quiet fall back to the positional spine:
+     * the two disagreeing means the topology and the definition came from
+     * different places, and a graph that draws edges the run will not take is
+     * worse than one that says it cannot be drawn.
+     */
+    edges?: readonly WfEdgeSpec[];
 }
 /** Build a positioned graph from a workflow YAML string. Never throws —
  *  malformed YAML or an empty definition returns an `error` the UI can fall
  *  back on (e.g. show the raw YAML while authoring). `reserveRunState` leaves
  *  room for the rows live run state adds (see {@link nodeHeight}); `direction`
- *  picks the flow axis (default "LR"); `compact` collapses nodes to icon tiles. */
+ *  picks the flow axis (default "LR"); `compact` collapses nodes to icon tiles;
+ *  `edges` replaces the inferred positional spine with a declared topology. */
 declare function buildWorkflowGraph(yaml: string, options?: BuildWorkflowGraphOptions): WfGraph;
 
 interface WorkflowGraphProps {
@@ -187,11 +270,46 @@ interface WorkflowGraphProps {
      * fresh record each update — e.g. from a poll/SSE tick — satisfies this.
      */
     nodeState?: Record<string, WfNodeState>;
+    /**
+     * The graph's DECLARED topology, replacing the spine inferred from `do`-list
+     * order — see {@link WfEdgeSpec}. Name endpoints with the exported id helpers
+     * (`actionNodeId`, `branchNodeId`, `TRIGGER_NODE_ID`).
+     *
+     * Immutability contract, as for `nodeState`: the layout memo keys on this
+     * array's reference, so pass a stable one (a `useMemo`, or a value derived
+     * once per fetch) rather than a fresh literal each render.
+     */
+    edges?: readonly WfEdgeSpec[];
+    /** Per-node visit budget for a cyclic graph, shown on cycle-closing edges.
+     *  Meaningless without `edges` (an inferred spine cannot loop). */
+    maxNodeVisits?: number;
+    /** The node to ring as selected — e.g. the one whose detail panel is open.
+     *  Selection is the host's state; the graph only reflects it. */
+    selectedNodeId?: string;
     /** Click handler for a node (e.g. open a detail drawer). Absent ⇒ nodes are
      *  non-interactive on click. */
     onNodeClick?: (nodeId: string, data: WfNodeData) => void;
+    /**
+     * Editing gestures. Supplying `onEdgeConnect` turns the canvas from a diagram
+     * into an EDITOR: node handles become visible and draggable, an edge can be
+     * selected and removed with Delete/Backspace, and clicking one asks to edit
+     * its guard. Omit all three — the default — and the graph stays the read-only
+     * visualisation it has always been.
+     *
+     * Every callback speaks node ids (`actionNodeId`, `branchNodeId`), never
+     * positions: this component reports the gesture, and turning it into a
+     * definition edit is the host's job — it owns the YAML, and only it knows
+     * what a `needs` row is. Fan-out and trigger edges never fire any of these
+     * ({@link isEditableEdge}), because neither is a row in anyone's topology.
+     *
+     * The canvas holds no pending state: an accepted edit comes back as new
+     * `yaml` + `edges`, and a rejected one simply never arrives.
+     */
+    onEdgeConnect?: (sourceId: string, targetId: string) => void;
+    onEdgeDelete?: (sourceId: string, targetId: string) => void;
+    onEdgeClick?: (sourceId: string, targetId: string) => void;
 }
 
 declare function WorkflowGraph(props: WorkflowGraphProps): React.JSX.Element;
 
-export { type BuildWorkflowGraphOptions, type WfEdge, type WfGraph, type WfNode, type WfNodeData, type WfNodeState, type WfNodeStatus, type WfNodeTone, WorkflowGraph as WorkflowGraphLazy, type WorkflowGraphProps, buildWorkflowGraph };
+export { type BuildWorkflowGraphOptions, TRIGGER_NODE_ID, type WfEdge, type WfEdgeKind, type WfEdgeSpec, type WfGraph, type WfNode, type WfNodeData, type WfNodeState, type WfNodeStatus, type WfNodeTone, WorkflowGraph as WorkflowGraphLazy, type WorkflowGraphProps, actionNodeId, branchNodeId, buildWorkflowGraph, triggerNodeId, triggerNodeIndex };

package/dist/workflows.js

@@ -1,6 +1,11 @@
 import {
-  buildWorkflowGraph
-} from "./chunk-2NS724P4.js";
+  TRIGGER_NODE_ID,
+  actionNodeId,
+  branchNodeId,
+  buildWorkflowGraph,
+  triggerNodeId,
+  triggerNodeIndex
+} from "./chunk-YOSNN3QU.js";
 import {
   ModelBrandStack,
   modelBrandFor
@@ -31,7 +36,7 @@ function retryImport(factory, retries = 2, delayMs = 350) {
 function lazyWorkflowGraph() {
   return lazy(
     () => retryImport(
-      () => import("./WorkflowGraph-GUX7XN7Y.js").then((m) => ({ default: m.WorkflowGraph }))
+      () => import("./WorkflowGraph-TKDBFK3V.js").then((m) => ({ default: m.WorkflowGraph }))
     )
   );
 }
@@ -103,7 +108,12 @@ function WorkflowGraph(props) {
 }
 export {
   ModelBrandStack,
+  TRIGGER_NODE_ID,
   WorkflowGraph as WorkflowGraphLazy,
+  actionNodeId,
+  branchNodeId,
   buildWorkflowGraph,
-  modelBrandFor
+  modelBrandFor,
+  triggerNodeId,
+  triggerNodeIndex
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/sandbox-ui",
-  "version": "0.91.5",
+  "version": "0.93.0",
   "description": "Unified UI component library for Tangle Sandbox — primitives, chat, dashboard, terminal, editor, and workspace components",
   "repository": {
     "type": "git",