@udibo/oauth2 0.1.0

package/esm/react/components/use-auth-form.d.ts

@@ -0,0 +1,118 @@
+/**
+ * {@link useAuthForm} — the headless hook backing every default auth form
+ * component in `@udibo/oauth2/react/components`.
+ *
+ * It owns field values, per-field and form-level errors, and the submit
+ * lifecycle, and stays entirely presentation-free: no markup, no styling, no
+ * router or network assumptions. The action is injected as `onSubmit`, so the
+ * same hook drives a client-side `fetch` in a plain React Router app or a
+ * router-action submit in Juniper. Reach for it directly when you want to own
+ * the markup completely (the "eject to headless" path); otherwise use a
+ * default component, which is built on this hook.
+ *
+ * @module
+ */
+import { type ChangeEvent } from "react";
+import type { AuthFormErrors, AuthFormValues, AuthSubmitHandler } from "./types.js";
+/** Lifecycle status of an {@link useAuthForm} instance. */
+export type AuthFormStatus = "idle" | "submitting" | "success" | "error";
+/**
+ * Props spread onto a field's `<input>` to wire value, change handling, and
+ * accessibility. Produced by {@link AuthFormState.getFieldProps}.
+ */
+export interface AuthFieldProps {
+    /** The input's `id`, also referenced by its label's `htmlFor`. */
+    id: string;
+    /** The field name (form key). */
+    name: string;
+    /** Current string value (checkboxes read `checked` instead — see below). */
+    value: string;
+    /** Whether a checkbox field is checked (omitted for text fields). */
+    checked?: boolean;
+    /** Change handler that reads `value`/`checked` and updates form state. */
+    onChange: (event: ChangeEvent<HTMLInputElement>) => void;
+    /** `true` when the field currently has an error, else `undefined`. */
+    "aria-invalid"?: true;
+    /** The id of this field's error element when errored, else `undefined`. */
+    "aria-describedby"?: string;
+}
+/** Options for {@link useAuthForm}. */
+export interface UseAuthFormOptions<V extends AuthFormValues> {
+    /** Starting values; also defines the set of fields. */
+    initialValues: V;
+    /** The injected action that performs the submit. */
+    onSubmit: AuthSubmitHandler<V>;
+    /**
+     * Optional synchronous client-side validation run before `onSubmit`. Return
+     * a map of field errors to block submission, or `null`/`undefined` to allow.
+     * A throw is trapped like an `onSubmit` throw — surfaced as a form-level
+     * error (`status: "error"`) rather than an unhandled rejection.
+     */
+    validate?: (values: V) => AuthFormErrors<V> | null | undefined;
+    /**
+     * Called after a successful submit (no `error`/`fieldErrors` returned). A
+     * promise it returns is awaited, but a throw or rejection is caught and
+     * logged to `console.error` rather than surfaced: `status` stays `"success"`
+     * and no form error appears.
+     */
+    onSuccess?: (values: V) => void;
+}
+/**
+ * The live state and actions returned by {@link useAuthForm}. This is also the
+ * value passed to a form component's render-prop `children`.
+ */
+export interface AuthFormState<V extends AuthFormValues> {
+    /** Current field values. */
+    values: V;
+    /** Current per-field errors. */
+    errors: AuthFormErrors<V>;
+    /** Current form-level error, or `null`. */
+    formError: string | null;
+    /** Lifecycle status. */
+    status: AuthFormStatus;
+    /** `true` while a submit is in flight (`status === "submitting"`). */
+    isSubmitting: boolean;
+    /** `true` once a submit has completed successfully. */
+    succeeded: boolean;
+    /** Increments on every submit attempt; useful as a focus-effect trigger. */
+    submitCount: number;
+    /** Set a single field's value. */
+    setValue<K extends keyof V & string>(name: K, value: V[K]): void;
+    /** Merge a partial set of field values. */
+    setValues(next: Partial<V>): void;
+    /** Reset values to `initialValues` and clear all errors/status. */
+    reset(): void;
+    /** Submit handler for a `<form onSubmit>` (calls `preventDefault`). */
+    handleSubmit(event?: {
+        preventDefault(): void;
+    }): Promise<void>;
+    /** Build the props to spread onto a field's `<input>`. */
+    getFieldProps<K extends keyof V & string>(name: K): AuthFieldProps;
+}
+/**
+ * Headless form engine: owns values, errors, and the submit lifecycle for an
+ * auth form, delegating the actual action to the injected `onSubmit`.
+ *
+ * @example Eject to fully custom markup
+ * ```tsx
+ * const form = useAuthForm({
+ *   initialValues: { identifier: "", password: "" },
+ *   onSubmit: async (values) => {
+ *     const res = await fetch("/auth/sign-in", {
+ *       method: "POST",
+ *       body: JSON.stringify(values),
+ *     });
+ *     if (!res.ok) return { error: "Invalid credentials" };
+ *   },
+ * });
+ * return (
+ *   <form onSubmit={form.handleSubmit}>
+ *     <input {...form.getFieldProps("identifier")} />
+ *     <input {...form.getFieldProps("password")} type="password" />
+ *     {form.formError ? <p role="alert">{form.formError}</p> : null}
+ *     <button type="submit" disabled={form.isSubmitting}>Sign in</button>
+ *   </form>
+ * );
+ * ```
+ */
+export declare function useAuthForm<V extends AuthFormValues>(options: UseAuthFormOptions<V>): AuthFormState<V>;

package/esm/react/components/use-auth-form.js

@@ -0,0 +1,172 @@
+/**
+ * {@link useAuthForm} — the headless hook backing every default auth form
+ * component in `@udibo/oauth2/react/components`.
+ *
+ * It owns field values, per-field and form-level errors, and the submit
+ * lifecycle, and stays entirely presentation-free: no markup, no styling, no
+ * router or network assumptions. The action is injected as `onSubmit`, so the
+ * same hook drives a client-side `fetch` in a plain React Router app or a
+ * router-action submit in Juniper. Reach for it directly when you want to own
+ * the markup completely (the "eject to headless" path); otherwise use a
+ * default component, which is built on this hook.
+ *
+ * @module
+ */
+import { useCallback, useId, useMemo, useRef, useState, } from "react";
+/**
+ * Headless form engine: owns values, errors, and the submit lifecycle for an
+ * auth form, delegating the actual action to the injected `onSubmit`.
+ *
+ * @example Eject to fully custom markup
+ * ```tsx
+ * const form = useAuthForm({
+ *   initialValues: { identifier: "", password: "" },
+ *   onSubmit: async (values) => {
+ *     const res = await fetch("/auth/sign-in", {
+ *       method: "POST",
+ *       body: JSON.stringify(values),
+ *     });
+ *     if (!res.ok) return { error: "Invalid credentials" };
+ *   },
+ * });
+ * return (
+ *   <form onSubmit={form.handleSubmit}>
+ *     <input {...form.getFieldProps("identifier")} />
+ *     <input {...form.getFieldProps("password")} type="password" />
+ *     {form.formError ? <p role="alert">{form.formError}</p> : null}
+ *     <button type="submit" disabled={form.isSubmitting}>Sign in</button>
+ *   </form>
+ * );
+ * ```
+ */
+export function useAuthForm(options) {
+    const { initialValues, onSubmit, validate, onSuccess } = options;
+    const idBase = useId();
+    const [values, setValuesState] = useState(initialValues);
+    const [errors, setErrors] = useState({});
+    const [formError, setFormError] = useState(null);
+    const [status, setStatus] = useState("idle");
+    const [submitCount, setSubmitCount] = useState(0);
+    // Synchronous re-entrancy lock: `status` is a render-closure value, so it
+    // can't block a same-tick double submit (Enter racing autofill, etc.).
+    const submittingRef = useRef(false);
+    const setValue = useCallback((name, value) => {
+        setValuesState((prev) => ({ ...prev, [name]: value }));
+    }, []);
+    const setValues = useCallback((next) => {
+        setValuesState((prev) => ({ ...prev, ...next }));
+    }, []);
+    const reset = useCallback(() => {
+        setValuesState(initialValues);
+        setErrors({});
+        setFormError(null);
+        setStatus("idle");
+    }, [initialValues]);
+    const handleSubmit = useCallback(async (event) => {
+        event?.preventDefault();
+        if (submittingRef.current)
+            return;
+        submittingRef.current = true;
+        try {
+            setSubmitCount((count) => count + 1);
+            setFormError(null);
+            setErrors({});
+            if (validate) {
+                let validationErrors;
+                try {
+                    validationErrors = validate(values);
+                }
+                catch (error) {
+                    setFormError(error instanceof Error ? error.message : "Something went wrong.");
+                    setStatus("error");
+                    return;
+                }
+                if (validationErrors && Object.keys(validationErrors).length > 0) {
+                    setErrors(validationErrors);
+                    setStatus("error");
+                    return;
+                }
+            }
+            setStatus("submitting");
+            let result;
+            try {
+                result = await onSubmit(values);
+            }
+            catch (error) {
+                setFormError(error instanceof Error ? error.message : "Something went wrong.");
+                setStatus("error");
+                return;
+            }
+            const fieldErrors = result?.fieldErrors;
+            const hasFieldErrors = fieldErrors &&
+                Object.keys(fieldErrors).length > 0;
+            if (result?.error || hasFieldErrors) {
+                if (result?.error)
+                    setFormError(result.error);
+                if (hasFieldErrors)
+                    setErrors(fieldErrors);
+                setStatus("error");
+                return;
+            }
+            setStatus("success");
+            // An integrator's onSuccess side effect must not become an unhandled
+            // rejection (form onSubmit doesn't await handleSubmit).
+            try {
+                await onSuccess?.(values);
+            }
+            catch (error) {
+                console.error("[@udibo/oauth2] auth form onSuccess failed:", error);
+            }
+        }
+        finally {
+            submittingRef.current = false;
+        }
+    }, [values, validate, onSubmit, onSuccess]);
+    const getFieldProps = useCallback((name) => {
+        const raw = values[name];
+        const hasError = Boolean(errors[name]);
+        const id = `${idBase}-${name}`;
+        const base = {
+            id,
+            name,
+            value: typeof raw === "boolean" ? "" : String(raw ?? ""),
+            onChange: (event) => {
+                const target = event.target;
+                const next = target.type === "checkbox"
+                    ? target.checked
+                    : target.value;
+                setValue(name, next);
+            },
+            "aria-invalid": hasError ? true : undefined,
+            "aria-describedby": hasError ? `${id}-error` : undefined,
+        };
+        if (typeof raw === "boolean")
+            base.checked = raw;
+        return base;
+    }, [values, errors, idBase, setValue]);
+    return useMemo(() => ({
+        values,
+        errors,
+        formError,
+        status,
+        isSubmitting: status === "submitting",
+        succeeded: status === "success",
+        submitCount,
+        setValue,
+        setValues,
+        reset,
+        handleSubmit,
+        getFieldProps,
+    }), [
+        values,
+        errors,
+        formError,
+        status,
+        submitCount,
+        setValue,
+        setValues,
+        reset,
+        handleSubmit,
+        getFieldProps,
+    ]);
+}

package/esm/react/components/user-menu.d.ts

@@ -0,0 +1,79 @@
+/**
+ * {@link UserMenu} — a default, accessible, unstyled signed-in user menu. Reads
+ * the current user and `logout` from {@link useOAuth2}, renders a disclosure
+ * button showing the user's name, and exposes a logout action plus a slot for
+ * your own menu items.
+ *
+ * Renders `null` (or a `signedOut` slot) when no user is authenticated, so it
+ * is safe to mount unconditionally in a nav bar.
+ *
+ * The claims type its `renderUser` / `children` callbacks receive is
+ * `UserInfoClaims`, imported from `@udibo/oauth2/client` — it belongs to the
+ * client, not to this component.
+ *
+ * @module
+ */
+import { type ReactNode } from "react";
+import type { UserInfoClaims } from "../../client/mod.js";
+import type { BaseClassNames } from "./types.js";
+/**
+ * Per-slot class hooks for {@link UserMenu}: the shared {@link BaseClassNames}
+ * `root` plus the menu's own slots.
+ */
+export interface UserMenuClassNames extends BaseClassNames {
+    /** The disclosure trigger button (`data-oauth2-user-trigger`). */
+    trigger?: string;
+    /** The display-name element inside the trigger. */
+    name?: string;
+    /** The menu panel revealed on open (`data-oauth2-user-panel`). */
+    menu?: string;
+    /** Each menu item wrapper. */
+    menuItem?: string;
+    /** The logout button (`data-oauth2-logout`). */
+    logout?: string;
+}
+/** Visible text overrides for {@link UserMenu}. */
+export interface UserMenuLabels {
+    /** Logout action text. Default: `"Sign out"`. */
+    logout?: string;
+}
+/** Props for {@link UserMenu}. */
+export interface UserMenuProps {
+    /** Extra menu content rendered above the logout action (links, etc.). */
+    items?: ReactNode;
+    /**
+     * Override the logout behaviour. Defaults to `useOAuth2().logout()`, which
+     * ends the session and (in the browser) navigates to the logout URL.
+     */
+    onLogout?: () => void | Promise<void>;
+    /** Custom renderer for the trigger's user display. */
+    renderUser?: (user: UserInfoClaims) => ReactNode;
+    /** Rendered when no user is authenticated. Default: `null`. */
+    signedOut?: ReactNode;
+    /** Class for the root wrapper (merged with `classNames.root`). */
+    className?: string;
+    /** Per-slot class hooks for theming. */
+    classNames?: UserMenuClassNames;
+    /** Text overrides. */
+    labels?: UserMenuLabels;
+    /**
+     * Render-prop escape hatch. Receives the current user and a `logout`
+     * callback so you can render an entirely custom menu.
+     */
+    children?: (state: {
+        user: UserInfoClaims;
+        logout: () => void | Promise<void>;
+    }) => ReactNode;
+}
+/**
+ * A ready-to-use signed-in user menu. Mount it in your nav; it reads auth
+ * state from the surrounding `<OAuth2Provider>`.
+ *
+ * @example
+ * ```tsx
+ * <UserMenu
+ *   items={<a href="/profile">Profile</a>}
+ * />
+ * ```
+ */
+export declare function UserMenu(props: UserMenuProps): ReactNode;

package/esm/react/components/user-menu.js

@@ -0,0 +1,73 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * {@link UserMenu} — a default, accessible, unstyled signed-in user menu. Reads
+ * the current user and `logout` from {@link useOAuth2}, renders a disclosure
+ * button showing the user's name, and exposes a logout action plus a slot for
+ * your own menu items.
+ *
+ * Renders `null` (or a `signedOut` slot) when no user is authenticated, so it
+ * is safe to mount unconditionally in a nav bar.
+ *
+ * The claims type its `renderUser` / `children` callbacks receive is
+ * `UserInfoClaims`, imported from `@udibo/oauth2/client` — it belongs to the
+ * client, not to this component.
+ *
+ * @module
+ */
+import { useEffect, useId, useRef, useState } from "react";
+import { useOAuth2 } from "../use-oauth2.js";
+import { combineClassNames, displayName } from "./internal.js";
+/**
+ * A ready-to-use signed-in user menu. Mount it in your nav; it reads auth
+ * state from the surrounding `<OAuth2Provider>`.
+ *
+ * @example
+ * ```tsx
+ * <UserMenu
+ *   items={<a href="/profile">Profile</a>}
+ * />
+ * ```
+ */
+export function UserMenu(props) {
+    const { items, onLogout, renderUser, signedOut = null, className, classNames, labels, children, } = props;
+    const { user, logout } = useOAuth2();
+    const [open, setOpen] = useState(false);
+    const panelId = useId();
+    const rootRef = useRef(null);
+    useEffect(() => {
+        if (!open)
+            return;
+        const onKeyDown = (event) => {
+            if (event.key === "Escape")
+                setOpen(false);
+        };
+        const onPointerDown = (event) => {
+            if (!rootRef.current?.contains(event.target))
+                setOpen(false);
+        };
+        document.addEventListener("keydown", onKeyDown);
+        document.addEventListener("pointerdown", onPointerDown);
+        return () => {
+            document.removeEventListener("keydown", onKeyDown);
+            document.removeEventListener("pointerdown", onPointerDown);
+        };
+    }, [open]);
+    if (!user)
+        return _jsx(_Fragment, { children: signedOut });
+    const runLogout = onLogout ?? (async () => {
+        await logout();
+    });
+    if (children)
+        return _jsx(_Fragment, { children: children({ user, logout: runLogout }) });
+    return (_jsxs("div", { ref: rootRef, "data-oauth2-user-menu": "", className: combineClassNames(className, classNames?.root), children: [_jsx("button", { type: "button", "aria-expanded": open, "aria-controls": panelId, onClick: () => setOpen((value) => !value), "data-oauth2-user-trigger": "", className: classNames?.trigger, children: renderUser
+                    ? renderUser(user)
+                    : (_jsx("span", { "data-oauth2-user-name": "", className: classNames?.name, children: displayName(user) })) }), open
+                ? (_jsxs("div", { id: panelId, "data-oauth2-user-panel": "", className: classNames?.menu, children: [items
+                            ? (_jsx("div", { "data-oauth2-user-items": "", className: classNames?.menuItem, children: items }))
+                            : null, _jsx("button", { type: "button", onClick: () => {
+                                void Promise.resolve(runLogout()).catch((error) => {
+                                    console.error("[@udibo/oauth2] logout failed:", error);
+                                });
+                            }, "data-oauth2-logout": "", className: classNames?.logout, children: labels?.logout ?? "Sign out" })] }))
+                : null] }));
+}

package/esm/react/context.d.ts

@@ -0,0 +1,51 @@
+/**
+ * React context wiring for the OAuth2 client.
+ *
+ * Internal — consumers should reach for {@link useOAuth2} (the hook),
+ * {@link OAuth2Provider}, {@link RequireAuth}, and {@link OAuth2Callback}
+ * rather than the context object directly.
+ *
+ * @module
+ */
+import { type Context } from "react";
+import type { OAuth2ClientBase, OAuth2Error, UserInfoClaims } from "../client/mod.js";
+/** Shape exposed by `useOAuth2()`. */
+export interface OAuth2State {
+    /** Whether a user is currently authenticated. */
+    isAuthenticated: boolean;
+    /**
+     * `true` during the initial session probe and during a token refresh
+     * with no currently valid access token. Settles to `false` once
+     * authentication state is known.
+     */
+    isLoading: boolean;
+    /**
+     * Current user claims, or `null` when unauthenticated. From
+     * `GET /auth/session` behind a `BffClient`; the decoded `id_token` claims
+     * (or the `userinfo_endpoint` body) behind a `DirectClient`.
+     */
+    user: UserInfoClaims | null;
+    /** Last error surfaced by the client, or `null`. */
+    error: OAuth2Error | null;
+    /**
+     * Seconds until the session's access token expires, or `null` when unknown.
+     * The provider calls `client.renewSession()` shortly before this elapses.
+     */
+    sessionExpiresIn: number | null;
+    /**
+     * A URL that ends the session, or `null` when the client has none to offer.
+     * Lets a UI render a sign-out link without hardcoding the path.
+     */
+    logoutUrl: string | null;
+}
+/** Internal context value shared by the provider and consumers. */
+export interface OAuth2ContextValue extends OAuth2State {
+    /** The underlying client — a `BffClient` or a `DirectClient`. */
+    client: OAuth2ClientBase;
+}
+/**
+ * Internal context — providers wire up the value, consumers read it
+ * through `useOAuth2()`. Default `null` so `useOAuth2()` can throw a
+ * clear error when called outside any provider.
+ */
+export declare const OAuth2Context: Context<OAuth2ContextValue | null>;

package/esm/react/context.js

@@ -0,0 +1,16 @@
+/**
+ * React context wiring for the OAuth2 client.
+ *
+ * Internal — consumers should reach for {@link useOAuth2} (the hook),
+ * {@link OAuth2Provider}, {@link RequireAuth}, and {@link OAuth2Callback}
+ * rather than the context object directly.
+ *
+ * @module
+ */
+import { createContext } from "react";
+/**
+ * Internal context — providers wire up the value, consumers read it
+ * through `useOAuth2()`. Default `null` so `useOAuth2()` can throw a
+ * clear error when called outside any provider.
+ */
+export const OAuth2Context = createContext(null);

package/esm/react/mod.d.ts

@@ -0,0 +1,26 @@
+/**
+ * React adapter for `@udibo/oauth2/client`.
+ *
+ * Wraps a `BffClient` or a `DirectClient` in a React context and ships
+ * components / hooks for the common SPA patterns:
+ *
+ * - {@link OAuth2Provider} — install once near the app root.
+ * - {@link useOAuth2} — read state and bound auth helpers.
+ * - {@link RequireAuth} — gate a subtree behind authentication.
+ * - {@link OAuth2Callback} — callback route for a `DirectClient` app.
+ *
+ * The adapter is framework- and server-neutral: it works against any
+ * RFC 6749-compliant authorization server, and everything above is written
+ * against the clients' shared base, so the same components and hooks work
+ * whichever one the app is wired with. Reach for {@link useBffClient} or
+ * {@link useDirectClient} when a component needs one transport's specifics.
+ *
+ * @module
+ */
+import "../_dnt.polyfills.js";
+export { OAuth2Context, type OAuth2ContextValue, type OAuth2State, } from "./context.js";
+export { OAuth2Provider, type OAuth2ProviderProps } from "./provider.js";
+export { useBffClient, useDirectClient, useOAuth2, type UseOAuth2Result, } from "./use-oauth2.js";
+export { useAuthorization } from "./use-authorization.js";
+export { RequireAuth, type RequireAuthProps } from "./require-auth.js";
+export { OAuth2Callback, type OAuth2CallbackProps } from "./callback.js";

package/esm/react/mod.js

@@ -0,0 +1,26 @@
+/**
+ * React adapter for `@udibo/oauth2/client`.
+ *
+ * Wraps a `BffClient` or a `DirectClient` in a React context and ships
+ * components / hooks for the common SPA patterns:
+ *
+ * - {@link OAuth2Provider} — install once near the app root.
+ * - {@link useOAuth2} — read state and bound auth helpers.
+ * - {@link RequireAuth} — gate a subtree behind authentication.
+ * - {@link OAuth2Callback} — callback route for a `DirectClient` app.
+ *
+ * The adapter is framework- and server-neutral: it works against any
+ * RFC 6749-compliant authorization server, and everything above is written
+ * against the clients' shared base, so the same components and hooks work
+ * whichever one the app is wired with. Reach for {@link useBffClient} or
+ * {@link useDirectClient} when a component needs one transport's specifics.
+ *
+ * @module
+ */
+import "../_dnt.polyfills.js";
+export { OAuth2Context, } from "./context.js";
+export { OAuth2Provider } from "./provider.js";
+export { useBffClient, useDirectClient, useOAuth2, } from "./use-oauth2.js";
+export { useAuthorization } from "./use-authorization.js";
+export { RequireAuth } from "./require-auth.js";
+export { OAuth2Callback } from "./callback.js";

package/esm/react/provider.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `<OAuth2Provider>` — wraps the app, wires an {@link OAuth2ClientBase} into
+ * a React context, and re-renders subscribers when the client emits
+ * authentication state changes.
+ *
+ * @module
+ */
+import { type ReactNode } from "react";
+import type { OAuth2ClientBase } from "../client/mod.js";
+import { type OAuth2State } from "./context.js";
+/** Props for {@link OAuth2Provider}. */
+export interface OAuth2ProviderProps {
+    /**
+     * The OAuth2 client driving the flows — a `BffClient` or a `DirectClient`.
+     * Construct once per app.
+     */
+    client: OAuth2ClientBase;
+    /**
+     * Optional pre-resolved auth state (typically from a server-side
+     * session probe). Populating this skips the on-mount session probe
+     * and renders the authenticated tree on the first paint — no
+     * hydration flash. Pass a stable reference (don't construct it inline
+     * in render) so the on-mount effect doesn't re-run.
+     */
+    initialState?: Partial<OAuth2State>;
+    /** The app subtree that reads auth state via `useOAuth2()`. */
+    children: ReactNode;
+}
+/**
+ * Provider — install once near the root of your app. Children read the
+ * state via `useOAuth2()`.
+ *
+ * While authenticated it renews the session on a timer shortly before the
+ * access token expires, re-arming after each renew. Renewal is per tab and
+ * uncoordinated: a `DirectClient` given a refresh-token storage shared across
+ * tabs (e.g. `IndexedDBRefreshTokenStorage`) against a server that
+ * rotates refresh tokens can still have two tabs redeem the same token, which
+ * reuse detection may answer by ending the session everywhere.
+ */
+export declare function OAuth2Provider(props: OAuth2ProviderProps): ReactNode;