flexdesk 0.16.0 → 0.17.0

package/src/ui/components/tag_input.js

@@ -0,0 +1,215 @@
+/**
+ * tag_input.js — A LIST OF SHORT STRINGS, drawn as removable chips followed by
+ * a text box. (0.17.0)
+ *
+ *     ┌──────────────────────────────────────────────────┐
+ *     │ [baseline ×] [stress ×] [q3 ×]  Add a tag…        │
+ *     └──────────────────────────────────────────────────┘
+ *
+ * The text box commits what was typed — trimmed, split at commas — on Enter,
+ * on a comma and when it loses focus. Empty pieces are dropped, and so is a
+ * piece already in the list unless `allowDuplicates`. Backspace in an empty
+ * box removes the last chip. A paste that carries a comma is split into
+ * chips at once; a paste without one is ordinary text in the box.
+ *
+ * Every chip has a remove button with an `aria-label` (`removeLabel(tag)`,
+ * "Remove <tag>" by default). `readOnly` draws the chips alone: no remove
+ * buttons and no text box.
+ *
+ * `onChange(list)` is called with a fresh copy of the list after every change
+ * the reader makes — never for `setValue`, and never for a commit that added
+ * nothing.
+ *
+ *     const tags = createTagInput(host, {
+ *         value: ['baseline'],
+ *         placeholder: 'Add a tag…',
+ *         onChange: (list) => save(list),
+ *     });
+ *     tags.getValue();          // ['baseline']
+ *     tags.setValue(['a', 'b']);
+ *     tags.dispose();
+ */
+
+/** The list as strings, the empty ones left out. */
+const normalise = (list) => (Array.isArray(list) ? list : [])
+    .map((v) => (v == null ? '' : String(v).trim()))
+    .filter((v) => v !== '');
+
+/**
+ * @typedef {Object} TagInputOptions
+ * @property {string[]} [value] - The tags it opens with.
+ * @property {string} [placeholder] - The empty text box's placeholder.
+ * @property {boolean} [readOnly] - Chips only: no remove buttons, no text box.
+ * @property {boolean} [allowDuplicates] - Keep a tag that is already in the list.
+ * @property {(list: string[]) => void} [onChange] - After each change the reader makes.
+ * @property {string} [label] - The text box's accessible name.
+ * @property {(tag: string) => string} [removeLabel] - A remove button's `aria-label`.
+ * @property {string} [className] - Extra classes on the root.
+ */
+
+/**
+ * @param {HTMLElement} host
+ * @param {TagInputOptions} [options]
+ */
+export function createTagInput(host, options = {}) {
+    if (!host || typeof host.appendChild !== 'function') {
+        throw new Error('[TagInput] host must be an HTMLElement');
+    }
+    const readOnly = !!options.readOnly;
+    const allowDuplicates = !!options.allowDuplicates;
+    const removeLabel = typeof options.removeLabel === 'function'
+        ? options.removeLabel : (tag) => `Remove ${tag}`;
+
+    let tags = normalise(options.value);
+    let disposed = false;
+
+    const root = document.createElement('div');
+    root.className = ['twm-tag-input', readOnly ? 'twm-tag-input--readonly' : '', options.className || '']
+        .join(' ').replace(/\s+/g, ' ').trim();
+    root.setAttribute('role', 'group');
+    if (options.label) root.setAttribute('aria-label', options.label);
+
+    const chips = document.createElement('ul');
+    chips.className = 'twm-tag-input__chips';
+    root.appendChild(chips);
+
+    let input = null;
+    if (!readOnly) {
+        input = document.createElement('input');
+        input.type = 'text';
+        input.className = 'twm-tag-input__input';
+        input.spellcheck = false;
+        input.autocomplete = 'off';
+        if (options.placeholder) input.placeholder = options.placeholder;
+        if (options.label) input.setAttribute('aria-label', options.label);
+        root.appendChild(input);
+    }
+
+    const changed = () => {
+        if (typeof options.onChange === 'function') options.onChange([...tags]);
+    };
+
+    const chipFor = (tag, idx) => {
+        const chip = document.createElement('li');
+        chip.className = 'twm-tag-input__chip';
+        const text = document.createElement('span');
+        text.className = 'twm-tag-input__text';
+        text.textContent = tag;
+        text.title = tag;
+        chip.appendChild(text);
+        if (!readOnly) {
+            const remove = document.createElement('button');
+            remove.type = 'button';
+            remove.className = 'twm-tag-input__remove';
+            remove.setAttribute('aria-label', removeLabel(tag));
+            remove.textContent = '×';
+            // The text box keeps the focus: a blur would commit its text
+            // and redraw the chips under the pointer before the click.
+            remove.addEventListener('mousedown', (ev) => ev.preventDefault());
+            remove.addEventListener('click', (ev) => {
+                ev.preventDefault();
+                ev.stopPropagation();
+                removeAt(idx);
+                input?.focus();
+            });
+            chip.appendChild(remove);
+        }
+        return chip;
+    };
+
+    /** Redraws every chip. */
+    const paint = () => {
+        chips.replaceChildren(...tags.map(chipFor));
+    };
+
+    function removeAt(idx) {
+        if (disposed || readOnly || idx < 0 || idx >= tags.length) return;
+        tags = tags.filter((_, i) => i !== idx);
+        paint();
+        changed();
+    }
+
+    /** Adds the comma-separated pieces of `text`; true when any was added. */
+    const commitText = (text) => {
+        if (disposed || readOnly) return false;
+        const next = [...tags];
+        for (const piece of String(text).split(',')) {
+            const tag = piece.trim();
+            if (tag === '') continue;
+            if (!allowDuplicates && next.includes(tag)) continue;
+            next.push(tag);
+        }
+        if (next.length === tags.length) return false;
+        // Only the new chips are drawn: the ones already there stay in place,
+        // so a remove button that the focus is moving to (Tab out of the box
+        // commits its text) is still in the document when the focus lands.
+        const added = next.slice(tags.length).map((tag, i) => chipFor(tag, tags.length + i));
+        tags = next;
+        chips.append(...added);
+        changed();
+        return true;
+    };
+
+    const commitInput = () => {
+        if (!input) return;
+        const text = input.value;
+        input.value = '';
+        commitText(text);
+    };
+
+    if (input) {
+        input.addEventListener('keydown', (ev) => {
+            if (ev.isComposing) return;
+            if (ev.key === 'Enter' || ev.key === ',') {
+                ev.preventDefault();
+                commitInput();
+            } else if (ev.key === 'Backspace' && input.value === '' && tags.length) {
+                ev.preventDefault();
+                removeAt(tags.length - 1);
+            }
+        });
+        // A comma that arrives without its keydown (a soft keyboard, an IME,
+        // a drop) commits all the same.
+        input.addEventListener('input', () => {
+            if (input.value.includes(',')) commitInput();
+        });
+        input.addEventListener('blur', commitInput);
+        input.addEventListener('paste', (ev) => {
+            const pasted = ev.clipboardData?.getData('text/plain') ?? '';
+            if (!pasted.includes(',')) return;
+            ev.preventDefault();
+            const start = input.selectionStart ?? input.value.length;
+            const end = input.selectionEnd ?? start;
+            const text = input.value.slice(0, start) + pasted + input.value.slice(end);
+            input.value = '';
+            commitText(text);
+        });
+        root.addEventListener('mousedown', (ev) => {
+            if (ev.target === root || ev.target === chips) {
+                ev.preventDefault();
+                input.focus();
+            }
+        });
+    }
+
+    paint();
+    host.appendChild(root);
+
+    return {
+        element: root,
+        input,
+        getValue: () => [...tags],
+        /** Replaces the list. Does not call `onChange`. */
+        setValue(list) {
+            if (disposed) return;
+            tags = normalise(list);
+            paint();
+        },
+        focus() { input?.focus(); },
+        dispose() {
+            if (disposed) return;
+            disposed = true;
+            root.remove();
+        },
+    };
+}

package/src/ui/components/toast.js

@@ -1,25 +1,42 @@
 /**
- * toast.js — thin wrapper around the global NotificationCenter for
+ * toast.js — thin wrapper around the mounted NotificationCenter for
  * callers that don't already hold an eventBus reference.
  *
  * The NotificationCenter (../notification_center.js) subscribes to
- * `toast:show` on the global event bus; we re-export tiny helpers
- * that emit the same payload shape.
+ * `toast:show` on its event bus; these helpers emit the same payload shape
+ * on the bus they were given. They read no global: `NotificationCenter.mount()`
+ * hands its bus to `setToastBus()`, and `dispose()` takes it back. An embedder
+ * that wants toasts on some other bus calls `setToastBus(bus)` itself, and
+ * `setToastBus(null)` to stop.
  *
  * Usage:
  *   import { toastError, toastSuccess, toastWarn, toastInfo } from './toast.js';
- *   toastError('Save failed', 'sector_update refused: …');
+ *   toastError('Save failed', 'the server refused the change');
  *
  * The 1-arg form treats the string as the message (no title); the
- * 2-arg form is title + message.
+ * 2-arg form is title + message. With no bus (no NotificationCenter mounted
+ * yet, isolated test pages) the message goes to the console and nothing throws.
  */
 
-function _bus() {
-    return window.__ecoagent?.eventBus ?? null;
+let toastBus = null;
+
+/**
+ * Route the toast helpers to `bus` (anything with `emit(name, payload)`), or
+ * to the console with `null`. Returns the bus that was set before.
+ */
+export function setToastBus(bus) {
+    const prev = toastBus;
+    toastBus = bus && typeof bus.emit === 'function' ? bus : null;
+    return prev;
+}
+
+/** The bus the toast helpers currently emit on, or null. */
+export function getToastBus() {
+    return toastBus;
 }
 
 function _emit(severity, persistent, titleOrMsg, msg) {
-    const bus = _bus();
+    const bus = toastBus;
     const title = (msg !== undefined) ? titleOrMsg : null;
     const message = (msg !== undefined) ? msg : titleOrMsg;
     if (!bus) {

package/src/ui/components/toggle_field.js

@@ -0,0 +1,175 @@
+/**
+ * ToggleField — an on/off switch: a track and a knob drawn over a REAL
+ * checkbox, so the form, the label and assistive technology all see a native
+ * control.
+ *
+ *   const t = new ToggleField({ label: 'Autosave', onText: 'On', offText: 'Off',
+ *                               checked: true, onChange: (on) => save(on) });
+ *   host.appendChild(t.render());
+ *   t.get();            // true
+ *   t.set(false);       // no onChange: the caller already knows
+ *   t.setDisabled(true);
+ *   t.dispose();
+ *
+ * The input carries `role="switch"` and an `aria-checked` that follows it.
+ * Space toggles it (as it does any checkbox) and so does Enter, which a
+ * checkbox ignores but a switch is expected to honour. Both go through the
+ * input's own `click()`, so a disabled switch ignores them exactly as it
+ * ignores the mouse, and a toggle fires the input's `input` and `change` like
+ * any other control. The root is a `<label>`, so a click on the track, the
+ * on/off text or the label toggles it too.
+ *
+ * Markup — every class is styled by `flexdesk.css` from tokens alone:
+ *
+ *   label.twm-toggle[.twm-toggle--compact][.twm-toggle--disabled]
+ *     span.twm-toggle__control
+ *       input.twm-toggle__input[type=checkbox][role=switch]
+ *       span.twm-toggle__track > span.twm-toggle__knob
+ *     span.twm-toggle__state     (onText / offText, when either is given)
+ *     span.twm-toggle__label     (label, when given)
+ */
+export class ToggleField {
+    /**
+     * @param {object}    o
+     * @param {boolean}  [o.checked=false]
+     * @param {string?}  [o.label]      text beside the switch, and its accessible name
+     * @param {string?}  [o.ariaLabel]  accessible name when there is no visible label
+     * @param {string?}  [o.onText]     state text shown while on
+     * @param {string?}  [o.offText]    state text shown while off
+     * @param {boolean}  [o.disabled=false]
+     * @param {boolean}  [o.compact=false]  a smaller track, for dense rows
+     * @param {string?}  [o.name]       the input's name, for a surrounding form
+     * @param {string?}  [o.id]         the input's id
+     * @param {Function?}[o.onChange]   `(checked: boolean)` after a user toggle
+     */
+    constructor({
+        checked = false, label = null, ariaLabel = null, onText = null, offText = null,
+        disabled = false, compact = false, name = null, id = null, onChange = null,
+    } = {}) {
+        this._initial = !!checked;
+        this._label = label == null ? null : String(label);
+        this._ariaLabel = ariaLabel == null ? null : String(ariaLabel);
+        this._onText = onText == null ? null : String(onText);
+        this._offText = offText == null ? null : String(offText);
+        this._disabled = !!disabled;
+        this._compact = !!compact;
+        this._name = name == null ? null : String(name);
+        this._id = id == null ? null : String(id);
+        this._onChange = typeof onChange === 'function' ? onChange : null;
+
+        this.root = null;
+        this.input = null;
+        this._stateEl = null;
+        this._disposers = [];
+    }
+
+    /** Build the switch once and hand back its root; later calls return it. */
+    render() {
+        if (this.root) return this.root;
+
+        const root = document.createElement('label');
+        root.className = 'twm-toggle';
+        if (this._compact) root.classList.add('twm-toggle--compact');
+
+        const control = document.createElement('span');
+        control.className = 'twm-toggle__control';
+
+        const input = document.createElement('input');
+        input.type = 'checkbox';
+        input.className = 'twm-toggle__input';
+        input.setAttribute('role', 'switch');
+        if (this._name) input.name = this._name;
+        if (this._id) input.id = this._id;
+        if (this._ariaLabel && !this._label) input.setAttribute('aria-label', this._ariaLabel);
+        input.checked = this._initial;
+
+        const track = document.createElement('span');
+        track.className = 'twm-toggle__track';
+        track.setAttribute('aria-hidden', 'true');
+        const knob = document.createElement('span');
+        knob.className = 'twm-toggle__knob';
+        track.appendChild(knob);
+
+        control.append(input, track);
+        root.appendChild(control);
+
+        if (this._onText != null || this._offText != null) {
+            this._stateEl = document.createElement('span');
+            this._stateEl.className = 'twm-toggle__state';
+            // The switch already says on/off to a screen reader.
+            this._stateEl.setAttribute('aria-hidden', 'true');
+            root.appendChild(this._stateEl);
+        }
+        if (this._label != null) {
+            const labelEl = document.createElement('span');
+            labelEl.className = 'twm-toggle__label';
+            labelEl.textContent = this._label;
+            root.appendChild(labelEl);
+        }
+
+        this.root = root;
+        this.input = input;
+        this.setDisabled(this._disabled);
+        this._sync();
+
+        const onKeyDown = (e) => {
+            if (e.key !== ' ' && e.key !== 'Enter') return;
+            // Ours, not the browser's: Space would otherwise activate on keyup
+            // as well, and Enter would submit the surrounding form.
+            e.preventDefault();
+            if (e.repeat) return;
+            input.click();
+        };
+        const onKeyUp = (e) => { if (e.key === ' ') e.preventDefault(); };
+        const onChange = () => {
+            this._sync();
+            this._onChange?.(input.checked);
+        };
+        input.addEventListener('keydown', onKeyDown);
+        input.addEventListener('keyup', onKeyUp);
+        input.addEventListener('change', onChange);
+        this._disposers.push(
+            () => input.removeEventListener('keydown', onKeyDown),
+            () => input.removeEventListener('keyup', onKeyUp),
+            () => input.removeEventListener('change', onChange),
+        );
+        return root;
+    }
+
+    /** Whether the switch is on. */
+    get() {
+        return this.input ? this.input.checked : this._initial;
+    }
+
+    /** Turn it on or off. Does NOT call `onChange`. */
+    set(checked) {
+        if (!this.input) { this._initial = !!checked; return; }
+        this.input.checked = !!checked;
+        this._sync();
+    }
+
+    /** A disabled switch ignores clicks and keys alike. */
+    setDisabled(disabled) {
+        this._disabled = !!disabled;
+        if (!this.input) return;
+        this.input.disabled = this._disabled;
+        this.root.classList.toggle('twm-toggle--disabled', this._disabled);
+    }
+
+    dispose() {
+        for (const d of this._disposers) {
+            try { d(); } catch { /* the element is already gone */ }
+        }
+        this._disposers = [];
+        this.root?.remove();
+        this.root = null;
+        this.input = null;
+        this._stateEl = null;
+    }
+
+    _sync() {
+        const on = this.input.checked;
+        this.input.setAttribute('aria-checked', on ? 'true' : 'false');
+        if (this._stateEl) this._stateEl.textContent = (on ? this._onText : this._offText) ?? '';
+    }
+}

package/src/ui/components/tree_view.js

@@ -11,6 +11,28 @@
  * - TreeItem: Leaf item (e.g., function, series)
  */
 
+/**
+ * Labels, subtitles and badge text are TEXT, set with `textContent` after the
+ * skeleton is built (BUG-0013): a dataset called 'A <b>B</b>' is shown as
+ * those characters, and a name carrying `<img onerror>` runs nothing.
+ */
+function setText(root, selector, value) {
+    const el = root.querySelector(selector);
+    if (el) el.textContent = value == null ? '' : String(value);
+}
+
+/**
+ * An id as the value of a double-quoted attribute selector (BUG-0013).
+ * NOT `CSS.escape`: jsdom does not provide it (see modal.js). Inside a quoted
+ * attribute value `"` and `\` are escaped, and a line break, which would end
+ * the string, becomes its hex escape.
+ */
+function attrValue(value) {
+    return String(value)
+        .replace(/["\\]/g, '\\$&')
+        .replace(/[\n\r\f]/g, (c) => `\\${c.charCodeAt(0).toString(16)} `);
+}
+
 /**
  * Create a tree category (top-level collapsible section)
  * @param {Object} options - Category options
@@ -49,11 +71,12 @@ export function createTreeCategory(options) {
             <span class="twm-tree-category__icon ${iconClass}">
                 <span class="material-symbols-outlined">${icon}</span>
             </span>
-            <span class="twm-tree-category__label">${label}</span>
+            <span class="twm-tree-category__label"></span>
             <span class="twm-tree-category__count">(${count})</span>
         </div>
         <div class="twm-collapsible-content${expanded ? ' visible' : ''}" data-collapsible-content="true"></div>
     `;
+    setText(node, '.twm-tree-category__label', label);
 
     return node;
 }
@@ -97,12 +120,13 @@ export function createTreeNode(options) {
                 <span class="material-symbols-outlined">${expanded ? 'expand_more' : 'chevron_right'}</span>
             </span>
             ${iconHtml}
-            <span class="twm-tree-node__label">${label}</span>
+            <span class="twm-tree-node__label"></span>
             <span class="twm-tree-node__count">(${count})</span>
             ${actionsHtml}
         </div>
         <div class="twm-tree-node__children" style="display: ${expanded ? 'block' : 'none'};"></div>
     `;
+    setText(node, '.twm-tree-node__label', label);
 
     // Add action buttons if specified
     if (actions) {
@@ -173,25 +197,28 @@ export function createTreeItem(options) {
         : '';
 
     const subtitleHtml = subtitle
-        ? `<span class="twm-tree-item__subtitle">${subtitle}</span>`
+        ? '<span class="twm-tree-item__subtitle"></span>'
         : '';
 
     let badgeHtml = '';
     if (badge) {
         const variant = badge.variant || 'muted';
         if (badge.text) {
-            badgeHtml = `<span class="twm-tree-item__badge tree-item__badge--${variant}">${badge.text}</span>`;
+            badgeHtml = `<span class="twm-tree-item__badge twm-tree-item__badge--${variant}"></span>`;
         } else {
-            badgeHtml = `<span class="twm-tree-item__status-dot tree-item__status-dot--${variant}"></span>`;
+            badgeHtml = `<span class="twm-tree-item__status-dot twm-tree-item__status-dot--${variant}"></span>`;
         }
     }
 
     item.innerHTML = `
         ${iconHtml}
-        <span class="twm-tree-item__label">${label}</span>
+        <span class="twm-tree-item__label"></span>
         ${subtitleHtml}
         ${badgeHtml}
     `;
+    setText(item, '.twm-tree-item__label', label);
+    if (subtitle) setText(item, '.twm-tree-item__subtitle', subtitle);
+    if (badge?.text) setText(item, '.twm-tree-item__badge', badge.text);
 
     return item;
 }
@@ -257,6 +284,12 @@ export function toggleNode(nodeEl, force) {
 
 /**
  * Filter tree items by text match
+ *
+ * An item is shown when its label contains the filter. A node or a category is
+ * shown when any tree item inside it is shown, whether the item sits directly
+ * in it or deeper inside nodes. An empty filter shows everything, so clearing
+ * the filter restores the whole tree, empty nodes and categories included.
+ *
  * @param {HTMLElement} container - Tree container
  * @param {string} filter - Filter text (case-insensitive)
  * @param {Object} [options] - Filter options
@@ -266,40 +299,28 @@ export function filterTree(container, filter, options = {}) {
     const { expandMatches = true } = options;
     const normalizedFilter = (filter || '').toLowerCase().trim();
 
-    const items = container.querySelectorAll('.twm-tree-item');
-    const nodes = container.querySelectorAll('.twm-tree-node');
-    const categories = container.querySelectorAll('.twm-tree-category');
-
-    // Reset visibility
-    items.forEach((item) => {
+    const visibleItems = new Set();
+    container.querySelectorAll('.twm-tree-item').forEach((item) => {
         const label = item.querySelector('.twm-tree-item__label')?.textContent || '';
         const matches = !normalizedFilter || label.toLowerCase().includes(normalizedFilter);
         item.style.display = matches ? '' : 'none';
         item.classList.toggle('twm-filter-match', matches && !!normalizedFilter);
+        if (matches) visibleItems.add(item);
     });
 
-    // Show/hide nodes based on visible children
-    nodes.forEach((node) => {
-        const visibleChildren = node.querySelectorAll('.twm-tree-item:not([style*="display: none"])');
-        const hasVisibleChildren = visibleChildren.length > 0;
-        node.style.display = hasVisibleChildren ? '' : 'none';
+    const hasVisibleItem = (el) => !normalizedFilter
+        || [...el.querySelectorAll('.twm-tree-item')].some((item) => visibleItems.has(item));
 
-        // Auto-expand nodes with matches
-        if (expandMatches && hasVisibleChildren && normalizedFilter) {
-            toggleNode(node, true);
-        }
+    container.querySelectorAll('.twm-tree-node').forEach((node) => {
+        const visible = hasVisibleItem(node);
+        node.style.display = visible ? '' : 'none';
+        if (expandMatches && visible && normalizedFilter) toggleNode(node, true);
     });
 
-    // Show/hide categories based on visible nodes
-    categories.forEach((category) => {
-        const visibleNodes = category.querySelectorAll('.twm-tree-node:not([style*="display: none"])');
-        const hasVisibleNodes = visibleNodes.length > 0;
-        category.style.display = hasVisibleNodes ? '' : 'none';
-
-        // Auto-expand categories with matches
-        if (expandMatches && hasVisibleNodes && normalizedFilter) {
-            toggleCategory(category, true);
-        }
+    container.querySelectorAll('.twm-tree-category').forEach((category) => {
+        const visible = hasVisibleItem(category);
+        category.style.display = visible ? '' : 'none';
+        if (expandMatches && visible && normalizedFilter) toggleCategory(category, true);
     });
 }
 
@@ -320,7 +341,7 @@ export function selectItem(container, itemId, options = {}) {
     });
 
     // Find and select item
-    const item = container.querySelector(`.twm-tree-item[data-item-id="${itemId}"]`);
+    const item = container.querySelector(`.twm-tree-item[data-item-id="${attrValue(itemId)}"]`);
     if (!item) return null;
 
     item.classList.add('selected');
@@ -418,7 +439,7 @@ export class TreeView {
     }
 
     addNode(categoryId, options) {
-        const category = this.container.querySelector(`.twm-tree-category[data-category-id="${categoryId}"]`);
+        const category = this.container.querySelector(`.twm-tree-category[data-category-id="${attrValue(categoryId)}"]`);
         const content = category?.querySelector('.twm-collapsible-content');
         if (!content) return null;
 
@@ -428,7 +449,7 @@ export class TreeView {
     }
 
     addItem(nodeId, options) {
-        const node = this.container.querySelector(`.twm-tree-node[data-node-id="${nodeId}"]`);
+        const node = this.container.querySelector(`.twm-tree-node[data-node-id="${attrValue(nodeId)}"]`);
         const children = node?.querySelector('.twm-tree-node__children');
         if (!children) return null;