@xtremax/pigeon 0.0.0-stage → 0.3.0

package/dist/cjs/inbox/project.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.projectNotification = projectNotification;
+exports.projectSummary = projectSummary;
+exports.projectPage = projectPage;
+exports.projectMarkRead = projectMarkRead;
+exports.projectReadAll = projectReadAll;
+exports.projectPreference = projectPreference;
+/**
+ * Allowlist projection: only the documented fields of IB-2 leave the host, so nothing the Gateway adds later reaches a
+ * browser by accident. A value of the wrong shape gives `null`, which the handler answers as `unavailable`.
+ */
+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);
+function projectNotification(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 };
+}
+function projectSummary(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 };
+}
+function projectPage(v) {
+    const o = obj(v);
+    if (!o || !Array.isArray(o.notifications))
+        return null;
+    const notifications = [];
+    for (const raw of o.notifications) {
+        const n = projectNotification(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 };
+}
+function projectMarkRead(v) {
+    const o = obj(v);
+    const notification = projectNotification(o?.notification);
+    const unreadCount = count(o?.unreadCount);
+    return notification && unreadCount !== null ? { notification, unreadCount } : null;
+}
+function projectReadAll(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 };
+}
+function projectPreference(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 };
+}

package/dist/cjs/inbox/validate.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INBOX_LIMITS = void 0;
+exports.parseLimit = parseLimit;
+exports.parseCursor = parseCursor;
+exports.parseUnread = parseUnread;
+exports.parseId = parseId;
+exports.parseUpTo = parseUpTo;
+exports.parseState = parseState;
+exports.parseBody = parseBody;
+exports.INBOX_LIMITS = { pageMin: 1, pageMax: 100, cursorMax: 128, idMax: 64, upToMax: 40, bodyBytes: 1024, personMax: 128 };
+const ok = (value) => ({ ok: true, value });
+const bad = (field) => ({ ok: false, field });
+function parseLimit(raw) {
+    if (raw === null)
+        return ok(undefined);
+    if (!/^\d{1,3}$/.test(raw))
+        return bad('limit');
+    const n = Number(raw);
+    return n >= exports.INBOX_LIMITS.pageMin && n <= exports.INBOX_LIMITS.pageMax ? ok(n) : bad('limit');
+}
+function parseCursor(raw) {
+    if (raw === null)
+        return ok(undefined);
+    return raw.length > 0 && raw.length <= exports.INBOX_LIMITS.cursorMax && /^[A-Za-z0-9_-]+$/.test(raw) ? ok(raw) : bad('cursor');
+}
+function parseUnread(raw) {
+    if (raw === null || raw === 'false')
+        return ok(false);
+    return raw === 'true' ? ok(true) : bad('unread');
+}
+function parseId(raw) {
+    return raw.length > 0 && raw.length <= exports.INBOX_LIMITS.idMax && /^[A-Za-z0-9_-]+$/.test(raw) ? ok(raw) : bad('id');
+}
+function parseUpTo(raw) {
+    if (raw === undefined || raw === null)
+        return ok(undefined);
+    if (typeof raw !== 'string' || raw.length > exports.INBOX_LIMITS.upToMax || !/^\d{4}-\d{2}-\d{2}T[\d:.]+(Z|[+-]\d{2}:\d{2})$/.test(raw))
+        return bad('upTo');
+    const t = Date.parse(raw);
+    return Number.isFinite(t) ? ok(new Date(t).toISOString()) : bad('upTo');
+}
+function parseState(raw) {
+    return raw === 'opted_in' || raw === 'opted_out' ? ok(raw) : bad('state');
+}
+/** A JSON object of at most 1024 bytes. An empty body is an empty object. */
+function parseBody(text) {
+    if (new TextEncoder().encode(text).length > exports.INBOX_LIMITS.bodyBytes)
+        return bad('body');
+    if (text.trim() === '')
+        return ok({});
+    try {
+        const v = JSON.parse(text);
+        return typeof v === 'object' && v !== null && !Array.isArray(v) ? ok(v) : bad('body');
+    }
+    catch {
+        return bad('body');
+    }
+}

package/dist/cjs/inbox-react/format.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fill = fill;
+exports.badgeText = badgeText;
+exports.bellName = bellName;
+exports.safeLink = safeLink;
+exports.relativeTime = relativeTime;
+exports.exactTime = exactTime;
+/** Fills `{name}` placeholders. Values are text, never markup. */
+function fill(template, values) {
+    return template.replace(/\{(\w+)\}/g, (whole, key) => (key in values ? String(values[key]) : whole));
+}
+/** Nothing for 0, the number for 1 to 99, "99+" above (12.1). */
+function badgeText(count) {
+    if (!Number.isFinite(count) || count < 1)
+        return '';
+    return count > 99 ? '99+' : String(Math.floor(count));
+}
+/** The bell's accessible name: "{label}, {n} unread", or the label alone when nothing is unread (15.3). */
+function bellName(labels, count) {
+    return count > 0 ? fill(labels.bellWithCount, { label: labels.bell, n: count }) : labels.bell;
+}
+const LINK_MAX = 2048;
+/** Accepts exactly what the inbox stores: an absolute https URL without credentials, at most 2048 characters (12.15). */
+function safeLink(link) {
+    if (!link || link.length > LINK_MAX)
+        return null;
+    try {
+        const u = new URL(link);
+        return u.protocol === 'https:' && !u.username && !u.password ? u.toString() : null;
+    }
+    catch {
+        return null;
+    }
+}
+const MINUTE = 60;
+const HOUR = 3600;
+const DAY = 86400;
+/** "now", "5 minutes ago", "yesterday", then a short date after a week. A time in the future (clock skew) reads as now. */
+function relativeTime(iso, now, locale) {
+    const then = Date.parse(iso);
+    if (!Number.isFinite(then))
+        return '';
+    const seconds = Math.max(0, Math.floor((now.getTime() - then) / 1000));
+    try {
+        const rtf = new Intl.RelativeTimeFormat(locale, { numeric: 'auto' });
+        if (seconds < MINUTE)
+            return rtf.format(0, 'second');
+        if (seconds < HOUR)
+            return rtf.format(-Math.floor(seconds / MINUTE), 'minute');
+        if (seconds < DAY)
+            return rtf.format(-Math.floor(seconds / HOUR), 'hour');
+        if (seconds < 7 * DAY)
+            return rtf.format(-Math.floor(seconds / DAY), 'day');
+        return new Intl.DateTimeFormat(locale, { dateStyle: 'medium' }).format(new Date(then));
+    }
+    catch {
+        return new Date(then).toISOString().slice(0, 10);
+    }
+}
+/** The full date and time, for the `title` of a relative time. */
+function exactTime(iso, locale) {
+    const then = Date.parse(iso);
+    if (!Number.isFinite(then))
+        return '';
+    try {
+        return new Intl.DateTimeFormat(locale, { dateStyle: 'full', timeStyle: 'short' }).format(new Date(then));
+    }
+    catch {
+        return new Date(then).toISOString();
+    }
+}

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

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_API_BASE = void 0;
+exports.normalizeApiBase = normalizeApiBase;
+exports.createInboxBrowserClient = createInboxBrowserClient;
+const parse_1 = require("./parse");
+exports.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.
+ */
+function normalizeApiBase(apiBase) {
+    const base = (apiBase ?? exports.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.
+ */
+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: (0, parse_1.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', parse_1.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}` : ''}`, parse_1.parsePage);
+        },
+        markRead: (id) => call('POST', `/notifications/${encodeURIComponent(id)}/read`, parse_1.parseMarkRead, {}),
+        markAllRead: (upTo) => call('POST', '/read-all', parse_1.parseReadAll, upTo ? { upTo } : {}),
+        getPreference: () => call('GET', '/preference', parse_1.parsePreference),
+        setPreference: (state) => call('PUT', '/preference', parse_1.parsePreference, { state }),
+    };
+}

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

@@ -0,0 +1,13 @@
+"use strict";
+'use client';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InboxContext = void 0;
+exports.useInbox = useInbox;
+const react_1 = require("react");
+exports.InboxContext = (0, react_1.createContext)(null);
+function useInbox() {
+    const value = (0, react_1.useContext)(exports.InboxContext);
+    if (!value)
+        throw new Error('Wrap the inbox components in <InboxProvider>.');
+    return value;
+}

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

@@ -0,0 +1,13 @@
+"use strict";
+'use client';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InboxFullList = InboxFullList;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const inbox_list_1 = require("./inbox-list");
+/**
+ * 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.
+ */
+function InboxFullList({ maxHeight = 'min(70vh, 640px)' }) {
+    return (0, jsx_runtime_1.jsx)(inbox_list_1.InboxListView, { paged: true, maxHeight: maxHeight });
+}

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

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

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

@@ -0,0 +1,13 @@
+"use strict";
+'use client';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InboxPanel = InboxPanel;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const core_1 = require("@mantine/core");
+const inbox_context_1 = require("./inbox-context");
+const inbox_list_1 = require("./inbox-list");
+/** What the bell opens: the newest notifications, with the ways on to the full list and the preference. */
+function InboxPanel() {
+    const { labels, viewAll, openPreferences } = (0, inbox_context_1.useInbox)();
+    return ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)(inbox_list_1.InboxListView, { maxHeight: 400, heading: (0, jsx_runtime_1.jsx)(core_1.Title, { order: 2, size: "h5", children: labels.heading }) }), (0, jsx_runtime_1.jsx)(core_1.Divider, {}), (0, jsx_runtime_1.jsxs)(core_1.Group, { justify: "space-between", gap: 4, p: 4, children: [(0, jsx_runtime_1.jsx)(core_1.Button, { variant: "subtle", size: "compact-sm", mih: 44, px: "sm", onClick: viewAll, children: labels.viewAll }), (0, jsx_runtime_1.jsx)(core_1.Button, { variant: "subtle", size: "compact-sm", mih: 44, px: "sm", onClick: openPreferences, children: labels.preferences })] })] }));
+}

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

@@ -0,0 +1,157 @@
+"use strict";
+'use client';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InboxProvider = InboxProvider;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+const core_1 = require("@mantine/core");
+const hooks_1 = require("@mantine/hooks");
+const format_1 = require("./format");
+const inbox_client_1 = require("./inbox-client");
+const inbox_context_1 = require("./inbox-context");
+const inbox_full_list_1 = require("./inbox-full-list");
+const inbox_state_1 = require("./inbox-state");
+const labels_1 = require("./labels");
+const preference_dialog_1 = require("./preference-dialog");
+const use_inbox_polling_1 = require("./use-inbox-polling");
+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();
+function InboxProvider({ apiBase, labels, locale, onViewAll, onOpenPreferences, openLink, children }) {
+    const client = (0, react_1.useMemo)(() => (0, inbox_client_1.createInboxBrowserClient)(apiBase), [apiBase]);
+    const merged = (0, react_1.useMemo)(() => (0, labels_1.mergeLabels)(labels), [labels]);
+    const [state, dispatch] = (0, react_1.useReducer)(inbox_state_1.inboxReducer, inbox_state_1.initialInboxState);
+    const [panelOpened, setPanelOpened] = (0, react_1.useState)(false);
+    const [fullOpened, setFullOpened] = (0, react_1.useState)(false);
+    const [preferencesOpened, setPreferencesOpened] = (0, react_1.useState)(false);
+    const reduceMotion = (0, hooks_1.useReducedMotion)();
+    const bellRef = (0, react_1.useRef)(null);
+    const latest = (0, react_1.useRef)(state);
+    (0, react_1.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 = (0, react_1.useRef)('all');
+    const lists = (0, react_1.useRef)(0);
+    const request = (0, react_1.useRef)(0);
+    const load = (0, react_1.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 = (0, react_1.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]);
+    (0, use_inbox_polling_1.useInboxPolling)(poll);
+    const attachList = (0, react_1.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 = (0, react_1.useCallback)((tab) => {
+        if (tab === tabRef.current)
+            return;
+        tabRef.current = tab;
+        dispatch({ type: 'tabChanged', tab });
+        void load('replace', tab);
+    }, [load]);
+    const select = (0, react_1.useCallback)((item) => {
+        const link = (0, format_1.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 = (0, react_1.useCallback)(() => {
+        const before = latest.current;
+        if (!(0, inbox_state_1.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 = (0, react_1.useCallback)(() => {
+        const s = latest.current;
+        if (s.nextCursor && !s.loadingMore)
+            void load('append', s.tab, s.nextCursor);
+    }, [load]);
+    const retry = (0, react_1.useCallback)(() => void load('replace', latest.current.tab), [load]);
+    const clearMessage = (0, react_1.useCallback)(() => dispatch({ type: 'messageCleared' }), []);
+    const openPanel = (0, react_1.useCallback)(() => setPanelOpened(true), []);
+    const closePanel = (0, react_1.useCallback)(() => setPanelOpened(false), []);
+    const viewAll = (0, react_1.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 = (0, react_1.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 = (0, react_1.useCallback)(() => {
+        window.setTimeout(() => bellRef.current?.focus(), 0);
+    }, []);
+    const value = (0, react_1.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 ((0, jsx_runtime_1.jsxs)(inbox_context_1.InboxContext.Provider, { value: value, children: [children, (0, jsx_runtime_1.jsx)(core_1.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 && (0, jsx_runtime_1.jsx)(inbox_full_list_1.InboxFullList, {}) }), (0, jsx_runtime_1.jsx)(preference_dialog_1.PreferenceDialog, { opened: preferencesOpened, onClose: () => {
+                    setPreferencesOpened(false);
+                    focusBell();
+                } })] }));
+}

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

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initialInboxState = void 0;
+exports.inboxReducer = inboxReducer;
+exports.canMarkAll = canMarkAll;
+exports.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 };
+}
+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). */
+function canMarkAll(s) {
+    return s.unreadCount > 0 && s.markAll === null;
+}

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

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_INBOX_LABELS = exports.InboxFullList = exports.NotificationBell = exports.InboxProvider = void 0;
+/**
+ * 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.
+ */
+var inbox_provider_1 = require("./inbox-provider");
+Object.defineProperty(exports, "InboxProvider", { enumerable: true, get: function () { return inbox_provider_1.InboxProvider; } });
+var notification_bell_1 = require("./notification-bell");
+Object.defineProperty(exports, "NotificationBell", { enumerable: true, get: function () { return notification_bell_1.NotificationBell; } });
+var inbox_full_list_1 = require("./inbox-full-list");
+Object.defineProperty(exports, "InboxFullList", { enumerable: true, get: function () { return inbox_full_list_1.InboxFullList; } });
+var labels_1 = require("./labels");
+Object.defineProperty(exports, "DEFAULT_INBOX_LABELS", { enumerable: true, get: function () { return labels_1.DEFAULT_INBOX_LABELS; } });