@faybl/react-utils 1.1.0 → 1.2.0

package/README.md

@@ -6,23 +6,36 @@ 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 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.
 
 ```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, login } = useSession({ client });
 ```
 
-| 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 |
+| 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 |
+
+`connected` and `expired` are `undefined` until the client has reported them.
 
 The two channel hooks take two options:
 
@@ -30,3 +43,23 @@ 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
+
+`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.
+
+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
+const SessionBanner = ({ client }) => {
+  const { expired, login } = useSession({ client });
+  return expired ? (
+    <Alert action={<Button onClick={login}>Log in</Button>}>Your session has expired.</Alert>
+  ) : undefined;
+};
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@faybl/react-utils",
-  "version": "1.1.0",
+  "version": "1.2.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.0"
+    "@faybl/utils": "^1.2.0"
   },
   "engines": {
     "node": ">=22"

package/src/index.js

@@ -1,3 +1,5 @@
 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/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/useSession.js

@@ -0,0 +1,31 @@
+import { useCallback, useEffect, useState } from 'react';
+
+const LOGIN_PATH = '/oauth2/start';
+
+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)}`;
+
+/**
+ * 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 }}
+ */
+export const useSession = ({ client, navigate = navigateTo }) => {
+  const [state, setState] = useState({ client: undefined, expired: undefined });
+
+  useEffect(() => {
+    if (!client) return undefined;
+    return client.session.subscribe(({ expired }) => setState({ client, expired }));
+  }, [client]);
+
+  const login = useCallback(() => navigate(loginUrl(window.location.href)), [navigate]);
+
+  return { expired: state.client === client ? state.expired : undefined, login };
+};