tosijs-ui 1.9.5 → 1.9.7

package/CHANGELOG.md

@@ -1,5 +1,171 @@
 # Changelog
 
+## 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
+in each half of the column comparator.
+
+**Numeric strings sorted by first digit.** The comparator used a raw `>`, which compares
+strings lexically — so `'9'` sorted after `'399'`, and `'1200'` before `'3.5'`. Real data
+is full of numeric strings: CSV and TSV imports, BigQuery exports, JSON where numbers
+arrived as text, anything id-shaped. Sorting now compares naturally:
+
+- numeric values (including numeric strings) compare as numbers, decimals and negatives
+  included
+- very long integers stay exact — two 20-digit ids differing in the last digit order
+  correctly, where a plain `parseFloat` comparison calls them equal
+- text compares with a locale collator, so accented letters order the way the reader
+  expects rather than the way ASCII does
+- 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
+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
+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:
+
+```typescript
+{
+  name: 'Invoice #',
+  prop: 'Customer invoice ID',   // what the row stores — CSV export, lookups
+  dataCell: invoiceCell,          // what the reader sees
+  sortValue: (row) => row['Invoice number'] || row['Customer invoice ID'],
+}
+```
+
+Purely additive; `table.sort` still overrides everything for cases a per-column value
+cannot express.
+
+**New `naturalCompare` / `naturalSorter` / `isBlank`** exported from `tosijs-ui`, since the
+same comparison is wanted outside tables.
+
+### Build system
+
+- **Code-split chunks land in `_chunks/` instead of the web root** (#64). `--splitting`
+  emits one hashed chunk per dynamic import, flat beside `index.html` — for a corpus that
+  pulls something large, that is thousands of files: tosijs-3d reported **2,473 hashed
+  chunks among 2,604 files**, all tracked in git because `docs/` is the Pages source.
+
+  The cost that hurts is not legibility. Any dependency bump rewrites every hash, so
+  upgrading one package became a multi-thousand-file commit — which makes the standing
+  "never commit `docs/` from a feature push" hazard far worse, since a stray `git add -A`
+  moves thousands of files and the diff is unreviewable. Assets move to `_assets/` for the
+  same reason.
+
+- **The dev server no longer times out mid-transfer on LAN loads** (#63). `Bun.serve`
+  defaults to a 10s `idleTimeout`, sized for small API responses — but a doc site's bundle
+  can be multiple MB, and over wifi to a phone or a second laptop that legitimately takes
+  longer, so the connection closed part-way. It never reproduces on loopback, which makes
+  it look like a client-side stall. Now 120s, overridable with
+  `DEV_REQUEST_TIMEOUT_SECONDS`. Testing on real devices over the LAN is exactly what the
+  dev cert covers `<host>.local` for.
+
+### Also
+
+- **The release lane now checks, against the packed manifest, that each peer dependency we
+  also develop against is pinned within the range we publish** (#57). A floor the library
+  is not itself built against is a contract nobody tests, and the only signal was an
+  adopter's install warning. `tosijs`'s `^1.7.8` floor is not arbitrary — it encodes
+  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_
+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.
+
 ## 1.9.5
 
 **`localize()` no longer destroys literal `#`** (#55, reported by snowfox).
@@ -13,18 +179,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
@@ -44,9 +210,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
@@ -79,7 +245,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
@@ -101,7 +267,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
@@ -122,15 +288,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
@@ -150,8 +316,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:
@@ -183,11 +349,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 } from './row-grouping.js';
 import { ValueRendererType } from './value-renderer.js';
 export interface ColumnOptions {
     name?: string;
@@ -10,6 +11,23 @@ export interface ColumnOptions {
     type?: ValueRendererType;
     pinned?: 'left' | 'right';
     sort?: false | 'ascending' | 'descending';
+    /**
+     * What this column SORTS by, when that differs from what it stores.
+     *
+     * Defaults to `row[prop]`. A column with a custom `dataCell` renders whatever it likes
+     * while the sort keys on `prop` — so when those differ, clicking "Sort Ascending"
+     * reorders rows by a value the reader cannot see, which reads as "sorting is broken"
+     * rather than "sorting a different field" (tosijs-ui#62).
+     *
+     *     { name: 'Invoice #', prop: 'Customer invoice ID', dataCell: invoiceCell,
+     *       sortValue: (row) => row['Invoice number'] || row['Customer invoice ID'] }
+     *
+     * Every other escape hatch costs more: `table.sort` is table-wide (one derived column
+     * means reimplementing sorting for all of them), replacing `headerCell` means
+     * reimplementing the header menu, and changing `prop` breaks CSV export and anything
+     * else keyed on it.
+     */
+    sortValue?: (row: any) => unknown;
     headerCell?: (options: ColumnOptions) => HTMLElement;
     dataCell?: (options: ColumnOptions) => HTMLElement;
 }
@@ -77,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;
         };
@@ -152,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;
@@ -166,6 +193,15 @@ 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();
+    private _grouping;
     get sort(): SortCallback | undefined;
     set sort(sortFunc: SortCallback | undefined);
     get columns(): ColumnOptions[];
@@ -188,6 +224,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;