@faybl/react-utils 1.2.0 → 2.0.0

package/README.md

@@ -6,10 +6,11 @@ React hooks for Faybl web apps.
 npm install @faybl/react-utils
 ```
 
-Every hook takes the `@faybl/client` client as `client` and does nothing until
-it has one. `useConnection` and `useSession` need client 4.1 or later. A list
-of rids or ids is compared by its content, so a new array with the same ids
-does not resubscribe.
+Every hook but `useSession` takes the `@faybl/client` client as `client` and
+does nothing until it has one; `useSession` reads it from `SessionProvider`.
+`useConnection` and `SessionProvider` need client 4.1 or later. A list of rids
+or ids is compared by its content, so a new array with the same ids does not
+resubscribe.
 
 ```js
 import {
@@ -24,16 +25,16 @@ const presenceById = usePresence({ client, identityIds });
 const latest = useChannelsLatest({ client, rids, commitMs: 1000, onError });
 const series = useChannelsSeries({ client, rids, windowSeconds: 3600 });
 const connected = useConnection({ client });
-const { expired, login } = useSession({ client });
+const { expired, cause, user, signIn, signOut } = useSession();
 ```
 
-| Hook                | Returns                                                                   |
-| ------------------- | ------------------------------------------------------------------------- |
-| `usePresence`       | `{ [identityId]: { ts, connected } }`, live                               |
-| `useChannelsLatest` | `{ [rid]: { ts, pl } }`, the last stored point, then live                 |
-| `useChannelsSeries` | `{ [rid]: points }`, the last `windowSeconds`, oldest first, then live    |
-| `useConnection`     | whether the MQTT connection is up                                         |
-| `useSession`        | `{ expired, login }`: whether the login session is gone, and the way back |
+| Hook                | Returns                                                                |
+| ------------------- | ---------------------------------------------------------------------- |
+| `usePresence`       | `{ [identityId]: { ts, connected } }`, live                            |
+| `useChannelsLatest` | `{ [rid]: { ts, pl } }`, the last stored point, then live              |
+| `useChannelsSeries` | `{ [rid]: points }`, the last `windowSeconds`, oldest first, then live |
+| `useConnection`     | whether the MQTT connection is up                                      |
+| `useSession`        | the session, see [An expired session](#an-expired-session)             |
 
 `connected` and `expired` are `undefined` until the client has reported them.
 
@@ -46,20 +47,57 @@ The two channel hooks take two options:
 
 ## An expired session
 
-`useSession` shows nothing and never navigates on its own; what happens when
-the session expires is the app's choice. `login` navigates the whole page to
-`/oauth2/start` and back to where the user was, which happens at once while the
-identity provider still has a session.
+`SessionProvider` follows the session behind the client and reacts when
+it is gone. Put it around the app once the client exists:
 
-A banner with a button that calls `login` keeps whatever the user was typing. A
-page with nothing to lose can call `login` from an effect once `expired` is
-true instead.
+```jsx
+<SessionProvider client={client}>
+  <App />
+</SessionProvider>
+```
+
+It finds an expiry two ways, and each has its own prop:
+
+| Prop               | When                                                            | Default  |
+| ------------------ | --------------------------------------------------------------- | -------- |
+| `expiredOnReturn`  | the user comes back to the tab; a request is sent then to check | `reload` |
+| `expiredOnRequest` | a request is refused while the user works on the page           | `dialog` |
+
+Each takes `reload`, `dialog` or `none`, also exported as `REACTION`:
+
+- `reload` reloads the page. While the identity provider still has a session
+  the user is back on the same page at once; otherwise the sign-in page shows.
+- `dialog` shows `SessionExpiredDialog`, which keeps the page, and whatever the
+  user was typing, until the user chooses to sign in again.
+- `none` does nothing, for an app that shows the expiry its own way through
+  `useSession`.
+
+An expiry found while the tab is hidden counts as a return and waits until the
+user comes back. After an automatic reload, a tab reloads on its own again only
+once `reloadCooldownMs` (default 30 000) has passed; an expiry before that shows
+the dialog, so a 401 that is not about the session cannot reload in a loop.
+`dialogLabels` sets the dialog's `{ title, action }`, which are English by
+default.
+
+`useSession()` returns:
+
+- `expired`: undefined until the client has reported, then whether the
+  session is gone.
+- `cause`: how the expiry was found, `returned` or `request`, also exported as
+  `CAUSE`.
+- `user`: `{ id, firstName, lastName, email }` from `auth.getUserInfo`, fetched
+  the first time a component asks and kept. Undefined until it arrives.
+- `signIn()`: reloads the page.
+- `signOut()`: goes to the login proxy's `sign_out` on the app's own host, which
+  ends the session there and at the identity provider, and comes back to the
+  page the user left, which asks the user to sign in again. `signOutUrl` on the
+  provider sends it somewhere else instead.
+
+An app that handles the expiry itself can still use the dialog:
 
 ```jsx
-const SessionBanner = ({ client }) => {
-  const { expired, login } = useSession({ client });
-  return expired ? (
-    <Alert action={<Button onClick={login}>Log in</Button>}>Your session has expired.</Alert>
-  ) : undefined;
+const SessionNotice = () => {
+  const { expired, signIn } = useSession();
+  return <SessionExpiredDialog open={expired === true} onSignIn={signIn} />;
 };
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@faybl/react-utils",
-  "version": "1.2.0",
+  "version": "2.0.0",
   "description": "React hooks for Faybl web apps",
   "license": "TBD",
   "author": "Arcturitech",
@@ -30,7 +30,7 @@
     }
   },
   "dependencies": {
-    "@faybl/utils": "^1.2.0"
+    "@faybl/utils": "^2.0.0"
   },
   "engines": {
     "node": ">=22"

package/src/SessionExpiredDialog.js

@@ -0,0 +1,50 @@
+import { createElement, useEffect, useId, useRef } from 'react';
+
+const DEFAULT_LABELS = { title: 'You have been signed out', action: 'Sign in again' };
+
+// Light or dark after the user's system, as apps here are.
+const dialogStyle = {
+  colorScheme: 'light dark',
+  border: 'none',
+  borderRadius: 8,
+  padding: 24,
+  minWidth: 280,
+  font: 'inherit',
+  boxShadow: '0 8px 32px rgba(0, 0, 0, 0.3)',
+};
+const titleStyle = { margin: '0 0 24px', fontSize: '1.25rem', fontWeight: 500 };
+const actionStyle = { font: 'inherit', fontWeight: 500, padding: '6px 16px', cursor: 'pointer' };
+
+// The only way out is to sign in again, so Escape does not close it.
+const keepOpen = (event) => event.preventDefault();
+
+const useModal = (open) => {
+  const ref = useRef(undefined);
+  useEffect(() => {
+    const dialog = ref.current;
+    if (open && !dialog.open) dialog.showModal();
+    if (!open && dialog.open) dialog.close();
+  }, [open]);
+  return ref;
+};
+
+/**
+ * A modal telling the user the session is gone, with one action that signs in
+ * again. The provider shows it for the `dialog` reaction; an app that handles
+ * expiry itself can render it with `open` from useSession.
+ * @param {object} params
+ * @param {boolean} params.open
+ * @param {() => void} params.onSignIn Usually useSession's signIn
+ * @param {{ title?: string, action?: string }} [params.labels] English by default
+ */
+export const SessionExpiredDialog = ({ open, onSignIn, labels }) => {
+  const ref = useModal(open);
+  const titleId = useId();
+  const { title, action } = { ...DEFAULT_LABELS, ...labels };
+  return createElement(
+    'dialog',
+    { ref, 'aria-labelledby': titleId, onCancel: keepOpen, style: dialogStyle },
+    createElement('h2', { id: titleId, style: titleStyle }, title),
+    createElement('button', { type: 'button', onClick: onSignIn, style: actionStyle }, action),
+  );
+};

package/src/SessionProvider.js

@@ -0,0 +1,117 @@
+import { createElement, useCallback, useEffect, useMemo, useReducer } from 'react';
+
+import { navigateTo, reloadPage } from './pageNavigation.js';
+import { readReloadStamp, writeReloadStamp } from './reloadStamp.js';
+import { SessionContext } from './sessionContext.js';
+import { SessionExpiredDialog } from './SessionExpiredDialog.js';
+import { CAUSE, DEFAULT_RELOAD_COOLDOWN_MS, REACTION } from './sessionReaction.js';
+import { INITIAL_SESSION_STATE, SESSION_EVENT, sessionReducer } from './sessionState.js';
+import { defaultSignOutUrl } from './signOutUrl.js';
+import { useReturnCheck } from './useReturnCheck.js';
+import { useUser } from './useUser.js';
+
+const isVisible = () => document.visibilityState === 'visible';
+
+const useSessionState = ({ client, reactions, reloadCooldownMs, probing }) => {
+  const [state, dispatch] = useReducer(sessionReducer, INITIAL_SESSION_STATE);
+  const policy = useCallback(
+    () => ({ reactions, reloadStamp: readReloadStamp(), now: Date.now(), reloadCooldownMs }),
+    [reactions, reloadCooldownMs],
+  );
+
+  useEffect(() => {
+    if (!client) return undefined;
+    return client.session.subscribe(({ expired }) =>
+      dispatch({
+        type: SESSION_EVENT.REPORTED,
+        client,
+        expired,
+        visible: isVisible(),
+        probing: probing(),
+        policy: policy(),
+      }),
+    );
+  }, [client, policy, probing]);
+
+  const returned = useCallback(
+    () => dispatch({ type: SESSION_EVENT.VISIBLE, client, visible: true, policy: policy() }),
+    [client, policy],
+  );
+
+  return { state: state.client === client ? state : INITIAL_SESSION_STATE, returned };
+};
+
+const useAutomaticReload = (reaction) =>
+  useEffect(() => {
+    if (reaction !== REACTION.RELOAD) return;
+    writeReloadStamp(Date.now());
+    reloadPage();
+  }, [reaction]);
+
+/**
+ * Follows the session behind `client` and reacts when it expires:
+ * `expiredOnReturn` when the user comes back to the tab, `expiredOnRequest`
+ * when a request fails while the user works. Each is `reload`, `dialog` or
+ * `none`. After an automatic reload, none runs for `reloadCooldownMs`; an
+ * expiry then shows the dialog. Children read it through useSession.
+ * @param {object} params
+ * @param {object} params.client faybl-client 4.1 or later; nothing happens until it is set
+ * @param {'reload' | 'dialog' | 'none'} [params.expiredOnReturn] Default `reload`
+ * @param {'reload' | 'dialog' | 'none'} [params.expiredOnRequest] Default `dialog`
+ * @param {number} [params.reloadCooldownMs] Default 30 000
+ * @param {string} [params.signOutUrl] Where signOut goes; through the login proxy by default
+ * @param {{ title?: string, action?: string }} [params.dialogLabels]
+ * @param {import('react').ReactNode} params.children
+ */
+export const SessionProvider = ({
+  client,
+  expiredOnReturn = REACTION.RELOAD,
+  expiredOnRequest = REACTION.DIALOG,
+  reloadCooldownMs = DEFAULT_RELOAD_COOLDOWN_MS,
+  signOutUrl,
+  dialogLabels,
+  children,
+}) => {
+  const reactions = useMemo(
+    () => ({ [CAUSE.RETURNED]: expiredOnReturn, [CAUSE.REQUEST]: expiredOnRequest }),
+    [expiredOnReturn, expiredOnRequest],
+  );
+  const { user, loadUser, fetchUser } = useUser(client);
+  const { probing, check } = useReturnCheck(fetchUser);
+  const { state, returned } = useSessionState({ client, reactions, reloadCooldownMs, probing });
+  const { expired, cause, reaction } = state;
+
+  useEffect(() => {
+    if (!client) return undefined;
+    const onVisibilityChange = () => {
+      if (!isVisible()) return;
+      returned();
+      check();
+    };
+    document.addEventListener('visibilitychange', onVisibilityChange);
+    return () => document.removeEventListener('visibilitychange', onVisibilityChange);
+  }, [client, returned, check]);
+
+  useAutomaticReload(reaction);
+
+  const signOut = useCallback(
+    () => navigateTo(signOutUrl ?? defaultSignOutUrl(window.location)),
+    [signOutUrl],
+  );
+  const session = useMemo(
+    () => ({ expired, cause, user, signIn: reloadPage, signOut }),
+    [expired, cause, user, signOut],
+  );
+  const value = useMemo(() => ({ session, loadUser }), [session, loadUser]);
+
+  return createElement(
+    SessionContext,
+    { value },
+    children,
+    createElement(SessionExpiredDialog, {
+      open: reaction === REACTION.DIALOG,
+      onSignIn: reloadPage,
+      labels: dialogLabels,
+    }),
+  );
+};

package/src/index.js

@@ -1,3 +1,6 @@
+export { CAUSE, REACTION } from './sessionReaction.js';
+export { SessionExpiredDialog } from './SessionExpiredDialog.js';
+export { SessionProvider } from './SessionProvider.js';
 export { useChannelsLatest } from './useChannelsLatest.js';
 export { useChannelsSeries } from './useChannelsSeries.js';
 export { useConnection } from './useConnection.js';

package/src/pageNavigation.js

@@ -0,0 +1,5 @@
+// Whole-page navigation, which ends the app's own state.
+
+export const reloadPage = () => window.location.reload();
+
+export const navigateTo = (url) => window.location.assign(url);

package/src/reloadStamp.js

@@ -0,0 +1,26 @@
+const RELOAD_STAMP_KEY = 'faybl.session.reloadedAt';
+
+// sessionStorage is per tab and survives the reload it records. Reaching it
+// throws where the browser blocks storage, so it is reached inside the guard.
+const tabStorage = () => globalThis.sessionStorage;
+
+/**
+ * When this tab last reloaded on its own: `{ ok: true, value }`, with `value`
+ * undefined for never, or `{ ok: false }` when storage cannot be read.
+ */
+export const readReloadStamp = (storage = tabStorage) => {
+  try {
+    const stamp = Number(storage().getItem(RELOAD_STAMP_KEY));
+    return { ok: true, value: Number.isFinite(stamp) && stamp > 0 ? stamp : undefined };
+  } catch {
+    return { ok: false };
+  }
+};
+
+export const writeReloadStamp = (now, storage = tabStorage) => {
+  try {
+    storage().setItem(RELOAD_STAMP_KEY, String(now));
+  } catch {
+    // A failed write leaves the earlier stamp, if any.
+  }
+};

package/src/sessionContext.js

@@ -0,0 +1,3 @@
+import { createContext } from 'react';
+
+export const SessionContext = createContext(undefined);

package/src/sessionReaction.js

@@ -0,0 +1,37 @@
+export const REACTION = { RELOAD: 'reload', DIALOG: 'dialog', NONE: 'none' };
+
+export const CAUSE = { RETURNED: 'returned', REQUEST: 'request' };
+
+export const DEFAULT_RELOAD_COOLDOWN_MS = 30_000;
+
+/**
+ * Whether an automatic reload may run now: none until `reloadCooldownMs` have
+ * passed since the last one, so a 401 that a reload does not cure cannot loop.
+ * Without a readable stamp the last reload is unknown, and none runs.
+ * @param {object} params
+ * @param {{ ok: boolean, value?: number }} params.reloadStamp Epoch ms of the last automatic reload
+ * @param {number} params.now Epoch ms
+ * @param {number} params.reloadCooldownMs
+ * @returns {boolean}
+ */
+export const reloadAllowed = ({ reloadStamp, now, reloadCooldownMs }) =>
+  reloadStamp.ok &&
+  (reloadStamp.value === undefined || now - reloadStamp.value >= reloadCooldownMs);
+
+/**
+ * The reaction to an expired session: the one configured for its cause, with
+ * a reload turned into the dialog during the reload cooldown.
+ * @param {object} params
+ * @param {string} params.cause One of CAUSE
+ * @param {{ returned: string, request: string }} params.reactions One of REACTION per cause
+ * @param {{ ok: boolean, value?: number }} params.reloadStamp
+ * @param {number} params.now
+ * @param {number} params.reloadCooldownMs
+ * @returns {string} One of REACTION
+ */
+export const chooseReaction = ({ cause, reactions, ...guard }) => {
+  const reaction = Object.values(REACTION).includes(reactions[cause])
+    ? reactions[cause]
+    : REACTION.DIALOG;
+  return reaction === REACTION.RELOAD && !reloadAllowed(guard) ? REACTION.DIALOG : reaction;
+};

package/src/sessionState.js

@@ -0,0 +1,42 @@
+import { CAUSE, chooseReaction } from './sessionReaction.js';
+
+export const SESSION_EVENT = { REPORTED: 'reported', VISIBLE: 'visible' };
+
+export const INITIAL_SESSION_STATE = {
+  client: undefined,
+  expired: undefined,
+  cause: undefined,
+  reaction: undefined,
+};
+
+// The reaction is chosen only while the user can see the page; an expiry found
+// in a hidden tab waits for the user to come back.
+const decide = (state, { visible, policy }) =>
+  state.expired && visible && !state.reaction
+    ? { ...state, reaction: chooseReaction({ cause: state.cause, ...policy }) }
+    : state;
+
+const reported = (state, { client, expired, visible, probing }) => {
+  const current = state.client === client ? state : { ...INITIAL_SESSION_STATE, client };
+  if (!expired) return { ...INITIAL_SESSION_STATE, client, expired };
+  if (current.expired) return current;
+  const cause = probing || !visible ? CAUSE.RETURNED : CAUSE.REQUEST;
+  return { client, expired, cause, reaction: undefined };
+};
+
+/**
+ * The provider's session state, for one client at a time. REPORTED is the
+ * client's `{ expired }`; VISIBLE is the tab becoming visible again. Both carry
+ * `client`, `visible` and `policy`, the input to chooseReaction apart from the
+ * cause, and REPORTED whether a check started by the user's return is running.
+ */
+export const sessionReducer = (state, event) => {
+  switch (event.type) {
+    case SESSION_EVENT.REPORTED:
+      return decide(reported(state, event), event);
+    case SESSION_EVENT.VISIBLE:
+      return state.client === event.client ? decide(state, event) : state;
+    default:
+      return state;
+  }
+};

package/src/signOutUrl.js

@@ -0,0 +1,10 @@
+/**
+ * Where sign-out goes by default: the login proxy on the tenant's host, which
+ * clears its cookie, ends the identity provider's session and sends the user
+ * back to the page they left. That page has no session, so it asks the user to
+ * sign in.
+ * @param {{ host: string, origin: string, pathname: string }} location
+ * @returns {string}
+ */
+export const defaultSignOutUrl = ({ host, origin, pathname }) =>
+  `https://oauth2.${host}/oauth2/sign_out?rd=${encodeURIComponent(`${origin}${pathname}`)}`;

package/src/useReturnCheck.js

@@ -0,0 +1,26 @@
+import { useCallback, useRef } from 'react';
+
+/**
+ * The request sent when the user returns to the tab, so a lost session is
+ * found at once. `probing()` is true while one is running, which tells an
+ * expiry found by it from one found while the user works.
+ * @param {() => Promise<void>} request A cheap request through the client that never rejects
+ */
+export const useReturnCheck = (request) => {
+  const running = useRef(0);
+
+  const probing = useCallback(() => running.current > 0, []);
+
+  const check = useCallback(async () => {
+    /* eslint-disable functional/immutable-data -- Counts checks in flight across visibility events; it is read synchronously by the session callback the request triggers, before any render. */
+    running.current += 1;
+    try {
+      await request();
+    } finally {
+      running.current -= 1;
+    }
+    /* eslint-enable functional/immutable-data */
+  }, [request]);
+
+  return { probing, check };
+};

package/src/useSession.js

@@ -1,31 +1,37 @@
-import { useCallback, useEffect, useState } from 'react';
+import { useContext, useEffect } from 'react';
 
-const LOGIN_PATH = '/oauth2/start';
+import { navigateTo, reloadPage } from './pageNavigation.js';
+import { SessionContext } from './sessionContext.js';
+import { defaultSignOutUrl } from './signOutUrl.js';
 
-const navigateTo = (url) => window.location.assign(url);
-
-// The login proxy sends the user back to `rd`; while the identity provider
-// still has a session that happens at once.
-export const loginUrl = (href) => `${LOGIN_PATH}?rd=${encodeURIComponent(href)}`;
+const OUTSIDE_PROVIDER = {
+  expired: undefined,
+  cause: undefined,
+  user: undefined,
+  signIn: reloadPage,
+  signOut: () => navigateTo(defaultSignOutUrl(window.location)),
+};
 
 /**
- * Whether the login session behind the client has expired, and `login`, which
- * sends the user to log in and back to the current page. `expired` is
- * undefined until the client has reported it. Nothing navigates on its own.
- * @param {object} params
- * @param {object} params.client faybl-client
- * @param {(url: string) => void} [params.navigate] Top-level navigation
- * @returns {{ expired: boolean | undefined, login: () => void }}
+ * The session from the nearest SessionProvider. `expired` is undefined
+ * until the client has reported it, and `cause` says how an expiry was found:
+ * `returned` or `request`. `user` is fetched the first time a component asks
+ * and is undefined until it arrives.
+ * @returns {{
+ *   expired: boolean | undefined,
+ *   cause: 'returned' | 'request' | undefined,
+ *   user: { id: string, firstName?: string, lastName?: string, email?: string } | undefined,
+ *   signIn: () => void,
+ *   signOut: () => void,
+ * }}
  */
-export const useSession = ({ client, navigate = navigateTo }) => {
-  const [state, setState] = useState({ client: undefined, expired: undefined });
+export const useSession = () => {
+  const context = useContext(SessionContext);
+  const loadUser = context?.loadUser;
 
   useEffect(() => {
-    if (!client) return undefined;
-    return client.session.subscribe(({ expired }) => setState({ client, expired }));
-  }, [client]);
-
-  const login = useCallback(() => navigate(loginUrl(window.location.href)), [navigate]);
+    loadUser?.();
+  }, [loadUser]);
 
-  return { expired: state.client === client ? state.expired : undefined, login };
+  return context?.session ?? OUTSIDE_PROVIDER;
 };

package/src/useUser.js

@@ -0,0 +1,31 @@
+import { useCallback, useRef, useState } from 'react';
+
+/**
+ * Who is signed in, from the client's `auth.getUserInfo`. `loadUser` fetches
+ * once per client and keeps the answer; `fetchUser` fetches again. A failed
+ * fetch keeps the last answer: a 401 already reaches the session, and the next
+ * return to the tab fetches again.
+ */
+export const useUser = (client) => {
+  const [cache, setCache] = useState({ client: undefined, user: undefined });
+  const loadedFor = useRef(undefined);
+
+  const fetchUser = useCallback(async () => {
+    if (!client) return;
+    try {
+      const user = await client.auth.getUserInfo();
+      setCache({ client, user });
+    } catch {
+      // Reported by the client: a 401 as `session`, anything else to its onError.
+    }
+  }, [client]);
+
+  const loadUser = useCallback(() => {
+    if (!client || loadedFor.current === client) return;
+    // eslint-disable-next-line functional/immutable-data -- Marks the client whose user is fetched, across the renders of every component that asks; state would refetch until the first answer lands.
+    loadedFor.current = client;
+    void fetchUser();
+  }, [client, fetchUser]);
+
+  return { user: cache.client === client ? cache.user : undefined, loadUser, fetchUser };
+};