@xtremax/pigeon 0.0.0-stage → 0.3.1

package/dist/esm/inbox-react/inbox-client.js

@@ -0,0 +1,58 @@
+import { parseErrorCode, parseMarkRead, parsePage, parsePreference, parseReadAll, parseSummary } from './parse.js';
+export const DEFAULT_API_BASE = '/api/communication/inbox';
+/**
+ * The browser talks only to the host xApp's own origin (14.2). The base is a path on that origin: an absolute URL,
+ * a protocol-relative one or anything with a query is refused.
+ */
+export function normalizeApiBase(apiBase) {
+    const base = (apiBase ?? DEFAULT_API_BASE).trim();
+    if (!base.startsWith('/') || base.startsWith('//') || /[\\?#\s]/.test(base) || base.includes('://'))
+        return null;
+    return base.replace(/\/+$/, '') || null;
+}
+/**
+ * Every call answers a result and never throws, so an outage cannot break the host page (14.9).
+ * The bell shows what this xApp's own sub-tenant sent the person, and the tenant's announcements: there is nothing to choose.
+ */
+export function createInboxBrowserClient(apiBase, fetchImpl) {
+    const base = normalizeApiBase(apiBase);
+    async function call(method, path, parse, body) {
+        if (base === null)
+            return { ok: false, code: 'unavailable' };
+        try {
+            const res = await (fetchImpl ?? fetch)(`${base}${path}`, {
+                method,
+                credentials: 'same-origin',
+                cache: 'no-store',
+                headers: { Accept: 'application/json', ...(body !== undefined ? { 'Content-Type': 'application/json' } : {}) },
+                body: body === undefined ? undefined : JSON.stringify(body),
+            });
+            const json = await res.json().catch(() => null);
+            if (!res.ok)
+                return { ok: false, code: parseErrorCode(res.status, json) };
+            const data = parse(json?.data);
+            return data === null ? { ok: false, code: 'unavailable' } : { ok: true, data };
+        }
+        catch {
+            return { ok: false, code: 'unavailable' };
+        }
+    }
+    return {
+        summary: () => call('GET', '/summary', parseSummary),
+        list(query = {}) {
+            const q = new URLSearchParams();
+            if (query.limit !== undefined)
+                q.set('limit', String(query.limit));
+            if (query.cursor)
+                q.set('cursor', query.cursor);
+            if (query.unreadOnly)
+                q.set('unread', 'true');
+            const qs = q.toString();
+            return call('GET', `/notifications${qs ? `?${qs}` : ''}`, parsePage);
+        },
+        markRead: (id) => call('POST', `/notifications/${encodeURIComponent(id)}/read`, parseMarkRead, {}),
+        markAllRead: (upTo) => call('POST', '/read-all', parseReadAll, upTo ? { upTo } : {}),
+        getPreference: () => call('GET', '/preference', parsePreference),
+        setPreference: (state) => call('PUT', '/preference', parsePreference, { state }),
+    };
+}

package/dist/esm/inbox-react/inbox-context.js

@@ -0,0 +1,9 @@
+'use client';
+import { createContext, useContext } from 'react';
+export const InboxContext = createContext(null);
+export function useInbox() {
+    const value = useContext(InboxContext);
+    if (!value)
+        throw new Error('Wrap the inbox components in <InboxProvider>.');
+    return value;
+}

package/dist/esm/inbox-react/inbox-full-list.js

@@ -0,0 +1,10 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { InboxListView } from './inbox-list.js';
+/**
+ * Every notification, a page at a time. The provider shows it in a dialog for "View all"; a host that passes
+ * `onViewAll` can place it on a page of its own instead.
+ */
+export function InboxFullList({ maxHeight = 'min(70vh, 640px)' }) {
+    return _jsx(InboxListView, { paged: true, maxHeight: maxHeight });
+}

package/dist/esm/inbox-react/inbox-list.js

@@ -0,0 +1,34 @@
+'use client';
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useState } from 'react';
+import { Alert, Button, Center, Group, Loader, ScrollArea, Stack, Tabs, Text } from '@mantine/core';
+import { fill } from './format.js';
+import { useInbox } from './inbox-context.js';
+import { canMarkAll } from './inbox-state.js';
+import { NotificationItem } from './notification-item.js';
+/** Tabs, "Mark all as read", the list and its loading, empty and error states. Shared by the panel and the full list. */
+export function InboxListView({ heading, maxHeight, paged = false }) {
+    const { state, labels, setTab, markAllRead, loadMore, retry, clearMessage, attachList } = useInbox();
+    useEffect(() => attachList(), [attachList]);
+    // Relative times move on while the list stays open.
+    const [now, setNow] = useState(() => new Date());
+    useEffect(() => {
+        const timer = window.setInterval(() => setNow(new Date()), 60_000);
+        return () => window.clearInterval(timer);
+    }, []);
+    let content;
+    if (!state.loaded && state.status === 'error') {
+        content = (_jsx(Alert, { color: "red", variant: "light", m: "md", title: labels.loadError, children: _jsx(Button, { variant: "default", size: "sm", mih: 44, onClick: retry, children: labels.retry }) }));
+    }
+    else if (!state.loaded) {
+        content = (_jsx(Center, { mih: 160, role: "status", "aria-label": labels.loading, children: _jsx(Loader, { size: "sm" }) }));
+    }
+    else if (state.items.length === 0) {
+        content = (_jsx(Text, { c: "dimmed", size: "sm", ta: "center", px: "md", py: "xl", children: state.tab === 'unread' ? labels.emptyUnread : labels.emptyAll }));
+    }
+    else {
+        content = (_jsxs(_Fragment, { children: [_jsx("ul", { className: "xci-list", children: state.items.map((item) => (_jsx("li", { className: "xci-entry", children: _jsx(NotificationItem, { item: item, now: now }) }, item.id))) }), paged && state.nextCursor && (_jsx(Center, { p: "sm", children: _jsx(Button, { variant: "default", size: "sm", mih: 44, loading: state.loadingMore, onClick: loadMore, children: labels.loadMore }) }))] }));
+    }
+    const list = (_jsx(ScrollArea.Autosize, { mah: maxHeight, type: "auto", children: content }));
+    return (_jsxs(Stack, { gap: 0, children: [_jsxs(Group, { justify: "space-between", wrap: "nowrap", gap: "xs", ps: "md", pe: 4, pt: 4, children: [heading ?? _jsx("span", {}), _jsx(Button, { variant: "subtle", size: "compact-sm", mih: 44, px: "sm", disabled: !canMarkAll(state), onClick: markAllRead, children: labels.markAllRead })] }), _jsxs(Tabs, { value: state.tab, onChange: (tab) => tab && setTab(tab), keepMounted: false, children: [_jsxs(Tabs.List, { px: "xs", children: [_jsx(Tabs.Tab, { value: "all", mih: 44, children: labels.tabAll }), _jsx(Tabs.Tab, { value: "unread", mih: 44, children: state.unreadCount > 0 ? fill(labels.tabUnreadWithCount, { n: state.unreadCount }) : labels.tabUnread })] }), state.actionFailed && (_jsx(Alert, { color: "red", variant: "light", m: "xs", role: "alert", withCloseButton: true, closeButtonLabel: labels.dismiss, onClose: clearMessage, children: labels.actionError })), _jsx(Tabs.Panel, { value: "all", children: list }), _jsx(Tabs.Panel, { value: "unread", children: list })] })] }));
+}

package/dist/esm/inbox-react/inbox-panel.js

@@ -0,0 +1,10 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Button, Divider, Group, Title } from '@mantine/core';
+import { useInbox } from './inbox-context.js';
+import { InboxListView } from './inbox-list.js';
+/** What the bell opens: the newest notifications, with the ways on to the full list and the preference. */
+export function InboxPanel() {
+    const { labels, viewAll, openPreferences } = useInbox();
+    return (_jsxs(_Fragment, { children: [_jsx(InboxListView, { maxHeight: 400, heading: _jsx(Title, { order: 2, size: "h5", children: labels.heading }) }), _jsx(Divider, {}), _jsxs(Group, { justify: "space-between", gap: 4, p: 4, children: [_jsx(Button, { variant: "subtle", size: "compact-sm", mih: 44, px: "sm", onClick: viewAll, children: labels.viewAll }), _jsx(Button, { variant: "subtle", size: "compact-sm", mih: 44, px: "sm", onClick: openPreferences, children: labels.preferences })] })] }));
+}

package/dist/esm/inbox-react/inbox-provider.js

@@ -0,0 +1,154 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useMemo, useReducer, useRef, useState } from 'react';
+import { Modal } from '@mantine/core';
+import { useReducedMotion } from '@mantine/hooks';
+import { safeLink } from './format.js';
+import { createInboxBrowserClient } from './inbox-client.js';
+import { InboxContext } from './inbox-context.js';
+import { InboxFullList } from './inbox-full-list.js';
+import { canMarkAll, initialInboxState, inboxReducer } from './inbox-state.js';
+import { mergeLabels } from './labels.js';
+import { PreferenceDialog } from './preference-dialog.js';
+import { useInboxPolling } from './use-inbox-polling.js';
+const openInNewTab = (url) => {
+    window.open(url, '_blank', 'noopener,noreferrer');
+};
+/** "Mark all as read" changes at most one batch per call; repeat while something remains, within a bound. */
+const READ_ALL_MAX_CALLS = 10;
+const nowIso = () => new Date().toISOString();
+export function InboxProvider({ apiBase, labels, locale, onViewAll, onOpenPreferences, openLink, children }) {
+    const client = useMemo(() => createInboxBrowserClient(apiBase), [apiBase]);
+    const merged = useMemo(() => mergeLabels(labels), [labels]);
+    const [state, dispatch] = useReducer(inboxReducer, initialInboxState);
+    const [panelOpened, setPanelOpened] = useState(false);
+    const [fullOpened, setFullOpened] = useState(false);
+    const [preferencesOpened, setPreferencesOpened] = useState(false);
+    const reduceMotion = useReducedMotion();
+    const bellRef = useRef(null);
+    const latest = useRef(state);
+    useEffect(() => {
+        latest.current = state;
+    }, [state]);
+    // The tab is also kept here: a list that mounts in the same render as a tab change must load the new tab.
+    const tabRef = useRef('all');
+    const lists = useRef(0);
+    const request = useRef(0);
+    const load = useCallback(async (mode, tab, cursor) => {
+        const mine = (request.current += 1);
+        dispatch({ type: 'loadStarted', mode });
+        const res = await client.list({ unreadOnly: tab === 'unread', cursor });
+        // An answer for a tab or a list the person has already left is dropped.
+        if (mine !== request.current)
+            return;
+        if (res.ok)
+            dispatch({ type: 'pageReceived', page: res.data, mode, at: nowIso() });
+        else
+            dispatch({ type: 'loadFailed', mode });
+    }, [client]);
+    const poll = useCallback(async () => {
+        const res = await client.summary();
+        if (!res.ok)
+            return res.code === 'not_signed_in' ? { result: 'stop' } : { result: 'failed' };
+        const before = latest.current;
+        dispatch({ type: 'summaryReceived', summary: res.data, at: nowIso() });
+        const changed = res.data.unreadCount !== before.unreadCount || res.data.newestUnreadAt !== before.newestUnreadAt;
+        // A list on screen follows the change (13.3). One that is mid-action is left alone.
+        if (changed && lists.current > 0 && before.loaded && before.status === 'idle' && !before.markAll && Object.keys(before.pending).length === 0)
+            void load('merge', before.tab);
+        return { result: 'ok', pollSeconds: res.data.pollSeconds };
+    }, [client, load]);
+    useInboxPolling(poll);
+    const attachList = useCallback(() => {
+        lists.current += 1;
+        const shown = latest.current;
+        void load(shown.loaded && shown.tab === tabRef.current ? 'merge' : 'replace', tabRef.current);
+        return () => {
+            lists.current -= 1;
+        };
+    }, [load]);
+    const setTab = useCallback((tab) => {
+        if (tab === tabRef.current)
+            return;
+        tabRef.current = tab;
+        dispatch({ type: 'tabChanged', tab });
+        void load('replace', tab);
+    }, [load]);
+    const select = useCallback((item) => {
+        const link = safeLink(item.link);
+        if (link)
+            (openLink ?? openInNewTab)(link);
+        if (item.read || latest.current.pending[item.id])
+            return;
+        dispatch({ type: 'markReadOptimistic', id: item.id, at: nowIso() });
+        void client.markRead(item.id).then((res) => {
+            if (res.ok)
+                dispatch({ type: 'markReadConfirmed', id: item.id, notification: res.data.notification, unreadCount: res.data.unreadCount });
+            else
+                dispatch({ type: 'markReadFailed', id: item.id });
+        });
+    }, [client, openLink]);
+    const markAllRead = useCallback(() => {
+        const before = latest.current;
+        if (!canMarkAll(before))
+            return;
+        // Only what the person could have seen: notifications that arrive later stay unread.
+        const upTo = before.newestUnreadAt ?? before.items[0]?.createdAt ?? null;
+        dispatch({ type: 'markAllOptimistic', at: nowIso() });
+        void (async () => {
+            let unreadCount = 0;
+            for (let i = 0; i < READ_ALL_MAX_CALLS; i += 1) {
+                const res = await client.markAllRead(upTo);
+                if (!res.ok) {
+                    dispatch({ type: 'markAllFailed' });
+                    return;
+                }
+                unreadCount = res.data.unreadCount;
+                if (res.data.remaining === 0)
+                    break;
+            }
+            dispatch({ type: 'markAllConfirmed', unreadCount });
+        })();
+    }, [client]);
+    const loadMore = useCallback(() => {
+        const s = latest.current;
+        if (s.nextCursor && !s.loadingMore)
+            void load('append', s.tab, s.nextCursor);
+    }, [load]);
+    const retry = useCallback(() => void load('replace', latest.current.tab), [load]);
+    const clearMessage = useCallback(() => dispatch({ type: 'messageCleared' }), []);
+    const openPanel = useCallback(() => setPanelOpened(true), []);
+    const closePanel = useCallback(() => setPanelOpened(false), []);
+    const viewAll = useCallback(() => {
+        setPanelOpened(false);
+        // "View all" means all: it never opens on the Unread tab the panel was showing.
+        if (tabRef.current !== 'all') {
+            tabRef.current = 'all';
+            dispatch({ type: 'tabChanged', tab: 'all' });
+        }
+        if (onViewAll)
+            onViewAll();
+        else
+            setFullOpened(true);
+    }, [onViewAll]);
+    const openPreferences = useCallback(() => {
+        setPanelOpened(false);
+        if (onOpenPreferences)
+            onOpenPreferences();
+        else
+            setPreferencesOpened(true);
+    }, [onOpenPreferences]);
+    // The control that opened a dialog is gone with the panel, so focus goes back to the bell (15.2).
+    const focusBell = useCallback(() => {
+        window.setTimeout(() => bellRef.current?.focus(), 0);
+    }, []);
+    const value = useMemo(() => ({ state, labels: merged, locale, client, panelOpened, bellRef, openPanel, closePanel, setTab, select, markAllRead, loadMore, viewAll, openPreferences, retry, clearMessage, attachList }), [state, merged, locale, client, panelOpened, openPanel, closePanel, setTab, select, markAllRead, loadMore, viewAll, openPreferences, retry, clearMessage, attachList]);
+    const transition = reduceMotion ? { duration: 0 } : undefined;
+    return (_jsxs(InboxContext.Provider, { value: value, children: [children, _jsx(Modal, { opened: fullOpened, onClose: () => {
+                    setFullOpened(false);
+                    focusBell();
+                }, title: merged.fullListTitle, closeButtonProps: { 'aria-label': merged.close }, size: "lg", returnFocus: false, transitionProps: transition, styles: { body: { padding: 0 } }, children: fullOpened && _jsx(InboxFullList, {}) }), _jsx(PreferenceDialog, { opened: preferencesOpened, onClose: () => {
+                    setPreferencesOpened(false);
+                    focusBell();
+                } })] }));
+}

package/dist/esm/inbox-react/inbox-state.js

@@ -0,0 +1,83 @@
+export const initialInboxState = {
+    unreadCount: 0, newestUnreadAt: null, items: [], nextCursor: null, tab: 'all', status: 'idle', loaded: false, loadingMore: false, lastSyncedAt: null, pending: {}, markAll: null, actionFailed: false,
+};
+const busy = (s) => s.markAll !== null || Object.keys(s.pending).length > 0;
+const asRead = (n, at) => (n.read ? n : { ...n, read: true, readAt: at });
+/** Newest first by (createdAt, id): true when `a` comes after `b` in the list. */
+const olderThan = (a, b) => a.createdAt < b.createdAt || (a.createdAt === b.createdAt && a.id < b.id);
+function mergePage(s, page, mode) {
+    if (mode === 'append') {
+        const seen = new Set(s.items.map((n) => n.id));
+        return { items: [...s.items, ...page.notifications.filter((n) => !seen.has(n.id))], nextCursor: page.nextCursor };
+    }
+    const last = page.notifications.at(-1);
+    if (mode === 'replace' || !last || page.nextCursor === null)
+        return { items: page.notifications, nextCursor: page.nextCursor };
+    // merge: the page is the newest part; keep what was already shown below it.
+    const fresh = new Set(page.notifications.map((n) => n.id));
+    const kept = s.items.filter((n) => !fresh.has(n.id) && olderThan(n, last));
+    return kept.length > 0 ? { items: [...page.notifications, ...kept], nextCursor: s.nextCursor } : { items: page.notifications, nextCursor: page.nextCursor };
+}
+export function inboxReducer(s, a) {
+    switch (a.type) {
+        case 'summaryReceived':
+            // While an optimistic change waits for its answer, the count on screen is the newer truth.
+            return busy(s) ? { ...s, lastSyncedAt: a.at } : { ...s, unreadCount: a.summary.unreadCount, newestUnreadAt: a.summary.newestUnreadAt, lastSyncedAt: a.at };
+        case 'loadStarted':
+            if (a.mode === 'append')
+                return { ...s, loadingMore: true };
+            return { ...s, loadingMore: false, status: s.loaded ? 'refreshing' : 'loading' };
+        case 'pageReceived': {
+            const merged = mergePage(s, a.page, a.mode);
+            // An item whose "mark read" is still in flight stays read, whatever this page says.
+            const stillUnread = merged.items.filter((n) => !n.read && (s.pending[n.id] || s.markAll)).length;
+            const items = merged.items.map((n) => (s.pending[n.id] || s.markAll ? asRead(n, a.at) : n));
+            return {
+                ...s, items, nextCursor: merged.nextCursor, loaded: true, loadingMore: false, status: 'idle', lastSyncedAt: a.at,
+                unreadCount: s.markAll ? s.unreadCount : Math.max(0, a.page.unreadCount - stillUnread),
+            };
+        }
+        case 'loadFailed':
+            if (a.mode === 'append')
+                return { ...s, loadingMore: false, actionFailed: true };
+            return { ...s, loadingMore: false, status: s.loaded ? 'idle' : 'error' };
+        case 'tabChanged':
+            return a.tab === s.tab ? s : { ...s, tab: a.tab, items: [], nextCursor: null, loaded: false, loadingMore: false, status: 'loading' };
+        case 'markReadOptimistic': {
+            const item = s.items.find((n) => n.id === a.id);
+            if (!item || item.read || s.pending[a.id])
+                return s;
+            return { ...s, items: s.items.map((n) => (n.id === a.id ? asRead(n, a.at) : n)), unreadCount: Math.max(0, s.unreadCount - 1), pending: { ...s.pending, [a.id]: item } };
+        }
+        case 'markReadConfirmed': {
+            if (!s.pending[a.id])
+                return s;
+            const { [a.id]: _done, ...pending } = s.pending;
+            void _done;
+            const settled = Object.keys(pending).length === 0 && !s.markAll;
+            return { ...s, pending, items: s.items.map((n) => (n.id === a.id ? a.notification : n)), unreadCount: settled ? a.unreadCount : s.unreadCount };
+        }
+        case 'markReadFailed': {
+            const previous = s.pending[a.id];
+            if (!previous)
+                return s;
+            const { [a.id]: _undone, ...pending } = s.pending;
+            void _undone;
+            return { ...s, pending, items: s.items.map((n) => (n.id === a.id ? previous : n)), unreadCount: s.unreadCount + 1, actionFailed: true };
+        }
+        case 'markAllOptimistic':
+            if (!canMarkAll(s))
+                return s;
+            return { ...s, markAll: { items: s.items, unreadCount: s.unreadCount }, items: s.items.map((n) => asRead(n, a.at)), unreadCount: 0 };
+        case 'markAllConfirmed':
+            return s.markAll ? { ...s, markAll: null, unreadCount: a.unreadCount } : s;
+        case 'markAllFailed':
+            return s.markAll ? { ...s, markAll: null, items: s.markAll.items, unreadCount: s.markAll.unreadCount, actionFailed: true } : s;
+        case 'messageCleared':
+            return s.actionFailed ? { ...s, actionFailed: false } : s;
+    }
+}
+/** "Mark all as read" is offered only when something is unread and no such request is running (12.8). */
+export function canMarkAll(s) {
+    return s.unreadCount > 0 && s.markAll === null;
+}

package/dist/esm/inbox-react/index.js

@@ -0,0 +1,18 @@
+/**
+ * The in-app inbox for an app: a bell with an unread badge, a panel, a full list and the person's preference.
+ * The bell shows what this app sent the person, and the tenant's announcements.
+ *
+ *   import { InboxProvider, NotificationBell } from '@xtremax/pigeon/inbox-react';
+ *   import '@xtremax/pigeon/inbox-react/styles.css';
+ *
+ *   <InboxProvider>
+ *     <NotificationBell />
+ *   </InboxProvider>
+ *
+ * The components call the host app's own routes (default `/api/communication/inbox`), which
+ * `createInboxHandler` from `@xtremax/pigeon/inbox` serves. They need React 19, Mantine 8 and Tabler icons. Nothing here holds a key or talks to another origin.
+ */
+export { InboxProvider } from './inbox-provider.js';
+export { NotificationBell } from './notification-bell.js';
+export { InboxFullList } from './inbox-full-list.js';
+export { DEFAULT_INBOX_LABELS } from './labels.js';

package/dist/esm/inbox-react/labels.js

@@ -0,0 +1,34 @@
+export const DEFAULT_INBOX_LABELS = {
+    bell: 'Notifications',
+    bellWithCount: '{label}, {n} unread',
+    heading: 'Notifications',
+    tabAll: 'All',
+    tabUnread: 'Unread',
+    tabUnreadWithCount: 'Unread ({n})',
+    markAllRead: 'Mark all as read',
+    viewAll: 'View all',
+    preferences: 'Notification preferences',
+    emptyAll: 'You have no notifications.',
+    emptyUnread: 'You have no unread notifications.',
+    loading: 'Loading notifications',
+    loadError: 'Notifications could not be loaded.',
+    retry: 'Try again',
+    actionError: 'That did not work. Try again.',
+    dismiss: 'Dismiss',
+    close: 'Close',
+    unread: 'Unread',
+    announcement: 'Announcement',
+    loadMore: 'Show older notifications',
+    newOne: '1 new notification',
+    newMany: '{n} new notifications',
+    fullListTitle: 'All notifications',
+    preferencesTitle: 'Notification preferences',
+    preferenceToggle: 'Receive in-app notifications',
+    preferenceOn: 'New notifications from this app appear here.',
+    preferenceOff: 'New notifications from this app do not appear here. The ones you already have stay. Other apps are not affected.',
+    preferenceLoadError: 'Your preference could not be loaded.',
+    preferenceSaveError: 'Your choice was not saved. Try again.',
+};
+export function mergeLabels(labels) {
+    return { ...DEFAULT_INBOX_LABELS, ...(labels ?? {}) };
+}

package/dist/esm/inbox-react/notification-bell.js

@@ -0,0 +1,29 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from 'react';
+import { ActionIcon, Indicator, Popover, VisuallyHidden } from '@mantine/core';
+import { useReducedMotion } from '@mantine/hooks';
+import { IconBell } from '@tabler/icons-react';
+import { badgeText, bellName, fill } from './format.js';
+import { useInbox } from './inbox-context.js';
+import { InboxPanel } from './inbox-panel.js';
+/** The bell with its unread badge. Opens the inbox panel. Place it inside `InboxProvider`. */
+export function NotificationBell({ size = 44 }) {
+    const { state, labels, panelOpened, openPanel, closePanel, bellRef } = useInbox();
+    const reduceMotion = useReducedMotion();
+    const badge = badgeText(state.unreadCount);
+    // A rise of the count while the panel is closed is announced, without moving focus (15.4). The first count is not news.
+    const [announcement, setAnnouncement] = useState('');
+    const known = useRef(null);
+    useEffect(() => {
+        if (state.lastSyncedAt === null)
+            return;
+        const before = known.current;
+        known.current = state.unreadCount;
+        if (before === null || state.unreadCount <= before || panelOpened)
+            return;
+        const rise = state.unreadCount - before;
+        setAnnouncement(rise === 1 ? labels.newOne : fill(labels.newMany, { n: rise }));
+    }, [state.unreadCount, state.lastSyncedAt, panelOpened, labels]);
+    return (_jsxs(_Fragment, { children: [_jsx(Indicator, { inline: true, label: badge, disabled: !badge, size: 18, offset: 8, children: _jsxs(Popover, { opened: panelOpened, onChange: (opened) => (opened ? openPanel() : closePanel()), position: "bottom-end", shadow: "md", trapFocus: true, returnFocus: true, closeOnEscape: true, withinPortal: true, transitionProps: reduceMotion ? { duration: 0 } : undefined, children: [_jsx(Popover.Target, { children: _jsx(ActionIcon, { ref: bellRef, variant: "subtle", color: "gray", radius: "xl", size: Math.max(44, size), "aria-label": bellName(labels, state.unreadCount), onClick: () => (panelOpened ? closePanel() : openPanel()), children: _jsx(IconBell, { size: 22, stroke: 1.75, "aria-hidden": "true" }) }) }), _jsx(Popover.Dropdown, { p: 0, style: { width: 'min(380px, calc(100vw - 16px))' }, children: _jsx(InboxPanel, {}) })] }) }), _jsx(VisuallyHidden, { role: "status", "aria-live": "polite", children: announcement })] }));
+}

package/dist/esm/inbox-react/notification-item.js

@@ -0,0 +1,14 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Badge, Text, UnstyledButton, VisuallyHidden } from '@mantine/core';
+import { exactTime, relativeTime } from './format.js';
+import { useInbox } from './inbox-context.js';
+/**
+ * One notification. The whole row is one button: selecting it marks the notification read and opens its link when
+ * it has a safe one. Title and body are text nodes, never markup (12.14).
+ */
+export function NotificationItem({ item, now }) {
+    const { labels, locale, select } = useInbox();
+    const unread = !item.read;
+    return (_jsxs(UnstyledButton, { className: "xci-row", onClick: () => select(item), "data-unread": unread || undefined, children: [_jsx("span", { className: "xci-dot", "data-unread": unread || undefined, "aria-hidden": "true" }), _jsxs("span", { className: "xci-content", children: [unread && _jsxs(VisuallyHidden, { children: [labels.unread, "."] }), _jsxs("span", { className: "xci-meta", children: [_jsx(Text, { component: "span", size: "xs", c: "dimmed", truncate: true, children: item.source.name }), item.kind === 'announcement' && (_jsx(Badge, { component: "span", size: "xs", variant: "light", style: { flex: 'none' }, children: labels.announcement }))] }), _jsx(Text, { component: "span", className: "xci-line", size: "sm", fw: unread ? 700 : 400, lineClamp: 2, children: item.title }), _jsx(Text, { component: "span", className: "xci-line", size: "sm", c: "dimmed", lineClamp: 3, children: item.body }), _jsx(Text, { component: "time", className: "xci-line", size: "xs", c: "dimmed", dateTime: item.createdAt, title: exactTime(item.createdAt, locale), children: relativeTime(item.createdAt, now, locale) })] })] }));
+}

package/dist/esm/inbox-react/parse.js

@@ -0,0 +1,85 @@
+import { INBOX_ERROR_CODES } from './types.js';
+/**
+ * Tolerant parsing (17.4): each parser takes only the fields it knows and ignores the rest at any depth, so a field
+ * added later changes nothing here. A value that lacks a known field gives `null`, never a half-filled object.
+ */
+const obj = (v) => (typeof v === 'object' && v !== null && !Array.isArray(v) ? v : null);
+const str = (v) => (typeof v === 'string' ? v : null);
+const strOrNull = (v) => (v === null ? null : typeof v === 'string' ? v : undefined);
+const count = (v) => (typeof v === 'number' && Number.isInteger(v) && v >= 0 ? v : null);
+export function parseNotification(v) {
+    const o = obj(v);
+    const source = obj(o?.source);
+    if (!o || !source)
+        return null;
+    const id = str(o.id);
+    const title = str(o.title);
+    const body = str(o.body);
+    const createdAt = str(o.createdAt);
+    const link = strOrNull(o.link);
+    const readAt = strOrNull(o.readAt);
+    const name = str(source.name);
+    if (id === null || title === null || body === null || createdAt === null || link === undefined || readAt === undefined || name === null)
+        return null;
+    if (o.kind !== 'notification' && o.kind !== 'announcement')
+        return null;
+    if (source.type !== 'xapp' && source.type !== 'tenant')
+        return null;
+    if (typeof o.read !== 'boolean')
+        return null;
+    return { id, kind: o.kind, title, body, link, source: { type: source.type, name }, createdAt, read: o.read, readAt };
+}
+export function parseSummary(v) {
+    const o = obj(v);
+    if (!o)
+        return null;
+    const unreadCount = count(o.unreadCount);
+    const newestUnreadAt = strOrNull(o.newestUnreadAt);
+    const pollSeconds = count(o.pollSeconds);
+    return unreadCount === null || newestUnreadAt === undefined || pollSeconds === null ? null : { unreadCount, newestUnreadAt, pollSeconds };
+}
+export function parsePage(v) {
+    const o = obj(v);
+    if (!o || !Array.isArray(o.notifications))
+        return null;
+    const notifications = [];
+    for (const raw of o.notifications) {
+        const n = parseNotification(raw);
+        if (!n)
+            return null;
+        notifications.push(n);
+    }
+    const nextCursor = strOrNull(o.nextCursor);
+    const unreadCount = count(o.unreadCount);
+    return nextCursor === undefined || unreadCount === null ? null : { notifications, nextCursor, unreadCount };
+}
+export function parseMarkRead(v) {
+    const o = obj(v);
+    const notification = parseNotification(o?.notification);
+    const unreadCount = count(o?.unreadCount);
+    return notification && unreadCount !== null ? { notification, unreadCount } : null;
+}
+export function parseReadAll(v) {
+    const o = obj(v);
+    const marked = count(o?.marked);
+    const remaining = count(o?.remaining);
+    const unreadCount = count(o?.unreadCount);
+    return marked === null || remaining === null || unreadCount === null ? null : { marked, remaining, unreadCount };
+}
+export function parsePreference(v) {
+    const o = obj(v);
+    if (!o)
+        return null;
+    const changedAt = strOrNull(o.changedAt);
+    if (o.state !== 'opted_in' && o.state !== 'opted_out' && o.state !== 'not_set')
+        return null;
+    return changedAt === undefined || typeof o.delivers !== 'boolean' ? null : { state: o.state, changedAt, delivers: o.delivers };
+}
+/** The code of an error body, or the nearest one for the status. Anything unknown is `unavailable`. */
+export function parseErrorCode(status, body) {
+    const code = obj(obj(body)?.error)?.code;
+    if (typeof code === 'string' && INBOX_ERROR_CODES.includes(code))
+        return code;
+    const byStatus = { 401: 'not_signed_in', 403: 'not_permitted', 404: 'not_found', 422: 'invalid_input', 429: 'rate_limited' };
+    return byStatus[status] ?? 'unavailable';
+}

package/dist/esm/inbox-react/preference-dialog.js

@@ -0,0 +1,46 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useState } from 'react';
+import { Alert, Button, Center, Loader, Modal, Stack, Switch } from '@mantine/core';
+import { useReducedMotion } from '@mantine/hooks';
+import { useInbox } from './inbox-context.js';
+/** The person's own choice for this app's in-app notifications. Other apps are not affected. */
+export function PreferenceDialog({ opened, onClose }) {
+    const { client, labels } = useInbox();
+    const reduceMotion = useReducedMotion();
+    const [preference, setPreference] = useState(null);
+    const [status, setStatus] = useState('loading');
+    const [saving, setSaving] = useState(false);
+    const [saveFailed, setSaveFailed] = useState(false);
+    const load = useCallback(async () => {
+        setStatus('loading');
+        const res = await client.getPreference();
+        if (res.ok)
+            setPreference(res.data);
+        setStatus(res.ok ? 'ready' : 'error');
+    }, [client]);
+    useEffect(() => {
+        if (!opened)
+            return;
+        setSaveFailed(false);
+        void load();
+    }, [opened, load]);
+    // The switch moves at once; a failure moves it back and says so.
+    const change = async (on) => {
+        if (!preference || saving)
+            return;
+        const before = preference;
+        setSaveFailed(false);
+        setSaving(true);
+        setPreference({ ...preference, state: on ? 'opted_in' : 'opted_out', delivers: on });
+        const res = await client.setPreference(on ? 'opted_in' : 'opted_out');
+        setSaving(false);
+        if (res.ok)
+            setPreference(res.data);
+        else {
+            setPreference(before);
+            setSaveFailed(true);
+        }
+    };
+    return (_jsxs(Modal, { opened: opened, onClose: onClose, title: labels.preferencesTitle, closeButtonProps: { 'aria-label': labels.close }, returnFocus: false, transitionProps: reduceMotion ? { duration: 0 } : undefined, children: [status === 'loading' && (_jsx(Center, { mih: 96, role: "status", "aria-label": labels.loading, children: _jsx(Loader, { size: "sm" }) })), status === 'error' && (_jsx(Alert, { color: "red", variant: "light", title: labels.preferenceLoadError, children: _jsx(Button, { variant: "default", size: "sm", mih: 44, onClick: () => void load(), children: labels.retry }) })), status === 'ready' && preference && (_jsxs(Stack, { gap: "sm", children: [_jsx(Switch, { label: labels.preferenceToggle, description: preference.delivers ? labels.preferenceOn : labels.preferenceOff, checked: preference.state === 'not_set' ? preference.delivers : preference.state === 'opted_in', onChange: (event) => void change(event.currentTarget.checked) }), saveFailed && (_jsx(Alert, { color: "red", variant: "light", role: "alert", children: labels.preferenceSaveError }))] }))] }));
+}

package/dist/esm/inbox-react/types.js

@@ -0,0 +1 @@
+export const INBOX_ERROR_CODES = ['not_signed_in', 'not_permitted', 'not_found', 'invalid_input', 'rate_limited', 'unavailable'];