tosijs-ui 1.9.5 → 1.9.6

package/CHANGELOG.md

@@ -1,5 +1,82 @@
 # Changelog
 
+## 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).

package/dist/data-table.d.ts

@@ -10,6 +10,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;
 }

package/dist/data-table.js

@@ -566,6 +566,7 @@ As well as any column names you want localized.
 /*{ "parent": "Components" }*/
 import { Component as WebComponent, elements, vars, varDefault, tosiValue, getListItem, getListBinding, tosi, } from 'tosijs';
 import { trackDrag } from './track-drag.js';
+import { naturalSorter } from './natural-compare.js';
 import { icons } from './icons.js';
 import { valueRenderer } from './value-renderer.js';
 import { popMenu } from './menu.js';
@@ -889,10 +890,19 @@ export class TosiTable extends WebComponent {
         if (!sortColumn) {
             return undefined;
         }
-        const { prop } = sortColumn;
-        return sortColumn.sort === 'ascending'
-            ? (a, b) => (a[prop] > b[prop] ? 1 : -1)
-            : (a, b) => (a[prop] > b[prop] ? -1 : 1);
+        /*
+        Two defects lived in these three lines (tosijs-ui#62).
+    
+        It keyed on `prop`, so a column whose `dataCell` shows something else sorted by a value
+        the reader cannot see. And `>` is a LEXICAL compare, so any column of numeric strings
+        sorted by first digit — `'9' > '399'` is true, and real data is full of numeric strings
+        from CSV, BigQuery and JSON. Worse, `a > b ? 1 : -1` never returns 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 rather than merely wrong output.
+        */
+        const { prop, sortValue } = sortColumn;
+        const key = sortValue ?? ((row) => row[prop]);
+        return naturalSorter(key, sortColumn.sort === 'ascending');
     }
     set sort(sortFunc) {
         if (this._sort !== sortFunc) {

package/dist/doc-system/site/dev-server.d.ts

@@ -68,6 +68,10 @@ export declare function resolveLimitMb(configMb: number | undefined, envMb: stri
 export { isLoopbackAddress };
 export declare function haltijaIsDrivable(stdout: string): boolean;
 export declare function haltijaLoaderSnippet(httpsPort: number): string;
+/** br if the client takes it, else gzip, else nothing. */
+export declare function negotiateEncoding(accept: string | null): 'br' | 'gzip' | null;
+/** Is this worth compressing? Already-compressed formats only get bigger. */
+export declare function isCompressible(filePath: string): boolean;
 export declare function devServer(config: SiteConfig, opts?: {
     test?: boolean;
     build?: () => unknown | Promise<unknown>;

package/dist/doc-system/site/dev-server.js

@@ -10,7 +10,8 @@ Build-time only (Bun APIs). Never import this from browser code.
 import * as path from 'path';
 import { statSync, existsSync, readFileSync } from 'fs';
 import { tmpdir } from 'os';
-import { $, spawn } from 'bun';
+import { $, spawn, gzipSync } from 'bun';
+import { brotliCompressSync, constants as zlibConstants } from 'node:zlib';
 import { buildSite } from './orchestrator.js';
 import { preflight } from './preflight.js';
 import { auditDependencies, reportAudit } from './audit-guard.js';
@@ -66,6 +67,12 @@ then shipped an instance of. A range is not a pin, and a cached range is not eve
 is something an adopter controls with the tool they already use. `HALTIJA_VERSION` still
 overrides everything.
 */
+/**
+ * Seconds `Bun.serve` will wait on a slow transfer before closing it. Bun's default is 10,
+ * sized for API responses rather than multi-MB bundles over LAN wifi (#63). Override with
+ * `DEV_REQUEST_TIMEOUT_SECONDS`; Bun caps this at 255.
+ */
+const DEV_IDLE_TIMEOUT_SECONDS = Math.min(255, Number(process.env.DEV_REQUEST_TIMEOUT_SECONDS) || 120);
 const HALTIJA_PKG = process.env.HALTIJA_VERSION ?? 'haltija@^1.11.2';
 /*
 Which haltija do we actually run, and can we say so out loud?
@@ -335,6 +342,70 @@ async function ensureDevCerts() {
         'install instructions if it is missing.\n');
     process.exit(1);
 }
+/*
+Compress text-shaped assets on the way out.
+
+The dev server serves REAL DEVICES over the LAN — that is what the mkcert cert covers
+`<host>.local` for — and a doc site's bundle can be multiple MB. Everything text-shaped
+here compresses to about 30%: this repo's 1.21MB iife goes to 0.39MB gzipped, 0.36MB
+brotli; tosijs-3d's 10MB one goes to roughly 3MB. That is the real fix for the LAN stalls
+behind #63 — raising `idleTimeout` stopped the connection dying, this stops it needing the
+extra time.
+
+Deliberately DEV-SERVER ONLY. Distribution is a host's job — Cloudflare, Firebase and
+friends do this better and for free — so the build emits nothing precompressed.
+
+Brotli at quality 5, not 11: measured on the 1.21MB iife, q5 takes 19ms for 0.36MB while
+q11 takes **1169ms** for 0.32MB. Sixty times the cost for four percent.
+*/
+const COMPRESSIBLE = /\.(js|mjs|css|html|json|svg|map|txt|xml|md|wasm)$/i;
+/*
+A BOUNDED cache, because this process lives for days.
+
+Recompressing a 10MB bundle per request would cost more than it saves, so the bytes have
+to be kept — but an unbounded cache in a long-lived dev server is precisely the failure
+that took this machine down twice, and it is invisible to the JS heap until it is not.
+Keyed on path + mtime so a rebuild invalidates naturally; capped in total bytes with
+oldest-out eviction.
+*/
+const COMPRESS_CACHE_MAX_BYTES = 64 * 1024 * 1024;
+const compressCache = new Map();
+let compressCacheBytes = 0;
+function cacheCompressed(key, bytes) {
+    // A single asset bigger than the whole budget is not worth evicting everything for.
+    if (bytes.byteLength > COMPRESS_CACHE_MAX_BYTES / 2)
+        return;
+    while (compressCacheBytes + bytes.byteLength > COMPRESS_CACHE_MAX_BYTES &&
+        compressCache.size) {
+        const oldest = compressCache.keys().next().value;
+        compressCacheBytes -= compressCache.get(oldest).byteLength;
+        compressCache.delete(oldest);
+    }
+    compressCache.set(key, bytes);
+    compressCacheBytes += bytes.byteLength;
+}
+function compressBytes(bytes, encoding) {
+    return encoding === 'br'
+        ? new Uint8Array(brotliCompressSync(bytes, {
+            params: { [zlibConstants.BROTLI_PARAM_QUALITY]: 5 },
+        }))
+        : gzipSync(bytes);
+}
+/** br if the client takes it, else gzip, else nothing. */
+export function negotiateEncoding(accept) {
+    if (!accept)
+        return null;
+    const a = accept.toLowerCase();
+    if (a.includes('br'))
+        return 'br';
+    if (a.includes('gzip'))
+        return 'gzip';
+    return null;
+}
+/** Is this worth compressing? Already-compressed formats only get bigger. */
+export function isCompressible(filePath) {
+    return COMPRESSIBLE.test(filePath);
+}
 export async function devServer(config, opts = {}) {
     // PORT env wins over the config, so a test harness can bring up its own instance on
     // its own port instead of adopting (or killing — killStrayServer takes the port)
@@ -532,15 +603,42 @@ export async function devServer(config, opts = {}) {
     async function respondFile(filePath, request, viaTunnel = false) {
         const extras = (haltijaDev ? HALTIJA_SNIPPET : '') +
             (testMode ? '' : statusSnippet(request, viaTunnel));
+        const encoding = negotiateEncoding(request?.headers.get('accept-encoding') ?? null);
         if (extras && filePath.endsWith('.html')) {
             const html = await Bun.file(filePath).text();
             const injected = html.includes('</body>')
                 ? html.replace('</body>', `${extras}</body>`)
                 : html + extras;
-            return new Response(injected, {
-                headers: { 'Content-Type': 'text/html; charset=utf-8' },
+            // Injected HTML is built per request, so it is compressed but never cached — the
+            // cache key would have to include the injected extras, and HTML is small anyway.
+            const body = encoding
+                ? compressBytes(new TextEncoder().encode(injected), encoding)
+                : injected;
+            return new Response(body, {
+                headers: {
+                    'Content-Type': 'text/html; charset=utf-8',
+                    ...(encoding ? { 'Content-Encoding': encoding, Vary: 'Accept-Encoding' } : {}),
+                },
+            });
+        }
+        if (encoding && isCompressible(filePath)) {
+            const file = Bun.file(filePath);
+            const key = `${encoding}:${filePath}:${file.lastModified}`;
+            let bytes = compressCache.get(key);
+            if (!bytes) {
+                bytes = compressBytes(new Uint8Array(await file.arrayBuffer()), encoding);
+                cacheCompressed(key, bytes);
+            }
+            return new Response(bytes, {
+                headers: {
+                    'Content-Type': file.type || 'application/octet-stream',
+                    'Content-Encoding': encoding,
+                    Vary: 'Accept-Encoding',
+                },
             });
         }
+        // Everything else streams untouched — images, fonts, epubs and glb are already
+        // compressed, and re-encoding them only makes them bigger.
         return new Response(Bun.file(filePath));
     }
     async function handleTestReport(request) {
@@ -1144,8 +1242,22 @@ export async function devServer(config, opts = {}) {
     and the OS closes the sockets, and calling `.stop()` first is what segfaulted on the
     idle path (#47). A handle we would never legitimately use is an invitation to use it.
     */
+    /*
+    A generous idleTimeout, because this serves BUNDLES to REAL DEVICES.
+  
+    `Bun.serve` defaults to 10s, which is sized for small API responses. A doc site's iife
+    can be multiple MB — tosijs-3d ships ~10MB unminified on purpose, so its source stays
+    browseable — and over LAN wifi to a phone or a second laptop that legitimately takes
+    longer than 10s. Bun then closes the connection mid-transfer and the page half-loads.
+  
+    It never reproduces on loopback, so it presents as a mysterious client-side stall; the
+    reporter first suspected a bundle-size regression (tosijs-ui#63). Serving real devices
+    over the LAN is exactly what the mkcert cert covers `<host>.local` FOR, so the default
+    is wrong for this server specifically.
+    */
     Bun.serve({
         port: PORT,
+        idleTimeout: DEV_IDLE_TIMEOUT_SECONDS,
         tls: {
             key: Bun.file('./tls/key.pem'),
             cert: Bun.file('./tls/certificate.pem'),
@@ -1184,6 +1296,8 @@ export async function devServer(config, opts = {}) {
         try {
             Bun.serve({
                 port: tunnelPort,
+                // Same reasoning as the main listener — a tunnelled load is slower, not faster.
+                idleTimeout: DEV_IDLE_TIMEOUT_SECONDS,
                 hostname: '127.0.0.1',
                 fetch: (request, srv) => handleRequest(request, srv, true),
             });

package/dist/doc-system/site/orchestrator.js

@@ -599,6 +599,25 @@ export async function buildSite(config, opts = {}) {
                 '--minify',
                 '--entry-naming',
                 'hydrate.js',
+                /*
+                Code-split chunks go in a SUBDIRECTORY, not the web root.
+      
+                `--splitting` emits one hashed chunk per dynamic import, and they landed flat
+                beside `index.html`. For a corpus that pulls something large — Babylon's glTF
+                extensions, shader chunks, audio engines — that is thousands of files in the root:
+                tosijs-3d reported **2,473 hashed chunks** among 2,604 files (tosijs-ui#64).
+      
+                Three costs, and the second is the dangerous one. `ls docs` stops being usable.
+                Any dependency bump rewrites every hash, so a Babylon upgrade becomes a
+                multi-thousand-file commit — which makes the standing "don't commit docs/ from a
+                feature push" hazard far worse, because a stray `git add -A` now moves thousands
+                of files and the diff is unreviewable. (They took their doc site down exactly that
+                way.) And a genuinely stale or missing artifact is invisible among the lookalikes.
+                */
+                '--chunk-naming',
+                '_chunks/[name]-[hash].[ext]',
+                '--asset-naming',
+                '_assets/[name]-[hash].[ext]',
                 ...externals.flatMap((ext) => ['--external', ext]),
             ], { stdout: 'inherit', stderr: 'inherit' });
             if ((await esm.exited) !== 0) {