@adminforth/dashboard 1.0.0

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

@@ -0,0 +1,125 @@
+---
+name: adminforth-dashboard
+description: Use when the user wants to view, create, update, move, remove, validate, or load data for AdminForth dashboard groups and widgets.
+---
+
+# AdminForth Dashboard Plugin
+
+This skill is action-oriented. When the user asks to create, add, edit, update, move, remove, or configure dashboard entities, complete the request by calling the dashboard tools. Do not satisfy dashboard mutation requests by only showing JSON, YAML, JavaScript, TypeScript, Zod schemas, or example config snippets.
+
+## Primary Rule
+
+If callable dashboard tools are available, use them.
+
+A response that only shows a config object, schema, or code snippet is incomplete unless the user explicitly asked for a schema, code example, or explanation.
+
+For dashboard mutation requests, the expected flow is:
+
+1. Load dashboard state when needed.
+2. Choose or create the target group/widget.
+3. Call the appropriate dashboard mutation tool. (WITHOUT USER CONFIRMATION)
+4. Return a short result summary.
+
+Do not print the widget config as the main answer instead of calling tools.
+
+## User Intent Mapping
+
+Use dashboard tools for these intents:
+
+- "add/create/write/make a widget" → create and configure a widget.
+- "change/update/edit this widget" → update widget config.
+- "move this widget/group" → call the move tool.
+- "remove/delete this widget/group" → call the remove tool.
+- "show/load dashboard" → call the dashboard config tool.
+- "load/check widget data" → call the widget data tool.
+- "validate this widget config" → call validation logic/tool if available.
+
+If the user asks how the schema works, how to implement the API, or how to change backend code, then answer as a developer/code task instead of mutating the dashboard.
+
+## Callable Dashboard Tools
+
+Use these tools whenever available:
+
+- `dashboard_get_config`
+- `dashboard_add_dashboard_group`
+- `dashboard_set_dashboard_group_config`
+- `dashboard_move_dashboard_group`
+- `dashboard_remove_dashboard_group`
+- `dashboard_add_dashboard_widget`
+- `dashboard_move_dashboard_widget`
+- `dashboard_remove_dashboard_widget`
+- `dashboard_set_widget_config`
+- `dashboard_get_dashboard_widget_data`
+
+If a dashboard tool is known by name but its argument schema is not loaded, call `fetch_tool_schema` for that tool first. After the schema is loaded, call the dashboard tool. Do not guess arguments if `fetch_tool_schema` is available.
+
+## Tool Argument Rules
+
+Do not pass fields between dashboard tools by analogy. Use each tool's schema.
+
+- `dashboard_add_dashboard_group` creates a new group. It accepts the dashboard slug only. Never pass `groupId` to this tool.
+- `dashboard_add_dashboard_widget` creates a widget inside an existing group. Use it when you already have a `groupId`.
+- `dashboard_set_dashboard_group_config`, `dashboard_move_dashboard_group`, and `dashboard_remove_dashboard_group` operate on an existing group and need `groupId`.
+- `dashboard_set_widget_config`, `dashboard_move_dashboard_widget`, `dashboard_remove_dashboard_widget`, and `dashboard_get_dashboard_widget_data` operate on an existing widget and need `widgetId`.
+- If a tool call fails with "input did not match expected schema", call `fetch_tool_schema` for that exact tool, remove unsupported arguments, and retry the correct tool.
+
+## Widget Creation Workflow
+
+For requests like:
+
+- "add a table widget"
+- "create a chart"
+- "write a widget showing top 5 orders"
+- "make a widget for revenue by product"
+
+do this:
+
+1. Call `dashboard_get_config` with the requested slug, or `default` if slug is not specified.
+2. Select the requested group. If the group is not specified, use the first existing group.
+3. If there are no groups, call `dashboard_add_dashboard_group`.
+4. Call `dashboard_add_dashboard_widget` with the selected group id.
+5. Call `dashboard_set_widget_config` with the returned widget id and schema-valid config.
+6. Return a short summary with dashboard slug, group id, widget id, target, label, resource, selected fields, order, and limit.
+
+Do not stop after generating config text.
+
+## Widget Update Workflow
+
+For requests like:
+
+- "change this widget"
+- "make the chart use another field"
+- "update the widget config"
+- "turn this widget into a table"
+
+do this:
+
+1. Call `dashboard_get_config`.
+2. Find the widget by id, label, or clear context.
+3. Build the new config while preserving server-owned fields handled by the API.
+4. Call `dashboard_set_widget_config`.
+5. Return a short summary of what changed.
+
+If the widget cannot be identified, ask only for the missing widget id or label.
+
+## Group Workflow
+
+For group requests:
+
+- Add group → `dashboard_add_dashboard_group`
+- Rename/change group config → `dashboard_set_dashboard_group_config`
+- Move group → `dashboard_move_dashboard_group`
+- Remove group → `dashboard_remove_dashboard_group`
+
+If slug is missing, use `default`.
+
+## Widget Config Rules
+
+Use the current schema keys exactly:
+
+- Use `target`, not `type`.
+- Use `label`, not `title`.
+- Use `query.resource`, not `resourceId`.
+- Use `query.select`, not `columns`.
+- Use `query.order`, not `sort`.
+- Use `query.limit` for row count.

package/custom/widgets/chart/ChartWidget.vue

@@ -0,0 +1,188 @@
+<template>
+  <div class="h-full min-h-0 overflow-hidden rounded-lg bg-lightTableBackground p-3 dark:bg-darkTableBackground">
+    <div
+      v-if="isLoading"
+      class="text-sm text-lightListTableText dark:text-darkListTableText"
+    >
+      Loading...
+    </div>
+
+    <div
+      v-else-if="error"
+      class="text-sm text-lightInputErrorColor"
+    >
+      Failed to load chart data
+    </div>
+
+    <div
+      v-else-if="!rows.length"
+      class="text-sm text-lightListTableText dark:text-darkListTableText"
+    >
+      No data available
+    </div>
+
+    <LineChart
+      v-else-if="chartConfig?.type === 'line'"
+      :rows="rows"
+      :x-field="xField"
+      :y-field="yField"
+      :series-name="chartConfig.series_name"
+      :color="chartConfig.color"
+      :height="chartHeight"
+    />
+
+    <PieChart
+      v-else-if="chartConfig?.type === 'pie'"
+      :rows="pieRows"
+      :label-field="pieLabelField"
+      :value-field="pieValueField"
+      :colors="chartConfig.colors"
+      :height="chartHeight"
+    />
+
+    <BarChart
+      v-else-if="chartConfig?.type === 'bar'"
+      :rows="barRows"
+      :label-field="barLabelField"
+      :value-field="barValueField"
+      :color="chartConfig.color"
+      :height="chartHeight"
+    />
+
+    <HistogramChart
+      v-else-if="chartConfig?.type === 'histogram'"
+      :rows="barRows"
+      :label-field="barLabelField"
+      :value-field="barValueField"
+      :color="chartConfig.color"
+      :height="chartHeight"
+    />
+
+    <FunnelChart
+      v-else-if="chartConfig?.type === 'funnel'"
+      :rows="rows"
+      :label-field="labelField"
+      :value-field="valueField"
+      :colors="chartConfig.colors"
+      :height="chartHeight"
+    />
+
+    <StackedBarChart
+      v-else-if="chartConfig?.type === 'stacked_bar'"
+      :rows="rows"
+      :x-field="xField"
+      :series="stackedBarSeries"
+      :colors="chartConfig.colors"
+      :height="chartHeight"
+    />
+
+    <div
+      v-else
+      class="text-sm text-lightListTableText dark:text-darkListTableText"
+    >
+      Unsupported chart type
+    </div>
+  </div>
+</template>
+
+
+
+<script setup lang="ts">
+import { computed, watch } from 'vue'
+import { useWidgetData } from '../../queries/useWidgetData.js'
+import type { DashboardWidgetConfig, DashboardWidgetTableData } from '../../model/dashboard.types.js'
+import BarChart from './bar/BarChart.vue'
+import FunnelChart from './funnel/FunnelChart.vue'
+import HistogramChart from './histogram/HistogramChart.vue'
+import LineChart from './line/LineChart.vue'
+import PieChart from './pie/PieChart.vue'
+import StackedBarChart from './stacked-bar/StackedBarChart.vue'
+import { formatChartLabel, toFiniteNumber } from './chart.utils.js'
+
+const DEFAULT_WIDGET_HEIGHT = 500
+
+const props = defineProps<{
+  dashboardSlug: string
+  widget: DashboardWidgetConfig
+}>()
+
+const dashboardSlugRef = computed(() => props.dashboardSlug)
+const widgetIdRef = computed(() => props.widget.id)
+const {
+  data,
+  isLoading,
+  error,
+  refetch,
+} = useWidgetData(dashboardSlugRef, widgetIdRef)
+
+watch(
+  () => props.widget,
+  () => {
+    void refetch()
+  },
+  { deep: true },
+)
+
+const chartData = computed(() => data.value?.data as DashboardWidgetTableData | null)
+const rows = computed(() => chartData.value?.rows ?? [])
+const columns = computed(() => chartData.value?.columns ?? [])
+const chartConfig = computed(() => props.widget.chart)
+const xField = computed(() => chartConfig.value?.x_field || columns.value[0])
+const yField = computed(() => chartConfig.value?.y_field || columns.value[1])
+const labelField = computed(() => chartConfig.value?.label_field || columns.value[0])
+const valueField = computed(() => chartConfig.value?.value_field || columns.value[1])
+const pieRows = computed(() => {
+  if (chartConfig.value?.value_field) {
+    return rows.value
+  }
+
+  const groupedRows = new Map<string, { label: string, value: number }>()
+
+  for (const row of rows.value) {
+    const label = formatChartLabel(row[labelField.value])
+    const item = groupedRows.get(label) ?? { label, value: 0 }
+    item.value += 1
+    groupedRows.set(label, item)
+  }
+
+  return Array.from(groupedRows.values())
+})
+const pieLabelField = computed(() => chartConfig.value?.value_field ? labelField.value : 'label')
+const pieValueField = computed(() => chartConfig.value?.value_field ? valueField.value : 'value')
+const barRows = computed(() => {
+  const bucketField = chartConfig.value?.bucket_field
+
+  if (!bucketField) {
+    return rows.value
+  }
+
+  const buckets = chartConfig.value?.buckets ?? []
+
+  return buckets.map((bucket) => ({
+    label: bucket.label,
+    count: rows.value.filter((row) => {
+      const value = toFiniteNumber(row[bucketField])
+      return (bucket.min === undefined || value >= bucket.min)
+        && (bucket.max === undefined || value < bucket.max)
+    }).length,
+  }))
+})
+const barLabelField = computed(() => chartConfig.value?.bucket_field ? 'label' : labelField.value)
+const barValueField = computed(() => chartConfig.value?.bucket_field ? 'count' : valueField.value)
+const stackedBarSeries = computed(() => {
+  if (chartConfig.value?.series?.length) {
+    return chartConfig.value.series
+  }
+
+  return columns.value
+    .filter((column) => column !== xField.value)
+    .map((column) => ({
+      name: column,
+      field: column,
+    }))
+})
+
+const chartHeight = computed(() => {
+  return Math.max((props.widget.height ?? DEFAULT_WIDGET_HEIGHT) - 24, 96)
+})
+</script>

package/custom/widgets/chart/bar/BarChart.vue

@@ -0,0 +1,167 @@
+<template>
+  <div
+    ref="rootEl"
+    class="h-full min-h-0 w-full overflow-hidden"
+  >
+    <svg
+      v-if="chartWidth > 0 && chartHeight > 0"
+      class="block h-full w-full"
+      :viewBox="`0 0 ${chartWidth} ${chartHeight}`"
+      role="img"
+      :aria-label="valueField"
+    >
+      <g class="text-lightListTableText dark:text-darkListTableText">
+        <line
+          v-for="tick in yTicks"
+          :key="tick.y"
+          :x1="padding.left"
+          :x2="chartWidth - padding.right"
+          :y1="tick.y"
+          :y2="tick.y"
+          stroke="currentColor"
+          stroke-opacity="0.14"
+        />
+        <text
+          v-for="tick in yTicks"
+          :key="`label-${tick.y}`"
+          :x="padding.left - 8"
+          :y="tick.y + 4"
+          fill="currentColor"
+          font-size="11"
+          text-anchor="end"
+        >
+          {{ formatChartValue(tick.value) }}
+        </text>
+      </g>
+
+      <rect
+        v-for="bar in bars"
+        :key="bar.label"
+        :x="bar.x"
+        :y="bar.y"
+        :width="barWidth"
+        :height="bar.height"
+        :fill="chartColor"
+        rx="5"
+      >
+        <title>{{ bar.label }}: {{ formatChartValue(bar.value) }}</title>
+      </rect>
+
+      <g class="text-lightListTableText dark:text-darkListTableText">
+        <text
+          v-for="(bar, barIndex) in bars"
+          v-show="visibleLabelIndexes.has(barIndex)"
+          :key="`x-${bar.label}`"
+          :x="bar.x + barWidth / 2"
+          :y="padding.top + innerHeight + 24"
+          fill="currentColor"
+          font-size="11"
+          text-anchor="middle"
+        >
+          {{ bar.axisLabel }}
+        </text>
+        <text
+          v-for="bar in bars"
+          v-show="barWidth >= 18"
+          :key="`value-${bar.label}`"
+          :x="bar.x + barWidth / 2"
+          :y="Math.max(bar.y - 8, 12)"
+          fill="currentColor"
+          font-size="11"
+          font-weight="600"
+          text-anchor="middle"
+        >
+          {{ formatChartValue(bar.value) }}
+        </text>
+      </g>
+    </svg>
+  </div>
+</template>
+
+
+
+<script setup lang="ts">
+import { computed } from 'vue'
+import { useElementSize } from '../../../composables/useElementSize.js'
+import { CHART_COLORS, formatChartAxisLabel, formatChartLabel, formatChartValue, toFiniteNumber } from '../chart.utils.js'
+
+const props = withDefaults(defineProps<{
+  rows: Record<string, unknown>[]
+  labelField: string
+  valueField: string
+  color?: string
+  height?: number
+}>(), {
+  height: 260,
+})
+
+const { el: rootEl, width: rootWidth, height: rootHeight } = useElementSize<HTMLDivElement>()
+
+const padding = {
+  top: 20,
+  right: 6,
+  bottom: 34,
+  left: 38,
+}
+const chartWidth = computed(() => Math.max(rootWidth.value, 1))
+const chartHeight = computed(() => {
+  if (rootHeight.value > 0) {
+    return Math.max(rootHeight.value, 1)
+  }
+
+  return Math.max(props.height, 1)
+})
+
+const chartColor = computed(() => props.color || CHART_COLORS[0])
+const values = computed(() => props.rows.map((row) => toFiniteNumber(row[props.valueField])))
+const maxValue = computed(() => Math.max(...values.value, 1))
+const innerWidth = computed(() => Math.max(chartWidth.value - padding.left - padding.right, 1))
+const innerHeight = computed(() => Math.max(chartHeight.value - padding.top - padding.bottom, 1))
+const barGap = 12
+const barWidth = computed(() => {
+  const count = Math.max(props.rows.length, 1)
+  return Math.max(Math.min((innerWidth.value - barGap * (count - 1)) / count, 80), 4)
+})
+const totalChartWidth = computed(() => {
+  const count = Math.max(props.rows.length, 1)
+  return count * barWidth.value + (count - 1) * barGap
+})
+const chartStartX = computed(() => padding.left + Math.max((innerWidth.value - totalChartWidth.value) / 2, 0))
+const visibleLabelIndexes = computed(() => {
+  const count = props.rows.length
+  const approxLabelWidth = 52
+  const maxLabels = Math.max(2, Math.floor(innerWidth.value / approxLabelWidth))
+
+  if (count <= maxLabels || barWidth.value >= 44) {
+    return new Set(props.rows.map((_, index) => index))
+  }
+
+  const indexes = new Set<number>()
+  const step = (count - 1) / (maxLabels - 1)
+
+  for (let index = 0; index < maxLabels; index += 1) {
+    indexes.add(Math.round(index * step))
+  }
+
+  return indexes
+})
+
+const bars = computed(() => props.rows.map((row, index) => {
+  const value = values.value[index]
+  const height = (value / maxValue.value) * innerHeight.value
+
+  return {
+    label: formatChartLabel(row[props.labelField]),
+    axisLabel: formatChartAxisLabel(row[props.labelField]),
+    value,
+    x: chartStartX.value + index * (barWidth.value + barGap),
+    y: padding.top + innerHeight.value - height,
+    height,
+  }
+}))
+
+const yTicks = computed(() => [0, 0.5, 1].map((ratio) => ({
+  value: maxValue.value * (1 - ratio),
+  y: padding.top + innerHeight.value * ratio,
+})))
+</script>

package/custom/widgets/chart/chart.types.ts

@@ -0,0 +1,34 @@
+export type ChartWidgetType =
+  | 'line'
+  | 'pie'
+  | 'bar'
+  | 'stacked_bar'
+  | 'funnel'
+  | 'histogram'
+
+export type ChartWidgetBucketConfig = {
+  label: string
+  min?: number
+  max?: number
+}
+
+export type ChartWidgetSeriesConfig = {
+  name: string
+  field: string
+  color?: string
+}
+
+export type ChartWidgetConfig = {
+  type: ChartWidgetType
+  title?: string
+  x_field?: string
+  y_field?: string
+  label_field?: string
+  value_field?: string
+  bucket_field?: string
+  buckets?: ChartWidgetBucketConfig[]
+  series?: ChartWidgetSeriesConfig[]
+  series_name?: string
+  color?: string
+  colors?: string[]
+}

package/custom/widgets/chart/chart.utils.ts

@@ -0,0 +1,54 @@
+export const CHART_COLORS = [
+  '#2563eb',
+  '#16a34a',
+  '#f97316',
+  '#dc2626',
+  '#7c3aed',
+  '#0891b2',
+  '#ca8a04',
+  '#db2777',
+]
+
+export function toFiniteNumber(value: unknown) {
+  const numberValue = typeof value === 'number' ? value : Number(value)
+  return Number.isFinite(numberValue) ? numberValue : 0
+}
+
+export function formatChartValue(value: number) {
+  return new Intl.NumberFormat().format(value)
+}
+
+export function formatChartLabel(value: unknown) {
+  if (typeof value !== 'string') {
+    return String(value)
+  }
+
+  const timestamp = Date.parse(value)
+
+  if (!Number.isFinite(timestamp)) {
+    return value
+  }
+
+  return new Intl.DateTimeFormat(undefined, {
+    year: 'numeric',
+    month: 'short',
+    day: '2-digit',
+  }).format(new Date(timestamp))
+}
+
+export function formatChartAxisLabel(value: unknown, maxLength = 12) {
+  const rawLabel = typeof value === 'string' ? value : String(value)
+  const timestamp = Date.parse(rawLabel)
+  const label = Number.isFinite(timestamp)
+    ? new Intl.DateTimeFormat(undefined, {
+        month: 'short',
+        day: 'numeric',
+      }).format(new Date(timestamp))
+    : rawLabel
+
+  if (label.length <= maxLength) {
+    return label
+  }
+
+  return `${label.slice(0, Math.max(maxLength - 1, 1))}…`
+}