@object-ui/app-shell 6.2.3 → 7.1.0

package/dist/views/metadata-admin/previews/flow-canvas-layout.d.ts

@@ -0,0 +1,102 @@
+/**
+ * flow-canvas-layout — pure, dependency-free geometry + graph helpers for
+ * the visual flow designer canvas (`FlowCanvas.tsx`).
+ *
+ * Kept separate from the React component so the layout math stays easy to
+ * reason about (and unit-test) without pulling in any rendering concerns.
+ *
+ * Coordinate system: top-to-bottom flowchart (mirrors Power Automate /
+ * Salesforce Flow Builder). Origin is the top-left of the diagram bounding
+ * box after normalization, so every node sits at x >= PADDING, y >= PADDING.
+ */
+export interface FlowNodeUI {
+    x?: number;
+    y?: number;
+}
+export interface FlowNode {
+    id: string;
+    type: string;
+    label?: string;
+    config?: Record<string, unknown>;
+    /** UI-only layout hint persisted via onPatch; ignored by the runtime. */
+    ui?: FlowNodeUI;
+    [k: string]: unknown;
+}
+export interface FlowEdge {
+    id?: string;
+    source: string;
+    target: string;
+    condition?: string | {
+        source?: string;
+    };
+    type?: string;
+    label?: string;
+    isDefault?: boolean;
+}
+export interface Point {
+    x: number;
+    y: number;
+}
+export declare const NODE_W = 240;
+export declare const NODE_H = 66;
+export declare const H_GAP = 44;
+export declare const V_GAP = 56;
+export declare const PADDING = 28;
+/** A node carries a persisted manual position when both x and y are finite. */
+export declare function hasManualPosition(node: FlowNode): boolean;
+/**
+ * Compute a deterministic layered (top-to-bottom) layout.
+ *
+ * - Edges with a dangling endpoint are ignored for layering.
+ * - Layer assignment is a cycle-guarded longest-path relaxation: a node sits
+ *   one layer below its deepest predecessor. Roots (the `start` node, else
+ *   nodes with no incoming edge, else the first node) seed layer 0.
+ * - Nodes never reached from a root are dropped into a trailing layer so the
+ *   author still sees them.
+ * - Within a layer, nodes keep their original `nodes[]` order (stable).
+ * - A node with a persisted `ui` position overrides its computed slot, but is
+ *   still included in the returned map so callers can size the canvas.
+ */
+export declare function computeLayout(nodes: FlowNode[], edges: FlowEdge[]): Map<string, Point>;
+/** Bounding box of the laid-out diagram, including node extents + padding. */
+export declare function diagramSize(positions: Map<string, Point>): {
+    width: number;
+    height: number;
+};
+/** Bottom-center anchor of a node — where its outgoing edges originate. */
+export declare function bottomAnchor(p: Point): Point;
+/** Top-center anchor of a node — where its incoming edges terminate. */
+export declare function topAnchor(p: Point): Point;
+/**
+ * Smooth vertical cubic-bezier path between two anchors. Control points are
+ * pulled along the vertical axis so the curve reads as a top-down flow even
+ * when the target sits above or beside the source.
+ */
+export declare function edgePath(from: Point, to: Point): string;
+/** Midpoint of an edge — anchor for the condition label + insert affordance. */
+export declare function edgeMidpoint(from: Point, to: Point): Point;
+/** True for an ADR-0044 declared back-edge (a revise/rework loop's return). */
+export declare function isBackEdge(edge: Pick<FlowEdge, 'type'>): boolean;
+/** Right-center anchor of a node — where a back-edge's return arc attaches. */
+export declare function rightAnchor(p: Point): Point;
+/**
+ * Curved return path for a declared back-edge (ADR-0044 revise loop). Unlike a
+ * forward edge (top→bottom), a back-edge re-enters an earlier node, so we route
+ * it off the right side of both endpoints and bow it out to the right — a
+ * distinct return arc that reads as "loop back" rather than crossing the
+ * top-to-bottom forward edges.
+ */
+export declare function backEdgePath(from: Point, to: Point): string;
+/** Anchor for a back-edge's label pill — the apex of its return arc. */
+export declare function backEdgeLabelAnchor(from: Point, to: Point): Point;
+/**
+ * Stable identity for an edge. Prefers an explicit `edge.id`; otherwise falls
+ * back to a `source->target#index` composite so an unsaved edge still has a
+ * deterministic key. Used for selection, traversal highlighting, and inspector
+ * lookup — all of which read the same `draft.edges` array, so the index is
+ * consistent across them. Editing label/condition/isDefault never changes the
+ * key (source/target/index are untouched), so a selection survives edits.
+ */
+export declare function edgeKey(edge: FlowEdge, index: number): string;
+/** Human-readable condition text for an edge's optional guard. */
+export declare function conditionText(c: FlowEdge['condition']): string | undefined;

package/dist/views/metadata-admin/previews/flow-canvas-layout.js

@@ -0,0 +1,227 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+// Node card + spacing geometry. Written as plain numbers so both the layout
+// pass and the SVG edge router share one source of truth.
+export const NODE_W = 240;
+export const NODE_H = 66;
+export const H_GAP = 44;
+export const V_GAP = 56;
+export const PADDING = 28;
+/** True when a value is a usable, finite coordinate. */
+function isFiniteNum(v) {
+    return typeof v === 'number' && Number.isFinite(v);
+}
+/** A node carries a persisted manual position when both x and y are finite. */
+export function hasManualPosition(node) {
+    return isFiniteNum(node.ui?.x) && isFiniteNum(node.ui?.y);
+}
+/**
+ * Compute a deterministic layered (top-to-bottom) layout.
+ *
+ * - Edges with a dangling endpoint are ignored for layering.
+ * - Layer assignment is a cycle-guarded longest-path relaxation: a node sits
+ *   one layer below its deepest predecessor. Roots (the `start` node, else
+ *   nodes with no incoming edge, else the first node) seed layer 0.
+ * - Nodes never reached from a root are dropped into a trailing layer so the
+ *   author still sees them.
+ * - Within a layer, nodes keep their original `nodes[]` order (stable).
+ * - A node with a persisted `ui` position overrides its computed slot, but is
+ *   still included in the returned map so callers can size the canvas.
+ */
+export function computeLayout(nodes, edges) {
+    const positions = new Map();
+    if (nodes.length === 0)
+        return positions;
+    const byId = new Map(nodes.map((n) => [n.id, n]));
+    const indexOf = new Map(nodes.map((n, i) => [n.id, i]));
+    const outAdj = new Map();
+    const incoming = new Map();
+    for (const n of nodes)
+        incoming.set(n.id, 0);
+    for (const e of edges) {
+        if (!byId.has(e.source) || !byId.has(e.target) || e.source === e.target)
+            continue;
+        // ADR-0044: a declared back-edge (`type: 'back'`) re-enters an earlier node
+        // to close a revise loop. Exclude it from layering — exactly as the engine
+        // excludes it from DAG validation — so the loop doesn't drag its target
+        // node below the wait point. The edge is still drawn (as a return arc).
+        if (isBackEdge(e))
+            continue;
+        if (!outAdj.has(e.source))
+            outAdj.set(e.source, []);
+        outAdj.get(e.source).push(e.target);
+        incoming.set(e.target, (incoming.get(e.target) ?? 0) + 1);
+    }
+    // Seed roots: explicit start nodes, then any node with no incoming edge,
+    // finally the first node as a last resort (handles pure cycles).
+    const roots = [];
+    for (const n of nodes)
+        if (n.type === 'start')
+            roots.push(n.id);
+    for (const n of nodes)
+        if ((incoming.get(n.id) ?? 0) === 0 && !roots.includes(n.id))
+            roots.push(n.id);
+    if (roots.length === 0)
+        roots.push(nodes[0].id);
+    const layer = new Map();
+    const queue = [];
+    for (const r of roots) {
+        layer.set(r, 0);
+        queue.push(r);
+    }
+    // Relaxation with a hard iteration cap so a cyclic graph can never loop.
+    const maxIterations = nodes.length * Math.max(1, edges.length) + nodes.length + 1;
+    let iterations = 0;
+    while (queue.length && iterations < maxIterations) {
+        iterations += 1;
+        const id = queue.shift();
+        const base = layer.get(id) ?? 0;
+        for (const next of outAdj.get(id) ?? []) {
+            const candidate = base + 1;
+            if ((layer.get(next) ?? -1) < candidate) {
+                layer.set(next, candidate);
+                queue.push(next);
+            }
+        }
+    }
+    // Any node not reached above goes one layer below the deepest known layer.
+    let maxLayer = 0;
+    for (const v of layer.values())
+        maxLayer = Math.max(maxLayer, v);
+    for (const n of nodes) {
+        if (!layer.has(n.id)) {
+            maxLayer += 1;
+            layer.set(n.id, maxLayer);
+        }
+    }
+    // Bucket nodes by layer, preserving original order within each layer.
+    const byLayer = new Map();
+    for (const n of nodes) {
+        const l = layer.get(n.id) ?? 0;
+        if (!byLayer.has(l))
+            byLayer.set(l, []);
+        byLayer.get(l).push(n.id);
+    }
+    for (const ids of byLayer.values()) {
+        ids.sort((a, b) => (indexOf.get(a) ?? 0) - (indexOf.get(b) ?? 0));
+    }
+    const sortedLayers = [...byLayer.keys()].sort((a, b) => a - b);
+    for (const l of sortedLayers) {
+        const ids = byLayer.get(l);
+        const rowWidth = ids.length * NODE_W + (ids.length - 1) * H_GAP;
+        const startX = -rowWidth / 2;
+        ids.forEach((id, i) => {
+            positions.set(id, {
+                x: startX + i * (NODE_W + H_GAP),
+                y: l * (NODE_H + V_GAP),
+            });
+        });
+    }
+    // Normalize the auto-computed slots so the diagram starts at
+    // (PADDING, PADDING). We do this BEFORE applying manual overrides so the
+    // auto-laid nodes always live in one stable frame — a dragged node then
+    // keeps the exact coordinate the user dropped it at, with no drift.
+    let minX = Infinity;
+    let minY = Infinity;
+    for (const p of positions.values()) {
+        minX = Math.min(minX, p.x);
+        minY = Math.min(minY, p.y);
+    }
+    if (Number.isFinite(minX) && Number.isFinite(minY)) {
+        const dx = PADDING - minX;
+        const dy = PADDING - minY;
+        for (const [id, p] of positions)
+            positions.set(id, { x: p.x + dx, y: p.y + dy });
+    }
+    // Apply persisted manual overrides on top of the normalized frame.
+    for (const n of nodes) {
+        if (hasManualPosition(n)) {
+            positions.set(n.id, { x: Math.max(0, n.ui.x), y: Math.max(0, n.ui.y) });
+        }
+    }
+    return positions;
+}
+/** Bounding box of the laid-out diagram, including node extents + padding. */
+export function diagramSize(positions) {
+    let maxX = 0;
+    let maxY = 0;
+    for (const p of positions.values()) {
+        maxX = Math.max(maxX, p.x + NODE_W);
+        maxY = Math.max(maxY, p.y + NODE_H);
+    }
+    return { width: maxX + PADDING, height: maxY + PADDING };
+}
+/** Bottom-center anchor of a node — where its outgoing edges originate. */
+export function bottomAnchor(p) {
+    return { x: p.x + NODE_W / 2, y: p.y + NODE_H };
+}
+/** Top-center anchor of a node — where its incoming edges terminate. */
+export function topAnchor(p) {
+    return { x: p.x + NODE_W / 2, y: p.y };
+}
+/**
+ * Smooth vertical cubic-bezier path between two anchors. Control points are
+ * pulled along the vertical axis so the curve reads as a top-down flow even
+ * when the target sits above or beside the source.
+ */
+export function edgePath(from, to) {
+    const dy = Math.max(Math.abs(to.y - from.y) * 0.5, 24);
+    const c1 = { x: from.x, y: from.y + dy };
+    const c2 = { x: to.x, y: to.y - dy };
+    return `M ${from.x},${from.y} C ${c1.x},${c1.y} ${c2.x},${c2.y} ${to.x},${to.y}`;
+}
+/** Midpoint of an edge — anchor for the condition label + insert affordance. */
+export function edgeMidpoint(from, to) {
+    return { x: (from.x + to.x) / 2, y: (from.y + to.y) / 2 };
+}
+/** True for an ADR-0044 declared back-edge (a revise/rework loop's return). */
+export function isBackEdge(edge) {
+    return edge.type === 'back';
+}
+/** Right-center anchor of a node — where a back-edge's return arc attaches. */
+export function rightAnchor(p) {
+    return { x: p.x + NODE_W, y: p.y + NODE_H / 2 };
+}
+/** Horizontal bow of a back-edge's return arc, scaled to the vertical span. */
+function backEdgeBow(from, to) {
+    return Math.max(64, Math.abs(to.y - from.y) * 0.35);
+}
+/**
+ * Curved return path for a declared back-edge (ADR-0044 revise loop). Unlike a
+ * forward edge (top→bottom), a back-edge re-enters an earlier node, so we route
+ * it off the right side of both endpoints and bow it out to the right — a
+ * distinct return arc that reads as "loop back" rather than crossing the
+ * top-to-bottom forward edges.
+ */
+export function backEdgePath(from, to) {
+    const bow = backEdgeBow(from, to);
+    const c1 = { x: from.x + bow, y: from.y };
+    const c2 = { x: to.x + bow, y: to.y };
+    return `M ${from.x},${from.y} C ${c1.x},${c1.y} ${c2.x},${c2.y} ${to.x},${to.y}`;
+}
+/** Anchor for a back-edge's label pill — the apex of its return arc. */
+export function backEdgeLabelAnchor(from, to) {
+    // The cubic's t=0.5 point sits ~0.75·bow right of the (shared) right edge.
+    const bow = backEdgeBow(from, to);
+    return { x: Math.max(from.x, to.x) + bow * 0.75, y: (from.y + to.y) / 2 };
+}
+/**
+ * Stable identity for an edge. Prefers an explicit `edge.id`; otherwise falls
+ * back to a `source->target#index` composite so an unsaved edge still has a
+ * deterministic key. Used for selection, traversal highlighting, and inspector
+ * lookup — all of which read the same `draft.edges` array, so the index is
+ * consistent across them. Editing label/condition/isDefault never changes the
+ * key (source/target/index are untouched), so a selection survives edits.
+ */
+export function edgeKey(edge, index) {
+    return edge.id || `${edge.source}->${edge.target}#${index}`;
+}
+/** Human-readable condition text for an edge's optional guard. */
+export function conditionText(c) {
+    if (!c)
+        return undefined;
+    if (typeof c === 'string')
+        return c;
+    if (typeof c === 'object' && typeof c.source === 'string')
+        return c.source;
+    return undefined;
+}

package/dist/views/metadata-admin/previews/flow-canvas-parts.d.ts

@@ -0,0 +1,96 @@
+/**
+ * flow-canvas-parts — presentational building blocks for `FlowCanvas.tsx`:
+ * the per-node-type icon/tone mapping, the node card, and the add-node
+ * palette popover. Kept dependency-free and Shadcn-native (Tailwind + lucide).
+ */
+import * as React from 'react';
+import { type LucideIcon } from 'lucide-react';
+import { type Point } from './flow-canvas-layout';
+export declare function nodeIcon(type: string): LucideIcon;
+interface NodeTone {
+    /** Icon color (used inside the tinted chip). */
+    icon: string;
+    /** Card accent border (left edge) + selected ring color. */
+    accent: string;
+    /** Small type-label text color. */
+    label: string;
+    /** Tinted icon-chip background + ring — the card's primary color cue. */
+    chip: string;
+}
+export declare function nodeTone(type: string): NodeTone;
+/**
+ * Renders the glyph for a node type. Uses `createElement` (rather than binding
+ * the resolved icon to a capitalized local) so the renderer stays a stable
+ * module-scope component instead of one re-created on every parent render.
+ */
+export declare function NodeTypeIcon({ type, className }: {
+    type: string;
+    className?: string;
+}): React.FunctionComponentElement<Omit<import("lucide-react").LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+/** Palette grouping — keeps the add-node list scannable as it grows. */
+export type NodeCategory = 'Data' | 'Logic' | 'Human' | 'Integration' | 'Flow';
+/** Display order of the palette's category sections. */
+export declare const NODE_CATEGORY_ORDER: NodeCategory[];
+export interface PaletteItem {
+    type: string;
+    label: string;
+    hint?: string;
+    /** Section this item belongs to in the grouped palette. */
+    category?: NodeCategory;
+}
+/**
+ * Category for a node type — drives palette grouping and gives engine-only
+ * (plugin-contributed) types a sensible section. Mirrors the `nodeTone`
+ * families so color and grouping stay consistent.
+ */
+export declare function nodeCategory(type: string): NodeCategory;
+/** Node types offered by the add-node palette (spec `FlowNodeAction`). */
+export declare const NODE_PALETTE: PaletteItem[];
+/** Human-friendly default label for a newly created node of `type`. */
+export declare function defaultNodeLabel(type: string): string;
+/**
+ * Spec-valid seed fields for a newly created node, so structured blocks start
+ * in a valid-ish shape (e.g. a wait node already has a timer eventType) rather
+ * than an empty intermediate state. Returns extra node props to spread in.
+ */
+export declare function defaultNodeExtras(type: string): Record<string, unknown>;
+export interface NodeCardProps {
+    id: string;
+    type: string;
+    label: string;
+    summary?: string;
+    position: Point;
+    selected: boolean;
+    editable: boolean;
+    /** Simulation overlay: the currently-executing or already-visited node. */
+    runState?: 'active' | 'visited';
+    /** Dim nodes not yet reached while a simulation is in progress. */
+    dimmed?: boolean;
+    /** Structural-validation error highlight (e.g. part of an un-declared cycle). */
+    invalid?: boolean;
+    onPointerDown?: (e: React.PointerEvent) => void;
+    onSelect?: () => void;
+    onAppend?: () => void;
+    /**
+     * ADR-0044: when set (approval nodes without an existing revise loop), render
+     * the one-click "add revision loop" affordance — drops a wait node + the
+     * `revise` and declared `back` edges in a single gesture.
+     */
+    onAddReviseLoop?: () => void;
+}
+/**
+ * A single draggable flow node rendered at an absolute canvas coordinate.
+ * The card body drives selection + reposition; a dedicated bottom "+" handle
+ * (edit mode only) appends a connected child without ambiguity.
+ */
+export declare function NodeCard({ type, label, summary, position, selected, editable, runState, dimmed, invalid, onPointerDown, onSelect, onAppend, onAddReviseLoop, }: NodeCardProps): React.JSX.Element;
+export interface NodePaletteProps {
+    locale?: string;
+    /** Node types to offer. Defaults to the hardcoded {@link NODE_PALETTE}. */
+    items?: PaletteItem[];
+    onPick: (type: string) => void;
+    onClose: () => void;
+}
+/** Compact popover listing the node types an author can add, grouped by category. */
+export declare function NodePalette({ items, onPick, onClose }: NodePaletteProps): React.JSX.Element;
+export {};