@visns-studio/visns-components 6.20.1 → 6.23.0

package/src/components/phone/ZoomPhoneBadge.jsx

@@ -0,0 +1,625 @@
+import React, {
+    useCallback,
+    useEffect,
+    useMemo,
+    useRef,
+    useState,
+} from 'react';
+import {
+    Loader2,
+    PhoneCall,
+    RefreshCw,
+    TriangleAlert,
+    Unplug,
+} from 'lucide-react';
+
+import CustomFetch from '../Fetch';
+import styles from '../styles/ZoomPhone.module.scss';
+// Named for the vault because that is where it was written; nothing in it is
+// vault-specific. It hands a component a `navigate` that works inside a Router
+// and outside one — the same reason SmsInboxBadge imports it.
+import withVaultNavigation from '../vault/vaultNavigation';
+import {
+    matchesShortcut,
+    shortcutLabel,
+    shouldIgnoreShortcut,
+} from '../vault/vaultHelpers';
+import { resolvePhonePresenceEndpoints } from './phonePresenceEndpoints';
+import useZoomPhoneLive from './useZoomPhoneLive';
+import {
+    applyPresenceEvent,
+    badgeCount,
+    callDuration,
+    callSummary,
+    freshnessLabel,
+    initialsFor,
+    onCallCount,
+    orderRoster,
+    peerNumberLabel,
+    presenceNote,
+    statusLabel,
+    statusTone,
+} from './phonePresenceHelpers';
+
+/** Ticks the on-screen call timers without re-fetching anything. */
+const TICK_MS = 1000;
+
+/** The same clock with nothing counting: it only drives the freshness stamp. */
+const IDLE_TICK_MS = 15_000;
+
+/**
+ * Zoom Phone, from the header.
+ *
+ * "Who is on the phone right now" — every extension in the account, who is
+ * free, who is ringing, who is talking, to what number, and which client that
+ * number belongs to. Mounted as an account action through Navigation's
+ * `renderers` slot, so it sits in the chip row beside Messages and the vault
+ * and wears the same trigger.
+ *
+ * The data is a join of two things the server does, not one thing Zoom offers:
+ * the roster comes from `GET /phone/users` (cached), and the live state is
+ * derived from the Zoom Phone webhooks the application already receives. Zoom
+ * has no per-extension "is this handset busy" endpoint — `/users/{id}/
+ * presence_status` is Zoom MEETINGS presence, and reports nothing about calls.
+ *
+ * That has one consequence the UI is honest about: "Available" means "no live
+ * call leg for this extension", which is only as true as the webhook is
+ * healthy. So the footer always says how old the snapshot is, or `Live` when a
+ * subscription has actually been confirmed — never a row of green dots with
+ * nothing to date them.
+ *
+ * The two states this was built around are the ones that do not exist on a
+ * fresh install: Zoom is not connected, and Zoom refused the credentials. Both
+ * say so on the face of the popover, the same way the messaging module does.
+ */
+const ZoomPhoneBadgeInner = ({
+    setting,
+    // Accepted so the component matches the shape Navigation's renderers hand
+    // over, even though the popover does not read them.
+    userProfile: _userProfile,
+    setSystemAuth: _setSystemAuth,
+    endpoints,
+    echo = null,
+    // The private channel to listen on. Null — never a guess — leaves the
+    // popover on its poll, which is a working roster, just a slower one.
+    channel = null,
+    // How a client name becomes a link. A function or a string template, the
+    // same contract CallQueuePop's `clientUrl` uses.
+    clientUrl = null,
+    // The fallback poll. Halved while the popover is open, because a roster
+    // somebody is looking at is worth more than one behind a closed chip.
+    pollInterval = 60_000,
+    openPollInterval = 20_000,
+    // ⌘⇧U / Ctrl+Shift+U. Not ⌘⇧P: browsers open a private window on that.
+    shortcut = 'mod+shift+u',
+    navigate,
+}) => {
+    const routes = useMemo(
+        () => resolvePhonePresenceEndpoints(endpoints),
+        [endpoints]
+    );
+
+    const [open, setOpen] = useState(false);
+    const [roster, setRoster] = useState(null);
+    const [loading, setLoading] = useState(false);
+    const [loaded, setLoaded] = useState(false);
+    // Drives the call timers. Cheap: one state write a second, and only while
+    // there is actually a call on screen.
+    const [tick, setTick] = useState(() => Date.now());
+
+    const wrapperRef = useRef(null);
+    const triggerRef = useRef(null);
+    const listRef = useRef(null);
+    const mountedRef = useRef(true);
+    // Guards against an early response overwriting a later one.
+    const requestRef = useRef(0);
+
+    useEffect(
+        () => () => {
+            mountedRef.current = false;
+        },
+        []
+    );
+
+    /* -------------------------------------------------------------- loading */
+
+    const load = useCallback(
+        (refresh = false) => {
+            const ticket = requestRef.current + 1;
+
+            requestRef.current = ticket;
+            setLoading(true);
+
+            CustomFetch(
+                routes.presence,
+                'GET',
+                refresh ? { refresh: 1 } : null,
+                (result) => {
+                    if (!mountedRef.current || requestRef.current !== ticket)
+                        return;
+
+                    setRoster(
+                        result && typeof result === 'object' ? result : null
+                    );
+                    setLoading(false);
+                    setLoaded(true);
+                },
+                // Silent: a header chip must not toast at someone because a
+                // background poll failed. The popover shows the last good
+                // snapshot and its age, which says the same thing usefully.
+                () => {
+                    if (!mountedRef.current || requestRef.current !== ticket)
+                        return;
+
+                    setLoading(false);
+                    setLoaded(true);
+                }
+            ).catch(() => {
+                if (!mountedRef.current || requestRef.current !== ticket)
+                    return;
+
+                setLoading(false);
+                setLoaded(true);
+            });
+        },
+        [routes]
+    );
+
+    /* ----------------------------------------------------------------- live */
+
+    const handlePresence = useCallback((event) => {
+        if (!mountedRef.current) return;
+
+        setRoster((prev) => {
+            if (!prev) return prev;
+
+            const users = applyPresenceEvent(prev.users, event);
+
+            // Nobody on this roster owns that leg. It is either an extension the
+            // cached directory has not heard of or — much more likely, since
+            // this channel is shared with the call pop — simply not our event.
+            // Re-fetch rather than guess: `unmatched_calls` is the server's
+            // answer to give, not ours to invent.
+            if (users === prev.users) return prev;
+
+            return {
+                ...prev,
+                users,
+                on_call_count: onCallCount(users, prev.unmatched_calls),
+            };
+        });
+    }, []);
+
+    const { live } = useZoomPhoneLive({
+        echo,
+        channel,
+        onPresence: handlePresence,
+    });
+
+    /*
+     * The poll. It is the only source when there is no confirmed subscription,
+     * and the safety net when there is one — a dropped frame then costs a
+     * minute of staleness rather than the rest of the session.
+     *
+     * It also covers the case `handlePresence` deliberately does not: a call
+     * arriving on an extension the roster does not list. Only the server can
+     * say who that is.
+     */
+    useEffect(() => {
+        const interval = open ? openPollInterval : pollInterval;
+
+        load();
+
+        if (!(interval > 0)) return undefined;
+
+        const timer = setInterval(() => load(), interval);
+
+        return () => clearInterval(timer);
+    }, [open, load, pollInterval, openPollInterval]);
+
+    /* --------------------------------------------------------------- timers */
+
+    const users = useMemo(() => orderRoster(roster?.users), [roster]);
+    const unmatched = useMemo(
+        () =>
+            Array.isArray(roster?.unmatched_calls)
+                ? roster.unmatched_calls
+                : [],
+        [roster]
+    );
+
+    const busy = onCallCount(roster?.users, unmatched);
+
+    /*
+     * The clock behind the call timers and the "updated 2m ago" stamp.
+     *
+     * Only while the popover is open, and only at one-second resolution while
+     * there is actually a duration ticking on screen — a closed chip has no
+     * reason to re-render once a second all day.
+     */
+    useEffect(() => {
+        if (!open) return undefined;
+
+        setTick(Date.now());
+
+        const timer = setInterval(
+            () => setTick(Date.now()),
+            busy > 0 ? TICK_MS : IDLE_TICK_MS
+        );
+
+        return () => clearInterval(timer);
+    }, [open, busy]);
+
+    /* -------------------------------------------------------------- opening */
+
+    const close = useCallback(() => setOpen(false), []);
+
+    // Global, captured: same reasoning as the vault and the SMS badge — the
+    // point of a chord is not reaching for the mouse, and a data grid or rich
+    // editor that stops keydown propagation must not swallow it.
+    const shortcutRef = useRef(shortcut);
+    shortcutRef.current = shortcut;
+
+    useEffect(() => {
+        const onKeyDown = (event) => {
+            if (!matchesShortcut(event, shortcutRef.current)) return;
+            if (shouldIgnoreShortcut(event)) return;
+
+            event.preventDefault();
+            event.stopPropagation();
+            setOpen((prev) => !prev);
+        };
+
+        window.addEventListener('keydown', onKeyDown, true);
+
+        return () => window.removeEventListener('keydown', onKeyDown, true);
+    }, []);
+
+    useEffect(() => {
+        if (!open) return undefined;
+
+        const onMouseDown = (event) => {
+            if (wrapperRef.current?.contains(event.target)) return;
+            if (triggerRef.current?.contains(event.target)) return;
+
+            close();
+        };
+
+        document.addEventListener('mousedown', onMouseDown);
+
+        return () => document.removeEventListener('mousedown', onMouseDown);
+    }, [open, close]);
+
+    useEffect(() => {
+        if (!open) return undefined;
+
+        // After paint, or the list is not in the document yet.
+        const handle = setTimeout(() => listRef.current?.focus(), 0);
+
+        return () => clearTimeout(handle);
+    }, [open]);
+
+    const onKeyDown = useCallback(
+        (event) => {
+            if (event.key !== 'Escape') return;
+
+            event.preventDefault();
+            close();
+            triggerRef.current?.focus();
+        },
+        [close]
+    );
+
+    /* --------------------------------------------------------------- render */
+
+    const label = setting?.label || 'Zoom Phone';
+    const hint = shortcutLabel(shortcut);
+    const count = badgeCount(busy);
+    const note = presenceNote(roster);
+
+    const linkFor = useCallback(
+        (client) => {
+            if (!client || !clientUrl) return null;
+
+            return typeof clientUrl === 'function'
+                ? clientUrl(client)
+                : clientUrl;
+        },
+        [clientUrl]
+    );
+
+    const openClient = useCallback(
+        (client) => {
+            const url = linkFor(client);
+
+            if (!url) return;
+
+            close();
+            navigate(url);
+        },
+        [linkFor, close, navigate]
+    );
+
+    /** The client chip on a busy row: a link when we know where to send it. */
+    const renderClient = (call) => {
+        const client = call?.client;
+
+        if (!client?.name) return null;
+
+        const url = linkFor(client);
+
+        if (!url) {
+            return <span className={styles.clientFlat}>{client.name}</span>;
+        }
+
+        return (
+            <button
+                type="button"
+                className={styles.clientLink}
+                onClick={(event) => {
+                    event.stopPropagation();
+                    openClient(client);
+                }}
+                title={`Open ${client.name}`}
+            >
+                {client.name}
+            </button>
+        );
+    };
+
+    const renderCall = (call) => {
+        if (!call) return null;
+
+        const duration = callDuration(call, tick);
+        const number = peerNumberLabel(call);
+
+        return (
+            <span className={styles.callLine}>
+                <span className={styles.callSummary}>{callSummary(call)}</span>
+                {number !== '' && (
+                    <span className={styles.callNumber}>{number}</span>
+                )}
+                {call.queue_name && (
+                    <span className={styles.queueTag}>{call.queue_name}</span>
+                )}
+                {duration !== '' && (
+                    <span className={styles.duration}>{duration}</span>
+                )}
+            </span>
+        );
+    };
+
+    const renderRow = (user) => {
+        const tone = statusTone(user.status);
+        const client = user.call?.client;
+
+        return (
+            <li key={user.id || user.extension_number} className={styles.row}>
+                <span className={styles.avatar} aria-hidden="true">
+                    {initialsFor(user.name)}
+                </span>
+
+                <span className={styles.rowMain}>
+                    <span className={styles.rowTop}>
+                        <strong className={styles.rowName}>{user.name}</strong>
+                        {user.extension_number && (
+                            <span className={styles.extension}>
+                                ext {user.extension_number}
+                            </span>
+                        )}
+                    </span>
+
+                    {user.call ? (
+                        <>
+                            {renderCall(user.call)}
+                            {client?.name && (
+                                <span className={styles.clientLine}>
+                                    {renderClient(user.call)}
+                                    {client.adviser && (
+                                        <span className={styles.clientMeta}>
+                                            {client.adviser}
+                                        </span>
+                                    )}
+                                </span>
+                            )}
+                        </>
+                    ) : (
+                        <span className={styles.idleLine}>
+                            {statusLabel(user.status)}
+                        </span>
+                    )}
+                </span>
+
+                <span
+                    className={[styles.status, styles[`status_${tone}`]]
+                        .filter(Boolean)
+                        .join(' ')}
+                >
+                    <span className={styles.dot} aria-hidden="true" />
+                    {statusLabel(user.status)}
+                </span>
+            </li>
+        );
+    };
+
+    /**
+     * A live call on an extension the cached directory does not list — a
+     * common-area handset, a meeting room, or somebody hired since the roster
+     * was last fetched. Shown rather than dropped: swallowing it would make the
+     * popover say the office is quiet during a call.
+     */
+    const renderUnmatched = (entry, index) => (
+        <li key={`unmatched-${index}`} className={styles.row}>
+            <span className={styles.avatar} aria-hidden="true">
+                {initialsFor(entry.name)}
+            </span>
+
+            <span className={styles.rowMain}>
+                <span className={styles.rowTop}>
+                    <strong className={styles.rowName}>
+                        {entry.name || 'Unknown extension'}
+                    </strong>
+                    {entry.extension_number && (
+                        <span className={styles.extension}>
+                            ext {entry.extension_number}
+                        </span>
+                    )}
+                </span>
+                {renderCall(entry.call)}
+            </span>
+
+            <span
+                className={[styles.status, styles.status_busy]
+                    .filter(Boolean)
+                    .join(' ')}
+            >
+                <span className={styles.dot} aria-hidden="true" />
+                {statusLabel(
+                    entry.call?.status === 'ringing' ? 'ringing' : 'on_call'
+                )}
+            </span>
+        </li>
+    );
+
+    const empty = users.length === 0 && unmatched.length === 0;
+
+    return (
+        <div className={styles.zoomPhone}>
+            <button
+                ref={triggerRef}
+                type="button"
+                className={styles.trigger}
+                onClick={() => (open ? close() : setOpen(true))}
+                data-tooltip-id="system-tooltip"
+                data-tooltip-place="bottom"
+                data-tooltip-content={hint ? `${label} · ${hint}` : label}
+                aria-label={busy > 0 ? `${label} (${busy} on a call)` : label}
+                aria-keyshortcuts="Meta+Shift+U Control+Shift+U"
+                aria-expanded={open}
+                aria-haspopup="dialog"
+            >
+                <PhoneCall size={20} strokeWidth={2} />
+                {count !== '' && (
+                    <span className={styles.badge} aria-hidden="true">
+                        {count}
+                    </span>
+                )}
+            </button>
+
+            {open && (
+                <div
+                    className={styles.popoverWrapper}
+                    ref={wrapperRef}
+                    /* Tells the navigation's action pill to stop clipping while
+                       this is open. See Navigation.module.scss `.hactions > ul`,
+                       and the vault and messages popovers, which do the same. */
+                    data-nav-overlay="open"
+                    role="dialog"
+                    aria-label={label}
+                >
+                    <div className={styles.popover}>
+                        <div className={styles.popoverHead}>
+                            <span className={styles.popoverTitle}>
+                                <PhoneCall
+                                    size={15}
+                                    strokeWidth={2.2}
+                                    aria-hidden="true"
+                                />
+                                {label}
+                            </span>
+
+                            <button
+                                type="button"
+                                className={styles.iconButton}
+                                onClick={() => load(true)}
+                                title="Refresh the extension list from Zoom"
+                                aria-label="Refresh"
+                            >
+                                {loading ? (
+                                    <Loader2
+                                        size={15}
+                                        className={styles.spin}
+                                    />
+                                ) : (
+                                    <RefreshCw size={15} strokeWidth={2} />
+                                )}
+                            </button>
+                        </div>
+
+                        {!empty && (
+                            <ul
+                                className={styles.rows}
+                                ref={listRef}
+                                tabIndex={-1}
+                                onKeyDown={onKeyDown}
+                                aria-label="Zoom Phone extensions"
+                            >
+                                {unmatched.map(renderUnmatched)}
+                                {users.map(renderRow)}
+                            </ul>
+                        )}
+
+                        {empty && (
+                            <div className={styles.empty}>
+                                {loading || !loaded ? (
+                                    <p>
+                                        <Loader2
+                                            size={16}
+                                            className={styles.spin}
+                                            aria-label="Loading extensions"
+                                        />
+                                    </p>
+                                ) : (
+                                    <p>No Zoom Phone extensions to show.</p>
+                                )}
+                            </div>
+                        )}
+
+                        {note && (
+                            <p
+                                className={[
+                                    styles.statusNote,
+                                    note.tone === 'bad'
+                                        ? styles.statusNoteBad
+                                        : '',
+                                ]
+                                    .filter(Boolean)
+                                    .join(' ')}
+                            >
+                                {note.tone === 'bad' ? (
+                                    <Unplug
+                                        size={14}
+                                        strokeWidth={2}
+                                        aria-hidden="true"
+                                    />
+                                ) : (
+                                    <TriangleAlert
+                                        size={14}
+                                        strokeWidth={2}
+                                        aria-hidden="true"
+                                    />
+                                )}
+                                {note.text}
+                            </p>
+                        )}
+
+                        <div className={styles.footer}>
+                            <span className={styles.footerHint}>
+                                {busy === 0
+                                    ? 'Nobody is on a call'
+                                    : `${busy} on a call`}
+                            </span>
+                            <span className={styles.footerStamp}>
+                                {freshnessLabel(roster?.fetched_at, live, tick)}
+                            </span>
+                        </div>
+                    </div>
+                </div>
+            )}
+        </div>
+    );
+};
+
+const ZoomPhoneBadge = withVaultNavigation(ZoomPhoneBadgeInner);
+
+export default ZoomPhoneBadge;

package/src/components/phone/phonePresenceEndpoints.js

@@ -0,0 +1,34 @@
+/**
+ * The URL the Zoom Phone roster talks to.
+ *
+ * One route today, and an object rather than a string anyway — for the same
+ * reason smsEndpoints.js and vaultEndpoints.js are objects: a consumer that
+ * moves the route must not have to re-derive anything, and a second route added
+ * later must not change this module's shape.
+ *
+ * Pure and React-free so `node --test` can import it. This default is the URL a
+ * consumer that passes no `endpoints` prop will hit, so a change here is a
+ * change to every deployment.
+ */
+
+export const makePhonePresenceEndpoints = (base = '/ajax/call-queue') => ({
+    base,
+
+    // The roster: every Zoom Phone extension, each with its live call if it has
+    // one. Served by the call queue module, because it is the same webhook, the
+    // same Zoom credentials and the same number -> client hook.
+    presence: `${base}/presence`,
+});
+
+export const DEFAULT_ENDPOINTS = makePhonePresenceEndpoints();
+
+/**
+ * Merge a partial `endpoints` prop over the defaults, so a consumer overriding
+ * one route does not lose the others.
+ */
+export const resolvePhonePresenceEndpoints = (endpoints) => ({
+    ...DEFAULT_ENDPOINTS,
+    ...(endpoints || {}),
+});
+
+export default DEFAULT_ENDPOINTS;