wip(i18n): widen the shared page walk to slots + items[].children; add dashboards.*.globalFilters

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016N6xmWt5hYm94ffVEwGH8x

Author: claude

.changeset/i18n-slotted-pages-and-global-filters.md

@@ -0,0 +1,15 @@
+---
+"@objectstack/spec": minor
+"@objectstack/cli": patch
+---
+
+Two surfaces the console renders that no translation bundle could address — a `kind: 'slotted'` page's components and a dashboard's global-filter bar — are now addressable (#16772).
+
+**`walkAddressedPageComponents` widens in both dimensions.** The shared page walk behind `translatePage` and the CLI extractor (`os i18n extract` / `os i18n coverage`) rooted at `regions[].components[]` only and descended `properties.children` only. A slotted record page authors `regions: []` and puts everything under `slots.<slot>`, so the walk visited nothing on it and `pages.<name>` carried exactly two addressable keys however many components the page authored; a `page:tabs` / `page:accordion` keeps its panels' components under `properties.items[].children`, one level deeper than the descended slot, so a related list inside a tab was unreachable on any page kind. The walk now roots at `regions[].components[]` **and** `slots.<slot>` (one component or an array per slot, regions first, then slots in authored order — both root level for the collision arbitration and for the page-name `page:header` route, so a slotted page's `slots.header` is translated as the page's header), and descends `properties.children` **and** `properties.items[].children` (matched by shape, so a custom container speaking the same vocabulary is walked too; `body` / `footer` remain undescended — a renderer back-compat fallback, not an authorable spelling). The depth cap, the cycle guard and the ruled id arbitration are unchanged.
+
+- Signature: the parameter is `AddressedPageRoots` (= `Pick<PageLike, 'regions' | 'slots'>`) instead of `Pick<PageLike, 'regions'>`, and the walk returns the rebuilt roots pair `{ regions?, slots? }` (each key present exactly when present on the input) instead of the regions array alone. `PageLike` gains `slots`. An enumeration-only consumer that ignores the return value needs no change; a consumer reading the returned regions destructures `{ regions }`.
+- `translatePage` carries the rebuilt `slots` back onto the document.
+
+**`dashboards.<name>.globalFilters.<key>` is a new bundle group.** A dashboard's filter bar draws directly above the widget titles the bundle has always translated, and neither a filter's label nor its static option labels had a key. The group is keyed by the filter's `name` (`GlobalFilterSchema.name`, declared as defaulting to `field` — a filter that authors no `name` is keyed by its `field`) and carries `label` and an `options.<value>` map keyed by the option `value` spelled as a string. `translateDashboard` overlays it on the served document, which is what objectui's filter bar already reads; the exported `globalFilterKey()` is the one key derivation both the resolver and the extractor use. `optionsFrom` options are fetched rows and are deliberately not addressable.
+
+**`@objectstack/cli`:** `os i18n extract` offers `dashboards.<name>.globalFilters.<key>.label` / `.options.<value>` for every static filter, and `pages.<name>.title` / `.subtitle` for a `page:header` at any root (a slotted page's `slots.header` included) — the component keys under `slots` and tab panels follow from the shared walk with no extractor change.

content/docs/ui/translations.mdx

@@ -74,9 +74,11 @@ export default defineStack({
 | App navigation | `apps.<app>.navigation.<id>.label` |
 | Dashboard label / description | `dashboards.<name>.label` / `description` |
 | Dashboard widget title / description / sub-caption | `dashboards.<name>.widgets.<widgetId>.title` / `description` / `subCaption` |
+| Dashboard global-filter label and static option labels | `dashboards.<name>.globalFilters.<filterName>.label` / `.options.<value>` — the key is the filter's `name`, or its `field` when it authors no `name`; an option is keyed by its `value` spelled as a string |
 | Analytics dataset label / description | `datasets.<name>.label` / `description` |
 | Dataset dimension and measure labels | `datasets.<name>.dimensions.<dimension>.label` / `datasets.<name>.measures.<measure>.label` |
-| Page labels and `page:header` copy | `pages.<name>.label` / `description` / `title` / `subtitle` |
+| Page labels and `page:header` copy | `pages.<name>.label` / `description` / `title` / `subtitle` — on a `kind: 'slotted'` page the header under `slots.header` is the page's header |
+| Page component copy, by component id | `pages.<name>.components.<id>.title` / `description` / `label` / `placeholder` / `emptyText` — reached under `regions[].components[]` and `slots.<slot>`, through `properties.children` and a `page:tabs` / `page:accordion` panel's `items[].children` |
 | Screen-flow wizards (flow label, screen headings, screen field copy) | `flows.<flow>.label` / `flows.<flow>.screens.<node_id>.title` / `.fields.<field>.label` / `.placeholder` — see the boundary note below |
 | Global actions, settings, messages | `globalActions`, `settings`, `messages` |
 | A label written as an inline locale map (`label: { en: 'Members', 'zh-CN': '成员' }`) | Nowhere — it is written on the metadata and resolved at render time; see **Current boundaries** below |

packages/cli/src/utils/i18n-extract.ts

@@ -127,6 +127,7 @@ import {
   PAGE_COMPONENT_COPY_KEYS,
   FLOW_SCREEN_COPY_KEYS,
   FLOW_SCREEN_FIELD_COPY_KEYS,
+  globalFilterKey,
   walkAddressedPageComponents,
 } from '@objectstack/spec/system';
 import { DEFAULT_METADATA_TYPE_REGISTRY } from '@objectstack/spec/kernel';
@@ -1321,6 +1322,26 @@ export function collectExpectedEntries(
         pushEntry(out, ['dashboards', name, 'widgets', wid, 'description'], w.description, 'widget');
       }
     }
+    // Global-filter copy (#16772) — `dashboards.<name>.globalFilters.<key>`,
+    // the filter bar drawn above the widget titles. The KEY is imported from
+    // `@objectstack/spec` (`name`, else `field`) so the extractor offers the
+    // entry `translateDashboard` reads and never a neighbour of it; an option
+    // is keyed by its `value` spelled as a string, the resolver's own
+    // spelling. `optionsFrom` options are fetched rows and have no key.
+    const globalFilters: any[] = Array.isArray(dash.globalFilters) ? dash.globalFilters : [];
+    for (const filter of globalFilters) {
+      if (!filter || typeof filter !== 'object') continue;
+      const key = globalFilterKey(filter);
+      if (key === undefined) continue;
+      pushEntry(out, ['dashboards', name, 'globalFilters', key, 'label'], filter.label, 'dashboard');
+      const options: any[] = Array.isArray(filter.options) ? filter.options : [];
+      for (const option of options) {
+        if (!option || typeof option !== 'object') continue;
+        const { value } = option;
+        if (typeof value !== 'string' && typeof value !== 'number' && typeof value !== 'boolean') continue;
+        pushEntry(out, ['dashboards', name, 'globalFilters', key, 'options', String(value)], option.label, 'dashboard');
+      }
+    }
   }
 
   // ── Analytics datasets (`datasets.<name>.…`) ─────────────────────
@@ -1337,12 +1358,13 @@ export function collectExpectedEntries(
     }
     // Header copy is authored inside the page's `page:header` component but
     // is addressed by page name — `translatePage` overlays it back onto every
-    // header in the page's regions.
-    const regions: any[] = Array.isArray(page.regions) ? page.regions : [];
-    for (const region of regions) {
-      const components: any[] = Array.isArray(region?.components) ? region.components : [];
-      for (const component of components) {
-        if (component?.type !== PAGE_HEADER_COMPONENT_TYPE) continue;
+    // ROOT-LEVEL header: a region's entry, or a `slots.<slot>` entry on a
+    // `kind: 'slotted'` page (#16772). Which components are root level is the
+    // shared walk's to say (`nested: false`), not a second loop's — the loop
+    // this replaced read `page.regions` by hand and would have offered
+    // nothing for the `slots.header` the resolver now translates.
+    walkAddressedPageComponents(page, (component, { nested }) => {
+      if (!nested && component?.type === PAGE_HEADER_COMPONENT_TYPE) {
         const props = component.properties ?? {};
         // `title` duplicating `label` is the common case and resolves via the
         // label fallback — only emit it when the two genuinely differ.
@@ -1351,7 +1373,8 @@ export function collectExpectedEntries(
         }
         pushEntry(out, ['pages', name, 'subtitle'], props.subtitle, 'page');
       }
-    }
+      return component;
+    });
 
     // Per-component copy, addressed by the component's own id (#6080). Without
     // this pass the face exists but nothing writes the skeleton, so a

packages/cli/test/platform-page-i18n-parity.test.ts

@@ -289,18 +289,24 @@ const walkParityPage = (): Record<string, any> => ({
               null,
             ],
             // NOT descended by `translatePage`: `body`/`footer` are a
-            // renderer-side back-compat fallback, and `items[].children` sits
-            // one level deeper than the slot the ruling names.
+            // renderer-side back-compat fallback, not an authorable
+            // composition spelling.
             body: [{ id: 'card_body_child', type: 'object-metric', properties: { title: 'Body child' } }],
             footer: [{ id: 'card_footer_child', type: 'object-metric', properties: { title: 'Footer child' } }],
-            items: [{ children: [{ id: 'tab_child', type: 'object-metric', properties: { title: 'Tab child' } }] }],
+            // DESCENDED since #16772 — a `page:tabs` / `page:accordion`
+            // panel's `items[].children`, one level below the container.
+            items: [{ label: 'Panel', children: [{ id: 'tab_child', type: 'object-metric', properties: { title: 'Tab child' } }] }],
           },
         },
       ],
     },
   ],
-  // NOT walked by `translatePage` at all — it maps `regions` only.
-  slots: { aside: { id: 'slot_child', type: 'object-metric', properties: { title: 'Slot child' } } },
+  // A ROOT since #16772 — a `kind: 'slotted'` page authors its components
+  // here (one component or an array per slot); walked after the regions.
+  slots: {
+    aside: { id: 'slot_child', type: 'object-metric', properties: { title: 'Slot child' } },
+    details: [{ id: 'slot_list_child', type: 'record:details', properties: { title: 'Slot list child' } }],
+  },
 });
 
 /** A container chain deeper than the resolver's descent cap. */
@@ -370,17 +376,46 @@ describe('i18n-extract ↔ translatePage walk parity (#13109)', () => {
     const page = walkParityPage();
     expect([...idsExtractorOffers(page)].sort()).toEqual([
       'card', 'inner_flex', 'kpi_1', 'kpi_deep', 'kpi_label', 'nested_header', 'region_metric',
+      'slot_child', 'slot_list_child', 'tab_child',
     ]);
-    // `card_body_child`, `card_footer_child`, `tab_child` and `slot_child` are
-    // absent from BOTH sides — the shapes `translatePage` does not descend.
+    // `card_body_child` and `card_footer_child` are absent from BOTH sides —
+    // the shapes `translatePage` does not descend. `tab_child`, `slot_child`
+    // and `slot_list_child` are present on BOTH sides since #16772 widened
+    // the shared walk to `items[].children` and to the `slots.<slot>` roots.
     // `hdr` — the region-level `page:header` — is absent from BOTH sides since
     // the ruling. `nested_header` stays: a `page:header` inside a container is
     // reached by the id route only, so the id key is the only key it has.
     expect([...idsResolverApplies(page)].sort()).toEqual([
       'card', 'inner_flex', 'kpi_1', 'kpi_deep', 'kpi_label', 'nested_header', 'region_metric',
+      'slot_child', 'slot_list_child', 'tab_child',
     ]);
   });
 
+  it('offers and reads the page-name header route for a `slots.header` page:header — a slotted page has a header too (#16772)', () => {
+    const page = {
+      name: 'slotted_header_page',
+      label: 'Contract',
+      kind: 'slotted',
+      regions: [],
+      slots: {
+        header: { id: 'hdr', type: 'page:header', properties: { title: 'Contract detail', subtitle: 'Lifecycle' } },
+      },
+    };
+    const offered = collectExpectedEntries({ pages: [page] } as any)
+      .filter((e) => e.path[0] === 'pages' && e.path[1] === page.name)
+      .map((e) => e.path.slice(2).join('.'))
+      .sort();
+    // Page-name route offered; the id route NOT offered for a root-level
+    // header, exactly as for a region-level one.
+    expect(offered).toEqual(['label', 'subtitle', 'title']);
+
+    const bundle = {
+      en: { pages: { slotted_header_page: { title: 'T::title', subtitle: 'T::subtitle', components: { hdr: { title: 'ID-ROUTE' } } } } },
+    } as any;
+    const out = translatePage(page as any, bundle, { locale: 'en' });
+    expect(out.slots.header.properties).toEqual({ title: 'T::title', subtitle: 'T::subtitle' });
+  });
+
   // ── The ruled invariant, pinned directly (decision batch #58, 2026-09-06) ──
   //
   // Maintainer 「同意」, option 1, verbatim: "The page-name route is canonical
@@ -756,22 +791,31 @@ describe('shipped platform record pages -- i18n ownership (#14817)', () => {
     expect(SHIPPED_LOCALES.length).toBeGreaterThan(1);
   });
 
-  it('records that the extractor reaches the page label and nothing under `slots`', () => {
-    // A BOUNDARY PIN, not an endorsement. It states the measured fact that the
-    // shared walk roots at `regions[].components[]` and these pages author
-    // `regions: []`, so the 45 inline sites under `slots.*` have no bundle
-    // face. If the walk is ever widened -- a maintainer decision open on
-    // #14749 -- this reds, and the person widening it is told, at the exact
-    // moment they can act on it, that these three pages gain a bundle surface
-    // that needs entries and a coverage home. That notice is the whole value:
-    // today the same change would land green over an unmeasured population.
+  it('records that the extractor now reaches under `slots` — and that every site it reaches there is an inline locale map with no seed', () => {
+    // A BOUNDARY PIN, not an endorsement — moved, not removed. Until #16772
+    // this pinned `offered: ['label']`: the shared walk rooted at
+    // `regions[].components[]`, these pages author `regions: []`, and the 45
+    // inline sites under `slots.*` had no bundle face. #16772 widened the
+    // walk to the `slots.<slot>` roots and to `items[].children`, so the
+    // notice the old pin promised has fired, and this is the answer to it:
+    // these pages' copy is authored as inline locale maps (the ruled route for
+    // page copy, judged complete by the next case), so what the extractor
+    // offers for them is a set of `inlineLocales` rows — authored-with-no-
+    // seed, never a string to translate. The bundle surface they gained
+    // therefore needs NO entries, and their coverage home stays this file.
+    // What this pin holds: the reach is real (more than the label alone), and
+    // it exposes no seeded string for a translator to be asked for.
     for (const page of RECORD_PAGES) {
-      const offered = collectExpectedEntries({ pages: [page] } as any)
-        .filter((e) => e.path[0] === 'pages' && e.path[1] === page.name)
-        .map((e) => e.path.slice(2).join('.'))
-        .sort();
-      expect({ page: page.name, regions: page.regions, offered })
-        .toEqual({ page: page.name, regions: [], offered: ['label'] });
+      const entries = collectExpectedEntries({ pages: [page] } as any)
+        .filter((e) => e.path[0] === 'pages' && e.path[1] === page.name);
+      const offered = entries.map((e) => e.path.slice(2).join('.')).sort();
+      expect(page.regions).toEqual([]);
+      expect(offered).toContain('label');
+      expect(offered.filter((k) => k.startsWith('components.')).length).toBeGreaterThan(0);
+      const seeded = entries
+        .filter((e) => e.path[2] === 'components' && e.inline !== undefined)
+        .map((e) => e.path.slice(2).join('.'));
+      expect({ page: page.name, seededUnderSlots: seeded }).toEqual({ page: page.name, seededUnderSlots: [] });
     }
   });
 

packages/spec/liveness/translation.json

@@ -51,7 +51,7 @@
     "dashboards": {
       "status": "live",
       "verifiedAt": "2026-08-28",
-      "evidence": "packages/spec/src/system/i18n-resolver.ts#lookupDashboardAttr (`dashboards.<name>.label` / `.description`); packages/spec/src/system/i18n-resolver.ts#lookupWidgetAttr (`dashboards.<name>.widgets.<id>.<attr>`, `subCaption` included); packages/spec/src/system/i18n-resolver.ts#translateDashboard",
+      "evidence": "packages/spec/src/system/i18n-resolver.ts#lookupDashboardAttr (`dashboards.<name>.label` / `.description`); packages/spec/src/system/i18n-resolver.ts#lookupWidgetAttr (`dashboards.<name>.widgets.<id>.<attr>`, `subCaption` included); packages/spec/src/system/i18n-resolver.ts#translateGlobalFilter (`dashboards.<name>.globalFilters.<key>.label` / `.options.<value>`, keyed by `globalFilterKey` — `name`, else `field`; #16772); packages/spec/src/system/i18n-resolver.ts#translateDashboard",
       "note": "translateDashboard: label/description plus per-widget title/description/subCaption by widget id; header action labels. `subCaption` (#7862, #5428 item 4) overlays the metric widget's `options.description` — a different authored field from `widget.description`, each on its own key — live through the same translateDashboard REST path; objectui's client-side renderer half is the downstream follow-up. 2026-08-28: RE-ANCHORED (#13003) and REPOINTED — `:538` had rotted onto the opening line of `translateAction`'s docblock, an ACTION resolver ~244 lines above the dashboard ones; the second position `:554` was a bare line suffix with no path and resolved to nothing. Re-closed by hand against 8cb96ec41."
     },
     "datasets": {