feat: implement dynamic menu contributions and refresh functionality

Author: NoOne7135

adminforth/documentation/docs/tutorial/03-Customization/10-menuConfiguration.md

@@ -57,6 +57,131 @@ E.g. create group "Blog" with Items who link to resource "posts" and "categories
 
 If it is rare Group you can make it `open: false` so it would not take extra space in menu, but admin users will be able to open it by clicking on the group name.
 
+## Adding menu items from plugins
+
+Plugins can add top-level menu items without mutating the user-defined `config.menu`. This keeps the application menu owned by the app configuration, while plugins can contribute their own entries.
+
+Use `registerMenuContribution` from a plugin's `modifyResourceConfig`:
+
+```ts title='./plugins/adminforth-dashboard/index.ts'
+async modifyResourceConfig(adminforth, resourceConfig) {
+  super.modifyResourceConfig(adminforth, resourceConfig);
+
+  adminforth.registerMenuContribution({
+    item: {
+      itemId: 'dashboard',
+      type: 'page',
+      label: 'Dashboard',
+      icon: 'flowbite:chart-pie-solid',
+      path: '/dashboard',
+      component: this.componentPath('Dashboard.vue'),
+    },
+    placement: { before: { resourceId: 'adminuser' } },
+  });
+}
+```
+
+Supported placements:
+
+```ts
+adminforth.registerMenuContribution({
+  item: {
+    itemId: 'dashboard',
+    type: 'page',
+    label: 'Dashboard',
+    path: '/dashboard',
+    component: this.componentPath('Dashboard.vue'),
+  },
+  placement: { position: 'first' },
+});
+
+adminforth.registerMenuContribution({
+  item: {
+    itemId: 'reports',
+    type: 'page',
+    label: 'Reports',
+    path: '/reports',
+    component: this.componentPath('Reports.vue'),
+  },
+  placement: { after: { resourceId: 'orders' } },
+});
+```
+
+`placement` can be:
+
+- `{ position: 'first' }`
+- `{ position: 'last' }`
+- `{ before: 'usersMenuItemId' }`
+- `{ after: 'usersMenuItemId' }`
+- `{ before: { itemId: 'usersMenuItemId' } }`
+- `{ after: { resourceId: 'adminuser' } }`
+- `{ before: { path: '/reports' } }`
+
+If placement is omitted, or if the target item is not found, AdminForth appends the contributed item to the end of the top-level menu.
+
+Plugin menu contributions are additive only:
+
+- user-defined `config.menu` is not changed
+- plugins cannot remove or edit existing menu items through this API
+- contributed `itemId` must not duplicate an existing top-level menu item
+- this first version inserts only top-level menu items
+
+### Dynamic menu items from plugin state
+
+If a plugin needs to add menu items at runtime, for example after a user clicks a button and creates a new dashboard, register a menu contribution provider. AdminForth calls providers every time it fetches the menu.
+
+```ts title='./plugins/adminforth-dashboard/index.ts'
+async modifyResourceConfig(adminforth, resourceConfig) {
+  super.modifyResourceConfig(adminforth, resourceConfig);
+
+  adminforth.registerMenuContributionProvider(async ({ adminUser, adminforth }) => {
+    const dashboards = await adminforth.resource('dashboards').list();
+
+    return [
+      {
+        item: {
+          itemId: 'dashboardsMenu',
+          type: 'group',
+          label: 'Dashboards',
+          icon: 'flowbite:chart-pie-solid',
+          children: dashboards.map((dashboard) => ({
+            itemId: `dashboard-${dashboard.id}`,
+            type: 'page',
+            label: dashboard.name,
+            path: `/dashboards/${dashboard.id}`,
+          })),
+        },
+        placement: { position: 'first' },
+      },
+    ];
+  });
+}
+```
+
+After the plugin changes the state used by the provider, call `refreshMenu` on the backend:
+
+```ts
+await adminforth.resource('dashboards').create({
+  name: 'Sales',
+});
+
+await adminforth.refreshMenu(adminUser);
+```
+
+AdminForth sends a websocket event to the current user, and the frontend refetches the menu without a page reload.
+
+Frontend components can also refresh the menu directly:
+
+```ts
+import { useAdminforth } from '@/adminforth';
+
+const { menu } = useAdminforth();
+
+await menu.refresh();
+```
+
+Dynamic menu items should point to routes that are already available in the SPA. If a provider returns a brand-new custom `component` path that was not known during AdminForth build, the menu item can appear, but the route will not be registered until the app is rebuilt.
+
 ## Visibility of menu items
 
 You might want to hide some menu items from the menu for some users. 

adminforth/index.ts

@@ -7,7 +7,7 @@ import CodeInjector from './modules/codeInjector.js';
 import ExpressServer from './servers/express.js';
 import OpenApiRegistry from './servers/openapi.js';
 // import FastifyServer from './servers/fastify.js';
-import { ADMINFORTH_VERSION, listify, suggestIfTypo, RateLimiter, RAMLock, getClientIp, isProbablyUUIDColumn, convertPeriodToSeconds, hookResponseError } from './modules/utils.js';
+import { ADMINFORTH_VERSION, listify, suggestIfTypo, RateLimiter, RAMLock, getClientIp, isProbablyUUIDColumn, convertPeriodToSeconds, hookResponseError, md5hash } from './modules/utils.js';
 import { 
   type AdminForthConfig, 
   type IAdminForth, 
@@ -25,11 +25,15 @@ import {
   CreateResourceRecordResult,
   UpdateResourceRecordResult,
   DeleteResourceRecordResult,
+  AdminForthMenuContributionProvider,
 } from './types/Back.js';
 import {
   AdminForthFilterOperators,
   AdminForthDataTypes,
-  AdminUser,
+  AdminUser, 
+  type AdminForthConfigMenuItem,
+  type AdminForthMenuContribution,
+  type AdminForthMenuTarget,
 } from './types/Common.js';
 
 import AdminForthPlugin from './basePlugin.js';
@@ -126,19 +130,95 @@ class AdminForth implements IAdminForth {
   runningHotReload: boolean;
   activatedPlugins: Array<AdminForthPlugin>;
   pluginsById: Record<string, AdminForthPlugin> = {};
+  private menuContributions: AdminForthMenuContribution[] = [];
+  private menuContributionProviders: AdminForthMenuContributionProvider[] = [];
   configValidator: IConfigValidator;
   restApi: AdminForthRestAPI;
 
   websocket: IWebSocketBroker;
 
+  registerMenuContribution(contribution: AdminForthMenuContribution): void {
+    this.menuContributions.push(contribution);
+  }
+
+  registerMenuContributionProvider(provider: AdminForthMenuContributionProvider): void {
+    this.menuContributionProviders.push(provider);
+  }
+
+  getMenuContributions(): AdminForthMenuContribution[] {
+    return [...this.menuContributions];
+  }
+
+  async getMenuWithContributions(adminUser?: AdminUser, menu: AdminForthConfigMenuItem[] = this.config.menu): Promise<AdminForthConfigMenuItem[]> {
+    const generateItemId = (item: AdminForthConfigMenuItem) =>
+      md5hash(`menu-item-${item.label}-${item.resourceId || ''}-${item.path || ''}`);
+    const matchesTarget = (item: AdminForthConfigMenuItem, target: AdminForthMenuTarget) =>
+      typeof target === 'string'
+        ? item.itemId === target
+        : (target.itemId !== undefined && item.itemId === target.itemId)
+          || (target.resourceId !== undefined && item.resourceId === target.resourceId)
+          || (target.path !== undefined && item.path === target.path);
+
+    const resolvedMenu: AdminForthConfigMenuItem[] = menu.map((item) => ({
+      ...item,
+      itemId: item.itemId || generateItemId(item),
+      children: item.children?.map((child) => ({
+        ...child,
+        itemId: child.itemId || generateItemId(child),
+      })),
+    }));
+    const usedItemIds = new Set(resolvedMenu.map((item) => item.itemId));
+
+    const providerContributions = await Promise.all(
+      this.menuContributionProviders.map((provider) => provider({ adminUser, adminforth: this }))
+    );
+    const contributions = [
+      ...this.getMenuContributions(),
+      ...providerContributions.flat(),
+    ]
+      .sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+
+    for (const contribution of contributions) {
+      const item = {
+        ...contribution.item,
+        itemId: contribution.item.itemId || generateItemId(contribution.item),
+      };
+      if (usedItemIds.has(item.itemId)) {
+        throw new Error(`Menu contribution itemId "${item.itemId}" already exists in menu`);
+      }
+      usedItemIds.add(item.itemId);
+
+      const placement = contribution.placement;
+      if (placement && 'position' in placement && placement.position === 'first') {
+        resolvedMenu.unshift(item);
+      } else if (placement && 'before' in placement) {
+        const targetIndex = resolvedMenu.findIndex((menuItem) => matchesTarget(menuItem, placement.before));
+        resolvedMenu.splice(targetIndex === -1 ? resolvedMenu.length : targetIndex, 0, item);
+      } else if (placement && 'after' in placement) {
+        const targetIndex = resolvedMenu.findIndex((menuItem) => matchesTarget(menuItem, placement.after));
+        resolvedMenu.splice(targetIndex === -1 ? resolvedMenu.length : targetIndex + 1, 0, item);
+      } else {
+        resolvedMenu.push(item);
+      }
+    }
+
+    return resolvedMenu;
+  }
+
+  async refreshMenu(adminUser: AdminUser) {
+    this.websocket.publish(`/opentopic/refresh-menu/${adminUser.pk}`, {});
+  }
+
   async refreshMenuBadge(menuItemId: string, adminUser: AdminUser) {
-    const menuItem = this.config.menu.find((item) => item.itemId === menuItemId);
+    const menu = await this.getMenuWithContributions(adminUser);
+    const menuItem = menu.find((item) => item.itemId === menuItemId)
+      || menu.flatMap((item) => item.children || []).find((item) => item.itemId === menuItemId);
     if (!menuItem) {
-      afLogger.error(`Cannot refresh badge for menu item with id "${menuItemId}" because it was not found in config.menu`);
+      afLogger.error(`Cannot refresh badge for menu item with id "${menuItemId}" because it was not found in menu`);
       return;
     }
     if (!menuItem.badge) {
-      afLogger.error(`Cannot refresh badge for menu item with id "${menuItemId}" because it does not have badge function in config.menu`);
+      afLogger.error(`Cannot refresh badge for menu item with id "${menuItemId}" because it does not have badge function in menu`);
       return;
     }
     const badgeValue = typeof menuItem.badge === 'function' ? await menuItem.badge(adminUser, this) : menuItem.badge;

adminforth/modules/codeInjector.ts

@@ -469,7 +469,8 @@ class CodeInjector implements ICodeInjector {
     }
 
     registerCustomPages(this.adminforth.config);
-    collectAssetsFromMenu(this.adminforth.config.menu);
+    const menuWithContributions = await this.adminforth.getMenuWithContributions();
+    collectAssetsFromMenu(menuWithContributions);
     registerSettingPages(this.adminforth.config.auth.userMenuSettingsPages);
     const spaDir = this.getSpaDir();
 
@@ -739,18 +740,18 @@ class CodeInjector implements ICodeInjector {
     await fs.promises.writeFile(indexHtmlPath, indexHtmlContent);
 
     /* generate custom routes */
-    let homepageMenuItem: AdminForthConfigMenuItem = findHomePage(this.adminforth.config.menu);
+    let homepageMenuItem: AdminForthConfigMenuItem = findHomePage(menuWithContributions);
     if (!homepageMenuItem) {
       // find first item with path or resourceId. If we face a menu item with children earlier then path/resourceId, we should search in children
-      homepageMenuItem = await findFirstMenuItemWithResource(this.adminforth.config.menu);
+      homepageMenuItem = await findFirstMenuItemWithResource(menuWithContributions);
     }
     if (!homepageMenuItem) {
       throw new Error('No homepage found in menu and no menu item with path/resourceId found. AdminForth can not generate routes');
     }
 
     let homePagePath = homepageMenuItem.path || `/resource/${homepageMenuItem.resourceId}`;
     if (!homePagePath) {
-      homePagePath=this.adminforth.config.menu.filter((mi)=>mi.path)[0]?.path || `/resource/${this.adminforth.config.menu.filter((mi)=>mi.children)[0]?.resourceId}` ;
+      homePagePath=menuWithContributions.filter((mi)=>mi.path)[0]?.path || `/resource/${menuWithContributions.filter((mi)=>mi.children)[0]?.resourceId}` ;
     }
 
     routes += `{
@@ -1237,4 +1238,4 @@ class CodeInjector implements ICodeInjector {
   }
 }
 
-export default CodeInjector;
+export default CodeInjector;

adminforth/modules/restApi.ts

@@ -870,7 +870,7 @@ export default class AdminForthRestAPI implements IAdminForthRestAPI {
         }
 
         let newMenu = []
-        for (let menuItem of this.adminforth.config.menu) {
+        for (let menuItem of await this.adminforth.getMenuWithContributions(adminUser)) {
           let newMenuItem = {...menuItem,}
           if (menuItem.visible){
             if (!checkIsMenuItemVisible(menuItem)){
@@ -1039,7 +1039,7 @@ export default class AdminForthRestAPI implements IAdminForthRestAPI {
           }
         }
 
-        this.adminforth.config.menu.map((menuItem) => {
+        (await this.adminforth.getMenuWithContributions(adminUser)).map((menuItem) => {
           processMenuItem(menuItem)
         })
 

adminforth/spa/src/App.vue

@@ -340,6 +340,9 @@ onMounted(async () => {
   // before init flowbite we have to wait router initialized because it affects dom(our v-ifs) and fetch menu
   await initRouter();
   document.documentElement.setAttribute('data-theme', theme.value);
+  menu.refresh = async () => {
+    await coreStore.refreshMenu();
+  }
   menu.refreshMenuBadges = async () => {
     await coreStore.fetchMenuBadges();
   }

adminforth/spa/src/adminforth.ts

@@ -35,6 +35,9 @@ class FrontendAPI implements FrontendAPIInterface {
   constructor() {
 
     this.menu = {
+      refresh: async () => {
+        console.log('refreshMenu')
+      },
       refreshMenuBadges: () => {
         console.log('refreshMenuBadges')
       }
@@ -231,4 +234,4 @@ export function useAdminforth() {
 }
 
 
-export default frontendAPI;
+export default frontendAPI;

adminforth/spa/src/stores/core.ts

@@ -87,6 +87,20 @@ export const useCoreStore = defineStore('core', () => {
     adminUser.value = resp.adminUser;
     userData.value = resp.user;
     console.log('🌍 AdminForth v', resp.version);
+    subscribeToMenuRefresh();
+  }
+
+  async function refreshMenu() {
+    await fetchMenuAndResource();
+    await fetchMenuBadges();
+  }
+
+  function subscribeToMenuRefresh() {
+    if (!userData.value?.pk) {
+      return;
+    }
+    websocket.unsubscribeByPrefix('/opentopic/refresh-menu/');
+    websocket.subscribe(`/opentopic/refresh-menu/${userData.value.pk}`, refreshMenu);
   }
 
   function findItemWithId(items: AdminForthConfigMenuItem[], itemId: string): AdminForthConfigMenuItem | undefined {
@@ -257,6 +271,7 @@ export const useCoreStore = defineStore('core', () => {
     userAvatarUrl,
     getPublicConfig,
     fetchMenuAndResource, 
+    refreshMenu,
     getLoginFormConfig,
     fetchRecord, 
     record, 

adminforth/types/Back.ts

@@ -13,6 +13,7 @@ import { ActionCheckSource, AdminForthFilterOperators, AdminForthSortDirections,
   type AdminForthResourceInputCommon,
   type AdminForthComponentDeclarationFull,
   type AdminForthConfigMenuItem,
+  type AdminForthMenuContribution,
   type AnnouncementBadgeResponse,
   type AdminForthResourceColumnInputCommon,
   type ColumnMinMaxValue,
@@ -594,9 +595,20 @@ export interface IAdminForth {
    */
   getPluginById<T>(id: string): T;
 
+  registerMenuContribution(contribution: AdminForthMenuContribution): void;
+  registerMenuContributionProvider(provider: AdminForthMenuContributionProvider): void;
+  getMenuContributions(): AdminForthMenuContribution[];
+  getMenuWithContributions(adminUser?: AdminUser, menu?: AdminForthConfigMenuItem[]): Promise<AdminForthConfigMenuItem[]>;
+
+  refreshMenu(adminUser: AdminUser): Promise<void>;
   refreshMenuBadge(menuItemId: string, adminUser: AdminUser): Promise<void>;
 }
 
+export type AdminForthMenuContributionProvider = (ctx: {
+  adminUser?: AdminUser,
+  adminforth: IAdminForth,
+}) => AdminForthMenuContribution[] | Promise<AdminForthMenuContribution[]>;
+
 
 export interface IAdminForthPlugin {
   adminforth: IAdminForth;