@object-ui/react 17.3.0 → 17.5.0

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 { NavigationConfigSchema, NavigationMode as SpecNavigationMode } from '@objectstack/spec/ui';
 import type { SpecAuthoredInput } from '../spec-input';
 /**
- * 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

@@ -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/index.d.ts

@@ -6,12 +6,14 @@
  * 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 { resolveI18nLabel } from './utils/i18n';
+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 { 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

@@ -6,13 +6,17 @@
  * 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';
+// 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';
 // i18n utilities
-export { resolveI18nLabel } from './utils/i18n';
+export { resolveKeyedI18nLabel } from './utils/i18n';
 // 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';

package/dist/schema-input.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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';
+/**
+ * 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.
+ *
+ * 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.
+ */
+export declare function toRenderableSchema(node: BaseSchema | string | number | boolean | null | undefined): SchemaRendererProps['schema'];

package/dist/schema-input.js

@@ -0,0 +1,31 @@
+/**
+ * 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.
+ *
+ * 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.
+ */
+export function toRenderableSchema(node) {
+    return typeof node === 'number' || typeof node === 'boolean' ? String(node) : node;
+}

package/dist/spec-bridge/SpecBridge.d.ts

@@ -5,18 +5,24 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import type { SchemaNode } from '@object-ui/core';
+import type { BaseSchema } from '@object-ui/types';
 import type { BridgeContext, BridgeFn } from './types';
 export declare class SpecBridge {
     private bridges;
     private context;
     constructor(context?: BridgeContext);
     register(specType: string, bridge: BridgeFn): void;
-    /** Transform a spec schema into a SchemaNode tree */
-    transform(specType: string, spec: any): SchemaNode;
+    /**
+     * Transform a spec schema into a schema node tree.
+     *
+     * Returns `BaseSchema` rather than `SchemaNode` — see {@link BridgeFn} for
+     * the ruling (objectui#4580 Q4-B) and the measurement behind it. A registered
+     * bridge always produces an object; the union only made callers narrow.
+     */
+    transform(specType: string, spec: any): BaseSchema;
     /** Transform a ListView spec */
-    transformListView(spec: any): SchemaNode;
+    transformListView(spec: any): BaseSchema;
     /** Transform a FormView spec */
-    transformFormView(spec: any): SchemaNode;
+    transformFormView(spec: any): BaseSchema;
     updateContext(ctx: Partial<BridgeContext>): void;
 }

package/dist/spec-bridge/SpecBridge.js

@@ -28,7 +28,13 @@ export class SpecBridge {
     register(specType, bridge) {
         this.bridges.set(specType, bridge);
     }
-    /** Transform a spec schema into a SchemaNode tree */
+    /**
+     * Transform a spec schema into a schema node tree.
+     *
+     * Returns `BaseSchema` rather than `SchemaNode` — see {@link BridgeFn} for
+     * the ruling (objectui#4580 Q4-B) and the measurement behind it. A registered
+     * bridge always produces an object; the union only made callers narrow.
+     */
     transform(specType, spec) {
         const bridge = this.bridges.get(specType);
         if (!bridge) {

package/dist/spec-bridge/bridges/list-view.js

@@ -38,21 +38,113 @@ function mapColumn(col) {
         mapped.action = col.action;
     return mapped;
 }
+/**
+ * The spec's five row heights collapsed onto the renderer's three densities.
+ *
+ * `Record<RowHeight, …>` on purpose (objectui#4352): the key set is the spec's,
+ * so a row height added upstream fails the build here instead of silently
+ * arriving with no density. The table used to carry four more keys —
+ * `comfortable`, `spacious`, `small`, `large` — which `RowHeightSchema` does
+ * not admit, so no spec-valid list view could ever reach them; they only
+ * survived because the parameter was widened back to `string` and the fixture
+ * asserting three of them compiled against nothing. Deleting them is AGENTS.md
+ * #0.1: a renderer-side dialect for off-spec metadata is a second de-facto
+ * contract, and one strict contract beats N. An off-spec `rowHeight` now falls
+ * through to `undefined` — the producer is where it gets fixed.
+ */
+const ROW_HEIGHT_TO_DENSITY = {
+    compact: 'compact',
+    short: 'compact',
+    medium: 'comfortable',
+    tall: 'spacious',
+    extra_tall: 'spacious',
+};
+/**
+ * Runtime reader for {@link ROW_HEIGHT_TO_DENSITY} — the five spec row heights
+ * and **nothing else**.
+ *
+ * `hasOwnProperty`, not a bare index (objectui#4442): the table is a plain
+ * object literal, so indexing it with an unchecked key reaches
+ * `Object.prototype`. The parameter is typed `RowHeight`, but the boundary a
+ * host's stored view definition actually crosses is `SpecBridge.transformListView`,
+ * whose parameter is `any` — so `rowHeight: 'toString'` used to come back as
+ * `Object.prototype.toString`, a FUNCTION returned from a signature that
+ * promises three strings or nothing. `bridgeListView` then writes the key under
+ * `if (density)`, and a function is truthy, so it landed on the SchemaNode.
+ *
+ * This is the same guard `@object-ui/core`'s `rowHeightToDensityMode` grew in
+ * objectui#4440, and the repo's existing convention (`freeze-schema.ts:135`,
+ * `metadata-admin/predicate.ts:305`, six more). Both rowHeight surfaces now
+ * abstain identically on every off-spec spelling; the agreement is pinned by
+ * `__tests__/RowHeightDensityAgreement.test.ts`.
+ *
+ * `typeof rowHeight !== 'string'`, not `!rowHeight` (objectui#4459): the
+ * truthiness guard this replaces rejected only FALSY values, so every truthy
+ * non-string walked past it into a lookup that coerces its key — both
+ * `hasOwnProperty.call` and the index run `String(...)`. `['compact']`, a boxed
+ * `String('compact')` and `{ toString: () => 'compact' }` therefore each
+ * selected a real density, where core's twin abstained
+ * (`packages/core/src/utils/normalize-list-view.ts:83`, which has opened with
+ * the type guard since #4440). Note the direction against #4442: that leak produced a
+ * FUNCTION, visibly wrong to everything downstream; this one produced a
+ * legitimate-looking `'compact'` that nothing can tell apart from an authored
+ * value. The type guard subsumes the old one — `undefined`, `null`, `0` and
+ * `false` are all non-strings — and `''` keeps its answer while changing route:
+ * a string, so it passes here and is refused by `hasOwnProperty` one line down.
+ */
 function mapDensity(rowHeight) {
-    if (!rowHeight)
+    if (typeof rowHeight !== 'string')
         return undefined;
-    const map = {
-        compact: 'compact',
-        short: 'compact',
-        comfortable: 'comfortable',
-        spacious: 'spacious',
-        small: 'compact',
-        medium: 'comfortable',
-        large: 'spacious',
-        tall: 'spacious',
-        extra_tall: 'spacious',
-    };
-    return map[rowHeight];
+    if (!Object.prototype.hasOwnProperty.call(ROW_HEIGHT_TO_DENSITY, rowHeight)) {
+        return undefined;
+    }
+    return ROW_HEIGHT_TO_DENSITY[rowHeight];
+}
+/**
+ * The spec's own parse-time lift, applied where `parse` cannot reach
+ * (objectui#4585).
+ *
+ * `@objectstack/spec` accepts BOTH spellings of `view.exportOptions` and lifts
+ * the legacy bare format array to the object form at parse (objectstack#8010,
+ * `ui/view.zod.ts`):
+ *
+ *     z.array(ListViewExportFormatSchema).transform((formats) => ({ formats }))
+ *
+ * That transform never runs on this path. The bridge's input is a TypeScript
+ * type, not a parsed value — there is no `parse`/`safeParse` anywhere under
+ * `spec-bridge/` — so a host that parses first hands over the object form while
+ * a host that forwards raw stored metadata hands over whatever was authored,
+ * and nothing here can tell them apart. The legacy array therefore used to
+ * reach the `object-grid` node verbatim, where `ObjectGrid` reads
+ * `exportOptions.formats` and only that: `.formats` on an array is `undefined`,
+ * the renderer's `['csv', 'json']` default won, and the view's declared formats
+ * were dropped with no error and no console line — the export button still
+ * showed, because a non-empty array is truthy.
+ *
+ * This mirrors that transform and NOTHING more: the same contract applied one
+ * layer out, not a second de-facto one (AGENTS.md #0.1 — the consumer-side
+ * `Array.isArray` fallback in the renderer is what that rule forbids). Hence:
+ *
+ * - the object form passes through by reference, unread and unrewritten;
+ * - an empty array lifts to `{ formats: [] }`, exactly as the spec's transform
+ *   does — its `z.array()` carries no `.min(1)`, so `[]` is a legal input that
+ *   wraps rather than defaults. ObjectGrid then offers no format and hides the
+ *   export button: "declared zero formats", read literally;
+ * - a `'pdf'` stored before its retirement is carried, not filtered. The spec
+ *   REFUSES `'pdf'` at parse with a migration prescription (objectstack#8010;
+ *   PDF export itself was declined as objectstack#1301 NOT_PLANNED) — it does
+ *   not silently drop the value, so neither may this. Such a format dies
+ *   downstream in ObjectGrid's format-AGNOSTIC menu filter, kept deliberately
+ *   at objectui#4535 for metadata predating `os migrate meta --from 16`.
+ */
+function liftExportOptions(exportOptions) {
+    if (!Array.isArray(exportOptions))
+        return exportOptions;
+    // The pinned `@objectstack/spec@17.0.0-rc.6` still admits `'pdf'` as an array
+    // member (the enum narrowing arrives with the pin bump), so the element type
+    // here is wider than the renderer-side `ListViewExportFormat`. Narrowing it by
+    // filtering would invent precisely the silent drop the spec declines to do.
+    return { formats: exportOptions };
 }
 /** Transforms a ListView spec into a DataTable SchemaNode */
 export const bridgeListView = (spec, _context) => {
@@ -116,7 +208,7 @@ export const bridgeListView = (spec, _context) => {
     if (spec.inlineEdit != null)
         node.inlineEdit = spec.inlineEdit;
     if (spec.exportOptions)
-        node.exportOptions = spec.exportOptions;
+        node.exportOptions = liftExportOptions(spec.exportOptions);
     if (spec.emptyState)
         node.emptyState = spec.emptyState;
     if (spec.userActions)

package/dist/spec-bridge/types.d.ts

@@ -5,7 +5,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import type { SchemaNode } from '@object-ui/core';
+import type { BaseSchema } from '@object-ui/types';
 /** Context passed to all bridge functions */
 export interface BridgeContext {
     /** Current user context for permission checks */
@@ -30,5 +30,26 @@ export interface ObjectDefLite {
         }>;
     }>;
 }
-/** A bridge function transforms a spec schema into a SchemaNode tree */
-export type BridgeFn<T = any> = (spec: T, context: BridgeContext) => SchemaNode;
+/**
+ * A bridge function transforms a spec schema into a schema node tree.
+ *
+ * Returns **`BaseSchema`**, not `SchemaNode` (objectui#4580, ruling Q4-B).
+ * Once core's `SchemaNode` became `@object-ui/types`' union
+ * (`BaseSchema | string | number | boolean | null | undefined`), declaring the
+ * return as `SchemaNode` made every caller re-ask a question no bridge has ever
+ * answered "yes" to: *is this a bare string / null?* Both shipped bridges end
+ * in a single `return node` on an object literal — `bridges/list-view.ts:226`
+ * and `bridges/form-view.ts:195` — so the wider declaration described nothing
+ * real while forcing a narrowing at every read.
+ *
+ * That cost was measured, not assumed: round 1 of this card recorded **272**
+ * mechanical errors across five spec-bridge suites, all of them TS18049
+ * (`'node' is possibly 'null' or 'undefined'`) and TS2339
+ * (`Property 'formType' does not exist on type
+ * 'string | number | boolean | BaseSchema'`) — the union being destructured by
+ * tests reading properties off a node the bridge always produces.
+ *
+ * This is a type ANNOTATION only: no runtime behaviour changes, and the emitted
+ * JavaScript is byte-identical (proven by bundle sha256 on this PR).
+ */
+export type BridgeFn<T = any> = (spec: T, context: BridgeContext) => BaseSchema;

package/dist/utils/i18n.d.ts

@@ -1,10 +1,45 @@
+import type { KeyedI18nLabel } from '@object-ui/types';
 /**
- * Resolves an I18nLabel to a plain string.
- * I18nLabel can be either a string or an object { key, defaultValue?, params? }.
- * When it's an object, we return the defaultValue or the key as fallback.
+ * Resolves objectui's KEYED i18n label to a plain string.
+ *
+ * The keyed form is `{ key, defaultValue?, params? }` — a reference INTO a
+ * translation bundle. This package has no `t()`, so it resolves the reference
+ * as far as it can without one: `defaultValue`, else the key itself. (The
+ * app-shell twin of this function takes a `t` and resolves the key properly.)
+ *
+ * ## Why this is not called `resolveI18nLabel` (objectui#4167)
+ *
+ * `@objectstack/spec` 17.0.0-rc.6 publishes a function of that exact name from
+ * `@objectstack/spec/ui`, over a DIFFERENT vocabulary: the INLINE LOCALE MAP
+ * (`{ en: 'Owner', 'zh-CN': '负责人' }`), resolved against a BCP-47 locale
+ * (`resolveI18nLabel(label, locale)`). Two resolvers, one name, and neither
+ * accepts the other's shape — which objectstack#4115 calls a planted premise
+ * rather than a naming nit, because the next agent reads the name and builds
+ * on it.
+ *
+ * rc.6 is also what made the clash dangerous rather than merely untidy. It
+ * widened the spec's `I18nLabel` from `string` to
+ * `string | Record< string, string >`, so the SAME authored value can now reach
+ * either function — and each answers wrongly for the other's input, silently:
+ *
+ *   this one, given `{ en: 'Owner' }`      → `undefined` (no `key`, no
+ *                                            `defaultValue`) → renders empty;
+ *   the spec's, given `{ key: 'nav.home' }` → treats `key`/`defaultValue`/
+ *                                            `params` as locale tags and picks
+ *                                            one of them as the display text.
+ *
+ * Neither is a type error at the call site that matters, and both look like a
+ * working render until someone reads the output. PR #4169 met this head-on and
+ * aliased the spec's import as `resolveInlineI18nLabel` in five files, with
+ * hand-written comments explaining the clash at two of them — a review
+ * convention, which is exactly what objectstack#4115 exists to replace with a
+ * rule. `Keyed` is the counterpart of that `Inline`: the name now says which
+ * vocabulary it resolves, at every call site, with no comment required.
+ *
+ * The keyed shape itself is now named too — `KeyedI18nLabel` in
+ * `@object-ui/types` (#4581) — so `BaseSchema.ariaLabel`, this parameter and
+ * the layout twin all state one type instead of three copies of one object
+ * literal. The `Inline`/`Keyed` split above is the naming half of #4167; the
+ * named shape is the declaration half.
  */
-export declare function resolveI18nLabel(label: string | {
-    key: string;
-    defaultValue?: string;
-    params?: Record<string, any>;
-} | undefined): string | undefined;
+export declare function resolveKeyedI18nLabel(label: string | KeyedI18nLabel | undefined): string | undefined;