chamba 0.7.0 → 0.9.0

package/templates/webterm/public/app/pane-shell.js

@@ -1,9 +1,10 @@
 // pane-shell.js - the pane itself: which tool is open in it, and how wide it is.
 //
-// The pane is furniture. What sits in it are tools - Pages (pane.js), Specs (specs-host.js) - and the line
-// between them is the whole point of this module: a tool draws inside its own panel and nothing else, while
-// the tab bar that says which tool is open, and the controls that say how wide the pane is, are drawn out
-// here. A tool can therefore never move the pane, and never lie about which tool the user is looking at.
+// The pane is furniture. What sits in it are tools - Home (home-host.js), Specs (specs-host.js), Code Reviews
+// (reviews-host.js) and Pages (pane.js) - and the line between them is the whole point of this module: a tool draws inside its
+// own panel and nothing else, while the tab bar that says which tool is open, and the controls that say how
+// wide the pane is, are drawn out here. A tool can therefore never move the pane, and never lie about which
+// tool the user is looking at.
 //
 // Width has three states, and only one of them is a width. Between the two ends the divider drags anything,
 // clamped as it always was. Past the near end the pane is put away and becomes the spine. Past the far end it
@@ -11,90 +12,158 @@
 // drag's own clamps stay where they are. The grip is reachable in every one of them, and dragging it is
 // always the way back.
 //
-// What the pane is belongs to the window - how wide, which tool, how big a page is drawn - and survives a
-// session switch and a reload. What is in a tool belongs to the session, and the tool keeps that itself.
+// What the pane is belongs to the session it is beside - how wide, which tool, how big a page is drawn, and
+// the reading theme - so switching sessions gives each one the pane it was left with, and a reload gives them
+// all back. What is in a tool belongs to the session too, and the tool keeps that itself.
 //
-// This module imports nothing but dom.js, deliberately: the tools import it and register themselves as they
-// load, so it has to be finished before any of them runs.
-
-import { grip, pane, panebar, paneCollapse, paneFull, spine, spineBadge, toolPages, toolSpecs, toolTabs } from "./dom.js";
+// This module imports dom.js and pane-shape.js and nothing else, deliberately: the tools import it and
+// register themselves as they load, so it has to be finished before any of them runs. Both of those are
+// leaves - pane-shape.js is the shape, its rules and its store, and it holds no element and reaches no
+// other module. Every rule about a shape lives there rather than here, so it can be run in a test; what is
+// left here is the pane as a thing on the screen.
+
+import {
+    grip,
+    pane,
+    panebar,
+    paneCollapse,
+    paneFull,
+    paneHalf,
+    spine,
+    spineBadge,
+    toolHome,
+    toolPages,
+    toolReviews,
+    toolSpecs,
+    toolTabs,
+} from "./dom.js";
+import {
+    DEFAULT_FRACTION,
+    defaultShape,
+    draggedTo,
+    HOME,
+    isDefaultWidth,
+    mergeShape,
+    PAGES,
+    pruneShapes,
+    REVIEWS,
+    readShapes,
+    reopenedFrom,
+    SPECS,
+} from "./pane-shape.js";
+
+// The tools' ids come from the shape, which holds one of them. Re-exported here because this module is the
+// pane, and a tool that asks whether it is open is asking the pane rather than the store.
+export { HOME, PAGES, REVIEWS, SPECS };
 
 // The tools, in the order their tabs are drawn. A tool is a tab, a panel, and a render function it hands over
 // when it loads; the pane knows nothing else about any of them.
-export const PAGES = "pages";
-export const SPECS = "specs";
 const TOOLS = [
-    { id: PAGES, label: "Pages", panel: toolPages },
+    { id: HOME, label: "Home", panel: toolHome },
     { id: SPECS, label: "Specs", panel: toolSpecs },
+    // "Reviews" on the tab and Code Reviews everywhere else: four tabs have to be readable at the width the
+    // pane reopens at, and the tab is the one place the tool's whole name does not fit.
+    { id: REVIEWS, label: "Reviews", panel: toolReviews },
+    { id: PAGES, label: "Pages", panel: toolPages },
 ];
 
-// Narrower than this and the pane is not a pane any more, so it becomes the spine instead. The mock's
-// threshold, and the width the spine itself takes.
-const COLLAPSE_AT = 150;
-// What the pane opens at, in a fraction of the window, and the most of the window a drag may give it.
-const DEFAULT_FRACTION = 0.44;
-const MAX_FRACTION = 0.7;
-// The least of the window the pane may come back into. Reopening is not the same as resizing: whatever width
-// it was put away at, a pane you have just asked for has to be wide enough to read a page in.
-const MIN_OPEN_FRACTION = 1 / 3;
-// The window's own pane preferences: how wide, whether it is collapsed, whether it has the whole row, which
-// tool is open, and how big a page is drawn in it. Not the session's - a pane is furniture, and furniture
-// does not move because you looked at another tab.
-const GEOMETRY_KEY = "webterm-pane";
-
-let width = null;
-// null means nobody has said. An untouched pane keeps out of the way while the tool it is open on has nothing
-// in it, and is open once that tool has something - which is the first page of a session opening on arrival,
-// as it always did. A click on the spine or on the collapse button is an answer, and from then on it is the
-// only one that counts.
-let collapsed = null;
-// The far end: the pane has the whole row and the terminal is squeezed out.
-let full = false;
-let openTool = PAGES;
-// How big a page is drawn. The pane applies it, so it is stored here with the rest of the furniture, and the
-// Pages tool owns the control and the steps.
-let pageSize = null;
-// What the last render decided, for the two things that only need to know whether the pane is showing.
-let shut = true;
+// The one shape this window is drawing, and the session it belongs to. One and not a map of them: the store
+// is shared by every window of this origin, so a shape held here from a session this window left is a copy
+// that has had time to go stale. It is read again on every move to another session instead.
+let sid = null;
+let current = defaultShape();
+// Whether a frame from the server named that session. The id this window opens with comes from its own
+// storage and is the session it is about to ask for, which is enough to draw in and not enough to write
+// under: the server may hand this window a different one, or none.
+let told = false;
 
 // id -> what that tool has to say for itself on its tab: how many things are waiting in it, and whether it
 // has anything at all. A tool nobody has heard from yet is empty and waiting on nothing.
-const EMPTY_MARK = { unread: 0, empty: true };
+const EMPTY_MARK = { unread: 0, empty: true, counted: true };
 const marks = new Map();
 // id -> the tool's own render function, handed over as it loads.
 const renderers = new Map();
 
-// --- What the window remembers -----------------------------------------------------------------------------------------------------------
-
-try {
-    const stored = JSON.parse(localStorage.getItem(GEOMETRY_KEY) ?? "{}");
-    if (typeof stored.width === "number" && stored.width >= COLLAPSE_AT) width = stored.width;
-    if (typeof stored.collapsed === "boolean") collapsed = stored.collapsed;
-    if (typeof stored.full === "boolean") full = stored.full;
-    if (TOOLS.some((tool) => tool.id === stored.tool)) openTool = stored.tool;
-    // The multiplier is stored rather than its position, so a window that was left at a size this version no
-    // longer offers falls back to the default instead of landing between two steps.
-    if (typeof stored.size === "number") pageSize = stored.size;
-} catch {
-    // A disabled or full store only means the pane opens at its default width, on its default tool.
-}
+// --- What every session remembers --------------------------------------------------------------------------------------------------------
 
+// Kept in the store, under the session this window is driving and no other. A window that has not been told
+// its session yet writes nothing: the id it opened with may turn out to be another window's session, and the
+// shape of that session is not this window's to set.
 function remember() {
-    try {
-        localStorage.setItem(GEOMETRY_KEY, JSON.stringify({ width, collapsed, full, tool: openTool, size: pageSize }));
-    } catch {
-        // The pane still works for this page's lifetime.
-    }
+    if (!told) return;
+    mergeShape(localStorage, sid, current);
+}
+
+// The shape of one session, off the store. A window with no session draws the defaults and stores nothing,
+// because there is nobody to store it under.
+function shapeOf(next) {
+    if (next === null) return defaultShape();
+    return readShapes(localStorage).get(next) ?? defaultShape();
+}
+
+// Draw everything the shape decides: the pane's own chrome, and the tool open in it, which has a bar and a
+// document to lay out at whatever width the pane now has.
+function redraw() {
+    renderShell();
+    renderers.get(current.tool)?.();
+}
+
+// The shape just changed, so keep it under this session and draw it. Every act on the pane ends here.
+function reshape() {
+    remember();
+    redraw();
 }
 
-/** How big a page was last drawn in this window, or null when nobody has said. */
+/**
+ * The window is beside that session now, so the pane is drawn in that session's own shape.
+ *
+ * The shape is read again here rather than kept from the load, so a window coming back to a session sees
+ * what it was left at, whichever window left it there. Called before the tools are told, because what they
+ * lay out depends on how wide the pane now is and on which of them is open in it.
+ */
+export function applySessionShape(next) {
+    const held = next ?? null;
+    // The first frame is worth acting on even where it names the session this window opened with: it is what
+    // makes the shape this window's to write, and the store may have moved since the page loaded.
+    if (held === sid && told) return;
+    // A drag in flight belongs to the session that is leaving. Ending it stores the width under that session
+    // rather than carrying the pointer into the next one's shape.
+    if (dragging) endDrag();
+    sid = held;
+    told = true;
+    current = shapeOf(held);
+    redraw();
+}
+
+/** A session that left the bar takes its pane shape with it, the way its unsent message and its page list do. */
+export function prunePaneShapes(live) {
+    pruneShapes(localStorage, live);
+}
+
+/** How big a page was last drawn in this session, or null when nobody has said. */
 export function storedPageSize() {
-    return pageSize;
+    return current.size;
 }
 
-/** The Pages tool's zoom, kept with the rest of the pane's furniture so one key has one writer. */
+/** The Pages tool's zoom, kept with the rest of the session's shape so one key has one writer. */
 export function rememberPageSize(size) {
-    pageSize = size;
+    current.size = size;
+    remember();
+}
+
+/** The reading theme this session was left on, or null for the system preference. */
+export function storedPaneTheme() {
+    return current.theme;
+}
+
+/**
+ * The Specs tool's reading theme, kept with the rest of the session's shape.
+ *
+ * The tool's frame has an opaque origin and therefore no storage of its own, so the pane holds the choice
+ * and hands it back with the session. Anything but the two palettes means the system preference.
+ */
+export function rememberPaneTheme(theme) {
+    current.theme = theme === "dark" || theme === "light" ? theme : null;
     remember();
 }
 
@@ -110,136 +179,155 @@ export function registerTool(id, render) {
 
 /** Whether the pane is open on that tool right now. */
 export function isToolOpen(id) {
-    return openTool === id;
+    return current.tool === id;
 }
 
 /**
  * What a tool has to say on its tab: `unread` is what is waiting for the user in it, and `empty` is whether
  * it has anything to show at all - which is what an untouched pane reads to decide whether to stay out of
  * the way.
+ *
+ * `counted` is whether that number is worth showing. A tool that asks the user things counts them, because
+ * two questions waiting is a different day from one. A tool that only receives counts nothing the user
+ * would act on differently, so its tab says that something arrived and leaves the number out of it.
  */
-export function noteTool(id, { unread = 0, empty = false } = {}) {
-    marks.set(id, { unread, empty });
+export function noteTool(id, { unread = 0, empty = false, counted = true } = {}) {
+    marks.set(id, { unread, empty, counted });
     renderShell();
 }
 
-/** Open a tool, drawing its panel. A tool the user chose is the tool this window opens on next time. */
+/** Open a tool, drawing its panel. A tool the user chose is the tool this session comes back on. */
 export function showTool(id) {
     if (!TOOLS.some((tool) => tool.id === id)) return;
-    openTool = id;
-    remember();
-    renderShell();
-    renderers.get(id)?.();
+    current.tool = id;
+    reshape();
 }
 
 function drawTabs() {
     const tabs = TOOLS.map((tool) => {
         const button = document.createElement("button");
         button.type = "button";
-        button.className = tool.id === openTool ? "tool-tab on" : "tool-tab";
+        button.className = tool.id === current.tool ? "tool-tab on" : "tool-tab";
         button.dataset.tool = tool.id;
         button.append(tool.label);
         // What is waiting in a tool nobody is looking at. The one thing a tab says beyond its name, so a tool
         // never has to take the screen to be noticed.
-        const waiting = (marks.get(tool.id) ?? EMPTY_MARK).unread;
-        if (waiting > 0) {
+        const mark = marks.get(tool.id) ?? EMPTY_MARK;
+        if (mark.unread > 0) {
             const badge = document.createElement("span");
-            badge.className = "tool-mark";
-            badge.textContent = String(waiting);
+            badge.className = mark.counted ? "tool-mark" : "tool-mark dot";
+            if (mark.counted) badge.textContent = String(mark.unread);
+            else badge.setAttribute("aria-label", "something new");
+            // The ring, for a tool something landed in a moment ago. This element is new on every redraw, so
+            // the ring would start from the beginning each time; a negative delay of what has already run
+            // puts it back where it was.
+            const ring = pulsing.get(tool.id);
+            if (ring) {
+                badge.classList.add("pulse");
+                badge.style.setProperty("--ring-delay", `-${Date.now() - ring.at}ms`);
+            }
             button.append(badge);
         }
         button.addEventListener("click", () => showTool(tool.id));
         return button;
     });
     toolTabs.replaceChildren(...tabs);
-    for (const tool of TOOLS) tool.panel.hidden = tool.id !== openTool;
+    for (const tool of TOOLS) tool.panel.hidden = tool.id !== current.tool;
 }
 
 // --- How wide ----------------------------------------------------------------------------------------------------------------------------
 
 // How wide, put away, or the whole row. Its own function because a drag is the one thing that changes the
 // pane without changing anything in it: sixty of these a second are cheap, and sixty full redraws are not.
-function applyGeometry(collapsedNow = shut) {
-    pane.classList.toggle("collapsed", collapsedNow);
+function applyGeometry() {
+    const { width, full, collapsed } = current;
+    pane.classList.toggle("collapsed", collapsed);
     // Only one of the two can be true: a pane that is put away has no width to be full of.
-    pane.classList.toggle("full", full && !collapsedNow);
+    pane.classList.toggle("full", full && !collapsed);
     // The width goes into a custom property rather than straight onto `width`, so the stylesheet keeps the
     // last word: the collapsed spine, the full row and the narrow-screen layout are rules, and an inline
     // width would beat all three.
     pane.style.setProperty("--pane-width", width === null ? `${DEFAULT_FRACTION * 100}%` : `${width}px`);
-    paneFull.classList.toggle("on", full && !collapsedNow);
-    const back = full && !collapsedNow;
+    paneFull.classList.toggle("on", full && !collapsed);
+    paneHalf.classList.toggle("on", isDefaultWidth(current));
+    const back = full && !collapsed;
     paneFull.title = back ? "Give the terminal its room back" : "Full width";
     paneFull.setAttribute("aria-label", paneFull.title);
 }
 
 /** Draw the pane's own chrome: the tabs, the width, and what the spine says while the pane is away. */
 export function renderShell() {
-    const mark = marks.get(openTool) ?? EMPTY_MARK;
-    shut = collapsed === null ? mark.empty : collapsed;
+    const mark = marks.get(current.tool) ?? EMPTY_MARK;
     pane.hidden = false;
     // There is no width worth choosing for a tool with nothing in it.
-    grip.hidden = mark.empty && shut;
+    grip.hidden = mark.empty && current.collapsed;
 
-    applyGeometry(shut);
+    applyGeometry();
     drawTabs();
 
     // The spine stands for the whole pane, so it carries what every tool is waiting on, not just the open one.
+    // It counts what the tools count, and falls back to the bare dot when all that arrived was uncounted:
+    // a number here has to mean the same thing it means on a tab.
     let waiting = 0;
-    for (const entry of marks.values()) waiting += entry.unread;
+    let arrived = false;
+    for (const entry of marks.values()) {
+        if (entry.unread <= 0) continue;
+        if (entry.counted) waiting += entry.unread;
+        else arrived = true;
+    }
     spineBadge.textContent = waiting > 0 ? String(waiting) : "";
-    spineBadge.hidden = waiting === 0;
+    spineBadge.classList.toggle("dot", waiting === 0 && arrived);
+    spineBadge.hidden = waiting === 0 && !arrived;
 }
 
 /**
  * Draw the pane for the first time, on the tool this window was left on. Called from the entry rather than
  * here, because the tools register as they load and there is no pane to draw until they all have.
  */
-export function mountPane() {
-    renderShell();
-    renderers.get(openTool)?.();
-}
-
-/** Whether the pane is drawn as the spine rather than as a pane. */
-export function isPaneShut() {
-    return shut;
+export function mountPane(startSid = null) {
+    sid = startSid ?? null;
+    current = shapeOf(sid);
+    redraw();
 }
 
-/** Whether the user put the pane away, as opposed to never having said. */
+/** Whether the pane is put away in this session, which is whether it is drawn as the spine. */
 export function isPaneCollapsed() {
-    return collapsed === true;
+    return current.collapsed;
 }
 
 // Away, and back. Two ways in and one way out, because the pane is put away far more often than it is
 // resized: the button in the bar is the obvious one, and dragging the grip past the threshold is the other.
 export function setPaneCollapsed(next) {
-    collapsed = next;
-    shut = next;
-    if (collapsed) {
+    current.collapsed = next;
+    if (current.collapsed) {
         // Coming back to a pane that fills the window, with the terminal nowhere, is not what putting one
         // away asks for. The width it had is remembered; the far end is not.
-        full = false;
+        current.full = false;
     } else {
-        // Back at whatever width it had, unless that width would be a sliver - a pane dragged shut, or one
-        // from a window remembered narrower than this one, has to open into something a page fits in.
-        const floor = Math.min(window.innerWidth * MIN_OPEN_FRACTION, window.innerWidth * MAX_FRACTION);
-        if (width !== null && width < floor) width = floor;
+        current.width = reopenedFrom(current, window.innerWidth);
     }
-    remember();
-    renderShell();
-    renderers.get(openTool)?.();
+    reshape();
+}
+
+// Back to the width the pane opens at. Not a width of its own: the pane is left with none, and the
+// stylesheet draws the default fraction, so a window resized afterwards leaves the pane at half rather
+// than at the pixels half happened to be when the button was pressed.
+function setHalf() {
+    current.width = null;
+    current.full = false;
+    current.collapsed = false;
+    reshape();
 }
 
 // The far end, and back. A press either way, and a drag of the grip is the other way back.
 function setFull(next) {
-    full = next;
-    if (full) collapsed = false;
-    remember();
-    renderShell();
-    renderers.get(openTool)?.();
+    current.full = next;
+    if (current.full) current.collapsed = false;
+    reshape();
 }
 
-paneFull.addEventListener("click", () => setFull(!full));
+paneFull.addEventListener("click", () => setFull(!current.full));
+paneHalf.addEventListener("click", setHalf);
 paneCollapse.addEventListener("click", () => setPaneCollapsed(true));
 spine.addEventListener("click", () => setPaneCollapsed(false));
 
@@ -262,6 +350,33 @@ export function flashPane() {
     arrivalTimer = setTimeout(() => pane.classList.remove("arriving"), ARRIVAL_MS);
 }
 
+// Three turns of the ring in styles.css, which runs for 1.6s each. The two numbers have to agree: the
+// keyframes are there and what takes the ring off again is here.
+const TAB_PULSE_MS = 4_800;
+
+// id -> when that tool's ring started, and the timer that ends it. A tab is rebuilt on every redraw, so the
+// ring cannot be left on the element the way the pane's own flash is - what holds it is this map.
+const pulsing = new Map();
+
+/**
+ * Something landed in a tool the user is not looking at, so its tab draws a ring around its mark for three
+ * turns and then rests.
+ *
+ * A second arrival during those three turns starts them again, which is what the mark means: the tab says
+ * that something arrived just now, and the number beside it says how much is waiting.
+ */
+export function pulseTool(id) {
+    clearTimeout(pulsing.get(id)?.timer);
+    pulsing.set(id, {
+        at: Date.now(),
+        timer: setTimeout(() => {
+            pulsing.delete(id);
+            renderShell();
+        }, TAB_PULSE_MS),
+    });
+    renderShell();
+}
+
 // --- The divider -------------------------------------------------------------------------------------------------------------------------
 
 // Dragging sets a pixel width until it stops making sense, and below the threshold the pane becomes the
@@ -275,37 +390,27 @@ let widthBeforeDrag = null;
 
 grip.addEventListener("pointerdown", (event) => {
     dragging = true;
-    widthBeforeDrag = width;
+    widthBeforeDrag = current.width;
     document.body.classList.add("dragging");
     grip.setPointerCapture(event.pointerId);
 });
 
 grip.addEventListener("pointermove", (event) => {
     if (!dragging) return;
-    // A drag is a width, so it is the way out of the far end as well as the way into any other width.
-    full = false;
     const wanted = Math.max(0, window.innerWidth - event.clientX - grip.offsetWidth / 2);
-    if (wanted < COLLAPSE_AT) {
-        collapsed = true;
-        width = widthBeforeDrag;
-    } else {
-        collapsed = false;
-        width = Math.min(wanted, window.innerWidth * MAX_FRACTION);
-    }
-    // A drag is an answer too, so what it decides is what the next render starts from.
-    shut = collapsed;
-    applyGeometry(shut);
+    // A drag is a width, so it is the way into every state the pane has and the way out of each of them.
+    // Where each of those states begins is pane-shape.js's rule; what is left here is the pointer.
+    Object.assign(current, draggedTo(wanted, window.innerWidth, widthBeforeDrag));
+    applyGeometry();
 });
 
 function endDrag() {
     if (!dragging) return;
     dragging = false;
     document.body.classList.remove("dragging");
-    remember();
-    // A drag that crossed the threshold changed which of the three states the pane is in, and the tool that
-    // is open in it has a bar and a document to lay out again at the new width.
-    renderShell();
-    renderers.get(openTool)?.();
+    // The shape changed under the pointer, and only the geometry followed it. A drag that crossed either
+    // threshold also changed which of the three states the pane is in, which the tool has to hear about.
+    reshape();
 }
 
 grip.addEventListener("pointerup", endDrag);