@adminforth/dashboard 1.5.0 → 1.7.0

package/custom/api/dashboardApi.ts

@@ -1,11 +1,15 @@
 import type {
   DashboardConfig,
   EditableDashboardGroupConfig,
-  EditableDashboardWidgetConfig,
   DashboardGroupMoveDirection,
+  ChartDashboardWidgetConfig,
   DashboardWidgetConfig,
   DashboardWidgetConfigValidationError,
   DashboardWidgetMoveDirection,
+  GaugeCardWidgetConfig,
+  KpiCardWidgetConfig,
+  PivotTableWidgetConfig,
+  TableWidgetConfig,
 } from '../model/dashboard.types.js'
 
 export type DashboardResponse = {
@@ -28,6 +32,18 @@ export type DashboardWidgetDataRequest = {
   }
 }
 
+export type ConfigurableTableWidgetConfig = Omit<TableWidgetConfig, 'id' | 'group_id' | 'order'>
+export type ConfigurableKpiCardWidgetConfig = Omit<KpiCardWidgetConfig, 'id' | 'group_id' | 'order'>
+export type ConfigurableGaugeCardWidgetConfig = Omit<GaugeCardWidgetConfig, 'id' | 'group_id' | 'order'>
+export type ConfigurableChartWidgetConfig = Omit<ChartDashboardWidgetConfig, 'id' | 'group_id' | 'order'>
+export type ConfigurableLineChartWidgetConfig = ConfigurableChartWidgetConfig & { chart: { type: 'line' } }
+export type ConfigurableBarChartWidgetConfig = ConfigurableChartWidgetConfig & { chart: { type: 'bar' } }
+export type ConfigurableStackedBarChartWidgetConfig = ConfigurableChartWidgetConfig & { chart: { type: 'stacked_bar' } }
+export type ConfigurablePieChartWidgetConfig = ConfigurableChartWidgetConfig & { chart: { type: 'pie' } }
+export type ConfigurableHistogramChartWidgetConfig = ConfigurableChartWidgetConfig & { chart: { type: 'histogram' } }
+export type ConfigurableFunnelChartWidgetConfig = ConfigurableChartWidgetConfig & { chart: { type: 'funnel' } }
+export type ConfigurablePivotTableWidgetConfig = Omit<PivotTableWidgetConfig, 'id' | 'group_id' | 'order'>
+
 export class DashboardApiError extends Error {
   validationErrors: DashboardWidgetConfigValidationError[]
 
@@ -205,6 +221,126 @@ export const dashboardApi = {
     })
   },
 
+  async configureTableWidget(
+    slug: string,
+    widgetId: string,
+    config: ConfigurableTableWidgetConfig,
+  ): Promise<DashboardResponse> {
+    return callDashboardApi('/adminapi/v1/dashboard/configure_table_widget', {
+      slug,
+      widgetId,
+      config,
+    })
+  },
+
+  async configureKpiCardWidget(
+    slug: string,
+    widgetId: string,
+    config: ConfigurableKpiCardWidgetConfig,
+  ): Promise<DashboardResponse> {
+    return callDashboardApi('/adminapi/v1/dashboard/configure_kpi_card_widget', {
+      slug,
+      widgetId,
+      config,
+    })
+  },
+
+  async configureGaugeCardWidget(
+    slug: string,
+    widgetId: string,
+    config: ConfigurableGaugeCardWidgetConfig,
+  ): Promise<DashboardResponse> {
+    return callDashboardApi('/adminapi/v1/dashboard/configure_gauge_card_widget', {
+      slug,
+      widgetId,
+      config,
+    })
+  },
+
+  async configureLineChartWidget(
+    slug: string,
+    widgetId: string,
+    config: ConfigurableLineChartWidgetConfig,
+  ): Promise<DashboardResponse> {
+    return callDashboardApi('/adminapi/v1/dashboard/configure_line_chart_widget', {
+      slug,
+      widgetId,
+      config,
+    })
+  },
+
+  async configureBarChartWidget(
+    slug: string,
+    widgetId: string,
+    config: ConfigurableBarChartWidgetConfig,
+  ): Promise<DashboardResponse> {
+    return callDashboardApi('/adminapi/v1/dashboard/configure_bar_chart_widget', {
+      slug,
+      widgetId,
+      config,
+    })
+  },
+
+  async configureStackedBarChartWidget(
+    slug: string,
+    widgetId: string,
+    config: ConfigurableStackedBarChartWidgetConfig,
+  ): Promise<DashboardResponse> {
+    return callDashboardApi('/adminapi/v1/dashboard/configure_stacked_bar_chart_widget', {
+      slug,
+      widgetId,
+      config,
+    })
+  },
+
+  async configurePieChartWidget(
+    slug: string,
+    widgetId: string,
+    config: ConfigurablePieChartWidgetConfig,
+  ): Promise<DashboardResponse> {
+    return callDashboardApi('/adminapi/v1/dashboard/configure_pie_chart_widget', {
+      slug,
+      widgetId,
+      config,
+    })
+  },
+
+  async configureHistogramChartWidget(
+    slug: string,
+    widgetId: string,
+    config: ConfigurableHistogramChartWidgetConfig,
+  ): Promise<DashboardResponse> {
+    return callDashboardApi('/adminapi/v1/dashboard/configure_histogram_chart_widget', {
+      slug,
+      widgetId,
+      config,
+    })
+  },
+
+  async configureFunnelChartWidget(
+    slug: string,
+    widgetId: string,
+    config: ConfigurableFunnelChartWidgetConfig,
+  ): Promise<DashboardResponse> {
+    return callDashboardApi('/adminapi/v1/dashboard/configure_funnel_chart_widget', {
+      slug,
+      widgetId,
+      config,
+    })
+  },
+
+  async configurePivotTableWidget(
+    slug: string,
+    widgetId: string,
+    config: ConfigurablePivotTableWidgetConfig,
+  ): Promise<DashboardResponse> {
+    return callDashboardApi('/adminapi/v1/dashboard/configure_pivot_table_widget', {
+      slug,
+      widgetId,
+      config,
+    })
+  },
+
   async getDashboardWidgetData(
     slug: string,
     widgetId: string,

package/custom/model/dashboard.types.ts

@@ -36,6 +36,7 @@ export type QueryAggregateOperation = 'sum' | 'count' | 'count_distinct' | 'avg'
 export type TimeGrain = 'day' | 'week' | 'month' | 'year'
 export type ValueFormat =
   | 'number'
+  | 'integer'
   | 'compact_number'
   | 'currency'
   | 'percent'
@@ -119,21 +120,17 @@ export type QueryOrderByItem = {
 export type QueryConfig = {
   resource: string
   select?: QuerySelectItem[]
+  sparkline?: {
+    field: string
+    grain: TimeGrain
+    as: string
+    fill_missing?: Record<string, JsonValue>
+  }
   filters?: FilterExpression
   group_by?: QueryGroupByItem[]
   order_by?: QueryOrderByItem[]
   limit?: number
   offset?: number
-  time_series?: {
-    field: string
-    grain: TimeGrain
-    timezone?: string
-  }
-  period?: {
-    field: string
-    gte?: JsonValue
-    lt?: JsonValue
-  }
   bucket?: {
     field: string
     buckets: Array<{ label: string, min?: number, max?: number }>
@@ -178,8 +175,29 @@ export type KpiCardViewConfig = {
     text?: string
     field?: string
   }
-  comparison?: JsonValue
-  sparkline?: JsonValue
+  comparison?: {
+    field: string
+    format?: ValueFormat
+    positive_is_good?: boolean
+    compact?: {
+      show?: boolean
+      template?: string
+    }
+    tooltip?: {
+      label?: string
+      template?: string
+    }
+  }
+  sparkline?: {
+    type?: 'line'
+    field: string
+    x: string
+    show_axes?: boolean
+    show_labels?: boolean
+    fill?: {
+      type?: 'gradient' | 'solid'
+    }
+  }
 }
 
 export type GaugeCardViewConfig = {
@@ -257,14 +275,6 @@ export type DashboardWidgetConfig =
   | GaugeCardWidgetConfig
   | PivotTableWidgetConfig
 
-export type EditableDashboardWidgetConfig =
-  | Omit<EmptyWidgetConfig, 'id' | 'group_id' | 'order'>
-  | Omit<TableWidgetConfig, 'id' | 'group_id' | 'order'>
-  | Omit<ChartDashboardWidgetConfig, 'id' | 'group_id' | 'order'>
-  | Omit<KpiCardWidgetConfig, 'id' | 'group_id' | 'order'>
-  | Omit<GaugeCardWidgetConfig, 'id' | 'group_id' | 'order'>
-  | Omit<PivotTableWidgetConfig, 'id' | 'group_id' | 'order'>
-
 export type DashboardWidgetTableData = {
   kind?: 'table'
   columns: string[]
@@ -299,10 +309,10 @@ export function serializeDashboardWidgetConfigForEditor(
     id: _id,
     group_id: _groupId,
     order: _order,
-    ...editableWidget
+    ...editableWidgetConfig
   } = widget
 
-  return editableWidget
+  return editableWidgetConfig
 }
 
 export function getFieldRefField(value: FieldRef | undefined) {

package/custom/package.json

@@ -5,6 +5,7 @@
   "type": "module",
   "license": "MIT",
   "dependencies": {
+    "monaco-editor": "^0.55.1",
     "yaml": "^2.9.0"
   }
 }

package/custom/pnpm-lock.yaml

@@ -8,12 +8,29 @@ importers:
 
   .:
     dependencies:
+      monaco-editor:
+        specifier: ^0.55.1
+        version: 0.55.1
       yaml:
         specifier: ^2.9.0
         version: 2.9.0
 
 packages:
 
+  '@types/trusted-types@2.0.7':
+    resolution: {integrity: sha512-ScaPdn1dQczgbl0QFTeTOmVHFULt394XJgOQNoyVhZ6r2vLnMLJfBPd53SB52T/3G36VI1/g2MZaX0cwDuXsfw==}
+
+  dompurify@3.2.7:
+    resolution: {integrity: sha512-WhL/YuveyGXJaerVlMYGWhvQswa7myDG17P7Vu65EWC05o8vfeNbvNf4d/BOvH99+ZW+LlQsc1GDKMa1vNK6dw==}
+
+  marked@14.0.0:
+    resolution: {integrity: sha512-uIj4+faQ+MgHgwUW1l2PsPglZLOLOT1uErt06dAPtx2kjteLAkbsd/0FiYg/MGS+i7ZKLb7w2WClxHkzOOuryQ==}
+    engines: {node: '>= 18'}
+    hasBin: true
+
+  monaco-editor@0.55.1:
+    resolution: {integrity: sha512-jz4x+TJNFHwHtwuV9vA9rMujcZRb0CEilTEwG2rRSpe/A7Jdkuj8xPKttCgOh+v/lkHy7HsZ64oj+q3xoAFl9A==}
+
   yaml@2.9.0:
     resolution: {integrity: sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA==}
     engines: {node: '>= 14.6'}
@@ -21,4 +38,18 @@ packages:
 
 snapshots:
 
+  '@types/trusted-types@2.0.7':
+    optional: true
+
+  dompurify@3.2.7:
+    optionalDependencies:
+      '@types/trusted-types': 2.0.7
+
+  marked@14.0.0: {}
+
+  monaco-editor@0.55.1:
+    dependencies:
+      dompurify: 3.2.7
+      marked: 14.0.0
+
   yaml@2.9.0: {}

package/custom/runtime/DashboardRuntime.vue

@@ -54,7 +54,7 @@
       class="fixed inset-0 z-50 flex items-center justify-center bg-black/35 p-4"
       @click.self="closeGroupConfigEditor"
     >
-      <section class="w-full max-w-2xl rounded-lg border border-lightListBorder bg-lightDropdownOptionsBackground p-4 shadow-xl dark:border-darkListBorder dark:bg-darkDropdownOptionsBackground">
+      <section class="w-full max-w-5xl rounded-lg border border-lightListBorder bg-lightDropdownOptionsBackground p-4 shadow-xl dark:border-darkListBorder dark:bg-darkDropdownOptionsBackground">
         <header class="mb-3 flex items-center justify-between gap-3">
           <h2 class="m-0 text-base font-bold text-lightNavbarText dark:text-darkNavbarText">
             Group JSON
@@ -81,12 +81,9 @@
           </button>
         </header>
 
-        <textarea
+        <YamlConfigEditor
           v-model="groupConfigCode"
-          class="min-h-[500px] w-full resize-y rounded-lg border border-lightListBorder bg-lightListTable p-3 font-mono text-sm text-lightNavbarText outline-none focus:border-lightPrimaryButtonBackground dark:border-darkListBorder dark:bg-darkListTable dark:text-darkNavbarText dark:focus:border-darkPrimaryButtonBackground"
-          spellcheck="false"
-          @keydown.ctrl.enter.prevent="saveGroupConfig"
-          @keydown.meta.enter.prevent="saveGroupConfig"
+          @save="saveGroupConfig"
         />
 
         <div
@@ -120,7 +117,7 @@
       class="fixed inset-0 z-50 flex items-center justify-center bg-black/35 p-4"
       @click.self="closeWidgetConfigEditor"
     >
-      <section class="w-full max-w-2xl rounded-lg border border-lightListBorder bg-lightDropdownOptionsBackground p-4 shadow-xl dark:border-darkListBorder dark:bg-darkDropdownOptionsBackground">
+      <section class="w-full max-w-5xl rounded-lg border border-lightListBorder bg-lightDropdownOptionsBackground p-4 shadow-xl dark:border-darkListBorder dark:bg-darkDropdownOptionsBackground">
         <header class="mb-3 flex items-center justify-between gap-3">
           <h2 class="m-0 text-base font-bold text-lightNavbarText dark:text-darkNavbarText">
             Widget JSON
@@ -147,12 +144,9 @@
           </button>
         </header>
 
-        <textarea
+        <YamlConfigEditor
           v-model="widgetConfigCode"
-          class="min-h-[500px] w-full resize-y rounded-lg border border-lightListBorder bg-lightListTable p-3 font-mono text-sm text-lightNavbarText outline-none focus:border-lightPrimaryButtonBackground dark:border-darkListBorder dark:bg-darkListTable dark:text-darkNavbarText dark:focus:border-darkPrimaryButtonBackground"
-          spellcheck="false"
-          @keydown.ctrl.enter.prevent="saveWidgetConfig"
-          @keydown.meta.enter.prevent="saveWidgetConfig"
+          @save="saveWidgetConfig"
         />
 
         <div
@@ -203,12 +197,12 @@ import { computed, ref, watch } from 'vue'
 import { parse as parseYaml, stringify as stringifyYaml } from 'yaml'
 import { Button } from '@/afcl'
 import DashboardGroup from './DashboardGroup.vue'
+import YamlConfigEditor from './YamlConfigEditor.vue'
 import { DashboardApiError, dashboardApi, type DashboardResponse } from '../api/dashboardApi.js'
 import type {
   DashboardConfig,
   DashboardGroupConfig,
   EditableDashboardGroupConfig,
-  EditableDashboardWidgetConfig,
   DashboardGroupMoveDirection,
   DashboardWidgetConfig,
   DashboardWidgetMoveDirection,
@@ -414,13 +408,13 @@ async function saveWidgetConfig() {
   try {
     widgetConfigError.value = ''
     widgetConfigFieldErrors.value = []
-    const widgetConfig = parseYaml(widgetConfigCode.value) as EditableDashboardWidgetConfig
+    const widgetConfig = parseYaml(widgetConfigCode.value) as DashboardWidgetConfig
 
     applyDashboardResponse(
       await dashboardApi.setWidgetConfig(
         props.dashboardSlug,
         editingWidgetId.value,
-        widgetConfig,
+        serializeDashboardWidgetConfigForEditor(widgetConfig),
       ),
     )
     closeWidgetConfigEditor()

package/custom/runtime/YamlConfigEditor.vue

@@ -0,0 +1,109 @@
+<template>
+  <div
+    ref="editorEl"
+    class="min-h-[500px] w-full overflow-hidden rounded-lg border border-lightListBorder bg-lightListTable text-sm dark:border-darkListBorder dark:bg-darkListTable"
+  />
+</template>
+
+<script setup lang="ts">
+import 'monaco-editor/min/vs/editor/editor.main.css'
+import EditorWorker from 'monaco-editor/esm/vs/editor/editor.worker?worker'
+import { nextTick, onBeforeUnmount, onMounted, ref, watch } from 'vue'
+import type * as Monaco from 'monaco-editor'
+
+declare global {
+  interface Window {
+    MonacoEnvironment?: {
+      getWorker: () => Worker
+    }
+  }
+}
+
+if (typeof window !== 'undefined' && !window.MonacoEnvironment) {
+  window.MonacoEnvironment = {
+    getWorker: () => new EditorWorker(),
+  }
+}
+
+const props = defineProps<{
+  modelValue: string
+}>()
+
+const emit = defineEmits<{
+  'update:modelValue': [value: string]
+  save: []
+}>()
+
+const editorEl = ref<HTMLElement | null>(null)
+let monaco: typeof Monaco | null = null
+let editor: Monaco.editor.IStandaloneCodeEditor | null = null
+let resizeObserver: ResizeObserver | null = null
+let applyingExternalValue = false
+
+watch(
+  () => props.modelValue,
+  (value) => {
+    if (!editor || value === editor.getValue()) {
+      return
+    }
+
+    applyingExternalValue = true
+    editor.setValue(value)
+    applyingExternalValue = false
+  },
+)
+
+onMounted(async () => {
+  const [loadedMonaco] = await Promise.all([
+    import('monaco-editor'),
+    import('monaco-editor/esm/vs/basic-languages/yaml/yaml.contribution'),
+  ])
+
+  monaco = loadedMonaco
+  await nextTick()
+
+  if (!editorEl.value) {
+    return
+  }
+
+  editor = monaco.editor.create(editorEl.value, {
+    value: props.modelValue,
+    language: 'yaml',
+    automaticLayout: true,
+    minimap: { enabled: false },
+    fontSize: 13,
+    lineNumbersMinChars: 3,
+    padding: { top: 12, bottom: 12 },
+    scrollBeyondLastLine: false,
+    tabSize: 2,
+    insertSpaces: true,
+    wordWrap: 'on',
+    wrappingIndent: 'same',
+    theme: document.documentElement.classList.contains('dark') ? 'vs-dark' : 'vs',
+  })
+
+  editor.onDidChangeModelContent(() => {
+    if (!editor || applyingExternalValue) {
+      return
+    }
+
+    emit('update:modelValue', editor.getValue())
+  })
+
+  editor.addCommand(monaco.KeyMod.CtrlCmd | monaco.KeyCode.Enter, () => {
+    emit('save')
+  })
+
+  resizeObserver = new ResizeObserver(() => {
+    editor?.layout()
+  })
+  resizeObserver.observe(editorEl.value)
+})
+
+onBeforeUnmount(() => {
+  resizeObserver?.disconnect()
+  resizeObserver = null
+  editor?.dispose()
+  editor = null
+})
+</script>

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

@@ -19,7 +19,6 @@ Dashboard root, groups, and widgets are different entities.
 - Widget tools use widgetId and change target/query/card/chart/table/pivot.
 - Never call dashboard_set_dashboard_group_config to configure a widget.
 - Never call dashboard_add_dashboard_group to configure a widget.
-- If widget target, label, query, chart, card, table, pivot, variables, formulas, filters, or display fields must change, use dashboard_set_widget_config.
 
 ## Tool routing
 
@@ -27,7 +26,16 @@ Dashboard root, groups, and widgets are different entities.
 - Add group: dashboard_add_dashboard_group
 - Rename group: dashboard_set_dashboard_group_config
 - Add widget slot: dashboard_add_dashboard_widget
-- Configure widget: dashboard_set_widget_config
+- Configure table widget: dashboard_configure_table_widget
+- Configure KPI card widget: dashboard_configure_kpi_card_widget
+- Configure gauge card widget: dashboard_configure_gauge_card_widget
+- Configure line chart widget: dashboard_configure_line_chart_widget
+- Configure bar chart widget: dashboard_configure_bar_chart_widget
+- Configure stacked bar chart widget: dashboard_configure_stacked_bar_chart_widget
+- Configure pie chart widget: dashboard_configure_pie_chart_widget
+- Configure histogram chart widget: dashboard_configure_histogram_chart_widget
+- Configure funnel chart widget: dashboard_configure_funnel_chart_widget
+- Configure pivot table widget: dashboard_configure_pivot_table_widget
 - Move/remove widget/group: matching move/remove tool
 - Load widget data: dashboard_get_dashboard_widget_data
 
@@ -42,7 +50,7 @@ Before creating a group, call dashboard_get_config and check existing groups.
 - If no matching group exists, call dashboard_add_dashboard_group at most once for that requested group.
 - After dashboard_add_dashboard_group succeeds, extract the new groupId from the returned dashboard response.
 - If the group needs a label, call dashboard_set_dashboard_group_config once with that groupId.
-- After that, the next mutation must be dashboard_add_dashboard_widget or dashboard_set_widget_config, not another dashboard_add_dashboard_group.
+- After that, the next mutation must be dashboard_add_dashboard_widget or a widget configure tool, not another dashboard_add_dashboard_group.
 
 Never call dashboard_add_dashboard_group repeatedly for the same user request. If you are about to create a second group for the same label/section, stop and report:
 
@@ -57,7 +65,7 @@ For any request to create KPI/chart/table/pivot/gauge widgets:
 3. if needed, rename group once
 4. for each widget:
    - dashboard_add_dashboard_widget
-   - immediately dashboard_set_widget_config for the returned widgetId
+   - immediately configure it with the matching dashboard_configure_*_widget tool
    - confirm target is not empty
 5. dashboard_get_config
 6. validate all requested widgets are configured
@@ -79,7 +87,7 @@ This is incomplete for KPI/chart/table/pivot/gauge/spend/revenue/usage widgets.
 
 If the same mutation tool is about to be called with the same payload twice, stop and reassess.
 If dashboard_add_dashboard_group repeats for the same requested group, stop and reuse the groupId from dashboard_get_config.
-If dashboard_set_dashboard_group_config repeats while new widgets are target: empty, use dashboard_set_widget_config instead.
+If dashboard_set_dashboard_group_config repeats while new widgets are target: empty, use a widget configure tool instead.
 After 2 repeated no-op mutations, stop with an explicit error.
 
 ## State machine
@@ -90,22 +98,43 @@ dashboard_get_config
 -> maybe dashboard_add_dashboard_group
 -> maybe dashboard_set_dashboard_group_config
 -> dashboard_add_dashboard_widget
--> dashboard_set_widget_config
+-> matching dashboard_configure_*_widget tool
 -> repeat only the two widget steps for more widgets
 -> dashboard_get_config
 
 Allowed repeats:
 - dashboard_add_dashboard_widget may repeat once per requested widget.
-- dashboard_set_widget_config may repeat once per requested widget.
+- widget configure tools may repeat once per requested widget.
 
 Forbidden repeats:
 - dashboard_add_dashboard_group for the same requested group.
 - dashboard_set_dashboard_group_config with the same label/groupId.
 
 Forbidden substitutions:
-- dashboard_set_dashboard_group_config instead of set widget config.
+- dashboard_set_dashboard_group_config instead of a widget configure tool.
 - dashboard_add_dashboard_group instead of add widget.
 
+## Specialized widget tools
+
+Available specialized tools:
+- dashboard_configure_table_widget
+- dashboard_configure_kpi_card_widget
+- dashboard_configure_gauge_card_widget
+- dashboard_configure_pivot_table_widget
+- dashboard_configure_line_chart_widget
+- dashboard_configure_bar_chart_widget
+- dashboard_configure_stacked_bar_chart_widget
+- dashboard_configure_pie_chart_widget
+- dashboard_configure_histogram_chart_widget
+- dashboard_configure_funnel_chart_widget
+
+Each specialized tool accepts:
+- slug
+- widgetId
+- config
+
+The config is the normal widget config for that target without server-owned id, group_id, and order.
+
 ## Widget config keys
 
 Use current keys:
@@ -116,22 +145,49 @@ Use table for table.
 Use pivot for pivot_table.
 
 Use target, not type.
+For charts, use target: chart and chart.type for the concrete chart kind.
 Use query, not dataSource.
 Use resource, not resourceId.
 
 ## Query shape rules
 
-Use query.steps only for funnel charts. Do not use query.steps for kpi_card, gauge_card, table, pivot_table, or normal bar/line/stacked/pie charts.
+Use dashboard_configure_funnel_chart_widget for funnel charts and set query.steps.
+Do not use query.steps for kpi_card, gauge_card, table, pivot_table, line, bar, stacked bar, pie, or histogram charts.
 
 For kpi_card and normal charts, use:
 - query.resource
 - query.select
 - optional query.filters
 - optional query.group_by
-- optional query.period
 - optional query.order_by
 - optional query.calcs
 
+## Date range rules
+
+Use only query.filters for time ranges.
+Never use fixed ISO dates for rolling dashboard periods.
+Never use query.period, period.range, query.time_series, or time_series.range.
+
+For rolling ranges, use this exact filter shape:
+
+filters:
+  and:
+    - field: created_at
+      gte:
+        now_minus: 30d
+    - field: created_at
+      lt:
+        now: true
+
+Supported relative duration suffixes:
+- h for hours
+- d for days
+- w for weeks
+- mo for months
+- y for years
+
+For today/yesterday/last 7 days comparisons, create separate aggregate select items with separate filters and aliases. Do not hard-code calendar dates.
+
 Calculations run after selected fields and aggregates are loaded into a row. Therefore:
 - aggregate real resource fields first
 - then calculate derived fields from those aggregate aliases