# Representations Refactor Tracker

Base branch: `refactor`

---

## Status

Current slice: Slice R3 — Journey Step Resolution Extraction  
Status: IMPLEMENTED (manual validation pending)

---

## Slice List

---

### Slice R1 — Representation Entry Logic Extraction

**Goal:**
Extract representation eligibility and CTA logic from `CaseSummary`.

**Scope:**

- showRepButton logic
- date window checks (showReps / showRepsEnded)
- appeal type branching
- LPA-specific behaviour
- CTA route construction

**Rules:**

- No behaviour change
- No UI change
- Same inputs/outputs

**Completion notes (this slice):**

- Extracted representation-entry decision logic from `components/case/summary.js` into `components/case/summary/utils/representationEntry.js`.
- Preserved existing branch structure/order and duplicated consultation/general render branches.
- Preserved existing data-source usage (`detailsObj` vs `searchDetailsObj`) and existing constants/field names.
- Preserved local date-check behaviour via extracted local-equivalent helpers (`showRepsLocal`, `showRepsEndedLocal`).
- Validation evidence:
    - `npm run lint` completed (warnings only, no new errors).
    - Manual regression checks reported as passed (APP/IP/Agent/LPA), including EN/CY parity and route/query behaviour.

---

### Slice R2 — Representation Page Loader Separation

**Goal:**
Separate SSR/data-loading paths.

**Scope:**

- existing representation (state param)
- new representation (from search/case)

**Target:**

- `loadExistingRepresentation()`
- `loadNewRepresentation()`

**Completion notes (this slice):**

- Extracted representation page SSR/data-loading orchestration into `lib/representation/pageLoaders.js` with:
    - `loadRepresentationBootstrap({ ctx })`
    - `loadExistingRepresentation({ store, ctx, bootstrap })`
    - `loadNewRepresentation({ store, ctx, bootstrap })`
    - `loadRepresentationPage({ store, ctx })`
- Kept `pages/myportal/representation.js` render/UI unchanged and converted `getServerSideProps` to a thin wrapper calling `loadRepresentationPage(...)`.
- Preserved behaviour-critical details:
    - shared pre-branch bootstrap fetch timing
    - exact branch condition `query.hasOwnProperty("state")`
    - existing dispatch ordering and payload shapes
    - existing fallback/data-shape logic and typo-field usage
    - unchanged SSR returned props (`containerID`, `docsOffline`)
- Validation evidence:
    - `npm run lint` completed (warnings only, no new errors).
    - `npm run test:reps` re-run completed: **6 passed, 1 failed**.
    - Failing test: `[chromium] tests/loggedin/raiserep.spec.js:203:5` (`Raise Statement representation as an Interested Party`) with error `no statement option` / missing `Statement` option in combobox.
    - Manual regression checks confirmed passed (APP/IP/Agent/LPA), including EN/CY parity.

---

### Slice R3 — Journey Step Resolution Extraction

**Goal:**
Isolate step navigation logic.

**Scope:**

- current step determination
- next/previous step logic
- validation gating between steps

**Completion notes (this slice):**

- Added pure step-resolution helpers in `components/case/representation/utils/stepResolution.js`:
    - `resolveJourneyStageFlags({ representationSubmit, representationSubmitConfirmation })`
    - `resolveRepresentationControlKey({ isLPA, representationCapacity, repDetailsCapacity, appealType, normalizeCapacity })`
    - `resolveSubmitTransition({ representationType, showQuestionnaireSection, questionnaireCount })`
    - `getQuestionnaireNextSection(currentSection, questionnaireCount)`
    - `getQuestionnairePreviousSection(currentSection)`
- Updated `components/case/representation/index.js` to call helpers for:
    - check-stage flag resolution (`showCheckStage`)
    - control key resolution in `whichControl()`
    - questionnaire/non-questionnaire submit transition decision
    - questionnaire next-section increment calculation
- Preserved behaviour-critical constraints:
    - no JSX structure redesign
    - no route/query changes
    - no payload/Redux shape changes
    - no dispatch/API side-effect sequencing changes
    - no representation-type availability logic changes (`buildRepsArr` unchanged)
- Validation evidence:
    - `npm run lint` completed (warnings only, no new errors).
    - `npm run test:reps` re-run completed: **6 passed**.
    - Manual APP/IP/Agent/LPA and EN/CY checks: **pending for this slice**.

---

### Slice R4 — Flow Shell Decomposition

**Goal:**
Break large flow component into smaller parts.

**Target components:**

- Capacity selection
- Representation type selection
- Content entry
- Check answers
- Completion

---

### Slice R5 — Representation Elements Normalisation

**Goal:**
Clean up shared UI helpers and duplicated patterns.

**Scope:**

- input rendering
- file upload handling (structure only, not behaviour)
- shared UI logic extraction

---

### Slice R6 — Async Data / Service Layer Cleanup

**Goal:**
Reduce duplication and coupling in data fetching.

**Scope:**

- getCase → getPortalModuleDetails chains
- blob/file retrieval
- representation detail aggregation

---

### Slice R7 — Summary / Case-Type Rendering Simplification (Optional)

**Goal:**
Reduce duplication in summary-type components.

**Scope:**

- unify repeated rendering patterns
- introduce shared summary renderer where safe

---

### Slice R8 — Submission / Finalisation Boundary Isolation

**Goal:**
Isolate submission logic.

**Scope:**

- payload shaping
- submit calls
- completion handling

**Risk Level:** HIGH  
(Must only be done after earlier slices stabilised)

---

## Rules

- Only work on ONE slice at a time
- Do not combine slices
- One branch per slice
- One commit per slice
- Update tracker after completion
- Do not proceed if regression risk exists

---

## Regression Checklist (Run After Each Slice)

### Core Journey

- Navigate from case summary → Make representation
- Select capacity
- Select representation type
- Enter content
- Upload files (if applicable)
- View check answers
- Submit representation
- View confirmation page

---

### Validation

- EN/CY parity maintained
- No navigation regressions
- No state inconsistencies
- No console errors

---

### Technical

- `npm run lint` passes
- No new warnings/errors introduced

---

## Notes

- CaseSummary is a high-risk entry point
- Eligibility logic is complex and must not drift
- Submission flow is highly sensitive
- Dual-mode entry (new vs existing representation) is a key complexity

---

## Definition of Done (Per Slice)

A slice is complete when:

- behaviour is preserved
- regression checks pass
- code is cleaner and easier to understand
- change is small and safe to merge