@payez/next-mvp 3.0.0

package/src/components/recovery/InitiateRecoveryStep.tsx

@@ -0,0 +1,68 @@
+'use client';
+
+import React from 'react';
+
+interface Props {
+  email: string;
+  setEmail: (email: string) => void;
+  onSubmit: () => void;
+  loading: boolean;
+}
+
+export function InitiateRecoveryStep({ email, setEmail, onSubmit, loading }: Props) {
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+    onSubmit();
+  };
+
+  return (
+    <div className="rounded-2xl p-8" style={{ background: 'var(--bg-card)', border: '1px solid var(--border-default)' }}>
+      <h2 className="text-xl font-semibold mb-2" style={{ color: 'var(--text-primary)' }}>Account Recovery</h2>
+      <p className="text-sm mb-6" style={{ color: 'var(--text-secondary)' }}>
+        Enter your email address to begin the account recovery process.
+      </p>
+
+      <form onSubmit={handleSubmit} className="space-y-4">
+        <div>
+          <label htmlFor="email" className="block text-sm font-medium mb-1" style={{ color: 'var(--text-primary)' }}>
+            Email Address
+          </label>
+          <input
+            type="email"
+            id="email"
+            value={email}
+            onChange={(e) => setEmail(e.target.value)}
+            required
+            disabled={loading}
+            placeholder="Enter your email address"
+            className="w-full px-3 py-2 rounded focus:ring-2 focus:outline-none disabled:opacity-50"
+            style={{
+              border: '1px solid var(--border-default)',
+              color: 'var(--text-primary)',
+              background: 'var(--bg-default)'
+            }}
+          />
+        </div>
+
+        <button
+          type="submit"
+          disabled={loading || !email}
+          className="w-full py-2 px-4 rounded font-medium focus:outline-none focus:ring-2 disabled:opacity-50 disabled:cursor-not-allowed"
+          style={{
+            border: '1px solid var(--border-default)',
+            color: 'var(--text-primary)',
+            background: 'var(--bg-default)'
+          }}
+        >
+          {loading ? 'Processing...' : 'Continue'}
+        </button>
+
+        <div className="text-center">
+          <a href="/account-auth/login" className="text-sm hover:underline font-medium" style={{ color: 'var(--text-primary)' }}>
+            Back to Login
+          </a>
+        </div>
+      </form>
+    </div>
+  );
+}

package/src/components/recovery/SelectMethodStep.tsx

@@ -0,0 +1,73 @@
+'use client';
+
+import React from 'react';
+import { RecoverySession } from '../../types/recovery';
+
+interface Props {
+  session: RecoverySession;
+  onSelectMethod: (method: 'email' | 'sms' | 'authenticator') => void;
+  loading: boolean;
+}
+
+export function SelectMethodStep({ session, onSelectMethod, loading }: Props) {
+  return (
+    <div className="bg-white border border-gray-300 rounded p-8">
+      <h2 className="text-xl font-semibold text-gray-900 mb-2">Select Verification Method</h2>
+      <p className="text-sm text-gray-600 mb-6">
+        Choose how you would like to receive your verification code.
+      </p>
+
+      <div className="bg-gray-50 border border-gray-200 rounded p-3 mb-6 text-sm">
+        {session.maskedEmail && (
+          <div className="mb-1">
+            <span className="text-gray-600">Email: </span>
+            <span className="text-gray-900 font-medium">{session.maskedEmail}</span>
+          </div>
+        )}
+        {session.maskedPhone && (
+          <div className="mb-1">
+            <span className="text-gray-600">Phone: </span>
+            <span className="text-gray-900 font-medium">{session.maskedPhone}</span>
+          </div>
+        )}
+        {session.hasAuthenticator && (
+          <div className="text-gray-600">
+            * This account has 2FA enabled
+          </div>
+        )}
+      </div>
+
+      <div className="space-y-2">
+        {session.availableMethods.includes('email') && (
+          <button
+            onClick={() => onSelectMethod('email')}
+            disabled={loading}
+            className="w-full py-2 px-4 border border-gray-300 rounded text-gray-900 font-medium hover:bg-gray-50 focus:outline-none focus:ring-2 focus:ring-gray-900 disabled:opacity-50 disabled:cursor-not-allowed"
+          >
+            Send Code via Email
+          </button>
+        )}
+
+        {session.availableMethods.includes('sms') && session.maskedPhone && (
+          <button
+            onClick={() => onSelectMethod('sms')}
+            disabled={loading}
+            className="w-full py-2 px-4 border border-gray-300 rounded text-gray-900 font-medium hover:bg-gray-50 focus:outline-none focus:ring-2 focus:ring-gray-900 disabled:opacity-50 disabled:cursor-not-allowed"
+          >
+            Send Code via SMS
+          </button>
+        )}
+
+        {session.availableMethods.includes('authenticator') && session.hasAuthenticator && (
+          <button
+            onClick={() => onSelectMethod('authenticator')}
+            disabled={loading}
+            className="w-full py-2 px-4 border border-gray-300 rounded text-gray-900 font-medium hover:bg-gray-50 focus:outline-none focus:ring-2 focus:ring-gray-900 disabled:opacity-50 disabled:cursor-not-allowed"
+          >
+            Use Authenticator App
+          </button>
+        )}
+      </div>
+    </div>
+  );
+}

package/src/components/recovery/SetPasswordStep.tsx

@@ -0,0 +1,97 @@
+'use client';
+
+import React, { useState } from 'react';
+
+interface Props {
+  onSubmit: (password: string, confirmPassword: string) => void;
+  loading: boolean;
+}
+
+export function SetPasswordStep({ onSubmit, loading }: Props) {
+  const [password, setPassword] = useState('');
+  const [confirmPassword, setConfirmPassword] = useState('');
+  const [showPassword, setShowPassword] = useState(false);
+  const [showConfirmPassword, setShowConfirmPassword] = useState(false);
+
+  const passwordsMatch = password === confirmPassword && password !== '';
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+    if (passwordsMatch) {
+      onSubmit(password, confirmPassword);
+    }
+  };
+
+  return (
+    <div className="bg-white border border-gray-300 rounded p-8">
+      <h2 className="text-xl font-semibold text-gray-900 mb-2">Set New Password</h2>
+      <p className="text-sm text-gray-600 mb-6">
+        Choose a strong password for your account.
+      </p>
+
+      <form onSubmit={handleSubmit} className="space-y-4">
+        <div>
+          <label htmlFor="password" className="block text-sm font-medium text-gray-900 mb-1">
+            New Password
+          </label>
+          <div className="relative">
+            <input
+              type={showPassword ? 'text' : 'password'}
+              id="password"
+              value={password}
+              onChange={(e) => setPassword(e.target.value)}
+              required
+              disabled={loading}
+              className="w-full px-3 py-2 border border-gray-300 rounded focus:ring-2 focus:ring-gray-900 focus:outline-none disabled:opacity-50 disabled:bg-gray-50 pr-10"
+            />
+            <button
+              type="button"
+              onClick={() => setShowPassword(!showPassword)}
+              className="absolute right-2 top-1/2 -translate-y-1/2 text-gray-600 hover:text-gray-900"
+            >
+              {showPassword ? '👁️' : '👁️‍🗨️'}
+            </button>
+          </div>
+        </div>
+
+        <div>
+          <label htmlFor="confirmPassword" className="block text-sm font-medium text-gray-900 mb-1">
+            Confirm New Password
+          </label>
+          <div className="relative">
+            <input
+              type={showConfirmPassword ? 'text' : 'password'}
+              id="confirmPassword"
+              value={confirmPassword}
+              onChange={(e) => setConfirmPassword(e.target.value)}
+              required
+              disabled={loading}
+              className="w-full px-3 py-2 border border-gray-300 rounded focus:ring-2 focus:ring-gray-900 focus:outline-none disabled:opacity-50 disabled:bg-gray-50 pr-10"
+            />
+            <button
+              type="button"
+              onClick={() => setShowConfirmPassword(!showConfirmPassword)}
+              className="absolute right-2 top-1/2 -translate-y-1/2 text-gray-600 hover:text-gray-900"
+            >
+              {showConfirmPassword ? '👁️' : '👁️‍🗨️'}
+            </button>
+          </div>
+        </div>
+
+        {!passwordsMatch && confirmPassword && (
+          <div className="bg-red-50 border border-red-200 rounded p-3">
+            <p className="text-red-700 text-sm">Passwords do not match</p>
+          </div>
+        )}
+
+        <button
+          type="submit"
+          disabled={!passwordsMatch || loading}
+          className="w-full py-2 px-4 border border-gray-300 rounded text-gray-900 font-medium hover:bg-gray-50 focus:outline-none focus:ring-2 focus:ring-gray-900 disabled:opacity-50 disabled:cursor-not-allowed"
+        >
+          {loading ? 'Resetting Password...' : 'Reset Password'}
+        </button>
+      </form>
+    </div>
+  );
+}

package/src/components/recovery/VerifyCodeStep.tsx

@@ -0,0 +1,90 @@
+'use client';
+
+import React, { useState, useEffect } from 'react';
+
+interface Props {
+  code: string;
+  setCode: (code: string) => void;
+  onSubmit: () => void;
+  onResend: () => void;
+  loading: boolean;
+  maskedDestination?: string;
+}
+
+export function VerifyCodeStep({
+  code,
+  setCode,
+  onSubmit,
+  onResend,
+  loading,
+  maskedDestination
+}: Props) {
+  const [resendCooldown, setResendCooldown] = useState(0);
+
+  useEffect(() => {
+    if (resendCooldown > 0) {
+      const timer = setTimeout(() => setResendCooldown(resendCooldown - 1), 1000);
+      return () => clearTimeout(timer);
+    }
+  }, [resendCooldown]);
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+    onSubmit();
+  };
+
+  const handleResend = () => {
+    onResend();
+    setResendCooldown(30);
+  };
+
+  return (
+    <div className="bg-white border border-gray-300 rounded p-8">
+      <h2 className="text-xl font-semibold text-gray-900 mb-2">Enter Verification Code</h2>
+      {maskedDestination && (
+        <p className="text-sm text-gray-600 mb-6">
+          Enter the 6-digit code sent to <span className="font-medium">{maskedDestination}</span>
+        </p>
+      )}
+
+      <form onSubmit={handleSubmit} className="space-y-4">
+        <div>
+          <label htmlFor="code" className="block text-sm font-medium text-gray-900 mb-1">
+            Verification Code
+          </label>
+          <input
+            type="text"
+            id="code"
+            value={code}
+            onChange={(e) => setCode(e.target.value.replace(/\D/g, '').slice(0, 6))}
+            required
+            disabled={loading}
+            placeholder="000000"
+            maxLength={6}
+            className="w-full px-3 py-2 border border-gray-300 rounded focus:ring-2 focus:ring-gray-900 focus:outline-none disabled:opacity-50 disabled:bg-gray-50 text-center text-2xl tracking-widest font-mono"
+          />
+          <p className="text-xs text-gray-600 mt-1">Code expires in 5 minutes</p>
+        </div>
+
+        <button
+          type="submit"
+          disabled={loading || code.length !== 6}
+          className="w-full py-2 px-4 border border-gray-300 rounded text-gray-900 font-medium hover:bg-gray-50 focus:outline-none focus:ring-2 focus:ring-gray-900 disabled:opacity-50 disabled:cursor-not-allowed"
+        >
+          {loading ? 'Verifying...' : 'Verify Code'}
+        </button>
+
+        <div className="text-center">
+          <button
+            type="button"
+            onClick={handleResend}
+            disabled={loading || resendCooldown > 0}
+            className="text-sm text-gray-900 hover:underline font-medium disabled:opacity-50 disabled:cursor-not-allowed disabled:no-underline"
+          >
+            {resendCooldown > 0 ? `Resend Code (${resendCooldown}s)` : 'Resend Code'}
+          </button>
+        </div>
+      </form>
+    </div>
+  );
+}

package/src/components/reserved/ReservedRecoveryWarning.tsx

@@ -0,0 +1,160 @@
+/**
+ * ReservedRecoveryWarning - Deterministic Reserved Space for Account Lockout Warning
+ * 
+ * PURPOSE: Eliminate layout shift when the lockout warning appears/disappears 
+ * by reserving exact height mathematically.
+ * 
+ * MATHEMATICAL APPROACH:
+ * - Mirrors the complete DOM structure (icon+title row, body paragraph, CTA button)
+ * - Height = Σ(child block heights) + (vertical gaps from space-y-3) + (padding top/bottom from p-4) + (borders)
+ * - Text block heights from exact font-size × line-height and wrapping at actual width
+ * - space-y-3: 0.75rem = 12px gap between children
+ * - p-4: 1rem = 16px padding (top + bottom = 32px)
+ * - border: 1px (top + bottom = 2px)
+ * - Evaluated via offscreen DOM for precision across zoom/browsers
+ * 
+ * CRITICAL: No transitions on height; reserves space even when hidden
+ */
+
+import React from "react";
+import { measureNodeHeightAtWidth, observeForRecalc } from "../../utils/layout/reservedSpace";
+
+type Props = {
+  className?: string;
+  /** Whether the warning is actually visible */
+  show?: boolean;
+  /** Provide the actual copy used so we can measure precise wrapping (localizable) */
+  titleText: string;
+  bodyText: string;
+  actionLabel: string;
+  /** Class recipes that match the live styles */
+  containerClass?: string;
+  titleClass?: string;
+  bodyClass?: string;
+  buttonClass?: string;
+  /** Icon size in px (default 20 for w-5 h-5) */
+  iconSizePx?: number;
+  /** The dynamic warning content */
+  children?: React.ReactNode;
+};
+
+export function ReservedRecoveryWarning({
+  className,
+  show = false,
+  titleText,
+  bodyText,
+  actionLabel,
+  containerClass = "p-4 rounded-lg border",
+  titleClass = "font-medium",
+  bodyClass = "text-sm",
+  buttonClass = "w-full py-2 px-4 text-sm font-medium rounded-md",
+  iconSizePx = 20,
+  children,
+}: Props) {
+  const hostRef = React.useRef<HTMLDivElement | null>(null);
+  
+  // Estimate initial height to prevent collapse during SSR/hydration
+  // Formula: icon (20px) + padding (p-4 = 32px) + border (2px) + title + body + button
+  // Conservative estimate: ~140px for typical warning with button
+  const estimatedMinHeight = 140;
+  
+  const [minH, setMinH] = React.useState<number>(estimatedMinHeight);
+
+  const recompute = React.useCallback(() => {
+    const el = hostRef.current;
+    if (!el) return;
+    const width = el.clientWidth;
+
+    // Wait for layout - clientWidth === 0 means container not laid out yet
+    if (width === 0) {
+      // Retry after next frame when layout is ready
+      requestAnimationFrame(recompute);
+      return;
+    }
+
+    const h = measureNodeHeightAtWidth(() => {
+      // Mirror the real DOM of the warning
+      const outer = document.createElement("div");
+      outer.className = containerClass;
+      
+      // Row: icon + title (flex items-start space-x-3)
+      const headerRow = document.createElement("div");
+      headerRow.className = "flex items-start space-x-3";
+      
+      const icon = document.createElement("div");
+      icon.style.width = iconSizePx + "px";
+      icon.style.height = iconSizePx + "px";
+      icon.style.flexShrink = "0";
+      icon.style.marginTop = "2px"; // mt-0.5 to align with text
+      
+      const titleContainer = document.createElement("div");
+      titleContainer.className = "flex-1";
+      
+      const h3 = document.createElement("h3");
+      h3.className = titleClass;
+      h3.style.margin = "0";
+      h3.style.marginBottom = "8px"; // mb-2
+      h3.textContent = titleText;
+      
+      // Body paragraph
+      const p = document.createElement("p");
+      p.className = bodyClass;
+      p.style.margin = "0";
+      p.style.marginBottom = "12px"; // mb-3
+      p.textContent = bodyText;
+      
+      // Action button
+      const btn = document.createElement("button");
+      btn.className = buttonClass;
+      btn.textContent = actionLabel;
+      
+      titleContainer.appendChild(h3);
+      titleContainer.appendChild(p);
+      titleContainer.appendChild(btn);
+      
+      headerRow.appendChild(icon);
+      headerRow.appendChild(titleContainer);
+      
+      outer.appendChild(headerRow);
+      
+      return outer;
+    }, width);
+
+    setMinH(h);
+  }, [titleText, bodyText, actionLabel, containerClass, titleClass, bodyClass, buttonClass, iconSizePx]);
+
+  React.useLayoutEffect(() => {
+    recompute();
+    if (hostRef.current) {
+      return observeForRecalc(hostRef.current, recompute);
+    }
+  }, [recompute]);
+
+  return (
+    <div 
+      ref={hostRef} 
+      className={className} 
+      style={{ minHeight: minH ? `${minH}px` : undefined, transition: "none" }}
+      data-testid="recovery-warning-wrap"
+    >
+      {show ? children : null}
+    </div>
+  );
+}
+
+export default ReservedRecoveryWarning;
+
+/*
+MATHEMATICAL NOTES (documented per spec):
+- We compute the exact height of the fully-rendered warning box by mirroring its DOM:
+  - Icon+title row (flex items-start space-x-3)
+  - Title (h3 with font-medium)
+  - Body paragraph (text-sm)
+  - CTA button (full-width)
+  
+- Height = Σ(child block heights) + (vertical gaps) + (padding top/bottom from p-4) + (borders)
+- Text block heights come from exact font-size × line-height and wrapping given the actual width
+- This is evaluated via offscreen DOM to preserve precision across zoom/browsers
+- No transitions applied; min-height is a fixed px value at any zoom level
+- Space is reserved even when content is hidden (show=false), eliminating jump
+*/

package/src/components/reserved/ReservedStatusBox.tsx

@@ -0,0 +1,118 @@
+/**
+ * ReservedStatusBox - Deterministic Reserved Space for Status Messages
+ * 
+ * PURPOSE: Eliminate layout shift when status messages (ready/submitting/error/success) 
+ * appear/disappear by reserving exact height mathematically.
+ * 
+ * MATHEMATICAL APPROACH:
+ * - Measures all candidate messages at current container width
+ * - Computes height = max(iconSizePx, text block height) + paddings + borders
+ * - Font metrics from Tailwind: text-sm (0.875rem = 14px), leading-relaxed (1.625)
+ * - Padding from p-3: 0.75rem = 12px (top + bottom = 24px)
+ * - Border from border class: 1px (top + bottom = 2px)
+ * - Sets minHeight to the maximum of all candidates
+ * 
+ * CRITICAL: No transitions on height; exact px value at any zoom level
+ */
+
+import React from "react";
+import { measureNodeHeightAtWidth, observeForRecalc } from "../../utils/layout/reservedSpace";
+
+type Props = {
+  className?: string;
+  /** List of candidate messages representing the longest possible strings for each state */
+  candidates: string[];
+  /** Tailwind classes applied to the live status container (must match for accurate measurement) */
+  containerClass?: string; // e.g., "p-3 text-sm leading-relaxed rounded-md border"
+  /** Icon size in px (default 16 for w-4 h-4) */
+  iconSizePx?: number;
+  /** The dynamic status content */
+  children?: React.ReactNode;
+};
+
+export function ReservedStatusBox({
+  className,
+  candidates,
+  containerClass = "p-3 text-sm leading-relaxed rounded-md border",
+  iconSizePx = 16,
+  children,
+}: Props) {
+  const hostRef = React.useRef<HTMLDivElement | null>(null);
+  
+  // Estimate initial height to prevent collapse during SSR/hydration
+  // Formula: iconSize + padding (p-3 = 24px) + border (2px) = conservative minimum
+  const estimatedMinHeight = iconSizePx + 24 + 2; // ~42px for 16px icon
+  
+  const [minH, setMinH] = React.useState<number>(estimatedMinHeight);
+
+  const recompute = React.useCallback(() => {
+    const el = hostRef.current;
+    if (!el) return;
+    const width = el.clientWidth; // width the status box will render at
+    
+    // Wait for layout - clientWidth === 0 means container not laid out yet
+    if (width === 0) {
+      // Retry after next frame when layout is ready
+      requestAnimationFrame(recompute);
+      return;
+    }
+    
+    // For each candidate, build a DOM subtree matching the live structure and measure its height
+    const heights = candidates.map((msg) =>
+      measureNodeHeightAtWidth(() => {
+        const outer = document.createElement("div");
+        outer.className = containerClass + " flex items-center space-x-2"; // must match live
+        
+        // icon placeholder
+        const icon = document.createElement("div");
+        icon.style.width = iconSizePx + "px";
+        icon.style.height = iconSizePx + "px";
+        icon.style.flexShrink = "0";
+        
+        // message text
+        const span = document.createElement("span");
+        span.className = "flex-1"; // let text wrap if needed
+        span.textContent = msg;
+        
+        outer.appendChild(icon);
+        outer.appendChild(span);
+        return outer;
+      }, width)
+    );
+    
+    const max = Math.max(0, ...heights);
+    setMinH(max);
+  }, [candidates, containerClass, iconSizePx]);
+
+  React.useLayoutEffect(() => {
+    recompute();
+    if (hostRef.current) {
+      return observeForRecalc(hostRef.current, recompute);
+    }
+  }, [recompute]);
+
+  return (
+    <div 
+      ref={hostRef} 
+      className={className} 
+      style={{ minHeight: minH ? `${minH}px` : undefined, transition: "none" }}
+      data-testid="status-wrap"
+    >
+      {children}
+    </div>
+  );
+}
+
+export default ReservedStatusBox;
+
+/*
+MATHEMATICAL NOTES (documented per spec):
+- We force the exact height by measuring the maximum of all candidate messages rendered with:
+  - Font metrics from applied classes: text-sm (font-size), leading-relaxed (line-height)
+  - Padding p-3 (top+bottom = 2 × 12px = 24px)
+  - Border widths from Tailwind's border class (1px top and bottom by default = 2px)
+  - The height is the max of (iconSizePx, text line block height) plus paddings and borders,
+    computed by the browser for precision
+- No transitions applied; min-height is a fixed px value at any zoom level
+- Text wrapping is accounted for by measuring at the actual container width
+*/

package/src/components/ui/BetaBadge.tsx

@@ -0,0 +1,58 @@
+'use client';
+
+import React from 'react';
+
+export interface BetaBadgeProps {
+  /** Text to display (default: 'beta') */
+  text?: string;
+  /** Additional CSS classes */
+  className?: string;
+  /** Badge variant */
+  variant?: 'subtle' | 'outlined' | 'solid';
+}
+
+/**
+ * A subtle badge component for indicating pre-release status.
+ *
+ * Controlled by NEXT_PUBLIC_SHOW_BETA_BADGE env var.
+ * When env var is not 'true', renders nothing.
+ *
+ * @example
+ * ```tsx
+ * // In your header, next to logo
+ * <Logo />
+ * <BetaBadge />
+ *
+ * // Custom text
+ * <BetaBadge text="preview" />
+ *
+ * // Different variant
+ * <BetaBadge variant="outlined" text="coming soon" />
+ * ```
+ */
+export function BetaBadge({
+  text = 'beta',
+  className = '',
+  variant = 'subtle'
+}: BetaBadgeProps) {
+  // Check env var - only render if explicitly enabled
+  if (process.env.NEXT_PUBLIC_SHOW_BETA_BADGE !== 'true') {
+    return null;
+  }
+
+  const baseStyles = 'inline-flex items-center px-2 py-0.5 text-xs font-medium rounded-full lowercase tracking-wide';
+
+  const variantStyles = {
+    subtle: 'bg-gray-100 text-gray-500 dark:bg-gray-800 dark:text-gray-400',
+    outlined: 'border border-gray-300 text-gray-500 dark:border-gray-600 dark:text-gray-400',
+    solid: 'bg-gray-500 text-white dark:bg-gray-600',
+  };
+
+  return (
+    <span className={`${baseStyles} ${variantStyles[variant]} ${className}`}>
+      {text}
+    </span>
+  );
+}
+
+export default BetaBadge;