@payload-auth-link/react 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,45 @@
-# Temporary Holding Version
+# @payload-auth-link/react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Provider-agnostic React UI for payload-auth-link: a session context plus unstyled sign-in, sign-out, and user-menu components. It has no Next.js or Payload imports, so it works under any framework adapter.
+
+Part of [payload-auth-link](https://github.com/jellologic/payload-auth-link): an auth plugin for Payload CMS with swappable identity providers (Better Auth, Auth.js) and first-class Next.js and TanStack Start adapters.
+
+## Install
+
+```bash
+npm install @payload-auth-link/react
+```
+
+Peer dependencies: `react` ^19.0.0.
+
+ESM-only, Node 20.9 or later.
+
+## What it provides
+
+- `AuthLinkProvider`, `useAuthLink`, `useHasRoles`: session context, hydrated from the server through `initialUser`
+- `SignInButton`, `SignOutButton`, `UserMenu`: unstyled primitives
+- `RequireRoles`: hides UI by role (never use it to gate content; enforce on the server)
+
+## Usage
+
+```tsx
+import { AuthLinkProvider, UserMenu } from '@payload-auth-link/react'
+
+export function Layout({ user, children }) {
+  return (
+    <AuthLinkProvider initialUser={user}>
+      <UserMenu signOutRedirectTo="/" />
+      {children}
+    </AuthLinkProvider>
+  )
+}
+```
+
+## Docs
+
+- [Getting started](https://github.com/jellologic/payload-auth-link/blob/main/docs/getting-started.md)
+- [Compatibility](https://github.com/jellologic/payload-auth-link/blob/main/docs/compatibility.md) · [Troubleshooting](https://github.com/jellologic/payload-auth-link/blob/main/docs/troubleshooting.md) · [Changelog](./CHANGELOG.md)
+
+## License
+
+MIT

package/dist/components.d.ts

@@ -0,0 +1,54 @@
+import type { ReactNode } from 'react';
+/** {@link SignInButton} wiring; unstyled by design. */
+export type SignInButtonProps = {
+    /** Where the sign-in page lives. Defaults to `/sign-in`. */
+    readonly href?: string | undefined;
+    readonly className?: string | undefined;
+    readonly children?: ReactNode | undefined;
+};
+/** Unstyled link to the builder's sign-in page. */
+export declare function SignInButton({ href, className, children, }: SignInButtonProps): ReactNode;
+/** {@link SignOutButton} wiring; navigation is injectable. */
+export type SignOutButtonProps = {
+    readonly className?: string | undefined;
+    readonly children?: ReactNode | undefined;
+    /**
+     * Where to go after a successful sign-out. Stays put by default.
+     * Narrowed by `safeRedirectPath` (an off-origin or API destination
+     * falls back to `/`), so a prop fed from a query param cannot turn
+     * sign-out into an open redirect.
+     */
+    readonly redirectTo?: string | undefined;
+    /** Navigation injection for tests; defaults to a full page load. */
+    readonly navigate?: ((url: string) => void) | undefined;
+    /** Called after a successful sign-out, before navigation. */
+    readonly onSignedOut?: (() => void) | undefined;
+};
+/**
+ * Unstyled sign-out button. Revokes through the provider; on failure it
+ * does nothing (the session is still live, so navigating away would lie).
+ */
+export declare function SignOutButton({ className, children, redirectTo, navigate, onSignedOut, }: SignOutButtonProps): ReactNode;
+/** {@link UserMenu} wiring; renders nothing while loading. */
+export type UserMenuProps = {
+    readonly className?: string | undefined;
+    /** Sign-in page for the anonymous state. Defaults to `/sign-in`. */
+    readonly signInHref?: string | undefined;
+    /** Where to go after sign-out. Stays put by default. */
+    readonly signOutRedirectTo?: string | undefined;
+};
+/**
+ * Minimal session menu: nothing while loading, a sign-in link when
+ * anonymous, the email plus a sign-out button when authenticated.
+ */
+export declare function UserMenu({ className, signInHref, signOutRedirectTo, }: UserMenuProps): ReactNode;
+/** {@link RequireRoles} wiring: all roles required, fail closed. */
+export type RequireRolesProps = {
+    /** Every listed role is required (fail closed while loading). */
+    readonly roles: readonly string[];
+    readonly children: ReactNode;
+    readonly fallback?: ReactNode | undefined;
+};
+/** Render-gate for role-restricted UI. Hides — it never authorizes. */
+export declare function RequireRoles({ roles, children, fallback }: RequireRolesProps): ReactNode;
+//# sourceMappingURL=components.d.ts.map

package/dist/components.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"components.d.ts","sourceRoot":"","sources":["../src/components.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAA;AAGtC,uDAAuD;AACvD,MAAM,MAAM,iBAAiB,GAAG;IAC9B,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAClC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACvC,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,GAAG,SAAS,CAAA;CAC1C,CAAA;AAED,mDAAmD;AACnD,wBAAgB,YAAY,CAAC,EAC3B,IAAiB,EACjB,SAAS,EACT,QAAoB,GACrB,EAAE,iBAAiB,GAAG,SAAS,CAM/B;AAED,8DAA8D;AAC9D,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACvC,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,GAAG,SAAS,CAAA;IACzC;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACxC,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,SAAS,CAAA;IACvD,6DAA6D;IAC7D,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAAA;CAChD,CAAA;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,EAC5B,SAAS,EACT,QAAqB,EACrB,UAAU,EACV,QAEC,EACD,WAAW,GACZ,EAAE,kBAAkB,GAAG,SAAS,CAuBhC;AAED,8DAA8D;AAC9D,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACvC,oEAAoE;IACpE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACxC,wDAAwD;IACxD,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAChD,CAAA;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,EACvB,SAAS,EACT,UAAuB,EACvB,iBAAiB,GAClB,EAAE,aAAa,GAAG,SAAS,CAc3B;AAED,oEAAoE;AACpE,MAAM,MAAM,iBAAiB,GAAG;IAC9B,iEAAiE;IACjE,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;IACjC,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAA;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,GAAG,SAAS,CAAA;CAC1C,CAAA;AAED,uEAAuE;AACvE,wBAAgB,YAAY,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAe,EAAE,EAAE,iBAAiB,GAAG,SAAS,CAG/F"}

package/dist/components.js

@@ -0,0 +1,49 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { safeRedirectPath } from '@payload-auth-link/core';
+import { useAuthLink, useHasRoles } from './provider.js';
+/** Unstyled link to the builder's sign-in page. */
+export function SignInButton({ href = '/sign-in', className, children = 'Sign in', }) {
+    return (_jsx("a", { href: href, className: className, "data-auth-link": "sign-in", children: children }));
+}
+/**
+ * Unstyled sign-out button. Revokes through the provider; on failure it
+ * does nothing (the session is still live, so navigating away would lie).
+ */
+export function SignOutButton({ className, children = 'Sign out', redirectTo, navigate = (url) => {
+    window.location.assign(url);
+}, onSignedOut, }) {
+    const { signOut } = useAuthLink();
+    return (_jsx("button", { type: "button", className: className, "data-auth-link": "sign-out", onClick: () => {
+            void (async () => {
+                if (await signOut()) {
+                    onSignedOut?.();
+                    if (redirectTo !== undefined) {
+                        // Sign-in is a fine post-sign-out destination: disable
+                        // that rule, keep the off-origin and API ones.
+                        navigate(safeRedirectPath(redirectTo, '/', { signInPath: null }));
+                    }
+                }
+            })();
+        }, children: children }));
+}
+/**
+ * Minimal session menu: nothing while loading, a sign-in link when
+ * anonymous, the email plus a sign-out button when authenticated.
+ */
+export function UserMenu({ className, signInHref = '/sign-in', signOutRedirectTo, }) {
+    const { user, status } = useAuthLink();
+    if (status === 'loading') {
+        return null;
+    }
+    if (!user) {
+        return _jsx(SignInButton, { href: signInHref });
+    }
+    return (_jsxs("div", { className: className, "data-auth-link": "user-menu", "data-auth-status": status, children: [_jsx("span", { "data-auth-link": "user-email", children: user.email }), ' ', _jsx(SignOutButton, { redirectTo: signOutRedirectTo })] }));
+}
+/** Render-gate for role-restricted UI. Hides — it never authorizes. */
+export function RequireRoles({ roles, children, fallback = null }) {
+    const allowed = useHasRoles(...roles);
+    return allowed ? children : fallback;
+}
+//# sourceMappingURL=components.js.map

package/dist/components.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"components.js","sourceRoot":"","sources":["../src/components.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAA;;AAEZ,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAA;AAE1D,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAUxD,mDAAmD;AACnD,MAAM,UAAU,YAAY,CAAC,EAC3B,IAAI,GAAG,UAAU,EACjB,SAAS,EACT,QAAQ,GAAG,SAAS,GACF;IAClB,OAAO,CACL,YAAG,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,SAAS,oBAAiB,SAAS,YAC1D,QAAQ,GACP,CACL,CAAA;AACH,CAAC;AAmBD;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,EAC5B,SAAS,EACT,QAAQ,GAAG,UAAU,EACrB,UAAU,EACV,QAAQ,GAAG,CAAC,GAAW,EAAQ,EAAE;IAC/B,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;AAC7B,CAAC,EACD,WAAW,GACQ;IACnB,MAAM,EAAE,OAAO,EAAE,GAAG,WAAW,EAAE,CAAA;IACjC,OAAO,CACL,iBACE,IAAI,EAAC,QAAQ,EACb,SAAS,EAAE,SAAS,oBACL,UAAU,EACzB,OAAO,EAAE,GAAG,EAAE;YACZ,KAAK,CAAC,KAAK,IAAI,EAAE;gBACf,IAAI,MAAM,OAAO,EAAE,EAAE,CAAC;oBACpB,WAAW,EAAE,EAAE,CAAA;oBACf,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;wBAC7B,uDAAuD;wBACvD,+CAA+C;wBAC/C,QAAQ,CAAC,gBAAgB,CAAC,UAAU,EAAE,GAAG,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC,CAAA;oBACnE,CAAC;gBACH,CAAC;YACH,CAAC,CAAC,EAAE,CAAA;QACN,CAAC,YAEA,QAAQ,GACF,CACV,CAAA;AACH,CAAC;AAWD;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,EACvB,SAAS,EACT,UAAU,GAAG,UAAU,EACvB,iBAAiB,GACH;IACd,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,WAAW,EAAE,CAAA;IACtC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,OAAO,IAAI,CAAA;IACb,CAAC;IACD,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,KAAC,YAAY,IAAC,IAAI,EAAE,UAAU,GAAI,CAAA;IAC3C,CAAC;IACD,OAAO,CACL,eAAK,SAAS,EAAE,SAAS,oBAAiB,WAAW,sBAAmB,MAAM,aAC5E,iCAAqB,YAAY,YAAE,IAAI,CAAC,KAAK,GAAQ,EAAC,GAAG,EACzD,KAAC,aAAa,IAAC,UAAU,EAAE,iBAAiB,GAAI,IAC5C,CACP,CAAA;AACH,CAAC;AAUD,uEAAuE;AACvE,MAAM,UAAU,YAAY,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,GAAG,IAAI,EAAqB;IAClF,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,KAAK,CAAC,CAAA;IACrC,OAAO,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAA;AACtC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Provider-agnostic React UI: session context, sign-in components, user
+ * menu, role gates. No Next, no Payload imports — framework work lives in
+ * `@payload-auth-link/next`, server work in `@payload-auth-link/plugin`.
+ */
+export declare const packageName = "@payload-auth-link/react";
+export { RequireRoles, SignInButton, SignOutButton, UserMenu } from './components.js';
+export type { RequireRolesProps, SignInButtonProps, SignOutButtonProps, UserMenuProps, } from './components.js';
+export { AuthLinkProvider, useAuthLink, useHasRoles } from './provider.js';
+export type { AuthLinkContextValue, AuthLinkProviderProps, AuthLinkStatus } from './provider.js';
+export { fetchSessionUser, revokeSession } from './session.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,eAAO,MAAM,WAAW,6BAA6B,CAAA;AAErD,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AACrF,YAAY,EACV,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,aAAa,GACd,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAC1E,YAAY,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAChG,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA"}

package/dist/index.js

@@ -0,0 +1,10 @@
+/**
+ * Provider-agnostic React UI: session context, sign-in components, user
+ * menu, role gates. No Next, no Payload imports — framework work lives in
+ * `@payload-auth-link/next`, server work in `@payload-auth-link/plugin`.
+ */
+export const packageName = '@payload-auth-link/react';
+export { RequireRoles, SignInButton, SignOutButton, UserMenu } from './components.js';
+export { AuthLinkProvider, useAuthLink, useHasRoles } from './provider.js';
+export { fetchSessionUser, revokeSession } from './session.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,0BAA0B,CAAA;AAErD,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAOrF,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAE1E,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA"}

package/dist/provider.d.ts

@@ -0,0 +1,46 @@
+import { type ReactNode } from 'react';
+import { type HttpFetch, type SessionUser } from '@payload-auth-link/core';
+/** Session state: unknown until the first load settles. */
+export type AuthLinkStatus = 'loading' | 'authenticated' | 'anonymous';
+/** What `useAuthLink` returns: user, status, refresh, honest sign-out. */
+export type AuthLinkContextValue = {
+    readonly user: SessionUser | null;
+    readonly status: AuthLinkStatus;
+    /** Re-read the session endpoint (call after sign-in or role changes). */
+    readonly refresh: () => Promise<void>;
+    /**
+     * Revoke the session and drop local state. Resolves `false` when the
+     * revocation failed — local state is kept so the UI stays honest.
+     */
+    readonly signOut: () => Promise<boolean>;
+};
+/** Client provider wiring; `initialUser` is the hydration contract. */
+export type AuthLinkProviderProps = {
+    readonly children: ReactNode;
+    /** Session endpoint path. Defaults to the plugin's endpoint. */
+    readonly sessionEndpoint?: string | undefined;
+    /** Injectible fetch. Defaults to the global `fetch`. */
+    readonly fetchImpl?: HttpFetch | undefined;
+    /**
+     * Hydration contract: `undefined` (default) fetches on mount;
+     * `SessionUser` starts authenticated without a fetch; `null` starts
+     * anonymous without a fetch. The Next adapter's server provider
+     * supplies this from full server-side validation.
+     */
+    readonly initialUser?: SessionUser | null | undefined;
+};
+/**
+ * Client session provider: loads once on mount (unless hydrated),
+ * exposes refresh/sign-out. Fail-closed — fetch errors mean anonymous.
+ *
+ * A later `initialUser` (a re-run server loader, a new RSC payload) is
+ * synced into context when its value changes; re-renders passing the
+ * same user as a fresh object change nothing, so a client-side sign-out
+ * is never undone by a stale snapshot. Refresh stays explicit.
+ */
+export declare function AuthLinkProvider({ children, sessionEndpoint, fetchImpl, initialUser, }: AuthLinkProviderProps): ReactNode;
+/** Read the auth context. Throws outside `AuthLinkProvider` — fail loud. */
+export declare function useAuthLink(): AuthLinkContextValue;
+/** `true` when the current user holds every listed role. Fails closed. */
+export declare function useHasRoles(...roles: readonly string[]): boolean;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.tsx"],"names":[],"mappings":"AAEA,OAAO,EAOL,KAAK,SAAS,EACf,MAAM,OAAO,CAAA;AACd,OAAO,EAEL,KAAK,SAAS,EACd,KAAK,WAAW,EACjB,MAAM,yBAAyB,CAAA;AAGhC,2DAA2D;AAC3D,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,eAAe,GAAG,WAAW,CAAA;AAEtE,0EAA0E;AAC1E,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CAAA;IACjC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAA;IAC/B,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;IACrC;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAA;CACzC,CAAA;AAID,uEAAuE;AACvE,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAA;IAC5B,gEAAgE;IAChE,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7C,wDAAwD;IACxD,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,GAAG,SAAS,CAAA;IAC1C;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,GAAG,IAAI,GAAG,SAAS,CAAA;CACtD,CAAA;AAiBD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,QAAQ,EACR,eAA4C,EAC5C,SAAiB,EACjB,WAAuB,GACxB,EAAE,qBAAqB,GAAG,SAAS,CA6DnC;AAED,4EAA4E;AAC5E,wBAAgB,WAAW,IAAI,oBAAoB,CAMlD;AAED,0EAA0E;AAC1E,wBAAgB,WAAW,CAAC,GAAG,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAMhE"}

package/dist/provider.js

@@ -0,0 +1,94 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useCallback, useContext, useEffect, useMemo, useState, } from 'react';
+import { defaultSessionEndpointPath, } from '@payload-auth-link/core';
+import { fetchSessionUser, revokeSession } from './session.js';
+const AuthLinkContext = createContext(null);
+/** Value identity for hydration snapshots (fresh objects, same user). */
+function snapshotKey(user) {
+    if (user === undefined) {
+        return 'undefined';
+    }
+    if (user === null) {
+        return 'null';
+    }
+    return JSON.stringify([user.id, user.collection, user.email, [...user.roles].sort()]);
+}
+function statusFor(user) {
+    return user === null ? 'anonymous' : 'authenticated';
+}
+/**
+ * Client session provider: loads once on mount (unless hydrated),
+ * exposes refresh/sign-out. Fail-closed — fetch errors mean anonymous.
+ *
+ * A later `initialUser` (a re-run server loader, a new RSC payload) is
+ * synced into context when its value changes; re-renders passing the
+ * same user as a fresh object change nothing, so a client-side sign-out
+ * is never undone by a stale snapshot. Refresh stays explicit.
+ */
+export function AuthLinkProvider({ children, sessionEndpoint = defaultSessionEndpointPath, fetchImpl = fetch, initialUser = undefined, }) {
+    const [user, setUser] = useState(initialUser ?? null);
+    const [status, setStatus] = useState(initialUser === undefined ? 'loading' : statusFor(initialUser));
+    // React's "adjust state when a prop changes" pattern (during render,
+    // not in an effect): no stale frame, no set-state-in-effect.
+    const [syncedKey, setSyncedKey] = useState(() => snapshotKey(initialUser));
+    const incomingKey = snapshotKey(initialUser);
+    if (incomingKey !== syncedKey) {
+        setSyncedKey(incomingKey);
+        if (initialUser !== undefined) {
+            setUser(initialUser);
+            setStatus(statusFor(initialUser));
+        }
+    }
+    const loadSession = useCallback(() => fetchSessionUser(sessionEndpoint, fetchImpl), [sessionEndpoint, fetchImpl]);
+    const refresh = useCallback(async () => {
+        const current = await loadSession();
+        setUser(current);
+        setStatus(current === null ? 'anonymous' : 'authenticated');
+    }, [loadSession]);
+    const signOut = useCallback(async () => {
+        const revoked = await revokeSession(sessionEndpoint, fetchImpl);
+        if (revoked) {
+            setUser(null);
+            setStatus('anonymous');
+        }
+        return revoked;
+    }, [sessionEndpoint, fetchImpl]);
+    useEffect(() => {
+        if (initialUser !== undefined) {
+            return;
+        }
+        let cancelled = false;
+        // Mount-only initial load (the async boundary keeps this out of the
+        // sync-setState-in-effect rule); `refresh` stays the public re-read.
+        void (async () => {
+            const current = await loadSession();
+            if (!cancelled) {
+                setUser(current);
+                setStatus(current === null ? 'anonymous' : 'authenticated');
+            }
+        })();
+        return () => {
+            cancelled = true;
+        };
+    }, [initialUser, loadSession]);
+    const value = useMemo(() => ({ user, status, refresh, signOut }), [user, status, refresh, signOut]);
+    return _jsx(AuthLinkContext.Provider, { value: value, children: children });
+}
+/** Read the auth context. Throws outside `AuthLinkProvider` — fail loud. */
+export function useAuthLink() {
+    const value = useContext(AuthLinkContext);
+    if (!value) {
+        throw new Error('useAuthLink must be used within AuthLinkProvider');
+    }
+    return value;
+}
+/** `true` when the current user holds every listed role. Fails closed. */
+export function useHasRoles(...roles) {
+    const { user } = useAuthLink();
+    if (!user) {
+        return false;
+    }
+    return roles.every((role) => user.roles.includes(role));
+}
+//# sourceMappingURL=provider.js.map

package/dist/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.tsx"],"names":[],"mappings":"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"}

package/dist/session.d.ts

@@ -0,0 +1,17 @@
+import { type HttpFetch, type SessionUser } from '@payload-auth-link/core';
+/**
+ * Read the current session user from the plugin's session endpoint
+ * (`{ user }` envelope). Fails closed: transport errors, non-2xx
+ * statuses, invalid JSON, and malformed envelopes all yield `null`,
+ * never an exception and never a partial user.
+ */
+export declare function fetchSessionUser(sessionEndpoint?: string, fetchImpl?: HttpFetch): Promise<SessionUser | null>;
+/**
+ * Revoke the current session through the plugin's session endpoint.
+ * Sends the CSRF header the endpoint requires. Returns `true` when the
+ * session is gone afterwards: `2xx`, or `401` (already signed out —
+ * logout is idempotent). Transport errors and other statuses return
+ * `false` so the caller can report instead of lying.
+ */
+export declare function revokeSession(sessionEndpoint?: string, fetchImpl?: HttpFetch): Promise<boolean>;
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,SAAS,EACd,KAAK,WAAW,EACjB,MAAM,yBAAyB,CAAA;AAEhC;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,eAAe,GAAE,MAAmC,EACpD,SAAS,GAAE,SAAiB,GAC3B,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAe7B;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,eAAe,GAAE,MAAmC,EACpD,SAAS,GAAE,SAAiB,GAC3B,OAAO,CAAC,OAAO,CAAC,CAYlB"}

package/dist/session.js

@@ -0,0 +1,46 @@
+import { csrfHeaderName, defaultSessionEndpointPath, parseSessionResponse, } from '@payload-auth-link/core';
+/**
+ * Read the current session user from the plugin's session endpoint
+ * (`{ user }` envelope). Fails closed: transport errors, non-2xx
+ * statuses, invalid JSON, and malformed envelopes all yield `null`,
+ * never an exception and never a partial user.
+ */
+export async function fetchSessionUser(sessionEndpoint = defaultSessionEndpointPath, fetchImpl = fetch) {
+    let response;
+    try {
+        response = await fetchImpl(sessionEndpoint, {
+            method: 'GET',
+            credentials: 'same-origin',
+            // Belt and suspenders with the endpoint's `Cache-Control:
+            // no-store`: never serve this read from any cache.
+            cache: 'no-store',
+            headers: { accept: 'application/json' },
+        });
+    }
+    catch {
+        return null;
+    }
+    return parseSessionResponse(response);
+}
+/**
+ * Revoke the current session through the plugin's session endpoint.
+ * Sends the CSRF header the endpoint requires. Returns `true` when the
+ * session is gone afterwards: `2xx`, or `401` (already signed out —
+ * logout is idempotent). Transport errors and other statuses return
+ * `false` so the caller can report instead of lying.
+ */
+export async function revokeSession(sessionEndpoint = defaultSessionEndpointPath, fetchImpl = fetch) {
+    let response;
+    try {
+        response = await fetchImpl(sessionEndpoint, {
+            method: 'DELETE',
+            credentials: 'same-origin',
+            headers: { [csrfHeaderName]: '1' },
+        });
+    }
+    catch {
+        return false;
+    }
+    return response.ok || response.status === 401;
+}
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,0BAA0B,EAC1B,oBAAoB,GAGrB,MAAM,yBAAyB,CAAA;AAEhC;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,kBAA0B,0BAA0B,EACpD,YAAuB,KAAK;IAE5B,IAAI,QAAkB,CAAA;IACtB,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,SAAS,CAAC,eAAe,EAAE;YAC1C,MAAM,EAAE,KAAK;YACb,WAAW,EAAE,aAAa;YAC1B,0DAA0D;YAC1D,mDAAmD;YACnD,KAAK,EAAE,UAAU;YACjB,OAAO,EAAE,EAAE,MAAM,EAAE,kBAAkB,EAAE;SACxC,CAAC,CAAA;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAA;IACb,CAAC;IACD,OAAO,oBAAoB,CAAC,QAAQ,CAAC,CAAA;AACvC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,kBAA0B,0BAA0B,EACpD,YAAuB,KAAK;IAE5B,IAAI,QAAkB,CAAA;IACtB,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,SAAS,CAAC,eAAe,EAAE;YAC1C,MAAM,EAAE,QAAQ;YAChB,WAAW,EAAE,aAAa;YAC1B,OAAO,EAAE,EAAE,CAAC,cAAc,CAAC,EAAE,GAAG,EAAE;SACnC,CAAC,CAAA;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAA;IACd,CAAC;IACD,OAAO,QAAQ,CAAC,EAAE,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,CAAA;AAC/C,CAAC"}

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@payload-auth-link/react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "payload-auth-link React UI: provider-agnostic sign-in components and user menu.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jellologic/payload-auth-link.git",
+    "directory": "packages/react"
+  },
+  "homepage": "https://github.com/jellologic/payload-auth-link/tree/main/packages/react#readme",
+  "bugs": {
+    "url": "https://github.com/jellologic/payload-auth-link/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "!dist/*.tsbuildinfo",
+    "src",
+    "!src/**/__tests__",
+    "!dist/**/__tests__",
+    "!dist/**/__fixtures__",
+    "!src/**/__fixtures__"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc -b",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  },
+  "dependencies": {
+    "@payload-auth-link/core": "0.1.1"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0"
+  },
+  "devDependencies": {
+    "react": "19.2.6"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "engines": {
+    "node": ">=20.9.0"
+  }
+}

package/src/components.tsx

@@ -0,0 +1,127 @@
+'use client'
+
+import { safeRedirectPath } from '@payload-auth-link/core'
+import type { ReactNode } from 'react'
+import { useAuthLink, useHasRoles } from './provider.js'
+
+/** {@link SignInButton} wiring; unstyled by design. */
+export type SignInButtonProps = {
+  /** Where the sign-in page lives. Defaults to `/sign-in`. */
+  readonly href?: string | undefined
+  readonly className?: string | undefined
+  readonly children?: ReactNode | undefined
+}
+
+/** Unstyled link to the builder's sign-in page. */
+export function SignInButton({
+  href = '/sign-in',
+  className,
+  children = 'Sign in',
+}: SignInButtonProps): ReactNode {
+  return (
+    <a href={href} className={className} data-auth-link="sign-in">
+      {children}
+    </a>
+  )
+}
+
+/** {@link SignOutButton} wiring; navigation is injectable. */
+export type SignOutButtonProps = {
+  readonly className?: string | undefined
+  readonly children?: ReactNode | undefined
+  /**
+   * Where to go after a successful sign-out. Stays put by default.
+   * Narrowed by `safeRedirectPath` (an off-origin or API destination
+   * falls back to `/`), so a prop fed from a query param cannot turn
+   * sign-out into an open redirect.
+   */
+  readonly redirectTo?: string | undefined
+  /** Navigation injection for tests; defaults to a full page load. */
+  readonly navigate?: ((url: string) => void) | undefined
+  /** Called after a successful sign-out, before navigation. */
+  readonly onSignedOut?: (() => void) | undefined
+}
+
+/**
+ * Unstyled sign-out button. Revokes through the provider; on failure it
+ * does nothing (the session is still live, so navigating away would lie).
+ */
+export function SignOutButton({
+  className,
+  children = 'Sign out',
+  redirectTo,
+  navigate = (url: string): void => {
+    window.location.assign(url)
+  },
+  onSignedOut,
+}: SignOutButtonProps): ReactNode {
+  const { signOut } = useAuthLink()
+  return (
+    <button
+      type="button"
+      className={className}
+      data-auth-link="sign-out"
+      onClick={() => {
+        void (async () => {
+          if (await signOut()) {
+            onSignedOut?.()
+            if (redirectTo !== undefined) {
+              // Sign-in is a fine post-sign-out destination: disable
+              // that rule, keep the off-origin and API ones.
+              navigate(safeRedirectPath(redirectTo, '/', { signInPath: null }))
+            }
+          }
+        })()
+      }}
+    >
+      {children}
+    </button>
+  )
+}
+
+/** {@link UserMenu} wiring; renders nothing while loading. */
+export type UserMenuProps = {
+  readonly className?: string | undefined
+  /** Sign-in page for the anonymous state. Defaults to `/sign-in`. */
+  readonly signInHref?: string | undefined
+  /** Where to go after sign-out. Stays put by default. */
+  readonly signOutRedirectTo?: string | undefined
+}
+
+/**
+ * Minimal session menu: nothing while loading, a sign-in link when
+ * anonymous, the email plus a sign-out button when authenticated.
+ */
+export function UserMenu({
+  className,
+  signInHref = '/sign-in',
+  signOutRedirectTo,
+}: UserMenuProps): ReactNode {
+  const { user, status } = useAuthLink()
+  if (status === 'loading') {
+    return null
+  }
+  if (!user) {
+    return <SignInButton href={signInHref} />
+  }
+  return (
+    <div className={className} data-auth-link="user-menu" data-auth-status={status}>
+      <span data-auth-link="user-email">{user.email}</span>{' '}
+      <SignOutButton redirectTo={signOutRedirectTo} />
+    </div>
+  )
+}
+
+/** {@link RequireRoles} wiring: all roles required, fail closed. */
+export type RequireRolesProps = {
+  /** Every listed role is required (fail closed while loading). */
+  readonly roles: readonly string[]
+  readonly children: ReactNode
+  readonly fallback?: ReactNode | undefined
+}
+
+/** Render-gate for role-restricted UI. Hides — it never authorizes. */
+export function RequireRoles({ roles, children, fallback = null }: RequireRolesProps): ReactNode {
+  const allowed = useHasRoles(...roles)
+  return allowed ? children : fallback
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Provider-agnostic React UI: session context, sign-in components, user
+ * menu, role gates. No Next, no Payload imports — framework work lives in
+ * `@payload-auth-link/next`, server work in `@payload-auth-link/plugin`.
+ */
+export const packageName = '@payload-auth-link/react'
+
+export { RequireRoles, SignInButton, SignOutButton, UserMenu } from './components.js'
+export type {
+  RequireRolesProps,
+  SignInButtonProps,
+  SignOutButtonProps,
+  UserMenuProps,
+} from './components.js'
+export { AuthLinkProvider, useAuthLink, useHasRoles } from './provider.js'
+export type { AuthLinkContextValue, AuthLinkProviderProps, AuthLinkStatus } from './provider.js'
+export { fetchSessionUser, revokeSession } from './session.js'

package/src/provider.tsx

@@ -0,0 +1,161 @@
+'use client'
+
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+  type ReactNode,
+} from 'react'
+import {
+  defaultSessionEndpointPath,
+  type HttpFetch,
+  type SessionUser,
+} from '@payload-auth-link/core'
+import { fetchSessionUser, revokeSession } from './session.js'
+
+/** Session state: unknown until the first load settles. */
+export type AuthLinkStatus = 'loading' | 'authenticated' | 'anonymous'
+
+/** What `useAuthLink` returns: user, status, refresh, honest sign-out. */
+export type AuthLinkContextValue = {
+  readonly user: SessionUser | null
+  readonly status: AuthLinkStatus
+  /** Re-read the session endpoint (call after sign-in or role changes). */
+  readonly refresh: () => Promise<void>
+  /**
+   * Revoke the session and drop local state. Resolves `false` when the
+   * revocation failed — local state is kept so the UI stays honest.
+   */
+  readonly signOut: () => Promise<boolean>
+}
+
+const AuthLinkContext = createContext<AuthLinkContextValue | null>(null)
+
+/** Client provider wiring; `initialUser` is the hydration contract. */
+export type AuthLinkProviderProps = {
+  readonly children: ReactNode
+  /** Session endpoint path. Defaults to the plugin's endpoint. */
+  readonly sessionEndpoint?: string | undefined
+  /** Injectible fetch. Defaults to the global `fetch`. */
+  readonly fetchImpl?: HttpFetch | undefined
+  /**
+   * Hydration contract: `undefined` (default) fetches on mount;
+   * `SessionUser` starts authenticated without a fetch; `null` starts
+   * anonymous without a fetch. The Next adapter's server provider
+   * supplies this from full server-side validation.
+   */
+  readonly initialUser?: SessionUser | null | undefined
+}
+
+/** Value identity for hydration snapshots (fresh objects, same user). */
+function snapshotKey(user: SessionUser | null | undefined): string {
+  if (user === undefined) {
+    return 'undefined'
+  }
+  if (user === null) {
+    return 'null'
+  }
+  return JSON.stringify([user.id, user.collection, user.email, [...user.roles].sort()])
+}
+
+function statusFor(user: SessionUser | null): AuthLinkStatus {
+  return user === null ? 'anonymous' : 'authenticated'
+}
+
+/**
+ * Client session provider: loads once on mount (unless hydrated),
+ * exposes refresh/sign-out. Fail-closed — fetch errors mean anonymous.
+ *
+ * A later `initialUser` (a re-run server loader, a new RSC payload) is
+ * synced into context when its value changes; re-renders passing the
+ * same user as a fresh object change nothing, so a client-side sign-out
+ * is never undone by a stale snapshot. Refresh stays explicit.
+ */
+export function AuthLinkProvider({
+  children,
+  sessionEndpoint = defaultSessionEndpointPath,
+  fetchImpl = fetch,
+  initialUser = undefined,
+}: AuthLinkProviderProps): ReactNode {
+  const [user, setUser] = useState<SessionUser | null>(initialUser ?? null)
+  const [status, setStatus] = useState<AuthLinkStatus>(
+    initialUser === undefined ? 'loading' : statusFor(initialUser)
+  )
+  // React's "adjust state when a prop changes" pattern (during render,
+  // not in an effect): no stale frame, no set-state-in-effect.
+  const [syncedKey, setSyncedKey] = useState(() => snapshotKey(initialUser))
+  const incomingKey = snapshotKey(initialUser)
+  if (incomingKey !== syncedKey) {
+    setSyncedKey(incomingKey)
+    if (initialUser !== undefined) {
+      setUser(initialUser)
+      setStatus(statusFor(initialUser))
+    }
+  }
+
+  const loadSession = useCallback(
+    () => fetchSessionUser(sessionEndpoint, fetchImpl),
+    [sessionEndpoint, fetchImpl]
+  )
+
+  const refresh = useCallback(async () => {
+    const current = await loadSession()
+    setUser(current)
+    setStatus(current === null ? 'anonymous' : 'authenticated')
+  }, [loadSession])
+
+  const signOut = useCallback(async () => {
+    const revoked = await revokeSession(sessionEndpoint, fetchImpl)
+    if (revoked) {
+      setUser(null)
+      setStatus('anonymous')
+    }
+    return revoked
+  }, [sessionEndpoint, fetchImpl])
+
+  useEffect(() => {
+    if (initialUser !== undefined) {
+      return
+    }
+    let cancelled = false
+    // Mount-only initial load (the async boundary keeps this out of the
+    // sync-setState-in-effect rule); `refresh` stays the public re-read.
+    void (async () => {
+      const current = await loadSession()
+      if (!cancelled) {
+        setUser(current)
+        setStatus(current === null ? 'anonymous' : 'authenticated')
+      }
+    })()
+    return () => {
+      cancelled = true
+    }
+  }, [initialUser, loadSession])
+
+  const value = useMemo<AuthLinkContextValue>(
+    () => ({ user, status, refresh, signOut }),
+    [user, status, refresh, signOut]
+  )
+  return <AuthLinkContext.Provider value={value}>{children}</AuthLinkContext.Provider>
+}
+
+/** Read the auth context. Throws outside `AuthLinkProvider` — fail loud. */
+export function useAuthLink(): AuthLinkContextValue {
+  const value = useContext(AuthLinkContext)
+  if (!value) {
+    throw new Error('useAuthLink must be used within AuthLinkProvider')
+  }
+  return value
+}
+
+/** `true` when the current user holds every listed role. Fails closed. */
+export function useHasRoles(...roles: readonly string[]): boolean {
+  const { user } = useAuthLink()
+  if (!user) {
+    return false
+  }
+  return roles.every((role) => user.roles.includes(role))
+}

package/src/session.ts

@@ -0,0 +1,57 @@
+import {
+  csrfHeaderName,
+  defaultSessionEndpointPath,
+  parseSessionResponse,
+  type HttpFetch,
+  type SessionUser,
+} from '@payload-auth-link/core'
+
+/**
+ * Read the current session user from the plugin's session endpoint
+ * (`{ user }` envelope). Fails closed: transport errors, non-2xx
+ * statuses, invalid JSON, and malformed envelopes all yield `null`,
+ * never an exception and never a partial user.
+ */
+export async function fetchSessionUser(
+  sessionEndpoint: string = defaultSessionEndpointPath,
+  fetchImpl: HttpFetch = fetch
+): Promise<SessionUser | null> {
+  let response: Response
+  try {
+    response = await fetchImpl(sessionEndpoint, {
+      method: 'GET',
+      credentials: 'same-origin',
+      // Belt and suspenders with the endpoint's `Cache-Control:
+      // no-store`: never serve this read from any cache.
+      cache: 'no-store',
+      headers: { accept: 'application/json' },
+    })
+  } catch {
+    return null
+  }
+  return parseSessionResponse(response)
+}
+
+/**
+ * Revoke the current session through the plugin's session endpoint.
+ * Sends the CSRF header the endpoint requires. Returns `true` when the
+ * session is gone afterwards: `2xx`, or `401` (already signed out —
+ * logout is idempotent). Transport errors and other statuses return
+ * `false` so the caller can report instead of lying.
+ */
+export async function revokeSession(
+  sessionEndpoint: string = defaultSessionEndpointPath,
+  fetchImpl: HttpFetch = fetch
+): Promise<boolean> {
+  let response: Response
+  try {
+    response = await fetchImpl(sessionEndpoint, {
+      method: 'DELETE',
+      credentials: 'same-origin',
+      headers: { [csrfHeaderName]: '1' },
+    })
+  } catch {
+    return false
+  }
+  return response.ok || response.status === 401
+}