@object-ui/react 17.1.0 → 17.3.0

package/CHANGELOG.md

@@ -1,5 +1,204 @@
 # @object-ui/react
 
+## 17.3.0
+
+### Patch Changes
+
+- d915c47: Relation fields (`lookup` / `master_detail` / `user` / `tree`) are now usable in action and conditional-formatting predicates: they bind as the stored foreign key on every surface, and the fields a predicate reads are included in the query projection (#3501).
+
+  Before this, one predicate over one relation field had four different fates, decided by things its author does not control. `$expand` **replaces** the id in place with the whole related record, and a view expands exactly the relations it shows as COLUMNS — so `record.owner == "U1"` was **true** where the column was absent, **false** where it was displayed, and a **fault** where the field was neither displayed nor projected (a list's `$select` was built from its columns alone, and CEL treats an absent key as a fault, not as null). A fault is fail-CLOSED on the row kebab and the selection bar and fail-OPEN on the lenient paths, so the same authoring mistake hid the button from everyone on one surface and showed it to everyone on the next, with nothing on screen to point at either. The server, meanwhile, only ever sees the id — so client and server could not agree, which is the one thing ADR-0036 / ADR-0058 exist to guarantee.
+
+  Two changes close it. `toPredicateRecord` (new, `@object-ui/core`) collapses expanded relation values back to their ids when a record is bound for evaluation — driven by the object's own field types, not by sniffing for an `id` key, so a `json` field that happens to carry one is untouched. It is threaded through `evalRowPredicate` / `resolveConditionalFormatting` (via a new `fields` option), `useRowPredicate`, `partitionBulkRows`, and both `page:header` evaluators, with the object schema supplied by `ObjectGrid` / `ListView` / `ObjectKanban` / the record context. Kanban card formatting is threaded the same way, so a rule cannot match on the grid view of a list and silently never match on its board. Display is unaffected — a detail-page title still renders the related record's name, and the schema-only `kanban-ui` entry point (which has no object schema to offer) keeps using the payload verbatim. `collectPredicateFieldRefs` / `listViewPredicates` (new) harvest the `record.x` / `data.x` references out of a view's conditional formatting, row-action defs, bulk-action defs, promoted object actions and `userActions` overrides, and add them to `$select` — intersected with the object's declared fields plus the platform columns every object carries (`isProjectableField`), because an unknown key is not ignored by every backend. No `$expand` is added: a predicate wants the foreign key, which is what an unexpanded relation already is.
+
+- 175bd79: `toPredicateInput` is now re-exported from `@object-ui/core` instead of being reimplemented in `@object-ui/react`. Behaviour is byte-for-byte identical — the renderer-side copy in `packages/react/src/hooks/useExpression.ts` had item-for-item the same semantics as the canonical `packages/core/src/evaluator/predicateInput.ts` (booleans short-circuit, bare strings and non-`cel` dialects become `${…}`, a `{ dialect: 'cel', source }` envelope survives so `useCondition` routes it to the canonical `@objectstack/formula` engine, empty/absent predicates become `undefined`), and every existing import path (`import { toPredicateInput } from '@object-ui/react'`) keeps working with an unchanged signature. What changes is that there is now ONE implementation rather than two held in step by a parity table: #3314 is the record of what two normalizations do when left alone — they drift, and the same `visible:` predicate reaches different verdicts depending on whether the action was surfaced by `ActionEngine.getActionsForLocation` or rendered standalone. The 14-shape normalization parity table degenerated once both of its columns called the same function, so it is replaced by a single identity assertion (`react`'s export IS `core`'s function object); the engine-path-vs-renderer-path verdict parity suite is untouched and still proves the two call paths agree (#3367).
+- Updated dependencies [18cd432]
+- Updated dependencies [d915c47]
+- Updated dependencies [b71fc92]
+- Updated dependencies [65516ba]
+- Updated dependencies [94c5b7c]
+- Updated dependencies [ca0fa8f]
+- Updated dependencies [3889ffb]
+- Updated dependencies [5781fb1]
+- Updated dependencies [7e2406a]
+- Updated dependencies [9e9e9a9]
+- Updated dependencies [4eeb932]
+- Updated dependencies [5c856ec]
+- Updated dependencies [23018cc]
+- Updated dependencies [68b6a28]
+- Updated dependencies [0554e88]
+- Updated dependencies [d915c47]
+- Updated dependencies [f44d872]
+- Updated dependencies [28b2e65]
+- Updated dependencies [509104a]
+- Updated dependencies [825bbe3]
+- Updated dependencies [6195841]
+- Updated dependencies [5dd0127]
+- Updated dependencies [a415684]
+- Updated dependencies [a4cff5b]
+- Updated dependencies [5af2852]
+- Updated dependencies [f833d3a]
+- Updated dependencies [a6ec93d]
+- Updated dependencies [2a9513d]
+- Updated dependencies [d22ae31]
+- Updated dependencies [c7ed4c3]
+- Updated dependencies [2409e1d]
+- Updated dependencies [789fe3e]
+  - @object-ui/core@17.3.0
+  - @object-ui/types@17.3.0
+  - @object-ui/i18n@17.3.0
+  - @object-ui/data-objectstack@17.3.0
+
+## 17.2.0
+
+### Minor Changes
+
+- a889e31: A record's approval band now shows the quorum / per-group tally the server already computes.
+
+  The showcase's `showcase_committee_quorum` node declares `behavior: 'quorum'` with
+  `minApprovals: 2` over three approvers, and even ships a pre-rendered
+  `"Committee Sign-off (2 of 3)"` label; `showcase_expense_signoff` declares
+  `per_group` (会签) with named manager / finance groups. On the business record
+  the approval band rendered none of it — the lock badge, the recall button and
+  the approve/reject actions were all correct, but a two-of-three committee step
+  looked exactly like a one-approver step. An approver could not see whether their
+  own click finalized the node or was one of three, which is the single fact a
+  quorum node exists to express (objectstack#4478).
+
+  Nothing was wrong on the wire, and nothing here papers over the server. The
+  framework computes `decision_progress` — `{ behavior, got, need, groups? }`,
+  derived from the node's own `node_config_json` snapshot, so the count a client
+  shows is the count the engine will enforce. **It attaches that block in
+  `getRequest` only**: `listRequests` deliberately skips it, because the
+  `sys_approval_action` tally it costs is per row and a list read may return
+  hundreds. The record header's `useRecordApprovals` reads
+  `GET /approvals/requests?object=…&recordId=…` — the list route — so the
+  enrichment was never in the payload it had. The hook now follows up with one
+  single read for the ONE pending row and folds the result onto it; a failed or
+  mismatched follow-up leaves the row exactly as the list sent it, so a display-only
+  enrichment can never take the approval panel down and no tally is ever invented.
+
+  `InlineEditProvider` carries the block through as `approvalProgress`, and the
+  DetailView approval band renders it beside the existing badge: a labelled
+  `role="progressbar"` with one tick per required approval for `quorum` /
+  `unanimous`, and for `per_group` a chip per group marking which have signed
+  (`finance 1/1` ✓, `manager 0/1`). Group names come from the flow author's own
+  config, so they need no locale strings; the three new label keys are added to all
+  ten packs. `first_response` nodes carry no `decision_progress` and are unchanged —
+  one decision is the whole step there, and a "1 of 1" bar would be noise.
+
+  Scored `minor` rather than `patch`: this is new observable rendering plus a new
+  public `approvalProgress` prop / `ApprovalProgress` type on `@object-ui/react`,
+  not a behavior correction inside an existing surface.
+
+- 09d30a4: Stop declaring 18 `@object-ui/auth` / `@object-ui/components` / `@object-ui/react`
+  symbols under names `@objectstack/spec` owns (objectui#3159, objectstack#4115
+  batch 5).
+
+  **Breaking for importers of all three packages** — six exported names changed,
+  because the spec exports the same name for a _different_ thing:
+
+  | package      | was                          | now                      | what the spec's same-named export actually is                                  |
+  | :----------- | :--------------------------- | :----------------------- | :----------------------------------------------------------------------------- |
+  | `auth`       | `AuthSession`                | `AuthClientSession`      | the SERVER's session record (`{ id, userId, expiresAt: ISO string, token? }`)  |
+  | `auth`       | `AuthProviderConfig`         | `AuthProviderOptions`    | an OAuth/OIDC provider registration (`{ id, clientId, clientSecret, scope? }`) |
+  | `components` | `FilterCondition`            | `FilterBuilderCondition` | the recursive ObjectQL predicate AST (`$and`/`$or`/`$not`)                     |
+  | `components` | `Field`                      | `FieldContainer`         | an object FIELD's metadata and its builder namespace                           |
+  | `react`      | `ConflictResolutionStrategy` | `ConflictResolution`     | the metadata-MERGE policy (`error \| priority \| first-wins \| last-wins`)     |
+
+  The `react` rename is the odd one out: the new name is the **spec's own** name
+  for the union that hook always used, so it is a re-export rather than a dialect.
+
+  Eleven more keep their names and are now **imported or derived from the spec**
+  instead of re-declared: `TenancyPosture`, `DelegableScope` (+`DelegableAdminScope`),
+  `AuthUser`, `ShareLinkPermission`, `ShareLinkAudience`, `ShareLink`, `SortItem`,
+  `OfflineStrategy`, `OfflineCacheConfig`, `OfflineSyncConfig`, `OfflineConfig`,
+  `NavigationConfig`.
+
+  **Three of the copies were losing information, not just duplicating it.**
+
+  - `AuthUser` never declared the spec's `positions` or `tenantId` — the
+    authorization inputs. Its `[key: string]: unknown` index signature meant the
+    omission was invisible at every call site _and_ to any structural comparison
+    (the objectstack#4075 mechanism). It now `extends` the spec principal, so the
+    display-only fields (`image`, `role`, `roles`, `emailVerified`) are the delta
+    and the spec's keys arrive on their own.
+  - `useNavigationOverlay`'s copy carried the note _"inline … to avoid importing
+    from `@object-ui/types` (which may not be a direct dependency of
+    `@object-ui/react`)"_. The vocabulary belongs to `@objectstack/spec`, which
+    **is** a direct dependency — the same expired "kept local to avoid a
+    dependency" comment objectui#3169 found in `@object-ui/app-shell`.
+  - `useOffline` and `usePerformance` both opened with _"Types aligned with
+    `@objectstack/spec` v2.0.7"_. The installed spec is 17.0.0-rc.1.
+
+  `ShareLink` derives from the spec row **minus `password_hash`** — omitted rather
+  than optional, because it is the credential itself and typing it in a browser
+  package is an invitation to render it. `password_protected` (the boolean the UI
+  needs in its place) is the one local addition.
+
+  The config types derive from each schema's **input** side, not `z.infer`.
+  `useOffline(config: OfflineConfig = {})` defaults to the empty object, which the
+  output type — every `.default()`ed key required — would reject outright.
+
+  `@objectstack/spec` moves from `devDependencies` to `dependencies` in
+  `@object-ui/components`: its public type surface now references the spec.
+
+  Scored `minor`, not `major`, per this repo's fixed-group rule — objectui's major
+  tracks `@objectstack`, so breaking changes of our own ship as minor with the
+  semantics spelled out above (see AGENTS.md §版本号策略). A `major` here would carry
+  all 39 packages of the fixed group to `18.0.0` and off objectstack's 17.x line.
+
+### Patch Changes
+
+- ea96284: `useMetadataItem` no longer spins forever outside a `<MetadataProvider>` — the "graceful fallback" was the thing that made those consumers impossible to mount.
+
+  `useMetadata()` built its no-provider fallback **inline on every call**, so outside a provider
+  every render produced a new `getItem`. `useMetadataItem` lists `getItem` in its effect deps and,
+  on the no-name path, called `setState({ item: null, loading: false, error: null })` with a fresh
+  object each run. New identity → effect re-runs → new state object → re-render → new identity:
+  an unbreakable loop, synchronous enough to hang inside `render()` rather than fail.
+
+  So the fallback documented as the graceful path for consumers mounted outside a provider —
+  "common in unit tests that only need to assert on rendering" — was precisely what made them
+  unmountable. `record:alert` and `record:quick_actions` both call `useMetadataItem`
+  unconditionally; each pinned a core and grew unbounded (8.6 GB before the first kill) on a
+  `render()` that never returned.
+
+  Two changes, at the cause and one layer in:
+
+  - The fallback is a frozen module-level singleton, so its identity is stable across renders.
+  - The clear-state path bails out when the state is already cleared, instead of installing an
+    equal-but-new object. That covers the same loop arriving by another route — any caller whose
+    context value is rebuilt per render, which this interface explicitly invites ("hand-rolled
+    context values in tests keep working").
+
+  Found by `apps/console/src/__tests__/record-block-record-reach.test.tsx` (objectui#3149), which
+  could not mount either block until this was fixed.
+
+- Updated dependencies [4ae0ac4]
+- Updated dependencies [696e3c1]
+- Updated dependencies [bca45cc]
+- Updated dependencies [a889e31]
+- Updated dependencies [4bf612c]
+- Updated dependencies [335041c]
+- Updated dependencies [b414983]
+- Updated dependencies [256f8cc]
+- Updated dependencies [c5ccbd5]
+- Updated dependencies [d9668a7]
+- Updated dependencies [4b470b9]
+- Updated dependencies [cb82705]
+- Updated dependencies [f572849]
+- Updated dependencies [d3584c6]
+- Updated dependencies [a8ad6c0]
+- Updated dependencies [444457c]
+- Updated dependencies [850033c]
+- Updated dependencies [022e4c3]
+- Updated dependencies [009e25d]
+- Updated dependencies [726b89c]
+  - @object-ui/types@17.2.0
+  - @object-ui/core@17.2.0
+  - @object-ui/i18n@17.2.0
+  - @object-ui/data-objectstack@17.2.0
+
 ## 17.1.0
 
 ### Minor Changes

package/dist/context/AppShellContext.js

@@ -7,30 +7,50 @@ export function useAdapter() {
     return useContext(AdapterCtx);
 }
 export const MetadataCtx = createContext(null);
+/** Shared frozen empty list for the fallback below — see {@link NO_METADATA_PROVIDER}. */
+const NO_ITEMS = Object.freeze([]);
+/**
+ * The no-provider fallback, as a MODULE-LEVEL SINGLETON.
+ *
+ * Identity matters here, not just shape. `useMetadata()` used to build this
+ * object inline on every call, so outside a `<MetadataProvider>` every render
+ * produced a new `getItem` — and `useMetadataItem` lists `getItem` in its
+ * effect deps and calls `setState({...})` with a fresh object on every run. New
+ * identity → effect re-runs → new state object → re-render → new identity: an
+ * unbreakable render loop, synchronous enough to hang inside `render()`.
+ *
+ * So the fallback documented as the graceful path for consumers mounted outside
+ * a provider was the one thing that made those consumers impossible to mount —
+ * `record:alert` and `record:quick_actions` both call `useMetadataItem`
+ * unconditionally, and both spin. Found by
+ * `apps/console/src/__tests__/record-block-record-reach.test.tsx`
+ * (objectui#3149), which could not mount them at all until this was frozen.
+ *
+ * Frozen so a consumer cannot mutate the shared fallback out from under every
+ * other consumer of it.
+ */
+const NO_METADATA_PROVIDER = Object.freeze({
+    apps: NO_ITEMS,
+    objects: NO_ITEMS,
+    dashboards: NO_ITEMS,
+    reports: NO_ITEMS,
+    pages: NO_ITEMS,
+    loading: false,
+    error: null,
+    refresh: async () => { },
+    invalidate: () => { },
+    ensureType: async () => [],
+    getItem: async () => null,
+    getItemsByType: () => [],
+    getTypeStatus: () => 'ready',
+});
 export function useMetadata() {
     const ctx = useContext(MetadataCtx);
-    if (!ctx) {
-        // Graceful fallback: when a consumer is rendered outside a MetadataProvider
-        // (common in unit tests that only need to assert on rendering), return an
-        // empty no-op implementation rather than crash. Production code paths
-        // should always wrap in <MetadataProvider>.
-        return {
-            apps: [],
-            objects: [],
-            dashboards: [],
-            reports: [],
-            pages: [],
-            loading: false,
-            error: null,
-            refresh: async () => { },
-            invalidate: () => { },
-            ensureType: async () => [],
-            getItem: async () => null,
-            getItemsByType: () => [],
-            getTypeStatus: () => 'ready',
-        };
-    }
-    return ctx;
+    // Graceful fallback: a consumer rendered outside a MetadataProvider (unit
+    // tests that only assert on rendering, standalone previews) gets an empty
+    // no-op implementation rather than a crash. Production code paths should
+    // always wrap in <MetadataProvider>.
+    return ctx ?? NO_METADATA_PROVIDER;
 }
 export function useMetadataItem(type, name) {
     const { getItem } = useMetadata();
@@ -41,7 +61,15 @@ export function useMetadataItem(type, name) {
     });
     useEffect(() => {
         if (!name) {
-            setState({ item: null, loading: false, error: null });
+            // Bail out when already cleared instead of installing a fresh object.
+            // Belt-and-braces against the loop the frozen fallback above fixes at the
+            // source: `getItem` is an effect dep, so ANY caller whose context value
+            // is rebuilt per render — a hand-rolled one in a test, which this
+            // interface explicitly invites — would otherwise re-run this effect,
+            // re-set an equal-but-new state object, and re-render forever.
+            setState((s) => (s.item === null && !s.loading && s.error === null
+                ? s
+                : { item: null, loading: false, error: null }));
             return;
         }
         let cancelled = false;

package/dist/context/InlineEditContext.d.ts

@@ -22,6 +22,34 @@
  * context for the draft/editing flags and drives `saving`/`error`/`reset`.
  */
 import React from 'react';
+/**
+ * Server-computed decision aggregation of the record's pending approval node
+ * (framework#3266, `decision_progress` on `GET /approvals/requests/:id`).
+ *
+ * A multi-approver node does NOT finalize on the first decision: `unanimous`
+ * needs everyone, `quorum` needs `minApprovals` of the slate, `per_group` (会签)
+ * needs each named group to sign. Without the tally, an approver looking at the
+ * record cannot tell whether their own click completes the step or is one of
+ * three — the fact the whole node is about (objectstack#4478). The server does
+ * the counting so every client renders the same "2 of 3" the engine enforces.
+ *
+ * Absent for `first_response` nodes (one decision finalizes, so there is no
+ * progress to show) and for a backend that predates the enrichment.
+ */
+export interface ApprovalProgress {
+    behavior: 'unanimous' | 'quorum' | 'per_group';
+    /** Approvals recorded so far — satisfied GROUPS when `behavior` is `per_group`. */
+    got: number;
+    /** Approvals required to finalize — total GROUPS when `behavior` is `per_group`. */
+    need: number;
+    /** Per-group tally, `per_group` only. */
+    groups?: Array<{
+        group: string;
+        got: number;
+        need: number;
+        satisfied: boolean;
+    }>;
+}
 export interface InlineEditContextValue {
     /** True while the record is in inline-edit mode. */
     editing: boolean;
@@ -58,6 +86,15 @@ export interface InlineEditContextValue {
      * still get a coherent band. Defaults to `false`.
      */
     approvalPending: boolean;
+    /**
+     * Quorum / per-group tally of the pending approval node, when it aggregates
+     * more than one decision (objectstack#4478). Threaded verbatim from the
+     * host's approvals read so the band renders the server's count instead of
+     * re-deriving the engine's tally rules. Undefined when no approval is
+     * running, when the node finalizes on the first response, or when the host
+     * doesn't resolve approvals at all.
+     */
+    approvalProgress?: ApprovalProgress;
     /**
      * Human-readable reason for the approval lock, surfaced as the band's
      * tooltip. Optional — consumers fall back to their own localized default
@@ -109,6 +146,12 @@ export interface InlineEditProviderProps {
      * only know about the lock rendering exactly as before.
      */
     approvalPending?: boolean;
+    /**
+     * The pending node's server-computed decision tally (objectstack#4478).
+     * Surfaced verbatim so the band can show "2 of 3" / per-group ticks. Omitted
+     * for `first_response` nodes and for hosts that don't read approvals.
+     */
+    approvalProgress?: ApprovalProgress;
     /** Optional human-readable lock reason, surfaced as the band tooltip. */
     lockedReason?: string;
     children: React.ReactNode;

package/dist/context/InlineEditContext.js

@@ -24,7 +24,7 @@ import { jsx as _jsx } from "react/jsx-runtime";
  */
 import React from 'react';
 const InlineEditContext = React.createContext(null);
-export const InlineEditProvider = ({ canEdit = true, locked = false, approvalPending, lockedReason, children, }) => {
+export const InlineEditProvider = ({ canEdit = true, locked = false, approvalPending, approvalProgress, lockedReason, children, }) => {
     // A locked record always has an approval running; the converse is what
     // #2902 added. Defaulting this way means an un-migrated host keeps its
     // previous behavior with no code change.
@@ -62,6 +62,7 @@ export const InlineEditProvider = ({ canEdit = true, locked = false, approvalPen
         canEdit,
         locked,
         approvalPending: pending,
+        approvalProgress,
         lockedReason,
         draft,
         autoFocusField,
@@ -73,7 +74,7 @@ export const InlineEditProvider = ({ canEdit = true, locked = false, approvalPen
         reset: teardown,
         setSaving,
         setError,
-    }), [editing, canEdit, locked, pending, lockedReason, draft, autoFocusField, saving, error, enter, setField, teardown]);
+    }), [editing, canEdit, locked, pending, approvalProgress, lockedReason, draft, autoFocusField, saving, error, enter, setField, teardown]);
     return _jsx(InlineEditContext.Provider, { value: value, children: children });
 };
 /**

package/dist/hooks/useExpression.d.ts

@@ -26,24 +26,36 @@ export declare function PredicateScopeProvider({ scope, children, }: {
 export declare function usePredicateScope(): Record<string, any>;
 /**
  * Normalize a schema-supplied predicate (`visible` / `enabled` / `disabled` /
- * `hidden`) into the `${expr}` template form expected by `useCondition`.
+ * `hidden`) into the form `useCondition` expects — the canonical helper to use
+ * in renderers so we never end up with `${[object Object]}` after JS
+ * template-literal interpolation.
  *
- * Accepts:
- *   - `boolean` → returned as-is (predicate hooks short-circuit on booleans).
- *   - `string`  → wrapped as `${string}` (legacy DX shorthand).
- *   - `Expression` envelope `{ dialect, source }` (new format from
- *     `@objectstack/spec`'s normalized predicate inputs) → unwrapped, then
- *     wrapped as `${source}`. Both `cel` and `template` dialects already use
- *     compatible variable syntax (`record.x`, etc.).
- *   - `null` / `undefined` / empty → `undefined` (default visible/enabled).
+ * **Re-exported from `@object-ui/core`, not reimplemented here.** There is
+ * exactly ONE implementation — `packages/core/src/evaluator/predicateInput.ts`
+ * — shared by the engine path (`ActionEngine.getActionsForLocation`) and the
+ * renderer path (`action-button` / `action-menu` / `action-bar` / …). See that
+ * file for the accepted input shapes and for why a `cel` envelope must survive
+ * normalization (#2661 / #3314).
  *
- * This is the canonical helper to use in renderers so we never end up with
- * `${[object Object]}` after JS template-literal interpolation.
+ * ## Why a re-export and not a twin (#3367)
+ *
+ * This module used to carry an independent renderer-side implementation with
+ * item-for-item identical semantics, held in step with the canonical one by a
+ * 14-shape normalization parity table. That table was a *guardrail against
+ * drift*, not a single source of truth — and #3314 is the record of what two
+ * normalizations do when left alone: they drift, and the same `visible:`
+ * predicate reaches different verdicts depending on which path surfaced the
+ * action. A re-export cannot drift, so the parity suite now pins identity
+ * (`react`'s export IS `core`'s function) instead of enumerating shapes, and
+ * keeps pinning the two PATHS verdict-for-verdict.
+ *
+ * Routing hook code through the `@object-ui/core` barrel is not a new coupling:
+ * this module already imports `ExpressionEvaluator` / `evalRowPredicate` from
+ * it, and `@object-ui/core` is a declared dependency of `@object-ui/react`
+ * (the reverse direction is the forbidden one — core declares "Zero React
+ * dependencies").
  */
-export declare function toPredicateInput(value: unknown): string | boolean | {
-    dialect: 'cel';
-    source: string;
-} | undefined;
+export { toPredicateInput } from '@object-ui/core';
 /**
  * Hook for evaluating expressions with dynamic context
  *
@@ -85,4 +97,11 @@ export declare function useRowPredicate(pred: unknown, row: Record<string, any>
     fallback?: boolean;
     warnOnError?: boolean;
     label?: string;
+    /**
+     * The object's field definitions. Supplying them binds a relation field as
+     * the stored foreign key instead of whatever `$expand` substituted for it
+     * on this surface, so `record.owner == os.user.id` reaches the server's
+     * verdict — see `toPredicateRecord`.
+     */
+    fields?: unknown;
 }): boolean;

package/dist/hooks/useExpression.js

@@ -40,41 +40,36 @@ export function usePredicateScope() {
 }
 /**
  * Normalize a schema-supplied predicate (`visible` / `enabled` / `disabled` /
- * `hidden`) into the `${expr}` template form expected by `useCondition`.
+ * `hidden`) into the form `useCondition` expects — the canonical helper to use
+ * in renderers so we never end up with `${[object Object]}` after JS
+ * template-literal interpolation.
  *
- * Accepts:
- *   - `boolean` → returned as-is (predicate hooks short-circuit on booleans).
- *   - `string`  → wrapped as `${string}` (legacy DX shorthand).
- *   - `Expression` envelope `{ dialect, source }` (new format from
- *     `@objectstack/spec`'s normalized predicate inputs) → unwrapped, then
- *     wrapped as `${source}`. Both `cel` and `template` dialects already use
- *     compatible variable syntax (`record.x`, etc.).
- *   - `null` / `undefined` / empty → `undefined` (default visible/enabled).
+ * **Re-exported from `@object-ui/core`, not reimplemented here.** There is
+ * exactly ONE implementation — `packages/core/src/evaluator/predicateInput.ts`
+ * — shared by the engine path (`ActionEngine.getActionsForLocation`) and the
+ * renderer path (`action-button` / `action-menu` / `action-bar` / …). See that
+ * file for the accepted input shapes and for why a `cel` envelope must survive
+ * normalization (#2661 / #3314).
  *
- * This is the canonical helper to use in renderers so we never end up with
- * `${[object Object]}` after JS template-literal interpolation.
+ * ## Why a re-export and not a twin (#3367)
+ *
+ * This module used to carry an independent renderer-side implementation with
+ * item-for-item identical semantics, held in step with the canonical one by a
+ * 14-shape normalization parity table. That table was a *guardrail against
+ * drift*, not a single source of truth — and #3314 is the record of what two
+ * normalizations do when left alone: they drift, and the same `visible:`
+ * predicate reaches different verdicts depending on which path surfaced the
+ * action. A re-export cannot drift, so the parity suite now pins identity
+ * (`react`'s export IS `core`'s function) instead of enumerating shapes, and
+ * keeps pinning the two PATHS verdict-for-verdict.
+ *
+ * Routing hook code through the `@object-ui/core` barrel is not a new coupling:
+ * this module already imports `ExpressionEvaluator` / `evalRowPredicate` from
+ * it, and `@object-ui/core` is a declared dependency of `@object-ui/react`
+ * (the reverse direction is the forbidden one — core declares "Zero React
+ * dependencies").
  */
-export function toPredicateInput(value) {
-    if (value === null || value === undefined || value === '')
-        return undefined;
-    if (typeof value === 'boolean')
-        return value;
-    if (typeof value === 'string')
-        return `\${${value}}`;
-    if (typeof value === 'object' && typeof value.source === 'string') {
-        const src = value.source;
-        if (!src)
-            return undefined;
-        // #2661 — preserve a CEL-dialect envelope so `useCondition` routes it to the
-        // canonical `@objectstack/formula` engine (identical verdict to the server),
-        // instead of collapsing it to a `${source}` string on the legacy JS path.
-        // Every other dialect (template / unset) keeps the legacy `${…}` behavior.
-        if (value.dialect === 'cel')
-            return { dialect: 'cel', source: src };
-        return `\${${src}}`;
-    }
-    return undefined;
-}
+export { toPredicateInput } from '@object-ui/core';
 /**
  * Hook for evaluating expressions with dynamic context
  *
@@ -160,6 +155,7 @@ export function useCondition(condition, context = {}, options) {
 export function useRowPredicate(pred, row, options) {
     const scope = usePredicateScope();
     const fallback = options?.fallback ?? true;
+    const fields = options?.fields;
     return useMemo(() => {
         // A boolean predicate short-circuits (no expression to evaluate).
         if (typeof pred === 'boolean')
@@ -171,6 +167,7 @@ export function useRowPredicate(pred, row, options) {
             scope,
             warnOnError: options?.warnOnError,
             label: options?.label,
+            fields: fields,
         });
-    }, [pred, row, scope, fallback, options?.warnOnError, options?.label]);
+    }, [pred, row, scope, fallback, options?.warnOnError, options?.label, fields]);
 }

package/dist/hooks/useNavigationOverlay.d.ts

@@ -5,21 +5,34 @@
  * 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';
 /**
- * Inline ViewNavigationConfig to avoid importing from @object-ui/types
- * (which may not be a direct dependency of @object-ui/react).
- * Mirrors the canonical definition in @object-ui/types/objectql.ts.
+ * The spec's `NavigationConfigSchema`, authoring side, with `mode` required.
+ *
+ * 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)".
+ * That reasoning is about the wrong package: the vocabulary belongs to
+ * `@objectstack/spec`, which IS a direct dependency of this one — the same
+ * expired "kept local to avoid a dependency" comment objectui#3169 found in
+ * `@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`.
+ *
+ * Two per-key notes the hand copy carried, kept here because a derived alias
+ * has no members to hang them on:
+ *  - `size` is the coarse overlay bucket added by #2578; `resolveOverlayWidth`
+ *    below maps it through {@link OVERLAY_SIZE_WIDTHS}.
+ *  - `width` is DEPRECATED by #2578 in favour of `size`. It still wins when
+ *    present, because app-shell pre-resolves `size` into it.
  */
-export interface NavigationConfig {
-    mode: 'page' | 'drawer' | 'modal' | 'split' | 'popover' | 'new_window' | 'none';
-    view?: string;
-    preventNavigation?: boolean;
-    openNewTab?: boolean;
-    /** Spec `NavigationConfig.size` (#2578) — coarse overlay bucket. */
-    size?: 'auto' | 'sm' | 'md' | 'lg' | 'xl' | 'full';
-    /** @deprecated [#2578 → `size`] explicit pixel/percent width. */
-    width?: string | number;
-}
+export type NavigationConfig = Omit<SpecAuthoredInput<typeof NavigationConfigSchema>, 'mode'> & {
+    mode: NonNullable<SpecAuthoredInput<typeof NavigationConfigSchema>['mode']>;
+};
 /**
  * Resolve the overlay width from a NavigationConfig: an explicit `width` wins
  * (app-shell pre-resolves `size` into it); otherwise a declared bucket maps

package/dist/hooks/useOffline.d.ts

@@ -5,14 +5,25 @@
  * 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 = 'cache_first' | 'network_first' | 'stale_while_revalidate' | 'network_only' | 'cache_only';
-/** Conflict resolution strategy for sync operations. */
-export type ConflictResolutionStrategy = 'manual' | 'client_wins' | 'server_wins' | 'last_write_wins';
+export type { OfflineStrategy };
+/**
+ * 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.
+ */
+export type { ConflictResolution };
 /** Persist storage backend. */
-export type PersistStorageType = 'indexeddb' | 'localstorage' | 'sqlite';
+export type PersistStorageType = PersistStorage;
 /** Eviction policy for cache management. */
-export type EvictionPolicyType = 'lru' | 'lfu' | 'fifo';
+export type EvictionPolicyType = EvictionPolicy;
 /** Sync state of the offline system. */
 export type SyncState = 'idle' | 'syncing' | 'error' | 'offline';
 /** A queued mutation waiting to be synced. */
@@ -23,31 +34,38 @@ export interface QueuedMutation {
     resource: string;
     data?: Record<string, unknown>;
 }
-/** Cache configuration aligned with OfflineCacheConfigSchema. */
-export interface OfflineCacheConfig {
-    maxSize?: number;
-    ttl?: number;
-    persistStorage?: PersistStorageType;
-    evictionPolicy?: EvictionPolicyType;
-}
-/** Sync configuration aligned with SyncConfigSchema. */
-export interface OfflineSyncConfig {
-    strategy?: OfflineStrategy;
-    conflictResolution?: ConflictResolutionStrategy;
-    retryInterval?: number;
-    maxRetries?: number;
-    batchSize?: number;
-}
-/** Top-level offline configuration aligned with OfflineConfigSchema. */
-export interface OfflineConfig {
-    enabled?: boolean;
-    strategy?: OfflineStrategy;
-    cache?: OfflineCacheConfig;
-    sync?: OfflineSyncConfig;
-    offlineIndicator?: boolean;
-    offlineMessage?: string;
-    queueMaxSize?: number;
-}
+/**
+ * Cache configuration — the AUTHORING side of the spec's
+ * `OfflineCacheConfigSchema`.
+ *
+ * `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}.
+ */
+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>;
+/**
+ * Top-level offline configuration — the AUTHORING side of the spec's
+ * `OfflineConfigSchema`.
+ *
+ * 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.
+ *
+ * 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.
+ */
+export type OfflineConfig = SpecAuthoredInput<typeof OfflineConfigSchema>;
 /** Result returned by the useOffline hook. */
 export interface OfflineResult {
     /** Whether the browser is currently online. */
@@ -72,9 +90,9 @@ export interface OfflineResult {
     offlineMessage: string;
 }
 /**
- * Hook for offline mode detection and sync queue management.
- * Implements OfflineConfigSchema, SyncConfigSchema, and ConflictResolutionSchema
- * from @objectstack/spec v2.0.7.
+ * Hook for offline mode detection and sync queue management. Its config types
+ * ARE the spec's `OfflineConfigSchema` / `SyncConfigSchema` / `ConflictResolution`
+ * (authoring side) — see {@link OfflineConfig}.
  *
  * @example
  * ```tsx

package/dist/hooks/useOffline.js

@@ -66,9 +66,9 @@ const DEFAULTS = {
     queueMaxSize: 100,
 };
 /**
- * Hook for offline mode detection and sync queue management.
- * Implements OfflineConfigSchema, SyncConfigSchema, and ConflictResolutionSchema
- * from @objectstack/spec v2.0.7.
+ * Hook for offline mode detection and sync queue management. Its config types
+ * ARE the spec's `OfflineConfigSchema` / `SyncConfigSchema` / `ConflictResolution`
+ * (authoring side) — see {@link OfflineConfig}.
  *
  * @example
  * ```tsx

package/dist/hooks/usePerformance.d.ts

@@ -13,7 +13,7 @@ export interface VirtualScrollConfig {
     itemHeight?: number;
     overscan?: number;
 }
-/** Performance configuration aligned with PerformanceConfigSchema. */
+/** Performance configuration. */
 export interface PerformanceConfig {
     /** Whether to lazy-load components/data. */
     lazyLoad?: boolean;
@@ -55,8 +55,8 @@ export interface PerformanceResult {
     debounce: <T extends (...args: unknown[]) => void>(fn: T) => T;
 }
 /**
- * Hook for performance monitoring and configuration aligned with
- * PerformanceConfigSchema from @objectstack/spec v2.0.7.
+ * Hook for performance monitoring and configuration. Its config type IS the
+ * spec's `PerformanceConfigSchema` (authoring side) — see {@link PerformanceConfig}.
  *
  * Provides resolved config values, Web Vitals metrics, and utility functions
  * (debounce, render marking) for performance-aware components.

package/dist/hooks/usePerformance.js

@@ -52,8 +52,8 @@ function getLCP() {
 // usePerformance hook
 // ---------------------------------------------------------------------------
 /**
- * Hook for performance monitoring and configuration aligned with
- * PerformanceConfigSchema from @objectstack/spec v2.0.7.
+ * Hook for performance monitoring and configuration. Its config type IS the
+ * spec's `PerformanceConfigSchema` (authoring side) — see {@link PerformanceConfig}.
  *
  * Provides resolved config values, Web Vitals metrics, and utility functions
  * (debounce, render marking) for performance-aware components.

package/dist/spec-input.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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.
+ */
+/**
+ * The AUTHORING ("input") type of a `@objectstack/spec` zod schema.
+ *
+ * ## Why not `z.infer`
+ *
+ * `z.infer` is the OUTPUT type — what `.parse()` returns, with every
+ * `.default()` already applied and therefore REQUIRED. The hooks in this
+ * package are handed configuration an app author wrote by hand, so the input
+ * side is the one that describes what they may legally omit. Deriving a config
+ * type from `z.infer` turns every defaulted key into a required one and makes
+ * the schema's own defaults unusable — the `_input`/`_output` trap the spec
+ * symbol guard's header warns about, and the one that already bit
+ * `ObjectFieldGroup` in objectui#3169.
+ *
+ * Rule of thumb: is this module WRITING the metadata, or READING what has
+ * already been parsed? Writing → input. Reading → `z.infer`.
+ *
+ * ## Why it reads `_zod`, not `z.input`
+ *
+ * `z.input<typeof S>` needs a `zod` import, and `@object-ui/react` deliberately
+ * does not depend on zod — it renders plain objects and never parses. The
+ * schema's own type already carries both sides in `_zod`, so the input type is
+ * reachable through the spec's binding alone, with no new dependency and no
+ * copy of the shape.
+ */
+export type SpecAuthoredInput<S extends {
+    _zod: {
+        input: unknown;
+    };
+}> = S['_zod']['input'];

package/dist/spec-input.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/react",
-  "version": "17.1.0",
+  "version": "17.3.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.0",
+    "@objectstack/spec": "^17.0.0-rc.2",
     "react-hook-form": "^7.83.0",
-    "@object-ui/core": "17.1.0",
-    "@object-ui/data-objectstack": "17.1.0",
-    "@object-ui/i18n": "17.1.0",
-    "@object-ui/types": "17.1.0"
+    "@object-ui/core": "17.3.0",
+    "@object-ui/data-objectstack": "17.3.0",
+    "@object-ui/i18n": "17.3.0",
+    "@object-ui/types": "17.3.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",
+    "type-check": "tsc --noEmit && tsc -p tsconfig.typetests.json",
     "lint": "eslint ."
   }
 }