@w6w/ui 0.2.0 → 0.2.54

package/dist/flow-types.d.ts

@@ -1,3 +1,5 @@
+import { StateWriteConfig } from '@w6w/expr';
+import { FlowCanvas } from './canvas-types.ts';
 import { EdgeRunState } from './run-visuals.ts';
 import { ActionParam } from './types.ts';
 export interface FlowStep {
@@ -6,13 +8,16 @@ export interface FlowStep {
         app: string;
         action: string;
         connection?: string | null;
+        connectionRef?: string;
+        /** An app TRIGGER node (`action` is the trigger key): behaves like a built-in trigger on the canvas. */
+        trigger?: true;
     };
     /**
      * Declared connection-port cardinality for this step (see core
      * `rfcs/node-types.md` · Ports & cardinality). Omitted fields fall through field-wise to the catalog action, the internal def, then `{ in: 1, out: "many" }`.
-     * A persisted value wins over the node's default — `in > 1` opts the step into
-     * accepting multiple inbound edges (e.g. a flow-control aggregator joining
-     * several upstream branches).
+     * A persisted value wins over the node's default. Only `in: 0` binds (no entry
+     * port); any `in >= 1` accepts any number of inbound edges (core node-types ·
+     * Alternate entries).
      */
     ports?: PortsDecl;
     with?: Record<string, unknown>;
@@ -36,6 +41,8 @@ export interface FlowStep {
      * runs them one after another.
      */
     fanOut?: "sequential" | "parallel";
+    /** Write to state (`Node.state`, core/rfcs/workflow.md). Absent = the default: Off, or Merge at root for `@w6w/data` set. */
+    state?: StateWriteConfig;
     /**
      * Authoring-time canvas coordinate for this step, in this editor's own
      * coordinate space (core `rfcs/workflow.md` · "Amendment — 2026-07-29:
@@ -59,10 +66,26 @@ export interface FlowStep {
         x: number;
         y: number;
     };
+    /**
+     * Disabled: skipped in EVERY run, published and triggered included — the node does not
+     * execute and its outgoing edges are skipped, so a node that depends only on it does not run
+     * either. An engine semantic (mirrors `Node.disabled` in `@w6w/workflow-types`). Written as
+     * `true` or absent, never `false`.
+     */
+    disabled?: true;
+    /**
+     * Editor-only metadata; the engine ignores it. `paused`: a test run started from a node's ▶
+     * stops BEFORE this node (it does not execute). Never affects a published or triggered run.
+     * Absent when empty, never `{}`.
+     */
+    ui?: {
+        paused?: true;
+    };
 }
 export interface FlowEdge {
     from: string;
     to: string;
+    route?: string;
     /**
      * Which outcome of the `from` step this edge carries (core
      * `rfcs/workflow.md` · "Amendment — 2026-07-29: failure-conditioned edges
@@ -110,7 +133,7 @@ export interface FlowEdge {
  * leaves the class in place, so `setEdgeWhen` assigns both keys explicitly
  * rather than spreading.
  */
-export declare function edgeVisuals(when: "success" | "error" | undefined, runState?: EdgeRunState): {
+export declare function edgeVisuals(when: CanvasLane | undefined, runState?: EdgeRunState): {
     className?: string;
     label?: string;
 };
@@ -120,6 +143,25 @@ export declare function edgeVisuals(when: "success" | "error" | undefined, runSt
  * (D-P2), since no consumer outside this package needs it.
  */
 export declare const ERROR_SOURCE_HANDLE = "out-error";
+/**
+ * The handle id of a For each's **Each item** exit port. The `each` lane derives
+ * `with.body` on save; its link to the first body step is also saved as a
+ * {@link FOREACH_EACH_ROUTE} edge so a reader sees which port it leaves.
+ */
+export declare const EACH_SOURCE_HANDLE = "out-each";
+/**
+ * `Edge.route` of a For each's **Done** port (the engine's `FOREACH_DONE_ROUTE`): the
+ * success edge that runs once, after every iteration. An unrouted For each success
+ * edge — the shape saved before the port had an id — is read as Done.
+ */
+export declare const FOREACH_DONE_ROUTE = "done";
+/** `Edge.route` of a For each's Each item link to `with.body[0]` (engine `FOREACH_EACH_ROUTE`). */
+export declare const FOREACH_EACH_ROUTE = "each";
+/**
+ * A lane on the CANVAS. `"each"` is canvas-only (a For each → body-step edge);
+ * the persisted {@link FlowEdge}`["when"]` deliberately stays `"success" | "error"`.
+ */
+export type CanvasLane = "success" | "error" | "each";
 /**
  * The `sourceHandle` a minted/re-laned/loaded edge carries for a given lane —
  * the inverse of {@link laneForSourceHandle}. `undefined` for `"success"`/
@@ -128,7 +170,7 @@ export declare const ERROR_SOURCE_HANDLE = "out-error";
  * already-saved workflow's edges implicitly use. An empty string would not do
  * this — an empty string is a real, if degenerate, handle id.
  */
-export declare function sourceHandleForLane(when: "success" | "error" | undefined): string | undefined;
+export declare function sourceHandleForLane(when: CanvasLane | undefined): string | undefined;
 /**
  * The lane a drag started from, read off the handle id React Flow reports.
  * **The one canonicalisation point** every minting/re-laning site calls
@@ -138,7 +180,7 @@ export declare function sourceHandleForLane(when: "success" | "error" | undefine
  * `"error"`; everything else — a near-miss id, `null`, `undefined` — is
  * `"success"`.
  */
-export declare function laneForSourceHandle(handleId: string | null | undefined): "success" | "error";
+export declare function laneForSourceHandle(handleId: string | null | undefined): CanvasLane;
 export interface FlowWorkflow {
     manifestVersion: string;
     id: string;
@@ -151,8 +193,15 @@ export interface FlowWorkflow {
         required?: boolean;
         default?: unknown;
     }>;
-    steps: FlowStep[];
+    /** Starting data (`Workflow.initialState`): a literal JSON object that seeds the run's state tree. */
+    initialState?: Record<string, unknown>;
+    nodes: FlowStep[];
+    connections?: Record<string, {
+        app: string;
+        connection: string | null;
+    }>;
     edges?: FlowEdge[];
+    canvas?: FlowCanvas;
     /**
      * Authoring-time presentation and preferences for this workflow (core
      * `rfcs/workflow.md` · "Amendment — 2026-07-29: authoring presentation
@@ -209,6 +258,15 @@ export interface FlowWorkflow {
         };
     };
 }
+/**
+ * What `workflowToFlow` accepts: a definition in either shape — the canonical
+ * `nodes[]` or the legacy `steps[]`. Both present is refused at read time.
+ */
+export type FlowWorkflowInput = Omit<FlowWorkflow, "nodes"> & ({
+    nodes: FlowStep[];
+} | {
+    steps: FlowStep[];
+});
 /** Reserved namespace for internal pseudo-apps. */
 export declare const INTERNAL_APP_PREFIX = "@w6w/";
 /** Engine-native flow control (if/foreach/parallel/wait). */
@@ -242,7 +300,13 @@ export declare const CALL_APP = "@w6w/call";
  */
 export declare const DOCUMENT_APP = "@w6w/document";
 /**
- * Compile a Handlebars `template` string against a resolved `values` object
+ * Call a model through a named route / read a connection's models and
+ * allowance. Host node, like {@link DOCUMENT_APP}; the params mirror the
+ * `@w6w/model` internal-app manifest (pinned by `model-node-parity.test.ts`).
+ */
+export declare const MODEL_APP = "@w6w/model";
+/**
+ * Render Handlebars text or JSON string values against a resolved `values` object
  * (core rfcs/node-types.md · F-3 amendment, "the `@w6w/template` host node").
  * Host node: `runInternalNode` short-circuits this id before the registry
  * loads a module — it needs no privileged host resource (no DB, no
@@ -250,6 +314,74 @@ export declare const DOCUMENT_APP = "@w6w/document";
  * compiles to a JS function, the same risk shape `@w6w/script` has.
  */
 export declare const TEMPLATE_APP = "@w6w/template";
+/** Host-run regular-expression operations. */
+export declare const REGEX_APP = "@w6w/regex";
+/**
+ * Read, write, count, list and query the entries of a named data store (core
+ * rfcs/node-types.md, the `@w6w/store` amendment). Host node, like
+ * {@link DOCUMENT_APP}: the run's own account and project are bound host-side, so
+ * there is no scope param — a store is addressed by NAME. The params mirror the
+ * `@w6w/store` internal-app manifest (pinned by `store-node-parity.test.ts`).
+ */
+export declare const STORE_APP = "@w6w/store";
+/** End the whole workflow successfully when its optional condition matches. */
+export declare const STOP_APP = "@w6w/stop";
+export declare const ROUTER_APP = "@w6w/router";
+export declare const RACE_APP = "@w6w/race";
+export declare const RACE_DESCRIPTION = "Continue once with the first arriving path\u2019s output. Later arrivals are ignored for this run. Other paths keep running.";
+export interface RouterRoute {
+    id: string;
+    label?: string;
+    condition?: unknown;
+    default?: boolean;
+}
+export declare function routesForStep(step: FlowStep): RouterRoute[];
+export declare const routeHandle: (id: string) => string;
+export declare const routeFromHandle: (handle: string | null | undefined) => string | undefined;
+/** Route ports the Router card's right edge holds at its natural height. */
+export declare const ROUTER_PORTS_AT_BASE_HEIGHT = 3;
+/** Card height (px, border-box) added per route port past the third. */
+export declare const ROUTER_PORT_STEP = 16;
+export interface RouterPort {
+    id: string;
+    /** Absent for an If's True port: the unnamed handle a route-less edge anchors to. */
+    handleId?: string;
+    label: string;
+    /** Handle position along its edge, as a CSS `top` (right-edge ports only). */
+    top?: string;
+}
+/**
+ * Where a Router's ports sit (human report, 2026-10-31: "they need to be
+ * attached to the router"). Condition routes go on the card's right edge,
+ * evenly spaced; the fallback route takes the bottom edge, the slot every
+ * other node gives its error port. Up to three right-edge ports fit the
+ * card's natural height; each one past that adds a fixed step, so five
+ * routes make a slightly taller card. Handle ids stay `route:<id>`, so
+ * saved edges keep resolving.
+ */
+export interface PortLayout {
+    right: RouterPort[];
+    bottom?: RouterPort;
+    minHeight?: number;
+}
+export declare function routerPortLayout(routes: RouterRoute[]): PortLayout;
+/**
+ * `Edge.route` of an If's false branch (the engine's `IF_FALSE_ROUTE`). The true
+ * branch is an edge with no route, which is what every If edge saved before the
+ * False port existed already is.
+ */
+export declare const IF_FALSE_ROUTE = "false";
+export declare function isIfStep(step: FlowStep): boolean;
+/**
+ * An If's ports, laid out the way {@link routerPortLayout} lays out a Router's
+ * (human report, 2026-10-31: "should not have error, it should have: true port
+ * and false port"). True takes the right edge; False takes the bottom edge, the
+ * slot every other node gives its error port, so an If has no error port. True
+ * keeps the unnamed handle, so saved If edges stay on it; False is `route:false`.
+ */
+export declare function ifPortLayout(): PortLayout & {
+    bottom: RouterPort;
+};
 /** True when `app` is a reserved internal pseudo-app id (`@w6w/*`). */
 export declare function isInternalApp(app: string): boolean;
 /** True when a node is an engine-native flow-control node (can't run standalone). */
@@ -261,6 +393,16 @@ export declare function isControlApp(app: string): boolean;
  * and send the filled values as `{ input }` rather than running the raw config.
  */
 export declare function isTriggerApp(app: string): boolean;
+/**
+ * Whether a step is a trigger NODE: one of the built-in triggers, or an app
+ * trigger node (`uses.trigger === true`). Canvas chrome, wiring and editing key
+ * on this; {@link isTriggerApp} stays for readers that mean the built-in
+ * `@w6w/*` triggers only (a callable workflow's input fields).
+ */
+export declare function isTriggerStep(uses: {
+    app: string;
+    trigger?: true;
+}): boolean;
 /** A palette entry for an internal node: its id, label, group, and config schema. */
 export interface InternalNodeDef {
     app: string;
@@ -272,6 +414,8 @@ export interface InternalNodeDef {
      * does. Shown wherever an app's name would be.
      */
     displayName: string;
+    /** Show one app entry in the palette and choose its action in configuration. */
+    groupActions?: boolean;
     group: "trigger" | "control" | "compute" | "request";
     /**
      * Inline SVG *inner* markup (paths / circles / polylines) for this primitive's
@@ -286,8 +430,9 @@ export interface InternalNodeDef {
      */
     hidden?: boolean;
     /**
-     * Connection ports: how many inbound (entry) and outbound (exit) connections
-     * this node accepts. A port is the ability to receive/emit a connection —
+     * Connection ports: whether this node has an entry (`in >= 1` takes any number
+     * of inbound edges; `in: 0` takes none) and how many outbound (exit) connections
+     * it allows. A port is the ability to receive/emit a connection —
      * rendered as a React Flow Handle. Defaults to one of each (`{ in: 1, out: 1 }`)
      * when omitted; a trigger overrides to `{ in: 0, out: 1 }` (nothing flows into
      * the entry node). Fixed for now — not user-editable.

package/dist/flow-utils.d.ts

@@ -1,6 +1,7 @@
 import { Edge, Node } from '@xyflow/react';
-import { FlowEdge, FlowStep, FlowWorkflow } from './flow-types.ts';
+import { CanvasLane, FlowStep, FlowWorkflow, FlowWorkflowInput } from './flow-types.ts';
 import { RunStatus, StepVisualState } from './run-visuals.ts';
+import { StepProblem } from './step-problems.ts';
 export interface StepNodeData extends Record<string, unknown> {
     step: FlowStep;
     /** True for internal pseudo-app nodes (`@w6w/*`) — rendered as pill cards. */
@@ -21,6 +22,19 @@ export interface StepNodeData extends Record<string, unknown> {
      * provenance/persistence rules as `stepStatus`.
      */
     runStatus?: RunStatus;
+    /**
+     * Host-supplied problems with this step (a dangling connection, loop problems).
+     * Patched in by `WorkflowFlowEditor.tsx`'s `stepProblems` effect — never set
+     * here, absent (never `[]`) when there are none, and never read by {@link flowToWorkflow} (not persisted).
+     */
+    stepProblems?: StepProblem[];
+    /**
+     * The For each this step is a loop-body member of (canvas-only; derived on load
+     * and by the editor, never read by {@link flowToWorkflow}).
+     */
+    loopOf?: string;
+    /** This For each was converted from a legacy (no-`body`) loop on load. Canvas-only. */
+    legacyLoop?: boolean;
 }
 export type StepNode = Node<StepNodeData>;
 /**
@@ -39,13 +53,19 @@ export type StepNode = Node<StepNodeData>;
  * rewrite) in `flow-connect.ts`. A second hand-rolled copy of the template is
  * exactly how the rename path came to drop the qualifier.
  */
-export declare function flowEdgeId(from: string, to: string, when?: FlowEdge["when"]): string;
+export declare function flowEdgeId(from: string, to: string, when?: CanvasLane, route?: string): string;
 /**
  * Why a step id may not be saved from the editor, or `null` when it may. The one
  * rule here is "no `.`" (a dotted id cannot be addressed by `steps.<id>.output`);
  * duplicates and the edge-time `->` / `:error` checks are NOT this function's job.
  */
 export declare function stepIdError(id: string): string | null;
+/**
+ * {@link stepIdError} plus uniqueness: why `id` may not name a node of a graph whose other
+ * nodes are `taken`, or `null`. The rename in the step editor and the name in the add flow
+ * both validate through this.
+ */
+export declare function stepNameError(id: string, taken: Iterable<string>): string | null;
 /**
  * The one wording for a refused edge id, shared by both routes into the collision —
  * drawing a wire whose minted id is taken (`applyConnect` / `connectConflict`) and
@@ -101,6 +121,8 @@ export declare function stepIdError(id: string): string | null;
  * vague-but-true message beats a confident false one.
  */
 export declare function idClashMessage(lead: string, id: string, involved: readonly (string | null | undefined)[]): string;
+/** Read a definition in either shape into the canonical `nodes[]` form. */
+export declare function normalizeInput(input: FlowWorkflowInput): FlowWorkflow;
 /**
  * Turn a Workflow into (nodes, edges) with an auto-layout when no positions are
  * known.
@@ -110,13 +132,10 @@ export declare function idClashMessage(lead: string, id: string, involved: reado
  * positioned graph mixes the two: positioned steps sit where they were left,
  * unpositioned ones take their computed slot.
  *
- * `computeLayers` runs over the **whole** graph either way, and the per-column
- * row counter advances for every step including positioned ones — so an
- * unpositioned step's computed coordinate is a pure function of the graph and
- * does not shift depending on which of its neighbours happen to carry a
- * coordinate.
+ * Layout runs over the whole graph, including positioned steps, so a fallback
+ * coordinate does not depend on which neighbours already have saved positions.
  */
-export declare function workflowToFlow(wf: FlowWorkflow): {
+export declare function workflowToFlow(input: FlowWorkflowInput): {
     nodes: StepNode[];
     edges: Edge[];
 };
@@ -128,12 +147,12 @@ export declare function workflowToFlow(wf: FlowWorkflow): {
  * button acts on **what is currently on the canvas**, including steps added and
  * wires drawn since the last save.
  *
- * Same {@link computeLayers} and same {@link slotPosition} as {@link
+ * Same {@link computePositions} as {@link
  * workflowToFlow}, so a graph with no stored positions lays out byte-identically
  * either way (pinned by `flow-utils.test.ts` — "auto-layout agrees with first
  * open"). The **only** difference is that a stored coordinate does not win here:
  * overriding hand placement is precisely what the author asked for by clicking.
- * That is also why the caller confirms first — there is no undo in studio.
+ * The editor records this as one undoable layout change.
  *
  * Layering is keyed by **`node.id`**, not `node.data.step.id`: React Flow's
  * `edge.source`/`edge.target` name node ids, so keying by anything else would
@@ -163,7 +182,7 @@ export declare function relayoutNodes(nodes: StepNode[], edges: Edge[]): StepNod
  * intended — **a workflow that has never been saved by this editor starts
  * carrying `position` on every step the first time it is saved.**
  */
-export declare function flowToWorkflow(original: FlowWorkflow, nodes: StepNode[], edges: Edge[]): FlowWorkflow;
+export declare function flowToWorkflow(originalInput: FlowWorkflowInput, nodes: StepNode[], edges: Edge[]): FlowWorkflow;
 /** The workflow's stored camera, as `settings.viewport` declares it. */
 type StoredViewport = NonNullable<NonNullable<FlowWorkflow["settings"]>["viewport"]>;
 /**
@@ -280,5 +299,7 @@ export declare function stepToJson(step: StepLike): string;
  * writable: the params-only `JsonEditor`'s `onValidChange` feeds straight back
  * into `with`/`withValues`, same as it always has.
  */
-export declare function paramsToJson(step: Pick<StepLike, "with">): string;
+export declare function paramsToJson(step: Pick<StepLike, "with"> & {
+    uses?: StepLike["uses"];
+}): string;
 export {};