diff --git a/CLAUDE.md b/CLAUDE.md index 8ed2168..24e5947 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -68,8 +68,8 @@ Theme state lives in `ui/src/theme.jsx` — a React context (`ThemeContext`) wit `ThemeProvider` that wraps the app in `main.jsx`. - **Storage key:** `df_dark` in `localStorage`; falls back to `window.matchMedia('(prefers-color-scheme: dark)')` on first visit -- **Toggle:** button in the sidebar header in `App.jsx`; effect writes `localStorage` and toggles the `.dark` class on `` -- **CSS:** `ui/src/index.css` defines CSS custom properties under `:root` (light) and `.dark`. All Tailwind color overrides are written as `.dark .bg-white { ... }` etc. +- **Toggle:** button at the foot of the sidebar (`Sidebar.jsx`), and in `BottomNav.jsx` on mobile; the effect writes `localStorage` and toggles the `.dark` class on `` +- **CSS:** `ui/src/index.css` declares semantic tokens under `@theme` (`bg-surface`, `text-ink`, `text-muted`, `border-line`, `text-danger`, …) that resolve to CSS custom properties redefined by `.dark`. **Write components against the tokens, never against literal shades like `bg-white` or `text-gray-400`** — the old per-utility `.dark .bg-white { … }` overrides are gone and must not come back - **Palette:** dark mode uses Perspective's "Pro Dark" colours (`--bg-primary: #242526`, panels `#2a2c2f`, gridlines `#3b3f46`, text `#c5c9d0`) - **Perspective viewer:** `Pivot.jsx` calls `viewer.setAttribute('theme', dark ? 'Pro Dark' : 'Pro Light')` on initial load and in a `useEffect([dark])` so the viewer stays in sync when the toggle fires - **Consuming the theme:** `import useTheme from '../theme.jsx'` then `const { dark, setDark } = useTheme()` diff --git a/docs/spec.md b/docs/spec.md index f7120ee..79f3e51 100644 --- a/docs/spec.md +++ b/docs/spec.md @@ -59,10 +59,14 @@ api/ ui/ src/ api.js — fetch wrapper, credential management - App.jsx — root: login gate, sidebar, source selector, routing + App.jsx — root: login gate, routing, stale/reprocess banners + index.css — semantic colour tokens for light and dark pages/ Login.jsx — username/password form - Sources.jsx — source CRUD, field config, view generation + SourceList.jsx — source list and the create dialog + SourceDetail.jsx — one source: connection, fields, view, maintenance + Bridge.jsx — SimpleFIN accounts, balances, and subtotals + ImportHub.jsx — all sources with sync / upload actions Import.jsx — CSV upload, SimpleFIN sync, and import log Rules.jsx — rule CRUD with live pattern preview Mappings.jsx — mapping table with TSV import/export @@ -71,7 +75,7 @@ ui/ Stacks.jsx — multi-source union views with running balance Remap.jsx — bulk remap of an output field value across mappings Log.jsx — global import log across all sources - components/ — Sidebar, StatusBar + components/ — Sidebar, BottomNav, navItems, SourceTabs, Section, SampleTable theme.jsx — light/dark context provider public/ — compiled UI (output of npm run build in ui/) docs/ — this file, tutorial, UI and Perspective references @@ -327,11 +331,43 @@ Built with React + Vite + Tailwind CSS. Compiled output goes to `public/`. The s 3. On 401 response, credentials are cleared and the login screen is shown. 4. `localStorage` persists the selected source name across sessions. +**Navigation.** The selected source is a route parameter, not global state: `/sources` +lists sources, `/sources/:name` owns one, and Import, Rules, Mappings, Records, and Pivot +are tabs beneath it (`components/SourceTabs.jsx`). The sidebar holds only top-level +destinations — Sources, Import, Bridge, Remap, Stacks, Log — defined once in +`components/navItems.jsx` and rendered by `Sidebar.jsx` on desktop and `BottomNav.jsx` +below the `md:` breakpoint. Out-of-sync and reprocess banners render above every page from +`App.jsx`. + +**Colour.** Components use semantic tokens (`bg-surface`, `text-ink`, `text-muted`, +`border-line`, `text-danger`) declared in `index.css` under `@theme`, which resolve to CSS +variables redefined by `.dark`. There are no per-utility `.dark` override rules; a new +component gets both themes for free. + +**Bundle.** `Pivot` is loaded with `React.lazy`, keeping Perspective (~4.7 MB gzipped) out +of the initial download and in a chunk fetched only when a pivot is opened. + **Pages:** -- **Sources** — View and edit source configuration. Shows all known field names and their origins (raw data, schema, rules, mappings). Checkboxes control which fields are constraint fields and which appear in the output view. Supports CSV upload to auto-detect fields. +- **Sources** (`SourceList.jsx`) — Lists every source with its constraint fields and a + badge for bank feeds; clicking opens it. "New source" opens the create dialog, which can + seed fields from a CSV sample or from a linked SimpleFIN account. -- **Import** — Upload a CSV to import records into the selected source. Transformations run automatically on new records. Shows import log with inserted/duplicate counts, expandable key detail, checkbox selection, and delete with confirmation. Sources with `config.simplefin.account_id` also get a Sync panel — a window selector (10/30/90 days or everything) and a "Sync now" button that pulls from the bank API through the same import path. +- **Source detail** (`SourceDetail.jsx`) — The Setup tab, grouped into titled panels: + Connection (link/unlink a SimpleFIN account, warns when constraint fields aren't `id`), + Fields and view (all known field names and their origins, with checkboxes for constraint + fields and view columns), Sample rows, Maintenance (reprocess), and Delete source. + +- **Bridge** (`Bridge.jsx`) — Every account behind the SimpleFIN credential with balances, + the source each maps to, and subtotals split into banking versus retirement (recognised by + keyword on the account and institution names). Queries SimpleFIN only when Refresh is + pressed. Balances render in accounting style with negatives in parentheses. + +- **Import** (`ImportHub.jsx`) — Top-level entry point for the frequent job. Lists every + source with record counts and last import date, a Sync button for bank feeds, and an + upload link for CSV sources. + +- **Source › Import tab** — Upload a CSV to import records into the selected source. Transformations run automatically on new records. Shows import log with inserted/duplicate counts, expandable key detail, checkbox selection, and delete with confirmation. Sources with `config.simplefin.account_id` also get a Sync panel — a window selector (10/30/45 days or a full backfill) and a "Sync now" button that pulls from the bank API through the same import path. - **Rules** — Create and manage regex rules. Live preview fires automatically (debounced 500ms) as pattern/field/flags are edited, showing match results against real records. Rules can be enabled/disabled by toggle. @@ -358,7 +394,8 @@ Built with React + Vite + Tailwind CSS. Compiled output goes to `public/`. The s See `docs/perspective.md` for the full technical reference on controlling Perspective programmatically. -- **Stacks** — Named unions of multiple sources. Each stack defines a field mapping (how source fields map to common output columns), an amount field, a date field, and an optional balance offset. The view-data endpoint unions the underlying source views and computes a running balance sorted by date. The Pivot page supports stacks as well as individual sources, with layouts stored in the same `pivot_layouts` table. +- **Stacks** — Named unions of multiple sources, each chip linking to its pivot at + `/stacks/:name/pivot`. Each stack defines a field mapping (how source fields map to common output columns), an amount field, a date field, and an optional balance offset. The view-data endpoint unions the underlying source views and computes a running balance sorted by date. The Pivot page supports stacks as well as individual sources, with layouts stored in the same `pivot_layouts` table. - **Log** — Global import log across all sources. Same expandable key detail and delete capability as the Import page, plus a source name column.