Group six more clusters out of web/src/lib

Takes the flat module count from 66 to 42, continuing what admin/ and
calendar/ started.

  lib/mailbox/  archiveDate, emptyFolder, folderMove, labelTree,
                mailboxName, mailboxRoute
  lib/sieve/    sieve, sieveApply, sieveFolders
  lib/input/    keyboard, swipe, touch, listSelection, dropUpload
  lib/notify/   notify, webpush, webpushEnable
  lib/sw/       swCache, swFacts, staleBuild
  lib/text/     html, markdown, text, emlName

FOUR THINGS THE FILENAMES GET WRONG, each checked by reading the file
rather than trusting what it is called:

  - appFolder is not a mailbox. It is the `ihasmail` folder in JMAP
    *Files*, where the client keeps signature images and synced settings.
    It stays flat.
  - format holds no formatting of text. It re-exports the date and clock
    formatters, so it belongs with dates/datetime, not with text/.
  - preview is the file viewer deciding what it can show without
    downloading, and source is where to point someone asking for this
    instance's AGPL source. Neither is about text.
  - notify is not Web Push. It is the tab title, the favicon badge and
    the new-mail sound -- in-app notification, which is why it sits with
    webpush rather than under sw/ with the service worker's own concerns.

threadScroll stays flat too: it decides where a conversation opens, which
is view state rather than a gesture, and input/ is honest only if
everything in it interprets something the reader did.

No behavior change. Almost every reference was on the @/ alias; eight
relative imports in files that did not move, or that moved away from a
sibling, needed rewriting by hand.

web/src/lib/input/__tests__/dropUpload.test.ts

@@ -0,0 +1,102 @@
+import { describe, expect, it } from "vitest";
+import { foldersNeeded, hasDirectory, planUpload } from "@/lib/input/dropUpload";
+
+/**
+ * Dropping a folder in, reduced to the two things the DataTransfer entry API
+ * gets wrong if you take it at face value.
+ *
+ * `readEntries` answers with *up to* some number of entries and signals the end
+ * of a directory with an empty array, so a single call quietly loses everything
+ * past the first batch — a real folder of a few hundred files would upload the
+ * first hundred and look like it had finished. And a directory tree that cycles
+ * has to stop somewhere the tab is still alive.
+ */
+
+const file = (name: string) => new File([name], name);
+
+/** A directory whose contents arrive a batch at a time, as a real one does. */
+const dir = (name: string, children: unknown[], batch = 2) => {
+  let at = 0;
+  return {
+    isFile: false,
+    isDirectory: true,
+    name,
+    createReader: () => ({
+      readEntries: (cb: (e: never[]) => void) => {
+        const slice = children.slice(at, at + batch);
+        at += slice.length;
+        cb(slice as never[]);
+      },
+    }),
+  };
+};
+
+const leaf = (name: string) => ({
+  isFile: true,
+  isDirectory: false,
+  name,
+  file: (cb: (f: File) => void) => cb(file(name)),
+});
+
+describe("walking a dropped folder", () => {
+  it("reads a directory across as many batches as it takes", async () => {
+    // Five children, two per readEntries call: a single read would find two.
+    const plan = await planUpload([dir("docs", ["a", "b", "c", "d", "e"].map(leaf))] as never[]);
+    expect(plan.map((p) => p.file.name)).toEqual(["a", "b", "c", "d", "e"]);
+    expect(plan.every((p) => p.path.join("/") === "docs")).toBe(true);
+  });
+
+  it("keeps the folder each file came from", async () => {
+    const plan = await planUpload([dir("outer", [leaf("top"), dir("inner", [leaf("deep")])])] as never[]);
+    expect(plan.map((p) => [p.path.join("/"), p.file.name])).toEqual([
+      ["outer", "top"],
+      ["outer/inner", "deep"],
+    ]);
+  });
+
+  it("puts a loose file at the drop itself", async () => {
+    const plan = await planUpload([leaf("loose")] as never[]);
+    expect(plan).toEqual([expect.objectContaining({ path: [] })]);
+  });
+
+  it("stops rather than following a cycle for ever", async () => {
+    const loop: Record<string, unknown> = {};
+    Object.assign(loop, dir("loop", []));
+    (loop as { createReader: () => unknown }).createReader = () => ({
+      readEntries: (cb: (e: unknown[]) => void) => cb([loop]),
+    });
+    // Terminating at all is the assertion; the caps decide where. Both are set
+    // low so the test does not have to read twenty thousand phantom entries.
+    const plan = await planUpload([loop] as never[], { maxDepth: 4, maxEntries: 50 });
+    expect(plan).toEqual([]);
+  });
+});
+
+describe("the folders a plan needs", () => {
+  it("lists parents before their children", () => {
+    const needed = foldersNeeded([
+      { file: file("x"), path: ["a", "b", "c"] },
+      { file: file("y"), path: ["a"] },
+    ]);
+    expect(needed).toEqual([["a"], ["a", "b"], ["a", "b", "c"]]);
+  });
+
+  it("names each folder once, however many files are in it", () => {
+    const needed = foldersNeeded([
+      { file: file("x"), path: ["a"] },
+      { file: file("y"), path: ["a"] },
+    ]);
+    expect(needed).toEqual([["a"]]);
+  });
+
+  it("asks for nothing when everything lands at the drop", () => {
+    expect(foldersNeeded([{ file: file("x"), path: [] }])).toEqual([]);
+  });
+});
+
+describe("spotting a folder in the drop", () => {
+  it("is true when any entry is a directory", () => {
+    expect(hasDirectory([leaf("a"), dir("d", [])] as never[])).toBe(true);
+    expect(hasDirectory([leaf("a")] as never[])).toBe(false);
+  });
+});

web/src/lib/input/__tests__/listSelection.test.ts

@@ -0,0 +1,104 @@
+import { describe, expect, it } from "vitest";
+import { rowClick, type RowClick } from "@/lib/input/listSelection";
+
+const IDS = ["a", "b", "c", "d", "e"];
+const click = (over: Partial<Parameters<typeof rowClick>[0]> = {}): RowClick =>
+  rowClick({
+    rowId: "c", ids: IDS, anchor: null, selected: {},
+    modifiers: { shift: false, ctrl: false }, isMobile: false,
+    ...over,
+  });
+
+describe("a plain click", () => {
+  it("opens the message rather than selecting it", () => {
+    expect(click()).toEqual({ kind: "open" });
+  });
+
+  it("opens it even when another message is already open", () => {
+    expect(click({ anchor: "a" })).toEqual({ kind: "open" });
+  });
+
+  it("goes on selecting on a touchscreen once a selection exists", () => {
+    // There is no modifier to hold on a phone, and opening a message in the
+    // middle of picking several is almost never what the tap meant.
+    expect(click({ isMobile: true, selected: { a: true } })).toEqual({ kind: "select", ids: ["c"], on: true, moveAnchor: true });
+  });
+
+  it("still opens on a touchscreen when nothing is selected", () => {
+    expect(click({ isMobile: true })).toEqual({ kind: "open" });
+  });
+});
+
+describe("ctrl-clicking", () => {
+  it("takes the message that was already current with it", () => {
+    // Issue #186: this used to select only the row clicked, leaving the open
+    // message highlighted but unticked, so actions applied to one of two.
+    expect(click({ anchor: "a", modifiers: { shift: false, ctrl: true } }))
+      .toEqual({ kind: "select", ids: ["a", "c"], on: true, moveAnchor: true });
+  });
+
+  it("toggles one row once there is a selection, and leaves the rest alone", () => {
+    expect(click({ anchor: "a", selected: { a: true, c: true }, modifiers: { shift: false, ctrl: true } }))
+      .toEqual({ kind: "select", ids: ["c"], on: false, moveAnchor: true });
+    expect(click({ anchor: "a", selected: { a: true }, modifiers: { shift: false, ctrl: true } }))
+      .toEqual({ kind: "select", ids: ["c"], on: true, moveAnchor: true });
+  });
+
+  it("selects just the row when there is nothing current to bring along", () => {
+    expect(click({ anchor: null, modifiers: { shift: false, ctrl: true } }))
+      .toEqual({ kind: "select", ids: ["c"], on: true, moveAnchor: true });
+  });
+
+  it("does not bring along a row that has scrolled out of the list", () => {
+    // The anchor can name a message from a folder that is no longer shown.
+    expect(click({ anchor: "gone", modifiers: { shift: false, ctrl: true } }))
+      .toEqual({ kind: "select", ids: ["c"], on: true, moveAnchor: true });
+  });
+
+  it("does not pair a row with itself", () => {
+    expect(click({ rowId: "a", anchor: "a", modifiers: { shift: false, ctrl: true } }))
+      .toEqual({ kind: "select", ids: ["a"], on: true, moveAnchor: true });
+  });
+});
+
+describe("shift-clicking", () => {
+  it("takes the whole run, including the row it started from", () => {
+    expect(click({ rowId: "d", anchor: "b", modifiers: { shift: true, ctrl: false } }))
+      .toEqual({ kind: "select", ids: ["b", "c", "d"], on: true, moveAnchor: false });
+  });
+
+  it("works the same way backwards", () => {
+    expect(click({ rowId: "b", anchor: "d", modifiers: { shift: true, ctrl: false } }))
+      .toEqual({ kind: "select", ids: ["b", "c", "d"], on: true, moveAnchor: false });
+  });
+
+  it("leaves the anchor where it is, so the range grows from one place", () => {
+    const first = click({ rowId: "c", anchor: "a", modifiers: { shift: true, ctrl: false } });
+    expect(first).toMatchObject({ moveAnchor: false });
+    // Extending again still starts at "a" rather than at "c".
+    expect(click({ rowId: "e", anchor: "a", modifiers: { shift: true, ctrl: false } }))
+      .toMatchObject({ ids: ["a", "b", "c", "d", "e"] });
+  });
+
+  it("falls back to opening when there is nothing to extend from", () => {
+    expect(click({ anchor: null, modifiers: { shift: true, ctrl: false } })).toEqual({ kind: "open" });
+  });
+
+  it("falls back when the anchor is no longer in the list", () => {
+    expect(click({ anchor: "gone", modifiers: { shift: true, ctrl: false } })).toEqual({ kind: "open" });
+  });
+});
+
+describe("the two rules agree with each other", () => {
+  it("both include the row the selection started from", () => {
+    // The bug was that only one of them did. Whatever else changes, a modifier
+    // click that begins a selection has to contain the anchor.
+    const withCtrl = click({ rowId: "d", anchor: "b", modifiers: { shift: false, ctrl: true } });
+    const withShift = click({ rowId: "d", anchor: "b", modifiers: { shift: true, ctrl: false } });
+    for (const result of [withCtrl, withShift]) {
+      expect(result.kind, JSON.stringify(result)).toBe("select");
+      expect((result as { ids: string[] }).ids).toContain("b");
+      expect((result as { ids: string[] }).ids).toContain("d");
+    }
+  });
+});

web/src/lib/input/__tests__/swipe.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from "vitest";
+import { SWIPE_CHOICES, describeSwipe, type SwipeAction } from "../swipe";
+
+/**
+ * A swipe names what it is about to do on a colored strip the reader sees for
+ * about a third of a second before letting go. These check that the name is
+ * true in the folder it is being read in — which is the whole reason the
+ * descriptor exists rather than a fixed label per setting.
+ */
+
+const inbox = { role: "inbox", unread: false, starred: false };
+
+describe("describeSwipe", () => {
+  it("offers nothing for a direction turned off", () => {
+    expect(describeSwipe("none", inbox)).toBe(null);
+  });
+
+  it("refuses to archive out of the archive", () => {
+    expect(describeSwipe("archive", { ...inbox, role: "archive" })).toBe(null);
+    expect(describeSwipe("archive", inbox)).toMatchObject({ label: "Archive", removes: true });
+  });
+
+  it("says out loud that a delete from Deleted Items is permanent", () => {
+    expect(describeSwipe("delete", inbox)?.label).toBe("Delete");
+    expect(describeSwipe("delete", { ...inbox, role: "trash" })?.label).toBe("Delete forever");
+  });
+
+  it("turns the spam action around inside the junk folder", () => {
+    expect(describeSwipe("spam", inbox)).toMatchObject({ label: "Report spam", icon: "spam" });
+    expect(describeSwipe("spam", { ...inbox, role: "junk" })).toMatchObject({ label: "Not spam", icon: "not-spam" });
+  });
+
+  it("has no opinion on whether your own mail is spam", () => {
+    expect(describeSwipe("spam", { ...inbox, role: "drafts" })).toBe(null);
+    expect(describeSwipe("spam", { ...inbox, role: "sent" })).toBe(null);
+  });
+
+  it("names the state a toggle is about to set, and carries it", () => {
+    expect(describeSwipe("read", { ...inbox, unread: true })).toMatchObject({ label: "Mark as read", icon: "read", on: true });
+    expect(describeSwipe("read", { ...inbox, unread: false })).toMatchObject({ label: "Mark as unread", icon: "unread", on: false });
+    expect(describeSwipe("star", { ...inbox, starred: false })).toMatchObject({ label: "Add star", on: true });
+    expect(describeSwipe("star", { ...inbox, starred: true })).toMatchObject({ label: "Remove star", on: false });
+  });
+
+  it("brings a row home for the actions that open something instead", () => {
+    // The row has to be back under the finger before the folder picker covers
+    // the list, or it is still hanging half-open when the picker closes again.
+    expect(describeSwipe("move", inbox)).toMatchObject({ label: "Move to…", removes: false });
+    for (const action of ["archive", "delete", "spam"] as const) {
+      expect(describeSwipe(action, inbox)?.removes).toBe(true);
+    }
+  });
+
+  it("can describe everything the settings picker offers", () => {
+    // A choice the picker offers and the list cannot describe is a direction
+    // that silently does nothing — the one failure nobody would report.
+    for (const { value } of SWIPE_CHOICES) {
+      const d = describeSwipe(value as SwipeAction, inbox);
+      if (value === "none") expect(d).toBe(null);
+      else expect(d?.label).toBeTruthy();
+    }
+  });
+});

web/src/lib/input/__tests__/touch.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, it } from "vitest";
+import { AXIS_SLOP, PULL_MAX, PULL_TRIGGER, lockAxis, pullDistance, swipeOffset, swipeThreshold } from "../touch";
+
+/**
+ * The arithmetic behind the touch gestures, checked without a touchscreen.
+ *
+ * These are the numbers that decide whether a finger meant to scroll the list
+ * or to act on a message, and getting them wrong is not a crash — it is an app
+ * that deletes mail when someone tried to scroll past it. Worth pinning down.
+ */
+
+describe("lockAxis", () => {
+  it("stays undecided until the finger has committed", () => {
+    expect(lockAxis(0, 0)).toBe(null);
+    expect(lockAxis(AXIS_SLOP - 1, AXIS_SLOP - 1)).toBe(null);
+  });
+
+  it("reads a clearly sideways drag as a swipe", () => {
+    expect(lockAxis(40, 4)).toBe("x");
+    expect(lockAxis(-40, 4)).toBe("x");
+  });
+
+  it("gives a diagonal to the scroller, not the swipe", () => {
+    // 45 degrees is more sideways than not, and is still a scroll: someone
+    // flicking down a list does not travel straight down the glass.
+    expect(lockAxis(30, 30)).toBe("y");
+    expect(lockAxis(30, 25)).toBe("y");
+  });
+
+  it("counts distance on either axis toward committing", () => {
+    expect(lockAxis(0, AXIS_SLOP)).toBe("y");
+    expect(lockAxis(AXIS_SLOP, 0)).toBe("x");
+  });
+});
+
+describe("swipeThreshold", () => {
+  it("scales with the row but never off either end", () => {
+    expect(swipeThreshold(300)).toBeCloseTo(84); // a phone: a share of the row
+    expect(swipeThreshold(160)).toBe(56); // a narrow row: a fixed floor
+    expect(swipeThreshold(2000)).toBe(96); // a tablet: not the whole reach
+  });
+});
+
+describe("swipeOffset", () => {
+  const width = 360;
+  const limit = swipeThreshold(width);
+
+  it("follows the finger exactly until the action would fire", () => {
+    expect(swipeOffset(20, width)).toBe(20);
+    expect(swipeOffset(-20, width)).toBe(-20);
+    expect(swipeOffset(limit, width)).toBe(limit);
+  });
+
+  it("resists past the threshold, in both directions", () => {
+    const over = swipeOffset(limit + 100, width);
+    expect(over).toBeGreaterThan(limit);
+    expect(over).toBeLessThan(limit + 100);
+    expect(swipeOffset(-(limit + 100), width)).toBeCloseTo(-over);
+  });
+
+  it("never travels further than the row is wide", () => {
+    // Past the row's own width there is nothing left to reveal, so a hard
+    // flick stops there rather than accumulating travel with nowhere to show.
+    expect(Math.abs(swipeOffset(2000, width))).toBe(width);
+    expect(Math.abs(swipeOffset(-2000, width))).toBe(width);
+  });
+});
+
+describe("pullDistance", () => {
+  it("ignores an upward drag", () => {
+    expect(pullDistance(0)).toBe(0);
+    expect(pullDistance(-50)).toBe(0);
+  });
+
+  it("asks for a deliberate pull, not the overscroll at the top of a list", () => {
+    expect(pullDistance(40)).toBeLessThan(PULL_TRIGGER);
+    expect(pullDistance(60)).toBeLessThan(PULL_TRIGGER);
+    expect(pullDistance(140)).toBeGreaterThanOrEqual(PULL_TRIGGER);
+  });
+
+  it("stops coming down however hard it is pulled", () => {
+    expect(pullDistance(400)).toBe(PULL_MAX);
+    expect(pullDistance(4000)).toBe(PULL_MAX);
+  });
+});