@visns-studio/visns-components 6.21.0 → 6.23.0

package/src/components/phone/phonePresenceHelpers.js

@@ -0,0 +1,298 @@
+/**
+ * The Zoom Phone roster's logic, with no React and no DOM in it.
+ *
+ * Split out for the same reason smsHelpers.js was: the interesting parts of a
+ * live roster are "what does this state mean" and "how does an event change the
+ * list", and both are much easier to be sure about when `node --test` can call
+ * them directly.
+ *
+ * The number formatting and the avatar initials are imported from the messaging
+ * module rather than written again — a phone number should read identically
+ * whether it is above a text message or beside an extension.
+ */
+
+// The extension is spelled out because this module is imported directly by
+// `node --test`, before tests/jsxHooks.mjs (which is what resolves the
+// library's extensionless imports) has been registered.
+import { initialsFor, normaliseNumberForDisplay } from '../sms/smsHelpers.js';
+
+export { initialsFor, normaliseNumberForDisplay };
+
+/**
+ * The four states a roster row can be in.
+ *
+ * `available` is worth reading carefully: it is an INFERENCE, not something
+ * Zoom said. It means "no live call leg for this extension", which is only as
+ * true as the webhook subscription is healthy — which is why the popover always
+ * shows the age of its snapshot next to the dots rather than letting a row of
+ * green stand on its own.
+ */
+export const STATUS = {
+    ON_CALL: 'on_call',
+    RINGING: 'ringing',
+    AVAILABLE: 'available',
+    INACTIVE: 'inactive',
+};
+
+const STATUS_LABELS = {
+    [STATUS.ON_CALL]: 'On a call',
+    [STATUS.RINGING]: 'Ringing',
+    [STATUS.AVAILABLE]: 'Available',
+    [STATUS.INACTIVE]: 'No handset',
+};
+
+/** Busy first: a roster is read to find out who is unavailable. */
+const STATUS_RANK = {
+    [STATUS.ON_CALL]: 0,
+    [STATUS.RINGING]: 1,
+    [STATUS.AVAILABLE]: 2,
+    [STATUS.INACTIVE]: 3,
+};
+
+export const statusLabel = (status) => STATUS_LABELS[status] ?? 'Unknown';
+
+/**
+ * The dot's tone. Four words rather than colours, so the stylesheet owns the
+ * palette and this module stays testable.
+ */
+export const statusTone = (status) => {
+    if (status === STATUS.ON_CALL) return 'busy';
+    if (status === STATUS.RINGING) return 'ringing';
+    if (status === STATUS.AVAILABLE) return 'free';
+
+    return 'muted';
+};
+
+const parseDate = (value) => {
+    if (!value) return null;
+
+    const date = value instanceof Date ? value : new Date(value);
+
+    return Number.isNaN(date.getTime()) ? null : date;
+};
+
+/**
+ * How long this leg has been going, as `m:ss` (or `h:mm:ss` past an hour).
+ *
+ * Measured from the answer where there is one and from the first ring where
+ * there is not, because those are the two questions being asked: "how long have
+ * they been talking" and "how long has that been ringing".
+ *
+ * Empty string, never "0:00", when there is no usable timestamp — a duration
+ * that is quietly wrong is worse than one that is absent.
+ */
+export const callDuration = (call, now = Date.now()) => {
+    const from = parseDate(call?.answered_at) ?? parseDate(call?.started_at);
+
+    if (!from) return '';
+
+    const seconds = Math.floor((now - from.getTime()) / 1000);
+
+    if (!Number.isFinite(seconds) || seconds < 0) return '';
+
+    const hours = Math.floor(seconds / 3600);
+    const minutes = Math.floor((seconds % 3600) / 60);
+    const rest = seconds % 60;
+    const pad = (value) => String(value).padStart(2, '0');
+
+    return hours > 0
+        ? `${hours}:${pad(minutes)}:${pad(rest)}`
+        : `${minutes}:${pad(rest)}`;
+};
+
+/**
+ * The line under a name while somebody is on a call.
+ *
+ * Direction first, because "called Cleo Client" and "call from Cleo Client" are
+ * different facts and the roster is read at a glance.
+ */
+export const callSummary = (call) => {
+    if (!call) return '';
+
+    const who = call.client?.name || call.peer_name || '';
+    const number = normaliseNumberForDisplay(call.peer_number);
+    const outbound = call.direction === 'outbound';
+
+    const subject = who || number || 'Unknown number';
+
+    if (call.status === 'ringing') {
+        return outbound ? `Calling ${subject}` : `Ringing — ${subject}`;
+    }
+
+    return outbound ? `Calling ${subject}` : `Call from ${subject}`;
+};
+
+/**
+ * The number to show beside the name, when it adds something.
+ *
+ * Suppressed when the summary is already showing the same digits — the row is
+ * one line of a popover, not a record card.
+ */
+export const peerNumberLabel = (call) => {
+    if (!call?.peer_number) return '';
+
+    const number = normaliseNumberForDisplay(call.peer_number);
+    const named = Boolean(call.client?.name || call.peer_name);
+
+    return named ? number : '';
+};
+
+/**
+ * Busy people first, then the server's order (which is by extension).
+ *
+ * Stable: `sort` is stable in every engine this library supports, so two
+ * extensions in the same state keep the order the roster gave them, and a row
+ * does not jump around under the cursor while the list refreshes.
+ */
+export const orderRoster = (users) => {
+    if (!Array.isArray(users)) return [];
+
+    return [...users].sort((a, b) => {
+        const left = STATUS_RANK[a?.status] ?? STATUS_RANK[STATUS.AVAILABLE];
+        const right = STATUS_RANK[b?.status] ?? STATUS_RANK[STATUS.AVAILABLE];
+
+        return left - right;
+    });
+};
+
+/**
+ * How many people are on the phone right now — the number on the header badge.
+ *
+ * Counts ringing legs too: "somebody's phone is ringing" is exactly the thing
+ * the badge exists to catch. `unmatched` are live calls on extensions the
+ * cached directory has not heard of; they are people too.
+ */
+export const onCallCount = (users, unmatched = []) => {
+    const roster = Array.isArray(users) ? users : [];
+    const extra = Array.isArray(unmatched) ? unmatched : [];
+
+    return roster.filter((user) => Boolean(user?.call)).length + extra.length;
+};
+
+/** '' below one, the count up to the ceiling, then '9+'. */
+export const badgeCount = (count, ceiling = 9) => {
+    const value = Number(count) || 0;
+
+    if (value <= 0) return '';
+
+    return value > ceiling ? `${ceiling}+` : String(value);
+};
+
+/**
+ * Does this roster row own the leg an event is about?
+ *
+ * The server publishes the identifier list it matched on — the Zoom user id,
+ * the extension number, the extension id — because `/phone/users` and the
+ * webhook payloads do not name these the same way and neither side should have
+ * to guess which one Zoom actually supplied.
+ */
+export const matchesUser = (user, keys) => {
+    if (!user || !Array.isArray(keys) || keys.length === 0) return false;
+
+    const mine = [user.id, user.extension_number]
+        .map((value) => String(value ?? '').trim())
+        .filter(Boolean);
+
+    return keys.some((key) => mine.includes(String(key ?? '').trim()));
+};
+
+/**
+ * Fold one broadcast into the roster.
+ *
+ * Returns a NEW array when something changed and the SAME array when nothing
+ * did, so React can skip the re-render for an event about somebody who is not
+ * on this list — which, on a broadcast channel shared with the call pop, is a
+ * good proportion of them.
+ *
+ * A cleared leg puts the row back to `available` rather than to whatever it was
+ * before: `inactive` is a property of the extension, not of the call, and the
+ * next poll re-reads it in the unlikely case it changed while a call was open.
+ */
+export const applyPresenceEvent = (users, event) => {
+    const list = Array.isArray(users) ? users : [];
+
+    if (!event || !Array.isArray(event.keys) || event.keys.length === 0) {
+        return list;
+    }
+
+    let changed = false;
+
+    const next = list.map((user) => {
+        if (!matchesUser(user, event.keys)) return user;
+
+        changed = true;
+
+        if (event.cleared || !event.call) {
+            return {
+                ...user,
+                status:
+                    user.active === false ? STATUS.INACTIVE : STATUS.AVAILABLE,
+                call: null,
+            };
+        }
+
+        return {
+            ...user,
+            status:
+                event.call.status === 'ringing'
+                    ? STATUS.RINGING
+                    : STATUS.ON_CALL,
+            call: event.call,
+        };
+    });
+
+    return changed ? next : list;
+};
+
+/**
+ * The one-line note under the list.
+ *
+ * Three different sentences for three different situations, because "no
+ * credentials", "Zoom refused us" and "nobody is on the phone" look identical
+ * from the browser and mean entirely different things. The house style is to
+ * say which one it is on the face of the popover rather than in a console
+ * somewhere.
+ */
+export const presenceNote = (status) => {
+    if (!status) return null;
+
+    if (status.configured === false) {
+        return {
+            tone: 'bad',
+            text: 'Zoom Phone is not connected — no extensions to show yet',
+        };
+    }
+
+    if (status.error) {
+        return { tone: 'bad', text: `Zoom: ${status.error}` };
+    }
+
+    if ((status.users?.length ?? 0) === 0) {
+        return {
+            tone: 'warn',
+            text: 'Zoom returned no phone extensions for this account',
+        };
+    }
+
+    return null;
+};
+
+/**
+ * "Updated just now" / "Updated 2m ago" — the freshness stamp that keeps a row
+ * of green dots honest. Live subscriptions get their own wording, because a
+ * subscribed tab is not relying on the stamp at all.
+ */
+export const freshnessLabel = (fetchedAt, live, now = Date.now()) => {
+    if (live) return 'Live';
+
+    const stamp = parseDate(fetchedAt);
+
+    if (!stamp) return '';
+
+    const seconds = Math.floor((now - stamp.getTime()) / 1000);
+
+    if (seconds < 0 || seconds < 45) return 'Updated just now';
+    if (seconds < 3600) return `Updated ${Math.floor(seconds / 60)}m ago`;
+
+    return `Updated ${Math.floor(seconds / 3600)}h ago`;
+};

package/src/components/phone/useZoomPhoneLive.js

@@ -0,0 +1,165 @@
+import { useEffect, useRef, useState } from 'react';
+
+import {
+    deriveLiveState,
+    isDeadConnectionState,
+    subscriptionMonitor,
+} from '../sms/smsLiveState';
+
+/** The event the backend broadcasts when one extension's state changes. */
+export const EVENT_PRESENCE = '.phone.presence';
+
+/**
+ * Live phone presence: Pusher when it is wired up, polling when it is not.
+ *
+ * A thin sibling of `useSmsLive`, and deliberately not a copy of it — the SMS
+ * inbox listens on one channel per line and has to reconcile a set; this
+ * listens on the ONE channel the call queue pop already uses, so all the set
+ * bookkeeping falls away.
+ *
+ * What is kept is the part that matters: "live" means a channel has actually
+ * reported `pusher:subscription_succeeded`, not merely that `echo.private()`
+ * returned an object. Treating the latter as live is how a roster ends up
+ * subscribed to nothing, polling nothing, and showing a green dot beside
+ * somebody who has been on the phone for half an hour. See smsLiveState.js.
+ *
+ * The `echo` prop is an instance OR a factory, matching CallQueuePop and the
+ * SMS badge: the factory is called inside the effect rather than at mount, so a
+ * user without the permission never opens a Pusher connection at all. The
+ * account has a hard concurrent-connection quota.
+ *
+ * @param {object}   options
+ * @param {object|Function|null} options.echo    Echo instance, or `() => echo`.
+ * @param {string|null} options.channel          Private channel name.
+ * @param {boolean}  [options.enabled]           Off entirely when false.
+ * @param {Function} [options.onPresence]        `({cleared, keys, call}) => void`.
+ *
+ * @returns {{live: boolean}}
+ */
+const useZoomPhoneLive = ({
+    echo = null,
+    channel = null,
+    enabled = true,
+    onPresence,
+} = {}) => {
+    const [live, setLive] = useState(false);
+
+    // Read through refs so a consumer passing an inline arrow — which is the
+    // normal way to write both of these — does not tear the subscription down
+    // and rebuild it on every render. Only the channel name does that.
+    const echoRef = useRef(echo);
+    echoRef.current = echo;
+
+    const presenceRef = useRef(onPresence);
+    presenceRef.current = onPresence;
+
+    useEffect(() => {
+        if (!enabled || !channel || typeof window === 'undefined') {
+            setLive(false);
+
+            return undefined;
+        }
+
+        const source = echoRef.current;
+        const instance = typeof source === 'function' ? source() : source;
+
+        if (!instance) {
+            setLive(false);
+
+            return undefined;
+        }
+
+        let confirmed = false;
+        let connectionState = null;
+
+        const sync = () =>
+            setLive(deriveLiveState(confirmed ? 1 : 0, connectionState));
+
+        let subscription = null;
+        let unmonitor = () => {};
+        let unbindState = () => {};
+
+        try {
+            subscription = instance.private(channel);
+
+            subscription.listen(EVENT_PRESENCE, (event) => {
+                presenceRef.current?.(event || {});
+            });
+
+            unmonitor = subscriptionMonitor(subscription, {
+                onSuccess: () => {
+                    confirmed = true;
+                    sync();
+                },
+                onError: () => {
+                    confirmed = false;
+                    sync();
+                },
+            });
+        } catch (error) {
+            // A channel that will not subscribe leaves the poller in charge,
+            // which is the whole point of the poller.
+            setLive(false);
+
+            return undefined;
+        }
+
+        // The socket underneath. When it goes, the channel goes with it whatever
+        // the confirmation said; pusher-js resubscribes on its own once it is
+        // back, and the subscribed callback re-confirms.
+        try {
+            const connection = instance.connector?.pusher?.connection;
+
+            if (connection && typeof connection.bind === 'function') {
+                const onStateChange = (states) => {
+                    const current = states?.current ?? states;
+
+                    connectionState = current;
+
+                    if (isDeadConnectionState(current)) confirmed = false;
+
+                    sync();
+                };
+
+                connection.bind('state_change', onStateChange);
+                connectionState = connection.state ?? null;
+
+                unbindState = () => {
+                    try {
+                        connection.unbind?.('state_change', onStateChange);
+                    } catch (error) {
+                        // Already gone.
+                    }
+                };
+            }
+        } catch (error) {
+            // No reachable connection object: the channel confirmation alone
+            // decides, which is the same answer we gave before.
+        }
+
+        sync();
+
+        return () => {
+            unbindState();
+
+            try {
+                unmonitor();
+            } catch (error) {
+                // Already gone.
+            }
+
+            try {
+                subscription?.stopListening(EVENT_PRESENCE);
+                instance.leave(channel);
+            } catch (error) {
+                // Nothing to clean up.
+            }
+
+            setLive(false);
+        };
+    }, [enabled, channel]);
+
+    return { live };
+};
+
+export default useZoomPhoneLive;

package/src/components/sms/SmsClientConversations.jsx

@@ -74,6 +74,12 @@ const SmsClientConversations = ({
     templates: templatesProp = null,
     canManage = false,
     clientUrl = (id) => `/clients/${id}`,
+    // Both opt-in and both handed straight to the conversation pane — see
+    // SmsThreadPanel for the shapes. They are here because the client page is
+    // where a host has a reason to file a client's messages against one of its
+    // own records; the card itself has no opinion about what that record is.
+    messageSelection = null,
+    messageAnnotations = null,
     title = 'Messages',
     // The card is a fixed-height box with the conversation scrolling inside
     // it: a timeline that grows the page pushes the composer off the bottom of
@@ -408,6 +414,8 @@ const SmsClientConversations = ({
                         lines={lines}
                         canManage={canManage}
                         clientUrl={clientUrl}
+                        messageSelection={messageSelection}
+                        messageAnnotations={messageAnnotations}
                         onThreadChange={applyThread}
                         onMessage={applyThread}
                         showTransportBanner={false}

package/src/components/sms/SmsInbox.jsx

@@ -104,6 +104,15 @@ const SmsInboxInner = ({
     channelFor = defaultChannelFor,
     settingsUrl = '/settings/sms',
     clientUrl = (id) => `/clients/${id}`,
+    // Both opt-in, both handed straight to the conversation pane — see
+    // SmsThreadPanel for the shapes. Absent, this page is exactly what it was.
+    //
+    // The pane, not the page, is what knows which conversation is open. That is
+    // why `onSelect` is handed the thread and why `messageAnnotations` may be a
+    // function of it: an inbox host cannot know either in advance, and cannot
+    // hold a chip map for every conversation in the practice.
+    messageSelection = null,
+    messageAnnotations = null,
     pageTitle = 'Messages',
     navigate,
     locationSearch,
@@ -523,6 +532,8 @@ const SmsInboxInner = ({
                         lines={lines}
                         canManage={canManage}
                         clientUrl={clientUrl}
+                        messageSelection={messageSelection}
+                        messageAnnotations={messageAnnotations}
                         onThreadChange={onThreadChange}
                         onMessage={onThreadChange}
                         onBack={() => {