@fayz-ai/plugin-reports 0.1.1

package/src/types.ts

@@ -0,0 +1,157 @@
+import type React from 'react'
+import type { FieldType } from '@fayz-ai/core'
+
+// ---------------------------------------------------------------------------
+// Report column
+// ---------------------------------------------------------------------------
+
+export type ReportFieldType = FieldType | 'person'
+
+export interface ReportColumnDef {
+  key: string
+  label: string
+  type: ReportFieldType
+  sortable?: boolean
+  currency?: string
+  /** For type 'person': the row key containing the person UUID */
+  idKey?: string
+  renderCell?: (value: any, row: any) => React.ReactNode
+  /** Include in export but hide in table. Default: true */
+  visible?: boolean
+  /** Text alignment. Currency/number default to 'right' */
+  align?: 'left' | 'center' | 'right'
+  /** Aggregate for optional summary row */
+  aggregate?: 'sum' | 'avg' | 'count' | 'min' | 'max'
+}
+
+// ---------------------------------------------------------------------------
+// Report filter
+// ---------------------------------------------------------------------------
+
+export type ReportFilterOption = { label: string; value: string }
+
+export interface ReportFilterDef {
+  key: string
+  label: string
+  type: 'select' | 'multiselect' | 'text' | 'boolean' | 'number'
+  options?: ReportFilterOption[] | (() => Promise<ReportFilterOption[]>)
+  defaultValue?: any
+  placeholder?: string
+}
+
+// ---------------------------------------------------------------------------
+// Report definition
+// ---------------------------------------------------------------------------
+
+export type ReportBadge = 'popular' | 'essential' | 'new' | (string & {})
+
+export type ReportDataSourceKind = 'view' | 'rpc'
+
+export interface ReportDataSource {
+  kind: ReportDataSourceKind
+  /** View name (e.g. 'rep_appointments_by_period') or RPC function name */
+  name: string
+  /** Column for date range filtering. Default: 'created_at' */
+  dateColumn?: string
+  defaultSort?: string
+  defaultSortDir?: 'asc' | 'desc'
+  /** snake_case DB → camelCase JS column mapping */
+  columnMap?: Record<string, string>
+}
+
+export interface ReportDef {
+  id: string
+  name: string
+  description?: string
+  icon: string
+  category: string
+  badge?: ReportBadge
+  columns: ReportColumnDef[]
+  filters?: ReportFilterDef[]
+  dataSource: ReportDataSource
+  permission?: { feature: string; action: 'read' }
+  /** Show aggregate summary row */
+  showSummary?: boolean
+  /** Whether the backing view/RPC exists. Default: true */
+  available?: boolean
+}
+
+// ---------------------------------------------------------------------------
+// Query state
+// ---------------------------------------------------------------------------
+
+export interface ReportDateRange {
+  from: string // YYYY-MM-DD
+  to: string   // YYYY-MM-DD
+}
+
+export interface ReportQueryState {
+  dateRange: ReportDateRange
+  filters: Record<string, any>
+  sortBy?: string
+  sortDir?: 'asc' | 'desc'
+  page: number
+  pageSize: number
+  search?: string
+}
+
+// ---------------------------------------------------------------------------
+// Plugin options
+// ---------------------------------------------------------------------------
+
+export interface ReportsPluginLabels {
+  pageTitle: string
+  pageSubtitle: string
+  allReports: string
+  dateRange: string
+  from: string
+  to: string
+  export: string
+  exportCsv: string
+  exportExcel: string
+  exportPdf: string
+  noResults: string
+  backToReports: string
+  reports: string
+  search: string
+  today: string
+  yesterday: string
+  last7Days: string
+  thisMonth: string
+  lastMonth: string
+  thisQuarter: string
+  custom: string
+  generate: string
+  print: string
+  filterFrom: string
+  filterTo: string
+  filterResults: string
+  emptyStateTitle: string
+  emptyStateDescription: string
+  unavailableTitle: string
+  unavailableDescription: string
+}
+
+export interface ReportsPluginOptions {
+  reports: ReportDef[]
+  labels?: Partial<ReportsPluginLabels>
+  currency?: { code?: string; locale?: string; symbol?: string }
+  dataProvider?: import('./data/types').ReportDataProvider
+  navPosition?: number
+  navSection?: 'main' | 'secondary'
+  scope?: import('@fayz-ai/core').PluginScope
+  verticalId?: import('@fayz-ai/core').VerticalId
+  /** Default page size. Default: 50 */
+  defaultPageSize?: number
+  /** Render the in-content title/subtitle. Set false when the app shell owns the
+   *  page title (sidebar/GHL-style layouts). Default: true. */
+  showHeader?: boolean
+}
+
+export interface ResolvedReportsConfig {
+  labels: ReportsPluginLabels
+  currency: { code: string; locale: string; symbol: string }
+  reports: ReportDef[]
+  defaultPageSize: number
+  showHeader: boolean
+}

package/src/views/ReportHub.tsx

@@ -0,0 +1,97 @@
+import React, { useMemo, useState } from 'react'
+import { Search } from 'lucide-react'
+import { Input } from '@fayz-ai/ui'
+import { useTranslation } from '@fayz-ai/core'
+import { ReportCard } from '../components/ReportCard'
+import { useReportsContext } from '../ReportsContext'
+import type { ReportDef } from '../types'
+
+interface ReportHubProps {
+  onSelect: (report: ReportDef) => void
+}
+
+interface CategoryGroup {
+  name: string
+  reports: ReportDef[]
+}
+
+export function ReportHub({ onSelect }: ReportHubProps) {
+  const t = useTranslation()
+  const { config } = useReportsContext()
+  const [search, setSearch] = useState('')
+
+  const categories = useMemo(() => {
+    const filtered = search
+      ? config.reports.filter(
+          (r) =>
+            r.name.toLowerCase().includes(search.toLowerCase()) ||
+            r.description?.toLowerCase().includes(search.toLowerCase()),
+        )
+      : config.reports
+
+    const map = new Map<string, ReportDef[]>()
+    for (const report of filtered) {
+      const list = map.get(report.category) ?? []
+      list.push(report)
+      map.set(report.category, list)
+    }
+
+    const groups: CategoryGroup[] = []
+    for (const [name, reports] of map) {
+      groups.push({ name, reports })
+    }
+    return groups
+  }, [config.reports, search])
+
+  const totalReports = config.reports.length
+
+  return (
+    <div className="space-y-6">
+      {/* Header (omitted when the app shell owns the page title) */}
+      {config.showHeader && (
+        <div>
+          <h1 className="text-2xl font-bold">{t('reports.pageTitle')}</h1>
+          <p className="text-muted-foreground mt-1">{t('reports.pageSubtitle')}</p>
+        </div>
+      )}
+
+      {/* Search */}
+      {totalReports > 6 && (
+        <div className="relative max-w-md">
+          <Search className="absolute left-3 top-1/2 -translate-y-1/2 h-4 w-4 text-muted-foreground" />
+          <Input
+            value={search}
+            onChange={(e) => setSearch(e.target.value)}
+            placeholder={t('reports.search')}
+            className="pl-9"
+          />
+        </div>
+      )}
+
+      {/* Categories */}
+      <div className="space-y-8">
+        {categories.map((category) => (
+            <div key={category.name} className="rounded-xl border bg-card shadow-sm p-5">
+              <div className="flex items-center justify-between mb-4">
+                <h2 className="font-semibold">{category.name}</h2>
+                <span className="text-sm text-muted-foreground">
+                  {category.reports.length} {t('reports.reports')}
+                </span>
+              </div>
+              <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-3">
+                {category.reports.map((report) => (
+                  <ReportCard key={report.id} report={report} onClick={onSelect} />
+                ))}
+              </div>
+            </div>
+        ))}
+      </div>
+
+      {categories.length === 0 && search && (
+        <div className="text-center py-12 text-muted-foreground">
+          {t('reports.noResults')}
+        </div>
+      )}
+    </div>
+  )
+}

package/src/views/ReportViewer.tsx

@@ -0,0 +1,183 @@
+import React, { useMemo } from 'react'
+import { ArrowLeft, Play, SlidersHorizontal, Construction, Loader2, Printer } from 'lucide-react'
+import { Button } from '@fayz-ai/ui'
+import { DataTable } from '@fayz-ai/ui'
+import { useTranslation } from '@fayz-ai/core'
+import { useReportsContext } from '../ReportsContext'
+import { useReportData } from '../hooks/useReportData'
+import { reportColumnsToTanstack } from '../lib/columns'
+import { ReportFilterBar } from '../components/ReportFilterBar'
+import { ReportPagination } from '../components/ReportPagination'
+import { ReportSummaryRow } from '../components/ReportSummaryRow'
+import { ExportDropdown } from '../components/ExportDropdown'
+import type { ReportDef } from '../types'
+
+interface ReportViewerProps {
+  report: ReportDef
+  onBack: () => void
+}
+
+export function ReportViewer({ report, onBack }: ReportViewerProps) {
+  const t = useTranslation()
+  const { config, provider } = useReportsContext()
+  const {
+    data,
+    total,
+    loading,
+    generated,
+    error,
+    query,
+    generate,
+    setDateRange,
+    setFilter,
+    setPage,
+    setPageSize,
+  } = useReportData(report, provider, config.defaultPageSize)
+
+  const isAvailable = report.available !== false
+
+  const tanstackColumns = useMemo(
+    () => reportColumnsToTanstack(report.columns, config.currency.code),
+    [report.columns, config.currency.code],
+  )
+
+  return (
+    <div className="space-y-4">
+      {/* Breadcrumb — hidden in print */}
+      <div className="flex items-center gap-1.5 text-sm no-print">
+        <button
+          onClick={onBack}
+          className="flex items-center gap-1 text-muted-foreground hover:text-foreground transition-colors"
+        >
+          <ArrowLeft className="h-3.5 w-3.5" />
+          {t('reports.pageTitle')}
+        </button>
+        <span className="text-muted-foreground">/</span>
+        <span className="font-medium">{report.name}</span>
+      </div>
+
+      <div>
+        <h2 className="text-lg font-bold">{report.name}</h2>
+        {report.description && (
+          <p className="text-xs text-muted-foreground mt-0.5">{report.description}</p>
+        )}
+      </div>
+
+      {/* Filters + Generate — hidden in print */}
+      <div className="flex flex-wrap items-end gap-3 no-print">
+        <ReportFilterBar
+          dateRange={query.dateRange}
+          onDateRangeChange={setDateRange}
+          filters={report.filters ?? []}
+          filterValues={query.filters}
+          onFilterChange={setFilter}
+        />
+        <Button onClick={generate} disabled={loading || !isAvailable} size="sm" className="h-9">
+          {loading
+            ? <Loader2 className="h-3.5 w-3.5 mr-1.5 animate-spin" />
+            : <Play className="h-3.5 w-3.5 mr-1.5" />
+          }
+          {t('reports.generate')}
+        </Button>
+        {generated && (
+          <>
+            <ExportDropdown
+              columns={report.columns}
+              data={data}
+              filename={report.id}
+              currency={config.currency.code}
+              title={report.name}
+            />
+            <Button variant="outline" size="sm" className="h-9" onClick={() => window.print()}>
+              <Printer className="h-3.5 w-3.5 mr-1.5" />
+              {t('reports.print')}
+            </Button>
+          </>
+        )}
+      </div>
+
+      {/* Print-only: compact filter summary as document header */}
+      {generated && (
+        <div className="print-only hidden text-[10px] border-b pb-2 mb-2">
+          <div className="flex flex-wrap gap-x-4 gap-y-0.5">
+            {query.dateRange.from && (
+              <span><strong>{t('reports.filterFrom')}:</strong> {new Date(query.dateRange.from + 'T12:00').toLocaleDateString()}</span>
+            )}
+            {query.dateRange.to && (
+              <span><strong>{t('reports.filterTo')}:</strong> {new Date(query.dateRange.to + 'T12:00').toLocaleDateString()}</span>
+            )}
+            {Object.entries(query.filters).map(([key, value]) =>
+              value ? <span key={key}><strong>{key}:</strong> {String(value)}</span> : null
+            )}
+            <span><strong>{t('reports.filterResults')}:</strong> {total}</span>
+          </div>
+        </div>
+      )}
+
+      {/* Error */}
+      {error && (
+        <div className="rounded-lg border border-destructive/50 bg-destructive/10 p-3 text-sm text-destructive">
+          {error}
+        </div>
+      )}
+
+      {/* Empty state — before generate */}
+      {!generated && !loading && (
+        <div className="flex flex-col items-center justify-center rounded-xl border border-dashed py-16 text-center">
+          {isAvailable ? (
+            <>
+              <div className="flex h-12 w-12 items-center justify-center rounded-full bg-muted mb-4">
+                <SlidersHorizontal className="h-5 w-5 text-muted-foreground" />
+              </div>
+              <p className="font-medium">{t('reports.emptyStateTitle')}</p>
+              <p className="text-sm text-muted-foreground mt-1 max-w-sm">{t('reports.emptyStateDescription')}</p>
+            </>
+          ) : (
+            <>
+              <div className="flex h-12 w-12 items-center justify-center rounded-full bg-muted mb-4">
+                <Construction className="h-5 w-5 text-muted-foreground" />
+              </div>
+              <p className="font-medium">{t('reports.unavailableTitle')}</p>
+              <p className="text-sm text-muted-foreground mt-1 max-w-sm">{t('reports.unavailableDescription')}</p>
+            </>
+          )}
+        </div>
+      )}
+
+      {/* Results — only shown after generate */}
+      {(generated || loading) && (
+        <>
+          <DataTable
+            columns={tanstackColumns}
+            data={data}
+            loading={loading}
+            skeletonRows={5}
+            emptyMessage={t('reports.noResults')}
+            variant="card"
+            compact
+          />
+
+          {report.showSummary && !loading && (
+            <ReportSummaryRow
+              columns={report.columns}
+              data={data}
+              currency={config.currency.code}
+            />
+          )}
+
+          {!loading && (
+            <div className="no-print">
+              <ReportPagination
+                page={query.page}
+                pageSize={query.pageSize}
+                total={total}
+                onPageChange={setPage}
+                onPageSizeChange={setPageSize}
+              />
+            </div>
+          )}
+        </>
+      )}
+    </div>
+  )
+}