@adminforth/dashboard 1.2.0 → 1.4.0

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

@@ -41,6 +41,7 @@ If the user asks how the schema works, how to implement the API, or how to chang
 Use these tools whenever available:
 
 - `dashboard_get_config`
+- `dashboard_set_dashboard_config`
 - `dashboard_add_dashboard_group`
 - `dashboard_set_dashboard_group_config`
 - `dashboard_move_dashboard_group`
@@ -58,6 +59,7 @@ If a dashboard tool is known by name but its argument schema is not loaded, call
 Do not pass fields between dashboard tools by analogy. Use each tool's schema.
 
 - `dashboard_add_dashboard_group` creates a new group. It accepts the dashboard slug only. Never pass `groupId` to this tool.
+- `dashboard_set_dashboard_config` replaces the full dashboard config. Use it when the user explicitly asks to edit the whole dashboard config.
 - `dashboard_add_dashboard_widget` creates a widget inside an existing group. Use it when you already have a `groupId`.
 - `dashboard_set_dashboard_group_config`, `dashboard_move_dashboard_group`, and `dashboard_remove_dashboard_group` operate on an existing group and need `groupId`.
 - `dashboard_set_widget_config`, `dashboard_move_dashboard_widget`, `dashboard_remove_dashboard_widget`, and `dashboard_get_dashboard_widget_data` operate on an existing widget and need `widgetId`.
@@ -113,13 +115,122 @@ For group requests:
 
 If slug is missing, use `default`.
 
+## Dashboard Config Workflow
+
+Use `dashboard_set_dashboard_config` only when the user explicitly asks to edit the whole dashboard root config.
+
+For requests like:
+
+- "update root dashboard config"
+- "replace the whole dashboard config"
+
+do this:
+
+1. Call `dashboard_get_config`.
+2. Modify the returned root config, preserving existing `version`, `groups`, and `widgets` unless the user asked to change them.
+3. Call `dashboard_set_dashboard_config` with the full updated config.
+4. Return a short summary of the root-level fields changed.
+
+Do not use `dashboard_set_dashboard_config` to store reusable widget variables.
+
 ## Widget Config Rules
 
 Use the current schema keys exactly:
 
 - Use `target`, not `type`.
 - Use `label`, not `title`.
-- Use `data_source`, not `dataSource`.
-- Use `resource_id`, not `resourceId`.
+- 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 step-based chart queries, use `query.steps` as an ordered array of `{ name, resource, metric, filters }` steps and add `query.calcs` when derived fields are needed.
+- Use `card` for KPI and gauge widget view config.
+- Use `pivot` for pivot table view config.
+- Use `variables` for reusable static maps or constants at widget level.
+- In `query.calcs`, use `lookup($variables.some.map, row_field, default_number)` to read a numeric value from a variable map by the current row/group field.
+
+## Variables And Lookup Calcs
+
+Widget config can define variables:
+
+```yaml
+variables:
+  token_prices_per_1m:
+    input:
+      gpt-4.1: 2.00
+      gpt-4.1-mini: 0.40
+      gpt-4o-mini: 0.15
+    output:
+      gpt-4.1: 8.00
+      gpt-4.1-mini: 1.60
+      gpt-4o-mini: 0.60
+    cached:
+      gpt-4.1: 0.50
+      gpt-4.1-mini: 0.10
+      gpt-4o-mini: 0.075
+```
+
+Use variables when a calculation needs a static rate table, threshold table, coefficient map, or other reusable constants. In calcs, `lookup($variables.path.to.map, field_name, 0)` returns the value from the map using `field_name` from the current row/group. The third argument is the numeric fallback when the key is missing.
+
+Example widget:
+
+```yaml
+target: chart
+label: Model costs
+size: large
+variables:
+  token_prices_per_1m:
+    input:
+      gpt-4.1: 2.00
+      gpt-4.1-mini: 0.40
+      gpt-4o-mini: 0.15
+    output:
+      gpt-4.1: 8.00
+      gpt-4.1-mini: 1.60
+      gpt-4o-mini: 0.60
+    cached:
+      gpt-4.1: 0.50
+      gpt-4.1-mini: 0.10
+      gpt-4o-mini: 0.075
+
+chart:
+  type: stacked_bar
+  title: LLM costs by model
+  x:
+    field: model
+    label: Model
+  y:
+    - field: input_cost
+      label: Input
+      format: currency
+    - field: output_cost
+      label: Output
+      format: currency
+    - field: cached_cost
+      label: Cached
+      format: currency
+
+query:
+  resource: model_usage
+  select:
+    - field: model
+    - agg: sum
+      field: input_tokens
+      as: input_tokens
+    - agg: sum
+      field: output_tokens
+      as: output_tokens
+    - agg: sum
+      field: cached_tokens
+      as: cached_tokens
+  group_by:
+    - model
+  calcs:
+    - calc: input_tokens / 1000000 * lookup($variables.token_prices_per_1m.input, model, 0)
+      as: input_cost
+    - calc: output_tokens / 1000000 * lookup($variables.token_prices_per_1m.output, model, 0)
+      as: output_cost
+    - calc: cached_tokens / 1000000 * lookup($variables.token_prices_per_1m.cached, model, 0)
+      as: cached_cost
+```

package/custom/widgets/chart/ChartWidget.vue

@@ -26,7 +26,7 @@
       :rows="rows"
       :x-field="xField"
       :y-field="yField"
-      :series-name="chartConfig.seriesName"
+      :series-name="lineSeriesName"
       :color="chartConfig.color"
       :height="chartHeight"
     />
@@ -69,9 +69,10 @@
 
     <StackedBarChart
       v-else-if="chartConfig?.type === 'stacked_bar'"
-      :rows="rows"
+      :rows="stackedBarRows"
       :x-field="xField"
-      :series="stackedBarSeries"
+      :y-field="stackedBarYField"
+      :series-field="stackedBarSeriesField"
       :colors="chartConfig.colors"
       :height="chartHeight"
     />
@@ -98,7 +99,7 @@ import HistogramChart from './histogram/HistogramChart.vue'
 import LineChart from './line/LineChart.vue'
 import PieChart from './pie/PieChart.vue'
 import StackedBarChart from './stacked-bar/StackedBarChart.vue'
-import { formatChartLabel, toFiniteNumber } from './chart.utils.js'
+import { toFiniteNumber } from './chart.utils.js'
 
 const DEFAULT_WIDGET_HEIGHT = 500
 
@@ -128,15 +129,6 @@ const chartData = computed(() => data.value?.data as DashboardWidgetTableData |
 const rows = computed(() => chartData.value?.rows ?? [])
 const columns = computed(() => chartData.value?.columns ?? [])
 const chartConfig = computed(() => normalizeChartWidgetConfig(props.widget.chart))
-const aggregateGroupField = computed(() => {
-  const dataSource = props.widget.dataSource
-
-  if (dataSource?.type !== 'aggregate' || !dataSource.groupBy) {
-    return undefined
-  }
-
-  return dataSource.groupBy.field
-})
 
 function resolveChartDimensionField(field: string | undefined, fallbackField: string | undefined) {
   const resolvedField = field ?? fallbackField
@@ -149,41 +141,39 @@ function resolveChartDimensionField(field: string | undefined, fallbackField: st
     return resolvedField
   }
 
-  if (
-    aggregateGroupField.value
-    && resolvedField === aggregateGroupField.value
-    && columns.value.includes('group')
-  ) {
-    return 'group'
-  }
-
   return resolvedField
 }
 
-const xField = computed(() => resolveChartDimensionField(chartConfig.value?.xField, columns.value[0]))
-const yField = computed(() => chartConfig.value?.yField || columns.value[1])
-const labelField = computed(() => resolveChartDimensionField(chartConfig.value?.labelField, columns.value[0]))
-const valueField = computed(() => chartConfig.value?.valueField || columns.value[1])
-const pieRows = computed(() => {
-  if (chartConfig.value?.valueField) {
+const firstYField = computed(() => {
+  const y = chartConfig.value?.y
+  return Array.isArray(y) ? y[0]?.field : y?.field
+})
+const xField = computed(() => resolveChartDimensionField(chartConfig.value?.x?.field, columns.value[0]))
+const yField = computed(() => firstYField.value || columns.value[1])
+const labelField = computed(() => resolveChartDimensionField(chartConfig.value?.label?.field, columns.value[0] || 'name'))
+const valueField = computed(() => chartConfig.value?.value?.field || columns.value[1] || 'value')
+const pieRows = computed(() => rows.value)
+const pieLabelField = computed(() => labelField.value)
+const pieValueField = computed(() => valueField.value)
+const stackedBarYItems = computed(() => {
+  const y = chartConfig.value?.y
+  return Array.isArray(y) ? y : []
+})
+const stackedBarRows = computed(() => {
+  if (chartConfig.value?.type !== 'stacked_bar' || !stackedBarYItems.value.length) {
     return rows.value
   }
 
-  const groupedRows = new Map<string, { label: string, value: number }>()
-
-  for (const row of rows.value) {
-    const label = formatChartLabel(row[labelField.value])
-    const item = groupedRows.get(label) ?? { label, value: 0 }
-    item.value += 1
-    groupedRows.set(label, item)
-  }
-
-  return Array.from(groupedRows.values())
+  return rows.value.flatMap((row) => stackedBarYItems.value.map((item) => ({
+    [xField.value]: row[xField.value],
+    __series: item.label ?? item.field,
+    __value: row[item.field],
+  })))
 })
-const pieLabelField = computed(() => chartConfig.value?.valueField ? labelField.value : 'label')
-const pieValueField = computed(() => chartConfig.value?.valueField ? valueField.value : 'value')
 const barRows = computed(() => {
-  const bucketField = chartConfig.value?.bucketField
+  const bucketField = chartConfig.value?.type === 'histogram'
+    ? chartConfig.value.x?.field
+    : undefined
 
   if (!bucketField) {
     return rows.value
@@ -200,19 +190,14 @@ const barRows = computed(() => {
     }).length,
   }))
 })
-const barLabelField = computed(() => chartConfig.value?.bucketField ? 'label' : labelField.value)
-const barValueField = computed(() => chartConfig.value?.bucketField ? 'count' : valueField.value)
-const stackedBarSeries = computed(() => {
-  if (chartConfig.value?.series?.length) {
-    return chartConfig.value.series
-  }
-
-  return columns.value
-    .filter((column) => column !== xField.value)
-    .map((column) => ({
-      name: column,
-      field: column,
-    }))
+const barLabelField = computed(() => chartConfig.value?.type === 'histogram' && chartConfig.value.buckets ? 'label' : xField.value)
+const barValueField = computed(() => chartConfig.value?.type === 'histogram' && chartConfig.value.buckets ? 'count' : yField.value)
+const seriesField = computed(() => chartConfig.value?.series?.field || columns.value[2] || '')
+const stackedBarYField = computed(() => stackedBarYItems.value.length ? '__value' : yField.value)
+const stackedBarSeriesField = computed(() => stackedBarYItems.value.length ? '__series' : seriesField.value)
+const lineSeriesName = computed(() => {
+  const y = chartConfig.value?.y
+  return Array.isArray(y) ? y[0]?.label : undefined
 })
 
 const chartHeight = computed(() => {

package/custom/widgets/chart/bar/BarChart.vue

@@ -83,7 +83,14 @@
 <script setup lang="ts">
 import { computed } from 'vue'
 import { useElementSize } from '../../../composables/useElementSize.js'
-import { CHART_COLORS, formatChartAxisLabel, formatChartLabel, formatChartValue, toFiniteNumber } from '../chart.utils.js'
+import {
+  CHART_COLORS,
+  formatChartAxisLabel,
+  formatChartLabel,
+  formatChartValue,
+  getChartYAxisWidth,
+  toFiniteNumber,
+} from '../chart.utils.js'
 
 const props = withDefaults(defineProps<{
   rows: Record<string, unknown>[]
@@ -97,12 +104,6 @@ const props = withDefaults(defineProps<{
 
 const { el: rootEl, width: rootWidth, height: rootHeight } = useElementSize<HTMLDivElement>()
 
-const padding = {
-  top: 20,
-  right: 6,
-  bottom: 34,
-  left: 38,
-}
 const chartWidth = computed(() => Math.max(rootWidth.value, 1))
 const chartHeight = computed(() => {
   if (rootHeight.value > 0) {
@@ -115,8 +116,15 @@ const chartHeight = computed(() => {
 const chartColor = computed(() => props.color || CHART_COLORS[0])
 const values = computed(() => props.rows.map((row) => toFiniteNumber(row[props.valueField])))
 const maxValue = computed(() => Math.max(...values.value, 1))
-const innerWidth = computed(() => Math.max(chartWidth.value - padding.left - padding.right, 1))
-const innerHeight = computed(() => Math.max(chartHeight.value - padding.top - padding.bottom, 1))
+const yTickValues = computed(() => [maxValue.value, maxValue.value * 0.5, 0])
+const padding = computed(() => ({
+  top: 20,
+  right: 6,
+  bottom: 34,
+  left: getChartYAxisWidth(yTickValues.value, chartWidth.value),
+}))
+const innerWidth = computed(() => Math.max(chartWidth.value - padding.value.left - padding.value.right, 1))
+const innerHeight = computed(() => Math.max(chartHeight.value - padding.value.top - padding.value.bottom, 1))
 const barGap = 12
 const barWidth = computed(() => {
   const count = Math.max(props.rows.length, 1)
@@ -126,7 +134,7 @@ const totalChartWidth = computed(() => {
   const count = Math.max(props.rows.length, 1)
   return count * barWidth.value + (count - 1) * barGap
 })
-const chartStartX = computed(() => padding.left + Math.max((innerWidth.value - totalChartWidth.value) / 2, 0))
+const chartStartX = computed(() => padding.value.left + Math.max((innerWidth.value - totalChartWidth.value) / 2, 0))
 const visibleLabelIndexes = computed(() => {
   const count = props.rows.length
   const approxLabelWidth = 52
@@ -155,13 +163,13 @@ const bars = computed(() => props.rows.map((row, index) => {
     axisLabel: formatChartAxisLabel(row[props.labelField]),
     value,
     x: chartStartX.value + index * (barWidth.value + barGap),
-    y: padding.top + innerHeight.value - height,
+    y: padding.value.top + innerHeight.value - height,
     height,
   }
 }))
 
 const yTicks = computed(() => [0, 0.5, 1].map((ratio) => ({
   value: maxValue.value * (1 - ratio),
-  y: padding.top + innerHeight.value * ratio,
+  y: padding.value.top + innerHeight.value * ratio,
 })))
 </script>

package/custom/widgets/chart/chart.types.ts

@@ -1,3 +1,5 @@
+import type { ValueFormat } from '../../model/dashboard.types.js'
+
 export type ChartWidgetType =
   | 'line'
   | 'pie'
@@ -12,81 +14,39 @@ export type ChartWidgetBucketConfig = {
   max?: number
 }
 
+export type ChartFieldRef = {
+  field: string
+  label?: string
+  format?: ValueFormat
+}
+
 export type ChartWidgetSeriesConfig = {
-  name: string
   field: string
+  label?: string
   color?: string
 }
 
 export type ChartWidgetConfig = {
   type: ChartWidgetType
   title?: string
-  x_field?: string
-  y_field?: string
-  label_field?: string
-  value_field?: string
-  bucket_field?: string
+  x?: ChartFieldRef
+  y?: ChartFieldRef | ChartFieldRef[]
+  label?: ChartFieldRef
+  value?: ChartFieldRef
   buckets?: ChartWidgetBucketConfig[]
-  series?: ChartWidgetSeriesConfig[]
-  series_name?: string
+  series?: ChartWidgetSeriesConfig
   color?: string
   colors?: string[]
 }
 
-export type NormalizedChartWidgetConfig = {
-  type: ChartWidgetType
-  title?: string
-  xField?: string
-  yField?: string
-  labelField?: string
-  valueField?: string
-  bucketField?: string
-  buckets?: ChartWidgetBucketConfig[]
-  series?: ChartWidgetSeriesConfig[]
-  seriesName?: string
-  color?: string
-  colors?: string[]
-}
+export type NormalizedChartWidgetConfig = ChartWidgetConfig
 
 export function normalizeChartWidgetConfig(value: unknown): NormalizedChartWidgetConfig | undefined {
-  const config = asChartWidgetConfigRecord(value)
-
-  if (!config) {
+  if (!isRecord(value) || !normalizeChartWidgetType(value.type)) {
     return undefined
   }
 
-  const type = normalizeChartWidgetType(config.type)
-
-  if (!type) {
-    return undefined
-  }
-
-  const xField = getStringField(config, 'x_field')
-  const yField = getStringField(config, 'y_field')
-  const labelField = getStringField(config, 'label_field')
-  const valueField = getStringField(config, 'value_field')
-  const bucketField = getStringField(config, 'bucket_field')
-  const seriesName = getStringField(config, 'series_name')
-  const title = getStringField(config, 'title')
-  const color = getStringField(config, 'color')
-  const colors = Array.isArray(config.colors) ? config.colors as string[] : undefined
-  const buckets = Array.isArray(config.buckets) ? config.buckets as ChartWidgetBucketConfig[] : undefined
-  const series = Array.isArray(config.series) ? config.series as ChartWidgetSeriesConfig[] : undefined
-
-  return {
-    type,
-    ...(title !== undefined ? { title } : {}),
-    ...(xField !== undefined ? { xField } : {}),
-    ...(yField !== undefined ? { yField } : {}),
-    ...(labelField !== undefined ? { labelField } : {}),
-    ...(valueField !== undefined ? { valueField } : {}),
-    ...(bucketField !== undefined ? { bucketField } : {}),
-    ...(buckets !== undefined ? { buckets } : {}),
-    ...(series !== undefined ? { series } : {}),
-    ...(seriesName !== undefined ? { seriesName } : {}),
-    ...(color !== undefined ? { color } : {}),
-    ...(colors !== undefined ? { colors } : {}),
-  }
+  return value as ChartWidgetConfig
 }
 
 function normalizeChartWidgetType(value: unknown): ChartWidgetType | undefined {
@@ -103,15 +63,6 @@ function normalizeChartWidgetType(value: unknown): ChartWidgetType | undefined {
   }
 }
 
-function asChartWidgetConfigRecord(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> {
   return typeof value === 'object' && value !== null
 }

package/custom/widgets/chart/chart.utils.ts

@@ -18,6 +18,17 @@ export function formatChartValue(value: number, options: Intl.NumberFormatOption
   return new Intl.NumberFormat(undefined, options).format(value)
 }
 
+export function getChartYAxisWidth(values: number[], chartWidth: number) {
+  const maxLabelLength = Math.max(
+    ...values.map((value) => formatChartValue(value).length),
+    1,
+  )
+  const estimatedWidth = Math.ceil(maxLabelLength * 6.5) + 18
+  const responsiveMaxWidth = Math.max(Math.floor(chartWidth * 0.36), 38)
+
+  return Math.min(Math.max(estimatedWidth, 38), responsiveMaxWidth, 120)
+}
+
 export function formatChartLabel(value: unknown) {
   if (typeof value !== 'string') {
     return String(value)

package/custom/widgets/chart/funnel/FunnelChart.vue

@@ -48,9 +48,11 @@ const funnelRows = computed(() => {
     groupedRows.set(label, item)
   }
 
-  return Array.from(groupedRows.values())
-    .filter((row) => row.value > 0)
-    .sort((left, right) => right.value - left.value)
+  const rows = Array.from(groupedRows.values()).filter((row) => row.value > 0)
+
+  return props.labelField === 'name'
+    ? rows
+    : rows.sort((left, right) => right.value - left.value)
 })
 
 const maxValue = computed(() => {
@@ -194,4 +196,4 @@ const segments = computed(() => funnelRows.value.map((row, index) => {
       </div>
     </div>
   </div>
-</template>
+</template>

package/custom/widgets/chart/line/LineChart.vue

@@ -85,7 +85,14 @@
 <script setup lang="ts">
 import { computed } from 'vue'
 import { useElementSize } from '../../../composables/useElementSize.js'
-import { CHART_COLORS, formatChartAxisLabel, formatChartLabel, formatChartValue, toFiniteNumber } from '../chart.utils.js'
+import {
+  CHART_COLORS,
+  formatChartAxisLabel,
+  formatChartLabel,
+  formatChartValue,
+  getChartYAxisWidth,
+  toFiniteNumber,
+} from '../chart.utils.js'
 
 const props = withDefaults(defineProps<{
   rows: Record<string, unknown>[]
@@ -100,12 +107,6 @@ const props = withDefaults(defineProps<{
 
 const { el: rootEl, width: rootWidth, height: rootHeight } = useElementSize<HTMLDivElement>()
 
-const padding = {
-  top: 12,
-  right: 6,
-  bottom: 24,
-  left: 38,
-}
 const chartWidth = computed(() => Math.max(rootWidth.value, 1))
 const chartHeight = computed(() => {
   if (rootHeight.value > 0) {
@@ -118,14 +119,21 @@ const chartHeight = computed(() => {
 const chartColor = computed(() => props.color || CHART_COLORS[0])
 const values = computed(() => props.rows.map((row) => toFiniteNumber(row[props.yField])))
 const maxValue = computed(() => Math.max(...values.value, 1))
-const innerWidth = computed(() => Math.max(chartWidth.value - padding.left - padding.right, 1))
-const innerHeight = computed(() => Math.max(chartHeight.value - padding.top - padding.bottom, 1))
+const yTickValues = computed(() => [maxValue.value, maxValue.value * 0.5, 0])
+const padding = computed(() => ({
+  top: 12,
+  right: 6,
+  bottom: 24,
+  left: getChartYAxisWidth(yTickValues.value, chartWidth.value),
+}))
+const innerWidth = computed(() => Math.max(chartWidth.value - padding.value.left - padding.value.right, 1))
+const innerHeight = computed(() => Math.max(chartHeight.value - padding.value.top - padding.value.bottom, 1))
 
 const points = computed(() => {
   if (props.rows.length === 1) {
     return [{
-      x: padding.left + innerWidth.value / 2,
-      y: padding.top + innerHeight.value - (values.value[0] / maxValue.value) * innerHeight.value,
+      x: padding.value.left + innerWidth.value / 2,
+      y: padding.value.top + innerHeight.value - (values.value[0] / maxValue.value) * innerHeight.value,
       label: formatChartLabel(props.rows[0][props.xField]),
       axisLabel: formatChartAxisLabel(props.rows[0][props.xField]),
       value: values.value[0],
@@ -133,8 +141,8 @@ const points = computed(() => {
   }
 
   return props.rows.map((row, index) => ({
-    x: padding.left + (index / (props.rows.length - 1)) * innerWidth.value,
-    y: padding.top + innerHeight.value - (values.value[index] / maxValue.value) * innerHeight.value,
+    x: padding.value.left + (index / (props.rows.length - 1)) * innerWidth.value,
+    y: padding.value.top + innerHeight.value - (values.value[index] / maxValue.value) * innerHeight.value,
     label: formatChartLabel(row[props.xField]),
     axisLabel: formatChartAxisLabel(row[props.xField]),
     value: values.value[index],
@@ -152,12 +160,12 @@ const fillPath = computed(() => {
 
   const first = points.value[0]
   const last = points.value[points.value.length - 1]
-  return `${linePath.value} L ${last.x} ${padding.top + innerHeight.value} L ${first.x} ${padding.top + innerHeight.value} Z`
+  return `${linePath.value} L ${last.x} ${padding.value.top + innerHeight.value} L ${first.x} ${padding.value.top + innerHeight.value} Z`
 })
 
 const yTicks = computed(() => [0, 0.5, 1].map((ratio) => ({
   value: maxValue.value * (1 - ratio),
-  y: padding.top + innerHeight.value * ratio,
+  y: padding.value.top + innerHeight.value * ratio,
 })))
 
 const xLabels = computed(() => {