@adminforth/dashboard 1.0.0 → 1.1.0

package/README.md

@@ -2,58 +2,120 @@
 
 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`, `minWidth`, `maxWidth` | Optional explicit layout constraints. |
+| `dataSource` | Optional resource or aggregate data source definition. |
+| `query` | Optional AdminForth resource query used to load widget data. |
+
+## Widget Support Matrix
+
+| Widget target | Config field | Main settings | Data usage |
+| --- | --- | --- | --- |
+| `table` | `table` | `columns`, `pagination`, `pageSize` | Uses `dataSource.type = 'resource'` or legacy `query` 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` | Supports legacy `query` or `dataSource.type = 'aggregate'` with `groupBy`. |
+| `kpi_card` | `kpi_card` | `value_field`, `label_field`, `prefix`, `suffix` | Reads the first row or aggregate values and formats one numeric value. |
+| `gauge_card` | `gauge_card` | `value_field`, `min`, `max`, `min_field`, `max_field`, `suffix`, `color` | Reads the first row or aggregate values and renders progress between static or field-driven bounds. |
+| `pivot_table` | `pivot_table` | `row_field`, `column_field`, `value_field`, `aggregation` | Supports legacy row-based queries and grouped aggregate rows. `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`. |
+
+## Query Shape
+
+```ts
+type DashboardWidgetQuery = {
+  resource: string
+  select?: string[]
+  order?: {
+    field: string
+    direction: 'asc' | 'desc'
+  }
+  limit?: number
+}
+```
+
+`resource` is an AdminForth `resourceId`. The query is executed through AdminForth resources, so widgets use the same resource contracts as the rest of the application.
+
+## Data Source Shape
+
+```ts
+type WidgetDataSource =
+  | {
+      type: 'resource'
+      resourceId: string
+      columns?: string[]
+      filters?: unknown
+      sort?: unknown
+    }
+  | {
+      type: 'aggregate'
+      resourceId: string
+      aggregations: Record<string, {
+        operation: 'sum' | 'count' | 'avg' | 'min' | 'max' | 'median'
+        field?: string
+      }>
+      groupBy?:
+        | { type: 'field'; field: string }
+        | {
+            type: 'date_trunc'
+            field: string
+            truncation: 'day' | 'week' | 'month' | 'year'
+            timezone?: string
+          }
+      filters?: unknown
+    }
+```
+
+`query` remains supported for backwards compatibility. When both are present, widgets prefer `dataSource`.
+
+## 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,6 +82,7 @@ export type DashboardWidgetConfig = {
   maxWidth?: number | null
   order: number
   target: DashboardWidgetTarget
+  dataSource?: WidgetDataSource
   chart?: ChartWidgetConfig
   table?: unknown
   kpi_card?: unknown
@@ -54,20 +92,139 @@ export type DashboardWidgetConfig = {
 }
 
 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 function normalizeDashboardConfig(config: unknown): DashboardConfig {
   const value = isRecord(config) ? config : {}
 
   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 }
+  const target = normalizeDashboardWidgetTarget(normalized.target ?? normalized.type)
+
+  if (target && normalized.target === undefined) {
+    normalized.target = target
+  }
+
+  if (target === 'kpi_card') {
+    const kpiCardConfig = normalizeKpiCardConfig(normalized)
+
+    if (kpiCardConfig !== undefined) {
+      normalized.kpi_card = kpiCardConfig
+    }
+  }
+
+  if (target === 'gauge_card') {
+    const gaugeCardConfig = normalizeGaugeCardConfig(normalized)
+
+    if (gaugeCardConfig !== undefined) {
+      normalized.gauge_card = gaugeCardConfig
+    }
+  }
+
+  return normalized
+}
+
+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 normalizeKpiCardConfig(value: Record<string, unknown>) {
+  const config = isRecord(value.kpi_card) ? { ...value.kpi_card } : {}
+
+  if (typeof value.valueField === 'string' && config.value_field === undefined) {
+    config.value_field = value.valueField
+  }
+
+  if (typeof value.labelField === 'string' && config.label_field === undefined) {
+    config.label_field = value.labelField
+  }
+
+  if (typeof value.prefix === 'string' && config.prefix === undefined) {
+    config.prefix = value.prefix
+  }
+
+  if (typeof value.suffix === 'string' && config.suffix === undefined) {
+    config.suffix = value.suffix
+  }
+
+  return Object.keys(config).length ? config : value.kpi_card
+}
+
+function normalizeGaugeCardConfig(value: Record<string, unknown>) {
+  const config = isRecord(value.gauge_card) ? { ...value.gauge_card } : {}
+
+  if (typeof value.valueField === 'string' && config.value_field === undefined) {
+    config.value_field = value.valueField
+  }
+
+  if (value.min !== undefined && config.min === undefined) {
+    config.min = value.min
+  }
+
+  if (value.max !== undefined && config.max === undefined) {
+    config.max = value.max
+  }
+
+  if (typeof value.minField === 'string' && config.min_field === undefined) {
+    config.min_field = value.minField
+  }
+
+  if (typeof value.maxField === 'string' && config.max_field === undefined) {
+    config.max_field = value.maxField
+  }
+
+  if (typeof value.suffix === 'string' && config.suffix === undefined) {
+    config.suffix = value.suffix
+  }
+
+  if (typeof value.color === 'string' && config.color === undefined) {
+    config.color = value.color
+  }
+
+  return Object.keys(config).length ? config : value.gauge_card
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null
 }

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/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/widgets/chart/chart.utils.ts

@@ -14,8 +14,8 @@ export function toFiniteNumber(value: unknown) {
   return Number.isFinite(numberValue) ? numberValue : 0
 }
 
-export function formatChartValue(value: number) {
-  return new Intl.NumberFormat().format(value)
+export function formatChartValue(value: number, options: Intl.NumberFormatOptions = {}) {
+  return new Intl.NumberFormat(undefined, options).format(value)
 }
 
 export function formatChartLabel(value: unknown) {

package/custom/widgets/gauge-card/GaugeCardWidget.vue

@@ -18,6 +18,66 @@ const {
   refetch,
 } = useWidgetData(dashboardSlugRef, widgetIdRef)
 
+type GaugeCardConfig = {
+  value_field?: string
+  valueField?: string
+  min?: number | string
+  max?: number | string
+  min_field?: string
+  minField?: string
+  max_field?: string
+  maxField?: string
+  suffix?: string
+  color?: string
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
+
+function parseGaugeCardConfig(value: unknown): GaugeCardConfig | undefined {
+  if (isRecord(value)) {
+    return value as GaugeCardConfig
+  }
+
+  if (typeof value !== 'string') {
+    return undefined
+  }
+
+  try {
+    const parsed = JSON.parse(value) as unknown
+    return isRecord(parsed) ? parsed as GaugeCardConfig : undefined
+  } catch {
+    return undefined
+  }
+}
+
+function parseOptionalNumber(value: unknown): number | undefined {
+  if (value === null || value === undefined || value === '') {
+    return undefined
+  }
+
+  const parsed = typeof value === 'number' ? value : Number(value)
+  return Number.isFinite(parsed) ? parsed : undefined
+}
+
+function countFractionDigits(value: number) {
+  if (!Number.isFinite(value)) {
+    return 0
+  }
+
+  const normalizedValue = value.toString().toLowerCase()
+  const [coefficient, exponentValue] = normalizedValue.split('e')
+  const exponent = exponentValue ? Number(exponentValue) : 0
+  const decimalDigits = coefficient.split('.')[1]?.length ?? 0
+
+  return Math.max(decimalDigits - exponent, 0)
+}
+
+function normalizeDisplayValue(value: number, useWholeNumbers: boolean) {
+  return useWholeNumbers ? Math.trunc(value) : value
+}
+
 watch(
   () => props.widget,
   () => {
@@ -26,20 +86,42 @@ watch(
   { deep: true },
 )
 
-const gaugeConfig = computed(() => props.widget.gauge_card as {
-  value_field?: string
-  min?: number
-  max?: number
-  suffix?: string
-  color?: string
-} | undefined)
+const gaugeConfig = computed(() => parseGaugeCardConfig(props.widget.gauge_card))
 const widgetData = computed(() => data.value?.data as DashboardWidgetTableData | null)
 const columns = computed(() => widgetData.value?.columns ?? [])
 const firstRow = computed(() => widgetData.value?.rows[0] ?? {})
-const valueField = computed(() => gaugeConfig.value?.value_field || columns.value[0])
-const minValue = computed(() => gaugeConfig.value?.min ?? 0)
-const maxValue = computed(() => gaugeConfig.value?.max ?? 100)
+const valueField = computed(() => gaugeConfig.value?.value_field || gaugeConfig.value?.valueField || columns.value[0])
+const minField = computed(() => gaugeConfig.value?.min_field || gaugeConfig.value?.minField)
+const maxField = computed(() => gaugeConfig.value?.max_field || gaugeConfig.value?.maxField)
+const minValue = computed(() => {
+  const dynamicMin = minField.value ? parseOptionalNumber(firstRow.value[minField.value]) : undefined
+  return dynamicMin ?? parseOptionalNumber(gaugeConfig.value?.min) ?? 0
+})
+const maxValue = computed(() => {
+  const dynamicMax = maxField.value ? parseOptionalNumber(firstRow.value[maxField.value]) : undefined
+  return dynamicMax ?? parseOptionalNumber(gaugeConfig.value?.max) ?? 100
+})
 const value = computed(() => toFiniteNumber(firstRow.value[valueField.value]))
+const fractionDigits = computed(() => Math.min([
+  value.value,
+  minValue.value,
+  maxValue.value,
+].reduce((maxDigits, currentValue) => Math.max(maxDigits, countFractionDigits(currentValue)), 0), 3))
+const shouldUseWholeNumbers = computed(() => Math.abs(maxValue.value) >= 1000)
+const formattedValue = computed(() => formatChartValue(normalizeDisplayValue(value.value, shouldUseWholeNumbers.value), {
+  minimumFractionDigits: shouldUseWholeNumbers.value ? 0 : fractionDigits.value,
+  maximumFractionDigits: shouldUseWholeNumbers.value ? 0 : fractionDigits.value,
+}))
+const formattedMinValue = computed(() => formatChartValue(normalizeDisplayValue(minValue.value, shouldUseWholeNumbers.value), {
+  minimumFractionDigits: shouldUseWholeNumbers.value ? 0 : fractionDigits.value,
+  maximumFractionDigits: shouldUseWholeNumbers.value ? 0 : fractionDigits.value,
+}))
+const formattedMaxValue = computed(() => {
+  return formatChartValue(normalizeDisplayValue(maxValue.value, shouldUseWholeNumbers.value), {
+    minimumFractionDigits: shouldUseWholeNumbers.value ? 0 : fractionDigits.value,
+    maximumFractionDigits: shouldUseWholeNumbers.value ? 0 : fractionDigits.value,
+  })
+})
 const progress = computed(() => {
   const range = maxValue.value - minValue.value
   return range > 0 ? Math.min(Math.max((value.value - minValue.value) / range, 0), 1) : 0
@@ -97,10 +179,10 @@ const gaugeColor = computed(() => gaugeConfig.value?.color || CHART_COLORS[0])
       </svg>
 
       <div class="text-3xl font-bold text-lightNavbarText dark:text-darkNavbarText">
-        {{ formatChartValue(value) }}{{ gaugeConfig?.suffix ?? '' }}
+        {{ formattedValue }}{{ gaugeConfig?.suffix ?? '' }}
       </div>
       <div class="text-sm text-lightListTableText dark:text-darkListTableText">
-        {{ formatChartValue(minValue) }} - {{ formatChartValue(maxValue) }}
+        {{ formattedMinValue }} - {{ formattedMaxValue }}
       </div>
     </div>
   </div>

package/custom/widgets/pivot-table/PivotTableWidget.vue

@@ -1,7 +1,7 @@
 <script setup lang="ts">
 import { computed, watch } from 'vue'
 import { useWidgetData } from '../../queries/useWidgetData.js'
-import type { DashboardWidgetConfig, DashboardWidgetTableData } from '../../model/dashboard.types.js'
+import type { DashboardWidgetConfig, DashboardWidgetData } from '../../model/dashboard.types.js'
 import { formatChartLabel, formatChartValue, toFiniteNumber } from '../chart/chart.utils.js'
 
 const props = defineProps<{
@@ -32,15 +32,37 @@ const pivotConfig = computed(() => props.widget.pivot_table as {
   value_field?: string
   aggregation?: 'count' | 'sum'
 } | undefined)
-const widgetData = computed(() => data.value?.data as DashboardWidgetTableData | null)
+const widgetData = computed(() => data.value?.data as DashboardWidgetData | null)
 const rows = computed(() => widgetData.value?.rows ?? [])
 const columns = computed(() => widgetData.value?.columns ?? [])
-const rowField = computed(() => pivotConfig.value?.row_field || columns.value[0])
+const isAggregateData = computed(() => widgetData.value?.kind === 'aggregate')
+const shouldRenderAggregateMatrix = computed(() => isAggregateData.value && !pivotConfig.value?.column_field)
+const rowField = computed(() => pivotConfig.value?.row_field || (isAggregateData.value ? 'group' : columns.value[0]))
 const columnField = computed(() => pivotConfig.value?.column_field || columns.value[1])
-const valueField = computed(() => pivotConfig.value?.value_field || columns.value[2])
+const valueField = computed(() => pivotConfig.value?.value_field || columns.value[2] || columns.value[1])
 const aggregation = computed(() => pivotConfig.value?.aggregation || (valueField.value ? 'sum' : 'count'))
-const pivotColumnLabels = computed(() => Array.from(new Set(rows.value.map((row) => formatChartLabel(row[columnField.value])))))
+const pivotColumnLabels = computed(() => {
+  if (shouldRenderAggregateMatrix.value) {
+    return columns.value.filter((column) => column !== rowField.value)
+  }
+
+  return Array.from(new Set(rows.value.map((row) => formatChartLabel(row[columnField.value]))))
+})
 const pivotRows = computed(() => {
+  if (shouldRenderAggregateMatrix.value) {
+    return rows.value.map((row) => {
+      const item: Record<string, number | string> = {
+        label: formatChartLabel(row[rowField.value]),
+      }
+
+      for (const column of pivotColumnLabels.value) {
+        item[column] = toFiniteNumber(row[column])
+      }
+
+      return item
+    })
+  }
+
   const rowMap = new Map<string, Record<string, number | string>>()
 
   for (const row of rows.value) {