@fayz-ai/plugin-financial 0.1.7 → 0.2.0

package/src/views/SummaryView.tsx

@@ -1,12 +1,203 @@
-import React from 'react'
+import React, { useEffect, useMemo } from 'react'
+import {
+  ShoppingCart, Car, Home, Utensils, Zap, Film, HeartPulse, Dumbbell,
+  Music, ShoppingBag, Landmark, Wallet, CircleDollarSign, Paperclip,
+} from 'lucide-react'
 import { DashboardCanvas } from '@fayz-ai/ui'
+import { useTranslation } from '@fayz-ai/core'
+import { useFinancialConfig, useFinancialStore, formatCurrency } from '../FinancialContext'
+import type { StatementEntry } from '../types'
 
 /**
- * Financial summary. KPIs, cash-flow chart, breakdown, overdue alerts and the
- * recent-transactions table are registered dashboard widgets (see
- * ./dashboardWidgets), rendered through the shared DashboardCanvas; the
- * total-balance KPI also surfaces on the global app home.
+ * Financial summary. On desktop (md+) it renders the rich multi-column dashboard
+ * (KPI cards + Fluxo de Caixa chart + breakdown + overdue alerts + recent-
+ * transactions table) via the shared DashboardCanvas. On mobile (<md) it swaps
+ * to a Mobills-grade experience: a compact KPI strip over a date-grouped
+ * transaction list. The two paths share the same store — no forked screen.
  */
 export function SummaryView() {
-  return <DashboardCanvas surface="plugin-home" domain="financial" showHeader={false} className="space-y-6" />
+  return (
+    <>
+      {/* Mobile: Mobills-style transaction-led summary */}
+      <div className="md:hidden">
+        <MobileSummary />
+      </div>
+      {/* Desktop: rich dashboard canvas (unchanged) */}
+      <DashboardCanvas
+        surface="plugin-home"
+        domain="financial"
+        showHeader={false}
+        className="hidden space-y-6 md:block"
+      />
+    </>
+  )
+}
+
+// ---------------------------------------------------------------------------
+// Mobile summary (Mobills-grade)
+// ---------------------------------------------------------------------------
+
+// keyword → category glyph, so each row leads with a recognizable colored circle
+// (Mobills-style). Purely cosmetic and safe while categories aren't modeled yet;
+// falls back to a generic money glyph.
+function categoryIcon(label: string): React.ElementType {
+  const s = label.toLowerCase()
+  if (/(mercado|super|padaria|extra|p[aã]o|hortifr)/.test(s)) return ShoppingCart
+  if (/(uber|99|posto|shell|gasol|combust|carro)/.test(s)) return Car
+  if (/(aluguel|casa|condom|im[oó]vel)/.test(s)) return Home
+  if (/(ifood|restaurante|outback|lanche|food|bar\b)/.test(s)) return Utensils
+  if (/(luz|energia|enel|internet|vivo|conta de|[aá]gua)/.test(s)) return Zap
+  if (/(cinema|netflix|cinemark|filme|disney|prime)/.test(s)) return Film
+  if (/(farm|drogasil|sa[uú]de|plano|hospital|m[eé]dic)/.test(s)) return HeartPulse
+  if (/(academia|smartfit|gym|treino)/.test(s)) return Dumbbell
+  if (/(spotify|music|deezer)/.test(s)) return Music
+  if (/(amazon|shopping|loja|magaz|americanas|mercado livre)/.test(s)) return ShoppingBag
+  if (/(fatura|cart[aã]o|nubank|banco|boleto)/.test(s)) return Landmark
+  if (/(sal[aá]rio|freel|pix|reembolso|receb|renda|d[ií]vidend)/.test(s)) return Wallet
+  return CircleDollarSign
+}
+
+function useDateLabel() {
+  const t = useTranslation()
+  const { currency } = useFinancialConfig()
+  return useMemo(() => {
+    const todayStr = new Date().toISOString().slice(0, 10)
+    const y = new Date(); y.setDate(y.getDate() - 1)
+    const yesterdayStr = y.toISOString().slice(0, 10)
+    return (dateStr: string): string => {
+      if (dateStr === todayStr) return t('financial.summary.today')
+      if (dateStr === yesterdayStr) return t('financial.summary.yesterday')
+      try {
+        return new Date(`${dateStr}T00:00:00`).toLocaleDateString(currency.locale, {
+          weekday: 'short', day: '2-digit', month: 'short',
+        })
+      } catch {
+        return dateStr
+      }
+    }
+  }, [t, currency.locale])
+}
+
+function MobileSummary() {
+  const t = useTranslation()
+  const { currency } = useFinancialConfig()
+  const summary = useFinancialStore((s) => s.summary)
+  const statement = useFinancialStore((s) => s.statement)
+  const bankAccounts = useFinancialStore((s) => s.bankAccounts)
+  const fetchSummary = useFinancialStore((s) => s.fetchSummary)
+  const fetchBankAccounts = useFinancialStore((s) => s.fetchBankAccounts)
+  const fetchStatement = useFinancialStore((s) => s.fetchStatement)
+  const dateLabel = useDateLabel()
+
+  useEffect(() => {
+    void fetchSummary()
+    void fetchBankAccounts()
+    const to = new Date().toISOString().slice(0, 10)
+    const from = new Date(); from.setDate(from.getDate() - 90)
+    void fetchStatement({ dateRange: { from: from.toISOString().slice(0, 10), to } })
+  }, [])
+
+  const fmt = (n: number) => formatCurrency(n, currency)
+  const inflow = summary?.monthlyInflow ?? 0
+  const outflow = summary?.monthlyOutflow ?? 0
+
+  const accountName = useMemo(() => {
+    const map = new Map(bankAccounts.map((a) => [a.id, a.name]))
+    return (id?: string) => (id ? map.get(id) ?? '' : '')
+  }, [bankAccounts])
+
+  // Realized cash events grouped by day (most recent first). Transfers are
+  // dropped — they're internal and would double-count in a personal feed.
+  const groups = useMemo(() => {
+    const entries = (statement?.entries ?? []).filter((e) => e.entryKind === 'movement')
+    const byDate = new Map<string, StatementEntry[]>()
+    for (const e of entries) {
+      const d = e.movement.paymentDate ?? e.movement.dueDate
+      const bucket = byDate.get(d)
+      if (bucket) bucket.push(e)
+      else byDate.set(d, [e])
+    }
+    return [...byDate.entries()].sort((a, b) => b[0].localeCompare(a[0]))
+  }, [statement])
+
+  return (
+    <div className="space-y-4">
+      {/* Compact KPI strip */}
+      <div className="grid grid-cols-2 gap-2">
+        <div className="col-span-2 rounded-xl border bg-card p-4">
+          <p className="text-xs text-muted-foreground">{t('financial.summary.totalBalance')}</p>
+          <p className="mt-0.5 text-2xl font-semibold">{fmt(summary?.totalBalance ?? 0)}</p>
+        </div>
+        <div className="rounded-xl border bg-card p-3">
+          <p className="text-[11px] text-muted-foreground">{t('financial.summary.income')}</p>
+          <p className="mt-0.5 text-base font-semibold text-success">{fmt(inflow)}</p>
+        </div>
+        <div className="rounded-xl border bg-card p-3">
+          <p className="text-[11px] text-muted-foreground">{t('financial.summary.expenses')}</p>
+          <p className="mt-0.5 text-base font-semibold text-destructive">{fmt(outflow)}</p>
+        </div>
+      </div>
+
+      {/* Date-grouped transaction list */}
+      {groups.length === 0 ? (
+        <div className="rounded-xl border border-dashed py-12 text-center text-sm text-muted-foreground">
+          {t('financial.summary.noTransactions')}
+        </div>
+      ) : (
+        <div className="space-y-4">
+          {groups.map(([date, rows]) => (
+            <div key={date} className="space-y-1.5">
+              <p className="px-1 text-xs font-medium uppercase tracking-wide text-muted-foreground">
+                {dateLabel(date)}
+              </p>
+              <div className="divide-y overflow-hidden rounded-xl border bg-card">
+                {rows.map((e) => {
+                  const isCredit = e.movement.direction === 'credit'
+                  const title = e.invoice?.contactName || e.movement.notes || t('financial.summary.transactionsTitle')
+                  const Icon = categoryIcon(title)
+                  const category = isCredit ? t('financial.summary.income') : t('financial.summary.expenses')
+                  const acct = accountName(e.movement.bankAccountId)
+                  const subtitle = acct ? `${category} · ${acct}` : category
+                  // FAY-1226: a snapped receipt lives on the invoice metadata.
+                  const receiptUrl = (e.invoice?.metadata as { receiptUrl?: string } | undefined)?.receiptUrl
+                  return (
+                    <div key={e.movement.id} className="flex items-center gap-3 px-3 py-2.5">
+                      <span
+                        className={`flex h-9 w-9 shrink-0 items-center justify-center rounded-full ${
+                          isCredit
+                            ? 'bg-success-soft text-success-soft-foreground'
+                            : 'bg-destructive-soft text-destructive-soft-foreground'
+                        }`}
+                      >
+                        <Icon className="h-4 w-4" />
+                      </span>
+                      <div className="min-w-0 flex-1">
+                        <p className="flex items-center gap-1.5 truncate text-sm font-medium">
+                          {title}
+                          {receiptUrl && (
+                            <Paperclip className="h-3 w-3 shrink-0 text-muted-foreground" aria-label={t('financial.quickTx.receiptAttached')} />
+                          )}
+                        </p>
+                        <p className="truncate text-xs text-muted-foreground">{subtitle}</p>
+                      </div>
+                      {receiptUrl && (
+                        <img
+                          src={receiptUrl}
+                          alt={t('financial.quickTx.receiptAttached')}
+                          className="h-9 w-9 shrink-0 rounded-md border object-cover"
+                        />
+                      )}
+                      <span className={`shrink-0 text-sm font-semibold ${isCredit ? 'text-success' : 'text-destructive'}`}>
+                        {isCredit ? '+' : '-'}{fmt(e.net)}
+                      </span>
+                    </div>
+                  )
+                })}
+              </div>
+            </div>
+          ))}
+        </div>
+      )}
+    </div>
+  )
 }

package/src/views/dashboardWidgets.tsx

@@ -1,17 +1,17 @@
 import React, { useEffect } from 'react'
-import { ArrowUpRight, ArrowDownRight, AlertTriangle } from 'lucide-react'
+import { ArrowUpRight, ArrowDownRight, AlertTriangle, CreditCard as CreditCardIcon, Eye, EyeOff } from 'lucide-react'
 import type { ColumnDef } from '@tanstack/react-table'
 import type { StoreApi } from 'zustand'
 import type { DashboardWidgetDef } from '@fayz-ai/core'
 import { useTranslation } from '@fayz-ai/core'
 import {
-  KpiCard, ChartWidget, TableWidget, Card, CardHeader, CardTitle, CardContent,
-  defineKpiWidget, defineChartWidget, defineCustomWidget, defineTableWidget,
+  KpiCard, ChartWidget, TableWidget, Card, CardHeader, CardTitle, CardContent, GoldCard,
+  defineKpiWidget, defineChartWidget, defineCustomWidget, defineTableWidget, useDashboardNavigate,
 } from '@fayz-ai/ui'
-import { FinancialContextProvider, useFinancialConfig, useFinancialStore, formatCurrency, type ResolvedFinancialConfig } from '../FinancialContext'
+import { FinancialContextProvider, useFinancialConfig, useFinancialProvider, useFinancialStore, formatCurrency, type ResolvedFinancialConfig } from '../FinancialContext'
 import type { FinancialDataProvider } from '../data/types'
 import type { FinancialUIState } from '../store'
-import type { Invoice } from '../types'
+import type { Invoice, FinancialMovement } from '../types'
 
 function useEnsureSummary() {
   const fetchSummary = useFinancialStore((s) => s.fetchSummary)
@@ -157,6 +157,239 @@ function RecentTransactions() {
   return <TableWidget title={t('financial.summary.recentTransactions')} icon="CircleDollarSign" columns={columns} data={invoices.slice(0, 5)} emptyMessage={t('financial.summary.noTransactions')} />
 }
 
+// ---------------------------------------------------------------------------
+// HOME surface (B2C) — a phone-first money dashboard that reflows into cells on
+// desktop. These render on surface="home" only; the plugin-home Resumo widgets
+// above are untouched. Same store/provider, so figures match the Financeiro
+// module (FAY-1233 mobile-summary logic, generalized into reusable widgets).
+// ---------------------------------------------------------------------------
+
+/** Human "due in N days" label from a YYYY-MM-DD due date. */
+function useDueLabel() {
+  const t = useTranslation()
+  return (dueDate: string): string => {
+    const today = new Date()
+    today.setHours(0, 0, 0, 0)
+    const due = new Date(`${dueDate}T00:00:00`)
+    const days = Math.round((due.getTime() - today.getTime()) / 86_400_000)
+    if (days < 0) return t('financial.home.overdueDays', { count: String(Math.abs(days)) })
+    if (days === 0) return t('financial.home.dueToday')
+    if (days === 1) return t('financial.home.dueTomorrow')
+    return t('financial.home.dueInDays', { count: String(days) })
+  }
+}
+
+/** Branded balance hero — Saldo + eye-toggle + clickable Entradas/Saídas pills.
+ *  Compact band (span-4): tight padding so it never becomes a tall empty block on
+ *  desktop. Pills deep-link into the Financeiro module (receivables / payables). */
+function BalanceHero() {
+  const t = useTranslation()
+  const { currency } = useFinancialConfig()
+  const summary = useFinancialStore((s) => s.summary)
+  const navigate = useDashboardNavigate()
+  useEnsureSummary()
+  const [hidden, setHidden] = React.useState(false)
+  const money = (v: number | null | undefined) => (hidden ? '••••••' : formatCurrency(v ?? 0, currency))
+  const inflow = summary?.monthlyInflow ?? 0
+  const outflow = summary?.monthlyOutflow ?? 0
+  return (
+    <GoldCard branded className="px-5 py-4 text-center md:px-8 md:py-5">
+      <p className="text-xs font-medium uppercase tracking-wide opacity-75">{t('financial.home.balance')}</p>
+      <div className="mt-0.5 flex items-center justify-center gap-2.5">
+        <span className="text-3xl font-bold tracking-tight tabular-nums md:text-4xl">{money(summary?.totalBalance)}</span>
+        <button
+          type="button"
+          onClick={() => setHidden((h) => !h)}
+          aria-label={hidden ? t('financial.home.showBalance') : t('financial.home.hideBalance')}
+          className="rounded-full p-1.5 text-primary-foreground/80 transition-colors hover:bg-white/10"
+        >
+          {hidden ? <EyeOff className="h-5 w-5" /> : <Eye className="h-5 w-5" />}
+        </button>
+      </div>
+      <div className="mx-auto mt-3 grid max-w-lg grid-cols-2 gap-3">
+        <button
+          type="button"
+          onClick={() => navigate('/financial/receivables-list')}
+          aria-label={t('financial.home.inflow')}
+          className="flex cursor-pointer items-center gap-2 rounded-2xl bg-white/10 px-3 py-2 text-left transition-colors hover:bg-white/20"
+        >
+          <span className="flex h-8 w-8 shrink-0 items-center justify-center rounded-full bg-emerald-500/90">
+            <ArrowUpRight className="h-4 w-4 text-white" />
+          </span>
+          <span className="min-w-0">
+            <span className="block text-[11px] uppercase tracking-wide opacity-70">{t('financial.home.inflow')}</span>
+            <span className="block truncate text-sm font-semibold tabular-nums">{money(inflow)}</span>
+          </span>
+        </button>
+        <button
+          type="button"
+          onClick={() => navigate('/financial/payables-list')}
+          aria-label={t('financial.home.outflow')}
+          className="flex cursor-pointer items-center gap-2 rounded-2xl bg-white/10 px-3 py-2 text-left transition-colors hover:bg-white/20"
+        >
+          <span className="flex h-8 w-8 shrink-0 items-center justify-center rounded-full bg-rose-500/90">
+            <ArrowDownRight className="h-4 w-4 text-white" />
+          </span>
+          <span className="min-w-0">
+            <span className="block text-[11px] uppercase tracking-wide opacity-70">{t('financial.home.outflow')}</span>
+            <span className="block truncate text-sm font-semibold tabular-nums">{money(outflow)}</span>
+          </span>
+        </button>
+      </div>
+    </GoldCard>
+  )
+}
+
+// ---------------------------------------------------------------------------
+// HOME charts — spend-by-category (donut) + cash-flow (in vs out). Both read the
+// same provider/store as the module, so figures stay coherent. surface 'home'
+// only (the plugin-home Resumo keeps its own cash-flow chart untouched).
+// ---------------------------------------------------------------------------
+
+/** Provider-agnostic expense classifier: maps a movement's label to a spend
+ *  bucket by keyword (pt-BR + en). Checked in priority order; first hit wins. */
+const SPEND_CATEGORIES: Array<{ key: string; keywords: string[] }> = [
+  { key: 'subscriptions', keywords: ['netflix', 'spotify', 'prime video', 'disney', 'hbo', ' max', 'youtube', 'apple', 'assinatura', 'subscription'] },
+  { key: 'groceries', keywords: ['supermercado', 'mercado', 'padaria', 'hortifruti', 'feira', 'açougue', 'grocery', 'market'] },
+  { key: 'transport', keywords: ['uber', '99', 'taxi', 'posto', 'shell', 'ipiranga', 'combustível', 'gasolina', 'metrô', 'ônibus', 'transport', 'fuel'] },
+  { key: 'dining', keywords: ['ifood', 'rappi', 'restaurante', 'outback', 'lanchonete', 'pizzaria', 'café', 'cafeteria', 'mcdonald', 'burger', 'food'] },
+  { key: 'home', keywords: ['aluguel', 'condomínio', 'luz', 'enel', 'água', 'sabesp', 'internet', 'vivo', 'claro', 'gás', 'iptu', 'rent', 'utilit'] },
+  { key: 'health', keywords: ['farmácia', 'farmacia', 'drogasil', 'drogaria', 'academia', 'smartfit', 'clínica', 'hospital', 'médico', 'saúde', 'gym', 'fitness', 'health', 'pharmac'] },
+  { key: 'leisure', keywords: ['cinema', 'cinemark', 'ingresso', 'show', 'teatro', 'viagem', 'hotel', 'steam', 'leisure'] },
+  { key: 'shopping', keywords: ['amazon', 'magalu', 'shopee', 'aliexpress', 'loja', 'shopping', 'zara', 'renner', 'store'] },
+]
+
+function categorizeSpend(notes: string | undefined): string {
+  const s = (notes ?? '').toLowerCase()
+  for (const c of SPEND_CATEGORIES) if (c.keywords.some((k) => s.includes(k))) return c.key
+  return 'other'
+}
+
+/** "Gastos por categoria" — realized expenses grouped into a donut. */
+function SpendByCategoryChart() {
+  const t = useTranslation()
+  const provider = useFinancialProvider()
+  const [rows, setRows] = React.useState<Array<{ name: string; value: number }>>([])
+  useEffect(() => {
+    let alive = true
+    void (async () => {
+      const res = await provider.getMovements({ status: 'paid', direction: 'debit' })
+      if (!alive) return
+      const totals = new Map<string, number>()
+      for (const m of res.data) {
+        if (m.movementKind === 'transfer') continue
+        const key = categorizeSpend(m.notes)
+        totals.set(key, (totals.get(key) ?? 0) + (m.paidAmount || m.amount))
+      }
+      setRows(
+        [...totals.entries()]
+          .sort((a, b) => b[1] - a[1])
+          .map(([key, value]) => ({ name: t(`financial.home.category.${key}`), value: Math.round(value * 100) / 100 })),
+      )
+    })()
+    return () => { alive = false }
+  }, [provider])
+  if (rows.length === 0) {
+    return (
+      <Card>
+        <CardHeader><CardTitle>{t('financial.home.spendByCategory')}</CardTitle></CardHeader>
+        <CardContent className="flex h-[200px] items-center justify-center text-sm text-muted-foreground">
+          {t('financial.home.noSpend')}
+        </CardContent>
+      </Card>
+    )
+  }
+  return (
+    <ChartWidget
+      type="pie" title={t('financial.home.spendByCategory')} icon="PieChart" categoryKey="name" data={rows}
+      series={[{ dataKey: 'value', label: t('financial.home.spendByCategory') }]}
+    />
+  )
+}
+
+/** "Próximas contas" — pending payable bills, soonest due first. */
+function UpcomingBills() {
+  const t = useTranslation()
+  const { currency } = useFinancialConfig()
+  const provider = useFinancialProvider()
+  const dueLabel = useDueLabel()
+  const [bills, setBills] = React.useState<FinancialMovement[]>([])
+  useEffect(() => {
+    let alive = true
+    void (async () => {
+      const pending = await provider.getMovements({ status: 'pending' })
+      if (!alive) return
+      setBills(
+        pending.data
+          .filter((m) => m.direction === 'debit' && m.movementKind === 'bill')
+          .sort((a, b) => a.dueDate.localeCompare(b.dueDate)),
+      )
+    })()
+    return () => { alive = false }
+  }, [provider])
+  return (
+    <GoldCard className="p-0 overflow-hidden">
+      <div className="flex items-center justify-between px-4 pt-4">
+        <h2 className="text-sm font-semibold text-foreground">{t('financial.home.upcomingBills')}</h2>
+      </div>
+      <div className="mt-3">
+        {bills.length === 0 ? (
+          <div className="px-4 py-6 text-center text-xs text-muted-foreground">{t('financial.home.noBills')}</div>
+        ) : (
+          bills.map((bill, i) => (
+            <div key={bill.id} className={'flex items-center justify-between px-4 py-3.5' + (i > 0 ? ' border-t border-border' : '')}>
+              <div className="min-w-0">
+                <p className="truncate text-sm font-medium text-foreground">{bill.notes ?? t('financial.home.bill')}</p>
+                <p className="text-xs text-muted-foreground">{dueLabel(bill.dueDate)}</p>
+              </div>
+              <span className="shrink-0 text-sm font-semibold tabular-nums text-foreground">
+                {formatCurrency(bill.amount - bill.paidAmount, currency)}
+              </span>
+            </div>
+          ))
+        )}
+      </div>
+    </GoldCard>
+  )
+}
+
+/** "Cartões" — credit-card accounts with current bill + available limit. */
+function CreditCards() {
+  const t = useTranslation()
+  const { currency } = useFinancialConfig()
+  const bankAccounts = useFinancialStore((s) => s.bankAccounts)
+  const fetchBankAccounts = useFinancialStore((s) => s.fetchBankAccounts)
+  useEffect(() => { void fetchBankAccounts() }, [])
+  const cards = bankAccounts.filter((a) => a.accountType === 'credit_card')
+  return (
+    <GoldCard className="bg-transparent border-0 p-0 shadow-none">
+      <h2 className="mb-3 text-sm font-semibold text-foreground">{t('financial.home.cards')}</h2>
+      <div className="space-y-3">
+        {cards.map((card) => {
+          const fatura = Math.abs(Math.min(0, card.currentBalance))
+          const limite = Math.max(0, (card.creditLimit ?? 0) - fatura)
+          return (
+            <div key={card.id} className="rounded-2xl bg-gradient-to-br from-violet-600 to-indigo-700 p-4 text-white shadow-md">
+              <div className="flex items-center justify-between">
+                <span className="text-sm font-semibold">{card.bankName ?? card.name}</span>
+                <CreditCardIcon className="h-5 w-5 opacity-80" />
+              </div>
+              <p className="mt-6 text-[11px] uppercase tracking-wide opacity-70">{t('financial.home.currentBill')}</p>
+              <p className="text-xl font-bold tabular-nums">{formatCurrency(fatura, currency)}</p>
+              <p className="mt-2 text-[11px] opacity-70">{t('financial.home.availableLimit')} {formatCurrency(limite, currency)}</p>
+            </div>
+          )
+        })}
+        {cards.length === 0 ? (
+          <div className="flex items-center justify-center rounded-2xl border border-dashed border-border py-6 text-sm font-medium text-muted-foreground">
+            + {t('financial.home.addCard')}
+          </div>
+        ) : null}
+      </div>
+    </GoldCard>
+  )
+}
+
 // ---------------------------------------------------------------------------
 // Registry builder
 // ---------------------------------------------------------------------------
@@ -187,5 +420,18 @@ export function createFinancialDashboardWidgets(ctx: {
     defineCustomWidget({ id: 'financial.panel.breakdown', title: 'financial.summary.cashFlowBreakdown', domain: 'financial', span: 1, defaultOrder: 11, surfaces: ['plugin-home'], component: withCtx(CashFlowBreakdown) }),
     defineCustomWidget({ id: 'financial.panel.overdue', title: 'financial.summary.overdueTitle', domain: 'financial', span: 1, defaultOrder: 12, surfaces: ['plugin-home'], component: withCtx(OverdueAlerts) }),
     defineTableWidget({ id: 'financial.table.recent', title: 'financial.summary.recentTransactions', domain: 'financial', span: 4, defaultOrder: 20, surfaces: ['plugin-home'], component: withCtx(RecentTransactions) }),
+
+    // FINANCE-HOME surface (B2C phone-first dashboard) — a compact analytical
+    // layout: hero band → charts row (spend-by-category + cash-flow) → bills +
+    // cards. This is a dedicated consumer surface (norman-ai's money screen), NOT
+    // the universal B2B 'home': a full-bleed balance hero and credit-card tiles
+    // are personal-finance chrome that would leak into every app that merely
+    // enables plugin-financial (e.g. the beauty-saas Painel). Apps that want them
+    // opt in explicitly by rendering <DashboardCanvas surface="finance-home">.
+    defineCustomWidget({ id: 'financial.hero.balance', title: 'financial.home.balance', domain: 'financial', span: 4, defaultOrder: 0, surfaces: ['finance-home'], component: withCtx(BalanceHero) }),
+    defineChartWidget({ id: 'financial.chart.spend-by-category', title: 'financial.home.spendByCategory', domain: 'financial', span: 2, defaultOrder: 1, surfaces: ['finance-home'], component: withCtx(SpendByCategoryChart) }),
+    defineChartWidget({ id: 'financial.chart.cash-flow-home', title: 'financial.summary.cashFlow', domain: 'financial', span: 2, defaultOrder: 2, surfaces: ['finance-home'], component: withCtx(CashFlowChart) }),
+    defineCustomWidget({ id: 'financial.list.upcoming-bills', title: 'financial.home.upcomingBills', domain: 'financial', span: 2, defaultOrder: 3, surfaces: ['finance-home'], component: withCtx(UpcomingBills) }),
+    defineCustomWidget({ id: 'financial.cards', title: 'financial.home.cards', domain: 'financial', span: 2, defaultOrder: 4, surfaces: ['finance-home'], component: withCtx(CreditCards) }),
   ]
 }