# `<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.