You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 7d0b47c
Browse filesBrowse the repository at this point in the historyBrowse files
feat(spec): an action param's helpText takes an inline locale map, so an inline action can write its hint per locale (#31485)
<!-- claude-projects-attribution: {"github_login":"os-zhuang"} -->
_Requested by **Sam** · [project
thread](https://claude.ai/code/project/chan_01GsBogozeZG5sdpAARrN7HP?thread=cmsg_01GsBogozeZG5sdpAARrN7HP5HtnZiicdy84BcZoZeHwXZ)_Fixes#28266
Clause-②: yes (widening)
Metadata-protocol: added
Skills-docs: follow-up owed — skills/objectstack-ui/rules/actions.md
(its copy-holes line teaches a param's `helpText` as a sentence only;
`skills/**` is a Tier H surface, so it is not edited here). This diff
teaches the map in `content/docs/protocol/objectui/actions.mdx` (the
`ActionParam` fields paragraph) and in the regenerated
`content/docs/references/ui/action.mdx`.
## 维护者速读
- 改了什么:动作参数的 `helpText`(参数对话框里输入框下方的说明)现在可以写成按语言的内联映射 `{ en, "zh-CN", …
}`,和它旁边的 `label`、`description`、`successMessage` 一样。校验门、控制台解析器和 AI
工具摘要都会按语言读取它。
- 为什么改:cloud
欢迎页的「邀请成员」是页面按钮上的内联动作,没有翻译包可走,标题、说明、选项和提示都写成了多语言映射,唯独角色说明只能是一个英文字符串,所以
cloud 只好把它省掉。注册在对象上的 `invite_user` 本来就经翻译包本地化(7 种语言都已翻好),不需要改。
- 风险与回滚:只放宽接受集,以前能解析的值解析结果不变;回滚即撤销本 PR。
- 先看:`packages/spec/src/ui/action.zod.ts`(`actionParamHelpText` 加上
`localeMap`)、`ui/packages/fields/src/resolveActionParams.ts`(`authoredHelpText`)、`packages/lint/src/validate-action-copy-templates.ts`(逐个语言判句)。
- 两分钟验证:`pnpm --filter @objectstack/spec exec vitest run
src/ui/action-copy-template.test.ts`,预期全部通过,其中 helpText 一行是 “keeps
inline locale map”。
- 需要你做的:无,席位落地。
## What changes
- **`@objectstack/spec` — `ActionParamSchema.helpText` takes an inline
locale map.** `actionParamHelpText` builds the copy family's slot with
`{ localeMap: true }`, the option `description`, `confirmText`,
`successMessage` and each `outcomeMessages` entry already pass. The slot
now accepts a bare sentence, the `{ dialect: 'template', source }`
envelope, a blank string (stored rows keep loading) or an
`InlineLocaleMapSchema` map. It reaches both carriers of `params`:
`ActionSchema` and `InlineActionSchema` (a page button's
`properties.action`). Every value that parsed before parses to the same
thing. A map whose key is not a language tag is refused with the slot's
own sentence, which now also names the map form.
- **`@objectstack/lint` — the copy door judges each map entry.**
`validate-action-copy-templates.ts` dropped the `key !== 'helpText'`
exclusion, so a `helpText` map's entries are judged as sentences at
`params[N].helpText.LOCALE`, exactly as a `description` map's are
(blank, `${…}`, single-brace token, a hole over a root other than
`record`, logic in a hole, unknown formatter: each an error). The i18n
walk already files a map as authored text (`authoredEvidence`); only its
doc comment changed.
- **`@objectstack/runtime` — the agent-facing tool schema reads a map.**
`summarizeActionParams` reads `helpText` through a new `paramHelpText`:
the string or envelope `source` first, else the map's source-language
entry through `resolveI18nLabel` (`en`, then `default`, then any entry).
An envelope with no `source` still gives nothing, so the bound field's
description stays the fallback.
- **`@object-ui/fields` — the console resolves a map for the active
language.** `resolveActionParam` narrows `helpText` like `label`: the
envelope's `source`, else `resolveI18nLabel(helpText, ctx.locale)`.
Before, `actionCopySource(map)` answered `undefined`, so a map fell
through to the field's help line. The three branches (inline, unresolved
field-backed, field-backed) read the one `authoredHelpText`.
- **Docs.** `content/docs/protocol/objectui/actions.mdx` says a param's
`helpText` is a sentence translated at
`objects.OBJECT._actions.ACTION.params.PARAM.helpText` or an inline
locale map, and that the map is how a page button's inline action
translates it. `content/docs/references/ui/action.mdx` is regenerated
(`gen:docs`).
### Premise reading (the card's facts, re-measured on `main` f67f3b3)
- The card says the spec "types action param `helpText` as `string`, so
there is no i18n key or per-locale form". The **i18n key exists**:
`TranslationItemSchema` declares `_actions.ACTION.params.PARAM.helpText`
(`packages/spec/src/system/translation.zod.ts`), the walk emits it
(`packages/lint/src/i18n-walk.ts`, `pushActionParams`),
`translateActionParams` overlays it server-side
(`packages/spec/src/system/i18n-resolver.ts`), and the console overlays
it through `actionParamText` (`useConsoleActionRuntime.tsx`,
`RecordDetailView.tsx`).
- The card's Work item 2 ("translate the `invite_user` role help in the
locale packs") is **already done**: the role help
(`MEMBERSHIP_ROLE_PARAM_HELP`) sits at 6 sites in
`en.objects.generated.ts` (the four `invite_user` mirrors,
`sys_member.add_member`, `sys_member.update_member_role`), and each of
`ar`, `es-ES`, `fr`, `ja-JP`, `pt-BR`, `zh-CN`, `zh-Hant` carries a
translated 5-line help at all 6, with 0 English left. So a zh session on
the organization page's registered `invite_user` already reads the role
help in Chinese.
- The **per-locale form was the real gap**: `helpText` was the one copy
slot built without `localeMap` (pinned as "takes no inline locale map"
in `action-copy-template.test.ts`). The card's consumer, cloud's welcome
page, declares the invitation as an inline `element:button` action with
no bundle, writes its label, description, option labels and toast as
maps, and leaves `helpText` out on purpose
(`packages/service-tenant/src/pages/welcome.page.test.ts`, the comment
above `withoutOwner`). This PR closes that gap.
## Tests
- `packages/spec/src/ui/action-copy-template.test.ts`: the family
table's `params[].helpText` row flips to "keeps inline locale map" (the
map parses and is kept; the refusal sentence names the map form); a new
describe pins `InlineActionSchema` keeping a field-backed role param's
map and refusing a `{ key, defaultValue }` map with the slot's sentence.
- `packages/lint/src/validate-action-copy-templates.test.ts`: a map
passes; a `${…}` entry and a blank entry are errors at
`params[0].helpText.zh-CN` / `.ja-JP` on a registered action; a `result`
hole in a page button's inline action map is an error at `· action
params[0].helpText.zh-CN`.
- `packages/cli/test/i18n-inline-locale-map-coverage.test.ts`: the walk
records a `helpText` map at its param key with `inlineLocales`, counts
its locales as covered, reports the locale a partial map omits, and
scaffolds no bundle row.
- `packages/runtime/src/action-param-help-envelope-27948.test.ts`: a map
gives its `en` entry (same summary as the bare string), a map with no
`en` gives `default`, an empty map falls back to the field description.
-
`ui/packages/app-shell/src/views/ActionParamDialog.fieldHelpLine-12213.test.tsx`:
a zh-CN session draws the map's zh-CN entry under the control, over the
field's help; an inline param in a locale the map omits reads `en`; an
envelope with no `source` still lends the field's help.
<details><summary>Local runs (worktree off main f67f3b3, merged with
main c6c2426; final head ea6ad0b)</summary>
- `pnpm --filter @objectstack/spec build` → VERDICT command-exit 0.
- `pnpm --filter @objectstack/spec test` (head 87e9040, before the main
merge; spec did not move on main) → Test Files 822 passed, Tests 26,010
passed, 1 todo.
- Targeted, on the final head ea6ad0b: spec `action-copy-template` +
`action` + `i18n-resolver` 701/701; lint
`validate-action-copy-templates` 26/26; runtime
`action-param-help-envelope-27948` 4/4; cli
`i18n-inline-locale-map-coverage` 20/20; ui
`ActionParamDialog.fieldHelpLine-12213` +
`ActionParamDialog.recordHoles-12967` 13/13.
- Earlier on 87e9040: lint `validate-action-copy-templates` +
`validate-translation-references` 259/259; ui `packages/fields/` whole +
six ActionParamDialog / useConsoleActionRuntime / RecordDetailView files
→ Test Files 306 passed, 1 skipped; Tests 4,640 passed, 7 skipped.
- `pnpm --filter @objectstack/lint typecheck`, `pnpm --filter
@objectstack/runtime typecheck` → exit 0 (both include
`check:test-typecheck`). `pnpm --filter @objectstack/spec
check:test-typecheck` → OK (52 files / 240 errors / 131 pinned
signatures held). `pnpm --filter @object-ui/fields type-check` (both its
programs) → exit 0 after building its dependency closure.
`@object-ui/app-shell` type-check (the new dialog cases) is left to
`Type Check UI`.
</details>
<details><summary>Ablations (each mutation through
`scripts/ablation-replace.mjs`, anchor 1 → 0, restored to the HEAD blob
with `git diff HEAD` empty; every subject resolves through source — a
relative import or the ui vitest alias — so no dist leg)</summary>
- A1 spec, `actionParamHelpText` built without `localeMap` →
`action-copy-template.test.ts` 2 failed / 32 passed: the family row
"params[].helpText: keeps inline locale map" and "an inline action …
keeping the map".
- A2 lint, `sentencesOf(value, localeMap && key !== 'helpText')` →
`validate-action-copy-templates.test.ts` 1 failed / 25 passed: "passes a
helpText locale map and judges each entry at `.LOCALE`".
- A3 runtime, `paramHelpText` map branch returns `undefined` → 2 failed
/ 2 passed: both #28266 cases; the two #27948 envelope cases stay green.
- A4 console, `authoredHelpText` read through `actionCopySource` again →
`ActionParamDialog.fieldHelpLine-12213.test.tsx` 2 failed / 8 passed:
the zh-CN and the inline-param map cases; the envelope-with-no-source
control stays green.
</details>
## Acceptance notes
- **cloud follow-up (carrier: cloud).** The welcome page's
`INVITE_ACTION` can carry the role help as a 4-locale map (`en`,
`zh-CN`, `ja-JP`, `es-ES`, copied from the framework bundles like its
other copy) once a cloud pin round carries this PR;
`welcome.page.test.ts` then compares it to the bundles instead of
leaving it out. That is the card's "a zh session sees the role help in
Chinese" on the welcome page.
- **`summarizeActionParams` reads a param `label` map as absent
(observation, not fixed here).** `typeof p.label === 'string' ? p.label
: field?.label` gives an inline param with a map label no label in the
agent-facing tool schema. Same call site, different key, pre-existing;
left for its own card.
- **`ActionParamLike.helpText` (`i18n-resolver.ts`) stays typed `string
| envelope`,** like its sibling `ActionLike.description`, which also
takes a map and is typed the same way. `translateActionParams` passes an
authored map through unchanged when no bundle sentence exists, as it
does for `description`. Widening both interface types together is a
separate, API-surface change.
- `check-plugin-teardown-shape --self-test` cannot run on this shallow
clone (its positive control is pinned to commit 621a487); NOT MEASURED
locally, CI runs it on a full clone.
## Verification
<details><summary>Gates</summary>
- Derived with `node scripts/pm/dispatch-gates.mjs --commands` at
87e9040 (14 paths vs merge base f67f3b3): 118 families. Run
sequentially: 114 exited 0 on the first pass. `check:i18n-walk-parity`
exited 3 (workspace CLI not built) and exited 0 after building the CLI
closure. Eight gates that overlapped an ablation's mutation window were
re-run on the restored tree: all 0.
- NOT MEASURED locally (exit 3, prerequisite, nothing read):
`check-plugin-teardown-shape --self-test` (positive control pinned to
621a487, unreachable on this shallow clone), `@objectstack/spec
check:skill-examples` (needs `packages/client-react/dist`),
`check:dual-build-cjs-loads` (needs every package's `dist/`). CI runs
all three. `dispatch-gates --ran` → 118 derived, 115 run, 3 UNRUN (those
three).
- `pnpm --filter @objectstack/spec check:generated`: `check:docs` was
stale (regenerated with `gen:docs`, committed); every other artifact up
to date. Its `check:test-typecheck` leg died without diagnostics under
the shared box's memory, and passed run alone with a 6 GB heap.
- i18n: `pnpm check:i18n` → OK (10 packages, all bundles in sync); `pnpm
check:i18n-coverage` → OK (14 configs, 426 baselined untranslated, none
new); `pnpm check:i18n-walk-parity` → OK (16 declared groups, 14 walked,
2 exempted).
- Repo-wide `pnpm lint` and the full battery are CI's.
</details>
## Human Minimum
- [x] 1. Schemas start as Zod; `packages/spec` holds no runtime logic.
- [x] 2. Every name I added uses the casing for its kind.
- [x] 3. No formatter ran; `pnpm lint` passes (CI-owned repo scan).
- [x] 4. One issue, one branch off an up-to-date `main`, one pull
request.
- [x] 5. A change that publishes carries a changeset, and both
declaration lines are filled in here and in the changeset.
- [x] 6. `packages/spec` touched: its generated artifacts are
regenerated and committed.
- [x] 7. No hand edits to `content/docs/references/`,
`packages/*/CHANGELOG.md` or `content/docs/releases/`.
- [x] 8. Title, body and comments are in English.
---
_Generated by [Claude
Code](https://claude.ai/code/session_01QUs3Bt3CmnAuRftY9mRSs2)_
---------
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: objectstack-fleet[bot] <332303061+objectstack-fleet[bot]@users.noreply.github.com>
feat(spec): an action param's `helpText` takes an inline locale map, so an inline action can write its param hint per locale
9
+
10
+
Clause-②: yes (widening)
11
+
Metadata-protocol: added
12
+
13
+
-**`@objectstack/spec`: `ActionParamSchema.helpText`** accepts an inline locale map (`{ en: 'Why the account is paused', 'zh-CN': '暂停该账户的原因' }`) beside the bare sentence and the `{ dialect: 'template', source }` envelope, the same three forms `description`, `confirmText`, `successMessage` and each `outcomeMessages` entry already take. It reaches every action that carries params: a registered action (`ActionSchema.params`) and a page button's inline `action` (`InlineActionSchema`). A registered action's hint is still translated through the bundle at `objects.<object>._actions.<action>.params.<param>.helpText`; the map is the form for an inline action, which no bundle reaches. Before, a page that wrote its dialog's title, line, option labels and toast as locale maps had to leave the hint out or show it in one language. Every value that parsed before parses to the same thing. A map key that is not a language tag is refused with the slot's own sentence.
14
+
-**`@objectstack/lint`:**`os validate`, `compile` and the publish gate judge each entry of a `helpText` map as a sentence, named at `params[N].helpText.<locale>`, the way they judge a `description` map: a blank entry, a `${…}` or single-brace token, a hole over a root the dialog does not bind (`record` only), logic in a hole or an unknown formatter is an error. `os i18n extract` records the map as authored text (its locales count as covered, a locale it omits is reported) and scaffolds no bundle row for it.
15
+
-**`@objectstack/runtime`:** the agent-facing tool schema (`summarizeActionParams`, read by the MCP action tools) reads a `helpText` map's source-language entry (`en`, then `default`, then any entry) instead of falling back to the bound field's description.
16
+
-**`@object-ui/fields`:**`resolveActionParams` resolves a `helpText` map for the active language with the same order as `label`, so the param dialog draws the viewer's language. A map no longer falls through to the field's help line; an envelope with no `source` still does.
17
+
18
+
Callers that read `helpText` and may now see a map: the console's `resolveActionParams` (handled here), the runtime's `summarizeActionParams` (handled here), the lint copy door and the i18n walk (handled here), and the server-side `translateAction`, which overlays a bundle sentence when one exists and otherwise passes the authored value through unchanged, as it does for a `description` map.
Copy file name to clipboardExpand all lines: content/docs/protocol/objectui/actions.mdx
+2Lines changed: 2 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -516,6 +516,8 @@ params:
516
516
517
517
`ActionParam` fields: `name`, `field`, `objectOverride`, `label`, `type`, `required` (default `false`), `options`, `placeholder`, `helpText`, `defaultValue`, `defaultFromRow`, `visible` (CEL predicate — the dialog omits the param when false), `requiresFeature` (capability gate, lowered into `visible` — see [Capability gates](#capability-gates-requiresfeature)).
518
518
519
+
A param's `helpText` is the hint under its input. Write it as a sentence, translated at `objects.<object>._actions.<action>.params.<param>.helpText` (`globalActions.<action>.params.<param>.helpText` for an action with no `objectName`), or as an inline locale map (`helpText: { en: 'Why the account is paused', 'zh-CN': '暂停该账户的原因' }`), the same two forms `label` takes. A page button's inline `action` has no translation key, so the locale map is the way to translate its hint. Either form may hold `{{ record.* }}` holes.
520
+
519
521
### Naming the submit button: `submitText`
520
522
521
523
An action with `params` collects them in a dialog whose submit button says **Confirm**. `submitText` gives that button the action's own verb, so a send-email action can say **Send** and a log-call action **Log Call**. The dialog's other copy stays where it was: the title is the action's `label`, and the line under it is `description`.
|**helpText**|`string \| { dialect: 'template'; source?: string; ast?: any; meta?: object } \| string`| optional | Hint shown under this input in the action's param dialog — a `template` slot (ADR-0032): a bare string is shorthand for `{ dialect: 'template', source }`, and text with no hole is shown as written. Holes are `{{ path }}` or `{{ path \| formatter[:arg] }}` over `record`, the record the action runs against; the dialog's own values are not bound. Formatters come from the template engine's whitelist (`TEMPLATE_FORMATTERS`, `@objectstack/formula`); a hole holds no logic (no CEL, no arithmetic). Example: 'Why `{{ record.name }}` is paused'. A hole over any other root, a `${…}` or single-brace `{x}` token (each named with its `{{ }}` spelling), a hole holding logic or an unknown formatter, and a blank sentence are named and refused at `objectstack validate`, `compile` and the publish gate; the text still parses, so a stored one loads until its next save. |
149
+
|**helpText**|`string \| { dialect: 'template'; source?: string; ast?: any; meta?: object } \| string \| Record<string, string>`| optional | Hint shown under this input in the action's param dialog — a `template` slot (ADR-0032): a bare string is shorthand for `{ dialect: 'template', source }`, and text with no hole is shown as written. Holes are `{{ path }}` or `{{ path \| formatter[:arg] }}` over `record`, the record the action runs against; the dialog's own values are not bound. Formatters come from the template engine's whitelist (`TEMPLATE_FORMATTERS`, `@objectstack/formula`); a hole holds no logic (no CEL, no arithmetic). Example: 'Why `{{ record.name }}` is paused'. A hole over any other root, a `${…}` or single-brace `{x}` token (each named with its `{{ }}` spelling), a hole holding logic or an unknown formatter, and a blank sentence are named and refused at `objectstack validate`, `compile` and the publish gate; the text still parses, so a stored one loads until its next save. |
|**helpText**|`string \| { dialect: 'template'; source?: string; ast?: any; meta?: object } \| string`| optional | Hint shown under this input in the action's param dialog — a `template` slot (ADR-0032): a bare string is shorthand for `{ dialect: 'template', source }`, and text with no hole is shown as written. Holes are `{{ path }}` or `{{ path \| formatter[:arg] }}` over `record`, the record the action runs against; the dialog's own values are not bound. Formatters come from the template engine's whitelist (`TEMPLATE_FORMATTERS`, `@objectstack/formula`); a hole holds no logic (no CEL, no arithmetic). Example: 'Why `{{ record.name }}` is paused'. A hole over any other root, a `${…}` or single-brace `{x}` token (each named with its `{{ }}` spelling), a hole holding logic or an unknown formatter, and a blank sentence are named and refused at `objectstack validate`, `compile` and the publish gate; the text still parses, so a stored one loads until its next save. |
243
+
|**helpText**|`string \| { dialect: 'template'; source?: string; ast?: any; meta?: object } \| string \| Record<string, string>`| optional | Hint shown under this input in the action's param dialog — a `template` slot (ADR-0032): a bare string is shorthand for `{ dialect: 'template', source }`, and text with no hole is shown as written. Holes are `{{ path }}` or `{{ path \| formatter[:arg] }}` over `record`, the record the action runs against; the dialog's own values are not bound. Formatters come from the template engine's whitelist (`TEMPLATE_FORMATTERS`, `@objectstack/formula`); a hole holds no logic (no CEL, no arithmetic). Example: 'Why `{{ record.name }}` is paused'. A hole over any other root, a `${…}` or single-brace `{x}` token (each named with its `{{ }}` spelling), a hole holding logic or an unknown formatter, and a blank sentence are named and refused at `objectstack validate`, `compile` and the publish gate; the text still parses, so a stored one loads until its next save. |
|**helpText**|`string \| { dialect: 'template'; source?: string; ast?: any; meta?: object } \| string`| optional | Hint shown under this input in the action's param dialog — a `template` slot (ADR-0032): a bare string is shorthand for `{ dialect: 'template', source }`, and text with no hole is shown as written. Holes are `{{ path }}` or `{{ path \| formatter[:arg] }}` over `record`, the record the action runs against; the dialog's own values are not bound. Formatters come from the template engine's whitelist (`TEMPLATE_FORMATTERS`, `@objectstack/formula`); a hole holds no logic (no CEL, no arithmetic). Example: 'Why `{{ record.name }}` is paused'. A hole over any other root, a `${…}` or single-brace `{x}` token (each named with its `{{ }}` spelling), a hole holding logic or an unknown formatter, and a blank sentence are named and refused at `objectstack validate`, `compile` and the publish gate; the text still parses, so a stored one loads until its next save. |
381
+
|**helpText**|`string \| { dialect: 'template'; source?: string; ast?: any; meta?: object } \| string \| Record<string, string>`| optional | Hint shown under this input in the action's param dialog — a `template` slot (ADR-0032): a bare string is shorthand for `{ dialect: 'template', source }`, and text with no hole is shown as written. Holes are `{{ path }}` or `{{ path \| formatter[:arg] }}` over `record`, the record the action runs against; the dialog's own values are not bound. Formatters come from the template engine's whitelist (`TEMPLATE_FORMATTERS`, `@objectstack/formula`); a hole holds no logic (no CEL, no arithmetic). Example: 'Why `{{ record.name }}` is paused'. A hole over any other root, a `${…}` or single-brace `{x}` token (each named with its `{{ }}` spelling), a hole holding logic or an unknown formatter, and a blank sentence are named and refused at `objectstack validate`, `compile` and the publish gate; the text still parses, so a stored one loads until its next save. |
0 commit comments