# MUI Migration — Phase 1: AppShell — Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax.

**Goal:** Replace the admin chrome (`AdminLayout` + `Sidebar`) with a MUI `<AppShell>` in the Soft-SaaS look — a `Drawer`-based sidebar (permanent on desktop, temporary on mobile) with a white active "pill", a minimal topbar (hamburger + theme toggle), reusing the existing permission-filtered nav data and preserving all behavior (auth/2FA guards, logout scale+blur animation, ShortcutsHelp).

**Architecture:** The valuable, well-tested parts are **reused, not rewritten**: the `menuSections` nav data (icons, permissions, active-match rules) and the active/permission logic move into `navData.tsx`. `SidebarNav` renders that data with MUI `List`. `AppShell` provides the responsive `Drawer` + topbar + auth guards + the framer-motion logout wrapper, and renders `<Outlet/>`. `AdminLayout`/`Sidebar`/`layout.css` are deleted when `AppShell` lands.

**Tech Stack:** React 18.3, MUI v7 (`@mui/material`), Emotion, framer-motion (kept for logout), react-router v6, TypeScript strict.

**Spec:** `docs/superpowers/specs/2026-06-06-css-mui-migration-design.md` (§5 AppShell, §7 aesthetic, §8 Phase 1, §9 animation).

**Authoritative gates:** `npx tsc -b --noEmit` (NOT `-p tsconfig.json` — that's a vacuous solution file), `npm run build:client`, `npx vitest run`. Live visual verification (dev server) is the USER's; implementers do build/typecheck/tests only and must NOT start the dev server.

**Behavior parity checklist (must all be preserved from `AdminLayout.tsx` + `Sidebar.tsx`):**

- Auth: `loading` → spinner; `!isAuthenticated` → `<Navigate to="/login" replace/>`; 2FA-setup redirect (`user.require2FA && !user.totpEnabled && pathname !== "/"` → `/`).
- Logout: `handleLogout` sets a logout alert (`setLogoutAlert()`), closes the mobile drawer, and calls `logout()` after 400ms; the layout plays the framer-motion `{scale:1.5, opacity:0, filter:"blur(12px)"}` exit over 0.4s.
- Sidebar: permission-filtered sections/items (empty sections hidden); custom active matching (`matchPrefix`/`matchAlso`/`matchExclude`/`end`); company logo with light/dark variant + `onError` fallback to `/images/logo-{dark,light}.png`; user chip (avatar initial + name + `roleDisplay`); logout button; mobile open/close.
- `ShortcutsHelp` still rendered; `<Outlet/>` for page content.

---

## File Structure

| File                                   | Responsibility                                                                                                                                                                 | Action              |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------- |
| `src/admin/ui/navData.tsx`             | `MenuItem`/`MenuSection` types, the `menuSections` array (moved verbatim from Sidebar), pure helpers `isItemActive(item, pathname)` + `hasItemPermission(item, hasPermission)` | Create (move)       |
| `src/admin/ui/SidebarNav.tsx`          | Renders `navData` with MUI `List`: logo header, sections, white-pill active items, user+logout footer                                                                          | Create              |
| `src/admin/ui/AppShell.tsx`            | Responsive `Drawer` + topbar + auth guards + logout animation + `<Outlet/>` + `ShortcutsHelp`                                                                                  | Create              |
| `src/admin/components/Sidebar.tsx`     | (interim) import `menuSections`/helpers from `navData` instead of defining inline                                                                                              | Modify, then Delete |
| `src/admin/components/AdminLayout.tsx` | Replaced by `AppShell`                                                                                                                                                         | Delete              |
| `src/admin/AdminApp.tsx`               | Route uses `<AppShell/>` instead of `<AdminLayout/>`; remove `import "./layout.css"`                                                                                           | Modify              |
| `src/admin/layout.css`                 | Chrome styling now in MUI                                                                                                                                                      | Delete              |

Import paths from `src/admin/ui/` (same depth as `components/`): `../context/AuthContext`, `../../context/ThemeContext`, `../utils/api`, `../hooks/...`, `../theme`.

---

## Task 1: Extract nav data into `navData.tsx`

**Files:** Create `src/admin/ui/navData.tsx`; Modify `src/admin/components/Sidebar.tsx`.

- [ ] **Step 1: Create `src/admin/ui/navData.tsx`.** MOVE (cut) the following from `src/admin/components/Sidebar.tsx` **verbatim**: the `MenuItem` and `MenuSection` interfaces and the entire `menuSections` array (all 6 sections with their inline SVG icons — do not retype, move them unchanged). Then add the two pure helpers (extracted from Sidebar's inline closures), and export everything:

```tsx
import { type ReactNode } from "react";

export interface MenuItem {
  path: string;
  label: string;
  end?: boolean;
  permission?: string | string[];
  matchPrefix?: string;
  matchAlso?: string[];
  matchExclude?: string[];
  icon: ReactNode;
}

export interface MenuSection {
  label: string;
  items: MenuItem[];
}

export const menuSections: MenuSection[] = [
  /* ... the 6 sections, MOVED verbatim from Sidebar.tsx ... */
];

/** Active-state matching (mirrors the original Sidebar logic, incl. matchAlso). */
export function isItemActive(item: MenuItem, pathname: string): boolean {
  if (item.matchPrefix) {
    let active = pathname.startsWith(item.matchPrefix);
    if (active && item.matchExclude) {
      active = !item.matchExclude.some((ex) => pathname.startsWith(ex));
    }
    if (!active && item.matchAlso) {
      active = item.matchAlso.some((p) => pathname.startsWith(p));
    }
    return active;
  }
  if (item.matchAlso && item.matchAlso.some((p) => pathname.startsWith(p))) {
    return true;
  }
  if (item.end) return pathname === item.path;
  return pathname.startsWith(item.path);
}

/** Permission check: true if no permission, or any listed permission is held. */
export function hasItemPermission(
  item: MenuItem,
  hasPermission: (p: string) => boolean,
): boolean {
  if (!item.permission) return true;
  if (Array.isArray(item.permission)) {
    return item.permission.some((p) => hasPermission(p));
  }
  return hasPermission(item.permission);
}
```

> Note: the original Sidebar computed `matchAlso` separately in the `NavLink` className callback. The consolidated `isItemActive` above folds `matchAlso` in so a single function is the source of truth. Preserve every section/item exactly.

- [ ] **Step 2: Update `Sidebar.tsx` to import from `navData`** (interim — Sidebar is deleted in Task 4). Remove the inline `MenuItem`/`MenuSection`/`menuSections` definitions and the inline `isItemActive`/`hasItemPermission`; import them from `../ui/navData`. In the `NavLink` `className` callback, replace the inline active+matchAlso logic with `isItemActive(item, location.pathname)`.

- [ ] **Step 3: Verify** — `npx tsc -b --noEmit` clean; `npm run build:client` succeeds; `npx vitest run` (147 pass — no behavior change).

- [ ] **Step 4: Commit** `src/admin/ui/navData.tsx` + `src/admin/components/Sidebar.tsx` (msg: `refactor(mui): extract sidebar nav data + active/permission helpers to navData`; end with the `Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>` trailer).

---

## Task 2: `SidebarNav.tsx` (MUI drawer content)

**Files:** Create `src/admin/ui/SidebarNav.tsx`.

Renders the permission-filtered nav with MUI. Props: `{ onNavigate?: () => void; onLogout: () => void }` (`onNavigate` closes the mobile drawer; `onLogout` is owned by `AppShell`).

- [ ] **Step 1: Create the component.** Requirements (write complete MUI code):
  - `const { user, hasPermission } = useAuth();` (`../context/AuthContext`), `const { theme } = useTheme();` aliased from `../../context/ThemeContext`, `const location = useLocation();`.
  - `visibleSections` = `menuSections` mapped to filter items by `hasItemPermission(item, hasPermission)`, dropping empty sections.
  - Root: a flex column `Box`, `height: "100%"`, padding ~`1.5`.
  - **Logo header:** `Box component="img"` with `src` = `/api/admin/company-settings/logo?variant=${theme === "dark" ? "dark" : "light"}` and `onError` falling back to `/images/logo-${theme}.png`; `sx={{ maxHeight: 40, maxWidth: "100%", objectFit: "contain" }}`.
  - **Nav:** scrollable `Box` (`flex: 1, overflowY: "auto"`). For each section: a `Typography variant="caption"` subheader (uppercase, `letterSpacing: ".06em"`, `fontWeight: 700`, `color: "text.secondary"`, `fontSize: ".64rem"`, `px: 1.5`), then a `List disablePadding` of items. Each item:
    ```tsx
    <ListItemButton
      component={NavLink}
      to={item.path}
      end={item.end}
      onClick={onNavigate}
      selected={isItemActive(item, location.pathname)}
      sx={{
        borderRadius: 2,
        mb: 0.25,
        py: 0.6,
        color: "text.secondary",
        "& svg": { width: 18, height: 18 },
        "&.Mui-selected, &.Mui-selected:hover": {
          bgcolor: "background.paper",
          color: "primary.main",
          fontWeight: 700,
          boxShadow: "0 2px 8px rgba(20,20,40,0.07)",
        },
      }}
    >
      <ListItemIcon sx={{ minWidth: 32, color: "inherit" }}>
        {item.icon}
      </ListItemIcon>
      <ListItemText
        primary={item.label}
        primaryTypographyProps={{ fontSize: ".82rem", fontWeight: "inherit" }}
      />
    </ListItemButton>
    ```
    (Use MUI's `selected` prop for the active "pill" — do NOT rely on NavLink's default active class, because the active rule is custom.)
  - **Footer:** top-bordered `Box` (`borderColor: "divider"`) with a user chip (MUI `Avatar` `bgcolor: "primary.main"` showing `user?.fullName?.charAt(0) || user?.username?.charAt(0) || "U"`, plus name + `roleDisplay` `Typography` with `noWrap`), and a logout `Button` (`color="inherit"`, `fullWidth`, the existing logout SVG as `startIcon`, label "Odhlásit se", `onClick={onLogout}`).

- [ ] **Step 2: Verify** — `npx tsc -b --noEmit` clean; `npm run build:client` succeeds. (Component not yet mounted; visual check is later.)

- [ ] **Step 3: Commit** `src/admin/ui/SidebarNav.tsx` (msg: `feat(mui): SidebarNav — MUI List nav with white-pill active state`; + trailer).

---

## Task 3: `AppShell.tsx` (responsive layout + guards + animation)

**Files:** Create `src/admin/ui/AppShell.tsx`.

- [ ] **Step 1: Create the component** with this exact structure (fill the guard bodies from the parity checklist):

```tsx
import { useState, useCallback } from "react";
import { Outlet, Navigate, useLocation } from "react-router-dom";
import { motion } from "framer-motion";
import Box from "@mui/material/Box";
import Drawer from "@mui/material/Drawer";
import IconButton from "@mui/material/IconButton";
import ScopedCssBaseline from "@mui/material/ScopedCssBaseline";
import { useAuth } from "../context/AuthContext";
import { useTheme as useAppTheme } from "../../context/ThemeContext";
import { setLogoutAlert } from "../utils/api";
import SidebarNav from "./SidebarNav";
import ShortcutsHelp from "../components/ShortcutsHelp";

const DRAWER_WIDTH = 248;

export default function AppShell() {
  const { isAuthenticated, loading, user, logout } = useAuth();
  const { theme, toggleTheme } = useAppTheme();
  const [mobileOpen, setMobileOpen] = useState(false);
  const [loggingOut, setLoggingOut] = useState(false);
  const location = useLocation();

  const handleLogout = useCallback(() => {
    setLoggingOut(true);
    setMobileOpen(false);
    setLogoutAlert();
    setTimeout(() => logout(), 400);
  }, [logout]);

  if (loading) {
    return (
      <ScopedCssBaseline>
        <Box
          sx={{
            display: "flex",
            minHeight: "100vh",
            alignItems: "center",
            justifyContent: "center",
            bgcolor: "background.default",
          }}
        >
          <div className="admin-spinner" />
        </Box>
      </ScopedCssBaseline>
    );
  }
  if (!isAuthenticated) return <Navigate to="/login" replace />;
  if (user?.require2FA && !user?.totpEnabled && location.pathname !== "/") {
    return <Navigate to="/" replace />;
  }

  return (
    <ScopedCssBaseline>
      <motion.div
        initial={{ opacity: 0, scale: 0.98 }}
        animate={
          loggingOut
            ? { scale: 1.5, opacity: 0, filter: "blur(12px)" }
            : { scale: 1, opacity: 1, filter: "none" }
        }
        transition={{
          duration: loggingOut ? 0.4 : 0.25,
          ease: [0.4, 0, 0.2, 1],
        }}
        style={{ minHeight: "100vh" }}
      >
        <Box
          sx={{
            display: "flex",
            minHeight: "100vh",
            bgcolor: "background.default",
          }}
        >
          {/* Desktop permanent drawer */}
          <Drawer
            variant="permanent"
            sx={{
              display: { xs: "none", md: "block" },
              width: DRAWER_WIDTH,
              flexShrink: 0,
              "& .MuiDrawer-paper": {
                width: DRAWER_WIDTH,
                boxSizing: "border-box",
                border: 0,
                bgcolor: "background.default",
              },
            }}
          >
            <SidebarNav onLogout={handleLogout} />
          </Drawer>

          {/* Mobile temporary drawer */}
          <Drawer
            variant="temporary"
            open={mobileOpen}
            onClose={() => setMobileOpen(false)}
            ModalProps={{ keepMounted: true }}
            sx={{
              display: { xs: "block", md: "none" },
              "& .MuiDrawer-paper": {
                width: DRAWER_WIDTH,
                boxSizing: "border-box",
              },
            }}
          >
            <SidebarNav
              onNavigate={() => setMobileOpen(false)}
              onLogout={handleLogout}
            />
          </Drawer>

          {/* Main column */}
          <Box
            sx={{
              flex: 1,
              minWidth: 0,
              display: "flex",
              flexDirection: "column",
            }}
          >
            <Box
              component="header"
              sx={{
                display: "flex",
                alignItems: "center",
                gap: 1,
                px: 2,
                py: 1.5,
                minHeight: 64,
              }}
            >
              <IconButton
                onClick={() => setMobileOpen(true)}
                aria-label="Otevřít menu"
                sx={{ display: { md: "none" } }}
              >
                {/* hamburger SVG (3 lines), 24x24, stroke currentColor */}
              </IconButton>
              <Box sx={{ flex: 1 }} />
              <IconButton
                onClick={toggleTheme}
                aria-label={theme === "dark" ? "Světlý režim" : "Tmavý režim"}
                title={theme === "dark" ? "Světlý režim" : "Tmavý režim"}
              >
                {/* sun SVG when theme==='dark' is off / moon — keep the two SVGs from AdminLayout, render the one for the current theme */}
              </IconButton>
            </Box>
            <Box component="main" sx={{ flex: 1, px: { xs: 2, md: 3 }, pb: 4 }}>
              <Outlet />
            </Box>
          </Box>
        </Box>
        <ShortcutsHelp />
      </motion.div>
    </ScopedCssBaseline>
  );
}
```

Fill the two `IconButton` SVGs from the existing `AdminLayout.tsx` (the hamburger 3-line icon; the sun/moon — render the moon when `theme === "dark"`, the sun when light, matching the current toggle's meaning). Keep the `admin-spinner` class for the loading state (it's defined in a CSS file that still exists in Phase 1).

- [ ] **Step 2: Verify** — `npx tsc -b --noEmit` clean; `npm run build:client` succeeds.

- [ ] **Step 3: Commit** `src/admin/ui/AppShell.tsx` (msg: `feat(mui): AppShell — responsive Drawer + topbar, guards + logout animation`; + trailer).

---

## Task 4: Wire `AppShell`, delete legacy chrome

**Files:** Modify `src/admin/AdminApp.tsx`; Delete `src/admin/components/AdminLayout.tsx`, `src/admin/components/Sidebar.tsx`, `src/admin/layout.css`.

- [ ] **Step 1: Swap the route.** In `src/admin/AdminApp.tsx`: change the import `import AdminLayout from "./components/AdminLayout";` → `import AppShell from "./ui/AppShell";`, and the route `<Route element={<AdminLayout />}>` → `<Route element={<AppShell />}>`. Remove the line `import "./layout.css";`.

- [ ] **Step 2: Delete** `src/admin/components/AdminLayout.tsx`, `src/admin/components/Sidebar.tsx`, and `src/admin/layout.css`. Then grep the repo for any remaining import of those modules and fix/remove (there should be none beyond AdminApp).

- [ ] **Step 3: Verify (full gates)** — `npx tsc -b --noEmit` clean; `npm run build` (server+client) succeeds and the prod bundle has no broken refs; `npx vitest run` (147 pass). Confirm `layout.css` is no longer imported anywhere.

- [ ] **Step 4: Commit** (msg: `feat(mui): adopt AppShell, remove AdminLayout/Sidebar/layout.css`; + trailer).

- [ ] **Step 5: MANUAL verification (USER, dev server) — deferred:** sidebar shows permission-filtered sections; active item is the white pill; navigation works + closes the mobile drawer; theme toggle works; logout plays the scale+blur animation; logo light/dark + fallback; responsive (permanent drawer ≥ md, hamburger + temporary drawer < md); no console errors; dark + light both correct.

---

## Self-review notes (for the controller)

- **Spec coverage:** Phase 1 (spec §8) — AppShell chrome via MUI Drawer + topbar (Tasks 2–4), reusing nav data/permissions (Task 1), preserving the logout animation + guards (Task 3), deleting `layout.css` (Task 4). Login stays OUT of this (it's a sibling route — Phase 3), untouched.
- **Type consistency:** `navData` exports `MenuItem`/`MenuSection`/`menuSections`/`isItemActive`/`hasItemPermission`; `SidebarNav` and (interim) `Sidebar` both consume them. `AppShell` props to `SidebarNav`: `onLogout` (required), `onNavigate` (optional).
- **Parity risks to watch in review:** the consolidated `isItemActive` must reproduce the original `matchAlso` behavior (the original applied `matchAlso` only in the NavLink callback) — the spec reviewer must diff active states for `/attendance/admin` (matchAlso `/attendance/create`,`/attendance/location`) and `/offers` (matchExclude). The `selected` prop must not double-apply with NavLink's own active class. `ScopedCssBaseline` wraps the shell so MUI reset applies; unmigrated page content inside `<Outlet/>` still uses its own CSS.
- **Deferred:** all live visual checks (no dev server in implementer scope).