@object-ui/react 17.6.0 → 18.0.0

package/dist/index.js

@@ -10,15 +10,62 @@ export * from './schema-input.js';
 export * from './hooks/index.js'; // will be empty for now
 export * from './context/index.js'; // will be empty for now
 export * from './LazyPluginLoader.js';
-export * from './spec-bridge/index.js';
 export * from './data-invalidation.js';
 // PageComponentSchema.dataSource — mapping the spec's per-element data binding
 // onto the schema keys each object-bound block reads (objectstack#6953).
 export * from './element-data-source/ElementDataSourceGate.js';
+// PageComponentSchema.dataSource as the spec's API binding — the read behind
+// the `data` root `SchemaRenderer` binds for it (objectui#12197).
+export * from './element-data-source/useElementApiDataSource.js';
 // i18n utilities
 export { resolveKeyedI18nLabel } from './utils/i18n.js';
+// The spec's NESTED `aria` bag (`AriaPropsSchema`) → `aria-label` /
+// `aria-describedby` / `role`, with `ariaLabel` resolved as an inline locale
+// map (objectui#11051). Exported for the renderers in `@object-ui/components`,
+// which depends on this package, so the mapping is written once. It is not the
+// flat keyed reader `SchemaRenderer` applies to every node; objectui#4580 Q2-B
+// keeps the two vocabularies apart.
+export { resolveInlineAriaProps } from './utils/inlineAria.js';
+// "Is this a real config bag?" — the ONE definition of that question
+// (objectui#6761), exported at the package entry for the same reason the node-gate
+// reporter above is (objectui#6038): a surface in `@object-ui/components`, which
+// depends on this package, asks it too. `element:*` renderers there read their
+// config out of `{ ...schema.props, ...schema.properties }`, the third channel of
+// the degenerate-bag hazard objectui#6752 / objectui#6760 closed here
+// (objectui#6783). A second copy one package over would be a spelling that
+// `utils/configBag.pin.test.ts` — which scans `packages/react/src` — cannot see,
+// which is the drift that pin exists to stop.
+export { isConfigBag } from './utils/configBag.js';
+// Node-gate predicate diagnostics. Exported at the package entry (objectui#6038)
+// so every surface that evaluates a node `visibleWhen` reports a fault through
+// ONE reporter and ONE dedupe `Set` — `page:tabs` item predicates live in
+// `@object-ui/components`, which depends on this package. A second copy of the
+// reporter would mean a second rate limit, and the same broken predicate would
+// then be entitled to one line per package instead of one line, which is the
+// property the 2026-08-25 ruling asked for.
+export { reportUnresolvableVisibilityPredicate, formatUnresolvableVisibilityMessage, UNRESOLVABLE_VISIBILITY_PREFIX, 
+// The ENABLEMENT gate's opening line (objectui#6445). Exported beside its
+// sibling for the reason that one is: an app filtering these out of its
+// console transport filters by the constant, and a second line it cannot
+// name is a second thing to hard-code. Not a second reporter — the emit,
+// the dedupe `Set` and the reset above are still the only ones.
+UNRESOLVABLE_ENABLEMENT_PREFIX, __resetVisibilityPredicateWarnings, } from './utils/visibilityDiagnostic.js';
 // Write-error surfacing utilities (shared by drag-write plugins so a failed
 // PATCH — e.g. an RLS 403 — is never silently swallowed).
 export { extractWriteErrorMessage, isPermissionError, extractFieldErrors, classifyLoadError, declaredUserMessage } from './utils/error-message.js';
 // Built-in i18n support
 export { I18nProvider, useObjectTranslation, useSafeTranslate, useObjectLabel, useSafeFieldLabel, useI18nContext, createI18n, getDirection, getAvailableLanguages, formatDate, formatDateTime, formatRelativeTime, formatCurrency, formatNumber, } from '@object-ui/i18n';
+// The platform row ceiling for NON-GRID visualisations — gantt, calendar, map
+// and tree (objectui#7210, maintainer ruling a′). One constant across the
+// four, because a per-plugin copy would be four constants wearing one name,
+// which is the thing the ruling ruled out.
+//
+// HOME: `@object-ui/core`, beside the `extractRecords` it wraps (objectui#7508,
+// maintainer ruling A′). This entry re-exports the three names it published
+// first, the same way it re-exports `@object-ui/i18n` above, and keeps only
+// the React half — `NonGridRowCeilingNote`, which takes the
+// `NonGridCeilingResult` and nothing else. The probe row's `+ 1` lives in
+// core's `nonGridRowCeilingQuery()` and nowhere else; the constant that used
+// to carry it here is deleted, not re-exported.
+export { NON_GRID_ROW_CEILING, applyNonGridRowCeiling } from '@object-ui/core';
+export { NonGridRowCeilingNote } from './utils/nonGridRowCeiling.js';

package/dist/schema-input.d.ts

@@ -5,23 +5,53 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import type { BaseSchema } from '@object-ui/types';
+import type { SchemaNode } from '@object-ui/types';
 import type { SchemaRendererProps } from './SchemaRenderer.js';
 /**
  * Narrow a loosely-typed metadata node onto {@link SchemaRendererProps.schema}.
  *
  * `@object-ui/types` declares `SchemaNode` as
- * `BaseSchema | string | number | boolean | null | undefined`, and a lot of
- * metadata plumbing (page regions, header-bar actions, detail tabs, view
+ * `DeclaredNode | string | number | boolean | null | undefined` (its object
+ * arm the declared-node union, objectui#11466), and a lot of metadata plumbing (page regions, header-bar actions, detail tabs, view
  * configs) is typed with it. `SchemaRenderer` deliberately does NOT declare the
  * `number` / `boolean` members — nobody should be invited to author them — so
  * forwarding such a value needs one honest step in between.
  *
  * This is that step, and it is a TOTAL function rather than a cast: it maps the
- * two primitive members onto their text form, which is precisely what the
- * renderer's own defensive branch does with them. So it changes no behaviour and
- * tells no lie — the value a caller forwards renders identically whether or not
- * it passes through here.
+ * two primitive members onto whatever `SchemaRenderer` would itself render for
+ * them. So it changes no behaviour and tells no lie — the value a caller
+ * forwards renders identically whether or not it passes through here.
+ *
+ * ## Why the mapping has TWO legs and not one
+ *
+ * Because the renderer's own narrowing has two, in a fixed order: the
+ * `!evaluatedSchema` leg returns nothing and runs FIRST, and only below it does
+ * the defensive branch return the value's `String` form. So the falsy
+ * primitives — `0`, `-0`, `NaN`, `false` — never reach that branch at all; they
+ * render as nothing. `!node` is exactly that set for the two members this
+ * function converts, so the ternary below IS the renderer's order, restated for
+ * a value that has to cross the type boundary as a string.
+ *
+ * ⚠️ The single-leg `String(node)` that stood here until objectui#8908 was the
+ * lie this paragraph used to tell. `String(0)` and `String(false)` are the
+ * NON-EMPTY strings `'0'` and `'false'`, which are truthy, so they sailed past
+ * the renderer's first leg and printed themselves — while the same two values
+ * handed to `SchemaRenderer` directly render nothing, pinned since
+ * objectui#4548 in `packages/react/src/__tests__/SchemaRenderer.primitiveSchema.test.tsx`.
+ * The shipped `empty` renderer, whose `action` slot gates on nullish rather than
+ * truthiness, printed a stray `0` for `{ type: 'empty', action: 0 }` because of
+ * it. ⛔ Do not "simplify" the two legs back into one.
+ *
+ * ## Why the falsy leg returns nothing rather than the value itself
+ *
+ * Passing `0` / `false` through UNCHANGED would widen this function's return
+ * type to admit `number` / `boolean`, and that is not a free choice: the return
+ * type is pinned exactly equal to `SchemaRendererProps['schema']` by
+ * `packages/react/src/__tests__/SchemaRenderer.propsResolution.test.ts`, which
+ * also pins that the prop admits NEITHER member (objectui#4548 ruling Q2). A
+ * widened return would therefore be a TS2322 at every call site that forwards
+ * it straight into `<SchemaRenderer schema={…} />`, which is all of them. The
+ * nullish leg is the spelling that keeps the guarantee and the type both.
  *
  * The bridge is PERMANENT — not scaffolding awaiting a merge. The two competing
  * repo-wide `SchemaNode` spellings ARE reconciled (objectui#4580, PR #4608):
@@ -39,4 +69,4 @@ import type { SchemaRendererProps } from './SchemaRenderer.js';
  * PR #4621 routed all five through here. An earlier revision of this paragraph
  * said the reconciliation was still pending and invited exactly that edit.
  */
-export declare function toRenderableSchema(node: BaseSchema | string | number | boolean | null | undefined): SchemaRendererProps['schema'];
+export declare function toRenderableSchema(node: SchemaNode): SchemaRendererProps['schema'];

package/dist/schema-input.js

@@ -9,17 +9,47 @@
  * Narrow a loosely-typed metadata node onto {@link SchemaRendererProps.schema}.
  *
  * `@object-ui/types` declares `SchemaNode` as
- * `BaseSchema | string | number | boolean | null | undefined`, and a lot of
- * metadata plumbing (page regions, header-bar actions, detail tabs, view
+ * `DeclaredNode | string | number | boolean | null | undefined` (its object
+ * arm the declared-node union, objectui#11466), and a lot of metadata plumbing (page regions, header-bar actions, detail tabs, view
  * configs) is typed with it. `SchemaRenderer` deliberately does NOT declare the
  * `number` / `boolean` members — nobody should be invited to author them — so
  * forwarding such a value needs one honest step in between.
  *
  * This is that step, and it is a TOTAL function rather than a cast: it maps the
- * two primitive members onto their text form, which is precisely what the
- * renderer's own defensive branch does with them. So it changes no behaviour and
- * tells no lie — the value a caller forwards renders identically whether or not
- * it passes through here.
+ * two primitive members onto whatever `SchemaRenderer` would itself render for
+ * them. So it changes no behaviour and tells no lie — the value a caller
+ * forwards renders identically whether or not it passes through here.
+ *
+ * ## Why the mapping has TWO legs and not one
+ *
+ * Because the renderer's own narrowing has two, in a fixed order: the
+ * `!evaluatedSchema` leg returns nothing and runs FIRST, and only below it does
+ * the defensive branch return the value's `String` form. So the falsy
+ * primitives — `0`, `-0`, `NaN`, `false` — never reach that branch at all; they
+ * render as nothing. `!node` is exactly that set for the two members this
+ * function converts, so the ternary below IS the renderer's order, restated for
+ * a value that has to cross the type boundary as a string.
+ *
+ * ⚠️ The single-leg `String(node)` that stood here until objectui#8908 was the
+ * lie this paragraph used to tell. `String(0)` and `String(false)` are the
+ * NON-EMPTY strings `'0'` and `'false'`, which are truthy, so they sailed past
+ * the renderer's first leg and printed themselves — while the same two values
+ * handed to `SchemaRenderer` directly render nothing, pinned since
+ * objectui#4548 in `packages/react/src/__tests__/SchemaRenderer.primitiveSchema.test.tsx`.
+ * The shipped `empty` renderer, whose `action` slot gates on nullish rather than
+ * truthiness, printed a stray `0` for `{ type: 'empty', action: 0 }` because of
+ * it. ⛔ Do not "simplify" the two legs back into one.
+ *
+ * ## Why the falsy leg returns nothing rather than the value itself
+ *
+ * Passing `0` / `false` through UNCHANGED would widen this function's return
+ * type to admit `number` / `boolean`, and that is not a free choice: the return
+ * type is pinned exactly equal to `SchemaRendererProps['schema']` by
+ * `packages/react/src/__tests__/SchemaRenderer.propsResolution.test.ts`, which
+ * also pins that the prop admits NEITHER member (objectui#4548 ruling Q2). A
+ * widened return would therefore be a TS2322 at every call site that forwards
+ * it straight into `<SchemaRenderer schema={…} />`, which is all of them. The
+ * nullish leg is the spelling that keeps the guarantee and the type both.
  *
  * The bridge is PERMANENT — not scaffolding awaiting a merge. The two competing
  * repo-wide `SchemaNode` spellings ARE reconciled (objectui#4580, PR #4608):
@@ -38,5 +68,7 @@
  * said the reconciliation was still pending and invited exactly that edit.
  */
 export function toRenderableSchema(node) {
-    return typeof node === 'number' || typeof node === 'boolean' ? String(node) : node;
+    return typeof node === 'number' || typeof node === 'boolean'
+        ? (node ? String(node) : undefined)
+        : node;
 }

package/dist/utils/configBag.d.ts

@@ -0,0 +1,68 @@
+/**
+ * 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.
+ */
+/**
+ * Is this value a real config bag — an object, and not an array pretending to
+ * be one? (objectui#6761)
+ *
+ * This is the ONE definition of that question in `@object-ui/react`, and it
+ * lives here rather than in whichever module happened to need it first,
+ * because every module that asks it is a CONSUMER of the same authored shape:
+ * the `properties` / `props` bags a node may carry. `typeof null === 'object'`
+ * is covered by the truthiness test.
+ *
+ * ## Why one definition, when all the copies agreed
+ *
+ * They agreed; that was never the cost. The cost is that disagreement between
+ * them produces NO error — each copy is a boolean expression, and a copy that
+ * drifts answers a different question on ONE channel while every other channel
+ * keeps the old answer. That is the same failure mode `hasDeclaredPredicate`
+ * (`@object-ui/core`) was created to end for "is a gate DECLARED?", which had
+ * three spellings with three different SCOPES before objectui#3850 —
+ * `disabled: null` greying a control out on one path and not another
+ * (objectui#3862).
+ *
+ * ## The spellings this replaces, measured on `b98352a15`
+ *
+ * Six occurrences, four spellings, all in `packages/react/src`:
+ *
+ *   1. `SchemaRenderer`'s module-private `isConfigBag` — itself already the
+ *      merge of the `properties` evaluation guard and `propsWithoutCanonicalKeys`
+ *      (objectui#6752, which unified those two because it had to touch both,
+ *      and filed the rest as objectui#6761 rather than smuggling it in);
+ *   2. `SchemaRenderer`'s `winningVisibilityKey`, inline, spelled with
+ *      `!= null` where the others spell truthiness;
+ *   3. `utils/propsBagDiagnostic.ts`'s module-private twin (objectui#6708);
+ *   4. `utils/unevaluatedExpression.ts`'s `scanBag` early return, spelled
+ *      NEGATED (objectui#4795);
+ *   5. `utils/unevaluatedExpression.ts`'s `hoisted`, in the same file as (4)
+ *      and spelled positively — this one is not in objectui#6761's inventory
+ *      of five, which counted the file once; six occurrences is the count
+ *      measured on this branch's base, and it was six on the card's base
+ *      (`b76ca6764`) too.
+ *
+ * `!= null` (2) and truthiness (1, 3, 5) cannot disagree HERE, and the
+ * difference is worth naming rather than smoothing over: they part company
+ * only on a falsy value, and every falsy value except `document.all` fails
+ * `typeof === 'object'` in the very next conjunct. The texts differ; the
+ * answers cannot.
+ *
+ * ## What this is NOT
+ *
+ * Not a general "is this a plain object?" utility, and deliberately not shared
+ * with the two sites that ask the same SHAPE question about a data ROW —
+ * `SchemaRenderer`'s `boundRecord` scope entry and
+ * `usePredicateRecordContext` (`hooks/useExpression.ts`). Those answer "did a
+ * row bind?", and their answer has its own pinned meaning: binding NOTHING
+ * rather than an empty row is what keeps a host-supplied `record` from being
+ * shadowed. Should "config bag" ever narrow (rejecting a class instance, say),
+ * the row sites must NOT follow — merging them would make that a single edit
+ * with two rulings behind it. The pin in `configBag.pin.test.ts` names both
+ * sites with this reason, so the next reader finds a decision rather than an
+ * oversight.
+ */
+export declare function isConfigBag(value: unknown): value is Record<string, unknown>;

package/dist/utils/configBag.js

@@ -0,0 +1,70 @@
+/**
+ * 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.
+ */
+/**
+ * Is this value a real config bag — an object, and not an array pretending to
+ * be one? (objectui#6761)
+ *
+ * This is the ONE definition of that question in `@object-ui/react`, and it
+ * lives here rather than in whichever module happened to need it first,
+ * because every module that asks it is a CONSUMER of the same authored shape:
+ * the `properties` / `props` bags a node may carry. `typeof null === 'object'`
+ * is covered by the truthiness test.
+ *
+ * ## Why one definition, when all the copies agreed
+ *
+ * They agreed; that was never the cost. The cost is that disagreement between
+ * them produces NO error — each copy is a boolean expression, and a copy that
+ * drifts answers a different question on ONE channel while every other channel
+ * keeps the old answer. That is the same failure mode `hasDeclaredPredicate`
+ * (`@object-ui/core`) was created to end for "is a gate DECLARED?", which had
+ * three spellings with three different SCOPES before objectui#3850 —
+ * `disabled: null` greying a control out on one path and not another
+ * (objectui#3862).
+ *
+ * ## The spellings this replaces, measured on `b98352a15`
+ *
+ * Six occurrences, four spellings, all in `packages/react/src`:
+ *
+ *   1. `SchemaRenderer`'s module-private `isConfigBag` — itself already the
+ *      merge of the `properties` evaluation guard and `propsWithoutCanonicalKeys`
+ *      (objectui#6752, which unified those two because it had to touch both,
+ *      and filed the rest as objectui#6761 rather than smuggling it in);
+ *   2. `SchemaRenderer`'s `winningVisibilityKey`, inline, spelled with
+ *      `!= null` where the others spell truthiness;
+ *   3. `utils/propsBagDiagnostic.ts`'s module-private twin (objectui#6708);
+ *   4. `utils/unevaluatedExpression.ts`'s `scanBag` early return, spelled
+ *      NEGATED (objectui#4795);
+ *   5. `utils/unevaluatedExpression.ts`'s `hoisted`, in the same file as (4)
+ *      and spelled positively — this one is not in objectui#6761's inventory
+ *      of five, which counted the file once; six occurrences is the count
+ *      measured on this branch's base, and it was six on the card's base
+ *      (`b76ca6764`) too.
+ *
+ * `!= null` (2) and truthiness (1, 3, 5) cannot disagree HERE, and the
+ * difference is worth naming rather than smoothing over: they part company
+ * only on a falsy value, and every falsy value except `document.all` fails
+ * `typeof === 'object'` in the very next conjunct. The texts differ; the
+ * answers cannot.
+ *
+ * ## What this is NOT
+ *
+ * Not a general "is this a plain object?" utility, and deliberately not shared
+ * with the two sites that ask the same SHAPE question about a data ROW —
+ * `SchemaRenderer`'s `boundRecord` scope entry and
+ * `usePredicateRecordContext` (`hooks/useExpression.ts`). Those answer "did a
+ * row bind?", and their answer has its own pinned meaning: binding NOTHING
+ * rather than an empty row is what keeps a host-supplied `record` from being
+ * shadowed. Should "config bag" ever narrow (rejecting a class instance, say),
+ * the row sites must NOT follow — merging them would make that a single edit
+ * with two rulings behind it. The pin in `configBag.pin.test.ts` names both
+ * sites with this reason, so the next reader finds a decision rather than an
+ * oversight.
+ */
+export function isConfigBag(value) {
+    return !!value && typeof value === 'object' && !Array.isArray(value);
+}

package/dist/utils/error-message.d.ts

@@ -16,7 +16,7 @@ export declare function extractWriteErrorMessage(err: unknown): string | null;
  * The refusal text the PRODUCER explicitly marked as addressed to the end user,
  * or `null` when the refusal carries no marking.
  *
- * `userMessage` is the opt-in channel added by objectstack#9934 (maintainer
+ * `userMessage` is the opt-in channel added by objectstack `79c46da90` (maintainer
  * ruling 2026-08-19 on objectui#5210), declared on `ApiErrorSchema` /
  * `EnhancedApiErrorSchema` in the pinned `@objectstack/spec`.
  * Three properties of the contract decide this reader's whole shape:

package/dist/utils/error-message.js

@@ -74,7 +74,7 @@ export function extractWriteErrorMessage(err) {
  * The refusal text the PRODUCER explicitly marked as addressed to the end user,
  * or `null` when the refusal carries no marking.
  *
- * `userMessage` is the opt-in channel added by objectstack#9934 (maintainer
+ * `userMessage` is the opt-in channel added by objectstack `79c46da90` (maintainer
  * ruling 2026-08-19 on objectui#5210), declared on `ApiErrorSchema` /
  * `EnhancedApiErrorSchema` in the pinned `@objectstack/spec`.
  * Three properties of the contract decide this reader's whole shape:

package/dist/utils/inlineAria.d.ts

@@ -0,0 +1,61 @@
+/**
+ * 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.
+ */
+import type { AriaProps } from '@objectstack/spec/ui';
+/**
+ * Resolves the spec's NESTED `aria` bag to the DOM attributes it declares
+ * (objectui#11051).
+ *
+ * The bag is `@objectstack/spec`'s `AriaPropsSchema`, the `aria` member a
+ * block's own props schema carries (`element:text`, `element:button`,
+ * `element:image` and `element:number` among them). It declares three keys,
+ * and each maps to one attribute:
+ *
+ *   `ariaLabel`       → `aria-label`, resolved with the spec's own
+ *                       `resolveI18nLabel` against `locale`: a plain string is
+ *                       used as written, and an inline locale map
+ *                       (`{ en: 'Order total', 'zh-CN': '订单合计' }`) gives the
+ *                       entry for the viewer's language;
+ *   `ariaDescribedBy` → `aria-describedby`;
+ *   `role`            → `role`.
+ *
+ * A key that resolves to nothing, or to an empty string, is left out of the
+ * result instead of being written as an empty or `undefined` attribute. A key
+ * the bag does not declare is not read: the spec refuses such keys when the
+ * document is parsed, so this function adds no alias for them.
+ *
+ * ## Two vocabularies, two readers (objectui#4580 Q2-B)
+ *
+ * This is NOT `SchemaRenderer`'s `resolveAriaProps`. That one reads the FLAT
+ * node keys (`BaseSchema.ariaLabel` / `ariaDescribedBy` / `role`) and resolves
+ * `ariaLabel` in objectui's KEYED vocabulary (`{ key, defaultValue?, params? }`,
+ * via `resolveKeyedI18nLabel`). The nested bag uses the INLINE locale map.
+ * Neither resolver accepts the other's shape: the keyed one returns `undefined`
+ * for a locale map, and the spec's one treats `key` / `defaultValue` as locale
+ * tags. So the two readers stay separate, as objectui#4580 Q2-B ruled.
+ *
+ * ## Why a pure function and not a hook
+ *
+ * The caller passes the locale; this function reads no React context. That
+ * lets a renderer call it anywhere in its body, including after an early
+ * return, and lets code outside React call it too. Renderers pass
+ * `useDisplayLocale()` from `@object-ui/i18n`, the locale every
+ * `resolveI18nLabel` read site in this repo resolves against (objectui#4580
+ * revised Q1-A). Like the spec's resolver, `locale` is a required parameter
+ * that may be `undefined` (which resolves as `en`), so a caller cannot forget
+ * it by accident.
+ *
+ * @param aria - The authored bag, taken directly from the node's config. A
+ *   missing bag, or a value that is not an object, gives `{}`.
+ * @param locale - BCP-47 tag of the viewer's language, e.g. `zh-CN`.
+ * @returns The attributes to spread onto the element that carries the name.
+ */
+export declare function resolveInlineAriaProps(aria: AriaProps | null | undefined, locale: string | undefined): {
+    'aria-label'?: string;
+    'aria-describedby'?: string;
+    role?: string;
+};

package/dist/utils/inlineAria.js

@@ -0,0 +1,70 @@
+/**
+ * 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.
+ */
+import { resolveI18nLabel as resolveInlineI18nLabel } from '@objectstack/spec/ui';
+/**
+ * Resolves the spec's NESTED `aria` bag to the DOM attributes it declares
+ * (objectui#11051).
+ *
+ * The bag is `@objectstack/spec`'s `AriaPropsSchema`, the `aria` member a
+ * block's own props schema carries (`element:text`, `element:button`,
+ * `element:image` and `element:number` among them). It declares three keys,
+ * and each maps to one attribute:
+ *
+ *   `ariaLabel`       → `aria-label`, resolved with the spec's own
+ *                       `resolveI18nLabel` against `locale`: a plain string is
+ *                       used as written, and an inline locale map
+ *                       (`{ en: 'Order total', 'zh-CN': '订单合计' }`) gives the
+ *                       entry for the viewer's language;
+ *   `ariaDescribedBy` → `aria-describedby`;
+ *   `role`            → `role`.
+ *
+ * A key that resolves to nothing, or to an empty string, is left out of the
+ * result instead of being written as an empty or `undefined` attribute. A key
+ * the bag does not declare is not read: the spec refuses such keys when the
+ * document is parsed, so this function adds no alias for them.
+ *
+ * ## Two vocabularies, two readers (objectui#4580 Q2-B)
+ *
+ * This is NOT `SchemaRenderer`'s `resolveAriaProps`. That one reads the FLAT
+ * node keys (`BaseSchema.ariaLabel` / `ariaDescribedBy` / `role`) and resolves
+ * `ariaLabel` in objectui's KEYED vocabulary (`{ key, defaultValue?, params? }`,
+ * via `resolveKeyedI18nLabel`). The nested bag uses the INLINE locale map.
+ * Neither resolver accepts the other's shape: the keyed one returns `undefined`
+ * for a locale map, and the spec's one treats `key` / `defaultValue` as locale
+ * tags. So the two readers stay separate, as objectui#4580 Q2-B ruled.
+ *
+ * ## Why a pure function and not a hook
+ *
+ * The caller passes the locale; this function reads no React context. That
+ * lets a renderer call it anywhere in its body, including after an early
+ * return, and lets code outside React call it too. Renderers pass
+ * `useDisplayLocale()` from `@object-ui/i18n`, the locale every
+ * `resolveI18nLabel` read site in this repo resolves against (objectui#4580
+ * revised Q1-A). Like the spec's resolver, `locale` is a required parameter
+ * that may be `undefined` (which resolves as `en`), so a caller cannot forget
+ * it by accident.
+ *
+ * @param aria - The authored bag, taken directly from the node's config. A
+ *   missing bag, or a value that is not an object, gives `{}`.
+ * @param locale - BCP-47 tag of the viewer's language, e.g. `zh-CN`.
+ * @returns The attributes to spread onto the element that carries the name.
+ */
+export function resolveInlineAriaProps(aria, locale) {
+    if (!aria || typeof aria !== 'object')
+        return {};
+    const out = {};
+    const label = resolveInlineI18nLabel(aria.ariaLabel, locale);
+    if (label)
+        out['aria-label'] = label;
+    if (typeof aria.ariaDescribedBy === 'string' && aria.ariaDescribedBy) {
+        out['aria-describedby'] = aria.ariaDescribedBy;
+    }
+    if (typeof aria.role === 'string' && aria.role)
+        out.role = aria.role;
+    return out;
+}

package/dist/utils/localeMap.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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.
+ */
+/**
+ * Is this value an inline locale map, in `InlineLocaleMapSchema`'s sense?
+ *
+ * The member loop first is a fast reject and not a second definition: the
+ * schema requires every value to be a string, so the loop can only turn away
+ * what the schema turns away, and it does so without the schema's per-key
+ * issue reporting. Most data objects carry a non-string member.
+ */
+export declare function isInlineLocaleMap(value: unknown): value is Record<string, string>;
+/** Visit one member. `locale` is the member's key (`en`, `zh-CN`, `default`). */
+export type LocaleMapMemberVisitor = (member: string, locale: string) => unknown;
+/**
+ * Map every member of an inline locale map through `visit` and return the
+ * result, spelled as a string: the map itself when nothing changed (copy on
+ * write).
+ *
+ * The evaluation memo passes the evaluator; the dev diagnostic passes a visitor
+ * that records the member and returns it unchanged.
+ */
+export declare function mapLocaleMapMembers(map: Record<string, string>, visit: LocaleMapMemberVisitor): Record<string, string>;

package/dist/utils/localeMap.js

@@ -0,0 +1,106 @@
+/**
+ * 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.
+ */
+/**
+ * Each member of an inline locale map is evaluated like a plain string on the
+ * same key (objectui#12936).
+ *
+ * ## The rule
+ *
+ * A node's config-bag value that is an INLINE LOCALE MAP - the second
+ * authorized form of the spec's `I18nLabel`, for example
+ * `title: { en: 'Published ${data.at}', 'zh-CN': '...${data.at}' }` - has
+ * every member evaluated by the `SchemaRenderer` evaluation memo, with the same
+ * evaluator and so against the same scope as a plain string on that key:
+ * `record`, `current_user` / `user`, `page`, the host's ambient roots, and
+ * `data` on a node with an API binding. The block then picks one member for
+ * the viewer's language (`pickLocalized`) and draws an evaluated string.
+ *
+ * Before it, the map was a data object to the per-value loops, which hand a
+ * data object over as authored, so the member the block picked kept its
+ * `${...}` and drew it as text. A plain string with the same hole on the same
+ * key was evaluated, so localizing a line was what broke it.
+ *
+ * ## What a locale map is: the spec's answer, not a third one
+ *
+ * {@link isInlineLocaleMap} asks `@objectstack/spec`'s `InlineLocaleMapSchema`,
+ * the schema the contract declares the form with: every key a BCP-47 tag or
+ * `default` (never `key` / `defaultValue`), every value a string. A value with
+ * a non-string member, or with a key that is not a locale tag, is NOT a locale
+ * map: it stays a data object and is handed over as authored, with nothing
+ * inside it evaluated. No other object is walked.
+ *
+ * ⚠️ The boundary that follows from asking the contract: an object whose keys
+ * all parse as locale tags (any two or three letters do, so `{ id, url }`
+ * qualifies) and whose values are all strings IS an inline locale map to the
+ * spec, and so it is one here too, and a `${...}` in its members is evaluated.
+ *
+ * ## Why this module exists
+ *
+ * Two readers must agree on one radius, as they do for `params`
+ * (`paramsBag.ts`): the memo that EVALUATES the members, and the dev
+ * diagnostic (`unevaluatedExpression.ts`) that REPORTS a member still carrying
+ * `${...}` afterwards because its expression threw. Both import this module, so
+ * a member that fails to evaluate is reported exactly as a plain string that
+ * fails is.
+ *
+ * ## The result is still a locale map
+ *
+ * A member's result is spelled as a string. A member that is one whole hole,
+ * `'${data.count}'`, evaluates to the number itself, as a plain string does;
+ * left a number, the member would be skipped by every `pickLocalized` limb
+ * (each reads string entries only) and the viewer would get another locale's
+ * line, or nothing. `String(result ?? '')` is the spelling the evaluator
+ * already gives an interpolated part of a plain string.
+ *
+ * ## Copy on write
+ *
+ * The map is copied only when a member changed, so a map without a hole comes
+ * back as the very object that went in, and the authored map is never mutated.
+ * Nothing may depend on that identity (AGENTS.md #10).
+ */
+import { InlineLocaleMapSchema } from '@objectstack/spec/ui';
+import { isConfigBag } from './configBag.js';
+/**
+ * Is this value an inline locale map, in `InlineLocaleMapSchema`'s sense?
+ *
+ * The member loop first is a fast reject and not a second definition: the
+ * schema requires every value to be a string, so the loop can only turn away
+ * what the schema turns away, and it does so without the schema's per-key
+ * issue reporting. Most data objects carry a non-string member.
+ */
+export function isInlineLocaleMap(value) {
+    if (!isConfigBag(value))
+        return false;
+    for (const member of Object.values(value)) {
+        if (typeof member !== 'string')
+            return false;
+    }
+    return InlineLocaleMapSchema.safeParse(value).success;
+}
+/**
+ * Map every member of an inline locale map through `visit` and return the
+ * result, spelled as a string: the map itself when nothing changed (copy on
+ * write).
+ *
+ * The evaluation memo passes the evaluator; the dev diagnostic passes a visitor
+ * that records the member and returns it unchanged.
+ */
+export function mapLocaleMapMembers(map, visit) {
+    let copy;
+    for (const locale of Object.keys(map)) {
+        const member = map[locale];
+        const result = visit(member, locale);
+        const next = typeof result === 'string' ? result : String(result ?? '');
+        if (next !== member) {
+            if (!copy)
+                copy = { ...map };
+            copy[locale] = next;
+        }
+    }
+    return copy ?? map;
+}