d17812fdb1
Co-authored-by: ayattara <alassane.yattara@savoirfairelinux.com> Co-authored-by: Carlos Florencio <carlosmflorencio@gmail.com>
88 lines
4.1 KiB
Markdown
88 lines
4.1 KiB
Markdown
---
|
|
status: active
|
|
system: ui
|
|
created: 2026-09-03
|
|
owners:
|
|
- kandev
|
|
---
|
|
|
|
# Changes File Action Feedback Requirements
|
|
|
|
## Overview
|
|
|
|
Working-tree file rows expose stage and unstage actions in the Changes panel.
|
|
On fine-pointer layouts, the action shares the file-type icon slot and normally
|
|
appears only while the row is hovered. Once an action starts, its progress
|
|
feedback must remain visible until the associated request finishes, even when
|
|
the pointer leaves the row. The UI system owns this transient presentation
|
|
contract and the per-file pending lifetime that drives it; Git operation
|
|
execution and refreshed repository status remain owned by their existing
|
|
systems.
|
|
|
|
## Terminology
|
|
|
|
- **File action slot:** The leading Changes-row position that shows either the
|
|
file-type icon, the stage or unstage action, or its pending indicator.
|
|
- **Pending file action:** The latest stage or unstage request within the active
|
|
session, environment, and checked-out branch generation that owns the pending
|
|
state for one repository and file and has not reached its target state or
|
|
failed.
|
|
|
|
## Requirements
|
|
|
|
### REQ-UI-CHANGES-FILE-ACTION-FEEDBACK-001: Persistent pending file-action feedback
|
|
|
|
**Intent:** Let users identify which file operation is still running without
|
|
keeping the pointer over its row.
|
|
|
|
**User story:** As a user staging or unstaging a file, I want its progress
|
|
indicator to remain visible until the operation finishes, so that I know when
|
|
the action is complete.
|
|
|
|
#### Acceptance criteria
|
|
|
|
- **AC-UI-CHANGES-FILE-ACTION-FEEDBACK-001.1:** When a user starts a stage or
|
|
unstage action for one file, that row shall replace its stage or unstage
|
|
control with the existing animated pending indicator for the lifetime of the
|
|
file's pending state.
|
|
- **AC-UI-CHANGES-FILE-ACTION-FEEDBACK-001.2:** On a fine-pointer layout, moving
|
|
the pointer away from a row with a pending file action shall keep the pending
|
|
indicator visible and shall not restore the file-type icon while the action
|
|
remains pending.
|
|
- **AC-UI-CHANGES-FILE-ACTION-FEEDBACK-001.3:** Pending feedback shall remain
|
|
scoped to the acted-on repository and file. Other file rows shall retain
|
|
their current icons and actions.
|
|
- **AC-UI-CHANGES-FILE-ACTION-FEEDBACK-001.4:** When the pending state clears,
|
|
the row shall return to its current idle presentation or move to the section
|
|
that reflects the refreshed staged state.
|
|
- **AC-UI-CHANGES-FILE-ACTION-FEEDBACK-001.5:** Coarse-pointer Changes surfaces
|
|
shall retain their always-visible, touch-sized file actions and show the same
|
|
pending indicator without introducing a hover dependency or reducing the
|
|
existing touch target.
|
|
- **AC-UI-CHANGES-FILE-ACTION-FEEDBACK-001.6:** A successful stage or unstage
|
|
request shall remain pending through stale status updates and clear only after
|
|
both the successful request response and refreshed status reach the requested
|
|
staged or unstaged state. Either signal may arrive first.
|
|
- **AC-UI-CHANGES-FILE-ACTION-FEEDBACK-001.7:** When the current stage or
|
|
unstage request fails, its pending feedback shall clear. If a newer request in
|
|
either direction has superseded it for the same repository and file, the
|
|
older request's completion or failure shall not clear the newer request's
|
|
pending feedback.
|
|
- **AC-UI-CHANGES-FILE-ACTION-FEEDBACK-001.8:** When one request spans multiple
|
|
repositories and only some repository scopes fail, failed scopes shall clear
|
|
immediately while successful scopes remain pending until their refreshed
|
|
status reaches the requested state.
|
|
- **AC-UI-CHANGES-FILE-ACTION-FEEDBACK-001.9:** Pending ownership shall reset
|
|
when the active session, environment, checked-out branch generation, or
|
|
workspace source generation changes. A callback from the prior scope shall
|
|
not add, retain, or clear feedback in the successor scope.
|
|
|
|
## Out of scope
|
|
|
|
- Changing Git stage or unstage execution, transport, or repository status
|
|
refresh.
|
|
- Changing discard, edit, commit, or stage-all control presentation.
|
|
- Adding user-facing copy, notifications, cancellation, or progress estimates.
|
|
- Changing Changes-panel navigation, grouping, row density, or scroll
|
|
ownership.
|