kvitt/PLAN-M7c.md

PLAN-M7c: Feature expense

1. Goal

Build :feature:expense: the full-screen expense editor (S-7) and the expense detail with its timeline (S-8), against the :core:model interfaces and :core:fakes. Every state of both screens is screenshot-tested in Swedish and English, light and dark.

2. Read first

1. docs/ux/design-spec.md: tokens, component inventory, and the sections for S-7, S-8.
2. docs/ux/strings.csv (keys for these screens) and docs/ux/screens/S-7-*, docs/ux/screens/S-8-*.
3. SPEC §13.2 Navigation model and §13.3 Screens (rows S-7, S-8 and the states paragraph); §9.11 Category suggestion (D-049). M12c must have landed (§11.2). After saving, the snackbar "Utgiften sparades" has no undo (S-7, D-052).
4. SPEC §14.2.4 UI contract: ExpenseRepository, ExpenseDraft, ExpenseEditorOptions, ExpenseDetailState, TimelineLine, FieldChange, Share, SaveResult, FieldError, SplitMode, Account, Category, User.
5. SPEC §4 FR-8 Expenses (AC-8.1 to AC-8.11); FR-12 AC-12.4, AC-12.5; §9.1 Splits; §9.6 (limits, amount input parsing); §9.10 (exact-mode edit); §14.5.3 error tokens.
6. SPEC §6.2 (module table), §9.8 Formatting, §9.9 Online-only actions, §11.2 (row M7c), §11.3 (note M7x), §14.7.
7. Files: android/core/model/**, android/core/design/** (read only), android/core/fakes/**, android/build-logic/**, CLAUDE.md (BUILD AND VERIFY: Screenshots; ARCHITECTURE RULES; ANTI-PATTERNS).

3. Already established

• Features depend only on :core:model, :core:design and :core:fakes; :core:fakes only in test, screenshot-test and debug-preview configurations, never in a release build. Features never depend on :data or :domain (§6.2, §11.3, CLAUDE.md Layering).
• Screens consume the *State classes through the repository interfaces of §14.2.4; no field may be added except through a contract change (§14.2.4, §14.8).
• Fake scenarios go only in android/core/fakes/src/main/kotlin/se/hagstedt/kvitt/fakes/<feature>/ (§11.3, §14.7).
• Strings live in the module's src/main/res/values/strings.xml and values-sv/strings.xml with keys from docs/ux/strings.csv; no string outside that file unless the report proposes it as a decision entry for the orchestrator (§13.4, §14.7, AC-19.1).
• No hard-coded colours, sizes or strings; tokens and shared components come from :core:design, which features may not edit (CLAUDE.md, §14.7). Money and dates go through MoneyFormatter and DateFormatter (§9.8).
• Online-only actions are disabled with "Needs connection" when offline (§9.9); a REST failure shows "Could not reach the server".
• Feature convention (§6.2, D-017): one composable entry point per screen, taking a hiltViewModel()-provided ViewModel and its navigation as plain lambdas; the feature never references another feature or the NavHost; ViewModels get repositories through the :core:model interfaces. Navigation graph, deep links and Hilt bindings are in :app (M8).
• M2b created this module's shell with one empty entry composable (D-004); this plan owns it and replaces it with the real entry points.
• Keys are prefixed by the feature name; lint MissingTranslation is an error in this module (§6.2, §13.4, D-017).
• The states each screen must have are the ones docs/ux/design-spec.md lists for it (§13.3).
• Shared UI (D-019): the expense editor fields (S-7) come from :core:design, built by M6; never copy or re-implement it here.
• Layout and visuals follow docs/ux/design-spec.md; TalkBack labels as it specifies; 48 dp targets, 200 % font scale reflow (§13.1).
• No placeholder text in previews or screenshots; goldens are committed; open every changed PNG before committing (CLAUDE.md).
• The add flow needs at most: open app, tap add, type amount, type description, tap save; account, category, payer and split are defaulted (§13.1, AC-8.6).
• Editor is a full screen, not a bottom sheet (§13.2). Amount input accepts digits, one decimal separator (, or .), at most two decimals, no sign, converted to öre by string parsing, never floating point (§9.6).
• Defaults: account = last used on this phone if active else oldest active; category for a new expense = the suggestion of §9.11 (D-049): the editor keeps a "picked by hand" flag (CS-2) and, while it is false, calls ExpenseRepository.suggestCategory(accountId, description) on every description and account change (CS-3), showing the result with no marker (CS-7); before any description it is ExpenseEditorOptions.defaultCategoryFor (last used in that account if active else other); editing never changes the category (CS-1); split mode default; payer = current user; date = today in the phone's zone (AC-8.3, AC-8.4, AC-8.6). Defaults come from ExpenseEditorOptions.
• Split modes default ("Account default 60/40"), ratio, exact (type one share, the other is amount minus it, read-only; a share larger than the amount blocks saving inline), full (one bearer); changing account in default re-copies the ratio; live preview from ExpenseRepository.preview (AC-8.5, AC-8.7, AC-8.8, §13.3 S-7).
• Validation errors come back as SaveResult.Invalid with §14.5.3 tokens, required, or validation_failed for a §9.6 limit without a domain token (lengths, dates) (§9.6, §14.2.4); deleting asks for confirmation (AC-8.9).
• Category quick row (D-059, SPEC §14.2.4 "Changes in v0.9"): ExpenseEditorOptions.frequentCategoryIds[accountId], read once on open and on an account change, filled up to five from the remaining active categories in sort_order; the selected category (suggested, defaulted or picked in "Alla") takes the fifth place when it is not among them. M12d must have landed (§11.2). When the suggestion returns null (other archived and no active last-used category), the editor shows no category until the user picks one, and saving is blocked as for a missing category (AC-8.6).
• Design-spec open points (docs/ux/design-spec.md §6) carried here: tabular figures for amounts as M6 delivers them (M6 checks them on the S26); Material 3 Expressive components only as M6 provides them, with M6's stable fallbacks; the recurring editor S-19 (M7f) has no category suggestion, so nothing in this feature is shared with it beyond the :core:design editor fields.
• Detail shows amount, description, category, account, date, payer, shares and mode, notes, "Recurring: " when generated, and the timeline: newest last, one line per entry, field names in the UI language, ids resolved, pending line "Your change is waiting to sync"; a deleted state when opened from a deletion notification (AC-8.11, AC-12.4, AC-12.5, §13.3 S-8).

  4. Owned paths

  From SPEC §14.7, verbatim: android/feature/expense/** (owner M7c), and from the android/core/fakes/** row: "M7x add files only under fakes/<feature>/", here android/core/fakes/src/main/kotlin/se/hagstedt/kvitt/fakes/expense/ (§11.3). Catalog entries and module includes may be added (§14.7, android/gradle/** row).

  Edit nothing outside these paths; a needed change elsewhere is a contract request to the orchestrator.

  5. Deliverables

  • android/feature/expense/build.gradle.kts: dependencies :core:model, :core:design; :core:fakes for tests and debug only.
  • android/feature/expense/src/main/kotlin/se/hagstedt/kvitt/feature/expense/**: the screens of this module and their state holders.
  • android/feature/expense/src/main/res/values/strings.xml, values-sv/strings.xml: keys from docs/ux/strings.csv.
  • android/core/fakes/src/main/kotlin/se/hagstedt/kvitt/fakes/expense/**: a scenario per state below.
  • Screenshot tests and committed goldens for every screen × state × light/dark × sv/en.
  • Unit tests for the state holders (input handling, enablement rules, error mapping).

  Screens and states. Required states for every screen below (SPEC §13.3): loaded, empty, offline (with pending changes), loading (first sync only), error (a failed online action), and for lists long content (long Swedish names, 7-digit amounts), each where it applies. A state that docs/ux/design-spec.md marks not applicable for a screen is skipped and named in the report. Each state is screenshot-tested in light and dark, Swedish and English. Screen-specific states from §13.3 "Must show" are added per screen:

  • S-7: new (defaults applied); edit mode with Delete; each split mode default, ratio, exact, full (on payer and on the other user); exact share larger than the amount (inline error, save blocked); missing description and missing amount errors; notes collapsed and expanded; account picker open; category grid open; date picker; delete confirmation; offline (saving still allowed); long content (long description, 7-digit amount, long account and category names).
  • S-8: loaded in each split mode; recurring; with notes; timeline with create, change (amount, account, split) and pending lines; deleted; pending; offline; long content (long timeline).

  6. Steps

  1. Worktree. From the main checkout /Users/jhag/projects/kvitt: git worktree add .claude/worktrees/agent-m7c -b agent-m7c main, then in .claude/worktrees/agent-m7c: git reset --hard main. Copy android/local.properties from the main checkout (add sdk.dir=/opt/homebrew/share/android-commandlinetools if missing; never overwrite or commit). Run tools/install-git-hooks.sh.
  2. Read §2 in order. Confirm M6 has landed (android/core/design/ has components on main); if not, stop and report. If a component the design spec assigns to :core:design is missing, file a contract request; do not build it inside the feature.
  3. Run python3 tools/dependency-report/latest.py; record the lines. No new library is expected; any one added is at its latest stable version from official docs; record it.
  4. Write the fake scenarios under the feature's fakes/<feature>/ directory for every state listed in §5.
  5. Write the state holders and screens, one screen at a time, with strings from docs/ux/strings.csv in both languages.
  6. Write the screenshot tests; record goldens; open every PNG and compare with docs/ux/screens/.
  7. Run the gate (§7). Commit on agent-m7c, git rebase main, rerun the gate. Never merge, push or remove the worktree.

  7. Gate

  From SPEC §11.2, verbatim: "as M7a", that is "Android gate with screenshot tests of every state, sv and en, light and dark". Command, from android/: PATH=/opt/homebrew/opt/openjdk@25/bin:$PATH ../tools/gradle-serial.sh check. Green means: BUILD SUCCESSFUL in this session; screenshot verification passes for :feature:expense; the report lists, per screen, every state × light/dark × sv/en golden; unit tests 0 failures in fresh XML.

  8. HUMAN steps

  From SPEC §11.2, verbatim: "none".

  9. Out of scope

  • Other screens: S-1, S-2, S-3, S-18 (M7a); S-4, S-5, S-6, S-16, S-17 (M7b); S-9, S-10 (M7d); S-11, S-12 (M7e); S-13, S-14, S-15, S-19, S-20, S-21, S-22 (M7f).
  • Navigation graph, deep links, Hilt bindings, notifications (M8); real repositories (M5).
  • Editing :core:design (requests go to the orchestrator) or :core:model; any dependency on :data or :domain.
  • Fake scenarios outside this plan's fakes/<feature>/ directories.

  10. Report

  • Branch agent-m7c, head commit hash after rebasing on main.
  • Gate output: BUILD line, actionable tasks line, screenshot task result, test counts from fresh XML.
  • Screens × states table with golden file names; states skipped as not applicable.
  • Versions added (if any) with sources; dependency-report lines.
  • Strings used that are missing from strings.csv (should be none) and design-spec mismatches.
  • Proposed decision entries (never written to SPEC.md or docs/decisions.md by this agent) or TODO(spec) occurrences.
  • Contract requests (:core:design, :core:model), open questions, spec gaps (with section numbers).

  11. Numbering

  Decision ids, spec version and schema version are assigned by the orchestrator in the start prompt; use TODO(spec) if none was given.