@suaveplan/react-auth-whitelabel - White-label authentication React components with tenant branding wired through @suaveplan/react-ui runtime theme mutator

White-label authentication React components with tenant branding wired through the @suaveplan/react-ui runtime theme-token mutator.

Documentation tree

login-form — <LoginForm> is the white-label login surface consumed by every tenant in the stack. It renders a controlled e…
- login-form — <LoginForm> is the white-label login surface consumed by every tenant in the stack. It renders a controlled e…
password-reset-form — <PasswordResetForm> is the white-label password-reset surface. It owns a single state machine across two modes — `req…
- password-reset-confirm — PasswordResetConfirm is the confirm-mode body of <PasswordResetForm> — the screen the user lands on from the email…
- password-reset-form — <PasswordResetForm> is the white-label password-reset surface. It owns a single state machine across two modes — `req…
- password-reset-request — PasswordResetRequest is the request-mode body of <PasswordResetForm> — the screen the user lands on when they click…
- password-reset-success — PasswordResetSuccess is the success state of <PasswordResetForm>, shared between the request and confirm modes. It…
register-form — <RegisterForm> is the white-label self-registration surface. It renders the header (logo + title + subtitle), the inl…
- register-form-fields — RegisterFormFields is the inner field block of <RegisterForm> — name (optional, optionally required), email, passwo…
- register-form-terms — RegisterFormTerms is the terms-acceptance checkbox block of <RegisterForm>. It renders the acceptance checkbox, the…
- register-form — <RegisterForm> is the white-label self-registration surface. It renders the header (logo + title + subtitle), the inl…
auth-context — auth-context.tsx ships the <AuthProvider> React context provider together with the three hooks useAuth, useUser…
auth-http — auth-http.ts houses the three helpers every AuthProvider verb shares: resolveFetch, resolveNavigate, and `postJ…
branding-context — branding-context.tsx ships the <BrandingProvider> React context provider together with the hooks useBranding, `us…
error-codes — error-codes.ts registers the canonical, stable error-code registry used by every error thrown from `@suaveplan/react-…
react-auth-whitelabel-error — ReactAuthWhitelabelError is the canonical error class for every error thrown by @suaveplan/react-auth-whitelabel. I…
types — TenantBrandingSchema is the Zod schema that validates every TenantBranding payload entering the package from an unt…
- branding.schema — TenantBrandingSchema is the Zod schema that validates every TenantBranding payload entering the package from an unt…
utils — navigateOrCall(target) is the canonical helper used by every form component in this package to act on a "URL or click…
- navigate-or-call — navigateOrCall(target) is the canonical helper used by every form component in this package to act on a "URL or click…

What ships

Forms — LoginForm, RegisterForm, PasswordResetForm
Contexts — AuthProvider, BrandingProvider
Hooks — useAuth, useBranding, useIsAuthenticated, useLogo, useTenantBranding, useUser
Types — AuthConfig, AuthContextValue, AuthUser, BrandingContextValue, BrandingProviderProps, RegisterData, TenantBranding, TenantBrandingSchema
Errors — REACT_AUTH_WL_CODES + ReactAuthWhitelabelError

Quick start

BrandingProvider calls useThemeMutator() from @suaveplan/react-ui/theme. That hook MUST be invoked inside a <ThemeProvider>. Wrap your subtree like this:

import { ThemeProvider, lightTheme } from "@suaveplan/react-ui/theme";
import {
    AuthProvider,
    BrandingProvider,
    LoginForm,
} from "@suaveplan/react-auth-whitelabel";

<ThemeProvider themes={[lightTheme]} defaultTheme="light">
    <BrandingProvider
        brandingEndpoint="/api/branding"
        tenantId={tenantSlug}
    >
        <AuthProvider config={{ authUrl: "/api/auth" }}>
            <LoginForm
                onForgotPassword={() => router.push("/forgot")}
                onRegister={() => router.push("/register")}
            />
        </AuthProvider>
    </BrandingProvider>
</ThemeProvider>;

On every branding change, BrandingProvider writes --brand-primary, --brand-secondary, --brand-accent, and --brand-font to document.documentElement.style via useThemeMutator().setExtensionTokens(...). Cleanup is automatic on unmount.

Modules

Out of scope (Excluded)

MFA / passkey / WebAuthn flows — deferred until @suaveplan/webauthn
- @suaveplan/otp ship .
Magic-link / SMS OTP — depends on @suaveplan/security-codes / @suaveplan/emailer / @suaveplan/sms.
Better-Auth first-class adapter — overlaps with the concurrent @suaveplan/react-auth Wave 1.
Audit-log integration, password-strength meter, rate limiter, axe-core story gate — depend on packages not yet .
Bundle-size snapshot — repo-wide tooling not yet wired.
Playwright E2E specs — see e2e/README.md.

7.5 KiB Raw Permalink Blame History