chamba 0.6.1 → 0.8.0

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

@@ -0,0 +1,380 @@
+// 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 Code Reviews
+// (reviews-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.
+//
+// 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
+// takes the whole row and the terminal is squeezed out - which is a state rather than a wider drag, so the
+// 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 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 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,
+    toolPages,
+    toolReviews,
+    toolSpecs,
+    toolTabs,
+} from "./dom.js";
+import {
+    DEFAULT_FRACTION,
+    defaultShape,
+    draggedTo,
+    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 { 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.
+const TOOLS = [
+    { id: PAGES, label: "Pages", panel: toolPages },
+    { id: SPECS, label: "Specs", panel: toolSpecs },
+    { id: REVIEWS, label: "Code Reviews", panel: toolReviews },
+];
+
+// 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, counted: true };
+const marks = new Map();
+// id -> the tool's own render function, handed over as it loads.
+const renderers = new Map();
+
+// --- 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() {
+    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();
+}
+
+/**
+ * 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 current.size;
+}
+
+/** The Pages tool's zoom, kept with the rest of the session's shape so one key has one writer. */
+export function rememberPageSize(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();
+}
+
+// --- The tools ---------------------------------------------------------------------------------------------------------------------------
+
+/**
+ * A tool says how to draw its panel. Called as the tool's module loads, which is why this module imports
+ * nothing that could still be half-built at that point.
+ */
+export function registerTool(id, render) {
+    renderers.set(id, render);
+}
+
+/** Whether the pane is open on that tool right now. */
+export function isToolOpen(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, counted = true } = {}) {
+    marks.set(id, { unread, empty, counted });
+    renderShell();
+}
+
+/** 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;
+    current.tool = id;
+    reshape();
+}
+
+function drawTabs() {
+    const tabs = TOOLS.map((tool) => {
+        const button = document.createElement("button");
+        button.type = "button";
+        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 mark = marks.get(tool.id) ?? EMPTY_MARK;
+        if (mark.unread > 0) {
+            const badge = document.createElement("span");
+            badge.className = mark.counted ? "tool-mark" : "tool-mark dot";
+            if (mark.counted) badge.textContent = String(mark.unread);
+            else badge.setAttribute("aria-label", "something new");
+            button.append(badge);
+        }
+        button.addEventListener("click", () => showTool(tool.id));
+        return button;
+    });
+    toolTabs.replaceChildren(...tabs);
+    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() {
+    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 && !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 && !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(current.tool) ?? EMPTY_MARK;
+    pane.hidden = false;
+    // There is no width worth choosing for a tool with nothing in it.
+    grip.hidden = mark.empty && current.collapsed;
+
+    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;
+    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.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(startSid = null) {
+    sid = startSid ?? null;
+    current = shapeOf(sid);
+    redraw();
+}
+
+/** Whether the pane is put away in this session, which is whether it is drawn as the spine. */
+export function isPaneCollapsed() {
+    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) {
+    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.
+        current.full = false;
+    } else {
+        current.width = reopenedFrom(current, window.innerWidth);
+    }
+    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) {
+    current.full = next;
+    if (current.full) current.collapsed = false;
+    reshape();
+}
+
+paneFull.addEventListener("click", () => setFull(!current.full));
+paneHalf.addEventListener("click", setHalf);
+paneCollapse.addEventListener("click", () => setPaneCollapsed(true));
+spine.addEventListener("click", () => setPaneCollapsed(false));
+
+// --- Saying that something arrived -------------------------------------------------------------------------------------------------------
+
+// One pulse of the pane's edge, in the workspace colour. ARRIVAL_MS must match the keyframes in styles.css.
+const ARRIVAL_MS = 1_000;
+let arrivalTimer = null;
+
+// The class comes off on a timer rather than on animationend, because with a reduced-motion preference there
+// is no animation to end - the stylesheet holds the highlight instead of pulsing it, and this is what makes
+// the two last the same moment.
+export function flashPane() {
+    clearTimeout(arrivalTimer);
+    // A pulse still running when the next page lands restarts rather than stacking: off, force the browser to
+    // notice, on again. Reading a layout property is what makes the restart real.
+    pane.classList.remove("arriving");
+    void pane.offsetWidth;
+    pane.classList.add("arriving");
+    arrivalTimer = setTimeout(() => pane.classList.remove("arriving"), ARRIVAL_MS);
+}
+
+// --- The divider -------------------------------------------------------------------------------------------------------------------------
+
+// Dragging sets a pixel width until it stops making sense, and below the threshold the pane becomes the
+// spine rather than a sliver. Pointer capture keeps the drag alive over the terminal and the frame alike -
+// a page is a document with its own event loop, and without capture the pointer would be lost in it.
+let dragging = false;
+// The width the pane had when the drag started. Dragging it shut is a request to put it away, not a request
+// for a 150px pane, so crossing the threshold hands its old width back rather than keeping the sliver the
+// pointer passed through on the way there.
+let widthBeforeDrag = null;
+
+grip.addEventListener("pointerdown", (event) => {
+    dragging = true;
+    widthBeforeDrag = current.width;
+    document.body.classList.add("dragging");
+    grip.setPointerCapture(event.pointerId);
+});
+
+grip.addEventListener("pointermove", (event) => {
+    if (!dragging) return;
+    const wanted = Math.max(0, window.innerWidth - event.clientX - grip.offsetWidth / 2);
+    // 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");
+    // 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);
+grip.addEventListener("pointercancel", endDrag);
+
+// The bar is chrome: a click on it must not leave the terminal without focus for no reason.
+panebar.addEventListener("mousedown", (event) => event.preventDefault());