# Requirements: Itinerary Editor

**Defined:** 2026-01-18
**Core Value:** Drag-and-drop that operates on semantic positions (day + sortOrder), not row indices — so user intent is preserved across data reloads.

## v1 Requirements

Requirements for initial release. Each maps to roadmap phases.

### Data Model

- [ ] **DATA-01**: All movable items have semantic position `(day: Int, sortOrder: Double)`
- [ ] **DATA-02**: Travel segments are positioned items with their own sortOrder, not structural day properties
- [ ] **DATA-03**: Games are immovable anchors ordered by game time within each day
- [ ] **DATA-04**: Custom items can be placed anywhere within any day (including between games)
- [ ] **DATA-05**: Items always belong to exactly one day (no liminal "between days" state)

### Constraints

- [ ] **CONS-01**: Games cannot be moved (fixed by schedule)
- [ ] **CONS-02**: Travel segments are constrained to valid day range (between last from-city game and first to-city game)
- [ ] **CONS-03**: Travel segments must be positioned after from-city games and before to-city games on same day
- [ ] **CONS-04**: Custom items have no constraints (any position within any day)

### Flattening

- [ ] **FLAT-01**: Visual flattening sorts by sortOrder within each day (not hard-coded order)
- [ ] **FLAT-02**: Flattening is deterministic and stateless (same semantic state → same row order)
- [ ] **FLAT-03**: sortOrder < 0 convention for "before games", sortOrder >= 0 for "after/between games"

### Drag Interaction

- [ ] **DRAG-01**: Lift animation on grab (shadow + slight scale)
- [ ] **DRAG-02**: Insertion line appears between items showing exact drop target
- [ ] **DRAG-03**: Items shuffle out of the way during drag (100ms animation)
- [ ] **DRAG-04**: Magnetic snap on drop (item settles into position)
- [ ] **DRAG-05**: Invalid drops rejected with snap-back animation
- [ ] **DRAG-06**: Haptic feedback on grab (light) and drop (medium)
- [ ] **DRAG-07**: Auto-scroll when dragging to viewport edge
- [ ] **DRAG-08**: Slight tilt during drag (2-3 degrees, Trello-style)

### Persistence

- [ ] **PERS-01**: Semantic position survives data reloads from SwiftUI/SwiftData
- [ ] **PERS-02**: No visual-only state; all positions are persisted semantically
- [ ] **PERS-03**: Midpoint insertion for sortOrder (1.0, 2.0 → 1.5) enables unlimited insertions

## v2 Requirements

Deferred to future release. Tracked but not in current roadmap.

### Accessibility

- **ACC-01**: VoiceOver Move Up/Down actions for keyboard reordering
- **ACC-02**: VoiceOver announcements on drag start/end
- **ACC-03**: Focus management after reorder

### External Drops

- **EXT-01**: Accept drops from outside the table (UITableViewDropDelegate)
- **EXT-02**: External items converted to semantic position on drop

### Polish

- **POL-01**: Undo toast after drop (5-second timeout)
- **POL-02**: Drag handle visual affordance

## Out of Scope

Explicitly excluded. Documented to prevent scope creep.

| Feature | Reason |
|---------|--------|
| Reordering games | Games are fixed by schedule; core constraint |
| Reordering day headers | Structural, one per day |
| Multi-day travel segments | Complexity; travel belongs to exactly one day |
| Multi-item drag | Overkill for itinerary; single item at a time |
| Custom drag preview images | Unnecessary; default cell preview is fine |
| Drag between screens | Overkill; all editing within single table |
| Physics-based spring animations | Diminishing returns; standard easing is sufficient |
| Zone-based drop highlighting | Using insertion lines for precision |

## Traceability

Which phases cover which requirements. Updated during roadmap creation.

| Requirement | Phase | Status |
|-------------|-------|--------|
| DATA-01 | Phase 1 | Pending |
| DATA-02 | Phase 1 | Pending |
| DATA-03 | Phase 1 | Pending |
| DATA-04 | Phase 1 | Pending |
| DATA-05 | Phase 1 | Pending |
| CONS-01 | Phase 2 | Pending |
| CONS-02 | Phase 2 | Pending |
| CONS-03 | Phase 2 | Pending |
| CONS-04 | Phase 2 | Pending |
| FLAT-01 | Phase 3 | Pending |
| FLAT-02 | Phase 3 | Pending |
| FLAT-03 | Phase 3 | Pending |
| DRAG-01 | Phase 4 | Pending |
| DRAG-02 | Phase 4 | Pending |
| DRAG-03 | Phase 4 | Pending |
| DRAG-04 | Phase 4 | Pending |
| DRAG-05 | Phase 4 | Pending |
| DRAG-06 | Phase 4 | Pending |
| DRAG-07 | Phase 4 | Pending |
| DRAG-08 | Phase 4 | Pending |
| PERS-01 | Phase 1 | Pending |
| PERS-02 | Phase 1 | Pending |
| PERS-03 | Phase 1 | Pending |

**Coverage:**
- v1 requirements: 23 total
- Mapped to phases: 23
- Unmapped: 0

---
*Requirements defined: 2026-01-18*
*Last updated: 2026-01-18 after roadmap creation*