From 97045e87aede9acb9235363d9d6f314f34e167b0 Mon Sep 17 00:00:00 2001 From: Manuel Klarmann Date: Tue, 17 Nov 2026 02:34:49 +0100 Subject: [PATCH 1/6] Review a step where it is chosen: its claim beside its effect, what it moved first Built on 7274efd (the chips, the grid first, the rest below), after Manuel's third look in sentier-bafu's frame. What a reviewer still had to hunt for: - What a step claimed. The claim sat in the folded steps table. Under the chips is now one line for the chosen step: the states it goes between, what it is, its claim with who made it, what the claim found ("All 11 124 moves as claimed", or "691 not claimed" in the signal colour), its tolerance and noise. - What a step moved. The columns came in the file's order, so the countries' factors (water use and land use) sat off-screen at the far right. The matrix now puts first the indicators in which the chosen comparison moved most; one in which nothing moved comes last, quietened, and keeps its column. - Where a reviewer is. The address keeps the chosen step with the open item (`#step=&item=`), so a link opens exactly that view; closing an item keeps the step, and an unknown step falls back to the whole way. - The arrow keys move between the chips. - The filters keep one line; the count, the matrix line and the legend take the row under them. Tests: node 54 (from 50). Seven reverts, applied on a copy, each fail a test. Co-Authored-By: Claude Opus 5.5 --- src/sentier_diagnostics/page/body.html | 1 + src/sentier_diagnostics/page/diagnostics.css | 17 ++- src/sentier_diagnostics/page/diagnostics.js | 119 +++++++++++++++++-- tests/js/page.test.js | 67 +++++++++++ 4 files changed, 189 insertions(+), 15 deletions(-) diff --git a/src/sentier_diagnostics/page/body.html b/src/sentier_diagnostics/page/body.html index d213ed6..0d4435c 100644 --- a/src/sentier_diagnostics/page/body.html +++ b/src/sentier_diagnostics/page/body.html @@ -22,6 +22,7 @@

Open a file

Comparison
+

Each cell is the result after divided by the result before, for one item and indicator, in the comparison chosen above; the grid opens with the items furthest apart. A heading sorts by that column. Choose a row (click it, or press Enter on it) to open the item.

diff --git a/src/sentier_diagnostics/page/diagnostics.css b/src/sentier_diagnostics/page/diagnostics.css index 69be7df..4502627 100644 --- a/src/sentier_diagnostics/page/diagnostics.css +++ b/src/sentier_diagnostics/page/diagnostics.css @@ -15,6 +15,7 @@ --sd-accent: var(--index, #1d625e); --sd-on-accent: var(--on-index, #ffffff); --sd-fail: var(--fail, #a3262a); + --sd-good: var(--good, #2e6b3a); --sd-radius: var(--radius, 6px); --sd-gutter: var(--gutter, 16px); --sd-t-xs: var(--t-xs, 0.75rem); @@ -77,6 +78,18 @@ .sentier-diagnostics .sd-chip-flag { font-weight: 800; color: var(--sd-fail); } .sentier-diagnostics .sd-chip[aria-pressed="true"] .sd-chip-flag { color: inherit; } .sentier-diagnostics .sd-chip-mark { font-size: var(--sd-t-xs); } + +/* the line of the chosen step: what it compares, its claim and what the claim found, its rule */ +.sentier-diagnostics .sd-step { margin: 0 0 var(--sd-s3); padding: var(--sd-s2) var(--sd-s4); border-left: 3px solid var(--sd-accent); border-radius: 0 var(--sd-radius) var(--sd-radius) 0; background: var(--sd-paper-deep); font-size: var(--sd-t-sm); } +.sentier-diagnostics .sd-step > p { margin: 0; } +.sentier-diagnostics .sd-step > p + p { margin-top: 0.25rem; } +.sentier-diagnostics .sd-claim-label { display: inline-block; margin-right: 0.5em; padding: 0 0.45em; border-radius: 3px; background: var(--sd-surface); font-size: var(--sd-t-xs); font-weight: 700; letter-spacing: 0.04em; text-transform: uppercase; color: var(--sd-muted); } +.sentier-diagnostics .sd-good { color: var(--sd-good); font-weight: 700; } +.sentier-diagnostics .sd-look { color: var(--sd-fail); font-weight: 700; } + +/* an indicator in which the chosen comparison moved nothing: last, and quiet */ +.sentier-diagnostics .sd-grid .sd-still { color: var(--sd-muted); opacity: 0.7; } +.sentier-diagnostics .sd-grid thead th.sd-still { font-weight: 400; } .sentier-diagnostics .sd-grid-note { margin: 0 0 var(--sd-s2); } .sentier-diagnostics .sd-matrix-said { margin: 0; font-size: var(--sd-t-xs); } .sentier-diagnostics .sd-matrix-said:empty { display: none; } @@ -99,8 +112,8 @@ .sentier-diagnostics .sd-controls { display: flex; flex-wrap: wrap; align-items: flex-end; gap: var(--sd-s2) var(--sd-s4); margin: var(--sd-s3) 0; } .sentier-diagnostics .sd-filters { display: flex; flex: 1 1 auto; flex-wrap: wrap; align-items: flex-end; gap: var(--sd-s2) var(--sd-s3); min-width: 0; } /* the count and the legend on the right of the filters, as in a dashboard's control row */ -.sentier-diagnostics .sd-controls > .sd-status { flex: 0 1 34rem; gap: 0.15rem; flex-direction: column; align-items: flex-end; text-align: right; } -.sentier-diagnostics .sd-controls > .sd-status .sd-legend { justify-content: flex-end; margin: 0; } +.sentier-diagnostics .sd-controls > .sd-status { flex: 1 1 100%; gap: 0.15rem var(--sd-s4); flex-direction: row; flex-wrap: wrap; align-items: baseline; justify-content: space-between; text-align: left; } +.sentier-diagnostics .sd-controls > .sd-status .sd-legend { margin: 0; } .sentier-diagnostics .sd-field { display: flex; flex-direction: column; gap: 0.2rem; font-size: var(--sd-t-sm); } .sentier-diagnostics .sd-field > span { font-size: var(--sd-t-xs); font-weight: 700; letter-spacing: 0.04em; text-transform: uppercase; color: var(--sd-muted); } .sentier-diagnostics .sd-grow { flex: 0 1 20rem; } diff --git a/src/sentier_diagnostics/page/diagnostics.js b/src/sentier_diagnostics/page/diagnostics.js index eeaeb6e..504693b 100644 --- a/src/sentier_diagnostics/page/diagnostics.js +++ b/src/sentier_diagnostics/page/diagnostics.js @@ -569,6 +569,7 @@ q('steps-zero').hidden = D.states[0].kind !== 'published'; q('made-by').textContent = 'Written by ' + D.made_by + '. ' + FORMAT + '.'; renderChips(); + renderStepSaid(); } // the comparison is chosen from a row of chips: the whole way, then each step with its @@ -601,6 +602,44 @@ }); } + // under the chips: what the chosen comparison is, the claim of its step and who made it, + // and its rule, so that a reviewer reads what a step said beside what it did + function renderStepSaid() { + var node = q('step-said'); + if (!node) return; + clear(node); + if (view.comp === 'total') { + node.appendChild(el('p', null, [el('strong', { text: 'The whole way: ' }), D.states[0].label + ' → ' + D.states[D.states.length - 1].label + '. ', + el('span', { cls: 'sd-quiet', text: 'Each cell holds the last result divided by the first. Choose a step to see what one change did; "Steps and the whole way" below splits the whole difference between them.' })])); + return; + } + var k = stepIndex(view.comp); + var s = D.steps[k]; + var line = [el('strong', { text: 'Step ' + stepNo(k) + ': ' + s.label + '. ' }), el('span', { cls: 'sd-quiet', text: D.states[k].label + ' → ' + D.states[k + 1].label + '. ' })]; + if (s.about) line.push(el('span', { cls: 'sd-quiet', text: s.about })); + node.appendChild(el('p', null, line)); + if (k === 0 && D.states[0].kind === 'published') { + node.appendChild(el('p', { cls: 'sd-quiet', text: 'What moves here was not reproduced within the tolerance: the residual the chain starts from, not a regression.' })); + } + if (!s.explained) node.appendChild(el('p', { cls: 'sd-error', text: 'Nothing explains this step.' })); + var claim = [el('span', { cls: 'sd-claim-label', text: 'Claim' })]; + if (s.claim) { + claim.push(s.claim.text, ' ', badge(s.claim.by)); + var found = LOOK.map(function (name) { return [name, sumOver(s.id, function (b) { return b.verdicts[name]; })]; }).filter(function (p) { return p[1]; }); + var held = sumOver(s.id, function (b) { return b.verdicts['as claimed']; }); + claim.push(el('span', { cls: found.length ? 'sd-look' : 'sd-good', text: found.length + ? ' ' + found.map(function (p) { return n(p[1]) + ' ' + p[0]; }).join(', ') + '.' + : held ? ' All ' + n(held) + ' moves as claimed.' : ' Nothing moved, as claimed.' })); + if (s.claim.scope.some(function (e) { return e.items === null; })) { + claim.push(el('span', { cls: 'sd-quiet', text: ' Its list of ' + D.item.many + ' is not in this file' + (s.claim.reach !== null ? ' (' + n(s.claim.reach) + ')' : '') + ': its verdicts were worked out by its writer.' })); + } + } else { + claim.push(el('span', { cls: 'sd-quiet', text: 'none: what moves here is counted, not judged.' })); + } + node.appendChild(el('p', { cls: 'sd-claim' }, claim)); + node.appendChild(el('p', { cls: 'sd-quiet', text: 'Tolerance ' + s.tolerance.value + ' (' + s.tolerance.basis + '). Noise ' + noiseText(s.noise, indicatorIds(), indWord(true)) + '.' })); + } + function markChips() { var chips = q('comparison').querySelectorAll('button[data-comp]'); for (var i = 0; i < chips.length; i++) chips[i].setAttribute('aria-pressed', chips[i].getAttribute('data-comp') === view.comp ? 'true' : 'false'); @@ -820,8 +859,18 @@ return button; } + // the columns of the matrix: the indicators in which the comparison moved most first, so + // that what a step did is in view without scrolling; the file's order among equals, and + // an indicator in which nothing moved last, quietened + function columns(comp) { + var blocks = comp === 'total' ? D.counts.total : D.counts.steps[comp]; + return D.indicators.map(function (ind, at) { return { ind: ind, moved: moved(blocks[ind.id]), at: at }; }) + .sort(function (a, b) { return b.moved - a.moved || a.at - b.at; }); + } + function renderGrid() { var k = stepIndex(view.comp); + var cols = columns(view.comp); var found = gridRows(); var shown = found.slice(0, view.limit); q('grid-said').textContent = D.tier === 'counts' @@ -836,8 +885,10 @@ el('th', { scope: 'col', cls: 'sd-name', 'aria-sort': sorted('name') }, [sortButton(capital(D.item.one), 'name', 'Sort by name')]), el('th', { scope: 'col', cls: 'sd-group', text: 'Group' }) ]; - D.indicators.forEach(function (ind) { - head.push(el('th', { scope: 'col', cls: 'num', 'aria-sort': sorted(ind.id), title: ind.name + (ind.unit ? ' (' + ind.unit + ')' : '') }, + cols.forEach(function (c) { + var ind = c.ind; + head.push(el('th', { scope: 'col', cls: 'num' + (c.moved ? '' : ' sd-still'), 'aria-sort': sorted(ind.id), + title: ind.name + (ind.unit ? ' (' + ind.unit + ')' : '') + (c.moved ? ': ' + groupThousands(c.moved) + ' moved here' : ': nothing moved here') }, [sortButton(indicatorName(ind.id), ind.id, 'Sort by how far the two lie apart, the furthest first')])); }); table.appendChild(el('thead', null, [el('tr', null, head)])); @@ -848,7 +899,11 @@ el('th', { scope: 'row', title: name + ', per ' + (row.unit || 'unknown unit') }, [M && row.item ? el('span', { cls: 'sd-listed', title: 'listed in this file' }) : null, name]), el('td', { cls: 'sd-group', text: row.group || '' }) ]; - D.indicators.forEach(function (ind) { cells.push(valueCell(row, ind.id, k, true)); }); + cols.forEach(function (c) { + var td = valueCell(row, c.ind.id, k, true); + if (!c.moved) td.className += ' sd-still'; + cells.push(td); + }); body.appendChild(el('tr', { cls: 'sd-row', tabindex: '0', 'data-item': row.id, 'aria-current': view.open === row.id ? 'true' : null }, cells)); }); table.appendChild(body); @@ -1067,9 +1122,7 @@ drawer.hidden = true; view.open = null; markOpen(); - if (/^#item=/.test(win.location.hash || '') && win.history && win.history.replaceState) { - win.history.replaceState(null, '', win.location.pathname + win.location.search); - } + if (hashParts().item) setHash({ step: view.comp }); if (lastFocus && lastFocus.focus && root.contains && root.contains(lastFocus)) lastFocus.focus(); lastFocus = null; } @@ -1243,10 +1296,41 @@ if (checked) loadMatrix(); } + // the address holds the chosen step and the open item, `#step=&item=`, each + // optional, so that a reviewer can send someone to exactly what they look at + function hashParts() { + var out = {}; + (win.location.hash || '').slice(1).split('&').forEach(function (part) { + var at = part.indexOf('='); + if (at > 0) out[part.slice(0, at)] = decodeURIComponent(part.slice(at + 1)); + }); + return out; + } + function setHash(parts) { + var said = []; + if (parts.step && parts.step !== 'total') said.push('step=' + encodeURIComponent(parts.step)); + if (parts.item) said.push('item=' + encodeURIComponent(parts.item)); + var wanted = said.join('&'); + if ((win.location.hash || '').replace(/^#/, '') === wanted) return false; + if (wanted) win.location.hash = wanted; + else if (win.history && win.history.replaceState) win.history.replaceState(null, '', win.location.pathname + win.location.search); + return true; + } + + function choose(comp) { + if (comp === view.comp) return; + view.comp = comp; view.cls = ''; view.verdict = ''; view.limit = PAGE; view.sort = 'worst'; + markChips(); + renderStepSaid(); + renderComparison(); + } + function route() { if (!D) return; - var hash = decodeURIComponent((win.location.hash || '').slice(1)); - if (hash.indexOf('item=') === 0) renderItem(hash.slice(5)); + var parts = hashParts(); + var step = parts.step && stepIndex(parts.step) < D.steps.length ? parts.step : 'total'; + choose(step); + if (parts.item) renderItem(parts.item); else closeItem(); } @@ -1254,8 +1338,7 @@ var row = event.target.closest ? event.target.closest('tr[data-item]') : null; if (!row) return; var id = row.getAttribute('data-item'); - if (win.location.hash === '#item=' + encodeURIComponent(id)) renderItem(id); - else win.location.hash = 'item=' + encodeURIComponent(id); + if (!setHash({ step: view.comp, item: id })) renderItem(id); } function readScript(name) { @@ -1268,9 +1351,19 @@ q('comparison').addEventListener('click', function (e) { var chip = e.target.closest ? e.target.closest('button[data-comp]') : null; if (!chip || chip.getAttribute('data-comp') === view.comp) return; - view.comp = chip.getAttribute('data-comp'); view.cls = ''; view.verdict = ''; view.limit = PAGE; - markChips(); - renderComparison(); + choose(chip.getAttribute('data-comp')); + setHash({ step: view.comp, item: view.open }); + }); + // the arrow keys move between the chips + q('comparison').addEventListener('keydown', function (e) { + if (!D || (e.key !== 'ArrowRight' && e.key !== 'ArrowLeft')) return; + var comps = ['total'].concat(D.steps.map(function (s) { return s.id; })); + var at = comps.indexOf(view.comp) + (e.key === 'ArrowRight' ? 1 : -1); + if (at < 0 || at >= comps.length) return; + choose(comps[at]); + setHash({ step: view.comp, item: view.open }); + var next = q('comparison').querySelector('button[data-comp="' + comps[at] + '"]'); + if (next && next.focus) next.focus(); }); q('size').addEventListener('change', function (e) { view.size = +e.target.value; view.limit = PAGE; renderWorst(); renderGrid(); }); q('worst-n').addEventListener('change', function (e) { view.worstN = +e.target.value; renderWorst(); }); diff --git a/tests/js/page.test.js b/tests/js/page.test.js index a8920f4..0182aac 100644 --- a/tests/js/page.test.js +++ b/tests/js/page.test.js @@ -590,3 +590,70 @@ test('steps count from 1 where the chain does not start from the published resul assert.doesNotMatch(drawer, /Step 0\b/); }); + +// ------------------------------------------------------------------ reviewing one step + +const chips = (drawn) => drawn.byId.comparison.querySelectorAll('button[data-comp]'); + +test('choosing a step says its claim and what the claim found, under the chips, and the address keeps it', () => { + const data = example(); + const drawn = dom.page(data); + assert.match(drawn.byId['step-said'].textContent, /^The whole way: /); + const k = data.steps.findIndex((s) => s.claim && s.claim.scope.length); + const step = data.steps[k]; + chips(drawn)[k + 1].dispatch('click', {}); + const said = drawn.byId['step-said'].textContent; + assert.ok(said.includes(step.claim.text), said); + // what the claim found, from the file's own counts + const look = ['off claim', 'not claimed', 'claimed, not moved']; + const found = look.filter((v) => Object.values(data.counts.steps[step.id]).some((b) => b.verdicts[v])); + if (found.length) found.forEach((v) => assert.ok(said.includes(v), v)); + else assert.match(said, /as claimed/); + assert.equal(drawn.context.location.hash, 'step=' + encodeURIComponent(step.id)); + assert.equal(chips(drawn)[k + 1].getAttribute('aria-pressed'), 'true'); +}); + +test('the matrix shows first the indicators in which the chosen comparison moved most', () => { + const data = example(); + const drawn = dom.page(data); + const moves = ['differs', 'beyond 10x', 'zero reference', 'zero result', 'sign change']; + const moved = (comp, id) => moves.reduce((m, c) => m + (comp === 'total' ? data.counts.total : data.counts.steps[comp])[id].classes[c], 0); + for (const comp of ['total'].concat(data.steps.map((s) => s.id))) { + drawn.byId.comparison.querySelectorAll('button[data-comp="' + comp + '"]')[0].dispatch('click', {}); + const heads = drawn.byId['grid-table'].querySelectorAll('th[scope="col"]').slice(2); + const counts = heads.map((th) => moved(comp, data.indicators.find((i) => th.getAttribute('title').indexOf(i.name) === 0).id)); + for (let k = 1; k < counts.length; k++) assert.ok(counts[k - 1] >= counts[k], comp + ': ' + counts.join()); + heads.forEach((th, k) => assert.equal(/sd-still/.test(th.className), counts[k] === 0, comp)); + // the cells of a quiet column are quiet too + const row = gridRows(drawn)[0]; + const cells = row.childNodes.filter((n) => n.tagName === 'TD').slice(1); // after the group + cells.forEach((td, k) => assert.equal(/sd-still/.test(td.className), counts[k] === 0, comp + ' cell ' + k)); + } +}); + +test('an address with a step opens the page on that step, and with an item on that item', () => { + const data = example(); + const step = data.steps[2]; + const drawn = dom.page(data); + drawn.open('step=' + encodeURIComponent(step.id) + '&item=' + encodeURIComponent(data.items[0].id)); + assert.equal(chips(drawn).find((c) => c.getAttribute('aria-pressed') === 'true').getAttribute('data-comp'), step.id); + assert.equal(drawn.byId.item.hidden, false); + // closing the item keeps the step + drawn.byId['item-close'].dispatch('click', {}); + assert.equal(drawn.byId.item.hidden, true); + assert.equal(drawn.context.location.hash, 'step=' + encodeURIComponent(step.id)); + // an unknown step falls back to the whole way + drawn.open('step=nothing-of-the-kind'); + assert.equal(chips(drawn)[0].getAttribute('aria-pressed'), 'true'); +}); + +test('the arrow keys move between the chips', () => { + const data = example(); + const drawn = dom.page(data); + drawn.byId.comparison.dispatch('keydown', { key: 'ArrowRight' }); + assert.equal(chips(drawn)[1].getAttribute('aria-pressed'), 'true'); + drawn.byId.comparison.dispatch('keydown', { key: 'ArrowLeft' }); + assert.equal(chips(drawn)[0].getAttribute('aria-pressed'), 'true'); + drawn.byId.comparison.dispatch('keydown', { key: 'ArrowLeft' }); // nothing before the whole way + assert.equal(chips(drawn)[0].getAttribute('aria-pressed'), 'true'); +}); From 752043bbf93fce62fde4c41955509c4691cf3ee2 Mon Sep 17 00:00:00 2001 From: Manuel Klarmann Date: Tue, 17 Nov 2026 02:35:12 +0100 Subject: [PATCH 2/6] SPEC: the line of the chosen step, the columns by what moved, the address Co-Authored-By: Claude Opus 5.5 --- SPEC.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/SPEC.md b/SPEC.md index 812d8a5..241c15f 100644 --- a/SPEC.md +++ b/SPEC.md @@ -490,9 +490,13 @@ stage, triage, ledger, layer, upstream, provider and candidate (a test holds thi **The page is a matrix page.** From the top: the header (10.1); a row of chips that chooses the comparison, the whole way first and then each step with its number, the values -that moved in it, a `!` where nothing explains it and a mark for each verdict worth a look; -one row of controls (name, group, class, verdict, the size filter) with the count and the -legend on its right; then the matrix (10.5), which opens an item in a drawer (10.6). Below +that moved in it, a `!` where nothing explains it and a mark for each verdict worth a look +(the arrow keys move between them); under the chips one line for the chosen step: the +states it goes between, what it is, its claim with who made it, what the claim found, its +tolerance and its noise; one row of controls (name, group, class, verdict, the size +filter) with the count and the legend in the row under it; then the matrix (10.5), which +opens an item in a drawer (10.6). The address keeps the chosen step and an open item +(`#step=&item=`), so that a reviewer can send someone to exactly that view. Below it, each closed until a reader opens it: the steps and the whole way (10.2), the distributions (10.3), the worst values (10.4), the explanations and the rule (10.7). A host's page never offers to open a file; it says only why nothing is drawn. @@ -525,7 +529,9 @@ ratio). The page always says how many it shows of how many, and how many items w look the file does not hold. ### 10.5 Matrix -Items by indicator for one comparison: each cell with a ratio shows the result after +Items by indicator for the comparison the chips have chosen. **The indicators in which that +comparison moved most come first**, so that what a step did is in view without scrolling; +an indicator in which it moved nothing comes last, quietened, and keeps its column. In it: each cell with a ratio shows the result after divided by the result before in three significant digits (`1.00`, `0.984`, `2.27`, `1.01e−3`), agreeing pairs included, so that a column reads as numbers; a cell without one says what the class says (from 0, to 0, + → −, missing, ≈ 0). The class shows as the tint From b1cd355b4a99b0d219572a9ff9a672275906b850 Mon Sep 17 00:00:00 2001 From: Manuel Klarmann Date: Tue, 17 Nov 2026 02:43:02 +0100 Subject: [PATCH 3/6] Distributions per indicator: a card each, under the matrix, as the trial dashboard has them MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The distributions were a table of small bars, folded away at the foot of the page. They are now always in view under the matrix, one card per indicator, in the order of the matrix's columns (what the chosen comparison moved most first, the unmoved ones quiet). Each card is a histogram of the file's own counts: across zero, down from far to near, the band around 1, up from near to far, then the values with no ratio; on the scale of its own tallest bar, every count in a bar's title. Under it, how many moved, and the median, 10th and 90th percentile of after ÷ before, in as many digits as keep apart the ones that differ. Those come only from every item (the matrix, or a file that lists all): the listed ones are the furthest apart, and a median of them would say more than the whole holds, so the card gives none and the section says why. A card's title sorts the matrix by its indicator; a heading of the matrix marks its card. Co-Authored-By: Claude Opus 5.5 --- src/sentier_diagnostics/page/body.html | 14 +- src/sentier_diagnostics/page/diagnostics.css | 37 +++- src/sentier_diagnostics/page/diagnostics.js | 168 +++++++++++++++---- tests/js/page.test.js | 70 ++++++++ 4 files changed, 245 insertions(+), 44 deletions(-) diff --git a/src/sentier_diagnostics/page/body.html b/src/sentier_diagnostics/page/body.html index 0d4435c..86992cf 100644 --- a/src/sentier_diagnostics/page/body.html +++ b/src/sentier_diagnostics/page/body.html @@ -46,6 +46,13 @@

Open a file

+
+

Distributions per indicator

+

+ +
+
+