@fayz-ai/plugin-financial 0.1.1

package/src/views/InvoiceListView.tsx

@@ -0,0 +1,177 @@
+import React, { useEffect, useState, useMemo } from 'react'
+import { FileText, CircleDashed, CircleEllipsis, CircleCheckBig, CircleAlert, Ban } from 'lucide-react'
+import type { ColumnDef } from '@tanstack/react-table'
+import { ListView } from '@fayz-ai/ui'
+import { useFinancialConfig, useFinancialStore, formatCurrency } from '../FinancialContext'
+import { SubpageHeader } from '@fayz-ai/ui'
+import { PersonLink } from '@fayz-ai/saas'
+import { useTranslation } from '@fayz-ai/core'
+import type { TransactionDirection, InvoiceStatus, Invoice } from '../types'
+
+const STATUS_OPTIONS: { value: InvoiceStatus; labelKey: string; color: string; icon: React.ElementType }[] = [
+  { value: 'open', labelKey: 'financial.invoice.statusOpen', color: 'bg-info-soft text-info-soft-foreground', icon: CircleDashed },
+  { value: 'partial', labelKey: 'financial.invoice.statusPartial', color: 'bg-warning-soft text-warning-soft-foreground', icon: CircleEllipsis },
+  { value: 'paid', labelKey: 'financial.invoice.statusPaid', color: 'bg-success-soft text-success-soft-foreground', icon: CircleCheckBig },
+  { value: 'overdue', labelKey: 'financial.invoice.statusOverdue', color: 'bg-destructive-soft text-destructive-soft-foreground', icon: CircleAlert },
+  { value: 'cancelled', labelKey: 'financial.invoice.statusCancelled', color: 'bg-muted text-muted-foreground', icon: Ban },
+]
+
+function StatusBadge({ status }: { status: string }) {
+  const t = useTranslation()
+  const opt = STATUS_OPTIONS.find((o) => o.value === status)
+  const Icon = opt?.icon ?? CircleDashed
+  return (
+    <span className={`inline-flex items-center gap-0.5 rounded-full px-2 py-0.5 text-[10px] font-medium ${opt?.color ?? 'bg-muted text-muted-foreground'}`}>
+      <Icon className="h-2.5 w-2.5" /> {opt ? t(opt.labelKey) : status}
+    </span>
+  )
+}
+
+function useInvoiceColumns(currency: { code: string; locale: string; symbol: string }): ColumnDef<Invoice, any>[] {
+  const t = useTranslation()
+  return useMemo(() => [
+    {
+      accessorKey: 'fiscalNumber', header: '#', size: 110,
+      cell: ({ getValue }) => {
+        const num = getValue() as string | undefined
+        return num ? <span className="text-xs font-mono text-muted-foreground">#{num}</span> : <span className="text-muted-foreground">—</span>
+      },
+    },
+    {
+      accessorKey: 'invoiceDate', header: t('financial.invoice.columnDate'),
+      cell: ({ getValue }) => <span className="text-muted-foreground text-xs">{getValue() as string}</span>,
+    },
+    {
+      id: 'description', header: t('financial.invoice.columnDescription'),
+      cell: ({ row }) => (
+        <div onClick={(e) => e.stopPropagation()}>
+          {row.original.contactName ? (
+            <PersonLink personId={row.original.contactId} name={row.original.contactName} size="sm" className="text-sm font-medium" />
+          ) : (
+            <p className="font-medium">—</p>
+          )}
+          {row.original.itemsSummary && <p className="text-[10px] text-muted-foreground truncate max-w-[250px]">{row.original.itemsSummary}</p>}
+        </div>
+      ),
+    },
+    {
+      accessorKey: 'totalAmount', header: t('financial.invoice.columnAmount'), enableSorting: true,
+      cell: ({ row }) => (
+        <span className={`font-medium ${row.original.status === 'cancelled' ? 'line-through text-muted-foreground' : ''}`}>
+          {formatCurrency(row.original.totalAmount, currency)}
+        </span>
+      ),
+    },
+    {
+      accessorKey: 'paidAmount', header: t('financial.invoice.columnPaid'),
+      cell: ({ row }) => (
+        <span className={row.original.status === 'cancelled' ? 'line-through text-muted-foreground' : 'text-muted-foreground'}>
+          {formatCurrency(row.original.paidAmount, currency)}
+        </span>
+      ),
+    },
+    {
+      accessorKey: 'status', header: t('financial.invoice.columnStatus'),
+      cell: ({ getValue }) => <StatusBadge status={getValue() as string} />,
+    },
+    {
+      accessorKey: 'totalInstallments', header: t('financial.invoice.columnInst'),
+      cell: ({ getValue }) => <span className="text-muted-foreground">{getValue() as number}</span>,
+    },
+  ], [currency, t])
+}
+
+export function InvoiceListView({ direction, onNew, onEdit }: {
+  direction: TransactionDirection
+  onNew?: () => void
+  onEdit?: (id: string) => void
+}) {
+  const t = useTranslation()
+  const { currency } = useFinancialConfig()
+  const invoices = useFinancialStore((s) => s.invoices)
+  const invoicesTotal = useFinancialStore((s) => s.invoicesTotal)
+  const invoicesLoading = useFinancialStore((s) => s.invoicesLoading)
+  const fetchInvoices = useFinancialStore((s) => s.fetchInvoices)
+
+  const [search, setSearch] = useState('')
+  const [statusFilter, setStatusFilter] = useState<InvoiceStatus[]>([])
+
+  useEffect(() => {
+    fetchInvoices({
+      direction,
+      status: statusFilter.length > 0 ? statusFilter : undefined,
+      search: search || undefined,
+    })
+  }, [direction, statusFilter, search])
+
+  const filtered = invoices.filter((inv) => inv.direction === direction)
+  const listTitle = direction === 'debit' ? t('financial.invoice.accountsPayable') : t('financial.invoice.accountsReceivable')
+  const columns = useInvoiceColumns(currency)
+  const tags = useMemo(
+    () => STATUS_OPTIONS.filter((o) => o.value !== 'cancelled').map((o) => ({ value: o.value, label: t(o.labelKey) })),
+    [t],
+  )
+
+  // Summary totals from currently visible data
+  const summary = useMemo(() => {
+    let totalAmount = 0
+    let paidAmount = 0
+    let openAmount = 0
+    for (const inv of filtered) {
+      if (inv.status === 'cancelled') continue
+      totalAmount += inv.totalAmount
+      paidAmount += inv.paidAmount
+    }
+    openAmount = totalAmount - paidAmount
+    return { totalAmount, paidAmount, openAmount }
+  }, [filtered])
+
+  const receivedLabel = direction === 'debit' ? t('financial.invoice.summaryPaid') : t('financial.invoice.summaryReceived')
+  const pendingLabel = direction === 'debit' ? t('financial.invoice.summaryPayable') : t('financial.invoice.summaryReceivable')
+
+  return (
+    <div className="space-y-4">
+      <SubpageHeader
+        title={listTitle}
+        subtitle={t('financial.invoice.invoices', { count: filtered.length })}
+      />
+      <ListView<Invoice>
+        columns={columns}
+        data={filtered}
+        loading={invoicesLoading}
+        searchPlaceholder={t('financial.invoice.searchPlaceholder')}
+        search={search}
+        onSearchChange={setSearch}
+        searchDebounce={0}
+        tags={tags}
+        activeTag={statusFilter.length === 1 ? statusFilter[0] : undefined}
+        onTagChange={(v) => setStatusFilter(v ? [v as InvoiceStatus] : [])}
+        newLabel={t('financial.invoice.new')}
+        onNew={onNew}
+        onRowClick={(row) => onEdit?.(row.id)}
+        emptyIcon={FileText}
+        emptyMessage={t('financial.invoice.noInvoices')}
+        emptyActionLabel={onNew ? t('financial.invoice.createFirst') : undefined}
+        onEmptyAction={onNew}
+      />
+      {filtered.length > 0 && !invoicesLoading && (
+        <div className="flex items-center justify-end gap-6 rounded-lg border bg-muted/30 px-5 py-3 text-sm">
+          <div className="flex items-center gap-2">
+            <span className="text-muted-foreground">{t('financial.invoice.summaryTotal')}</span>
+            <span className="font-semibold">{formatCurrency(summary.totalAmount, currency)}</span>
+          </div>
+          <div className="h-4 w-px bg-border" />
+          <div className="flex items-center gap-2">
+            <span className="text-muted-foreground">{receivedLabel}</span>
+            <span className="font-semibold text-success">{formatCurrency(summary.paidAmount, currency)}</span>
+          </div>
+          <div className="h-4 w-px bg-border" />
+          <div className="flex items-center gap-2">
+            <span className="text-muted-foreground">{pendingLabel}</span>
+            <span className="font-semibold text-warning">{formatCurrency(summary.openAmount, currency)}</span>
+          </div>
+        </div>
+      )}
+    </div>
+  )
+}

package/src/views/PayablesView.tsx

@@ -0,0 +1,37 @@
+import React from 'react'
+import { InvoiceListView } from './InvoiceListView'
+import { InvoiceFormView } from './InvoiceFormView'
+import { InvoiceDetailView } from './InvoiceDetailView'
+import type { ViewIntent } from '../FinancialPage'
+
+export function PayablesView({ intent, onNavigate }: {
+  intent: ViewIntent
+  onNavigate: (view: string) => void
+}) {
+  if (intent.mode === 'new') {
+    return <InvoiceFormView direction="debit" onSaved={(id) => onNavigate(id ? `payables-detail:${id}` : 'payables-list')} />
+  }
+
+  if (intent.mode === 'edit' && intent.editId) {
+    return <InvoiceFormView direction="debit" editId={intent.editId} onSaved={() => onNavigate(`payables-detail:${intent.editId}`)} />
+  }
+
+  if (intent.mode === 'detail' && intent.editId) {
+    return (
+      <InvoiceDetailView
+        invoiceId={intent.editId}
+        direction="debit"
+        onBack={() => onNavigate('payables-list')}
+        onEdit={() => onNavigate(`payables-edit:${intent.editId}`)}
+      />
+    )
+  }
+
+  return (
+    <InvoiceListView
+      direction="debit"
+      onNew={() => onNavigate('payables-new')}
+      onEdit={(id) => onNavigate(`payables-detail:${id}`)}
+    />
+  )
+}

package/src/views/ReceivablesView.tsx

@@ -0,0 +1,37 @@
+import React from 'react'
+import { InvoiceListView } from './InvoiceListView'
+import { InvoiceFormView } from './InvoiceFormView'
+import { InvoiceDetailView } from './InvoiceDetailView'
+import type { ViewIntent } from '../FinancialPage'
+
+export function ReceivablesView({ intent, onNavigate }: {
+  intent: ViewIntent
+  onNavigate: (view: string) => void
+}) {
+  if (intent.mode === 'new') {
+    return <InvoiceFormView direction="credit" onSaved={(id) => onNavigate(id ? `receivables-detail:${id}` : 'receivables-list')} />
+  }
+
+  if (intent.mode === 'edit' && intent.editId) {
+    return <InvoiceFormView direction="credit" editId={intent.editId} onSaved={() => onNavigate(`receivables-detail:${intent.editId}`)} />
+  }
+
+  if (intent.mode === 'detail' && intent.editId) {
+    return (
+      <InvoiceDetailView
+        invoiceId={intent.editId}
+        direction="credit"
+        onBack={() => onNavigate('receivables-list')}
+        onEdit={() => onNavigate(`receivables-edit:${intent.editId}`)}
+      />
+    )
+  }
+
+  return (
+    <InvoiceListView
+      direction="credit"
+      onNew={() => onNavigate('receivables-new')}
+      onEdit={(id) => onNavigate(`receivables-detail:${id}`)}
+    />
+  )
+}

package/src/views/StatementsView.tsx

@@ -0,0 +1,123 @@
+import React, { useEffect, useState, useMemo } from 'react'
+import { Receipt } from 'lucide-react'
+import type { ColumnDef } from '@tanstack/react-table'
+import { DataTable } from '@fayz-ai/ui'
+import { useFinancialConfig, useFinancialStore, formatCurrency } from '../FinancialContext'
+import { SubpageHeader } from '@fayz-ai/ui'
+import { DatePicker } from '@fayz-ai/ui'
+import { useTranslation } from '@fayz-ai/core'
+import type { StatementEntry } from '../types'
+
+export function StatementsView() {
+  const t = useTranslation()
+  const { currency } = useFinancialConfig()
+  const bankAccounts = useFinancialStore((s) => s.bankAccounts)
+  const statementEntries = useFinancialStore((s) => s.statementEntries)
+  const statementLoading = useFinancialStore((s) => s.statementLoading)
+  const fetchBankAccounts = useFinancialStore((s) => s.fetchBankAccounts)
+  const fetchStatement = useFinancialStore((s) => s.fetchStatement)
+
+  const [accountId, setAccountId] = useState('')
+  const [dateFrom, setDateFrom] = useState(() => {
+    const d = new Date(); d.setMonth(d.getMonth() - 1)
+    return d.toISOString().slice(0, 10)
+  })
+  const [dateTo, setDateTo] = useState(() => new Date().toISOString().slice(0, 10))
+
+  useEffect(() => { fetchBankAccounts() }, [])
+
+  useEffect(() => {
+    if (accountId) {
+      fetchStatement({ bankAccountId: accountId, dateRange: { from: dateFrom, to: dateTo } })
+    }
+  }, [accountId, dateFrom, dateTo])
+
+  useEffect(() => {
+    if (!accountId && bankAccounts.length > 0) setAccountId(bankAccounts[0].id)
+  }, [bankAccounts])
+
+  const columns: ColumnDef<StatementEntry, any>[] = useMemo(() => [
+    {
+      id: 'date', header: t('financial.statements.columnDate'),
+      cell: ({ row }) => (
+        <span className="text-muted-foreground text-xs">{row.original.movement.paymentDate ?? row.original.movement.dueDate}</span>
+      ),
+    },
+    {
+      id: 'description', header: t('financial.statements.columnDescription'),
+      cell: ({ row }) => (
+        <div>
+          <p className="text-xs font-medium">{row.original.invoice?.contactName || row.original.movement.notes || 'Transaction'}</p>
+          <p className="text-[10px] text-muted-foreground capitalize">{row.original.movement.movementKind}</p>
+        </div>
+      ),
+    },
+    {
+      id: 'debit', header: t('financial.statements.columnDebit'),
+      cell: ({ row }) => (
+        <span className="text-right block text-destructive text-xs">
+          {row.original.movement.direction === 'debit' ? formatCurrency(row.original.movement.paidAmount, currency) : ''}
+        </span>
+      ),
+    },
+    {
+      id: 'credit', header: t('financial.statements.columnCredit'),
+      cell: ({ row }) => (
+        <span className="text-right block text-success text-xs">
+          {row.original.movement.direction === 'credit' ? formatCurrency(row.original.movement.paidAmount, currency) : ''}
+        </span>
+      ),
+    },
+    {
+      id: 'balance', header: t('financial.statements.columnBalance'),
+      cell: ({ row }) => (
+        <span className="text-right block font-medium text-xs">{formatCurrency(row.original.runningBalance, currency)}</span>
+      ),
+    },
+  ], [currency, t])
+
+  return (
+    <div className="space-y-4">
+      <SubpageHeader title={t('financial.statements.title')} subtitle={t('financial.statements.subtitle')} />
+
+      {/* Filters */}
+      <div className="flex flex-col sm:flex-row gap-3 sm:items-end">
+        <div className="flex-1 max-w-xs">
+          <label className="text-[10px] font-medium text-muted-foreground uppercase">{t('financial.statements.account')}</label>
+          <select
+            value={accountId}
+            onChange={(e) => setAccountId(e.target.value)}
+            className="w-full mt-0.5 rounded-input border border-input  bg-card shadow-[inset_0_1px_0_rgb(0_0_0_/0.06)] px-3 py-2 text-sm"
+          >
+            <option value="">{t('financial.statements.selectAccount')}</option>
+            {bankAccounts.map((a) => (
+              <option key={a.id} value={a.id}>{a.name}</option>
+            ))}
+          </select>
+        </div>
+        <div>
+          <label className="text-[10px] font-medium text-muted-foreground uppercase">{t('financial.statements.from')}</label>
+          <DatePicker value={dateFrom} onChange={setDateFrom} className="mt-0.5" />
+        </div>
+        <div>
+          <label className="text-[10px] font-medium text-muted-foreground uppercase">{t('financial.statements.to')}</label>
+          <DatePicker value={dateTo} onChange={setDateTo} className="mt-0.5" />
+        </div>
+      </div>
+
+      {/* Statement table */}
+      {!accountId ? (
+        <div className="flex flex-col items-center justify-center py-12 text-center rounded-lg border-2 border-dashed border-muted">
+          <Receipt className="h-8 w-8 text-muted-foreground mb-2" />
+          <p className="text-sm text-muted-foreground">{t('financial.statements.selectToView')}</p>
+        </div>
+      ) : statementLoading ? (
+        <DataTable columns={columns} data={[]} loading skeletonRows={5} />
+      ) : statementEntries.length === 0 ? (
+        <DataTable columns={columns} data={[]} emptyMessage={t('financial.statements.noTransactions')} />
+      ) : (
+        <DataTable columns={columns} data={statementEntries} />
+      )}
+    </div>
+  )
+}

package/src/views/SummaryView.tsx

@@ -0,0 +1,12 @@
+import React from 'react'
+import { DashboardCanvas } from '@fayz-ai/ui'
+
+/**
+ * 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.
+ */
+export function SummaryView() {
+  return <DashboardCanvas surface="plugin-home" domain="financial" showHeader={false} className="space-y-6" />
+}

package/src/views/dashboardWidgets.tsx

@@ -0,0 +1,191 @@
+import React, { useEffect } from 'react'
+import { ArrowUpRight, ArrowDownRight, AlertTriangle } 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,
+} from '@fayz-ai/ui'
+import { FinancialContextProvider, useFinancialConfig, useFinancialStore, formatCurrency, type ResolvedFinancialConfig } from '../FinancialContext'
+import type { FinancialDataProvider } from '../data/types'
+import type { FinancialUIState } from '../store'
+import type { Invoice } from '../types'
+
+function useEnsureSummary() {
+  const fetchSummary = useFinancialStore((s) => s.fetchSummary)
+  useEffect(() => { void fetchSummary() }, [])
+}
+
+// ---------------------------------------------------------------------------
+// KPIs
+// ---------------------------------------------------------------------------
+
+function TotalBalanceKpi() {
+  const t = useTranslation()
+  const { currency } = useFinancialConfig()
+  const summary = useFinancialStore((s) => s.summary)
+  const loading = useFinancialStore((s) => s.summaryLoading)
+  useEnsureSummary()
+  return <KpiCard label={t('financial.summary.totalBalance')} icon="Wallet" value={formatCurrency(summary?.totalBalance ?? 0, currency)} sub={loading ? undefined : t('financial.summary.allAccounts')} />
+}
+
+function ReceivableKpi() {
+  const t = useTranslation()
+  const { currency } = useFinancialConfig()
+  const summary = useFinancialStore((s) => s.summary)
+  useEnsureSummary()
+  return <KpiCard label={t('financial.summary.receivable')} icon="TrendingUp" value={formatCurrency(summary?.totalReceivable ?? 0, currency)} sub={t('financial.summary.overdue', { count: String(summary?.overdueReceivableCount ?? 0) })} />
+}
+
+function PayableKpi() {
+  const t = useTranslation()
+  const { currency } = useFinancialConfig()
+  const summary = useFinancialStore((s) => s.summary)
+  useEnsureSummary()
+  return <KpiCard label={t('financial.summary.payable')} icon="TrendingDown" value={formatCurrency(summary?.totalPayable ?? 0, currency)} sub={t('financial.summary.overdue', { count: String(summary?.overduePayableCount ?? 0) })} />
+}
+
+function MonthlyFlowKpi() {
+  const t = useTranslation()
+  const { currency } = useFinancialConfig()
+  const summary = useFinancialStore((s) => s.summary)
+  useEnsureSummary()
+  const inflow = summary?.monthlyInflow ?? 0
+  const outflow = summary?.monthlyOutflow ?? 0
+  return <KpiCard label={t('financial.summary.monthlyFlow')} icon="BarChart3" value={formatCurrency(inflow - outflow, currency)} sub={inflow >= outflow ? t('financial.summary.positiveBalance') : t('financial.summary.negativeBalance')} />
+}
+
+// ---------------------------------------------------------------------------
+// Cash flow (recharts) + breakdown + overdue alerts
+// ---------------------------------------------------------------------------
+
+function CashFlowChart() {
+  const t = useTranslation()
+  const summary = useFinancialStore((s) => s.summary)
+  useEnsureSummary()
+  const data = [{ name: t('financial.summary.cashFlow'), income: summary?.monthlyInflow ?? 0, expenses: summary?.monthlyOutflow ?? 0 }]
+  return (
+    <ChartWidget
+      type="bar" title={t('financial.summary.cashFlow')} icon="BarChart3" categoryKey="name" data={data}
+      series={[
+        { dataKey: 'income', label: t('financial.summary.income'), color: 'hsl(var(--success))' },
+        { dataKey: 'expenses', label: t('financial.summary.expenses'), color: 'hsl(var(--destructive))' },
+      ]}
+    />
+  )
+}
+
+function CashFlowBreakdown() {
+  const t = useTranslation()
+  const { currency } = useFinancialConfig()
+  const summary = useFinancialStore((s) => s.summary)
+  useEnsureSummary()
+  const inflow = summary?.monthlyInflow ?? 0
+  const outflow = summary?.monthlyOutflow ?? 0
+  const total = Math.max(inflow + outflow, 1)
+  return (
+    <Card>
+      <CardHeader><CardTitle>{t('financial.summary.cashFlowBreakdown')}</CardTitle></CardHeader>
+      <CardContent className="space-y-4">
+        <div className="space-y-1.5">
+          <div className="flex items-center justify-between text-xs">
+            <span className="flex items-center gap-1.5 text-muted-foreground"><span className="h-2 w-2 rounded-full bg-success" />{t('financial.summary.received')}</span>
+            <span className="font-medium">{formatCurrency(inflow, currency)}</span>
+          </div>
+          <div className="h-2 overflow-hidden rounded-full bg-muted"><div className="h-full rounded-full bg-success" style={{ width: `${(inflow / total) * 100}%` }} /></div>
+        </div>
+        <div className="space-y-1.5">
+          <div className="flex items-center justify-between text-xs">
+            <span className="flex items-center gap-1.5 text-muted-foreground"><span className="h-2 w-2 rounded-full bg-destructive" />{t('financial.summary.paid')}</span>
+            <span className="font-medium">{formatCurrency(outflow, currency)}</span>
+          </div>
+          <div className="h-2 overflow-hidden rounded-full bg-muted"><div className="h-full rounded-full bg-destructive" style={{ width: `${(outflow / total) * 100}%` }} /></div>
+        </div>
+        <div className="border-t pt-2">
+          <div className="flex items-center justify-between text-xs">
+            <span className="text-muted-foreground">{t('financial.summary.net')}</span>
+            <span className={`font-semibold ${inflow - outflow >= 0 ? 'text-success' : 'text-destructive'}`}>{formatCurrency(inflow - outflow, currency)}</span>
+          </div>
+        </div>
+      </CardContent>
+    </Card>
+  )
+}
+
+function OverdueAlerts() {
+  const t = useTranslation()
+  const { currency } = useFinancialConfig()
+  const summary = useFinancialStore((s) => s.summary)
+  useEnsureSummary()
+  const items = [
+    { label: t('financial.summary.overdueReceivable'), value: summary?.overdueReceivableAmount ?? 0, count: summary?.overdueReceivableCount ?? 0, Icon: ArrowUpRight, color: 'text-warning' },
+    { label: t('financial.summary.overduePayable'), value: summary?.overduePayableAmount ?? 0, count: summary?.overduePayableCount ?? 0, Icon: ArrowDownRight, color: 'text-destructive' },
+  ]
+  return (
+    <Card>
+      <CardHeader><CardTitle className="flex items-center gap-2"><AlertTriangle className="h-4 w-4 text-warning" />{t('financial.summary.overdueTitle')}</CardTitle></CardHeader>
+      <CardContent className="space-y-3">
+        {items.map((item) => (
+          <div key={item.label} className="flex items-center justify-between">
+            <div className="flex items-center gap-2"><item.Icon className={`h-3.5 w-3.5 ${item.color}`} /><span className="text-sm text-muted-foreground">{item.label}</span></div>
+            <span className="text-sm font-semibold">{formatCurrency(item.value, currency)}</span>
+          </div>
+        ))}
+        {items.every((i) => i.count === 0) ? <p className="border-t pt-3 text-xs text-muted-foreground">{t('financial.summary.noOverdue')}</p> : null}
+      </CardContent>
+    </Card>
+  )
+}
+
+function RecentTransactions() {
+  const t = useTranslation()
+  const { currency } = useFinancialConfig()
+  const invoices = useFinancialStore((s) => s.invoices)
+  const fetchInvoices = useFinancialStore((s) => s.fetchInvoices)
+  useEffect(() => { void fetchInvoices({ pageSize: 5 }) }, [])
+  const columns: ColumnDef<Invoice, unknown>[] = [
+    { accessorKey: 'contactName', header: t('financial.summary.recentTransactions'), cell: ({ row }) => <span className="font-medium">{row.original.contactName || 'Unknown'}</span> },
+    { id: 'date', header: '', cell: ({ row }) => <span className="text-xs capitalize text-muted-foreground">{row.original.direction} · {row.original.invoiceDate}</span> },
+    { accessorKey: 'totalAmount', header: '', cell: ({ row }) => (
+      <span className={`font-semibold ${row.original.direction === 'credit' ? 'text-success' : 'text-destructive'}`}>
+        {row.original.direction === 'credit' ? '+' : '-'}{formatCurrency(row.original.totalAmount, currency)}
+      </span>
+    ) },
+  ]
+  return <TableWidget title={t('financial.summary.recentTransactions')} icon="CircleDollarSign" columns={columns} data={invoices.slice(0, 5)} emptyMessage={t('financial.summary.noTransactions')} />
+}
+
+// ---------------------------------------------------------------------------
+// Registry builder
+// ---------------------------------------------------------------------------
+
+export function createFinancialDashboardWidgets(ctx: {
+  config: ResolvedFinancialConfig
+  provider: FinancialDataProvider
+  store: StoreApi<FinancialUIState>
+}): DashboardWidgetDef[] {
+  const withCtx = (Inner: React.ComponentType): React.ComponentType<unknown> => {
+    const Wrapped = () => (
+      <FinancialContextProvider config={ctx.config} provider={ctx.provider} store={ctx.store}>
+        <Inner />
+      </FinancialContextProvider>
+    )
+    Wrapped.displayName = `FinancialWidget(${Inner.displayName ?? Inner.name})`
+    return Wrapped
+  }
+
+  return [
+    // Total balance is finance's headline KPI on the global home; the rest are
+    // home-hidden by default (shown on the financial plugin-home, addable via Customize).
+    defineKpiWidget({ id: 'financial.kpi.total-balance', title: 'financial.summary.totalBalance', domain: 'financial', defaultOrder: 0, component: withCtx(TotalBalanceKpi) }),
+    defineKpiWidget({ id: 'financial.kpi.receivable', title: 'financial.summary.receivable', domain: 'financial', defaultOrder: 1, defaultVisible: false, component: withCtx(ReceivableKpi) }),
+    defineKpiWidget({ id: 'financial.kpi.payable', title: 'financial.summary.payable', domain: 'financial', defaultOrder: 2, defaultVisible: false, component: withCtx(PayableKpi) }),
+    defineKpiWidget({ id: 'financial.kpi.monthly-flow', title: 'financial.summary.monthlyFlow', domain: 'financial', defaultOrder: 3, defaultVisible: false, component: withCtx(MonthlyFlowKpi) }),
+    defineChartWidget({ id: 'financial.chart.cash-flow', title: 'financial.summary.cashFlow', domain: 'financial', span: 2, defaultOrder: 10, surfaces: ['plugin-home'], component: withCtx(CashFlowChart) }),
+    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) }),
+  ]
+}