@foldworks/workflow

Internal structured-workflow primitives for Foldkit applications.

The package owns:

• recursive flows and branch-aware immutable operations;
• stable flow locations for inserting and moving elements;
• a deterministic orthogonal layout with derived connectors, labels, junctions, and insertion targets in vertical or horizontal orientation;
• a workflow-specific facade over Foldkit UI drag and drop;
• a generic node-type registry contract.

The consuming application registers its node catalogue. Definitions provide a factory, dimensions, palette metadata, and an application-specific renderer, so the package does not prescribe Action, Condition, Switch, or other business types.

const nodeTypes = defineNodeTypes({
  action: {
    create: (id) => action(id),
    size: () => ({ width: 252, height: 62 }),
    palette: {
      label: "Action",
      description: "Run an operation",
    },
    movable: true,
    deletable: true,
    render: ActionNode.view,
  },
})

Branching definitions create child flows on their node instances. Layout and drag operations treat those child flows generically, including dynamic switch cases.

Pass orientation: "Horizontal" to createStructuredLayout for a left-to-right graph. The default is "Vertical". Use the same orientation when initializing Workflow.init so pointer and keyboard drag behavior follows the rendered axis. The interaction defaults to an 8px activation threshold.

paletteItemId and paletteTypeFromId own palette identifiers. applyReorder decodes a Workflow.OutMessage.Reordered and applies either insertElement or moveElement; the application supplies createFromPalette and therefore keeps ownership of node construction. For sortable keyboard movement, render nodes inside the flowContainerId(flow.id) droppable and pass that same id to Workflow.draggable.