@marinoscar/platform-web 0.1.0-next.3 → 0.1.0-next.4

package/dist/notifications/headless/useBroadcasts.js

@@ -0,0 +1,187 @@
+/**
+ * The broadcast list and the writes (issue #325, epic #319; resume, #459).
+ *
+ * Two exports in one file, in the shape `hooks/useJobs.ts` establishes for an
+ * admin resource page: a list hook whose `refresh` does NOT raise the loading
+ * flag, and an actions hook with one in-flight flag and one error string. What
+ * they share is the contract — every function RESOLVES rather than throws, and
+ * a failure is a STRING the page renders — because every caller is a click
+ * handler that needs to branch, not a place to handle an exception that has
+ * already been captured for display.
+ *
+ * =============================================================================
+ * `useVisiblePolling` — RE-EXPORTED, NOT DEFINED HERE
+ * =============================================================================
+ *
+ * Same arrangement as `useJobs.ts` and `useWorkerNodes.ts`: there is exactly
+ * one implementation, in `hooks/useVisiblePolling.ts`, and it is re-exported
+ * from here so `BroadcastsPage` takes its polling from the hook module it
+ * already depends on — which is also what keeps a page test that mocks
+ * `hooks/useBroadcasts` in control of the poll.
+ *
+ * =============================================================================
+ * WHY THIS PAGE POLLS LESS EAGERLY THAN JOBS
+ * =============================================================================
+ *
+ * A queue is never at rest; a broadcast list usually is. Most of the time every
+ * row is `sent`, `canceled` or `failed` — states that cannot change with
+ * nobody touching them (a `failed` row only moves when an admin resumes it,
+ * which turns it `sending` and so re-enables the poll) — and polling those is a request per ten seconds
+ * for an answer that is known in advance. So `BroadcastsPage` passes `0` (which
+ * `useVisiblePolling` treats as "off") unless a row is actually `scheduled` or
+ * `sending`, and the interval below is what it passes when one is.
+ */
+import { useCallback, useRef, useState } from 'react';
+import { ApiError } from './api.js';
+import { useVisiblePolling } from './useVisiblePolling.js';
+import { cancelBroadcast, createBroadcast, deleteBroadcast, getBroadcasts, resumeBroadcast, sendTestBroadcast, } from './broadcasts.js';
+import { useIsMounted } from './useIsMounted.js';
+// See the file header: one implementation, in `hooks/useVisiblePolling.ts`.
+export { useVisiblePolling };
+/**
+ * How often the broadcasts page re-asks while something is in flight.
+ *
+ * The same ten seconds the jobs page uses, and for the same reason: the thing
+ * being watched is `recipientsDispatched` climbing through an audience in
+ * chunks, which a faster poll does not observe any better. Unlike Jobs, this
+ * interval is only ever REACHED while a row is `scheduled` or `sending` — see
+ * the file header.
+ */
+export const BROADCASTS_POLL_INTERVAL_MS = 10_000;
+/** Turn any thrown value into the sentence the page will render. */
+function messageFor(err, fallback) {
+    if (err instanceof ApiError) {
+        // Named explicitly because their remedies are not a retry — the same
+        // treatment `useJobs` gives 403.
+        if (err.status === 403)
+            return 'You do not have permission to manage broadcasts';
+        // 409 is this surface's characteristic refusal: a cancel that lost the race
+        // with the fan-out, a delete of something already sending, or a resume of a
+        // broadcast that is no longer `failed` (another admin resumed or cancelled
+        // it first). The API's own message says which, so it is passed through
+        // rather than replaced.
+        return err.message;
+    }
+    return fallback;
+}
+export function useBroadcasts() {
+    const [broadcasts, setBroadcasts] = useState([]);
+    const [total, setTotal] = useState(0);
+    const [isLoading, setIsLoading] = useState(true);
+    const [error, setError] = useState(null);
+    // Every `setState` past an `await` is guarded: a request that settles after
+    // the component is gone must not schedule an update on it.
+    const isMounted = useIsMounted();
+    /**
+     * The last query, so a poll repeats the CURRENT view rather than an
+     * unfiltered one. A ref and not state: a re-render on every query would be a
+     * re-render that changes nothing on screen, and the value is only ever read
+     * from inside a callback.
+     */
+    const lastParams = useRef({});
+    const runQuery = useCallback(async (params, showLoading) => {
+        // A POLL DOES NOT RAISE THE LOADING FLAG. The rows stay on screen and the
+        // table keeps its scroll offset, its expansion and its focus — which
+        // matters more here than on the jobs page, because the thing an operator
+        // is watching during a send is one row's progress counter.
+        if (showLoading)
+            setIsLoading(true);
+        setError(null);
+        try {
+            const response = await getBroadcasts(params);
+            if (isMounted()) {
+                setBroadcasts(response.items);
+                setTotal(response.total);
+            }
+        }
+        catch (err) {
+            if (isMounted()) {
+                setError(messageFor(err, 'Failed to load broadcasts'));
+                // Cleared, not left standing: rows from the previous successful query
+                // under an error banner read as the current state of the list.
+                setBroadcasts([]);
+                setTotal(0);
+            }
+        }
+        finally {
+            if (isMounted() && showLoading)
+                setIsLoading(false);
+        }
+    }, [isMounted]);
+    const fetchBroadcasts = useCallback(async (params = {}) => {
+        lastParams.current = params;
+        await runQuery(params, true);
+    }, [runQuery]);
+    const refresh = useCallback(async () => {
+        await runQuery(lastParams.current, false);
+    }, [runQuery]);
+    return { broadcasts, total, isLoading, error, fetchBroadcasts, refresh };
+}
+/**
+ * The writes, sharing one in-flight flag and one error.
+ *
+ * ONE FLAG FOR ALL OF THEM, as `useJobActions` does: they all mutate the same
+ * list, the page re-reads it after any of them, and a second write started
+ * while the first is landing would report its result over the top of the
+ * first's. Disabling the whole action set for the duration is the honest
+ * reading of "these are not independent".
+ *
+ * `sendTest` is in this set even though it mutates NOTHING — it stores no row
+ * and queues no job. It shares the flag anyway because it shares the composer:
+ * a test send and a real send are the same form, and letting the admin submit
+ * for real while a test of the same composition is in flight is how you get two
+ * conflicting snackbars over one dialog.
+ */
+export function useBroadcastActions(onChanged) {
+    const [isWorking, setIsWorking] = useState(false);
+    const [error, setError] = useState(null);
+    const isMounted = useIsMounted();
+    // Held in a ref for the same reason `useVisiblePolling` holds its callback:
+    // the page passes a fresh closure over the current query on every render, and
+    // depending on it would rebuild every callback each time.
+    const onChangedRef = useRef(onChanged);
+    onChangedRef.current = onChanged;
+    const run = useCallback(async (operation, fallback, { notifiesChange = true } = {}) => {
+        setIsWorking(true);
+        setError(null);
+        try {
+            const result = await operation();
+            // The list changed, so whatever is on screen is now stale. Fired AFTER
+            // the write resolves and never in parallel with it: a refresh racing
+            // its own mutation is how a canceled broadcast flickers back to
+            // `scheduled` for one frame.
+            //
+            // `notifiesChange: false` is the test send's case — it writes no row,
+            // so refetching the list would be a request that can only ever return
+            // what is already on screen.
+            if (notifiesChange)
+                onChangedRef.current?.();
+            return result;
+        }
+        catch (err) {
+            if (isMounted())
+                setError(messageFor(err, fallback));
+            return null;
+        }
+        finally {
+            if (isMounted())
+                setIsWorking(false);
+        }
+    }, [isMounted]);
+    const create = useCallback((body) => run(() => createBroadcast(body), 'Failed to create broadcast'), [run]);
+    const cancel = useCallback(async (id) => (await run(() => cancelBroadcast(id), 'Failed to cancel broadcast')) !== null, [run]);
+    const resume = useCallback(async (id) => (await run(() => resumeBroadcast(id), 'Failed to resume broadcast')) !== null, [run]);
+    const remove = useCallback(async (id) => (await run(async () => {
+        await deleteBroadcast(id);
+        // `deleteBroadcast` resolves `undefined` (the endpoint answers 204),
+        // and `run` reports failure as `null` — so a literal is returned to
+        // keep "succeeded" distinguishable from "failed".
+        return true;
+    }, 'Failed to delete broadcast')) !== null, [run]);
+    const sendTest = useCallback((body) => run(() => sendTestBroadcast(body), 'Failed to send the test notification', {
+        notifiesChange: false,
+    }), [run]);
+    const clearError = useCallback(() => setError(null), []);
+    return { isWorking, error, clearError, create, cancel, resume, remove, sendTest };
+}
+//# sourceMappingURL=useBroadcasts.js.map

package/dist/notifications/headless/useBroadcasts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useBroadcasts.js","sourceRoot":"","sources":["../../../src/notifications/headless/useBroadcasts.ts"],"names":[],"mappings":"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"}

package/dist/notifications/headless/useBrowserNotificationPermission.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The browser's CURRENT notification permission, observed — never requested.
+ *
+ * Issue #126, epic #109. The preferences page has a `browser` column, and a
+ * stored preference for it means nothing on its own: the browser, not the app,
+ * decides whether a native notification may be raised at all. This hook is how
+ * that column tells the truth.
+ *
+ * THIS HOOK NEVER CALLS `Notification.requestPermission()` — it only observes.
+ * Requesting is `services/browserNotifications.ts`'s job, and since #365 the app
+ * DOES prompt without a click: `hooks/usePushSubscriptionSync.ts` auto-prompts
+ * once per page load when the deployment has push enabled, and the app-wide
+ * banner and the settings page offer a button for browsers that ignore a
+ * gestureless request. Keeping every request out of this file means "what
+ * prompts, and when?" is answered by that one service's callers.
+ *
+ * WHY A HOOK RATHER THAN READING `Notification.permission` INLINE
+ * ---------------------------------------------------------------
+ * Because the value CHANGES UNDER THE PAGE. A user who reads "blocked — allow
+ * notifications in your browser settings", opens those settings in another tab,
+ * flips the switch and comes back would otherwise still be looking at "blocked"
+ * until a full reload — and would reasonably conclude the app is broken. So the
+ * value is state, and it is re-read on the signals that can indicate a change:
+ *
+ *   1. The Permissions API's `change` event, where available — the exact,
+ *     immediate signal.
+ *   2. `visibilitychange`, as the fallback for browsers whose Permissions API
+ *     does not expose `notifications` (older Safari). Coming back to the tab is
+ *     precisely the moment a user who just changed the setting returns.
+ *   3. `NOTIFICATION_PERMISSION_CHANGED_EVENT` (#365), which this app fires
+ *     after its own requests settle, so every mounted instance — the shell's
+ *     banner and the settings page — updates together.
+ */
+/**
+ * Permission as this app needs to reason about it.
+ *
+ * `'unsupported'` is a FOURTH state the Web API does not have, and it is not
+ * the same as `'denied'`: the browser has refused nothing, it simply has no
+ * `Notification` constructor (an old browser, or — the common case in this
+ * repo — jsdom under the test runner, and any non-secure-context origin). The
+ * UI must say "your browser does not support this", not "you blocked this",
+ * because the remedies are completely different and only one of them exists.
+ */
+export type BrowserNotificationPermission = 'unsupported' | 'default' | 'granted' | 'denied';
+export interface UseBrowserNotificationPermissionResult {
+    /** What the browser says right now. See `BrowserNotificationPermission`. */
+    permission: BrowserNotificationPermission;
+    /**
+     * Force a re-read.
+     *
+     * CALLED BY EVERY PROMPT HANDLER (`UserNotificationsPage`,
+     * `usePushSubscriptionSync`), in a `finally`, after
+     * `Notification.requestPermission()` settles — so the UI moves to its
+     * `granted` or `denied` treatment without a reload.
+     *
+     * Unconditional there rather than driven by the request's return value: the
+     * user can dismiss the prompt without choosing (permission stays `default`)
+     * and some browsers resolve with nothing useful at all. Re-reading
+     * `Notification.permission` is the only answer that is right in every case.
+     */
+    refresh: () => void;
+}
+export declare function useBrowserNotificationPermission(): UseBrowserNotificationPermissionResult;
+//# sourceMappingURL=useBrowserNotificationPermission.d.ts.map

package/dist/notifications/headless/useBrowserNotificationPermission.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useBrowserNotificationPermission.d.ts","sourceRoot":"","sources":["../../../src/notifications/headless/useBrowserNotificationPermission.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAKH;;;;;;;;;GASG;AACH,MAAM,MAAM,6BAA6B,GACrC,aAAa,GACb,SAAS,GACT,SAAS,GACT,QAAQ,CAAC;AAyBb,MAAM,WAAW,sCAAsC;IACrD,4EAA4E;IAC5E,UAAU,EAAE,6BAA6B,CAAC;IAC1C;;;;;;;;;;;;OAYG;IACH,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED,wBAAgB,gCAAgC,IAAI,sCAAsC,CA+DzF"}

package/dist/notifications/headless/useBrowserNotificationPermission.js

@@ -0,0 +1,119 @@
+/**
+ * The browser's CURRENT notification permission, observed — never requested.
+ *
+ * Issue #126, epic #109. The preferences page has a `browser` column, and a
+ * stored preference for it means nothing on its own: the browser, not the app,
+ * decides whether a native notification may be raised at all. This hook is how
+ * that column tells the truth.
+ *
+ * THIS HOOK NEVER CALLS `Notification.requestPermission()` — it only observes.
+ * Requesting is `services/browserNotifications.ts`'s job, and since #365 the app
+ * DOES prompt without a click: `hooks/usePushSubscriptionSync.ts` auto-prompts
+ * once per page load when the deployment has push enabled, and the app-wide
+ * banner and the settings page offer a button for browsers that ignore a
+ * gestureless request. Keeping every request out of this file means "what
+ * prompts, and when?" is answered by that one service's callers.
+ *
+ * WHY A HOOK RATHER THAN READING `Notification.permission` INLINE
+ * ---------------------------------------------------------------
+ * Because the value CHANGES UNDER THE PAGE. A user who reads "blocked — allow
+ * notifications in your browser settings", opens those settings in another tab,
+ * flips the switch and comes back would otherwise still be looking at "blocked"
+ * until a full reload — and would reasonably conclude the app is broken. So the
+ * value is state, and it is re-read on the signals that can indicate a change:
+ *
+ *   1. The Permissions API's `change` event, where available — the exact,
+ *     immediate signal.
+ *   2. `visibilitychange`, as the fallback for browsers whose Permissions API
+ *     does not expose `notifications` (older Safari). Coming back to the tab is
+ *     precisely the moment a user who just changed the setting returns.
+ *   3. `NOTIFICATION_PERMISSION_CHANGED_EVENT` (#365), which this app fires
+ *     after its own requests settle, so every mounted instance — the shell's
+ *     banner and the settings page — updates together.
+ */
+import { useCallback, useEffect, useState } from 'react';
+import { NOTIFICATION_PERMISSION_CHANGED_EVENT } from './browserNotifications.js';
+/**
+ * Read the permission defensively.
+ *
+ * Feature-detected on every read rather than once at module load: this module
+ * is imported by a lazily-loaded page, and a module-level snapshot would also
+ * be unpatchable from a test that stubs `window.Notification` after import.
+ *
+ * The `try` is not decorative. Some embedded and privacy-hardened browsers
+ * define `Notification` and THROW on the property access, and this is a
+ * settings page — a permission read must never be the thing that blanks it.
+ */
+function readPermission() {
+    if (typeof window === 'undefined' || !('Notification' in window)) {
+        return 'unsupported';
+    }
+    try {
+        const value = window.Notification.permission;
+        return value === 'granted' || value === 'denied' ? value : 'default';
+    }
+    catch {
+        return 'unsupported';
+    }
+}
+export function useBrowserNotificationPermission() {
+    // Lazy initialiser, so the read happens once on mount rather than on every
+    // render of a component that may re-render on each toggle.
+    const [permission, setPermission] = useState(readPermission);
+    const refresh = useCallback(() => {
+        setPermission(readPermission());
+    }, []);
+    useEffect(() => {
+        // Re-read once on mount as well as in the initialiser: this page is lazily
+        // loaded and the module may have been evaluated long before it mounted.
+        refresh();
+        const onVisibility = () => {
+            // Only when the tab becomes visible. Re-reading as it HIDES is work
+            // nobody can see, and the interesting transition is the return.
+            if (document.visibilityState === 'visible')
+                refresh();
+        };
+        document.addEventListener('visibilitychange', onVisibility);
+        // An app-initiated request settled somewhere (#365) — see the header.
+        window.addEventListener(NOTIFICATION_PERMISSION_CHANGED_EVENT, refresh);
+        // The Permissions API is the precise signal, and is optional in two ways:
+        // the API may be absent, and `notifications` may be an unsupported name
+        // (Safari), in which case `query` REJECTS rather than returning a status.
+        // Both are handled by falling back to `visibilitychange` above.
+        let status = null;
+        let cancelled = false;
+        const onChange = () => refresh();
+        // The `try` wraps the CALL, not just the promise: older WebKit throws a
+        // synchronous `TypeError` for an unsupported permission name rather than
+        // returning a rejected promise, and an exception escaping an effect would
+        // take the whole settings page down over a progressive enhancement.
+        try {
+            void navigator.permissions
+                ?.query({ name: 'notifications' })
+                .then((result) => {
+                // The component may have unmounted while this promise was in flight;
+                // binding the listener then would leak it past the cleanup below.
+                if (cancelled)
+                    return;
+                status = result;
+                result.addEventListener('change', onChange);
+                refresh();
+            })
+                .catch(() => {
+                // Not supported here. `visibilitychange` remains the fallback; this
+                // is an expected outcome, not an error worth surfacing to the user.
+            });
+        }
+        catch {
+            // Same fallback as the rejection path above.
+        }
+        return () => {
+            cancelled = true;
+            document.removeEventListener('visibilitychange', onVisibility);
+            window.removeEventListener(NOTIFICATION_PERMISSION_CHANGED_EVENT, refresh);
+            status?.removeEventListener('change', onChange);
+        };
+    }, [refresh]);
+    return { permission, refresh };
+}
+//# sourceMappingURL=useBrowserNotificationPermission.js.map

package/dist/notifications/headless/useBrowserNotificationPermission.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useBrowserNotificationPermission.js","sourceRoot":"","sources":["../../../src/notifications/headless/useBrowserNotificationPermission.ts"],"names":[],"mappings":"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"}

package/dist/notifications/headless/useIsMounted.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Returns a stable getter for "is this component still mounted?".
+ *
+ * Used to guard `setState` in the tail of an async operation. A ref rather
+ * than state, and a getter rather than the ref itself, so callers can hold it
+ * in a `useCallback` dependency list without invalidating on every render.
+ */
+export declare function useIsMounted(): () => boolean;
+//# sourceMappingURL=useIsMounted.d.ts.map

package/dist/notifications/headless/useIsMounted.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useIsMounted.d.ts","sourceRoot":"","sources":["../../../src/notifications/headless/useIsMounted.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,wBAAgB,YAAY,IAAI,MAAM,OAAO,CAW5C"}

package/dist/notifications/headless/useIsMounted.js

@@ -0,0 +1,19 @@
+import { useCallback, useEffect, useRef } from 'react';
+/**
+ * Returns a stable getter for "is this component still mounted?".
+ *
+ * Used to guard `setState` in the tail of an async operation. A ref rather
+ * than state, and a getter rather than the ref itself, so callers can hold it
+ * in a `useCallback` dependency list without invalidating on every render.
+ */
+export function useIsMounted() {
+    const mounted = useRef(true);
+    useEffect(() => {
+        mounted.current = true;
+        return () => {
+            mounted.current = false;
+        };
+    }, []);
+    return useCallback(() => mounted.current, []);
+}
+//# sourceMappingURL=useIsMounted.js.map

package/dist/notifications/headless/useIsMounted.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useIsMounted.js","sourceRoot":"","sources":["../../../src/notifications/headless/useIsMounted.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AAEvD;;;;;;GAMG;AACH,MAAM,UAAU,YAAY;IAC1B,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;IAE7B,SAAS,CAAC,GAAG,EAAE;QACb,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC;QACvB,OAAO,GAAG,EAAE;YACV,OAAO,CAAC,OAAO,GAAG,KAAK,CAAC;QAC1B,CAAC,CAAC;IACJ,CAAC,EAAE,EAAE,CAAC,CAAC;IAEP,OAAO,WAAW,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;AAChD,CAAC"}