@peter.prib/renderengine 0.12.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` |
@@ -1057,7 +1057,10 @@ types — see `ARCHITECTURE.md`):
 
   **In the workbench:** `DataModelPart` (type `data-model`, `RenderEngineWorkspace.DataModelPart`) shows one
   model: File ▸ Open…, Save, Save As… (Ctrl+O, Ctrl+S; `part.file`, the `ModelFile` editors use, • while changed,
-  asking before the page is left with changes unsaved), and hosted by a `ModelsPart` (`editorType: 'data-model'`)
+  asking before the page is left with changes unsaved), File ▸ **Import from pasted text (.datamodel.json)…** (a model from
+  pasted text rather than a file: a file's contents, or an assistant's answer or a page with the JSON in a ``` block
+  or between other words, found by `findPayload(format, text)`; `askPasteImport(format, { onImport })`; every
+  `ModelHosted` part offers it for its text formats, `part.pasteItems()`; it opens as Open… does), and hosted by a `ModelsPart` (`editorType: 'data-model'`)
   New ▸ (New model, From base: …), Duplicate model, Close model and This browser ▸ (with `keep`: kept in this browser
   as it changes, reopened next time, backed up to a folder chosen once, as the modeller's models are); Edit ▸ Undo
   and Redo; Tools ▸ Compare with and Merge from (the other open models and the bases; a merge is one undo step); Model ▸ New / Edit / Delete perspective and context (those dialogs), Perspective and Context selects (when
@@ -1081,6 +1084,13 @@ this to `line`/`area`/`stackedBar`/etc. is the same three-line change: call
 `this._drawYAxisTicks(x, y, width, height, rawMax)` before drawing marks, and scale against its
 return value instead of the raw max — not done yet for the rest, tracked as a follow-up.
 
+**Negative values.** `bar` and `groupedBar` (and so `pivotChart`, which charts through the grouped
+bar) take in the smallest value as well as the largest: when one is negative the axis goes below zero
+on one common step (`Axis.niceRange(min, max)`, drawn by `Axis.drawYRange`), a zero line is drawn
+across the plot where it crosses, and a negative bar hangs down from it, its value written below it.
+Money signed both ways (income positive, spending negative) charts as it is, and a total over both is
+the net. Without a negative value nothing changes: the axis starts at 0 at the bottom.
+
 ### Choosing a chart for result rows — `ChartChooser`
 
 `new ChartChooser().choose(rows, columns?, { complete? })` says which chart types fit a set of result rows (a query
@@ -1138,6 +1148,7 @@ const view = new RenderEngine(container, { rendererType: 'svg' }).resultView(row
     pageSize: 50,
     menus: { row: ({ row }) => [{ label: 'Open order', action: () => open(row.id) }] },
     highlight: (row) => row.id === selectedId,   // rows drawn highlighted: the host's selection
+    format: { Revenue: new Intl.NumberFormat('en-AU', { style: 'currency', currency: 'AUD' }) },
 });
 ```
 
@@ -1159,6 +1170,12 @@ or `chartHeight`, 360); pass `fitHeight: false` to size it yourself. A host adds
 any menu with `menus: { cell, row, column, table }`, each `(context) → PopupMenu items`, shown after
 a separator.
 
+**Number format.** `format` says how numbers show: a function (number → text) or an
+`Intl.NumberFormat` for every number, or an object naming either per column, where a column it does
+not name stays plain (116028; a fraction to at most 4 decimals). Only the cells' text changes: sorting
+and filtering use the values, and every copy (the table, a column, a row, a value) keeps the raw
+numbers, so a pasted copy still adds up. `pivotView` takes the same `format`, per measure.
+
 Interaction needs the SVG renderer (its shapes take clicks); on canvas the same table is drawn
 without it. `TableView` (`src/charting/table/TableView.js`) holds all of the state and builds every
 menu as data, so it can be driven and tested without a DOM; `TableViewChart` draws it.
@@ -1211,6 +1228,10 @@ grid, as `resultView`'s does. `PivotView` (`src/charting/pivot/`) holds all the
 menus as data, so it can be tested without a DOM; `PivotGridChart` draws it, with the interactive
 table's click handling (SVG for clicks; canvas draws the grid without them).
 
+`format` (as `resultView`'s, per measure: `{ Revenue: new Intl.NumberFormat(…) }`, or one for every
+measure) writes the cells, the totals and the traffic lights' cut-offs ("Revenue ≥ $3,000.00"); the
+grid copy keeps the raw numbers.
+
 #### Saved views
 
 A saved view is plain data: the layout (`view.layout()`) and how the grid shows it
@@ -2098,8 +2119,32 @@ colour by, then a colour for each of its values (a soft palette by default, `Dia
 colour" leaves a value's shapes as they are), and whether to add a legend. Each shape takes its value's colour as
 its own fill, so the colours are kept like any other (an Archi file included), and one undo puts them back. The
 template editor colours by the kind of shape; the ArchiMate canvas by **Layer**, **Type**, **Specialization** or any
-**property** its elements have (notes and pictures have no value and stay as they are). A legend is a title and a
-box per value in its colour, in a row under the drawing (notes; on a canvas, stickies). **Add legend of the kinds
+**property** its elements have (notes and pictures have no value and stay as they are), and two more:
+
+- **Change (create, update, delete)**, offered when the model has a deliverable or work package: each element related
+  to one (either way round) takes the change the relationship's name says, or, when the relationship has no name, the
+  deliverable's or work package's name. Synonyms count, in any form: delete, remove, retire, decommission, drop,
+  sunset, phase out, shut down, …; create, add, new, introduce, build, implement, set up, launch, …; update, change,
+  modify, upgrade, enhance, migrate, replace, … (`CHANGE_WORDS`, whole words only). Where an element is given more
+  than one, the one with most consequence wins: delete, then create, then update. The colours offered are
+  **Create** yellow #FDD835, **Update** blue #1E88E5 and **Delete** magenta #D81B60 (`CHANGE_COLOURS`), each still
+  changeable (`changeAction(text)`, `elementChange(model, elementId)`). The lines are coloured too: each relationship
+  to a deliverable or work package is drawn in the colour of the change it says itself (`relationshipChange(model,
+  rel)`), so an element changed two ways shows both on its lines; other lines keep their colour. Lines only drawn
+  (derived ones) are left as they are (`editor.colourEdgeValue(edge, key)`, which a subclass overrides to colour
+  lines by a key).
+- **A formula over properties…**, offered when elements have properties: a number from each element's numeric
+  properties, in the formula language `colorCol` uses (`kernelExpr.js`: arithmetic, comparisons, `a ? b : c`,
+  maths functions), each property by its name with anything but letters, digits and _ made _ ("Risk score" is
+  `Risk_score`), e.g. `Cost * Risk_score` or `Cost > 10000 ? 1 : 0`. A formula naming no property is refused
+  with what the names are. An element without a number for a property the formula uses is left as it is. Up to
+  eight different results are each a value; more are put in five equal bands, smallest first (a band with nothing in
+  it left out), and the colours offered run light to dark (`expressionValues`, `resultBands`,
+  `sequentialColours`; the key is `expression:<formula>`).
+
+A legend is a box under the
+drawing, titled at its top-left, holding a box per value in its colour (in rows of up to four,
+`DiagramEditor.legendLayout`), all grouped so they move as one (notes; on a canvas, stickies). **Add legend of the kinds
 shown** adds one for the kinds of shape (ArchiMate: the element types) in the colour of each's first shape. A
 locked shape keeps its colour. `colourKeys()`, `colourValue(template, key)`, `colourValues(key)`,
 `colourByCommand(key, colours, { legend })`, `kindLegendEntries()` and `legendCommand(entries, title)`, which a
@@ -2224,7 +2269,23 @@ label shown, in the same box (or none), with the same lines drawn (each relation
 thing at the other end), as one undo step with its lines (`view.repeatedBoxes()`, `editor.removeRepeatedBoxes()`).
 The first box stays; a box holding others is never taken off. The **File** menu (`EditorPart`'s, and the ArchiMate editor's) exports the current view
 as an image: PNG, SVG or a copy to the clipboard (`editor.exportImage('png' | 'svg' | 'copy')`, without the grid
-or selection; the ArchiMate editor's is off with `features.exportImage: false`). **Generate View For This**, on
+or selection; the ArchiMate editor's is off with `features.exportImage: false`), and so does a right-click on empty
+canvas (**Export image**, `editor.canvasContextMenu(at)`). By default a picture takes in **the whole drawing**,
+wherever the view is scrolled: every shape and line, line labels and arrowheads included, with 20px clear all round
+so nothing touches the edge (`editor.drawingBounds({ margin })`), at **100%**. **Export image…** asks the format,
+the area (the whole drawing, or only what is in sight) and the scale in percent, and the quick items use its last
+choice (`editor.exportOptions`, `setExportOptions({ area, scale })`; `exportImage(format, { area, scale })`).
+**⚙ Settings ▸ Export area** shows where the whole drawing's picture ends as a faint dashed box, never itself
+exported (`editor.showExportArea`). An SVG cropped to a viewBox keeps a white background over all of it.
+
+**🗑 Delete from model…**, on an element's menu in the tree and on its box's menu in the diagram (the elements
+selected, when it is one of them), takes it out of the model rather than off one view, as Archi's "Delete from
+Model". First a dialog says where it is used: each view it is on (with how many boxes), and each relationship that
+goes too (those ending on it, and those ending on such a relationship); **Delete from model** goes ahead. Every
+box and line of them goes from every view, with any view's own connection to one of its boxes, as one undo step
+that puts it all back, ids and all (`model.usage(elementIds)`, `model.deleteFromModelCommand(elementIds)`,
+`editor.askDeleteFromModel(ids)` / `deleteFromModel(ids)`, `deleteFromModelMessage(model, ids)`;
+`elementMenuItems` offers it when the host gives `deleteFromModel`). **Generate View For This**, on
 an element's menu in the diagram or the tree, makes a view of the element with everything related to it
 around it and every relationship between them (`model.generateView(elementIds, { name, related })`, Archi's
 "Generate View For").
@@ -2587,7 +2648,7 @@ single list of cascading properties:
 | Key | Values (default first) |
 |---|---|
 | `routing` | `straight`, `orthogonal`, `curved`, `polyline` (bends around other shapes) |
-| `attach` | `floating` (outline, aimed at the other end), `sides` (middle of the facing side) |
+| `attach` | `shortest` (the default, as Archi draws: where two shapes face each other across a gap with their widths or heights overlapping, a straight line straight across the middle of the overlap, outline to outline; otherwise as `floating`), `floating` (outline, aimed at the other end), `sides` (middle of the facing side). `shortest` leaves a line with bends, a pinned end, routing other than straight, or a rotated shape as `floating` draws it |
 | `lineStyle` | `solid`, `dashed`, `dotted` (same dash patterns as `GraphDiagram`, via `LINE_STYLE_DASH`) |
 | `strokeColor`, `strokeWidth` | `#666666`, `2` |
 | `startMarker`, `endMarker` | `none`, or an `EdgeMarker` key |
@@ -3221,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.12.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/Axis.js

@@ -27,6 +27,30 @@ export class Axis {
         return ticks;
     }
 
+    /**
+     * Ticks over a range that may go below zero: one common "nice" step, from at or below `minVal`
+     * to at or above `maxVal`, always taking in 0 so bars have a baseline. Without a negative it is
+     * `niceTicks(maxVal)`.
+     * @param {number} minVal
+     * @param {number} maxVal
+     * @param {number} [count=4] desired number of intervals
+     * @returns {number[]}
+     */
+    static niceRange(minVal, maxVal, count = 4) {
+        const lo = Math.min(0, minVal || 0);
+        const hi = Math.max(0, maxVal || 0);
+        if (lo === 0) return Axis.niceTicks(hi, count);
+        const raw = (hi - lo) / count;
+        const mag = Math.pow(10, Math.floor(Math.log10(raw)));
+        const frac = raw / mag;
+        const step = frac < 1.5 ? mag : frac < 3.5 ? 2 * mag : frac < 7.5 ? 5 * mag : 10 * mag;
+        const first = Math.floor(lo / step + 1e-9);
+        const last = Math.ceil(hi / step - 1e-9);
+        const ticks = [];
+        for (let i = first; i <= last; i++) ticks.push(parseFloat((i * step).toFixed(10)));
+        return ticks;
+    }
+
     /**
      * How often a category label fits along an axis `width` wide: 1 (every
      * label), 2 (every other), … — so a long series (a minute of samples, a
@@ -71,18 +95,36 @@ export class Axis {
      * @returns {number} the nice domain max the ticks actually span
      */
     drawYAxis(renderer, box, rawMax) {
-        const ticks = Axis.niceTicks(rawMax);
-        const niceMax = ticks[ticks.length - 1] || 1;
+        return this.drawYRange(renderer, box, 0, rawMax).max;
+    }
+
+    /**
+     * Draw a y-axis over a range that may go below zero (`niceRange`): ticks, labels, gridlines,
+     * and, when the range does go below zero, a zero line across the plot where it crosses.
+     *
+     * @param {*} renderer a renderer implementing .path() and .text()
+     * @param {{x:number, y:number, width:number, height:number}} box plot-area box
+     * @param {number} rawMin the raw data minimum (0 or more: the axis starts at 0)
+     * @param {number} rawMax the raw data maximum
+     * @returns {{min:number, max:number}} the nice domain the ticks actually span
+     */
+    drawYRange(renderer, box, rawMin, rawMax) {
+        const ticks = Axis.niceRange(rawMin, rawMax);
+        const min = ticks[0];
+        const max = ticks.length > 1 ? ticks[ticks.length - 1] : 1;
+        const yOf = (v) => box.y + box.height - ((v - min) / (max - min)) * box.height;
         for (const t of ticks) {
-            const ty = box.y + box.height - (t / niceMax) * box.height;
+            const ty = yOf(t);
             renderer.path(`M${box.x - 5},${ty} L${box.x},${ty}`, 'none', { color: '#999', width: 1 });
-            if (t > 0) {
+            if (t !== 0) {
                 renderer.path(`M${box.x},${ty} L${box.x + box.width},${ty}`, 'none', { color: '#eee', width: 1 });
+            } else if (min < 0) {
+                renderer.path(`M${box.x},${ty} L${box.x + box.width},${ty}`, 'none', { color: '#666', width: 1, zeroLine: true });
             }
             renderer.text(Axis.formatValue(t), box.x - 10, ty, {
                 textAnchor: 'end', verticalAlign: 'middle', fontSize: '10px', fill: '#666',
             });
         }
-        return niceMax;
+        return { min, max };
     }
 }

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);