@object-ui/app-shell 6.1.0 → 6.2.0

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

@@ -0,0 +1,150 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+/**
+ * Tiny predicate evaluator for FormView `visibleOn` expressions.
+ *
+ * This is an interim stand-in for the full CEL runtime
+ * (`@objectstack/formula`) — we keep it intentionally small so the
+ * Setup admin engine has zero new runtime dependencies. When CEL is
+ * unified across the platform (ROADMAP M9), swap `evaluatePredicate`
+ * for the real CEL evaluator without touching SchemaForm.tsx.
+ *
+ * Supported subset (covers everything used in spec `*.form.ts` today):
+ *   - `path == 'literal'`       string equality
+ *   - `path != 'literal'`       string inequality
+ *   - `path == 123`             number equality
+ *   - `path == true|false`      boolean equality
+ *   - `path in ['a','b']`       membership
+ *   - `!path`                   negation (truthy)
+ *   - `path`                    truthy check
+ *   - `path && expr`            conjunction
+ *   - `path || expr`            disjunction
+ *
+ * Paths support dot notation: `data.type`, `data.config.kind`.
+ *
+ * On any parse error → returns `true` (fail-open): better to show a
+ * field than to silently hide it.
+ */
+export function evaluatePredicate(expr, ctx) {
+    if (expr == null)
+        return true;
+    const source = typeof expr === 'string' ? expr : expr.source;
+    if (!source)
+        return true;
+    try {
+        return evalExpr(source.trim(), ctx);
+    }
+    catch {
+        return true;
+    }
+}
+function evalExpr(expr, ctx) {
+    // Handle || (lowest precedence)
+    const orParts = splitTopLevel(expr, '||');
+    if (orParts.length > 1) {
+        return orParts.some((p) => evalExpr(p.trim(), ctx));
+    }
+    // Handle &&
+    const andParts = splitTopLevel(expr, '&&');
+    if (andParts.length > 1) {
+        return andParts.every((p) => evalExpr(p.trim(), ctx));
+    }
+    // Handle negation
+    if (expr.startsWith('!')) {
+        return !evalExpr(expr.slice(1).trim(), ctx);
+    }
+    // Handle 'in'
+    const inMatch = expr.match(/^(.+?)\s+in\s+(\[.*\])$/);
+    if (inMatch) {
+        const left = resolveValue(inMatch[1].trim(), ctx);
+        const right = parseLiteral(inMatch[2]);
+        return Array.isArray(right) && right.includes(left);
+    }
+    // Handle == / != (CEL-style loose equality: null == undefined)
+    const eqMatch = expr.match(/^(.+?)\s*(==|!=)\s*(.+)$/);
+    if (eqMatch) {
+        const left = resolveValue(eqMatch[1].trim(), ctx);
+        const right = parseLiteral(eqMatch[3].trim());
+        const nullish = (v) => v === null || v === undefined;
+        const equal = nullish(left) && nullish(right) ? true : left === right;
+        return eqMatch[2] === '==' ? equal : !equal;
+    }
+    // Bare truthy check
+    return Boolean(resolveValue(expr, ctx));
+}
+function splitTopLevel(expr, op) {
+    const out = [];
+    let depth = 0;
+    let inStr = null;
+    let buf = '';
+    for (let i = 0; i < expr.length; i++) {
+        const ch = expr[i];
+        if (inStr) {
+            buf += ch;
+            if (ch === inStr && expr[i - 1] !== '\\')
+                inStr = null;
+            continue;
+        }
+        if (ch === "'" || ch === '"') {
+            inStr = ch;
+            buf += ch;
+            continue;
+        }
+        if (ch === '(' || ch === '[')
+            depth++;
+        else if (ch === ')' || ch === ']')
+            depth--;
+        if (depth === 0 &&
+            expr.slice(i, i + op.length) === op &&
+            // Not a sub-operator (e.g. == when looking for =)
+            expr[i + op.length] !== '=') {
+            out.push(buf);
+            buf = '';
+            i += op.length - 1;
+            continue;
+        }
+        buf += ch;
+    }
+    if (buf)
+        out.push(buf);
+    return out;
+}
+function resolveValue(path, ctx) {
+    // Allow literals on the left side too.
+    if (/^['"]/.test(path) || /^-?\d/.test(path) || path === 'true' || path === 'false' || path === 'null') {
+        return parseLiteral(path);
+    }
+    const segs = path.split('.');
+    let cur = ctx;
+    for (const seg of segs) {
+        if (cur == null)
+            return undefined;
+        cur = cur[seg];
+    }
+    return cur;
+}
+function parseLiteral(raw) {
+    const s = raw.trim();
+    if (s === 'true')
+        return true;
+    if (s === 'false')
+        return false;
+    if (s === 'null')
+        return null;
+    if (/^-?\d+(\.\d+)?$/.test(s))
+        return Number(s);
+    if ((s.startsWith("'") && s.endsWith("'")) ||
+        (s.startsWith('"') && s.endsWith('"'))) {
+        return s.slice(1, -1);
+    }
+    if (s.startsWith('[') && s.endsWith(']')) {
+        try {
+            // JSON-parse after normalising single-quoted strings to double.
+            const json = s.replace(/'([^']*)'/g, (_, inner) => JSON.stringify(inner));
+            return JSON.parse(json);
+        }
+        catch {
+            return [];
+        }
+    }
+    return s;
+}

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

@@ -0,0 +1,125 @@
+/**
+ * MetadataResourceRegistry — per-type overrides for the generic metadata
+ * admin engine (Phase 3c).
+ *
+ * The engine drives all 27 metadata types from a single ListPage /
+ * EditPage / HistoryPage shell. By default everything is rendered via
+ * a JSONSchema-driven AutoForm (using the rich `/meta/types` registry
+ * row's `schema` field). Specialised editors (ObjectManager,
+ * FieldDesigner, ObjectViewConfigurator, PermissionMatrix, …) opt in
+ * by calling `registerMetadataResource()` to override the default
+ * components for their type.
+ *
+ * This keeps the contract for "add a new metadata type" trivial:
+ *   1. Define its Zod schema in `packages/spec/src/<domain>/`.
+ *   2. Add it to `DEFAULT_METADATA_TYPE_REGISTRY` (framework).
+ *   3. Done. It shows up in the Setup app's Metadata Directory with
+ *      a working list / create / edit / history out of the box.
+ *
+ * Conventions:
+ *   • `primaryKey` defaults to `'name'` (the universal metadata
+ *     short-name; ADR-0006).
+ *   • `searchableFields` defaults to `['name','label','description']`.
+ *   • `listColumns` defaults to inferring from primary + label.
+ *   • `supportsHistory` defaults to true (every overlay goes through
+ *     `sys_metadata_history`).
+ */
+import type { ComponentType, ReactNode } from 'react';
+export type MetadataDomain = 'data' | 'ui' | 'automation' | 'ai' | 'system' | 'platform' | 'identity' | 'security' | 'other';
+/**
+ * One row in the registry — describes how the generic engine should
+ * render and edit a metadata type. All fields are optional; sensible
+ * defaults apply if a type isn't registered at all.
+ */
+export interface MetadataResourceConfig {
+    /** Metadata type, e.g. 'view', 'flow', 'agent'. */
+    type: string;
+    /** Display label. Falls back to server-side label or the type id. */
+    label?: string;
+    /** Long-form description shown in the page hero. */
+    description?: string;
+    /** Lucide icon name (e.g. 'database', 'workflow'). */
+    iconName?: string;
+    /** Coarse grouping for the directory page. */
+    domain?: MetadataDomain;
+    /** Primary key field, default `'name'`. */
+    primaryKey?: string;
+    /** Fields searched by the free-text filter. Default `['name','label','description']`. */
+    searchableFields?: string[];
+    /** Columns rendered in the list page. */
+    listColumns?: Array<{
+        key: string;
+        label: string;
+        /** Optional cell renderer. `value` is `item[key]`. */
+        render?: (value: unknown, item: Record<string, unknown>) => ReactNode;
+        /** Column width hint in CSS (e.g. `'180px'`, `'30%'`). */
+        width?: string;
+    }>;
+    /**
+     * Fully custom list page. When provided, the generic shell is bypassed.
+     * Receives `{ type }`. Use this for ObjectManager, etc.
+     */
+    ListPage?: ComponentType<{
+        type: string;
+    }>;
+    /**
+     * Fully custom edit page. Receives `{ type, name }`.
+     */
+    EditPage?: ComponentType<{
+        type: string;
+        name: string;
+    }>;
+    /**
+     * Fully custom create page. Receives `{ type }`.
+     */
+    CreatePage?: ComponentType<{
+        type: string;
+    }>;
+    /** Fields hidden from the AutoForm (still serialised on save). */
+    hiddenFields?: string[];
+    /** Suggested form field order (top to bottom). */
+    fieldOrder?: string[];
+    /** Whether the type opts in to the history tab. Default true. */
+    supportsHistory?: boolean;
+    /**
+     * Override the empty-state copy on the list page (e.g. "No views yet —
+     * Studio's Page Designer creates these for you").
+     */
+    emptyStateHint?: string;
+    /**
+     * Fallback JSONSchema used by the generic SchemaForm when the
+     * framework's `/meta/types` endpoint doesn't expose a `schema` field
+     * for this type (most types today). This lets us deliver a usable
+     * form-driven create/edit experience without first wiring full
+     * Zod→JSONSchema generation in the framework registry.
+     *
+     * If the server registry DOES return a `schema`, this is ignored.
+     */
+    defaultSchema?: Record<string, unknown>;
+}
+/**
+ * Register (or merge) an entry. Idempotent — re-registering with the
+ * same `type` merges the new fields with any existing entry so that
+ * bespoke editors (e.g. PermissionMatrixEditor) and generic-engine
+ * defaults (e.g. `defaultSchema`) can be registered independently and
+ * coexist. Explicit `undefined` values do not overwrite.
+ */
+export declare function registerMetadataResource(config: MetadataResourceConfig): void;
+/** Look up an entry. Returns `undefined` when the type isn't registered. */
+export declare function getMetadataResource(type: string): MetadataResourceConfig | undefined;
+/** Snapshot of all registered entries (diagnostics; directory page). */
+export declare function listMetadataResources(): MetadataResourceConfig[];
+/**
+ * Merge a registered config (if any) with server-side defaults from
+ * `/meta/types`. Server fields win for label/description/domain
+ * (the spec is source of truth); user-registered fields win for
+ * everything else (UI behaviour).
+ */
+export declare function resolveResourceConfig(type: string, serverEntry?: {
+    label?: string;
+    description?: string;
+    domain?: string;
+    allowOrgOverride?: boolean;
+}): MetadataResourceConfig & {
+    allowOrgOverride?: boolean;
+};

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

@@ -0,0 +1,48 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+const REGISTRY = new Map();
+/**
+ * Register (or merge) an entry. Idempotent — re-registering with the
+ * same `type` merges the new fields with any existing entry so that
+ * bespoke editors (e.g. PermissionMatrixEditor) and generic-engine
+ * defaults (e.g. `defaultSchema`) can be registered independently and
+ * coexist. Explicit `undefined` values do not overwrite.
+ */
+export function registerMetadataResource(config) {
+    const prev = REGISTRY.get(config.type);
+    if (!prev) {
+        REGISTRY.set(config.type, config);
+        return;
+    }
+    const merged = { ...prev };
+    for (const [k, v] of Object.entries(config)) {
+        if (v !== undefined)
+            merged[k] = v;
+    }
+    REGISTRY.set(config.type, merged);
+}
+/** Look up an entry. Returns `undefined` when the type isn't registered. */
+export function getMetadataResource(type) {
+    return REGISTRY.get(type);
+}
+/** Snapshot of all registered entries (diagnostics; directory page). */
+export function listMetadataResources() {
+    return Array.from(REGISTRY.values());
+}
+/**
+ * Merge a registered config (if any) with server-side defaults from
+ * `/meta/types`. Server fields win for label/description/domain
+ * (the spec is source of truth); user-registered fields win for
+ * everything else (UI behaviour).
+ */
+export function resolveResourceConfig(type, serverEntry) {
+    const registered = REGISTRY.get(type) ?? { type };
+    return {
+        ...registered,
+        type,
+        label: registered.label ?? serverEntry?.label ?? type,
+        description: registered.description ?? serverEntry?.description,
+        domain: (registered.domain ?? serverEntry?.domain ?? 'other'),
+        allowOrgOverride: serverEntry?.allowOrgOverride,
+        defaultSchema: registered.defaultSchema,
+    };
+}

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

@@ -0,0 +1,37 @@
+import { MetadataClient } from '@object-ui/data-objectstack';
+export interface RichMetadataTypeEntry {
+    type: string;
+    label?: string;
+    description?: string;
+    domain?: string;
+    allowOrgOverride?: boolean;
+    /** 'registry' = ADR opt-in; 'env' = unlocked via OBJECTSTACK_METADATA_WRITABLE. */
+    overrideSource?: 'registry' | 'env';
+    supportsOverlay?: boolean;
+    loadOrder?: number;
+    /** JSONSchema for the type's item shape (Phase 3a addition). */
+    schema?: Record<string, unknown>;
+    /** Canonical FormView layout for the type's editor (Phase 3c+). */
+    form?: Record<string, unknown>;
+    /** UI hints (icon, color, etc.) the framework may include. */
+    ui?: Record<string, unknown>;
+}
+/** Use a single MetadataClient for the whole admin engine. */
+export declare function useMetadataClient(environmentId?: string): MetadataClient;
+/**
+ * Fetch and cache the rich `/meta/types` registry response. Most pages
+ * only need it once per session, so we memoise per (client) instance.
+ */
+export declare function useMetadataTypes(client: MetadataClient): {
+    loading: boolean;
+    error: string | null;
+    entries: RichMetadataTypeEntry[];
+};
+/**
+ * Build a stable lookup map by type id from the entries array. Most
+ * pages need O(1) access to "what's the label / writable status for
+ * type X?".
+ */
+export declare function useTypesIndex(entries: RichMetadataTypeEntry[]): Record<string, RichMetadataTypeEntry>;
+/** Free-text filter helper used by list pages + QuickFind. */
+export declare function matchesQuery(item: Record<string, unknown>, query: string, fields?: string[]): boolean;

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

@@ -0,0 +1,96 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+/**
+ * Shared hooks + types for the metadata-admin engine (Phase 3c).
+ *
+ * Centralises the MetadataClient creation and the rich `/meta/types`
+ * row shape so every page reads from the same source of truth.
+ *
+ * Why a tiny barrel?
+ *   • DirectoryPage, ListPage, EditPage, HistoryPage and QuickFind
+ *     all need (client, typesRegistry). Letting each page re-fetch
+ *     would be wasteful and produce flickering badges.
+ *   • The hook caches the client per `baseUrl + environmentId` pair
+ *     so `client.withEnvironment(...)` swaps without remounting
+ *     consumers.
+ */
+import { useEffect, useMemo, useState } from 'react';
+import { MetadataClient } from '@object-ui/data-objectstack';
+/** Use a single MetadataClient for the whole admin engine. */
+export function useMetadataClient(environmentId) {
+    return useMemo(() => {
+        const c = new MetadataClient({ baseUrl: '' });
+        return environmentId ? c.withEnvironment(environmentId) : c;
+    }, [environmentId]);
+}
+/**
+ * Fetch and cache the rich `/meta/types` registry response. Most pages
+ * only need it once per session, so we memoise per (client) instance.
+ */
+export function useMetadataTypes(client) {
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState(null);
+    const [entries, setEntries] = useState([]);
+    useEffect(() => {
+        let cancelled = false;
+        setLoading(true);
+        setError(null);
+        (async () => {
+            try {
+                const result = await client.listTypes();
+                let list;
+                if (Array.isArray(result)) {
+                    list = result.map((t) => typeof t === 'string' ? { type: t } : t);
+                }
+                else {
+                    const rich = result?.entries;
+                    if (Array.isArray(rich) && rich.length > 0) {
+                        list = rich;
+                    }
+                    else {
+                        const names = result?.types ?? [];
+                        list = names.map((t) => ({ type: t }));
+                    }
+                }
+                if (!cancelled) {
+                    setEntries(list);
+                    setLoading(false);
+                }
+            }
+            catch (err) {
+                if (!cancelled) {
+                    setError(err?.message ?? String(err));
+                    setLoading(false);
+                }
+            }
+        })();
+        return () => {
+            cancelled = true;
+        };
+    }, [client]);
+    return { loading, error, entries };
+}
+/**
+ * Build a stable lookup map by type id from the entries array. Most
+ * pages need O(1) access to "what's the label / writable status for
+ * type X?".
+ */
+export function useTypesIndex(entries) {
+    return useMemo(() => {
+        const idx = {};
+        for (const e of entries)
+            idx[e.type] = e;
+        return idx;
+    }, [entries]);
+}
+/** Free-text filter helper used by list pages + QuickFind. */
+export function matchesQuery(item, query, fields = ['name', 'label', 'description']) {
+    if (!query)
+        return true;
+    const q = query.toLowerCase();
+    for (const f of fields) {
+        const v = item[f];
+        if (typeof v === 'string' && v.toLowerCase().includes(q))
+            return true;
+    }
+    return false;
+}

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

@@ -0,0 +1,68 @@
+/**
+ * Built-in widget renderers for SchemaForm.
+ *
+ * These cover the common widget hints declared in spec `*.form.ts`
+ * files (e.g. `widget: 'ref:object'`, `widget: 'master-detail'`).
+ *
+ * Each widget receives `WidgetProps`:
+ *   - schema     — the JSONSchema fragment for THIS field (so widgets
+ *                  for nested arrays can read items.properties)
+ *   - value      — the current value
+ *   - onChange   — write-back callback
+ *   - readOnly   — disable
+ *   - context    — out-of-band data (object list, ObjectQL fields, …)
+ *
+ * To register a new widget, add an entry to `WIDGETS` below. To wire
+ * extra context (e.g. a fields list), extend `WidgetContext` in
+ * SchemaForm.tsx and prefetch it in ResourceEditPage.
+ */
+import * as React from 'react';
+export interface WidgetContext {
+    /** Names of all object metadata records (for `ref:object`). */
+    objectNames?: string[];
+    /** Loading flag for the object list. */
+    objectsLoading?: boolean;
+}
+export interface WidgetProps {
+    id?: string;
+    schema: Record<string, any>;
+    value: unknown;
+    onChange: (v: unknown) => void;
+    readOnly?: boolean;
+    context?: WidgetContext;
+    /** Optional FormFieldSpec with type/options/reference/constraints */
+    fieldSpec?: {
+        field: string;
+        type?: string;
+        options?: Array<{
+            label: string;
+            value: string;
+            color?: string;
+        }>;
+        reference?: string;
+        maxLength?: number;
+        minLength?: number;
+        min?: number;
+        max?: number;
+        multiple?: boolean;
+        dependsOn?: string | string[];
+        /** Sub-fields for `composite` / `repeater` types */
+        fields?: Array<any>;
+        /** Code editor language (for type=code) */
+        language?: string;
+        /** Form-level helpers passed through from FormField */
+        label?: string;
+        placeholder?: string;
+        helpText?: string;
+        widget?: string;
+        colSpan?: number;
+        immutable?: boolean;
+        readonly?: boolean;
+        required?: boolean;
+    };
+    /** All form data (for reading dependency values) */
+    formData?: Record<string, unknown>;
+}
+export type WidgetRenderer = (props: WidgetProps) => React.ReactElement;
+export declare const WIDGETS: Record<string, WidgetRenderer>;
+export declare function CodeWidget({ schema, value, onChange, readOnly, fieldSpec, }: WidgetProps): import("react/jsx-runtime").JSX.Element;