@object-ui/app-shell 6.2.2 → 7.0.0

package/dist/views/metadata-admin/inspectors/json-schema-to-fields.js

@@ -0,0 +1,227 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+const REFERENCE_KINDS = new Set([
+    'object',
+    'object-field',
+    'flow',
+    'role',
+    'node',
+    'user',
+    'team',
+    'queue',
+    'department',
+    'connector',
+    'email-template',
+]);
+/**
+ * Read a valid `xRef` annotation off a schema node, or undefined. Accepts both
+ * the static shape (`{ kind }`) and the polymorphic shape (`{ kindFrom, map }`),
+ * validating every referenced kind against {@link REFERENCE_KINDS} so an unknown
+ * kind degrades to free text rather than a broken picker.
+ */
+function refOf(node) {
+    const x = node.xRef;
+    if (!x || typeof x !== 'object')
+        return undefined;
+    const objectSource = typeof x.objectSource === 'string' && x.objectSource ? { objectSource: x.objectSource } : {};
+    // Polymorphic: kindFrom + a map of discriminator value → kind.
+    if (typeof x.kindFrom === 'string' && x.kindFrom && x.map && typeof x.map === 'object') {
+        const map = {};
+        for (const [disc, kind] of Object.entries(x.map)) {
+            if (typeof kind === 'string' && REFERENCE_KINDS.has(kind))
+                map[disc] = kind;
+        }
+        if (Object.keys(map).length === 0)
+            return undefined;
+        return { kindFrom: x.kindFrom, map, ...objectSource };
+    }
+    // Static: a single concrete kind.
+    if (typeof x.kind === 'string' && REFERENCE_KINDS.has(x.kind)) {
+        return { kind: x.kind, ...objectSource };
+    }
+    return undefined;
+}
+/** "approvalStatusField" → "Approval Status Field"; "approve" → "Approve". */
+export function humanizeKey(key) {
+    const spaced = key
+        .replace(/[_-]+/g, ' ')
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .trim();
+    if (!spaced)
+        return key;
+    return spaced
+        .split(/\s+/)
+        .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+        .join(' ');
+}
+function isObject(v) {
+    return !!v && typeof v === 'object' && !Array.isArray(v);
+}
+/** The JSON Schema `type`, normalized to a single string (first non-null of a union). */
+function schemaType(node) {
+    if (Array.isArray(node.type))
+        return node.type.find((t) => t !== 'null');
+    if (typeof node.type === 'string')
+        return node.type;
+    // Infer from shape when `type` is omitted (common with enum-only schemas).
+    if (Array.isArray(node.enum))
+        return 'string';
+    if (node.properties)
+        return 'object';
+    if (node.items)
+        return 'array';
+    return undefined;
+}
+/** Build `{ value, label }` options from a string enum. */
+function enumOptions(values) {
+    return values
+        .filter((v) => typeof v === 'string')
+        .map((v) => ({ value: v, label: humanizeKey(v) }));
+}
+/** Default coerced to the string form the inspector's `defaultValue` expects. */
+function defaultString(node) {
+    if (node.default === undefined || node.default === null)
+        return undefined;
+    if (typeof node.default === 'boolean')
+        return String(node.default);
+    if (typeof node.default === 'number')
+        return String(node.default);
+    if (typeof node.default === 'string')
+        return node.default;
+    return undefined;
+}
+/** Scalar (non-object, non-array) → field kind. */
+function scalarKind(node) {
+    if (Array.isArray(node.enum))
+        return 'select';
+    const t = schemaType(node);
+    if (t === 'boolean')
+        return 'boolean';
+    if (t === 'number' || t === 'integer')
+        return 'number';
+    if (t === 'string')
+        return node.format === 'multiline' ? 'textarea' : 'text';
+    return undefined;
+}
+/** Derive `objectList` columns from an item object's properties. */
+function columnsFor(item) {
+    const props = item.properties ?? {};
+    const cols = [];
+    for (const [key, prop] of Object.entries(props)) {
+        if (!isObject(prop))
+            continue;
+        const t = schemaType(prop);
+        let kind;
+        let options;
+        // A reference annotation wins over the plain scalar mapping — the column is
+        // a typed reference and gets a picker (static or polymorphic via kindFrom).
+        const ref = refOf(prop);
+        if (ref) {
+            kind = 'reference';
+        }
+        else if (Array.isArray(prop.enum)) {
+            kind = 'select';
+            options = enumOptions(prop.enum);
+        }
+        else if (t === 'boolean') {
+            kind = 'boolean';
+        }
+        else {
+            kind = 'text';
+        }
+        cols.push({
+            key,
+            label: prop.title || humanizeKey(key),
+            kind,
+            ...(options ? { options } : {}),
+            ...(ref ? { ref } : {}),
+            // Columns have no help slot — surface the schema description as a hint.
+            ...(prop.description ? { placeholder: prop.description } : {}),
+        });
+    }
+    return cols;
+}
+/** Common field metadata derived from a schema node. */
+function meta(node, key) {
+    return {
+        label: node.title || humanizeKey(key),
+        ...(node.description ? { help: node.description } : {}),
+        ...(defaultString(node) ? { defaultValue: defaultString(node) } : {}),
+    };
+}
+/**
+ * Convert a published config JSON Schema (an object schema) into the inspector's
+ * `FlowConfigField[]`. Property order is preserved. Returns `null` when the
+ * schema is not a usable object schema, so callers fall back to their hardcoded
+ * field group.
+ */
+export function jsonSchemaToFlowFields(schema) {
+    if (!isObject(schema) || schemaType(schema) !== 'object' || !isObject(schema.properties)) {
+        return null;
+    }
+    const fields = [];
+    for (const [key, prop] of Object.entries(schema.properties)) {
+        if (!isObject(prop))
+            continue;
+        const t = schemaType(prop);
+        // ── arrays ────────────────────────────────────────────────────────────
+        if (t === 'array') {
+            const item = isObject(prop.items) ? prop.items : undefined;
+            const itemType = item ? schemaType(item) : undefined;
+            if (item && itemType === 'object' && isObject(item.properties)) {
+                fields.push({ id: key, path: ['config', key], kind: 'objectList', columns: columnsFor(item), ...meta(prop, key) });
+            }
+            else if (itemType === 'string') {
+                fields.push({ id: key, path: ['config', key], kind: 'stringList', ...meta(prop, key) });
+            }
+            // arrays of anything else fall through to the Advanced block.
+            continue;
+        }
+        // ── nested object → flatten one level under config.<key>.* ──────────────
+        if (t === 'object' && isObject(prop.properties)) {
+            const subProps = Object.entries(prop.properties).filter(([, p]) => isObject(p));
+            // A boolean `enabled` toggle gates the rest of the group (mirrors the SLA
+            // escalation UX): the group's other fields reveal only when it is on.
+            const hasEnabled = subProps.some(([k, p]) => k === 'enabled' && schemaType(p) === 'boolean');
+            for (const [subKey, subProp] of subProps) {
+                const sp = subProp;
+                const subRef = refOf(sp);
+                const kind = subRef ? 'reference' : scalarKind(sp);
+                if (!kind)
+                    continue; // deeper nesting / unsupported → Advanced block
+                const id = `${key}.${subKey}`;
+                const isGate = hasEnabled && subKey === 'enabled';
+                const field = {
+                    id,
+                    path: ['config', key, subKey],
+                    kind,
+                    // The gate adopts the parent group's label; siblings keep their own.
+                    ...(isGate ? { label: prop.title || humanizeKey(key), ...(prop.description ? { help: prop.description } : {}), ...(defaultString(sp) ? { defaultValue: defaultString(sp) } : {}) } : meta(sp, subKey)),
+                    ...(subRef ? { ref: subRef } : {}),
+                    ...(kind === 'select' && Array.isArray(sp.enum) ? { options: enumOptions(sp.enum) } : {}),
+                    ...(hasEnabled && !isGate ? { showWhen: { field: `${key}.enabled`, equals: ['true'] } } : {}),
+                };
+                fields.push(field);
+            }
+            continue;
+        }
+        // ── scalars ─────────────────────────────────────────────────────────────
+        // A reference annotation (xRef) wins over the plain scalar mapping — the
+        // string is really a typed reference and gets a picker.
+        const ref = refOf(prop);
+        if (ref) {
+            fields.push({ id: key, path: ['config', key], kind: 'reference', ref, ...meta(prop, key) });
+            continue;
+        }
+        const kind = scalarKind(prop);
+        if (!kind)
+            continue; // unrepresentable → Advanced block
+        fields.push({
+            id: key,
+            path: ['config', key],
+            kind,
+            ...meta(prop, key),
+            ...(kind === 'select' && Array.isArray(prop.enum) ? { options: enumOptions(prop.enum) } : {}),
+        });
+    }
+    return fields;
+}

package/dist/views/metadata-admin/inspectors/useDatasetFields.d.ts

@@ -0,0 +1,72 @@
+export interface DatasetObjectOption {
+    /** Object API name (snake_case) — what `dataset.object` stores. */
+    name: string;
+    /** Human label (falls back to the name). */
+    label: string;
+}
+export interface DatasetRelationship {
+    /** Relationship field name — what goes in `dataset.include`. */
+    name: string;
+    /** Human label (falls back to the name). */
+    label: string;
+    /** Target object the relationship points at (for `rel.field` paths). */
+    referenceTo?: string;
+}
+export interface DatasetFieldOption {
+    /** Field path: a base field name or `relationship.field`. */
+    value: string;
+    /** Human label (falls back to the value). */
+    label: string;
+    /** Raw framework field type (e.g. 'text', 'currency', 'lookup'). */
+    type?: string;
+    /** Group heading: the base object label, or `rel → target`. */
+    group: string;
+}
+export interface DatasetFieldCatalog {
+    relationships: DatasetRelationship[];
+    fieldOptions: DatasetFieldOption[];
+    loading: boolean;
+}
+/** Resolve a string | i18n-object label down to a display string. */
+export declare function resolveLabel(label: unknown, fallback: string): string;
+/** Read a lookup/master_detail field's target object from its raw def. */
+export declare function resolveReferenceTo(def: Record<string, unknown>): string | undefined;
+/** Map a framework field type onto a dataset dimension type. */
+export declare function fieldTypeToDimensionType(type: string | undefined): string;
+export interface NormalizedObject {
+    label: string;
+    fields: Array<{
+        name: string;
+        label: string;
+        type?: string;
+        def: Record<string, unknown>;
+    }>;
+    relationships: DatasetRelationship[];
+}
+/** Normalize a raw object metadata doc into label + fields + relationships. */
+export declare function normalizeObject(doc: Record<string, unknown> | null | undefined, name: string): NormalizedObject;
+/**
+ * Build the flat `field` / `relationship.field` option list from the base
+ * object and the included relationships' (already-fetched) target objects.
+ */
+export declare function buildFieldOptions(base: NormalizedObject, include: string[], targets: Record<string, NormalizedObject>): DatasetFieldOption[];
+/** Recursively test whether a metadata doc references `datasetName` via a `dataset` key. */
+export declare function referencesDataset(doc: unknown, datasetName: string): boolean;
+/** Every object as `{ name, label }`, sorted by label. Fetched once. */
+export declare function useObjectOptions(): {
+    options: DatasetObjectOption[];
+    loading: boolean;
+};
+/**
+ * The base object's relationships (join allowlist) + a flat `field` /
+ * `relationship.field` option list. Refetches when `object` or the set of
+ * included relationships changes.
+ */
+export declare function useDatasetFieldCatalog(object: string | undefined, include: string[]): DatasetFieldCatalog;
+export interface DatasetUsage {
+    reports: number;
+    dashboards: number;
+    loading: boolean;
+}
+/** Reverse lineage: how many reports / dashboards bind this dataset by name. */
+export declare function useDatasetUsage(name: string | undefined): DatasetUsage;

package/dist/views/metadata-admin/mergeServerFields.d.ts

@@ -0,0 +1,65 @@
+/**
+ * mergeServerFields — completes the cross-repo spec-skew root-cure for the
+ * CURATED inspectors (report / dashboard / view).
+ *
+ * Background: the curated "home" inspectors derive their authoring form from
+ * the BUNDLED `@objectstack/spec` (`getReportForm()`/`getReportSchema()` …).
+ * When the running server adds new fields to a metadata type (e.g. report's
+ * `dataset`/`rows`/`values`) before objectui bumps its bundled spec, those
+ * fields exist in the live server schema (`/meta/types` → `entry.schema`) but
+ * NOT in the bundled one — so the curated form can't render them. They were
+ * only reachable via the raw "source" tab / API.
+ *
+ * `clientValidation.ts` already stopped the bundled spec from being STRICTER
+ * than the server (no more false "required" banners). This is the symmetric
+ * other half: let the bundled-derived FORM be a SUPERSET of the bundled spec
+ * by grafting in any server-only top-level properties, so new fields become
+ * directly editable in the right-hand curated form.
+ *
+ * It is purely ADDITIVE and lag-tolerant:
+ *   - Only fields the server has and the bundle lacks are added; existing
+ *     bundled fields, ordering, sections and `visibleOn` predicates are
+ *     untouched.
+ *   - When the bundle catches up (the field appears in `bundledSchema`), the
+ *     merge becomes a no-op for that field automatically — no shim to remove.
+ *   - When no server schema is available (offline/older server), it returns
+ *     the bundled `{schema, form}` verbatim.
+ *
+ * SchemaForm renders ONLY the fields a `form` declares (see SchemaForm's
+ * sectioned path), so new properties must be added to BOTH the schema's
+ * `properties` AND the form (as a trailing section) to actually surface.
+ */
+import type { FormViewSpec } from './SchemaForm';
+type JsonSchema = Record<string, any>;
+export interface MergeServerFieldsArgs {
+    /** Bundled-spec JSONSchema for the whole document (may be undefined). */
+    bundledSchema: JsonSchema | undefined;
+    /** Bundled-spec authoring FormView (may be undefined). */
+    bundledForm: FormViewSpec | undefined;
+    /**
+     * Live server JSONSchema for this type (`RichMetadataTypeEntry.schema`).
+     * For nested documents (view), pass the relevant sub-schema (e.g.
+     * `serverSchema.properties.list`).
+     */
+    serverSchema: JsonSchema | undefined;
+    /**
+     * Top-level fields the curated inspector renders itself (e.g. report's
+     * `objectName`/`columns`/`label`) plus identity (`name`). These are never
+     * grafted into the spec form even if the server adds/keeps them, so they
+     * are not double-edited.
+     */
+    excludeFields: Set<string>;
+    /** Localized title for the trailing "new server fields" section. */
+    sectionTitle: string;
+}
+export interface MergeServerFieldsResult {
+    schema: JsonSchema | undefined;
+    form: FormViewSpec | undefined;
+}
+/**
+ * Return `{schema, form}` with server-only top-level properties grafted onto
+ * the bundled pair. No-op (returns the bundled pair) when there is nothing to
+ * add or no server schema to read.
+ */
+export declare function mergeServerFields({ bundledSchema, bundledForm, serverSchema, excludeFields, sectionTitle, }: MergeServerFieldsArgs): MergeServerFieldsResult;
+export {};

package/dist/views/metadata-admin/mergeServerFields.js

@@ -0,0 +1,56 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+/** Collect every field name a FormView's sections already declare. */
+function formDeclaredFields(form) {
+    const out = new Set();
+    for (const s of form?.sections ?? []) {
+        for (const f of s.fields ?? []) {
+            out.add(typeof f === 'string' ? f : f?.field);
+        }
+    }
+    return out;
+}
+/**
+ * Return `{schema, form}` with server-only top-level properties grafted onto
+ * the bundled pair. No-op (returns the bundled pair) when there is nothing to
+ * add or no server schema to read.
+ */
+export function mergeServerFields({ bundledSchema, bundledForm, serverSchema, excludeFields, sectionTitle, }) {
+    if (!bundledSchema)
+        return { schema: bundledSchema, form: bundledForm };
+    const serverProps = serverSchema?.properties;
+    if (!serverProps || typeof serverProps !== 'object') {
+        return { schema: bundledSchema, form: bundledForm };
+    }
+    const bundledProps = (bundledSchema.properties ?? {});
+    const alreadyShown = formDeclaredFields(bundledForm);
+    // Server-only fields = on the server, absent from the bundled schema, not
+    // curated-owned, and not already declared by the bundled form.
+    const newKeys = Object.keys(serverProps).filter((k) => !(k in bundledProps) &&
+        !excludeFields.has(k) &&
+        !alreadyShown.has(k));
+    if (newKeys.length === 0)
+        return { schema: bundledSchema, form: bundledForm };
+    // ── additive schema merge (shallow clone; bundled defs win on conflict) ──
+    const mergedSchema = {
+        ...bundledSchema,
+        properties: { ...bundledProps },
+    };
+    for (const k of newKeys) {
+        if (!(k in mergedSchema.properties))
+            mergedSchema.properties[k] = serverProps[k];
+    }
+    // ── additive form merge — append a trailing section with the new fields ──
+    // When the bundle ships no form at all, SchemaForm falls back to a flat
+    // property list (which already renders every property), so we only need to
+    // synthesise a form when one exists to preserve its curated layout.
+    let mergedForm = bundledForm;
+    if (bundledForm && typeof bundledForm === 'object') {
+        const clone = JSON.parse(JSON.stringify(bundledForm));
+        clone.sections = [
+            ...(clone.sections ?? []),
+            { label: sectionTitle, fields: newKeys.map((field) => ({ field })) },
+        ];
+        mergedForm = clone;
+    }
+    return { schema: mergedSchema, form: mergedForm };
+}

package/dist/views/metadata-admin/preview-registry.d.ts

@@ -19,6 +19,20 @@
  * empty "preview not available" surface is shown.
  */
 import type { ComponentType } from 'react';
+/**
+ * Identifies a sub-element selected inside a preview surface.
+ *
+ *   { kind: 'widget', id: 'metric_revenue', label: 'Revenue (KPI)' }
+ *
+ * `kind` is preview-defined (dashboard uses 'widget'; page may use
+ * 'block'; view may use 'column'). The host (`ResourceEditPage`) is
+ * agnostic — it only forwards the value to the registered inspector.
+ */
+export interface MetadataSelection {
+    kind: string;
+    id: string;
+    label?: string;
+}
 export interface MetadataPreviewProps {
     /** The metadata type, e.g. 'page', 'dashboard'. */
     type: string;
@@ -29,6 +43,47 @@ export interface MetadataPreviewProps {
      * as immutable and untrusted (validation may be in progress).
      */
     draft: Record<string, unknown>;
+    /**
+     * Optional: apply a shallow patch to the draft. When omitted, the
+     * preview surface is read-only (legacy behavior). When provided, the
+     * preview may offer in-place edits (Airtable-style column management,
+     * inline rename, etc.) — implementations should respect `editing`
+     * before exposing mutating affordances.
+     */
+    onPatch?: (patch: Record<string, unknown>) => void;
+    /**
+     * Optional: the last *published* version of this item, for previews
+     * that offer a review/diff mode (e.g. the object designer diffing an
+     * AI-authored draft against what's live). Undefined in create mode or
+     * when no published baseline exists.
+     */
+    baseline?: Record<string, unknown>;
+    /**
+     * Optional: whether the host is in edit mode. Previews that ship
+     * editing affordances should render them in a disabled/hidden state
+     * when `editing === false`.
+     */
+    editing?: boolean;
+    /**
+     * Optional: BCP-47 locale code (e.g. 'en', 'zh-CN') for previews that
+     * render localized labels. Defaults are derived from the host locale.
+     */
+    locale?: string;
+    /**
+     * Optional: the currently selected sub-element (e.g. a dashboard
+     * widget). Previews use this to render selection chrome (highlight
+     * ring, keyboard focus) and the host uses it to swap the inspector
+     * to a scoped sub-form. `null` means "nothing selected → show the
+     * top-level form".
+     */
+    selection?: MetadataSelection | null;
+    /**
+     * Optional: notify the host that the user picked (or cleared) a
+     * sub-element. Pair with {@link MetadataPreviewProps.selection} and
+     * a registered inspector (`registerMetadataInspector`) to get the
+     * "click widget → edit widget in the right panel" pattern.
+     */
+    onSelectionChange?: (selection: MetadataSelection | null) => void;
 }
 export type MetadataPreview = ComponentType<MetadataPreviewProps>;
 /**

package/dist/views/metadata-admin/previews/ActionPreview.d.ts

@@ -0,0 +1,25 @@
+/**
+ * ActionPreview — read-only summary of an Action metadata draft.
+ *
+ * Actions are the configurable buttons / menu items / shortcuts a
+ * record or list surfaces. The preview shows:
+ *
+ *   1. A faux button rendered using the action's `variant`, `icon`,
+ *      and `label` so authors can see the visual weight before they
+ *      ship it (primary buttons are highlighted, danger turns red,
+ *      icon-only actions render a compact icon button).
+ *   2. A metadata strip: type, target, locations, shortcut, bulk
+ *      flag, AI exposure, refreshAfter, confirmText.
+ *   3. A params table when the action prompts the user — this is the
+ *      modal/drawer it would open on click. We render it as a static
+ *      preview, not an interactive form, because previews must be
+ *      side-effect free.
+ *   4. A "what happens on click" callout that describes the resolved
+ *      handler in plain language (e.g. "POST ${target}", "open form
+ *      ${target}", "run script ${target}").
+ *   5. A resultDialog mock when configured (TOTP / backup-codes-style
+ *      reveal dialogs).
+ */
+import * as React from 'react';
+import type { MetadataPreviewProps } from '../preview-registry';
+export declare function ActionPreview({ name, draft }: MetadataPreviewProps): React.JSX.Element;