fix: show clarification submission status (#3157)

This commit is contained in:
Carlos Florêncio
2026-08-30 13:36:48 +00:00
committed by GitHub
parent 2ef2c174c9
commit c95407941d
10 changed files with 742 additions and 112 deletions
@@ -85,6 +85,7 @@ export function ClarificationHeaderActions({
type="button"
onClick={onSubmit}
disabled={!allAnswered || isSubmitting}
aria-label={t("task:submit")}
data-testid="clarification-submit"
className={cn(
"inline-flex w-full items-center justify-center gap-2 rounded-lg px-4 py-1 text-xs font-medium transition-[color,background-color,transform] duration-150 active:scale-[0.96] md:w-auto md:gap-1 md:rounded md:px-3 [@media(pointer:coarse)]:min-h-11",
@@ -94,15 +95,18 @@ export function ClarificationHeaderActions({
)}
>
{isSubmitting ? t("task:submitting") : t("task:submit")}
{isSubmitting ? (
<Spinner aria-hidden="true" className="size-3" />
) : (
<IconCheck className="h-3 w-3" />
)}
{!isSubmitting && <IconCheck className="h-3 w-3" />}
</button>
</span>
</KeyboardShortcutTooltip>
)}
{isSubmitting && (
<Spinner
aria-label={t("task:submitting")}
data-testid="clarification-submitting-status"
className="size-3 shrink-0"
/>
)}
<ClarificationSkipButton
isSubmitting={isSubmitting}
onSkip={onSkip}
@@ -4,6 +4,7 @@ import { render, cleanup, fireEvent, screen } from "@testing-library/react";
import { i18n } from "@/lib/i18n";
import { sessionId as toSessionId, taskId as toTaskId, type Message } from "@/lib/types/http";
import { ClarificationPanelSection } from "./clarification-panel-section";
import { ClarificationHeaderActions } from "./clarification-overlay-header";
vi.mock("@/lib/config", () => ({
getBackendConfig: () => ({ apiBaseUrl: "https://api.test" }),
@@ -91,6 +92,7 @@ afterEach(async () => {
const SCROLL_REGION_TESTID = "clarification-scroll-region";
const CONTAINER_TESTID = "clarification-overlay-container";
const QUESTION_COUNT_TESTID = "clarification-question-count";
const SUBMITTING_STATUS_TESTID = "clarification-submitting-status";
describe("ClarificationPanelSection — collapse affordance", () => {
it("keeps the expanded question controls in one header row", () => {
@@ -167,6 +169,93 @@ describe("ClarificationPanelSection — collapse affordance", () => {
});
});
describe("ClarificationPanelSection — submitting feedback", () => {
it("keeps the multi-question header status announced with a stable Submit name", () => {
render(
<ClarificationHeaderActions
total={3}
allAnswered={true}
isSubmitting={true}
onSubmit={vi.fn()}
onSkip={vi.fn()}
/>,
);
const status = screen.getByTestId(SUBMITTING_STATUS_TESTID);
const submit = screen.getByTestId("clarification-submit");
expect(status.getAttribute("aria-label")).toBe(i18n.t("task:submitting"));
expect(status.getAttribute("aria-hidden")).toBeNull();
expect(submit.getAttribute("aria-label")).toBe(i18n.t("task:submit"));
});
it("shows the translated submitting status before Skip while a single answer is in flight", async () => {
const messages = [
clarMessage({ pendingId: "p1", id: "m1", questionId: "q1", index: 0, total: 1 }),
];
let releaseResponse!: (response: Response) => void;
const heldResponse = new Promise<Response>((resolve) => {
releaseResponse = resolve;
});
fetchMock.mockReturnValueOnce(heldResponse);
renderSection(true, messages);
expect(screen.queryByTestId(SUBMITTING_STATUS_TESTID)).toBeNull();
try {
fireEvent.click(screen.getByTestId("clarification-option"));
const status = await screen.findByTestId(SUBMITTING_STATUS_TESTID);
const skip = screen.getByTestId("clarification-skip");
expect(status.getAttribute("aria-label")).toBe(i18n.t("task:submitting"));
expect(status.getAttribute("aria-hidden")).toBeNull();
expect(status.compareDocumentPosition(skip) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy();
expect((skip as HTMLButtonElement).disabled).toBe(true);
releaseResponse(
new Response("{}", {
status: 200,
headers: { "Content-Type": "application/json" },
}),
);
await vi.waitFor(() => expect(screen.queryByTestId(SUBMITTING_STATUS_TESTID)).toBeNull());
} finally {
releaseResponse(
new Response("{}", {
status: 200,
headers: { "Content-Type": "application/json" },
}),
);
}
});
it("removes the submitting status and re-enables Skip when the answer request fails", async () => {
const messages = [
clarMessage({ pendingId: "p1", id: "m1", questionId: "q1", index: 0, total: 1 }),
];
let rejectResponse!: (error: Error) => void;
const heldResponse = new Promise<Response>((_, reject) => {
rejectResponse = reject;
});
fetchMock.mockReturnValueOnce(heldResponse);
renderSection(true, messages);
try {
fireEvent.click(screen.getByTestId("clarification-option"));
await screen.findByTestId(SUBMITTING_STATUS_TESTID);
rejectResponse(new Error("network"));
await vi.waitFor(() => {
expect(screen.queryByTestId(SUBMITTING_STATUS_TESTID)).toBeNull();
expect((screen.getByTestId("clarification-skip") as HTMLButtonElement).disabled).toBe(
false,
);
});
} finally {
rejectResponse(new Error("network"));
}
});
});
describe("ClarificationPanelSection — per-surface max-height cap", () => {
it("renders the CSS max-height from the maxHeightVh prop instead of a hardcoded value", () => {
const messages = [
+5
View File
@@ -519,6 +519,11 @@ export class SessionPage {
return this.page.getByTestId("clarification-skip");
}
/** Header status shown while a clarification answer is being submitted. */
clarificationSubmittingStatus(): Locator {
return this.clarificationOverlay().getByTestId("clarification-submitting-status");
}
/** Custom text input on the clarification overlay. */
clarificationInput(): Locator {
return this.page.getByTestId("clarification-input");
+82 -13
View File
@@ -123,6 +123,57 @@ test.describe("Clarification flow", () => {
await expect(session.chat).toContainText(/You answered|selected_option/);
});
test("shows the header submitting status for a single-question answer", async ({
testPage,
apiClient,
seedData,
}) => {
const session = await seedClarificationTask(
testPage,
apiClient,
seedData,
"Clarification Single Submit Feedback",
"clarification",
);
await expect(session.clarificationOverlay()).toBeVisible({ timeout: 30_000 });
const header = session.clarificationOverlay().getByTestId("clarification-overlay-header");
const status = session.clarificationSubmittingStatus();
await expect(status).toHaveCount(0);
let releaseResponse = () => undefined;
const heldResponse = new Promise<void>((resolve) => {
releaseResponse = resolve;
});
await testPage.route("**/api/v1/clarification/*/respond", async (route) => {
await heldResponse;
await route.fulfill({ status: 200, contentType: "application/json", body: "{}" });
});
try {
await session.clarificationOption("PostgreSQL").click();
await expect(status).toBeVisible();
await expect(status).toHaveAttribute("aria-label", "Submitting…");
await expect(status).toHaveCount(1);
await expect(session.clarificationSkip()).toBeDisabled();
const statusPrecedesSkip = await header.evaluate((node) => {
const submitting = node.querySelector('[data-testid="clarification-submitting-status"]');
const skip = node.querySelector('[data-testid="clarification-skip"]');
return Boolean(
submitting &&
skip &&
submitting.compareDocumentPosition(skip) & Node.DOCUMENT_POSITION_FOLLOWING,
);
});
expect(statusPrecedesSkip).toBe(true);
} finally {
releaseResponse();
}
await expect(session.clarificationOverlay()).not.toBeVisible({ timeout: 30_000 });
});
// R2/R11 + W3: a duplicate submit is a 200 with claimed: false, not a 409 —
// the losing client must apply the winner's own answer instead of stranding
// the overlay on "pending" or rendering its own (overwritten) submission.
@@ -1028,22 +1079,40 @@ test.describe("Multi-question clarification carousel", () => {
await route.fulfill({ status: 200, contentType: "application/json", body: "{}" });
});
await session.chat.focus();
await testPage.keyboard.press("ControlOrMeta+Enter");
const submit = session.clarificationSubmit();
await expect(submit).toContainText("Submitting");
await expect(submit).toBeDisabled();
await expect(submit.locator('[role="status"]')).toBeVisible();
await expect(submit.locator('[role="status"]')).toHaveAttribute("aria-hidden", "true");
await expect(submit.locator("svg.tabler-icon-check")).toHaveCount(0);
try {
await session.chat.focus();
await testPage.keyboard.press("ControlOrMeta+Enter");
const submit = session.clarificationSubmit();
const header = session.clarificationOverlay().getByTestId("clarification-overlay-header");
const status = session.clarificationSubmittingStatus();
await expect(submit).toContainText("Submitting");
await expect(submit).toBeDisabled();
await expect(status).toBeVisible();
await expect(status).toHaveAttribute("aria-label", "Submitting…");
await expect(status).not.toHaveAttribute("aria-hidden");
await expect(submit).toHaveAttribute("aria-label", "Submit");
await expect(submit.locator('[role="status"]')).toHaveCount(0);
await expect(submit.locator("svg.tabler-icon-check")).toHaveCount(0);
await testPage.keyboard.press("ArrowLeft");
await expect(session.clarificationStep(2)).toHaveAttribute("data-active", "true");
const statusPrecedesSkip = await header.evaluate((node) => {
const submitting = node.querySelector('[data-testid="clarification-submitting-status"]');
const skip = node.querySelector('[data-testid="clarification-skip"]');
return Boolean(
submitting &&
skip &&
submitting.compareDocumentPosition(skip) & Node.DOCUMENT_POSITION_FOLLOWING,
);
});
expect(statusPrecedesSkip).toBe(true);
await testPage.getByTestId("clarification-submit-shortcut").hover();
await expect(testPage.getByRole("tooltip", { name: /Submit answers/ })).not.toBeVisible();
await testPage.keyboard.press("ArrowLeft");
await expect(session.clarificationStep(2)).toHaveAttribute("data-active", "true");
releaseResponse();
await testPage.getByTestId("clarification-submit-shortcut").hover();
await expect(testPage.getByRole("tooltip", { name: /Submit answers/ })).not.toBeVisible();
} finally {
releaseResponse();
}
await expect(session.clarificationOverlay()).not.toBeVisible({ timeout: 30_000 });
});
@@ -86,6 +86,79 @@ test.describe("Mobile clarification multiline answer", () => {
await expect(session.chat).not.toContainText("linesecond line");
});
test("shows the header submitting status for a single-question answer", async ({
testPage,
apiClient,
seedData,
}) => {
const session = await seedClarificationSession(
testPage,
apiClient,
seedData,
"Mobile Clarify Submit Feedback",
{ scenario: "clarification" },
);
await expect(session.clarificationOverlay()).toBeVisible({ timeout: 30_000 });
const overlay = session.clarificationOverlay();
const header = overlay.getByTestId("clarification-overlay-header");
const status = session.clarificationSubmittingStatus();
await expect(status).toHaveCount(0);
let releaseResponse = () => undefined;
const heldResponse = new Promise<void>((resolve) => {
releaseResponse = resolve;
});
await testPage.route("**/api/v1/clarification/*/respond", async (route) => {
await heldResponse;
await route.fulfill({ status: 200, contentType: "application/json", body: "{}" });
});
try {
await session.clarificationOption("PostgreSQL").tap();
await expect(status).toBeVisible();
await expect(status).toHaveAttribute("aria-label", "Submitting…");
await expect(session.clarificationSkip()).toBeDisabled();
const [headerBox, statusBox, skipBox, collapseBox] = await Promise.all([
header.boundingBox(),
status.boundingBox(),
session.clarificationSkip().boundingBox(),
session.clarificationCollapseToggle().boundingBox(),
]);
if (!headerBox || !statusBox || !skipBox || !collapseBox) {
throw new Error("expected mobile clarification header controls to have bounding boxes");
}
expect(statusBox.x).toBeGreaterThanOrEqual(headerBox.x);
expect(statusBox.x + statusBox.width).toBeLessThanOrEqual(headerBox.x + headerBox.width);
expect(skipBox.height).toBeGreaterThanOrEqual(44);
expect(skipBox.width).toBeGreaterThanOrEqual(44);
expect(collapseBox.height).toBeGreaterThanOrEqual(44);
expect(collapseBox.width).toBeGreaterThanOrEqual(44);
const statusPrecedesSkip = await header.evaluate((node) => {
const submitting = node.querySelector('[data-testid="clarification-submitting-status"]');
const skip = node.querySelector('[data-testid="clarification-skip"]');
return Boolean(
submitting &&
skip &&
submitting.compareDocumentPosition(skip) & Node.DOCUMENT_POSITION_FOLLOWING,
);
});
expect(statusPrecedesSkip).toBe(true);
await expect(
testPage.evaluate(
() => document.documentElement.scrollWidth <= document.documentElement.clientWidth,
),
).resolves.toBe(true);
} finally {
releaseResponse();
}
await expect(overlay).not.toBeVisible({ timeout: 30_000 });
});
test("keeps the over-limit counter inside the phone viewport", async ({
testPage,
apiClient,
@@ -283,23 +356,45 @@ test.describe("Mobile clarification multiline answer", () => {
expect(collapseBox.width).toBeGreaterThanOrEqual(44);
expect(idleSubmitBox.x).toBeGreaterThanOrEqual(headerBox.x);
expect(collapseBox.x + collapseBox.width).toBeLessThanOrEqual(headerBox.x + headerBox.width);
await submit.tap();
await expect(submit).toContainText("Submitting");
await expect(submit).toBeDisabled();
await expect(submit.locator('[role="status"]')).toBeVisible();
await expect(submit.locator('[role="status"]')).toHaveAttribute("aria-hidden", "true");
await expect(submit.locator("svg.tabler-icon-check")).toHaveCount(0);
const pendingSubmitBox = await submit.boundingBox();
if (!pendingSubmitBox) {
throw new Error("expected pending mobile clarification Submit button to have a bounding box");
}
await expect(
testPage.evaluate(
() => document.documentElement.scrollWidth <= document.documentElement.clientWidth,
),
).resolves.toBe(true);
try {
await submit.tap();
await expect(submit).toContainText("Submitting");
await expect(submit).toBeDisabled();
const status = session.clarificationSubmittingStatus();
await expect(status).toBeVisible();
await expect(status).toHaveAttribute("aria-label", "Submitting…");
await expect(status).not.toHaveAttribute("aria-hidden");
await expect(submit).toHaveAttribute("aria-label", "Submit");
await expect(submit.locator('[role="status"]')).toHaveCount(0);
await expect(submit.locator("svg.tabler-icon-check")).toHaveCount(0);
const statusPrecedesSkip = await header.evaluate((node) => {
const submitting = node.querySelector('[data-testid="clarification-submitting-status"]');
const headerSkip = node.querySelector('[data-testid="clarification-skip"]');
return Boolean(
submitting &&
headerSkip &&
submitting.compareDocumentPosition(headerSkip) & Node.DOCUMENT_POSITION_FOLLOWING,
);
});
expect(statusPrecedesSkip).toBe(true);
const [pendingSubmitBox, pendingSkipBox, pendingCollapseBox] = await Promise.all([
submit.boundingBox(),
skip.boundingBox(),
collapse.boundingBox(),
]);
if (!pendingSubmitBox || !pendingSkipBox || !pendingCollapseBox) {
throw new Error("expected pending mobile clarification controls to have bounding boxes");
}
expect(pendingSkipBox.height).toBeGreaterThanOrEqual(44);
expect(pendingSkipBox.width).toBeGreaterThanOrEqual(44);
expect(pendingCollapseBox.height).toBeGreaterThanOrEqual(44);
expect(pendingCollapseBox.width).toBeGreaterThanOrEqual(44);
await expect(
testPage.evaluate(
() => document.documentElement.scrollWidth <= document.documentElement.clientWidth,
),
).resolves.toBe(true);
expect(idleSubmitBox.height).toBeGreaterThanOrEqual(44);
expect(pendingSubmitBox.height).toBeGreaterThanOrEqual(44);
expect(Math.abs(pendingSubmitBox.height - idleSubmitBox.height)).toBeLessThanOrEqual(1);
@@ -0,0 +1,135 @@
---
created: 2026-08-30
status: done
requirements:
- REQ-UI-CLARIFICATION-SUBMIT-FEEDBACK-001
system_design:
- ../../specs/ui/system-design/clarification-submit-feedback.md
legacy_specs: []
---
# Implementation Plan: Clarification Header Submitting Status
## Overview
Move the clarification's animated pending indicator into the shared expanded
header immediately before Skip. Implement the shared component and its focused
test first, then update the existing desktop and mobile Playwright coverage so
single-question auto-submit and multi-question explicit submit prove the same
status contract.
## Scope
### In scope
- Show one translated, accessible spinner in the expanded clarification header
for every in-flight answer request.
- Preserve the multi-question Submit button's disabled pending label while
moving its animated indicator to the shared header position.
- Cover task chat and Quick Chat through their shared clarification component.
- Preserve desktop density, mobile action-row geometry, coarse-pointer targets,
and the existing response lifecycle.
### Out of scope
- Backend, API, persistence, WebSocket, and submission-state changes.
- New or changed translations.
- New single-question Submit controls or collapsed-header pending feedback.
- Changes to Skip, Collapse, custom-answer Send, or retry semantics.
## Technical approach
### Shared clarification header
- Update
`apps/web/components/task/chat/clarification-overlay-header.tsx` so
`ClarificationHeaderActions` conditionally renders `Spinner` as a sibling
immediately before `ClarificationSkipButton`.
- Give the spinner `data-testid="clarification-submitting-status"` and the
translated `task:submitting` value as its accessible label. Keep it exposed
to assistive technology for every bundle.
- Keep the multi-question button's pending text and disabled state, and give it
the normal translated `task:submit` value as a stable accessible name while
its visible label changes. Replace its in-button pending spinner branch with
no icon so only the header status animates, while the idle `IconCheck` remains
unchanged.
- Do not add viewport-specific state or composition. The current action group
already positions new siblings before Skip on desktop and in the mobile
action row.
### Focused component proof
- Extend
`apps/web/components/task/chat/clarification-panel-section.test.tsx` with a
held single-question response. Assert the header status is absent at idle,
appears after choosing an option, precedes Skip in DOM order, and exposes the
translated submitting label.
- Keep the response pending for the assertion and resolve it during test cleanup
so the test does not leak asynchronous work.
### Desktop and mobile E2E proof
- Add a held-response single-question scenario to
`apps/web/e2e/tests/chat/clarification.spec.ts`. Assert the status is inside
the expanded header, precedes Skip, then disappears through normal resolution.
- Update the existing multi-question submitting test in the same file to scope
the status to the header rather than the Submit button while retaining the
button label, disabled state, and missing-check assertions.
- Add the equivalent single-question scenario to
`apps/web/e2e/tests/chat/mobile-clarification.spec.ts`. Use the configured
Pixel 5 project and assert control order, 44px Skip and Collapse targets,
containment, and no document horizontal overflow.
- Update the existing mobile multi-question geometry scenario for the header
status location without weakening its action-row and stable-height checks.
- Add a `clarificationSubmittingStatus()` locator to
`apps/web/e2e/pages/session-page.ts` if repeated selector use makes the page
object clearer.
## Tests
- `AC-UI-CLARIFICATION-SUBMIT-FEEDBACK-001.1` through `.7`: focused component
coverage in `clarification-panel-section.test.tsx` proves immediate
single-question state mapping, ordering, accessible naming, multi-question
stable button naming, and failure recovery.
- `AC-UI-CLARIFICATION-SUBMIT-FEEDBACK-001.1` through `.8`: desktop Playwright
coverage proves both auto-submit and explicit multi-question submit against a
held response.
## E2E tests
- `AC-UI-CLARIFICATION-SUBMIT-FEEDBACK-001.1` through `.8`: Chromium runs the
single- and multi-question submitting-status scenarios in
`tests/chat/clarification.spec.ts`.
- `AC-UI-CLARIFICATION-SUBMIT-FEEDBACK-001.8` through `.10`: `mobile-chrome`
runs the single-question status scenario and the existing multi-question
geometry scenario in `tests/chat/mobile-clarification.spec.ts`.
## Work orders
- [x] [Task 01: Show clarification header submitting status](task-01-show-header-submitting-status.md)
## Verification results
Implementation and focused verification passed:
- Dependencies bootstrapped with `pnpm install --frozen-lockfile` from `apps/`.
- Focused clarification component tests passed: 14 tests.
- Web typecheck passed.
- Focused ESLint and Prettier checks passed for the changed web and E2E files.
- Focused Chromium E2E passed: 2 tests covering single-question header status
and multi-question submitting behavior.
- Focused `mobile-chrome` E2E passed: 2 tests covering single-question header
status and multi-question mobile geometry.
- `git diff --check` passed.
## Risks
- The design-system spinner defaults to an English accessible label. The
implementation must override it with the existing translated submitting
value instead of hiding it. Multi-question Submit must keep a stable
translated accessible name while its visible pending label changes.
- Multi-question tests currently scope the spinner inside Submit; they must be
updated together with the component so assertions cannot pass on a stale or
duplicate indicator or unstable button name.
- Held-response tests must always release their route in cleanup to avoid
hanging the managed Playwright worker.
@@ -0,0 +1,131 @@
---
id: "01-show-header-submitting-status"
title: "Show clarification header submitting status"
status: done
wave: 1
depends_on: []
plan: "plan.md"
requirements:
- REQ-UI-CLARIFICATION-SUBMIT-FEEDBACK-001
acceptance_criteria:
- AC-UI-CLARIFICATION-SUBMIT-FEEDBACK-001.1
- AC-UI-CLARIFICATION-SUBMIT-FEEDBACK-001.2
- AC-UI-CLARIFICATION-SUBMIT-FEEDBACK-001.3
- AC-UI-CLARIFICATION-SUBMIT-FEEDBACK-001.4
- AC-UI-CLARIFICATION-SUBMIT-FEEDBACK-001.5
- AC-UI-CLARIFICATION-SUBMIT-FEEDBACK-001.6
- AC-UI-CLARIFICATION-SUBMIT-FEEDBACK-001.7
- AC-UI-CLARIFICATION-SUBMIT-FEEDBACK-001.8
- AC-UI-CLARIFICATION-SUBMIT-FEEDBACK-001.9
- AC-UI-CLARIFICATION-SUBMIT-FEEDBACK-001.10
system_design:
- ../../specs/ui/system-design/clarification-submit-feedback.md
---
# Task 01: Show Clarification Header Submitting Status
## Summary
Render the clarification answer's in-flight spinner in the shared expanded
header immediately before Skip, including single-question auto-submit. Prove
the shared state on desktop and mobile while preserving the current submission
lifecycle and responsive geometry.
## In scope
- Add the translated, accessible header status and stable test identifier.
- Remove the duplicate animated icon from the multi-question Submit button
while retaining its pending label, disabled state, and idle check behavior.
- Add focused component coverage for single-question state and header order.
- Add or update desktop and Pixel 5 Playwright coverage for single- and
multi-question submission states.
## Out of scope
- Backend or clarification-state changes.
- Translation catalog changes.
- Collapsed-header progress, new controls, or changed Skip, Collapse, Send, and
retry behavior.
## Acceptance
- A held single-question or multi-question answer request shows exactly one
animated status in the expanded header immediately before Skip, and idle
state shows none. The status remains announced for both bundle types.
- The status has the translated submitting accessible name; multi-question
Submit remains disabled with its visible pending label, stable normal submit
accessible name, and no idle check.
- Desktop and Pixel 5 flows retain existing control order, touch targets,
containment, lack of horizontal overflow, successful resolution, and retry
behavior.
## Verification
Bootstrap once from the repository root if workspace dependencies are absent:
```bash
(cd apps && pnpm install --frozen-lockfile)
```
Run the focused checks from the repository root:
```bash
(cd apps/web && pnpm exec vitest run components/task/chat/clarification-panel-section.test.tsx)
(cd apps/web && pnpm run typecheck)
(cd apps/web && pnpm exec eslint components/task/chat/clarification-overlay-header.tsx components/task/chat/clarification-panel-section.test.tsx e2e/pages/session-page.ts e2e/tests/chat/clarification.spec.ts e2e/tests/chat/mobile-clarification.spec.ts)
(cd apps/web && pnpm exec prettier --check components/task/chat/clarification-overlay-header.tsx components/task/chat/clarification-panel-section.test.tsx e2e/pages/session-page.ts e2e/tests/chat/clarification.spec.ts e2e/tests/chat/mobile-clarification.spec.ts)
(cd apps/web && pnpm e2e:run --project chromium tests/chat/clarification.spec.ts -- --grep "header submitting status|question shortcuts stay disabled while answers are submitting")
(cd apps/web && pnpm e2e:run --project mobile-chrome tests/chat/mobile-clarification.spec.ts -- --grep "header submitting status|separates batch actions from the stepper")
git diff --check
```
## Files likely touched
- `apps/web/components/task/chat/clarification-overlay-header.tsx`
- `apps/web/components/task/chat/clarification-panel-section.test.tsx`
- `apps/web/e2e/pages/session-page.ts`
- `apps/web/e2e/tests/chat/clarification.spec.ts`
- `apps/web/e2e/tests/chat/mobile-clarification.spec.ts`
## Dependencies
None.
## Risks
- The spinner's default English accessible label must be overridden with the
existing translated submitting value.
- Response-hold cleanup must release every pending test route after assertions,
including failure paths.
## Parallelism
`sequential`
## Inputs
- `REQ-UI-CLARIFICATION-SUBMIT-FEEDBACK-001` and all acceptance criteria.
- The paired system design's component, control-flow, responsive, and
verification sections.
- Existing `useClarificationGroup` submit-state behavior and clarification E2E
response-hold patterns.
## Results
Implemented the shared expanded-header submitting status. The multi-question
Submit button retains its visible pending label and disabled state with a
stable normal submit accessible name, while single- and multi-question desktop
and mobile coverage verifies the shared header location, accessible label,
control order, touch targets, containment, overflow, and successful resolution.
Focused component coverage also verifies failure recovery. Held-response tests
release their routes in cleanup, including assertion failure paths.
Verification passed:
- `pnpm install --frozen-lockfile` from `apps/`.
- Focused clarification component tests: 14 tests passed.
- Web typecheck passed.
- Focused ESLint and Prettier checks passed.
- Focused Chromium E2E: 2 tests passed.
- Focused `mobile-chrome` E2E: 2 tests passed.
- `git diff --check` passed.
+4 -6
View File
@@ -15,12 +15,9 @@ The UI system owns web presentation.
## Ownership
This system owns navigation, settings, boards, task/review surfaces,
walkthroughs, chat controls, visual feedback, and responsive interaction
contracts without backend-state ownership.
Controls for provider/task state remain owned by that system.
The UI system owns reusable contracts.
The UI system owns reusable navigation, settings, task/review, chat, visual
feedback, and responsive interaction contracts. Provider and task state remain
with their owning systems.
## Exclusions
@@ -148,6 +145,7 @@ The UI system owns reusable contracts.
### System design
- [Clarification submit feedback](system-design/clarification-submit-feedback.md)
- [Growing Dialog Content Containment](system-design/dialog-content-containment.md)
- [Agent Todo List Panel](system-design/agent-todo-list-panel.md)
- [App Status Bar](system-design/app-status-bar.md)
@@ -5,91 +5,76 @@ created: 2026-08-20
owners:
- kandev
---
# Clarification submit feedback Requirements
# Clarification Submit Feedback Requirements
## Overview
When a multi-question clarification is submitted, the chat button changes to `Submitting...` and becomes disabled, but its completion check icon remains. The button needs a clear in-flight signal while the response is pending. On phone viewports, progress and batch actions also need distinct rows so the pending action does not collide with the stepper or fall below standard touch-target sizing.
The shared clarification overlay must show visible progress whenever an answer
is being submitted. The UI system owns this presentation contract because the
same feedback is used by task chat and Quick Chat without changing the task
system's clarification state or response lifecycle.
## Terminology
- **Header submitting status:** The animated status indicator in the expanded
clarification header's action cluster.
- **Skip control:** The X-shaped action that rejects the pending clarification.
## Requirements
### REQ-UI-CLARIFICATION-SUBMIT-FEEDBACK-001: Clarification submit feedback
**Intent:** When a multi-question clarification is submitted, the chat button changes to `Submitting...` and becomes disabled, but its completion check icon remains. The button needs a clear in-flight signal while the response is pending.
**Intent:** Operators can tell that their answer is being submitted during a
slow response, including single-question flows that have no Submit button.
**User story:** As an operator answering an agent question, I want immediate
submission feedback, so that I know my answer was accepted for processing.
#### Acceptance criteria
- **AC-UI-CLARIFICATION-SUBMIT-FEEDBACK-001.1:** The shared clarification overlay keeps the translated `Submitting...` label while its answer request is in flight.
- **AC-UI-CLARIFICATION-SUBMIT-FEEDBACK-001.2:** While submitting, the multi-question Submit button is disabled and shows the shared animated loading spinner in place of the completion check icon.
- **AC-UI-CLARIFICATION-SUBMIT-FEEDBACK-001.3:** When the overlay is idle and answerable, the button keeps its existing translated Submit label and completion check icon.
- **AC-UI-CLARIFICATION-SUBMIT-FEEDBACK-001.4:** The same behavior applies to task chat and Quick Chat on desktop and mobile, because they share the clarification overlay header.
- **AC-UI-CLARIFICATION-SUBMIT-FEEDBACK-001.5:** If submission fails and the clarification remains visible, the spinner stops, the button returns to its existing retryable Submit state, and no new error behavior is introduced.
- **AC-UI-CLARIFICATION-SUBMIT-FEEDBACK-001.6:** **GIVEN** every question in a multi-question clarification has an answer, **WHEN** the operator submits the answers and the response request remains pending, **THEN** the Submit button is disabled, retains the `Submitting...` label, shows an animated loading status, and does not show the completion check icon.
- **AC-UI-CLARIFICATION-SUBMIT-FEEDBACK-001.7:** **GIVEN** a pending submission succeeds, **WHEN** the response is accepted, **THEN** the clarification resolves as it does today and the submitting indicator is no longer rendered.
- **AC-UI-CLARIFICATION-SUBMIT-FEEDBACK-001.8:** **GIVEN** a pending submission fails, **WHEN** the response returns an error, **THEN** the clarification remains available, the spinner is removed, and the existing Submit action is available for retry.
- **AC-UI-CLARIFICATION-SUBMIT-FEEDBACK-001.9:** On coarse-pointer viewports, the multi-question Submit button remains at least 44px tall in both idle and submitting states, retains its height between those states, and centers its label and status icon.
- **AC-UI-CLARIFICATION-SUBMIT-FEEDBACK-001.10:** On phone viewports, the stepper and answered count occupy a progress row above a distinct full-width action row; the Submit action uses the available width, Skip and Collapse remain at least 44px in each dimension, and no action overlaps or causes horizontal overflow.
- **AC-UI-CLARIFICATION-SUBMIT-FEEDBACK-001.11:** Fine-pointer desktop viewports retain the compact inline header layout and control dimensions.
## Migrated source detail
## Why
When a multi-question clarification is submitted, the chat button changes to
`Submitting...` and becomes disabled, but its completion check icon remains.
The button needs a clear in-flight signal while the response is pending.
On a touch viewport, that pending-state control can be only about 24px tall
beside the 44px clarification controls. Keeping progress and actions on the
same row also crowds the loading label, spinner, Skip, and Collapse controls.
## What
- The shared clarification overlay keeps the translated `Submitting...` label
while its answer request is in flight.
- While submitting, the multi-question Submit button is disabled and shows the
shared animated loading spinner in place of the completion check icon.
- When the overlay is idle and answerable, the button keeps its existing
translated Submit label and completion check icon.
- The same behavior applies to task chat and Quick Chat on desktop and mobile,
because they share the clarification overlay header.
- On coarse-pointer viewports, the multi-question Submit button remains at
least 44px tall in both its idle and submitting states, with its label and
status icon centered inside the control.
- On phone viewports, progress stays on a row above the full-width batch action
row. Skip and Collapse retain 44px touch targets without crowding Submit.
- Fine-pointer desktop viewports keep the compact inline header dimensions.
- If submission fails and the clarification remains visible, the spinner stops,
the button returns to its existing retryable Submit state, and no new error
behavior is introduced.
## Scenarios
- **GIVEN** every question in a multi-question clarification has an answer,
**WHEN** the operator submits the answers and the response request remains
pending, **THEN** the Submit button is disabled, retains the `Submitting...`
label, shows an animated loading status, and does not show the completion
check icon.
- **GIVEN** a pending submission succeeds, **WHEN** the response is accepted,
**THEN** the clarification resolves as it does today and the submitting
indicator is no longer rendered.
- **GIVEN** a pending submission fails, **WHEN** the response returns an error,
**THEN** the clarification remains available, the spinner is removed, and
the existing Submit action is available for retry.
- **GIVEN** the same multi-question clarification is rendered in a phone
viewport, **WHEN** its answer request is pending, **THEN** the loading status
remains visible inside a Submit button that is at least 44px tall, retains
its idle-state height, and occupies the action row below progress without
overlap or horizontal overflow.
- **GIVEN** the clarification is rendered on a fine-pointer desktop viewport,
**WHEN** Submit changes between idle and pending states, **THEN** its compact
inline dimensions and behavior remain unchanged.
- **AC-UI-CLARIFICATION-SUBMIT-FEEDBACK-001.1:** When any clarification answer
request is in flight, the expanded clarification header shall show an
animated submitting status immediately before the Skip control.
- **AC-UI-CLARIFICATION-SUBMIT-FEEDBACK-001.2:** The header submitting status
shall appear for option and custom-text answers in both single-question and
multi-question clarification bundles.
- **AC-UI-CLARIFICATION-SUBMIT-FEEDBACK-001.3:** The header submitting status
shall carry the existing translated submitting label as its accessible name
and remain exposed to assistive technology for both single-question and
multi-question bundles. For multi-question bundles, the Submit button shall
keep the normal translated submit label as its accessible name while its
visible label changes to the translated submitting label.
- **AC-UI-CLARIFICATION-SUBMIT-FEEDBACK-001.4:** While a multi-question answer
request is in flight, the Submit button shall remain disabled, keep the
normal translated submit label as its accessible name, show its translated
submitting label visibly, omit its idle completion check, and defer the
animated status indicator to the header position.
- **AC-UI-CLARIFICATION-SUBMIT-FEEDBACK-001.5:** When no answer request is in
flight, the header submitting status shall not be visible and the existing
idle clarification controls shall remain unchanged.
- **AC-UI-CLARIFICATION-SUBMIT-FEEDBACK-001.6:** When submission succeeds, the
clarification shall resolve through its existing lifecycle and the submitting
status shall be removed with the overlay.
- **AC-UI-CLARIFICATION-SUBMIT-FEEDBACK-001.7:** When submission fails and the
clarification remains visible, the submitting status shall stop, and the
existing answer controls shall become available for retry.
- **AC-UI-CLARIFICATION-SUBMIT-FEEDBACK-001.8:** Task chat and Quick Chat shall
render the same submitting feedback on fine-pointer desktop and coarse-pointer
mobile surfaces.
- **AC-UI-CLARIFICATION-SUBMIT-FEEDBACK-001.9:** The submitting status shall not
overlap the Skip or Collapse controls, cause horizontal overflow, or reduce
the existing coarse-pointer touch targets.
- **AC-UI-CLARIFICATION-SUBMIT-FEEDBACK-001.10:** Fine-pointer desktop surfaces
shall retain the existing compact clarification header dimensions and control
order apart from the transient status inserted before Skip.
## Out of scope
- Changing the clarification response API, submission lifecycle, or duplicate
request guard.
- Changing the existing `Submitting...` translation or adding new copy.
- Adding a header Submit button to single-question clarifications.
- Changing custom-answer Send behavior, Skip or Collapse semantics, or other
loading states.
- Adding new user-facing copy or changing the existing translated submitting
label.
- Adding a Submit button to single-question clarifications.
- Changing custom-answer Send, Skip, Collapse, or collapsed-header semantics.
- Adding submission feedback to the collapsed clarification header.
@@ -0,0 +1,119 @@
---
status: current
system: ui
requirements:
- REQ-UI-CLARIFICATION-SUBMIT-FEEDBACK-001
---
# Clarification Submit Feedback System Design
## Purpose and boundaries
The UI system owns the visible in-flight feedback for the shared clarification
overlay. The task and clarification services continue to own the pending
question, response endpoint, winner selection, and resume lifecycle. This
design changes no backend contract, persisted state, or WebSocket event.
## Requirement mapping
| Requirement | Design section |
| --- | --- |
| `REQ-UI-CLARIFICATION-SUBMIT-FEEDBACK-001` | [Components and responsibilities](#components-and-responsibilities), [Control flow](#control-flow), [Responsive and accessible presentation](#responsive-and-accessible-presentation), and [Failure and recovery](#failure-and-recovery) |
## Components and responsibilities
- `useClarificationGroup` remains the owner of the local `submitState` and the
single in-flight request guard. It synchronously enters `submitting` before
awaiting the response.
- `ClarificationInputOverlay` derives `isSubmitting` from that state and passes
it to the existing shared header and question controls.
- `ClarificationHeaderActions` renders one design-system `Spinner` immediately
before `ClarificationSkipButton` while `isSubmitting` is true. This position
exists for both single-question and multi-question bundles, and the spinner
remains exposed to assistive technology for both bundle types.
- The multi-question Submit button retains its translated pending label and
disabled behavior, but keeps the normal translated submit label as its
accessible name while the pending label changes visually. It does not render
a second spinner, and its idle completion check is absent while the request
is pending.
- Task chat and Quick Chat continue to compose the same
`ClarificationPanelSection`, so they receive identical behavior without
surface-specific state or handlers.
## Data and contracts
No wire or persistence contract changes. The presentation consumes the existing
`SubmitState` values `idle`, `submitting`, `ok`, and `error` through the current
`isSubmitting` boolean.
The header spinner receives the existing translated `task:submitting` value as
its accessible name and remains announced for every bundle. The multi-question
Submit button receives the normal translated `task:submit` value as a stable
accessible name while its visible label changes to the pending value. A stable
`clarification-submitting-status` test identifier anchors component and
Playwright assertions without using translated text as a selector.
## Control flow
1. A single-question option or custom-text action calls
`submitCollected` immediately, or a fully answered multi-question bundle
calls it from the explicit Submit action.
2. `runClarificationRequest` sets `submitState` to `submitting` before awaiting
the response.
3. React re-renders the expanded header with the submitting status before the
Skip control. Answer controls remain protected by the current disabled and
in-flight guards.
4. A successful response applies the existing resolved status and closes the
clarification. An error returns `submitState` to `error`, which removes the
spinner and restores the existing retry path.
## Responsive and accessible presentation
The existing header composition remains shared across viewport classes. On
fine-pointer desktop, the small non-interactive status joins the compact action
cluster without changing the dimensions of Skip, Collapse, or the
multi-question Submit button. On coarse pointers, the existing 44px Skip and
Collapse targets and the full-width multi-question action row remain intact.
The status occupies its own flex item immediately before Skip and must not
become a touch target.
The design-system spinner keeps `role="status"`, and its accessible name uses
the translated submitting label for every bundle. The multi-question Submit
button keeps a stable accessible name with the normal translated submit label,
so the visible pending-label change does not compete with the header status
announcement. Rendered desktop and Pixel 5 tests verify its order,
containment, and absence of document-level horizontal overflow.
## Failure and recovery
Network and non-success responses continue to produce the existing `error`
state. The header status is conditional only on `submitting`, so it stops
without a separate cleanup path. Existing answer state and retry behavior
remain unchanged.
Collapsing the clarification while a request is pending retains today's compact
header behavior; this design does not project submit state into that collapsed
surface.
## Verification strategy
- A focused component test holds a single-question response and verifies that
the status appears before Skip, uses the translated accessible label, and is
removed outside the in-flight state.
- A focused component test verifies that a multi-question status remains
announced and that its Submit button keeps a stable accessible name while a
failed request removes the status and re-enables Skip.
- Desktop Playwright coverage holds a single-question response to prove the
status is visible in the expanded header before the Skip control, then
releases the response and verifies normal resolution.
- Existing desktop multi-question coverage moves its spinner assertion from
the Submit button to the shared header while retaining disabled-label and
idle-check assertions.
- Pixel 5 coverage proves the same single-question feedback, control order,
touch-target preservation, and lack of horizontal overflow. Existing
multi-question geometry coverage is updated for the new spinner location.
## Security
The change introduces no new input, authorization decision, data exposure, or
external side effect.