# MetaMuLate Component Mapping This document maps the original HTML sections from `metamulate_decompose.html` to proposed React components, indicating which `@theorchard/suite-components` to use. ## Component Hierarchy ``` MetamulateOAPanel/ ├── Header/ │ ├── BrandLogo │ ├── DataMenu (dropdown) │ └── ActionButtons ├── MainLayout/ │ ├── ArtistSearch/ (Left Panel - 320px) │ │ ├── SearchInput │ │ ├── TrackList │ │ └── QueueFooter │ ├── MetadataMatrix/ (Center Panel - Flex) │ │ ├── ContextHeader │ │ ├── MatrixGrid/ │ │ │ ├── MatrixHeaderRow │ │ │ ├── MatrixCategory/ (Collapsible) │ │ │ │ └── MatrixRow/ │ │ │ │ └── MatrixCell │ │ │ └── ... │ │ └── EmptyState │ └── GoldenRecordPanel/ (Right Panel - 320px) │ ├── PreviewArtwork │ ├── GoldenFields/ │ │ └── EditableField │ └── ResolveButton ├── ConsoleLog/ (Bottom Panel - Resizable) │ ├── ConsoleHeader │ └── LogEntries └── Modals/ ├── ConnectionsModal ├── WebScrapeModal ├── BandcampUrlModal ├── WikidataEditorModal ├── LyricsModal └── DocsModal ``` --- ## Detailed Component Mapping ### 1. MetamulateOAPanel (Container) **Original HTML:** `` wrapper with all state management **Purpose:** Root container, provides context, initializes app state **Suite Components:** - `OAPanel` or custom layout container - `OAModuleProvider` for application context **Props Interface:** ```typescript interface MetamulateOAPanelProps { initialArtist?: string; onTrackResolved?: (goldenRecord: GoldenRecord) => void; theme?: 'default' | 'orchard'; } ``` --- ### 2. Header Component **Original HTML:** `

` **Purpose:** App branding, navigation, data menu, action buttons **Suite Components:** - `Header` or custom `

` with glass effect - `Button` for actions - `Dropdown` for Data & Config menu - `Tooltip` for help text **Child Components:** - `BrandLogo` - Logo with version badge - `DataMenu` - Export/Import dropdown - `ConnectionsButton` - Opens config modal **Example JSX:** ```tsx

Primary Data Reconciliation

``` --- ### 3. ArtistSearch Component **Original HTML:** `

` **Purpose:** Artist discovery, track queue management **Suite Components:** - `SearchInput` with icon prefix - `List` or `VirtualList` for track list - `Spinner` for loading state - `EmptyState` for no results **Child Components:** - `TrackListItem` - Individual track in queue **State:** ```typescript interface ArtistSearchState { query: string; tracks: TrackMetadata[]; isLoading: boolean; selectedTrackId: string | null; hasMore: boolean; } ``` **Example JSX:** ```tsx ``` --- ### 4. TrackList Component **Original HTML:** `

` **Purpose:** Scrollable list of discovered tracks **Suite Components:** - `VirtualList` for performance with large lists - Custom `TrackListItem` component **Example JSX:** ```tsx

{tracks.map(track => ( onSelect(track.id)} /> ))}

``` --- ### 5. TrackListItem Component **Original HTML:** Rendered dynamically in `renderTrackItem()` **Purpose:** Single track display with artwork, title, metadata badges **Suite Components:** - `Badge` for ISRC, authority score - `Tooltip` for additional info **Props:** ```typescript interface TrackListItemProps { track: TrackMetadata; isSelected: boolean; isResolved: boolean; onClick: () => void; } ``` --- ### 6. MetadataMatrix Component **Original HTML:** `

` **Purpose:** Central reconciliation workspace **Suite Components:** - Custom grid layout - `Tabs` for column source selection (potential) - `ResizeHandle` for column width adjustment **Child Components:** - `ContextHeader` - Current track info - `MatrixHeaderRow` - Column headers with source icons - `MatrixCategory` - Collapsible field groups - `MatrixRow` - Single field across sources - `MatrixCell` - Individual cell with selection **State:** ```typescript interface MatrixState { config: MatrixConfig; categories: MatrixCategory[]; selectedCell: { fieldKey: string; sourceKey: string } | null; } ``` --- ### 7. MatrixCell Component **Original HTML:** Cells in `.matrix-cell` **Purpose:** Display single value with selection, hover, and provenance link **Suite Components:** - `Tooltip` for full value display - `Badge` or icon for provenance **Props:** ```typescript interface MatrixCellProps { cell: MatrixCell; onSelect: () => void; isGolden: boolean; } ``` **Example JSX:** ```tsx

{cell.value.val} {cell.value.url && ( )}

``` --- ### 8. GoldenRecordPanel Component **Original HTML:** `

` **Purpose:** Display/edit the resolved "golden" record **Suite Components:** - `Card` for artwork display - `Form` with `Field` components for editing - `Button` for resolve action **Child Components:** - `PreviewArtwork` - Album art display - `EditableField` - Inline editable field - `FieldCategory` - Grouped fields **Example JSX:** ```tsx ``` --- ### 9. ConsoleLog Component **Original HTML:** `

` **Purpose:** System log with colored entries, debug mode, export **Suite Components:** - Custom resizable panel - `Toggle` for debug mode - `Button` for clear/export **Features:** - Resizable height - Collapsible - Source-colored log entries - Debug JSON expansion **Example JSX:** ```tsx ``` --- ### 10. ScrapeOverlay Component **Original HTML:** `

` **Purpose:** Modal overlay showing active scrape progress **Suite Components:** - `Modal` or custom overlay - `ProgressBar` or spinner - `Button` for cancel **Child Components:** - `ScrapeCard` - Individual source progress **Example JSX:** ```tsx Scraping: {trackName} {completedCount}/{totalCount} {sources.map(([key, state]) => ( cancelSource(key)} /> ))} ``` --- ### 11. ConnectionsModal Component **Original HTML:** `

` **Purpose:** API configuration, secrets, proxy settings **Suite Components:** - `Modal` with `ModalHeader`, `ModalBody`, `ModalFooter` - `Form`, `Field`, `Input`, `Select` - `Toggle` for boolean settings - `Button` for actions **Sections:** 1. API Sources (Apple, Discogs, Genius, etc.) 2. CORS Proxy Gateway 3. Matrix Display Settings 4. Snowflake Configuration --- ### 12. WebScrapeModal Component **Original HTML:** `

` **Purpose:** Manual URL/content scraping **Suite Components:** - `Modal` - `Tabs` for URL vs Paste content - `Input` for URL - `Textarea` for pasted content - `List` for detected candidates --- ### 13. TourOverlay Component **Original HTML:** `#tourSpotlight`, `#tourTooltip` **Purpose:** Guided onboarding tour **Suite Components:** - Custom overlay with spotlight effect - `Tooltip` positioned dynamically - `Button` for navigation **State:** ```typescript interface TourState { isActive: boolean; currentStep: number; steps: TourStep[]; } interface TourStep { target: string; // CSS selector title: string; content: string; position: 'top' | 'bottom' | 'left' | 'right'; } ``` --- ## Suite Components Usage Summary | Suite Component | Usage Locations | |-----------------|-----------------| | `Button` | Header, Modals, GoldenRecord, Console | | `Input` | ArtistSearch, ConnectionsModal, WebScrape | | `Modal` | All modals (Connections, WebScrape, etc.) | | `Tooltip` | MatrixCell, TrackListItem, various | | `Badge` | TrackListItem, MatrixCell (ISRC, scores) | | `Toggle` | DebugMode, Settings | | `Dropdown` | DataMenu, Source selection | | `Tabs` | WebScrapeModal (URL/Paste) | | `Form/Field` | ConnectionsModal, GoldenFields | | `Spinner` | Loading states | | `EmptyState` | No tracks, no matrix data | | `ProgressBar` | ScrapeOverlay (optional) | | `VirtualList` | TrackList (performance) | --- ## CSS/Styling Notes 1. **Glass Effect Header**: Use `backdrop-filter: blur(16px)` with semi-transparent background 2. **Matrix Cell Hover**: `box-shadow: 0 0 0 1px rgba(accent-color, 0.3)` 3. **Selected Cell**: Green border/background for golden record selections 4. **Console Source Colors**: Map source names to specific text colors 5. **Theme System**: CSS custom properties for theme switching --- ## State Management Recommendations 1. **Apollo Client Cache**: Track list, golden records, resolved tracks 2. **React Context**: - `ScrapeContext` for active scraping state - `MatrixContext` for column configuration - `ThemeContext` for theme switching 3. **Local State**: Modal visibility, form inputs, UI toggles 4. **localStorage**: Persist config, secrets, matrix settings