@adminforth/dashboard 1.11.2 → 1.12.0

package/README.md

@@ -39,7 +39,7 @@ Each widget has common fields:
 | Widget target | Config field | Main settings | Data usage |
 | --- | --- | --- | --- |
 | `table` | `table` | `pagination`, `page_size`, `columns` | Uses `query` to display raw or aggregate rows. |
-| `chart` | `chart` | `type`, `x`, `y`, `label`, `value`, `series`, `buckets`, `color`, `colors` | Uses the same `query` shape for every chart type. Multi-resource charts use `query.source: steps`. |
+| `chart` | `chart` | `type`, `x`, `y`, `label`, `value`, `series`, `buckets`, `color`, `colors` | Uses the same `query` shape for most chart types. Multi-resource charts use `query.source: steps`; add `query.bucket` for shared numeric buckets across resources. |
 | `kpi_card` | `card` | `value`, `subtitle`, `comparison`, `sparkline` | Reads the first returned query row. |
 | `gauge_card` | `card` | `value`, `target`, `progress`, `color` | Reads the first returned query row. |
 | `pivot_table` | `pivot` | `rows`, `columns`, `values` | Uses query rows to build a pivot table. |
@@ -53,7 +53,7 @@ Chart widget types:
 | `bar` | Uses `x` and `y`. |
 | `stacked_bar` | Uses `x`, `y`, and `series`. |
 | `funnel` | Uses `label`, `value`, and optional `colors`. Data comes from the same `query` shapes as every other chart. |
-| `histogram` | Uses `x`, `y`, and optional `buckets`. |
+| `histogram` | Uses `x`, `y`, and optional `buckets`. Current histogram runtime support is single-resource only: provide raw rows for the numeric field and let `chart.buckets` derive counts on the frontend. For multi-resource bucket distributions, use `stacked_bar` with `query.source: steps` and `query.bucket`. |
 
 ## Query Shape
 
@@ -89,6 +89,8 @@ type QueryConfig = {
   formatting?: Record<string, JsonValue>
 }
 
+`source: 'steps'` returns one aggregate row per step by default. Each step supports aggregate `select` items plus optional `filters`; it does not support per-step `field` selects, `calc` selects, or `group_by`. Add `query.bucket` when multiple resources need the same numeric buckets, for example a stacked bar distribution by price range.
+
 type DashboardFilter =
   | { and: DashboardFilter[] }
   | { or: DashboardFilter[] }
@@ -155,6 +157,45 @@ query:
           as: value
 ```
 
+Bucketed multi-resource queries use `query.bucket`. The dashboard runs each step once per bucket and returns rows with `label`, `name`, `resource`, and the selected aggregate aliases:
+
+```yaml
+target: chart
+label: Cars by price range and database
+chart:
+  type: stacked_bar
+  title: Cars by price range and database
+  x:
+    field: label
+  y:
+    field: count
+  series:
+    field: name
+query:
+  source: steps
+  bucket:
+    field: price
+    buckets:
+      - label: Budget
+        max: 3500
+      - label: Mid-range
+        min: 3500
+        max: 7000
+      - label: Premium
+        min: 7000
+  steps:
+    - name: SQLite
+      resource: cars_sl
+      select:
+        - agg: count
+          as: count
+    - name: MySQL
+      resource: cars_mysql
+      select:
+        - agg: count
+          as: count
+```
+
 Cost calculation example:
 
 ```yaml

package/custom/api/dashboardApi.ts

@@ -62,20 +62,82 @@ export class DashboardApiError extends Error {
 }
 
 function normalizeValidationErrors(response: any): DashboardWidgetConfigValidationError[] {
-  if (Array.isArray(response?.validationErrors)) {
-    return response.validationErrors
+  const errors = Array.isArray(response?.validationErrors)
+    ? response.validationErrors
+    : Array.isArray(response?.details)
+      ? response.details.map((detail: any) => ({
+        field: getValidationErrorField(detail),
+        message: String(detail.message || 'Invalid value'),
+      }))
+      : []
+
+  return simplifyValidationErrors(errors)
+}
+
+function getValidationErrorField(detail: any) {
+  return Array.isArray(detail.instancePath)
+    ? detail.instancePath.join('.')
+    : String(detail.instancePath || detail.path || 'config').replace(/^\//, '').replaceAll('/', '.')
+}
+
+function simplifyValidationErrors(errors: DashboardWidgetConfigValidationError[]) {
+  const collapsed = new Map<string, DashboardWidgetConfigValidationError>()
+
+  for (const error of errors) {
+    const selectItemMatch = error.field.match(/^config\.query\.select\.(\d+)$/)
+
+    if (selectItemMatch) {
+      const field = error.field
+      collapsed.set(field, {
+        field,
+        message: 'must be a valid select item: field, aggregate, or calc',
+      })
+      continue
+    }
+
+    if (isUnionBranchNoise(error)) {
+      continue
+    }
+
+    const key = `${error.field}:${error.message}`
+    collapsed.set(key, error)
   }
 
-  if (Array.isArray(response?.details)) {
-    return response.details.map((detail: any) => ({
-      field: Array.isArray(detail.instancePath)
-        ? detail.instancePath.join('.')
-        : String(detail.instancePath || detail.path || 'config').replace(/^\//, '').replaceAll('/', '.'),
-      message: String(detail.message || 'Invalid value'),
-    }))
+  const simplifiedErrors = Array.from(collapsed.values())
+
+  if (simplifiedErrors.length) {
+    return simplifiedErrors
+  }
+
+  return dedupeValidationErrors(errors).filter((error) => error.message !== 'must match a schema in anyOf').slice(0, 5)
+}
+
+function dedupeValidationErrors(errors: DashboardWidgetConfigValidationError[]) {
+  const deduped = new Map<string, DashboardWidgetConfigValidationError>()
+
+  for (const error of errors) {
+    deduped.set(`${error.field}:${error.message}`, error)
+  }
+
+  return Array.from(deduped.values())
+}
+
+function isUnionBranchNoise(error: DashboardWidgetConfigValidationError) {
+  if (error.field !== 'config') {
+    return false
   }
 
-  return []
+  return error.message === 'must NOT have additional properties'
+    || error.message === 'must match a schema in anyOf'
+    || error.message === 'must match exactly one schema in oneOf'
+    || error.message === 'must have required property \'chart\''
+    || error.message === 'must have required property "chart"'
+    || error.message === 'must have required property \'card\''
+    || error.message === 'must have required property "card"'
+    || error.message === 'must have required property \'table\''
+    || error.message === 'must have required property "table"'
+    || error.message === 'must have required property \'pivot\''
+    || error.message === 'must have required property "pivot"'
 }
 
 async function parseDashboardResponse(rawResponse: Response) {

package/custom/model/dashboard.types.ts

@@ -140,6 +140,11 @@ export type ResourceQueryConfig = {
   formatting?: Record<string, JsonValue>
 }
 
+export type QueryBucketConfig = {
+  field: string
+  buckets: Array<{ label: string, min?: number, max?: number }>
+}
+
 export type StepsQueryStepConfig = {
   name: string
   resource: string
@@ -150,6 +155,7 @@ export type StepsQueryStepConfig = {
 export type StepsQueryConfig = {
   source: 'steps'
   steps: StepsQueryStepConfig[]
+  bucket?: QueryBucketConfig
   calcs?: QueryCalcSelectItem[]
   order_by?: QueryOrderByItem[]
   limit?: number

package/custom/runtime/DashboardGroup.vue

@@ -14,91 +14,36 @@
         v-if="isAdmin"
         class="absolute right-3 top-3 flex gap-1 opacity-0 transition-opacity group-hover/dashboard:opacity-100"
       >
-        <button
-          type="button"
-          class="flex h-8 w-8 items-center justify-center rounded-lg border border-lightListViewButtonBorder bg-lightListViewButtonBackground text-lightListViewButtonText shadow-sm hover:bg-lightListViewButtonBackgroundHover hover:text-lightListViewButtonTextHover dark:border-darkListViewButtonBorder dark:bg-darkListViewButtonBackground dark:text-darkListViewButtonText dark:hover:bg-darkListViewButtonBackgroundHover dark:hover:text-darkListViewButtonTextHover"
+        <DashboardToolbarButton
           title="Edit JSON"
           @click="emit('edit-group', group)"
         >
-          <svg
-            class="h-4 w-4"
-            viewBox="0 0 24 24"
-            fill="none"
-            stroke="currentColor"
-            stroke-width="1.8"
-            stroke-linecap="round"
-            stroke-linejoin="round"
-            aria-hidden="true"
-          >
-            <path d="M15.5 7.5a3 3 0 1 1 1 2.2l-6.8 6.8H7.5v2.2H5.3v2.2H2.8v-2.5l7.5-7.5a5.5 5.5 0 1 1 5.2 1.6" />
-          </svg>
-        </button>
+          <DashboardToolbarIcon name="edit" />
+        </DashboardToolbarButton>
 
-        <button
-          type="button"
-          class="flex h-8 w-8 items-center justify-center rounded-lg border border-lightListViewButtonBorder bg-lightListViewButtonBackground text-lightListViewButtonText shadow-sm hover:bg-lightListViewButtonBackgroundHover hover:text-lightListViewButtonTextHover disabled:opacity-45 dark:border-darkListViewButtonBorder dark:bg-darkListViewButtonBackground dark:text-darkListViewButtonText dark:hover:bg-darkListViewButtonBackgroundHover dark:hover:text-darkListViewButtonTextHover"
+        <DashboardToolbarButton
           title="Move up"
           :disabled="!canMoveUp"
           @click="emit('move-up')"
         >
-          <svg
-            class="h-4 w-4"
-            viewBox="0 0 24 24"
-            fill="none"
-            stroke="currentColor"
-            stroke-width="2"
-            stroke-linecap="round"
-            stroke-linejoin="round"
-            aria-hidden="true"
-          >
-            <path d="m18 15-6-6-6 6" />
-          </svg>
-        </button>
+          <DashboardToolbarIcon name="move-up" />
+        </DashboardToolbarButton>
 
-        <button
-          type="button"
-          class="flex h-8 w-8 items-center justify-center rounded-lg border border-lightListViewButtonBorder bg-lightListViewButtonBackground text-lightListViewButtonText shadow-sm hover:bg-lightListViewButtonBackgroundHover hover:text-lightListViewButtonTextHover disabled:opacity-45 dark:border-darkListViewButtonBorder dark:bg-darkListViewButtonBackground dark:text-darkListViewButtonText dark:hover:bg-darkListViewButtonBackgroundHover dark:hover:text-darkListViewButtonTextHover"
+        <DashboardToolbarButton
           title="Move down"
           :disabled="!canMoveDown"
           @click="emit('move-down')"
         >
-          <svg
-            class="h-4 w-4"
-            viewBox="0 0 24 24"
-            fill="none"
-            stroke="currentColor"
-            stroke-width="2"
-            stroke-linecap="round"
-            stroke-linejoin="round"
-            aria-hidden="true"
-          >
-            <path d="m6 9 6 6 6-6" />
-          </svg>
-        </button>
+          <DashboardToolbarIcon name="move-down" />
+        </DashboardToolbarButton>
 
-        <button
-          type="button"
-          class="flex h-8 w-8 items-center justify-center rounded-lg border border-lightInputErrorColor/30 bg-lightSecondary text-lightInputErrorColor shadow-sm hover:bg-lightListViewButtonBackgroundHover dark:bg-darkSecondary dark:hover:bg-darkListViewButtonBackgroundHover"
+        <DashboardToolbarButton
           title="Remove"
+          variant="danger"
           @click="emit('remove-group')"
         >
-          <svg
-            class="h-4 w-4"
-            viewBox="0 0 24 24"
-            fill="none"
-            stroke="currentColor"
-            stroke-width="2"
-            stroke-linecap="round"
-            stroke-linejoin="round"
-            aria-hidden="true"
-          >
-            <path d="M3 6h18" />
-            <path d="M8 6V4h8v2" />
-            <path d="M19 6l-1 14H6L5 6" />
-            <path d="M10 11v5" />
-            <path d="M14 11v5" />
-          </svg>
-        </button>
+          <DashboardToolbarIcon name="remove" />
+        </DashboardToolbarButton>
       </div>
     </header>
 
@@ -158,6 +103,8 @@
 
 <script setup lang="ts">
 import { Button } from '@/afcl'
+import DashboardToolbarButton from './DashboardToolbarButton.vue'
+import DashboardToolbarIcon from './DashboardToolbarIcon.vue'
 import WidgetRenderer from './WidgetRenderer.vue'
 import WidgetShell from './WidgetShell.vue'
 import type { DashboardGroupConfig, DashboardWidgetConfig } from '../model/dashboard.types.js'

package/custom/runtime/DashboardToolbarButton.vue

@@ -0,0 +1,32 @@
+<template>
+  <button
+    type="button"
+    class="flex h-8 w-8 items-center justify-center rounded-lg border shadow-sm"
+    :class="buttonClass"
+    :title="title"
+    :disabled="disabled"
+  >
+    <slot />
+  </button>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue'
+
+const props = withDefaults(defineProps<{
+  title: string
+  disabled?: boolean
+  variant?: 'default' | 'danger'
+}>(), {
+  disabled: false,
+  variant: 'default',
+})
+
+const buttonClass = computed(() => {
+  if (props.variant === 'danger') {
+    return 'border-lightInputErrorColor/30 bg-lightSecondary text-lightInputErrorColor hover:bg-lightListViewButtonBackgroundHover dark:bg-darkSecondary dark:hover:bg-darkListViewButtonBackgroundHover'
+  }
+
+  return 'border-lightListViewButtonBorder bg-lightListViewButtonBackground text-lightListViewButtonText hover:bg-lightListViewButtonBackgroundHover hover:text-lightListViewButtonTextHover disabled:opacity-45 dark:border-darkListViewButtonBorder dark:bg-darkListViewButtonBackground dark:text-darkListViewButtonText dark:hover:bg-darkListViewButtonBackgroundHover dark:hover:text-darkListViewButtonTextHover'
+})
+</script>

package/custom/runtime/DashboardToolbarIcon.vue

@@ -0,0 +1,52 @@
+<template>
+  <svg
+    v-if="name === 'edit'"
+    xmlns="http://www.w3.org/2000/svg"
+    width="16"
+    height="16"
+    viewBox="0 0 90 90"
+    fill="none"
+    aria-hidden="true"
+  >
+    <g transform="translate(90 0) scale(-1 1)">
+      <path
+        fill="currentColor"
+        d="M69.243 90c-5.389 0-10.67-2.107-14.643-6.081-5.433-5.432-7.391-13.514-5.115-20.831L26.912 40.515c-7.313 2.276-15.397.32-20.832-5.114C.147 29.468-1.625 20.617 1.566 12.852l.846-2.059 12.493 12.493c2.311 2.31 6.07 2.311 8.381 0 2.31-2.311 2.31-6.071 0-8.381L10.794 2.413l2.059-.846c7.766-3.191 16.616-1.418 22.549 4.514 5.433 5.433 7.39 13.516 5.114 20.831l22.572 22.573c7.314-2.278 15.398-.32 20.832 5.114 5.934 5.933 7.704 14.784 4.514 22.549l-.847 2.059-12.492-12.493c-1.113-1.113-2.601-1.726-4.191-1.726s-3.077.613-4.191 1.726c-2.31 2.311-2.31 6.071 0 8.381l12.493 12.492-2.06.847C74.582 89.487 71.899 89.999 69.243 90zM27.692 37.1l25.206 25.207-.322.887c-2.345 6.469-.728 13.779 4.119 18.626 4.538 4.538 11.069 6.235 17.152 4.603l-9.232-9.232c-3.466-3.467-3.466-9.109 0-12.576 3.466-3.468 9.109-3.468 12.576 0l9.232 9.232c1.633-6.083-.064-12.615-4.602-17.153-4.847-4.847-12.161-6.464-18.627-4.118l-.887.322L37.101 27.692l.322-.887c2.345-6.469.729-13.78-4.118-18.627-4.539-4.538-11.07-6.235-17.152-4.603l9.232 9.232c3.467 3.467 3.467 9.109 0 12.576s-9.109 3.468-12.576 0l-9.233-9.232c-1.634 6.083.064 12.614 4.602 17.153 4.848 4.848 12.16 6.464 18.628 4.118l.886-.322z"
+      />
+    </g>
+  </svg>
+
+  <svg
+    v-else
+    class="h-4 w-4"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    stroke-width="2"
+    stroke-linecap="round"
+    stroke-linejoin="round"
+    aria-hidden="true"
+  >
+    <path
+      v-if="name === 'move-up'"
+      d="m18 15-6-6-6 6"
+    />
+    <path
+      v-else-if="name === 'move-down'"
+      d="m6 9 6 6 6-6"
+    />
+    <template v-else>
+      <path d="M3 6h18" />
+      <path d="M8 6V4h8v2" />
+      <path d="M19 6l-1 14H6L5 6" />
+      <path d="M10 11v5" />
+      <path d="M14 11v5" />
+    </template>
+  </svg>
+</template>
+
+<script setup lang="ts">
+defineProps<{
+  name: 'edit' | 'move-up' | 'move-down' | 'remove'
+}>()
+</script>

package/custom/runtime/WidgetShell.vue

@@ -10,91 +10,36 @@
       v-if="isAdmin"
       class="absolute right-2 top-2 flex gap-1 opacity-0 transition-opacity group-hover:opacity-100"
     >
-      <button
-        type="button"
-        class="flex h-8 w-8 items-center justify-center rounded-lg border border-lightListViewButtonBorder bg-lightListViewButtonBackground text-lightListViewButtonText shadow-sm hover:bg-lightListViewButtonBackgroundHover hover:text-lightListViewButtonTextHover dark:border-darkListViewButtonBorder dark:bg-darkListViewButtonBackground dark:text-darkListViewButtonText dark:hover:bg-darkListViewButtonBackgroundHover dark:hover:text-darkListViewButtonTextHover"
+      <DashboardToolbarButton
         title="Edit JSON"
         @click="emit('edit')"
       >
-        <svg
-          class="h-4 w-4"
-          viewBox="0 0 24 24"
-          fill="none"
-          stroke="currentColor"
-          stroke-width="1.8"
-          stroke-linecap="round"
-          stroke-linejoin="round"
-          aria-hidden="true"
-        >
-          <path d="M15.5 7.5a3 3 0 1 1 1 2.2l-6.8 6.8H7.5v2.2H5.3v2.2H2.8v-2.5l7.5-7.5a5.5 5.5 0 1 1 5.2 1.6" />
-        </svg>
-      </button>
+        <DashboardToolbarIcon name="edit" />
+      </DashboardToolbarButton>
 
-      <button
-        type="button"
-        class="flex h-8 w-8 items-center justify-center rounded-lg border border-lightListViewButtonBorder bg-lightListViewButtonBackground text-lightListViewButtonText shadow-sm hover:bg-lightListViewButtonBackgroundHover hover:text-lightListViewButtonTextHover disabled:opacity-45 dark:border-darkListViewButtonBorder dark:bg-darkListViewButtonBackground dark:text-darkListViewButtonText dark:hover:bg-darkListViewButtonBackgroundHover dark:hover:text-darkListViewButtonTextHover"
+      <DashboardToolbarButton
         title="Move up"
         :disabled="!canMoveUp"
         @click="emit('move-up')"
       >
-        <svg
-          class="h-4 w-4"
-          viewBox="0 0 24 24"
-          fill="none"
-          stroke="currentColor"
-          stroke-width="2"
-          stroke-linecap="round"
-          stroke-linejoin="round"
-          aria-hidden="true"
-        >
-          <path d="m18 15-6-6-6 6" />
-        </svg>
-      </button>
+        <DashboardToolbarIcon name="move-up" />
+      </DashboardToolbarButton>
 
-      <button
-        type="button"
-        class="flex h-8 w-8 items-center justify-center rounded-lg border border-lightListViewButtonBorder bg-lightListViewButtonBackground text-lightListViewButtonText shadow-sm hover:bg-lightListViewButtonBackgroundHover hover:text-lightListViewButtonTextHover disabled:opacity-45 dark:border-darkListViewButtonBorder dark:bg-darkListViewButtonBackground dark:text-darkListViewButtonText dark:hover:bg-darkListViewButtonBackgroundHover dark:hover:text-darkListViewButtonTextHover"
+      <DashboardToolbarButton
         title="Move down"
         :disabled="!canMoveDown"
         @click="emit('move-down')"
       >
-        <svg
-          class="h-4 w-4"
-          viewBox="0 0 24 24"
-          fill="none"
-          stroke="currentColor"
-          stroke-width="2"
-          stroke-linecap="round"
-          stroke-linejoin="round"
-          aria-hidden="true"
-        >
-          <path d="m6 9 6 6 6-6" />
-        </svg>
-      </button>
+        <DashboardToolbarIcon name="move-down" />
+      </DashboardToolbarButton>
 
-      <button
-        type="button"
-        class="flex h-8 w-8 items-center justify-center rounded-lg border border-lightInputErrorColor/30 bg-lightSecondary text-lightInputErrorColor shadow-sm hover:bg-lightListViewButtonBackgroundHover dark:bg-darkSecondary dark:hover:bg-darkListViewButtonBackgroundHover"
+      <DashboardToolbarButton
         title="Remove"
+        variant="danger"
         @click="emit('remove')"
       >
-        <svg
-          class="h-4 w-4"
-          viewBox="0 0 24 24"
-          fill="none"
-          stroke="currentColor"
-          stroke-width="2"
-          stroke-linecap="round"
-          stroke-linejoin="round"
-          aria-hidden="true"
-        >
-          <path d="M3 6h18" />
-          <path d="M8 6V4h8v2" />
-          <path d="M19 6l-1 14H6L5 6" />
-          <path d="M10 11v5" />
-          <path d="M14 11v5" />
-        </svg>
-      </button>
+        <DashboardToolbarIcon name="remove" />
+      </DashboardToolbarButton>
     </div>
   </div>
 </template>
@@ -105,6 +50,8 @@
 import { computed } from 'vue'
 import type { CSSProperties } from 'vue'
 import type { WidgetLayout } from '../model/dashboard.types.js'
+import DashboardToolbarButton from './DashboardToolbarButton.vue'
+import DashboardToolbarIcon from './DashboardToolbarIcon.vue'
 
 const DEFAULT_WIDGET_HEIGHT = 500
 

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

@@ -253,6 +253,50 @@ query:
       direction: asc
 ```
 
+Note: use `stacked_bar` with a normal single-resource grouped query when you need a dynamic series dimension such as `series.field: purpose`. For the same numeric buckets across multiple resources, use `query.source: steps` with `query.bucket`; set `chart.x.field: label`, `chart.y.field` to the aggregate alias, and `chart.series.field: name`.
+
+Example bucketed multi-resource stacked bar:
+
+```yaml
+target: chart
+label: Cars by price range and database
+size: wide
+chart:
+  type: stacked_bar
+  x:
+    field: label
+    label: Price range
+  y:
+    field: count
+    label: Cars
+  series:
+    field: name
+    label: Database
+query:
+  source: steps
+  bucket:
+    field: price
+    buckets:
+      - label: Budget
+        max: 3500
+      - label: Mid-range
+        min: 3500
+        max: 7000
+      - label: Premium
+        min: 7000
+  steps:
+    - name: SQLite
+      resource: cars_sl
+      select:
+        - agg: count
+          as: count
+    - name: MySQL
+      resource: cars_mysql
+      select:
+        - agg: count
+          as: count
+```
+
 Example `dashboard_configure_pie_chart_widget` config:
 
 ```yaml
@@ -291,26 +335,24 @@ chart:
     field: total_tokens
     label: Tokens
   y:
-    field: requests
+    field: count
     label: Requests
+  buckets:
+    - label: Small
+      max: 1000
+    - label: Medium
+      min: 1000
+      max: 10000
+    - label: Large
+      min: 10000
 query:
   resource: llm_usage
   select:
     - field: total_tokens
-    - agg: count
-      as: requests
-  bucket:
-    field: total_tokens
-    buckets:
-      - label: Small
-        max: 1000
-      - label: Medium
-        min: 1000
-        max: 10000
-      - label: Large
-        min: 10000
 ```
 
+Note: for the current dashboard runtime, histogram buckets are computed on the frontend from raw rows using `chart.buckets`. Do not rely on `query.bucket` for histogram widgets, do not use `query.source: steps`, and do not aggregate the source rows first. Histogram widgets should use a single-resource plain query with raw numeric rows, for example `select: - field: total_tokens`; the histogram component will derive the per-bucket `count` values itself.
+
 Example `dashboard_configure_funnel_chart_widget` config:
 
 ```yaml
@@ -476,6 +518,14 @@ query:
 
 Do not use bare query.steps without source: steps.
 Do not use metric. Use select even when a step has only one aggregate.
+Each `steps[]` item supports only:
+- name
+- resource
+- select with aggregate items only, for example `agg: count`, `agg: sum`, `agg: avg`
+- optional filters
+Do not put `field` selects, `calc` selects, `group_by`, `order_by`, `limit`, `offset`, or `bucket` inside a step.
+Without `query.bucket`, `query.source: steps` produces one output row per step, with built-in `name` and `resource` fields plus the aggregate aliases from that step.
+For per-bucket comparisons across multiple resources, put `bucket` at the query level, not inside a step. Use stacked_bar with `chart.x.field: label`, `chart.series.field: name`, and `chart.y.field` set to the aggregate alias such as `count`.
 All filters, including aggregate select item filters, must use filter expression shape.
 Use `filters: { field: model, eq: gpt-5.4 }`, not shorthand maps like `filters: { model: gpt-5.4 }`.
 When grouping by a derived date alias, repeat the source field object in `group_by`.