@insforge/react 0.3.2 → 0.3.3

package/README.md

@@ -1,604 +1,604 @@
-# @insforge/react
-
-**Complete authentication solution for React applications.** Production-ready components with full business logic included.
-
-## Why @insforge/react?
-
-✅ **5-Minute Setup** - One provider + one line of router config = done  
-✅ **Built-in Auth UI** - Use deployed auth pages (like Next.js middleware)  
-✅ **Framework Agnostic** - Works with any React framework  
-✅ **Full TypeScript** - Complete type safety out of the box  
-✅ **Fully Customizable** - Deep styling control when you need it
-
----
-
-## Quick Start
-
-Get authentication working in your React app in 5 minutes.
-
-### 1. Install
-
-```bash
-npm install @insforge/react
-# or
-yarn add @insforge/react
-# or
-pnpm add @insforge/react
-```
-
-### 2. Setup Provider
-
-Wrap your app with `InsforgeProvider`:
-
-```tsx
-// src/main.tsx (Vite) or src/index.tsx (CRA)
-import { StrictMode } from 'react';
-import { createRoot } from 'react-dom/client';
-import { InsforgeProvider } from '@insforge/react';
-import '@insforge/react/styles.css';
-import App from './App';
-
-createRoot(document.getElementById('root')!).render(
-  <StrictMode>
-    <InsforgeProvider baseUrl={import.meta.env.VITE_INSFORGE_BASE_URL}>
-      <App />
-    </InsforgeProvider>
-  </StrictMode>
-);
-```
-
-### 3. Configure Router (Built-in Auth)
-
-```tsx
-// src/App.tsx
-import { createBrowserRouter, RouterProvider } from 'react-router-dom';
-import { getInsforgeRoutes } from '@insforge/react/router';
-import Home from './pages/Home';
-import Dashboard from './pages/Dashboard';
-
-const router = createBrowserRouter([
-  { path: '/', element: <Home /> },
-  
-  ...getInsforgeRoutes({
-    baseUrl: import.meta.env.VITE_INSFORGE_BASE_URL,
-    builtInAuth: true
-  }),
-  
-  { path: '/dashboard', element: <Dashboard /> }
-]);
-
-export default function App() {
-  return <RouterProvider router={router} />;
-}
-```
-
-**What this does:**
-- Visiting `/sign-in` → Redirects to `your-project.insforge.app/auth/sign-in`
-- Visiting `/sign-up` → Redirects to `your-project.insforge.app/auth/sign-up`
-- After auth → Redirects back to `/auth/callback` → Goes to dashboard
-
-### 4. Add Auth UI to Your Pages
-
-```tsx
-// src/pages/Home.tsx
-import { SignedIn, SignedOut, UserButton } from '@insforge/react';
-
-export default function Home() {
-  return (
-    <div>
-      <nav>
-        <SignedOut>
-          <a href="/sign-in">Sign In</a>
-        </SignedOut>
-
-        <SignedIn>
-          <UserButton afterSignOutUrl="/" />
-        </SignedIn>
-      </nav>
-
-      <h1>Welcome to My App!</h1>
-    </div>
-  );
-}
-```
-
-**That's it!** 🎉 You now have production-ready authentication.
-
----
-
-## Router Configuration Options
-
-### Built-in Auth (Recommended)
-
-Uses your deployed Insforge auth pages (includes all flows):
-
-```tsx
-...getInsforgeRoutes({
-  baseUrl: 'https://your-project.insforge.app',
-  builtInAuth: true,  // Default
-  paths: {
-    signIn: '/sign-in',                // Sign in page
-    signUp: '/sign-up',                // Sign up page
-    verifyEmail: '/verify-email',      // Email verification page
-    forgotPassword: '/forgot-password', // Request password reset
-    resetPassword: '/reset-password',   // Reset password with token
-    callback: '/auth/callback'          // OAuth callback handler
-  }
-})
-```
-
-### Custom UI Components
-
-Use package components with your own styling:
-
-```tsx
-import { 
-  SignIn, 
-  SignUp, 
-  ForgotPassword, 
-  ResetPassword, 
-  VerifyEmail 
-} from '@insforge/react';
-
-const router = createBrowserRouter([
-  { path: '/', element: <Home /> },
-  
-  // Still need callback route for OAuth
-  ...getInsforgeRoutes({
-    baseUrl: import.meta.env.VITE_INSFORGE_BASE_URL,
-    builtInAuth: false  // Don't redirect to deployed UI
-  }),
-  
-  // Use package components for complete auth flows
-  { path: '/sign-in', element: <SignIn afterSignInUrl="/dashboard" /> },
-  { path: '/sign-up', element: <SignUp afterSignUpUrl="/dashboard" /> },
-  { path: '/forgot-password', element: <ForgotPassword backToSignInUrl="/sign-in" /> },
-  { path: '/reset-password', element: <ResetPassword token={searchParams.get('token')} /> },
-  { path: '/verify-email', element: <VerifyEmail token={searchParams.get('token')} /> }
-]);
-```
-
-### Fully Custom UI
-
-Build your own auth pages from scratch:
-
-```tsx
-import { useAuth } from '@insforge/react';
-
-function CustomSignIn() {
-  const { signIn } = useAuth();
-  
-  const handleSubmit = async (e) => {
-    e.preventDefault();
-    await signIn(email, password);
-    navigate('/dashboard');
-  };
-  
-  return <form onSubmit={handleSubmit}>...</form>;
-}
-```
-
----
-
-## Core Features
-
-### Components
-
-**Pre-built with Business Logic:**
-- `<SignIn />` - Complete sign-in with email/password & OAuth
-- `<SignUp />` - Registration with password validation & email verification
-- `<ForgotPassword />` - Request password reset with email validation
-- `<ResetPassword />` - Reset password with token validation
-- `<VerifyEmail />` - Verify email with automatic token handling
-- `<UserButton />` - User dropdown with sign-out
-- `<Protect />` - Route protection wrapper
-- `<SignedIn>` / `<SignedOut>` - Conditional rendering
-- `<InsforgeCallback />` - OAuth callback handler
-
-**Form Components (Pure UI):**
-- `<SignInForm />` - Sign-in UI without logic
-- `<SignUpForm />` - Sign-up UI without logic
-- `<ForgotPasswordForm />` - Password reset request UI
-- `<ResetPasswordForm />` - Password reset with token UI
-- `<VerifyEmailStatus />` - Email verification status UI
-
-**Atomic Components (14 total):**
-- `<AuthContainer />`, `<AuthHeader />`, `<AuthFormField />`, `<AuthPasswordField />`, `<AuthEmailVerificationStep />`, etc.
-
-### Hooks
-
-```tsx
-const { signIn, signUp, signOut, isSignedIn, isLoaded } = useAuth();
-const { user, updateUser, isLoaded } = useUser();
-const { oauthProviders, emailConfig, isLoaded } = usePublicAuthConfig();
-```
-
----
-
-## Customization
-
-### Basic Styling
-
-All components support `appearance` props:
-
-```tsx
-<SignIn
-  appearance={{
-    container: "max-w-lg",
-    card: "bg-white shadow-2xl",
-    button: "bg-blue-600 hover:bg-blue-700"
-  }}
-/>
-
-// Works with all auth components
-<ForgotPassword
-  appearance={{
-    card: "bg-gradient-to-br from-indigo-50 to-white",
-    button: "bg-indigo-600 hover:bg-indigo-700"
-  }}
-/>
-```
-
-### Deep Customization (Hierarchical Appearance)
-
-Style nested components through hierarchical structure:
-
-```tsx
-<SignIn
-  appearance={{
-    card: "bg-gradient-to-br from-blue-50 to-white shadow-2xl",
-    header: {
-      title: "text-3xl font-bold text-purple-900",
-      subtitle: "text-purple-600"
-    },
-    form: {
-      emailField: {
-        label: "text-gray-800 font-semibold",
-        input: "border-purple-300 focus:border-purple-500 rounded-lg"
-      },
-      passwordField: {
-        input: "border-purple-300 focus:border-purple-500 rounded-lg",
-        forgotPasswordLink: "text-purple-600 hover:text-purple-800"
-      }
-    },
-    button: "bg-purple-600 hover:bg-purple-700 rounded-lg h-12",
-    link: {
-      text: "text-gray-600",
-      link: "text-purple-600 hover:text-purple-800 font-semibold"
-    },
-    oauth: {
-      button: "border-2 hover:bg-gray-50 rounded-xl"
-    }
-  }}
-/>
-```
-
-#### Complete Appearance Structure
-
-**All auth components** (`SignIn`, `SignUp`, `ForgotPassword`, `ResetPassword`) support hierarchical appearance:
-
-```typescript
-appearance?: {
-  container?: string;              // Outermost wrapper
-  card?: string;                   // Inner card box
-  header?: {
-    container?: string;            // Header wrapper
-    title?: string;                // Title text
-    subtitle?: string;             // Subtitle text
-  };
-  errorBanner?: string;            // Error message banner
-  form?: {
-    container?: string;            // Form wrapper
-    emailField?: {                 // Available in SignIn, SignUp, ForgotPassword
-      container?: string;
-      label?: string;
-      input?: string;
-    };
-    passwordField?: {              // Available in SignIn, SignUp, ResetPassword
-      container?: string;
-      label?: string;
-      input?: string;
-      forgotPasswordLink?: string; // SignIn only
-      strengthIndicator?: {        // SignUp and ResetPassword
-        container?: string;
-        requirement?: string;
-      };
-    };
-  };
-  button?: string;                 // Submit button
-  link?: {
-    container?: string;            // Link section wrapper
-    text?: string;                 // Link description text
-    link?: string;                 // Actual link element
-  };
-  divider?: string;                // "or" divider (SignIn, SignUp)
-  oauth?: {                        // OAuth section (SignIn, SignUp)
-    container?: string;
-    button?: string;
-  };
-}
-```
-
-### Text Customization
-
-All components support full text customization:
-
-```tsx
-<SignIn
-  title="Welcome Back!"
-  subtitle="We're happy to see you again"
-  emailLabel="Your Email Address"
-  emailPlaceholder="you@company.com"
-  passwordLabel="Your Password"
-  submitButtonText="Login Now"
-  loadingButtonText="Signing you in..."
-  signUpText="New to our platform?"
-  signUpLinkText="Create an account"
-  dividerText="or continue with"
-/>
-
-<ForgotPassword
-  title="Reset Your Password"
-  subtitle="Enter your email to receive a reset code"
-  emailLabel="Email Address"
-  submitButtonText="Send Reset Code"
-  backToSignInText="Remember your password?"
-  successTitle="Check Your Email"
-  successMessage="We've sent a reset code to your inbox"
-/>
-```
-
----
-
-## Advanced Usage
-
-### Complete Component with Custom Logic
-
-```tsx
-import { SignInForm, useAuth } from '@insforge/react';
-import { useState } from 'react';
-
-function CustomSignIn() {
-  const { signIn } = useAuth();
-  const [email, setEmail] = useState('');
-  const [password, setPassword] = useState('');
-  const [error, setError] = useState('');
-  const [loading, setLoading] = useState(false);
-
-  const handleSubmit = async (e: React.FormEvent) => {
-    e.preventDefault();
-    setLoading(true);
-    setError('');
-    
-    try {
-      await signIn(email, password);
-      // Custom success logic
-    } catch (err) {
-      setError(err.message);
-    } finally {
-      setLoading(false);
-    }
-  };
-
-  return (
-    <SignInForm
-      email={email}
-      password={password}
-      onEmailChange={setEmail}
-      onPasswordChange={setPassword}
-      onSubmit={handleSubmit}
-      error={error}
-      loading={loading}
-      availableProviders={['google', 'github']}
-      onOAuthClick={(provider) => {
-        // Custom OAuth logic
-      }}
-    />
-  );
-}
-```
-
-### Build from Atomic Components
-
-```tsx
-import {
-  AuthContainer,
-  AuthHeader,
-  AuthFormField,
-  AuthPasswordField,
-  AuthSubmitButton,
-  AuthErrorBanner,
-  AuthDivider,
-  AuthOAuthProviders,
-  AuthLink,
-} from '@insforge/react';
-
-function CompletelyCustomAuth() {
-  return (
-    <AuthContainer
-      appearance={{
-        containerClassName: "max-w-md",
-        cardClassName: "bg-white shadow-2xl"
-      }}
-    >
-      <AuthHeader
-        title="Welcome to MyApp"
-        subtitle="Sign in to continue"
-        appearance={{
-          titleClassName: "text-3xl text-blue-900"
-        }}
-      />
-
-      <AuthErrorBanner error={error} />
-
-      <form onSubmit={handleSubmit}>
-        <AuthFormField
-          id="email"
-          type="email"
-          label="Email"
-          value={email}
-          onChange={(e) => setEmail(e.target.value)}
-          appearance={{
-            inputClassName: "border-blue-500"
-          }}
-        />
-
-        <AuthPasswordField
-          id="password"
-          label="Password"
-          value={password}
-          onChange={(e) => setPassword(e.target.value)}
-          emailAuthConfig={config}
-          showStrengthIndicator
-        />
-
-        <AuthSubmitButton isLoading={loading}>
-          Sign In
-        </AuthSubmitButton>
-      </form>
-
-      <AuthDivider text="or" />
-
-      <AuthOAuthProviders
-        providers={['google', 'github', 'discord']}
-        onClick={handleOAuth}
-        loading={oauthLoading}
-      />
-
-      <AuthLink
-        text="Don't have an account?"
-        linkText="Sign up"
-        href="/sign-up"
-      />
-    </AuthContainer>
-  );
-}
-```
-
-### Route Protection
-
-```tsx
-import { Protect } from '@insforge/react';
-
-function Dashboard() {
-  return (
-    <div>
-      <h1>Dashboard</h1>
-      
-      {/* Simple protection */}
-      <Protect redirectTo="/sign-in">
-        <UserContent />
-      </Protect>
-
-      {/* Role-based protection */}
-      <Protect
-        redirectTo="/unauthorized"
-        condition={(user) => user.role === 'admin'}
-      >
-        <AdminPanel />
-      </Protect>
-    </div>
-  );
-}
-```
-
----
-
-## TypeScript
-
-Full TypeScript support with exported types:
-
-```tsx
-import type {
-  InsforgeUser,
-  SignInProps,
-  SignUpProps,
-  ForgotPasswordProps,
-  ResetPasswordProps,
-  VerifyEmailProps,
-  SignInAppearance,
-  SignUpAppearance,
-  ForgotPasswordAppearance,
-  ResetPasswordAppearance,
-  UserButtonProps,
-  ProtectProps,
-  ConditionalProps,
-  InsforgeCallbackProps,
-  SignInFormProps,
-  SignUpFormProps,
-  ForgotPasswordFormProps,
-  ResetPasswordFormProps,
-  VerifyEmailStatusProps,
-  AuthFormFieldProps,
-  OAuthProvider,
-  EmailAuthConfig,
-  InsforgeProviderProps,
-  GetInsforgeRoutesConfig,
-} from '@insforge/react';
-```
-
----
-
-## OAuth Providers
-
-Built-in support for 10+ OAuth providers:
-- Google
-- GitHub
-- Discord
-- Apple
-- Microsoft
-- Facebook
-- LinkedIn
-- Instagram
-- TikTok
-- Spotify
-- X (Twitter)
-
-Providers are auto-detected from your backend configuration.
-
----
-
-## Validation Utilities
-
-```tsx
-import { emailSchema, cn } from '@insforge/react/lib';
-
-// Validate email with Zod
-const result = emailSchema.safeParse('user@example.com');
-
-// Merge Tailwind classes
-const className = cn('px-4 py-2', 'bg-blue-500', conditionalClass);
-```
-
----
-
-## Available Atomic Components
-
-Low-level building blocks for complete customization:
-
-- `<AuthBranding />` - Insforge branding footer
-- `<AuthContainer />` - Main container wrapper
-- `<AuthHeader />` - Title and subtitle display
-- `<AuthErrorBanner />` - Error message display
-- `<AuthFormField />` - Standard input field
-- `<AuthPasswordField />` - Password input with features
-- `<AuthPasswordStrengthIndicator />` - Password checklist
-- `<AuthSubmitButton />` - Submit button with states
-- `<AuthLink />` - Call-to-action link
-- `<AuthDivider />` - Visual separator
-- `<AuthOAuthButton />` - Single OAuth provider button
-- `<AuthOAuthProviders />` - Smart OAuth grid
-- `<AuthVerificationCodeInput />` - 6-digit OTP input
-- `<AuthEmailVerificationStep />` - Email verification step with countdown and resend
-
----
-
-## Support
-
-- **Documentation**: https://docs.insforge.dev
-- **GitHub Issues**: https://github.com/InsForge/InsForge/issues
-- **Discord Community**: https://discord.com/invite/DvBtaEc9Jz
-
-## License
-
-MIT © Insforge
+# @insforge/react
+
+**Complete authentication solution for React applications.** Production-ready components with full business logic included.
+
+## Why @insforge/react?
+
+✅ **5-Minute Setup** - One provider + one line of router config = done  
+✅ **Built-in Auth UI** - Use deployed auth pages (like Next.js middleware)  
+✅ **Framework Agnostic** - Works with any React framework  
+✅ **Full TypeScript** - Complete type safety out of the box  
+✅ **Fully Customizable** - Deep styling control when you need it
+
+---
+
+## Quick Start
+
+Get authentication working in your React app in 5 minutes.
+
+### 1. Install
+
+```bash
+npm install @insforge/react
+# or
+yarn add @insforge/react
+# or
+pnpm add @insforge/react
+```
+
+### 2. Setup Provider
+
+Wrap your app with `InsforgeProvider`:
+
+```tsx
+// src/main.tsx (Vite) or src/index.tsx (CRA)
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { InsforgeProvider } from '@insforge/react';
+import '@insforge/react/styles.css';
+import App from './App';
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <InsforgeProvider baseUrl={import.meta.env.VITE_INSFORGE_BASE_URL}>
+      <App />
+    </InsforgeProvider>
+  </StrictMode>
+);
+```
+
+### 3. Configure Router (Built-in Auth)
+
+```tsx
+// src/App.tsx
+import { createBrowserRouter, RouterProvider } from 'react-router-dom';
+import { getInsforgeRoutes } from '@insforge/react/router';
+import Home from './pages/Home';
+import Dashboard from './pages/Dashboard';
+
+const router = createBrowserRouter([
+  { path: '/', element: <Home /> },
+  
+  ...getInsforgeRoutes({
+    baseUrl: import.meta.env.VITE_INSFORGE_BASE_URL,
+    builtInAuth: true
+  }),
+  
+  { path: '/dashboard', element: <Dashboard /> }
+]);
+
+export default function App() {
+  return <RouterProvider router={router} />;
+}
+```
+
+**What this does:**
+- Visiting `/sign-in` → Redirects to `your-project.insforge.app/auth/sign-in`
+- Visiting `/sign-up` → Redirects to `your-project.insforge.app/auth/sign-up`
+- After auth → Redirects back to `/auth/callback` → Goes to dashboard
+
+### 4. Add Auth UI to Your Pages
+
+```tsx
+// src/pages/Home.tsx
+import { SignedIn, SignedOut, UserButton } from '@insforge/react';
+
+export default function Home() {
+  return (
+    <div>
+      <nav>
+        <SignedOut>
+          <a href="/sign-in">Sign In</a>
+        </SignedOut>
+
+        <SignedIn>
+          <UserButton afterSignOutUrl="/" />
+        </SignedIn>
+      </nav>
+
+      <h1>Welcome to My App!</h1>
+    </div>
+  );
+}
+```
+
+**That's it!** 🎉 You now have production-ready authentication.
+
+---
+
+## Router Configuration Options
+
+### Built-in Auth (Recommended)
+
+Uses your deployed Insforge auth pages (includes all flows):
+
+```tsx
+...getInsforgeRoutes({
+  baseUrl: 'https://your-project.insforge.app',
+  builtInAuth: true,  // Default
+  paths: {
+    signIn: '/sign-in',                // Sign in page
+    signUp: '/sign-up',                // Sign up page
+    verifyEmail: '/verify-email',      // Email verification page
+    forgotPassword: '/forgot-password', // Request password reset
+    resetPassword: '/reset-password',   // Reset password with token
+    callback: '/auth/callback'          // OAuth callback handler
+  }
+})
+```
+
+### Custom UI Components
+
+Use package components with your own styling:
+
+```tsx
+import { 
+  SignIn, 
+  SignUp, 
+  ForgotPassword, 
+  ResetPassword, 
+  VerifyEmail 
+} from '@insforge/react';
+
+const router = createBrowserRouter([
+  { path: '/', element: <Home /> },
+  
+  // Still need callback route for OAuth
+  ...getInsforgeRoutes({
+    baseUrl: import.meta.env.VITE_INSFORGE_BASE_URL,
+    builtInAuth: false  // Don't redirect to deployed UI
+  }),
+  
+  // Use package components for complete auth flows
+  { path: '/sign-in', element: <SignIn afterSignInUrl="/dashboard" /> },
+  { path: '/sign-up', element: <SignUp afterSignUpUrl="/dashboard" /> },
+  { path: '/forgot-password', element: <ForgotPassword backToSignInUrl="/sign-in" /> },
+  { path: '/reset-password', element: <ResetPassword token={searchParams.get('token')} /> },
+  { path: '/verify-email', element: <VerifyEmail token={searchParams.get('token')} /> }
+]);
+```
+
+### Fully Custom UI
+
+Build your own auth pages from scratch:
+
+```tsx
+import { useAuth } from '@insforge/react';
+
+function CustomSignIn() {
+  const { signIn } = useAuth();
+  
+  const handleSubmit = async (e) => {
+    e.preventDefault();
+    await signIn(email, password);
+    navigate('/dashboard');
+  };
+  
+  return <form onSubmit={handleSubmit}>...</form>;
+}
+```
+
+---
+
+## Core Features
+
+### Components
+
+**Pre-built with Business Logic:**
+- `<SignIn />` - Complete sign-in with email/password & OAuth
+- `<SignUp />` - Registration with password validation & email verification
+- `<ForgotPassword />` - Request password reset with email validation
+- `<ResetPassword />` - Reset password with token validation
+- `<VerifyEmail />` - Verify email with automatic token handling
+- `<UserButton />` - User dropdown with sign-out
+- `<Protect />` - Route protection wrapper
+- `<SignedIn>` / `<SignedOut>` - Conditional rendering
+- `<InsforgeCallback />` - OAuth callback handler
+
+**Form Components (Pure UI):**
+- `<SignInForm />` - Sign-in UI without logic
+- `<SignUpForm />` - Sign-up UI without logic
+- `<ForgotPasswordForm />` - Password reset request UI
+- `<ResetPasswordForm />` - Password reset with token UI
+- `<VerifyEmailStatus />` - Email verification status UI
+
+**Atomic Components (14 total):**
+- `<AuthContainer />`, `<AuthHeader />`, `<AuthFormField />`, `<AuthPasswordField />`, `<AuthEmailVerificationStep />`, etc.
+
+### Hooks
+
+```tsx
+const { signIn, signUp, signOut, isSignedIn, isLoaded } = useAuth();
+const { user, updateUser, isLoaded } = useUser();
+const { oauthProviders, authConfig, isLoaded } = usePublicAuthConfig();
+```
+
+---
+
+## Customization
+
+### Basic Styling
+
+All components support `appearance` props:
+
+```tsx
+<SignIn
+  appearance={{
+    container: "max-w-lg",
+    card: "bg-white shadow-2xl",
+    button: "bg-blue-600 hover:bg-blue-700"
+  }}
+/>
+
+// Works with all auth components
+<ForgotPassword
+  appearance={{
+    card: "bg-gradient-to-br from-indigo-50 to-white",
+    button: "bg-indigo-600 hover:bg-indigo-700"
+  }}
+/>
+```
+
+### Deep Customization (Hierarchical Appearance)
+
+Style nested components through hierarchical structure:
+
+```tsx
+<SignIn
+  appearance={{
+    card: "bg-gradient-to-br from-blue-50 to-white shadow-2xl",
+    header: {
+      title: "text-3xl font-bold text-purple-900",
+      subtitle: "text-purple-600"
+    },
+    form: {
+      emailField: {
+        label: "text-gray-800 font-semibold",
+        input: "border-purple-300 focus:border-purple-500 rounded-lg"
+      },
+      passwordField: {
+        input: "border-purple-300 focus:border-purple-500 rounded-lg",
+        forgotPasswordLink: "text-purple-600 hover:text-purple-800"
+      }
+    },
+    button: "bg-purple-600 hover:bg-purple-700 rounded-lg h-12",
+    link: {
+      text: "text-gray-600",
+      link: "text-purple-600 hover:text-purple-800 font-semibold"
+    },
+    oauth: {
+      button: "border-2 hover:bg-gray-50 rounded-xl"
+    }
+  }}
+/>
+```
+
+#### Complete Appearance Structure
+
+**All auth components** (`SignIn`, `SignUp`, `ForgotPassword`, `ResetPassword`) support hierarchical appearance:
+
+```typescript
+appearance?: {
+  container?: string;              // Outermost wrapper
+  card?: string;                   // Inner card box
+  header?: {
+    container?: string;            // Header wrapper
+    title?: string;                // Title text
+    subtitle?: string;             // Subtitle text
+  };
+  errorBanner?: string;            // Error message banner
+  form?: {
+    container?: string;            // Form wrapper
+    emailField?: {                 // Available in SignIn, SignUp, ForgotPassword
+      container?: string;
+      label?: string;
+      input?: string;
+    };
+    passwordField?: {              // Available in SignIn, SignUp, ResetPassword
+      container?: string;
+      label?: string;
+      input?: string;
+      forgotPasswordLink?: string; // SignIn only
+      strengthIndicator?: {        // SignUp and ResetPassword
+        container?: string;
+        requirement?: string;
+      };
+    };
+  };
+  button?: string;                 // Submit button
+  link?: {
+    container?: string;            // Link section wrapper
+    text?: string;                 // Link description text
+    link?: string;                 // Actual link element
+  };
+  divider?: string;                // "or" divider (SignIn, SignUp)
+  oauth?: {                        // OAuth section (SignIn, SignUp)
+    container?: string;
+    button?: string;
+  };
+}
+```
+
+### Text Customization
+
+All components support full text customization:
+
+```tsx
+<SignIn
+  title="Welcome Back!"
+  subtitle="We're happy to see you again"
+  emailLabel="Your Email Address"
+  emailPlaceholder="you@company.com"
+  passwordLabel="Your Password"
+  submitButtonText="Login Now"
+  loadingButtonText="Signing you in..."
+  signUpText="New to our platform?"
+  signUpLinkText="Create an account"
+  dividerText="or continue with"
+/>
+
+<ForgotPassword
+  title="Reset Your Password"
+  subtitle="Enter your email to receive a reset code"
+  emailLabel="Email Address"
+  submitButtonText="Send Reset Code"
+  backToSignInText="Remember your password?"
+  successTitle="Check Your Email"
+  successMessage="We've sent a reset code to your inbox"
+/>
+```
+
+---
+
+## Advanced Usage
+
+### Complete Component with Custom Logic
+
+```tsx
+import { SignInForm, useAuth } from '@insforge/react';
+import { useState } from 'react';
+
+function CustomSignIn() {
+  const { signIn } = useAuth();
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
+  const [error, setError] = useState('');
+  const [loading, setLoading] = useState(false);
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    setLoading(true);
+    setError('');
+    
+    try {
+      await signIn(email, password);
+      // Custom success logic
+    } catch (err) {
+      setError(err.message);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <SignInForm
+      email={email}
+      password={password}
+      onEmailChange={setEmail}
+      onPasswordChange={setPassword}
+      onSubmit={handleSubmit}
+      error={error}
+      loading={loading}
+      availableProviders={['google', 'github']}
+      onOAuthClick={(provider) => {
+        // Custom OAuth logic
+      }}
+    />
+  );
+}
+```
+
+### Build from Atomic Components
+
+```tsx
+import {
+  AuthContainer,
+  AuthHeader,
+  AuthFormField,
+  AuthPasswordField,
+  AuthSubmitButton,
+  AuthErrorBanner,
+  AuthDivider,
+  AuthOAuthProviders,
+  AuthLink,
+} from '@insforge/react';
+
+function CompletelyCustomAuth() {
+  return (
+    <AuthContainer
+      appearance={{
+        containerClassName: "max-w-md",
+        cardClassName: "bg-white shadow-2xl"
+      }}
+    >
+      <AuthHeader
+        title="Welcome to MyApp"
+        subtitle="Sign in to continue"
+        appearance={{
+          titleClassName: "text-3xl text-blue-900"
+        }}
+      />
+
+      <AuthErrorBanner error={error} />
+
+      <form onSubmit={handleSubmit}>
+        <AuthFormField
+          id="email"
+          type="email"
+          label="Email"
+          value={email}
+          onChange={(e) => setEmail(e.target.value)}
+          appearance={{
+            inputClassName: "border-blue-500"
+          }}
+        />
+
+        <AuthPasswordField
+          id="password"
+          label="Password"
+          value={password}
+          onChange={(e) => setPassword(e.target.value)}
+          authConfig={config}
+          showStrengthIndicator
+        />
+
+        <AuthSubmitButton isLoading={loading}>
+          Sign In
+        </AuthSubmitButton>
+      </form>
+
+      <AuthDivider text="or" />
+
+      <AuthOAuthProviders
+        providers={['google', 'github', 'discord']}
+        onClick={handleOAuth}
+        loading={oauthLoading}
+      />
+
+      <AuthLink
+        text="Don't have an account?"
+        linkText="Sign up"
+        href="/sign-up"
+      />
+    </AuthContainer>
+  );
+}
+```
+
+### Route Protection
+
+```tsx
+import { Protect } from '@insforge/react';
+
+function Dashboard() {
+  return (
+    <div>
+      <h1>Dashboard</h1>
+      
+      {/* Simple protection */}
+      <Protect redirectTo="/sign-in">
+        <UserContent />
+      </Protect>
+
+      {/* Role-based protection */}
+      <Protect
+        redirectTo="/unauthorized"
+        condition={(user) => user.role === 'admin'}
+      >
+        <AdminPanel />
+      </Protect>
+    </div>
+  );
+}
+```
+
+---
+
+## TypeScript
+
+Full TypeScript support with exported types:
+
+```tsx
+import type {
+  InsforgeUser,
+  SignInProps,
+  SignUpProps,
+  ForgotPasswordProps,
+  ResetPasswordProps,
+  VerifyEmailProps,
+  SignInAppearance,
+  SignUpAppearance,
+  ForgotPasswordAppearance,
+  ResetPasswordAppearance,
+  UserButtonProps,
+  ProtectProps,
+  ConditionalProps,
+  InsforgeCallbackProps,
+  SignInFormProps,
+  SignUpFormProps,
+  ForgotPasswordFormProps,
+  ResetPasswordFormProps,
+  VerifyEmailStatusProps,
+  AuthFormFieldProps,
+  OAuthProvider,
+  EmailAuthConfig,
+  InsforgeProviderProps,
+  GetInsforgeRoutesConfig,
+} from '@insforge/react';
+```
+
+---
+
+## OAuth Providers
+
+Built-in support for 10+ OAuth providers:
+- Google
+- GitHub
+- Discord
+- Apple
+- Microsoft
+- Facebook
+- LinkedIn
+- Instagram
+- TikTok
+- Spotify
+- X (Twitter)
+
+Providers are auto-detected from your backend configuration.
+
+---
+
+## Validation Utilities
+
+```tsx
+import { emailSchema, cn } from '@insforge/react/lib';
+
+// Validate email with Zod
+const result = emailSchema.safeParse('user@example.com');
+
+// Merge Tailwind classes
+const className = cn('px-4 py-2', 'bg-blue-500', conditionalClass);
+```
+
+---
+
+## Available Atomic Components
+
+Low-level building blocks for complete customization:
+
+- `<AuthBranding />` - Insforge branding footer
+- `<AuthContainer />` - Main container wrapper
+- `<AuthHeader />` - Title and subtitle display
+- `<AuthErrorBanner />` - Error message display
+- `<AuthFormField />` - Standard input field
+- `<AuthPasswordField />` - Password input with features
+- `<AuthPasswordStrengthIndicator />` - Password checklist
+- `<AuthSubmitButton />` - Submit button with states
+- `<AuthLink />` - Call-to-action link
+- `<AuthDivider />` - Visual separator
+- `<AuthOAuthButton />` - Single OAuth provider button
+- `<AuthOAuthProviders />` - Smart OAuth grid
+- `<AuthVerificationCodeInput />` - 6-digit OTP input
+- `<AuthEmailVerificationStep />` - Email verification step with countdown and resend
+
+---
+
+## Support
+
+- **Documentation**: https://docs.insforge.dev
+- **GitHub Issues**: https://github.com/InsForge/InsForge/issues
+- **Discord Community**: https://discord.com/invite/DvBtaEc9Jz
+
+## License
+
+MIT © Insforge