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