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

Admin Interface Modernization Plan

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 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 redirects 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

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

Steps

1. Create src/lib/components/admin/project-form/ folder with:
   • ProjectFormShell.svelte (layout, header, actions).
   • ProjectMetadataSection.svelte, ProjectBrandingSection.svelte, ProjectAssetsSection.svelte (each consuming a shared store).
   • CaseStudyEditor.svelte for the composer panel.
2. Extract a store factory createProjectFormStore(project?: Project) in src/lib/stores/project-form.ts that returns typed read/write handles (fields, validation, status, actions).
3. Move autosave and draft recovery logic into dedicated helpers:
   • useProjectAutosave(store, { projectId }) (wraps Task 6 autosave store).
   • useDraftRecovery(store, draftKey) to encapsulate prompt/timer behavior.
4. Rebuild the route components (projects/new, [id]/edit) to instantiate the store and pass it into the shell via props.

Implementation Notes

• Expose store fields as readonly derived getters (const title = $derived(store.fields.title)) to stay idiomatic with runes.
• Use z.infer<typeof projectSchema> for the store’s form type to stay aligned with validation.
• Prefer export type ProjectFormStore = ReturnType<typeof createProjectFormStore>; for downstream usage.

Dependencies

• Depends on Task 2 actions for create/update to avoid duplicating mutation logic.
• Leverages Task 6 autosave refactor.

---

Task 4 – Shared List Filtering Utilities

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

Steps

1. Introduce src/lib/admin/listFilters.ts providing createListFilters<T>(items, config) that returns:
   • Rune-backed state stores for selected filters ($state),
   • $derived filtered/sorted output,
   • Helpers setFilter, reset, and computed counts.
2. Define filter configuration types using generics (FilterConfig<T, K extends keyof T> etc.) for compile-time safety.
3. Update each admin list page to:
   • Import the helper, pass initial data from the server load, and drive the UI from the returned stores.
   • Replace manual event handlers with filters.set('status', value) style interactions.
4. Add lightweight unit tests (Vitest) for the utility to confirm sort stability and predicate correctness.

Implementation Notes

• Use export interface ListFiltersResult<T> to codify the return signature.
• Provide optional serializer hooks for search params so UI state can round-trip URL query strings.

Dependencies

• Task 2 ensures initial data arrives via server load.

---

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

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

Steps

1. Create src/lib/actions/clickOutside.ts that dispatches a custom:event when the user clicks outside an element; write in TypeScript with generics for event detail types.
2. Replace manual document.addEventListener usages in ProjectListItem, PostListItem, media dropdowns with use:clickOutside and component-local state.
3. Evolve BaseDropdown.svelte into Dropdown.svelte + DropdownTrigger.svelte + DropdownMenu.svelte components backed by a shared store (manages open state, keyboard navigation).
4. Standardize action buttons to use <button type="button"> and move repeated SVG markup into icon components (src/lib/icons).

Implementation Notes

• Ensure dropdown components accept slots typed via Snippet and expose export type DropdownContext for advanced use cases.
• Add focus-trap support with optional dependency on @floating-ui/dom if necessary, wrapped in a utility to keep types consistent.

Dependencies

• No external dependencies beyond existing component imports; can be implemented incrementally per list.

---

Task 6 – Autosave Store & Draft Persistence

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

Steps

1. Wrap createAutoSaveController into createAutoSaveStore<TPayload, TResponse>(options) that returns:
   • Writable rune store for status ($state),
   • Methods schedule, flush, cancel,
   • Optional onError and onSaved callbacks.
2. Update ProjectForm (post-refactor) to consume the store instead of managing controller lifecycles manually.
3. Extend draftStore.ts with typed helpers (loadDraft<T extends DraftPayload>()) and integrate into the new store so persistence happens automatically when schedules run.
4. Document the pattern for future forms (e.g., post editor) in docs/autosave-completion-guide.md.

Implementation Notes

• Use TypeScript overloads or generics for save to ensure the response type flows back to callers.
• Prefer rune subscriptions inside the store (const status = $state<AutoSaveStatus>('idle')).

Dependencies

• Requires Task 2 mutation path so autosave can call shared helpers.

---

Task 7 – Styling & Theming Harmonization

Objective: Reduce SCSS duplication and make layout adjustments easier.

Steps

1. Create src/lib/styles/admin.css exposing CSS variables for spacing, typography, and colors consumed by admin components.
2. Replace per-component @import '$styles/variables.scss' with @use in a single scoped stylesheet or with CSS variable access.
3. Introduce layout wrappers (e.g., AdminLayoutShell.svelte) that centralize container widths and card backgrounds, removing repeated SCSS from AdminPage, AdminNavBar, etc.
4. Audit component classes to ensure consistent BEM-ish naming and remove redundant selectors (e.g., duplicate .loading styles across pages).

Implementation Notes

• Consider PostCSS or Svelte’s <style global> for variable declarations; keep component styles scoped.
• Document variable names and usage in a short appendix within this doc once finalized.

Dependencies

• Largely independent; best executed after structural refactors to avoid churn.

---

Rollout Strategy

0. Phase 0: Execute Task 0 to integrate Runed and document approved utility usage.
1. Phase 1: Complete Task 1 & Task 2 to stabilize auth/data flows (blocks others).
2. Phase 2: Execute Task 3 and Task 6 to modernize the heaviest form.
3. Phase 3: Apply Task 4 and Task 5 across lists; retrofit dropdowns and filters.
4. Phase 4: Finish with Task 7 styling clean-up and documentation updates.

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