# Database Detail Pages Refactor Plan (SvelteKit-centric)

This plan refactors the database detail pages to be modular, reusable, and easy to port across characters, weapons, and summons. It leans into SvelteKit features (server `load`, form `actions`, and `use:enhance`) and Svelte composition (slots, small components, and lightweight state helpers).

## Goals
- Consistent scaffold for detail pages (header, edit toolbar, sections, feedback).
- Encapsulated edit-mode state + mapping to/from API payloads.
- Clean separation between server concerns (loading, saving, validation) and client UI.
- Reusable section components that can be shared or adapted per resource.
- Smooth path to port the architecture to weapons and summons.

## Architecture Overview
- Client
  - `DetailScaffold.svelte`: Common header, edit/save/cancel controls, messages, and section slots.
  - `createEditForm.ts`: Small factory returning state + helpers for edit lifecycle.
    - Initializes `editData` from the resource model via a schema mapping.
    - Exposes `editMode`, `toggleEdit`, `reset`, `set`, `get`, and `submit` glue for forms.
  - `image.ts`: `getResourceImage(type, granblue_id)` centralizing image paths and fallbacks.
  - Section components per resource (e.g., `CharacterMetadataSection.svelte`, shared `StatsSection` when possible).
- Server
  - Shared loader helpers (e.g., `lib/server/detail/load.ts`) to fetch a resource detail and normalize to a client-facing model.
  - Form actions in `+page.server.ts` for save (`actions.save`) with validation (optionally Zod) and proper error handling.
  - Progressive enhancement via `use:enhance` so the UI stays responsive without losing SSR form semantics.
- Schema-driven mapping
  - Per resource (`characters/schema.ts`, `weapons/schema.ts`, `summons/schema.ts`) define:
    - `toEditData(model)`: API model -> UI edit state.
    - `toPayload(editData)`: UI edit state -> API payload.
    - Optional field metadata (labels, formatter hooks) for low-ceremony sections.

## File Structure (proposed)
- `src/lib/features/database/detail/`
  - `DetailScaffold.svelte` (header + actions + slots)
  - `createEditForm.ts` (state helper)
  - `image.ts` (resource image helper)
  - `api.ts` (client-side action helpers if needed)
- `src/lib/features/database/characters/`
  - `schema.ts`
  - `sections/`
    - `CharacterMetadataSection.svelte`
    - `CharacterUncapSection.svelte`
    - `CharacterTaxonomySection.svelte`
    - `CharacterStatsSection.svelte`
      - `HPStatsSubsection.svelte`
      - `ATKStatsSubsection.svelte`
- Similar folders for `weapons` and `summons` as we port.

## Form Actions and Loaders
- Loader strategy
  - Current route `+page.ts`/`+page.server.ts` fetches the detailed entity and returns a normalized `model`.
  - A shared helper `getResourceDetail(resource, id)` can live under `lib/server/detail/load.ts` to reduce duplication across resources.
- Save strategy
  - Define `export const actions = { save: async (event) => { ... } }` in `+page.server.ts`.
  - Validate incoming form data (Zod/schema), map to API payload via the schema’s `toPayload`, then persist via your backend API.
  - Return `fail(status, { fieldErrors, message })` on validation errors.
  - On success, return the updated item; `load` can pick it up or the client can reconcile locally.
- Client strategy
  - Wrap the editable fields in a `<form method="POST">` with `use:enhance`.
  - For a gradual migration from controlled inputs, keep local `editData` but mirror it into form fields (hidden or direct binds) to submit via actions.
  - Use action results to show success/error messages in `DetailScaffold`.

## Phased Tasks

### Phase 1 — Extract Scaffold + Edit Form Helper
- [ ] Create `src/lib/features/database/detail/DetailScaffold.svelte` with slots:
  - [ ] Header slot or props for resource `type`, `item`, `image`.
  - [ ] Top-right action area for Edit/Cancel/Save.
  - [ ] Message area for success/error.
  - [ ] Default slot for sections.
- [ ] Create `src/lib/features/database/detail/createEditForm.ts`:
  - [ ] Accepts initial `model` and mapping `toEditData`/`toPayload`.
  - [ ] Returns `editMode`, `editData` (store or bindable object), `toggleEdit`, `reset`, `submit`.
  - [ ] Resets `editData` when `model` changes.
- [ ] Replace inline header/controls in `characters/[id]/+page.svelte` with `DetailScaffold` while preserving behavior.

### Phase 2 — Extract Character Sections
- [ ] `CharacterMetadataSection.svelte` (Rarity, Granblue ID): view/edit with existing utilities.
- [ ] `CharacterUncapSection.svelte` (Indicator + FLB/ULB/Transcendence/Special toggles).
- [ ] `CharacterTaxonomySection.svelte` (Element, Race1/2, Gender, Proficiency1/2).
- [ ] `CharacterStatsSection.svelte` with subcomponents for HP and ATK stats.
- [ ] Wire sections to `editMode` and `editData` via props/bindings; keep look-and-feel identical.

### Phase 3 — Add Schema + Validation + Actions
- [ ] `src/lib/features/database/characters/schema.ts`:
  - [ ] `toEditData(model)` maps current character model to edit state.
  - [ ] `toPayload(editData)` maps edit state to backend payload.
  - [ ] Optional Zod schemas for validation.
- [ ] Add `+page.server.ts` `actions.save` for characters:
  - [ ] Parse form data; validate; call backend; return updated item or errors.
  - [ ] Handle cookies/credentials as needed.
- [ ] Wrap editable UI in `<form method="POST" use:enhance>` and handle optimistic UI/disable Save while pending.
- [ ] Show validation errors and success states in `DetailScaffold`.

### Phase 4 — Shared Loaders + Port to Weapons/Summons
- [ ] Add `lib/server/detail/load.ts` helpers for shared resource fetching.
- [ ] Update characters loader to use shared helper.
- [ ] Create `src/lib/features/database/weapons/schema.ts` and sections; adopt the scaffold.
- [ ] Create `src/lib/features/database/summons/schema.ts` and sections; adopt the scaffold.
- [ ] Implement `+page.server.ts` actions for weapons and summons with validation.

### Phase 5 — Polish and DX
- [ ] `image.ts` helper and replace ad-hoc image path logic.
- [ ] Extract `getDisplayName` to a single utility.
- [ ] Add unit tests for schema mapping functions (to/from payload).
- [ ] Add basic e2e smoke for actions (save success and validation failure).
- [ ] Document conventions (where to put schemas, sections, and loaders).

## Acceptance Criteria
- Character detail page renders identically, with no regressions.
- Edit mode and saving function via form actions, with graceful errors.
- Sections are split into components and trivially testable.
- Weapons and summons can be implemented by adding schema + sections and wiring the same scaffold and actions.

## Risks and Mitigations
- Form action migration conflict with controlled inputs:
  - Mitigate by mirroring `editData` into form fields and using `use:enhance` to reconcile results.
- Server validation shape mismatch:
  - Use Zod schemas that align with backend; log/trace action failures early.
- Over-abstracting sections:
  - Favor small, explicit components; introduce config-driven rendering only where repetition is high and behavior simple.

---

If we agree on this plan, start with Phase 1 (scaffold + helper) and wire it into the character page without changing behavior, then proceed section-by-section.