@object-ui/core 17.2.0 → 17.5.0

package/dist/evaluator/fieldRules.js

@@ -22,8 +22,46 @@
  * 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.
+ * field editable).
+ *
+ * Fail-open agrees with the server for MOST faults — but not for all, and the
+ * exception is the half worth knowing. Since objectstack#4889 a `readonlyWhen`
+ * predicate that faults because it names a scope ROOT the write never bound —
+ * `parent.status == 'paid'` with no master-detail header in hand — is
+ * fail-CLOSED on the server: `isReadonlyWhenLocked` warns and then returns
+ * TRUE, i.e. LOCKED (a declared lock is not waived merely because it could not
+ * be evaluated), and `stripReadonlyWhenFields` — plus
+ * `stripReadonlyWhenFieldsMulti` on the bulk path — DELETES that key from the
+ * UPDATE payload. This file keeps the same fault fail-OPEN. For that one class
+ * the two ends therefore point in OPPOSITE directions, deliberately: the
+ * framework's ADR-0057 D10 — server enforces, client is courtesy (framework
+ * numbering; this repo's own ADR-0057 is an unrelated document) — makes the
+ * server the authority, so the courtesy layer does not get to guess "locked"
+ * and grey out a field the server might have accepted.
+ *
+ * The caller-visible consequence, spelled out because the symptom is silent:
+ * the form renders the field EDITABLE, the user edits it, the save reports
+ * SUCCESS, and the new value never lands — the server dropped the key and kept
+ * the persisted one. Debug that toward the SERVER-side lock (its `… treating
+ * the field as LOCKED` warning, and the write response's `droppedFields`), not
+ * toward the client predicate, which did exactly what it was asked to. The
+ * other two halves carry no such carve-out: `requiredWhen` binds the same
+ * `parent` scope but deliberately kept fail-open semantics (objectstack#4977),
+ * so an unevaluable requirement is skipped on BOTH ends, and field-level
+ * `visibleWhen` is not a server concept at all.
+ *
+ * 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 for the faults where
+ * the two ends DO agree (`readonlyWhen for 'x' failed to evaluate — change
+ * allowed through` — the GENERIC-fault message; the unbound-root fault above
+ * logs `treating the field as LOCKED` instead). 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 +70,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,23 +104,47 @@ 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);
+    // The two fault sources — a not-ok verdict and a throw that slipped past the
+    // engine's "never throws" contract — converge on one reason string and one
+    // reporting site below, so the built-in warning and the `onFault` passback
+    // can never describe the failure differently.
+    let reason;
+    let value = fallback;
     try {
-        const res = ExpressionEngine.evaluate(toExpression(pred), {
+        const res = ExpressionEngine.evaluate(expr, {
             record,
             previous,
             ...(scope ? { extra: scope } : {}),
         });
+        // Parse error, type error, unbound identifier, engine fault … — every
+        // not-ok verdict resolves to the fallback, but never silently (#5149).
         if (!res.ok)
-            return fallback;
-        return res.value === true;
+            reason = `[${res.error.kind}] ${res.error.message}`;
+        else
+            value = res.value === true;
     }
-    catch {
+    catch (err) {
+        reason = `[throw] ${err instanceof Error ? err.message : String(err)}`;
+    }
+    if (reason !== undefined) {
+        if (diagnostic?.warn !== false) {
+            warnPredicateFailure(expr, fallback, reason, diagnostic?.context);
+        }
+        // Outside the try on purpose: a throwing callback is a caller bug and must
+        // surface as one, not be swallowed and re-reported as an engine fault.
+        diagnostic?.onFault?.(reason);
         return fallback;
     }
+    return value;
 }
 /**
  * Resolve the effective `{ visible, readonly, required }` state for a field
@@ -70,18 +152,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,8 @@
  */
 export * from './ExpressionContext.js';
 export * from './ExpressionEvaluator.js';
+export * from './predicateInput.js';
+export * from './declaredPredicate.js';
 export * from './fieldRules.js';
 export * from './listConditional.js';
 export * from './optionRules.js';

package/dist/evaluator/index.js

@@ -7,6 +7,8 @@
  */
 export * from './ExpressionContext.js';
 export * from './ExpressionEvaluator.js';
+export * from './predicateInput.js';
+export * from './declaredPredicate.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}. */
@@ -43,12 +44,21 @@ export interface RowPredicateOptions {
      * row-action `visible`/`disabled`; `false` (no style) for formatting. */
     fallback?: boolean;
     /** Extra top-level scope merged alongside the row — e.g. the global predicate
-     * scope (`features` / `user` / `app`) a host shell provides. */
+     * scope (`features` / `user` / `app`) a host shell provides. The row wins on
+     * collision: a `record` or `data` key here never shadows the row. */
     scope?: Record<string, unknown>;
     /** When true, log a one-time warning if a *present* predicate faults. */
     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
@@ -56,7 +66,9 @@ export interface RowPredicateOptions {
  * fields are bound three ways so every authoring convention resolves:
  * `record.status` (spec/canonical), bare `status` (row-action shorthand), and
  * `data.status` (legacy). The optional `scope` (host predicate scope) is bound
- * alongside so `features.*` / `user.*` predicates keep working.
+ * alongside so `features.*` / `user.*` predicates keep working — but the row is
+ * the subject: `record` and `data` always name THIS row, on both dialect paths,
+ * even when the host scope carries keys of those names (objectui#3796).
  */
 export declare function evalRowPredicate(pred: FieldRulePredicate | undefined | null, row: Record<string, unknown> | null | undefined, opts?: RowPredicateOptions): boolean;
 /** A conditional-formatting rule in any of the three historical shapes. */
@@ -89,5 +101,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,132 @@
+/**
+ * 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`  → a BARE expression is wrapped as `${string}` (legacy DX
+ *     shorthand); a string that is already a `${…}` template is ALREADY in the
+ *     normalized shape and is returned untouched (objectui#3871, below).
+ *   - `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).
+ *
+ * ## Why an already-`${…}` string is NOT wrapped again (objectui#3871)
+ *
+ * `${…}` is one of the spellings this repo documents for a predicate
+ * (AGENTS.md §4: `hidden?: string; // expression: "${data.role != 'admin'}"`)
+ * AND one of the shapes {@link EvaluatorPredicateInput} lists as a normalized
+ * OUTPUT. Wrapping unconditionally therefore corrupted every value that was
+ * already normalized: `'${x}'` became `'${${x}}'`, which no longer matches
+ * `ExpressionEvaluator`'s single-template fast path (`/^\$\{([^}]+)\}$/` —
+ * `[^}]+` cannot cross the inner `}`), so it fell to the global replace, whose
+ * inner expression `'${x'` does not parse. The verdict then stopped depending
+ * on the predicate at all, in a direction set by the CALLER's error policy:
+ *
+ *   - fail-soft callers (every `disabled` / `enabled` leg, and the `visible`
+ *     legs of `action:group` / `action:icon` / `RelatedList`) got the original
+ *     non-empty string back from the evaluator's `catch { return match }`, so
+ *     `Boolean(…)` was a constant `true` — `disabled` greyed out forever,
+ *     `visible` shown forever, `enabled` never disabling.
+ *   - fail-closed callers (`throwOnError: true` — `action:button` / `action:bar`
+ *     / `action:menu` / `DeclaredActionsBar` `visible`, and
+ *     `ActionEngine.getActionsForLocation`) got a THROW, so the constant was
+ *     the other one: the action was hidden forever, including when its
+ *     predicate held.
+ *
+ * Either way the author's expression was never consulted. The guard is
+ * `includes('${')` — "does this string already carry template syntax", the
+ * same question `evaluateCondition` itself asks before choosing the template
+ * path — not an anchored full match: a multi-part string like `'a ${x} b'` is
+ * not a predicate in any spelling, and wrapping it produced the same constant
+ * verdict, so the narrower guard would buy nothing and would still corrupt a
+ * value the evaluator can read.
+ *
+ * The same guard covers the envelope branch below, where the unwrapped
+ * `source` reaches the identical wrap one line later. It is one defect with two
+ * spellings, and `{ dialect: 'template', source: '${x}' }` is the shape a
+ * producer that compiles an authored template emits. A bare `source` (what
+ * `@objectstack/spec`'s `ExpressionInputSchema` produces today, pinned in
+ * `packages/react/src/hooks/__tests__/useExpression.test.ts`) is unaffected.
+ *
+ * What this does NOT do is decide whether `${…}` SHOULD be authorable on an
+ * action predicate: `@objectstack/spec`'s `PredicateInput` models a bare string
+ * and a dialect envelope, not the template spelling. Rejecting it loudly at
+ * publish time is a spec-side ruling (deferred to the objectstack seat by the
+ * objectui#3871 dispatch); until then this normalizer must not silently invent
+ * a verdict for a spelling both the docs and this file's own output type bless.
+ *
+ * What pins the single implementation 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,129 @@
+/**
+ * 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.
+ */
+/**
+ * Wrap a BARE expression as a `${…}` template, and leave a string that already
+ * carries template syntax alone (objectui#3871 — rationale in
+ * {@link toPredicateInput}'s doc below). One rule, so the two string spellings
+ * inside the normalizer cannot drift apart.
+ */
+function wrapIfBare(expression) {
+    return expression.includes('${') ? expression : `\${${expression}}`;
+}
+/**
+ * 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`  → a BARE expression is wrapped as `${string}` (legacy DX
+ *     shorthand); a string that is already a `${…}` template is ALREADY in the
+ *     normalized shape and is returned untouched (objectui#3871, below).
+ *   - `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).
+ *
+ * ## Why an already-`${…}` string is NOT wrapped again (objectui#3871)
+ *
+ * `${…}` is one of the spellings this repo documents for a predicate
+ * (AGENTS.md §4: `hidden?: string; // expression: "${data.role != 'admin'}"`)
+ * AND one of the shapes {@link EvaluatorPredicateInput} lists as a normalized
+ * OUTPUT. Wrapping unconditionally therefore corrupted every value that was
+ * already normalized: `'${x}'` became `'${${x}}'`, which no longer matches
+ * `ExpressionEvaluator`'s single-template fast path (`/^\$\{([^}]+)\}$/` —
+ * `[^}]+` cannot cross the inner `}`), so it fell to the global replace, whose
+ * inner expression `'${x'` does not parse. The verdict then stopped depending
+ * on the predicate at all, in a direction set by the CALLER's error policy:
+ *
+ *   - fail-soft callers (every `disabled` / `enabled` leg, and the `visible`
+ *     legs of `action:group` / `action:icon` / `RelatedList`) got the original
+ *     non-empty string back from the evaluator's `catch { return match }`, so
+ *     `Boolean(…)` was a constant `true` — `disabled` greyed out forever,
+ *     `visible` shown forever, `enabled` never disabling.
+ *   - fail-closed callers (`throwOnError: true` — `action:button` / `action:bar`
+ *     / `action:menu` / `DeclaredActionsBar` `visible`, and
+ *     `ActionEngine.getActionsForLocation`) got a THROW, so the constant was
+ *     the other one: the action was hidden forever, including when its
+ *     predicate held.
+ *
+ * Either way the author's expression was never consulted. The guard is
+ * `includes('${')` — "does this string already carry template syntax", the
+ * same question `evaluateCondition` itself asks before choosing the template
+ * path — not an anchored full match: a multi-part string like `'a ${x} b'` is
+ * not a predicate in any spelling, and wrapping it produced the same constant
+ * verdict, so the narrower guard would buy nothing and would still corrupt a
+ * value the evaluator can read.
+ *
+ * The same guard covers the envelope branch below, where the unwrapped
+ * `source` reaches the identical wrap one line later. It is one defect with two
+ * spellings, and `{ dialect: 'template', source: '${x}' }` is the shape a
+ * producer that compiles an authored template emits. A bare `source` (what
+ * `@objectstack/spec`'s `ExpressionInputSchema` produces today, pinned in
+ * `packages/react/src/hooks/__tests__/useExpression.test.ts`) is unaffected.
+ *
+ * What this does NOT do is decide whether `${…}` SHOULD be authorable on an
+ * action predicate: `@objectstack/spec`'s `PredicateInput` models a bare string
+ * and a dialect envelope, not the template spelling. Rejecting it loudly at
+ * publish time is a spec-side ruling (deferred to the objectstack seat by the
+ * objectui#3871 dispatch); until then this normalizer must not silently invent
+ * a verdict for a spelling both the docs and this file's own output type bless.
+ *
+ * What pins the single implementation 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 wrapIfBare(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 wrapIfBare(src);
+    }
+    return undefined;
+}

package/dist/index.d.ts

@@ -13,12 +13,15 @@ export * from './registry/PluginScopeImpl.js';
 export * from './registry/WidgetRegistry.js';
 export * from './validation/index.js';
 export * from './builder/schema-builder.js';
+export * from './utils/dom-props.js';
 export * from './utils/filter-converter.js';
 export * from './utils/managedBy.js';
 export * from './utils/extract-records.js';
 export * from './utils/expand-fields.js';
 export * from './utils/column-identity.js';
 export * from './utils/sort-values.js';
+export * from './utils/sort-query.js';
+export * from './utils/resolve-view-id.js';
 export * from './evaluator/index.js';
 export * from './actions/index.js';
 export * from './query/index.js';
@@ -28,7 +31,6 @@ export * from './data-scope/index.js';
 export * from './errors/index.js';
 export * from './utils/debug.js';
 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';
@@ -47,8 +49,12 @@ export * from './utils/dashboard-filters.js';
 export * from './utils/merge-filters.js';
 export * from './utils/compare-to.js';
 export * from './utils/chart-series.js';
+export * from './utils/number-display.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

@@ -12,12 +12,20 @@ export * from './registry/PluginScopeImpl.js';
 export * from './registry/WidgetRegistry.js';
 export * from './validation/index.js';
 export * from './builder/schema-builder.js';
+// The DOM pass-through whitelist of the SDUI widget prop contract
+// (objectui#4425 phase 2): a registered widget's host element receives only
+// what `toDomProps` passes — everything else is consumed or dropped.
+// `@object-ui/fields` executes the SAME mechanism against its own declared key
+// list (`pickDomProps`), so there is one judge, not two.
+export * from './utils/dom-props.js';
 export * from './utils/filter-converter.js';
 export * from './utils/managedBy.js';
 export * from './utils/extract-records.js';
 export * from './utils/expand-fields.js';
 export * from './utils/column-identity.js';
 export * from './utils/sort-values.js';
+export * from './utils/sort-query.js';
+export * from './utils/resolve-view-id.js';
 export * from './evaluator/index.js';
 export * from './actions/index.js';
 export * from './query/index.js';
@@ -27,7 +35,6 @@ export * from './data-scope/index.js';
 export * from './errors/index.js';
 export * from './utils/debug.js';
 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';
@@ -49,8 +56,26 @@ export * from './utils/dashboard-filters.js';
 export * from './utils/merge-filters.js';
 export * from './utils/compare-to.js';
 export * from './utils/chart-series.js';
+// The ONE number-display formatter (objectui#4033) — grouping policy, display
+// locale and the percent convention. It lived in `@object-ui/i18n` until
+// objectui#4576; it is pure, and living above `core` was what kept
+// `dataset-format` below from reaching it (so the two drifted). `@object-ui/i18n`
+// re-exports these names unchanged, so both import paths name the same symbol.
+export * from './utils/number-display.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/DndProtocol.d.ts

@@ -14,7 +14,48 @@
  * @module protocols/DndProtocol
  * @packageDocumentation
  */
-import type { DndConfig, DragItem, DropZone, DragConstraint } from '@object-ui/types';
+/** How a drag is initiated. */
+export type DragHandle = 'element' | 'handle' | 'grip_icon';
+/** The `dropEffect` advertised to assistive technology and DnD libraries. */
+export type DropEffect = 'none' | 'link' | 'move' | 'copy';
+/** Movement constraints applied to a drag. */
+export interface DragConstraint {
+    axis: 'x' | 'y' | 'both';
+    bounds: 'none' | 'parent' | 'viewport';
+    grid?: [number, number];
+}
+/** A draggable item's declaration. */
+export interface DragItem {
+    type: string;
+    label?: string;
+    handle: DragHandle;
+    constraint?: DragConstraint;
+    preview: 'custom' | 'none' | 'element';
+    disabled: boolean;
+    ariaLabel?: string;
+    ariaDescribedBy?: string;
+    role?: string;
+}
+/** A drop target's declaration. */
+export interface DropZone {
+    label?: string;
+    accept: string[];
+    maxItems?: number;
+    highlightOnDragOver: boolean;
+    dropEffect: DropEffect;
+    ariaLabel?: string;
+    ariaDescribedBy?: string;
+    role?: string;
+}
+/** Top-level drag-and-drop configuration. */
+export interface DndConfig {
+    enabled: boolean;
+    dragItem?: DragItem;
+    dropZone?: DropZone;
+    sortable: boolean;
+    autoScroll: boolean;
+    touchDelay: number;
+}
 /** Fully resolved DnD configuration with all defaults applied. */
 export interface ResolvedDndConfig {
     enabled: boolean;