flexdesk 0.17.17 → 0.18.0

package/src/flow/kit/dom.js

@@ -1,27 +1,16 @@
 /**
- * THE KIT'S SMALL DOM HELPERS, AND ITS ONE POPOVER.
+ * THE KIT'S SMALL DOM HELPERS, AND ITS POPOVER.
  *
  * Everything here builds elements; nothing here reads the network, storage or
- * a consumer's vocabulary. The popover is the step picker's and *Insert a
- * value*'s shell (36 §3.5, §3.7):
- *
- *  - it is appended to FlexDesk's modal host (`modalHost()`, C25) or to
- *    `document.body` — the same question a modal and a context menu ask, so a
- *    consumer spanning two browser windows gets it in the window it set;
- *  - it is `position: fixed`, placed under its anchor (above when there is no
- *    room below) and CLAMPED to the viewport;
- *  - it is dismissed by a press outside it, by Escape, or by `close()`, and
- *    **it returns focus to its anchor** when it closes with focus inside it —
- *    a picker that drops focus on `<body>` drops it where an editor's keys
- *    never arrive — except when focus has just left it by Tab, which the
- *    pickers close it for (`'blur'`): that focus is going where it was sent;
- *  - there is ONE at a time: opening a second closes the first, and opening one
- *    from the anchor that holds the open one closes it (a toggle);
- *  - `closeFlowPopovers()` closes whichever is open, which is what an editor's
- *    `destroy()` calls so that nothing it opened outlives it.
+ * a consumer's vocabulary. The popover, the step picker's and *Insert a value*'s
+ * shell (36 §3.5, §3.7), is FlexDesk's `openPopover`, which says how it is placed,
+ * dismissed and toggled and that it returns focus to its anchor: a picker that
+ * drops focus on `<body>` drops it where an editor's keys never arrive. What the
+ * kit adds is `closeFlowPopovers()`, which closes whichever of its own is open:
+ * what an editor's `destroy()` calls so that nothing it opened outlives it.
  */
 
-import { modalHost } from '../../ui/components/modal.js';
+import { openPopover as openAnchoredPopover } from '../../ui/components/popover.js';
 
 /** The category tones (36 §3.1, §3.12); the stylesheet maps each to tokens. */
 export const TONES = Object.freeze(['violet', 'teal', 'amber', 'grey', 'blue', 'indigo']);
@@ -81,118 +70,38 @@ export function uid(stem = 'flow') {
 
 // ── the popover ──────────────────────────────────────────────────────────
 
-const EDGE = 8;
-const GAP = 4;
-let ACTIVE = null;
+/** The kit's open popovers, oldest first. */
+const OPEN = [];
 
-/** Close whichever kit popover is open. */
+/** Close every kit popover that is open. */
 export function closeFlowPopovers() {
-    ACTIVE?.close('closed');
+    OPEN[0]?.close('closed');
 }
 
-/** The open popover's element, or null — for a test. */
+/** The open popover's element (the innermost's), or null — for a test. */
 export function openFlowPopover() {
-    return ACTIVE ? ACTIVE.el : null;
+    return OPEN.length ? OPEN[OPEN.length - 1].el : null;
 }
 
 /**
- * Put `content` in a popover under `anchor`.
+ * FlexDesk's popover (`openPopover` in `ui/components/popover.js`), wearing the
+ * kit's class and remembered so that an editor can close what it opened.
  *
- * @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 (`role="dialog"`)
- * @param {string} [o.className]     an extra block class
- * @param {(reason: string) => void} [o.onClose]  after it is gone
- * @param {HTMLElement} [o.focus]    what takes focus on open
- * @returns {{el: HTMLElement, close: (reason?: string) => void, reposition: () => void, toggled: boolean}}
- *          `toggled` is true when the call only CLOSED the popover its anchor held.
+ * @param {object} o  What `openPopover` takes.
+ * @returns {{el: HTMLElement|null, close: (reason?: string) => void, reposition: () => void, toggled: boolean}}
+ *          `el` is null when nothing opened; `toggled` is true when the call only
+ *          CLOSED the popover its anchor held.
  */
-export function openPopover({ anchor, content, label, className = '', onClose = null, focus = null }) {
-    if (ACTIVE && anchor && ACTIVE.anchor === anchor) {
-        ACTIVE.close('toggle');
-        return { el: null, close() {}, reposition() {}, toggled: true };
-    }
-    ACTIVE?.close('replaced');
-
-    const pop = el('div', `twm-flow-popover${className ? ` ${className}` : ''}`);
-    pop.setAttribute('role', 'dialog');
-    pop.setAttribute('aria-label', label || '');
-    pop.tabIndex = -1;
-    pop.appendChild(content);
-    (modalHost() || document.body).appendChild(pop);
-
-    let closed = false;
-    const place = () => {
-        if (closed) return;
-        // The CLIENT width: a page scrollbar is not room to draw in.
-        const view = { w: document.documentElement.clientWidth || window.innerWidth || 1024,
-                       h: document.documentElement.clientHeight || window.innerHeight || 768 };
-        const a = anchor?.getBoundingClientRect?.() || { left: 0, top: 0, bottom: 0, right: 0 };
-        const box = pop.getBoundingClientRect();
-        // Under the anchor, its left edge on the anchor's; an anchor near the
-        // right edge gets the popover's RIGHT edge on its own instead.
-        let left = a.left;
-        if (left + box.width > view.w - EDGE && a.right - box.width >= EDGE) left = a.right - box.width;
-        let top = a.bottom + GAP;
-        if (top + box.height > view.h - EDGE && a.top - GAP - box.height >= EDGE) top = a.top - GAP - box.height;
-        left = Math.max(EDGE, Math.min(left, view.w - box.width - EDGE));
-        top = Math.max(EDGE, Math.min(top, view.h - box.height - EDGE));
-        pop.style.left = `${Math.round(left)}px`;
-        pop.style.top = `${Math.round(top)}px`;
-    };
-
-    const onPress = (ev) => {
-        if (pop.contains(ev.target)) return;
-        if (anchor && anchor.contains?.(ev.target)) return;   // the anchor's own click toggles
-        handle.close('outside');
-    };
-    const onKey = (ev) => {
-        if (ev.key !== 'Escape') return;
-        ev.preventDefault();
-        ev.stopPropagation();
-        handle.close('escape');
-    };
-    const onResize = () => place();
-    // Placed before its content is drawn — a picker fills its list after this
-    // returns — so it is placed again whenever its size changes, or it would
-    // run past the window's edge.
-    const sized = typeof ResizeObserver === 'function' ? new ResizeObserver(() => place()) : null;
-
-    const handle = {
-        el: pop,
-        anchor,
-        toggled: false,
-        reposition: place,
-        close(reason = 'closed') {
-            if (closed) return;
-            closed = true;
-            const held = pop.contains(document.activeElement) || document.activeElement === document.body;
-            document.removeEventListener('pointerdown', onPress, true);
-            document.removeEventListener('mousedown', onPress, true);
-            pop.removeEventListener('keydown', onKey);
-            window.removeEventListener('resize', onResize);
-            sized?.disconnect();
-            pop.remove();
-            if (ACTIVE === handle) ACTIVE = null;
-            // Focus that LEFT the popover (a Tab out of it) is going somewhere the
-            // reader sent it; taking it back to the anchor would fight that move.
-            if (held && reason !== 'blur' && anchor?.isConnected) anchor.focus?.({ preventScroll: true });
+export function openPopover({ className = '', onClose = null, ...rest }) {
+    const handle = openAnchoredPopover({
+        ...rest,
+        className: `twm-flow-popover${className ? ` ${className}` : ''}`,
+        onClose(reason) {
+            OPEN.splice(OPEN.indexOf(handle), 1);
             onClose?.(reason);
         },
-    };
-    ACTIVE = handle;
-    // The press that OPENED it is still being dispatched; listen from the next turn.
-    setTimeout(() => {
-        if (closed) return;
-        document.addEventListener('pointerdown', onPress, true);
-        document.addEventListener('mousedown', onPress, true);
-    }, 0);
-    pop.addEventListener('keydown', onKey);
-    window.addEventListener('resize', onResize);
-    sized?.observe(pop);
-    place();
-    (focus || pop).focus?.({ preventScroll: true });
+    });
+    if (handle.el) OPEN.push(handle);
     return handle;
 }
 

package/src/flow/kit/step_picker.js

@@ -202,7 +202,7 @@ export function openStepPicker({ anchor, entries = [], categories = [], where =
         anchor, content: root, label: title ?? say(S, 'addStep'), className: 'twm-flow-popover--picker',
         focus: search, onClose: () => settle(result),
     });
-    if (handle.toggled) settle(null);
+    if (!handle.el) settle(null);
     else filter();
     done.close = () => handle.close('closed');
     return done;

package/src/flow/kit/value_picker.js

@@ -231,7 +231,7 @@ export function openValuePicker({ anchor, groups = [], note = null, onPick = nul
         anchor, content: root, label: title ?? say(S, 'insertValue'), className: 'twm-flow-popover--values',
         focus: search, onClose: () => settle(result),
     });
-    if (handle.toggled) settle(null);
+    if (!handle.el) settle(null);
     else paint();
     done.close = () => handle.close('closed');
     return done;

package/src/flow/outline/menu.js

@@ -150,5 +150,5 @@ export function openStepMenu({ anchor, label, items, strings = null, onClose = n
         anchor, content: root, label: label || '', className: 'twm-flow-popover--menu',
         focus: enabled(root)[0] || root, onClose: () => onClose?.(),
     });
-    return { el: root, close: () => handle.close('closed'), toggled: handle.toggled };
+    return { el: handle.el ? root : null, close: () => handle.close('closed'), toggled: handle.toggled };
 }

package/src/git/diff_viewer.js

@@ -0,0 +1,212 @@
+/**
+ * diff_viewer.js — what changed, drawn three ways. Usable alone: it needs no
+ * adapter and knows nothing of git beyond reading a unified diff.
+ *
+ *     FIELDS  named values, `Priority  low → high`. The consumer parses them;
+ *             they arrive as `{ name, from, to }`
+ *     TEXT    line by line, with old and new line numbers and no diff headers,
+ *             from `before`/`after` (compared here) or else from `diff` (read)
+ *     RAW     the `diff` text as it came
+ *
+ *     const viewer = createDiffViewer(el, { before, after, diff, fields });
+ *     viewer.update({ before, after });
+ *     viewer.setView('raw');
+ *     viewer.destroy();
+ *
+ * A view is offered only when its data is there, and the buttons that switch
+ * between views only when there are two or more. Which view shows: the one set
+ * by `view`, `setView` or a click while it stays on offer, else Fields when a
+ * field changed, else Text, else Raw. `setView(null)` hands the choice back.
+ */
+
+import { computeLineDiff, parseUnifiedDiff } from './line_diff.js';
+
+const DEFAULT_LABELS = Object.freeze({
+    fields: 'Fields',
+    text: 'Text',
+    raw: 'Raw',
+    noChanges: 'No differences.',
+    noFields: 'No field changes.',
+    tooLong: 'Too long to compare here.',
+    gap: (hidden) => `${hidden} unchanged line${hidden === 1 ? '' : 's'}`,
+});
+
+function el(tag, className, text) {
+    const n = document.createElement(tag);
+    if (className) n.className = className;
+    if (text !== undefined) n.textContent = text;
+    return n;
+}
+
+/** A field's value as drawn: an absent or empty one reads as a dash. */
+const shownField = (v) => {
+    const s = v === null || v === undefined ? '' : String(v);
+    return s === '' ? '—' : s;
+};
+
+function lineRow(line, labels) {
+    const row = el('div', `twm-diff__line twm-diff__line--${line.kind}`);
+    if (line.kind === 'gap' || line.kind === 'hunk' || line.kind === 'meta' || line.kind === 'file') {
+        row.textContent = line.kind === 'gap' ? labels.gap(line.hidden) : line.text;
+        return row;
+    }
+    row.append(
+        el('span', 'twm-diff__n', line.oldLine === null ? '' : String(line.oldLine)),
+        el('span', 'twm-diff__n', line.newLine === null ? '' : String(line.newLine)),
+        el('span', 'twm-diff__sign', line.kind === 'add' ? '+' : line.kind === 'del' ? '-' : ''),
+        el('span', 'twm-diff__text', line.text),
+    );
+    return row;
+}
+
+/**
+ * @param {HTMLElement} host
+ * @param {Object} [options]
+ * @param {string} [options.before] - The old text. With `after`, drawn by comparing the two.
+ * @param {string} [options.after] - The new text.
+ * @param {string} [options.diff] - A unified diff: the Raw view, and the Text view when there is no `before`/`after`.
+ * @param {Array<{name: string, from?: *, to?: *}>} [options.fields] - The Fields view's rows.
+ * @param {number} [options.beforeStart=1] - The line number of `before`'s first line.
+ * @param {number} [options.afterStart=1] - The line number of `after`'s first line.
+ * @param {number} [options.context=3] - Unchanged lines kept around each change.
+ * @param {number} [options.maxLines] - Past this many differing lines a side, the texts are not compared.
+ * @param {'fields'|'text'|'raw'} [options.view] - The view to show while it is on offer.
+ * @param {Object} [options.labels] - Words to replace: `fields`, `text`, `raw`, `noChanges`, `noFields`, `tooLong`, `gap(hidden)`.
+ * @param {(view: string) => void} [options.onViewChange] - Told when a click changes the view.
+ * @returns {{ el: HTMLElement, update(data: Object): void, setView(view: string|null): void,
+ *   view(): string|null, showMessage(text: string): void, destroy(): void }}
+ */
+export function createDiffViewer(host, options = {}) {
+    const { context = 3, maxLines, onViewChange = null } = options;
+    const labels = { ...DEFAULT_LABELS, ...options.labels };
+
+    const root = el('div', 'twm-diff');
+    const switcher = el('div', 'twm-diff__views');
+    switcher.setAttribute('role', 'group');
+    switcher.setAttribute('aria-label', 'Diff view');
+    const body = el('div', 'twm-diff__body');
+    root.append(switcher, body);
+    host.appendChild(root);
+
+    let data = {};
+    let chosen = options.view ?? null;
+    let textLines;     // this data's Text view; undefined until first drawn
+    let current = null;
+
+    const hasPair = () => typeof data.before === 'string' || typeof data.after === 'string';
+
+    const linesOfText = () => {
+        if (textLines !== undefined) return textLines;
+        textLines = hasPair()
+            ? computeLineDiff(data.before, data.after, {
+                context,
+                ...(maxLines === undefined ? {} : { maxLines }),
+                beforeStart: data.beforeStart ?? 1,
+                afterStart: data.afterStart ?? 1,
+            })
+            : parseUnifiedDiff(data.diff);
+        return textLines;
+    };
+
+    const offered = () => {
+        const out = [];
+        if (Array.isArray(data.fields)) out.push('fields');
+        if (hasPair() || (typeof data.diff === 'string' && linesOfText().length > 0)) out.push('text');
+        if (typeof data.diff === 'string') out.push('raw');
+        return out;
+    };
+
+    const pick = (views) => {
+        if (chosen && views.includes(chosen)) return chosen;
+        if (views.includes('fields') && data.fields.length > 0) return 'fields';
+        if (views.includes('text')) return 'text';
+        return views[0] ?? null;
+    };
+
+    const message = (text) => {
+        body.replaceChildren(el('div', 'twm-diff__message', text));
+    };
+
+    const drawFields = () => {
+        if (data.fields.length === 0) { message(labels.noFields); return; }
+        const grid = el('div', 'twm-diff__fields');
+        for (const field of data.fields) {
+            const values = el('span', 'twm-diff__field-values');
+            const arrow = el('span', 'material-symbols-outlined twm-diff__field-arrow', 'arrow_forward');
+            arrow.setAttribute('aria-hidden', 'true');
+            values.append(
+                el('span', 'twm-diff__field-from', shownField(field.from)),
+                arrow,
+                el('span', 'twm-diff__field-to', shownField(field.to)),
+            );
+            grid.append(el('span', 'twm-diff__field-name', String(field.name)), values);
+        }
+        body.replaceChildren(grid);
+    };
+
+    const drawText = () => {
+        const lines = linesOfText();
+        if (lines === null) {
+            message(typeof data.diff === 'string' ? `${labels.tooLong} See ${labels.raw}.` : labels.tooLong);
+            return;
+        }
+        if (lines.length === 0) { message(labels.noChanges); return; }
+        const list = el('div', 'twm-diff__lines');
+        list.append(...lines.map((line) => lineRow(line, labels)));
+        body.replaceChildren(list);
+    };
+
+    const drawRaw = () => {
+        if (data.diff === '') { message(labels.noChanges); return; }
+        body.replaceChildren(el('pre', 'twm-diff__raw', data.diff));
+    };
+
+    const draw = () => {
+        const views = offered();
+        current = pick(views);
+        switcher.replaceChildren(...(views.length > 1 ? views.map((v) => {
+            const b = el('button', 'twm-diff__view', labels[v]);
+            b.type = 'button';
+            b.setAttribute('aria-pressed', String(v === current));
+            b.addEventListener('click', () => {
+                chosen = v;
+                draw();
+                onViewChange?.(v);
+            });
+            return b;
+        }) : []));
+        switcher.hidden = views.length <= 1;
+        if (current === 'fields') drawFields();
+        else if (current === 'text') drawText();
+        else if (current === 'raw') drawRaw();
+        else message(labels.noChanges);
+    };
+
+    const update = (next) => {
+        data = next ?? {};
+        textLines = undefined;
+        draw();
+    };
+
+    update(options);
+
+    return {
+        el: root,
+        update,
+        setView(view) {
+            chosen = view;
+            draw();
+        },
+        view: () => current,
+        /** Words in place of the diff, while it loads or when it could not be read. The next update replaces them. */
+        showMessage(text) {
+            switcher.replaceChildren();
+            switcher.hidden = true;
+            current = null;
+            message(text);
+        },
+        destroy() {
+            root.remove();
+        },
+    };
+}

package/src/git/diff_window.js

@@ -0,0 +1,51 @@
+/**
+ * diff_window.js — a diff in a window of its own: FlexDesk's modal around a
+ * createDiffViewer, showing "Loading…" until the data arrives.
+ */
+
+import { openModal } from '../ui/components/modal.js';
+import { createDiffViewer } from './diff_viewer.js';
+
+/**
+ * @param {Object} options
+ * @param {string} options.title
+ * @param {() => Promise<Object>|Object} options.load - Answers what `createDiffViewer`'s `update` takes, or
+ *   `{ ok: false, error }`; a throw is shown the same way.
+ * @param {string} [options.icon='difference']
+ * @param {number} [options.width=880]
+ * @param {number} [options.height=600]
+ * @param {Object} [options.labels] - As for createDiffViewer.
+ * @returns {Promise<null>} Settles when the window closes.
+ */
+export function openDiffWindow({ title, load, icon = 'difference', width = 880, height = 600, labels } = {}) {
+    const content = document.createElement('div');
+    content.className = 'twm-diff-window';
+    const viewer = createDiffViewer(content, { labels });
+    viewer.showMessage('Loading…');
+    const closed = openModal({ title, icon, content, width, height, maximizable: true });
+    Promise.resolve()
+        .then(load)
+        .then((data) => {
+            if (data?.ok === false) viewer.showMessage(data.error || 'The diff could not be read.');
+            else viewer.update(data);
+        })
+        .catch((e) => viewer.showMessage(e?.message || String(e)));
+    return closed;
+}
+
+/**
+ * The diff of one file, from an adapter's `diffFile`, in a window.
+ * @param {Object} options
+ * @param {Object} options.adapter - A git adapter with `diffFile` (docs/components/git.md).
+ * @param {string} options.path
+ * @param {string} [options.status]
+ * @param {string} [options.renamedFrom] - The path it had before, for a rename.
+ * @param {string} [options.ref] - A commit: the file's change in that commit, not the uncommitted one.
+ * @returns {Promise<null>}
+ */
+export function openGitDiffWindow({ adapter, path, status, renamedFrom, ref }) {
+    return openDiffWindow({
+        title: renamedFrom ? `${renamedFrom} → ${path}` : path,
+        load: () => adapter.diffFile({ path, status, ...(renamedFrom ? { renamedFrom } : {}), ...(ref ? { ref } : {}) }),
+    });
+}