@authrobo/react 0.2.0 → 0.5.0

package/README.md

@@ -1,13 +1,25 @@
 # @authrobo/react
 
-Drop-in React sign-in for [AuthRobo](https://authrobo.com): a configurable social
-button and an auth modal/panel that renders exactly the sign-in methods you've
-enabled in your AuthRobo dashboard (Google, LinkedIn, GitHub, Apple, email).
+Drop-in React sign-in for [AuthRobo](https://authrobo.com). Renders exactly the
+methods you've enabled in your dashboard — social providers (Google, LinkedIn,
+GitHub, Apple) plus an email switcher (**Magic Link · Register · Login**) — or
+compose your own UI from a single configurable button.
 
 ```bash
 npm i @authrobo/react
 ```
 
+## Contents
+
+- [Quick start](#quick-start) — the whole box: `<AuthRoboAuth>`
+- [Just one button](#just-one-button) — `<AuthRoboButton>`, single or mapped
+- [Two ways to sign in](#two-ways-to-sign-in-direct-vs-proxied) — direct vs. `startPath`
+- [The proxy server contract](#the-proxy-server-contract) — routes your app implements
+- [Theming](#theming)
+- [API](#api)
+
+---
+
 ## Quick start
 
 Wrap your app once with your AuthRobo config:
@@ -18,7 +30,7 @@ import { AuthRoboProvider } from "@authrobo/react";
 <AuthRoboProvider
   config={{
     issuerUrl: "https://authrobo.com",
-    clientId: process.env.NEXT_PUBLIC_AUTHROBO_CLIENT_ID!, // arc_...
+    clientId: process.env.NEXT_PUBLIC_AUTHROBO_CLIENT_ID!, // arc_...  (public)
     redirectUri: "https://yourapp.com/auth/callback",
   }}
 >
@@ -26,18 +38,8 @@ import { AuthRoboProvider } from "@authrobo/react";
 </AuthRoboProvider>;
 ```
 
-### A single provider button
-
-```tsx
-import { AuthRoboButton } from "@authrobo/react";
-
-<AuthRoboButton provider="linkedin" />;
-```
-
-### The auto-configured auth panel / modal
-
-`<AuthRoboAuth>` calls AuthRobo's public `/api/v1/config` endpoint and renders a
-button for every method you've turned on — no need to hard-code the list.
+Then drop in the full widget. It calls AuthRobo's public `/api/v1/config` and
+renders only what you've enabled:
 
 ```tsx
 import { AuthRoboAuth } from "@authrobo/react";
@@ -51,26 +53,151 @@ const [open, setOpen] = useState(false);
 <AuthRoboAuth mode="modal" open={open} onClose={() => setOpen(false)} />
 ```
 
-## How the flow works
+**What the email switcher collects** (each tab shows exactly its flow's fields):
+
+| Tab | Fields | Result |
+| --- | --- | --- |
+| **Magic Link** | email | a one-time sign-in link is emailed |
+| **Register** | name · email · password | creates the account |
+| **Login** | email · password | signs in |
+
+Magic Link is first; a tab only appears if its method is enabled (`magic_link`
+for Magic Link, `password` for Register + Login).
+
+## Just one button
+
+Don't want the whole box? Use `<AuthRoboButton>` — it takes a `provider` and
+renders that provider's branded button. Perfect for a single "Continue with
+Google", or map an array to lay them out however your design wants:
+
+```tsx
+import { AuthRoboButton } from "@authrobo/react";
+
+// one button
+<AuthRoboButton provider="google" />
+
+// your own set, your own layout
+<div className="grid gap-2">
+  {["google", "linkedin", "github"].map((p) => (
+    <AuthRoboButton key={p} provider={p} />
+  ))}
+</div>
+
+// custom label / classes
+<AuthRoboButton provider="github" label="Sign in with GitHub" className="my-btn" />
+```
+
+`provider` is any enabled method (`"google" | "linkedin" | "github" | "apple" |
+"facebook" | "password" | "magic_link"`). Clicking begins that flow via
+`startSignIn` — pass `startPath` here too if you proxy (see below).
+
+### Neutral or branded buttons
+
+By default social buttons share one consistent, themeable chrome (`buttonStyle="neutral"`).
+Switch to `buttonStyle="branded"` to give each button its provider's own colours —
+LinkedIn blue, GitHub black, Google white with a Google-blue label, Facebook blue,
+Apple black (monochrome glyphs flip to white for legibility):
+
+```tsx
+<AuthRoboAuth buttonStyle="branded" />
+<AuthRoboButton provider="linkedin" buttonStyle="branded" />
+```
 
-Clicking a method navigates the browser to AuthRobo's hosted flow. After the user
-authenticates, AuthRobo redirects back to your `redirectUri` with a one-time
-`code`. **Your backend** exchanges that code (with your `client_secret`, kept
-server-side) for tokens — e.g. via [`@authrobo/sdk`](https://www.npmjs.com/package/@authrobo/sdk)'s
-`exchange()`. This package never sees your secret.
+## Loading &amp; the config cache
+
+`<AuthRoboProvider>` **prefetches** your app's enabled methods the moment it
+mounts — i.e. on app start — and caches them per `(issuer, clientId)`. So by the
+time a login modal or page opens, the methods are already resolved: no
+request-on-open, no flash. (Not using the provider? Call `prefetchAppConfig(config)`
+yourself on app start.) While anything is loading, a theme-aware `<Spinner>` is
+shown (it inherits `currentColor`, so it matches whatever you've themed).
+
+## Two ways to sign in (direct vs. proxied)
+
+The same components support two flows; pick with the `startPath` prop.
+
+**Direct (default).** No backend beyond one callback. Social buttons redirect to
+the provider; the Login/Register forms do a native cross-origin form POST to
+AuthRobo's `authorize` endpoint; Magic Link posts to `magic/start`. AuthRobo
+returns to your `redirectUri` with a one-time `code`; your server exchanges it
+(with your `client_secret`) for tokens. Credentials go straight to AuthRobo —
+never to your own server.
+
+```tsx
+<AuthRoboAuth />              // uses config.redirectUri
+```
+
+**Proxied (`startPath`).** Best when you keep the session in **httpOnly
+cookies**. Every action is proxied through your own server so the CSRF state
+cookie and the token exchange stay first-party. Password login/register become a
+same-origin JSON POST that sets your cookies with **no page redirect**, so
+`onSuccess` fires and you can close your modal in place:
+
+```tsx
+<AuthRoboAuth
+  startPath="/api/auth"
+  onSuccess={() => { refreshSession(); close(); }}
+/>
+```
+
+> **Note:** in direct mode the password field lives in your app's DOM (submitted
+> to AuthRobo). If you require the credential entry to be isolated on AuthRobo's
+> origin, use `<AuthRoboButton provider="password" />`, which redirects to the
+> hosted page instead.
+
+## The proxy server contract
+
+When you pass `startPath`, the components call these routes on **your** server
+(shown for `startPath="/api/auth"`). Each one forwards to AuthRobo and manages
+your session cookies:
+
+| Trigger | Request | Your route should |
+| --- | --- | --- |
+| Social button | `GET /api/auth/{provider}/start` | set a CSRF state cookie, redirect to AuthRobo's provider start with your callback as `redirect_uri` |
+| Login | `POST /api/auth/login` `{ email, password }` | password-grant to AuthRobo, set httpOnly cookies, `2xx` |
+| Register | `POST /api/auth/register` `{ name?, email, password }` | create + set cookies, `2xx` |
+| Magic Link | `POST /api/auth/magic` `{ email }` | call AuthRobo `magic/start`, `2xx` |
+| Callback | `GET /api/auth/{method}/callback?code=…` | exchange the code (+ `client_secret`) for tokens, set cookies |
+
+On a non-`2xx`, return `{ "error": "message" }` — the widget shows it inline.
+(See AuthRobo's docs for a copy-pasteable Next.js implementation of these routes.)
+
+## Theming
+
+Styling is self-contained and theme-aware (light/dark via `prefers-color-scheme`
+or a `data-theme` attribute). Override any CSS variable on an ancestor to brand
+it — e.g. `--authrobo-accent` / `--authrobo-accent-fg` recolour the active tab
+and the primary button:
+
+```css
+.my-auth .authrobo-stack,
+.my-auth .authrobo-btn {
+  --authrobo-accent: #f5b81d;
+  --authrobo-accent-fg: #1c1400;
+  --authrobo-input-bg: #070f1d;
+  --authrobo-btn-bg: #070f1d;
+  --authrobo-tabs-bg: #070f1d;
+}
+```
+
+Other tokens: `--authrobo-btn-*`, `--authrobo-input-fg`, `--authrobo-title-fg`,
+`--authrobo-muted`, `--authrobo-divider-*`, `--authrobo-focus`, `--authrobo-error`.
 
 ## API
 
-- `AuthRoboProvider({ config, children })` — supplies config via context.
-- `AuthRoboButton({ provider, config?, label?, className?, style?, onClick? })` —
-  one branded button. `provider` is `"google" | "linkedin" | "github" | "apple" | "password"`.
-- `AuthRoboAuth({ config?, mode?, open?, onClose?, title?, methods? })` — renders
-  all enabled methods; `methods` can restrict/reorder them.
-- `useAppConfig(config?)` → `{ data, loading, error }` — the app's branding +
-  enabled methods.
-- `startSignIn(config, method, opts?)` — imperatively begin a flow.
+- `AuthRoboProvider({ config, children })` — supplies config via context **and
+  prefetches** the app config on mount.
+- `AuthRoboButton({ provider, config?, label?, className?, style?, onClick?, startPath?, lastUsed?, buttonStyle? })` —
+  one button. `provider` is any enabled `Method`; `buttonStyle` is `"neutral" | "branded"`.
+- `AuthRoboAuth({ config?, mode?, open?, onClose?, onSuccess?, title?, showHeader?, methods?, startPath?, buttonStyle? })` —
+  the full widget: social buttons + the email switcher. `methods` restricts/reorders;
+  `showHeader={false}` hides the logo/title row when you supply your own heading.
+- `useAppConfig(config?)` → `{ data, loading, error }` — branding + enabled methods (cached).
+- `prefetchAppConfig(config)` → `Promise<void>` — warm the cache on app start.
+- `useLastMethod(clientId)` → `Method | null` — the method last used on this client.
+- `startSignIn(config, method, opts?)` — imperatively begin a flow. `opts`:
+  `{ state?, loginHint?, screen?: "login" | "register" | "magic", startPath? }`.
+- `Spinner({ style?, className? })` — the theme-aware loading spinner.
+- `PROVIDER_META` / `BRAND_STYLE` — `{ label, icon }` and the branded palette per method.
 
 `config` can come from `<AuthRoboProvider>` or be passed per-component.
-
-Styling is self-contained (no CSS import needed); pass `className`/`style` to
-override, or restyle the `.authrobo-*` classes.