flexdesk 0.17.18 → 0.18.1

package/src/ui/components/option_list.js

@@ -0,0 +1,160 @@
+/**
+ * THE ROWS `createSelect`, `createCombobox` AND `createTagInput`'s SUGGESTIONS
+ * DRAW: a `role="listbox"` of options, each with a glyph, a label, a second line,
+ * a hint at the end of the row and, when disabled, its reason; `{ group, options }`
+ * sections under a heading; one active row that the arrow keys walk.
+ *
+ * Focus never comes here. The text box or trigger that holds it names the active
+ * row with `aria-activedescendant` (`onActive`), and a press on a row is
+ * prevented from taking focus, so that a list row can be chosen with the box
+ * still holding the caret, and no blur closes the list under the pointer.
+ *
+ * `aria-selected` says which row IS the current value; the active row is a class.
+ * They are different things in a select, where the highlight walks away from the
+ * value and comes back. Every word is built with `textContent`: these lists carry
+ * text users wrote.
+ *
+ * An internal part: not exported from `@flexdesk/widgets`.
+ */
+
+let SEQ = 0;
+
+function node(tag, className, text) {
+    const n = document.createElement(tag);
+    if (className) n.className = className;
+    if (text !== undefined && text !== null) n.textContent = String(text);
+    return n;
+}
+
+/** `text` with the first run of `needle` in a `<mark>`, so it is plain why a row is offered. */
+function marked(target, text, needle) {
+    const at = needle ? text.toLowerCase().indexOf(needle.toLowerCase()) : -1;
+    if (at < 0) { target.textContent = text; return; }
+    target.append(text.slice(0, at), node('mark', 'twm-option-list__match', text.slice(at, at + needle.length)),
+                  text.slice(at + needle.length));
+}
+
+/**
+ * @param {object} o
+ * @param {(option: object) => void} o.onPick   A row was clicked. Never a disabled one.
+ * @param {(id: string|null) => void} [o.onActive]  The active row's id changed.
+ */
+export function createOptionList({ onPick, onActive = null }) {
+    const id = `twm-option-list-${++SEQ}`;
+    const el = node('div', 'twm-option-list');
+    el.id = id;
+    el.setAttribute('role', 'listbox');
+
+    /** Every row drawn: `{ option, row }`. */
+    let rows = [];
+    let active = -1;
+
+    const paintActive = () => {
+        rows.forEach(({ row }, i) => row.classList.toggle('twm-option-list__row--active', i === active));
+        const row = rows[active]?.row;
+        // jsdom does not implement it, and a test harness is no reason to drop it.
+        row?.scrollIntoView?.({ block: 'nearest' });
+        onActive?.(row ? row.id : null);
+    };
+
+    const rowFor = (option, { glyphs, mark, isCurrent }) => {
+        const row = node('div', 'twm-option-list__row');
+        row.id = `${id}-${rows.length}`;
+        row.setAttribute('role', 'option');
+        row.setAttribute('aria-selected', String(!!isCurrent?.(option)));
+        if (option.disabled) row.setAttribute('aria-disabled', 'true');
+        row.title = option.description ? `${option.label} — ${option.description}` : option.label;
+        if (glyphs) {
+            const glyph = node('span', 'twm-option-list__glyph material-symbols-outlined', option.icon || '');
+            glyph.setAttribute('aria-hidden', 'true');
+            row.appendChild(glyph);
+        }
+        const words = node('span', 'twm-option-list__words');
+        const label = node('span', 'twm-option-list__label');
+        marked(label, option.label, mark);
+        words.appendChild(label);
+        if (option.description) words.appendChild(node('span', 'twm-option-list__description', option.description));
+        if (option.disabled && option.reason) words.appendChild(node('span', 'twm-choice__reason', option.reason));
+        row.appendChild(words);
+        if (option.hint) row.appendChild(node('span', 'twm-option-list__hint', option.hint));
+        return row;
+    };
+
+    const enabled = () => rows.map((r, i) => (r.option.disabled ? -1 : i)).filter((i) => i >= 0);
+
+    // A press on the list leaves focus where it is. See the header.
+    el.addEventListener('mousedown', (ev) => ev.preventDefault());
+    el.addEventListener('click', (ev) => {
+        const row = ev.target.closest?.('[role="option"]');
+        const hit = rows.find((r) => r.row === row);
+        if (hit && !hit.option.disabled) onPick(hit.option);
+    });
+
+    return {
+        el,
+        id,
+        /**
+         * Draw `sections` (`[{ heading, items }]`, as `choiceSections` gives them).
+         * @param {object} [opts]
+         * @param {string} [opts.mark]  The text to mark in each label.
+         * @param {(option: object) => boolean} [opts.isCurrent]  Is this the current value?
+         */
+        setRows(sections, { mark = '', isCurrent = null } = {}) {
+            rows = [];
+            active = -1;
+            el.replaceChildren();
+            const glyphs = sections.some((s) => s.items.some((o) => o.icon));
+            for (const { heading, items } of sections) {
+                let parent = el;
+                if (heading != null) {
+                    parent = node('div', 'twm-option-list__section');
+                    parent.setAttribute('role', 'group');
+                    parent.setAttribute('aria-label', heading);
+                    const title = node('div', 'twm-choice__group', heading);
+                    title.setAttribute('aria-hidden', 'true');
+                    parent.appendChild(title);
+                    el.appendChild(parent);
+                }
+                for (const option of items) {
+                    const row = rowFor(option, { glyphs, mark, isCurrent });
+                    rows.push({ option, row });
+                    parent.appendChild(row);
+                }
+            }
+            paintActive();
+        },
+        /** One line of text in place of the rows: nothing matched, still loading, a failure. */
+        setMessage(text) {
+            rows = [];
+            active = -1;
+            el.replaceChildren(node('div', 'twm-option-list__message', text));
+            paintActive();
+        },
+        /** How many rows are drawn. */
+        get size() { return rows.length; },
+        /** The drawn options, in order. */
+        options: () => rows.map((r) => r.option),
+        /** The active row's option, or null. */
+        activeOption: () => rows[active]?.option ?? null,
+        /** Make row `index` active; -1, or a row that is disabled, makes none active. */
+        setActive(index) {
+            active = rows[index] && !rows[index].option.disabled ? index : -1;
+            paintActive();
+        },
+        /** The next row that may be chosen, by `step`, wrapping. From none: the first or the last. */
+        move(step) {
+            const stops = enabled();
+            if (!stops.length) return;
+            const at = stops.indexOf(active);
+            const next = at < 0 ? (step > 0 ? 0 : stops.length - 1) : (at + step + stops.length) % stops.length;
+            active = stops[next];
+            paintActive();
+        },
+        /** The first (`step` 1) or last (`step` -1) row that may be chosen. */
+        moveToEnd(step) {
+            const stops = enabled();
+            active = stops.length ? stops[step > 0 ? 0 : stops.length - 1] : -1;
+            paintActive();
+        },
+    };
+}

package/src/ui/components/popover.js

@@ -0,0 +1,94 @@
+/**
+ * A POPOVER — a panel of rich content hung off the element that opened it. (0.18.0)
+ *
+ * `role="dialog"`, on an anchored layer (`anchored_layer.js`, which says how it is
+ * placed and what closes it). Focus moves into it on open and comes back to the
+ * anchor on close. Opening one from the anchor that holds an open one closes it,
+ * a toggle; opening one anywhere else closes the open one, unless that one owns
+ * the new anchor (`anchored_layer.js`).
+ *
+ * TAB STAYS INSIDE, cycling the panel's controls, as a modal's and a `CategoryPicker`'s
+ * do. The panel is mounted at the end of the page, so past its edge lies whatever comes
+ * next in the document, which is not the anchor's neighbour and, over a modal, is behind
+ * it. Escape is the way out.
+ */
+import { openAnchoredLayer } from './anchored_layer.js';
+import { collectFocusable } from '../utils/focusable.js';
+
+/** The open popovers, to find the one an anchor holds. */
+const OPEN = new Set();
+
+/** What a call answers when nothing opened. */
+const nothingOpened = (toggled) => ({ el: null, close() {}, closed: Promise.resolve(), reposition() {}, toggled });
+
+/** Tab at the panel's edge goes round to the other edge. */
+function keepTabInside(el) {
+    el.addEventListener('keydown', (ev) => {
+        if (ev.key !== 'Tab' || ev.defaultPrevented) return;
+        const controls = collectFocusable(el);
+        if (!controls.length) { ev.preventDefault(); return; }
+        const first = controls[0];
+        const last = controls[controls.length - 1];
+        const active = el.ownerDocument.activeElement;
+        if (ev.shiftKey ? (active === first || active === el) : active === last) {
+            ev.preventDefault();
+            (ev.shiftKey ? last : first).focus();
+        }
+    });
+}
+
+/**
+ * @param {object} o
+ * @param {HTMLElement} o.anchor     What opened it; focus returns here.
+ * @param {HTMLElement} o.content    The popover's body.
+ * @param {string} [o.label]         Its accessible name.
+ * @param {string} [o.className]     Extra classes on the panel.
+ * @param {HTMLElement} [o.focus]    What takes focus on open; else the panel.
+ * @param {'start'|'end'} [o.align]  Which anchor edge it lines up with first.
+ * @param {string} [o.inside]        A selector for floating things of your own that
+ *                                   are not "outside" it.
+ * @param {(reason: string) => void} [o.onClose]  After it is gone.
+ * @returns {{el: HTMLElement|null, close: (reason?: string) => void, closed: Promise<void>,
+ *            reposition: () => void, toggled: boolean}}
+ *          `el` is null when nothing opened, and `onClose` is not called for it: `toggled`
+ *          is true when the call only CLOSED the popover its anchor held, false when
+ *          the anchor has left the document.
+ */
+export function openPopover({ anchor, content, label = '', className = '', focus = null, align = 'start',
+                              inside = null, onClose = null }) {
+    for (const open of OPEN) {
+        if (anchor && open.anchor === anchor) {
+            open.close('toggle');
+            return nothingOpened(true);
+        }
+    }
+
+    const el = document.createElement('div');
+    el.className = `twm-popover${className ? ` ${className}` : ''}`;
+    el.setAttribute('role', 'dialog');
+    if (label) el.setAttribute('aria-label', label);
+    el.tabIndex = -1;
+    el.appendChild(content);
+    keepTabInside(el);
+
+    let settle;
+    const closed = new Promise((resolve) => { settle = resolve; });
+    const layer = openAnchoredLayer({
+        anchor, el, align, gap: 4, inside,
+        onClose(reason) {
+            OPEN.delete(handle);
+            anchor?.classList?.remove('twm-is-open');
+            anchor?.setAttribute?.('aria-expanded', 'false');
+            onClose?.(reason);
+            settle();
+        },
+    });
+    if (!layer) return nothingOpened(false);
+    const handle = { el, anchor, closed, toggled: false, close: layer.close, reposition: layer.place };
+    OPEN.add(handle);
+    anchor?.classList?.add('twm-is-open');
+    if (anchor && !anchor.hasAttribute?.('aria-haspopup')) anchor.setAttribute?.('aria-haspopup', 'dialog');
+    anchor?.setAttribute?.('aria-expanded', 'true');
+    (focus || el).focus?.({ preventScroll: true });
+    return handle;
+}

package/src/ui/components/recent_items.js

@@ -0,0 +1,169 @@
+/**
+ * recent_items.js — a most-recent-first list kept through the Host's `state`
+ * capability, so it survives a restart.
+ *
+ *     const recent = createRecentItems({ host, key: 'recent-workspaces' });
+ *     await recent.load();
+ *     recent.add({ id: 'w1', name: 'North' });
+ *     recent.list();    // [{ id: 'w1', name: 'North', openedAt: 1730... }]
+ *
+ * An entry is any plain object; `identity` says which two are the same one, and
+ * `add` stamps `openedAt`. `capacity` is per `groupOf(entry)` when that is
+ * given, so one busy kind of entry never pushes another kind out.
+ *
+ * ══ A READ THAT FAILS IS NOT AN EMPTY LIST ═════════════════════════════════
+ *
+ * A `host.state.read` that rejects says nothing about what is stored, so until
+ * a read succeeds the stored list is never written: writing would replace
+ * entries nobody has seen. Changes made in the meantime show in `list()` at
+ * once, are kept, are replayed onto the stored list when it is read, and each
+ * of them asks for the read again. A read that answers something other than an
+ * array is a read: the store is empty.
+ *
+ * Writes run one at a time and the last one carries the latest list, because a
+ * host may answer them out of order and the older list must not win.
+ *
+ * A host with no `state` capability keeps the list in memory for this session.
+ */
+
+/**
+ * @param {object} options
+ * @param {object} options.host - The Host; its `state` keeps the list
+ * @param {string} options.key - The state key the list is stored under
+ * @param {(entry: object) => string} [options.identity] - Which entries are the same one
+ * @param {(entry: unknown) => boolean} [options.isValid] - Stored entries that fail this
+ *   are dropped on read, as is one that makes it, `identity` or `groupOf` throw, so
+ *   `identity` may assume an entry's shape.
+ * @param {number} [options.capacity=10] - The most entries kept, per group
+ * @param {(entry: object) => string} [options.groupOf] - Groups the capacity counts within
+ * @param {() => void} [options.onChange] - After every change, and after a read that
+ *   replayed changes
+ * @param {object} [options.logger] - Its `warn` hears a failed read or write
+ */
+export function createRecentItems({
+    host,
+    key,
+    identity = (entry) => entry.id,
+    isValid = (entry) => !!entry && typeof entry === 'object' && !!identity(entry),
+    capacity = 10,
+    groupOf = () => '',
+    onChange = null,
+    logger = null,
+}) {
+    const state = host?.state ?? null;
+    let entries = [];
+    let loaded = !state;
+    /** The changes made while the stored list is unread, oldest first: list => list. */
+    let pending = [];
+    let reading = null;
+    let writing = false;
+    let writeAgain = false;
+
+    const capped = (list) => {
+        const counts = new Map();
+        return list.filter((entry) => {
+            const group = groupOf(entry);
+            const count = (counts.get(group) ?? 0) + 1;
+            counts.set(group, count);
+            return count <= capacity;
+        });
+    };
+
+    const without = (list, entry) => {
+        const id = identity(entry);
+        return list.filter((other) => identity(other) !== id);
+    };
+
+    async function write() {
+        if (!state) return;
+        if (writing) {
+            writeAgain = true;
+            return;
+        }
+        writing = true;
+        do {
+            writeAgain = false;
+            try {
+                await state.write(key, entries);
+            } catch (err) {
+                logger?.warn?.(`Could not save the recent list "${key}"`, err);
+            }
+        } while (writeAgain);
+        writing = false;
+    }
+
+    /** A stored entry the list can hold: everything it goes through accepts it. */
+    const usable = (entry) => {
+        try {
+            if (!isValid(entry)) return false;
+            identity(entry);
+            groupOf(entry);
+            return true;
+        } catch (err) {
+            logger?.warn?.(`Dropped an unreadable entry of the recent list "${key}"`, err);
+            return false;
+        }
+    };
+
+    async function read() {
+        let stored;
+        try {
+            const saved = await state.read(key);
+            stored = Array.isArray(saved) ? capped(saved.filter(usable)) : [];
+        } catch (err) {
+            logger?.warn?.(`Could not read the recent list "${key}"; the stored list is left unchanged until it can be read`, err);
+            return false;
+        }
+        const replay = pending;
+        pending = [];
+        loaded = true;
+        entries = replay.reduce((list, apply) => apply(list), stored);
+        if (replay.length > 0) {
+            onChange?.();
+            void write();
+        }
+        return true;
+    }
+
+    /**
+     * Read the stored list. Call it once at startup, before anything lists; a
+     * change made while the list is unread calls it again. Once a read has
+     * succeeded it does not read again.
+     * @returns {Promise<boolean>} Whether the stored list has been read
+     */
+    function load() {
+        if (!state) return Promise.resolve(false);
+        if (loaded) return Promise.resolve(true);
+        reading ??= read().finally(() => { reading = null; });
+        return reading;
+    }
+
+    function change(apply) {
+        entries = apply(entries);
+        onChange?.();
+        if (loaded) {
+            void write();
+            return;
+        }
+        pending.push(apply);
+        void load();
+    }
+
+    return Object.freeze({
+        load,
+        /** @returns {ReadonlyArray<object>} Most recent first */
+        list: () => Object.freeze(entries.map((entry) => Object.freeze({ ...entry }))),
+        /** Put an entry at the top, dropping the older one with its identity. */
+        add(entry) {
+            const stamped = { ...entry, openedAt: Date.now() };
+            change((list) => capped([stamped, ...without(list, stamped)]));
+        },
+        /** Drop the entry with this one's identity. */
+        remove(entry) {
+            change((list) => without(list, entry));
+        },
+        clear() {
+            change(() => []);
+        },
+    });
+}