@faybl/react-utils 1.1.1 → 2.0.0

package/README.md

@@ -6,16 +6,26 @@ React hooks for Faybl web apps.
 npm install @faybl/react-utils
 ```
 
-Every hook takes the faybl-client as `client` and does nothing until it has
-one. 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 { useChannelsLatest, useChannelsSeries, usePresence } from '@faybl/react-utils';
+import {
+  useChannelsLatest,
+  useChannelsSeries,
+  useConnection,
+  usePresence,
+  useSession,
+} from '@faybl/react-utils';
 
 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, cause, user, signIn, signOut } = useSession();
 ```
 
 | Hook                | Returns                                                                |
@@ -23,6 +33,10 @@ const series = useChannelsSeries({ client, rids, windowSeconds: 3600 });
 | `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.
 
 The two channel hooks take two options:
 
@@ -30,3 +44,60 @@ The two channel hooks take two options:
   Without it, every point renders as it arrives.
 - `onError(error, rid)` is called when a history read fails. The hooks report
   nothing on their own.
+
+## An expired session
+
+`SessionProvider` follows the session behind the client and reacts when
+it is gone. Put it around the app once the client exists:
+
+```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 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.1.1",
+  "version": "2.0.0",
   "description": "React hooks for Faybl web apps",
   "license": "TBD",
   "author": "Arcturitech",
@@ -21,10 +21,16 @@
     "directory": "packages/react-utils"
   },
   "peerDependencies": {
+    "@faybl/client": "^4.1.0",
     "react": "^19.2.0"
   },
+  "peerDependenciesMeta": {
+    "@faybl/client": {
+      "optional": true
+    }
+  },
   "dependencies": {
-    "@faybl/utils": "^1.1.1"
+    "@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,8 @@
+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';
 export { usePresence } from './usePresence.js';
+export { useSession } from './useSession.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/useConnection.js

@@ -0,0 +1,19 @@
+import { useEffect, useState } from 'react';
+
+/**
+ * Whether the client's MQTT connection is up: true or false once the client
+ * has reported it, undefined before that and without a client.
+ * @param {object} params
+ * @param {object} params.client faybl-client with MQTT
+ * @returns {boolean | undefined}
+ */
+export const useConnection = ({ client }) => {
+  const [state, setState] = useState({ client: undefined, connected: undefined });
+
+  useEffect(() => {
+    if (!client) return undefined;
+    return client.connection.subscribe(({ connected }) => setState({ client, connected }));
+  }, [client]);
+
+  return state.client === client ? state.connected : undefined;
+};

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

@@ -0,0 +1,37 @@
+import { useContext, useEffect } from 'react';
+
+import { navigateTo, reloadPage } from './pageNavigation.js';
+import { SessionContext } from './sessionContext.js';
+import { defaultSignOutUrl } from './signOutUrl.js';
+
+const OUTSIDE_PROVIDER = {
+  expired: undefined,
+  cause: undefined,
+  user: undefined,
+  signIn: reloadPage,
+  signOut: () => navigateTo(defaultSignOutUrl(window.location)),
+};
+
+/**
+ * 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 = () => {
+  const context = useContext(SessionContext);
+  const loadUser = context?.loadUser;
+
+  useEffect(() => {
+    loadUser?.();
+  }, [loadUser]);
+
+  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 };
+};