flexdesk 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "flexdesk",
-    "version": "0.3.0",
+    "version": "0.4.0",
     "description": "A tiling window manager and widget set for desktop-class web applications. Zero runtime dependencies.",
     "license": "MIT",
     "repository": {

package/src/tiling/shell.js

@@ -44,6 +44,7 @@ import { createContentRegistry } from './content_registry.js';
 import { createCommandPalette } from './command_palette.js';
 import { installKeymap } from './keymap.js';
 import { openTileTabSwitcher } from './tile_tab_menu.js';
+import { mountZoomControl } from './zoom.js';
 import { showContextMenu } from '../ui/components/context_menu.js';
 import { openForm } from '../ui/components/modal.js';
 
@@ -97,7 +98,12 @@ import { openForm } from '../ui/components/modal.js';
  *                                      embedder whose settings pane holds only
  *                                      the root element can change it live.
  * @param {object}     [cfg.chrome]     { topNav?, paletteButton?, desktops?,
- *                                        panelToggles?: { left?, right?, bottom? } }
+ *                                        panelToggles?: { left?, right?, bottom? },
+ *                                        zoom? }
+ *                                      `zoom` is C31: the element the content
+ *                                      zoom control is painted into — see
+ *                                      zoom.js. Absent, there is no control and
+ *                                      nothing is ever scaled.
  * @returns {Promise<object>} the frozen shell
  */
 export async function createShell({
@@ -185,6 +191,13 @@ export async function createShell({
     const paletteBtn = mountPaletteButton(chrome.paletteButton, palette);
     topNavEl = mountTopNav(chrome.topNav, taxonomy, wm);
     desktopsEl = mountDesktopBar(chrome.desktops, wm);
+    // C31. The content zoom. Painted with the rest of the chrome and, unlike the
+    // rest, AWAITED before the first mount: its saved value is applied to `root`
+    // as a CSS variable, and a shell that mounted first would paint every tile at
+    // 100% and then visibly jump to the user's zoom a moment later. A host with no
+    // saved zoom — or no `state` at all — resolves immediately to the default.
+    const zoom = mountZoomControl(chrome.zoom, { root, host });
+    if (zoom) await zoom.ready;
     // NOTE: bindPanelToggles CLONES the buttons (to strip whatever state the
     // embedder's own machinery left on them) and returns the FRESH nodes. The
     // originals are detached from here on — sync against the returned map, not
@@ -211,6 +224,9 @@ export async function createShell({
             topNavEl,
             desktopsEl,
             panelToggles: toggles,
+            // `get`/`set` so an embedder can drive the zoom from its own settings
+            // pane, or read it, without reaching into the control's DOM.
+            zoom,
         }),
         // A shell that can be built can be built TWICE — an embedder that
         // rebuilds on a context change (a different project, a different
@@ -229,6 +245,10 @@ export async function createShell({
             // captured before a rebuild, a promise that has not settled —
             // cannot repaint a dead tree into a root the live shell now owns.
             try { wm.renderer.destroy(); } catch (err) { log.warn?.('renderer teardown', err); }
+            // The zoom lives on `root` as a variable and a class. A rebuilt shell on
+            // the same root must not inherit the old one's scale with no control on
+            // screen to change it, so dispose puts the root back to 100%.
+            try { zoom?.dispose(); } catch { /* ignore */ }
         },
     });
 }

package/src/tiling/tile_tree.js

@@ -298,15 +298,27 @@ export class TileTree {
             }));
             n.activeTabIdx = Math.max(0,
                 Math.min(n.tabs.length - 1, saved.activeTabIdx || 0));
-            // The caller asked for a specific entity (props.id) OR for a
-            // page kind that ISN'T the nav category itself (e.g. `settings`
-            // lives under the `home` topNav). In both cases we must surface
-            // the requested target rather than silently showing whatever
-            // the restored page happened to hold. A bare top-nav click
-            // (target.kind === targetTopNav, no id) falls through and just
-            // restores the saved tabs as-is.
+            // The caller asked for a specific entity (props.id), for a page
+            // kind that ISN'T the nav category itself (e.g. `settings` lives
+            // under the `home` topNav), or for this page WITH PARTICULAR PROPS
+            // (a filter, an ad-hoc expression). In all three we must surface the
+            // requested target rather than silently showing whatever the
+            // restored page happened to hold.
+            //
+            // THE THIRD CASE WAS MISSING, and it is not a corner: "show me
+            // everything open on bo" is `kind: 'backlog'` with an `expr` and no
+            // id — no entity, and `backlog` IS its own nav category — so it fell
+            // through to the bare-restore branch and put back whatever the page
+            // last held. If that was a record you had been reading, the tile did
+            // not visibly change at all, and the click looked broken. (Found and
+            // fixed in BugDesk's fork first; this is that fix, upstream.)
+            //
+            // A BARE page switch still restores as-is, which is the whole point
+            // of archiving tabs: clicking a top-nav chip carries no props and
+            // must put back the tab you left open.
             const wantsTarget = target.props?.id != null
-                             || target.kind !== targetTopNav;
+                             || target.kind !== targetTopNav
+                             || Object.keys(target.props || {}).length > 0;
             if (wantsTarget) {
                 const wantId = target.props?.id != null;
                 const matchIdx = n.tabs.findIndex((t) =>
@@ -489,9 +501,19 @@ export class TileTree {
         };
         n.tabs = Array.isArray(n.tabs) ? n.tabs : [];
         n.tabs.push(tab);
-        n.activeTabIdx = n.tabs.length - 1;
-        _syncActiveTab(n);
-        return n.activeTabIdx;
+        // `background` appends WITHOUT switching to it — the caller asked for a
+        // tab to come back to, not for the page to change under them. Without
+        // this, "open in a background tab" was indistinguishable from an
+        // ordinary click: the tab arrived and took the screen with it.
+        //
+        // Returns the new tab's index either way, NOT `activeTabIdx`: for a
+        // background tab those differ, and a caller that wants to address the
+        // tab it just made needs the index of that tab.
+        if (!opts.background) {
+            n.activeTabIdx = n.tabs.length - 1;
+            _syncActiveTab(n);
+        }
+        return n.tabs.length - 1;
     }
 
     /** Switch the active tab on a leaf. No-op if `idx` is out of range. */

package/src/tiling/wm.js

@@ -3279,6 +3279,11 @@ export class WindowManager {
      *  `opts.transient` — the appended tab is not persisted/restored
      *                     (e.g. an add-row form). Only meaningful with
      *                     `newTab:true`.
+     *  `opts.background` — with `newTab`, append the tab WITHOUT switching to
+     *                     it or focusing its tile. "Open in a background tab"
+     *                     means the page you are reading stays in front;
+     *                     without it the tab arrives and takes the screen,
+     *                     which is what an ordinary click already does.
      *
      *  Back-compat: the legacy `opts.target` enum still works and maps
      *  onto the axes — 'auto'→origin, 'tab'→origin+newTab,
@@ -3289,6 +3294,8 @@ export class WindowManager {
      *  `openInWindow`) stay internal; callers prefer `wm.navigate(...)`. */
     navigate(kind, props = {}, opts = {}) {
         const { ctx = null, transient = false } = opts;
+        // Append the tab but stay where you are. Only meaningful with `newTab`.
+        const background = !!opts.background;
         // Resolve the two axes, honoring the legacy `target` alias.
         let { dest = 'main', newTab = false } = opts;
         if (opts.target != null) {
@@ -3314,12 +3321,12 @@ export class WindowManager {
         if (dest === 'window') return this._navigateWindow(kind, props);
         if (dest === 'main') {
             return newTab
-                ? this.openInTabInPrimary(kind, props, transient)
+                ? this.openInTabInPrimary(kind, props, transient, background)
                 : this.openInPrimary(kind, props);
         }
         // dest === 'origin'
         return newTab
-            ? this._navigateTab(ctx, kind, props, transient)
+            ? this._navigateTab(ctx, kind, props, transient, background)
             : this._navigateAuto(ctx, kind, props);
     }
 
@@ -3346,14 +3353,14 @@ export class WindowManager {
         this.openInPrimary(kind, props);
     }
 
-    _navigateTab(ctx, kind, props, transient = false) {
+    _navigateTab(ctx, kind, props, transient = false, background = false) {
         // Windows aren't tabbed — "open in tab" inside a window just
         // replaces the window's content.
         if (ctx?.windowId && this._windowToLeaf.has(ctx.windowId)) {
             this.openInWindow(ctx.windowId, kind, props);
             return;
         }
-        this.openInTabFromContext(ctx || {}, kind, props, transient);
+        this.openInTabFromContext(ctx || {}, kind, props, transient, background);
     }
 
     /** Spawn a fresh ManagedWindow with the requested content. No
@@ -3486,7 +3493,7 @@ export class WindowManager {
      *  Mirrors `openFromContext` (windowed / split-leaf / primary
      *  routing) but uses `appendLeafTab` so the existing content
      *  stays in place as a tab. */
-    openInTabFromContext(ctx, kind, props = {}, transient = false) {
+    openInTabFromContext(ctx, kind, props = {}, transient = false, background = false) {
         // Managed-window content: just open in the window — managed
         // windows aren't tabbed (one window = one content).
         if (ctx?.windowId && this._windowToLeaf.has(ctx.windowId)) {
@@ -3504,8 +3511,11 @@ export class WindowManager {
             this.openInPrimary(kind, props);
             return;
         }
-        tree.appendLeafTab(leafId, { kind, props }, _tabTitle(kind, props), { transient });
-        tree.focus(leafId);
+        tree.appendLeafTab(leafId, { kind, props }, _tabTitle(kind, props),
+            { transient, background });
+        // A BACKGROUND tab must not steal the tile's focus either — the point
+        // is that the user stays exactly where they were.
+        if (!background) tree.focus(leafId);
         this.renderer.render();
         this._persist();
         this._notifyChange('tab-open');
@@ -3518,7 +3528,7 @@ export class WindowManager {
      *  click from outside the tile system (e.g. the bottom-panel
      *  "Add row" button, which passes no ctx) reliably lands as a sibling
      *  tab in the main tile rather than swapping its content. */
-    openInTabInPrimary(kind, props = {}, transient = false) {
+    openInTabInPrimary(kind, props = {}, transient = false, background = false) {
         const tree = this._tree();
         const leafId = tree.primaryLeafId();
         // No content tile on this desktop (e.g. a panels-only layout) —
@@ -3526,8 +3536,11 @@ export class WindowManager {
         // caller asked for "a tab in the main tile"; with no main tile to
         // tab into, a floating window is the least-surprising fallback.
         if (!leafId) { this._navigateWindow(kind, props); return; }
-        tree.appendLeafTab(leafId, { kind, props }, _tabTitle(kind, props), { transient });
-        tree.focus(leafId);
+        tree.appendLeafTab(leafId, { kind, props }, _tabTitle(kind, props),
+            { transient, background });
+        // A BACKGROUND tab must not steal the tile's focus either — the point
+        // is that the user stays exactly where they were.
+        if (!background) tree.focus(leafId);
         this.renderer.render();
         this._persist();
         this._notifyChange('tab-open');

package/src/tiling/zoom.js

@@ -0,0 +1,248 @@
+/**
+ * zoom.js — the shell's content zoom: a − / track / + / readout control, and
+ * the one place that decides what "zoom the workspace" is allowed to touch.
+ *
+ * Opt-in, like every shell feature that changes what the user sees: an embedder
+ * that passes no `chrome.zoom` element gets no control and no scaling, so no
+ * existing consumer changes by upgrading. The control is Excel's — a continuous
+ * track with a detent-free middle, buttons either side that move in tens, and a
+ * readout that is itself the reset — because that is the shape people already
+ * know, and it is the one Tables shipped in its own status bar before this was
+ * lifted into the framework.
+ *
+ * ── WHAT IT SCALES, AND WHAT IT MUST NOT ───────────────────────────────────
+ *
+ * It scales CONTENT SURFACES and nothing a window is dragged across:
+ *
+ *     .twm-leaf__body          what a tile's content factory mounted into
+ *     .twm-window-content      what a promoted window's content mounted into
+ *
+ * and it does NOT scale the root, a leaf wrap, tile chrome, tab bars, or a
+ * window frame. That line is load-bearing rather than a matter of taste. CSS
+ * `zoom` establishes a scaled coordinate space, and FlexDesk's window drag,
+ * resize and snap all do arithmetic between the pointer (viewport pixels) and a
+ * window's `left`/`top` (the pixels of whatever contains it). A contained window
+ * (C21) lives in a LEAF WRAP and is re-parented to the ROOT for the length of a
+ * drag (R1); zoom either of those and every drag drifts by the zoom factor, and
+ * every C15 snap probe measures a tile in units the pointer is not in. Tile
+ * bodies and window content sit BELOW all of that geometry, so scaling them
+ * changes the text and none of the maths.
+ *
+ * ── HOW IT IS APPLIED ─────────────────────────────────────────────────────
+ *
+ * A CSS variable and a class, both on `root` — the element the embedder handed
+ * the shell. Never `document.body`, never a selector the framework did not
+ * author (the doctrine at the top of shell.js). Tiles and windows are created
+ * and destroyed long after any given change, so anything written element by
+ * element would have to be re-applied on every mount; a variable on the root is
+ * read by whatever exists at the time.
+ *
+ * The class is what keeps 100% free of any declaration. A rule that always said
+ * `zoom: var(--twm-zoom, 1)` would establish a scaled coordinate space even at
+ * 1, so at the default the class comes off and no `zoom` applies anywhere — an
+ * unzoomed shell lays out byte-for-byte as it did before this existed.
+ *
+ * A window an embedder mounts on `document.body` itself is outside the shell's
+ * root and therefore outside this: it is not the shell's to scale. Every window
+ * the WM promotes under `promoteInPlace` (C21) is inside the root, and so is
+ * every window for the duration of a drag.
+ *
+ * ── `zoom`, NOT `transform: scale()` ──────────────────────────────────────
+ *
+ * `zoom` reflows: text stays on the pixel grid, and a scroll container still
+ * measures the content it is scrolling. A transform would blur the text and
+ * leave the layout box at its old size, so a zoomed-in table would overflow a
+ * pane that did not know it had grown.
+ */
+
+/** The range. Below 50% a data row stops being readable; above 200% a typical
+ *  row no longer fits its own columns. */
+export const ZOOM_MIN = 50;
+export const ZOOM_MAX = 200;
+
+/** The track's granularity — fine, because a control you have to aim is one
+ *  people stop using. */
+export const ZOOM_STEP = 5;
+
+/** The BUTTONS' step: Excel's split, where the track is continuous and the − / +
+ *  cover ground. Commensurate with ZOOM_STEP by construction, so a button press
+ *  always lands on a notch and repeated presses cannot drift. */
+export const ZOOM_NUDGE = 10;
+
+/**
+ * Where the shell opens, and where a reset returns. Load-bearing: `applyZoom`
+ * removes the class at exactly this value, and that is what makes "unzoomed"
+ * mean "no declaration at all". Only true while the default IS 100.
+ */
+export const ZOOM_DEFAULT = 100;
+
+/** The logical key under the host's `state` capability. A per-person display
+ *  preference, persisted the same way the desktops are. */
+export const ZOOM_STATE_KEY = 'zoom';
+
+/**
+ * A number from anywhere — a slider, a stored preference, a caller — as a zoom
+ * the shell will accept.
+ *
+ * `null`, `undefined` and `''` are "no value" and read as the default. They are
+ * checked BEFORE the cast because `Number()` turns both `null` and `''` into 0 —
+ * a perfectly finite number that would then clamp to the floor, so a host with
+ * no saved zoom, or a read that failed, would silently open the shell at 50%.
+ *
+ * It QUANTISES, which is what makes 100% reachable: the track is stepped, so a
+ * stored 97 has to land on a notch rather than sit between two where neither the
+ * track nor the buttons can leave it.
+ */
+export function clampZoom(value) {
+    if (value == null || value === '') return ZOOM_DEFAULT;
+    const n = Number(value);
+    if (!Number.isFinite(n)) return ZOOM_DEFAULT;
+    const stepped = Math.round(n / ZOOM_STEP) * ZOOM_STEP;
+    return Math.min(ZOOM_MAX, Math.max(ZOOM_MIN, stepped));
+}
+
+/**
+ * Apply one zoom to a shell root. Idempotent. Takes the ELEMENT, never finds it.
+ *
+ * @param {Element} root     the shell's root
+ * @param {number}  percent  already clamped
+ */
+export function applyZoom(root, percent) {
+    if (!root?.style) return;
+    root.style.setProperty('--twm-zoom', String(percent / 100));
+    root.classList.toggle('twm-zoomed', percent !== ZOOM_DEFAULT);
+}
+
+/**
+ * Paint the control into the element the embedder handed over, restore the saved
+ * zoom, and keep the root in step.
+ *
+ * @param {Element|null} hostEl       where the control goes; absent → no control
+ * @param {object}       opts
+ * @param {Element}      opts.root    the shell root the zoom applies to
+ * @param {object}      [opts.host]   the host port; its `state` persists the zoom
+ * @param {string}      [opts.stateKey]
+ * @param {Function}    [opts.onChange] `(percent) => void`, after every change
+ * @returns {{el: Element, get: () => number, set: (percent: number) => void,
+ *            ready: Promise<number>, dispose: () => void} | null}
+ */
+export function mountZoomControl(hostEl, { root, host = null, stateKey = ZOOM_STATE_KEY, onChange } = {}) {
+    if (!hostEl || !root) return null;
+
+    const doc = hostEl.ownerDocument;
+    let current = ZOOM_DEFAULT;
+    let disposed = false;
+
+    const el = doc.createElement('div');
+    el.className = 'twm-zoom';
+
+    const stepButton = (label, title, delta) => {
+        const b = doc.createElement('button');
+        b.type = 'button';
+        b.className = 'twm-zoom__step';
+        b.textContent = label;
+        b.title = title;
+        b.setAttribute('aria-label', title);
+        b.addEventListener('click', () => commit(clampZoom(current + delta)));
+        return b;
+    };
+
+    const slider = doc.createElement('input');
+    slider.type = 'range';
+    slider.className = 'twm-zoom__slider';
+    slider.min = String(ZOOM_MIN);
+    slider.max = String(ZOOM_MAX);
+    slider.step = String(ZOOM_STEP);
+    slider.value = String(ZOOM_DEFAULT);
+    slider.title = `Zoom the workspace, ${ZOOM_MIN}–${ZOOM_MAX}% — double-click to reset.`;
+    slider.setAttribute('aria-label', 'Zoom the workspace');
+    // `input`, NOT `change`: the readout has to follow the thumb while it is
+    // being dragged, or the number under the mouse is the number you left.
+    slider.addEventListener('input', () => commit(clampZoom(slider.value)));
+    // A double-click on the track resets. It arrives after two mousedowns that
+    // each set the value and fire `input`, so the honest description is "one real
+    // write, then the reset", and a brief jump to wherever you clicked is visible
+    // before it snaps back. Excel's track does exactly that. It must not be
+    // "fixed" by swallowing `input` — that is the event the drag is made of.
+    slider.addEventListener('dblclick', () => commit(ZOOM_DEFAULT));
+
+    // The readout IS the reset, where Excel puts it and where a hand already is.
+    // A separate "100%" button would be a fourth control in a bar 20px tall, and a
+    // percentage nobody can click answers the question while refusing the obvious
+    // next request.
+    const readout = doc.createElement('button');
+    readout.type = 'button';
+    readout.className = 'twm-zoom__value';
+    readout.title = `Back to ${ZOOM_DEFAULT}%`;
+    readout.addEventListener('click', () => commit(ZOOM_DEFAULT));
+
+    el.append(
+        stepButton('−', `Zoom out ${ZOOM_NUDGE}%`, -ZOOM_NUDGE),
+        slider,
+        stepButton('+', `Zoom in ${ZOOM_NUDGE}%`, ZOOM_NUDGE),
+        readout,
+    );
+    hostEl.appendChild(el);
+
+    /** Paint the control and the root. No persistence — used by the restore,
+     *  where writing back what was just read would be a pointless round trip. */
+    const paint = (percent) => {
+        current = percent;
+        slider.value = String(percent);
+        readout.textContent = `${percent}%`;
+        applyZoom(root, percent);
+    };
+
+    // Debounced, because a drag fires `input` per pixel and each one would
+    // otherwise be a write through the host. A host without `state` is legal,
+    // exactly as it is for the desktops: the control still works, the zoom just
+    // does not survive a reload.
+    let saveTimer = 0;
+    const persist = (percent) => {
+        const state = host?.state;
+        if (!state) return;
+        clearTimeout(saveTimer);
+        saveTimer = setTimeout(() => {
+            Promise.resolve()
+                .then(() => state.write(stateKey, percent))
+                .catch((err) => console.warn('[zoom] save failed', err));
+        }, 400);
+    };
+
+    const commit = (percent) => {
+        if (disposed || percent === current) return;
+        paint(percent);
+        persist(percent);
+        try { onChange?.(percent); } catch (err) { console.warn('[zoom] onChange threw', err); }
+    };
+
+    paint(ZOOM_DEFAULT);
+
+    // Restored after the control is already on screen and usable: a zoom is not
+    // worth blocking a first paint on, and a failed read costs the default. The
+    // promise is returned so an embedder that DOES want to wait before mounting —
+    // to avoid content painting at 100% and then jumping — can.
+    const ready = Promise.resolve()
+        .then(() => host?.state?.read?.(stateKey))
+        .then((saved) => {
+            if (!disposed && saved != null) paint(clampZoom(saved));
+            return current;
+        })
+        .catch((err) => {
+            console.warn('[zoom] load failed', err);
+            return current;
+        });
+
+    return {
+        el,
+        get: () => current,
+        set: (percent) => commit(clampZoom(percent)),
+        ready,
+        dispose: () => {
+            disposed = true;
+            clearTimeout(saveTimer);
+            el.remove();
+            applyZoom(root, ZOOM_DEFAULT);
+        },
+    };
+}