nexus-shared 4.0.0 → 4.1.0

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,6 +12,57 @@ 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");
 }
@@ -30,7 +81,10 @@ const homes = new WeakMap();
  * @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, "aria-describedby": ariaDescribedBy, 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.
@@ -61,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;
@@ -120,8 +181,12 @@ export function Popup({ open, onClose, onClosed, title, description, icon, varia
         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(() => {
@@ -130,6 +195,12 @@ export function Popup({ open, onClose, onClosed, title, description, icon, varia
             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`);
@@ -138,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.
@@ -234,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(() => {
@@ -319,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();
@@ -348,7 +443,8 @@ export function Popup({ open, onClose, onClosed, title, description, icon, varia
     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.
@@ -397,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": cx(description ? descriptionId : undefined, ariaDescribedBy) || undefined, onCancel: onCancel, onClose: onNativeClose, onPointerDown: onPointerDown, 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)) }));
+    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/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;