@peter.prib/renderengine 0.13.0 → 0.14.0

package/documentation/REFERENCE.md

@@ -74,7 +74,7 @@ catalog `key` for you.
 | `sankey` | `sankeyDiagram(data, opts)` | `{nodes?: Array<{id,label?,color?}>, links: Array<{source,target,value}>}` | proportional-width flow links; `nodeWidth`, `linkOpacity` |
 | `chord` | `chordDiagram(data, opts)` | same as `sankey` | nodes on a circle with curved chords of proportional thickness |
 | `candlestick` | `candlestick(data, opts)` | `Array<{label, open, high, low, close}>` | `upColor`, `downColor`, `markers` (tooltip annotations) |
-| `stackedBar` | `stackedBarChart(data, opts)` | `Array<{label, values:number[]}>` | `colors` (no built-in legend — a known gap) |
+| `stackedBar` | `stackedBarChart(data, opts)` | multi-series `Array<{name, values:Array<{label,value}>}>` or `Array<{label, values:number[]}>` | `colors`, `legend`, `seriesLabels`; draws Y-axis ticks and legend |
 | `pipe` | `pipeChart(data, opts)` | `Array<{label, value, metric?}>` or multi-series | `metric` tapers line width; `legend` |
 | `radar` | `radarChart(data, opts)` | `Array<{axis, value}>` or multi-series | `colors`, `legend` |
 | `funnel` | `funnelChart(data, opts)` | `Array<{label, value}>` (largest first) | `colors` |
@@ -3282,6 +3282,35 @@ const mine = ICONS.with({                            // a host's own icons over
 the workspace bundle), until a `foreignObject`, whose children are HTML again. A spec's `ns` sets the namespace
 explicitly.
 
+## Ask Bar & Next-Word Typeahead (`AskBar` / `AskView`)
+
+`AskBar` (`src/charting/ask/AskBar.js`) and its DOM-free state model `AskView` (`src/charting/ask/AskView.js`) provide the interactive question bar and scrollable next-word prediction dropdown (as used in `semanticengine/examples/browser/index.html` and the **Cubing** tab in `test/charts.html`).
+
+```javascript
+import { RenderEngine, AskBar, AskView } from '@peter.prib/renderengine';
+
+const bar = RenderEngine.askBar(document.getElementById('ask-bar'), {
+    value: 'top 3 customers by revenue',
+    // Either pass a custom suggestion callback (e.g. semanticengine's engine.suggest):
+    suggest: (text) => semanticEngine.suggest(text, { sampler: (dim) => semanticEngine.members(dim) }),
+    // Or pass declarative cube/table metadata for built-in next-word prediction:
+    // measures: ['Revenue', 'Cost'],
+    // dimensions: ['Region', 'Quarter'],
+    // members: (dim) => [...],
+    sampleQuestions: ['revenue by region', 'top 3 customers by revenue'],
+    visibleCount: 5,                     // items visible at once in the scrollable list
+    predictChoices: [0, 3, 5, 8, 10],    // 0 = Off; user can switch in the bar's selector
+    onAsk: (question) => runQuery(question),
+});
+```
+
+- **Configurable scrollable next-word prediction:** `visibleCount` (default `5`) sets how many predicted items show at once before scrolling (`max-height` on `.re-ask-suggest-box` with `overflow-y: auto`), and `predictChoices` (default `[0, 3, 5, 8, 10]`) populates the **Predict next word** selector (`Off`, `3 visible (scrollable)`, `5 visible (scrollable)`, …). Set `showPredictControl: false` to hide the selector.
+- **Semantic badges:** each suggestion item (`{ display, completion, sense?, reference?, relation?, kind? }`) renders its `display` token, optional `sense → reference` subtitle, lexical `relation` badge (`synonym`, `hypernym`, `hyponym`, `antonym`), and `kind` badge (`metric`, `dimension`, `keyword`, `value`).
+- **Keyboard navigation:** nothing in the list is selected until you move into it, so `Enter` asks the question as typed. `↑` / `↓` move through the scrollable list, starting at the last or first item and scrolling the active item into view. `Enter` completes the selected item; `Tab` completes the selected item, or the first. Either one immediately predicts the following word. `Escape` closes the popup.
+- **Async sources and answers:** `suggest` can return a promise, for example from an engine that is still loading or a vocabulary on a server. The list keeps showing what it had until the promise settles. An answer for text the user has since changed is dropped, and a rejected promise shows no suggestions. `onAsk` can also return a promise of `{ rows, columns, complete }`, which `resultEngine` shows once it settles.
+- **For a host:** `bar.setSuggest(fn)` swaps where suggestions come from, for example when the user picks another model or ontology. `bar.setValue(text)` sets the question without suggesting. `bar.focus()` puts the cursor in the question, and `bar.destroy()` removes the bar and cancels any pending close.
+- **Accessible:** the input is a WAI-ARIA combobox over a `listbox` of `option`s. `aria-expanded` follows the popup and `aria-activedescendant` follows the active item. Each bar's list has its own id, so several bars can share a page.
+
 ## Where to go next
 
 - **`ARCHITECTURE.md`** — module layout, the chart-type catalog mechanics, how to add a new chart type.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@peter.prib/renderengine",
-  "version": "0.13.0",
-  "description": "ArchiMate modeller, diagram editor and chart library for the browser, with no runtime dependencies.",
+  "version": "0.14.0",
+  "description": "ArchiMate modeller, data modeller, diagram editor, OLAP cube & pivot chart studio, and 50+ type chart library for the browser, with no runtime dependencies.",
   "type": "module",
   "main": "src/index.js",
   "module": "src/index.js",
@@ -28,7 +28,7 @@
     "archimate": "node scripts/open.mjs examples/archimate.html",
     "diagram": "node scripts/open.mjs examples/diagram-editor.html",
     "datamodel": "node scripts/open.mjs examples/data-model.html",
-    "test": "node --test --test-timeout=10000 ./test/*.js ./test/charting/*.js ./test/charting/charts/*.js ./test/charting/table/*.js ./test/charting/pivot/*.js ./test/charting/diagrams/*.js ./test/charting/shapes/*.js",
+    "test": "node --test --test-timeout=10000 ./test/*.js ./test/charting/*.js ./test/charting/charts/*.js ./test/charting/table/*.js ./test/charting/pivot/*.js ./test/charting/ask/*.js ./test/charting/diagrams/*.js ./test/charting/shapes/*.js",
     "build": "rollup -c",
     "prepublishOnly": "npm test && npm run build",
     "screenshots": "node scripts/screenshots/screenshots.mjs"
@@ -38,6 +38,11 @@
     "archi",
     "diagram",
     "diagram-editor",
+    "data-modelling",
+    "bian",
+    "olap",
+    "pivot",
+    "cube",
     "modelling",
     "charts",
     "svg",

package/src/chartCatalog.js

@@ -318,12 +318,15 @@ export const CHART_CATALOG = [
   },
   {
     key: 'stackedBar', label: 'Stacked Bar', method: 'stackedBarChart', category: '2d',
-    coordSystem: COORD_SYSTEM.CARTESIAN, title: true, legend: false, colorMode: COLOR_MODE.PALETTE, camera: CAMERA_MODE.NONE,
+    coordSystem: COORD_SYSTEM.CARTESIAN, title: true, legend: true, colorMode: COLOR_MODE.PALETTE, camera: CAMERA_MODE.NONE,
+    seriesCapable: true,
     axes: [
       { role: 'category', kind: AXIS_KIND.CATEGORICAL,  channel: ENCODING_CHANNEL.POSITION_X,        required: true },
-      { role: 'values',   kind: AXIS_KIND.NUMERIC_LIST, channel: ENCODING_CHANNEL.POSITION_Y_STACKED, required: true },
+      { role: 'values',   kind: AXIS_KIND.NUMERIC_LIST, channel: ENCODING_CHANNEL.POSITION_Y_STACKED, required: false },
+      { role: 'value',    kind: AXIS_KIND.NUMERIC,      channel: ENCODING_CHANNEL.POSITION_Y_STACKED, required: false },
+      { role: 'series',   kind: AXIS_KIND.CATEGORICAL,  channel: ENCODING_CHANNEL.COLOR,              required: false },
     ],
-    dataShape: "Array<{label, values:number[]}> e.g. [{label:'Jan', values:[10,20]}] — no built-in legend option despite being multi-series (a real gap; areaChart's stacked mode has one, this doesn't)",
+    dataShape: "Array<{label, values:number[]}> or multi-series Array<{name, values:Array<{label,value}>}> — segments stacked from zero, with optional series legend",
     streamShape: 'flat', // a new stacked bar is a whole new {label,values} record appended to the outer array, not growth of an existing record's values
   },
   {
@@ -564,6 +567,50 @@ export const CHART_CATALOG = [
     dataShape: 'Array<{label, x, y, z, size?, category?}> — real orbit camera (drag-rotate/wheel-zoom); a future sphere/ellipsoid variant is this same shape with a second shape-size-channeled role, not a new chart type',
     streamShape: 'flat',
   },
+  {
+    key: 'pareto', label: 'Pareto', method: 'paretoChart', category: '2d',
+    coordSystem: COORD_SYSTEM.CARTESIAN, title: true, legend: false, colorMode: COLOR_MODE.SEMANTIC, camera: CAMERA_MODE.NONE,
+    axes: [
+      { role: 'category', kind: AXIS_KIND.CATEGORICAL, channel: ENCODING_CHANNEL.POSITION_X, required: true },
+      { role: 'value',    kind: AXIS_KIND.NUMERIC,      channel: ENCODING_CHANNEL.POSITION_Y, required: true },
+    ],
+    dataShape: 'Array<{label, value}> — sorted descending with a right-hand 0-100% cumulative percentage line and 80% cutoff reference line',
+    streamShape: 'flat',
+  },
+  {
+    key: 'lollipop', label: 'Lollipop', method: 'lollipopChart', category: '2d',
+    coordSystem: COORD_SYSTEM.CARTESIAN, title: true, legend: true, colorMode: COLOR_MODE.PALETTE, camera: CAMERA_MODE.NONE,
+    seriesCapable: true,
+    axes: [
+      { role: 'category', kind: AXIS_KIND.CATEGORICAL, channel: ENCODING_CHANNEL.POSITION_X, required: true },
+      { role: 'value',    kind: AXIS_KIND.NUMERIC,      channel: ENCODING_CHANNEL.POSITION_Y, required: true },
+      { role: 'series',   kind: AXIS_KIND.CATEGORICAL, channel: ENCODING_CHANNEL.COLOR,      required: false },
+    ],
+    dataShape: 'Array<{label, value}> or multi-series Array<{name, values:Array<{label,value}>}> — stem-and-dot alternative to bars',
+    streamShape: 'flat',
+  },
+  {
+    key: 'marimekko', label: 'Marimekko', method: 'marimekkoChart', category: '2d',
+    coordSystem: COORD_SYSTEM.CARTESIAN, title: true, legend: true, colorMode: COLOR_MODE.PALETTE, camera: CAMERA_MODE.NONE,
+    seriesCapable: true,
+    axes: [
+      { role: 'category', kind: AXIS_KIND.CATEGORICAL, channel: ENCODING_CHANNEL.SHAPE_WIDTH,       required: true },
+      { role: 'value',    kind: AXIS_KIND.NUMERIC,      channel: ENCODING_CHANNEL.POSITION_Y_HEIGHT, required: true },
+      { role: 'series',   kind: AXIS_KIND.CATEGORICAL, channel: ENCODING_CHANNEL.COLOR,             required: true },
+    ],
+    dataShape: 'Multi-series Array<{name, values:Array<{label,value}>}> or Array<{label, values:number[]}> — variable-width 100%-stacked mosaic columns',
+    streamShape: 'series',
+  },
+  {
+    key: 'icicle', label: 'Icicle', method: 'icicleChart', category: '2d',
+    coordSystem: COORD_SYSTEM.CARTESIAN, title: true, legend: false, colorMode: COLOR_MODE.PALETTE, camera: CAMERA_MODE.NONE,
+    axes: [
+      { role: 'value', kind: AXIS_KIND.NUMERIC,     channel: ENCODING_CHANNEL.ANGLE_OR_AREA,  required: true },
+      { role: 'group', kind: AXIS_KIND.CATEGORICAL, channel: ENCODING_CHANNEL.POSITION_ORDER, required: false },
+    ],
+    dataShape: 'Array<{label, value?, children?}> — rectangular hierarchical partition chart (top-down bands by depth, width proportional to value)',
+    streamShape: 'flat',
+  },
   {
     key: 'bar3DOrbit', label: 'Bar (3D Orbit)', method: 'barChart3DOrbit', category: '3d',
     coordSystem: COORD_SYSTEM.ORBIT_3D, title: true, legend: false, colorMode: COLOR_MODE.PALETTE, camera: CAMERA_MODE.ORBIT,

package/src/charting/Chart3D.js

@@ -72,8 +72,9 @@ export class Chart3D extends Chart {
 
     /**
      * Draw one 3D box through the orbit camera. Returns average corner depth.
+     * When `datum` is supplied (`{ label, series? }`), each face is recorded via `_datum()`.
      */
-    drawBox(renderer, x0, x1, y0, y1, z0, z1, color, toScreen) {
+    drawBox(renderer, x0, x1, y0, y1, z0, z1, color, toScreen, datum = null) {
         const camera = this.camera;
         const faceXSign = Math.sin(camera.theta) >= 0 ? 1 : -1;
         const faceZSign = Math.cos(camera.theta) >= 0 ? 1 : -1;
@@ -87,7 +88,8 @@ export class Chart3D extends Chart {
 
         const drawFace = (pts, shade) => {
             const d = `M${pts[0].x},${pts[0].y} L${pts[1].x},${pts[1].y} L${pts[2].x},${pts[2].y} L${pts[3].x},${pts[3].y} Z`;
-            renderer.path(d, ColorPalette.lighten(color, shade), { color: '#333', width: 1 });
+            const el = renderer.path(d, ColorPalette.lighten(color, shade), { color: '#333', width: 1 });
+            if (datum) this._datum(el, datum);
         };
         drawFace(top, 0.15);
         drawFace(xSide, faceXSign > 0 ? -0.05 : -0.2);

package/src/charting/Hierarchy.js

@@ -145,6 +145,34 @@ export class Hierarchy {
         return result;
     }
 
+    /**
+     * Recursive rectangular partition (icicle / flame graph) layout over a node tree.
+     * Partitions `width` proportionally to node value at each level and steps down by `bandHeight` per depth.
+     * @returns {Array<{node: object, x: number, y: number, width: number, height: number, depth: number, isLeaf: boolean, topAncestor: object}>}
+     */
+    static icicleLayout(nodes, x, y, width, bandHeight, depth = 0, topAncestors = null) {
+        const items = (nodes ?? [])
+            .map(node => ({ node, value: Hierarchy.value(node) }))
+            .filter(it => it.value > 0);
+        const total = items.reduce((s, it) => s + it.value, 0) || 1;
+
+        const result = [];
+        let cursorX = x;
+        for (const it of items) {
+            const { node } = it;
+            const spanW = (it.value / total) * width;
+            const isLeaf = !node.children?.length;
+            const topAncestor = topAncestors ? topAncestors.get(node) : node;
+            result.push({ node, x: cursorX, y, width: spanW, height: bandHeight, depth, isLeaf, topAncestor });
+            if (!isLeaf) {
+                const childTopAncestors = new Map(node.children.map(c => [c, topAncestor]));
+                result.push(...Hierarchy.icicleLayout(node.children, cursorX, y + bandHeight, spanW, bandHeight, depth + 1, childTopAncestors));
+            }
+            cursorX += spanW;
+        }
+        return result;
+    }
+
     /**
      * Flat, pre-order list of *visible* rows for an outline view. A branch
      * present in `collapsed` contributes its own row but none of its

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