Page Designer - Dashboards Documentation

Version: 2.0
Last Updated: March 13, 2026
Scope: Dashboard design, widgets, data visualization, real-time updates

Overview

The Dashboard Designer enables creation of data-driven analytics and business intelligence dashboards with:

14+ widget types for comprehensive data visualization
Real-time data updates with WebSocket support
Responsive grid layout for multi-device support
Chart configuration (line, bar, pie, area, mixed)
KPI tracking with thresholds and alerts
Data export (CSV, PDF, Excel)
Drill-down capabilities for detailed analysis
Role-based widget access for different user types

Page Mode: "dashboard"

All dashboard configurations must set pageMode: "dashboard" in the root configuration.

interface DashboardPage {
  id: string;
  name: string;
  pageMode: 'dashboard';
  components: DashboardWidget[];
  settings?: DashboardSettings;
  refreshInterval?: number; // milliseconds
}

interface DashboardSettings {
  layout?: 'grid' | 'responsive';
  columnCount?: number; // 12 by default (Bootstrap grid)
  autoRefresh?: boolean;
  autoRefreshInterval?: number;
  exportFormat?: 'pdf' | 'excel' | 'csv';
  themeColor?: 'light' | 'dark';
  timezone?: string;
}

Dashboard Widgets (14 Types)

KPI & Metric Widgets

1. KPI (Key Performance Indicator)

Type: 'kpi'
Purpose: Display single key metric with trend
When to Use: Revenue, user growth, conversion rate, key metrics
Parameters:
  - label: string | "Total Revenue"
  - value: number | dynamic from dataSource
  - icon: string | "dollar" (Material icon name)
  - color: string | "#2196F3"
  - trend?: {
      value: number | percentage change
      direction: 'up' | 'down'
      showPercentage: boolean
    }
  - format: 'currency' | 'percentage' | 'number' | 'decimal'
  - currencySymbol?: string | "$"
  - decimalPlaces?: number | 2
  - comparison?: {
      label: string
      value: number
      period: string
    }
  - threshold?: {
      warning: number
      critical: number
    }
  - dataSource: DataSource | required

Example: Revenue KPI
  {
    id: 'revenueKpi',
    type: 'kpi',
    label: 'Total Revenue',
    icon: 'attach_money',
    color: '#4CAF50',
    format: 'currency',
    currencySymbol: '$',
    decimalPlaces: 2,
    trend: {
      value: 12.5,
      direction: 'up',
      showPercentage: true
    },
    comparison: {
      label: 'vs Last Month',
      value: 125000,
      period: 'M'
    },
    threshold: {
      warning: 50000,
      critical: 10000
    },
    dataSource: {
      type: 'api',
      url: '/api/metrics/revenue',
      method: 'GET'
    }
  }

Example: Conversion Rate KPI
  {
    id: 'conversionKpi',
    type: 'kpi',
    label: 'Conversion Rate',
    icon: 'trending_up',
    color: '#FF9800',
    format: 'percentage',
    decimalPlaces: 1,
    trend: {
      value: 2.3,
      direction: 'up',
      showPercentage: true
    },
    dataSource: {
      type: 'api',
      url: '/api/metrics/conversion'
    }
  }

2. Gauge

Type: 'gauge'
Purpose: Circular gauge showing value against scale
When to Use: Performance score, health status, usage percentage
Parameters:
  - label: string | "System Health"
  - min: number | 0
  - max: number | 100
  - value: number | from dataSource
  - unit: string | "%"
  - thresholds: { from, to, color }[] | danger/warning/success ranges
  - hideLabel: boolean | false
  - dataSource: DataSource | required

Example: System Health Gauge
  {
    id: 'healthGauge',
    type: 'gauge',
    label: 'System Health',
    min: 0,
    max: 100,
    unit: '%',
    thresholds: [
      { from: 0, to: 33, color: '#F44336' },      // Red
      { from: 33, to: 66, color: '#FFC107' },     // Yellow
      { from: 66, to: 100, color: '#4CAF50' }     // Green
    ],
    dataSource: {
      type: 'api',
      url: '/api/metrics/system-health'
    }
  }

3. Metric

Type: 'metric'
Purpose: Display single metric with optional comparison
When to Use: Simple metric display, counter cards
Parameters:
  - label: string | "Active Users"
  - value: string | number | from dataSource
  - color: string | "#2196F3"
  - size: 'small' | 'medium' | 'large'
  - icon: string | Material icon name
  - showBackground: boolean | true
  - dataSource: DataSource | optional

Example:
  {
    id: 'activeUsersMetric',
    type: 'metric',
    label: 'Active Users',
    color: '#2196F3',
    size: 'medium',
    icon: 'people',
    showBackground: true,
    dataSource: {
      type: 'api',
      url: '/api/metrics/active-users'
    }
  }

Chart Widgets

4. Chart (Multi-Type)

Type: 'chart'
Purpose: Flexible chart visualization (line, bar, pie, area)
When to Use: Trends, comparisons, distribution analysis
Parameters:
  - label: string | "Sales Trend"
  - chartType: 'line' | 'bar' | 'pie' | 'doughnut' | 'area' | 'scatter' | 'bubble'
  - dataSource: DataSource | required
  - xAxisKey: string | "date" (x-axis data field)
  - yAxisKey: string | "sales" (y-axis data field)
  - series?: SeriesConfig[] | for multi-series charts
  - xAxisLabel: string | "Time"
  - yAxisLabel: string | "Amount"
  - legend: 'top' | 'bottom' | 'left' | 'right'
  - showGrid: boolean | true
  - showDataLabels: boolean | false
  - showTooltip: boolean | true
  - height: string | "400px"
  - responsive: boolean | true
  - colors: string[] | ["#2196F3", "#4CAF50", "#FF9800"]

Example: Line Chart (Sales Trend)
  {
    id: 'salesTrendChart',
    type: 'chart',
    label: 'Sales Trend',
    chartType: 'line',
    xAxisKey: 'date',
    yAxisKey: 'amount',
    xAxisLabel: 'Date',
    yAxisLabel: 'Revenue ($)',
    height: '350px',
    showDataLabels: true,
    legend: 'top',
    dataSource: {
      type: 'api',
      url: '/api/sales/daily-trend',
      method: 'GET'
    }
  }

Example: Bar Chart (Comparison)
  {
    id: 'departmentComparisonChart',
    type: 'chart',
    label: 'Sales by Department',
    chartType: 'bar',
    xAxisKey: 'department',
    yAxisKey: 'sales',
    xAxisLabel: 'Department',
    yAxisLabel: 'Sales',
    colors: ['#2196F3'],
    dataSource: {
      type: 'api',
      url: '/api/sales/by-department'
    }
  }

Example: Pie Chart (Distribution)
  {
    id: 'marketShareChart',
    type: 'chart',
    label: 'Market Share',
    chartType: 'pie',
    dataSource: {
      type: 'static',
      staticData: [
        { label: 'Product A', value: 35 },
        { label: 'Product B', value: 25 },
        { label: 'Product C', value: 20 },
        { label: 'Product D', value: 20 }
      ]
    },
    showDataLabels: true,
    legend: 'right'
  }

Example: Multi-Series Chart
  {
    id: 'revenueComparisonChart',
    type: 'chart',
    label: 'Revenue vs Target',
    chartType: 'area',
    xAxisKey: 'month',
    height: '300px',
    series: [
      {
        label: 'Actual Revenue',
        dataKey: 'actual',
        color: '#4CAF50'
      },
      {
        label: 'Target Revenue',
        dataKey: 'target',
        color: '#FFC107'
      }
    ],
    dataSource: {
      type: 'api',
      url: '/api/revenue/monthly'
    }
  }

Data & List Widgets

Type: 'table-widget' or 'table'
Purpose: Display tabular data with sorting, filtering
When to Use: Data display, transaction list, results
Parameters:
  - label: string | "Recent Orders"
  - columns: ColumnDef[] | required
  - dataSource: DataSource | required
  - sortable: boolean | true
  - filterable: boolean | true
  - pageable: boolean | true
  - pageSize: number | 10
  - rowClickAction?: string | for drill-down
  - exportable: boolean | true
  - height: string | "auto"
  - rowHeight: 'small' | 'medium' | 'large'

Example:
  {
    id: 'recentOrdersTable',
    type: 'table-widget',
    label: 'Recent Orders',
    sortable: true,
    filterable: true,
    pageable: true,
    pageSize: 20,
    exportable: true,
    columns: [
      { key: 'orderId', label: 'Order ID', width: '15%', sortable: true },
      { key: 'customerName', label: 'Customer', width: '25%' },
      { key: 'orderDate', label: 'Order Date', width: '20%', type: 'date' },
      { key: 'totalAmount', label: 'Total', width: '15%', type: 'currency' },
      { key: 'status', label: 'Status', width: '15%', type: 'badge' }
    ],
    dataSource: {
      type: 'api',
      url: '/api/orders',
      method: 'GET'
    }
  }

Type: 'list-widget' or 'list'
Purpose: Display items in list format (not tabular)
When to Use: News feeds, notifications, activities, items
Parameters:
  - label: string | "Recent Activities"
  - dataSource: DataSource | required
  - itemTemplate: string | HTML template for list items
  - showAvatar: boolean | true
  - showDate: boolean | true
  - maxItems: number | 20
  - pageable: boolean | false

Example:
  {
    id: 'recentActivitiesList',
    type: 'list-widget',
    label: 'Recent Activities',
    maxItems: 10,
    pageable: true,
    showAvatar: true,
    showDate: true,
    itemTemplate: '<div class="activity-item"><span>{{ user }}</span>: {{ action }} <span class="date">{{ timestamp }}</span></div>',
    dataSource: {
      type: 'api',
      url: '/api/activities/recent'
    }
  }

Visualization Widgets

Type: 'calendar-widget'
Purpose: Calendar view with events
When to Use: Event scheduling, appointment view, date-based tracking
Parameters:
  - label: string | "Events Calendar"
  - dataSource: DataSource | event data
  - dateField: string | "eventDate"
  - titleField: string | "title"
  - onClick?: function | handle date click
  - viewType: 'month' | 'week' | 'day'
  - showWeekends: boolean | true

Example:
  {
    id: 'eventsCalendar',
    type: 'calendar-widget',
    label: 'Team Events',
    viewType: 'month',
    dateField: 'eventDate',
    titleField: 'eventTitle',
    showWeekends: true,
    dataSource: {
      type: 'api',
      url: '/api/events/calendar'
    }
  }

Type: 'map-widget'
Purpose: Geographic visualization
When to Use: Store locations, regional data, geographic analysis
Parameters:
  - label: string | "Store Locations"
  - dataSource: DataSource | location data
  - latitudeField: string | "latitude"
  - longitudeField: string | "longitude"
  - titleField: string | "storeName"
  - zoom: number | 8
  - height: string | "400px"
  - markerColor: string | "#2196F3"
  - clusterMarkers: boolean | true

Example:
  {
    id: 'storeLocationsMap',
    type: 'map-widget',
    label: 'Store Locations',
    zoom: 10,
    height: '350px',
    latitudeField: 'lat',
    longitudeField: 'lng',
    titleField: 'storeName',
    clusterMarkers: true,
    dataSource: {
      type: 'api',
      url: '/api/stores/locations'
    }
  }

Type: 'timeline'
Purpose: Event timeline display
When to Use: Project milestones, order status, event history
Parameters:
  - label: string | "Project Milestones"
  - dataSource: DataSource | timeline events
  - dateField: string | "date"
  - titleField: string | "title"
  - descriptionField: string | "description"
  - alignment: 'left' | 'right' | 'alternate'
  - variant: 'outlined' | 'dot'

Example:
  {
    id: 'projectTimeline',
    type: 'timeline',
    label: 'Project Milestones',
    alignment: 'alternate',
    dateField: 'milestoneDate',
    titleField: 'milestoneName',
    descriptionField: 'description',
    dataSource: {
      type: 'api',
      url: '/api/project/milestones'
    }
  }

Type: 'kanban'
Purpose: Kanban board visualization
When to Use: Task management, workflow status, agile boards
Parameters:
  - label: string | "Tasks Board"
  - dataSource: DataSource | tasks data
  - columns: KanbanColumn[] | column definitions
  - groupBy: string | "status" (field to group by)
  - cardTitle: string | "title"
  - cardDescription?: string | "description"
  - dragDropEnabled: boolean | true
  - height: string | "500px"

Example:
  {
    id: 'tasksKanban',
    type: 'kanban',
    label: 'Development Tasks',
    groupBy: 'status',
    cardTitle: 'taskName',
    cardDescription: 'assignee',
    dragDropEnabled: true,
    height: '500px',
    columns: [
      { id: 'todo', title: 'To Do', color: '#gray' },
      { id: 'inProgress', title: 'In Progress', color: '#blue' },
      { id: 'review', title: 'Review', color: '#orange' },
      { id: 'done', title: 'Done', color: '#green' }
    ],
    dataSource: {
      type: 'api',
      url: '/api/tasks'
    }
  }

11. Progress Tracker

Type: 'progress-tracker'
Purpose: Show progress towards goal
When to Use: Sales targets, completion percentage, achievement tracking
Parameters:
  - label: string | "Annual Target"
  - value: number | current progress
  - target: number | 100
  - unit: string | "%"
  - showLabel: boolean | true
  - color: 'primary' | 'success' | 'warning' | 'error'
  - striped: boolean | false
  - animated: boolean | true

Example:
  {
    id: 'salesTargetProgress',
    type: 'progress-tracker',
    label: 'Q1 Sales Target',
    value: 75,
    target: 100,
    unit: '%',
    color: 'success',
    striped: true,
    animated: true,
    dataSource: {
      type: 'api',
      url: '/api/sales/progress'
    }
  }

12. Activity Log

Type: 'activity-log'
Purpose: Log of system activities and events
When to Use: System audit, user activities, change tracking
Parameters:
  - label: string | "System Activity"
  - dataSource: DataSource | activity entries
  - timestampField: string | "createdAt"
  - actionField: string | "action"
  - userField: string | "user"
  - maxItems: number | 50
  - showTimestamp: boolean | true
  - showUser: boolean | true

Example:
  {
    id: 'systemActivityLog',
    type: 'activity-log',
    label: 'System Activity',
    maxItems: 100,
    timestampField: 'timestamp',
    actionField: 'action',
    userField: 'username',
    showTimestamp: true,
    showUser: true,
    dataSource: {
      type: 'api',
      url: '/api/audit/activities'
    }
  }

Container & Layout Widgets

13. Grid Container

Type: 'responsive-grid'
Purpose: Grid layout for arranging widgets
When to Use: Widget arrangement, responsive dashboards
Parameters:
  - columns: DashboardWidget[] | child widgets
  - columnCount: number | 12 (Bootstrap grid width)
  - gap: string | "20px"
  - responsive: boolean | true (stack on mobile)

Example:
  {
    id: 'mainDashboardGrid',
    type: 'responsive-grid',
    columnCount: 12,
    gap: '20px',
    children: [
      // Each widget specifies gridColumn, gridRow, or width
    ]
  }

14. Spacer/Divider

Type: 'spacer' or 'divider'
Purpose: Visual spacing and separation
When to Use: Dashboard organization, visual breaks
Parameters:
  - height: string | "20px" (for spacer)
  - variant: 'fullWidth' | 'inset' (for divider)

---

## Dashboard Configuration Example

Complete dashboard with multiple widget types:

```typescript
{
  id: 'salesDashboard',
  pageMode: 'dashboard',
  name: 'Sales Analytics Dashboard',
  settings: {
    layout: 'responsive',
    columnCount: 12,
    autoRefresh: true,
    autoRefreshInterval: 300000, // 5 minutes
    timezone: 'UTC'
  },
  components: [
    // KPI Row
    {
      id: 'kpiRow',
      type: 'responsive-grid',
      columnCount: 12,
      gap: '15px',
      children: [
        {
          id: 'totalRevenueKpi',
          type: 'kpi',
          label: 'Total Revenue',
          gridColumn: '1 / span 3',
          format: 'currency',
          trend: { value: 15, direction: 'up' },
          dataSource: { type: 'api', url: '/api/metrics/revenue' }
        },
        {
          id: 'orderCountKpi',
          type: 'kpi',
          label: 'Total Orders',
          gridColumn: '4 / span 3',
          format: 'number',
          dataSource: { type: 'api', url: '/api/metrics/orders' }
        },
        {
          id: 'conversionKpi',
          type: 'kpi',
          label: 'Conversion Rate',
          gridColumn: '7 / span 3',
          format: 'percentage',
          dataSource: { type: 'api', url: '/api/metrics/conversion' }
        },
        {
          id: 'customerCountKpi',
          type: 'kpi',
          label: 'New Customers',
          gridColumn: '10 / span 3',
          format: 'number',
          trend: { value: 8, direction: 'up' },
          dataSource: { type: 'api', url: '/api/metrics/new-customers' }
        }
      ]
    },
    
    // Charts Row
    {
      id: 'chartsRow',
      type: 'responsive-grid',
      columnCount: 12,
      gap: '15px',
      children: [
        {
          id: 'salesTrendChart',
          type: 'chart',
          label: 'Sales Trend',
          gridColumn: '1 / span 8',
          chartType: 'line',
          xAxisKey: 'date',
          yAxisKey: 'revenue',
          height: '400px',
          dataSource: { type: 'api', url: '/api/sales/trend' }
        },
        {
          id: 'salesByRegionChart',
          type: 'chart',
          label: 'Sales by Region',
          gridColumn: '9 / span 4',
          chartType: 'pie',
          height: '400px',
          dataSource: { type: 'api', url: '/api/sales/by-region' }
        }
      ]
    },
    
    // Data Table Row
    {
      id: 'dataRow',
      type: 'responsive-grid',
      columnCount: 12,
      gap: '15px',
      children: [
        {
          id: 'topProductsTable',
          type: 'table-widget',
          label: 'Top Products',
          gridColumn: '1 / span 6',
          dataSource: { type: 'api', url: '/api/products/top' }
        },
        {
          id: 'recentOrdersList',
          type: 'list-widget',
          label: 'Recent Orders',
          gridColumn: '7 / span 6',
          dataSource: { type: 'api', url: '/api/orders/recent' }
        }
      ]
    }
  ]
}

Data Source Configuration

interface DataSource {
  type: 'api' | 'resource' | 'static';
  url?: string; // For API
  method?: 'GET' | 'POST';
  headers?: Record<string, string>;
  resourceKey?: string; // For resource
  staticData?: any[]; // For static
  refreshInterval?: number; // milliseconds
  cacheData?: boolean; // Cache results
  cacheDuration?: number; // seconds
}

Real-Time Updates with WebSocket

{
  dataSource: {
    type: 'api',
    url: '/api/live-metrics',
    refreshInterval: 5000, // Refresh every 5 seconds
    method: 'GET'
  }
}

Export & Printing

Configure export capabilities for dashboards.

interface ExportConfig {
  formats: ('pdf' | 'excel' | 'csv')[];
  filename?: string;
  includeCharts?: boolean;
  includeTables?: boolean;
  landscape?: boolean;
}

Widgets use 12-column grid system (Bootstrap):

{
  gridColumn: '1 / span 6',  // Start at column 1, span 6 columns (50% width)
  gridRow: '1 / span 2',      // Start at row 1, span 2 rows
  width: '50%',               // Alternative: percentage width
  height: '400px'             // Fixed or auto height
}

Common sizing patterns:

Full width: gridColumn: '1 / span 12'
Half width: gridColumn: '1 / span 6'
One-third: gridColumn: '1 / span 4'
One-quarter: gridColumn: '1 / span 3'

Best Practices

Responsiveness: Always test dashboards on mobile devices
Performance: Use autoRefreshInterval wisely (don't refresh too often)
Color Coding: Use consistent colors for similar metrics
KPI Placement: Put most important KPIs at the top
Data Labels: Show units and decimals appropriately
Legends: Always include chart legends for clarity
Export: Enable export for reports and analysis
Caching: Cache static data sources to improve performance
Drill-Down: Implement drill-down for detailed analysis
Alerts: Configure thresholds for warning/critical states

Next: See PAGE_DESIGNER_CONTENT.md for Content page types.

Page Designer - Dashboards Documentation

Overview

Page Mode: "dashboard"

Dashboard Widgets (14 Types)

KPI & Metric Widgets

1. KPI (Key Performance Indicator)

2. Gauge

3. Metric

Chart Widgets

4. Chart (Multi-Type)

Data & List Widgets

5. Table Widget

6. List Widget

Visualization Widgets

7. Calendar Widget

8. Map Widget

9. Timeline Widget

10. Kanban Widget

11. Progress Tracker

12. Activity Log

Container & Layout Widgets

13. Grid Container

14. Spacer/Divider

Data Source Configuration

Real-Time Updates with WebSocket

Export & Printing

Widget Sizing & Positioning

Best Practices

Overview​

Page Mode: "dashboard"​

Dashboard Widgets (14 Types)​

KPI & Metric Widgets​

1. KPI (Key Performance Indicator)​

2. Gauge​

3. Metric​

Chart Widgets​

4. Chart (Multi-Type)​

Data & List Widgets​

5. Table Widget​

6. List Widget​

Visualization Widgets​

7. Calendar Widget​

8. Map Widget​

9. Timeline Widget​

10. Kanban Widget​

11. Progress Tracker​

12. Activity Log​

Container & Layout Widgets​

13. Grid Container​

14. Spacer/Divider​

Data Source Configuration​

Real-Time Updates with WebSocket​

Export & Printing​

Widget Sizing & Positioning​

Best Practices​

Overview

Page Mode: "dashboard"

Dashboard Widgets (14 Types)

KPI & Metric Widgets

1. KPI (Key Performance Indicator)

2. Gauge

3. Metric

Chart Widgets

4. Chart (Multi-Type)

Data & List Widgets

5. Table Widget

6. List Widget

Visualization Widgets

7. Calendar Widget

8. Map Widget

9. Timeline Widget

10. Kanban Widget

11. Progress Tracker

12. Activity Log

Container & Layout Widgets

13. Grid Container

14. Spacer/Divider

Data Source Configuration

Real-Time Updates with WebSocket

Export & Printing

Widget Sizing & Positioning

Best Practices