flexdesk 0.16.1 → 0.17.0

package/src/ui/components/section_stack.js

@@ -0,0 +1,298 @@
+/**
+ * ══ A STACK OF COLLAPSIBLE SECTIONS ══════════════════════════════════════
+ *
+ * Inspector-style panel content: titled sections, one above the other, each
+ * opened and closed from its header (FlexDesk STORY-0036). Until this, only a
+ * tree's categories could collapse, and every embedder that wanted a panel of
+ * "Notes / Assistant / Parameters" built the headers, the arrows and the
+ * remembering itself.
+ *
+ *     const stack = createSectionStack(panel, {
+ *         sections: [
+ *             { id: 'notes', title: 'Notes', content: notesEl },
+ *             { id: 'chat',  title: 'Assistant', fill: true,
+ *               actions: [{ id: 'clear', icon: 'delete', label: 'Clear', onClick: clear }] },
+ *             { id: 'params', title: 'Parameters', defaultExpanded: false },
+ *         ],
+ *         key: 'inspector.sections',
+ *         stateStore: { read: (key) => saved[key], write: (key, map) => { saved[key] = map; } },
+ *     });
+ *     stack.body('chat').appendChild(chatEl);
+ *     const off = stack.on('toggled', ({ id, expanded }) => …);
+ *
+ * A SECTION is `{ id, title, icon?, content?, actions?, defaultExpanded?, fill? }`.
+ * `content` is a Node put into the section's body at mount; `body(id)` hands
+ * the same element over for anything mounted later. `defaultExpanded` is true
+ * unless it says otherwise.
+ *
+ * THE HEADER TOGGLES; ITS ACTIONS DO NOT. A click anywhere on the header opens
+ * or closes the section and turns its arrow — except on one of its `actions`
+ * (`{ id?, icon, label, title?, onClick(sectionId, event) }`), which runs its
+ * own `onClick` and leaves the section as it was.
+ *
+ * A FILL SECTION (`fill: true`) takes the height the others leave, and its
+ * body scrolls inside it (`min-height: 0`), so a long conversation scrolls in
+ * its section instead of growing the panel past the window. Give the stack's
+ * container a height — it is `height: 100%` of it.
+ *
+ * REMEMBERING is the embedder's: `stateStore` is `{ read(key), write(key, map) }`
+ * and `map` is `{ [sectionId]: expanded }`, written whenever a section opens or
+ * closes. `read` may answer a promise; until it does, sections show their
+ * `defaultExpanded`, and a section somebody toggled meanwhile keeps their
+ * choice. Such a toggle is written once the read has settled, merged over
+ * the stored map, so the defaults on screen never overwrite it. A store that throws, rejects, or answers something that is not a map
+ * leaves every section on its `defaultExpanded` — remembering is a convenience,
+ * never a reason for a panel not to draw. `ready` resolves once the read has
+ * been applied (at once without a store).
+ *
+ * `setVisible(id, false)` takes a section off the stack without forgetting it:
+ * `setVisible(id, true)` brings it back open or closed exactly as it was.
+ *
+ * The `toggled` event carries `{ id, expanded, source }`, `source` being
+ * `'user'` (a header click), `'api'` (expand / collapse / toggle) or
+ * `'restore'` (a stored state that arrived after mount). It fires only on a
+ * change. `on()` answers the function that stops listening.
+ *
+ * `dispose()` removes the one listener the stack adds and every node it made;
+ * `content` the embedder handed in goes with its section.
+ *
+ * Styled by `.twm-collapsible-*` (the tree's primitive) plus `.twm-section-stack*`.
+ */
+
+/**
+ * @param {HTMLElement} container
+ * @param {object}  opts
+ * @param {Array}   opts.sections      `{ id, title, icon?, content?, actions?, defaultExpanded?, fill? }`
+ * @param {object} [opts.stateStore]   `{ read(key): map|Promise<map>, write(key, map) }`
+ * @param {string} [opts.key]          the key the expanded states live under; required with a store
+ */
+export function createSectionStack(container, { sections = [], stateStore = null, key = null } = {}) {
+    if (stateStore && !key) throw new Error('createSectionStack: a stateStore needs a { key }');
+    const doc = container.ownerDocument;
+
+    const root = doc.createElement('div');
+    root.className = 'twm-section-stack';
+
+    /** id -> { def, box, toggle, arrow, body, expanded, visible, touched } */
+    const byId = new Map();
+    /** action button -> { sectionId, action } */
+    const actionOf = new Map();
+    /** header -> section id */
+    const headerOf = new Map();
+    const listeners = new Set();
+    let disposed = false;
+    // While a promised read is out, the sections nobody touched still show
+    // their defaults, not what the store holds: writing them then would
+    // overwrite the stored states with defaults. A toggle meanwhile only marks
+    // the map as owed; it is written once the read has settled.
+    let readPending = false;
+    let writeOwed = false;
+
+    for (const def of sections) {
+        if (!def || def.id == null || byId.has(def.id)) {
+            throw new Error(`createSectionStack: every section needs a unique id (got ${def?.id})`);
+        }
+        const expanded = def.defaultExpanded !== false;
+
+        const box = doc.createElement('section');
+        box.className = 'twm-collapsible-box twm-section-stack__section'
+            + (def.fill ? ' twm-section-stack__section--fill' : '');
+
+        const header = doc.createElement('div');
+        header.className = 'twm-collapsible-header twm-section-stack__header';
+
+        const toggle = doc.createElement('button');
+        toggle.type = 'button';
+        toggle.className = 'twm-section-stack__toggle';
+        const arrow = doc.createElement('span');
+        arrow.className = 'twm-collapsible-arrow material-symbols-outlined';
+        arrow.setAttribute('aria-hidden', 'true');
+        arrow.textContent = 'expand_more';
+        toggle.appendChild(arrow);
+        if (def.icon) {
+            const icon = doc.createElement('span');
+            icon.className = 'twm-section-stack__icon material-symbols-outlined';
+            icon.setAttribute('aria-hidden', 'true');
+            icon.textContent = def.icon;
+            toggle.appendChild(icon);
+        }
+        const title = doc.createElement('span');
+        title.className = 'twm-section-stack__title';
+        title.textContent = def.title ?? String(def.id);
+        toggle.appendChild(title);
+        header.appendChild(toggle);
+
+        if (Array.isArray(def.actions) && def.actions.length) {
+            const bar = doc.createElement('div');
+            bar.className = 'twm-section-stack__actions';
+            for (const action of def.actions) {
+                const btn = doc.createElement('button');
+                btn.type = 'button';
+                btn.className = 'twm-section-stack__action';
+                if (action.label) btn.setAttribute('aria-label', action.label);
+                if (action.title ?? action.label) btn.setAttribute('title', action.title ?? action.label);
+                const glyph = doc.createElement('span');
+                glyph.className = 'material-symbols-outlined';
+                glyph.setAttribute('aria-hidden', 'true');
+                glyph.textContent = action.icon ?? '';
+                btn.appendChild(glyph);
+                bar.appendChild(btn);
+                actionOf.set(btn, { sectionId: def.id, action });
+            }
+            header.appendChild(bar);
+        }
+
+        const body = doc.createElement('div');
+        body.className = 'twm-collapsible-content twm-section-stack__body';
+        if (def.content) body.appendChild(def.content);
+
+        box.append(header, body);
+        root.appendChild(box);
+        headerOf.set(header, def.id);
+        const entry = { def, box, toggle, arrow, body, expanded, visible: true, touched: false };
+        byId.set(def.id, entry);
+        paint(entry);
+    }
+
+    function paint(entry) {
+        entry.box.classList.toggle('twm-section-stack__section--expanded', entry.expanded);
+        entry.body.classList.toggle('visible', entry.expanded);
+        entry.arrow.classList.toggle('collapsed', !entry.expanded);
+        entry.toggle.setAttribute('aria-expanded', String(entry.expanded));
+        entry.box.hidden = !entry.visible;
+    }
+
+    function emit(detail) {
+        for (const fn of [...listeners]) {
+            try { fn(detail); } catch (err) { console.error('[section-stack] toggled listener failed', err); }
+        }
+    }
+
+    function persist() {
+        if (!stateStore?.write) return;
+        if (readPending) { writeOwed = true; return; }
+        const map = {};
+        for (const [id, entry] of byId) map[id] = entry.expanded;
+        write(map);
+    }
+
+    function write(map) {
+        try {
+            const pending = stateStore.write(key, map);
+            pending?.catch?.(() => { /* storage refused: not ours to fix */ });
+        } catch { /* storage refused: not ours to fix */ }
+    }
+
+    /** Set one section's state; true when it changed. */
+    function set(id, expanded, source) {
+        const entry = byId.get(id);
+        if (disposed || !entry || entry.expanded === expanded) return false;
+        entry.expanded = expanded;
+        if (source !== 'restore') entry.touched = true;
+        paint(entry);
+        if (source !== 'restore') persist();
+        emit({ id, expanded, source });
+        return true;
+    }
+
+    const isMap = (saved) => !!saved && typeof saved === 'object' && !Array.isArray(saved);
+
+    function restore(saved, source) {
+        if (disposed || !isMap(saved)) return;
+        for (const [id, entry] of byId) {
+            if (entry.touched || typeof saved[id] !== 'boolean') continue;
+            if (source === 'restore') set(id, saved[id], 'restore');
+            else { entry.expanded = saved[id]; paint(entry); }
+        }
+    }
+
+    /** A promised read has settled (`saved` is null when it rejected). */
+    function settle(saved) {
+        restore(saved, 'restore');
+        readPending = false;
+        if (!writeOwed) return;
+        writeOwed = false;
+        // The touched sections over what the store holds — also after a
+        // dispose, which must not lose a choice made before the read answered.
+        const map = {};
+        for (const [id, entry] of byId) {
+            map[id] = !entry.touched && isMap(saved) && typeof saved[id] === 'boolean'
+                ? saved[id] : entry.expanded;
+        }
+        write(map);
+    }
+
+    function onClick(event) {
+        const target = event.target;
+        const btn = target?.closest?.('.twm-section-stack__action');
+        if (btn && actionOf.has(btn)) {
+            const { sectionId, action } = actionOf.get(btn);
+            event.stopPropagation();
+            try { action.onClick?.(sectionId, event); } catch (err) {
+                console.error(`[section-stack] action on "${sectionId}" failed`, err);
+            }
+            return;
+        }
+        const header = target?.closest?.('.twm-section-stack__header');
+        if (!header || !headerOf.has(header)) return;
+        const id = headerOf.get(header);
+        set(id, !byId.get(id).expanded, 'user');
+    }
+    root.addEventListener('click', onClick);
+
+    // Synchronous stored state is applied before the stack is on screen, so it
+    // never flashes the defaults; a promise is applied when it answers.
+    let ready = Promise.resolve();
+    if (stateStore?.read) {
+        let saved = null;
+        try { saved = stateStore.read(key); } catch { saved = null; }
+        if (saved && typeof saved.then === 'function') {
+            readPending = true;
+            ready = Promise.resolve(saved)
+                .then((value) => settle(value), () => settle(null));
+        } else {
+            restore(saved, 'mount');
+        }
+    }
+
+    container.appendChild(root);
+
+    const need = (id) => {
+        if (!byId.has(id)) throw new Error(`createSectionStack: no section "${id}"`);
+        return byId.get(id);
+    };
+
+    return {
+        root,
+        ready,
+        /** The section's body element, for content mounted after the stack. */
+        body: (id) => need(id).body,
+        expand(id) { need(id); set(id, true, 'api'); },
+        collapse(id) { need(id); set(id, false, 'api'); },
+        toggle(id) { set(id, !need(id).expanded, 'api'); },
+        isExpanded: (id) => need(id).expanded,
+        /** Off the stack, or back on it — its expanded state is kept either way. */
+        setVisible(id, visible) {
+            const entry = need(id);
+            entry.visible = !!visible;
+            paint(entry);
+        },
+        isVisible: (id) => need(id).visible,
+        /** `on('toggled', fn)` — answers the function that stops listening. */
+        on(event, fn) {
+            if (event !== 'toggled') throw new Error(`createSectionStack: no "${event}" event`);
+            if (disposed) return () => {};
+            listeners.add(fn);
+            return () => listeners.delete(fn);
+        },
+        dispose() {
+            if (disposed) return;
+            disposed = true;
+            root.removeEventListener('click', onClick);
+            listeners.clear();
+            actionOf.clear();
+            headerOf.clear();
+            root.remove();
+        },
+    };
+}

package/src/ui/components/series.js

@@ -0,0 +1,173 @@
+/**
+ * series.js — STORY-0089. What a FILL HANDLE writes: `detectSeries` reads the
+ * block a fill starts from, and `projectSeries` continues it. Pure functions,
+ * no DOM, so the rules are tested on their own (tests/series.test.mjs) and a
+ * consumer that builds its own grid fills the way DataTable does.
+ *
+ * The rules, as a spreadsheet has them:
+ *   - one value                          -> repeat it
+ *   - two or more numbers a constant
+ *     step apart                         -> continue the arithmetic series
+ *   - two or more dates (`YYYY-MM-DD`
+ *     or `Date`) a constant number of
+ *     days apart                         -> continue them that many days apart
+ *   - two or more texts with one shared
+ *     prefix and suffix around a number
+ *     a constant step apart ("Item 1")   -> continue the number, zero-padded
+ *                                           as the first is
+ *   - anything else (equal values
+ *     included)                          -> repeat the block, in a cycle
+ *   - `forceCopy` (Ctrl held)            -> repeat the block, in a cycle
+ *
+ * `values` is the seed IN FILL ORDER: a fill up or left hands the block in
+ * reverse, so the value next to the gap comes last and the series runs away
+ * from the block.
+ */
+
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+const TRAILING_NUMBER = /^(.*?)(\d+)(\D*)$/;
+const NUMERIC_TEXT = /^[-+]?(\d+\.?\d*|\.\d+)$/;
+const DAY_MS = 86400000;
+
+const isBlank = (v) => v === null || v === undefined || v === '';
+
+/**
+ * What the seed is: `{kind, step}` with `kind` one of 'copy', 'number',
+ * 'date' (step in days), 'text-number' (also `prefix`, `suffix`, `pad`) or
+ * 'cycle' — or null for an empty seed or one of blanks only.
+ *
+ * @param {any[]} values
+ * @returns {{kind: string, step: number, prefix?: string, suffix?: string, pad?: number}|null}
+ */
+export function detectSeries(values) {
+    if (!Array.isArray(values) || values.length === 0) return null;
+    if (values.every(isBlank)) return null;
+    if (values.length === 1) return { kind: 'copy', step: 0 };
+
+    const numbers = values.map(toNumber);
+    if (numbers.every((n) => n !== null)) {
+        const step = numbers[1] - numbers[0];
+        const constant = numbers.every((n, i) => i === 0 || nearlyEqual(n - numbers[i - 1], step));
+        if (constant && step !== 0) return { kind: 'number', step };
+        if (constant) return { kind: 'copy', step: 0 };
+        return { kind: 'cycle', step: 0 };
+    }
+
+    const days = values.map(toDayMs);
+    if (days.every((d) => d !== null)) {
+        const step = Math.round((days[1] - days[0]) / DAY_MS);
+        const constant = days.every((d, i) => i === 0 || Math.round((d - days[i - 1]) / DAY_MS) === step);
+        if (constant && step !== 0) return { kind: 'date', step };
+        if (constant) return { kind: 'copy', step: 0 };
+        return { kind: 'cycle', step: 0 };
+    }
+
+    // "Item 1", "Item 2": one prefix and suffix around a number.
+    const parts = values.map((v) => (typeof v === 'string' ? TRAILING_NUMBER.exec(v) : null));
+    if (parts.every(Boolean)) {
+        const prefix = parts[0][1];
+        const suffix = parts[0][3];
+        if (parts.every((p) => p[1] === prefix && p[3] === suffix)) {
+            const nums = parts.map((p) => Number(p[2]));
+            const step = nums[1] - nums[0];
+            const constant = nums.every((n, i) => i === 0 || n - nums[i - 1] === step);
+            if (constant && step !== 0) {
+                return { kind: 'text-number', step, prefix, suffix, pad: parts[0][2].length };
+            }
+        }
+    }
+
+    return { kind: 'cycle', step: 0 };
+}
+
+/**
+ * The `count` values a fill writes after `values` (the seed, in fill order).
+ * A series keeps its seed's type: number seeds give numbers, text seeds text
+ * (with the seed's decimals), `Date` seeds `Date`s and `YYYY-MM-DD` seeds
+ * `YYYY-MM-DD`. A repeat hands back the seed's own values.
+ *
+ * @param {any[]} values
+ * @param {number} count
+ * @param {{forceCopy?: boolean}} [options]  `forceCopy`: repeat the block
+ *   even when it is a series (Ctrl held).
+ * @returns {any[]}
+ */
+export function projectSeries(values, count, { forceCopy = false } = {}) {
+    const out = [];
+    const n = Math.max(0, Math.floor(Number(count) || 0));
+    if (!Array.isArray(values) || values.length === 0 || n === 0) return out;
+    const series = forceCopy ? null : detectSeries(values);
+    const last = values[values.length - 1];
+    if (series?.kind === 'number') {
+        const base = toNumber(last);
+        const decimals = Math.min(15, Math.max(...values.map(decimalsOf)));
+        const allNumbers = values.every((v) => typeof v === 'number');
+        for (let i = 1; i <= n; i++) {
+            const next = base + series.step * i;
+            out.push(allNumbers ? Number(next.toFixed(decimals)) : next.toFixed(decimals));
+        }
+        return out;
+    }
+    if (series?.kind === 'date') {
+        // Calendar days, not 24-hour blocks: a `Date` keeps its wall-clock
+        // time across a daylight-saving change (local calendar), and a
+        // YYYY-MM-DD text stays on the UTC calendar it was parsed on.
+        const asDate = last instanceof Date;
+        for (let i = 1; i <= n; i++) {
+            if (asDate) {
+                const next = new Date(last.getTime());
+                next.setDate(next.getDate() + series.step * i);
+                out.push(next);
+            } else {
+                const next = new Date(toDayMs(last));
+                next.setUTCDate(next.getUTCDate() + series.step * i);
+                out.push(next.toISOString().slice(0, 10));
+            }
+        }
+        return out;
+    }
+    if (series?.kind === 'text-number') {
+        const base = Number(TRAILING_NUMBER.exec(last)[2]);
+        for (let i = 1; i <= n; i++) {
+            const next = base + series.step * i;
+            const digits = String(Math.abs(next)).padStart(series.pad, '0');
+            out.push(`${series.prefix}${next < 0 ? '-' : ''}${digits}${series.suffix}`);
+        }
+        return out;
+    }
+    for (let i = 0; i < n; i++) out.push(values[i % values.length]);
+    return out;
+}
+
+/** A number, or a text that is exactly one; never NaN. */
+function toNumber(value) {
+    if (typeof value === 'number') return Number.isFinite(value) ? value : null;
+    if (typeof value !== 'string') return null;
+    const text = value.trim();
+    return NUMERIC_TEXT.test(text) ? Number(text) : null;
+}
+
+/** A `Date`, or a `YYYY-MM-DD` text (read as UTC midnight), in ms. */
+function toDayMs(value) {
+    if (value instanceof Date) {
+        const t = value.getTime();
+        return Number.isNaN(t) ? null : t;
+    }
+    if (typeof value !== 'string' || !ISO_DATE.test(value.trim())) return null;
+    const text = value.trim();
+    const t = new Date(`${text}T00:00:00Z`).getTime();
+    // 2026-02-30 parses to March 2nd in some engines: not a date.
+    if (Number.isNaN(t) || new Date(t).toISOString().slice(0, 10) !== text) return null;
+    return t;
+}
+
+/** The decimals a seed value is written with ("2.50" → 2, 0.1 → 1). */
+function decimalsOf(value) {
+    const text = typeof value === 'number' ? String(value) : String(value).trim();
+    if (/e/i.test(text)) return 15;
+    return (text.split('.')[1] || '').length;
+}
+
+function nearlyEqual(a, b) {
+    return Math.abs(a - b) < 1e-9;
+}