docs(readme,preview): screenshots of both tabs, a calendar scene on the busiest month

The panel drifted while the keyboard came up and then slid under it at the
end. Two reasons, both about the ground moving twice: iOS animates the
keyboard, and once it is up Obsidian hides its own navbar - a second move that
the old four-frame watch had already stopped waiting for, and that a trigger
arriving mid-watch was dropped for instead of restarting it.

The watch now runs until the reading holds still for twelve frames, a fresh
trigger restarts it, and Obsidian's Capacitor keyboard events (`keyboardWill/
DidShow`, `...Hide`) are listened to as well - they fire around the animation
that `visualViewport` does not always report, and never fire on the desktop.

README.md

@@ -1,9 +1,11 @@
 # beaver-calendar
 [![AI Slop Inside](https://sladge.net/badge.svg)](https://sladge.net)
 
-Calendar and task list for Obsidian Kanban+Tasks
+A calendar and a task list for Obsidian on top of Kanban boards and the Tasks plugin. A sphere is a board file, a project is an h2 inside it; every task keeps living in its board, the plugin only shows them together - by deadline, by sphere, or on a month grid - and lets you drag, edit and close them without opening the board.
 
-Sphere - md-file in Kanban boards directory. Project - h2 inside the file.
+![The Calendar tab: a month with tasks by day, the undated ones below](docs/calendar.webp)
+
+![The List tab: tasks grouped by deadline, the rail with spheres and projects on the left](docs/list.webp)
 
 ## Archiving
 
@@ -49,5 +51,5 @@ VAULT=/path/to/vault npm run preview               # the vault's theme
 BOARDS=/path/to/vault/Boards npm run preview       # real boards, not fixtures
 EXTRA_CSS=/path/to/other-plugin/styles.css …       # another plugin's css, loaded after ours
 open 'http://localhost:4173/?groupBy=due&railCollapsed=1#edit-date'   # prefs + scene
-node preview/shot.mjs out.png 'http://localhost:4173/#date'           # screenshot + console
+node preview/shot.mjs out.png 'http://localhost:4173/#cal'            # screenshot + console
 ```

preview/entry.ts

@@ -105,6 +105,17 @@ async function main(): Promise<void> {
     }
     if (scene === "rail-none") store.filterNone();
   }
+  // The month grid on its own, opened on the month the fixtures are busiest in.
+  if (scene === "cal") {
+    const months = new Map<string, number>();
+    for (const item of store.visible) {
+      const key = (item.due ?? item.scheduled)?.slice(0, 7);
+      if (key) months.set(key, (months.get(key) ?? 0) + 1);
+    }
+    const busiest = [...months.entries()].sort((a, b) => b[1] - a[1])[0]?.[0];
+    store.view = "calendar";
+    if (busiest) store.focusDay(`${busiest}-15`);
+  }
   if (scene.startsWith("peek")) {
     if (scene === "peek-cal") store.view = "calendar";
     if (scene === "peek-notes") store.showDone = true;

preview/index.html

@@ -2,6 +2,9 @@
 <html lang="en">
   <head>
     <meta charset="utf-8" />
+    <!-- Without this a phone-sized window still lays out at 980px, so a
+         "mobile" screenshot is not one and coarse-pointer rules never apply. -->
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>beaver-calendar preview</title>
     <link rel="stylesheet" href="/app.css" />
     <link rel="stylesheet" href="/theme.css" />

src/lib/inset.ts

@@ -0,0 +1,54 @@
+/**
+ * How much of the view's bottom is covered by something the operator cannot
+ * move: Obsidian's desktop status bar, a phone's navbar (which paints over a
+ * leaf instead of shortening it), and the software keyboard, which shrinks the
+ * visual viewport while the layout keeps its full height.
+ *
+ * Pure on purpose - the view feeds it live rectangles, the tests feed it the
+ * numbers a phone actually reports.
+ */
+
+export interface Rect {
+  bottom: number;
+  height: number;
+  left: number;
+  right: number;
+  top: number;
+}
+
+export interface Visible {
+  /** `visualViewport.height`: what is left once the keyboard is up. */
+  height: number;
+  /** `visualViewport.offsetTop`: where the visible area starts. */
+  offsetTop: number;
+}
+
+/** Bars that float over a leaf rather than making room for it. */
+export const BOTTOM_BARS = [
+  ".status-bar",
+  ".mobile-navbar",
+  ".mobile-toolbar",
+] as const;
+
+export function insetFor(
+  leaf: Rect,
+  bars: Rect[],
+  visible: Visible | null,
+): number {
+  if (leaf.height <= 0) return 0;
+
+  let overlap = 0;
+  for (const bar of bars) {
+    // A bar that does not sit over this leaf horizontally covers nothing of
+    // it - the desktop status bar beside a left-hand sidedock, say.
+    if (bar.height > 0 && bar.left < leaf.right && bar.right > leaf.left) {
+      overlap = Math.max(overlap, leaf.bottom - bar.top);
+    }
+  }
+  if (visible) {
+    // While the keyboard is up the navbar is behind it: the deeper of the two
+    // is the inset, and summing them would push the view twice as far.
+    overlap = Math.max(overlap, leaf.bottom - (visible.offsetTop + visible.height));
+  }
+  return Math.max(0, Math.round(overlap));
+}

src/lib/place.ts

@@ -24,13 +24,35 @@ export interface Viewport {
 /**
  * What is actually visible, which on a phone is not the window: the software
  * keyboard shrinks the visual viewport and leaves `innerHeight` alone, so a
- * panel placed against the window lands behind the keys.
+ * panel placed against the window lands behind the keys. The navbar is not in
+ * the viewport at all - it floats over it - so it is subtracted by hand.
  */
 export function viewport(win: Window = window): Viewport {
   const vv = win.visualViewport;
-  return vv
+  const base: Viewport = vv
     ? { width: vv.width, height: vv.height, top: vv.offsetTop, left: vv.offsetLeft }
     : { width: win.innerWidth, height: win.innerHeight };
+  return { ...base, height: base.height - floating(win, base) };
+}
+
+/**
+ * How much of the bottom of `view` a floating bar covers. Obsidian's phone
+ * navbar paints over every leaf, so a panel that ends under it cannot be
+ * reached even though it is inside the viewport.
+ */
+function floating(win: Window, view: Viewport): number {
+  const doc = win.document;
+  const bottom = (view.top ?? 0) + view.height;
+  let covered = 0;
+  for (const selector of [".mobile-navbar", ".mobile-toolbar", ".status-bar"]) {
+    const node = doc.querySelector(selector) as HTMLElement | null;
+    if (!node || node.offsetParent === null) continue;
+    const box = node.getBoundingClientRect();
+    if (box.height > 0 && box.top < bottom) {
+      covered = Math.max(covered, bottom - box.top);
+    }
+  }
+  return Math.min(covered, Math.max(0, view.height - 120));
 }
 
 /** The tallest a panel may be here before it has to scroll its own body. */

src/tailwind.css

@@ -102,7 +102,12 @@
 }
 
 .bcal-root {
+  box-sizing: border-box;
   height: 100%;
+  /* The phone's navbar floats over the leaf rather than shortening it, so the
+     last row of the list would sit underneath it. The view measures how much
+     and sets this; on a desktop it stays 0. */
+  padding-bottom: var(--bcal-inset-bottom, 0px);
   font-family: var(--font-interface);
   font-size: var(--text-sm);
   color: var(--foreground);

src/ui/anchored-panel.svelte

@@ -27,8 +27,18 @@
 
   const view = useView();
 
-  // iOS animates the keyboard in; the viewport only tells the truth after.
+  // The keyboard animates both ways: rather than guess how long that takes,
-  const KEYBOARD_SETTLE_MS = 350;
+  // the panel re-places every frame until its position holds still. Long enough
+  // to outlast Obsidian hiding its navbar, which moves the ground a second time.
+  const STEADY_FRAMES = 12;
+
+  /** Obsidian's Capacitor keyboard events on mobile; absent on the desktop. */
+  const KEYBOARD_EVENTS = [
+    "keyboardWillShow",
+    "keyboardDidShow",
+    "keyboardWillHide",
+    "keyboardDidHide",
+  ];
 
   let panel = $state<HTMLElement | null>(null);
   let at = $state({ top: 0, left: 0 });
@@ -74,14 +84,46 @@
       if (!node.contains(event.target as Node)) onclose();
     };
     const reflow = (): void => measure();
+    /**
+     * Re-place every frame until the position has held still for a while. The
+     * keyboard animates, and Obsidian hides its navbar *after* it is up, which
+     * moves the ground under the panel a second time - a short "steady" run
+     * exits between the two and leaves the panel where neither wanted it. In a
+     * sidedock no resize event fires at all, so a frame loop is the only thing
+     * that notices either move.
+     */
+    let frame: number | null = null;
+    const settle = (): void => {
+      let last = Number.NaN;
+      let steady = 0;
+      if (frame !== null) win.cancelAnimationFrame(frame);
+      const tick = (): void => {
+        measure();
+        steady = at.top === last ? steady + 1 : 0;
+        last = at.top;
+        if (steady >= STEADY_FRAMES) {
+          frame = null;
+          return;
+        }
+        frame = win.requestAnimationFrame(tick);
+      };
+      frame = win.requestAnimationFrame(tick);
+    };
     document.addEventListener("pointerdown", outside, true);
     window.addEventListener("resize", reflow);
-    // The keyboard changes the visual viewport without resizing the window,
+    // The keyboard changes the visual viewport without resizing the window.
-    // and its animation takes a moment to settle.
     const vv = win.visualViewport;
-    vv?.addEventListener("resize", reflow);
+    vv?.addEventListener("resize", settle);
-    vv?.addEventListener("scroll", reflow);
+    vv?.addEventListener("scroll", settle);
-    const settle = win.setTimeout(reflow, KEYBOARD_SETTLE_MS);
+    // Obsidian's own keyboard events (Capacitor, mobile only): they fire before
+    // the animation and again as the navbar comes back, which `visualViewport`
+    // on its own does not always report.
+    for (const name of KEYBOARD_EVENTS) {
+      win.addEventListener(name, settle);
+    }    // The panel's own input takes focus a beat before the keyboard is up, and
+    // swapping fields re-opens it.
+    node.addEventListener("focusin", settle);
+    settle();
     // A panel whose body grew (an option list opened) re-places itself. Only
     // the content height is watched: measure() sets max-height, so observing
     // the panel itself would feed its own change back in.
@@ -97,9 +139,13 @@
       destroy() {
         document.removeEventListener("pointerdown", outside, true);
         window.removeEventListener("resize", reflow);
-        vv?.removeEventListener("resize", reflow);
+        vv?.removeEventListener("resize", settle);
-        vv?.removeEventListener("scroll", reflow);
+        vv?.removeEventListener("scroll", settle);
-        win.clearTimeout(settle);
+        for (const name of KEYBOARD_EVENTS) {
+          win.removeEventListener(name, settle);
+        }
+        node.removeEventListener("focusin", settle);
+        if (frame !== null) win.cancelAnimationFrame(frame);
         watcher?.disconnect();
         win.removeEventListener("keydown", keys, true);
         panel = null;

src/view.ts

@@ -1,13 +1,29 @@
 import { ItemView } from "obsidian";
 import type { WorkspaceLeaf } from "obsidian";
 import { mount, unmount } from "svelte";
+import { BOTTOM_BARS, insetFor } from "./lib/inset";
+import type { Rect } from "./lib/inset";
 import App from "./ui/app.svelte";
 import type BeaverCalendarPlugin from "./main";
 
 export const VIEW_TYPE_BOARDS = "beaver-calendar-boards";
 
+// The keyboard and the navbar both animate, and Obsidian hides the navbar
+// *after* the keyboard is up: the inset is re-measured every frame until the
+// reading has held still long enough to outlast both moves.
+const STEADY_FRAMES = 12;
+
+/** Obsidian's Capacitor keyboard events on mobile; absent on the desktop. */
+const KEYBOARD_EVENTS = [
+  "keyboardWillShow",
+  "keyboardDidShow",
+  "keyboardWillHide",
+  "keyboardDidHide",
+] as const;
+
 export class BoardsView extends ItemView {
   private root: Record<string, unknown> | null = null;
+  private settling: number | null = null;
 
   constructor(
     leaf: WorkspaceLeaf,
@@ -51,6 +67,30 @@ export class BoardsView extends ItemView {
       }),
     );
 
+    this.registerEvent(this.app.workspace.on("resize", () => this.settle()));
+    this.registerEvent(
+      this.app.workspace.on("layout-change", () => this.settle()),
+    );
+    // The keyboard shrinks the visual viewport without resizing the layout, so
+    // no workspace event fires - and in a sidedock none fires at all.
+    const vv = window.visualViewport;
+    if (vv) {
+      const onViewport = () => this.settle();
+      vv.addEventListener("resize", onViewport);
+      vv.addEventListener("scroll", onViewport);
+      this.register(() => {
+        vv.removeEventListener("resize", onViewport);
+        vv.removeEventListener("scroll", onViewport);
+      });
+    }
+    this.registerDomEvent(this.contentEl, "focusin", () => this.settle());
+    this.registerDomEvent(this.contentEl, "focusout", () => this.settle());
+    for (const name of KEYBOARD_EVENTS) {
+      const onKeyboard = () => this.settle();
+      window.addEventListener(name, onKeyboard);
+      this.register(() => window.removeEventListener(name, onKeyboard));
+    }
+
     await this.plugin.store.reloadAll();
     this.root = mount(App, {
       target: this.contentEl,
@@ -61,6 +101,59 @@ export class BoardsView extends ItemView {
         component: this,
       },
     });
+    this.settle();
+  }
+
+  /**
+   * Re-measure until the viewport stops moving: the keyboard animates both
+   * ways, Obsidian hides its navbar while it is up, and a frame loop needs
+   * neither a duration to guess nor an event that a sidedock never sends.
+   */
+  private settle(): void {
+    let last = Number.NaN;
+    let steady = 0;
+    // A fresh trigger restarts the watch rather than being dropped: the navbar
+    // coming back is a second move, after the first one has settled.
+    if (this.settling !== null) cancelAnimationFrame(this.settling);
+    const tick = () => {
+      const inset = this.inset();
+      steady = inset === last ? steady + 1 : 0;
+      last = inset;
+      if (steady >= STEADY_FRAMES) {
+        this.settling = null;
+        return;
+      }
+      this.settling = requestAnimationFrame(tick);
+    };
+    this.settling = requestAnimationFrame(tick);
+    this.register(() => {
+      if (this.settling !== null) {
+        cancelAnimationFrame(this.settling);
+        this.settling = null;
+      }
+    });
+  }
+
+  /** Pads the view clear of the navbar and the keyboard. */
+  private inset(): number {
+    const box = this.contentEl.getBoundingClientRect();
+    if (box.height <= 0) return Number.NaN;
+
+    const bars: Rect[] = [];
+    for (const selector of BOTTOM_BARS) {
+      const node = document.querySelector<HTMLElement>(selector);
+      if (node && node.offsetParent !== null) {
+        bars.push(node.getBoundingClientRect());
+      }
+    }
+    const vv = window.visualViewport;
+    const inset = insetFor(
+      box,
+      bars,
+      vv ? { height: vv.height, offsetTop: vv.offsetTop } : null,
+    );
+    this.contentEl.style.setProperty("--bcal-inset-bottom", `${inset}px`);
+    return inset;
   }
 
   async onClose(): Promise<void> {

tests/inset.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from "vitest";
+import { BOTTOM_BARS, insetFor } from "../src/lib/inset";
+import type { Rect } from "../src/lib/inset";
+
+const rect = (over: Partial<Rect> = {}): Rect => ({
+  top: 0,
+  left: 0,
+  right: 390,
+  bottom: 780,
+  height: 780,
+  ...over,
+});
+
+// A phone: 780 tall, a 56px navbar floating over the bottom, 340px of keyboard.
+const NAVBAR = rect({ top: 724, bottom: 780, height: 56 });
+
+describe("insetFor", () => {
+  it("clears nothing when the view stands alone", () => {
+    expect(insetFor(rect(), [], null)).toBe(0);
+  });
+
+  it("clears the navbar that paints over the view", () => {
+    expect(insetFor(rect(), [NAVBAR], null)).toBe(56);
+  });
+
+  it("clears the keyboard, which shortens no layout", () => {
+    expect(insetFor(rect(), [], { height: 440, offsetTop: 0 })).toBe(340);
+  });
+
+  it("takes the deeper of the two rather than their sum", () => {
+    // The navbar hides behind the keyboard while it is up.
+    expect(insetFor(rect(), [NAVBAR], { height: 440, offsetTop: 0 })).toBe(340);
+  });
+
+  it("comes back to the navbar once the keyboard goes", () => {
+    expect(insetFor(rect(), [NAVBAR], { height: 780, offsetTop: 0 })).toBe(56);
+  });
+
+  it("ignores a bar that sits beside the view, not over it", () => {
+    const sidedock = rect({ right: 300 });
+    const statusBar = rect({
+      top: 760,
+      bottom: 780,
+      height: 20,
+      left: 700,
+      right: 980,
+    });
+    expect(insetFor(sidedock, [statusBar], null)).toBe(0);
+  });
+
+  it("measures from where the visible area starts", () => {
+    expect(insetFor(rect(), [], { height: 440, offsetTop: 100 })).toBe(240);
+  });
+
+  it("says nothing about a view with no height yet", () => {
+    expect(insetFor(rect({ height: 0, bottom: 0 }), [NAVBAR], null)).toBe(0);
+  });
+
+  it("never returns a negative inset", () => {
+    const short = rect({ bottom: 300, height: 300 });
+    expect(insetFor(short, [], { height: 780, offsetTop: 0 })).toBe(0);
+  });
+
+  it("names the bars that float rather than make room", () => {
+    expect(BOTTOM_BARS).toContain(".mobile-navbar");
+    expect(BOTTOM_BARS).toContain(".status-bar");
+  });
+});

tests/place.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { onScreen, place, roomFor } from "../src/lib/place";
+import { onScreen, place, roomFor, viewport } from "../src/lib/place";
 import type { Box } from "../src/lib/place";
 
 const VIEW = { width: 1280, height: 800 };
@@ -95,3 +95,41 @@ describe("roomFor", () => {
     expect(roomFor({ width: 390, height: 60 })).toBeGreaterThan(100);
   });
 });
+
+// Obsidian's phone navbar is not part of the visual viewport - it floats over
+// it - so a panel sized to the viewport still ends up underneath it.
+describe("viewport minus the floating navbar", () => {
+  function fakeWin(navbarTop: number | null, height = 780): Window {
+    const bar = {
+      getBoundingClientRect: () => ({
+        top: navbarTop ?? 0,
+        bottom: height,
+        height: height - (navbarTop ?? 0),
+        left: 0,
+        right: 390,
+      }),
+      offsetParent: {},
+    };
+    return {
+      innerWidth: 390,
+      innerHeight: height,
+      visualViewport: { width: 390, height, offsetTop: 0, offsetLeft: 0 },
+      document: {
+        querySelector: (selector: string) =>
+          selector === ".mobile-navbar" && navbarTop !== null ? bar : null,
+      },
+    } as unknown as Window;
+  }
+
+  it("takes the navbar off the bottom", () => {
+    expect(viewport(fakeWin(724)).height).toBe(724);
+  });
+
+  it("leaves the height alone with no navbar in the way", () => {
+    expect(viewport(fakeWin(null)).height).toBe(780);
+  });
+
+  it("still leaves a usable strip if a bar somehow covers everything", () => {
+    expect(viewport(fakeWin(0)).height).toBeGreaterThanOrEqual(120);
+  });
+});