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

package/dist/notifications/ui/NotificationBell.d.ts

@@ -0,0 +1,85 @@
+/**
+ * The notification centre — a bell in the `AppBar` with an unread badge, and a
+ * popover listing what has arrived recently.
+ *
+ * Issue #127, epic #109.
+ *
+ * =============================================================================
+ * THIS IS THE PRIMARY SURFACE, NOT A CONVENIENCE ON TOP OF NATIVE TOASTS
+ * =============================================================================
+ *
+ * Everything here works with the SSE stream down and with browser notification
+ * permission denied, because those are the NORMAL cases: permission is denied
+ * by a large fraction of users and cannot be re-requested, and a stream is one
+ * proxy misconfiguration away from never connecting. Epic #109 is explicit that
+ * a feature existing only as an OS toast does not exist at all for the people
+ * who denied it.
+ *
+ * So this component reads `NotificationContext`, whose contents come from
+ * `GET /api/notifications` — a database table — and never from the stream
+ * directly. The stream only makes the numbers change without a refresh.
+ *
+ * =============================================================================
+ * NO BREAKPOINT GATE, DELIBERATELY
+ * =============================================================================
+ *
+ * There is no `useMediaQuery` here. `CLAUDE.md` names FIVE coupled gates that
+ * move together or not at all (`Layout`'s `showRail`, `BottomNav`'s self-gate,
+ * `<main>`'s padding, and `isCompactWindow` in both `SettingsHub` and
+ * `AppBar`), and a sixth would be a sixth thing to keep in lockstep for no
+ * gain.
+ *
+ * The popover sizes itself with `min()` instead: `min(100vw - 32px, 380px)`
+ * gives a phone a near-full-width sheet and a desktop a fixed panel, from ONE
+ * declaration with no breakpoint in it and no second layout to keep in sync.
+ * The same trick bounds its height against the viewport so a long list scrolls
+ * inside the popover rather than off the bottom of a short screen.
+ */
+import type { ReactNode } from 'react';
+import type { AppNotification } from '../headless/types.js';
+/**
+ * The bell's slots (#738): app content placed inside the packaged popover.
+ * Every slot is optional; without one the bell renders exactly as before.
+ *
+ * @stability experimental
+ */
+export interface NotificationBellSlots {
+    /** Replaces the "You're all caught up." text of an empty inbox. */
+    emptyState?: ReactNode;
+    /**
+     * Rendered under the list, inside the popover (a "View all" link, a
+     * settings shortcut). Receives `close`, to dismiss the popover before
+     * navigating.
+     */
+    footer?: (helpers: {
+        close: () => void;
+    }) => ReactNode;
+    /** Extra content at the end of one row (an event-specific chip). */
+    itemExtra?: (notification: AppNotification) => ReactNode;
+}
+/**
+ * The props of {@link NotificationBell}.
+ *
+ * @stability experimental
+ */
+export interface NotificationBellProps {
+    /** The bell's slots. */
+    slots?: NotificationBellSlots;
+}
+/**
+ * The AppBar notification bell: the unread badge and the recent-notifications
+ * popover, reading the inbox from `NotificationProvider`. Renders nothing
+ * without the provider. The app places it in its own AppBar; the package
+ * never imports the app shell.
+ *
+ * @example
+ * ```tsx
+ * <NotificationBell slots={{ footer: ({ close }) => <Button onClick={close}>Close</Button> }} />
+ * ```
+ *
+ * @extensionPoint slot
+ * @stability experimental
+ */
+export declare function NotificationBell({ slots }?: NotificationBellProps): import("react").JSX.Element | null;
+export default NotificationBell;
+//# sourceMappingURL=NotificationBell.d.ts.map

package/dist/notifications/ui/NotificationBell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NotificationBell.d.ts","sourceRoot":"","sources":["../../../src/notifications/ui/NotificationBell.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAuBvC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAW5D;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,mEAAmE;IACnE,UAAU,CAAC,EAAE,SAAS,CAAC;IACvB;;;;OAIG;IACH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,IAAI,CAAA;KAAE,KAAK,SAAS,CAAC;IACvD,oEAAoE;IACpE,SAAS,CAAC,EAAE,CAAC,YAAY,EAAE,eAAe,KAAK,SAAS,CAAC;CAC1D;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,wBAAwB;IACxB,KAAK,CAAC,EAAE,qBAAqB,CAAC;CAC/B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,KAAK,EAAE,GAAE,qBAA0B,sCAmQrE;AAED,eAAe,gBAAgB,CAAC"}

package/dist/notifications/ui/NotificationBell.js

@@ -0,0 +1,161 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * The notification centre — a bell in the `AppBar` with an unread badge, and a
+ * popover listing what has arrived recently.
+ *
+ * Issue #127, epic #109.
+ *
+ * =============================================================================
+ * THIS IS THE PRIMARY SURFACE, NOT A CONVENIENCE ON TOP OF NATIVE TOASTS
+ * =============================================================================
+ *
+ * Everything here works with the SSE stream down and with browser notification
+ * permission denied, because those are the NORMAL cases: permission is denied
+ * by a large fraction of users and cannot be re-requested, and a stream is one
+ * proxy misconfiguration away from never connecting. Epic #109 is explicit that
+ * a feature existing only as an OS toast does not exist at all for the people
+ * who denied it.
+ *
+ * So this component reads `NotificationContext`, whose contents come from
+ * `GET /api/notifications` — a database table — and never from the stream
+ * directly. The stream only makes the numbers change without a refresh.
+ *
+ * =============================================================================
+ * NO BREAKPOINT GATE, DELIBERATELY
+ * =============================================================================
+ *
+ * There is no `useMediaQuery` here. `CLAUDE.md` names FIVE coupled gates that
+ * move together or not at all (`Layout`'s `showRail`, `BottomNav`'s self-gate,
+ * `<main>`'s padding, and `isCompactWindow` in both `SettingsHub` and
+ * `AppBar`), and a sixth would be a sixth thing to keep in lockstep for no
+ * gain.
+ *
+ * The popover sizes itself with `min()` instead: `min(100vw - 32px, 380px)`
+ * gives a phone a near-full-width sheet and a desktop a fixed panel, from ONE
+ * declaration with no breakpoint in it and no second layout to keep in sync.
+ * The same trick bounds its height against the viewport so a long list scrolls
+ * inside the popover rather than off the bottom of a short screen.
+ */
+import { useCallback, useRef, useState } from 'react';
+import { Alert, Badge, Box, Button, CircularProgress, Divider, IconButton, List, ListItemButton, Popover, Tooltip, Typography, } from '@mui/material';
+import { Notifications as NotificationsIcon, NotificationsNone as NotificationsNoneIcon, } from '@mui/icons-material';
+import { useNavigate } from 'react-router-dom';
+import { useNotifications } from '../headless/NotificationContext.js';
+import { isInternalLink } from '../headless/internalLink.js';
+import { formatRelativeTime } from './relativeTime.js';
+/**
+ * The badge stops counting here and shows "20+".
+ *
+ * MUI's `max`. A four-digit badge is unreadable and would widen the toolbar;
+ * the exact number past this point is not a thing anyone acts on, and the list
+ * itself holds the same 20 (`RECENT_NOTIFICATION_COUNT`).
+ */
+const BADGE_MAX = 20;
+/**
+ * The AppBar notification bell: the unread badge and the recent-notifications
+ * popover, reading the inbox from `NotificationProvider`. Renders nothing
+ * without the provider. The app places it in its own AppBar; the package
+ * never imports the app shell.
+ *
+ * @example
+ * ```tsx
+ * <NotificationBell slots={{ footer: ({ close }) => <Button onClick={close}>Close</Button> }} />
+ * ```
+ *
+ * @extensionPoint slot
+ * @stability experimental
+ */
+export function NotificationBell({ slots } = {}) {
+    const centre = useNotifications();
+    const navigate = useNavigate();
+    const anchorRef = useRef(null);
+    const [open, setOpen] = useState(false);
+    /**
+     * Open the popover, and RE-READ while doing it.
+     *
+     * The refresh is not redundant with the stream. A tab that has been open for
+     * hours may have missed events entirely — the stream replays nothing after a
+     * drop, and its fan-out is per API process, so a multi-replica deployment can
+     * leave a perfectly healthy connection unaware of an event published
+     * elsewhere. Opening the bell is a deliberate "show me what there is", which
+     * makes it exactly the right moment to pay for one query. See the header of
+     * `contexts/NotificationContext.tsx`.
+     */
+    const handleOpen = useCallback(() => {
+        setOpen(true);
+        void centre?.refresh();
+    }, [centre]);
+    const handleRowClick = useCallback((notification) => {
+        // Marked read on ANY click, including one that navigates nowhere: the
+        // user has demonstrably seen it. Fire-and-forget — the context applies it
+        // optimistically and reconciles the count from the response, so awaiting
+        // here would only delay closing the popover.
+        if (notification.readAt === null)
+            void centre?.markRead(notification.id);
+        // Closed BEFORE navigating. A popover left open across a route change
+        // hangs over the page it just took the user to, anchored to a toolbar
+        // button they are no longer looking at.
+        setOpen(false);
+        // `isInternalLink` re-checks a guarantee the API already makes (see that
+        // function). A notification with no link is a perfectly ordinary
+        // notification — it is an announcement, not a shortcut — so a missing
+        // link is not an error state and the row simply marks itself read.
+        if (isInternalLink(notification.link))
+            navigate(notification.link);
+    }, [centre, navigate]);
+    // NO PROVIDER, NO BELL. `useNotifications` returns `null` rather than
+    // throwing, so the app shell renders normally where the centre is not mounted
+    // — `AppBar` is rendered standalone in several test files, none of which is
+    // about notifications, and a shell that refuses to render because an optional
+    // data provider is absent turns a missing decoration into a blank page. The
+    // wiring point is `App.tsx`, which wraps the `Layout` route element.
+    if (!centre)
+        return null;
+    const { notifications, unreadCount, isLoading, error, markAllRead } = centre;
+    const hasUnread = unreadCount > 0;
+    // One instant for the whole list, so seven rows rendered in one pass cannot
+    // disagree about what "now" is.
+    const renderedAt = new Date();
+    return (_jsxs(_Fragment, { children: [_jsx(Tooltip, { title: "Notifications", children: _jsx(IconButton, { ref: anchorRef, onClick: handleOpen, color: "inherit", "aria-label": hasUnread
+                        ? `Notifications, ${unreadCount} unread`
+                        : 'Notifications, none unread', "aria-haspopup": "dialog", "aria-expanded": open, sx: { mr: 1, flexShrink: 0 }, children: _jsx(Badge, { badgeContent: unreadCount, max: BADGE_MAX, color: "error", children: hasUnread ? _jsx(NotificationsIcon, {}) : _jsx(NotificationsNoneIcon, {}) }) }) }), _jsxs(Popover, { open: open, anchorEl: anchorRef.current, onClose: () => setOpen(false), anchorOrigin: { vertical: 'bottom', horizontal: 'right' }, transformOrigin: { vertical: 'top', horizontal: 'right' }, slotProps: {
+                    paper: {
+                        // `role="dialog"` matches the `aria-haspopup` on the trigger, and
+                        // the label names it — without one a screen reader announces an
+                        // unnamed dialog and the user has to guess what they just opened.
+                        role: 'dialog',
+                        'aria-label': 'Notifications',
+                        sx: {
+                            // See the header: `min()` rather than a breakpoint. `- 32px`
+                            // leaves the popover clear of the viewport edges on a phone
+                            // instead of butting against them.
+                            width: 'min(100vw - 32px, 380px)',
+                            // Bounded against the SHORT side too, so a long list scrolls
+                            // inside the panel rather than running off a landscape phone.
+                            maxHeight: 'min(70vh, 480px)',
+                            display: 'flex',
+                            flexDirection: 'column',
+                        },
+                    },
+                }, children: [_jsxs(Box, { sx: {
+                            display: 'flex',
+                            alignItems: 'center',
+                            justifyContent: 'space-between',
+                            gap: 1,
+                            px: 2,
+                            py: 1.5,
+                            flexShrink: 0,
+                        }, children: [_jsx(Typography, { variant: "subtitle1", component: "h2", sx: { fontWeight: 600 }, children: "Notifications" }), hasUnread && (_jsx(Button, { size: "small", onClick: () => void markAllRead(), children: "Mark all read" }))] }), _jsx(Divider, {}), _jsxs(Box, { sx: { overflowY: 'auto', flexGrow: 1 }, children: [error && (_jsx(Alert, { severity: "error", sx: { m: 2 }, children: error })), isLoading && notifications.length === 0 && !error && (_jsx(Box, { sx: { display: 'flex', justifyContent: 'center', p: 4 }, children: _jsx(CircularProgress, { size: 24, "aria-label": "Loading notifications" }) })), !isLoading && !error && notifications.length === 0 && (_jsx(Box, { sx: { p: 4, textAlign: 'center' }, children: slots?.emptyState ?? (_jsx(Typography, { variant: "body2", color: "text.secondary", children: "You\u2019re all caught up." })) })), notifications.length > 0 && (_jsx(List, { disablePadding: true, children: notifications.map((notification, index) => {
+                                    const isUnread = notification.readAt === null;
+                                    return (_jsxs(Box, { component: "li", sx: { listStyle: 'none' }, children: [index > 0 && _jsx(Divider, { component: "div" }), _jsxs(ListItemButton, { onClick: () => handleRowClick(notification), sx: { alignItems: 'flex-start', gap: 1.5, py: 1.5 }, children: [_jsx(Box, { "aria-hidden": true, sx: {
+                                                            mt: 0.75,
+                                                            width: 8,
+                                                            height: 8,
+                                                            borderRadius: '50%',
+                                                            flexShrink: 0,
+                                                            backgroundColor: isUnread ? 'primary.main' : 'transparent',
+                                                        } }), _jsxs(Box, { sx: { minWidth: 0, flexGrow: 1 }, children: [_jsx(Typography, { variant: "body2", sx: { fontWeight: isUnread ? 600 : 400 }, children: notification.title }), _jsx(Typography, { variant: "body2", color: "text.secondary", sx: { mt: 0.25 }, children: notification.body }), _jsxs(Typography, { variant: "caption", color: "text.secondary", sx: { display: 'block', mt: 0.5 }, children: [_jsx(Box, { component: "time", dateTime: notification.createdAt, title: new Date(notification.createdAt).toLocaleString(), children: formatRelativeTime(notification.createdAt, renderedAt) }), isUnread && ' · Unread'] }), slots?.itemExtra?.(notification)] })] })] }, notification.id));
+                                }) }))] }), slots?.footer && (_jsxs(_Fragment, { children: [_jsx(Divider, {}), _jsx(Box, { sx: { flexShrink: 0 }, children: slots.footer({ close: () => setOpen(false) }) })] }))] })] }));
+}
+export default NotificationBell;
+//# sourceMappingURL=NotificationBell.js.map

package/dist/notifications/ui/NotificationBell.js.map

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

package/dist/notifications/ui/NotificationPermissionBanner.d.ts

@@ -0,0 +1,56 @@
+/**
+ * App-wide "notifications are not on for this device" banner — issue #365.
+ *
+ * Rendered by `Layout` directly under `MaintenanceBanner`, fed by the single
+ * `usePushSubscriptionSync` mount there. Shown only when the deployment offers
+ * browser or push notifications and this device can act on it:
+ *
+ *   * `default`           — an Enable button. The auto-prompt may have been
+ *                           ignored (Firefox/Safari need a gesture) or quieted
+ *                           (Chrome), so a click must always be available.
+ *   * `denied`            — the app cannot re-ask; explain the browser's
+ *                           site-settings remedy.
+ *   * `ios-needs-install` — Add to Home Screen first.
+ *
+ * Every other capability renders nothing: there is either nothing left to do
+ * (`granted`, `sw-unavailable`) or nothing the user can do
+ * (`unsupported`, `insecure-context`, `admin-disabled`).
+ *
+ * Dismissal lasts for the browser session only, and only for the state that
+ * was dismissed — the owner wants this prominent, so it returns on the next
+ * visit, and a dismissed `default` that becomes `denied` shows again.
+ * Suppressed on `/settings/notifications`, which carries the fuller version of
+ * the same message and controls.
+ */
+import type { NotificationCapability } from '../headless/useNotificationCapability.js';
+import type { NotificationConfigResponse } from '../headless/types.js';
+export declare const NOTIFICATION_SETTINGS_PATH = "/settings/notifications";
+export declare const BANNER_DISMISSED_STORAGE_KEY = "notificationPermissionBanner.dismissed";
+/**
+ * The props of {@link NotificationPermissionBanner}.
+ *
+ * @stability experimental
+ */
+export interface NotificationPermissionBannerProps {
+    /** `null` while loading — renders nothing rather than flashing. */
+    config: NotificationConfigResponse | null;
+    /** What this device can do about browser notifications. */
+    capability: NotificationCapability;
+    /** Asks for permission (from the banner's button). */
+    onRequestPermission: () => void;
+    /** Whether the permission prompt is open (disables the button). */
+    isRequestingPermission?: boolean;
+}
+/**
+ * The app-wide banner that asks for notification permission (or explains why
+ * it cannot be granted on this device), dismissible per session. The app
+ * places it in its layout, fed by `usePushSubscriptionSync`.
+ *
+ * @param props - the config, the capability and the request action.
+ * @returns the banner, or null when there is nothing to ask.
+ *
+ * @extensionPoint component
+ * @stability experimental
+ */
+export declare function NotificationPermissionBanner({ config, capability, onRequestPermission, isRequestingPermission, }: NotificationPermissionBannerProps): import("react").JSX.Element | null;
+//# sourceMappingURL=NotificationPermissionBanner.d.ts.map

package/dist/notifications/ui/NotificationPermissionBanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"NotificationPermissionBanner.d.ts","sourceRoot":"","sources":["../../../src/notifications/ui/NotificationPermissionBanner.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAMH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,0CAA0C,CAAC;AACvF,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;AAEvE,eAAO,MAAM,0BAA0B,4BAA4B,CAAC;AACpE,eAAO,MAAM,4BAA4B,2CAA2C,CAAC;AAwBrF;;;;GAIG;AACH,MAAM,WAAW,iCAAiC;IAChD,mEAAmE;IACnE,MAAM,EAAE,0BAA0B,GAAG,IAAI,CAAC;IAC1C,2DAA2D;IAC3D,UAAU,EAAE,sBAAsB,CAAC;IACnC,sDAAsD;IACtD,mBAAmB,EAAE,MAAM,IAAI,CAAC;IAChC,mEAAmE;IACnE,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,4BAA4B,CAAC,EAC3C,MAAM,EACN,UAAU,EACV,mBAAmB,EACnB,sBAA8B,GAC/B,EAAE,iCAAiC,sCAiFnC"}

package/dist/notifications/ui/NotificationPermissionBanner.js

@@ -0,0 +1,106 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * App-wide "notifications are not on for this device" banner — issue #365.
+ *
+ * Rendered by `Layout` directly under `MaintenanceBanner`, fed by the single
+ * `usePushSubscriptionSync` mount there. Shown only when the deployment offers
+ * browser or push notifications and this device can act on it:
+ *
+ *   * `default`           — an Enable button. The auto-prompt may have been
+ *                           ignored (Firefox/Safari need a gesture) or quieted
+ *                           (Chrome), so a click must always be available.
+ *   * `denied`            — the app cannot re-ask; explain the browser's
+ *                           site-settings remedy.
+ *   * `ios-needs-install` — Add to Home Screen first.
+ *
+ * Every other capability renders nothing: there is either nothing left to do
+ * (`granted`, `sw-unavailable`) or nothing the user can do
+ * (`unsupported`, `insecure-context`, `admin-disabled`).
+ *
+ * Dismissal lasts for the browser session only, and only for the state that
+ * was dismissed — the owner wants this prominent, so it returns on the next
+ * visit, and a dismissed `default` that becomes `denied` shows again.
+ * Suppressed on `/settings/notifications`, which carries the fuller version of
+ * the same message and controls.
+ */
+import { useState } from 'react';
+import { Alert, AlertTitle, Box, Button, CircularProgress, IconButton, Stack } from '@mui/material';
+import CloseIcon from '@mui/icons-material/Close';
+import { Link as RouterLink, useLocation } from 'react-router-dom';
+export const NOTIFICATION_SETTINGS_PATH = '/settings/notifications';
+export const BANNER_DISMISSED_STORAGE_KEY = 'notificationPermissionBanner.dismissed';
+function isBannerCapability(capability) {
+    return capability === 'default' || capability === 'denied' || capability === 'ios-needs-install';
+}
+function readDismissed() {
+    try {
+        return window.sessionStorage.getItem(BANNER_DISMISSED_STORAGE_KEY);
+    }
+    catch {
+        return null;
+    }
+}
+function writeDismissed(capability) {
+    try {
+        window.sessionStorage.setItem(BANNER_DISMISSED_STORAGE_KEY, capability);
+    }
+    catch {
+        // Storage blocked: the in-memory dismissal below still hides it for now.
+    }
+}
+/**
+ * The app-wide banner that asks for notification permission (or explains why
+ * it cannot be granted on this device), dismissible per session. The app
+ * places it in its layout, fed by `usePushSubscriptionSync`.
+ *
+ * @param props - the config, the capability and the request action.
+ * @returns the banner, or null when there is nothing to ask.
+ *
+ * @extensionPoint component
+ * @stability experimental
+ */
+export function NotificationPermissionBanner({ config, capability, onRequestPermission, isRequestingPermission = false, }) {
+    const { pathname } = useLocation();
+    const [dismissed, setDismissed] = useState(readDismissed);
+    if (!config || !(config.pushEnabled || config.browserEnabled))
+        return null;
+    if (!isBannerCapability(capability))
+        return null;
+    if (dismissed === capability)
+        return null;
+    if (pathname === NOTIFICATION_SETTINGS_PATH || pathname.startsWith(`${NOTIFICATION_SETTINGS_PATH}/`)) {
+        return null;
+    }
+    const dismiss = () => {
+        writeDismissed(capability);
+        setDismissed(capability);
+    };
+    const settingsLink = (_jsx(Button, { component: RouterLink, to: NOTIFICATION_SETTINGS_PATH, color: "inherit", size: "small", children: capability === 'ios-needs-install' ? 'Show me how' : 'Notification settings' }));
+    let title;
+    let body;
+    let primaryAction;
+    switch (capability) {
+        case 'default':
+            title = 'Notifications are not enabled on this device';
+            body = 'Turn them on so important alerts reach you even when this app is closed.';
+            primaryAction = (_jsx(Button, { variant: "contained", color: "warning", size: "small", onClick: onRequestPermission, disabled: isRequestingPermission, startIcon: isRequestingPermission ? _jsx(CircularProgress, { size: 16, color: "inherit" }) : undefined, children: isRequestingPermission ? 'Waiting for your browser…' : 'Enable notifications' }));
+            break;
+        case 'denied':
+            title = 'Notifications are blocked on this device';
+            body =
+                'Your browser is blocking notifications from this site, and the app cannot ask again. ' +
+                    'Open your browser’s site settings (usually the icon at the left of the address bar) ' +
+                    'and allow notifications.';
+            primaryAction = settingsLink;
+            break;
+        case 'ios-needs-install':
+            title = 'Add this app to your Home Screen to get notifications';
+            body =
+                'On iPhone and iPad, notifications only work for apps added to the Home Screen: ' +
+                    'tap Share, then “Add to Home Screen”.';
+            primaryAction = settingsLink;
+            break;
+    }
+    return (_jsx(Box, { sx: { mb: 3 }, children: _jsxs(Alert, { severity: capability === 'ios-needs-install' ? 'info' : 'warning', action: _jsx(IconButton, { "aria-label": "Dismiss notification banner", color: "inherit", size: "small", onClick: dismiss, children: _jsx(CloseIcon, { fontSize: "small" }) }), children: [_jsx(AlertTitle, { children: title }), body, _jsxs(Stack, { direction: "row", spacing: 1, sx: { mt: 1.5, flexWrap: 'wrap', rowGap: 1 }, children: [primaryAction, capability === 'default' && settingsLink] })] }) }));
+}
+//# sourceMappingURL=NotificationPermissionBanner.js.map

package/dist/notifications/ui/NotificationPermissionBanner.js.map

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