flexdesk 0.2.0 → 0.4.0

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);
+        },
+    };
+}

package/src/ui/components/action_dropdown.js

@@ -174,13 +174,27 @@ export class ActionDropdown {
         // Position against trigger
         ActionDropdown.position(this.trigger, this.menuEl);
 
-        // Animate in
+        // Animate in.
+        //
+        // OPTIONAL CHAINING, AND IT IS LOAD-BEARING. This callback runs a frame
+        // after `open()` returned, and `destroy()` sets `this.menuEl = null`
+        // (see below) — so a dropdown that is opened and then destroyed inside
+        // one frame threw an uncaught `TypeError: Cannot read properties of
+        // null` out of an animation-frame callback, where no caller has a stack
+        // to catch it. That is not a hypothetical: it is what a user does every
+        // time they open a picker and then click something that unmounts the
+        // pane around it, and it was reproduced eighteen times in one run of a
+        // consumer's settings suite. Nothing is lost by skipping the class — the
+        // element it would have been added to no longer exists.
         requestAnimationFrame(() => {
-            this.menuEl.classList.add('visible');
+            this.menuEl?.classList.add('visible');
         });
 
         // Update trigger state
         this.trigger?.classList.add('twm-is-open');
+        if (this.trigger?.hasAttribute('aria-expanded')) {
+            this.trigger.setAttribute('aria-expanded', 'true');
+        }
 
         // Add document listeners
         document.addEventListener('click', this._boundHandleDocumentClick, true);
@@ -204,8 +218,16 @@ export class ActionDropdown {
             this.menuEl.hidden = true;
         }
 
-        // Update trigger state
+        // Update trigger state. `aria-expanded` belongs on the TRIGGER and has
+        // to be written on every close, not only on the ones a click caused —
+        // an embedder that synced it from its own click handler was announcing
+        // an expanded menu to a screen reader every time Escape or an outside
+        // click dismissed one. The component knows when it closed; nothing else
+        // reliably does.
         this.trigger?.classList.remove('twm-is-open');
+        if (this.trigger?.hasAttribute('aria-expanded')) {
+            this.trigger.setAttribute('aria-expanded', 'false');
+        }
 
         // Remove document listeners
         document.removeEventListener('click', this._boundHandleDocumentClick, true);
@@ -235,6 +257,15 @@ export class ActionDropdown {
      */
     _handleKeydown(e) {
         if (e.key === 'Escape') {
+            // AND NOBODY ELSE GETS IT. An open dropdown is the innermost thing
+            // on screen, so Escape means "close this" and nothing further —
+            // but the event was left to bubble, and inside a `ManagedWindow`
+            // (which binds its own Escape to dismiss) that meant one keystroke
+            // closed the dropdown AND the dialog around it. The user loses a
+            // form they were filling in because they changed their mind about
+            // one field.
+            e.preventDefault();
+            e.stopPropagation();
             this.close();
             this.trigger?.focus();
             return;

package/src/ui/components/autocomplete_field.js

@@ -80,6 +80,10 @@ export class AutocompleteField {
         this._activeIndex = -1;
         this._isOpen = false;
         this._disposers = [];
+        // Every call to the provider is numbered. See `#updateSuggestions`: a
+        // provider that answers over the network answers out of order, and the
+        // reply to "No" must not be allowed to overwrite the reply to "North".
+        this._suggestSeq = 0;
     }
 
     getValue() {
@@ -431,24 +435,68 @@ export class AutocompleteField {
     #updateSuggestions() {
         // Pass the fragment (variable part) for filtering, not the full composed value
         const fragment = this.#getInputFragment();
+
+        // A PROVIDER MAY ANSWER LATER THAN IT WAS ASKED.
+        //
+        // This used to require the answer synchronously — `provider(...) || []`
+        // straight into `Array.isArray`, so a provider that returned a promise
+        // produced an empty list and a dropdown that closed on every keystroke.
+        // That ruled out the entire class of completion source that lives on a
+        // server, which is most of them outside a single-page simulation: a
+        // table's rows, a query's result set, an index's matches.
+        //
+        // A provider that answers synchronously still takes the synchronous
+        // path, unchanged and untouched, so nothing that works today changes.
+        // A provider that hands back a thenable is awaited, and the reply is
+        // used only if it is the reply to the most recent question — typing
+        // "North" fires five requests and the network is free to answer them in
+        // any order, so without the sequence number the list can settle on the
+        // matches for "Nor".
+        const request = ++this._suggestSeq;
+        let produced;
         try {
-            const items = this.provider({ 
-                value: fragment, 
-                scope: this.scope, 
-                namespace: this.selectedNamespace 
-            }) || [];
-            this._items = Array.isArray(items) ? items : [];
-            this._activeIndex = items.length > 0 ? 0 : -1;
-            this.#renderDropdown();
-            if (items.length > 0) {
-                this.#open();
-            } else {
-                this.#close();
-            }
+            produced = this.provider({
+                value: fragment,
+                scope: this.scope,
+                namespace: this.selectedNamespace
+            });
         } catch (err) {
             this.logger?.warn?.('autocomplete', 'Provider error', { err });
             this._items = [];
             this.#close();
+            return;
+        }
+
+        if (produced && typeof produced.then === 'function') {
+            produced.then(
+                (items) => {
+                    if (request !== this._suggestSeq) return;
+                    this.#applySuggestions(items);
+                },
+                (err) => {
+                    this.logger?.warn?.('autocomplete', 'Provider error', { err });
+                    if (request !== this._suggestSeq) return;
+                    this._items = [];
+                    this.#close();
+                }
+            );
+            return;
+        }
+
+        this.#applySuggestions(produced);
+    }
+
+    /** Draw whatever the provider produced. Split out of `#updateSuggestions`
+     *  so the synchronous and the awaited paths cannot drift apart. */
+    #applySuggestions(produced) {
+        const items = Array.isArray(produced) ? produced : [];
+        this._items = items;
+        this._activeIndex = items.length > 0 ? 0 : -1;
+        this.#renderDropdown();
+        if (items.length > 0) {
+            this.#open();
+        } else {
+            this.#close();
         }
     }
 
@@ -714,6 +762,10 @@ export class AutocompleteField {
     }
 
     dispose() {
+        // Retire the outstanding question first. An awaited provider can answer
+        // after the field is gone, and `#applySuggestions` would then paint into
+        // a dropdown that has been removed and nulled.
+        this._suggestSeq += 1;
         // Close dropdown before cleanup
         this.#close();
         this._disposers.forEach((fn) => {

package/src/ui/components/context_menu.js

@@ -10,28 +10,65 @@
  *   ], (action) => { ... });
  *
  * The menu auto-closes on outside click / scroll / Escape.
+ *
+ * ── It is operable by keyboard ────────────────────────────────────────
+ * Items were bare `<div>`s with a click listener: no role, no tab stop, no
+ * arrow-key movement, and `showContextMenu` never moved focus into the menu.
+ * A consumer that opened this from Shift+F10 — the rail in Tables does — put a
+ * menu on screen that the keyboard could only dismiss. Every command in it was
+ * unreachable without a pointer, and nothing said so.
+ *
+ * So an item is a `<button role="menuitem">`, the first enabled one takes focus
+ * when the menu opens, Up/Down/Home/End move between them and wrap, Enter and
+ * Space activate, Escape closes, and focus returns to whatever had it before.
+ * Disabled items are skipped by the arrows rather than focusable-but-inert.
+ * `<button>` rather than a div with `tabindex`: the browser then gives Enter and
+ * Space for free and screen readers announce it without further help.
  */
 
+import { modalHost } from './modal.js';
+
 let _activeMenu = null;
+let _returnFocusTo = null;
 
 export function showContextMenu(x, y, items, onAction) {
     hideContextMenu();
 
+    // Whatever had focus when the menu opened gets it back when the menu
+    // closes. Without this a keyboard user who presses Escape is returned to
+    // `document.body` and has to tab back to where they were.
+    _returnFocusTo = document.activeElement;
+
     const menu = document.createElement('div');
     menu.className = 'twm-context-menu ea-context-menu';
+    menu.setAttribute('role', 'menu');
 
     for (const it of items) {
         if (it.separator) {
             const sep = document.createElement('div');
             sep.className = 'twm-context-menu__separator';
+            sep.setAttribute('role', 'separator');
             menu.appendChild(sep);
             continue;
         }
-        const row = document.createElement('div');
+        const row = document.createElement('button');
+        row.type = 'button';
+        row.setAttribute('role', 'menuitem');
         let cls = 'twm-context-menu-item';
         if (it.danger) cls += ' twm-delete-node';
         if (it.disabled) cls += ' disabled';
         row.className = cls;
+        if (it.disabled) {
+            row.disabled = true;
+            row.setAttribute('aria-disabled', 'true');
+        }
+        // A DISABLED ROW WITH NO EXPLANATION IS A DEAD CONTROL. `title` was
+        // accepted by callers and rendered by nothing — the item was built with
+        // one, the row silently dropped it, and the user got a greyed line with
+        // no way to learn why. It is the same shape as the classes this
+        // repository keeps finding: no error, no throw, and invisible to every
+        // test that checks the row is disabled.
+        if (it.title) row.title = it.title;
         row.innerHTML = `
             <span class="material-symbols-outlined">${it.icon || ''}</span>
             <span>${escapeHtml(it.label)}</span>
@@ -46,7 +83,12 @@ export function showContextMenu(x, y, items, onAction) {
         menu.appendChild(row);
     }
 
-    document.body.appendChild(menu);
+    // C25. THE SAME QUESTION A MODAL ASKS: which window is the user in? A
+    // consumer spanning two browser windows sets the host when its focus moves;
+    // null — every consumer today — is `document.body`, exactly as before. A
+    // menu in the wrong window is worse than a modal in the wrong window,
+    // because it is positioned at coordinates from the OTHER one.
+    (modalHost() || document.body).appendChild(menu);
     menu.style.display = 'block';
     _activeMenu = menu;
 
@@ -61,23 +103,52 @@ export function showContextMenu(x, y, items, onAction) {
     setTimeout(() => {
         document.addEventListener('mousedown', _outsideHandler, { once: true, capture: true });
     }, 0);
-    document.addEventListener('keydown', _escHandler);
+    document.addEventListener('keydown', _keyHandler);
     window.addEventListener('scroll', hideContextMenu, { once: true, capture: true });
+
+    // Focus the first item the keyboard can actually use. `preventScroll` so a
+    // menu opened near the bottom of a long page does not jump it.
+    _enabledItems(menu)[0]?.focus({ preventScroll: true });
 }
 
 export function hideContextMenu() {
     if (!_activeMenu) return;
+    const returnTo = _returnFocusTo;
+    const held = _activeMenu.contains(document.activeElement);
     _activeMenu.remove();
     _activeMenu = null;
-    document.removeEventListener('keydown', _escHandler);
+    _returnFocusTo = null;
+    document.removeEventListener('keydown', _keyHandler);
+    // Only take focus back if the menu still had it. A click elsewhere has
+    // already moved focus deliberately and must not be undone.
+    if (held && returnTo?.isConnected) returnTo.focus?.({ preventScroll: true });
 }
 
-function _outsideHandler(e) {
-    if (_activeMenu && !_activeMenu.contains(e.target)) hideContextMenu();
+function _enabledItems(menu) {
+    return [...menu.querySelectorAll('.twm-context-menu-item:not(.disabled)')];
+}
+
+/** Up/Down/Home/End move; the list WRAPS, which is what a menu of four items
+ *  wants and what every desktop menu does. Enter and Space are the button's
+ *  own, so they are not bound here. */
+function _keyHandler(e) {
+    if (!_activeMenu) return;
+    if (e.key === 'Escape') { e.preventDefault(); hideContextMenu(); return; }
+    const items = _enabledItems(_activeMenu);
+    if (items.length === 0) return;
+    const at = items.indexOf(document.activeElement);
+    let next = null;
+    if (e.key === 'ArrowDown')      next = items[(at + 1 + items.length) % items.length];
+    else if (e.key === 'ArrowUp')   next = items[(at - 1 + items.length) % items.length];
+    else if (e.key === 'Home')      next = items[0];
+    else if (e.key === 'End')       next = items[items.length - 1];
+    if (!next) return;
+    e.preventDefault();
+    next.focus({ preventScroll: true });
 }
 
-function _escHandler(e) {
-    if (e.key === 'Escape') hideContextMenu();
+function _outsideHandler(e) {
+    if (_activeMenu && !_activeMenu.contains(e.target)) hideContextMenu();
 }
 
 function escapeHtml(s) {