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

package/src/contexts/ThemeProvider.tsx

@@ -0,0 +1,67 @@
+import { Brightness4, Brightness7 } from '@mui/icons-material';
+import {
+  IconButton,
+  ThemeProvider as MuiThemeProvider,
+  PaletteMode,
+  createTheme,
+  Theme,
+} from '@mui/material';
+import { FC, ReactNode, createContext, useContext, useMemo, useState } from 'react';
+
+export interface ThemeContextType {
+  toggleColorMode: () => void;
+  setColorMode: (mode: PaletteMode) => void;
+  mode: PaletteMode;
+}
+
+const ThemeContext = createContext<ThemeContextType | undefined>(undefined);
+
+export const useTheme = () => {
+  const context = useContext(ThemeContext);
+  if (!context) {
+    throw new Error('useTheme must be used within an AppThemeProvider');
+  }
+  return context;
+};
+
+export interface AppThemeProviderProps {
+  children: ReactNode;
+  customTheme?: (mode: PaletteMode) => Theme;
+}
+
+export const AppThemeProvider: FC<AppThemeProviderProps> = ({ children, customTheme }) => {
+  const [mode, setMode] = useState<PaletteMode>('light');
+
+  const colorMode = useMemo(
+    () => ({
+      toggleColorMode: () => {
+        setMode((prevMode) => (prevMode === 'light' ? 'dark' : 'light'));
+      },
+      setColorMode: (newMode: PaletteMode) => {
+        setMode(newMode);
+      },
+      mode,
+    }),
+    [mode]
+  );
+
+  const theme = useMemo(
+    () => (customTheme ? customTheme(mode) : createTheme({ palette: { mode } })),
+    [mode, customTheme]
+  );
+
+  return (
+    <ThemeContext.Provider value={colorMode}>
+      <MuiThemeProvider theme={theme}>{children}</MuiThemeProvider>
+    </ThemeContext.Provider>
+  );
+};
+
+export const ThemeToggleButton: FC = () => {
+  const { mode, toggleColorMode } = useTheme();
+  return (
+    <IconButton onClick={toggleColorMode} color="inherit">
+      {mode === 'dark' ? <Brightness7 /> : <Brightness4 />}
+    </IconButton>
+  );
+};

package/src/contexts/{index.d.ts → index.ts}

@@ -3,4 +3,3 @@ export * from './MenuContext';
 export * from './I18nProvider';
 export * from './ThemeProvider';
 export * from './SuiteConfigProvider';
-//# sourceMappingURL=index.d.ts.map

package/src/hooks/{index.d.ts → index.ts}

@@ -4,4 +4,3 @@ export * from './useBackupCodes';
 export * from './useUserSettings';
 export * from './useEmailVerification';
 export * from './useAuthenticatedApi';
-//# sourceMappingURL=index.d.ts.map

package/src/hooks/useAuthenticatedApi.tsx

@@ -0,0 +1,67 @@
+/**
+ * useAuthenticatedApi — React hook + provider for a shared authenticated
+ * Axios instance.
+ *
+ * The provider creates a single AxiosInstance via createAuthenticatedApiClient
+ * using the baseUrl from SuiteConfigProvider. All component libraries consume
+ * the same instance through the useAuthenticatedApi() hook, eliminating
+ * duplicate axios instances and circular dependency issues.
+ *
+ * Usage:
+ *   // In the app root (wrap inside SuiteConfigProvider):
+ *   <AuthenticatedApiProvider>
+ *     <App />
+ *   </AuthenticatedApiProvider>
+ *
+ *   // In any component library:
+ *   const api = useAuthenticatedApi();
+ *   const res = await api.get('/some-endpoint');
+ */
+
+import { createContext, ReactNode, useContext, useMemo } from 'react';
+import type { AxiosInstance } from 'axios';
+import { createAuthenticatedApiClient } from '../services/authenticatedApi';
+import { useSuiteConfig } from '../contexts/SuiteConfigProvider';
+
+const AuthenticatedApiContext = createContext<AxiosInstance | undefined>(
+  undefined,
+);
+
+export interface AuthenticatedApiProviderProps {
+  children: ReactNode;
+  /** Optional token key in localStorage. Defaults to 'authToken'. */
+  tokenKey?: string;
+}
+
+export const AuthenticatedApiProvider = ({
+  children,
+  tokenKey,
+}: AuthenticatedApiProviderProps) => {
+  const { baseUrl } = useSuiteConfig();
+
+  const api = useMemo(
+    () => createAuthenticatedApiClient(baseUrl, tokenKey),
+    [baseUrl, tokenKey],
+  );
+
+  return (
+    <AuthenticatedApiContext.Provider value={api}>
+      {children}
+    </AuthenticatedApiContext.Provider>
+  );
+};
+
+/**
+ * Returns the shared authenticated Axios instance.
+ * Must be used within an AuthenticatedApiProvider (which itself must be
+ * inside a SuiteConfigProvider).
+ */
+export const useAuthenticatedApi = (): AxiosInstance => {
+  const context = useContext(AuthenticatedApiContext);
+  if (!context) {
+    throw new Error(
+      'useAuthenticatedApi must be used within an AuthenticatedApiProvider',
+    );
+  }
+  return context;
+};

package/src/hooks/useBackupCodes.ts

@@ -0,0 +1,105 @@
+import {
+  SuiteCoreStringKey,
+  TranslatableSuiteError,
+} from '@digitaldefiance/suite-core-lib';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useSuiteConfig } from '../contexts';
+import { createAuthenticatedApiClient } from '../services';
+
+export interface UseBackupCodesOptions {
+  initialCodeCount?: number | null;
+}
+
+export interface UseBackupCodesResult {
+  backupCodesRemaining: number | null;
+  isLoading: boolean;
+  error: Error | null;
+  generateBackupCodes: (
+    password?: string,
+    mnemonic?: string
+  ) => Promise<{
+    message: string;
+    backupCodes: string[];
+  }>;
+  refreshCodeCount: () => Promise<void>;
+}
+
+export const useBackupCodes = (
+  options: UseBackupCodesOptions = {}
+): UseBackupCodesResult => {
+  const { baseUrl } = useSuiteConfig();
+  const [backupCodesRemaining, setBackupCodesRemaining] = useState<
+    number | null
+  >(options.initialCodeCount ?? null);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const requestedOnMountRef = useRef(false);
+  const api = useMemo(() => createAuthenticatedApiClient(baseUrl), [baseUrl]);
+
+  const refreshCodeCount = useCallback(async () => {
+    setIsLoading(true);
+    setError(null);
+    try {
+      const result = await api.get<{ codeCount: number }>('/user/backup-codes');
+      if (result?.data?.codeCount !== undefined) {
+        setBackupCodesRemaining(result.data.codeCount);
+      }
+    } catch (err) {
+      setError(
+        err instanceof Error
+          ? err
+          : new TranslatableSuiteError(
+              SuiteCoreStringKey.BackupCodes_FailedToFetch
+            )
+      );
+      setBackupCodesRemaining(0);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [api]);
+
+  useEffect(() => {
+    if (requestedOnMountRef.current) return;
+    if (backupCodesRemaining !== null) return;
+
+    requestedOnMountRef.current = true;
+    refreshCodeCount();
+  }, [backupCodesRemaining, refreshCodeCount]);
+
+  const generateBackupCodes = async (password?: string, mnemonic?: string) => {
+    setIsLoading(true);
+    setError(null);
+    try {
+      const result = await api.post<{ message: string; backupCodes: string[] }>(
+        '/user/backup-codes',
+        {
+          ...(password ? { password } : {}),
+          ...(mnemonic ? { mnemonic } : {}),
+        }
+      );
+      return {
+        message: result.data.message,
+        backupCodes: result.data.backupCodes,
+      };
+    } catch (err) {
+      const error =
+        err instanceof Error
+          ? err
+          : new TranslatableSuiteError(
+              SuiteCoreStringKey.BackupCodes_FailedToGenerate
+            );
+      setError(error);
+      throw error;
+    } finally {
+      setIsLoading(false);
+    }
+  };
+
+  return {
+    backupCodesRemaining,
+    isLoading,
+    error,
+    generateBackupCodes,
+    refreshCodeCount,
+  };
+};

package/src/hooks/useEmailVerification.ts

@@ -0,0 +1,54 @@
+import {
+  getSuiteCoreTranslation,
+  SuiteCoreStringKey,
+} from '@digitaldefiance/suite-core-lib';
+import { useCallback, useMemo, useState } from 'react';
+import { useSuiteConfig } from '../contexts';
+import { createAuthenticatedApiClient } from '../services';
+
+export interface UseEmailVerificationResult {
+  isVerifying: boolean;
+  error: Error | null;
+  verifyEmail: (
+    token: string
+  ) => Promise<{ success: boolean; message?: string }>;
+}
+
+export const useEmailVerification = (): UseEmailVerificationResult => {
+  const { baseUrl } = useSuiteConfig();
+  const api = useMemo(() => createAuthenticatedApiClient(baseUrl), [baseUrl]);
+  const [isVerifying, setIsVerifying] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const verifyEmail = useCallback(
+    async (verificationToken: string) => {
+      setIsVerifying(true);
+      setError(null);
+      try {
+        const result = await api.post<{ message: string }>('/user/verify-email', {
+          token: verificationToken,
+        });
+        return { success: true, message: result.data.message };
+      } catch (err: unknown) {
+        const axiosError = err as {
+          response?: { data?: { message?: string } };
+        };
+        const errorMessage =
+          axiosError.response?.data?.message ||
+          getSuiteCoreTranslation(SuiteCoreStringKey.Error_VerificationFailed);
+        const error = new Error(errorMessage);
+        setError(error);
+        return { success: false, message: errorMessage };
+      } finally {
+        setIsVerifying(false);
+      }
+    },
+    [api]
+  );
+
+  return {
+    isVerifying,
+    error,
+    verifyEmail,
+  };
+};

package/src/hooks/useExpiringValue.ts

@@ -0,0 +1,78 @@
+import { useCallback, useState } from 'react';
+
+export interface TimerInfo {
+  timeout: NodeJS.Timeout;
+  startTime: number;
+  durationMs: number;
+}
+
+export interface ExpiringValueReturn<T> {
+  value: T | undefined;
+  setValue: (newValue: T, durationSeconds?: number, saveToStorage?: boolean) => () => void;
+  clearValue: () => void;
+  getRemainingTime: () => number;
+  isActive: boolean;
+}
+
+export function useExpiringValue<T>(
+  defaultDurationSeconds: number,
+  localStorageKey?: string
+): ExpiringValueReturn<T> {
+  const [value, _setValue] = useState<T | undefined>(undefined);
+  const [timer, setTimer] = useState<TimerInfo | undefined>(undefined);
+  const [durationSeconds, _setDurationSeconds] = useState<number>(() => {
+    if (localStorageKey) {
+      const stored = localStorage.getItem(localStorageKey);
+      return stored ? parseInt(stored, 10) : defaultDurationSeconds;
+    }
+    return defaultDurationSeconds;
+  });
+
+  const getRemainingTime = useCallback((): number => {
+    if (!timer) return 0;
+    const elapsed = Date.now() - timer.startTime;
+    const remaining = Math.max(0, timer.durationMs - elapsed);
+    return Math.ceil(remaining / 1000);
+  }, [timer]);
+
+  const setValue = useCallback((newValue: T, customDurationSeconds?: number, saveToStorage?: boolean) => {
+    const finalDurationSeconds = customDurationSeconds ?? durationSeconds;
+    
+    if (saveToStorage && customDurationSeconds !== undefined && localStorageKey) {
+      _setDurationSeconds(customDurationSeconds);
+      localStorage.setItem(localStorageKey, customDurationSeconds.toString());
+    }
+    
+    _setValue(newValue);
+    
+    if (timer) {
+      clearTimeout(timer.timeout);
+    }
+    
+    const startTime = Date.now();
+    const durationMs = finalDurationSeconds * 1000;
+    const timeout = setTimeout(() => {
+      _setValue(undefined);
+      setTimer(undefined);
+    }, durationMs);
+    
+    setTimer({ timeout, startTime, durationMs });
+    
+    return () => {
+      clearTimeout(timeout);
+      setTimer(undefined);
+    };
+  }, [durationSeconds, timer, localStorageKey]);
+
+  const clearValue = useCallback(() => {
+    if (timer) {
+      clearTimeout(timer.timeout);
+      setTimer(undefined);
+    }
+    _setValue(undefined);
+  }, [timer]);
+
+  const isActive = Boolean(timer && value !== undefined);
+
+  return { value, setValue, clearValue, getRemainingTime, isActive };
+}

package/src/hooks/useLocalStorage.ts

@@ -0,0 +1,18 @@
+import { useCallback, useState } from 'react';
+import { LocalStorageManager } from '@digitaldefiance/suite-core-lib';
+
+export function useLocalStorage<T>(
+  key: string,
+  defaultValue: T
+): [T, (value: T) => void] {
+  const [storedValue, setStoredValue] = useState<T>(() => {
+    return LocalStorageManager.getValue(key, defaultValue);
+  });
+
+  const setValue = useCallback((value: T) => {
+    setStoredValue(value);
+    LocalStorageManager.setValue(key, value);
+  }, [key]);
+
+  return [storedValue, setValue];
+}

package/src/hooks/useUserSettings.ts

@@ -0,0 +1,271 @@
+import { EmailString } from '@digitaldefiance/ecies-lib';
+import {
+  CurrencyCode,
+  DefaultCurrencyCode,
+  DefaultLanguageCode,
+  DefaultTimezone,
+  Timezone,
+} from '@digitaldefiance/i18n-lib';
+import {
+  dehydrateUserSettings,
+  getSuiteCoreTranslation,
+  IUserSettings,
+  IUserSettingsDTO,
+  SuiteCoreStringKey,
+  TranslatableSuiteError,
+} from '@digitaldefiance/suite-core-lib';
+import { useCallback, useEffect, useState } from 'react';
+import { useAuth, useI18n, useTheme } from '../contexts';
+
+const defaultUserSettings: Partial<IUserSettings> = {
+  darkMode: false,
+  currency: new CurrencyCode(DefaultCurrencyCode),
+  timezone: new Timezone(DefaultTimezone),
+  siteLanguage: DefaultLanguageCode,
+  directChallenge: false,
+} as const;
+
+export interface UseUserSettingsOptions {
+  authenticatedApi: {
+    post: <T = unknown>(
+      url: string,
+      data: Record<string, unknown>
+    ) => Promise<{ data: T }>;
+  };
+  isAuthenticated: boolean;
+}
+
+export interface UseUserSettingsResult {
+  currentLanguage: string;
+  changeLanguage: (languageCode: string) => Promise<void>;
+  userSettings: IUserSettings | undefined;
+  setUserSettingAndUpdateSettings: (
+    setting?: Partial<IUserSettings>
+  ) => Promise<void>;
+  toggleColorMode: () => Promise<void>;
+}
+
+/**
+ * Hook for managing user settings state and synchronization.
+ * Used by AuthProvider to handle user settings logic.
+ */
+export const useUserSettings = ({
+  authenticatedApi,
+  isAuthenticated,
+}: UseUserSettingsOptions): UseUserSettingsResult => {
+  const { setColorMode: themeSetPaletteMode, mode: currentThemeMode } =
+    useTheme();
+  const { currentLanguage, changeLanguage } = useI18n();
+  const [userSettings, setUserSettings] = useState<IUserSettings | undefined>(
+    undefined
+  );
+
+  const setUserSettingAndUpdateSettings = useCallback(
+    async (setting?: Partial<IUserSettings>) => {
+      if (setting) {
+        // Merge settings with defaults and existing settings
+        const merged = {
+          ...defaultUserSettings,
+          ...(userSettings ? userSettings : {}),
+          ...setting,
+        };
+
+        // TypeScript requires all IUserSettings fields, but during initialization
+        // some fields like email may not be set yet. We'll use Partial until
+        // all required fields are available.
+        setUserSettings(merged as IUserSettings);
+
+        if (setting.darkMode !== undefined) {
+          themeSetPaletteMode(setting.darkMode ? 'dark' : 'light');
+        }
+        if (
+          setting.siteLanguage !== undefined &&
+          setting.siteLanguage !== currentLanguage
+        ) {
+          await changeLanguage(setting.siteLanguage);
+        }
+
+        // Send to server if authenticated and we have complete settings (including email)
+        if (isAuthenticated && merged.email) {
+          const dehydratedSettings = dehydrateUserSettings(
+            merged as IUserSettings
+          );
+          await authenticatedApi.post(
+            '/user/settings',
+            dehydratedSettings as unknown as Record<string, unknown>
+          );
+        }
+      } else {
+        setUserSettings(undefined);
+        themeSetPaletteMode('light');
+      }
+    },
+    [
+      isAuthenticated,
+      userSettings,
+      currentLanguage,
+      changeLanguage,
+      themeSetPaletteMode,
+      authenticatedApi,
+    ]
+  );
+
+  const changeLanguageSetting = useCallback(
+    async (languageCode: string) => {
+      await setUserSettingAndUpdateSettings({ siteLanguage: languageCode });
+    },
+    [setUserSettingAndUpdateSettings]
+  );
+
+  const toggleColorMode = useCallback(async () => {
+    // When not authenticated, read from the current theme mode
+    // When authenticated, read from userSettings (synced with server)
+    const currentDarkMode = isAuthenticated
+      ? userSettings?.darkMode ?? false
+      : currentThemeMode === 'dark';
+    await setUserSettingAndUpdateSettings({ darkMode: !currentDarkMode });
+  }, [
+    isAuthenticated,
+    userSettings?.darkMode,
+    currentThemeMode,
+    setUserSettingAndUpdateSettings,
+  ]);
+
+  return {
+    changeLanguage: changeLanguageSetting,
+    currentLanguage,
+    userSettings,
+    setUserSettingAndUpdateSettings,
+    toggleColorMode,
+  };
+};
+
+// Public-facing hook for components
+export interface UserSettingsValues extends IUserSettingsDTO {
+  [key: string]: string | boolean | undefined;
+}
+
+export interface UseUserSettingsPublicResult {
+  settings: UserSettingsValues | null;
+  isLoading: boolean;
+  error: Error | null;
+  updateSettings: (values: UserSettingsValues) => Promise<
+    | {
+        success: boolean;
+        message: string;
+      }
+    | {
+        error: string;
+        errorType?: string;
+        field?: string;
+        errors?: Array<{ path: string; msg: string }>;
+      }
+  >;
+  refreshSettings: () => Promise<void>;
+}
+
+/**
+ * Public hook for components to manage user settings.
+ * Provides a simpler API for fetching and updating settings.
+ */
+export const useUserSettingsPublic = (): UseUserSettingsPublicResult => {
+  const { userData, setUserSetting, userSettings } = useAuth();
+  const [settings, setSettings] = useState<UserSettingsValues | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<Error | null>(null);
+
+  const refreshSettings = useCallback(async () => {
+    setIsLoading(true);
+    setError(null);
+    try {
+      if (userSettings) {
+        const dehydratedSettings = dehydrateUserSettings(userSettings);
+        setSettings(dehydratedSettings as UserSettingsValues);
+      } else if (userData) {
+        const fallback = {
+          email: userData.email || '',
+          timezone: userData.timezone || 'UTC',
+          siteLanguage: userData.siteLanguage || 'en-US',
+          currency: userData.currency || 'USD',
+          darkMode: userData.darkMode || false,
+          directChallenge: userData.directChallenge || false,
+          ...(userData.displayName !== undefined ? { displayName: userData.displayName } : {}),
+        };
+        setSettings(fallback);
+      }
+    } catch (err) {
+      setError(
+        err instanceof Error
+          ? err
+          : new TranslatableSuiteError(
+              SuiteCoreStringKey.Settings_RetrieveFailure
+            )
+      );
+    } finally {
+      setIsLoading(false);
+    }
+  }, [userSettings, userData]);
+
+  useEffect(() => {
+    refreshSettings();
+  }, [refreshSettings]);
+
+  const updateSettings = useCallback(
+    async (values: UserSettingsValues) => {
+      setIsLoading(true);
+      setError(null);
+      try {
+        await setUserSetting({
+          darkMode: values.darkMode,
+          currency: new CurrencyCode(values.currency),
+          timezone: new Timezone(values.timezone),
+          siteLanguage: values.siteLanguage,
+          email: new EmailString(values.email),
+          directChallenge: values.directChallenge,
+          ...(values.displayName !== undefined ? { displayName: values.displayName } : {}),
+        });
+
+        setSettings(values);
+
+        return {
+          success: true,
+          message: getSuiteCoreTranslation(
+            SuiteCoreStringKey.Settings_SaveSuccess
+          ),
+        };
+      } catch (err: unknown) {
+        const axiosError = err as {
+          response?: {
+            data?: {
+              message?: string;
+              errorType?: string;
+              field?: string;
+              errors?: Array<{ path: string; msg: string }>;
+            };
+          };
+        };
+        const errorMessage =
+          axiosError.response?.data?.message ||
+          getSuiteCoreTranslation(SuiteCoreStringKey.Settings_UpdateFailed);
+        setError(err instanceof Error ? err : new Error(errorMessage));
+        return {
+          error: errorMessage,
+          errorType: axiosError.response?.data?.errorType,
+          field: axiosError.response?.data?.field,
+          errors: axiosError.response?.data?.errors,
+        };
+      } finally {
+        setIsLoading(false);
+      }
+    },
+    [setUserSetting]
+  );
+
+  return {
+    settings,
+    isLoading,
+    error,
+    updateSettings,
+    refreshSettings,
+  };
+};

package/src/{index.d.ts → index.ts}

@@ -1,3 +1,4 @@
+// Export all components
 export * from './auth';
 export * from './components';
 export * from './contexts';
@@ -6,4 +7,3 @@ export * from './interfaces';
 export * from './services';
 export * from './types';
 export * from './wrappers';
-//# sourceMappingURL=index.d.ts.map

package/src/interfaces/IAppConfig.ts

@@ -0,0 +1,7 @@
+export interface IAppConfig {
+  hostname: string;
+  siteTitle: string;
+  server: string;
+  /** Whether TOTP two-factor authentication is available on this deployment. */
+  totpAvailable?: boolean;
+}