@digitaldefiance/express-suite-react-components 5.0.1 → 5.0.2

package/src/contexts/I18nProvider.tsx

@@ -0,0 +1,164 @@
+import {
+  GlobalActiveContext,
+  IActiveContext,
+  LanguageRegistry,
+} from '@digitaldefiance/i18n-lib';
+import {
+  createContext,
+  FC,
+  ReactNode,
+  useCallback,
+  useContext,
+  useState,
+} from 'react';
+
+/**
+ * Minimal structural interface accepted by I18nProvider.
+ * Both I18nEngine and PluginI18nEngine satisfy this interface.
+ */
+export interface II18nEngineCompat {
+  setLanguage(language: string): void;
+  translate(
+    componentId: string,
+    stringKey: string,
+    variables?: Record<string, string | number>,
+    language?: string
+  ): string;
+  translateStringKey?(
+    key: string,
+    vars?: Record<string, string | number>,
+    language?: string
+  ): string;
+  /** Template processor that handles {{component.key}} and {variable} patterns */
+  t?(
+    template: string,
+    variables?: Record<string, string | number>,
+    language?: string
+  ): string;
+}
+
+export interface I18nProviderProps {
+  children: ReactNode;
+  i18nEngine: II18nEngineCompat;
+  onLanguageChange?: (language: string) => Promise<void>;
+}
+
+export interface I18nContextType {
+  t: (
+    key: string,
+    vars?: Record<string, string | number>,
+    language?: string
+  ) => string;
+  tBranded: <TStringKey extends string>(
+    stringKey: TStringKey,
+    vars?: Record<string, string | number>,
+    language?: string
+  ) => string;
+  tComponent: <TStringKey extends string>(
+    componentId: string,
+    stringKey: TStringKey,
+    vars?: Record<string, string | number>,
+    language?: string
+  ) => string;
+  changeLanguage: (language: string) => void;
+  currentLanguage: string;
+}
+
+const I18nContext = createContext<I18nContextType | undefined>(undefined);
+
+export const I18nProvider: FC<I18nProviderProps> = ({
+  children,
+  i18nEngine,
+  onLanguageChange,
+}) => {
+  const context = GlobalActiveContext.getInstance<
+    string,
+    IActiveContext<string>
+  >();
+  const [currentLanguage, setCurrentLanguage] = useState<string>(
+    context.userLanguage
+  );
+
+  const changeLanguage = useCallback(
+    async (language: string) => {
+      const languageDetails = LanguageRegistry.getLanguageByCode(language);
+      if (language && languageDetails) {
+        context.userLanguage = language;
+        i18nEngine.setLanguage(language);
+        localStorage.setItem('language', languageDetails.name);
+        localStorage.setItem('languageCode', language);
+        setCurrentLanguage(language);
+        if (onLanguageChange) {
+          await onLanguageChange(language);
+        }
+      }
+    },
+    [onLanguageChange, i18nEngine, context]
+  );
+
+  const tBranded = useCallback(
+    (
+      key: string,
+      vars?: Record<string, string | number>,
+      language?: string
+    ) => {
+      if (!i18nEngine.translateStringKey) return `[${key}]`;
+      return i18nEngine.translateStringKey(key, vars, language ?? currentLanguage);
+    },
+    [i18nEngine, currentLanguage]
+  );
+
+  const t = useCallback(
+    (
+      key: string,
+      vars?: Record<string, string | number>,
+      language?: string
+    ) => {
+      // If the engine has a template processor and the key looks like a template
+      // (contains {{...}} or {variable} patterns), use t() for template resolution
+      if (i18nEngine.t && (/\{\{/.test(key) || /\{[A-Za-z]/.test(key))) {
+        return i18nEngine.t(key, vars, language ?? currentLanguage);
+      }
+      if (i18nEngine.translateStringKey) {
+        return i18nEngine.translateStringKey(key, vars, language ?? currentLanguage);
+      }
+      return `[${key}]`;
+    },
+    [i18nEngine, currentLanguage]
+  );
+
+  const tComponent = useCallback(
+    <TStringKey extends string>(
+      componentId: string,
+      stringKey: TStringKey,
+      vars?: Record<string, string | number>,
+      language?: string
+    ): string => {
+      return i18nEngine.translate(
+        componentId,
+        stringKey,
+        vars,
+        language ?? currentLanguage
+      );
+    },
+    [currentLanguage, i18nEngine]
+  );
+
+  const value = {
+    t,
+    tComponent,
+    tBranded,
+    changeLanguage,
+    currentLanguage,
+  };
+
+  return <I18nContext.Provider value={value}>{children}</I18nContext.Provider>;
+};
+
+export const useI18n = () => {
+  const context = useContext(I18nContext);
+  if (context === undefined) {
+    throw new Error('useI18n must be used within an I18nProvider');
+  }
+  return context;
+};

package/src/contexts/MenuContext.tsx

@@ -0,0 +1,426 @@
+// src/app/menuContext.tsx
+import {
+  IRoleDTO,
+  SuiteCoreComponentId,
+  SuiteCoreStringKey,
+  SuiteCoreStringKeyValue,
+} from '@digitaldefiance/suite-core-lib';
+import {
+  AccountCircle,
+  Autorenew as AutorenewIcon,
+  Brightness4,
+  Brightness7,
+  Dashboard as DashboardIcon,
+  Key as KeyIcon,
+  LockOpen as LockOpenIcon,
+  LockReset as LockResetIcon,
+  Login as LoginIcon,
+  ExitToApp as LogoutIcon,
+  PersonAdd as PersonAddIcon,
+  Settings,
+} from '@mui/icons-material';
+import {
+  FC,
+  ReactNode,
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+import { useUserSettings } from '../hooks';
+import { IMenuConfig } from '../interfaces/IMenuConfig';
+import { IMenuOption } from '../interfaces/IMenuOption';
+import { createAuthenticatedApiClient } from '../services';
+import { MenuType, MenuTypes } from '../types/MenuType';
+import { useAuth } from './AuthProvider';
+import { useI18n } from './I18nProvider';
+import { useSuiteConfig } from './SuiteConfigProvider';
+import { useTheme } from './ThemeProvider';
+
+interface MenuProviderProps {
+  children: ReactNode;
+  menuConfigs?: IMenuConfig[];
+  enableBackupCodes?: boolean;
+  /**
+   * IDs of menu options to suppress from every menu. Matches both the built-in
+   * options (e.g. 'change-password', 'user-settings', 'logout') and any option
+   * registered via `menuConfigs`. Dividers left orphaned by the removal are
+   * cleaned up automatically. Defaults to none hidden, so existing consumers are
+   * unaffected.
+   */
+  hiddenMenuIds?: readonly string[];
+}
+
+interface MenuContextType {
+  menuOptions: IMenuOption[];
+  getMenuOptions: (
+    menuType: MenuType,
+    includeDividers: boolean
+  ) => IMenuOption[];
+  registerMenuOption: (option: IMenuOption) => () => void;
+  registerMenuOptions: (options: IMenuOption[]) => () => void;
+  getTopMenus: () => Array<IMenuConfig>;
+}
+
+const MenuContext = createContext<MenuContextType | undefined>(undefined);
+
+export const MenuProvider: FC<MenuProviderProps> = ({
+  children,
+  menuConfigs = [],
+  enableBackupCodes = true,
+  hiddenMenuIds = [],
+}) => {
+  const {
+    userData: user,
+    isAuthenticated,
+    admin: isGlobalAdmin,
+    mnemonic,
+    clearMnemonic,
+    wallet,
+    clearWallet,
+  } = useAuth();
+  const { mode: colorMode } = useTheme();
+  const registeredMenuOptions = useRef(new Set<() => void>());
+  const [registeredOptions, setRegisteredOptions] = useState<
+    Map<string, IMenuOption>
+  >(new Map<string, IMenuOption>());
+  const { tComponent } = useI18n();
+  const { baseUrl } = useSuiteConfig();
+  const authenticatedApi = useMemo(
+    () => createAuthenticatedApiClient(baseUrl),
+    [baseUrl]
+  );
+  const { toggleColorMode } = useUserSettings({
+    authenticatedApi,
+    isAuthenticated,
+  });
+
+  const registerMenuOption = useCallback((option: IMenuOption) => {
+    const unregister = () => {
+      setRegisteredOptions((prev) => {
+        const newMap = new Map(prev);
+        newMap.delete(option.id);
+        return newMap;
+      });
+      registeredMenuOptions.current.delete(unregister);
+    };
+
+    setRegisteredOptions((prev) => {
+      const newMap = new Map(prev);
+      newMap.set(option.id, option);
+      return newMap;
+    });
+    registeredMenuOptions.current.add(unregister);
+
+    return unregister;
+  }, []);
+
+  const registerMenuOptions = useCallback(
+    (options: IMenuOption[]) => {
+      const unregisterFunctions = options.map(registerMenuOption);
+      return () => unregisterFunctions.forEach((f) => f());
+    },
+    [registerMenuOption]
+  );
+
+  const menuOptions = useMemo(() => {
+    const isUserRestricted = () => {
+      return user?.roles?.some((role: IRoleDTO) => role.child) ?? false;
+    };
+    let index = 0;
+    const baseOptions: IMenuOption[] = [
+      {
+        id: 'dashboard',
+        label: tComponent<SuiteCoreStringKeyValue>(
+          SuiteCoreComponentId,
+          SuiteCoreStringKey.Common_Dashboard
+        ),
+        icon: <DashboardIcon />,
+        link: '/dashboard',
+        requiresAuth: true,
+        includeOnMenus: [MenuTypes.SideMenu],
+        index: index++,
+      },
+      {
+        id: 'user-divider',
+        label: '',
+        divider: true,
+        includeOnMenus: [MenuTypes.SideMenu],
+        index: index++,
+        requiresAuth: false,
+      },
+      {
+        id: 'logout',
+        label: tComponent<SuiteCoreStringKeyValue>(
+          SuiteCoreComponentId,
+          SuiteCoreStringKey.LogoutButton
+        ),
+        icon: <LogoutIcon />,
+        link: '/logout',
+        requiresAuth: true,
+        includeOnMenus: [MenuTypes.UserMenu, MenuTypes.SideMenu],
+        index: index++,
+      },
+      {
+        id: 'login',
+        label: tComponent<SuiteCoreStringKeyValue>(
+          SuiteCoreComponentId,
+          SuiteCoreStringKey.Login_LoginButton
+        ),
+        icon: <LoginIcon />,
+        link: '/login',
+        requiresAuth: false,
+        includeOnMenus: [MenuTypes.UserMenu, MenuTypes.SideMenu],
+        index: index++,
+      },
+      {
+        id: 'register',
+        label: tComponent<SuiteCoreStringKeyValue>(
+          SuiteCoreComponentId,
+          SuiteCoreStringKey.RegisterButton
+        ),
+        icon: <PersonAddIcon />,
+        link: '/register',
+        requiresAuth: false,
+        includeOnMenus: [MenuTypes.UserMenu, MenuTypes.SideMenu],
+        index: index++,
+      },
+      {
+        id: 'forgot-password',
+        label: tComponent<SuiteCoreStringKeyValue>(
+          SuiteCoreComponentId,
+          SuiteCoreStringKey.ForgotPassword_Title
+        ),
+        icon: <LockOpenIcon />,
+        link: '/forgot-password',
+        requiresAuth: false,
+        includeOnMenus: [MenuTypes.UserMenu, MenuTypes.SideMenu],
+        index: index++,
+      },
+      {
+        id: 'change-password',
+        label: tComponent<SuiteCoreStringKeyValue>(
+          SuiteCoreComponentId,
+          SuiteCoreStringKey.Common_ChangePassword
+        ),
+        icon: <LockResetIcon />,
+        link: '/change-password',
+        requiresAuth: true,
+        includeOnMenus: [MenuTypes.UserMenu, MenuTypes.SideMenu],
+        index: index++,
+      },
+      ...(enableBackupCodes
+        ? [
+            {
+              id: 'backup-code',
+              label: tComponent<SuiteCoreStringKeyValue>(
+                SuiteCoreComponentId,
+                SuiteCoreStringKey.BackupCodeRecovery_Title
+              ),
+              icon: <KeyIcon />,
+              link: '/backup-code',
+              requiresAuth: false,
+              includeOnMenus: [MenuTypes.UserMenu, MenuTypes.SideMenu],
+              index: index++,
+            },
+            {
+              id: 'backup-codes',
+              label: tComponent<SuiteCoreStringKeyValue>(
+                SuiteCoreComponentId,
+                SuiteCoreStringKey.BackupCodeRecovery_GenerateNewCodes
+              ),
+              icon: <AutorenewIcon />,
+              link: '/backup-codes',
+              requiresAuth: true,
+              includeOnMenus: [MenuTypes.UserMenu, MenuTypes.SideMenu],
+              index: index++,
+            },
+          ]
+        : []),
+      {
+        id: 'divider',
+        label: '',
+        divider: true,
+        includeOnMenus: [MenuTypes.SideMenu],
+        index: index++,
+        requiresAuth: false,
+      },
+      {
+        id: 'clear-mnemonic',
+        label: tComponent<SuiteCoreStringKeyValue>(
+          SuiteCoreComponentId,
+          SuiteCoreStringKey.Common_ClearMnemonic
+        ),
+        action: clearMnemonic,
+        icon: <KeyIcon />,
+        requiresAuth: true,
+        includeOnMenus: [MenuTypes.UserMenu, MenuTypes.SideMenu],
+        index: index++,
+        filter: () => !!mnemonic,
+      },
+      {
+        id: 'clear-wallet',
+        label: tComponent<SuiteCoreStringKeyValue>(
+          SuiteCoreComponentId,
+          SuiteCoreStringKey.Common_ClearWallet
+        ),
+        action: clearWallet,
+        icon: <KeyIcon />,
+        requiresAuth: true,
+        includeOnMenus: [MenuTypes.UserMenu, MenuTypes.SideMenu],
+        index: index++,
+        filter: () => !!wallet,
+      },
+      ...(isUserRestricted() ? [] : []),
+      {
+        id: 'color-divider',
+        label: '',
+        divider: true,
+        includeOnMenus: [MenuTypes.SideMenu],
+        index: index++,
+        requiresAuth: undefined,
+      },
+      {
+        id: 'theme-toggle',
+        label:
+          colorMode === 'dark'
+            ? tComponent<SuiteCoreStringKeyValue>(
+                SuiteCoreComponentId,
+                SuiteCoreStringKey.Common_ThemeToggle_Light
+              )
+            : tComponent<SuiteCoreStringKeyValue>(
+                SuiteCoreComponentId,
+                SuiteCoreStringKey.Common_ThemeToggle_Dark
+              ),
+        icon: colorMode === 'dark' ? <Brightness7 /> : <Brightness4 />,
+        includeOnMenus: [MenuTypes.SideMenu],
+        index: index++,
+        requiresAuth: undefined,
+        action: toggleColorMode,
+      },
+      {
+        id: 'user-settings',
+        label: tComponent<SuiteCoreStringKeyValue>(
+          SuiteCoreComponentId,
+          SuiteCoreStringKey.Settings_Title
+        ),
+        icon: <Settings />,
+        link: '/user-settings',
+        requiresAuth: true,
+        includeOnMenus: [MenuTypes.UserMenu, MenuTypes.SideMenu],
+        index: index++,
+      },
+    ];
+
+    const allOptions = [...baseOptions, ...registeredOptions.values()];
+    return allOptions.sort((a, b) => a.index - b.index);
+  }, [
+    tComponent,
+    registeredOptions,
+    user?.roles,
+    colorMode,
+    toggleColorMode,
+    clearMnemonic,
+    clearWallet,
+    mnemonic,
+    wallet,
+    enableBackupCodes,
+  ]);
+
+  const getMenuOptions = useCallback(
+    (menuType: MenuType, includeDividers: boolean) => {
+      const hidden = new Set(hiddenMenuIds);
+      const MenuFilter = (o: IMenuOption) => {
+        // Suppress any option whose id the consumer asked to hide.
+        if (hidden.has(o.id)) return false;
+
+        // Apply the custom filter first
+        let customFilterPasses = true;
+        if (o.filter !== undefined) {
+          customFilterPasses = o.filter(o);
+        }
+        if (!customFilterPasses) return false;
+
+        if (o.divider === true && !includeDividers) return false;
+
+        if (o.requiresAdmin === true && !isGlobalAdmin) return false;
+
+        return (
+          o.includeOnMenus.includes(menuType) &&
+          (o.requiresAuth === undefined || o.requiresAuth === isAuthenticated)
+        );
+      };
+
+      const filtered = menuOptions.filter(MenuFilter);
+
+      // Drop dividers left orphaned once hidden items are removed: a divider at
+      // the start or end of the list, or immediately following another divider,
+      // carries no meaning and would show as a stray separator.
+      return filtered.filter((o, i) => {
+        if (o.divider !== true) return true;
+        const prev = filtered[i - 1];
+        if (prev === undefined || prev.divider === true) return false;
+        if (i === filtered.length - 1) return false;
+        return true;
+      });
+    },
+    [hiddenMenuIds, isAuthenticated, isGlobalAdmin, menuOptions]
+  );
+
+  useEffect(() => {
+    if (menuConfigs.length > 0) {
+      return registerMenuOptions(
+        menuConfigs.flatMap((config) => config.options)
+      );
+    }
+    return undefined;
+  }, [menuConfigs, registerMenuOptions]);
+
+  const getTopMenus = useCallback(() => {
+    const menus: Array<IMenuConfig & { isUserMenu?: boolean }> = [
+      ...menuConfigs.map((config) => ({ ...config, isUserMenu: false })),
+      {
+        menuType: MenuTypes.UserMenu,
+        menuIcon: <AccountCircle />,
+        priority: 0,
+        options: [],
+        isUserMenu: true,
+      },
+    ];
+    return menus.sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+  }, [menuConfigs]);
+
+  const contextValue = useMemo(() => {
+    return {
+      menuOptions: menuOptions,
+      getMenuOptions: getMenuOptions,
+      registerMenuOption: registerMenuOption,
+      registerMenuOptions: registerMenuOptions,
+      getTopMenus: getTopMenus,
+    };
+  }, [
+    menuOptions,
+    getMenuOptions,
+    registerMenuOption,
+    registerMenuOptions,
+    getTopMenus,
+  ]);
+
+  const memoizedChildren = useMemo(() => children, [children]);
+  return (
+    <MenuContext.Provider value={contextValue}>
+      {memoizedChildren}
+    </MenuContext.Provider>
+  );
+};
+
+export const useMenu = (): MenuContextType => {
+  const context = useContext(MenuContext);
+  if (context === undefined) {
+    throw new Error('useMenu must be used within a MenuProvider');
+  }
+  return context;
+};

package/src/contexts/SuiteConfigProvider.tsx

@@ -0,0 +1,93 @@
+import { createContext, ReactNode, useContext } from 'react';
+
+export interface SuiteConfigRoutes {
+  dashboard?: string;
+  login?: string;
+  register?: string;
+  verifyEmail?: string;
+  forgotPassword?: string;
+  resetPassword?: string;
+  settings?: string;
+}
+
+export interface SuiteConfigContextData {
+  /**
+   * Base URL for API calls
+   */
+  baseUrl: string;
+  
+  /**
+   * Application routes for navigation
+   */
+  routes: SuiteConfigRoutes;
+  
+  /**
+   * Available languages for the application
+   */
+  languages: Array<{ code: string; label: string }>;
+  
+  /**
+   * Available timezones
+   */
+  timezones?: string[];
+}
+
+const defaultRoutes: SuiteConfigRoutes = {
+  dashboard: '/dashboard',
+  login: '/login',
+  register: '/register',
+  verifyEmail: '/verify-email',
+  forgotPassword: '/forgot-password',
+  resetPassword: '/reset-password',
+  settings: '/settings',
+};
+
+const defaultLanguages = [
+  { code: 'en-US', label: 'English (US)' },
+  { code: 'en-GB', label: 'English (UK)' },
+  { code: 'es-ES', label: 'Español' },
+  { code: 'fr-FR', label: 'Français' },
+  { code: 'de-DE', label: 'Deutsch' },
+  { code: 'ja', label: '日本語' },
+  { code: 'zh-CN', label: '中文 (简体)' },
+  { code: 'uk', label: 'Українська' },
+];
+
+const SuiteConfigContext = createContext<SuiteConfigContextData | undefined>(undefined);
+
+export interface SuiteConfigProviderProps {
+  children: ReactNode;
+  baseUrl: string;
+  routes?: Partial<SuiteConfigRoutes>;
+  languages?: Array<{ code: string; label: string }>;
+  timezones?: string[];
+}
+
+export const SuiteConfigProvider = ({
+  children,
+  baseUrl,
+  routes = {},
+  languages = defaultLanguages,
+  timezones,
+}: SuiteConfigProviderProps) => {
+  const value: SuiteConfigContextData = {
+    baseUrl,
+    routes: { ...defaultRoutes, ...routes },
+    languages,
+    timezones,
+  };
+
+  return (
+    <SuiteConfigContext.Provider value={value}>
+      {children}
+    </SuiteConfigContext.Provider>
+  );
+};
+
+export const useSuiteConfig = (): SuiteConfigContextData => {
+  const context = useContext(SuiteConfigContext);
+  if (!context) {
+    throw new Error('useSuiteConfig must be used within a SuiteConfigProvider');
+  }
+  return context;
+};