@adminforth/dashboard 1.7.0 → 1.9.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/model/dashboard.types.ts

@@ -117,7 +117,8 @@ export type QueryOrderByItem = {
   direction?: 'asc' | 'desc'
 }
 
-export type QueryConfig = {
+export type ResourceQueryConfig = {
+  source?: 'resource'
   resource: string
   select?: QuerySelectItem[]
   sparkline?: {
@@ -139,18 +140,25 @@ export type QueryConfig = {
   formatting?: Record<string, JsonValue>
 }
 
-export type FunnelQueryConfig = {
-  steps: FunnelQueryStep[]
-  calcs?: QueryCalcSelectItem[]
-}
-
-export type FunnelQueryStep = {
+export type StepsQueryStepConfig = {
   name: string
   resource: string
-  metric: QueryAggregateSelectItem
+  select: QueryAggregateSelectItem[]
   filters?: FilterExpression
 }
 
+export type StepsQueryConfig = {
+  source: 'steps'
+  steps: StepsQueryStepConfig[]
+  calcs?: QueryCalcSelectItem[]
+  order_by?: QueryOrderByItem[]
+  limit?: number
+  offset?: number
+  formatting?: Record<string, JsonValue>
+}
+
+export type QueryConfig = ResourceQueryConfig | StepsQueryConfig
+
 export type FieldRef = string | {
   field: string
   label?: string
@@ -246,7 +254,7 @@ export type TableWidgetConfig = WidgetBaseConfig & {
 export type ChartDashboardWidgetConfig = WidgetBaseConfig & {
   target: 'chart'
   chart: ChartWidgetConfig
-  query: QueryConfig | FunnelQueryConfig
+  query: QueryConfig
 }
 
 export type KpiCardWidgetConfig = WidgetBaseConfig & {

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

@@ -151,8 +151,8 @@ Use resource, not resourceId.
 
 ## Query shape rules
 
-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.
+All chart widgets, including funnel charts, use the same query shape.
+Use a single-resource query by default.
 
 For kpi_card and normal charts, use:
 - query.resource
@@ -162,6 +162,26 @@ For kpi_card and normal charts, use:
 - optional query.order_by
 - optional query.calcs
 
+For multi-resource charts or widgets, use the general steps source:
+
+query:
+  source: steps
+  steps:
+    - name: Leads
+      resource: leads
+      select:
+        - agg: count
+          as: value
+    - name: Customers
+      resource: orders
+      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
 
 Use only query.filters for time ranges.
@@ -201,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. Do not use query.steps.
+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

package/dist/custom/model/dashboard.types.d.ts

@@ -87,7 +87,8 @@ export type QueryOrderByItem = {
     field: string;
     direction?: 'asc' | 'desc';
 };
-export type QueryConfig = {
+export type ResourceQueryConfig = {
+    source?: 'resource';
     resource: string;
     select?: QuerySelectItem[];
     sparkline?: {
@@ -112,16 +113,22 @@ export type QueryConfig = {
     calcs?: QueryCalcSelectItem[];
     formatting?: Record<string, JsonValue>;
 };
-export type FunnelQueryConfig = {
-    steps: FunnelQueryStep[];
-    calcs?: QueryCalcSelectItem[];
-};
-export type FunnelQueryStep = {
+export type StepsQueryStepConfig = {
     name: string;
     resource: string;
-    metric: QueryAggregateSelectItem;
+    select: QueryAggregateSelectItem[];
     filters?: FilterExpression;
 };
+export type StepsQueryConfig = {
+    source: 'steps';
+    steps: StepsQueryStepConfig[];
+    calcs?: QueryCalcSelectItem[];
+    order_by?: QueryOrderByItem[];
+    limit?: number;
+    offset?: number;
+    formatting?: Record<string, JsonValue>;
+};
+export type QueryConfig = ResourceQueryConfig | StepsQueryConfig;
 export type FieldRef = string | {
     field: string;
     label?: string;
@@ -210,7 +217,7 @@ export type TableWidgetConfig = WidgetBaseConfig & {
 export type ChartDashboardWidgetConfig = WidgetBaseConfig & {
     target: 'chart';
     chart: ChartWidgetConfig;
-    query: QueryConfig | FunnelQueryConfig;
+    query: QueryConfig;
 };
 export type KpiCardWidgetConfig = WidgetBaseConfig & {
     target: 'kpi_card';

package/dist/custom/model/dashboard.types.ts

@@ -117,7 +117,8 @@ export type QueryOrderByItem = {
   direction?: 'asc' | 'desc'
 }
 
-export type QueryConfig = {
+export type ResourceQueryConfig = {
+  source?: 'resource'
   resource: string
   select?: QuerySelectItem[]
   sparkline?: {
@@ -139,18 +140,25 @@ export type QueryConfig = {
   formatting?: Record<string, JsonValue>
 }
 
-export type FunnelQueryConfig = {
-  steps: FunnelQueryStep[]
-  calcs?: QueryCalcSelectItem[]
-}
-
-export type FunnelQueryStep = {
+export type StepsQueryStepConfig = {
   name: string
   resource: string
-  metric: QueryAggregateSelectItem
+  select: QueryAggregateSelectItem[]
   filters?: FilterExpression
 }
 
+export type StepsQueryConfig = {
+  source: 'steps'
+  steps: StepsQueryStepConfig[]
+  calcs?: QueryCalcSelectItem[]
+  order_by?: QueryOrderByItem[]
+  limit?: number
+  offset?: number
+  formatting?: Record<string, JsonValue>
+}
+
+export type QueryConfig = ResourceQueryConfig | StepsQueryConfig
+
 export type FieldRef = string | {
   field: string
   label?: string
@@ -246,7 +254,7 @@ export type TableWidgetConfig = WidgetBaseConfig & {
 export type ChartDashboardWidgetConfig = WidgetBaseConfig & {
   target: 'chart'
   chart: ChartWidgetConfig
-  query: QueryConfig | FunnelQueryConfig
+  query: QueryConfig
 }
 
 export type KpiCardWidgetConfig = WidgetBaseConfig & {