Add JSON import/export for full encounter state
Export and import encounter, undo/redo history, and player characters as a downloadable .json file. Export/import actions are in the action bar overflow menu. Import validates using existing rehydration functions and shows a confirmation dialog when replacing a non-empty encounter. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Lukas
34
specs/007-json-import-export/checklists/requirements.md
Normal file
34
specs/007-json-import-export/checklists/requirements.md
Normal file
@@ -0,0 +1,34 @@
|
||||
# Specification Quality Checklist: JSON Import/Export
|
||||
|
||||
**Purpose**: Validate specification completeness and quality before proceeding to planning
|
||||
**Created**: 2026-03-27
|
||||
**Feature**: [spec.md](../spec.md)
|
||||
|
||||
## Content Quality
|
||||
|
||||
- [x] No implementation details (languages, frameworks, APIs)
|
||||
- [x] Focused on user value and business needs
|
||||
- [x] Written for non-technical stakeholders
|
||||
- [x] All mandatory sections completed
|
||||
|
||||
## Requirement Completeness
|
||||
|
||||
- [x] No [NEEDS CLARIFICATION] markers remain
|
||||
- [x] Requirements are testable and unambiguous
|
||||
- [x] Success criteria are measurable
|
||||
- [x] Success criteria are technology-agnostic (no implementation details)
|
||||
- [x] All acceptance scenarios are defined
|
||||
- [x] Edge cases are identified
|
||||
- [x] Scope is clearly bounded
|
||||
- [x] Dependencies and assumptions identified
|
||||
|
||||
## Feature Readiness
|
||||
|
||||
- [x] All functional requirements have clear acceptance criteria
|
||||
- [x] User scenarios cover primary flows
|
||||
- [x] Feature meets measurable outcomes defined in Success Criteria
|
||||
- [x] No implementation details leak into specification
|
||||
|
||||
## Notes
|
||||
|
||||
- All items pass. Spec is ready for `/speckit.clarify` or `/speckit.plan`.
|
||||
102
specs/007-json-import-export/data-model.md
Normal file
102
specs/007-json-import-export/data-model.md
Normal file
@@ -0,0 +1,102 @@
|
||||
# Data Model: JSON Import/Export
|
||||
|
||||
**Feature**: 007-json-import-export
|
||||
**Date**: 2026-03-27
|
||||
|
||||
## Entities
|
||||
|
||||
### ExportBundle
|
||||
|
||||
The top-level structure written to and read from `.json` files. Contains all exportable application state.
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|--------------------|----------------------|----------|--------------------------------------------------|
|
||||
| version | number | Yes | Format version (starts at 1) |
|
||||
| exportedAt | string (ISO 8601) | Yes | Timestamp of when the export was created |
|
||||
| encounter | Encounter | Yes | Current encounter state (combatants + turn info) |
|
||||
| undoStack | Encounter[] | Yes | Undo history (encounter snapshots, max 50) |
|
||||
| redoStack | Encounter[] | Yes | Redo history (encounter snapshots) |
|
||||
| playerCharacters | PlayerCharacter[] | Yes | Player character templates |
|
||||
|
||||
### Encounter (existing)
|
||||
|
||||
Defined in `packages/domain/src/types.ts`. No changes needed — exported as-is via JSON serialization.
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|--------------|--------------|----------|--------------------------------------|
|
||||
| combatants | Combatant[] | Yes | Ordered list of combatants |
|
||||
| activeIndex | number | Yes | Index of current turn (0-based) |
|
||||
| roundNumber | number | Yes | Current round (starts at 1) |
|
||||
|
||||
### Combatant (existing)
|
||||
|
||||
Defined in `packages/domain/src/types.ts`. No changes needed.
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|--------------------|-------------------|----------|------------------------------------|
|
||||
| id | CombatantId | Yes | Unique identifier ("c-N") |
|
||||
| name | string | Yes | Display name |
|
||||
| initiative | number | No | Initiative roll result |
|
||||
| maxHp | number | No | Maximum hit points (>= 1) |
|
||||
| currentHp | number | No | Current HP (0 to maxHp) |
|
||||
| tempHp | number | No | Temporary hit points |
|
||||
| ac | number | No | Armor class (>= 0) |
|
||||
| conditions | ConditionId[] | No | Active status conditions |
|
||||
| isConcentrating | boolean | No | Concentration flag |
|
||||
| creatureId | CreatureId | No | Link to bestiary creature |
|
||||
| color | string | No | Visual color (from player char) |
|
||||
| icon | string | No | Visual icon (from player char) |
|
||||
| playerCharacterId | PlayerCharacterId | No | Link to player character template |
|
||||
|
||||
### PlayerCharacter (existing)
|
||||
|
||||
Defined in `packages/domain/src/player-character-types.ts`. No changes needed.
|
||||
|
||||
| Field | Type | Required | Description |
|
||||
|--------|-------------------|----------|-------------------------------------------|
|
||||
| id | PlayerCharacterId | Yes | Unique identifier ("pc-N") |
|
||||
| name | string | Yes | Character name |
|
||||
| ac | number | Yes | Armor class (>= 0) |
|
||||
| maxHp | number | Yes | Maximum hit points (>= 1) |
|
||||
| color | PlayerColor | No | Visual color (10 options) |
|
||||
| icon | PlayerIcon | No | Visual icon (15 options) |
|
||||
|
||||
## Validation Rules
|
||||
|
||||
### Import Validation
|
||||
|
||||
1. **Top-level structure**: Must be a JSON object with `version`, `encounter`, `undoStack`, `redoStack`, and `playerCharacters` fields.
|
||||
2. **Version check**: `version` must be a number. Unknown versions are rejected.
|
||||
3. **Encounter validation**: Delegated to existing `rehydrateEncounter()` — validates combatant structure, HP ranges, condition IDs, player colors/icons.
|
||||
4. **Undo/redo stack validation**: Each entry in both stacks is validated via `rehydrateEncounter()`. Invalid entries are silently dropped.
|
||||
5. **Player character validation**: Delegated to existing player character rehydration — validates types, ranges, color/icon enums.
|
||||
6. **Graceful degradation**: Invalid optional fields on combatants/characters are stripped (not rejected). Only structurally malformed data (missing required fields, wrong types) causes full rejection.
|
||||
|
||||
## State Transitions
|
||||
|
||||
### Export Flow
|
||||
|
||||
```
|
||||
User triggers export
|
||||
→ Read encounter from EncounterContext
|
||||
→ Read undoRedoState from EncounterContext
|
||||
→ Read playerCharacters from PlayerCharactersContext
|
||||
→ Assemble ExportBundle { version: 1, exportedAt, encounter, undoStack, redoStack, playerCharacters }
|
||||
→ Serialize to JSON
|
||||
→ Trigger browser file download
|
||||
```
|
||||
|
||||
### Import Flow
|
||||
|
||||
```
|
||||
User selects file
|
||||
→ Read file as text
|
||||
→ Parse JSON (reject on parse failure)
|
||||
→ Validate top-level structure (reject on missing fields)
|
||||
→ Validate encounter via rehydrateEncounter() (reject on null)
|
||||
→ Validate undo/redo stacks via rehydrateEncounter() per entry (filter invalid)
|
||||
→ Validate player characters via rehydration (filter invalid)
|
||||
→ If current encounter is non-empty: show confirmation dialog
|
||||
→ On confirm: replace encounter, undo/redo, and player characters in state
|
||||
→ State changes trigger existing useEffect auto-saves to localStorage
|
||||
```
|
||||
111
specs/007-json-import-export/plan.md
Normal file
111
specs/007-json-import-export/plan.md
Normal file
@@ -0,0 +1,111 @@
|
||||
# Implementation Plan: JSON Import/Export
|
||||
|
||||
**Branch**: `007-json-import-export` | **Date**: 2026-03-27 | **Spec**: [spec.md](spec.md)
|
||||
**Input**: Feature specification from `/specs/007-json-import-export/spec.md`
|
||||
|
||||
## Summary
|
||||
|
||||
Add JSON import/export for the full application state (encounter, undo/redo history, player characters). Export creates a downloadable `.json` file; import reads a file, validates it using existing rehydration functions, and replaces the current state after user confirmation. UI is integrated via the action bar overflow menu.
|
||||
|
||||
## Technical Context
|
||||
|
||||
**Language/Version**: TypeScript 5.8 (strict mode, `verbatimModuleSyntax`)
|
||||
**Primary Dependencies**: React 19, Vite 6, Tailwind CSS v4, Lucide React
|
||||
**Storage**: localStorage (encounter, undo/redo, player characters)
|
||||
**Testing**: Vitest (v8 coverage)
|
||||
**Target Platform**: Browser (desktop + mobile)
|
||||
**Project Type**: Web application (SPA)
|
||||
**Performance Goals**: Export/import completes in under 1 second for typical encounters
|
||||
**Constraints**: No server-side component; browser-only file operations
|
||||
**Scale/Scope**: Encounters with up to ~50 combatants, undo stacks of up to 50 snapshots
|
||||
|
||||
## Constitution Check
|
||||
|
||||
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
|
||||
|
||||
| Principle | Status | Notes |
|
||||
|-----------|--------|-------|
|
||||
| I. Deterministic Domain Core | PASS | No new domain logic needed. ExportBundle type is pure data. Validation reuses existing pure functions. |
|
||||
| II. Layered Architecture | PASS | Type in domain, validation in adapter layer (co-located with existing rehydration functions), file I/O and UI in adapter layer. No reverse dependencies. |
|
||||
| II-A. Context-Based State Flow | PASS | Import reads/writes state via existing contexts. No new props beyond per-instance config. |
|
||||
| III. Clarification-First | PASS | All decisions documented in research.md. No ambiguities remain. |
|
||||
| IV. Escalation Gates | PASS | Feature scope matches spec exactly. No out-of-scope additions. |
|
||||
| V. MVP Baseline Language | PASS | Format versioning and selective import noted as "not included in MVP baseline." |
|
||||
| VI. No Gameplay Rules | PASS | No gameplay mechanics involved. |
|
||||
|
||||
**Post-Phase 1 re-check**: All gates still pass. The ExportBundle type is a pure data structure in the domain layer. The validation logic lives in the adapter layer alongside existing rehydration functions (it depends on adapter-layer `rehydrateEncounter` and `rehydrateCharacter`). File I/O and UI live in the adapter layer.
|
||||
|
||||
## Project Structure
|
||||
|
||||
### Documentation (this feature)
|
||||
|
||||
```text
|
||||
specs/007-json-import-export/
|
||||
├── plan.md # This file
|
||||
├── research.md # Phase 0 output
|
||||
├── data-model.md # Phase 1 output
|
||||
├── quickstart.md # Phase 1 output
|
||||
└── tasks.md # Phase 2 output (/speckit.tasks)
|
||||
```
|
||||
|
||||
### Source Code (repository root)
|
||||
|
||||
```text
|
||||
packages/domain/src/
|
||||
├── export-bundle.ts # ExportBundle type definition
|
||||
|
||||
apps/web/src/
|
||||
├── persistence/
|
||||
│ └── export-import.ts # Export assembly + import validation + file handling
|
||||
├── hooks/
|
||||
│ └── use-encounter.ts # Existing — needs import/export state setters exposed
|
||||
├── components/
|
||||
│ ├── action-bar.tsx # Existing — add overflow menu items
|
||||
│ └── import-confirm-prompt.tsx # Confirmation dialog for import
|
||||
```
|
||||
|
||||
**Structure Decision**: Follows existing project structure. New files are minimal — one domain type, one persistence module (validation + export assembly + file handling), one UI component. Most work integrates into existing files.
|
||||
|
||||
## Implementation Phases
|
||||
|
||||
### Phase 1: ExportBundle Type + Validation Use Case
|
||||
|
||||
**Goal**: Define the export format and validation logic with full test coverage.
|
||||
|
||||
1. Create `ExportBundle` type in `packages/domain/src/export-bundle.ts`
|
||||
2. Export from domain package index
|
||||
3. Create `validateImportBundle()` in `apps/web/src/persistence/export-import.ts` — accepts `unknown`, returns validated `ExportBundle | DomainError`
|
||||
4. Import `rehydrateEncounter()` from `./encounter-storage.ts` for encounter and undo/redo stack validation
|
||||
5. Export `rehydrateCharacter()` from `player-character-storage.ts` and import it for player character validation
|
||||
6. Write tests covering: valid bundles, missing fields, invalid encounter, invalid player characters, empty stacks, unknown version
|
||||
|
||||
### Phase 2: Export Functionality
|
||||
|
||||
**Goal**: Users can download the current state as a `.json` file.
|
||||
|
||||
1. Create `export-import.ts` in `apps/web/src/persistence/`
|
||||
2. Implement `assembleExportBundle(encounter, undoRedoState, playerCharacters)` — pure function returning `ExportBundle`
|
||||
3. Implement `triggerDownload(bundle: ExportBundle)` — creates JSON blob, generates filename with date, triggers browser download
|
||||
4. Add "Export Encounter" item to action bar overflow menu
|
||||
5. Wire button to read from contexts and call export functions
|
||||
|
||||
### Phase 3: Import Functionality + Confirmation
|
||||
|
||||
**Goal**: Users can import a `.json` file with confirmation and error handling.
|
||||
|
||||
1. Add "Import Encounter" item to action bar overflow menu
|
||||
2. Implement file picker trigger (hidden `<input type="file">`)
|
||||
3. On file selected: read text, parse JSON, validate via use case
|
||||
4. If validation fails: show error toast
|
||||
5. If encounter is non-empty: show confirmation dialog
|
||||
6. On confirm (or if encounter is empty): replace encounter, undo/redo, and player characters via context setters
|
||||
7. Write integration test: export → import round-trip produces identical state
|
||||
|
||||
## Notes
|
||||
|
||||
- Import `rehydrateEncounter()` from `apps/web/src/persistence/encounter-storage.ts` for encounter validation — do not duplicate
|
||||
- Export `rehydrateCharacter()` from `apps/web/src/persistence/player-character-storage.ts` so it can be imported for player character validation
|
||||
- Follow existing file picker pattern from `apps/web/src/components/source-fetch-prompt.tsx`
|
||||
- Follow existing overflow menu pattern in `apps/web/src/components/action-bar.tsx`
|
||||
- Follow existing `<dialog>` pattern from `apps/web/src/components/settings-modal.tsx`
|
||||
- Commit after each phase checkpoint
|
||||
52
specs/007-json-import-export/quickstart.md
Normal file
52
specs/007-json-import-export/quickstart.md
Normal file
@@ -0,0 +1,52 @@
|
||||
# Quickstart: JSON Import/Export
|
||||
|
||||
**Feature**: 007-json-import-export
|
||||
**Date**: 2026-03-27
|
||||
|
||||
## Overview
|
||||
|
||||
Export and import the full application state (encounter, undo/redo history, player characters) as a JSON file. Enables backup/restore and sharing encounters between DMs.
|
||||
|
||||
## Key Concepts
|
||||
|
||||
- **ExportBundle**: A JSON object containing `version`, `exportedAt`, `encounter`, `undoStack`, `redoStack`, and `playerCharacters`. This is the file format.
|
||||
- **Full replacement**: Import replaces all existing state — encounter, undo/redo, and player characters. It's not a merge.
|
||||
- **Validation reuse**: Import validation uses the same `rehydrateEncounter()` and player character validation functions that localStorage loading uses.
|
||||
|
||||
## Implementation Layers
|
||||
|
||||
### Domain Layer
|
||||
|
||||
No new domain functions are needed. The existing types (`Encounter`, `PlayerCharacter`, `UndoRedoState`) and validation functions are reused as-is.
|
||||
|
||||
A new `ExportBundle` type is defined in the domain layer as a pure data structure.
|
||||
|
||||
### Application Layer
|
||||
|
||||
A new use case for import validation and bundle assembly:
|
||||
- `validateImportBundle(data: unknown)` — validates and rehydrates an export bundle, returning the validated bundle or an error.
|
||||
|
||||
Export assembly is straightforward enough to live in the adapter layer (it's just reading and packaging existing state).
|
||||
|
||||
### Adapter Layer (Web)
|
||||
|
||||
- **Export**: Read state from contexts, assemble bundle, trigger browser download via `URL.createObjectURL()` + anchor element.
|
||||
- **Import**: File picker input, parse JSON, delegate to application-layer validation, show confirmation dialog if encounter is non-empty, replace state via context setters.
|
||||
- **UI**: Two new overflow menu items in the action bar — "Export Encounter" and "Import Encounter".
|
||||
|
||||
## File Locations
|
||||
|
||||
| Artifact | Path |
|
||||
|----------|------|
|
||||
| ExportBundle type | `packages/domain/src/types.ts` or new file |
|
||||
| Import validation use case | `packages/application/src/` |
|
||||
| Export/import adapter functions | `apps/web/src/persistence/` |
|
||||
| UI integration | `apps/web/src/components/action-bar.tsx` |
|
||||
| Confirmation dialog | `apps/web/src/components/` (new or reuse existing confirm pattern) |
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
- **Domain**: No new domain tests needed (existing types unchanged).
|
||||
- **Application**: Test `validateImportBundle()` with valid bundles, invalid bundles, missing fields, wrong types, and edge cases (empty encounter, empty stacks).
|
||||
- **Adapter**: Test export bundle assembly and import file handling.
|
||||
- **Integration**: Round-trip test — export then import should produce identical state.
|
||||
79
specs/007-json-import-export/research.md
Normal file
79
specs/007-json-import-export/research.md
Normal file
@@ -0,0 +1,79 @@
|
||||
# Research: JSON Import/Export
|
||||
|
||||
**Feature**: 007-json-import-export
|
||||
**Date**: 2026-03-27
|
||||
|
||||
## Decision 1: Export Bundle Contents
|
||||
|
||||
**Decision**: Export includes encounter, undo/redo stacks, and player characters. Excludes bestiary cache, theme, and rules edition.
|
||||
|
||||
**Rationale**: The spec explicitly includes undo/redo history and player characters. Theme and rules edition are user preferences that should not transfer between DMs. Bestiary cache is large and can be rebuilt from sources.
|
||||
|
||||
**Alternatives considered**:
|
||||
- Include theme/edition settings — rejected because these are personal preferences, not encounter data.
|
||||
- Exclude undo/redo — rejected because the spec explicitly requires it and it enables full session restore.
|
||||
- Include bestiary cache — rejected because it's large, device-specific, and reconstructable from source URLs.
|
||||
|
||||
## Decision 2: Import Strategy — Full Replacement vs Merge
|
||||
|
||||
**Decision**: Full state replacement. Import replaces encounter, undo/redo, and player characters entirely.
|
||||
|
||||
**Rationale**: The spec states "Import replaces all existing state." Merging would require conflict resolution (duplicate IDs, name collisions) which adds significant complexity for unclear benefit.
|
||||
|
||||
**Alternatives considered**:
|
||||
- Merge player characters — rejected because ID conflicts between different sessions would be complex to resolve and the spec doesn't call for it.
|
||||
- Selective import (pick which parts to load) — rejected as out of MVP scope.
|
||||
|
||||
## Decision 3: Validation Approach
|
||||
|
||||
**Decision**: Reuse existing `rehydrateEncounter()` and player character validation from the persistence layer. These functions already handle all field validation, type checking, and graceful degradation for invalid fields.
|
||||
|
||||
**Rationale**: The spec explicitly states "validated using the same rules as localStorage loading." The existing `rehydrateEncounter()` function already validates every combatant field, filters invalid conditions, clamps HP values, and rejects structurally malformed data. Reusing it ensures consistency and avoids duplication.
|
||||
|
||||
**Alternatives considered**:
|
||||
- Write separate import validation — rejected because it would duplicate existing validation logic and risk divergence.
|
||||
- Stricter validation (reject files with any invalid field) — rejected because the existing approach gracefully degrades (strips invalid optional fields) which is more user-friendly.
|
||||
|
||||
## Decision 4: File Download Mechanism
|
||||
|
||||
**Decision**: Use `URL.createObjectURL()` with an anchor element's `download` attribute for triggering the file download.
|
||||
|
||||
**Rationale**: This is the standard browser-native approach that works across all modern browsers without popup blockers interfering. No server-side component needed.
|
||||
|
||||
**Alternatives considered**:
|
||||
- `window.open()` with data URI — rejected because popup blockers can interfere.
|
||||
- FileSaver.js library — rejected because the native approach is sufficient and avoids an additional dependency.
|
||||
|
||||
## Decision 5: File Upload Mechanism
|
||||
|
||||
**Decision**: Use an `<input type="file" accept=".json">` element, consistent with the existing pattern in `source-fetch-prompt.tsx` which uses `file.text()` + `JSON.parse()`.
|
||||
|
||||
**Rationale**: The codebase already has this pattern for bestiary source uploads. Reusing the same approach keeps the UX consistent.
|
||||
|
||||
## Decision 6: UI Placement
|
||||
|
||||
**Decision**: Place export and import actions in the action bar's overflow menu, alongside existing items like "Players", "Manage Sources", and "Settings".
|
||||
|
||||
**Rationale**: The overflow menu already groups secondary actions. Import/export are infrequent operations that don't need primary button placement. The action bar's `buildOverflowItems()` function makes this straightforward to add.
|
||||
|
||||
**Alternatives considered**:
|
||||
- Settings modal — rejected because import/export are actions, not settings.
|
||||
- Dedicated toolbar buttons — rejected because import/export are infrequent and would clutter the primary UI.
|
||||
|
||||
## Decision 7: Export File Naming
|
||||
|
||||
**Decision**: Use a filename pattern like `initiative-export-YYYY-MM-DD.json` with the current date.
|
||||
|
||||
**Rationale**: The date provides context for when the export was created. Including "initiative" in the name makes the file's purpose clear when browsing a downloads folder.
|
||||
|
||||
## Decision 8: State Restoration After Import
|
||||
|
||||
**Decision**: Import must update both React state and localStorage in one operation. The encounter hook's `setEncounter()` triggers a `useEffect` that auto-saves to localStorage, and `setUndoRedoState()` similarly auto-saves. For player characters, the same auto-save pattern applies.
|
||||
|
||||
**Rationale**: Following the existing state flow ensures consistency. Setting React state triggers the existing persistence effects, so no manual localStorage writes are needed for the import path.
|
||||
|
||||
## Decision 9: Export Format Versioning
|
||||
|
||||
**Decision**: Include a `version` field in the export format (e.g., `1`) but do not implement migration logic in MVP.
|
||||
|
||||
**Rationale**: The spec's assumptions state "Future format versioning is not included in MVP baseline." Including the version field costs nothing and enables future migration logic without breaking existing exports.
|
||||
102
specs/007-json-import-export/spec.md
Normal file
102
specs/007-json-import-export/spec.md
Normal file
@@ -0,0 +1,102 @@
|
||||
# Feature Specification: JSON Import/Export
|
||||
|
||||
**Feature Branch**: `007-json-import-export`
|
||||
**Created**: 2026-03-27
|
||||
**Status**: Draft
|
||||
**Input**: Gitea issue #17 — JSON import/export for full encounter state
|
||||
|
||||
## User Scenarios & Testing *(mandatory)*
|
||||
|
||||
### Story IE-1 — Export encounter to file (Priority: P1)
|
||||
|
||||
A DM has set up an encounter (combatants, HP, initiative, conditions) and wants to save it as a file for backup or to share with another DM. They click an export button, and the browser downloads a `.json` file containing the full application state.
|
||||
|
||||
**Why this priority**: Export is the foundation — without it, import has nothing to work with. It also delivers standalone value as a backup mechanism.
|
||||
|
||||
**Independent Test**: Can be fully tested by creating an encounter, exporting, and verifying the downloaded file contains all encounter data, undo/redo history, and player character templates.
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
|
||||
1. **Given** an encounter with combatants (some with HP, AC, conditions, initiative), **When** the user clicks the export button, **Then** a `.json` file is downloaded containing the encounter state, undo/redo stacks, and player character templates.
|
||||
2. **Given** an empty encounter with no combatants, **When** the user clicks the export button, **Then** a `.json` file is downloaded containing the empty encounter state and any existing player character templates.
|
||||
3. **Given** an encounter with player character combatants (color, icon, linked template), **When** the user exports, **Then** the exported file preserves all player character visual properties and template links.
|
||||
|
||||
---
|
||||
|
||||
### Story IE-2 — Import encounter from file (Priority: P1)
|
||||
|
||||
A DM receives a `.json` file from another DM (or from their own earlier export) and wants to load it. They click an import button, select the file, and the application replaces the current state with the imported data.
|
||||
|
||||
**Why this priority**: Import completes the core value proposition — without it, export is just a read-only backup. Both are needed for the feature to be useful.
|
||||
|
||||
**Independent Test**: Can be tested by importing a valid `.json` file and verifying the encounter, undo/redo history, and player characters are replaced with the imported data.
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
|
||||
1. **Given** the current encounter is empty, **When** the user selects a valid exported `.json` file, **Then** the application loads the imported encounter, undo/redo history, and player characters without any confirmation prompt.
|
||||
2. **Given** the current encounter has combatants, **When** the user selects a valid `.json` file, **Then** a confirmation dialog appears warning that the current encounter will be replaced.
|
||||
3. **Given** the confirmation dialog is shown, **When** the user confirms, **Then** the current encounter, undo/redo history, and player characters are replaced with the imported data.
|
||||
4. **Given** the confirmation dialog is shown, **When** the user cancels, **Then** the current state remains unchanged.
|
||||
|
||||
---
|
||||
|
||||
### Story IE-3 — Reject invalid import files (Priority: P2)
|
||||
|
||||
A DM accidentally selects a wrong file (a non-JSON file, a corrupted export, or a JSON file with the wrong structure). The application rejects it and shows a clear error message without losing the current state.
|
||||
|
||||
**Why this priority**: Error handling is essential for a good user experience but secondary to the core import/export flow.
|
||||
|
||||
**Independent Test**: Can be tested by attempting to import various invalid files and verifying appropriate error messages appear while the current state is preserved.
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
|
||||
1. **Given** the user selects a non-JSON file (e.g., an image), **When** the import attempts to parse it, **Then** a user-facing error message is shown and the current state is unchanged.
|
||||
2. **Given** the user selects a JSON file with missing required fields, **When** the import validates it, **Then** a user-facing error message is shown and the current state is unchanged.
|
||||
3. **Given** the user selects a JSON file with a valid top-level structure but individual combatants with invalid fields (e.g., negative HP, unknown condition IDs), **When** the import validates it, **Then** invalid fields on otherwise valid combatants are dropped/defaulted (same as localStorage rehydration), but if the top-level structure is malformed (missing `encounter` key, wrong types), the file is rejected with an error message.
|
||||
|
||||
---
|
||||
|
||||
### Edge Cases
|
||||
|
||||
- What happens when the exported file is from a newer version of the application with unknown fields? The import ignores unknown fields and loads what it can validate.
|
||||
- What happens when the user imports a file with player characters that conflict with existing player character IDs? The imported player characters replace the existing ones entirely (full state replacement, not merge).
|
||||
- What happens when the undo/redo stacks in the imported file are empty or missing? The system loads with empty undo/redo stacks (same as a fresh session).
|
||||
- What happens when the browser blocks the file download (e.g., popup blocker)? The export uses a direct download mechanism (anchor element with download attribute) that is not subject to popup blocking.
|
||||
|
||||
## Requirements *(mandatory)*
|
||||
|
||||
### Functional Requirements
|
||||
|
||||
- **FR-001**: The system MUST provide an export action accessible from the UI that downloads the full application state as a `.json` file.
|
||||
- **FR-002**: The exported file MUST contain the current encounter (combatants and turn/round state), undo/redo stacks, and player character templates.
|
||||
- **FR-003**: The exported file MUST use a human-readable filename that includes context (e.g., date or encounter info).
|
||||
- **FR-004**: The system MUST provide an import action accessible from the UI that opens a file picker for `.json` files.
|
||||
- **FR-005**: On import, the system MUST replace the current encounter, undo/redo history, and player characters with the imported data.
|
||||
- **FR-006**: The system MUST show a confirmation dialog before importing if the current encounter is non-empty (has at least one combatant).
|
||||
- **FR-007**: The system MUST validate imported data using the same rules applied when loading from localStorage — invalid fields are cleaned or dropped, structurally malformed files are rejected entirely.
|
||||
- **FR-008**: The system MUST show a user-facing error message when an imported file is rejected as invalid.
|
||||
- **FR-009**: A failed or cancelled import MUST NOT alter the current application state.
|
||||
- **FR-010**: Export and import actions MUST be accessible from the same location in the UI.
|
||||
|
||||
### Key Entities
|
||||
|
||||
- **Export Bundle**: A single JSON structure containing the encounter snapshot, undo stack, redo stack, and player character list. Represents the full application state at the time of export.
|
||||
|
||||
## Success Criteria *(mandatory)*
|
||||
|
||||
### Measurable Outcomes
|
||||
|
||||
- **SC-001**: Users can export the current state to a downloadable file in one click.
|
||||
- **SC-002**: Users can import a previously exported file and see the full encounter restored, including combatant stats, turn tracking, and player characters.
|
||||
- **SC-003**: Importing an invalid file shows an error message within 1 second without affecting the current state.
|
||||
- **SC-004**: A round-trip (export then import) produces an encounter identical to the original.
|
||||
|
||||
## Assumptions
|
||||
|
||||
- The export format does not need to be backwards-compatible across application versions at this stage. Future format versioning is not included in MVP baseline.
|
||||
- Export/import covers the three main state stores: encounter, undo/redo, and player characters. Bestiary cache and user settings (theme, rules edition) are excluded.
|
||||
- The import is a full state replacement, not a merge. There is no selective import of individual pieces.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Undo/redo system (spec 006) must be implemented so that undo/redo stacks can be included in the export.
|
||||
142
specs/007-json-import-export/tasks.md
Normal file
142
specs/007-json-import-export/tasks.md
Normal file
@@ -0,0 +1,142 @@
|
||||
# Tasks: JSON Import/Export
|
||||
|
||||
**Input**: Design documents from `/specs/007-json-import-export/`
|
||||
**Prerequisites**: plan.md, spec.md, research.md, data-model.md, quickstart.md
|
||||
|
||||
**Tests**: Domain tests included (pure function testing is standard for this project per CLAUDE.md).
|
||||
|
||||
**Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story.
|
||||
|
||||
## Format: `[ID] [P?] [Story] Description`
|
||||
|
||||
- **[P]**: Can run in parallel (different files, no dependencies)
|
||||
- **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3)
|
||||
- Include exact file paths in descriptions
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Foundational (ExportBundle Type + Validation)
|
||||
|
||||
**Purpose**: Define the export format and validation logic that all stories depend on.
|
||||
|
||||
**⚠️ CRITICAL**: Export and import both depend on the ExportBundle type and validation.
|
||||
|
||||
- [x] T001 [P] Create `ExportBundle` type in `packages/domain/src/export-bundle.ts` with fields: `version` (number), `exportedAt` (string), `encounter` (Encounter), `undoStack` (Encounter[]), `redoStack` (Encounter[]), `playerCharacters` (PlayerCharacter[]). Export from `packages/domain/src/index.ts`.
|
||||
- [x] T002 [P] Create `validateImportBundle()` in `apps/web/src/persistence/export-import.ts` — accepts `unknown`, validates top-level structure (version, encounter, undoStack, redoStack, playerCharacters), delegates encounter validation to `rehydrateEncounter()` (imported from `./encounter-storage.ts`) and player character validation to `rehydrateCharacter()` (exported from `./player-character-storage.ts`). Returns validated `ExportBundle` or `DomainError`.
|
||||
- [x] T003 Write tests for `validateImportBundle()` in `apps/web/src/__tests__/validate-import-bundle.test.ts` — valid bundle, missing fields, invalid encounter, invalid player characters, empty stacks, unknown version, non-object input, invalid JSON types for each field.
|
||||
|
||||
**Checkpoint**: ExportBundle type and validation are tested and ready for use by export and import stories.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: User Story 1 — Export Encounter to File (Priority: P1) 🎯 MVP
|
||||
|
||||
**Goal**: Users can download the current state as a `.json` file in one click.
|
||||
|
||||
**Independent Test**: Create an encounter with combatants, HP, conditions, and player characters. Click export. Verify the downloaded file contains all state and is valid JSON matching the ExportBundle schema.
|
||||
|
||||
### Implementation for User Story 1
|
||||
|
||||
- [x] T004 [P] [US1] Create `assembleExportBundle()` function in `apps/web/src/persistence/export-import.ts` — takes encounter, undoRedoState, and playerCharacters, returns an `ExportBundle` with version 1 and current ISO timestamp.
|
||||
- [x] T005 [P] [US1] Create `triggerDownload(bundle: ExportBundle)` function in `apps/web/src/persistence/export-import.ts` — serializes bundle to JSON, creates a Blob, generates filename `initiative-export-YYYY-MM-DD.json`, triggers download via anchor element with `download` attribute.
|
||||
- [x] T006 [US1] Add "Export Encounter" item to the overflow menu in `apps/web/src/components/action-bar.tsx` — wire it to read encounter, undoRedoState, and playerCharacters from contexts, call `assembleExportBundle()`, then `triggerDownload()`. Use a `Download` icon from Lucide.
|
||||
- [x] T007 [US1] Write test for `assembleExportBundle()` in `apps/web/src/__tests__/export-import.test.ts` — verify output shape, version field, timestamp format, and that encounter/stacks/characters are included.
|
||||
|
||||
**Checkpoint**: Export is fully functional. Users can download state as JSON.
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: User Story 2 — Import Encounter from File (Priority: P1)
|
||||
|
||||
**Goal**: Users can import a `.json` file and replace the current state.
|
||||
|
||||
**Independent Test**: Export a file, clear the encounter, import the file. Verify the encounter is restored with all combatants, HP, conditions, undo/redo history, and player characters.
|
||||
|
||||
### Implementation for User Story 2
|
||||
|
||||
- [x] T008 [US2] Expose `setEncounter` and `setUndoRedoState` from `useEncounter` hook via `EncounterContext` in `apps/web/src/hooks/use-encounter.ts` and `apps/web/src/contexts/encounter-context.tsx` — these are needed for import to replace state directly (bypassing individual use cases). Also expose a `replacePlayerCharacters` setter from `usePlayerCharacters` hook via `PlayerCharactersContext` in `apps/web/src/hooks/use-player-characters.ts` and `apps/web/src/contexts/player-characters-context.tsx`.
|
||||
- [x] T009 [US2] Create `readImportFile(file: File)` function in `apps/web/src/persistence/export-import.ts` — reads file as text, parses JSON, calls `validateImportUseCase()`, returns validated `ExportBundle` or error string.
|
||||
- [x] T010 [US2] Create `ImportConfirmPrompt` component in `apps/web/src/components/import-confirm-prompt.tsx` — confirmation dialog (using native `<dialog>` element consistent with existing patterns) warning that the current encounter will be replaced. Props: `open`, `onConfirm`, `onCancel`.
|
||||
- [x] T011 [US2] Add "Import Encounter" item to the overflow menu in `apps/web/src/components/action-bar.tsx` — renders a hidden `<input type="file" accept=".json">`, triggers it on menu item click. On file selected: validate via `readImportFile()`, show error toast on failure, show `ImportConfirmPrompt` if encounter is non-empty, replace state on confirm (or directly if encounter is empty). Use an `Upload` icon from Lucide.
|
||||
- [x] T012 [US2] Write round-trip test in `apps/web/src/__tests__/export-import.test.ts` — assemble an export bundle, validate it via the import use case, verify the result matches the original state.
|
||||
|
||||
**Checkpoint**: Import is fully functional. Users can load exported files and restore state.
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: User Story 3 — Reject Invalid Import Files (Priority: P2)
|
||||
|
||||
**Goal**: Invalid files are rejected with clear error messages while preserving current state.
|
||||
|
||||
**Independent Test**: Attempt to import various invalid files (non-JSON, wrong structure, malformed combatants). Verify error messages appear and current state is unchanged.
|
||||
|
||||
### Implementation for User Story 3
|
||||
|
||||
- [x] T013 [US3] Add user-facing error toast for import failures in `apps/web/src/components/action-bar.tsx` — use the existing toast/alert pattern in the app. Show specific messages: "Invalid file format" for non-JSON, "Invalid encounter data" for validation failures.
|
||||
- [x] T014 [US3] Write validation edge case tests in `apps/web/src/__tests__/validate-import-bundle.test.ts` — non-JSON text file content, JSON array instead of object, missing version field, version 0 or negative, encounter that fails rehydration, undo stack with mix of valid and invalid entries (valid ones kept, invalid dropped), player characters with invalid color/icon (stripped but character kept). Include a state-preservation test: set up an encounter, attempt import of an invalid file, verify encounter is unchanged after error (FR-009).
|
||||
|
||||
**Checkpoint**: All three stories are complete. Invalid files are handled gracefully.
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: Polish & Cross-Cutting Concerns
|
||||
|
||||
**Purpose**: Final cleanup and documentation.
|
||||
|
||||
- [x] T015 Update CLAUDE.md spec listing to describe the feature in `CLAUDE.md`
|
||||
- [x] T016 N/A — no project-level README.md exists
|
||||
|
||||
---
|
||||
|
||||
## Dependencies & Execution Order
|
||||
|
||||
### Phase Dependencies
|
||||
|
||||
- **Foundational (Phase 1)**: No dependencies — can start immediately
|
||||
- **US1 Export (Phase 2)**: Depends on Phase 1 (needs ExportBundle type)
|
||||
- **US2 Import (Phase 3)**: Depends on Phase 1 (needs validation use case) and Phase 2 (needs export for round-trip testing)
|
||||
- **US3 Error Handling (Phase 4)**: Depends on Phase 3 (builds on import flow)
|
||||
- **Polish (Phase 5)**: Depends on all stories being complete
|
||||
|
||||
### Within Each Phase
|
||||
|
||||
- Tasks marked [P] can run in parallel
|
||||
- T001 and T002 are parallel (different files)
|
||||
- T004 and T005 are parallel (different functions, same file but independent)
|
||||
- T008 must complete before T011 (setters must exist before import wiring)
|
||||
|
||||
### Parallel Opportunities
|
||||
|
||||
- Phase 1: T001 and T002 can run in parallel (type definition + validation use case)
|
||||
- Phase 2: T004 and T005 can run in parallel (assemble + download functions)
|
||||
- Phase 2: T007 can run in parallel with T006 (test + UI wiring)
|
||||
|
||||
---
|
||||
|
||||
## Implementation Strategy
|
||||
|
||||
### MVP First (Export Only)
|
||||
|
||||
1. Complete Phase 1: ExportBundle type + validation
|
||||
2. Complete Phase 2: Export functionality
|
||||
3. **STOP and VALIDATE**: User can download encounter state as JSON
|
||||
4. Continue to Phase 3: Import functionality
|
||||
5. Continue to Phase 4: Error handling polish
|
||||
|
||||
### Incremental Delivery
|
||||
|
||||
1. Phase 1 → Foundation ready
|
||||
2. Phase 2 → Export works → Delivers backup value
|
||||
3. Phase 3 → Import works → Delivers full round-trip + sharing value
|
||||
4. Phase 4 → Error handling → Production-ready robustness
|
||||
5. Phase 5 → Documentation updated
|
||||
|
||||
---
|
||||
|
||||
## Notes
|
||||
|
||||
- Reuse `rehydrateEncounter()` from `apps/web/src/persistence/encounter-storage.ts` for all encounter validation — do not duplicate
|
||||
- Follow existing file picker pattern from `apps/web/src/components/source-fetch-prompt.tsx`
|
||||
- Follow existing overflow menu pattern in `apps/web/src/components/action-bar.tsx`
|
||||
- Follow existing `<dialog>` pattern from `apps/web/src/components/settings-modal.tsx`
|
||||
- Commit after each phase checkpoint
|
||||
Reference in New Issue
Block a user