Swipe the calendar sideways to step a day or a month

The calendar had next and previous as toolbar buttons and n/p, and nothing
for a thumb. Every other surface in the app that a finger drives already
answers to a swipe.

Day and month only. Those are the two views where a period is a page;
week and agenda scroll through a range rather than turning to the next
one, so there is nothing a sideways flick would obviously mean. Dragging
left pulls the next period in from the right, the way paper and every
phone do it.

Three things it deliberately does not do.

It draws nothing while the finger moves. The row swipe slides the row open
because the strip underneath has to name which of six actions is about to
happen; stepping a calendar has two outcomes and the direction of the
finger already says which. Translating the grid would also break the
sticky day header, since a transform makes a containing block. The
threshold is reported by the vibration motor instead, which is what the
haptics are for.

It does not start on an event. Which gesture was meant is decidable at the
moment the finger lands and only then, so dragging an event stays
available to be built later without having to be untangled from this
first.

And it asks for a longer drag than a row swipe -- not because the
consequence is bigger, since stepping back undoes it while a swiped row
has already been archived, but because this gesture has no way to change
its mind. A row reveals what it will do and can be let go early, and
offers Undo after. This shows nothing and offers nothing, so the distance
is the only chance to not mean it.

The axis lock is the shared one, keeping its bias towards the vertical:
the day grid scrolls through the hours, and a scroll misread as a swipe
throws the reader into another day. The toolbar buttons and n/p stay,
because a gesture with no visible control is one only the people who
already know about it can use.

FEATURES.md

@@ -110,6 +110,21 @@ every drag.
 - **Hold a folder** in the drawer for the menu its ⋮ button opens.
 - **Pull the message list** down to refresh it.
 - **Drag in from the left edge** of a conversation to go back to the list.
+- **Swipe the calendar sideways** in day or month view to step to the next
+  period or back — dragging left pulls the next one in from the right, the way
+  paper and every phone do it. Week and agenda scroll through a range rather
+  than turning to the next one, so a sideways flick would not obviously mean
+  anything there and does nothing. A drag that begins on an event is left
+  alone, which keeps dragging an event to move it available to be built later
+  without having to be untangled from this first.
+
+  It asks for a longer drag than a row swipe does, and not because the
+  consequence is bigger — stepping back undoes it, while a swiped row has
+  already been archived. It is because this gesture has no way to change its
+  mind: a row slides open as it goes, so the strip underneath names what will
+  happen and letting go early calls it off, and a toast offers Undo afterwards.
+  Stepping the calendar shows nothing on the way and offers nothing after, so
+  the distance is the only chance to not mean it.
 
 The toolbar's refresh button and the thread's back arrow both stay. A gesture
 with no visible control is one only the people who already know about it can

web/src/lib/__tests__/swipeNav.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from "vitest";
+import { navSwipeThreshold, swipeNavDirection, swipeThreshold, lockAxis } from "@/lib/touch";
+
+describe("navSwipeThreshold", () => {
+  it("asks for more travel than a row swipe does, at every width", () => {
+    // Not because the consequence is bigger -- stepping back undoes it -- but
+    // because this gesture reveals nothing on the way and offers no Undo
+    // after, so the distance is the only chance to not mean it.
+    for (const width of [320, 360, 414, 768, 1024]) {
+      expect(navSwipeThreshold(width)).toBeGreaterThan(swipeThreshold(width));
+    }
+  });
+
+  it("is a share of the width, bounded at both ends", () => {
+    expect(navSwipeThreshold(360)).toBe(108);
+    expect(navSwipeThreshold(200)).toBe(80); // floor
+    expect(navSwipeThreshold(1000)).toBe(180); // ceiling
+  });
+});
+
+describe("swipeNavDirection", () => {
+  const W = 400; // threshold is 120 at this width
+
+  it("goes forward when the finger drags left, the way pages turn", () => {
+    expect(swipeNavDirection(-200, W)).toBe(1);
+  });
+
+  it("goes back when the finger drags right", () => {
+    expect(swipeNavDirection(200, W)).toBe(-1);
+  });
+
+  it("does nothing short of the threshold, in either direction", () => {
+    expect(swipeNavDirection(-60, W)).toBe(0);
+    expect(swipeNavDirection(60, W)).toBe(0);
+    expect(swipeNavDirection(0, W)).toBe(0);
+  });
+
+  it("fires exactly at the threshold and not a pixel before", () => {
+    const at = navSwipeThreshold(W);
+    expect(swipeNavDirection(-at, W)).toBe(1);
+    expect(swipeNavDirection(-(at - 1), W)).toBe(0);
+    expect(swipeNavDirection(at, W)).toBe(-1);
+    expect(swipeNavDirection(at - 1, W)).toBe(0);
+  });
+
+  it("scales with the width, so a tablet asks for more than a phone", () => {
+    // The same 120px drag commits on a narrow screen and does not on a wide one.
+    expect(swipeNavDirection(-120, 360)).toBe(1);
+    expect(swipeNavDirection(-120, 1024)).toBe(0);
+  });
+});
+
+describe("the axis lock this shares with the row swipe", () => {
+  it("keeps a mostly-vertical drag as a scroll, which is what the day grid needs", () => {
+    // The day view scrolls through the hours; a scroll misread as a swipe
+    // throws the reader into another day.
+    expect(lockAxis(20, 30)).toBe("y");
+    expect(lockAxis(30, 25)).toBe("y");
+  });
+
+  it("commits to sideways only when it is clearly sideways", () => {
+    expect(lockAxis(40, 10)).toBe("x");
+  });
+
+  it("is undecided until the drag has moved at all", () => {
+    expect(lockAxis(2, 2)).toBeNull();
+  });
+});

web/src/lib/touch.ts

@@ -490,3 +490,129 @@ export function useEdgeBack(el: HTMLElement | null, onBack: () => void, enabled:
     };
   }, [el, enabled]);
 }
+
+/**
+ * How far a horizontal drag must travel before it moves the calendar to
+ * another day or month.
+ *
+ * Further than a row swipe, and not because the consequence is bigger --
+ * stepping a calendar is undone by stepping back, while a swiped row has
+ * already been archived. It is because this gesture has no way to change its
+ * mind. A row slides open as it goes, so the strip underneath names what is
+ * about to happen and letting go early calls it off, and a toast offers Undo
+ * afterwards. Stepping the calendar shows nothing on the way and offers
+ * nothing after, so the distance is the only chance to not mean it.
+ */
+export function navSwipeThreshold(width: number): number {
+  return Math.max(80, Math.min(180, width * 0.3));
+}
+
+/**
+ * Which way a finished drag sends the view: -1 back, +1 forward, 0 nowhere.
+ *
+ * Dragging left pulls the next period in from the right, which is how paper,
+ * phones and every other calendar behave. (It would need mirroring for a
+ * right-to-left interface; there is not one yet, and the day there is, this is
+ * one of the places that has to know.)
+ */
+export function swipeNavDirection(dx: number, width: number): -1 | 0 | 1 {
+  const threshold = navSwipeThreshold(width);
+  if (dx <= -threshold) return 1;
+  if (dx >= threshold) return -1;
+  return 0;
+}
+
+/**
+ * Swipe sideways across a calendar to step it a period at a time.
+ *
+ * Three things it deliberately does not do:
+ *
+ *  - **No visual drag.** The row swipe slides the row open because the strip
+ *    underneath has to name which of six actions is about to happen. Stepping
+ *    a calendar has two outcomes and the direction of the finger already says
+ *    which, so there is nothing to reveal -- and translating the grid would
+ *    break the sticky day header, since a transform makes a containing block.
+ *    The threshold is reported by the vibration motor instead, which is what
+ *    the haptics are for: a swipe fires as the finger passes a line it cannot
+ *    see.
+ *  - **It does not start on an event.** A drag beginning on an event chip is
+ *    left alone, so that moving an event by dragging it stays available to be
+ *    built without having to be untangled from this first. Which gesture is
+ *    meant is decidable at the moment the finger lands, and that is the only
+ *    moment it can be decided cleanly.
+ *  - **It does not start on the toolbar.** Buttons live there.
+ *
+ * The axis lock is the shared one, so it keeps the same bias towards the
+ * vertical: the day grid scrolls through the hours, and a scroll misread as a
+ * swipe throws the reader into another day.
+ */
+export function useSwipeNav(
+  el: HTMLElement | null,
+  opts: { onStep: (n: -1 | 1) => void; enabled: boolean; ignore?: string },
+) {
+  const step = useRef(opts.onStep);
+  step.current = opts.onStep;
+  const { enabled, ignore } = opts;
+
+  useEffect(() => {
+    if (!el || !enabled) return;
+    let startX: number | null = null;
+    let startY = 0;
+    let axis: Axis = null;
+    let fired = false;
+
+    const onStart = (e: TouchEvent) => {
+      if (e.touches.length !== 1) return;
+      const t = e.touches[0]!;
+      if (ignore && (t.target as Element | null)?.closest?.(ignore)) return;
+      startX = t.clientX;
+      startY = t.clientY;
+      axis = null;
+      fired = false;
+    };
+
+    const onMove = (e: TouchEvent) => {
+      if (startX === null || e.touches.length !== 1) return;
+      const t = e.touches[0]!;
+      const dx = t.clientX - startX;
+      const dy = t.clientY - startY;
+      if (!axis) {
+        axis = lockAxis(dx, dy);
+        // Committed to scrolling: stay out of the way for the rest of the drag.
+        if (axis === "y") startX = null;
+        return;
+      }
+      if (axis !== "x") return;
+      // Once sideways, the browser must not also scroll.
+      if (e.cancelable) e.preventDefault();
+      if (!fired && swipeNavDirection(dx, el.clientWidth || window.innerWidth) !== 0) {
+        fired = true;
+        haptic();
+      }
+    };
+
+    const onEnd = (e: TouchEvent) => {
+      if (startX === null) return;
+      const t = e.changedTouches[0];
+      const dx = t ? t.clientX - startX : 0;
+      const wasX = axis === "x";
+      startX = null;
+      axis = null;
+      fired = false;
+      if (!wasX) return;
+      const dir = swipeNavDirection(dx, el.clientWidth || window.innerWidth);
+      if (dir !== 0) step.current(dir);
+    };
+
+    el.addEventListener("touchstart", onStart, { passive: true });
+    el.addEventListener("touchmove", onMove, { passive: false });
+    el.addEventListener("touchend", onEnd);
+    el.addEventListener("touchcancel", onEnd);
+    return () => {
+      el.removeEventListener("touchstart", onStart);
+      el.removeEventListener("touchmove", onMove);
+      el.removeEventListener("touchend", onEnd);
+      el.removeEventListener("touchcancel", onEnd);
+    };
+  }, [el, enabled, ignore]);
+}

web/src/views/calendar/CalendarView.tsx

@@ -4,9 +4,10 @@ import { ChevronLeft, ChevronRight, Plus, Calendar as CalIcon } from "lucide-rea
 import { useCalendar, participantAddresses, type EventInstance } from "@/store/calendar";
 import { useSettings } from "@/store/settings";
 import { addDays, addMonths, DAY_MS, endOfDay, isSameDay, isToday, monthGrid, roundToNext, startOfDay, startOfWeek, toLocalDateOnly, weekDays } from "@/lib/dates";
+import { useSwipeNav } from "@/lib/touch";
 import { formatMonthYear, formatTime } from "@/lib/format";
 import { formatDate, formatDateLong, formatDayMonth, formatHourLabel, formatWeekday, formatWeekdayDate } from "@/lib/datetime";
-import { Empty, useIsMobile } from "@/ui/misc";
+import { Empty, useIsMobile, useIsTouch } from "@/ui/misc";
 import { keyboard } from "@/lib/keyboard";
 import { EventPopover } from "./EventPopover";
 import { EventEditor, type EditorInit } from "./EventEditor";
@@ -90,6 +91,25 @@ export function CalendarView({ view: viewParam, date }: { view?: string; date?:
     else go(view, addDays(anchor, 30 * n));
   };
 
+  /*
+   * Swipe sideways to step the calendar, on a touchscreen only and only in the
+   * two views where a period is a page: day and month. Week and agenda scroll
+   * through a range rather than turning to the next one, so there is nothing a
+   * sideways flick would obviously mean.
+   *
+   * The buttons in the toolbar stay, and so does n/p. A gesture with no
+   * visible control is one only the people who already know about it can use.
+   */
+  const [mainEl, setMainEl] = useState<HTMLDivElement | null>(null);
+  const isTouch = useIsTouch();
+  useSwipeNav(mainEl, {
+    enabled: isTouch && (effectiveView === "day" || effectiveView === "month"),
+    onStep: (n) => step(n),
+    // Buttons live in the toolbar; an event is where a future drag-to-move
+    // gesture has to start, so this one keeps out of both.
+    ignore: ".cal-toolbar, .ev-chip, .ev-block, .agenda-ev",
+  });
+
   const openNew = useCallback(
     (start?: Date, end?: Date, allDay = false) => {
       const s = start ?? roundToNext(new Date(), 30);
@@ -147,7 +167,7 @@ export function CalendarView({ view: viewParam, date }: { view?: string; date?:
   };
 
   return (
-    <div className="cal-main">
+    <div className="cal-main" ref={setMainEl}>
       <div className="cal-toolbar">
         <button className="btn btn-sm" onClick={() => go(view, new Date())}>{translate("Today")}</button>
         <button className="icon-btn sm" onClick={() => step(-1)} aria-label={translate("Previous")}><ChevronLeft size={18} /></button>