fix(budget): implement print styling for Budget Overview page

[steilerDev]

Summary

Implements print-specific behavior and styles for the Budget Overview page to ensure it prints correctly without app chrome and with all breakdown sections expanded.

Problem: Printing /budget/overview rendered full app chrome (sidebar, nav, hero card, Add button) and only expanded rows due to JSX-level conditional rendering of rows based on expandedKeys state.

Solution:

• New usePrintExpansion hook listens to beforeprint/afterprint events to temporarily expand all sections during print
• Print CSS hides chrome elements and resets styling for clean output
• Dark mode print reset ensures text is black on white for readability and minimal ink usage

Changes

1. client/src/hooks/usePrintExpansion.ts (new)

   • Hook that snapshots current expandedKeys on beforeprint, forces all keys to be expanded, then restores on afterprint

2. client/src/components/CostBreakdownTable/CostBreakdownTable.tsx

   • Imports useMemo and usePrintExpansion hook
   • Computes allExpandableKeys from breakdown structure via recursive traversal of work items, household items, and areas
   • Calls usePrintExpansion to enable print expansion behavior

3. client/src/components/CostBreakdownTable/CostBreakdownTable.module.css

   • Print media block: hides toggle button, removes card styling, resets table layout to auto, prevents row breaks

4. client/src/pages/BudgetOverviewPage/BudgetOverviewPage.module.css

   • Print media block: hides hero card, add button, empty state, loading placeholder
   • :global(@media print) reset: overrides dark mode tokens to light values for black text on white

Test Plan

• Print the Budget Overview page with dark mode enabled — verify text is black/dark on white
• Print with expanded and collapsed sections — verify all sections print expanded
• Verify sidebar, hero card, and buttons are hidden in print
• After printing, verify expansion state is restored to pre-print state
• Verify responsive print layout (no horizontal scroll needed)

🤖 Generated with Claude Code

[github-actions]

Thank you for your submission! We require all contributors to sign our Contributor License Agreement before we can accept your contribution.

To sign, please comment on this PR with:
I have read the CLA Document and I hereby sign the CLA

---

I have read the CLA Document and I hereby sign the CLA

---

Frank Steiler seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account.
_{You can retrigger this bot by commenting recheck in this Pull Request. Posted by the CLA Assistant Lite bot.}

[steilerDev]

[product-architect]

Verdict: Approve (posted as comment because self-authored PR)

Scoped, well-constructed fix. Architecture and conventions check out.

Verified

• Hook location: client/src/hooks/usePrintExpansion.ts matches project convention (colocated with useAreas, useBudgetSection, etc.)
• ESM .js extensions: Correctly used in imports (./usePrintExpansion.js, ../../hooks/usePrintExpansion.js)
• CSS Modules + design tokens: Page/component print blocks use locally-scoped selectors. The :global(@media print) custom-property override in BudgetOverviewPage.module.css is wrapped in stylelint-disable color-no-hex with a clear comment — this is a legitimate Layer-1 palette bootstrap case, not a token violation.
• Hook logic: Snapshot pattern is correct. snapshot = null after restore guards against stale state. Cleanup removes both beforeprint and afterprint listeners. useCallback deps are accurate.
• useMemo key collection: Recursive collectors are correct. areaId ?? 'unassigned' handling matches the existing key scheme in CostBreakdownTable. breakdown as sole dep is appropriate — the hook returns a new object on every fetch, so memo invalidation tracks identity of the underlying data.
• Test coverage: Unit tests cover happy path, no-op afterprint, unmount cleanup (×2), empty allKeys (×2), and multi-cycle — well above the 95% bar. E2E covers chrome hiding, forced expansion, chevron hiding, h1 visibility, dark-mode reset, state restoration, and a regression check on an unrelated page.

Architectural concern: global print dark-mode reset

The :global(@media print) block in BudgetOverviewPage.module.css resets CSS custom properties globally (not just on the Budget Overview page) because it targets :root from within a CSS module. This is acceptable given:

1. The spec explicitly calls for "light theme in print is desired everywhere"
2. client/src/styles/print.css already applies a global light-print reset (body { background-color: white; color: black }, * { background-color: transparent !important }), so this PR strengthens — not contradicts — existing intent
3. The token reset closes a gap where child-component print styles that read --color-* tokens would still render dark values

Informational note (non-blocking): The cleanest home for this global reset would be client/src/styles/print.css rather than a page-scoped module file, since the rule applies to every page, not just Budget Overview. Moving it there would make the global scope self-documenting and avoid the need for the :global() escape. Consider in a future refinement pass; no action required on this PR.

Informational observations (not blocking)

• Listener churn: useEffect deps include expandedKeys, so listeners are torn down and re-registered on every expansion change. Functionally correct (closure captures the right snapshot), but a ref-based approach (store expandedKeys in a ref, listeners use .current) would avoid the re-registration and simplify the dep list. Ignorable given the interaction volume on this page.
• Stale snapshot corner case: If the user toggles expansion between beforeprint firing and afterprint firing (only possible in a headless scripted context — the print dialog blocks UI in real browsers), the restored state would be the pre-print snapshot, not the intra-print state. Acceptable behaviour for real usage.

No action required on either — raising for awareness.

[steilerDev]

[ux-designer]

Reviewed against tokens.css, CostBreakdownTable.module.css (screen styles), and BudgetOverviewPage.module.css. Scope: print CSS + usePrintExpansion hook.

---

1. Token usage — screen-mode CSS

All screen-mode CSS uses var(--token-name) throughout. No hardcoded values in screen rules. Clean.

2. Print dark-mode reset — hex escape hatch

The :global(@media print) block intentionally anchors to Layer 1 palette hex constants and is guarded with stylelint-disable color-no-hex. I verified all 11 values against tokens.css Layer 1 — they are exact matches:

Reset value	Layer 1 token	Matches
#ffffff	--color-white	yes
#f9fafb	--color-gray-50	yes
#f3f4f6	--color-gray-100	yes
#111827	--color-gray-900	yes
#374151	--color-gray-700	yes
#6b7280	--color-gray-500	yes
#e5e7eb	--color-gray-200	yes
#d1d5db	--color-gray-300	yes
#166534	--color-green-700	yes
#991b1b	--color-red-700	yes
#c2410c	--color-orange-700	yes

The approach is acceptable. CSS custom properties cannot be reset with var() references inside @media print when the goal is to override the same property that the variable points to — doing so creates a circular dependency. Using Layer 1 hex constants here is the correct escape hatch, and limiting the disable to this block prevents the color-no-hex rule from being silently suppressed elsewhere.

3. Dark mode coverage gap — informational

The reset covers the core --color-bg-*, --color-text-*, --color-border*, --color-success-text-on-light, --color-danger-text-on-light, and --color-warning-text-on-light families. The CostBreakdownTable also uses several tokens that are NOT reset and will still render in dark-mode values if the user prints while in dark theme:

• --color-success-badge-bg — used on subsidy-adjusted rows and confidence badges; dark mode value is rgba(16, 185, 129, 0.15) (tinted green), not the light --color-green-100
• --color-success — used as a border-left accent and for confidence icon color; dark mode value is --color-emerald-400 (#34d399)
• --color-primary — used as expand-button background and link color; dark mode value is --color-blue-400 (#60a5fa)
• --color-primary-bg-hover — used as a left-border accent; dark mode is rgba(59,130,246,0.25)
• --color-warning-text-on-light is reset correctly, but --color-warning-bg (#fff7ed in light mode) is not reset — it does not appear to be used in CostBreakdownTable so no practical impact

For a budget print-out (black ink on white paper), the badge and accent tints are low-severity — they affect decorative color accents and tinted row backgrounds, not primary text legibility. The primary text contrast is correctly handled by the reset. I'm flagging this as informational rather than blocking; a follow-up can extend the reset block with the badge/accent tokens if full color fidelity in dark-mode print is desired.

4. Visual consistency in print

The stripped card chrome (no border, no shadow, no radius, no padding on .breakdownCard) is correct — print output should read as a plain table, not a web UI chrome element. Hiding .perspectiveToggle and .expandBtn is appropriate since the hook forces full expansion. The table-layout: auto reset allows the browser to recalculate column widths for the paper medium. nowrap on numeric columns prevents currency values from wrapping mid-number. break-inside: avoid on all row levels prevents rows from splitting across pages. These are all sensible choices.

5. Accessibility in print

Page <h1> title is explicitly kept visible (not in any hide list). Table structure (thead/tbody/tr/th/td) is untouched — screen-reader-accessible print is preserved. color: inherit on .nameLink ensures links render in body text color rather than blue (which may be invisible or low-contrast depending on printer settings). The ::after { content: none !important } suppression of the global URL-append rule is the correct approach — URL noise is not useful on a budget printout.

6. usePrintExpansion hook

The snapshot-and-restore pattern is correct: snapshot is captured at beforeprint, all keys are expanded, and the snapshot is restored at afterprint. The hook correctly handles the case where afterprint fires without a prior beforeprint (no-op). Cleanup removes both listeners on unmount. The useMemo for allExpandableKeys in CostBreakdownTable.tsx is correctly scoped to [breakdown]. No design system concerns.

---

Verdict: Approve. Print styles are well-structured and the hex escape hatch is justified and correctly applied. The unreset badge/accent tokens in dark print are informational — they affect tinted decorative elements, not text legibility.