@fayz-ai/plugin-reports 0.1.1

package/src/export/excel.ts

@@ -0,0 +1,42 @@
+import type { ReportColumnDef } from '../types'
+import { formatValuePlain } from '../lib/columns'
+
+// Opaque dynamic import — hidden from Vite's static analysis so it won't
+// fail when xlsx is not installed (it's an optional peer dependency).
+const load = (m: string) => new Function('m', 'return import(m)')(m) as Promise<any>
+
+export async function exportToExcel(
+  columns: ReportColumnDef[],
+  data: Record<string, any>[],
+  filename: string,
+  currency?: string,
+): Promise<void> {
+  const XLSX = await load('xlsx')
+  const visibleCols = columns.filter((c) => c.visible !== false)
+
+  const header = visibleCols.map((c) => c.label)
+  const rows = data.map((row) =>
+    visibleCols.map((col) => {
+      const value = row[col.key]
+      if (col.type === 'number' || col.type === 'currency') {
+        const num = typeof value === 'number' ? value : parseFloat(value)
+        return isNaN(num) ? '' : num
+      }
+      return formatValuePlain(value, col, currency)
+    }),
+  )
+
+  const ws = XLSX.utils.aoa_to_sheet([header, ...rows])
+  const wb = XLSX.utils.book_new()
+  XLSX.utils.book_append_sheet(wb, ws, 'Report')
+  XLSX.writeFile(wb, `${filename}.xlsx`)
+}
+
+export async function isExcelAvailable(): Promise<boolean> {
+  try {
+    await load('xlsx')
+    return true
+  } catch {
+    return false
+  }
+}

package/src/export/pdf.ts

@@ -0,0 +1,47 @@
+import type { ReportColumnDef } from '../types'
+import { formatValuePlain } from '../lib/columns'
+
+// Opaque dynamic import — hidden from Vite's static analysis so it won't
+// fail when jspdf is not installed (it's an optional peer dependency).
+const load = (m: string) => new Function('m', 'return import(m)')(m) as Promise<any>
+
+export async function exportToPdf(
+  columns: ReportColumnDef[],
+  data: Record<string, any>[],
+  filename: string,
+  options?: { title?: string; currency?: string },
+): Promise<void> {
+  const { default: jsPDF } = await load('jspdf')
+  await load('jspdf-autotable')
+
+  const visibleCols = columns.filter((c) => c.visible !== false)
+
+  const doc = new jsPDF({ orientation: visibleCols.length > 6 ? 'landscape' : 'portrait' })
+
+  if (options?.title) {
+    doc.setFontSize(14)
+    doc.text(options.title, 14, 20)
+  }
+
+  ;(doc as any).autoTable({
+    startY: options?.title ? 30 : 14,
+    head: [visibleCols.map((c) => c.label)],
+    body: data.map((row) =>
+      visibleCols.map((col) => formatValuePlain(row[col.key], col, options?.currency)),
+    ),
+    styles: { fontSize: 8 },
+    headStyles: { fillColor: [100, 100, 100] },
+  })
+
+  doc.save(`${filename}.pdf`)
+}
+
+export async function isPdfAvailable(): Promise<boolean> {
+  try {
+    await load('jspdf')
+    await load('jspdf-autotable')
+    return true
+  } catch {
+    return false
+  }
+}

package/src/hooks/useReportData.ts

@@ -0,0 +1,123 @@
+import { useState, useCallback, useRef } from 'react'
+import type { ReportDef, ReportQueryState, ReportDateRange } from '../types'
+import type { ReportDataProvider, ReportResult } from '../data/types'
+import { dedup } from '@fayz-ai/saas'
+
+function defaultDateRange(): ReportDateRange {
+  const now = new Date()
+  const from = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}-01`
+  const to = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}-${String(now.getDate()).padStart(2, '0')}`
+  return { from, to }
+}
+
+function buildDefaultFilters(report: ReportDef): Record<string, any> {
+  const filters: Record<string, any> = {}
+  for (const f of report.filters ?? []) {
+    if (f.defaultValue !== undefined) filters[f.key] = f.defaultValue
+  }
+  return filters
+}
+
+export interface UseReportDataReturn {
+  data: Record<string, any>[]
+  total: number
+  loading: boolean
+  generated: boolean
+  error: string | null
+  query: ReportQueryState
+  generate: () => void
+  setDateRange: (range: ReportDateRange) => void
+  setFilter: (key: string, value: any) => void
+  setSort: (sortBy: string) => void
+  setPage: (page: number) => void
+  setPageSize: (size: number) => void
+  setSearch: (search: string) => void
+}
+
+export function useReportData(
+  report: ReportDef,
+  provider: ReportDataProvider,
+  defaultPageSize: number = 50,
+): UseReportDataReturn {
+  const [query, setQuery] = useState<ReportQueryState>({
+    dateRange: defaultDateRange(),
+    filters: buildDefaultFilters(report),
+    sortBy: report.dataSource.defaultSort,
+    sortDir: report.dataSource.defaultSortDir ?? 'desc',
+    page: 1,
+    pageSize: defaultPageSize,
+  })
+
+  const [result, setResult] = useState<ReportResult>({ data: [], total: 0 })
+  const [loading, setLoading] = useState(false)
+  const [generated, setGenerated] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+  const queryRef = useRef(query)
+  queryRef.current = query
+
+  const fetchData = useCallback(async (q: ReportQueryState) => {
+    setLoading(true)
+    setError(null)
+    try {
+      const res = await dedup(`report:${report.id}:${JSON.stringify(q)}`, () =>
+        provider.fetch(report, q),
+      )
+      setResult(res)
+      setGenerated(true)
+    } catch (err: any) {
+      setError(err?.message ?? 'Failed to load report')
+      setResult({ data: [], total: 0 })
+    } finally {
+      setLoading(false)
+    }
+  }, [report, provider])
+
+  const generate = useCallback(() => {
+    fetchData(queryRef.current)
+  }, [fetchData])
+
+  const setDateRange = useCallback((dateRange: ReportDateRange) => {
+    setQuery((q) => ({ ...q, dateRange, page: 1 }))
+  }, [])
+
+  const setFilter = useCallback((key: string, value: any) => {
+    setQuery((q) => ({ ...q, filters: { ...q.filters, [key]: value }, page: 1 }))
+  }, [])
+
+  const setSort = useCallback((sortBy: string) => {
+    setQuery((q) => ({
+      ...q,
+      sortBy,
+      sortDir: q.sortBy === sortBy && q.sortDir === 'asc' ? 'desc' : 'asc',
+      page: 1,
+    }))
+  }, [])
+
+  const setPage = useCallback((page: number) => {
+    setQuery((q) => ({ ...q, page }))
+  }, [])
+
+  const setPageSize = useCallback((pageSize: number) => {
+    setQuery((q) => ({ ...q, pageSize, page: 1 }))
+  }, [])
+
+  const setSearch = useCallback((search: string) => {
+    setQuery((q) => ({ ...q, search, page: 1 }))
+  }, [])
+
+  return {
+    data: result.data,
+    total: result.total,
+    loading,
+    generated,
+    error,
+    query,
+    generate,
+    setDateRange,
+    setFilter,
+    setSort,
+    setPage,
+    setPageSize,
+    setSearch,
+  }
+}

package/src/index.ts

@@ -0,0 +1,140 @@
+import React from 'react'
+import type { PluginManifest, PluginScope, VerticalId } from '@fayz-ai/core'
+import { createSafeDataProvider, registerTranslations } from '@fayz-ai/core'
+import { ReportsPage } from './ReportsPage'
+import type { ReportDataProvider } from './data/types'
+import { createSupabaseReportProvider } from './data/supabase'
+import { createMockReportProvider } from './data/mock'
+import { getReportsTenantId } from './lib/tenant'
+import { reportsLocales } from './locales'
+import type {
+  ReportsPluginOptions,
+  ReportsPluginLabels,
+  ResolvedReportsConfig,
+} from './types'
+
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+
+const DEFAULT_LABELS: ReportsPluginLabels = {
+  pageTitle: 'Reports',
+  pageSubtitle: 'Access complete reports for analysis and decision making',
+  allReports: 'All Reports',
+  dateRange: 'Date Range',
+  from: 'From',
+  to: 'To',
+  export: 'Export',
+  exportCsv: 'Export CSV',
+  exportExcel: 'Export Excel',
+  exportPdf: 'Export PDF',
+  noResults: 'No results found.',
+  backToReports: 'Back',
+  reports: 'reports',
+  search: 'Search reports...',
+  today: 'Today',
+  yesterday: 'Yesterday',
+  last7Days: 'Last 7 days',
+  thisMonth: 'This month',
+  lastMonth: 'Last month',
+  thisQuarter: 'This quarter',
+  custom: 'Custom',
+  generate: 'Generate',
+  print: 'Print',
+  filterFrom: 'From',
+  filterTo: 'To',
+  filterResults: 'Results',
+  emptyStateTitle: 'Ready to generate',
+  emptyStateDescription: 'Select a date range and filters, then click Generate to view the report.',
+  unavailableTitle: 'Coming soon',
+  unavailableDescription: 'This report is not available yet. It will be enabled in a future update.',
+}
+
+const DEFAULT_CURRENCY = { code: 'BRL', locale: 'pt-BR', symbol: 'R$' }
+
+// ---------------------------------------------------------------------------
+// Config resolver
+// ---------------------------------------------------------------------------
+
+function resolveConfig(options: ReportsPluginOptions): ResolvedReportsConfig {
+  return {
+    labels: { ...DEFAULT_LABELS, ...options.labels },
+    currency: { ...DEFAULT_CURRENCY, ...options.currency },
+    reports: options.reports,
+    defaultPageSize: options.defaultPageSize ?? 50,
+    showHeader: options.showHeader !== false,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+export function createReportsPlugin(options: ReportsPluginOptions): PluginManifest {
+  const config = resolveConfig(options)
+  registerTranslations(reportsLocales)
+  const provider: ReportDataProvider = options.dataProvider ?? createSafeDataProvider(
+    () => createSupabaseReportProvider({ tenantId: () => getReportsTenantId() }),
+    () => createMockReportProvider(),
+  )
+
+  const PageComponent: React.FC<any> = () =>
+    React.createElement(ReportsPage, { config, provider })
+
+  return {
+    id: 'reports',
+    name: config.labels.pageTitle,
+    icon: 'BarChart3',
+    version: '1.0.0',
+    scope: options.scope ?? 'universal',
+    verticalId: options.verticalId,
+    defaultEnabled: true,
+    dependencies: [],
+    declaredFeatures: [
+      { id: 'reports', label: config.labels.pageTitle, group: config.labels.pageTitle },
+    ],
+    navigation: [
+      {
+        section: options.navSection ?? 'main',
+        position: options.navPosition ?? 9,
+        label: config.labels.pageTitle,
+        route: '/reports',
+        icon: 'BarChart3',
+        permission: { feature: 'reports', action: 'read' as const },
+      },
+    ],
+    routes: [
+      {
+        path: '/reports',
+        component: PageComponent,
+        permission: { feature: 'reports', action: 'read' as const },
+      },
+    ],
+    widgets: [],
+    registries: [],
+    locales: reportsLocales,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Re-exports
+// ---------------------------------------------------------------------------
+
+export type {
+  ReportDef,
+  ReportColumnDef,
+  ReportFilterDef,
+  ReportDateRange,
+  ReportQueryState,
+  ReportBadge,
+  ReportDataSource,
+  ReportFilterOption,
+  ReportsPluginOptions,
+  ReportsPluginLabels,
+  ResolvedReportsConfig,
+} from './types'
+
+export type { ReportDataProvider, ReportResult } from './data/types'
+export { createSupabaseReportProvider } from './data/supabase'
+export type { SupabaseReportProviderConfig } from './data/supabase'
+export { createMockReportProvider } from './data/mock'

package/src/lib/columns.ts

@@ -0,0 +1,130 @@
+import React from 'react'
+import type { ColumnDef } from '@tanstack/react-table'
+import type { ReportColumnDef } from '../types'
+import { PersonLink } from '@fayz-ai/saas'
+import {
+  formatCurrency as formatCurrencyLocale,
+  formatDate as formatDateLocale,
+  formatDateTime as formatDateTimeLocale,
+} from '@fayz-ai/core'
+
+// ---------------------------------------------------------------------------
+// Formatters (mirrors fieldToColumn.tsx logic)
+// ---------------------------------------------------------------------------
+
+function formatCurrency(value: any, currency?: string): string {
+  const num = typeof value === 'number' ? value : parseFloat(value)
+  if (isNaN(num)) return '—'
+  return formatCurrencyLocale(num, currency)
+}
+
+function formatDate(value: any): string {
+  if (!value) return '—'
+  return formatDateLocale(value)
+}
+
+function formatDateTime(value: any): string {
+  if (!value) return '—'
+  return formatDateTimeLocale(value)
+}
+
+function formatNumber(value: any): string {
+  if (value == null) return '—'
+  return typeof value === 'number' ? value.toLocaleString() : String(value)
+}
+
+// ---------------------------------------------------------------------------
+// Plain-text formatter for exports
+// ---------------------------------------------------------------------------
+
+export function formatValuePlain(value: any, col: ReportColumnDef, currency?: string): string {
+  if (value == null || value === '') return ''
+  switch (col.type) {
+    case 'currency':
+      return formatCurrency(value, col.currency ?? currency)
+    case 'date':
+      return formatDate(value)
+    case 'datetime':
+      return formatDateTime(value)
+    case 'number':
+      return formatNumber(value)
+    case 'boolean':
+      return value ? 'Yes' : 'No'
+    default:
+      return String(value)
+  }
+}
+
+// ---------------------------------------------------------------------------
+// ReportColumnDef[] → TanStack ColumnDef[]
+// ---------------------------------------------------------------------------
+
+export function reportColumnsToTanstack(
+  columns: ReportColumnDef[],
+  currency?: string,
+): ColumnDef<Record<string, any>>[] {
+  return columns
+    .filter((c) => c.visible !== false)
+    .map((col): ColumnDef<Record<string, any>> => {
+      const sortable = col.sortable ?? ['text', 'number', 'currency', 'date', 'datetime', 'email'].includes(col.type)
+      const alignRight = col.align === 'right' || (!col.align && (col.type === 'currency' || col.type === 'number'))
+      const alignCenter = col.align === 'center'
+
+      return {
+        accessorKey: col.key,
+        header: col.label,
+        enableSorting: sortable,
+        cell: (ctx) => {
+          const value = ctx.getValue()
+          const row = ctx.row.original
+
+          if (col.renderCell) {
+            return col.renderCell(value, row)
+          }
+
+          if (value == null || value === '') {
+            return React.createElement('span', { className: 'text-muted-foreground' }, '—')
+          }
+
+          let content: React.ReactNode
+          switch (col.type) {
+            case 'person':
+              content = React.createElement(PersonLink, {
+                personId: col.idKey ? row[col.idKey] : null,
+                name: String(value),
+                size: 'sm',
+                className: 'text-xs',
+              })
+              break
+            case 'currency':
+              content = formatCurrency(value, col.currency ?? currency)
+              break
+            case 'date':
+              content = formatDate(value)
+              break
+            case 'datetime':
+              content = formatDateTime(value)
+              break
+            case 'boolean':
+              content = value
+                ? React.createElement('svg', { className: 'h-4 w-4 text-success', viewBox: '0 0 24 24', fill: 'none', stroke: 'currentColor', strokeWidth: '2' },
+                    React.createElement('polyline', { points: '20 6 9 17 4 12' }),
+                  )
+                : React.createElement('span', { className: 'text-muted-foreground' }, '—')
+              break
+            case 'number':
+              content = formatNumber(value)
+              break
+            default:
+              content = String(value)
+          }
+
+          const cls = alignRight ? 'text-right' : alignCenter ? 'text-center' : undefined
+          return cls
+            ? React.createElement('div', { className: cls }, content)
+            : React.createElement(React.Fragment, null, content)
+        },
+        meta: { align: alignRight ? 'right' : alignCenter ? 'center' : 'left' },
+      }
+    })
+}

package/src/lib/tenant.ts

@@ -0,0 +1,3 @@
+let t: string | undefined
+export function setReportsTenantId(id: string | undefined){ t = id }
+export function getReportsTenantId(): string | undefined { return t }

package/src/locales/en.ts

@@ -0,0 +1,28 @@
+export const en: Record<string, string> = {
+  'reports.pageTitle': 'Reports',
+  'reports.pageSubtitle': 'Access complete reports for analysis and decision making',
+  'reports.allReports': 'All Reports',
+  'reports.dateRange': 'Date Range',
+  'reports.from': 'From',
+  'reports.to': 'To',
+  'reports.export': 'Export',
+  'reports.exportCsv': 'Export CSV',
+  'reports.exportExcel': 'Export Excel',
+  'reports.exportPdf': 'Export PDF',
+  'reports.noResults': 'No results found.',
+  'reports.backToReports': 'Back',
+  'reports.reports': 'reports',
+  'reports.search': 'Search reports...',
+  'reports.today': 'Today',
+  'reports.yesterday': 'Yesterday',
+  'reports.last7Days': 'Last 7 days',
+  'reports.thisMonth': 'This month',
+  'reports.lastMonth': 'Last month',
+  'reports.thisQuarter': 'This quarter',
+  'reports.custom': 'Custom',
+  'reports.generate': 'Generate',
+  'reports.emptyStateTitle': 'Ready to generate',
+  'reports.emptyStateDescription': 'Select a date range and filters, then click Generate to view the report.',
+  'reports.unavailableTitle': 'Coming soon',
+  'reports.unavailableDescription': 'This report is not available yet. It will be enabled in a future update.',
+}

package/src/locales/index.ts

@@ -0,0 +1,7 @@
+import { en } from './en'
+import { ptBR } from './pt-BR'
+
+export const reportsLocales: Record<string, Record<string, string>> = {
+  en,
+  'pt-BR': ptBR,
+}

package/src/locales/pt-BR.ts

@@ -0,0 +1,28 @@
+export const ptBR: Record<string, string> = {
+  'reports.pageTitle': 'Relatórios',
+  'reports.pageSubtitle': 'Acesse relatórios completos para análise e tomada de decisão',
+  'reports.allReports': 'Todos os Relatórios',
+  'reports.dateRange': 'Período',
+  'reports.from': 'De',
+  'reports.to': 'Até',
+  'reports.export': 'Exportar',
+  'reports.exportCsv': 'Exportar CSV',
+  'reports.exportExcel': 'Exportar Excel',
+  'reports.exportPdf': 'Exportar PDF',
+  'reports.noResults': 'Nenhum resultado encontrado.',
+  'reports.backToReports': 'Voltar',
+  'reports.reports': 'relatórios',
+  'reports.search': 'Buscar relatórios...',
+  'reports.today': 'Hoje',
+  'reports.yesterday': 'Ontem',
+  'reports.last7Days': 'Últimos 7 dias',
+  'reports.thisMonth': 'Este mês',
+  'reports.lastMonth': 'Mês passado',
+  'reports.thisQuarter': 'Este trimestre',
+  'reports.custom': 'Personalizado',
+  'reports.generate': 'Gerar',
+  'reports.emptyStateTitle': 'Pronto para gerar',
+  'reports.emptyStateDescription': 'Selecione o período e os filtros desejados, depois clique em Gerar para visualizar o relatório.',
+  'reports.unavailableTitle': 'Em breve',
+  'reports.unavailableDescription': 'Este relatório ainda não está disponível. Será habilitado em uma atualização futura.',
+}