@peter.prib/renderengine 0.8.0 → 0.9.0

package/REFERENCE.md

@@ -1112,6 +1112,10 @@ or `'time'` (without a hint, a column whose values are all numbers is numeric, e
 | 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
@@ -1121,6 +1125,42 @@ 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.