@tmf/finance-front (6.3.0)
Installation
@tmf:registry=npm install @tmf/finance-front@6.3.0"@tmf/finance-front": "6.3.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.
Estado atual (pós TMFP-61304 — religamento do shell). As 7 áreas + ⚙️ Configurações estão religadas às páginas reais do módulo (
AREA_COMPONENTS/src/FinanceApp.tsx+src/pages/areaCompositions.tsx):overview,receivables,payables,fiscal,revenue-contracts,reports,bankingesettings(com sub-navegação paracompanies/parties/teams/categories/tax-rates/gateways/importers) renderizam os componentes de negócio reais, não mais o texto"Conteúdo de … chega nas próximas fases"(esse placeholder textual permanece só como fallback defensivo para uma área futura que ainda não tenha entrada emAREA_COMPONENTS). O shell também consome os tokens de tema--fin-*via classes.fin-*(./styles.css, dark+light) e os labels de navegação vêm do catálogo i18n (ptBR/enUS,getFinanceCatalog—src/i18n/), não mais hardcoded pt-BR. O switcher de empresa segue com dado mock (FINANCE_MOCK_COMPANIES) até o client real (GET /companies) religar — troca sem mudar o contrato do componente.⚠️ Import obrigatório:
@tmf/finance-front/styles.css. O host DEVE importar esse arquivo (ver § Como consumir) — sem ele o shell renderiza sem tema: sem cores, sem contraste dark/light, sem spacing/radius dos tokens--fin-*. Foi exatamente esse o sintoma observado no HelpCor (tela do Financeiro "crua", sem estilo) quando o host montou<FinanceApp/>sem o import do CSS. Não há fallback automático — o pacote não injeta<style>via JS, só exporta o CSS como subpath.
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 religada renderiza a página/composição de blocos real (AREA_COMPONENTS,src/FinanceApp.tsx); só uma área sem entrada nesse mapa cairia no placeholder textual de fallback — hoje as 7 áreas + ⚙️ têm todas entrada.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 (conteúdo real desde TMFP-61308, ver
src/pages/README.md/FUNCIONALIDADES.md): overview, receivables, payables,
banking, fiscal, revenue-contracts, reports, teams, companies, parties.
Como consumir
import { FinanceApp } from '@tmf/finance-front'
import '@tmf/finance-front/styles.css' // ⚠️ OBRIGATÓRIO — ver aviso acima
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 — o import de styles.css
continua obrigatório em qualquer um dos dois casos, pois é ele que carrega os tokens
--fin-* que tanto o shell quanto as páginas isoladas consomem.
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.
Docs de família (valem para back + front juntos):
| Arquivo | Conteúdo |
|---|---|
../UPGRADE.md |
Guia de upgrade e adoção — sair de um pin pré-época (0.x) e chegar à linha 5.x: pins floor-sem-teto, breaking changes reais, migrations no boot, checklist |
../COMPATIBILITY.md |
Matriz de compatibilidade entre as peças e com o contrato OpenAPI congelado |
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 |