@adminforth/dashboard 1.2.0 → 1.4.0

package/README.md

@@ -29,62 +29,139 @@ 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)`. |
 | `size` | Preset width: `small`, `medium`, `large`, `wide`, or `full`. |
 | `width`, `height`, `min_width`, `max_width` | Optional explicit layout constraints. |
-| `data_source` | Resource or aggregate data source definition. |
+| `query` | Data query definition. |
 
 ## Widget Support Matrix
 
 | Widget target | Config field | Main settings | Data usage |
 | --- | --- | --- | --- |
-| `table` | `table` | `pagination`, `page_size` | Uses `data_source.type = 'resource'` to display resource rows with backend pagination unless `pagination` is `false`. |
-| `chart` | `chart` | `type`, `x_field`, `y_field`, `label_field`, `value_field`, `bucket_field`, `buckets`, `series`, `series_name`, `color`, `colors` | Uses `data_source.type = 'aggregate'` with `group_by`. |
-| `kpi_card` | `kpi_card` | `value_field`, `label_field`, `prefix`, `suffix` | Reads aggregate values or the first returned row from `data_source`. |
-| `gauge_card` | `gauge_card` | `value_field`, `min`, `max`, `min_field`, `max_field`, `suffix`, `color` | Reads aggregate values or the first returned row from `data_source` and renders progress between static or field-driven bounds. |
-| `pivot_table` | `pivot_table` | `row_field`, `column_field`, `value_field`, `aggregation` | Uses grouped aggregate rows from `data_source.type = 'aggregate'`. `aggregation` supports `count` and `sum`. |
+| `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`. |
+| `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. |
 
 Chart widget types:
 
 | Chart type | Notes |
 | --- | --- |
-| `line` | Uses `x_field` and `y_field`; optional `series_name` and `color`. |
-| `pie` | Uses `label_field` and optional `value_field`; without `value_field`, rows are counted by label. |
-| `bar` | Uses `label_field` and `value_field`, or `bucket_field` with `buckets`. |
-| `stacked_bar` | Uses `x_field` and `series`; if `series` is omitted, non-x columns become series. |
-| `funnel` | Uses `label_field`, `value_field`, and optional `colors`. |
-| `histogram` | Uses the same bucket settings as `bar`. |
+| `line` | Uses `x` and `y`; `y` may contain multiple fields in config. |
+| `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`. |
+| `histogram` | Uses `x`, `y`, and optional `buckets`. |
 
-## Data Source Shape
+## Query Shape
 
 ```ts
-type WidgetDataSource =
-  | {
-      type: 'resource'
-      resource_id: string
-      columns?: string[]
-      filters?: unknown
-      sort?: unknown
-    }
-  | {
-      type: 'aggregate'
-      resource_id: string
-      aggregations: Record<string, {
-        operation: 'sum' | 'count' | 'avg' | 'min' | 'max' | 'median'
-        field?: string
-      }>
-      group_by?:
-        | { type: 'field'; field: string }
-        | {
-            type: 'date_trunc'
-            field: string
-            truncation: 'day' | 'week' | 'month' | 'year'
-            timezone?: string
-          }
-      filters?: unknown
-    }
+type QueryConfig = {
+  resource: string
+  select?: Array<
+    | { field: string; as?: string; grain?: 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year' }
+    | { agg: 'sum' | 'count' | 'count_distinct' | 'avg' | 'min' | 'max' | 'median'; field?: string; as: string; filters?: unknown }
+    | { calc: string; as: string }
+  >
+  filters?: unknown
+  group_by?: Array<string | { field: string; as?: string; grain?: 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year'; timezone?: string }>
+  order_by?: Array<{ field: string; direction?: 'asc' | 'desc' }>
+  limit?: number
+  offset?: number
+}
+```
+
+Step-based chart queries use `steps` and may include `calcs`:
+
+```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
+query:
+  steps:
+    - name: SQLite
+      resource: cars_sl
+      metric:
+        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
 ```
 
-  `resource_id` is an AdminForth `resourceId`. The data source is executed through AdminForth resources, so widgets use the same resource contracts as the rest of the application.
+Widget-level variables 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
+  x:
+    field: model
+  y:
+    - field: input_cost
+    - field: output_cost
+    - field: cached_cost
+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
+```
 
 ## Runtime Structure
 

package/custom/api/dashboardApi.ts

@@ -143,6 +143,10 @@ export const dashboardApi = {
     return callDashboardApi('/adminapi/v1/dashboard/get-config', { slug })
   },
 
+  async setDashboardConfig(slug: string, config: DashboardConfig): Promise<DashboardResponse> {
+    return callDashboardApi('/adminapi/v1/dashboard/set_dashboard_config', { slug, config })
+  },
+
   async addDashboardGroup(slug: string): Promise<DashboardResponse> {
     return callDashboardApi('/adminapi/v1/dashboard/add_dashboard_group', { slug })
   },

package/custom/composables/useElementSize.ts

@@ -13,6 +13,7 @@ export function useElementSize<T extends HTMLElement>(): ElementSizeState<T> {
   const height = ref(0)
 
   let observer: ResizeObserver | undefined
+  let frameId: number | undefined
 
   onMounted(() => {
     observer = new ResizeObserver(([entry]) => {
@@ -20,8 +21,18 @@ export function useElementSize<T extends HTMLElement>(): ElementSizeState<T> {
         return
       }
 
-      width.value = Math.floor(entry.contentRect.width)
-      height.value = Math.floor(entry.contentRect.height)
+      const nextWidth = Math.floor(entry.contentRect.width)
+      const nextHeight = Math.floor(entry.contentRect.height)
+
+      if (frameId !== undefined) {
+        cancelAnimationFrame(frameId)
+      }
+
+      frameId = requestAnimationFrame(() => {
+        frameId = undefined
+        width.value = nextWidth
+        height.value = nextHeight
+      })
     })
 
     if (el.value) {
@@ -30,6 +41,10 @@ export function useElementSize<T extends HTMLElement>(): ElementSizeState<T> {
   })
 
   onBeforeUnmount(() => {
+    if (frameId !== undefined) {
+      cancelAnimationFrame(frameId)
+    }
+
     observer?.disconnect()
   })