@rapidmx/web-client 0.21.0 → 0.23.0

package/dist/lib/calendar/recurrence.js

@@ -0,0 +1,225 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * RFC5545 recurrence expansion, entirely client-side — `@rapidmx/restapi` stores/returns
+ * `RecurrenceRule` as-is and does no expansion of its own (see `calendarApi.ts`'s own header
+ * comment). Built on the `rrule` package.
+ */
+// `rrule` ships a real ESM build (resolved by the client bundler via its own module graph, where
+// named imports work normally) alongside a separate CJS build with no `"exports"` map (resolved by
+// this framework's *server-side* render path via Node's own loader, which falls back to the CJS
+// build since "module" is a bundler-only convention Node itself doesn't honor). Node's static
+// named-export detection for that CJS build doesn't pick up `RRule` (confirmed directly: SSR-ing the
+// calendar page threw "does not provide an export named 'RRule'"), so a plain named import breaks
+// under SSR even though it works in the browser. A namespace import sidesteps the static check
+// entirely; reading `.default` afterward reaches the same class via Node's CJS interop (`default`
+// always aliases `module.exports` for a CJS module) without disturbing the ESM path, where `.default`
+// simply doesn't exist and the direct named property is used instead.
+import * as RRuleNS from "rrule";
+/** Extracted so the CJS-interop fallback branch can be exercised directly with a plain object,
+ * without needing to fight a module mock into reproducing Node's exact interop shape. */
+export function resolveRRuleExport(ns) {
+    return ns.RRule ?? ns.default.RRule;
+}
+const RRule = resolveRRuleExport(RRuleNS);
+const FREQ_MAP = {
+    yearly: RRule.YEARLY,
+    monthly: RRule.MONTHLY,
+    weekly: RRule.WEEKLY,
+    daily: RRule.DAILY,
+};
+// `RRule`'s own `.toText()` formatter requires actual `Weekday` instances in `byweekday` — passing the
+// raw two-letter strings works for occurrence expansion (`.between()`) but throws inside `.toText()`
+// (confirmed by reproducing it directly against this exact package version).
+const WEEKDAY_OBJECT = {
+    MO: RRule.MO,
+    TU: RRule.TU,
+    WE: RRule.WE,
+    TH: RRule.TH,
+    FR: RRule.FR,
+    SA: RRule.SA,
+    SU: RRule.SU,
+};
+function createRRule(rule, dtstart, until, tzid) {
+    return new RRule({
+        freq: FREQ_MAP[rule.freq],
+        interval: rule.interval,
+        dtstart,
+        tzid,
+        byweekday: rule.byDay?.map((code) => WEEKDAY_OBJECT[code]),
+        bymonthday: rule.byMonthDay,
+        bymonth: rule.byMonth,
+        count: rule.count,
+        until,
+    });
+}
+/**
+ * Builds an `RRule` instance from this app's `RecurrenceRule` shape, anchored at `dtstart`. Pass the
+ * event's IANA `tzid` so the rule carries it (e.g. `DTSTART;TZID=America/New_York:...` from
+ * `.toString()`) — note that, per `rrule`'s own convention, a rule with a non-UTC `tzid` expects
+ * `dtstart` to be a "floating" wall-clock time expressed as a UTC `Date` and rezones its generated
+ * dates using the *runtime's* local zone, which is why `expandOccurrences()` below does its own
+ * timezone conversion instead of relying on this.
+ */
+export function buildRRule(rule, dtstart, tzid) {
+    return createRRule(rule, dtstart, rule.until ? new Date(rule.until) : null, tzid ?? null);
+}
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+function positiveMs(ms) {
+    return ((ms % 1000) + 1000) % 1000;
+}
+/** The runtime's own local zone — used for a "floating" event with no (or an unrecognized) timezone. */
+const LOCAL_ZONE = {
+    toWall(instantMs) {
+        const d = new Date(instantMs);
+        return Date.UTC(d.getFullYear(), d.getMonth(), d.getDate(), d.getHours(), d.getMinutes(), d.getSeconds(), d.getMilliseconds());
+    },
+    fromWall(wallMs) {
+        const w = new Date(wallMs);
+        return new Date(w.getUTCFullYear(), w.getUTCMonth(), w.getUTCDate(), w.getUTCHours(), w.getUTCMinutes(), w.getUTCSeconds(), w.getUTCMilliseconds()).getTime();
+    },
+};
+/** UTC itself - used for all-day events, whose dates are stored as UTC midnight (date-only values). */
+const UTC_ZONE = {
+    toWall: (instantMs) => instantMs,
+    fromWall: (wallMs) => wallMs,
+};
+function ianaZone(formatter) {
+    const toWall = (instantMs) => {
+        const fields = {};
+        for (const part of formatter.formatToParts(new Date(instantMs))) {
+            fields[part.type] = Number(part.value);
+        }
+        // `% 24`: some engines render midnight as hour "24" even with `hourCycle: "h23"`.
+        return Date.UTC(fields.year, fields.month - 1, fields.day, fields.hour % 24, fields.minute, fields.second, positiveMs(instantMs));
+    };
+    return {
+        toWall,
+        // RFC 5545 §3.3.5 resolution against the offsets in effect a day before and a day after (zones
+        // change offset at most once in that window): an ambiguous (fall-back) wall time resolves to its
+        // first occurrence (the earlier instant); a nonexistent (spring-forward) one is interpreted with
+        // the offset from *before* the transition, so 02:30 on a US spring-forward day becomes 03:30 EDT.
+        fromWall(wallMs) {
+            const offsetBefore = toWall(wallMs - MS_PER_DAY) - (wallMs - MS_PER_DAY);
+            const offsetAfter = toWall(wallMs + MS_PER_DAY) - (wallMs + MS_PER_DAY);
+            const valid = [wallMs - offsetBefore, wallMs - offsetAfter].filter((instant) => toWall(instant) === wallMs);
+            return valid.length > 0 ? Math.min(...valid) : wallMs - offsetBefore;
+        },
+    };
+}
+const zoneCache = new Map();
+/** Resolves `timezone` (an IANA zone id) to a converter, falling back to the runtime's local zone when
+ * it's empty or not a zone `Intl` recognizes. */
+function resolveZone(timezone) {
+    const key = timezone ?? "";
+    let zone = zoneCache.get(key);
+    if (!zone) {
+        try {
+            zone = key
+                ? ianaZone(new Intl.DateTimeFormat("en-US", {
+                    timeZone: key,
+                    hourCycle: "h23",
+                    year: "numeric",
+                    month: "2-digit",
+                    day: "2-digit",
+                    hour: "2-digit",
+                    minute: "2-digit",
+                    second: "2-digit",
+                }))
+                : LOCAL_ZONE;
+        }
+        catch {
+            zone = LOCAL_ZONE;
+        }
+        zoneCache.set(key, zone);
+    }
+    return zone;
+}
+/**
+ * Converts an instant to the "wall-clock as UTC" milliseconds recurrence expansion works in for an event
+ * with this `timezone`/`allDay` - UTC for an all-day event (stored as UTC-midnight dates), the event's IANA
+ * zone otherwise (the runtime's local zone when empty or unrecognized). Exported for `calendarMutations.ts`,
+ * which shifts a series' exception dates by the same wall-clock delta as its start.
+ */
+export function toEventWallClock(instantMs, timezone, allDay) {
+    return (allDay ? UTC_ZONE : resolveZone(timezone)).toWall(instantMs);
+}
+/** Inverse of `toEventWallClock()` (DST gaps/overlaps resolved per RFC 5545 - see `ianaZone()`). */
+export function fromEventWallClock(wallMs, timezone, allDay) {
+    return (allDay ? UTC_ZONE : resolveZone(timezone)).fromWall(wallMs);
+}
+/**
+ * Expands `event` into every occurrence whose interval overlaps `[rangeStart, rangeEnd]`. A
+ * non-recurring event yields itself (in a one-element array) if it overlaps, or `[]` otherwise —
+ * callers don't need to special-case recurring vs. not.
+ *
+ * Recurrence is expanded in the event's own `timezone` (an IANA zone id; an empty or unrecognized
+ * value falls back to the runtime's local zone, i.e. floating time), so every occurrence keeps the
+ * master's local wall-clock start/end time and local weekday — a weekly Monday 23:00
+ * America/New_York event stays on Monday 23:00 New York time across DST changes, rather than being
+ * expanded on the UTC weekday/time of its first instance. An all-day event is the exception: its dates are
+ * UTC-midnight date-only values, so it expands in UTC regardless of `timezone` - expanding a
+ * `2026-09-14T00:00Z` Monday in America/New_York would otherwise see a Sunday-evening start and put every
+ * occurrence on the wrong date. A timed occurrence that falls in a DST gap starts at the pre-transition
+ * offset (RFC 5545) and keeps its wall-clock duration.
+ */
+export function expandOccurrences(event, rangeStart, rangeEnd) {
+    const start = new Date(event.startDate);
+    const end = new Date(event.endDate);
+    if (!event.recurrenceRule) {
+        const overlaps = start < rangeEnd && end > rangeStart;
+        return overlaps ? [{ ...event, occurrenceKey: event.uid, isRecurringOccurrence: false }] : [];
+    }
+    const zone = event.allDay ? UTC_ZONE : resolveZone(event.timezone);
+    const startWall = zone.toWall(start.getTime());
+    // The duration in wall-clock terms, so an occurrence also keeps its local end time across DST.
+    const wallDurationMs = zone.toWall(end.getTime()) - startWall;
+    const { until } = event.recurrenceRule;
+    const rule = createRRule(event.recurrenceRule, new Date(startWall), until ? new Date(zone.toWall(new Date(until).getTime())) : null, null);
+    // Query in the wall-clock frame, widened by one occurrence's duration (so an occurrence that started
+    // before `rangeStart` but is still in progress isn't missed) plus a day on each side to absorb the
+    // zone's offset; the exact instant-based overlap filter at the end trims the excess.
+    const queryStart = new Date(zone.toWall(rangeStart.getTime()) - wallDurationMs - MS_PER_DAY);
+    const queryEnd = new Date(zone.toWall(rangeEnd.getTime()) + MS_PER_DAY);
+    const occurrenceStarts = rule
+        .between(queryStart, queryEnd, true)
+        .map((occWall) => ({ start: new Date(zone.fromWall(occWall.getTime())), wall: occWall.getTime() }));
+    const exceptions = new Set(event.recurrenceRule.exceptions.map((d) => new Date(d).getTime()));
+    return occurrenceStarts
+        .filter((occ) => !exceptions.has(occ.start.getTime()))
+        .map(({ start: occStart, wall }) => {
+        // Non-zero only when the start fell in a DST gap and was pushed forward - the end moves with it.
+        const gapShiftMs = zone.toWall(occStart.getTime()) - wall;
+        const occEnd = new Date(zone.fromWall(wall + gapShiftMs + wallDurationMs));
+        return {
+            ...event,
+            startDate: occStart.toISOString(),
+            endDate: occEnd.toISOString(),
+            recurrenceId: occStart.toISOString(),
+            occurrenceKey: `${event.uid}::${occStart.toISOString()}`,
+            isRecurringOccurrence: true,
+        };
+    })
+        .filter((occ) => new Date(occ.startDate) < rangeEnd && new Date(occ.endDate) > rangeStart);
+}
+/** Expands every event in `events` and flattens the result — the usual entry point for a grid view. */
+export function expandAllOccurrences(events, rangeStart, rangeEnd) {
+    return events.flatMap((event) => expandOccurrences(event, rangeStart, rangeEnd));
+}
+/** A human-readable summary of `rule` (e.g. "every 2 weeks on Monday, Wednesday until Jan 1, 2027"). */
+export function describeRecurrence(rule) {
+    const rrule = buildRRule(rule, new Date());
+    return rrule.toText();
+}
+export const WEEKDAY_CODES = ["MO", "TU", "WE", "TH", "FR", "SA", "SU"];
+export const WEEKDAY_LABELS = {
+    MO: "Mon",
+    TU: "Tue",
+    WE: "Wed",
+    TH: "Thu",
+    FR: "Fri",
+    SA: "Sat",
+    SU: "Sun",
+};

package/dist/lib/components/avatar/ContactAvatar.d.ts

@@ -0,0 +1,8 @@
+import React from "react";
+export interface ContactAvatarProps {
+    displayName: string;
+    size?: number;
+}
+/** A small circular initials avatar for a contact, matching Outlook People's list-row avatars — deterministic
+ * per name (same contact always gets the same color/initials), no photo-upload dependency. */
+export default function ContactAvatar({ displayName, size }: ContactAvatarProps): React.JSX.Element;

package/dist/lib/components/avatar/ContactAvatar.js

@@ -0,0 +1,26 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/** A fixed palette of background colors, cycled by a hash of the contact's name — no photo upload feature
+ * exists yet (`Contact.photoBlobKey` is modeled server-side but nothing in this app sets/reads it), so every
+ * contact gets one of these deterministically rather than a plain generic gray circle for everyone. */
+const PALETTE = ["#7c3aed", "#2563eb", "#0891b2", "#059669", "#d97706", "#dc2626", "#db2777", "#4f46e5"];
+function initialsOf(displayName) {
+    const parts = displayName.trim().split(/\s+/).filter(Boolean);
+    if (parts.length === 0) {
+        return "?";
+    }
+    const first = parts[0][0];
+    const last = parts.length > 1 ? parts[parts.length - 1][0] : "";
+    return (first + last).toUpperCase();
+}
+function colorOf(displayName) {
+    let hash = 0;
+    for (let i = 0; i < displayName.length; i++) {
+        hash = (hash * 31 + displayName.charCodeAt(i)) | 0;
+    }
+    return PALETTE[Math.abs(hash) % PALETTE.length];
+}
+/** A small circular initials avatar for a contact, matching Outlook People's list-row avatars — deterministic
+ * per name (same contact always gets the same color/initials), no photo-upload dependency. */
+export default function ContactAvatar({ displayName, size = 32 }) {
+    return (_jsx("span", { "aria-hidden": "true", style: { width: size, height: size, backgroundColor: colorOf(displayName), fontSize: size * 0.4 }, className: "inline-flex items-center justify-center rounded-full text-white font-semibold shrink-0", children: initialsOf(displayName) }));
+}

package/dist/lib/components/buttons/Button.d.ts

@@ -0,0 +1,9 @@
+import React, { ButtonHTMLAttributes } from "react";
+export type ButtonVariant = "primary" | "secondary" | "text";
+export interface ButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "className"> {
+    variant?: ButtonVariant;
+    /** Renders a small spinner before the button's content. */
+    loading?: boolean;
+    className?: string;
+}
+export default function Button({ variant, loading, className, children, ...rest }: ButtonProps): React.JSX.Element;

package/dist/lib/components/buttons/Button.js

@@ -0,0 +1,14 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const BASE = "inline-flex items-center justify-center gap-2 font-semibold text-sm rounded-sm border transition-colors disabled:opacity-55 disabled:cursor-not-allowed active:translate-y-px";
+/** Primary is gold (the brand's action color, per the style guide's "gold gradient fill" convention);
+ * secondary/text hover accents follow the guide's "turning gold on hover" rule too. Teal (`primary`
+ * the color token, confusingly named the same as this `primary` variant) stays reserved for
+ * structural/navigational chrome — active nav items, links, focus rings — not call-to-action buttons. */
+const VARIANTS = {
+    primary: "w-full py-2.5 px-4 bg-gradient-to-b from-accent-soft to-accent border-transparent text-text-on-accent hover:not-disabled:from-accent hover:not-disabled:to-accent-dark",
+    secondary: "w-full py-2.5 px-4 bg-transparent border-border text-text hover:not-disabled:border-accent hover:not-disabled:text-accent-dark",
+    text: "w-auto py-1 px-0.5 border-transparent bg-transparent text-accent-dark hover:not-disabled:underline",
+};
+export default function Button({ variant = "primary", loading, className, children, ...rest }) {
+    return (_jsxs("button", { className: [BASE, VARIANTS[variant], className].filter(Boolean).join(" "), ...rest, children: [loading && (_jsx("span", { className: "w-4 h-4 rounded-full border-2 border-current/30 border-t-current animate-spin" })), children] }));
+}

package/dist/lib/components/buttons/CopyButton.d.ts

@@ -0,0 +1,18 @@
+import React, { ReactNode } from "react";
+export interface CopyButtonProps {
+    /** The text put on the clipboard. */
+    value: string;
+    /** The button's accessible name - say what is copied, e.g. "Copy value for the SPF record". */
+    label: string;
+    /** The visible caption. Defaults to "Copy". */
+    children?: ReactNode;
+    className?: string;
+}
+/**
+ * A small "Copy" button for a value someone has to paste elsewhere (a DNS record, a code). Copies through
+ * `copyTextToClipboard()` - the async Clipboard API, then a hidden-textarea `execCommand` fallback - and
+ * announces the result next to the button in a polite live region ("Copied", or "Couldn't copy" when both
+ * routes fail, in which case the value is still on screen to select by hand). The live region is always
+ * rendered, empty until there is something to say, so screen readers pick the change up.
+ */
+export default function CopyButton({ value, label, children, className }: CopyButtonProps): React.JSX.Element;

package/dist/lib/components/buttons/CopyButton.js

@@ -0,0 +1,14 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import useCopyToClipboard from "../../util/useCopyToClipboard.js";
+import Button from "./Button.js";
+/**
+ * A small "Copy" button for a value someone has to paste elsewhere (a DNS record, a code). Copies through
+ * `copyTextToClipboard()` - the async Clipboard API, then a hidden-textarea `execCommand` fallback - and
+ * announces the result next to the button in a polite live region ("Copied", or "Couldn't copy" when both
+ * routes fail, in which case the value is still on screen to select by hand). The live region is always
+ * rendered, empty until there is something to say, so screen readers pick the change up.
+ */
+export default function CopyButton({ value, label, children = "Copy", className }) {
+    const { status, copy } = useCopyToClipboard();
+    return (_jsxs("span", { className: "inline-flex items-center gap-2 shrink-0", children: [_jsx(Button, { type: "button", variant: "secondary", "aria-label": label, className: ["!w-auto !py-1 !px-2 text-xs", className].filter(Boolean).join(" "), onClick: () => void copy(value), children: children }), _jsx("span", { role: "status", "aria-live": "polite", className: status === "failed" ? "text-xs text-danger" : "text-xs text-success", children: status === "copied" ? "Copied" : status === "failed" ? "Couldn’t copy" : "" })] }));
+}

package/dist/lib/components/feedback/Alert.d.ts

@@ -0,0 +1,4 @@
+import React, { ReactNode } from "react";
+export default function Alert({ children }: {
+    children: ReactNode;
+}): React.JSX.Element;

package/dist/lib/components/feedback/Alert.js

@@ -0,0 +1,4 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+export default function Alert({ children }) {
+    return (_jsx("div", { className: "flex gap-2 items-start py-3 px-3.5 rounded-sm text-sm mb-5 bg-danger-bg text-danger", role: "alert", children: children }));
+}

package/dist/lib/components/feedback/Skeleton.d.ts

@@ -0,0 +1,21 @@
+import React from "react";
+export interface SkeletonProps {
+    /** Tailwind width class, e.g. `"w-32"` or `"w-full"`. Defaults to full width. */
+    width?: string;
+    /** Tailwind height class, e.g. `"h-4"`. Defaults to a text-line height. */
+    height?: string;
+    /** Extra classes — e.g. `"rounded-full"` for an avatar placeholder instead of the default bar shape. */
+    className?: string;
+}
+/** A single pulsing placeholder bar — the shared building block every skeleton layout in this app
+ * composes from, so a loading list/sidebar/page reads as "this shape is about to have real content"
+ * rather than either a blank pane or a spinner (this app's convention going forward for anything that
+ * takes a network round trip to render — see the shells' own `Skeleton`-based "checking" state). */
+export default function Skeleton({ width, height, className }: SkeletonProps): React.JSX.Element;
+/** A vertical stack of `count` skeleton rows, each an icon-sized block plus a text-line bar — the
+ * shape shared by every list-style loading state in this app (folder trees, message/contact/task
+ * lists, sidebar nav items). */
+export declare function SkeletonList({ count, className }: {
+    count?: number;
+    className?: string;
+}): React.JSX.Element;

package/dist/lib/components/feedback/Skeleton.js

@@ -0,0 +1,14 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/** A single pulsing placeholder bar — the shared building block every skeleton layout in this app
+ * composes from, so a loading list/sidebar/page reads as "this shape is about to have real content"
+ * rather than either a blank pane or a spinner (this app's convention going forward for anything that
+ * takes a network round trip to render — see the shells' own `Skeleton`-based "checking" state). */
+export default function Skeleton({ width = "w-full", height = "h-4", className = "" }) {
+    return _jsx("div", { "aria-hidden": "true", className: ["animate-pulse rounded-sm bg-border", width, height, className].join(" ") });
+}
+/** A vertical stack of `count` skeleton rows, each an icon-sized block plus a text-line bar — the
+ * shape shared by every list-style loading state in this app (folder trees, message/contact/task
+ * lists, sidebar nav items). */
+export function SkeletonList({ count = 5, className = "" }) {
+    return (_jsx("div", { "aria-hidden": "true", className: ["flex flex-col gap-2", className].join(" "), children: Array.from({ length: count }, (_, i) => (_jsxs("div", { className: "flex items-center gap-2.5 py-1", children: [_jsx(Skeleton, { width: "w-6", height: "h-6", className: "rounded-full shrink-0" }), _jsx(Skeleton, { width: i % 2 === 0 ? "w-3/4" : "w-1/2" })] }, i))) }));
+}

package/dist/lib/components/forms/FormField.d.ts

@@ -0,0 +1,8 @@
+import React, { ReactNode } from "react";
+export interface FormFieldProps {
+    label: string;
+    htmlFor: string;
+    children: ReactNode;
+}
+/** The repeated `.rr-field` label+input wrapper. The input (and any hint/error text) is passed as children. */
+export default function FormField({ label, htmlFor, children }: FormFieldProps): React.JSX.Element;

package/dist/lib/components/forms/FormField.js

@@ -0,0 +1,5 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/** The repeated `.rr-field` label+input wrapper. The input (and any hint/error text) is passed as children. */
+export default function FormField({ label, htmlFor, children }) {
+    return (_jsxs("div", { className: "mb-4", children: [_jsx("label", { htmlFor: htmlFor, className: "block text-sm font-semibold mb-1.5 text-text", children: label }), children] }));
+}

package/dist/lib/components/navigation/BottomTabBar.d.ts

@@ -0,0 +1,27 @@
+import React 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): React.JSX.Element;

package/dist/lib/components/navigation/BottomTabBar.js

@@ -0,0 +1,32 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useRef } from "react";
+/**
+ * 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 }) {
+    const activeRef = useRef(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 (_jsx("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", children: apps.map(({ id, href, label, icon: Icon }) => (_jsxs("a", { 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(" "), children: [_jsx(Icon, { size: 20, "aria-hidden": "true" }), label] }, id))) }));
+}

package/dist/lib/components/overlays/Drawer.d.ts

@@ -0,0 +1,20 @@
+import React, { ReactNode } from "react";
+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, fullScreen, children }: DrawerProps): React.ReactPortal | null;

package/dist/lib/components/overlays/Drawer.js

@@ -0,0 +1,27 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useRef } from "react";
+import { createPortal } from "react-dom";
+import { OverlayDepthContext, useOverlayDialog } from "./overlayStack.js";
+/**
+ * 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 }) {
+    const dialogRef = useRef(null);
+    const childDepth = useOverlayDialog(open, dialogRef, onClose);
+    if (!open) {
+        return null;
+    }
+    return createPortal(_jsx("div", { className: "fixed inset-0 bg-black/50 z-[1000]", onMouseDown: (e) => e.target === e.currentTarget && onClose(), children: _jsxs("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, children: [_jsxs("div", { className: "flex items-start justify-between gap-4 mb-5", children: [_jsx("div", { className: "text-xl font-bold tracking-tight", children: title }), _jsx("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, children: "\u00D7" })] }), _jsx("div", { children: _jsx(OverlayDepthContext.Provider, { value: childDepth, children: children }) })] }) }), document.body);
+}

package/dist/lib/components/overlays/Modal.d.ts

@@ -0,0 +1,17 @@
+import React, { ReactNode } from "react";
+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): React.ReactPortal | null;

package/dist/lib/components/overlays/Modal.js

@@ -0,0 +1,25 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useRef } from "react";
+import { createPortal } from "react-dom";
+import { OverlayDepthContext, useOverlayDialog } from "./overlayStack.js";
+/**
+ * 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 }) {
+    const dialogRef = useRef(null);
+    const childDepth = useOverlayDialog(open, dialogRef, onClose);
+    if (!open) {
+        return null;
+    }
+    return createPortal(_jsx("div", { className: "fixed inset-0 bg-black/50 flex items-center justify-center p-5 z-[1000]", onMouseDown: (e) => e.target === e.currentTarget && onClose(), children: _jsxs("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, children: [_jsxs("div", { className: "flex items-start justify-between gap-4 mb-5", children: [_jsx("div", { className: "text-xl font-bold tracking-tight", children: title }), _jsx("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, children: "\u00D7" })] }), _jsx("div", { children: _jsx(OverlayDepthContext.Provider, { value: childDepth, children: children }) })] }) }), document.body);
+}

package/dist/lib/components/overlays/PopoverPortal.d.ts

@@ -0,0 +1,23 @@
+import React, { PropsWithChildren, RefObject } from "react";
+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>): React.ReactPortal | null;