From dd489a2018a0c1c0eaa6658a3c62858c0926d45e Mon Sep 17 00:00:00 2001 From: Frank Steiler Date: Wed, 29 Apr 2026 09:05:42 +0200 Subject: [PATCH 01/11] fix(docs): correct broken links in budget overview related pages (#1384) The work-items and household-items links need to point to the index pages, not a non-existent /overview sub-path. Co-authored-by: Frank Steiler Co-authored-by: Claude Sonnet 4.6 --- docs/src/guides/budget/budget-overview.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/src/guides/budget/budget-overview.md b/docs/src/guides/budget/budget-overview.md index 9ed5b102..d031ce11 100644 --- a/docs/src/guides/budget/budget-overview.md +++ b/docs/src/guides/budget/budget-overview.md @@ -120,7 +120,7 @@ If the exported PDF does not match what you see on screen, make sure your browse ## Related Pages -- [Work Items](../work-items/overview) — track progress and link budget lines to construction tasks -- [Household Items](../household-items/overview) — manage furniture and appliance purchases with their own budget lines +- [Work Items](../work-items/) — track progress and link budget lines to construction tasks +- [Household Items](../household-items/) — manage furniture and appliance purchases with their own budget lines - [Financing Sources](financing-sources) — detailed view of each financing source and its allocated lines - [Subsidies](subsidies) — manage subsidy applications and their impact on your budget From 53a1d7724704caf1b3b850ddbb60ea4c9d86a50e Mon Sep 17 00:00:00 2001 From: Frank Steiler Date: Wed, 29 Apr 2026 09:56:31 +0200 Subject: [PATCH 02/11] feat(budget): enforce includes_vat NOT NULL, align VAT behavior across pricing modes (#1385) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * feat(budget): enforce includes_vat NOT NULL, align VAT behavior across pricing modes - Add migration 0031 to backfill NULL includes_vat → true and enforce NOT NULL at DB level - Update Drizzle schema: includesVat is now .notNull().default(true) on both budget tables - Change shared types: BaseBudgetLine.includesVat is now boolean (not boolean | null) - Update JSON schemas in workItemBudgets and householdItemBudgets routes - Fix service converters to use ?? true fallback instead of ?? null - Align direct pricing mode with unit pricing: both modes now apply the VAT multiplier (1 or 1.19) before storing plannedAmount, so the stored value is always gross (VAT-inclusive) - Default includesVat form state to true in both WorkItemDetailPage and HouseholdItemDetailPage - Update all test fixtures to use includesVat: true (was null) Fixes: direct pricing VAT behavior was inconsistent with unit pricing mode. Co-Authored-By: Claude backend-developer (claude-haiku-4-5-20251001) Co-Authored-By: Claude frontend-developer (claude-haiku-4-5-20251001) Co-Authored-By: Claude qa-integration-tester (claude-sonnet-4-6) Co-Authored-By: Claude Sonnet 4.6 * fix(budget): restore CHECK constraints in migration 0031 table recreation Migration 0031 recreated work_item_budgets and household_item_budgets without the original CHECK(planned_amount >= 0) and CHECK(confidence IN (...)) constraints, causing tests that expect these constraints to be enforced to fail. Also switch to explicit column lists in INSERT...SELECT to be safe for existing databases where column order differs from the new table definition. Co-Authored-By: Claude Sonnet 4.6 --------- Co-authored-by: Frank Steiler Co-authored-by: Claude backend-developer (claude-haiku-4-5-20251001) --- .../SourceBudgetLinePanel.test.tsx | 2 +- .../components/budget/BudgetSection.test.tsx | 2 +- .../components/budget/InvoiceGroup.test.tsx | 2 +- client/src/hooks/useBudgetSection.test.ts | 2 +- client/src/hooks/useBudgetSection.ts | 2 + client/src/lib/budgetApiFactory.test.ts | 2 +- client/src/lib/budgetConstants.test.ts | 2 +- client/src/lib/budgetSourcesApi.test.ts | 2 +- .../src/lib/householdItemBudgetsApi.test.ts | 8 +- client/src/lib/workItemBudgetsApi.test.ts | 2 +- ...holdItemDetailPage.budget-unified.test.tsx | 2 +- .../HouseholdItemDetailPage.budget.test.tsx | 2 +- .../HouseholdItemDetailPage.tsx | 9 +- .../WorkItemDetailPage/WorkItemDetailPage.tsx | 9 +- .../migrations/0031_includes_vat_not_null.sql | 92 +++++++++++++++++++ server/src/db/schema.ts | 4 +- server/src/routes/householdItemBudgets.ts | 4 +- server/src/routes/invoiceBudgetLines.test.ts | 4 +- server/src/routes/standaloneInvoices.test.ts | 2 +- server/src/routes/workItemBudgets.ts | 4 +- .../services/householdItemBudgetService.ts | 4 +- .../invoiceBudgetLineService.area.test.ts | 4 +- .../services/invoiceBudgetLineService.test.ts | 4 +- .../services/shared/budgetServiceFactory.ts | 2 +- .../budgetServiceFactory.unitPricing.test.ts | 18 ++-- server/src/services/workItemBudgetService.ts | 4 +- shared/src/types/budget.test.ts | 2 +- shared/src/types/budget.ts | 6 +- 28 files changed, 144 insertions(+), 58 deletions(-) create mode 100644 server/src/db/migrations/0031_includes_vat_not_null.sql diff --git a/client/src/components/SourceBudgetLinePanel/SourceBudgetLinePanel.test.tsx b/client/src/components/SourceBudgetLinePanel/SourceBudgetLinePanel.test.tsx index d582db76..4d748e0c 100644 --- a/client/src/components/SourceBudgetLinePanel/SourceBudgetLinePanel.test.tsx +++ b/client/src/components/SourceBudgetLinePanel/SourceBudgetLinePanel.test.tsx @@ -63,7 +63,7 @@ function makeLine(overrides: Partial = {}): BudgetSource quantity: null, unit: null, unitPrice: null, - includesVat: null, + includesVat: true, createdBy: null, hasClaimedInvoice: false, createdAt: '2026-01-01T00:00:00.000Z', diff --git a/client/src/components/budget/BudgetSection.test.tsx b/client/src/components/budget/BudgetSection.test.tsx index 344fbc30..3ee53a6b 100644 --- a/client/src/components/budget/BudgetSection.test.tsx +++ b/client/src/components/budget/BudgetSection.test.tsx @@ -106,7 +106,7 @@ function buildLine(id: string, invoiceLink: BudgetLineInvoiceLink | null = null) quantity: null, unit: null, unitPrice: null, - includesVat: null, + includesVat: true, }; } diff --git a/client/src/components/budget/InvoiceGroup.test.tsx b/client/src/components/budget/InvoiceGroup.test.tsx index b0501515..71f9a3b3 100644 --- a/client/src/components/budget/InvoiceGroup.test.tsx +++ b/client/src/components/budget/InvoiceGroup.test.tsx @@ -100,7 +100,7 @@ function buildLine(id: string, invoiceLink: BudgetLineInvoiceLink | null = null) quantity: null, unit: null, unitPrice: null, - includesVat: null, + includesVat: true, }; } diff --git a/client/src/hooks/useBudgetSection.test.ts b/client/src/hooks/useBudgetSection.test.ts index f68c123b..d2c6a5c2 100644 --- a/client/src/hooks/useBudgetSection.test.ts +++ b/client/src/hooks/useBudgetSection.test.ts @@ -27,7 +27,7 @@ const makeLine = (overrides: Partial = {}): TestBudgetLine => ({ quantity: null, unit: null, unitPrice: null, - includesVat: null, + includesVat: true, ...overrides, }); diff --git a/client/src/hooks/useBudgetSection.ts b/client/src/hooks/useBudgetSection.ts index 9c0256e4..e3b23374 100644 --- a/client/src/hooks/useBudgetSection.ts +++ b/client/src/hooks/useBudgetSection.ts @@ -193,6 +193,8 @@ export function useBudgetSection( setBudgetFormError('Planned amount must be a valid non-negative number.'); return; } + const multiplier = budgetForm.includesVat ? 1 : 1.19; + plannedAmount = Math.round(plannedAmount * multiplier * 100) / 100; } else { // Unit pricing mode const qty = parseFloat(budgetForm.quantity); diff --git a/client/src/lib/budgetApiFactory.test.ts b/client/src/lib/budgetApiFactory.test.ts index 968b8943..66122297 100644 --- a/client/src/lib/budgetApiFactory.test.ts +++ b/client/src/lib/budgetApiFactory.test.ts @@ -27,7 +27,7 @@ const makeLine = (overrides: Partial = {}): TestBudgetLine => ({ quantity: null, unit: null, unitPrice: null, - includesVat: null, + includesVat: true, ...overrides, }); diff --git a/client/src/lib/budgetConstants.test.ts b/client/src/lib/budgetConstants.test.ts index ddf56352..9f6c923d 100644 --- a/client/src/lib/budgetConstants.test.ts +++ b/client/src/lib/budgetConstants.test.ts @@ -28,7 +28,7 @@ const makeLine = (overrides: Partial = {}): BaseBudgetLine => ({ quantity: null, unit: null, unitPrice: null, - includesVat: null, + includesVat: true, ...overrides, }); diff --git a/client/src/lib/budgetSourcesApi.test.ts b/client/src/lib/budgetSourcesApi.test.ts index 06e229c2..55a1e6e8 100644 --- a/client/src/lib/budgetSourcesApi.test.ts +++ b/client/src/lib/budgetSourcesApi.test.ts @@ -678,7 +678,7 @@ describe('budgetSourcesApi', () => { quantity: null, unit: null, unitPrice: null, - includesVat: null, + includesVat: true, createdBy: null, hasClaimedInvoice: false, createdAt: '2026-01-01T00:00:00.000Z', diff --git a/client/src/lib/householdItemBudgetsApi.test.ts b/client/src/lib/householdItemBudgetsApi.test.ts index 7e277abe..e4850bf4 100644 --- a/client/src/lib/householdItemBudgetsApi.test.ts +++ b/client/src/lib/householdItemBudgetsApi.test.ts @@ -59,7 +59,7 @@ describe('householdItemBudgetsApi', () => { quantity: null, unit: null, unitPrice: null, - includesVat: null, + includesVat: true, }; mockFetch.mockResolvedValueOnce({ @@ -128,7 +128,7 @@ describe('householdItemBudgetsApi', () => { quantity: null, unit: null, unitPrice: null, - includesVat: null, + includesVat: true, }; mockFetch.mockResolvedValueOnce({ @@ -184,7 +184,7 @@ describe('householdItemBudgetsApi', () => { quantity: null, unit: null, unitPrice: null, - includesVat: null, + includesVat: true, }; mockFetch.mockResolvedValueOnce({ @@ -291,7 +291,7 @@ describe('householdItemBudgetsApi', () => { quantity: null, unit: null, unitPrice: null, - includesVat: null, + includesVat: true, }; mockFetch.mockResolvedValueOnce({ diff --git a/client/src/lib/workItemBudgetsApi.test.ts b/client/src/lib/workItemBudgetsApi.test.ts index af9786d6..24b7e60e 100644 --- a/client/src/lib/workItemBudgetsApi.test.ts +++ b/client/src/lib/workItemBudgetsApi.test.ts @@ -36,7 +36,7 @@ describe('workItemBudgetsApi', () => { quantity: null, unit: null, unitPrice: null, - includesVat: null, + includesVat: true, createdBy: null, createdAt: '2026-01-01T00:00:00.000Z', updatedAt: '2026-01-01T00:00:00.000Z', diff --git a/client/src/pages/HouseholdItemDetailPage/HouseholdItemDetailPage.budget-unified.test.tsx b/client/src/pages/HouseholdItemDetailPage/HouseholdItemDetailPage.budget-unified.test.tsx index 62d1f4f7..f7ff5af1 100644 --- a/client/src/pages/HouseholdItemDetailPage/HouseholdItemDetailPage.budget-unified.test.tsx +++ b/client/src/pages/HouseholdItemDetailPage/HouseholdItemDetailPage.budget-unified.test.tsx @@ -314,7 +314,7 @@ describe('HouseholdItemDetailPage — unified Budget section (issue #566)', () = quantity: null, unit: null, unitPrice: null, - includesVat: null, + includesVat: true, ...overrides, }; } diff --git a/client/src/pages/HouseholdItemDetailPage/HouseholdItemDetailPage.budget.test.tsx b/client/src/pages/HouseholdItemDetailPage/HouseholdItemDetailPage.budget.test.tsx index 026d0a08..2d07128f 100644 --- a/client/src/pages/HouseholdItemDetailPage/HouseholdItemDetailPage.budget.test.tsx +++ b/client/src/pages/HouseholdItemDetailPage/HouseholdItemDetailPage.budget.test.tsx @@ -321,7 +321,7 @@ describe('HouseholdItemDetailPage — budget line rendering (bug #436)', () => { quantity: null, unit: null, unitPrice: null, - includesVat: null, + includesVat: true, ...overrides, }; } diff --git a/client/src/pages/HouseholdItemDetailPage/HouseholdItemDetailPage.tsx b/client/src/pages/HouseholdItemDetailPage/HouseholdItemDetailPage.tsx index e9990e64..0eef24fb 100644 --- a/client/src/pages/HouseholdItemDetailPage/HouseholdItemDetailPage.tsx +++ b/client/src/pages/HouseholdItemDetailPage/HouseholdItemDetailPage.tsx @@ -211,21 +211,18 @@ export function HouseholdItemDetailPage() { quantity: line.quantity !== null ? String(line.quantity) : '', unit: line.unit ?? '', unitPrice: line.unitPrice !== null ? String(line.unitPrice) : '', - includesVat: line.quantity !== null ? (line.includesVat ?? true) : false, + includesVat: line.includesVat ?? true, }), toPayload: (form: BudgetLineFormState) => ({ description: form.description.trim() || null, - plannedAmount: - form.pricingMode === 'direct' && form.includesVat - ? Math.round((parseFloat(form.plannedAmount) / 1.19) * 100) / 100 - : parseFloat(form.plannedAmount), + plannedAmount: parseFloat(form.plannedAmount), confidence: form.confidence, budgetSourceId: form.budgetSourceId, vendorId: form.vendorId || null, quantity: form.pricingMode === 'unit' && form.quantity ? parseFloat(form.quantity) : null, unit: form.pricingMode === 'unit' && form.unit ? form.unit : null, unitPrice: form.pricingMode === 'unit' && form.unitPrice ? parseFloat(form.unitPrice) : null, - includesVat: form.pricingMode === 'unit' ? form.includesVat : null, + includesVat: form.includesVat, }), entityId: id ?? '', defaultBudgetSourceId: budgetSources.find((s) => s.isDiscretionary)?.id, diff --git a/client/src/pages/WorkItemDetailPage/WorkItemDetailPage.tsx b/client/src/pages/WorkItemDetailPage/WorkItemDetailPage.tsx index e64d76ed..c5b9f990 100644 --- a/client/src/pages/WorkItemDetailPage/WorkItemDetailPage.tsx +++ b/client/src/pages/WorkItemDetailPage/WorkItemDetailPage.tsx @@ -264,14 +264,11 @@ export default function WorkItemDetailPage() { quantity: line.quantity !== null ? String(line.quantity) : '', unit: line.unit ?? '', unitPrice: line.unitPrice !== null ? String(line.unitPrice) : '', - includesVat: line.quantity !== null ? (line.includesVat ?? true) : false, + includesVat: line.includesVat ?? true, }), toPayload: (form: BudgetLineFormState): CreateWorkItemBudgetRequest => ({ description: form.description.trim() || null, - plannedAmount: - form.pricingMode === 'direct' && form.includesVat - ? Math.round((parseFloat(form.plannedAmount) / 1.19) * 100) / 100 - : parseFloat(form.plannedAmount), + plannedAmount: parseFloat(form.plannedAmount), confidence: form.confidence, budgetCategoryId: form.budgetCategoryId || null, budgetSourceId: form.budgetSourceId, @@ -279,7 +276,7 @@ export default function WorkItemDetailPage() { quantity: form.pricingMode === 'unit' && form.quantity ? parseFloat(form.quantity) : null, unit: form.pricingMode === 'unit' && form.unit ? form.unit : null, unitPrice: form.pricingMode === 'unit' && form.unitPrice ? parseFloat(form.unitPrice) : null, - includesVat: form.pricingMode === 'unit' ? form.includesVat : null, + includesVat: form.includesVat, }), entityId: id ?? '', defaultBudgetSourceId: budgetSources.find((s) => s.isDiscretionary)?.id, diff --git a/server/src/db/migrations/0031_includes_vat_not_null.sql b/server/src/db/migrations/0031_includes_vat_not_null.sql new file mode 100644 index 00000000..7d38865b --- /dev/null +++ b/server/src/db/migrations/0031_includes_vat_not_null.sql @@ -0,0 +1,92 @@ +-- Migration 0031: Make includes_vat NOT NULL DEFAULT 1 +-- Backfills any NULL values to 1 (true) and recreates both budget tables with NOT NULL constraint. +-- Uses explicit column lists in INSERT...SELECT to be safe regardless of column order. +-- Preserves all CHECK constraints from the original table definitions. + +PRAGMA foreign_keys = OFF; + +-- Backfill NULLs before table recreation +UPDATE work_item_budgets SET includes_vat = 1 WHERE includes_vat IS NULL; +UPDATE household_item_budgets SET includes_vat = 1 WHERE includes_vat IS NULL; + +-- Recreate work_item_budgets with includes_vat NOT NULL DEFAULT 1 +CREATE TABLE work_item_budgets_new ( + id TEXT PRIMARY KEY, + work_item_id TEXT NOT NULL REFERENCES work_items(id) ON DELETE CASCADE, + description TEXT, + planned_amount REAL NOT NULL DEFAULT 0 CHECK(planned_amount >= 0), + confidence TEXT NOT NULL DEFAULT 'own_estimate' CHECK(confidence IN ('own_estimate', 'professional_estimate', 'quote', 'invoice')), + budget_category_id TEXT REFERENCES budget_categories(id) ON DELETE SET NULL, + budget_source_id TEXT REFERENCES budget_sources(id) ON DELETE SET NULL, + vendor_id TEXT REFERENCES vendors(id) ON DELETE SET NULL, + created_by TEXT REFERENCES users(id) ON DELETE SET NULL, + created_at TEXT NOT NULL, + updated_at TEXT NOT NULL, + quantity REAL, + unit TEXT, + unit_price REAL, + includes_vat INTEGER NOT NULL DEFAULT 1 +); + +INSERT INTO work_item_budgets_new ( + id, work_item_id, description, planned_amount, confidence, + budget_category_id, budget_source_id, vendor_id, + created_by, created_at, updated_at, + quantity, unit, unit_price, includes_vat +) +SELECT + id, work_item_id, description, planned_amount, confidence, + budget_category_id, budget_source_id, vendor_id, + created_by, created_at, updated_at, + quantity, unit, unit_price, includes_vat +FROM work_item_budgets; + +DROP TABLE work_item_budgets; +ALTER TABLE work_item_budgets_new RENAME TO work_item_budgets; + +CREATE INDEX idx_work_item_budgets_work_item_id ON work_item_budgets(work_item_id); +CREATE INDEX idx_work_item_budgets_vendor_id ON work_item_budgets(vendor_id); +CREATE INDEX idx_work_item_budgets_budget_category_id ON work_item_budgets(budget_category_id); +CREATE INDEX idx_work_item_budgets_budget_source_id ON work_item_budgets(budget_source_id); + +-- Recreate household_item_budgets with includes_vat NOT NULL DEFAULT 1 +CREATE TABLE household_item_budgets_new ( + id TEXT PRIMARY KEY, + household_item_id TEXT NOT NULL REFERENCES household_items(id) ON DELETE CASCADE, + description TEXT, + planned_amount REAL NOT NULL DEFAULT 0 CHECK(planned_amount >= 0), + confidence TEXT NOT NULL DEFAULT 'own_estimate' CHECK(confidence IN ('own_estimate', 'professional_estimate', 'quote', 'invoice')), + budget_category_id TEXT REFERENCES budget_categories(id) ON DELETE SET NULL, + budget_source_id TEXT REFERENCES budget_sources(id) ON DELETE SET NULL, + vendor_id TEXT REFERENCES vendors(id) ON DELETE SET NULL, + created_by TEXT REFERENCES users(id) ON DELETE SET NULL, + created_at TEXT NOT NULL, + updated_at TEXT NOT NULL, + quantity REAL, + unit TEXT, + unit_price REAL, + includes_vat INTEGER NOT NULL DEFAULT 1 +); + +INSERT INTO household_item_budgets_new ( + id, household_item_id, description, planned_amount, confidence, + budget_category_id, budget_source_id, vendor_id, + created_by, created_at, updated_at, + quantity, unit, unit_price, includes_vat +) +SELECT + id, household_item_id, description, planned_amount, confidence, + budget_category_id, budget_source_id, vendor_id, + created_by, created_at, updated_at, + quantity, unit, unit_price, includes_vat +FROM household_item_budgets; + +DROP TABLE household_item_budgets; +ALTER TABLE household_item_budgets_new RENAME TO household_item_budgets; + +CREATE INDEX idx_household_item_budgets_household_item_id ON household_item_budgets(household_item_id); +CREATE INDEX idx_household_item_budgets_vendor_id ON household_item_budgets(vendor_id); +CREATE INDEX idx_household_item_budgets_budget_category_id ON household_item_budgets(budget_category_id); +CREATE INDEX idx_household_item_budgets_budget_source_id ON household_item_budgets(budget_source_id); + +PRAGMA foreign_keys = ON; diff --git a/server/src/db/schema.ts b/server/src/db/schema.ts index 46f0d474..19573341 100644 --- a/server/src/db/schema.ts +++ b/server/src/db/schema.ts @@ -358,7 +358,7 @@ export const workItemBudgets = sqliteTable( quantity: real('quantity'), unit: text('unit'), unitPrice: real('unit_price'), - includesVat: integer('includes_vat', { mode: 'boolean' }), + includesVat: integer('includes_vat', { mode: 'boolean' }).notNull().default(true), createdBy: text('created_by').references(() => users.id, { onDelete: 'set null' }), createdAt: text('created_at').notNull(), updatedAt: text('updated_at').notNull(), @@ -725,7 +725,7 @@ export const householdItemBudgets = sqliteTable( quantity: real('quantity'), unit: text('unit'), unitPrice: real('unit_price'), - includesVat: integer('includes_vat', { mode: 'boolean' }), + includesVat: integer('includes_vat', { mode: 'boolean' }).notNull().default(true), createdBy: text('created_by').references(() => users.id, { onDelete: 'set null' }), createdAt: text('created_at').notNull(), updatedAt: text('updated_at').notNull(), diff --git a/server/src/routes/householdItemBudgets.ts b/server/src/routes/householdItemBudgets.ts index 1b7d3f56..4fece38e 100644 --- a/server/src/routes/householdItemBudgets.ts +++ b/server/src/routes/householdItemBudgets.ts @@ -47,7 +47,7 @@ const createBudgetSchema = { quantity: { type: ['number', 'null'], minimum: 0 }, unit: { type: ['string', 'null'], maxLength: 100 }, unitPrice: { type: ['number', 'null'], minimum: 0 }, - includesVat: { type: ['boolean', 'null'] }, + includesVat: { type: 'boolean' }, }, additionalProperties: false, }, @@ -78,7 +78,7 @@ const updateBudgetSchema = { quantity: { type: ['number', 'null'], minimum: 0 }, unit: { type: ['string', 'null'], maxLength: 100 }, unitPrice: { type: ['number', 'null'], minimum: 0 }, - includesVat: { type: ['boolean', 'null'] }, + includesVat: { type: 'boolean' }, }, additionalProperties: false, }, diff --git a/server/src/routes/invoiceBudgetLines.test.ts b/server/src/routes/invoiceBudgetLines.test.ts index d5953912..914ffbea 100644 --- a/server/src/routes/invoiceBudgetLines.test.ts +++ b/server/src/routes/invoiceBudgetLines.test.ts @@ -134,7 +134,7 @@ describe('Invoice Budget Lines Routes', () => { quantity: null, unit: null, unitPrice: null, - includesVat: null, + includesVat: true, createdBy: null, createdAt: ts, updatedAt: ts, @@ -189,7 +189,7 @@ describe('Invoice Budget Lines Routes', () => { quantity: null, unit: null, unitPrice: null, - includesVat: null, + includesVat: true, createdBy: null, createdAt: ts, updatedAt: ts, diff --git a/server/src/routes/standaloneInvoices.test.ts b/server/src/routes/standaloneInvoices.test.ts index 9481b463..6861f2ce 100644 --- a/server/src/routes/standaloneInvoices.test.ts +++ b/server/src/routes/standaloneInvoices.test.ts @@ -776,7 +776,7 @@ describe('Standalone Invoice Routes', () => { quantity: null, unit: null, unitPrice: null, - includesVat: null, + includesVat: true, createdBy: null, createdAt: ts, updatedAt: ts, diff --git a/server/src/routes/workItemBudgets.ts b/server/src/routes/workItemBudgets.ts index 15a77530..01674b53 100644 --- a/server/src/routes/workItemBudgets.ts +++ b/server/src/routes/workItemBudgets.ts @@ -44,7 +44,7 @@ const createBudgetSchema = { quantity: { type: ['number', 'null'], minimum: 0 }, unit: { type: ['string', 'null'], maxLength: 100 }, unitPrice: { type: ['number', 'null'], minimum: 0 }, - includesVat: { type: ['boolean', 'null'] }, + includesVat: { type: 'boolean' }, }, additionalProperties: false, }, @@ -75,7 +75,7 @@ const updateBudgetSchema = { quantity: { type: ['number', 'null'], minimum: 0 }, unit: { type: ['string', 'null'], maxLength: 100 }, unitPrice: { type: ['number', 'null'], minimum: 0 }, - includesVat: { type: ['boolean', 'null'] }, + includesVat: { type: 'boolean' }, }, additionalProperties: false, }, diff --git a/server/src/services/householdItemBudgetService.ts b/server/src/services/householdItemBudgetService.ts index ceed4e50..086b3fe1 100644 --- a/server/src/services/householdItemBudgetService.ts +++ b/server/src/services/householdItemBudgetService.ts @@ -45,7 +45,7 @@ function toHouseholdItemBudgetLine( quantity: row.quantity ?? null, unit: row.unit ?? null, unitPrice: row.unitPrice ?? null, - includesVat: row.includesVat ?? null, + includesVat: row.includesVat ?? true, createdBy: rel.createdBy, createdAt: row.createdAt, updatedAt: row.updatedAt, @@ -76,7 +76,7 @@ function buildInsertValues( quantity: data.quantity ?? null, unit: data.unit ?? null, unitPrice: data.unitPrice ?? null, - includesVat: data.includesVat ?? null, + includesVat: data.includesVat ?? true, createdBy: userId, }; } diff --git a/server/src/services/invoiceBudgetLineService.area.test.ts b/server/src/services/invoiceBudgetLineService.area.test.ts index 3a69376d..fc573cfe 100644 --- a/server/src/services/invoiceBudgetLineService.area.test.ts +++ b/server/src/services/invoiceBudgetLineService.area.test.ts @@ -149,7 +149,7 @@ describe('invoiceBudgetLineService — parentItemArea enrichment', () => { quantity: null, unit: null, unitPrice: null, - includesVat: null, + includesVat: true, createdBy: null, createdAt: ts, updatedAt: ts, @@ -202,7 +202,7 @@ describe('invoiceBudgetLineService — parentItemArea enrichment', () => { quantity: null, unit: null, unitPrice: null, - includesVat: null, + includesVat: true, createdBy: null, createdAt: ts, updatedAt: ts, diff --git a/server/src/services/invoiceBudgetLineService.test.ts b/server/src/services/invoiceBudgetLineService.test.ts index c1884eee..6f2d5943 100644 --- a/server/src/services/invoiceBudgetLineService.test.ts +++ b/server/src/services/invoiceBudgetLineService.test.ts @@ -116,7 +116,7 @@ describe('Invoice Budget Line Service', () => { quantity: null, unit: null, unitPrice: null, - includesVat: null, + includesVat: true, createdBy: null, createdAt: ts, updatedAt: ts, @@ -174,7 +174,7 @@ describe('Invoice Budget Line Service', () => { quantity: null, unit: null, unitPrice: null, - includesVat: null, + includesVat: true, createdBy: null, createdAt: ts, updatedAt: ts, diff --git a/server/src/services/shared/budgetServiceFactory.ts b/server/src/services/shared/budgetServiceFactory.ts index 744d5aa1..622532e3 100644 --- a/server/src/services/shared/budgetServiceFactory.ts +++ b/server/src/services/shared/budgetServiceFactory.ts @@ -524,7 +524,7 @@ export function createBudgetService< } if ('includesVat' in data) { - updates.includesVat = data.includesVat ?? null; + updates.includesVat = data.includesVat ?? true; } updates.updatedAt = new Date().toISOString(); diff --git a/server/src/services/shared/budgetServiceFactory.unitPricing.test.ts b/server/src/services/shared/budgetServiceFactory.unitPricing.test.ts index 6a873cfd..85f8ddf1 100644 --- a/server/src/services/shared/budgetServiceFactory.unitPricing.test.ts +++ b/server/src/services/shared/budgetServiceFactory.unitPricing.test.ts @@ -124,7 +124,7 @@ describe('budgetServiceFactory — unit pricing fields', () => { expect(result.includesVat).toBe(false); }); - it('returns null for all unit pricing fields when not provided on create', () => { + it('returns null for quantity/unit/unitPrice and true for includesVat when not provided on create', () => { const workItemId = insertWorkItem(); const result = createWorkItemBudget(db, workItemId, 'user-001', { @@ -135,7 +135,7 @@ describe('budgetServiceFactory — unit pricing fields', () => { expect(result.quantity).toBeNull(); expect(result.unit).toBeNull(); expect(result.unitPrice).toBeNull(); - expect(result.includesVat).toBeNull(); + expect(result.includesVat).toBe(true); }); it('updates quantity only, leaving other unit pricing fields unchanged', () => { @@ -160,7 +160,7 @@ describe('budgetServiceFactory — unit pricing fields', () => { expect(updated.includesVat).toBe(true); }); - it('clears all unit pricing fields when explicitly set to null', () => { + it('clears quantity/unit/unitPrice when explicitly set to null; includesVat defaults to true when unset via null', () => { const workItemId = insertWorkItem(); const created = createWorkItemBudget(db, workItemId, 'user-001', { @@ -176,13 +176,12 @@ describe('budgetServiceFactory — unit pricing fields', () => { quantity: null, unit: null, unitPrice: null, - includesVat: null, }); expect(updated.quantity).toBeNull(); expect(updated.unit).toBeNull(); expect(updated.unitPrice).toBeNull(); - expect(updated.includesVat).toBeNull(); + expect(updated.includesVat).toBe(false); }); it('does not touch unit pricing fields when they are absent from update payload', () => { @@ -230,7 +229,7 @@ describe('budgetServiceFactory — unit pricing fields', () => { expect(result.includesVat).toBe(true); }); - it('returns null for all unit pricing fields when not provided on create', () => { + it('returns null for quantity/unit/unitPrice and true for includesVat when not provided on create', () => { const hiId = insertHouseholdItem(); const result = createHouseholdItemBudget(db, hiId, 'user-001', { @@ -241,7 +240,7 @@ describe('budgetServiceFactory — unit pricing fields', () => { expect(result.quantity).toBeNull(); expect(result.unit).toBeNull(); expect(result.unitPrice).toBeNull(); - expect(result.includesVat).toBeNull(); + expect(result.includesVat).toBe(true); }); it('updates quantity only, leaving other unit pricing fields unchanged', () => { @@ -266,7 +265,7 @@ describe('budgetServiceFactory — unit pricing fields', () => { expect(updated.includesVat).toBe(false); }); - it('clears all unit pricing fields when explicitly set to null', () => { + it('clears quantity/unit/unitPrice when explicitly set to null; includesVat retains its value', () => { const hiId = insertHouseholdItem(); const created = createHouseholdItemBudget(db, hiId, 'user-001', { @@ -282,13 +281,12 @@ describe('budgetServiceFactory — unit pricing fields', () => { quantity: null, unit: null, unitPrice: null, - includesVat: null, }); expect(updated.quantity).toBeNull(); expect(updated.unit).toBeNull(); expect(updated.unitPrice).toBeNull(); - expect(updated.includesVat).toBeNull(); + expect(updated.includesVat).toBe(true); }); }); }); diff --git a/server/src/services/workItemBudgetService.ts b/server/src/services/workItemBudgetService.ts index 735e1e79..c0e9633a 100644 --- a/server/src/services/workItemBudgetService.ts +++ b/server/src/services/workItemBudgetService.ts @@ -45,7 +45,7 @@ function toWorkItemBudgetLine( quantity: row.quantity ?? null, unit: row.unit ?? null, unitPrice: row.unitPrice ?? null, - includesVat: row.includesVat ?? null, + includesVat: row.includesVat ?? true, createdBy: rel.createdBy, createdAt: row.createdAt, updatedAt: row.updatedAt, @@ -76,7 +76,7 @@ function buildInsertValues( quantity: data.quantity ?? null, unit: data.unit ?? null, unitPrice: data.unitPrice ?? null, - includesVat: data.includesVat ?? null, + includesVat: data.includesVat ?? true, createdBy: userId, }; } diff --git a/shared/src/types/budget.test.ts b/shared/src/types/budget.test.ts index c4eaa34a..d5f42576 100644 --- a/shared/src/types/budget.test.ts +++ b/shared/src/types/budget.test.ts @@ -52,7 +52,7 @@ const minimalBudgetLine = { quantity: null, unit: null, unitPrice: null, - includesVat: null, + includesVat: true, createdBy: null, createdAt: '2025-01-01T00:00:00Z', updatedAt: '2025-01-01T00:00:00Z', diff --git a/shared/src/types/budget.ts b/shared/src/types/budget.ts index 358ca2aa..1c303d32 100644 --- a/shared/src/types/budget.ts +++ b/shared/src/types/budget.ts @@ -86,7 +86,7 @@ export interface BaseBudgetLine { quantity: number | null; unit: string | null; unitPrice: number | null; - includesVat: boolean | null; + includesVat: boolean; createdBy: UserSummary | null; createdAt: string; updatedAt: string; @@ -106,7 +106,7 @@ export interface CreateBudgetLineRequest { quantity?: number | null; unit?: string | null; unitPrice?: number | null; - includesVat?: boolean | null; + includesVat?: boolean; } /** @@ -124,7 +124,7 @@ export interface UpdateBudgetLineRequest { quantity?: number | null; unit?: string | null; unitPrice?: number | null; - includesVat?: boolean | null; + includesVat?: boolean; } /** From 47a766fce42797453e47e8438a749e3adeed72a3 Mon Sep 17 00:00:00 2001 From: Frank Steiler Date: Wed, 29 Apr 2026 10:51:05 +0200 Subject: [PATCH 03/11] docs: add backup guide and configuration reference (#1386) Documents the built-in backup feature: what gets archived, Docker volume mount setup, scheduled backups via BACKUP_CADENCE, retention policy, and restore steps. Also adds BACKUP_* env vars to the configuration reference with a cross-link to the new guide. Co-authored-by: Frank Steiler Co-authored-by: Claude --- .claude/agent-memory/docs-writer/MEMORY.md | 2 + docs/docusaurus.config.js | 1 + docs/sidebars.js | 1 + docs/src/getting-started/configuration.md | 10 + docs/src/guides/backup/index.md | 229 +++++++++++++++++++++ 5 files changed, 243 insertions(+) create mode 100644 docs/src/guides/backup/index.md diff --git a/.claude/agent-memory/docs-writer/MEMORY.md b/.claude/agent-memory/docs-writer/MEMORY.md index 65f9326d..1ceb4ed0 100644 --- a/.claude/agent-memory/docs-writer/MEMORY.md +++ b/.claude/agent-memory/docs-writer/MEMORY.md @@ -35,6 +35,8 @@ - `guides/household-items/` -- index, creating-editing-items, budget-and-invoices, work-item-linking, delivery-and-dependencies - `guides/diary/` -- index, manual-entries, automatic-events, signatures - `guides/dashboard/` -- index +- `guides/feeds/` -- index, subscribing +- `guides/backup/` -- index (BACKUP_DIR/CADENCE/RETENTION env vars, manual + scheduled backups, restore flow, off-site guidance) -- EPIC-19 - `guides/appearance/` -- dark-mode - `development/` -- index, tech-stack, agentic/overview, agentic/agent-team, agentic/workflow, agentic/setup diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index 8eaac666..70768843 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -88,6 +88,7 @@ const config = { { label: 'Household Items', to: '/guides/household-items' }, { label: 'Documents', to: '/guides/documents' }, { label: 'Diary', to: '/guides/diary' }, + { label: 'Backups', to: '/guides/backup' }, { label: 'Roadmap', to: '/roadmap' }, ], }, diff --git a/docs/sidebars.js b/docs/sidebars.js index e36d51af..7c2a5126 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -93,6 +93,7 @@ const sidebars = { items: ['guides/feeds/subscribing'], }, 'guides/dashboard/index', + 'guides/backup/index', 'guides/appearance/dark-mode', 'roadmap', ], diff --git a/docs/src/getting-started/configuration.md b/docs/src/getting-started/configuration.md index 08676876..4aca320d 100644 --- a/docs/src/getting-started/configuration.md +++ b/docs/src/getting-started/configuration.md @@ -67,6 +67,16 @@ The OIDC callback URL is automatically derived as `/api/auth/oidc/ `PHOTO_STORAGE_PATH` defaults to a `photos` directory alongside your database file. If you use a custom `DATABASE_URL`, the photo directory is created relative to it. Make sure the path is within a persistent Docker volume so photos survive container restarts. ::: +## Backups + +| Variable | Default | Description | +|----------|---------|-------------| +| `BACKUP_DIR` | `/backups` | Directory where backup archives are written. Must be outside the app data directory. | +| `BACKUP_CADENCE` | -- | Cron expression for automatic scheduled backups (e.g., `0 2 * * *` for daily at 2 AM). If unset, only manual backups are available. | +| `BACKUP_RETENTION` | -- | Maximum number of backup archives to keep. The oldest archives are deleted when the limit is exceeded. If unset, backups are kept indefinitely. | + +The backup feature is enabled whenever `BACKUP_DIR` resolves to a directory outside the app data directory -- which is true by default. See [Backups](/guides/backup) for setup, scheduling, and restore instructions. + ## Paperless-ngx (Document Integration) The document integration is automatically enabled when both `PAPERLESS_URL` and `PAPERLESS_API_TOKEN` are set. diff --git a/docs/src/guides/backup/index.md b/docs/src/guides/backup/index.md new file mode 100644 index 00000000..065a81f7 --- /dev/null +++ b/docs/src/guides/backup/index.md @@ -0,0 +1,229 @@ +--- +sidebar_position: 11 +title: Backups +--- + +# Backups + +Cornerstone has a built-in backup feature that snapshots your entire app data directory -- the SQLite database and any associated files like diary photos -- into a single compressed archive. Backups can be created manually from the admin UI or run automatically on a schedule, with optional retention limits to keep the backup directory tidy. + +This guide walks through configuring the backup directory, scheduling automatic backups, and restoring from an archive when you need to roll back. + +## What Gets Backed Up + +A backup is a `tar.gz` archive of the **entire app data directory** -- the same directory that contains your SQLite database file (`cornerstone.db` by default). That means a single archive captures: + +- The SQLite database (work items, budgets, users, vendors, diary entries, etc.) +- Diary photo attachments stored under the data directory +- Any other state Cornerstone keeps next to the database + +Cornerstone uses SQLite's online backup API to snapshot the database safely while it is running, so you do not need to stop the container to take a backup. + +Archives are named with a UTC timestamp: + +``` +cornerstone-backup-2026-04-29T143022Z.tar.gz +``` + +## Configuration + +All backup behaviour is controlled by three environment variables: + +| Variable | Default | Description | +|----------|---------|-------------| +| `BACKUP_DIR` | `/backups` | Directory where backup archives are written. Must be outside the app data directory. | +| `BACKUP_CADENCE` | -- | Cron expression for automatic scheduled backups. If unset, only manual backups are available. | +| `BACKUP_RETENTION` | -- | Maximum number of backup archives to keep. Oldest are deleted when the limit is exceeded. If unset, archives are kept indefinitely. | + +These are also listed alongside the other server settings in [Configuration](/getting-started/configuration#backups). + +:::caution `BACKUP_DIR` must be outside the app data directory +Cornerstone refuses to start if `BACKUP_DIR` is the same as -- or a subdirectory of -- the app data directory (the directory that contains your SQLite database). Storing backups inside the data directory would mean the next backup would also archive the previous backup, ballooning archive size and defeating the purpose. Always mount a separate volume or path for backups. +::: + +## Mounting the Backup Directory + +The default `BACKUP_DIR` is `/backups` inside the container, but that path is only useful if you mount a host directory or named volume to it -- otherwise archives live in the container's writable layer and disappear when the container is recreated. + +### Docker Run + +```bash +docker run -d \ + --name cornerstone \ + -p 3000:3000 \ + -v cornerstone-data:/app/data \ + -v cornerstone-backups:/backups \ + steilerdev/cornerstone:latest +``` + +To bind-mount a host directory instead: + +```bash +docker run -d \ + --name cornerstone \ + -p 3000:3000 \ + -v cornerstone-data:/app/data \ + -v /path/on/host/cornerstone-backups:/backups \ + steilerdev/cornerstone:latest +``` + +A bind mount is often the easier choice for backups because the archives are directly accessible from the host -- you can copy them off-site, list them with `ls`, or hand them to your existing backup tooling without having to enter the container. + +### Docker Compose + +```yaml +services: + cornerstone: + image: steilerdev/cornerstone:latest + ports: + - '3000:3000' + volumes: + - cornerstone-data:/app/data + - cornerstone-backups:/backups + environment: + BACKUP_CADENCE: '0 2 * * *' + BACKUP_RETENTION: '30' + +volumes: + cornerstone-data: + cornerstone-backups: +``` + +## Manual Backups + +When the backup feature is configured, a **Backups** entry appears in the admin sidebar (admins only). + +From the Backups page you can: + +- **Create Backup** -- triggers a new backup archive immediately +- **Restore** -- restores from a selected archive (see [Restoring from a Backup](#restoring-from-a-backup) below) +- **Delete** -- removes a specific archive from disk + +The list shows each archive's filename, creation timestamp, and size on disk, sorted newest-first. + +:::note Admin-only +All backup actions -- create, list, restore, and delete -- require an admin role. Members do not see the Backups page. +::: + +## Scheduled Backups + +Set `BACKUP_CADENCE` to a standard cron expression to run backups automatically. Cornerstone uses the [node-cron](https://www.npmjs.com/package/node-cron) parser, which supports the standard 5-field cron syntax: + +``` +┌───────────── minute (0 - 59) +│ ┌───────────── hour (0 - 23) +│ │ ┌───────────── day of month (1 - 31) +│ │ │ ┌───────────── month (1 - 12) +│ │ │ │ ┌───────────── day of week (0 - 7, 0 and 7 = Sunday) +│ │ │ │ │ +* * * * * +``` + +### Common Cadences + +| Cron expression | Schedule | +|-----------------|----------| +| `0 2 * * *` | Daily at 02:00 | +| `0 2 * * 0` | Weekly on Sunday at 02:00 | +| `0 2 1 * *` | Monthly on the 1st at 02:00 | +| `0 */6 * * *` | Every 6 hours | +| `30 1 * * 1-5` | Weekdays at 01:30 | + +### Docker Compose Example + +```yaml +services: + cornerstone: + image: steilerdev/cornerstone:latest + volumes: + - cornerstone-data:/app/data + - cornerstone-backups:/backups + environment: + BACKUP_CADENCE: '0 2 * * *' # Daily at 2 AM + BACKUP_RETENTION: '14' # Keep last 14 archives +``` + +Scheduled backups run with the same logic as manual ones -- they appear in the Backups page list immediately and respect the retention policy. The schedule uses the container's local time zone (UTC by default in most Docker images). + +:::tip +If a scheduled backup fails -- for example because the backup directory is full or read-only -- the failure is logged but does not crash the server. Check the container logs to confirm scheduled backups are running successfully. +::: + +## Retention Policy + +Set `BACKUP_RETENTION` to a positive integer to cap the number of archives Cornerstone keeps. After every backup (manual or scheduled), Cornerstone counts the archives in `BACKUP_DIR` and deletes the oldest ones until the count is at or below the limit. + +For example, with `BACKUP_RETENTION=7` and a daily cadence, you always have roughly the last week of backups on disk. + +If `BACKUP_RETENTION` is unset, archives accumulate indefinitely -- you are responsible for pruning them manually. + +:::caution Retention only counts valid archives +The retention sweep only inspects files matching the `cornerstone-backup-*.tar.gz` naming pattern. Other files in `BACKUP_DIR` are ignored, so you can safely keep notes or off-site copies alongside the managed archives without risking accidental deletion. +::: + +## Restoring from a Backup + +Restoring replaces the **entire app data directory** with the contents of the selected archive. Any work items, budgets, photos, or other data added since that backup was taken will be lost. + +To restore: + +1. Open the **Backups** page (admin only) +2. Find the archive you want to restore from +3. Click **Restore** and confirm the warning dialog +4. Cornerstone returns a confirmation, closes the database, swaps the data directory in place, and exits + +After the process exits, your container orchestrator (Docker, Compose, Kubernetes, etc.) will restart the container automatically -- and the new instance comes up against the restored data. + +:::caution Restoring is destructive +A restore replaces all current data with the archive contents. There is no automatic "undo." Before restoring, take a fresh manual backup so you can roll forward again if you change your mind. Cornerstone does keep a timestamped copy of the previous data directory next to the original (e.g., `data.backup-1730000000`) until the next restart, but you should not rely on it as a recovery mechanism. +::: + +:::note Restart policy required +The restore flow exits the Node.js process intentionally so the new data directory is picked up cleanly on the next start. This relies on your container being configured to restart automatically. The default `docker-compose.yml` and `docker run` examples in this documentation use `restart: unless-stopped` (or equivalent). If you run Cornerstone without a restart policy, you will need to start the container yourself after a restore. +::: + +### Restoring on a New Host + +To migrate Cornerstone to a different machine using a backup: + +1. Copy the `.tar.gz` archive from the source host's `BACKUP_DIR` to the new host +2. Start a fresh Cornerstone container on the new host with the same `BACKUP_DIR` mount +3. Drop the archive into the mounted backup directory +4. Open the Backups page on the new host -- the archive appears in the list +5. Click **Restore** and confirm + +The restore flow rebuilds the data directory from the archive, so the new host comes up with the same database, photos, and configuration. + +## Off-Site Copies + +Cornerstone's backup feature manages archives on a single volume. For true disaster recovery, copy archives to a different machine or cloud storage on a regular basis. Some options: + +- **`rsync` to a remote host:** schedule `rsync` (or `restic`, `rclone`, etc.) on the host to mirror the bind-mounted backup directory to off-site storage +- **Cloud sync agents:** point a tool like `rclone` at the bind-mounted directory to sync to S3, Backblaze B2, Google Drive, etc. +- **Snapshot the volume:** if you use ZFS, btrfs, or a managed volume service, take periodic snapshots of the volume holding `BACKUP_DIR` + +Bind mounts make this easier than named volumes, since the archives live at a known host path you can hand to standard tooling. + +## Troubleshooting + +### "Backup not configured" + +The backup feature is enabled whenever `BACKUP_DIR` is set -- which it is by default (`/backups`). If you see a "not configured" message on the Backups page, your container does not have the default in effect. Confirm `BACKUP_DIR` is set to a valid path and that the path is mounted with write permissions. + +### "Backup directory is not writable" + +Cornerstone probes the backup directory for write access before each backup. If the probe fails, the backup is aborted. Check that: + +- The host directory or volume mounted at `BACKUP_DIR` exists +- The container user (typically `node`, UID 1000) has write permissions on the directory +- The volume is not mounted read-only + +### A scheduled backup didn't run + +- Check container logs for messages starting with `Backup scheduler initialized` (logged at startup) and `Scheduled backup` (logged on each run) +- Verify your cron expression with a tool like [crontab.guru](https://crontab.guru/) +- Remember the schedule uses the container's time zone (UTC by default) -- a `0 2 * * *` schedule fires at 02:00 UTC, which may not be 2 AM in your local time + +### "Backup in progress" + +Only one backup or restore can run at a time. If you trigger a manual backup while a scheduled one is still running -- or while a restore is mid-flight -- the second request is rejected. Wait for the first operation to finish and try again. From 30b6b2ee915132c07e9b29d8d9810f4aeafc23e9 Mon Sep 17 00:00:00 2001 From: "cornerstone-bot[bot]" Date: Wed, 29 Apr 2026 10:19:03 +0000 Subject: [PATCH 04/11] style: auto-fix lint and format [skip ci] --- client/src/components/budget/BudgetSection.tsx | 5 ++++- server/src/services/budgetOverviewService.ts | 4 +--- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/client/src/components/budget/BudgetSection.tsx b/client/src/components/budget/BudgetSection.tsx index 328df141..113ea8ef 100644 --- a/client/src/components/budget/BudgetSection.tsx +++ b/client/src/components/budget/BudgetSection.tsx @@ -133,7 +133,10 @@ export function BudgetSection({ (sum, line) => sum + (line.invoiceLink?.itemizedAmount || 0), 0, ); - const plannedTotal = groupLines.reduce((sum, line) => sum + effectivePlannedAmount(line), 0); + const plannedTotal = groupLines.reduce( + (sum, line) => sum + effectivePlannedAmount(line), + 0, + ); return ( - l.includesVat === 0 - ? Math.round(l.plannedAmount * 1.19 * 100) / 100 - : l.plannedAmount; + l.includesVat === 0 ? Math.round(l.plannedAmount * 1.19 * 100) / 100 : l.plannedAmount; for (const line of budgetLines) { const margin = CONFIDENCE_MARGINS[line.confidence as keyof typeof CONFIDENCE_MARGINS] ?? 0; From 1d793ef51e13ab32c18d92bc90539d0731a94fd9 Mon Sep 17 00:00:00 2001 From: Frank Steiler Date: Wed, 29 Apr 2026 16:50:06 +0200 Subject: [PATCH 05/11] fix(budget): remove hero card and fix printout source badge (#1389, #1390) (#1391) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * test(e2e): add smoke tests for budget overview cleanup (#1389/#1390) Add budget-overview-no-hero-card.spec.ts verifying that the hero card (
) and its CSS class are absent after removal in #1389, the Add button and Cost Breakdown Table are still rendered, and the source-badge label is present in the DOM for budget lines with a source assignment (#1390). Update BudgetOverviewPage POM's waitForLoaded() to race on costBreakdownCard instead of heroCard, which no longer exists. Remove heroCard assertions from budget-overview.spec.ts, budget-overview- print.spec.ts, and budget-source-filter.spec.ts that would fail after the hero card removal. Fixes #1389 Fixes #1390 Co-Authored-By: Claude e2e-test-engineer (Sonnet 4.6) * test(budget): prune hero-card tests and add print-badge DOM test (#1389/#1390) Remove 27 test cases that covered the removed hero card section (BudgetBar, key metrics row, remaining detail panel, currency formatting, Expected Payback metric, payback-adjusted remaining, subsidy payback detail panel, mobile bar detail, and hero card footer cleanup describe blocks). Keep the one hero-card it case in the empty state block. Add describe('source badge print visibility (#1390)') to CostBreakdownTable.test.tsx: expands a work item to budget-line level and asserts both .sourceBadgeDot (aria-hidden="true") and .sourceBadgeLabel (containing a child with aria-label) are present in the DOM — the exact structure that the new @media print CSS rules in CostBreakdownTable.module.css depend on. Fixes #1389 Fixes #1390 Co-Authored-By: Claude qa-integration-tester (Sonnet 4.5) * fix(budget): remove hero card and fix printout source badge (#1389/#1390) Remove the Budget Health hero card from the Budget Overview page, including all helpers, state, computed values, CSS classes, unused imports, and i18n keys that were exclusively used by it. The page now goes from PageLayout straight into the empty-state and Cost Breakdown Table without the metrics row, stacked bar, hover tooltip, and remaining detail panel. Fix the Budget Overview printout: print viewports map to ~600-720px, which triggers the mobile breakpoint and hides the source badge label in CostBreakdownTable, leaving only an invisible colored dot. Add print-mode rules that force the source-badge label visible and the dot hidden, with a border-based legibility treatment so the label prints without depending on background colors. Fixes #1389 Fixes #1390 Co-Authored-By: Claude dev-team-lead (Sonnet 4.6) Co-Authored-By: Claude frontend-developer (Haiku 4.5) Co-Authored-By: Claude translator (Sonnet 4.6) Co-Authored-By: Claude e2e-test-engineer (Sonnet 4.6) --------- Co-authored-by: Frank Steiler Co-authored-by: Claude e2e-test-engineer (Sonnet 4.6) --- .../agent-memory/e2e-test-engineer/MEMORY.md | 11 + .claude/agent-memory/product-owner/MEMORY.md | 1 + .../qa-integration-tester/MEMORY.md | 4 + .../CostBreakdownTable.module.css | 18 + .../CostBreakdownTable.test.tsx | 37 ++ client/src/i18n/de/budget.json | 29 -- client/src/i18n/en/budget.json | 29 -- .../BudgetOverviewPage.module.css | 325 ------------- .../BudgetOverviewPage.test.tsx | 452 ------------------ .../BudgetOverviewPage/BudgetOverviewPage.tsx | 392 --------------- e2e/pages/BudgetOverviewPage.ts | 15 +- .../budget-overview-no-hero-card.spec.ts | 333 +++++++++++++ .../budget/budget-overview-print.spec.ts | 10 +- e2e/tests/budget/budget-overview.spec.ts | 95 +--- e2e/tests/budget/budget-source-filter.spec.ts | 4 - 15 files changed, 422 insertions(+), 1333 deletions(-) create mode 100644 e2e/tests/budget/budget-overview-no-hero-card.spec.ts diff --git a/.claude/agent-memory/e2e-test-engineer/MEMORY.md b/.claude/agent-memory/e2e-test-engineer/MEMORY.md index e7ea8262..6c3b6c51 100644 --- a/.claude/agent-memory/e2e-test-engineer/MEMORY.md +++ b/.claude/agent-memory/e2e-test-engineer/MEMORY.md @@ -3,6 +3,17 @@ > Detailed notes live in topic files. This index links to them. > See: `e2e-pom-patterns.md`, `e2e-parallel-isolation.md`, `story-epic08-e2e.md`, `story-933-dav-vendor-contacts.md`, `milestones-e2e.md`, `story-1248-mass-move.md` +## Budget Overview Hero Card Removed (Issues #1389/#1390, 2026-04-29) + +- `
` (heroCard) is **gone** from BudgetOverviewPage.tsx after #1389. +- `BudgetOverviewPage.POM.waitForLoaded()` now races on `costBreakdownCard` instead of `heroCard`. +- `heroCard` locator kept in POM for historical reference but never matches on-page elements. +- Tests that asserted `heroCard.toBeVisible()` were removed from: `budget-overview.spec.ts`, `budget-overview-print.spec.ts`, `budget-source-filter.spec.ts`. +- New spec: `e2e/tests/budget/budget-overview-no-hero-card.spec.ts` (smoke, @smoke tag). +- Source badge (`aria-label="Budget source: {name}"`) is on Level 3 rows only — must expand Work Items → area → item to reveal budget lines. +- `BreakdownBudgetLine` fields: `id`, `description`, `plannedAmount`, `confidence`, `actualCost`, `hasInvoice`, `isQuotation`, `budgetSourceId` (NOT `sourceId`/`sourceName`). +- BudgetSources API mock response: `{ budgetSources: [{ id, name, ... }] }` — component only reads `s.id` and `s.name`. + ## Budget Source Filter E2E (Story #1360, 2026-04-25 — server-side filter) - **Story #1360** rewrote filter from client-side to server-side. `BudgetSourceSummaryBreakdown` now has `subsidyPaybackMin/Max` NOT `subsidyPayback`. diff --git a/.claude/agent-memory/product-owner/MEMORY.md b/.claude/agent-memory/product-owner/MEMORY.md index 92822fb3..cd78b690 100644 --- a/.claude/agent-memory/product-owner/MEMORY.md +++ b/.claude/agent-memory/product-owner/MEMORY.md @@ -109,6 +109,7 @@ All 12 stories merged. Paperless-ngx links for invoices are EPIC-08; budget repo - **2026-02-27** — 11 issues #328-#338 (EPIC-06 + EPIC-05 sub-issues, 6 bugs / 5 stories) - **2026-04-28** — 5 standalone UI bugs #1369-#1373 (no active parent epic; all related epics closed): #1369 hide-linked filter on Paperless picker, #1370 disable scroll-wheel on numeric inputs, #1371 "Includes VAT" parity for direct-amount budget lines, #1372 vendor in invoice picker, #1373 "Claimed" total on Budget Invoices summary. All Todo. Only EPIC-16 (Floor Plans) is currently open and is unrelated to these. +- **2026-04-29** — 2 standalone Budget Overview bugs #1389-#1390 (no parent epic): #1389 remove Budget Health hero card from `/budget/overview` (full deletion incl. helpers, state, CSS classes, i18n keys, hero-card-only tests), #1390 source-name badge missing from print preview (mobile media query hides label on print-width pages). Both Todo. ## Patterns and Conventions diff --git a/.claude/agent-memory/qa-integration-tester/MEMORY.md b/.claude/agent-memory/qa-integration-tester/MEMORY.md index ceef8f8b..dc2e78f2 100644 --- a/.claude/agent-memory/qa-integration-tester/MEMORY.md +++ b/.claude/agent-memory/qa-integration-tester/MEMORY.md @@ -3,6 +3,10 @@ > Detailed notes live in topic files. This index links to them. > See: `budget-categories-story-142.md`, `e2e-pom-patterns.md`, `e2e-parallel-isolation.md`, `story-358-document-linking.md`, `story-360-document-a11y.md`, `story-epic08-e2e.md`, `story-509-manage-page.md`, `story-471-dashboard.md` +## Systemic jest.unstable_mockModule Issue in This Worktree (2026-04-29) + +ALL client tests using `jest.unstable_mockModule('../../lib/formatters.js', ...)` fail locally in this worktree with `useLocale must be used within a LocaleProvider`. This is a pre-existing environment issue — tests pass in CI. **Do not attempt to fix by changing mocks or adding LocaleProvider** — the tests are structurally correct and the mock works in CI. Just commit and let CI validate. The issue is specific to this worktree's Jest module resolution environment. + ## Story #1360 — Server-Side Source Filter Tests (2026-04-25) **CostBreakdownTable.test.tsx**: Replaced the 12-test `describe('Source filter — aggregate consistency (#1358)')` block with 4-test `describe('Server-driven render path (#1360)')`. The 12 old tests tested deleted client-side helpers (`computePerSourcePayback`, `computeFilteredAggregates`, `visibleLineIds`). Removal strategy: Python `content.replace()` on large block — incremental Edit tool calls left orphaned code. The `buildBreakdownWithTwoSources()` helper was replaced by `buildServerFilteredBreakdown()`. diff --git a/client/src/components/CostBreakdownTable/CostBreakdownTable.module.css b/client/src/components/CostBreakdownTable/CostBreakdownTable.module.css index 6cbfde22..04f5bf27 100644 --- a/client/src/components/CostBreakdownTable/CostBreakdownTable.module.css +++ b/client/src/components/CostBreakdownTable/CostBreakdownTable.module.css @@ -664,6 +664,24 @@ .rowSourceDetailToggle[aria-pressed='false'] { display: none !important; } + + /* Issue #1390: Print viewports map to ~600-720px which triggers the mobile + breakpoint and hides .sourceBadgeLabel. Force the label visible and the + dot hidden in print regardless of viewport width. */ + .sourceBadgeLabel { + display: inline-flex !important; + } + + .sourceBadgeDot { + display: none !important; + } + + /* Make source badge legible without background-color in print using a border. */ + .sourceBadgeLabel > * { + background: transparent !important; + border: 1pt solid var(--color-border-strong) !important; + print-color-adjust: exact; + } } /* ============================================================ diff --git a/client/src/components/CostBreakdownTable/CostBreakdownTable.test.tsx b/client/src/components/CostBreakdownTable/CostBreakdownTable.test.tsx index 909c3f25..cfdc3156 100644 --- a/client/src/components/CostBreakdownTable/CostBreakdownTable.test.tsx +++ b/client/src/components/CostBreakdownTable/CostBreakdownTable.test.tsx @@ -4473,3 +4473,40 @@ describe('filteredAvailableFunds — Available Funds row and Remaining Budget ro expect(remainingCostCell!.textContent?.replace(/\s+/g, '')).toContain('€200,000.00'); }); }); + +// ── Source badge print visibility (#1390) ───────────────────────────────────── + +describe('source badge print visibility (#1390)', () => { + // Verifies the DOM structure that the print-mode CSS in CostBreakdownTable.module.css depends on. + // The CSS toggles .sourceBadgeDot off and .sourceBadgeLabel on inside @media print; + // jsdom does not evaluate @media, so this test asserts both elements are present in the DOM, + // which is the contract the CSS relies on. + it('renders both .sourceBadgeDot and .sourceBadgeLabel with the badge inside the label for each budget line', () => { + const sourceId = 'src-1'; + const sourceName = 'Bank Loan'; + const breakdown = buildBreakdownWithSourcedWI({ + budgetSourceId: sourceId, + budgetSources: [buildSourceSummary({ id: sourceId, name: sourceName })], + }); + + const { container } = renderWithRouter(breakdown, buildOverview()); + + // Expand WI section → area → item so BudgetLineRow renders in the DOM + fireEvent.click(getButtonByControls(container, 'wi-section-categories')); + fireEvent.click(getButtonByControls(container, 'area:No Area')); + fireEvent.click(getButtonByLabel('Expand Sourced Work Item')); + + // .sourceBadgeDot — screen-visible colored dot, hidden in print via CSS + const dot = container.querySelector('[class*="sourceBadgeDot"]'); + expect(dot).not.toBeNull(); + expect(dot!.getAttribute('aria-hidden')).toBe('true'); + + // .sourceBadgeLabel — wraps the Badge; hidden on screen, shown in print via CSS + const label = container.querySelector('[class*="sourceBadgeLabel"]'); + expect(label).not.toBeNull(); + + // The Badge inside has aria-label set by the source-badge code path. + const badgeChild = label!.querySelector('[aria-label]'); + expect(badgeChild).not.toBeNull(); + }); +}); diff --git a/client/src/i18n/de/budget.json b/client/src/i18n/de/budget.json index e8585234..535cdc85 100644 --- a/client/src/i18n/de/budget.json +++ b/client/src/i18n/de/budget.json @@ -12,36 +12,7 @@ "addInvoice": "Rechnung Hinzufügen", "addVendor": "Auftragnehmer Hinzufügen" }, - "availableFunds": "Verfügbare Mittel", - "projectedCostRange": "Geplanter Kostenbereich", "expectedPayback": "Erwartete Rückzahlung", - "paybackCapped": "Einige Förderprogramme sind überzeichnet – Rückzahlungswerte sind begrenzt", - "remaining": "Verbleibend", - "remainingDetail": "Verbleibendes Budget – tippen Sie für Details", - "categories": "Kategorien", - "allCategories": "Alle Kategorien", - "noCategories": "Keine Kategorien", - "selectAll": "Alle auswählen", - "clearAll": "Alle deaktivieren", - "bars": { - "claimedInvoices": "Eingereichte Rechnungen", - "paidInvoices": "Bezahlte Rechnungen", - "pendingInvoices": "Ausstehende Rechnungen", - "projectedOptimistic": "Projiziert (optimistisch)", - "projectedPessimistic": "Projiziert (pessimistisch)", - "overflow": "Überlauf" - }, - "remainingPerspectives": { - "vsMinPlanned": "Verbleibend vs. Min. Geplant", - "vsMaxPlanned": "Verbleibend vs. Max. Geplant", - "vsProjectedMin": "Verbleibend vs. Projiz. Min.", - "vsProjectedMax": "Verbleibend vs. Projiz. Max.", - "vsActualCost": "Verbleibend vs. Tatsächliche Kosten", - "vsActualPaid": "Verbleibend vs. Tatsächlich Bezahlt", - "vsMinPlannedWithPayback": "Verbleibend vs. Min. Geplant (inkl. Rückzahlung)", - "vsMaxPlannedWithPayback": "Verbleibend vs. Max. Geplant (inkl. Rückzahlung)" - }, - "ofAvailableFunds": "der verfügbaren Mittel", "costBreakdown": { "tableCaption": "Kostenaufschlüsselung nach Bereich und Element", "loading": "Kostenaufschlüsselung wird geladen…", diff --git a/client/src/i18n/en/budget.json b/client/src/i18n/en/budget.json index 817cc6cd..fbef287d 100644 --- a/client/src/i18n/en/budget.json +++ b/client/src/i18n/en/budget.json @@ -12,36 +12,7 @@ "addInvoice": "Add Invoice", "addVendor": "Add Vendor" }, - "availableFunds": "Available Funds", - "projectedCostRange": "Projected Cost Range", "expectedPayback": "Expected Payback", - "paybackCapped": "Some subsidies are oversubscribed — payback values are capped", - "remaining": "Remaining", - "remainingDetail": "Remaining budget — tap for details", - "categories": "Categories", - "allCategories": "All categories", - "noCategories": "No categories", - "selectAll": "Select All", - "clearAll": "Clear All", - "bars": { - "claimedInvoices": "Claimed Invoices", - "paidInvoices": "Paid Invoices", - "pendingInvoices": "Pending Invoices", - "projectedOptimistic": "Projected (optimistic)", - "projectedPessimistic": "Projected (pessimistic)", - "overflow": "Overflow" - }, - "remainingPerspectives": { - "vsMinPlanned": "Remaining vs Min Planned", - "vsMaxPlanned": "Remaining vs Max Planned", - "vsProjectedMin": "Remaining vs Projected Min", - "vsProjectedMax": "Remaining vs Projected Max", - "vsActualCost": "Remaining vs Actual Cost", - "vsActualPaid": "Remaining vs Actual Paid", - "vsMinPlannedWithPayback": "Remaining vs Min Planned (incl. payback)", - "vsMaxPlannedWithPayback": "Remaining vs Max Planned (incl. payback)" - }, - "ofAvailableFunds": "of available funds", "costBreakdown": { "tableCaption": "Budget cost breakdown by area and item", "loading": "Loading cost breakdown…", diff --git a/client/src/pages/BudgetOverviewPage/BudgetOverviewPage.module.css b/client/src/pages/BudgetOverviewPage/BudgetOverviewPage.module.css index 32981f37..c19afb4a 100644 --- a/client/src/pages/BudgetOverviewPage/BudgetOverviewPage.module.css +++ b/client/src/pages/BudgetOverviewPage/BudgetOverviewPage.module.css @@ -148,296 +148,6 @@ max-width: 480px; } -/* ============================================================ - * Budget Health Hero Card - * ============================================================ */ - -.heroCard { - background: var(--color-bg-primary); - border: 1px solid var(--color-border); - border-radius: var(--radius-lg); - box-shadow: var(--shadow-sm); - padding: var(--spacing-6); - display: flex; - flex-direction: column; - gap: var(--spacing-5); -} - -/* ---- Key metrics row: 3-column grid (desktop), 4-column with payback ---- */ - -.metricsRow { - display: grid; - grid-template-columns: repeat(3, 1fr); - gap: var(--spacing-4); -} - -.metricsRowWithPayback { - grid-template-columns: repeat(4, 1fr); -} - -.metricPaybackValue { - color: var(--color-success-text-on-light); -} - -.paybackCappedNote { - font-size: var(--font-size-xs); - font-weight: var(--font-weight-normal); - color: var(--color-warning-text-on-light); - margin-top: var(--spacing-1); -} - -.metricGroup { - display: flex; - flex-direction: column; - gap: var(--spacing-1); -} - -.metricLabel { - font-size: var(--font-size-xs); - font-weight: var(--font-weight-semibold); - color: var(--color-text-muted); - text-transform: uppercase; - letter-spacing: 0.05em; -} - -.metricValue { - font-size: var(--font-size-xl); - font-weight: var(--font-weight-semibold); - color: var(--color-text-primary); - font-variant-numeric: tabular-nums; - line-height: 1.2; -} - -/* Interactive metric value (button reset + hover cue) */ -.metricValueInteractive { - display: inline-flex; - align-items: baseline; - gap: var(--spacing-1-5); - background: none; - border: none; - padding: 0; - cursor: pointer; - font-size: inherit; - font-weight: inherit; - font-variant-numeric: tabular-nums; - color: inherit; - text-align: left; - line-height: inherit; - transition: opacity var(--transition-fast); -} - -.metricValueInteractive:hover { - opacity: 0.8; -} - -.metricValueInteractive:focus-visible { - outline: none; - box-shadow: var(--shadow-focus); - border-radius: var(--radius-sm); -} - -.metricRange { - display: inline-flex; - align-items: baseline; - gap: var(--spacing-1-5); -} - -.metricRangeSep { - color: var(--color-text-muted); - font-weight: var(--font-weight-normal); -} - -.metricPositive { - color: var(--color-success-text-on-light); -} - -.metricNegative { - color: var(--color-danger-text-on-light); -} - -/* Info hint icon (circled i) */ -.metricHint { - font-size: var(--font-size-sm); - color: var(--color-text-muted); - margin-left: var(--spacing-1); - vertical-align: middle; -} - -/* ---- Remaining detail panel (mobile inline toggle) ---- */ - -.remainingDetailPanel { - overflow: hidden; - max-height: 0; - opacity: 0; - transition: - max-height var(--transition-slow), - opacity var(--transition-normal); -} - -.remainingDetailPanelOpen { - max-height: 400px; - opacity: 1; -} - -/* ---- Remaining detail contents ---- */ - -.remainingPanel { - padding-top: var(--spacing-3); - display: flex; - flex-direction: column; - gap: var(--spacing-2); -} - -.remainingPanelRow { - display: flex; - justify-content: space-between; - align-items: baseline; - gap: var(--spacing-2); - font-size: var(--font-size-sm); -} - -.remainingPanelLabel { - color: var(--color-text-muted); - white-space: nowrap; - flex-shrink: 0; -} - -.remainingPanelValue { - font-weight: var(--font-weight-medium); - font-variant-numeric: tabular-nums; - text-align: right; -} - -.remainingPositive { - color: var(--color-success-text-on-light); -} - -.remainingNegative { - color: var(--color-danger-text-on-light); -} - -/* ---- Bar wrapper + desktop hover tooltip ---- */ - -.barWrapper { - position: relative; -} - -.barTooltipAnchor { - position: absolute; - bottom: calc(100% + var(--spacing-2)); - left: 50%; - transform: translateX(-50%); - z-index: var(--z-dropdown); - pointer-events: none; -} - -/* ---- Segment tooltip content ---- */ - -.segmentTooltip { - background: var(--color-bg-inverse); - color: var(--color-text-inverse); - border-radius: var(--radius-md); - padding: var(--spacing-2) var(--spacing-3); - white-space: nowrap; - display: flex; - flex-direction: column; - gap: var(--spacing-0-5); - box-shadow: var(--shadow-md); - font-size: var(--font-size-sm); -} - -.segmentTooltipLabel { - font-weight: var(--font-weight-semibold); -} - -.segmentTooltipValue { - font-variant-numeric: tabular-nums; -} - -.segmentTooltipPct { - font-size: var(--font-size-xs); - opacity: 0.8; -} - -/* ---- Mobile bar detail panel ---- */ - -.mobileDetail { - overflow: hidden; - max-height: 0; - opacity: 0; - transition: - max-height var(--transition-slow), - opacity var(--transition-normal); -} - -.mobileDetailOpen { - max-height: 400px; - opacity: 1; -} - -.mobileBarDetail { - padding: var(--spacing-3) 0 var(--spacing-1); - display: flex; - flex-direction: column; - gap: var(--spacing-2); -} - -.mobileBarDetailRow { - display: grid; - grid-template-columns: auto 1fr auto auto; - align-items: center; - gap: var(--spacing-2); - font-size: var(--font-size-sm); -} - -.mobileBarDetailDot { - width: 10px; - height: 10px; - border-radius: var(--radius-circle); - flex-shrink: 0; - display: inline-block; -} - -.mobileBarDetailLabel { - color: var(--color-text-secondary); -} - -.mobileBarDetailValue { - font-variant-numeric: tabular-nums; - color: var(--color-text-primary); - font-weight: var(--font-weight-medium); - text-align: right; -} - -.mobileBarDetailPct { - font-size: var(--font-size-xs); - color: var(--color-text-muted); - min-width: 4.5rem; - text-align: right; -} - -/* ---- Footer row ---- */ - -.heroFooter { - display: flex; - align-items: center; - justify-content: space-between; - gap: var(--spacing-4); - flex-wrap: wrap; - font-size: var(--font-size-sm); - color: var(--color-text-muted); - padding-top: var(--spacing-2); - border-top: 1px solid var(--color-border); -} - -.footerItem strong { - color: var(--color-text-secondary); - font-weight: var(--font-weight-semibold); -} - -.footerItemPayback strong { - color: var(--color-success-text-on-light); -} /* ---- Breakdown loading state ---- */ @@ -465,10 +175,6 @@ min-height: 44px; } - .metricsRowWithPayback { - grid-template-columns: repeat(2, 1fr); - } - .addButton { min-height: 44px; } @@ -506,33 +212,6 @@ .emptyState { padding: var(--spacing-6); } - - .heroCard { - padding: var(--spacing-4); - gap: var(--spacing-4); - } - - /* Metrics: single column on mobile */ - .metricsRow { - grid-template-columns: 1fr; - gap: var(--spacing-3); - } - - .metricValue { - font-size: var(--font-size-lg); - } - - /* Footer: stack on mobile */ - .heroFooter { - flex-direction: column; - align-items: flex-start; - gap: var(--spacing-2); - } - - /* Desktop tooltip hidden on mobile — use inline panel instead */ - .barTooltipAnchor { - display: none; - } } /* ============================================================ @@ -540,10 +219,6 @@ * ============================================================ */ @media print { - .heroCard { - display: none !important; - } - .addContainer { display: none !important; } diff --git a/client/src/pages/BudgetOverviewPage/BudgetOverviewPage.test.tsx b/client/src/pages/BudgetOverviewPage/BudgetOverviewPage.test.tsx index 3e356f74..391a8c3d 100644 --- a/client/src/pages/BudgetOverviewPage/BudgetOverviewPage.test.tsx +++ b/client/src/pages/BudgetOverviewPage/BudgetOverviewPage.test.tsx @@ -319,14 +319,6 @@ describe('BudgetOverviewPage', () => { }); }); - it('still renders the hero card section in empty state', async () => { - mockFetchBudgetOverview.mockResolvedValueOnce(zeroOverview); - renderPage(); - - await waitFor(() => { - expect(screen.getByRole('region', { name: /budget overview/i })).toBeInTheDocument(); - }); - }); }); // ─── Page header ──────────────────────────────────────────────────────────── @@ -342,381 +334,7 @@ describe('BudgetOverviewPage', () => { }); }); - // ─── Key metrics row ───────────────────────────────────────────────────────── - - describe('key metrics row', () => { - it('shows "Available Funds" label', async () => { - mockFetchBudgetOverview.mockResolvedValueOnce(richOverview); - renderPage(); - - await waitFor(() => { - expect(screen.getByText('Available Funds')).toBeInTheDocument(); - }); - }); - - it('shows available funds value formatted as currency', async () => { - mockFetchBudgetOverview.mockResolvedValueOnce(richOverview); - renderPage(); - - // richOverview: availableFunds = 200000 - await waitFor(() => { - expect(screen.getByText(/200,000\.00/)).toBeInTheDocument(); - }); - }); - - it('shows "Projected Cost Range" label', async () => { - mockFetchBudgetOverview.mockResolvedValueOnce(richOverview); - renderPage(); - - await waitFor(() => { - expect(screen.getByText('Projected Cost Range')).toBeInTheDocument(); - }); - }); - - it('shows planned min and max values in the metrics row', async () => { - mockFetchBudgetOverview.mockResolvedValueOnce(richOverview); - renderPage(); - - // richOverview: minPlanned=120000 → €120K, maxPlanned=180000 → €180K - await waitFor(() => { - expect(screen.getByText(/120K/)).toBeInTheDocument(); - expect(screen.getByText(/180K/)).toBeInTheDocument(); - }); - }); - - it('shows "Remaining" label', async () => { - mockFetchBudgetOverview.mockResolvedValueOnce(richOverview); - renderPage(); - - await waitFor(() => { - expect(screen.getByText('Remaining')).toBeInTheDocument(); - }); - }); - - it('shows remaining range values (vs min planned and max planned)', async () => { - mockFetchBudgetOverview.mockResolvedValueOnce(richOverview); - renderPage(); - - // Component uses remainingVsMinPlanned and remainingVsMaxPlanned when hasPayback=false. - // richOverview: remainingVsMinPlanned=80000 → €80K, remainingVsMaxPlanned=20000 → €20K - // These values may appear in multiple elements (tooltip + mobile panel) - await waitFor(() => { - expect(screen.getAllByText(/€80K/).length).toBeGreaterThan(0); - expect(screen.getAllByText(/€20K/).length).toBeGreaterThan(0); - }); - }); - }); - - // ─── BudgetBar ──────────────────────────────────────────────────────────────── - - describe('BudgetBar', () => { - it('renders a BudgetBar with role="img"', async () => { - mockFetchBudgetOverview.mockResolvedValueOnce(richOverview); - renderPage(); - - await waitFor(() => { - expect(screen.getByRole('img')).toBeInTheDocument(); - }); - }); - - it('BudgetBar aria-label includes segment descriptions', async () => { - mockFetchBudgetOverview.mockResolvedValueOnce(richOverview); - renderPage(); - - await waitFor(() => { - const bar = screen.getByRole('img'); - const label = bar.getAttribute('aria-label') ?? ''; - // richOverview: actualCostClaimed=60000 (Claimed segment), actualCostPaid=100000, - // so paidVal = 100000 - 60000 = 40000 (Paid segment) - expect(label).toContain('Claimed'); - expect(label).toContain('Paid'); - }); - }); - - it('BudgetBar aria-label mentions Pending when pending invoices exist', async () => { - // actualCost=120000 > actualCostPaid=100000 → pendingVal=20000 - mockFetchBudgetOverview.mockResolvedValueOnce(richOverview); - renderPage(); - - await waitFor(() => { - const bar = screen.getByRole('img'); - const label = bar.getAttribute('aria-label') ?? ''; - expect(label).toContain('Pending'); - }); - }); - - it('does not render overflow segment when max planned <= available funds', async () => { - // richOverview: maxPlanned=180000 <= availableFunds=200000 → no overflow - mockFetchBudgetOverview.mockResolvedValueOnce(richOverview); - renderPage(); - - await waitFor(() => { - expect(screen.getByRole('img')).toBeInTheDocument(); - }); - - const bar = screen.getByRole('img'); - const label = bar.getAttribute('aria-label') ?? ''; - expect(label).not.toContain('Overflow'); - }); - - it('renders overflow segment when max planned exceeds available funds', async () => { - const overflowOverview: BudgetOverview = { - ...richOverview, - availableFunds: 100000, // maxPlanned=180000 > 100000 → overflow=80000 - }; - mockFetchBudgetOverview.mockResolvedValueOnce(overflowOverview); - renderPage(); - - await waitFor(() => { - const bar = screen.getByRole('img'); - expect(bar.getAttribute('aria-label')).toContain('Overflow'); - }); - }); - }); - - // ─── Footer cleanup (Scenarios 26–27) ────────────────────────────────────── - - describe('hero card footer cleanup', () => { - // Scenario 26: "Sources: N" text is NOT present - it('does not render "Sources: N" text in the page', async () => { - mockFetchBudgetOverview.mockResolvedValueOnce(richOverview); - renderPage(); - - await waitFor(() => { - // Wait for load to complete - expect(screen.queryByText(/loading budget overview/i)).not.toBeInTheDocument(); - }); - - expect(screen.queryByText(/sources:/i)).not.toBeInTheDocument(); - }); - - // Scenario 27: Expected Payback span is not in the footer section (only in metrics row when hasPayback) - it('does not render Expected Payback in a footer section when payback is zero', async () => { - // richOverview has maxTotalPayback = 0 → payback metric should not appear at all - mockFetchBudgetOverview.mockResolvedValueOnce(richOverview); - renderPage(); - - await waitFor(() => { - expect(screen.queryByText(/loading budget overview/i)).not.toBeInTheDocument(); - }); - - expect(screen.queryByText(/expected payback/i)).not.toBeInTheDocument(); - }); - }); - - // ─── Mobile bar detail ───────────────────────────────────────────────────── - - describe('mobile bar detail panel', () => { - it('clicking the BudgetBar toggles the mobile detail panel open', async () => { - const user = userEvent.setup(); - mockFetchBudgetOverview.mockResolvedValueOnce(richOverview); - renderPage(); - - await waitFor(() => { - expect(screen.getByRole('img')).toBeInTheDocument(); - }); - - const bar = screen.getByRole('img'); - - // aria-hidden on mobile panel before toggle - renderPage(); - mockFetchBudgetOverview.mockResolvedValueOnce(richOverview); - // Use the already-rendered bar from above - await user.click(bar); - - // After click, the mobile detail div should no longer have aria-hidden="true" - // (it toggles between open/closed) - // We verify this by checking if mobileBarOpen toggled at all — click fires onSegmentClick - // which calls setMobileBarOpen. We can verify the aria-hidden value changed. - // Since we click bar directly and the bar calls onSegmentClick(null), mobileBarOpen toggles. - // We trust the component logic and check the accessible structure. - expect(bar).toBeInTheDocument(); // bar is still present after click - }); - }); - - // ─── Remaining detail panel ──────────────────────────────────────────────── - - describe('remaining detail panel', () => { - it('renders the remaining detail panel (possibly hidden) with 6 perspectives', async () => { - mockFetchBudgetOverview.mockResolvedValueOnce(richOverview); - renderPage(); - - await waitFor(() => { - // All 6 perspective labels should exist in the DOM. - // They appear in BOTH the Tooltip panel and the mobile inline panel → use getAllByText - expect(screen.getAllByText('Remaining vs Min Planned').length).toBeGreaterThan(0); - expect(screen.getAllByText('Remaining vs Max Planned').length).toBeGreaterThan(0); - expect(screen.getAllByText('Remaining vs Projected Min').length).toBeGreaterThan(0); - expect(screen.getAllByText('Remaining vs Projected Max').length).toBeGreaterThan(0); - expect(screen.getAllByText('Remaining vs Actual Cost').length).toBeGreaterThan(0); - expect(screen.getAllByText('Remaining vs Actual Paid').length).toBeGreaterThan(0); - }); - }); - - it('remaining perspective values are formatted as currency', async () => { - mockFetchBudgetOverview.mockResolvedValueOnce(richOverview); - renderPage(); - - // richOverview: remainingVsMinPlanned = 80000 → €80,000.00 (appears in panel) - await waitFor(() => { - const elements = screen.getAllByText(/80,000\.00/); - expect(elements.length).toBeGreaterThan(0); - }); - }); - - it('clicking Remaining button toggles the mobile inline detail panel', async () => { - const user = userEvent.setup(); - mockFetchBudgetOverview.mockResolvedValueOnce(richOverview); - renderPage(); - - await waitFor(() => { - expect(screen.getByRole('button', { name: /remaining budget/i })).toBeInTheDocument(); - }); - - const remainingBtn = screen.getByRole('button', { name: /remaining budget/i }); - - // DOM structure: button → aria-describedby span → wrapper span (Tooltip) - // → wrapper.nextElementSibling = remainingDetailPanel div - const tooltipWrapper = remainingBtn.closest('.wrapper'); - expect(tooltipWrapper).not.toBeNull(); - const detailPanel = tooltipWrapper!.nextElementSibling; - expect(detailPanel).not.toBeNull(); - - // Initially closed (aria-hidden="true") - expect(detailPanel!.getAttribute('aria-hidden')).toBe('true'); - - await user.click(remainingBtn); - - // After click, the panel should be open (aria-hidden="false") - expect(detailPanel!.getAttribute('aria-hidden')).toBe('false'); - }); - }); - - // Category filter and category filter scope tests removed in #1243 — categorySummaries dropped - - // ─── Currency formatting ──────────────────────────────────────────────────── - - describe('currency formatting', () => { - it('formats large amounts using short notation (K/M) in metrics row', async () => { - mockFetchBudgetOverview.mockResolvedValueOnce(richOverview); - renderPage(); - - // richOverview: minPlanned=120000 → €120K, maxPlanned=180000 → €180K - await waitFor(() => { - expect(screen.getByText(/€120K/)).toBeInTheDocument(); - expect(screen.getByText(/€180K/)).toBeInTheDocument(); - }); - }); - - it('formats availableFunds as full currency (not short notation)', async () => { - mockFetchBudgetOverview.mockResolvedValueOnce(richOverview); - renderPage(); - - // richOverview: availableFunds = 200000 → formatted as full currency in Available Funds - await waitFor(() => { - expect(screen.getByText(/200,000\.00/)).toBeInTheDocument(); - }); - }); - }); - - // ─── Expected Payback Metric (Scenarios 22–25) ───────────────────────────── - describe('Expected Payback metric', () => { - // Scenario 22: maxTotalPayback === 0 → metric group not rendered; metrics row has 3 columns - it('does NOT render Expected Payback metric group when maxTotalPayback is 0', async () => { - // richOverview has maxTotalPayback = 0 → payback metric group should not appear - mockFetchBudgetOverview.mockResolvedValueOnce(richOverview); - renderPage(); - - await waitFor(() => { - expect(screen.queryByText(/loading budget overview/i)).not.toBeInTheDocument(); - }); - - expect(screen.queryByText(/expected payback/i)).not.toBeInTheDocument(); - }); - - // Scenario 23: maxTotalPayback > 0 → metric rendered with green value - it('renders Expected Payback metric group with green value when maxTotalPayback > 0', async () => { - const paybackOverview: BudgetOverview = { - ...richOverview, - subsidySummary: { - totalReductions: 15000, - activeSubsidyCount: 3, - minTotalPayback: 5000, - maxTotalPayback: 7500, - oversubscribedSubsidies: [], - }, - }; - mockFetchBudgetOverview.mockResolvedValueOnce(paybackOverview); - renderPage(); - - await waitFor(() => { - expect(screen.getByText(/expected payback/i)).toBeInTheDocument(); - }); - - // The payback value is styled with a positive/green class - // The metric group contains the label + value span with metricPaybackValue class - const paybackLabel = screen.getByText(/expected payback/i); - const metricGroup = paybackLabel.closest('div'); - expect(metricGroup).not.toBeNull(); - }); - - // Scenario 24: min === max → single value shown (no range dash) - it('shows a single value when minTotalPayback === maxTotalPayback', async () => { - const paybackOverview: BudgetOverview = { - ...richOverview, - subsidySummary: { - totalReductions: 15000, - activeSubsidyCount: 3, - minTotalPayback: 5000, - maxTotalPayback: 5000, - oversubscribedSubsidies: [], - }, - }; - mockFetchBudgetOverview.mockResolvedValueOnce(paybackOverview); - renderPage(); - - await waitFor(() => { - expect(screen.getByText(/expected payback/i)).toBeInTheDocument(); - }); - - // When min === max, no range dash should appear within the payback value - // We verify that the range separator "–" character does not appear in the payback group - const paybackLabel = screen.getByText(/expected payback/i); - const metricGroup = paybackLabel.closest('div'); - expect(metricGroup).not.toBeNull(); - // The dash separator element should not be rendered inside this group - const rangeSeps = metricGroup!.querySelectorAll('span[class*="metricRangeSep"]'); - expect(rangeSeps.length).toBe(0); - }); - - // Scenario 25: min !== max → range shown - it('shows a range when minTotalPayback !== maxTotalPayback', async () => { - const paybackOverview: BudgetOverview = { - ...richOverview, - subsidySummary: { - totalReductions: 15000, - activeSubsidyCount: 3, - minTotalPayback: 5000, - maxTotalPayback: 7500, - oversubscribedSubsidies: [], - }, - }; - mockFetchBudgetOverview.mockResolvedValueOnce(paybackOverview); - renderPage(); - - await waitFor(() => { - expect(screen.getByText(/expected payback/i)).toBeInTheDocument(); - }); - - // Both min and max payback formatted values should be in the DOM. - // formatShort(5000) = "€5K", formatShort(7500) = "€8K" (rounds .toFixed(0)) - await waitFor(() => { - expect(screen.getAllByText(/€5K/).length).toBeGreaterThan(0); - expect(screen.getAllByText(/€8K/).length).toBeGreaterThan(0); - }); - }); - }); // ─── Budget Sources Fetch (Scenarios 28–30) ──────────────────────────────── @@ -837,76 +455,6 @@ describe('BudgetOverviewPage', () => { }); }); - // ─── Payback-Adjusted Remaining (Scenario 33) ────────────────────────────── - - describe('payback-adjusted remaining metric', () => { - // Scenario 33: Remaining metric in hero card displays payback-adjusted values when payback exists - it('Remaining metric shows payback-adjusted min/max when payback exists', async () => { - // remainingVsMinPlannedWithPayback=85000 → €85K, remainingVsMaxPlannedWithPayback=25000 → €25K - const paybackOverview: BudgetOverview = { - ...richOverview, - remainingVsMinPlannedWithPayback: 85000, - remainingVsMaxPlannedWithPayback: 25000, - subsidySummary: { - totalReductions: 15000, - activeSubsidyCount: 3, - minTotalPayback: 5000, - maxTotalPayback: 5000, - oversubscribedSubsidies: [], - }, - }; - mockFetchBudgetOverview.mockResolvedValueOnce(paybackOverview); - renderPage(); - - await waitFor(() => { - // The Remaining metric button should show the payback-adjusted values - // €85K and €25K (formatted short notation) - expect(screen.getAllByText(/€85K/).length).toBeGreaterThan(0); - expect(screen.getAllByText(/€25K/).length).toBeGreaterThan(0); - }); - }); - }); - - // ─── Subsidy payback detail panel ───────────────────────────────────────── - - describe('subsidy payback detail panel', () => { - it('payback-adjusted rows appear in remaining detail panel when payback > 0', async () => { - const paybackOverview: BudgetOverview = { - ...richOverview, - remainingVsMinPlannedWithPayback: 85000, - remainingVsMaxPlannedWithPayback: 25000, - subsidySummary: { - totalReductions: 15000, - activeSubsidyCount: 3, - minTotalPayback: 5000, - maxTotalPayback: 5000, - oversubscribedSubsidies: [], - }, - }; - mockFetchBudgetOverview.mockResolvedValueOnce(paybackOverview); - renderPage(); - - await waitFor(() => { - // The payback-adjusted perspective labels should appear in the detail panel - expect( - screen.getAllByText(/remaining vs min planned \(incl\. payback\)/i).length, - ).toBeGreaterThan(0); - expect( - screen.getAllByText(/remaining vs max planned \(incl\. payback\)/i).length, - ).toBeGreaterThan(0); - }); - }); - - it('payback rows do NOT appear in remaining detail panel when payback = 0', async () => { - // richOverview has maxTotalPayback = 0 - mockFetchBudgetOverview.mockResolvedValueOnce(richOverview); - renderPage(); - - await waitFor(() => { - expect(screen.queryByText(/incl\. payback/i)).not.toBeInTheDocument(); - }); - }); - }); // ─── Story #1039: Add dropdown button ───────────────────────────────────── diff --git a/client/src/pages/BudgetOverviewPage/BudgetOverviewPage.tsx b/client/src/pages/BudgetOverviewPage/BudgetOverviewPage.tsx index cc50969b..6279ed2d 100644 --- a/client/src/pages/BudgetOverviewPage/BudgetOverviewPage.tsx +++ b/client/src/pages/BudgetOverviewPage/BudgetOverviewPage.tsx @@ -5,12 +5,8 @@ import type { BudgetOverview, BudgetBreakdown, BudgetSource } from '@cornerstone import { fetchBudgetOverview, fetchBudgetBreakdown } from '../../lib/budgetOverviewApi.js'; import { fetchBudgetSources } from '../../lib/budgetSourcesApi.js'; import { ApiClientError } from '../../lib/apiClient.js'; -import { useFormatters } from '../../lib/formatters.js'; import { PageLayout } from '../../components/PageLayout/PageLayout.js'; import { SubNav, type SubNavTab } from '../../components/SubNav/SubNav.js'; -import { BudgetBar } from '../../components/BudgetBar/BudgetBar.js'; -import type { BudgetBarSegment } from '../../components/BudgetBar/BudgetBar.js'; -import { Tooltip } from '../../components/Tooltip/Tooltip.js'; import { CostBreakdownTable } from '../../components/CostBreakdownTable/CostBreakdownTable.js'; import styles from './BudgetOverviewPage.module.css'; @@ -21,134 +17,12 @@ const BUDGET_TABS: SubNavTab[] = [ { labelKey: 'subnav.budget.subsidies', to: '/budget/subsidies' }, ]; -// ---- Helpers ---- - -// formatShort is defined inside the component to access formatCurrency from useFormatters() - -function formatPct(value: number, total: number): string { - if (total <= 0) return '0.0%'; - return `${((value / total) * 100).toFixed(1)}%`; -} - -// ---- Remaining Detail Panel ---- - -interface RemainingDetail { - label: string; - value: number; -} - -interface RemainingDetailPanelProps { - items: RemainingDetail[]; - formatCurrency: (value: number) => string; -} - -function RemainingDetailPanel({ items, formatCurrency }: RemainingDetailPanelProps) { - return ( -
- {items.map((item) => { - const isPositive = item.value >= 0; - return ( -
- {item.label} - - {formatCurrency(item.value)} - -
- ); - })} -
- ); -} - -// ---- Mobile bar detail panel ---- - -interface MobileBarDetailProps { - segments: BudgetBarSegment[]; - overflow: number; - availableFunds: number; - formatCurrency: (value: number) => string; -} - -function MobileBarDetail({ - segments, - overflow, - availableFunds, - formatCurrency, -}: MobileBarDetailProps) { - const { t } = useTranslation('budget'); - const rows = segments.filter((s) => s.value > 0); - return ( -
- {rows.map((seg) => { - const displayValue = seg.totalValue ?? seg.value; - return ( -
-
- ); - })} - {overflow > 0 && ( -
-
- )} -
- ); -} - -// ---- Hover tooltip content ---- - -interface SegmentTooltipProps { - segment: BudgetBarSegment; - availableFunds: number; - formatCurrency: (value: number) => string; -} - -function SegmentTooltipContent({ segment, availableFunds, formatCurrency }: SegmentTooltipProps) { - const { t } = useTranslation('budget'); - const displayValue = segment.totalValue ?? segment.value; - return ( -
- {segment.label} - {formatCurrency(displayValue)} - - {formatPct(displayValue, availableFunds)} {t('overview.ofAvailableFunds')} - -
- ); -} // ---- Main component ---- export function BudgetOverviewPage() { const { t } = useTranslation('budget'); const navigate = useNavigate(); - const { formatCurrency } = useFormatters(); - - function formatShort(value: number): string { - const abs = Math.abs(value); - if (abs >= 1_000_000) return `€${(value / 1_000_000).toFixed(1)}M`; - if (abs >= 1_000) return `€${(value / 1_000).toFixed(0)}K`; - return formatCurrency(value); - } const [overview, setOverview] = useState(null); const [isLoading, setIsLoading] = useState(true); @@ -174,15 +48,6 @@ export function BudgetOverviewPage() { // Budget sources state const [budgetSources, setBudgetSources] = useState([]); - // Hovered bar segment (desktop tooltip) - const [hoveredSegment, setHoveredSegment] = useState(null); - - // Mobile bar detail open - const [mobileBarOpen, setMobileBarOpen] = useState(false); - - // Remaining detail open (hover or tap) - const [remainingDetailOpen, setRemainingDetailOpen] = useState(false); - // Add dropdown state const [addOpen, setAddOpen] = useState(false); const addRef = useRef(null); @@ -338,13 +203,6 @@ export function BudgetOverviewPage() { } }; - const handleSegmentHover = useCallback((segment: BudgetBarSegment | null) => { - setHoveredSegment(segment); - }, []); - - const handleSegmentClick = useCallback((_segment: BudgetBarSegment | null) => { - setMobileBarOpen((v) => !v); - }, []); // Action dropdown (reused across loading, error, and main states) const actionDropdown = ( @@ -431,135 +289,6 @@ export function BudgetOverviewPage() { const hasData = overview.minPlanned > 0 || overview.actualCost > 0 || overview.sourceCount > 0; - // Use direct totals from overview (no filtering) - const filtered = { - actualCostClaimed: overview.actualCostClaimed, - actualCostPaid: overview.actualCostPaid, - actualCost: overview.actualCost, - minPlanned: overview.minPlanned, - maxPlanned: overview.maxPlanned, - }; - - // Segment values - const claimedVal = filtered.actualCostClaimed; - const paidVal = Math.max(0, filtered.actualCostPaid - filtered.actualCostClaimed); - const pendingVal = Math.max(0, filtered.actualCost - filtered.actualCostPaid); - const projMinVal = Math.max(0, filtered.minPlanned - filtered.actualCost); - const projMaxVal = Math.max(0, filtered.maxPlanned - filtered.minPlanned); - const overflow = Math.max(0, filtered.maxPlanned - overview.availableFunds); - - // Remaining vs projected (using filtered totals) - const filteredRemainingVsProjectedMin = overview.availableFunds - filtered.minPlanned; - const filteredRemainingVsProjectedMax = overview.availableFunds - filtered.maxPlanned; - - // Bar segments - const segments: BudgetBarSegment[] = [ - { - key: 'claimed', - value: claimedVal, - color: 'var(--color-budget-claimed)', - label: t('overview.bars.claimedInvoices')!, - totalValue: filtered.actualCostClaimed, - }, - { - key: 'paid', - value: paidVal, - color: 'var(--color-budget-paid)', - label: t('overview.bars.paidInvoices')!, - totalValue: filtered.actualCostPaid, - }, - { - key: 'pending', - value: pendingVal, - color: 'var(--color-budget-pending)', - label: t('overview.bars.pendingInvoices')!, - totalValue: filtered.actualCost, - }, - { - key: 'proj-min', - value: projMinVal, - color: 'var(--color-budget-projected)', - label: t('overview.bars.projectedOptimistic')!, - totalValue: filtered.minPlanned, - }, - { - key: 'proj-max', - value: projMaxVal, - // Projected max layer is fainter — achieved via inline opacity on color - color: 'var(--color-budget-projected)', - label: t('overview.bars.projectedPessimistic')!, - totalValue: filtered.maxPlanned, - }, - ]; - - // Payback visibility flag - const hasPayback = overview.subsidySummary.maxTotalPayback > 0; - - // Determine remaining values for health indicator - const remainingMin = hasPayback - ? overview.remainingVsMinPlannedWithPayback - : overview.remainingVsMinPlanned; - const remainingMax = hasPayback - ? overview.remainingVsMaxPlannedWithPayback - : overview.remainingVsMaxPlanned; - - // Remaining perspectives detail items (uses filtered where sensible) - const remainingDetailItems: RemainingDetail[] = [ - { - label: t('overview.remainingPerspectives.vsMinPlanned')!, - value: overview.remainingVsMinPlanned, - }, - { - label: t('overview.remainingPerspectives.vsMaxPlanned')!, - value: overview.remainingVsMaxPlanned, - }, - { - label: t('overview.remainingPerspectives.vsProjectedMin')!, - value: filteredRemainingVsProjectedMin, - }, - { - label: t('overview.remainingPerspectives.vsProjectedMax')!, - value: filteredRemainingVsProjectedMax, - }, - { - label: t('overview.remainingPerspectives.vsActualCost')!, - value: overview.remainingVsActualCost, - }, - { - label: t('overview.remainingPerspectives.vsActualPaid')!, - value: overview.remainingVsActualPaid, - }, - ...(hasPayback - ? [ - { - label: t('overview.remainingPerspectives.vsMinPlannedWithPayback')!, - value: overview.remainingVsMinPlannedWithPayback, - }, - { - label: t('overview.remainingPerspectives.vsMaxPlannedWithPayback')!, - value: overview.remainingVsMaxPlannedWithPayback, - }, - ] - : []), - ]; - - // Format projected max segment with reduced opacity - const segmentsForBar = segments.map((seg) => { - if (seg.key === 'proj-max') { - return { - ...seg, - // Pass as a CSS color with opacity via a wrapper style; BudgetBar accepts inline style via color string - // We encode it via a known CSS pattern — opacity half of projected - color: `color-mix(in srgb, var(--color-budget-projected) 50%, transparent)`, - }; - } - return seg; - }); - - const remainingTooltipContent = ( - - ); - return ( )} - {/* ======================================================== - * Budget Health Hero Card - * ======================================================== */} -
- {/* Key metrics row */} -
- {/* Available Funds */} -
- {t('overview.availableFunds')} - {formatCurrency(overview.availableFunds)} -
- - {/* Projected Cost Range */} -
- {t('overview.projectedCostRange')} - - - {formatShort(filtered.minPlanned)} - – - {formatShort(filtered.maxPlanned)} - - -
- - {/* Expected Payback (only when hasPayback) */} - {hasPayback && ( -
- {t('overview.expectedPayback')} - - - {formatShort(overview.subsidySummary.minTotalPayback)} - {overview.subsidySummary.minTotalPayback !== - overview.subsidySummary.maxTotalPayback ? ( - <> - – - {formatShort(overview.subsidySummary.maxTotalPayback)} - - ) : null} - - - {overview.subsidySummary.oversubscribedSubsidies?.length > 0 && ( - {t('overview.paybackCapped')} - )} -
- )} - - {/* Remaining (best/worst) — with detail on hover/tap */} -
- {t('overview.remaining')} - - - - - {/* Mobile inline remaining detail — toggled by tap */} -
- -
-
-
- - {/* Stacked bar */} -
- - - {/* Desktop floating tooltip anchored below bar */} - {hoveredSegment && ( -
- -
- )} -
- - {/* Mobile bar detail panel */} -
- -
-
- {/* Cost Breakdown Table */} {overview && (isBreakdownLoading ? ( diff --git a/e2e/pages/BudgetOverviewPage.ts b/e2e/pages/BudgetOverviewPage.ts index b9adc053..0ae88f55 100644 --- a/e2e/pages/BudgetOverviewPage.ts +++ b/e2e/pages/BudgetOverviewPage.ts @@ -7,11 +7,11 @@ * - Loading indicator while data is fetched * - Error card with a Retry button if the API fails * - Empty state when no budget data has been entered (all-zero response) - * - Budget overview hero card containing: - * - A key metrics row: Available Funds, Projected Cost Range, Remaining - * - A BudgetBar stacked bar chart (role="img") - * - A footer showing subsidies and sources info * - Cost Breakdown table (CostBreakdownTable) with area hierarchy expand/collapse + * + * NOTE: The "Budget overview" hero card (
) was removed + * in issue #1389. The `heroCard` locator is retained for historical reference but will not + * match any element on the current page. */ import type { Page, Locator } from '@playwright/test'; @@ -102,7 +102,10 @@ export class BudgetOverviewPage { /** * Wait until the page has finished loading data (loading indicator gone, - * either error card, empty state, or hero card is visible). + * either error card, empty state, or cost breakdown section is visible). + * + * NOTE: The hero card was removed in issue #1389. waitForLoaded() now races on + * errorCard, emptyState, and costBreakdownCard instead. */ async waitForLoaded(): Promise { // Wait for the loading indicator to disappear @@ -113,7 +116,7 @@ export class BudgetOverviewPage { await Promise.race([ this.errorCard.waitFor({ state: 'visible', timeout: 10000 }), this.emptyState.waitFor({ state: 'visible', timeout: 10000 }), - this.heroCard.waitFor({ state: 'visible', timeout: 10000 }), + this.costBreakdownCard.waitFor({ state: 'visible', timeout: 10000 }), ]); } diff --git a/e2e/tests/budget/budget-overview-no-hero-card.spec.ts b/e2e/tests/budget/budget-overview-no-hero-card.spec.ts new file mode 100644 index 00000000..7f6b408c --- /dev/null +++ b/e2e/tests/budget/budget-overview-no-hero-card.spec.ts @@ -0,0 +1,333 @@ +/** + * Smoke tests for Budget Overview page post-cleanup (Issues #1389 and #1390) + * + * Issue #1389: The "Budget Health" hero card (
) was + * removed from the Budget Overview page. This spec asserts the hero card and its CSS-module + * class are absent and that the page still renders its core chrome correctly. + * + * Issue #1390: Print CSS in CostBreakdownTable is fixed so source-badge labels are visible + * during print. DOM-level verification of this fix is covered by unit tests; we include a + * focused DOM assertion here confirming the source-badge markup is present on screen. + * + * All tests use API route mocking — no testcontainers data dependency. + * Desktop viewport only (no @responsive tag — smoke, not full viewport matrix). + */ + +import { test, expect } from '../../fixtures/auth.js'; +import { BudgetOverviewPage } from '../../pages/BudgetOverviewPage.js'; +import { API } from '../../fixtures/testData.js'; + +// ───────────────────────────────────────────────────────────────────────────── +// Shared response factories +// ───────────────────────────────────────────────────────────────────────────── + +/** Minimal overview response with non-zero values so hasData=true and the breakdown renders. */ +function populatedOverviewResponse() { + return { + availableFunds: 300000, + sourceCount: 2, + minPlanned: 250000, + maxPlanned: 275000, + actualCost: 185000, + actualCostPaid: 150000, + projectedMin: 260000, + projectedMax: 270000, + actualCostClaimed: 80000, + remainingVsMinPlanned: 50000, + remainingVsMaxPlanned: 25000, + remainingVsActualCost: 115000, + remainingVsActualPaid: 150000, + remainingVsProjectedMin: 40000, + remainingVsProjectedMax: 30000, + remainingVsActualClaimed: 220000, + remainingVsMinPlannedWithPayback: 50000, + remainingVsMaxPlannedWithPayback: 25000, + subsidySummary: { + totalReductions: 12500, + activeSubsidyCount: 2, + }, + }; +} + +/** Minimal breakdown response so the CostBreakdownTable has data to render. */ +function populatedBreakdownResponse() { + const emptyTotals = { + projectedMin: 250000, + projectedMax: 275000, + actualCost: 185000, + subsidyPayback: 0, + rawProjectedMin: 250000, + rawProjectedMax: 275000, + minSubsidyPayback: 0, + }; + return { + workItems: { + areas: [ + { + areaId: 'area-rohbau', + name: 'Rohbau', + parentId: null, + color: '#3B82F6', + projectedMin: 250000, + projectedMax: 275000, + actualCost: 185000, + subsidyPayback: 0, + rawProjectedMin: 250000, + rawProjectedMax: 275000, + minSubsidyPayback: 0, + items: [], + children: [], + }, + ], + totals: emptyTotals, + }, + householdItems: { + areas: [], + totals: { + projectedMin: 0, + projectedMax: 0, + actualCost: 0, + subsidyPayback: 0, + rawProjectedMin: 0, + rawProjectedMax: 0, + minSubsidyPayback: 0, + }, + }, + subsidyAdjustments: [], + budgetSources: [], + }; +} + +/** Minimal breakdown with a budget source so the source-badge label (#1390) is rendered. */ +function breakdownWithSourceBadge() { + const bd = populatedBreakdownResponse(); + const area = bd.workItems.areas[0]; + return { + ...bd, + budgetSources: [ + { + id: 'src-bank', + name: 'Bank Loan', + totalAmount: 300000, + projectedMin: 0, + projectedMax: 0, + subsidyPaybackMin: 0, + subsidyPaybackMax: 0, + }, + ], + workItems: { + ...bd.workItems, + areas: [ + { + ...area, + items: [ + { + workItemId: 'wi-rohbau-1', + title: 'Rohbau Item', + projectedMin: 250000, + projectedMax: 275000, + actualCost: 185000, + subsidyPayback: 0, + rawProjectedMin: 250000, + rawProjectedMax: 275000, + minSubsidyPayback: 0, + costDisplay: 'mixed' as const, + budgetLines: [ + { + id: 'bl-1', + description: 'Foundation work', + plannedAmount: 250000, + confidence: 'medium' as const, + actualCost: 0, + hasInvoice: false, + isQuotation: false, + budgetSourceId: 'src-bank', + }, + ], + }, + ], + }, + ], + }, + }; +} + +/** + * Mount route mocks for both GET /api/budget/overview, GET /api/budget/breakdown, + * and GET /api/budget-sources. + * Returns a teardown function that must be called in a finally block. + */ +async function mountRoutes( + page: Parameters[1]['page'], + overviewBody: object, + breakdownBody: object, +) { + await page.route(`${API.budgetOverview}`, async (route) => { + if (route.request().method() === 'GET') { + await route.fulfill({ + status: 200, + contentType: 'application/json', + body: JSON.stringify({ overview: overviewBody }), + }); + } else { + await route.continue(); + } + }); + await page.route('**/api/budget/breakdown**', async (route) => { + if (route.request().method() === 'GET') { + await route.fulfill({ + status: 200, + contentType: 'application/json', + body: JSON.stringify({ breakdown: breakdownBody }), + }); + } else { + await route.continue(); + } + }); + await page.route(`${API.budgetSources}`, async (route) => { + if (route.request().method() === 'GET') { + await route.fulfill({ + status: 200, + contentType: 'application/json', + body: JSON.stringify({ + budgetSources: [{ id: 'src-bank', name: 'Bank Loan', amount: 300000 }], + }), + }); + } else { + await route.continue(); + } + }); + return async () => { + await page.unroute(`${API.budgetOverview}`); + await page.unroute('**/api/budget/breakdown**'); + await page.unroute(`${API.budgetSources}`); + }; +} + +// ───────────────────────────────────────────────────────────────────────────── +// Tests +// ───────────────────────────────────────────────────────────────────────────── + +test.describe('Budget Overview — hero card removed (#1389)', { tag: '@smoke' }, () => { + test('Page loads and "Budget" heading is visible', async ({ page }) => { + const overviewPage = new BudgetOverviewPage(page); + const teardown = await mountRoutes(page, populatedOverviewResponse(), populatedBreakdownResponse()); + + try { + await overviewPage.goto(); + await overviewPage.waitForLoaded(); + + await expect(overviewPage.heading).toBeVisible(); + await expect(overviewPage.heading).toHaveText('Budget'); + } finally { + await teardown(); + } + }); + + test('No element with aria-label "Budget overview" (hero card is gone)', async ({ page }) => { + const overviewPage = new BudgetOverviewPage(page); + const teardown = await mountRoutes(page, populatedOverviewResponse(), populatedBreakdownResponse()); + + try { + await overviewPage.goto(); + await overviewPage.waitForLoaded(); + + // The hero card was removed in #1389 — no section with aria-label="Budget overview" should exist + await expect(page.locator('[aria-label="Budget overview"]')).not.toBeAttached(); + } finally { + await teardown(); + } + }); + + test('No element with CSS class containing "heroCard" (hero card CSS removed)', async ({ + page, + }) => { + const overviewPage = new BudgetOverviewPage(page); + const teardown = await mountRoutes(page, populatedOverviewResponse(), populatedBreakdownResponse()); + + try { + await overviewPage.goto(); + await overviewPage.waitForLoaded(); + + // CSS Modules obfuscate class names but keep the original substring — assert absent + await expect(page.locator('[class*="heroCard"]')).not.toBeAttached(); + } finally { + await teardown(); + } + }); + + test('Add button is visible and opens dropdown with Add Invoice option', async ({ page }) => { + const overviewPage = new BudgetOverviewPage(page); + const teardown = await mountRoutes(page, populatedOverviewResponse(), populatedBreakdownResponse()); + + try { + await overviewPage.goto(); + await overviewPage.waitForLoaded(); + + // Add button is visible + await expect(overviewPage.addButton).toBeVisible(); + + // Clicking opens the dropdown — "Add Invoice" menu item becomes visible + await overviewPage.addButton.click(); + await expect(page.getByTestId('budget-overview-add-invoice')).toBeVisible(); + } finally { + await teardown(); + } + }); + + test('Cost Breakdown Table section is rendered', async ({ page }) => { + const overviewPage = new BudgetOverviewPage(page); + const teardown = await mountRoutes(page, populatedOverviewResponse(), populatedBreakdownResponse()); + + try { + await overviewPage.goto(); + await overviewPage.waitForLoaded(); + + // CostBreakdownTable is rendered: section[aria-labelledby="breakdown-heading"] + await expect(overviewPage.costBreakdownCard).toBeVisible(); + } finally { + await teardown(); + } + }); +}); + +test.describe('Budget Overview — source badge in breakdown (#1390)', { tag: '@smoke' }, () => { + test('Source-badge label is present in DOM for budget line with source assignment', async ({ + page, + }) => { + const overviewPage = new BudgetOverviewPage(page); + const teardown = await mountRoutes( + page, + populatedOverviewResponse(), + breakdownWithSourceBadge(), + ); + + try { + await overviewPage.goto(); + await overviewPage.waitForLoaded(); + + // Expand the Work Items section to reveal the area rows + await overviewPage.costBreakdownCard + .getByRole('button', { name: /expand work item budget by area/i }) + .click(); + + // Expand the Rohbau area to reveal the work item row + await overviewPage.breakdownAreaToggle('Rohbau').click(); + await expect(overviewPage.breakdownAreaRow('Rohbau Item')).toBeVisible(); + + // Expand the Rohbau Item to reveal the budget line row (Level 3) + await overviewPage.costBreakdownCard + .getByRole('button', { name: /Expand Rohbau Item/i }) + .click(); + + // The source-badge span should now be in the DOM with the correct aria-label. + // This confirms the source-badge markup is present on screen; the CSS print fix in + // #1390 ensures the label is also visible in print media (tested via unit tests). + await expect( + page.locator('[aria-label="Budget source: Bank Loan"]'), + ).toBeAttached(); + } finally { + await teardown(); + } + }); +}); diff --git a/e2e/tests/budget/budget-overview-print.spec.ts b/e2e/tests/budget/budget-overview-print.spec.ts index 634cce36..3d732836 100644 --- a/e2e/tests/budget/budget-overview-print.spec.ts +++ b/e2e/tests/budget/budget-overview-print.spec.ts @@ -2,7 +2,7 @@ * E2E tests for Budget Overview page print behaviour (Issue #1310 / fix/1310-print-budget-overview) * * Tests covered: - * 1. Print hides app chrome (sidebar, SubNav, hero card, Add button) + * 1. Print hides app chrome (sidebar, SubNav, Add button) — hero card removed in #1389 * 2. Print forces full expansion of collapsed breakdown rows (beforeprint event) * 3. Print hides expand chevron buttons * 4. Print shows page title (h1) @@ -200,7 +200,9 @@ async function mountRoutes( // ───────────────────────────────────────────────────────────────────────────── test.describe('Budget Overview — print behaviour', () => { - test('Print hides app chrome: sidebar, SubNav, hero card, and Add button', async ({ page }) => { + // NOTE: Hero card ("Budget overview" section) was removed in issue #1389. + // The test name and heroCard assertions have been updated accordingly. + test('Print hides app chrome: sidebar, SubNav, and Add button', async ({ page }) => { const overviewPage = new BudgetOverviewPage(page); const teardown = await mountRoutes( page, @@ -215,7 +217,6 @@ test.describe('Budget Overview — print behaviour', () => { // Verify chrome is visible on screen before switching to print await expect(overviewPage.sidebar).toBeVisible(); await expect(overviewPage.subNav).toBeVisible(); - await expect(overviewPage.heroCard).toBeVisible(); await expect(overviewPage.addButton).toBeVisible(); // Switch to print media @@ -227,9 +228,6 @@ test.describe('Budget Overview — print behaviour', () => { // Budget section SubNav must be hidden await expect(overviewPage.subNav).not.toBeVisible(); - // Hero card must be hidden - await expect(overviewPage.heroCard).not.toBeVisible(); - // Add dropdown button must be hidden await expect(overviewPage.addButton).not.toBeVisible(); } finally { diff --git a/e2e/tests/budget/budget-overview.spec.ts b/e2e/tests/budget/budget-overview.spec.ts index 6b90df3d..545f650a 100644 --- a/e2e/tests/budget/budget-overview.spec.ts +++ b/e2e/tests/budget/budget-overview.spec.ts @@ -5,8 +5,6 @@ * - Page loads with the correct h1 "Budget" heading * - Budget sub-navigation (tabs) is visible * - Empty state shown when no budget data exists - * - Budget overview hero card visible when data is present - * - Budget bar (stacked chart) is visible * - Error state with Retry button when API returns 500 * - Responsive layout: no horizontal scroll * - Dark mode rendering @@ -19,6 +17,9 @@ * - Cost Breakdown area grouping: no No Area row when breakdown has none * - Cost Breakdown area grouping: nested-area indent increases with depth (bounding box) * - Cost Breakdown area grouping: no standalone Area Breakdown section renders (smoke) + * + * NOTE: Hero card ("Budget overview" section) was removed in issue #1389. + * Hero card / BudgetBar tests have been removed. See budget-overview-no-hero-card.spec.ts. */ import { test, expect } from '../../fixtures/auth.js'; @@ -168,65 +169,6 @@ test.describe('Empty state', { tag: '@responsive' }, () => { }); }); -// ───────────────────────────────────────────────────────────────────────────── -// Hero card -// ───────────────────────────────────────────────────────────────────────────── -test.describe('Hero card', { tag: '@responsive' }, () => { - test('Hero card is visible when data is present', async ({ page }) => { - const overviewPage = new BudgetOverviewPage(page); - - await page.route(`${API.budgetOverview}`, async (route) => { - if (route.request().method() === 'GET') { - await route.fulfill({ - status: 200, - contentType: 'application/json', - body: JSON.stringify({ overview: populatedOverviewResponse() }), - }); - } else { - await route.continue(); - } - }); - - try { - await overviewPage.goto(); - await overviewPage.waitForLoaded(); - - // Then: The hero card is visible - await expect(overviewPage.heroCard).toBeVisible({ timeout: 8000 }); - } finally { - await page.unroute(`${API.budgetOverview}`); - } - }); - - test('Budget bar is visible', async ({ page }) => { - const overviewPage = new BudgetOverviewPage(page); - - await page.route(`${API.budgetOverview}`, async (route) => { - if (route.request().method() === 'GET') { - await route.fulfill({ - status: 200, - contentType: 'application/json', - body: JSON.stringify({ overview: populatedOverviewResponse() }), - }); - } else { - await route.continue(); - } - }); - - try { - await overviewPage.goto(); - await overviewPage.waitForLoaded(); - - // Then: The BudgetBar stacked bar chart is visible (role="img") - await expect(page.getByRole('img', { name: /Budget breakdown/ })).toBeVisible({ - timeout: 8000, - }); - } finally { - await page.unroute(`${API.budgetOverview}`); - } - }); -}); - // ───────────────────────────────────────────────────────────────────────────── // Error state // ───────────────────────────────────────────────────────────────────────────── @@ -318,35 +260,8 @@ test.describe('Dark mode rendering', { tag: '@responsive' }, () => { expect(hasHorizontalScroll).toBe(false); }); - test('Hero card visible in dark mode when budget data is mocked', async ({ page }) => { - const overviewPage = new BudgetOverviewPage(page); - - await page.route(`${API.budgetOverview}`, async (route) => { - if (route.request().method() === 'GET') { - await route.fulfill({ - status: 200, - contentType: 'application/json', - body: JSON.stringify({ overview: populatedOverviewResponse() }), - }); - } else { - await route.continue(); - } - }); - - try { - await page.goto('/budget/overview'); - await page.evaluate(() => { - document.documentElement.setAttribute('data-theme', 'dark'); - }); - - await overviewPage.waitForLoaded(); - - // Hero card visible in dark mode - await expect(overviewPage.heroCard).toBeVisible({ timeout: 8000 }); - } finally { - await page.unroute(`${API.budgetOverview}`); - } - }); + // NOTE: Hero card was removed in issue #1389. Dark mode hero card test removed. + // See budget-overview-no-hero-card.spec.ts for post-cleanup smoke tests. }); // ───────────────────────────────────────────────────────────────────────────── diff --git a/e2e/tests/budget/budget-source-filter.spec.ts b/e2e/tests/budget/budget-source-filter.spec.ts index 4f09b770..f2b43071 100644 --- a/e2e/tests/budget/budget-source-filter.spec.ts +++ b/e2e/tests/budget/budget-source-filter.spec.ts @@ -1388,9 +1388,6 @@ test.describe('Stale-while-revalidate during refetch', { tag: '@responsive' }, ( await overviewPage.goto(); await overviewPage.waitForLoaded(); - // Hero card is visible (initial state loaded) - await expect(overviewPage.heroCard).toBeVisible(); - // Expand work items to see content await overviewPage.costBreakdownCard .getByRole('button', { name: /expand work item budget by area/i }) @@ -1411,7 +1408,6 @@ test.describe('Stale-while-revalidate during refetch', { tag: '@responsive' }, ( // The breakdown section must still be visible (stale content rendered) // and must NOT have been replaced by a skeleton/loading state. await expect(overviewPage.costBreakdownCard).toBeVisible(); - await expect(overviewPage.heroCard).toBeVisible(); // No skeleton loading indicator for the breakdown section await expect(page.getByRole('status', { name: 'Loading budget overview' })).not.toBeVisible(); From 044d8fd869a20b98fe0635ffacc473f8c042f6f4 Mon Sep 17 00:00:00 2001 From: "cornerstone-bot[bot]" Date: Wed, 29 Apr 2026 14:52:07 +0000 Subject: [PATCH 06/11] style: auto-fix lint and format [skip ci] --- .../BudgetOverviewPage.module.css | 1 - .../BudgetOverviewPage.test.tsx | 4 --- .../BudgetOverviewPage/BudgetOverviewPage.tsx | 2 -- .../budget-overview-no-hero-card.spec.ts | 34 ++++++++++++++----- 4 files changed, 26 insertions(+), 15 deletions(-) diff --git a/client/src/pages/BudgetOverviewPage/BudgetOverviewPage.module.css b/client/src/pages/BudgetOverviewPage/BudgetOverviewPage.module.css index c19afb4a..e6510139 100644 --- a/client/src/pages/BudgetOverviewPage/BudgetOverviewPage.module.css +++ b/client/src/pages/BudgetOverviewPage/BudgetOverviewPage.module.css @@ -148,7 +148,6 @@ max-width: 480px; } - /* ---- Breakdown loading state ---- */ .breakdownLoading { diff --git a/client/src/pages/BudgetOverviewPage/BudgetOverviewPage.test.tsx b/client/src/pages/BudgetOverviewPage/BudgetOverviewPage.test.tsx index 391a8c3d..28da0465 100644 --- a/client/src/pages/BudgetOverviewPage/BudgetOverviewPage.test.tsx +++ b/client/src/pages/BudgetOverviewPage/BudgetOverviewPage.test.tsx @@ -318,7 +318,6 @@ describe('BudgetOverviewPage', () => { expect(screen.getByText(/start by adding budget categories/i)).toBeInTheDocument(); }); }); - }); // ─── Page header ──────────────────────────────────────────────────────────── @@ -334,8 +333,6 @@ describe('BudgetOverviewPage', () => { }); }); - - // ─── Budget Sources Fetch (Scenarios 28–30) ──────────────────────────────── describe('budget sources fetch', () => { @@ -455,7 +452,6 @@ describe('BudgetOverviewPage', () => { }); }); - // ─── Story #1039: Add dropdown button ───────────────────────────────────── describe('Add dropdown button', () => { diff --git a/client/src/pages/BudgetOverviewPage/BudgetOverviewPage.tsx b/client/src/pages/BudgetOverviewPage/BudgetOverviewPage.tsx index 6279ed2d..0d770573 100644 --- a/client/src/pages/BudgetOverviewPage/BudgetOverviewPage.tsx +++ b/client/src/pages/BudgetOverviewPage/BudgetOverviewPage.tsx @@ -17,7 +17,6 @@ const BUDGET_TABS: SubNavTab[] = [ { labelKey: 'subnav.budget.subsidies', to: '/budget/subsidies' }, ]; - // ---- Main component ---- export function BudgetOverviewPage() { @@ -203,7 +202,6 @@ export function BudgetOverviewPage() { } }; - // Action dropdown (reused across loading, error, and main states) const actionDropdown = (
diff --git a/e2e/tests/budget/budget-overview-no-hero-card.spec.ts b/e2e/tests/budget/budget-overview-no-hero-card.spec.ts index 7f6b408c..b544928d 100644 --- a/e2e/tests/budget/budget-overview-no-hero-card.spec.ts +++ b/e2e/tests/budget/budget-overview-no-hero-card.spec.ts @@ -211,7 +211,11 @@ async function mountRoutes( test.describe('Budget Overview — hero card removed (#1389)', { tag: '@smoke' }, () => { test('Page loads and "Budget" heading is visible', async ({ page }) => { const overviewPage = new BudgetOverviewPage(page); - const teardown = await mountRoutes(page, populatedOverviewResponse(), populatedBreakdownResponse()); + const teardown = await mountRoutes( + page, + populatedOverviewResponse(), + populatedBreakdownResponse(), + ); try { await overviewPage.goto(); @@ -226,7 +230,11 @@ test.describe('Budget Overview — hero card removed (#1389)', { tag: '@smoke' } test('No element with aria-label "Budget overview" (hero card is gone)', async ({ page }) => { const overviewPage = new BudgetOverviewPage(page); - const teardown = await mountRoutes(page, populatedOverviewResponse(), populatedBreakdownResponse()); + const teardown = await mountRoutes( + page, + populatedOverviewResponse(), + populatedBreakdownResponse(), + ); try { await overviewPage.goto(); @@ -243,7 +251,11 @@ test.describe('Budget Overview — hero card removed (#1389)', { tag: '@smoke' } page, }) => { const overviewPage = new BudgetOverviewPage(page); - const teardown = await mountRoutes(page, populatedOverviewResponse(), populatedBreakdownResponse()); + const teardown = await mountRoutes( + page, + populatedOverviewResponse(), + populatedBreakdownResponse(), + ); try { await overviewPage.goto(); @@ -258,7 +270,11 @@ test.describe('Budget Overview — hero card removed (#1389)', { tag: '@smoke' } test('Add button is visible and opens dropdown with Add Invoice option', async ({ page }) => { const overviewPage = new BudgetOverviewPage(page); - const teardown = await mountRoutes(page, populatedOverviewResponse(), populatedBreakdownResponse()); + const teardown = await mountRoutes( + page, + populatedOverviewResponse(), + populatedBreakdownResponse(), + ); try { await overviewPage.goto(); @@ -277,7 +293,11 @@ test.describe('Budget Overview — hero card removed (#1389)', { tag: '@smoke' } test('Cost Breakdown Table section is rendered', async ({ page }) => { const overviewPage = new BudgetOverviewPage(page); - const teardown = await mountRoutes(page, populatedOverviewResponse(), populatedBreakdownResponse()); + const teardown = await mountRoutes( + page, + populatedOverviewResponse(), + populatedBreakdownResponse(), + ); try { await overviewPage.goto(); @@ -323,9 +343,7 @@ test.describe('Budget Overview — source badge in breakdown (#1390)', { tag: '@ // The source-badge span should now be in the DOM with the correct aria-label. // This confirms the source-badge markup is present on screen; the CSS print fix in // #1390 ensures the label is also visible in print media (tested via unit tests). - await expect( - page.locator('[aria-label="Budget source: Bank Loan"]'), - ).toBeAttached(); + await expect(page.locator('[aria-label="Budget source: Bank Loan"]')).toBeAttached(); } finally { await teardown(); } From c058c986ac978b45929ec80baaa3c3ea6dc8dd8a Mon Sep 17 00:00:00 2001 From: Frank Steiler Date: Sun, 3 May 2026 11:49:48 +0200 Subject: [PATCH 07/11] chore: retrigger promotion CI (#1393) * chore: retrigger promotion CI The auto-fix bot's [skip ci] commit on top of beta blocked all pull_request workflows for promotion PR #1392. This empty no-op commit advances the beta head SHA so Quality Gates and E2E Gates can run on the promotion PR. Co-Authored-By: Claude Opus 4.7 (1M context) * chore: append newline to test pull_request event trigger Co-Authored-By: Claude Opus 4.7 (1M context) --------- Co-authored-by: Frank Steiler Co-authored-by: Claude Opus 4.7 (1M context) --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 5a13ee71..aea10990 100644 --- a/README.md +++ b/README.md @@ -106,3 +106,4 @@ Cornerstone is a personal project built primarily through an agentic development ## License This project is not currently published under an open-source license. + From f8a1d7df063c8a9b041756edabcf8b7914214c3b Mon Sep 17 00:00:00 2001 From: Frank Steiler Date: Sun, 3 May 2026 12:01:04 +0200 Subject: [PATCH 08/11] chore: refire promotion CI (#1394) Add a trailing newline to README to advance the beta SHA via a clean synchronize event. The previous trigger commit accidentally included the directive that suppresses CI in its body, which suppressed all workflow runs for the squash-merged commit on beta. Co-authored-by: Frank Steiler Co-authored-by: Claude Opus 4.7 (1M context) --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index aea10990..c185e907 100644 --- a/README.md +++ b/README.md @@ -107,3 +107,4 @@ Cornerstone is a personal project built primarily through an agentic development This project is not currently published under an open-source license. + From 3018220cdaaa78ea2293cefa6725df02ce660701 Mon Sep 17 00:00:00 2001 From: "cornerstone-bot[bot]" Date: Sun, 3 May 2026 10:02:54 +0000 Subject: [PATCH 09/11] style: auto-fix lint and format [skip ci] --- README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/README.md b/README.md index c185e907..5a13ee71 100644 --- a/README.md +++ b/README.md @@ -106,5 +106,3 @@ Cornerstone is a personal project built primarily through an agentic development ## License This project is not currently published under an open-source license. - - From 0abb37b964ab888a2f8468c29ecc6e12928337db Mon Sep 17 00:00:00 2001 From: Frank Steiler Date: Sun, 3 May 2026 12:29:43 +0200 Subject: [PATCH 10/11] chore: trivial docs bump (#1395) Append a trailing newline to docs/src/intro.md to advance the beta SHA via a clean synchronize event for the promotion PR. The docs directory is ignored by Prettier and ESLint, so the auto-fix bot will not produce a follow-up commit on top. Co-authored-by: Frank Steiler Co-authored-by: Claude Opus 4.7 (1M context) --- docs/src/intro.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/src/intro.md b/docs/src/intro.md index 8e0ef60c..d8dea955 100644 --- a/docs/src/intro.md +++ b/docs/src/intro.md @@ -63,3 +63,4 @@ See the [Roadmap](roadmap) for upcoming features. - [Development](development) -- How Cornerstone is built by an AI agent team - [GitHub Repository](https://github.com/steilerDev/cornerstone) -- Source code and issue tracker - [GitHub Wiki](https://github.com/steilerDev/cornerstone/wiki) -- Technical architecture documentation + From a6c69ea73a56147ffed1485fd8a59af752cd8b12 Mon Sep 17 00:00:00 2001 From: Frank Steiler Date: Sun, 3 May 2026 13:16:39 +0200 Subject: [PATCH 11/11] docs: refresh user-facing docs for v2.5.0 release (#1396) Sync the docs site, README, and release summary with what's actually shipping on beta. - Rewrite Budget Overview guide to match the post-hero-card layout: the page now goes straight from the title bar into the Cost Breakdown Table. Removes the stale Summary Tiles and Remaining Budget Perspectives sections; the Min / Avg / Max perspective toggle and Available Funds row are now described in their actual location (inside the breakdown table). Add a print-mode note about the source-name border treatment landing on printouts. - Add a VAT Handling section to Work Item Budgets covering the always-gross-stored semantics and the unified behavior across direct and unit pricing modes. - Add the missing PAPERLESS_FILTER_TAG row to the Configuration reference table. - Update README Quick Start to mount a backup volume and point at the new Backups guide. - Replace RELEASE_SUMMARY.md with v2.5.0 content covering Backup & Restore (#1386), VAT alignment (#1385), the Budget Overview hero removal (#1389), the printout source-name fix (#1390), and the related-pages link fix (#1384). Co-authored-by: Frank Steiler Co-authored-by: Claude --- README.md | 3 +- RELEASE_SUMMARY.md | 38 ++++++++--- docs/src/getting-started/configuration.md | 1 + docs/src/guides/budget/budget-overview.md | 74 +++++++++------------ docs/src/guides/budget/work-item-budgets.md | 8 +++ 5 files changed, 71 insertions(+), 53 deletions(-) diff --git a/README.md b/README.md index 5a13ee71..e94e2cf0 100644 --- a/README.md +++ b/README.md @@ -59,10 +59,11 @@ docker run -d \ --name cornerstone \ -p 3000:3000 \ -v cornerstone-data:/app/data \ + -v cornerstone-backups:/backups \ steilerdev/cornerstone:latest ``` -Open `http://localhost:3000` -- the setup wizard will guide you through creating your admin account. See the [full deployment guide](https://steilerDev.github.io/cornerstone/getting-started/docker-setup) for Docker Compose, reverse proxy, and OIDC configuration. +Open `http://localhost:3000` -- the setup wizard will guide you through creating your admin account. See the [full deployment guide](https://steilerDev.github.io/cornerstone/getting-started/docker-setup) for Docker Compose, reverse proxy, OIDC, and [scheduled-backup configuration](https://steilerDev.github.io/cornerstone/guides/backup/). ## Roadmap diff --git a/RELEASE_SUMMARY.md b/RELEASE_SUMMARY.md index b6061315..53abc6fc 100644 --- a/RELEASE_SUMMARY.md +++ b/RELEASE_SUMMARY.md @@ -1,15 +1,20 @@ -# v2.4.2 Release Summary +# v2.5.0 Release Summary -A small bug-fix release that tightens up the Budget and Document workflows introduced in v2.4. No new features, no breaking changes, no migration required -- pull and restart. +A focused release that adds **Backup & Restore**, tightens budget VAT handling, and slims down the Budget Overview page. Migration 0031 backfills `includes_vat` on existing budget lines, runs automatically on first start, and requires no manual intervention. + +## What's New + +- **Backup & Restore** -- Cornerstone now ships with a built-in backup feature that snapshots your entire app data directory (SQLite database + diary photos) into a single `tar.gz` archive. Trigger backups manually from the admin UI, run them on a cron schedule, set a retention limit, and restore from any archive in two clicks. Mount a separate volume to `/backups` (or wherever you point `BACKUP_DIR`) and you're set. See the [Backups guide](https://steilerDev.github.io/cornerstone/guides/backup) for setup, scheduling, and restore steps. (#1386) + +## Improvements + +- **Consistent VAT handling across budget lines** (#1385) -- Direct pricing mode now applies the same VAT multiplier as unit pricing (quantity × unit price), so the **Price includes VAT** checkbox behaves identically regardless of which pricing mode you use. Planned amounts are now always stored as gross internally, which means the Budget Overview, Available Funds row, and printed reports compare every line on a like-for-like basis. The `includes_vat` flag is now `NOT NULL` at the database level (defaults to `true`); migration 0031 backfills any pre-existing `NULL` values. ## Bug Fixes -- **Budget source filter now drives every total on the page.** The "Available Funds" and "Remaining Budget" columns in the Cost Breakdown table -- as well as the Pending, Paid, and Quotation summary cards above the table -- now correctly reflect the active source filter. Previously they always showed unfiltered totals, which made the per-source filter misleading when you only wanted to see the picture for a single source. -- **Document picker shows all documents by default.** The "Hide already-linked documents" checkbox in the document picker now starts unchecked, so every document is immediately visible. You no longer have to clear the filter before you can re-link a document that is already attached elsewhere. -- **Mouse wheel no longer changes numeric fields.** Scrolling the page with your mouse wheel while the cursor sits over an Amount or budget field will not accidentally increment or decrement the value -- a common source of silent edits when scrolling long invoice forms. -- **VAT checkbox round-trips correctly.** The VAT / tax checkbox on invoices now preserves its state when you reopen an invoice for editing. Previously the saved state was not always reflected in the form. -- **Vendor picker no longer clears on blur.** Selecting a vendor in the Add Invoice form and then clicking elsewhere on the page (e.g. into the Amount field) no longer clears the selection. -- **Budget Overview summary cards refresh with the source filter.** The Pending, Paid, and Quotation summary cards on the Budget Overview page now refresh correctly when you toggle the source filter, so the headline numbers always match the rows below them. +- **Budget Overview is now the breakdown** (#1389) -- The Budget Health hero card has been removed from the top of the page. The overview now goes straight from the title bar into the Cost Breakdown Table. The Min / Avg / Max perspective toggle, source-filter, and Available Funds row all live inside the table and remain unchanged. The page is faster, prints cleaner, and removes a layer of summary metrics that mostly duplicated what the breakdown already shows. +- **Source name now prints on the Budget Overview** (#1390) -- Print viewports (around 600-720 px) used to trigger the mobile breakpoint, which collapsed the source attribution badge to just a colored dot -- great on a phone, useless on a printout. Print mode now forces the full source name visible with a border-based color treatment, so the printed report shows the actual source attached to each budget line. +- **Broken docs links on the Budget Overview page** (#1384) -- The "Related Pages" links to Work Items and Household Items pointed to non-existent `/overview` sub-paths and now point to the correct guide indices. ## What to Update @@ -17,8 +22,21 @@ A small bug-fix release that tightens up the Budget and Document workflows intro docker pull steilerdev/cornerstone:latest ``` -Restart your container -- no database migration is required. +Restart your container. Migration 0031 runs automatically on first start. + +If you want to enable the new backup feature, mount a backup volume: + +```bash +docker run -d \ + --name cornerstone \ + -p 3000:3000 \ + -v cornerstone-data:/app/data \ + -v cornerstone-backups:/backups \ + steilerdev/cornerstone:latest +``` + +Optionally set `BACKUP_CADENCE` (e.g., `0 2 * * *` for daily at 2 AM) and `BACKUP_RETENTION` (e.g., `7` to keep a week's worth of archives). --- -_Released: 2026-04-28_ +_Released: 2026-05-03_ diff --git a/docs/src/getting-started/configuration.md b/docs/src/getting-started/configuration.md index 4aca320d..b1422e06 100644 --- a/docs/src/getting-started/configuration.md +++ b/docs/src/getting-started/configuration.md @@ -86,5 +86,6 @@ The document integration is automatically enabled when both `PAPERLESS_URL` and | `PAPERLESS_URL` | -- | Base URL of your Paperless-ngx instance used by the server for API calls (e.g., `http://paperless:8000` in Docker) | | `PAPERLESS_API_TOKEN` | -- | API authentication token from Paperless-ngx | | `PAPERLESS_EXTERNAL_URL` | -- | Browser-facing URL for Paperless-ngx links (e.g., `https://paperless.example.com`). If unset, falls back to `PAPERLESS_URL`. | +| `PAPERLESS_FILTER_TAG` | -- | Optional tag name. When set, only Paperless-ngx documents tagged with this name are visible to Cornerstone. Useful for keeping personal documents private when sharing a Paperless-ngx instance across applications. | For detailed setup instructions, see [Documents Setup](/guides/documents/setup). diff --git a/docs/src/guides/budget/budget-overview.md b/docs/src/guides/budget/budget-overview.md index d031ce11..50b6c33f 100644 --- a/docs/src/guides/budget/budget-overview.md +++ b/docs/src/guides/budget/budget-overview.md @@ -5,36 +5,44 @@ title: Budget Overview # Budget Overview -The budget overview dashboard at **Budget > Overview** gives you a high-level view of your project's financial health. It surfaces totals across financing sources, four different "remaining budget" perspectives, and a cost breakdown grouped by **area hierarchy**. +The budget overview at **Budget > Overview** is a single-page report of your project's costs, grouped by **area hierarchy** rather than by category. It rolls everything up from individual budget lines through work items and household items into a clean, printable view of where your money is going -- and which financing source is funding each line. -## Summary Tiles +## Page Layout -At the top of the overview you see a set of summary tiles -- Total Budget, Total Estimated, Total Invoiced, Total Remaining, and one per financing source. Each tile is **clickable**: clicking a tile selects every matching budget line in the table below, so you can jump straight from a headline number into the underlying lines that drive it. Click the same tile again (or click in empty space) to clear the selection. +The page renders the **Cost Breakdown Table** as its primary view, with a per-source filter, a min / avg / max perspective toggle inside the table, and a built-in **Available Funds** row that summarizes each financing source. -## Remaining Budget Perspectives +If your project has no budget data yet, you see a short empty state inviting you to add work items, household items, or invoices. Once you have a few budget lines, the breakdown takes over the page. -The overview provides four ways to look at how much budget remains, each answering a different question: +## Cost Breakdown by Area -| Perspective | Calculation | What It Tells You | -|------------|-------------|-------------------| -| **vs Min Planned** | Financing - (Estimated x (1 - margin)) | Best-case remaining budget assuming all estimates come in under | -| **vs Max Planned** | Financing - (Estimated x (1 + margin)) | Worst-case remaining budget assuming all estimates come in over | -| **vs Actual Cost** | Financing - Actual costs | Remaining budget based on real invoice amounts where available | -| **vs Actual Paid** | Financing - Paid amounts | Remaining budget based on what has actually been paid out | +The cost breakdown table is grouped by your **area hierarchy** rather than by category. This makes it easy to see what each room, floor, or zone of the project actually costs. -Switch between perspectives to understand your financial position from different angles. Early in a project, the min/max planned views are most useful. As invoices arrive, the actual cost and actual paid views become more meaningful. +- Each **area** is a row. Its totals roll up every descendant area beneath it. +- Clicking a row expands it to show child areas and, at the leaf level, the individual budget lines. +- Nested rows are visually indented so the tree is easy to scan. +- Budget lines whose work item or household item has no area assigned are collected in a dedicated **No Area** bucket at the bottom of the table. -## How Projections Work +Each row displays the projected cost, subsidy payback, and remaining amount for that slice of the project. -The budget overview uses a **blended projection model** that combines estimates and actuals: +### Cost Perspectives -- **Budget lines linked to a paid, pending, or claimed invoice** use the itemized invoice amount (0% margin) -- **Budget lines linked to a quotation** use the itemized amount with a +/- 5% margin -- **Budget lines without an invoice link** use the estimated amount with the confidence margin +A **Min / Avg / Max** segmented control above the table switches the projected-cost calculation between three views: + +| Perspective | What It Tells You | +|------------|-------------------| +| **Min** | Best-case cost assuming all estimates come in under their confidence margin | +| **Avg** | Mid-point cost using the middle of each estimate's confidence range | +| **Max** | Worst-case cost assuming all estimates come in over their confidence margin | + +Switch between perspectives to understand your financial position from different angles. Early in a project, Min and Max bracket your exposure. As invoices arrive and confidence levels rise, the three views converge. -This means your projections automatically become more accurate as your project progresses and estimates are replaced by real invoices. +### How Projections Work -### Confidence Margins +The breakdown uses a **blended projection model** that combines estimates and actuals: + +- **Budget lines linked to a paid, pending, or claimed invoice** use the itemized invoice amount (0% margin) +- **Budget lines linked to a quotation** use the itemized amount with a +/- 5% margin +- **Budget lines without an invoice link** use the planned amount with the confidence margin The margin applied to non-invoiced budget lines depends on the confidence level: @@ -45,16 +53,7 @@ The margin applied to non-invoiced budget lines depends on the confidence level: | Quote | +/- 5% | | Invoice | 0% (actual cost used) | -## Cost Breakdown by Area - -The cost breakdown table is grouped by your **area hierarchy** rather than by category. This makes it easy to see what each room, floor, or zone of the project actually costs. - -- Each **area** is a row. Its totals roll up every descendant area beneath it. -- Clicking a row expands it to show child areas and, at the leaf level, the individual budget lines. -- Nested rows are visually indented so the tree is easy to scan. -- Budget lines whose work item or household item has no area assigned are collected in a dedicated **No Area** bucket at the bottom of the table (previously labeled "Unassigned"). - -Each row displays the estimated total, invoiced total, subsidy reduction, and remaining amount for that slice of the project. +This means projections automatically become more accurate as your project progresses and estimates are replaced by real invoices. ### Source Attribution Badges @@ -79,28 +78,18 @@ This makes it easy to spot which source is most depleted, which one is being sub Click any source detail row inside the **Available Funds** expansion to toggle that source on or off. Deselected sources are dropped from the entire breakdown: -- The summary tiles, projected cost range, every nested area row, and the **Available Funds** and **Remaining Budget** (Cost + Net) totals all recalculate against the visible set in real time as you toggle. +- The projected cost range, every nested area row, and the **Available Funds** and **Remaining Budget** (Cost + Net) totals all recalculate against the visible set in real time as you toggle. - A small "X of N selected" caption appears next to **Available Funds** while a filter is active. - The selection is **persisted in the URL** as `?deselectedSources=,` so you can bookmark a filtered view, share it with your bank or partner, or refresh without losing state. - Press **Escape** while focused on a source row to clear all deselections in one go. - Source detail rows stay visible even when every source is deselected -- the filter is never a dead-end; you can always click your way back in. - When you print a filtered view, deselected source rows are hidden from the printed output so the report only shows the sources you actually have selected. -Filtering happens **server-side** (`GET /api/budget/breakdown?deselectedSources=...`), which means subsidy payback math stays consistent with the visible set: subsidies that no longer have any qualifying budget lines drop out cleanly instead of double-counting. The Pending, Paid, and Quotation summary cards at the top of the page also refresh in step with the filter -- pick the sources you care about and the headline numbers update without leaving the page. - -## Financing Source Summary - -A summary of each financing source shows: - -- Total amount available -- Current depletion (based on actual invoice costs) -- Remaining balance - -For a much deeper view of each source -- including every budget line attached to it, grouped by area and work item, with multi-select and mass-move -- see [Financing Sources](financing-sources). +Filtering happens **server-side** (`GET /api/budget/breakdown?deselectedSources=...`), which means subsidy payback math stays consistent with the visible set: subsidies that no longer have any qualifying budget lines drop out cleanly instead of double-counting. ## Subsidy Impact -Approved and disbursed [subsidies](subsidies) are factored into the overview calculations. The dashboard shows how much each subsidy reduces the total cost for its linked category. Pending and rejected subsidies are excluded from calculations. +Approved and disbursed [subsidies](subsidies) are factored into the breakdown calculations. The Available Funds row shows how much each subsidy reduces the net cost for its linked source. Pending and rejected subsidies are excluded from calculations. ## Printing the Overview @@ -110,6 +99,7 @@ The Budget Overview has dedicated **print styling** so you can hand your bank, a - The app chrome -- sidebar, navigation, floating buttons -- is suppressed in print. - Page margins, title spacing, and nested area group boxes are tuned for A4/Letter output. - Inner item separators keep individual budget lines readable when an area group contains many children. +- Source attribution badges keep their **full source name** on the printed page, with a border-based color treatment so the source is legible even if your printer doesn't preserve background colors. - The browser's own print header/footer is suppressed; pick your target (printer or "Save as PDF") and go. :::tip diff --git a/docs/src/guides/budget/work-item-budgets.md b/docs/src/guides/budget/work-item-budgets.md index ab290f0a..f643d6a8 100644 --- a/docs/src/guides/budget/work-item-budgets.md +++ b/docs/src/guides/budget/work-item-budgets.md @@ -44,3 +44,11 @@ See [Invoices & Vendors](vendors-and-invoices) for details on managing invoices A single work item can have multiple budget lines. For example, "Renovate bathroom" might have separate budget lines for plumbing, electrical, and tiling -- each in a different category and potentially funded by different financing sources. +## VAT Handling + +The budget line form has a **Price includes VAT** checkbox. When entering an amount that already includes VAT (gross), leave the box checked; when entering a net amount, uncheck the box and Cornerstone will apply the VAT multiplier on save. + +Internally, planned amounts are always stored as gross (VAT-inclusive). The checkbox controls how Cornerstone interprets your input, not how the value is stored -- so all comparisons in the [Budget Overview](budget-overview), Available Funds row, and printed reports are like-for-like across budget lines, regardless of the pricing mode you chose when entering each one. The same behavior applies whether you use direct pricing or unit pricing (quantity × unit price) on the budget line. + + +