tosijs-ui 1.9.6 → 1.9.8

package/CHANGELOG.md

@@ -1,5 +1,126 @@
 # Changelog
 
+## 1.9.8
+
+**Grouped tables can now say how much of a group is showing.** The piece missing from 1.9.7's
+row grouping: a cell that reports on its group ("showing 2 of 7") or offers a **show-all**
+toggle needs to compare what is rendered against what exists — and that is the one comparison
+a cell renderer cannot make for itself. The filter has already run by then, so a consumer
+sees the survivors with nothing to measure them against. The table sees both sides.
+
+```js
+const id = table.groupIdFor(row)
+const { visible, total } = table.rowGroupCounts.get(id) ?? { visible: 0, total: 0 }
+cell.textContent = visible < total ? `showing ${visible} of ${total}` : `${total} lines`
+
+// the toggle is just a set of ids handed back to the table
+expanded.has(id) ? expanded.delete(id) : expanded.add(id)
+table.visibleGroupedRowIds = [...expanded]
+```
+
+- **`table.rowGroupCounts`** — a `Map` from group id to `{ visible, total }`, rendered rows
+  against rows before filtering. Recomputed each render and readable while cells render.
+- **`table.groupIdFor(row)`** — a row's group id, or `null` when ungrouped. This matters when
+  the grouping was **inferred** from `nonRepeatingGroupedRowCells`: you never wrote that
+  function, so its ids are otherwise unreproducible and the map would be keyed by strings you
+  could not construct.
+
+Groups the filter removed **entirely** stay in the map with `visible: 0`, so "nothing here
+matched" stays distinguishable from "no such group" — the first being exactly when a show-all
+toggle is worth offering. `rowGroupCounts` is always a `Map` (empty when ungrouped), so
+`.get()` needs no null check. Pinned rows sit outside grouping and are not counted.
+
+Additive only; ungrouped tables are unaffected.
+
+## 1.9.7
+
+**`<tosi-table>` can group rows.** The motivating shape is invoice lines: rows that belong
+together, striped as a unit, with the values they all repeat shown once.
+
+```js
+table.rowGroupId = (row) => `${row.invoice}/${row.buyer}`
+table.nonRepeatingGroupedRowCells = ['invoice', 'buyer'] // shown once per group
+table.visibleGroupedRowIds = ['INV-1001/Acme'] // stays visible past the filter
+```
+
+Set `nonRepeatingGroupedRowCells` on its own and the grouping is **inferred** from exactly
+those columns, so the common case is one line. Grouped rows get `table-cluster-even` /
+`table-cluster-odd`, alternating **per group** — a five-line invoice is one stripe, not
+five.
+
+`visibleGroupedRowIds` keeps whole groups visible regardless of the filter, so a search
+matching one line of an invoice can open the whole invoice without the filter needing to
+know anything about grouping. It is additive to the filter's own result, so a filter that
+ranks as well as selects keeps its ranking.
+
+Two details worth knowing. **Clusters keep your sort**: groups appear in first-appearance
+order, so a group lands wherever its best-sorted row landed. Sorting the clusters by their
+id instead would have quietly thrown away the sort the user just clicked. And repeated
+cells are **hidden, not emptied** — `.tr:not(.table-cluster-first) .cluster-repeat
+{ visibility: hidden }`. If you write your own rule for a custom `dataCell`, use
+`visibility`, never `display: none`: every cell is an item of the row's grid, so removing
+one pulls each later cell a column left and the row renders under the wrong headers.
+`table.isFirstInGroup(row)` answers the same question in JavaScript.
+
+Ungrouped tables are unaffected — all three properties default to off.
+
+**The inline doc-test lane was under-reporting, and staying green about it.** If you use
+`tosijs-ui/site` and have doc pages whose examples do async work, **your test counts may
+have been wrong.** A test iframe reported "page done" as soon as its _first_ example
+settled, so any example still awaiting a slow `js` block — a `fetch`, typically — never ran
+its tests, and they were omitted rather than failed. On this repo's own table page that was
+8 tests silently becoming 1, with the suite reporting "passed" either way.
+
+Completion is now decided by which examples have `test` **source**, which is known before
+anything executes, so an example that has not started yet is waited on instead of
+overlooked. An example that never finishes now fails by name with an excerpt of its source.
+The rule itself is exported as `unsettledExamples()` / `isSettled()` from
+`src/doc-system/test-completion.ts`, pure and unit-tested — a bug whose symptom is a
+_missing_ test cannot be caught by the browser lane it breaks.
+
+Check your own counts against what your pages actually contain; a number that goes **up**
+after upgrading is this bug, not a new one.
+
+**The dev server no longer 404s while it rebuilds** — the actual cause behind the LAN
+stalls in #63, traced by tosijs-3d.
+
+`buildSite` moves the output directory aside (`mv docs docs.last-good`) and repopulates it
+from empty, so for the length of every build **every served path is simply absent**. Two
+failures follow:
+
+- a request that _starts_ in that window gets a plain 404 — the page loads and never
+  hydrates
+- a request already _in flight_ has its file vanish underneath it, stops producing data,
+  and idles until something closes it — the "loads then stalls" symptom
+
+It only ever bit over the LAN because a loopback transfer finishes in ~22 ms and almost
+never overlaps the hole, while a multi-MB transfer to a phone or a second machine is
+easily still running two seconds later. It also explains why reloading never helped while
+you were actively editing: every save reopened the window.
+
+The dev server now falls back to the last-good tree for any path missing from the live
+one. That copy exists for exactly the window's duration — created by the stash at the
+start of a build, removed on success — so the fallback is self-scoping, and no stale
+content can be served outside a rebuild.
+
+Measured across real rebuilds: **2 failed requests before, 0 after**.
+
+**Formatting is gated.** `bun format` was named in no gate, so drift only accumulated — 24
+unformatted files at 1.9.0, 40 by now — and the cost always landed on whoever next ran it,
+as three dozen unrelated files in their feature diff. New `bun run format-check`
+(`prettier --check .`), run in CI. Adopters get the script; nothing about the published
+package changes.
+
+> **On versioning.** This is a patch that adds public API, which the project's own rule
+> previously called a minor. The rule has changed: minors are for **breaking changes and
+> feature rollouts**, while additive, non-breaking extensions ship as patches. The contract
+> you rely on is unchanged and is the whole point — **a patch never breaks you.**
+
+> The `idleTimeout` raise and asset compression in 1.9.6 both help, but neither closes this
+> window — compression shortens the exposure, and `idleTimeout` only decides how long a
+> stalled request waits before failing. If you are on 1.9.6 and still seeing LAN stalls,
+> this is the release that fixes them.
+
 ## 1.9.6
 
 **`<tosi-table>` sorts correctly** (#62, reported by snowfox). Two independent defects, one
@@ -19,11 +140,11 @@ arrived as text, anything id-shaped. Sorting now compares naturally:
 - blank cells sort **last in both directions** — a descending sort that opens on a
   screenful of empty cells is never what was clicked for
 
-The old comparator also never returned `0`, so two *equal* values each claimed to be
+The old comparator also never returned `0`, so two _equal_ values each claimed to be
 greater than the other. `Array.sort` is entitled to turn an inconsistent comparator into
 arbitrary output, not merely wrong output.
 
-**New `ColumnOptions.sortValue`** — sort by what the cell *shows*, when that differs from
+**New `ColumnOptions.sortValue`** — sort by what the cell _shows_, when that differs from
 what the row stores. A column with a custom `dataCell` renders whatever it likes while the
 sort keyed on `prop`, so the rows reordered by an invisible value:
 
@@ -72,7 +193,7 @@ same comparison is wanted outside tables.
   tosijs#20 (the `parts` proxy crossing into nested components) and #21 — and that reason
   is now recorded in `CLAUDE.md` rather than only in an old changelog entry.
 
-`makeSorter` deliberately keeps its existing comparison: switching it would change *case*
+`makeSorter` deliberately keeps its existing comparison: switching it would change _case_
 ordering (`'Zed'` before `'alice'` today) in a general-purpose utility where that has not
 been reported as a problem. Coerce numeric strings in the valuator, or pass values through
 `naturalCompare` yourself.
@@ -90,18 +211,18 @@ An annotation is a **suffix identifier**, so only a `#` that looks like one is t
 one — immediately preceded by a non-space, followed by letters/digits/`_`/`-`, at the end
 of the string:
 
-| string | read as |
-| --- | --- |
-| `Okay#confirm` | annotation |
-| `C# Tutorial` | literal — space after |
-| `Issue #42` | literal — space before |
-| `#hashtag` | literal — nothing before |
-| `C#` | literal — no annotation after |
+| string         | read as                       |
+| -------------- | ----------------------------- |
+| `Okay#confirm` | annotation                    |
+| `C# Tutorial`  | literal — space after         |
+| `Issue #42`    | literal — space before        |
+| `#hashtag`     | literal — nothing before      |
+| `C#`           | literal — no annotation after |
 
 No author action and no data migration; every documented annotation form is unchanged.
 Escape with `\#` for a literal that genuinely looks like an annotation (`tag\#42`).
 
-**The worse half:** annotations were stripped from the *translated value* too, so a
+**The worse half:** annotations were stripped from the _translated value_ too, so a
 translation containing `#` was truncated **even when the source string had none** —
 `'Sharp'` → `'Dièse #1'` came back as `'Dièse '`. A translator writing an ordinary string
 had it silently cut, with nothing in the source to hint why. Translations are no longer
@@ -121,9 +242,9 @@ it resolves to.
 
 It spawned its own channel via `bunx haltija@^1.6.1` and ignored the project's dependency
 entirely — and because **bunx caches the resolution**, a range that resolves forward never
-*re*-resolves once its cache key exists. So an adopter who bumped `haltija` to `^1.11.2`
+_re_-resolves once its cache key exists. So an adopter who bumped `haltija` to `^1.11.2`
 for a fix, restarted, and still didn't have the fix was running a cached 1.11.0: new
-enough to look current, old enough to lack it. `hj where` reports the *spawned* server, so
+enough to look current, old enough to lack it. `hj where` reports the _spawned_ server, so
 the version indicator agreed with them.
 
 - Your `node_modules/.bin/haltija` is preferred when present. `HALTIJA_VERSION` still
@@ -156,7 +277,7 @@ upstream as [oven-sh/bun#36788](https://github.com/oven-sh/bun/issues/36788).
 ### ePub volumes are now linkable (#46)
 
 The build wrote an ePub per volume and linked to none of them, so a reader had no route
-to a book that existed. The filename is *derived* (`<project>-<volume>.epub`), so
+to a book that existed. The filename is _derived_ (`<project>-<volume>.epub`), so
 hand-written links rot silently when a volume is renamed.
 
 Three ways to surface them, and the ePub build now names its output through the same
@@ -178,7 +299,7 @@ at.
   walled you with "that invite link has been used". The stale token is simply irrelevant
   to someone who already holds a session.
 - **`tosijs-tunnel --close` confirms identity before signalling.** It SIGTERMed every
-  `pgrep -f` match, and `pgrep -f` matches an argv *substring* — a shell echoing the
+  `pgrep -f` match, and `pgrep -f` matches an argv _substring_ — a shell echoing the
   command or an editor holding a log path both matched. It now checks the process really
   is `ssh`, says what it signalled, and names what it skipped. It also interpolated `host`
   into a REGEX unescaped, so `me@a.b` matched `me@axb` and a host containing `+`, `(` or
@@ -199,15 +320,15 @@ at.
 `hj map` (haltija 1.11) over the doc site, which reports a measured contrast ratio per
 node — none of these were visible as wrong to the eye.
 
-| pair | was | now |
-| --- | --- | --- |
-| test widget, running | white on `#fa0` — **1.9:1** | `#2b1a00` on `#fa0` — 8.8:1 |
-| test widget, passed | white on `#0a0` — **3.1:1** | white on `#008a00` — 4.5:1 |
-| `--tosi-accent` as text | `#EE257B` — **4.05:1** on white, 4.3:1 on the page | `#d92270` — 4.6:1 |
-| `--tosi-accent` as a fill | white on `#EE257B` — **4.05:1** | white on `#d92270` — 4.8:1 |
+| pair                      | was                                                | now                         |
+| ------------------------- | -------------------------------------------------- | --------------------------- |
+| test widget, running      | white on `#fa0` — **1.9:1**                        | `#2b1a00` on `#fa0` — 8.8:1 |
+| test widget, passed       | white on `#0a0` — **3.1:1**                        | white on `#008a00` — 4.5:1  |
+| `--tosi-accent` as text   | `#EE257B` — **4.05:1** on white, 4.3:1 on the page | `#d92270` — 4.6:1           |
+| `--tosi-accent` as a fill | white on `#EE257B` — **4.05:1**                    | white on `#d92270` — 4.8:1  |
 
 **The brand pink is 9% darker** (`#EE257B` → `#d92270`). It is imperceptible side by side
-and it was the only value that clears AA in *both* directions — as text on the page, and
+and it was the only value that clears AA in _both_ directions — as text on the page, and
 as a fill carrying white text. Override `--tosi-accent` if you want the original.
 
 Two more, found by sweeping wider — both in **example code we publish**, which matters
@@ -227,8 +348,8 @@ Verified across 8 pages in both themes on haltija 1.11.2: **0 failures, 0 uncert
 
 **The browser-test lane now runs its own private haltija.** It used to reuse any running
 instance and otherwise spawn with `-f`, which reclaims haltija's shared default port and
-kills whatever held it. Both halves were wrong: adopting meant inheriting the *desktop
-app's* window, whose visibility depends on whatever else is on screen — and `hj` rightly
+kills whatever held it. Both halves were wrong: adopting meant inheriting the _desktop
+app's_ window, whose visibility depends on whatever else is on screen — and `hj` rightly
 refuses to drive a hidden tab, since a backgrounded tab throttles `requestAnimationFrame`
 and would produce plausible-but-wrong results. The lane failed roughly two runs in three
 with no programmatic way out. It now takes an isolated instance on an ephemeral port:
@@ -260,11 +381,11 @@ Two runtime requirements are unchanged, and are now documented rather than impli
 are honest constraints, not bugs, but the failure messages named symptoms rather than
 causes:
 
-| entry point | runtime |
-| --- | --- |
-| `tosijs-ui/site` | **bun** — it shells out, builds and spawns |
-| `tosijs-ui`, `tosijs-ui/<component>` | a **browser** or a bundler targeting one |
-| `tosijs-ui/icon-svg` | anything — deliberately DOM-free |
+| entry point                          | runtime                                    |
+| ------------------------------------ | ------------------------------------------ |
+| `tosijs-ui/site`                     | **bun** — it shells out, builds and spawns |
+| `tosijs-ui`, `tosijs-ui/<component>` | a **browser** or a bundler targeting one   |
+| `tosijs-ui/icon-svg`                 | anything — deliberately DOM-free           |
 
 `engines` now declares bun, and `doc-site-system.md` has a "Runtimes — what runs where"
 section.

package/dist/data-table.d.ts

@@ -1,5 +1,6 @@
 import { Component as WebComponent, ElementCreator } from 'tosijs';
 import { SortCallback } from './make-sorter.js';
+import { RowGroupIdFn, GroupCount } from './row-grouping.js';
 import { ValueRendererType } from './value-renderer.js';
 export interface ColumnOptions {
     name?: string;
@@ -94,6 +95,12 @@ export declare class TosiTable extends WebComponent {
             zIndex: string;
             background: string;
         };
+        ':host .tr:not(.table-cluster-first) .cluster-repeat': {
+            visibility: string;
+        };
+        ':host .tr.table-cluster-odd': {
+            _tosiTableBg: string;
+        };
         ':host .tr[aria-selected] .td': {
             background: string;
         };
@@ -169,6 +176,9 @@ export declare class TosiTable extends WebComponent {
     private _columns;
     private _filter;
     private _sort?;
+    private _rowGroupId;
+    private _visibleGroupedRowIds;
+    private _nonRepeatingGroupedRowCells;
     private _pinnedTopRows?;
     private _pinnedBottomRows?;
     get pinnedTopRows(): any[] | undefined;
@@ -183,6 +193,36 @@ export declare class TosiTable extends WebComponent {
     set array(newArray: any[]);
     get filter(): ArrayFilter;
     set filter(filterFunc: ArrayFilter);
+    get rowGroupId(): RowGroupIdFn | null;
+    set rowGroupId(fn: RowGroupIdFn | null);
+    get visibleGroupedRowIds(): string[] | null;
+    set visibleGroupedRowIds(ids: string[] | null);
+    get nonRepeatingGroupedRowCells(): string[] | null;
+    set nonRepeatingGroupedRowCells(props: string[] | null);
+    /** The grouping function in force, or null when the table is ungrouped. */
+    private get groupIdFn();
+    /**
+     * This row's group id, or null when the table is ungrouped.
+     *
+     * Public because the grouping may be INFERRED from `nonRepeatingGroupedRowCells`, in which
+     * case the consumer never wrote the function and cannot reproduce its ids — which would
+     * leave `rowGroupCounts` keyed by strings they have no way to construct.
+     */
+    groupIdFor(row: any): string | null;
+    /**
+     * Per-group `{ visible, total }` counts — rendered rows against rows before filtering.
+     *
+     * For cells that report or control their own group: "showing 2 of 7", or a toggle that
+     * adds the group to `visibleGroupedRowIds`. The table is the only thing that sees both
+     * sides of the filter, so this is the piece a custom cell renderer cannot derive itself.
+     *
+     * Recomputed each render, and always a Map — empty when ungrouped — so callers can `.get()`
+     * without a null check. Groups filtered away entirely are present with `visible: 0`;
+     * pinned rows sit outside grouping and are not counted.
+     */
+    get rowGroupCounts(): Map<string, GroupCount>;
+    private _grouping;
+    private _rowGroupCounts;
     get sort(): SortCallback | undefined;
     set sort(sortFunc: SortCallback | undefined);
     get columns(): ColumnOptions[];
@@ -205,6 +245,15 @@ export declare class TosiTable extends WebComponent {
     private cellStyle;
     private applyGridCellAttrs;
     private buildCell;
+    private tagClusterParity;
+    /**
+     * Is this row the first of its group? Always true when the table is ungrouped.
+     *
+     * Exposed for custom `dataCell` columns, which render themselves and so have to decide
+     * for themselves whether to show a value the rest of the group repeats.
+     */
+    isFirstInGroup(row: any): boolean;
+    private isRepeatedGroupRow;
     private buildRow;
     private buildHeaderCell;
     private buildHeader;