pedwfrontend/context/representations-refactor-tracker.md

Representations Refactor Tracker

Base branch: refactor

---

Status

Current slice: Slice R7 — Summary / Case-Type Rendering Simplification
Status: IMPLEMENTED (manual validation in progress)

---

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

Completion notes (this slice):

• Implemented on feature branch created from refactor: rep-slice-r7-summary-rendering-simplification.
• Added render-only summary primitives:
  • components/case/summary/components/SummaryCard.js
  • components/case/summary/components/SummaryRow.js
• Applied these primitives to a small proof subset of summary-type files only:
  • components/case/summaryTypes/pinswg_planningappeals78id.js
  • components/case/summaryTypes/pinswg_planningconditionss73s79id.js
• Preserved Slice R7 constraints:
  • no CaseSummary orchestration changes
  • no translation/date/bilingual logic moved into shared primitives
  • no linked-cases extraction (kept inline)
  • no row/card order changes intended
  • no route/query/payload/Redux/business-rule changes
• Validation evidence:
  • npm run lint completed (warnings only, no new errors).
  • npm run test:reps completed: 7 passed.
  • Manual APP/IP/Agent/LPA and EN/CY checks: in progress (Welsh IP statement option-label parity issue detected and patched in representation flow check display).

---

Post-R7 follow-up patch — Welsh IP statement label parity

Issue observed during manual check:

• In Welsh journey (Interested Party → Statement), option-label parity regressed:
  • selection step showed duplicated Welsh “No” labels
  • check/submit summary displayed raw English No

Fix applied (minimal, behaviour-preserving):

• components/case/representation/representationInterestedPartyPerson.js
  • restored canonical option values for conditional radio to options={["Yes", "No"]} so RenderCondtionalRadioList translation mapping behaves correctly.
• components/case/representation/representationCompleteSubmit.js
  • added display mapping for representationOnBehalfOf summary value:
    • Yes → t("myrepresentations:questionnaire-yes")
    • No → t("myrepresentations:questionnaire-no")
    • fallback unchanged for non-boolean/unexpected values

Validation evidence (follow-up patch):

• npm run lint completed (warnings only, no new errors).
• npm run test:reps completed: 7 passed (4.6m).
• Manual Welsh IP statement check: input labels and check-summary label now aligned via translation mapping.

---

Post-R7 follow-up patch 2 — Welsh IP conditional details submit validation

Issue observed during manual check:

• In Welsh journey (Interested Party → Statement), when selecting “Yes” and entering conditional details, submit could still block with required validation on the conditional text field.

Fix applied (minimal, behaviour-preserving):

• components/case/representation/representationElements.js
  • In RenderCondtionalRadioList, made “Yes selected” detection bilingual-safe and value-safe:
    • accepts canonical value ("Yes"), translated display value (t("myrepresentations:questionnaire-yes")), and boolean true.
  • Replaced unconditional conditional-field validator with context-aware validator:
    • requiredIfYes only enforces required when “Yes” is selected.
  • Updated conditional rendering check to use the same normalized isYesSelected guard.

Validation evidence (follow-up patch 2):

• npm run lint completed (warnings only, no new errors).
• npm run test:reps run completed with 6 passed / 1 failed.
  • Failure: [chromium] Raise representation as an Appellant timed out waiting for dd a.govuk-link--no-underline (entry-link locator timeout), not in Welsh IP conditional details path.

---

Post-R7 follow-up patch 3 — Welsh conditional required check tied to current radio value

Issue observed during manual check:

• In Welsh journey, selecting “Yes” could still leave the conditional details field blocked with required validation (Yn ofynnol) after entering text, preventing progress.

Fix applied (minimal, behaviour-preserving):

• components/case/representation/representationElements.js
  • Added explicit normalizeYesNo(...) mapping for both selected value and option values:
    • canonical/translated/boolean values normalize to "Yes" / "No".
  • Radio Field values now use normalized canonical values (preserves existing payload expectation).
  • Updated conditional requiredIfYes validator to evaluate against the current form value (allValues[id]) rather than closure-only value.
  • Required check now trims whitespace and only errors when selected value resolves to "Yes" and details are empty.

Validation evidence (follow-up patch 3):

• npm run lint completed (warnings only, no new errors).
• npm run test:reps intentionally not run per user instruction while manual Welsh verification is in progress.

---

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