@object-ui/layout 17.2.0 → 17.5.0

package/CHANGELOG.md

@@ -1,5 +1,626 @@
 # @object-ui/layout
 
+## 17.5.0
+
+### Minor Changes
+
+- bb68488: Stop declaring 14 symbols under names `@objectstack/spec` owns at `17.0.0-rc.6`
+  (objectui#4167, objectstack#4115).
+
+  The rc.6 bump published nine names this repo already declared locally, on top of
+  four that predate it — `check:spec-symbols` reported all thirteen at once, and a
+  fourteenth (`GlobalFilterSchema`) appeared during the bump itself. Each was
+  triaged on its own rather than blanket-renamed, because the right answer differs
+  per symbol: five bind to the spec, three are renamed because the spec's
+  same-named export means something else, five arrive by derivation, and one is a
+  declared dialect with a written reason.
+
+  **Breaking for importers of `@object-ui/react`, `@object-ui/app-shell` and
+  `@object-ui/types`** — three 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                                                                                                          |
+  | :-------------------- | :----------------- | :----------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |
+  | `react` / `app-shell` | `MetadataState`    | `MetadataCacheState`           | a metadata item's LIFECYCLE state — `'draft' \| 'active' \| 'deprecated' \| 'archived'` (`MetadataStateSchema`, `@objectstack/spec/system`)            |
+  | `react` / `app-shell` | `resolveI18nLabel` | `resolveKeyedI18nLabel`        | a resolver for the INLINE per-locale map (`{ en: 'Owner', 'zh-CN': '负责人' }`) against a BCP-47 locale                                                |
+  | `types`               | `DateRangePreset`  | `FilterBuilderDateRangePreset` | the thirteen HISTORICAL dashboard filter-bar presets; this one is the filter-builder set, which adds eight FUTURE windows the dashboard schema rejects |
+
+  `resolveI18nLabel` is the one where the collision had already started costing
+  something. rc.6 widened `I18nLabel` from `string` to
+  `string | Record< string, string >`, so the same authored value now reaches
+  either resolver — and each answers wrongly, silently, for the other's input: the
+  keyed one returns `undefined` for `{ en: 'Owner' }` (no `key`, no
+  `defaultValue`), and the spec's reads `key` / `defaultValue` / `params` as locale
+  tags. The rc.6 bump PR met this and aliased the spec's import as
+  `resolveInlineI18nLabel` in five files, with hand-written comments at two of
+  them. That is a review convention, which is what objectstack#4115 exists to
+  replace with a rule — so `Keyed` is now the counterpart of that `Inline`, and the
+  name says which vocabulary it resolves at every call site.
+
+  **Eleven keep their names and are now imported or derived from the spec** instead
+  of re-declared: `DATE_RANGE_PRESETS`, `NavigationMode`, `AddressValue`,
+  `BreakpointColumnMap`, `BreakpointOrderMap`, `KanbanConfig`, `CalendarConfig`,
+  `GanttConfig`, plus the three renamed above at their new names.
+
+  **Four of the copies were losing information, not just duplicating it.**
+
+  - **`GanttConfig` declared six keys and called itself canonical; rc.6's
+    `GanttConfigSchema` declares seventeen.** The eleven it never mentioned —
+    `parentField`, `typeField`, `baselineStartField`, `baselineEndField`,
+    `groupByField`, `resourceView`, `assigneeField`, `effortField`, `capacity`,
+    `quickFilters`, `autoZoomToFilter` — are all read by
+    `plugin-gantt/src/ObjectGantt.tsx`, through a local `GanttConfigEx`
+    intersection that existed only because this type did not carry them. It now
+    derives from the spec, with `timeSegments` (shift segmentation) as the one
+    genuinely local extension; the schema is `$loose` upstream, so that key is
+    legal metadata rather than a second dialect.
+  - **`GanttConfig.tooltipFields` carried the comment "not part of the upstream
+    GanttConfigSchema".** It is, as of rc.6, so the key now arrives from the spec.
+  - **`AddressValue` declared five of the spec's seven parts** — `countryCode` and
+    `formatted` were missing, under a comment already claiming to be "the part
+    names of `AddressSchema`". The widget still renders five inputs; binding the
+    type stops it from asserting the platform cannot store the other two, and makes
+    the `{ ...address }` write-through say so.
+  - **`DATE_RANGE_PRESETS` was `Object.keys(PRESET_RANGES)`,** a third copy of a
+    vocabulary the spec extracted in objectstack#4614 precisely to collapse — its
+    own doc comment names this module as one of the three. It is now the spec's
+    array by reference, and the local date-macro bounds table is pinned complete
+    against it with `satisfies`, so a preset the schema gains without bounds here
+    is a compile error rather than a filter that validates clean and then selects
+    nothing.
+
+  `NavigationMode` was one hop from the spec already (`NavigationConfig['mode']`);
+  it is bound directly, with a both-directions type pin that it stays the same type
+  as the config's own `mode`. `KanbanConfig` / `CalendarConfig` /
+  `BreakpointColumnMap` / `BreakpointOrderMap` were exact hand copies of `$strict`
+  schemas and are now re-exports — "still exact" is the argument for binding them,
+  since a copy with nothing to protect can only drift.
+
+  `GlobalFilterSchema` is the one ALLOW entry. It is the same spread-composition
+  dialect as `SelectOptionSchema` next to it, and it collided only because rc.6's
+  new refinement forced `.extend()` to be respelled as a `.shape` spread — which
+  moved a derivation the guard could see into an object literal it deliberately
+  does not descend into. The dialect is unchanged and its three divergences are
+  pinned; which side moves on the refinement itself is objectui#4165.
+
+  `@objectstack/spec` moves from `devDependencies` to `dependencies` in
+  `@object-ui/layout`: its public type surface now references the spec.
+
+### Patch Changes
+
+- f650253: `BaseSchema.ariaLabel` declares the keyed i18n vocabulary the renderer actually
+  resolves, `.disabled` accepts the predicate string it actually evaluates, and the
+  keyed shape finally has a name (objectui#4581)
+
+  Three slots on one base type had drifted from what the renderer does with them.
+  PR #4593 fixed `visible` and measured the rest; these are the rest.
+
+  `ariaLabel` was `string`, but `SchemaRenderer.tsx:111` resolves it with
+  `resolveKeyedI18nLabel`, whose input is the KEYED form
+  `{ key, defaultValue?, params? }` — a reference into a translation bundle. It is
+  now `string | KeyedI18nLabel`, and `KeyedI18nLabel` is a new exported type in
+  `@object-ui/types` rather than a fourth inline copy of one object literal: the
+  three that existed (`@object-ui/react`'s resolver, `@object-ui/layout`'s
+  `resolveLabel`, `@object-ui/app-shell`'s `t`-taking twin) were verified identical
+  in their object half first, and two of them now import the name.
+
+  The vocabulary matters more than the widening. `#4581` originally asked for
+  `string | I18nLabel`, and that spelling was withdrawn as measured-wrong: the
+  spec's `I18nLabel` is the INLINE LOCALE MAP (`string | Record<string, string>`),
+  a different vocabulary resolved against a BCP-47 locale by a different function
+  of a confusingly similar name. Under it the shipped keyed fixture type-checked
+  only vacuously — as a locale map whose "locales" are named `key` and
+  `defaultValue` — the same label carrying `params` was rejected outright, and a
+  genuine `{ en: 'Owner' }` compiled while rendering an EMPTY `aria-label`. Naming
+  the keyed shape is the declaration half of the fix objectui#4167 started on the
+  naming side; `@object-ui/app-shell`'s copy keeps its inline spelling for now
+  because an open PR has a pending change to that file, and the comment there says
+  so.
+
+  `disabled` was `boolean` on a key the renderer never reads as one:
+  `SchemaRenderer.tsx:466` evaluates it through the same `evaluateCondition` as
+  `visible`, and a `disabledOn?: string` sibling exists for the same reason. It is
+  now `boolean | string`. The asymmetry with `visible` was accidental rather than
+  deliberate.
+
+  Both are widenings on authored-input-dominant properties: authors gain a
+  spelling, nothing that type-checked before stops doing so, and readers already
+  coped with `any` through `BaseSchema`'s index signature. Three test fixtures that
+  had been casting past these declarations with `as unknown as BaseSchema` state
+  their values directly now, and the declared unions are pinned invariantly so
+  neither a missing widening nor an overshoot to `any` can pass unnoticed.
+
+  Declaring the vocabulary honestly also surfaced a real one: the `toggle`
+  renderer writes `aria-label` itself instead of going through SchemaRenderer's
+  resolver, and it forwarded the raw value. Invoked directly it emitted
+  `aria-label="[object Object]"` for a keyed label — announced verbatim by a
+  screen reader. It resolves now. Through `SchemaRenderer` the bug was invisible,
+  because SchemaRenderer injects its own resolved `aria-label` afterwards; a
+  downstream type-check sweep found it, not a test.
+
+  `BaseSchema.label` and `.description` are deliberately unchanged and pinned that
+  way. They receive the spec's inline `I18nLabel` from the view bridges, which is a
+  real defect, but resolving it belongs at the spec-to-schema boundary rather than
+  in this declaration — and that work is still blocked on a design question about
+  where the display locale enters, so it is not in this release.
+
+- bb68488: An inline per-locale label now renders its locale's string at the thirteen read sites the `@objectstack/spec` 17.0.0-rc.6 bump exposed
+
+  rc.6 widened `I18nLabel` from `string` to `string | Record<string, string>`, so an author may write `label: { en: 'Owner', 'zh-CN': '负责人' }` anywhere the spec accepts a display label. PR #4169 repaired eight such sites; these thirteen were invisible to it because the five packages involved build through vite/rolldown, so `turbo run build` never type-checks their sources — only `turbo run type-check` does. All thirteen are now resolved through a shared resolver against a real locale, and `turbo run type-check` is 78/78 with zero errors.
+
+  | package                       | what an author can now write and see                                                    |
+  | ----------------------------- | --------------------------------------------------------------------------------------- |
+  | `@object-ui/layout`           | `NavigationArea.label` — the sidebar area switcher's button and its tooltip             |
+  | `@object-ui/plugin-list`      | `ViewTab.label` — the inline pill row, and the mobile dropdown's trigger and menu items |
+  | `@object-ui/plugin-dashboard` | `DashboardWidget.title` — the widget card heading and its `title` attribute             |
+  | `@object-ui/plugin-designer`  | `DashboardWidget.title` — the widget card and the preview tile                          |
+  | `@object-ui/app-shell`        | `ActionParam.label` **and** each `ActionParam.options[].label`                          |
+
+  **Patch, not minor, in every case: no public surface changes meaning.** Every entry above is a read site that previously could only be reached with a value the type system rejected, so no caller's working code changes behaviour. `@object-ui/app-shell` is the only package with an exported-type change and it is purely additive on the authoring side — `RawActionParam.label` and `RawActionParam.options[].label` widen to `I18nLabel` (they accept strictly more), `ResolveActionParamsContext` gains an optional `locale`, and the new `RawActionParamOption` names the authoring shape that was previously spelled with the resolved one. What `resolveActionParams` **emits** is unchanged: `ActionParamDef.label` and its options' labels are still plain `string`s.
+
+  Two consequences worth knowing:
+
+  - **The dashboard designer's title input is deliberately read-only for a map-valued title.** Resolving a per-locale map into a single-line input and writing `e.target.value` back would collapse every other locale on the first keystroke, so the write is guarded and an inline map survives an unrelated edit-and-save round trip untouched — the same conservative branch #4169 took for `DashboardWidgetInspector`. What Studio should actually offer for authoring a per-locale label is objectui#4163 part 2, which is unclaimed and pending design.
+  - **`@object-ui/layout` resolves at the spec's `en` default, not the viewer's language.** That package carries no i18n dependency by design (its whole i18n story is injection), and `AppSchemaRendererProps` exposes no locale to thread. The choice and what would change it are documented at the call site.
+
+- Updated dependencies [ceccdcf]
+- Updated dependencies [d6e5124]
+- Updated dependencies [debad27]
+- Updated dependencies [dc2aa3e]
+- Updated dependencies [ee66e2e]
+- Updated dependencies [ee26e65]
+- Updated dependencies [5900ac5]
+- Updated dependencies [f650253]
+- Updated dependencies [3d9769a]
+- Updated dependencies [8f85f8b]
+- Updated dependencies [d0c3b26]
+- Updated dependencies [3fc2971]
+- Updated dependencies [aca27fa]
+- Updated dependencies [dde7283]
+- Updated dependencies [4dadf0d]
+- Updated dependencies [ae10a01]
+- Updated dependencies [92876f0]
+- Updated dependencies [f279deb]
+- Updated dependencies [4b70d28]
+- Updated dependencies [eb7f586]
+- Updated dependencies [e901131]
+- Updated dependencies [d9d3463]
+- Updated dependencies [2a40f69]
+- Updated dependencies [bec3e14]
+- Updated dependencies [613b167]
+- Updated dependencies [b4d3c22]
+- Updated dependencies [1f9b905]
+- Updated dependencies [cb13400]
+- Updated dependencies [bc64bfe]
+- Updated dependencies [abb0f81]
+- Updated dependencies [38ab505]
+- Updated dependencies [3e19fe7]
+- Updated dependencies [b953a97]
+- Updated dependencies [d7f3e30]
+- Updated dependencies [7e4f0e5]
+- Updated dependencies [a84385b]
+- Updated dependencies [45e1949]
+- Updated dependencies [92250d6]
+- Updated dependencies [c1d939f]
+- Updated dependencies [49ae9f4]
+- Updated dependencies [a3ae404]
+- Updated dependencies [bfdf3d4]
+- Updated dependencies [bb68488]
+- Updated dependencies [b1e42d0]
+- Updated dependencies [2459a3e]
+- Updated dependencies [d6aa172]
+- Updated dependencies [fe52a04]
+- Updated dependencies [3f5f87c]
+- Updated dependencies [f5e1143]
+- Updated dependencies [f148a64]
+- Updated dependencies [bb68488]
+- Updated dependencies [9461dd3]
+- Updated dependencies [47f551b]
+- Updated dependencies [ab04728]
+- Updated dependencies [5bf09fd]
+  - @object-ui/react@17.5.0
+  - @object-ui/components@17.5.0
+  - @object-ui/core@17.5.0
+  - @object-ui/types@17.5.0
+
+## 17.4.0
+
+### Patch Changes
+
+- 6bd6a4d: `registerLayout()` 的 `inputs` 声明面与渲染器实现对齐 —— 校验器不再对正确写法报假诊断
+
+  `inputs` 是**作者面**:`sdui-parser/src/validate.ts` 拿一个节点的顶层属性逐个比对
+  `comp.inputs`,不在其中的报 `unknown-prop`,类型不符的报 `type-mismatch`;设计器面板、
+  `sdui.manifest.json`、生成的 JSX 类型也都由它派生。所以声明面写错的代价不是"文档不全",
+  而是**校验器对着能正常渲染的 schema 说谎**(objectui#3972,与 objectui#3900 同族、换到属性面)。
+
+  两处修正,都是按渲染器**实际读点**审计出来的:
+
+  - **`page-header` 补声明 `icon` 与 `actions`。** 两个键三面齐全:渲染器真读
+    (`PageHeader.tsx:117` 取参 `:224-226` 渲染 icon;`:119` 取参 `:192-196` 把 actions
+    委派给 `record:quick_actions`)、`@objectstack/spec/ui` 的 `PageHeaderProps` 声明、
+    `ManifestInputType` 表达得了(`string` / `array`)。`content/docs/layout/page-header.mdx`
+    的 Component Props 段落也把两者写成公开契约,而该文档页**唯一**的 live demo
+    (`layout-page-header/pageheader-with-actions`)就写着 `"icon": "users"` —— 于是仓内
+    自己的文档示例每次过 manifest 门都收到一条 `unknown-prop: page-header has no prop "icon"`。
+    `actions` 的类型与 canonical 的 `page:header` 逐字一致(`type: 'array'`),一个概念一个键
+    一种类型。
+  - **`navigation-renderer` 的 `items` 由 `type: 'object'` 改为 `'array'`。**
+    `NavigationRendererProps.items` 是 `NavigationItem[]`(`NavigationRenderer.tsx:108`),
+    而 `checkType` 对 `'object'` 判 `typeof value === 'object' && !Array.isArray(value)`、
+    对 `'array'` 判 `Array.isArray`(`validate.ts:124-129`)—— 两者互斥。所以旧声明对这个
+    渲染器**唯一能渲染的形状**报 `type-mismatch ... expected an object`,而对真会让它崩的
+    对象形状一言不发。这不是 objectui#3832 的表达力问题:`ManifestInputType` 本来就有
+    `'array'`,只是声明写错了一个表达得了的类型。
+
+  **刻意不声明**的键同样被钉住,因为"照抄 spec 的 shape"是这条修复最容易滑进去的反向缺陷:
+  `breadcrumb`(spec 有、这个渲染器零读点 —— 声明它就是 objectui#3829 的缺陷方向)、
+  `showBack` / `action` / `description`(渲染器读、spec 无此键 —— 声明任一个就是在开第二套
+  方言,正是 objectui#3226 收窄要防的事)、`aria`(每个 block 都因同一理由省略的可访问性逃逸口)。
+
+  渲染输出逐字节不变:渲染路径从不读 `inputs`。变化只在校验/设计器/清单这一侧,且两个方向
+  都钉了 —— 正确写法放行的同时,`description` 这类刻意不声明的键仍报 `unknown-prop`、
+  `items` 写成对象仍报 `type-mismatch`(诊断没有被弄哑)。
+
+- 876e3f7: `@object-ui/layout` no longer tells bundlers it has no side effects while registering components at load time (objectui#3899)
+
+  The published manifest declared `"sideEffects": false` — a promise that no module
+  in the package does anything on evaluation, so any module whose exports go unused
+  may be dropped whole. But `src/index.ts` ends with a bare
+  `try { registerLayout(); } catch {}`, and that call is the only thing that puts
+  `page-header`, `page:card`, `app-shell`, `responsive-grid`,
+  `navigation-renderer` and `app-schema-renderer` into the `ComponentRegistry`.
+
+  Both statements cannot be true, and a bundler that believes the manifest is
+  right to delete the registration. Measured with the repo's own bundler by
+  building `import '@object-ui/layout';` — the side-effect-only import, i.e. the
+  documented "import it to register" pattern:
+
+  - `sideEffects: false` — the bundle is **0 bytes**. Zero registrations, exit
+    code 0, no warning.
+  - after this change — the bundle keeps all six `ComponentRegistry.register`
+    calls.
+
+  A dropped registration does not fail where it happened. It surfaces later as a
+  red `Unknown component type` panel (OBJUI-001) on a fully green build, with
+  nothing in the build log to connect the two. Nobody had been bitten yet only
+  because every consumer today ALSO imports a named export, which forces the module
+  to be evaluated regardless — coincidence, not design. objectui#3787 met the
+  hazard and routed around it by calling `registerLayout()` explicitly.
+
+  `sideEffects` is now the narrowest honest answer: an array naming the modules
+  that actually register, rather than `true`, which would be honest but would hand
+  the whole package to every bundler as unshakeable.
+
+  ```json
+  "sideEffects": ["./dist/index.js", "./dist/index.umd.cjs", "./src/index.ts"]
+  ```
+
+  All three are load-bearing, and the set is derived from the manifest rather than
+  guessed:
+
+  - `./dist/index.js` and `./dist/index.umd.cjs` are every JS file the manifest's
+    own entry fields point at (`module` / `main` / `exports` import+require). The
+    library build inlines everything into those two files, so there is no third
+    chunk to name.
+  - `./src/index.ts` is not published (`files` ships `dist` only) but is bundled
+    for real: `apps/console` and `examples/console-starter` both alias the
+    specifier straight at `packages/layout/src`, and a bundler reads this same
+    manifest for those files. With only the published paths declared, the console's
+    alias shape still produced a 0-byte bundle.
+
+  What deliberately did NOT change: the load-time `registerLayout()` itself.
+  Replacing it with an explicit registration API is the opposite direction — it
+  eliminates the side effect instead of declaring it, and it is breaking for any
+  consumer relying on automatic registration. objectui#3899 leaves that call to the
+  maintainer, and the two steps do not conflict: once the manifest tells the truth,
+  the migration to explicit registration can happen whenever it is wanted.
+
+  A new pin (`packages/layout/src/__tests__/side-effects-manifest.test.ts`) runs a
+  real bundler build per entry form and asserts the registrations survive a
+  side-effect-only import, with a `sideEffects: false` control per form asserting
+  they are dropped — so the pin cannot pass because the bundler stopped shaking
+  anything. The required set is derived from the manifest's own entry fields, so a
+  renamed build output or a new `exports` subpath fails as a missing declaration
+  instead of drifting silently.
+
+- f3b2874: `navigation-renderer` 的 `items` 声明为 `required: true` —— 校验器不再放过必崩的节点
+
+  `items` 在组件侧是**非可选**的 `NavigationItem[]`(`NavigationRendererProps.items`,无 `?`),
+  渲染器也不给默认值,而注册声明一直没写 `required`。`sdui-parser` 只在 `input.required` 为真时
+  报 `missing-required-prop`(`validate.ts:55-64`),于是 `{ "type": "navigation-renderer" }`
+  这个节点**校验零诊断、渲染直接抛**:第一处无守卫的读点是 `pinnedItems` memo 里的
+  `collectPinnedItems(filteredItems)`(`NavigationRenderer.tsx:1242` → `:1410` 的
+  `for (const item of items)`),实测 `TypeError: items is not iterable`。
+  (`resolveActiveNavItem` memo 挡得住 —— 它的 `visit` 首行是 `if (!nodes) return`;
+  `:1247` 的 `filteredItems.slice()` 同样会抛,但根本走不到。)
+
+  这是 objectui#3972(键的**存在**与**类型**三面对齐)的第四面:**可选性**。#3972 与
+  objectui#3900 都是删除假诊断,这一条相反——它是**收紧**。
+
+  **blast radius:** 今天省略 `items` 写 `navigation-renderer` 的 schema,会新增一条
+  **error** 级 `missing-required-prop`。受影响面是仓外按 `inputs` / `packages/layout/README.md`
+  做 schema 驱动的消费者(仓内没有任何 JSON 元数据把它当 schema 节点写,React 调用侧的必填由
+  TS 兜住;`examples/schema-catalog` 的 `not-a-container` 对照节点补了 `items: []`,使它只剩
+  那一处故意植入的缺陷)。而这条诊断新拦下的形状,**恰好等于渲染必然崩溃的形状** —— 让作者
+  (尤其是 AI 作者)在发布期就听到运行期注定要发生的失败,正是 `missing-required-prop` 存在
+  的理由。若某个消费者确实想要"缺 items 就渲染空导航",那是给组件加 `= []` 默认值的另一条路
+  (objectui#3987 里记了,与本改动不互斥),而不是让校验器继续沉默。
+
+  `basePath` **保持可选**并被钉成对照:渲染器真的给了它默认值(`basePath = ''`)。`required`
+  是逐个属性从组件读出的事实,不是一刀切——否则这道门会开始拒绝完全能渲染的 schema,作者就会
+  学着无视 `missing-required-prop`,正如 #3972 里他们被教着无视 `type-mismatch`。
+
+- 82f8dff: `page-header` 注册补 `isContainer: true` —— 校验器不再对文档承诺的 children 写法报 `not-a-container`
+
+  `PageHeader` 一直**有意**把 `schema.children` 渲染进右侧动作槽(`PageHeader.tsx:182`,
+  `record:quick_actions` 嵌在 `page:header.children` 下就是靠它),
+  `content/docs/layout/page-header.mdx` 把该槽的优先级(`action` → React `children` →
+  `actions` → schema children)写成公开契约,该文档页唯一的 live demo
+  (`layout-page-header/pageheader-with-actions`)正是这个形状且实测正常渲染。但
+  `packages/layout/src/index.ts` 的注册漏了 `isContainer: true`。
+
+  漏这个 flag 从来没有挡住任何渲染 —— 渲染路径根本不读它(`SchemaRenderer` 把
+  `children` 从 React props 里剥掉当元数据,而始终把整个节点作为 `schema` 传下去,
+  `PageHeader` 自己再把 `schema.children` 放回槽里)。它的消费者在别处:`sdui-parser`
+  的 `not-a-container` 诊断、Studio 调色板元数据、react-page 标签表。所以真正的后果是
+  **校验器在说谎**:作者照文档写出能正常渲染的 schema,却拿到一条
+  "`page-header` does not accept children" 的 warning;信了这条 warning 去掉 children,
+  右槽就空掉。而会说谎的 warning 比缺一条 warning 更贵 —— 它训练作者(尤其 AI 作者)
+  连真实的 `not-a-container`(那些确实不收子节点的组件)一起无视。
+
+  这不是在 spec 之外新开作者面:`children` 是 objectui JSON 协议里**每个节点**的基础属性
+  (`sdui-parser/src/validate.ts` 的 `BASE_PROPS` 把它和 `type`/`id`/`className` 并列),
+  不是 `PageHeaderProps` 的键。所以这个 flag 回答的是协议层面的"该节点是否接受子节点列表",
+  而对这个组件,答案一直是"是"。维护者 2026-08-09 就 objectui#3900 的 A/B 分叉裁定 A 案,
+  理由同上。
+
+  行为面变化极窄:注册元数据一个布尔位。渲染输出逐字节不变(渲染路径不读该 flag);
+  `sdui-parser` 对带 children 的 `page-header` 少报一条 warning;设计器把它当容器对待
+  (即它本来的样子)。canonical 的 `page:header`(`@object-ui/components`)不在此列且刻意不动
+  —— 那个渲染器完全不读 `schema.children`,所以它没有 `isContainer` 是正确的。
+
+  两个方向都已钉住:文档 demo 走应用真实构建的 manifest 后不再产生 `not-a-container`,
+  而一个真正不收子节点的组件(`navigation-renderer`)带 children 时诊断照旧触发 ——
+  后者是前者的对照,保证这条修复不是把诊断弄哑了。
+
+- Updated dependencies [794c497]
+- Updated dependencies [993336f]
+- Updated dependencies [f0a625a]
+- Updated dependencies [b5980f4]
+- Updated dependencies [8aad9fd]
+- Updated dependencies [6719877]
+- Updated dependencies [56ff091]
+- Updated dependencies [0cbdca8]
+- Updated dependencies [d229dfa]
+- Updated dependencies [ecae400]
+- Updated dependencies [4bc6c23]
+- Updated dependencies [d3e738a]
+- Updated dependencies [c3b01a7]
+- Updated dependencies [7ed3360]
+- Updated dependencies [0fa5e4d]
+- Updated dependencies [5bfaabd]
+- Updated dependencies [e06810e]
+- Updated dependencies [ab3ad4f]
+- Updated dependencies [c2fd122]
+- Updated dependencies [e24d767]
+- Updated dependencies [aca561a]
+- Updated dependencies [48132f7]
+- Updated dependencies [0ef9dfd]
+- Updated dependencies [1d723e3]
+- Updated dependencies [0109f54]
+- Updated dependencies [7e5bb5d]
+- Updated dependencies [fbc23e0]
+- Updated dependencies [e6fdbdc]
+- Updated dependencies [54233b1]
+- Updated dependencies [97b63d7]
+- Updated dependencies [6bb454a]
+- Updated dependencies [523be48]
+- Updated dependencies [7e2b7e9]
+- Updated dependencies [c1e1e6b]
+  - @object-ui/components@17.4.0
+  - @object-ui/react@17.4.0
+  - @object-ui/core@17.4.0
+  - @object-ui/types@17.4.0
+
+## 17.3.0
+
+### Minor Changes
+
+- 608669e: `AppSchemaRenderer` now derives area visibility from the items inside the
+  area, closing the visible-but-empty regression the spec 17.0.0 area-key
+  retirement left behind (objectui#3311, option C of the recorded ruling).
+
+  Spec 17.0.0 retired the authorable area-level `visible` /
+  `requiredPermissions` (`AREA_VISIBLE_RETIRED` /
+  `AREA_REQUIRED_PERMISSIONS_RETIRED`) — an area is a layout grouping, not an
+  access boundary — and objectui followed in #3315 by deleting the area
+  switcher's filter. Correct on the contract, but it changed the navigation
+  surface: an area whose items are **all** gated away used to disappear from
+  the switcher and instead rendered as a selectable, empty area.
+
+  ## What changed
+
+  - **Area visibility is now derived, not authored.** An area appears in the
+    switcher iff at least one of its navigation items survives the exact
+    item-level guards `NavigationRenderer` applies: the `visible` expression,
+    `requiredPermissions`, the `requiresObject` / `requiresService` runtime
+    capability gates, and — for `action` items — the presence of an `onAction`
+    dispatcher (framework#4509: without one they are not rendered, so they
+    cannot carry an area either). Separators never count; a `group` counts only
+    through its children.
+  - **The active area is elected among visible areas only.** A fully gated
+    first area is no longer auto-activated, and when a gating change hides the
+    currently active area the shell re-elects the first visible one. A gating
+    change that merely _reveals_ an area never yanks the user away from where
+    they are.
+  - **An area with no items at all derives the same way**: no visible item →
+    hidden. (Boundary recorded in objectui#3311.)
+  - New export `hasVisibleNavigationItems(items, options)` from
+    `@object-ui/layout` — the predicate behind the derivation, usable by other
+    shells that render their own area switchers.
+
+  No authorable key is involved anywhere: the platform's `.strict()` area
+  object still rejects the retired keys, and the derivation — computed from the
+  same guards that decide what renders — cannot disagree with the rendered
+  navigation, so there is nothing for a metadata author to get wrong.
+
+- d22ae31: Track `@objectstack/spec` 17.0.0-rc.2 (objectui#3235, #3208, #3287, #3264).
+
+  The pin moves from `^17.0.0-rc.1` to `^17.0.0-rc.2` across the workspace, and
+  the sibling `@objectstack/*` packages (`client` / `core` / `formula` / `lint`)
+  move with it — they pin `@objectstack/spec` **exactly**, so leaving them behind
+  kept a second copy of the spec in the tree and would have had `@objectstack/lint`
+  validating against rc.1 schemas that still accept keys rc.2 retires.
+
+  Breaking semantics, in FROM → TO form:
+
+  - **`app.homePageId` is retired — an app's landing page is now its first
+    navigation item.** An app that pinned a landing page with `homePageId` will
+    open on the first reachable navigation entry (by `order`) instead; the root
+    landing still follows `isDefault`. To restore a specific landing page, reorder
+    `navigation` so the intended entry comes first. Stored metadata is migrated by
+    `os migrate meta --from 16`. The key is a hard error now, not a stripped one:
+    the spec ships a tombstone that names the migration.
+    Upstream retired it because of its SHAPE, not its usage — it was an ID
+    cross-reference with no referential integrity, so a `homePageId` that pointed
+    at nothing silently fell back to the first navigation item anyway
+    (objectstack#4667, premise corrected in #4709). If the capability returns, it
+    returns as a flag on the navigation item itself, which cannot dangle.
+  - **`@object-ui/types`' `HttpMethod` now resolves to the spec's
+    `HttpMethodType`.** Shape is verbatim identical — the same 5-value UI subset —
+    and `@object-ui/types` still exports it as `HttpMethod`, so no consumer
+    changes. The spec renamed its `./ui` export because `HttpMethod` named two
+    different types depending on the import path (`./shared` / `./api` carry a
+    7-value enum including `HEAD` / `OPTIONS`); objectui deliberately keeps the
+    5-value one (objectstack#4691).
+  - **`AppContextSelector.includeAll` / `placement` are gone.** Neither ever did
+    anything in this renderer: context selectors are mandatory-scope, so no "All"
+    row was ever rendered, and `placement: 'topbar'` put nothing in the topbar.
+    Both carried schema defaults, which is why the liveness lint structurally
+    could not flag them — removal was the only channel that reaches an author
+    (framework#4509).
+  - **`NavigationArea.visible` / `order` / `requiredPermissions` are gone.** An
+    area is a layout grouping, not an access boundary. Gating moved down to the
+    navigation ITEM, where `visible` and `requiredPermissions` are unchanged and
+    still enforced. `AppSchemaRenderer`'s area switcher no longer hides an area, so
+    an area whose items are all gated away renders as visible-but-empty rather
+    than disappearing.
+  - **`@object-ui/core` no longer exports `NotificationProtocol`**
+    (`resolveNotificationConfig`, `specNotificationToToast`, `mapSeverityToVariant`,
+    `mapPosition`, `ToastNotification`). It bridged `@objectstack/spec/ui`'s
+    `Notification` / `NotificationConfig`, which objectstack#4610 deleted with no
+    successor. Use `resolveNotificationConfig` from `@object-ui/react`
+    (`NotificationContext`), which owns the live `NotificationSystemConfig` and is
+    what every notification surface already read. Note that the spec's _other_
+    `Notification` — `@objectstack/spec/api` — is the REST inbox row, a different
+    contract, and is deliberately NOT aliased in as a replacement.
+  - **The `email_template` client-side validator now uses
+    `EmailTemplateDefinitionSchema`.** It was pointing at the removed
+    `EmailTemplateSchema`, so authored templates were being checked against the
+    wrong contract: the live one is keyed `name` + `locale` (not `id`) and splits
+    the body into `bodyHtml` / `bodyText` (not `body` + `bodyType`)
+    (objectstack#4616 / #4807).
+
+  Fixes that are not breaking, but were only found because rc.2 stopped being
+  lenient — each had been passing vacuously:
+
+  - **`view` drafts are actually validated now.** The client validator named the
+    aggregated container schema while this admin authors first-class `ViewItem`s,
+    and the container used to strip `viewKind` / `config` in silence — so no view
+    draft ever had one of its own keys checked. It now validates each shape
+    against its own schema (objectui#3312).
+  - **The console's worked examples were wrong**, and being stripped rather than
+    refused: `view.list.object` (the container root already declares it),
+    `job.concurrency` / `job.timeoutMs` (no such keys; the spelling is `timeout`,
+    already in ms), `email_template.from` / `.to` (a template is not a send —
+    the sender override is `fromOverride`, an object), and
+    `datasource.capabilities` / `.healthCheck` (objectstack#4583 removed the
+    former; the latter was never a datasource key). These are the drafts an
+    author — or a model generating metadata — copies.
+  - Action key inventory re-derived: `ActionSchema` gained the package-lock
+    envelope (`_lock*` / `_package*` / `_provenance`), so a packaged action no
+    longer reports them as unknown keys.
+  - The schema-diff panel labels the new `default_mismatch` finding.
+  - Test fixtures pinning the retired `managedBy: 'system'` bucket now use
+    `engine-owned`. Protocol 17 split that value (objectstack#3355), so it
+    resolved to the default-writable fallback and a batch of "stays locked"
+    assertions had quietly stopped asserting anything.
+
+### Patch Changes
+
+- d2363e7: The legacy `page-header` alias stops advertising `description` as an authorable
+  key (objectui#3226).
+
+  FROM: `registerLayout()` declared `inputs: [title, description]`. TO:
+  `inputs: [title, subtitle]` — the key `@objectstack/spec/ui`'s `PageHeaderProps`
+  declares, and the one the canonical `page:header` renderer in
+  `@object-ui/components` already declares.
+
+  `inputs` is a DECLARATION surface, not documentation: the designer builds its
+  property palette from it, and the framework's `check:react-declaration-parity`
+  diffs it against the spec schemas. Declaring `description` therefore did not
+  merely tolerate a legacy spelling — it published a second dialect for the one
+  concept the protocol calls `subtitle`, and told authors (an AI author most
+  readily, since the registry is what it reads to learn the shape) that the
+  non-spec key was legal. Metadata that took the offer renders a subtitle under
+  `page-header` and silently loses it under `page:header`: same JSON, two results,
+  which is the outcome a single contract exists to prevent.
+
+  No runtime behaviour changes. `PageHeader` still reads `subtitle ?? description`,
+  deliberately: this alias exists for out-of-repo consumer schemas, so "no in-repo
+  author writes `description`" (verified — zero hits) is not evidence that nobody
+  does, and dropping the read today would delete an external page's second line
+  while its title kept rendering, the least reportable failure mode there is. That
+  read is retired together with an ADR-0087 D2 conversion entry
+  (`page-header-subtitle-alias`, `description` → `subtitle` rewritten at load
+  time), which lives in the framework repo and is tracked separately. Narrowing the
+  declaration did not need to wait on it and breaks no consumer; leaving the
+  declaration wrong in the meantime keeps minting the metadata the conversion would
+  then have to absorb.
+
+  New tests pin both halves so neither can drift back: the registration may not
+  declare `description`, must declare `subtitle`, and — checked against the spec's
+  own shape rather than a hand-written allowlist — may declare nothing
+  `@objectstack/spec` does not; while the runtime fallback is pinned as a sequencing
+  guard, to be deleted in the same change that lands the conversion entry.
+
+- Updated dependencies [18cd432]
+- Updated dependencies [532cf8b]
+- Updated dependencies [680080a]
+- Updated dependencies [a7651e6]
+- Updated dependencies [d915c47]
+- Updated dependencies [b71fc92]
+- Updated dependencies [34595eb]
+- Updated dependencies [3889ffb]
+- Updated dependencies [5781fb1]
+- Updated dependencies [9e9e9a9]
+- Updated dependencies [56409c2]
+- Updated dependencies [042e09d]
+- Updated dependencies [9cbcbf4]
+- Updated dependencies [85c4c9c]
+- Updated dependencies [fd54c3e]
+- Updated dependencies [4eeb932]
+- Updated dependencies [23018cc]
+- Updated dependencies [53811d1]
+- Updated dependencies [d915c47]
+- Updated dependencies [f44d872]
+- Updated dependencies [509104a]
+- Updated dependencies [825bbe3]
+- Updated dependencies [5dd0127]
+- Updated dependencies [06632e9]
+- Updated dependencies [a4cff5b]
+- Updated dependencies [175bd79]
+- Updated dependencies [f833d3a]
+- Updated dependencies [2a9513d]
+- Updated dependencies [71be406]
+- Updated dependencies [d22ae31]
+- Updated dependencies [8d8094a]
+  - @object-ui/core@17.3.0
+  - @object-ui/components@17.3.0
+  - @object-ui/types@17.3.0
+  - @object-ui/react@17.3.0
+
 ## 17.2.0
 
 ### Minor Changes
@@ -815,6 +1436,7 @@
 - b703480: feat(layout): smoother sidebar transitions
 
   `SidebarNav` now animates the previously-instant state changes:
+
   - Active-state colour swap on `SidebarMenuButton` /
     `SidebarMenuSubButton` is wrapped in `transition-colors duration-150`
     so navigating between rows glides rather than snaps.
@@ -894,6 +1516,7 @@
   record detail page (lead, opportunity, future account/contact/case).
   Before this change it had two problems that bled into every custom
   page across the product:
+
   1. **Quadruple registration**: `@object-ui/layout` registered both
      `page-header` and `page:header`, and `@object-ui/components`
      independently registered `page:header` (and `page:section`).
@@ -904,6 +1527,7 @@
      than the default detail view it was meant to supersede.
 
   This commit:
+
   - Removes the `@object-ui/layout` `page:header` registration. The
     layout package keeps the legacy kebab-cased `page-header` alias only.
     The canonical renderer now lives in `@object-ui/components` and is
@@ -982,6 +1606,7 @@
 - d714e85: Lookup display-name resolution now falls back through a Salesforce-style chain
   when an `$expand`'d reference object lacks a top-level `name`/`label`/
   `display_name`/`title` field:
+
   1. Standard display fields (existing behaviour)
   2. `salutation first_name last_name` composite — handles person records that
      only carry first/last name parts
@@ -1040,6 +1665,7 @@ Lin` and no `name` field now renders as `Bob Lin` everywhere — instead of
   pages without a record context are unaffected.
 
 - 2bd45af: feat(shell): main becomes the scroll container; record tabs are sticky
+
   - `AppShell`'s SidebarProvider wrapper is now constrained to viewport
     height (`h-svh overflow-hidden`) instead of expanding with content via
     the default `min-h-svh`. This makes the inner `<main>` (which is
@@ -1062,6 +1688,7 @@ Lin` and no `name` field now renders as `Bob Lin` everywhere — instead of
 ### Patch Changes
 
 - 6b683c8: fix(detail): clean up record page rendering
+
   - Drop `ai:chat_window` from the protocol-component placeholder list. The
     floating chat overlay (plugin-chatbot) is the canonical AI entry point;
     inline page schemas that still reference `ai:chat_window` now surface
@@ -1075,6 +1702,7 @@ Lin` and no `name` field now renders as `Bob Lin` everywhere — instead of
     as a fallback so both inlined and raw-bag schema shapes are supported.
 
 - 0d8eb98: feat(detail): Salesforce-style record header + section field grid
+
   - `page:header` now renders an icon chip (resolves Lucide names via
     `LazyIcon`) plus subtitle, so detail pages can show
     "Name / Company" without an extra component.
@@ -1233,6 +1861,7 @@ Lin` and no `name` field now renders as `Bob Lin` everywhere — instead of
   Library builds (vite lib mode) now externalize every non-relative import instead of bundling third-party CJS dependencies into the published dist. This avoids inlined `require("react")` / `require("react-dom")` calls that cause `Calling \`require\` for "react" in an environment that doesn't expose the \`require\` function` runtime errors when consumer apps re-bundle the published dist.
 
   Specifically fixes:
+
   - `@object-ui/plugin-dashboard` no longer inlines `react-grid-layout` (and its transitive `react-draggable` / `react-resizable` CJS bundles). `react-grid-layout` is now declared as a peer dependency so consumers install a single ESM-friendly copy.
   - `@object-ui/components`, `@object-ui/plugin-calendar`, `@object-ui/plugin-charts`, `@object-ui/plugin-designer` no longer inline `react-i18next` / `i18next` / `use-sync-external-store` CJS shims.
   - All plugin packages now use a unified `external: (id) => !/^[./]/.test(id) && !id.startsWith(__dirname)` rule, ensuring future additions of CJS deps are automatically externalized.