@object-ui/react 17.3.0 → 17.6.0

package/dist/hooks/useExpression.js

@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 import { createContext, createElement, useContext, useMemo } from 'react';
-import { ExpressionEvaluator, evalRowPredicate } from '@object-ui/core';
+import { ExpressionEvaluator, evalRowPredicate, isLegacyDialectSource, warnNonCanonicalRowSpelling, } from '@object-ui/core';
 /**
  * Global predicate scope — populated by host shells (e.g. app-shell's
  * `ExpressionProvider`) so renderers like action buttons can resolve
@@ -70,6 +70,90 @@ export function usePredicateScope() {
  * dependencies").
  */
 export { toPredicateInput } from '@object-ui/core';
+/**
+ * Build the predicate context for a **row record** — the bag to hand
+ * {@link useCondition} when the thing being gated is scoped to one record.
+ *
+ * The row is bound the THREE ways the platform's row surfaces bind it:
+ * `record.status` (spec/canonical), bare `status` (row-action shorthand), and
+ * `data.status` (legacy). This is not three dialects; it is one rule, and it is
+ * `evalRowPredicate`'s rule (`core/evaluator/listConditional.ts` — the record
+ * header, list rows, the row kebab and conditional formatting all evaluate
+ * through it), restated here for the `useCondition` tier so both tiers answer
+ * an author's `visible:` the same way.
+ *
+ * ## Why a helper and not "just spread the row" (objectui#4075)
+ *
+ * `useCondition` evaluates on `new ExpressionEvaluator({ ...scope, ...context })`,
+ * so a caller that passes the row spread flat resolves the shorthand spelling
+ * and NOTHING else. The canonical spelling is the `record.` root — it is what
+ * `ExpressionEvaluator`'s CEL path binds (`bag.record` as the record
+ * namespace), what `evalRowPredicate` binds, and what the server enforces
+ * with. Under a root-only bag `record.viewer.can_act` does not read as `false`:
+ * the evaluator throws `record is not defined`, and a fail-closed `visible`
+ * turns that throw into "hidden". A correctly-authored predicate then deletes
+ * its own button, indistinguishably from the gate having said no.
+ *
+ * That was live, not theoretical: every declared action on framework's
+ * `sys_approval_request` gates on `record.viewer.*` (framework#3310 / #3424),
+ * so the whole server-declared approval decision set was invisible wherever
+ * `DeclaredActionsBar` rendered until objectui#4077 bound the row this way —
+ * and the four generic action renderers carried the same root-only binding
+ * until objectui#4075.
+ *
+ * ## The canon is `record.*` (objectui#5330, ruled 2026-08-20)
+ *
+ * All three spellings are bound here, and that is unchanged — but they are NOT
+ * peers. `record.*` is the CONTRACT; the bare shorthand and `data.*` are
+ * tolerances in a deprecation window, kept because stored metadata carries
+ * them, reported once by `warnNonCanonicalRowSpelling` from `useCondition`
+ * below, and removable only after a stored-metadata survey sizes the window
+ * (⛔ no removal before the survey — part of the same ruling).
+ *
+ * The canon states the SERVER's accept set, which is narrower than this bag:
+ * measured on `@objectstack/formula@17.1.0`, `buildScope({ record })` mounts
+ * exactly `['record']`, so of the three spellings this helper binds, only
+ * `record.*` evaluates server-side — a bare field faults `Unknown variable:
+ * status` and `data.*` faults `Unknown variable: data`. This three-way bag has
+ * no server counterpart at all, which is exactly why the warning belongs on
+ * this side. `@object-ui/core`'s `evaluator/rowPredicateCanon.ts` carries the
+ * full measurement and the layer scoping (`data` stays canonical one layer
+ * over, in a metadata-editing form — ADR-0089 D3).
+ *
+ * `record` and `data` are written AFTER the spread deliberately: a row that
+ * happens to carry a field literally named `record` or `data` must not shadow
+ * the root every predicate is written against. Same precedence as
+ * `evalRowPredicate`.
+ *
+ * This is the BINDING rule only. It deliberately does not touch the evaluation
+ * entry — `useCondition` / `toPredicateInput` / `hasDeclaredVisibilityGate`
+ * keep their pinned semantics (objectui#3492 / #3842 / #3850 / #3871), and each
+ * caller keeps its own error policy (fail-closed `visible` vs the fail-soft
+ * legs). Binding the row is a different question from what to do when the
+ * predicate faults.
+ *
+ * ## No row → bind NOTHING, do not bind an empty one
+ *
+ * `null` / `undefined` / a non-object returns an EMPTY bag, not
+ * `{ record: {}, data: {} }`. The difference is load-bearing: `useCondition`
+ * merges this context OVER the ambient predicate scope, so binding an empty
+ * record would blank out a `record` that a host had put in the scope itself —
+ * which is exactly how `action:group`'s dropdown leaf is driven in
+ * `action-group-dropdown-visible.test.tsx`, and it is a legitimate way for a
+ * host to supply the row. "This surface has no row of its own" must stay
+ * distinct from "this surface's row is empty"; only the latter is entitled to
+ * shadow the scope.
+ *
+ * @param record The row, or nothing.
+ */
+export function usePredicateRecordContext(record) {
+    return useMemo(() => {
+        if (record == null || typeof record !== 'object' || Array.isArray(record))
+            return {};
+        const row = record;
+        return { ...row, record: row, data: row };
+    }, [record]);
+}
 /**
  * Hook for evaluating expressions with dynamic context
  *
@@ -104,6 +188,37 @@ export function useCondition(condition, context = {}, options) {
     const scope = usePredicateScope();
     // We evaluate directly without caching the evaluator to avoid issues with context changes
     return useMemo(() => {
+        // objectui#5330 Phase 1 — report a deprecated row-predicate spelling on
+        // the `useCondition` tier. This is the BINDING half's evaluation entry:
+        // `usePredicateRecordContext` sees the row but never the predicate text,
+        // so it structurally cannot detect a spelling, and this is the first
+        // point where the two meet.
+        //
+        // Two guards, both of which can only remove a report:
+        //  - the bag must carry the `usePredicateRecordContext` signature, `data`
+        //    and `record` being the SAME object by identity. A host scope that
+        //    merely happens to carry a `data` key cannot satisfy that, so a
+        //    non-row `useCondition` call is never judged as a row predicate.
+        //  - the source must be CEL. In this tier's legacy `${…}` dialect
+        //    (`'${data.status === "active"}'` — this hook's own doc example)
+        //    `data.*` is the NORMAL spelling, and reporting it would be a false
+        //    positive on every legacy predicate.
+        const bag = context;
+        const boundRow = bag.record != null && typeof bag.record === 'object' && bag.record === bag.data
+            ? bag.record
+            : undefined;
+        if (boundRow !== undefined) {
+            const celSource = typeof condition === 'string'
+                ? isLegacyDialectSource(condition)
+                    ? undefined
+                    : condition
+                : condition && typeof condition === 'object' && condition.dialect === 'cel'
+                    ? condition.source
+                    : undefined;
+            if (typeof celSource === 'string') {
+                warnNonCanonicalRowSpelling(celSource, boundRow, true, options?.label);
+            }
+        }
         const evaluator = new ExpressionEvaluator({ ...scope, ...context });
         if (options?.throwOnError) {
             // Fail-closed: a predicate that can't be evaluated hides/disables
@@ -141,9 +256,11 @@ export function useCondition(condition, context = {}, options) {
  * routes to `@object-ui/core`'s `evalRowPredicate`: a bare string is CEL (the
  * spec contract for `ActionSchema.visible`), a `{ dialect: 'cel', source }`
  * envelope is always CEL, and only a legacy-dialect string falls back to the
- * old engine (with a deprecation warning). The row is bound as `record.*` and
- * bare fields; the ambient predicate scope (`features` / `user` / …) is merged
- * alongside so deployment-level gates keep resolving.
+ * old engine (with a deprecation warning). The row is bound as `record.*` — the
+ * CANON (objectui#5330) — and, for stored metadata only, as bare fields and
+ * `data.*`, both of which now warn once; the ambient predicate scope
+ * (`features` / `user` / …) is merged alongside so deployment-level gates keep
+ * resolving.
  *
  * @param pred     The raw predicate: `boolean` (returned as-is), a CEL string,
  *                 an `{ dialect, source }` envelope, or `null`/`undefined`/`''`.

package/dist/hooks/useNavigationOverlay.d.ts

@@ -5,10 +5,11 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import type { NavigationConfigSchema } from '@objectstack/spec/ui';
-import type { SpecAuthoredInput } from '../spec-input';
+import type { NavigationConfigSchema, NavigationMode as SpecNavigationMode } from '@objectstack/spec/ui';
+import type { SpecAuthoredInput } from '../spec-input.js';
 /**
- * The spec's `NavigationConfigSchema`, authoring side, with `mode` required.
+ * The spec's `NavigationConfigSchema`, authoring side — by reference, with no
+ * divergence of its own.
  *
  * This was a hand copy carrying the note "inline … to avoid importing from
  * @object-ui/types (which may not be a direct dependency of @object-ui/react)".
@@ -18,10 +19,35 @@ import type { SpecAuthoredInput } from '../spec-input';
  * `@object-ui/app-shell`, where the dependency had likewise been there all
  * along. Check `package.json` before believing such a note (objectstack#4115).
  *
- * The ONE divergence: the spec defaults `mode`, so its authoring side makes it
- * optional; this hook dispatches on `mode` and its callers always supply one,
- * so it is required here. Every other key is the spec's, by reference. Pinned
- * by `__tests__/offline-nav-performance-spec-parity.test.ts`.
+ * `mode` is OPTIONAL, because the spec says so and this hook agrees.
+ * `packages/spec/src/ui/view.zod.ts` declares
+ * `mode: NavigationModeSchema.default('page')`, and a `.default()` lands on the
+ * AUTHORING side as `| undefined` — so `navigation: { view: 'summary_view' }`
+ * is legal authored metadata that lets the mode default.
+ *
+ * Until objectui#4550 this alias `Omit`ted `mode` and re-added it as
+ * `NonNullable<…>`, on the stated reasoning that "this hook dispatches on
+ * `mode` and its callers always supply one". Both halves were false.
+ * `useNavigationOverlay` does not require `mode` — it DEFAULTS it
+ * (`navigation?.mode ?? 'page'`, ~140 lines below), and `'page'` is meaningful
+ * behaviour rather than a placeholder. And callers did not always supply one:
+ * `ListView` carried `schema.navigation as NavigationConfig | undefined` purely
+ * to get a spec-shaped value past this declaration — a value the hook had
+ * always been willing to take.
+ *
+ * The rule that makes this a producer-side fix rather than a caller-side one:
+ * a type in front of an implementation must not be stricter than the
+ * implementation. When it is, every caller pays in assertions, and an assertion
+ * is exactly the renderer-side workaround AGENTS.md #0.1 sends back to the
+ * producer. Here the producer was this line.
+ *
+ * `@object-ui/types` re-exports the spec's own `NavigationConfig` unchanged, so
+ * that published name and this one now agree — they did not before, which is
+ * how one monorepo shipped two `NavigationConfig`s that disagreed about whether
+ * `mode` could be omitted. Pinned by
+ * `__tests__/offline-nav-performance-spec-parity.test.ts` (the type) and
+ * `__tests__/useNavigationOverlay.modeDefault.test.tsx` (the default behaviour
+ * the relaxation rests on).
  *
  * Two per-key notes the hand copy carried, kept here because a derived alias
  * has no members to hang them on:
@@ -30,9 +56,7 @@ import type { SpecAuthoredInput } from '../spec-input';
  *  - `width` is DEPRECATED by #2578 in favour of `size`. It still wins when
  *    present, because app-shell pre-resolves `size` into it.
  */
-export type NavigationConfig = Omit<SpecAuthoredInput<typeof NavigationConfigSchema>, 'mode'> & {
-    mode: NonNullable<SpecAuthoredInput<typeof NavigationConfigSchema>['mode']>;
-};
+export type NavigationConfig = SpecAuthoredInput<typeof NavigationConfigSchema>;
 /**
  * Resolve the overlay width from a NavigationConfig: an explicit `width` wins
  * (app-shell pre-resolves `size` into it); otherwise a declared bucket maps
@@ -41,7 +65,31 @@ export type NavigationConfig = Omit<SpecAuthoredInput<typeof NavigationConfigSch
  * count, which only schema-aware hosts have. Exported for the parity test.
  */
 export declare function resolveOverlayWidth(navigation: NavigationConfig | undefined): string | number | undefined;
-export type NavigationMode = NavigationConfig['mode'];
+/**
+ * The overlay modes — the spec's own union, DERIVED since objectui#4167.
+ *
+ * rc.6 publishes `NavigationMode` (`z.input<typeof NavigationModeSchema>`), and
+ * this alias resolved to exactly it already: `NavigationConfig['mode']` was then
+ * `NonNullable<…['mode']>`, and stripping the `undefined` that the schema's
+ * `.default()` puts on the authoring side leaves the seven-member enum itself.
+ * So the spec reference was one hop away rather than absent — the alias just
+ * reached it through a member access, which reads as a hand-written union to
+ * `check:spec-symbols` and, more to the point, to a person.
+ *
+ * Bound to the spec directly instead: the seven members now arrive from the
+ * schema that validates them. `__tests__/offline-nav-performance-spec-parity.test.ts`
+ * pins that this stays the same type as `NonNullable<NavigationConfig['mode']>`,
+ * so the two spellings cannot silently come apart if the spec ever stops
+ * defaulting `mode` or defaults it on a narrower union.
+ *
+ * The `NonNullable` in that pin is objectui#4550's mark and is load-bearing:
+ * `NavigationConfig` no longer strips the authoring-side `undefined`, so
+ * `NavigationConfig['mode']` is `NavigationMode | undefined` and a bare
+ * equality would now fail for a reason unrelated to the drift being guarded.
+ * What stays pinned is the MEMBERSHIP — the seven modes this hook switches on
+ * are exactly the seven the exported union publishes.
+ */
+export type NavigationMode = SpecNavigationMode;
 export interface UseNavigationOverlayOptions {
     /** The navigation configuration from the schema */
     navigation?: NavigationConfig;

package/dist/hooks/useOffline.d.ts

@@ -5,25 +5,21 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import type { OfflineStrategy, ConflictResolution, PersistStorage, EvictionPolicy, OfflineCacheConfigSchema, OfflineConfigSchema, SyncConfigSchema } from '@objectstack/spec/ui';
-import type { SpecAuthoredInput } from '../spec-input';
 /** Offline strategy determines how data is fetched when connectivity is limited. */
-export type { OfflineStrategy };
+export type OfflineStrategy = 'cache_first' | 'network_first' | 'stale_while_revalidate' | 'network_only' | 'cache_only';
 /**
  * Conflict resolution strategy for sync operations.
  *
- * Renamed from `ConflictResolutionStrategy` — that name belongs to a DIFFERENT
- * spec export (`@objectstack/spec/api`: `error | priority | first-wins |
- * last-wins`, the metadata-merge policy). The spec's name for the union this
- * hook actually uses is `ConflictResolution`, so the fix was to take the spec's
- * own name and its binding at once, the same move `FieldGroup` →
- * `ObjectFieldGroup` made in objectui#3169.
+ * Deliberately NOT named `ConflictResolutionStrategy` — that name belongs to a
+ * different contract (`@objectstack/spec/api`: `error | priority | first-wins |
+ * last-wins`, the metadata-merge policy), and the confusion between the two is
+ * what objectui#3169 / objectstack#4115 cost.
  */
-export type { ConflictResolution };
+export type ConflictResolution = 'manual' | 'client_wins' | 'server_wins' | 'last_write_wins';
 /** Persist storage backend. */
-export type PersistStorageType = PersistStorage;
+export type PersistStorageType = 'sqlite' | 'indexeddb' | 'localstorage';
 /** Eviction policy for cache management. */
-export type EvictionPolicyType = EvictionPolicy;
+export type EvictionPolicyType = 'lru' | 'lfu' | 'fifo';
 /** Sync state of the offline system. */
 export type SyncState = 'idle' | 'syncing' | 'error' | 'offline';
 /** A queued mutation waiting to be synced. */
@@ -35,37 +31,67 @@ export interface QueuedMutation {
     data?: Record<string, unknown>;
 }
 /**
- * Cache configuration — the AUTHORING side of the spec's
- * `OfflineCacheConfigSchema`.
+ * Cache configuration.
  *
- * `persistStorage` and `evictionPolicy` carry `.default()`s, so they are
- * optional to write and present after a parse. This hook is handed what an app
- * author wrote, hence the input side; see {@link SpecAuthoredInput}.
+ * `persistStorage` and `evictionPolicy` used to carry schema `.default()`s, so
+ * they stay optional to WRITE — this hook is handed what an app author wrote,
+ * which is why every key here is optional (the former `SpecAuthoredInput` /
+ * input-side reading of the retired schema).
  */
-export type OfflineCacheConfig = SpecAuthoredInput<typeof OfflineCacheConfigSchema>;
-/**
- * Sync configuration — the AUTHORING side of the spec's `SyncConfigSchema`.
- *
- * `strategy` and `conflictResolution` carry `.default()`s, so the output type
- * makes them required; this hook is handed what an app author wrote.
- */
-export type OfflineSyncConfig = SpecAuthoredInput<typeof SyncConfigSchema>;
+export interface OfflineCacheConfig {
+    /** Maximum cache size. */
+    maxSize?: number;
+    /** Time-to-live for cached entries. */
+    ttl?: number;
+    /** Storage backend. Defaults to `indexeddb` when a cache is used. */
+    persistStorage?: PersistStorageType;
+    /** Eviction policy once `maxSize` is reached. Defaults to `lru`. */
+    evictionPolicy?: EvictionPolicyType;
+}
+/** Sync configuration — controls how queued mutations reach the server. */
+export interface OfflineSyncConfig {
+    /** Fetch strategy for sync requests. */
+    strategy?: OfflineStrategy;
+    /** How to resolve a server/client conflict. */
+    conflictResolution?: ConflictResolution;
+    /** Delay between retry attempts, in ms. */
+    retryInterval?: number;
+    /** Maximum retry attempts before giving up. */
+    maxRetries?: number;
+    /** Mutations flushed per sync batch. */
+    batchSize?: number;
+}
 /**
- * Top-level offline configuration — the AUTHORING side of the spec's
- * `OfflineConfigSchema`.
+ * Top-level offline configuration.
  *
  * This name stays with `@object-ui/react` (objectui#3156 / objectui#3159): the
  * `OfflineConfig` that used to sit in `@object-ui/types` was a service-worker
  * ROUTE cache and has been renamed `PWAOfflineConfig`, so there is no
- * cross-package clash left — this hook's config is the spec's concept, key for
- * key, and takes the spec's binding.
+ * cross-package clash.
  *
- * Input side, not `z.infer`, and here the reason is visible in the signature:
- * `useOffline(config: OfflineConfig = {})` defaults to the empty object, which
- * the output type — where `enabled`, `strategy` and `offlineIndicator` are all
- * required once their `.default()`s have run — would reject outright.
+ * Every key is optional, and that is load-bearing rather than incidental:
+ * `useOffline(config: OfflineConfig = {})` defaults to the empty object, so a
+ * shape that made `enabled` / `strategy` / `offlineIndicator` required — as the
+ * retired schema's OUTPUT side did, once its `.default()`s had run — would
+ * reject the hook's own default argument. {@link DEFAULTS} below applies the
+ * same values the schema defaults used to.
  */
-export type OfflineConfig = SpecAuthoredInput<typeof OfflineConfigSchema>;
+export interface OfflineConfig {
+    /** Whether offline mode is active. Defaults to `true`. */
+    enabled?: boolean;
+    /** Fetch strategy. Defaults to `network_first`. */
+    strategy?: OfflineStrategy;
+    /** Client-side cache configuration. */
+    cache?: OfflineCacheConfig;
+    /** Sync behaviour for queued mutations. */
+    sync?: OfflineSyncConfig;
+    /** Whether to surface the offline indicator UI. Defaults to `true`. */
+    offlineIndicator?: boolean;
+    /** Message shown while offline. */
+    offlineMessage?: string;
+    /** Maximum queued mutations retained. Defaults to `100`. */
+    queueMaxSize?: number;
+}
 /** Result returned by the useOffline hook. */
 export interface OfflineResult {
     /** Whether the browser is currently online. */
@@ -91,8 +117,8 @@ export interface OfflineResult {
 }
 /**
  * Hook for offline mode detection and sync queue management. Its config types
- * ARE the spec's `OfflineConfigSchema` / `SyncConfigSchema` / `ConflictResolution`
- * (authoring side) — see {@link OfflineConfig}.
+ * are declared locally — see {@link OfflineConfig} for why they stopped being
+ * the spec's.
  *
  * @example
  * ```tsx

package/dist/hooks/useOffline.js

@@ -67,8 +67,8 @@ const DEFAULTS = {
 };
 /**
  * Hook for offline mode detection and sync queue management. Its config types
- * ARE the spec's `OfflineConfigSchema` / `SyncConfigSchema` / `ConflictResolution`
- * (authoring side) — see {@link OfflineConfig}.
+ * are declared locally — see {@link OfflineConfig} for why they stopped being
+ * the spec's.
  *
  * @example
  * ```tsx

package/dist/hooks/usePageAssignment.js

@@ -24,7 +24,7 @@
  * when no record Page is authored.
  */
 import { useEffect, useMemo, useState } from 'react';
-import { useMetadata } from '../context/AppShellContext';
+import { useMetadata } from '../context/AppShellContext.js';
 function matchesAssignment(_page, _opts) {
     // Placeholder — every page matches until rules-based assignment lands.
     return true;
@@ -76,10 +76,10 @@ export function usePageAssignment(objectName, opts = {}) {
             if (!p)
                 return false;
             // Only `pageType: 'record'` (or bare `type: 'record'`) is a
-            // user-facing record-detail page. `pageType: 'record_detail'` is a
-            // distinct concept used by the metadata designer page schemas
-            // (`buildObjectDetailPageSchema`) and must NOT be picked up here —
-            // otherwise opening any record would render the designer widget.
+            // user-facing record-detail page. Any other `pageType` — notably the
+            // designer-side `'record_detail'`, dropped from `PageType` in
+            // framework#2265 but still expressible in raw metadata — must NOT be
+            // picked up here, otherwise opening any record would render it.
             const pt = p.pageType ?? (p.type === 'record' ? 'record' : undefined);
             const isRecord = pt === 'record';
             if (!isRecord)

package/dist/hooks/usePageTransition.js

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

package/dist/hooks/usePageVariableActionBridge.js

@@ -6,8 +6,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 import * as React from 'react';
-import { usePageVariables } from './usePageVariables';
-import { useAction } from '../context';
+import { usePageVariables } from './usePageVariables.js';
+import { useAction } from '../context/index.js';
 /**
  * PageVariableActionBridge — publishes the live page-variable snapshot into the
  * shared ActionRunner context as `pageVariables`, so a submit action (`api` /

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,13 +5,15 @@
  * 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 './hooks';
-export * from './context';
-export * from './LazyPluginLoader';
-export * from './spec-bridge';
-export * from './data-invalidation';
-export { resolveI18nLabel } 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 './spec-bridge/index.js';
+export * from './data-invalidation.js';
+export * from './element-data-source/ElementDataSourceGate.js';
+export { resolveKeyedI18nLabel } from './utils/i18n.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';

package/dist/index.js

@@ -5,16 +5,20 @@
  * 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 './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 './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 { resolveI18nLabel } from './utils/i18n';
+export { resolveKeyedI18nLabel } from './utils/i18n.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';

package/dist/schema-input.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 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 { BaseSchema } 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
+ * 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.
+ *
+ * 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'];

package/dist/schema-input.js

@@ -0,0 +1,42 @@
+/**
+ * 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.
+ */
+/**
+ * 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
+ * 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.
+ *
+ * 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;
+}