insforge 0.3.3 → 1.3.0

package/docs/core-concepts/authentication/ui-components/customization.mdx

@@ -0,0 +1,529 @@
+---
+title: InsForge Auth Components
+description: Framework-agnostic authentication components guidance for customization
+---
+
+## Custom Authentication system
+
+Use this approach when you need custom authentication pages in your application instead of redirecting to hosted pages.
+
+### Step-by-Step: Custom Auth Pages Setup
+
+#### Step 1: Setup Provider (Same as Quick Start)
+
+The provider setup is identical:
+
+```tsx src/main.tsx
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { InsforgeProvider } from '@insforge/react-router';
+import App from './App';
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <InsforgeProvider
+      baseUrl={
+        import.meta.env.VITE_INSFORGE_BASE_URL || 'https://your-app.region.insforge.app' // Replace with your InsForge backend URL
+      }
+      afterSignInUrl="/dashboard"
+    >
+      <App />
+    </InsforgeProvider>
+  </StrictMode>
+);
+```
+
+#### Step 2: Configure Router with Custom Pages
+
+Set `builtInAuth: false` and provide your page components:
+
+```tsx src/App.tsx
+import { createBrowserRouter, RouterProvider } from 'react-router-dom';
+import { getInsforgeRoutes } from '@insforge/react-router/router';
+import Layout from './components/Layout';
+import Home from './pages/Home';
+import Dashboard from './pages/Dashboard';
+// Import your custom auth pages
+import SignInPage from './pages/auth/SignInPage';
+import SignUpPage from './pages/auth/SignUpPage';
+import ForgotPasswordPage from './pages/auth/ForgotPasswordPage';
+
+const router = createBrowserRouter([
+  {
+    path: '/',
+    element: <Layout />,
+    children: [
+      { index: true, element: <Home /> },
+      { path: 'dashboard', element: <Dashboard /> },
+    ],
+  },
+
+  // Custom auth routes
+  ...getInsforgeRoutes({
+    baseUrl: import.meta.env.VITE_INSFORGE_BASE_URL || 'https://your-app.region.insforge.app', // Replace with your InsForge backend URL
+    afterSignInUrl: '/dashboard',
+    builtInAuth: false, // Render custom components instead of redirecting
+    pages: {
+      signIn: <SignInPage />,
+      signUp: <SignUpPage />,
+      forgotPassword: <ForgotPasswordPage />,
+    },
+  }),
+]);
+
+export default function App() {
+  return <RouterProvider router={router} />;
+}
+```
+
+#### Step 3: Create Auth Page Components
+
+Use our complete authentication components directly. These components are **full-featured page-level components** with all business logic included:
+
+```tsx src/pages/auth/SignInPage.tsx
+import { SignIn } from '@insforge/react-router';
+
+export default function SignInPage() {
+  return (
+    <div className="h-screen flex items-center justify-center">
+      <SignIn
+        title="Welcome Back"
+        subtitle="Sign in to your account"
+        onError={(error) => {
+          console.error('Sign in error:', error);
+        }}
+      />
+    </div>
+  );
+}
+```
+
+```tsx src/pages/auth/SignUpPage.tsx
+import { SignUp } from '@insforge/react-router';
+
+export default function SignUpPage() {
+  return (
+    <div className="h-screen flex items-center justify-center">
+      <SignUp
+        title="Create Account"
+        subtitle="Get started for free"
+        onError={(error) => {
+          console.error('Sign up error:', error);
+        }}
+      />
+    </div>
+  );
+}
+```
+
+```tsx src/pages/auth/ForgotPasswordPage.tsx
+import { ForgotPassword } from '@insforge/react-router';
+
+export default function ForgotPasswordPage() {
+  return (
+    <div className="h-screen flex items-center justify-center">
+      <ForgotPassword
+        onError={(error) => {
+          console.error('Password reset error:', error);
+        }}
+      />
+    </div>
+  );
+}
+```
+
+**That's it!** The `<SignIn>`, `<SignUp>`, and `<ForgotPassword>` components are complete page-level components that include:
+
+- Form UI with validation
+- OAuth provider buttons (auto-detected)
+- Error handling
+- Loading states
+- Password strength indicators (SignUp)
+- All authentication logic
+
+You only need to wrap them in your page components for layout/styling purposes.
+
+### Key Difference from Built-in Auth
+
+**Built-in Auth:**
+
+- `/sign-in` → Redirects to `https://your-app.region.insforge.app/auth/sign-in`
+- Authentication happens on hosted page
+- Returns to your app with token
+
+**Custom Components:**
+
+- `/sign-in` → Renders your `<SignInPage>` component
+- Authentication happens in your app
+- SDK handles token management automatically
+
+---
+
+## Features
+
+- **Built-in Auth**: React Router integration with deployed auth pages
+- **Complete Components**: Pre-built `<SignIn>`, `<SignUp>`, `<UserButton>` with business logic
+- **OAuth Support**: Google, GitHub, Discord, Facebook, LinkedIn, Microsoft, Apple, X, Instagram, TikTok, Spotify
+- **React Hooks**: `useAuth()`, `useUser()`, `usePublicAuthConfig()`
+- **Control Components**: `<SignedIn>`, `<SignedOut>`, `<Protect>`
+- **Form Components**: Pure UI forms for custom logic
+- **TypeScript**: Full type safety
+
+---
+
+## How It Works
+
+### Built-in Auth Flow
+
+```
+1. User clicks "Sign In" → Visits /sign-in route
+   ↓
+2. getInsforgeRoutes() redirects → https://your-app.region.insforge.app/auth/sign-in?redirect=yourapp.com/you-defined-destination-after-sign-in
+   ↓
+3. User signs in on deployed page → Backend processes authentication
+   ↓
+4. Backend redirects → yourapp.com/you-defined-destination-after-sign-in?access_token=xxx&user_id=xxx
+   ↓
+5. InsForge SDK will:
+   - Extracts token from URL
+   - Saves to localStorage
+   - Verifies with getCurrentUser()
+   - Updates Provider state
+   ↓
+6. User sees the destination page (e.g /dashboard)
+```
+
+### Custom UI Flow
+
+```
+1. User visits /sign-in route → Renders <SignIn> component
+   ↓
+2. User enters credentials → Component calls SDK methods
+   ↓
+3. SDK communicates with backend → Returns auth token and user data
+   ↓
+4. Component adds token to URL and redirects → SDK auto-detects token from URL
+   ↓
+5. Provider automatically updates auth state → Components re-render
+   ↓
+6. User sees authenticated UI at destination
+```
+
+**Architecture:**
+
+- **InsforgeProvider**: Manages authentication state globally using React Context
+- **getInsforgeRoutes()**: Creates redirect routes for built-in auth
+- **SDK Integration**: All auth operations go through `@insforge/sdk`, which auto-detects tokens from URL
+- **React Context**: Provides auth state to all child components
+- **Hooks**: Easy access to auth methods and user data
+
+---
+
+## Complete Components (with Business Logic)
+
+These components include full authentication logic and work out of the box.
+
+### `<SignIn />`
+
+Complete sign-in component with email/password and OAuth:
+
+```tsx
+import { SignIn } from '@insforge/react-router';
+
+function SignInPage() {
+  return (
+    <SignIn
+      title="Welcome Back"
+      subtitle="Sign in to continue"
+      onError={(error) => {
+        console.error('Error:', error);
+      }}
+    />
+  );
+}
+```
+
+**Key Features:**
+
+- Email/password authentication
+- OAuth provider buttons (auto-detected from backend)
+- Password visibility toggle
+- Error handling
+- Loading states
+- Customizable text
+
+**Props:**
+
+- `onError` - Callback on error
+- `title` / `subtitle` - Custom heading text
+
+### `<SignUp />`
+
+Complete sign-up component with password strength validation:
+
+```tsx
+import { SignUp } from '@insforge/react-router';
+
+function SignUpPage() {
+  return (
+    <SignUp
+      title="Create Account"
+      subtitle="Get started with your free account"
+      onError={(error) => {
+        console.error('Error:', error);
+      }}
+    />
+  );
+}
+```
+
+**Key Features:**
+
+- Email/password registration
+- Real-time password strength indicator
+- OAuth provider buttons
+- Form validation
+- Customizable text
+
+**Props:** Same as `<SignIn>`.
+
+### `<UserButton />`
+
+User profile dropdown with sign-out:
+
+```tsx
+import { UserButton } from '@insforge/react-router';
+
+function Header() {
+  return (
+    <header>
+      <nav>{/* Your navigation */}</nav>
+      <UserButton afterSignOutUrl="/" mode="detailed" />
+    </header>
+  );
+}
+```
+
+**Modes:**
+
+- `detailed` (default): Shows avatar + name + email
+- `simple`: Shows avatar only
+
+**Props:**
+
+- `mode` - Display mode: `"detailed"` or `"simple"`
+- `afterSignOutUrl` - Redirect URL after sign out
+
+### `<ForgotPassword />`
+
+Complete password reset flow with automatic method detection:
+
+```tsx
+import { ForgotPassword } from '@insforge/react-router';
+
+function ForgotPasswordPage() {
+  return (
+    <ForgotPassword
+      onError={(error) => {
+        console.error('Error:', error);
+      }}
+    />
+  );
+}
+```
+
+**Key Features:**
+
+- Auto-detects reset method (code or link) from backend config
+- **Link method**: Sends email with reset link
+- **Code method**: Three-step flow (email → verify code → reset password)
+- 60-second countdown timer for resend
+- Built-in form validation
+- Customizable text
+
+**Props:**
+
+- `onError` - Callback on error
+
+### `<Protect />`
+
+Protected content with conditional rendering:
+
+```tsx
+import { Protect } from '@insforge/react-router';
+
+function Dashboard() {
+  return (
+    <div>
+      <h1>Dashboard</h1>
+      {/* Simple protection */}
+      <Protect redirectTo="/sign-in">
+        <UserContent />
+      </Protect>
+      {/* Custom logic */}
+      <Protect condition={(user) => user.subscription === 'premium'} fallback={<UpgradePrompt />}>
+        <PremiumFeature />
+      </Protect>
+    </div>
+  );
+}
+```
+
+**Props:**
+
+- `redirectTo` - URL to redirect if not authorized
+- `condition` - Custom condition function `(user) => boolean`
+- `fallback` - React node to show if not authorized
+
+### `<SignedIn>` / `<SignedOut>`
+
+Conditional rendering based on auth state:
+
+```tsx
+import { SignedIn, SignedOut } from '@insforge/react-router';
+
+function NavBar() {
+  return (
+    <nav>
+      <SignedOut>
+        <a href="/sign-in">Sign In</a>
+        <a href="/sign-up">Sign Up</a>
+      </SignedOut>
+
+      <SignedIn>
+        <a href="/dashboard">Dashboard</a>
+        <UserButton />
+      </SignedIn>
+    </nav>
+  );
+}
+```
+
+---
+
+## Hooks
+
+### `useAuth()`
+
+Access authentication methods and state:
+
+```tsx
+import { useAuth } from '@insforge/react-router';
+
+function LoginButton() {
+  const { signIn, signUp, signOut, isSignedIn, isLoaded } = useAuth();
+
+  const handleSignIn = async () => {
+    try {
+      await signIn('user@example.com', 'password');
+    } catch (error) {
+      console.error('Sign in failed:', error);
+    }
+  };
+
+  if (!isLoaded) return <div>Loading...</div>;
+
+  return (
+    <button onClick={isSignedIn ? signOut : handleSignIn}>
+      {isSignedIn ? 'Sign Out' : 'Sign In'}
+    </button>
+  );
+}
+```
+
+**Returns:**
+
+- `signIn(email, password)` - Sign in with email/password
+- `signUp(email, password)` - Sign up new user
+- `signOut()` - Sign out current user
+- `isSignedIn` - Boolean auth state
+- `isLoaded` - Boolean loading state
+
+### `useUser()`
+
+Access current user data:
+
+```tsx
+import { useUser } from '@insforge/react-router';
+
+function UserProfile() {
+  const { user, isLoaded, updateUser } = useUser();
+
+  if (!isLoaded) return <div>Loading...</div>;
+  if (!user) return <div>Not signed in</div>;
+
+  const handleUpdate = async () => {
+    await updateUser({ name: 'New Name' });
+  };
+
+  return (
+    <div>
+      <p>Email: {user.email}</p>
+      <p>Name: {user.name}</p>
+      <img src={user.avatarUrl} alt="Avatar" />
+      <button onClick={handleUpdate}>Update Name</button>
+    </div>
+  );
+}
+```
+
+**Returns:**
+
+- `user` - User object with id, email, name, avatarUrl
+- `isLoaded` - Boolean loading state
+- `updateUser(data)` - Update user profile
+
+### `usePublicAuthConfig()`
+
+Get your authentication config in InsForge:
+
+```tsx
+import { usePublicAuthConfig } from '@insforge/react-router';
+
+function SignInPage() {
+  const { authConfig, isLoaded } = usePublicAuthConfig();
+
+  if (!isLoaded) return <div>Loading...</div>;
+
+  return (
+    <div>
+      <p>Available OAuth: {authConfig.oAuthProviders.join(', ')}</p>
+      <p>Password min length: {authConfig?.passwordMinLength}</p>
+    </div>
+  );
+}
+```
+
+**Returns:**
+
+- `authConfig` - Authentication Configuration you set in InsForge dashboard.
+- `isLoaded` - Boolean loading state
+
+<Warning>
+  **Performance**: Only use this hook in SignIn/SignUp components to avoid unnecessary API calls.
+</Warning>
+
+---
+
+## Advanced Features
+
+### Auth Change Callback
+
+Track authentication state changes:
+
+```tsx
+<InsforgeProvider
+  baseUrl={baseUrl}
+  onAuthChange={(user) => {
+    if (user) {
+      console.log('User signed in:', user.email);
+      analytics.identify(user.id);
+    } else {
+      console.log('User signed out');
+      analytics.reset();
+    }
+  }}
+>
+  {children}
+</InsforgeProvider>
+```