@tmf/finance-front (0.2.0)
Installation
@tmf:registry=npm install @tmf/finance-front@0.2.0"@tmf/finance-front": "0.2.0"About this package
@tmf/finance-front
Shell React plug-and-play do módulo Financeiro da TMF (SPEC_FINANCE_LIB.md) — 7 áreas
(Visão Geral, A Receber, A Pagar, Bancos & Conciliação, Fiscal, Receita & Contratos,
Relatórios) + ⚙️ Configurações. Consumido por Hub, TMF9, Priceshow, Helpcor e DAIS.
Estágio: F0 — Fundação (em andamento). Existe o shell vazio: contexto (
FinanceProvider), roteamento próprio, o componenteFinanceAppque monta o menu e renderiza um placeholder por área, um switcher de empresa funcional alimentado por dado mock, os tokens de tema--fin-*(./styles.css) e a infra de i18n (ptBR/enUS,getFinanceCatalogcom deep-merge de overrides —src/i18n/). Nenhuma página de negócio (A Receber, Fiscal, Contratos…) tem conteúdo real ainda — isso chega fase a fase a partir de F1 (§10SPEC_FINANCE_LIB.md), incluindo trocar os labels pt-BR hardcoded do shell pelo catálogo de i18n. O client HTTP gerado do OpenAPI (que troca o switcher mock porGET /companies) é a última subtask em andamento desta mesma fase F0.
D1 (autocontenção total, §2 da spec): ao contrário do @tmf/communication-front, este pacote
não depende de nenhum host além de dois valores obrigatórios (baseUrl/getToken
espelhando AuthPort, tenantId espelhando TenantPort) — não usa AppContract/
ModuleProvider do @tmf/platform-core. Roteamento próprio via History API (sem
react-router); QueryClient interno (não exige QueryClientProvider do host).
O que a lib promete
Contrato público hoje (tudo exportado por src/index.ts — ver __all__ equivalente em TS):
FinanceProvider(+useFinanceContext,FinanceContext) — contexto canônico:baseUrl,getToken,tenantId,can,locale,currency,features,company,routing,slots,theme,adapters,onEvent,queryClient?. Monta seu próprioQueryClienta menos que um seja injetado.FinanceApp— ponto de entrada top-level: envolveFinanceProvidere renderiza o shell (nav das áreas visíveis + switcher de empresa + conteúdo da área ativa). Cada área nativa hoje é só um placeholder ("Conteúdo de … chega nas próximas fases").useFinanceRouting(+readFinanceRouteState,writeFinanceRouteState,FINANCE_URL_KEYS) — roteamento próprio via History API;mode: "query"(?area=&tab=&company=na URL do host) ou"memory"(embed isolado).FINANCE_AREAS/FINANCE_SETTINGS_AREA/getVisibleFinanceAreas/buildFinanceMenu— catálogo das 7 áreas + ⚙️ e a função que cruzafeatures ∩ meta ∩ can()para decidir o que aparece no menu (aba sem permissão nunca aparece — nunca um 403 na cara do usuário).FINANCE_MOCK_COMPANIES/buildCompanySwitcherOptions/shouldShowCompanySwitcher/resolveCompanySwitcherValue— switcher de empresa do header (Consolidado do grupo + empresas, oculto se só existir 1). Dado mock até o client HTTP real (GET /companies) — troca sem mudar o contrato do componente.
Tipos exportados junto de cada um (FinanceProviderProps, FinanceContextValue,
FinanceFeatureKey, FinanceAreaKey, FinanceMenuEntry, FinanceMockCompany, etc.) —
ver src/index.ts para a lista completa.
O que é privado
Só o que passa pelo barrel src/index.ts é contrato público. Hoje isso deixa fora do
contrato, por exemplo: os componentes internos de FinanceApp.tsx
(FinanceAppShell/FinanceMenuEntryContent/FinanceAreaPlaceholder/
FinanceCompanySwitcher) — só FinanceApp é exportado — e qualquer helper interno de
areas.ts/routing.ts/companySwitcher.ts que não apareça na lista de exports. Importar
de @tmf/finance-front/src/* diretamente (em vez do pacote publicado) é o anti-padrão que o
eslint vai proibir (mesmo guardião de @tmf/communication-front).
Instalação
# frontend/.npmrc do host
@tmf:registry=https://git.trademarketingforce.com/api/packages/TMF/npm/
legacy-peer-deps=true
npm install @tmf/finance-front --legacy-peer-deps
Peers obrigatórias: react/react-dom (^18.0.0 || ^19.0.0). Dependência interna:
@tanstack/react-query (^5.0.0, o pacote já a declara — o host não precisa instalar à
parte nem prover QueryClientProvider).
Build & subpath exports
Build via tsup (ESM+CJS+d.ts, noExternal: []/D1 — zero @tmf/* interno empacotado).
Ao contrário de @tmf/communication-front/@tmf/service-desk-front (entry único), este
pacote é multi-entry (§3/§8 SPEC_FINANCE_LIB.md) — o host pode importar só o que usa:
import { FinanceApp } from '@tmf/finance-front' // shell completo
import { useFinanceContext } from '@tmf/finance-front/hooks' // só o contexto/hooks
import { createFinanceClient } from '@tmf/finance-front/client' // só o client HTTP
import OverviewPage from '@tmf/finance-front/pages/overview' // 1 área isolada
import '@tmf/finance-front/styles.css' // tokens --fin-*
Subpaths de página disponíveis hoje (scaffold — conteúdo real chega fase a fase, ver
FUNCIONALIDADES.md): overview, receivables, payables, banking, fiscal,
revenue-contracts, reports, teams, companies, parties.
Como consumir
import { FinanceApp } from '@tmf/finance-front'
export function FinancePage() {
return (
<FinanceApp
baseUrl="/api" // → /api/finance/* (§7)
getToken={() => getAccessToken() ?? ''}
tenantId={currentTenantId}
can={(permission) => userCan(permission)} // espelha o backend (§6.4) — front nunca decide sozinho
locale="pt-BR"
currency="BRL"
features={{ core: true, dashboard: true, contracts: true }}
company={{ initial: 'all', allowAll: true }}
routing={{ mode: 'query', basePath: '/finance' }}
onEvent={(event) => console.debug('finance event', event)}
/>
)
}
Só baseUrl, getToken, tenantId e can são obrigatórios — os demais campos têm
defaults funcionais (§8). Para usar só o contexto sem o shell (ex.: montar UI própria),
consuma FinanceProvider + useFinanceContext diretamente.
Documentação
Referência de contrato: este README + os docstrings de src/context.tsx/src/FinanceApp.tsx/
src/routing.ts/src/areas.ts (cada arquivo documenta o #TMFP-* da subtask que o criou) +
docs/modulos/finance/SPEC_FINANCE_LIB.md (§3, §8) no repo tmf-platform. Histórico de
mudanças em CHANGELOG.md; checklist de conformidade em CONFORMANCE.md; catálogo de
funcionalidades por área em FUNCIONALIDADES.md.
Dependencies
Dependencies
| ID | Version |
|---|---|
| @tanstack/react-query | ^5.0.0 |
Development dependencies
| ID | Version |
|---|---|
| @eslint/js | ^10.0.1 |
| @testing-library/jest-dom | ^6.9.1 |
| @testing-library/react | ^16.3.2 |
| @testing-library/user-event | ^14.6.1 |
| @types/react | ^18.2.47 |
| @types/react-dom | ^18.2.18 |
| @vitejs/plugin-react | ^6.0.3 |
| eslint | ^10.7.0 |
| eslint-plugin-react-hooks | ^7.1.1 |
| globals | ^17.7.0 |
| jsdom | ^29.1.1 |
| openapi-typescript | ^7.13.0 |
| react | ^19.0.0 |
| react-dom | ^19.0.0 |
| tsup | ^8.5.1 |
| typescript | ^5.3.3 |
| typescript-eslint | ^8.63.0 |
| vite | ^8.1.4 |
| vitest | ^4.1.10 |
Peer dependencies
| ID | Version |
|---|---|
| react | ^18.0.0 || ^19.0.0 |
| react-dom | ^18.0.0 || ^19.0.0 |