@adminforth/dashboard 1.5.0 → 1.7.0

package/dist/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

package/dist/custom/widgets/KpiCardWidget.vue

@@ -16,14 +16,68 @@
 
     <div
       v-else
-      class="grid gap-1"
+      class="grid gap-3"
     >
-      <div class="text-3xl font-bold text-lightNavbarText dark:text-darkNavbarText">
-        {{ formattedValue }}
-      </div>
-      <div class="text-sm text-lightListTableText dark:text-darkListTableText">
-        {{ label }}
+      <div class="grid gap-1">
+        <div class="text-3xl font-bold text-lightNavbarText dark:text-darkNavbarText">
+          {{ formattedValue }}
+        </div>
+        <div class="flex flex-wrap items-center gap-2 text-sm text-lightListTableText dark:text-darkListTableText">
+          <span>{{ label }}</span>
+          <span
+            v-if="comparison"
+            class="rounded px-1.5 py-0.5 text-xs font-medium"
+            :class="comparisonClass"
+            :title="comparison.tooltip"
+          >
+            {{ comparison.label }}
+          </span>
+        </div>
       </div>
+      <svg
+        v-if="sparklinePoints"
+        class="h-12 w-full overflow-visible"
+        viewBox="0 0 100 32"
+        preserveAspectRatio="none"
+        aria-hidden="true"
+      >
+        <defs v-if="usesSparklineGradient">
+          <linearGradient
+            :id="sparklineGradientId"
+            x1="0"
+            y1="0"
+            x2="0"
+            y2="1"
+          >
+            <stop
+              offset="0%"
+              stop-color="currentColor"
+              stop-opacity="0.24"
+            />
+            <stop
+              offset="100%"
+              stop-color="currentColor"
+              stop-opacity="0"
+            />
+          </linearGradient>
+        </defs>
+        <polygon
+          v-if="usesSparklineGradient"
+          class="text-lightPrimary dark:text-darkPrimary"
+          :points="sparklineFillPoints"
+          :fill="`url(#${sparklineGradientId})`"
+        />
+        <polyline
+          class="text-lightPrimary dark:text-darkPrimary"
+          :points="sparklinePoints"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="2"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+          vector-effect="non-scaling-stroke"
+        />
+      </svg>
     </div>
   </div>
 </template>
@@ -61,11 +115,120 @@ watch(
 const kpiConfig = computed(() => props.widget.target === 'kpi_card' ? props.widget.card : undefined)
 const widgetData = computed(() => data.value?.data as DashboardWidgetTableData | null)
 const columns = computed(() => widgetData.value?.columns ?? [])
-const firstRow = computed(() => widgetData.value?.rows[0] ?? {})
+const firstRow = computed(() => widgetData.value?.values ?? widgetData.value?.rows[0] ?? {})
 const valueField = computed(() => kpiConfig.value?.value.field || columns.value[0])
 const value = computed(() => toFiniteNumber(firstRow.value[valueField.value]))
 const label = computed(() => kpiConfig.value?.subtitle?.field
-  ? String(firstRow.value[kpiConfig.value.subtitle.field])
+  ? [kpiConfig.value.subtitle.text, formatValue(firstRow.value[kpiConfig.value.subtitle.field], kpiConfig.value.value.format)]
+      .filter(Boolean)
+      .join(': ')
   : kpiConfig.value?.subtitle?.text ?? kpiConfig.value?.title ?? props.widget.label)
-const formattedValue = computed(() => `${kpiConfig.value?.value.prefix ?? ''}${formatChartValue(value.value)}${kpiConfig.value?.value.suffix ?? ''}`)
+const formattedValue = computed(() => `${kpiConfig.value?.value.prefix ?? ''}${formatValue(value.value, kpiConfig.value?.value.format)}${kpiConfig.value?.value.suffix ?? ''}`)
+const comparisonValue = computed(() => toFiniteNumber(kpiConfig.value?.comparison?.field
+  ? firstRow.value[kpiConfig.value.comparison.field]
+  : undefined))
+const comparison = computed(() => {
+  const config = kpiConfig.value?.comparison
+
+  if (!config) {
+    return null
+  }
+
+  const template = config.compact?.template ?? '{sign}{value}'
+  const tooltipTemplate = config.tooltip?.template
+  const valueText = formatValue(Math.abs(comparisonValue.value), config.format, { signed: false, compactTemplate: true })
+  const sign = comparisonValue.value > 0 ? '+' : comparisonValue.value < 0 ? '-' : ''
+
+  return {
+    value: comparisonValue.value,
+    label: config.compact?.show === false ? valueText : applyTemplate(template, sign, valueText),
+    tooltip: tooltipTemplate
+      ? applyTemplate(tooltipTemplate, sign, valueText)
+      : config.tooltip?.label,
+    positiveIsGood: config.positive_is_good ?? true,
+  }
+})
+const comparisonClass = computed(() => {
+  if (!comparison.value || comparison.value.value === 0) {
+    return 'bg-lightListBorder text-lightListTableText dark:bg-darkListBorder dark:text-darkListTableText'
+  }
+
+  const isGood = comparison.value.positiveIsGood
+    ? comparison.value.value > 0
+    : comparison.value.value < 0
+
+  return isGood
+    ? 'bg-green-100 text-green-700 dark:bg-green-900/30 dark:text-green-300'
+    : 'bg-red-100 text-red-700 dark:bg-red-900/30 dark:text-red-300'
+})
+const sparklineRows = computed(() => widgetData.value?.rows ?? [])
+const sparklineConfig = computed(() => kpiConfig.value?.sparkline)
+const sparklineGradientId = computed(() => `kpi-sparkline-${props.widget.id}`)
+const usesSparklineGradient = computed(() => sparklineConfig.value?.fill?.type === 'gradient')
+const sparklineCoordinates = computed(() => {
+  const field = sparklineConfig.value?.field
+
+  if (!field || sparklineRows.value.length < 2) {
+    return []
+  }
+
+  const values = sparklineRows.value.map((row) => toFiniteNumber(row[field]))
+  const min = Math.min(...values)
+  const max = Math.max(...values)
+  const range = max - min || 1
+
+  return values.map((item, index) => ({
+    x: (index / Math.max(values.length - 1, 1)) * 100,
+    y: 30 - ((item - min) / range) * 28,
+  }))
+})
+const sparklinePoints = computed(() => sparklineCoordinates.value.length
+  ? sparklineCoordinates.value.map((point) => `${point.x},${point.y}`).join(' ')
+  : '')
+const sparklineFillPoints = computed(() => sparklineCoordinates.value.length
+  ? `0,32 ${sparklinePoints.value} 100,32`
+  : '')
+
+function applyTemplate(template: string, sign: string, value: string) {
+  return template
+    .replaceAll('{sign}', sign)
+    .replaceAll('{value}', value)
+}
+
+function formatValue(
+  rawValue: unknown,
+  format = 'number',
+  options: { signed?: boolean, compactTemplate?: boolean } = {},
+) {
+  const numericValue = toFiniteNumber(rawValue)
+  const sign = options.signed && numericValue > 0 ? '+' : ''
+  const absoluteValue = options.signed ? Math.abs(numericValue) : numericValue
+
+  if (format === 'integer') {
+    return `${sign}${formatChartValue(absoluteValue, { maximumFractionDigits: 0 })}`
+  }
+
+  if (format === 'compact_number') {
+    return `${sign}${formatChartValue(absoluteValue, { notation: 'compact', maximumFractionDigits: 1 })}`
+  }
+
+  if (format === 'currency' || format === 'currency_delta') {
+    return `${sign}${formatChartValue(absoluteValue, {
+      style: 'currency',
+      currency: 'USD',
+      maximumFractionDigits: 2,
+    })}`
+  }
+
+  if (format === 'percent' || format === 'percent_delta') {
+    const value = formatChartValue(absoluteValue, { maximumFractionDigits: 1 })
+    return options.compactTemplate ? value : `${sign}${value}%`
+  }
+
+  if (format === 'number_delta') {
+    return `${sign}${formatChartValue(absoluteValue, { maximumFractionDigits: 2 })}`
+  }
+
+  return `${sign}${formatChartValue(absoluteValue, { maximumFractionDigits: 2 })}`
+}
 </script>

package/dist/custom/widgets/chart/ChartWidget.vue

@@ -83,11 +83,11 @@
 import { computed, watch } from 'vue'
 import { useWidgetData } from '../../queries/useWidgetData.js'
 import type { ChartDashboardWidgetConfig, DashboardWidgetTableData } from '../../model/dashboard.types.js'
-import BarChart from './bar/BarChart.vue'
-import FunnelChart from './funnel/FunnelChart.vue'
-import LineChart from './line/LineChart.vue'
-import PieChart from './pie/PieChart.vue'
-import StackedBarChart from './stacked-bar/StackedBarChart.vue'
+import BarChart from './BarChart.vue'
+import FunnelChart from './FunnelChart.vue'
+import LineChart from './LineChart.vue'
+import PieChart from './PieChart.vue'
+import StackedBarChart from './StackedBarChart.vue'
 import { toFiniteNumber } from './chart.utils.js'
 
 const DEFAULT_WIDGET_HEIGHT = 500

package/dist/custom/widgets/registry.js

@@ -1,8 +1,8 @@
 import ChartWidget from './chart/ChartWidget.vue';
-import GaugeCardWidget from './gauge-card/GaugeCardWidget.vue';
-import KpiCardWidget from './kpi-card/KpiCardWidget.vue';
-import PivotTableWidget from './pivot-table/PivotTableWidget.vue';
-import TableWidget from './table/TableWidget.vue';
+import GaugeCardWidget from './GaugeCardWidget.vue';
+import KpiCardWidget from './KpiCardWidget.vue';
+import PivotTableWidget from './PivotTableWidget.vue';
+import TableWidget from './TableWidget.vue';
 export const widgetRegistry = [
     {
         type: 'table',

package/dist/custom/widgets/registry.ts

@@ -1,10 +1,10 @@
 import type { Component } from 'vue'
 import type { DashboardWidgetTarget } from '../model/dashboard.types.js'
 import ChartWidget from './chart/ChartWidget.vue'
-import GaugeCardWidget from './gauge-card/GaugeCardWidget.vue'
-import KpiCardWidget from './kpi-card/KpiCardWidget.vue'
-import PivotTableWidget from './pivot-table/PivotTableWidget.vue'
-import TableWidget from './table/TableWidget.vue'
+import GaugeCardWidget from './GaugeCardWidget.vue'
+import KpiCardWidget from './KpiCardWidget.vue'
+import PivotTableWidget from './PivotTableWidget.vue'
+import TableWidget from './TableWidget.vue'
 
 export type DashboardWidgetType = DashboardWidgetTarget
 

package/dist/endpoint/widgets.js

@@ -8,7 +8,53 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 import { randomUUID } from 'crypto';
-import { DashboardApiResponseSchema, DashboardWidgetDataResponseSchema, GroupIdRequestSchema, MoveWidgetRequestSchema, SetWidgetConfigRequestSchema, WidgetDataRequestSchema, WidgetIdRequestSchema, } from '../schema/api.js';
+import { ConfigureBarChartWidgetRequestSchema, ConfigureFunnelChartWidgetRequestSchema, ConfigureGaugeCardWidgetRequestSchema, ConfigureHistogramChartWidgetRequestSchema, ConfigureKpiCardWidgetRequestSchema, ConfigureLineChartWidgetRequestSchema, ConfigurePieChartWidgetRequestSchema, ConfigurePivotTableWidgetRequestSchema, ConfigureStackedBarChartWidgetRequestSchema, ConfigureTableWidgetRequestSchema, DashboardApiResponseSchema, DashboardWidgetDataResponseSchema, GroupIdRequestSchema, MoveWidgetRequestSchema, SetWidgetConfigRequestSchema, WidgetDataRequestSchema, WidgetIdRequestSchema, } from '../schema/api.js';
+function replaceWidgetConfig(ctx, slug, widgetId, widgetConfig) {
+    return __awaiter(this, void 0, void 0, function* () {
+        let mutationError = null;
+        const updatedDashboard = yield ctx.updateDashboardConfig(slug, (config) => {
+            const widget = config.widgets.find((item) => item.id === widgetId);
+            if (!widget) {
+                mutationError = 'Dashboard widget not found';
+                return null;
+            }
+            const nextWidget = Object.assign(Object.assign({}, widgetConfig), { id: widget.id, group_id: widget.group_id, order: widget.order });
+            return Object.assign(Object.assign({}, config), { widgets: config.widgets.map((item) => item.id === widgetId
+                    ? nextWidget
+                    : item) });
+        });
+        return {
+            updatedDashboard,
+            mutationError,
+        };
+    });
+}
+function registerConfigureWidgetEndpoint(server, ctx, options) {
+    server.endpoint({
+        method: 'POST',
+        path: options.path,
+        description: options.description,
+        request_schema: options.requestSchema,
+        response_schema: DashboardApiResponseSchema,
+        handler: (_a) => __awaiter(this, [_a], void 0, function* ({ body, adminUser, response }) {
+            if (!ctx.canEditDashboard(adminUser)) {
+                response.setStatus(403);
+                return { error: 'Dashboard edit is not allowed' };
+            }
+            const request = body;
+            const { updatedDashboard, mutationError } = yield replaceWidgetConfig(ctx, request.slug, request.widgetId, request.config);
+            if (!updatedDashboard) {
+                response.setStatus(404);
+                return { error: 'Dashboard not found' };
+            }
+            if (mutationError) {
+                response.setStatus(404);
+                return { error: mutationError };
+            }
+            return updatedDashboard;
+        }),
+    });
+}
 export function registerWidgetEndpoints(server, ctx) {
     server.endpoint({
         method: 'POST',
@@ -138,19 +184,8 @@ export function registerWidgetEndpoints(server, ctx) {
                 response.setStatus(403);
                 return { error: 'Dashboard edit is not allowed' };
             }
-            let mutationError = null;
-            const updatedDashboard = yield ctx.updateDashboardConfig(body.slug, (config) => {
-                const widget = config.widgets.find((item) => item.id === body.widgetId);
-                if (!widget) {
-                    mutationError = 'Dashboard widget not found';
-                    return null;
-                }
-                const typedWidgetConfig = body.config;
-                const nextWidget = Object.assign(Object.assign({}, typedWidgetConfig), { id: widget.id, group_id: widget.group_id, order: widget.order });
-                return Object.assign(Object.assign({}, config), { widgets: config.widgets.map((item) => item.id === body.widgetId
-                        ? nextWidget
-                        : item) });
-            });
+            const request = body;
+            const { updatedDashboard, mutationError } = yield replaceWidgetConfig(ctx, request.slug, request.widgetId, request.config);
             if (!updatedDashboard) {
                 response.setStatus(404);
                 return { error: 'Dashboard not found' };
@@ -162,6 +197,56 @@ export function registerWidgetEndpoints(server, ctx) {
             return updatedDashboard;
         }),
     });
+    registerConfigureWidgetEndpoint(server, ctx, {
+        path: '/dashboard/configure_table_widget',
+        description: 'Configures an existing dashboard widget as a table. Superadmin only.',
+        requestSchema: ConfigureTableWidgetRequestSchema,
+    });
+    registerConfigureWidgetEndpoint(server, ctx, {
+        path: '/dashboard/configure_kpi_card_widget',
+        description: 'Configures an existing dashboard widget as a KPI card. Superadmin only.',
+        requestSchema: ConfigureKpiCardWidgetRequestSchema,
+    });
+    registerConfigureWidgetEndpoint(server, ctx, {
+        path: '/dashboard/configure_gauge_card_widget',
+        description: 'Configures an existing dashboard widget as a gauge card. Superadmin only.',
+        requestSchema: ConfigureGaugeCardWidgetRequestSchema,
+    });
+    registerConfigureWidgetEndpoint(server, ctx, {
+        path: '/dashboard/configure_pivot_table_widget',
+        description: 'Configures an existing dashboard widget as a pivot table. Superadmin only.',
+        requestSchema: ConfigurePivotTableWidgetRequestSchema,
+    });
+    registerConfigureWidgetEndpoint(server, ctx, {
+        path: '/dashboard/configure_line_chart_widget',
+        description: 'Configures an existing dashboard widget as a line chart. Superadmin only.',
+        requestSchema: ConfigureLineChartWidgetRequestSchema,
+    });
+    registerConfigureWidgetEndpoint(server, ctx, {
+        path: '/dashboard/configure_bar_chart_widget',
+        description: 'Configures an existing dashboard widget as a bar chart. Superadmin only.',
+        requestSchema: ConfigureBarChartWidgetRequestSchema,
+    });
+    registerConfigureWidgetEndpoint(server, ctx, {
+        path: '/dashboard/configure_stacked_bar_chart_widget',
+        description: 'Configures an existing dashboard widget as a stacked bar chart. Superadmin only.',
+        requestSchema: ConfigureStackedBarChartWidgetRequestSchema,
+    });
+    registerConfigureWidgetEndpoint(server, ctx, {
+        path: '/dashboard/configure_pie_chart_widget',
+        description: 'Configures an existing dashboard widget as a pie chart. Superadmin only.',
+        requestSchema: ConfigurePieChartWidgetRequestSchema,
+    });
+    registerConfigureWidgetEndpoint(server, ctx, {
+        path: '/dashboard/configure_histogram_chart_widget',
+        description: 'Configures an existing dashboard widget as a histogram chart. Superadmin only.',
+        requestSchema: ConfigureHistogramChartWidgetRequestSchema,
+    });
+    registerConfigureWidgetEndpoint(server, ctx, {
+        path: '/dashboard/configure_funnel_chart_widget',
+        description: 'Configures an existing dashboard widget as a funnel chart. Superadmin only.',
+        requestSchema: ConfigureFunnelChartWidgetRequestSchema,
+    });
     server.endpoint({
         method: 'POST',
         path: '/dashboard/get_dashboard_widget_data',