@nommos/core 0.0.43 → 0.0.45

package/src/lib/popup-viewer.d.ts

@@ -11,10 +11,20 @@ export interface PopupViewerCallbacks {
      * engagement span from running forever when the tab simply goes away.
      */
     onAbandoned: (item: WebPopupItem) => void;
-    onDismissed: (item: WebPopupItem) => void;
+    /**
+     * @param source which surface the visitor dismissed from. Same act either way — the distinction
+     *        is a data field on one event, not two events.
+     */
+    onDismissed: (item: WebPopupItem, source: 'tray' | 'modal') => void;
     onCtaClick: (item: WebPopupItem, buttonIndex: number, url: string) => void;
     onLinkClick: (item: WebPopupItem, url: string) => void;
-    onCarouselMove: (item: WebPopupItem, direction: 'next' | 'prev') => void;
+    /**
+     * The tray was opened. Not an engagement signal for any single popup — seeing a row in a list is
+     * not opening it — so this must never be treated as a view.
+     */
+    onTrayOpened: (items: WebPopupItem[], unreadCount: number) => void;
+    /** The visitor asked for everything to be marked seen. Deliberate and explicit, never implicit. */
+    onMarkAllSeen: () => void;
     onRenderFailed: (item: WebPopupItem, reason: string) => void;
 }
 export declare class PopupViewer {
@@ -24,28 +34,37 @@ export declare class PopupViewer {
     private state;
     private launcherHost;
     private launcherRoot;
-    /** The element the launcher is currently mounted into. `null` means the floating fallback. */
+    /** The element the launcher is mounted into. `null` means no anchor, so no launcher at all. */
     private anchor;
     private domObserver;
     private remountQueued;
     /** Resolved once per viewer: the visitor's language does not change mid-page. */
+    private readonly lang;
     private readonly copy;
     private items;
-    /** What is on screen. Only moves once the next popup's content is in hand. */
+    /** Which popup the modal is showing. Set by {@link open}; the tray is what moves between them. */
     private index;
-    /**
-     * Where the visitor has navigated to, which runs ahead of {@link index} while a load is in
-     * flight. Without it, two quick taps on `›` both step from the same rendered index and the
-     * second is swallowed.
-     */
-    private pendingIndex;
-    /** Guards against a slow content load landing after a later move and rewinding the carousel. */
-    private swapToken;
     private lastFocused;
-    private touchStartX;
     private audio;
+    /**
+     * Tray visibility, deliberately separate from {@link ViewerState}.
+     *
+     * <p>That enum models the modal's animated open/close and its awaited content load. The tray has
+     * neither, and folding it in would force every `state !== 'visible'` guard in this file to be
+     * re-reasoned for a surface those guards were never about.
+     */
+    private trayOpen;
     private readonly onKeyDown;
     private readonly onViewportChange;
+    /**
+     * Registered on `document` only while the tray is open, in the capture phase.
+     *
+     * <p>`event.target` is useless here: a click inside a shadow root retargets to the host by the
+     * time it reaches `document`. `composedPath()` is the only reliable cross-boundary test.
+     */
+    private readonly onDocumentPointerDown;
+    /** The tray is positioned from the bell's box, so it has to follow the bell. */
+    private readonly onTrayReflow;
     private readonly onPageHide;
     constructor(callbacks: PopupViewerCallbacks);
     setItems(items: WebPopupItem[]): void;
@@ -66,10 +85,21 @@ export declare class PopupViewer {
      */
     private ensureLauncherHost;
     /**
-     * @returns the integrator's chosen mount point, or null for the floating fallback.
+     * @returns the integrator's chosen mount point, or null when they have not marked one.
      */
     private resolveAnchor;
-    /** Places the launcher host under the current anchor, or under `body` when there is none. */
+    /**
+     * Places the launcher host inside the integrator's anchor, or detaches it when there is none.
+     *
+     * <p>There is no floating fallback. Parking a bell in the corner of someone else's page is a
+     * decision only they can make: it lands on their layout, competes with their own widgets, and
+     * appears without them having asked for it. So the launcher exists exactly where a tenant marked
+     * a slot for it, and nowhere else.
+     *
+     * <p>Popups still arrive and still auto-open without an anchor — only the persistent bell and its
+     * tray are withheld. The cost is that a popup the visitor closes has no way back until the next
+     * page load, unless the host app calls {@code openViewer} itself.
+     */
     private mountLauncher;
     /**
      * Follows the anchor for the life of the page. A one-shot query at init would almost always miss
@@ -81,33 +111,73 @@ export declare class PopupViewer {
      */
     private observeDom;
     /**
-     * Whether the launcher shows at all depends on where it lives — the two placements have opposite
-     * defaults, and that is deliberate.
+     * Draws the bell, but only where the tenant asked for one.
      *
-     * <p><b>Floating</b> shows only while something is unread. A permanent button parked over
-     * someone else's page with nothing behind it is clutter, so once the visitor has seen everything
-     * it disappears. The cost is real: a read-but-undismissed popup then has no way back for the rest
-     * of the session, short of the host app calling {@link PopupInbox.openViewer}.
+     * <p>With no anchor there is no launcher at all — see {@link mountLauncher} for why there is no
+     * corner fallback.
      *
-     * <p><b>Anchored</b> always shows. The tenant deliberately reserved a slot in their own header,
-     * so vacating it leaves a hole their layout collapses around — a flex or grid {@code gap} still
-     * applies to a zero-width item — and a header bell that vanishes reads as broken chrome rather
-     * than as tidiness. Persisting also restores the way back, so a popup closed by accident can be
-     * reopened.
+     * <p>Where there is an anchor the bell is permanent, including once everything has been read. The
+     * tenant reserved that slot, so vacating it leaves a hole their layout collapses around — a flex
+     * or grid {@code gap} still applies to a zero-width item — and chrome that disappears reads as
+     * broken rather than as tidy. Persisting is also what keeps a way back to a popup closed by
+     * accident.
      */
     private renderLauncher;
     /**
-     * Hiding is per page session and deliberately weaker than dismissing: it silences the launcher
-     * for a visitor who does not want it in the corner right now, but a genuinely new popup clears
-     * it again (see {@link notifyArrival}) because that is a new reason to be shown.
+     * The list of what is waiting, and the only way to move between popups.
+     *
+     * <p>It lives in the launcher's shadow root rather than the modal's because it has to track the
+     * bell, and {@link observeDom} re-parents that host into and out of the tenant's header on SPA
+     * route changes. In the modal's root it would need a permanent coordinate sync to follow.
+     *
+     * <p>Opening it is emphatically <em>not</em> opening a popup: no row here calls
+     * {@code POST /view}, and nothing marks a popup `VIEWED`. Seeing a title in a list is not reading
+     * the message, and conflating the two would make every campaign report a 100% open rate.
+     */
+    private toggleTray;
+    private openTray;
+    private closeTray;
+    /** Kept off {@link renderLauncher} so toggling the tray does not rebuild the bell. */
+    private syncLauncherExpanded;
+    private attachTrayListeners;
+    private detachTrayListeners;
+    private renderTray;
+    /**
+     * One row.
+     *
+     * <p>Everything interpolated here is tenant-authored — `previewText` is derived from their own
+     * popup body and routinely contains quotes and apostrophes, and `thumbnailUrl` is a free-text
+     * column — so the title, preview and time go through {@link escapeHtml} and the thumbnail through
+     * {@link sanitizeUrl}.
+     *
+     * <p>Each of the three optional parts is omitted rather than rendered blank when its data is
+     * missing. That covers both a new SDK talking to a backend without the fields and the tail of
+     * popups delivered before they existed.
      */
-    private launcherHidden;
-    private setLauncherHidden;
+    private rowMarkup;
+    /**
+     * Places the panel against the bell.
+     *
+     * <p>`position: fixed` with coordinates written here, rather than `absolute` inside the wrap:
+     * fixed descendants are not clipped by an ancestor's `overflow: hidden`, which is what a tenant's
+     * sticky header almost always has. It does not escape a `transform`ed ancestor — the same
+     * documented limit the modal already carries — so the anchor element must not sit inside one.
+     *
+     * <h3>Why a default decides and geometry only refines</h3>
+     * jsdom has no layout: every `getBoundingClientRect()` is zeroes. Geometry-first logic would read
+     * that as "there is room below" and be silently right in tests while being wrong for a bell in a
+     * footer or a bottom bar. Defaulting first means the untestable path is the *refinement*, never
+     * the rule.
+     */
+    private positionTray;
     /**
      * A popup arrived while the visitor was already on the page. Without this the only signal is a
-     * small badge appearing in a corner nobody is looking at, so shake the launcher and play a short
-     * chime. Callers suppress it for first load, cache restore and the auto-open path — see
+     * small badge appearing among header icons nobody is looking at, so shake the launcher and play a
+     * short chime. Callers suppress it for first load, cache restore and the auto-open path — see
      * `PopupInbox.refresh`.
+     *
+     * <p>Silent with no anchor: there is no bell to shake. The chime still plays, since it is the one
+     * signal that does not need a button to land on.
      */
     notifyArrival(): void;
     /**
@@ -132,7 +202,6 @@ export declare class PopupViewer {
     private applyVariantCss;
     private shell;
     private ctaMarkup;
-    private dotsMarkup;
     private isMobileViewport;
     /**
      * One delegated listener covers the chrome and the authored body alike, which is what lets an
@@ -152,29 +221,13 @@ export declare class PopupViewer {
      */
     private closeAfterFollowing;
     /**
-     * Moves the carousel by one, keeping the current popup on screen until the next one is ready.
-     *
-     * <p>This used to re-render the whole modal through {@link renderCurrent}, which tore the shell
-     * down to a loading placeholder before awaiting the content. Content is cached after its first
-     * fetch, so the await almost always resolved on the next microtask — but "almost always" still
-     * paints one frame of collapsed spinner, which is what read as a flicker. Loading first and
-     * swapping second means the visitor never sees an intermediate state.
-     */
-    private move;
-    /**
-     * Cross-slides the authored body, leaving the chrome untouched.
-     *
-     * <p>Only `.np-stage`'s children change, so the underbar, the chips and the dialog itself never
-     * re-render — the frame stays put while the content moves through it.
+     * The tray branch runs before the modal's `visible` guard, because the two surfaces are never open
+     * at once and Escape has to mean "close what is in front of me" for both.
      */
-    private swapBody;
-    /** Repoints the dots without rebuilding them, so the underbar never repaints mid-swipe. */
-    private syncDots;
-    private prefersReducedMotion;
     private handleKeyDown;
+    /** Roving focus between rows — the muscle memory the removed carousel arrows used to serve. */
+    private moveTrayFocus;
     /** Keeps keyboard focus inside the dialog while it is open. */
     private trapFocus;
     private focusDialog;
-    private handleTouchStart;
-    private handleTouchEnd;
 }