Bento, the office suite that fits in a file
TypeScript mit-licenseofficeoffice-365office-suiteoffice-toolsoffice365open-sourcepowerpointself-hostedsingle-page-appslidesslideshareslideshowslideshow-galleryslideshow-makerslideshows
dash: 3D answers to the filter, says what it is showing, and stops plotting x against x×y (#644)
nyblnetc0ff43d8f83f
diff --git a/dash/CHANGELOG.md b/dash/CHANGELOG.mdindex e5ee5153..761582f3 100644--- a/dash/CHANGELOG.md+++ b/dash/CHANGELOG.md@@ -167,6 +167,32 @@ The release that came out of watching somebody use 0.2.0.fits gets no tooltip, and dragging a column wider takes the tooltip awayagain.+- **The 3D view answers to the filter, says what it is showing, and no longer+ opens on a plot of one column against itself.** Three faults, and the third+ is the one that made the other two hard to see.++ Filtering the sheet changed the grid, the status bar, the footer and the 2D+ chart, and left the 3D plot drawing every row — filter the starter workbook+ to one region and three readouts said "3 of 8 rows, £50,750" beside a picture+ of all eight. It subscribes to view changes now, and reads the same vector the+ footer totals do, so the plot cannot describe a different population from the+ numbers beside it.++ Axis titles, the colour legend and the count of rows dropped for having no+ value existed, and were drawn only by the no-WebGL fallback — so the browser+ that could not render in 3D got the labelled picture and every ordinary+ browser got an unlabelled one. They are drawn over the plot now. The dropped+ count is the part that matters: values with no number are left out rather than+ plotted as zero, which is right, and until now nothing said so.++ And the default binding took the first three numeric columns, which on the+ starter workbook meant Value, Probability, and Weighted — a column defined as+ Value × Probability. The third axis was a function of the other two, so the+ cloud was a surface and told you nothing. A column with a formula is no longer+ used as an axis while a stored one is available; and where a sheet has only+ two independent measures, it opens as 3D bars over two categories instead,+ which is both true to the data and the view a spreadsheet cannot draw.+## [0.2.0] — 2026-08-03First release. A workbook is one self-contained HTML file: the data, the grid,diff --git a/dash/src/main.ts b/dash/src/main.tsindex fa48161b..2e7d75bc 100644--- a/dash/src/main.ts+++ b/dash/src/main.ts@@ -1024,10 +1024,20 @@ function boot(doc: DashDoc, repaired: number, frozen?: 'policy' | 'version', savkindBtn.textContent = viz.kind[0].toUpperCase() + viz.kind.slice(1)const scene = buildScene(sheet, viz, sheet.id === shownId? (grid.computed as Map<string, unknown[]>)- : (recalc(sheet, store.doc.modified).values as Map<string, unknown[]>))+ : (recalc(sheet, store.doc.modified).values as Map<string, unknown[]>),+ // THE VIEW VECTOR — the same one the footer totals and the 2D chart read.+ // Its absence is why this plot ignored the filter completely.+ store.order[sheet.id] ?? null)vizDown = mountViz3d(chartBody, scene)}store.on('doc', () => { if (viz) draw3d() })+ // FILTERING AND SORTING ARE VIEW STATE: `store.view()` emits `view` and never+ // `doc`, because they must not dirty the file. `drawChart` has been on both+ // since that was found; `draw3d` was on `doc` alone, so a filter changed the+ // grid, the status bar, the footer and the 2D chart, and left the 3D plot+ // showing every row — beside three readouts that had already corrected+ // themselves. Same subscription, same reason, ten lines further down.+ store.on('view', () => { if (viz) draw3d() })app.querySelector('[data-act="viz3d"]')!.addEventListener('click', () => {const sheet = dataset('viz3d')if (!sheet) returndiff --git a/dash/src/viz3d.ts b/dash/src/viz3d.tsindex 115d362f..43160ae9 100644--- a/dash/src/viz3d.ts+++ b/dash/src/viz3d.ts@@ -58,7 +58,7 @@ import {normalize as vnorm, dot as vdot,type Mat4, type Vec3,} from './gl.ts'-import type { TableSheet } from './model.ts'+import type { Column, TableSheet } from './model.ts'import { readCell } from './store.ts'import { isErr } from './formula.ts'@@ -674,19 +674,47 @@ export function buildScene(sheet: TableSheet,binding: Viz3dBinding,computed?: Map<string, unknown[]>,+ /**+ * The view vector — `store.order[sheet.id]`: the canonical row indices the+ * reader can SEE, in the order they see them, or null/undefined for every+ * row. Exactly the argument `chart.ts` takes, for exactly the reason its+ * comment gives, and this plot did not take it.+ *+ * Measured before the fix, on the starter workbook filtered to Region =+ * North: the grid showed 3 rows, the status bar said "3 of 8 rows", the+ * footer said £50,750 — and the plot beside all of that drew all EIGHT+ * points, unchanged. That is the same failure as the footer that ignored the+ * filter, in the panel next to the one where it was fixed: the fix went into+ * `drawChart` and never crossed to `draw3d`.+ *+ * IT APPLIES TO EVERY BOUND COLUMN OR TO NONE, which is why it is projected+ * HERE rather than at the call site. `buildScatter` and `buildGrid` zip x, y,+ * z, colour and size BY INDEX; project one and not another and the plot pairs+ * the wrong height with the wrong position — plausible, and wrong. Projecting+ * inside `col` makes that unrepresentable: after this, `rows` counts the view+ * and every array is view-local, so nothing downstream can disagree about+ * which population it is describing. `scene.rows`/`scene.dropped` then report+ * the VIEW's counts, which is what the reader is being told about.+ */+ view?: number[] | null,): Scene {- const rows = sheet.rids.reduce((a, [, c]) => a + c, 0)- if (rows === 0) return emptyScene(binding.kind, 'this sheet has no rows yet')+ const all = sheet.rids.reduce((a, [, c]) => a + c, 0)+ const rows = view ? view.length : all+ if (all === 0) return emptyScene(binding.kind, 'this sheet has no rows yet')+ // A filter that matches nothing is not the same statement as an empty sheet,+ // and saying "no rows yet" over a live filter would send the reader looking+ // for data that is right there.+ if (rows === 0) return emptyScene(binding.kind, 'the filter leaves no rows to plot', all)const nameOf = (id?: string): string =>id ? (sheet.columns.find((c) => c.id === id)?.name ?? id) : ''const col = (id?: string): unknown[] | null => {if (!id) return nullconst c = computed?.get(id)- if (c) return c+ if (c) return view ? view.map((r) => c[r]) : cconst d = sheet.data[id]if (!d) return null- return Array.from({ length: rows }, (_, i) => readCell(d, i))+ return Array.from({ length: rows }, (_, i) => readCell(d, view ? view[i] : i))}switch (binding.kind) {@@ -1050,7 +1078,30 @@ function graticule(): Mesh {* actually shaped for, and return null rather than force one that is wrong.*/export function defaultViz3d(sheet: TableSheet): Viz3dBinding | null {- const numeric = sheet.columns.filter((c) => c.type === 'number' || c.type === 'money' || c.type === 'percent')+ const isNum = (c: Column): boolean => c.type === 'number' || c.type === 'money' || c.type === 'percent'+ /**+ * A DERIVED COLUMN IS NEVER AN INDEPENDENT AXIS, and the starter workbook is+ * the proof of what happens when the default does not know that.+ *+ * This bound the first three numeric columns in declaration order. On+ * `sheet-pipeline` those are Value (money), Probability (percent) and+ * Weighted (money) — `closed` is a date and drops out — and `weighted` is+ * `formula: 'value * prob'` (starter.ts). So the plot every new user met was+ * x = Value, y = Probability, **z = Value × Probability**: a surface, drawn+ * as a cloud, in which the third dimension carries no information the first+ * two do not already have. It looked like an argument against 3D and it was+ * an argument against this function.+ *+ * A column with a `formula` is a function of columns already on the sheet, so+ * using one as an axis plots a variable against itself. Stored columns are+ * preferred for x/y/z; a computed one is still allowed to COLOUR or SIZE the+ * points, where being derived is informative rather than degenerate, and is+ * still used as an axis if there is nothing else — a sheet of three formula+ * columns is better plotted than refused.+ */+ const stored = sheet.columns.filter((c) => isNum(c) && !c.formula)+ const derived = sheet.columns.filter((c) => isNum(c) && !!c.formula)+ const numeric = [...stored, ...derived]const cat = sheet.columns.filter((c) => c.type === 'text' || c.type === 'enum' || c.type === 'date')const find = (re: RegExp) => numeric.find((c) => re.test(c.name) || re.test(c.id))// `\b` matters: without it "platform" is a latitude column.@@ -1059,17 +1110,36 @@ export function defaultViz3d(sheet: TableSheet): Viz3dBinding | null {if (lat && lon && lat.id !== lon.id) {return { kind: 'globe', lat: lat.id, lon: lon.id, color: numeric.find((c) => c.id !== lat.id && c.id !== lon.id)?.id }}- if (numeric.length >= 3) {- return {- kind: 'scatter',- x: numeric[0].id, y: numeric[1].id, z: numeric[2].id,- color: numeric[3]?.id ?? cat[0]?.id,- size: numeric[4]?.id,- }- }- if (cat.length >= 2 && numeric.length >= 1) {- return { kind: 'bars', x: cat[0].id, y: cat[1].id, z: numeric[0].id, agg: 'sum' }- }+ const scatter = (): Viz3dBinding => ({+ kind: 'scatter',+ x: numeric[0].id, y: numeric[1].id, z: numeric[2].id,+ color: numeric[3]?.id ?? cat[0]?.id,+ size: numeric[4]?.id,+ })+ const bars = (): Viz3dBinding =>+ ({ kind: 'bars', x: cat[0].id, y: cat[1].id, z: numeric[0].id, agg: 'sum' })++ // THREE INDEPENDENT AXES, or this is not a scatter worth drawing.+ if (stored.length >= 3) return scatter()++ // ONLY TWO STORED MEASURES — the starter workbook's exact shape, and the+ // reason preferring stored columns is not on its own enough. `sheet-pipeline`+ // has Value and Probability and nothing else independent, so a scatter of it+ // can only reach three dimensions by taking a derived column, whatever the+ // preference says. There is no honest scatter here to pick.+ //+ // 3D BARS ARE, and they are the better answer twice over: a category x+ // category x measure grid is a genuinely three-dimensional reading of a+ // pipeline (who is selling how much, where), and it is the thing a+ // spreadsheet cannot draw — which is the whole claim this view is here to+ // make. A degenerate scatter drawn ahead of a truthful grid was the default+ // arguing against its own feature.+ if (cat.length >= 2 && numeric.length >= 1) return bars()++ // LAST RESORT, and deliberately still allowed: a sheet whose numeric columns+ // are all computed, with nothing to group by, is better plotted than refused.+ // Preferring stored columns is a preference, never a ban.+ if (numeric.length >= 3) return scatter()return null}@@ -1344,6 +1414,9 @@ export interface Viz3dOpts {elevation?: number/** point radius as a fraction of the scene radius */pointScale?: number+ /** label colour for the overlay — same default as the fallback's, so the two+ * renderers cannot drift apart on the one thing they now both draw. */+ ink?: string}/**@@ -1463,19 +1536,43 @@ export function mountViz3d(host: HTMLElement, scene: Scene, opts: Viz3dOpts = {}host.textContent = ''if (scene.empty || !supportsWebGL2()) return mountFallback(host, scene, opts)+ // A POSITIONED WRAPPER, because the labels go OVER the canvas.+ //+ // `overlaySvg` — axis titles, the colour legend and the dropped-row count —+ // had exactly one call site, inside `fallbackSvg`. So the machine that CANNOT+ // do WebGL2 got the labelled, honest picture and every ordinary browser got a+ // bare canvas: measured in the built shell, one <canvas>, zero text nodes,+ // zero overlay elements. `Scene.axes` and `Scene.legend` were computed on+ // every build and thrown away.+ //+ // The dropped-row count is the half that is not cosmetic, and this file+ // already says so: nulls are dropped rather than zeroed (correctly — a+ // missing value coerced to 0 is a crater, and craters look like findings),+ // and `overlaySvg`'s own comment calls the count "not optional: it is the+ // only place the fallback can say that some rows are not in the picture".+ // It was the only place FULL STOP, and the primary renderer said nothing.+ //+ // Deliberately a sibling layer rather than anything inside the GL path:+ // the same string the fallback builds, positioned over the canvas,+ // `pointer-events:none` so the orbit drag still lands on the canvas beneath.+ const wrap = document.createElement('div')+ wrap.className = 'dash-viz3d dash-viz3d-gl'+ wrap.style.cssText = 'position:relative;width:100%;height:100%'+ host.appendChild(wrap)+const canvas = document.createElement('canvas')// `touch-action:none` so a one-finger drag orbits instead of scrolling the// page; `user-select:none` because an orbit drag that runs off the canvas// otherwise selects the surrounding page text and leaves it highlighted.canvas.style.cssText = 'display:block;width:100%;height:100%;touch-action:none;user-select:none'- host.appendChild(canvas)+ wrap.appendChild(canvas)const view = new GLView(canvas)// supportsWebGL2() can be TRUE while this particular context fails: browsers// cap live contexts at about 16, and a dashboard that swaps tiles reaches it.// Falling back to the SVG is much better than a blank canvas.if (!view.ok) {view.dispose()- canvas.remove()+ wrap.remove()return mountFallback(host, scene, opts)}@@ -1490,6 +1587,21 @@ export function mountViz3d(host: HTMLElement, scene: Scene, opts: Viz3dOpts = {}idx: m.indices ? view.buffer(m.indices, { index: true }) : null,}))+ const labels = document.createElementNS('http://www.w3.org/2000/svg', 'svg')+ labels.setAttribute('aria-hidden', 'true')+ labels.style.cssText = 'position:absolute;inset:0;width:100%;height:100%;pointer-events:none'+ wrap.appendChild(labels)+ // Only when the BOX changes. The overlay is a function of the scene and the+ // size, never of the camera, so redrawing it per orbit frame would rebuild+ // this markup on every mouse move for no change at all.+ let lw = -1, lh = -1+ const drawLabels = (w: number, h: number) => {+ if (w === lw && h === lh) return+ lw = w; lh = h+ labels.setAttribute('viewBox', `0 0 ${w} ${h}`)+ labels.innerHTML = overlaySvg(scene, w, h, opts.ink ?? '#C7D0DE')+ }+const cam = frameCamera(scene, opts)const bg = hexToRgb(opts.background ?? '#0E1420')const pointRadius = scene.radius * (opts.pointScale ?? 0.022)@@ -1531,6 +1643,7 @@ export function mountViz3d(host: HTMLElement, scene: Scene, opts: Viz3dOpts = {}...(b.idx ? { index: b.idx } : {}),})}+ drawLabels(canvas.clientWidth || 640, canvas.clientHeight || 420)if (opts.autoRotate) { cam.rotate(-0.4, 0); schedule() }}const schedule = () => {@@ -1549,7 +1662,7 @@ export function mountViz3d(host: HTMLElement, scene: Scene, opts: Viz3dOpts = {}detach()ro?.disconnect()view.dispose()- canvas.remove()+ wrap.remove()}}diff --git a/docs/DECISIONS.md b/docs/DECISIONS.mdindex 6c2cf860..c1127103 100644--- a/docs/DECISIONS.md+++ b/docs/DECISIONS.md@@ -6613,6 +6613,57 @@ mapped, 1 correctly absent, run by bento-team-slides.Claude-Session: https://claude.ai/code/session_01Jcfdy8A69nonyATtm8vRy8+## 2026-09-09 — a derived column is never an independent axis, and a view that ignores the filter is worse than no view++**bento/dash keeps its 3D view.** The cut was proposed with numbers — 2,240+lines across `viz3d.ts` and `gl.ts`, and a starter plot that looked like it said+nothing — and declined by the maintainer: *"I think 3d is a wow feature of dash+that excel doesn't have."* This entry records the decision and, more usefully,+what the investigation behind it turned out to have been measuring.++**The strongest argument for cutting was a DEFAULT-BINDING bug, not a property+of three dimensions.** `defaultViz3d` bound the first three numeric columns in+declaration order. On `sheet-pipeline` — the workbook every new user meets —+those are Value, Probability and Weighted, and `weighted` is+`formula: 'value * prob'`. So the first 3D plot anyone saw was x = Value,+y = Probability, **z = Value × Probability**: a surface drawn as a cloud, in+which the third dimension carried nothing the first two did not. The feature was+being judged on a demo defect. *(Found by bento-team-lead.)*++**The rule, which generalises past this view.** A column with a `formula` is a+function of columns already on the sheet, so using one as an axis plots a+variable against itself. Stored columns are preferred for x/y/z; a derived one+may still colour or size the points, where being derived is informative rather+than degenerate. It is a preference and not a ban — a sheet whose numeric+columns are all computed is still better plotted than refused.++**A preference alone was not enough, and that is the more interesting half.**+The starter has only TWO stored measures, so the third axis fell to the derived+column regardless: there is no honest scatter of that sheet to pick. When fewer+than three independent measures exist and there are two categories to group by,+the default is now 3D BARS — a category × category × measure grid, which is both+truthful about the data and the thing a spreadsheet cannot draw. A degenerate+scatter drawn ahead of a truthful grid was the default arguing against its own+feature.++**Two ordinary faults, both of the same family this repo keeps finding.**+`draw3d` subscribed to `doc` and not `view`, so filtering changed the grid, the+status bar, the footer and the 2D chart and left the plot showing every row —+the same failure as the footer that ignored the filter, in the panel beside the+one where it was fixed, because the fix went into `drawChart` and never crossed.+And `overlaySvg` — axis titles, legend, and the count of rows dropped for having+no value — had exactly one call site, inside the SVG fallback, so a machine that+could NOT do WebGL2 got the labelled picture and every ordinary browser got a+bare canvas. The dropped-row count is the load-bearing half: nulls are dropped+rather than zeroed (correct — a zero is a crater, and craters look like+findings), and the primary renderer never said so.++**The view vector is projected inside `buildScene`, not at the call site**, for+the reason `chart.ts` already gives: it applies to every bound column or to+none. The builders zip x, y, z, colour and size by index; project one and not+another and the plot pairs the wrong height with the wrong position, plausibly.++## 2026-09-13 — Broadcast is a special case of collaboration: the relay half**Decision.** A live show is not a second transport. An audience member is adiff --git a/scripts/test-dash-viz3d.ts b/scripts/test-dash-viz3d.tsindex 5eb275f1..9a1b6eef 100644--- a/scripts/test-dash-viz3d.ts+++ b/scripts/test-dash-viz3d.ts@@ -64,6 +64,17 @@ function sheetOf(cols: Record<string, unknown[]>, types: Record<string, ColumnTy}}+/** `sheetOf` with formulas declared on named columns — a DERIVED column. */+function sheetWithFormulas(+ cols: Record<string, unknown[]>,+ formulas: Record<string, string>,+ types: Record<string, ColumnType> = {},+): TableSheet {+ const sh = sheetOf(cols, types)+ for (const c of sh.columns) if (formulas[c.id]) c.formula = formulas[c.id]+ return sh+}+/** Every float the GPU would read, checked for NaN/Infinity. */function sceneFinite(s: Scene): boolean {const fin = (a: Float32Array | undefined) => {@@ -568,6 +579,96 @@ function gridRows(skip: Array<[number, number]> = []) {ok(defaultViz3d(cats)?.kind === 'bars', 'two categories and a measure default to 3D bars')ok(defaultViz3d(sheetOf({ a: ['x'] }, { a: 'text' })) === null,'and a sheet with nothing to plot gets NULL rather than a forced wrong view')++ // ---- a DERIVED column is never an independent axis+ //+ // The starter workbook is the case this exists for. Its numeric columns in+ // declaration order are Value, Probability and Weighted, and Weighted is+ // `formula: 'value * prob'` — so the default binding was x = Value,+ // y = Probability, z = Value × Probability, on the one dataset every new user+ // meets. The plot was a surface drawn as a cloud, and it read as an argument+ // against three dimensions rather than against this function.+ // The starter's actual shape: three text columns and a date, Value and+ // Probability stored, Weighted computed from both.+ const starterish = sheetWithFormulas(+ { region: ['N'], owner: ['P'], stage: ['Won'], value: [10], prob: [0.5], weighted: [5] },+ { weighted: 'value * prob' },+ { region: 'text', owner: 'text', stage: 'text', value: 'money', prob: 'percent', weighted: 'money' },+ )+ const sb = defaultViz3d(starterish)!+ ok(sb.z !== 'weighted',+ 'the starter shape no longer plots Value x Probability as its Z axis — a column that IS x*y carries no third dimension')+ ok(sb.kind === 'bars',+ 'it gets 3D BARS instead: with only two stored measures there is no honest scatter, and a category x category x measure grid is both truthful and the thing a spreadsheet cannot draw')+ ok(sb.x === 'region' && sb.y === 'owner' && sb.z === 'value' && sb.agg === 'sum',+ 'and the grid is the reading a pipeline actually has — who is selling how much, where')++ // Preferring stored columns still has to BITE where a scatter is right.+ const threeStored = sheetWithFormulas(+ { a: [1], b: [2], c: [3], d: [4] },+ { b: 'a*2' },+ {},+ )+ const ts = defaultViz3d(threeStored)!+ ok(ts.kind === 'scatter' && ts.x === 'a' && ts.y === 'c' && ts.z === 'd',+ 'three STORED measures take the axes in order, stepping over the computed one between them')+ ok(ts.color === 'b',+ 'and the computed column colours the points, where being derived is informative rather than degenerate')++ // Not a ban — a preference. Three formula columns are still better plotted+ // than refused, or the rule would turn a working view into nothing at all.+ const allDerived = sheetWithFormulas(+ { a: [1], b: [2], c: [3] },+ { a: 'x+1', b: 'x+2', c: 'x+3' },+ )+ ok(defaultViz3d(allDerived)?.kind === 'scatter',+ 'a sheet whose numeric columns are ALL computed still gets a scatter — stored is preferred, not required, or the rule would refuse a view that works')++ // Order within each group is preserved, so the rule cannot reshuffle a sheet+ // that had no derived columns to begin with.+ const plain = defaultViz3d(sheetOf({ p: [1], q: [2], r: [3] }))!+ ok(plain.x === 'p' && plain.y === 'q' && plain.z === 'r',+ 'a sheet with no computed columns binds exactly as it did before — declaration order, untouched')+}++// ================================================== the view vector (a filter)+//+// `buildScene` took the whole sheet and nothing else, so the plot ignored the+// filter completely. Measured in the built shell before the fix, on the starter+// workbook filtered to Region = North: grid 3 rows, status bar "3 of 8 rows",+// footer £50,750 — and all EIGHT points still in the plot, beside three+// readouts that had already corrected themselves.+{+ const sheet = sheetOf({ x: [1, 2, 3, 4], y: [1, 2, 3, 4], z: [10, 20, 30, 40] })+ const bind: Viz3dBinding = { kind: 'scatter', x: 'x', y: 'y', z: 'z' }++ const all = buildScene(sheet, bind)+ ok(vertCount(meshOf(all, 'points')) === 4, 'with no view vector every row is plotted')++ const view = buildScene(sheet, bind, undefined, [0, 2])+ ok(vertCount(meshOf(view, 'points')) === 2,+ 'with a view vector ONLY the rows it names are plotted — the whole bug, in one number')+ ok(view.rows === 2, 'and `rows` counts the view, so the overlay describes the population on screen')+ ok(view.axes[2].max === 30 && view.axes[2].min === 10,+ 'the axes are scaled to the VISIBLE rows — a filtered plot must not keep the old range')++ // A SORT is a permutation: same rows, different order. Geometry is a set of+ // points, so the extents cannot move — only a FILTER changes what is drawn.+ const sorted = buildScene(sheet, bind, undefined, [3, 1, 2, 0])+ ok(vertCount(meshOf(sorted, 'points')) === 4 && sorted.axes[2].max === 40,+ 'a sort is a permutation, so every extent is unchanged')++ // EVERY bound column or none. Projecting x and not z would pair the wrong+ // height with the wrong position — plausible, and wrong.+ const c = buildScene(sheet, { ...bind, color: 'z' }, undefined, [0, 1])+ ok(c.legend?.kind === 'ramp' && c.legend.max === 20,+ 'the colour column is projected through the same vector as the axes')++ const none = buildScene(sheet, bind, undefined, [])+ ok(!!none.empty && /filter/.test(none.empty),+ 'a filter that matches nothing says so, and does not claim the sheet is empty')+ ok(none.rows === 4,+ 'while still reporting how many rows the sheet HAS — "0 of 4" is the honest reading')}// ====================================================== formula columns ride in