@object-ui/react 17.5.0 → 17.7.0

package/dist/hooks/useSettledSchema.js

@@ -0,0 +1,186 @@
+/**
+ * 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 { useEffect, useState } from 'react';
+/**
+ * Is this refetch's answer the SAME answer, by value, as the one already
+ * published?
+ *
+ * Used for exactly one decision — whether a settle republishes or keeps the
+ * object consumers already hold — and its failure direction is chosen for
+ * that decision. A false NEGATIVE (two encodings of the same metadata that
+ * serialise differently, e.g. with the keys in another order) republishes,
+ * which is precisely what this hook did for every answer before
+ * objectui#10106: no consumer can be worse off than it already was. A false
+ * POSITIVE would withhold a genuinely new definition from consumers, so the
+ * comparison is deliberately a whole-payload one and never a sampled or
+ * shallow test.
+ *
+ * ⚠️ An answer JSON cannot express — a cycle, a `BigInt` — makes
+ * `JSON.stringify` throw; that is answered as "not equal" rather than allowed
+ * to escape into a state updater, which lands on the safe side above.
+ */
+function isEqualPayload(a, b) {
+    if (Object.is(a, b))
+        return true;
+    try {
+        return JSON.stringify(a) === JSON.stringify(b);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolves an object's schema/definition and tracks whether that resolution
+ * has SETTLED for the object CURRENTLY being asked about — one piece of
+ * state a caller cannot observe half of.
+ *
+ * ## The shape, and why it is exactly this one
+ *
+ * This is the RESOLUTION half of the settled-schema gate four views
+ * (`ObjectKanban`, `ObjectView`, `ObjectCalendar`, and — pre-fix —
+ * `ObjectTree`) each hand-wrote (objectui#6271, #6419, #6453, #6014). Ruled
+ * objectui#6482 (maintainer, 2026-08-27, Option A): extract the resolution
+ * half as a shared, published hook; leave GATE PLACEMENT — deciding which
+ * effect branch actually waits on `ready` — to each component, because that
+ * part is genuinely component-private (`ObjectCalendar` gates only its
+ * `object`-provider branch and keys on the object the block RESOLVES rather
+ * than on `schema.objectName`, because an inline `value` data set issues no
+ * metadata read at all — a whole-effect gate would hold its query open on a
+ * resolution nothing was ever going to produce).
+ *
+ * `ready` is DERIVED at render time — `resolution !== null && resolution.key
+ * === key` — from a SINGLE piece of state, `{ key, def } | null`, rather than
+ * stored as a second, independent boolean. That is not a style choice; it is
+ * the fix for the defect this card exists to close. objectui#6481's
+ * `ObjectTree` carried the definition (`objectSchema`) and "has it settled"
+ * (`schemaSettled`) as two SEPARATE `useState`s. `schemaSettled` was a
+ * one-way latch — set `true` on first settle and never reset — so when the
+ * host swapped `objectName` mid-life, the fetch effect re-ran and started
+ * refetching the NEW object's schema, but `schemaSettled` stayed `true` from
+ * the OLD object's settle. The gated effect read `schemaSettled === true`
+ * and `objectSchema` still holding the OLD object's fields, and queried with
+ * the WRONG `$expand` — a stale key reading as ready.
+ *
+ * With one state value and a render-time key comparison, that failure mode
+ * is not merely fixed, it is UNREPRESENTABLE: the instant `key` changes,
+ * `resolution.key === key` is false in that very render (no effect needs to
+ * run first), so `ready` flips to `false` in the same commit the key
+ * changed — there is no window, and no second piece of state a caller could
+ * read out of sync with the first, because there is no second piece of
+ * state. A caller cannot spell "ready for the wrong object": `ready` and
+ * `def` are two views of one value, never independently settable.
+ *
+ * Every exit of the internal fetch effect settles the resolution — success,
+ * a thrown read, and "there is no source to read from" alike — because a
+ * caller's gated effect WAITS on `ready`. An exit that returned without
+ * settling would not merely skip the expansion; it would hold that gated
+ * query open forever.
+ *
+ * ## What this hook does NOT do
+ *
+ * It does not decide when to fetch beyond "when `key` or `dataSource`
+ * change", and it does not decide what a caller's OTHER effects should wait
+ * on. A caller that should not fetch at all for the current render (e.g.
+ * `ObjectCalendar`'s inline `value` provider, which issues no metadata read)
+ * passes `dataSource: undefined` for that render rather than a new "should
+ * fetch" flag — the hook already settles-with-`null` whenever `dataSource`
+ * is absent, which is the exact "no source to read from" outcome that case
+ * needs.
+ *
+ * @param key - The identity of the object THIS render is asking about — for a
+ *   record-bound view, `resolveRecordSourceObjectName(schema, dataConfig) ?? ''`
+ *   from `@object-ui/core`. ⛔ Do NOT re-spell that ladder inline here: six view
+ *   plugins each carried their own copy and had drifted, which is the whole of
+ *   what `b041b9c0c` collapsed. Choosing the key is still the caller's job — it is the
+ *   component-private half of the original hand copies, not something this hook
+ *   can infer — but the ladder behind it is published and shared.
+ * @param dataSource - The data source to read the definition from. Pass
+ *   `undefined`/`null` for a render that should settle immediately with no
+ *   definition (no source, or a provider that needs none) rather than adding
+ *   a separate enable flag.
+ * @returns `{ ready, def }` — see {@link SettledSchema}.
+ *
+ * @example
+ * ```tsx
+ * const schemaKey = resolveRecordSourceObjectName(schema, dataConfig); // @object-ui/core
+ * const { ready: objectSchemaReady, def: objectSchema } =
+ *   useSettledSchema(schemaKey ?? '', hasInlineData ? undefined : dataSource);
+ *
+ * useEffect(() => {
+ *   // A PROVIDER test, not an object-name read — it asks "is there metadata to
+ *   // wait for at all", which the shared reader deliberately does not answer.
+ *   // Gate placement stays local (objectui#6482); the ladder does not.
+ *   if (dataConfig?.provider === 'object' && !objectSchemaReady) return;
+ *   // ...issue the record query, `buildExpandFields(objectSchema?.fields)`
+ * }, [objectSchemaReady, objectSchema, /* ... *\/]);
+ * ```
+ */
+export function useSettledSchema(key, dataSource) {
+    const [resolution, setResolution] = useState(null);
+    useEffect(() => {
+        let isMounted = true;
+        const settleKey = key;
+        /**
+         * Settle THIS effect run's resolution — and, when the answer is one
+         * consumers already hold, settle it as the object they already hold.
+         *
+         * This is the PRODUCER half of `AGENTS.md` §5 commandment #10: *"a
+         * provider that refetches may not republish an equal payload as a new
+         * object, and a consumer that needs stability keys on the data, not on a
+         * cache"*. This hook refetches whenever the adapter identity changes, and
+         * the consumers its own `@example` instructs do exactly what the other
+         * half of that sentence asks — they key their record fetch on `def`, the
+         * payload, never on a memo identity. So a fresh object for an unchanged
+         * answer is not a wasted allocation; it is a DUPLICATE RECORD QUERY at
+         * every one of them, carrying the same expand set as the one before it.
+         * Pinned with its control in
+         * `useSettledSchema.equalPayload-10106.test.tsx` (objectui#10106).
+         *
+         * ⛔ The cure may NOT be moved to the consumer — the same sentence names
+         * keying on a cache as the wrong one, and a consumer that stopped keying
+         * on `def` would also stop re-querying when the definition genuinely
+         * changes, which the control case in that pin holds open.
+         *
+         * Bailing out is only ever safe for the SAME key: `resolution` is one
+         * piece of state whose `key` decides `ready`, so a settle for a different
+         * key must always publish (see the hook doc comment above).
+         */
+        const settle = (settledDef) => {
+            setResolution((prev) => prev && prev.key === settleKey && isEqualPayload(prev.def, settledDef)
+                ? prev
+                : { key: settleKey, def: settledDef });
+        };
+        const resolve = async () => {
+            if (!dataSource || !settleKey || typeof dataSource.getObjectSchema !== 'function') {
+                // No source for a definition: settle with none, so anything gated on
+                // `ready` still runs (unexpanded — with no schema there is no expand
+                // set to derive).
+                if (isMounted)
+                    settle(null);
+                return;
+            }
+            try {
+                const def = await dataSource.getObjectSchema(settleKey);
+                if (isMounted)
+                    settle(def);
+            }
+            catch (err) {
+                console.error('[useSettledSchema] getObjectSchema failed for', settleKey, err);
+                if (isMounted)
+                    settle(null);
+            }
+        };
+        resolve();
+        return () => {
+            isMounted = false;
+        };
+    }, [key, dataSource]);
+    const ready = resolution !== null && resolution.key === key;
+    const def = ready ? resolution.def : null;
+    return { ready, def };
+}

package/dist/hooks/useViewData.d.ts

@@ -37,8 +37,13 @@ export interface UseViewDataResult<T = any> {
     dataSource: DataSource<T> | null;
     /** Re-fetch data with current or new params */
     refresh: (newParams?: QueryParams) => Promise<void>;
-    /** Fetch a single record by ID */
-    fetchOne: (id: string | number) => Promise<T | null>;
+    /**
+     * Fetch a single record by ID. The id is a `string`, as every record door on
+     * `DataSource` declares it — this hook hands the value straight to
+     * `DataSource.findOne`, so the union it used to admit was a claim the
+     * protocol never made (objectui#9511).
+     */
+    fetchOne: (id: string) => Promise<T | null>;
     /** Whether more records are available */
     hasMore: boolean;
 }

package/dist/hooks/useViewData.js

@@ -10,7 +10,7 @@
  */
 import { useState, useEffect, useCallback, useMemo, useContext } from 'react';
 import { resolveDataSource } from '@object-ui/core';
-import { SchemaRendererContext } from '../context/SchemaRendererContext';
+import { SchemaRendererContext } from '../context/SchemaRendererContext.js';
 // ---------------------------------------------------------------------------
 // Hook
 // ---------------------------------------------------------------------------

package/dist/hooks/useViewTransition.js

@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 import { useState, useCallback, useMemo } from 'react';
-import { useReducedMotion } from './useReducedMotion';
+import { useReducedMotion } from './useReducedMotion.js';
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------

package/dist/index.d.ts

@@ -5,15 +5,22 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-export * from './SchemaRenderer';
-export * from './schema-input';
-export * from './hooks';
-export * from './context';
-export * from './LazyPluginLoader';
-export * from './spec-bridge';
-export * from './data-invalidation';
-export * from './element-data-source/ElementDataSourceGate';
-export { resolveKeyedI18nLabel } from './utils/i18n';
-export { extractWriteErrorMessage, isPermissionError, extractFieldErrors } from './utils/error-message';
-export type { WriteFieldError } from './utils/error-message';
+export * from './SchemaRenderer.js';
+export * from './schema-input.js';
+export * from './hooks/index.js';
+export * from './context/index.js';
+export * from './LazyPluginLoader.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

@@ -5,20 +5,64 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-export * from './SchemaRenderer';
-export * from './schema-input';
-export * from './hooks'; // will be empty for now
-export * from './context'; // will be empty for now
-export * from './LazyPluginLoader';
-export * from './spec-bridge';
-export * from './data-invalidation';
+export * from './SchemaRenderer.js';
+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 './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';
+export * from './element-data-source/ElementDataSourceGate.js';
 // i18n utilities
-export { resolveKeyedI18nLabel } from './utils/i18n';
+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 } from './utils/error-message';
+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,27 +5,68 @@
  * 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 { SchemaRendererProps } from './SchemaRenderer';
+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.
- *
- * It exists because the two competing repo-wide `SchemaNode` spellings
- * (`@object-ui/core`'s interface vs `@object-ui/types`' union) have not been
- * reconciled; that reconciliation is tracked separately. When it lands, the
- * call sites using this can go back to forwarding directly.
+ * 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):
+ * `@object-ui/core` stopped hand-declaring its own interface and now re-exports
+ * `@object-ui/types`' union, so one declaration is left to disagree with. That
+ * reconciliation resolved in favour of the UNION, while `SchemaRenderer`'s prop
+ * stays deliberately narrow (objectui#4548 ruling Q2 — it declares no `number`
+ * or `boolean`), so a `SchemaNode` is now LESS assignable to that prop than it
+ * was, not more. This step therefore bridges two intentionally different types,
+ * and it stays. ⛔ Do not "tidy" a call site back into a direct forward: the
+ * five `apps/site` sites that were forwarding directly when PR #4608 landed are
+ * what kept `Build Docs` red on `main` for ~5 hours — each one a TS2322 naming
+ * `number` against this function's return type, spelled
+ * `string | BaseSchema | null | undefined` in objectui#4617's logs — until
+ * 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,23 +9,66 @@
  * 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.
- *
- * It exists because the two competing repo-wide `SchemaNode` spellings
- * (`@object-ui/core`'s interface vs `@object-ui/types`' union) have not been
- * reconciled; that reconciliation is tracked separately. When it lands, the
- * call sites using this can go back to forwarding directly.
+ * 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):
+ * `@object-ui/core` stopped hand-declaring its own interface and now re-exports
+ * `@object-ui/types`' union, so one declaration is left to disagree with. That
+ * reconciliation resolved in favour of the UNION, while `SchemaRenderer`'s prop
+ * stays deliberately narrow (objectui#4548 ruling Q2 — it declares no `number`
+ * or `boolean`), so a `SchemaNode` is now LESS assignable to that prop than it
+ * was, not more. This step therefore bridges two intentionally different types,
+ * and it stays. ⛔ Do not "tidy" a call site back into a direct forward: the
+ * five `apps/site` sites that were forwarding directly when PR #4608 landed are
+ * what kept `Build Docs` red on `main` for ~5 hours — each one a TS2322 naming
+ * `number` against this function's return type, spelled
+ * `string | BaseSchema | null | undefined` in objectui#4617's logs — until
+ * 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 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);
+}