flexdesk 0.1.0

package/src/tiling/loading_overlay.js

@@ -0,0 +1,33 @@
+/**
+ * loading_overlay.js — the canonical "content is loading" overlay.
+ *
+ * An absolutely-positioned spinner layer dropped over a slot while an async
+ * mount is in flight, with an 80ms grace period so cache hits / instant
+ * renders never strobe a spinner. Returns a `done()` that removes it.
+ *
+ * Uses the global `twm-tile-loading` styles (ui/css/tiling/host.css). Shared
+ * by the WM page-stub shell and the agent Code tab's split view.
+ *
+ *   const done = makeLoadingOverlay(slot);
+ *   try { await mount(); } finally { done(); }
+ */
+
+/** Drop a loading overlay over `slot` and return a `done()` to remove it.
+ *  The overlay stays invisible for `delay` ms (default 80) so fast renders
+ *  don't flash a spinner. `slot` must be a positioned ancestor (or pass one
+ *  that is); the overlay is `position:absolute; inset:0`. */
+export function makeLoadingOverlay(slot, { delay = 80 } = {}) {
+    const overlay = document.createElement('div');
+    overlay.className = 'twm-tile-loading twm-tile-loading--pending';
+    overlay.innerHTML =
+        '<div class="twm-tile-loading__spinner" aria-label="Loading"></div>';
+    slot.appendChild(overlay);
+    // Promote to visible only if the mount hasn't finished within the grace.
+    const showTimer = setTimeout(() => {
+        overlay.classList.remove('twm-tile-loading--pending');
+    }, delay);
+    return () => {
+        clearTimeout(showTimer);
+        overlay.remove();
+    };
+}

package/src/tiling/nav_panel.js

@@ -0,0 +1,142 @@
+/**
+ * nav_panel.js — the left navigation panel-tile: a mode strip, a shared
+ * filter box, and one lazily-mounted pane per mode.
+ *
+ *   ┌─[ mode ][ mode ][ mode ]─────┐   mode tabs
+ *   │ ┌──────────────────────────┐ │
+ *   │ │ Filter…                  │ │   unified filter (sidebar-controls)
+ *   │ └──────────────────────────┘ │
+ *   │ ┌──────────────────────────┐ │
+ *   │ │ (pane body)              │ │
+ *   │ └──────────────────────────┘ │
+ *
+ * The panel owns the strip, the filter and the pane hosts. It owns NONE of
+ * the panes: the embedder passes them in. There used to be three hardcoded
+ * modes here (a file tree, an object tree, a git view) plus a dead category
+ * browser; all of that is the embedder's, and lives on its side now.
+ *
+ * A mode:
+ *
+ *   {
+ *     id, icon, label,
+ *     mount(paneEl, { wm, eventBus }) -> {
+ *        activate?(),       // called every time the mode is selected (may be async)
+ *        filter?(query),    // the shared filter box changed
+ *        destroy?(),
+ *     }
+ *   }
+ *
+ * `mount()` runs at most once, the first time its mode is selected.
+ * `activate()` runs on every selection, INCLUDING the first — a pane that
+ * has to rebuild on each visit (a git status list, say) does its work there.
+ * The filter query is remembered per mode.
+ */
+
+export function mountNavPanel(hostEl, {
+    modes = [],
+    wm = null,
+    eventBus = null,
+    filterPlaceholder = 'Filter…',
+} = {}) {
+    if (!Array.isArray(modes) || modes.length === 0) {
+        throw new Error('mountNavPanel: at least one mode is required');
+    }
+
+    hostEl.classList.add('twm-nav');
+    hostEl.innerHTML = `
+        <div class="twm-nav__modes" data-role="modes"></div>
+        <div class="twm-sidebar-controls twm-nav__filter">
+            <span class="material-symbols-outlined twm-sidebar-search-icon">search</span>
+            <input class="twm-data-page__search twm-nav__filter-input"
+                   type="search" placeholder="${_esc(filterPlaceholder)}"
+                   autocomplete="off" />
+        </div>
+        <div class="twm-nav__body" data-role="body"></div>
+    `;
+    const modesEl = hostEl.querySelector('[data-role="modes"]');
+    const bodyEl  = hostEl.querySelector('[data-role="body"]');
+    const filterEl = hostEl.querySelector('.twm-nav__filter-input');
+
+    modesEl.innerHTML = modes.map((m) => `
+        <button class="twm-nav__mode twm-has-tooltip" data-mode="${_esc(m.id)}"
+                data-tooltip="${_esc(m.label)}">
+            <span class="material-symbols-outlined">${_esc(m.icon)}</span>
+            <span>${_esc(m.label)}</span>
+        </button>
+    `).join('');
+
+    const byId = new Map(modes.map((m) => [m.id, m]));
+    const hosts = {};   // mode id -> pane host element
+    const panes = {};   // mode id -> the object the mode's mount() returned
+    const filterByMode = Object.fromEntries(modes.map((m) => [m.id, '']));
+    let mode = modes[0].id;
+
+    const ensureHost = (id) => {
+        if (hosts[id]) return hosts[id];
+        const el = document.createElement('div');
+        el.className = `twm-nav__pane twm-nav__pane--${id}`;
+        el.style.display = 'none';
+        bodyEl.appendChild(el);
+        hosts[id] = el;
+        return el;
+    };
+
+    const activate = async (next) => {
+        const def = byId.get(next);
+        if (!def) return;
+        mode = next;
+        for (const m of modes) {
+            ensureHost(m.id).style.display = (m.id === next) ? 'flex' : 'none';
+        }
+        modesEl.querySelectorAll('[data-mode]').forEach((b) =>
+            b.classList.toggle('twm-nav__mode--on', b.dataset.mode === next));
+        filterEl.value = filterByMode[next] || '';
+
+        const paneEl = ensureHost(next);
+        if (!panes[next]) {
+            try { panes[next] = def.mount(paneEl, { wm, eventBus }) || {}; }
+            catch (err) {
+                console.error('[nav] mode mount failed', next, err);
+                panes[next] = {};
+            }
+        }
+        // `activate()` runs on EVERY selection, including the first. A pane that
+        // must rebuild on each visit (a git status list) does its work here.
+        try { await panes[next].activate?.(); }
+        catch (err) { console.error('[nav] mode activate failed', next, err); }
+        _applyFilter();
+    };
+
+    const _applyFilter = () => {
+        const q = filterByMode[mode] || '';
+        try { panes[mode]?.filter?.(q); }
+        catch (err) { console.warn('[nav] filter failed', mode, err); }
+    };
+
+    filterEl.addEventListener('input', () => {
+        filterByMode[mode] = filterEl.value;
+        _applyFilter();
+    });
+
+    modesEl.addEventListener('click', (e) => {
+        const btn = e.target.closest('[data-mode]');
+        if (btn) activate(btn.dataset.mode);
+    });
+
+    activate(mode);
+
+    return {
+        refresh: () => activate(mode),
+        destroy: () => {
+            for (const p of Object.values(panes)) {
+                try { p?.destroy?.(); } catch { /* ignore */ }
+            }
+        },
+    };
+}
+
+function _esc(s) {
+    return String(s ?? '').replace(/[&<>"']/g, (c) => (
+        { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]
+    ));
+}

package/src/tiling/page_factory.js

@@ -0,0 +1,215 @@
+/**
+ * page_factory.js — the MECHANISM behind a tile's content, with no
+ * knowledge of what that content is about.
+ *
+ * `createPageFactories()` returns the four wrappers an embedder uses to
+ * turn its own page/tab modules into content factories:
+ *
+ *     tabFactory(kind, factory)      breadcrumb page-shell + a mounted tab
+ *     bareTabFactory(kind, factory)  same, minus the breadcrumb (transient forms)
+ *     stubPageFactory(kind, render)  breadcrumb + a plain render fn + loading overlay
+ *     mountTabBody / makeShim        the pieces the three are built from
+ *
+ * ── makeShim: the navigation contract ─────────────────────────────────
+ * Mounted content receives a `workspaceTabs` object. That object IS the
+ * library's public navigation API in embryo:
+ *
+ *     openTab      open a kind in THIS tile          (openFromContext)
+ *     openInTab    open it as a new TAB in this tile (openInTabFromContext)
+ *     openInWindow open it in a fresh managed window
+ *     updateProps  persist editor sub-state into this tile's tab props
+ *     closeTab     close this tab (falls back to closing the tile)
+ *     notifyChanged  broadcast "I mutated the project" so sidebars refresh
+ *
+ * ── refreshOn / events: no bus-name literals here ─────────────────────
+ * This module used to hardcode five bus names (`<domain>:run:tick`, …) and
+ * one mutation event. Both are now INJECTED:
+ *
+ *     refreshOn  { [busEvent]: reasonString }  fanned into tab.refresh(reason)
+ *     events     { projectChanged? }           emitted by close/notifyChanged
+ *
+ * An absent key means an absent subscription / an absent emit, so an
+ * embedder with no run loop simply passes `{}` and nothing fires.
+ */
+
+import { makeLoadingOverlay } from './loading_overlay.js';
+import { mountTileBreadcrumb } from './tile_breadcrumb.js';
+
+/**
+ * @param {object}  cfg
+ * @param {object}  cfg.eventBus   the embedder's bus (may be null)
+ * @param {object}  cfg.events     { projectChanged?: string }
+ * @param {object}  cfg.refreshOn  { [busEventName]: reason } -> tab.refresh(reason)
+ */
+export function createPageFactories({ eventBus = null, events = {}, refreshOn = {} } = {}) {
+    const projectChanged = events?.projectChanged || null;
+
+    // The `workspaceTabs` API tile content calls to open/close tabs and
+    // broadcast mutations. Shared by breadcrumbed and bare tabs.
+    const makeShim = (ctx) => ({
+        // Route through openFromContext so navigation triggered from a
+        // split tile / window stays in that container.
+        openTab: ({ kind: k, entityId, label, icon, subTab }) =>
+            ctx.wm?.openFromContext(ctx, k, { id: entityId, label, icon, subTab }),
+        // Open the same content as a NEW TAB in the current tile.
+        openInTab: ({ kind: k, entityId, label, icon, subTab }) =>
+            ctx.wm?.openInTabFromContext(ctx, k, { id: entityId, label, icon, subTab }),
+        // Open the same content in a fresh managed window.
+        openInWindow: ({ kind: k, entityId, label, icon, subTab }) =>
+            ctx.wm?.navigate(k, { id: entityId, label, icon, subTab }, { ctx, dest: 'window' }),
+        // Persist editor sub-state into this tile's WM tab props.
+        updateProps: (patch) => {
+            try { ctx.wm?.updateActiveTabProps?.(ctx.leafId, patch); }
+            catch (err) { console.warn('[shim] updateProps failed', err); }
+        },
+        // Close just THIS tab (not the whole tile); falls back to closing
+        // the tile when it's the last tab. Also broadcasts so sidebars /
+        // landings / nav refresh against the mutated project state.
+        closeTab: (_id) => {
+            if (projectChanged) {
+                try { eventBus?.emit?.(projectChanged, { source: 'twm-tab-close' }); } catch {}
+            }
+            try { ctx.wm?.closeActiveTab?.(ctx.leafId); } catch (err) {
+                console.warn('[shim] closeTab failed', err);
+            }
+        },
+        // Non-closing mutations (Save/New/Rename) broadcast so listeners refresh.
+        notifyChanged: (domain) => {
+            if (!projectChanged) return;
+            try {
+                eventBus?.emit?.(projectChanged,
+                    { source: 'tab-mutation', domain: domain || null });
+            } catch {}
+        },
+        registerProvider: () => {},
+        getActiveTab: () => null,
+    });
+
+    // Run a content factory inside a content slot: build the shim, mount
+    // the tab, drive the loading overlay, and fan the embedder's declared
+    // events into the tab's refresh(reason) hook (tabs that don't
+    // self-subscribe would otherwise freeze mid-run). Returns a teardown
+    // that removes listeners + disposes the tab.
+    const mountTabBody = (factory, contentSlot, props, ctx) => {
+        const shim = makeShim(ctx);
+        const tab = factory(contentSlot, props?.id ?? props?.entityId ?? null, {
+            logger: null, eventBus, workspaceTabs: shim,
+            wm: ctx.wm, leafId: ctx.leafId, windowId: ctx.windowId,
+        });
+        const hideLoading = makeLoadingOverlay(contentSlot);
+        try {
+            const ret = tab?.mount?.(props);
+            if (ret && typeof ret.then === 'function') {
+                ret.then(hideLoading, (err) => {
+                    console.error('[page] mount failed', err);
+                    hideLoading();
+                });
+            } else {
+                requestAnimationFrame(hideLoading);
+            }
+        } catch (err) {
+            console.error('[page] mount failed', err);
+            hideLoading();
+        }
+        const listeners = {};
+        if (typeof tab?.refresh === 'function' && eventBus?.on) {
+            for (const [busEvent, reason] of Object.entries(refreshOn || {})) {
+                const fn = () => {
+                    try { tab.refresh(reason); }
+                    catch (err) { console.warn('[page] refresh failed', busEvent, err); }
+                };
+                listeners[busEvent] = fn;
+                eventBus.on(busEvent, fn);
+            }
+        }
+        return () => {
+            for (const [n, fn] of Object.entries(listeners)) {
+                try { eventBus?.off?.(n, fn); } catch {}
+            }
+            try { tab?.dispose?.(); tab?.unmount?.(); } catch {}
+        };
+    };
+
+    /** Wrap a tab factory in a "page shell" — breadcrumb strip at the top,
+     *  content fills the rest. `kind` is captured at build time so the
+     *  breadcrumb knows which crumbs to build. */
+    const tabFactory = (kind, factory) => (host, props, ctx) => {
+        host.classList.add('twm-page-shell');
+        host.innerHTML = '';
+        const contentSlot = document.createElement('div');
+        contentSlot.className = 'twm-page-shell__content';
+        // Focusable via JS so `document.activeElement` lands inside the
+        // page when the tile is activated.
+        contentSlot.tabIndex = -1;
+
+        // A breadcrumb navigates the host TILE — meaningless for an entity
+        // opened in a standalone managed window, where we want only the
+        // entity view. Skip the crumb when mounted in a window.
+        let crumb = null;
+        if (!ctx?.windowId) {
+            const breadcrumbSlot = document.createElement('div');
+            breadcrumbSlot.className = 'twm-page-shell__breadcrumb';
+            host.appendChild(breadcrumbSlot);
+            crumb = mountTileBreadcrumb(kind, props, { ...ctx, eventBus });
+            breadcrumbSlot.appendChild(crumb.el);
+        }
+        host.appendChild(contentSlot);
+
+        const teardown = mountTabBody(factory, contentSlot, props, ctx);
+        return {
+            destroy: () => {
+                teardown();
+                try { crumb?.destroy(); } catch {}
+            },
+        };
+    };
+
+    // Like tabFactory but with NO breadcrumb chrome — for transient /
+    // form content (e.g. an add-row entry mask) that isn't an entity
+    // view. Content still gets the full ctx (wm/leafId) + shim, so it
+    // can self-close via wm.closeActiveTab.
+    const bareTabFactory = (kind, factory) => (host, props, ctx) => {
+        host.classList.add('twm-page-shell');
+        host.innerHTML = '';
+        const contentSlot = document.createElement('div');
+        contentSlot.className = 'twm-page-shell__content';
+        contentSlot.tabIndex = -1;
+        host.appendChild(contentSlot);
+        return { destroy: mountTabBody(factory, contentSlot, props, ctx) };
+    };
+
+    /** Page with a breadcrumb at the top and a plain `render(slot, props, ctx)`
+     *  body — for content that isn't a full tab object. If `render` returns a
+     *  `ready` promise the loading overlay waits on it. */
+    const stubPageFactory = (kind, render) => (host, props, ctx) => {
+        host.classList.add('twm-page-shell');
+        host.innerHTML = '';
+        const breadcrumbSlot = document.createElement('div');
+        breadcrumbSlot.className = 'twm-page-shell__breadcrumb';
+        const contentSlot = document.createElement('div');
+        contentSlot.className = 'twm-page-shell__content';
+        contentSlot.tabIndex = -1;
+        host.appendChild(breadcrumbSlot);
+        host.appendChild(contentSlot);
+        const crumb = mountTileBreadcrumb(kind, props, { ...ctx, eventBus });
+        breadcrumbSlot.appendChild(crumb.el);
+        const hideLoading = makeLoadingOverlay(contentSlot);
+        const ret = render(contentSlot, props, ctx) || {};
+        // Most landings kick off their own async refresh after the
+        // synchronous render returns. If render exposes a `ready`
+        // promise we await it; otherwise hide on the next frame.
+        if (ret.ready && typeof ret.ready.then === 'function') {
+            ret.ready.then(hideLoading, hideLoading);
+        } else {
+            requestAnimationFrame(hideLoading);
+        }
+        return {
+            title: ret.title,
+            destroy: () => { try { crumb.destroy(); } catch {} ret.destroy?.(); },
+        };
+    };
+
+    return Object.freeze({
+        makeShim, mountTabBody, tabFactory, bareTabFactory, stubPageFactory,
+    });
+}

package/src/tiling/panel_keys.js

@@ -0,0 +1,145 @@
+/**
+ * panel_keys.js — central keyboard router for panel-local navigation.
+ *
+ * THE PROBLEM IT SOLVES
+ * ---------------------
+ * Several panels want plain-key navigation (↑/↓ to move a cursor, Enter to
+ * open, single letters for actions): the landing tables, the top-nav
+ * overview pages, and any future browser panel. Each one used to attach its
+ * OWN `document` keydown listener gated by the heuristic
+ *
+ *     hostEl.contains(document.activeElement) || activeElement === <body>
+ *
+ * That heuristic is wrong as soon as there is more than one tile. When the
+ * user selects a different tile, focus usually rests on `<body>`, so EVERY
+ * mounted landing's listener still fires — the "main" panel keeps eating
+ * arrow keys even though another panel is selected, and two panels can move
+ * their cursors at once. The selected tile is never actually consulted.
+ *
+ * THE CONCEPT
+ * -----------
+ * One listener, one authority. Panels do not listen on `document`
+ * themselves; they REGISTER a handler bound to their host element. On each
+ * keydown the router asks the window manager which leaf is currently
+ * focused (the single source of truth — `WindowManager.focusedLeafEl()`)
+ * and dispatches the event to the handler whose host lives inside that leaf
+ * — and to no one else. A panel automatically receives keys exactly when,
+ * and only when, it is the selected tile.
+ *
+ * Content rendered OUTSIDE the tile tree (a promoted managed window or a
+ * floating shell) has no focused-leaf concept; for those hosts the router
+ * falls back to the focus-containment scope so they keep working.
+ *
+ * USAGE
+ * -----
+ *     import { registerPanelKeys } from './panel_keys.js';
+ *     const off = registerPanelKeys(hostEl, (ev) => { ... });
+ *     // later, on teardown:
+ *     off();
+ *
+ * The handler is responsible for its own key semantics (which keys, whether
+ * to skip editable targets, when to preventDefault). The router only decides
+ * WHETHER this panel is the active keyboard target. A handler that calls
+ * `ev.preventDefault()` stops the event from reaching any other handler in
+ * the same leaf.
+ *
+ * When no router has been installed (unit tests, or a landing used outside
+ * the WM), `registerPanelKeys` degrades to a self-contained listener using
+ * the legacy focus-containment scope, so callers work in isolation too.
+ */
+
+let _router = null;
+
+/** Install the singleton router. Called once by the WindowManager. */
+export function installPanelKeyRouter(wm) {
+    if (_router) _router.destroy();
+    _router = new PanelKeyRouter(wm);
+    return _router;
+}
+
+/** The installed router, or null if the WM hasn't built one yet. */
+export function getPanelKeyRouter() { return _router; }
+
+/** Tear down the singleton (test cleanup / shell teardown). */
+export function uninstallPanelKeyRouter() {
+    _router?.destroy();
+    _router = null;
+}
+
+/**
+ * Register `handler` as the key handler for `hostEl`'s panel. Returns an
+ * unregister function — call it on teardown. Routes through the installed
+ * router when present, otherwise falls back to a legacy scoped listener so
+ * the panel still works outside the WM.
+ */
+export function registerPanelKeys(hostEl, handler) {
+    if (!hostEl || typeof handler !== 'function') return () => {};
+    if (_router) return _router.register(hostEl, handler);
+    return _legacyRegister(hostEl, handler);
+}
+
+export class PanelKeyRouter {
+    constructor(wm) {
+        this._wm = wm;
+        this._entries = [];                 // { hostEl, handler }
+        this._onKey = this._dispatch.bind(this);
+        document.addEventListener('keydown', this._onKey);
+    }
+
+    register(hostEl, handler) {
+        const entry = { hostEl, handler };
+        this._entries.push(entry);
+        return () => {
+            const i = this._entries.indexOf(entry);
+            if (i >= 0) this._entries.splice(i, 1);
+        };
+    }
+
+    destroy() {
+        document.removeEventListener('keydown', this._onKey);
+        this._entries.length = 0;
+    }
+
+    /** Is `hostEl` the panel that should receive keys right now? */
+    _isActiveTarget(hostEl) {
+        if (!hostEl?.isConnected) return false;
+        const leaf = hostEl.closest?.('.twm-leaf');
+        if (leaf) {
+            // Inside the tile tree: only the focused leaf is live. This is
+            // the whole point — compare against the WM's single source of
+            // truth, not against `document.activeElement`.
+            return leaf === this._wm?.focusedLeafEl?.();
+        }
+        // Outside any tile (managed window / floating shell): no focused
+        // leaf to consult, so fall back to focus containment.
+        return hostEl.contains(document.activeElement)
+            || document.activeElement === document.body;
+    }
+
+    _dispatch(ev) {
+        // Snapshot: a handler may unregister (e.g. navigate away) mid-loop.
+        for (const entry of [...this._entries]) {
+            if (!this._isActiveTarget(entry.hostEl)) continue;
+            try { entry.handler(ev); }
+            catch (err) { console.warn('[panel-keys] handler threw', err); }
+            // A handler that consumed the key ends the chain so a second
+            // handler in the same leaf (e.g. the action-footer shortcuts)
+            // doesn't double-fire on the same press.
+            if (ev.defaultPrevented) return;
+        }
+    }
+}
+
+/** Legacy fallback used only when no router is installed. Mirrors the old
+ *  per-panel scope check so isolated/test usage keeps its previous
+ *  behavior. */
+function _legacyRegister(hostEl, handler) {
+    const wrapped = (ev) => {
+        if (!hostEl.isConnected) return;
+        if (!hostEl.contains(document.activeElement)
+            && document.activeElement !== document.body) return;
+        handler(ev);
+    };
+    document.addEventListener('keydown', wrapped);
+    return () => document.removeEventListener('keydown', wrapped);
+}