jedmund-svelte/docs/admin-modernization-plan.md

# Admin Interface Modernization Plan

## Progress Overview

**Current Status:** Phase 4 In Progress 🚧 (Task 7 Phase 1 Complete)

- ✅ **Phase 0:** Runed integration (Task 0)
- ✅ **Phase 1:** Auth & data foundation (Tasks 1, 2)
- ✅ **Phase 2:** Form modernization (Tasks 3, 6)
- ✅ **Phase 3:** List utilities & primitives (Tasks 4, 5)
- 🚧 **Phase 4:** Styling harmonization (Task 7) - **IN PROGRESS**

**Recent Completions:**
- Task 7 Phase 1 - Styling & Theming Foundation (Oct 8, 2025)
  - Created 3-layer theming architecture (SCSS → CSS variables)
  - Added ~30 semantic SCSS variables for components
  - Built EmptyState and ErrorMessage reusable components
  - Refactored projects and posts pages (~60 lines removed)
- Task 5 - Dropdown & Click-Outside Primitives (Oct 8, 2025)
  - Documented existing implementation (~85% already done)
  - Cleaned up GenericMetadataPopover to use clickOutside action
- Task 4 - Shared List Filtering Utilities (Oct 8, 2025)
  - Removed ~100 lines of duplicated filter/sort code
  - Integrated into projects and posts lists

---

## Goals
- Deliver an admin surface that uses idiomatic Svelte 5 + Runes with first-class TypeScript.
- Replace client-side authentication fallbacks with server-validated sessions and consistent typing.
- Reduce duplication across resource screens (projects, posts, media) by extracting reusable list, form, and dropdown primitives.
- Improve reliability by centralizing data loading, mutation, and invalidation logic.

## Guiding Principles
- Prefer `+layout.server.ts`/`+page.server.ts` with typed `load` results over `onMount` fetches; use `satisfies` clauses for strong typing.
- Use Svelte runes (`$derived`, `$state`, `$effect`) inside components, but push cross-route state into stores or `load` data.
- Model mutations as form `actions` (with optional `enhance`) to avoid bespoke `fetch` calls and to keep optimistic UI localized.
- Encode shared behaviors (filters, dropdowns, autosave) as reusable helpers or actions so we can verify and test them once.
- Annotate shared helpers with explicit generics, exported types, and narrow `ReturnType` helpers for downstream safety.
- Leverage the [Runed](https://runed.dev) utility library where it meaningfully reduces rune boilerplate while keeping bundle size in check.

---

## Task 0 – Adopt Runed Utility Layer

**Objective:** Introduce Runed as a shared dependency for rune-focused utilities, formalize usage boundaries, and pilot it in list/data flows.

### Steps
1. Add the dependency: `pnpm add runed` (or equivalent) and ensure type declarations are available to the TypeScript compiler.
2. Create `src/lib/runed/README.md` documenting approved utilities (e.g., `asyncState`, `memo`, `taskQueue`, `clickOutside`) and guidelines for contributions.
3. Establish a thin wrapper export in `src/lib/runed/index.ts` so future refactors can swap implementations without touching call sites.
4. Update Task 2 prototype (projects list) to replace manual async state handling with `resource` and memoized filters via `$derived` helpers.
5. Evaluate bundle impact via `pnpm run build` and record findings in the doc, adjusting the allowed utility list if necessary.

**Current Adoption:** Projects index page now uses `resource` for data fetching and `onClickOutside` for dropdowns as the pilot integration.

### Implementation Notes
- Prefer wrapping Runed utilities so downstream components import from a single local module (`import { asyncState } from '$lib/runed'`).
- Pair Runed helpers with `satisfies` clauses to keep returned state strongly typed.
- Audit for tree-shaking compliance; Runed utilities are individually exported to support dead code elimination.

### Dependencies
- None; execute before Task 1 to unlock downstream usage.

---

## Task 1 – Server-Side Authentication & Session Flow

**Objective:** Move credential validation out of the browser and expose typed session data to all admin routes.

### Steps
1. Create `src/routes/admin/+layout.server.ts` that:
   - Reads an HttpOnly cookie (e.g., `admin_session`).
   - Validates credentials via shared server utility (reusable by API routes).
   - Returns `{ user }` (or `null`) while throwing `redirect(303, '/admin/login')` for unauthenticated requests.
2. Add `src/routes/admin/login/+page.server.ts` with:
   - A `load` that returns any flash errors.
   - A default `actions` export that validates the submitted password, sets the cookie via `cookies.set`, and `redirect`s into `/admin`.
3. Update `src/routes/admin/+layout.svelte` to:
   - Remove `onMount`, `$page` derived auth checks, and `goto` usage.
   - Read the session via `const { user } = await parent()` and gate rendering accordingly.
   - Handle the login route by checking `data` from parent rather than client state.
4. Replace all `localStorage.getItem('admin_auth')` references (e.g., `Admin API`, media page) with reliance on server session (see Task 2).

### Implementation Notes
- Use `LayoutServerLoad` typing: `export const load = (async (event) => { ... }) satisfies LayoutServerLoad;`.
- Define a `SessionUser` type in `src/lib/types/session.ts` to share across routes and endpoint handlers.
- For Basic auth compatibility during transition, consider reading the existing header and issuing the new cookie so legacy API calls keep working.

### Dependencies
- Requires shared credential validation utility (see Task 2 Step 1).
- Requires infra support for HttpOnly cookie (name, maxAge, secure flag).

---

## Task 2 – Unified Data Fetching & Mutation Pipeline

**Objective:** Standardize how admin pages load data and mutate resources with TypeScript-checked flows.

### Steps
1. Extract a server helper `src/lib/server/admin/authenticated-fetch.ts` that wraps `event.fetch`, injects auth headers if needed, and narrows error handling.
2. Convert project, post, media list routes to use server loads:
   - Add `+page.server.ts` returning `{ items, filters }` with `depends('admin:projects')`-style cache keys.
   - Update `+page.svelte` files to read `export let data` and derive view state from `data.items`.
   - Use `$derived` to compute filtered lists inside the component rather than re-fetching.
3. Replace manual `fetch` calls for mutations with typed form actions:
   - Define actions in `+page.server.ts` (`export const actions = { toggleStatus: async (event) => { ... } }`).
   - In Svelte, use `<form use:enhance>` or `form` wrappers to submit with `fetch`, reading `event.detail.result`.
4. After successful mutations, call `invalidate('admin:projects')` (client side) or return `invalidate` instructions within actions to refresh data.

### Implementation Notes
- Leverage `type ProjectListData = Awaited<ReturnType<typeof load>>` for consumer typing.
- Use discriminated union responses from actions (`{ type: 'success'; payload: ... } | { type: 'error'; message: string }`).
- For media pagination, accept `url.searchParams` in the server load and return `pagination` metadata for the UI.

### Dependencies
- Requires Task 1 cookie/session handling.
- Coordinate with API endpoint typing to avoid duplicating DTO definitions (reuse from `src/lib/schemas/...`).

---

## Task 3 – Project Form Modularization & Store Extraction ✅

**Status:** ✅ **COMPLETED** (Oct 7, 2025) - Commit `34a3e37`

**Objective:** Split `ProjectForm.svelte` into composable, typed stores and view modules.

### Implementation Summary
Created reusable form patterns following Svelte 5 best practices:

**New Files:**
- `src/lib/stores/project-form.svelte.ts` (114 lines) - Store factory with `$state`, `$derived`, validation
- `src/lib/admin/useDraftRecovery.svelte.ts` (62 lines) - Generic draft restoration with auto-detection
- `src/lib/admin/useFormGuards.svelte.ts` (56 lines) - Navigation guards, beforeunload, Cmd+S shortcuts
- `src/lib/components/admin/DraftPrompt.svelte` (92 lines) - Reusable draft prompt UI component

**Refactored:**
- `src/lib/components/admin/ProjectForm.svelte` - Reduced from 720 → 417 lines (42% reduction)

### Key Achievements
- All form state centralized in composable store
- Draft recovery, navigation guards fully extracted and reusable
- Type-safe with full generic support (`useDraftRecovery<TPayload>`)
- Patterns ready for PostForm, MediaForm, etc.
- Build passes, manual QA complete

### Implementation Notes
- State returned directly from factories (no `readonly` wrappers needed in Svelte 5)
- Used `$state`, `$derived`, `$effect` runes throughout
- Store factory uses `z.infer<typeof projectSchema>` for type alignment
- Exported `type ProjectFormStore = ReturnType<typeof createProjectFormStore>` for downstream usage

### Dependencies
- ✅ Task 2 (data fetching) - complete
- ✅ Task 6 (autosave store) - complete

---

## Task 4 – Shared List Filtering Utilities ✅

**Status:** ✅ **COMPLETED** (Oct 8, 2025)

**Objective:** Remove duplicated filter/sort code across projects, posts, and media.

### Implementation Summary

Created `src/lib/admin/listFilters.svelte.ts` with:
- Generic `createListFilters<T>(items, config)` factory
- Rune-backed reactivity using `$state` and `$derived`
- Type-safe filter and sort configuration
- `ListFiltersResult<T>` interface with `values`, `items`, `count`, `set()`, `setSort()`, `reset()`
- `commonSorts` collection with 8 reusable sort functions

**Integrated into:**
- ✅ Projects list (`/admin/projects`)
- ✅ Posts list (`/admin/posts`)
- ⏸️ Media list uses server-side pagination (intentionally separate)

**Removed ~100 lines of duplicated filtering logic**

### Testing Approach

Rune-based utilities cannot be unit tested outside Svelte's compiler context. Instead, extensively integration-tested through actual usage in projects and posts pages. Manual QA complete for all filtering and sorting scenarios.

**Documented in:** `docs/task-4-list-filters-completion.md`

### Implementation Notes
- Uses `export interface ListFiltersResult<T>` for return type
- Filters use exact equality comparison with special 'all' bypass
- Sorts use standard JavaScript comparator functions
- Media page intentionally uses manual filtering due to server-side pagination needs

### Dependencies
- ✅ Task 2 (server loads provide initial data) - complete

---

## Task 5 – Dropdown, Modal, and Click-Outside Primitives ✅

**Status:** ✅ **COMPLETED** (Oct 8, 2025) - Option A (Minimal Cleanup)

**Objective:** Centralize interaction patterns to reduce ad-hoc document listeners.

### Implementation Summary

Task 5 was **~85% complete** when reviewed. Core infrastructure already existed and worked well.

**What Already Existed:**
- ✅ `src/lib/actions/clickOutside.ts` - Full TypeScript implementation
- ✅ `BaseDropdown.svelte` - Svelte 5 snippets + clickOutside integration
- ✅ Dropdown primitives: `DropdownMenuContainer`, `DropdownItem`, `DropdownMenu`
- ✅ Used in ~10 components across admin interface
- ✅ Specialized dropdowns: `StatusDropdown`, `PostDropdown`, `PublishDropdown`

**Changes Made:**
- Refactored `GenericMetadataPopover.svelte` to use clickOutside action
- Removed manual event listener code
- Documented remaining manual listeners as justified exceptions

**Justified Exceptions (15 manual listeners remaining):**
- `DropdownMenu.svelte` - Complex submenu hierarchy (uses Floating UI)
- `ProjectListItem.svelte` + `PostListItem.svelte` - Global dropdown coordination
- `BaseModal.svelte` + forms - Keyboard shortcuts (Escape, Cmd+S)
- Various - Scroll/resize positioning (layout, not interaction)

**Documented in:** `docs/task-5-dropdown-primitives-completion.md`

### Implementation Notes
- Did not use Runed library (custom `clickOutside` is production-ready)
- BaseDropdown uses Svelte 5 snippets for flexible composition
- Dropdown coordination uses custom event pattern (valid approach)
- Future: Could extract keyboard handling to actions (`useEscapeKey`, `useKeyboardShortcut`)

### Dependencies
- ✅ No external dependencies required

---

## Task 6 – Autosave Store & Draft Persistence ✅

**Status:** ✅ **COMPLETED** (Earlier in Phase 2)

**Objective:** Turn autosave logic into a typed store for reuse across forms.

### Implementation Summary
Created `src/lib/admin/autoSave.svelte.ts` with:
- Generic `createAutoSaveStore<TPayload, TResponse>(options)` factory
- Reactive status using `$state<AutoSaveStatus>`
- Methods: `schedule()`, `flush()`, `destroy()`, `prime()`
- Debounced saves with abort controller support
- Online/offline detection with automatic retry
- Draft persistence fallback when offline

**Documented in:** `docs/autosave-completion-guide.md`

### Key Features
- Fully typed with TypeScript generics
- Integrates with `draftStore.ts` for localStorage fallback
- Used successfully in refactored ProjectForm
- Reusable across all admin forms

### Implementation Notes
- Returns reactive `$state` for status tracking
- Accepts `onSaved` callback with `prime()` helper for baseline updates
- Handles concurrent saves with abort controller
- Automatically transitions from 'saved' → 'idle' after delay

### Dependencies
- ✅ Task 2 (mutation endpoints) - complete

---

## Task 7 – Styling & Theming Harmonization 🚧

**Status:** 🚧 **PHASE 1 COMPLETE** (Oct 8, 2025)

**Objective:** Reduce SCSS duplication, standardize component styling, and prepare for future dark mode theming.

### Phase 1: Foundation (Complete ✅)

**Completed:**
1. ✅ Created 3-layer theming architecture:
   - Base colors (`$gray-80`, `$red-60`) in `variables.scss`
   - Semantic SCSS variables (`$input-bg`, `$error-bg`) in `variables.scss`
   - CSS custom properties (`--input-bg`, `--error-bg`) in `themes.scss`
2. ✅ Added ~30 semantic SCSS variables for:
   - Inputs & forms (bg, hover, focus, text, border)
   - State messages (error, success, warning)
   - Empty states
   - Cards & containers
   - Dropdowns & popovers
   - Modals
3. ✅ Created reusable components:
   - `EmptyState.svelte` - Replaces 10+ duplicate implementations
   - `ErrorMessage.svelte` - Replaces 4+ duplicate implementations
4. ✅ Refactored pages using new components:
   - `/admin/projects` - Removed ~30 lines of duplicate styles
   - `/admin/posts` - Removed ~30 lines of duplicate styles

**Results:**
- 60+ lines of duplicated styles removed (2 pages)
- Theme-ready architecture for future dark mode
- Guaranteed visual consistency for errors and empty states

### Phase 2: Rollout (Future)

**Remaining work:**
1. ⏳ Replace hardcoded colors with semantic variables (~40 files)
   - `rgba(239, 68, 68, 0.1)` → `$error-bg`
   - `#dc2626` → `$error-text`
2. ⏳ Fix hardcoded spacing with $unit system (~20 files)
   - `padding: 24px` → `$unit-3x`
   - `margin: 12px` → `calc($unit * 1.5)`
3. ⏳ Expand EmptyState usage to media, albums pages (~8 more usages)
4. ⏳ Expand ErrorMessage usage across forms/modals (~4 more usages)

### Implementation Notes
- Three-layer architecture enables dark mode without touching component code
- Components use SCSS variables; themes.scss maps to CSS custom properties
- Future dark mode = remap `[data-theme='dark']` block in themes.scss
- Documented in: `docs/task-7-styling-harmonization-completion.md`

### Dependencies
- ✅ No dependencies - can be done incrementally

---

## Rollout Strategy

### ✅ Phase 0: Runed Integration (Complete)
- ✅ Task 0: Runed utility layer integrated and documented
- Projects index page using `resource` for data fetching
- `onClickOutside` implemented for dropdowns

### ✅ Phase 1: Auth & Data Foundation (Complete)
- ✅ Task 1: Server-side authentication with session flow
- ✅ Task 2: Unified data fetching & mutation pipeline
- HttpOnly cookie authentication working
- Server loads with typed `satisfies` clauses

### ✅ Phase 2: Form Modernization (Complete)
- ✅ Task 6: Autosave store with draft persistence
- ✅ Task 3: Project form modularization with composable stores
- Reduced ProjectForm from 720 → 417 lines (42%)
- Reusable patterns ready for other forms

### ✅ Phase 3: List Utilities & Primitives (Complete)
- ✅ Task 4: Shared list filtering utilities (Oct 8, 2025)
- ✅ Task 5: Dropdown, modal, and click-outside primitives (Oct 8, 2025)
- Removed ~100 lines of duplicated filtering logic
- Standardized dropdown patterns across admin interface

### 🚧 Phase 4: Styling Harmonization (In Progress)
- 🚧 Task 7: Styling & theming cleanup (Phase 1 Complete)
  - ✅ Semantic SCSS variable system
  - ✅ CSS custom properties for theming
  - ✅ EmptyState and ErrorMessage components
  - ✅ Projects and posts pages refactored
  - ⏳ Remaining: Hardcoded color/spacing fixes across 40+ files

---

Each task section above can serve as a standalone issue. Ensure QA includes regression passes for projects, posts, and media operations after every phase.