@poly-x/react 0.1.1 → 0.3.0

package/README.md

@@ -41,11 +41,138 @@ function Dashboard() {
 Add a callback route (`/auth/callback`) that renders `<AuthCallback />` to
 complete sign-in.
 
+## Profile self-service
+
+`<UserProfile>` gives a signed-in person a dialog to correct their own details —
+first name, last name, phone number, national ID, gender and photo. You write no
+form, no validation rules and no upload handling:
+
+```tsx
+import { UserProfile } from "@poly-x/react";
+
+<UserProfile onSaved={() => router.refresh()} />;
+```
+
+Most apps want it on the account menu instead of as its own button:
+
+```tsx
+<UserButton showUserProfile />
+```
+
+That turns the existing **Manage account** entry into one that opens the dialog.
+It is opt-in, and `manageAccountUrl` always wins — so an app already linking that
+entry to its own page keeps exactly what it has.
+
+Requires `@poly-x/next`'s route handler to be mounted (the platform call is made
+server-side; the browser never holds a credential). Validation mirrors the
+platform's own rules, so a value the dialog accepts is one the platform accepts.
+
+Editing anybody **else's** profile is not offered here — that is administration,
+and it lives in the PolyX console with the permission model and audit trail.
+Email, username and password are likewise excluded: each has its own verification
+path that a profile form must not route around.
+
+## Signing in silently, and switching workspace
+
+Someone already signed into another application on the same domain should not be asked for a
+password again. `useWarmHop()` tries that once when your sign-in screen mounts:
+
+```tsx
+import { useWarmHop, SignIn } from "@poly-x/react";
+
+export default function SignInPage() {
+  const hop = useWarmHop();
+  if (hop.status !== "settled") return null;                 // never a half-drawn form
+  if (hop.result.status === "signed_in") router.replace("/");
+  return <SignIn />;                                          // the ordinary path
+}
+```
+
+A failed attempt is invisible on purpose. Someone who is genuinely signed out pays the whole
+cost of this and gains nothing from it, so there is a hard timeout, nothing in the flow
+navigates, and every failure — offline, slow platform, unexpected response — ends at "show the
+form" rather than at an exception or a spinner.
+
+The attempt runs **once per tab**. The marker lives in `sessionStorage` rather than component
+state because the fall-back renders the sign-in page, which is a route change in most apps — a
+guard in state would reset at exactly the moment it needs to hold. Call `resetWarmHop()` after
+signing out so the next sign-in may try again.
+
+### Switching workspace
+
+Someone with access to several workspaces can move between them without a password:
+
+```tsx
+import { switchWorkspace } from "@poly-x/react";
+
+const result = await switchWorkspace(tenantId);
+if (result.status === "signed_in") router.refresh();          // now scoped to that workspace
+if (result.status === "no_access") showNoAccess();
+```
+
+When someone has more than one workspace and none was named, the settled result is
+`{ status: "select_workspace", workspaces }` — the SDK never picks for you, because putting
+someone to work in the wrong tenant without their noticing is worse than asking:
+
+```tsx
+const hop = useWarmHop();
+if (hop.status === "settled" && hop.result.status === "select_workspace") {
+  return <WorkspacePicker options={hop.result.workspaces} onPick={switchWorkspace} />;
+}
+```
+
+Entitlement is decided **by the platform at the moment of the switch**, not from the list you are
+holding, so a workspace revoked since you drew the picker never lets them in. What you get back
+depends on what is left: still hold other workspaces and you get `select_workspace` listing them;
+lost them all and you get `no_access`. Either way, not entry — so do not cache the decision in
+front of it.
+
+### When the workspace you asked for is quietly ignored
+
+Worth knowing, because success is not always what it looks like. PolyX only honours a workspace
+hint when the person has **more than one** workspace for that application. With exactly one, it
+ignores the hint and seats them there anyway — answering an ordinary success. Nobody gains access
+they are not entitled to, but they can end up **working in the wrong tenant without noticing**,
+which is the failure the picker exists to prevent.
+
+The SDK will not relay that as plain success. Pass a **tenant id** and land somewhere else, and you
+get `workspace_mismatch` carrying both:
+
+```tsx
+const result = await switchWorkspace(tenantId);
+if (result.status === "workspace_mismatch") {
+  // result.requested — what you asked for
+  // result.workspace — where they actually are now
+}
+```
+
+The session is left in place: it is valid, and you may be perfectly happy with it. What to do about
+it is your call, not the SDK's.
+
+An **organization code or slug** cannot be compared against what a session carries, so no mismatch
+is claimed for those — guessing would invent failures. Instead **every** successful result names
+the workspace actually entered, so you can check for yourself:
+
+```tsx
+if (result.status === "signed_in" && result.workspace !== expected) { /* … */ }
+```
+
+Switching does not navigate or reload — the SDK cannot know what is unsaved on your screen, so
+what happens next is yours to decide.
+
+### The boundary
+
+Silent sign-on works between applications that **share the ecosystem cookie's domain**.
+Browsers block third-party cookies by default, so an application on an unrelated domain falls
+back to ordinary sign-in. That is browser policy, not something to configure around.
+*Switching workspace is unaffected* — it happens inside one application.
+
 ## API
 
 `PolyXProvider` · `useAuth` (`isLoaded`, `isSignedIn`, `signIn`, `signOut`,
 `getToken`) · `useUser` · `useSession` · `<SignIn>` · `<Protected>` ·
-`<AuthCallback>`. Sign-in defaults to a popup; pass `mode="redirect"` for a
-full-page flow.
+`<UserButton>` · `<UserProfile>` · `<AuthCallback>` · `useWarmHop` ·
+`attemptWarmHop` · `switchWorkspace` · `resetWarmHop`. Sign-in defaults to a
+popup; pass `mode="redirect"` for a full-page flow.
 
 MIT licensed.