fix(dashboard,i18n): KPI cards and dashboard filters resolve authored labels instead of dropping them (#4032)

[yinlianghui]

Part of #4032.

Part of, not Fixes: ruling item 4 (the sub-caption's own convention segment) is blocked by a hard spec constraint and is returned as a decision rather than implemented — see "Item 4" below. Items 1-3 and the merged #4163 filter-bar scope are complete.

The ruling this implements

From objectstack#5428, maintainer decision of 2026-08-06, quoted verbatim:

维护者裁决（2026-08-06，经 PM 会话 session_01MN3ao9kJEtD7PNAKwFVp96 转达）：A —— DashboardFilterDef.label 放宽为 string | I18nLabel，与渲染器修复打包一单落地：

1. 类型放宽：packages/core/src/utils/dashboard-filters.ts 的 DashboardFilterDef.label，filter bar 消费端解析 I18nLabel；
2. 渲染器三处私有 resolveLabel（MetricCard.tsx:15 / MetricWidget.tsx:118 / DashboardRenderer.tsx:92）接 t()，不再静默丢 key；
3. self-contained metric 分支接回 tWidgetTitle / tWidgetDescription 通道，KPI 卡与其它 widget 同源翻译；
4. 正文遗留设计点（options.description 子标题的 key 归属）PM 裁量：子标题给自己的 convention segment，⛔ 不与 widget.description 共用一个 key —— 两个作者字段两个 key；维护者可否决。

The merged scope comes from the #4163 part-1 audit comment of 2026-08-11, which recorded two compiler-blind filter-bar reads as this ruling's implementation surface.

Premise check: the ruling's item 2 mechanism has expired, its goal has not

Verified against origin/main before implementing, and this changes how item 2 lands.

Item 2 says the three private resolveLabel copies should hand their key to t(). Those copies read { key, defaultValue } — and that vocabulary was retired from @objectstack/spec after the ruling was written (objectstack#5055, in 17.0.0-rc.6). Measured:

DashboardSchema.safeParse({ …widgets: [{ id: 'w1', type: 'metric',
  title: { key: 'crm.rev', defaultValue: 'Total Revenue' } }] })
→ "an inline label map is keyed by BCP-47 locale tags (`en`, `zh-CN`, …) or
   `default` — not by `key`/`defaultValue`, which was the retired key-reference
   form (#5055) and resolves to nothing"

So there is no key left to hand to t(): an author who writes that form today has their dashboard rejected at authoring, not rendered in English. Wiring it to t() would have resurrected a form the contract now refuses — the opposite of contract-first.

The ruling's goal is untouched and is what this PR delivers, through the two channels that are actually live:

• the inline per-locale map ({ en: 'Revenue', 'zh-CN': '收入' }), resolved by pickLocalized;
• the convention-key channel ({ns}.dashboards.{dash}.widgets.{id}.title), which is t() and needs no annotation on the authored value.

They compose in the order useActionTextLocalizer (#4265) already established: collapse the authored value to the active language first, hand the resulting plain string to the bundle as its fallback. A bundle entry always wins; a per-locale literal and a bundle entry can never disagree about what "the authored title" is.

The live defect is also worse than the card states. The card predicts "the English defaultValue in every locale". Measured, a spec-valid map title made resolveLabel return undefined, so the caller's || widgetType fallback took over and the KPI card rendered the literal string metric — the widget type, a plausible-looking word substituted for the title with no diagnostic.

Resolver seam: reused, not re-invented

pickLocalized from @object-ui/i18n — the seam #4208 landed for this exact vocabulary on the sibling surface (DashboardGridLayout.tsx, same DashboardWidget.title field), pinned limb-for-limb against the spec's own resolveI18nLabel over 96/96 spec-valid inputs. No fourth dialect was added; the three private copies are deleted rather than fixed in place.

What changed

Ruling item	Change
1	DashboardFilterDef.label → string | I18nLabel; options[].label likewise. @object-ui/core stays locale-free and carries the vocabulary through; the filter bar resolves.
1 (merged #4163)	DashboardFilterBar resolves before rendering — trigger text, aria-label, TextFilter placeholder/aria-label, date-range aria-label. The def.label || def.name gate now tests the resolved string (an object is always truthy, so it never reached the fallback).
1 (merged #4163)	normalizeFilterOptions no longer coerces a map label to String(value). That line discarded the authored text in every locale, English included: { value: 'domestic', label: { en: 'Domestic', … } } displayed as domestic.
1 (merged #4163)	DashboardComponentSchema.globalFilters bound to the spec's GlobalFilter instead of restated ("绑定优先于重述").
2	Three private resolveLabel copies deleted; DashboardRenderer, MetricWidget, MetricCard all resolve through pickLocalized.
3	The self-contained metric branch takes its label from tWidgetTitle(widget) — the same convention channel every other widget header uses.
4	Not implemented — returned as a decision, below.

MetricWidget keeps two distinct locale channels on purpose: useDisplayLocale for numbers (#4333's threading, untouched) and language for label text.

Item 4 — the sub-caption segment is blocked at the spec, not chosen

The ruling gives the sub-caption its own convention segment. The spec does not admit one. TranslationDataSchema.dashboards.{dash}.widgets.{id} is z.core.$strict over exactly { title?, description? }:

+subCaption  → unrecognized_keys: "Unrecognized key(s) on this widget
               translation: `subCaption`. …"
+subtitle    → "… Did you mean `subtitle` → `description`? …"
+caption     → unrecognized_keys

Every candidate name is refused, and the spec's own suggestion points the sub-caption at description — i.e. at precisely the shared key the ruling forbids. The two constraints are in direct conflict, objectstack is read-only for this task, and the dispatch brief names this case a stop rather than a workaround. Details and options are in the report.

Consequence for reviewers: widget.description on a self-contained metric is still not rendered by this PR. Giving it the only available slot would have put it in the sub-caption, which is the conflation item 4 exists to prevent.

Verification

Red-first, with the direction of every case written down before it was run. All predictions held, including the two that were not the obvious guess: the map-title case fails as the literal metric rather than [object Object], and the option-label case is red in en too (data loss, not a translation gap).

Reverse verification by limb (git checkout origin/main -- < file >, re-run, restore — never git stash):

Reverted	Result
DashboardRenderer.tsx	4 red, 2 controls green
DashboardFilterBar.tsx	6 red, 2 controls green
dashboard-filters.ts (core, alone)	exactly the 2 option-label cases red — producer and consumer halves independently load-bearing
MetricWidget.tsx + MetricCard.tsx	4 red, 2 controls green
complex.ts (the binding)	runtime suite fully GREEN, type-check RED

That last row is the point of dashboard-global-filters-spec-binding.test.ts. The binding is the one part of this change no runtime test can falsify — a type that is too narrow does not fail, it makes the read sites that would have failed invisible to tsc, which is exactly how these reads shipped. Reverting it reproduces that signature deliberately.

Against the merge with current main:

turbo run build        → 43 successful, 43 total
turbo run type-check   → 78 successful, 78 total
turbo run lint         → 45 successful, 45 total (0 errors)
vitest packages/plugin-dashboard/ packages/core/ packages/types/
                       → Test Files 152 passed (152) · Tests 2457 passed (2457)
vitest packages/app-shell/ packages/plugin-designer/   (downstream sweep)
                       → Test Files 354 passed (354) · Tests 3364 passed | 1 skipped
check-i18n-call-site-keys / check-i18n-en-drift  → green, 0 en values changed
check-control-bytes → OK · changeset presence / no-major / fixed → green

Downstream direction stated explicitly: app-shell and plugin-designer are the consumers of the two changed contracts (@object-ui/core's DashboardFilterDef, @object-ui/types' globalFilters), reached by consumer-direction filter, not the upstream dependency set.

One file outside the nominal scope

packages/app-shell/.../DashboardWidgetInspector.tsx, two lines. This is the widening's forced blast radius, not scope creep: widening label turns two previously compiler-blind reads into tsc errors (TS2322 at 369 and 389), so TypeScript Type Check cannot go green without them. Both are repaired with the file's own existing resolver (resolveInlineI18nLabel, already imported there for widget.title), and resolving before the || fixes the same truthiness gate. Flagging it because that file is held by a continuation task — it does not overlap that work, but the PM should know it was touched.

Out of scope, filed

• normalizeFilterOptions accepts a bare-string globalFilters[].options shorthand that @objectstack/spec rejects at publish #4356 — normalizeFilterOptions accepts a bare-string option shorthand the spec rejects at publish. Surfaced by the binding: the restatement was not only too narrow on label, it was too wide here. The type half is fixed and pinned in this PR; the runtime tolerance is deliberately left for stored documents.
• MetricWidget / MetricCard spread ...props onto the DOM, emitting a schema="[object Object]" attribute on every KPI card #4357 — MetricWidget/MetricCard spread ...props onto the DOM, emitting schema="[object Object]" on every KPI card. Observation-class. It is the reason this PR's pins assert on the card heading rather than container.innerHTML.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectui	Ignored		Aug 11, 2026 9:02pm

[github-actions]

✅ Console Performance Budget

Metric	Value	Budget
Main entry (gzip)	29.6 KB	350 KB
Entry file	index-DRzljz6h.js	—
Status	PASS	—

---

📦 Bundle Size Report

Package	Size	Gzipped
app-shell (index.js)	9.56KB	3.59KB
app-shell (runtime-config.js)	7.42KB	2.32KB
app-shell (types.js)	0.01KB	0.04KB
app-shell (urlParams.js)	8.92KB	3.41KB
auth (AuthContext.js)	0.31KB	0.24KB
auth (AuthGuard.js)	1.17KB	0.53KB
auth (AuthProvider.js)	22.10KB	4.37KB
auth (AuthShell.js)	3.49KB	1.40KB
auth (ForgotPasswordForm.js)	12.21KB	3.45KB
auth (LoginForm.js)	18.13KB	5.39KB
auth (PreviewBanner.js)	0.90KB	0.50KB
auth (RegisterForm.js)	6.64KB	2.21KB
auth (SocialSignInButtons.js)	9.60KB	3.89KB
auth (UserMenu.js)	3.40KB	1.22KB
auth (auth-gate-events.js)	1.29KB	0.66KB
auth (authStyles.js)	5.04KB	1.72KB
auth (createAuthClient.js)	35.76KB	9.11KB
auth (createAuthenticatedFetch.js)	4.37KB	1.69KB
auth (index.js)	2.35KB	1.07KB
auth (org-roles.js)	6.66KB	2.78KB
auth (phone-identifier.js)	1.11KB	0.66KB
auth (types.js)	0.59KB	0.35KB
auth (useAuth.js)	4.91KB	0.87KB
auth (useIsWorkspaceAdmin.js)	1.61KB	0.85KB
collaboration (CommentThread.js)	26.07KB	7.56KB
collaboration (LiveCursors.js)	3.17KB	1.27KB
collaboration (PresenceAvatars.js)	6.49KB	2.64KB
collaboration (PresenceProvider.js)	2.79KB	1.13KB
collaboration (index.js)	1.65KB	0.73KB
collaboration (useCollaborationTranslation.js)	6.05KB	2.52KB
collaboration (useCommentSearch.js)	1.98KB	0.88KB
collaboration (useConflictResolution.js)	7.75KB	1.86KB
collaboration (useMentionNotifications.js)	1.81KB	0.68KB
collaboration (usePresence.js)	6.33KB	1.84KB
collaboration (useRealtimeSubscription.js)	7.91KB	2.01KB
components (index.js)	489.12KB	108.41KB
core (index.js)	3.04KB	1.15KB
create-plugin (index.js)	10.08KB	3.26KB
data-objectstack (index.js)	150.04KB	39.79KB
fields (index.js)	228.37KB	56.62KB
i18n (LocalizationContext.js)	1.76KB	0.96KB
i18n (currency.js)	1.22KB	0.64KB
i18n (i18n.js)	4.32KB	1.77KB
i18n (index.js)	3.35KB	1.38KB
i18n (pickLocalized.js)	1.70KB	0.83KB
i18n (provider.js)	23.12KB	7.62KB
i18n (useDisplayLocale.js)	2.33KB	1.20KB
i18n (useObjectLabel.js)	27.59KB	6.63KB
i18n (useSafeTranslation.js)	4.52KB	1.96KB
layout (index.js)	38.98KB	10.85KB
mobile (MobileProvider.js)	0.92KB	0.49KB
mobile (ResponsiveContainer.js)	0.94KB	0.38KB
mobile (breakpoints.js)	1.51KB	0.70KB
mobile (createOfflineDataSource.js)	5.61KB	1.74KB
mobile (index.js)	1.50KB	0.62KB
mobile (offlineQueue.js)	3.91KB	1.35KB
mobile (pwa.js)	0.97KB	0.49KB
mobile (serviceWorker.js)	1.48KB	0.62KB
mobile (serviceWorkerSource.js)	3.41KB	1.48KB
mobile (useBreakpoint.js)	1.54KB	0.65KB
mobile (useGesture.js)	6.96KB	1.98KB
mobile (useOfflineSync.js)	1.99KB	0.72KB
mobile (usePullToRefresh.js)	2.53KB	0.85KB
mobile (useResponsive.js)	0.71KB	0.42KB
mobile (useResponsiveConfig.js)	1.36KB	0.63KB
mobile (useSpecGesture.js)	4.32KB	1.64KB
mobile (useTouchTarget.js)	1.01KB	0.54KB
permissions (MePermissionsProvider.js)	8.75KB	3.06KB
permissions (PermissionContext.js)	0.31KB	0.25KB
permissions (PermissionGuard.js)	0.89KB	0.45KB
permissions (PermissionProvider.js)	3.67KB	1.12KB
permissions (evaluator.js)	4.41KB	1.44KB
permissions (index.js)	0.91KB	0.41KB
permissions (store.js)	0.91KB	0.42KB
permissions (useFieldPermissions.js)	1.28KB	0.52KB
permissions (usePermissions.js)	1.55KB	0.71KB
plugin-ai (index.js)	15.71KB	3.79KB
plugin-calendar (index.js)	45.23KB	12.45KB
plugin-charts (index.js)	62.18KB	17.67KB
plugin-chatbot (index.js)	180.33KB	42.79KB
plugin-dashboard (index.js)	121.60KB	31.63KB
plugin-designer (index.js)	210.91KB	42.67KB
plugin-detail (index.js)	238.95KB	59.76KB
plugin-editor (index.js)	2.46KB	1.10KB
plugin-form (index.js)	114.58KB	27.68KB
plugin-gantt (index.js)	164.14KB	39.98KB
plugin-grid (index.js)	188.00KB	49.94KB
plugin-kanban (index.js)	48.60KB	13.41KB
plugin-list (index.js)	110.10KB	26.74KB
plugin-map (index.js)	18.05KB	5.80KB
plugin-markdown (index.js)	13.72KB	4.69KB
plugin-report (index.js)	40.60KB	10.58KB
plugin-timeline (index.js)	26.21KB	7.52KB
plugin-tree (index.js)	8.50KB	2.88KB
plugin-view (index.js)	84.03KB	20.55KB
providers (DataSourceProvider.js)	0.75KB	0.39KB
providers (MetadataProvider.js)	1.37KB	0.59KB
providers (ThemeProvider.js)	1.90KB	0.85KB
providers (UploadProvider.js)	11.71KB	3.53KB
providers (index.js)	0.44KB	0.22KB
providers (types.js)	0.01KB	0.04KB
react-runtime (index.js)	5.67KB	2.37KB
react (LazyPluginLoader.js)	3.77KB	1.33KB
react (SchemaRenderer.js)	23.71KB	7.96KB
react (data-invalidation.js)	5.05KB	2.08KB
react (index.js)	1.23KB	0.66KB
react (spec-input.js)	0.20KB	0.18KB
sdui-parser (codegen.js)	4.09KB	1.74KB
sdui-parser (index.js)	4.47KB	2.03KB
sdui-parser (parse.js)	10.04KB	2.82KB
sdui-parser (types.js)	0.29KB	0.24KB
sdui-parser (validate.js)	4.69KB	1.48KB
types (ai.js)	0.20KB	0.17KB
types (api-types.js)	0.20KB	0.18KB
types (app.js)	2.87KB	0.99KB
types (base.js)	0.20KB	0.18KB
types (blocks.js)	0.20KB	0.18KB
types (complex.js)	0.20KB	0.18KB
types (crud.js)	0.20KB	0.18KB
types (dashboard-filter-alias.js)	6.23KB	2.74KB
types (data-display.js)	0.20KB	0.18KB
types (data-protocol.js)	0.20KB	0.19KB
types (data.js)	0.20KB	0.18KB
types (designer.js)	1.87KB	0.85KB
types (disclosure.js)	0.20KB	0.18KB
types (error-code.js)	1.54KB	0.88KB
types (feedback.js)	0.20KB	0.18KB
types (field-types.js)	0.20KB	0.18KB
types (form.js)	0.20KB	0.18KB
types (http-retry.js)	4.32KB	2.02KB
types (index.js)	3.05KB	1.52KB
types (layout.js)	0.20KB	0.18KB
types (managed-by.js)	0.19KB	0.18KB
types (mobile.js)	2.59KB	1.31KB
types (navigation.js)	0.20KB	0.18KB
types (objectql.js)	0.20KB	0.18KB
types (overlay.js)	0.20KB	0.18KB
types (permissions.js)	0.20KB	0.18KB
types (plugin-scope.js)	0.20KB	0.18KB
types (record-components.js)	0.20KB	0.19KB
types (record-semantics.js)	1.28KB	0.67KB
types (registry.js)	0.20KB	0.18KB
types (reports.js)	0.20KB	0.18KB
types (spec-report.js)	5.05KB	1.93KB
types (system-fields.js)	3.33KB	1.54KB
types (theme.js)	0.20KB	0.18KB
types (ui-action.js)	3.40KB	1.71KB
types (views.js)	0.20KB	0.18KB
types (widget.js)	0.20KB	0.18KB

Size Limits

• ✅ Core packages should be < 50KB gzipped
• ✅ Component packages should be < 100KB gzipped
• ⚠️ Plugin packages should be < 150KB gzipped