@phoenix-iq/notifications 0.0.0-stage → 1.1.0

package/dist/bell.js

@@ -0,0 +1,331 @@
+import { applyColors, applyTheme, colorOr, ICONS, svg, uiLanguage } from './theme.js';
+const MESSAGE_MS = 3500;
+const ATTENTION_MS = 4000;
+const TEXTS = {
+    en: {
+        unsubscribed: 'Subscribe to notifications',
+        subscribed: "You're subscribed to notifications",
+        blocked: "You've blocked notifications",
+        thanks: 'Thanks for subscribing!',
+        goodbye: "You won't get notifications any more",
+        title: 'Notifications',
+        subscribedText: "You're getting this site's notifications in this browser.",
+        unsubscribedText: "Get this site's news as notifications in this browser.",
+        subscribe: 'Subscribe',
+        unsubscribe: 'Unsubscribe',
+        blockedTitle: 'Notifications are blocked',
+        blockedText: 'To get them, allow notifications for this site: open the site settings next to the address bar and set Notifications to Allow.',
+        failed: "This browser couldn't be subscribed. Try again later.",
+        close: 'Close',
+    },
+    ar: {
+        unsubscribed: 'اشترك في الإشعارات',
+        subscribed: 'أنت مشترك في الإشعارات',
+        blocked: 'الإشعارات محظورة في هذا المتصفح',
+        thanks: 'شكرًا لاشتراكك!',
+        goodbye: 'لن تصلك الإشعارات بعد الآن',
+        title: 'الإشعارات',
+        subscribedText: 'تصلك إشعارات هذا الموقع على هذا المتصفح.',
+        unsubscribedText: 'اشترك لتصلك أخبار هذا الموقع وجديده على هذا المتصفح.',
+        subscribe: 'اشتراك',
+        unsubscribe: 'إلغاء الاشتراك',
+        blockedTitle: 'الإشعارات محظورة',
+        blockedText: 'لتصلك الإشعارات، اسمح بها لهذا الموقع: افتح إعدادات الموقع بجانب شريط العنوان واختر «السماح» للإشعارات.',
+        failed: 'تعذّر الاشتراك من هذا المتصفح. حاول لاحقًا.',
+        close: 'إغلاق',
+    },
+};
+const STYLE = `
+:host { all: initial; position: fixed; z-index: 2147483000; bottom: calc(20px + env(safe-area-inset-bottom, 0px)); font-family: inherit; }
+:host([data-side="right"]) { right: calc(20px + env(safe-area-inset-right, 0px)); }
+:host([data-side="left"]) { left: calc(20px + env(safe-area-inset-left, 0px)); }
+@media (max-width: 480px) {
+  :host { bottom: calc(16px + env(safe-area-inset-bottom, 0px)); }
+  :host([data-side="right"]) { right: calc(16px + env(safe-area-inset-right, 0px)); }
+  :host([data-side="left"]) { left: calc(16px + env(safe-area-inset-left, 0px)); }
+}
+@media print { :host { display: none !important; } }
+* { box-sizing: border-box; }
+[hidden] { display: none !important; }
+.root { position: relative; font-family: inherit; }
+button { font: inherit; margin: 0; -webkit-tap-highlight-color: transparent; }
+.bell {
+  position: relative; display: grid; place-items: center; width: 48px; height: 48px; padding: 0; border: 0; border-radius: 50%;
+  background: var(--bell); color: var(--bell-text); cursor: pointer;
+  box-shadow: 0 6px 20px rgba(0, 0, 0, 0.28), 0 1px 3px rgba(0, 0, 0, 0.22);
+  transition: transform 0.15s ease, opacity 0.15s ease;
+}
+.bell:hover { transform: scale(1.06); }
+.bell:active { transform: scale(0.95); }
+.bell:focus-visible { outline: 3px solid var(--bell); outline-offset: 3px; }
+:host([data-view="blocked"]) .bell { opacity: 0.82; }
+.bell::after { content: ""; position: absolute; inset: 0; border-radius: 50%; pointer-events: none; }
+:host([data-attention][data-view="unsubscribed"]) .bell::after { animation: ring 1.6s ease-out 2; }
+@keyframes ring { from { box-shadow: 0 0 0 0 var(--ring); } to { box-shadow: 0 0 0 14px rgba(0, 0, 0, 0); } }
+.badge {
+  position: absolute; top: -3px; right: -3px; display: grid; place-items: center; width: 18px; height: 18px; border-radius: 50%;
+  background: #16a34a; color: #ffffff; border: 2px solid #ffffff;
+}
+.bubble {
+  position: absolute; bottom: 7px; width: max-content; max-width: min(260px, calc(100vw - 104px)); padding: 7px 11px; border-radius: 8px;
+  background: var(--tip); color: var(--tip-text); font-size: 13px; line-height: 1.45; text-align: start;
+  box-shadow: 0 4px 14px rgba(0, 0, 0, 0.25); opacity: 0; transform: translateY(4px); pointer-events: none;
+  transition: opacity 0.15s ease, transform 0.15s ease;
+}
+:host([data-side="right"]) .bubble { right: 60px; }
+:host([data-side="left"]) .bubble { left: 60px; }
+.bubble[data-shown] { opacity: 1; transform: none; }
+.panel {
+  position: absolute; bottom: 60px; width: min(300px, calc(100vw - 32px)); padding: 14px 16px 16px; border-radius: 14px;
+  background: var(--panel); color: var(--text); border: 1px solid var(--border); text-align: start;
+  box-shadow: 0 14px 40px rgba(0, 0, 0, 0.32); font-size: 14px; line-height: 1.55;
+}
+:host([data-side="right"]) .panel { right: 0; }
+:host([data-side="left"]) .panel { left: 0; }
+.head { display: flex; align-items: center; gap: 8px; margin-bottom: 4px; }
+.title { flex: 1; margin: 0; font-size: 15px; font-weight: 700; }
+.text { margin: 0 0 14px; color: var(--muted); }
+.error { margin: -6px 0 12px; color: var(--error); font-size: 13px; }
+.close {
+  display: grid; place-items: center; width: 30px; height: 30px; padding: 0; border: 0; border-radius: 8px; margin-inline-end: -6px;
+  background: transparent; color: inherit; opacity: 0.7; cursor: pointer;
+}
+.close:hover { opacity: 1; background: var(--hover); }
+.action {
+  width: 100%; min-height: 40px; padding: 8px 12px; border: 1px solid transparent; border-radius: 9px; font-weight: 600; cursor: pointer;
+  background: var(--bell); color: var(--bell-text);
+}
+.action[data-kind="secondary"] { background: transparent; color: inherit; border-color: var(--border); }
+.action[data-kind="secondary"]:hover { background: var(--hover); }
+.action:disabled { opacity: 0.6; cursor: progress; }
+.close:focus-visible, .action:focus-visible { outline: 2px solid var(--text); outline-offset: 2px; }
+@media (prefers-reduced-motion: reduce) {
+  .bell, .bubble { transition: none; }
+  .bell:hover, .bell:active { transform: none; }
+  :host([data-attention][data-view="unsubscribed"]) .bell::after { animation: none; }
+}
+`;
+/** Draws the bell into the page; `destroy()` takes it away again. */
+export function mountBell(api, settings, language) {
+    const lang = uiLanguage(language);
+    const t = TEXTS[lang];
+    const host = document.createElement('phoenix-notifications-bell');
+    host.dataset.side = settings.position === 'bottom_left' ? 'left' : 'right';
+    host.dataset.view = 'unsubscribed';
+    applyColors(host, colorOr(settings.color));
+    const shadow = host.attachShadow({ mode: 'open' });
+    // only constants go into this markup (the texts and icons above, lang 'ar' or 'en'); the colour is set as a property
+    shadow.innerHTML = `<style>${STYLE}</style>
+<div class="root" dir="${lang === 'ar' ? 'rtl' : 'ltr'}" lang="${lang}">
+  <div class="panel" role="dialog" aria-labelledby="phx-bell-title" hidden>
+    <div class="head"><p class="title" id="phx-bell-title"></p><button type="button" class="close" aria-label="${t.close}">${svg(ICONS.close, 18, 2)}</button></div>
+    <p class="text"></p>
+    <p class="error" role="alert" hidden></p>
+    <button type="button" class="action"></button>
+  </div>
+  <div class="bubble" role="status" aria-live="polite"></div>
+  <button type="button" class="bell" aria-haspopup="dialog" aria-expanded="false"><span class="icon"></span><span class="badge" hidden>${svg(ICONS.check, 11, 3)}</span></button>
+</div>`;
+    const $ = (selector) => shadow.querySelector(selector);
+    const bell = $('.bell');
+    const icon = $('.icon');
+    const badge = $('.badge');
+    const bubble = $('.bubble');
+    const panel = $('.panel');
+    const title = $('.title');
+    const text = $('.text');
+    const errorLine = $('.error');
+    const action = $('.action');
+    const close = $('.close');
+    let view = 'unsubscribed';
+    let open = false;
+    let busy = false;
+    let failed = false;
+    let message = null;
+    let bubbleTimer = 0;
+    let iconFor = null;
+    /** Hidden until the first read of the state, so it never shows a wrong state (or shows at all, when it hides) first. */
+    let settled = false;
+    const viewOf = (state) => (state.permission === 'denied' ? 'blocked' : state.subscribed ? 'subscribed' : 'unsubscribed');
+    function render() {
+        host.dataset.view = view;
+        const hidden = !settled || (!!settings.hideWhenSubscribed && view === 'subscribed' && !open && !busy && !message);
+        host.style.display = hidden ? 'none' : '';
+        bell.setAttribute('aria-label', t[view]);
+        bell.setAttribute('aria-expanded', String(open));
+        if (iconFor !== view) {
+            icon.innerHTML = svg(view === 'blocked' ? ICONS.bellOff : ICONS.bell, 24);
+            iconFor = view;
+        }
+        badge.hidden = view !== 'subscribed';
+        panel.hidden = !open;
+        if (!open)
+            return;
+        title.textContent = view === 'blocked' ? t.blockedTitle : t.title;
+        text.textContent = view === 'blocked' ? t.blockedText : view === 'subscribed' ? t.subscribedText : t.unsubscribedText;
+        errorLine.hidden = !failed;
+        errorLine.textContent = t.failed;
+        action.hidden = view === 'blocked';
+        action.textContent = view === 'subscribed' ? t.unsubscribe : t.subscribe;
+        action.dataset.kind = view === 'subscribed' ? 'secondary' : 'primary';
+        action.disabled = busy;
+    }
+    function showBubble(content, ms) {
+        window.clearTimeout(bubbleTimer);
+        applyTheme(host);
+        bubble.textContent = content;
+        bubble.dataset.shown = '';
+        if (ms)
+            bubbleTimer = window.setTimeout(hideBubble, ms);
+    }
+    function hideBubble() {
+        window.clearTimeout(bubbleTimer);
+        const told = message !== null;
+        message = null;
+        delete bubble.dataset.shown;
+        // the thanks are over: a bell that hides once subscribed goes now
+        if (told)
+            render();
+    }
+    /** Something happened (subscribed, unsubscribed): said in the bubble for a few seconds. */
+    function tell(content) {
+        message = content;
+        showBubble(content, MESSAGE_MS);
+    }
+    function setOpen(next, focus) {
+        open = next;
+        failed = next && failed;
+        if (open) {
+            hideBubble();
+            applyTheme(host);
+        }
+        render();
+        if (focus === 'panel')
+            (action.hidden ? close : action).focus();
+        else if (focus === 'bell')
+            bell.focus();
+    }
+    async function settle() {
+        try {
+            view = viewOf(await api.state());
+        }
+        catch {
+            // keep the last view
+        }
+    }
+    async function subscribe() {
+        if (busy)
+            return;
+        busy = true;
+        failed = false;
+        render();
+        try {
+            // the browser's prompt opens inside this call, while the click still counts as the person's gesture
+            const state = await api.subscribe();
+            if (state.subscribed) {
+                setOpen(false, null);
+                tell(t.thanks);
+            }
+            else if (state.permission === 'granted') {
+                failed = true;
+            }
+        }
+        catch (error) {
+            console.warn('[notifications] subscribing failed', error);
+            failed = true;
+        }
+        finally {
+            busy = false;
+            await settle();
+            if (failed && !open)
+                setOpen(true, 'panel');
+            else
+                render();
+        }
+    }
+    async function unsubscribe() {
+        if (busy)
+            return;
+        busy = true;
+        render();
+        try {
+            await api.unsubscribe();
+        }
+        catch (error) {
+            // the opt-out is kept even when the server could not be told; the browser no longer subscribes
+            console.warn('[notifications] unsubscribing failed', error);
+        }
+        finally {
+            busy = false;
+            await settle();
+            setOpen(false, 'bell');
+            tell(t.goodbye);
+        }
+    }
+    bell.addEventListener('click', () => {
+        if (busy)
+            return;
+        // first time here: the browser's own prompt is the clearest question, so ask straight away
+        if (!open && view === 'unsubscribed' && Notification.permission === 'default') {
+            hideBubble();
+            void subscribe();
+            return;
+        }
+        setOpen(!open, open ? null : 'panel');
+    });
+    action.addEventListener('click', () => void (view === 'subscribed' ? unsubscribe() : subscribe()));
+    close.addEventListener('click', () => setOpen(false, 'bell'));
+    // the bell's label as a tooltip, for a mouse or the keyboard (a tap goes straight to the click)
+    bell.addEventListener('pointerenter', (event) => {
+        if (event.pointerType === 'mouse' && !open && !message)
+            showBubble(t[view]);
+    });
+    bell.addEventListener('pointerleave', () => {
+        if (!message)
+            hideBubble();
+    });
+    bell.addEventListener('focus', () => {
+        if (bell.matches(':focus-visible') && !open && !message)
+            showBubble(t[view]);
+    });
+    bell.addEventListener('blur', () => {
+        if (!message)
+            hideBubble();
+    });
+    const onKey = (event) => {
+        if (event.key === 'Escape' && open) {
+            event.stopPropagation();
+            setOpen(false, 'bell');
+        }
+    };
+    shadow.addEventListener('keydown', onKey);
+    const onOutside = (event) => {
+        if (open && !event.composedPath().includes(host))
+            setOpen(false, null);
+    };
+    document.addEventListener('pointerdown', onOutside);
+    const stop = api.onChange((state) => {
+        view = viewOf(state);
+        if (!busy)
+            render();
+    });
+    render();
+    document.body.appendChild(host);
+    void settle().then(() => {
+        settled = true;
+        render();
+        // a gentle pulse, twice, the first time the bell offers itself on a page
+        if (view === 'unsubscribed' && Notification.permission === 'default') {
+            host.dataset.attention = '';
+            window.setTimeout(() => delete host.dataset.attention, ATTENTION_MS);
+        }
+    });
+    return {
+        destroy() {
+            stop();
+            window.clearTimeout(bubbleTimer);
+            document.removeEventListener('pointerdown', onOutside);
+            host.remove();
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,83 @@
+import { type StoredDevice } from './store.js';
+/**
+ * Phoenix Notifications web SDK: subscribes the browser to web push for an app on notifications.phnx-iq.com, binds it to
+ * the signed-in user with an identity token from the app's own backend, and hands notification clicks to the app. When the
+ * app has its subscription bell or banner switched on in HQ, it also draws them, so a site needs no button of its own.
+ *
+ * Nothing here throws for an unsupported browser or a denied permission: check `isSupported()` / `permission()`.
+ * The service worker file (phoenix-notifications-sw.js) must be served from the site, at `serviceWorkerPath`.
+ */
+export declare const DEFAULT_SERVER_URL = "https://notifications.phnx-iq.com";
+export declare const DEFAULT_SERVICE_WORKER_PATH = "/phoenix-notifications-sw.js";
+export interface InitOptions {
+    /** The app id from HQ (Notification management → the app). */
+    appId: string;
+    /** Where the notifications API is. '' means this site's own origin (development through a proxy). */
+    serverUrl?: string;
+    serviceWorkerPath?: string;
+    serviceWorkerScope?: string;
+    /** Language the device reports (picks Arabic or English text, and the bell's language); defaults to the page's, then the browser's. */
+    language?: string;
+    appVersion?: string;
+    /**
+     * The subscription bell, drawn when the app has it switched on in HQ (the app → Web push → Subscription bell). `false`
+     * never draws it, for a site with its own "Get notifications" button.
+     */
+    bell?: boolean;
+    /** The subscription banner, shown when the app has it switched on in HQ (the app → Web push → Subscription banner). `false` never shows it. */
+    banner?: boolean;
+}
+export type PushPermission = 'granted' | 'denied' | 'default' | 'unsupported';
+/** Whether this browser gets the app's notifications, for a site's own button. */
+export interface SubscriptionState {
+    permission: PushPermission;
+    /** Subscribed and registered with the server. False after `unsubscribe()`, even though the permission stays granted. */
+    subscribed: boolean;
+}
+export interface NotificationClick {
+    url?: string;
+    data: Record<string, string>;
+    messageId?: string;
+}
+export declare class NotificationsError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+export declare const Notifications: {
+    /** True when this browser can receive web push here (a secure context with service workers and the Push API). */
+    isSupported(): boolean;
+    /**
+     * Registers the service worker, and draws the subscription bell and the banner when the app has them on. When the person
+     * already allowed notifications (and did not unsubscribe here), subscribes quietly.
+     */
+    init(init: InitOptions): Promise<void>;
+    permission(): PushPermission;
+    /** Whether this browser gets the app's notifications now. */
+    getState(): Promise<SubscriptionState>;
+    /**
+     * Asks the person (call it from a click: browsers only ask on a user gesture) and subscribes when they allow. It also
+     * subscribes again after `unsubscribe()`, without asking, since the browser keeps the permission.
+     */
+    requestPermission(): Promise<PushPermission>;
+    /**
+     * Binds this browser to the user an identity token from the app's backend vouches for. Before the person allows
+     * notifications there is no device yet: the token is kept and used once they do.
+     */
+    login(identityToken: string): Promise<void>;
+    /** The browser keeps receiving the app's broadcasts as a guest, but no longer this user's notifications. */
+    logout(): Promise<void>;
+    /**
+     * Stops notifications in this browser altogether, and remembers it: later page loads do not subscribe again although the
+     * permission stays granted, until `requestPermission()` (the bell's "Subscribe").
+     */
+    unsubscribe(): Promise<void>;
+    /** A notification was clicked while the site was open. Without a handler the SDK opens its link. Returns an unsubscribe function. */
+    onClick(handler: (click: NotificationClick) => void): () => void;
+    /** Called when this browser subscribes, unsubscribes or the permission changes. Returns an unsubscribe function. */
+    onSubscriptionChange(handler: (state: SubscriptionState) => void): () => void;
+    /** Re-runs the subscription check now (e.g. after the person changed the site's permission). */
+    refresh(): Promise<void>;
+};
+export type { BannerPosition } from './banner.js';
+export type { BellPosition } from './bell.js';
+export type { StoredDevice };