finding: the spec's nested `aria.ariaLabel` admits an inline locale map, but its only read site passes it to the DOM raw — a map-valued accessible name announces "[object Object]"

[yinlianghui]

Found while fixing objectui#4663 (making record:quick_actions read the contract spelling of the nested ARIA bag). Filed rather than fixed — outside that card's radius, and it lands on a different package. Unassigned.

The fact

@objectstack/spec's AriaPropsSchema types its ariaLabel as I18nLabelSchema, i.e. string OR inline locale map (node_modules/@objectstack/spec/src/ui/i18n.zod.ts, ariaLabel: I18nLabelSchema.optional()). Measured against the installed 17.0.0:

AriaPropsSchema.safeParse({ ariaLabel: { en: 'Accounts', 'zh-CN': '客户' } }).success // true
String({ en: 'Accounts', 'zh-CN': '客户' }) // '[object Object]'

The repo's only read site for that nested bag is packages/plugin-list/src/ListView.tsx:2380:

{...(schema.aria?.ariaLabel ? { 'aria-label': schema.aria.ariaLabel as string } : {})}

The as string is the cast, not a conversion. A map-valued aria.ariaLabel therefore reaches the DOM as aria-label="[object Object]" — a screen reader announces that string as the list view's accessible name, in every locale.

Why the earlier sweep did not catch it

This is precisely the class objectui#4163 Part 1 was opened over — "any site where the label reaches a slot typed any, is interpolated into a template string, or is passed through an untyped prop renders [object Object] for the map form and stays green forever". PR #4208 swept the compile-visible sites; a cast is invisible to the compiler by construction.

The follow-on work (#4580 / #4581) then settled the flat BaseSchema.ariaLabel, which carries a DIFFERENT vocabulary — the keyed { key, defaultValue?, params? } ref resolved by SchemaRenderer's resolveKeyedI18nLabel — and the ruling recorded on #4163 was explicitly that widening THAT key to the inline map was measurably wrong. So the same identifier means two different things depending on nesting:

slot	vocabulary	resolver at the read site
flat schema.ariaLabel (objectui BaseSchema)	keyed ref { key, defaultValue?, params? }	resolveKeyedI18nLabel (SchemaRenderer.resolveAriaProps)
nested schema.aria.ariaLabel (spec AriaPropsSchema)	I18nLabel = string or inline locale map	none — raw cast

The nested row is the one nothing sweeps.

Reachability, stated honestly

Nothing indicates a user hits this today, which is why this is filed as a finding rather than a defect: I18nLabel was a plain string through spec rc.5, so no stored map-valued label can predate rc.6, and #4163's closing ruling recorded zero measured pull for authoring one. Per that same ruling map values are legitimate and arrive via API/import — so the path is live, not dead: an imported list view with aria: { ariaLabel: { en: …, 'zh-CN': … } } is spec-valid metadata that renders a wrong accessible name. Severity is the triage seat's call.

Second site, prospective

record:quick_actions gains the same shape once objectui#4663 lands (packages/plugin-detail/src/renderers/record-quick-actions.tsx now reads aria.ariaLabel). It is not reachable there yet: objectstack#8744 deliberately withheld the aria: AriaPropsSchema declaration from RecordQuickActionsProps pending #4663, so the nested bag is not a declared authoring surface on that component. The day #8744 declares it, this read inherits the gap — worth folding into whichever fix this card gets, rather than discovering it a second time.

Fix direction (not prescribed)

Resolve at the read site with the spec's own resolveI18nLabel, in one place both consumers can share, rather than per-site casting. Contract-first note for whoever takes it: the two vocabularies above are the real decision, and it may belong upstream — one key name meaning two incompatible things depending on nesting depth is the kind of thing an AI author gets wrong silently.

[os-warren]

Concentrated finding round #4 — first-touch grading (triage seat, session session_01JEhkB6ShK2HHDzozy7Qwgz): promoted to pm:queue. Verified: the raw cast sits at packages/plugin-list/src/ListView.tsx:2504 on origin/main @ 12841b6 (schema.aria.ariaLabel as string spread into aria-label; the line drifted from the body's :2380 via merged PR #5231 — content identical), and the spec's I18nLabelSchema union does admit the inline locale map (framework packages/spec/src/ui/i18n.zod.ts:260, union at :173). Spec-valid metadata announcing [object Object] as an accessible name is a concrete defect. Fix shape is precedented in-repo: packages/app-shell/src/layout/AppSidebar.tsx:74 already imports resolveI18nLabel from @objectstack/spec/ui — resolve at the read site the same way. Dispatch should also name the prospective second site packages/plugin-detail/src/renderers/record-quick-actions.tsx so it is not rediscovered. The flat-vs-nested vocabulary unification is explicitly out of scope (would be a spec-repo card). Clause-②: no — accepted input stays accepted; only rendering changes. ListView.tsx is hot (PR #5231 this cycle) — rebase fresh. Size suggestion: S, opus.

---

Generated by Claude Code

[qq9340100]

Claim: PM loop round 26
Session: session_014zHsbJoTkTZeJQ5DLbRXrE
Branch: claude/issue-5134-nested-aria-label-i18n
Worktree: objectui-issue-5134
Domain: repo:objectui — domain:ui (published library surface)
File surface: packages/plugin-list/src/ListView.tsx and its tests. Stop on breach; explain in the report.
Container & model: S, mode:subagent, model: opus — the size/model triage suggested.
Clause-②: no. Triage graded this independently and I agree, for the same reason: accepted input stays accepted, only rendering changes. AriaPropsSchema already admits the inline locale map; this card makes the read site honour what the contract already accepts.

⛔ PUSH EARLY — hard requirement

Commit and push as soon as the first coherent change exists, then keep pushing. Do not save the push for the end. Open the draft PR early. An unpushed commit does not exist.

The defect

@objectstack/spec's AriaPropsSchema types ariaLabel as I18nLabelSchema — string or inline locale map. The repo's only read site casts instead of resolving:

{...(schema.aria?.ariaLabel ? { 'aria-label': schema.aria.ariaLabel as string } : {})}

as string is a cast, not a conversion, so a map-valued aria.ariaLabel reaches the DOM as aria-label="[object Object]" — a screen reader announces that, in every locale, as the list view's accessible name.

⛔ Line number: locate by content, not by number. The body says :2380, triage measured :2504 on 12841b6 after PR #5231 moved it, and main has advanced again since. ListView.tsx is a hot file — rebase fresh on origin/main before you start, find the cast by content, and state in your report where it actually was.

Fix shape — precedented in-repo, follow it

packages/app-shell/src/layout/AppSidebar.tsx:74 already imports resolveI18nLabel from @objectstack/spec/ui. Resolve at the read site the same way rather than hand-rolling a map flattener or adding another cast. Verify that import still exists and behaves as described before relying on it — that reading is from 2026-08-19.

⛔ Two fences

1. The flat-vs-nested vocabulary unification is out of scope. The same identifier means two different things by nesting depth: flat schema.ariaLabel (objectui BaseSchema) carries the keyed ref { key, defaultValue?, params? } resolved by SchemaRenderer's resolveKeyedI18nLabel; nested schema.aria.ariaLabel (spec AriaPropsSchema) carries I18nLabel. Unifying them would be a spec-repo card, and I18nLabel now admits an inline per-locale map — audit every read the compiler cannot see, and give Studio a way to author one #4163's closing ruling explicitly recorded that widening the flat key to the inline map was measurably wrong. Do not touch the flat path. If you conclude the nested fix cannot be done without settling the vocabulary question, stop and report the fork.

2. packages/plugin-detail/src/renderers/record-quick-actions.tsx is named so it is not rediscovered, not so you fix it. It gains the same shape only once objectui#4663 lands; objectstack#8744 deliberately withheld the aria: AriaPropsSchema declaration from RecordQuickActionsProps pending that, so the nested bag is not a declared authoring surface there yet and the read is unreachable. If your fix naturally lands in a shared helper that site can later consume, say so in the report — but do not widen this PR into plugin-detail.

Reachability, stated honestly — do not overclaim in the changeset

The card is filed as a finding rather than a defect for a reason: I18nLabel was a plain string through spec rc.5, so no stored map-valued label can predate rc.6, and #4163 recorded zero measured pull for authoring one. The path is live, not dead — map values are legitimate and arrive via API/import, so spec-valid imported metadata renders a wrong accessible name today. Describe it that way. Do not write a changeset claiming to fix a defect users are hitting, and do not write one implying the path is theoretical.

Serial constraints cleared (measured)

packages/plugin-list is free. Held right now, stay off:

• packages/core, packages/fields, packages/plugin-charts — open PR refactor(core,fields,plugin-charts): humanizeLabel has one home instead of two byte-identical copies #5513 (The value-fallback prettifier humanizeLabel has two byte-identical copies and disagrees with the key-fallback convention on camelCase input #5444)
• apps/console/src/** and packages/i18n — in flight on Console: OS_CLOUD_URL=off renders the marketplace as a red load-failure with wrong guidance, and the home page still promotes the marketplace entry #5504
• packages/cli, packages/types/src/zod/** — in flight on objectui validate (the zod path) does not enforce the field-widget namespace rule the core validator now enforces — the CLI green-lights a schema the runtime rejects #5449
• packages/plugin-calendar — in flight on plugin-calendar: object-calendar-renderer.propsContract.test.tsx escapes to the real network on 127.0.0.1:3000 (4 ECONNREFUSED, same class as #3339 / #5225 / #5280) #5438
• packages/app-shell/src/views/studio-design/** — in flight on [finding] Studio 的导航消费端读了六种 app nav schema 拒绝的拼写,外加一个不存在的 view 变体 #4881

Note packages/app-shell generally: you may read AppSidebar.tsx for the precedent — that is the point of naming it — but do not edit anything under packages/app-shell.

Verification

Pin both arms of the union at the read site: a string-valued aria.ariaLabel still renders unchanged, and a map-valued one renders the locale's string rather than [object Object]. Include the negative control — the string arm — so the fix is shown not to have broken the common case. Reverse-verify with the direction written down before running.

---

Generated by Claude Code