@adminforth/dashboard 1.8.0 → 1.10.0

package/README.md

@@ -29,7 +29,7 @@ Each widget has common fields:
 | `label` | Optional widget title. |
 | `target` | Widget type: `table`, `chart`, `kpi_card`, `pivot_table`, or `gauge_card`. |
 | `order` | Widget order inside its group. |
-| `variables` | Optional static maps/constants available inside widget `query.calcs` via `lookup($variables.path, field, default)`. |
+| `variables` | Optional widget variables passed to widget data loading. Variables are not available inside `query.calcs`. |
 | `size` | Preset width: `small`, `medium`, `large`, `wide`, or `full`. |
 | `width`, `height`, `min_width`, `max_width` | Optional explicit layout constraints. |
 | `query` | Data query definition. |
@@ -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 `query`; step-based charts may use `query.steps` with optional `calcs`. |
+| `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`. |
 | `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. |
@@ -52,13 +52,14 @@ Chart widget types:
 | `pie` | Uses `label` and `value`. |
 | `bar` | Uses `x` and `y`. |
 | `stacked_bar` | Uses `x`, `y`, and `series`. |
-| `funnel` | Uses `query.steps` and optional `label`, `value`, `colors`. |
+| `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`. |
 
 ## Query Shape
 
 ```ts
 type QueryConfig = {
+  source?: 'resource'
   resource: string
   select?: Array<
     | { field: string; as?: string; grain?: 'day' | 'week' | 'month' | 'year' }
@@ -70,6 +71,22 @@ type QueryConfig = {
   order_by?: Array<{ field: string; direction?: 'asc' | 'desc' }>
   limit?: number
   offset?: number
+  bucket?: { field: string; buckets: Array<{ label: string; min?: number; max?: number }> }
+  calcs?: Array<{ calc: string; as: string }>
+  formatting?: Record<string, JsonValue>
+} | {
+  source: 'steps'
+  steps: Array<{
+    name: string
+    resource: string
+    select: Array<{ agg: 'sum' | 'count' | 'count_distinct' | 'avg' | 'min' | 'max' | 'median'; field?: string; as: string; filters?: DashboardFilter | DashboardFilter[] }>
+    filters?: DashboardFilter | DashboardFilter[]
+  }>
+  calcs?: Array<{ calc: string; as: string }>
+  order_by?: Array<{ field: string; direction?: 'asc' | 'desc' }>
+  limit?: number
+  offset?: number
+  formatting?: Record<string, JsonValue>
 }
 
 type DashboardFilter =
@@ -77,91 +94,97 @@ type DashboardFilter =
   | { or: DashboardFilter[] }
   | {
       field: string
-      eq?: JsonValue
-      neq?: JsonValue
-      gt?: JsonValue
-      gte?: JsonValue
-      lt?: JsonValue
-      lte?: JsonValue
-      in?: JsonValue[]
-      not_in?: JsonValue[]
-      like?: JsonValue
-      ilike?: JsonValue
+      eq?: FilterValue
+      neq?: FilterValue
+      gt?: FilterValue
+      gte?: FilterValue
+      lt?: FilterValue
+      lte?: FilterValue
+      in?: FilterValue[]
+      not_in?: FilterValue[]
+      like?: FilterValue
+      ilike?: FilterValue
     }
 
 type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue }
+type RelativeDateValue = { now: true } | { now_minus: `${number}${'h' | 'd' | 'w' | 'mo' | 'y'}` }
+type FilterValue = JsonValue | RelativeDateValue
+```
+
+Use `filters` for rolling date ranges. Do not hard-code dates for dashboards that should move with time:
+
+```yaml
+query:
+  resource: orders
+  filters:
+    and:
+      - field: created_at
+        gte:
+          now_minus: 30d
+      - field: created_at
+        lt:
+          now: true
 ```
 
-Step-based chart queries use `steps` and may include `calcs`:
+Multi-resource queries use `source: steps`. Each step uses `select`, even if it has only one aggregate:
 
 ```yaml
 target: chart
 label: Average price by database
-variables:
-  price_multipliers:
-    cars_sl: 0.84
-    cars_mysql: 1.12
-    cars_pg: 0.91
-    cars_mongo: 1.07
-    cars_ch: 0.76
 chart:
   type: bar
   title: Average price by database
   x:
     field: name
   y:
-    field: adjusted_value
+    field: value
 query:
+  source: steps
   steps:
     - name: SQLite
       resource: cars_sl
-      metric:
-        agg: avg
-        field: price
-        as: value
+      select:
+        - agg: avg
+          field: price
+          as: value
     - name: MySQL
       resource: cars_mysql
-      metric:
-        agg: avg
-        field: price
-        as: value
-  calcs:
-    - calc: value * lookup($variables.price_multipliers, resource, 1)
-      as: adjusted_value
+      select:
+        - agg: avg
+          field: price
+          as: value
 ```
 
-Widget-level variables example:
+Cost calculation example:
 
 ```yaml
 target: chart
 label: Model costs
-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
+  title: GPT-5.4 costs by day
   x:
-    field: model
+    field: day
   y:
     - field: input_cost
     - field: output_cost
     - field: cached_cost
 query:
   resource: model_usage
+  filters:
+    and:
+      - field: model
+        eq: gpt-5.4
+      - field: used_at
+        gte:
+          now_minus: 7d
+      - field: used_at
+        lt:
+          now: true
   select:
-    - field: model
+    - field: used_at
+      as: day
+      grain: day
     - agg: sum
       field: input_tokens
       as: input_tokens
@@ -172,16 +195,19 @@ query:
       field: cached_tokens
       as: cached_tokens
   group_by:
-    - model
+    - field: used_at
+      as: day
+      grain: day
   calcs:
-    - calc: input_tokens / 1000000 * lookup($variables.token_prices_per_1m.input, model, 0)
+    - calc: input_tokens / 1000000 * 2.5
       as: input_cost
-    - calc: output_tokens / 1000000 * lookup($variables.token_prices_per_1m.output, model, 0)
+    - calc: output_tokens / 1000000 * 15
       as: output_cost
-    - calc: cached_tokens / 1000000 * lookup($variables.token_prices_per_1m.cached, model, 0)
+    - calc: cached_tokens / 1000000 * 0.25
       as: cached_cost
 ```
 
+
 ## Runtime Structure
 
 ```text

package/custom/api/dashboardApi.ts

@@ -25,6 +25,13 @@ export type DashboardWidgetDataResponse = {
   data: unknown
 }
 
+export type DashboardMutationResponse = {
+  ok: boolean
+  error?: string
+  groupId?: string
+  widgetId?: string
+}
+
 export type DashboardWidgetDataRequest = {
   pagination?: {
     page: number
@@ -119,6 +126,36 @@ async function callDashboardApi(path: string, body: Record<string, unknown>): Pr
   }
 }
 
+async function callDashboardMutationApi(path: string, body: Record<string, unknown>): Promise<DashboardMutationResponse> {
+  const rawResponse = await fetch(path, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'accept-language': localStorage.getItem('af_lang') || 'en',
+    },
+    body: JSON.stringify(body),
+  })
+
+  const response = await parseDashboardResponse(rawResponse)
+
+  if (!rawResponse.ok) {
+    throw new DashboardApiError(
+      response?.error || rawResponse.statusText || `Dashboard request failed (${rawResponse.status})`,
+      normalizeValidationErrors(response),
+    )
+  }
+
+  if (!response || response.error || response.ok === false) {
+    throw new DashboardApiError(response?.error || 'Dashboard request failed', normalizeValidationErrors(response))
+  }
+
+  return {
+    ok: true,
+    groupId: response.groupId,
+    widgetId: response.widgetId,
+  }
+}
+
 async function callDashboardWidgetDataApi(
   path: string,
   body: Record<string, unknown>,
@@ -156,39 +193,39 @@ export const dashboardApi = {
     return callDashboardApi('/adminapi/v1/dashboard/get-config', { slug })
   },
 
-  async addDashboardGroup(slug: string): Promise<DashboardResponse> {
-    return callDashboardApi('/adminapi/v1/dashboard/add_dashboard_group', { slug })
+  async addDashboardGroup(slug: string): Promise<DashboardMutationResponse> {
+    return callDashboardMutationApi('/adminapi/v1/dashboard/add_dashboard_group', { slug })
   },
 
   async moveDashboardGroup(
     slug: string,
     groupId: string,
     direction: DashboardGroupMoveDirection,
-  ): Promise<DashboardResponse> {
-    return callDashboardApi('/adminapi/v1/dashboard/move_dashboard_group', {
+  ): Promise<DashboardMutationResponse> {
+    return callDashboardMutationApi('/adminapi/v1/dashboard/move_dashboard_group', {
       slug,
       groupId,
       direction,
     })
   },
 
-  async removeDashboardGroup(slug: string, groupId: string): Promise<DashboardResponse> {
-    return callDashboardApi('/adminapi/v1/dashboard/remove_dashboard_group', {
+  async removeDashboardGroup(slug: string, groupId: string): Promise<DashboardMutationResponse> {
+    return callDashboardMutationApi('/adminapi/v1/dashboard/remove_dashboard_group', {
       slug,
       groupId,
     })
   },
 
-  async setDashboardGroupConfig(slug: string, groupId: string, config: EditableDashboardGroupConfig): Promise<DashboardResponse> {
-    return callDashboardApi('/adminapi/v1/dashboard/set_dashboard_group_config', {
+  async setDashboardGroupConfig(slug: string, groupId: string, config: EditableDashboardGroupConfig): Promise<DashboardMutationResponse> {
+    return callDashboardMutationApi('/adminapi/v1/dashboard/set_dashboard_group_config', {
       slug,
       groupId,
       config,
     })
   },
 
-  async addDashboardWidget(slug: string, groupId: string): Promise<DashboardResponse> {
-    return callDashboardApi('/adminapi/v1/dashboard/add_dashboard_widget', {
+  async addDashboardWidget(slug: string, groupId: string): Promise<DashboardMutationResponse> {
+    return callDashboardMutationApi('/adminapi/v1/dashboard/add_dashboard_widget', {
       slug,
       groupId,
     })
@@ -198,23 +235,23 @@ export const dashboardApi = {
     slug: string,
     widgetId: string,
     direction: DashboardWidgetMoveDirection,
-  ): Promise<DashboardResponse> {
-    return callDashboardApi('/adminapi/v1/dashboard/move_dashboard_widget', {
+  ): Promise<DashboardMutationResponse> {
+    return callDashboardMutationApi('/adminapi/v1/dashboard/move_dashboard_widget', {
       slug,
       widgetId,
       direction,
     })
   },
 
-  async removeDashboardWidget(slug: string, widgetId: string): Promise<DashboardResponse> {
-    return callDashboardApi('/adminapi/v1/dashboard/remove_dashboard_widget', {
+  async removeDashboardWidget(slug: string, widgetId: string): Promise<DashboardMutationResponse> {
+    return callDashboardMutationApi('/adminapi/v1/dashboard/remove_dashboard_widget', {
       slug,
       widgetId,
     })
   },
 
-  async setWidgetConfig(slug: string, widgetId: string, config: unknown): Promise<DashboardResponse> {
-    return callDashboardApi('/adminapi/v1/dashboard/set_widget_config', {
+  async setWidgetConfig(slug: string, widgetId: string, config: unknown): Promise<DashboardMutationResponse> {
+    return callDashboardMutationApi('/adminapi/v1/dashboard/set_widget_config', {
       slug,
       widgetId,
       config,
@@ -225,8 +262,8 @@ export const dashboardApi = {
     slug: string,
     widgetId: string,
     config: ConfigurableTableWidgetConfig,
-  ): Promise<DashboardResponse> {
-    return callDashboardApi('/adminapi/v1/dashboard/configure_table_widget', {
+  ): Promise<DashboardMutationResponse> {
+    return callDashboardMutationApi('/adminapi/v1/dashboard/configure_table_widget', {
       slug,
       widgetId,
       config,
@@ -237,8 +274,8 @@ export const dashboardApi = {
     slug: string,
     widgetId: string,
     config: ConfigurableKpiCardWidgetConfig,
-  ): Promise<DashboardResponse> {
-    return callDashboardApi('/adminapi/v1/dashboard/configure_kpi_card_widget', {
+  ): Promise<DashboardMutationResponse> {
+    return callDashboardMutationApi('/adminapi/v1/dashboard/configure_kpi_card_widget', {
       slug,
       widgetId,
       config,
@@ -249,8 +286,8 @@ export const dashboardApi = {
     slug: string,
     widgetId: string,
     config: ConfigurableGaugeCardWidgetConfig,
-  ): Promise<DashboardResponse> {
-    return callDashboardApi('/adminapi/v1/dashboard/configure_gauge_card_widget', {
+  ): Promise<DashboardMutationResponse> {
+    return callDashboardMutationApi('/adminapi/v1/dashboard/configure_gauge_card_widget', {
       slug,
       widgetId,
       config,
@@ -261,8 +298,8 @@ export const dashboardApi = {
     slug: string,
     widgetId: string,
     config: ConfigurableLineChartWidgetConfig,
-  ): Promise<DashboardResponse> {
-    return callDashboardApi('/adminapi/v1/dashboard/configure_line_chart_widget', {
+  ): Promise<DashboardMutationResponse> {
+    return callDashboardMutationApi('/adminapi/v1/dashboard/configure_line_chart_widget', {
       slug,
       widgetId,
       config,
@@ -273,8 +310,8 @@ export const dashboardApi = {
     slug: string,
     widgetId: string,
     config: ConfigurableBarChartWidgetConfig,
-  ): Promise<DashboardResponse> {
-    return callDashboardApi('/adminapi/v1/dashboard/configure_bar_chart_widget', {
+  ): Promise<DashboardMutationResponse> {
+    return callDashboardMutationApi('/adminapi/v1/dashboard/configure_bar_chart_widget', {
       slug,
       widgetId,
       config,
@@ -285,8 +322,8 @@ export const dashboardApi = {
     slug: string,
     widgetId: string,
     config: ConfigurableStackedBarChartWidgetConfig,
-  ): Promise<DashboardResponse> {
-    return callDashboardApi('/adminapi/v1/dashboard/configure_stacked_bar_chart_widget', {
+  ): Promise<DashboardMutationResponse> {
+    return callDashboardMutationApi('/adminapi/v1/dashboard/configure_stacked_bar_chart_widget', {
       slug,
       widgetId,
       config,
@@ -297,8 +334,8 @@ export const dashboardApi = {
     slug: string,
     widgetId: string,
     config: ConfigurablePieChartWidgetConfig,
-  ): Promise<DashboardResponse> {
-    return callDashboardApi('/adminapi/v1/dashboard/configure_pie_chart_widget', {
+  ): Promise<DashboardMutationResponse> {
+    return callDashboardMutationApi('/adminapi/v1/dashboard/configure_pie_chart_widget', {
       slug,
       widgetId,
       config,
@@ -309,8 +346,8 @@ export const dashboardApi = {
     slug: string,
     widgetId: string,
     config: ConfigurableHistogramChartWidgetConfig,
-  ): Promise<DashboardResponse> {
-    return callDashboardApi('/adminapi/v1/dashboard/configure_histogram_chart_widget', {
+  ): Promise<DashboardMutationResponse> {
+    return callDashboardMutationApi('/adminapi/v1/dashboard/configure_histogram_chart_widget', {
       slug,
       widgetId,
       config,
@@ -321,8 +358,8 @@ export const dashboardApi = {
     slug: string,
     widgetId: string,
     config: ConfigurableFunnelChartWidgetConfig,
-  ): Promise<DashboardResponse> {
-    return callDashboardApi('/adminapi/v1/dashboard/configure_funnel_chart_widget', {
+  ): Promise<DashboardMutationResponse> {
+    return callDashboardMutationApi('/adminapi/v1/dashboard/configure_funnel_chart_widget', {
       slug,
       widgetId,
       config,
@@ -333,8 +370,8 @@ export const dashboardApi = {
     slug: string,
     widgetId: string,
     config: ConfigurablePivotTableWidgetConfig,
-  ): Promise<DashboardResponse> {
-    return callDashboardApi('/adminapi/v1/dashboard/configure_pivot_table_widget', {
+  ): Promise<DashboardMutationResponse> {
+    return callDashboardMutationApi('/adminapi/v1/dashboard/configure_pivot_table_widget', {
       slug,
       widgetId,
       config,

package/custom/model/dashboard.types.ts

@@ -140,19 +140,12 @@ export type ResourceQueryConfig = {
   formatting?: Record<string, JsonValue>
 }
 
-export type StepsQueryStepConfig =
-  | {
-      name: string
-      resource: string
-      metric: QueryAggregateSelectItem
-      filters?: FilterExpression
-    }
-  | {
-      name: string
-      resource: string
-      select: QueryAggregateSelectItem[]
-      filters?: FilterExpression
-    }
+export type StepsQueryStepConfig = {
+  name: string
+  resource: string
+  select: QueryAggregateSelectItem[]
+  filters?: FilterExpression
+}
 
 export type StepsQueryConfig = {
   source: 'steps'

package/custom/runtime/DashboardRuntime.vue

@@ -286,7 +286,8 @@ async function addGroup() {
   }
 
   try {
-    applyDashboardResponse(await dashboardApi.addDashboardGroup(props.dashboardSlug))
+    await dashboardApi.addDashboardGroup(props.dashboardSlug)
+    await refreshDashboardConfig()
   } catch (error) {
     console.error('Failed to add dashboard group', error)
   }
@@ -298,7 +299,8 @@ async function addWidget(groupId: string) {
   }
 
   try {
-    applyDashboardResponse(await dashboardApi.addDashboardWidget(props.dashboardSlug, groupId))
+    await dashboardApi.addDashboardWidget(props.dashboardSlug, groupId)
+    await refreshDashboardConfig()
   } catch (error) {
     console.error('Failed to add dashboard widget', error)
   }
@@ -310,9 +312,8 @@ async function moveGroup(groupId: string, direction: DashboardGroupMoveDirection
   }
 
   try {
-    applyDashboardResponse(
-      await dashboardApi.moveDashboardGroup(props.dashboardSlug, groupId, direction),
-    )
+    await dashboardApi.moveDashboardGroup(props.dashboardSlug, groupId, direction)
+    await refreshDashboardConfig()
   } catch (error) {
     console.error('Failed to move dashboard group', error)
   }
@@ -324,7 +325,8 @@ async function removeGroup(groupId: string) {
   }
 
   try {
-    applyDashboardResponse(await dashboardApi.removeDashboardGroup(props.dashboardSlug, groupId))
+    await dashboardApi.removeDashboardGroup(props.dashboardSlug, groupId)
+    await refreshDashboardConfig()
   } catch (error) {
     console.error('Failed to remove dashboard group', error)
   }
@@ -348,13 +350,12 @@ async function saveGroupConfig() {
   try {
     const groupConfig = parseYaml(groupConfigCode.value) as EditableDashboardGroupConfig
 
-    applyDashboardResponse(
-      await dashboardApi.setDashboardGroupConfig(
-        props.dashboardSlug,
-        editingGroupId.value,
-        groupConfig,
-      ),
+    await dashboardApi.setDashboardGroupConfig(
+      props.dashboardSlug,
+      editingGroupId.value,
+      groupConfig,
     )
+    await refreshDashboardConfig()
     closeGroupConfigEditor()
   } catch (error) {
     groupConfigError.value = error instanceof Error ? error.message : 'Invalid group config'
@@ -373,9 +374,8 @@ async function moveWidget(widgetId: string, direction: DashboardWidgetMoveDirect
   }
 
   try {
-    applyDashboardResponse(
-      await dashboardApi.moveDashboardWidget(props.dashboardSlug, widgetId, direction),
-    )
+    await dashboardApi.moveDashboardWidget(props.dashboardSlug, widgetId, direction)
+    await refreshDashboardConfig()
   } catch (error) {
     console.error('Failed to move dashboard widget', error)
   }
@@ -387,7 +387,8 @@ async function removeWidget(widgetId: string) {
   }
 
   try {
-    applyDashboardResponse(await dashboardApi.removeDashboardWidget(props.dashboardSlug, widgetId))
+    await dashboardApi.removeDashboardWidget(props.dashboardSlug, widgetId)
+    await refreshDashboardConfig()
   } catch (error) {
     console.error('Failed to remove dashboard widget', error)
   }
@@ -410,13 +411,12 @@ async function saveWidgetConfig() {
     widgetConfigFieldErrors.value = []
     const widgetConfig = parseYaml(widgetConfigCode.value) as DashboardWidgetConfig
 
-    applyDashboardResponse(
-      await dashboardApi.setWidgetConfig(
-        props.dashboardSlug,
-        editingWidgetId.value,
-        serializeDashboardWidgetConfigForEditor(widgetConfig),
-      ),
+    await dashboardApi.setWidgetConfig(
+      props.dashboardSlug,
+      editingWidgetId.value,
+      serializeDashboardWidgetConfigForEditor(widgetConfig),
     )
+    await refreshDashboardConfig()
     closeWidgetConfigEditor()
   } catch (error) {
     widgetConfigError.value = error instanceof Error ? error.message : 'Invalid widget config'
@@ -431,6 +431,10 @@ function closeWidgetConfigEditor() {
   widgetConfigFieldErrors.value = []
 }
 
+async function refreshDashboardConfig() {
+  applyDashboardResponse(await dashboardApi.getDashboardConfig(props.dashboardSlug))
+}
+
 function applyDashboardResponse(response: DashboardResponse) {
   draftConfig.value = cloneConfig(response.config)
   currentRevision.value = response.revision

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

@@ -169,21 +169,18 @@ query:
   steps:
     - name: Leads
       resource: leads
-      metric:
-        agg: count
-        as: value
+      select:
+        - agg: count
+          as: value
     - name: Customers
       resource: orders
-      metric:
-        agg: count_distinct
-        field: customer_id
-        as: value
-
-Each step may use either:
-- metric for one aggregate
-- select for multiple aggregate fields
+      select:
+        - agg: count_distinct
+          field: customer_id
+          as: value
 
 Do not use bare query.steps without source: steps.
+Do not use metric. Use select even when a step has only one aggregate.
 
 ## Date range rules
 
@@ -224,22 +221,18 @@ select raw token totals:
 - sum output_tokens as output_tokens
 
 then query.calcs:
-- calculate total_spend from those aliases and lookup variables
+- calculate total_spend from those aliases with explicit constants
 
 For today vs yesterday KPI, use multiple aggregate select items with filters and distinct aliases, then calcs.
 
-## Calc variables
+## Calc rules
 
-Use variables for static maps/rates.
-Use lookup($variables.some.map, row_field, default_number) in query.calcs.
+Calcs can reference only fields already present in the current row.
+Use explicit constants for rates.
 
 Minimal example:
 
-variables:
-  prices:
-    gpt-5.4: 2.5
-
 query:
   calcs:
-    - calc: tokens / 1000000 * lookup($variables.prices, model, 0)
+    - calc: tokens / 1000000 * 2.5
       as: cost