flexdesk 0.16.0 → 0.17.0

package/src/ui/components/cell_selection.js

@@ -0,0 +1,220 @@
+/**
+ * cell_selection.js — STORY-0003. The model under DataTable's CELL MODE
+ * (`selectionMode: 'cells'`): a cursor cell, a range from an anchor to that
+ * cursor, and every move the keys make over them. No DOM, so the rules can be
+ * tested — or drive another grid — without a table. DataTable's own half (the
+ * painting, the pointer, the keys, the editor) is `cell_grid.js`, which is
+ * internal to the table.
+ *
+ * ══ COORDINATES ═════════════════════════════════════════════════════════
+ *
+ * A cell is `{row, col}`. `row` is the row's POSITION in the order shown — the
+ * index into `getDisplayedRows()`, after the sort and the filters — because a
+ * range is a rectangle on the screen, not in the data. `col` is the DATA column
+ * index (the one `headers`, `renderCell` and `hiddenColumns` use); a range
+ * spans the columns SHOWN between its two edges, so a hidden column inside it
+ * is not part of it. The cursor moves only over the rows of the page drawn.
+ */
+
+/**
+ * The selection model. Rows are positions `first..last`; columns are the data
+ * indices in `cols`, in the order they are shown. Both are handed in on every
+ * move (`setBounds`), because a filter, a page or a hidden column changes them
+ * under a selection that has to survive.
+ */
+export class CellSelection {
+    constructor() {
+        /** @type {{row:number, col:number}|null} */
+        this.anchor = null;
+        /** @type {{row:number, col:number}|null} the cursor */
+        this.focus = null;
+        this.first = 0;
+        this.last = -1;
+        this.cols = [];
+    }
+
+    /** The rows (positions, inclusive) and columns (data indices, shown order)
+     *  the cursor may stand on. A selection outside them is pulled in. */
+    setBounds(first, last, cols) {
+        this.first = first;
+        this.last = last;
+        this.cols = Array.isArray(cols) ? cols.slice() : [];
+        if (this.isEmptyGrid()) {
+            this.anchor = null;
+            this.focus = null;
+            return;
+        }
+        if (this.focus) this.focus = this._clamp(this.focus);
+        if (this.anchor) this.anchor = this._clamp(this.anchor);
+    }
+
+    isEmptyGrid() {
+        return this.last < this.first || this.cols.length === 0;
+    }
+
+    _ord(col) {
+        const i = this.cols.indexOf(col);
+        return i >= 0 ? i : 0;
+    }
+
+    _clamp({ row, col }) {
+        const r = Math.max(this.first, Math.min(this.last, row));
+        const c = this.cols.includes(col) ? col
+            : this.cols[Math.max(0, Math.min(this.cols.length - 1, this._nearestOrd(col)))];
+        return { row: r, col: c };
+    }
+
+    /** A column that is not shown any more: the shown one nearest its index. */
+    _nearestOrd(col) {
+        let best = 0;
+        for (let i = 0; i < this.cols.length; i++) if (this.cols[i] <= col) best = i;
+        return best;
+    }
+
+    _inside(row, ord) {
+        return row >= this.first && row <= this.last && ord >= 0 && ord < this.cols.length;
+    }
+
+    /** Put the cursor on one cell and collapse the range onto it. */
+    setCursor(row, col) {
+        if (this.isEmptyGrid()) return false;
+        this.focus = this._clamp({ row, col });
+        this.anchor = { ...this.focus };
+        return true;
+    }
+
+    /** Move the cursor to a cell and keep the anchor: the range grows. */
+    extendTo(row, col) {
+        if (!this.anchor) return this.setCursor(row, col);
+        if (this.isEmptyGrid()) return false;
+        this.focus = this._clamp({ row, col });
+        return true;
+    }
+
+    _go(cell, extend) {
+        return extend ? this.extendTo(cell.row, cell.col) : this.setCursor(cell.row, cell.col);
+    }
+
+    /** One step: the arrows. At an edge the cursor stays put. */
+    move(dRow, dCol, { extend = false } = {}) {
+        if (!this.focus) return this.setCursor(this.first, this.cols[0]);
+        const ord = Math.max(0, Math.min(this.cols.length - 1, this._ord(this.focus.col) + dCol));
+        const row = Math.max(this.first, Math.min(this.last, this.focus.row + dRow));
+        return this._go({ row, col: this.cols[ord] }, extend);
+    }
+
+    /**
+     * Ctrl+arrow: to the edge of the block of filled cells, as a spreadsheet
+     * does. From a filled cell whose neighbour is filled, to the last filled
+     * cell of that run; otherwise to the next filled cell along the line, or
+     * the edge of the grid when there is none.
+     *
+     * @param {number} dRow  -1, 0 or 1
+     * @param {number} dCol  -1, 0 or 1
+     * @param {(row:number, col:number) => boolean} filled
+     */
+    jump(dRow, dCol, filled, { extend = false } = {}) {
+        if (!this.focus) return this.setCursor(this.first, this.cols[0]);
+        let r = this.focus.row;
+        let o = this._ord(this.focus.col);
+        const isFilled = (row, ord) => !!filled(row, this.cols[ord]);
+        if (this._inside(r + dRow, o + dCol)) {
+            if (isFilled(r, o) && isFilled(r + dRow, o + dCol)) {
+                while (this._inside(r + dRow, o + dCol) && isFilled(r + dRow, o + dCol)) {
+                    r += dRow; o += dCol;
+                }
+            } else {
+                r += dRow; o += dCol;
+                while (!isFilled(r, o) && this._inside(r + dRow, o + dCol)) {
+                    r += dRow; o += dCol;
+                }
+            }
+        }
+        return this._go({ row: r, col: this.cols[o] }, extend);
+    }
+
+    /** Home / End: the first or last column of the cursor's row; with
+     *  `corner` (Ctrl), the first or last cell of the grid. */
+    lineEnd(toEnd, { extend = false, corner = false } = {}) {
+        if (!this.focus) return this.setCursor(this.first, this.cols[0]);
+        const col = toEnd ? this.cols[this.cols.length - 1] : this.cols[0];
+        const row = corner ? (toEnd ? this.last : this.first) : this.focus.row;
+        return this._go({ row, col }, extend);
+    }
+
+    /** Tab: one cell right, wrapping to the first cell of the next row (Shift:
+     *  left, wrapping to the last cell of the row before). The last cell of
+     *  the grid (the first, going back) stays put. */
+    tab(back = false) {
+        if (!this.focus) return this.setCursor(this.first, this.cols[0]);
+        let row = this.focus.row;
+        let ord = this._ord(this.focus.col) + (back ? -1 : 1);
+        if (ord >= this.cols.length) {
+            if (row >= this.last) return this.setCursor(row, this.focus.col);
+            row += 1; ord = 0;
+        } else if (ord < 0) {
+            if (row <= this.first) return this.setCursor(row, this.focus.col);
+            row -= 1; ord = this.cols.length - 1;
+        }
+        return this.setCursor(row, this.cols[ord]);
+    }
+
+    /** Whether Tab (Shift+Tab with `back`) has nowhere to go: the cursor is
+     *  on the grid's last cell (its first, going back). The grid then lets
+     *  the key move focus on, out of the table. */
+    tabEnds(back = false) {
+        if (!this.focus || this.isEmptyGrid()) return false;
+        const col = back ? this.cols[0] : this.cols[this.cols.length - 1];
+        const row = back ? this.first : this.last;
+        return this.focus.row === row && this.focus.col === col;
+    }
+
+    /** Every cell of the grid: from its first cell to its last, which is
+     *  where the cursor goes. */
+    selectAll() {
+        if (this.isEmptyGrid()) return false;
+        this.anchor = { row: this.first, col: this.cols[0] };
+        this.focus = { row: this.last, col: this.cols[this.cols.length - 1] };
+        return true;
+    }
+
+    /** The range collapses onto the cursor. */
+    collapse() {
+        if (!this.focus) return false;
+        const was = this.anchor && (this.anchor.row !== this.focus.row || this.anchor.col !== this.focus.col);
+        this.anchor = { ...this.focus };
+        return !!was;
+    }
+
+    clear() {
+        this.anchor = null;
+        this.focus = null;
+    }
+
+    /** `{top, bottom, left, right, columns}` — rows as positions, `left` and
+     *  `right` and `columns` as data indices — or null with nothing selected. */
+    range() {
+        if (!this.focus || !this.anchor) return null;
+        const a = this._ord(this.anchor.col);
+        const b = this._ord(this.focus.col);
+        const lo = Math.min(a, b);
+        const hi = Math.max(a, b);
+        return {
+            top: Math.min(this.anchor.row, this.focus.row),
+            bottom: Math.max(this.anchor.row, this.focus.row),
+            left: this.cols[lo],
+            right: this.cols[hi],
+            columns: this.cols.slice(lo, hi + 1),
+        };
+    }
+
+    contains(row, col) {
+        const r = this.range();
+        if (!r || row < r.top || row > r.bottom) return false;
+        return r.columns.includes(col);
+    }
+
+    isCursor(row, col) {
+        return !!this.focus && this.focus.row === row && this.focus.col === col;
+    }
+}

package/src/ui/components/choice_controls.js

@@ -0,0 +1,351 @@
+/**
+ * CHOICE CONTROLS — the one select, the one set of toggle chips and the one
+ * radio list, shared by `openForm` and the flow kit's settings widgets.
+ *
+ * Each draws a fixed list of options and reads back the option's OWN value —
+ * a number stays a number, an object stays the object — never the text of an
+ * `<option>` or a `value` attribute. That is why every control here keeps the
+ * values beside the DOM it draws and resolves the reader's choice by position.
+ *
+ * An option is a bare value, or `{ value, label?, description?, disabled?,
+ * reason? }`. Each also takes `{ group, options }` entries: `selectBox` draws
+ * one as an `<optgroup>`, the chips and the radio list as a `.twm-choice__group`
+ * heading over its options. A group with no options draws no heading there.
+ *
+ * A DISABLED OPTION IS SHOWN, WITH ITS REASON, AND IS NEVER CHOSEN BY VALUE:
+ * a stored value that names one is not selected (the select falls to its first
+ * enabled option, the radios to none, the chips leave it unpressed), unless
+ * `keepMissing` keeps it as a value the list does not offer. The reader cannot
+ * pick one either. What a caller does about a disabled option selected some
+ * other way (a script setting `.value`) is the caller's: `selectBox.entry()`
+ * and `choiceList.entry()` say which option is selected, disabled or not.
+ *
+ * `keepMissing` (the kit's rule, on by default): a stored value the list does
+ * not offer is KEPT, marked with `notFound(text)`, so a settings panel cannot
+ * silently turn it into the first entry on the next save. A form that should
+ * offer only what is listed passes `keepMissing: false`.
+ *
+ * `loose`: a stored value matches an option whose value has the same TEXT
+ * (`2` matches `'2'`), for a caller whose stored values may arrive as strings.
+ * Off by default: the kit's values keep their type, and `'2'` is not `2`.
+ * Text is only the fallback: an option whose value IS the stored value (`===`)
+ * wins over an earlier one that only reads the same (`findChoice`).
+ *
+ * Nothing here names a consumer's vocabulary; every word on screen is the
+ * caller's (`label`, `reason`, `description`, `notFound`).
+ */
+
+/** A value as one line of text shows it: a string as itself, anything else as JSON. */
+export const shownValue = (v) => (v === undefined ? '' : typeof v === 'string' ? v : JSON.stringify(v));
+
+function el(tag, className, text) {
+    const n = document.createElement(tag);
+    if (className) n.className = className;
+    if (text !== undefined && text !== null) n.textContent = String(text);
+    return n;
+}
+
+const isGroup = (o) => o !== null && typeof o === 'object' && Array.isArray(o.options) && 'group' in o;
+
+/** One option, normalised: `{value, label, description, disabled, reason}`. */
+function choiceOption(o) {
+    if (o === null || typeof o !== 'object') {
+        return { value: o, label: shownValue(o), description: null, disabled: false, reason: null };
+    }
+    return {
+        value: o.value,
+        label: o.label != null ? String(o.label) : shownValue(o.value),
+        description: o.description != null ? String(o.description) : null,
+        disabled: Boolean(o.disabled),
+        reason: o.reason != null && o.reason !== '' ? String(o.reason) : null,
+    };
+}
+
+/** Every option of a list, groups flattened in order. */
+export function flatChoices(options) {
+    const out = [];
+    for (const o of options || []) {
+        if (isGroup(o)) for (const inner of o.options) out.push(choiceOption(inner));
+        else out.push(choiceOption(o));
+    }
+    return out;
+}
+
+/**
+ * Where the chips and the radio list draw a group heading: the position in
+ * the flattened list of each non-empty group's first option, to its heading.
+ */
+function groupHeads(options) {
+    const heads = new Map();
+    let at = 0;
+    for (const o of options || []) {
+        if (!isGroup(o)) { at += 1; continue; }
+        if (o.options.length) heads.set(at, String(o.group ?? ''));
+        at += o.options.length;
+    }
+    return heads;
+}
+
+const groupHeading = (text) => el('div', 'twm-choice__group', text);
+
+/** Does stored `value` name option value `v`? */
+function sameChoice(v, value, loose = false) {
+    if (v === value) return true;
+    if (!loose || v === undefined || value === undefined || v === null || value === null) return false;
+    return String(v) === String(value);
+}
+
+/**
+ * The position in `list` (normalised options) of the option stored value `v`
+ * names, or -1: the first whose value IS `v`, else — with `loose` — the first
+ * whose value has the same text. `from` skips the leading entries.
+ */
+function choiceIndex(list, v, loose = false, from = 0) {
+    for (let i = from; i < list.length; i += 1) if (list[i].value === v) return i;
+    if (!loose) return -1;
+    for (let i = from; i < list.length; i += 1) if (sameChoice(list[i].value, v, true)) return i;
+    return -1;
+}
+
+/** The option of `list` stored value `v` names (`choiceIndex`), or undefined. */
+export function findChoice(list, v, loose = false) {
+    const i = choiceIndex(list, v, loose);
+    return i >= 0 ? list[i] : undefined;
+}
+
+/** An option's text: its label, and the reason it is unavailable when it is. */
+const optionText = (o) => (o.disabled && o.reason ? `${o.label} — ${o.reason}` : o.label);
+
+/**
+ * A `<select>` over `options`.
+ *
+ * `empty` (text) draws a first option that stands for "no value" (`undefined`).
+ * `valueAttr`: what each `<option value>` carries — `'index'` (its position;
+ * the kit's) or `'value'` (the option's value as text, so a script that sets
+ * `.value = 'b'` picks option `'b'`). The value READ BACK is the option's own
+ * either way.
+ *
+ * Returns `{ box, valueOf(), entry(), select(value), setOptions(options, value?) }`:
+ * `select` re-selects by value (true when the value is offered and enabled);
+ * `setOptions` redraws the list and places `value` (default: the current
+ * value) the way the first draw places one, so with `keepMissing` a value the
+ * list lacks shows as its own not-found entry.
+ */
+export function selectBox(options, value, {
+    empty = null, label = '', notFound = (v) => `${v} (not found)`, keepMissing = true,
+    valueAttr = 'index', loose = false, className = 'twm-flow-input twm-flow-input--select',
+} = {}) {
+    const box = el('select', className);
+    if (label) box.setAttribute('aria-label', label);
+    let entries = [];
+
+    const add = (parent, o) => {
+        const attr = valueAttr === 'index' ? String(entries.length) : (o.value === undefined ? '' : String(o.value));
+        // `createElement`, not `new Option`: the constructor is a window
+        // global, and a page that installed only `document` has none.
+        const opt = el('option', '', optionText(o));
+        opt.value = attr;
+        if (o.disabled) {
+            opt.disabled = true;
+            if (o.reason) opt.title = o.reason;
+        }
+        parent.appendChild(opt);
+        entries.push(o);
+    };
+    const firstEnabled = () => {
+        const i = entries.findIndex((e) => !e.disabled);
+        return i >= 0 ? i : 0;
+    };
+    const select = (v) => {
+        const start = empty !== null ? 1 : 0;
+        const at = choiceIndex(entries, v, loose, start);
+        if (at < 0 || entries[at].disabled || entries[at].stray) return false;
+        box.selectedIndex = at;
+        return true;
+    };
+    const place = (v) => {
+        if (select(v)) return;
+        if (keepMissing && v !== undefined && v !== null && v !== '') {
+            // A stored value the list no longer offers is KEPT as its own option:
+            // it must not silently become the first entry on the next save.
+            add(box, { value: v, label: notFound(shownValue(v)), description: null, disabled: false, reason: null,
+                       stray: true });
+            box.selectedIndex = entries.length - 1;
+            return;
+        }
+        box.selectedIndex = empty !== null ? 0 : firstEnabled();
+    };
+    const fill = (opts, v) => {
+        box.replaceChildren();
+        entries = [];
+        if (empty !== null) add(box, { value: undefined, label: String(empty), description: null, disabled: false,
+                                       reason: null });
+        for (const o of opts || []) {
+            if (isGroup(o)) {
+                const g = el('optgroup');
+                g.label = String(o.group ?? '');
+                for (const inner of o.options) add(g, choiceOption(inner));
+                box.appendChild(g);
+            } else {
+                add(box, choiceOption(o));
+            }
+        }
+        place(v);
+    };
+    const entry = () => (box.selectedIndex < 0 ? null : entries[box.selectedIndex] ?? null);
+    const valueOf = () => entry()?.value;
+
+    fill(options, value);
+    return {
+        box,
+        valueOf,
+        entry,
+        select,
+        setOptions(opts, v = valueOf()) { fill(opts, v); },
+    };
+}
+
+/**
+ * Toggle chips over a fixed list: a multi-select. The value is the list of
+ * pressed values in the list's order, and `onChange(list | undefined)` hears
+ * each toggle (`undefined` when none is pressed). With `keepMissing`, a stored
+ * entry the list lacks is kept, marked, until it is toggled off. A disabled
+ * option is a chip that cannot be pressed, its reason under its label.
+ *
+ * Returns `{ el, valueOf(), setValue(list), setOptions(options) }`;
+ * `setOptions` keeps the pressed values the new list still offers.
+ */
+export function toggleChips({ options, value, label, readOnly, onChange, notFound = (v) => `${v} (not found)`,
+                              keepMissing = true, loose = false }) {
+    const root = el('div', 'twm-flow-togglechips');
+    root.setAttribute('role', 'group');
+    if (label) root.setAttribute('aria-label', label);
+    let shown = [];           // the options as given, groups and all
+    let list = [];
+    let chosen = new Set();
+    let strays = [];
+
+    const emit = () => {
+        const out = valueOf();
+        onChange?.(out.length ? out : undefined);
+    };
+    const chipFor = (text, pressed, toggle, { stray = false, reason = null, disabled = false } = {}) => {
+        const b = el('button', `twm-flow-togglechip${stray ? ' twm-flow-togglechip--missing' : ''}`, text);
+        b.type = 'button';
+        b.setAttribute('aria-pressed', pressed ? 'true' : 'false');
+        b.disabled = Boolean(readOnly) || disabled;
+        if (reason) {
+            b.title = reason;
+            b.appendChild(el('span', 'twm-choice__reason', reason));
+        }
+        b.addEventListener('click', () => {
+            const on = toggle();
+            b.setAttribute('aria-pressed', on ? 'true' : 'false');
+            emit();
+        });
+        return b;
+    };
+    const draw = (opts, stored) => {
+        shown = opts || [];
+        list = flatChoices(shown);
+        const heads = groupHeads(shown);
+        const wanted = Array.isArray(stored) ? stored : [];
+        const offered = (v) => {
+            const o = findChoice(list, v, loose);
+            return o && !o.disabled ? o : undefined;
+        };
+        chosen = new Set(wanted.map(offered).filter(Boolean).map((o) => o.value));
+        strays = keepMissing ? wanted.filter((v) => !offered(v)) : [];
+        root.replaceChildren();
+        list.forEach((o, i) => {
+            if (heads.has(i)) root.appendChild(groupHeading(heads.get(i)));
+            root.appendChild(chipFor(o.label, chosen.has(o.value), () => {
+                if (o.disabled) return false;           // never chosen, even with the button forced
+                if (chosen.has(o.value)) chosen.delete(o.value); else chosen.add(o.value);
+                return chosen.has(o.value);
+            }, { disabled: o.disabled, reason: o.disabled ? o.reason : null }));
+        });
+        for (const v of [...strays]) {
+            root.appendChild(chipFor(notFound(shownValue(v)), true, () => {
+                const i = strays.indexOf(v);
+                if (i >= 0) { strays.splice(i, 1); return false; }
+                strays.push(v);
+                return true;
+            }, { stray: true }));
+        }
+    };
+    const valueOf = () => [...list.filter((o) => chosen.has(o.value)).map((o) => o.value), ...strays];
+    draw(options, value);
+    return {
+        el: root,
+        valueOf,
+        setValue: (stored) => draw(shown, stored),
+        setOptions: (opts) => draw(opts, valueOf()),
+    };
+}
+
+/**
+ * A one-of-N as radio rows, each with its label — and a sentence under it when
+ * the option has a `description`, and its `reason` when it is disabled. `name`
+ * groups the radios (the caller's, so it is unique where it needs to be).
+ *
+ * Returns `{ el, focus(), valueOf(), entry(), select(value), setOptions(options) }`.
+ * `onChange(value)` hears the reader's choice. With `keepMissing`, a stored
+ * value the list lacks is named in a note under the list (and kept by the
+ * caller, since no radio holds it).
+ */
+export function choiceList({ options, value, name, label, readOnly, onChange, notFound = (v) => `${v} (not found)`,
+                             keepMissing = true, loose = false }) {
+    const root = el('div', 'twm-flow-choices');
+    root.setAttribute('role', 'radiogroup');
+    if (label) root.setAttribute('aria-label', label);
+    let list = [];
+    let radios = [];
+
+    const draw = (opts, current) => {
+        list = flatChoices(opts);
+        const heads = groupHeads(opts);
+        radios = [];
+        root.replaceChildren();
+        const named = choiceIndex(list, current, loose);
+        const at = named >= 0 && !list[named].disabled ? named : -1;
+        list.forEach((o, i) => {
+            if (heads.has(i)) root.appendChild(groupHeading(heads.get(i)));
+            const row = el('label', `twm-flow-choice${o.disabled ? ' twm-choice--disabled' : ''}`);
+            const radio = el('input', 'twm-flow-choice__radio');
+            radio.type = 'radio';
+            radio.name = name;
+            radio.checked = i === at;
+            radio.disabled = Boolean(readOnly) || o.disabled;
+            radio.addEventListener('change', () => { if (radio.checked) onChange?.(o.value); });
+            radios.push(radio);
+            const words = el('span', 'twm-flow-choice__words');
+            words.appendChild(el('span', 'twm-flow-choice__label', o.label));
+            if (o.description !== null) words.appendChild(el('span', 'twm-flow-choice__sub', o.description));
+            if (o.disabled && o.reason) words.appendChild(el('span', 'twm-choice__reason', o.reason));
+            row.append(radio, words);
+            root.appendChild(row);
+        });
+        if (keepMissing && current !== undefined && named < 0) {
+            root.appendChild(el('p', 'twm-flow-field__note', notFound(shownValue(current))));
+        }
+    };
+    const checkedAt = () => radios.findIndex((r) => r.checked);
+    const entry = () => list[checkedAt()] ?? null;
+    const api = {
+        el: root,
+        focus: () => (radios.find((r) => r.checked && !r.disabled) || radios.find((r) => !r.disabled))
+            ?.focus({ preventScroll: true }),
+        entry,
+        valueOf: () => entry()?.value,
+        select(v) {
+            const named = choiceIndex(list, v, loose);
+            const at = named >= 0 && !list[named].disabled ? named : -1;
+            radios.forEach((r, i) => { r.checked = i === at; });
+            return at >= 0;
+        },
+        setOptions(opts) { draw(opts, api.valueOf()); },
+    };
+    draw(options, value);
+    return api;
+}