@adminforth/dashboard 1.0.0 → 1.2.0

package/README.md

@@ -2,58 +2,103 @@
 
 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
+
+```ts
+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
+
+```ts
+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
+
+```text
 DashboardPage.vue
-  └── DashboardRuntime.vue
-        ├── DashboardGroup.vue
-        │     └── WidgetShell.vue
-        │           └── WidgetRenderer.vue
-        │                 ├── TableWidget.vue
-        │                 ├── ChartWidget.vue
-        │                 ├── KpiCardWidget.vue
-        │                 ├── PivotTableWidget.vue
-        │                 └── GaugeCardWidget.vue
-        └── DashboardEditorPanel.vue
-
-src/features/dashboards/
-
-  runtime/
-    DashboardPage.vue
-    DashboardRuntime.vue
-    DashboardGroup.vue
-    WidgetShell.vue
-    WidgetRenderer.vue
-
-  widgets/
-    registry.ts
-
-    table/
-      TableWidget.vue
-      TableWidgetEditor.vue
-      table.adapter.ts
-
-    chart/
-      ChartWidget.vue
-      ChartWidgetEditor.vue
-      chart.adapter.ts
-      charts/
-        PieChart.vue
-        LineChart.vue
-        BarChart.vue
-        StackedBarChart.vue
-        FunnelChart.vue
-        HistogramChart.vue
-
-    kpi-card/
-      KpiCardWidget.vue
-      KpiCardWidgetEditor.vue
-      kpi.adapter.ts
-
-    pivot-table/
-      PivotTableWidget.vue
-      PivotTableWidgetEditor.vue
-      pivot.adapter.ts
-
-    gauge-card/
-      GaugeCardWidget.vue
-      GaugeCardWidgetEditor.vue
-      gauge.adapter.ts
+└── 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`.

package/custom/api/dashboardApi.ts

@@ -24,6 +24,13 @@ export type DashboardWidgetDataResponse = {
   data: unknown
 }
 
+export type DashboardWidgetDataRequest = {
+  pagination?: {
+    page: number
+    pageSize: number
+  }
+}
+
 export class DashboardApiError extends Error {
   validationErrors: DashboardWidgetConfigValidationError[]
 
@@ -204,10 +211,12 @@ export const dashboardApi = {
   async getDashboardWidgetData(
     slug: string,
     widgetId: string,
+    request: DashboardWidgetDataRequest = {},
   ): Promise<DashboardWidgetDataResponse> {
     return callDashboardWidgetDataApi('/adminapi/v1/dashboard/get_dashboard_widget_data', {
       slug,
       widgetId,
+      ...request,
     })
   },
 }

package/custom/model/dashboard.types.ts

@@ -1,5 +1,42 @@
 import type { ChartWidgetConfig } from '../widgets/chart/chart.types.js'
 
+export type AggregationOperation = 'sum' | 'count' | 'avg' | 'min' | 'max' | 'median'
+
+export type AggregationRule = {
+  operation: AggregationOperation
+  field?: string
+}
+
+export type GroupByRule =
+  | {
+      type: 'field'
+      field: string
+    }
+  | {
+      type: 'date_trunc'
+      field: string
+      truncation: 'day' | 'week' | 'month' | 'year'
+      timezone?: string
+    }
+
+export type ResourceWidgetDataSource = {
+  type: 'resource'
+  resourceId: string
+  columns?: string[]
+  sort?: unknown
+  filters?: unknown
+}
+
+export type AggregateWidgetDataSource = {
+  type: 'aggregate'
+  resourceId: string
+  aggregations: Record<string, AggregationRule>
+  groupBy?: GroupByRule
+  filters?: unknown
+}
+
+export type WidgetDataSource = ResourceWidgetDataSource | AggregateWidgetDataSource
+
 export type DashboardConfig = {
   version: number
   groups: DashboardGroupConfig[]
@@ -45,17 +82,57 @@ export type DashboardWidgetConfig = {
   maxWidth?: number | null
   order: number
   target: DashboardWidgetTarget
+  dataSource?: WidgetDataSource
   chart?: ChartWidgetConfig
   table?: unknown
   kpi_card?: unknown
   pivot_table?: unknown
   gauge_card?: unknown
-  query?: unknown
 }
 
 export type DashboardWidgetTableData = {
+  kind?: 'table'
+  columns: string[]
+  rows: Record<string, unknown>[]
+  pagination?: {
+    page: number
+    pageSize: number
+    total: number
+    totalPages: number
+  }
+}
+
+export type DashboardWidgetAggregateData = {
+  kind: 'aggregate'
   columns: string[]
   rows: Record<string, unknown>[]
+  values?: Record<string, unknown>
+}
+
+export type DashboardWidgetData = DashboardWidgetTableData | DashboardWidgetAggregateData
+
+export type NormalizedKpiCardWidgetConfig = {
+  valueField?: string
+  labelField?: string
+  prefix?: string
+  suffix?: string
+}
+
+export type NormalizedGaugeCardWidgetConfig = {
+  valueField?: string
+  min?: number | string
+  max?: number | string
+  minField?: string
+  maxField?: string
+  suffix?: string
+  color?: string
+}
+
+export type NormalizedPivotTableWidgetConfig = {
+  rowField?: string
+  columnField?: string
+  valueField?: string
+  aggregation?: 'count' | 'sum'
 }
 
 export function normalizeDashboardConfig(config: unknown): DashboardConfig {
@@ -64,8 +141,282 @@ export function normalizeDashboardConfig(config: unknown): DashboardConfig {
   return {
     version: typeof value.version === 'number' ? value.version : 1,
     groups: Array.isArray(value.groups) ? (value.groups as DashboardGroupConfig[]) : [],
-    widgets: Array.isArray(value.widgets) ? (value.widgets as DashboardWidgetConfig[]) : [],
+    widgets: Array.isArray(value.widgets)
+      ? value.widgets.map((widget) => normalizeDashboardWidgetConfig(widget) as DashboardWidgetConfig)
+      : [],
+  }
+}
+
+export function normalizeDashboardWidgetConfig(config: unknown) {
+  if (!isRecord(config)) {
+    return config
+  }
+
+  const normalized: Record<string, unknown> = { ...config }
+  normalizeWidgetLayoutConfig(normalized)
+
+  if (normalized.table !== undefined) {
+    normalized.table = normalizeTableConfig(normalized.table)
+  }
+
+  if (normalized.data_source !== undefined) {
+    normalized.dataSource = normalizeWidgetDataSource(normalized.data_source)
+  }
+
+  const target = normalizeDashboardWidgetTarget(normalized.target)
+
+  if (target !== undefined) {
+    normalized.target = target
+  }
+
+  return normalized
+}
+
+export function serializeDashboardWidgetConfigForEditor(widget: DashboardWidgetConfig) {
+  const serialized: Record<string, unknown> = { ...widget }
+
+  if (Object.prototype.hasOwnProperty.call(serialized, 'minWidth')) {
+    serialized.min_width = widget.minWidth
+    delete serialized.minWidth
+  }
+
+  if (Object.prototype.hasOwnProperty.call(serialized, 'maxWidth')) {
+    serialized.max_width = widget.maxWidth
+    delete serialized.maxWidth
+  }
+
+  if (widget.table !== undefined) {
+    serialized.table = serializeTableConfigForEditor(widget.table)
+  }
+
+  if (widget.dataSource !== undefined) {
+    serialized.data_source = serializeWidgetDataSourceForEditor(widget.dataSource)
+    delete serialized.dataSource
+  }
+
+  return serialized
+}
+
+export function normalizeKpiCardWidgetConfig(value: unknown): NormalizedKpiCardWidgetConfig | undefined {
+  const config = asWidgetConfigRecord(value)
+
+  if (!config) {
+    return undefined
+  }
+
+  const valueField = getStringField(config, 'value_field')
+  const labelField = getStringField(config, 'label_field')
+  const prefix = getStringField(config, 'prefix')
+  const suffix = getStringField(config, 'suffix')
+
+  return {
+    ...(valueField !== undefined ? { valueField } : {}),
+    ...(labelField !== undefined ? { labelField } : {}),
+    ...(prefix !== undefined ? { prefix } : {}),
+    ...(suffix !== undefined ? { suffix } : {}),
+  }
+}
+
+export function normalizeGaugeCardWidgetConfig(value: unknown): NormalizedGaugeCardWidgetConfig | undefined {
+  const config = asWidgetConfigRecord(value)
+
+  if (!config) {
+    return undefined
+  }
+
+  const valueField = getStringField(config, 'value_field')
+  const minField = getStringField(config, 'min_field')
+  const maxField = getStringField(config, 'max_field')
+  const suffix = getStringField(config, 'suffix')
+  const color = getStringField(config, 'color')
+
+  return {
+    ...(valueField !== undefined ? { valueField } : {}),
+    ...(config.min !== undefined ? { min: config.min as number | string } : {}),
+    ...(config.max !== undefined ? { max: config.max as number | string } : {}),
+    ...(minField !== undefined ? { minField } : {}),
+    ...(maxField !== undefined ? { maxField } : {}),
+    ...(suffix !== undefined ? { suffix } : {}),
+    ...(color !== undefined ? { color } : {}),
+  }
+}
+
+export function normalizePivotTableWidgetConfig(value: unknown): NormalizedPivotTableWidgetConfig | undefined {
+  const config = asWidgetConfigRecord(value)
+
+  if (!config) {
+    return undefined
+  }
+
+  const rowField = getStringField(config, 'row_field')
+  const columnField = getStringField(config, 'column_field')
+  const valueField = getStringField(config, 'value_field')
+  const aggregation = config.aggregation === 'count' || config.aggregation === 'sum'
+    ? config.aggregation
+    : undefined
+
+  return {
+    ...(rowField !== undefined ? { rowField } : {}),
+    ...(columnField !== undefined ? { columnField } : {}),
+    ...(valueField !== undefined ? { valueField } : {}),
+    ...(aggregation !== undefined ? { aggregation } : {}),
+  }
+}
+
+function normalizeDashboardWidgetTarget(value: unknown): DashboardWidgetTarget | undefined {
+  switch (value) {
+    case 'empty':
+    case 'table':
+    case 'chart':
+    case 'kpi_card':
+    case 'pivot_table':
+    case 'gauge_card':
+      return value
+    default:
+      return undefined
+  }
+}
+
+function normalizeWidgetLayoutConfig(value: Record<string, unknown>) {
+  if (value.min_width !== undefined) {
+    value.minWidth = value.min_width
+  }
+
+  if (value.max_width !== undefined) {
+    value.maxWidth = value.max_width
+  }
+}
+
+function normalizeTableConfig(value: unknown) {
+  if (!isRecord(value)) {
+    return value
+  }
+
+  const normalized = { ...value }
+
+  if (normalized.page_size !== undefined) {
+    normalized.pageSize = normalized.page_size
+  }
+
+  return normalized
+}
+
+function normalizeWidgetDataSource(value: unknown) {
+  if (!isRecord(value) || typeof value.type !== 'string') {
+    return value
+  }
+
+  const resourceId = typeof value.resource_id === 'string'
+    ? value.resource_id
+    : undefined
+
+  if (value.type === 'resource') {
+    return {
+      type: 'resource',
+      ...(resourceId !== undefined ? { resourceId } : {}),
+      ...(value.columns !== undefined ? { columns: value.columns } : {}),
+      ...(value.filters !== undefined ? { filters: value.filters } : {}),
+      ...(value.sort !== undefined ? { sort: value.sort } : {}),
+    }
+  }
+
+  if (value.type === 'aggregate') {
+    const groupBy = normalizeGroupByRule(value.group_by)
+
+    return {
+      type: 'aggregate',
+      ...(resourceId !== undefined ? { resourceId } : {}),
+      ...(value.aggregations !== undefined ? { aggregations: value.aggregations } : {}),
+      ...(groupBy !== undefined ? { groupBy } : {}),
+      ...(value.filters !== undefined ? { filters: value.filters } : {}),
+    }
+  }
+
+  return value
+}
+
+function normalizeGroupByRule(value: unknown) {
+  if (!isRecord(value) || typeof value.type !== 'string') {
+    return value
+  }
+
+  if (value.type === 'field') {
+    return {
+      type: 'field',
+      ...(value.field !== undefined ? { field: value.field } : {}),
+    }
+  }
+
+  if (value.type === 'date_trunc') {
+    return {
+      type: 'date_trunc',
+      ...(value.field !== undefined ? { field: value.field } : {}),
+      ...(value.truncation !== undefined ? { truncation: value.truncation } : {}),
+      ...(value.timezone !== undefined ? { timezone: value.timezone } : {}),
+    }
+  }
+
+  return value
+}
+
+function serializeTableConfigForEditor(value: unknown) {
+  if (!isRecord(value)) {
+    return value
+  }
+
+  const serialized = { ...value }
+
+  if (Object.prototype.hasOwnProperty.call(serialized, 'pageSize')) {
+    serialized.page_size = serialized.pageSize
+    delete serialized.pageSize
   }
+
+  return serialized
+}
+
+function serializeWidgetDataSourceForEditor(value: WidgetDataSource) {
+  if (value.type === 'resource') {
+    return {
+      type: 'resource',
+      resource_id: value.resourceId,
+      ...(value.columns !== undefined ? { columns: value.columns } : {}),
+      ...(value.filters !== undefined ? { filters: value.filters } : {}),
+      ...(value.sort !== undefined ? { sort: value.sort } : {}),
+    }
+  }
+
+  return {
+    type: 'aggregate',
+    resource_id: value.resourceId,
+    aggregations: value.aggregations,
+    ...(value.groupBy !== undefined ? { group_by: serializeGroupByRuleForEditor(value.groupBy) } : {}),
+    ...(value.filters !== undefined ? { filters: value.filters } : {}),
+  }
+}
+
+function serializeGroupByRuleForEditor(value: GroupByRule) {
+  if (value.type === 'field') {
+    return {
+      type: 'field',
+      field: value.field,
+    }
+  }
+
+  return {
+    type: 'date_trunc',
+    field: value.field,
+    truncation: value.truncation,
+    ...(value.timezone !== undefined ? { timezone: value.timezone } : {}),
+  }
+}
+
+function asWidgetConfigRecord(value: unknown): Record<string, unknown> | undefined {
+  return isRecord(value) ? value : undefined
+}
+
+function getStringField(record: Record<string, unknown>, key: string) {
+  const value = record[key]
+  return typeof value === 'string' ? value : undefined
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {

package/custom/queries/useWidgetData.ts

@@ -1,7 +1,11 @@
 import { ref, watch, type Ref } from 'vue'
-import { dashboardApi } from '../api/dashboardApi.js'
+import { dashboardApi, type DashboardWidgetDataRequest } from '../api/dashboardApi.js'
 
-export function useWidgetData(slug: Ref<string>, widgetId: Ref<string>) {
+export function useWidgetData(
+  slug: Ref<string>,
+  widgetId: Ref<string>,
+  request?: Ref<DashboardWidgetDataRequest>,
+) {
   const data = ref<Awaited<ReturnType<typeof dashboardApi.getDashboardWidgetData>> | null>(null)
   const isLoading = ref(false)
   const isFetching = ref(false)
@@ -20,7 +24,7 @@ export function useWidgetData(slug: Ref<string>, widgetId: Ref<string>) {
     }
 
     try {
-      const response = await dashboardApi.getDashboardWidgetData(slug.value, widgetId.value)
+      const response = await dashboardApi.getDashboardWidgetData(slug.value, widgetId.value, request?.value)
       data.value = response
       error.value = null
       return response
@@ -34,7 +38,7 @@ export function useWidgetData(slug: Ref<string>, widgetId: Ref<string>) {
   }
 
   watch(
-    [slug, widgetId],
+    request ? [slug, widgetId, request] : [slug, widgetId],
     () => {
       void refetch()
     },

package/custom/runtime/DashboardRuntime.vue

@@ -211,6 +211,7 @@ import type {
   DashboardWidgetConfig,
   DashboardWidgetMoveDirection,
 } from '../model/dashboard.types.js'
+import { serializeDashboardWidgetConfigForEditor } from '../model/dashboard.types.js'
 
 const props = defineProps<{
   dashboardSlug: string
@@ -388,7 +389,7 @@ async function removeWidget(widgetId: string) {
 
 function editWidget(widget: DashboardWidgetConfig) {
   editingWidgetId.value = widget.id
-  widgetConfigCode.value = stringifyYaml(widget)
+  widgetConfigCode.value = stringifyYaml(serializeDashboardWidgetConfigForEditor(widget))
   widgetConfigError.value = ''
   widgetConfigFieldErrors.value = []
 }

package/custom/runtime/WidgetRenderer.vue

@@ -26,6 +26,7 @@
 <script setup lang="ts">
 import { computed } from 'vue'
 import type { DashboardWidgetConfig } from '../model/dashboard.types.js'
+import { normalizeChartWidgetConfig } from '../widgets/chart/chart.types.js'
 import { getWidgetLabel, getWidgetRegistration } from '../widgets/registry.js'
 
 const props = defineProps<{
@@ -52,7 +53,7 @@ const widgetTitle = computed(() => {
   }
 
   if (props.widget.target === 'chart') {
-    return props.widget.chart?.title || 'Untitled chart'
+    return normalizeChartWidgetConfig(props.widget.chart)?.title || 'Untitled chart'
   }
 
   return getWidgetLabel(props.widget.target)

package/custom/runtime/WidgetShell.vue

@@ -135,11 +135,11 @@ const widgetLayoutVars = computed<CSSProperties>(() => {
   const fixedWidth = formatWidth(props.layout?.width)
 
   return {
-    '--widget-basis': fixedWidth ?? basis,
-    '--widget-min-width': fixedWidth ?? formatWidth(props.layout?.minWidth) ?? basis,
+    '--widget-basis': clampToContainerWidth(fixedWidth ?? basis),
+    '--widget-min-width': clampToContainerWidth(fixedWidth ?? formatWidth(props.layout?.minWidth) ?? basis),
     '--widget-max-width': props.layout?.maxWidth === null
-      ? 'none'
-      : fixedWidth ?? formatWidth(props.layout?.maxWidth) ?? 'none',
+      ? '100%'
+      : clampToContainerWidth(fixedWidth ?? formatWidth(props.layout?.maxWidth) ?? '100%'),
     height: formatWidth(props.layout?.height ?? DEFAULT_WIDGET_HEIGHT),
   }
 })
@@ -149,4 +149,8 @@ function formatWidth(value: number | undefined) {
     return `${value}px`
   }
 }
+
+function clampToContainerWidth(value: string) {
+  return `min(${value}, 100%)`
+}
 </script>

package/custom/skills/adminforth-dashboard/SKILL.md

@@ -119,7 +119,7 @@ Use the current schema keys exactly:
 
 - Use `target`, not `type`.
 - Use `label`, not `title`.
-- Use `query.resource`, not `resourceId`.
-- Use `query.select`, not `columns`.
-- Use `query.order`, not `sort`.
-- Use `query.limit` for row count.
+- Use `data_source`, not `dataSource`.
+- Use `resource_id`, not `resourceId`.
+- Use `group_by`, not `groupBy`.
+- Use `page_size`, not `pageSize`.