@rapidmx/web-client 0.21.0 → 0.22.0

package/lib/components/navigation/BottomTabBar.tsx

@@ -0,0 +1,66 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React, { useEffect, useRef } from "react";
+import type { IconType } from "react-icons";
+
+/** A single icon-rail/bottom-tab entry — deliberately generic (not tied to `AppShell`'s own
+ * `AppDef`/`AppShellApp`) so both `AppShell` (www) and `AdminShell` (admin) can share this component
+ * for their own, differently-shaped nav item sets. */
+export interface NavItem {
+    id: string;
+    href: string;
+    label: string;
+    icon: IconType;
+}
+
+export interface BottomTabBarProps {
+    apps: NavItem[];
+    active: string;
+}
+
+/**
+ * The mobile counterpart to an icon rail (`AppShell`'s Mail/Calendar/Contacts/Tasks, or `AdminShell`'s
+ * Mailboxes/Quarantine/Ingest Queue) — same data, same full-page-nav `<a href>` links (this framework
+ * has no client-side router), just relocated to a fixed bottom bar instead of a persistent left rail,
+ * which doesn't fit below the `md` breakpoint. Only ever rendered alongside that rail (`md:hidden` here,
+ * `hidden md:flex` there) — never both hidden or both visible at once.
+ *
+ * A few items share the width equally; a long list (the admin console has ten or so) doesn't fit at a readable size, so each
+ * item keeps a minimum width, its label wraps onto a second line rather than running into its neighbour's, and the bar scrolls
+ * sideways - opening with the active item in view.
+ */
+export default function BottomTabBar({ apps, active }: BottomTabBarProps) {
+    const activeRef = useRef<HTMLAnchorElement | null>(null);
+    useEffect(() => {
+        const item = activeRef.current;
+        const bar = item?.parentElement;
+        if (item && bar && bar.scrollWidth > bar.clientWidth) {
+            // Set directly rather than `scrollIntoView()`, which would scroll the page as well.
+            bar.scrollLeft = item.offsetLeft - (bar.clientWidth - item.offsetWidth) / 2;
+        }
+    }, [active]);
+    return (
+        <nav
+            aria-label="Mobile navigation"
+            className="md:hidden fixed bottom-0 inset-x-0 z-30 h-14 bg-surface border-t border-border flex items-stretch overflow-x-auto overflow-y-hidden [scrollbar-width:none] [&::-webkit-scrollbar]:hidden"
+        >
+            {apps.map(({ id, href, label, icon: Icon }) => (
+                <a
+                    key={id}
+                    href={href}
+                    ref={id === active ? activeRef : undefined}
+                    aria-current={id === active ? "page" : undefined}
+                    className={[
+                        "flex-1 shrink-0 min-w-[4.75rem] px-1 flex flex-col items-center justify-center gap-0.5 text-[10px] leading-tight text-center font-medium",
+                        id === active ? "text-primary-dark" : "text-text-muted",
+                    ].join(" ")}
+                >
+                    <Icon size={20} aria-hidden="true" />
+                    {label}
+                </a>
+            ))}
+        </nav>
+    );
+}

package/lib/components/overlays/Drawer.tsx

@@ -0,0 +1,72 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React, { ReactNode, useRef } from "react";
+import { createPortal } from "react-dom";
+import { OverlayDepthContext, useOverlayDialog } from "./overlayStack.js";
+
+export interface DrawerProps {
+    open: boolean;
+    onClose: () => void;
+    title: string;
+    /** Which edge the drawer slides in from. Defaults to "left" (matches every current call site — a
+     * secondary sidebar or nav list). */
+    side?: "left" | "right";
+    /** Fill the whole window instead of a 18rem strip beside a dimmed page - what a phone's navigation drawer wants, where a sliver of the page behind
+     * it is only a mis-tap waiting to happen. The panel keeps the safe-area insets clear of a notch and the home indicator. Defaults to `false`. */
+    fullScreen?: boolean;
+    children: ReactNode;
+}
+
+/**
+ * An off-canvas panel for mobile, portal-rendered to `document.body` like `Modal.tsx` — same
+ * backdrop/focus-trap/Escape-key contract (shared via `overlayStack.ts`), just styled as a slide-in edge panel
+ * instead of a centered card. Used to hold a secondary sidebar's content below the `md` breakpoint,
+ * where it doesn't fit alongside the primary content.
+ */
+export default function Drawer({ open, onClose, title, side = "left", fullScreen = false, children }: DrawerProps) {
+    const dialogRef = useRef<HTMLDivElement>(null);
+    const childDepth = useOverlayDialog(open, dialogRef, onClose);
+
+    if (!open) {
+        return null;
+    }
+
+    return createPortal(
+        <div
+            className="fixed inset-0 bg-black/50 z-[1000]"
+            onMouseDown={(e) => e.target === e.currentTarget && onClose()}
+        >
+            <div
+                className={[
+                    fullScreen
+                        ? "fixed inset-0 w-full overflow-y-auto bg-surface p-5 pt-[max(1.25rem,env(safe-area-inset-top))] pb-[max(1.25rem,env(safe-area-inset-bottom))] focus:outline-none"
+                        : "fixed inset-y-0 w-72 max-w-[85vw] overflow-y-auto bg-surface border-border shadow-modal p-5 focus:outline-none",
+                    fullScreen ? "" : side === "left" ? "left-0 border-r" : "right-0 border-l",
+                ].join(" ")}
+                role="dialog"
+                aria-modal="true"
+                aria-label={title}
+                tabIndex={-1}
+                ref={dialogRef}
+            >
+                <div className="flex items-start justify-between gap-4 mb-5">
+                    <div className="text-xl font-bold tracking-tight">{title}</div>
+                    <button
+                        type="button"
+                        className="bg-transparent border-none text-text-muted text-2xl leading-none cursor-pointer p-0 hover:text-text"
+                        aria-label="Close"
+                        onClick={onClose}
+                    >
+                        &times;
+                    </button>
+                </div>
+                <div>
+                    <OverlayDepthContext.Provider value={childDepth}>{children}</OverlayDepthContext.Provider>
+                </div>
+            </div>
+        </div>,
+        document.body,
+    );
+}

package/lib/components/overlays/Modal.tsx

@@ -0,0 +1,64 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React, { ReactNode, useRef } from "react";
+import { createPortal } from "react-dom";
+import { OverlayDepthContext, useOverlayDialog } from "./overlayStack.js";
+
+export interface ModalProps {
+    open: boolean;
+    onClose: () => void;
+    title: string;
+    children: ReactNode;
+}
+
+/**
+ * A small, dependency-free modal dialog rendered via a portal to `document.body`. Controlled by the
+ * caller (`open` state lives in the parent, not here) so multiple call sites can share the same simple
+ * contract without each needing its own open/close plumbing.
+ *
+ * Focus moves into the dialog on open, Tab/Shift+Tab stay trapped inside it, and focus returns to the
+ * previously focused element on close. When overlays are stacked (Modal/Drawer), only the topmost one
+ * handles Escape and the focus trap - see `overlayStack.ts`.
+ */
+export default function Modal({ open, onClose, title, children }: ModalProps) {
+    const dialogRef = useRef<HTMLDivElement>(null);
+    const childDepth = useOverlayDialog(open, dialogRef, onClose);
+
+    if (!open) {
+        return null;
+    }
+
+    return createPortal(
+        <div
+            className="fixed inset-0 bg-black/50 flex items-center justify-center p-5 z-[1000]"
+            onMouseDown={(e) => e.target === e.currentTarget && onClose()}
+        >
+            <div
+                className="w-full max-w-[440px] max-h-[calc(100vh-2.5rem)] overflow-y-auto bg-surface border border-border rounded-md shadow-modal p-7 focus:outline-none"
+                role="dialog"
+                aria-modal="true"
+                aria-label={title}
+                tabIndex={-1}
+                ref={dialogRef}
+            >
+                <div className="flex items-start justify-between gap-4 mb-5">
+                    <div className="text-xl font-bold tracking-tight">{title}</div>
+                    <button
+                        type="button"
+                        className="bg-transparent border-none text-text-muted text-2xl leading-none cursor-pointer p-0 hover:text-text"
+                        aria-label="Close"
+                        onClick={onClose}
+                    >
+                        &times;
+                    </button>
+                </div>
+                <div>
+                    <OverlayDepthContext.Provider value={childDepth}>{children}</OverlayDepthContext.Provider>
+                </div>
+            </div>
+        </div>,
+        document.body,
+    );
+}

package/lib/components/overlays/PopoverPortal.tsx

@@ -0,0 +1,74 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React, { PropsWithChildren, RefObject, useEffect, useRef, useState } from "react";
+import { createPortal } from "react-dom";
+
+export interface PopoverPortalProps {
+    /** The button (or other element) this popover is anchored to — used both to position it and to
+     * exclude it from the outside-click-closes check (it already has its own toggle handler; without
+     * this exclusion, a click on the trigger while open would close-then-immediately-reopen, since
+     * `pointerdown` fires — and closes it — before the trigger's own `click` handler re-opens it). */
+    anchorRef: RefObject<HTMLElement | null>;
+    onClose: () => void;
+    width: number;
+    height: number;
+    "aria-label": string;
+}
+
+/**
+ * Renders its children into `document.body` (via a portal), `position: fixed` at a spot computed from
+ * `anchorRef`'s own rect — used by `EmojiPicker`/`GifPicker` so the popup escapes every ancestor's
+ * `overflow-hidden` (the Compose window's own outer frame, and `RichTextEditor`'s bordered wrapper
+ * both clip anything positioned merely `absolute` inside them, however high its `z-index` — clipping
+ * isn't a stacking-order problem `z-index` can override). Prefers opening *below* the anchor (there's
+ * more room in the editor area below the toolbar than above it, where the To/Cc/Subject rows are —
+ * confirmed directly: an earlier `absolute`+`overflow-hidden` version of this rendered the popup
+ * behind those rows), flipping to *above* only if there isn't enough room below.
+ */
+export default function PopoverPortal({ anchorRef, onClose, width, height, children, ...rest }: PropsWithChildren<PopoverPortalProps>) {
+    const containerRef = useRef<HTMLDivElement>(null);
+    const [style, setStyle] = useState<React.CSSProperties | null>(null);
+    // Read through a ref, like `overlayStack.ts`'s `onCloseRef`: callers (EmojiPicker/GifPicker) routinely pass
+    // `onClose` as a fresh inline function every render, and depending on it directly would remove/re-add the
+    // document listener on every parent re-render instead of just once on mount.
+    const onCloseRef = useRef(onClose);
+    onCloseRef.current = onClose;
+
+    useEffect(() => {
+        const rect = anchorRef.current?.getBoundingClientRect();
+        if (!rect) {
+            return;
+        }
+        const gap = 6;
+        const margin = 8;
+        const spaceBelow = window.innerHeight - rect.bottom;
+        const top = spaceBelow >= height + gap ? rect.bottom + gap : Math.max(margin, rect.top - height - gap);
+        const left = Math.min(Math.max(rect.left, margin), window.innerWidth - width - margin);
+        setStyle({ position: "fixed", top, left, width, height });
+    }, [anchorRef, height, width]);
+
+    useEffect(() => {
+        function handlePointerDown(e: PointerEvent) {
+            const target = e.target as Node;
+            if (containerRef.current?.contains(target) || anchorRef.current?.contains(target)) {
+                return;
+            }
+            onCloseRef.current();
+        }
+        document.addEventListener("pointerdown", handlePointerDown);
+        return () => document.removeEventListener("pointerdown", handlePointerDown);
+    }, [anchorRef]);
+
+    if (!style) {
+        return null;
+    }
+
+    return createPortal(
+        <div ref={containerRef} role="dialog" style={style} className="z-50 flex flex-col bg-surface border border-border rounded-md shadow-modal overflow-hidden" {...rest}>
+            {children}
+        </div>,
+        document.body,
+    );
+}

package/lib/components/overlays/overlayStack.ts

@@ -0,0 +1,165 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * The shared dialog behavior behind `Modal.tsx` and `Drawer.tsx`: a module-level stack of every open
+ * overlay, so that when overlays nest (a Modal opened from inside a Drawer, a confirm Modal on top of an
+ * edit Modal) only the *topmost* one reacts to Escape and traps Tab — pressing Escape once closes one
+ * layer, not every layer at once.
+ *
+ * One `keydown` listener on `document` is installed while the stack is non-empty and dispatches to the
+ * top entry only. A per-overlay listener that checked "am I on top?" wouldn't be enough: the top
+ * overlay's `onClose` only *schedules* a React state update, so a lower overlay's listener running later
+ * in the same dispatch would still see itself as not-on-top only by luck of ordering.
+ */
+import { RefObject, createContext, useContext, useEffect, useRef } from "react";
+
+interface OverlayEntry {
+    dialogRef: RefObject<HTMLElement | null>;
+    onEscape: () => void;
+    /** How many overlays enclose this one in the React tree (portals don't change React nesting). */
+    depth: number;
+    /** Which commit (see `push()`) pushed this entry - assigned by `push()`. */
+    commit?: number;
+}
+
+/**
+ * The nesting depth of the overlay rendering a subtree. Overlays wrap their children in a provider with
+ * the value `useOverlayDialog()` returns, so an overlay rendered inside another's children knows it
+ * belongs above it regardless of effect ordering - see `push()`.
+ */
+export const OverlayDepthContext = createContext(0);
+
+const stack: OverlayEntry[] = [];
+
+/** Everything natively tabbable - disabled controls, `tabindex="-1"`, and hidden inputs excluded. */
+const TABBABLE_SELECTOR = [
+    "a[href]",
+    "area[href]",
+    "button:not([disabled])",
+    "input:not([disabled]):not([type='hidden'])",
+    "select:not([disabled])",
+    "textarea:not([disabled])",
+    "iframe",
+    "audio[controls]",
+    "video[controls]",
+    "[contenteditable]:not([contenteditable='false'])",
+    "[tabindex]",
+].join(",");
+
+function tabbableElements(container: HTMLElement): HTMLElement[] {
+    return Array.from(container.querySelectorAll<HTMLElement>(TABBABLE_SELECTOR)).filter(
+        (el) => el.tabIndex >= 0 && !el.hasAttribute("inert") && !el.closest("[hidden]"),
+    );
+}
+
+function handleKeyDown(e: KeyboardEvent) {
+    const top = stack[stack.length - 1];
+    const dialog = top.dialogRef.current;
+    if (e.key === "Escape") {
+        top.onEscape();
+        return;
+    }
+    if (e.key !== "Tab" || !dialog) {
+        return;
+    }
+    const tabbable = tabbableElements(dialog);
+    const active = document.activeElement;
+    if (tabbable.length === 0) {
+        e.preventDefault();
+        dialog.focus();
+        return;
+    }
+    const first = tabbable[0];
+    const last = tabbable[tabbable.length - 1];
+    const outside = !dialog.contains(active);
+    if (e.shiftKey) {
+        if (outside || active === first || active === dialog) {
+            e.preventDefault();
+            last.focus();
+        }
+    } else if (outside || active === last) {
+        e.preventDefault();
+        first.focus();
+    }
+}
+
+/** Identifies the synchronous burst of effects (one React commit) an entry was pushed in: bumped in a
+ * microtask after the first push of a burst, so every push from the same commit shares one value. */
+let currentCommit = 0;
+let commitBumpScheduled = false;
+
+function push(entry: OverlayEntry) {
+    if (stack.length === 0) {
+        document.addEventListener("keydown", handleKeyDown);
+    }
+    if (!commitBumpScheduled) {
+        commitBumpScheduled = true;
+        queueMicrotask(() => {
+            commitBumpScheduled = false;
+            currentCommit++;
+        });
+    }
+    entry.commit = currentCommit;
+    // Normally just an append (the most recently opened overlay is on top). But React runs a child's
+    // effects before its parent's, so when a nested overlay mounts already-open in the same commit as the
+    // overlay containing it, the child is pushed first and would end up *under* its own container - so an
+    // entry goes below deeper entries pushed *in the same commit* (its not-yet-stacked children). A deeper
+    // entry from an earlier commit stays below it: an overlay opened later is on top regardless of depth
+    // (e.g. a top-level confirm opened while a nested Drawer > Modal is already showing).
+    let index = stack.length;
+    while (index > 0 && stack[index - 1].depth > entry.depth && stack[index - 1].commit === entry.commit) {
+        index--;
+    }
+    stack.splice(index, 0, entry);
+}
+
+function remove(entry: OverlayEntry) {
+    stack.splice(stack.indexOf(entry), 1);
+    if (stack.length === 0) {
+        document.removeEventListener("keydown", handleKeyDown);
+    }
+}
+
+/**
+ * Wires one open overlay into the stack: on open, remembers the previously focused element and moves
+ * focus into `dialogRef`'s element; while open *and topmost*, Escape calls `onClose` and Tab/Shift+Tab
+ * cycle focus within the dialog; on close/unmount, leaves the stack and restores focus to whatever had it
+ * before opening (when that's still an `HTMLElement`).
+ *
+ * `onClose` is read through a ref: callers routinely pass it as a fresh inline function every render, and
+ * depending on it directly would re-run the effect - re-stealing focus into the dialog - on every parent
+ * re-render (e.g. every keystroke in a field inside the dialog).
+ *
+ * Returns the depth to provide to the overlay's children via `OverlayDepthContext`.
+ */
+export function useOverlayDialog(open: boolean, dialogRef: RefObject<HTMLElement | null>, onClose: () => void): number {
+    const depth = useContext(OverlayDepthContext);
+    const onCloseRef = useRef(onClose);
+    onCloseRef.current = onClose;
+
+    useEffect(() => {
+        if (!open) return;
+
+        // Remember what had focus before the overlay opened so it can be restored on close (e.g. the
+        // "+ Add" button that triggered it), then move focus into the dialog itself.
+        const trigger = document.activeElement;
+        const entry: OverlayEntry = { dialogRef, onEscape: () => onCloseRef.current(), depth };
+        push(entry);
+        // An overlay that mounted open underneath an already-open nested one (see `push()`) must not
+        // steal focus from the overlay above it.
+        if (stack[stack.length - 1] === entry) {
+            dialogRef.current?.focus();
+        }
+
+        return () => {
+            remove(entry);
+            if (trigger instanceof HTMLElement) {
+                trigger.focus();
+            }
+        };
+    }, [open]);
+
+    return depth + 1;
+}

package/lib/components/pickers/MiniDatePicker.tsx

@@ -0,0 +1,90 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React, { useState } from "react";
+import { addMonths, eachDayOfInterval, endOfMonth, endOfWeek, format, isSameDay, isSameMonth, isToday, startOfMonth, startOfWeek } from "date-fns";
+
+export interface MiniDatePickerProps {
+    /** The main view's current date — determines both the month shown and which day is highlighted. */
+    selected: Date;
+    onSelect: (date: Date) => void;
+}
+
+const WEEKDAY_LABELS = ["M", "T", "W", "T", "F", "S", "S"];
+
+/** A compact month-grid date picker for the Calendar sidebar, reusing `MonthView`'s own grid-generation
+ * approach (`date-fns`'s `startOfWeek`/`endOfWeek`/`eachDayOfInterval`, Monday-start) rather than
+ * re-deriving it — this component just renders that same grid far smaller and without any event data.
+ * Its own displayed month tracks `selected` (so navigating the main view keeps this in sync) but can
+ * also be paged independently via the arrows without moving the main view until a day is actually
+ * clicked. */
+export default function MiniDatePicker({ selected, onSelect }: MiniDatePickerProps) {
+    const [shownMonth, setShownMonth] = useState(() => startOfMonth(selected));
+    // Tracks the last `selected` month this picker synced to, in the standard React
+    // "adjust state during render" shape — resyncs `shownMonth` whenever the caller's selected date
+    // moves to a different month (e.g. via the main view's own Previous/Next/Today controls), but
+    // otherwise leaves it alone so paging this picker's own arrows isn't immediately undone.
+    const [trackedSelectedMonth, setTrackedSelectedMonth] = useState(() => startOfMonth(selected));
+    if (!isSameMonth(trackedSelectedMonth, selected)) {
+        setTrackedSelectedMonth(startOfMonth(selected));
+        setShownMonth(startOfMonth(selected));
+    }
+
+    const gridStart = startOfWeek(startOfMonth(shownMonth), { weekStartsOn: 1 });
+    const gridEnd = endOfWeek(endOfMonth(shownMonth), { weekStartsOn: 1 });
+    const days = eachDayOfInterval({ start: gridStart, end: gridEnd });
+
+    return (
+        <nav aria-label="Mini calendar" className="p-2">
+            <div className="flex items-center justify-between mb-1.5">
+                <button
+                    type="button"
+                    aria-label="Previous month"
+                    onClick={() => setShownMonth((m) => addMonths(m, -1))}
+                    className="w-6 h-6 text-xs rounded-sm hover:bg-surface-alt"
+                >
+                    &lsaquo;
+                </button>
+                <span className="text-xs font-semibold">{format(shownMonth, "MMMM yyyy")}</span>
+                <button
+                    type="button"
+                    aria-label="Next month"
+                    onClick={() => setShownMonth((m) => addMonths(m, 1))}
+                    className="w-6 h-6 text-xs rounded-sm hover:bg-surface-alt"
+                >
+                    &rsaquo;
+                </button>
+            </div>
+            <div className="grid grid-cols-7 gap-0.5">
+                {WEEKDAY_LABELS.map((label, i) => (
+                    <div key={i} className="text-[10px] text-text-muted text-center">
+                        {label}
+                    </div>
+                ))}
+                {days.map((day) => (
+                    <button
+                        key={day.toISOString()}
+                        type="button"
+                        onClick={() => {
+                            onSelect(day);
+                            setShownMonth(startOfMonth(day));
+                        }}
+                        className={[
+                            "text-[11px] w-6 h-6 rounded-full flex items-center justify-center mx-auto",
+                            isSameDay(day, selected)
+                                ? "bg-primary text-white"
+                                : isToday(day)
+                                  ? "text-primary-dark font-semibold"
+                                  : isSameMonth(day, shownMonth)
+                                    ? "text-text hover:bg-surface-alt"
+                                    : "text-text-muted/50 hover:bg-surface-alt",
+                        ].join(" ")}
+                    >
+                        {format(day, "d")}
+                    </button>
+                ))}
+            </div>
+        </nav>
+    );
+}