@adminforth/dashboard

Dashboard plugin for AdminForth.

It adds configurable dashboard pages backed by an AdminForth resource. Dashboard records define groups and widgets, the plugin renders them under /dashboard/:slug, contributes a Dashboards sidebar group, and exposes endpoints for editing groups and widgets from the AdminForth UI.

Full setup guide: https://adminforth.dev/docs/tutorial/Plugins/dashboard/

Dashboard Config Shape

type DashboardConfig = {
  version: number
  groups: {
    id: string
    label: string
    order: number
  }[]
  widgets: DashboardWidgetConfig[]
}

Each widget has common fields:

| Field | Description | | --- | --- | | id | Persisted widget id. | | group_id | Group where the widget is rendered. | | label | Optional widget title. | | target | Widget type: table, chart, kpi_card, pivot_table, or gauge_card. | | order | Widget order inside its group. | | size | Preset width: small, medium, large, wide, or full. | | width, height, min_width, max_width | Optional explicit layout constraints. | | data_source | Resource or aggregate data source definition. |

Widget Support Matrix

| Widget target | Config field | Main settings | Data usage | | --- | --- | --- | --- | | table | table | pagination, page_size | Uses data_source.type = 'resource' to display resource rows with backend pagination unless pagination is false. | | chart | chart | type, x_field, y_field, label_field, value_field, bucket_field, buckets, series, series_name, color, colors | Uses data_source.type = 'aggregate' with group_by. | | kpi_card | kpi_card | value_field, label_field, prefix, suffix | Reads aggregate values or the first returned row from data_source. | | gauge_card | gauge_card | value_field, min, max, min_field, max_field, suffix, color | Reads aggregate values or the first returned row from data_source and renders progress between static or field-driven bounds. | | pivot_table | pivot_table | row_field, column_field, value_field, aggregation | Uses grouped aggregate rows from data_source.type = 'aggregate'. aggregation supports count and sum. |

Chart widget types:

| Chart type | Notes | | --- | --- | | line | Uses x_field and y_field; optional series_name and color. | | pie | Uses label_field and optional value_field; without value_field, rows are counted by label. | | bar | Uses label_field and value_field, or bucket_field with buckets. | | stacked_bar | Uses x_field and series; if series is omitted, non-x columns become series. | | funnel | Uses label_field, value_field, and optional colors. | | histogram | Uses the same bucket settings as bar. |

Data Source Shape

type WidgetDataSource =
  | {
      type: 'resource'
      resource_id: string
      columns?: string[]
      filters?: unknown
      sort?: unknown
    }
  | {
      type: 'aggregate'
      resource_id: string
      aggregations: Record<string, {
        operation: 'sum' | 'count' | 'avg' | 'min' | 'max' | 'median'
        field?: string
      }>
      group_by?:
        | { type: 'field'; field: string }
        | {
            type: 'date_trunc'
            field: string
            truncation: 'day' | 'week' | 'month' | 'year'
            timezone?: string
          }
      filters?: unknown
    }

resource_id is an AdminForth resourceId. The data source is executed through AdminForth resources, so widgets use the same resource contracts as the rest of the application.

Runtime Structure

DashboardPage.vue
└── DashboardRuntime.vue
    └── DashboardGroup.vue
        └── WidgetShell.vue
            └── WidgetRenderer.vue
                ├── TableWidget.vue
                ├── ChartWidget.vue
                ├── KpiCardWidget.vue
                ├── PivotTableWidget.vue
                └── GaugeCardWidget.vue

DashboardPage.vue loads a dashboard by slug, DashboardRuntime.vue renders ordered groups, WidgetShell.vue provides the widget frame and editor actions, and WidgetRenderer.vue selects the widget component by target.