import type { BudgetParticipantFinal, BudgetUnconverted, CostCategory, TripCostsMode } from '@trek/shared'; import { readDateFormat } from '../../hooks/useDateFormat'; import { convertBooked, convertedLine, inDisplayCurrency, tripAmountOf } from '../../hooks/useExchangeRates'; import type { BudgetItem } from '../../types'; import { formatDisplayDate } from '../../utils/dateFormat'; import { currencyDecimals } from '../../utils/formatters'; import { currenciesWith, SYMBOLS } from './BudgetPanel.constants'; import { hasTicketSplit, paidByUser, readUserNote, settlementDate, splitEqualShares } from './CostsPanel.helpers'; import { catMeta, COST_CATEGORY_LIST } from './costsCategories'; /** * Costs view-model: the ledger maths both Costs surfaces run on, the desktop * `CostsPanel.tsx` and the phone `MCostsTab.tsx` (baseTotal, myPaidOf, the * shares, isUnfinished, totals, filters, payments, the category breakdown and * the CSV), so the two never disagree. Decoupled from React so it stays * testable. Money is converted to the display/base currency via an injected * `convert` (from `useExchangeRates`), never computed here. */ /** Per-render context every money computation needs — cheap to build, memoize in the caller. */ export interface CostsCtx { me: number; /** The trip's own currency — what a NULL `budget_items.currency` means. */ tripCurrency: string; /** The currency everything is shown in, the base `convert` converts to. */ displayCurrency: string; convert: (amount: number, currency: string | null | undefined) => number; } /** An expense's own currency, defaulting to the trip currency (NULL column = trip currency). */ export function currencyOf(e: BudgetItem, ctx: CostsCtx): string { return (e.currency || ctx.tripCurrency).toUpperCase(); } /** * An amount of this expense in the display currency, at the rate the expense was booked at; * as typed when it was entered in the display currency (#2965). */ export function booked(amount: number, e: BudgetItem, ctx: CostsCtx): number { if (inDisplayCurrency(e.currency, ctx.tripCurrency, ctx.displayCurrency)) return amount; return convertBooked(amount, e.currency, e.exchange_rate, ctx.tripCurrency, ctx.convert); } /** * The line under an amount of this expense the list shows converted, what was entered and * where it went (#2525); null when there is nothing to explain. `shown` is the display * value printed beside it. */ export function lineOf(amount: number, e: BudgetItem, ctx: CostsCtx, shown: number) { return convertedLine(amount, e.currency, e.exchange_rate, ctx.tripCurrency, ctx.displayCurrency, shown); } /** Expense total converted to the display/base currency, at its booked rate. */ export function baseTotal(e: BudgetItem, ctx: CostsCtx): number { return booked(e.total_price || 0, e, ctx); } /** How much `ctx.me` personally fronted for this expense, in the base currency. */ export function myPaidOf(e: BudgetItem, ctx: CostsCtx): number { return booked(paidByUser(e, ctx.me), e, ctx); } /** A given member's share of this expense (explicit custom amount, else equal split), base currency. */ export function memberShareOf(e: BudgetItem, userId: number, ctx: CostsCtx): number { const member = (e.members || []).find((m) => m.user_id === userId); if (!member) return 0; if (member.amount !== null && member.amount !== undefined) { return booked(member.amount, e, ctx); } const shares = splitEqualShares(e.total_price || 0, e.members || [], e.id); return booked(shares[userId] || 0, e, ctx); } /** `ctx.me`'s own share — the common case of {@link memberShareOf}. */ export function myShareOf(e: BudgetItem, ctx: CostsCtx): number { return memberShareOf(e, ctx.me, ctx); } /** How a ledger counts `ctx.me`'s share of one expense, for the totals and the "owed" filter. */ export type ShareOf = (e: BudgetItem, ctx: CostsCtx) => number; /** * A recorded total nobody has actually paid yet — counts toward the trip total * but stays out of settlement. A negative total (a refund, #2176) is just as * unfinished until its recipient is recorded as the (negative) payer. */ export function isUnfinished(e: BudgetItem, ctx: CostsCtx): boolean { return baseTotal(e, ctx) !== 0 && (e.payers || []).filter((p) => p.amount !== 0).length === 0; } /** * `ctx.me`'s share as the desktop ledger counts it: nobody paid, so nobody owes. * The ledger skips an unfinished expense entirely (#2225), and counting it here * left the tile contradicting the balances right beside it. */ export function settledShareOf(e: BudgetItem, ctx: CostsCtx): number { return isUnfinished(e, ctx) ? 0 : myShareOf(e, ctx); } // ── settlement (server-computed; these types describe what both ledgers read from it) ── export interface CostsSettlementFlow { from: { user_id: number; username: string; avatar_url?: string | null }; to: { user_id: number; username: string; avatar_url?: string | null }; amount: number; } export interface CostsBalance { user_id: number; username: string; avatar_url: string | null; balance: number; } /** A recorded settle-up transfer ("Ajouter un paiement") — history, not a suggestion like {@link CostsSettlementFlow}. */ export interface CostsSettlement { id: number; from_user_id: number; to_user_id: number; amount: number; // Legacy rows predate this column (null) and are read as the display currency. currency?: string | null; // The rate frozen when the transfer was settled, units of `currency` per 1 trip // currency (#1445). Absent, or exactly 1, on rows written before the freeze existed. exchange_rate?: number; created_at?: string; // The day the transfer actually happened; editable, unlike created_at (when it // was recorded). Null/absent on rows predating this field. settled_at?: string | null; /** A free-text note on the payment (#2340). */ note?: string | null; } /** The currency a recorded payment was entered in: legacy rows without one were in the display currency. */ function paymentCurrency(s: CostsSettlement, ctx: CostsCtx): string { return (s.currency || ctx.displayCurrency).toUpperCase(); } /** * A recorded payment in the display currency, at the rate frozen when it was settled (#1445); * as entered when it was made in the display currency (#2965). */ export function paymentAmount(s: CostsSettlement, ctx: CostsCtx): number { const currency = paymentCurrency(s, ctx); if (inDisplayCurrency(currency, ctx.tripCurrency, ctx.displayCurrency)) return s.amount; return convertBooked(s.amount, currency, s.exchange_rate, ctx.tripCurrency, ctx.convert); } /** The line under a payment shown converted, explained the way an expense's is (#2525). */ export function paymentLineOf(s: CostsSettlement, ctx: CostsCtx, shown: number) { return convertedLine( s.amount, paymentCurrency(s, ctx), s.exchange_rate, ctx.tripCurrency, ctx.displayCurrency, shown ); } export interface CostsSettlementResponse { balances: CostsBalance[]; flows: CostsSettlementFlow[]; settlements: CostsSettlement[]; /** What the trip ends up costing each participant — netted server-side off the same ledger as `balances`. */ finalBudgets: BudgetParticipantFinal[]; /** The currency the figures are in: the display currency, or the trip's own without a quote for it. */ currency?: string; /** Rows no rate could convert, left out of every figure above. */ unconverted?: BudgetUnconverted; } // ── who paid and the shares: when Costs shows them ───────────────────────── /** * Whether Costs shows the splitting side: who paid, the shares, the balances * and settling up. A trip that keeps its costs as totals only leaves it out * (#1714), whatever is stored. A trip of one has nothing to split, since every * share is the whole amount and nobody can owe anybody (#2689), so it is left * out there too, unless the ledger still names someone else: a traveller who * left the trip with money open, or members that have not loaded yet. */ export function showsSplitting( costsMode: TripCostsMode | undefined, memberCount: number, items: BudgetItem[], settlement: Pick | null, me: number ): boolean { if (costsMode === 'totals') return false; if (memberCount > 1) return true; const namesOthers = items.some((e) => [...(e.payers || []), ...(e.members || [])].some((p) => p.user_id !== me)); const moneyOpen = (settlement?.balances || []).some((b) => Math.abs(b.balance) >= 0.005); return namesOthers || moneyOpen || (settlement?.flows || []).length > 0; } /** * Whether an expense's payers and split hold nothing beyond the obvious, so an * editor that leaves them out of sight loses nothing by it: at most one payer, * an equal split, no receipt lines, and only people still on the trip. A new * expense (null) has nothing yet. */ export function isPlainSplit(e: BudgetItem | null, memberIds: number[]): boolean { if (!e) return true; const payers = (e.payers || []).filter((p) => p.amount !== 0); const members = e.members || []; const people = [...payers, ...members].map((p) => p.user_id); return ( payers.length <= 1 && !hasTicketSplit(e) && members.every((m) => m.amount === null || m.amount === undefined) && people.every((id) => memberIds.includes(id)) ); } // ── hero / tile totals (spec §3.1-§3.3) ──────────────────────────────────── export interface CostsTotals { totalSpend: number; myPaid: number; myShare: number; owe: number; owed: number; outstanding: number; outstandingCount: number; } export function computeTotals( items: BudgetItem[], flows: CostsSettlementFlow[], ctx: CostsCtx, shareOf: ShareOf = myShareOf ): CostsTotals { const totalSpend = items.reduce((a, e) => a + baseTotal(e, ctx), 0); const myPaid = items.reduce((a, e) => a + myPaidOf(e, ctx), 0); const myShare = items.reduce((a, e) => a + shareOf(e, ctx), 0); const owe = flows.filter((f) => f.from.user_id === ctx.me).reduce((a, f) => a + f.amount, 0); const owed = flows.filter((f) => f.to.user_id === ctx.me).reduce((a, f) => a + f.amount, 0); const outstandingItems = items.filter((e) => isUnfinished(e, ctx)); const outstanding = outstandingItems.reduce((a, e) => a + baseTotal(e, ctx), 0); return { totalSpend, myPaid, myShare, owe, owed, outstanding, outstandingCount: outstandingItems.length }; } // ── expenses list: filter + group (spec §3.6-§3.7) ───────────────────────── export type CostsSegment = 'all' | 'mine' | 'owed'; export interface CostsFilterState { search: string; segment: CostsSegment; /** '' = all categories */ categoryKey: string; /** '' = all days, else the expense's own YYYY-MM-DD */ dayKey: string; } const round2 = (n: number) => Math.round(n * 100) / 100; /** * `mine`/`owed` use the real balance, not the demo's `payer==='you'` shortcut * (spec 03 §3.6): `mine` = I fronted money on it, `owed` = I'm net owed on it. */ export function filterBudgetItems( items: BudgetItem[], f: CostsFilterState, ctx: CostsCtx, shareOf: ShareOf = myShareOf ): BudgetItem[] { let list = items.slice(); if (f.segment === 'mine') list = list.filter((e) => myPaidOf(e, ctx) > 0); if (f.segment === 'owed') list = list.filter((e) => round2(myPaidOf(e, ctx) - shareOf(e, ctx)) > 0); if (f.categoryKey) list = list.filter((e) => catMeta(e.category).key === f.categoryKey); if (f.dayKey) list = list.filter((e) => (e.expense_date || '') === f.dayKey); const q = f.search.trim().toLowerCase(); if (q) list = list.filter((e) => e.name.toLowerCase().includes(q)); return list; } export interface CostsDayGroup { /** '' = no date (spec's "NO DATE" group) */ dateKey: string; items: BudgetItem[]; } /** Groups by `expense_date`, newest first, the no-date bucket sinking to the end (spec §3.7). */ export function groupByDay(items: BudgetItem[]): CostsDayGroup[] { const byDate = new Map(); for (const e of items) { const key = e.expense_date || ''; const bucket = byDate.get(key); if (bucket) bucket.push(e); else byDate.set(key, [e]); } const keys = Array.from(byDate.keys()).sort((a, b) => { if (a === b) return 0; if (a === '') return 1; if (b === '') return -1; return b.localeCompare(a); }); return keys.map((dateKey) => ({ dateKey, items: byDate.get(dateKey) as BudgetItem[] })); } /** * Settlements ("payments") shown inline in the ledger: they have no name or * category, so a text or category filter hides them; "owed" excludes them; * "mine" keeps only transfers the current user is part of. */ export function filterSettlements(settlements: CostsSettlement[], f: CostsFilterState, me: number): CostsSettlement[] { if (f.search.trim() || f.categoryKey) return []; if (f.segment === 'owed') return []; let list = settlements.slice(); if (f.segment === 'mine') list = list.filter((s) => s.from_user_id === me || s.to_user_id === me); if (f.dayKey) list = list.filter((s) => settlementDate(s) === f.dayKey); return list; } export type CostsLedgerEntry = { kind: 'expense'; date: string; item: BudgetItem } | { kind: 'payment'; date: string; settlement: CostsSettlement }; export interface CostsLedgerDayGroup { /** '' = no date (spec's "NO DATE" group) */ dateKey: string; entries: CostsLedgerEntry[]; } /** * Like {@link groupByDay}, but also folds in settlement payments (see * {@link filterSettlements}) as their own ledger entries, keyed by * {@link settlementDate} — the mobile counterpart to desktop's unified * `LedgerEntry` grouping, so a payment shows up even on a day with no expense. */ export function groupLedgerByDay(items: BudgetItem[], settlements: CostsSettlement[]): CostsLedgerDayGroup[] { const entries: CostsLedgerEntry[] = [ ...items.map((item) => ({ kind: 'expense' as const, date: item.expense_date || '', item })), ...settlements.map((settlement) => ({ kind: 'payment' as const, date: settlementDate(settlement), settlement })), ]; const byDate = new Map(); for (const en of entries) { const bucket = byDate.get(en.date); if (bucket) bucket.push(en); else byDate.set(en.date, [en]); } const keys = Array.from(byDate.keys()).sort((a, b) => { if (a === b) return 0; if (a === '') return 1; if (b === '') return -1; return b.localeCompare(a); }); return keys.map((dateKey) => ({ dateKey, entries: byDate.get(dateKey) as CostsLedgerEntry[] })); } /** Categories present among `items`, canonical order — the dropdown only lists categories in use (spec §3.6). */ export function categoryFilterKeys(items: BudgetItem[]): CostCategory[] { const present = new Set(items.map((e) => catMeta(e.category).key)); return COST_CATEGORY_LIST.map((c) => c.key).filter((k) => present.has(k)); } /** Distinct expense dates, ascending (spec §3.6: "Tage mit Ausgaben aufsteigend"). */ export function dayFilterKeys(items: BudgetItem[]): string[] { const dates = new Set(items.map((e) => e.expense_date).filter((d): d is string => Boolean(d))); return Array.from(dates).sort((a, b) => a.localeCompare(b)); } // ── by-category breakdown (spec §3.5) ─────────────────────────────────────── export interface CostsCategoryBar { key: CostCategory; amount: number; /** 0-100, relative to the largest category (not the grand total) — spec §3.5. */ widthPct: number; } export function categoryBreakdown(items: BudgetItem[], ctx: CostsCtx): CostsCategoryBar[] { // Categories net refunds against spend (#2176): a negative entry lowers its // category's sum. A category that nets negative keeps its own row at the // bottom, with widthPct 0 — the bars rank positive spend, and a negative // CSS width would be dropped and render as a full bar. const totals = new Map(); for (const e of items) { const key = catMeta(e.category).key; totals.set(key, (totals.get(key) || 0) + baseTotal(e, ctx)); } const rows = COST_CATEGORY_LIST.map((c) => ({ key: c.key, amount: totals.get(c.key) || 0 })) .filter((r) => r.amount !== 0) .sort((a, b) => b.amount - a.amount); const max = Math.max(0, ...rows.map((r) => r.amount)); return rows.map((r) => ({ ...r, widthPct: max > 0 && r.amount > 0 ? (r.amount / max) * 100 : 0 })); } // ── presentation helpers ───────────────────────────────────────────────── /** Category colour at a fixed alpha — the expense card's border tint (spec §3.10: "brC"). */ export function tint(hex: string, alpha: number): string { const clean = hex.replace('#', ''); const r = Number.parseInt(clean.slice(0, 2), 16); const g = Number.parseInt(clean.slice(2, 4), 16); const b = Number.parseInt(clean.slice(4, 6), 16); return `rgba(${r}, ${g}, ${b}, ${alpha})`; } // ── CSV export (spec §3.8 `csvGo`; string-building only — the caller turns this into a download) ── export interface CsvBuildOptions { base: string; ctx: CostsCtx; locale: string; tripTitle?: string | null; t: (key: string) => string; /** The Currency column; {@link currencyOf} unless the caller writes it as stored. */ currencyOf?: (e: BudgetItem) => string; } /** The Costs CSV export's rows, one per expense, oldest first; the Blob/download is a DOM concern left to the caller. */ export function buildCostsCsv(items: BudgetItem[], opts: CsvBuildOptions): { filename: string; content: string } { const sep = ';'; // A cell starting with =, +, -, @, TAB or CR is evaluated as a formula by Excel // and Sheets, and the name/note columns are free text any trip member can write. const esc = (v: unknown) => { let s = String(v ?? ''); if (/^[=+\-@\t\r]/.test(s)) s = "'" + s; return s.includes(sep) || s.includes('"') || s.includes('\n') ? '"' + s.replace(/"/g, '""') + '"' : s; }; const fmtDate = (iso: string) => { if (!iso) return ''; try { return formatDisplayDate( new Date(iso + 'T00:00:00Z'), opts.locale, { day: '2-digit', month: '2-digit', year: 'numeric', timeZone: 'UTC', }, readDateFormat() ); } catch { return iso; } }; // Read in another currency than the trip's, what each row counts as in the trip currency // too, the figure every sum is built from (#2525). const trip = opts.ctx.tripCurrency.toUpperCase(); const tripCol = trip !== opts.base.toUpperCase(); const header = [ 'Date', 'Name', 'Category', 'Amount', 'Currency', ...(tripCol ? [`Amount (${trip})`] : []), `Amount (${opts.base})`, 'Note', ]; const rows = [header.join(sep)]; const sorted = items.slice().sort((a, b) => (a.expense_date || '').localeCompare(b.expense_date || '')); for (const e of sorted) { const cur = opts.currencyOf ? opts.currencyOf(e) : currencyOf(e, opts.ctx); const note = readUserNote(e); const inTrip = tripAmountOf(e.total_price || 0, e.currency, e.exchange_rate, trip, opts.ctx.convert); rows.push( [ esc(fmtDate(e.expense_date || '')), esc(e.name), esc(opts.t(catMeta(e.category).labelKey)), (e.total_price || 0).toFixed(currencyDecimals(cur)), cur, ...(tripCol ? [inTrip.toFixed(currencyDecimals(trip))] : []), baseTotal(e, opts.ctx).toFixed(currencyDecimals(opts.base)), esc(note), ].join(sep) ); } const safeName = (opts.tripTitle || 'trip').replace(/[^a-zA-Z0-9À-ɏ _-]/g, '').trim(); return { filename: `costs-${safeName}.csv`, content: rows.join('\r\n') }; } /** * The currency picker of every Costs form (expense and payment, desktop and * phone): the supported currencies plus the one already chosen, each labelled * with its code and, when it has one, its symbol. `pinned` ones lead the list * in the order given, so the few a trip really uses are not buried in the * alphabet (#2807). */ export function currencyOptions( current?: string | null, pinned: readonly string[] = [] ): { value: string; label: string }[] { const all = currenciesWith(current); const lead = [...new Set(pinned.map((c) => c.toUpperCase()))].filter((c) => all.includes(c)); const ordered = [...lead, ...all.filter((c) => !lead.includes(c))]; return ordered.map((c) => ({ value: c, label: SYMBOLS[c] ? `${c} ${SYMBOLS[c]}` : c })); }