@tinvar/react 0.0.0-stage → 0.4.1

package/src/router-hooks.js

@@ -0,0 +1,234 @@
+// What a form does to the page after an action, through the router.
+//
+// An action's answer changes the page: a redirect to follow, a re-rendered
+// payload to mount, prefetch entries to drop, a flash to announce. The
+// router owns all of it -- the page, history, the prefetch cache, its
+// events -- so a form asks it, through its public API:
+//
+//   router.flushAll()               every prefetched page, after an action
+//                                   that went through; see
+//                                   flushAfterAction()
+//   router.applyPayload(payload, o) mounts a re-rendered payload as the page
+//                                   that is up: no request, no history, no
+//                                   scroll
+//   router.flash(flash, detail)     the router's `flash` event, which is
+//                                   also a native `tinvar:flash` event
+//   router.announce(name, detail)   the router's `actionStart`, `progress`
+//                                   and `actionSettle` events; see
+//                                   announceAction()
+//   router.revoke()                 a 401: everything held for the session,
+//                                   dropped, before the page is loaded
+//
+// The router is optional throughout. A form rendered without one -- no
+// RouterProvider, a server render, a test -- still posts: a redirect is a
+// full load, there is no prefetch cache to flush, and a flash or an action
+// event goes out as the native event alone.
+
+import { revokeSession } from './router.js';
+import { markDocumentLoad, reloadUnlessLoading } from './document-load.js';
+
+/**
+ * @typedef {Pick<import('./router.js').Router,
+ *   'visit' | 'reload' | 'routeTokens' | 'flushAll' | 'applyPayload' | 'flash' | 'revoke'
+ * > & Partial<Pick<import('./router.js').Router, 'flushInvalidated' | 'announce'>> | null | undefined} RouterLike
+ */
+
+/** The router's tokens for the pages it has mounted, which an action re-renders from. */
+export function routeTokens(/** @type {RouterLike} */ router) {
+  try {
+    const tokens = router?.routeTokens();
+    return Array.isArray(tokens) ? tokens.filter((t) => typeof t === 'string') : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Forgets every prefetched page once an action has gone through.
+ *
+ * Not only those its `X-Invalidated-Tags` names: an action can sign in, sign
+ * out or switch tenant, and a session rotated in a cookie script cannot read
+ * leaves nothing on the page to tell it by. Every page prefetched before it
+ * may have been rendered for the session that has just ended -- the next
+ * visit asks the server again.
+ *
+ * And by those it names, for what is kept beyond the prefetch cache: the
+ * content of a #[Once] field kept under one of the tags is no longer
+ * claimed, so the next page sends it fresh (ADR 0020). Only by its tags:
+ * whose session it was is the server's to check, on every request.
+ *
+ * @param {RouterLike} router
+ * @param {Headers} [headers] the action's response's
+ */
+export function flushAfterAction(router, headers) {
+  router?.flushAll();
+  if (headers !== undefined) router?.flushInvalidated?.(headers);
+}
+
+/**
+ * Follows an action's redirect: a client visit when there is a router, so
+ * the next page's layout reads the new session without a full load.
+ *
+ * Fresh, never from the prefetch cache: the page it leads to was most
+ * likely prefetched before the action, under whatever session the action
+ * may have just replaced.
+ *
+ * @param {RouterLike} router
+ * @param {string} href
+ * @param {Record<string, unknown>} options the visit options a form was given
+ * @param {(url: string) => void} hardNavigate
+ */
+export async function followRedirect(router, href, options, hardNavigate) {
+  if (router) {
+    await router.visit(href, { ...options, fresh: true });
+    return;
+  }
+  hardNavigate(href);
+}
+
+/**
+ * Puts the server's re-render of the page on screen.
+ *
+ * "The response carries a fresh RSC payload for affected mounted routes."
+ * The router sends one token, for the page it has up, so there is at most one
+ * payload, and it is this page's. An action that revalidated routes and sent
+ * no payload -- the page's pipeline denied, its token was refused, the server
+ * re-renders nothing -- means "reload that route yourself", and the router's
+ * reload does.
+ *
+ * Only while the page the action was sent from is still the one up, by the
+ * route token it was sent with. An action takes time, and a link followed
+ * meanwhile puts another page up: the re-render of the page left, mounted
+ * over it, showed the old page under the new one's URL, and a reload
+ * reloaded a page the action never touched.
+ *
+ * With the re-render's live token, when the server sent one under the same
+ * key (`live`, ADR 0048): what the page listens for from then on, handed on
+ * in the router's `success` event as a reload's is. Null is a token too --
+ * the re-render read nothing to listen for. No key at all leaves the page
+ * listening as it was.
+ *
+ * @param {RouterLike} router
+ * @param {Record<string, string> | null | undefined} payloads
+ * @param {string[]} revalidated
+ * @param {Record<string, unknown>} options
+ * @param {string | null} [sentFrom] the route token the action was sent with
+ * @param {unknown} [live] the action's `live`: page key to live token
+ * @returns {Promise<boolean>} whether the page on screen was re-rendered
+ */
+export async function applyPayloads(router, payloads, revalidated, options, sentFrom, live) {
+  if (!router) return false;
+
+  const entry = Object.entries(payloads ?? {}).find(([, p]) => typeof p === 'string');
+  if (entry !== undefined) {
+    const [key, payload] = entry;
+    /** @type {Record<string, unknown>} */
+    const opts = sentFrom === undefined ? { ...options } : { ...options, routeToken: sentFrom };
+    if (live !== null && typeof live === 'object' && !Array.isArray(live) && Object.hasOwn(live, key)) {
+      const token = /** @type {Record<string, unknown>} */ (live)[key];
+      opts.liveToken = typeof token === 'string' ? token : null;
+    }
+    return router.applyPayload(payload, opts);
+  }
+
+  if (revalidated.length > 0) {
+    if (sentFrom !== undefined && (routeTokens(router)[0] ?? null) !== sentFrom) return false;
+    // Refused, as a payload is, while the user's own visit is in flight.
+    return (
+      (await router.reload(sentFrom === undefined ? options : { ...options, routeToken: sentFrom })) !== false
+    );
+  }
+
+  return false;
+}
+
+/**
+ * The session is over: the server answered 401. "Session revocation, which
+ * the server signals with a 401", is cleared "with a full page load"
+ * (tinvar-spec.md, "Client-held data") -- here as on a navigation, and not
+ * the caller's to cancel. The load alone was not the clearing: what
+ * useRemember() and useForm() kept is in the tab's storage, which outlives
+ * the document, and the reloaded page read it back under the same session
+ * hash.
+ *
+ * What the session held goes at once; the load leaves a document load
+ * already begun to arrive. An action that ended the session -- a sign-out,
+ * a reset -- sent the browser on with one, and a form, a call or an upload
+ * refused meanwhile for the session it ended reloaded the page being left
+ * over it, and landed the browser back there (document-load.js).
+ *
+ * @param {RouterLike} router
+ * @param {(url: string) => void} hardNavigate
+ */
+export function endSession(router, hardNavigate) {
+  revokeSession(router);
+  reloadUnlessLoading(hardNavigate);
+}
+
+/**
+ * A full page load, for what the router cannot do in place: an external
+ * location, a revoked session.
+ *
+ * @param {string} url
+ */
+export function assignLocation(url) {
+  // http(s) on any origin, and nothing else: a javascript: URL from a
+  // response header would run.
+  let target;
+  try {
+    target = new URL(url, globalThis.location.href);
+  } catch {
+    return;
+  }
+  if (target.protocol !== 'http:' && target.protocol !== 'https:') return;
+  markDocumentLoad(target.href);
+  globalThis.location.assign(target.href);
+}
+
+/**
+ * Tells the page an action flashed something: through the router, so
+ * `router.on('flash')` hears it as well as anything listening for the
+ * native `tinvar:flash` event -- or, without a router, as that event alone.
+ *
+ * @param {RouterLike} router
+ * @param {Record<string, unknown>} flash
+ * @param {string} action
+ */
+export function announceFlash(router, flash, action) {
+  if (Object.keys(flash).length === 0) return;
+  if (router) {
+    router.flash(flash, { action });
+    return;
+  }
+  if (typeof document === 'undefined') return;
+  document.dispatchEvent(new CustomEvent('tinvar:flash', { detail: { flash, action } }));
+}
+
+/**
+ * Tells the page about an action call: tinvar-spec.md's RSC events
+ * `actionStart` and `actionSettle`, and `progress` as its files upload --
+ * Inertia's `progress` event, which is a form's upload, since here a form
+ * posts to an action and a visit is a GET with nothing to upload. Through
+ * the router, so `router.on()` hears them as well as anything listening for
+ * the native `tinvar:<name>` events -- or, without one, as those alone.
+ *
+ * Never a reason for the call to fail: a listener's exception is reported
+ * by the router, and anything the router itself throws is reported here.
+ *
+ * @param {RouterLike} router
+ * @param {'actionStart' | 'progress' | 'actionSettle'} name
+ * @param {Record<string, unknown>} detail
+ */
+export function announceAction(router, name, detail) {
+  if (typeof router?.announce === 'function') {
+    try {
+      router.announce(name, detail);
+    } catch (error) {
+      if (typeof globalThis.reportError === 'function') globalThis.reportError(error);
+      else console.error(error);
+    }
+    return;
+  }
+  if (typeof document === 'undefined') return;
+  document.dispatchEvent(new CustomEvent(`tinvar:${name}`, { detail }));
+}