Invoices: 'Show only open items' view with open deposits as child rows

[steilerDev]

As a homeowner managing a construction project, I want to see every open invoice and open deposit in one filtered view on the Invoices page so that I know exactly what I still have to pay and what is already overdue, without opening each invoice one by one.

Parent Epic: none — standalone story (all epics are closed; this is a budget/invoice backlog item)
Priority: Should Have

---

Problem

Deposits are only visible on InvoiceDetailPage — one invoice at a time. There is no cross-invoice deposit view anywhere in the application, so a deposit whose due date has passed is invisible unless the user happens to open that specific invoice. GET /api/invoices returns deposits: [] on every list row and accepts only a single status value, so this cannot be solved client-side.

Scope

Extend the existing Invoices page (/budget/invoices) with a "Show only open items" toggle. Open deposits appear as expandable child rows under their parent invoice.

/budget/invoices    [x] Show only open items

▾ INV-204  Muster Bau   2026-08-12   €15,000  pending
    └ Deposit 1/3       2026-08-12    €5,000  OVERDUE
    └ Deposit 2/3       2026-09-12    €5,000  pending
  INV-198  Elektro X    2026-08-20    €2,310  pending

Definition of "open" (fixed — not open for re-litigation)

status === 'pending', applied independently to invoices and to deposits. Explicitly excludes 'quotation', 'paid', and 'claimed'. Overdue (pending + dueDate in the past) is a flag, not a status and not a separate bucket — overdue items remain open items.

Out of scope

• Any new page, route, or navigation tab.
• Dashboard changes (InvoicePipelineCard is untouched).
• Treating quotation invoices as open in their own right.
• Creating, editing, or settling deposits from this view (detail page keeps that).
• Changing the meaning of finalPaymentAmount, the existing summary buckets, or any existing status semantics.
• Notifications, reminders, or emails about overdue items.

---

Acceptance Criteria

A. Server-side open-items filtering

• AC1 — Given the invoice list endpoint, when an open-items filter is requested, then the response contains exactly those invoices that either (a) have status === 'pending', or (b) have at least one deposit with status === 'pending' (of either entryType). Invoices matching neither are absent.
• AC2 — Given an invoice with status === 'quotation' that has a pending deposit, when the open-items filter is applied, then that invoice is returned (its pending deposit is an open item and must be visible), and the invoice's own amount contributes nothing to the open totals of AC10/AC11.
• AC3 — Given the open-items filter is applied, when the response is returned, then each returned invoice carries its deposits in the deposits field with the field's existing documented meaning unchanged (the invoice's deposit entries) — the field is not silently redefined to mean "pending deposits only". Filtering to pending for display is the client's job (AC7).
• AC4 — Given the open-items filter is applied, when pagination is computed, then pagination.totalItems and totalPages count invoices only. Child deposit rows never consume page capacity, and a page of size 25 returns at most 25 invoices regardless of how many deposits they carry.
• AC5 — Given the endpoint receives the open-items filter parameter, when the request is validated, then it is accepted (the querystring schema is additionalProperties: false today and currently rejects it). Requests without the parameter behave exactly as before.

B. The toggle and its state

• AC6 — Given the user is on /budget/invoices, when they activate "Show only open items", then the list re-queries with the open-items filter, the URL gains a query parameter representing the toggle, and a full page reload or a browser Back/Forward to that URL restores the toggle in the same state.
• AC7 — Given the toggle is ON, when a status column filter is active or is subsequently chosen, then the two cannot contradict each other: turning the toggle ON clears any active status filter from the table state and URL and disables the status filter control while ON; choosing a status filter turns the toggle OFF. (Decision: mutual exclusivity, because "open" is itself a status predicate.)
• AC8 — Given the toggle is ON, when any other filter, search, or sort is applied, then it composes with the open-items filter rather than replacing it (e.g. open items for one vendor).

C. Rows and child rows

• AC9 — Given the toggle is ON, when the list renders, then each returned invoice is a parent row and each of its pending deposits is a child row beneath it. Non-pending deposits of that invoice are not rendered as child rows. A parent with no pending deposits renders as a plain row with no expand control.
• AC10 — Given a parent row exists only because of its pending deposits (its own status is not pending — see AC2), when it renders, then it is visually and programmatically marked as a container that is not itself an open item, and its own status badge shows its real status.
• AC11 — Given a parent row has pending deposits, when the list first renders in open-items mode, then it is expanded by default; the user can collapse and re-expand it, and this expansion state is component-local (it is not written to the URL).
• AC12 — Given the toggle is OFF, when the list renders, then there are no child rows and the page behaves exactly as it does today.

D. Amounts — the double-counting trap

• AC13 — Given deposits carve up the invoice total (Σ deposits ≤ invoice.amount), when parent and child amounts are displayed, then the UI makes clear that child amounts are part of the parent amount and not additional to it. A user must not be able to read the screen as €15,000 + €5,000 + €5,000.
• AC14 — Given the toggle is ON, when the list renders, then each parent row shows an open amount for that invoice, defined as: (invoice.status === 'pending' ? max(0, invoice.amount − Σ deposit-type entries of any status) : 0) + Σ (pending deposit-type entries), i.e. the still-unpaid final payment plus the still-unpaid deposits. Pending refunds are excluded from this figure (see AC17).
• AC15 — Given a set of open invoices spanning multiple pages, when the per-invoice open amounts of AC14 are summed across the whole result set, then the sum equals the open payable total of AC16 exactly (no double counting, no omission).
• AC16 — Given the page header summary, when the open-items view is available, then an open payable total (count + amount) is shown, computed as in AC14 summed over all invoices. This figure is global / filter-independent, matching the established behaviour of the existing summary tiles, and therefore does not change when the toggle or any filter is applied.
• AC17 — Given the existing summary.pending bucket nets pending refunds against payables, when the open payable total is computed, then it does not reuse that netted figure unchanged: pending refunds are excluded from the payable total and reported separately (AC19).

E. Refunds (entryType: 'refund')

• AC18 — Given a deposit with entryType === 'refund' and status === 'pending', when the open-items filter is applied, then it is an open item (money owed to the user) and renders as a child row that is visually distinguished from a payable deposit, signed so the direction of money is unambiguous.
• AC19 — Given pending refunds exist, when totals are shown, then the refund amount is reported as its own figure ("refunds due to you") and is never summed naively into the open payable total of AC16.
• AC20 — Given an invoice whose only open entry is a pending refund, when the open-items filter is applied, then the invoice appears with that refund as a child row, and its open payable amount (AC14) is 0.

F. Overdue

• AC21 — Given an open item (invoice or deposit) whose dueDate is strictly before today, when it renders, then it is flagged as overdue by a visual treatment plus an accessible text/label — colour alone is not sufficient — while keeping its pending status badge. No new status value is introduced anywhere.
• AC22 — Given the toggle is ON and the user has not chosen an explicit sort, when the list is ordered, then invoices are sorted ascending by their earliest open due date, defined as the minimum of the invoice's own dueDate (when the invoice is pending) and the dueDates of its pending deposits. Overdue items therefore appear first, without being placed in a separate bucket or given a separate status.
• AC23 — Given an open invoice with a null dueDate and no pending deposits with due dates, when the default open-items ordering of AC22 is applied, then it sorts last, after all dated items.
• AC24 — Given the user chooses an explicit sort column, when the list re-renders, then that sort wins over the AC22 default and the toggle stays on.
• AC25 — Given a parent invoice that is not itself overdue but has an overdue pending deposit, when the list renders, then the overdue condition is discoverable on the collapsed parent row (the user must not have to expand it to learn something is overdue).

G. Empty state

• AC26 — Given the toggle is ON and no open items exist, when the list renders, then a distinct "nothing open" empty state is shown (positive framing — nothing is outstanding), and it does not show the existing "add your first invoice" copy or its call-to-action, which would be wrong when invoices exist but none are open.
• AC27 — Given the toggle is ON and additional filters exclude everything, when the list renders, then the existing "no results for these filters" treatment applies rather than the AC26 empty state.

H. Responsive

• AC28 — Given a mobile viewport where the page renders as cards rather than a table, when the toggle is ON, then open deposits render as clearly nested entries within their parent invoice card, with the same expand/collapse affordance as AC11, and no horizontal overflow at 320px width.
• AC29 — Given tablet and desktop viewports, when the toggle is ON, then parent/child indentation is visually unambiguous and the page passes the project's dark-mode expectations in both themes.

I. Accessibility and i18n

• AC30 — Given the expand/collapse control on a parent row, when a keyboard user reaches it, then it is focusable with a visible focus indicator, operable by Enter/Space, and exposes aria-expanded reflecting its true state; child rows are programmatically associated with their parent.
• AC31 — Given the "Show only open items" toggle, when a screen-reader user encounters it, then it has an accessible name and its state is announced.
• AC32 — Given all new user-facing strings, when they are added, then they live in the budget namespace under invoices.* (English keys only from the implementer), every t() path resolves in client/src/i18n/en/budget.json, and German translations are added by the translator. Amounts and dates use formatCurrency / formatDate from client/src/lib/formatters.ts — never raw Intl or toLocaleDateString.

J. Regression guards

• AC33 — Given the invoice list is requested without the open-items filter, when the response is compared to current behaviour, then it is unchanged: same rows, same pagination, same summary buckets, and deposits still [] on list rows.
• AC34 — Given DataTable gains an expandable-child-row capability, when any other page that uses DataTable renders, then its markup and behaviour are unchanged — the new capability is opt-in and inert when unused.
• AC35 — Given finalPaymentAmount and computeFinalPaymentAmount, when this story ships, then their formula and meaning are unchanged; the new open-amount computation of AC14 is additive and does not replace or redefine them.

---

Notes

Is a new "outstanding amount" computation in scope? — Yes, a narrow one.

Invoice.finalPaymentAmount is not "amount still outstanding". Confirmed in server/src/services/shared/depositAggregateUtils.ts → computeFinalPaymentAmount: it is max(0, amount − Σ deposit-type entries of ANY status − Σ received (paid/claimed) refunds). It subtracts pending deposits, so on an invoice with unpaid deposits it under-reports what is owed, and it is clamped at zero. Nothing in the codebase computes a true outstanding figure.

So AC14/AC15/AC16 require a new, narrowly scoped per-invoice open-amount computation. It must be additive (AC35) — finalPaymentAmount has other consumers and its meaning must not shift.

Note for the implementer: aggregateInvoiceStatusBreakdown already produces a deposit-aware summary.pending bucket that is close to the needed figure (residual of pending invoices + pending deposits, refund-signed). It is deliberately not reusable as-is, because it nets pending refunds against payables — precisely the naive summing AC17/AC19 forbid. Derive alongside it, do not repurpose it.

Decisions made while drafting (flagged for the user — cheap to reverse before implementation)

1. AC2 — quotation invoices as containers. A quotation invoice with a pending deposit appears in the open list, because "see all open deposits" cannot be satisfied otherwise, and quotationCoveredByDeposits in the existing summary proves deposits on quotation invoices are a real, modelled case. The invoice itself contributes nothing to open totals and is marked as a container (AC10). Alternative if unwanted: restrict parents to status === 'pending', accepting that some open deposits become invisible.
2. AC7 — toggle and status filter are mutually exclusive. "Open" is itself a status predicate, so allowing both invites contradictory states like "open items that are paid".
3. AC16 — open totals are global, not filtered. Matches the deliberate existing behaviour of the page's summary tiles (invoiceService.listAllInvoices computes the summary filter-independently by design).

Technical constraints (for the architect / implementer, not decisions)

• GET /api/invoices querystring is additionalProperties: false and accepts a single status enum — a new parameter must be added to the schema (AC5). Exact parameter name and response shape are product-architect's call.
• List rows currently hardcode deposits: [] (invoiceService.listAllInvoices, "Map rows directly (not using toInvoice()) to avoid fetching full deposits in list").
• DataTable (client/src/components/DataTable/DataTable.tsx) has no expandable-row support today. Per the Component Reuse Policy this must be an extension of the shared component, not a parallel implementation — which is why AC34 exists.
• Mobile card rendering goes through DataTableCard; ordering is server-side SQL (ORDER BY on invoice columns only), so AC22's "earliest open due date" ordering is genuine server work.

Commit convention

This story has no parent epic, so /epic-close (the only workflow with a UAT step) will never run for it. Commits must use Refs #<this issue>, not Fixes #<this issue>, so a standalone /release cannot auto-close it before UAT. Acceptance is the board status, set by the product-owner.

[steilerDev]

[product-owner]

UAT Scenarios

Reference for QA/E2E test authoring and for manual validation. Each scenario is binary pass/fail.

Fixture set (used by scenarios below)

Invoice	Status	Amount	Due	Deposits
INV-A	pending	€15,000	2026-09-30	D1 €5,000 pending due 2026-08-01 (past), D2 €5,000 pending due 2026-09-12, D3 €5,000 paid
INV-B	pending	€2,310	2026-08-20	none
INV-C	quotation	€40,000	—	D4 €8,000 pending due 2026-08-15
INV-D	paid	€900	2026-07-01	none
INV-E	pending	€1,000	null	none
INV-F	pending	€4,000	2026-08-25	R1 €1,200 refund pending

Today = 2026-08-09 for the purposes of "overdue".

---

S1 — Toggle filters the list (AC1, AC6)
Given the fixture set, when I open /budget/invoices and switch on "Show only open items", then INV-A, INV-B, INV-C, INV-E and INV-F are listed and INV-D is not.

S2 — Toggle survives reload and Back (AC6)
Given the toggle is on, when I reload the page and then navigate away and press Back, then the toggle is still on and the same filtered list is shown both times.

S3 — Quotation parent appears only as a container (AC2, AC10)
Given the toggle is on, when I look at INV-C, then it is listed, its badge reads "Quotation", it is marked as not itself an open item, and its own €40,000 is not included in the open payable total.

S4 — Only pending deposits become child rows (AC9)
Given the toggle is on and INV-A is expanded, when I count its child rows, then exactly two are shown (D1 and D2); the paid D3 is not shown. INV-B shows no expand control.

S5 — Expanded by default, collapsible, not in the URL (AC11)
Given the toggle is on, when the list first renders, then INV-A is expanded; when I collapse it, the child rows disappear and the URL does not change; when I reload, INV-A is expanded again.

S6 — No double counting on screen (AC13, AC14, AC15)
Given the toggle is on, when I read INV-A's row, then its open amount is €10,000 (€15,000 − €15,000 of deposit-type entries = €0 residual, + €5,000 D1 + €5,000 D2), it is clearly not €25,000, and the sum of every listed invoice's open amount equals the open payable total in the header exactly.

S7 — Open payable total is global (AC16)
Given the header shows an open payable total, when I switch the toggle on and off and when I filter by vendor, then that total does not change.

S8 — Pending refund is open but not netted (AC18, AC19, AC20)
Given the toggle is on, when I look at INV-F, then R1 appears as a child row visually distinguished from a payable deposit with an unambiguous money direction, INV-F's open payable amount is €4,000 (the refund is not subtracted from it), and the €1,200 appears in a separate "refunds due to you" figure.

S9 — Overdue is a flag, not a bucket (AC21, AC25)
Given the toggle is on, when I look at D1 (due 2026-08-01), then it is flagged overdue with both a visual treatment and accessible text, its status badge still reads "Pending", there is no "Overdue" status option anywhere, and the overdue condition is visible on INV-A's row while it is collapsed.

S10 — Default ordering surfaces the earliest open due date (AC22, AC23)
Given the toggle is on and no explicit sort is chosen, when the list renders, then the order is INV-A (earliest open due 2026-08-01, from its deposit), INV-C (2026-08-15), INV-B (2026-08-20), INV-F (2026-08-25), INV-E (no due date) last.

S11 — Explicit sort wins (AC24)
Given the toggle is on, when I sort by Amount descending, then the list re-orders by amount and the toggle stays on.

S12 — Toggle and status filter cannot contradict (AC7)
Given a status filter of "Paid" is active, when I switch on "Show only open items", then the status filter is cleared from the table and from the URL and its control is disabled; when I then switch the toggle off, the control is usable again.

S13 — Filters compose (AC8)
Given the toggle is on, when I additionally filter by the vendor of INV-B, then only INV-B is listed.

S14 — Nothing-open empty state (AC26)
Given every invoice is paid or claimed, when I switch on "Show only open items", then a positive "nothing open" message is shown and the "add your first invoice" call-to-action is not offered.

S15 — No-results-for-filters state is distinct (AC27)
Given the toggle is on and open items exist, when I add a vendor filter that matches none of them, then the existing "no results for these filters" treatment is shown, not the S14 message.

S16 — Mobile cards nest deposits (AC28)
Given a 320px-wide viewport, when the toggle is on, then INV-A renders as a card with D1 and D2 clearly nested inside it, the same expand/collapse works, and the page does not scroll horizontally.

S17 — Keyboard and screen reader (AC30, AC31)
Given I navigate with the keyboard only, when I reach a parent row's expand control, then it shows a visible focus indicator, toggles with Enter and with Space, and its aria-expanded matches its visual state; the "Show only open items" control has an accessible name and announces its on/off state.

S18 — Dark mode and tablet (AC29)
Given tablet and desktop viewports in both light and dark themes, when the toggle is on, then parent/child indentation is unambiguous and no element is unreadable in either theme.

S19 — Nothing regresses with the toggle off (AC12, AC33)
Given the toggle is off, when I use the Invoices page as before, then rows, pagination, filters, sorting and the existing summary tiles behave exactly as they did before this change, and no child rows appear.

S20 — Other DataTable pages untouched (AC34)
Given the shared DataTable gained expandable rows, when I visit the other pages that use it, then nothing about their appearance or behaviour has changed.

S21 — Pagination counts invoices only (AC4)
Given more than 25 open invoices each carrying pending deposits, when the toggle is on with page size 25, then page 1 shows 25 invoices (plus their child rows) and the reported total item count is the invoice count, not the invoice-plus-deposit count.

[steilerDev]

[ux-designer]

Visual Specification — "Show only open items" (Issue #2046)

Read against all 35 ACs and the 21 UAT scenarios. I'm departing from the ASCII mockup in one deliberate way (see §1) — the literal mockup as drawn reproduces the double-counting trap the ACs explicitly forbid, so it can only be schematic, not pixel spec.

---

1. The double-counting trap (AC13/AC14/AC15)

The mockup's literal column reuse is the bug. If a deposit's amount lands in the same "Amount" column as the parent's invoice total, a user reading top-to-bottom adds them. Two changes fix this:

A. Split "Amount" (invoice face value) from "Open" (AC14 figure) as two distinct, differently-styled cells — never the same visual slot.

• Parent row, Amount column (existing column, unchanged meaning): invoice face value, e.g. €15,000. Plain --color-text-primary, --font-weight-medium, tabular-nums — exactly today's .amountCell treatment.

• New Open column (only rendered/visible when the toggle is ON — see §8 for how this composes with column-visibility prefs): parent row shows the AC14 open amount as the headline figure, bold, with a muted one-line composition caption directly beneath it in the same cell:

  €10,000                    ← font-weight-semibold, color-text-primary
  of €15,000 · 2 open        ← font-size-xs, color-text-muted
  

  The caption text is t('invoices.openItems.openAmountCaption', { total, count }) → "of {{total}} · {{count}} open" (EN key; German via translator). This caption is what actually prevents the mental-math error: it tells the user in words that the €10,000 is carved out of the €15,000, not stacked on it.

B. Child (deposit) rows never present their amount as a peer figure.

• Child row, Open column shows the deposit's own pending amount, but demoted: smaller (--font-size-sm vs parent's --font-size-base), --color-text-secondary (not -primary), prefixed with an "included" glyph, and captioned:

  ⊂ €5,000                   ← font-size-sm, color-text-secondary
  part of total above        ← font-size-2xs, color-text-muted, italic
  

  ⊂ is decorative (aria-hidden="true"); the caption text t('invoices.openItems.childIncludedCaption') ("part of total above") is what a screen reader announces, so the "not additional" fact is conveyed non-visually too.

• Child row, Amount column (the invoice-total column): render — (em dash), same as any other N/A cell in this table today. A deposit has no invoice-total of its own — leaving this cell blank removes the second place a user could stack numbers.

C. Refund child rows use the same demoted treatment but a different caption (excluded, not included) — see §4.

Net effect: reading the parent row alone gives the correct AC14 number with its own explanation. Reading a child row alone never presents a number that looks like it should be added to anything above it — it explicitly says the opposite.

---

2. Container-only parents (AC2/AC10)

A quotation invoice that's only listed because of a pending deposit must never look like an open item.

• Status badge: unchanged — still renders Quotation via the existing invoiceStatusVariants map (AC10 requires the real status to show; do not fabricate a status).
• No Open headline treatment: the new Open column (§1) renders — for these parents, not €0 and not a bold figure — there is nothing open about the invoice itself.
• Container badge: add a second, small outlined chip next to the status badge, text t('invoices.openItems.containerBadge') → "Deposits only". Style: background: transparent, border: 1px solid var(--color-border-strong), color: var(--color-text-muted), same pill shape/padding as Badge (--radius-full, --spacing-0-5 --spacing-2, --font-size-xs) but rendered as a plain <span>, not through the Badge component's variant map (it's not a status — it's a second, independent signal that can co-occur with any status badge, which Badge's one-variant-per-value model doesn't support cleanly).
• Row-level signal: give the leftmost cell (invoice number) a 2px left border rail: --color-primary for a genuinely-open parent (status === 'pending'), --color-border-strong (neutral) for a container-only parent. This is a single glance-able differentiator that survives at any zoom level and doesn't rely on reading text.
• Programmatic: the parent <tr> gets data-open-item="false" / "true" (or equivalent prop-driven attribute) so QA/E2E can assert on it directly rather than parsing badge text — this satisfies "programmatically distinguishable" without inventing new ARIA (a container row is still a normal, fully-operable row; nothing about its interaction model differs, so no ARIA state is warranted, just a data hook).

---

3. Overdue treatment (AC21, AC25)

Overdue is a flag on top of pending, never a replacement badge, and must be visible without expanding.

• On the item that is itself overdue (deposit or invoice), place a small inline indicator immediately after its due-date cell content:

  ⚠ Overdue
  

  Style: color: var(--color-danger-text-on-light), background: var(--color-danger-bg), border-radius: var(--radius-sm), padding: 0 var(--spacing-1-5), font-size: var(--font-size-xs), font-weight: var(--font-weight-medium). The glyph ⚠ is aria-hidden="true"; the word "Overdue" is real text — this is the "colour alone is not sufficient" requirement from AC21 satisfied directly (text, not just a red dot).

• Discoverability on a collapsed parent (AC25) — this is the harder half. A parent whose own due date is fine but which has an overdue child must surface that fact without expanding:

  • Add the same ⚠ Overdue indicator to the parent row, driven by "any open item under this invoice (itself or a pending deposit) is overdue" rather than only the invoice's own dueDate. Do not invent a second visual language for "something inside is overdue" vs "I am overdue" — same chip, same meaning ("there is overdue money here"), because from the user's task ("what do I need to pay right now") the distinction doesn't matter.
  • Place it directly beside the expand chevron (§7), in the invoice-number cell, so it's the first thing seen — not buried in the due-date column, which is easy to miss on a collapsed row when the invoice's own due date (unaffected) is what's printed there.
  • This is why it must be a real inline indicator and not a Tooltip-only affordance: Tooltip (client/src/components/Tooltip/Tooltip.tsx) is hover/focus-triggered with no click/touch fallback, so anything shown only on hover is invisible on the mobile card layout by definition. The ⚠ Overdue chip must render statically.

---

4. Refund child rows (AC18/AC19/AC20)

Reuse the pattern already shipped in InvoiceDepositsSection.tsx (DepositRow/DepositCard) rather than inventing one — it already solves "unambiguous direction of money":

• Same Badge treatment: variants.refund = { label: t('invoices.openItems.entryTypeLabels.refund'), className: <uses --color-status-blocked-bg/-text> } (the existing red badge pair — do not invent a new --color-danger-badge-* token family; --color-status-blocked-bg/-text is the established red badge pair used for this exact purpose in InvoiceDepositsSection.module.css's .refund class).
• Amount rendered via formatCurrency(-deposit.amount) — the literal minus sign from Intl.NumberFormat is part of the "unambiguous" signal, on top of the badge. Color: --color-danger-text-on-light (matches .amountNegative in InvoiceDepositsSection.module.css).
• Open column caption differs from a payable deposit's (§1B): a refund's caption is not "part of total above" (it explicitly does not count toward the parent's open payable amount per AC14/AC20) but t('invoices.openItems.childExcludedCaption') → "reported separately below" — pointing at the header's "Refunds due to you" tile (§5). Getting this caption wrong (reusing "part of total above" for a refund) would restate the exact bug AC19 forbids, just in words instead of arithmetic — do not let implementation copy-paste the deposit caption onto the refund row.
• Invoice whose only open entry is a refund (AC20): parent's Open column renders €0 (not —) with the standard headline styling — €0 is a real, correct value here (there is genuinely nothing payable), distinct from the container-only — in §2 (which means "not applicable, this row isn't open at all"). Don't conflate the two.

---

5. Header summary (AC16/AC19)

Two new tiles in the existing .summaryGrid (InvoicesPage.module.css), which already reflows via repeat(auto-fit, minmax(140px, 1fr)) desktop / repeat(2, 1fr) mobile — no grid changes needed, it already absorbs more tiles.

• "Open (Payable)" tile — always visible (matches AC16's "does not change when toggle... is applied", and matches how pending/claimed/quotation tiles today are unconditional). Same .summaryCard shell, label t('invoices.openItems.summaryOpenPayable'), count + formatCurrency(amount). Amount color: plain .summaryAmount (default --color-text-secondary) — this is a neutral "still owed" figure, not a positive or negative outcome, so it shouldn't borrow .summaryAmountPaid's green.
• "Refunds due to you" tile — conditionally rendered, same convention as the existing hasOverdue && (...) conditional card (summaryCardOverdue): only shown when the refund total > 0. Label t('invoices.openItems.summaryRefundsDue'), amount styled .summaryAmountPaid (green, --color-success-badge-text) — unlike the payable tile, a refund is money coming back, which is the same "good news" semantic the codebase already colors green for claimed/claimable amounts.
• Placement: insert both after the existing quotation tile and before the conditional overdue tile, so the overdue tile (a warning) stays visually last/most-alarming.
• Per AC17, do not wire either tile to summary.pending (the netted bucket) — they must come from the new AC14/AC17 computation the architect/backend own. This is a data-plumbing note, not a visual one, but it's worth restating here since a visually-identical-looking tile fed the wrong number would pass a design review and still be wrong.

---

6. Responsive — mobile cards (AC28/AC29)

DataTableCard (client/src/components/DataTable/DataTableCard.tsx) currently renders one flat .card per item with no concept of children. Extend it (see §9 for the API shape) so that when a parent has pending deposits:

• The parent card renders exactly as today (.cardHeader/.cardContent/.cardRows), plus:
  • The expand toggle (§7) as a 44×44px button in the card header, to the left of the existing content, using the same chevron glyph/rotation as the desktop version.
  • The ⚠ Overdue chip (§3) and container badge (§2) inline in the card's existing row for status/amount — no new card rows needed for these, they attach to the cells that already exist.
• When expanded, child cards render inside the parent card (not as sibling cards in .cardsContainer — nesting must be structural, not just visual, or AC28's "clearly nested" requirement is unmet on a re-flowed narrow screen where indentation alone collapses). New block .cardChildren: background: var(--color-bg-secondary), border-left: 2px solid var(--color-border-strong) (neutral rail, or --color-primary — reuse the same rail-color logic as §2), margin-top: var(--spacing-3), padding: var(--spacing-3), border-radius: var(--radius-md), containing one simplified .cardChildRow per deposit (deposit label + due date + Open figure with its caption + status/refund badge), stacked with flex-direction: column; gap: var(--spacing-2).
• No fixed widths anywhere in the new markup — reuse .cardValue's existing word-break: break-word; the Open column's two-line (headline + caption) layout must wrap onto its own lines rather than force horizontal scroll (white-space: normal, not nowrap). At 320px, €10,000 / of €15,000 · 2 open stacked vertically in a flex-direction: column cell — never side-by-side — is what keeps this within budget.

Tablet/desktop (AC29): the existing --breakpoint-md/--breakpoint-lg table layout already has room; the only requirement is that the indentation (§7's row indent) plus the left-rail color (§2) together make parent/child unambiguous in both themes — verify by checking --color-border-strong and --color-primary both meet 3:1 non-text contrast against --color-bg-primary in dark mode (they do: --color-border-strong → --color-slate-400 #475569 against --color-slate-800 #1a1a2e background passes; --color-primary in dark mode is --color-blue-400 #60a5fa, well above 3:1).

---

7. Accessibility — expand/collapse pattern (AC30/AC31)

DataTable renders a real <table>/<tbody>/<tr> on desktop and a <div> card list on mobile — the pattern has to work in both without relying on DOM nesting HTML forbids inside <table> (you cannot wrap a <tr> inside another <tr>, so parent/child association is by reference, not containment).

Desktop table:

• The expand control is a real <button> prefixed inside the parent row's leftmost visible cell (same cell as the invoice-number link), not a separate table column — this avoids adding a column that the other 5 DataTable pages don't have and keeps AC34's "inert when unused" property trivially true (no expandableRows prop = no button, no layout change, full stop).
• Chevron glyph: reuse InvoiceGroup.tsx's established rotate pattern (▸ collapsed → rotate 90° to ▾ on expand, transition: transform var(--transition-normal), disabled under prefers-reduced-motion).
• aria-expanded={isExpanded} on the button, reflecting true state (AC30).
• aria-controls="deposit-row-{id-1} deposit-row-{id-2} …" — space-separated ids of the child <tr> elements, which is the standards-correct way to associate a trigger with a non-adjacent-in-the-accessibility-tree set of controlled elements when true DOM nesting isn't possible.
• aria-label={t('invoices.openItems.expandLabel', { invoiceNumber, count, action: isExpanded ? 'collapse' : 'expand' })} — must say how many deposits, not just "expand", since the count is exactly the information a screen reader user can't infer from a collapsed row otherwise (mirrors InvoiceGroup.tsx's existing ariaLabel construction, which already includes line count + amount).
• Native <button> already handles Enter/Space activation — no custom onKeyDown is needed (note: InvoiceGroup.tsx has one anyway, defensively; it's redundant but harmless — don't copy it unless there's a reason).
• Focus ring: box-shadow: var(--shadow-focus) on :focus-visible, matching every other interactive element in DataTable.module.css — do not use outline.
• Each child <tr> gets id="deposit-row-{depositId}". Its first cell's visible text ("Deposit 1/3") already differentiates it, but to make the parent relationship legible to a screen reader user who navigates directly into the child row (table row-by-row navigation, not via the trigger), prefix a visually-hidden span (sharedStyles.srOnly, already defined in client/src/styles/shared.module.css) reading t('invoices.openItems.childOf', { invoiceNumber }) → "Part of invoice {{invoiceNumber}}: " before the visible "Deposit 1/3" text.
• Child rows get a distinct row background tint (--color-bg-secondary) so the parent/child boundary is visible even before considering indentation — this covers the "child rows are... associated" visual half; the ARIA above covers the programmatic half.

Mobile cards: identical aria-expanded/aria-controls contract on the card's expand button; the controlled elements are the child cards' container id (a single id="deposit-children-{invoiceId}" on the .cardChildren block is sufficient here since children are true DOM descendants of the card, unlike the table case).

The toggle control (AC31): a native <input type="checkbox"> inside a <label> with visible text "Show only open items" — the accessible name comes from the visible label (no extra aria-label needed), and native checkbox semantics announce checked/unchecked automatically on every screen reader without any custom role="switch" plumbing. This also matches the only existing boolean-ish precedent in the table toolbar (BooleanFilter's segmented control uses aria-pressed, but that's a 3-state control; a genuine 2-state persistent mode toggle is exactly what <input type="checkbox"> is for — don't reach for a custom switch component that doesn't exist anywhere in this codebase).

---

8. The toggle control itself — slot, look, disabled state

• Slot: customFilters, not headerContent. headerContent (currently used for the summary tiles) renders above the whole DataTable shell; customFilters renders as a second row inside .toolbar, directly below the search box — exactly where a control that composes with search/sort/filters (AC8) and must visually and functionally interact with the status filter (AC7) belongs. No page currently populates customFilters (confirmed by search), so this is the slot's first real use, but it's exactly what it was built for.
• Look: checkbox + label, not a segmented control and not an invented track/thumb switch. Reuse the existing 18px checkbox recipe from Filter.module.css's .filterCheckbox (border: 1px solid var(--color-border-strong), border-radius: var(--radius-sm), accent-color: var(--color-primary)). Wrap the checkbox + label text in a <label> with padding: var(--spacing-2) var(--spacing-1) so the combined tap target clears 44px height even though the checkbox glyph itself is 18px (same "generous label padding, not a padded box around a tiny control" approach used for other checkbox rows in this codebase, e.g. BudgetLineForm's radio rows).
• Disabled state (AC7, mutual exclusivity with the status filter): opacity: 0.5 on the label + cursor: not-allowed, matching .filterButtonSecondary:disabled's existing convention. Wrap in the shared Tooltip component with content t('invoices.openItems.toggleDisabledHint') → "Turn off the status filter to show open items" for mouse/keyboard-focus users; the native disabled attribute on the <input> communicates it to screen readers without extra ARIA. This tooltip is a supplement, not the only signal — the dimmed, non-interactive appearance and the disabled announcement both work without hover, satisfying the same "don't rely on hover-only" principle from §3.
• Sort-order caption: when the toggle is ON and no explicit sort is chosen (AC22's default), add a small caption to the right of the toggle: t('invoices.openItems.defaultSortHint') → "Sorted by earliest due date", font-size: var(--font-size-xs), color: var(--color-text-muted). This isn't in the ACs but pre-empts a real confusion: INV-C (quotation, container-only) sorting before INV-B in the default order (per UAT S10) looks like a bug until you know the sort key. Cheap to include, cheap to cut if the team disagrees.

---

9. DataTable API extension — minimal, opt-in, inert elsewhere (AC34)

I'm not making the architectural call on the exact prop shape (that's frontend-developer/product-architect territory), but the behavioral contract the API must satisfy is:

• Nothing changes for the 5 other DataTable consumers (workItems, householdItems, milestones, vendors, users) unless they opt in — so the new capability must be a single new optional prop that is undefined for every other page, with all new rendering gated behind prop !== undefined.
• A parent with zero qualifying children renders with no expand control at all (AC9) — not a disabled/greyed-out chevron, nothing.
• Child content (deposits) has a different shape than parent content (invoices) — don't force reuse of the same ColumnDef<T>[] typed to the parent's T; the child renderer needs to be its own function, not a coincidental reuse of parent columns.
• Default-expanded state (AC11) is computed per-item, is useState-local to the row (never reflected in TableState/URL), and resets on remount (e.g., page navigation away and back) — consistent with "expansion state is component-local."

A reasonable shape meeting all four:

expandableRows?: {
  getChildren: (item: T) => unknown[];               // [] ⇒ no expand control (AC9)
  getChildKey: (child: unknown, parent: T) => string;
  renderChildRow: (child: unknown, parent: T) => ReactNode;   // <tr> cells, desktop
  renderChildCard: (child: unknown, parent: T) => ReactNode;  // nested card content, mobile
  isDefaultExpanded?: (item: T) => boolean;           // AC11, default false
  getExpandLabel: (item: T, expanded: boolean, childCount: number) => string; // aria-label
};

Plus the empty-state extension from §10.

---

10. Empty states (AC26/AC27)

Two distinct states, and a third (unrelated, pre-existing) state must NOT be triggered by mistake:

1. "Nothing open" (AC26) — toggle ON, no other filters active, zero results. Positive framing, no CTA: EmptyState with icon="✅", message={t('invoices.openItems.empty.title')} → "Nothing open right now", description={t('invoices.openItems.empty.description')} → "Every invoice and deposit is paid, claimed, or otherwise settled." — and critically, no action prop (omit it entirely; don't pass addFirstInvoice here even though invoices exist).

2. "No results for these filters" (AC27) — toggle ON, an additional filter (e.g. vendor) matches nothing. This is DataTable's existing generic filtered-empty-state (t('dataTable.empty.filteredMessage') + clear-filters action) and requires no new markup — it already fires correctly today whenever tableState.filters/search is non-empty, and a vendor filter does populate tableState.filters, so hasActiveFilters is already true in this case without any new plumbing.

3. The bug to avoid: case 1 has hasActiveFilters === false today (the toggle itself lives outside tableState.filters — it has to, since AC7 requires it to clear the status filter, so it can't itself be stored as one). DataTable's current logic would therefore fall through to its default branch — emptyState.message || t('dataTable.empty.defaultMessage'), with the page's action (today, "Add your first invoice"). That is exactly the wrong CTA AC26 forbids ("nothing open" ≠ "you have no invoices").

   Fix: add one more optional DataTable prop, e.g. emptyStateAction?: 'auto' | 'suppress' (default 'auto', preserving today's behavior for every other page — AC34-safe). InvoicesPage sets it to 'suppress' precisely when openOnly && !hasActiveFilters && items.length === 0, which renders the page-provided message/description with the action button omitted regardless of the hasActiveFilters branch. When openOnly && hasActiveFilters, leave it 'auto' — case 2 already resolves correctly through existing logic.

---

Interactive states summary

Element	Default	Hover	Focus	Active/Pressed	Disabled
Toggle checkbox	--color-border-strong border	n/a (native checkbox)	box-shadow: var(--shadow-focus) on the input	accent-color: var(--color-primary) fill when checked	opacity: 0.5, cursor: not-allowed, Tooltip hint
Expand button (desktop)	--color-text-muted chevron	background: var(--color-bg-tertiary) (44px hit area, padding:10px; margin:-10px technique per existing .expandButton convention)	box-shadow: var(--shadow-focus)	chevron rotates 90°, transition: transform var(--transition-normal)	n/a — never rendered disabled, only absent
Expand button (mobile card)	same glyph, 44×44 box	n/a (touch)	box-shadow: var(--shadow-focus)	same rotation	n/a
Container badge / Overdue chip	static, non-interactive	n/a	n/a	n/a	n/a

All transitions use --transition-normal (0.15s ease) and are disabled under @media (prefers-reduced-motion: reduce), matching every other transition in DataTable.module.css.

---

Dark mode

Every token referenced above (--color-danger-*, --color-status-blocked-*, --color-border-strong, --color-primary, --color-bg-secondary, --color-text-muted/-secondary/-primary) already has a [data-theme="dark"] override in tokens.css — nothing new needs a dark-mode stub. Two things worth double-checking at implementation review time:

• The ⊂/⚠ decorative glyphs are plain text characters (not SVG with hardcoded fill), so they inherit currentColor automatically in both themes — verify the implementer didn't hardcode a fill color.
• The container-row left-rail (--color-border-strong) and open-row left-rail (--color-primary) must both be visually distinguishable from each other AND from the row's own background in dark mode — spot-check side by side, since --color-border-strong (--color-slate-400) and --color-primary (--color-blue-400) are different enough hues that this should hold, but low-vision contrast between "primary blue" and "neutral gray-blue" against a near-black slate background is worth an eyeball check in the PR review.

---

Component Mapping

UI Element	Shared Component	Props/Variant	Notes
"Show only open items" toggle	plain <input type="checkbox"> + <label>	—	No switch component exists in the codebase; checkbox is the correct native semantic for a persistent boolean mode. New reusable pattern candidate for Style Guide, not a new component.
Toggle disabled hint	Tooltip	content={t('invoices.openItems.toggleDisabledHint')}	Existing, client/src/components/Tooltip/Tooltip.tsx
Container badge ("Deposits only")	plain <span>, not Badge	—	Badge is one-variant-per-value; this must co-occur with any real status badge, which the variant-map model doesn't support. Justified new pattern, not a new component (styled inline via CSS Module).
Overdue chip	plain <span>	—	Same reasoning — must co-occur with the pending status badge, not replace it.
Refund badge on child rows	Badge	variants.refund reusing --color-status-blocked-bg/-text	Reuse InvoiceDepositsSection.tsx's existing entryTypeVariants pattern verbatim — do not reinvent.
Invoice/deposit status badges	Badge	existing invoiceStatusVariants	Unchanged from current InvoicesPage.tsx
"Nothing open" empty state	EmptyState	icon="✅", no action	Existing, client/src/components/EmptyState/EmptyState.tsx
"No results for filters" empty state	EmptyState (via DataTable internal logic)	unchanged	Already correct, no new code needed (§10)
Expand/collapse control	new: plain <button> w/ aria-expanded/aria-controls	—	Modeled directly on client/src/components/budget/InvoiceGroup.tsx's existing chevron-toggle pattern; not extracted into a shared component because it's one call site today, but flag as an extraction candidate if a second expandable-table use case shows up.
Child row nesting (mobile)	extend DataTableCard	new expandableRows prop (§9)	This is the shared-component change — lives on DataTable/DataTableCard themselves, available to all 6 pages going forward.
Summary tiles (Open Payable / Refunds due)	existing .summaryCard shell (CSS Module, not a component)	—	InvoicesPage.module.css already has no SummaryTile component — it's inline JSX + CSS Module classes; stay consistent with the existing non-componentized pattern rather than extracting one now.

---

New i18n keys (namespace budget, path invoices.openItems.*)

English keys only (per AC32) — translator adds German:

invoices.openItems.toggleLabel               "Show only open items"
invoices.openItems.toggleDisabledHint         "Turn off the status filter to show open items"
invoices.openItems.defaultSortHint            "Sorted by earliest due date"
invoices.openItems.containerBadge             "Deposits only"
invoices.openItems.openAmountCaption          "of {{total}} · {{count}} open"
invoices.openItems.childIncludedCaption       "part of total above"
invoices.openItems.childExcludedCaption       "reported separately below"
invoices.openItems.entryTypeLabels.refund     "Refund"
invoices.openItems.overdueLabel               "Overdue"
invoices.openItems.expandLabel                "{{action}} {{invoiceNumber}}, {{count}} open deposits" (compose via i18next interpolation + separate expand/collapse verb keys, or two full keys — implementer's call)
invoices.openItems.childOf                    "Part of invoice {{invoiceNumber}}: "
invoices.openItems.summaryOpenPayable         "Open (Payable)"
invoices.openItems.summaryRefundsDue          "Refunds due to you"
invoices.openItems.empty.title                "Nothing open right now"
invoices.openItems.empty.description          "Every invoice and deposit is paid, claimed, or otherwise settled."

All amounts/dates through formatCurrency/formatDate from client/src/lib/formatters.ts — no raw Intl calls (AC32).

---

Pattern references (existing code to model from, not reinvent)

• Expand/collapse ARIA + chevron rotation: client/src/components/budget/InvoiceGroup.tsx + .module.css
• Refund badge + negative-amount styling: client/src/pages/InvoiceDetailPage/InvoiceDepositsSection.tsx (DepositRow, entryTypeVariants, .amountNegative)
• Conditional summary tile (show only when count > 0): InvoicesPage.tsx's existing hasOverdue && (...) overdue card
• Checkbox styling: client/src/components/DataTable/filters/Filter.module.css's .filterCheckbox/.filterCheckboxItem
• 44px touch target via padding+negative-margin on a small glyph: existing .expandButton convention elsewhere in the codebase

Happy to walk through any of the above with frontend-developer before implementation starts if the expandableRows API shape needs adjustment once real typing is attempted.