@butinapp/ui 0.1.0

package/dist/features/dashboard/timeseries-chart.js

@@ -0,0 +1,191 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { MONTH_ABBR } from '@butinapp/sdk/util';
+import { ChevronDown, ChevronLeft, ChevronRight } from 'lucide-react';
+import { useMemo, useState } from 'react';
+import { Card, CardContent, CardHeader, CardTitle } from '../../components/card.js';
+import { DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuTrigger } from '../../components/dropdown-menu.js';
+import { EChart } from '../../components/echart.js';
+import { useLabels } from '../../i18n/context.js';
+import { grid, useEchartsTheme } from '../../lib/echarts-theme.js';
+import { formatMoney, formatMoneyCompact } from '../../lib/format.js';
+import {} from './view-models.js';
+const monthLabel = (key) => {
+    const [y, m] = key.split('-');
+    return `${MONTH_ABBR[Number(m) - 1] ?? m} '${(y ?? '').slice(2)}`;
+};
+// 'YYYY-MM-DD' -> a short day axis label, e.g. 'Jun 3'.
+const dayLabel = (key) => {
+    const [, m, d] = key.split('-');
+    return `${MONTH_ABBR[Number(m) - 1] ?? m} ${Number(d)}`;
+};
+const monthOf = (key) => key.slice(0, 7);
+const nowMonthKey = () => {
+    const d = new Date();
+    return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}`;
+};
+// A muted, hatched bar marks an in-progress / gap-filled value (a synthesized day, or the current month
+// projected from its MTD) so it reads distinctly from a settled bar.
+const estimatedBar = (color) => ({
+    color,
+    opacity: 0.4,
+    decal: {
+        symbol: 'line',
+        color: 'rgba(255,255,255,0.5)',
+        dashArrayX: [1, 4],
+        dashArrayY: [2, 2],
+        rotation: -Math.PI / 4
+    }
+});
+// Distinct categories of a point set in first-seen order; [''] for a single (categoryless) series.
+const categoriesOf = (points) => {
+    const seen = [];
+    for (const p of points) {
+        const c = p.category ?? '';
+        if (!seen.includes(c)) {
+            seen.push(c);
+        }
+    }
+    return seen.length > 0 ? seen : [''];
+};
+// Build the bar option for points already filtered to the visible window. One bar series per category
+// (stacked, with a legend) or a single series; per-point itemStyle carries the estimate hatch and the
+// single-series current-month highlight. Money formatting is gated on `isMoney`.
+const buildBarOption = (points, labelFn, opts) => {
+    const { stacked, isMoney, currency, theme, highlightKey } = opts;
+    const { LABEL, AXIS_LINE, TOOLTIP, ACCENT, PALETTE, LEGEND_TEXT } = theme;
+    const fmtFull = (v) => (isMoney ? formatMoney(v, currency) : String(v));
+    const fmtCompact = (v) => (isMoney ? formatMoneyCompact(v, currency) : String(v));
+    const axis = [...new Set(points.map((p) => p.key))].sort();
+    const cats = categoriesOf(points);
+    const cell = new Map();
+    for (const p of points) {
+        cell.set(`${p.category ?? ''}|${p.key}`, p);
+    }
+    return {
+        tooltip: {
+            ...TOOLTIP,
+            formatter: (params) => {
+                const arr = Array.isArray(params) ? params : [params];
+                const first = arr[0];
+                const head = first?.axisValueLabel ?? first?.name ?? '';
+                const lines = arr
+                    .map((p) => {
+                    const row = p;
+                    const v = typeof row.value === 'number' ? row.value : 0;
+                    const name = stacked ? `${row.marker ?? ''}${row.seriesName} ` : '';
+                    return `${name}<b>${fmtFull(v)}</b>`;
+                })
+                    .join('<br/>');
+                return `${head}<br/>${lines}`;
+            }
+        },
+        legend: stacked
+            ? { data: cats, textStyle: { color: LEGEND_TEXT }, itemWidth: 10, itemHeight: 10, top: 0 }
+            : undefined,
+        grid: grid(stacked ? 28 : 16),
+        xAxis: { type: 'category', data: axis.map(labelFn), axisLabel: LABEL, ...AXIS_LINE },
+        yAxis: { type: 'value', axisLabel: { ...LABEL, formatter: (v) => fmtCompact(v) }, ...AXIS_LINE },
+        series: cats.map((cat, i) => {
+            const color = stacked ? (PALETTE[i % PALETTE.length] ?? ACCENT) : ACCENT;
+            return {
+                name: cat || undefined,
+                type: 'bar',
+                stack: stacked ? 'total' : undefined,
+                emphasis: { disabled: true },
+                data: axis.map((k) => {
+                    const p = cell.get(`${cat}|${k}`);
+                    const itemStyle = p?.estimated
+                        ? estimatedBar(color)
+                        : { color: !stacked && highlightKey && k === highlightKey ? 'var(--border)' : color };
+                    return { value: p?.value ?? 0, itemStyle };
+                })
+            };
+        })
+    };
+};
+// The shared timeseries chart: a Monthly|Daily toggle over bar series, single or stacked. Pure + prop-driven —
+// the host normalizes a dataset into `monthly` (always) and an optional per-day `daily` series, each point
+// optionally carrying a `category` (→ stacked bars + legend). Monthly mode filters by a multi-year picker
+// (default: current year); daily mode shows one calendar month with a ‹ › stepper and renders gap-filled
+// (`estimated`) bars muted + hatched. A daily-source chart opens in Monthly mode. The MTD projection +
+// current-month highlight apply only to a single (categoryless) series. Both per-service and the Overview feed it.
+export const TimeseriesChart = ({ monthly, daily, isMoney = false, currency, title, height = 200, highlightCurrentMonth = false, estimateCurrentMonth }) => {
+    const t = useLabels();
+    const theme = useEchartsTheme();
+    const nowMonth = nowMonthKey();
+    const stacked = monthly.some((p) => p.category != null) || (daily ?? []).some((p) => p.category != null);
+    const hasDaily = (daily?.length ?? 0) > 0;
+    const [mode, setMode] = useState('monthly');
+    const effectiveMode = hasDaily ? mode : 'monthly';
+    const years = useMemo(() => [...new Set(monthly.map((p) => p.key.slice(0, 4)))].sort(), [monthly]);
+    const [selectedYears, setSelectedYears] = useState(() => new Set([nowMonth.slice(0, 4)]));
+    const showYearPicker = effectiveMode === 'monthly' && years.length > 1;
+    // Months present in the daily series, sorted — the steppable range. Default to the most recent.
+    const dailyMonths = useMemo(() => [...new Set((daily ?? []).map((p) => monthOf(p.key)))].sort(), [daily]);
+    const [dailyMonth, setDailyMonth] = useState('');
+    const activeDailyMonth = dailyMonth && dailyMonths.includes(dailyMonth) ? dailyMonth : (dailyMonths.at(-1) ?? '');
+    const monthIndex = dailyMonths.indexOf(activeDailyMonth);
+    const monthlyChart = useMemo(() => {
+        const shown = years.length > 1 ? monthly.filter((p) => selectedYears.has(p.key.slice(0, 4))) : monthly;
+        const points = shown.map((p) => ({ ...p }));
+        // Project the open month from its MTD figure (single series only) when nothing has settled it yet: fill the
+        // empty current-month bucket (or append a missing one) with the running total, flagged so it draws as an estimate.
+        if (!stacked && estimateCurrentMonth != null && (years.length <= 1 || selectedYears.has(nowMonth.slice(0, 4)))) {
+            const cur = points.find((p) => p.key === nowMonth);
+            if (cur && cur.value === 0) {
+                cur.value = estimateCurrentMonth;
+                cur.estimated = true;
+            }
+            else if (!cur) {
+                points.push({ key: nowMonth, value: estimateCurrentMonth, estimated: true });
+            }
+        }
+        return buildBarOption(points, monthLabel, {
+            stacked,
+            isMoney,
+            currency,
+            theme,
+            highlightKey: highlightCurrentMonth ? nowMonth : undefined
+        });
+    }, [
+        monthly,
+        years,
+        selectedYears,
+        estimateCurrentMonth,
+        stacked,
+        isMoney,
+        currency,
+        theme,
+        nowMonth,
+        highlightCurrentMonth
+    ]);
+    const dailyChart = useMemo(() => {
+        const days = (daily ?? []).filter((p) => monthOf(p.key) === activeDailyMonth);
+        return buildBarOption(days, dayLabel, { stacked, isMoney, currency, theme });
+    }, [daily, activeDailyMonth, stacked, isMoney, currency, theme]);
+    return (_jsxs(Card, { className: "gap-2 py-3", children: [_jsxs(CardHeader, { className: "flex-row items-center justify-between px-4", children: [_jsx(CardTitle, { className: "text-muted-foreground text-[11px] font-medium", children: title }), _jsxs("div", { className: "flex items-center gap-2", children: [effectiveMode === 'daily' && dailyMonths.length > 0 ? (_jsxs("div", { className: "flex items-center gap-1 text-[11px]", children: [_jsx("button", { type: "button", disabled: monthIndex <= 0, onClick: () => setDailyMonth(dailyMonths[monthIndex - 1] ?? activeDailyMonth), className: "text-muted-foreground hover:text-foreground disabled:opacity-30 disabled:hover:text-muted-foreground", "aria-label": "Previous month", children: _jsx(ChevronLeft, { className: "size-4" }) }), _jsx("span", { className: "text-foreground min-w-14 text-center tabular-nums", children: monthLabel(activeDailyMonth) }), _jsx("button", { type: "button", disabled: monthIndex < 0 || monthIndex >= dailyMonths.length - 1, onClick: () => setDailyMonth(dailyMonths[monthIndex + 1] ?? activeDailyMonth), className: "text-muted-foreground hover:text-foreground disabled:opacity-30 disabled:hover:text-muted-foreground", "aria-label": "Next month", children: _jsx(ChevronRight, { className: "size-4" }) })] })) : null, showYearPicker ? (_jsx(YearPicker, { years: years, selected: selectedYears, onChange: setSelectedYears, t: t })) : null, hasDaily ? (_jsx("div", { className: "bg-secondary/50 flex rounded-md p-0.5 text-[11px]", children: ['monthly', 'daily'].map((m) => (_jsx("button", { type: "button", onClick: () => setMode(m), className: `rounded px-2 py-0.5 transition-colors ${effectiveMode === m
+                                        ? 'bg-background text-foreground shadow-sm'
+                                        : 'text-muted-foreground hover:text-foreground'}`, children: m === 'monthly' ? t.chartMonthly : t.chartDaily }, m))) })) : null] })] }), _jsx(CardContent, { className: "px-4", children: _jsx(EChart, { option: effectiveMode === 'daily' ? dailyChart : monthlyChart, height: height }) })] }));
+};
+// Multi-select year filter. "All years" clears the filter (every year shows); ticking individual years
+// narrows. A year set that excludes everything falls back to showing all (never an empty chart).
+const YearPicker = ({ years, selected, onChange, t }) => {
+    const all = years.every((y) => selected.has(y));
+    const label = all ? t.chartAllYears : [...selected].sort().join(', ') || t.chartAllYears;
+    const toggle = (year) => {
+        const next = new Set(selected);
+        if (next.has(year)) {
+            next.delete(year);
+        }
+        else {
+            next.add(year);
+        }
+        if (next.size === 0) {
+            for (const y of years) {
+                next.add(y);
+            }
+        }
+        onChange(next);
+    };
+    return (_jsxs(DropdownMenu, { children: [_jsxs(DropdownMenuTrigger, { "aria-label": t.chartYears, className: "bg-secondary/50 hover:bg-secondary text-muted-foreground hover:text-foreground flex items-center gap-1 rounded-md px-2 py-0.5 text-[11px] transition-colors", children: [label, _jsx(ChevronDown, { className: "size-3" })] }), _jsxs(DropdownMenuContent, { children: [_jsx(DropdownMenuCheckboxItem, { checked: all, onCheckedChange: () => onChange(new Set(years)), children: t.chartAllYears }), years.map((y) => (_jsx(DropdownMenuCheckboxItem, { checked: selected.has(y), onCheckedChange: () => toggle(y), children: y }, y)))] })] }));
+};

package/dist/features/dashboard/view-models.d.ts

@@ -0,0 +1,72 @@
+import { type BadgeTone, type CapabilityResult, type Column, type RecordDataset, type StatField, type StatTone, type TableDataset } from '@butinapp/sdk/data';
+import type { DailyPoint } from '@butinapp/shapes';
+export declare const resolveBadgeTone: (value: unknown, badges?: Record<string, BadgeTone>) => BadgeTone;
+export declare const CATEGORICAL_HUES: readonly ['indigo', 'violet', 'purple', 'fuchsia', 'pink', 'cyan', 'teal', 'rose'];
+export type CategoricalHue = (typeof CATEGORICAL_HUES)[number];
+export declare const categoricalTone: (value: unknown) => CategoricalHue;
+export interface LabelledValue {
+    label: string;
+    value: string;
+}
+export interface TableCell {
+    text: string;
+    href?: string;
+}
+export interface TableModel {
+    columns: Array<{
+        key: string;
+        label: string;
+    }>;
+    rows: TableCell[][];
+}
+export declare const recordRows: (ds: RecordDataset, fields?: string[], locale?: string) => LabelledValue[];
+export declare const tableModel: (ds: TableDataset, columns?: string[], locale?: string) => TableModel;
+export declare const defaultTableSort: (columns: Column[]) => {
+    key: string;
+    dir: 'desc';
+} | undefined;
+export declare const datasetRowId: (row: Record<string, unknown>, key: string | string[] | undefined) => string | undefined;
+export declare const findCumulativeColumn: (result: CapabilityResult) => {
+    datasetId: string;
+    columnKey: string;
+} | undefined;
+export interface StatCardModel {
+    key: string;
+    label: string;
+    value: string;
+    unit?: string;
+    denominator?: string;
+    progress?: number;
+    percentLabel?: string;
+    caption?: string;
+    tone?: StatTone;
+}
+export declare const statCards: (ds: RecordDataset, fields: (string | StatField)[] | undefined, locale?: string) => StatCardModel[];
+export interface SeriesData {
+    labels: string[];
+    values: number[];
+}
+export interface StackedSeries {
+    labels: string[];
+    series: {
+        name: string;
+        values: number[];
+    }[];
+}
+export type ChartPoint = {
+    key: string;
+    value: number;
+    category?: string;
+    estimated?: boolean;
+};
+export declare const monthlyAggregate: (points: ChartPoint[]) => ChartPoint[];
+export interface DailyMonthGroup {
+    month: string;
+    label: string;
+    subtotal: number;
+    points: DailyPoint[];
+}
+export declare const groupDailyByMonth: (series: DailyPoint[]) => DailyMonthGroup[];
+export declare const latestMonthDaily: (series: DailyPoint[]) => DailyPoint[];
+export declare const stackedSeries: (ds: TableDataset, x: string, y: string, stackBy: string) => StackedSeries;
+export declare const seriesData: (ds: TableDataset, x: string, y: string, nowMonth?: string) => SeriesData;

package/dist/features/dashboard/view-models.js

@@ -0,0 +1,291 @@
+import {} from '@butinapp/sdk/data';
+import { monthlyBuckets } from '../../lib/monthly-buckets.js';
+import { formatByRole } from './format-role.js';
+// The default sentiment a status value carries, so a role:'status' column auto-tones with no per-plugin map.
+// Keys are lowercase; matched case-insensitively. A plugin's `badges` map overrides an entry here, and any
+// value absent from both falls back to neutral. This is presentation (which words read as good/bad), so it
+// lives in the renderer, not the contract.
+const STATUS_LEXICON = {
+    // settled / healthy
+    paid: 'success',
+    success: 'success',
+    succeeded: 'success',
+    finalized: 'success',
+    collected: 'success',
+    processed: 'success',
+    posted: 'success',
+    complete: 'success',
+    completed: 'success',
+    active: 'success',
+    current: 'success',
+    // awaiting payment / attention
+    open: 'warning',
+    pending: 'warning',
+    processing: 'warning',
+    issued: 'warning',
+    unpaid: 'warning',
+    inactive: 'warning',
+    // forecast / future (not overdue)
+    upcoming: 'info',
+    scheduled: 'info',
+    // problem
+    failed: 'danger',
+    declined: 'danger',
+    uncollectible: 'danger',
+    expired: 'danger',
+    revoked: 'danger',
+    past_due: 'danger',
+    delinquent: 'danger',
+    suspended: 'danger',
+    disabled: 'danger',
+    // no judgment (informational)
+    draft: 'neutral',
+    void: 'neutral',
+    voided: 'neutral',
+    refunded: 'neutral',
+    closed: 'neutral',
+    archived: 'neutral',
+    canceled: 'neutral',
+    cancelled: 'neutral'
+};
+// Resolve a role:'status' value to its sentiment tone: a column `badges` override wins, else the renderer's
+// built-in lexicon, else 'neutral'. Case-insensitive; a null/empty value is neutral. Pure (unit-tested off-DOM).
+export const resolveBadgeTone = (value, badges) => {
+    if (value == null || value === '') {
+        return 'neutral';
+    }
+    const want = String(value).toLowerCase();
+    if (badges) {
+        for (const [key, tone] of Object.entries(badges)) {
+            if (key.toLowerCase() === want) {
+                return tone;
+            }
+        }
+    }
+    return STATUS_LEXICON[want] ?? 'neutral';
+};
+// The distinct hues a role:'category' value cycles through — colors with NO sentiment, so different
+// categories (member roles, seat tiers) stay visually separable. Badge carries these variants on top of the
+// sentiment tones.
+export const CATEGORICAL_HUES = ['indigo', 'violet', 'purple', 'fuchsia', 'pink', 'cyan', 'teal', 'rose'];
+// Assign a category value a stable distinct hue by hashing it, so the same value is the same color within a
+// table and across services (owner is always one hue, admin another) with zero plugin input. A null/empty
+// value gets the first hue.
+export const categoricalTone = (value) => {
+    const text = value == null ? '' : String(value).toLowerCase();
+    let hash = 0;
+    for (let i = 0; i < text.length; i++) {
+        hash = (hash * 31 + text.charCodeAt(i)) | 0;
+    }
+    return CATEGORICAL_HUES[Math.abs(hash) % CATEGORICAL_HUES.length];
+};
+// Pick the columns to show: the named keys (in that order, skipping any that don't exist) or all of them.
+const pick = (cols, keys) => keys ? keys.map((k) => cols.find((c) => c.key === k)).filter((c) => c != null) : cols;
+// Record dataset -> formatted label/value rows. Feeds both the stat-tile and key/value renderers (they
+// differ only in layout). `fields` narrows/orders which fields show.
+export const recordRows = (ds, fields, locale) => pick(ds.fields, fields).map((col) => ({
+    label: col.label ?? col.key,
+    value: formatByRole(ds.value[col.key], col.role, col.currency, locale)
+}));
+// Table dataset -> header labels + per-cell formatted text. A url-role cell with a value also carries an
+// `href` so the renderer can make it a link. `columns` narrows/orders which columns show.
+export const tableModel = (ds, columns, locale) => {
+    const cols = pick(ds.columns, columns);
+    return {
+        columns: cols.map((c) => ({ key: c.key, label: c.label ?? c.key })),
+        rows: ds.rows.map((row) => cols.map((c) => {
+            const raw = row[c.key];
+            if (c.role === 'url' && typeof raw === 'string' && raw !== '') {
+                return { text: raw, href: raw };
+            }
+            return { text: formatByRole(raw, c.role, c.currency, locale) };
+        }))
+    };
+};
+// The default sort for a table that carries a date: the first timestamp-role column, descending (newest
+// first) — so an invoices/statements list opens chronologically instead of in fetch order. undefined when no
+// column is a timestamp (the table then keeps its natural row order). Only a fallback: a persisted user sort
+// always wins.
+export const defaultTableSort = (columns) => {
+    const ts = columns.find((c) => c.role === 'timestamp' && !c.hidden);
+    return ts ? { key: ts.key, dir: 'desc' } : undefined;
+};
+// A row's stable identity from a table's `key` — the SAME join the ledger uses to track a row across captures,
+// so the renderer can look up a row's derived daily series by its ledger row id. undefined when any key part is
+// missing/empty (an unkeyed row never accumulates).
+export const datasetRowId = (row, key) => {
+    const parts = key === undefined ? [] : Array.isArray(key) ? key : [key];
+    if (parts.length === 0) {
+        return undefined;
+    }
+    const out = [];
+    for (const k of parts) {
+        const v = row[k];
+        if (v === null || v === undefined || v === '') {
+            return undefined;
+        }
+        out.push(String(v));
+    }
+    return out.join('');
+};
+// The first keyed table dataset carrying a cumulative column (an MTD-per-row counter), with that column's key.
+// The host fetches its per-row daily series; the table view differences it into a trend sparkline. undefined
+// when no dataset has one — most capabilities, so the renderer skips the extra fetch + column entirely.
+export const findCumulativeColumn = (result) => {
+    for (const ds of result.datasets) {
+        if (ds.shape !== 'table' || ds.key === undefined) {
+            continue;
+        }
+        const col = ds.columns.find((c) => c.accrual === 'cumulative');
+        if (col) {
+            return { datasetId: ds.id, columnKey: col.key };
+        }
+    }
+    return undefined;
+};
+const clamp01 = (n) => Math.max(0, Math.min(1, n));
+// Resolve a record dataset + a stat view's `fields` into render-ready cards. A bare string field shows the
+// value as-is; a StatField adds a denominator/progress bar (`max`), a unit suffix, a caption, or a tone. The
+// column's role/currency drives formatting of both the value and the denominator, so they always match.
+export const statCards = (ds, fields, locale) => {
+    const specs = fields
+        ? fields.map((f) => (typeof f === 'string' ? { key: f } : f))
+        : ds.fields.map((c) => ({ key: c.key }));
+    return specs.flatMap((spec) => {
+        const col = ds.fields.find((c) => c.key === spec.key);
+        if (!col) {
+            return [];
+        }
+        const raw = ds.value[spec.key];
+        const card = {
+            key: spec.key,
+            label: col.label ?? col.key,
+            value: formatByRole(raw, col.role, col.currency, locale),
+            unit: spec.unit,
+            caption: spec.caption,
+            tone: spec.tone
+        };
+        if (spec.max != null && spec.max > 0 && typeof raw === 'number' && Number.isFinite(raw)) {
+            card.denominator = formatByRole(spec.max, col.role, col.currency, locale);
+            card.progress = clamp01(raw / spec.max);
+            card.percentLabel = `${Math.round((raw / spec.max) * 100)}%`;
+        }
+        return [card];
+    });
+};
+// Bucket long-format trend points into monthly points, summing per (month, category). Months sort ascending;
+// categories keep first-seen order so a stacked chart's series order is stable. The monthly-aggregation
+// counterpart to stackedSeries — feeds the Monthly view of a daily-sourced chart.
+export const monthlyAggregate = (points) => {
+    const months = [];
+    const cats = [];
+    const sum = new Map();
+    for (const p of points) {
+        const month = p.key.slice(0, 7);
+        const cat = p.category ?? '';
+        if (!months.includes(month)) {
+            months.push(month);
+        }
+        if (!cats.includes(cat)) {
+            cats.push(cat);
+        }
+        const k = `${cat}|${month}`;
+        sum.set(k, (sum.get(k) ?? 0) + p.value);
+    }
+    months.sort();
+    const out = [];
+    for (const month of months) {
+        for (const cat of cats) {
+            const k = `${cat}|${month}`;
+            if (sum.has(k)) {
+                out.push(cat ? { key: month, value: sum.get(k), category: cat } : { key: month, value: sum.get(k) });
+            }
+        }
+    }
+    return out;
+};
+const MONTHS_FULL = [
+    'January',
+    'February',
+    'March',
+    'April',
+    'May',
+    'June',
+    'July',
+    'August',
+    'September',
+    'October',
+    'November',
+    'December'
+];
+// 'YYYY-MM' -> 'June 2026'.
+const monthFullLabel = (month) => {
+    const [y, m] = month.split('-');
+    return `${MONTHS_FULL[Number(m) - 1] ?? m} ${y ?? ''}`.trim();
+};
+// Group a per-day series into month sections: months newest-first, days ascending within each, plus the
+// month's value subtotal. Feeds the expanded per-row daily breakdown so a long flat list reads by period.
+export const groupDailyByMonth = (series) => {
+    const byMonth = new Map();
+    for (const p of series) {
+        const month = p.date.slice(0, 7);
+        const arr = byMonth.get(month) ?? [];
+        arr.push(p);
+        byMonth.set(month, arr);
+    }
+    return [...byMonth.entries()]
+        .sort((a, b) => b[0].localeCompare(a[0]))
+        .map(([month, points]) => ({
+        month,
+        label: monthFullLabel(month),
+        subtotal: points.reduce((s, p) => s + p.value, 0),
+        points: [...points].sort((a, b) => a.date.localeCompare(b.date))
+    }));
+};
+// The newest month's daily points (ascending), empty when there's no data. The Trend sparkline draws this
+// alone so it reads as the current period's day-over-day shape rather than a jagged multi-month line that
+// dips at each monthly reset.
+export const latestMonthDaily = (series) => groupDailyByMonth(series)[0]?.points ?? [];
+// Pivot long-format rows into stacked series: distinct x values (sorted) form the axis; each distinct
+// `stackBy` category becomes a series whose value at each x is the sum of that (x, category) cell. Categories
+// keep first-seen order, so a plugin controls stack order by row order.
+export const stackedSeries = (ds, x, y, stackBy) => {
+    const labels = [];
+    const cats = [];
+    const cell = new Map();
+    for (const row of ds.rows) {
+        const xv = String(row[x] ?? '');
+        const cat = String(row[stackBy] ?? '');
+        const v = Number(row[y]) || 0;
+        if (!labels.includes(xv)) {
+            labels.push(xv);
+        }
+        if (!cats.includes(cat)) {
+            cats.push(cat);
+        }
+        const k = `${cat}${xv}`;
+        cell.set(k, (cell.get(k) ?? 0) + v);
+    }
+    labels.sort();
+    return {
+        labels,
+        series: cats.map((name) => ({ name, values: labels.map((xv) => cell.get(`${name}${xv}`) ?? 0) }))
+    };
+};
+const MONTH_KEY = /^\d{4}-\d{2}$/;
+const nowMonthKey = () => {
+    const d = new Date();
+    return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}`;
+};
+// Table dataset -> one numeric series for the chart. When every x value is a YYYY-MM period key, gaps are
+// filled to a continuous month axis (reusing monthlyBuckets, extended to nowMonth); otherwise rows pass
+// through in order. `nowMonth` is injectable to keep the month branch pure/testable.
+export const seriesData = (ds, x, y, nowMonth = nowMonthKey()) => {
+    const pairs = ds.rows.map((r) => ({ date: String(r[x] ?? ''), amount: Number(r[y]) || 0 }));
+    const isMonth = pairs.length > 0 && pairs.every((p) => MONTH_KEY.test(p.date));
+    if (isMonth) {
+        const buckets = monthlyBuckets(pairs, nowMonth);
+        return { labels: buckets.map((b) => b.month), values: buckets.map((b) => b.amount) };
+    }
+    return { labels: pairs.map((p) => p.date), values: pairs.map((p) => p.amount) };
+};

package/dist/features/documents/doc-models.d.ts

@@ -0,0 +1 @@
+export declare const formatSize: (bytes?: number) => string;

package/dist/features/documents/doc-models.js

@@ -0,0 +1,17 @@
+// Pure view-model helper for the downloadable-table file size cell — node-tested, no React.
+export const formatSize = (bytes) => {
+    if (bytes === undefined) {
+        return '—';
+    }
+    if (bytes < 1024) {
+        return `${bytes} B`;
+    }
+    const units = ['KB', 'MB', 'GB'];
+    let value = bytes / 1024;
+    let i = 0;
+    while (value >= 1024 && i < units.length - 1) {
+        value /= 1024;
+        i++;
+    }
+    return `${value.toFixed(1)} ${units[i]}`;
+};

package/dist/features/documents/open-file-button.d.ts

@@ -0,0 +1,6 @@
+export declare const OpenFileButton: ({ onClick }: {
+    onClick: () => void;
+}) => import("react").JSX.Element;
+export declare const ViewFileLink: ({ url }: {
+    url: string;
+}) => import("react").JSX.Element;

package/dist/features/documents/open-file-button.js

@@ -0,0 +1,16 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ExternalLink, FolderOpen } from 'lucide-react';
+import { Button } from '../../components/button.js';
+import { useLabels } from '../../i18n/context.js';
+// The canonical "open a downloaded file" row action — icon + label — for a downloadable table's trailing
+// action column (the local copy, once on disk).
+export const OpenFileButton = ({ onClick }) => {
+    const t = useLabels();
+    return (_jsxs(Button, { variant: "ghost", size: "xs", className: "text-muted-foreground hover:text-foreground", title: t.openDocument, onClick: onClick, children: [_jsx(FolderOpen, { className: "size-3.5" }), " ", t.openDocument] }));
+};
+// The "view the file where it lives" row action — opens the row's URL externally (no local copy needed).
+// Sits alongside Open in the trailing action column whenever the row has a URL.
+export const ViewFileLink = ({ url }) => {
+    const t = useLabels();
+    return (_jsxs("a", { href: url, target: "_blank", rel: "noreferrer", title: t.viewDocument, className: "text-muted-foreground hover:text-foreground inline-flex h-6 items-center gap-1 rounded-md px-2 text-xs", children: [_jsx(ExternalLink, { className: "size-3.5" }), " ", t.viewDocument] }));
+};

package/dist/features/shell/app-shell.d.ts

@@ -0,0 +1,13 @@
+import { type ReactNode } from 'react';
+export declare const AppShell: ({ brand, actions, sidebar, inset, children }: {
+    brand: ReactNode;
+    actions?: ReactNode;
+    sidebar: (ctx: {
+        onNavigate: () => void;
+    }) => ReactNode;
+    inset?: {
+        left?: number;
+        right?: number;
+    };
+    children: ReactNode;
+}) => import("react").JSX.Element;

package/dist/features/shell/app-shell.js

@@ -0,0 +1,22 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Menu } from 'lucide-react';
+import { useState } from 'react';
+import { useLabels } from '../../i18n/index.js';
+import { Button, Sheet, SheetContent, SheetTitle, SheetTrigger } from '../../primitives.js';
+// The app frame: a slim sticky top bar over a sidebar/content body. The bar splits into a brand cell that
+// sits in the sidebar column — same `w-56` width, its `border-r` continuing the sidebar divider so the
+// wordmark anchors the rail rather than floating — and a content header holding the right-aligned `actions`
+// slot. `sidebar` is a render prop so the same node renders inline on desktop and inside a closing Sheet on
+// mobile — `onNavigate` closes the sheet after a pick. Pure + prop-driven; no IPC, no theme state.
+// (SheetContent is a right-side slide-over by default; we override position to left for the nav drawer.)
+//
+// The header doubles as the OS title-bar drag handle when the host hides the native frame (`app-region: drag`,
+// ignored in a browser); its 48px height must match the native window-controls overlay height the host sets.
+// Interactive controls opt back out with `no-drag`, and `inset` reserves space on the side the native window
+// controls occupy (right on Windows/Linux, left for macOS traffic lights) so the brand + actions never sit
+// under them.
+export const AppShell = ({ brand, actions, sidebar, inset, children }) => {
+    const t = useLabels();
+    const [menuOpen, setMenuOpen] = useState(false);
+    return (_jsxs("div", { className: "bg-background flex h-full flex-col overflow-hidden", children: [_jsxs("header", { className: "bg-card sticky top-0 z-40 flex h-12 shrink-0 items-center border-b [-webkit-app-region:drag]", children: [inset?.left ? _jsx("div", { "aria-hidden": true, style: { width: inset.left } }) : null, _jsxs(Sheet, { open: menuOpen, onOpenChange: setMenuOpen, children: [_jsx(SheetTrigger, { asChild: true, children: _jsx(Button, { variant: "ghost", size: "icon", className: "ml-2 [-webkit-app-region:no-drag] md:hidden", "aria-label": t.menuLabel, children: _jsx(Menu, {}) }) }), _jsxs(SheetContent, { className: "right-auto left-0 w-56 max-w-[14rem] border-r border-l-0 p-0", children: [_jsx(SheetTitle, { className: "sr-only", children: t.menuLabel }), sidebar({ onNavigate: () => setMenuOpen(false) })] })] }), _jsx("div", { className: "flex h-full items-center px-4 [-webkit-app-region:no-drag] md:w-56 md:shrink-0 md:border-r", children: brand }), _jsx("div", { className: "flex flex-1 items-center px-4 sm:px-6", children: _jsx("div", { className: "ml-auto flex items-center gap-1 [-webkit-app-region:no-drag]", children: actions }) }), inset?.right ? _jsx("div", { "aria-hidden": true, style: { width: inset.right } }) : null] }), _jsxs("div", { className: "flex flex-1 overflow-hidden", children: [_jsx("div", { className: "hidden md:flex", children: sidebar({ onNavigate: () => { } }) }), _jsx("main", { className: "flex-1 overflow-auto", children: _jsx("div", { className: "w-full px-4 py-6 sm:px-6 lg:px-8", children: children }) })] })] }));
+};

package/dist/features/shell/conn-state.d.ts

@@ -0,0 +1,10 @@
+import { type ButinLabels } from '../../i18n/index.js';
+export type ConnState = 'connected' | 'unverified' | 'disconnected';
+export declare const connDotClass: Record<ConnState, string>;
+export declare const connLabel: (t: ButinLabels, state: ConnState) => string;
+export declare const ConnDot: ({ state, testing, className, title }: {
+    state: ConnState;
+    testing?: boolean;
+    className?: string;
+    title?: string;
+}) => import("react").JSX.Element;