@zango-core/appbuilder 1.0.0-rc.1

package/dist/types/__tests__/utils/mockRouterUtils.d.ts

@@ -0,0 +1,62 @@
+import { default as React } from 'react';
+export declare const mockNavigate: import('vitest').Mock<import('@vitest/spy').Procedure>;
+export declare const mockLocation: {
+    pathname: string;
+    search: string;
+    hash: string;
+    state: null;
+    key: string;
+};
+/**
+ * Helper to set mock location
+ */
+export declare const setMockLocation: (location: Partial<typeof mockLocation>) => void;
+/**
+ * Reset router mocks
+ */
+export declare const resetRouterMocks: () => void;
+/**
+ * Create a mock for react-router-dom
+ * Use with vi.mock('react-router-dom', () => createRouterMock())
+ */
+export declare const createRouterMock: () => {
+    useNavigate: () => import('vitest').Mock<import('@vitest/spy').Procedure>;
+    useLocation: () => {
+        pathname: string;
+        search: string;
+        hash: string;
+        state: null;
+        key: string;
+    };
+    useParams: () => {};
+    useSearchParams: () => (URLSearchParams | import('vitest').Mock<import('@vitest/spy').Procedure>)[];
+    Link: ({ children, to, ...props }: {
+        children: React.ReactNode;
+        to: string;
+        [key: string]: unknown;
+    }) => React.ReactElement<{
+        href: string;
+    }, string | React.JSXElementConstructor<any>>;
+    NavLink: ({ children, to, ...props }: {
+        children: React.ReactNode;
+        to: string;
+        [key: string]: unknown;
+    }) => React.ReactElement<{
+        href: string;
+    }, string | React.JSXElementConstructor<any>>;
+    Outlet: () => null;
+    Routes: ({ children }: {
+        children: React.ReactNode;
+    }) => React.ReactNode;
+    Route: () => null;
+    MemoryRouter: ({ children }: {
+        children: React.ReactNode;
+    }) => React.ReactNode;
+    BrowserRouter: ({ children }: {
+        children: React.ReactNode;
+    }) => React.ReactNode;
+};
+/**
+ * Parse URL search params helper
+ */
+export declare const parseSearchParams: (search: string) => Record<string, string>;

package/dist/types/__tests__/utils/renderWithProviders.d.ts

@@ -0,0 +1,22 @@
+import { RenderOptions, RenderResult, render } from '@testing-library/react';
+import { ReactElement } from 'react';
+import { MemoryRouterProps } from 'react-router-dom';
+interface CustomRenderOptions extends Omit<RenderOptions, 'wrapper'> {
+    routerProps?: MemoryRouterProps;
+    initialEntries?: string[];
+}
+/**
+ * Render with MemoryRouter wrapper
+ * Use this for components that need routing context
+ */
+export declare const renderWithRouter: (ui: ReactElement, options?: CustomRenderOptions) => RenderResult;
+/**
+ * Re-export common testing library utilities
+ */
+export { act, fireEvent, screen, waitFor, within } from '@testing-library/react';
+export { default as userEvent } from '@testing-library/user-event';
+/**
+ * Simple render without providers
+ * Use this for pure components without dependencies
+ */
+export { render };

package/dist/types/__tests__/utils/waitForHelpers.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Wait for loading spinner to disappear
+ */
+export declare const waitForLoadingToFinish: (testId?: string) => Promise<void>;
+/**
+ * Wait for loading text to disappear
+ */
+export declare const waitForLoadingTextToFinish: (text?: RegExp) => Promise<void>;
+/**
+ * Wait for element to appear then disappear
+ */
+export declare const waitForElementToDisappear: (testId: string) => Promise<void>;
+/**
+ * Wait for async state updates (useful after act())
+ */
+export declare const waitForStateUpdate: () => Promise<void>;
+/**
+ * Wait for navigation to be called with expected path
+ */
+export declare const waitForNavigation: (expectedPath: string, navigate: ReturnType<typeof import("vitest").vi.fn>) => Promise<void>;
+/**
+ * Wait for element to be visible
+ */
+export declare const waitForElement: (testId: string, timeout?: number) => Promise<void>;
+/**
+ * Wait for text to be visible
+ */
+export declare const waitForText: (text: string | RegExp, timeout?: number) => Promise<void>;
+/**
+ * Delay helper for tests that need explicit timing
+ */
+export declare const delay: (ms: number) => Promise<unknown>;
+/**
+ * Wait for fetch request to complete
+ */
+export declare const waitForRequest: (timeout?: number) => Promise<void>;

package/dist/types/auth/components/AuthMobileShell.d.ts

@@ -0,0 +1,8 @@
+import { default as React } from 'react';
+export interface AuthMobileShellProps {
+    appName?: string;
+    appLogo?: string;
+    brandColor?: string;
+    children: React.ReactNode;
+}
+export declare const AuthMobileShell: React.FC<AuthMobileShellProps>;

package/dist/types/auth/components/AuthProvider.d.ts

@@ -0,0 +1,30 @@
+import { default as React } from 'react';
+import { AuthConfig, LoginCredentials, PasswordResetConfirm, PasswordResetRequest, UserRole } from '../../types';
+import { AuthApiResponse } from '../../types/common';
+interface AuthContextValue {
+    user: Record<string, unknown> | null;
+    loading: boolean;
+    error: string | null;
+    login: (credentials: LoginCredentials) => Promise<AuthApiResponse>;
+    logout: () => Promise<void>;
+    selectRole: (role: UserRole) => Promise<Record<string, unknown>>;
+    checkAuth: () => Promise<void>;
+    processAuthResult: (response: Record<string, unknown>) => Record<string, unknown>;
+    forgotPassword: (data: {
+        email?: string;
+        phone?: string;
+        method: string;
+    }) => Promise<unknown>;
+    resetPassword: (data: PasswordResetRequest | PasswordResetConfirm) => Promise<unknown>;
+    isAuthenticated: boolean;
+    pendingAuth: AuthApiResponse | null;
+    availableRoles: unknown[] | null;
+    authConfig: Record<string, unknown> | null;
+    requiresRoleSelection: boolean;
+}
+export declare const useAuthContext: () => AuthContextValue;
+export declare const AuthProvider: ({ children, config }: {
+    children: React.ReactNode;
+    config?: AuthConfig;
+}) => React.JSX.Element;
+export {};

package/dist/types/auth/components/DynamicLoginForm.d.ts

@@ -0,0 +1,9 @@
+import { default as React } from 'react';
+import { LoginCredentials } from '../../types';
+import { AuthResponse } from '../utils/authFlowHandler';
+interface DynamicLoginFormProps {
+    onLogin: (data: LoginCredentials | AuthResponse) => Promise<void>;
+    showRememberMe?: boolean;
+}
+export declare const DynamicLoginForm: React.FC<DynamicLoginFormProps>;
+export {};

package/dist/types/auth/components/ForgotPasswordForm.d.ts

@@ -0,0 +1,11 @@
+import { default as React } from 'react';
+interface ForgotPasswordFormProps {
+    onSubmit: (data: {
+        email?: string;
+        phone?: string;
+        method: string;
+    }) => Promise<void>;
+    logo?: React.ReactNode;
+}
+export declare const ForgotPasswordForm: React.FC<ForgotPasswordFormProps>;
+export {};

package/dist/types/auth/components/LoginForm.d.ts

@@ -0,0 +1,7 @@
+interface LoginFormProps {
+    onLogin?: (values: Record<string, unknown>) => Promise<void>;
+    showRememberMe?: boolean;
+    showForgotPassword?: boolean;
+}
+export declare const LoginForm: ({ onLogin, showRememberMe, showForgotPassword }: LoginFormProps) => import("react").JSX.Element;
+export {};

package/dist/types/auth/components/LoginRouter.d.ts

@@ -0,0 +1,197 @@
+import { default as React } from 'react';
+import { ApiConfig, AuthResult } from '../../types';
+interface LoginRouterProps {
+    basePath?: string;
+    apiConfig?: ApiConfig;
+    onAuthComplete?: (result: AuthResult) => void;
+    logo?: React.ReactNode;
+    title?: string;
+    subtitle?: string;
+    roleSelectionTitle?: string;
+    roleSelectionSubtitle?: string;
+    twoFactorTitle?: string;
+    twoFactorSubtitle?: string;
+    passwordResetTitle?: string;
+    passwordResetSubtitle?: string;
+}
+interface MockRole {
+    id: number;
+    name: string;
+    description: string;
+    permissions: string[];
+    is_default: boolean;
+}
+/** @internal Mock API config for development/testing — no-op in production */
+export declare const createMockApiConfig: (_selectedScenario: unknown) => ReturnType<typeof _createMockApiConfig>;
+declare function _createMockApiConfig(_selectedScenario: unknown): {
+    loginEndpoint: string;
+    logoutEndpoint: string;
+    verifyEndpoint: string;
+    forgotPasswordEndpoint: string;
+    resetPasswordEndpoint: string;
+    loginMethodsEndpoint: string;
+    otpRequestEndpoint: string;
+    otpVerifyEndpoint: string;
+    apiClient: {
+        post: (endpoint: string, data: Record<string, unknown>) => Promise<{
+            requires2FA?: boolean;
+            requiresPasswordReset?: boolean;
+            passwordResetReason?: string;
+            twoFactorMethods?: string[];
+            user: {
+                id: number;
+                username: string;
+                email: string;
+                mobile: string;
+                name: string;
+            };
+            token: string;
+            roles: MockRole[];
+            success?: undefined;
+            message?: undefined;
+        } | {
+            success: boolean;
+            message: string;
+            user?: undefined;
+            token?: undefined;
+            roles?: undefined;
+            requires2FA?: undefined;
+            twoFactorMethods?: undefined;
+            requiresPasswordReset?: undefined;
+            passwordResetReason?: undefined;
+        } | {
+            message: string;
+            success?: undefined;
+            user?: undefined;
+            token?: undefined;
+            roles?: undefined;
+            requires2FA?: undefined;
+            twoFactorMethods?: undefined;
+            requiresPasswordReset?: undefined;
+            passwordResetReason?: undefined;
+        } | {
+            requires2FA?: boolean;
+            requiresPasswordReset?: boolean;
+            passwordResetReason?: string;
+            twoFactorMethods?: string[];
+            success: boolean;
+            message?: undefined;
+            user?: undefined;
+            token?: undefined;
+            roles?: undefined;
+        } | {
+            user: {
+                id: number;
+                email: string;
+                name: string;
+                username: string;
+            };
+            token: string;
+            roles: MockRole[];
+            requires2FA: boolean;
+            twoFactorMethods: string[];
+            success?: undefined;
+            message?: undefined;
+            requiresPasswordReset?: undefined;
+            passwordResetReason?: undefined;
+        } | {
+            user: {
+                id: number;
+                email: string;
+                name: string;
+                username: string;
+            };
+            token: string;
+            requiresPasswordReset: boolean;
+            passwordResetReason: string;
+            success?: undefined;
+            message?: undefined;
+            roles?: undefined;
+            requires2FA?: undefined;
+            twoFactorMethods?: undefined;
+        } | {
+            user: {
+                id: number;
+                email: string;
+                name: string;
+                username: string;
+            };
+            token: string;
+            success?: undefined;
+            message?: undefined;
+            roles?: undefined;
+            requires2FA?: undefined;
+            twoFactorMethods?: undefined;
+            requiresPasswordReset?: undefined;
+            passwordResetReason?: undefined;
+        }>;
+        get: (endpoint: string) => Promise<{
+            success: boolean;
+            response: {
+                auth_config: {
+                    login_methods: {
+                        password: {
+                            enabled: boolean;
+                            forgot_password_enabled: boolean;
+                            allowed_usernames: string[];
+                        };
+                        otp: {
+                            enabled: boolean;
+                            allowed_methods: string[];
+                        };
+                        sso: {
+                            enabled: boolean;
+                            providers: {
+                                id: number;
+                                label: string;
+                            }[];
+                        };
+                        oidc: {
+                            enabled: boolean;
+                        };
+                    };
+                    password_policy: {
+                        min_length: number;
+                        require_numbers: boolean;
+                        require_lowercase: boolean;
+                        require_uppercase: boolean;
+                        require_special_chars: boolean;
+                        password_expiry_days: number;
+                        password_history_count: number;
+                        allow_change: boolean;
+                        reset: {
+                            enabled: boolean;
+                            method: string[];
+                            expiry_hours: number;
+                        };
+                    };
+                    session_policy: {
+                        remember_me_enabled: boolean;
+                        remember_me_duration_days: number;
+                    };
+                    two_factor_auth: {
+                        required: boolean;
+                        allowed_methods: never[];
+                    };
+                };
+            };
+            id?: undefined;
+            username?: undefined;
+            email?: undefined;
+        } | {
+            id: number;
+            username: string;
+            email: string;
+            success?: undefined;
+            response?: undefined;
+        } | {
+            success?: undefined;
+            response?: undefined;
+            id?: undefined;
+            username?: undefined;
+            email?: undefined;
+        }>;
+    };
+};
+export declare const LoginRouter: React.FC<LoginRouterProps>;
+export {};

package/dist/types/auth/components/OAuthCallback.d.ts

@@ -0,0 +1,19 @@
+import { default as React } from 'react';
+import { ApiConfig, AuthResult, PendingAuthResult } from '../../types';
+interface OAuthCallbackProps {
+    onSuccess?: (result: AuthResult | PendingAuthResult) => void;
+    onError?: (error: Error) => void;
+    apiConfig?: ApiConfig;
+    redirectPath?: string;
+    title?: string;
+    errorTitle?: string;
+    logo?: React.ReactNode;
+    roleSelectionTitle?: string;
+    roleSelectionSubtitle?: string;
+    twoFactorTitle?: string;
+    twoFactorSubtitle?: string;
+    passwordResetTitle?: string;
+    passwordResetSubtitle?: string;
+}
+export declare const OAuthCallback: ({ onSuccess, onError, apiConfig, redirectPath, title, errorTitle, logo, roleSelectionTitle, roleSelectionSubtitle, twoFactorTitle, twoFactorSubtitle, passwordResetTitle, passwordResetSubtitle, }: OAuthCallbackProps) => React.JSX.Element;
+export {};

package/dist/types/auth/components/OTPForm.d.ts

@@ -0,0 +1,11 @@
+import { default as React } from 'react';
+import { AuthResponse } from '../utils/authFlowHandler';
+interface OTPFormProps {
+    onSuccess: (result: AuthResponse) => void;
+    onBack?: () => void;
+    submitButtonText?: string;
+    verifyButtonText?: string;
+    resendButtonText?: string;
+}
+export declare const OTPForm: React.FC<OTPFormProps>;
+export {};

package/dist/types/auth/components/OTPInput.d.ts

@@ -0,0 +1,8 @@
+interface OTPInputProps {
+    length?: number;
+    value?: string;
+    onChange?: (value: string) => void;
+    disabled?: boolean;
+}
+export declare const OTPInput: ({ length, value, onChange, disabled }: OTPInputProps) => import("react").JSX.Element;
+export {};

package/dist/types/auth/components/PasswordResetRequired.d.ts

@@ -0,0 +1,23 @@
+import { default as React } from 'react';
+interface PasswordRules {
+    minLength: number;
+    maxLength?: number;
+    requireUppercase: boolean;
+    requireLowercase: boolean;
+    requireNumbers: boolean;
+    requireSpecialChars: boolean;
+}
+interface PasswordResetRequiredProps {
+    reason?: string;
+    onReset: (data: {
+        password: string;
+        confirmPassword: string;
+    }) => Promise<void>;
+    loading?: boolean;
+    title?: string;
+    subtitle?: string;
+    passwordRules?: PasswordRules;
+    logo?: React.ReactNode;
+}
+export declare const PasswordResetRequired: React.FC<PasswordResetRequiredProps>;
+export {};

package/dist/types/auth/components/ProviderButton.d.ts

@@ -0,0 +1,17 @@
+import { default as React } from 'react';
+interface ProviderButtonProps {
+    provider: Record<string, unknown> & {
+        label?: string;
+        id?: string;
+        provider_type?: string;
+        url?: string;
+        icon_url?: string;
+        name?: string;
+        provider?: string;
+    };
+    type?: 'default' | 'sso' | 'oidc';
+    prefix?: string;
+    postfix?: string;
+}
+export declare const ProviderButton: ({ provider, type, prefix, postfix, }: ProviderButtonProps) => React.ReactElement;
+export {};

package/dist/types/auth/components/ResetPasswordForm.d.ts

@@ -0,0 +1,12 @@
+import { default as React } from 'react';
+interface ResetPasswordFormProps {
+    onSubmit: (data: {
+        password: string;
+        confirmPassword: string;
+        token: string;
+    }) => Promise<void>;
+    token: string;
+    logo?: React.ReactNode;
+}
+export declare const ResetPasswordForm: React.FC<ResetPasswordFormProps>;
+export {};

package/dist/types/auth/components/RoleSelection.d.ts

@@ -0,0 +1,25 @@
+import { default as React } from 'react';
+interface Role {
+    id: string;
+    name: string;
+    description?: string;
+    permissions?: string[];
+    is_default?: boolean;
+}
+interface RoleSelectionUser {
+    id?: string;
+    name?: string;
+    username?: string;
+    email?: string;
+}
+interface RoleSelectionProps {
+    user?: RoleSelectionUser;
+    roles: Role[];
+    onRoleSelect: (role: Role) => Promise<void>;
+    loading?: boolean;
+    title?: string;
+    subtitle?: string;
+    logo?: React.ReactNode;
+}
+export declare const RoleSelection: React.FC<RoleSelectionProps>;
+export {};

package/dist/types/auth/components/SecondFactorAuth.d.ts

@@ -0,0 +1,21 @@
+import { default as React } from 'react';
+interface User {
+    id?: string;
+    name?: string;
+    username?: string;
+    email?: string;
+    mobile?: string;
+}
+interface SecondFactorAuthProps {
+    user?: User;
+    availableMethods?: ('sms' | 'email' | 'totp')[];
+    onVerify: (result: unknown) => Promise<void>;
+    loading?: boolean;
+    otpDigits?: number;
+    retryInterval?: number;
+    title?: string;
+    subtitle?: string;
+    logo?: React.ReactNode;
+}
+export declare const SecondFactorAuth: React.FC<SecondFactorAuthProps>;
+export {};

package/dist/types/auth/components/composable/OTPLoginForm.d.ts

@@ -0,0 +1,17 @@
+import { default as React } from 'react';
+interface OTPLoginFormProps {
+    onSuccess?: (data: unknown) => void;
+    onBack?: () => void;
+    submitButtonText?: string;
+    verifyButtonText?: string;
+    resendButtonText?: string;
+}
+/**
+ * OTPLoginForm - Composable component for OTP-based login
+ *
+ * Automatically handles:
+ * - OTP request and verification
+ * - Delegates multi-step authentication to parent via LoginContext or onSuccess
+ */
+export declare const OTPLoginForm: React.FC<OTPLoginFormProps>;
+export {};

package/dist/types/auth/components/composable/PasswordLoginForm.d.ts

@@ -0,0 +1,17 @@
+import { default as React } from 'react';
+interface PasswordLoginFormProps {
+    onSuccess?: (data: unknown) => void;
+    showRememberMe?: boolean;
+    submitButtonText?: string;
+}
+/**
+ * PasswordLoginForm - Composable component for password-based login
+ *
+ * Automatically handles:
+ * - Auth configuration loading
+ * - Email/mobile tabs based on allowed usernames
+ * - Form validation
+ * - Delegates multi-step authentication to parent via LoginContext or onSuccess
+ */
+export declare const PasswordLoginForm: React.FC<PasswordLoginFormProps>;
+export {};

package/dist/types/auth/components/composable/SSOButtons.d.ts

@@ -0,0 +1,61 @@
+import { default as React } from 'react';
+export interface SSOButtonsProps {
+    /**
+     * Layout mode for multiple providers
+     * - 'column': Stack buttons vertically (default)
+     * - 'grid': Display in a responsive grid (2 columns on desktop, 1 on mobile)
+     * - 'row': Display side by side (horizontal)
+     *
+     * Note: Single button always takes full width regardless of layout
+     */
+    layout?: 'column' | 'grid' | 'row';
+    /**
+     * Gap between buttons (in Tailwind spacing units)
+     * @default 2 for column/row, 3 for grid
+     */
+    gap?: number;
+    /**
+     * Custom class name for the container
+     */
+    className?: string;
+    /**
+     * Prefix text for the provider buttons
+     * @default "Continue with"
+     */
+    buttonTextPrefix?: string;
+    /**
+     * Postfix text for the provider buttons
+     * @default ""
+     */
+    buttonTextPostfix?: string;
+}
+/**
+ * SSOButtons - Self-contained component that renders SSO/OIDC provider buttons
+ *
+ * This component automatically:
+ * - Fetches auth configuration from API
+ * - Checks if SSO/OIDC is enabled
+ * - Renders provider buttons if available
+ * - Handles OAuth/SAML redirects
+ * - Returns null if no providers are configured
+ * - Single button takes full width automatically
+ * - Multiple buttons can be laid out in column/grid/row
+ *
+ * @example
+ * ```tsx
+ * import { SSOButtons } from '@zango/auth/composable';
+ *
+ * // Default: Column layout
+ * <SSOButtons />
+ *
+ * // Grid layout (2 columns)
+ * <SSOButtons layout="grid" />
+ *
+ * // Row layout (side by side)
+ * <SSOButtons layout="row" />
+ *
+ * // Custom gap
+ * <SSOButtons layout="grid" gap={4} />
+ * ```
+ */
+export declare const SSOButtons: React.FC<SSOButtonsProps>;

package/dist/types/auth/components/composable/index.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Composable Authentication Components
+ *
+ * Self-contained, reusable components for building custom authentication flows.
+ * All components automatically fetch their configuration from the API and handle
+ * the complete authentication flow internally.
+ *
+ * @example
+ * ```tsx
+ * import { SSOButtons, PasswordLoginForm, OTPLoginForm } from '@zango/auth/composable';
+ *
+ * // Custom login card with choice between SSO and password login
+ * function CustomLoginCard() {
+ *   const [showPasswordForm, setShowPasswordForm] = useState(false);
+ *
+ *   return (
+ *     <div>
+ *       {!showPasswordForm ? (
+ *         <>
+ *           <h2>Choose Login Method</h2>
+ *           <SSOButtons />
+ *           <button onClick={() => setShowPasswordForm(true)}>
+ *             Normal Login
+ *           </button>
+ *         </>
+ *       ) : (
+ *         <>
+ *           <PasswordLoginForm />
+ *           <button onClick={() => setShowPasswordForm(false)}>Back</button>
+ *         </>
+ *       )}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export { LoginContext, useLoginContext } from '../../contexts/LoginContext';
+export { PasswordResetRequired } from '../PasswordResetRequired';
+export { RoleSelection } from '../RoleSelection';
+export { OTPLoginForm } from './OTPLoginForm';
+export { PasswordLoginForm } from './PasswordLoginForm';
+export { SSOButtons } from './SSOButtons';