@object-ui/core 17.3.0 → 17.5.0

package/dist/evaluator/listConditional.d.ts

@@ -44,7 +44,8 @@ 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;
@@ -65,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. */

package/dist/evaluator/listConditional.js

@@ -54,27 +54,47 @@ function warnLegacyDialect(source) {
     if (warnedLegacy.has(source))
         return;
     warnedLegacy.add(source);
-    console.warn('[object-ui] A list conditional predicate uses the legacy expression dialect ' +
+    console.warn('[object-ui] A conditional predicate uses the legacy expression dialect ' +
         'and is not portable to the server CEL engine: ' +
         JSON.stringify(source) +
         '. Rewrite it as CEL (use "==" not "===", "x in [..]" for membership, ' +
         '".contains()" not ".includes()", and drop template interpolation).');
 }
 const warnedError = new Set();
-function warnEvalError(source, label) {
+/**
+ * One-time fail-closed report for a predicate that could not be evaluated.
+ *
+ * `reason` is the engine's own description of the failure (`"[runtime] No such
+ * key: owner_id"`) — the single most useful line for the author, and precisely
+ * what this path used to discard: the fault-probing CEL route silences the
+ * canonical helper's warning to avoid double-reporting, so before objectui#3792
+ * the more safety-critical the surface, the LESS it said. It is optional
+ * because a caller may genuinely have no reason to pass (nothing fabricates
+ * one).
+ *
+ * The wording is deliberately surface-neutral: this function is not
+ * list-specific and has not been for a long time — row kebabs, the bulk
+ * selection bar, kanban conditional formatting and (since objectui#3521)
+ * `page:header` all report through it, and telling a page-header author that
+ * "a list conditional predicate" failed sends them to the wrong screen.
+ */
+function warnEvalError(source, label, reason) {
     // One-time-warning identity for the (label, source) pair. JSON-encoded rather
     // than joined on a character the two halves "cannot contain" — that separator
     // was a raw U+0000, which made this whole file binary to grep (objectstack#5450).
     // JSON needs no impossible character, so the boundary is unambiguous for any
     // label and any predicate source, and the literal is plain ASCII.
+    // `reason` is deliberately NOT part of the key: one predicate text has one
+    // reason, so keying on it could only ever weaken the warn-once contract.
     const key = JSON.stringify([label ?? '', source]);
     if (warnedError.has(key))
         return;
     warnedError.add(key);
-    console.warn('[object-ui] A list conditional predicate failed to evaluate' +
+    console.warn('[object-ui] A conditional predicate failed to evaluate' +
         (label ? ` (${label})` : '') +
         ' and was treated as its safe default: ' +
         JSON.stringify(source) +
+        (reason ? `. Reason: ${reason}` : '') +
         '. Check the field names and CEL syntax.');
 }
 /**
@@ -91,11 +111,18 @@ function evalCel(pred, record, scope) {
     // verbatim — no second engine — so CEL semantics never drift from B2.
     // `warn: false`: this caller reports the fault itself (the labelled
     // `warnEvalError` in `evalRowPredicate`) — one warning per broken predicate,
-    // not two (#5149).
-    const asTrue = evalFieldPredicate(pred, record, true, undefined, scope, { warn: false });
-    const asFalse = evalFieldPredicate(pred, record, false, undefined, scope, { warn: false });
+    // not two (#5149). `onFault` carries the engine's reason across that silence
+    // so the labelled report can still name it (objectui#3792); both probes fault
+    // identically, so the first reason is the reason.
+    let reason;
+    const onFault = (r) => {
+        reason ?? (reason = r);
+    };
+    const diagnostic = { warn: false, onFault };
+    const asTrue = evalFieldPredicate(pred, record, true, undefined, scope, diagnostic);
+    const asFalse = evalFieldPredicate(pred, record, false, undefined, scope, diagnostic);
     if (asTrue !== asFalse)
-        return { ok: false, value: false };
+        return { ok: false, value: false, reason };
     return { ok: true, value: asTrue };
 }
 /**
@@ -104,7 +131,9 @@ function evalCel(pred, record, scope) {
  * 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 function evalRowPredicate(pred, row, opts = {}) {
     const fallback = opts.fallback ?? false;
@@ -117,20 +146,33 @@ export function evalRowPredicate(pred, row, opts = {}) {
     // means one thing whether or not this surface expanded the column
     // (objectui#3501). Returned by reference when there is nothing to collapse.
     const rowObj = toPredicateRecord(row && typeof row === 'object' ? row : {}, opts.fields);
-    // Bare fields + `data.*` + the host scope, all top-level; `record` is bound
-    // by the engine call itself (evalCel / the legacy evaluator below).
-    const scope = { ...(opts.scope ?? {}), ...rowObj, data: rowObj };
+    // Bare fields + `data.*` + `record.*` + the host scope, all top-level.
+    //
+    // `data` AND `record` are pinned AFTER the spread, so a host scope that
+    // happens to carry either key is background and the ROW stays the subject of
+    // this function — on BOTH dialect paths. `data` always had that protection;
+    // `record` did not, and relied instead on each engine's own binding, which
+    // disagreed: the legacy evaluator re-pinned `record` (row won) while the CEL
+    // engine takes `extra` over its `record` binding (host scope won). Same
+    // function, same predicate text, opposite subjects — decided by whether the
+    // string happens to contain `===`/`${…}`, which no author is choosing
+    // deliberately (objectui#3796). Pinning here fixes both paths at the merge,
+    // independently of either engine's precedence.
+    const scope = { ...(opts.scope ?? {}), ...rowObj, data: rowObj, record: rowObj };
     // Legacy-dialect *strings* route to the legacy engine (back-compat). The
     // `{ dialect: 'cel', source }` envelope is never routed here — it is CEL.
     if (source !== undefined && isLegacyDialectSource(source)) {
         warnLegacyDialect(source);
         try {
-            const evaluator = new ExpressionEvaluator({ ...scope, record: rowObj });
+            const evaluator = new ExpressionEvaluator(scope);
             return evaluator.evaluateCondition(source, { throwOnError: true });
         }
-        catch {
-            if (opts.warnOnError)
-                warnEvalError(source, opts.label);
+        catch (err) {
+            // The legacy engine reports by throwing, so its message IS the reason —
+            // the fail-closed report carries it for the same reason the CEL path does.
+            if (opts.warnOnError) {
+                warnEvalError(source, opts.label, `[legacy] ${err instanceof Error ? err.message : String(err)}`);
+            }
             return fallback;
         }
     }
@@ -145,7 +187,7 @@ export function evalRowPredicate(pred, row, opts = {}) {
     }
     const verdict = evalCel(pred, rowObj, scope);
     if (!verdict.ok) {
-        warnEvalError(source ?? '(expression)', opts.label);
+        warnEvalError(source ?? '(expression)', opts.label, verdict.reason);
         return fallback;
     }
     return verdict.value;

package/dist/evaluator/predicateInput.d.ts

@@ -44,7 +44,9 @@ export type EvaluatorPredicateInput = string | boolean | {
  *
  * Accepts:
  *   - `boolean` → returned as-is (predicate evaluation short-circuits).
- *   - `string`  → wrapped as `${string}` (legacy DX shorthand).
+ *   - `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
@@ -73,8 +75,54 @@ export type EvaluatorPredicateInput = string | boolean | {
  * 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
+ * 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

package/dist/evaluator/predicateInput.js

@@ -5,6 +5,15 @@
  * 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}
@@ -12,7 +21,9 @@
  *
  * Accepts:
  *   - `boolean` → returned as-is (predicate evaluation short-circuits).
- *   - `string`  → wrapped as `${string}` (legacy DX shorthand).
+ *   - `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
@@ -41,8 +52,54 @@
  * 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
+ * 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
@@ -55,7 +112,7 @@ export function toPredicateInput(value) {
     if (typeof value === 'boolean')
         return value;
     if (typeof value === 'string')
-        return `\${${value}}`;
+        return wrapIfBare(value);
     if (typeof value === 'object' && typeof value.source === 'string') {
         const src = value.source;
         if (!src)
@@ -66,7 +123,7 @@ export function toPredicateInput(value) {
         if (value.dialect === 'cel')
             return { dialect: 'cel', source: src };
         // Every other dialect (template / unset) keeps the legacy `${…}` behavior.
-        return `\${${src}}`;
+        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,6 +49,7 @@ 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';

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,6 +56,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';
+// 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

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;

package/dist/protocols/KeyboardProtocol.d.ts

@@ -15,7 +15,37 @@
  * @module protocols/KeyboardProtocol
  * @packageDocumentation
  */
-import type { KeyboardNavigationConfig, KeyboardShortcut, FocusTrapConfig } from '@object-ui/types';
+/** A single keyboard shortcut binding. */
+export interface KeyboardShortcut {
+    key: string;
+    action: string;
+    description?: string;
+    scope: 'global' | 'form' | 'modal' | 'view' | 'list';
+}
+/** Focus trap declaration for a modal-like region. */
+export interface FocusTrapConfig {
+    enabled: boolean;
+    initialFocus?: string;
+    returnFocus: boolean;
+    escapeDeactivates: boolean;
+}
+/** Focus management declaration. */
+export interface FocusManagement {
+    tabOrder: 'manual' | 'auto';
+    skipLinks: boolean;
+    focusVisible: boolean;
+    focusTrap?: FocusTrapConfig;
+    arrowNavigation: boolean;
+}
+/** Top-level keyboard navigation configuration. */
+export interface KeyboardNavigationConfig {
+    shortcuts?: KeyboardShortcut[];
+    focusManagement?: FocusManagement;
+    rovingTabindex: boolean;
+    ariaLabel?: string;
+    ariaDescribedBy?: string;
+    role?: string;
+}
 /** Fully resolved keyboard navigation configuration. */
 export interface ResolvedKeyboardConfig {
     shortcuts: KeyboardShortcut[];

package/dist/protocols/SharingProtocol.d.ts

@@ -15,7 +15,17 @@
  * @module protocols/SharingProtocol
  * @packageDocumentation
  */
-import type { SharingConfig, EmbedConfig } from '@object-ui/types';
+import type { SharingConfig } from '@object-ui/types';
+/** An iframe embed declaration. */
+export interface EmbedConfig {
+    enabled: boolean;
+    allowedOrigins?: string[];
+    width?: string;
+    height?: string;
+    showHeader?: boolean;
+    showNavigation?: boolean;
+    responsive?: boolean;
+}
 /** Fully resolved sharing configuration. */
 export interface ResolvedSharingConfig {
     enabled: boolean;

package/dist/registry/Registry.d.ts

@@ -43,6 +43,30 @@ export type ComponentMeta = {
      * registry.register('form', FormView, { namespace: 'view', skipFallback: true });
      */
     skipFallback?: boolean;
+    /**
+     * How a HOST must associate its own visible label with what this component
+     * renders (objectui#3961). Read by the form renderer; absent ⇒ `'control'`.
+     *
+     * - `'control'` — the component's outermost rendered element is a LABELABLE
+     *   HTML element (`input` / `textarea` / `select` / `button` / …), so the host
+     *   associates its label the plain way: `<label for>` → the id the host handed
+     *   down. This is the default and covers every single-control widget.
+     * - `'group'` — it is NOT labelable: either a real composite (several inputs
+     *   under one container, e.g. `address`) or a single control that is not a
+     *   labelable element (a `div[role="button"]` dropzone, e.g. `file`). A
+     *   `<label for>` pointing at such an element is inert in HTML — it activates
+     *   nothing and contributes no accessible name (`HTMLLabelElement.control` is
+     *   `null`) — so the host must instead give its label an `id` and hand the
+     *   component `aria-labelledby`, which associates by IDREF and works on any
+     *   element.
+     *
+     * This is a DECLARATION, not a guess: the host cannot infer it from the DOM a
+     * widget happens to render, and a widget that fails to declare it falls back
+     * to the `'control'` path where the dangling/inert `for` is caught by the
+     * label-association tests (objectui#3952) instead of silently producing an
+     * unlabelled group.
+     */
+    labelling?: 'control' | 'group';
     inputs?: ComponentInput[];
     defaultProps?: Record<string, any>;
     defaultChildren?: SchemaNode[];

package/dist/theme/ThemeEngine.d.ts

@@ -43,14 +43,6 @@ export declare function generateBorderRadiusVars(borderRadius: NonNullable<Theme
  * Generate CSS custom properties from a Theme's shadow config.
  */
 export declare function generateShadowVars(shadows: NonNullable<Theme['shadows']>): Record<string, string>;
-/**
- * Generate CSS custom properties from a Theme's animation config.
- */
-export declare function generateAnimationVars(animation: NonNullable<Theme['animation']>): Record<string, string>;
-/**
- * Generate CSS custom properties from a Theme's z-index config.
- */
-export declare function generateZIndexVars(zIndex: NonNullable<Theme['zIndex']>): Record<string, string>;
 /**
  * Generate ALL CSS custom properties from a complete Theme.
  * This is the main entry point for theme → CSS conversion.