feat(frontend): slice 1 — foundation for MUI->shadcn migration
Web UI rework (openspec/changes/web-ui-rework). Foundation slice: - Add @tanstack/react-table; remove orphaned recharts, d3 - Vendor shadcn primitives: tabs table dialog input label checkbox switch progress separator avatar textarea dropdown-menu scroll-area - Add Vitest + @testing-library/react + jsdom harness; npm test script - Delete no-op theme.ts shim; remove getAppTheme references - Smoke test proves the harness Gate: build + lint + test green.
This commit is contained in:
Developer
@@ -0,0 +1,170 @@
|
||||
# Apply Progress — web-ui-rework
|
||||
|
||||
> Cumulative apply log. Updated by `sdd-apply` after each slice/sub-slice.
|
||||
> Strict TDD is **not** active for this change (no strict-tdd directive in
|
||||
> `openspec/config.yaml`); this run used standard mode against `design.md` / `tasks.md`.
|
||||
|
||||
## Status context consumed
|
||||
|
||||
- `schemaName: gentle-pi.sdd-status`, `changeName: web-ui-rework`.
|
||||
- `applyState` reported by the status engine: **blocked** (`blockedReasons`: domain
|
||||
specs missing/partial; legacy flat `spec.md` present without domain specs). This is a
|
||||
**planning-completeness** gap, not a safety/`actionContext` blocker.
|
||||
- `actionContext`: `mode: repo-local`, `workspaceRoot: /home/user/Manage_01`,
|
||||
`allowedEditRoots: ["/home/user/Manage_01"]`, `warnings: []` — safe.
|
||||
- This run executed the explicitly delegated **Slice 1 (Foundation)** scope per the
|
||||
parent acceptance contract. The foundation work is fully specified in `tasks.md`
|
||||
(Slice 1) and does not depend on the missing domain specs, so it proceeds under the
|
||||
parent's explicit delegation. The `instructions.apply` line itself says
|
||||
"Implement only unchecked tasks from the tasks artifact."
|
||||
- `artifactStore: openspec`; persisted task checkboxes updated in `tasks.md` (13 → `[x]`).
|
||||
|
||||
## Slice 1 — Foundation (primitives, TanStack Table, Vitest, token/Badge cleanup) — COMPLETE
|
||||
|
||||
All 13 Slice-1 tasks in `tasks.md` are marked `- [x]`. Summary below.
|
||||
|
||||
### Completed tasks (persisted checkboxes updated)
|
||||
|
||||
- [x] Added the missing shadcn primitives (13): `tabs table dialog input label checkbox
|
||||
switch progress separator avatar textarea dropdown-menu scroll-area` via
|
||||
`npx shadcn@latest add …`. The 9 already-present primitives
|
||||
(`button tooltip sheet card badge alert select skeleton collapsible`) were **not** re-added.
|
||||
- [x] Installed `@tanstack/react-table` (`^8.21.3`, dependency).
|
||||
- [x] Removed orphaned charting deps: `recharts`, `d3`, and the companion `@types/d3`
|
||||
from `package.json` (zero `from "recharts"` / `from "d3"` / `from "d3-*"` imports
|
||||
existed in `frontend/src`).
|
||||
- [x] Deleted `frontend/src/theme.ts` (no-op `getAppTheme` shim). Grep confirmed the
|
||||
only reference was the file itself; no source file imported it.
|
||||
- [x] Added the `success` Badge variant (`chart-2`) and the `warning` variant (`chart-3`)
|
||||
to `frontend/src/components/ui/badge.tsx`, mirroring the `destructive` soft-cue pattern
|
||||
exactly per design §2.3.
|
||||
- [x] Documented the `chart-1..5` role mapping as an inline comment block above the
|
||||
tokens in **both** the `@theme` block and `.dark` block of `frontend/src/index.css`
|
||||
(chart-1=info/brand, chart-2=success, chart-3=warning, chart-4=destructive,
|
||||
chart-5=neutral-accent). **No token value changed; no token dropped. Primary `#4f8cff`.**
|
||||
- [x] Created `frontend/vitest.config.ts` (separate from `vite.config.ts`):
|
||||
`vitest/config` `defineConfig`, `@vitejs/plugin-react`, `environment: "jsdom"`,
|
||||
`globals: true`, `setupFiles: ["./src/test/setup.ts"]`, the `@` path alias from
|
||||
`tsconfig.app.json`, and `include: ["src/**/*.{test,spec}.{ts,tsx}"]` (does NOT claim
|
||||
the `frontend/tests/*.mjs` node suites).
|
||||
- [x] Created `frontend/src/test/setup.ts` registering `@testing-library/jest-dom`
|
||||
matchers (via the `/vitest` entry for runtime + TS augmentation).
|
||||
- [x] Installed dev deps: `vitest@^4.1.9`, `@testing-library/react@^16.3.2`,
|
||||
`@testing-library/jest-dom@^6.9.1`, `@testing-library/user-event@^14.6.1`,
|
||||
`jsdom@^29.1.1`.
|
||||
- [x] Added npm scripts: `"test": "vitest run"`, `"test:watch": "vitest"`,
|
||||
`"test:node": "node --test tests/*.test.mjs"` (see Deviations).
|
||||
- [x] Added one trivial passing component test: `src/components/ui/__tests__/badge.test.tsx`
|
||||
(asserts a `success` Badge renders with the `chart-2` cue).
|
||||
- [x] Verified lucide-react `1.14.0` exports every name used by later slices:
|
||||
`Pencil, X, Paperclip, Bold, Italic, Link, List, Mail, Send, Trash2, DatabaseBackup,
|
||||
ExternalLink`. **`DatabaseBackup` IS exported — no fallback needed** (slice-3 nav will
|
||||
use `DatabaseBackup`).
|
||||
- [x] **Exit gate green:** `npm run build` + `npm run lint` + `npm test` + `npm run
|
||||
test:node` all pass; no `theme`/`getAppTheme` imports remain.
|
||||
|
||||
### Files changed (tracked)
|
||||
|
||||
Modified:
|
||||
|
||||
- `frontend/package.json` (added `@tanstack/react-table`, vitest/testing-library/jsdom
|
||||
dev deps, test scripts; removed `recharts`, `d3`, `@types/d3`)
|
||||
- `frontend/package-lock.json` (regenerated by npm)
|
||||
- `frontend/src/components/ui/badge.tsx` (added `success` + `warning` variants)
|
||||
- `frontend/src/components/ui/tabs.tsx` (vendored primitive; un-exported
|
||||
`tabsListVariants` to satisfy `react-refresh/only-export-components` — see Deviations)
|
||||
- `frontend/src/index.css` (chart-1..5 role-mapping comment blocks in `@theme` + `.dark`)
|
||||
|
||||
Deleted:
|
||||
|
||||
- `frontend/src/theme.ts`
|
||||
|
||||
Added (new):
|
||||
|
||||
- `frontend/vitest.config.ts`
|
||||
- `frontend/src/test/setup.ts`
|
||||
- `frontend/src/components/ui/__tests__/badge.test.tsx`
|
||||
- 13 new shadcn primitives under `frontend/src/components/ui/`:
|
||||
`tabs.tsx, table.tsx, dialog.tsx, input.tsx, label.tsx, checkbox.tsx, switch.tsx,
|
||||
progress.tsx, separator.tsx, avatar.tsx, textarea.tsx, dropdown-menu.tsx,
|
||||
scroll-area.tsx`
|
||||
|
||||
Untouched (no-unintended-edits respected): the 22 MUI page/component files in
|
||||
Slice 1's scope (all `frontend/src/pages/*` and `frontend/src/components/*.tsx` outside
|
||||
`components/ui/`) — `git status --porcelain frontend/src/pages 'frontend/src/components/*.tsx'
|
||||
| grep -v 'components/ui/'` returns nothing.
|
||||
|
||||
Also touched (gitignored generated docs, not tracked changes): `frontend/src/.pi-map.md`
|
||||
and `frontend/src/.pi-map.index.md` were refreshed to remove the now-deleted `theme.ts` /
|
||||
`getAppTheme` references (the `project_map_patch` tool is unavailable in this session, so
|
||||
the stale generated maps were minimally reconciled to match source).
|
||||
|
||||
### Commands run (validation)
|
||||
|
||||
- `npx shadcn@latest add tabs table dialog input label checkbox switch progress separator avatar textarea dropdown-menu scroll-area --yes` → created 14 files (13 primitives + a duplicate button written to a stray `@/` path; stray dir removed, dup button discarded).
|
||||
- `npm i @tanstack/react-table` → ok.
|
||||
- `npm i -D vitest @testing-library/react @testing-library/jest-dom @testing-library/user-event jsdom` → ok.
|
||||
- `npm uninstall recharts d3 @types/d3` → ok.
|
||||
- `cd frontend && npm run build` → **PASS** (`tsc -b` + `vite build`).
|
||||
- `cd frontend && npm run lint` → **PASS** (0 errors, 0 errors; 2 pre-existing `react-hooks/exhaustive-deps` warnings in `UsersPage.impl.tsx` that are out of Slice-1 scope).
|
||||
- `cd frontend && npm test` → **PASS** (Vitest: 1 file, 1 test passed).
|
||||
- `cd frontend && npm run test:node` → **PASS** (legacy node:test suites green).
|
||||
|
||||
### Deviations from design / task text (documented)
|
||||
|
||||
1. **`tabs.tsx` variant export.** The vendored shadcn `tabs.tsx` exported
|
||||
`tabsListVariants` (a `cva` function) alongside components, which violates
|
||||
`react-refresh/only-export-components` and broke `npm run lint`. The project's own
|
||||
convention (`button.tsx`, `select.tsx`) is to **not** export the `cva` variant helper,
|
||||
so `tabsListVariants` was removed from the `export { … }` statement (the `const` is
|
||||
retained for internal use by `TabsList`). This keeps the component API intact for all
|
||||
later slices (TabbedCard uses `<TabsList variant=…>`, not the helper).
|
||||
2. **`test:node` script form.** The task text specifies `"test:node": "node --test tests"`,
|
||||
but on **Node v22.22.2** a bare directory argument is resolved as a CommonJS module
|
||||
entry point (`Error: Cannot find module '…/tests'`). The functional equivalent
|
||||
`"test:node": "node --test tests/*.test.mjs"` is used instead, which targets exactly
|
||||
the legacy node:test suites (`users.test.mjs`, `userState.test.mjs`) and passes.
|
||||
`node --test` auto-discovery also passes; the glob form is the explicit, minimal choice.
|
||||
3. **shadcn CLI path artifact.** The CLI resolved the `@/` alias to a literal
|
||||
`frontend/@/` directory. All 13 primitives were moved to `frontend/src/components/ui/`
|
||||
and the stray `frontend/@/` tree was deleted; the duplicate generated `button.tsx`
|
||||
was discarded to keep the existing tracked `button.tsx` unchanged.
|
||||
4. **Stale generated `.pi-map.md`** files referenced the deleted `theme.ts`. Since the
|
||||
`project_map_patch` tool is unavailable this session, they were minimally reconciled to
|
||||
match source (these are gitignored generated docs, not tracked changes).
|
||||
|
||||
### Slice boundary / PR
|
||||
|
||||
- Slice 1 is the foundation slice (~vendored primitives dominate the line count).
|
||||
Per the Review Workload Forecast this slice is "at/over" 400 lines and may be taken as
|
||||
a vendored-primitives **size exception** or sub-split 1a/1b. The majority of the diff is
|
||||
generated shadcn primitives (mechanical, vendored). **No delivery decision was provided
|
||||
in this run's delegation** (the parent delegated a single foundation slice); this run
|
||||
implemented the whole foundation in one slice. The parent should confirm the PR shape
|
||||
(1a/1b split vs. generated-code size exception) when opening the PR.
|
||||
|
||||
## Remaining tasks (Slices 2–8, 58 unchecked)
|
||||
|
||||
Slice 1 is the only completed slice. The remaining unchecked work (Slices 2–8) is listed
|
||||
verbatim in `tasks.md`. The first unchecked items are (Slice 2 — Shared components):
|
||||
|
||||
- [ ] Migrate `frontend/src/components/SectionCard.tsx` …
|
||||
- [ ] Migrate `frontend/src/components/SelectionRailCard.tsx` …
|
||||
- [ ] … (see `tasks.md` Slice 2 → Slice 8)
|
||||
|
||||
Dependency order is fixed (DAG in `tasks.md`): `1 → 2 → {3,4,5,6}`; `4 ← 3`;
|
||||
`{3,4,5,6} → 7`; `{1..7} → 8`. **Next recommended:** Slice 2 (Shared components) — it is
|
||||
unblocked now that all primitives, TanStack Table, the Vitest harness, the `success`/
|
||||
`warning` Badge variants, and the cleared `theme.ts` are in place.
|
||||
|
||||
## Risks / notes for the parent
|
||||
|
||||
- The overall change `applyState` is **blocked** on **missing domain specs** (legacy flat
|
||||
`spec.md` present without domain specs). This does not block Slice 1 (done) but should
|
||||
be resolved before `sdd-verify`/archive. Recommended: convert/supplement `spec.md` into
|
||||
domain specs, or have the orchestrator confirm the flat spec is acceptable.
|
||||
- The two `react-hooks/exhaustive-deps` **warnings** in `UsersPage.impl.tsx` are
|
||||
pre-existing and out of Slice-1 scope (lint still passes — warnings, not errors).
|
||||
- `npm audit` reports 8 vulnerabilities in the dependency tree (pre-existing across the
|
||||
MUI/emotion/react stack); not introduced by this slice and out of scope.
|
||||
- `DatabaseBackup` from lucide-react is available — Slice 3 nav should use it directly.
|
||||
@@ -0,0 +1,465 @@
|
||||
# Design — web-ui-rework
|
||||
|
||||
> Phase: **design**. Technical design (not implementation) for finishing the
|
||||
> MUI v9 → shadcn/ui + Tailwind v4 + lucide-react migration and reconciling the
|
||||
> Manage information architecture to a single, coherent, thin-dashboard UI.
|
||||
>
|
||||
> Grounded in `exploration.md` (verified inventory), `proposal.md`, and
|
||||
> `spec.md` (locked decisions). No source changes in this phase.
|
||||
|
||||
## 0. Locked design constraints (do not re-litigate)
|
||||
|
||||
These are settled by the spec and bound every decision below:
|
||||
|
||||
- **Single design system:** shadcn/ui + Tailwind v4 `@theme` tokens + lucide-react only. Zero `@mui/*` / `@emotion/*` / `recharts` / `d3` at the end; `theme.ts` deleted in slice 1.
|
||||
- **IA:** Backups becomes a top-level nav item; the Media/Applications surface is named **"Media"** at canonical route **`/media`**; **`/applications` → redirect (replace) to `/media`**, mirroring the existing `/monitoring` → `/observability` redirect in `App.tsx`. Auth (`auth.ts`, `react-oidc-context`) and `react-router-dom` structure otherwise unchanged.
|
||||
- **TanStack Table:** **visibility-only** parity — pagination, row selection, row click, column visibility. **No sorting, no resizing.**
|
||||
- **Palette:** primary stays `#4f8cff`; `chart-1..5` tokens **repurposed** as status/Grafana-link semantic cues (not dropped).
|
||||
- **Density:** comfortable everywhere (`p-4 md:p-6`, `gap-4`); **no compact mode**.
|
||||
- **Test harness:** Vitest + `@testing-library/react` introduced in slice 1.
|
||||
- **Delivery:** force-chained PRs, ≤400 changed lines/slice; ~8 slices per exploration §9.
|
||||
- **Observability model:** thin dashboard, **no in-app charting**, Grafana deep-links preserved.
|
||||
|
||||
## 1. MUI → shadcn/ui + Tailwind component mapping table
|
||||
|
||||
Authoritative destination for every MUI component present across the 22
|
||||
`@mui/material` consumers (see exploration §2a for per-file frequency). The 22
|
||||
files follow this table verbatim; deviation requires a design-note in the
|
||||
slice's tasks file.
|
||||
|
||||
| MUI component | Destination | shadcn primitive / Tailwind pattern | Status |
|
||||
|---|---|---|---|
|
||||
| `Typography` | semantic element + text utilities | `<h1>`–`<h6>`/`<p>`/`<span>` + `text-* font-*` per the §2 ramp | none needed |
|
||||
| `Box` | `<div>` + utilities | `<div className="…">` with flex/grid utilities | none needed |
|
||||
| `Stack` | `<div>` flex stack | `<div className="flex flex-col gap-4">` (or `flex-row gap-*`) | none needed |
|
||||
| `Grid` | CSS grid `<div>` | `<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">` w/ responsive `md:`/`lg:` | none needed |
|
||||
| `Paper` | bordered surface `<div>` or `Card` | `<div className="rounded-lg border bg-card">`; prefer `Card` where it already wraps a titled section | none needed |
|
||||
| `Card` / `CardContent` | shadcn `Card` / `CardContent` | `@/components/ui/card` (Card, CardHeader, CardTitle, CardDescription, CardAction, CardContent, CardFooter) | **present** |
|
||||
| `Chip` | `Badge` | `@/components/ui/badge` (variants incl. new `success` — §2) | **present** |
|
||||
| `Button` | `Button` | `@/components/ui/button` (`variant`, `size`) | **present** |
|
||||
| `IconButton` | `Button size="icon"` | `<Button variant="ghost" size="icon">` (pattern already used in the shell) | **present** |
|
||||
| `Tooltip` | `Tooltip` family | `@/components/ui/tooltip` (TooltipProvider/Tooltip/TooltipTrigger/TooltipContent) | **present** |
|
||||
| `Alert` | `Alert` family | `@/components/ui/alert` (Alert, AlertTitle, AlertDescription) | **present** |
|
||||
| `Table` / `TableHead` / `TableBody` / `TableRow` / `TableCell` / `TableContainer` | shadcn `Table` family | `@/components/ui/table` (Table, TableHeader, TableBody, TableRow, TableHead, TableCell, TableCaption) | **add** |
|
||||
| `Tabs` / `Tab` | shadcn `Tabs` | `@/components/ui/tabs` (Tabs, TabsList, TabsTrigger, TabsContent) | **add** |
|
||||
| `Dialog` / `DialogTitle` / `DialogContent` / `DialogActions` | shadcn `Dialog` | `@/components/ui/dialog` (Dialog, DialogTrigger, DialogContent, DialogHeader, DialogTitle, DialogDescription, DialogFooter, DialogClose) | **add** |
|
||||
| `TextField` | `Input` (+ `Label`) | `@/components/ui/input`, `@/components/ui/label` | **add** |
|
||||
| `Select` / `MenuItem` / `FormControl` / `InputLabel` | shadcn `Select` | `@/components/ui/select` (Select, SelectTrigger, SelectValue, SelectContent, SelectItem, SelectGroup, SelectLabel) | **present** |
|
||||
| `Switch` | `Switch` | `@/components/ui/switch` | **add** |
|
||||
| `Checkbox` | `Checkbox` | `@/components/ui/checkbox` | **add** |
|
||||
| `LinearProgress` | `Progress` | `@/components/ui/progress` (indeterminate via animated class) | **add** |
|
||||
| `Divider` | `Separator` | `@/components/ui/separator` | **add** |
|
||||
| `Avatar` | `Avatar` | `@/components/ui/avatar` (Avatar, AvatarImage, AvatarFallback) | **add** |
|
||||
| `Drawer` | `Sheet side="right"` | `@/components/ui/sheet` (already used for mobile nav) | **present** |
|
||||
| `FormControlLabel` | `Label` + control | `<Label>` wrapping the control; or sibling `<div className="flex items-center gap-2">` | **add** `Label` |
|
||||
| `FormHelperText` | muted `<p>` | `<p className="text-xs text-muted-foreground">` | none needed |
|
||||
| `DataGrid` (`@mui/x-data-grid`) | TanStack Table + `Table` | reusable `DataTable` wrapper (§3) on shadcn `Table` | **add** `@tanstack/react-table` |
|
||||
|
||||
**Shared Tailwind layout patterns (anti-drift reference for all 22 files):**
|
||||
|
||||
- **Vertical stack:** `<div className="flex flex-col gap-4">` (replaces MUI `<Stack direction="column" spacing={n}>`).
|
||||
- **Horizontal row:** `<div className="flex flex-row items-center gap-2">`.
|
||||
- **Responsive grid:** `<div className="grid grid-cols-1 gap-4 md:grid-cols-2 lg:grid-cols-3">` (replaces MUI `<Grid>` + `<Grid item xs={…} md={…}>`).
|
||||
- **Page section:** `SectionCard` (migrated in slice 2) wraps titled sections; consistent `gap-4` between cards.
|
||||
- **Single surface treatment:** one border weight (`border-border`) and one radius (`rounded-lg` = `--radius` 0.625rem).
|
||||
|
||||
## 2. Token + theme design (`frontend/src/index.css`)
|
||||
|
||||
The existing Tailwind v4 `@theme` block is already a complete shadcn-style
|
||||
system (verified against current source). The edits are surgical: keep the
|
||||
palette, repurpose the chart tokens with documented roles, and add the `success`
|
||||
Badge variant. `tailwind.config.cjs` stays minimal (content glob only) — no JS
|
||||
theme config is introduced.
|
||||
|
||||
### 2.1 Palette — primary unchanged, `chart-1..5` repurposed
|
||||
|
||||
Primary remains `#4f8cff` (light + dark). The five `--color-chart-*` tokens are
|
||||
retained at their current hues and documented in `index.css` as the **status /
|
||||
Grafana-link semantic cue** source of truth. Single source of truth: Badge
|
||||
variants and status code map to the `chart-N` tokens directly, **not** to
|
||||
parallel `--color-success` aliases (which would drift).
|
||||
|
||||
| Token | Current value | Repurposed role | Consumed by |
|
||||
|---|---|---|---|
|
||||
| `--color-chart-1` | `#4f8cff` | **info** — default/informational status; also the Grafana deep-link brand cue (matches primary) | `Badge variant="default"`; Grafana-link `ExternalLink` affordance |
|
||||
| `--color-chart-2` | `#22c55e` | **success** — healthy/OK (target up, run succeeded, resolved) | `Badge variant="success"` (new, §2.3) |
|
||||
| `--color-chart-3` | `#f59e0b` | **warning** — pending/stale/missed-schedule | `Badge variant="warning"` (optional, map at call site) |
|
||||
| `--color-chart-4` | `#ef4444` | **destructive** — error / firing alert (already aligns with `--color-destructive`) | `Badge variant="destructive"`; Alertmanager firing |
|
||||
| `--color-chart-5` | `#8b5cf6` | **neutral-accent** — unknown/paused/secondary, and Grafana Explore deep-link cue (distinct from brand/destructive) | `Badge variant="secondary"` accents; Explore links |
|
||||
|
||||
**Concrete `index.css` edit shape:** add an inline comment block above the
|
||||
`chart-1..5` lines in both the `@theme` block and `.dark` block documenting the
|
||||
role mapping above. No token values change; no token is removed. Example:
|
||||
|
||||
```css
|
||||
@theme {
|
||||
/* …unchanged… */
|
||||
/* Status / Grafana-link semantic cues — single source of truth for Badges.
|
||||
chart-1=info/brand, chart-2=success, chart-3=warning,
|
||||
chart-4=destructive, chart-5=neutral-accent. */
|
||||
--color-chart-1: #4f8cff;
|
||||
--color-chart-2: #22c55e;
|
||||
--color-chart-3: #f59e0b;
|
||||
--color-chart-4: #ef4444;
|
||||
--color-chart-5: #8b5cf6;
|
||||
}
|
||||
```
|
||||
|
||||
### 2.2 Density + typography ramp (comfortable, no compact mode)
|
||||
|
||||
Codified as the standard every page follows (already matches the migrated
|
||||
shell `<main className="p-4 md:p-6">` and `gap-4`):
|
||||
|
||||
- **Page padding:** `p-4 md:p-6` (the shell `<main>` already provides this; pages must not double-pad).
|
||||
- **Card / section gap:** `gap-4` between cards; `space-y-4` for stacked sections.
|
||||
- **Typography ramp:**
|
||||
- Page title — `text-lg font-semibold` (rendered by `TopBar` from `navItems`).
|
||||
- Section title — `text-base font-semibold`.
|
||||
- Body — `text-sm`.
|
||||
- Caption / helper — `text-xs text-muted-foreground`.
|
||||
- **Radius:** one — `rounded-lg` (`--radius: 0.625rem`).
|
||||
- **No compact/dense mode** anywhere: Media, Users, Backups runs all use the same comfortable row padding (`<TableCell className="py-3">`). No density toggle is introduced.
|
||||
|
||||
### 2.3 `success` Badge variant to add (`frontend/src/components/ui/badge.tsx`)
|
||||
|
||||
The current `badge.tsx` exposes variants `default | secondary | destructive |
|
||||
outline | ghost | link` — there is **no success/healthy variant**. Add one,
|
||||
mirroring the existing `destructive` soft-cue pattern and drawing color from the
|
||||
repurposed `chart-2` token so the cue is the documented source of truth:
|
||||
|
||||
```ts
|
||||
// inside badgeVariants variants: { …
|
||||
success:
|
||||
"bg-chart-2/10 text-chart-2 focus-visible:ring-chart-2/20 dark:bg-chart-2/20 dark:focus-visible:ring-chart-2/40 [a]:hover:bg-chart-2/20",
|
||||
// optional warning (chart-3) may be added identically if a call site needs it
|
||||
// }
|
||||
```
|
||||
|
||||
Tailwind v4 resolves `chart-2` from the `--color-chart-2` `@theme` token, so
|
||||
`text-chart-2` / `bg-chart-2/10` / `ring-chart-2/20` are valid utilities.
|
||||
|
||||
**Status → variant mapping (consumed consistently by Backups, Observability, Users):**
|
||||
|
||||
| Domain status | Badge variant | Cue token |
|
||||
|---|---|---|
|
||||
| healthy / OK / succeeded / up | `success` | `chart-2` |
|
||||
| informational / default | `default` | `chart-1` |
|
||||
| neutral / secondary / unknown | `secondary` | `chart-5` accent |
|
||||
| pending / stale / warning | `warning` (add if needed) or `secondary` | `chart-3` |
|
||||
| error / firing alert / failed | `destructive` | `chart-4` |
|
||||
|
||||
## 3. TanStack Table design — reusable `DataTable` wrapper
|
||||
|
||||
Both DataGrid surfaces (`Media.tsx`, `FileBrowser.impl.tsx`) are rebuilt on a
|
||||
single headless `@tanstack/react-table` instance styled with the shadcn `Table`
|
||||
primitive, behind a thin reusable wrapper. **Feature scope is visibility-only**
|
||||
(locked): pagination, row selection, row click, column visibility. Sorting and
|
||||
resizing are explicit non-goals.
|
||||
|
||||
### 3.1 Component shape
|
||||
|
||||
`frontend/src/components/ui/data-table.tsx` — a generic wrapper built on
|
||||
`@/components/ui/table`. Props shape (design, not full impl):
|
||||
|
||||
```ts
|
||||
import type { ColumnDef, OnChangeFn, RowSelectionState,
|
||||
VisibilityState, PaginationState } from "@tanstack/react-table";
|
||||
|
||||
interface DataTableProps<TData, TValue> {
|
||||
columns: ColumnDef<TData, TValue>[];
|
||||
data: TData[];
|
||||
// stable identity (Media needs path-derived id so selection survives paging)
|
||||
getRowId?: (row: TData, index: number) => string;
|
||||
// visibility-only feature set
|
||||
enableRowSelection?: boolean;
|
||||
rowSelection?: RowSelectionState;
|
||||
onRowSelectionChange?: OnChangeFn<RowSelectionState>;
|
||||
onRowClick?: (row: TData) => void; // Media→open files; FileBrowser→preview
|
||||
columnVisibility?: VisibilityState;
|
||||
onColumnVisibilityChange?: OnChangeFn<VisibilityState>;
|
||||
enableColumnVisibilityToggle?: boolean; // renders the column dropdown
|
||||
// pagination (Media only; FileBrowser does not paginate)
|
||||
enablePagination?: boolean;
|
||||
manualPagination?: boolean; // Media: server-driven via limit/offset
|
||||
pagination?: PaginationState;
|
||||
onPaginationChange?: OnChangeFn<PaginationState>;
|
||||
pageSizeOptions?: number[];
|
||||
rowCount?: number; // server total for Media
|
||||
emptyMessage?: string;
|
||||
}
|
||||
```
|
||||
|
||||
Internally, `DataTable` calls `useReactTable` wired as follows:
|
||||
|
||||
- **Core:** `getCoreRowModel: getCoreRowModel()`.
|
||||
- **Pagination:** `getPaginationRowModel: getPaginationRowModel()` only when `enablePagination` and **not** `manualPagination`. When `manualPagination` is true (Media), the table renders the supplied slice and `rowCount` drives the pager; the page index/size are lifted to the parent and feed `useMediaQuery` limit/offset.
|
||||
- **Selection:** `enableRowSelection: true` gated by the prop; `rowSelection` state is controlled by the parent.
|
||||
- **Column visibility:** `columnVisibility` state controlled by the parent; a `DropdownMenu` + `Checkbox` list renders the toggle UI when `enableColumnVisibilityToggle`.
|
||||
- **Row click:** `<TableRow onClick={() => onRowClick?.(row.original)}>` with `className="cursor-pointer"` when `onRowClick` is set; selection column click stops propagation so checkboxes do not trigger navigation.
|
||||
- **Selection column:** a leading display `ColumnDef` rendering a `Checkbox` (header = select-all-on-page via `table.getIsSomeRowsSelected()/getIsSelected()`), present only when `enableRowSelection`.
|
||||
|
||||
### 3.2 Column-def typing pattern
|
||||
|
||||
Columns are declared as `ColumnDef<TData>[]` with `accessorKey`/`accessorFn`,
|
||||
`header`, and `cell` returning a styled `<TableCell>` child. Static widths use
|
||||
Tailwind classes on the cell content (e.g. `className="w-[120px]`) — **no**
|
||||
TanStack `size`/`enableColumnResizing` (locked out). No column sets
|
||||
`enableSorting`; the table instance never receives `getSortedRowModel`.
|
||||
|
||||
### 3.3 Explicit non-goals (enforced)
|
||||
|
||||
- **No sorting:** no `getSortedRowModel`, no sortable header affordance, no sort indicators. Media's existing external filter controls (search/type/library/HDR) remain the only filtering path.
|
||||
- **No resizing:** `enableColumnResizing` unset; no resize handles rendered.
|
||||
|
||||
### 3.4 Consumer contracts
|
||||
|
||||
**`pages/Media.tsx`** — builds `mediaColumns: ColumnDef<MediaItem>[]` for the 15
|
||||
pre-rework columns (`title, series, season, episode, type, year, runtime_min,
|
||||
size, bitrate, hdr, video, resolution, date_added, library, path`) and renders
|
||||
`<DataTable>` with: `enableRowSelection`, `enablePagination` + `manualPagination`
|
||||
- `rowCount` (driven by `queryResult.total`), `onRowClick` →
|
||||
`navigate('/files?path=…')`, and `enableColumnVisibilityToggle`. Pagination and
|
||||
column-visibility state persist via the existing `usePersistentState` media
|
||||
state, feeding `useMediaQuery({ limit, offset, … })`. The toggleable column set
|
||||
matches the locked list in the spec scenario.
|
||||
|
||||
**`pages/FileBrowser.impl.tsx`** — builds `fileColumns: ColumnDef<FileEntry>[]`
|
||||
for the 5 columns (`type, name, ext, size, modified`) and renders `<DataTable>`
|
||||
with: `enableRowSelection`, `onRowClick` → selects the file for ffprobe preview,
|
||||
and `enableColumnVisibilityToggle`. **No pagination** (the directory listing is
|
||||
rendered in full, as today). Column-visibility state persists via the existing
|
||||
browser state.
|
||||
|
||||
## 4. Navigation / IA design (`frontend/src/App.tsx`)
|
||||
|
||||
Three surgical edits, mirroring the established `/monitoring` → `/observability`
|
||||
redirect pattern. Auth and routing structure are otherwise untouched.
|
||||
|
||||
### 4.1 `navItems` change
|
||||
|
||||
Current:
|
||||
|
||||
```ts
|
||||
const navItems = [
|
||||
{ path: "/", label: "Dashboard", icon: LayoutDashboard },
|
||||
{ path: "/observability", label: "Observability", icon: Activity },
|
||||
{ path: "/applications", label: "Media", icon: Monitor },
|
||||
{ path: "/files", label: "Files", icon: FolderOpen },
|
||||
{ path: "/users", label: "Users", icon: Users },
|
||||
{ path: "/actions", label: "Actions", icon: Zap },
|
||||
{ path: "/settings", label: "Settings", icon: SettingsIcon },
|
||||
];
|
||||
```
|
||||
|
||||
Target — retarget Media to `/media`, **add a top-level Backups item**, and import
|
||||
a lucide icon for it:
|
||||
|
||||
```ts
|
||||
import { /* …existing…, */ DatabaseBackup } from "lucide-react";
|
||||
|
||||
const navItems = [
|
||||
{ path: "/", label: "Dashboard", icon: LayoutDashboard },
|
||||
{ path: "/observability", label: "Observability", icon: Activity },
|
||||
{ path: "/media", label: "Media", icon: Monitor },
|
||||
{ path: "/files", label: "Files", icon: FolderOpen },
|
||||
{ path: "/backups", label: "Backups", icon: DatabaseBackup },
|
||||
{ path: "/users", label: "Users", icon: Users },
|
||||
{ path: "/actions", label: "Actions", icon: Zap },
|
||||
{ path: "/settings", label: "Settings", icon: SettingsIcon },
|
||||
];
|
||||
```
|
||||
|
||||
**Icon choice + fallback:** `DatabaseBackup` is the semantic fit; if the pinned
|
||||
`lucide-react@^1.14.0` (see §8 risk) does not export it, fall back to `HardDrive`
|
||||
or `Archive` (both are long-standing exports). Verify the export before the
|
||||
Backups slice (slice 3). Backups is placed after Files (operational grouping) and
|
||||
before Users.
|
||||
|
||||
### 4.2 Route changes
|
||||
|
||||
In **both** route blocks (the OIDC-configured branch and the unauthenticated
|
||||
branch), make `/media` the canonical element and convert `/applications` to a
|
||||
replace-redirect, exactly mirroring `/monitoring`:
|
||||
|
||||
```tsx
|
||||
<Route path="/media" element={<Applications />} />
|
||||
<Route path="/applications" element={<Navigate to="/media" replace />} />
|
||||
```
|
||||
|
||||
`/backups` already renders `<BackupsPage />`; no route addition is needed (only
|
||||
the nav item). The page component remains `Applications` (the `Applications.tsx`
|
||||
file rename is **out of scope** — non-goal: routing structure unchanged); only
|
||||
the nav label + canonical route change.
|
||||
|
||||
## 5. Icon migration — MUI → lucide-react
|
||||
|
||||
The 10 distinct `@mui/icons-material` icons map as follows (from exploration §2c):
|
||||
|
||||
| File | MUI icon | lucide-react |
|
||||
|---|---|---|
|
||||
| `components/HoverEditButton.tsx` | `EditOutlined` | `Pencil` |
|
||||
| `pages/UsersPage.impl.tsx` | `Close` | `X` |
|
||||
| `pages/UsersPage.impl.tsx` | `AttachFile` | `Paperclip` |
|
||||
| `pages/UsersPage.impl.tsx` | `FormatBold` | `Bold` |
|
||||
| `pages/UsersPage.impl.tsx` | `FormatItalic` | `Italic` |
|
||||
| `pages/UsersPage.impl.tsx` | `Link` | `Link` |
|
||||
| `pages/UsersPage.impl.tsx` | `FormatListBulleted` | `List` |
|
||||
| `pages/UsersPage.impl.tsx` | `MailOutlined` | `Mail` |
|
||||
| `pages/UsersPage.impl.tsx` | `Send` | `Send` |
|
||||
| `pages/UsersPage.impl.tsx` | `DeleteOutlined` | `Trash2` |
|
||||
|
||||
**Version-pin verification (required gate):** `package.json` pins
|
||||
`lucide-react: ^1.14.0`, an unusual major. All 10 names above (plus
|
||||
`DatabaseBackup`, `ExternalLink` already in use) are standard lucide exports,
|
||||
but the exact pin must be verified to export them **before the UsersPage slice
|
||||
(slice 6)** and the Backups icon (slice 3). Verification step: in a scratch
|
||||
build, import each name from the pinned version; if any is missing, pick the
|
||||
nearest lucide equivalent (e.g. `DatabaseBackup` → `HardDrive`) or bump the pin
|
||||
within `^1.x` as a slice-1 foundation task. The icon set for the already-migrated
|
||||
`ObservabilityPage` (12 icons) and shell is the proof that common names exist at
|
||||
this pin.
|
||||
|
||||
## 6. Vitest setup design (slice 1)
|
||||
|
||||
A minimal component-test harness is introduced in the foundation slice. It must
|
||||
coexist with — not replace — the existing `node --test` suites in
|
||||
`frontend/tests/*.mjs`.
|
||||
|
||||
### 6.1 Config + scripts
|
||||
|
||||
- **Config file:** `frontend/vitest.config.ts` (separate from `vite.config.ts` to
|
||||
keep the build config clean), using `defineConfig` from `vitest/config`,
|
||||
`@vitejs/plugin-react`, `test.environment: "jsdom"`, `test.globals: true`,
|
||||
`test.setupFiles: ["./src/test/setup.ts"]`, the `@` path alias from
|
||||
`tsconfig.app.json`, and `test.include: ["src/**/*.{test,spec}.{ts,tsx}"]` so
|
||||
Vitest does **not** claim the `frontend/tests/*.mjs` node suites.
|
||||
- **Setup file:** `frontend/src/test/setup.ts` importing
|
||||
`@testing-library/jest-dom` (matcher registration).
|
||||
- **npm scripts (added to `package.json`):**
|
||||
- `"test": "vitest run"` — single-run CI gate.
|
||||
- `"test:watch": "vitest"` — watch mode for local dev.
|
||||
- `"test:node": "node --test tests"` — keeps the existing node suites runnable explicitly (they also still run directly).
|
||||
|
||||
### 6.2 Dev dependencies added in slice 1
|
||||
|
||||
`vitest`, `@testing-library/react`, `@testing-library/jest-dom`,
|
||||
`@testing-library/user-event`, `jsdom`. (Runtime deps untouched here.)
|
||||
|
||||
### 6.3 Example test shape (for a migrated component)
|
||||
|
||||
Co-located component test for a slice-2 shared block, asserting migrated
|
||||
behavior — representative pattern every migrated component follows:
|
||||
|
||||
```tsx
|
||||
// frontend/src/components/__tests__/MetricCard.test.tsx
|
||||
import { describe, it, expect } from "vitest";
|
||||
import { render, screen } from "@testing-library/react";
|
||||
import { MetricCard } from "../MetricCard";
|
||||
|
||||
describe("MetricCard", () => {
|
||||
it("renders the label and value", () => {
|
||||
render(<MetricCard label="Movies" value="1,234" subtext="across 3 libraries" />);
|
||||
expect(screen.getByText("Movies")).toBeInTheDocument();
|
||||
expect(screen.getByText("1,234")).toBeInTheDocument();
|
||||
expect(screen.getByText(/across 3 libraries/)).toBeInTheDocument();
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
Status-Badge mapping is a natural component-test target (e.g. assert a healthy
|
||||
target renders `variant="success"`), satisfying the spec's "migrated components
|
||||
have component tests" scenario.
|
||||
|
||||
## 7. Slice contracts (~8 slices; full table in exploration §9)
|
||||
|
||||
Each slice is independently reviewable and leaves `npm run build` + `npm run lint`
|
||||
green. One-paragraph contracts follow; the authoritative file list is exploration §9.
|
||||
|
||||
1. **Foundation.** Add the §5 shadcn primitives (`tabs table dialog input label
|
||||
checkbox switch progress separator avatar textarea dropdown-menu scroll-area`),
|
||||
install `@tanstack/react-table`, remove `recharts` + `d3` from `package.json`,
|
||||
delete `frontend/src/theme.ts` (and its callers), and introduce the §6 Vitest
|
||||
harness + a trivial passing test. Add the `success` Badge variant + `chart-*`
|
||||
role comments (§2). **Exit:** no `theme`/`getAppTheme` imports remain; build +
|
||||
lint + `vitest run` green; no behavior change yet.
|
||||
|
||||
2. **Shared components.** Migrate the reusable building blocks to lock the shared
|
||||
language before pages: `SectionCard`, `SelectionRailCard`, `TabbedCard`,
|
||||
`MetricCard`, `DiskSpaceCard`, `HoverEditButton`, `DialogFooter`,
|
||||
`ConfirmDialog`, `LibraryOverview`, `NowPlaying`/`SessionActivityPanel`. Each
|
||||
uses `Card`/`Badge`/`Button`/`Table`/`Tabs`/`Dialog` per §1. **Exit:** all
|
||||
shared components MUI-free; one component test per migrated block; downstream
|
||||
pages still compile against the same exported APIs.
|
||||
|
||||
3. **Backups cluster + nav.** Migrate `BackupAlertsTable`, `BackupJobsTable`,
|
||||
`BackupRunsTable`, `BackupsPage`, `BackupDashboardWidget` (all `Table` family
|
||||
- `Badge` status cues), and apply the §4 `navItems` + route edits to surface
|
||||
`/backups` as a top-level item (verify `DatabaseBackup`/fallback icon).
|
||||
**Exit:** `/backups` reachable from the sidebar; `/applications` redirects to
|
||||
`/media`; build + lint green.
|
||||
|
||||
4. **Dashboard + Media/Applications surface.** Migrate `Dashboard.tsx` (20 MUI
|
||||
components → `Card`/`Grid`→CSS-grid/`Dialog`/`Select`/`Switch`/`TextField`→`Input`)
|
||||
and `Applications.tsx` (9 → `Card`/grid/`Tabs`). **Exit:** both pages MUI-free
|
||||
and visually consistent; build + lint green.
|
||||
|
||||
5. **Settings + Actions.** Migrate `Settings.tsx` (18) and `Actions.tsx` (19) —
|
||||
the form-heavy pair (`TextField`→`Input`, `Select`, `Switch`, `Checkbox`,
|
||||
`Tabs`, `Dialog`). Keep uncontrolled/`useState` form parity (no form library).
|
||||
**Exit:** both pages MUI-free; forms behave as before; build + lint green.
|
||||
|
||||
6. **Users (largest).** Migrate `UsersPage.impl.tsx` (25 MUI components + 9 icons
|
||||
- `Drawer`→`Sheet` + `Table` + rich-text compose). **High sub-split likelihood**
|
||||
(§8): likely split into (a) directory table + selection + drawer, (b) compose
|
||||
dialog + formatting actions + attachments, to stay ≤400 lines. Apply the §5
|
||||
icon map (verify the 9 names at the pin). **Exit:** page MUI-free; drawer,
|
||||
selection-across-pages, and compose/send behavior preserved; build + lint green.
|
||||
|
||||
7. **DataGrid → TanStack Table (highest risk, last).** Build the §3 `DataTable`
|
||||
wrapper on shadcn `Table`, then rebuild `Media.tsx` and `FileBrowser.impl.tsx`
|
||||
against it. Preserve pagination (Media, server-driven) / row selection / row
|
||||
click / column visibility exactly (locked scenario columns). No sorting, no
|
||||
resizing. **Exit:** both grids behaviorally at parity; `@mui/x-data-grid` no
|
||||
longer imported; build + lint green.
|
||||
|
||||
8. **Cleanup + docs.** Remove `@mui/*` + `@emotion/*` from `package.json`, run a
|
||||
final `tsc -b` + `eslint` + `vitest run` + existing `node --test`, and update
|
||||
`docs/REQUIREMENTS.md` (single design system, thin-dashboard observability,
|
||||
TanStack tables, `/media` + `/applications` redirect, Backups nav, removed
|
||||
deps). **Exit:** recursive search of `frontend/src` for `@mui/*`/`@emotion/*`
|
||||
returns zero; requirements doc updated; all gates green.
|
||||
|
||||
## 8. Review / judgment risks
|
||||
|
||||
1. **DataGrid slice sequenced last (high).** Slice 7 carries the single largest
|
||||
behavior-parity surface (Media pagination is **server-driven** via
|
||||
`useMediaQuery` limit/offset, and selection must survive paging via a stable
|
||||
`getRowId`). It is deliberately last so `Table`, tokens, and Badge cues are
|
||||
already settled; but manual smoke of Media pagination + row-click navigation
|
||||
and FileBrowser row-click preview is mandatory at slice exit. Mitigation:
|
||||
component-test the `DataTable` wrapper (selection toggle, column visibility
|
||||
toggle, row-click callback) in slice 7 before re-wiring the pages.
|
||||
|
||||
2. **UsersPage sub-split likelihood (high).** `UsersPage.impl.tsx` is the largest
|
||||
consumer (25 components + 9 icons + `Drawer` + rich-text compose). Expect to
|
||||
split slice 6 into two PRs (table/drawer vs. compose). Judgment call at apply
|
||||
time: split before exceeding 400 lines rather than after.
|
||||
|
||||
3. **Cross-slice drift mitigation (medium).** 22 files over ~8 slices risks
|
||||
inconsistent layout primitives. Mitigated by (a) shared-components-first
|
||||
(slice 2 before any page), (b) the §1 anti-drift Tailwind patterns, and (c)
|
||||
the single `chart-*` color source of truth. Reviewers enforce §1 patterns as
|
||||
the lint-supplement gate.
|
||||
|
||||
4. **lucide-react version risk (low–medium).** `^1.14.0` is an unusual major.
|
||||
The 10 mapped icons (plus `DatabaseBackup` for Backups) must be verified at
|
||||
the pin before the consuming slices (3 and 6). The already-migrated
|
||||
`ObservabilityPage` (12 icons) proves common names resolve; verification is a
|
||||
slice-1 foundation task with a fallback list.
|
||||
|
||||
5. **Test-coverage gaps (medium).** Today there is no component harness; legacy
|
||||
`node --test` suites cover only pure-JS transforms. The new Vitest harness
|
||||
mitigates this, but coverage is only as good as what each slice writes — make
|
||||
"at least one behavioral component test per migrated component" a hard slice
|
||||
gate (spec scenario), especially for the status-Badge mapping and the
|
||||
`DataTable` features.
|
||||
@@ -0,0 +1,221 @@
|
||||
# Exploration — web-ui-rework
|
||||
|
||||
> Phase: **explore**. Evidence-grounded mapping of the rework surface. No code changes.
|
||||
> Recovered by the orchestrator after the `sdd-explore` subagent hit an MCP-bridge heap OOM;
|
||||
> all figures below were re-derived directly from source with multiline-aware parsing and verified with `grep`.
|
||||
|
||||
## 1. Scope and non-goals
|
||||
|
||||
### In scope
|
||||
|
||||
- Finish the **MUI v9 → shadcn/ui + Tailwind CSS + lucide-react** migration for every remaining `@mui/*` consumer in `frontend/src`.
|
||||
- Deliver a **visual/UX redesign** on top of the migrated primitives, consistent with the already-migrated style references: `frontend/src/App.tsx` (shell + sidebar) and `frontend/src/components/ObservabilityPage.tsx`.
|
||||
- Align the UI to the **new observability model**: Manage is a *thin dashboard*; charts/metrics/logs live in external, decoupled Grafana. In-app surfaces show Alertmanager alerts + Prometheus target health + Grafana deep-links only.
|
||||
- Remove orphaned charting deps (`recharts`, `d3`) and the no-op `theme.ts` shim.
|
||||
- Add the missing shadcn primitives and `@tanstack/react-table` needed for the migration.
|
||||
- Update `docs/REQUIREMENTS.md` to reflect the UX/architecture change (per `AGENTS.md`).
|
||||
|
||||
### Non-goals
|
||||
|
||||
- **No in-app charting.** Do not re-introduce recharts/d3 or build custom charts; metrics visualisation stays in Grafana.
|
||||
- **No new design system.** Use shadcn/ui + the existing Tailwind v4 `@theme` token system; do not adopt a different component library.
|
||||
- **No backend API changes** as part of this rework. The data contracts in `frontend/src/types/*` are unchanged unless a UI simplification forces one, which must then be flagged separately.
|
||||
- **No MUI retention.** `@mui/material`, `@mui/icons-material`, `@mui/x-data-grid`, `@emotion/react`, `@emotion/styled` are all removed by the final slice.
|
||||
- **No auth/routing model change.** OIDC flow (`auth.ts`, `react-oidc-context`) and `react-router-dom` structure stay as-is; only nav *items*/IA may shift.
|
||||
|
||||
## 2. Extended component inventory (verified from source)
|
||||
|
||||
Parsing note: MUI imports are multiline (`import {\n Box,\n Card,\n} from "@mui/material"`); figures below use a brace-bounded multiline parser and were cross-checked with `grep -rlE '@mui/(material|icons-material|x-data-grid)' src`.
|
||||
|
||||
### 2a. `@mui/material` — 22 files, 37 distinct components
|
||||
|
||||
| File | # | Components |
|
||||
|---|---|---|
|
||||
| `pages/UsersPage.impl.tsx` | 25 | Alert, Avatar, Box, Button, Checkbox, Chip, Dialog, DialogActions, DialogContent, DialogTitle, Divider, Drawer, IconButton, LinearProgress, Paper, Stack, Table, TableBody, TableCell, TableContainer, TableHead, TableRow, TextField, Tooltip, Typography |
|
||||
| `pages/Dashboard.tsx` | 20 | Alert, Box, Button, Card, CardContent, Chip, Dialog, DialogContent, DialogTitle, FormControl, FormControlLabel, FormHelperText, Grid, InputLabel, MenuItem, Select, Stack, Switch, TextField, Typography |
|
||||
| `pages/Actions.tsx` | 19 | Alert, Box, Button, Card, CardContent, Chip, Dialog, DialogContent, DialogTitle, Divider, FormControl, InputLabel, MenuItem, Select, Stack, Tab, Tabs, TextField, Typography |
|
||||
| `pages/Settings.tsx` | 18 | Alert, Box, Button, Card, CardContent, Checkbox, Chip, Dialog, DialogContent, DialogTitle, FormControlLabel, Grid, MenuItem, Stack, Switch, Tab, TextField, Typography |
|
||||
| `pages/FileBrowser.impl.tsx` | 15 | Alert, Box, Button, Card, CardContent, Chip, FormControl, Grid, InputLabel, MenuItem, Select, Stack, Tab, TextField, Typography |
|
||||
| `pages/Media.tsx` | 14 | Alert, Box, Button, Card, CardContent, FormControl, Grid, InputLabel, LinearProgress, MenuItem, Select, Stack, TextField, Typography |
|
||||
| `components/BackupRunsTable.tsx` | 12 | Chip, FormControl, InputLabel, MenuItem, Paper, Select, Table, TableBody, TableCell, TableContainer, TableHead, TableRow |
|
||||
| `components/SessionActivityPanel.tsx` | 10 | Button, Chip, Paper, Table, TableBody, TableCell, TableContainer, TableHead, TableRow, Typography |
|
||||
| `components/BackupAlertsTable.tsx` | 9 | Button, Chip, Paper, Table, TableBody, TableCell, TableContainer, TableHead, TableRow |
|
||||
| `pages/Applications.tsx` | 9 | Alert, Box, Card, CardContent, Chip, Grid, Stack, Tab, Typography |
|
||||
| `components/BackupJobsTable.tsx` | 8 | Chip, Paper, Table, TableBody, TableCell, TableContainer, TableHead, TableRow |
|
||||
| `components/DiskSpaceCard.tsx` | 7 | Box, Card, CardContent, Grid, LinearProgress, Stack, Typography |
|
||||
| `components/BackupDashboardWidget.tsx` | 5 | Box, Card, CardContent, Chip, Typography |
|
||||
| `components/ConfirmDialog.tsx` | 5 | Dialog, DialogContent, DialogTitle, Stack, Typography |
|
||||
| `components/LibraryOverview.tsx` | 5 | Card, CardContent, Grid, Stack, Typography |
|
||||
| `components/SectionCard.tsx` | 5 | Box, Card, CardContent, Stack, Typography |
|
||||
| `components/BackupsPage.tsx` | 4 | Box, Tab, Tabs, Typography |
|
||||
| `components/SelectionRailCard.tsx` | 4 | Box, Card, CardContent, Typography |
|
||||
| `components/TabbedCard.tsx` | 4 | Box, Card, CardContent, Tabs |
|
||||
| `components/DialogFooter.tsx` | 3 | Box, Button, DialogActions |
|
||||
| `components/MetricCard.tsx` | 3 | Card, CardContent, Typography |
|
||||
| `components/HoverEditButton.tsx` | 1 | IconButton |
|
||||
|
||||
**Component frequency (migration sizing):** Typography 16 · Box 14 · Card/CardContent 13 · Chip 11 · Stack 11 · Button 9 · Grid 7 · Alert 7 · MenuItem 6 · TextField 6 · Paper/Table*/FormControl/InputLabel/Select/Tab 5 · Dialog/DialogContent/DialogTitle 5 · Tabs 3 · LinearProgress 3 · DialogActions/IconButton/Divider/FormControlLabel/Switch/Checkbox 2 · FormHelperText/Avatar/Drawer/Tooltip 1.
|
||||
|
||||
### 2b. `@mui/x-data-grid` — 2 files (DataGrid)
|
||||
|
||||
- `pages/Media.tsx` — `DataGrid`, `GridColDef`
|
||||
- `pages/FileBrowser.impl.tsx` — `DataGrid`, `GridColDef`, `GridRowSelectionModel`
|
||||
|
||||
### 2c. `@mui/icons-material` — 2 files, 10 distinct icons (default-import-per-icon style)
|
||||
|
||||
| File | Icons → lucide-react equivalent |
|
||||
|---|---|
|
||||
| `components/HoverEditButton.tsx` | `EditOutlined` → `Pencil` |
|
||||
| `pages/UsersPage.impl.tsx` | `Close`→`X` · `AttachFile`→`Paperclip` · `FormatBold`→`Bold` · `FormatItalic`→`Italic` · `Link`→`Link` · `FormatListBulleted`→`List` · `MailOutlined`→`Mail` · `Send`→`Send` · `DeleteOutlined`→`Trash2` |
|
||||
|
||||
> **lucide caveat:** `package.json` pins `lucide-react: ^1.14.0`, an unusual major. The named icons above (`Pencil`, `X`, `Paperclip`, `Bold`, `Italic`, `Link`, `List`, `Mail`, `Send`, `Trash2`) are standard lucide exports, but the version pin must be verified to export them before the UsersPage slice.
|
||||
|
||||
### 2d. Orphaned / unused deps (verified zero imports)
|
||||
|
||||
- `recharts: ^3.8.1` — **no `from "recharts"` anywhere.** Removable.
|
||||
- `d3: ^7.9.0` — **no `from "d3"` / `from "d3-*"` anywhere.** Removable.
|
||||
- `frontend/src/theme.ts` — no-op shim (`getAppTheme` returns `{}`); safe to delete once no caller remains.
|
||||
|
||||
### 2e. Already-migrated style references (the design targets)
|
||||
|
||||
- `frontend/src/App.tsx` — shell: fixed sidebar (`w-16`/`w-60` collapse), `TopBar` (sticky, backdrop-blur, version chips), `MobileDrawer` (shadcn `Sheet`), `useDarkMode` toggles `dark` class on `<html>`.
|
||||
- `frontend/src/components/ObservabilityPage.tsx` (575 lines) — uses shadcn `Card/Badge/Alert/Button/Select/Skeleton/Collapsible` + 12 lucide icons; Grafana deep-links via kiosk URLs (`/d/node-exporter-overview/...?kiosk&var-instance=…`) and Explore.
|
||||
|
||||
## 3. MUI → shadcn/ui + Tailwind mapping table
|
||||
|
||||
| MUI | shadcn/ui + Tailwind | Primitive status |
|
||||
|---|---|---|
|
||||
| `Card` / `CardContent` | `Card` / `CardContent` (`@/components/ui/card`) | **present** |
|
||||
| `Typography` | semantic `<h1>`–`<h6>`/`<p>`/`<span>` + Tailwind `text-* font-*` | none needed |
|
||||
| `Box` | `<div>` + flex/grid utilities | none needed |
|
||||
| `Stack` | `<div className="flex flex-col gap-*">` (or `flex-row`) | none needed |
|
||||
| `Grid` | CSS grid `grid grid-cols-* gap-*` w/ responsive `md:`/`lg:` | none needed |
|
||||
| `Chip` | `Badge` (`@/components/ui/badge`) | **present** |
|
||||
| `Button` | `Button` (`@/components/ui/button`) | **present** |
|
||||
| `IconButton` | `Button variant="ghost" size="icon"` (pattern already used in shell) | **present** |
|
||||
| `Tooltip` | `Tooltip` (`@/components/ui/tooltip`) | **present** |
|
||||
| `Alert` | `Alert`/`AlertTitle`/`AlertDescription` | **present** |
|
||||
| `Select`/`MenuItem`/`FormControl`/`InputLabel` | `Select` family (`@/components/ui/select`) | **present** |
|
||||
| `Paper` | `<div className="rounded-lg border bg-card">` or `Card` | none needed |
|
||||
| `Table`/`TableHead`/`TableBody`/`TableRow`/`TableCell`/`TableContainer` | shadcn `Table` family | **add** |
|
||||
| `Tabs`/`Tab` | shadcn `Tabs` (`TabsList`/`TabsTrigger`/`TabsContent`) | **add** |
|
||||
| `Dialog`/`DialogTitle`/`DialogContent`/`DialogActions` | shadcn `Dialog` (+ `DialogFooter`, `DialogHeader`) | **add** |
|
||||
| `TextField` | `Input` (+ `Label`) | **add** |
|
||||
| `Checkbox` | `Checkbox` | **add** |
|
||||
| `Switch` | `Switch` | **add** |
|
||||
| `LinearProgress` | `Progress` | **add** |
|
||||
| `Divider` | `Separator` | **add** |
|
||||
| `Avatar` | `Avatar` | **add** |
|
||||
| `Drawer` | `Sheet` (side="right") — already used for mobile nav | **present** |
|
||||
| `FormControlLabel` / `FormHelperText` | `Label` + `<p className="text-xs text-muted-foreground">` | **add** `Label` |
|
||||
| `DataGrid` (`@mui/x-data-grid`) | TanStack Table + shadcn `Table` (see §4) | **add** `@tanstack/react-table` |
|
||||
|
||||
## 4. DataGrid decision — TanStack Table (KEY TECHNICAL RISK)
|
||||
|
||||
**Recommendation:** migrate both DataGrid usages to **`@tanstack/react-table`** (headless) styled with the shadcn `Table` primitive. Rationale: headless (no opinionated styling, fits Tailwind), first-class sorting/filtering/pagination/selection/column-visibility, actively maintained, and the project already uses `@tanstack/react-query` so the dependency family is consistent.
|
||||
|
||||
**Feature parity that MUST be preserved** (derived from source):
|
||||
|
||||
| Page | Columns (`field`) | Features in use |
|
||||
|---|---|---|
|
||||
| `pages/Media.tsx` | title, series, season, episode, type, year, runtime_min, size, bitrate, hdr, video, resolution, date_added, library, path | pagination, row selection, row click (opens file browser), column visibility management, stable row id |
|
||||
| `pages/FileBrowser.impl.tsx` | type, name, ext, size, modified | row selection, row click (selects file for ffprobe), column visibility management |
|
||||
|
||||
**Open parity questions for the proposal phase:**
|
||||
|
||||
- Does the redesign keep client-side column *resizing*, or only *visibility*? (Source scan shows visibility; resizing usage is ambiguous and must be confirmed against the live DataGrid props.)
|
||||
- Sorting/filtering: Media has external controls already (its own filter UI); decide whether TanStack sorting is added or deferred to keep slice size ≤400 lines.
|
||||
|
||||
This is the single highest-risk slice; it is sequenced **last** so the shared Table primitive and design tokens are already settled.
|
||||
|
||||
## 5. shadcn primitives gap list
|
||||
|
||||
Add via `npx shadcn@latest add <name>` (project already initialised — `components.json`, `@/components/ui`, `cn()` in `src/lib/utils.ts`):
|
||||
|
||||
```
|
||||
tabs table dialog input label checkbox switch progress separator avatar textarea dropdown-menu scroll-area
|
||||
```
|
||||
|
||||
Plus dependency: `npm i @tanstack/react-table`.
|
||||
|
||||
Already present (do not re-add): `button tooltip sheet card badge alert select skeleton collapsible`.
|
||||
|
||||
## 6. Design tokens, theming, and redesign direction
|
||||
|
||||
**Current tokens (`frontend/src/index.css`, Tailwind v4 `@theme`)** — already a complete shadcn-style system:
|
||||
|
||||
- Font: Inter (300–700 via Google Fonts).
|
||||
- Light: background `#fafafa`, foreground `#0f172a`, card `#ffffff`, primary `#4f8cff`, border `#e2e8f0`, muted-foreground `#64748b`.
|
||||
- `.dark`: background `#0f172a`, card `#1e293b`, border `#334155`, muted-foreground `#94a3b8`.
|
||||
- Radius `0.625rem`. Chart palette `chart-1..5` defined but **unused** (no charting) — keep for Grafana-link color cues, or drop.
|
||||
- Dark mode: `useDarkMode()` in `App.tsx` toggles `.dark` on `<html>`; `theme.ts` is a no-op shim.
|
||||
|
||||
**Config:** `frontend/tailwind.config.cjs` is minimal (`content` glob only) — correct for Tailwind v4 which reads tokens from `@theme` in CSS. No JS theme config to migrate.
|
||||
|
||||
**Redesign direction (consistent with shell + ObservabilityPage):**
|
||||
|
||||
- **Density:** comfortable, not cramped. Page padding `p-4 md:p-6` (matches `<main>` in `App.tsx`). Card gap `gap-4`. Section spacing via `SectionCard` replacement.
|
||||
- **Typography ramp:** headings `text-lg font-semibold` (page title, per `TopBar`), section titles `text-base font-semibold`, body `text-sm`, captions `text-xs text-muted-foreground`.
|
||||
- **Color semantics:** status uses Badge variants — `default` (info), `secondary` (neutral), `destructive` (error/firing alert), and a success variant to add for healthy/OK (currently only ObservabilityPage has health semantics). Keep primary blue `#4f8cff`.
|
||||
- **Surfaces:** prefer `Card` over ad-hoc `Paper`; one border weight (`border-border`), one radius (`rounded-lg`).
|
||||
- **Layout primitive:** replace MUI `Grid`/`Stack` with a small set of Tailwind patterns documented in the design doc so all 22 files stay consistent across slices.
|
||||
|
||||
## 7. Information architecture & navigation
|
||||
|
||||
**Current nav (`App.tsx` `navItems`):** Dashboard (`/`), Observability (`/observability`), Media (`/applications`), Files (`/files`), Users (`/users`), Actions (`/actions`), Settings (`/settings`).
|
||||
|
||||
**Routing facts:**
|
||||
|
||||
- `/monitoring` → `<Navigate to="/observability" replace />` (legacy redirect).
|
||||
- `/media` → `Applications` (alias).
|
||||
- `/backups` route **exists** (`BackupsPage`) but is **not in the sidebar** — reachable only by URL or via the Dashboard widget's deep-link.
|
||||
|
||||
**IA recommendations for the proposal:**
|
||||
|
||||
- Surface **Backups** in the nav (currently hidden) — either its own item or folded into a "Media ops" group.
|
||||
- Reconcile the **Media ↔ Applications** naming (nav says "Media", route is `/applications`, page component is `Applications`); pick one name.
|
||||
- Keep Observability as a first-class top-level item (it is the post-decoupling home for status + Grafana links).
|
||||
|
||||
## 8. Observability-decoupling implications for the redesign
|
||||
|
||||
- **Stays in-app:** Alertmanager alerts list, Prometheus target health table, monitoring-machine status, Grafana deep-link cards (kiosk iframe URLs + Explore). All already implemented in `ObservabilityPage.tsx`.
|
||||
- **Becomes / stays a Grafana deep-link:** any metric chart, time-series, log stream. The `chart-1..5` tokens and orphaned `recharts`/`d3` deps are leftovers from the removed in-app Monitoring UI — removing them codifies the decoupling.
|
||||
- **Design consequence:** no chart components need to be designed; "metric" surfaces become either a number (MetricCard) or an outbound Grafana link. The redesign should make the **external-link affordance** consistent (lucide `ExternalLink`, already used in `ObservabilityPage`).
|
||||
|
||||
## 9. Slice plan preview (Force-chained, ≤400 changed lines/PR)
|
||||
|
||||
Sequenced so each slice leaves `npm run build` + `npm run lint` green and is independently reviewable:
|
||||
|
||||
1. **Foundation** — add shadcn primitives (§5), add `@tanstack/react-table`, remove `recharts`+`d3` from `package.json`, delete `theme.ts`. Enables all later slices.
|
||||
2. **Shared components** — migrate the reusable building blocks first to prevent drift: `SectionCard`, `SelectionRailCard`, `TabbedCard`, `MetricCard`, `DiskSpaceCard`, `HoverEditButton`, `DialogFooter`, `ConfirmDialog`, `LibraryOverview`, `NowPlaying`/`SessionActivityPanel`.
|
||||
3. **Backups cluster** — `BackupAlertsTable`, `BackupJobsTable`, `BackupRunsTable`, `BackupsPage`, `BackupDashboardWidget` (+ surface `/backups` in nav).
|
||||
4. **Dashboard + Applications** — `Dashboard.tsx`, `Applications.tsx`.
|
||||
5. **Settings + Actions** — `Settings.tsx`, `Actions.tsx`.
|
||||
6. **Users** — `UsersPage.impl.tsx` (largest MUI consumer: 25 components + 9 icons + Drawer + Table + rich-text compose). May sub-split.
|
||||
7. **DataGrid → TanStack Table** — `Media.tsx` + `FileBrowser.impl.tsx` (highest risk; sequenced last).
|
||||
8. **Cleanup + docs** — remove `@mui/*` + `@emotion/*` deps, final typecheck/lint pass, update `docs/REQUIREMENTS.md`.
|
||||
|
||||
~8 slices; slices 6 and 7 are the most likely to need sub-splitting at apply time to stay under 400 lines.
|
||||
|
||||
## 10. Risks & open questions for the proposal
|
||||
|
||||
1. **DataGrid parity (high)** — TanStack Table must reproduce pagination/selection/row-click/column-visibility; resizing/sorting scope undecided (§4).
|
||||
2. **UsersPage size (high)** — single largest migration; rich-text compose UI with formatting actions, attachments, drawer, table. Needs its own careful slice (possibly split).
|
||||
3. **Cross-slice visual drift (medium)** — 22 files migrated over 8 slices; mitigated by doing shared components (slice 2) and documenting the Tailwind layout patterns in the design doc first.
|
||||
4. **lucide-react v1 pin (low–medium)** — unusual major (`^1.14.0`); verify all 10 mapped icon names exist before the UsersPage slice.
|
||||
5. **Form patterns (low)** — current forms are uncontrolled/`useState`; keep parity, no form library introduction (non-goal).
|
||||
6. **IA decisions (product)** — Backups nav placement, Media/Applications naming (§7).
|
||||
7. **Testing coverage (medium)** — see §11; no component test harness exists today.
|
||||
|
||||
## 11. Testing strategy note
|
||||
|
||||
- `frontend/package.json` has **no `test` script**. Capability today:
|
||||
- `npm run build` → `tsc -b && vite build` (typecheck + build).
|
||||
- `npm run lint` → `eslint .`.
|
||||
- `node --test` on `frontend/tests/*.mjs` (`users.test.mjs`, `userState.test.mjs`) — pure-JS transform tests, run directly, not wired into npm.
|
||||
- `openspec/config.yaml` declares **no strict-TDD flag**.
|
||||
- **Implication:** "green" for each slice = `tsc -b` clean + `eslint` clean + existing `node --test` suites pass + manual smoke of the affected page. The proposal should decide whether to introduce a minimal component test harness (e.g. Vitest + Testing Library) as slice 1 work, or proceed on static + smoke evidence only.
|
||||
|
||||
---
|
||||
|
||||
**Status:** explore complete. **Recommended next phase:** `proposal` (with a product-question round before locking, given redesign + IA ambiguity).
|
||||
@@ -0,0 +1,89 @@
|
||||
# Proposal — web-ui-rework
|
||||
|
||||
> Phase: **proposal**. Grounded in `openspec/changes/web-ui-rework/exploration.md` (verified inventory). No code changes.
|
||||
> Product/UX questions for the user are collected in **§8 — Proposal question round** and must be answered before this proposal is treated as locked.
|
||||
|
||||
## 1. Problem / motivation
|
||||
|
||||
The Manage frontend is **mid-migration**: the app shell (`App.tsx`) and the new `ObservabilityPage.tsx` already live on shadcn/ui + Tailwind + lucide-react, but **22 files still import `@mui/material`, 2 use `@mui/x-data-grid`, and 2 use `@mui/icons-material`** (10 distinct icons). The result is a split-feeling product: two design languages, two theming systems (MUI `@emotion` vs the Tailwind v4 `@theme` tokens in `index.css`), and a no-op `theme.ts` shim left behind. Orphaned charting deps (`recharts`, `d3`) linger in `package.json` even though **no in-app charting exists**.
|
||||
|
||||
This half-finished state collides with a second driver: Manage has moved to a **thin-dashboard observability model** where charts/metrics/logs live in external Grafana, and in-app surfaces show only Alertmanager alerts + Prometheus target health + Grafana deep-links. Finishing the migration is therefore not cosmetic — it is how we *codify* the decoupling (remove the charting deps, retire the last MUI surface, make the external-link affordance consistent) and land a coherent visual redesign on one design system.
|
||||
|
||||
## 2. Target outcome / product vision
|
||||
|
||||
A single, coherent Manage UI on **shadcn/ui + Tailwind v4 + lucide-react**, visually consistent with the already-migrated shell and ObservabilityPage:
|
||||
|
||||
- Every page uses the same tokens (primary `#4f8cff`, Inter, `rounded-lg`, one border weight) and the same layout primitives — `Card` over ad-hoc `Paper`, Tailwind flex/grid over MUI `Grid`/`Stack`.
|
||||
- Observability stays first-class and **thin**: status as numbers/Badges plus outbound Grafana kiosk deep-links; **no in-app charts**.
|
||||
- DataGrid surfaces (Media, FileBrowser) become TanStack Table on the shadcn `Table` primitive, preserving pagination / row-selection / row-click / column-visibility.
|
||||
- A reconciled information architecture (Backups surfaced in nav; one name for Media/Applications).
|
||||
- `@mui/*`, `@emotion/*`, `recharts`, `d3`, and the `theme.ts` shim are gone, and `docs/REQUIREMENTS.md` reflects the new UX.
|
||||
|
||||
## 3. Scope (in)
|
||||
|
||||
- Finish MUI v9 → shadcn/ui + Tailwind + lucide-react across all remaining consumers in `frontend/src` (22 material files + 2 DataGrid files + 2 icon files).
|
||||
- Add the missing shadcn primitives (`tabs table dialog input label checkbox switch progress separator avatar textarea dropdown-menu scroll-area`) and `@tanstack/react-table`.
|
||||
- Migrate both `@mui/x-data-grid` DataGrid usages to TanStack Table + shadcn `Table`.
|
||||
- Deliver a visual/UX redesign aligned to the thin-dashboard model (density, typography ramp, status Badge semantics including a success variant, consistent external-link affordance).
|
||||
- Remove orphaned `recharts`, `d3`, the `theme.ts` shim, and all `@mui/*` + `@emotion/*` deps.
|
||||
- Reconcile IA: surface Backups in nav; resolve Media vs Applications naming.
|
||||
- Update `docs/REQUIREMENTS.md`.
|
||||
|
||||
## 4. Non-goals
|
||||
|
||||
- **No in-app charting** — no recharts/d3 re-introduction, no custom charts; metrics visualisation stays in Grafana.
|
||||
- **No new design system** — shadcn/ui + the existing Tailwind v4 `@theme` tokens only.
|
||||
- **No backend API changes** — frontend `types/*` contracts stay unless a UI simplification forces one, which must be flagged separately.
|
||||
- **No MUI retention** — all `@mui/*` and `@emotion/*` removed by the final slice.
|
||||
- **No auth/routing model change** — OIDC (`auth.ts`, `react-oidc-context`) and `react-router-dom` structure unchanged; only nav *items*/IA may shift.
|
||||
- **No form-library introduction** — keep current uncontrolled/`useState` form parity.
|
||||
|
||||
## 5. Key technical risks
|
||||
|
||||
- **DataGrid → TanStack Table (high).** The two DataGrid usages (`Media.tsx`, `FileBrowser.impl.tsx`) must reproduce pagination, row-selection, row-click, and column-visibility. Whether to also carry over client-side **resizing/sorting** is an open product question (exploration §4) and is the single highest-risk slice — sequenced **last** so the shared `Table` primitive and tokens are already settled.
|
||||
- **UsersPage size (high).** `pages/UsersPage.impl.tsx` is the largest consumer (25 MUI components + 9 icons + `Drawer` + `Table` + a rich-text compose UI with formatting actions and attachments). Likely needs a sub-split to stay under the 400-line slice budget.
|
||||
- **Cross-slice visual drift (medium).** 22 files over ~8 slices; mitigated by migrating shared building blocks first (exploration §9 slice 2) and documenting the Tailwind layout patterns up front.
|
||||
- **lucide-react v1 pin (low–medium).** `^1.14.0` is an unusual major; the 10 mapped icon names must be verified to exist before the UsersPage slice.
|
||||
- **No component test harness today (medium).** See exploration §11; whether to add Vitest in slice 1 is an open question.
|
||||
|
||||
## 6. High-level slice strategy
|
||||
|
||||
Chained PRs, ≤400 changed lines each, each leaving `npm run build` + `npm run lint` green. Full table and sequencing rationale live in exploration.md **§9**; summary:
|
||||
|
||||
1. **Foundation** — shadcn primitives + `@tanstack/react-table`, remove `recharts`/`d3`, delete `theme.ts`.
|
||||
2. **Shared components** — `SectionCard`, `SelectionRailCard`, `TabbedCard`, `MetricCard`, `DiskSpaceCard`, `HoverEditButton`, `DialogFooter`, `ConfirmDialog`, `LibraryOverview`, `NowPlaying`/`SessionActivityPanel`.
|
||||
3. **Backups cluster** (+ surface `/backups` in nav).
|
||||
4. **Dashboard + Applications**.
|
||||
5. **Settings + Actions**.
|
||||
6. **Users** (largest; may sub-split).
|
||||
7. **DataGrid → TanStack Table** — Media + FileBrowser (highest risk; last).
|
||||
8. **Cleanup + docs** — remove `@mui/*` + `@emotion/*`, final typecheck/lint, update `docs/REQUIREMENTS.md`.
|
||||
|
||||
Slices 6 and 7 are the most likely to need sub-splitting to stay ≤400 lines.
|
||||
|
||||
## 7. Success criteria
|
||||
|
||||
- `npm run build` (tsc -b + vite build) and `npm run lint` green; existing `node --test` suites pass.
|
||||
- **Zero `@mui/*` or `@emotion/*` imports remain** in `frontend/src` (verified by grep); `recharts`, `d3`, and `theme.ts` removed.
|
||||
- Both DataGrid surfaces rebuilt on TanStack Table with pagination / row-selection / row-click / column-visibility parity.
|
||||
- **ObservabilityPage parity preserved** (Alertmanager alerts + Prometheus target health + Grafana deep-links); no in-app charts introduced.
|
||||
- Visual consistency with the migrated shell + ObservabilityPage; Backups surfaced in nav; Media/Applications naming resolved.
|
||||
- `docs/REQUIREMENTS.md` updated to reflect the UX/architecture change.
|
||||
|
||||
## 8. Proposal question round
|
||||
|
||||
The following product/UX questions need user answers before this proposal is treated as locked. They are intended to uncover business rules, IA intent, and scope boundaries — not delivery mechanics. *(Parent: ask these verbatim.)*
|
||||
|
||||
**Q1 — Information architecture (parent-ask):** Today the sidebar lists Dashboard, Observability, Media, Files, Users, Actions, Settings — but "Media" routes to `/applications` (component `Applications`), and a working **Backups** page (`/backups`) is hidden from the nav. Do you want (a) **Backups as its own top-level nav item**, (b) Backups grouped under a "Media ops" section, or (c) left as URL-only? And should the Media/Applications surface be named **"Media"** or **"Applications"** going forward?
|
||||
|
||||
**Q2 — Visual density (parent-ask):** The migrated shell uses **comfortable** spacing (`p-4 md:p-6`, `gap-4`). Should the redesign keep comfortable density across all 22 pages, or do some dense tables (Media, Users, Backups runs) need a **compact** mode to fit more rows on screen?
|
||||
|
||||
**Q3 — TanStack Table feature parity (parent-ask):** The current DataGrids use column **visibility**; **resizing** and **sorting** usage is ambiguous. For the rebuilt tables, do you want (a) **visibility-only** parity (smallest scope), (b) add **sorting**, or (c) add **sorting + column resizing** (closest to a full DataGrid)?
|
||||
|
||||
**Q4 — Test harness (parent-ask):** There is **no component test harness** today (only `tsc -b`, `eslint`, and `node --test` on pure-JS transforms). Should slice 1 introduce a **minimal Vitest + Testing Library** harness for the migrated components, or proceed on **static + manual smoke** evidence per slice?
|
||||
|
||||
**Q5 — Palette (parent-ask):** The current primary is **`#4f8cff`** with `chart-1..5` tokens defined but unused. Do you want to (a) **keep `#4f8cff`** and repurpose the chart tokens as Grafana-link color cues, (b) **shift the primary** to a new accent (please specify), or (c) keep the palette as-is and **drop** the unused chart tokens entirely?
|
||||
|
||||
---
|
||||
|
||||
**Recommended next phase:** `spec` — after the §8 questions are answered, refine scope/token/IA decisions and lock the slice contracts.
|
||||
@@ -0,0 +1,321 @@
|
||||
# Web UI Specification
|
||||
|
||||
> Change: `web-ui-rework` · Domain: `web-ui` · Phase: **spec**
|
||||
> Grounded in `openspec/changes/web-ui-rework/proposal.md` and `exploration.md` (verified inventory).
|
||||
> Locked product decisions encoded as requirements: IA (Backups top-level; surface named "Media" at `/media` with `/applications` → redirect), TanStack visibility-only table parity, palette (`#4f8cff` kept + `chart-1..5` repurposed), comfortable density, Vitest harness in slice 1.
|
||||
|
||||
## Purpose
|
||||
|
||||
Define WHAT must be true of the Manage web frontend after the rework: a single coherent UI on **shadcn/ui + Tailwind v4 + lucide-react**, a **thin-dashboard** observability model (no in-app charts; Grafana deep-links preserved), **TanStack Table** data grids with **visibility-only** parity, a **reconciled information architecture**, and **zero** MUI/`@emotion`/`recharts`/`d3`/`theme.ts` residue — delivered as a chain of build-and-lint-green slices. This spec is acceptance-focused and verifiable; it deliberately does not prescribe implementation.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Requirement: Single design system
|
||||
|
||||
The frontend MUST render all surfaces using only **shadcn/ui** primitives, **Tailwind v4** `@theme` tokens, and **lucide-react** icons. The application MUST NOT introduce any additional component or styling library. The application MUST NOT retain any `@mui/*` or `@emotion/*` import.
|
||||
|
||||
#### Scenario: No MUI imports remain anywhere in source
|
||||
|
||||
- GIVEN the `web-ui-rework` change is fully applied
|
||||
- WHEN a recursive search of `frontend/src` is performed for imports from `@mui/material`, `@mui/icons-material`, `@mui/x-data-grid`, `@emotion/react`, or `@emotion/styled`
|
||||
- THEN the search returns zero matches
|
||||
- AND `@mui/material`, `@mui/icons-material`, `@mui/x-data-grid`, `@emotion/react`, and `@emotion/styled` are absent from `frontend/package.json`
|
||||
|
||||
#### Scenario: No new design system adopted
|
||||
|
||||
- GIVEN the rework is applied
|
||||
- WHEN `frontend/package.json` dependencies are inspected
|
||||
- THEN no component library other than the existing shadcn/ui + Tailwind + lucide-react stack is present
|
||||
|
||||
### Requirement: Orphaned charting dependencies removed and no in-app charting
|
||||
|
||||
The frontend MUST remove the unused `recharts` and `d3` dependencies from `frontend/package.json`. The frontend MUST NOT introduce any in-app chart, time-series, or log-stream visualization component. The no-op `frontend/src/theme.ts` shim MUST be deleted. Metric surfaces MUST be expressed as numbers or outbound Grafana links only.
|
||||
|
||||
#### Scenario: Charting dependencies are gone
|
||||
|
||||
- GIVEN the final slice is applied
|
||||
- WHEN `frontend/package.json` is inspected
|
||||
- THEN neither `recharts` nor `d3` is listed as a dependency
|
||||
- AND a recursive search of `frontend/src` for imports from `recharts`, `d3`, or `d3-*` returns zero matches
|
||||
|
||||
#### Scenario: No chart component is introduced
|
||||
|
||||
- GIVEN the rework is applied
|
||||
- WHEN the migrated pages and components are inspected
|
||||
- THEN no component renders an in-app chart, sparkline, or graph canvas
|
||||
- AND observability metric surfaces render only as numeric values, status Badges, or outbound Grafana deep-link affordances
|
||||
|
||||
#### Scenario: Theme shim deleted
|
||||
|
||||
- GIVEN the foundation slice is applied
|
||||
- WHEN the `frontend/src/theme.ts` file is checked for existence
|
||||
- THEN it does not exist
|
||||
- AND no import of `theme`/`getAppTheme` remains in `frontend/src`
|
||||
|
||||
### Requirement: Palette — primary color kept and chart tokens repurposed
|
||||
|
||||
The primary color MUST remain `#4f8cff`. The existing `chart-1..5` CSS tokens in `frontend/src/index.css` MUST be **repurposed** as Grafana-link and status color cues (success / info / warning / destructive / neutral) and MUST NOT be dropped from the token system. Status Badges MUST convey meaning through these semantic color cues.
|
||||
|
||||
#### Scenario: Primary color unchanged
|
||||
|
||||
- GIVEN the rework is applied
|
||||
- WHEN `frontend/src/index.css` is inspected
|
||||
- THEN the primary color token resolves to `#4f8cff` in both light and dark themes
|
||||
|
||||
#### Scenario: Chart tokens retained and repurposed
|
||||
|
||||
- GIVEN the rework is applied
|
||||
- WHEN `frontend/src/index.css` is inspected
|
||||
- THEN the `chart-1` through `chart-5` tokens are still defined
|
||||
- AND they are documented/applied as Grafana-link and status semantic cues (success / info / warning / destructive / neutral)
|
||||
- AND status Badges draw their variant colors from these cues
|
||||
|
||||
### Requirement: Comfortable visual density across all surfaces
|
||||
|
||||
The redesign MUST use comfortable density on every surface: page padding `p-4 md:p-6` (matching the migrated shell `<main>`) and card spacing `gap-4`. The application MUST NOT introduce a compact or dense mode for any table, list, or panel.
|
||||
|
||||
#### Scenario: Comfortable density on every page
|
||||
|
||||
- GIVEN each migrated page is rendered
|
||||
- WHEN the page content container is inspected
|
||||
- THEN it uses comfortable padding consistent with the shell (`p-4 md:p-6`) and card gaps (`gap-4`)
|
||||
|
||||
#### Scenario: No compact mode
|
||||
|
||||
- GIVEN the rework is applied
|
||||
- WHEN the frontend is inspected for a density/compact toggle or compact spacing classes on tables
|
||||
- THEN no compact or dense mode exists for Media, Users, Backups runs, or any other surface
|
||||
|
||||
### Requirement: Status Badge semantics
|
||||
|
||||
The Badge component MUST provide variants that cover success (healthy/OK), info (default), neutral (secondary), warning, and destructive (error / firing alert). Status displays across Backups, Observability, and Users MUST map status values to these variants consistently.
|
||||
|
||||
#### Scenario: Healthy status uses a success cue
|
||||
|
||||
- GIVEN a monitoring target or backup run is in a healthy/OK state
|
||||
- WHEN its status is rendered
|
||||
- THEN it displays a Badge using the success color cue (mapped from the repurposed `chart-*` tokens)
|
||||
|
||||
#### Scenario: Firing alert uses a destructive cue
|
||||
|
||||
- GIVEN an Alertmanager alert is firing
|
||||
- WHEN its status is rendered
|
||||
- THEN it displays a destructive Badge
|
||||
|
||||
### Requirement: Information architecture — Backups as a top-level navigation item
|
||||
|
||||
The **Backups** surface MUST be exposed as a top-level navigation item in the sidebar, linking to the existing `/backups` route.
|
||||
|
||||
#### Scenario: Backups is reachable from the sidebar
|
||||
|
||||
- GIVEN the application shell is rendered
|
||||
- WHEN the sidebar navigation items are inspected
|
||||
- THEN a top-level "Backups" item is present
|
||||
- AND selecting it navigates to `/backups` and renders the Backups page
|
||||
|
||||
### Requirement: Information architecture — Media surface naming and route reconciliation
|
||||
|
||||
The Media/Applications surface MUST be named **"Media"** going forward, and its canonical route MUST be `/media`. The legacy `/applications` route MUST redirect (replace) to `/media`, mirroring the existing `/monitoring` → `/observability` redirect pattern. This change MUST NOT alter the OIDC authentication model or the `react-router-dom` routing structure beyond the renamed nav item, the `/media` route, and the `/applications` redirect.
|
||||
|
||||
#### Scenario: Media route is the canonical entry
|
||||
|
||||
- GIVEN the rework is applied
|
||||
- WHEN the sidebar "Media" item is selected
|
||||
- THEN the browser navigates to `/media`
|
||||
- AND the Media/Applications surface is rendered under the name "Media"
|
||||
|
||||
#### Scenario: Legacy /applications redirects to /media
|
||||
|
||||
- GIVEN the application is running
|
||||
- WHEN a user navigates directly to `/applications`
|
||||
- THEN the client router issues a replace redirect to `/media`
|
||||
- AND the Media surface is rendered (same pattern as `/monitoring` → `/observability`)
|
||||
|
||||
#### Scenario: Auth and routing model unchanged
|
||||
|
||||
- GIVEN the rework is applied
|
||||
- WHEN the authentication and routing setup is inspected
|
||||
- THEN the OIDC flow (`auth.ts`, `react-oidc-context`) and the `react-router-dom` structure are unchanged
|
||||
- AND only nav items, the `/media` route, and the `/applications` redirect differ from the prior state
|
||||
|
||||
### Requirement: TanStack Table — visibility-only parity (no sorting, no resizing)
|
||||
|
||||
The Media and FileBrowser data grids MUST be rebuilt on `@tanstack/react-table` styled with the shadcn `Table` primitive, reproducing **only** the features currently in use: **column visibility management**, **pagination** (where present), **row selection**, and **row click**. This is **visibility only** parity — the smallest DataGrid scope — and the rebuilt tables MUST NOT add column sorting, and MUST NOT add column resizing.
|
||||
|
||||
#### Scenario: No sorting added
|
||||
|
||||
- GIVEN the rebuilt Media and FileBrowser tables are rendered
|
||||
- WHEN the table headers and column definitions are inspected
|
||||
- THEN no sortable-column behavior is present
|
||||
- AND no sort affordance is rendered
|
||||
|
||||
#### Scenario: No column resizing added
|
||||
|
||||
- GIVEN the rebuilt Media and FileBrowser tables are rendered
|
||||
- WHEN the column edges are inspected
|
||||
- THEN no column-resize handles or resizing behavior are present
|
||||
|
||||
### Requirement: TanStack Table — column visibility management preserved
|
||||
|
||||
Both rebuilt tables MUST preserve the existing column-visibility management behavior, allowing the same set of columns to be shown or hidden as before the rework.
|
||||
|
||||
#### Scenario: Column visibility works on Media
|
||||
|
||||
- GIVEN the rebuilt Media table is rendered
|
||||
- WHEN a user toggles the visibility of a column
|
||||
- THEN that column is shown or hidden accordingly
|
||||
- AND the set of toggleable columns matches the pre-rework DataGrid columns (title, series, season, episode, type, year, runtime, size, bitrate, hdr, video, resolution, date_added, library, path)
|
||||
|
||||
#### Scenario: Column visibility works on FileBrowser
|
||||
|
||||
- GIVEN the rebuilt FileBrowser table is rendered
|
||||
- WHEN a user toggles the visibility of a column
|
||||
- THEN that column is shown or hidden accordingly
|
||||
- AND the set of toggleable columns matches the pre-rework columns (type, name, ext, size, modified)
|
||||
|
||||
### Requirement: TanStack Table — pagination preserved where present
|
||||
|
||||
The Media table MUST preserve its pagination behavior (page-size selection, total-count display, and page navigation) as it existed in the pre-rework DataGrid.
|
||||
|
||||
#### Scenario: Media pagination parity
|
||||
|
||||
- GIVEN the rebuilt Media table is rendered with more rows than one page
|
||||
- WHEN a user changes the page size and navigates between pages
|
||||
- THEN the visible rows, total count, and page index update consistently with the pre-rework behavior
|
||||
|
||||
### Requirement: TanStack Table — row selection preserved
|
||||
|
||||
The rebuilt tables MUST preserve their existing row-selection behavior (checkbox selection model) where it existed pre-rework.
|
||||
|
||||
#### Scenario: Row selection works on Media
|
||||
|
||||
- GIVEN the rebuilt Media table is rendered
|
||||
- WHEN a user selects and deselects rows via the selection control
|
||||
- THEN the selection state is maintained across pagination and matches the pre-rework row-selection model
|
||||
|
||||
#### Scenario: Row selection works on FileBrowser
|
||||
|
||||
- GIVEN the rebuilt FileBrowser table is rendered
|
||||
- WHEN a user selects rows via the selection control
|
||||
- THEN the selection state is maintained and matches the pre-rework model
|
||||
|
||||
### Requirement: TanStack Table — row click behavior preserved
|
||||
|
||||
The rebuilt tables MUST preserve their existing row-click behavior. On Media, clicking a row MUST open the file browser at the item's path. On FileBrowser, clicking a row MUST select that file for ffprobe preview, matching the pre-rework behavior.
|
||||
|
||||
#### Scenario: Media row click opens file browser
|
||||
|
||||
- GIVEN the rebuilt Media table is rendered
|
||||
- WHEN a user clicks a media row
|
||||
- THEN navigation occurs to the file browser targeted at the clicked item's path, as before the rework
|
||||
|
||||
#### Scenario: FileBrowser row click selects file for preview
|
||||
|
||||
- GIVEN the rebuilt FileBrowser table is rendered
|
||||
- WHEN a user clicks a file row
|
||||
- THEN that file is selected for ffprobe preview, as before the rework
|
||||
|
||||
### Requirement: Observability parity preserved (thin dashboard)
|
||||
|
||||
The Observability surface MUST continue to render Alertmanager alerts, Prometheus target health, monitoring-machine status, and Grafana deep-link cards (kiosk iframe URLs and Explore links). The rework MUST NOT introduce any in-app chart, and MUST preserve all existing Grafana deep-link affordances.
|
||||
|
||||
#### Scenario: Alerts and target health still shown
|
||||
|
||||
- GIVEN the Observability page is rendered
|
||||
- WHEN Alertmanager and Prometheus data are available
|
||||
- THEN Alertmanager alerts and Prometheus target health are displayed as before the rework
|
||||
|
||||
#### Scenario: Grafana deep-links preserved
|
||||
|
||||
- GIVEN the Observability page is rendered
|
||||
- WHEN a Grafana deep-link card is inspected
|
||||
- THEN the outbound kiosk/explore URL with instance variables is preserved
|
||||
- AND an external-link affordance is present and consistent across the surface
|
||||
|
||||
#### Scenario: No in-app chart on observability
|
||||
|
||||
- GIVEN the Observability page is rendered
|
||||
- WHEN metric surfaces are inspected
|
||||
- THEN no in-app chart is rendered; metrics are numbers, status Badges, or Grafana deep-links only
|
||||
|
||||
### Requirement: Component test harness introduced and maintained
|
||||
|
||||
Slice 1 MUST introduce a **Vitest** + **@testing-library/react** component test harness. Every component migrated by this rework MUST have real component tests asserting the migrated behavior. The existing `node --test` suites in `frontend/tests` (e.g. `users.test.mjs`, `userState.test.mjs`) MUST continue to run and pass.
|
||||
|
||||
#### Scenario: Vitest harness is present
|
||||
|
||||
- GIVEN the foundation slice is applied
|
||||
- WHEN `frontend/package.json` and config are inspected
|
||||
- THEN Vitest and `@testing-library/react` are installed
|
||||
- AND a Vitest test script is configured
|
||||
|
||||
#### Scenario: Migrated components have component tests
|
||||
|
||||
- GIVEN a slice migrates a component
|
||||
- WHEN that slice is applied
|
||||
- THEN at least one component test exercising the migrated behavior exists and passes
|
||||
|
||||
#### Scenario: Legacy node:test suites keep passing
|
||||
|
||||
- GIVEN the rework is applied
|
||||
- WHEN the `frontend/tests/*.mjs` suites are executed with `node --test`
|
||||
- THEN all pre-existing assertions still pass
|
||||
|
||||
### Requirement: Per-slice build and lint green gate
|
||||
|
||||
Every slice in the delivery chain MUST leave `npm run build` (which runs `tsc -b` then `vite build`) and `npm run lint` (eslint) green as a hard, non-negotiable gate. No slice may be merged with a failing build or lint.
|
||||
|
||||
#### Scenario: A slice leaves the build green
|
||||
|
||||
- GIVEN any slice in the chain is applied in isolation
|
||||
- WHEN `npm run build` is executed in `frontend/`
|
||||
- THEN the command exits successfully with no TypeScript or Vite errors
|
||||
|
||||
#### Scenario: A slice leaves lint green
|
||||
|
||||
- GIVEN any slice in the chain is applied in isolation
|
||||
- WHEN `npm run lint` is executed in `frontend/`
|
||||
- THEN the command exits successfully with no eslint errors
|
||||
|
||||
### Requirement: Eight-slice delivery strategy (per-slice scope and gate)
|
||||
|
||||
The rework MUST be delivered as the chained eight-slice strategy at the requirement level, with each slice independently reviewable and leaving build + lint green: (1) **Foundation** — add the missing shadcn primitives and `@tanstack/react-table`, remove `recharts`/`d3`, delete `theme.ts`, introduce the Vitest harness; (2) **Shared components** — migrate the reusable building blocks (`SectionCard`, `SelectionRailCard`, `TabbedCard`, `MetricCard`, `DiskSpaceCard`, `HoverEditButton`, `DialogFooter`, `ConfirmDialog`, `LibraryOverview`, `NowPlaying`/`SessionActivityPanel`); (3) **Backups cluster** (and surface `/backups` in nav); (4) **Dashboard + Media/Applications surface**; (5) **Settings + Actions**; (6) **Users** (largest consumer; may sub-split); (7) **DataGrid → TanStack Table** (Media + FileBrowser; highest risk, sequenced last); (8) **Cleanup + docs** — remove `@mui/*` + `@emotion/*`, final typecheck/lint pass, update `docs/REQUIREMENTS.md`.
|
||||
|
||||
#### Scenario: Foundation slice enables later slices
|
||||
|
||||
- GIVEN slice 1 is applied
|
||||
- WHEN the shared primitives, `@tanstack/react-table`, Vitest harness are present and `recharts`/`d3`/`theme.ts` are removed
|
||||
- THEN `npm run build` and `npm run lint` are green and the foundation is in place for subsequent slices
|
||||
|
||||
#### Scenario: Backups slice surfaces nav
|
||||
|
||||
- GIVEN slice 3 is applied
|
||||
- WHEN the Backups cluster is migrated
|
||||
- THEN the `/backups` route is reachable as a top-level nav item and the build + lint are green
|
||||
|
||||
#### Scenario: Final cleanup slice removes all MUI
|
||||
|
||||
- GIVEN slice 8 is applied
|
||||
- WHEN a recursive search for `@mui/*` and `@emotion/*` imports is performed in `frontend/src`
|
||||
- THEN zero matches remain
|
||||
- AND the cleanup slice leaves build + lint green
|
||||
|
||||
### Requirement: Documentation updated to reflect the new UX and architecture
|
||||
|
||||
`docs/REQUIREMENTS.md` MUST be updated to reflect the post-rework UX and architecture (single design system, thin-dashboard observability, TanStack tables, reconciled IA, removed dependencies).
|
||||
|
||||
#### Scenario: Requirements doc reflects the rework
|
||||
|
||||
- GIVEN the final slice is applied
|
||||
- WHEN `docs/REQUIREMENTS.md` is inspected
|
||||
- THEN it documents the shadcn/ui + Tailwind + lucide-react stack, the thin-dashboard observability model (no in-app charts), the `/media` route with `/applications` redirect, the Backups top-level nav item, and the removal of MUI/`@emotion`/`recharts`/`d3`
|
||||
|
||||
### Requirement: No backend API or frontend data-contract changes
|
||||
|
||||
The rework MUST NOT change any backend API contract or any type in `frontend/src/types/*`. If a UI simplification forces a contract change, that change MUST be flagged separately and approved outside this spec.
|
||||
|
||||
#### Scenario: Frontend data contracts unchanged
|
||||
|
||||
- GIVEN the rework is applied
|
||||
- WHEN `frontend/src/types/*` and the backend API surface are compared to the pre-rework state
|
||||
- THEN no backend endpoint, response shape, or shared frontend type is altered by this change (unless a separate, flagged change is approved)
|
||||
@@ -0,0 +1,261 @@
|
||||
# Tasks — web-ui-rework
|
||||
|
||||
<!-- markdownlint-disable-file MD004 -->
|
||||
|
||||
> Phase: **tasks**. Concrete, reviewable implementation tasks for the MUI v9 →
|
||||
> shadcn/ui + Tailwind v4 + lucide-react finish migration. Grounded in
|
||||
> `proposal.md`, `exploration.md`, `spec.md`, and `design.md` (all authoritative).
|
||||
> No source changes in this phase — this file is the contract `sdd-apply` executes
|
||||
> and `sdd-verify` checks.
|
||||
>
|
||||
> Locked decisions (do not re-litigate): single design system — shadcn/ui, Tailwind
|
||||
> v4, and lucide-react; Backups top-level nav item; surface renamed **Media** at
|
||||
> `/media` with `/applications` → redirect (mirrors `/monitoring` → `/observability`);
|
||||
> TanStack Table **visibility-only** parity (pagination, row selection, row click,
|
||||
> column visibility — NO sorting, NO resizing); palette keeps `#4f8cff` with
|
||||
> `chart-1..5` repurposed as status/Grafana-link cues; comfortable density everywhere;
|
||||
> Vitest + Testing Library harness added in slice 1; force-chained PRs, ≤400 changed
|
||||
> lines/slice.
|
||||
|
||||
## Review Workload Forecast
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| Estimated changed lines | ~2,800–3,900 total (sum of per-slice ranges below) |
|
||||
| 400-line budget risk | High (slices 1, 6, 7 sit at/over the boundary; 4–5 medium) |
|
||||
| Chained PRs recommended | Yes |
|
||||
| Suggested split | PR 1 → PR 2 → PR 3 → PR 4 → PR 5 → PR 6a → PR 6b → PR 7a → PR 7b → PR 8 (sub-splits on size overruns) |
|
||||
| Delivery strategy | auto-chain (force-chained per locked decision; sub-split a slice before exceeding 400) |
|
||||
| Chain strategy | stacked-to-main |
|
||||
|
||||
### Per-slice changed-line estimate
|
||||
|
||||
| Slice | Focus | Est. changed lines | ≤400? | Sub-split policy |
|
||||
|-------|-------|--------------------|-------|------------------|
|
||||
| 1 | Foundation (primitives, tanstack, Vitest, theme/badge) | ~400–580 | **At/over** — vendored shadcn primitives dominate | Likely split **1a** (shadcn primitives + deps) → **1b** (Vitest harness + `theme.ts` removal + `success` Badge + chart comments). Vendored generated primitives may also be taken as a size exception. |
|
||||
| 2 | Shared components (11 blocks) | ~280–420 | Medium | If over, split **2a** (cards/buttons/dialogs) → **2b** (tables/panels). |
|
||||
| 3 | Backups cluster + nav | ~250–400 | Likely OK | Single PR; split nav edit out if over. |
|
||||
| 4 | Dashboard + Applications | ~300–450 | Medium | If over, split **4a** (Applications, smaller) → **4b** (Dashboard). |
|
||||
| 5 | Settings + Actions | ~350–500 | Medium-High | If over, split **5a** (Actions) → **5b** (Settings). |
|
||||
| 6 | Users (largest) | ~550–850 | **No** | Force split **6a** (directory table + selection + Drawer/Sheet) → **6b** (compose dialog + formatting actions + attachments). |
|
||||
| 7 | DataGrid → TanStack (highest risk) | ~450–700 | **No** | Force split **7a** (`DataTable` wrapper + tests + FileBrowser) → **7b** (Media, server-driven pagination). |
|
||||
| 8 | Cleanup + docs | ~80–160 | OK | Single PR. |
|
||||
|
||||
**Confirmation:** Slices 3 and 8 fit ≤400 as a single PR. Slices 1, 2, 4, 5 are
|
||||
"medium" — apply the **sub-split-before-exceeding** rule (measure the diff mid-slice;
|
||||
if it crosses 400, split at the next clean boundary). Slices 6 and 7 are **confirmed
|
||||
over 400** and MUST be sub-split (6a/6b, 7a/7b) as shown. Every sub-PR keeps the
|
||||
build+lint+test gate below.
|
||||
|
||||
**Headline:** ~3,000 changed lines across **~10–12 chained PRs** (8 base slices +
|
||||
mandatory Users/DataGrid sub-splits + optional Foundation/shared/Dashboard/Settings
|
||||
sub-splits on overrun). Recommendation: **Force-chained, one PR per slice/sub-slice.**
|
||||
|
||||
### Plain-text guard lines
|
||||
|
||||
```text
|
||||
Decision needed before apply: Yes
|
||||
Chained PRs recommended: Yes
|
||||
Chain strategy: stacked-to-main
|
||||
400-line budget risk: High
|
||||
```
|
||||
|
||||
> Decision needed: yes, because (a) Slice 1 vendored-shadcn-primitives size is at/over
|
||||
> 400 (choose sub-split 1a/1b vs. size exception for generated code), and (b) Slices 6
|
||||
> and 7 are confirmed over 400 and must be sub-split — confirm the 6a/6b and 7a/7b
|
||||
> boundaries before apply. These are delivery-mechanics decisions; the product/design
|
||||
> content is fully locked in `spec.md`/`design.md`.
|
||||
|
||||
## Slice ordering rationale & dependencies
|
||||
|
||||
1. **Foundation** — must be first: all later slices consume the new primitives, `@tanstack/react-table`, the Vitest harness, the `success` Badge variant, and the cleared `theme.ts`.
|
||||
2. **Shared components** — depends on 1; must precede pages so every page reuses one building-block language (anti-drift).
|
||||
3. **Backups cluster + nav** — depends on 2 (uses `Table`/`Badge`/`Tabs`/shared cards); also lands the IA nav + route edits (`/backups` item, `/applications` → `/media`).
|
||||
4. **Dashboard + Applications** — depends on 2 and 3 (IA/route edits for Media live here-or-3; Dashboard reuses `BackupDashboardWidget` from 3, shared cards from 2).
|
||||
5. **Settings + Actions** — depends on 2 (shared dialog/cards/inputs); independent of 3/4 content.
|
||||
6. **Users** — depends on 2 (shared `Sheet`/`Table`/`Badge`/`Dialog`); largest, sub-split.
|
||||
7. **DataGrid → TanStack** — depends on 2 (`Table` primitive), 4 (`Media.tsx` page already MUI-migrated to plain primitives first so only the grid swaps), and the settled `success`/status Badge cues. Deliberately last so the Table primitive, tokens, and Badge semantics are frozen.
|
||||
8. **Cleanup + docs** — depends on all; removes the now-unused `@mui/*` + `@emotion/*` deps only after every consumer is gone.
|
||||
|
||||
Dependency DAG: `1 → 2 → {3, 4, 5, 6}` with `4 ← 3` (IA/route + backup widget);
|
||||
`{3,4,5,6} → 7` (7 needs pages' MUI shell already converted so only the grid swaps);
|
||||
`{1..7} → 8`.
|
||||
|
||||
## Universal slice exit gate (HARD — repeated for every slice)
|
||||
|
||||
A slice/sub-slice is **not done** until ALL of the following pass from `frontend/`:
|
||||
|
||||
- `npm run build` green (`tsc -b` + `vite build`).
|
||||
- `npm run lint` green (eslint).
|
||||
- `npm test` green (Vitest single-run) — applicable from slice 1 onward.
|
||||
- Existing legacy suites still pass: `node --test tests` (`users.test.mjs`, `userState.test.mjs`).
|
||||
- Manual smoke of every migrated page in that slice (no behavior regression).
|
||||
|
||||
Each slice section restates this gate as its final task.
|
||||
|
||||
---
|
||||
|
||||
## Slice 1 — Foundation (primitives, TanStack Table, Vitest, token/Badge cleanup)
|
||||
|
||||
> Enables every later slice. No page behavior change yet. Target: ~400–580 changed
|
||||
> lines — **likely sub-split 1a/1b** (primitives+deps vs. harness+cleanup) or
|
||||
> vendored-primitives size exception. Decision: confirm split before apply.
|
||||
|
||||
- [x] Add the missing shadcn primitives by running, from `frontend/`:
|
||||
`npx shadcn@latest add tabs table dialog input label checkbox switch progress separator avatar textarea dropdown-menu scroll-area`
|
||||
(do NOT re-add already-present: `button tooltip sheet card badge alert select skeleton collapsible`).
|
||||
- [x] Install the table dependency: `npm i @tanstack/react-table`.
|
||||
- [x] Remove orphaned charting deps from `frontend/package.json`: `recharts` and `d3` (verify zero `from "recharts"` / `from "d3"` / `from "d3-*"` imports in `frontend/src` before removing; none expected).
|
||||
- [x] Delete `frontend/src/theme.ts` (no-op `getAppTheme` shim) and remove every import of `theme` / `getAppTheme` in `frontend/src` (grep first, then delete).
|
||||
- [x] Add the `success` Badge variant to `frontend/src/components/ui/badge.tsx`, drawing color from the repurposed `chart-2` token per design §2.3 (`bg-chart-2/10 text-chart-2 … dark:bg-chart-2/20 …`); optionally add `warning` (`chart-3`) if a call site needs it.
|
||||
- [x] Document the `chart-1..5` role mapping as an inline comment block above the tokens in **both** the `@theme` block and `.dark` block of `frontend/src/index.css` (chart-1=info/brand, chart-2=success, chart-3=warning, chart-4=destructive, chart-5=neutral-accent). Do NOT change any token value; do NOT drop any token. Primary stays `#4f8cff`.
|
||||
- [x] Configure the Vitest harness: create `frontend/vitest.config.ts` (separate from `vite.config.ts`) using `vitest/config` `defineConfig`, `@vitejs/plugin-react`, `test.environment: "jsdom"`, `test.globals: true`, `test.setupFiles: ["./src/test/setup.ts"]`, the `@` path alias from `tsconfig.app.json`, and `test.include: ["src/**/*.{test,spec}.{ts,tsx}"]` (must NOT claim the `frontend/tests/*.mjs` node suites).
|
||||
- [x] Create `frontend/src/test/setup.ts` importing `@testing-library/jest-dom` for matcher registration.
|
||||
- [x] Install dev deps: `vitest`, `@testing-library/react`, `@testing-library/jest-dom`, `@testing-library/user-event`, `jsdom`.
|
||||
- [x] Add npm scripts to `frontend/package.json`: `"test": "vitest run"`, `"test:watch": "vitest"`, `"test:node": "node --test tests"`.
|
||||
- [x] Add one trivial passing component test under `frontend/src/**` to prove the harness (e.g. a `success` Badge renders with the `chart-2` cue).
|
||||
- [x] Verify lucide-react `^1.14.0` exports the names used by later slices (`Pencil, X, Paperclip, Bold, Italic, Link, List, Mail, Send, Trash2, DatabaseBackup, ExternalLink`); if `DatabaseBackup` is missing, fall back to `HardDrive`/`Archive` (record the chosen fallback in the slice note).
|
||||
- [x] **Exit gate:** no `theme`/`getAppTheme` imports remain; `npm run build` + `npm run lint` + `npm test` + `node --test tests` all green.
|
||||
|
||||
---
|
||||
|
||||
## Slice 2 — Shared components (lock the building-block language)
|
||||
|
||||
> Migrate the 11 reusable blocks first to prevent cross-slice drift. Each keeps its
|
||||
> exported API intact so downstream pages compile unchanged. ~280–420 lines → split
|
||||
> 2a/2b if over.
|
||||
|
||||
- [ ] Migrate `frontend/src/components/SectionCard.tsx` (Box/Card/CardContent/Stack/Typography → shadcn `Card` family + Tailwind stack; comfortable density, `gap-4`).
|
||||
- [ ] Migrate `frontend/src/components/SelectionRailCard.tsx` (Box/Card/CardContent/Typography → `Card` + Tailwind; preserve `minHeight`/scrollable body/footer props).
|
||||
- [ ] Migrate `frontend/src/components/TabbedCard.tsx` (Box/Card/CardContent/Tabs → shadcn `Tabs` (`TabsList`/`TabsTrigger`/`TabsContent`) on a `Card`).
|
||||
- [ ] Migrate `frontend/src/components/MetricCard.tsx` (Card/CardContent/Typography → shadcn `Card` + typography ramp: label `text-sm`, value `text-lg font-semibold`, subtext `text-xs text-muted-foreground`).
|
||||
- [ ] Migrate `frontend/src/components/DiskSpaceCard.tsx` (Box/Card/CardContent/Grid/LinearProgress/Stack/Typography → `Card` + CSS grid + shadcn `Progress`; preserve used/free/total/percent breakdown).
|
||||
- [ ] Migrate `frontend/src/components/HoverEditButton.tsx` (`@mui/material` IconButton + `@mui/icons-material/EditOutlined` → `Button variant="ghost" size="icon"` + lucide `Pencil`; keep the hover-in visibility transition).
|
||||
- [ ] Migrate `frontend/src/components/DialogFooter.tsx` (Box/Button/DialogActions → `Button` row (`flex flex-row items-center gap-2`); preserve cancel/confirm/secondary-action props + busy/disabled labels).
|
||||
- [ ] Migrate `frontend/src/components/ConfirmDialog.tsx` (Dialog/DialogContent/DialogTitle/Stack/Typography → shadcn `Dialog` family + `DialogFooter` from this slice).
|
||||
- [ ] Migrate `frontend/src/components/LibraryOverview.tsx` (Card/CardContent/Grid/Stack/Typography → `Card` + responsive CSS grid `grid grid-cols-1 md:grid-cols-2 gap-4`).
|
||||
- [ ] Migrate `frontend/src/components/NowPlaying.tsx` (wrapper around `SessionActivityPanel`; keep the empty-state message contract) and migrate `frontend/src/components/SessionActivityPanel.tsx` (Button/Chip/Paper/Table family/Typography → `Button`/`Badge`/bordered surface/shadcn `Table` family; status → Badge variant mapping per design §2.3, healthy=`success`).
|
||||
- [ ] Add at least one behavioral component test per migrated block (co-located under the component's `__tests__/`), e.g. `MetricCard` renders label/value/subtext; status Badge variant mapping for `SessionActivityPanel`.
|
||||
- [ ] **Exit gate:** all 11 shared components MUI-free (`grep -rlE '@mui/(material|icons-material)' src/components` returns none of these files); exported APIs unchanged so pages still compile; `npm run build` + `npm run lint` + `npm test` + `node --test tests` green.
|
||||
|
||||
---
|
||||
|
||||
## Slice 3 — Backups cluster + navigation/IA
|
||||
|
||||
> ~250–400 lines, likely a single PR. Depends on slice 2 (Table/Badge/Tabs/cards).
|
||||
> This is where Backups becomes a top-level nav item and the Media/Applications route
|
||||
> is reconciled.
|
||||
|
||||
- [ ] Migrate `frontend/src/components/BackupAlertsTable.tsx` (Chip/Paper/Table family/FormControl/InputLabel/MenuItem/Select/Button → `Badge` (status cues), bordered surface, shadcn `Table` family, shadcn `Select`; acknowledge button preserved; severity → Badge variant).
|
||||
- [ ] Migrate `frontend/src/components/BackupJobsTable.tsx` (Chip/Paper/Table family → `Badge` + shadcn `Table`; latest-run status + next-expected timing preserved).
|
||||
- [ ] Migrate `frontend/src/components/BackupRunsTable.tsx` (Chip/FormControl/InputLabel/MenuItem/Paper/Select/Table family → shadcn `Select` + `Badge` + `Table`; status filter + formatted duration/size/timestamp preserved).
|
||||
- [ ] Migrate `frontend/src/components/BackupDashboardWidget.tsx` (Box/Card/CardContent/Chip/Typography → shadcn `Card` + `Badge`; total jobs / 24h success rate / active alerts / last-failed-time preserved).
|
||||
- [ ] Migrate `frontend/src/components/BackupsPage.tsx` (Box/Tab/Tabs/Typography → shadcn `Tabs`; tabs Jobs/Runs/Alerts behavior + acknowledge mutation preserved).
|
||||
- [ ] Apply the IA nav + route edits in `frontend/src/App.tsx` per design §4: import a Backups icon (`DatabaseBackup`, or the slice-1-chosen fallback) from lucide-react; add a top-level `{ path: "/backups", label: "Backups", icon: … }` nav item (after Files, before Users); retarget the Media nav item from `/applications` to `/media`; in **both** route blocks add `<Route path="/media" element={<Applications />} />` and convert `<Route path="/applications" …>` to `<Route path="/applications" element={<Navigate to="/media" replace />} />`, mirroring the existing `/monitoring` → `/observability` redirect.
|
||||
- [ ] Add/extend component tests for the migrated Backups tables (status Badge variant mapping; alert acknowledge callback).
|
||||
- [ ] **Exit gate:** `/backups` reachable from the sidebar; `/applications` redirects to `/media`; Backups cluster MUI-free; `npm run build` + `npm run lint` + `npm test` + `node --test tests` green.
|
||||
|
||||
---
|
||||
|
||||
## Slice 4 — Dashboard + Media/Applications surface
|
||||
|
||||
> ~300–450 lines, medium. Depends on slices 2 and 3 (IA routes for Media + the
|
||||
> `BackupDashboardWidget` from slice 3). Split 4a (Applications) → 4b (Dashboard) if
|
||||
> over 400.
|
||||
|
||||
- [ ] Migrate `frontend/src/pages/Applications.tsx` (Alert/Box/Card/CardContent/Chip/Grid/Stack/Tab/Typography → `Alert`/`Card`/`Badge`/responsive CSS grid/`Tabs`; Jellyfin library stats + Media tab preserved).
|
||||
- [ ] Migrate `frontend/src/pages/Dashboard.tsx` (20 MUI components: Alert/Box/Button/Card/CardContent/Chip/Dialog/DialogContent/DialogTitle/FormControl/FormControlLabel/FormHelperText/Grid/InputLabel/MenuItem/Select/Stack/Switch/TextField/Typography → shadcn `Card`/CSS grid/`Dialog`/`Select`/`Switch`/`Input`+`Label`/`Badge`; shortcut CRUD (website/action/users), machine picker, NowPlaying + BackupDashboardWidget composition, comfortable density).
|
||||
- [ ] Preserve the Dashboard → Media navigation and shortcut deep-links under the reconciled `/media` route.
|
||||
- [ ] Add component tests for the migrated Dashboard (shortcut create/save/delete flow) and Applications (library stats render).
|
||||
- [ ] **Exit gate:** Dashboard + Applications MUI-free and visually consistent; `npm run build` + `npm run lint` + `npm test` + `node --test tests` green.
|
||||
|
||||
---
|
||||
|
||||
## Slice 5 — Settings + Actions (form-heavy pair)
|
||||
|
||||
> ~350–500 lines, medium-high. Depends on slice 2. Keep uncontrolled/`useState` form
|
||||
> parity — NO form library. Split 5a (Actions) → 5b (Settings) if over 400.
|
||||
|
||||
- [ ] Migrate `frontend/src/pages/Actions.tsx` (19 MUI components incl. Tab/Tabs/Select/MenuItem/FormControl/InputLabel/Divider/Dialog → shadcn `Tabs`/`Select`/`Separator`/`Dialog`; saved-task editor, machine selection, run history preserved).
|
||||
- [ ] Migrate `frontend/src/pages/Settings.tsx` (18 MUI components incl. Grid/Switch/Checkbox/FormControlLabel/Tab/Select/Dialog → CSS grid/`Switch`/`Checkbox`/`Label`/`Tabs`/`Select`/`Dialog`; monitoring-machine CRUD, SSH-key management, SSH test/validation feedback, danger-zone reset, tabbed UI preserved).
|
||||
- [ ] Keep all current form behaviors (controlled `useState`, SSH validation messages, ConfirmDialog integration from slice 2) — no form-library introduction.
|
||||
- [ ] Add component tests for the migrated Settings (machine save/delete confirm) and Actions (save/run task) where behavior is exercisable without live SSH.
|
||||
- [ ] **Exit gate:** Settings + Actions MUI-free; forms behave as before; `npm run build` + `npm run lint` + `npm test` + `node --test tests` green.
|
||||
|
||||
---
|
||||
|
||||
## Slice 6 — Users (largest consumer; force sub-split 6a/6b)
|
||||
|
||||
> ~550–850 lines, **confirmed over 400** — MUST sub-split. Depends on slice 2
|
||||
> (`Sheet`/`Table`/`Badge`/`Dialog`/`Avatar`). Apply the icon map from design §5
|
||||
> (verify the 9 names at the `lucide-react` pin, done in slice 1).
|
||||
|
||||
### Slice 6a — directory table, selection, drawer
|
||||
|
||||
- [ ] Migrate `frontend/src/pages/UsersPage.impl.tsx` directory surface: user table (`Table`/`TableBody`/`TableCell`/`TableContainer`/`TableHead`/`TableRow` + `Checkbox`/`Chip`/`Avatar`/`Tooltip` + `LinearProgress`) → shadcn `Table` family + `Checkbox` + `Badge` (status cues) + `Avatar` + `Tooltip` + `Progress`.
|
||||
- [ ] Replace MUI `Drawer` with shadcn `Sheet side="right"` for the user detail drawer; preserve `buildUserDrawerModel` rendering.
|
||||
- [ ] Preserve selection-across-pagination semantics (selected-user-id set survives paging/filtering) and the search/filter logic (`mergeUsersWithActivity`, row-level text matching).
|
||||
- [ ] Wire status → Badge variant mapping (healthy/activity = `success` cue) consistently with design §2.3.
|
||||
|
||||
### Slice 6b — compose dialog, formatting actions, attachments
|
||||
|
||||
- [ ] Migrate the compose dialog (`Dialog`/`DialogActions`/`DialogContent`/`DialogTitle` + `TextField`/`Divider`/`IconButton`) → shadcn `Dialog` family + `Input`/`Textarea`/`Separator` + `Button variant="ghost" size="icon"`.
|
||||
- [ ] Replace the 9 `@mui/icons-material` icons with lucide per design §5: `Close→X`, `AttachFile→Paperclip`, `FormatBold→Bold`, `FormatItalic→Italic`, `Link→Link`, `FormatListBulleted→List`, `MailOutlined→Mail`, `Send→Send`, `DeleteOutlined→Trash2`.
|
||||
- [ ] Preserve the rich-text compose behavior: subject + html body, markup insertion actions (bold/italic/link/list), file attachments (FormData), queue-status polling (`useUserMessageQueueStatus`), and send (`useSendUserMessage`).
|
||||
- [ ] Add component tests for selection toggle, drawer open, and at least one compose formatting action.
|
||||
- [ ] **Exit gate (6a+6b):** `UsersPage.impl.tsx` fully MUI/icon-MUI-free; drawer, selection-across-pages, and compose/send behavior preserved; `npm run build` + `npm run lint` + `npm test` + `node --test tests` green on each sub-PR.
|
||||
|
||||
---
|
||||
|
||||
## Slice 7 — DataGrid → TanStack Table (highest risk; force sub-split 7a/7b)
|
||||
|
||||
> ~450–700 lines, **confirmed over 400** — MUST sub-split. Deliberately last so the
|
||||
> `Table` primitive, tokens, and Badge cues are frozen. **Visibility-only** parity:
|
||||
> pagination (Media, server-driven), row selection, row click, column visibility.
|
||||
> **No sorting, no resizing.** Depends on slices 2 and 4.
|
||||
|
||||
### Slice 7a — DataTable wrapper + FileBrowser
|
||||
|
||||
- [ ] Create `frontend/src/components/ui/data-table.tsx`: a generic wrapper over `@/components/ui/table` built on `@tanstack/react-table` per design §3.1, exposing `columns`, `data`, `getRowId`, `enableRowSelection`/`rowSelection`/`onRowSelectionChange`, `onRowClick`, `columnVisibility`/`onColumnVisibilityChange`/`enableColumnVisibilityToggle`, `enablePagination`/`manualPagination`/`pagination`/`onPaginationChange`/`pageSizeOptions`/`rowCount`, and `emptyMessage`.
|
||||
- [ ] Wire `useReactTable` with `getCoreRowModel()`; `getPaginationRowModel()` only when `enablePagination && !manualPagination`; controlled `rowSelection` + `columnVisibility`; **never** `getSortedRowModel`, **never** `enableColumnResizing`/`size`.
|
||||
- [ ] Render a leading display selection column (header select-all-on-page via `Checkbox`) only when `enableRowSelection`; row `onClick → onRowClick?.(row.original)` with `cursor-pointer`, selection-cell click stops propagation; column-visibility dropdown via `DropdownMenu` + `Checkbox` when `enableColumnVisibilityToggle`.
|
||||
- [ ] Add component tests for `DataTable`: row-selection toggle, column-visibility toggle, row-click callback fires (RED→GREEN before re-wiring pages).
|
||||
- [ ] Migrate `frontend/src/pages/FileBrowser.impl.tsx` off `@mui/x-data-grid` onto `DataTable`: build `fileColumns: ColumnDef<FileEntry>[]` for the 5 columns (`type, name, ext, size, modified`); `enableRowSelection`; `onRowClick` → selects the file for ffprobe preview (preserved); `enableColumnVisibilityToggle`; **no pagination** (full listing as today). Also migrate its remaining `@mui/material` shell (Card/SectionCard/TabbedCard/Select/Input) to shadcn primitives.
|
||||
- [ ] **Exit gate (7a):** `DataTable` + FileBrowser on TanStack Table; FileBrowser row-click → ffprobe preview and column set (type/name/ext/size/modified) preserved; `@mui/x-data-grid` no longer imported by FileBrowser; `npm run build` + `npm run lint` + `npm test` + `node --test tests` green.
|
||||
|
||||
### Slice 7b — Media (server-driven pagination)
|
||||
|
||||
- [ ] Migrate `frontend/src/pages/Media.tsx` off `@mui/x-data-grid` onto `DataTable`: build `mediaColumns: ColumnDef<MediaItem>[]` for the 15 locked columns (`title, series, season, episode, type, year, runtime_min, size, bitrate, hdr, video, resolution, date_added, library, path`).
|
||||
- [ ] Render `DataTable` with `enableRowSelection`, `enablePagination` + `manualPagination` + `rowCount` (driven by `queryResult.total`), `onRowClick → navigate('/files?path=…')` (opens file browser at the item's path — preserved), and `enableColumnVisibilityToggle` (toggleable set must match the 15-column list above exactly).
|
||||
- [ ] Lift pagination + column-visibility state into the existing `usePersistentState` media state and feed `useMediaQuery({ limit, offset, … })`; use a stable path-derived `getRowId` so selection survives server-driven paging.
|
||||
- [ ] Also migrate the remaining `@mui/material` Media shell (Card/SectionCard/Grid/Select/Input/LinearProgress) to shadcn primitives + CSS grid + `Progress`; preserve index-build controls + progress (stop/force-stop).
|
||||
- [ ] Add component tests asserting the toggleable column set equals the locked 15 and that row-click triggers the navigation callback.
|
||||
- [ ] **Exit gate (7b):** Media on TanStack Table with pagination (server-driven, page-size + total-count + page-nav parity), row selection, row click → file browser, column-visibility parity; `@mui/x-data-grid` no longer imported anywhere; **no sorting, no resizing** present; `npm run build` + `npm run lint` + `npm test` + `node --test tests` green; manual smoke of Media paging + row-click and FileBrowser row-click preview.
|
||||
|
||||
---
|
||||
|
||||
## Slice 8 — Cleanup + docs (remove MUI/@emotion, final gates, docs)
|
||||
|
||||
> ~80–160 lines, single PR. Depends on all prior slices. `@mui/*` + `@emotion/*` are
|
||||
> removed only after every consumer is gone.
|
||||
|
||||
- [ ] Remove from `frontend/package.json`: `@mui/material`, `@mui/icons-material`, `@mui/x-data-grid`, `@emotion/react`, `@emotion/styled` (run `npm install`/regenerate the lockfile).
|
||||
- [ ] Grep-verify ZERO remaining imports: recursive search of `frontend/src` for `@mui/material`, `@mui/icons-material`, `@mui/x-data-grid`, `@emotion/react`, `@emotion/styled` returns no matches (hard gate for the spec "No MUI imports remain" scenario).
|
||||
- [ ] Grep-verify `recharts`, `d3`, `d3-*` have zero imports and are absent from `package.json` (carry-over from slice 1; re-confirm).
|
||||
- [ ] Confirm `frontend/src/theme.ts` does not exist and no `theme`/`getAppTheme` import remains.
|
||||
- [ ] Run final gates from `frontend/`: `npm run build` (tsc -b + vite build), `npm run lint`, `npm test`, and `node --test tests` — all green.
|
||||
- [ ] Update `docs/REQUIREMENTS.md` per `AGENTS.md`: document the single design system (shadcn/ui + Tailwind v4 + lucide-react), the thin-dashboard observability model (no in-app charts; Grafana deep-links), TanStack tables (visibility-only parity), the reconciled IA (Backups top-level nav; Media at `/media` with `/applications` redirect), the repurposed `chart-*` status cues, and the removal of `@mui/*`/`@emotion/*`/`recharts`/`d3`/`theme.ts`.
|
||||
- [ ] **Exit gate:** recursive search of `frontend/src` for `@mui/*` and `@emotion/*` returns zero; requirements doc updated; `npm run build` + `npm run lint` + `npm test` + `node --test tests` all green.
|
||||
|
||||
---
|
||||
|
||||
## Acceptance cross-check (verification commands for sdd-verify)
|
||||
|
||||
- `cd frontend && npm run build` → must be green after every slice.
|
||||
- `cd frontend && npm run lint` → must be green after every slice.
|
||||
- `cd frontend && npm test` → must be green from slice 1 onward.
|
||||
- `cd frontend && node --test tests` → legacy suites (`users.test.mjs`, `userState.test.mjs`) stay green throughout.
|
||||
- `grep -rlE '@mui/(material|icons-material|x-data-grid)|@emotion/(react|styled)' frontend/src` → must return **nothing** after slice 8.
|
||||
- `grep -rlE 'recharts|from .d3|from .d3-' frontend/src` → must return nothing (re-confirm at slice 8).
|
||||
- `test ! -e frontend/src/theme.ts` → must succeed after slice 1.
|
||||
- Inspect `frontend/src/App.tsx`: `/media` canonical route + `/applications` → `<Navigate to="/media" replace />`; a top-level Backups nav item present.
|
||||
Reference in New Issue
Block a user