@cccsaurora/howler-ui 2.14.0-dev.232 → 2.14.0-dev.247

package/plugins/HowlerPlugin.d.ts

@@ -13,6 +13,7 @@ import type { Hit } from '@cccsaurora/howler-ui/models/entities/generated/Hit';
 import type React from 'react';
 import type { PropsWithChildren } from 'react';
 import type { IPlugin, PluginStore } from 'react-pluggable';
+import type { MainMenuInsertOperation } from './store';
 declare abstract class HowlerPlugin implements IPlugin {
     abstract name: string;
     abstract version: string;
@@ -27,7 +28,6 @@ declare abstract class HowlerPlugin implements IPlugin {
     deactivate(): void;
     addLead(format: string, form: (props: LeadFormProps) => React.ReactNode, renderer: (content: string, metadata: any, hit?: Hit) => React.ReactNode): void;
     addPivot(format: string, form: (props: PivotFormProps) => React.ReactNode, renderer: (props: PivotLinkProps) => React.ReactNode): void;
-    addOperation(format: string, form: (props: CustomActionProps) => React.ReactNode, documentation: PluginDocumentation): void;
     /**
      * Adds a single menu item to the User Menu group under the Avatar Menu,
      * items are added before the 'Settings' and 'Logout' menu items.
@@ -46,6 +46,58 @@ declare abstract class HowlerPlugin implements IPlugin {
      * @param icon JSX Icon element, <Settings/> for example
      */
     addAdminMenuItem(i18nKey: string, route: string, icon: JSX.Element): void;
+    /**
+     * Adds a single route to the system to load, items are added to the end of
+     * base routes defined.
+     *
+     * @param path Route path, should not start with /
+     * @param element Element the route directs to
+     * @param children Child routes if required
+     */
+    addRoute(path: string, element: JSX.Element, children?: []): void;
+    /**
+     * Adds a sitemap entry to the sitemap table, this is used to populate
+     * information on the Breadcrumb component
+     *
+     * @param path The react router path to this route
+     * @param title The title/label to display in breadcrumbs for this route
+     * @param icon The icon component to show beside the title/label
+     * @param isRoot When true, indicates that the breadcrumbs will reset to this one path each time it is encountered
+     * @param isLeaf When true, indicates that this path does not aggregate in breadcrumbs, i.e. will be replaced by next path
+     * @param excluded When true, indicates to breadcrumbs component to not render this route
+     * @param breadcrumbs Static list of breadcrumb paths to be rendered for the given route
+     * @param textWidth The max width of the text when rendering the breadcrumb
+     */
+    addSitemap(path: string, title: string, icon?: JSX.Element, isRoot?: boolean, isLeaf?: boolean, excluded?: boolean, breadcrumbs?: string[], textWidth?: number): void;
+    /**
+     * Adds a route as well as a simple sitemap entry with values derived from the path
+     *
+     * @param path Route path, should not start with /
+     * @param element Element the route directs to
+     * @param children Child routes if required
+     * @param title The title/label to display in breadcrumbs for this route
+     * @param icon The icon component to show beside the title/label
+     */
+    addRouteAndSitemap(path: string, element: JSX.Element, title: string, icon?: JSX.Element, children?: []): void;
+    /**
+     * Adds a new menu item to the Main Menu
+     *
+     * @param operation Insert operation to perform
+     * @param targetId Reference Menu Id
+     * @param id Identifier for new menu entry
+     * @param i18nKey Translation key for new menu entry
+     * @param route Route for new menu entry
+     * @param icon Icon for new menu entry
+     */
+    addMainMenuItem(operation: MainMenuInsertOperation, targetId: string, id: string, i18nKey: string, route: string, icon: JSX.Element): void;
+    /**
+     * Adds a divider to the main menu
+     *
+     * @param operation Insert operation to perform
+     * @param targetId Reference menu id
+     */
+    addMainMenuDivider(operation: MainMenuInsertOperation, targetId: string): void;
+    addOperation(format: string, form: (props: CustomActionProps) => React.ReactNode, documentation: PluginDocumentation): void;
     on(_event: string, _hit: Hit): any;
     provider(): React.FC<PropsWithChildren<{}>> | null;
     setup(): void;

package/plugins/HowlerPlugin.js

@@ -8,7 +8,16 @@ const INTERNAL_FUNCTIONS = [
     'init',
     'activate',
     'deactivate',
-    'addLead'
+    'addLead',
+    'addPivot',
+    'addUserMenuItem',
+    'addAdminMenuItem',
+    'addRoute',
+    'addSitemap',
+    'addRouteAndSitemap',
+    'addMainMenuItem',
+    'addMainMenuDivider',
+    'addOperation'
 ];
 class HowlerPlugin {
     pluginStore;
@@ -59,19 +68,6 @@ class HowlerPlugin {
         // eslint-disable-next-line no-console
         console.debug(`Pivot format ${format} enabled for plugin ${this.getPluginName()}`);
     }
-    addOperation(format, form, documentation) {
-        if (!howlerPluginStore.addOperation(format)) {
-            // eslint-disable-next-line no-console
-            console.error(`Operation ${format} already configured, not enabling for plugin ${this.getPluginName()}`);
-            return;
-        }
-        this.pluginStore.addFunction(`operation.${format}`, form);
-        this.functionsToRemove.push(`operation.${format}`);
-        this.pluginStore.addFunction(`operation.${format}.documentation`, () => documentation);
-        this.functionsToRemove.push(`operation.${format}.documentation`);
-        // eslint-disable-next-line no-console
-        console.debug(`Operation ${format} enabled for plugin ${this.getPluginName()}`);
-    }
     /**
      * Adds a single menu item to the User Menu group under the Avatar Menu,
      * items are added before the 'Settings' and 'Logout' menu items.
@@ -102,6 +98,142 @@ class HowlerPlugin {
             icon: icon
         });
     }
+    /**
+     * Adds a single route to the system to load, items are added to the end of
+     * base routes defined.
+     *
+     * @param path Route path, should not start with /
+     * @param element Element the route directs to
+     * @param children Child routes if required
+     */
+    addRoute(path, element, children) {
+        howlerPluginStore.addRoute({
+            path: path,
+            element: element,
+            children: children
+        });
+    }
+    /**
+     * Adds a sitemap entry to the sitemap table, this is used to populate
+     * information on the Breadcrumb component
+     *
+     * @param path The react router path to this route
+     * @param title The title/label to display in breadcrumbs for this route
+     * @param icon The icon component to show beside the title/label
+     * @param isRoot When true, indicates that the breadcrumbs will reset to this one path each time it is encountered
+     * @param isLeaf When true, indicates that this path does not aggregate in breadcrumbs, i.e. will be replaced by next path
+     * @param excluded When true, indicates to breadcrumbs component to not render this route
+     * @param breadcrumbs Static list of breadcrumb paths to be rendered for the given route
+     * @param textWidth The max width of the text when rendering the breadcrumb
+     */
+    addSitemap(path, title, icon, isRoot, isLeaf, excluded, breadcrumbs, textWidth) {
+        if (isRoot === isLeaf) {
+            throw new Error(`Sitemap '${path}' must define either isRoot or isLeaf as true`);
+        }
+        if (isRoot) {
+            if (breadcrumbs != null) {
+                breadcrumbs = null;
+                console.warn(`Sitemap '${path}' with isRoot should not contain breadcrumbs and have been removed`);
+            }
+        }
+        howlerPluginStore.addSitemap({
+            path: path,
+            title: title,
+            icon: icon,
+            isRoot: isRoot,
+            isLeaf: isLeaf,
+            excluded: excluded,
+            breadcrumbs: breadcrumbs,
+            textWidth: textWidth
+        });
+    }
+    /**
+     * Adds a route as well as a simple sitemap entry with values derived from the path
+     *
+     * @param path Route path, should not start with /
+     * @param element Element the route directs to
+     * @param children Child routes if required
+     * @param title The title/label to display in breadcrumbs for this route
+     * @param icon The icon component to show beside the title/label
+     */
+    addRouteAndSitemap(path, element, title, icon, children) {
+        this.addRoute(path, element, children);
+        const routeParts = path.split('/');
+        let isRoot = true;
+        let isLeaf = false;
+        let breadcrumbs = null;
+        if (routeParts.length > 1) {
+            // Set as leaf and not root
+            isRoot = false;
+            isLeaf = true;
+            // Attempt to auto build breadcrumbs
+            breadcrumbs = [];
+            for (let index = 0; index < routeParts.length - 1; index++) {
+                breadcrumbs.push(`/${routeParts[index]}`);
+            }
+        }
+        this.addSitemap(`/${path}`, title, icon, isRoot, isLeaf, false, breadcrumbs);
+    }
+    /**
+     * Adds a new menu item to the Main Menu
+     *
+     * @param operation Insert operation to perform
+     * @param targetId Reference Menu Id
+     * @param id Identifier for new menu entry
+     * @param i18nKey Translation key for new menu entry
+     * @param route Route for new menu entry
+     * @param icon Icon for new menu entry
+     */
+    addMainMenuItem(operation, targetId, id, i18nKey, route, icon) {
+        if (targetId === '') {
+            targetId = 'root';
+        }
+        howlerPluginStore.addMainMenuItem({
+            operation: operation,
+            targetId: targetId,
+            item: {
+                type: 'item',
+                element: {
+                    id: id,
+                    i18nKey: i18nKey,
+                    route: route,
+                    icon: icon
+                }
+            }
+        });
+    }
+    /**
+     * Adds a divider to the main menu
+     *
+     * @param operation Insert operation to perform
+     * @param targetId Reference menu id
+     */
+    addMainMenuDivider(operation, targetId) {
+        if (targetId === '') {
+            targetId = 'root';
+        }
+        howlerPluginStore.addMainMenuItem({
+            operation: operation,
+            targetId: targetId,
+            item: {
+                type: 'divider',
+                element: null
+            }
+        });
+    }
+    addOperation(format, form, documentation) {
+        if (!howlerPluginStore.addOperation(format)) {
+            // eslint-disable-next-line no-console
+            console.error(`Operation ${format} already configured, not enabling for plugin ${this.getPluginName()}`);
+            return;
+        }
+        this.pluginStore.addFunction(`operation.${format}`, form);
+        this.functionsToRemove.push(`operation.${format}`);
+        this.pluginStore.addFunction(`operation.${format}.documentation`, () => documentation);
+        this.functionsToRemove.push(`operation.${format}.documentation`);
+        // eslint-disable-next-line no-console
+        console.debug(`Operation ${format} enabled for plugin ${this.getPluginName()}`);
+    }
     on(_event, _hit) {
         return null;
     }

package/plugins/store.d.ts

@@ -1,10 +1,16 @@
 import type { Hit } from '@cccsaurora/howler-ui/models/entities/generated/Hit';
 import { Event } from 'react-pluggable';
 import type HowlerPlugin from './HowlerPlugin';
+import type { AppLeftNavElement } from '../commons/components/app/AppConfigs';
 export declare class HitEvent extends Event {
     hit: Hit;
     constructor(type: string, hit: Hit);
 }
+export declare enum MainMenuInsertOperation {
+    Insert = "INSERT",
+    InsertAfter = "AFTER",
+    InsertBefore = "BEFORE"
+}
 declare class HowlerPluginStore {
     private _pluginStore;
     plugins: string[];
@@ -13,36 +19,46 @@ declare class HowlerPluginStore {
     private _operations;
     private _userMenuItems;
     private _adminMenuItems;
+    private _mainMenuOperations;
+    private _routes;
+    private _sitemaps;
     install(plugin: HowlerPlugin): void;
     addLead(format: string): boolean;
     addPivot(format: string): boolean;
-    addOperation(format: string): boolean;
-    /**
-     * Adds a single menu item to the User Menu group under the Avatar Menu,
-     * items are added before the 'Settings' and 'Logout' menu items.
-     *
-     * @param menuItem Menu Item {i18nKey, route, icon}
-     */
     addUserMenuItem(menuItem: {
         i18nKey: string;
         route: string;
         icon: JSX.Element;
     }): void;
-    /**
-     * Adds a single menu item to the Admin Menu group under the Avatar Menu,
-     * items are added to the end of the existing Admin menu items.
-     *
-     * @param menuItem Menu Item {i18nKey, route, icon}
-     */
     addAdminMenuItem(menuItem: {
         i18nKey: string;
         route: string;
         icon: JSX.Element;
     }): void;
+    addMainMenuItem(menuOperation: {
+        operation: string;
+        targetId: string;
+        item: AppLeftNavElement;
+    }): void;
+    addRoute(route: {
+        path: string;
+        element: JSX.Element;
+        children?: [];
+    }): void;
+    addSitemap(sitemap: {
+        path: string;
+        title: string;
+        icon?: JSX.Element;
+        isRoot?: boolean;
+        isLeaf?: boolean;
+        excluded?: boolean;
+        breadcrumbs?: string[];
+        textWidth?: number;
+    }): void;
+    addOperation(format: string): boolean;
     get leadFormats(): string[];
     get pivotFormats(): string[];
     get operations(): string[];
-    get pluginStore(): import("react-pluggable").PluginStore;
     get userMenuItems(): {
         i18nKey: string;
         route: string;
@@ -53,6 +69,27 @@ declare class HowlerPluginStore {
         route: string;
         icon: JSX.Element;
     }[];
+    get mainMenuOperations(): {
+        operation: string;
+        targetId: string;
+        item: AppLeftNavElement;
+    }[];
+    get routes(): {
+        path: string;
+        element: JSX.Element;
+        children?: [];
+    }[];
+    get sitemaps(): {
+        path: string;
+        title: string;
+        icon?: JSX.Element;
+        isRoot?: boolean;
+        isLeaf?: boolean;
+        excluded?: boolean;
+        breadcrumbs?: string[];
+        textWidth?: number;
+    }[];
+    get pluginStore(): import("react-pluggable").PluginStore;
 }
 declare const howlerPluginStore: HowlerPluginStore;
 export default howlerPluginStore;

package/plugins/store.js

@@ -6,6 +6,12 @@ export class HitEvent extends Event {
         this.hit = hit;
     }
 }
+export var MainMenuInsertOperation;
+(function (MainMenuInsertOperation) {
+    MainMenuInsertOperation["Insert"] = "INSERT";
+    MainMenuInsertOperation["InsertAfter"] = "AFTER";
+    MainMenuInsertOperation["InsertBefore"] = "BEFORE";
+})(MainMenuInsertOperation || (MainMenuInsertOperation = {}));
 class HowlerPluginStore {
     _pluginStore = createPluginStore();
     plugins = [];
@@ -14,6 +20,9 @@ class HowlerPluginStore {
     _operations = [];
     _userMenuItems = [];
     _adminMenuItems = [];
+    _mainMenuOperations = [];
+    _routes = [];
+    _sitemaps = [];
     install(plugin) {
         console.log(`Installing plugin ${plugin.getPluginName()} by ${plugin.author}`);
         this.plugins.push(plugin.name);
@@ -33,6 +42,21 @@ class HowlerPluginStore {
         this._pivotFormats.push(format);
         return true;
     }
+    addUserMenuItem(menuItem) {
+        this._userMenuItems.push(menuItem);
+    }
+    addAdminMenuItem(menuItem) {
+        this._adminMenuItems.push(menuItem);
+    }
+    addMainMenuItem(menuOperation) {
+        this._mainMenuOperations.push(menuOperation);
+    }
+    addRoute(route) {
+        this._routes.push(route);
+    }
+    addSitemap(sitemap) {
+        this._sitemaps.push(sitemap);
+    }
     addOperation(format) {
         if (this._operations.includes(format)) {
             return false;
@@ -40,24 +64,6 @@ class HowlerPluginStore {
         this._operations.push(format);
         return true;
     }
-    /**
-     * Adds a single menu item to the User Menu group under the Avatar Menu,
-     * items are added before the 'Settings' and 'Logout' menu items.
-     *
-     * @param menuItem Menu Item {i18nKey, route, icon}
-     */
-    addUserMenuItem(menuItem) {
-        this._userMenuItems.push(menuItem);
-    }
-    /**
-     * Adds a single menu item to the Admin Menu group under the Avatar Menu,
-     * items are added to the end of the existing Admin menu items.
-     *
-     * @param menuItem Menu Item {i18nKey, route, icon}
-     */
-    addAdminMenuItem(menuItem) {
-        this._adminMenuItems.push(menuItem);
-    }
     get leadFormats() {
         return this._leadFormats;
     }
@@ -67,15 +73,24 @@ class HowlerPluginStore {
     get operations() {
         return this._operations;
     }
-    get pluginStore() {
-        return this._pluginStore;
-    }
     get userMenuItems() {
         return this._userMenuItems;
     }
     get adminMenuItems() {
         return this._adminMenuItems;
     }
+    get mainMenuOperations() {
+        return this._mainMenuOperations;
+    }
+    get routes() {
+        return this._routes;
+    }
+    get sitemaps() {
+        return this._sitemaps;
+    }
+    get pluginStore() {
+        return this._pluginStore;
+    }
 }
 const howlerPluginStore = new HowlerPluginStore();
 export default howlerPluginStore;

package/utils/menuUtils.d.ts

@@ -0,0 +1,89 @@
+import type { AppLeftNavElement, AppLeftNavItem } from '../commons/components/app/AppConfigs';
+declare class AppMenuBuilder {
+    private items;
+    private indexMap;
+    constructor(defaultMenu: AppLeftNavElement[]);
+    /**
+     * Applies a collection of Menu Operation objects created by the plugin system
+     *
+     * @param operations Operations created by the plugin system
+     */
+    applyOperations(operations: {
+        operation: string;
+        targetId: string;
+        item: AppLeftNavElement;
+    }[]): void;
+    /**
+     * Get the completed menu structure
+     */
+    get menu(): AppLeftNavElement[];
+    /**
+     * Insert provided menu item at the menu object identified by targetId.
+     *
+     * If the target menu is a group then item will be placed at end of sub items
+     *
+     * If the target menu is a standard item then group will be created and new item added, warning this removes
+     * the route from the new group parent item, be sure to add it back.
+     *
+     * If the target is 'root' then item will be added to end of root menu
+     *
+     * @param targetId Identifier of menu to insert to
+     * @param item Menu Item to insert
+     */
+    insert(targetId: string, item: AppLeftNavElement): void;
+    /**
+     * Insert provided menu item before the menu object identified by targetId.
+     *
+     * @param targetId Identifier of menu to insert to
+     * @param item Menu Item to insert
+     */
+    insertBefore(targetId: string, item: AppLeftNavElement): void;
+    /**
+     * Insert provided menu item after the menu object identified by targetId.
+     *
+     * @param targetId Identifier of menu to insert to
+     * @param item Menu Item to insert
+     */
+    insertAfter(targetId: string, item: AppLeftNavElement): void;
+    /**
+     * Locates menu location in menu structure by menu id.
+     *
+     * @param id Menu Id to search for
+     * @return {index: number, subIndex: number} A dictionary containing indexes needed to access Menu Item
+     */
+    indexOfMenuId(id: string): {
+        index: number;
+        subIndex?: number;
+    };
+    /**
+     *  Grabs a menu by indexes, helper function to account for an index of -1
+     *  to represent the root menu
+     *
+     * @param index First level index
+     * @param subIndex Second level index
+     * @return {} Menu item
+     */
+    menuFromIndex(index: number, subIndex?: number): AppLeftNavElement[] | AppLeftNavElement | AppLeftNavItem;
+    /**
+     * Determine if provided element is a group element
+     *
+     * @param elem Element to check
+     * @private
+     */
+    private isGroupElement;
+    /**
+     * Determine if provided element is an item element
+     *
+     * @param elem Element to check
+     * @private
+     */
+    private isItemElement;
+    /**
+     * Creates a flat list of menu items and subitems by menu id
+     * for quick lookup.
+     *
+     * @private
+     */
+    private updateMenuMap;
+}
+export default AppMenuBuilder;