flexdesk 0.16.1 → 0.17.0

package/src/ui/components/staged_edits.js

@@ -0,0 +1,343 @@
+/**
+ * staged_edits.js — STORY-0088. DataTable's STAGED edits (`staged: true`).
+ * INTERNAL to the table, like `cell_grid.js`: built by the cell grid, and
+ * reading the table's private fields.
+ *
+ * With `staged`, an editor's commit does not go to `onCellCommit`: the value
+ * is STAGED here, drawn `twm-dt-cell--staged`, and recorded in the undo ring
+ * (`staged_history.js`) as a before/after delta. `commit()` hands every staged
+ * cell to the consumer's `onCommit({edits})` in one call; `discard()` drops
+ * them. While any cell is staged the table's sort, filters and pages are
+ * FROZEN — each such control is disabled with the reason on it
+ * (`data-refusal`), and the methods behind them refuse — because a new order
+ * or page would move the rows being edited out from under the person editing.
+ *
+ * A cell has three states: absent (no change), staged as null, staged as a
+ * value. Staging the value its row already holds makes it absent again.
+ */
+
+import { StagedHistory, DEFAULT_HISTORY_LIMIT } from './staged_history.js';
+
+const key = (rowIdx, colIdx) => `${rowIdx}:${colIdx}`;
+
+/** The controls a freeze holds, under the table's wrapper. The export button
+ *  moves no rows and is left alone. */
+const FROZEN_SELECTORS = [
+    'th.sortable',
+    '.data-table__filter-cell:not(.data-table__filter-cell--empty)',
+    '.data-table__filter-cell:not(.data-table__filter-cell--empty) input',
+    '.data-table__filter-cell:not(.data-table__filter-cell--empty) button',
+    '.data-table__filter-cell:not(.data-table__filter-cell--empty) select',
+    '.data-table__filter-cell:not(.data-table__filter-cell--empty) textarea',
+    '.twm-pagination-controls button:not(.twm-pagination-btn--export)',
+    '.twm-pagination-controls input',
+    '.twm-dt-paging button',
+    '.twm-dt-paging input',
+].join(', ');
+
+/** The attributes a freeze writes, put back as they were when it lifts. */
+const SAVED_ATTRS = ['title', 'data-refusal', 'data-tooltip', 'aria-disabled'];
+
+export class StagedEdits {
+    /** @param {import('./cell_grid.js').CellGrid} grid */
+    constructor(grid) {
+        this.grid = grid;
+        this.table = grid.table;
+        /** `rowIdx:colIdx` → {rowIdx, colIdx, value}: what is staged. */
+        this.cells = new Map();
+        /** `rowIdx:colIdx` → message: a cell the last commit refused. */
+        this.errors = new Map();
+        /** The commit out, or null. */
+        this.committing = null;
+        /** Bumped by new rows: a commit that outlived its rows marks nothing. */
+        this.generation = 0;
+        /** Rows touched while the ring applies an entry, drawn after it. */
+        this._touched = null;
+        /** Element → the attributes it had before the freeze. */
+        this._frozen = new Map();
+        const limit = this.table.config.historyLimit;
+        this.history = new StagedHistory({
+            apply: (entry, direction) => this._apply(entry, direction),
+            limit: limit == null ? DEFAULT_HISTORY_LIMIT : limit,
+        });
+    }
+
+    // ── what is staged ───────────────────────────────────────────────────
+
+    has(k) { return this.cells.has(k); }
+
+    value(k) { return this.cells.get(k)?.value; }
+
+    /** The value the row holds for a cell: what "no change" means. */
+    original(rowIdx, colIdx) {
+        const row = this.grid.currentRow(rowIdx);
+        return row ? row[colIdx] : undefined;
+    }
+
+    /** Every staged cell as `{rowIdx, colIdx, value, previous}`, by row then
+     *  column; `previous` is the value the row holds. */
+    edits() {
+        return [...this.cells.values()]
+            .sort((a, b) => a.rowIdx - b.rowIdx || a.colIdx - b.colIdx)
+            .map(({ rowIdx, colIdx, value }) => ({
+                rowIdx, colIdx, value, previous: this.original(rowIdx, colIdx),
+            }));
+    }
+
+    _side(k) {
+        return this.cells.has(k) ? { has: true, value: this.cells.get(k).value } : { has: false, value: null };
+    }
+
+    /** Write one side of a delta: stage the value, or take the cell out. */
+    _write(rowIdx, colIdx, side) {
+        const k = key(rowIdx, colIdx);
+        if (side.has) this.cells.set(k, { rowIdx, colIdx, value: side.value });
+        else this.cells.delete(k);
+        // A cell staged again (or taken back) is no longer what a commit refused.
+        this.errors.delete(k);
+    }
+
+    /**
+     * Stage a value in a cell, as one undo entry (inside an open group, part
+     * of it). The value its row holds takes the cell back to no change.
+     * Returns whether anything changed.
+     */
+    stage(rowIdx, colIdx, value) {
+        if (this.committing || !this._stageOne(rowIdx, colIdx, value)) return false;
+        this.grid._redraw(rowIdx, colIdx);
+        this._changed();
+        return true;
+    }
+
+    /**
+     * STORY-0089. Stage many cells (`[{rowIdx, colIdx, value}]`) as ONE undo
+     * entry — a fill, a paste — each as `stage` would; the rows are drawn and
+     * the listeners told once, at the end. Returns how many cells changed.
+     */
+    stageMany(cells, label = '') {
+        if (this.committing) return 0;
+        const rows = new Set();
+        let changed = 0;
+        this.history.beginGroup(label);
+        try {
+            for (const { rowIdx, colIdx, value } of cells) {
+                if (this._stageOne(rowIdx, colIdx, value)) { changed++; rows.add(rowIdx); }
+            }
+        } finally {
+            this.history.endGroup();
+        }
+        for (const rowIdx of rows) this.grid._redraw(rowIdx);
+        if (changed) this._changed();
+        return changed;
+    }
+
+    /** One cell's new state and its delta in the ring; whether it changed. */
+    _stageOne(rowIdx, colIdx, value) {
+        const k = key(rowIdx, colIdx);
+        const before = this._side(k);
+        const after = Object.is(value, this.original(rowIdx, colIdx))
+            ? { has: false, value: null } : { has: true, value };
+        if (before.has === after.has && Object.is(before.value, after.value)) return false;
+        this._write(rowIdx, colIdx, after);
+        this.history.record({ action: 'cell:stage', row: rowIdx, col: colIdx, before, after });
+        return true;
+    }
+
+    _apply(entry, direction) {
+        this._write(entry.row, entry.col, direction === 'undo' ? entry.before : entry.after);
+        this._touched?.add(entry.row);
+    }
+
+    _walk(step) {
+        if (this.committing) return false;
+        this._touched = new Set();
+        let moved = false;
+        try {
+            moved = step();
+        } finally {
+            const rows = this._touched;
+            this._touched = null;
+            for (const rowIdx of rows) this.grid._redraw(rowIdx);
+        }
+        if (moved) this._changed();
+        return moved;
+    }
+
+    undo() { return this._walk(() => this.history.undo()); }
+
+    redo() { return this._walk(() => this.history.redo()); }
+
+    /** Drop every staged cell, its marks and the ring. */
+    discard() {
+        if (this.committing) return false;
+        const rows = this._rows();
+        const had = this.cells.size > 0 || this.errors.size > 0;
+        this.cells.clear();
+        this.errors.clear();
+        this.history.reset();
+        for (const rowIdx of rows) this.grid._redraw(rowIdx);
+        if (had) this._changed();
+        return had;
+    }
+
+    /** New rows (`setData({rows})`): the cells named rows that are gone. */
+    clear() {
+        this.generation++;
+        this.committing = null;
+        const had = this.cells.size > 0 || this.errors.size > 0;
+        this.cells.clear();
+        this.errors.clear();
+        this.history.reset();
+        if (had) this._changed();
+    }
+
+    _rows() {
+        const rows = new Set();
+        for (const c of this.cells.values()) rows.add(c.rowIdx);
+        for (const k of this.errors.keys()) rows.add(Number(k.split(':')[0]));
+        return rows;
+    }
+
+    // ── the commit ───────────────────────────────────────────────────────
+
+    /**
+     * Hand every staged cell to `onCommit({edits})`, once. Resolves
+     * `{ok: true, committed}` when it succeeded — the values are written into
+     * the rows the table holds, and the staged cells and the ring are gone —
+     * or `{ok: false, errors}` when it refused: per-cell errors mark their
+     * cells, a refusal with none marks every staged cell, and every staged
+     * value stays.
+     */
+    commit() {
+        if (this.committing) return this.committing;
+        // An open editor's value is staged first: it is part of the batch.
+        if (this.grid.isEditing()) this.grid.editor.commit(null, 'commit');
+        const fn = this.table.config.onCommit;
+        const edits = this.edits();
+        if (!edits.length) return Promise.resolve({ ok: true, committed: 0 });
+        if (typeof fn !== 'function') {
+            console.warn('[DataTable] commit() needs an `onCommit`; nothing was committed.');
+            return Promise.resolve({ ok: false, errors: [] });
+        }
+        const generation = this.generation;
+        const refused = (err) => ({ ok: false, error: err?.message || String(err ?? 'Not saved') });
+        let result;
+        try {
+            result = fn({ edits: edits.map((e) => ({ ...e })) });
+        } catch (err) {
+            result = refused(err);
+        }
+        const out = Promise.resolve(result)
+            .then((r) => r, refused)
+            .then((r) => {
+                if (generation !== this.generation) return { ok: false, errors: [] };
+                this.committing = null;
+                return this._settle(edits, r);
+            });
+        this.committing = out;
+        this._changed();
+        return out;
+    }
+
+    _settle(edits, result) {
+        const listed = Array.isArray(result?.errors) ? result.errors : [];
+        if (listed.length || result?.ok === false) {
+            const errors = [];
+            const mark = (rowIdx, colIdx, message) => {
+                const k = key(rowIdx, colIdx);
+                if (!this.cells.has(k)) return;
+                const text = String(message ?? 'Not saved');
+                this.errors.set(k, text);
+                errors.push({ rowIdx, colIdx, error: text });
+            };
+            if (listed.length) {
+                for (const e of listed) mark(e?.rowIdx, e?.colIdx, e?.error ?? e?.message);
+            } else {
+                for (const e of edits) mark(e.rowIdx, e.colIdx, result.error);
+            }
+            for (const rowIdx of this._rows()) this.grid._redraw(rowIdx);
+            this._changed();
+            return { ok: false, errors };
+        }
+        const rows = this._rows();
+        for (const e of edits) {
+            const row = this.grid.currentRow(e.rowIdx);
+            if (Array.isArray(row)) row[e.colIdx] = e.value;
+        }
+        this.cells.clear();
+        this.errors.clear();
+        this.history.reset();
+        for (const rowIdx of rows) this.grid._redraw(rowIdx);
+        this._changed();
+        return { ok: true, committed: edits.length };
+    }
+
+    // ── the freeze ───────────────────────────────────────────────────────
+
+    /** Why sort, filters and pages are held, or null when nothing is staged. */
+    freezeReason() {
+        const n = this.cells.size;
+        if (!n) return null;
+        const own = this.table.config.stagedRefusal;
+        if (typeof own === 'function') {
+            try { return String(own(n)); } catch (err) {
+                console.error('[DataTable] stagedRefusal threw', err);
+            }
+        } else if (typeof own === 'string' && own) return own;
+        return `Sorting, filtering and paging are held while ${n} change${n === 1 ? ' is' : 's are'} `
+            + 'not committed. Commit or discard them first.';
+    }
+
+    /** Disable every control the freeze holds with the reason on it, or put
+     *  back the ones it held. Run after every render and every change. */
+    paintFreeze() {
+        const root = this.table._wrapperEl;
+        const reason = this.freezeReason();
+        root?.classList.toggle('twm-dt--frozen', !!reason);
+        if (!reason) {
+            for (const [el, saved] of this._frozen) this._thaw(el, saved);
+            this._frozen.clear();
+            return;
+        }
+        for (const el of this._frozen.keys()) if (!el.isConnected) this._frozen.delete(el);
+        if (!root) return;
+        for (const el of root.querySelectorAll(FROZEN_SELECTORS)) {
+            if (!this._frozen.has(el)) {
+                const saved = {};
+                for (const a of SAVED_ATTRS) saved[a] = el.getAttribute(a);
+                saved.disabled = 'disabled' in el ? el.disabled : null;
+                this._frozen.set(el, saved);
+            }
+            el.setAttribute('data-refusal', reason);
+            el.setAttribute('title', reason);
+            if (el.hasAttribute('data-tooltip')) el.setAttribute('data-tooltip', reason);
+            el.setAttribute('aria-disabled', 'true');
+            if ('disabled' in el) el.disabled = true;
+        }
+    }
+
+    _thaw(el, saved) {
+        for (const a of SAVED_ATTRS) {
+            if (saved[a] == null) el.removeAttribute(a);
+            else el.setAttribute(a, saved[a]);
+        }
+        if (saved.disabled !== null) el.disabled = saved.disabled;
+    }
+
+    /** After every change: the freeze, and whoever listens. */
+    _changed() {
+        this.paintFreeze();
+        const fn = this.table.config.onStagedChange;
+        if (typeof fn !== 'function') return;
+        try {
+            fn({
+                count: this.cells.size,
+                canUndo: this.history.canUndo,
+                canRedo: this.history.canRedo,
+                committing: !!this.committing,
+            });
+        } catch (err) {
+            console.error('[DataTable] onStagedChange threw', err);
+        }
+    }
+}

package/src/ui/components/staged_history.js

@@ -0,0 +1,172 @@
+/**
+ * staged_history.js — STORY-0088. Ctrl+Z and Ctrl+Y over a grid's STAGED
+ * edits, and over nothing else. No DOM: the ring decides WHAT to reverse, and
+ * the grid that owns the staged cells decides HOW (`apply`).
+ *
+ * ══ STAGED, NEVER COMMITTED ══════════════════════════════════════════════
+ *
+ * Ctrl+Z takes back what was typed and not yet committed. It never reaches a
+ * commit: once a batch has gone to the consumer, `reset()` empties the ring,
+ * so an undo or a redo after a commit does nothing. `ACTIONS` lists the only
+ * thing the ring knows how to reverse, and `record()` refuses anything else —
+ * an undoable action that writes somewhere cannot be added by accident.
+ *
+ * ══ A DELTA, NOT A SNAPSHOT ══════════════════════════════════════════════
+ *
+ * An entry is the change itself: one cell's `before` and `after`. A paste of
+ * 20,000 cells is one group of 20,000 deltas, held once — not 20,000 entries'
+ * worth of copies of the staged set. `limit` counts ENTRIES (a group is one).
+ *
+ * Each side is `{has, value}`, not just a value, because a staged cell has
+ * three states: absent (no change), staged as null, staged as something. A
+ * side that held only the value could not tell the first two apart, and undoing
+ * a cell staged as null would leave a staged null behind instead of no change.
+ */
+
+/** The only action that exists: one cell's staged state changed.
+ *  `{action: 'cell:stage', row, col, before: {has, value}, after: {has, value}}`. */
+export const ACTIONS = Object.freeze(['cell:stage']);
+
+/** Entries kept when no `limit` is given. */
+export const DEFAULT_HISTORY_LIMIT = 100;
+
+export class StagedHistory {
+    /**
+     * @param {object} cfg
+     * @param {(entry, direction: 'undo'|'redo') => void} cfg.apply  writes one
+     *   leaf entry's `before` (undo) or `after` (redo) into the staged cells.
+     *   Called once per leaf; the ring holds no reference to those cells.
+     * @param {({canUndo, canRedo, depth}) => void} [cfg.onState]  after every
+     *   change of the stacks.
+     * @param {number} [cfg.limit=100]  entries kept; the oldest fall off.
+     */
+    constructor({ apply, onState = null, limit = DEFAULT_HISTORY_LIMIT } = {}) {
+        if (typeof apply !== 'function') {
+            throw new Error('StagedHistory needs an `apply(entry, direction)`: a ring with no '
+                + 'writer would report every undo as done and change nothing.');
+        }
+        this.apply = apply;
+        this.onState = onState;
+        this.limit = Number.isFinite(limit) && limit >= 1 ? Math.floor(limit) : DEFAULT_HISTORY_LIMIT;
+        this.undoStack = [];
+        this.redoStack = [];
+        this.group = null;
+        /** Groups nest; only the outermost `endGroup` closes one. */
+        this.depthOpen = 0;
+        /** Set while `apply` runs: a record from inside it is ignored, so an
+         *  undo that writes through the grid's own staging cannot record its
+         *  own inverse. */
+        this.applying = false;
+    }
+
+    get canUndo() { return this.undoStack.length > 0; }
+    get canRedo() { return this.redoStack.length > 0; }
+    get depth() { return this.undoStack.length; }
+
+    /** Open a group: everything recorded until the matching `endGroup` is one
+     *  undo (a fill, a paste). */
+    beginGroup(label = '') {
+        this.depthOpen += 1;
+        if (this.depthOpen === 1) this.group = { action: 'batch', label, entries: [] };
+    }
+
+    /** Close a group. An empty one is dropped, so it costs no undo step; one
+     *  holding a single entry is that entry. */
+    endGroup() {
+        if (!this.depthOpen) return;
+        this.depthOpen -= 1;
+        if (this.depthOpen) return;
+        const group = this.group;
+        this.group = null;
+        if (!group) return;
+        if (group.entries.length === 1) this._push(group.entries[0]);
+        else if (group.entries.length) this._push(group);
+    }
+
+    /** Record one delta. Returns whether it was recorded (false while an
+     *  entry is being applied). Throws on an action that is not in `ACTIONS`. */
+    record(entry) {
+        if (this.applying) return false;
+        if (!entry || !ACTIONS.includes(entry.action)) {
+            throw new Error(`${entry?.action} is not an undoable action: the ring reverses `
+                + 'staged cells only, never a commit.');
+        }
+        if (this.group) { this.group.entries.push(entry); return true; }
+        this._push(entry);
+        return true;
+    }
+
+    undo() {
+        this._closeOpenGroup();
+        const entry = this.undoStack.pop();
+        if (!entry) return false;
+        this._run(entry, 'undo');
+        this.redoStack.push(entry);
+        this._publish();
+        return true;
+    }
+
+    redo() {
+        this._closeOpenGroup();
+        const entry = this.redoStack.pop();
+        if (!entry) return false;
+        this._run(entry, 'redo');
+        this.undoStack.push(entry);
+        this._publish();
+        return true;
+    }
+
+    /** Forget everything — after a commit or a discard, whose cells the
+     *  entries no longer describe. An open group is closed with it. */
+    reset() {
+        this.undoStack = [];
+        this.redoStack = [];
+        this.group = null;
+        this.depthOpen = 0;
+        this._publish();
+    }
+
+    /** A group left open (a caller that threw) is closed before an undo, so it
+     *  cannot swallow every later entry. */
+    _closeOpenGroup() {
+        if (!this.depthOpen) return;
+        this.depthOpen = 1;
+        this.endGroup();
+    }
+
+    _push(entry) {
+        this.undoStack.push(entry);
+        // A new edit after an undo ends the redo branch.
+        this.redoStack = [];
+        if (this.undoStack.length > this.limit) this.undoStack.splice(0, this.undoStack.length - this.limit);
+        this._publish();
+    }
+
+    _publish() {
+        try {
+            this.onState?.({ canUndo: this.canUndo, canRedo: this.canRedo, depth: this.undoStack.length });
+        } catch (err) {
+            console.error('[StagedHistory] onState threw', err);
+        }
+    }
+
+    _run(entry, direction) {
+        this.applying = true;
+        try {
+            this._applyOne(entry, direction);
+        } finally {
+            this.applying = false;
+        }
+    }
+
+    /** A group replays in REVERSE on the way back (two writes to one cell must
+     *  unwind last first) and in order on the way forward. */
+    _applyOne(entry, direction) {
+        if (entry.action === 'batch') {
+            const entries = direction === 'undo' ? [...entry.entries].reverse() : entry.entries;
+            for (const child of entries) this._applyOne(child, direction);
+            return;
+        }
+        this.apply(entry, direction);
+    }
+}