397 lines
17 KiB
Markdown
397 lines
17 KiB
Markdown
# 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).
|