@adminforth/dashboard 1.1.0 → 1.3.0

package/custom/model/dashboard.types.ts

@@ -1,42 +1,5 @@
 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[]
@@ -50,18 +13,19 @@ export type DashboardGroupConfig = {
 }
 
 export type DashboardGroupMoveDirection = 'up' | 'down'
-
 export type DashboardWidgetMoveDirection = 'up' | 'down'
-
-export type DashboardWidgetTarget =
-  | 'empty'
-  | 'table'
-  | 'chart'
-  | 'kpi_card'
-  | 'pivot_table'
-  | 'gauge_card'
-
+export type DashboardWidgetTarget = 'empty' | 'table' | 'chart' | 'kpi_card' | 'pivot_table' | 'gauge_card'
 export type DashboardWidgetSize = 'small' | 'medium' | 'large' | 'wide' | 'full'
+export type QueryAggregateOperation = 'sum' | 'count' | 'count_distinct' | 'avg' | 'min' | 'max' | 'median'
+export type TimeGrain = 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year'
+export type ValueFormat =
+  | 'number'
+  | 'compact_number'
+  | 'currency'
+  | 'percent'
+  | 'percent_delta'
+  | 'number_delta'
+  | 'currency_delta'
 
 export type WidgetLayout = {
   size?: DashboardWidgetSize
@@ -71,7 +35,7 @@ export type WidgetLayout = {
   height?: number
 }
 
-export type DashboardWidgetConfig = {
+export type WidgetBaseConfig = {
   id: string
   group_id: string
   label?: string
@@ -81,16 +45,200 @@ export type DashboardWidgetConfig = {
   minWidth?: number
   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 FilterExpression =
+  | { and: FilterExpression[] }
+  | { or: FilterExpression[] }
+  | Array<FilterExpression>
+  | {
+      field: string
+      eq?: unknown
+      neq?: unknown
+      gt?: unknown
+      gte?: unknown
+      lt?: unknown
+      lte?: unknown
+      in?: unknown[]
+      not_in?: unknown[]
+      like?: unknown
+      ilike?: unknown
+    }
+
+export type QueryFieldSelectItem = {
+  field: string
+  as?: string
+  grain?: TimeGrain
+}
+
+export type QueryAggregateSelectItem = {
+  agg: QueryAggregateOperation
+  field?: string
+  as: string
+  filters?: FilterExpression
+}
+
+export type QueryCalcSelectItem = {
+  calc: string
+  as: string
+}
+
+export type QuerySelectItem = QueryFieldSelectItem | QueryAggregateSelectItem | QueryCalcSelectItem
+
+export type QueryGroupByItem =
+  | string
+  | {
+      field: string
+      as?: string
+      grain?: TimeGrain
+      timezone?: string
+    }
+
+export type QueryOrderByItem = {
+  field: string
+  direction?: 'asc' | 'desc'
+}
+
+export type QueryConfig = {
+  resource: string
+  select?: QuerySelectItem[]
+  filters?: FilterExpression
+  groupBy?: QueryGroupByItem[]
+  orderBy?: QueryOrderByItem[]
+  limit?: number
+  offset?: number
+  timeSeries?: {
+    field: string
+    grain: TimeGrain
+    timezone?: string
+  }
+  period?: {
+    field: string
+    gte?: unknown
+    lt?: unknown
+  }
+  bucket?: {
+    field: string
+    buckets: Array<{ label: string, min?: number, max?: number }>
+  }
+  calcs?: QueryCalcSelectItem[]
+  formatting?: Record<string, unknown>
+}
+
+export type FunnelQueryConfig = {
+  steps: FunnelQueryStep[]
+}
+
+export type FunnelQueryStep = {
+  name: string
+  resource: string
+  metric: QueryAggregateSelectItem
+  filters?: FilterExpression
+}
+
+export type FieldRef = string | {
+  field: string
+  label?: string
+  format?: ValueFormat
+}
+
+export type TableViewConfig = {
+  columns?: FieldRef[]
+  pagination?: boolean
+  pageSize?: number
+}
+
+export type KpiCardViewConfig = {
+  title?: string
+  value: {
+    field: string
+    format?: ValueFormat
+    prefix?: string
+    suffix?: string
+  }
+  subtitle?: {
+    text?: string
+    field?: string
+  }
+  comparison?: unknown
+  sparkline?: unknown
+}
+
+export type GaugeCardViewConfig = {
+  title?: string
+  value: {
+    field: string
+    format?: ValueFormat
+    prefix?: string
+    suffix?: string
+  }
+  target?: {
+    value?: number
+    field?: string
+    label?: string
+  }
+  progress?: {
+    valueField: string
+    targetValue?: number
+    targetField?: string
+    format?: ValueFormat
+  }
+  color?: string
+}
+
+export type PivotTableViewConfig = {
+  rows: FieldRef[]
+  columns?: FieldRef[]
+  values: Array<{
+    field: string
+    label?: string
+    format?: ValueFormat
+    aggregation?: 'sum' | 'count' | 'avg' | 'min' | 'max'
+  }>
+}
+
+export type EmptyWidgetConfig = WidgetBaseConfig & {
+  target: 'empty'
+}
+
+export type TableWidgetConfig = WidgetBaseConfig & {
+  target: 'table'
+  table?: TableViewConfig
+  query: QueryConfig
+}
+
+export type ChartDashboardWidgetConfig = WidgetBaseConfig & {
+  target: 'chart'
+  chart: ChartWidgetConfig
+  query: QueryConfig | FunnelQueryConfig
+}
+
+export type KpiCardWidgetConfig = WidgetBaseConfig & {
+  target: 'kpi_card'
+  card: KpiCardViewConfig
+  query: QueryConfig
+}
+
+export type GaugeCardWidgetConfig = WidgetBaseConfig & {
+  target: 'gauge_card'
+  card: GaugeCardViewConfig
+  query: QueryConfig
+}
+
+export type PivotTableWidgetConfig = WidgetBaseConfig & {
+  target: 'pivot_table'
+  pivot: PivotTableViewConfig
+  query: QueryConfig
+}
+
+export type DashboardWidgetConfig =
+  | EmptyWidgetConfig
+  | TableWidgetConfig
+  | ChartDashboardWidgetConfig
+  | KpiCardWidgetConfig
+  | GaugeCardWidgetConfig
+  | PivotTableWidgetConfig
+
 export type DashboardWidgetTableData = {
   kind?: 'table'
   columns: string[]
@@ -108,6 +256,12 @@ export type DashboardWidgetAggregateData = {
   columns: string[]
   rows: Record<string, unknown>[]
   values?: Record<string, unknown>
+  pagination?: {
+    page: number
+    pageSize: number
+    total: number
+    totalPages: number
+  }
 }
 
 export type DashboardWidgetData = DashboardWidgetTableData | DashboardWidgetAggregateData
@@ -130,31 +284,73 @@ export function normalizeDashboardWidgetConfig(config: unknown) {
   }
 
   const normalized: Record<string, unknown> = { ...config }
-  const target = normalizeDashboardWidgetTarget(normalized.target ?? normalized.type)
+  normalizeWidgetLayoutConfig(normalized)
 
-  if (target && normalized.target === undefined) {
-    normalized.target = target
+  if (normalized.query !== undefined) {
+    normalized.query = normalizeQueryConfig(normalized.query)
   }
 
-  if (target === 'kpi_card') {
-    const kpiCardConfig = normalizeKpiCardConfig(normalized)
+  if (normalized.table !== undefined) {
+    normalized.table = normalizeTableConfig(normalized.table)
+  }
 
-    if (kpiCardConfig !== undefined) {
-      normalized.kpi_card = kpiCardConfig
-    }
+  if (normalized.card !== undefined) {
+    normalized.card = normalizeCardConfig(normalized.card)
   }
 
-  if (target === 'gauge_card') {
-    const gaugeCardConfig = normalizeGaugeCardConfig(normalized)
+  if (normalized.pivot !== undefined) {
+    normalized.pivot = normalizePivotConfig(normalized.pivot)
+  }
 
-    if (gaugeCardConfig !== undefined) {
-      normalized.gauge_card = gaugeCardConfig
-    }
+  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 ('query' in widget) {
+    serialized.query = serializeQueryConfigForEditor(widget.query)
+  }
+
+  if ('table' in widget && widget.table !== undefined) {
+    serialized.table = serializeTableConfigForEditor(widget.table)
+  }
+
+  if ('card' in widget && widget.card !== undefined) {
+    serialized.card = serializeCardConfigForEditor(widget.card)
+  }
+
+  if ('pivot' in widget && widget.pivot !== undefined) {
+    serialized.pivot = serializePivotConfigForEditor(widget.pivot)
+  }
+
+  return serialized
+}
+
+export function getFieldRefField(value: FieldRef | undefined) {
+  return typeof value === 'string' ? value : value?.field
+}
+
+export function getFieldRefLabel(value: FieldRef | undefined) {
+  return typeof value === 'string' ? value : value?.label
+}
+
 function normalizeDashboardWidgetTarget(value: unknown): DashboardWidgetTarget | undefined {
   switch (value) {
     case 'empty':
@@ -169,62 +365,153 @@ function normalizeDashboardWidgetTarget(value: unknown): DashboardWidgetTarget |
   }
 }
 
-function normalizeKpiCardConfig(value: Record<string, unknown>) {
-  const config = isRecord(value.kpi_card) ? { ...value.kpi_card } : {}
+function normalizeWidgetLayoutConfig(value: Record<string, unknown>) {
+  if (value.min_width !== undefined) {
+    value.minWidth = value.min_width
+  }
 
-  if (typeof value.valueField === 'string' && config.value_field === undefined) {
-    config.value_field = value.valueField
+  if (value.max_width !== undefined) {
+    value.maxWidth = value.max_width
   }
+}
 
-  if (typeof value.labelField === 'string' && config.label_field === undefined) {
-    config.label_field = value.labelField
+function normalizeQueryConfig(value: unknown): unknown {
+  if (!isRecord(value)) {
+    return value
   }
 
-  if (typeof value.prefix === 'string' && config.prefix === undefined) {
-    config.prefix = value.prefix
+  if (Array.isArray(value.steps)) {
+    return {
+      steps: value.steps.map((step) => normalizeFunnelQueryStep(step)),
+    }
   }
 
-  if (typeof value.suffix === 'string' && config.suffix === undefined) {
-    config.suffix = value.suffix
+  return {
+    ...value,
+    ...(Array.isArray(value.group_by) ? { groupBy: value.group_by } : {}),
+    ...(Array.isArray(value.order_by) ? { orderBy: value.order_by } : {}),
+    ...(value.time_series !== undefined ? { timeSeries: value.time_series } : {}),
+  }
+}
+
+function normalizeFunnelQueryStep(value: unknown) {
+  if (!isRecord(value)) {
+    return value
   }
 
-  return Object.keys(config).length ? config : value.kpi_card
+  return {
+    ...value,
+    ...(typeof value.resource_id === 'string' ? { resource: value.resource_id } : {}),
+  }
 }
 
-function normalizeGaugeCardConfig(value: Record<string, unknown>) {
-  const config = isRecord(value.gauge_card) ? { ...value.gauge_card } : {}
+function normalizeTableConfig(value: unknown) {
+  if (!isRecord(value)) {
+    return value
+  }
 
-  if (typeof value.valueField === 'string' && config.value_field === undefined) {
-    config.value_field = value.valueField
+  return {
+    ...value,
+    ...(value.page_size !== undefined ? { pageSize: value.page_size } : {}),
   }
+}
 
-  if (value.min !== undefined && config.min === undefined) {
-    config.min = value.min
+function normalizeCardConfig(value: unknown): unknown {
+  if (!isRecord(value)) {
+    return value
   }
 
-  if (value.max !== undefined && config.max === undefined) {
-    config.max = value.max
+  const normalized = { ...value }
+
+  if (isRecord(normalized.progress)) {
+    normalized.progress = {
+      ...normalized.progress,
+      ...(normalized.progress.value_field !== undefined ? { valueField: normalized.progress.value_field } : {}),
+      ...(normalized.progress.target_value !== undefined ? { targetValue: normalized.progress.target_value } : {}),
+      ...(normalized.progress.target_field !== undefined ? { targetField: normalized.progress.target_field } : {}),
+    }
   }
 
-  if (typeof value.minField === 'string' && config.min_field === undefined) {
-    config.min_field = value.minField
+  if (isRecord(normalized.comparison)) {
+    normalized.comparison = {
+      ...normalized.comparison,
+      ...(normalized.comparison.positive_is_good !== undefined ? { positiveIsGood: normalized.comparison.positive_is_good } : {}),
+    }
   }
 
-  if (typeof value.maxField === 'string' && config.max_field === undefined) {
-    config.max_field = value.maxField
+  return normalized
+}
+
+function normalizePivotConfig(value: unknown): unknown {
+  return value
+}
+
+function serializeQueryConfigForEditor(value: QueryConfig | FunnelQueryConfig) {
+  if ('steps' in value) {
+    return {
+      steps: value.steps.map((step) => ({
+        ...step,
+        resource_id: step.resource,
+        resource: undefined,
+      })).map((step) => removeUndefinedFields(step)),
+    }
   }
 
-  if (typeof value.suffix === 'string' && config.suffix === undefined) {
-    config.suffix = value.suffix
+  return removeUndefinedFields({
+    ...value,
+    group_by: value.groupBy,
+    groupBy: undefined,
+    order_by: value.orderBy,
+    orderBy: undefined,
+    time_series: value.timeSeries,
+    timeSeries: undefined,
+  })
+}
+
+function serializeTableConfigForEditor(value: TableViewConfig) {
+  return removeUndefinedFields({
+    ...value,
+    page_size: value.pageSize,
+    pageSize: undefined,
+  })
+}
+
+function serializeCardConfigForEditor(value: KpiCardViewConfig | GaugeCardViewConfig) {
+  const serialized: Record<string, unknown> = { ...value }
+
+  if (isRecord(serialized.progress)) {
+    serialized.progress = removeUndefinedFields({
+      ...serialized.progress,
+      value_field: serialized.progress.valueField,
+      valueField: undefined,
+      target_value: serialized.progress.targetValue,
+      targetValue: undefined,
+      target_field: serialized.progress.targetField,
+      targetField: undefined,
+    })
   }
 
-  if (typeof value.color === 'string' && config.color === undefined) {
-    config.color = value.color
+  if (isRecord(serialized.comparison)) {
+    serialized.comparison = removeUndefinedFields({
+      ...serialized.comparison,
+      positive_is_good: serialized.comparison.positiveIsGood,
+      positiveIsGood: undefined,
+    })
   }
 
-  return Object.keys(config).length ? config : value.gauge_card
+  return removeUndefinedFields(serialized)
+}
+
+function serializePivotConfigForEditor(value: PivotTableViewConfig) {
+  return value
+}
+
+function removeUndefinedFields<T extends Record<string, unknown>>(value: T) {
+  return Object.fromEntries(
+    Object.entries(value).filter(([, item]) => item !== undefined),
+  )
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
+function isRecord(value: unknown): value is Record<string, any> {
   return typeof value === 'object' && value !== null
 }

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/skills/adminforth-dashboard/SKILL.md

@@ -119,7 +119,11 @@ 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 `query`, not `data_source`.
+- Use `resource`, not `resource_id`.
+- Use `group_by`, not `groupBy`.
+- Use `order_by`, not `orderBy`.
+- Use `page_size`, not `pageSize`.
+- For funnel charts, use `query.steps` as an ordered array of `{ name, resource, metric, filters }` steps.
+- Use `card` for KPI and gauge widget view config.
+- Use `pivot` for pivot table view config.