@adminforth/dashboard 1.0.0

package/schema/widget.ts

@@ -0,0 +1,159 @@
+import { z } from 'zod'
+
+export type DashboardWidgetConfigValidationError = {
+  field: string
+  message: string
+}
+
+const DashboardWidgetSizeSchema = z.enum([
+  'small',
+  'medium',
+  'large',
+  'wide',
+  'full',
+])
+
+const WidgetBaseSchema = z.object({
+  id: z.string().optional(),
+  group_id: z.string().optional(),
+  label: z.string().optional(),
+  size: DashboardWidgetSizeSchema.optional(),
+  width: z.number().positive('Width must be greater than 0').optional(),
+  height: z.number().positive('Height must be greater than 0').optional(),
+  minWidth: z.number().nonnegative('Min width must be a non-negative number').optional(),
+  maxWidth: z.number().nonnegative('Max width must be a non-negative number').nullable().optional(),
+  order: z.number().optional(),
+})
+
+const ChartBaseSchema = z.object({
+  title: z.string().optional(),
+})
+
+const ChartBucketSchema = z.object({
+  label: z.string().min(1, 'Bucket label is required'),
+  min: z.number().optional(),
+  max: z.number().optional(),
+})
+
+const ChartSeriesSchema = z.object({
+  name: z.string().min(1, 'Series name is required'),
+  field: z.string().min(1, 'Series field is required'),
+  color: z.string().optional(),
+})
+
+const LineChartSchema = ChartBaseSchema.extend({
+  type: z.literal('line'),
+  x_field: z.string().optional(),
+  y_field: z.string().optional(),
+  series_name: z.string().optional(),
+  color: z.string().optional(),
+})
+
+const BarChartSchema = ChartBaseSchema.extend({
+  type: z.literal('bar'),
+  label_field: z.string().optional(),
+  value_field: z.string().optional(),
+  bucket_field: z.string().optional(),
+  buckets: z.array(ChartBucketSchema).optional(),
+  color: z.string().optional(),
+})
+
+const StackedBarChartSchema = ChartBaseSchema.extend({
+  type: z.literal('stacked_bar'),
+  x_field: z.string().optional(),
+  series: z.array(ChartSeriesSchema).optional(),
+  colors: z.array(z.string()).optional(),
+})
+
+const PieChartSchema = ChartBaseSchema.extend({
+  type: z.literal('pie'),
+  label_field: z.string().optional(),
+  value_field: z.string().optional(),
+  colors: z.array(z.string()).optional(),
+})
+
+const HistogramChartSchema = ChartBaseSchema.extend({
+  type: z.literal('histogram'),
+  label_field: z.string().optional(),
+  value_field: z.string().optional(),
+  bucket_field: z.string().optional(),
+  buckets: z.array(ChartBucketSchema).optional(),
+  color: z.string().optional(),
+})
+
+const FunnelChartSchema = ChartBaseSchema.extend({
+  type: z.literal('funnel'),
+  label_field: z.string().optional(),
+  value_field: z.string().optional(),
+  colors: z.array(z.string()).optional(),
+})
+
+export const ChartConfigSchema = z.discriminatedUnion('type', [
+  LineChartSchema,
+  BarChartSchema,
+  StackedBarChartSchema,
+  PieChartSchema,
+  HistogramChartSchema,
+  FunnelChartSchema,
+])
+
+export const DashboardWidgetQuerySchema = z.object({
+  resource: z.string().min(1, 'Query resource must be a non-empty string'),
+  select: z.array(z.string()).optional(),
+  order: z.object({
+    field: z.string().min(1, 'Order field is required'),
+    direction: z.enum(['asc', 'desc']),
+  }).optional(),
+  limit: z.number().optional(),
+})
+
+export const EmptyWidgetConfigSchema = WidgetBaseSchema.extend({
+  target: z.literal('empty'),
+})
+
+const TableWidgetConfigSchema = WidgetBaseSchema.extend({
+  target: z.literal('table'),
+  table: z.unknown().optional(),
+  query: DashboardWidgetQuerySchema.optional(),
+})
+
+const ChartWidgetTargetConfigSchema = WidgetBaseSchema.extend({
+  target: z.literal('chart'),
+  chart: ChartConfigSchema,
+  query: DashboardWidgetQuerySchema,
+})
+
+const KpiCardWidgetConfigSchema = WidgetBaseSchema.extend({
+  target: z.literal('kpi_card'),
+  kpi_card: z.unknown().optional(),
+  query: DashboardWidgetQuerySchema.optional(),
+})
+
+const GaugeCardWidgetConfigSchema = WidgetBaseSchema.extend({
+  target: z.literal('gauge_card'),
+  gauge_card: z.unknown().optional(),
+  query: DashboardWidgetQuerySchema.optional(),
+})
+
+const PivotTableWidgetConfigSchema = WidgetBaseSchema.extend({
+  target: z.literal('pivot_table'),
+  pivot_table: z.unknown().optional(),
+  query: DashboardWidgetQuerySchema.optional(),
+})
+
+export const WidgetConfigSchema = z.discriminatedUnion('target', [
+  TableWidgetConfigSchema,
+  ChartWidgetTargetConfigSchema,
+  KpiCardWidgetConfigSchema,
+  GaugeCardWidgetConfigSchema,
+  PivotTableWidgetConfigSchema,
+])
+
+export const StoredWidgetConfigSchema = z.discriminatedUnion('target', [
+  EmptyWidgetConfigSchema,
+  TableWidgetConfigSchema,
+  ChartWidgetTargetConfigSchema,
+  KpiCardWidgetConfigSchema,
+  GaugeCardWidgetConfigSchema,
+  PivotTableWidgetConfigSchema,
+])

package/services/dashboardConfigService.ts

@@ -0,0 +1,136 @@
+import { Filters } from 'adminforth';
+import type { IAdminForth } from 'adminforth';
+import { normalizeDashboardConfig } from '../custom/model/dashboard.types.js';
+import type { DashboardConfig, DashboardWidgetConfig } from '../custom/model/dashboard.types.js';
+
+const DASHBOARD_CONFIG_UPDATED_TOPIC_PREFIX = '/opentopic/dashboard-config-updated';
+
+export type DashboardRecord = {
+  id: string;
+  slug: string;
+  label: string;
+  revision: number;
+  config: unknown;
+};
+
+export function parseStoredDashboardConfig(config: unknown): DashboardConfig {
+  if (typeof config === 'string') {
+    return normalizeDashboardConfig(JSON.parse(config));
+  }
+
+  return normalizeDashboardConfig(config);
+}
+
+export function buildDashboardResponse(dashboard: DashboardRecord) {
+  return {
+    id: dashboard.id,
+    slug: dashboard.slug,
+    label: dashboard.label,
+    revision: dashboard.revision,
+    config: parseStoredDashboardConfig(dashboard.config),
+  };
+}
+
+export type PersistedDashboardResponse = {
+  id: string;
+  slug: string;
+  label: string;
+  revision: number;
+  config: DashboardConfig;
+};
+
+export function dashboardConfigUpdatedTopic(slug: string) {
+  return `${DASHBOARD_CONFIG_UPDATED_TOPIC_PREFIX}/${slug}`;
+}
+
+export function normalizeDashboardOrder(config: DashboardConfig): DashboardConfig {
+  const widgetsByGroupId = new Map<string, DashboardWidgetConfig[]>();
+
+  for (const widget of config.widgets) {
+    const groupWidgets = widgetsByGroupId.get(widget.group_id) ?? [];
+    groupWidgets.push(widget);
+    widgetsByGroupId.set(widget.group_id, groupWidgets);
+  }
+
+  for (const [groupId, widgets] of widgetsByGroupId.entries()) {
+    widgetsByGroupId.set(groupId, [...widgets].sort((a, b) => a.order - b.order));
+  }
+
+  return {
+    ...config,
+    groups: config.groups.map((group, index) => ({
+      ...group,
+      order: index + 1,
+    })),
+    widgets: config.widgets.map((widget) => ({
+      ...widget,
+      order: widgetsByGroupId.get(widget.group_id)!.findIndex((item) => item.id === widget.id) + 1,
+    })),
+  };
+}
+
+export async function getDashboardRecord(
+  adminforth: IAdminForth,
+  dashboardConfigsResourceId: string,
+  slug: string,
+): Promise<DashboardRecord | null> {
+  const dashboardConfigs = adminforth.resource(dashboardConfigsResourceId);
+  const dashboard = await dashboardConfigs.get(Filters.EQ('slug', slug));
+
+  return dashboard || null;
+}
+
+export async function persistDashboardConfig(
+  adminforth: IAdminForth,
+  dashboardConfigsResourceId: string,
+  dashboard: DashboardRecord,
+  config: DashboardConfig,
+): Promise<PersistedDashboardResponse> {
+  const normalizedConfig = normalizeDashboardOrder(config);
+
+  await adminforth.resource(dashboardConfigsResourceId).update(dashboard.id, {
+    config: normalizedConfig,
+    revision: dashboard.revision + 1,
+  });
+
+  await adminforth.websocket.publish(dashboardConfigUpdatedTopic(dashboard.slug), {
+    id: dashboard.id,
+    slug: dashboard.slug,
+    revision: dashboard.revision + 1,
+  });
+
+  return {
+    id: dashboard.id,
+    slug: dashboard.slug,
+    label: dashboard.label,
+    revision: dashboard.revision + 1,
+    config: normalizedConfig,
+  };
+}
+
+export type DashboardConfigService = {
+  getDashboardRecord: (slug: string) => Promise<DashboardRecord | null>;
+  parseStoredDashboardConfig: typeof parseStoredDashboardConfig;
+  persistDashboardConfig: (
+    dashboard: DashboardRecord,
+    config: DashboardConfig,
+  ) => Promise<PersistedDashboardResponse>;
+  buildDashboardResponse: typeof buildDashboardResponse;
+};
+
+export function createDashboardConfigService(
+  adminforth: IAdminForth,
+  dashboardConfigsResourceId: string,
+): DashboardConfigService {
+  return {
+    getDashboardRecord: (slug) => getDashboardRecord(adminforth, dashboardConfigsResourceId, slug),
+    parseStoredDashboardConfig,
+    persistDashboardConfig: (dashboard, config) => persistDashboardConfig(
+      adminforth,
+      dashboardConfigsResourceId,
+      dashboard,
+      config,
+    ),
+    buildDashboardResponse,
+  };
+}

package/services/widgetConfigValidator.ts

@@ -0,0 +1,93 @@
+import type { IAdminForth } from 'adminforth';
+import type { DashboardWidgetConfig } from '../custom/model/dashboard.types.js';
+import type { DashboardWidgetConfigValidationError } from '../schema/widget.js';
+import type { DashboardWidgetQueryConfig } from './widgetDataService.js';
+
+export type WidgetConfigValidatorService = {
+  validateDashboardWidgetApiConfig: (
+    widget: DashboardWidgetConfig,
+  ) => DashboardWidgetConfigValidationError[];
+};
+
+export function validateDashboardWidgetApiConfig(
+  adminforth: IAdminForth,
+  widget: DashboardWidgetConfig,
+): DashboardWidgetConfigValidationError[] {
+  if (widget.target !== 'chart') {
+    return [];
+  }
+
+  const errors: DashboardWidgetConfigValidationError[] = [];
+
+  if (!widget.query) {
+    errors.push({
+      field: 'query',
+      message: 'Chart widget must have query config',
+    });
+    return errors;
+  }
+
+  if (!widget.chart) {
+    errors.push({
+      field: 'chart',
+      message: 'Chart widget must have chart config',
+    });
+    return errors;
+  }
+
+  const query = widget.query as DashboardWidgetQueryConfig;
+  const chart = widget.chart;
+
+  const resource = adminforth.config.resources.find((item) => item.resourceId === query.resource);
+
+  if (!resource) {
+    errors.push({
+      field: 'query.resource',
+      message: `Resource "${query.resource}" is not registered`,
+    });
+    return errors;
+  }
+
+  if (!query.select) {
+    return errors;
+  }
+
+  const resourceFields = resource.columns.map((column) => column.name);
+
+  for (const field of query.select) {
+    if (!resourceFields.includes(field)) {
+      errors.push({
+        field: 'query.select',
+        message: `Field "${field}" is not in resource "${query.resource}"`,
+      });
+    }
+  }
+
+  const chartFields = [
+    chart.x_field,
+    chart.y_field,
+    chart.label_field,
+    chart.value_field,
+    chart.bucket_field,
+    ...(chart.series?.map((series: { field: string }) => series.field) ?? []),
+  ].filter((field): field is string => typeof field === 'string');
+
+  for (const field of chartFields) {
+    if (!query.select.includes(field)) {
+      errors.push({
+        field: 'query.select',
+        message: `Query select must include chart field "${field}"`,
+      });
+    }
+  }
+
+  return errors;
+}
+
+export function createWidgetConfigValidatorService(
+  adminforth: IAdminForth,
+): WidgetConfigValidatorService {
+  return {
+    validateDashboardWidgetApiConfig: (widget) => validateDashboardWidgetApiConfig(adminforth, widget),
+  };
+}

package/services/widgetDataService.ts

@@ -0,0 +1,57 @@
+import { Sorts } from 'adminforth';
+import type { IAdminForth } from 'adminforth';
+import type { DashboardWidgetConfig } from '../custom/model/dashboard.types.js';
+
+export type DashboardWidgetQueryConfig = {
+  resource: string;
+  select?: string[];
+  order?: {
+    field: string;
+    direction: 'asc' | 'desc';
+  };
+  limit?: number;
+};
+
+export type DashboardWidgetData = {
+  columns: string[];
+  rows: Record<string, unknown>[];
+};
+
+export type WidgetDataService = {
+  getWidgetData: (widget: DashboardWidgetConfig) => Promise<DashboardWidgetData | null>;
+};
+
+export async function getWidgetData(
+  adminforth: IAdminForth,
+  widget: DashboardWidgetConfig,
+): Promise<DashboardWidgetData | null> {
+  if (!widget.query) {
+    return null;
+  }
+
+  const query = widget.query as DashboardWidgetQueryConfig;
+
+  const rows = await adminforth.resource(query.resource).list(
+    [],
+    query.limit,
+    0,
+    query.order
+      ? [query.order.direction === 'desc' ? Sorts.DESC(query.order.field) : Sorts.ASC(query.order.field)]
+      : undefined,
+  );
+
+  const columns = query.select ?? Object.keys(rows[0] ?? {});
+
+  return {
+    columns,
+    rows: rows.map((row) => (
+      Object.fromEntries(columns.map((column) => [column, row[column]]))
+    )),
+  };
+}
+
+export function createWidgetDataService(adminforth: IAdminForth): WidgetDataService {
+  return {
+    getWidgetData: (widget) => getWidgetData(adminforth, widget),
+  };
+}

package/shims-vue.d.ts

@@ -0,0 +1,5 @@
+declare module '*.vue' {
+  import type { DefineComponent } from 'vue';
+  const component: DefineComponent<{}, {}, any>;
+  export default component;
+}

package/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "es2016",
+    "lib": ["ES2021", "DOM", "DOM.Iterable"],
+    "module": "node16",
+    "outDir": "./dist",
+    "declaration": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "paths": {
+      "@/afcl": ["./node_modules/adminforth/dist/spa/src/afcl/index.ts"],
+      "@/*": ["./node_modules/adminforth/dist/spa/src/*"]
+    }
+  },
+  "exclude": ["node_modules", "dist"]
+}

package/types.ts

@@ -0,0 +1,8 @@
+export type PluginOptions = {
+	/**
+	 * ResourceId of a resource that stores dashboard configs.
+	 *
+	 * Expected columns: id, slug, label, revision, config (JSON).
+	 */
+	dashboardConfigsResourceId: string;
+};