@object-ui/react 17.6.0 → 17.7.0

package/dist/index.d.ts

@@ -10,10 +10,17 @@ export * from './schema-input.js';
 export * from './hooks/index.js';
 export * from './context/index.js';
 export * from './LazyPluginLoader.js';
-export * from './spec-bridge/index.js';
 export * from './data-invalidation.js';
 export * from './element-data-source/ElementDataSourceGate.js';
 export { resolveKeyedI18nLabel } from './utils/i18n.js';
+export { resolveInlineAriaProps } from './utils/inlineAria.js';
+export { isConfigBag } from './utils/configBag.js';
+export { reportUnresolvableVisibilityPredicate, formatUnresolvableVisibilityMessage, UNRESOLVABLE_VISIBILITY_PREFIX, UNRESOLVABLE_ENABLEMENT_PREFIX, __resetVisibilityPredicateWarnings, } from './utils/visibilityDiagnostic.js';
+export type { PredicateScopeTier } from './utils/visibilityDiagnostic.js';
+export type { PredicateGateKind } from './utils/visibilityDiagnostic.js';
 export { extractWriteErrorMessage, isPermissionError, extractFieldErrors, classifyLoadError, declaredUserMessage } from './utils/error-message.js';
 export type { WriteFieldError, LoadErrorKind } from './utils/error-message.js';
 export { I18nProvider, useObjectTranslation, useSafeTranslate, useObjectLabel, useSafeFieldLabel, useI18nContext, createI18n, getDirection, getAvailableLanguages, formatDate, formatDateTime, formatRelativeTime, formatCurrency, formatNumber, type I18nConfig, type I18nProviderProps, type TranslationKeys, type DateFormatOptions, type CurrencyFormatOptions, type NumberFormatOptions, } from '@object-ui/i18n';
+export { NON_GRID_ROW_CEILING, applyNonGridRowCeiling } from '@object-ui/core';
+export type { NonGridCeilingResult } from '@object-ui/core';
+export { NonGridRowCeilingNote } from './utils/nonGridRowCeiling.js';

package/dist/index.js

@@ -10,15 +10,59 @@ 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';
 // 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/nonGridRowCeiling.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 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 React from 'react';
+import type { NonGridCeilingResult } from '@object-ui/core';
+/**
+ * The loud footnote a non-grid view shows when it drew only the first
+ * `NON_GRID_ROW_CEILING` rows of a larger result set (objectui#7210).
+ *
+ * Placement and tone follow objectui#7148's chart footnote — a `role="note"`
+ * line in muted small type directly under the visualisation, naming BOTH
+ * numbers, because the count is the half a reader cannot recover from the
+ * picture. A truncated schedule renders as a healthy, confident schedule of a
+ * fraction of itself; "some rows are missing" leaves it indistinguishable from
+ * a complete one, and `2,000 of 40,000` is the bit that was missing.
+ *
+ * Two sentences because there are two conditions: a known total states the
+ * fact with both numbers; an adapter that reported no `total` still gets a
+ * DEFINITE sentence (the probe row proves more rows exist), it simply cannot
+ * name how many.
+ *
+ * ## It takes the RESULT, and nothing else (objectui#7508, ruling A′)
+ *
+ * The only prop is the `NonGridCeilingResult` that `applyNonGridRowCeiling`
+ * returned. Every number the note prints is read off that one object — the
+ * drawn count is `result.rows.length`, the total is `result.total`, the
+ * verdict is `result.truncated` — so a footnote whose numbers disagree with
+ * the rows actually drawn is not something a caller can write. The earlier
+ * shape took `drawn` / `total` / `truncated` as three loose props, and every
+ * call site hand-wrote `drawn={NON_GRID_ROW_CEILING}` next to a `total` from
+ * somewhere else: an incoherent pair was expressible and nothing refused it.
+ * ⛔ No deprecated path keeps those props; there were no released consumers.
+ *
+ * Renders `null` when nothing was truncated, so a caller holding a result can
+ * mount it unconditionally and gains no wrapper element on the healthy path.
+ */
+export declare function NonGridRowCeilingNote({ result, }: {
+    /** What `applyNonGridRowCeiling` returned for the rows being drawn. */
+    result: NonGridCeilingResult;
+}): React.JSX.Element | null;

package/dist/utils/nonGridRowCeiling.js

@@ -0,0 +1,78 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useObjectTranslation, en } from '@object-ui/i18n';
+// The non-React half of the non-grid row ceiling — `NON_GRID_ROW_CEILING`,
+// `nonGridRowCeilingQuery`, `applyNonGridRowCeiling` and `NonGridCeilingResult`
+// — lives in `@object-ui/core` beside the `extractRecords` it wraps
+// (objectui#7508, ruling A′). Only the footnote is React, so only the footnote
+// is here.
+/**
+ * The loud footnote a non-grid view shows when it drew only the first
+ * `NON_GRID_ROW_CEILING` rows of a larger result set (objectui#7210).
+ *
+ * Placement and tone follow objectui#7148's chart footnote — a `role="note"`
+ * line in muted small type directly under the visualisation, naming BOTH
+ * numbers, because the count is the half a reader cannot recover from the
+ * picture. A truncated schedule renders as a healthy, confident schedule of a
+ * fraction of itself; "some rows are missing" leaves it indistinguishable from
+ * a complete one, and `2,000 of 40,000` is the bit that was missing.
+ *
+ * Two sentences because there are two conditions: a known total states the
+ * fact with both numbers; an adapter that reported no `total` still gets a
+ * DEFINITE sentence (the probe row proves more rows exist), it simply cannot
+ * name how many.
+ *
+ * ## It takes the RESULT, and nothing else (objectui#7508, ruling A′)
+ *
+ * The only prop is the `NonGridCeilingResult` that `applyNonGridRowCeiling`
+ * returned. Every number the note prints is read off that one object — the
+ * drawn count is `result.rows.length`, the total is `result.total`, the
+ * verdict is `result.truncated` — so a footnote whose numbers disagree with
+ * the rows actually drawn is not something a caller can write. The earlier
+ * shape took `drawn` / `total` / `truncated` as three loose props, and every
+ * call site hand-wrote `drawn={NON_GRID_ROW_CEILING}` next to a `total` from
+ * somewhere else: an incoherent pair was expressible and nothing refused it.
+ * ⛔ No deprecated path keeps those props; there were no released consumers.
+ *
+ * Renders `null` when nothing was truncated, so a caller holding a result can
+ * mount it unconditionally and gains no wrapper element on the healthy path.
+ */
+export function NonGridRowCeilingNote({ result, }) {
+    // ⚠️ A HOOK AT RENDER, never a module-scope `createSafeTranslation(...)`
+    // factory, and that is a correctness constraint rather than taste. This
+    // module is re-exported from `@object-ui/react`'s entry, so anything at its
+    // module scope runs on IMPORT for every consumer that touches the barrel —
+    // and a factory call there throws inside any test that partially mocks
+    // `@object-ui/i18n` with an object literal instead of `importOriginal`,
+    // before a single assertion runs. Two such files went red in CI on exactly
+    // that, and the population is repo-wide rather than knowable from here, so
+    // the call moved to where it cannot fire at import time. `en` is likewise
+    // dereferenced HERE, at render, not in a module-scope constant.
+    //
+    // `useObjectTranslation` is the one that interpolates on the provider-less
+    // path too (objectui#6219), so `{{shown}}` / `{{total}}` are filled whether
+    // or not the host mounted an `I18nProvider`. The `defaultValue` is read from
+    // the `en` pack rather than retyped: both sit in the same eagerly-loaded
+    // chunk, so a hand copy would ship identical bytes twice, and reading the
+    // pack makes an inline default that disagrees with `en` unrepresentable
+    // instead of merely policed.
+    const { t } = useObjectTranslation();
+    if (!result.truncated)
+        return null;
+    const shown = result.rows.length;
+    const text = typeof result.total === 'number'
+        ? t('common.rowCeilingNote', {
+            shown,
+            total: result.total,
+            defaultValue: en.common.rowCeilingNote,
+        })
+        : t('common.rowCeilingNoteUnknownTotal', {
+            shown,
+            defaultValue: en.common.rowCeilingNoteUnknownTotal,
+        });
+    // `shrink-0` is the note's own, not a caller's: under a `flex-1` view pane in
+    // a fixed-height host a plain sibling can be clipped out of view — the
+    // construction objectui#7148's `ChartFootnote` measured, and the reason the
+    // gantt used to pass this exact class in. Outside a flex container it does
+    // nothing, so all four views take it and no caller needs a styling prop.
+    return (_jsx("p", { role: "note", "data-row-ceiling-note": "non-grid", className: "shrink-0 px-1 py-1 text-xs text-muted-foreground", children: text }));
+}