docs: start milestone v1.3 Session Settings Tests
This commit is contained in:
Nuwan
parent
86420c85de
commit
98183f7efa
|
|
@ -1,18 +1,19 @@
|
|||
# JamKazam Media Features Modernization
|
||||
|
||||
**One-liner:** Modernize media features (Backing Track, JamTrack, Session Chat, Session Attachments) from legacy jQuery/Rails to React patterns in jam-ui
|
||||
**One-liner:** Modernize session features from legacy jQuery/Rails to React patterns in jam-ui, with comprehensive test coverage
|
||||
|
||||
## Vision
|
||||
|
||||
Transform media features from the legacy web project into modern React patterns in jam-ui. The features exist in the legacy codebase with jQuery dialogs and polling-based playback monitoring - we're bringing them into the React architecture with proper component structure, hooks, and Redux integration where appropriate.
|
||||
Transform session features from the legacy web project into modern React patterns in jam-ui. The features exist in the legacy codebase with jQuery dialogs and polling-based playback monitoring - we're bringing them into the React architecture with proper component structure, hooks, and Redux integration where appropriate.
|
||||
|
||||
**Completed Features (v1.0, v1.1):**
|
||||
**Completed Features (v1.0, v1.1, v1.2):**
|
||||
1. ✅ **Backing Track** - File-based audio playback with player controls
|
||||
2. ✅ **JamTrack** - Collaborative track loading with mixdown selection
|
||||
3. ✅ **Session Chat** - Real-time chat with message history and read/unread tracking
|
||||
4. ✅ **Session Attachments** - File upload/download integration with chat window
|
||||
|
||||
**Current Milestone (v1.2):**
|
||||
4. 🚧 **Session Attachments** - File upload/download integration with chat window
|
||||
**Current Milestone (v1.3):**
|
||||
5. 🚧 **Session Settings Tests** - Add test coverage for the Session Settings modal
|
||||
|
||||
**Future Work:**
|
||||
- **Metronome** - Tempo/sound configuration and playback (deferred)
|
||||
|
|
@ -32,11 +33,16 @@ Transform media features from the legacy web project into modern React patterns
|
|||
- ✅ Read/unread status tracking with badge indicators
|
||||
- ✅ Error handling, accessibility, and edge cases
|
||||
|
||||
**v1.2 Session Attachments (IN PROGRESS):**
|
||||
- ⏳ File attachment capability from session toolbar
|
||||
- ⏳ Integration with existing chat window
|
||||
- ⏳ Real-time attachment notifications via WebSocket
|
||||
- ⏳ File viewing in new browser tab
|
||||
**v1.2 Session Attachments (SHIPPED 2026-02-07):**
|
||||
- ✅ File attachment capability from session toolbar
|
||||
- ✅ Integration with existing chat window
|
||||
- ✅ Real-time attachment notifications via WebSocket
|
||||
- ✅ File viewing in new browser tab
|
||||
|
||||
**v1.3 Session Settings Tests (IN PROGRESS):**
|
||||
- ⏳ Jest unit tests for JKSessionSettingsModal component
|
||||
- ⏳ Playwright integration tests for Settings modal user flows
|
||||
- ⏳ Coverage for critical paths: save, cancel, validation, errors
|
||||
|
||||
**Deferred:**
|
||||
- **Metronome** - Tempo/sound configuration and playback
|
||||
|
|
@ -58,7 +64,7 @@ Transform media features from the legacy web project into modern React patterns
|
|||
|
||||
## Requirements
|
||||
|
||||
### Validated (from v1.0, v1.1)
|
||||
### Validated (from v1.0, v1.1, v1.2)
|
||||
|
||||
- ✓ Native file dialog for track selection - works well for media files
|
||||
- ✓ jamClient API integration - proven in Backing Track/JamTrack
|
||||
|
|
@ -66,53 +72,32 @@ Transform media features from the legacy web project into modern React patterns
|
|||
- ✓ WebSocket real-time communication - proven in chat feature
|
||||
- ✓ Modeless dialog pattern - established in chat window
|
||||
- ✓ Backend API integration - REST endpoints for chat/media working well
|
||||
- ✓ File attachment upload to S3 - validated in Session Attachments
|
||||
- ✓ Attachment display in chat - validated in Session Attachments
|
||||
|
||||
### Active (v1.2 Session Attachments)
|
||||
### Active (v1.3 Session Settings Tests)
|
||||
|
||||
**File Upload:**
|
||||
- [ ] Attach button in session toolbar opens OS file dialog
|
||||
- [ ] Support file types: .pdf, .xml, .mxl, .txt, .png, .jpg, .jpeg, .gif, .mp3, .wav
|
||||
- [ ] Enforce 10 MB file size limit with validation
|
||||
- [ ] Upload progress indicator displayed in chat window
|
||||
- [ ] Upload to S3 via existing MusicNotation API
|
||||
- [ ] Error handling for upload failures (network, size limit, file type)
|
||||
**Unit Tests (Jest):**
|
||||
- [ ] Test modal renders with correct initial values from props
|
||||
- [ ] Test privacy dropdown state changes
|
||||
- [ ] Test description textarea state changes
|
||||
- [ ] Test form validation behavior
|
||||
- [ ] Test save button calls onSave with correct payload
|
||||
- [ ] Test cancel/close behavior
|
||||
|
||||
**Chat Integration:**
|
||||
- [ ] Display attachment as message in chat: "John attached Song.pdf"
|
||||
- [ ] Show attachment icon/indicator in message
|
||||
- [ ] Include attachment metadata (filename, size, uploader, timestamp)
|
||||
- [ ] Clickable link to view/download file
|
||||
- [ ] Attachment messages sortable with regular chat messages
|
||||
|
||||
**Real-time Sync:**
|
||||
- [ ] WebSocket broadcast of new attachments to all session participants
|
||||
- [ ] New attachment appears immediately in all users' chat windows
|
||||
- [ ] Chat history includes attachments when joining session
|
||||
- [ ] Attachment messages persist across page refreshes
|
||||
|
||||
**File Viewing:**
|
||||
- [ ] Click attachment opens file in new browser tab
|
||||
- [ ] Browser handles view/download based on file type
|
||||
- [ ] Attachment URLs use existing S3 file_url from MusicNotation model
|
||||
|
||||
**Error Handling:**
|
||||
- [ ] Toast notification for file size exceeded
|
||||
- [ ] Toast notification for invalid file type
|
||||
- [ ] Toast notification for upload network errors
|
||||
- [ ] Clear feedback when upload succeeds
|
||||
- [ ] Graceful handling of missing/deleted files
|
||||
**Integration Tests (Playwright):**
|
||||
- [ ] Test Settings button opens modal
|
||||
- [ ] Test save settings updates session via API
|
||||
- [ ] Test cancel closes modal without API call
|
||||
- [ ] Test error handling when API fails
|
||||
- [ ] Test success feedback after save
|
||||
|
||||
### Out of Scope
|
||||
|
||||
- **Backend changes** - Use existing MusicNotation model, S3 storage, and API endpoints
|
||||
- **File attachment from chat window** - Only from session toolbar attach button
|
||||
- **Comment/annotation on attachments** - Just display filename with uploader name
|
||||
- **File icons/thumbnails** - Display text-based attachment messages only
|
||||
- **Claimed recordings attachment** - Only computer files for now
|
||||
- **Music notation attachment** - Defer to future work
|
||||
- **File preview** - Browser handles view/download, no custom preview UI
|
||||
- **Attachment deletion** - Not in scope for v1.2
|
||||
- **Attachment editing/versioning** - Not in scope for v1.2
|
||||
- **New features** - Only adding tests for existing functionality
|
||||
- **Refactoring** - Unless required for testability
|
||||
- **Other modals** - Only JKSessionSettingsModal in this milestone
|
||||
- **Backend test changes** - Frontend tests only
|
||||
|
||||
## Key Decisions
|
||||
|
||||
|
|
@ -120,46 +105,45 @@ Transform media features from the legacy web project into modern React patterns
|
|||
|----------|-----------|---------|
|
||||
| Keep native file dialogs | Already working, platform-native UX, no need to rebuild | Validated (v1.0) |
|
||||
| Use Redux for chat state | Global visibility needed for badge, history, WebSocket sync | Validated (v1.1) |
|
||||
| Reuse existing backend | MusicNotation model already has S3, API, attachment_type | Confirmed (v1.2) |
|
||||
| Only toolbar upload | Simplifies UX, avoids dual upload paths, matches common patterns | Confirmed (v1.2) |
|
||||
| 10 MB file size limit | Matches legacy app limit, reasonable for notation/audio files | Confirmed (v1.2) |
|
||||
| Browser handles view/download | No custom preview UI, leverages native browser capabilities | Confirmed (v1.2) |
|
||||
| Display in chat window | Natural integration, attachments are part of session communication | Confirmed (v1.2) |
|
||||
| File types from legacy | .pdf, .xml, .mxl, .txt (notation), .png/.jpg/.jpeg/.gif (images), .mp3/.wav (audio) | Confirmed (v1.2) |
|
||||
| Reuse existing backend | MusicNotation model already has S3, API, attachment_type | Validated (v1.2) |
|
||||
| Only toolbar upload | Simplifies UX, avoids dual upload paths, matches common patterns | Validated (v1.2) |
|
||||
| 10 MB file size limit | Matches legacy app limit, reasonable for notation/audio files | Validated (v1.2) |
|
||||
| Browser handles view/download | No custom preview UI, leverages native browser capabilities | Validated (v1.2) |
|
||||
| Display in chat window | Natural integration, attachments are part of session communication | Validated (v1.2) |
|
||||
| File types from legacy | .pdf, .xml, .mxl, .txt (notation), .png/.jpg/.jpeg/.gif (images), .mp3/.wav (audio) | Validated (v1.2) |
|
||||
| Critical paths only | Focus on save/cancel/validation/errors, not exhaustive coverage | Confirmed (v1.3) |
|
||||
| Both test types | Jest for unit tests, Playwright for integration - comprehensive coverage | Confirmed (v1.3) |
|
||||
|
||||
## Constraints
|
||||
|
||||
### Technical
|
||||
|
||||
- **Must use jamClient API methods:** SessionGetTracksPlayDurationMs(), SessionCurrrentPlayPosMs(), isSessionTrackPlaying(), SessionTrackSeekMs()
|
||||
- **React 16 patterns only** - No async/await in useEffect without proper cleanup
|
||||
- **Maintain 60fps VU meter performance** - Playback monitoring must not degrade mixer rendering
|
||||
- **TDD workflow** - Follow RED-GREEN-REFACTOR pattern per CLAUDE.md
|
||||
- **Jest for unit tests** - Component logic, validation, state changes
|
||||
- **Playwright for integration tests** - User flows, API calls, error handling
|
||||
|
||||
### Business
|
||||
### Testing
|
||||
|
||||
- **Functional parity with legacy web** - Users expect same capabilities in jam-ui
|
||||
- **Zero audio glitches** - Seek/playback changes must be seamless
|
||||
- **Mock external dependencies** - API calls, Redux store, native client
|
||||
- **Follow existing test patterns** - Match structure in `sessionUISlice.test.js`
|
||||
- **Critical paths focus** - Save, cancel, validation, error handling only
|
||||
|
||||
## Critical Files
|
||||
|
||||
**v1.2 Session Attachments (Current Focus):**
|
||||
- `jam-ui/src/components/client/JKSessionScreen.js` - Session toolbar, attach button entry point
|
||||
- `jam-ui/src/components/client/chat/JKChatWindow.js` - Chat window for attachment display
|
||||
- `jam-ui/src/components/client/chat/JKChatMessageList.js` - Message list to render attachments
|
||||
- `jam-ui/src/store/features/sessionChatSlice.js` - Redux state for chat/attachments
|
||||
- `jam-ui/src/helpers/rest.js` - API calls to backend
|
||||
**v1.3 Session Settings Tests (Current Focus):**
|
||||
- `jam-ui/src/components/client/JKSessionSettingsModal.js` - Settings modal component (101 lines)
|
||||
- `jam-ui/src/components/client/JKSessionScreen.js` - Parent component, Settings button, onSave handler
|
||||
- `jam-ui/src/store/features/sessionUISlice.js` - Redux modal state management
|
||||
- `jam-ui/src/helpers/rest.js` - `updateSessionSettings()` API call
|
||||
- `jam-ui/src/helpers/globals.js` - `SESSION_PRIVACY_MAP` constant
|
||||
|
||||
**Backend (Existing Infrastructure):**
|
||||
- `ruby/lib/jam_ruby/models/music_notation.rb` - MusicNotation model with S3 upload
|
||||
- `web/app/controllers/api/music_notations_controller.rb` - REST API for attachments
|
||||
- `web/db/migrations/*_create_music_notations.rb` - Database schema
|
||||
**Test Files (to be created):**
|
||||
- `jam-ui/src/components/client/__tests__/JKSessionSettingsModal.test.js` - Jest unit tests
|
||||
- `jam-ui/test/session-settings/` - Playwright integration tests
|
||||
|
||||
**Legacy Reference:**
|
||||
- `web/app/assets/javascripts/react-components/stores/AttachmentStore.js.coffee` - Legacy upload pattern
|
||||
- `web/app/views/clients/_sessionSettings.html.haml` - File type restrictions
|
||||
|
||||
**WebSocket:**
|
||||
- `websocket-gateway/` - Real-time attachment broadcast (existing infrastructure)
|
||||
**Existing Test Reference:**
|
||||
- `jam-ui/src/store/features/__tests__/sessionUISlice.test.js` - Redux tests (modal state already covered)
|
||||
|
||||
---
|
||||
*Last updated: 2026-02-02 for v1.2 Session Attachments milestone*
|
||||
*Last updated: 2026-02-07 for v1.3 Session Settings Tests milestone*
|
||||
|
|
|
|||
|
|
@ -4,17 +4,17 @@
|
|||
|
||||
See: .planning/PROJECT.md (updated 2026-02-07)
|
||||
|
||||
**Core value:** Modernize session features (Backing Track, JamTrack, Session Chat, Session Attachments) from legacy jQuery/Rails to React patterns in jam-ui
|
||||
**Current focus:** Planning next milestone
|
||||
**Core value:** Add test coverage for session features to enable confident changes
|
||||
**Current focus:** v1.3 Session Settings Tests
|
||||
|
||||
## Current Position
|
||||
|
||||
Phase: Complete (v1.2 shipped)
|
||||
Plan: N/A
|
||||
Status: v1.2 Session Attachments milestone SHIPPED
|
||||
Last activity: 2026-02-07 — v1.2 milestone complete
|
||||
Phase: Not started (defining requirements)
|
||||
Plan: —
|
||||
Status: Defining requirements
|
||||
Last activity: 2026-02-07 — Milestone v1.3 started
|
||||
|
||||
Progress: ████████████ 100% (v1.2 MILESTONE COMPLETE)
|
||||
Progress: ░░░░░░░░░░░░ 0%
|
||||
|
||||
## Performance Metrics
|
||||
|
||||
|
|
@ -41,7 +41,6 @@ Progress: ████████████ 100% (v1.2 MILESTONE COMPLETE)
|
|||
### Decisions
|
||||
|
||||
Decisions are logged in PROJECT.md Key Decisions table.
|
||||
See `.planning/milestones/v1.2-ROADMAP.md` for v1.2 decisions.
|
||||
|
||||
### Deferred Issues
|
||||
|
||||
|
|
@ -56,14 +55,15 @@ See `.planning/milestones/v1.2-ROADMAP.md` for v1.2 decisions.
|
|||
- **v1.0 Media Players** (Phases 1-5): Shipped 2026-01-14
|
||||
- **v1.1 Music Session Chat** (Phases 6-11): Shipped 2026-01-31
|
||||
- **v1.2 Session Attachments** (Phases 12-16): Shipped 2026-02-07
|
||||
- **v1.3 TBD**: Not started
|
||||
- **v1.3 Session Settings Tests** (Phases 17+): In progress
|
||||
|
||||
## Session Continuity
|
||||
|
||||
Last session: 2026-02-07
|
||||
Stopped at: v1.2 milestone complete
|
||||
Stopped at: Milestone initialization
|
||||
Resume file: None
|
||||
|
||||
**Status:** Ready for next milestone
|
||||
**Next steps:**
|
||||
1. Run `/gsd:new-milestone` to start next milestone planning
|
||||
1. Define REQUIREMENTS.md
|
||||
2. Create ROADMAP.md with phase structure
|
||||
3. Run `/gsd:plan-phase 17` to start execution
|
||||
|
|
|
|||
Loading…
Reference in New Issue