Skip to content

money: implement #89 frontend design - #148

Merged
michielbdejong merged 21 commits into
mainfrom
claude/impl-89-money
Sep 25, 2026
Merged

michielbdejong merged 21 commits into
mainfrom
claude/impl-89-money

Conversation

@michielbdejong

@michielbdejong michielbdejong commented Sep 24, 2026 •

Copy link
Copy Markdown
Contributor

For users

Money: your bank transactions, readable and in your own hands

Money turns the statement files you download from your bank into one clear overview of what came in and what went out. You export a statement from your bank as MT940 or camt.053, the formats banks such as bunq, ING, Rabobank and ABN AMRO offer, and drop it on Money. Money checks it, shows you what it will add, and imports it once you confirm. Your data stays in your own Atomic Server: nothing is sent to your bank or to anyone else.

What you get

  • Every account in one overview. Each account and currency shows its latest closing balance from your statements, plus money in and money out for the period you pick. Different currencies are never added together.
  • Find a payment in seconds. Search on description or reference, switch between this month, last month, this year or your own dates, and show only money in or only money out.
  • Balances checked before anything is added. Money checks that each statement's opening balance, transactions and closing balance add up. If they don't, it shows you where the difference is, so a cut-off or edited file never slips in unnoticed.
  • No double entries. Before you import, Money tells you which transactions are new and which you already have. If the bank changed a transaction you already have, the file is stopped and Money shows the old and new details side by side.
  • Your own categories and notes, next to the bank's details. Give a transaction a category or a note; the bank's own dates, reference and description stay exactly as the bank wrote them. It works on a phone as well as on a wide screen, in light and dark mode.

How it works

  1. Export a statement from your bank's website or app as MT940 or camt.053.
  2. Drop it on Money (or choose Import statement). Money checks the balances and shows what's new, then you review the changes and apply them. Nothing is saved before that.
  3. Browse, filter and annotate. The first time you add a category or note, Atomic asks you once to let Money edit your Bank transactions table.

Good to know

  • Supported files: MT940 up to 512 KB and camt.053 up to 5 MB, with up to 500 transactions per file. CSV and PDF statements are not supported.
  • No live bank connection. Money works from the files you download. It never logs in to your bank and never makes payments.
  • Balances come from your statements. Money shows the closing balance of the latest statement in the period you pick. When no statement ends in that period, it shows money in and out only, never a balance it made up.
  • Statements imported before this version show up without their balances until you run Set up again and import them once more.
  • Moneybird and QuickBooks are planned for later.

Part of #89. Implements the Money frontend from integrations/money/design/ (design PR #107), in the order of design/issues.md. Everything is inside integrations/money/.

Plugin shape

A drive app at integrations/money/app/ (shape 1 in AGENTS.md), as DESIGN.md §1 describes: view({ root, store }), one ES module built by app/build.mjs, plain DOM, no stylesheet file. The sandbox importer (plugin.ts, shape 2) stays in the same package and stays the only writer of imported bank fields. The shapes are not mixed: the app never runs in QuickJS. It imports the importer's pure readers (statement.ts, parser.ts, camt053.ts, and the new identity.ts) so its in-app check follows the importer's rules exactly.

The app is a view of whichever table the host points it at (store.getData()): the importer's Bank transactions table, added through that table's Add view menu. It makes no store.proxy calls and has no connect or consent code, so it does not overlap with #54 phase 2 (#142). The branch is rebased on main at pin bc39dac4b (candidate11), which has the host changes Money was waiting for: #1768, #1774 and #1788.

issues.md items

Item Status Notes
M-1 scaffold Done controller with loading, empty, populated and error states; fake store modelled on hostStore.ts; reproducible build; README paragraph
M-2 shared shell Done app/ui/ (css.ts "PLUGIN CSS", components.ts, dom.ts, focus.ts), with no Money code in it, so it can move to a shared kit later. Token and class names as in DESIGN.md §4; buttons, chips, tabs and the panel use a pl- prefix too (pl-btn, pl-chip, pl-tabs, pl-panel)
M-3 amounts Done Intl v3 string formatting when the engine formats strings exactly (checked once at run time), otherwise a BigInt fallback. Both paths are tested with 12345678901234.56789, -0.00001, JPY and BHD. Totals use parser.ts units(), and a source check keeps Number() out
M-4 ledger Done account switcher, strip, search, period, direction and Uncategorised filters, a day-grouped table (≥560px) or list (<560px), 200-row window. Render budget measured in Chromium: first render of 500 rows (200 shown) 30–73 ms; re-render after a filter change 38–76 ms
M-5 annotations Done money-category (free text, as the design assumes) and money-note are in the class's recommends. The importer never writes them, and a reimport proposes nothing and leaves them alone (test). plugin.js rebuilt
M-6 detail Done Saving on blur, Saved and Retry, docked, drawer and sheet layouts, Esc closes and focus returns to the row. Row writes go through atomic-server#1788: while access is none the detail says editing needs permission and offers Allow editing. Saving asks in the host's bar (requestRowAccess) and shows "Waiting for you to allow editing…" with the typed text kept. denied shows the reason and Ask again. The host E2E clicks the real "Allow editing" and checks the category after a reload
M-7 stored statements Done destination.tables.statements (#1768): an Imported statements table of bank-statement-record rows holding account, currency, number, period, opening and closing balance, entry count, format and import date. There is one append-only row per statement, and a reimport proposes nothing. config.required gains tables, so an importer set up earlier pauses until Set up runs again, which adds only the missing table. The statement identity is deliberately not JSON-shaped: a flat JSON string array was read back as a resource array, and the host refused the write
M-8 host import op Done in the host atomic-server#1774 (store.importer.run)
M-9 structured errors Done errors.ts StatementError with code and data (BALANCE_MISMATCH, OVERLAP_WITHOUT_REFERENCES, REPEATED_REFERENCE, CONFLICTING_REFERENCE, JSON_NARRATIVE with a count, INVALID_FIELD with tag and MT940 line, plus FILE_TOO_LARGE, TOO_MANY_ENTRIES, MISSING_BALANCE and NOT_A_STATEMENT). Messages are unchanged. OVERLAP's data carries overlappingDate (value date of the earlier row) instead of earlierPeriod, because the earlier period is not stored (M-7). CHANGED_TRANSACTION is computed in the app, not by importRecords
M-10 import sheet Done The file is checked in the browser (size, decoding, reconciliation, comparison with the table), then Import N transactions hands it to store.importer.run. The host shows its bar and its own review, and nothing is written before Apply. A cancelled review returns to the preview, and a blocked one shows the importer's errors. On an older host, Import stays disabled and the note points to the importer's Import tab (with Open the importer where openResource exists). The preview's New / Already imported tabs now stay pinned at the top of the sheet (see item 5 below). No Worker (see decisions)
M-11 Imports tab Done Lists the stored statements with period, opening → closing, entries and import date. Selecting one filters Transactions. On a table without statements it falls back to rows grouped by statement
M-12 closing balances Done Each strip segment shows the latest stored closing balance that ends in the selected period, with its date. Where no statement ends in the period it shows net, in and out, never a computed balance
M-13 a11y / responsive Done axe finds no serious or critical issues on 20 frames (360, 720, 900 and 1200 px, light and dark). --pl-pos contrast is 7.53:1 on #fff and 7.76:1 on #000 (recorded in DESIGN.md). Keyboard: /, ↑/↓, Enter, Esc, i, and a ? popover
M-14 Moneybird Skipped (next) Shown disabled ("Not available yet") on first run and in Sources, as in the mockups. moneybird/ is not touched
M-15 counterparty Skipped (next) The ledger's bold line is the first line of the narrative

Host APIs (feature-detected)

Where the app had fallbacks, it now uses the new host APIs, each feature-detected so an older host still works. The fake store models both hosts, and unit tests cover both paths.

  • getMany: ledger rows load in batches of 100, several in flight. An entry that comes back as an error is skipped.

  • getTheme / onThemeChange: the host's colorScheme sets color-scheme on the app root, for native controls and scrollbars, and follows a switch.

  • --t-color-success: used for money in, with the earlier colour mix kept as the fallback. Contrast measured 5.34:1 on #fff and 9.31:1 on #000.

  • openResource: the import preview's note ("Apps can't run the importer yet") gets an Open the importer button.

  • getData().tables, importer.run, rowAccess / requestRowAccess (candidate11): see M-6, M-7 and M-10. Each of these also falls back on an older host.

Item 5, the preview tabs that wouldn't click in the screencast: this was a real bug. With a long list, the tabs scrolled away inside the sheet's body. In a frame taller than the window, a click on them then landed on the body. The tabs are now sticky at the top of the sheet. The screencast now clicks them, and so does the host E2E.

Decisions

  • Default period: This month when this month has rows, otherwise all periods, so the ledger never opens on an empty result. Clicking the pressed period chip clears it.
  • Status pill: "Latest entry · 22 Sep" instead of "Up to date", because the app cannot know a file-based account is up to date. It shows "Imported N · just now" when the table subscription delivers new rows.
  • Strip: the latest stored closing balance in the period, or net where no statement ends in it.
  • Account labels: IBAN-shaped identifiers are grouped in fours. The short form shows the bank code and the last six characters (bunq …4567 89). Other identifiers are left as they are.
  • Amounts: formatted in the browser's locale, so en-NL shows €850.00, not the mockups' € 850.00.
  • Account switcher: a native <select> styled like the design, not a custom listbox.
  • bank-fingerprint: bankingSchema() does not list it on the class, so the app finds it by shortname in the class's own ontology. It needs it to detect changed transactions.
  • No Worker for parsing: the frame is null-origin and CSP-bound. Files are at most 5 MB and 500 entries, and parsing yields between the checklist steps.
  • Bundle: JS is minified, and both embedded stylesheets go through esbuild.transform(css, { loader: 'css', minify: true }). The bundle measured 88,741 bytes; the build-test limit is 98,000.
  • Remembered UI choices: not built. Keeping filters, period and tab in a small resource under the app is a follow-up.

Needs outside this PR

  • atomic-server: nothing further. #1768, #1774 and #1788 are in the pin.
  • integrations/catalog.json: a catalog entry and a published apps/money/<version>/ui.js so the app installs from the Integrations page. The e2e installs it test-side. The existing money entry's version must match package.json if the importer version is bumped. plugin.js changed (statements table, tables in config.required) but stays at 0.2.0 here. The owner handles the version bump and the catalog after merge.
  • integrations/lanes.json: the money note describes the e2e contents and could mention the new Money app test. No tier change is needed: certify already runs money's typecheck and unit.
  • integrations/READINESS.md: a row for the Money app (drive app, host E2E as a table view, with import and row editing through the host).
  • Lane store (fixed here): money.spec.ts publishes a release on every run and used to find the "Bank statements" card by name. On a lane store kept from an earlier run it then failed, on plain origin/main too, with a strict-mode error: two "Unverified" releases. Both tests now pick the card by the content-addressed release id that the publish returned. This is a test-only change, and the connect/consent steps are untouched. I did not see the 10 s locator.click timeout reported on money: frontend design, mockups and implementation issue drafts (#89) #107.

How I tested

  • node integrations/tooling/run-lane.mjs money --tier typecheck and --tier unit: passed. Unit is 158 tests across 10 files: parser, camt, plugin, amounts, ledger, check/import states, controller, UI components and jsdom views.

  • node integrations/tooling/certify.mjs --layer js: money, notion and pets passed. Reproducible plugin.js.

  • oxlint and oxfmt --check integrations: clean. tsc -p integrations/tsconfig.e2e.json: clean.

  • run-lane.mjs money typecheck, unit and e2e against a locally built bc39dac4b binary: all passed on a fresh lane store, then twice more in a row on the same reused store (e2e 2 of 2 each time).

    • The importer test now counts the statement row ("Apply 3 changes").
    • The app test adds Money as a Read-only view, imports the MT940 from inside the app through the host bar and the real review (Apply 3 changes), and clicks the preview's tabs. It checks the strip's closing balance and the Imports tab, saves a category after clicking the real "Allow editing" in the host bar (the first test of #1788), reloads to confirm the save, and runs the in-app check (nothing new; a changed transaction blocks).
  • Screenshots from node integrations/money/app/harness/screenshots.mjs --axe, rendered with the fake store in Chromium using the host's light and dark --t-* values from mockups.html. Frames:

    • first run (720 light, 360 dark)
    • ledger with the docked detail (1200 light and dark)
    • drawer (720)
    • list (360 light and dark)
    • detail sheet, plain and with the save error (360)
    • no results (720 dark)
    • sources (720)
    • imports (720, 360 dark)
    • checking (720)
    • preview (900 light and dark)
    • nothing new (720)
    • balance error (720)
    • conflict (720 light, 360 dark)

    Compared by eye with mockups.html, they match in structure and tokens. The remaining differences are intentional: the strip shows net where no statement ends in the period, the status copy differs, and the Imports tab has no import-name column. Output goes to app/dist/screenshots/, which is gitignored.

🤖 Generated with Claude Code

Michiel de Jong and others added 20 commits September 25, 2026 11:41
…ild) (M-1)

Adds integrations/money/app/: a DOM-free controller with loading, empty,
populated and error states over the Bank transactions table the host
points the app at, a per-plugin copy of the host store types, a fake
store shaped after hostStore.ts (rows outside the app are not writable),
and a reproducible one-module build.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The --pl-* token map with light fallbacks over the host's --t-* theme,
derived --pl-pos and Money tints, and DOM builders for .pl-header,
.pl-pill (the status live region), .pl-conn, .pl-empty, .pl-banner,
buttons, chips, tabs and the detail panel (region when docked, modal
dialog otherwise), plus focus keeping across re-renders and a Tab trap.
Kept in its own folder so it can move to a shared kit later; nothing in
it knows about money.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
formatAmount formats the amount string through Intl.NumberFormat v3 when
the engine formats strings exactly (detected once), and otherwise through
a BigInt integer part with the fraction spliced in; both paths are tested
with 12345678901234.56789, -0.00001, JPY and BHD. Sums reuse parser.ts's
units(); a source check keeps Number()/parseFloat out of amounts.ts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… (M-4)

Account switcher (account + currency), search over description and
reference, period chips (this month, last month, this year, custom),
direction and Uncategorised filters, a day-grouped ledger (captioned
table with rowgroup day headers at >=560px, a list of buttons below),
200 rows per window with Show earlier transactions, a per account +
currency strip that never sums across currencies, and the no-results
state. The table subscription shows rows from a new import without a
reload. Adds a Playwright screenshot harness over the fake store.

Render budget, measured in Chromium through the harness (500 rows, 200
rendered): first render 32-73 ms, filter re-render 43-76 ms.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
money-category (free text) and money-note in the Bank transaction class's
recommends, never written by the importer: a reimport of the same
statement after annotating a row proposes nothing and leaves both values
alone. plugin.js rebuilt with the README's esbuild command.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Read-only 'From your bank' fields and the verbatim narrative; category
(a text field suggesting categories already used) and note saved on
change through resource.set/remove + save(), with Saving/Saved in the
footer and an inline alert with Retry that keeps the typed text. A
docked region at >=900px, a modal drawer at 560-899px and a full-screen
sheet below; Escape closes and returns focus to the row, arrow keys move
between rows, Tab stays inside modals.

At the pinned host the save is refused while the app is a view of the
importer's table (hostStore.ts only lets an app write beneath itself);
the detail says so instead of failing silently.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Parser, camt.053 reader and importer throw StatementError with a stable
code and the data a UI needs (BALANCE_MISMATCH with opening, entries sum,
expected and actual closing; OVERLAP_WITHOUT_REFERENCES; REPEATED_ and
CONFLICTING_REFERENCE; JSON_NARRATIVE with a count; INVALID_FIELD with
tag and MT940 line; FILE_TOO_LARGE; TOO_MANY_ENTRIES; MISSING_BALANCE;
NOT_A_STATEMENT). Messages are unchanged, so the host shows the same
text. Identities and fingerprints move to identity.ts so the Money app's
preview uses the importer's own function. plugin.js rebuilt.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…rtial)

Choose or drop a statement file: it is size-checked before reading,
decoded as UTF-8 or Windows-1252 like the host does, read with the same
readers, and compared with the table through the importer's own
identity function. The sheet ticks Read file, Check balances and Compare,
then shows one reconciliation card per statement and New / Already
imported / Blocked tabs, or a designed banner per error code (balance
figures for BALANCE_MISMATCH, In your table / In this file for a changed
transaction), with the reader's message under Technical details and
focus on the banner title.

Applying needs a host op (issues.md M-8) the pinned host lacks, so the
preview says to import the same file from the importer's Import tab and
the Import button stays disabled. The controller takes an ImportPort for
when such an op exists; tests exercise that path with a fake. The finder
for bank-fingerprint looks it up by shortname, since bankingSchema()
does not list it on the row class.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
One row per statement the table's rows came from (format, account,
currency, bank-statement number): period, format, in/out and entries,
newest first; a list at narrow widths. Selecting one shows its
transactions through a removable Statement filter chip. Opening and
closing balances and import dates need stored statements (M-7), which
this PR does not add; the tab says so.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
axe (via the screenshot harness, --axe) reports no serious or critical
findings on any frame at 360, 720, 900 and 1200 px, light and dark,
after two fixes: the narrow ledger is now a heading plus a list per day
(no presentational items inside a list), and the balance difference
uses a darker mix of the alert colour on its tinted banner. Measured
--pl-pos contrast: 7.53:1 on #fff, 7.76:1 on #000. Adds the '?'
shortcuts popover; shortcuts stay off while typing in a field.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
JS through esbuild's minify, and both embedded stylesheets through
esbuild.transform(css, { loader: 'css', minify: true }) at build time,
per the owner's bundle-size rule. Measured 82,579 bytes; the build test
limit is 91,000 (measured plus about 10%).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
README: what the app does, what the pinned host does not let it do yet
(apply an import, write annotations to the importer's table, install from
the catalog), and the harness commands. The importer's e2e passed against
11264e83e with the rebuilt plugin.js on a fresh lane store; a store kept
from earlier runs makes the spec fail on plain origin/main too. DESIGN.md
records the measured --pl-pos contrast.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…table

A new test block in e2e/money.spec.ts (the importer's own test is
unchanged): set up the importer and import the synthetic MT940, install
the built app test-side as an App that renders bank transactions, add it
through the table's Add view menu, and check the ledger, the detail with
the host's refusal of the category save (the table is not under the
app), and the in-app check (nothing new; a changed transaction blocks).
Passed against 11264e83e on a fresh lane store.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The spec found the Bank statements card by name, so a lane store kept
from an earlier run (or an earlier test in the same run) listed two and
the strict locator failed. Both tests now match the content-addressed
release id that the publish returned. Test-only change; passes on a fresh
store and twice in a row on a reused one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
getMany loads ledger rows 100 at a time (errors in place are skipped);
getTheme/onThemeChange set color-scheme from the host's colorScheme;
--pl-pos takes --t-color-success; the import preview's note offers
'Open the importer' through openResource. All feature-detected: the fake
store models both the current and an older host, and tests cover both.
The importer-run, table-write and multi-class Set up items are not in
this pin, so their fallbacks stay. Measured --pl-pos contrast with the
host's success colour: 5.34:1 light, 9.31:1 dark. Bundle 83,637 bytes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ble (M-7)

The destination gains tables.statements (atomic-server#1768): an
Imported statements table of bank-statement-record rows with account,
currency, number, period, reconciled opening and closing balance, entry
count, format and the date first imported. plugin.ts writes one
append-only row per parsed statement beside its transactions, identified
by format, account, currency, number and period, so a reimport proposes
nothing. config.required gains tables: an importer set up before this
pauses until Set up runs again, which adds only the missing table.
The 'previously imported transactions skipped' count stays per
transaction. plugin.js rebuilt.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…, M-11, M-12)

Uses the candidate11 host (bc39dac4b), each call feature-detected:
- getData().tables.statements: the strip shows the latest closing balance
  that ends in the period with its date (in/out and net otherwise, never a
  computed balance); the Imports tab lists stored statements with
  opening -> closing, entries and import date, and falls back to rows.
- rowAccess/requestRowAccess (#1788): the detail says editing needs
  permission, saving asks in the host's bar while the typed text stays,
  a refusal is shown with Ask again; with a grant, category and note save.
- importer.run (#1774): Import N transactions hands the checked file to
  the importer and its host review; cancelled returns to the preview,
  blocked shows the importer's errors. Older hosts keep the pointer to
  the importer's Import tab.
The fake store models the current and an older host; the bundle limit
is 98,000 (measured 88,741).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ids not JSON-shaped

The app test now adds Money as a read-only view, imports from inside the
app through importer.run and the host's review (Apply 3 changes: two
transactions and their statement), checks the strip's closing balance
and the Imports tab, clicks the preview's New/Already imported tabs, and
saves a category after clicking the host bar's 'Allow editing' (the
first test of atomic-server#1788). The importer test counts the
statement row.

Statement identities are no longer a flat JSON array of strings, which
legacy storage read as a resource array, so the host refused the write
('did not preserve its source datatype'). After an applied import the app
reads the tables again instead of relying on the subscription alone.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The tabs scrolled away with a long list inside the sheet, and in a frame
taller than the window a click on them landed on the sheet's body
(the click in the screencast). They now stay at the top of the sheet's
scroll area.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@michielbdejong
michielbdejong marked this pull request as ready for review September 25, 2026 10:33
@michielbdejong
michielbdejong merged commit 4176ca8 into main Sep 25, 2026
18 checks passed
michielbdejong added a commit that referenced this pull request Sep 29, 2026
money 0.3.0: publish the Money app (disabled), lanes note, READINESS (#148)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant