@peter.prib/renderengine 0.12.0 → 0.14.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);
+        };
+    }
+}

package/src/charting/charts/AreaChart.js

@@ -16,8 +16,10 @@ export class AreaChart extends Chart {
         const box = ChartBox.fromRenderer(this.renderer);
         const {
             x = box.x, y = box.y, width = box.width, height = box.height,
-            colors, title, xAxisLabel, yAxisLabel, stacked = false, legend: showLegend = false,
+            colors, title, xAxisLabel, yAxisLabel, stacked = false,
+            normalize = false, stackMode, legend: showLegend = false,
         } = options;
+        const isPercent = Boolean(stacked && (normalize || stackMode === 'percent'));
         const plotBox = { x, y, width, height };
         const isMultiline = Array.isArray(data[0]?.values);
         const series = isMultiline ? data : [{ name: 'default', values: data }];
@@ -26,6 +28,10 @@ export class AreaChart extends Chart {
         const palette = new ColorPalette(colors);
         const textAnchor = this.renderer.centerTextAnchor;
 
+        const pointTotals = isPercent
+            ? Array.from({ length: pointCount }, (_, i) => series.reduce((sum, s) => sum + Math.max(0, s.values[i]?.value ?? 0), 0))
+            : null;
+
         // Precompute each series' [base, top] band per point — base is 0
         // unless stacked, in which case it's the running cumulative of prior
         // series (computed once here, not re-derived during render).
@@ -33,12 +39,15 @@ export class AreaChart extends Chart {
         const bands = series.map(s => {
             const band = s.values.map((d, i) => {
                 const base = stacked ? running[i] : 0;
-                return { base, top: base + d.value };
+                const val = isPercent
+                    ? (pointTotals[i] > 0 ? (Math.max(0, d.value) / pointTotals[i]) * 100 : 0)
+                    : d.value;
+                return { base, top: base + val, pct: val };
             });
             if (stacked) running = band.map(b => b.top);
             return band;
         });
-        const maxValue = Math.max(...bands.flat().map(b => b.top)) || 1;
+        const maxValue = isPercent ? 100 : (Math.max(...bands.flat().map(b => b.top)) || 1);
 
         new ChartLabels({ title, xAxisLabel, yAxisLabel }).draw(this.renderer, plotBox);
         this.renderer.path(`M${x},${y} L${x},${y + height} L${x + width},${y + height}`, 'none', { color: 'black', width: 1 });
@@ -53,6 +62,14 @@ export class AreaChart extends Chart {
             const { r, g, b: bl } = palette.hexToRgb(color);
             this.renderer.path(areaPath, `rgba(${r},${g},${bl},0.35)`, null, { tooltip: s.name });
             this.renderer.path('M' + topPts.map(p => `${p.px},${p.py}`).join(' L'), 'none', { color, width: 2 });
+            if (typeof this.renderer.circle === 'function') {
+                topPts.forEach((p, i) => {
+                    const d = s.values[i];
+                    this._datum(this.renderer.circle(p.px, p.py, 3, color, { color: '#fff', width: 1 }, {
+                        tooltip: `${isMultiline ? s.name + ': ' : ''}${d.label}: ${d.value}`,
+                    }), { label: d.label, series: isMultiline ? s.name : null });
+                });
+            }
 
             if (seriesIndex === 0) {
                 const step = Axis.categoryLabelStep(s.values.map(d => d.label), width, { fontSize: 10 });

package/src/charting/charts/BarChart.js

@@ -17,7 +17,7 @@ export class BarChart extends BarChartBase {
     _computeMaxValue() {
         const data = this.data;
         const rawMax = Math.max(...data.map(d => d.value)) || 1;
-        return this._drawYAxis(rawMax);
+        return this._drawYAxis(rawMax, Math.min(0, ...data.map(d => d.value)));
     }
 
     _beforeBars(maxValue) {
@@ -39,12 +39,12 @@ export class BarChart extends BarChartBase {
             }
 
             const color = colors ? this._palette.colorAt(i) : barColor;
-            const barHeight = (d.value / maxValue) * height;
+            const bar = this._barSpan(d.value);
             const barX = x + i * (bandWidth + margin);
-            const barY = y + height - barHeight;
 
-            this._datum(this.renderer.rect(barX, barY, bandWidth, barHeight, color, null, { bar: true, dataIndex: i, tooltip: `${d.label}: ${d.value}` }), { label: d.label });
-            this.renderer.text(String(d.value), barX + bandWidth / 2, barY - 5, { textAnchor, fontSize: '10px', fill: '#333' });
+            this._datum(this.renderer.rect(barX, bar.top, bandWidth, bar.height, color, null, { bar: true, dataIndex: i, tooltip: `${d.label}: ${d.value}` }), { label: d.label });
+            // The value just past the bar's end: above a bar going up, below one going down.
+            this.renderer.text(String(d.value), barX + bandWidth / 2, d.value < 0 ? bar.end + 12 : bar.end - 5, { textAnchor, fontSize: '10px', fill: '#333' });
             if (i % labelStep === 0) this.renderer.text(d.label, barX + bandWidth / 2, y + height + 20, { textAnchor });
         });
     }

package/src/charting/charts/BarChart3D.js

@@ -34,12 +34,12 @@ export class BarChart3D extends Chart {
             const barBaseY = y + height;
             const color = palette.colorAt(i);
 
-            this.renderer.rect(
+            this._datum(this.renderer.rect(
                 barX, barBaseY - barHeight, barWidth, barHeight,
                 color,
                 { color: '#333', width: 1 },
                 { tooltip: `${d.label}: ${d.value}` },
-            );
+            ), { label: d.label });
 
             // Top face
             const topPath = `M${barX},${barBaseY - barHeight} L${barX + barWidth},${barBaseY - barHeight} L${barX + barWidth + depth},${barBaseY - barHeight - depth} L${barX + depth},${barBaseY - barHeight - depth} Z`;

package/src/charting/charts/BarChart3DOrbit.js

@@ -40,7 +40,9 @@ export class BarChart3DOrbit extends Chart3D {
         }).sort((a, b) => b.depth - a.depth);
 
         for (const bar of bars) {
-            this.drawBox(this.renderer, bar.x0, bar.x1, 0, bar.y1, bar.z0, bar.z1, bar.color, toScreen);
+            this.drawBox(this.renderer, bar.x0, bar.x1, 0, bar.y1, bar.z0, bar.z1, bar.color, toScreen, {
+                label: bar.d.x, series: bar.d.z, x: bar.d.x, z: bar.d.z,
+            });
         }
 
         new Legend({

package/src/charting/charts/BarChartBase.js

@@ -38,9 +38,27 @@ export class BarChartBase extends Chart {
         this.renderer.path(`M${x},${y} L${x},${y + height} L${x + width},${y + height}`, 'none', { color: 'black', width: 1 });
     }
 
-    /** Draw a Y axis and return the nice-rounded max value. */
-    _drawYAxis(rawMax) {
-        return new Axis().drawYAxis(this.renderer, this._plotBox, rawMax);
+    /**
+     * Draw a Y axis and return the nice-rounded max value. With a negative `rawMin` the axis goes
+     * below zero, with a zero line; `_barSpan` then draws each bar from zero, up or down.
+     */
+    _drawYAxis(rawMax, rawMin = 0) {
+        this._domain = new Axis().drawYRange(this.renderer, this._plotBox, rawMin, rawMax);
+        return this._domain.max;
+    }
+
+    /**
+     * Where a bar of `value` goes on the axis `_drawYAxis` drew: from the zero line up to it, or
+     * down to it when negative.
+     * @returns {{top: number, height: number, end: number}} `end` is the bar's far end from zero
+     */
+    _barSpan(value) {
+        const { y, height } = this._plotBox;
+        const { min, max } = this._domain;
+        const yOf = (v) => y + height - ((v - min) / (max - min)) * height;
+        const zero = yOf(0);
+        const end = yOf(value);
+        return { top: Math.min(zero, end), height: Math.abs(end - zero), end };
     }
 
     _render() {

package/src/charting/charts/BoxPlotChart.js

@@ -30,9 +30,9 @@ export class BoxPlotChart extends GroupedDistributionChart {
         this.renderer.path(`M${cx - boxWidth / 4},${this._toY(s.min)} L${cx + boxWidth / 4},${this._toY(s.min)}`, 'none', { color: '#555', width: 1 });
         this.renderer.path(`M${cx - boxWidth / 4},${this._toY(s.max)} L${cx + boxWidth / 4},${this._toY(s.max)}`, 'none', { color: '#555', width: 1 });
         const boxTop = this._toY(s.q3), boxBottom = this._toY(s.q1);
-        this.renderer.rect(cx - boxWidth / 2, boxTop, boxWidth, Math.max(1, boxBottom - boxTop), boxColor, { color: '#333', width: 1 }, {
+        this._datum(this.renderer.rect(cx - boxWidth / 2, boxTop, boxWidth, Math.max(1, boxBottom - boxTop), boxColor, { color: '#333', width: 1 }, {
             tooltip: `${d.label}: median ${Axis.formatValue(s.median)}, Q1 ${Axis.formatValue(s.q1)}, Q3 ${Axis.formatValue(s.q3)}`,
-        });
+        }), { label: d.label, series: d.label });
         this.renderer.path(`M${cx - boxWidth / 2},${this._toY(s.median)} L${cx + boxWidth / 2},${this._toY(s.median)}`, 'none', { color: '#fff', width: 2 });
         s.outliers.forEach(v => {
             this.renderer.circle(cx, this._toY(v), 3, 'none', { color: boxColor, width: 1.5 }, { tooltip: `${d.label} outlier: ${Axis.formatValue(v)}` });

package/src/charting/charts/BubbleChart.js

@@ -83,7 +83,10 @@ export class BubbleChart extends Chart {
                 // 3D effect: draw a line to the "floor"
                 this.renderer.path(`M${floorX},${floorY} L${bubbleX},${bubbleY}`, 'none', { color: '#e0e0e0', width: 1 });
             }
-            this.renderer.circle(bubbleX, bubbleY, radius, color, { color: 'rgba(0,0,0,0.2)', width: 1 }, { tooltip: `${d.label}: (${d.x}, ${d.y}, ${d.z})` });
+            const series = catField ? ChartData.readColorCol(d, catField) : null;
+            this._datum(this.renderer.circle(bubbleX, bubbleY, radius, color, { color: 'rgba(0,0,0,0.2)', width: 1 }, { tooltip: `${d.label}: (${d.x}, ${d.y}, ${d.z})` }), {
+                label: d.label ?? String(d.x), series: series != null ? String(series) : null,
+            });
         });
 
         // Category color legend

package/src/charting/charts/ChordDiagram.js

@@ -92,19 +92,19 @@ export class ChordDiagram extends Chart {
             const c2x = cx + (innerRadius * 0.2) * Math.cos(t.mid);
             const c2y = cy + (innerRadius * 0.2) * Math.sin(t.mid);
             const width = Math.max(1, (l.value / maxLink) * maxStroke);
-            this.renderer.path(`M${sx},${sy} C${c1x},${c1y} ${c2x},${c2y} ${tx},${ty}`, 'none', {
+            this._datum(this.renderer.path(`M${sx},${sy} C${c1x},${c1y} ${c2x},${c2y} ${tx},${ty}`, 'none', {
                 color: s.color, width,
             }, {
                 tooltip: `${s.label} ↔ ${t.label}: ${l.value}`,
-            });
+            }), { label: s.label, series: t.label });
         });
 
         // Draw node arcs.
         nodes.forEach(n => {
             const path = this._arcPath(cx, cy, radius, innerRadius, n.start, n.end);
-            this.renderer.path(path, n.color, { color: '#fff', width: 1 }, {
+            this._datum(this.renderer.path(path, n.color, { color: '#fff', width: 1 }, {
                 tooltip: `${n.label}: ${n.value}`,
-            });
+            }), { label: n.label });
 
             // Label outside the circle.
             const lx = cx + (radius + 16) * Math.cos(n.mid);

package/src/charting/charts/DensityChart.js

@@ -58,7 +58,7 @@ export class DensityChart extends Chart {
             const topPath = 'M' + topPts.map(p => `${p.px},${p.py}`).join(' L');
             const areaPath = topPath + ` L${x + width},${y + height} L${x},${y + height} Z`;
             const { r, g, b } = ColorPalette.hexToRgb(color);
-            this.renderer.path(areaPath, `rgba(${r},${g},${b},0.25)`, null, { tooltip: d.label });
+            this._datum(this.renderer.path(areaPath, `rgba(${r},${g},${b},0.25)`, null, { tooltip: d.label }), { label: d.label, series: d.label });
             this.renderer.path(topPath, 'none', { color, width: 2 });
         });
 

package/src/charting/charts/FunnelChart.js

@@ -38,7 +38,7 @@ export class FunnelChart extends Chart {
             const bottomRight = bottomLeft + bottomWidth;
 
             const path = `M${topLeft},${top} L${topRight},${top} L${bottomRight},${bottom} L${bottomLeft},${bottom} Z`;
-            this.renderer.path(path, palette.colorAt(i), { color: '#fff', width: 1 }, { tooltip: `${d.label}: ${d.value}` });
+            this._datum(this.renderer.path(path, palette.colorAt(i), { color: '#fff', width: 1 }, { tooltip: `${d.label}: ${d.value}` }), { label: d.label });
             this.renderer.text(`${d.label} (${d.value})`, x + width / 2, top + stageHeight / 2, {
                 textAnchor, verticalAlign: 'middle', fontSize: '12px', fill: '#fff', fontWeight: 'bold',
             });

package/src/charting/charts/GroupedBarChart.js

@@ -10,18 +10,17 @@ import { TableChart } from './TableChart.js';
  *   Array<{name: string, values: Array<{label: string, value: number}>}>
  *
  * Each category (`label`) gets a cluster of bars side-by-side, one per series. A value a series does
- * not have (missing, or null) is a gap in its cluster — no bar — never a bar of zero.
+ * not have (missing, or null) is a gap in its cluster — no bar — never a bar of zero. A negative value
+ * is drawn down from a zero line, the axis taking in the smallest value too.
  */
 export class GroupedBarChart extends BarChartBase {
     static chartType = 'groupedBar';
 
     _computeMaxValue() {
         const series = this.data;
-        const rawMax = Math.max(
-            ...series.flatMap(s => s.values.map(v => v.value).filter(v => v != null)),
-            1,
-        );
-        return this._drawYAxis(rawMax);
+        const values = series.flatMap(s => s.values.map(v => v.value).filter(v => v != null));
+        const rawMax = Math.max(...values, 1);
+        return this._drawYAxis(rawMax, Math.min(0, ...values));
     }
 
     _renderBars(maxValue) {
@@ -63,12 +62,11 @@ export class GroupedBarChart extends BarChartBase {
             series.forEach((seriesData, seriesIndex) => {
                 const value = valueBySeriesLabel[seriesIndex].get(label);
                 if (value == null) return;
-                const barHeight = (value / maxValue) * height;
+                const bar = this._barSpan(value);
                 const barX = clusterX + seriesIndex * barWidth + barGap / 2;
-                const barY = y + height - barHeight;
                 const color = this._palette.colorAt(seriesIndex);
 
-                this._datum(this.renderer.rect(barX, barY, finalBarWidth, barHeight, color, null, {
+                this._datum(this.renderer.rect(barX, bar.top, finalBarWidth, bar.height, color, null, {
                     tooltip: `${seriesData.name} — ${label}: ${value}`,
                 }), { label, series: seriesData.name });
             });