@zoreal/oauth2-react 0.2.19 → 0.2.21

package/README.md

@@ -89,10 +89,10 @@ import { ZorealOAuthProvider } from '@zoreal/oauth2-react';
 ```
 
 ```tsx
-// ZorealSignIn.tsx
-import { useZorealLogin } from '@zoreal/oauth2-react';
+// ZorealSignIn.tsx — your own button, styled your way.
+import { useZorealLogin, ZorealMark } from '@zoreal/oauth2-react';
 
-function ZorealSignIn() {
+function ZorealSignIn({ onSignedIn }: { onSignedIn: () => void }) {
   // `email` (and profile.name, etc.) are returned from /userinfo on your backend.
   const login = useZorealLogin({
     flow: 'auth-code',
@@ -102,28 +102,42 @@ function ZorealSignIn() {
       // code and verifier plus its client authentication, verifies the ID
       // token's nonce is this one, then reads the email and name from
       // /userinfo. That is where personal data is delivered.
-      await fetch('/api/auth/zoreal', {
+      const res = await fetch('/api/auth/zoreal', {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({ code, code_verifier, nonce }),
       });
+      if (res.ok) onSignedIn();
     },
     onError: (e) => console.error(e.description ?? e.error),
     onNonOAuthError: (e) => {
-      // The holder closing or ignoring the request is not an error to surface.
-      if (e.type === 'request_denied' || e.type === 'request_expired') return;
+      // The holder declining or ignoring the request, or closing the dialog,
+      // is not an error to surface: the button is simply ready again.
+      if (e.type === 'request_denied' || e.type === 'request_expired' || e.type === 'popup_closed') return;
       console.error(e.description ?? e.type);
     },
   });
 
-  return <button onClick={login}>Continue with ZOREAL</button>;
+  // Pass the click through as it is. The SDK takes the button from it, holds it
+  // busy with the pairing modal's light round it until the login ends, and lets
+  // it go on every outcome. No wrapper, no busy state of your own.
+  return (
+    <button type="button" onClick={login}>
+      <ZorealMark size={22} brand />
+      Continue with ZOREAL
+    </button>
+  );
 }
 ```
 
-That is the whole integration. When `login()` runs, the provider puts the
-pairing modal on screen; on a phone it skips the QR and opens the ZOREAL ID
-app instead. See [The pairing modal](#the-pairing-modal) for what it does and
-how to theme, translate, time out or replace it.
+That is the whole integration. When `login()` runs on a computer, the provider
+puts the pairing modal on screen and the button you tapped waits, disabled, with
+the light round it. On a phone the tap itself navigates to the provider, which
+opens the ZOREAL ID app; once the person has approved, the app brings them back
+to this page, and the same hook finishes the sign-in and calls your `onSuccess`
+there. So mount this component on the page the sign-in starts from, and expect
+`onSuccess` on a fresh page load. See [The pairing modal](#the-pairing-modal)
+for what it does and how to theme, translate, time out or replace it.
 
 ## Quick start: the button (no backend, pseudonymous)
 
@@ -251,7 +265,7 @@ What the modal does:
 
 | | |
 | --- | --- |
-| **Mobile** | No QR and no modal. The tap itself is a navigation: the SDK sends the tab to the provider's `/pair/start` with the pairing's parameters, synchronously from the click, and the provider answers with a redirect to the pairing's universal link, which the ZOREAL ID app claims while the page stays put and polls. A browser hands a link to an app only inside a navigation the person began, which is why nothing is fetched first. With no app installed the same redirect lands on the page that installs it. Call `login()` from the click handler itself: `ZorealLogin` does, disables itself and runs a light round its edge until the flow ends. Once the holder has approved, the app reopens your page with the pairing named in the fragment, and the first `useZorealLogin` or `ZorealLogin` on that page finishes the sign-in there, through the same `onSuccess` and `onError`; the tab that was left behind stands down when the returned page finishes first; a site with its own button keeps that button and draws its own busy state from the tap until `onSuccess` or `onError` fires, or wraps it in `ZorealBusyRing` to get the same light (a wrapper: pass `block` for a full-width button, keep `overflow: hidden` off its ancestors, and expect `.parent > button` selectors to stop matching). Force one or the other with `display: 'qr'` / `'link'`. |
+| **Mobile** | No QR and no modal. The tap itself is a navigation: the SDK sends the tab to the provider's `/pair/start` with the pairing's parameters, synchronously from the click, and the provider answers with a redirect to the pairing's universal link, which the ZOREAL ID app claims while the page stays put and polls. A browser hands a link to an app only inside a navigation the person began, which is why nothing is fetched first. With no app installed the same redirect lands on the page that installs it. Pass the click event through to `login` (`onClick={login}`): the SDK takes the button from it, disables it and runs the light round it until the flow ends, then lets it go, on every outcome. `ZorealLogin` does the same for itself. Once the holder has approved, the app reopens your page with the pairing named in the fragment, and the first `useZorealLogin` or `ZorealLogin` on that page finishes the sign-in there, through the same `onSuccess` and `onError`; the tab that was left behind stands down when the returned page finishes first; a site with its own button gets the same by passing the click to `login`; `ZorealBusyRing` remains for a site that wants to drive the light itself (a wrapper: pass `block` for a full-width button, keep `overflow: hidden` off its ancestors, and expect `.parent > button` selectors to stop matching). Force one or the other with `display: 'qr'` / `'link'`. |
 | **Live status** | The copy and the title follow the pairing: waiting for a scan, then waiting for approval once the holder has claimed the code (the spent QR blurs out behind a phone glyph). |
 | **Title** | Says what the scan is for, inferred from the request: "Scan to sign in" for `openid`, `email` and `profile.name`; "Scan to verify your identity" once a document attribute such as `zoreal.age` or `profile.birthdate` is requested; "Scan to prove you are a real human" for `openid` alone with `acr_values: 'zoreal.live'`. Override with `intent`, one of `'sign-in'`, `'identify'`, `'presence'`, when the scope does not say. |
 | **Countdown** | Counts down to expiry, turning amber under 20s. Reads the clock each tick rather than decrementing, so a backgrounded tab comes back honest. |
@@ -577,28 +591,26 @@ error path.
 
 ## A complete example
 
-A full sign-in component, end to end — the shape a real auth-code integration
-takes. It renders the button, renders its own pairing UI (the hook renders
-none), hands `{ code, code_verifier, nonce }` to your backend on success, and
-treats the decline/expiry path as the non-events they are.
+A full sign-in component, end to end, the shape a production auth-code
+integration takes: your own button, held busy by the SDK from the tap until
+the flow ends, the SDK's pairing modal on a computer and the app hand-over on
+a phone, `{ code, code_verifier, nonce }` to your backend on success, the human
+outcomes treated as the non-events they are, and the return from the app on a
+phone handled by the same hook.
 
 ```tsx
 import { useState } from 'react';
-import { ZorealOAuthProvider, useZorealLogin } from '@zoreal/oauth2-react';
-import type { PairingState } from '@zoreal/oauth2-react';
+import { ZorealOAuthProvider, useZorealLogin, ZorealMark } from '@zoreal/oauth2-react';
 
 function ZorealSignIn() {
-  const [pairing, setPairing] = useState<PairingState | null>(null);
   const [note, setNote] = useState<string | null>(null);
 
   const login = useZorealLogin({
     flow: 'auth-code',
     scope: 'openid email profile.name',
     // acr_values: 'zoreal.live',  // request a fresh liveness for a step-up / high-value login
-    onPairingStateChange: setPairing,
 
     onSuccess: async ({ code, code_verifier, nonce }) => {
-      setPairing(null);
       // Post ALL THREE to YOUR backend over TLS. Your backend does the /token
       // exchange with its client authentication, verifies the ID token
       // (ES256 against the JWKS, iss/aud/exp, and this nonce), checks the acr
@@ -619,38 +631,26 @@ function ZorealSignIn() {
     },
 
     // An OAuth error from the provider (e.g. a scope not on your allow list).
-    onError: (e) => {
-      setPairing(null);
-      setNote(e.description ?? e.error); // the provider's words, verbatim
-    },
+    onError: (e) => setNote(e.description ?? e.error), // the provider's words, verbatim
 
-    // The human outcomes: declined, expired, cancelled. Not faults — clear the
-    // pairing UI and let them try again. Do not alarm on these.
+    // The human outcomes: declined, expired, the dialog closed. Not faults:
+    // the button is ready again. Do not alarm on these.
     onNonOAuthError: (e) => {
-      setPairing(null);
       if (e.type === 'request_denied') setNote('Login was declined. Try again when ready.');
       else if (e.type === 'request_expired') setNote('That took too long. Try again.');
+      else if (e.type === 'popup_closed') setNote(null);
       else setNote('Something went wrong. Try again.');
     },
   });
 
   return (
     <div>
-      <button onClick={login}>Continue with ZOREAL</button>
-
-      {/* The hook renders nothing, so the pairing UI is yours. On desktop the
-          login cannot complete until something shows pairing.qrUrl to scan. */}
-      {pairing && !pairing.appLink && ['pending', 'claimed'].includes(pairing.status) && (
-        <div role="dialog" aria-label="Log in with ZOREAL">
-          <img src={pairing.qrUrl} alt="Log in with ZOREAL" width={200} height={200} />
-          <p>
-            {pairing.status === 'claimed'
-              ? 'Approve the login in your ZOREAL ID app.'
-              : 'Scan with your phone camera or the ZOREAL ID app.'}
-          </p>
-          <button onClick={pairing.cancel}>Cancel</button>
-        </div>
-      )}
+      {/* The click goes through as it is: the SDK holds this button busy, with
+          the light round it, until the login ends. */}
+      <button type="button" onClick={login}>
+        <ZorealMark size={22} brand />
+        Continue with ZOREAL
+      </button>
 
       {note && <p role="status">{note}</p>}
     </div>
@@ -659,13 +659,20 @@ function ZorealSignIn() {
 
 export default function App() {
   return (
-    <ZorealOAuthProvider clientId="ast_your_asset_id">
+    <ZorealOAuthProvider clientId="ast_your_asset_id" locale="en" theme="auto">
       <ZorealSignIn />
     </ZorealOAuthProvider>
   );
 }
 ```
 
+On a computer the provider renders the pairing modal for this button; nothing
+here draws a QR. To draw your own instead, see
+[Rendering it yourself](#rendering-it-yourself). On a phone there is no dialog:
+the tap navigates to the provider, the ZOREAL ID app opens, and after the
+approval the app reopens this page, where `useZorealLogin` finishes the sign-in
+and `onSuccess` runs on that fresh page load.
+
 **The backend must verify.** This component only starts the flow and forwards a
 code; on its own it proves nothing. The security is your backend exchanging the
 code with its client authentication and verifying the signed ID token — use a

package/dist/index.cjs

@@ -25,6 +25,7 @@ __export(index_exports, {
   PairingModal: () => PairingModal,
   ZorealBusyRing: () => ZorealBusyRing,
   ZorealLogin: () => ZorealLogin,
+  ZorealMark: () => ZorealMark,
   ZorealOAuthProvider: () => ZorealOAuthProvider,
   hasGrantedAllScopesZoreal: () => hasGrantedAllScopesZoreal,
   hasGrantedAnyScopeZoreal: () => hasGrantedAnyScopeZoreal,
@@ -41,7 +42,7 @@ var import_react2 = require("react");
 
 // src/wire.ts
 var WIRE_VERSION = 1;
-var SDK_VERSION = "0.2.19";
+var SDK_VERSION = "0.2.21";
 var DEFAULT_ISSUER = "https://id.zoreal.com";
 var POLL_INTERVAL_MS = 2e3;
 var POLL_INTERVAL_ENROLLING_MS = 5e3;
@@ -1396,6 +1397,16 @@ var CSS = `
   transition: opacity 200ms ease-out;
 }
 .${PREFIX}-ring[data-busy="true"] > .${PREFIX}-ring-svg { opacity: 1; }
+/* The same light as an overlay in the document body, placed over a site's
+   own control by the package itself (busy.ts): nothing of the site's
+   markup or CSS is touched, and neither an ancestor's overflow nor a
+   selector on the control's parent is affected. */
+.${PREFIX}-ring-overlay {
+  position: fixed;
+  display: block;
+  z-index: 2147483000;
+  pointer-events: none;
+}
 .${PREFIX}-ring-svg rect {
   --zrl-l: var(--zrl-ring-len, 600px);
   x: 2px;
@@ -1636,6 +1647,96 @@ var import_react5 = require("react");
 // src/useZorealLogin.ts
 var import_react3 = require("react");
 
+// src/busy.ts
+var SVG_NS = "http://www.w3.org/2000/svg";
+var TAIL = 0.3;
+var STACK = Array.from({ length: 12 }, (_, i) => 12 - i);
+var HALO = [3, 2, 1];
+function radiusOf(control) {
+  const value = parseFloat(getComputedStyle(control).borderTopLeftRadius);
+  return Number.isFinite(value) ? value : 8;
+}
+function holdBusy(control) {
+  if (typeof document === "undefined") return () => {
+  };
+  ensureStyles();
+  const hadDisabled = control.hasAttribute("disabled");
+  const hadBusy = control.getAttribute("aria-busy");
+  if (control instanceof HTMLButtonElement || control instanceof HTMLInputElement) {
+    control.disabled = true;
+  } else {
+    control.setAttribute("aria-disabled", "true");
+  }
+  control.setAttribute("aria-busy", "true");
+  const overlay = document.createElement("div");
+  overlay.className = `${cx("root")} ${cx("ring")} ${cx("ring-overlay")}`;
+  overlay.dataset.theme = "auto";
+  overlay.dataset.busy = "true";
+  overlay.setAttribute("aria-hidden", "true");
+  const svg = document.createElementNS(SVG_NS, "svg");
+  svg.setAttribute("class", cx("ring-svg"));
+  const rx = radiusOf(control) + 2;
+  const layer = (name, len, alpha) => {
+    const rect = document.createElementNS(SVG_NS, "rect");
+    rect.setAttribute("class", cx(name));
+    rect.setAttribute("rx", String(rx));
+    rect.setAttribute("ry", String(rx));
+    rect.style.strokeDasharray = `calc(var(--zrl-l) * ${len}) calc(var(--zrl-l) * ${1 - len})`;
+    rect.style.setProperty("--zrl-s", `calc(var(--zrl-l) * ${-(TAIL - len)})`);
+    rect.style.opacity = alpha;
+    svg.appendChild(rect);
+    return rect;
+  };
+  let measured = null;
+  for (const n of HALO) {
+    const rect = layer("ring-halo", TAIL * n / HALO.length, `calc(var(--zrl-glow-opacity) * 0.6 / ${n})`);
+    measured ?? (measured = rect);
+  }
+  for (const n of STACK) layer(n <= 2 ? "ring-head" : "ring-tail", TAIL * n / STACK.length, String(1 / n));
+  overlay.appendChild(svg);
+  document.body.appendChild(overlay);
+  let frame = 0;
+  const place = () => {
+    frame = 0;
+    const box = control.getBoundingClientRect();
+    overlay.style.left = `${box.left}px`;
+    overlay.style.top = `${box.top}px`;
+    overlay.style.width = `${box.width}px`;
+    overlay.style.height = `${box.height}px`;
+    const length = typeof measured?.getTotalLength === "function" ? measured.getTotalLength() : 0;
+    if (length > 0) overlay.style.setProperty("--zrl-ring-len", `${length}px`);
+  };
+  const schedule = () => {
+    if (!frame) frame = requestAnimationFrame(place);
+  };
+  place();
+  const observer = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(schedule);
+  observer?.observe(control);
+  window.addEventListener("scroll", schedule, true);
+  window.addEventListener("resize", schedule);
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    if (frame) cancelAnimationFrame(frame);
+    observer?.disconnect();
+    window.removeEventListener("scroll", schedule, true);
+    window.removeEventListener("resize", schedule);
+    overlay.remove();
+    if (control instanceof HTMLButtonElement || control instanceof HTMLInputElement) {
+      control.disabled = hadDisabled;
+    } else {
+      control.removeAttribute("aria-disabled");
+    }
+    if (hadBusy === null) control.removeAttribute("aria-busy");
+    else control.setAttribute("aria-busy", hadBusy);
+  };
+}
+function controlFrom(event) {
+  const target = event?.currentTarget;
+  return typeof HTMLElement !== "undefined" && target instanceof HTMLElement ? target : null;
+}
+
 // src/return.ts
 var PREFIX2 = "zoreal:oauth2:return:";
 var DONE = "zoreal:oauth2:done:";
@@ -2100,6 +2201,7 @@ function useZorealFlow(options) {
     () => () => {
       abortRef.current?.abort();
       publishRef.current?.(null);
+      releaseRef.current();
     },
     []
   );
@@ -2158,10 +2260,21 @@ function useZorealFlow(options) {
       }
     })();
   }, [clientId, issuer]);
-  const login = (0, import_react3.useCallback)(() => {
+  const releaseRef = (0, import_react3.useRef)(() => {
+  });
+  const login = (0, import_react3.useCallback)((event) => {
     const opts = optionsRef.current;
+    const control = controlFrom(event);
     const run = async () => {
       abortRef.current?.abort();
+      releaseRef.current();
+      releaseRef.current = control ? holdBusy(control) : () => {
+      };
+      const release = () => {
+        releaseRef.current();
+        releaseRef.current = () => {
+        };
+      };
       const controller = new AbortController();
       abortRef.current = controller;
       const flow = opts.flow;
@@ -2310,6 +2423,7 @@ function useZorealFlow(options) {
         setPairing(null);
         publishRef.current?.(null);
         if (returnId) markReturnDone(returnId);
+        release();
         if (flow === "auth-code") {
           opts.onCode?.({
             code,
@@ -2334,6 +2448,7 @@ function useZorealFlow(options) {
         };
         opts.onCredential?.(response);
       } catch (e) {
+        release();
         setPairing(null);
         publishRef.current?.(null);
         if (e instanceof DOMException && e.name === "AbortError") {
@@ -2382,9 +2497,9 @@ function useZorealLogin(options) {
 // src/ring.tsx
 var import_react4 = require("react");
 var import_jsx_runtime5 = require("react/jsx-runtime");
-var TAIL = 0.3;
-var STACK = Array.from({ length: 12 }, (_, i) => 12 - i);
-var HALO = [3, 2, 1];
+var TAIL2 = 0.3;
+var STACK2 = Array.from({ length: 12 }, (_, i) => 12 - i);
+var HALO2 = [3, 2, 1];
 function ZorealBusyRing({
   busy,
   radius = 8,
@@ -2423,7 +2538,7 @@ function ZorealBusyRing({
       ry: rx,
       style: {
         strokeDasharray: `calc(var(--zrl-l) * ${len}) calc(var(--zrl-l) * ${1 - len})`,
-        "--zrl-s": `calc(var(--zrl-l) * ${-(TAIL - len)})`,
+        "--zrl-s": `calc(var(--zrl-l) * ${-(TAIL2 - len)})`,
         opacity: alpha
       }
     },
@@ -2440,10 +2555,10 @@ function ZorealBusyRing({
       children: [
         children,
         /* @__PURE__ */ (0, import_jsx_runtime5.jsxs)("svg", { className: cx("ring-svg"), "aria-hidden": "true", children: [
-          HALO.map(
-            (n, i) => layer(`h${n}`, "ring-halo", TAIL * n / HALO.length, `calc(var(--zrl-glow-opacity) * 0.6 / ${n})`, i === 0 ? measureRef : void 0)
+          HALO2.map(
+            (n, i) => layer(`h${n}`, "ring-halo", TAIL2 * n / HALO2.length, `calc(var(--zrl-glow-opacity) * 0.6 / ${n})`, i === 0 ? measureRef : void 0)
           ),
-          STACK.map((n) => layer(`t${n}`, n <= 2 ? "ring-head" : "ring-tail", TAIL * n / STACK.length, String(1 / n)))
+          STACK2.map((n) => layer(`t${n}`, n <= 2 ? "ring-head" : "ring-tail", TAIL2 * n / STACK2.length, String(1 / n)))
         ] })
       ]
     }
@@ -2590,6 +2705,7 @@ function hasGrantedAnyScopeZoreal(response, firstScope, ...restScopes) {
   PairingModal,
   ZorealBusyRing,
   ZorealLogin,
+  ZorealMark,
   ZorealOAuthProvider,
   hasGrantedAllScopesZoreal,
   hasGrantedAnyScopeZoreal,