workforce-pay-bill-p/DASHBOARD_CONFIG.md

Dashboard JSON Configuration

The dashboard layout, data, and translations are now loaded from JSON files, making it easy to customize and configure the dashboard without modifying React components.

Files

• /src/data/dashboard.json - Dashboard layout and configuration
• /src/data/translations/en.json - English translations (including dashboard keys)
• /src/data/translations/fr.json - French translations
• /src/data/translations/es.json - Spanish translations

Dashboard Configuration Structure

Layout Sections

The dashboard is divided into three main sections:

1. Metrics Grid

Displays key performance indicators (KPIs) in a grid layout.

{
  "id": "metrics",
  "type": "metrics-grid",
  "columns": {
    "mobile": 1,
    "tablet": 2,
    "desktop": 4
  },
  "metrics": [
    {
      "id": "pendingApprovals",
      "titleKey": "dashboard.pendingApprovals",
      "dataSource": "metrics.pendingApprovals",
      "icon": "ClockCounterClockwise",
      "iconColor": "text-warning",
      "variant": "warning",
      "trend": {
        "enabled": true,
        "direction": "up",
        "value": 12,
        "textKey": "dashboard.vsLastWeek",
        "textParams": { "value": "12" }
      }
    }
  ]
}

2. Financial Summary Cards

Shows financial metrics like revenue, payroll, and margins.

{
  "id": "financial-summary",
  "type": "cards-grid",
  "columns": {
    "mobile": 1,
    "tablet": 1,
    "desktop": 3
  },
  "cards": [
    {
      "id": "monthlyRevenue",
      "titleKey": "dashboard.monthlyRevenue",
      "descriptionKey": "dashboard.monthlyRevenueDescription",
      "dataSource": "metrics.monthlyRevenue",
      "format": "currency",
      "currencySymbol": "£",
      "trend": {
        "enabled": true,
        "direction": "up",
        "value": 12.5,
        "textKey": "dashboard.vsLastMonth",
        "textParams": { "value": "12.5" },
        "color": "text-success"
      }
    }
  ]
}

3. Activity Feed & Quick Actions

Two-column layout showing recent activities and quick action buttons.

{
  "id": "activity-and-actions",
  "type": "two-column-cards",
  "columns": {
    "mobile": 1,
    "tablet": 1,
    "desktop": 2
  },
  "cards": [
    {
      "id": "recentActivity",
      "type": "activity-feed",
      "titleKey": "dashboard.recentActivity",
      "descriptionKey": "dashboard.recentActivityDescription",
      "dataSource": "recentActivities",
      "maxItems": 4
    },
    {
      "id": "quickActions",
      "type": "action-list",
      "titleKey": "dashboard.quickActions",
      "descriptionKey": "dashboard.quickActionsDescription",
      "actions": [
        {
          "id": "createTimesheet",
          "labelKey": "dashboard.createTimesheet",
          "icon": "Clock",
          "action": "navigate",
          "target": "timesheets"
        }
      ]
    }
  ]
}

Recent Activities

Activity feed items are defined separately:

{
  "recentActivities": [
    {
      "id": "activity-1",
      "icon": "CheckCircle",
      "iconColor": "text-success",
      "titleKey": "dashboard.timesheetApproved",
      "description": "John Smith - Week ending 15 Jan 2025",
      "timeKey": "dashboard.minutesAgo",
      "timeParams": { "value": "5" },
      "timestamp": "2025-01-15T14:55:00Z"
    }
  ]
}

Data Sources

The dataSource field references metrics from the application's state:

• metrics.pendingApprovals → Dashboard metrics object
• metrics.monthlyRevenue → Financial data
• metrics.complianceAlerts → Compliance tracking

The hook automatically resolves nested paths like metrics.pendingApprovals by traversing the metrics object.

Available Icons

Icons are mapped from Phosphor Icons library:

• Clock
• Receipt
• CurrencyDollar
• ClockCounterClockwise
• CheckCircle
• Warning
• Notepad
• Download
• ArrowUp
• ArrowDown

Variants

Metric cards support visual variants:

• default - Standard border
• success - Green accent border
• warning - Yellow/orange accent border
• error - Red accent border

Formats

Financial cards support multiple formats:

• currency - Displays with currency symbol (e.g., £1,234)
• percentage - Displays with % symbol (e.g., 15.5%)
• number - Plain number with locale formatting

Translations

All text is loaded from translation files using translation keys:

{
  "dashboard": {
    "title": "Dashboard",
    "subtitle": "Real-time overview of your workforce operations",
    "pendingApprovals": "Pending Approvals",
    "monthlyRevenue": "Monthly Revenue",
    "vsLastWeek": "{{value}}% vs last week",
    "minutesAgo": "{{value}} minutes ago"
  }
}

Translation keys support parameter interpolation using {{paramName}} syntax.

Custom Hook

The useDashboardConfig hook provides easy access to the configuration:

import { useDashboardConfig } from '@/hooks/use-dashboard-config'

const {
  config,              // Full configuration object
  loading,             // Loading state
  error,               // Error state
  getMetricsSection,   // Get metrics section config
  getFinancialSection, // Get financial cards config
  getRecentActivities, // Get activity feed (with optional limit)
  getQuickActions      // Get quick action buttons
} = useDashboardConfig()

Adding New Metrics

To add a new metric:

1. Add the metric to /src/data/dashboard.json in the appropriate section
2. Add translation keys to all language files (en.json, fr.json, es.json)
3. Ensure the data source path matches your metrics object structure

Example:

{
  "id": "activeWorkers",
  "titleKey": "dashboard.activeWorkers",
  "dataSource": "metrics.activeWorkers",
  "icon": "Users",
  "iconColor": "text-info",
  "variant": "default"
}

Benefits

✅ No code changes needed - Update dashboard by editing JSON ✅ Fully internationalized - All text comes from translation files ✅ Flexible layout - Responsive column configurations ✅ Type-safe - TypeScript interfaces ensure correct structure ✅ Easy maintenance - Centralized configuration ✅ Reusable - Same pattern can be applied to other views