nexus-shared 3.2.0 → 4.1.0

package/dist/Components/Layouts/Popup.d.ts

@@ -40,6 +40,11 @@ export interface PopupProps {
     variant?: PopupVariant;
     /** Width: `xs` 360, `sm` 440, `md` 560 (default), `lg` 720, `xl` 960, or `full`. */
     size?: PopupSize;
+    /**
+     * Height, pixels or a CSS length: the body scrolls inside it. Default: as tall as the content, up to the window. A
+     * docked window is `32rem` tall by default, never taller than the window.
+     */
+    height?: number | string;
     /** Buttons at the end, right-aligned. */
     footer?: ReactNode;
     /** Shows the close button. Default true. */
@@ -50,8 +55,9 @@ export interface PopupProps {
     closeOnBackdrop?: boolean;
     /**
      * The minimize button: the popup steps aside to a bar at the bottom right, keeping everything typed in it, and the
-     * page can be used again. Default: when `closable`, since a popup that must be answered cannot be put aside.
-     * Needs `<PopupHost />`, which shows the bars.
+     * page can be used again. Default false: only a popup that asks has it. A CRUD page's Add and Edit forms and its row
+     * forms ask (a form put aside while the list behind it is read); message boxes, viewers, galleries, histories and
+     * the rest do not. Needs `<PopupHost />`, which shows the bars.
      */
     minimizable?: boolean;
     /** The maximize button, and a double-click on the title bar: the popup fills the window. Default true. */
@@ -66,27 +72,48 @@ export interface PopupProps {
     reopen?: PopupReopen;
     /** The window state, when the page controls it; pair it with `onWindowStateChange`. */
     windowState?: PopupWindowState;
+    /**
+     * A window that leaves the page usable: it opens without a backdrop at the bottom right, beside the other docked
+     * windows (the first on the right, each next one to its left; on a screen too narrow for two, over each other), the
+     * one last used on top. Esc inside it closes it, Tab leaves it for the page. A mail client's chat popups and compose
+     * window are docked. Minimize and maximize work as on any popup. Default false: a popup locks the page.
+     */
+    docked?: boolean;
+    /**
+     * A drawer: the window's whole height at its end edge (the right, in a left-to-right page), its width from `size`
+     * (all of it on a phone). Modal as any popup; it neither moves nor maximizes. A board's Add widget list is one.
+     */
+    drawer?: boolean;
     /** The window state each time the popup opens, when the page does not control it. Default `normal`. */
     defaultWindowState?: Exclude<PopupWindowState, "minimized">;
     /** When the buttons, a double-click on the title bar, a drag, or the minimized bar change the window state. */
     onWindowStateChange?: (state: PopupWindowState) => void;
     /** A body without padding, for tables and lists that reach the edges. */
     flush?: boolean;
-    /** A selector for the element that takes focus when the popup opens. Default: the first control in the body or footer. */
+    /**
+     * A selector for the element that takes focus when the popup opens. Default: an element of the body or footer marked
+     * `data-nx-focus` (with `tabIndex={-1}` when it is no control, such as a heading), else the first control there.
+     */
     initialFocus?: string;
     /** Name for screen readers when there is no title. */
     "aria-label"?: string;
+    /**
+     * Ids of elements inside the popup that describe it to screen readers, after its `description`: a message box names
+     * its message and its details, so they are read with the title as the focus enters.
+     */
+    "aria-describedby"?: string;
     className?: string;
     children?: ReactNode;
 }
 /**
- * A modal window on the native <dialog>, with the buttons of a desktop window: minimize, maximize, and close. It sits
- * in the top layer above everything, dims and locks the page behind it, traps Tab, closes with Esc or a click outside,
- * and returns focus to where it came from. The title bar moves it; a double-click there maximizes it. Minimized, it
+ * A modal window on the native <dialog>, with the buttons of a desktop window: maximize and close, and minimize when
+ * it asks (`minimizable`: a CRUD page's Add and Edit). It sits in the top layer above everything, dims and locks the
+ * page behind it, traps Tab, closes with Esc or a click outside, and returns focus to where it came from. The title
+ * bar moves it; a double-click there maximizes it. Minimized, it
  * waits as a bar at the bottom right with its content kept, while the page can be used. The body scrolls while the
  * title and the footer stay. The content mounts while the popup is open, so a form inside starts fresh every time.
  *
  * @example
  * <Popup open={open} onClose={() => setOpen(false)} title="Edit booking" footer={<Button variant="primary">Save</Button>}>…</Popup>
  */
-export declare function Popup({ open, onClose, onClosed, title, description, icon, variant, size, footer, closable, closeOnEscape, closeOnBackdrop, minimizable, maximizable, movable, reopen, windowState: windowStateProp, defaultWindowState, onWindowStateChange, flush, initialFocus, "aria-label": ariaLabel, className, children, }: PopupProps): import("react").JSX.Element;
+export declare function Popup({ open, onClose, onClosed, title, description, icon, variant, size, height, footer, closable, closeOnEscape, closeOnBackdrop, minimizable, maximizable: maximizableProp, movable: movableProp, reopen, docked, drawer, windowState: windowStateProp, defaultWindowState, onWindowStateChange, flush, initialFocus, "aria-label": ariaLabel, "aria-describedby": ariaDescribedBy, className, children, }: PopupProps): import("react").JSX.Element | null;

package/dist/Components/Layouts/Popup.js

@@ -2,7 +2,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { iconMinus, iconSquare, iconSquares, iconX, InlineIcon } from "nexus-icons";
 import { useContext, useEffect, useId, useLayoutEffect, useRef, useState } from "react";
-import { flushSync } from "react-dom";
+import { createPortal, flushSync } from "react-dom";
 import { afterAnimation, motionAllowed } from "../../Helpers/AnimationHelpers.js";
 import { cx } from "../../Helpers/ClassHelpers.js";
 import { cssVariablePosition, DRAG_CANCEL_SELECTOR, moveWithin, startDrag, viewportBounds } from "../../Helpers/DragHelpers.js";
@@ -12,22 +12,79 @@ const FOCUSABLE = 'a[href], button:not([disabled]), input:not([disabled]):not([t
 // Where a minimized popup flies to: the newest bar of the dock, at the bottom right.
 const DOCK_EDGE = 16;
 const DOCK_BAR = { width: 300, height: 44 };
+// Docked windows (`docked`), in the order they opened (each next one to the left of the one before), and in the order
+// they were last used (the last on top).
+const DOCKED_GAP = 12;
+let dockedOrder = [];
+let dockedStack = [];
+let dockedObserver = null;
+/** Lays the open docked windows out along the bottom edge, and stacks them by use. */
+function layoutDocked() {
+    const view = document.documentElement.clientWidth;
+    let right = DOCK_EDGE;
+    for (const dialog of dockedOrder) {
+        if (!dialog.open)
+            continue;
+        const width = dialog.offsetWidth;
+        // A window with no room left of the others stands at the right again, over them: the last used shows on top.
+        const fits = right + width + DOCK_EDGE <= view;
+        dialog.style.setProperty("--nx-docked-right", `${fits ? right : DOCK_EDGE}px`);
+        if (fits)
+            right += width + DOCKED_GAP;
+    }
+    dockedStack.forEach((dialog, index) => dialog.style.setProperty("--nx-docked-z", String(index + 1)));
+}
+function dockedJoin(dialog) {
+    if (!dockedOrder.includes(dialog))
+        dockedOrder = [...dockedOrder, dialog];
+    dockedRaise(dialog);
+    if (!dockedObserver) {
+        dockedObserver = new ResizeObserver(layoutDocked);
+        window.addEventListener("resize", layoutDocked);
+    }
+    dockedObserver.observe(dialog);
+    layoutDocked();
+}
+function dockedLeave(dialog) {
+    dockedOrder = dockedOrder.filter(one => one !== dialog);
+    dockedStack = dockedStack.filter(one => one !== dialog);
+    dockedObserver?.unobserve(dialog);
+    if (dockedOrder.length === 0 && dockedObserver) {
+        dockedObserver.disconnect();
+        dockedObserver = null;
+        window.removeEventListener("resize", layoutDocked);
+    }
+    layoutDocked();
+}
+/** The docked window last used comes on top of the others. */
+function dockedRaise(dialog) {
+    if (dockedStack[dockedStack.length - 1] === dialog)
+        return;
+    dockedStack = [...dockedStack.filter(one => one !== dialog), dialog];
+    layoutDocked();
+}
 function popupPosition(dialog) {
     return cssVariablePosition(dialog, "--nx-popup-x", "--nx-popup-y");
 }
 // Each popup's opener and the popup that held it, so focus can find its way back through popups that have gone.
 const openers = new WeakMap();
+// How each popup puts the focus inside itself (its `initialFocus`), for a popup closed over it that left the focus nowhere.
+const homes = new WeakMap();
 /**
- * A modal window on the native <dialog>, with the buttons of a desktop window: minimize, maximize, and close. It sits
- * in the top layer above everything, dims and locks the page behind it, traps Tab, closes with Esc or a click outside,
- * and returns focus to where it came from. The title bar moves it; a double-click there maximizes it. Minimized, it
+ * A modal window on the native <dialog>, with the buttons of a desktop window: maximize and close, and minimize when
+ * it asks (`minimizable`: a CRUD page's Add and Edit). It sits in the top layer above everything, dims and locks the
+ * page behind it, traps Tab, closes with Esc or a click outside, and returns focus to where it came from. The title
+ * bar moves it; a double-click there maximizes it. Minimized, it
  * waits as a bar at the bottom right with its content kept, while the page can be used. The body scrolls while the
  * title and the footer stay. The content mounts while the popup is open, so a form inside starts fresh every time.
  *
  * @example
  * <Popup open={open} onClose={() => setOpen(false)} title="Edit booking" footer={<Button variant="primary">Save</Button>}>…</Popup>
  */
-export function Popup({ open, onClose, onClosed, title, description, icon, variant = "window", size = "md", footer, closable = true, closeOnEscape = true, closeOnBackdrop = true, minimizable, maximizable = true, movable = true, reopen = "replace", windowState: windowStateProp, defaultWindowState = "normal", onWindowStateChange, flush = false, initialFocus, "aria-label": ariaLabel, className, children, }) {
+export function Popup({ open, onClose, onClosed, title, description, icon, variant = "window", size = "md", height, footer, closable = true, closeOnEscape = true, closeOnBackdrop = true, minimizable, maximizable: maximizableProp = true, movable: movableProp = true, reopen = "replace", docked = false, drawer = false, windowState: windowStateProp, defaultWindowState = "normal", onWindowStateChange, flush = false, initialFocus, "aria-label": ariaLabel, "aria-describedby": ariaDescribedBy, className, children, }) {
+    // A drawer stands at its edge: it neither moves nor maximizes.
+    const maximizable = maximizableProp && !drawer;
+    const movable = movableProp && !drawer;
     const id = useId();
     const dialogRef = useRef(null);
     // Content stays mounted through the exit animation, and while minimized.
@@ -41,7 +98,8 @@ export function Popup({ open, onClose, onClosed, title, description, icon, varia
     const maximized = windowState === "maximized";
     const dockReady = useDockReady();
     const hosted = useContext(HostedPopupContext);
-    const canMinimize = (minimizable ?? closable) && dockReady;
+    // Only a popup that asks: a CRUD page's Add and Edit, and its row forms.
+    const canMinimize = minimizable === true && dockReady;
     const downOnBackdropRef = useRef(false);
     // The element that opened the popup, where focus goes back when the browser has nowhere better.
     const openerRef = useRef(null);
@@ -57,6 +115,13 @@ export function Popup({ open, onClose, onClosed, title, description, icon, varia
     // The box before a maximize or a restore, for the animation between the two.
     const flipFromRef = useRef(null);
     const dockId = `nx-window${id}`;
+    // A docked window is drawn on the page's body, never inside what opened it: a scroller, a container or a transform
+    // there would carry it along or cut it off. Only once the page is in the browser, where a window can be opened.
+    const [portalReady, setPortalReady] = useState(false);
+    useEffect(() => {
+        if (docked)
+            setPortalReady(true);
+    }, [docked]);
     function changeWindowState(next) {
         if (next === latest.current.windowState)
             return;
@@ -65,19 +130,22 @@ export function Popup({ open, onClose, onClosed, title, description, icon, varia
         onWindowStateChange?.(next);
     }
     // The latest props and callbacks, for the dock bar and the drag, which outlive a render.
-    const latest = useRef({ windowState, defaultWindowState, reopen, title, icon, closable, ariaLabel, onClose, changeWindowState });
+    const latest = useRef({ windowState, defaultWindowState, reopen, title, description, icon, closable, ariaLabel, onClose, changeWindowState });
     useLayoutEffect(() => {
-        latest.current = { windowState, defaultWindowState, reopen, title, icon, closable, ariaLabel, onClose, changeWindowState };
+        latest.current = { windowState, defaultWindowState, reopen, title, description, icon, closable, ariaLabel, onClose, changeWindowState };
         if (!minimized)
             restoreToRef.current = windowState;
     });
     function dock() {
         const current = latest.current;
         dockedRef.current = true;
+        const label = typeof current.title === "string" ? current.title : current.ariaLabel;
         dockWindow({
             id: dockId,
             title: current.title ?? current.ariaLabel ?? "Window",
-            label: typeof current.title === "string" ? current.title : current.ariaLabel,
+            // Under the title, so two bars of one kind (two Edit forms, two Adds) read apart: the record, the place.
+            description: current.description,
+            label: label && typeof current.description === "string" ? `${label} · ${current.description}` : label,
             icon: current.icon,
             restore: () => latest.current.changeWindowState(restoreToRef.current),
             close: current.closable ? () => latest.current.onClose("close") : undefined,
@@ -102,12 +170,37 @@ export function Popup({ open, onClose, onClosed, title, description, icon, varia
             link = openers.get(link.within);
         if (link?.opener?.isConnected)
             link.opener.focus({ preventScroll: true });
+        // An opener that cannot take the focus - hidden in a menu that closed, disabled while its action runs - or none at
+        // all never leaves it on the page while another popup is still open: the popup now on top takes it, where it puts
+        // it on opening (a record's workspace: its chosen tab).
+        const now = document.activeElement;
+        if (now && now !== document.body && !dialog.contains(now))
+            return;
+        const below = Array.from(document.querySelectorAll("dialog.nx-popup")).filter(other => other !== dialog && other.open);
+        const top = below[below.length - 1];
+        if (top)
+            (homes.get(top) ?? (() => top.focus()))();
     }
+    // Where the focus starts: the asked-for element; else what the content marked as its start (`data-nx-focus`, such as a
+    // mail thread's subject, so a long read opens at its top and not on its first link or scroller); else the first control.
     function focusInside(dialog) {
-        const target = initialFocus ? dialog.querySelector(initialFocus) : dialog.querySelector(`:is(.nx-popup__body, .nx-popup__foot) :is(${FOCUSABLE})`);
+        const target = initialFocus
+            ? dialog.querySelector(initialFocus)
+            : (dialog.querySelector(":is(.nx-popup__body, .nx-popup__foot) [data-nx-focus]") ?? dialog.querySelector(`:is(.nx-popup__body, .nx-popup__foot) :is(${FOCUSABLE})`));
         (target ?? dialog).focus();
     }
+    useLayoutEffect(() => {
+        const dialog = dialogRef.current;
+        if (dialog)
+            homes.set(dialog, () => focusInside(dialog));
+    });
     function showDialog(dialog) {
+        // A docked window leaves the page as it is: no backdrop, no lock, laid out beside the others.
+        if (docked) {
+            dialog.show();
+            dockedJoin(dialog);
+            return;
+        }
         // The first modal locks the page; the space of its scrollbar is kept as padding, so nothing shifts.
         if (!document.querySelector(".nx-popup:modal"))
             document.documentElement.style.setProperty("--nx-scrollbar-gap", `${window.innerWidth - document.documentElement.clientWidth}px`);
@@ -116,6 +209,8 @@ export function Popup({ open, onClose, onClosed, title, description, icon, varia
     function closeDialog(dialog) {
         selfCloseRef.current = true;
         dialog.close();
+        if (docked)
+            layoutDocked();
         returnFocus();
     }
     // After the popup has closed: the content unmounts, and the next opening starts centered, in its default state.
@@ -212,7 +307,7 @@ export function Popup({ open, onClose, onClosed, title, description, icon, varia
                 focusInside(dialog);
         }
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [open, minimized]);
+    }, [open, minimized, portalReady]);
     // Closing: the exit animation plays, then the dialog closes and the content unmounts. Without the animation
     // (reduced motion), it closes in the same frame.
     useLayoutEffect(() => {
@@ -297,6 +392,28 @@ export function Popup({ open, onClose, onClosed, title, description, icon, varia
     useEffect(() => () => undock(), 
     // eslint-disable-next-line react-hooks/exhaustive-deps
     []);
+    // A docked window leaves the row of docked windows when it goes.
+    useEffect(() => {
+        const dialog = dialogRef.current;
+        if (!docked || !dialog)
+            return;
+        return () => dockedLeave(dialog);
+    }, [docked, portalReady]);
+    // Esc inside a docked window closes it: the browser asks only a modal one. A menu or a list inside that took the key
+    // first keeps it.
+    function onKeyDown(event) {
+        if (!docked || event.key !== "Escape" || event.defaultPrevented || closing)
+            return;
+        event.preventDefault();
+        if (closeOnEscape)
+            onClose("escape");
+    }
+    // The docked window used last comes on top.
+    function raise() {
+        const dialog = dialogRef.current;
+        if (docked && dialog)
+            dockedRaise(dialog);
+    }
     // Esc: the browser asks to close; the page decides through onClose.
     function onCancel(event) {
         event.preventDefault();
@@ -317,10 +434,17 @@ export function Popup({ open, onClose, onClosed, title, description, icon, varia
     function onPointerDown(event) {
         downOnBackdropRef.current = event.target === event.currentTarget;
     }
+    // A press outside a popup that stays open through it (`closeOnBackdrop: false`) leaves the focus where it was, as
+    // the press does nothing: a question's Confirm keeps it, so Enter still answers, and a field keeps its caret.
+    function onMouseDown(event) {
+        if (event.target === event.currentTarget && !closeOnBackdrop)
+            event.preventDefault();
+    }
     function onClick(event) {
         const onBackdrop = event.target === event.currentTarget && downOnBackdropRef.current;
         downOnBackdropRef.current = false;
-        if (onBackdrop && closeOnBackdrop && !closing)
+        // A docked window has no backdrop: a press on its own edge is not outside it.
+        if (onBackdrop && closeOnBackdrop && !closing && !docked)
             onClose("backdrop");
     }
     // A mouse click on minimize or maximize leaves focus in the field being typed in, as a desktop window's buttons do.
@@ -369,5 +493,11 @@ export function Popup({ open, onClose, onClosed, title, description, icon, varia
     const titleId = `${id}-title`;
     const descriptionId = `${id}-description`;
     const hasControls = canMinimize || maximizable || closable;
-    return (_jsx("dialog", { ref: dialogRef, className: cx("nx-popup", `nx-popup--${variant}`, `nx-popup--${size}`, flush && "nx-popup--flush", maximized && "nx-popup--maximized", movable && "nx-popup--movable", closing && "nx-popup--closing", className), "data-window-state": windowState, "aria-labelledby": title ? titleId : undefined, "aria-label": title ? undefined : ariaLabel, "aria-describedby": description ? descriptionId : undefined, onCancel: onCancel, onClose: onNativeClose, onPointerDown: onPointerDown, onClick: onClick, children: shown && (_jsxs(HostedPopupContext, { value: false, children: [(title || icon || hasControls) && (_jsxs("header", { className: "nx-popup__head", onPointerDown: onHeadPointerDown, onDoubleClick: onHeadDoubleClick, children: [icon && _jsx("span", { className: "nx-popup__icon", children: icon }), _jsxs("div", { className: "nx-popup__heading", children: [title && (_jsx("h2", { id: titleId, className: "nx-popup__title", children: title })), description && (_jsx("p", { id: descriptionId, className: "nx-popup__description", children: description }))] }), hasControls && (_jsxs("div", { className: "nx-popup__controls", children: [canMinimize && (_jsx("button", { type: "button", className: "nx-popup__control nx-popup__minimize", "aria-label": "Minimize", title: "Minimize", onMouseDown: keepFocus, onClick: () => changeWindowState("minimized"), children: _jsx(InlineIcon, { icon: iconMinus }) })), maximizable && (_jsx("button", { type: "button", className: "nx-popup__control nx-popup__maximize", "aria-label": maximized ? "Restore down" : "Maximize", title: maximized ? "Restore down" : "Maximize", onMouseDown: keepFocus, onClick: toggleMaximize, children: _jsx(InlineIcon, { icon: maximized ? iconSquares : iconSquare }) })), closable && (_jsx("button", { type: "button", className: "nx-popup__control nx-popup__close", "aria-label": "Close", title: "Close", onClick: () => onClose("close"), children: _jsx(InlineIcon, { icon: iconX }) }))] }))] })), _jsx("div", { className: "nx-popup__body", children: children }), footer && _jsx("footer", { className: "nx-popup__foot", children: footer })] }, round)) }));
+    const element = (_jsx("dialog", { ref: dialogRef, className: cx("nx-popup", `nx-popup--${variant}`, `nx-popup--${size}`, docked && "nx-popup--docked", drawer && "nx-popup--drawer", flush && "nx-popup--flush", maximized && "nx-popup--maximized", movable && "nx-popup--movable", closing && "nx-popup--closing", className), "data-window-state": windowState, style: height === undefined ? undefined : { "--nx-popup-height": typeof height === "number" ? `${height}px` : height }, "aria-labelledby": title ? titleId : undefined, "aria-label": title ? undefined : ariaLabel, "aria-describedby": cx(description ? descriptionId : undefined, ariaDescribedBy) || undefined, onCancel: onCancel, onClose: onNativeClose, onPointerDown: event => {
+            raise();
+            onPointerDown(event);
+        }, onFocus: raise, onKeyDown: onKeyDown, onMouseDown: onMouseDown, onClick: onClick, children: shown && (_jsxs(HostedPopupContext, { value: false, children: [(title || icon || hasControls) && (_jsxs("header", { className: "nx-popup__head", onPointerDown: onHeadPointerDown, onDoubleClick: onHeadDoubleClick, children: [icon && _jsx("span", { className: "nx-popup__icon", children: icon }), _jsxs("div", { className: "nx-popup__heading", children: [title && (_jsx("h2", { id: titleId, className: "nx-popup__title", children: title })), description && (_jsx("p", { id: descriptionId, className: "nx-popup__description", children: description }))] }), hasControls && (_jsxs("div", { className: "nx-popup__controls", children: [canMinimize && (_jsx("button", { type: "button", className: "nx-popup__control nx-popup__minimize", "aria-label": "Minimize", title: "Minimize", onMouseDown: keepFocus, onClick: () => changeWindowState("minimized"), children: _jsx(InlineIcon, { icon: iconMinus }) })), maximizable && (_jsx("button", { type: "button", className: "nx-popup__control nx-popup__maximize", "aria-label": maximized ? "Restore down" : "Maximize", title: maximized ? "Restore down" : "Maximize", onMouseDown: keepFocus, onClick: toggleMaximize, children: _jsx(InlineIcon, { icon: maximized ? iconSquares : iconSquare }) })), closable && (_jsx("button", { type: "button", className: "nx-popup__control nx-popup__close", "aria-label": "Close", title: "Close", onClick: () => onClose("close"), children: _jsx(InlineIcon, { icon: iconX }) }))] }))] })), _jsx("div", { className: "nx-popup__body", children: children }), footer && _jsx("footer", { className: "nx-popup__foot", children: footer })] }, round)) }));
+    if (!docked)
+        return element;
+    return portalReady ? createPortal(element, document.body) : null;
 }

package/dist/Components/Layouts/PopupDock.d.ts

@@ -3,7 +3,9 @@ import { type ReactNode } from "react";
 export interface DockedWindow {
     id: string;
     title: ReactNode;
-    /** Plain text of the title, for the tooltip. */
+    /** A second line under the title: the record or the place a window is about, so two of one kind read apart. */
+    description?: ReactNode;
+    /** Plain text of the title, and of the description, for the tooltip. */
     label?: string;
     /** The window's icon; a window icon when left out. */
     icon?: ReactNode;

package/dist/Components/Layouts/PopupDock.js

@@ -113,9 +113,10 @@ export function PopupDock() {
 function DockBar({ item, onRestore }) {
     const id = useId();
     const titleId = `${id}-title`;
+    const descriptionId = `${id}-description`;
     const closeId = `${id}-close`;
     return (_jsxs("li", { className: "nx-dock__item", children: [_jsxs("button", { type: "button", className: "nx-dock__window", title: item.label ? `Restore: ${item.label}` : "Restore", onClick: () => {
                     onRestore();
                     item.restore();
-                }, children: [_jsx("span", { className: "nx-dock__icon", "aria-hidden": "true", children: item.icon ?? _jsx(InlineIcon, { icon: iconAppWindow }) }), _jsx("span", { className: "nx-visually-hidden", children: "Restore " }), _jsx("span", { id: titleId, className: "nx-dock__title", children: item.title }), _jsx(InlineIcon, { className: "nx-dock__restore", icon: iconChevronUp })] }), item.close && (_jsxs("button", { type: "button", className: "nx-dock__close", "aria-labelledby": `${closeId} ${titleId}`, title: "Close", onClick: item.close, children: [_jsx("span", { id: closeId, hidden: true, children: "Close" }), _jsx(InlineIcon, { icon: iconX })] }))] }));
+                }, children: [_jsx("span", { className: "nx-dock__icon", "aria-hidden": "true", children: item.icon ?? _jsx(InlineIcon, { icon: iconAppWindow }) }), _jsx("span", { className: "nx-visually-hidden", children: "Restore " }), _jsxs("span", { className: "nx-dock__text", children: [_jsx("span", { id: titleId, className: "nx-dock__title", children: item.title }), item.description ? (_jsx("span", { id: descriptionId, className: "nx-dock__description", children: item.description })) : null] }), _jsx(InlineIcon, { className: "nx-dock__restore", icon: iconChevronUp })] }), item.close && (_jsxs("button", { type: "button", className: "nx-dock__close", "aria-labelledby": item.description ? `${closeId} ${titleId} ${descriptionId}` : `${closeId} ${titleId}`, title: "Close", onClick: item.close, children: [_jsx("span", { id: closeId, hidden: true, children: "Close" }), _jsx(InlineIcon, { icon: iconX })] }))] }));
 }

package/dist/Components/Layouts/PopupHost.js

@@ -3,6 +3,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useLayoutEffect, useSyncExternalStore } from "react";
 import { Popup } from "./Popup.js";
 import { HostedPopupContext } from "./PopupContext.js";
+import { PageLeaveGuardContext } from "../Forms/FormLeaveGuard.js";
 import { PopupDock } from "./PopupDock.js";
 import { withPopupRule } from "./PopupRules.js";
 const EMPTY = [];
@@ -156,8 +157,8 @@ export function PopupHost() {
         for (const entry of list)
             rendered.add(entry.id);
     });
-    return (_jsxs(HostedPopupContext, { value: true, children: [list.map(entry => {
-                const { content, footer, onClose: _onClose, beforeClose: _beforeClose, onWindowStateChange: _onWindowStateChange, key: _key, ...rest } = entry.options;
-                return (_jsx(Popup, { ...rest, open: entry.open, windowState: entry.windowState, onWindowStateChange: state => setWindowState(entry.id, state), footer: typeof footer === "function" ? footer(entry.handle) : footer, onClose: reason => requestClose(entry.id, reason), onClosed: () => removeEntry(entry.id), children: typeof content === "function" ? content(entry.handle) : content }, entry.id));
-            }), _jsx(PopupDock, {})] }));
+    return (_jsx(PageLeaveGuardContext, { value: null, children: _jsxs(HostedPopupContext, { value: true, children: [list.map(entry => {
+                    const { content, footer, onClose: _onClose, beforeClose: _beforeClose, onWindowStateChange: _onWindowStateChange, key: _key, ...rest } = entry.options;
+                    return (_jsx(Popup, { ...rest, open: entry.open, windowState: entry.windowState, onWindowStateChange: state => setWindowState(entry.id, state), footer: typeof footer === "function" ? footer(entry.handle) : footer, onClose: reason => requestClose(entry.id, reason), onClosed: () => removeEntry(entry.id), children: typeof content === "function" ? content(entry.handle) : content }, entry.id));
+                }), _jsx(PopupDock, {})] }) }));
 }

package/dist/Components/Messages/MailClient.d.ts

@@ -0,0 +1,50 @@
+import { type ReactNode } from "react";
+import { type MailClientView } from "../../Helpers/MailClientHelpers.ts";
+import type { ChatId, ChatSource } from "../../Interfaces/ChatInterfaces.ts";
+import type { MailDomain, MailInboxRow, MessageSource } from "../../Interfaces/MailInterfaces.ts";
+import type { MailDomainContext } from "./MailThread.tsx";
+export interface MailClientProps {
+    /** Where the mailbox's data comes from: one object for the page (the bell polls on it too). */
+    source: MessageSource;
+    /** Who is reading. */
+    userId: ChatId;
+    /**
+     * The bar's heading. Default "Message". `false` draws none, for a page whose own heading names the client (an admin
+     * page's title from its menu row): the search then starts the bar, and the page has one heading.
+     */
+    title?: ReactNode | false;
+    /** A sentence beside the title, clipped to the rail's width, the whole of it on hover: what a page's own heading would say. */
+    description?: ReactNode;
+    /** The title's heading level: 1 when the client takes the page's own title. Default 2. */
+    headingLevel?: 1 | 2 | 3;
+    /** The folder and type shown, when the page controls them (a URL); pair with `onViewChange`. */
+    view?: MailClientView;
+    /** The folder and type shown first, when the page does not control them. Default the Inbox, every type. */
+    defaultView?: MailClientView;
+    onViewChange?: (view: MailClientView) => void;
+    /**
+     * The conversation open in the pane, when the page controls it (`?thread=`); pair with `onThreadChange`. A chat named
+     * here (the bell's link, an e-mail copy's) opens its chat window too, as a click on its row does.
+     */
+    threadId?: ChatId | null;
+    onThreadChange?: (threadId: ChatId | null) => void;
+    /** At the end of the bar: the app's settings, a gear `Button` that links to its admin pages. */
+    settings?: ReactNode;
+    /** Conversations per page of the list. Default 50. */
+    pageSize?: number;
+    /** A chat's lines, when they do not come from the source's `threadSource`. */
+    chatSourceFor?: (row: MailInboxRow) => ChatSource;
+    /** Draws the record a mail is about. Default its `DomainCard`. */
+    renderDomain?: (domain: MailDomain, context: MailDomainContext) => ReactNode;
+    /**
+     * After anything that changes what is unread or where a conversation is - a read mark once the server answered it, a
+     * mark, an archive: a page's bell reads again (`refreshMessageUnread`). The client's own counts wait for every read
+     * mark on its way, so a page needs no wrapper of its own around the source for them.
+     */
+    onChanged?: () => void;
+    /** Milliseconds between quiet reads of the list and its counts while the page is in front. 0 turns it off. Default 60,000. */
+    pollInterval?: number;
+    className?: string;
+}
+/** A mailbox as a mail client: rail, list and reading pane, with chat popups and compose windows docked at the bottom right. */
+export declare function MailClient({ source, userId, title, description, headingLevel, view: viewProp, defaultView, onViewChange, threadId: threadProp, onThreadChange, settings, pageSize, chatSourceFor, renderDomain, onChanged, pollInterval, className, }: MailClientProps): import("react").JSX.Element;