@peter.prib/renderengine 0.7.0 → 0.8.0

package/REFERENCE.md

@@ -88,6 +88,7 @@ catalog `key` for you.
 | `treemap` | `treemapChart(data, opts)` | `Array<{label, value?, children?}>` (hierarchical) | squarified layout, palette by top-level branch |
 | `sunburst` | `sunburstChart(data, opts)` | same hierarchical shape as `treemap` | nested rings by depth |
 | `outline` | `outlineChart(data, opts)` | same hierarchical shape as `treemap`/`sunburst` | `onNodeClick`; collapsible indented list |
+| `table` | `tableChart(data, opts)` | `Array<object>` — a row per object, a column per key | `columns` (names or `{key, label?, align?}`), `maxRows`, `nullText` (`'—'`); values exact, numeric columns right-aligned; drawn with the renderer's primitives, so SVG or canvas |
 | `gauge-dial` | `dialGauge(value, opts)` | `number`, `{value, target?}`, or `[{value, label?, color?}]` for a needle each (0–100 unless `min`/`max`) | the gauge options below; `cx`, `cy`, `r`, `thickness`, `startAngle`, `sweep`, `needleColors`; several needles get a legend, the first fills the arc |
 | `gauge-bar` | `barGauge(value, opts)` | `number` or `{value, target?}` (0–100 unless `min`/`max`) | the gauge options below; `x`, `y`, `width`, `height`, `orientation: 'vertical'` |
 | `gauge-arc` | `arcGauge(value, opts)` | `number` or `{value, target?}` | the gauge options below; `cx`, `cy`, `r`, `thickness`, `startAngle`, `sweep` (a half circle by default), `cap` |
@@ -1080,6 +1081,50 @@ 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.
 
+### 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
+answer, a CSV), best first, each with the rows already shaped as that type's `dataShape` — so
+drawing the best one is `engine.renderChartType(best.key, best.data)`. A `table` always fits and is
+always offered, last.
+
+```javascript
+import { RenderEngine, ChartChooser } from '@peter.prib/renderengine';
+
+const rows = [{ Region: 'West', Revenue: 200 }, { Region: 'East', Revenue: 405 }];
+const choices = new ChartChooser().choose(rows, [{ name: 'Region' }, { name: 'Revenue', measure: 'additive' }]);
+// → bar, pie, donut, table — each { key, label, data, reason }
+const [best] = choices;
+new RenderEngine(container).renderChartType(best.key, best.data, { title: best.reason });
+```
+
+`columns` are optional hints, `{ name, kind?, measure? }`: `kind` is `'categorical'`, `'numeric'`
+or `'time'` (without a hint, a column whose values are all numbers is numeric, else categorical);
+`measure` is the data model's measure kind (`'additive'`, `'semi-additive'`, `'non-additive'`).
+`complete: false` says the rows are only part of the answer (a top N, a first page).
+
+| Rows look like | Offered, best first |
+|---|---|
+| one number, one row | `kpi-tile` |
+| one category, one number | `bar`; also `pie`, `donut` when the measure is additive, the rows are complete, no value is negative and there are 2–8 categories |
+| one time column, one number | `line`, `area`, `bar` — in time order |
+| one category, several numbers | `groupedBar`, `line` (a series per number); with time, `line` first |
+| two categories, one number | `groupedBar`, `heatmap`; with a time column, `line` (a line per category) first |
+| anything else | `table` only |
+
+Three rules keep a choice from misleading: only an **additive** measure is offered as shares of a
+whole (a slice of an average or a balance means nothing); only **complete** rows are (three
+customers' slices of a top 3 would claim to be the whole); and a **missing value is never drawn as
+0** — a result with a hole in a series is not offered as series charts (the heatmap, which draws
+only the cells present, still is), and a bar chart simply has no bar for a null.
+
+A table has no axes, so it takes none of a chart's axis margins. `TableChart.heightFor(rowCount,
+{ title?, maxRows? })` is the height it will draw, for sizing its container first.
+
+Every suggestion is checked against the registry the chooser is given (`chartRegistry` by default):
+a type is offered only if the catalog has it and every axis it marks `required` is one the result's
+shape provides, so the catalog stays the single source of truth for what each chart needs.
+
 ## Common options
 
 Not every method takes every option below — the table above calls out what's notable per type —

package/dist/renderengine-workspace.umd.js

@@ -6898,6 +6898,16 @@
         dataShape: 'Array<{label, value?, children?}> — same hierarchical shape as treemap/sunburst (shares _hierarchyValue); drawn as an indented, collapsible list instead of nested rectangles/rings — a branch\'s value is auto-summed from its descendants and shown as a trailing count, a leaf\'s own extra fields (anything beyond label/value/children) shown as trailing descriptive text instead',
         streamShape: 'flat',
       },
+      {
+        key: 'table', label: 'Table', method: 'tableChart', category: '2d',
+        coordSystem: COORD_SYSTEM.CARTESIAN, title: true, legend: false, colorMode: COLOR_MODE.NONE, camera: CAMERA_MODE.NONE,
+        axes: [
+          { role: 'row',   kind: AXIS_KIND.CATEGORICAL, channel: ENCODING_CHANNEL.POSITION_ORDER, required: false },
+          { role: 'value', kind: AXIS_KIND.NUMERIC,     channel: ENCODING_CHANNEL.TEXT_VALUE,     required: false },
+        ],
+        dataShape: 'Array<object> — one row per object, a column per key (options.columns: names or {key, label?, align?}; every key of the first row when absent); values shown exactly as text, numeric columns right-aligned; options.maxRows, options.nullText',
+        streamShape: 'flat',
+      },
       {
         key: 'gauge-dial', label: 'Gauge (Dial)', method: 'dialGauge', category: 'gauge',
         coordSystem: COORD_SYSTEM.RADIAL, title: true, legend: false, colorMode: COLOR_MODE.SINGLE, camera: CAMERA_MODE.NONE,
@@ -17669,6 +17679,330 @@
     OutlineChart.INDENT_W = 18;
     OutlineChart.HIERARCHY_STRUCTURAL_KEYS = new Set(['label', 'value', 'children']);
 
+    /**
+     * TableChart — rows of values as a table: a header row of column names, then one row per record,
+     * numeric columns right-aligned. Drawn with the renderer's primitives like every chart, so it works
+     * under SVG and canvas and needs no DOM table. Values are shown exactly (not an axis's "1.20k"):
+     * a table is where a reader goes for the actual number.
+     */
+    class TableChart extends Chart {
+        static chartType = 'table';
+
+        /** Layout constants for the rows. */
+        static ROW_H = 26;
+        static PAD_X = 8;
+        static HEADER_FILL = '#eef1f6';
+        static STRIPE_FILL = '#f8f9fb';
+        static RULE = { color: '#d9dde4', width: 1 };
+
+        /**
+         * The columns to show: `options.columns` (names, or `{ key, label?, align? }`), else every key of
+         * the first row. A column is right-aligned when every value it holds is a number (or null).
+         */
+        static columns(data, given) {
+            const specs = (given ?? Object.keys(data[0] ?? {})).map(c => (typeof c === 'string' ? { key: c } : { ...c }));
+            return specs.map(c => ({
+                key: c.key,
+                label: c.label ?? c.key,
+                align: c.align ?? (data.length > 0 && data.every(r => r[c.key] == null || typeof r[c.key] === 'number') ? 'end' : 'start'),
+            }));
+        }
+
+        /** The table has no axes, so none of a chart's axis margins: an edge all round, and room for a title. */
+        static margins(title) {
+            return { left: 8, right: 8, top: title ? 50 : 8, bottom: 8 };
+        }
+
+        /**
+         * The height a table of `rowCount` rows needs — header, rows (at most `maxRows`), the "more rows"
+         * line, a title and the edges — so a page can size its container to fit before drawing.
+         */
+        static heightFor(rowCount, { title, maxRows = Infinity } = {}) {
+            const shown = Math.min(rowCount, maxRows);
+            const more = rowCount > shown ? 1 : 0;
+            const { top, bottom } = TableChart.margins(title);
+            return top + (1 + shown + more) * TableChart.ROW_H + bottom;
+        }
+
+        /** A cell's text: a number exactly (to at most 4 decimals), null/undefined as `nullText`. */
+        static cellText(value, nullText = '—') {
+            if (value == null) return nullText;
+            if (typeof value === 'number') return Number.isInteger(value) ? String(value) : String(Number(value.toFixed(4)));
+            if (value instanceof Date) return value.toISOString().slice(0, 10);
+            return String(value);
+        }
+
+        _render() {
+            const data = this.data ?? [];
+            const box = ChartBox.fromRenderer(this.renderer, TableChart.margins(this.options.title));
+            const { x = box.x, y = box.y, width = box.width, title, maxRows = Infinity, nullText = '—' } = this.options;
+            const { ROW_H, PAD_X } = TableChart;
+            const columns = TableChart.columns(data, this.options.columns);
+            const colW = columns.length > 0 ? width / columns.length : width;
+
+            new ChartLabels({ title }).draw(this.renderer, { x, y, width, height: box.height });
+
+            const shown = data.slice(0, maxRows);
+            let top = y;
+            this.renderer.rect(x, top, width, ROW_H, TableChart.HEADER_FILL, null);
+            columns.forEach((c, i) => this._cell(c.label, c, x + i * colW, top, colW, { fontWeight: 'bold', fill: '#333' }));
+            top += ROW_H;
+            this._rule(x, top, width);
+
+            shown.forEach((row, r) => {
+                if (r % 2 === 1) this.renderer.rect(x, top, width, ROW_H, TableChart.STRIPE_FILL, null);
+                columns.forEach((c, i) => this._cell(TableChart.cellText(row[c.key], nullText), c, x + i * colW, top, colW, { fill: '#222' }));
+                top += ROW_H;
+                this._rule(x, top, width);
+            });
+
+            if (data.length > shown.length) {
+                this.renderer.text(`${data.length - shown.length} more row(s) not shown`, x + PAD_X, top + ROW_H / 2, {
+                    textAnchor: 'start', verticalAlign: 'middle', fontSize: '11px', fill: '#888',
+                });
+            }
+        }
+
+        _cell(text, column, left, top, colW, attrs) {
+            const end = column.align === 'end';
+            this.renderer.text(text, end ? left + colW - TableChart.PAD_X : left + TableChart.PAD_X, top + TableChart.ROW_H / 2, {
+                textAnchor: end ? 'end' : 'start', verticalAlign: 'middle', fontSize: '12px', ...attrs,
+            });
+        }
+
+        _rule(x, y, width) {
+            this.renderer.path(`M${x},${y} L${x + width},${y}`, 'none', TableChart.RULE);
+        }
+    }
+
+    /**
+     * ChartChooser — which catalog chart types fit a set of result rows, best first, each with the rows
+     * already shaped as that chart's `dataShape`. A table always fits, so it is always offered, last.
+     *
+     * The caller may describe the columns (hints). `kind` is `'categorical'`, `'numeric'` or `'time'`; a
+     * column with no hint is numeric when every value it holds is a number, else categorical. `measure`
+     * is renderengine's measure kind (`'additive'`, `'semi-additive'`, `'non-additive'`), as a data model
+     * gives it. The hints change the choice: a time column is drawn along a line, and only an additive
+     * measure is offered as shares of a whole (a pie), since a part-of-a-whole slice of an average or a
+     * balance means nothing.
+     *
+     * Every suggestion is checked against CHART_CATALOG: a chart type is offered only when the catalog
+     * has it and every axis it requires is one the result's shape provides — so the catalog stays the
+     * single source of truth for what each chart needs.
+     *
+     *     const [best, ...others] = new ChartChooser().choose(rows, [{ name: 'Day', kind: 'time' }]);
+     *     engine.renderChartType(best.key, best.data, { title: best.label });
+     */
+    class ChartChooser {
+        /** @param {ChartRegistry} [registry] — the built-in chart types, or another registry to choose from */
+        constructor(registry = chartRegistry) {
+            this.registry = registry;
+        }
+
+        /**
+         * @param {Array<object>} rows
+         * @param {Array<{name:string, kind?:string, measure?:string}>} [columns] — hints; every key of the
+         *   first row when absent, in that order
+         * @param {{complete?:boolean}} [options] — `complete: false` when the rows are only part of the
+         *   answer (a top N, a first page): then nothing is offered as shares of a whole, since the
+         *   slices would claim to be all of it
+         * @returns {Array<{key:string, label:string, data:*, reason:string}>} best first; the table last
+         */
+        choose(rows, columns = null, { complete = true } = {}) {
+            const described = ChartChooser.describe(rows, columns);
+            const shape = RESULT_SHAPES.map(S => S.of(described, rows)).find(s => s !== null) ?? null;
+            if (shape !== null) shape.complete = complete;
+            const charts = shape === null ? [] : shape.candidates()
+                .filter(({ key }) => this.fits(key, shape))
+                .map(({ key, reason, data }) => ({ key, label: this.registry.get(key).label, data, reason }));
+            return [...charts, this.table(rows, described, charts.length === 0)];
+        }
+
+        /** A catalog entry fits a shape when every axis it requires is one the shape provides. */
+        fits(key, shape) {
+            const entry = this.registry.get(key);
+            if (!entry) return false;
+            if (shape.needsSeries && !entry.seriesCapable && !entry.axes.some(a => a.role === 'series')) return false;
+            return entry.axes.filter(a => a.required).every(a => shape.provides[a.role] === a.kind);
+        }
+
+        table(rows, described, only) {
+            return {
+                key: 'table', label: this.registry.get('table')?.label ?? 'Table',
+                data: rows, columns: described.map(c => c.name),
+                reason: only ? 'no chart fits these columns' : 'every value, exactly',
+            };
+        }
+
+        /** The columns with their kinds settled: the hint's, else derived from the rows' values. */
+        static describe(rows, columns) {
+            const given = columns ?? Object.keys(rows[0] ?? {}).map(name => ({ name }));
+            return given.map(c => ({
+                name: c.name,
+                kind: c.kind ?? (rows.length > 0 && rows.every(r => r[c.name] == null || typeof r[c.name] === 'number') ? 'numeric' : 'categorical'),
+                measure: c.measure ?? null,
+            }));
+        }
+    }
+
+    /** The label a category value is drawn with. */
+    function label(value) {
+        return value == null ? '—' : value instanceof Date ? value.toISOString().slice(0, 10) : String(value);
+    }
+
+    /** Rows in time order by `column` (numbers, dates and ISO strings all sort correctly this way). */
+    function inOrder(rows, column) {
+        return [...rows].sort((a, b) => (a[column] < b[column] ? -1 : a[column] > b[column] ? 1 : 0));
+    }
+
+    /**
+     * ResultShape — what a result's columns look like: how many category, time and numeric columns.
+     * Each subclass recognises one shape (`static of`), says which catalog axes it provides, and lists
+     * the chart types that suit it, best first, with the rows shaped for each.
+     */
+    class ResultShape {
+        constructor() {
+            /** Whether the rows are all of the answer (ChartChooser.choose's `complete`). */
+            this.complete = true;
+        }
+
+        /** The axes this shape can fill, role → AXIS_KIND. */
+        get provides() { return {}; }
+        /** Whether a chart must draw several series (one per numeric column). */
+        get needsSeries() { return false; }
+        /** @returns {Array<{key, reason, data}>} */
+        candidates() { return []; }
+
+        static split(columns) {
+            return {
+                categories: columns.filter(c => c.kind !== 'numeric'),
+                numbers: columns.filter(c => c.kind === 'numeric'),
+            };
+        }
+    }
+
+    /** One number and nothing to group it by: a single figure. */
+    class SingleFigure extends ResultShape {
+        static of(columns, rows) {
+            const { categories, numbers } = ResultShape.split(columns);
+            return categories.length === 0 && numbers.length === 1 && rows.length === 1 ? new SingleFigure(numbers[0], rows) : null;
+        }
+        constructor(number, rows) { super(); this.number = number; this.rows = rows; }
+        get provides() { return { value: AXIS_KIND.NUMERIC }; }
+        candidates() {
+            return [{ key: 'kpi-tile', reason: 'a single figure', data: { value: this.rows[0][this.number.name] } }];
+        }
+    }
+
+    /** One category (or time) column and one number: a value per category. */
+    class CategoryValue extends ResultShape {
+        static of(columns, rows) {
+            const { categories, numbers } = ResultShape.split(columns);
+            return categories.length === 1 && numbers.length === 1 ? new CategoryValue(categories[0], numbers[0], rows) : null;
+        }
+        constructor(category, number, rows) { super(); this.category = category; this.number = number; this.rows = rows; }
+        get provides() { return { category: AXIS_KIND.CATEGORICAL, value: AXIS_KIND.NUMERIC }; }
+
+        candidates() {
+            const { category, number } = this;
+            const time = category.kind === 'time';
+            const rows = time ? inOrder(this.rows, category.name) : this.rows;
+            const data = rows.filter(r => r[number.name] != null).map(r => ({ label: label(r[category.name]), value: r[number.name] }));
+            if (time) {
+                return [
+                    { key: 'line', reason: `${number.name} over ${category.name}`, data },
+                    { key: 'area', reason: `${number.name} over ${category.name}, filled`, data },
+                    { key: 'bar', reason: `${number.name} for each ${category.name}`, data },
+                ];
+            }
+            const options = [{ key: 'bar', reason: `${number.name} for each ${category.name}`, data }];
+            if (this.isShareOfWhole(data)) {
+                options.push({ key: 'pie', reason: `each ${category.name}'s share of the total ${number.name}`, data });
+                options.push({ key: 'donut', reason: `each ${category.name}'s share of the total ${number.name}`, data });
+            }
+            return options;
+        }
+
+        /**
+         * Shares of a whole make sense only for an additive measure, over all of the rows (not a top N),
+         * with no negatives, in few slices.
+         */
+        isShareOfWhole(data) {
+            return this.complete && this.number.measure === 'additive' && data.length >= 2 && data.length <= CategoryValue.MAX_SLICES
+                && data.every(d => d.value >= 0);
+        }
+    }
+    CategoryValue.MAX_SLICES = 8;
+
+    /** One category (or time) column and several numbers: a series per number. */
+    class CategorySeries extends ResultShape {
+        static of(columns, rows) {
+            const { categories, numbers } = ResultShape.split(columns);
+            return categories.length === 1 && numbers.length >= 2 ? new CategorySeries(categories[0], numbers, rows) : null;
+        }
+        constructor(category, numbers, rows) { super(); this.category = category; this.numbers = numbers; this.rows = rows; }
+        get provides() { return { category: AXIS_KIND.CATEGORICAL, value: AXIS_KIND.NUMERIC, series: AXIS_KIND.CATEGORICAL }; }
+        get needsSeries() { return true; }
+
+        candidates() {
+            const { category } = this;
+            const time = category.kind === 'time';
+            const rows = time ? inOrder(this.rows, category.name) : this.rows;
+            // lineChart and groupedBarChart have no gap for a missing value: a null would have to be drawn
+            // as 0, a figure the data does not hold. So a result with one is not offered as series.
+            if (rows.some(r => this.numbers.some(n => r[n.name] == null))) return [];
+            const data = this.numbers.map(n => ({
+                name: n.name,
+                values: rows.map(r => ({ label: label(r[category.name]), value: r[n.name] })),
+            }));
+            const names = this.numbers.map(n => n.name).join(', ');
+            return time
+                ? [{ key: 'line', reason: `${names} over ${category.name}`, data }, { key: 'groupedBar', reason: `${names} for each ${category.name}`, data }]
+                : [{ key: 'groupedBar', reason: `${names} for each ${category.name}`, data }, { key: 'line', reason: `${names} across ${category.name}`, data }];
+        }
+    }
+
+    /** Two category (or time) columns and one number: a value per pair. */
+    class TwoCategories extends ResultShape {
+        static of(columns, rows) {
+            const { categories, numbers } = ResultShape.split(columns);
+            return categories.length === 2 && numbers.length === 1 ? new TwoCategories(categories, numbers[0], rows) : null;
+        }
+        constructor(categories, number, rows) {
+            super();
+            // A time column goes along the x axis, whichever order the columns came in.
+            this.across = categories.find(c => c.kind === 'time') ?? categories[0];
+            this.down = categories.find(c => c !== this.across);
+            this.number = number;
+            this.rows = rows;
+        }
+        get provides() {
+            return { x: AXIS_KIND.CATEGORICAL, y: AXIS_KIND.CATEGORICAL, category: AXIS_KIND.CATEGORICAL, value: AXIS_KIND.NUMERIC, series: AXIS_KIND.CATEGORICAL };
+        }
+
+        candidates() {
+            const { across, down, number } = this;
+            const rows = across.kind === 'time' ? inOrder(this.rows, across.name) : this.rows;
+            const heat = rows.filter(r => r[number.name] != null)
+                .map(r => ({ x: label(r[across.name]), y: label(r[down.name]), value: r[number.name] }));
+            const heatmap = { key: 'heatmap', reason: `${number.name} for each ${across.name} and ${down.name}`, data: heat };
+            // A series needs a value for every label; where a pair is missing (or null) only the heatmap,
+            // which draws just the cells present, shows the data without inventing a 0.
+            const labels = [...new Set(rows.map(r => label(r[across.name])))];
+            const value = new Map(rows.map(r => [`${label(r[across.name])}\u0000${label(r[down.name])}`, r[number.name]]));
+            const names = [...new Set(rows.map(r => label(r[down.name])))];
+            if (names.some(name => labels.some(l => value.get(`${l}\u0000${name}`) == null))) return [heatmap];
+            const series = names.map(name => ({ name, values: labels.map(l => ({ label: l, value: value.get(`${l}\u0000${name}`) })) }));
+            const grouped = { key: 'groupedBar', reason: `${number.name} for each ${across.name}, by ${down.name}`, data: series };
+            return across.kind === 'time'
+                ? [{ key: 'line', reason: `${number.name} over ${across.name}, a line per ${down.name}`, data: series }, heatmap, grouped]
+                : [grouped, heatmap];
+        }
+    }
+
+    /** Shapes in the order they are tried; the first that recognises the columns wins. */
+    const RESULT_SHAPES = [SingleFigure, CategoryValue, CategorySeries, TwoCategories];
+
     /**
      * RadarChart — one polygon per series across N shared axes, each axis scaled
      * independently by its own max value across all series.
@@ -53374,6 +53708,24 @@ ${theirs}` : theirs;
             this._renderChart(new FunnelChart(this.renderer, data, options));
         }
 
+        /**
+         * Renders rows as a table — a header of column names, a row per record, numeric columns
+         * right-aligned, values shown exactly. Drawn with the renderer's primitives, so it works under
+         * SVG and canvas. ChartChooser offers it for any result, last.
+         * @param {Array<object>} data one object per row
+         * @param {object} [options]
+         * @param {Array<string|{key:string, label?:string, align?:'start'|'end'}>} [options.columns] every key of the first row when absent
+         * @param {number} [options.maxRows] rows beyond it are counted, not drawn
+         * @param {string} [options.nullText] what a null or missing value shows ('—')
+         * @param {string} [options.title]
+         */
+        tableChart(data, options = {}) {
+            if (!this.renderer) return;
+            this._chart3D = false;
+            this._chartState = { type: 'table', data, options };
+            this._renderChart(new TableChart(this.renderer, data, options));
+        }
+
         /**
          * Renders a waterfall chart — running-total bars, each floating from the
          * previous cumulative value to the new one (a "delta" bar), except
@@ -58192,6 +58544,7 @@ th { color: #555; font-weight: 500; }
     exports.CanvasTemplateMenu = CanvasTemplateMenu;
     exports.CanvasView = CanvasView;
     exports.CatalogDialog = CatalogDialog;
+    exports.ChartChooser = ChartChooser;
     exports.ChartPart = ChartPart;
     exports.CheckboxTreeSelector = CheckboxTreeSelector;
     exports.CircleMarker = CircleMarker;
@@ -58406,6 +58759,7 @@ th { color: #555; font-weight: 500; }
     exports.TREE_LAYERS = TREE_LAYERS;
     exports.TREE_MODE_CATALOG = TREE_MODE_CATALOG;
     exports.TREE_SETTINGS_PROPERTIES = TREE_SETTINGS_PROPERTIES;
+    exports.TableChart = TableChart;
     exports.TabsNode = TabsNode;
     exports.Template = Template;
     exports.TemplateCatalog = TemplateCatalog;

package/dist/renderengine.umd.js

@@ -1479,6 +1479,16 @@
         dataShape: 'Array<{label, value?, children?}> — same hierarchical shape as treemap/sunburst (shares _hierarchyValue); drawn as an indented, collapsible list instead of nested rectangles/rings — a branch\'s value is auto-summed from its descendants and shown as a trailing count, a leaf\'s own extra fields (anything beyond label/value/children) shown as trailing descriptive text instead',
         streamShape: 'flat',
       },
+      {
+        key: 'table', label: 'Table', method: 'tableChart', category: '2d',
+        coordSystem: COORD_SYSTEM.CARTESIAN, title: true, legend: false, colorMode: COLOR_MODE.NONE, camera: CAMERA_MODE.NONE,
+        axes: [
+          { role: 'row',   kind: AXIS_KIND.CATEGORICAL, channel: ENCODING_CHANNEL.POSITION_ORDER, required: false },
+          { role: 'value', kind: AXIS_KIND.NUMERIC,     channel: ENCODING_CHANNEL.TEXT_VALUE,     required: false },
+        ],
+        dataShape: 'Array<object> — one row per object, a column per key (options.columns: names or {key, label?, align?}; every key of the first row when absent); values shown exactly as text, numeric columns right-aligned; options.maxRows, options.nullText',
+        streamShape: 'flat',
+      },
       {
         key: 'gauge-dial', label: 'Gauge (Dial)', method: 'dialGauge', category: 'gauge',
         coordSystem: COORD_SYSTEM.RADIAL, title: true, legend: false, colorMode: COLOR_MODE.SINGLE, camera: CAMERA_MODE.NONE,
@@ -12541,6 +12551,330 @@
     OutlineChart.INDENT_W = 18;
     OutlineChart.HIERARCHY_STRUCTURAL_KEYS = new Set(['label', 'value', 'children']);
 
+    /**
+     * TableChart — rows of values as a table: a header row of column names, then one row per record,
+     * numeric columns right-aligned. Drawn with the renderer's primitives like every chart, so it works
+     * under SVG and canvas and needs no DOM table. Values are shown exactly (not an axis's "1.20k"):
+     * a table is where a reader goes for the actual number.
+     */
+    class TableChart extends Chart {
+        static chartType = 'table';
+
+        /** Layout constants for the rows. */
+        static ROW_H = 26;
+        static PAD_X = 8;
+        static HEADER_FILL = '#eef1f6';
+        static STRIPE_FILL = '#f8f9fb';
+        static RULE = { color: '#d9dde4', width: 1 };
+
+        /**
+         * The columns to show: `options.columns` (names, or `{ key, label?, align? }`), else every key of
+         * the first row. A column is right-aligned when every value it holds is a number (or null).
+         */
+        static columns(data, given) {
+            const specs = (given ?? Object.keys(data[0] ?? {})).map(c => (typeof c === 'string' ? { key: c } : { ...c }));
+            return specs.map(c => ({
+                key: c.key,
+                label: c.label ?? c.key,
+                align: c.align ?? (data.length > 0 && data.every(r => r[c.key] == null || typeof r[c.key] === 'number') ? 'end' : 'start'),
+            }));
+        }
+
+        /** The table has no axes, so none of a chart's axis margins: an edge all round, and room for a title. */
+        static margins(title) {
+            return { left: 8, right: 8, top: title ? 50 : 8, bottom: 8 };
+        }
+
+        /**
+         * The height a table of `rowCount` rows needs — header, rows (at most `maxRows`), the "more rows"
+         * line, a title and the edges — so a page can size its container to fit before drawing.
+         */
+        static heightFor(rowCount, { title, maxRows = Infinity } = {}) {
+            const shown = Math.min(rowCount, maxRows);
+            const more = rowCount > shown ? 1 : 0;
+            const { top, bottom } = TableChart.margins(title);
+            return top + (1 + shown + more) * TableChart.ROW_H + bottom;
+        }
+
+        /** A cell's text: a number exactly (to at most 4 decimals), null/undefined as `nullText`. */
+        static cellText(value, nullText = '—') {
+            if (value == null) return nullText;
+            if (typeof value === 'number') return Number.isInteger(value) ? String(value) : String(Number(value.toFixed(4)));
+            if (value instanceof Date) return value.toISOString().slice(0, 10);
+            return String(value);
+        }
+
+        _render() {
+            const data = this.data ?? [];
+            const box = ChartBox.fromRenderer(this.renderer, TableChart.margins(this.options.title));
+            const { x = box.x, y = box.y, width = box.width, title, maxRows = Infinity, nullText = '—' } = this.options;
+            const { ROW_H, PAD_X } = TableChart;
+            const columns = TableChart.columns(data, this.options.columns);
+            const colW = columns.length > 0 ? width / columns.length : width;
+
+            new ChartLabels({ title }).draw(this.renderer, { x, y, width, height: box.height });
+
+            const shown = data.slice(0, maxRows);
+            let top = y;
+            this.renderer.rect(x, top, width, ROW_H, TableChart.HEADER_FILL, null);
+            columns.forEach((c, i) => this._cell(c.label, c, x + i * colW, top, colW, { fontWeight: 'bold', fill: '#333' }));
+            top += ROW_H;
+            this._rule(x, top, width);
+
+            shown.forEach((row, r) => {
+                if (r % 2 === 1) this.renderer.rect(x, top, width, ROW_H, TableChart.STRIPE_FILL, null);
+                columns.forEach((c, i) => this._cell(TableChart.cellText(row[c.key], nullText), c, x + i * colW, top, colW, { fill: '#222' }));
+                top += ROW_H;
+                this._rule(x, top, width);
+            });
+
+            if (data.length > shown.length) {
+                this.renderer.text(`${data.length - shown.length} more row(s) not shown`, x + PAD_X, top + ROW_H / 2, {
+                    textAnchor: 'start', verticalAlign: 'middle', fontSize: '11px', fill: '#888',
+                });
+            }
+        }
+
+        _cell(text, column, left, top, colW, attrs) {
+            const end = column.align === 'end';
+            this.renderer.text(text, end ? left + colW - TableChart.PAD_X : left + TableChart.PAD_X, top + TableChart.ROW_H / 2, {
+                textAnchor: end ? 'end' : 'start', verticalAlign: 'middle', fontSize: '12px', ...attrs,
+            });
+        }
+
+        _rule(x, y, width) {
+            this.renderer.path(`M${x},${y} L${x + width},${y}`, 'none', TableChart.RULE);
+        }
+    }
+
+    /**
+     * ChartChooser — which catalog chart types fit a set of result rows, best first, each with the rows
+     * already shaped as that chart's `dataShape`. A table always fits, so it is always offered, last.
+     *
+     * The caller may describe the columns (hints). `kind` is `'categorical'`, `'numeric'` or `'time'`; a
+     * column with no hint is numeric when every value it holds is a number, else categorical. `measure`
+     * is renderengine's measure kind (`'additive'`, `'semi-additive'`, `'non-additive'`), as a data model
+     * gives it. The hints change the choice: a time column is drawn along a line, and only an additive
+     * measure is offered as shares of a whole (a pie), since a part-of-a-whole slice of an average or a
+     * balance means nothing.
+     *
+     * Every suggestion is checked against CHART_CATALOG: a chart type is offered only when the catalog
+     * has it and every axis it requires is one the result's shape provides — so the catalog stays the
+     * single source of truth for what each chart needs.
+     *
+     *     const [best, ...others] = new ChartChooser().choose(rows, [{ name: 'Day', kind: 'time' }]);
+     *     engine.renderChartType(best.key, best.data, { title: best.label });
+     */
+    class ChartChooser {
+        /** @param {ChartRegistry} [registry] — the built-in chart types, or another registry to choose from */
+        constructor(registry = chartRegistry) {
+            this.registry = registry;
+        }
+
+        /**
+         * @param {Array<object>} rows
+         * @param {Array<{name:string, kind?:string, measure?:string}>} [columns] — hints; every key of the
+         *   first row when absent, in that order
+         * @param {{complete?:boolean}} [options] — `complete: false` when the rows are only part of the
+         *   answer (a top N, a first page): then nothing is offered as shares of a whole, since the
+         *   slices would claim to be all of it
+         * @returns {Array<{key:string, label:string, data:*, reason:string}>} best first; the table last
+         */
+        choose(rows, columns = null, { complete = true } = {}) {
+            const described = ChartChooser.describe(rows, columns);
+            const shape = RESULT_SHAPES.map(S => S.of(described, rows)).find(s => s !== null) ?? null;
+            if (shape !== null) shape.complete = complete;
+            const charts = shape === null ? [] : shape.candidates()
+                .filter(({ key }) => this.fits(key, shape))
+                .map(({ key, reason, data }) => ({ key, label: this.registry.get(key).label, data, reason }));
+            return [...charts, this.table(rows, described, charts.length === 0)];
+        }
+
+        /** A catalog entry fits a shape when every axis it requires is one the shape provides. */
+        fits(key, shape) {
+            const entry = this.registry.get(key);
+            if (!entry) return false;
+            if (shape.needsSeries && !entry.seriesCapable && !entry.axes.some(a => a.role === 'series')) return false;
+            return entry.axes.filter(a => a.required).every(a => shape.provides[a.role] === a.kind);
+        }
+
+        table(rows, described, only) {
+            return {
+                key: 'table', label: this.registry.get('table')?.label ?? 'Table',
+                data: rows, columns: described.map(c => c.name),
+                reason: only ? 'no chart fits these columns' : 'every value, exactly',
+            };
+        }
+
+        /** The columns with their kinds settled: the hint's, else derived from the rows' values. */
+        static describe(rows, columns) {
+            const given = columns ?? Object.keys(rows[0] ?? {}).map(name => ({ name }));
+            return given.map(c => ({
+                name: c.name,
+                kind: c.kind ?? (rows.length > 0 && rows.every(r => r[c.name] == null || typeof r[c.name] === 'number') ? 'numeric' : 'categorical'),
+                measure: c.measure ?? null,
+            }));
+        }
+    }
+
+    /** The label a category value is drawn with. */
+    function label(value) {
+        return value == null ? '—' : value instanceof Date ? value.toISOString().slice(0, 10) : String(value);
+    }
+
+    /** Rows in time order by `column` (numbers, dates and ISO strings all sort correctly this way). */
+    function inOrder(rows, column) {
+        return [...rows].sort((a, b) => (a[column] < b[column] ? -1 : a[column] > b[column] ? 1 : 0));
+    }
+
+    /**
+     * ResultShape — what a result's columns look like: how many category, time and numeric columns.
+     * Each subclass recognises one shape (`static of`), says which catalog axes it provides, and lists
+     * the chart types that suit it, best first, with the rows shaped for each.
+     */
+    class ResultShape {
+        constructor() {
+            /** Whether the rows are all of the answer (ChartChooser.choose's `complete`). */
+            this.complete = true;
+        }
+
+        /** The axes this shape can fill, role → AXIS_KIND. */
+        get provides() { return {}; }
+        /** Whether a chart must draw several series (one per numeric column). */
+        get needsSeries() { return false; }
+        /** @returns {Array<{key, reason, data}>} */
+        candidates() { return []; }
+
+        static split(columns) {
+            return {
+                categories: columns.filter(c => c.kind !== 'numeric'),
+                numbers: columns.filter(c => c.kind === 'numeric'),
+            };
+        }
+    }
+
+    /** One number and nothing to group it by: a single figure. */
+    class SingleFigure extends ResultShape {
+        static of(columns, rows) {
+            const { categories, numbers } = ResultShape.split(columns);
+            return categories.length === 0 && numbers.length === 1 && rows.length === 1 ? new SingleFigure(numbers[0], rows) : null;
+        }
+        constructor(number, rows) { super(); this.number = number; this.rows = rows; }
+        get provides() { return { value: AXIS_KIND.NUMERIC }; }
+        candidates() {
+            return [{ key: 'kpi-tile', reason: 'a single figure', data: { value: this.rows[0][this.number.name] } }];
+        }
+    }
+
+    /** One category (or time) column and one number: a value per category. */
+    class CategoryValue extends ResultShape {
+        static of(columns, rows) {
+            const { categories, numbers } = ResultShape.split(columns);
+            return categories.length === 1 && numbers.length === 1 ? new CategoryValue(categories[0], numbers[0], rows) : null;
+        }
+        constructor(category, number, rows) { super(); this.category = category; this.number = number; this.rows = rows; }
+        get provides() { return { category: AXIS_KIND.CATEGORICAL, value: AXIS_KIND.NUMERIC }; }
+
+        candidates() {
+            const { category, number } = this;
+            const time = category.kind === 'time';
+            const rows = time ? inOrder(this.rows, category.name) : this.rows;
+            const data = rows.filter(r => r[number.name] != null).map(r => ({ label: label(r[category.name]), value: r[number.name] }));
+            if (time) {
+                return [
+                    { key: 'line', reason: `${number.name} over ${category.name}`, data },
+                    { key: 'area', reason: `${number.name} over ${category.name}, filled`, data },
+                    { key: 'bar', reason: `${number.name} for each ${category.name}`, data },
+                ];
+            }
+            const options = [{ key: 'bar', reason: `${number.name} for each ${category.name}`, data }];
+            if (this.isShareOfWhole(data)) {
+                options.push({ key: 'pie', reason: `each ${category.name}'s share of the total ${number.name}`, data });
+                options.push({ key: 'donut', reason: `each ${category.name}'s share of the total ${number.name}`, data });
+            }
+            return options;
+        }
+
+        /**
+         * Shares of a whole make sense only for an additive measure, over all of the rows (not a top N),
+         * with no negatives, in few slices.
+         */
+        isShareOfWhole(data) {
+            return this.complete && this.number.measure === 'additive' && data.length >= 2 && data.length <= CategoryValue.MAX_SLICES
+                && data.every(d => d.value >= 0);
+        }
+    }
+    CategoryValue.MAX_SLICES = 8;
+
+    /** One category (or time) column and several numbers: a series per number. */
+    class CategorySeries extends ResultShape {
+        static of(columns, rows) {
+            const { categories, numbers } = ResultShape.split(columns);
+            return categories.length === 1 && numbers.length >= 2 ? new CategorySeries(categories[0], numbers, rows) : null;
+        }
+        constructor(category, numbers, rows) { super(); this.category = category; this.numbers = numbers; this.rows = rows; }
+        get provides() { return { category: AXIS_KIND.CATEGORICAL, value: AXIS_KIND.NUMERIC, series: AXIS_KIND.CATEGORICAL }; }
+        get needsSeries() { return true; }
+
+        candidates() {
+            const { category } = this;
+            const time = category.kind === 'time';
+            const rows = time ? inOrder(this.rows, category.name) : this.rows;
+            // lineChart and groupedBarChart have no gap for a missing value: a null would have to be drawn
+            // as 0, a figure the data does not hold. So a result with one is not offered as series.
+            if (rows.some(r => this.numbers.some(n => r[n.name] == null))) return [];
+            const data = this.numbers.map(n => ({
+                name: n.name,
+                values: rows.map(r => ({ label: label(r[category.name]), value: r[n.name] })),
+            }));
+            const names = this.numbers.map(n => n.name).join(', ');
+            return time
+                ? [{ key: 'line', reason: `${names} over ${category.name}`, data }, { key: 'groupedBar', reason: `${names} for each ${category.name}`, data }]
+                : [{ key: 'groupedBar', reason: `${names} for each ${category.name}`, data }, { key: 'line', reason: `${names} across ${category.name}`, data }];
+        }
+    }
+
+    /** Two category (or time) columns and one number: a value per pair. */
+    class TwoCategories extends ResultShape {
+        static of(columns, rows) {
+            const { categories, numbers } = ResultShape.split(columns);
+            return categories.length === 2 && numbers.length === 1 ? new TwoCategories(categories, numbers[0], rows) : null;
+        }
+        constructor(categories, number, rows) {
+            super();
+            // A time column goes along the x axis, whichever order the columns came in.
+            this.across = categories.find(c => c.kind === 'time') ?? categories[0];
+            this.down = categories.find(c => c !== this.across);
+            this.number = number;
+            this.rows = rows;
+        }
+        get provides() {
+            return { x: AXIS_KIND.CATEGORICAL, y: AXIS_KIND.CATEGORICAL, category: AXIS_KIND.CATEGORICAL, value: AXIS_KIND.NUMERIC, series: AXIS_KIND.CATEGORICAL };
+        }
+
+        candidates() {
+            const { across, down, number } = this;
+            const rows = across.kind === 'time' ? inOrder(this.rows, across.name) : this.rows;
+            const heat = rows.filter(r => r[number.name] != null)
+                .map(r => ({ x: label(r[across.name]), y: label(r[down.name]), value: r[number.name] }));
+            const heatmap = { key: 'heatmap', reason: `${number.name} for each ${across.name} and ${down.name}`, data: heat };
+            // A series needs a value for every label; where a pair is missing (or null) only the heatmap,
+            // which draws just the cells present, shows the data without inventing a 0.
+            const labels = [...new Set(rows.map(r => label(r[across.name])))];
+            const value = new Map(rows.map(r => [`${label(r[across.name])}\u0000${label(r[down.name])}`, r[number.name]]));
+            const names = [...new Set(rows.map(r => label(r[down.name])))];
+            if (names.some(name => labels.some(l => value.get(`${l}\u0000${name}`) == null))) return [heatmap];
+            const series = names.map(name => ({ name, values: labels.map(l => ({ label: l, value: value.get(`${l}\u0000${name}`) })) }));
+            const grouped = { key: 'groupedBar', reason: `${number.name} for each ${across.name}, by ${down.name}`, data: series };
+            return across.kind === 'time'
+                ? [{ key: 'line', reason: `${number.name} over ${across.name}, a line per ${down.name}`, data: series }, heatmap, grouped]
+                : [grouped, heatmap];
+        }
+    }
+
+    /** Shapes in the order they are tried; the first that recognises the columns wins. */
+    const RESULT_SHAPES = [SingleFigure, CategoryValue, CategorySeries, TwoCategories];
+
     /**
      * RadarChart — one polygon per series across N shared axes, each axis scaled
      * independently by its own max value across all series.
@@ -49441,6 +49775,24 @@ ${theirs}` : theirs;
             this._renderChart(new FunnelChart(this.renderer, data, options));
         }
 
+        /**
+         * Renders rows as a table — a header of column names, a row per record, numeric columns
+         * right-aligned, values shown exactly. Drawn with the renderer's primitives, so it works under
+         * SVG and canvas. ChartChooser offers it for any result, last.
+         * @param {Array<object>} data one object per row
+         * @param {object} [options]
+         * @param {Array<string|{key:string, label?:string, align?:'start'|'end'}>} [options.columns] every key of the first row when absent
+         * @param {number} [options.maxRows] rows beyond it are counted, not drawn
+         * @param {string} [options.nullText] what a null or missing value shows ('—')
+         * @param {string} [options.title]
+         */
+        tableChart(data, options = {}) {
+            if (!this.renderer) return;
+            this._chart3D = false;
+            this._chartState = { type: 'table', data, options };
+            this._renderChart(new TableChart(this.renderer, data, options));
+        }
+
         /**
          * Renders a waterfall chart — running-total bars, each floating from the
          * previous cumulative value to the new one (a "delta" bar), except
@@ -50805,6 +51157,7 @@ ${theirs}` : theirs;
     exports.CanvasTemplateMenu = CanvasTemplateMenu;
     exports.CanvasView = CanvasView;
     exports.CatalogDialog = CatalogDialog;
+    exports.ChartChooser = ChartChooser;
     exports.CheckboxTreeSelector = CheckboxTreeSelector;
     exports.CircleMarker = CircleMarker;
     exports.CircleTemplate = CircleTemplate;
@@ -50986,6 +51339,7 @@ ${theirs}` : theirs;
     exports.TREE_LAYERS = TREE_LAYERS;
     exports.TREE_MODE_CATALOG = TREE_MODE_CATALOG;
     exports.TREE_SETTINGS_PROPERTIES = TREE_SETTINGS_PROPERTIES;
+    exports.TableChart = TableChart;
     exports.Template = Template;
     exports.TemplateCatalog = TemplateCatalog;
     exports.TemplateLibrary = TemplateLibrary;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peter.prib/renderengine",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "ArchiMate modeller, diagram editor and chart library for the browser, with no runtime dependencies.",
   "type": "module",
   "main": "src/index.js",

package/src/chartCatalog.js

@@ -457,6 +457,16 @@ export const CHART_CATALOG = [
     dataShape: 'Array<{label, value?, children?}> — same hierarchical shape as treemap/sunburst (shares _hierarchyValue); drawn as an indented, collapsible list instead of nested rectangles/rings — a branch\'s value is auto-summed from its descendants and shown as a trailing count, a leaf\'s own extra fields (anything beyond label/value/children) shown as trailing descriptive text instead',
     streamShape: 'flat',
   },
+  {
+    key: 'table', label: 'Table', method: 'tableChart', category: '2d',
+    coordSystem: COORD_SYSTEM.CARTESIAN, title: true, legend: false, colorMode: COLOR_MODE.NONE, camera: CAMERA_MODE.NONE,
+    axes: [
+      { role: 'row',   kind: AXIS_KIND.CATEGORICAL, channel: ENCODING_CHANNEL.POSITION_ORDER, required: false },
+      { role: 'value', kind: AXIS_KIND.NUMERIC,     channel: ENCODING_CHANNEL.TEXT_VALUE,     required: false },
+    ],
+    dataShape: 'Array<object> — one row per object, a column per key (options.columns: names or {key, label?, align?}; every key of the first row when absent); values shown exactly as text, numeric columns right-aligned; options.maxRows, options.nullText',
+    streamShape: 'flat',
+  },
   {
     key: 'gauge-dial', label: 'Gauge (Dial)', method: 'dialGauge', category: 'gauge',
     coordSystem: COORD_SYSTEM.RADIAL, title: true, legend: false, colorMode: COLOR_MODE.SINGLE, camera: CAMERA_MODE.NONE,

package/src/charting/ChartChooser.js

@@ -0,0 +1,229 @@
+import { AXIS_KIND, chartRegistry } from '../chartCatalog.js';
+
+/**
+ * ChartChooser — which catalog chart types fit a set of result rows, best first, each with the rows
+ * already shaped as that chart's `dataShape`. A table always fits, so it is always offered, last.
+ *
+ * The caller may describe the columns (hints). `kind` is `'categorical'`, `'numeric'` or `'time'`; a
+ * column with no hint is numeric when every value it holds is a number, else categorical. `measure`
+ * is renderengine's measure kind (`'additive'`, `'semi-additive'`, `'non-additive'`), as a data model
+ * gives it. The hints change the choice: a time column is drawn along a line, and only an additive
+ * measure is offered as shares of a whole (a pie), since a part-of-a-whole slice of an average or a
+ * balance means nothing.
+ *
+ * Every suggestion is checked against CHART_CATALOG: a chart type is offered only when the catalog
+ * has it and every axis it requires is one the result's shape provides — so the catalog stays the
+ * single source of truth for what each chart needs.
+ *
+ *     const [best, ...others] = new ChartChooser().choose(rows, [{ name: 'Day', kind: 'time' }]);
+ *     engine.renderChartType(best.key, best.data, { title: best.label });
+ */
+export class ChartChooser {
+    /** @param {ChartRegistry} [registry] — the built-in chart types, or another registry to choose from */
+    constructor(registry = chartRegistry) {
+        this.registry = registry;
+    }
+
+    /**
+     * @param {Array<object>} rows
+     * @param {Array<{name:string, kind?:string, measure?:string}>} [columns] — hints; every key of the
+     *   first row when absent, in that order
+     * @param {{complete?:boolean}} [options] — `complete: false` when the rows are only part of the
+     *   answer (a top N, a first page): then nothing is offered as shares of a whole, since the
+     *   slices would claim to be all of it
+     * @returns {Array<{key:string, label:string, data:*, reason:string}>} best first; the table last
+     */
+    choose(rows, columns = null, { complete = true } = {}) {
+        const described = ChartChooser.describe(rows, columns);
+        const shape = RESULT_SHAPES.map(S => S.of(described, rows)).find(s => s !== null) ?? null;
+        if (shape !== null) shape.complete = complete;
+        const charts = shape === null ? [] : shape.candidates()
+            .filter(({ key }) => this.fits(key, shape))
+            .map(({ key, reason, data }) => ({ key, label: this.registry.get(key).label, data, reason }));
+        return [...charts, this.table(rows, described, charts.length === 0)];
+    }
+
+    /** A catalog entry fits a shape when every axis it requires is one the shape provides. */
+    fits(key, shape) {
+        const entry = this.registry.get(key);
+        if (!entry) return false;
+        if (shape.needsSeries && !entry.seriesCapable && !entry.axes.some(a => a.role === 'series')) return false;
+        return entry.axes.filter(a => a.required).every(a => shape.provides[a.role] === a.kind);
+    }
+
+    table(rows, described, only) {
+        return {
+            key: 'table', label: this.registry.get('table')?.label ?? 'Table',
+            data: rows, columns: described.map(c => c.name),
+            reason: only ? 'no chart fits these columns' : 'every value, exactly',
+        };
+    }
+
+    /** The columns with their kinds settled: the hint's, else derived from the rows' values. */
+    static describe(rows, columns) {
+        const given = columns ?? Object.keys(rows[0] ?? {}).map(name => ({ name }));
+        return given.map(c => ({
+            name: c.name,
+            kind: c.kind ?? (rows.length > 0 && rows.every(r => r[c.name] == null || typeof r[c.name] === 'number') ? 'numeric' : 'categorical'),
+            measure: c.measure ?? null,
+        }));
+    }
+}
+
+/** The label a category value is drawn with. */
+function label(value) {
+    return value == null ? '—' : value instanceof Date ? value.toISOString().slice(0, 10) : String(value);
+}
+
+/** Rows in time order by `column` (numbers, dates and ISO strings all sort correctly this way). */
+function inOrder(rows, column) {
+    return [...rows].sort((a, b) => (a[column] < b[column] ? -1 : a[column] > b[column] ? 1 : 0));
+}
+
+/**
+ * ResultShape — what a result's columns look like: how many category, time and numeric columns.
+ * Each subclass recognises one shape (`static of`), says which catalog axes it provides, and lists
+ * the chart types that suit it, best first, with the rows shaped for each.
+ */
+class ResultShape {
+    constructor() {
+        /** Whether the rows are all of the answer (ChartChooser.choose's `complete`). */
+        this.complete = true;
+    }
+
+    /** The axes this shape can fill, role → AXIS_KIND. */
+    get provides() { return {}; }
+    /** Whether a chart must draw several series (one per numeric column). */
+    get needsSeries() { return false; }
+    /** @returns {Array<{key, reason, data}>} */
+    candidates() { return []; }
+
+    static split(columns) {
+        return {
+            categories: columns.filter(c => c.kind !== 'numeric'),
+            numbers: columns.filter(c => c.kind === 'numeric'),
+        };
+    }
+}
+
+/** One number and nothing to group it by: a single figure. */
+class SingleFigure extends ResultShape {
+    static of(columns, rows) {
+        const { categories, numbers } = ResultShape.split(columns);
+        return categories.length === 0 && numbers.length === 1 && rows.length === 1 ? new SingleFigure(numbers[0], rows) : null;
+    }
+    constructor(number, rows) { super(); this.number = number; this.rows = rows; }
+    get provides() { return { value: AXIS_KIND.NUMERIC }; }
+    candidates() {
+        return [{ key: 'kpi-tile', reason: 'a single figure', data: { value: this.rows[0][this.number.name] } }];
+    }
+}
+
+/** One category (or time) column and one number: a value per category. */
+class CategoryValue extends ResultShape {
+    static of(columns, rows) {
+        const { categories, numbers } = ResultShape.split(columns);
+        return categories.length === 1 && numbers.length === 1 ? new CategoryValue(categories[0], numbers[0], rows) : null;
+    }
+    constructor(category, number, rows) { super(); this.category = category; this.number = number; this.rows = rows; }
+    get provides() { return { category: AXIS_KIND.CATEGORICAL, value: AXIS_KIND.NUMERIC }; }
+
+    candidates() {
+        const { category, number } = this;
+        const time = category.kind === 'time';
+        const rows = time ? inOrder(this.rows, category.name) : this.rows;
+        const data = rows.filter(r => r[number.name] != null).map(r => ({ label: label(r[category.name]), value: r[number.name] }));
+        if (time) {
+            return [
+                { key: 'line', reason: `${number.name} over ${category.name}`, data },
+                { key: 'area', reason: `${number.name} over ${category.name}, filled`, data },
+                { key: 'bar', reason: `${number.name} for each ${category.name}`, data },
+            ];
+        }
+        const options = [{ key: 'bar', reason: `${number.name} for each ${category.name}`, data }];
+        if (this.isShareOfWhole(data)) {
+            options.push({ key: 'pie', reason: `each ${category.name}'s share of the total ${number.name}`, data });
+            options.push({ key: 'donut', reason: `each ${category.name}'s share of the total ${number.name}`, data });
+        }
+        return options;
+    }
+
+    /**
+     * Shares of a whole make sense only for an additive measure, over all of the rows (not a top N),
+     * with no negatives, in few slices.
+     */
+    isShareOfWhole(data) {
+        return this.complete && this.number.measure === 'additive' && data.length >= 2 && data.length <= CategoryValue.MAX_SLICES
+            && data.every(d => d.value >= 0);
+    }
+}
+CategoryValue.MAX_SLICES = 8;
+
+/** One category (or time) column and several numbers: a series per number. */
+class CategorySeries extends ResultShape {
+    static of(columns, rows) {
+        const { categories, numbers } = ResultShape.split(columns);
+        return categories.length === 1 && numbers.length >= 2 ? new CategorySeries(categories[0], numbers, rows) : null;
+    }
+    constructor(category, numbers, rows) { super(); this.category = category; this.numbers = numbers; this.rows = rows; }
+    get provides() { return { category: AXIS_KIND.CATEGORICAL, value: AXIS_KIND.NUMERIC, series: AXIS_KIND.CATEGORICAL }; }
+    get needsSeries() { return true; }
+
+    candidates() {
+        const { category } = this;
+        const time = category.kind === 'time';
+        const rows = time ? inOrder(this.rows, category.name) : this.rows;
+        // lineChart and groupedBarChart have no gap for a missing value: a null would have to be drawn
+        // as 0, a figure the data does not hold. So a result with one is not offered as series.
+        if (rows.some(r => this.numbers.some(n => r[n.name] == null))) return [];
+        const data = this.numbers.map(n => ({
+            name: n.name,
+            values: rows.map(r => ({ label: label(r[category.name]), value: r[n.name] })),
+        }));
+        const names = this.numbers.map(n => n.name).join(', ');
+        return time
+            ? [{ key: 'line', reason: `${names} over ${category.name}`, data }, { key: 'groupedBar', reason: `${names} for each ${category.name}`, data }]
+            : [{ key: 'groupedBar', reason: `${names} for each ${category.name}`, data }, { key: 'line', reason: `${names} across ${category.name}`, data }];
+    }
+}
+
+/** Two category (or time) columns and one number: a value per pair. */
+class TwoCategories extends ResultShape {
+    static of(columns, rows) {
+        const { categories, numbers } = ResultShape.split(columns);
+        return categories.length === 2 && numbers.length === 1 ? new TwoCategories(categories, numbers[0], rows) : null;
+    }
+    constructor(categories, number, rows) {
+        super();
+        // A time column goes along the x axis, whichever order the columns came in.
+        this.across = categories.find(c => c.kind === 'time') ?? categories[0];
+        this.down = categories.find(c => c !== this.across);
+        this.number = number;
+        this.rows = rows;
+    }
+    get provides() {
+        return { x: AXIS_KIND.CATEGORICAL, y: AXIS_KIND.CATEGORICAL, category: AXIS_KIND.CATEGORICAL, value: AXIS_KIND.NUMERIC, series: AXIS_KIND.CATEGORICAL };
+    }
+
+    candidates() {
+        const { across, down, number } = this;
+        const rows = across.kind === 'time' ? inOrder(this.rows, across.name) : this.rows;
+        const heat = rows.filter(r => r[number.name] != null)
+            .map(r => ({ x: label(r[across.name]), y: label(r[down.name]), value: r[number.name] }));
+        const heatmap = { key: 'heatmap', reason: `${number.name} for each ${across.name} and ${down.name}`, data: heat };
+        // A series needs a value for every label; where a pair is missing (or null) only the heatmap,
+        // which draws just the cells present, shows the data without inventing a 0.
+        const labels = [...new Set(rows.map(r => label(r[across.name])))];
+        const value = new Map(rows.map(r => [`${label(r[across.name])}\u0000${label(r[down.name])}`, r[number.name]]));
+        const names = [...new Set(rows.map(r => label(r[down.name])))];
+        if (names.some(name => labels.some(l => value.get(`${l}\u0000${name}`) == null))) return [heatmap];
+        const series = names.map(name => ({ name, values: labels.map(l => ({ label: l, value: value.get(`${l}\u0000${name}`) })) }));
+        const grouped = { key: 'groupedBar', reason: `${number.name} for each ${across.name}, by ${down.name}`, data: series };
+        return across.kind === 'time'
+            ? [{ key: 'line', reason: `${number.name} over ${across.name}, a line per ${down.name}`, data: series }, heatmap, grouped]
+            : [grouped, heatmap];
+    }
+}
+
+/** Shapes in the order they are tried; the first that recognises the columns wins. */
+const RESULT_SHAPES = [SingleFigure, CategoryValue, CategorySeries, TwoCategories];

package/src/charting/charts/TableChart.js

@@ -0,0 +1,98 @@
+import { Chart } from '../Chart.js';
+import { ChartBox, ChartLabels } from '../ChartBox.js';
+
+/**
+ * TableChart — rows of values as a table: a header row of column names, then one row per record,
+ * numeric columns right-aligned. Drawn with the renderer's primitives like every chart, so it works
+ * under SVG and canvas and needs no DOM table. Values are shown exactly (not an axis's "1.20k"):
+ * a table is where a reader goes for the actual number.
+ */
+export class TableChart extends Chart {
+    static chartType = 'table';
+
+    /** Layout constants for the rows. */
+    static ROW_H = 26;
+    static PAD_X = 8;
+    static HEADER_FILL = '#eef1f6';
+    static STRIPE_FILL = '#f8f9fb';
+    static RULE = { color: '#d9dde4', width: 1 };
+
+    /**
+     * The columns to show: `options.columns` (names, or `{ key, label?, align? }`), else every key of
+     * the first row. A column is right-aligned when every value it holds is a number (or null).
+     */
+    static columns(data, given) {
+        const specs = (given ?? Object.keys(data[0] ?? {})).map(c => (typeof c === 'string' ? { key: c } : { ...c }));
+        return specs.map(c => ({
+            key: c.key,
+            label: c.label ?? c.key,
+            align: c.align ?? (data.length > 0 && data.every(r => r[c.key] == null || typeof r[c.key] === 'number') ? 'end' : 'start'),
+        }));
+    }
+
+    /** The table has no axes, so none of a chart's axis margins: an edge all round, and room for a title. */
+    static margins(title) {
+        return { left: 8, right: 8, top: title ? 50 : 8, bottom: 8 };
+    }
+
+    /**
+     * The height a table of `rowCount` rows needs — header, rows (at most `maxRows`), the "more rows"
+     * line, a title and the edges — so a page can size its container to fit before drawing.
+     */
+    static heightFor(rowCount, { title, maxRows = Infinity } = {}) {
+        const shown = Math.min(rowCount, maxRows);
+        const more = rowCount > shown ? 1 : 0;
+        const { top, bottom } = TableChart.margins(title);
+        return top + (1 + shown + more) * TableChart.ROW_H + bottom;
+    }
+
+    /** A cell's text: a number exactly (to at most 4 decimals), null/undefined as `nullText`. */
+    static cellText(value, nullText = '—') {
+        if (value == null) return nullText;
+        if (typeof value === 'number') return Number.isInteger(value) ? String(value) : String(Number(value.toFixed(4)));
+        if (value instanceof Date) return value.toISOString().slice(0, 10);
+        return String(value);
+    }
+
+    _render() {
+        const data = this.data ?? [];
+        const box = ChartBox.fromRenderer(this.renderer, TableChart.margins(this.options.title));
+        const { x = box.x, y = box.y, width = box.width, title, maxRows = Infinity, nullText = '—' } = this.options;
+        const { ROW_H, PAD_X } = TableChart;
+        const columns = TableChart.columns(data, this.options.columns);
+        const colW = columns.length > 0 ? width / columns.length : width;
+
+        new ChartLabels({ title }).draw(this.renderer, { x, y, width, height: box.height });
+
+        const shown = data.slice(0, maxRows);
+        let top = y;
+        this.renderer.rect(x, top, width, ROW_H, TableChart.HEADER_FILL, null);
+        columns.forEach((c, i) => this._cell(c.label, c, x + i * colW, top, colW, { fontWeight: 'bold', fill: '#333' }));
+        top += ROW_H;
+        this._rule(x, top, width);
+
+        shown.forEach((row, r) => {
+            if (r % 2 === 1) this.renderer.rect(x, top, width, ROW_H, TableChart.STRIPE_FILL, null);
+            columns.forEach((c, i) => this._cell(TableChart.cellText(row[c.key], nullText), c, x + i * colW, top, colW, { fill: '#222' }));
+            top += ROW_H;
+            this._rule(x, top, width);
+        });
+
+        if (data.length > shown.length) {
+            this.renderer.text(`${data.length - shown.length} more row(s) not shown`, x + PAD_X, top + ROW_H / 2, {
+                textAnchor: 'start', verticalAlign: 'middle', fontSize: '11px', fill: '#888',
+            });
+        }
+    }
+
+    _cell(text, column, left, top, colW, attrs) {
+        const end = column.align === 'end';
+        this.renderer.text(text, end ? left + colW - TableChart.PAD_X : left + TableChart.PAD_X, top + TableChart.ROW_H / 2, {
+            textAnchor: end ? 'end' : 'start', verticalAlign: 'middle', fontSize: '12px', ...attrs,
+        });
+    }
+
+    _rule(x, y, width) {
+        this.renderer.path(`M${x},${y} L${x + width},${y}`, 'none', TableChart.RULE);
+    }
+}

package/src/index.js

@@ -33,6 +33,8 @@ import { LagPlotChart } from './charting/charts/LagPlotChart.js';
 import { TreemapChart } from './charting/charts/TreemapChart.js';
 import { SunburstChart } from './charting/charts/SunburstChart.js';
 import { OutlineChart } from './charting/charts/OutlineChart.js';
+import { TableChart } from './charting/charts/TableChart.js';
+import { ChartChooser } from './charting/ChartChooser.js';
 import { RadarChart } from './charting/charts/RadarChart.js';
 import { FunnelChart } from './charting/charts/FunnelChart.js';
 import { WaterfallChart } from './charting/charts/WaterfallChart.js';
@@ -215,7 +217,7 @@ import {
 // separate browser-only entry: import 'renderengine/src/workspace.js' directly.
 
 export {
-  Mat4, OrbitCamera, CHART_CATALOG, getChartCatalogEntry, chartRegistry,
+  Mat4, OrbitCamera, CHART_CATALOG, getChartCatalogEntry, chartRegistry, ChartChooser, TableChart,
   DIAGRAM_CATALOG, getDiagramCatalogEntry, diagramRegistry,
   TREE_MODE_CATALOG, treeModeRegistry, getTreeModeCatalogEntry,
   AXIS_KIND, ENCODING_CHANNEL, COORD_SYSTEM, COLOR_MODE, CAMERA_MODE,
@@ -1417,6 +1419,24 @@ export class RenderEngine {
         this._renderChart(new FunnelChart(this.renderer, data, options));
     }
 
+    /**
+     * Renders rows as a table — a header of column names, a row per record, numeric columns
+     * right-aligned, values shown exactly. Drawn with the renderer's primitives, so it works under
+     * SVG and canvas. ChartChooser offers it for any result, last.
+     * @param {Array<object>} data one object per row
+     * @param {object} [options]
+     * @param {Array<string|{key:string, label?:string, align?:'start'|'end'}>} [options.columns] every key of the first row when absent
+     * @param {number} [options.maxRows] rows beyond it are counted, not drawn
+     * @param {string} [options.nullText] what a null or missing value shows ('—')
+     * @param {string} [options.title]
+     */
+    tableChart(data, options = {}) {
+        if (!this.renderer) return;
+        this._chart3D = false;
+        this._chartState = { type: 'table', data, options };
+        this._renderChart(new TableChart(this.renderer, data, options));
+    }
+
     /**
      * Renders a waterfall chart — running-total bars, each floating from the
      * previous cumulative value to the new one (a "delta" bar), except