Redesign auto-itemize as dedicated page launched from document card

[steilerDev]

As a homeowner with a Paperless invoice linked to a Cornerstone invoice, I want the auto-itemize workflow to live on a dedicated full page launched from the linked-document card, with a side-by-side document preview and editable extracted rows, so that I can validate the LLM's interpretation against the underlying document and edit invoice metadata in the same flow without juggling a cramped modal inside the budget-lines section.

Parent Epic: #1547
Priority: Should Have

Description

The current auto-itemize trigger lives as a button + cramped modal inside InvoiceBudgetLinesSection. This redesign relocates the trigger to the per-document LinkedDocumentCard (the natural place — "I want to itemize this document"), turns the modal into a dedicated full page, adds a side-by-side document preview so the user can verify the LLM's reading, and lets the user reconcile invoice metadata (currency, total, dates, vendor) with LLM-suggested values in the same flow. Per-row budget-line linking must reuse the existing two-step picker from InvoiceBudgetLinesSection.tsx — no parallel implementation.

This is a presentation-layer rework. The LLM service, extraction logic, and request/response shapes from #1547 are not touched (one open question to the architect: do we need a new endpoint that atomically updates invoice metadata + creates budget lines, or are two sequential calls acceptable — see Open Questions).

Acceptance Criteria

Group 1 — Trigger placement and visibility (replaces #1547 AC 1-5)

1. Given the invoice detail page renders a LinkedDocumentCard for a Paperless document AND entityType === 'invoice' AND config.autoItemizeEnabled === true, when the card is rendered, then an "Itemize" button appears on the card next to (or replacing the position of) the renamed "Details" button.
2. Given the same card is rendered for a non-invoice entity (work item, household item, diary, etc.), when the card is rendered, then the "Itemize" button is NOT present, regardless of autoItemizeEnabled.
3. Given config.autoItemizeEnabled === false, when an invoice's LinkedDocumentCard is rendered, then the "Itemize" button is NOT present (the "Details" button remains).
4. Given the redesign is in effect, when I open InvoiceDetailPage, then the "Auto-itemize" button is NOT present in the budget-lines section header (the trigger has moved entirely to the document card).
5. Given a LinkedDocumentCard in any context (invoice, work item, household item, diary), when it renders, then the button previously labelled "View" is labelled "Details" (i18n key updated; underlying DocumentDetailPanel inline expand/collapse behavior is unchanged).

Group 2 — Navigation and page lifecycle

6. Given I click the "Itemize" button on a LinkedDocumentCard for invoice :invoiceId and document :documentId, when the click is handled, then the app navigates to a dedicated full page (route TBD — suggest /budget/invoices/:invoiceId/auto-itemize?documentId=N) — NOT a modal overlay.
7. Given the dedicated auto-itemize page mounts, when the page-load effect runs, then it immediately issues POST /api/invoices/:invoiceId/auto-itemize with { paperlessDocumentId, dryRun: true, mode: 'append' } (no "Start" button) and shows an "Analyzing…" indicator (skeleton or spinner with descriptive text) while the request is in flight.
8. Given the page is in the "Analyzing…" state, when the LLM provider is unreachable, then the page shows the LLM_UNREACHABLE error (same i18n key as Auto-itemize invoices from Paperless OCR documents #1547 AC 11) with a Retry button that re-issues the dry-run.
9. Given the LLM returns malformed output, when the dry-run resolves, then the page shows the LLM_INVALID_RESPONSE error (same i18n key as Auto-itemize invoices from Paperless OCR documents #1547 AC 12) with a Retry button.
10. Given I navigate away and back to the page for the same invoice/document, when the page remounts, then the LLM dry-run runs again from scratch — no per-document persistence of prior LLM output, no draft state, no cached suggestions.
11. Given the dry-run returns { lines: [] }, when the page renders, then it shows an empty-state message "No line items detected" with a Cancel button that returns to invoice detail.

Group 3 — Page layout and document preview

12. Given the dry-run resolves successfully, when the page renders, then the layout includes a document preview (image/PDF render of the underlying Paperless document) alongside the editable form. The preview reuses the existing DocumentDetailPanel (or its underlying rendering component) used by the "Details" button — not a parallel implementation.
13. Given the page renders on a desktop viewport, when I view it, then the document preview and the editable form are presented side-by-side. On smaller viewports the layout MAY stack (mobile-friendly), but the preview must remain accessible.

Group 4 — Editable invoice metadata with LLM suggestions

14. Given the dry-run response includes a suggested value for an invoice-level field (currency, total amount, invoice date, due date, vendor name — whichever the LLM proposes) that differs from the value currently stored on the invoice, when the page renders, then an "LLM suggested {{value}}" badge appears next to that field with a one-click "Apply" affordance that copies the suggestion into the field.
15. Given the LLM's suggested value matches the current stored value (or the LLM did not suggest a value), when the page renders, then no badge is shown for that field.
16. Given the page is rendered (regardless of LLM suggestions), when I focus any invoice metadata field, then it is freely editable — the user always has manual override.
17. Given I click "Apply" on a suggestion badge, when the click is handled, then the field value updates to the suggested value, the badge disappears, and standard field validation runs.

Group 5 — Per-row editing and budget-line linking (reuses existing two-step picker)

18. Given the dry-run resolves with N lines, when the page renders, then each line appears as an editable row with these fields: description, quantity, unit, unitPrice, totalAmount, includesVat, vatRate. The same fields and validation rules as the current AutoItemizePreviewModal row editor apply.
19. Given an extracted row, when I open its budget-line picker, then the picker reuses the same components and logic as the two-step picker in InvoiceBudgetLinesSection.tsx (today: type select → work item / household item → search existing OR create inline via BudgetLineForm). This is mandatory — a parallel implementation is not acceptable.
20. Given the budget-line picker, when I pick an existing work-item or household-item budget line, then on save the auto-itemized row is linked to that existing budget line (no new work_item_budgets / household_item_budgets row is created — only an invoice_budget_lines junction row).
21. Given the budget-line picker, when I choose "Create new" and fill the inline BudgetLineForm, then on save a new budget line is created (with origin = 'auto', parent work-item / household-item assignment per the picker) AND linked to the invoice via invoice_budget_lines.
22. Given each row, when I view it, then an include/exclude checkbox controls whether that row participates in save (same behavior as the current modal).
23. Given the rows table, when I view it, then a mode selector (append / replace) controls whether existing auto-extracted lines on the invoice are kept or removed on save — semantics identical to Auto-itemize invoices from Paperless OCR documents #1547 AC 8-9 (replace removes only origin = 'auto' rows; origin = 'manual' lines are preserved).
24. Given the rows table, when the included rows' Σ totalAmount differs from the invoice total (current or LLM-applied) by > 1%, then a non-blocking variance indicator is shown on the totals row (same threshold as Auto-itemize invoices from Paperless OCR documents #1547 AC 14).

Group 6 — Save and cancel semantics

25. Given I click Save, when the request(s) complete successfully, then invoice metadata is updated (if changed), included rows are created/linked as budget lines, any inline-created work items / household items are created, append/replace semantics are honored, and the app navigates back to /budget/invoices/:invoiceId (the invoice detail page) which reflects the new state.
26. Given I click Save and the backend returns an error (e.g., ITEMIZED_SUM_EXCEEDS_INVOICE, validation error, transient 5xx), when the response lands, then the page stays mounted, an inline error banner appears, all user edits (rows, metadata, include/exclude state, mode selector) are preserved, and the user can retry without re-running the LLM.
27. Given I click Cancel, when the click is handled, then the app navigates back to /budget/invoices/:invoiceId without saving any changes (no metadata update, no budget-line creation). If the user has unsaved edits, a confirmation prompt is shown (standard "discard changes?" pattern).

Group 7 — Deletion of obsolete components

28. Given this story is merged, when the diff is reviewed, then client/src/components/budget/AutoItemizePreviewModal.tsx is deleted.
29. Given this story is merged, when the diff is reviewed, then client/src/components/budget/DocumentPickerModal.tsx is deleted (the per-document trigger on LinkedDocumentCard removes the need for a multi-document picker — the user picks which document to itemize by clicking that document's card).
30. Given this story is merged, when I view InvoiceBudgetLinesSection.tsx, then the "Auto-itemize" button (currently lines 917-936) and all wiring for the old picker/preview modal are removed; the section is back to "+ Add Itemization" as the sole header action.
31. Given this story is merged, when I view client/src/i18n/en/budget.json and client/src/i18n/de/budget.json, then orphaned keys for the deleted modals (autoItemize.modalTitle, autoItemize.docPickerTitle, etc.) are removed and any new keys for the dedicated page are added under a clear namespace (translator owns DE).

Out-of-Scope

• Backend LLM extraction logic is NOT modified. server/src/services/invoiceAutoItemizeService.ts and the OpenAI-compatible gateway from BudgetExtractionService with OpenAI-compatible LLM gateway #1546 stay untouched.
• Per-document persistence of LLM output is NOT introduced. Each visit re-runs the dry-run. Saving still creates persistent budget lines + invoice metadata changes; only the LLM's proposed output is ephemeral.
• Background / async extraction. Same as Auto-itemize invoices from Paperless OCR documents #1547 out-of-scope: still synchronous with a spinner.
• Vision / binary PDF input. Out of scope.
• New confidence-level inference. Auto-extracted lines still get confidence = 'invoice' (same as Auto-itemize invoices from Paperless OCR documents #1547).
• Bulk multi-document itemize. One document per page visit. (If multiple linked documents need itemizing, the user clicks "Itemize" on each in turn.)

Open Questions (flag to product-architect)

1. Atomic save endpoint vs two calls. The current POST /api/invoices/:invoiceId/auto-itemize (commit mode, dryRun: false) creates budget lines but does NOT update invoice metadata. The new page lets the user edit metadata (currency, total, dates, vendor) alongside line items. Options:
   • (a) Two sequential client calls — PATCH /api/invoices/:invoiceId (metadata) then POST /api/invoices/:invoiceId/auto-itemize (commit). Risk: partial-success state if the second call fails.
   • (b) New atomic endpoint that accepts both metadata patch + line items in one transaction.
   • (c) Extend the existing POST /api/invoices/:invoiceId/auto-itemize commit payload with an optional invoicePatch field.
   • Recommend (b) or (c) to avoid the partial-success failure mode in AC 2.3: Standardized API Error Handling #26, but defer to architect.
2. Route shape. Suggest /budget/invoices/:invoiceId/auto-itemize?documentId=N. Architect to confirm vs /budget/invoices/:invoiceId/documents/:documentId/auto-itemize (RESTful path-only) or another convention consistent with the existing React Router layout.
3. Inline-created work items / household items. When a user uses the per-row picker to create a new work item or household item inline (Group 5 AC 21), is that creation committed eagerly (separate API call on inline-form submit, same as today's BudgetLineForm behavior) or batched into the save? Today's behavior is eager creation — likely keep that, but confirm.
4. Document preview component reuse. Spec calls for reusing DocumentDetailPanel. Architect to confirm that component is suitable for the side-by-side preview context (vs. needing a new layout variant) — if a new variant is needed, that's an additional small component spec but not a redesign.
5. Vendor field on invoice metadata. Invoice metadata edit includes vendor. Vendors are a managed entity (FK to vendors table). LLM-suggested vendor name needs a resolution strategy: match by name → fuzzy match → "create new vendor" inline? Could be deferred to a follow-up if too large, in which case vendor is read-only on this page.

Notes

• Parent Epic Auto-itemize invoices from Paperless OCR documents #1547 is CLOSED but remains the correct umbrella for the auto-itemize feature. This redesign is a UX iteration on the shipped feature, not a separate epic.
• No new backend extraction logic. The dev-team-lead should not route any spec to add LLM-related code.
• Test authorship: all unit, integration, and E2E tests written by qa-integration-tester / e2e-test-engineer per CLAUDE.md.
• Translator owns DE keys for any new i18n entries (and removal of orphaned keys per AC 31).
• Shared component policy: the per-row budget-line picker must reuse WorkItemPicker / HouseholdItemPicker / BudgetLineForm exactly. The "Details" rename on LinkedDocumentCard is a single i18n key change — keep all existing behavior.

Existing implementation reference (file:line)

• client/src/pages/InvoiceDetailPage/InvoiceBudgetLinesSection.tsx:917-936 — current auto-itemize button to remove
• client/src/components/budget/AutoItemizePreviewModal.tsx — to be deleted
• client/src/components/budget/DocumentPickerModal.tsx — to be deleted
• client/src/components/documents/LinkedDocumentCard.tsx:74-82 — "View" button to rename + add "Itemize" sibling
• client/src/components/documents/LinkedDocumentsSection.tsx:336-344 — existing DocumentDetailPanel rendering pattern (reuse on new page)
• client/src/pages/InvoiceDetailPage/InvoiceBudgetLinesSection.tsx:1154+ — two-step picker (WorkItemPicker / HouseholdItemPicker + inline BudgetLineForm create) — reuse this
• server/src/routes/invoiceAutoItemize.ts — backend route (reuse, possibly extend per Open Question 1)
• server/src/services/invoiceAutoItemizeService.ts — extraction service (DO NOT modify)
• shared/src/types/invoiceAutoItemize.ts — request/response types (may need extension per Open Question 1)
• shared/src/types/config.ts — AppConfigResponse.autoItemizeEnabled (already gates visibility)

[steilerDev]

[product-architect]

Resolutions for the five architectural questions on the auto-itemize redesign. Each decision below is binding for the implementation spec.

1. Atomic save vs two sequential calls

Decision: Option A — extend POST /api/invoices/:invoiceId/auto-itemize commit payload with an optional invoicePatch field; server applies the patch then creates lines inside one DB transaction.

Rationale:

• AC 2.3: Standardized API Error Handling #26 requires that a backend failure leaves the user able to retry without losing edits. Two sequential calls (Option B) introduce a partial-success window where the metadata patch lands but line creation fails — the page would have to detect and roll back the patch client-side, which is fragile and security-sensitive.
• A new dedicated endpoint (Option C) is unjustified surface area: the payload is a natural extension of the commit-mode shape, the auth/validation flow is identical, and we keep one route for security-engineer to audit.
• Drizzle's db.transaction() already wraps the existing line creation logic; folding a thin updateInvoice call into the same transaction is a minimal, low-risk change.

invoicePatch is optional — when omitted, the commit behaves exactly as today. The patch surface mirrors UpdateInvoiceRequest minus status (status changes are out of scope on this page).

2. Frontend route shape

Decision: /budget/invoices/:invoiceId/auto-itemize/:documentId (path-only, no query string).

Rationale:

• Consistent with the existing nested-path convention in App.tsx (/project/work-items/:id, /budget/invoices/:id, /project/household-items/:id/edit). Every other detail/sub-page in the app uses path params.
• :documentId here is a Paperless document id — that's already true everywhere else in the app (PaperlessDocumentSearchResult.id is the Paperless id). The route name documentId is unambiguous because the route is scoped to a Paperless context (Itemize button is on a LinkedDocumentCard).
• Path-based makes the page a first-class navigation target (back/forward, browser history, bookmarkable for debugging) without us having to manage query-string parsing.
• Rejecting /invoices/:invoiceId/itemize/:documentId because invoice routes live under /budget/ in this app.

3. Vendor resolution

Decision: Option C — out of scope for this story. Vendor is read-only on the auto-itemize page; the LLM-suggested vendorName is displayed as a non-actionable hint only. User changes vendor via the existing invoice-edit flow.

Rationale:

• Vendor changes carry side effects (the invoice's vendorId FK, the relationship to work_item_vendors, audit trail in the diary feed) that deserve a deliberate decision, not an inline auto-create driven by an LLM string.
• PATCH /api/vendors/:vendorId/invoices/:invoiceId deliberately does not accept vendorId in the body today — changing vendor is a "move the invoice to a different vendor namespace" operation, not a field edit. Re-architecting that for this story would balloon scope.
• The existing PO spec already lists this as a deferral candidate. Taking the safe path keeps the story scoped to presentation-layer rework.
• Follow-up story can introduce a structured POST /api/invoices/:invoiceId/move-vendor or a vendor-resolver service when there's a real product decision to anchor it.

vendorPatch is therefore NOT part of the invoicePatch payload. invoicePatch covers: invoiceNumber, amount, date, dueDate, notes only.

4. Inline parent creation atomicity

Decision: Option A — eager per-row creation of new work items / household items, as the user fills the inline BudgetLineForm. Save then references existing IDs in invoicePatch + lines.

Rationale:

• Matches today's BudgetLineForm behavior in InvoiceBudgetLinesSection.tsx. Reuse policy in AC build(deps): Bump github/codeql-action from 3 to 4 #19/build(deps): Bump actions/checkout from 4 to 6 #21 is unambiguous: the per-row picker is reused, including its create-inline submit flow. Changing that to deferred batched create would be a parallel implementation of BudgetLineForm.
• Server-side, batching new work-item/household-item creates into a single auto-itemize transaction would require shoehorning entity creation into a route whose contract is "itemize an invoice" — that's a layering smell and the transaction would touch four+ tables in surprising ways.
• The cost of eager creates: if the user abandons the page, a few orphan work items/household items may exist. This is identical to today's behavior on the manual flow and is acceptable. Orphans are user-visible and deletable.
• Save remains atomic for the parts that matter: the invoicePatch + the invoice_budget_lines (and work_item_budgets for origin='auto' rows) creation. Inline-created parents already exist by then.

5. DocumentDetailPanel reuse for side-by-side preview

Decision: Reuse DocumentDetailPanel for the preview pane, with one new optional prop. Do NOT build a parallel doc-preview component.

Inspection of client/src/components/documents/DocumentDetailPanel.tsx and .module.css:

• The panel already renders thumbnail + metadata + content snippet + "View in Paperless" link — exactly what the AC EPIC-11: CI/CD Infrastructure with Semantic Release #12 preview pane needs.
• Required changes:
  • Add an optional variant?: 'inline' | 'sidebyside' prop (default 'inline'). The 'sidebyside' variant removes the onClose button and applies a CSS class that drops the grid-column: 1 / -1 constraint and enables vertical scroll for tall content. The onClose callback becomes optional when variant === 'sidebyside'.
  • Wrap in a panel container on the new page that scrolls independently of the form (sticky preview behavior is a UX concern, handled in the consuming page's CSS).
• The 200px thumbnail width is sufficient for the side-by-side preview's spec (the spec calls for a verifying preview, not a full PDF reader). For a full PDF viewer, users follow the "View in Paperless" external link the panel already provides.
• No new component, no parallel implementation — DocumentDetailPanel stays the single source of truth for Paperless document presentation.

---

Spec impact (for dev-team-lead)

Backend (server/):

• Extend shared/src/types/invoiceAutoItemize.ts AutoItemizeRequest with an optional invoicePatch?: { invoiceNumber?, amount?, date?, dueDate?, notes? } field. Mirror UpdateInvoiceRequest shape minus status.
• Extend server/src/routes/invoiceAutoItemize.ts JSON schema to allow invoicePatch (additionalProperties: false; minProperties: 1 when present).
• Extend server/src/services/invoiceAutoItemizeService.ts commit branch: when body.invoicePatch is present, call into invoiceService.updateInvoice inside the existing db.transaction(), BEFORE line insertion. The transaction must roll back the patch if line insertion fails (Drizzle handles this).
• invoiceService.updateInvoice signature already returns the updated invoice — no service change beyond invocation. Vendor is not patchable; reject any vendorId field in invoicePatch at the schema level (it's already not allowed).
• Diary auto-event for invoice update (existing onInvoiceUpdated if any) must fire on patch — match existing PATCH endpoint behavior.

Frontend (client/):

• New page at /budget/invoices/:invoiceId/auto-itemize/:documentId. Register in App.tsx under the /budget route group.
• New page component (InvoiceAutoItemizePage.tsx) — auto-runs dry-run on mount, side-by-side layout, form with LLM-suggestion badges on invoice metadata fields.
• Reuse DocumentDetailPanel with new variant: 'sidebyside' prop. Add the prop and matching CSS class in DocumentDetailPanel.module.css. The new variant skips onClose rendering and removes the grid-column: 1 / -1 constraint.
• Reuse the two-step picker from InvoiceBudgetLinesSection.tsx lines 1154+ as a shared sub-component — extract if not already extracted, do not parallel-implement (AC build(deps): Bump github/codeql-action from 3 to 4 #19).
• Inline-created work items / household items remain eager (today's behavior).
• Vendor field is read-only on this page — render LLM-suggested vendor name (if extracted) as a hint, but no "Apply" affordance. AC 11.2: Automated Versioning with Semantic Release #14's apply-badge applies only to: amount (total), date, dueDate. currency is global config, not per-invoice.
• Add the new page route, the "Itemize" button on LinkedDocumentCard (gated on entityType === 'invoice' && config.autoItemizeEnabled), and remove the old auto-itemize button from InvoiceBudgetLinesSection.tsx.
• Delete AutoItemizePreviewModal.tsx and DocumentPickerModal.tsx.

Shared types (shared/):

• AutoItemizeRequest.invoicePatch?: InvoicePatchForAutoItemize — define InvoicePatchForAutoItemize as a new exported type (subset of UpdateInvoiceRequest).

Tests (qa-integration-tester + e2e-test-engineer):

• Integration: commit with invoicePatch only (no lines edits), with both patch + lines, with invalid patch (rejected at schema), and rollback semantics (lines fail → patch not persisted).
• E2E: navigate to new route, verify auto-run dry-run, edit a row + apply a metadata suggestion + Save, verify back-navigation lands on /budget/invoices/:invoiceId with the new state.

Wiki updates (product-architect, in this PR):

• wiki/API-Contract.md — POST /api/invoices/:invoiceId/auto-itemize updated to document the new optional invoicePatch field, its transactional semantics, and the rollback contract.
• No schema change; no Schema.md update needed.
• No new ADR — this is an incremental extension of an existing endpoint, not a new architectural pattern. ADR-018 (junction tables) and the existing auto-itemize design remain authoritative.

[steilerDev]

[ux-designer]

Visual Specification — Auto-Itemize UX Redesign (Story #1564)

Token source: client/src/styles/tokens.css | Reference components: LinkedDocumentCard, DocumentDetailPanel, AutoItemizePreviewModal

---

A. LinkedDocumentCard — Button Row Redesign

Current state (from LinkedDocumentCard.tsx / .module.css)

The existing .actions strip holds three controls: a text viewButton (flex: 1, left-aligned text), an openLink icon anchor (↗), and an unlinkButton icon (✕). The view button already uses onView → this maps to the new "Details" function.

Proposed button order

Left → right within .actions:

Slot	Button	Variant	Visibility
1 (flex: 1)	Details (formerly "View")	Ghost text, color: var(--color-primary)	When hasDocument
2	Itemize	Secondary outlined (border: 1px solid var(--color-primary))	When hasDocument && autoItemizeEnabled
3	Open in Paperless	Icon-only ↗	When hasDocument && paperlessBaseUrl
4	Unlink	Icon-only ✕	Always

"Details" keeps flex: 1 to absorb leftover space. "Itemize" is flex-shrink: 0. Icon buttons ("Open in Paperless", "Unlink") remain flex-shrink: 0 as today.

"Itemize" button visual treatment

Use a secondary/outlined variant — not a full primary fill — because it is an optional action on a card that already has a primary text action ("Details"). Reuse the existing outline button pattern from shared.module.css.

background: transparent
color: var(--color-primary)
border: 1px solid var(--color-primary)
border-radius: var(--radius-md)
padding: var(--spacing-1-5) var(--spacing-3)
font-size: var(--font-size-xs)
font-weight: var(--font-weight-medium)
transition: var(--transition-button-border)

Hover: background: var(--color-primary-bg); border-color: var(--color-primary-hover)
Focus-visible: box-shadow: var(--shadow-focus-subtle)

Icon: Use the Unicode glyph ✨ (U+2728) or ⚡ (U+26A1) as a leading icon before the "Itemize" label text. Of these, ⚡ is more universally legible at var(--font-size-xs). Mark aria-hidden="true" on the glyph <span> so the button's visible label "Itemize" reads cleanly. Do not use an icon-only button for "Itemize" — the concept is not universally understood from iconography alone.

If the project's SVG icon set gains a "sparkle" or "wand" icon, prefer that with aria-hidden="true" 24×24 inline SVG over the glyph.

Visibility and spacing

The "Itemize" button must use display: none when !autoItemizeEnabled — not visibility: hidden. This prevents it from occupying space in the flex row and avoids a gap between "Details" and the icon buttons when the feature is off.

Disabled state when link.document === null

When hasDocument is false, the entire .actions strip contains only the Unlink button. The Itemize button is simply absent (not rendered). Do not render a disabled Itemize button for missing documents.

Token references (no changes needed to existing button tokens)

• .actions background: var(--color-bg-secondary) — unchanged
• .actions border-top: 1px solid var(--color-border) — unchanged
• Itemize border color: var(--color-primary) → dark mode auto-resolves to var(--color-blue-400)

---

B. New Auto-Itemize Page — /budget/invoices/:invoiceId/auto-itemize/:documentId

B1. Page-Level Header

Structure: a sticky page header bar (position: sticky; top: 0; z-index: var(--z-dropdown)) containing breadcrumb + title + primary actions.

background: var(--color-bg-primary)
border-bottom: 1px solid var(--color-border)
padding: var(--spacing-3) var(--spacing-6)
display: flex; align-items: center; gap: var(--spacing-4)

Elements left → right:

1. Breadcrumb back link: ← Invoice #NNN — font-size: var(--font-size-sm), color: var(--color-primary), text link (no button styling needed).
2. Page title (flex: 1): "Itemize Document" — font-size: var(--font-size-xl), font-weight: var(--font-weight-semibold), color: var(--color-text-primary).
3. Cancel button: secondary outlined — color: var(--color-text-secondary), border: 1px solid var(--color-border-strong). Triggers dirty-state guard.
4. Save button: primary filled — background: var(--color-primary), color: var(--color-primary-text). Disabled until LLM result arrives and at least one row is included.

Save disabled state: opacity: 0.5; cursor: not-allowed — use disabled attribute which carries color: var(--color-text-disabled) automatically via the existing global button reset.

Header is sticky — the two-column body below scrolls independently. This keeps Save reachable without scrolling.

B2. Loading State — "Analyzing…"

The page auto-fires the LLM dry-run on mount. During loading:

• Render the sticky header (Save + Cancel both disabled with disabled attribute).
• Left column: render the DocumentDetailPanel normally — document preview is available immediately from the URL params.
• Right column: replace the form with a centered loading treatment:

display: flex
flex-direction: column
align-items: center
justify-content: center
gap: var(--spacing-4)
min-height: 320px

Inside the loading region:

• A <Skeleton lines={5} widths={['100%', '80%', '100%', '60%', '40%']} loadingLabel="Analyzing document" /> for the table area.
• Below the skeleton, a caption paragraph: font-size: var(--font-size-sm), color: var(--color-text-muted), text-align: center — text: t('autoItemize.analyzing').
• No spinner separate from Skeleton — the shimmer animation communicates activity.

What stays interactive during loading: nothing in the form. The document preview panel (left column) remains interactive (scrollable, "Open in Paperless" link works). Both header buttons are disabled.

B3. Error State

LLM errors (network failure, malformed response, timeout) replace the right column's skeleton with a <FormError message={...} variant="banner" /> component plus a "Retry" button below it.

display: flex
flex-direction: column
align-items: center
gap: var(--spacing-4)
padding: var(--spacing-8) var(--spacing-6)

Retry button: primary outlined variant. After retry, return to loading skeleton.

The <FormError> banner already uses role="alert" — screen readers will announce the error automatically. No additional live region needed.

B4. Side-by-Side Layout

.pageBody {
  display: grid;
  grid-template-columns: 1fr 1fr;  /* 50/50 */
  gap: var(--spacing-6);
  padding: var(--spacing-6);
  min-height: calc(100vh - [header height]);
  align-items: start;
}

The 50/50 split is preferred over 40/60. Document preview is content the user actively references while editing — equal weight respects that. The preview column does not need a dominant share because it is read-only; the form column handles all interaction.

Left column (preview): Renders <DocumentDetailPanel variant="sidebyside" />. The sidebyside variant:

• Removes the close button (no onClose prop needed, or conditionally rendered by variant).
• Removes grid-column: 1 / -1 from .panel — the existing grid-column: 1 / -1 in DocumentDetailPanel.module.css is scoped to the .panel root; the new variant drops this rule.
• Adds position: sticky; top: [header-height]; max-height: calc(100vh - [header-height]); overflow-y: auto so the preview scrolls independently within the viewport.
• Background stays var(--color-bg-secondary), border 1px solid var(--color-border), border-radius: var(--radius-lg).

Thumb column within the panel: for sidebyside variant, constrain thumbnail to max-width: 240px (up from 200px — more space available) and use the full content grid (unchanged).

Right column (form): Scrolls with the page, not sticky. No overflow constraint on this column.

Gap: var(--spacing-6) (24px) between columns.

Tablet (768–1023px): Reduce column split to minmax(0, 1fr) minmax(0, 1fr) — same 50/50 but columns are narrower. Below ~860px the preview panel becomes cramped; collapse to single column at this threshold using grid-template-columns: 1fr. Use @media (max-width: 860px) for the stack breakpoint (not the canonical 768px), since the preview + form at 50/50 on narrow tablet is unworkable.

Mobile (<768px): Single column. Form first, preview second — the form is the primary task; the preview is reference material. Users completing the form benefit from having inputs immediately in view on load without scrolling past the preview.

B5. Form Region Anatomy (right column)

Top-to-bottom within the form column:

1. Metadata block — invoice fields section
2. Mode selector — append / replace radio group
3. Line item table — editable rows with include/exclude
4. Totals row with variance indicator

Metadata block

A card inset: background: var(--color-bg-secondary); border: 1px solid var(--color-border); border-radius: var(--radius-lg); padding: var(--spacing-4).

Fields: Total Amount, Invoice Date, Due Date, Currency (editable). Vendor (read-only hint).

Each field row: display: grid; grid-template-columns: 1fr auto; align-items: center; gap: var(--spacing-2) — input on the left, LLM suggestion badge on the right (described below). gap: var(--spacing-3) between field rows.

Vendor row: color: var(--color-text-muted); font-size: var(--font-size-sm) — not an input, just <p> text with the label in var(--color-text-secondary).

LLM Suggestion Badge

Appears only when the LLM proposed a value different from the stored value. Placement: to the right of the input on the same baseline.

Visual treatment — inline pill:

display: inline-flex
align-items: center
gap: var(--spacing-1-5)
padding: var(--spacing-0-5) var(--spacing-2)
background: var(--color-primary-bg)
color: var(--color-primary-badge-text)
border-radius: var(--radius-full)
font-size: var(--font-size-xs)
font-weight: var(--font-weight-medium)
white-space: nowrap

Structure: [✨ Suggested: {value}] [Apply]

The "Apply" affordance inside the badge: a small text button with font-size: var(--font-size-xs), font-weight: var(--font-weight-semibold), color: var(--color-primary), background: none; border: none; cursor: pointer; padding: var(--spacing-0-5) var(--spacing-1), border-radius: var(--radius-sm), text-decoration: underline.

Hover on Apply: color: var(--color-primary-hover).
Focus-visible on Apply: box-shadow: var(--shadow-focus-subtle).

On narrow mobile where the badge cannot fit on the same line as the input, wrap to a second line: flex-wrap: wrap on the field row container.

Dark mode: var(--color-primary-bg) resolves to rgba(59,130,246,0.15) in dark mode; var(--color-primary-badge-text) resolves to var(--color-blue-300) — no contrast violations. The "Suggested: {value}" text reads #93c5fd on a near-transparent blue tint against the dark surface — passes WCAG AA (contrast approximately 5.2:1 on --color-bg-primary dark #1a1a2e).

Mode Selector

Reuse the existing pattern from AutoItemizePreviewModal.module.css directly:

• <fieldset> with border: none; padding: 0; margin: 0
• <legend> with .modeLegend class
• .modeOptions flex row, two <label class=modeOption> wrapping <input type="radio">

The mode selector sits between the metadata block and the table, with margin-top: var(--spacing-4).

Line Item Table

Reuse the .table, .table th, .table td, .rowExcluded patterns from AutoItemizePreviewModal.module.css exactly — this is a page, not a modal, but the visual language should be continuous.

New column: "Assign To" — added between tdUnit and tdUnitPrice. Width: 20% on desktop. Contains the two-step parent picker (WorkItemPicker / HouseholdItemPicker + inline BudgetLineForm). This column is the widest cell and will drive row height. On mobile, move to the stacked card layout below.

Column widths (desktop, total = 100%):

• Include (checkbox): 3rem fixed
• Description: 28%
• Qty: 8%
• Unit: 7%
• Assign To: 20%
• Unit Price: 12%
• Total: 12%
• VAT: 10%

Inputs within cells: existing pattern from AutoItemizePreviewModal.module.css (font-family: 'Monaco', 'Courier', monospace; font-size: var(--font-size-xs); width: 100%; box-sizing: border-box).

VAT fields (includesVat checkbox + vatRate input): Pair them in a single td as a flex row — checkbox + "%" rate input side by side. display: flex; align-items: center; gap: var(--spacing-1).

Row height: use vertical-align: top; padding-top: var(--spacing-2) when the picker is expanded inline (BudgetLineForm opens below the picker in the same cell). The row height grows naturally.

Excluded row: .rowExcluded — opacity: 0.6; background-color: var(--color-bg-secondary) — unchanged from modal pattern. Inputs in an excluded row should be disabled to prevent accidental editing.

Totals Row

Reuse .totalsRow, .totalsLabel, .totalMatch, .totalWarning, .totalDanger from AutoItemizePreviewModal.module.css.

Variance indicator: Extends the existing .totalWarning / .totalDanger pattern with a text label (not color-only):

Deviation	Color token	Text indicator
≤1%	var(--color-success-text-on-light)	"✓ Matches invoice total"
1–5%	var(--color-warning-text-on-light)	"⚠ {amount} difference"
>5%	var(--color-danger-text-on-light)	"✕ {amount} difference"

The indicator text sits in the totals row's rightmost cell, below the computed total value, in font-size: var(--font-size-xs). The glyph (✓, ⚠, ✕) is aria-hidden="true" — the full text communicates the meaning to screen readers.

Totals row: font-weight: var(--font-weight-semibold), background-color: var(--color-bg-secondary), border-top: 2px solid var(--color-border-strong).

Mobile row layout (cards): Below 640px, switch each table row to a card layout. Each row becomes:

background: var(--color-bg-primary)
border: 1px solid var(--color-border)
border-radius: var(--radius-lg)
padding: var(--spacing-3)
margin-bottom: var(--spacing-2)

Within the card: a top bar with the include checkbox (left), description input (flex: 1), and row total (right). Below that: a two-column sub-grid for Qty/Unit and UnitPrice/VAT. "Assign To" picker spans full width below the sub-grid. This pattern is consistent with the BudgetLineCard mobile treatment.

B6. Dirty-State Cancel Confirmation

Use the existing <Modal> shared component (not window.confirm()). Native browser confirm() is synchronous, inaccessible (cannot be styled, no screen reader role guarantee), and blocked in some contexts.

Modal title: t('autoItemize.cancelConfirmTitle') — "Discard changes?"
Body: t('autoItemize.cancelConfirmBody') — "You have unsaved changes. Leaving will discard your extracted line items."
Footer buttons: "Keep editing" (secondary, dismisses modal) + "Discard" (danger, navigates back to invoice).

The dirty state is true whenever the user has edited any metadata field or any line item row — tracked in component state. If the form is clean (LLM result not yet modified), Cancel navigates immediately without the confirmation modal.

---

C. Dark Mode Verification

All proposed elements use semantic tokens that have Layer 3 dark mode overrides defined in tokens.css. Specific confirmations:

Element	Token(s)	Dark mode value	Contrast check
LLM suggestion badge bg	--color-primary-bg	rgba(59,130,246,0.15)	Badge text --color-primary-badge-text = #93c5fd on #1a1a2e → ~5.2:1 passes WCAG AA
LLM suggestion badge text	--color-primary-badge-text	var(--color-blue-300) = #93c5fd	✓
Variance: match	--color-success-text-on-light	var(--color-emerald-300) = #6ee7b7 on --color-bg-secondary dark	~5.2:1 ✓
Variance: warning	--color-warning-text-on-light	var(--color-orange-300) = #fdba74 on dark bg	~5.4:1 ✓
Variance: danger	--color-danger-text-on-light	var(--color-red-300) = #fca5a5 on dark bg	~5.1:1 ✓
Loading skeleton	Skeleton component	Uses --color-bg-tertiary / --color-bg-hover — both have dark overrides	✓
Metadata card inset	--color-bg-secondary	var(--color-slate-700) = #16213e	— (not text)
Page sticky header	--color-bg-primary	var(--color-slate-800) = #1a1a2e	— (not text)

No white-on-white or invisible-element risks identified. The DocumentDetailPanel in sidebyside variant inherits all its existing dark mode tokens unchanged.

---

D. Accessibility

D1. "Itemize" button (LinkedDocumentCard)

The button has visible text ("Itemize"), so aria-label is optional. However, because multiple cards may be shown at once, qualify the label:

<button
  aria-label={`${t('documentCard.itemize')}: ${title}`}
  ...
>
  <span aria-hidden="true">⚡</span> {t('documentCard.itemize')}
</button>

This matches the pattern already used on .viewButton and .unlinkButton in the existing component.

D2. "Apply suggestion" affordance

The Apply button must announce the value it will apply:

<button
  type="button"
  aria-label={`${t('autoItemize.applySuggestion')}: ${suggestedValue}`}
  onClick={handleApply}
>
  {t('autoItemize.apply')}
</button>

After applying: use a role="status" aria-atomic="true" live region at the field level to announce t('autoItemize.suggestionApplied', { field: fieldLabel, value: suggestedValue }). This is a polite announcement — do not use role="alert" (too disruptive for a user-initiated action).

The suggestion badge disappears after Apply (the stored value now matches the suggestion), which is a meaningful state change that the live region announcement covers.

D3. Per-row include/exclude checkbox

Each checkbox must have an associated label. Because the checkbox is in a table cell with no visible text label in that cell, use aria-label:

<input
  type="checkbox"
  checked={row.included}
  onChange={...}
  aria-label={`${t('autoItemize.includeRow')}: ${row.description}`}
/>

When toggled, announce the new state via the page's shared live region: t('autoItemize.rowIncluded', { description }) or t('autoItemize.rowExcluded', { description }). Use role="status" aria-atomic="true" (polite). This is the same live region used for suggestion-applied announcements — a single live region per page, placed near the top of the form region.

D4. Variance indicator

The indicator text includes a glyph and descriptive text (e.g., "⚠ 48 € difference") — color is not the sole means of conveying state. The glyph is aria-hidden="true", the text is visible and screen-reader readable. This satisfies WCAG 1.4.1 (Use of Color).

For screen readers: wrap the variance indicator in a role="status" aria-atomic="true" region so it re-announces when the included rows change and the computed total updates.

D5. Skip-to-form link

Because the document preview panel can be tall (scrollable thumbnail + metadata), provide a visually hidden skip link at the top of the page body:

<a href="#itemize-form" className={styles.skipLink}>
  {t('autoItemize.skipToForm')}
</a>

.skipLink: position: absolute; left: -9999px in default state; :focus-visible { position: static; ... } — standard skip link pattern. Make #itemize-form the id of the form column's root <div>.

D6. Keyboard navigation

• Tab order: breadcrumb → Cancel → Save (header) → [skip link if focused] → DocumentDetailPanel → form fields top-to-bottom.
• Within each table row: Tab moves through editable cells left-to-right; the parent picker opens a role="listbox" dropdown (handled by SearchPicker); Escape closes the dropdown without leaving the row.
• Modal confirmation (Cancel dirty): focus moves to "Keep editing" button on open; Escape and backdrop click both dismiss; Tab cycles within modal until dismissed — standard Modal component behavior.

---

E. Responsive Behavior

Breakpoint	Layout	Notes
≥1024px (desktop)	Side-by-side 50/50, sticky preview	Full table with all columns
768–1023px (tablet)	Side-by-side until 860px, then single column	Table columns compress; Assign To column hidden below 900px — move to stacked card mobile layout at 860px
<768px (mobile)	Single column, form first	Table rows render as stacked cards

Justification for "form first" on mobile: the user's goal on this page is to review and confirm the extracted line items. On mobile, the first visible content should be the actionable content (form). The document preview is reference material — users who need it can scroll down or tap the "Open in Paperless" link.

Touch targets: all form inputs, checkboxes, the Apply button, and the per-row picker must meet min-height: 44px; min-width: 44px at max-width: 1023px. Checkboxes achieve this via padding with box-sizing: content-box (same pattern as color swatches in PhotoAnnotator).

---

Component Mapping

UI Element	Shared Component	Props / Variant	Notes
Loading placeholder (form column)	Skeleton	lines={5}, loadingLabel="Analyzing document"	Existing
LLM error display	FormError	variant="banner"	Existing
Cancel confirmation dialog	Modal	danger footer buttons	Existing
Document preview (left column)	DocumentDetailPanel	variant="sidebyside" (new prop)	New variant — no close button, no grid-column override
LLM suggestion badge	New: SuggestionBadge	suggestedValue, fieldLabel, onApply	New shared component — reusable for any LLM-assisted field across the app
Parent picker per row	SearchPicker + BudgetLineForm	Existing patterns	Reuse without redesign per architect decision
Mode selector	Inline <fieldset>	—	Reuse pattern from AutoItemizePreviewModal.module.css exactly
Status/variance live region	role="status" aria-atomic="true"	—	Single shared live region <div> in form column; not a shared component

SuggestionBadge new shared component spec: client/src/components/SuggestionBadge/ — props: suggestedValue: string, fieldLabel: string, onApply: () => void, className?: string. Renders the pill with "Suggested: {value}" text and inline Apply button. Tokens: --color-primary-bg, --color-primary-badge-text, --radius-full. Dark mode: automatic via token cascade. Accessibility: Apply button carries aria-label={t('applySuggestion', { field: fieldLabel, value: suggestedValue })}. This component will serve any future LLM-assisted field across diary, work items, etc.

---

New i18n Keys Required (namespace autoItemize)

Key	Suggested English value
analyzing	"Analyzing document…"
cancelConfirmTitle	"Discard changes?"
cancelConfirmBody	"You have unsaved changes. Leaving will discard your extracted line items."
applySuggestion	"Apply suggested {{field}}: {{value}}"
apply	"Apply"
suggestionApplied	"Applied suggested {{field}}: {{value}}"
includeRow	"Include row: {{description}}"
rowIncluded	"Row included: {{description}}"
rowExcluded	"Row excluded: {{description}}"
skipToForm	"Skip to itemize form"
varianceMatch	"Matches invoice total"
varianceWarning	"{{amount}} difference"
varianceDanger	"{{amount}} difference"

Note: documentCard.itemize key goes in the existing documents namespace, not autoItemize.