@object-ui/app-shell 6.2.3 → 7.0.0

package/dist/views/metadata-admin/previews/block-types.js

@@ -0,0 +1,110 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+/**
+ * Catalog of Page-block types, mirrored from the framework's Page
+ * schema (`regions[].components[].type` enum). Grouped + iconified
+ * for the picker UI in PageBlockCanvas.
+ *
+ * Source of truth: keep the IDs in sync with
+ * `@objectstack/spec`'s page protocol. New block types appear in the
+ * `Other` category by default — add a META entry to give them an icon.
+ */
+import { PanelTop, PanelBottom, PanelLeft, Folders, ChevronsUpDown, Square, Layers, FileText, Tag, ListChecks, Activity, MessageSquare, Compass, AlertTriangle, Zap, BookOpen, History, Menu, Search, Bot, Sparkles, Type, Hash, Image as ImageIcon, Minus, MousePointerClick, List, Rows3, Box, Table, FormInput, Gauge, Columns3, LayoutGrid, } from 'lucide-react';
+export const BLOCK_TYPE_META = {
+    // Data — object-bound views & layout grid
+    'grid': { label: 'Grid', category: 'data', Icon: LayoutGrid },
+    'object-grid': { label: 'Table', category: 'data', Icon: Table },
+    'object-form': { label: 'Form', category: 'data', Icon: FormInput },
+    'object-metric': { label: 'Metric', category: 'data', Icon: Gauge },
+    'object-kanban': { label: 'Kanban', category: 'data', Icon: Columns3 },
+    // Page layout
+    'page:header': { label: 'Header', category: 'layout', Icon: PanelTop },
+    'page:footer': { label: 'Footer', category: 'layout', Icon: PanelBottom },
+    'page:sidebar': { label: 'Sidebar', category: 'layout', Icon: PanelLeft },
+    'page:tabs': { label: 'Tabs', category: 'layout', Icon: Folders },
+    'page:accordion': { label: 'Accordion', category: 'layout', Icon: ChevronsUpDown },
+    'page:card': { label: 'Card', category: 'layout', Icon: Square },
+    'page:section': { label: 'Section', category: 'layout', Icon: Layers },
+    // Record context
+    'record:details': { label: 'Record details', category: 'record', Icon: FileText },
+    'record:highlights': { label: 'Highlights', category: 'record', Icon: Tag },
+    'record:related_list': { label: 'Related list', category: 'record', Icon: ListChecks },
+    'record:activity': { label: 'Activity timeline', category: 'record', Icon: Activity },
+    'record:chatter': { label: 'Chatter feed', category: 'record', Icon: MessageSquare },
+    'record:path': { label: 'Stage path', category: 'record', Icon: Compass },
+    'record:alert': { label: 'Alert banner', category: 'record', Icon: AlertTriangle },
+    'record:quick_actions': { label: 'Quick actions', category: 'record', Icon: Zap },
+    'record:reference_rail': { label: 'Reference rail', category: 'record', Icon: BookOpen },
+    'record:history': { label: 'History', category: 'record', Icon: History },
+    // Navigation (page-content only; shell singletons are not page blocks)
+    'nav:menu': { label: 'Nav menu', category: 'navigation', Icon: Menu },
+    'nav:breadcrumb': { label: 'Breadcrumb', category: 'navigation', Icon: Compass },
+    'global:search': { label: 'Global search', category: 'navigation', Icon: Search },
+    // AI
+    'ai:chat_window': { label: 'AI chat window', category: 'ai', Icon: Bot },
+    'ai:suggestion': { label: 'AI suggestion', category: 'ai', Icon: Sparkles },
+    // Elements
+    'element:text': { label: 'Text', category: 'element', Icon: Type },
+    'element:number': { label: 'Number', category: 'element', Icon: Hash },
+    'element:image': { label: 'Image', category: 'element', Icon: ImageIcon },
+    'element:divider': { label: 'Divider', category: 'element', Icon: Minus },
+    'element:button': { label: 'Button', category: 'element', Icon: MousePointerClick },
+    'element:definition-list': { label: 'Definition list', category: 'element', Icon: List },
+    'element:repeater': { label: 'Repeater', category: 'element', Icon: Rows3 },
+};
+export const CATEGORY_LABEL_EN = {
+    data: 'Data',
+    layout: 'Layout',
+    record: 'Record context',
+    navigation: 'Navigation',
+    element: 'Elements',
+    ai: 'AI',
+    misc: 'Other',
+};
+export const TYPES_BY_CATEGORY = (() => {
+    const out = {
+        data: [], layout: [], record: [], navigation: [], element: [], ai: [], misc: [],
+    };
+    for (const [id, meta] of Object.entries(BLOCK_TYPE_META)) {
+        out[meta.category].push(id);
+    }
+    return ['data', 'layout', 'record', 'element', 'navigation', 'ai', 'misc']
+        .map((c) => ({ category: c, types: out[c] }))
+        .filter((g) => g.types.length > 0);
+})();
+/** Fallback icon for unknown block types. */
+export const UnknownBlockIcon = Box;
+export const BLOCK_CATEGORY_TONE = {
+    data: {
+        icon: 'text-emerald-500 dark:text-emerald-400',
+        badge: 'border-emerald-200 bg-emerald-50 text-emerald-700 dark:border-emerald-900 dark:bg-emerald-950/40 dark:text-emerald-300',
+    },
+    layout: {
+        icon: 'text-slate-500 dark:text-slate-400',
+        badge: 'border-slate-200 bg-slate-50 text-slate-700 dark:border-slate-800 dark:bg-slate-900/40 dark:text-slate-300',
+    },
+    record: {
+        icon: 'text-blue-500 dark:text-blue-400',
+        badge: 'border-blue-200 bg-blue-50 text-blue-700 dark:border-blue-900 dark:bg-blue-950/40 dark:text-blue-300',
+    },
+    navigation: {
+        icon: 'text-indigo-500 dark:text-indigo-400',
+        badge: 'border-indigo-200 bg-indigo-50 text-indigo-700 dark:border-indigo-900 dark:bg-indigo-950/40 dark:text-indigo-300',
+    },
+    element: {
+        icon: 'text-teal-500 dark:text-teal-400',
+        badge: 'border-teal-200 bg-teal-50 text-teal-700 dark:border-teal-900 dark:bg-teal-950/40 dark:text-teal-300',
+    },
+    ai: {
+        icon: 'text-violet-500 dark:text-violet-400',
+        badge: 'border-violet-200 bg-violet-50 text-violet-700 dark:border-violet-900 dark:bg-violet-950/40 dark:text-violet-300',
+    },
+    misc: {
+        icon: 'text-zinc-500 dark:text-zinc-400',
+        badge: 'border-zinc-200 bg-zinc-50 text-zinc-600 dark:border-zinc-800 dark:bg-zinc-900/40 dark:text-zinc-400',
+    },
+};
+/** Resolve a category tone for any block `type` string (handles unknowns). */
+export function resolveBlockTone(type) {
+    const meta = BLOCK_TYPE_META[type];
+    return BLOCK_CATEGORY_TONE[meta?.category ?? 'misc'];
+}

package/dist/views/metadata-admin/previews/field-types.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Canonical field-type catalog for the object form designer.
+ *
+ * Mirrors `@objectstack/spec`'s `FieldType` discriminated union (46
+ * entries as of spec 7.1) but grouped into the 9 user-facing
+ * categories used by the type picker and inspector.
+ *
+ * Adding a new type here is enough — the canvas and inspector both
+ * key off `FIELD_TYPE_META` for icon / label / category lookup, and
+ * the picker auto-includes any new entry.
+ */
+import type { LucideIcon } from 'lucide-react';
+export type FieldTypeId = 'text' | 'textarea' | 'email' | 'url' | 'phone' | 'password' | 'markdown' | 'html' | 'richtext' | 'number' | 'currency' | 'percent' | 'date' | 'datetime' | 'time' | 'boolean' | 'toggle' | 'select' | 'multiselect' | 'radio' | 'checkboxes' | 'lookup' | 'master_detail' | 'tree' | 'image' | 'file' | 'avatar' | 'video' | 'audio' | 'formula' | 'summary' | 'autonumber' | 'composite' | 'repeater' | 'location' | 'address' | 'code' | 'json' | 'color' | 'rating' | 'slider' | 'signature' | 'qrcode' | 'progress' | 'tags' | 'vector';
+export type FieldTypeCategory = 'text' | 'number' | 'date' | 'logic' | 'selection' | 'relation' | 'media' | 'calculated' | 'advanced';
+export interface FieldTypeMeta {
+    id: FieldTypeId;
+    label: string;
+    /** Brief Chinese label for the picker / type badge. */
+    labelZh: string;
+    category: FieldTypeCategory;
+    Icon: LucideIcon;
+}
+export declare const FIELD_TYPE_META: Record<FieldTypeId, FieldTypeMeta>;
+export declare const CATEGORY_ORDER: FieldTypeCategory[];
+export declare const CATEGORY_LABEL_EN: Record<FieldTypeCategory, string>;
+/**
+ * Per-category color tone. Lets the canvas, type badges, and type
+ * picker tint a field by its category so the form is scannable at a
+ * glance (text vs number vs relation vs media …) instead of a wall of
+ * neutral-grey rows. Colour is used purely as a category *signal* —
+ * subtle tints, never loud fills — consistent with the console's
+ * content-first visual language.
+ *
+ * Class strings are written out in full (not composed) so Tailwind's
+ * JIT can see and emit every variant.
+ */
+export interface CategoryTone {
+    /** Icon stroke colour. */
+    icon: string;
+    /** Tinted type-badge classes (border + bg + text), light & dark. */
+    badge: string;
+}
+export declare const CATEGORY_TONE: Record<FieldTypeCategory, CategoryTone>;
+/** Resolve the colour tone for any field-type string (unknown → advanced). */
+export declare function resolveCategoryTone(type: unknown): CategoryTone;
+export declare const CATEGORY_LABEL_ZH: Record<FieldTypeCategory, string>;
+/** All type ids grouped by category, in category order. */
+export declare const TYPES_BY_CATEGORY: Array<{
+    category: FieldTypeCategory;
+    types: FieldTypeId[];
+}>;
+/** Resolve metadata for any type string, including unknown values. */
+export declare function resolveFieldTypeMeta(type: unknown): FieldTypeMeta;

package/dist/views/metadata-admin/previews/field-types.js

@@ -0,0 +1,97 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+import { Type, AlignLeft, AtSign, Globe, Phone, Lock, FileText, Code, Sparkles, Hash, DollarSign, Percent, Calendar, Clock, ToggleLeft, ListOrdered, ListChecks, CircleDot, CheckSquare, Link2, Workflow, Network, Image, Paperclip, UserCircle, Video, Music, Calculator, Sigma, Boxes, Repeat2, MapPin, Map, FileJson, Palette, Star, SlidersHorizontal, PenLine, QrCode, BarChart3, Tags, Atom, } from 'lucide-react';
+const M = (id, label, labelZh, category, Icon) => ({ id, label, labelZh, category, Icon });
+export const FIELD_TYPE_META = {
+    text: M('text', 'Text', '单行文本', 'text', Type),
+    textarea: M('textarea', 'Text Area', '多行文本', 'text', AlignLeft),
+    email: M('email', 'Email', '邮箱', 'text', AtSign),
+    url: M('url', 'URL', '网址', 'text', Globe),
+    phone: M('phone', 'Phone', '电话', 'text', Phone),
+    password: M('password', 'Password', '密码', 'text', Lock),
+    markdown: M('markdown', 'Markdown', 'Markdown', 'text', FileText),
+    html: M('html', 'HTML', 'HTML', 'text', Code),
+    richtext: M('richtext', 'Rich Text', '富文本', 'text', Sparkles),
+    number: M('number', 'Number', '数字', 'number', Hash),
+    currency: M('currency', 'Currency', '货币', 'number', DollarSign),
+    percent: M('percent', 'Percent', '百分比', 'number', Percent),
+    date: M('date', 'Date', '日期', 'date', Calendar),
+    datetime: M('datetime', 'Date/Time', '日期时间', 'date', Calendar),
+    time: M('time', 'Time', '时间', 'date', Clock),
+    boolean: M('boolean', 'Checkbox', '复选框', 'logic', CheckSquare),
+    toggle: M('toggle', 'Toggle', '开关', 'logic', ToggleLeft),
+    select: M('select', 'Picklist', '下拉选择', 'selection', ListOrdered),
+    multiselect: M('multiselect', 'Multi-Select', '多选', 'selection', ListChecks),
+    radio: M('radio', 'Radio', '单选', 'selection', CircleDot),
+    checkboxes: M('checkboxes', 'Checkboxes', '复选组', 'selection', ListChecks),
+    lookup: M('lookup', 'Lookup', '查找关系', 'relation', Link2),
+    master_detail: M('master_detail', 'Master-Detail', '主从关系', 'relation', Workflow),
+    tree: M('tree', 'Tree', '树形关系', 'relation', Network),
+    image: M('image', 'Image', '图片', 'media', Image),
+    file: M('file', 'File', '文件', 'media', Paperclip),
+    avatar: M('avatar', 'Avatar', '头像', 'media', UserCircle),
+    video: M('video', 'Video', '视频', 'media', Video),
+    audio: M('audio', 'Audio', '音频', 'media', Music),
+    formula: M('formula', 'Formula', '公式', 'calculated', Calculator),
+    summary: M('summary', 'Rollup', '汇总', 'calculated', Sigma),
+    autonumber: M('autonumber', 'Auto Number', '自动编号', 'calculated', Hash),
+    composite: M('composite', 'Composite', '复合字段', 'advanced', Boxes),
+    repeater: M('repeater', 'Repeater', '重复字段', 'advanced', Repeat2),
+    location: M('location', 'Location', '地理坐标', 'advanced', MapPin),
+    address: M('address', 'Address', '地址', 'advanced', Map),
+    code: M('code', 'Code', '代码', 'advanced', Code),
+    json: M('json', 'JSON', 'JSON', 'advanced', FileJson),
+    color: M('color', 'Color', '颜色', 'advanced', Palette),
+    rating: M('rating', 'Rating', '评分', 'advanced', Star),
+    slider: M('slider', 'Slider', '滑块', 'advanced', SlidersHorizontal),
+    signature: M('signature', 'Signature', '签名', 'advanced', PenLine),
+    qrcode: M('qrcode', 'QR Code', '二维码', 'advanced', QrCode),
+    progress: M('progress', 'Progress', '进度条', 'advanced', BarChart3),
+    tags: M('tags', 'Tags', '标签', 'advanced', Tags),
+    vector: M('vector', 'Vector', '向量', 'advanced', Atom),
+};
+export const CATEGORY_ORDER = [
+    'text', 'number', 'date', 'logic', 'selection', 'relation', 'media', 'calculated', 'advanced',
+];
+export const CATEGORY_LABEL_EN = {
+    text: 'Text', number: 'Number', date: 'Date & Time', logic: 'Logic',
+    selection: 'Selection', relation: 'Relation', media: 'Media',
+    calculated: 'Calculated', advanced: 'Advanced',
+};
+export const CATEGORY_TONE = {
+    text: { icon: 'text-slate-500 dark:text-slate-400', badge: 'border-slate-200 bg-slate-50 text-slate-600 dark:border-slate-700/50 dark:bg-slate-800/40 dark:text-slate-300' },
+    number: { icon: 'text-blue-600 dark:text-blue-400', badge: 'border-blue-200 bg-blue-50 text-blue-700 dark:border-blue-800/50 dark:bg-blue-950/40 dark:text-blue-300' },
+    date: { icon: 'text-violet-600 dark:text-violet-400', badge: 'border-violet-200 bg-violet-50 text-violet-700 dark:border-violet-800/50 dark:bg-violet-950/40 dark:text-violet-300' },
+    logic: { icon: 'text-amber-600 dark:text-amber-400', badge: 'border-amber-200 bg-amber-50 text-amber-700 dark:border-amber-800/50 dark:bg-amber-950/40 dark:text-amber-300' },
+    selection: { icon: 'text-teal-600 dark:text-teal-400', badge: 'border-teal-200 bg-teal-50 text-teal-700 dark:border-teal-800/50 dark:bg-teal-950/40 dark:text-teal-300' },
+    relation: { icon: 'text-indigo-600 dark:text-indigo-400', badge: 'border-indigo-200 bg-indigo-50 text-indigo-700 dark:border-indigo-800/50 dark:bg-indigo-950/40 dark:text-indigo-300' },
+    media: { icon: 'text-pink-600 dark:text-pink-400', badge: 'border-pink-200 bg-pink-50 text-pink-700 dark:border-pink-800/50 dark:bg-pink-950/40 dark:text-pink-300' },
+    calculated: { icon: 'text-emerald-600 dark:text-emerald-400', badge: 'border-emerald-200 bg-emerald-50 text-emerald-700 dark:border-emerald-800/50 dark:bg-emerald-950/40 dark:text-emerald-300' },
+    advanced: { icon: 'text-zinc-500 dark:text-zinc-400', badge: 'border-zinc-200 bg-zinc-50 text-zinc-600 dark:border-zinc-700/50 dark:bg-zinc-800/40 dark:text-zinc-300' },
+};
+/** Resolve the colour tone for any field-type string (unknown → advanced). */
+export function resolveCategoryTone(type) {
+    return CATEGORY_TONE[resolveFieldTypeMeta(type).category];
+}
+export const CATEGORY_LABEL_ZH = {
+    text: '文本', number: '数值', date: '日期/时间', logic: '逻辑',
+    selection: '选择', relation: '关系', media: '媒体',
+    calculated: '计算', advanced: '高级',
+};
+/** All type ids grouped by category, in category order. */
+export const TYPES_BY_CATEGORY = CATEGORY_ORDER.map((category) => ({
+    category,
+    types: Object.keys(FIELD_TYPE_META).filter((id) => FIELD_TYPE_META[id].category === category),
+}));
+/** Resolve metadata for any type string, including unknown values. */
+export function resolveFieldTypeMeta(type) {
+    if (typeof type === 'string' && type in FIELD_TYPE_META) {
+        return FIELD_TYPE_META[type];
+    }
+    return {
+        id: 'text',
+        label: typeof type === 'string' ? type : 'unknown',
+        labelZh: typeof type === 'string' ? type : '未知',
+        category: 'advanced',
+        Icon: Type,
+    };
+}

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

@@ -0,0 +1,88 @@
+/**
+ * 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;
+/**
+ * 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,190 @@
+// 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;
+        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 };
+}
+/**
+ * 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,88 @@
+/**
+ * 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;
+    onPointerDown?: (e: React.PointerEvent) => void;
+    onSelect?: () => void;
+    onAppend?: () => 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, onPointerDown, onSelect, onAppend, }: 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 {};