Targ Apps Finance

Targ-Apps-Finance es la aplicación de gestión de gastos personales del workspace TargApps. Está construida con Chroma (framework reactivo Rust → WASM) y usa ES modules como fuente, los cuales se bundlean y recompilan a WASM en build.

Stack

• Framework: Chroma 0.3.2 (pkg/chroma.js — e, hookState, useEffect, useMemo, render).
• Bundler: esbuild (vía chroma build).
• Sin dependencias externas de routing/estado: el router y el store se implementan sobre las primitivas de Chroma.

Estructura de carpetas

Targ-Apps-Finance/
├─ index.html              # Punto de entrada HTML (monta #app)
├─ chroma.json             # Config del proyecto Chroma (modo dynamic)
├─ jsconfig.json           # Resolución de módulos (bundler)
├─ src/
│  ├─ main.js              # Bootstrap: hydratePersist() → render(App, #app)
│  ├─ App.js               # Shell: header + nav + página activa
│  └─ components/          # Piezas de UI reutilizables (PascalCase)
├─ pages/                  # Vistas de nivel de ruta (PascalCase)
│  ├─ Dashboard.js
│  ├─ Transactions.js
│  ├─ Accounts.js
│  ├─ Categories.js
│  ├─ Budgets.js
│  ├─ Reports.js
│  ├─ Settings.js
│  └─ Onboarding.js
├─ logic/                  # Lógica de negocio y estado (sin DOM)
│  ├─ router.js            # Router mínimo basado en location.hash
│  ├─ persist.js           # Hidratar/guardar snapshot Chroma-Fs
│  ├─ settings.js          # Reglas de preferencias (currency, locale, …)
│  ├─ validation.js        # Nombre, monto, moneda
│  ├─ onboarding.js        # Flag + sync de hash
│  ├─ store/               # Estado (signals, reducers, contextos)
│  ├─ persistence/         # Repositorio + export/import sobre persist
│  └─ utils/               # Utilidades puras (formato, fechas, ids)
├─ chroma-fs.json          # IndexedDB targ-apps-finance / files
├─ pkg/                    # Motor Chroma vendored (0.2.0, no editar a mano)
└─ tasks/                  # Tareas del proyecto (TAF-xxx)

Responsabilidades por capa

Router

logic/router.js expone el hook useRouter() que devuelve { route, resolvePage } y el mapa routes:

• route — getter del hash activo (#/dashboard, #/transactions, …). Hash vacío → #/onboarding si el onboarding no está completo, si no #/dashboard.
• resolvePage(hash) — devuelve el componente de página para ese hash (fallback a Dashboard).
• Se sincroniza con el evento hashchange del navegador vía useEffect.
• AppShell monta cada entrada de routes con Show (páginas creadas una vez dentro de FinanceProvider). Un child reactivo () => e(resolvePage(route())) re-invocaría la página al escribir en un form, fuera de la ventana de contexto, y useFinance() fallaría. Hash desconocido → Dashboard.

Es intencionalmente mínimo: sin guards en el router. El guard de onboarding vive en FinanceProvider.

Convención de nombres

Definida en la cabecera de logic/router.js:

• PascalCase → componentes de UI y páginas (Dashboard, Transactions).
• camelCase → módulos de lógica, utilidades y adaptadores (useRouter, formatCurrency).
• kebab-case → archivos de documentación y assets estáticos.

Estado actual

• TAF-003: persistencia Chroma-Fs (logic/persist.js, snapshot finance/snapshot.json; fallback localStorage / memoria).
• TAF-004 / TAF-006: store global (FinanceProvider, useFinance()) con dominio de cuentas (alta, edición, archivo, default, listas derivadas).
• TAF-008/009/010/016: alta, edición, eliminación, listado agrupado y transferencias entre cuentas (logic/store/ledger.js, logic/store/transactions.js, pages/Transactions.js).
• TAF-018: export/import JSON vía logic/persistence/exportImport.js (validación antes de sobrescribir).
• TAF-025: suite npm test (node:test) — persist, dominio de cuentas, ledger, transacciones, filtros e integración E2E (test/logic/integration.test.js).
• Páginas y formularios siguen como wireframes en algunas áreas; la lógica de negocio vive en logic/ y se conecta progresivamente en tareas TAF-005+.

Ver Store global, Ledger y movimientos y Persistencia local.

Licencia

Targ-Apps-Finance está licenciado bajo la GNU GPL versión 3. Ver Licencia GPLv3.