PRD: Make expense templates catalog mobile friendly

[Jorg3L3on]

Problem Statement

The expense templates catalog is difficult to use on mobile devices because it is currently presented as a dense desktop-style table. The table contains many columns for template identity, category, estimated amount, cutoff day, per-fortnight payment days, recurrence, subscription state, active state, and actions. On a phone, this forces horizontal scrolling and makes routine catalog work feel cramped: users cannot quickly identify a template, understand when it applies in the fortnight planning flow, or edit/delete it with confidence.

This is the first mobile-friendly catalog transformation for MiCasa. The goal is to improve the expense templates page without changing the underlying owner context, API contract, expense template schema, or desktop experience.

Solution

Provide a responsive expense templates catalog that keeps the current table experience on desktop and introduces a mobile-first card/list experience on small screens.

On desktop, users continue to get the existing sortable DataTable with column visibility and dense scanning.

On mobile, each expense template should render as a compact card that answers the key questions quickly: what is this template, what category does it belong to, how much is estimated, whether it is active, whether it is recurring or a subscription, which fortnights it applies to, what payment days apply, whether it has a cutoff day, and how to edit or delete it.

The current search/category/type filters should remain, but they should stack cleanly on mobile. The column visibility control should not be shown for the mobile card view because there are no columns to manage. The sticky header should remain aligned with the dashboard shell and should keep the add action usable on mobile, likely with shorter mobile text such as “Agregar” while desktop keeps “Agregar plantilla”.

User Stories

1. As a mobile household member, I want to browse expense templates as readable cards, so that I do not have to horizontally scroll a wide table.
2. As a mobile user, I want each expense template card to show the template name prominently, so that I can identify the recurring obligation quickly.
3. As a mobile user, I want each expense template card to show the estimated amount, so that I can understand the expected impact on my fortnight planning.
4. As a mobile user, I want each expense template card to show the category and category icon, so that I can recognize the expense type at a glance.
5. As a mobile user, I want each expense template card to show whether the template is active, so that I do not confuse inactive templates with current planning inputs.
6. As a mobile user, I want active and inactive states to be visually distinct, so that catalog scanning is faster.
7. As a mobile user, I want recurring templates to be marked clearly, so that I understand which expenses are expected to repeat.
8. As a mobile user, I want subscription templates to be marked clearly, so that I can distinguish subscriptions from other recurring expenses.
9. As a mobile user, I want the card to show whether a template applies to the first fortnight, so that I understand when it participates in planning.
10. As a mobile user, I want the card to show whether a template applies to the second fortnight, so that I understand when it participates in planning.
11. As a mobile user, I want per-fortnight due days to be grouped into one readable line, so that I do not have to compare multiple table columns.
12. As a mobile user, I want the legacy/default due day to still be displayed when per-fortnight due days are not present, so that older template data remains understandable.
13. As a mobile user, I want cutoff day information shown only when it exists, so that the card stays compact and avoids empty noise.
14. As a mobile user, I want edit and delete controls to remain available on every card, so that I can manage templates without switching to desktop.
15. As a mobile user, I want edit and delete controls to have clear accessible labels, so that assistive technology can identify the target template.
16. As a mobile user, I want the delete confirmation behavior to remain unchanged, so that destructive actions still require confirmation.
17. As a mobile user, I want delete errors for templates in use to continue surfacing in the confirmation flow, so that I understand why deletion failed.
18. As a mobile user, I want search by template name to be full width, so that typing and editing the query is comfortable.
19. As a mobile user, I want category filtering to fit within the viewport, so that I can filter the catalog without layout overflow.
20. As a mobile user, I want type filtering to fit within the viewport, so that I can quickly filter to recurring templates or subscriptions.
21. As a mobile user, I want filtered empty states to remain clear, so that I know whether no templates exist or my filters hid them.
22. As a desktop user, I want the existing table experience preserved, so that I do not lose dense scanning, sorting, or column visibility.
23. As a desktop user, I want the current column visibility menu to remain available, so that I can customize the desktop table.
24. As a user switching between mobile and desktop widths, I want the same filtered dataset to be shown in both layouts, so that responsive behavior does not change the meaning of the page.
25. As a house-context user, I want the catalog to continue respecting the active owner context, so that house templates and personal templates remain scoped correctly.
26. As a user-context user, I want the catalog to continue respecting my personal owner context, so that I only see my personal templates when appropriate.
27. As a user with no expense templates, I want the existing empty state to remain simple and clear, so that I know there is nothing to manage yet.
28. As a user with many expense templates, I want the mobile cards to remain compact, so that I can scroll through the catalog efficiently.
29. As a user with long template names, I want cards to wrap gracefully, so that text is readable and does not clip or overlap.
30. As a user with long category names, I want category labels to wrap or truncate safely, so that the card layout remains stable.
31. As a keyboard user, I want interactive controls to remain reachable and operable, so that the responsive change does not reduce accessibility.
32. As a screen reader user, I want mobile card actions to announce the template name, so that edit/delete actions are not ambiguous.
33. As a maintainer, I want this first mobile transformation to be scoped to expense templates, so that we can validate the pattern before applying it across the whole catalog.
34. As a maintainer, I want the mobile card rendering to reuse existing formatter and label utilities, so that currency and category display stay consistent.
35. As a maintainer, I want the mobile card component to reuse existing handlers for edit and delete, so that behavior does not diverge between desktop and mobile.
36. As a maintainer, I want no schema changes for this feature, so that the implementation remains a UI-only responsive improvement.
37. As a maintainer, I want no API changes for this feature, so that existing catalog data loading remains stable.
38. As a maintainer, I want the desktop DataTable code path to remain intact, so that the mobile change has a small blast radius.
39. As a maintainer, I want this implementation to align with MiCasa dashboard visual conventions, so that the page feels native to the app.
40. As a maintainer, I want this work to create a reusable direction for future catalog pages, so that income templates, budget templates, categories, wallets, and similar list pages can be improved later.

Implementation Decisions

• Keep the current desktop DataTable for medium and larger screens.
• Add a mobile-only expense template card/list presentation for small screens.
• Use the same filtered expense template collection for both desktop and mobile presentations.
• Keep the existing page data fetch, owner context behavior, delete API behavior, edit navigation behavior, and create navigation behavior unchanged.
• Keep the implementation focused on the expense templates catalog as the first slice of the broader mobile-friendly catalog effort.
• Do not introduce database schema changes.
• Do not introduce API contract changes.
• Do not change expense template creation or editing forms as part of this PRD.
• Render mobile cards with dashboard conventions: compact rounded card, subtle border, card background, small status/chip badges, tabular currency text, and icon-only row actions with accessible labels.
• Show template name as the primary card text.
• Show active/inactive as a status badge near the card header.
• Show category using the existing category label behavior, including category icon where available.
• Show total estimated amount using the existing currency formatter.
• Show recurring, subscription, first fortnight, and second fortnight state as compact badges/chips rather than independent table columns.
• Show due-day details as a single human-readable timing line. Prefer per-fortnight due days when present; fall back to legacy/default due day when appropriate.
• Show cutoff day only when present.
• Keep edit and delete actions available on each mobile card and wire them to the existing handlers.
• Preserve the existing ConfirmDeleteDialog behavior for deletion.
• Stack filter controls on mobile so search and selects fit the viewport without horizontal overflow.
• Hide the desktop column visibility control on the mobile card view.
• Keep the sticky page header aligned with the dashboard shell. Use shorter mobile copy for the add button if needed to avoid crowding.
• Avoid extracting a broad reusable responsive table abstraction in this first slice unless the local implementation becomes meaningfully duplicated or complex.
• Treat a future reusable responsive catalog/data-view component as a follow-up after this page validates the pattern.

Major modules to build or modify:

• Expense templates catalog page: add responsive mobile rendering while preserving the existing desktop DataTable path.
• Expense template mobile card/list component: may be local to the page or extracted into a small component if the page becomes hard to scan.
• DataTable usage on this page: wrap or conditionally display it for desktop while keeping its existing behavior.
• Filter toolbar layout: update control sizing and visibility so mobile and desktop both remain usable.

Deep-module opportunity:

• A small formatter/helper for deriving display chips and timing text from an expense template could be useful if it keeps card rendering simple and can be tested independently. It should expose a stable interface such as “given an expense template list item, return display metadata for chips and timing.” This is optional for the first implementation and should be introduced only if it simplifies the UI code.

Testing Decisions

• Good tests should verify external behavior from the user’s perspective: what appears on mobile and desktop, which actions are available, and whether filters affect both layouts consistently. Tests should not assert internal component boundaries or Tailwind implementation details beyond what is necessary to distinguish mobile and desktop behavior.
• Add focused component or page-level tests if the existing test setup supports rendering responsive variants reliably.
• If extracting a display metadata helper for chips/timing text, test that helper with representative template inputs: per-fortnight due days, legacy due day fallback, cutoff day present/absent, recurring/subscription flags, first/second fortnight applicability, and inactive templates.
• If browser/e2e coverage is used, verify the catalog at a mobile viewport and a desktop viewport. At mobile width, cards should be visible and the table should not force horizontal scrolling. At desktop width, the DataTable should remain available.
• Verify that edit and delete actions exist for mobile cards and retain accessible labels containing the template name.
• Verify that category and type filters still reduce the displayed result set on mobile.
• Verify that the name search still filters mobile results.
• Prior art in the codebase includes dashboard page component patterns, existing DataTable usage across catalog pages, EmptyState usage for empty lists, and existing Vitest tests for isolated finance helpers. Browser verification should follow the repo’s normal validation flow for UI changes.
• Run the standard verification commands appropriate for a UI-only change: lint, tests if relevant, and build when feasible.

Out of Scope

• Making the entire MiCasa app mobile friendly.
• Updating income templates, budget templates, categories, wallets, transactions, or other catalog/list pages.
• Redesigning the expense template create/edit forms.
• Changing owner context behavior for user vs house resources.
• Changing fortnight accounting behavior.
• Changing expense template schema, API response shape, or route handlers.
• Changing delete semantics or conflict rules for templates that are in use.
• Introducing a global responsive DataTable abstraction before the first page pattern is validated.
• Adding a mobile floating action button unless the sticky header add button proves too crowded during implementation.
• Changing desktop table columns, sorting, pagination, or column visibility behavior except as needed to hide the desktop table on mobile.

Further Notes

This PRD captures the agreed plan from the conversation: keep the desktop table, add a mobile card/list catalog, stack filters on mobile, hide column visibility on mobile, and start with expense templates as the first catalog transformation.

The broader product direction is to make the whole project mobile friendly, but this issue is intentionally narrow so it can be implemented, reviewed, and used as a reference pattern for future catalog pages.