@peter.prib/renderengine 0.7.0 → 0.9.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,90 @@ 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 |
+
+A chart is of **one value per category**: rows that repeat a category (orders, not totals per
+region) get no chart — group them in the query first — since a bar per row would repeat its label,
+and a repeated pair of categories would replace another's value unseen.
+
+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.
+
+### One output for a result — `resultView`
+
+`engine.resultView(rows, options)` shows result rows as an **interactive table** whose own menu
+can show them as any chart that fits — table or chart, one output. It returns the table's state, a
+`TableView`.
+
+```javascript
+const view = new RenderEngine(container, { rendererType: 'svg' }).resultView(rows, {
+    columns: [{ name: 'Day', kind: 'time' }, { name: 'Revenue', measure: 'additive' }],  // ChartChooser hints
+    complete: true,    // false when the rows are only part of the answer (a top N)
+    pageSize: 50,
+    menus: { row: ({ row }) => [{ label: 'Open order', action: () => open(row.id) }] },
+});
+```
+
+| Click | Does |
+|---|---|
+| a column header | sorts: ascending, descending, unsorted (nulls always last; equal values keep their order) |
+| a header's ▾ | the column menu: sort, **Filter to** one of its values (up to 20 listed), clear its filters, hide it, copy it |
+| a cell | the cell menu: only / exclude rows with this value (or with an empty one); for a number, only rows above / below it; copy the value |
+| a row number | the row menu: copy the row (tab-separated, or as JSON) |
+| the corner ⋮ | the table menu: **Show as** (the chart types ChartChooser says fit what is showing), clear all filters, show hidden columns, copy the table |
+| the footer's ‹ › | pages; the footer says "1–50 of 120 rows (filtered from 300: Region = West)" |
+
+Filtering is by choosing values in the table, never by typing. A filter, a sort or a hidden column
+carries into **Show as**: the chart is drawn from the rows and columns showing, in their order, and
+filtered rows are never offered as shares of a whole. A chart drawn that way has a **◂ Table** link
+back to the table as it was left. The container's height follows what is drawn (the table's rows,
+or `chartHeight`, 360); pass `fitHeight: false` to size it yourself. A host adds its own items to
+any menu with `menus: { cell, row, column, table }`, each `(context) → PopupMenu items`, shown after
+a separator.
+
+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.
+
+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 —