pedwfrontend/context/representations-refactor-tracker.md

Representations Refactor Tracker

Base branch: refactor

---

Status

Current slice: Slice R6 — Async Data / Service Layer Cleanup
Status: COMPLETE

---

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

Completion notes (this slice):

• Implemented on feature branch created from refactor: rep-slice-r5-elements-normalisation.
• Added render-only shared fragments under components/case/representation/elements/:
  • RepresentationTypeSelectorBlock.js
  • RepresentationActionButtons.js
• Integrated these fragments into main representation variants only:
  • representationAppellant.js
  • representationAgent.js
  • representationInterestedPartyPerson.js
• Preserved scope constraints for Slice R5:
  • kept parent components as logic owners
  • no submission/update side-effect refactor
  • no upload service behaviour changes
  • no payload/route/query/Redux/validation business-rule changes
  • consultation variants intentionally not normalised in this slice
• Validation evidence:
  • npm run lint completed (warnings only, no new errors).
  • npm run test:reps completed: 7 passed.
  • Manual APP/IP/Agent/LPA checks: passed.
  • Manual EN/CY parity checks: passed.

---

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

Completion notes (this slice):

• Implemented on feature branch created from refactor: rep-slice-r6-data-service-cleanup.
• Added deterministic representation-specific data-resolution helpers in:
  • components/case/representation/utils/dataResolution.js
• Updated components/case/representation/index.js to use extracted helper functions for:
  • initial case details/results source resolution
  • details/results lookup by current context (state/edit/ticket/created)
  • submit-path details source resolution and details lookup
• Preserved slice boundary constraints:
  • no service/API call execution movement
  • no dispatch sequencing changes
  • no loader branch redesign
  • no blob retrieval orchestration changes
  • no payload contract/Redux/route/query/EN-CY changes
• Validation evidence:
  • npm run lint completed (warnings only, no new errors).
  • npm run test:reps completed: 7 passed.
  • Manual APP/IP/Agent/LPA checks: passed.
  • Manual EN/CY parity checks: passed.

---

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