@djangocfg/layouts 2.1.605 → 2.1.606

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/layouts",
-  "version": "2.1.605",
+  "version": "2.1.606",
   "description": "Simple, straightforward layout components for Next.js - import and use with props",
   "keywords": [
     "layouts",
@@ -91,11 +91,11 @@
     "test": "vitest run"
   },
   "peerDependencies": {
-    "@djangocfg/analytics": "^2.1.605",
-    "@djangocfg/api": "^2.1.605",
-    "@djangocfg/devtools": "^2.1.605",
-    "@djangocfg/i18n": "^2.1.605",
-    "@djangocfg/ui-core": "^2.1.605",
+    "@djangocfg/analytics": "^2.1.606",
+    "@djangocfg/api": "^2.1.606",
+    "@djangocfg/devtools": "^2.1.606",
+    "@djangocfg/i18n": "^2.1.606",
+    "@djangocfg/ui-core": "^2.1.606",
     "@hookform/resolvers": "^5.2.2",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
@@ -125,12 +125,12 @@
     "uuid": "^11.1.1"
   },
   "devDependencies": {
-    "@djangocfg/analytics": "^2.1.605",
-    "@djangocfg/api": "^2.1.605",
-    "@djangocfg/devtools": "^2.1.605",
-    "@djangocfg/i18n": "^2.1.605",
-    "@djangocfg/typescript-config": "^2.1.605",
-    "@djangocfg/ui-core": "^2.1.605",
+    "@djangocfg/analytics": "^2.1.606",
+    "@djangocfg/api": "^2.1.606",
+    "@djangocfg/devtools": "^2.1.606",
+    "@djangocfg/i18n": "^2.1.606",
+    "@djangocfg/typescript-config": "^2.1.606",
+    "@djangocfg/ui-core": "^2.1.606",
     "@storybook/react-vite": "^10.5.0",
     "@types/node": "^25.9.5",
     "@types/react": "19.2.15",

package/src/layouts/AuthLayout/AuthLayout.tsx

@@ -29,6 +29,7 @@ import { AuthFormProvider, useAuthFormContext } from './context';
 import { AuthShell } from './shells';
 
 import './styles/auth.css';
+import './styles/oauth.css';
 import './styles/centered-shell.css';
 import './styles/split-shell.css';
 import './styles/fullsplit-shell.css';

package/src/layouts/AuthLayout/README.md

@@ -293,10 +293,10 @@ the wait for the code exchange covers the page.
 | Expired or foreign state, exchange or token failure, provider down, unknown | one short sentence | **Try {provider} again** (email when the provider has no button here) |
 | Email missing or unverified, domain refused | one sentence | **Continue with email** |
 | Account disabled, rate limited | one sentence | none |
+| `origin_not_allowed`, `missing_redirect_uri`, `oauth_disabled` (site not set up for the provider) | "not available on this site"; for `origin_not_allowed` also a developer line with the refused origin and the redirect URI to register | **Continue with email** |
 
-The notice closes with its button or Escape. The code-to-copy table
-(`OAUTH_CODE_TO_KEY`) and the code-to-next-step table live together in
-`components/oauth/oauthNoticeCopy.ts`; copy is `layouts.auth.oauth.error.*` and
+The notice closes with its button or Escape. One table maps each code to its
+sentence and next step: `components/oauth/errors/errorCopy.ts`; copy is `layouts.auth.oauth.error.*` and
 `layouts.auth.oauth.notice.*` in `@djangocfg/i18n`. The strict-mode guard is
 unchanged: one attempt per page load.
 
@@ -333,10 +333,17 @@ AuthLayout/
 │   ├── context.tsx        — Shell context (variant, hasSidebar)
 │   └── types.ts           — AuthShellVariant, AuthBackgroundConfig
 ├── components/steps/      — Auth step components (IdentifierStep, OTPStep, ...)
+├── components/oauth/      — Provider sign-in, see its `index.ts` for the map:
+│   ├── providers/         — registry (name + icon per provider), icons, which to show
+│   ├── buttons/           — OAuthProviderButton, OAuthButtonList, OAuthButtons (hook)
+│   ├── notice/            — inline message after a failed round trip
+│   ├── callback/          — /auth?provider=<id>: URL parsing, wait overlay
+│   └── errors/            — failure code -> copy and next step
 ├── components/shared/     — Reusable UI primitives (AuthButton, AuthConsent, ...)
 │                          incl. AuthBrandPanel — the default `fullsplit` media content
 ├── styles/
 │   ├── auth.css            — Shared form/button/input styles
+│   ├── oauth.css           — Provider column, reserve while loading, developer hint
 │   ├── centered-shell.css  — Centered variant layout
 │   ├── split-shell.css     — Split variant layout
 │   └── fullsplit-shell.css — Full-bleed split variant layout
@@ -365,3 +372,13 @@ import { useAuthShell } from '@djangocfg/layouts';
 
 const { variant, hasSidebar } = useAuthShell();
 ```
+
+## Adding an OAuth provider
+
+1. The backend adds the provider; `make generate` in `@djangocfg/api` extends `OAuthProviderId`.
+2. Typecheck now fails in `components/oauth/providers/registry.ts`.
+3. Draw `providers/icons/<Name>Icon.tsx` (20x20, `currentColor` unless the brand forbids recolouring).
+4. Add one line to `OAUTH_PROVIDERS`: `{ name: 'Brand', Icon }`.
+
+Nothing else changes: the label is `layouts.auth.identifier.oauth.continueWith` with
+the brand name, the notices and error copy read the same table.

package/src/layouts/AuthLayout/components/oauth/OAuthSection.tsx

@@ -0,0 +1,54 @@
+'use client';
+
+import React, { memo, useCallback } from 'react';
+
+import { useAuthFormContext } from '../../context';
+import { AuthDivider } from '../shared/AuthDivider';
+import { OAuthButtons } from './buttons/OAuthButtons';
+import { OAuthNotice } from './notice/OAuthNotice';
+
+export interface OAuthSectionProps {
+  sourceUrl?: string;
+  /** Disables every provider button, e.g. while the email form is submitting. */
+  disabled?: boolean;
+  /** A provider sign-in that could not start: the sentence to show under the form field. */
+  onError?: (message: string) => void;
+  /** Called after the notice closed because the visitor chose email: put the cursor in the email field. */
+  onUseEmail: () => void;
+}
+
+/**
+ * Everything provider sign-in puts above the email form, in order: the failure
+ * notice (if the last round trip failed), the buttons, the "or" divider.
+ *
+ * Reads the server's provider list and the notice from the form context. While
+ * the list loads it holds the room the buttons will take, so the email field
+ * does not jump; with no providers it renders nothing.
+ */
+function OAuthSectionRaw({ sourceUrl, disabled, onError, onUseEmail }: OAuthSectionProps) {
+  const { oauth, oauthNotice, setOAuthNotice } = useAuthFormContext();
+
+  const dismissNotice = useCallback(() => setOAuthNotice(null), [setOAuthNotice]);
+  const useEmail = useCallback(() => {
+    setOAuthNotice(null);
+    onUseEmail();
+  }, [setOAuthNotice, onUseEmail]);
+
+  return (
+    <>
+      {oauthNotice && (
+        <OAuthNotice failure={oauthNotice} sourceUrl={sourceUrl} onDismiss={dismissNotice} onUseEmail={useEmail} />
+      )}
+
+      {oauth.providers.length > 0 && (
+        <>
+          <OAuthButtons providers={oauth.providers} sourceUrl={sourceUrl} disabled={disabled} onError={onError} />
+          <AuthDivider />
+        </>
+      )}
+      {!oauth.isReady && <div className="auth-oauth-reserve" aria-hidden="true" />}
+    </>
+  );
+}
+
+export const OAuthSection = memo(OAuthSectionRaw);

package/src/layouts/AuthLayout/components/oauth/buttons/OAuthButtonList.test.tsx

@@ -0,0 +1,52 @@
+// @vitest-environment jsdom
+import React, { act } from 'react';
+import { createRoot } from 'react-dom/client';
+import { describe, expect, it, vi } from 'vitest';
+
+import { OAuthButtonList, type OAuthButtonListProps } from './OAuthButtonList';
+
+vi.mock('@djangocfg/i18n', () => ({
+  useAppT: () => (key: string, params?: Record<string, string>) =>
+    key === 'layouts.auth.identifier.oauth.continueWith' ? `Continue with ${params?.provider}` : key,
+}));
+
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+function render(props: Partial<OAuthButtonListProps> = {}) {
+  const host = document.createElement('div');
+  const root = createRoot(host);
+  const onSelect = vi.fn();
+  act(() => root.render(<OAuthButtonList providers={['github', 'google']} onSelect={onSelect} {...props} />));
+  return { group: host.querySelector('[role="group"]')!, buttons: [...host.querySelectorAll('button')], onSelect };
+}
+
+describe('OAuthButtonList', () => {
+  it('renders one named button per provider inside a labelled group', () => {
+    const { group, buttons } = render();
+    expect(group.getAttribute('aria-label')).toBe('layouts.auth.identifier.oauth.groupLabel');
+    expect(buttons.map((b) => b.textContent)).toEqual(['Continue with GitHub', 'Continue with Google']);
+  });
+
+  it('reports the clicked provider', () => {
+    const { buttons, onSelect } = render();
+    act(() => buttons[1]!.click());
+    expect(onSelect).toHaveBeenCalledExactlyOnceWith('google');
+  });
+
+  it('shows progress on one provider and disables the other', () => {
+    const { buttons } = render({ loadingProvider: 'github' });
+    expect(buttons[0]!.getAttribute('aria-busy')).toBe('true');
+    expect(buttons[0]!.disabled).toBe(true);
+    expect(buttons[1]!.getAttribute('aria-busy')).toBeNull();
+    expect(buttons[1]!.disabled).toBe(true);
+  });
+
+  it('disables everything when told to, and nothing otherwise', () => {
+    expect(render({ disabled: true }).buttons.every((b) => b.disabled)).toBe(true);
+    expect(render().buttons.every((b) => !b.disabled)).toBe(true);
+  });
+
+  it('renders nothing but the group for an empty list', () => {
+    expect(render({ providers: [] }).buttons).toEqual([]);
+  });
+});

package/src/layouts/AuthLayout/components/oauth/buttons/OAuthButtonList.tsx

@@ -0,0 +1,49 @@
+'use client';
+
+import React, { memo } from 'react';
+
+import type { OAuthProviderId } from '@djangocfg/api/auth';
+import { useAppT } from '@djangocfg/i18n';
+
+import { OAUTH_PROVIDERS } from '../providers/registry';
+import { OAuthProviderButton } from './OAuthProviderButton';
+
+export interface OAuthButtonListProps {
+  providers: readonly OAuthProviderId[];
+  /** The provider whose flow is in flight: it shows progress, the others are disabled. */
+  loadingProvider?: OAuthProviderId | null;
+  /** Disables every button, e.g. while the email form is submitting. */
+  disabled?: boolean;
+  onSelect: (provider: OAuthProviderId) => void;
+}
+
+/**
+ * The provider buttons as a labelled group, one per provider, stacked at full
+ * width (a column holds at 320px and in long translations). Stateless: the
+ * flow lives in `OAuthButtons`, which keeps this list easy to render in any state.
+ */
+function OAuthButtonListRaw({ providers, loadingProvider = null, disabled = false, onSelect }: OAuthButtonListProps) {
+  const t = useAppT();
+  const busy = loadingProvider !== null;
+
+  return (
+    <div className="auth-oauth" role="group" aria-label={t('layouts.auth.identifier.oauth.groupLabel')}>
+      {providers.map((id) => {
+        const { name, Icon } = OAUTH_PROVIDERS[id];
+        return (
+          <OAuthProviderButton
+            key={id}
+            Icon={Icon}
+            label={t('layouts.auth.identifier.oauth.continueWith', { provider: name })}
+            data-provider={id}
+            loading={loadingProvider === id}
+            disabled={disabled || (busy && loadingProvider !== id)}
+            onClick={() => onSelect(id)}
+          />
+        );
+      })}
+    </div>
+  );
+}
+
+export const OAuthButtonList = memo(OAuthButtonListRaw);

package/src/layouts/AuthLayout/components/oauth/buttons/OAuthButtons.tsx

@@ -0,0 +1,44 @@
+'use client';
+
+import React, { memo, useCallback, useRef } from 'react';
+
+import { type OAuthProviderId, useOAuthLogin } from '@djangocfg/api/auth';
+
+import { useOAuthErrorText } from '../errors/useOAuthErrorText';
+import { OAuthButtonList } from './OAuthButtonList';
+
+export interface OAuthButtonsProps {
+  providers: readonly OAuthProviderId[];
+  sourceUrl?: string;
+  /** Disables every button, e.g. while the email form is submitting. */
+  disabled?: boolean;
+  /** Receives the visitor-facing sentence for a sign-in that could not start. */
+  onError?: (message: string) => void;
+}
+
+/**
+ * The provider buttons wired to `useOAuthLogin`: a click starts that
+ * provider's flow, progress shows on the one clicked and the rest are disabled
+ * until the page leaves or the start fails.
+ */
+function OAuthButtonsRaw({ providers, sourceUrl, disabled, onError }: OAuthButtonsProps) {
+  const errorText = useOAuthErrorText();
+  const startedRef = useRef<OAuthProviderId | null>(null);
+
+  const { start, loadingProvider } = useOAuthLogin({
+    sourceUrl,
+    onError: (message, code) => onError?.(errorText(code, message, startedRef.current)),
+  });
+
+  const handleSelect = useCallback(
+    (id: OAuthProviderId) => {
+      startedRef.current = id;
+      void start(id);
+    },
+    [start],
+  );
+
+  return <OAuthButtonList providers={providers} loadingProvider={loadingProvider} disabled={disabled} onSelect={handleSelect} />;
+}
+
+export const OAuthButtons = memo(OAuthButtonsRaw);

package/src/layouts/AuthLayout/components/oauth/buttons/OAuthProviderButton.test.tsx

@@ -0,0 +1,56 @@
+// @vitest-environment jsdom
+import React, { act } from 'react';
+import { createRoot } from 'react-dom/client';
+import { describe, expect, it } from 'vitest';
+
+import { OAUTH_PROVIDERS } from '../providers/registry';
+import { OAuthProviderButton } from './OAuthProviderButton';
+
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+function render(state: { loading?: boolean; disabled?: boolean } = {}) {
+  const host = document.createElement('div');
+  const root = createRoot(host);
+  act(() =>
+    root.render(
+      <>
+        <OAuthProviderButton Icon={OAUTH_PROVIDERS.github.Icon} label="GitHub" {...state} />
+        <OAuthProviderButton Icon={OAUTH_PROVIDERS.google.Icon} label="Google" {...state} />
+      </>,
+    ),
+  );
+  return [...host.querySelectorAll('button')];
+}
+
+describe('OAuthProviderButton', () => {
+  it('gives every provider the same classes', () => {
+    const [a, b] = render();
+    expect(a!.className).toBe(b!.className);
+    expect(a!.className).toContain('hover:bg-accent');
+    expect(a!.querySelector('[data-slot="oauth-icon"] svg')).not.toBeNull();
+  });
+
+  it('hides the mark from assistive tech: the label carries the name', () => {
+    const [a] = render();
+    expect(a!.querySelector('[data-slot="oauth-icon"]')!.getAttribute('aria-hidden')).toBe('true');
+    expect(a!.textContent).toBe('GitHub');
+  });
+
+  it('marks loading as busy and disabled, without the provider icon', () => {
+    for (const b of render({ loading: true })) {
+      expect(b.getAttribute('aria-busy')).toBe('true');
+      expect(b.disabled).toBe(true);
+      expect(b.querySelector('[data-slot="oauth-icon"]')).toBeNull();
+    }
+  });
+
+  it('disables both the same way', () => {
+    for (const b of render({ disabled: true })) expect(b.disabled).toBe(true);
+  });
+
+  it('lets a long label wrap instead of clipping it', () => {
+    const [a] = render();
+    expect(a!.className).toContain('whitespace-normal');
+    expect(a!.className).toContain('h-auto');
+  });
+});

package/src/layouts/AuthLayout/components/oauth/buttons/OAuthProviderButton.tsx

@@ -0,0 +1,51 @@
+'use client';
+
+import React, { memo } from 'react';
+
+import { Button } from '@djangocfg/ui-core/components';
+import { cn } from '@djangocfg/ui-core/lib';
+
+export interface OAuthProviderButtonProps
+  extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'children'> {
+  /** Provider mark (an svg component); hidden while loading. */
+  Icon: React.FC;
+  label: string;
+  loading?: boolean;
+}
+
+/**
+ * The one button every OAuth provider uses. Border, height, radius, type,
+ * hover, focus, active, disabled and loading are the same for all; only the
+ * icon and the label change. Theme tokens only, so it follows light and dark.
+ *
+ * Full width, at least `--auth-oauth-height` tall (above the 44px touch
+ * minimum). The label may wrap to a second line on a narrow screen or in a
+ * long translation; the button grows instead of clipping it.
+ */
+function OAuthProviderButtonRaw({ Icon, label, loading = false, className, ...props }: OAuthProviderButtonProps) {
+  return (
+    <Button
+      type="button"
+      variant="outline"
+      loading={loading}
+      aria-busy={loading || undefined}
+      className={cn(
+        'h-auto min-h-[var(--auth-oauth-height)] w-full gap-2.5 whitespace-normal px-4 py-2 text-center text-sm font-medium shadow-none',
+        'hover:bg-accent hover:text-accent-foreground active:bg-accent/70',
+        'focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background',
+        'disabled:opacity-50',
+        className,
+      )}
+      {...props}
+    >
+      {!loading && (
+        <span data-slot="oauth-icon" className="inline-flex shrink-0" aria-hidden="true">
+          <Icon />
+        </span>
+      )}
+      {label}
+    </Button>
+  );
+}
+
+export const OAuthProviderButton = memo(OAuthProviderButtonRaw);

package/src/layouts/AuthLayout/components/oauth/{OAuthCallback.tsx → callback/OAuthCallback.tsx}

@@ -1,19 +1,17 @@
 'use client';
 
-import { Loader2 } from 'lucide-react';
 import { useSearchParams } from 'next/navigation';
 import React, { memo, useCallback, useEffect, useRef, useState } from 'react';
 
 import {
     beginTwoFactorChallenge, clearOAuthAttempt, isOAuthProviderId, type OAuthFailureCode, useOAuthLogin
 } from '@djangocfg/api/auth';
-import { useAppT } from '@djangocfg/i18n';
-import { Card, CardDescription, CardHeader, CardTitle } from '@djangocfg/ui-core/components';
 
-import { useAuthFormContext } from '../../context';
-import { readOAuthCallback, stripOAuthCallbackParams } from './oauthCallbackParams';
-import { useOAuthErrorText } from './oauthErrors';
-import { describeOAuthFailure } from './oauthNoticeCopy';
+import { useAuthFormContext } from '../../../context';
+import { describeOAuthFailure } from '../errors/errorCopy';
+import { useOAuthErrorText } from '../errors/useOAuthErrorText';
+import { readOAuthCallback, stripOAuthCallbackParams } from './callbackParams';
+import { OAuthCallbackOverlay } from './OAuthCallbackOverlay';
 
 export interface OAuthCallbackProps {
   /** `user` is the provider callback's user payload, untyped upstream — narrow it before reading fields. */
@@ -43,7 +41,6 @@ type CallbackStatus = 'idle' | 'processing' | 'challenge';
 function OAuthCallbackRaw({ onSuccess, onError, redirectUrl }: OAuthCallbackProps) {
   const searchParams = useSearchParams();
   const { setStep, setOAuthNotice } = useAuthFormContext();
-  const t = useAppT();
   const errorText = useOAuthErrorText();
 
   const [status, setStatus] = useState<CallbackStatus>('idle');
@@ -58,7 +55,7 @@ function OAuthCallbackRaw({ onSuccess, onError, redirectUrl }: OAuthCallbackProp
       // Cancel is not an error: the visitor is simply back at the form.
       if (describeOAuthFailure(code)) setOAuthNotice({ provider: providerId, code });
       setStatus('idle');
-      onError?.(errorText(code, message));
+      onError?.(errorText(code, message, providerId));
     },
     [errorText, setOAuthNotice, onError],
   );
@@ -107,30 +104,7 @@ function OAuthCallbackRaw({ onSuccess, onError, redirectUrl }: OAuthCallbackProp
 
   // Success is the layout's success screen (setStep('success')), a failure is
   // the notice on the form; this overlay covers only the wait for the exchange.
-  return (
-    <div className="fixed inset-0 bg-background/80 backdrop-blur-sm z-50 flex items-center justify-center">
-      <Card className="w-full max-w-md mx-4 shadow-lg">
-        <CardHeader className="text-center">
-          <div role="status" aria-live="polite">
-            <div className="mx-auto w-12 h-12 bg-primary/10 rounded-full flex items-center justify-center mb-4">
-              <Loader2 className="w-6 h-6 text-primary animate-spin" aria-hidden="true" />
-            </div>
-            <CardTitle>{t('layouts.auth.oauth.signingIn')}</CardTitle>
-            <CardDescription>
-              {t('layouts.auth.oauth.signingInBody', { provider: providerLabel(provider) })}
-            </CardDescription>
-          </div>
-        </CardHeader>
-      </Card>
-    </div>
-  );
+  return <OAuthCallbackOverlay provider={provider} />;
 }
 
-/** Brand names are not translated; an id we do not know is shown as it came. */
-const providerLabel = (id: string | null): string => {
-  if (id === 'github') return 'GitHub';
-  if (id === 'google') return 'Google';
-  return id ?? '';
-};
-
 export const OAuthCallback = memo(OAuthCallbackRaw);

package/src/layouts/AuthLayout/components/oauth/callback/OAuthCallbackOverlay.tsx

@@ -0,0 +1,41 @@
+'use client';
+
+import { Loader2 } from 'lucide-react';
+import React, { memo } from 'react';
+
+import { useAppT } from '@djangocfg/i18n';
+import { Card, CardDescription, CardHeader, CardTitle } from '@djangocfg/ui-core/components';
+
+import { providerName } from '../providers/registry';
+
+export interface OAuthCallbackOverlayProps {
+  /** Provider id as it came back in the URL. */
+  provider: string | null;
+}
+
+/**
+ * Covers the page while the provider's code is exchanged for a session.
+ * A polite live region: the wait is announced once, then the page changes.
+ */
+function OAuthCallbackOverlayRaw({ provider }: OAuthCallbackOverlayProps) {
+  const t = useAppT();
+  return (
+    <div className="fixed inset-0 bg-background/80 backdrop-blur-sm z-50 flex items-center justify-center">
+      <Card className="w-full max-w-md mx-4 shadow-lg">
+        <CardHeader className="text-center">
+          <div role="status" aria-live="polite">
+            <div className="mx-auto w-12 h-12 bg-primary/10 rounded-full flex items-center justify-center mb-4">
+              <Loader2 className="w-6 h-6 text-primary animate-spin" aria-hidden="true" />
+            </div>
+            <CardTitle>{t('layouts.auth.oauth.signingIn')}</CardTitle>
+            <CardDescription>
+              {t('layouts.auth.oauth.signingInBody', { provider: providerName(provider ?? '') })}
+            </CardDescription>
+          </div>
+        </CardHeader>
+      </Card>
+    </div>
+  );
+}
+
+export const OAuthCallbackOverlay = memo(OAuthCallbackOverlayRaw);

package/src/layouts/AuthLayout/components/oauth/{oauthCallbackParams.test.ts → callback/callbackParams.test.ts}

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest';
 
-import { readOAuthCallback, stripOAuthCallbackParams } from './oauthCallbackParams';
+import { readOAuthCallback, stripOAuthCallbackParams } from './callbackParams';
 
 const isProvider = (value: string): value is 'github' | 'google' => value === 'github' || value === 'google';
 const read = (query: string) => readOAuthCallback(new URLSearchParams(query), isProvider);

package/src/layouts/AuthLayout/components/oauth/errors/errorCopy.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from 'vitest';
+
+import { describeOAuthFailure, oauthErrorKey } from './errorCopy';
+
+describe('describeOAuthFailure', () => {
+  it('says nothing when the visitor cancelled', () => {
+    expect(describeOAuthFailure('cancelled')).toBeNull();
+  });
+
+  it('points a staff account at the email code, with a heading', () => {
+    expect(describeOAuthFailure('link_not_allowed')).toEqual({
+      titleKey: 'layouts.auth.oauth.notice.linkNotAllowedTitle',
+      bodyKey: 'layouts.auth.oauth.error.link_not_allowed',
+      action: 'email',
+      developerHintKey: undefined,
+    });
+  });
+
+  it('offers a retry where trying again can help', () => {
+    for (const code of ['invalid_state', 'oauth_exchange_failed', 'provider_unavailable', 'server_error'] as const) {
+      expect(describeOAuthFailure(code)?.action).toBe('retry');
+    }
+  });
+
+  it('offers nothing the visitor cannot act on', () => {
+    expect(describeOAuthFailure('account_inactive')?.action).toBe('none');
+    expect(describeOAuthFailure('rate_limited')?.action).toBe('none');
+  });
+
+  it('treats a missing code as the generic failure', () => {
+    expect(describeOAuthFailure(undefined)).toEqual({
+      titleKey: undefined,
+      bodyKey: 'layouts.auth.oauth.error.generic',
+      action: 'retry',
+      developerHintKey: undefined,
+    });
+  });
+
+  it('says the site is not set up, with a developer hint, when the origin is refused', () => {
+    expect(describeOAuthFailure('origin_not_allowed')).toEqual({
+      titleKey: undefined,
+      bodyKey: 'layouts.auth.oauth.error.not_configured',
+      action: 'email',
+      developerHintKey: 'layouts.auth.oauth.notice.originNotAllowedHint',
+    });
+  });
+
+  it('gives the other configuration faults the same sentence without the hint', () => {
+    for (const code of ['oauth_disabled', 'github_oauth_disabled', 'missing_redirect_uri'] as const) {
+      const copy = describeOAuthFailure(code);
+      expect(copy?.bodyKey).toBe('layouts.auth.oauth.error.not_configured');
+      expect(copy?.developerHintKey).toBeUndefined();
+    }
+  });
+});
+
+describe('oauthErrorKey', () => {
+  it('maps a code to its sentence and an unknown cause to the generic one', () => {
+    expect(oauthErrorKey('rate_limited')).toBe('layouts.auth.oauth.error.rate_limited');
+    expect(oauthErrorKey('server_error')).toBe('layouts.auth.oauth.error.generic');
+    expect(oauthErrorKey(undefined)).toBe('layouts.auth.oauth.error.generic');
+  });
+});