@rapidmx/web-client 0.14.0 → 0.15.1

package/apps/shared/components/settings/layout/SettingsShell.tsx

@@ -22,6 +22,7 @@ export interface SettingsSectionDef {
 
 /** Every settings section with its own sidebar entry. */
 export const SETTINGS_SECTIONS: SettingsSectionDef[] = [
+    { id: "profile", href: "/settings/profile", label: "Profile" },
     { id: "appearance", href: "/settings/appearance", label: "Appearance" },
     { id: "auto-reply", href: "/settings/auto-reply", label: "Automatic Replies" },
     { id: "filters", href: "/settings/filters", label: "Mail Filters" },

package/apps/shared/gestures/useEnterSlide.ts

@@ -0,0 +1,54 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useRef, useState, type CSSProperties } from "react";
+
+/** How long the new contents take to settle. Short, so a run of steps (a wheel kept turning) never waits on the last one. */
+export const ENTER_SLIDE_MS = 140;
+/** How far off, in pixels, and how faded the new contents start. */
+const ENTER_OFFSET_PX = 56;
+const ENTER_START_OPACITY = 0.35;
+/** The pause that lets the browser draw the contents at their starting place before they move. */
+const ENTER_SETTLE_MS = 20;
+
+/** Whether the user asked their device for less motion. */
+function prefersReducedMotion(): boolean {
+    return typeof window !== "undefined" && typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+}
+
+/**
+ * The look of a page that has just been swapped for the next or previous one by a vertical step (the wheel): the new contents start
+ * a little way off in the direction the step went - below for `1` (the next), above for `-1` - and faded, and settle into place.
+ * The old contents are not animated out: the swap is immediate, so a run of steps never queues, and a step in the middle of a
+ * settle just starts the next one from its start. Put `style` on the element that holds the contents and call `enter()` as the
+ * contents change. Nothing moves for someone who asked for less motion.
+ */
+export function useEnterSlide() {
+    const [offset, setOffset] = useState(0);
+    const [animated, setAnimated] = useState(false);
+    const timer = useRef<number | undefined>(undefined);
+
+    useEffect(() => () => window.clearTimeout(timer.current), []);
+
+    function enter(direction: 1 | -1) {
+        if (prefersReducedMotion()) {
+            return;
+        }
+        window.clearTimeout(timer.current);
+        setAnimated(false);
+        setOffset(direction * ENTER_OFFSET_PX);
+        timer.current = window.setTimeout(() => {
+            setAnimated(true);
+            setOffset(0);
+        }, ENTER_SETTLE_MS);
+    }
+
+    const style: CSSProperties = {
+        transform: offset === 0 ? undefined : `translate3d(0, ${offset}px, 0)`,
+        opacity: offset === 0 ? undefined : ENTER_START_OPACITY,
+        transition: animated ? `transform ${ENTER_SLIDE_MS}ms ease-out, opacity ${ENTER_SLIDE_MS}ms ease-out` : "none",
+    };
+
+    return { style, enter };
+}

package/apps/shared/gestures/useSwipe.ts

@@ -0,0 +1,114 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useRef, type TouchEvent } from "react";
+
+/** Which way the finger moved: `"left"` is right to left. */
+export type SwipeDirection = "left" | "right";
+
+export interface UseSwipeOptions {
+    /** Nothing is tracked while this is `false` (a desktop pointer, select mode). Default `true`. */
+    enabled?: boolean;
+    /** The directions that mean something; a drag the other way doesn't move at all. Default both. */
+    directions?: readonly SwipeDirection[];
+    /** How far the finger has to travel to commit, in px. Default `MIN_SWIPE_DISTANCE`, or a third of the element's width when that is more. */
+    distance?: number;
+    /** Called as the finger moves, with the horizontal offset (the direction filter applied), and with `0` once it lifts. */
+    onDrag?: (offset: number) => void;
+    /** Called once when a swipe commits. `onDrag(0)` follows. */
+    onSwipe: (direction: SwipeDirection) => void;
+}
+
+/** The least distance that commits a swipe, and how far the finger must move before its direction is decided. */
+export const MIN_SWIPE_DISTANCE = 80;
+export const SWIPE_SLOP = 10;
+/** A quicker flick than this (px per ms) commits after `FLING_MIN_DISTANCE` alone. */
+export const FLING_VELOCITY = 0.5;
+export const FLING_MIN_DISTANCE = 40;
+
+/**
+ * A horizontal swipe by one finger, for the touch screens the app's phone layout is for: mouse and pen are left alone.
+ *
+ * Spread the handlers on the element and give it `touch-action: pan-y` (`style`), so the browser keeps scrolling vertically and leaves
+ * the horizontal movement to this. A gesture that starts out mostly vertical is a scroll and is never a swipe, however far it later
+ * strays sideways; one that starts out horizontal is a swipe, and stays one.
+ */
+export function useSwipe({ enabled = true, directions = ["left", "right"], distance, onDrag, onSwipe }: UseSwipeOptions) {
+    const start = useRef<{ x: number; y: number; time: number; width: number; mode?: "swipe" | "scroll" } | null>(null);
+    const offset = useRef(0);
+    const latest = useRef({ directions, distance, onDrag, onSwipe });
+    latest.current = { directions, distance, onDrag, onSwipe };
+
+    function clamp(dx: number): number {
+        const allowed = latest.current.directions;
+        return (dx < 0 && !allowed.includes("left")) || (dx > 0 && !allowed.includes("right")) ? 0 : dx;
+    }
+
+    function onTouchStart(event: TouchEvent<HTMLElement>) {
+        if (!enabled || event.touches.length !== 1) {
+            start.current = null;
+            return;
+        }
+        const touch = event.touches[0];
+        start.current = { x: touch.clientX, y: touch.clientY, time: Date.now(), width: event.currentTarget.clientWidth };
+        offset.current = 0;
+    }
+
+    function onTouchMove(event: TouchEvent<HTMLElement>) {
+        const gesture = start.current;
+        if (!gesture || gesture.mode === "scroll") {
+            return;
+        }
+        if (event.touches.length !== 1) {
+            cancel();
+            return;
+        }
+        const dx = event.touches[0].clientX - gesture.x;
+        const dy = event.touches[0].clientY - gesture.y;
+        if (!gesture.mode) {
+            if (Math.max(Math.abs(dx), Math.abs(dy)) < SWIPE_SLOP) {
+                return;
+            }
+            gesture.mode = Math.abs(dx) > Math.abs(dy) * 1.5 ? "swipe" : "scroll";
+            if (gesture.mode === "scroll") {
+                return;
+            }
+        }
+        offset.current = clamp(dx);
+        latest.current.onDrag?.(offset.current);
+    }
+
+    function onTouchEnd() {
+        const gesture = start.current;
+        start.current = null;
+        if (!gesture || gesture.mode !== "swipe") {
+            return;
+        }
+        const dx = offset.current;
+        offset.current = 0;
+        const travelled = Math.abs(dx);
+        const velocity = travelled / Math.max(1, Date.now() - gesture.time);
+        const needed = latest.current.distance ?? Math.max(MIN_SWIPE_DISTANCE, gesture.width / 3);
+        const committed = dx !== 0 && (travelled >= needed || (velocity >= FLING_VELOCITY && travelled >= FLING_MIN_DISTANCE));
+        if (committed) {
+            latest.current.onSwipe(dx < 0 ? "left" : "right");
+        }
+        latest.current.onDrag?.(0);
+    }
+
+    function cancel() {
+        const moved = start.current?.mode === "swipe";
+        start.current = null;
+        offset.current = 0;
+        if (moved) {
+            latest.current.onDrag?.(0);
+        }
+    }
+
+    return {
+        handlers: enabled ? { onTouchStart, onTouchMove, onTouchEnd, onTouchCancel: cancel } : {},
+        /** Leaves vertical panning to the browser. */
+        style: enabled ? ({ touchAction: "pan-y" } as const) : undefined,
+    };
+}

package/apps/shared/gestures/useSwipeSlide.ts

@@ -0,0 +1,113 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useRef, useState, type CSSProperties } from "react";
+import { SwipeDirection, useSwipe } from "./useSwipe.js";
+
+/** How long the current contents take to leave, and the new ones to arrive - or the current ones to snap back. */
+export const SLIDE_MS = 200;
+/** The pause between the new contents being put off-screen and them starting to slide in, long enough for the browser to draw them there. */
+const SETTLE_MS = 30;
+/** How far a slide goes when the element's width can't be measured. */
+const FALLBACK_WIDTH_PX = 320;
+
+export interface UseSwipeSlideOptions {
+    /** Nothing is tracked while this is `false`. */
+    enabled: boolean;
+    /** Changes what is shown to the period the swipe went to - called once the old contents have left, while the new ones wait off-screen. */
+    onShift: (direction: SwipeDirection) => void;
+}
+
+/** Whether the user asked their device for less motion, in which case the change is made at once instead of slid. */
+function prefersReducedMotion(): boolean {
+    return typeof window !== "undefined" && typeof window.matchMedia === "function" && window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+}
+
+/**
+ * A swipe between pages of content that visibly moves them, the way a phone calendar does: the contents follow the finger, and once
+ * the swipe commits they carry on out of view in the direction it went while the next ones - `onShift()` changes what is shown at
+ * that moment - slide in from the other side. A swipe that stops short slides back. The animation is timed here (`SLIDE_MS`) rather than
+ * left to `transitionend`, so it can't stall if the browser skips a transition.
+ *
+ * Put `handlers` and `style` on a clipping element (`overflow-hidden`, so the contents don't widen the page while they are off to
+ * the side), the contents inside it in an element of their own with `contentStyle`, and `ref` on the clipping element.
+ */
+export function useSwipeSlide({ enabled, onShift }: UseSwipeSlideOptions) {
+    const [offset, setOffset] = useState(0);
+    /** Whether a change of `offset` is animated: not while the finger is moving it, yes for everything else. */
+    const [animated, setAnimated] = useState(false);
+    /** A committed slide is under way: further swipes are ignored until it ends. */
+    const [sliding, setSliding] = useState(false);
+    const slidingRef = useRef(false);
+    const ref = useRef<HTMLDivElement | null>(null);
+    const timers = useRef<number[]>([]);
+    const latest = useRef({ onShift });
+    latest.current = { onShift };
+
+    useEffect(
+        () => () => {
+            for (const timer of timers.current) {
+                window.clearTimeout(timer);
+            }
+        },
+        [],
+    );
+
+    function later(work: () => void, ms: number) {
+        timers.current.push(window.setTimeout(work, ms));
+    }
+
+    const swipe = useSwipe({
+        enabled: enabled && !sliding,
+        onDrag: (dx) => {
+            // `useSwipe()` reports the finger lifting (0) right after a swipe commits: that must not undo the slide out.
+            if (slidingRef.current) {
+                return;
+            }
+            setAnimated(dx === 0);
+            setOffset(dx);
+        },
+        onSwipe: (direction) => {
+            if (prefersReducedMotion()) {
+                latest.current.onShift(direction);
+                return;
+            }
+            const width = ref.current?.clientWidth || FALLBACK_WIDTH_PX;
+            // The finger moved `direction`, so the contents go that way and the next ones come from the opposite side.
+            const out = direction === "left" ? -width : width;
+            slidingRef.current = true;
+            setSliding(true);
+            setAnimated(true);
+            setOffset(out);
+            later(() => {
+                latest.current.onShift(direction);
+                setAnimated(false);
+                setOffset(-out);
+                later(() => {
+                    setAnimated(true);
+                    setOffset(0);
+                    later(() => {
+                        slidingRef.current = false;
+                        setSliding(false);
+                    }, SLIDE_MS);
+                }, SETTLE_MS);
+            }, SLIDE_MS);
+        },
+    });
+
+    const contentStyle: CSSProperties = {
+        transform: offset === 0 ? undefined : `translate3d(${offset}px, 0, 0)`,
+        transition: animated ? `transform ${SLIDE_MS}ms ease-out` : "none",
+    };
+
+    return {
+        handlers: swipe.handlers,
+        /** For the clipping element: `touch-action: pan-y`, and no overflow. */
+        style: swipe.style,
+        contentStyle,
+        ref,
+        /** For a test or a style hook: `"idle"`, `"dragging"` or `"sliding"`. */
+        phase: sliding ? "sliding" : offset !== 0 && !animated ? "dragging" : "idle",
+    };
+}

package/apps/shared/gestures/useWheelPaging.ts

@@ -0,0 +1,107 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useRef, type RefObject } from "react";
+
+/** Wheel movement, in pixels, that steps to the next or previous page when nothing inside scrolls: about one notch of a mouse wheel. */
+export const WHEEL_STEP_PX = 100;
+/** Wheel movement, in pixels, pushed against the top or bottom of what scrolls inside before it steps onto the next or previous page. */
+export const WHEEL_EDGE_PX = 80;
+/** Movement that isn't followed by more within this long starts from nothing again, so an old nudge doesn't add to a new one. */
+export const WHEEL_IDLE_MS = 250;
+/** After a step that starts at an edge, wheel events for this long are left to settle the new page, so one hard push isn't two steps. */
+export const WHEEL_SETTLE_MS = 100;
+
+/** Where the new page's scroll position goes: `"top"` when stepping forward past the bottom, `"bottom"` when stepping back past the top. */
+export type WheelEdge = "top" | "bottom";
+
+export interface UseWheelPagingOptions {
+    /** Nothing is handled while this is `false` (a phone, an event being dragged, a dialog open). */
+    enabled: boolean;
+    /** The element inside that scrolls vertically, if there is one now: the wheel scrolls it as usual and only steps past its ends.
+     * `null` when nothing inside scrolls (a month grid), and then every wheel movement counts towards a step. */
+    getScroller: () => HTMLElement | null;
+    /** Called for each step: `1` towards the next page (the wheel turned down), `-1` towards the previous. `edge` says where in the new
+     * page's scroller to start, when there is one. */
+    onStep: (direction: 1 | -1, edge: WheelEdge | null) => void;
+}
+
+/** A wheel event's vertical movement in pixels, whichever unit the browser reports it in. */
+function pixelsOf(event: WheelEvent, page: number): number {
+    return event.deltaMode === 1 ? event.deltaY * 16 : event.deltaMode === 2 ? event.deltaY * page : event.deltaY;
+}
+
+/**
+ * Turns the mouse wheel over `ref`'s element into stepping through pages - the months, weeks or days of a calendar - without a limit:
+ * keep turning and it keeps stepping, and nothing waits for an animation to end.
+ *
+ * Where nothing inside scrolls, every `WHEEL_STEP_PX` of movement is a step (a bigger turn is several). Where something does, the
+ * wheel scrolls it as it always did and only what is pushed against its top or bottom counts (`WHEEL_EDGE_PX`), so scrolling on
+ * from the last hour of a day carries into the first hours of the next, and back the other way. The event is only cancelled when it
+ * counts towards a step, so the page and whatever scrolls inside keep their own wheel behaviour everywhere else. Zooming
+ * (Ctrl+wheel) and sideways movement are left alone.
+ */
+export function useWheelPaging(ref: RefObject<HTMLElement | null>, { enabled, getScroller, onStep }: UseWheelPagingOptions) {
+    const latest = useRef({ getScroller, onStep });
+    latest.current = { getScroller, onStep };
+    /** Movement collected towards the next step, and when it last grew. */
+    const collected = useRef({ pixels: 0, at: 0 });
+    const settledUntil = useRef(0);
+
+    useEffect(() => {
+        const element = ref.current;
+        if (!enabled || !element) {
+            return;
+        }
+
+        function onWheel(event: WheelEvent) {
+            if (event.ctrlKey || event.defaultPrevented || Math.abs(event.deltaX) > Math.abs(event.deltaY)) {
+                return;
+            }
+            const pixels = pixelsOf(event, element!.clientHeight || 600);
+            if (pixels === 0) {
+                return;
+            }
+            const scroller = latest.current.getScroller();
+            if (scroller) {
+                const room = scroller.scrollHeight - scroller.clientHeight;
+                const canScroll = pixels > 0 ? scroller.scrollTop < room - 1 : scroller.scrollTop > 0;
+                if (room > 0 && canScroll) {
+                    // Still something to scroll that way: the browser does it, and what was pushed against an end is forgotten.
+                    collected.current = { pixels: 0, at: 0 };
+                    return;
+                }
+            }
+
+            event.preventDefault();
+            const now = Date.now();
+            if (scroller && now < settledUntil.current) {
+                return;
+            }
+            const state = collected.current;
+            if (now - state.at > WHEEL_IDLE_MS || Math.sign(state.pixels) !== Math.sign(pixels)) {
+                state.pixels = 0;
+            }
+            state.at = now;
+            state.pixels += pixels;
+
+            const needed = scroller ? WHEEL_EDGE_PX : WHEEL_STEP_PX;
+            while (Math.abs(state.pixels) >= needed) {
+                const direction: 1 | -1 = state.pixels > 0 ? 1 : -1;
+                state.pixels -= direction * needed;
+                latest.current.onStep(direction, scroller ? (direction > 0 ? "top" : "bottom") : null);
+                if (scroller) {
+                    // One push against an end is one step; the next turn of the wheel scrolls the page it arrived at.
+                    state.pixels = 0;
+                    settledUntil.current = now + WHEEL_SETTLE_MS;
+                    break;
+                }
+            }
+        }
+
+        // Not passive: the wheel's default (scrolling the page) has to be cancellable for the steps that replace it.
+        element.addEventListener("wheel", onWheel, { passive: false });
+        return () => element.removeEventListener("wheel", onWheel);
+    }, [enabled, ref]);
+}