@djangocfg/layouts 2.1.580 → 2.1.581

package/src/snippets/TwoFactor/TwoFactorChallengeDialog.tsx

@@ -0,0 +1,188 @@
+'use client';
+
+import React, { memo, useCallback, useMemo, useState } from 'react';
+
+import {
+  AUTH_CONSTANTS,
+  endTwoFactorChallenge,
+  useTwoFactorChallenge,
+  useTwoFactorVerify,
+} from '@djangocfg/api/auth';
+import { useAppT } from '@djangocfg/i18n';
+import {
+  Button,
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+  Input,
+  OTPInput,
+} from '@djangocfg/ui-core/components';
+
+export interface TwoFactorChallengeDialogProps {
+  /** Runs once the code is accepted and the session is stored. Without it the dialog navigates itself. */
+  onVerified?: () => void;
+  /** Runs when the user abandons the challenge. */
+  onCancel?: () => void;
+  /** Where the dialog navigates after success when `onVerified` is absent. */
+  redirectUrl?: string;
+}
+
+/**
+ * Second-factor prompt over whatever page started the sign-in.
+ *
+ * Opens when a sign-in step calls `beginTwoFactorChallenge` and owns everything
+ * from there: code entry, backup-code fallback, lockout hints. The sign-in form
+ * does not know it exists.
+ */
+function TwoFactorChallengeDialogRaw(props: TwoFactorChallengeDialogProps) {
+  const challenge = useTwoFactorChallenge();
+  const { onCancel } = props;
+
+  const handleOpenChange = useCallback(
+    (open: boolean) => {
+      if (open) return;
+      endTwoFactorChallenge();
+      onCancel?.();
+    },
+    [onCancel],
+  );
+
+  return (
+    <Dialog open={challenge !== null} onOpenChange={handleOpenChange}>
+      {/* A stray click must not discard a verified password or email code. */}
+      <DialogContent className="max-w-sm" onInteractOutside={(e) => e.preventDefault()}>
+        {challenge && <Challenge key={challenge.sessionId} sessionId={challenge.sessionId} {...props} />}
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+function Challenge({
+  sessionId,
+  onVerified,
+  redirectUrl,
+}: TwoFactorChallengeDialogProps & { sessionId: string }) {
+  const t = useAppT();
+  const [code, setCode] = useState('');
+  const [useBackupCode, setUseBackupCode] = useState(false);
+
+  const verify = useTwoFactorVerify({
+    onSuccess: () => {
+      endTwoFactorChallenge();
+      onVerified?.();
+    },
+    redirectUrl,
+    skipRedirect: Boolean(onVerified),
+  });
+
+  const content = useMemo(
+    () => ({
+      title: t('layouts.auth.twoFactor.title'),
+      subtitle: {
+        totp: t('layouts.auth.twoFactor.subtitle.totp'),
+        backup: t('layouts.auth.twoFactor.subtitle.backup'),
+      },
+      placeholder: t('layouts.auth.twoFactor.placeholder.backup'),
+      button: t('layouts.auth.twoFactor.button'),
+      toggle: {
+        toBackup: t('layouts.auth.twoFactor.toggle.toBackup'),
+        toTotp: t('layouts.auth.twoFactor.toggle.toTotp'),
+      },
+    }),
+    [t],
+  );
+
+  const { isLoading, error, warning, attemptsRemaining, verifyTOTP, verifyBackupCode, clearError } = verify;
+
+  const switchMode = useCallback(() => {
+    setUseBackupCode((prev) => !prev);
+    setCode('');
+    clearError();
+  }, [clearError]);
+
+  const handleTotpComplete = useCallback(
+    (value: string) => {
+      if (!isLoading) void verifyTOTP(sessionId, value);
+    },
+    [isLoading, sessionId, verifyTOTP],
+  );
+
+  const handleSubmit = useCallback(
+    (e: React.FormEvent) => {
+      e.preventDefault();
+      if (isLoading) return;
+      void (useBackupCode ? verifyBackupCode(sessionId, code) : verifyTOTP(sessionId, code));
+    },
+    [code, isLoading, sessionId, useBackupCode, verifyBackupCode, verifyTOTP],
+  );
+
+  const canSubmit = useBackupCode ? code.length > 0 : code.length === AUTH_CONSTANTS.TOTP_LENGTH;
+
+  return (
+    <>
+      <DialogHeader>
+        <DialogTitle>{content.title}</DialogTitle>
+        <DialogDescription>
+          {useBackupCode ? content.subtitle.backup : content.subtitle.totp}
+        </DialogDescription>
+      </DialogHeader>
+
+      <form onSubmit={handleSubmit} className="space-y-4">
+        {useBackupCode ? (
+          <Input
+            value={code}
+            onChange={(e) => setCode(e.target.value.toUpperCase())}
+            placeholder={content.placeholder}
+            disabled={isLoading}
+            maxLength={AUTH_CONSTANTS.BACKUP_CODE_MAX_LENGTH}
+            autoComplete="off"
+            autoFocus
+          />
+        ) : (
+          <div className="flex justify-center">
+            <OTPInput
+              length={AUTH_CONSTANTS.TOTP_LENGTH}
+              validationMode="numeric"
+              pasteBehavior="clean"
+              value={code}
+              onChange={setCode}
+              onComplete={handleTotpComplete}
+              disabled={isLoading}
+              autoFocus
+            />
+          </div>
+        )}
+
+        {warning && <p className="text-sm text-muted-foreground">{warning}</p>}
+        {error && (
+          <p role="alert" className="text-sm text-destructive">
+            {error}
+          </p>
+        )}
+        {attemptsRemaining !== null && attemptsRemaining <= 3 && (
+          <p className="text-sm text-muted-foreground">
+            {attemptsRemaining} attempt{attemptsRemaining === 1 ? '' : 's'} remaining
+          </p>
+        )}
+
+        <Button type="submit" className="w-full" disabled={!canSubmit || isLoading}>
+          {content.button}
+        </Button>
+
+        <Button
+          type="button"
+          variant="link"
+          className="w-full"
+          onClick={switchMode}
+          disabled={isLoading}
+        >
+          {useBackupCode ? content.toggle.toTotp : content.toggle.toBackup}
+        </Button>
+      </form>
+    </>
+  );
+}
+
+export const TwoFactorChallengeDialog = memo(TwoFactorChallengeDialogRaw);

package/src/snippets/TwoFactor/TwoFactorSetup.tsx

@@ -0,0 +1,209 @@
+'use client';
+
+import { Check, Copy } from 'lucide-react';
+import { QRCodeSVG } from 'qrcode.react';
+import React, { memo, useCallback, useEffect, useMemo, useRef, useState } from 'react';
+
+import { AUTH_CONSTANTS, useTwoFactorSetup } from '@djangocfg/api/auth';
+import { useAppT } from '@djangocfg/i18n';
+import {
+  Alert,
+  AlertDescription,
+  Button,
+  Collapsible,
+  CollapsibleContent,
+  CollapsibleTrigger,
+  OTPInput,
+  Preloader,
+} from '@djangocfg/ui-core/components';
+
+const QR_SIZE = 160;
+const COPIED_MS = 2000;
+
+export interface TwoFactorSetupProps {
+  /** Runs when the user dismisses the backup codes — never earlier, or the codes are lost. */
+  onComplete?: () => void;
+  /** Shows a "skip" link on the QR step. */
+  onSkip?: () => void;
+}
+
+function useCopy() {
+  const [copied, setCopied] = useState(false);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  useEffect(() => () => {
+    if (timerRef.current) clearTimeout(timerRef.current);
+  }, []);
+
+  const copy = useCallback(async (text: string) => {
+    try {
+      await navigator.clipboard.writeText(text);
+    } catch {
+      return;
+    }
+    setCopied(true);
+    if (timerRef.current) clearTimeout(timerRef.current);
+    timerRef.current = setTimeout(() => setCopied(false), COPIED_MS);
+  }, []);
+
+  return { copied, copy };
+}
+
+/**
+ * Enable 2FA: QR provisioning, confirmation code, then one-time backup codes.
+ * Self-contained — no sign-in context — so any settings surface can mount it.
+ */
+function TwoFactorSetupRaw({ onComplete, onSkip }: TwoFactorSetupProps) {
+  const t = useAppT();
+  const { copied, copy } = useCopy();
+  const [confirmCode, setConfirmCode] = useState('');
+
+  const { isLoading, error, setupData, backupCodes, backupCodesWarning, setupStep, startSetup, confirmSetup } =
+    useTwoFactorSetup({ onError: () => {} });
+
+  useEffect(() => {
+    if (setupStep === 'idle') void startSetup();
+  }, [setupStep, startSetup]);
+
+  const content = useMemo(
+    () => ({
+      loading: t('layouts.auth.setup.loading.button'),
+      qr: {
+        title: t('layouts.auth.setup.qrCode.title'),
+        subtitle: t('layouts.auth.setup.qrCode.subtitle'),
+        manualEntry: t('layouts.auth.setup.qrCode.manualEntry'),
+        confirmPrompt: t('layouts.auth.setup.qrCode.confirmPrompt'),
+        button: t('layouts.auth.setup.qrCode.button'),
+        skip: t('layouts.auth.setup.qrCode.skip'),
+      },
+      done: {
+        title: t('layouts.auth.setup.complete.title'),
+        subtitle: t('layouts.auth.setup.complete.subtitle'),
+        instruction: t('layouts.auth.setup.complete.instruction'),
+        copyAll: t('layouts.auth.setup.complete.copyAll'),
+        copied: t('layouts.auth.setup.complete.copied'),
+        button: t('layouts.auth.setup.complete.done'),
+      },
+    }),
+    [t],
+  );
+
+  const handleConfirm = useCallback(
+    (e: React.FormEvent) => {
+      e.preventDefault();
+      void confirmSetup(confirmCode);
+    },
+    [confirmCode, confirmSetup],
+  );
+
+  if (setupStep === 'complete' && backupCodes) {
+    return (
+      <div className="w-full max-w-sm space-y-4">
+        <Header title={content.done.title} subtitle={content.done.subtitle} />
+        {backupCodesWarning && (
+          <Alert>
+            <AlertDescription>{backupCodesWarning}</AlertDescription>
+          </Alert>
+        )}
+        <div className="grid grid-cols-2 gap-1.5 rounded-lg border border-dashed border-border bg-muted/40 p-3.5">
+          {backupCodes.map((code) => (
+            <code key={code} className="p-1.5 text-center font-mono text-[13px] tracking-wide">
+              {code}
+            </code>
+          ))}
+        </div>
+        <p className="text-center text-sm text-muted-foreground">{content.done.instruction}</p>
+        <Button
+          type="button"
+          variant="outline"
+          className="w-full"
+          onClick={() => void copy(backupCodes.join('\n'))}
+        >
+          {copied ? <Check className="size-4" /> : <Copy className="size-4" />}
+          {copied ? content.done.copied : content.done.copyAll}
+        </Button>
+        <Button type="button" className="w-full" onClick={() => onComplete?.()}>
+          {content.done.button}
+        </Button>
+      </div>
+    );
+  }
+
+  if (!setupData) {
+    return <Preloader variant="inline" text={content.loading} className="py-4" />;
+  }
+
+  return (
+    <form onSubmit={handleConfirm} className="w-full max-w-sm space-y-4">
+      <Header title={content.qr.title} subtitle={content.qr.subtitle} />
+
+      <div className="flex justify-center">
+        {/* White plate: authenticator apps need dark-on-light contrast in both themes. */}
+        <div className="rounded-lg bg-white p-3.5 shadow-sm">
+          <QRCodeSVG value={setupData.provisioningUri} size={QR_SIZE} level="M" marginSize={0} />
+        </div>
+      </div>
+
+      <Collapsible className="flex flex-col items-center">
+        <CollapsibleTrigger asChild>
+          <Button type="button" variant="link" size="sm">
+            {content.qr.manualEntry}
+          </Button>
+        </CollapsibleTrigger>
+        <CollapsibleContent className="flex flex-col items-center gap-2 p-3">
+          <code className="break-all rounded bg-muted px-3.5 py-2 text-center font-mono text-[13px] tracking-wider">
+            {setupData.secret}
+          </code>
+          <Button type="button" variant="link" size="sm" onClick={() => void copy(setupData.secret)}>
+            {copied ? <Check className="size-4" /> : <Copy className="size-4" />}
+            {copied ? content.done.copied : 'Copy'}
+          </Button>
+        </CollapsibleContent>
+      </Collapsible>
+
+      <p className="text-center text-sm text-muted-foreground">{content.qr.confirmPrompt}</p>
+
+      <div className="flex justify-center">
+        <OTPInput
+          length={AUTH_CONSTANTS.TOTP_LENGTH}
+          validationMode="numeric"
+          pasteBehavior="clean"
+          value={confirmCode}
+          onChange={setConfirmCode}
+          disabled={isLoading}
+        />
+      </div>
+
+      {error && (
+        <p role="alert" className="text-center text-sm text-destructive">
+          {error}
+        </p>
+      )}
+
+      <Button
+        type="submit"
+        className="w-full"
+        disabled={isLoading || confirmCode.length !== AUTH_CONSTANTS.TOTP_LENGTH}
+      >
+        {content.qr.button}
+      </Button>
+
+      {onSkip && (
+        <Button type="button" variant="link" className="w-full" onClick={onSkip} disabled={isLoading}>
+          {content.qr.skip}
+        </Button>
+      )}
+    </form>
+  );
+}
+
+function Header({ title, subtitle }: { title: string; subtitle: string }) {
+  return (
+    <div className="space-y-1 text-center">
+      <h3 className="text-base font-semibold">{title}</h3>
+      <p className="text-sm text-muted-foreground">{subtitle}</p>
+    </div>
+  );
+}
+
+export const TwoFactorSetup = memo(TwoFactorSetupRaw);

package/src/snippets/TwoFactor/index.ts

@@ -0,0 +1,2 @@
+export { TwoFactorChallengeDialog, type TwoFactorChallengeDialogProps } from './TwoFactorChallengeDialog';
+export { TwoFactorSetup, type TwoFactorSetupProps } from './TwoFactorSetup';

package/src/snippets/index.ts

@@ -6,6 +6,7 @@
 
 export * from './Breadcrumbs';
 export * from './AuthDialog';
+export * from './TwoFactor';
 export * from './Analytics';
 
 // Devtools lives in @djangocfg/devtools — re-exported here for convenience

package/src/testing/MockAuthFormProvider.tsx

@@ -24,15 +24,9 @@ export interface MockAuthFormProviderProps extends Partial<AuthLayoutConfig> {
   isLoading?: boolean;
   acceptedTerms?: boolean;
   error?: string;
-  twoFactorSessionId?: string | null;
-  shouldPrompt2FA?: boolean;
-  twoFactorCode?: string;
-  useBackupCode?: boolean;
   rateLimitSeconds?: number;
+  resendSeconds?: number;
   webmail?: WebmailLink | null;
-  is2FALoading?: boolean;
-  twoFactorWarning?: string | null;
-  twoFactorAttemptsRemaining?: number | null;
 }
 
 function formatRateLimit(seconds: number): string {
@@ -65,15 +59,9 @@ export const MockAuthFormProvider: React.FC<MockAuthFormProviderProps> = ({
   isLoading: initialLoading = false,
   acceptedTerms: initialAcceptedTerms = false,
   error: initialError = '',
-  twoFactorSessionId: initialTwoFactorSessionId = null,
-  shouldPrompt2FA: initialShouldPrompt2FA = false,
-  twoFactorCode: initialTwoFactorCode = '',
-  useBackupCode: initialUseBackupCode = false,
   rateLimitSeconds: initialRateLimitSeconds = 0,
+  resendSeconds: initialResendSeconds = 0,
   webmail: initialWebmail = null,
-  is2FALoading = false,
-  twoFactorWarning = null,
-  twoFactorAttemptsRemaining = null,
 }) => {
   const [step, setStep] = useState<AuthStep>(initialStep);
   const [identifier, setIdentifier] = useState(initialIdentifier);
@@ -84,11 +72,8 @@ export const MockAuthFormProvider: React.FC<MockAuthFormProviderProps> = ({
   const [rememberMe, setRememberMe] = useState(false);
   const [marketingConsent, setMarketingConsent] = useState<boolean | null>(null);
   const [error, setError] = useState(initialError);
-  const [twoFactorSessionId, setTwoFactorSessionId] = useState<string | null>(initialTwoFactorSessionId);
-  const [shouldPrompt2FA, setShouldPrompt2FA] = useState(initialShouldPrompt2FA);
-  const [twoFactorCode, setTwoFactorCode] = useState(initialTwoFactorCode);
-  const [useBackupCode, setUseBackupCode] = useState(initialUseBackupCode);
   const [rateLimitSeconds, setRateLimitSeconds] = useState(initialRateLimitSeconds);
+  const [resendSeconds, setResendSeconds] = useState(initialResendSeconds);
   const [webmail, setWebmail] = useState<WebmailLink | null>(initialWebmail);
 
   const isAutoSubmittingFromUrl = useRef(false);
@@ -109,13 +94,11 @@ export const MockAuthFormProvider: React.FC<MockAuthFormProviderProps> = ({
       marketingConsent,
       step,
       error,
-      twoFactorSessionId,
-      shouldPrompt2FA,
-      twoFactorCode,
-      useBackupCode,
       rateLimitSeconds,
       isRateLimited: rateLimitSeconds > 0,
       rateLimitLabel: formatRateLimit(rateLimitSeconds),
+      resendSeconds,
+      resendLabel: formatRateLimit(resendSeconds),
       webmail,
 
       // State handlers
@@ -129,11 +112,8 @@ export const MockAuthFormProvider: React.FC<MockAuthFormProviderProps> = ({
       clearError: () => setError(''),
       setStep,
       setIsLoading,
-      setTwoFactorSessionId,
-      setShouldPrompt2FA,
-      setTwoFactorCode,
-      setUseBackupCode,
       startRateLimitCountdown: (seconds: number) => setRateLimitSeconds(seconds),
+      startResendCountdown: (seconds: number) => setResendSeconds(seconds),
       setWebmail,
 
       // Submit handlers — all no-op (preventDefault only) so the visible
@@ -145,9 +125,6 @@ export const MockAuthFormProvider: React.FC<MockAuthFormProviderProps> = ({
       handleResendOTP: async () => {},
       handleBackToIdentifier: () => setStep('identifier'),
       forceOTPStep: () => setStep('otp'),
-      handle2FASubmit: async (e) => stop(e),
-      handleUseBackupCode: () => setUseBackupCode(true),
-      handleUseTOTP: () => setUseBackupCode(false),
 
       // Validation — accept anything that looks email-ish or 10+ digits.
       validateIdentifier: (id: string) =>
@@ -156,11 +133,6 @@ export const MockAuthFormProvider: React.FC<MockAuthFormProviderProps> = ({
       // Auto-submit ref
       isAutoSubmittingFromUrl,
 
-      // 2FA state (read-only here; tests/stories override via props)
-      is2FALoading,
-      twoFactorWarning,
-      twoFactorAttemptsRemaining,
-
       // Layout config
       sourceUrl,
       supportUrl,
@@ -180,15 +152,9 @@ export const MockAuthFormProvider: React.FC<MockAuthFormProviderProps> = ({
     marketingConsent,
     step,
     error,
-    twoFactorSessionId,
-    shouldPrompt2FA,
-    twoFactorCode,
-    useBackupCode,
     rateLimitSeconds,
+    resendSeconds,
     webmail,
-    is2FALoading,
-    twoFactorWarning,
-    twoFactorAttemptsRemaining,
     sourceUrl,
     supportUrl,
     termsUrl,

package/src/testing/index.ts

@@ -31,6 +31,8 @@ export { AuthBrandPanel } from '../layouts/AuthLayout/components/shared';
 export {
   IdentifierStep,
   OTPStep,
-  TwoFactorStep,
-  SetupStep,
 } from '../layouts/AuthLayout/components/steps';
+
+// The 2FA challenge is its own surface; stories open it by beginning a challenge.
+export { TwoFactorChallengeDialog, TwoFactorSetup } from '../snippets/TwoFactor';
+export { beginTwoFactorChallenge, endTwoFactorChallenge } from '@djangocfg/api/auth';

package/src/layouts/AuthLayout/components/steps/SetupStep/SetupComplete.tsx

@@ -1,86 +0,0 @@
-'use client';
-
-import { Check, Copy } from 'lucide-react';
-import React, { memo, useMemo } from 'react';
-
-import { useAppT } from '@djangocfg/i18n';
-
-import { useCopyToClipboard } from '../../../hooks';
-import { AuthButton, AuthContainer, AuthHeader } from '../../shared';
-
-interface SetupCompleteProps {
-  backupCodes: string[];
-  backupCodesWarning?: string | null;
-  onDone: () => void;
-}
-
-/**
- * SetupComplete - Backup codes display after 2FA setup.
- *
- * Memoised: re-renders only when `backupCodes` array reference,
- * `backupCodesWarning`, or `onDone` change. The array content is
- * compared by reference — the parent should not recreate the array
- * on every render.
- */
-function SetupCompleteRaw({
-  backupCodes,
-  backupCodesWarning,
-  onDone,
-}: SetupCompleteProps) {
-  const { copied, copy } = useCopyToClipboard();
-  const t = useAppT();
-  const content = useMemo(() => ({
-    title: t('layouts.auth.setup.complete.title'),
-    subtitle: t('layouts.auth.setup.complete.subtitle'),
-    instruction: t('layouts.auth.setup.complete.instruction'),
-    copyAll: t('layouts.auth.setup.complete.copyAll'),
-    copied: t('layouts.auth.setup.complete.copied'),
-    done: t('layouts.auth.setup.complete.done'),
-  }), [t]);
-
-  const handleCopyAll = () => {
-    copy(backupCodes.join('\n'));
-  };
-
-  return (
-    <AuthContainer step="2fa-setup">
-      <AuthHeader title={content.title} subtitle={content.subtitle} />
-
-      <div className="auth-form-group">
-        {backupCodesWarning && (
-          <div className="auth-dev-notice">{backupCodesWarning}</div>
-        )}
-
-        <div className="auth-backup-codes">
-          {backupCodes.map((code, index) => (
-            <div key={index} className="auth-backup-code">
-              {code}
-            </div>
-          ))}
-        </div>
-
-        <p className="auth-instruction">{content.instruction}</p>
-
-        <AuthButton type="button" variant="secondary" onClick={handleCopyAll}>
-          {copied ? (
-            <>
-              <Check className="w-4 h-4" />
-              {content.copied}
-            </>
-          ) : (
-            <>
-              <Copy className="w-4 h-4" />
-              {content.copyAll}
-            </>
-          )}
-        </AuthButton>
-
-        <AuthButton type="button" onClick={onDone}>
-          {content.done}
-        </AuthButton>
-      </div>
-    </AuthContainer>
-  );
-}
-
-export const SetupComplete = memo(SetupCompleteRaw);

package/src/layouts/AuthLayout/components/steps/SetupStep/SetupLoading.tsx

@@ -1,36 +0,0 @@
-'use client';
-
-import React, { memo, useMemo } from 'react';
-
-import { useAppT } from '@djangocfg/i18n';
-import { Preloader } from '@djangocfg/ui-core/components';
-
-import { AuthContainer, AuthHeader } from '../../shared';
-
-/**
- * SetupLoading - Loading state for 2FA setup.
- *
- * Uses the ui-core Preloader (text-primary spinner) so the "Setting up…"
- * indicator stays clearly visible instead of the near-invisible chip spinner.
- *
- * Memoised: no props; pure translation-driven component. Prevents
- * re-renders when parent orchestrators re-render for unrelated reasons.
- */
-function SetupLoadingRaw() {
-  const t = useAppT();
-  const content = useMemo(() => ({
-    title: t('layouts.auth.setup.loading.title'),
-    button: t('layouts.auth.setup.loading.button'),
-  }), [t]);
-
-  return (
-    <AuthContainer step="2fa-setup">
-      <AuthHeader title={content.title} />
-      <div className="auth-form-group">
-        <Preloader variant="inline" text={content.button} className="py-4" />
-      </div>
-    </AuthContainer>
-  );
-}
-
-export const SetupLoading = memo(SetupLoadingRaw);