@object-ui/app-shell 6.2.3 → 7.1.0

package/dist/views/metadata-admin/previews/object-fields-bridge.js

@@ -0,0 +1,171 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+/** Set of types the designer can edit losslessly. Keep in sync with FieldDesigner. */
+const DESIGNER_TYPES = new Set([
+    'text',
+    'textarea',
+    'number',
+    'boolean',
+    'date',
+    'datetime',
+    'time',
+    'select',
+    'email',
+    'phone',
+    'url',
+    'password',
+    'currency',
+    'percent',
+    'lookup',
+    'formula',
+    'autonumber',
+    'file',
+    'image',
+    'markdown',
+    'html',
+    'color',
+    'code',
+    'location',
+    'address',
+    'rating',
+    'slider',
+]);
+/** Try to map a framework field type to a designer type; null if unsupported. */
+function mapFrameworkToDesignerType(t) {
+    if (!t)
+        return null;
+    if (DESIGNER_TYPES.has(t))
+        return t;
+    // Best-effort fallbacks for the most common "close cousin" types.
+    switch (t) {
+        case 'richtext':
+            return 'html';
+        case 'toggle':
+            return 'boolean';
+        case 'multiselect':
+        case 'checkboxes':
+        case 'radio':
+            return 'select';
+        case 'master_detail':
+        case 'tree':
+            return 'lookup';
+        default:
+            return null;
+    }
+}
+export function bridgeFromDraft(fieldsInput) {
+    const preserved = new Map();
+    const designerFields = [];
+    const originalOrder = [];
+    if (!fieldsInput || typeof fieldsInput !== 'object') {
+        return { designerFields, preserved, inputShape: 'record', originalOrder };
+    }
+    const isArray = Array.isArray(fieldsInput);
+    const inputShape = isArray ? 'array' : 'record';
+    const entries = isArray
+        ? fieldsInput.map((def, i) => [
+            String(def?.name ?? `field_${i + 1}`),
+            def,
+        ])
+        : Object.entries(fieldsInput);
+    for (const [name, def] of entries) {
+        originalOrder.push(name);
+        const mapped = mapFrameworkToDesignerType(def?.type);
+        if (mapped === null) {
+            // Quarantine — preserve as-is, do not surface in the designer.
+            preserved.set(name, def);
+            continue;
+        }
+        designerFields.push({
+            id: name, // FieldDesigner uses id as React key; using `name` is stable across edits.
+            name,
+            label: String(def?.label ?? name),
+            type: mapped,
+            required: !!def?.required,
+            unique: !!def?.unique,
+            readonly: !!def?.readonly,
+            hidden: !!def?.hidden,
+            description: typeof def?.description === 'string' ? def.description : undefined,
+            defaultValue: def?.default,
+            placeholder: typeof def?.placeholder === 'string' ? def.placeholder : undefined,
+            group: typeof def?.group === 'string' ? def.group : undefined,
+            options: Array.isArray(def?.options)
+                ? def.options.map((o) => ({
+                    label: String(o.label ?? o.value),
+                    value: String(o.value),
+                    color: o.color,
+                }))
+                : undefined,
+            referenceTo: typeof def?.reference === 'string' ? def.reference : undefined,
+            formula: typeof def?.formula === 'string' ? def.formula : undefined,
+        });
+    }
+    return { designerFields, preserved, inputShape, originalOrder };
+}
+/**
+ * Reassemble the framework-shape fields record from designer output.
+ * Preserved fields are spliced back in their original order. Newly
+ * added fields land at the end.
+ */
+export function commitToDraft(designerFields, prev) {
+    const designerByName = new Map();
+    for (const f of designerFields)
+        designerByName.set(f.name, f);
+    const writeName = (name, target) => {
+        const preserved = prev.preserved.get(name);
+        if (preserved) {
+            target[name] = preserved;
+            return;
+        }
+        const f = designerByName.get(name);
+        if (f) {
+            target[name] = serializeDesignerField(f);
+        }
+    };
+    const result = {};
+    // First emit fields in their original order to preserve user-visible
+    // ordering and keep diff noise low for unchanged drafts.
+    for (const name of prev.originalOrder) {
+        if (designerByName.has(name) || prev.preserved.has(name)) {
+            writeName(name, result);
+        }
+    }
+    // Then append any newly added designer fields (not in originalOrder).
+    for (const f of designerFields) {
+        if (!prev.originalOrder.includes(f.name)) {
+            result[f.name] = serializeDesignerField(f);
+        }
+    }
+    if (prev.inputShape === 'array') {
+        return Object.entries(result).map(([name, def]) => ({ name, ...def }));
+    }
+    return result;
+}
+function serializeDesignerField(f) {
+    const out = {
+        type: f.type,
+        label: f.label,
+    };
+    if (f.required)
+        out.required = true;
+    if (f.unique)
+        out.unique = true;
+    if (f.readonly)
+        out.readonly = true;
+    if (f.hidden)
+        out.hidden = true;
+    if (f.description)
+        out.description = f.description;
+    if (f.defaultValue !== undefined)
+        out.default = f.defaultValue;
+    if (f.placeholder)
+        out.placeholder = f.placeholder;
+    if (f.group)
+        out.group = f.group;
+    if (f.options && f.options.length > 0)
+        out.options = f.options;
+    if (f.referenceTo)
+        out.reference = f.referenceTo;
+    if (f.formula)
+        out.formula = f.formula;
+    return out;
+}

package/dist/views/metadata-admin/previews/object-fields-io.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Field-IO helpers for the form-designer canvas + inspector.
+ *
+ * `draft.fields` can be either an array `[{name, ...def}, …]` (the
+ * legacy / objectql shape) or a record `{name: def, …}` (the spec
+ * shape used in `*.object.ts`). This module reads/writes both shapes
+ * transparently and preserves arbitrary unknown properties on each
+ * field — the inspector only edits the keys it knows about.
+ *
+ * Field reorders / inserts / removes are performed on a normalized
+ * ordered list and serialized back to the input shape, so round-trips
+ * are non-destructive.
+ */
+import type { FieldTypeId } from './field-types';
+export type Shape = 'array' | 'record';
+export interface FieldEntry {
+    /** Canonical snake_case key. */
+    name: string;
+    /** Raw framework field definition (label, type, options, …). */
+    def: Record<string, unknown>;
+}
+export interface FieldsView {
+    shape: Shape;
+    entries: FieldEntry[];
+}
+/** Read draft.fields into a normalized ordered list. */
+export declare function readFields(fieldsInput: unknown): FieldsView;
+/** Serialize the ordered list back to the original shape. */
+export declare function writeFields(view: FieldsView): Record<string, unknown> | Array<Record<string, unknown>>;
+/** Find the index of a field by name. Returns -1 if not found. */
+export declare function indexOfField(view: FieldsView, name: string): number;
+/** Build a fresh field definition for the given type. */
+export declare function newField(name: string, type: FieldTypeId, label?: string): FieldEntry;
+/** Convert a snake_case name to a human-friendly Title Case label. */
+export declare function toLabel(name: string): string;
+/** Normalize an arbitrary string into a valid snake_case field name. */
+export declare function toFieldName(raw: string): string;
+/**
+ * Prefix-stable variant of {@link toFieldName} for *live keystroke* input.
+ *
+ * The strict `toFieldName` trims a trailing `_`, which makes it impossible
+ * to TYPE a multi-word identifier into a controlled input: the field's
+ * `onChange` re-normalizes on every keystroke, so the instant the user
+ * presses `_` the value is `"repair_"` -> trimmed to `"repair"` -> the
+ * underscore vanishes before the next letter arrives, yielding
+ * `"repairticket"` instead of `"repair_ticket"`. (Authors of non-Latin
+ * locales hit this hardest: their label cannot derive a Latin slug, so
+ * they MUST type the identifier by hand.)
+ *
+ * This variant keeps a single trailing `_` so typing can continue, and
+ * returns `''` (not the `'field'` placeholder) on empty input so clearing
+ * the box actually clears it. A trailing `_` is itself a valid identifier
+ * per the spec ("starts with a letter, may contain letters/digits/`_`"),
+ * so no separate commit-time trim is required for correctness; callers
+ * that need a canonical form for a *complete* string (label->name
+ * derivation, group keys) should keep using strict `toFieldName`.
+ */
+export declare function toFieldNameLoose(raw: string): string;
+/**
+ * A declared field group (a.k.a. "section"). Lives at the object's
+ * top level as `draft.fieldGroups`; individual fields opt into a group
+ * via `Field.group === FieldGroup.key`.
+ */
+export interface FieldGroup {
+    key: string;
+    label: string;
+}
+/** Read `draft.fieldGroups` into a normalized, well-typed list. */
+export declare function readGroups(fieldGroupsInput: unknown): FieldGroup[];
+/**
+ * Derive a unique snake_case group key from a human label, avoiding
+ * collisions with `existing` keys. Falls back to `group` / `group_N`.
+ */
+export declare function genGroupKey(label: string, existing: string[]): string;
+/** Append a new group with a unique key derived from `label`. */
+export declare function addGroup(groups: FieldGroup[], label: string): FieldGroup[];
+/** Rename a group's label in place (key is stable). */
+export declare function renameGroup(groups: FieldGroup[], key: string, label: string): FieldGroup[];
+/** Remove a group declaration (callers should also clear members' `group`). */
+export declare function removeGroup(groups: FieldGroup[], key: string): FieldGroup[];
+/** Move a group one slot up (-1) or down (+1), clamped to bounds. */
+export declare function moveGroup(groups: FieldGroup[], key: string, dir: -1 | 1): FieldGroup[];
+/** Strip `group === key` from every field (used after removing a group). */
+export declare function clearFieldGroup(view: FieldsView, key: string): FieldsView;
+/** Generic immutable array move helper (also used by group reorder). */
+export declare function moveArray<T>(arr: T[], from: number, to: number): T[];
+/**
+ * Group entries by their `group` property, in `fieldGroups[]` order.
+ * Fields with no group (or a group not declared in fieldGroups) land
+ * in a trailing "Ungrouped" bucket.
+ *
+ * By default empty *declared* groups are dropped to avoid chrome noise
+ * (read-only / preview). Pass `includeEmptyDeclared` while editing so a
+ * freshly-added, still-empty section stays visible as a drop target.
+ */
+export interface GroupedEntries {
+    key: string | null;
+    label: string;
+    entries: FieldEntry[];
+}
+export declare function groupEntries(view: FieldsView, fieldGroups: Array<{
+    key?: string;
+    label?: string;
+}> | undefined, opts?: {
+    includeEmptyDeclared?: boolean;
+}): GroupedEntries[];
+export type FieldDiffStatus = 'added' | 'removed' | 'changed' | 'unchanged';
+export interface FieldDiffEntry {
+    name: string;
+    status: FieldDiffStatus;
+    /** Sorted def keys that differ (only for `changed`). */
+    changedKeys: string[];
+}
+export interface FieldsDiff {
+    /** Per current-field status, keyed by field name. */
+    byName: Record<string, FieldDiffEntry>;
+    /** Baseline fields absent from the current draft (rendered as ghosts). */
+    removed: FieldEntry[];
+    counts: {
+        added: number;
+        changed: number;
+        removed: number;
+    };
+}
+/**
+ * Diff the current `fields` against a `baseline` (e.g. the last published
+ * version). Drives the canvas review mode: added / changed / removed
+ * per field. Shape-agnostic — both inputs are read via {@link readFields}.
+ */
+export declare function diffFields(baselineInput: unknown, currentInput: unknown): FieldsDiff;

package/dist/views/metadata-admin/previews/object-fields-io.js

@@ -0,0 +1,243 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+/** Read draft.fields into a normalized ordered list. */
+export function readFields(fieldsInput) {
+    if (Array.isArray(fieldsInput)) {
+        return {
+            shape: 'array',
+            entries: fieldsInput.map((raw, i) => {
+                const { name, ...rest } = raw ?? {};
+                return {
+                    name: typeof name === 'string' && name ? name : `field_${i + 1}`,
+                    def: rest,
+                };
+            }),
+        };
+    }
+    if (fieldsInput && typeof fieldsInput === 'object') {
+        return {
+            shape: 'record',
+            entries: Object.entries(fieldsInput).map(([name, def]) => ({ name, def: { ...(def ?? {}) } })),
+        };
+    }
+    return { shape: 'record', entries: [] };
+}
+/** Serialize the ordered list back to the original shape. */
+export function writeFields(view) {
+    if (view.shape === 'array') {
+        return view.entries.map((e) => ({ name: e.name, ...e.def }));
+    }
+    const out = {};
+    for (const e of view.entries)
+        out[e.name] = e.def;
+    return out;
+}
+/** Find the index of a field by name. Returns -1 if not found. */
+export function indexOfField(view, name) {
+    return view.entries.findIndex((e) => e.name === name);
+}
+/** Build a fresh field definition for the given type. */
+export function newField(name, type, label) {
+    const def = { type, label: label ?? toLabel(name) };
+    // Picklist-style fields start with no options; the OptionsEditor shows a
+    // blank input row locally and only persists rows once they have a value, so
+    // an unfilled row never trips the spec's identifier validation.
+    if (type === 'select' || type === 'multiselect' || type === 'radio' || type === 'checkboxes') {
+        def.options = [];
+    }
+    return { name, def };
+}
+/** Convert a snake_case name to a human-friendly Title Case label. */
+export function toLabel(name) {
+    if (!name)
+        return '';
+    return name
+        .split('_')
+        .filter(Boolean)
+        .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+        .join(' ');
+}
+/** Normalize an arbitrary string into a valid snake_case field name. */
+export function toFieldName(raw) {
+    const lower = raw.trim().toLowerCase();
+    const sanitized = lower
+        .replace(/[^a-z0-9]+/g, '_')
+        .replace(/^_+|_+$/g, '')
+        .replace(/_{2,}/g, '_');
+    if (!sanitized)
+        return 'field';
+    if (!/^[a-z_]/.test(sanitized))
+        return `f_${sanitized}`;
+    return sanitized;
+}
+/**
+ * Prefix-stable variant of {@link toFieldName} for *live keystroke* input.
+ *
+ * The strict `toFieldName` trims a trailing `_`, which makes it impossible
+ * to TYPE a multi-word identifier into a controlled input: the field's
+ * `onChange` re-normalizes on every keystroke, so the instant the user
+ * presses `_` the value is `"repair_"` -> trimmed to `"repair"` -> the
+ * underscore vanishes before the next letter arrives, yielding
+ * `"repairticket"` instead of `"repair_ticket"`. (Authors of non-Latin
+ * locales hit this hardest: their label cannot derive a Latin slug, so
+ * they MUST type the identifier by hand.)
+ *
+ * This variant keeps a single trailing `_` so typing can continue, and
+ * returns `''` (not the `'field'` placeholder) on empty input so clearing
+ * the box actually clears it. A trailing `_` is itself a valid identifier
+ * per the spec ("starts with a letter, may contain letters/digits/`_`"),
+ * so no separate commit-time trim is required for correctness; callers
+ * that need a canonical form for a *complete* string (label->name
+ * derivation, group keys) should keep using strict `toFieldName`.
+ */
+export function toFieldNameLoose(raw) {
+    const sanitized = raw
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '_')
+        .replace(/^_+/g, '') // trim leading only -- a trailing `_` must survive
+        .replace(/_{2,}/g, '_');
+    if (!sanitized)
+        return '';
+    if (!/^[a-z_]/.test(sanitized))
+        return `f_${sanitized}`;
+    return sanitized;
+}
+/** Read `draft.fieldGroups` into a normalized, well-typed list. */
+export function readGroups(fieldGroupsInput) {
+    if (!Array.isArray(fieldGroupsInput))
+        return [];
+    return fieldGroupsInput
+        .filter((g) => !!g && typeof g === 'object')
+        .map((g) => ({
+        key: typeof g.key === 'string' ? g.key : '',
+        label: typeof g.label === 'string' ? g.label : '',
+    }))
+        .filter((g) => g.key);
+}
+/**
+ * Derive a unique snake_case group key from a human label, avoiding
+ * collisions with `existing` keys. Falls back to `group` / `group_N`.
+ */
+export function genGroupKey(label, existing) {
+    // toFieldName() bottoms out at "field"; for a *group* key prefer
+    // "group" when the label carries no usable alphanumerics.
+    const base = /[a-z0-9]/i.test(label) ? toFieldName(label) : 'group';
+    if (!existing.includes(base))
+        return base;
+    let i = 2;
+    while (existing.includes(`${base}_${i}`))
+        i += 1;
+    return `${base}_${i}`;
+}
+/** Append a new group with a unique key derived from `label`. */
+export function addGroup(groups, label) {
+    const clean = label.trim() || 'New section';
+    const key = genGroupKey(clean, groups.map((g) => g.key));
+    return [...groups, { key, label: clean }];
+}
+/** Rename a group's label in place (key is stable). */
+export function renameGroup(groups, key, label) {
+    const clean = label.trim();
+    if (!clean)
+        return groups;
+    return groups.map((g) => (g.key === key ? { ...g, label: clean } : g));
+}
+/** Remove a group declaration (callers should also clear members' `group`). */
+export function removeGroup(groups, key) {
+    return groups.filter((g) => g.key !== key);
+}
+/** Move a group one slot up (-1) or down (+1), clamped to bounds. */
+export function moveGroup(groups, key, dir) {
+    const idx = groups.findIndex((g) => g.key === key);
+    if (idx < 0)
+        return groups;
+    const to = idx + dir;
+    if (to < 0 || to >= groups.length)
+        return groups;
+    return moveArray(groups, idx, to);
+}
+/** Strip `group === key` from every field (used after removing a group). */
+export function clearFieldGroup(view, key) {
+    return {
+        shape: view.shape,
+        entries: view.entries.map((e) => e.def.group === key ? { name: e.name, def: { ...e.def, group: undefined } } : e),
+    };
+}
+/** Generic immutable array move helper (also used by group reorder). */
+export function moveArray(arr, from, to) {
+    const next = arr.slice();
+    const [item] = next.splice(from, 1);
+    next.splice(to, 0, item);
+    return next;
+}
+export function groupEntries(view, fieldGroups, opts) {
+    const declared = Array.isArray(fieldGroups) ? fieldGroups.filter((g) => typeof g?.key === 'string') : [];
+    const buckets = new Map();
+    for (const g of declared) {
+        buckets.set(g.key, { key: g.key, label: String(g.label ?? g.key), entries: [] });
+    }
+    const declaredKeys = new Set(declared.map((g) => g.key));
+    for (const e of view.entries) {
+        const g = typeof e.def.group === 'string' ? e.def.group : null;
+        if (g && declaredKeys.has(g)) {
+            buckets.get(g).entries.push(e);
+        }
+        else {
+            if (!buckets.has(null))
+                buckets.set(null, { key: null, label: 'Ungrouped', entries: [] });
+            buckets.get(null).entries.push(e);
+        }
+    }
+    const includeEmpty = !!opts?.includeEmptyDeclared;
+    // Drop empty declared buckets unless asked to keep them (edit mode).
+    // The implicit "Ungrouped" bucket is only created when populated, so
+    // it never shows empty.
+    return Array.from(buckets.values()).filter((b) => b.entries.length > 0 || (includeEmpty && b.key !== null));
+}
+/** Stable equality for field-def values (small JSON — order-sensitive is fine). */
+function valueEqual(a, b) {
+    if (a === b)
+        return true;
+    return JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
+}
+/** Def keys whose values differ between two field definitions, sorted. */
+function changedDefKeys(a, b) {
+    const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+    const out = [];
+    for (const k of keys)
+        if (!valueEqual(a[k], b[k]))
+            out.push(k);
+    return out.sort();
+}
+/**
+ * Diff the current `fields` against a `baseline` (e.g. the last published
+ * version). Drives the canvas review mode: added / changed / removed
+ * per field. Shape-agnostic — both inputs are read via {@link readFields}.
+ */
+export function diffFields(baselineInput, currentInput) {
+    const base = readFields(baselineInput);
+    const cur = readFields(currentInput);
+    const baseByName = new Map(base.entries.map((e) => [e.name, e]));
+    const curNames = new Set(cur.entries.map((e) => e.name));
+    const byName = {};
+    let added = 0;
+    let changed = 0;
+    for (const e of cur.entries) {
+        const b = baseByName.get(e.name);
+        if (!b) {
+            byName[e.name] = { name: e.name, status: 'added', changedKeys: [] };
+            added += 1;
+            continue;
+        }
+        const keys = changedDefKeys(b.def, e.def);
+        if (keys.length) {
+            byName[e.name] = { name: e.name, status: 'changed', changedKeys: keys };
+            changed += 1;
+        }
+        else {
+            byName[e.name] = { name: e.name, status: 'unchanged', changedKeys: [] };
+        }
+    }
+    const removed = base.entries.filter((e) => !curNames.has(e.name));
+    return { byName, removed, counts: { added, changed, removed: removed.length } };
+}

package/dist/views/metadata-admin/previews/screen-spec.d.ts

@@ -0,0 +1,43 @@
+/**
+ * screen-spec — pure helpers that map a flow `screen` node's authored `config`
+ * onto the runtime `ScreenSpec` (the contract {@link ScreenView} renders), plus
+ * `{var}` interpolation for the title/description and `visibleWhen` field
+ * gating. Kept framework-free so {@link ScreenPreview} stays a thin component
+ * and these stay unit-testable.
+ */
+import type { ScreenSpec } from '../../ScreenView';
+/** Minimal node shape the preview needs (id + authored config). */
+export interface ScreenPreviewNode {
+    id: string;
+    label?: string;
+    config?: Record<string, unknown>;
+}
+/**
+ * Interpolate `{var}` references, mirroring the simulator's `{var}` syntax
+ * (flow-simulator.ts). Known vars are substituted; unknown refs stay literal so
+ * the author still sees the dependency in the design preview.
+ */
+export declare function interpolate(text: string | undefined, vars: Record<string, unknown> | undefined): string;
+/**
+ * A field's `visibleWhen` gate, evaluated against the current variables using
+ * the SAME evaluator the simulator uses for edge conditions (so the preview
+ * agrees with the simulator). Real metadata mixes `{var}` and bare-var styles
+ * (e.g. `{createOpportunity} == true`, `stage == "review"`), so brace
+ * placeholders are normalised to bare identifiers first.
+ *
+ * Fail-OPEN: a missing condition, an unparseable one, or one that references a
+ * not-yet-set variable (the inspector has no run state) keeps the field
+ * visible — the design preview never hides a configured field just because it
+ * lacks the data to decide. With live run state (the simulator) it gates
+ * faithfully: `createOpportunity == false` hides the field.
+ */
+export declare function isFieldVisibleWhen(visibleWhen: unknown, variables: Record<string, unknown> | undefined): boolean;
+/** Count of authored field rows hidden by their `visibleWhen` against `variables`. */
+export declare function hiddenFieldCount(node: ScreenPreviewNode, variables: Record<string, unknown> | undefined): number;
+/**
+ * Map a screen node's authored `config` onto the runtime `ScreenSpec` — the
+ * same keys the engine's `screen` executor reads (title / description / fields
+ * / objectName / mode / defaults / idVariable). `fields` are gated by their
+ * `visibleWhen` against `variables` (omit `variables` to keep every field).
+ */
+export declare function buildScreenSpec(node: ScreenPreviewNode, variables?: Record<string, unknown>): ScreenSpec;