@adminforth/dashboard 1.0.0

package/endpoint/widgets.ts

@@ -0,0 +1,255 @@
+import type { AdminUser, IHttpServer } from 'adminforth';
+import { randomUUID } from 'crypto';
+import type { DashboardConfig, DashboardWidgetConfig } from '../custom/model/dashboard.types.js';
+import {
+  DashboardApiResponseSchema,
+  DashboardWidgetDataResponseSchema,
+  GroupIdRequestSchema,
+  MoveWidgetRequestSchema,
+  SetWidgetConfigRequestSchema,
+  WidgetIdRequestSchema,
+} from '../schema/api.js';
+import type { DashboardWidgetConfigValidationError } from '../schema/widget.js';
+import type { DashboardRecord, PersistedDashboardResponse } from '../services/dashboardConfigService.js';
+
+type WidgetEndpointsContext = {
+  canEditDashboard: (adminUser: AdminUser) => boolean;
+  getDashboardRecord: (slug: string) => Promise<DashboardRecord | null>;
+  parseStoredDashboardConfig: (config: unknown) => DashboardConfig;
+  persistDashboardConfig: (
+    dashboard: DashboardRecord,
+    config: DashboardConfig,
+  ) => Promise<PersistedDashboardResponse>;
+  buildDashboardResponse: (dashboard: DashboardRecord) => PersistedDashboardResponse;
+  validateDashboardWidgetApiConfig: (
+    widget: DashboardWidgetConfig,
+  ) => DashboardWidgetConfigValidationError[];
+  getWidgetData: (widget: DashboardWidgetConfig) => Promise<unknown>;
+};
+
+export function registerWidgetEndpoints(
+  server: IHttpServer,
+  ctx: WidgetEndpointsContext,
+) {
+  server.endpoint({
+    method: 'POST',
+    path: '/dashboard/add_dashboard_widget',
+    description: 'Adds a new empty widget to a dashboard group. Superadmin only.',
+    request_schema: GroupIdRequestSchema,
+    response_schema: DashboardApiResponseSchema,
+    handler: async ({ body, adminUser, response }) => {
+      if (!ctx.canEditDashboard(adminUser)) {
+        response.setStatus(403);
+        return { error: 'Dashboard edit is not allowed' };
+      }
+
+      const slug = String(body?.slug || 'default');
+      const groupId = String(body?.groupId || '');
+      const dashboard = await ctx.getDashboardRecord(slug);
+
+      if (!dashboard) {
+        response.setStatus(404);
+        return { error: 'Dashboard not found' };
+      }
+
+      const config = ctx.parseStoredDashboardConfig(dashboard.config);
+      const group = config.groups.find((item) => item.id === groupId);
+
+      if (!group) {
+        response.setStatus(404);
+        return { error: 'Dashboard group not found' };
+      }
+
+      const nextOrder = config.widgets.filter((item) => item.group_id === groupId).length + 1;
+      const widget: DashboardWidgetConfig = {
+        id: `widget_${randomUUID()}`,
+        group_id: groupId,
+        label: 'New widget',
+        size: 'small',
+        order: nextOrder,
+        target: 'empty',
+      };
+
+      return ctx.persistDashboardConfig(dashboard, {
+        ...config,
+        widgets: [...config.widgets, widget],
+      });
+    },
+  });
+
+  server.endpoint({
+    method: 'POST',
+    path: '/dashboard/move_dashboard_widget',
+    description: 'Moves a dashboard widget up or down inside its group. Superadmin only.',
+    request_schema: MoveWidgetRequestSchema,
+    response_schema: DashboardApiResponseSchema,
+    handler: async ({ body, adminUser, response }) => {
+      if (!ctx.canEditDashboard(adminUser)) {
+        response.setStatus(403);
+        return { error: 'Dashboard edit is not allowed' };
+      }
+
+      const slug = String(body?.slug || 'default');
+      const widgetId = String(body?.widgetId || '');
+      const direction = body?.direction === 'down' ? 'down' : 'up';
+      const dashboard = await ctx.getDashboardRecord(slug);
+
+      if (!dashboard) {
+        response.setStatus(404);
+        return { error: 'Dashboard not found' };
+      }
+
+      const config = ctx.parseStoredDashboardConfig(dashboard.config);
+      const widget = config.widgets.find((item) => item.id === widgetId);
+
+      if (!widget) {
+        response.setStatus(404);
+        return { error: 'Dashboard widget not found' };
+      }
+
+      const sortedWidgets = config.widgets
+        .filter((item) => item.group_id === widget.group_id)
+        .sort((a, b) => a.order - b.order);
+      const currentIndex = sortedWidgets.findIndex((item) => item.id === widgetId);
+      const targetIndex = direction === 'up' ? currentIndex - 1 : currentIndex + 1;
+
+      if (targetIndex < 0 || targetIndex >= sortedWidgets.length) {
+        return ctx.buildDashboardResponse(dashboard);
+      }
+
+      const reorderedWidgets = [...sortedWidgets];
+      const [movedWidget] = reorderedWidgets.splice(currentIndex, 1);
+      reorderedWidgets.splice(targetIndex, 0, movedWidget);
+      const reorderedWidgetIds = new Map(reorderedWidgets.map((item, index) => [item.id, index + 1]));
+
+      return ctx.persistDashboardConfig(dashboard, {
+        ...config,
+        widgets: config.widgets.map((item) => ({
+          ...item,
+          order: reorderedWidgetIds.get(item.id) ?? item.order,
+        })),
+      });
+    },
+  });
+
+  server.endpoint({
+    method: 'POST',
+    path: '/dashboard/remove_dashboard_widget',
+    description: 'Removes one dashboard widget by id. Superadmin only.',
+    request_schema: WidgetIdRequestSchema,
+    response_schema: DashboardApiResponseSchema,
+    handler: async ({ body, adminUser, response }) => {
+      if (!ctx.canEditDashboard(adminUser)) {
+        response.setStatus(403);
+        return { error: 'Dashboard edit is not allowed' };
+      }
+
+      const slug = String(body?.slug || 'default');
+      const widgetId = String(body?.widgetId || '');
+      const dashboard = await ctx.getDashboardRecord(slug);
+
+      if (!dashboard) {
+        response.setStatus(404);
+        return { error: 'Dashboard not found' };
+      }
+
+      const config = ctx.parseStoredDashboardConfig(dashboard.config);
+      const nextWidgets = config.widgets.filter((item) => item.id !== widgetId);
+
+      if (nextWidgets.length === config.widgets.length) {
+        response.setStatus(404);
+        return { error: 'Dashboard widget not found' };
+      }
+
+      return ctx.persistDashboardConfig(dashboard, {
+        ...config,
+        widgets: nextWidgets,
+      });
+    },
+  });
+
+  server.endpoint({
+    method: 'POST',
+    path: '/dashboard/set_widget_config',
+    description: 'Replaces editable JSON configuration for a dashboard widget while preserving widget id, group id, and order. Superadmin only.',
+    request_schema: SetWidgetConfigRequestSchema,
+    response_schema: DashboardApiResponseSchema,
+    handler: async ({ body, adminUser, response }) => {
+      if (!ctx.canEditDashboard(adminUser)) {
+        response.setStatus(403);
+        return { error: 'Dashboard edit is not allowed' };
+      }
+
+      const slug = String(body?.slug || 'default');
+      const widgetId = String(body?.widgetId || '');
+      const dashboard = await ctx.getDashboardRecord(slug);
+
+      if (!dashboard) {
+        response.setStatus(404);
+        return { error: 'Dashboard not found' };
+      }
+
+      const config = ctx.parseStoredDashboardConfig(dashboard.config);
+      const widget = config.widgets.find((item) => item.id === widgetId);
+
+      if (!widget) {
+        response.setStatus(404);
+        return { error: 'Dashboard widget not found' };
+      }
+
+      const typedWidgetConfig = body.config as DashboardWidgetConfig;
+      const apiValidationErrors = ctx.validateDashboardWidgetApiConfig(typedWidgetConfig);
+
+      if (apiValidationErrors.length) {
+        response.setStatus(422);
+        return {
+          error: 'Invalid widget config',
+          validationErrors: apiValidationErrors,
+        };
+      }
+
+      return ctx.persistDashboardConfig(dashboard, {
+        ...config,
+        widgets: config.widgets.map((item) => item.id === widgetId
+          ? {
+              ...typedWidgetConfig,
+              id: widget.id,
+              group_id: widget.group_id,
+              order: widget.order,
+            }
+          : item),
+      });
+    },
+  });
+
+  server.endpoint({
+    method: 'POST',
+    path: '/dashboard/get_dashboard_widget_data',
+    description: 'Loads query result data for one dashboard widget by dashboard slug and widget id.',
+    request_schema: WidgetIdRequestSchema,
+    response_schema: DashboardWidgetDataResponseSchema,
+    handler: async ({ body, response }) => {
+      const slug = String(body?.slug || 'default');
+      const widgetId = String(body?.widgetId || '');
+      const dashboard = await ctx.getDashboardRecord(slug);
+
+      if (!dashboard) {
+        response.setStatus(404);
+        return { error: 'Dashboard not found' };
+      }
+
+      const config = ctx.parseStoredDashboardConfig(dashboard.config);
+      const widget = config.widgets.find((item) => item.id === widgetId);
+
+      if (!widget) {
+        response.setStatus(404);
+        return { error: 'Dashboard widget not found' };
+      }
+
+      return {
+        widget,
+        data: await ctx.getWidgetData(widget),
+      };
+    },
+  });
+}

package/index.ts

@@ -0,0 +1,141 @@
+import { AdminForthPlugin } from "adminforth";
+import type { AdminForthResource, AdminUser, IAdminForth, IHttpServer } from "adminforth";
+import type { PluginOptions } from "./types.js";
+import { randomUUID } from 'crypto';
+import path from 'path';
+import { registerDashboardEndpoints } from './endpoint/dashboard.js';
+import { registerGroupEndpoints } from "./endpoint/groups.js";
+import { registerWidgetEndpoints } from './endpoint/widgets.js';
+import { createDashboardConfigService } from "./services/dashboardConfigService.js";
+import { createWidgetDataService } from "./services/widgetDataService.js";
+import { createWidgetConfigValidatorService } from "./services/widgetConfigValidator.js";
+
+const DEFAULT_DASHBOARD_CONFIG = {
+  version: 1,
+  groups: [{
+    id: 'default',
+    label: 'Default Group',
+    order: 1,
+  }],
+  widgets: [],
+};
+
+function canEditDashboard(adminUser: AdminUser) {
+  return adminUser.dbUser.role === 'superadmin';
+}
+
+export default class DashboardPlugin extends AdminForthPlugin {
+  options: PluginOptions;
+  private didRegisterMenuProvider = false;
+  private didInstallSeedHook = false;
+
+  constructor(options: PluginOptions) {
+    super(options, import.meta.url);
+    this.options = options;
+    this.customFolderName = 'custom';
+    this.customFolderPath = path.join(this.pluginDir, this.customFolderName);
+  }
+
+  async modifyResourceConfig(adminforth: IAdminForth, resourceConfig: AdminForthResource) {
+    super.modifyResourceConfig(adminforth, resourceConfig);
+
+    if (!this.didRegisterMenuProvider) {
+      this.didRegisterMenuProvider = true;
+
+      const adminforthWithDynamicMenu = adminforth as any;
+      adminforthWithDynamicMenu.registerMenuContributionProvider(async () => {
+        if (this.adminforth.statuses.dbDiscover !== 'done') {
+          return [];
+        }
+
+        const dashboards = await this.adminforth.resource(this.options.dashboardConfigsResourceId).list([]);
+
+        return [
+          {
+            item: {
+              itemId: 'dashboardMenu',
+              type: 'group',
+              label: 'Dashboards',
+              icon: 'flowbite:chart-pie-solid',
+              open: true,
+              children: dashboards.map((dashboard: any) => ({
+                itemId: `dashboard-${dashboard.id}`,
+                type: 'page',
+                label: dashboard.label,
+                url: `/dashboard/${dashboard.slug}`,
+              })),
+            },
+            placement: { position: 'first' },
+          },
+        ];
+      });
+    }
+
+    if (!this.didInstallSeedHook) {
+      this.didInstallSeedHook = true;
+
+      const discoverDatabases = adminforth.discoverDatabases.bind(adminforth);
+      adminforth.discoverDatabases = async () => {
+        await discoverDatabases();
+        await this.ensureDefaultDashboardConfig();
+      };
+    }
+
+    adminforth.config.customization.customPages.push({
+      path: '/dashboard/:slug',
+      component: {
+        file: this.componentPath('runtime/DashboardPage.vue'),
+        meta: {
+          title: 'Dashboard',
+        },
+      },
+    });
+  }
+
+  private async ensureDefaultDashboardConfig() {
+    const dashboardConfigs = this.adminforth.resource(this.options.dashboardConfigsResourceId);
+    const dashboardsCount = await dashboardConfigs.count();
+
+    if (dashboardsCount > 0) {
+      return;
+    }
+
+    const createResult = await dashboardConfigs.create({
+      id: randomUUID(),
+      slug: 'default',
+      label: 'Default Dashboard',
+      revision: 1,
+      config: DEFAULT_DASHBOARD_CONFIG,
+    });
+
+    if (!createResult.ok) {
+      throw new Error(createResult.error || 'Failed to create default dashboard config');
+    }
+  }
+
+  setupEndpoints(server: IHttpServer) {
+    const dashboardConfigService = createDashboardConfigService(
+      this.adminforth,
+      this.options.dashboardConfigsResourceId,
+    );
+    const widgetDataService = createWidgetDataService(this.adminforth);
+    const widgetConfigValidatorService = createWidgetConfigValidatorService(this.adminforth);
+
+    const ctx = {
+      adminforth: this.adminforth,
+      dashboardConfigsResourceId: this.options.dashboardConfigsResourceId,
+      canEditDashboard,
+      ...dashboardConfigService,
+      ...widgetDataService,
+      ...widgetConfigValidatorService,
+    };
+
+    registerDashboardEndpoints(server, ctx);
+    registerGroupEndpoints(server, ctx);
+    registerWidgetEndpoints(server, ctx);
+  }
+
+  instanceUniqueRepresentation(): string {
+    return "dashboard";
+  }
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@adminforth/dashboard",
+  "version": "1.0.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "homepage": "https://adminforth.dev/docs/tutorial/Plugins/dashboard/",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc && rsync -av --exclude 'node_modules' custom dist/",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "adminforth",
+    "dashboard"
+  ],
+  "author": "DevForth (https://devforth.io)",
+  "license": "MIT",
+  "description": "Dashboard plugin for AdminForth",
+  "devDependencies": {
+    "@types/node": "latest",
+    "adminforth": "^2.60.0",
+    "semantic-release": "^24.2.1",
+    "semantic-release-slack-bot": "^4.0.2",
+    "typescript": "^5.7.3",
+    "vue-tsc": "^3.3.2"
+  },
+  "peerDependencies": {
+    "adminforth": "^2.60.0"
+  },
+  "release": {
+    "plugins": [
+      "@semantic-release/commit-analyzer",
+      "@semantic-release/release-notes-generator",
+      "@semantic-release/npm",
+      "@semantic-release/github",
+      [
+        "semantic-release-slack-bot",
+        {
+          "packageName": "@adminforth/dashboard",
+          "notifyOnSuccess": true,
+          "notifyOnFail": true,
+          "slackIcon": ":package:",
+          "markdownReleaseNotes": true
+        }
+      ]
+    ]
+  },
+  "branches": [
+    "main",
+    {
+      "name": "next",
+      "prerelease": true
+    }
+  ],
+  "dependencies": {
+    "vue": "^3.5.34",
+    "vue-router": "^5.0.7",
+    "yaml": "^2.9.0",
+    "zod": "^4.4.3"
+  }
+}

package/schema/api.ts

@@ -0,0 +1,99 @@
+import { toJSONSchema, z } from 'zod'
+import { StoredWidgetConfigSchema, WidgetConfigSchema } from './widget.js'
+
+function toAdminForthJsonSchema(schema: z.ZodType) {
+  return toJSONSchema(schema, { target: 'draft-7' })
+}
+
+export const DashboardErrorResponseZodSchema = z.object({
+  error: z.string(),
+  validationErrors: z.array(z.object({
+    field: z.string(),
+    message: z.string(),
+  })).optional(),
+})
+
+export const DashboardGroupZodSchema = z.object({
+  id: z.string(),
+  label: z.string(),
+  order: z.number(),
+})
+
+export const DashboardConfigZodSchema = z.object({
+  version: z.number(),
+  groups: z.array(DashboardGroupZodSchema),
+  widgets: z.array(StoredWidgetConfigSchema),
+})
+
+export const DashboardResponseZodSchema = z.object({
+  id: z.string(),
+  slug: z.string(),
+  label: z.string(),
+  revision: z.number(),
+  config: DashboardConfigZodSchema,
+})
+
+export const DashboardApiResponseZodSchema = z.union([
+  DashboardResponseZodSchema,
+  DashboardErrorResponseZodSchema,
+])
+
+export const DashboardWidgetDataResponseZodSchema = z.union([
+  z.object({
+    widget: StoredWidgetConfigSchema,
+    data: z.unknown(),
+  }),
+  DashboardErrorResponseZodSchema,
+])
+
+export const SlugRequestZodSchema = z.object({
+  slug: z.string().optional(),
+}).strict()
+
+export const GroupIdRequestZodSchema = z.object({
+  slug: z.string().optional(),
+  groupId: z.string(),
+}).strict()
+
+export const MoveGroupRequestZodSchema = z.object({
+  slug: z.string().optional(),
+  groupId: z.string(),
+  direction: z.enum(['up', 'down']),
+}).strict()
+
+export const SetGroupConfigRequestZodSchema = z.object({
+  slug: z.string().optional(),
+  groupId: z.string(),
+  config: DashboardGroupZodSchema,
+}).strict()
+
+export const WidgetIdRequestZodSchema = z.object({
+  slug: z.string().optional(),
+  widgetId: z.string(),
+}).strict()
+
+export const MoveWidgetRequestZodSchema = z.object({
+  slug: z.string().optional(),
+  widgetId: z.string(),
+  direction: z.enum(['up', 'down']),
+}).strict()
+
+export const SetWidgetConfigRequestZodSchema = z.object({
+  slug: z.string().optional(),
+  widgetId: z.string(),
+  config: WidgetConfigSchema,
+}).strict()
+
+export const DashboardErrorResponseSchema = toAdminForthJsonSchema(DashboardErrorResponseZodSchema)
+export const DashboardGroupSchema = toAdminForthJsonSchema(DashboardGroupZodSchema)
+export const DashboardConfigSchema = toAdminForthJsonSchema(DashboardConfigZodSchema)
+export const DashboardResponseSchema = toAdminForthJsonSchema(DashboardResponseZodSchema)
+export const DashboardApiResponseSchema = toAdminForthJsonSchema(DashboardApiResponseZodSchema)
+export const DashboardWidgetDataResponseSchema = toAdminForthJsonSchema(DashboardWidgetDataResponseZodSchema)
+export const SlugRequestSchema = toAdminForthJsonSchema(SlugRequestZodSchema)
+export const GroupIdRequestSchema = toAdminForthJsonSchema(GroupIdRequestZodSchema)
+export const MoveGroupRequestSchema = toAdminForthJsonSchema(MoveGroupRequestZodSchema)
+export const SetGroupConfigRequestSchema = toAdminForthJsonSchema(SetGroupConfigRequestZodSchema)
+export const WidgetIdRequestSchema = toAdminForthJsonSchema(WidgetIdRequestZodSchema)
+export const MoveWidgetRequestSchema = toAdminForthJsonSchema(MoveWidgetRequestZodSchema)
+export const SetWidgetConfigRequestSchema = toAdminForthJsonSchema(SetWidgetConfigRequestZodSchema)