@peter.prib/renderengine 0.13.0 → 0.15.0

package/src/charting/ask/AskView.js

@@ -0,0 +1,400 @@
+/**
+ * AskView — the state and next-word prediction model for an interactive "Ask" bar
+ * (question input, scrollable predictive typeahead list with semantic sense/reference/relation
+ * badges, keyboard navigation, and configurable next-word prediction), kept apart from DOM
+ * rendering so all of it can be unit-tested under Node.js without a browser.
+ *
+ * A host can supply its own `suggest(text, view)` callback (for example, semanticengine's
+ * `(text) => engine.suggest(text, { sampler: (dim) => engine.members(dim) })`), or pass
+ * declarative vocabulary hints (`measures`, `dimensions`, `members`, `vocabulary`,
+ * `sampleQuestions`) to use `AskView.nextWordPredictor(...)`.
+ */
+export class AskView {
+    /** Default choices for how many predicted next-word items are visible at once in the scrollable list (`0` = Off). */
+    static DEFAULT_PREDICT_CHOICES = [0, 3, 5, 8, 10];
+
+    /**
+     * @param {object} [options]
+     * @param {string} [options.value=''] initial question text
+     * @param {function} [options.suggest] `(text, view) => Array<string|{display, completion?, sense?, reference?, relation?, kind?}>`, or a promise of one
+     * @param {string[]} [options.measures] measure names for built-in next-word prediction
+     * @param {string[]} [options.dimensions] dimension names for built-in next-word prediction
+     * @param {function|object} [options.members] `(dimension) => Array<string|number>` or `{ dim: [...] }` for value prediction after `=`
+     * @param {Array<string|{display, completion?, sense?, reference?, relation?, kind?}>} [options.vocabulary] custom vocabulary entries
+     * @param {string[]} [options.sampleQuestions] sample questions used both as clickable pills and to learn next-word transitions
+     * @param {boolean} [options.predict=true] whether next-word prediction is initially enabled
+     * @param {number} [options.visibleCount=5] how many items are visible at once in the scrollable suggestion viewport
+     * @param {number[]} [options.predictChoices=[0, 3, 5, 8, 10]] configurable choices for the predict-next-word selector (`0` = Off)
+     * @param {number} [options.maxSuggestions=50] maximum number of suggestions kept in the scrollable list
+     * @param {function} [options.onAsk] `(question, view) => *` called when the user submits the question
+     * @param {function} [options.onComplete] `(item, view) => void` called when a suggestion is accepted
+     * @param {function} [options.onChange] `(view) => void` called whenever view state changes
+     */
+    constructor(options = {}) {
+        this.value = options.value ?? '';
+        this.samples = [...(options.sampleQuestions ?? options.samples ?? [])];
+        this.predictChoices = Array.isArray(options.predictChoices) && options.predictChoices.length > 0
+            ? [...options.predictChoices]
+            : [...AskView.DEFAULT_PREDICT_CHOICES];
+        const initialVisible = Number.isFinite(options.visibleCount) && options.visibleCount > 0 ? Math.floor(options.visibleCount) : 5;
+        this.visibleCount = initialVisible;
+        this.predict = options.predict !== false && options.visibleCount !== 0;
+        if (this.predict && !this.predictChoices.includes(this.visibleCount)) {
+            this.predictChoices = [...new Set([...this.predictChoices, this.visibleCount])].sort((a, b) => a - b);
+        }
+        this.maxSuggestions = Number.isFinite(options.maxSuggestions) && options.maxSuggestions > 0
+            ? Math.floor(options.maxSuggestions)
+            : 50;
+        this.suggestFn = typeof options.suggest === 'function'
+            ? options.suggest
+            : AskView.nextWordPredictor({
+                measures: options.measures,
+                dimensions: options.dimensions,
+                members: options.members,
+                vocabulary: options.vocabulary,
+                sampleQuestions: this.samples,
+            });
+        this.onAsk = options.onAsk ?? null;
+        this.onComplete = options.onComplete ?? null;
+        this.onChange = options.onChange ?? null;
+        this.items = [];
+        this.selectedIndex = -1;
+        this.open = false;
+        this.history = [];
+        this._ticket = 0;
+    }
+
+    /**
+     * Current predict-next-word setting as a single number (`0` when Off, else `visibleCount`),
+     * matching `predictChoices`.
+     */
+    get predictCount() {
+        return this.predict ? this.visibleCount : 0;
+    }
+
+    /**
+     * Enables or disables next-word prediction, or sets how many items show at once in the
+     * scrollable list (`0` or `false` turns prediction off; a positive integer enables it with
+     * that viewport size).
+     */
+    setPredictCount(countOrEnabled) {
+        if (countOrEnabled === false || countOrEnabled === 0 || countOrEnabled === '0' || countOrEnabled === 'off') {
+            this.predict = false;
+            this.items = [];
+            this.selectedIndex = -1;
+            this.open = false;
+            this._changed();
+            return;
+        }
+        if (countOrEnabled === true) {
+            this.predict = true;
+            if (this.visibleCount <= 0) this.visibleCount = 5;
+        } else {
+            const n = Number(countOrEnabled);
+            if (Number.isFinite(n) && n > 0) {
+                this.predict = true;
+                this.visibleCount = Math.floor(n);
+            }
+        }
+        this.refresh();
+    }
+
+    /** Updates the input text and refreshes next-word predictions if enabled. */
+    setInput(text, { suggest = true } = {}) {
+        this.value = String(text ?? '');
+        if (suggest && this.predict) {
+            return this.refresh();
+        } else {
+            if (!suggest) {
+                this.open = false;
+                this.selectedIndex = -1;
+            }
+            this._changed();
+        }
+    }
+
+    /**
+     * Swaps the source of suggestions (a host whose vocabulary changed — another model or
+     * ontology) and refreshes the list.
+     */
+    setSuggest(suggest) {
+        this.suggestFn = typeof suggest === 'function' ? suggest : null;
+        this.refresh();
+    }
+
+    /**
+     * Recomputes suggestions for the current `value` and opens the list if any match. Nothing is
+     * selected until the user moves into the list, so Enter asks the question as typed.
+     *
+     * `suggest` may answer with a promise (an engine still loading, a server's vocabulary): the
+     * list keeps what it shows until it settles, and an answer for text since changed is dropped.
+     * Returns the items, or a promise of them.
+     */
+    refresh() {
+        const ticket = ++this._ticket;
+        if (!this.predict || !this.suggestFn) {
+            this._apply([]);
+            return this.items;
+        }
+        let raw;
+        try {
+            raw = this.suggestFn(this.value, this);
+        } catch {
+            this._apply([]);
+            return this.items;
+        }
+        if (raw && typeof raw.then === 'function') {
+            const asked = this.value;
+            return Promise.resolve(raw).then(
+                (items) => (ticket === this._ticket && asked === this.value ? this._apply(items) : this.items),
+                () => (ticket === this._ticket ? this._apply([]) : this.items),
+            );
+        }
+        return this._apply(raw);
+    }
+
+    /** Shows `raw` suggestions (anything not a list shows none). */
+    _apply(raw) {
+        this.items = Array.isArray(raw)
+            ? raw.slice(0, this.maxSuggestions).map((item) => AskView.normalizeItem(item, this.value))
+            : [];
+        this.selectedIndex = -1;
+        this.open = this.items.length > 0;
+        this._changed();
+        return this.items;
+    }
+
+    /**
+     * Moves the active highlight up (`-1`) or down (`+1`) in the scrollable list, wrapping around.
+     * From no selection, down goes to the first item and up to the last.
+     */
+    move(delta) {
+        if (!this.open || this.items.length === 0) {
+            this.refresh();
+            return this.selectedIndex;
+        }
+        const len = this.items.length;
+        this.selectedIndex = this.selectedIndex < 0
+            ? (delta > 0 ? 0 : len - 1)
+            : (this.selectedIndex + delta + len) % len;
+        this._changed();
+        return this.selectedIndex;
+    }
+
+    /**
+     * Applies the suggestion at `index` (defaults to `selectedIndex`, or `0`), replacing `value`
+     * with `item.completion` and immediately predicting the next word.
+     */
+    accept(index = this.selectedIndex >= 0 ? this.selectedIndex : 0) {
+        if (index < 0 || index >= this.items.length) return null;
+        const item = this.items[index];
+        this.value = item.completion;
+        this.onComplete?.(item, this);
+        if (this.predict) {
+            this.refresh();
+        } else {
+            this.close();
+        }
+        return item;
+    }
+
+    /** Closes the suggestion popup without changing `value`. */
+    close() {
+        if (!this.open && this.selectedIndex === -1) return;
+        this.open = false;
+        this.selectedIndex = -1;
+        this._changed();
+    }
+
+    /** Submits the current question (`value`), closes the suggestion list, and invokes `onAsk`. */
+    submit(question = this.value) {
+        this.value = String(question ?? '');
+        this.open = false;
+        this.selectedIndex = -1;
+        const trimmed = this.value.trim();
+        if (trimmed && this.history.at(-1) !== trimmed) {
+            this.history.push(trimmed);
+        }
+        this._changed();
+        return this.onAsk?.(this.value, this);
+    }
+
+    _changed() {
+        this.onChange?.(this);
+    }
+
+    /** Normalizes a string or suggestion object into `{ display, completion, sense, reference, relation, kind }`. */
+    static normalizeItem(item, currentText = '') {
+        if (typeof item === 'string') {
+            return {
+                display: item,
+                completion: AskView._completeWord(currentText, item),
+                sense: null,
+                reference: null,
+                relation: null,
+                kind: 'suggestion',
+            };
+        }
+        const display = String(item.display ?? item.word ?? item.label ?? item.completion ?? '');
+        const completion = item.completion !== undefined
+            ? String(item.completion)
+            : AskView._completeWord(currentText, display);
+        return {
+            display,
+            completion,
+            sense: item.sense ?? null,
+            reference: item.reference ?? null,
+            relation: item.relation ?? null,
+            kind: item.kind ?? 'suggestion',
+        };
+    }
+
+    /** Replaces the trailing partial token of `currentText` with `word` (followed by a space). */
+    static _completeWord(currentText, word) {
+        const text = String(currentText ?? '');
+        if (word.includes(' ') && word.toLowerCase().startsWith(text.trim().toLowerCase()) && text.trim().length > 0) {
+            return word;
+        }
+        const match = text.match(/^(.*?)(\S*)$/);
+        const prefix = match ? match[1] : '';
+        const cleanWord = String(word).trim();
+        return `${prefix}${cleanWord} `;
+    }
+
+    /**
+     * Builds a context-aware next-word predictor from declarative cube/table metadata and/or
+     * sample questions. Predicts metrics, dimensions, clauses (`by`, `and`, `where`, `top`, `vs`),
+     * sampled dimension members after `=`, and learned next-word bigrams from `sampleQuestions`.
+     */
+    static nextWordPredictor({
+        measures = [],
+        dimensions = [],
+        members = null,
+        vocabulary = [],
+        sampleQuestions = [],
+    } = {}) {
+        const catalog = [];
+        const addEntry = (display, kind, sense = null, reference = null, relation = null) => {
+            if (!display) return;
+            if (catalog.some(c => c.display.toLowerCase() === String(display).toLowerCase() && c.kind === kind)) return;
+            catalog.push({ display: String(display), kind, sense, reference, relation });
+        };
+
+        for (const m of measures) addEntry(m, 'metric', `Measure ${m}`, m, 'canonical');
+        for (const d of dimensions) addEntry(d, 'dimension', `Dimension ${d}`, d, 'canonical');
+        for (const v of vocabulary) {
+            if (typeof v === 'string') addEntry(v, 'term');
+            else addEntry(v.display ?? v.word ?? v.label, v.kind ?? 'term', v.sense ?? null, v.reference ?? null, v.relation ?? null);
+        }
+
+        const keywords = [
+            { display: 'by', kind: 'keyword', sense: 'Group or slice by dimension' },
+            { display: 'and', kind: 'keyword', sense: 'Add another measure or dimension' },
+            { display: 'where', kind: 'keyword', sense: 'Filter by dimension member' },
+            { display: 'top', kind: 'keyword', sense: 'Rank top N members' },
+            { display: '=', kind: 'operator', sense: 'Equals member value' },
+            { display: 'in', kind: 'keyword', sense: 'Match any of several members' },
+            { display: 'vs', kind: 'keyword', sense: 'Compare against another measure or period' },
+            { display: 'descending', kind: 'keyword', sense: 'Sort highest first' },
+            { display: 'ascending', kind: 'keyword', sense: 'Sort lowest first' },
+        ];
+        for (const kw of keywords) addEntry(kw.display, kw.kind, kw.sense);
+
+        // Learn next-word transitions (bigrams) from sampleQuestions.
+        const bigrams = new Map();
+        for (const q of sampleQuestions) {
+            const tokens = String(q).trim().split(/\s+/).filter(Boolean);
+            for (let i = 0; i < tokens.length - 1; i++) {
+                const prev = tokens[i].replace(/,+$/, '').toLowerCase();
+                const next = tokens[i + 1].replace(/,+$/, '');
+                if (!bigrams.has(prev)) bigrams.set(prev, new Set());
+                bigrams.get(prev).add(next);
+                addEntry(tokens[i].replace(/,+$/, ''), 'term');
+            }
+            if (tokens.length > 0) addEntry(tokens.at(-1).replace(/,+$/, ''), 'term');
+        }
+
+        const getMembers = (dim) => {
+            if (!dim || !members) return [];
+            if (typeof members === 'function') return members(dim) ?? [];
+            const foundKey = Object.keys(members).find(k => k.toLowerCase() === dim.toLowerCase());
+            return foundKey ? members[foundKey] ?? [] : [];
+        };
+
+        return (text) => {
+            const raw = String(text ?? '');
+            const match = raw.match(/^(.*?)(\S*)$/);
+            const before = match ? match[1] : '';
+            const partial = (match ? match[2] : '').toLowerCase();
+            const priorTokens = before.trim().split(/\s+/).filter(Boolean);
+            const lastToken = (priorTokens.at(-1) ?? '').replace(/,+$/, '').toLowerCase();
+            const prevToken = (priorTokens.at(-2) ?? '').replace(/,+$/, '').toLowerCase();
+
+            const results = [];
+            const push = (entry, bonus = 0) => {
+                const word = String(entry.display);
+                if (partial && !word.toLowerCase().startsWith(partial)) return;
+                if (results.some(r => r.display.toLowerCase() === word.toLowerCase())) return;
+                results.push({
+                    display: word,
+                    completion: AskView._completeWord(raw, word),
+                    sense: entry.sense ?? null,
+                    reference: entry.reference ?? null,
+                    relation: entry.relation ?? null,
+                    kind: entry.kind ?? 'suggestion',
+                    _score: bonus + (word.toLowerCase() === partial ? 0 : 10),
+                });
+            };
+
+            // 1. After `<dimension> =`, suggest sampled member values of that dimension.
+            if (lastToken === '=' && prevToken) {
+                const dimName = dimensions.find(d => d.toLowerCase() === prevToken) ?? prevToken;
+                for (const val of getMembers(dimName)) {
+                    push({
+                        display: String(val),
+                        kind: 'value',
+                        sense: `Member of ${dimName}`,
+                        reference: `${dimName} = ${val}`,
+                    }, 100);
+                }
+            }
+
+            // 2. Context-sensitive grammar transitions.
+            if (!lastToken) {
+                for (const c of catalog.filter(e => e.kind === 'metric')) push(c, 80);
+                for (const c of catalog.filter(e => e.display === 'top')) push(c, 70);
+                for (const c of catalog.filter(e => e.kind === 'dimension')) push(c, 60);
+            } else if (lastToken === 'by' || lastToken === 'where') {
+                for (const c of catalog.filter(e => e.kind === 'dimension')) push(c, 90);
+            } else if (lastToken === 'and') {
+                const inByClause = priorTokens.some(t => t.toLowerCase() === 'by');
+                for (const c of catalog.filter(e => e.kind === (inByClause ? 'dimension' : 'metric'))) push(c, 90);
+                for (const c of catalog.filter(e => e.kind === (inByClause ? 'metric' : 'dimension'))) push(c, 70);
+            } else if (dimensions.some(d => d.toLowerCase() === lastToken)) {
+                const inWhere = priorTokens.some(t => t.toLowerCase() === 'where');
+                if (inWhere) {
+                    for (const c of catalog.filter(e => e.display === '=')) push(c, 95);
+                } else {
+                    for (const c of catalog.filter(e => ['and', 'where', 'descending', 'ascending'].includes(e.display))) push(c, 85);
+                }
+            } else if (measures.some(m => m.toLowerCase() === lastToken)) {
+                for (const c of catalog.filter(e => ['by', 'and', 'where', 'vs'].includes(e.display))) push(c, 90);
+            }
+
+            // 3. Learned bigram transitions from sample questions.
+            if (lastToken && bigrams.has(lastToken)) {
+                for (const nextWord of bigrams.get(lastToken)) {
+                    const existing = catalog.find(c => c.display.toLowerCase() === nextWord.toLowerCase());
+                    push(existing ?? { display: nextWord, kind: 'next word', sense: `Follows "${lastToken}"` }, 88);
+                }
+            }
+
+            // 4. All remaining catalog entries matching the partial prefix.
+            for (const c of catalog) push(c, 20);
+
+            return results
+                .sort((a, b) => b._score - a._score)
+                .map(({ _score, ...rest }) => rest);
+        };
+    }
+}