Reports frontend — spec-driven generate form, sliceable viewer, dimension bars (#16)

# MR: Reports frontend — spec-driven generate form, sliceable viewer, dimension bars

**Branch:** `cached-reporting` → **Target:** `main`

## Summary

Reports UI rebuilt to treat the backend OpenAPI spec as the source of truth: the
generate-report form renders generically from `ReportQuery`, and the viewer displays
API-computed metrics verbatim instead of recomputing them client-side.

## Changes

### react-openapi (library)
- `MultiEnumField` renderer for array-of-enum fields; dispatch branch in
  `FormFieldRenderer`
- `useFkFieldOptions` hook + `FKFieldConfig.value` (FK options keyed by a non-PK
  field — accounts resolve by `name`)
- `FieldConfig.defaultValue` seeding in `extractFields`; enum lift for
  `items.enum` arrays; sanitize-payload bypasses FK resolution when `fk.value` is set

### Reports page
- **GenerateReportPanel**: rewritten (~275 → ~110 lines) — fields extracted from the
  served `ReportQuery` schema (labels, order, defaults, multi-enum, account picker);
  server-side validation only
- **ReportViewer**:
  - Period groups built from cube buckets keyed by canonical `period_id`; buckets
    merged per period (disjoint slices), txn ids deduped
  - Cards/bars/metric strips read `metrics` verbatim (outflows/inflows/sum/count/
    avg/min/max/cadence/frequency); Net = one subtraction at render
  - Dimension-switchable bar strip (Period / Payees / Tags): segmented pill control
    with sliding indicator; pills disabled when the report has ≤1 distinct value;
    top-10 bars in a fixed view paged by chevrons (hidden scrollbar)
  - Active dim requests the full distribution via `payee=*` / `tags=*` when its own
    filter is unselected; explicit selections always slice normally
- **TransactionList**: shared component with optional `groups` prop (API periods +
  metrics) used by the viewer; Expense page keeps the client-side fallback path;
  group strip shows Sum · Avg · Min · Max · Cadence (or Frequency /day when
  cadence < 1)

### Fixes
- Strict DD-MM-YYYY parsing (`parseOccurredAt`) in period merges and date ordering —
  `new Date()` mis-read dates as MM-DD-YYYY and corrupted merged cadence
  (Aug Zomato: 12.89 days displayed vs 0.76 actual)
- Bar widths magnitude-based so all-outflow slices render at proper width

Reviewed-on: #16
Co-authored-by: Vishesh 'ironeagle' Bangotra <aetoskia@gmail.com>
Co-committed-by: Vishesh 'ironeagle' Bangotra <aetoskia@gmail.com>

src/common/utils/transactions.ts

@@ -0,0 +1,161 @@
+import type { ExpenseItem } from "../types";
+import { dateLabel, monthKey, monthLabel, parseOccurredAt } from "./dates";
+
+export function isExpense(item: ExpenseItem): boolean {
+  return (item.amount ?? 0) < 0;
+}
+
+export interface DateGroup {
+  date: string;
+  label: string;
+  items: ExpenseItem[];
+}
+
+export function groupByDate(items: ExpenseItem[]): DateGroup[] {
+  const sorted = [...items].sort(
+    (a, b) => parseOccurredAt(b.occurred_at).getTime() - parseOccurredAt(a.occurred_at).getTime(),
+  );
+  const map = new Map<string, ExpenseItem[]>();
+  for (const item of sorted) {
+    const key = item.occurred_at ?? "";
+    const list = map.get(key) ?? [];
+    list.push(item);
+    map.set(key, list);
+  }
+  return [...map.entries()].map(([date, list]) => ({
+    date,
+    label: dateLabel(date),
+    items: list,
+  }));
+}
+
+export type PeriodGranularity = "weekly" | "monthly" | "quarterly" | "yearly";
+
+export interface PeriodGroup {
+  key: string;
+  label: string;
+  items: ExpenseItem[];
+  spent: number;
+  income: number;
+  currency: string;
+}
+
+/** Metrics verbatim from the API's ReportMetrics (camelCased). */
+export interface ListGroupMetrics {
+  sum: number;
+  count: number;
+  avg: number | null;
+  min: number | null;
+  max: number | null;
+  cadence: number | null;
+  frequency: number | null;
+}
+
+export interface ListPeriodGroup extends PeriodGroup {
+  metrics?: ListGroupMetrics;
+}
+
+function isoWeekKey(d: Date): string {
+  const date = new Date(Date.UTC(d.getFullYear(), d.getMonth(), d.getDate()));
+  const day = date.getUTCDay() || 7;
+  date.setUTCDate(date.getUTCDate() + 4 - day);
+  const yearStart = new Date(Date.UTC(date.getUTCFullYear(), 0, 1));
+  const week = Math.ceil(((date.getTime() - yearStart.getTime()) / 86400000 + 1) / 7);
+  return `${date.getUTCFullYear()}-W${String(week).padStart(2, "0")}`;
+}
+
+function quarterKey(d: Date): string {
+  return `${d.getFullYear()}-Q${Math.floor(d.getMonth() / 3) + 1}`;
+}
+
+export function periodKey(value: string | undefined, granularity: PeriodGranularity): string {
+  const d = parseOccurredAt(value);
+  switch (granularity) {
+    case "weekly":
+      return isoWeekKey(d);
+    case "quarterly":
+      return quarterKey(d);
+    case "yearly":
+      return String(d.getFullYear());
+    default:
+      return monthKey(value);
+  }
+}
+
+export function periodLabel(key: string, granularity: PeriodGranularity): string {
+  switch (granularity) {
+    case "weekly":
+    case "yearly":
+      return key;
+    case "quarterly": {
+      const [y, q] = key.split("-Q");
+      return `Q${q} ${y}`;
+    }
+    default:
+      return monthLabel(key);
+  }
+}
+
+export function groupByPeriod(items: ExpenseItem[], granularity: PeriodGranularity = "monthly"): PeriodGroup[] {
+  const map = new Map<string, ExpenseItem[]>();
+  for (const item of items) {
+    const key = periodKey(item.occurred_at, granularity);
+    const list = map.get(key) ?? [];
+    list.push(item);
+    map.set(key, list);
+  }
+  return [...map.entries()]
+    .map(([key, list]) => {
+      const sorted = [...list].sort(
+        (a, b) => parseOccurredAt(b.occurred_at).getTime() - parseOccurredAt(a.occurred_at).getTime(),
+      );
+      const currency = sorted.find((it) => it.account?.currency)?.account?.currency ?? "INR";
+      const spent = sorted.filter(isExpense).reduce((sum, it) => sum + Math.abs(it.amount ?? 0), 0);
+      const income = sorted.filter((it) => !isExpense(it)).reduce((sum, it) => sum + (it.amount ?? 0), 0);
+      return { key, label: periodLabel(key, granularity), items: sorted, spent, income, currency };
+    })
+    .sort((a, b) => b.key.localeCompare(a.key));
+}
+
+export interface TxnMetrics {
+  sum: number;
+  count: number;
+  avg: number | null;
+  min: number | null;
+  max: number | null;
+  cadenceDays: number | null;
+  frequency: number | null;
+}
+
+/** Mirrors backend ReportMetrics.compute_metrics over a list of transactions. */
+export function computeTxnMetrics(items: ExpenseItem[]): TxnMetrics {
+  const amounts = items.filter((it) => typeof it.amount === "number").map((it) => it.amount as number);
+  const empty = { sum: 0, count: 0, avg: null, min: null, max: null, cadenceDays: null, frequency: null };
+  if (amounts.length === 0) {
+    return empty;
+  }
+  const dates = items
+    .map((it) => it.occurred_at)
+    .filter((d): d is string => !!d)
+    .map((d) => parseOccurredAt(d).getTime())
+    .sort((a, b) => a - b);
+  const sum = amounts.reduce((s, a) => s + a, 0);
+  let cadenceDays: number | null = null;
+  if (dates.length >= 2) {
+    const gaps: number[] = [];
+    for (let i = 0; i < dates.length - 1; i += 1) {
+      gaps.push((dates[i + 1] - dates[i]) / 86400000);
+    }
+    cadenceDays = Math.round((gaps.reduce((s, g) => s + g, 0) / gaps.length) * 100) / 100;
+  }
+  const frequency = cadenceDays != null && cadenceDays > 0 ? Math.round((1 / cadenceDays) * 100) / 100 : null;
+  return {
+    sum,
+    count: amounts.length,
+    avg: sum / amounts.length,
+    min: Math.min(...amounts),
+    max: Math.max(...amounts),
+    cadenceDays,
+    frequency,
+  };
+}