first commit

docs/ui/react/react-auth/src/pages/login/login.md

@@ -0,0 +1,67 @@
+# `<LoginPage>` — routing-aware login page
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+`<LoginPage>` is the routing-aware adapter that wraps the Wave 2 `<LoginForm>` with the navigation and auth-context wiring needed to drop into a `react-router-dom` v7 application. It applies a guest-only auth guard, calls `useAuth().signIn` on submit, redirects to `?returnTo` (or `/dashboard` as fallback) on success, and surfaces errors through the form's destructive alert via the `useAuth().error` field.
+
+Use this component for the sign-in route of a shipping application. For a customisable lower-level UI consider mounting `<LoginForm>` directly and wiring submission and navigation manually.
+
+## Features
+
+- `useAuthGuard({ requireGuest: true })` — already-authenticated visitors are redirected to `/`.
+- `?returnTo` query param honoured for post-login navigation; defaults to `/dashboard`.
+- `signIn` rejections are swallowed so the page never throws into a router error boundary.
+- Reads `useAuth().isLoading` to disable the submit button during the in-flight `signIn`.
+- Reads `useAuth().error` to render the destructive alert in the form.
+
+## Usage: Basic
+
+```tsx
+import { BrowserRouter, Route, Routes } from "react-router-dom";
+import { AuthProvider, LoginPage } from "@suaveplan/react-auth";
+
+export function App() {
+    return (
+        <AuthProvider config={{ baseURL: "https://auth.example.com" }}>
+            <BrowserRouter>
+                <Routes>
+                    <Route path="/auth/login" element={<LoginPage />} />
+                </Routes>
+            </BrowserRouter>
+        </AuthProvider>
+    );
+}
+```
+
+## Usage: Advanced
+
+When a protected route renders `<AuthGuard requireAuth fallback={<Navigate to={`/auth/login?returnTo=${path}`} />}>`, the user returns to the original path after sign-in:
+
+```tsx
+import { Navigate, useLocation } from "react-router-dom";
+
+function Protected({ children }) {
+    const { isAuthenticated } = useAuth();
+    const loc = useLocation();
+    if (!isAuthenticated) {
+        return <Navigate to={`/auth/login?returnTo=${loc.pathname}`} replace />;
+    }
+    return children;
+}
+```
+
+The `LoginPage` reads the `returnTo` search param via `useSearchParams` and routes the user back after a successful sign-in.
+
+## API Reference
+
+`<LoginPage>` accepts no props. It reads context via `useAuth()` and `useSearchParams()`.
+
+## Implementation Notes
+
+- The page mounts the Wave 2 `<LoginForm>` and never re-implements form-level concerns (Zod validation, react-hook-form wiring, password show/hide). Those remain in the form layer.
+- The submit handler is `async` and catches synchronously; nothing propagates to a React error boundary on a failed `signIn`.
+- The guard is a side-effect of `useAuthGuard` — the page still renders the form for one frame while the guard's `useEffect` schedules the redirect.