Files
stemengine_old/StemEngine WebUI.md
T

397 lines
17 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# StemEngine Web UI Redesign — MetroUI Plan
Redesign the StemEngine React frontend using the
[MetroUI](https://github.com/olton/metroui) (`@olton/metroui`) component framework,
replacing the current Tailwind CSS utility-class approach with MetroUI's Metro Style
design language (flat, tile-based, high-contrast, strongly typographic).
---
## Current Stack
| Layer | Current |
|-------|---------|
| Build | Vite 5 + TypeScript |
| Framework | React 18 |
| Styling | Tailwind CSS 3 + custom CSS variables (`--brand-*`) |
| Icons | lucide-react |
| Query | TanStack React Query 5 |
| Audio | Tone.js, @tonejs/midi, abcjs |
The Tailwind dependency is removed; everything else stays.
---
## Why MetroUI
- **Zero external dependencies** — one CSS + one JS bundle, no tree-shaking puzzle.
- **Metro Style** matches the tool's technical, editor-like aesthetic better than a
generic utility framework.
- **Built-in dark theme** — `data-theme="dark"` on `<html>`, no custom variable juggling.
- **Rich component set** already covers every current UI pattern: panels, tiles, appbar,
sidenav, progress bars, sliders, dialogs, toasts, accordions, tabs, badges, activity
indicators.
- **Live Tiles** — ideal for the project browser grid: each project tile can show
job-status colour and animated activity indicator natively.
- **CSS-class driven** — React keeps all interactivity; MetroUI JS is only needed for
a handful of overlay components (dialog, toast, window). No framework conflict.
---
## Installation
```bash
npm install @olton/metroui
```
In `main.tsx` (replaces Tailwind imports in `index.css`):
```ts
import '@olton/metroui/dist/css/metro.css'
import '@olton/metroui/dist/css/icons.css'
// MetroUI JS (for dialog/toast/tooltip JS API)
import '@olton/metroui/dist/js/metro.js'
```
Remove from `package.json`:
- `tailwindcss`, `autoprefixer`, `postcss`
- `tailwind.config.js`, `postcss.config.js`
The `index.css` file is reduced to:
- Custom scrollbar overrides
- `KaraokeEditor` canvas variables (these are purely internal and not Tailwind)
- Any one-off layout rules not covered by MetroUI
---
## Design Language Decisions
| Decision | Choice |
|----------|--------|
| Theme | Dark (`data-theme="dark"`) by default; user can toggle to Light |
| Accent | Six Metro accent colours matching current set: Blue, Violet, Rose, Emerald, Amber, Cyan — applied via `data-accent` on `<html>` and MetroUI's built-in accent palette |
| Typography | Keep current font selection feature (Archivo, Inter, Poppins, etc.); MetroUI's font stack is overridden with the user's chosen font |
| Border radius | Metro default (minimal rounding, ~2–4 px) |
| Spacing | MetroUI grid (12-column) + flexbox utilities |
| Icons | Replace lucide-react with MetroUI icon font (`<span class="mif-...">`) or keep lucide SVGs as-is (both work) |
---
## Layout Shell (App.tsx)
### Current
Flex column: fixed header → flex row (collapsible sidebar + main content) → fixed footer.
Tab navigation (`Separator` / `ProjectDetail` / `Settings`) via `activeTabId` state.
### MetroUI Redesign
```
┌─────────────────────────────────────────────────────┐
│ AppBar [≡ StemEngine] [GPU status] [⚙ Settings] │ ← metro appbar
├───────────┬─────────────────────────────────────────┤
│ │ │
│ SideNav │ Main content panel │
│ │ (routed view) │
│ Project │ │
│ list │ │
│ (tiles) │ │
│ │ │
├───────────┴─────────────────────────────────────────┤
│ GlobalAudioBar (fixed bottom strip) │
└─────────────────────────────────────────────────────┘
```
**Key class mappings:**
| Old | MetroUI |
|-----|---------|
| `fixed top-0` header div | `<div data-role="appbar">` |
| Sidebar div | `<div data-role="sidenav-m3">` or custom vertical nav panel |
| Main content flex area | `<div class="container-fluid">` with MetroUI grid |
| Footer credits | `<div class="app-footer">` |
Navigation moves from tab buttons to **AppBar action buttons + sidenav** so the
main content area is maximised.
---
## Page: Separator
### Current
Long vertical form: file upload zone → model accordion → format options → output
settings → submit button.
### MetroUI Redesign
Use a **two-column panel** layout:
```
┌──────────────────────┬────────────────────────────┐
│ Drop Zone │ Configuration Panel │
│ │ │
│ [Metro drop-zone │ ┌─ Model ──────────────┐ │
│ with dashed border │ │ accordion (closed) │ │
│ and icon] │ └──────────────────────┘ │
│ │ ┌─ Output Format ──────┐ │
│ Imported files list │ │ radio tiles │ │
│ (metro listview) │ └──────────────────────┘ │
│ │ ┌─ Stems ──────────────┐ │
│ │ │ slider group │ │
│ │ └──────────────────────┘ │
│ │ [Separate ▶] │
└──────────────────────┴────────────────────────────┘
```
**MetroUI components:**
| UI element | MetroUI |
|------------|---------|
| File drop zone | `data-role="drop-zone"` |
| Accordion sections | `data-role="accordion"` |
| Model radio tiles | Metro tile grid with `data-role="radio"` |
| Format select | `data-role="select"` |
| Level sliders | `data-role="slider"` with custom track labels |
| Job status | `data-role="progress"` + `data-role="activity"` spinner |
| Submit | `<button class="button large primary">` |
| Toast notification | Metro toast API on job queue |
---
## Page: ProjectDetail
### Current
Vertical stack: stem file list → job action buttons → KaraokeEditor → DynamicMixPlayer
→ LyricsLivePreview — all in one scrollable column.
### MetroUI Redesign
**Resizable window panels** — each major feature area is a collapsible Metro
`data-role="panel"` with a title bar, independently collapsible. Power users can
collapse all but the one they're working in.
```
┌── Project: "Song Title" ─────────────────────────── [↑ actions] ┐
│ │
│ ┌─ Stems ──────────────────────────────────── [▼] ────────────┐│
│ │ [stem tiles with colour-coded job badges] ││
│ └─────────────────────────────────────────────────────────────┘│
│ │
│ ┌─ Karaoke Editor ─────────────────────────── [▼] ────────────┐│
│ │ WaveformCanvas + TimingTable (unchanged internally) ││
│ └─────────────────────────────────────────────────────────────┘│
│ │
│ ┌─ Dynamic Mix ────────────────────────────── [▼] ────────────┐│
│ │ DynamicMixPlayer sliders + master gain ││
│ └─────────────────────────────────────────────────────────────┘│
│ │
│ ┌─ Lyrics Preview ─────────────────────────── [▼] ────────────┐│
│ │ LyricsLivePreview (unchanged internally) ││
│ └─────────────────────────────────────────────────────────────┘│
└──────────────────────────────────────────────────────────────────┘
```
**MetroUI components:**
| UI element | MetroUI |
|------------|---------|
| Panel sections | `data-role="panel"` with `data-collapsible="true"` |
| Stem tiles | Metro tile grid — colour indicates stem type |
| Job status badges | `<span class="badge ...">` |
| Action buttons (transcribe, align, etc.) | `<button class="button">` + `data-role="dropdown"` for multi-action |
| Job progress | `data-role="progress"` bar inside stem tile |
| File download links | `<a class="button flat">` with icon |
---
## Page: Settings
### Current
Horizontal tab strip (Appearance / Models / Subsonic / Maintenance / Power / AutoPipeline)
with tab panel content below.
### MetroUI Redesign
Keep tabs but use MetroUI `data-role="tabs"` with a **left-side vertical pill list**
on desktop and collapsing to a `data-role="select"` dropdown on narrow viewports.
**Appearance tab:**
- Theme radio tiles (Dark / Light / System) — Metro style tiles with check mark
- Font select → `data-role="select"` with preview label
- Accent colour — a horizontal row of Metro colour tiles
**Models tab:**
- `data-role="listview"` with group rows and expand/collapse
- Progress bars inside each model row for download status
- Action buttons (Download / Pause / Cancel / Remove) inline
**Subsonic tab:**
- Metro form layout with `data-role="input"` fields
- `data-role="treeview"` for the library browser
**Maintenance tab:**
- `data-role="accordion"` grouping related cleanup actions
- Each action: button + status badge + result count
**Power tab:**
- Metro form grid with labelled inputs and toggle switches
(`data-role="switch"`)
**AutoPipeline tab:**
- Step-builder as a sortable `data-role="listview"` with
`data-role="accordion"` detail panels per step
---
## Sidebar: Project Browser
### Current
Fixed-width div with search input, filter checkboxes, and a flat list of project cards.
### MetroUI Redesign
```
┌─────────────────────────────┐
│ 🔍 [Search input] │
│ Filter: [All ▼] │
├─────────────────────────────┤
│ ┌── Live Tile ─────────────┐│
│ │ Artist — Title ││ ← Metro medium tile
│ │ ████░░░░ Separating… ││ ← job progress strip at bottom
│ └──────────────────────────┘│
│ ┌── Tile ──────────────────┐│
│ │ Artist — Title ✓ ││
│ └──────────────────────────┘│
│ ... │
├─────────────────────────────┤
│ ▶ Imported Files │ ← metro accordion section
│ ▶ Subsonic Browser │
└─────────────────────────────┘
```
**MetroUI components:**
| UI element | MetroUI |
|------------|---------|
| Project tiles | Metro tile grid (`tile`, `tile-medium`) |
| Search | `data-role="input"` with search icon |
| Filter | `data-role="select"` |
| Imported files | `data-role="accordion"` > `data-role="listview"` |
| Subsonic tree | `data-role="accordion"` > `data-role="treeview"` |
Live Tile behaviour: tile background colour reflects job state —
- `bg-blue` — separating
- `bg-amber` — transcribing / aligning
- `bg-green` — complete
- `bg-red` — error
- Animated `data-role="activity"` spinner appears while any job is running.
---
## GlobalAudioBar
Fixed bottom strip, unchanged in function. Reskin with MetroUI:
- `<div class="app-bar bottom fixed">` container
- Metro-style playback buttons (`<button class="button cycle">`)
- `data-role="slider"` for seek bar and volume
- `<span class="badge">` for current stem label
---
## KaraokeEditor & LyricsLivePreview
**These components are NOT reskinned.** They are complex custom canvas/DOM components
with their own internal style systems (direct colour constants, inline styles).
They will be wrapped in a MetroUI `data-role="panel"` shell but their internals remain
unchanged. This is explicitly called out because they must not be broken by the migration.
---
## ThemeContext
Currently manages `light | dark | system` and applies a `dark` class to `<html>`.
Replaces the class toggle with MetroUI's `data-theme` attribute:
```ts
// was: document.documentElement.classList.toggle('dark', isDark)
document.documentElement.setAttribute('data-theme', isDark ? 'dark' : 'light')
```
Accent colours: set `data-accent` attribute on `<html>` exactly as now, but map to
MetroUI's built-in accent palette names (`blue`, `violet`, `crimson`, `green`,
`amber`, `cyan`).
---
## Migration Phases
### Phase 1 — Install & Shell (App.tsx)
1. `npm install @olton/metroui`; remove Tailwind packages.
2. Swap `index.css` imports; update `main.tsx`.
3. Rebuild `App.tsx` AppBar + SideNav shell in MetroUI classes.
4. Verify dark/light theme toggle and accent switching still work.
5. No page content changed yet — inner pages still render their existing JSX.
### Phase 2 — Sidebar
1. Project tile grid with job-status colour coding.
2. Imported files + Subsonic accordion sections.
3. Search input + filter select.
### Phase 3 — Separator page
1. Drop zone.
2. Model accordion + format radio tiles.
3. Slider group for stem levels.
4. Job progress + toast notifications.
### Phase 4 — ProjectDetail page
1. Panel sections (Stems, Karaoke Editor, Dynamic Mix, Lyrics Preview).
2. Stem tiles with badges + progress.
3. Action button dropdowns.
*(KaraokeEditor and LyricsLivePreview interiors untouched.)*
### Phase 5 — Settings page
1. Vertical tab nav.
2. Appearance: theme tiles, font select, accent tiles.
3. Models: listview with progress rows.
4. Subsonic: form + treeview.
5. Maintenance / Power / AutoPipeline panels.
### Phase 6 — GlobalAudioBar + polish
1. Reskin audio bar.
2. Remove any remaining Tailwind class remnants.
3. Audit icon usage — decide lucide SVG vs MetroUI icon font.
4. Cross-browser / dark-mode QA pass.
---
## What Does NOT Change
| Item | Reason |
|------|--------|
| `KaraokeEditor.tsx` internals | Custom canvas engine; MetroUI-independent |
| `LyricsLivePreview.tsx` internals | Custom RAF renderer |
| `api/client.ts` | Pure data layer |
| `utils/` | Pure logic |
| `ThemeContext.tsx` logic | Only the DOM attribute changes |
| TanStack React Query | Unaffected by styling |
| Tone.js / abcjs / midi | Audio/music — unaffected |
| Vite config | No changes needed |
| TypeScript types | Unaffected |
---
## Risk Notes
- **MetroUI JS and React event system**: MetroUI's JS-initialised components (dialog,
dropdown, tooltip) bypass React's synthetic event system. Use MetroUI CSS classes
only for those components and implement open/close logic in React state, or use the
MetroUI JS API via `useEffect` with refs — never let both systems control the same
element.
- **`data-role` auto-init**: MetroUI scans the DOM on load for `data-role` attributes
and initialises JS widgets. Components rendered after initial load (dynamically by
React) need `Metro.makePlugin(el, 'role-name')` called in a `useEffect` — or switch
to CSS-only for those elements.
- **Vite tree-shaking**: Metro bundles are monolithic (CSS + JS). Ensure `metro.css`
and `metro.js` are imported as side-effects (`"sideEffects": true` in package config
or explicit import) so Vite doesn't exclude them.
- **SSR / hydration**: Not applicable (Vite SPA mode, no SSR).