Prevent edit actions while a replacement document is importing
Import sets isLoading but leaves isEditable true. A user types while the asynchronous parser runs, then the parsed document replaces those edits without a warning.
- Focused work estimate
- 2h 30m + prerequisites
- Priority in the scenario
- High
- Engineering practice
- State machines · Race handling · Accessible feedback
Estimated field mix
- Frontend70%
- Accessibility30%
Field percentages are editorial estimates of the ticket's engineering focus. They total 100%; they are not measured time, proficiency scores, or ownership evidence.
Pattern topics
- StateApply
Represent import lifecycle and command eligibility with explicit states so contradictory loading/editing flags cannot erase user work.
Review it, then add it to your workspace.
The board opens an editable draft; nothing is saved until you confirm it. Sign-in and workspace permissions apply, and Demo boards remain ephemeral.
Project context
A fictional support team edits reusable troubleshooting documents with paragraphs, links, and nested sections. The browser prototype has separate toolbar and keyboard handlers, an unreliable undo stack, and mutable shared formatting objects. Create a local editor and synthetic documents; no starter assets, rich-text engine, collaborative backend, or production service is supplied.
Setup prerequisites
- Browser events
- Immutable updates
- Accessible form controls
Preceding work
Complete these dependencies, or supply their agreed outputs before taking this ticket.
- PDOC-101 · Give nested sections and paragraphs one structural contract
- PDOC-103 · Route toolbar and keyboard deletion through one command
- PDOC-104 · Restore selection together with content when undoing a deletion
- PDOC-105 · Stop closed editor tabs from receiving document updates
- PDOC-106 · Untangle the toolbar's direct calls into three side panels
Acceptance criteria
- Define explicit ready, importing, and import-failed states and legal transitions, including cancel and retry.
- Edit commands are rejected during replacement import, and controls expose their disabled reason accessibly.
- A failed or cancelled import preserves the prior document and selection; a late result from a cancelled attempt cannot replace them.
Implementation constraints
- A tagged union and transition function can implement State semantics; separate state representation from parsing work.
Verification to include
- Delay parsing, attempt a keyboard edit, and verify no hidden edit or unexpected replacement occurs.
- Cancel one import, start another, then resolve results in reverse order; only the current successful attempt may install a document.
Deliverables
- Import state transitions and delayed-result interaction tests
Rollout and recovery
Replace boolean flags with the explicit local state model; keep the last valid document available until a replacement commits.
Value of the work
For the engineer: Practice relating object and state patterns to real UI behavior, including undo semantics, bounded traversal, lifecycle cleanup, and memory tradeoffs.
For the team: Review whether editor changes preserve user work, keep controls consistent, and reduce maintenance effort without concealing document corruption.
Evidence boundaries
Outcome Evidence: Tests, patches, and runbooks are requested deliverables. They become Outcome Evidence only through a qualified Mission and immutable Evidence IDs.
Ownership Evidence: Independent adaptation must be observed under a declared verification policy and cite immutable Evidence IDs. Completing a planning ticket establishes no Ownership Evidence.