@object-ui/plugin-detail 16.1.0 → 17.2.0

package/CHANGELOG.md

@@ -1,5 +1,819 @@
 # @object-ui/plugin-detail
 
+## 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.
+
+- 4a51e77: Stop declaring 14 symbols across ten packages under names `@objectstack/spec`
+  owns (objectui#3161, objectstack#4115 batch 7 — the long tail, one or two
+  entries per package). All ten packages leave the ledger, which drops from 17
+  collisions across 11 packages to 3 across 1.
+
+  **Renamed exports** — in every case the spec exports the same name for a
+  _different_ thing, so the old name was a mis-description rather than a dialect:
+
+  | package                    | was                                | now                                                  | what the spec's same-named export is                                                                                                       |
+  | :------------------------- | :--------------------------------- | :--------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------- |
+  | `@object-ui/fields`        | `FieldWidgetProps`                 | `FieldWidgetComponentProps`                          | the DECLARED field-widget plugin props contract (a zod object; `field.type` is the `FieldType` enum, `readonly`/`required` carry defaults) |
+  | `@object-ui/layout`        | `PageHeaderProps`                  | `PageHeaderComponentProps`                           | the authored `page:header` node — a zod schema of `title`, `subtitle`, an icon NAME, `breadcrumb`, `actions: string[]`                     |
+  | `@object-ui/layout`        | `Page`                             | `PageNodeRenderer`                                   | the authored page metadata DOCUMENT (`name`, `label`, `type`, `regions`)                                                                   |
+  | `@object-ui/plugin-detail` | `ObjectFieldLike`                  | `ObjectDefFieldLike`                                 | the i18n duck type `translateObject` walks (`help`/`description`, plus `[key: string]: any`)                                               |
+  | `@object-ui/plugin-grid`   | `ColumnSummaryConfig`              | `ColumnSummarySetting`                               | the OBJECT form of `ListColumn.summary` **only** — the local one was the whole union, shorthand included                                   |
+  | `@object-ui/plugin-grid`   | `isMultiValueField`                | `hasMultiValueShape`                                 | the spec's classifier, which requires a def with a `type`; the local one is called with `undefined`                                        |
+  | `@object-ui/collaboration` | `RealtimeConfig`                   | `RealtimeSubscriptionConfig`                         | the app's realtime DECLARATION (`enabled`, `transport`, `subscriptions[]`)                                                                 |
+  | `@object-ui/plugin-charts` | `ChartConfig`                      | `ChartContainerConfig`                               | the authored chart document (`type`, `xAxis`, `series`, `showLegend`, …)                                                                   |
+  | `@object-ui/plugin-form`   | `FormSection` / `FormSectionProps` | `FormSectionContainer` / `FormSectionContainerProps` | the authored form-section metadata (`name`, `pane`, `visibleWhen`, `fields`)                                                               |
+  | `@object-ui/providers`     | `Theme`                            | `ThemePreference`                                    | a whole theme DOCUMENT (`name`, `label`, `colors`, `typography`)                                                                           |
+  | `@object-ui/runner`        | `App` (default export)             | `RunnerApp`                                          | the authored application metadata type **and** the `App.create()` builder                                                                  |
+  | `@object-ui/sdui-parser`   | `ValidationResult`                 | `ManifestValidationResult`                           | plugin-manifest validation (`{ valid, errors?, warnings? }`), exported from both `kernel` and `contracts`                                  |
+
+  `ManifestValidationResult` follows the `<what was validated>Validation<Error|Result>`
+  convention registered on objectstack#4115 (`@object-ui/core` took
+  `SchemaNodeValidationResult` in batch 4). `PageHeaderComponentProps` deliberately
+  reuses the name `@object-ui/app-shell` already chose for its own header props in
+  batch 3, so one concept does not acquire two dialect names one package apart.
+
+  **Now derived from the spec instead of hand-written:**
+
+  - `@object-ui/fields` — `isFileIdToken` is re-exported from
+    `@objectstack/spec/data`. The local copy was character-for-character identical
+    to the spec's function while its comment said it "mirrors" it, so every
+    behaviour test passed and only reference identity could tell the two apart.
+    The regex is a wire decision: widening it server-side while a copy here kept
+    the old bound would make every new id read as "not a reference", and the
+    widget would submit the legacy inline blob to a backend expecting a reference.
+  - `@object-ui/plugin-detail` — `FeedFilterMode` is re-exported from
+    `@objectstack/spec/data`, in a file that already imported the sibling
+    `FeedItemType` from the spec.
+  - `@object-ui/plugin-grid` — the eleven-member aggregation union is now the
+    spec's `ColumnSummary` enum, so the total `Record<ColumnSummaryType, string>`
+    label map turns a member the spec adds into a compile error instead of a
+    blank footer cell. `ColumnSummarySetting` is `NonNullable<ListColumn['summary']>`,
+    i.e. whatever forms the spec itself accepts. `hasMultiValueShape` delegates to
+    the spec's `isMultiValueField` rather than re-deriving it from
+    `MULTI_OPTION_TYPES` / `MULTI_CAPABLE_TYPES`.
+  - `@object-ui/providers` — `ThemePreference` is the spec's `ThemeMode` union
+    plus the one legacy `'system'` spelling this provider still honours for stored
+    preferences, read off the schema's own `_zod` carrier so the package takes no
+    zod dependency.
+
+  `@objectstack/spec` moves from `devDependencies` to `dependencies` in
+  `@object-ui/fields` (it re-exports a runtime function) and `@object-ui/providers`
+  (its public `.d.ts` 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.
+
+- dd06bcd: `record:activity` fetches a feed instead of rendering a permanently empty one (objectui#3165).
+
+  The block published eleven inputs — `types`, `filterMode`, `showFilterToggle`,
+  `limit`, `showCompleted`, `unifiedTimeline`, `showCommentInput`,
+  `enableMentions`, `enableReactions`, `enableThreading`,
+  `showSubscriptionToggle` — every one of them a filter or an affordance over a
+  feed that could not have content on any path. `RecordActivityRenderer` called
+  `useRecordContext()`, discarded the result and rendered
+  `<RecordActivityTimeline items={[]}>` with the empty array hard-coded; the
+  timeline takes `items` as a prop and never fetched; no host supplied any
+  (`buildDefaultPageSchema` emits `{ type: 'record:activity' }` with no props at
+  all). Declared, published to `sdui.manifest.json`, inert at runtime —
+  objectstack#4413's shape, three blocks over.
+
+  **The feed now has three sources, in precedence order.** `items` on the node
+  (the convention `record:history` uses for `entries`); a mounted
+  `DiscussionContext`, which the console's record page fills with the merged
+  `sys_comment` + `sys_activity` feed and the write handlers; otherwise a
+  **self-fetch** of `sys_activity` scoped to the bound record
+  (`{ object_name, record_id }`, newest first, `limit` rows per page, "Load more"
+  re-reading a wider window). The third path is what makes the block
+  drop-anywhere — hand-authored inside a `page:tabs`, with no host feeding it —
+  and it mirrors the read `record:history` already had. Rows map to feed items
+  exactly as the console's record page maps them, so both surfaces agree about
+  what a row is.
+
+  **The read-side inputs now filter.** `types` is an allow-list over feed item
+  types (unrecognised entries ignored; an all-typo list is treated as unset
+  rather than emptying the feed). `limit` is a page size and caps the scoped
+  read. `showCompleted` (spec default `false`) hides completed activities.
+  `unifiedTimeline: false` un-mixes field changes from the comment stream — the
+  panel becomes a discussion feed and field changes stay in `record:history`.
+  `filterMode` seeds which slice the dropdown opens on and falls back to `all`
+  on an unrecognised value instead of leaving a `<Select>` matching nothing.
+
+  **The write-side switches are wired to the host's handlers.**
+  `showCommentInput`, `enableThreading`, `enableReactions` and `enableMentions`
+  read `onAddComment` / `onAddReply` / `onToggleReaction` /
+  `mentionSuggestions` off `DiscussionContext` — the same standing
+  `record:discussion` has. With no host mounted the feed stays read-only and no
+  composer is rendered, rather than showing one that silently drops what you
+  type.
+
+  **`showSubscriptionToggle` is recorded as a known gap, not quietly left
+  looking configurable.** The bell needs a `RecordSubscription` value and
+  somewhere to persist it, and the platform has no record-subscription object to
+  read or write one from. Its input description now says `NOT IMPLEMENTED` (that
+  text ships to `sdui.manifest.json`, so an author meets it before writing the
+  prop), the docs repeat it, and a test pins it inert so the note has to be
+  deleted the day a backend for it lands.
+
+  `apps/console`'s record-reach probe (objectui#3149 layer 3a) asserted the old
+  behaviour from its `NO_RECORD_REACH` ledger in both directions; that entry is
+  deleted, and the probe now reports `record:activity` as responding to the bound
+  record.
+
+### Patch Changes
+
+- 6be575c: A fetching activity feed says "loading", not "No activity recorded" (objectui#3205).
+
+  `RecordActivityTimeline` declared a `loading` prop and destructured it straight
+  into `_loading`, so nothing in the component ever read it. For the whole
+  duration of a feed fetch the panel therefore rendered the empty state — "No
+  activity recorded" — and then contradicted itself when the rows landed. The
+  empty copy is a factual claim about the record; it may only be made once the
+  fetch that would fill the feed has settled.
+
+  The timeline now branches on `loading` **before** the empty branch and renders a
+  spinner row (`role="status"`, `aria-live="polite"`) while the feed is in flight.
+  `collapseWhenEmpty` does not suppress it: that flag is about the empty state
+  ("collapse when there are no items"), and mid-fetch it is not yet known whether
+  there are items.
+
+  The guard is `loading && filtered.length === 0`, not `loading` alone — a refresh
+  or a "Load more" round-trip keeps the rows already on screen instead of blanking
+  them (that button carries its own spinner).
+
+  No prop or signature changed: the fix is that the declared prop is now read.
+  `record:activity` has computed a live `loading` since objectui#3165 (true during
+  its self-fetch) and `RecordChatterPanel` already forwarded it in both positions,
+  so the whole chain now shows a loading state end to end.
+
+- Updated dependencies [a889e31]
+- Updated dependencies [4b470b9]
+  - @object-ui/i18n@17.2.0
+
+## 17.1.0
+
+### Minor Changes
+
+- 1cf0de7: fix(detail): finish the approval-lock story, and warn on silently stripped fields (framework#3794)
+
+  The Console reported record writability wrong in both directions during an
+  approval, so a user had nothing to go on: what they _could_ edit said "locked",
+  and what they _couldn't_ said "updated successfully".
+
+  **The lock band told the truth; the Edit button did not.** objectui#2902 split
+  the band into "in approval · editable" vs locked, but the header **Edit** CTA
+  still keyed off nothing at all — on a genuinely locked record it stayed live, so
+  the user opened the form, filled a screen, and got `RECORD_LOCKED` back on Save.
+  It is now `disabled` on a locked record: visible-but-off, with the band beside it
+  saying why. This is the LOCK, not the mere presence of an approval — a
+  `lockRecord: false` node keeps Edit live, which is the point of that setting.
+
+  **And the band could still re-lock itself.** `DetailView` OR-ed the record's own
+  `approval_status` mirror into `isLocked` unconditionally. That mirror is written
+  on submit by any flow configuring an `approvalStatusField`, _regardless of_
+  `lockRecord` — so on a `lockRecord: false` node the host correctly resolved "not
+  locked" from the request's `lock_record` while the mirror dragged the band back
+  to "Locked for approval", with the pencils live and saves landing underneath it.
+  The host is now authoritative whenever it threads `approvalPending`; the mirror
+  is consulted only for bare/legacy `DetailView` hosts that thread nothing, where
+  it still reads as locked (no node granularity — the safe direction).
+
+  Recall's tooltip no longer promises to unlock a record the node never locked
+  (`detail.cancelApprovalTooltipUnlocked`).
+
+  **Silently stripped fields now surface on the record form's save path.** The
+  adapter emitted a write-warning for `create`/`update` responses carrying
+  `droppedFields`, but not for `batchTransaction` — which is how the record form
+  saves a master-detail record, i.e. the one surface where a user actually edits a
+  `readonlyWhen`-locked field. `batchTransaction` now emits one warning per event,
+  resolving each back to its operation via the response's `index`.
+
+  The toast itself was hardcoded English and called every strip "read-only". It is
+  now localized (`detail.writeStripped*`, ten locales) and worded by reason:
+  `readonly_when` says the field is not editable _in this record's current state_,
+  which is what actually happened — the field is editable in other states and the
+  form rendered it as an ordinary input, so "read-only" sent the user hunting for a
+  permission problem that does not exist.
+
+  **And it stopped crying wolf.** `createObjectStackUserStateAdapter` hand-stamped
+  the server-managed `updated_at` on every recents/favorites write, which the
+  server strips and reports — so the console popped "Some fields were not saved"
+  about a field no user ever touched, on page loads, drowning the signal the toast
+  exists for. It no longer sends the column; the server stamps it anyway.
+
+- 390c071: feat(record): declare inputs for the seven configurable record:\* blocks, and curate six
+
+  Seven `record:*` blocks shipped with renderers that read props but declared no
+  `inputs`. That combination is the worst of both: the renderer honours
+  `limit`, `severity`, `location` …, while every authoring surface — the designer
+  panel, the AI vocabulary, the generated manifest — reports the block takes no
+  configuration. objectui#3013 recorded them as deliberately uncurated for
+  exactly that reason.
+
+  The declarations mirror what each renderer actually reads:
+
+  | block                                  | inputs                                                                       |
+  | -------------------------------------- | ---------------------------------------------------------------------------- |
+  | `record:activity`                      | 11 — from `RecordActivityComponentProps`                                     |
+  | `record:chatter` / `record:discussion` | 5 — from `RecordChatterComponentProps`                                       |
+  | `record:alert`                         | 8 — severity, title, body, visible, icon, action, dismissible, dismissKey    |
+  | `record:quick_actions`                 | 7 — actionNames, requiredPermissions, location, align, inline, variant, size |
+  | `record:history`                       | 3 — limit, emptyText, unknownUserText                                        |
+  | `record:reference_rail`                | 1 — hideEmpty                                                                |
+
+  `inputs` describe what an AUTHOR writes, which is a subset of what the renderer
+  reads. `entries`, `loading` and resolved `actions` are injected by the host
+  shell off RecordContext; declaring them would invite a model to hand-write the
+  data the page is supposed to fetch. `aria` is omitted for the reason it is
+  omitted on `record:details` — an accessibility escape hatch, not a layout
+  choice. `location` takes its enum from the spec's `ACTION_LOCATIONS` rather
+  than restating it, per objectui#3019.
+
+  Six of the seven are now in `PUBLIC_BLOCKS`: configurable and absent from the
+  contract is the state objectui#3006 was about. The contract goes 36 → 42 tags,
+  all resolving.
+
+  `record:chatter` stays out — it is the same renderer as `record:discussion`
+  under a Salesforce-familiar name, kept for schemas already in the wild. Two
+  spellings of one block is ambiguity an authoring model cannot resolve, so the
+  vocabulary carries the spec's name. A test compares the two input lists, so the
+  day they diverge the exclusion stops being justified and fails.
+
+  A companion assertion requires every curated `record:*` tag to declare inputs.
+  A curated tag with none reads as "takes no configuration" when the renderer in
+  fact reads props — the same gap objectui#3006 opened, pointed the other way.
+
+- bac266c: fix(detail): a related list has one sorting semantics instead of two — #3106
+
+  A related list carried two. Its own sort-button row (opt-in via `sortable`) went
+  out as a server `$orderby` over the whole child collection; the `data-table` it
+  embeds took `sortable`'s default of `true` and sorted the rows it was holding —
+  which, in windowed mode, is **one page**.
+
+  Turning `sortable` on put both in the same card, with nothing saying they meant
+  different things. Leaving it off — the default — was worse: the page-local sort
+  was then the _only_ one the user could reach, and it looked exactly like the
+  list being sorted.
+
+  The table's column headers now drive this list's sort in both modes, so there is
+  one order behind them:
+
+  - **Windowed**: the header sort becomes the server `$orderby` and resets to page
+    one, the same path the buttons took.
+  - **Client mode**: this list keeps sorting in memory, where its key is the label
+    resolved through its own id → name map (#3096) — a key the embedded table
+    cannot see, so its sort was the worse of the two even when both were possible.
+
+  The button row survives only where there are no headers to click: a `list`
+  (`data-list`) related list, or a caller-supplied `schema` whose contents we
+  cannot assume. `sortable`'s documentation now says that is what it controls.
+
+  Relational columns keep #3096's rule, moved to the header: no sort affordance
+  while the sort is a server `$orderby` (the key would be the stored foreign-key
+  id while the cell shows a name), live in client mode where the key is the label.
+
+### Patch Changes
+
+- fc0272a: fix(actions): apply the ADR-0066 D4 capability gate on every action surface (framework#3923)
+
+  An action declaring `requiredPermissions` is supposed to be one declaration with
+  two enforcement surfaces: 403 on the server, hidden button in the UI. The UI half
+  only ever ran inside `ActionEngine.getActionsForLocation` — and the surfaces
+  `record_header`, `record_more`, `list_item` and `list_toolbar` actually render on
+  do not go through the engine. They filter their own action lists. So a button
+  declaring a capability nobody holds rendered, live and clickable, on the record
+  header, in every grid row menu, and on the list toolbar. For a `type: 'api'`
+  action pointed at a self-authored endpoint, nothing else was checking either: the
+  platform's action route (which is where the 403 comes from) never sees that
+  request.
+
+  `page:header`, `action:bar` (business _and_ `systemActions`) and the grid's
+  `RowActionMenu` now apply the same gate, via a shared `useCapabilityGate()` so
+  the surfaces cannot drift apart. The rule is the engine's, unchanged: hide unless
+  the caller holds **all** declared capabilities; an empty held set is "holds
+  nothing" and gates; **unknown** — no action runtime, no resolved capabilities —
+  fails OPEN, because the server is the authority and hiding a permitted user's
+  button on missing client data is the worse failure.
+
+  The record surface was also feeding the gate nothing to work with.
+  `RecordDetailView` mounts its own `<ActionProvider>`, which shadows the shell's
+  for every action on that page, and seeded it with identity only — no
+  `systemPermissions`. Since unknown fails open, that alone un-gated every
+  `record_header` / `record_more` / `record_section` action on the one page those
+  locations exist on. It now forwards the caller's resolved capabilities (and only
+  once they have actually resolved, so a standalone embed without a
+  `PermissionProvider` keeps failing open rather than hiding everything).
+
+  `useRecordEditable`'s record-level explain probe went out on a bare
+  `fetch(..., { credentials: 'include' })`. A bearer-token session carries its
+  credential in the `Authorization` header, not a cookie, so the probe came back
+  401 on a perfectly valid admin session and the verdict silently failed open —
+  the hook was inert in exactly the deployments it was written for. It now rides
+  the host's authenticated fetch (`SchemaRendererProvider`'s `apiFetch`), falling
+  back to the global one for standalone embeds.
+
+- c785740: fix(detail): record Attachments become their own tab (with count badge) and their copy is translated — objectstack#4358
+
+  Two defects on `enable.files: true` record detail pages:
+
+  1. **Buried placement.** `RecordDetailView` appended `RecordAttachmentsPanel`
+     AFTER the schema-rendered page tree, whose synthesized default embeds
+     `record:discussion` as the last main component — so the panel always
+     landed below an ever-growing feed timeline, undiscoverable without
+     scrolling to the very bottom, with no metadata knob to move it.
+
+     `buildDefaultTabs` now emits a peer **Attachments** tab (a new
+     `record:attachments` node rendered by an app-shell registration wrapping
+     the existing panel via RecordContext) between Related and
+     Activity/History. `PageTabsRenderer` derives the tab's count badge from a
+     `sys_attachment` probe scoped to `(parent_object, parent_id)`, riding the
+     same RelatedCountStore cache/invalidation bus as related-list badges — so
+     uploads and deletes update the badge live. A `hideAttachments` synthesizer
+     option suppresses the tab; RecordDetailView keeps its legacy bottom append
+     only as the fallback for authored pages without the node
+     (`hasExplicitAttachments`).
+
+  2. **Untranslated copy.** The panel's eleven `detail.*` keys (`attachments`,
+     `uploadAttachment`, `loadingAttachments`, `noAttachments`,
+     `downloadAttachment`, `deleteAttachment`, and the five
+     `attachment*Denied/Required` friendly errors) existed only as inline
+     English `defaultValue`s — no locale bundle carried them, so non-English
+     consoles always showed English. All ten locales now define them; the tab
+     label rides the existing well-known-label dictionary (→ 附件 etc.).
+
+- 95b7214: fix(list,grid,detail,tree,core): every column resolver reads one key (#3104 PR2)
+
+  PR1 (#3119) put a canonicalizing fold at ListView's ingestion boundary. This
+  converges the 22 read sites themselves onto `columnIdentity()` from
+  `@object-ui/core`, so a surface that is NOT downstream of that fold resolves
+  the same identity anyway.
+
+  That distinction is the user-visible part. A standalone `object-grid` node —
+  authored directly on a page, with no `list-view` above it — never passed
+  through `normalizeListViewSchema`. Its `getSelectFields` read `c.field` alone
+  while the `ensureId` probe one line above read `f?.name || f?.field`, so a
+  legacy `{ name: 'account' }` column reached `$select` as a literal `undefined`
+  hole: the server never returned the field and every cell in that column came
+  back empty. Same for `ObjectTree`, `RelatedList` and the `record:details` /
+  `record:related_list` renderers.
+
+  Converged:
+
+  | Surface                                  | Was                                            | Now                                 |
+  | ---------------------------------------- | ---------------------------------------------- | ----------------------------------- |
+  | `ListView` ×9 + its 2 request builders   | `name \|\| fieldName \|\| field` vs `f?.field` | `columnIdentity()`                  |
+  | `RelatedList` ×8                         | `accessorKey \|\| field \|\| name`             | `accessorKey \|\| columnIdentity()` |
+  | `ObjectGrid`                             | name-first probe vs `c.field` projection       | `columnIdentity()`                  |
+  | `ObjectTree`                             | `name \|\| fieldName \|\| field \|\| key`      | `columnIdentity() \|\| key`         |
+  | `buildExpandFields`                      | `field ?? name ?? fieldName`                   | `columnIdentity()`                  |
+  | `record-details` / `record-related-list` | `field \|\| name (\|\| key)`                   | `columnIdentity() (\|\| key)`       |
+
+  `accessorKey` keeps its precedence in `RelatedList` — it is TanStack Table's
+  column key, not ObjectStack metadata identity, and only the `field || name`
+  tail was converged. `key` stays a tail fallback in `ObjectTree` and
+  `record-related-list` for the same reason: it is a generic entry key.
+
+  Two incidental fixes that TypeScript surfaced once the resolver stopped
+  returning `any`: ListView's filter-field options and its hide-fields popover
+  both built entries keyed `undefined` for a column with no resolvable identity.
+  Those entries could never match a column; they are now dropped.
+
+  **Inventory re-triage.** PR1 recorded 24 family members. Two were mis-classified
+  and are reclassified here rather than converged — reading what they actually
+  feed shows they are not column reads at all:
+
+  - `ViewPreview.tsx` adapts a ViewItem **form** section to what `object-form`
+    selects by (`field` → `name`) — the #3090 two-layer join.
+  - `SchemaForm.tsx` renders an arbitrary metadata **array** into a popover
+    summary and guesses at a display key; the entries are validations, actions,
+    or whatever the JSON schema declares.
+
+  So the family was 22, and it is now **0**. The ratchet asserts that, asserts
+  each converged surface actually routes through the shared reader (a surface
+  that dropped identity resolution instead of converging it goes red), and pins
+  `accessorKey`'s precedence in `RelatedList`.
+
+- 2baa13f: fix(record): register the record:\* blocks under one key, prefixed once
+
+  Eleven blocks in plugin-detail were registered as
+  `register('record:x', …, { namespace: 'record' })` — an already-prefixed name
+  handed to a registry that prefixes it again. Each landed at
+  `record:record:x`, and the key authors actually resolved, `record:x`, was the
+  un-namespaced _fallback_ rather than the intended registration. The registry
+  carried 23 keys for 12 components.
+
+  Nothing failed, which is why it survived: `getPublicConfigs()` rewrites `type`
+  to the curated tag, so the doubled name never reached the contract, the
+  manifest, or the JSX surface. It was visible only when enumerating the registry
+  directly — which is what objectui#3013's reverse check does.
+
+  Registering the bare name is what makes `namespace` correct, and
+  `skipFallback: true` is what keeps the fallback from claiming that bare name
+  globally. Without it these would take over `details`, `path`, `history`,
+  `alert` … as top-level tags; `alert` is the live case, owned by `ui:`. Every
+  block stays reachable exactly as `record:<name>`, and 23 keys become 12.
+
+  `record:line_items` needed no change — it was the one already registered this
+  way, which is what made objectui#3006's near-miss possible in the first place.
+
+  Two console assertions hold the shape: no key carries a doubled prefix, and no
+  `record:*` block owns the bare spelling of its own name.
+
+- 2d5d594: fix(list,detail): sorting a lookup column no longer orders by an invisible key — #3096
+
+  A relational column (`lookup` / `master_detail` / `user` / `tree`) never holds
+  the string its cell shows: it holds the `$expand`-ed record, or a raw foreign-key
+  id whose label was resolved separately. Every sort path took that raw value as
+  its key, so the column of names came back in an order with no relation to the
+  names — sorting looked broken, with nothing saying the key was something else.
+
+  The two halves are fixed differently, because they can order by different things:
+
+  - **Client-side sorts** (grid column headers, any `data-table`, a non-windowed
+    related list) now key off the label the cell renders, via the new
+    `getSortValue` / `compareSortValues` in `@object-ui/core` — which resolves an
+    expanded record through `getRecordDisplayName` (ADR-0079), so the sort key and
+    the lookup cell agree on which field names a record. This replaces two broken
+    comparators: `a[col] < b[col]` is always false between two objects (the
+    comparator collapsed to a constant and permuted the rows), and
+    `String(a[col])` is `"[object Object]"` (every row compared equal, so the sort
+    silently did nothing).
+  - **Server `$orderby` sorts** cannot be fixed here — the key is the stored id by
+    construction, and `objectstack#4256` settled that no relation join is coming.
+    So those entry points stop offering the illusion: the ListView toolbar sort
+    picker withholds relational fields and explains why (pointing at a formula
+    field as the supported way to sort by a related name), and a windowed related
+    list renders no sort button for them.
+
+  A relational field the view's CURRENT sort already uses stays listed, labelled
+  `(by ID)`, so view metadata authored or saved with such a sort round-trips
+  instead of rendering a blank row and losing the sort on the next edit.
+
+- Updated dependencies [1cf0de7]
+- Updated dependencies [752e18f]
+- Updated dependencies [c785740]
+- Updated dependencies [d61efd1]
+- Updated dependencies [9eb932b]
+- Updated dependencies [3cb9646]
+- Updated dependencies [d21794c]
+- Updated dependencies [b5b97e2]
+- Updated dependencies [2d5d594]
+- Updated dependencies [f8a95e5]
+  - @object-ui/i18n@17.1.0
+
+## 17.0.0
+
+### Minor Changes
+
+- 952b978: fix(detail): the approval band honors the node's `lockRecord` instead of assuming every approval locks (#2902)
+
+  A record detail page treated "a pending approval request exists" as "this
+  record is locked". An approval node declares `lockRecord` (default `true`), and
+  on `lockRecord: false` the server keeps accepting writes for the whole time
+  that node waits — so the console was asserting a lock the backend did not
+  enforce.
+
+  The label was the smaller half of it. The same conflated signal fed `canEdit`,
+  so the record-level inline-edit session was suppressed too: no pencils,
+  `enter()` a no-op. On a single-approver step — a department head or plant
+  manager, exactly the case `lockRecord: false` exists for, where the approver is
+  meant to fill in the missing detail before deciding — the capability was
+  unreachable from the UI. And a flow chaining nodes with different policies drew
+  one identical band for "edit freely" and "the server will reject your save with
+  `RECORD_LOCKED`", so the two states were indistinguishable until Save failed.
+
+  Approval state is now two signals:
+
+  - **`approvalPending`** — an approval is running. Drives the band and the recall
+    button, both meaningful whether or not the record is editable.
+  - **`locked`** — that approval also forbids edits, from the pending node's
+    `lock_record` (framework#3814, read off the same `node_config_json` snapshot
+    the server's record-lock hook reads).
+
+  The band renders two states: amber lock + "Locked for approval", or sky clock +
+  "In approval · editable", each with its own tooltip. Recall moved out of the
+  locked branch — an editable pending approval is just as recallable. Inline
+  editing stays live in the editable state.
+
+  `InlineEditProvider` takes a new optional `approvalPending` prop, defaulting to
+  `locked`, so a host that threads only `locked` renders exactly as before. The
+  record's `approval_status` field remains the fallback for backends with no
+  approvals API; it carries no node granularity, so it still reads as locked — as
+  does a pending request from a backend too old to report the policy.
+
+  New `detail.approvalPendingEditable` / `detail.approvalPendingTooltip` keys are
+  translated in all ten locales.
+
+- f9bbddb: feat: gate detail/form edit & delete on the server's effective operation set (#3546)
+
+  PR-4 (#3391) wired the **list/toolbar** surface (ObjectView Import, ListView /
+  ObjectGrid Export) to the server-resolved effective API operation set
+  (`/me/permissions` `apiOperations`, intersected via
+  `resolveCrudAffordances(obj, effectiveApiOperations?)`). The **detail / form**
+  surfaces still gated edit/delete on the bucket + `userActions` alone. This
+  extends the same intersection to them, so the record page and its forms never
+  offer an operation the server would 405.
+
+  - **core** `isObjectInlineEditable(obj, effectiveApiOperations?)` gains the same
+    optional second argument as `resolveCrudAffordances` — inline-edit is now
+    additionally ANDed with the server allowing `update`.
+  - **app-shell** `RecordDetailView` threads the object's effective operations into
+    the synthesized Edit/Delete header actions and the record-body inline-edit
+    gate (`canEdit`); `RelatedRecordActionsBridge` intersects each **child**
+    object's Create/Edit/Delete handlers with that child's own effective set.
+  - **plugin-detail** `record:details` ANDs its inline-edit affordance with the
+    object's effective `update`.
+  - **plugin-form** `ObjectForm`'s blanket managed-object field lock also engages
+    when the server denies `update` (edit mode) / `create` (create mode).
+
+  Backward-compatible: a missing effective set (unrestricted object, older
+  backend, or no `PermissionProvider`) leaves the resolved affordance untouched —
+  the bucket/`userActions` decision wins, exactly as today. Layers on top of the
+  existing per-object `check('edit')` / `check('delete')` permission gates
+  (intersection, never union).
+
+### Patch Changes
+
+- 7b21891: fix(action): honor the spec `disabled` predicate on every action-rendering surface (#1885 follow-through)
+
+  The spec Action field is `disabled` (boolean | CEL — disabled when TRUE); the
+  schema has no `enabled` key. #1885 wired it in `action:button` only. Browser
+  dogfooding against the showcase found FIVE more surfaces where a spec-authored
+  `disabled` silently did nothing:
+
+  - **components** — the `action:group` leaves (inline + dropdown), `action:icon`
+    and `action:menu` still read the legacy non-spec `enabled`. They now consume
+    `disabled` as the primary control (evaluated in the same scope as `visible`),
+    with `enabled` kept as a deprecated fallback.
+  - **app-shell** — `DeclaredActionsBar` (server-declared action bar) read
+    neither; it gains `disabled` (no legacy fallback: declared actions are
+    spec-shaped and never carried `enabled`).
+  - **plugin-detail** — `record:quick_actions` HAD a `disabled` implementation,
+    but its `typeof === 'string'` split dropped the `{dialect:'cel', source}`
+    envelope the server compiles authored CEL into (#2661 routes envelopes to the
+    canonical formula engine), so the predicate never fired on real metadata. It
+    now feeds `toPredicateInput`'s result to `useCondition` whole, like every
+    other surface.
+
+  Pinned by new `DropdownActionItem` tests (disabled-when-TRUE, false-stays-
+  clickable, disabled-wins-over-enabled, boolean literal) and browser-verified
+  end-to-end against the showcase `showcase_archive_task` specimen: greyed on an
+  in-progress task, clickable on a done one (with `visible` hiding Mark Done on
+  the same screen — the hide-vs-grey contrast).
+
+- faad45e: fix(fields): render `image` fields consistently and add click-to-zoom (#2836)
+
+  An `image` field rendered differently — and wrongly — on three surfaces:
+
+  - **Edit form showed broken thumbnails.** A record read back its `image` value
+    as a bare `sys_file` id (the reference form), but `readFileValue` returned an
+    id with no URL — the comment assumed the read path expands it, which the
+    edit-form data path does not. The result was `<img src="">`. `file-value` now
+    derives the stable download URL (`/api/v1/storage/files/:id`, which
+    302-redirects to a signed URL and works directly as `<img src>`) for a bare
+    id or an id-only object, so every widget and cell renderer resolves one.
+  - **Inline edit leaked the raw storage URL.** `InlineFieldInput` had no branch
+    for file-backed types and fell through to a plain text input showing
+    `/api/v1/storage/files/…`. It now renders the same upload widgets the form
+    uses (`image`/`avatar`/`signature`/`file`/`video`/`audio`).
+  - **Hard-coded English.** `ImageField`'s upload/crop/remove/alt strings now go
+    through `t('fields.image.*')` (en + zh added).
+
+  Also adds an `ImageLightbox` — click a read-only thumbnail (detail or list cell)
+  to open a full-screen preview; multiple images get prev/next navigation, a
+  position counter and arrow-key support, a single image just the image. In a
+  grid cell the click is `stopPropagation`-guarded so enlarging doesn't also open
+  the row.
+
+- 7d46648: fix(hooks): stop calling translation hooks inside try/catch (objectui#2879)
+
+  Eleven call sites wrapped a React hook in `try`/`catch` to make it
+  "provider-safe". `useObjectTranslation` and `useObjectLabel` already are — they
+  read context optionally and fall back to react-i18next's global instance, and
+  never throw. The `catch` bought nothing and cost correctness: a throw _after_
+  the hook ran desyncs hook order on the next render, because React matches hooks
+  positionally. objectui#2595/#2596 fixed exactly this in `@object-ui/i18n`'s
+  `createSafeTranslation`; nine plugin-local re-implementations kept their own
+  copy of the bug, and two more (`ObjectTimeline`, `ObjectView`) were found by the
+  new lint rule below — `ObjectView` had even suppressed
+  `react-hooks/rules-of-hooks` inline to keep it.
+
+  - Six exact re-implementations now delegate to `createSafeTranslation`:
+    `plugin-detail`, `plugin-timeline`, `plugin-list`, `plugin-calendar`,
+    `plugin-grid`'s `ObjectGrid`, `plugin-designer`.
+  - `components`' `data-table` also delegates; `createSafeTranslation` now
+    returns `language` alongside `t` so consumers that localize dates don't need
+    a second hook call. Purely additive.
+  - `plugin-gantt` and `plugin-grid`'s `ImportWizard` keep their local hooks —
+    they fall back _per key_, which a single-probe factory cannot express and
+    which their comments justify (a host dictionary that covers common keys but
+    lags on newer ones). Only the `try`/`catch` is removed.
+  - `ObjectTimeline` and `ObjectView` call the hook directly and probe the
+    returned value, mirroring `useSafeFieldLabel`.
+
+  Adds `object-ui/no-try-catch-around-hook` (error) so a twelfth copy fails CI.
+  It only matches `use*` names, accepts member calls solely on `React` (so
+  `vi.useRealTimers()` is not a hook), and resets its try-depth inside nested
+  functions (so `renderHook(() => useThing())` inside a `try` is fine) — both
+  false positives were real code in this repo and are pinned in the rule's tests.
+
+  `eslint-rules/**/*.test.js` matched no vitest project glob, so the local
+  plugin's specs had never run in CI. They are now included; all three pass.
+
+  `ObjectTimeline`'s test mock of `@object-ui/react` omitted `useObjectLabel` —
+  the removed `try`/`catch` had been silently absorbing that gap. The mock is now
+  complete.
+
+- 53642d4: fix(core,fields): a string `$orderby` is a clause, not a character array — and localize the sharing-rule widgets (objectstack#3821)
+
+  **The recipient picker listed nothing, ever.** `QueryParams['$orderby']` was
+  typed as `Record | string[] | SortObject[]`, so `queryParamsToRecord` sent any
+  non-array value through `Object.entries`. Handed the clause string `'name asc'`
+  — which callers do build by hand — it walked the string index by index and
+  emitted `$orderby=0 n,1 a,2 m,3 e,4 ,5 a,6 s,7 c`. The server sorted by columns
+  that don't exist and every row was filtered out, so
+  `sys_sharing_rule.recipient_id` rendered "No matches" for every recipient type
+  and no sharing rule could be created from the Console. `ObjectGrid` builds the
+  same shape from a schema-level `sort` in three places, so grids with a string
+  sort silently showed an empty table.
+
+  A string `$orderby` is now passed through verbatim (the server's OData
+  normalizer has always parsed `'name asc'`), and the type admits `string`.
+  `RecipientPickerField` additionally switched to the structured
+  `{ name: 'asc' }` form so it can't regress this way against any data source.
+
+  **The three sharing-rule authoring widgets never had translations.**
+  `ObjectRefField`, `RecipientPickerField` and `FilterConditionField` hardcoded
+  their English copy — a Chinese Console showed "Select an object", "Select a
+  user", "Search…", "No matches", "Edit as JSON". They now go through
+  `useFieldTranslation` like every other widget, with keys added under `fields.*`
+  in all ten locales.
+
+  The recipient placeholder was the interesting one: it read
+  `` `Select a ${recipientType.replace(/_/g,' ')}` ``, interpolating the enum
+  value into an English sentence — a shape no locale can translate. It is now a
+  per-type key (`fields.recipient.selectUser`, `…selectBusinessUnit`, …), so
+  "选择业务单元" and "Select a business unit" no longer have to share a structure.
+
+  **Editing a rule silently dropped its recipient.** The picker resets the stored
+  id when `recipient_type` changes, because an id valid for a user is meaningless
+  for a team. It treated the edit form's `'' → 'user'` hydration as such a change:
+  opening any saved rule blanked the recipient, and saving persisted the blank.
+  Only a non-empty predecessor now counts as a type switch.
+
+  **Building a filter submitted the surrounding form.** None of `FilterBuilder`'s
+  controls declared `type="button"`, and a bare `<button>` inside a `<form>`
+  defaults to `type="submit"`. Adding, removing or clearing a condition therefore
+  submitted the sharing-rule dialog — firing validation mid-edit, and on an
+  already-valid form saving the record before the admin was done.
+
+  **A rejected write showed the user raw server diagnostics.** The form rendered
+  `error.message` verbatim, so a sharing / RLS denial reached the dialog and the
+  toast as `FORBIDDEN: insufficient privileges to update showcase_private_note
+pi-TgoJ4_DM55Fqz` — untranslated, and leaking the object's machine name and the
+  record id to whoever hit it. Permission failures now render localized copy
+  (`form.noPermissionToSave`, added in all ten locales), with the server text kept
+  on the console for debugging; other failures still show the server's message,
+  which is the useful part, and fall back to `form.submitFailed` when there is
+  none — replacing the previously hardcoded English "An error occurred during
+  submission".
+
+  **The detail header offered "Edit" on records the user may only read.** Object
+  permissions can't express "this one record is read-only" — a read-only sharing
+  grant sits inside an object the user may otherwise edit — so the header showed
+  the primary Edit CTA, opened the form, and let the user retype a field before
+  the server rejected the save. `DetailView` now gates Edit / Delete on the
+  object-level check AND on the explain engine's record-grained verdict
+  (`POST /api/v1/security/explain` with a `recordId`, ADR-0090 D6 / ADR-0095 C2 —
+  the same pipeline the enforcement middleware runs, so button and server cannot
+  disagree). Explaining oneself needs no special permission. The probe is one
+  cached request per record, skipped entirely when the object-level check already
+  says no, and **fails open** on every uncertainty — an unanswered hint must never
+  be the reason a permitted user cannot act; the server stays the authority
+  (ADR-0057 D10).
+
+  **A long option rendered straight past the combobox border.** `Combobox`'s
+  trigger pinned itself to the component's `w-[200px]` default while the fields
+  around it ran the full form column, and the selected label was a bare text child
+  of a flex button — flex items need `truncate` AND `min-w-0` to clip, and it had
+  neither. So "成员 (showcase_project_membership)" in the object picker overflowed
+  the control and collided with the field beside it. The label now truncates, the
+  trigger can shrink, the dropdown matches the trigger's width instead of a
+  hardcoded 200px (a widened combobox used to clip its own options), and the two
+  sharing-rule pickers ask for `w-full` so they line up with every other input.
+
+  Hardens `evaluatePermission` while there: a role config carrying only
+  `fieldPermissions` (no `actions`) made `check()` throw a TypeError that
+  propagated out of the render. A permission check must not be able to crash a
+  view.
+
+  Browser-verified against the framework showcase Console in Chinese: object /
+  criteria / recipient copy is fully localized, the recipient dropdown lists real
+  users, business units and positions, a saved rule reopens with its recipient and
+  criteria intact, editing the filter no longer submits, and a rule created
+  end-to-end stores a real record id rather than free text. The criteria authored
+  in the builder is honored by the evaluator: `{"pinned":true}` on an owner-private
+  object granted the recipient exactly the matching records and nothing else.
+
+- Updated dependencies [7b21891]
+- Updated dependencies [0b3be01]
+- Updated dependencies [3c4d935]
+- Updated dependencies [4b1ed7d]
+- Updated dependencies [4b60d2d]
+- Updated dependencies [952b978]
+- Updated dependencies [de5e40c]
+- Updated dependencies [1a03af6]
+- Updated dependencies [3e886eb]
+- Updated dependencies [cfc675e]
+- Updated dependencies [20df08c]
+- Updated dependencies [1767124]
+- Updated dependencies [8ecf5a6]
+- Updated dependencies [af705b9]
+- Updated dependencies [0502a7c]
+- Updated dependencies [7b35e4b]
+- Updated dependencies [8fb1295]
+- Updated dependencies [e16ed2d]
+- Updated dependencies [c6fd752]
+- Updated dependencies [f9bbddb]
+- Updated dependencies [dfd3705]
+- Updated dependencies [c77108c]
+- Updated dependencies [2735de6]
+- Updated dependencies [697cda4]
+- Updated dependencies [c19ac11]
+- Updated dependencies [6dee2cb]
+- Updated dependencies [e05f052]
+- Updated dependencies [0502a7c]
+- Updated dependencies [faad45e]
+- Updated dependencies [09c6a17]
+- Updated dependencies [c7cff19]
+- Updated dependencies [ba73a02]
+- Updated dependencies [cd09a7b]
+- Updated dependencies [f1abf0e]
+- Updated dependencies [f05b84e]
+- Updated dependencies [9b4b952]
+- Updated dependencies [341bfb5]
+- Updated dependencies [2f947e4]
+- Updated dependencies [7d46648]
+- Updated dependencies [9b53d72]
+- Updated dependencies [bb4aa25]
+- Updated dependencies [75f1cdf]
+- Updated dependencies [662bdf9]
+- Updated dependencies [059a052]
+- Updated dependencies [53642d4]
+- Updated dependencies [8aae006]
+- Updated dependencies [c6cfdf1]
+- Updated dependencies [d147a13]
+- Updated dependencies [c6aaed8]
+- Updated dependencies [263f885]
+- Updated dependencies [dc334da]
+  - @object-ui/components@17.0.0
+  - @object-ui/i18n@17.0.0
+  - @object-ui/fields@17.0.0
+  - @object-ui/react@17.0.0
+  - @object-ui/types@17.0.0
+  - @object-ui/core@17.0.0
+  - @object-ui/permissions@17.0.0
+
 ## 16.1.0
 
 ### Minor Changes