Initial Commit

packages/ui/react/react-auth/src/components/auth-provider/auth-provider.md

@@ -0,0 +1,56 @@
+# `auth-provider`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+`auth-provider.tsx` is a thin back-compatibility re-export shim that forwards `AuthContext`, `AuthProvider`, `useAuth`, and the associated types from the canonical implementation at `src/context/auth-context.tsx`. Upstream consumers of `@suaveplan/react-auth` historically imported `AuthProvider` from `@suaveplan/react-auth` (re-exported through `components/auth-provider/auth-provider.tsx`). The migration keeps that path stable so apps porting from upstream continue to compile without touching imports. Internally everything points at the single implementation; there is no duplicate state machine, no parallel context, and no diverging behaviour. Tests, stories, and Wave-2 forms will all consume the same context value regardless of which import path the caller picks.
+
+## Features
+
+- Stable backward-compatible import path.
+- Single source of truth — re-exports the canonical context.
+- Identical runtime behaviour to the canonical surface.
+
+## Usage: Basic
+
+```tsx
+import { AuthProvider } from "@suaveplan/react-auth/components/auth-provider";
+
+<AuthProvider config={{ baseURL: "https://auth.example.com" }}>
+    <App />
+</AuthProvider>;
+```
+
+## Usage: Advanced
+
+```tsx
+import {
+    AuthContext,
+    AuthProvider,
+    type AuthContextValue,
+} from "@suaveplan/react-auth/components/auth-provider";
+import { useContext } from "react";
+
+function DebugBadge() {
+    const ctx = useContext(AuthContext) as AuthContextValue | undefined;
+    return <span>{ctx?.isAuthenticated ? "in" : "out"}</span>;
+}
+```
+
+## API Reference
+
+This module re-exports the following from `src/context/auth-context.tsx`:
+
+- `AuthContext` — React Context handle.
+- `type AuthContextValue` — full context payload.
+- `AuthProvider` — provider component.
+- `type AuthProviderProps` — provider prop shape.
+- `type AuthState` — state-block shape.
+- `useAuth` — context-reading hook.
+
+## Implementation Notes
+
+The re-export is a single `export { ... } from "../../context/auth-context.js"` statement so Tree-shaking sees both paths as the same module under `sideEffects: false`. No additional runtime code lives here — every symbol is forwarded by name with no namespace wrapping. The path exists purely for ergonomics: callers porting from upstream do not need to grep-replace import statements as part of the migration. Wave 2 form components and Wave 3 page components will continue to use the canonical `context/auth-context.js` path internally for their imports to keep the dependency tree flat.