@udibo/oauth2 0.1.0

package/esm/react/components/reset-password-form.d.ts

@@ -0,0 +1,66 @@
+/**
+ * {@link ResetPasswordForm} — a default, accessible, unstyled "set a new
+ * password" form built on {@link useAuthForm}. Collects a new password and its
+ * confirmation, validates the match on the client, and forwards an opaque
+ * reset `token` (from the reset link) to your `onSubmit`.
+ *
+ * @module
+ */
+import { type ReactNode } from "react";
+import type { AuthFormState } from "./use-auth-form.js";
+import type { BaseAuthFormProps } from "./types.js";
+/** Values collected by {@link ResetPasswordForm}. */
+export type ResetPasswordValues = {
+    /** The new password. */
+    password: string;
+    /** Confirmation of the new password. */
+    confirmPassword: string;
+    /** The opaque reset token from the link; passed through from `token`. */
+    token: string;
+};
+/** Visible text overrides for {@link ResetPasswordForm}. */
+export interface ResetPasswordLabels {
+    /** Label for the password field. Default: `"New password"`. */
+    password?: string;
+    /** Label for the confirm field. Default: `"Confirm new password"`. */
+    confirmPassword?: string;
+    /** Submit button text. Default: `"Reset password"`. */
+    submit?: string;
+    /** Submit button text while submitting. Default: `"Resetting…"`. */
+    submitting?: string;
+    /** Password-mismatch message. Default: `"Passwords do not match."`. */
+    passwordMismatch?: string;
+}
+/** Props for {@link ResetPasswordForm}. */
+export interface ResetPasswordFormProps extends BaseAuthFormProps<ResetPasswordValues> {
+    /** The opaque reset token, typically read from the URL by your route. */
+    token?: string;
+    /** Text overrides. */
+    labels?: ResetPasswordLabels;
+    /**
+     * Render-prop escape hatch. When provided, you own the markup and receive
+     * the live {@link AuthFormState}.
+     */
+    children?: (state: AuthFormState<ResetPasswordValues>) => ReactNode;
+}
+/**
+ * A ready-to-use "set a new password" form. Pass the reset `token` from the
+ * link; it is forwarded to `onSubmit` alongside the password. A client-side
+ * check blocks submission on password mismatch.
+ *
+ * @example
+ * ```tsx
+ * <ResetPasswordForm
+ *   token={new URLSearchParams(location.search).get("token") ?? ""}
+ *   onSubmit={async (values) => {
+ *     const res = await fetch("/auth/reset-password", {
+ *       method: "POST",
+ *       headers: { "content-type": "application/json" },
+ *       body: JSON.stringify(values),
+ *     });
+ *     if (!res.ok) return await res.json();
+ *   }}
+ * />
+ * ```
+ */
+export declare function ResetPasswordForm(props: ResetPasswordFormProps): ReactNode;

package/esm/react/components/reset-password-form.js

@@ -0,0 +1,56 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * {@link ResetPasswordForm} — a default, accessible, unstyled "set a new
+ * password" form built on {@link useAuthForm}. Collects a new password and its
+ * confirmation, validates the match on the client, and forwards an opaque
+ * reset `token` (from the reset link) to your `onSubmit`.
+ *
+ * @module
+ */
+import { useEffect } from "react";
+import { useAuthForm } from "./use-auth-form.js";
+import { AuthFormShell, SubmitButton, TextField, useFocusFirstError, } from "./internal.js";
+import { useAuthFormClassNames } from "./class-names.js";
+/**
+ * A ready-to-use "set a new password" form. Pass the reset `token` from the
+ * link; it is forwarded to `onSubmit` alongside the password. A client-side
+ * check blocks submission on password mismatch.
+ *
+ * @example
+ * ```tsx
+ * <ResetPasswordForm
+ *   token={new URLSearchParams(location.search).get("token") ?? ""}
+ *   onSubmit={async (values) => {
+ *     const res = await fetch("/auth/reset-password", {
+ *       method: "POST",
+ *       headers: { "content-type": "application/json" },
+ *       body: JSON.stringify(values),
+ *     });
+ *     if (!res.ok) return await res.json();
+ *   }}
+ * />
+ * ```
+ */
+export function ResetPasswordForm(props) {
+    const { onSubmit, token = "", className, labels, children } = props;
+    const form = useAuthForm({
+        initialValues: { password: "", confirmPassword: "", token },
+        onSubmit,
+        onSuccess: props.onSuccess,
+        validate: (values) => {
+            const errors = {};
+            if (values.password !== values.confirmPassword) {
+                errors.confirmPassword = labels?.passwordMismatch ??
+                    "Passwords do not match.";
+            }
+            return errors;
+        },
+    });
+    const { setValue } = form;
+    useEffect(() => {
+        setValue("token", token);
+    }, [token, setValue]);
+    useFocusFirstError(form);
+    const classNames = useAuthFormClassNames(props.classNames);
+    return (_jsxs(AuthFormShell, { name: "reset-password", form: form, className: className, classNames: classNames, render: children, action: props.action, method: props.method, formRef: props.formRef, children: [_jsx(TextField, { fieldProps: form.getFieldProps("password"), label: labels?.password ?? "New password", type: "password", autoComplete: "new-password", required: true, error: form.errors.password }), _jsx(TextField, { fieldProps: form.getFieldProps("confirmPassword"), label: labels?.confirmPassword ?? "Confirm new password", type: "password", autoComplete: "new-password", required: true, error: form.errors.confirmPassword }), _jsx(SubmitButton, { isSubmitting: form.isSubmitting, label: labels?.submit ?? "Reset password", submittingLabel: labels?.submitting ?? "Resetting…" })] }));
+}

package/esm/react/components/sign-in-form.d.ts

@@ -0,0 +1,74 @@
+/**
+ * {@link SignInForm} — a default, accessible, unstyled sign-in form built on
+ * {@link useAuthForm}. Collects an identifier and password (optionally a
+ * "remember me" checkbox), renders "Continue with …" social buttons when
+ * providers are supplied, and reports the outcome through the injected
+ * `onSubmit`.
+ *
+ * @module
+ */
+import type { ReactNode } from "react";
+import type { AuthFormState } from "./use-auth-form.js";
+import type { BaseAuthFormProps, SocialProvidersProps } from "./types.js";
+/** Values collected by {@link SignInForm}. */
+export type SignInValues = {
+    /** Email address or username. */
+    identifier: string;
+    /** The user's password. */
+    password: string;
+    /** Whether to keep the session beyond the browser session. */
+    remember: boolean;
+};
+/** Visible text overrides for {@link SignInForm}. */
+export interface SignInLabels {
+    /** Label for the identifier field. Default: `"Email or username"`. */
+    identifier?: string;
+    /** Label for the password field. Default: `"Password"`. */
+    password?: string;
+    /** Label for the remember checkbox. Default: `"Remember me"`. */
+    remember?: string;
+    /** Submit button text. Default: `"Sign in"`. */
+    submit?: string;
+    /** Submit button text while submitting. Default: `"Signing in…"`. */
+    submitting?: string;
+    /** Text of the "forgot password" link. Default: `"Forgot password?"`. */
+    forgotPassword?: string;
+}
+/** Props for {@link SignInForm}. */
+export interface SignInFormProps extends BaseAuthFormProps<SignInValues>, SocialProvidersProps {
+    /** Render the "remember me" checkbox. Default: `false`. */
+    showRemember?: boolean;
+    /** Href for the "forgot password?" link. Omit to hide the link. */
+    forgotPasswordHref?: string;
+    /** Text overrides. */
+    labels?: SignInLabels;
+    /**
+     * Render-prop escape hatch. When provided, you own the markup and receive
+     * the live {@link AuthFormState}; the component still owns state and submit.
+     */
+    children?: (state: AuthFormState<SignInValues>) => ReactNode;
+}
+/**
+ * A ready-to-use sign-in form. Wire `onSubmit` to your auth endpoint; pass
+ * `socialProviders` to add federated buttons. Drop to {@link useAuthForm} (or
+ * pass a function as `children`) for full markup control.
+ *
+ * @example
+ * ```tsx
+ * <SignInForm
+ *   showRemember
+ *   forgotPasswordHref="/forgot-password"
+ *   socialProviders={[{ id: "github", name: "GitHub" }]}
+ *   socialHref={(p) => `/auth/login?connection=${p.id}`}
+ *   onSubmit={async (values) => {
+ *     const res = await fetch("/auth/sign-in", {
+ *       method: "POST",
+ *       headers: { "content-type": "application/json" },
+ *       body: JSON.stringify(values),
+ *     });
+ *     if (!res.ok) return await res.json();
+ *   }}
+ * />
+ * ```
+ */
+export declare function SignInForm(props: SignInFormProps): ReactNode;

package/esm/react/components/sign-in-form.js

@@ -0,0 +1,43 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useAuthForm } from "./use-auth-form.js";
+import { AuthFormShell, SocialButtons, SubmitButton, TextField, useFocusFirstError, } from "./internal.js";
+import { useAuthFormClassNames } from "./class-names.js";
+/**
+ * A ready-to-use sign-in form. Wire `onSubmit` to your auth endpoint; pass
+ * `socialProviders` to add federated buttons. Drop to {@link useAuthForm} (or
+ * pass a function as `children`) for full markup control.
+ *
+ * @example
+ * ```tsx
+ * <SignInForm
+ *   showRemember
+ *   forgotPasswordHref="/forgot-password"
+ *   socialProviders={[{ id: "github", name: "GitHub" }]}
+ *   socialHref={(p) => `/auth/login?connection=${p.id}`}
+ *   onSubmit={async (values) => {
+ *     const res = await fetch("/auth/sign-in", {
+ *       method: "POST",
+ *       headers: { "content-type": "application/json" },
+ *       body: JSON.stringify(values),
+ *     });
+ *     if (!res.ok) return await res.json();
+ *   }}
+ * />
+ * ```
+ */
+export function SignInForm(props) {
+    const { onSubmit, className, socialProviders, onSocialSelect, socialHref, showRemember = false, forgotPasswordHref, labels, children, } = props;
+    const form = useAuthForm({
+        initialValues: { identifier: "", password: "", remember: false },
+        onSubmit,
+        onSuccess: props.onSuccess,
+    });
+    useFocusFirstError(form);
+    const classNames = useAuthFormClassNames(props.classNames);
+    const rememberField = form.getFieldProps("remember");
+    return (_jsxs(AuthFormShell, { name: "sign-in", form: form, className: className, classNames: classNames, render: children, action: props.action, method: props.method, formRef: props.formRef, aboveForm: _jsx(SocialButtons, { socialProviders: socialProviders, onSocialSelect: onSocialSelect, socialHref: socialHref }), children: [_jsx(TextField, { fieldProps: form.getFieldProps("identifier"), label: labels?.identifier ?? "Email or username", autoComplete: "username", required: true, error: form.errors.identifier }), _jsx(TextField, { fieldProps: form.getFieldProps("password"), label: labels?.password ?? "Password", type: "password", autoComplete: "current-password", required: true, error: form.errors.password, children: forgotPasswordHref
+                    ? (_jsx("a", { href: forgotPasswordHref, "data-oauth2-forgot-password": "", className: classNames.hint, children: labels?.forgotPassword ?? "Forgot password?" }))
+                    : null }), showRemember
+                ? (_jsx("div", { "data-oauth2-field": "remember", className: classNames.field, children: _jsxs("label", { htmlFor: rememberField.id, "data-oauth2-label": "", className: classNames.label, children: [_jsx("input", { ...rememberField, type: "checkbox", "data-oauth2-input": "", className: classNames.input }), labels?.remember ?? "Remember me"] }) }))
+                : null, _jsx(SubmitButton, { isSubmitting: form.isSubmitting, label: labels?.submit ?? "Sign in", submittingLabel: labels?.submitting ?? "Signing in…" })] }));
+}

package/esm/react/components/sign-up-form.d.ts

@@ -0,0 +1,85 @@
+/**
+ * {@link SignUpForm} — a default, accessible, unstyled account-creation form
+ * built on {@link useAuthForm}. Collects email and password, optionally a
+ * confirm-password, username, and name, validates the password match on the
+ * client, and renders social buttons when providers are supplied.
+ *
+ * @module
+ */
+import type { ReactNode } from "react";
+import type { AuthFormState } from "./use-auth-form.js";
+import type { BaseAuthFormProps, SocialProvidersProps } from "./types.js";
+/** Values collected by {@link SignUpForm}. */
+export type SignUpValues = {
+    /** Email address. */
+    email: string;
+    /** The chosen password. */
+    password: string;
+    /** Confirmation of the password (present when `showConfirmPassword`). */
+    confirmPassword: string;
+    /** Username (present when `showUsername`). */
+    username: string;
+    /** Given name (present when `showName`). */
+    firstName: string;
+    /** Family name (present when `showName`). */
+    lastName: string;
+};
+/** Visible text overrides for {@link SignUpForm}. */
+export interface SignUpLabels {
+    /** Label for the email field. Default: `"Email"`. */
+    email?: string;
+    /** Label for the username field. Default: `"Username"`. */
+    username?: string;
+    /** Label for the first-name field. Default: `"First name"`. */
+    firstName?: string;
+    /** Label for the last-name field. Default: `"Last name"`. */
+    lastName?: string;
+    /** Label for the password field. Default: `"Password"`. */
+    password?: string;
+    /** Label for the confirm-password field. Default: `"Confirm password"`. */
+    confirmPassword?: string;
+    /** Submit button text. Default: `"Create account"`. */
+    submit?: string;
+    /** Submit button text while submitting. Default: `"Creating account…"`. */
+    submitting?: string;
+    /** Password-mismatch message. Default: `"Passwords do not match."`. */
+    passwordMismatch?: string;
+}
+/** Props for {@link SignUpForm}. */
+export interface SignUpFormProps extends BaseAuthFormProps<SignUpValues>, SocialProvidersProps {
+    /** Render the username field. Default: `false`. */
+    showUsername?: boolean;
+    /** Render the first/last name fields. Default: `false`. */
+    showName?: boolean;
+    /** Render the confirm-password field. Default: `true`. */
+    showConfirmPassword?: boolean;
+    /** Text overrides. */
+    labels?: SignUpLabels;
+    /**
+     * Render-prop escape hatch. When provided, you own the markup and receive
+     * the live {@link AuthFormState}.
+     */
+    children?: (state: AuthFormState<SignUpValues>) => ReactNode;
+}
+/**
+ * A ready-to-use account-creation form. Wire `onSubmit` to your sign-up
+ * endpoint. When the confirm-password field is shown, a client-side check
+ * blocks submission on mismatch before `onSubmit` runs.
+ *
+ * @example
+ * ```tsx
+ * <SignUpForm
+ *   showUsername
+ *   showName
+ *   onSubmit={async (values) => {
+ *     const res = await fetch("/auth/sign-up", {
+ *       method: "POST",
+ *       headers: { "content-type": "application/json" },
+ *       body: JSON.stringify(values),
+ *     });
+ *     if (!res.ok) return await res.json();
+ *   }}
+ * />
+ * ```
+ */
+export declare function SignUpForm(props: SignUpFormProps): ReactNode;

package/esm/react/components/sign-up-form.js

@@ -0,0 +1,57 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useAuthForm } from "./use-auth-form.js";
+import { AuthFormShell, SocialButtons, SubmitButton, TextField, useFocusFirstError, } from "./internal.js";
+import { useAuthFormClassNames } from "./class-names.js";
+/**
+ * A ready-to-use account-creation form. Wire `onSubmit` to your sign-up
+ * endpoint. When the confirm-password field is shown, a client-side check
+ * blocks submission on mismatch before `onSubmit` runs.
+ *
+ * @example
+ * ```tsx
+ * <SignUpForm
+ *   showUsername
+ *   showName
+ *   onSubmit={async (values) => {
+ *     const res = await fetch("/auth/sign-up", {
+ *       method: "POST",
+ *       headers: { "content-type": "application/json" },
+ *       body: JSON.stringify(values),
+ *     });
+ *     if (!res.ok) return await res.json();
+ *   }}
+ * />
+ * ```
+ */
+export function SignUpForm(props) {
+    const { onSubmit, className, socialProviders, onSocialSelect, socialHref, showUsername = false, showName = false, showConfirmPassword = true, labels, children, } = props;
+    const form = useAuthForm({
+        initialValues: {
+            email: "",
+            password: "",
+            confirmPassword: "",
+            username: "",
+            firstName: "",
+            lastName: "",
+        },
+        onSubmit,
+        onSuccess: props.onSuccess,
+        validate: (values) => {
+            const errors = {};
+            if (showConfirmPassword && values.password !== values.confirmPassword) {
+                errors.confirmPassword = labels?.passwordMismatch ??
+                    "Passwords do not match.";
+            }
+            return errors;
+        },
+    });
+    useFocusFirstError(form);
+    const classNames = useAuthFormClassNames(props.classNames);
+    return (_jsxs(AuthFormShell, { name: "sign-up", form: form, className: className, classNames: classNames, render: children, action: props.action, method: props.method, formRef: props.formRef, aboveForm: _jsx(SocialButtons, { socialProviders: socialProviders, onSocialSelect: onSocialSelect, socialHref: socialHref }), children: [showUsername
+                ? (_jsx(TextField, { fieldProps: form.getFieldProps("username"), label: labels?.username ?? "Username", autoComplete: "username", required: true, error: form.errors.username }))
+                : null, _jsx(TextField, { fieldProps: form.getFieldProps("email"), label: labels?.email ?? "Email", type: "email", autoComplete: "email", required: true, error: form.errors.email }), showName
+                ? (_jsxs(_Fragment, { children: [_jsx(TextField, { fieldProps: form.getFieldProps("firstName"), label: labels?.firstName ?? "First name", autoComplete: "given-name", required: true, error: form.errors.firstName }), _jsx(TextField, { fieldProps: form.getFieldProps("lastName"), label: labels?.lastName ?? "Last name", autoComplete: "family-name", required: true, error: form.errors.lastName })] }))
+                : null, _jsx(TextField, { fieldProps: form.getFieldProps("password"), label: labels?.password ?? "Password", type: "password", autoComplete: "new-password", required: true, error: form.errors.password }), showConfirmPassword
+                ? (_jsx(TextField, { fieldProps: form.getFieldProps("confirmPassword"), label: labels?.confirmPassword ?? "Confirm password", type: "password", autoComplete: "new-password", required: true, error: form.errors.confirmPassword }))
+                : null, _jsx(SubmitButton, { isSubmitting: form.isSubmitting, label: labels?.submit ?? "Create account", submittingLabel: labels?.submitting ?? "Creating account…" })] }));
+}

package/esm/react/components/types.d.ts

@@ -0,0 +1,208 @@
+/**
+ * Shared types for the prebuilt auth components
+ * (`@udibo/oauth2/react/components`).
+ *
+ * These types describe the wiring contract every component shares: how a
+ * submit handler reports success and errors ({@link AuthFormResult}), the
+ * per-slot class hooks used for theming ({@link BaseClassNames} and
+ * {@link AuthFormClassNames}), and the social-provider descriptor
+ * ({@link SocialProvider}). The headless hook state ({@link AuthFormState}) is
+ * defined alongside the hook in `use-auth-form.ts`.
+ *
+ * @module
+ */
+import type { ReactNode, Ref } from "react";
+/**
+ * A record of field values a form collects. Keys are field names; values are
+ * strings for text inputs and booleans for checkboxes.
+ */
+export type AuthFormValues = Record<string, string | boolean>;
+/**
+ * Per-field error messages keyed by field name. Only fields with an error
+ * appear; a missing key means the field is valid.
+ */
+export type AuthFormErrors<V extends AuthFormValues> = Partial<Record<keyof V & string, string>>;
+/**
+ * The result an {@link AuthSubmitHandler} may return to drive the form's UI.
+ *
+ * Return nothing (or an empty object) to signal success. Populate `error`
+ * and/or `fieldErrors` to surface validation problems inline without throwing.
+ * A thrown error is also treated as a form-level failure, using its message.
+ */
+export interface AuthFormResult {
+    /** A form-level error message shown in the error summary region. */
+    error?: string;
+    /** Per-field error messages keyed by field name. */
+    fieldErrors?: Record<string, string>;
+}
+/**
+ * The app-provided function that performs a form's action — a client-side
+ * `fetch` in a plain React Router app, or a call that submits a router action
+ * in Juniper. Receives the collected values; resolve/return an
+ * {@link AuthFormResult} (or throw) to report the outcome.
+ */
+export type AuthSubmitHandler<V extends AuthFormValues> = (values: V) => Promise<AuthFormResult | void> | AuthFormResult | void;
+/**
+ * A social / federated identity provider to render a "Continue with …" button
+ * for. Supply an array of these to a sign-in or sign-up component and the
+ * buttons appear automatically; omit or pass an empty array for no social
+ * section.
+ */
+export interface SocialProvider {
+    /** Stable identifier passed back to your handler / href builder. */
+    id: string;
+    /** Human-readable name rendered in the button ("Continue with {name}"). */
+    name: string;
+    /** Optional icon node rendered before the label. */
+    iconSlot?: ReactNode;
+}
+/**
+ * Props mixed into the sign-in / sign-up components for the social section.
+ * Provide `socialHref` to render anchors (full-page redirects), or
+ * `onSocialSelect` to render buttons that call back. `socialHref` wins when
+ * both are given.
+ */
+export interface SocialProvidersProps {
+    /** Providers to render buttons for. Empty/absent → no social section. */
+    socialProviders?: SocialProvider[];
+    /** Called with the chosen provider when a social button is clicked. */
+    onSocialSelect?: (provider: SocialProvider) => void;
+    /** Builds the href for a provider; renders anchors instead of buttons. */
+    socialHref?: (provider: SocialProvider) => string;
+}
+/**
+ * The class hook every prebuilt component shares. Component-specific class-name
+ * maps ({@link AuthFormClassNames}, `UserMenuClassNames`) extend this, so `root`
+ * means the same thing everywhere.
+ */
+export interface BaseClassNames {
+    /**
+     * The component's outermost element — the one carrying its
+     * `data-oauth2-form` / `data-oauth2-user-menu` marker. Merged with the
+     * component's top-level `className` prop.
+     */
+    root?: string;
+}
+/**
+ * Per-slot class hooks for theming the default form components — the complete
+ * slot set they share, so one map themes any of them and a form simply ignores
+ * the slots its markup has no element for. Every slot is optional; unset slots
+ * render with no class. Each rendered element also carries a stable
+ * `data-oauth2-*` attribute for CSS-only theming.
+ *
+ * Pass it as a component's `classNames` prop, or to
+ * `AuthFormClassNamesProvider` to theme every form in a subtree at once.
+ */
+export interface AuthFormClassNames extends BaseClassNames {
+    /** The `<form>` element (`data-oauth2-form-element`). */
+    form?: string;
+    /** The form-level error summary region (`data-oauth2-error-summary`). */
+    errorSummary?: string;
+    /** Each field wrapper (`data-oauth2-field`). */
+    field?: string;
+    /** Each `<label>` (`data-oauth2-label`). */
+    label?: string;
+    /** Each `<input>` (`data-oauth2-input`). */
+    input?: string;
+    /** Each inline field error (`data-oauth2-error`). */
+    error?: string;
+    /**
+     * Inline content rendered under a field — today the sign-in form's "Forgot
+     * password?" link (`data-oauth2-forgot-password`).
+     */
+    hint?: string;
+    /** The actions row wrapping the submit button (`data-oauth2-actions`). */
+    actions?: string;
+    /** The submit `<button>` (`data-oauth2-submit`). */
+    submit?: string;
+    /**
+     * A secondary action below the submit button (`data-oauth2-secondary`) — the
+     * MFA challenge's recovery-code toggle is the one form that renders it, and it
+     * also carries `data-oauth2-toggle-recovery`.
+     */
+    secondary?: string;
+    /** The social section wrapper (`data-oauth2-social`). */
+    socialSection?: string;
+    /**
+     * The divider between the social section and the form
+     * (`data-oauth2-social-divider`). Rendered only when social providers are
+     * present.
+     */
+    socialDivider?: string;
+    /** Each social button/anchor (`data-oauth2-social-button`). */
+    socialButton?: string;
+    /**
+     * The terminal success panel that replaces the form (`data-oauth2-success`) —
+     * rendered by the forms that have a success state, such as
+     * `RequestPasswordResetForm`.
+     */
+    success?: string;
+    /** The secret display block (`data-oauth2-secret`), an `MfaEnrollmentForm` slot. */
+    secret?: string;
+    /** The QR slot wrapper (`data-oauth2-qr`), an `MfaEnrollmentForm` slot. */
+    qr?: string;
+    /**
+     * The recovery-codes list (`data-oauth2-recovery-codes`), an
+     * `MfaEnrollmentForm` slot.
+     */
+    recoveryCodes?: string;
+    /**
+     * Each recovery code item (`data-oauth2-recovery-code`), an
+     * `MfaEnrollmentForm` slot.
+     */
+    recoveryCode?: string;
+}
+/**
+ * Base props shared by the default form components: the injected submit
+ * handler, theming hooks, and an optional render-prop escape hatch.
+ *
+ * Passing a function as `children` "ejects" to headless mode: you receive the
+ * live {@link AuthFormState} and render your own markup, while the component
+ * keeps owning state and the submit lifecycle. For full control over state as
+ * well, call {@link useAuthForm} directly instead.
+ */
+export interface BaseAuthFormProps<V extends AuthFormValues> {
+    /** The action that performs the submit. See {@link AuthSubmitHandler}. */
+    onSubmit: AuthSubmitHandler<V>;
+    /**
+     * Called after a successful submit, with the values that were submitted —
+     * the seam for navigating, redirecting, or revealing your own "done" panel
+     * without ejecting to {@link useAuthForm}. A promise it returns is awaited,
+     * but a throw or rejection is caught and logged rather than surfaced: the
+     * form still reports success.
+     */
+    onSuccess?: (values: V) => void;
+    /** Class for the root wrapper (merged with `classNames.root`). */
+    className?: string;
+    /**
+     * Per-slot class hooks for theming. Overrides an inherited
+     * `AuthFormClassNamesProvider` map slot by slot. See
+     * {@link AuthFormClassNames}.
+     */
+    classNames?: AuthFormClassNames;
+    /**
+     * `action` for the rendered `<form>`. Set it (with {@link method}) on a
+     * server-rendered page so the form still posts when JavaScript never
+     * arrives; every field carries its `name`, so a native post sends the same
+     * keys `onSubmit` receives. Once React is running, `onSubmit` handles the
+     * submit and the native post is suppressed.
+     *
+     * Ignored in render-prop mode — you own the `<form>` there.
+     */
+    action?: string;
+    /**
+     * `method` for the rendered `<form>`. Defaults to `"post"` whenever
+     * {@link action} is set, because the fields these forms render — passwords,
+     * one-time codes, reset tokens — must never reach a URL, where a `get` form
+     * would put them: browser history, the `Referer` sent to every third-party
+     * asset on the destination page, and the server's access log.
+     */
+    method?: "get" | "post";
+    /**
+     * Ref to the rendered `<form>` element — for example to call its native
+     * `submit()`, which bypasses `onSubmit` and posts to {@link action}.
+     *
+     * Ignored in render-prop mode.
+     */
+    formRef?: Ref<HTMLFormElement>;
+}

package/esm/react/components/types.js

@@ -0,0 +1,14 @@
+/**
+ * Shared types for the prebuilt auth components
+ * (`@udibo/oauth2/react/components`).
+ *
+ * These types describe the wiring contract every component shares: how a
+ * submit handler reports success and errors ({@link AuthFormResult}), the
+ * per-slot class hooks used for theming ({@link BaseClassNames} and
+ * {@link AuthFormClassNames}), and the social-provider descriptor
+ * ({@link SocialProvider}). The headless hook state ({@link AuthFormState}) is
+ * defined alongside the hook in `use-auth-form.ts`.
+ *
+ * @module
+ */
+export {};