@object-ui/core 6.2.2 → 7.0.0

package/dist/actions/ActionRunner.js

@@ -14,6 +14,7 @@
  * redirect handling, action chaining, custom handler registration.
  */
 import { ExpressionEvaluator } from '../evaluator/ExpressionEvaluator';
+import { globalUndoManager } from './UndoManager';
 export class ActionRunner {
     constructor(context = {}) {
         Object.defineProperty(this, "handlers", {
@@ -70,6 +71,12 @@ export class ActionRunner {
             writable: true,
             value: void 0
         });
+        Object.defineProperty(this, "resultDialogHandler", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         this.context = context;
         this.evaluator = new ExpressionEvaluator(context);
         // Default confirmation: window.confirm (can be overridden)
@@ -78,6 +85,7 @@ export class ActionRunner {
         this.modalHandler = null;
         this.navigationHandler = null;
         this.paramCollectionHandler = null;
+        this.resultDialogHandler = null;
     }
     /**
      * Set a custom confirmation handler (e.g., Shadcn AlertDialog).
@@ -110,6 +118,14 @@ export class ActionRunner {
     setParamCollectionHandler(handler) {
         this.paramCollectionHandler = handler;
     }
+    /**
+     * Set a result dialog handler — shows a one-shot reveal dialog after
+     * a successful action whose spec declares `resultDialog`. Used for
+     * values the user must copy now (2FA codes, OAuth client_secret).
+     */
+    setResultDialogHandler(handler) {
+        this.resultDialogHandler = handler;
+    }
     registerHandler(actionName, handler) {
         this.handlers.set(actionName, handler);
     }
@@ -139,10 +155,22 @@ export class ActionRunner {
                     return { success: false, error: 'Action condition not met' };
                 }
             }
-            if (action.disabled) {
-                const isDisabled = typeof action.disabled === 'string'
-                    ? this.evaluator.evaluateCondition(action.disabled)
-                    : action.disabled;
+            if (action.disabled != null && action.disabled !== false) {
+                // `disabled` may be a boolean, a CEL string, or the normalized envelope
+                // `{ dialect, source }` (what `objectstack build` emits). The previous
+                // code only evaluated the STRING form and treated any object as truthy,
+                // so an envelope-disabled action was ALWAYS "disabled" — silently
+                // blocking every execution (param dialog never opened, handler never
+                // ran). `evaluateCondition` already handles boolean/string/envelope;
+                // and the renderers are authoritative for the visual disabled state, so
+                // any eval failure here defaults to NOT-disabled (don't false-block).
+                let isDisabled = false;
+                try {
+                    isDisabled = this.evaluator.evaluateCondition(action.disabled);
+                }
+                catch {
+                    isDisabled = false;
+                }
                 if (isDisabled) {
                     return { success: false, error: 'Action is disabled' };
                 }
@@ -208,6 +236,9 @@ export class ActionRunner {
                 case 'api':
                     result = await this.executeAPI(action);
                     break;
+                case 'form':
+                    result = await this.executeForm(action);
+                    break;
                 case 'navigation':
                     result = await this.executeNavigation(action);
                     break;
@@ -272,19 +303,64 @@ export class ActionRunner {
      * Post-execution: emit toast notifications, handle chaining, callbacks.
      */
     async handlePostExecution(action, result) {
+        // resultDialog SUPPRESSES the successMessage toast — these are one-shot
+        // reveals (2FA codes, fresh OAuth secrets) where a toast would let the
+        // user dismiss the value before copying it. The reveal dialog itself
+        // requires explicit acknowledgement; we await it here so refreshAfter
+        // / chain steps don't fire until the user closes the dialog.
+        const hasResultDialog = !!(action.resultDialog && result.success);
         // Toast notifications
         if (this.toastHandler) {
             const showToast = action.toast ?? { showOnSuccess: true, showOnError: true };
             const duration = action.toast?.duration;
-            if (result.success && showToast.showOnSuccess !== false) {
-                const message = action.successMessage || 'Action completed successfully';
-                this.toastHandler(message, { type: 'success', duration });
+            if (result.success && !hasResultDialog && !result.silent && showToast.showOnSuccess !== false) {
+                // Prefer a DYNAMIC message the server returned (result.data.message)
+                // over the static action.successMessage. Server-driven actions like
+                // check_app_updates / publish / install compute a real outcome
+                // ("2 app updates available: CRM 1.0.0→1.0.1", "Published v1.2.0")
+                // that the static label can't express; without this the user only ever
+                // sees a generic "Done". Falls back to the static label, then a default.
+                const dyn = (result.data && typeof result.data === 'object'
+                    && typeof result.data.message === 'string')
+                    ? String(result.data.message).trim()
+                    : '';
+                const message = dyn || action.successMessage || 'Action completed successfully';
+                // Undoable action: register the captured operation on the global
+                // UndoManager and surface an "Undo" affordance on the toast (the
+                // consumer's toast handler wires the button to UndoManager).
+                if (result.undo) {
+                    try {
+                        globalUndoManager.push(result.undo);
+                    }
+                    catch { /* non-fatal */ }
+                }
+                this.toastHandler(message, { type: 'success', duration, undo: result.undo ? {} : undefined });
             }
             if (!result.success && showToast.showOnError !== false && result.error) {
                 const message = action.errorMessage || result.error;
                 this.toastHandler(message, { type: 'error', duration });
             }
         }
+        // Open the reveal dialog. If no handler is registered we still mark the
+        // execution successful but log — better to lose the value visibility
+        // than to silently re-toast and dismiss it.
+        if (hasResultDialog) {
+            if (this.resultDialogHandler) {
+                try {
+                    await this.resultDialogHandler(action.resultDialog, result.data, action);
+                }
+                catch (err) {
+                    // Acknowledgement failure is non-fatal; the underlying action already
+                    // succeeded. Log so consumers can wire it through their error reporter.
+                    // eslint-disable-next-line no-console
+                    console.warn('[ActionRunner] resultDialog handler rejected; treating as acknowledged', err);
+                }
+            }
+            else {
+                // eslint-disable-next-line no-console
+                console.warn('[ActionRunner] action.resultDialog set but no resultDialogHandler registered — the response value will not be shown to the user.', { action: action.name, data: result.data });
+            }
+        }
         // Apply refreshAfter from UIActionSchema
         if (action.refreshAfter && result.success) {
             result.reload = true;
@@ -352,14 +428,46 @@ export class ActionRunner {
         if (!rawUrl) {
             return { success: false, error: 'No URL provided for url action' };
         }
-        const url = this.evaluator.evaluate(rawUrl);
+        // Apply target ${param.X} / ${ctx.X} interpolation FIRST — the
+        // ExpressionEvaluator that follows would otherwise see unresolved
+        // `param.provider` and either error or substitute undefined. Doing it
+        // here also URL-encodes values (required for query-position params
+        // like `?provider=foo+bar`).
+        const interpolated = this.interpolateTarget(rawUrl, action);
+        let url = this.evaluator.evaluate(interpolated);
         if (!this.isValidUrl(url)) {
             return {
                 success: false,
                 error: 'Invalid URL scheme. Only http://, https://, and relative URLs are allowed.',
             };
         }
+        // Promote same-origin-style `/api/...` paths to absolute when an
+        // `apiBase` is provided in context (typical of split SPA + backend
+        // dev setups). Without this, `window.location.href = "/api/..."`
+        // hits the SPA host (e.g. Vite at :5173), the router has no match,
+        // and the browser silently falls back to the home page instead of
+        // following better-auth's 302 to the IdP.
+        const apiBase = typeof this.context.apiBase === 'string' ? this.context.apiBase.replace(/\/+$/, '') : '';
+        if (apiBase && /^\/(api|_auth|_account)\//.test(url)) {
+            url = `${apiBase}${url}`;
+        }
         const isExternal = url.startsWith('http://') || url.startsWith('https://');
+        // Same-origin API endpoints (most commonly the auth provider's
+        // `/api/v1/auth/sign-in/social` redirect dance) issue server-side
+        // 302s that must be followed by the *browser*, not the SPA router.
+        // Pushing `/api/...` into React Router lands on no matching route
+        // and silently falls back to the default page, so the OAuth flow
+        // never starts. Short-circuit to a full-page navigation here.
+        // For absolute URLs (now also produced by the apiBase prefix above),
+        // we need full-page navigation for any URL that is going to issue a
+        // server-side redirect dance — better-auth's `/sign-in/social` is the
+        // canonical case. Detect "looks like a same-origin API path" both for
+        // bare-relative input AND for the apiBase-prefixed form.
+        const isApiCall = /\/(api|_auth|_account)\//.test(url) && (isExternal || url.startsWith('/'));
+        if (isApiCall) {
+            window.location.href = url;
+            return { success: true };
+        }
         const newTab = action.params?.newTab ?? isExternal;
         if (this.navigationHandler) {
             this.navigationHandler(url, { external: isExternal, newTab });
@@ -428,6 +536,28 @@ export class ActionRunner {
     /**
      * Execute navigation action
      */
+    /**
+     * `form` action — open a FormView as a routed page (`/forms/:name`, per the
+     * spec). `target` is the FormView name. Without this case the action fell
+     * through to `executeActionSchema` and silently no-opped (the "Log Time does
+     * nothing" report). The current record id is forwarded as `?recordId=` for
+     * hosts that support it; the form route ignores unknown query params.
+     */
+    async executeForm(action) {
+        const name = this.evaluator.evaluate(action.target);
+        if (!name || typeof name !== 'string') {
+            return { success: false, error: 'No form target (FormView name) provided for form action' };
+        }
+        const recordId = (this.context.record && this.context.record.id) ??
+            (this.context.data && this.context.data.id);
+        const base = `/forms/${name}`;
+        const to = recordId != null ? `${base}?recordId=${encodeURIComponent(String(recordId))}` : base;
+        if (this.navigationHandler) {
+            this.navigationHandler(to, { external: false });
+            return { success: true };
+        }
+        return { success: true, redirect: to };
+    }
     async executeNavigation(action) {
         const nav = action.navigate || action;
         const to = this.evaluator.evaluate(nav.to || nav.target);
@@ -471,14 +601,14 @@ export class ActionRunner {
             let responseType = 'json';
             if (typeof apiConfig === 'string') {
                 // Simple string endpoint
-                url = apiConfig;
+                url = this.interpolateTarget(apiConfig, action);
                 method = action.method || 'POST';
                 body = JSON.stringify(action.params || this.context.data || {});
             }
             else {
                 // Complex ApiConfig
                 const config = apiConfig;
-                url = config.url;
+                url = this.interpolateTarget(config.url, action);
                 method = config.method || action.method || 'POST';
                 headers = { ...headers, ...config.headers };
                 responseType = config.responseType || 'json';
@@ -531,6 +661,66 @@ export class ActionRunner {
             url.startsWith('/') ||
             url.startsWith('./'));
     }
+    /**
+     * Substitute `${param.X}` and `${ctx.X}` tokens in an action target.
+     *
+     * Used by executeUrl and executeAPI so metadata can produce dynamic
+     * URLs without coupling to the wider ExpressionEvaluator surface
+     * (which would also evaluate operators, member access, etc. — overkill
+     * and unsafe for URL-position values).
+     *
+     * Every substituted value is `encodeURIComponent`'d, since the only
+     * legitimate use case so far (better-auth `/sign-in/social?provider=…`)
+     * places interpolated values in URL query positions. Callers MUST
+     * therefore put tokens after a `?` or `&` — using `${param.x}` inside a
+     * path segment will produce percent-encoded slashes, which is the
+     * correct behaviour for opaque IDs but would break a literal path
+     * fragment.
+     *
+     * `ctx.origin`, `ctx.user.*`, `ctx.org.*`, `ctx.recordId` are surfaced
+     * implicitly from the runner's ActionContext + window. Consumers can
+     * extend by stuffing extra keys under `context.ctx = {...}` before
+     * calling `runner.execute()`.
+     */
+    interpolateTarget(target, action) {
+        if (typeof target !== 'string' || target.indexOf('${') === -1)
+            return target;
+        const params = (action.params && typeof action.params === 'object' && !Array.isArray(action.params))
+            ? action.params
+            : {};
+        const ctx = this.buildInterpolationContext();
+        return target.replace(/\$\{(param|ctx)\.([\w.]+)\}/g, (_match, scope, path) => {
+            const root = scope === 'param' ? params : ctx;
+            const value = readPath(root, path);
+            if (value == null)
+                return '';
+            return encodeURIComponent(String(value));
+        });
+    }
+    /**
+     * Assemble the `ctx` namespace exposed to target interpolation.
+     * Built-in keys: origin, user, org, recordId. Anything the consumer
+     * placed under context.ctx is merged on top.
+     */
+    buildInterpolationContext() {
+        const ctx = {
+            origin: typeof window !== 'undefined' ? window.location.origin : '',
+            // Backend API origin (typically `import.meta.env.VITE_SERVER_URL`
+            // passed in from the host app). Empty string means "same-origin",
+            // which collapses `${ctx.apiBase}/api/...` to a regular relative
+            // path — exactly the production-deployment behaviour.
+            apiBase: typeof this.context.apiBase === 'string'
+                ? this.context.apiBase.replace(/\/+$/, '')
+                : '',
+            user: this.context.user ?? {},
+            org: this.context.org ?? this.context.organization ?? {},
+            recordId: this.context.record?.id ?? this.context.recordId,
+        };
+        if (this.context.ctx && typeof this.context.ctx === 'object') {
+            Object.assign(ctx, this.context.ctx);
+        }
+        return ctx;
+    }
     updateContext(newContext) {
         this.context = { ...this.context, ...newContext };
         this.evaluator.updateContext(newContext);
@@ -552,3 +742,16 @@ export async function executeAction(action, context = {}) {
     const runner = new ActionRunner(context);
     return await runner.execute(action);
 }
+/**
+ * Dot-path read used by target interpolation. Plain reduce — kept inline
+ * to avoid pulling lodash for a 3-line helper.
+ */
+function readPath(root, path) {
+    if (root == null)
+        return undefined;
+    return path.split('.').reduce((acc, key) => {
+        if (acc == null)
+            return undefined;
+        return acc[key];
+    }, root);
+}

package/dist/evaluator/ExpressionEvaluator.js

@@ -181,12 +181,34 @@ export class ExpressionEvaluator {
         if (condition && typeof condition === 'object' && typeof condition.source === 'string') {
             condition = condition.source;
         }
+        // No condition → default to visible/enabled (undefined, null, '').
         if (!condition) {
-            return true; // Default to visible/enabled if no condition
+            return true;
+        }
+        if (typeof condition !== 'string') {
+            return Boolean(condition);
+        }
+        const trimmed = condition.trim();
+        if (!trimmed) {
+            return true; // Whitespace-only → treat as "no condition".
+        }
+        // A condition is semantically a single boolean expression. When it's a
+        // `${...}` template, evaluate via the template path. Otherwise treat the
+        // ENTIRE string as one expression (bare CEL like `record.status == "x"`):
+        // `evaluate` would short-circuit a non-`${}` string and return it verbatim,
+        // so `Boolean('record.status == "x"')` was ALWAYS true — silently making
+        // every bare-expression `disabled`/`condition`/`visible` predicate truthy.
+        if (trimmed.includes('${')) {
+            return Boolean(this.evaluate(trimmed, options));
+        }
+        try {
+            return Boolean(this.evaluateExpression(trimmed, { sanitize: options.sanitize !== false }));
+        }
+        catch {
+            // Unparseable predicate — preserve the historical "default to
+            // visible/enabled" behaviour rather than hiding/blocking on a typo.
+            return true;
         }
-        const result = this.evaluate(condition, options);
-        // Convert result to boolean
-        return Boolean(result);
     }
     /**
      * Update the context with new data

package/dist/evaluator/fieldRules.d.ts

@@ -0,0 +1,49 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/** A field-rule predicate as authored in metadata. */
+export type FieldRulePredicate = string | {
+    dialect?: string;
+    source: string;
+};
+/**
+ * Evaluate a field-rule CEL predicate against a record.
+ *
+ * @param pred      The `visibleWhen` / `readonlyWhen` / `requiredWhen` predicate.
+ * @param record    The live form values (overlays prior persisted record).
+ * @param fallback  Value to return when the predicate is absent or fails to
+ *                  evaluate. Pick the *safe* default for the caller:
+ *                  `false` for readonly/required (don't lock/block on error),
+ *                  `true` for visibility (don't hide on error).
+ * @param previous  The prior persisted record, if any (for `previous.*` refs).
+ * @param scope     Extra top-level scope variables bound alongside `record` —
+ *                  e.g. `{ parent }` so an inline line-item cell can reference
+ *                  its header (`parent.status == 'paid'`) as well as its own
+ *                  row (`record.quantity`). Bound via the engine's `extra`.
+ */
+export declare function evalFieldPredicate(pred: FieldRulePredicate | undefined | null, record: Record<string, unknown>, fallback: boolean, previous?: Record<string, unknown>, scope?: Record<string, unknown>): boolean;
+/**
+ * Resolve the effective `{ visible, readonly, required }` state for a field
+ * given its conditional rules and the live record. Each `*When` rule, when
+ * present, *overrides* the static flag. A static `true` is never weakened by a
+ * `false` predicate result for required/readonly — but `visibleWhen` is
+ * authoritative when present (so a field can be conditionally shown/hidden).
+ */
+export declare function resolveFieldRuleState(rules: {
+    visibleWhen?: FieldRulePredicate;
+    readonlyWhen?: FieldRulePredicate;
+    requiredWhen?: FieldRulePredicate;
+    /** Back-compat alias of `requiredWhen` (spec @deprecated). */
+    conditionalRequired?: FieldRulePredicate;
+}, record: Record<string, unknown>, statics: {
+    required?: boolean;
+    readonly?: boolean;
+}, previous?: Record<string, unknown>, scope?: Record<string, unknown>): {
+    visible: boolean;
+    readonly: boolean;
+    required: boolean;
+};

package/dist/evaluator/fieldRules.js

@@ -0,0 +1,86 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * Client-side evaluation of field-level conditional rules
+ * (`visibleWhen` / `readonlyWhen` / `requiredWhen`).
+ *
+ * These predicates are authored as CEL — the *same* dialect the server
+ * enforces in `@objectstack/objectql`'s rule-validator (`requiredWhen`) and
+ * `stripReadonlyWhenFields` (`readonlyWhen`). To guarantee the client UX and
+ * the server enforcement reach the *identical* verdict for a given record we
+ * delegate to the canonical engine, `@objectstack/formula`'s
+ * `ExpressionEngine`, rather than re-implementing a parallel evaluator. See
+ * ADR-0036 (field-level conditional rules) and the framework's
+ * `packages/formula` "No private expression DSL" note.
+ *
+ * A predicate is `string | { dialect, source }`. A bare string is treated as
+ * CEL (mirrors the server's `toExpression`). Evaluation is *fail-open* for
+ * visibility/required (a broken predicate must not hide a field or wrongly
+ * block submit) and *fail-open* for readonly (a broken predicate leaves the
+ * field editable) — matching the server, which logs and allows the change
+ * through.
+ */
+import { ExpressionEngine } from '@objectstack/formula';
+/** Normalize a predicate into the `Expression` shape the engine expects. */
+function toExpression(pred) {
+    if (typeof pred === 'string')
+        return { dialect: 'cel', source: pred };
+    return { dialect: (pred.dialect ?? 'cel'), source: pred.source };
+}
+/**
+ * Evaluate a field-rule CEL predicate against a record.
+ *
+ * @param pred      The `visibleWhen` / `readonlyWhen` / `requiredWhen` predicate.
+ * @param record    The live form values (overlays prior persisted record).
+ * @param fallback  Value to return when the predicate is absent or fails to
+ *                  evaluate. Pick the *safe* default for the caller:
+ *                  `false` for readonly/required (don't lock/block on error),
+ *                  `true` for visibility (don't hide on error).
+ * @param previous  The prior persisted record, if any (for `previous.*` refs).
+ * @param scope     Extra top-level scope variables bound alongside `record` —
+ *                  e.g. `{ parent }` so an inline line-item cell can reference
+ *                  its header (`parent.status == 'paid'`) as well as its own
+ *                  row (`record.quantity`). Bound via the engine's `extra`.
+ */
+export function evalFieldPredicate(pred, record, fallback, previous, scope) {
+    if (pred == null || (typeof pred === 'string' && !pred.trim()))
+        return fallback;
+    try {
+        const res = ExpressionEngine.evaluate(toExpression(pred), {
+            record,
+            previous,
+            ...(scope ? { extra: scope } : {}),
+        });
+        if (!res.ok)
+            return fallback;
+        return res.value === true;
+    }
+    catch {
+        return fallback;
+    }
+}
+/**
+ * Resolve the effective `{ visible, readonly, required }` state for a field
+ * given its conditional rules and the live record. Each `*When` rule, when
+ * present, *overrides* the static flag. A static `true` is never weakened by a
+ * `false` predicate result for required/readonly — but `visibleWhen` is
+ * authoritative when present (so a field can be conditionally shown/hidden).
+ */
+export function resolveFieldRuleState(rules, record, statics, previous, scope) {
+    const visible = rules.visibleWhen != null
+        ? evalFieldPredicate(rules.visibleWhen, record, true, previous, scope)
+        : true;
+    const readonly = statics.readonly === true ||
+        (rules.readonlyWhen != null
+            ? evalFieldPredicate(rules.readonlyWhen, record, false, previous, scope)
+            : false);
+    const requiredPred = rules.requiredWhen ?? rules.conditionalRequired;
+    const required = statics.required === true ||
+        (requiredPred != null ? evalFieldPredicate(requiredPred, record, false, previous, scope) : false);
+    return { visible, readonly, required };
+}

package/dist/evaluator/index.d.ts

@@ -7,6 +7,7 @@
  */
 export * from './ExpressionContext.js';
 export * from './ExpressionEvaluator.js';
+export * from './fieldRules.js';
 export * from './ExpressionCache.js';
 export * from './FormulaFunctions.js';
 export * from './SafeExpressionParser.js';

package/dist/evaluator/index.js

@@ -7,6 +7,7 @@
  */
 export * from './ExpressionContext.js';
 export * from './ExpressionEvaluator.js';
+export * from './fieldRules.js';
 export * from './ExpressionCache.js';
 export * from './FormulaFunctions.js';
 export * from './SafeExpressionParser.js';

package/dist/index.d.ts

@@ -13,7 +13,6 @@ export * from './registry/WidgetRegistry.js';
 export * from './validation/index.js';
 export * from './builder/schema-builder.js';
 export * from './utils/filter-converter.js';
-export * from './utils/normalize-quick-filter.js';
 export * from './utils/extract-records.js';
 export * from './utils/expand-fields.js';
 export * from './evaluator/index.js';
@@ -28,6 +27,7 @@ export * from './utils/debug-collector.js';
 export * from './utils/merge-views-into-objects.js';
 export * from './utils/freeze-schema.js';
 export * from './protocols/index.js';
+export * from './styling/scoped-styles.js';
 /**
  * @deprecated Import `composeStacks` from `@objectstack/spec` instead.
  *
@@ -38,3 +38,5 @@ export { composeStacks } from '@objectstack/spec';
 export * from './utils/drill-down.js';
 export * from './utils/date-macros.js';
 export * from './utils/compare-to.js';
+export * from './utils/chart-series.js';
+export * from './utils/dataset-format.js';

package/dist/index.js

@@ -12,7 +12,6 @@ export * from './registry/WidgetRegistry.js';
 export * from './validation/index.js';
 export * from './builder/schema-builder.js';
 export * from './utils/filter-converter.js';
-export * from './utils/normalize-quick-filter.js';
 export * from './utils/extract-records.js';
 export * from './utils/expand-fields.js';
 export * from './evaluator/index.js';
@@ -27,6 +26,7 @@ export * from './utils/debug-collector.js';
 export * from './utils/merge-views-into-objects.js';
 export * from './utils/freeze-schema.js';
 export * from './protocols/index.js';
+export * from './styling/scoped-styles.js';
 /**
  * @deprecated Import `composeStacks` from `@objectstack/spec` instead.
  *
@@ -37,3 +37,5 @@ export { composeStacks } from '@objectstack/spec';
 export * from './utils/drill-down.js';
 export * from './utils/date-macros.js';
 export * from './utils/compare-to.js';
+export * from './utils/chart-series.js';
+export * from './utils/dataset-format.js';

package/dist/registry/Registry.d.ts

@@ -91,6 +91,17 @@ export declare class Registry<T = any> {
      * // Accessible as 'button'
      */
     register(type: string, component: ComponentRenderer<T>, meta?: ComponentMeta): void;
+    /**
+     * Remove a previously registered component. Mirrors {@link register} by
+     * clearing both the namespaced key and the bare-name fallback (when the
+     * fallback still points at this registration), plus any matching lazy stub.
+     * Notifies subscribers only when something was actually removed.
+     *
+     * Mainly used by tests that install a stub renderer and need to restore the
+     * prior registry state on teardown, since the registry is a process-level
+     * singleton shared across test files.
+     */
+    unregister(type: string, namespace?: string): boolean;
     /**
      * Register a lazy-loaded component. The `loader` is a function returning a
      * dynamic `import()` whose target module performs `register()` calls for

package/dist/registry/Registry.js

@@ -76,6 +76,17 @@ export class Registry {
         // the last registration wins for non-namespaced lookups
         // Skip this if skipFallback is true to avoid overwriting other components
         if (meta?.namespace && !meta?.skipFallback) {
+            // Collision guard: a bare-name fallback that overwrites a DIFFERENT
+            // component is almost always an accident (e.g. plugin 'view:grid' silently
+            // clobbering the layout 'grid'). Warn so it surfaces instead of 404-ing at
+            // render time. Pass `skipFallback: true` when a namespaced-only alias is
+            // intended.
+            const existing = this.components.get(type);
+            if (existing && existing.component !== component && existing.type !== fullType) {
+                console.warn(`Component "${type}" bare-name fallback is being overwritten by "${fullType}". ` +
+                    `If this is intentional keep going; otherwise register "${fullType}" with ` +
+                    `{ skipFallback: true } so it doesn't claim the bare "${type}" key.`);
+            }
             this.components.set(type, {
                 type: fullType, // Keep reference to namespaced type
                 component,
@@ -88,6 +99,31 @@ export class Registry {
         this.lazyEntries.delete(type);
         this.notify();
     }
+    /**
+     * Remove a previously registered component. Mirrors {@link register} by
+     * clearing both the namespaced key and the bare-name fallback (when the
+     * fallback still points at this registration), plus any matching lazy stub.
+     * Notifies subscribers only when something was actually removed.
+     *
+     * Mainly used by tests that install a stub renderer and need to restore the
+     * prior registry state on teardown, since the registry is a process-level
+     * singleton shared across test files.
+     */
+    unregister(type, namespace) {
+        const fullType = namespace ? `${namespace}:${type}` : type;
+        const removed = this.components.delete(fullType);
+        // Only drop the bare fallback if it still resolves to this registration.
+        if (namespace) {
+            const bare = this.components.get(type);
+            if (bare && bare.type === fullType)
+                this.components.delete(type);
+        }
+        this.lazyEntries.delete(fullType);
+        this.lazyEntries.delete(type);
+        if (removed)
+            this.notify();
+        return removed;
+    }
     /**
      * Register a lazy-loaded component. The `loader` is a function returning a
      * dynamic `import()` whose target module performs `register()` calls for