@incodetech/web 2.0.0-alpha.1

package/src/flow/useFlowInitialization.test.tsx

@@ -0,0 +1,292 @@
+import { act, renderHook, waitFor } from '@testing-library/preact';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const mockFlowManager = {
+  load: vi.fn(),
+  getState: vi.fn(() => ({ status: 'idle' })),
+  subscribe: vi.fn(() => vi.fn()),
+  stop: vi.fn(),
+};
+
+const mockSetupSDK = vi.fn().mockResolvedValue(undefined);
+const mockFetchTheme = vi.fn().mockResolvedValue({
+  theme: { logo: 'logo.png' },
+  uiConfig: { logoSrc: 'logo.png' },
+});
+
+vi.mock('./flowInit', () => ({
+  createFlowManager: vi.fn(() => mockFlowManager),
+  setupSDK: (...args: unknown[]) => mockSetupSDK(...args),
+  fetchTheme: () => mockFetchTheme(),
+}));
+
+const mockGetPreloadedData = vi.fn();
+const mockConsumePreloadedData = vi.fn();
+
+vi.mock('./preloadFlow', () => ({
+  getPreloadedData: (...args: unknown[]) => mockGetPreloadedData(...args),
+  consumePreloadedData: (...args: unknown[]) =>
+    mockConsumePreloadedData(...args),
+}));
+
+const mockSetUiConfig = vi.fn();
+vi.mock('../shared/uiConfig/uiConfig', () => ({
+  setUiConfig: (...args: unknown[]) => mockSetUiConfig(...args),
+}));
+
+import { useFlowInitialization } from './useFlowInitialization';
+
+describe('useFlowInitialization', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockGetPreloadedData.mockReturnValue(null);
+    mockConsumePreloadedData.mockReturnValue(null);
+    mockSetupSDK.mockResolvedValue(undefined);
+    mockFetchTheme.mockResolvedValue({
+      theme: { logo: 'logo.png' },
+      uiConfig: { logoSrc: 'logo.png' },
+    });
+  });
+
+  afterEach(() => {
+    vi.resetAllMocks();
+  });
+
+  it('should start in initializing state when no preload', () => {
+    const { result } = renderHook(() =>
+      useFlowInitialization({
+        apiURL: 'https://api.example.com',
+        token: 'test-token',
+      }),
+    );
+
+    expect(result.current.status).toBe('initializing');
+    expect(result.current.flowManager).toBeDefined();
+  });
+
+  it('should use preloaded data when available and ready', () => {
+    const preloadedFlowManager = {
+      ...mockFlowManager,
+      preloaded: true,
+    };
+
+    mockGetPreloadedData.mockReturnValue({
+      status: 'ready',
+      flowManager: preloadedFlowManager,
+      uiConfig: { logoSrc: 'preloaded-logo.png' },
+    });
+
+    mockConsumePreloadedData.mockReturnValue({
+      status: 'ready',
+      flowManager: preloadedFlowManager,
+      uiConfig: { logoSrc: 'preloaded-logo.png' },
+    });
+
+    const { result } = renderHook(() =>
+      useFlowInitialization({
+        apiURL: 'https://api.example.com',
+        token: 'preloaded-token',
+      }),
+    );
+
+    expect(result.current.status).toBe('ready');
+    expect(result.current.flowManager).toBe(preloadedFlowManager);
+    expect(mockSetUiConfig).toHaveBeenCalledWith({
+      logoSrc: 'preloaded-logo.png',
+    });
+  });
+
+  it('should show error when preload failed', () => {
+    mockGetPreloadedData.mockReturnValue({
+      status: 'error',
+      error: 'Preload failed',
+    });
+
+    const { result } = renderHook(() =>
+      useFlowInitialization({
+        apiURL: 'https://api.example.com',
+        token: 'error-token',
+      }),
+    );
+
+    expect(result.current.status).toBe('error');
+    if (result.current.status === 'error') {
+      expect(result.current.error).toBe('Preload failed');
+    }
+  });
+
+  it('should wait for preload when loading', async () => {
+    let resolvePreload: (value: unknown) => void;
+    const readyPromise = new Promise((resolve) => {
+      resolvePreload = resolve;
+    });
+
+    const preloadedFlowManager = {
+      ...mockFlowManager,
+      preloaded: true,
+    };
+
+    mockGetPreloadedData.mockReturnValue({
+      status: 'loading',
+      readyPromise,
+    });
+
+    const { result } = renderHook(() =>
+      useFlowInitialization({
+        apiURL: 'https://api.example.com',
+        token: 'loading-token',
+      }),
+    );
+
+    expect(result.current.status).toBe('initializing');
+
+    mockConsumePreloadedData.mockReturnValue({
+      status: 'ready',
+      flowManager: preloadedFlowManager,
+      uiConfig: { logoSrc: 'loaded-logo.png' },
+    });
+
+    await act(async () => {
+      resolvePreload?.(undefined);
+    });
+
+    await waitFor(() => {
+      expect(result.current.status).toBe('ready');
+    });
+
+    expect(result.current.flowManager).toBe(preloadedFlowManager);
+  });
+
+  it('should initialize SDK and become ready', async () => {
+    const { result } = renderHook(() =>
+      useFlowInitialization({
+        apiURL: 'https://api.example.com',
+        token: 'init-token',
+        lang: 'es',
+      }),
+    );
+
+    expect(result.current.status).toBe('initializing');
+
+    await waitFor(() => {
+      expect(result.current.status).toBe('ready');
+    });
+
+    expect(mockSetupSDK).toHaveBeenCalledWith({
+      apiURL: 'https://api.example.com',
+      token: 'init-token',
+      lang: 'es',
+    });
+
+    expect(mockFlowManager.load).toHaveBeenCalled();
+  });
+
+  it('should fetch theme during initialization', async () => {
+    const { result } = renderHook(() =>
+      useFlowInitialization({
+        apiURL: 'https://api.example.com',
+        token: 'theme-token',
+        disableDashboardTheme: false,
+      }),
+    );
+
+    await waitFor(() => {
+      expect(result.current.status).toBe('ready');
+    });
+
+    expect(mockFetchTheme).toHaveBeenCalled();
+  });
+
+  it('should skip theme fetch when disabled', async () => {
+    const { result } = renderHook(() =>
+      useFlowInitialization({
+        apiURL: 'https://api.example.com',
+        token: 'no-theme-token',
+        disableDashboardTheme: true,
+      }),
+    );
+
+    await waitFor(() => {
+      expect(result.current.status).toBe('ready');
+    });
+
+    expect(mockFetchTheme).not.toHaveBeenCalled();
+  });
+
+  it('should call onError when SDK setup fails', async () => {
+    mockSetupSDK.mockRejectedValueOnce(new Error('SDK error'));
+
+    const onError = vi.fn();
+
+    const { result } = renderHook(() =>
+      useFlowInitialization({
+        apiURL: 'https://api.example.com',
+        token: 'sdk-error-token',
+        onError,
+      }),
+    );
+
+    await waitFor(() => {
+      expect(result.current.status).toBe('error');
+    });
+
+    if (result.current.status === 'error') {
+      expect(result.current.error).toBe('SDK error');
+    }
+    expect(onError).toHaveBeenCalledWith('SDK error');
+  });
+
+  it('should handle preload promise rejection', async () => {
+    const readyPromise = Promise.reject(new Error('Preload rejected'));
+
+    mockGetPreloadedData.mockReturnValue({
+      status: 'loading',
+      readyPromise,
+    });
+
+    const onError = vi.fn();
+
+    const { result } = renderHook(() =>
+      useFlowInitialization({
+        apiURL: 'https://api.example.com',
+        token: 'reject-token',
+        onError,
+      }),
+    );
+
+    await waitFor(() => {
+      expect(result.current.status).toBe('error');
+    });
+
+    if (result.current.status === 'error') {
+      expect(result.current.error).toBe('Preload rejected');
+    }
+    expect(onError).toHaveBeenCalledWith('Preload rejected');
+  });
+
+  it('should not re-initialize when options change after ready', async () => {
+    const { result, rerender } = renderHook<
+      ReturnType<typeof useFlowInitialization>,
+      { apiURL: string; token: string; lang?: string }
+    >((props) => useFlowInitialization(props), {
+      initialProps: {
+        apiURL: 'https://api.example.com',
+        token: 'stable-token',
+      },
+    });
+
+    await waitFor(() => {
+      expect(result.current.status).toBe('ready');
+    });
+
+    expect(mockSetupSDK).toHaveBeenCalledTimes(1);
+
+    rerender({
+      apiURL: 'https://api.example.com',
+      token: 'stable-token',
+      lang: 'fr',
+    });
+
+    expect(mockSetupSDK).toHaveBeenCalledTimes(1);
+  });
+});

package/src/flow/useFlowInitialization.ts

@@ -0,0 +1,128 @@
+import { useEffect, useRef, useState } from 'preact/hooks';
+import { setUiConfig } from '../shared/uiConfig/uiConfig';
+import { createFlowManager, fetchTheme, setupSDK } from './flowInit';
+import { consumePreloadedData, getPreloadedData } from './preloadFlow';
+
+type FlowManager = ReturnType<typeof createFlowManager>;
+
+type FlowInitializationOptions = {
+  apiURL: string;
+  token: string;
+  lang?: string;
+  disableDashboardTheme?: boolean;
+  onError?: (error: string) => void;
+};
+
+type FlowInitializationState =
+  | { status: 'initializing'; flowManager: FlowManager }
+  | { status: 'ready'; flowManager: FlowManager }
+  | { status: 'error'; error: string; flowManager: FlowManager };
+
+export function useFlowInitialization(
+  options: FlowInitializationOptions,
+): FlowInitializationState {
+  const { apiURL, token, lang, disableDashboardTheme, onError } = options;
+
+  const flowManagerRef = useRef<FlowManager | null>(null);
+
+  const [state, setState] = useState<FlowInitializationState>(() => {
+    const preloaded = getPreloadedData(token);
+
+    if (preloaded?.status === 'ready') {
+      const consumed = consumePreloadedData(token);
+      if (consumed) {
+        flowManagerRef.current = consumed.flowManager;
+        if (consumed.uiConfig) {
+          setUiConfig(consumed.uiConfig);
+        }
+        return { status: 'ready', flowManager: consumed.flowManager };
+      }
+    }
+
+    const flowManager = createFlowManager();
+    flowManagerRef.current = flowManager;
+
+    if (preloaded?.status === 'error') {
+      return {
+        status: 'error',
+        error: preloaded.error ?? 'Preload failed',
+        flowManager,
+      };
+    }
+
+    return { status: 'initializing', flowManager };
+  });
+
+  const initStartedRef = useRef(false);
+
+  useEffect(() => {
+    if (state.status !== 'initializing') {
+      return;
+    }
+
+    const preloaded = getPreloadedData(token);
+
+    if (preloaded?.status === 'loading') {
+      preloaded.readyPromise
+        .then(() => {
+          const consumed = consumePreloadedData(token);
+          if (consumed) {
+            flowManagerRef.current = consumed.flowManager;
+            if (consumed.uiConfig) {
+              setUiConfig(consumed.uiConfig);
+            }
+            setState({ status: 'ready', flowManager: consumed.flowManager });
+          }
+        })
+        .catch((error) => {
+          const errorMessage =
+            error instanceof Error ? error.message : 'Preload failed';
+          setState({
+            status: 'error',
+            error: errorMessage,
+            flowManager: state.flowManager,
+          });
+          onError?.(errorMessage);
+        });
+      return;
+    }
+
+    if (initStartedRef.current) {
+      return;
+    }
+    initStartedRef.current = true;
+
+    const initialize = async () => {
+      try {
+        await setupSDK({ apiURL, token, lang });
+
+        const themePromise = disableDashboardTheme
+          ? Promise.resolve()
+          : fetchTheme().then((result) => {
+              if (result.uiConfig) {
+                setUiConfig(result.uiConfig);
+              }
+            });
+
+        state.flowManager.load();
+
+        await themePromise;
+
+        setState({ status: 'ready', flowManager: state.flowManager });
+      } catch (error) {
+        const errorMessage =
+          error instanceof Error ? error.message : 'Failed to initialize SDK';
+        setState({
+          status: 'error',
+          error: errorMessage,
+          flowManager: state.flowManager,
+        });
+        onError?.(errorMessage);
+      }
+    };
+
+    initialize();
+  }, [apiURL, token, lang, disableDashboardTheme, onError, state]);
+
+  return state;
+}

package/src/flow/useModuleLoader.test.tsx

@@ -0,0 +1,212 @@
+import { renderHook, waitFor } from '@testing-library/preact';
+import type { FC } from 'preact/compat';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const MockPhoneComponent: FC = () => <div>Phone</div>;
+const MockEmailComponent: FC = () => <div>Email</div>;
+const MockSelfieComponent: FC = () => <div>Selfie</div>;
+
+vi.mock('./flowInit', () => ({
+  LAZY_UI_MODULES: {
+    PHONE: vi.fn(() => Promise.resolve(MockPhoneComponent)),
+    EMAIL: vi.fn(() => Promise.resolve(MockEmailComponent)),
+    SELFIE: vi.fn(() => Promise.resolve(MockSelfieComponent)),
+  },
+}));
+
+import { LAZY_UI_MODULES } from './flowInit';
+import { useModuleLoader, usePrefetchNextModule } from './useModuleLoader';
+
+describe('useModuleLoader', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    vi.resetAllMocks();
+  });
+
+  it('should return idle state when moduleKey is undefined', () => {
+    const { result } = renderHook(() =>
+      useModuleLoader({ moduleKey: undefined }),
+    );
+
+    expect(result.current.status).toBe('idle');
+  });
+
+  it('should return unsupported state for unknown module', () => {
+    const { result } = renderHook(() =>
+      useModuleLoader({ moduleKey: 'UNKNOWN_MODULE' }),
+    );
+
+    expect(result.current.status).toBe('unsupported');
+    if (result.current.status === 'unsupported') {
+      expect(result.current.moduleKey).toBe('UNKNOWN_MODULE');
+    }
+  });
+
+  it('should load PHONE module successfully', async () => {
+    const onModuleLoading = vi.fn();
+    const onModuleLoaded = vi.fn();
+
+    const { result } = renderHook(() =>
+      useModuleLoader({
+        moduleKey: 'PHONE',
+        onModuleLoading,
+        onModuleLoaded,
+      }),
+    );
+
+    expect(onModuleLoading).toHaveBeenCalledWith('PHONE');
+
+    await waitFor(() => {
+      expect(result.current.status).toBe('loaded');
+    });
+
+    if (result.current.status === 'loaded') {
+      expect(result.current.moduleKey).toBe('PHONE');
+      expect(result.current.Component).toBe(MockPhoneComponent);
+    }
+    expect(onModuleLoaded).toHaveBeenCalledWith('PHONE');
+  });
+
+  it('should handle module load error', async () => {
+    const loadError = new Error('Failed to load');
+    vi.mocked(LAZY_UI_MODULES.EMAIL).mockRejectedValueOnce(loadError);
+
+    const onError = vi.fn();
+
+    const { result } = renderHook(() =>
+      useModuleLoader({
+        moduleKey: 'EMAIL',
+        onError,
+      }),
+    );
+
+    await waitFor(() => {
+      expect(result.current.status).toBe('error');
+    });
+
+    if (result.current.status === 'error') {
+      expect(result.current.error).toBe('Failed to load');
+    }
+    expect(onError).toHaveBeenCalledWith(
+      'Failed to load EMAIL: Failed to load',
+    );
+  });
+
+  it('should cancel loading when moduleKey changes', async () => {
+    const onModuleLoaded = vi.fn();
+
+    let resolvePhone: ((value: unknown) => void) | undefined;
+    const phonePromise = new Promise((resolve) => {
+      resolvePhone = resolve;
+    });
+    vi.mocked(LAZY_UI_MODULES.PHONE).mockReturnValueOnce(phonePromise as never);
+
+    const { rerender } = renderHook(
+      ({ moduleKey }) =>
+        useModuleLoader({
+          moduleKey,
+          onModuleLoaded,
+        }),
+      { initialProps: { moduleKey: 'PHONE' } },
+    );
+
+    rerender({ moduleKey: 'EMAIL' });
+
+    resolvePhone?.(MockPhoneComponent);
+
+    await waitFor(() => {
+      expect(onModuleLoaded).toHaveBeenCalledWith('EMAIL');
+    });
+
+    expect(onModuleLoaded).not.toHaveBeenCalledWith('PHONE');
+  });
+
+  it('should reset to idle when moduleKey becomes undefined', async () => {
+    const { result, rerender } = renderHook(
+      ({ moduleKey }) => useModuleLoader({ moduleKey }),
+      { initialProps: { moduleKey: 'PHONE' as string | undefined } },
+    );
+
+    await waitFor(() => {
+      expect(result.current.status).toBe('loaded');
+    });
+
+    rerender({ moduleKey: undefined });
+
+    expect(result.current.status).toBe('idle');
+  });
+});
+
+describe('usePrefetchNextModule', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('should prefetch next module when available', () => {
+    const steps = ['PHONE', 'EMAIL', 'SELFIE'];
+
+    renderHook(() => usePrefetchNextModule(steps, 0));
+
+    expect(LAZY_UI_MODULES.EMAIL).toHaveBeenCalled();
+  });
+
+  it('should not prefetch when at last step', () => {
+    const steps = ['PHONE', 'EMAIL', 'SELFIE'];
+
+    renderHook(() => usePrefetchNextModule(steps, 2));
+
+    expect(LAZY_UI_MODULES.PHONE).not.toHaveBeenCalled();
+    expect(LAZY_UI_MODULES.EMAIL).not.toHaveBeenCalled();
+    expect(LAZY_UI_MODULES.SELFIE).not.toHaveBeenCalled();
+  });
+
+  it('should not prefetch same module twice', () => {
+    const steps = ['PHONE', 'EMAIL', 'SELFIE'];
+
+    const { rerender } = renderHook(
+      ({ index }) => usePrefetchNextModule(steps, index),
+      { initialProps: { index: 0 } },
+    );
+
+    expect(LAZY_UI_MODULES.EMAIL).toHaveBeenCalledTimes(1);
+
+    rerender({ index: 0 });
+
+    expect(LAZY_UI_MODULES.EMAIL).toHaveBeenCalledTimes(1);
+  });
+
+  it('should handle empty steps array', () => {
+    expect(() => {
+      renderHook(() => usePrefetchNextModule([], 0));
+    }).not.toThrow();
+  });
+
+  it('should handle prefetch failure gracefully', async () => {
+    vi.mocked(LAZY_UI_MODULES.EMAIL).mockRejectedValueOnce(
+      new Error('Prefetch failed'),
+    );
+
+    const steps = ['PHONE', 'EMAIL', 'SELFIE'];
+
+    expect(() => {
+      renderHook(() => usePrefetchNextModule(steps, 0));
+    }).not.toThrow();
+
+    expect(LAZY_UI_MODULES.EMAIL).toHaveBeenCalledTimes(1);
+
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  });
+
+  it('should skip prefetch for unsupported modules', () => {
+    const steps = ['PHONE', 'UNKNOWN_MODULE', 'SELFIE'];
+
+    renderHook(() => usePrefetchNextModule(steps, 0));
+
+    expect(LAZY_UI_MODULES.PHONE).not.toHaveBeenCalled();
+    expect(LAZY_UI_MODULES.EMAIL).not.toHaveBeenCalled();
+    expect(LAZY_UI_MODULES.SELFIE).not.toHaveBeenCalled();
+  });
+});