Files
stemengine_old/StemEngine WebUI.md
T
2026-03-11 15:37:35 +09:00

23 KiB
Raw Blame History

StemEngine Web UI Redesign — MetroUI Plan

Redesign the StemEngine React frontend using the 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

npm install @olton/metroui

In main.tsx (replaces Tailwind imports in index.css):

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

Internal rendering is NOT reskinned. It is a custom canvas + DOM timing-table component with its own internal colour constants and inline styles. It will be wrapped in a MetroUI data-role="panel" shell (title bar + collapse toggle) but its internals remain unchanged. This is explicitly called out because it must not be broken by the migration.


LyricsLivePreview

LyricsLivePreview has two distinct layers with different treatment:

Lyrics display canvas — NOT reskinned with MetroUI

The animated lyrics rendering area (scrolling lines, word-fill gradient, glow/blur effects) is driven by a custom RAF loop with direct DOM/style mutations (and per the Karaoke Renderer (Two JS).md plan, will be replaced by a Two.js SVG scene). MetroUI does not touch this area.

UI shell — reskinned with MetroUI

All the surrounding controls and panels are standard HTML UI and are fully reskinned:

┌─ Lyrics Preview ─────────────────────────────────────── [⛶] [▼] ┐
│                                                                   │
│  ┌──────────────────────────────────────────────────────────────┐ │
│  │  [lyrics display canvas — Two.js / custom RAF, unchanged]   │ │
│  └──────────────────────────────────────────────────────────────┘ │
│                                                                   │
│  ┌─ Transport ──────────────────────────────────────────────────┐ │
│  │  [◀◀] [▶] [▶▶]   ══════════════●══════  0:32 / 3:47  🔊 ─● │ │
│  └──────────────────────────────────────────────────────────────┘ │
│                                                                   │
│  ┌─ Style ──────────────────────────────────────── [▼] ─────────┐ │
│  │  [scroll] [fade] [karaoke] [glow] [blur]  ← Metro radio tiles│ │
│  │  Font [select ▼]  Size [──●──]  Align [L] [C] [R]           │ │
│  │  Highlight ■  Word fill ■  Text ■  Bg ■                      │ │
│  │  [•] Stroke  width [─●─]  color ■                            │ │
│  │  [•] Shadow  x [─●─]  y [─●─]  blur [─●─]  color ■         │ │
│  └──────────────────────────────────────────────────────────────┘ │
│                                                                   │
│  ┌─ Speakers ───────────────────────────────────── [▼] ─────────┐ │
│  │  ● SPEAKER_00  [name input]                                  │ │
│  │  ● SPEAKER_01  [name input]                                  │ │
│  └──────────────────────────────────────────────────────────────┘ │
│                                                                   │
│  ┌─ LRC Editor ─────────────────────────────────── [▼] ─────────┐ │
│  │  [textarea]                          [Apply] [Reset]         │ │
│  └──────────────────────────────────────────────────────────────┘ │
└───────────────────────────────────────────────────────────────────┘

MetroUI components:

UI element MetroUI
Outer panel shell data-role="panel" with data-collapsible="true"
Visual style selector Metro tile grid with data-role="radio" (one tile per style mode)
Transport play/pause <button class="button cycle primary">
Seek bar data-role="slider"
Volume slider data-role="slider" with mute toggle button
Time display <span class="badge">
Font family data-role="select"
Font size data-role="slider" with numeric readout
Text alignment Three-button <button class="button"> group (L / C / R)
Colour pickers (highlight, fill, text, bg) data-role="color-picker" or data-role="input" data-type="color"
Stroke / shadow toggles data-role="switch"
Stroke width, shadow x/y/blur data-role="slider"
Speaker list data-role="listview" — each row has a colour swatch + editable name input
Speaker colour assignment Metro accent colour tile row
LRC text editor <textarea class="metro-input" rows="8">
Editor apply/reset buttons <button class="button primary"> / <button class="button">
Timing shift slider data-role="slider" (−15 s … +15 s) with numeric readout
Fullscreen toggle <button class="button square"> with mif-expand icon

Style picker as collapsible panel (default collapsed): The full style picker is wrapped in a data-role="panel" with data-collapsible="true" and data-collapsed="true" so it doesn't dominate the view. A single gear icon button in the lyrics panel title bar expands it. The transport controls remain always visible below the canvas.


ThemeContext

Currently manages light | dark | system and applies a dark class to <html>. Replaces the class toggle with MetroUI's data-theme attribute:

// 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 outer shell).
  2. Stem tiles with badges + progress.
  3. Action button dropdowns. (KaraokeEditor internals and the LyricsLivePreview rendering canvas 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.

Phase 7 — LyricsLivePreview UI shell

  1. Transport controls: play/pause cycle button, seek slider, volume slider + mute, time badge.
  2. Visual style selector: Metro radio tile row (scroll / fade / karaoke / glow / blur).
  3. Style picker panel: font select, size/alignment sliders, colour pickers, stroke/shadow switches + sliders.
  4. Speaker listview: colour swatch tiles + inline name inputs.
  5. LRC text editor: Metro textarea + apply/reset buttons.
  6. Timing shift slider.
  7. Fullscreen button (mif-expand icon).
  8. Verify the lyrics rendering canvas is visually unaffected (no MetroUI classes inside it).

What Does NOT Change

Item Reason
KaraokeEditor.tsx internals Custom canvas engine; MetroUI-independent
LyricsLivePreview.tsx — lyrics rendering canvas Custom RAF / Two.js scene; MetroUI-independent
LyricsLivePreview.tsx — UI shell (transport, style picker, speakers, editor) Does change — reskinned with MetroUI in Phase 7
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).