@object-ui/react 17.2.0 → 17.5.0

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;

package/dist/utils/i18n.js

@@ -1,9 +1,47 @@
 /**
- * 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 function resolveI18nLabel(label) {
+export function resolveKeyedI18nLabel(label) {
     if (label === undefined || label === null)
         return undefined;
     if (typeof label === 'string')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/react",
-  "version": "17.2.0",
+  "version": "17.5.0",
   "type": "module",
   "license": "MIT",
   "description": "React bindings and SchemaRenderer component for Object UI",
@@ -24,20 +24,20 @@
     }
   },
   "dependencies": {
-    "@objectstack/spec": "^17.0.0-rc.1",
-    "react-hook-form": "^7.83.0",
-    "@object-ui/core": "17.2.0",
-    "@object-ui/data-objectstack": "17.2.0",
-    "@object-ui/i18n": "17.2.0",
-    "@object-ui/types": "17.2.0"
+    "@objectstack/spec": "^17.0.0-rc.6",
+    "react-hook-form": "^7.84.0",
+    "@object-ui/core": "17.5.0",
+    "@object-ui/data-objectstack": "17.5.0",
+    "@object-ui/i18n": "17.5.0",
+    "@object-ui/types": "17.5.0"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@types/react": "19.2.17",
-    "@types/react-dom": "19.2.3",
+    "@types/react": "19.2.18",
+    "@types/react-dom": "19.2.4",
     "typescript": "^6.0.3"
   },
   "keywords": [
@@ -65,7 +65,7 @@
   "scripts": {
     "build": "tsc",
     "test": "vitest run",
-    "type-check": "tsc --noEmit && tsc -p tsconfig.typetests.json",
+    "type-check": "tsc --noEmit && tsc -p tsconfig.test.json",
     "lint": "eslint ."
   }
 }