@insforge/react 0.5.0 → 0.5.2

package/README.md

@@ -1,439 +1,426 @@
-# @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
-
----
-
-## 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
-```
-
-**Required Dependencies:** `bash npm install react@^19.0.0 react-dom@^19.0.0
-  react-router-dom@^7.9.0 `
-
-#### Environment Variables
-
-```bash .env
-VITE_INSFORGE_BASE_URL=https://your-project.insforge.app/
-```
-
-### 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 App from './App';
-
-createRoot(document.getElementById('root')!).render(
-  <StrictMode>
-    <InsforgeProvider baseUrl={import.meta.env.VITE_INSFORGE_BASE_URL} afterSignInUrl="/dashboard">
-      <App />
-    </InsforgeProvider>
-  </StrictMode>
-);
-```
-
-### Step 3: Configure Router (Built-in Auth)
-
-**The fastest way** - Use deployed auth pages with Layout pattern:
-
-```tsx src/App.tsx
-import { createBrowserRouter, RouterProvider } from 'react-router-dom';
-import { getInsforgeRoutes } from '@insforge/react/router';
-import Layout from './components/Layout';
-import Home from './pages/Home';
-import Dashboard from './pages/Dashboard';
-
-const router = createBrowserRouter([
-  {
-    path: '/',
-    element: <Layout />,
-    children: [
-      { index: true, element: <Home /> },
-
-      { path: 'dashboard', element: <Dashboard /> }
-    ]
-  },
-
-  // Add built-in auth redirect routes (sign-in, sign-up, forgot-password, etc.)
-  ...getInsforgeRoutes({
-    baseUrl: import.meta.env.VITE_INSFORGE_BASE_URL,
-    afterSignInUrl="/dashboard"
-    builtInAuth: true  // Redirects to deployed auth pages
-  })
-]);
-
-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`
-- Visiting `/forgot-password` → Redirects to `your-project.insforge.app/auth/forgot-password`
-- After auth → Backend redirects with token in URL → SDK auto-detects and stores token
-
-### 4. Use Hooks & Components
-
-```tsx
-// src/pages/Home.tsx
-import { SignedIn, SignedOut, UserButton, useAuth, useUser } from '@insforge/react';
-
-export default function Home() {
-  const { isSignedIn } = useAuth();
-  const { user } = useUser();
-
-  return (
-    <div>
-      <nav>
-        <SignedOut>
-          <a href="/sign-in">Sign In</a>
-        </SignedOut>
-
-        <SignedIn>
-          <UserButton afterSignOutUrl="/" />
-          <h1>Welcome, {user?.email}!</h1>
-        </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
-    forgotPassword: '/forgot-password', // Request password reset
-  }
-})
-```
-
-### 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 /> },
-
-  // 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 /> },
-]);
-```
-
-### 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
-
-**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
-
-### 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) => {
-        console.log(provider);
-      }}
-    />
-  );
-}
-```
-
-### Build from Atomic Components
-
-```tsx
-import {
-  AuthContainer,
-  AuthHeader,
-  AuthFormField,
-  AuthPasswordField,
-  AuthSubmitButton,
-  AuthErrorBanner,
-  AuthDivider,
-  AuthOAuthProviders,
-  AuthLink,
-} from '@insforge/react';
-
-function CompletelyCustomAuth() {
-  return (
-    <AuthContainer>
-      <AuthHeader title="Welcome to MyApp" subtitle="Sign in to continue" />
-
-      <AuthErrorBanner error={error} />
-
-      <form onSubmit={handleSubmit}>
-        <AuthFormField
-          id="email"
-          type="email"
-          label="Email"
-          value={email}
-          onChange={(e) => setEmail(e.target.value)}
-        />
-
-        <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>
-  );
-}
-```
-
----
-
-## 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.
-
----
-
-## 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
+
+**Framework-agnostic authentication solution for React applications.** Production-ready components with full business logic included.
+
+## Why @insforge/react?
+
+✅ **Framework Agnostic** - Works with any React setup (Vite, CRA, or no bundler)  
+✅ **Zero Router Dependencies** - Use with any routing solution or none at all  
+✅ **Production Ready** - Complete auth flows with business logic included  
+✅ **Full TypeScript** - Complete type safety out of the box
+
+---
+
+## 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
+```
+
+**Required Peer Dependencies:**
+```bash
+npm install react@^19.0.0 react-dom@^19.0.0
+```
+
+
+#### Environment Variables
+
+```bash
+# .env
+VITE_INSFORGE_BASE_URL=https://your-project.insforge.app/
+```
+
+### 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 App from './App';
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <InsforgeProvider baseUrl={import.meta.env.VITE_INSFORGE_BASE_URL} afterSignInUrl="/dashboard">
+      <App />
+    </InsforgeProvider>
+  </StrictMode>
+);
+```
+
+### 3. Use Components & Hooks
+
+Now you can use authentication components and hooks anywhere in your app:
+
+```tsx
+// src/App.tsx
+import { SignIn, SignedIn, SignedOut, UserButton, useAuth } from '@insforge/react';
+
+export default function App() {
+  const { isSignedIn, isLoaded } = useAuth();
+
+  if (!isLoaded) {
+    return <div>Loading...</div>;
+  }
+
+  return (
+    <div>
+      <SignedOut>
+        <SignIn />
+      </SignedOut>
+
+      <SignedIn>
+        <nav>
+          <UserButton afterSignOutUrl="/" />
+        </nav>
+        <h1>Welcome to your dashboard!</h1>
+      </SignedIn>
+    </div>
+  );
+}
+```
+
+**That's it!** 🎉 You now have production-ready authentication.
+
+---
+
+## Usage Patterns
+
+### Option 1: Pre-built Components (Fastest)
+
+Use complete auth flows with built-in UI and logic:
+
+```tsx
+import { SignIn, SignUp, ForgotPassword, ResetPassword } from '@insforge/react';
+
+// In your app
+<SignIn />  // Complete sign-in flow
+<SignUp />  // Complete sign-up flow with email verification
+<ForgotPassword />  // Password reset request + verification
+<ResetPassword />  // Reset password with token (from URL params)
+```
+
+### Option 2: Form Components (UI Only)
+
+Use UI components and add your own 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) => {
+    e.preventDefault();
+    setLoading(true);
+    const result = await signIn(email, password);
+    if ('error' in result) {
+      setError(result.error);
+    }
+    setLoading(false);
+  };
+
+  return (
+    <SignInForm
+      email={email}
+      password={password}
+      onEmailChange={setEmail}
+      onPasswordChange={setPassword}
+      onSubmit={handleSubmit}
+      error={error}
+      loading={loading}
+    />
+  );
+}
+```
+
+### Option 3: Hooks Only (Headless)
+
+Build completely custom UI using authentication hooks:
+
+```tsx
+import { useAuth } from '@insforge/react';
+
+function CustomAuthForm() {
+  const { signIn, signUp, isLoaded } = useAuth();
+
+  const handleLogin = async (email: string, password: string) => {
+    const result = await signIn(email, password);
+    if ('error' in result) {
+      console.error(result.error);
+    } else {
+      console.log('Signed in!');
+    }
+  };
+
+  return <form>...your custom UI...</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
+
+**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
+
+### 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
+
+### Conditional Rendering
+
+Control what users see based on auth state:
+
+```tsx
+import { SignedIn, SignedOut, Protect } from '@insforge/react';
+
+function App() {
+  return (
+    <>
+      <SignedOut>
+        <SignIn />
+      </SignedOut>
+
+      <SignedIn>
+        <Dashboard />
+      </SignedIn>
+
+      {/* Or use Protect for specific sections */}
+      <Protect redirectTo="/sign-in">
+        <ProtectedContent />
+      </Protect>
+    </>
+  );
+}
+```
+
+### Build from Atomic Components
+
+```tsx
+import {
+  AuthContainer,
+  AuthHeader,
+  AuthFormField,
+  AuthPasswordField,
+  AuthSubmitButton,
+  AuthErrorBanner,
+  AuthDivider,
+  AuthOAuthProviders,
+  AuthLink,
+} from '@insforge/react';
+
+function CompletelyCustomAuth() {
+  return (
+    <AuthContainer>
+      <AuthHeader title="Welcome to MyApp" subtitle="Sign in to continue" />
+
+      <AuthErrorBanner error={error} />
+
+      <form onSubmit={handleSubmit}>
+        <AuthFormField
+          id="email"
+          type="email"
+          label="Email"
+          value={email}
+          onChange={(e) => setEmail(e.target.value)}
+        />
+
+        <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>
+  );
+}
+```
+
+### Content Protection
+
+Protect specific content or sections:
+
+```tsx
+import { Protect } from '@insforge/react';
+
+function Dashboard() {
+  return (
+    <div>
+      <h1>Dashboard</h1>
+
+      {/* Simple protection - shows nothing if not signed in */}
+      <Protect>
+        <UserContent />
+      </Protect>
+
+      {/* Custom condition - e.g., role-based */}
+      <Protect condition={(user) => user.email.endsWith('@admin.com')}>
+        <AdminPanel />
+      </Protect>
+    </div>
+  );
+}
+```
+
+> **Note:** `<Protect>` is for conditional rendering only. For route-level protection, use your router's authentication guards with `useAuth()` hook.
+
+---
+
+## 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.
+
+---
+
+## 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
+
+---
+
+## Framework Integration
+
+### Next.js
+
+For Next.js App Router with full SSR support:
+
+```bash
+npm install @insforge/nextjs
+```
+
+See [@insforge/nextjs documentation](https://github.com/InsForge/InsForge/tree/main/packages/nextjs)
+
+---
+
+## Support
+
+- **Documentation**: https://docs.insforge.dev
+- **GitHub Issues**: https://github.com/InsForge/InsForge/issues
+- **Discord Community**: https://discord.com/invite/DvBtaEc9Jz
+
+## License
+
+MIT © Insforge