Skip to content

Commit 30e42aa

Browse files
committed
refactor(spec): build the action copy template inputs at their declaring .zod.ts files; classify them in the expression-surface ledger
Claude-Session: https://claude.ai/code/session_01DcqhBfbrsH8ACDsMQ62Hzq Co-authored-by: Claude <noreply@anthropic.com>
1 parent 04dd99c commit 30e42aa

5 files changed

Lines changed: 133 additions & 57 deletions

File tree

‎packages/qa/dogfood/test/expression-conformance.ledger.ts‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -638,6 +638,50 @@ export const EXPRESSION_SURFACE: ExprSurface[] = [
638638
covers: ['ui/bulk-action.zod.ts:BulkActionDefSchema.confirmText'],
639639
note: 'EXPERIMENTAL until the console fills the holes. The spec half declares the slot, its closed scope and the display-value rule a param hole renders; the console half — the dialog rendering the slot through the formula template engine, `count` first and the param roots second — lands in objectui, and this row is re-stated as `enforced` with the fail policy that renderer has once it is measured there. Until then a hole reaches the screen as literal text, as it did before the slot was typed.',
640640
},
641+
// #24814 (ruling A): an action's copy — `confirmText`, `successMessage`, `errorMessage` — became a
642+
// `template` slot over the closed scope the console's runner binds, on a registered action
643+
// (`actionObject`, which `InlineActionSchema` picks) and on the three page action rows.
644+
{
645+
id: 'template-action-confirm-text',
646+
summary: 'action confirm sentence (Action.confirmText, and the page action rows\' `confirmText`) — `{{ record.* }}` holes, and `{{ params.* }}` beside static values',
647+
dialect: 'template', mode: 'interpret', state: 'enforced', failPolicy: 'fail-soft-log',
648+
enforcement:
649+
'PARSE, measured here: `ui/action-copy-template.ts` `actionCopyTemplateSlot` around `templateExpressionInput`, built at each declaring file, normalizes a bare string to `{dialect:"template",source}`, keeps a blank string as written and (on `Action`) the inline locale map. BUILD-TIME GATE, measured here: lint/validate-action-copy-templates.ts `actionCopyTemplateIssues`, run by `validateStackExpressions` at `objectstack validate` / `compile` and the publish gate (`action`, `object` and `page` writes), judges each sentence with `closedScopeTemplateRefusal` over `actionConfirmTemplateRoots(action)` and then `validateExpression(\'template\', …)` — every finding a WARNING. EVALUATOR: console (objectui) `ActionRunner.confirmMessage` → `fillTemplateHoles` → @objectstack/formula `templateEngine.evaluate` over `record` (the dispatched row, else the context record) and `params` (the static values), read at the pinned `.objectui-sha`; a sentence the engine refuses is shown as written, an unbound hole prints empty, and a sentence with no `{{ }}` hole keeps the transitional `${…}` reading',
650+
covers: [
651+
'ui/action.zod.ts:actionObject.confirmText',
652+
'ui/component.zod.ts:ActionButtonPropsSchema.confirmText',
653+
'ui/component.zod.ts:ActionIconPropsSchema.confirmText',
654+
'ui/component.zod.ts:actionContainerMemberShape.confirmText',
655+
],
656+
note: 'Soft on both faces — a refused sentence reads as written and an unbound root as a blank fragment — which is why the doors name both ahead of time. Warnings, not refusals: each such sentence parsed while the key was a plain string, so the refusal is its own card. ⛔ NOT MEASURED HERE: the runner was read at the pin, not run, and the `-log` half of `fail-soft-log` (no log line was found on either face).',
657+
},
658+
{
659+
id: 'template-action-success-message',
660+
summary: 'action success toast (Action.successMessage, and the page action rows\' `successMessage`) — `{{ result.* }}` and `{{ record.* }}` holes',
661+
dialect: 'template', mode: 'interpret', state: 'enforced', failPolicy: 'fail-soft-log',
662+
enforcement:
663+
'PARSE and BUILD-TIME GATE: the same as `template-action-confirm-text`, over `ACTION_SUCCESS_TEMPLATE_ROOTS` (`result`, then `record`). EVALUATOR: console (objectui) `ActionRunner.composeSuccessMessage` → `fillTemplateHoles` → @objectstack/formula `templateEngine.evaluate` over `result` (the payload the handler answered) and `record`, read at the pinned `.objectui-sha`; `outcomeMessages[outcome]` outranks it, a blank sentence falls to the runner\'s default text, and a sentence with no `{{ }}` hole keeps the transitional `${result.*}` reading',
664+
covers: [
665+
'ui/action.zod.ts:actionObject.successMessage',
666+
'ui/component.zod.ts:ActionButtonPropsSchema.successMessage',
667+
'ui/component.zod.ts:ActionIconPropsSchema.successMessage',
668+
'ui/component.zod.ts:actionContainerMemberShape.successMessage',
669+
],
670+
note: 'The platform\'s own sentences (`sys_invitation` / `sys_member` / `sys_organization` / `sys_user` `invite_user`, the nine `sys_approval_request` decisions) were converted from `${result.*}` to `{{ result.* }}` on the same change. `outcomeMessages` is NOT this row: it stays a `${result.*}` string. ⛔ NOT MEASURED HERE: the runner was read at the pin, not run, and the `-log` half of `fail-soft-log`.',
671+
},
672+
{
673+
id: 'template-action-error-message',
674+
summary: 'page action row failure toast (the rows\' `errorMessage`) — a `template` slot that binds no root',
675+
dialect: 'template', mode: 'interpret', state: 'experimental', failPolicy: 'unevaluated',
676+
enforcement:
677+
'PARSE ONLY in this repo — the rows type the key with the same `template` slot as `template-action-confirm-text`, over `ACTION_ERROR_TEMPLATE_ROOTS`, which is EMPTY. NO EVALUATOR FOUND: the console\'s action runner shows an authored `errorMessage` as written (its envelope\'s `source`) and fills no hole, read at the pinned `.objectui-sha`. At build and at the publish gate the action copy pass names every hole and every `${…}` / `{…}` token in it as literal text, a WARNING',
678+
covers: [
679+
'ui/component.zod.ts:ActionButtonPropsSchema.errorMessage',
680+
'ui/component.zod.ts:ActionIconPropsSchema.errorMessage',
681+
'ui/component.zod.ts:actionContainerMemberShape.errorMessage',
682+
],
683+
note: 'EXPERIMENTAL until a scope is ruled for the failure toast. `Action.errorMessage` (the registered action\'s) is NOT typed: it stays an `I18nLabel`, outside this family by the ruling, so it declares no expression surface.',
684+
},
641685
{
642686
id: 'template-notify-content',
643687
summary: 'flow `notify` node inline content (NotifyConfig.title, .message) — `{{ }}` template holes rendered per run by the formula template engine',

‎packages/qa/dogfood/test/member-transfer-ownership-step-down.dogfood.test.ts‎

Lines changed: 9 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -40,15 +40,18 @@
4040
import { describe, it, expect, beforeAll, afterAll } from 'vitest';
4141
import { type VerifyStack } from '@objectstack/verify';
4242
import { celEngine } from '@objectstack/formula';
43+
import { templateSlotSource } from '@objectstack/spec/automation';
4344
import { bootShowcase } from './showcase-boot.js';
4445

4546
const SYSTEM_CTX = { isSystem: true };
4647

4748
type ServedAction = {
4849
name: string;
4950
label?: string;
50-
confirmText?: string;
51-
successMessage?: string;
51+
// [#24814] `template` slots: a translated sentence is served as a string, an
52+
// untranslated one as the parsed `{ dialect: 'template', source }` envelope.
53+
confirmText?: unknown;
54+
successMessage?: unknown;
5255
target?: string;
5356
bodyExtra?: Record<string, unknown>;
5457
visible?: unknown;
@@ -142,14 +145,15 @@ describe('sys_member.transfer_ownership makes the target an owner; the caller st
142145
expect(action!.target).toBe('/api/v1/auth/organization/update-member-role');
143146
expect(action!.bodyExtra).toEqual({ role: 'owner' });
144147

145-
const copy = [action!.label, action!.confirmText, action!.successMessage].join(' | ');
148+
const confirmText = templateSlotSource(action!.confirmText);
149+
const copy = [action!.label, confirmText, templateSlotSource(action!.successMessage)].join(' | ');
146150
// No demotion and no transfer is promised anywhere in the copy.
147151
expect(copy).not.toMatch(/demot/i);
148152
expect(copy).not.toMatch(/transfer/i);
149153
expect(action!.label).toBe('Make Owner');
150154
// The confirm names the outcome and the real step-down, by the step-down's own label.
151-
expect(action!.confirmText).toContain('You stay an owner');
152-
expect(action!.confirmText).toContain(served.get('update_member_role')?.label ?? 'update_member_role is not served');
155+
expect(confirmText).toContain('You stay an owner');
156+
expect(confirmText).toContain(served.get('update_member_role')?.label ?? 'update_member_role is not served');
153157
});
154158

155159
it('the action, as an owner, makes the target an owner and leaves the caller an owner', async () => {

‎packages/spec/src/ui/action-copy-template.ts‎

Lines changed: 28 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,7 @@
11
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
22

33
import { z } from 'zod';
4-
import { ExpressionSchema } from '../shared/expression.zod';
5-
import { templateExpressionInput } from '../shared/typed-expression-input';
4+
import type { TypedExpressionRefusals } from '../shared/typed-expression-input';
65
import { InlineLocaleMapSchema } from './i18n.zod';
76

87
/**
@@ -113,21 +112,35 @@ function dialectOnly(key: ActionCopyKey, localeMap: boolean): string {
113112
}
114113

115114
/**
116-
* The slot one copy key declares: ADR-0032's `template` dialect, the input
117-
* `TemplateExpressionInputSchema` takes — a bare string is shorthand for
118-
* `{ dialect: 'template', source }`, an envelope must declare
119-
* `dialect: 'template'` — built from the package-internal constructor so its
120-
* refusal prescribes this key's own sentence; then a blank-string arm, so the
121-
* parse does not narrow (the module note); then, on `ActionSchema`, the
122-
* inline locale map its `I18nLabel` took.
123-
*
124-
* A factory the schemas call, not a shared constant: each key refuses with its
125-
* own sentence, and a schema instance shared between two lazily built rows
126-
* would carry one `describe()` for both.
115+
* The two sentences one copy key's template input refuses with
116+
* (`templateExpressionInput`'s `refusals`): both prescribe the key's own
117+
* sentence, so a refusal names the slot the author wrote.
127118
*/
128-
export function actionCopyTemplateSlot(key: ActionCopyKey, options: { localeMap?: boolean } = {}) {
119+
export function actionCopyRefusals(key: ActionCopyKey, options: { localeMap?: boolean } = {}): TypedExpressionRefusals {
129120
const refusal = dialectOnly(key, options.localeMap === true);
130-
const template = templateExpressionInput(ExpressionSchema, { sourceRequired: refusal, dialectOnly: refusal });
121+
return { sourceRequired: refusal, dialectOnly: refusal };
122+
}
123+
124+
/**
125+
* The slot one copy key declares, around its `template` input: ADR-0032's
126+
* `template` dialect, the input `TemplateExpressionInputSchema` takes — a bare
127+
* string is shorthand for `{ dialect: 'template', source }`, an envelope must
128+
* declare `dialect: 'template'` — then a blank-string arm, so the parse does
129+
* not narrow (the module note); then, on `ActionSchema`, the inline locale map
130+
* its `I18nLabel` took.
131+
*
132+
* The `template` input itself is built at each declaring `.zod.ts` file
133+
* (`templateExpressionInput(ExpressionSchema, actionCopyRefusals(key))`), not
134+
* here: the expression-surface census (the conformance ledger's scan) reads
135+
* `.zod.ts` files, and a slot whose input is constructed in a plain module is
136+
* a declared expression surface that census never sees.
137+
*/
138+
export function actionCopyTemplateSlot<T extends z.ZodType>(
139+
template: T,
140+
key: ActionCopyKey,
141+
options: { localeMap?: boolean } = {},
142+
) {
143+
const { dialectOnly: refusal } = actionCopyRefusals(key, options);
131144
// `trim()`'s whitespace set is exactly `\s` (ECMA-262), so this arm takes the blank strings
132145
// `NON_BLANK_STRING` refuses — as a `pattern` the JSON Schema carries, not a dropped refinement.
133146
const blank = z.string().regex(/^\s*$/);
@@ -168,26 +181,3 @@ export const ACTION_ERROR_MESSAGE_TEMPLATE_DESCRIBE =
168181
"a `template` slot (ADR-0032) that binds no root: a bare string is shorthand for `{ dialect: 'template', source }`, "
169182
+ 'and the text is shown as written, so a `{{ }}` hole, a `${…}` or a `{x}` token in it is literal text. Each of '
170183
+ `those, and a blank sentence, is named ${DOORS}`;
171-
172-
/**
173-
* The three copy keys of a page action row — `action:button`, `action:icon`
174-
* and an `action:group` / `action:menu` member (`ui/component.zod.ts`), each
175-
* of which forwards them to the runner as written. One factory per key, so
176-
* every row names its keys in its own shape.
177-
*/
178-
export function actionRowConfirmText() {
179-
return actionCopyTemplateSlot('confirmText').optional()
180-
.describe(`Confirmation question asked before the action runs — ${ACTION_CONFIRM_TEXT_TEMPLATE_DESCRIBE}`);
181-
}
182-
183-
/** A page action row's `successMessage` — see {@link actionRowConfirmText}. */
184-
export function actionRowSuccessMessage() {
185-
return actionCopyTemplateSlot('successMessage').optional()
186-
.describe(`Toast shown when the action succeeds — ${ACTION_SUCCESS_MESSAGE_TEMPLATE_DESCRIBE}`);
187-
}
188-
189-
/** A page action row's `errorMessage` — see {@link actionRowConfirmText}. */
190-
export function actionRowErrorMessage() {
191-
return actionCopyTemplateSlot('errorMessage').optional()
192-
.describe(`Toast shown when the action fails, in place of the raw error — ${ACTION_ERROR_MESSAGE_TEMPLATE_DESCRIBE}`);
193-
}

‎packages/spec/src/ui/action.zod.ts‎

Lines changed: 15 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -21,14 +21,16 @@ import { isActionParamValuePresent } from './action-params.zod';
2121
// reaches only `shared/` + `data/`, so it cannot close a cycle back to `ui/`.
2222
import { BulkActionExecutionSchema } from './bulk-action.zod';
2323
import { SnakeCaseIdentifierSchema } from '../shared/identifiers.zod';
24-
import { EvaluatedExpressionInputSchema } from '../shared/expression.zod';
24+
import { EvaluatedExpressionInputSchema, ExpressionSchema } from '../shared/expression.zod';
2525
import { evaluatedExpressionUnionRefusal } from '../shared/evaluated-slot-union';
2626
import { I18nLabelSchema } from './i18n.zod';
2727
import {
2828
ACTION_CONFIRM_TEXT_TEMPLATE_DESCRIBE,
2929
ACTION_SUCCESS_MESSAGE_TEMPLATE_DESCRIBE,
30+
actionCopyRefusals,
3031
actionCopyTemplateSlot,
3132
} from './action-copy-template';
33+
import { templateExpressionInput } from '../shared/typed-expression-input';
3234
import { HookBodySchema } from '../data/hook-body.zod';
3335
// Imported file-directly (not via the kernel barrel): the module is
3436
// deliberately import-free, so this cannot introduce a cycle.
@@ -868,6 +870,16 @@ const ActionConditionInputSchema = z.union([z.boolean(), EvaluatedExpressionInpu
868870
error: (issue) => evaluatedExpressionUnionRefusal(issue.input),
869871
});
870872

873+
/**
874+
* [#24814, ADR-0032 Decisions 2–3] A registered action's `confirmText` /
875+
* `successMessage` — a `template` slot over the roots the console's runner
876+
* binds, one family with the page action rows' copy keys
877+
* (`./action-copy-template.ts`), which also keeps the inline locale map
878+
* `I18nLabelSchema` took. The `template` input is built HERE, at the declaring
879+
* file, so the expression-surface census sees both positions.
880+
*/
881+
const actionCopy = (key: 'confirmText' | 'successMessage') => actionCopyTemplateSlot(templateExpressionInput(ExpressionSchema, actionCopyRefusals(key, { localeMap: true })), key, { localeMap: true });
882+
871883
/**
872884
* The object half of {@link ActionSchema}, before its refinements.
873885
*
@@ -1352,15 +1364,15 @@ const actionObject = () => strictObject({
13521364
// (`./action-copy-template.ts`): the runner reads the same key from both.
13531365
// The inline locale map `I18nLabelSchema` took stays an arm, so the parse
13541366
// does not narrow; each of its values is a sentence the doors judge alike.
1355-
confirmText: actionCopyTemplateSlot('confirmText', { localeMap: true }).optional().describe(`Confirmation message before execution — ${ACTION_CONFIRM_TEXT_TEMPLATE_DESCRIBE} An inline locale map ({ en, "zh-CN" }) is accepted too, each value such a sentence. On a registered action, pairing this with a non-empty \`params\` is refused — that opens a second dialog for one decision; put the question on \`description\` instead. Correct on a param-LESS action, where the confirm is the only dialog there is.`),
1367+
confirmText: actionCopy('confirmText').optional().describe(`Confirmation message before execution — ${ACTION_CONFIRM_TEXT_TEMPLATE_DESCRIBE} An inline locale map ({ en, "zh-CN" }) is accepted too, each value such a sentence. On a registered action, pairing this with a non-empty \`params\` is refused — that opens a second dialog for one decision; put the question on \`description\` instead. Correct on a param-LESS action, where the confirm is the only dialog there is.`),
13561368
// `result` is the payload `onSuccess.navigate` reads as `${result.*}` (see
13571369
// that key's docblock for its members) — the copy reads the same payload,
13581370
// as a `{{ result.* }}` hole since #24814 (the `${result.*}` spelling it
13591371
// took before is the one the judge now prescribes a hole for). The sentence
13601372
// is phrased "on a registered action" for the same reason `confirmText`'s
13611373
// is: this describe() also renders into the InlineAction table, which does
13621374
// not pick `outcomeMessages`.
1363-
successMessage: actionCopyTemplateSlot('successMessage', { localeMap: true }).optional().describe(`Success message shown after the action succeeds — ${ACTION_SUCCESS_MESSAGE_TEMPLATE_DESCRIBE} An inline locale map ({ en, "zh-CN" }) is accepted too, each value such a sentence. On a registered action that declares \`outcomeMessages\`, the entry named by the response's \`outcome\` is shown instead, and this message is the fallback.`),
1375+
successMessage: actionCopy('successMessage').optional().describe(`Success message shown after the action succeeds — ${ACTION_SUCCESS_MESSAGE_TEMPLATE_DESCRIBE} An inline locale map ({ en, "zh-CN" }) is accepted too, each value such a sentence. On a registered action that declares \`outcomeMessages\`, the entry named by the response's \`outcome\` is shown instead, and this message is the fallback.`),
13641376

13651377
/**
13661378
* Outcome-specific success copy — ruling A on objectstack-ai/cloud#2315,

0 commit comments

Comments
 (0)