@visns-studio/visns-components 6.6.4 → 6.15.0

package/src/components/callQueue/CallQueuePop.jsx

@@ -0,0 +1,1502 @@
+import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { Link } from 'react-router-dom';
+import {
+    ChevronDown,
+    ExternalLink,
+    FlaskConical,
+    Phone,
+    PhoneIncoming,
+    X,
+} from 'lucide-react';
+import { toast } from 'react-toastify';
+
+import CustomFetch from '../Fetch';
+import styles from '../styles/CallQueuePop.module.scss';
+
+// Pure helpers live in a plain .js sibling so `node --test` can import them;
+// re-exported below so this file's public surface is unchanged.
+import {
+    CLIENT_DETAIL_FIELDS,
+    FALLBACK_QUEUE_NAME,
+    MONITOR_PERMISSION,
+    clientDetails,
+    defaultClientTasksUrl,
+    defaultClientUrl,
+    defaultTaskUrl,
+    formatAuPhone,
+    formatDueDate,
+    formatElapsed,
+    formatEventDate,
+    hasMonitorPermission,
+    normaliseCall,
+    normalisePickupCodes,
+    toCallWorkspaceId,
+    toLocalDigits,
+} from './callQueueHelpers';
+
+export {
+    CLIENT_DETAIL_FIELDS,
+    clientDetails,
+    formatAuPhone,
+    formatDueDate,
+    formatElapsed,
+    formatEventDate,
+    hasMonitorPermission,
+    normaliseCall,
+    normalisePickupCodes,
+    toCallWorkspaceId,
+    toLocalDigits,
+};
+
+/**
+ * Call Queue Pop
+ * -----------------------------------------------------------------------
+ * A permission-gated, root-level stack of "call is ringing" cards for every
+ * Zoom Phone call queue in the account, so monitoring staff can see an incoming
+ * call and pick it up without watching the Zoom client. Each card's badge is
+ * simply the queue's own name, as Zoom named it in the webhook payload.
+ *
+ * Everything that talks to the server is optional and fails silently, so the
+ * component is safe to ship ahead of (or alongside) its backend:
+ *   - GET  `endpoints.live`        -> `{ calls: [...], pickup_codes: {...} }`
+ *   - GET  `endpoints.clientTasks` -> `{ tasks: [...] }`, fetched lazily (once
+ *     per call) when the open-task badge is expanded
+ *   - Echo private channel (only when the `echo` prop yields an instance, i.e.
+ *     the host app has a broadcaster configured)
+ * With neither present the component renders nothing and logs nothing.
+ *
+ * Pickup codes arrive as the snapshot's `pickup_codes` map, keyed by Zoom call
+ * queue id. A queue with no code still pops — its card just has no Pick up
+ * button, because there is no dial string to offer.
+ *
+ * The caller -> client match arrives already resolved, as each call's `client`
+ * block (computed once by the Zoom webhook, server-side). This component never
+ * looks a caller up itself — every watching member of staff sees every pop, and
+ * that was one duplicate lookup per watcher per ringing phone.
+ *
+ * Cross-tab sync: every open tab shares a BroadcastChannel, so dismissing or
+ * picking up a call in one tab clears that card everywhere immediately rather
+ * than waiting on the server's `queue.answered` event.
+ *
+ * Background awareness: when the tab is hidden/unfocused a new ringing call
+ * raises a system notification (deduped across tabs by `tag`) and the document
+ * title flashes until the user comes back.
+ *
+ * Demo mode lets the UI be reviewed today. From the browser console:
+ *   window.callPopDemo()   -> inject two sample calls (broadcast to all tabs)
+ *   window.callPopClear()  -> clear the stack (in all tabs)
+ * Demo calls bypass the permission gate and never hit a real endpoint.
+ *
+ * Library note: this is the portable version of the CRM's original component.
+ * Every host-specific decision it hard-coded — the Echo instance, the channel
+ * name, the endpoints, the routes it links to, whether Pick up is live — is now
+ * a prop whose default reproduces the CRM's behaviour exactly.
+ */
+
+/**
+ * Events the backend broadcasts. The channel NAME is not a constant: it is
+ * environment-scoped ('call-queue-monitor.{env}') because dev and prod may
+ * share one Pusher app, and it arrives in the live snapshot — the `channel`
+ * prop is only the fallback for a server that does not name one.
+ */
+const EVENT_RINGING = '.queue.ringing';
+const EVENT_ANSWERED = '.queue.answered';
+const EVENT_ENDED = '.queue.ended';
+
+/** Default BroadcastChannel used to keep every open tab's stack in step. */
+const SYNC_CHANNEL = 'throughlife-call-queue-pop';
+
+/** Default Echo channel, used when the snapshot does not name its own. */
+const DEFAULT_CHANNEL = 'call-queue-monitor';
+
+/** How long the exit animation runs before the card is dropped from state. */
+const EXIT_MS = 220;
+
+/** Title shown on alternate ticks while a call rings in a hidden tab. */
+const FLASH_TITLE = '📞 Incoming call…';
+
+/** How often the hidden-tab title alternates. */
+const FLASH_MS = 1000;
+
+/** The trial-run banner's copy, when `trialBadge` is left at its default. */
+const TRIAL_BADGE_TEXT = 'Trial run — the call pop is being tested';
+
+/**
+ * The demo queue id + code injected by `window.callPopDemo()`, so the demo can
+ * show a card WITH a Pick up button next to one without.
+ */
+const DEMO_QUEUE_ID = 'demo-test-queue';
+const DEMO_PICKUP_CODE = '*996439';
+
+/** Endpoints the component talks to; `endpoints` is merged over these. */
+const DEFAULT_ENDPOINTS = {
+    live: '/ajax/call-queue/live',
+    clientTasks: (clientId) => `/ajax/call-queue/client/${clientId}/tasks`,
+};
+
+/**
+ * Substitute a `{token}` placeholder in a string template. Used so every
+ * URL prop accepts a plain string as well as a builder function.
+ */
+const applyTemplate = (template, token, value) =>
+    String(template).split(token).join(value === null || value === undefined ? '' : String(value));
+
+/**
+ * Resolve a URL prop that may be a builder function, a `{token}` template, or
+ * absent — in which case the caller's own fallback builder is used.
+ */
+const resolveUrl = (option, token, value, fallback) => {
+    if (typeof option === 'function') {
+        return option(value);
+    }
+
+    if (typeof option === 'string' && option !== '') {
+        return applyTemplate(option, token, value);
+    }
+
+    return fallback(value);
+};
+
+
+/**
+ * Is the user actually looking at this tab? Both checks matter: a focused but
+ * backgrounded window reports `visible`, and a foreground window whose focus
+ * sits in another application reports `hasFocus() === false`.
+ */
+const isPageVisible = () => {
+    if (typeof document === 'undefined') {
+        return true;
+    }
+
+    if (document.visibilityState !== 'visible') {
+        return false;
+    }
+
+    return typeof document.hasFocus === 'function' ? document.hasFocus() : true;
+};
+
+const CallQueuePop = ({
+    userProfile,
+    echo = null,
+    channel = DEFAULT_CHANNEL,
+    pickupEnabled = false,
+    trialBadge = true,
+    monitorPermission = MONITOR_PERMISSION,
+    endpoints,
+    onOpenTask = null,
+    taskUrl = defaultTaskUrl,
+    clientUrl = defaultClientUrl,
+    clientTasksUrl = defaultClientTasksUrl,
+    onOpenCalendar = null,
+    calendarPath = '/calendar',
+    callWorkspacePath = '/call/{number}',
+    syncChannelName = SYNC_CHANNEL,
+    demoEnabled = true,
+}) => {
+    const [calls, setCalls] = useState([]);
+    const [now, setNow] = useState(() => Date.now());
+
+    // Pickup codes keyed by Zoom call queue id. Empty until the snapshot fills
+    // it in — there is no sensible client-side default for a dial string.
+    const [pickupCodes, setPickupCodes] = useState({});
+    // Environment-scoped Echo channel name, delivered by the snapshot.
+    const [echoChannel, setEchoChannel] = useState(null);
+
+    // Open-task drill-down, keyed by callId: which cards are expanded, and the
+    // tasks fetched for each as `{ status: idle|loading|ready|error, tasks }`.
+    const [expandedTasks, setExpandedTasks] = useState({});
+    const [taskLists, setTaskLists] = useState({});
+
+    // Timeouts for exit animations, cleared on unmount so no setState fires
+    // against an unmounted tree.
+    const exitTimers = useRef([]);
+
+    // callIds whose drill-down request has already gone out — the endpoint is
+    // hit once per call however often the chip is toggled.
+    const taskFetched = useRef(new Set());
+
+    // The cross-tab channel, and the live system notifications keyed by callId
+    // so each can be closed the moment its call goes away.
+    const syncChannel = useRef(null);
+    const notifications = useRef(new Map());
+    const notified = useRef(new Set());
+
+    // The Echo instance is read through a ref so a consumer passing an inline
+    // factory (`echo={() => getEcho()}`) does not tear the subscription down
+    // and rebuild it on every render. Changing the channel name is what forces
+    // a resubscribe, exactly as it did in the CRM.
+    const echoRef = useRef(echo);
+    echoRef.current = echo;
+
+    // The snapshot's own channel wins; the prop is the fallback for a server
+    // that does not name one. Pass `channel={null}` to restore the original
+    // "subscribe to nothing until the snapshot says so" behaviour.
+    const activeChannel = echoChannel || channel || null;
+
+    // Snapshot URL as a plain string, so it can sit in an effect's dep list
+    // without an object identity re-running the fetch on every render.
+    const liveUrl = endpoints?.live ?? DEFAULT_ENDPOINTS.live;
+
+    /** The drill-down endpoint for a client, from a builder or `{id}` template. */
+    const clientTasksEndpoint = useCallback(
+        (clientId) =>
+            resolveUrl(
+                endpoints?.clientTasks,
+                '{id}',
+                clientId,
+                DEFAULT_ENDPOINTS.clientTasks
+            ),
+        [endpoints]
+    );
+
+    const canMonitor = hasMonitorPermission(userProfile, monitorPermission);
+    const hasDemoCalls = calls.some((call) => call.isDemo);
+    const hasRinging = calls.some((call) => !call.leaving);
+    const isVisible = canMonitor || hasDemoCalls;
+
+    /** The trial banner's copy, or '' when the banner is switched off. */
+    const trialText = useMemo(() => {
+        if (typeof trialBadge === 'string') {
+            return trialBadge;
+        }
+
+        return trialBadge ? TRIAL_BADGE_TEXT : '';
+    }, [trialBadge]);
+
+    /** Add a call, ignoring duplicates of a callId already on screen. */
+    const addCall = useCallback((call) => {
+        if (!call) {
+            return;
+        }
+
+        setCalls((previous) => {
+            if (previous.some((item) => item.callId === call.callId)) {
+                return previous;
+            }
+
+            return [...previous, call];
+        });
+    }, []);
+
+    /** Animate a card out, then drop it from state. */
+    const removeCall = useCallback((callId) => {
+        setCalls((previous) =>
+            previous.map((call) =>
+                call.callId === String(callId)
+                    ? { ...call, leaving: true }
+                    : call
+            )
+        );
+
+        const timer = setTimeout(() => {
+            setCalls((previous) =>
+                previous.filter((call) => call.callId !== String(callId))
+            );
+        }, EXIT_MS);
+
+        exitTimers.current.push(timer);
+    }, []);
+
+    /** Drop the whole stack (no exit animation — used by clear). */
+    const clearCalls = useCallback(() => {
+        setCalls([]);
+    }, []);
+
+    /**
+     * The demo's "queue with a pickup code" case has no server behind it, so
+     * its code is injected locally whenever a demo call for that queue lands —
+     * in the tab that ran callPopDemo() and in every tab it was mirrored to, so
+     * the demo looks the same everywhere.
+     */
+    const addDemoPickupCode = useCallback((call) => {
+        if (!call?.isDemo || call.queueId !== DEMO_QUEUE_ID) {
+            return;
+        }
+
+        setPickupCodes((previous) =>
+            previous[DEMO_QUEUE_ID] === DEMO_PICKUP_CODE
+                ? previous
+                : { ...previous, [DEMO_QUEUE_ID]: DEMO_PICKUP_CODE }
+        );
+    }, []);
+
+    /** Undo the above, so the map only ever holds real configured codes. */
+    const dropDemoPickupCode = useCallback(() => {
+        setPickupCodes((previous) => {
+            if (!(DEMO_QUEUE_ID in previous)) {
+                return previous;
+            }
+
+            const next = { ...previous };
+            delete next[DEMO_QUEUE_ID];
+
+            return next;
+        });
+    }, []);
+
+    /**
+     * Fire-and-forget message to every other tab. No-op when the channel is
+     * unsupported or already closed.
+     */
+    const broadcastSync = useCallback((message) => {
+        const bus = syncChannel.current;
+
+        if (!bus) {
+            return;
+        }
+
+        try {
+            bus.postMessage(message);
+        } catch (error) {
+            // A closed/unsupported channel must never break the UI.
+        }
+    }, []);
+
+    /**
+     * Local removal plus a cross-tab `remove`, for the two user actions that
+     * settle a call: Dismiss and Pick up.
+     */
+    const dismissCall = useCallback(
+        (callId) => {
+            removeCall(callId);
+            broadcastSync({ type: 'remove', callId: String(callId) });
+        },
+        [broadcastSync, removeCall]
+    );
+
+    /**
+     * Expand/collapse a card's open-task list, fetching it the first time it is
+     * opened. Like everything else here the request fails silently — a card that
+     * cannot list its tasks still rings, picks up and dismisses.
+     */
+    const toggleTasks = useCallback(
+        (call) => {
+            const callId = call.callId;
+
+            setExpandedTasks((previous) => ({
+                ...previous,
+                [callId]: previous[callId] !== true,
+            }));
+
+            // Demo cards carry their own tasks, and the demo client (id 0) has
+            // nothing on the server to ask for.
+            if (Array.isArray(call.tasks) || !call.client?.id) {
+                return;
+            }
+
+            if (taskFetched.current.has(callId)) {
+                return;
+            }
+
+            taskFetched.current.add(callId);
+
+            const settle = (status, tasks) => {
+                setTaskLists((previous) => ({
+                    ...previous,
+                    [callId]: { status, tasks },
+                }));
+            };
+
+            settle('loading', []);
+
+            try {
+                const request = CustomFetch(
+                    clientTasksEndpoint(call.client.id),
+                    'GET',
+                    {},
+                    function (result) {
+                        const tasks = Array.isArray(result)
+                            ? result
+                            : result?.tasks;
+
+                        settle('ready', Array.isArray(tasks) ? tasks : []);
+                    },
+                    function () {
+                        settle('error', []);
+                    }
+                );
+
+                if (request && typeof request.catch === 'function') {
+                    request.catch(() => {});
+                }
+            } catch (error) {
+                settle('error', []);
+            }
+        },
+        [clientTasksEndpoint]
+    );
+
+    /**
+     * Ingest a call from the snapshot or a broadcast. The client block is
+     * already on the payload — the server resolves the caller -> client match
+     * once per call rather than every watching browser doing it.
+     */
+    const ingestCall = useCallback(
+        (payload) => {
+            addCall(normaliseCall(payload));
+        },
+        [addCall]
+    );
+
+    /**
+     * Demo helpers. Registered unconditionally (when `demoEnabled`) so the UI
+     * can be reviewed by anyone, including a user without the monitor
+     * permission.
+     */
+    useEffect(() => {
+        if (!demoEnabled || typeof window === 'undefined') {
+            return undefined;
+        }
+
+        /** Add a demo call here and mirror it into every other open tab. */
+        const pushDemo = (call) => {
+            addDemoPickupCode(call);
+            addCall(call);
+            broadcastSync({ type: 'add', call });
+        };
+
+        window.callPopDemo = () => {
+            // Fixed ids (no Date.now()): a second tab running callPopDemo()
+            // itself can then never duplicate a card, and a `remove` broadcast
+            // matches the same card in every tab.
+            //
+            // This first card has no pickup code for its queue, so it renders
+            // the "Dismiss only" state.
+            pushDemo({
+                callId: 'demo-primary',
+                queueId: 'demo-main-queue',
+                queueName: 'Main CQ',
+                callerNumber: '+61412345678',
+                callerName: '',
+                client: null,
+                startedAt: new Date().toISOString(),
+                status: 'ringing',
+                isDemo: true,
+                leaving: false,
+            });
+
+            const secondaryTimer = setTimeout(() => {
+                // This one's queue IS in the pickup-code map, so it renders
+                // with a working Pick up button.
+                pushDemo({
+                    callId: 'demo-secondary',
+                    queueId: DEMO_QUEUE_ID,
+                    queueName: 'Test Call Queue',
+                    callerNumber: '+61298765432',
+                    callerName: 'Margaret Chen',
+                    // Every field the server's client block can carry, so the
+                    // rich card can be reviewed without a real match. id 0
+                    // renders the name as plain text, not a link.
+                    client: {
+                        id: 0,
+                        name: 'Chen, Margaret (Mrs)',
+                        matched_on: 'home',
+                        adviser: 'Alina Bailey',
+                        coding: 'Early Retirement',
+                        age: 66,
+                        email: 'margaret.chen@example.com',
+                        city: 'Fremantle',
+                        next_event: {
+                            title: 'Client - Annual Review',
+                            date: new Date(
+                                Date.now() + 2 * 24 * 60 * 60 * 1000
+                            ).toISOString(),
+                        },
+                        open_tasks: 2,
+                    },
+                    // Pre-supplied so the expansion can be reviewed without a
+                    // backend: with these present the chip never fetches.
+                    tasks: [
+                        {
+                            id: 90001,
+                            label: 'Confirm rollover paperwork',
+                            due_date: new Date(
+                                Date.now() + 3 * 24 * 60 * 60 * 1000
+                            ).toISOString(),
+                            task_type: 'Superannuation',
+                        },
+                        {
+                            id: 90002,
+                            label: 'Send updated risk profile questionnaire',
+                            due_date: new Date(
+                                Date.now() + 9 * 24 * 60 * 60 * 1000
+                            ).toISOString(),
+                            task_type: 'Insurance',
+                        },
+                    ],
+                    startedAt: new Date().toISOString(),
+                    status: 'ringing',
+                    isDemo: true,
+                    leaving: false,
+                });
+            }, 1500);
+
+            exitTimers.current.push(secondaryTimer);
+        };
+
+        window.callPopClear = () => {
+            clearCalls();
+            dropDemoPickupCode();
+            broadcastSync({ type: 'clear' });
+        };
+
+        return () => {
+            delete window.callPopDemo;
+            delete window.callPopClear;
+        };
+    }, [
+        addCall,
+        addDemoPickupCode,
+        broadcastSync,
+        clearCalls,
+        demoEnabled,
+        dropDemoPickupCode,
+    ]);
+
+    /**
+     * Cross-tab sync.
+     *
+     * Protocol (all messages are plain objects with a `type`):
+     *   { type: 'add', call }        -> demo injection mirrored to other tabs
+     *   { type: 'remove', callId }   -> Dismiss / Pick up settled the call
+     *   { type: 'clear' }            -> window.callPopClear()
+     * Handling an inbound message never re-broadcasts, so there is no loop.
+     * Unknown types are ignored and malformed payloads never throw.
+     */
+    useEffect(() => {
+        if (
+            typeof window === 'undefined' ||
+            typeof BroadcastChannel === 'undefined' ||
+            !syncChannelName
+        ) {
+            return undefined;
+        }
+
+        let bus = null;
+
+        try {
+            bus = new BroadcastChannel(syncChannelName);
+        } catch (error) {
+            return undefined;
+        }
+
+        syncChannel.current = bus;
+
+        bus.onmessage = (event) => {
+            try {
+                const message = event?.data;
+
+                if (!message || typeof message !== 'object') {
+                    return;
+                }
+
+                if (message.type === 'remove') {
+                    if (message.callId) {
+                        removeCall(message.callId);
+                    }
+
+                    return;
+                }
+
+                if (message.type === 'clear') {
+                    clearCalls();
+                    dropDemoPickupCode();
+
+                    return;
+                }
+
+                if (message.type === 'add') {
+                    // normaliseCall carries isDemo through, so a demo card
+                    // received here still bypasses the permission gate.
+                    const call = normaliseCall(message.call);
+
+                    addDemoPickupCode(call);
+                    addCall(call);
+                }
+            } catch (error) {
+                // A bad message from another tab must never break this one.
+            }
+        };
+
+        return () => {
+            try {
+                bus.onmessage = null;
+                bus.close();
+            } catch (error) {
+                // Already closed.
+            }
+
+            if (syncChannel.current === bus) {
+                syncChannel.current = null;
+            }
+        };
+    }, [
+        addCall,
+        addDemoPickupCode,
+        clearCalls,
+        dropDemoPickupCode,
+        removeCall,
+        syncChannelName,
+    ]);
+
+    /** Snapshot of what is already ringing when the page loads. */
+    useEffect(() => {
+        if (!canMonitor) {
+            return undefined;
+        }
+
+        let cancelled = false;
+
+        try {
+            const request = CustomFetch(
+                liveUrl,
+                'GET',
+                {},
+                function (result) {
+                    if (cancelled) {
+                        return;
+                    }
+
+                    if (
+                        typeof result?.channel === 'string' &&
+                        result.channel !== ''
+                    ) {
+                        setEchoChannel(result.channel);
+                    }
+
+                    if (result?.pickup_codes ?? result?.pickupCodes) {
+                        const codes = normalisePickupCodes(
+                            result.pickup_codes ?? result.pickupCodes
+                        );
+
+                        // Merged, not replaced: an injected demo code already
+                        // in the map must survive the snapshot landing.
+                        setPickupCodes((previous) => ({
+                            ...previous,
+                            ...codes,
+                        }));
+                    }
+
+                    const payload = Array.isArray(result)
+                        ? result
+                        : result?.calls;
+
+                    if (!Array.isArray(payload)) {
+                        return;
+                    }
+
+                    payload.forEach((item) => ingestCall(item));
+                },
+                function () {
+                    // Absence of the endpoint is expected pre-backend.
+                }
+            );
+
+            if (request && typeof request.catch === 'function') {
+                request.catch(() => {});
+            }
+        } catch (error) {
+            // Silent by design.
+        }
+
+        return () => {
+            cancelled = true;
+        };
+    }, [canMonitor, ingestCall, liveUrl]);
+
+    /** Live updates over Laravel Echo, when the broadcaster is wired up. */
+    useEffect(() => {
+        if (!canMonitor || !activeChannel || typeof window === 'undefined') {
+            return undefined;
+        }
+
+        // The prop may be an instance or a factory. A factory is called here
+        // rather than at mount so only a permission-gated user ever opens a
+        // Pusher connection — the lazy `getEcho()` behaviour, preserved.
+        const source = echoRef.current;
+        const instance = typeof source === 'function' ? source() : source;
+
+        if (!instance) {
+            return undefined;
+        }
+
+        let subscription = null;
+
+        try {
+            // Until /broadcasting/auth knows this channel the subscription just
+            // fails auth — pusher-js logs a warning, nothing of ours throws.
+            subscription = instance.private(activeChannel);
+
+            subscription.listen(EVENT_RINGING, (event) => {
+                ingestCall(event?.call ?? event);
+            });
+
+            subscription.listen(EVENT_ANSWERED, (event) => {
+                const callId =
+                    event?.callId ?? event?.call_id ?? event?.call?.callId;
+
+                if (callId) {
+                    removeCall(callId);
+                }
+            });
+
+            subscription.listen(EVENT_ENDED, (event) => {
+                const callId =
+                    event?.callId ?? event?.call_id ?? event?.call?.callId;
+
+                if (callId) {
+                    removeCall(callId);
+                }
+            });
+        } catch (error) {
+            subscription = null;
+        }
+
+        return () => {
+            try {
+                if (subscription) {
+                    subscription.stopListening(EVENT_RINGING);
+                    subscription.stopListening(EVENT_ANSWERED);
+                    subscription.stopListening(EVENT_ENDED);
+                }
+
+                instance.leave(activeChannel);
+            } catch (error) {
+                // Nothing to clean up.
+            }
+        };
+    }, [activeChannel, canMonitor, ingestCall, removeCall]);
+
+    /**
+     * One interval for the whole stack, started only while cards are on screen
+     * and torn down the moment the stack empties.
+     */
+    useEffect(() => {
+        if (calls.length === 0) {
+            return undefined;
+        }
+
+        setNow(Date.now());
+
+        const interval = setInterval(() => {
+            setNow(Date.now());
+        }, 1000);
+
+        return () => clearInterval(interval);
+    }, [calls.length]);
+
+    /**
+     * Ask for notification permission, lazily and only for gated-in users.
+     *
+     * Chrome/Safari reject `requestPermission()` outside a user gesture, so the
+     * request is parked behind the first click or keypress after mount and the
+     * listeners are torn down as soon as it fires. Demo-only visitors never get
+     * a prompt — a demo call still notifies, but only if permission is already
+     * granted.
+     */
+    useEffect(() => {
+        if (!canMonitor || typeof window === 'undefined') {
+            return undefined;
+        }
+
+        if (typeof Notification === 'undefined') {
+            return undefined;
+        }
+
+        if (Notification.permission !== 'default') {
+            return undefined;
+        }
+
+        let asked = false;
+
+        const detach = () => {
+            window.removeEventListener('click', request, true);
+            window.removeEventListener('keydown', request, true);
+        };
+
+        function request() {
+            if (asked) {
+                return;
+            }
+
+            asked = true;
+            detach();
+
+            try {
+                const result = Notification.requestPermission();
+
+                if (result && typeof result.catch === 'function') {
+                    result.catch(() => {});
+                }
+            } catch (error) {
+                // Legacy callback-only implementations, or a blocked prompt.
+            }
+        }
+
+        window.addEventListener('click', request, true);
+        window.addEventListener('keydown', request, true);
+
+        return detach;
+    }, [canMonitor]);
+
+    /**
+     * System notifications: raise one per newly-arrived call while the tab is
+     * in the background, and close it again the instant the call leaves the
+     * stack (dismissed, picked up, cross-tab remove, answered/ended, cleared).
+     *
+     * `tag` is keyed on the callId so N open tabs collapse to a single
+     * notification for a given call rather than N of them.
+     */
+    useEffect(() => {
+        const live = calls.filter((call) => !call.leaving);
+        const liveIds = new Set(live.map((call) => call.callId));
+
+        notifications.current.forEach((notification, callId) => {
+            if (liveIds.has(callId)) {
+                return;
+            }
+
+            try {
+                notification.close();
+            } catch (error) {
+                // Already dismissed by the OS.
+            }
+
+            notifications.current.delete(callId);
+        });
+
+        notified.current.forEach((callId) => {
+            if (!liveIds.has(callId)) {
+                notified.current.delete(callId);
+            }
+        });
+
+        live.forEach((call) => {
+            if (notified.current.has(call.callId)) {
+                return;
+            }
+
+            // Marked regardless of outcome: a call only ever notifies on
+            // arrival, never later when the tab happens to lose focus.
+            notified.current.add(call.callId);
+
+            try {
+                if (typeof Notification === 'undefined') {
+                    return;
+                }
+
+                if (Notification.permission !== 'granted') {
+                    return;
+                }
+
+                if (isPageVisible()) {
+                    return;
+                }
+
+                const number = formatAuPhone(call.callerNumber);
+                const clientName = call.client?.name || '';
+
+                // A matched client leads: who is calling matters more than the
+                // digits they are calling from.
+                const body = clientName
+                    ? `${clientName} · ${number}`
+                    : [number, call.callerName].filter(Boolean).join(' · ');
+
+                const notification = new Notification(
+                    `Incoming call — ${call.queueName}`,
+                    {
+                        body,
+                        tag: `cqpop-${call.callId}`,
+                        requireInteraction: true,
+                    }
+                );
+
+                // Focus IS allowed from inside a notification click handler —
+                // this is the only sanctioned "bring the window to front" path.
+                notification.onclick = () => {
+                    try {
+                        window.focus();
+                        notification.close();
+                    } catch (error) {
+                        // Nothing further to do.
+                    }
+                };
+
+                notifications.current.set(call.callId, notification);
+            } catch (error) {
+                // Notifications are strictly best-effort.
+            }
+        });
+    }, [calls]);
+
+    /**
+     * Forget the drill-down state of any call that has left the stack, so a
+     * later call reusing a callId (the demo cards do) starts collapsed and
+     * re-fetches rather than showing the previous card's tasks.
+     */
+    useEffect(() => {
+        const liveIds = new Set(calls.map((call) => call.callId));
+
+        const prune = (previous) => {
+            const keys = Object.keys(previous);
+
+            if (keys.every((key) => liveIds.has(key))) {
+                return previous;
+            }
+
+            const next = {};
+
+            keys.forEach((key) => {
+                if (liveIds.has(key)) {
+                    next[key] = previous[key];
+                }
+            });
+
+            return next;
+        };
+
+        setExpandedTasks(prune);
+        setTaskLists(prune);
+
+        taskFetched.current.forEach((callId) => {
+            if (!liveIds.has(callId)) {
+                taskFetched.current.delete(callId);
+            }
+        });
+    }, [calls]);
+
+    /**
+     * Flash the tab title while a call rings in a hidden tab. The original
+     * title is captured when flashing starts (the SPA rewrites it on
+     * navigation) and restored on stop, on unmount, and the moment the tab is
+     * looked at again.
+     */
+    useEffect(() => {
+        if (typeof document === 'undefined' || !hasRinging) {
+            return undefined;
+        }
+
+        let interval = null;
+        let original = document.title;
+        let flashing = false;
+
+        const stop = () => {
+            if (interval) {
+                clearInterval(interval);
+                interval = null;
+            }
+
+            if (flashing) {
+                document.title = original;
+                flashing = false;
+            }
+        };
+
+        const start = () => {
+            if (interval) {
+                return;
+            }
+
+            original = document.title;
+
+            interval = setInterval(() => {
+                document.title = flashing ? original : FLASH_TITLE;
+                flashing = !flashing;
+            }, FLASH_MS);
+        };
+
+        const sync = () => {
+            if (document.visibilityState === 'hidden') {
+                start();
+            } else {
+                stop();
+            }
+        };
+
+        sync();
+        document.addEventListener('visibilitychange', sync);
+
+        return () => {
+            document.removeEventListener('visibilitychange', sync);
+            stop();
+        };
+    }, [hasRinging]);
+
+    /** Drop any pending exit timers, notifications and titles on unmount. */
+    useEffect(
+        () => () => {
+            exitTimers.current.forEach((timer) => clearTimeout(timer));
+            exitTimers.current = [];
+
+            notifications.current.forEach((notification) => {
+                try {
+                    notification.close();
+                } catch (error) {
+                    // Already dismissed.
+                }
+            });
+
+            notifications.current.clear();
+            notified.current.clear();
+        },
+        []
+    );
+
+    /** The dial string for a call's queue, or '' when that queue has none. */
+    const pickupCodeFor = (call) =>
+        (call.queueId !== null && pickupCodes[call.queueId]) || '';
+
+    /** A task's popup target, from the `taskUrl` builder or `{id}` template. */
+    const hrefForTask = (task) =>
+        resolveUrl(taskUrl, '{id}', task, defaultTaskUrl);
+
+    /**
+     * Open a task row. With no `onOpenTask` handler this keeps the CRM's own
+     * behaviour: the same detached popup window the tasks list page uses.
+     */
+    const openTask = (task) => {
+        if (typeof onOpenTask === 'function') {
+            onOpenTask(task);
+
+            return;
+        }
+
+        window.open(
+            hrefForTask(task),
+            '',
+            'width=1440,height=1024,menubar=1,resizable=1,status=1,titlebar=1,toolbar=1'
+        );
+    };
+
+    /**
+     * Pick up: copy the queue's code, tell the user, and settle the card here
+     * and in every other tab. The `zoomphonecall://` href fires alongside this
+     * handler and hands the code to the Zoom desktop client.
+     *
+     * Only reachable from a card whose queue actually has a code — the button
+     * is not rendered otherwise.
+     */
+    const handlePickup = (call) => {
+        const code = pickupCodeFor(call);
+
+        if (code !== '') {
+            try {
+                if (navigator?.clipboard?.writeText) {
+                    navigator.clipboard.writeText(code).catch(() => {});
+                }
+            } catch (error) {
+                // Clipboard is best-effort; the href still fires.
+            }
+
+            toast.info(
+                `Pickup code ${code} copied — dial it in Zoom if the call didn't connect`
+            );
+        }
+
+        // The user is taking this call: clear it here and everywhere else. The
+        // server's `queue.answered` event remains the authoritative cleanup.
+        dismissCall(call.callId);
+    };
+
+    if (!isVisible || calls.length === 0) {
+        return null;
+    }
+
+    return (
+        <div className={styles.cqpopStack}>
+            {trialText ? (
+                <div className={styles.cqpopTrial}>
+                    <FlaskConical size={12} />
+                    <span>{trialText}</span>
+                </div>
+            ) : null}
+            {calls.map((call) => {
+                const pickupCode = pickupCodeFor(call);
+                const client = call.client;
+                const details = clientDetails(client);
+                const nextEvent = client?.next_event ?? null;
+                const nextEventDate = formatEventDate(nextEvent?.date);
+                const openTasks = Number(client?.open_tasks ?? 0);
+                const workspaceId = toCallWorkspaceId(call.callerNumber);
+                const workspaceHref =
+                    typeof callWorkspacePath === 'function'
+                        ? callWorkspacePath(workspaceId, call)
+                        : applyTemplate(
+                              callWorkspacePath,
+                              '{number}',
+                              workspaceId
+                          );
+                const tasksPanelId = `cqpop-tasks-${call.callId}`;
+                const tasksOpen = expandedTasks[call.callId] === true;
+
+                // Demo cards ship a ready-made list; everything else waits on
+                // (or has already had) the drill-down fetch.
+                const tasksPanel = Array.isArray(call.tasks)
+                    ? { status: 'ready', tasks: call.tasks }
+                    : (taskLists[call.callId] ?? { status: 'idle', tasks: [] });
+
+                return (
+                    <div
+                        className={`${styles.cqpopCard}${
+                            call.leaving ? ` ${styles.cqpopCardLeaving}` : ''
+                        }`}
+                        key={`cqpop-${call.callId}`}
+                    >
+                        <div className={styles.cqpopCardHead}>
+                            <span className={styles.cqpopBadge}>
+                                <span className={styles.cqpopDot} />
+                                {call.queueName}
+                            </span>
+                            <span className={styles.cqpopTimer}>
+                                Ringing · {formatElapsed(call.startedAt, now)}
+                            </span>
+                        </div>
+
+                        <div className={styles.cqpopCardBody}>
+                            <div className={styles.cqpopCaller}>
+                                <PhoneIncoming size={16} />
+                                <span className={styles.cqpopNumber}>
+                                    {formatAuPhone(call.callerNumber)}
+                                </span>
+                                {client?.matched_on ? (
+                                    <span className={styles.cqpopMatched}>
+                                        {client.matched_on}
+                                    </span>
+                                ) : null}
+                            </div>
+
+                            {call.callerName ? (
+                                <div className={styles.cqpopName}>
+                                    {call.callerName}
+                                </div>
+                            ) : null}
+
+                            {client ? (
+                                <div className={styles.cqpopClient}>
+                                    <div className={styles.cqpopClientHead}>
+                                        {client.id ? (
+                                            <Link
+                                                to={resolveUrl(
+                                                    clientUrl,
+                                                    '{id}',
+                                                    client,
+                                                    defaultClientUrl
+                                                )}
+                                                className={
+                                                    styles.cqpopClientLink
+                                                }
+                                            >
+                                                {client.name}
+                                            </Link>
+                                        ) : (
+                                            <span
+                                                className={
+                                                    styles.cqpopClientName
+                                                }
+                                            >
+                                                {client.name}
+                                            </span>
+                                        )}
+                                        {openTasks > 0 ? (
+                                            <button
+                                                type="button"
+                                                className={`${
+                                                    styles.cqpopClientTasks
+                                                }${
+                                                    tasksOpen
+                                                        ? ` ${styles.cqpopClientTasksOpen}`
+                                                        : ''
+                                                }`}
+                                                onClick={() =>
+                                                    toggleTasks(call)
+                                                }
+                                                aria-expanded={tasksOpen}
+                                                aria-controls={tasksPanelId}
+                                            >
+                                                <span>
+                                                    {openTasks} open task
+                                                    {openTasks === 1 ? '' : 's'}
+                                                </span>
+                                                <ChevronDown size={11} />
+                                            </button>
+                                        ) : null}
+                                    </div>
+
+                                    {details.length > 0 ? (
+                                        <dl className={styles.cqpopClientGrid}>
+                                            {details.map((row) => (
+                                                <React.Fragment
+                                                    key={`cqpop-${call.callId}-${row.label}`}
+                                                >
+                                                    <dt>{row.label}</dt>
+                                                    <dd>{row.value}</dd>
+                                                </React.Fragment>
+                                            ))}
+                                        </dl>
+                                    ) : null}
+
+                                    {/* The next meeting is a link into the
+                                        calendar, or a button when the host app
+                                        would rather open the event itself. */}
+                                    {nextEvent?.title ? (
+                                        typeof onOpenCalendar === 'function' ? (
+                                            <button
+                                                type="button"
+                                                className={
+                                                    styles.cqpopClientEvent
+                                                }
+                                                onClick={() =>
+                                                    onOpenCalendar(nextEvent)
+                                                }
+                                            >
+                                                Next: {nextEvent.title}
+                                                {nextEventDate
+                                                    ? ` · ${nextEventDate}`
+                                                    : ''}
+                                            </button>
+                                        ) : (
+                                            <Link
+                                                to={calendarPath}
+                                                className={
+                                                    styles.cqpopClientEvent
+                                                }
+                                            >
+                                                Next: {nextEvent.title}
+                                                {nextEventDate
+                                                    ? ` · ${nextEventDate}`
+                                                    : ''}
+                                            </Link>
+                                        )
+                                    ) : null}
+
+                                    {tasksOpen ? (
+                                        <div
+                                            className={styles.cqpopTasks}
+                                            id={tasksPanelId}
+                                        >
+                                            {tasksPanel.status === 'loading' ? (
+                                                <p
+                                                    className={
+                                                        styles.cqpopTasksNote
+                                                    }
+                                                >
+                                                    Loading tasks…
+                                                </p>
+                                            ) : null}
+
+                                            {tasksPanel.status === 'error' ? (
+                                                <p
+                                                    className={
+                                                        styles.cqpopTasksNote
+                                                    }
+                                                >
+                                                    Tasks unavailable
+                                                </p>
+                                            ) : null}
+
+                                            {tasksPanel.status === 'ready' &&
+                                            tasksPanel.tasks.length === 0 ? (
+                                                <p
+                                                    className={
+                                                        styles.cqpopTasksNote
+                                                    }
+                                                >
+                                                    No open tasks to show
+                                                </p>
+                                            ) : null}
+
+                                            {tasksPanel.tasks.length > 0 ? (
+                                                <ul
+                                                    className={
+                                                        styles.cqpopTasksList
+                                                    }
+                                                >
+                                                    {tasksPanel.tasks.map(
+                                                        (task) => {
+                                                            const due =
+                                                                formatDueDate(
+                                                                    task.due_date
+                                                                );
+
+                                                            const taskBody = (
+                                                                <>
+                                                                    <span
+                                                                        className={
+                                                                            styles.cqpopTasksLabel
+                                                                        }
+                                                                    >
+                                                                        {task.label ||
+                                                                            `Task #${task.id}`}
+                                                                    </span>
+                                                                    <span
+                                                                        className={
+                                                                            styles.cqpopTasksMeta
+                                                                        }
+                                                                    >
+                                                                        {task.task_type ? (
+                                                                            <span
+                                                                                className={
+                                                                                    styles.cqpopTasksType
+                                                                                }
+                                                                            >
+                                                                                {
+                                                                                    task.task_type
+                                                                                }
+                                                                            </span>
+                                                                        ) : null}
+                                                                        {due ? (
+                                                                            <span
+                                                                                className={
+                                                                                    styles.cqpopTasksDue
+                                                                                }
+                                                                            >
+                                                                                {
+                                                                                    due
+                                                                                }
+                                                                            </span>
+                                                                        ) : null}
+                                                                    </span>
+                                                                </>
+                                                            );
+
+                                                            return (
+                                                                <li
+                                                                    key={`${tasksPanelId}-${task.id}`}
+                                                                >
+                                                                    {call.isDemo ? (
+                                                                        // Demo tasks have fake ids — linking
+                                                                        // to the task route would 404.
+                                                                        <span
+                                                                            className={
+                                                                                styles.cqpopTasksItem
+                                                                            }
+                                                                        >
+                                                                            {
+                                                                                taskBody
+                                                                            }
+                                                                        </span>
+                                                                    ) : (
+                                                                        // Same popup-window behaviour as the
+                                                                        // tasks list page (openFamilyTask),
+                                                                        // unless onOpenTask says otherwise.
+                                                                        <a
+                                                                            href={hrefForTask(
+                                                                                task
+                                                                            )}
+                                                                            className={
+                                                                                styles.cqpopTasksItem
+                                                                            }
+                                                                            onClick={(
+                                                                                event
+                                                                            ) => {
+                                                                                event.preventDefault();
+                                                                                openTask(
+                                                                                    task
+                                                                                );
+                                                                            }}
+                                                                        >
+                                                                            {
+                                                                                taskBody
+                                                                            }
+                                                                        </a>
+                                                                    )}
+                                                                </li>
+                                                            );
+                                                        }
+                                                    )}
+                                                </ul>
+                                            ) : null}
+
+                                            {client?.id ? (
+                                                <Link
+                                                    to={resolveUrl(
+                                                        clientTasksUrl,
+                                                        '{id}',
+                                                        client.id,
+                                                        defaultClientTasksUrl
+                                                    )}
+                                                    className={
+                                                        styles.cqpopTasksAll
+                                                    }
+                                                >
+                                                    View all tasks →
+                                                </Link>
+                                            ) : null}
+                                        </div>
+                                    ) : null}
+                                </div>
+                            ) : (
+                                <div
+                                    className={`${styles.cqpopClient} ${styles.cqpopClientNone}`}
+                                >
+                                    No client match
+                                </div>
+                            )}
+                        </div>
+
+                        {/* No configured pickup code for this queue means no
+                            dial string to offer, so the card falls back to
+                            Dismiss alone rather than a button that cannot
+                            work. */}
+                        <div className={styles.cqpopCardActions}>
+                            {pickupCode !== '' ? (
+                                pickupEnabled ? (
+                                    <a
+                                        className={`${styles.cqpopBtn} ${styles.cqpopBtnAnswer}`}
+                                        href={`zoomphonecall://${pickupCode}`}
+                                        onClick={() => handlePickup(call)}
+                                    >
+                                        <Phone size={14} />
+                                        <span>Pick up</span>
+                                    </a>
+                                ) : (
+                                    <button
+                                        type="button"
+                                        className={`${styles.cqpopBtn} ${styles.cqpopBtnAnswer} ${styles.cqpopBtnSoon}`}
+                                        disabled
+                                        title="Pick up is coming soon — answer in Zoom for now"
+                                    >
+                                        <Phone size={14} />
+                                        <span>Pick up</span>
+                                    </button>
+                                )
+                            ) : null}
+                            <button
+                                type="button"
+                                className={`${styles.cqpopBtn} ${styles.cqpopBtnDismiss}`}
+                                onClick={() => dismissCall(call.callId)}
+                            >
+                                <X size={14} />
+                                <span>Dismiss</span>
+                            </button>
+                        </div>
+
+                        {/* Secondary by design: the workspace is a place to go
+                            after the call is in hand, never instead of Pick up. */}
+                        <div className={styles.cqpopCardMore}>
+                            {workspaceId !== '' && !call.isDemo ? (
+                                <Link
+                                    to={workspaceHref}
+                                    className={styles.cqpopLink}
+                                >
+                                    <ExternalLink size={12} />
+                                    <span>Open call workspace</span>
+                                </Link>
+                            ) : (
+                                <span
+                                    className={`${styles.cqpopLink} ${styles.cqpopLinkInert}`}
+                                    aria-disabled="true"
+                                >
+                                    <ExternalLink size={12} />
+                                    <span>Open call workspace</span>
+                                </span>
+                            )}
+                        </div>
+                    </div>
+                );
+            })}
+        </div>
+    );
+};
+
+export default CallQueuePop;