Skip to content

Commit 8a8a03d

Browse files
fix(studio): a refusal in a Studio strip is announced to screen readers (#29224)
<!-- claude-projects-attribution: {"github_login":"zhuangjianguo"} --> _Requested by **Steedos** · [project thread](https://claude.ai/code/project/chan_018ETKaNwMZCNRYD7D8Q9Ubb?thread=cmsg_018ETKaNwMZCNRYD7D8Q9UbbPQhqXLEJrxrqzKQ49MhRNU)_ Fixes #29139 Clause-②: no Metadata-protocol: none The two lines are copied from the claim (comment 6572863221). ## 维护者速读 - 改了什么:Studio 所有支柱共用的拒绝条(`StudioRefusalStrip`)里,那句拒绝说明现在是 `role="alert"`,读屏软件会在它出现时立即朗读,朗读内容就是服务器原话;"Show me" 按钮和 Details 展开区留在 alert 之外。视觉上没有任何变化。 - 为什么改:Setup 的 Packaged automation 页退役、开关搬进 Studio 后,开关被拒(409/403)只显示在这条没有 role、没有 live region 的拒绝条里,使用读屏的管理员拨开关时什么也听不到,开关只是不动。退役前的 Setup 页用一个带 `role="alert"` 的段落播报同一句话(18.3.0 RC 清单项 automation.setup-packaged-automation-board 的 acceptance[5])。 - 风险与回滚:只加一个 ARIA 属性,影响所有用这条拒绝条的地方(Interfaces、Data、Automations、发布清单的行);不改文案、不改布局、不改数据。回滚即撤销本 PR。 - 先看:`StudioDesignSurface.tsx` 中 `StudioRefusalStrip` 的 `studio-refusal-message` 那一行;新测试 `StudioDesignSurface.refusalAnnounced-29139.test.tsx`;`AutomationsPillar.ledgerSwitch-28148.test.tsx` 新增的 409 用例。 - 两分钟验证:`pnpm --dir ui exec vitest run packages/app-shell/src/views/studio-design/StudioDesignSurface.refusalAnnounced-29139.test.tsx packages/app-shell/src/views/studio-design/AutomationsPillar.ledgerSwitch-28148.test.tsx`,预期 12 个用例全部通过。 - 需要你做的:无,席位落地。 ## What changes - `StudioRefusalStrip` (`ui/packages/app-shell/src/views/studio-design/StudioDesignSurface.tsx`, the strip block only): the sentence element, `data-testid="studio-refusal-message"`, carries `role="alert"`. Nothing else in the strip moves: no new string, no new prop, no layout change. - Every pillar that draws the strip gets it from the one component: the Interfaces leaf and nav strips, the Data object strip, the Automations flow strip (where the ledger switch's 409 and 403 land), and the publish sheet's per-row refusal. ## Why this role, on this element - **`role="alert"`, not a polite region.** The strip is mounted with its sentence already in it (every call site renders it only when there is a refusal). An alert is announced when it is inserted; a polite live region inserted already filled is not reliably announced, because a live region must exist before its content changes. And what it shows is a refusal that stopped what the author just did, which is what an assertive alert is for. - **On the sentence, not on the strip.** The retired Setup › Packaged automation page rendered the refusal as a paragraph with `role="alert"` holding the server's sentence verbatim, beside the switch, and the checklist item `automation.setup-packaged-automation-board` acceptance[5] scores exactly that: the alert's text equals the server sentence. With the role on the whole strip, the alert would also read "Show me" and "Details", and opening the Details disclosure would change the alert's content and announce it again. On the sentence alone, the announcement is the sentence, and the strip's two controls stay ordinary, reachable controls after it. - A second refusal of the same flip is announced again: the Automations pillar clears its error before each toggle request, so the strip leaves while the request is in flight and the alert that comes back is a new element. ## Tests - New `StudioDesignSurface.refusalAnnounced-29139.test.tsx` (the strip itself, so every pillar is covered): - a one-line and a multi-line refusal are each exactly one alert, inside the strip, whose text is the sentence verbatim; - with a target, an input and a detail, "Show me" and the Details disclosure are outside the alert, before and after Details opens, and "Show me" still calls `onShow` with the target and input. - `AutomationsPillar.ledgerSwitch-28148.test.tsx`, one new case on the card's reproduction (the ledger switch, the subflow guard's 409 `DELETE_RESTRICTED` naming the caller): no alert before the flip; after it, one alert inside `studio-refusal` whose text is the 409 sentence verbatim; flipped again with the same refusal, no alert while the request is in flight (the toggle door is held on a gate), then a new alert element with the same sentence; the switch still reads the ledger. - Ablation, one leg: `role="alert"` dropped from the sentence through `scripts/ablation-replace.mjs` (anchor 1 to 0, blob changed, restore proven equal to HEAD with an empty `git diff HEAD`): 4 of the 12 cases in the two files went red (the three strip pins and the 409 case), the 8 others stayed green. - Neighbours: the 24 test files that render or query the strip, or query an alert in Studio, 125/125 green. - Live in a real browser, before and after: see Verification. ## Acceptance notes - **`aria-describedby` from the switch to the sentence: not added; not a local change.** The ledger switch (`FlowLedgerSwitch`) takes its description ids from its own hint, the not-running reason and the walled reason. The strip is drawn in the pillar body from the pillar's shared `error` state, which load, save, delete and toggle failures all set, and it has no id. Pointing the switch at the sentence needs an id on the strip, a new prop on `FlowLedgerSwitch`, and the pillar telling a toggle refusal apart from its other failures: three places outside the strip block. Measured live, the switch's `aria-describedby` names one id (its hint) before and after the refusal, on both legs. With the alert, the sentence is announced when it lands; the link would let a reader hear it again from the switch. Reported to the seat as a finding. - **Focus leaves the ledger switch on every flip (pre-existing, measured on both legs).** With the switch focused, Space flips it; while the request is in flight the switch is `disabled` (busy), and after the answer `document.activeElement` read `body`, on origin/main's strip and on this branch alike. Most likely the disabled state drops the focus, and nothing puts it back. A keyboard or screen-reader author has to find the switch again after each flip. It is in `FlowLedgerSwitch.tsx`, outside this card's file surface; reported to the seat as a finding. ## Verification - **Live, the card's reproduction** (head 3d6fa84): a fresh showcase (`objectstack dev --seed-admin --fresh` on a private port) with the Console served from source by Vite, signed in as the seeded admin, Studio › Automations › `showcase_notify_owner` (a read-only package, so the ledger switch), flipped with Space from the keyboard, twice. The real door answered both flips `409` `DELETE_RESTRICTED`, naming the caller `showcase_task_done_notify_owner`. - This branch: before the flip, no alert on the page. After it, one `role="alert"` inside `studio-refusal`, its text the response's `error.message` byte for byte, and Playwright's aria snapshot of the strip reads `- alert: "Flow 'showcase_notify_owner' cannot be disabled while 1 packaged flow still calls it as a subflow: ..."`. A DOM observer counted two alert insertions over the two refusals, each with the sentence. - origin/main's strip (its file swapped in under Vite, then restored, blob and empty `git diff HEAD` proven): the same sentence is a `- paragraph`, no alert on the page, no insertion over two refusals. - The strip's screenshot is byte-identical on the two legs (same md5): nothing visual moved. - **Gates:** `node scripts/pm/dispatch-gates.mjs --commands` derived 34 commands for this diff; all 34 ran at 5c8cc56 (the fix commit; the two later commits merge main and leave the delta to main at these four files), each exit 0, including `node scripts/check-sdui-manifest.mjs` and `pnpm --dir ui exec vitest run scripts/` (169 files, 4900 tests). `--ran` reconciliation: 34 derived, 34 run, 0 NOT-MEASURED. - **Tests:** the two touched files 12/12 and the 24 neighbour files 125/125 at 5c8cc56 and again at 3d6fa84. The second merge of main (0dffec2) brings four commits, none under `ui/packages/app-shell`; CI's Test UI runs the head. - **Type-check:** `turbo run type-check --filter=@object-ui/app-shell` (both `tsc --noEmit` and `tsc -p tsconfig.test.json`) green at 5c8cc56 and at 3d6fa84. - **Lint:** eslint on the three touched ui files, 0 errors; its 43 warnings are all on existing lines of `StudioDesignSurface.tsx`, none in the strip block or the tests. The repo-wide run is CI's Lint UI. ## 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. (Measured on the touched files only; see Verification.) - [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. (Not touched.) - [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. - [x] The *Before Submitting* list in CONTRIBUTING.md is done. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01QsR2jReFyNpMGkARoUHPD3 --- _Generated by [Claude Code](https://claude.ai/code/session_01QsR2jReFyNpMGkARoUHPD3)_ Co-authored-by: Claude <noreply@anthropic.com>
1 parent c84f795 commit 8a8a03d

4 files changed

Lines changed: 136 additions & 2 deletions

File tree

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
'@object-ui/app-shell': patch
3+
---
4+
5+
fix(studio): a refusal shown in a Studio strip is announced to screen readers — its sentence is a `role="alert"`, as Setup › Packaged automation announced it
6+
7+
Clause-②: no
8+
Metadata-protocol: none
9+
10+
Every Studio pillar shows a refused save, load, publish or flow switch in the same refusal strip, and the strip had no role and no live region, so a screen reader announced nothing: an author whose flow switch was refused heard silence while the switch simply did not move. The strip's sentence is now an alert, holding the sentence verbatim and nothing else. "Show me" and the Details disclosure stay outside it, so they are not read as part of the sentence, and opening Details does not announce it again. A second refusal of the same flip is announced again, because the strip leaves while the next request is in flight. Nothing visual changes.

‎ui/packages/app-shell/src/views/studio-design/AutomationsPillar.ledgerSwitch-28148.test.tsx‎

Lines changed: 42 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,8 @@
1919
* - under a wall a non-operator gets a disabled switch with the console's
2020
* sentence, and nothing is sent; `single` and the operator under the same
2121
* wall (CONTROLS) get a live switch;
22-
* - a refusal is the server's sentence, verbatim;
22+
* - a refusal is the server's sentence, verbatim, announced as an alert
23+
* (objectstack#29139), and announced again when the next flip is refused;
2324
* - a writable package's flow (CONTROL) keeps its definition switch and its
2425
* Delete, with no ledger switch.
2526
*
@@ -111,6 +112,8 @@ const doors = {
111112
enabled: true,
112113
unbound: null as null | { unboundCause: string; reason: string },
113114
toggle: null as null | { status: number; body: unknown },
115+
// Held until released: the toggle request is in flight meanwhile.
116+
toggleGate: null as null | Promise<void>,
114117
};
115118
const json = (status: number, body: unknown) =>
116119
new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json' } });
@@ -123,6 +126,7 @@ const fetchMock = vi.fn(async (input: RequestInfo | URL, init?: RequestInit) =>
123126
return json(200, { success: true, data: { flows: [row] } });
124127
}
125128
if (url.endsWith('/automation/approval/toggle')) {
129+
if (doors.toggleGate) await doors.toggleGate;
126130
if (doors.toggle) return json(doors.toggle.status, doors.toggle.body);
127131
doors.enabled = (JSON.parse(String(init?.body)) as { enabled: boolean }).enabled;
128132
return json(200, { success: true, data: { name: 'approval', enabled: doors.enabled } });
@@ -140,6 +144,7 @@ beforeEach(() => {
140144
doors.enabled = true;
141145
doors.unbound = null;
142146
doors.toggle = null;
147+
doors.toggleGate = null;
143148
fetchMock.mockClear();
144149
for (const fn of Object.values(mockClient)) (fn as unknown as { mockClear: () => void }).mockClear();
145150
vi.mocked(toast.success).mockClear();
@@ -242,6 +247,42 @@ describe('Automations — the ledger switch on a read-only package (ADR-0146 D4)
242247
expect(toast.success).not.toHaveBeenCalled();
243248
});
244249

250+
// objectstack#29139 — the refusal is announced, as Setup › Packaged
251+
// automation announced it: the sentence is an alert, and nothing is one
252+
// before a refusal or while the next flip is in flight.
253+
it('announces the subflow guard\'s 409: one alert, the sentence verbatim, and again on a second refusal', async () => {
254+
const sentence =
255+
"Flow 'approval' cannot be disabled while 1 packaged flow still calls it as a subflow: 'notify_owner'. " +
256+
'Disabling it would break that caller mid-run at its subflow node with a late, inexplicable failure ' +
257+
"(ADR-0126 §7.3). Switch 'notify_owner' off first — or leave this one armed.";
258+
doors.toggle = { status: 409, body: { success: false, error: { code: 'DELETE_RESTRICTED', message: sentence } } };
259+
mount();
260+
const sw = await ledgerSwitch();
261+
expect(screen.queryByRole('alert')).toBeNull();
262+
263+
fireEvent.click(sw);
264+
const alert = await screen.findByRole('alert');
265+
expect(alert.textContent).toBe(sentence);
266+
expect(screen.getAllByRole('alert')).toHaveLength(1);
267+
expect(screen.getByTestId('studio-refusal')).toContainElement(alert);
268+
269+
// Flipped again and refused with the same sentence: the strip leaves while
270+
// the request is in flight, and the alert that comes back is a new element,
271+
// which is what makes the same sentence announced a second time.
272+
let release!: () => void;
273+
doors.toggleGate = new Promise<void>((resolve) => {
274+
release = resolve;
275+
});
276+
fireEvent.click(screen.getByTestId('auto-ledger-switch'));
277+
await waitFor(() => expect(calls('/automation/approval/toggle')).toHaveLength(2));
278+
await waitFor(() => expect(screen.queryByRole('alert')).toBeNull());
279+
release();
280+
const again = await screen.findByRole('alert');
281+
expect(again).not.toBe(alert);
282+
expect(again.textContent).toBe(sentence);
283+
expect(screen.getByTestId('auto-ledger-switch')).toHaveAttribute('aria-checked', 'true');
284+
});
285+
245286
it('a writable package\'s flow keeps its definition switch and Delete, with no ledger switch', async () => {
246287
mount(false);
247288
expect(await screen.findByTestId('auto-canvas-caption', undefined, { timeout: 8000 })).toHaveTextContent('Approval');
Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
2+
3+
/**
4+
* objectstack#29139 — every Studio refusal is announced to assistive tech.
5+
*
6+
* `StudioRefusalStrip` is the one strip every pillar draws for a refused save
7+
* or load (the Interfaces leaf and nav, the Data object, the Automations flow,
8+
* the publish sheet's rows), so the property is pinned on the strip itself:
9+
* - the sentence is a `role="alert"`, and the alert's text is the sentence
10+
* verbatim, nothing added: what a screen reader reads is what the server or
11+
* the designer said;
12+
* - "Show me" and the Details disclosure sit outside the alert, so neither is
13+
* read as part of the sentence, and opening Details adds nothing to it;
14+
* - one strip is one alert.
15+
*
16+
* The pillar path the card reproduced (the flow ledger switch's refusal) is
17+
* pinned in `AutomationsPillar.ledgerSwitch-28148.test.tsx`.
18+
*/
19+
20+
import '@testing-library/jest-dom/vitest';
21+
import * as React from 'react';
22+
import { describe, it, expect, vi, afterEach } from 'vitest';
23+
import { render, screen, fireEvent, cleanup, within } from '@testing-library/react';
24+
25+
import { StudioRefusalStrip } from './StudioDesignSurface';
26+
27+
afterEach(cleanup);
28+
29+
const SENTENCE = 'The field “Status” needs at least one option.';
30+
31+
describe('StudioRefusalStrip — the refusal is announced (objectstack#29139)', () => {
32+
it.each([
33+
['a one-line refusal', SENTENCE],
34+
// A batch publish refusal is several lines (`whitespace-pre-line`).
35+
['a refusal of several lines', 'Nothing was published — the batch rolled back (all-or-nothing).\nflow/approval — Title is required.'],
36+
])('%s is one alert inside the strip, its text the sentence verbatim', (_label, message) => {
37+
render(<StudioRefusalStrip refusal={{ message }} locale="en" />);
38+
const alerts = screen.getAllByRole('alert');
39+
expect(alerts).toHaveLength(1);
40+
expect(alerts[0].textContent).toBe(message);
41+
expect(alerts[0]).toHaveAttribute('data-testid', 'studio-refusal-message');
42+
expect(screen.getByTestId('studio-refusal')).toContainElement(alerts[0]);
43+
});
44+
45+
it('keeps "Show me" and Details out of the alert, before and after Details opens', () => {
46+
const onShow = vi.fn();
47+
render(
48+
<StudioRefusalStrip
49+
refusal={{
50+
message: SENTENCE,
51+
target: { kind: 'field', id: 'status' },
52+
input: 'Options',
53+
detail: 'fields.status.options — Array must contain at least 1 element(s)',
54+
}}
55+
locale="en"
56+
onShow={onShow}
57+
/>,
58+
);
59+
const alert = screen.getByRole('alert');
60+
expect(alert.textContent).toBe(SENTENCE);
61+
// The strip's controls are reachable, and none is inside the alert.
62+
const show = screen.getByRole('button', { name: 'Show me' });
63+
expect(alert).not.toContainElement(show);
64+
expect(within(alert).queryByRole('button')).toBeNull();
65+
const details = screen.getByTestId('studio-refusal-detail');
66+
expect(alert).not.toContainElement(details);
67+
68+
fireEvent.click(within(details).getByText('Details'));
69+
(details as HTMLDetailsElement).open = true;
70+
expect(screen.getAllByRole('alert')).toHaveLength(1);
71+
expect(screen.getByRole('alert').textContent).toBe(SENTENCE);
72+
73+
fireEvent.click(show);
74+
expect(onShow).toHaveBeenCalledWith({ kind: 'field', id: 'status' }, 'Options');
75+
});
76+
});

‎ui/packages/app-shell/src/views/studio-design/StudioDesignSurface.tsx‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -703,6 +703,13 @@ const navIcon = (type?: string): LucideIcon => KIND_ICON[type ?? ''] ?? Compass;
703703
* "Details" disclosure. A failure with nothing rewritten (`plainRefusal`) has
704704
* no detail and renders as the single line it always was.
705705
*
706+
* objectstack#29139 — the sentence is announced: it is a `role="alert"`, the
707+
* sentence alone. A refusal stops what the author just did, and the strip
708+
* mounts with its sentence already in it; an alert is announced on insertion,
709+
* where a polite live region inserted already filled may not be. "Show me" and
710+
* Details stay outside it, so the announcement is the sentence verbatim and
711+
* opening Details does not announce it again.
712+
*
706713
* Exported for its pins; `index.ts` does not re-export it.
707714
*/
708715
export function StudioRefusalStrip({
@@ -729,7 +736,7 @@ export function StudioRefusalStrip({
729736
className={cn('rounded-md border border-destructive/40 bg-destructive/10 text-destructive', className)}
730737
>
731738
<div className="flex items-start gap-2">
732-
<p data-testid="studio-refusal-message" className="min-w-0 flex-1 whitespace-pre-line">
739+
<p data-testid="studio-refusal-message" role="alert" className="min-w-0 flex-1 whitespace-pre-line">
733740
{message}
734741
</p>
735742
{target !== undefined && onShow && (

0 commit comments

Comments
 (0)