120 lines
5.7 KiB
Markdown
120 lines
5.7 KiB
Markdown
---
|
|
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.
|