@fayz-ai/plugin-dashboard 0.1.1

package/src/index.ts

@@ -0,0 +1,200 @@
+import React from 'react'
+import type { PluginManifest, PluginScope, VerticalId, DashboardWidgetDef, DashboardLayoutConfig } from '@fayz-ai/core'
+import { DashboardCanvas, type DashboardCanvasProps } from '@fayz-ai/ui'
+import { DashboardPage } from './DashboardPage'
+import { metricsToWidgets, sectionsToWidgets, onboardingToWidget } from './builders'
+import { dashboardLocales } from './locales'
+import type { DashboardMetric, DashboardSection, OnboardingStep } from './types'
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export interface DashboardPluginLabels {
+  pageTitle: string
+  pageSubtitle: string
+  kpiTitle: string
+  onboardingTitle: string
+  onboardingSubtitle: string
+  settingsTitle: string
+}
+
+export interface DashboardPluginOptions {
+  /** KPI metrics to show on the dashboard */
+  metrics?: DashboardMetric[]
+  /** Custom sections injected by the consumer app */
+  sections?: DashboardSection[]
+  /** Onboarding steps for the getting-started checklist */
+  onboardingSteps?: OnboardingStep[]
+  /** Label overrides */
+  labels?: Partial<DashboardPluginLabels>
+  /** Currency config for metrics that use 'currency' format */
+  currency?: { code?: string; locale?: string; symbol?: string }
+  /** Plugin scope */
+  scope?: PluginScope
+  /** Vertical ID */
+  verticalId?: VerticalId
+  /** Whether to show onboarding module. Default: true if onboardingSteps provided */
+  showOnboarding?: boolean
+  /** Nav position (default: 0 — first item) */
+  navPosition?: number
+  /** Nav section (default: 'main') */
+  navSection?: 'main' | 'secondary'
+  /** Navigation icon override (default: 'LayoutDashboard') */
+  navIcon?: string
+  /** Skip adding a navigation entry (use when the consumer app provides its own page entry for '/') */
+  skipNavigation?: boolean
+  /** Render the in-content title/subtitle. Set false when the app shell owns the
+   *  page title (sidebar/GHL-style layouts). Default: true. */
+  showHeader?: boolean
+  /** App-level curation of the home surface — which widgets show, order, span.
+   *  Applied on top of every plugin's registered defaults. */
+  layout?: DashboardLayoutConfig
+  /** Custom widgets the consumer app contributes directly to the home surface. */
+  customWidgets?: DashboardWidgetDef[]
+  /** Show the shared, sticky time-range control on the home. Pass `true` for
+   *  defaults (7d/30d/90d) or an options object. Widgets read it via
+   *  useDashboardRange(); provide `onChange` to drive app-level refetching. */
+  range?: DashboardCanvasProps['range']
+}
+
+// ---------------------------------------------------------------------------
+// Defaults
+// ---------------------------------------------------------------------------
+
+const DEFAULT_LABELS: DashboardPluginLabels = {
+  pageTitle: 'Dashboard',
+  pageSubtitle: 'Business overview',
+  kpiTitle: 'Key Metrics',
+  onboardingTitle: 'Getting Started',
+  onboardingSubtitle: 'Complete these steps to set up your business',
+  settingsTitle: 'Dashboard',
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+export function createDashboardPlugin(options?: DashboardPluginOptions): PluginManifest {
+  const labels: DashboardPluginLabels = { ...DEFAULT_LABELS, ...options?.labels }
+  const onboardingSteps = options?.onboardingSteps ?? []
+  const showOnboarding = options?.showOnboarding ?? onboardingSteps.length > 0
+
+  // Everything the dashboard plugin owns flows through the widget registry:
+  // legacy metrics/sections, the onboarding checklist, and app custom widgets.
+  const dashboardWidgets: DashboardWidgetDef[] = [
+    ...metricsToWidgets(options?.metrics ?? [], options?.currency),
+    ...sectionsToWidgets(options?.sections ?? []),
+    ...(showOnboarding && onboardingSteps.length > 0
+      ? [onboardingToWidget(onboardingSteps, { title: labels.onboardingTitle, subtitle: labels.onboardingSubtitle })]
+      : []),
+    ...(options?.customWidgets ?? []),
+  ]
+
+  const PageComponent: React.ComponentType<unknown> = () =>
+    React.createElement(DashboardCanvas, {
+      surface: 'home',
+      title: labels.pageTitle,
+      subtitle: labels.pageSubtitle,
+      showHeader: options?.showHeader,
+      appLayout: options?.layout,
+      range: options?.range,
+    })
+
+  return {
+    id: 'dashboard',
+    name: labels.pageTitle,
+    icon: 'LayoutDashboard',
+    version: '1.0.0',
+    scope: options?.scope ?? 'universal',
+    verticalId: options?.verticalId,
+    defaultEnabled: true,
+    dependencies: [],
+    declaredFeatures: [
+      { id: 'dashboard', label: labels.pageTitle, group: 'Core' },
+    ],
+
+    navigation: options?.skipNavigation ? [] : [
+      {
+        section: options?.navSection ?? 'main',
+        position: options?.navPosition ?? 0,
+        label: labels.pageTitle,
+        route: '/',
+        icon: options?.navIcon ?? 'LayoutDashboard',
+      },
+    ],
+
+    routes: [
+      {
+        path: '/',
+        component: PageComponent,
+      },
+    ],
+
+    widgets: [],
+    dashboardWidgets,
+
+    aiTools: [
+      {
+        id: 'dashboard.kpi-summary',
+        name: 'getKpiSummary',
+        description: 'Returns a summary of all KPI metrics for the current dashboard, including trends and comparisons.',
+        icon: 'BarChart3',
+        mode: 'read' as const,
+        category: 'Dashboard',
+        parameters: {
+          type: 'object' as const,
+          properties: {
+            category: {
+              type: 'string' as const,
+              description: 'Filter by metric category',
+              enum: ['revenue', 'operations', 'clients', 'custom', 'all'],
+            },
+          },
+        },
+        suggestions: [
+          { label: 'How is my business doing today?' },
+          { label: "What's my revenue today?" },
+          { label: 'Give me a summary of today' },
+        ],
+      },
+    ],
+
+    locales: dashboardLocales,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Re-exports
+// ---------------------------------------------------------------------------
+
+export { DashboardPage } from './DashboardPage'
+export {
+  DashboardCanvas,
+  DashboardNavigateProvider,
+  useDashboardNavigate,
+  resolveDashboardLayout,
+  useDashboardPreferences,
+  type DashboardCanvasProps,
+  type LaidOutWidget,
+  type DashboardPreferencesState,
+} from '@fayz-ai/ui'
+export {
+  metricsToWidgets,
+  sectionsToWidgets,
+  onboardingToWidget,
+} from './builders'
+
+export type {
+  DashboardMetric,
+  MetricValue,
+  MetricCategory,
+  MetricFormat,
+  ResolvedMetric,
+  DashboardSection,
+  DashboardSectionProps,
+  DashboardZone,
+  OnboardingStep,
+  OnboardingProgress,
+  DashboardPreferences,
+} from './types'

package/src/locales/en.ts

@@ -0,0 +1,23 @@
+export const en: Record<string, string> = {
+  'dashboard.title': 'Dashboard',
+  'dashboard.subtitle': 'Business overview',
+  'dashboard.kpi.title': 'Key Metrics',
+  'dashboard.kpi.noData': 'No metrics configured',
+  'dashboard.kpi.error': 'Failed to load',
+  'dashboard.kpi.refresh': 'Refresh',
+  'dashboard.onboarding.title': 'Getting Started',
+  'dashboard.onboarding.subtitle': 'Complete these steps to set up your business',
+  'dashboard.onboarding.completed': 'Completed',
+  'dashboard.onboarding.allDone': "All done! You're all set.",
+  'dashboard.onboarding.dismiss': 'Dismiss',
+  'dashboard.onboarding.step': 'Step',
+  'dashboard.onboarding.of': 'of',
+  'dashboard.settings.title': 'Dashboard',
+  'dashboard.settings.subtitle': 'Choose which metrics appear on your dashboard',
+  'dashboard.settings.metricsVisibility': 'Visible Metrics',
+  'dashboard.settings.metricOrder': 'Metric Order',
+  'dashboard.settings.resetDefaults': 'Reset to Defaults',
+  'dashboard.settings.saved': 'Dashboard preferences saved',
+  'dashboard.empty.title': 'Welcome!',
+  'dashboard.empty.subtitle': 'Your dashboard will show key metrics and information here.',
+}

package/src/locales/index.ts

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

package/src/locales/pt-BR.ts

@@ -0,0 +1,23 @@
+export const ptBR: Record<string, string> = {
+  'dashboard.title': 'Painel',
+  'dashboard.subtitle': 'Visao geral do seu negocio',
+  'dashboard.kpi.title': 'Metricas',
+  'dashboard.kpi.noData': 'Nenhuma metrica configurada',
+  'dashboard.kpi.error': 'Falha ao carregar',
+  'dashboard.kpi.refresh': 'Atualizar',
+  'dashboard.onboarding.title': 'Primeiros Passos',
+  'dashboard.onboarding.subtitle': 'Complete estes passos para configurar seu negocio',
+  'dashboard.onboarding.completed': 'Concluido',
+  'dashboard.onboarding.allDone': 'Tudo pronto! Voce esta configurado.',
+  'dashboard.onboarding.dismiss': 'Dispensar',
+  'dashboard.onboarding.step': 'Passo',
+  'dashboard.onboarding.of': 'de',
+  'dashboard.settings.title': 'Painel',
+  'dashboard.settings.subtitle': 'Escolha quais metricas aparecem no seu painel',
+  'dashboard.settings.metricsVisibility': 'Metricas Visiveis',
+  'dashboard.settings.metricOrder': 'Ordem das Metricas',
+  'dashboard.settings.resetDefaults': 'Restaurar Padrao',
+  'dashboard.settings.saved': 'Preferencias do painel salvas',
+  'dashboard.empty.title': 'Bem-vindo!',
+  'dashboard.empty.subtitle': 'Seu painel mostrara metricas e informacoes importantes aqui.',
+}

package/src/types.ts

@@ -0,0 +1,127 @@
+import type React from 'react'
+import type { VerticalId } from '@fayz-ai/core'
+
+// ---------------------------------------------------------------------------
+// KPI Metric system
+// ---------------------------------------------------------------------------
+
+export type MetricCategory = 'revenue' | 'operations' | 'clients' | 'custom'
+export type MetricFormat = 'number' | 'currency' | 'percent' | 'duration'
+
+export interface MetricValue {
+  /** Primary numeric value */
+  value: number
+  /** Comparison value for trend (e.g., yesterday, last week) */
+  previousValue?: number
+  /** Unit suffix (e.g., 'min', 'BRL') */
+  unit?: string
+  /** Trend direction for visual indicator */
+  trend?: 'up' | 'down' | 'neutral'
+  /** Optional series (oldest → newest) rendered as an inline sparkline. */
+  spark?: number[]
+}
+
+export interface DashboardMetric {
+  /** Unique metric ID, e.g. 'revenue-today' */
+  id: string
+  /** i18n key or plain label */
+  label: string
+  /** Tooltip description */
+  description?: string
+  /** Lucide icon name */
+  icon: string
+  /** Grouping category */
+  category: MetricCategory
+  /** Async function that computes the current value */
+  compute: () => Promise<MetricValue>
+  /** Whether visible by default (before user customization) */
+  defaultVisible: boolean
+  /** Default display order (lower = first) */
+  defaultOrder: number
+  /** How to format the value */
+  format?: MetricFormat
+  /** Render the card as a radial gauge toward this goal value. */
+  goal?: number
+  /** Accent color for the gauge/sparkline. Defaults to a trend-aware color. */
+  accent?: string
+}
+
+export interface ResolvedMetric extends DashboardMetric {
+  /** Current computed value (null while loading) */
+  currentValue: MetricValue | null
+  /** Whether this metric is currently loading */
+  loading: boolean
+  /** Error message if compute() failed */
+  error?: string
+}
+
+// ---------------------------------------------------------------------------
+// Section system
+// ---------------------------------------------------------------------------
+
+export type DashboardZone = 'main' | 'sidebar' | 'bottom-right'
+
+export interface DashboardSectionProps {
+  tenantId?: string
+  onNavigate?: (path: string) => void
+}
+
+export interface DashboardSection {
+  /** Unique section ID */
+  id: string
+  /** i18n key or plain title */
+  title: string
+  /** Lucide icon name */
+  icon?: string
+  /** Zone placement on the dashboard */
+  zone: DashboardZone
+  /** Column span on the 4-col grid (1–4). Default: 2 (half width). */
+  span?: 1 | 2 | 3 | 4
+  /** Sort order within zone (lower = first) */
+  order: number
+  /** React component to render */
+  component: React.ComponentType<DashboardSectionProps>
+  /** Only show for specific verticals */
+  verticalId?: VerticalId
+}
+
+// ---------------------------------------------------------------------------
+// Onboarding system
+// ---------------------------------------------------------------------------
+
+export interface OnboardingStep {
+  /** Unique step ID, e.g. 'add-first-client' */
+  id: string
+  /** i18n key or plain title */
+  title: string
+  /** i18n key or plain description */
+  description: string
+  /** Lucide icon name */
+  icon: string
+  /** Async check: returns true if this step is already completed */
+  check: () => Promise<boolean>
+  /** Route path to navigate to, or a callback */
+  action: string | (() => void)
+  /** Sort order (lower = first) */
+  order: number
+}
+
+export interface OnboardingProgress {
+  stepId: string
+  completedAt: string | null
+}
+
+// ---------------------------------------------------------------------------
+// Preferences (DB-backed per-tenant)
+// ---------------------------------------------------------------------------
+
+export interface DashboardPreferences {
+  id: string
+  tenantId: string
+  /** Ordered list of metric IDs the user wants visible */
+  visibleMetrics: string[]
+  /** Full metric ordering (visible + hidden) */
+  metricOrder: string[]
+  createdAt: string
+  updatedAt: string
+}