@peter.prib/renderengine 0.12.0 → 0.14.0

package/src/charting/archimate/deleteFromModel.js

@@ -0,0 +1,57 @@
+import { FormDialog } from '../FormDialog.js';
+import { typeTitle } from './archimateNames.js';
+
+/** At most this many views or relationships are named; the rest are counted. */
+const LISTED = 10;
+
+/**
+ * What deleting elements from the model takes with it, in words, for the
+ * confirmation: the views they are on (and how many boxes), and the
+ * relationships that go too (ArchimateModel#usage).
+ * @param {ArchimateModel} model
+ * @param {Array<string>} elementIds
+ * @returns {string}
+ */
+export function deleteFromModelMessage(model, elementIds) {
+    const elements = elementIds.map(id => model.getElement(id)).filter(Boolean);
+    const name = (el) => `"${el.name || el.id}"`;
+    const { views, relationships } = model.usage(elementIds);
+    const list = (items) => [...items.slice(0, LISTED).map(s => `  • ${s}`), ...(items.length > LISTED ? [`  • and ${items.length - LISTED} more`] : [])];
+    const end = (id) => { const c = model.getElement(id) ?? model.getRelationship(id); return c ? `${c.name || typeTitle(c.type ?? c.kind ?? '') || c.id}` : id; };
+    const lines = [
+        elements.length === 1 ? `${name(elements[0])} (${typeTitle(elements[0].type ?? '')}) goes from the model.` : `These ${elements.length} elements go from the model: ${elements.map(name).join(', ')}.`,
+        '',
+        views.length
+            ? `Used in ${views.length} view${views.length === 1 ? '' : 's'}, where ${elements.length === 1 ? 'its' : 'their'} boxes go:`
+            : 'Used in no view.',
+        ...list(views.map(({ view, boxes }) => `${view.name || view.id}${boxes > 1 ? ` (${boxes} boxes)` : ''}`)),
+        '',
+        relationships.length
+            ? `${relationships.length} relationship${relationships.length === 1 ? '' : 's'} go${relationships.length === 1 ? 'es' : ''} too:`
+            : 'No relationships.',
+        ...list(relationships.map(r => `${end(r.source)} → ${end(r.target)} (${typeTitle(r.kind ?? r.type ?? '') || 'relationship'}${r.name ? `: ${r.name}` : ''})`)),
+        '',
+        'Undo puts them all back.',
+    ];
+    return lines.join('\n');
+}
+
+/**
+ * Ask before deleting elements from the model: a dialog saying where they are
+ * used and what goes with them; **Delete from model** runs `onConfirm()`.
+ * @returns {FormDialog|null} null when none of the ids is an element
+ */
+export function askDeleteFromModel(model, elementIds, { onConfirm, document: doc = globalThis.document } = {}) {
+    const ids = elementIds.filter(id => model.getElement(id));
+    if (!ids.length) return null;
+    const dialog = new FormDialog({
+        title: ids.length === 1 ? 'Delete from model' : `Delete ${ids.length} elements from model`,
+        description: deleteFromModelMessage(model, ids),
+        fields: [],
+        submitLabel: 'Delete from model',
+        document: doc,
+        onApply: () => onConfirm(ids),
+    });
+    dialog.open();
+    return dialog;
+}

package/src/charting/archimate/elementMenuItems.js

@@ -11,9 +11,10 @@
  * @param {(element) => void} host.editProperties
  * @param {(view, instanceId) => void} host.showIn - Open `view` with that box selected
  * @param {(element) => void} [host.addToView] - Show it on `view` (offered when it is not there)
+ * @param {(element) => void} [host.deleteFromModel] - Delete it from the model, after saying where it is used
  * @returns {Array<Object>} menu items
  */
-export function elementMenuItems(element, { model, view = null, editProperties, showIn, addToView = null }) {
+export function elementMenuItems(element, { model, view = null, editProperties, showIn, addToView = null, deleteFromModel = null }) {
     const placed = model.views()
         .map(v => ({ view: v, instance: v.elementInstancesFor?.(element.id)?.[0] }))
         .filter(({ instance }) => instance);
@@ -28,5 +29,6 @@ export function elementMenuItems(element, { model, view = null, editProperties,
             : { label: 'Show in View (on none)', disabled: true, action: () => {} },
         ...(addToView && view && !onThisView ? [{ label: `Add to "${view.name || 'this view'}"`, action: () => addToView(element) }] : []),
         { label: 'Generate View For This', action: () => model.generateView([element.id]) },
+        ...(deleteFromModel ? [{ separator: true }, { label: '🗑 Delete from model…', danger: true, action: () => deleteFromModel(element) }] : []),
     ];
 }

package/src/charting/archimate/heatMaps.js

@@ -0,0 +1,169 @@
+import { compileFormula } from '../../kernelExpr.js';
+
+/**
+ * Heat maps an ArchiMate view can be coloured by beyond its elements' own
+ * fields (ArchimateCanvasEditor#colourKeys): what change a deliverable or work
+ * package makes to each element, and a formula over the elements' numeric
+ * properties. Pure: no editor, no DOM.
+ */
+
+/** The change heat map's colours. */
+export const CHANGE_COLOURS = Object.freeze({ Create: '#FDD835', Update: '#1E88E5', Delete: '#D81B60' });
+
+/** Element types that make changes: their relationships to an element say what they do to it. */
+export const CHANGE_MAKERS = Object.freeze(['deliverable', 'work-package']);
+
+/** The words for each change, synonyms included (verbs as base forms; their -s, -ed, -ing forms match too). */
+export const CHANGE_WORDS = Object.freeze({
+    Delete: ['delete', 'remove', 'retire', 'decommission', 'drop', 'sunset', 'terminate', 'eliminate', 'discontinue', 'deprecate', 'withdraw', 'phase out', 'shut down', 'switch off'],
+    Create: ['create', 'add', 'new', 'introduce', 'build', 'built', 'establish', 'implement', 'insert', 'provision', 'set up', 'launch', 'develop', 'onboard'],
+    Update: ['update', 'change', 'modify', 'amend', 'enhance', 'upgrade', 'improve', 'revise', 'extend', 'migrate', 'refactor', 'replace', 'rework', 'adapt', 'alter', 'patch'],
+});
+
+/** Which change wins when an element is given more than one: the one with most consequence. */
+const PRECEDENCE = ['Delete', 'Create', 'Update'];
+
+const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/**
+ * A word and its inflections: retire → retires, retired, retiring; drop →
+ * dropped, dropping; modify → modifies, modified, modifying.
+ */
+function forms(word) {
+    const [verb, ...rest] = word.split(' ');
+    const tail = rest.length ? `\\s+${rest.map(escape).join('\\s+')}` : '';
+    const stem = verb.endsWith('e') ? verb.slice(0, -1) : verb;
+    const doubled = /[^aeiou][aeiou][bdgmnpt]$/.test(verb) ? `|${escape(verb)}${verb.at(-1)}(?:ed|ing)` : '';
+    const y = /[^aeiou]y$/.test(verb) ? `|${escape(verb.slice(0, -1))}i(?:es|ed)` : '';
+    return `(?:${escape(verb)}(?:s|es|d|ed)?|${escape(stem)}(?:ed|ing|es)${doubled}${y})${tail}`;
+}
+
+const PATTERNS = Object.fromEntries(Object.entries(CHANGE_WORDS)
+    .map(([change, words]) => [change, new RegExp(`\\b(?:${words.map(forms).join('|')})\\b`, 'i')]));
+
+/**
+ * The change a piece of text names ('Create', 'Update' or 'Delete'), or null.
+ * Where it names more than one, the one with most consequence (delete, then
+ * create, then update).
+ */
+export function changeAction(text) {
+    if (!text) return null;
+    return PRECEDENCE.find(change => PATTERNS[change].test(String(text))) ?? null;
+}
+
+/**
+ * The change one relationship says a deliverable or work package makes: its
+ * name, or, when it has none, the name of the deliverable or work package at
+ * one of its ends (`toward`: the end that is not the element changed, when
+ * known). Null when neither end makes changes, or nothing is said.
+ * @returns {'Create'|'Update'|'Delete'|null}
+ */
+export function relationshipChange(model, rel, toward = null) {
+    const ends = toward ? [toward] : [rel.source, rel.target];
+    const maker = ends.map(id => model.getElement(id)).find(e => e && CHANGE_MAKERS.includes(e.type));
+    if (!maker) return null;
+    return changeAction((rel.name ?? '').trim() ? rel.name : maker.name);
+}
+
+/**
+ * What change the deliverables and work packages related to an element make
+ * to it: for each relationship between them (either way), relationshipChange.
+ * Where they differ, the one with most consequence. Null when none says.
+ * @param {ArchimateModel} model
+ * @param {string} elementId
+ * @returns {'Create'|'Update'|'Delete'|null}
+ */
+export function elementChange(model, elementId) {
+    const found = new Set();
+    for (const rel of model.relationships()) {
+        const other = rel.source === elementId ? rel.target : rel.target === elementId ? rel.source : null;
+        const change = other && relationshipChange(model, rel, other);
+        if (change) found.add(change);
+    }
+    return PRECEDENCE.find(change => found.has(change)) ?? null;
+}
+
+/** Whether a model has anything that makes changes (a deliverable or work package). */
+export function hasChangeMakers(model) {
+    return model.elements().some(e => CHANGE_MAKERS.includes(e.type));
+}
+
+/**
+ * The names a formula can use for the properties: each property name as an
+ * identifier (anything not a letter, digit or _ becomes _; a leading digit gets
+ * a _ before it), mapped to the property it stands for.
+ * @param {Array<Object>} elements
+ * @returns {Map<string, string>} identifier -> property name
+ */
+export function propertyParams(elements) {
+    const params = new Map();
+    for (const e of elements) {
+        for (const p of e.properties ?? []) {
+            const name = p.name ?? p.key;
+            if (!name) continue;
+            let id = String(name).replace(/[^A-Za-z0-9_]/g, '_');
+            if (/^\d/.test(id)) id = `_${id}`;
+            if (!params.has(id)) params.set(id, name);
+        }
+    }
+    return params;
+}
+
+/**
+ * A formula's result for each element (by id): the formula over the
+ * element's numeric properties, by their propertyParams names. An element
+ * missing a property the formula uses, or whose value is not a number, or
+ * whose result is not a finite number, has none.
+ * Throws the formula's own error when it does not parse (an unknown name, say).
+ * @returns {Map<string, number>}
+ */
+export function expressionValues(elements, formula) {
+    const params = propertyParams(elements);
+    const names = [...params.keys()];
+    if (!names.length) throw new Error('No element here has a property to use');
+    const fn = compileFormula(formula, names);
+    const used = names.filter(n => new RegExp(`\\b${n}\\b`).test(formula));
+    const results = new Map();
+    for (const e of elements) {
+        const valueOf = (id) => {
+            const p = (e.properties ?? []).find(q => (q.name ?? q.key) === params.get(id));
+            const n = p === undefined || p.value === null || p.value === '' ? NaN : Number(p.value);
+            return n;
+        };
+        if (used.some(id => !Number.isFinite(valueOf(id)))) continue;
+        const result = fn(...names.map(id => { const v = valueOf(id); return Number.isFinite(v) ? v : 0; }));
+        if (Number.isFinite(result)) results.set(e.id, result);
+    }
+    return results;
+}
+
+/** A number as a label: integers as they are, others to at most 3 decimals. */
+const show = (n) => (Number.isInteger(n) ? String(n) : String(Number(n.toFixed(3))));
+
+/**
+ * Labels for a formula's results: each distinct result its own, in order,
+ * when there are at most `distinct` of them; else `bands` equal-width bands
+ * from the smallest to the largest ("10 – 20"), the last taking in the largest;
+ * a band no result falls in is left out.
+ * @param {Iterable<number>} numbers
+ * @returns {{labels: string[], labelOf: (n: number) => string}}
+ */
+export function resultBands(numbers, { distinct = 8, bands = 5 } = {}) {
+    const values = [...new Set(numbers)].sort((a, b) => a - b);
+    if (values.length <= distinct) return { labels: values.map(show), labelOf: show };
+    const lo = values[0], hi = values.at(-1), width = (hi - lo) / bands;
+    const all = Array.from({ length: bands }, (_, i) => `${show(lo + i * width)} – ${show(i === bands - 1 ? hi : lo + (i + 1) * width)}`);
+    const labelOf = (n) => all[Math.min(bands - 1, Math.floor((n - lo) / width))];
+    const used = new Set(values.map(labelOf));
+    return { labels: all.filter(l => used.has(l)), labelOf };
+}
+
+/** `count` colours from light to dark (a sequential scale, light yellow to dark red), for ordered values. */
+export function sequentialColours(count) {
+    const from = [255, 247, 188], to = [189, 0, 38];
+    const hex = (c) => Math.round(c).toString(16).padStart(2, '0');
+    return Array.from({ length: count }, (_, i) => {
+        const t = count === 1 ? 1 : i / (count - 1);
+        return `#${from.map((f, k) => hex(f + (to[k] - f) * t)).join('')}`;
+    });
+}

package/src/charting/archimate/index.js

@@ -15,3 +15,4 @@ export { ViewGroupTemplate, GROUP_FILL } from './ViewGroupTemplate.js';
 export { CustomViewpoints, CUSTOM_VIEWPOINTS_STORE } from './CustomViewpoints.js';
 export { specializationCatalogDialog } from './specializationCatalogDialog.js';
 export { elementTypeChoices } from './elementTypeChoices.js';
+export { askDeleteFromModel, deleteFromModelMessage } from './deleteFromModel.js';

package/src/charting/ask/AskBar.js

@@ -0,0 +1,388 @@
+import { AskView } from './AskView.js';
+
+/**
+ * AskBar — a self-contained browser UI component for asking questions with preemptive
+ * next-word prediction in a scrollable list (generalizing the Ask bar from
+ * `semanticengine/examples/browser/index.html` into a reusable RenderEngine capability).
+ *
+ * Follows the same OO encapsulation pattern as `ArchimateDiagramEditor`:
+ * - Owns DOM creation, CSS injection, event wiring, and keyboard/scroll management.
+ * - Separates pure state and prediction logic into `AskView` (`this.view`) so all logic is
+ *   DOM-free testable under Node.js.
+ * - Includes a configurable **Predict next word** selector allowing the user (or host) to
+ *   choose how many predicted items are visible at once in the scrollable list (e.g. `Off`,
+ *   `3`, `5`, `8`, `10`), while scrolling (`overflow-y: auto`) or pressing `↑`/`↓` browses
+ *   through the full list of predictions.
+ */
+export class AskBar {
+    /** Approximate height in pixels of one suggestion row in the scrollable list. */
+    static ITEM_HEIGHT = 44;
+
+    /** Numbers each bar's list, so several bars on one page each name their own (ARIA ids). */
+    static _count = 0;
+
+    /**
+     * @param {HTMLElement|string} container host element or its DOM id
+     * @param {object} [options] all `AskView` options plus UI options:
+     * @param {Document} [options.document] DOM document (defaults to `globalThis.document`)
+     * @param {string} [options.placeholder='Ask a question…'] input placeholder
+     * @param {string} [options.buttonLabel='Run'] submit button label
+     * @param {string} [options.ariaLabel='Question'] input aria-label
+     * @param {boolean} [options.showPredictControl=true] whether to show the configurable "Predict next word" selector
+     * @param {string} [options.predictLabel='Predict next word:'] label for the predict selector
+     * @param {boolean} [options.autoRun=false] whether to run `onAsk` immediately upon mounting
+     * @param {object} [options.resultEngine] optional `RenderEngine` instance whose `resultView()` displays `{ rows, columns, complete }` returned by `onAsk`
+     */
+    constructor(container, options = {}) {
+        this.options = options;
+        this.doc = options.document ?? container?.ownerDocument ?? globalThis.document ?? null;
+        this.container = typeof container === 'string'
+            ? this.doc?.getElementById?.(container) ?? null
+            : container ?? null;
+        this.resultEngine = options.resultEngine ?? null;
+
+        const userOnAsk = options.onAsk;
+        this.listId = `re-ask-list-${++AskBar._count}`;
+        this._blurTimer = null;
+        // An answer (`{ rows, columns, complete }`), or a promise of one, is shown by resultEngine.
+        const show = (res) => {
+            if (res && typeof res === 'object' && Array.isArray(res.rows) && this.resultEngine?.resultView) {
+                this.resultEngine.resultView(res.rows, {
+                    columns: res.columns,
+                    complete: res.complete,
+                    pageSize: options.pageSize ?? 10,
+                });
+            }
+            return res;
+        };
+        this.view = options.view instanceof AskView ? options.view : new AskView({
+            ...options,
+            onAsk: (question, view) => {
+                const res = userOnAsk?.(question, view, this);
+                return res && typeof res.then === 'function' ? Promise.resolve(res).then(show) : show(res);
+            },
+            onChange: (view) => {
+                this._syncFromView();
+                options.onChange?.(view, this);
+            },
+        });
+
+        this.root = null;
+        this.inputEl = null;
+        this.suggestEl = null;
+        this.predictSelectEl = null;
+        this.samplesEl = null;
+
+        if (this.container && this.doc) {
+            this.render();
+            if (options.autoRun && this.view.value) {
+                this.view.submit(this.view.value);
+            }
+        }
+    }
+
+    /** Injects the component's scoped stylesheet once per document, build-free and theme-aware. */
+    static _injectStyles(doc) {
+        if (!doc?.head || doc.getElementById?.('re-ask-bar-styles')) return;
+        const style = doc.createElement('style');
+        style.id = 're-ask-bar-styles';
+        style.textContent = `
+            .re-ask-bar { display: flex; flex-direction: column; gap: 6px; font: 14px/1.45 system-ui, sans-serif; color: var(--ws-fg, var(--fg, #1d1d1f)); }
+            .re-ask-form { display: flex; gap: 8px; flex-wrap: wrap; align-items: center; margin: 0; }
+            .re-ask-input-wrapper { position: relative; flex: 1 1 260px; min-width: 180px; }
+            .re-ask-input { width: 100%; box-sizing: border-box; padding: 7px 10px; font: inherit; color: inherit; background: var(--ws-panel-bg, var(--bg, #fff)); border: 1px solid var(--ws-border, var(--line, #ccc)); border-radius: 6px; }
+            .re-ask-input:focus { outline: 2px solid var(--ws-accent, var(--accent, #2b5fd9)); outline-offset: -1px; }
+            .re-ask-submit { padding: 7px 14px; font: inherit; font-weight: 500; color: #fff; background: var(--ws-accent, var(--accent, #2b5fd9)); border: 0; border-radius: 6px; cursor: pointer; }
+            .re-ask-submit:hover { filter: brightness(1.06); }
+            .re-ask-predict-ctrl { display: inline-flex; align-items: center; gap: 6px; font-size: 12px; color: var(--ws-muted, var(--muted, #666)); }
+            .re-ask-predict-select { padding: 5px 7px; font: inherit; color: var(--ws-fg, var(--fg, #1d1d1f)); background: var(--ws-panel-bg, var(--bg, #fff)); border: 1px solid var(--ws-border, var(--line, #ccc)); border-radius: 5px; }
+            .re-ask-suggest-box {
+                position: absolute; top: calc(100% + 4px); left: 0; right: 0; z-index: 250;
+                background: var(--ws-panel-bg, var(--bg, #fff));
+                border: 1px solid var(--ws-border, var(--line, #ccc));
+                border-radius: 6px; box-shadow: 0 4px 16px rgba(0,0,0,0.18);
+                overflow-y: auto; display: flex; flex-direction: column;
+            }
+            .re-ask-suggest-box[hidden] { display: none !important; }
+            .re-ask-suggest-item {
+                display: flex; align-items: center; justify-content: space-between;
+                padding: 7px 10px; cursor: pointer; font-size: 13px; gap: 8px; user-select: none;
+                box-sizing: border-box; min-height: 36px;
+            }
+            .re-ask-suggest-item:hover, .re-ask-suggest-item.active {
+                background: var(--ws-accent, var(--accent, #2b5fd9)); color: #fff;
+            }
+            .re-ask-suggest-main { display: flex; flex-direction: column; gap: 1px; min-width: 0; }
+            .re-ask-suggest-text { font-family: ui-monospace, monospace; font-size: 13px; }
+            .re-ask-suggest-sense { font-size: 11px; color: var(--ws-muted, var(--muted, #6b6b70)); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+            .re-ask-suggest-item:hover .re-ask-suggest-sense,
+            .re-ask-suggest-item.active .re-ask-suggest-sense { color: rgba(255, 255, 255, 0.85); }
+            .re-ask-suggest-badges { display: flex; gap: 4px; align-items: center; flex-shrink: 0; }
+            .re-ask-suggest-badge {
+                font-size: 10px; text-transform: uppercase; letter-spacing: 0.05em;
+                padding: 2px 6px; border-radius: 4px;
+                background: var(--ws-border, var(--line, #e0e0e4));
+                color: var(--ws-muted, var(--muted, #555)); flex-shrink: 0;
+            }
+            .re-ask-suggest-item:hover .re-ask-suggest-badge,
+            .re-ask-suggest-item.active .re-ask-suggest-badge {
+                background: rgba(255, 255, 255, 0.25); color: #fff;
+            }
+            .re-ask-samples { font-size: 12px; color: var(--ws-muted, var(--muted, #666)); display: flex; flex-wrap: wrap; gap: 6px; align-items: center; }
+            .re-ask-sample-pill {
+                font-family: ui-monospace, monospace; font-size: 11.5px;
+                padding: 2px 6px; border-radius: 4px; cursor: pointer;
+                background: rgba(127,127,127,0.12); border: 1px solid var(--ws-border, var(--line, #ddd));
+                color: var(--ws-fg, var(--fg, #222));
+            }
+            .re-ask-sample-pill:hover { border-color: var(--ws-accent, var(--accent, #2b5fd9)); }
+        `;
+        doc.head.appendChild(style);
+    }
+
+    /** Builds the AskBar DOM inside `this.container`. */
+    render() {
+        if (!this.container || !this.doc) return this;
+        AskBar._injectStyles(this.doc);
+
+        const root = this.doc.createElement('div');
+        root.className = 're-ask-bar';
+
+        const form = this.doc.createElement('form');
+        form.className = 're-ask-form';
+
+        const wrapper = this.doc.createElement('div');
+        wrapper.className = 're-ask-input-wrapper';
+
+        const input = this.doc.createElement('input');
+        input.className = 're-ask-input';
+        input.type = 'text';
+        input.value = this.view.value;
+        input.placeholder = this.options.placeholder ?? 'Ask a question…';
+        input.setAttribute('aria-label', this.options.ariaLabel ?? 'Question');
+        input.setAttribute('autocomplete', 'off');
+        input.setAttribute('spellcheck', 'false');
+        // A combobox over its list of completions (WAI-ARIA 1.2), so a screen reader follows ↑/↓.
+        input.setAttribute('role', 'combobox');
+        input.setAttribute('aria-autocomplete', 'list');
+        input.setAttribute('aria-controls', this.listId);
+        input.setAttribute('aria-expanded', 'false');
+
+        const suggestBox = this.doc.createElement('div');
+        suggestBox.className = 're-ask-suggest-box';
+        suggestBox.id = this.listId;
+        suggestBox.hidden = true;
+        suggestBox.setAttribute('role', 'listbox');
+        suggestBox.setAttribute('aria-label', 'Suggested completions');
+
+        wrapper.appendChild(input);
+        wrapper.appendChild(suggestBox);
+        form.appendChild(wrapper);
+
+        const submitBtn = this.doc.createElement('button');
+        submitBtn.type = 'submit';
+        submitBtn.className = 're-ask-submit';
+        submitBtn.textContent = this.options.buttonLabel ?? 'Run';
+        form.appendChild(submitBtn);
+
+        if (this.options.showPredictControl !== false) {
+            const ctrlLabel = this.doc.createElement('label');
+            ctrlLabel.className = 're-ask-predict-ctrl';
+            ctrlLabel.textContent = this.options.predictLabel ?? 'Predict next word:';
+
+            const select = this.doc.createElement('select');
+            select.className = 're-ask-predict-select';
+            select.setAttribute('aria-label', 'Predict next word in scrollable list');
+            for (const choice of this.view.predictChoices) {
+                const n = Number(choice);
+                const text = n <= 0 ? 'Off' : `${n} visible (scrollable)`;
+                const opt = this.doc.createElement('option');
+                opt.value = String(n);
+                opt.textContent = text;
+                if (n === this.view.predictCount) opt.selected = true;
+                select.appendChild(opt);
+            }
+            select.addEventListener('change', () => {
+                this.view.setPredictCount(Number(select.value));
+            });
+            ctrlLabel.appendChild(select);
+            form.appendChild(ctrlLabel);
+            this.predictSelectEl = select;
+        }
+
+        root.appendChild(form);
+
+        if (this.view.samples.length > 0) {
+            const samplesRow = this.doc.createElement('div');
+            samplesRow.className = 're-ask-samples';
+            const prefix = this.doc.createElement('span');
+            prefix.textContent = 'Try:';
+            samplesRow.appendChild(prefix);
+            for (const q of this.view.samples) {
+                const pill = this.doc.createElement('code');
+                pill.className = 're-ask-sample-pill';
+                pill.textContent = q;
+                pill.addEventListener('click', () => {
+                    this.view.submit(q);
+                });
+                samplesRow.appendChild(pill);
+            }
+            root.appendChild(samplesRow);
+            this.samplesEl = samplesRow;
+        }
+
+        this.root = root;
+        this.inputEl = input;
+        this.suggestEl = suggestBox;
+        this._wireEvents(form, input);
+        this.container.replaceChildren ? this.container.replaceChildren(root) : (this.container.innerHTML = '', this.container.appendChild(root));
+        this._syncFromView();
+        return this;
+    }
+
+    _wireEvents(form, input) {
+        input.addEventListener('input', () => {
+            this.view.setInput(input.value, { suggest: true });
+        });
+        input.addEventListener('focus', () => {
+            if (this.view.predict) this.view.refresh();
+        });
+        input.addEventListener('blur', () => {
+            this._blurTimer = setTimeout(() => { this._blurTimer = null; this.view.close(); }, 150);
+        });
+        input.addEventListener('keydown', (e) => {
+            if (!this.view.open || this.view.items.length === 0) {
+                if (e.key === 'ArrowDown' || e.key === 'ArrowUp') {
+                    this.view.refresh();
+                }
+                return;
+            }
+            if (e.key === 'ArrowDown') {
+                e.preventDefault();
+                this.view.move(1);
+            } else if (e.key === 'ArrowUp') {
+                e.preventDefault();
+                this.view.move(-1);
+            } else if (e.key === 'Tab') {
+                e.preventDefault();
+                this.view.accept(this.view.selectedIndex >= 0 ? this.view.selectedIndex : 0);
+                this.inputEl?.focus?.();
+            } else if (e.key === 'Enter' && this.view.selectedIndex >= 0) {
+                e.preventDefault();
+                this.view.accept(this.view.selectedIndex);
+                this.inputEl?.focus?.();
+            } else if (e.key === 'Escape') {
+                this.view.close();
+            }
+        });
+        form.addEventListener('submit', (e) => {
+            e.preventDefault();
+            this.view.submit(input.value);
+        });
+    }
+
+    /** Swaps where suggestions come from (`AskView.setSuggest`): another model or ontology. */
+    setSuggest(suggest) {
+        this.view.setSuggest(suggest);
+        return this;
+    }
+
+    /** Sets the question shown, without suggesting. */
+    setValue(text) {
+        this.view.setInput(text, { suggest: false });
+        return this;
+    }
+
+    /** Puts the cursor in the question. */
+    focus() {
+        this.inputEl?.focus?.();
+        return this;
+    }
+
+    /** Takes the bar out of its container; a pending close is cancelled. */
+    destroy() {
+        if (this._blurTimer !== null) clearTimeout(this._blurTimer);
+        this._blurTimer = null;
+        this.root?.remove?.();
+        this.root = this.inputEl = this.suggestEl = this.predictSelectEl = this.samplesEl = null;
+    }
+
+    _syncFromView() {
+        if (!this.inputEl || !this.suggestEl) return;
+        if (this.inputEl.value !== this.view.value) {
+            this.inputEl.value = this.view.value;
+        }
+        if (this.predictSelectEl) {
+            const val = String(this.view.predictCount);
+            if (this.predictSelectEl.value !== val) this.predictSelectEl.value = val;
+        }
+
+        const active = this.view.selectedIndex;
+        if (active >= 0 && this.view.open) this.inputEl.setAttribute('aria-activedescendant', `${this.listId}-${active}`);
+        else this.inputEl.removeAttribute?.('aria-activedescendant');
+
+        if (!this.view.open || !this.view.predict || this.view.items.length === 0) {
+            this.inputEl.setAttribute('aria-expanded', 'false');
+            this.suggestEl.hidden = true;
+            if (this.suggestEl.replaceChildren) this.suggestEl.replaceChildren();
+            return;
+        }
+
+        this.suggestEl.style.maxHeight = `${Math.max(1, this.view.visibleCount) * AskBar.ITEM_HEIGHT}px`;
+        if (this.suggestEl.replaceChildren) this.suggestEl.replaceChildren();
+
+        this.view.items.forEach((item, idx) => {
+            const row = this.doc.createElement('div');
+            row.className = `re-ask-suggest-item${idx === this.view.selectedIndex ? ' active' : ''}`;
+            row.dataset.index = String(idx);
+            row.id = `${this.listId}-${idx}`;
+            row.setAttribute('role', 'option');
+            row.setAttribute('aria-selected', String(idx === this.view.selectedIndex));
+
+            const mainCol = this.doc.createElement('div');
+            mainCol.className = 're-ask-suggest-main';
+
+            const textSpan = this.doc.createElement('span');
+            textSpan.className = 're-ask-suggest-text';
+            textSpan.textContent = item.display;
+            mainCol.appendChild(textSpan);
+
+            if (item.sense) {
+                const senseSpan = this.doc.createElement('span');
+                senseSpan.className = 're-ask-suggest-sense';
+                senseSpan.textContent = `${item.sense}${item.reference ? ` → ${item.reference}` : ''}`;
+                mainCol.appendChild(senseSpan);
+            }
+
+            const badges = this.doc.createElement('div');
+            badges.className = 're-ask-suggest-badges';
+
+            if (item.relation && item.relation !== 'canonical' && item.relation !== 'function') {
+                const relBadge = this.doc.createElement('span');
+                relBadge.className = 're-ask-suggest-badge';
+                relBadge.textContent = item.relation;
+                badges.appendChild(relBadge);
+            }
+            if (item.kind) {
+                const kindBadge = this.doc.createElement('span');
+                kindBadge.className = 're-ask-suggest-badge';
+                kindBadge.textContent = item.kind;
+                badges.appendChild(kindBadge);
+            }
+
+            row.appendChild(mainCol);
+            row.appendChild(badges);
+            row.addEventListener('mousedown', (e) => {
+                e.preventDefault();
+                this.view.accept(idx);
+                this.inputEl?.focus?.();
+            });
+            this.suggestEl.appendChild(row);
+            if (idx === this.view.selectedIndex && typeof row.scrollIntoView === 'function') {
+                row.scrollIntoView({ block: 'nearest' });
+            }
+        });
+        this.suggestEl.hidden = false;
+        this.inputEl.setAttribute('aria-expanded', 'true');
+    }
+}