flexdesk 0.16.1 → 0.17.1

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;
+}

package/src/ui/components/color_field.js

@@ -0,0 +1,211 @@
+/**
+ * ColorField — one colour: a swatch that opens the native picker, a hex text
+ * box kept in step with it, and an optional row of preset swatches.
+ *
+ *   const field = new ColorField({
+ *       value: 'rgb(31, 119, 180)',            // shown as #1f77b4
+ *       presets: ['#1f77b4', '#ff7f0e', '#2ca02c'],
+ *       onChange: (hex, { commit }) => { ... },
+ *   });
+ *   host.appendChild(field.render());
+ *   field.getValue();                          // '#1f77b4' | '' | null
+ *
+ * THE HEX BOX IS THE CONTROL. Picking in the swatch writes the box and fires
+ * the box's own `input` (and, when the picker commits, `change`); a preset
+ * does the same. So there is one path from any gesture to the value, and a
+ * host listening on the box — `openForm` does, by its `name` — hears every
+ * change whatever made it. Typing a valid hex moves the swatch; typing an
+ * invalid one leaves the swatch on the last good colour and marks the field
+ * `.twm-color-field--invalid`.
+ *
+ * VALUES. `getValue()` is the colour as lowercase `#rrggbb`, `''` when the box
+ * is empty, and `null` when what is typed is not a hex colour (`#rgb` and
+ * `#rrggbb` are). An `rgb()` / `rgba()` value handed IN — a default, a preset,
+ * `setValue` — is converted to its hex equivalent first; alpha is dropped,
+ * because the native picker has no alpha channel.
+ *
+ * `onChange(value, { commit })` runs on every edit with `commit: false` and on
+ * the box's `change` (blur, Enter, a preset, the picker closing) with
+ * `commit: true`.
+ */
+
+const HEX_RE = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i;
+const RGB_RE = /^rgba?\(\s*([^)]*)\)$/i;
+
+/** True for `#rgb` and `#rrggbb` (any case), and nothing else. */
+export function isHexColor(value) {
+    return typeof value === 'string' && HEX_RE.test(value.trim());
+}
+
+/**
+ * A colour as lowercase `#rrggbb`, or null when `value` is not one.
+ * Accepts `#rgb`, `#rrggbb` and `rgb()` / `rgba()` in comma or space syntax,
+ * with channels as 0–255 or percentages; an alpha channel is dropped.
+ */
+export function normalizeHex(value) {
+    if (typeof value !== 'string') return null;
+    const s = value.trim();
+    if (HEX_RE.test(s)) {
+        const h = s.slice(1).toLowerCase();
+        return h.length === 3 ? `#${h[0]}${h[0]}${h[1]}${h[1]}${h[2]}${h[2]}` : `#${h}`;
+    }
+    const m = RGB_RE.exec(s);
+    if (!m) return null;
+    const parts = m[1].split(/\s*[,/]\s*|\s+/).filter(Boolean);
+    if (parts.length < 3 || parts.length > 4) return null;
+    const channels = [];
+    for (const p of parts.slice(0, 3)) {
+        const pct = p.endsWith('%');
+        const n = Number(pct ? p.slice(0, -1) : p);
+        if (!Number.isFinite(n)) return null;
+        const v = pct ? (n / 100) * 255 : n;
+        if (v < 0 || v > 255) return null;
+        channels.push(Math.round(v));
+    }
+    return `#${channels.map((c) => c.toString(16).padStart(2, '0')).join('')}`;
+}
+
+/** What the box shows for a value handed in: its hex if it is a colour, else as given. */
+function displayText(value) {
+    if (value == null) return '';
+    return normalizeHex(String(value)) ?? String(value);
+}
+
+export class ColorField {
+    /**
+     * @param {Object}   [o]
+     * @param {string}   [o.value]     initial colour (hex or rgb()); '' for none
+     * @param {string[]} [o.presets]   preset colours drawn as buttons; ones that
+     *                                 are not colours are left out
+     * @param {string}   [o.name]      `name` of the hex box, for a host form
+     * @param {string}   [o.label]     accessible name of the swatch and the box
+     * @param {Function} [o.onChange]  `(value, { commit })`, value as `getValue()`
+     */
+    constructor({ value = '', presets = [], name = null, label = null, onChange = null } = {}) {
+        this.initial = displayText(value);
+        this.presets = (Array.isArray(presets) ? presets : []).map(normalizeHex).filter(Boolean);
+        this.name = name;
+        this.label = label;
+        this.onChange = typeof onChange === 'function' ? onChange : null;
+
+        this.root = null;
+        this.swatch = null;
+        this.hex = null;
+        this._disposers = [];
+    }
+
+    render() {
+        if (this.root) return this.root;
+        const root = document.createElement('div');
+        root.className = 'twm-color-field';
+
+        const swatch = document.createElement('input');
+        swatch.type = 'color';
+        swatch.className = 'twm-color-field__swatch';
+        swatch.value = normalizeHex(this.initial) ?? '#000000';
+        if (this.label) swatch.title = this.label;
+
+        const hex = document.createElement('input');
+        hex.type = 'text';
+        hex.className = 'twm-color-field__hex';
+        hex.value = this.initial;
+        hex.placeholder = '#rrggbb';
+        hex.spellcheck = false;
+        hex.autocomplete = 'off';
+        hex.maxLength = 7;
+        if (this.name) hex.name = this.name;
+        if (this.label) hex.setAttribute('aria-label', this.label);
+
+        root.append(swatch, hex);
+        this.root = root;
+        this.swatch = swatch;
+        this.hex = hex;
+
+        if (this.presets.length) {
+            const strip = document.createElement('div');
+            strip.className = 'twm-color-field__presets';
+            for (const color of this.presets) {
+                const btn = document.createElement('button');
+                btn.type = 'button';
+                btn.className = 'twm-color-field__preset';
+                btn.style.backgroundColor = color;
+                btn.title = color;
+                btn.setAttribute('aria-label', color);
+                this.#listen(btn, 'click', () => this.#writeBox(color, true));
+                strip.appendChild(btn);
+            }
+            root.appendChild(strip);
+        }
+
+        // Every gesture lands on the box; the box's listeners do the rest.
+        this.#listen(swatch, 'input', () => this.#writeBox(swatch.value, false));
+        this.#listen(swatch, 'change', () => this.#writeBox(swatch.value, true));
+        this.#listen(hex, 'input', () => this.#sync(false));
+        this.#listen(hex, 'change', () => {
+            const v = this.getValue();
+            if (v) hex.value = v;                // canonical form once committed
+            this.#sync(true);
+        });
+
+        this.#sync(null);
+        return root;
+    }
+
+    /** `#rrggbb`, `''` when empty, or `null` when the box holds no hex colour. */
+    getValue() {
+        const text = this.getText().trim();
+        if (text === '') return '';
+        return isHexColor(text) ? normalizeHex(text) : null;
+    }
+
+    /** The box as it stands. */
+    getText() {
+        return this.hex ? this.hex.value : this.initial;
+    }
+
+    isValid() {
+        return this.getValue() !== null;
+    }
+
+    /** Write a colour (hex or rgb()) without firing `onChange`. */
+    setValue(value) {
+        const text = displayText(value);
+        if (!this.hex) { this.initial = text; return; }
+        this.hex.value = text;
+        this.#sync(null);
+    }
+
+    focus() {
+        this.hex?.focus();
+    }
+
+    dispose() {
+        for (const d of this._disposers) {
+            try { d(); } catch { /* listener already gone */ }
+        }
+        this._disposers = [];
+        this.root = null;
+        this.swatch = null;
+        this.hex = null;
+    }
+
+    #listen(el, type, fn) {
+        el.addEventListener(type, fn);
+        this._disposers.push(() => el.removeEventListener(type, fn));
+    }
+
+    /** Put `text` in the box and fire the box's own events, as typing would. */
+    #writeBox(text, commit) {
+        this.hex.value = text;
+        this.hex.dispatchEvent(new Event('input', { bubbles: true }));
+        if (commit) this.hex.dispatchEvent(new Event('change', { bubbles: true }));
+    }
+
+    /** Swatch and invalid mark follow the box; `commit === null` is silent. */
+    #sync(commit) {
+        const v = this.getValue();
+        if (v) this.swatch.value = v;
+        this.root.classList.toggle('twm-color-field--invalid', v === null);
+        if (commit !== null) this.onChange?.(v, { commit });
+    }
+}