@object-ui/core 17.1.0 → 17.3.0

package/dist/evaluator/fieldRules.js

@@ -24,6 +24,17 @@
  * block submit) and *fail-open* for readonly (a broken predicate leaves the
  * field editable) — matching the server, which logs and allows the change
  * through.
+ *
+ * Fail-open is **loud**, not silent (objectstack#5149): a predicate that
+ * cannot be evaluated — parse error, unbound identifier, engine fault — logs
+ * one `console.warn` per predicate text with the source and the failure
+ * reason, then still returns the caller's fallback. Without the warning a
+ * broken predicate is indistinguishable from an absent one, so
+ * conditional-visibility bugs survive inspection indefinitely. This is the
+ * client half of the server's "log and allow" convention (`readonlyWhen for
+ * 'x' failed to evaluate — change allowed through`). The *default* stays
+ * fail-open on purpose — flipping it is a shipped-behavior change tracked
+ * separately in objectstack#5149 (appeal 1, undecided).
  */
 import { ExpressionEngine } from '@objectstack/formula';
 /** Normalize a predicate into the `Expression` shape the engine expects. */
@@ -32,6 +43,26 @@ function toExpression(pred) {
         return { dialect: 'cel', source: pred };
     return { dialect: (pred.dialect ?? 'cel'), source: pred.source };
 }
+const warnedPredicates = new Set();
+/**
+ * One-time warning for a predicate that could not be evaluated. Deduped per
+ * predicate TEXT (dialect + source): a broken predicate is re-evaluated on
+ * every render/keystroke, and the point is one loud line, not a scrolling
+ * wall. The dedupe key is JSON-encoded — never a control-character separator
+ * (objectstack#5450 made a sibling of this file binary to grep that way).
+ */
+function warnPredicateFailure(expr, fallback, reason, context) {
+    const key = JSON.stringify([expr.dialect, expr.source]);
+    if (warnedPredicates.has(key))
+        return;
+    warnedPredicates.add(key);
+    console.warn('[object-ui] A conditional predicate failed to evaluate' +
+        (context ? ` (${context})` : '') +
+        ` and was treated as its safe default (${String(fallback)}): ` +
+        JSON.stringify(expr.source) +
+        `. Reason: ${reason}. ` +
+        "Values are bound under 'record.' (e.g. record.status) — check the field names and CEL syntax.");
+}
 /**
  * Evaluate a field-rule CEL predicate against a record.
  *
@@ -46,21 +77,37 @@ function toExpression(pred) {
  *                  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`.
+ * @param diagnostic  Failure-warning options: a `context` locator for the
+ *                  one-time warning, and `warn: false` for callers that probe
+ *                  for faults and report them themselves. The returned value
+ *                  is unaffected either way.
  */
-export function evalFieldPredicate(pred, record, fallback, previous, scope) {
+export function evalFieldPredicate(pred, record, fallback, previous, scope, diagnostic) {
     if (pred == null || (typeof pred === 'string' && !pred.trim()))
         return fallback;
+    const expr = toExpression(pred);
     try {
-        const res = ExpressionEngine.evaluate(toExpression(pred), {
+        const res = ExpressionEngine.evaluate(expr, {
             record,
             previous,
             ...(scope ? { extra: scope } : {}),
         });
-        if (!res.ok)
+        if (!res.ok) {
+            // Parse error, type error, unbound identifier, engine fault … — every
+            // not-ok verdict resolves to the fallback, but never silently (#5149).
+            if (diagnostic?.warn !== false) {
+                warnPredicateFailure(expr, fallback, `[${res.error.kind}] ${res.error.message}`, diagnostic?.context);
+            }
             return fallback;
+        }
         return res.value === true;
     }
-    catch {
+    catch (err) {
+        // The engine contract is "never throws"; this guard is for anything that
+        // slips past it. Same loud fail-open as the not-ok branch.
+        if (diagnostic?.warn !== false) {
+            warnPredicateFailure(expr, fallback, `[throw] ${err instanceof Error ? err.message : String(err)}`, diagnostic?.context);
+        }
         return fallback;
     }
 }
@@ -70,18 +117,26 @@ export function evalFieldPredicate(pred, record, fallback, previous, scope) {
  * 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).
+ *
+ * @param fieldContext  Optional locator for failure warnings — e.g.
+ *                      `"field 'amount'"`. The warning then reads
+ *                      `visibleWhen of field 'amount' …`; without it, the rule
+ *                      kind alone is reported.
  */
-export function resolveFieldRuleState(rules, record, statics, previous, scope) {
+export function resolveFieldRuleState(rules, record, statics, previous, scope, fieldContext) {
+    const diag = (rule) => ({
+        context: fieldContext ? `${rule} of ${fieldContext}` : rule,
+    });
     const visible = rules.visibleWhen != null
-        ? evalFieldPredicate(rules.visibleWhen, record, true, previous, scope)
+        ? evalFieldPredicate(rules.visibleWhen, record, true, previous, scope, diag('visibleWhen'))
         : true;
     const readonly = statics.readonly === true ||
         (rules.readonlyWhen != null
-            ? evalFieldPredicate(rules.readonlyWhen, record, false, previous, scope)
+            ? evalFieldPredicate(rules.readonlyWhen, record, false, previous, scope, diag('readonlyWhen'))
             : false);
     const required = statics.required === true ||
         (rules.requiredWhen != null
-            ? evalFieldPredicate(rules.requiredWhen, record, false, previous, scope)
+            ? evalFieldPredicate(rules.requiredWhen, record, false, previous, scope, diag('requiredWhen'))
             : 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 './predicateInput.js';
 export * from './fieldRules.js';
 export * from './listConditional.js';
 export * from './optionRules.js';

package/dist/evaluator/index.js

@@ -7,6 +7,7 @@
  */
 export * from './ExpressionContext.js';
 export * from './ExpressionEvaluator.js';
+export * from './predicateInput.js';
 export * from './fieldRules.js';
 export * from './listConditional.js';
 export * from './optionRules.js';

package/dist/evaluator/listConditional.d.ts

@@ -34,6 +34,7 @@
  * (or nothing) to the server's CEL engine.
  */
 import { type FieldRulePredicate } from './fieldRules.js';
+import { type FieldContainerLike } from '../utils/predicate-record.js';
 /** True when a *string* predicate uses legacy-only (non-CEL) syntax. */
 export declare function isLegacyDialectSource(source: string): boolean;
 /** Options for {@link evalRowPredicate}. */
@@ -49,6 +50,14 @@ export interface RowPredicateOptions {
     warnOnError?: boolean;
     /** Label used in warning messages (e.g. an action name or rule index). */
     label?: string;
+    /**
+     * The object's field definitions (`objectSchema.fields`). Supplying them lets
+     * a relation field be bound as the FOREIGN KEY the server stores, rather than
+     * as whatever `$expand` happened to substitute for it on this surface — see
+     * {@link toPredicateRecord}. Omitting them keeps the payload verbatim, so a
+     * caller with no schema at hand never guesses which fields are relations.
+     */
+    fields?: FieldContainerLike;
 }
 /**
  * Evaluate a single boolean predicate against a row record on the canonical CEL
@@ -89,5 +98,8 @@ export type ConditionalFormattingRuleLike = {
  *
  * @param scope  Extra top-level scope (host predicate scope) bound alongside
  *               the row, so `features.*` predicates keep resolving.
+ * @param fields The object's field definitions, so a rule comparing a relation
+ *               field sees the stored foreign key rather than the expanded
+ *               record (see {@link RowPredicateOptions.fields}).
  */
-export declare function resolveConditionalFormatting(record: Record<string, unknown> | null | undefined, rules?: readonly ConditionalFormattingRuleLike[] | null, scope?: Record<string, unknown>): Record<string, string>;
+export declare function resolveConditionalFormatting(record: Record<string, unknown> | null | undefined, rules?: readonly ConditionalFormattingRuleLike[] | null, scope?: Record<string, unknown>, fields?: FieldContainerLike): Record<string, string>;

package/dist/evaluator/optionRules.js

@@ -39,7 +39,11 @@ export function isOptionGroupGated(dependsOn, record) {
 export function resolveVisibleOptions(options, record, scope) {
     if (!options || options.length === 0)
         return [];
-    return options.filter((o) => o?.visibleWhen == null ? true : evalFieldPredicate(o.visibleWhen, record, true, undefined, scope));
+    return options.filter((o) => o?.visibleWhen == null
+        ? true
+        : evalFieldPredicate(o.visibleWhen, record, true, undefined, scope, {
+            context: `visibleWhen of option '${String(o.value)}'`,
+        }));
 }
 /**
  * Whether a scalar field value is still valid given the currently-visible

package/dist/evaluator/predicateInput.d.ts

@@ -0,0 +1,84 @@
+/**
+ * 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.
+ */
+/**
+ * The normalized shape {@link ExpressionEvaluator.evaluateCondition} consumes:
+ * a boolean (short-circuits), a `${…}` template string (legacy JS path), a
+ * `{ dialect: 'cel', source }` envelope (canonical `@objectstack/formula`
+ * path), or `undefined` for "no predicate declared".
+ *
+ * ## Why not `PredicateInput` (objectstack#4115 / objectui#3074)
+ *
+ * `@objectstack/spec` owns `PredicateInput` — and it is a genuinely DIFFERENT
+ * concept, so wearing that name would be the exact drift this repo's
+ * `check:spec-symbols` gate exists to stop. The spec's is
+ * `z.input<typeof PredicateInputSchema>`: what an author WRITES, before
+ * normalization — a bare string, or an envelope over the full dialect set
+ * (`cel` | `cron` | `template`) with optional `source` / `ast` / `meta`.
+ *
+ * This one is the OUTPUT of normalization: what the evaluator ACCEPTS. It
+ * admits `boolean` and the `${…}` template spelling (neither of which the spec
+ * models as a predicate), narrows `dialect` to `cel` alone (every other dialect
+ * has already been flattened onto the legacy path by `toPredicateInput`),
+ * requires a non-empty `source`, and carries no `ast` / `meta`. The two unions
+ * are not mutually assignable in either direction.
+ *
+ * The rename is pinned from both sides by the tripwire in
+ * `packages/core/src/utils/__tests__/spec-symbol-batch4.test.ts`: the spec must
+ * still own `PredicateInput` (else this rename has lost its reason), and must
+ * still NOT own `EvaluatorPredicateInput` (the objectui#3074 mistake of
+ * renaming onto another name the spec already holds).
+ */
+export type EvaluatorPredicateInput = string | boolean | {
+    dialect: 'cel';
+    source: string;
+} | undefined;
+/**
+ * Normalize a schema-supplied predicate (`visible` / `enabled` / `disabled` /
+ * `hidden`) into the form {@link ExpressionEvaluator.evaluateCondition}
+ * expects.
+ *
+ * Accepts:
+ *   - `boolean` → returned as-is (predicate evaluation short-circuits).
+ *   - `string`  → wrapped as `${string}` (legacy DX shorthand).
+ *   - `Expression` envelope `{ dialect, source }` (the normalized form
+ *     `@objectstack/spec`'s `ExpressionInputSchema` produces for every
+ *     authored predicate, including bare strings) → a `cel` dialect keeps
+ *     its envelope; every other dialect is unwrapped and wrapped as
+ *     `${source}`.
+ *   - `null` / `undefined` / empty / anything else → `undefined`
+ *     (default visible/enabled).
+ *
+ * ## Why the `cel` envelope must survive normalization (#2661 / #3314)
+ *
+ * `evaluateCondition` routes to the canonical `@objectstack/formula` engine —
+ * the one the SERVER enforces with — only while the argument is still a
+ * `{ dialect: 'cel' }` object. Collapse it to `${source}` first and the
+ * predicate silently falls to the legacy JS evaluator, whose semantics
+ * differ: CEL has no `<` overload for `null`, so `null < null` faults and
+ * fail-closed hides, while JS quietly yields `false`; CEL-only builtins
+ * (`today()`, objectstack#3205) do not exist on the JS path at all. Two
+ * normalizers that disagree on this one branch therefore make the SAME
+ * `visible:` predicate reach different verdicts depending on whether the
+ * action was surfaced by `ActionEngine.getActionsForLocation` or rendered
+ * standalone (#3314).
+ *
+ * This is THE implementation, not one of two — `@object-ui/core` is the common
+ * dependency of every consumer, so engine-side code and renderer-side code
+ * share one normalization instead of hand-rolling envelope unwrapping per call
+ * site. `@object-ui/react`'s `toPredicateInput` is a re-export of this function
+ * (since #3367; it used to be an independent twin held in step by a 14-shape
+ * normalization parity table, which is exactly the arrangement the paragraph
+ * above describes the failure mode of). What pins that now is the identity
+ * assertion in
+ * `packages/react/src/hooks/__tests__/actionPredicate.parity.test.tsx` — the
+ * react export must BE this function object — alongside the engine-path vs
+ * renderer-path verdict parity suite in the same file, which is a separate
+ * claim and still earns its keep: sharing a normalizer does not by itself
+ * prove the two call paths reach the same verdict.
+ */
+export declare function toPredicateInput(value: unknown): EvaluatorPredicateInput;

package/dist/evaluator/predicateInput.js

@@ -0,0 +1,72 @@
+/**
+ * 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.
+ */
+/**
+ * Normalize a schema-supplied predicate (`visible` / `enabled` / `disabled` /
+ * `hidden`) into the form {@link ExpressionEvaluator.evaluateCondition}
+ * expects.
+ *
+ * Accepts:
+ *   - `boolean` → returned as-is (predicate evaluation short-circuits).
+ *   - `string`  → wrapped as `${string}` (legacy DX shorthand).
+ *   - `Expression` envelope `{ dialect, source }` (the normalized form
+ *     `@objectstack/spec`'s `ExpressionInputSchema` produces for every
+ *     authored predicate, including bare strings) → a `cel` dialect keeps
+ *     its envelope; every other dialect is unwrapped and wrapped as
+ *     `${source}`.
+ *   - `null` / `undefined` / empty / anything else → `undefined`
+ *     (default visible/enabled).
+ *
+ * ## Why the `cel` envelope must survive normalization (#2661 / #3314)
+ *
+ * `evaluateCondition` routes to the canonical `@objectstack/formula` engine —
+ * the one the SERVER enforces with — only while the argument is still a
+ * `{ dialect: 'cel' }` object. Collapse it to `${source}` first and the
+ * predicate silently falls to the legacy JS evaluator, whose semantics
+ * differ: CEL has no `<` overload for `null`, so `null < null` faults and
+ * fail-closed hides, while JS quietly yields `false`; CEL-only builtins
+ * (`today()`, objectstack#3205) do not exist on the JS path at all. Two
+ * normalizers that disagree on this one branch therefore make the SAME
+ * `visible:` predicate reach different verdicts depending on whether the
+ * action was surfaced by `ActionEngine.getActionsForLocation` or rendered
+ * standalone (#3314).
+ *
+ * This is THE implementation, not one of two — `@object-ui/core` is the common
+ * dependency of every consumer, so engine-side code and renderer-side code
+ * share one normalization instead of hand-rolling envelope unwrapping per call
+ * site. `@object-ui/react`'s `toPredicateInput` is a re-export of this function
+ * (since #3367; it used to be an independent twin held in step by a 14-shape
+ * normalization parity table, which is exactly the arrangement the paragraph
+ * above describes the failure mode of). What pins that now is the identity
+ * assertion in
+ * `packages/react/src/hooks/__tests__/actionPredicate.parity.test.tsx` — the
+ * react export must BE this function object — alongside the engine-path vs
+ * renderer-path verdict parity suite in the same file, which is a separate
+ * claim and still earns its keep: sharing a normalizer does not by itself
+ * prove the two call paths reach the same verdict.
+ */
+export function toPredicateInput(value) {
+    if (value === null || value === undefined || value === '')
+        return undefined;
+    if (typeof value === 'boolean')
+        return value;
+    if (typeof value === 'string')
+        return `\${${value}}`;
+    if (typeof value === 'object' && typeof value.source === 'string') {
+        const src = value.source;
+        if (!src)
+            return undefined;
+        // Preserve a CEL-dialect envelope so `evaluateCondition` routes it to the
+        // canonical `@objectstack/formula` engine (identical verdict to the
+        // server) instead of collapsing it onto the legacy JS path.
+        if (value.dialect === 'cel')
+            return { dialect: 'cel', source: src };
+        // Every other dialect (template / unset) keeps the legacy `${…}` behavior.
+        return `\${${src}}`;
+    }
+    return undefined;
+}

package/dist/index.d.ts

@@ -48,7 +48,10 @@ export * from './utils/merge-filters.js';
 export * from './utils/compare-to.js';
 export * from './utils/chart-series.js';
 export * from './utils/dataset-format.js';
+export * from './utils/dataset-pivot.js';
 export * from './utils/record-title.js';
 export * from './utils/export-filename.js';
 export * from './utils/reference-keys.js';
+export * from './utils/predicate-record.js';
+export * from './utils/predicate-fields.js';
 export * from './utils/normalize-list-view.js';

package/dist/index.js

@@ -50,7 +50,19 @@ export * from './utils/merge-filters.js';
 export * from './utils/compare-to.js';
 export * from './utils/chart-series.js';
 export * from './utils/dataset-format.js';
+// Pivot lookup-key encoders, shared by every cross-tab renderer so the
+// dashboard widget and the report renderer key their buckets identically
+// (objectstack#5473 / objectstack#5665).
+export * from './utils/dataset-pivot.js';
 export * from './utils/record-title.js';
 export * from './utils/export-filename.js';
 export * from './utils/reference-keys.js';
+// Binds a fetched record into an expression scope the way the SERVER binds it
+// (a relation is its foreign key, never the expanded record) — see
+// `toPredicateRecord` for why an unnormalized one gives the same predicate
+// different verdicts on different surfaces.
+export * from './utils/predicate-record.js';
+// The other half of a view's field appetite: the fields its PREDICATES read,
+// which the column-derived `$select` never asked the server for.
+export * from './utils/predicate-fields.js';
 export * from './utils/normalize-list-view.js';

package/dist/protocols/index.d.ts

@@ -7,6 +7,5 @@
  */
 export * from './DndProtocol.js';
 export * from './KeyboardProtocol.js';
-export * from './NotificationProtocol.js';
 export * from './ResponsiveProtocol.js';
 export * from './SharingProtocol.js';

package/dist/protocols/index.js

@@ -7,6 +7,13 @@
  */
 export * from './DndProtocol.js';
 export * from './KeyboardProtocol.js';
-export * from './NotificationProtocol.js';
+// `NotificationProtocol` removed in the 17.0.0-rc.2 uptake: it bridged
+// `@objectstack/spec/ui`'s `Notification` / `NotificationConfig`, which
+// objectstack#4610 deleted with no successor. The bridge had zero consumers in
+// this repo — the live notification config resolution is
+// `resolveNotificationConfig` in `@object-ui/react`'s `NotificationContext`,
+// which declares its own `NotificationSystemConfig` and is what every surface
+// reads. Re-typing the bridge would have meant re-declaring a vocabulary the
+// spec had just retired (AGENTS.md #0.1).
 export * from './ResponsiveProtocol.js';
 export * from './SharingProtocol.js';

package/dist/query/query-ast.d.ts

@@ -1,14 +1,14 @@
 /**
  * ObjectUI - Query AST Builder
- * Phase 3.3: QuerySchema AST implementation
+ * Phase 3.3: DriverQueryConfig AST implementation
  * ObjectStack Spec v2.0.1: Window functions support
  */
-import type { QueryAST, QuerySchema } from '@object-ui/types';
+import type { SqlQueryAST, DriverQueryConfig } from '@object-ui/types';
 /**
- * Query AST Builder - Converts QuerySchema to AST
+ * Query AST Builder - Converts DriverQueryConfig to AST
  */
 export declare class QueryASTBuilder {
-    build(query: QuerySchema): QueryAST;
+    build(query: DriverQueryConfig): SqlQueryAST;
     private buildSelect;
     private buildFrom;
     private buildWhere;
@@ -26,7 +26,7 @@ export declare class QueryASTBuilder {
      * Build window function node (ObjectStack Spec v2.0.1)
      */
     private buildWindow;
-    optimize(ast: QueryAST): QueryAST;
+    optimize(ast: SqlQueryAST): SqlQueryAST;
 }
 export declare const defaultQueryASTBuilder: QueryASTBuilder;
-export declare function buildQueryAST(query: QuerySchema): QueryAST;
+export declare function buildQueryAST(query: DriverQueryConfig): SqlQueryAST;

package/dist/query/query-ast.js

@@ -1,10 +1,10 @@
 /**
  * ObjectUI - Query AST Builder
- * Phase 3.3: QuerySchema AST implementation
+ * Phase 3.3: DriverQueryConfig AST implementation
  * ObjectStack Spec v2.0.1: Window functions support
  */
 /**
- * Query AST Builder - Converts QuerySchema to AST
+ * Query AST Builder - Converts DriverQueryConfig to AST
  */
 export class QueryASTBuilder {
     build(query) {

package/dist/registry/PluginSystem.d.ts

@@ -7,7 +7,17 @@
  */
 import type { Registry } from './Registry.js';
 import type { PluginScope, PluginScopeConfig, AppMetadataPlugin, AppPluginContext } from '@object-ui/types';
-export interface PluginDefinition {
+/**
+ * A plugin for objectui's component REGISTRY: it declares its name/version and
+ * a `register(registry | scope)` callback that contributes renderers.
+ *
+ * NOT the spec's `PluginDefinition` (`@objectstack/spec/kernel`), whose name
+ * this interface carried until objectstack#4115. That one is the platform
+ * PACKAGE manifest — `{ id?, type?, slug?, staticPath?, version?, author?,
+ * homepage?, onInstall?, onEnable?, … }` — a marketplace/install-time document
+ * with no `register` seam, and it shares no required member with this type.
+ */
+export interface RegistryPluginDefinition {
     name: string;
     version: string;
     dependencies?: string[];
@@ -28,7 +38,7 @@ export declare class PluginSystem {
      * @param useScope Whether to use scoped loading (default: true for better isolation)
      * @throws Error if dependencies are missing
      */
-    loadPlugin(plugin: PluginDefinition, registry: Registry, useScope?: boolean): Promise<void>;
+    loadPlugin(plugin: RegistryPluginDefinition, registry: Registry, useScope?: boolean): Promise<void>;
     /**
      * Unload a plugin from the system
      * @param name The name of the plugin to unload
@@ -52,7 +62,7 @@ export declare class PluginSystem {
      * @param name The name of the plugin
      * @returns The plugin definition or undefined
      */
-    getPlugin(name: string): PluginDefinition | undefined;
+    getPlugin(name: string): RegistryPluginDefinition | undefined;
     /**
      * Get all loaded plugin names
      * @returns Array of loaded plugin names
@@ -62,11 +72,11 @@ export declare class PluginSystem {
      * Get all plugin definitions
      * @returns Array of all plugin definitions
      */
-    getAllPlugins(): PluginDefinition[];
+    getAllPlugins(): RegistryPluginDefinition[];
     /**
      * Install an AppMetadataPlugin at runtime.
      *
-     * Wraps the plugin as a PluginDefinition, calls its `init()` and `start()`
+     * Wraps the plugin as a RegistryPluginDefinition, calls its `init()` and `start()`
      * lifecycle hooks, and loads it into the system.
      *
      * @param plugin - An AppMetadataPlugin instance

package/dist/registry/PluginSystem.js

@@ -142,7 +142,7 @@ export class PluginSystem {
     /**
      * Install an AppMetadataPlugin at runtime.
      *
-     * Wraps the plugin as a PluginDefinition, calls its `init()` and `start()`
+     * Wraps the plugin as a RegistryPluginDefinition, calls its `init()` and `start()`
      * lifecycle hooks, and loads it into the system.
      *
      * @param plugin - An AppMetadataPlugin instance

package/dist/registry/WidgetRegistry.d.ts

@@ -9,12 +9,12 @@
  * WidgetRegistry - Runtime widget management with auto-discovery.
  *
  * Provides registration, loading, and lookup of runtime widgets
- * described by WidgetManifest objects. Widgets can be loaded from
+ * described by RuntimeWidgetManifest objects. Widgets can be loaded from
  * ES module URLs, provided inline, or resolved from the component registry.
  *
  * @module
  */
-import type { WidgetManifest, ResolvedWidget, WidgetRegistryListener } from '@object-ui/types';
+import type { RuntimeWidgetManifest, ResolvedWidget, WidgetRegistryListener } from '@object-ui/types';
 import type { Registry } from './Registry.js';
 /**
  * Options for creating a WidgetRegistry instance.
@@ -54,11 +54,11 @@ export declare class WidgetRegistry {
      * Register a widget manifest.
      * Does not load the widget; call `load()` to resolve it.
      */
-    register(manifest: WidgetManifest): void;
+    register(manifest: RuntimeWidgetManifest): void;
     /**
      * Register multiple widget manifests at once.
      */
-    registerAll(manifests: WidgetManifest[]): void;
+    registerAll(manifests: RuntimeWidgetManifest[]): void;
     /**
      * Unregister a widget by name.
      */
@@ -66,15 +66,15 @@ export declare class WidgetRegistry {
     /**
      * Get a widget manifest by name.
      */
-    getManifest(name: string): WidgetManifest | undefined;
+    getManifest(name: string): RuntimeWidgetManifest | undefined;
     /**
      * Get all registered widget manifests.
      */
-    getAllManifests(): WidgetManifest[];
+    getAllManifests(): RuntimeWidgetManifest[];
     /**
      * Get manifests filtered by category.
      */
-    getByCategory(category: string): WidgetManifest[];
+    getByCategory(category: string): RuntimeWidgetManifest[];
     /**
      * Check if a widget is registered.
      */

package/dist/registry/WidgetRegistry.js

@@ -244,7 +244,7 @@ export class WidgetRegistry {
                 // source.url is only known at runtime.
                 //
                 // Security: Widget URLs must be from trusted sources only. Never pass
-                // user-supplied URLs directly to WidgetManifest. URLs should be validated
+                // user-supplied URLs directly to RuntimeWidgetManifest. URLs should be validated
                 // and controlled by the application developer.
                 //
                 // CSP Consideration: If your application uses strict Content Security Policy,

package/dist/styling/scoped-styles.d.ts

@@ -19,14 +19,20 @@
  * `large` is the unconditional base; `medium`/`small`/`xsmall` are `max-width`
  * overrides.
  */
-export type StyleMap = Record<string, string | number>;
-export interface ResponsiveStyles {
-    /** Unconditional base (desktop-first). */
-    large?: StyleMap;
-    medium?: StyleMap;
-    small?: StyleMap;
-    xsmall?: StyleMap;
-}
+import type { ResponsiveStyles } from '@objectstack/spec/ui';
+/**
+ * `StyleMap` / `ResponsiveStyles` are **owned by the spec** (ADR-0065,
+ * `@objectstack/spec/ui`) and re-exported here, not re-declared.
+ *
+ * They used to be hand-written copies under the spec's own names. Both were
+ * member-for-member identical to the spec's at the time of the burn-down
+ * (objectstack#4115), which is exactly what makes a copy dangerous: it passes
+ * every structural comparison right up until the spec adds a breakpoint or
+ * widens a value type, and the doc comment above claims spec canonicity the
+ * whole time. Binding the names to the spec at compile time is the only form
+ * that cannot drift.
+ */
+export type { StyleMap, ResponsiveStyles } from '@objectstack/spec/ui';
 /** max-width breakpoints (px), mirroring Builder.io's default device sizes. */
 export declare const STYLE_BREAKPOINTS: Record<'medium' | 'small' | 'xsmall', number>;
 /** True when a node actually carries responsive styles worth compiling. */

package/dist/utils/chart-series.d.ts

@@ -26,14 +26,26 @@ export interface ChartResultField {
     label?: string;
     format?: string;
 }
-export interface ChartSeries {
+/**
+ * One renderer-internal series binding produced by {@link buildChartSeries}:
+ * WHICH result-set column to draw and what to call it.
+ *
+ * NOT the spec's `ChartSeries` (`@objectstack/spec/ui`), which this type was
+ * named after until objectstack#4115. That one is the AUTHORED dataset-binding
+ * descriptor — `{ name, label?, type?, color?, stack?, yAxis, variant?,
+ * dashArray?, opacity? }`, where `name` is a measure and no `data` is carried.
+ * A third shape, `ChartDataSeries` in `@object-ui/types` (renamed in the same
+ * burn-down), is the inline static-data series of an SDUI `ChartSchema` node.
+ * Three different concepts; this is the one the chart renderers consume.
+ */
+export interface ChartSeriesBinding {
     dataKey: string;
     label: string;
 }
 export interface ChartSeriesResult {
     data: Array<Record<string, unknown>>;
     xAxisKey: string | undefined;
-    series: ChartSeries[];
+    series: ChartSeriesBinding[];
 }
 export declare function buildChartSeries(rows: Array<Record<string, unknown>> | null | undefined, dimensions: string[] | null | undefined, values: string[] | null | undefined, fields?: ChartResultField[] | null): ChartSeriesResult;
 /**

package/dist/utils/dashboard-filters.d.ts

@@ -78,6 +78,15 @@ export declare function dashboardFilterVariableDefs(defs: DashboardFilterDef[]):
  * Build the operator shape (the value side of a `FilterCondition` entry) for
  * one filter's current value. Returns `undefined` when the value imposes no
  * constraint. The caller keys the result by the bound field name.
+ *
+ * A `date`/`dateRange` value is held to three spellings (#3151): a known
+ * preset name → range bounds; a date-macro token or ISO date → equality on
+ * that day; **anything else → skipped with a console warning**, never
+ * silently downgraded to an equality nothing can match. That last branch is
+ * the same strictness `buildWidgetScopedFilter` applies to a default binding
+ * on an unknown field name, for the same reason: a query the backend answers
+ * `200 OK` with zero rows is indistinguishable from "this range has no data",
+ * so the typo has to be said out loud somewhere.
  */
 export declare function buildFilterCondition(def: DashboardFilterDef, value: unknown): Record<string, unknown> | unknown | undefined;
 /**