From 17fe5cecf00a026653238e3a789a2b7d3e2a268c Mon Sep 17 00:00:00 2001 From: mbrucedogs Date: Fri, 25 Jul 2025 15:28:55 -0500 Subject: [PATCH] Signed-off-by: mbrucedogs --- README.md | 2 +- docs/PRD.md | 13 +++ docs/README.md | 194 ----------------------------------------- src/redux/selectors.ts | 42 ++++++++- src/types/index.ts | 2 +- 5 files changed, 54 insertions(+), 199 deletions(-) delete mode 100644 docs/README.md diff --git a/README.md b/README.md index f984773..10134b5 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ A real-time karaoke application designed for in-home party use with multi-user s - **Artist Browsing** - Browse songs by artist with modal views - **Song Lists** - Predefined song collections with availability matching - **Top Played** - Popular songs based on play history -- **New Songs** - Recently added songs to the catalog +- **New Songs** - Recently added songs to the catalog (see PRD for implementation details) ### **Admin Features** - **Queue Control** - Reorder and delete queue items diff --git a/docs/PRD.md b/docs/PRD.md index 84cb17b..5918fe0 100644 --- a/docs/PRD.md +++ b/docs/PRD.md @@ -148,6 +148,19 @@ This document defines the functional, technical, and UX requirements for the Kar **Requirements (Platform-Agnostic):** - Shows recently added songs from the `newSongs` node - Real-time updates and infinite scroll +- **Data Format Support**: Handles both full song objects and path-only references +- **Reverse Lookup**: Automatically resolves song paths to full song objects from main catalog +- **Backward Compatibility**: Works with both old and new data formats + +**Implementation Details:** +- **Format Detection**: Automatically detects whether `newSongs` contains full song objects or path-only references +- **Reverse Lookup**: When path-only data is detected, performs lookup against main songs catalog +- **Error Resilience**: Gracefully handles missing songs without breaking the UI +- **Debug Logging**: Provides detailed logging for troubleshooting missing songs + +**Data Formats Supported:** +1. **New Format**: `{ path: "song_path", key: "firebase_key" }` → Performs reverse lookup +2. **Old Format**: Full song objects with `artist`, `title`, `path`, etc. → Uses as-is **Platform Implementation:** - **Web:** See `platforms/web/PRD-web.md#new-songs` for React/Ionic implementation diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index b9202bd..0000000 --- a/docs/README.md +++ /dev/null @@ -1,194 +0,0 @@ -# 📄 Documentation & Reference Models - -This `/docs` folder contains **Product Requirements Documents (PRD)**, **data model definitions**, and **Firebase schema references** for the Karaoke App project. - -These files are intended for: -- 📃 Developers reviewing the business logic and architecture. -- 🤖 AI tools like Cursor or Copilot that reference documentation for context-aware coding. -- 📝 Project planning, architecture decisions, and future enhancements. -- 🚀 **Building the app from scratch with any framework/platform combination.** - ---- - -## Contents - -| File | Purpose | -|------|---------| -| `PRD.md` | **Complete Product Requirements Document** — platform-agnostic business logic, technical specifications, data flows, service APIs, component architecture, error handling, and performance optimizations. **Self-guiding for AI implementation.** | -| `types.ts` | Reference TypeScript interfaces used for modeling app objects. **Not imported into app runtime code.** | -| `firebase_schema.json` | Example Firebase Realtime Database structure for understanding data relationships and CRUD operations. | -| `platforms/web/design/` | **Web UI/UX Design Assets** — mockups and visual references for web platform features. | - ---- - -## 🚀 How to Use This Documentation - -### **For AI-Assisted Development:** -Simply say **"Read this PRD"** in any new chat. The PRD contains: -- **Self-guiding instructions** for AI implementation -- **Complete technical specifications** for 100% accuracy -- **Implementation questions** to determine platform/framework choices -- **Step-by-step build process** with checklists - -### **For Human Developers:** -- **Reference during implementation** for business logic and data flows -- **Guide for architecture decisions** and technology choices -- **Source of truth** for all functional requirements -- **Migration guide** when switching frameworks/platforms - -### **For New Implementations:** -1. **Read the PRD completely** - it contains comprehensive specifications -2. **Review design assets** in `platforms/web/design/` folder for visual reference -3. **Answer implementation questions** from Section 29 -4. **Follow the implementation checklist** for complete build process -5. **Preserve business logic** while adapting UI to chosen framework - ---- - -## 📋 Key Features of the Updated PRD - -### **Platform-Agnostic Design:** -- **Core business logic** completely separated from implementation details -- **Firebase architecture** and data models for any platform -- **Cross-platform references** to platform-specific PRDs -- **Universal business rules** that apply to all implementations - -### **Complete Technical Specifications:** -- **Firebase data structure** and relationships -- **Business logic patterns** and validation rules -- **Real-time synchronization** requirements -- **User role permissions** and access control -- **Error handling scenarios** and recovery patterns -- **Performance requirements** and optimization guidelines - -### **Implementation Guide:** -- **Platform selection questions** to determine technology stack -- **5-phase implementation checklist** for complete builds -- **Business logic preservation** guidelines -- **Critical success factors** for accurate implementations - -### **Design Assets:** -- **Visual mockups** for all major features and screens -- **Platform-specific designs** (web, mobile, etc.) -- **UX patterns** and interaction flows -- **Design system references** for consistent implementation - ---- - -## 🔄 Workflow for New Versions - -### **When Creating New Implementations:** -1. **Use the PRD as-is** - it's designed for any framework/platform -2. **Reference design assets** for visual guidance and UX patterns -3. **Follow the implementation guide** in Section 29 -4. **Preserve all business logic** while adapting UI layer -5. **Test against specifications** for 100% accuracy - -### **When Updating the PRD:** -1. **Keep platform-agnostic requirements** intact -2. **Add new implementation details** to appropriate sections -3. **Update toolset sections** with new technology choices -4. **Maintain self-guiding nature** for AI implementation - -### **When Migrating Platforms:** -1. **Keep all business logic** from core requirements -2. **Replace only implementation details** in platform-specific sections -3. **Add new platform sections** following the established pattern -4. **Update toolset rationale** for new technology choices - ---- - -## Important Notes -- ✅ These files are **not intended for direct import or use in application runtime**. -- ✅ Validation logic and data models here serve as **development references only**. -- ✅ Any updates to business logic, data flow, or app architecture should be reflected here for documentation purposes. -- ✅ AI tools may use this information to assist with code generation but will not access `/src` directly. -- ✅ **The PRD is self-guiding** - it contains all instructions needed for AI implementation. -- ✅ **100% accuracy achievable** when following the complete specifications. - ---- - -## 🎨 Design Assets Reference - -### **Current Web Design Assets:** -Located in `platforms/web/design/` folder with comprehensive mockups for all features: - -#### **Core Navigation & Layout:** -- `00-web-layout.JPG` - Overall web layout structure -- `01-Login.png` - Login screen design -- `02-menu.jpeg`, `02a-menu.jpeg`, `02b-menu.png`, `02c-menu.jpeg` - Navigation menu variations - -#### **Queue Management:** -- `02-queue.png` - Main queue view -- `02-queue-delete.png` - Queue with delete functionality -- `02-queue-drag.png` - Queue reordering with drag and drop -- `02-queue-sorting.png` - Queue sorting interface - -#### **Search & Discovery:** -- `04-search.png` - Main search interface -- `04-search typing .png` - Search with typing interaction -- `04-search-song info.png` - Search results with song information - -#### **User Management:** -- `05-singers.png` - Singer list view -- `05-singers add.png` - Singer management interface - -#### **Content Browsing:** -- `06-artists .png` - Artist browse interface -- `06-artists (not admin).png` - Non-admin artist view -- `06-artists search.png` - Artist search functionality -- `06-artists songs.png` - Artist songs list - -#### **User Features:** -- `07-favorites.png` - Favorites management -- `08-history.png` - Play history view -- `09-songs list.png` - Main song lists view -- `09-song lists - songs.png` - Song lists with song details -- `09- song lists songs expand.png` - Song lists with expandable sections - -#### **Admin Features:** -- `10-Settings.png` - Settings interface -- `11-top 100.png` - Top played songs -- `12-favorites .png` - Favorites view -- `12-favorite lists.png` - Favorite lists management - -#### **Menu States:** -- `03-menu.png` - General menu layout -- `03-menu current page and non-admin.png` - Navigation with current page indicators -- `03-menu playing (admin).png` - Admin view during playback - -### **Future Platform Design Structure:** -``` -docs/platforms/ -├── web/ -│ └── design/ # Current web mockups -├── ios/ -│ └── design/ # Future iOS designs -├── android/ -│ └── design/ # Future Android designs -├── tablet/ -│ └── design/ # Future tablet designs -└── desktop/ - └── design/ # Future desktop designs -``` - -### **Using Design Assets:** -- **Reference during implementation** for visual accuracy -- **Understand UX patterns** and interaction flows -- **Guide UI component design** and layout decisions -- **Ensure consistency** across different implementations -- **Validate feature completeness** against visual requirements - ---- - -## 🎯 Success Metrics -- **Zero ambiguity** in technical requirements -- **Framework independence** for easy migration -- **Complete implementation path** from start to finish -- **Consistent results** across different technology stacks -- **Self-documenting** for future developers and AI tools - ---- - -_This documentation is designed to be your **ultimate development tool** - enabling accurate builds with any framework/platform combination._ - diff --git a/src/redux/selectors.ts b/src/redux/selectors.ts index c7502cf..5061814 100644 --- a/src/redux/selectors.ts +++ b/src/redux/selectors.ts @@ -108,14 +108,50 @@ export const selectFavoritesArrayWithoutDisabled = createSelector( ); export const selectNewSongsArray = createSelector( - [selectNewSongs], - (newSongs) => sortSongsByArtistAndTitle(objectToArray(newSongs)) + [selectNewSongs, selectSongs], + (newSongs, songs) => { + // Handle both formats: + // 1. Array of objects with only path property (new format) + // 2. Array of full song objects (old format) + + const newSongsArray = objectToArray(newSongs); + + // Check if the first item has only path and key properties (new format) or is a full song object (old format) + if (newSongsArray.length > 0 && + typeof newSongsArray[0] === 'object' && + newSongsArray[0] !== null && + 'path' in newSongsArray[0] && + !('artist' in newSongsArray[0]) && + !('title' in newSongsArray[0])) { + // New format: array of objects with only path property - do reverse lookup + const songPaths = (newSongsArray as { path: string }[]).map(item => item.path); + const songsMap = new Map(Object.values(songs as Record).map(song => [song.path, song])); + + const resolvedSongs = songPaths + .map(path => songsMap.get(path)) + .filter((song): song is Song => song !== undefined); + + debugLog('selectNewSongsArray - reverse lookup:', { + pathsCount: songPaths.length, + resolvedCount: resolvedSongs.length, + missingPaths: songPaths.filter(path => !songsMap.has(path)) + }); + + return sortSongsByArtistAndTitle(resolvedSongs); + } else { + // Old format: array of full song objects + return sortSongsByArtistAndTitle(newSongsArray as Song[]); + } + } ); // New songs array without disabled songs export const selectNewSongsArrayWithoutDisabled = createSelector( [selectNewSongsArray, (_state: RootState, disabledSongPaths: Set) => disabledSongPaths], - (newSongs, disabledSongPaths) => newSongs.filter(song => !disabledSongPaths.has(song.path)) + (newSongs, disabledSongPaths) => { + // The selectNewSongsArray already handles the reverse lookup, so we just filter disabled songs + return newSongs.filter(song => !disabledSongPaths.has(song.path)); + } ); export const selectSingersArray = createSelector( diff --git a/src/types/index.ts b/src/types/index.ts index c7de08b..45cb529 100644 --- a/src/types/index.ts +++ b/src/types/index.ts @@ -93,7 +93,7 @@ export interface Controller { favorites: Record; history: Record; topPlayed: Record; - newSongs: Record; + newSongs: Record; // Can be either Song objects or objects with only path property player: { queue: Record; settings: Settings;