flexdesk 0.16.0 → 0.17.0

package/src/ui/components/fill_handle.js

@@ -0,0 +1,322 @@
+/**
+ * fill_handle.js — STORY-0089. DataTable's FILL HANDLE (`fillHandle: true`).
+ * INTERNAL to the table, like `cell_grid.js`: built by the cell grid, and
+ * reading the table through it.
+ *
+ * A small square on the bottom-right corner of the cell range. Dragging it
+ * up, down, left or right over the cells beyond the range previews the cells
+ * it covers (`twm-dt-cell--fill-preview`) and, on release, STAGES their new
+ * values (`staged_edits.js`) as ONE undo entry. What the values are is
+ * `series.js`'s: each line of the range — a column for a fill up or down, a
+ * row for a fill left or right — is a seed, continued as a series or repeated
+ * in a cycle; Ctrl (Cmd) held at release repeats it.
+ *
+ * A target cell that `editable` refuses is SKIPPED: nothing is staged in it,
+ * and it is drawn `twm-dt-cell--fill-skipped` until the selection moves, the
+ * next fill, or new rows.
+ */
+
+import { projectSeries } from './series.js';
+
+const key = (rowIdx, colIdx) => `${rowIdx}:${colIdx}`;
+
+export class FillHandle {
+    /** @param {import('./cell_grid.js').CellGrid} grid */
+    constructor(grid) {
+        this.grid = grid;
+        /** The handle element; made on first use, moved into the corner cell. */
+        this.el = null;
+        /** The `<td>` holding the handle, or null. */
+        this.corner = null;
+        /** `rowIdx:colIdx` of the cells the last fill skipped. */
+        this.skipped = new Set();
+        /** `pos:colIdx` of the cells a drag covers now. */
+        this.preview = new Set();
+        /** The drag in progress: `{range, plan, unbind}`, or null. */
+        this.drag = null;
+        /** Takes the click guard of the last press on the handle off, or null. */
+        this._unguard = null;
+    }
+
+    // ── painting (called by the grid for every cell it paints) ───────────
+
+    /** One cell: its preview and skipped marks, and the handle when it is
+     *  the range's corner. */
+    paintCell(td, pos, col) {
+        const rowIdx = td.parentNode?.__rowIndex;
+        td.classList.toggle('twm-dt-cell--fill-preview', this.preview.has(`${pos}:${col}`));
+        td.classList.toggle('twm-dt-cell--fill-skipped', this.skipped.has(key(rowIdx, col)));
+        const r = this.grid.sel.range();
+        if (r && r.bottom === pos && r.right === col) this._place(td);
+        else if (td === this.corner) this._unplace();
+    }
+
+    _handle() {
+        if (this.el) return this.el;
+        const el = document.createElement('div');
+        el.className = 'twm-dt-fill-handle';
+        el.setAttribute('aria-hidden', 'true');
+        el.title = 'Drag to fill; hold Ctrl to repeat instead of continuing a series';
+        el.addEventListener('pointerdown', (ev) => this._begin(ev));
+        this.el = el;
+        return el;
+    }
+
+    _place(td) {
+        if (this.grid.isEditing() || this.grid.staged.committing) { this._unplace(); return; }
+        if (this.corner && this.corner !== td) this.corner.classList.remove('twm-dt-cell--fill-corner');
+        this.corner = td;
+        td.classList.add('twm-dt-cell--fill-corner');
+        const el = this._handle();
+        if (el.parentNode !== td) td.appendChild(el);
+    }
+
+    _unplace() {
+        this.corner?.classList.remove('twm-dt-cell--fill-corner');
+        this.corner = null;
+        this.el?.remove();
+    }
+
+    // ── what a fill covers ───────────────────────────────────────────────
+
+    /**
+     * The fill that reaching cell `to` (`{row, col}`, position and data
+     * column) from `range` makes: `{direction, count}`, or null when `to` is
+     * inside the range's rows and columns. The direction is the one the cell
+     * lies furthest out in; up and down win a tie. Clamped to the page drawn.
+     */
+    plan(range, to) {
+        if (!range || !to) return null;
+        const cols = this.grid.columns();
+        const [first, last] = this.grid.span();
+        const row = Math.max(first, Math.min(last, Number(to.row)));
+        const ordL = cols.indexOf(range.left);
+        const ordR = cols.indexOf(range.right);
+        const ordTo = cols.indexOf(to.col);
+        const out = [
+            ['down', row - range.bottom],
+            ['up', range.top - row],
+            ['right', ordTo < 0 ? 0 : ordTo - ordR],
+            ['left', ordTo < 0 ? 0 : ordL - ordTo],
+        ];
+        let best = null;
+        for (const [direction, count] of out) {
+            if (count > 0 && (!best || count > best.count)) best = { direction, count };
+        }
+        return best;
+    }
+
+    /** The cells a plan covers, as `{pos, col}`, line by line in fill order:
+     *  `[{seed: [{pos, col}], targets: [{pos, col}]}]`. */
+    _lines(range, { direction, count }) {
+        const cols = this.grid.columns();
+        const ordL = cols.indexOf(range.left);
+        const ordR = cols.indexOf(range.right);
+        const lines = [];
+        if (direction === 'down' || direction === 'up') {
+            const down = direction === 'down';
+            for (let o = ordL; o <= ordR; o++) {
+                const col = cols[o];
+                const seed = [];
+                for (let p = range.top; p <= range.bottom; p++) seed.push({ pos: p, col });
+                if (!down) seed.reverse();
+                const targets = [];
+                for (let i = 1; i <= count; i++) {
+                    targets.push({ pos: down ? range.bottom + i : range.top - i, col });
+                }
+                lines.push({ seed, targets });
+            }
+        } else {
+            const right = direction === 'right';
+            for (let p = range.top; p <= range.bottom; p++) {
+                const seed = [];
+                for (let o = ordL; o <= ordR; o++) seed.push({ pos: p, col: cols[o] });
+                if (!right) seed.reverse();
+                const targets = [];
+                for (let i = 1; i <= count; i++) {
+                    const o = right ? ordR + i : ordL - i;
+                    if (o >= 0 && o < cols.length) targets.push({ pos: p, col: cols[o] });
+                }
+                lines.push({ seed, targets });
+            }
+        }
+        return lines;
+    }
+
+    // ── the fill ─────────────────────────────────────────────────────────
+
+    /**
+     * Fill from the range to cell `to`, staging the values as ONE undo
+     * entry. Returns `{direction, count, staged, skipped}` (`skipped` the
+     * cells `editable` refused, `{row, col, rowIdx}`), or null when nothing
+     * was filled: no range, `to` inside it, an editor open or a commit out.
+     */
+    fill(to, { forceCopy = false } = {}) {
+        const g = this.grid;
+        g._sync();
+        const range = g.sel.range();
+        const plan = this.plan(range, to);
+        if (!plan || g.staged.committing || g.isEditing()) return null;
+        const cells = [];
+        const skipped = [];
+        for (const { seed, targets } of this._lines(range, plan)) {
+            const values = projectSeries(
+                seed.map(({ pos, col }) => g.shownValue(g.rowIndexAt(pos), col)),
+                targets.length, { forceCopy });
+            targets.forEach(({ pos, col }, i) => {
+                const rowIdx = g.rowIndexAt(pos);
+                if (g.canEdit(pos, col)) cells.push({ rowIdx, colIdx: col, value: values[i] });
+                else skipped.push({ row: pos, col, rowIdx });
+            });
+        }
+        const staged = g.staged.stageMany(cells, `fill ${cells.length} cell(s)`);
+        // The range grows over what was filled, the cursor at its far end.
+        const cols = g.columns();
+        const ordL = cols.indexOf(range.left);
+        const ordR = cols.indexOf(range.right);
+        const { direction, count } = plan;
+        if (direction === 'down') g.set({ row: range.bottom + count, col: range.right }, { row: range.top, col: range.left });
+        else if (direction === 'up') g.set({ row: range.top - count, col: range.left }, { row: range.bottom, col: range.right });
+        else if (direction === 'right') g.set({ row: range.bottom, col: cols[Math.min(cols.length - 1, ordR + count)] }, { row: range.top, col: range.left });
+        else g.set({ row: range.top, col: cols[Math.max(0, ordL - count)] }, { row: range.bottom, col: range.right });
+        // Marked after the selection moved, which clears the last fill's marks.
+        for (const s of skipped) this.skipped.add(key(s.rowIdx, s.col));
+        if (skipped.length) g.paint();
+        return { direction, count, staged, skipped };
+    }
+
+    /** The selection moved, or new rows came: the skipped marks are over. */
+    clearMarks() {
+        this.skipped.clear();
+    }
+
+    // ── the drag ─────────────────────────────────────────────────────────
+
+    _begin(ev) {
+        if (ev.button != null && ev.button !== 0) return;
+        ev.preventDefault();
+        ev.stopPropagation();
+        const g = this.grid;
+        g._sync();
+        const range = g.sel.range();
+        if (!range || this.drag || g.isEditing() || g.staged.committing) return;
+        const doc = this.el.ownerDocument;
+        this._guardClick(doc);
+        const onMove = (move) => this._move(move);
+        const onUp = (up) => {
+            const plan = this.drag?.plan;
+            this._end();
+            if (plan) this.fill(this._reach(range, plan), { forceCopy: !!(up.ctrlKey || up.metaKey) });
+            try { g.table._tableEl?.focus({ preventScroll: true }); } catch (_) { /* detached */ }
+        };
+        const onCancel = () => this._end();
+        const onKey = (k) => { if (k.key === 'Escape') { k.preventDefault(); k.stopPropagation(); this._end(); } };
+        doc.addEventListener('pointermove', onMove);
+        doc.addEventListener('pointerup', onUp);
+        doc.addEventListener('pointercancel', onCancel);
+        doc.addEventListener('keydown', onKey, true);
+        this.drag = {
+            range,
+            plan: null,
+            unbind: () => {
+                doc.removeEventListener('pointermove', onMove);
+                doc.removeEventListener('pointerup', onUp);
+                doc.removeEventListener('pointercancel', onCancel);
+                doc.removeEventListener('keydown', onKey, true);
+            },
+        };
+    }
+
+    /**
+     * A press on the handle and its release make, in a browser, a click (and
+     * on a second press a dblclick) of their own, on the element under both:
+     * the corner cell, the row, the body. Filled, cancelled by Escape or
+     * released where it began, a drag is no click on the table: from the
+     * press, the next click in the document is swallowed in the capture
+     * phase, and so is every dblclick until the task the release is handled
+     * in is over. A cancelled pointer makes no click; the guard ends with it.
+     */
+    _guardClick(doc) {
+        this._unguard?.();
+        const view = doc.defaultView;
+        let timer = null;
+        const swallow = (c) => { c.stopPropagation(); c.preventDefault(); };
+        const swallowOnce = (c) => { swallow(c); doc.removeEventListener('click', swallowOnce, true); };
+        const released = () => {
+            doc.removeEventListener('pointerup', released, true);
+            doc.removeEventListener('pointercancel', unguard, true);
+            timer = view.setTimeout(unguard, 0);
+        };
+        const unguard = () => {
+            if (timer !== null) view.clearTimeout(timer);
+            doc.removeEventListener('click', swallowOnce, true);
+            doc.removeEventListener('dblclick', swallow, true);
+            doc.removeEventListener('pointerup', released, true);
+            doc.removeEventListener('pointercancel', unguard, true);
+            if (this._unguard === unguard) this._unguard = null;
+        };
+        doc.addEventListener('click', swallowOnce, true);
+        doc.addEventListener('dblclick', swallow, true);
+        doc.addEventListener('pointerup', released, true);
+        doc.addEventListener('pointercancel', unguard, true);
+        this._unguard = unguard;
+    }
+
+    /** The cell a plan reaches, as `fill` takes it. */
+    _reach(range, { direction, count }) {
+        const cols = this.grid.columns();
+        if (direction === 'down') return { row: range.bottom + count, col: range.right };
+        if (direction === 'up') return { row: range.top - count, col: range.left };
+        if (direction === 'right') return { row: range.bottom, col: cols[cols.indexOf(range.right) + count] };
+        return { row: range.top, col: cols[cols.indexOf(range.left) - count] };
+    }
+
+    /** The data cell under the pointer: the event's target, or (a touch,
+     *  whose events stay on the handle) the element at its point. */
+    _cellUnder(ev) {
+        const tbody = this.grid.table._tbodyEl;
+        const hit = (el) => {
+            const td = el?.closest?.('td');
+            if (!td || td.__colIdx === undefined || !tbody?.contains(td)) return null;
+            const pos = td.parentNode?.__cellPos;
+            return pos === undefined ? null : { row: pos, col: td.__colIdx };
+        };
+        let cell = ev.target === this.el ? null : hit(ev.target);
+        const doc = this.el.ownerDocument;
+        if (!cell && typeof doc.elementFromPoint === 'function') {
+            cell = hit(doc.elementFromPoint(ev.clientX, ev.clientY));
+        }
+        return cell;
+    }
+
+    _move(ev) {
+        const d = this.drag;
+        if (!d) return;
+        const cell = this._cellUnder(ev);
+        if (!cell) return;
+        d.plan = this.plan(d.range, cell);
+        this.preview.clear();
+        if (d.plan) {
+            for (const { targets } of this._lines(d.range, d.plan)) {
+                for (const t of targets) this.preview.add(`${t.pos}:${t.col}`);
+            }
+        }
+        this.grid.paint();
+    }
+
+    _end() {
+        const d = this.drag;
+        if (!d) return;
+        this.drag = null;
+        d.unbind();
+        this.preview.clear();
+        this.grid.paint();
+    }
+
+    dispose() {
+        this._end();
+        this._unguard?.();
+        this._unplace();
+        this.skipped.clear();
+    }
+}

package/src/ui/components/gallery_picker.js

@@ -6,7 +6,8 @@
  * called a "template"). The picker is mounted into a host element
  * and fires `onChange(entry)` whenever the selection changes.
  *
- * Each entry is the raw gallery dict from `pywebview.api.gallery_list`:
+ * The entries come from `opts.entries`, or else from the host's optional
+ * `gallery` capability (`host.gallery.list(kind)`, see host.js). Each entry is
  *
  *     { id, kind, label, description, fields }
  *
@@ -17,6 +18,7 @@
  * Usage:
  *
  *     const picker = await mountGalleryPicker(hostEl, {
+ *         host,                 // or entries: [...]
  *         kind: 'agent',
  *         selectedId: 'blank',
  *         onChange: (entry) => { … },
@@ -45,8 +47,11 @@ function esc(s) {
  *                                            first entry wins.
  * @param {function}    [opts.onChange]    — `(entry) => void` fired on selection
  *                                            change AND on initial mount.
- * @param {object[]}    [opts.entries]     — explicit entries (skips bridge fetch).
- *                                            Useful for tests + offline previews.
+ * @param {object[]}    [opts.entries]     — explicit entries (the host is not asked).
+ * @param {object}      [opts.host]        — a Host; its `gallery.list(kind)` supplies
+ *                                            the entries when `entries` is absent.
+ *                                            With neither, the picker shows
+ *                                            `emptyLabel` and warns once.
  * @param {string}      [opts.emptyLabel]  — copy shown when the catalog is empty
  *                                            for that kind.
  * @returns {Promise<{getSelected, setSelectedById, dispose}>}
@@ -57,18 +62,24 @@ export async function mountGalleryPicker(hostEl, opts = {}) {
         selectedId   = null,
         onChange     = () => {},
         entries      = null,
+        host         = null,
         emptyLabel   = 'No starters available for this kind.',
     } = opts;
     if (!hostEl) throw new Error('mountGalleryPicker: hostEl is required');
 
     let catalog = entries;
     if (!catalog) {
-        const api = window.pywebview?.api;
-        try {
-            catalog = (await api?.gallery_list?.(kind)) || [];
-        } catch (err) {
-            console.warn('[gallery-picker] gallery_list failed', err);
+        const list = host?.gallery?.list;
+        if (typeof list !== 'function') {
+            console.warn('[gallery-picker] no entries and no host gallery capability; showing the empty label');
             catalog = [];
+        } else {
+            try {
+                catalog = (await list(kind)) || [];
+            } catch (err) {
+                console.warn('[gallery-picker] host.gallery.list failed', err);
+                catalog = [];
+            }
         }
     }
     catalog = Array.isArray(catalog) ? catalog : [];

package/src/ui/components/header_actions.js

@@ -0,0 +1,55 @@
+/**
+ * header_actions.js — STORY-0066. The pieces DataTable's column groups
+ * (column_groups.js) and structural edits (table_structure.js) share: the
+ * consumer callback called behind a guard, and the action button drawn in a
+ * header cell. INTERNAL to the table, and not part of the widgets barrel.
+ */
+
+/** Call the table option `name` (a function on `config`) with `args`. An
+ *  option that is not a function answers undefined; one that throws is
+ *  logged and answers undefined too, so a consumer's bug never breaks a
+ *  render or a click. */
+export function callOption(config, name, ...args) {
+    const fn = config?.[name];
+    if (typeof fn !== 'function') return undefined;
+    try {
+        return fn.apply(config, args);
+    } catch (err) {
+        console.error(`[DataTable] ${name} threw`, err);
+        return undefined;
+    }
+}
+
+/**
+ * A button in a header cell for the item `{icon?, label?, title?, disabled?}`:
+ * the material-symbols icon, or the label when there is no icon; the title
+ * and aria-label from `title ?? label`; disabled when `disabled`. Its press
+ * is its own: neither the mousedown nor the click reaches the header (no
+ * sort, no drag under it).
+ */
+export function headerActionButton(className, { icon, label, title, disabled } = {}, onClick) {
+    const b = document.createElement('button');
+    b.type = 'button';
+    b.className = className;
+    if (icon) {
+        const span = document.createElement('span');
+        span.className = 'material-symbols-outlined';
+        span.textContent = String(icon);
+        b.appendChild(span);
+    } else if (label != null) {
+        b.appendChild(document.createTextNode(String(label)));
+    }
+    const name = title ?? label;
+    if (name != null) {
+        b.title = String(name);
+        b.setAttribute('aria-label', String(name));
+    }
+    if (disabled) b.disabled = true;
+    b.addEventListener('mousedown', (ev) => ev.stopPropagation());
+    b.addEventListener('click', (ev) => {
+        ev.preventDefault();
+        ev.stopPropagation();
+        onClick(ev);
+    });
+    return b;
+}

package/src/ui/components/job_progress.js

@@ -0,0 +1,51 @@
+/**
+ * The progress block both job dialogs share — `showRunProgressDialog` and
+ * `showComputingWindow` — so a bar and a row of phases behave the same in
+ * either. Internal: not in the `widgets` barrel.
+ */
+
+import { ProgressBar, StepProgress } from './progress.js';
+
+/**
+ * Mount the optional phases and bar into `parent`, phases first.
+ *
+ * @param {HTMLElement} parent
+ * @param {{ progress?: boolean|Object, steps?: Array, spinner?: HTMLElement|null }} options
+ *   `progress`: `true`, or ProgressBar options (its `onCancel` is ignored: the
+ *   dialog owns cancelling). `steps`: StepProgress steps. `spinner`: hidden
+ *   while a bar is shown. Both are fixed at mount: `setProgress` throws
+ *   without `progress` and `setStep` without `steps`, so the window is sized
+ *   for what it holds from the start.
+ */
+export function mountJobProgress(parent, { progress = null, steps = null, spinner = null } = {}) {
+    const stepper = Array.isArray(steps) && steps.length
+        ? new StepProgress(parent, { steps, className: 'twm-job-progress__steps' })
+        : null;
+    let bar = null;
+    if (progress) {
+        const { onCancel: _ignored, ...rest } = typeof progress === 'object' ? progress : {};
+        bar = new ProgressBar(parent, { ...rest, className: 'twm-job-progress__bar' });
+        if (spinner) spinner.hidden = true;
+    }
+
+    return {
+        get bar() { return bar; },
+        get steps() { return stepper; },
+        /** `bar.update(next)`. */
+        setProgress(next) {
+            if (!bar) throw new Error('setProgress: this dialog was opened without `progress`');
+            bar.update(next);
+        },
+        /** `steps.setStep(which, opts)`. */
+        setStep(which, opts) {
+            if (!stepper) throw new Error('setStep: this dialog was opened without `steps`');
+            stepper.setStep(which, opts);
+        },
+        /** Put the bar and the phases in their final state. */
+        finish(status) {
+            if (status === 'done') { bar?.setState('done'); stepper?.complete(); }
+            else if (status === 'error') { bar?.setState('error'); stepper?.fail(); }
+            else bar?.setState('cancelled');
+        },
+    };
+}

package/src/ui/components/managed_window.js

@@ -19,7 +19,11 @@
 
 import { getSetting } from '../../core/settings.js';
 
-const STORAGE_KEY = 'ecosim.managedWindows.v1';
+/** Where window geometry lives when the embedder names no key. An embedder
+ *  that saved geometry under another key keeps it by passing that key to
+ *  `ManagedWindow.configure({ storageKey })` before the first window opens. */
+export const DEFAULT_WINDOW_STORAGE_KEY = 'flexdesk.managedWindows.v1';
+let _storageKey = DEFAULT_WINDOW_STORAGE_KEY;
 const BASE_Z_INDEX = 6000;
 const MAX_Z_INDEX = 6999;
 
@@ -70,7 +74,7 @@ let _stateCache = null;
 function _loadState() {
     if (_stateCache) return _stateCache;
     try {
-        const raw = localStorage.getItem(STORAGE_KEY);
+        const raw = localStorage.getItem(_storageKey);
         _stateCache = raw ? JSON.parse(raw) : {};
     } catch {
         _stateCache = {};
@@ -81,7 +85,7 @@ function _loadState() {
 function _saveState(state) {
     _stateCache = state;
     try {
-        localStorage.setItem(STORAGE_KEY, JSON.stringify(state));
+        localStorage.setItem(_storageKey, JSON.stringify(state));
     } catch (err) {
         console.warn('[ManagedWindow] Failed to save state:', err);
     }
@@ -958,7 +962,7 @@ export class ManagedWindow {
      *      x         = max(minX, min(x, maxX))        = max(0, min(x, maxX))                    ✓
      *      y         = max(minY, min(y, maxY))        = max(TOP, min(y, maxY))                  ✓
      *
-     *  EcoAgent's and EcoSim's modals depend on that arithmetic; prove the
+     *  Embedders' modals depend on that arithmetic; prove the
      *  equivalence in review by substitution rather than by testing.
      */
     _bounds() {
@@ -1661,6 +1665,25 @@ export class ManagedWindow {
 
     // ========== Static Methods ==========
 
+    /**
+     * Choose where window geometry is saved and restored. Call once at boot,
+     * before the first window opens; from then on windows read and write only
+     * `storageKey`. The geometry already read from another key is dropped, so
+     * a window shown afterwards restores what `storageKey` holds.
+     *
+     * @param {object} [opts]
+     * @param {string} [opts.storageKey=DEFAULT_WINDOW_STORAGE_KEY]
+     */
+    static configure({ storageKey = DEFAULT_WINDOW_STORAGE_KEY } = {}) {
+        _storageKey = storageKey;
+        _stateCache = null;
+    }
+
+    /** @returns {string} The localStorage key window geometry uses. */
+    static get storageKey() {
+        return _storageKey;
+    }
+
     /**
      * Get a window by ID.
      */