tosijs-ui 1.9.8 → 1.10.0

package/CHANGELOG.md

@@ -1,5 +1,115 @@
 # Changelog
 
+## 1.10.0
+
+Mostly a **silent-failure** release: several things that were quietly not working, or quietly
+not being checked, now say so. If you use `tosijs-ui/site`, three of these have probably cost
+you time already.
+
+### `<tosi-table>`
+
+**Scroll position survives a re-render.** Sorting, filtering, or toggling
+`visibleGroupedRowIds` no longer throws you back to the top. The table anchors on the
+**topmost visible row**, not on `scrollTop`, and restores that row to the same offset — the
+distinction matters as soon as the row count changes, because the same pixel offset then
+shows entirely different rows. Set `preserveScroll = false` for the case where a render means
+"here is a different dataset" and starting at the top is right.
+
+### The tunnel: links now work on a second device
+
+A magic link is redeemable **repeatedly for 15 minutes** instead of dying on first use. The
+old behaviour collided with the feature's own purpose: glance at a link and close the tab and
+you need a new one; open it on a laptop then reach for your phone and it is dead — in a
+workspace built for reading your uncommitted tree _on a phone_. One project had already
+replaced it with a never-expiring link of their own, which is the tell.
+
+The bound moved from _uses_ to _time_, not away. Set the level per project:
+
+```typescript
+tunnel: { linkPolicy: 'single-use', linkTtlMinutes: 2 }   // ratchet up
+```
+
+An expired link is refused under either policy — widening reuse never widens lifetime.
+
+Every user-facing string — including the line the CLI prints at the moment you share a link
+— is derived from the policy in force, rather than asserting "single-use" regardless.
+
+### Silent failures, now loud
+
+- **`docPaths` are watched.** A root-level doc was served and rendered but never watched:
+  edit, save, refresh, stale page, no rebuild, no message — indistinguishable from a browser
+  cache. (#49)
+- **Two builders on one output tree are refused,** naming the holder's pid and port. Both
+  wipe-then-repopulate `docs/`, so running a standalone build against a live dev server meant
+  each deleted what the other was writing; it killed a dev server with no error anywhere and
+  left `docs/` a fraction populated. A standalone `buildSite()` refuses; a second **dev
+  server** only warns and continues, because `bun playwright test` and `bun run test-browser`
+  each start their own and a hard failure there would break the lanes this protects. The lock
+  is stale-safe (a dead holder's lock is debris), re-entrant, released on Ctrl-C, and fails
+  open. (#51)
+- **A truncated `/*#` doc block warns, by name.** Block comments cannot nest, so a `*/`
+  inside a doc demo ends the doc there — previously surfacing as parse errors pointing at
+  _prose_, never at the delimiter responsible. (#70)
+- **Inline doc tests no longer under-report.** A page could report "done" before its examples
+  had run, so their tests were omitted rather than failed — silently, with the suite green.
+  **If you use `tosijs-ui/site` with async examples, your counts may have been wrong;** a
+  number that goes UP after upgrading is this fix.
+
+### Build output
+
+**The hydration bundle now builds into your site output, not `dist/`.** It was written into
+the library tree with only the `.js` copied out, stranding the sourcemap in a directory you
+publish and commit but never serve — 65 MiB across 216 packed blobs in one adopter, ~35% of
+that repo's packed blob store, for a file nothing could load. Set `bundleOutDir` if your
+bundle is itself a published artifact. If you have that history:
+`git rm --cached dist/iife.js dist/iife.js.map` and gitignore them. (#69)
+
+### Also in this release
+
+- **`checkExamples` accepts `{ contextKeys: [...] }`** as well as a boolean, so a library
+  that documents ITSELF — whose examples import its own package name — keeps the guard on
+  instead of disabling it. The keys are **added to** the `tosijs` / `tosijs-ui` defaults, not
+  substituted for them. (#71)
+- **`preview.tunnel.linkPolicy`** (`'window'` | `'single-use'`) and
+  **`preview.tunnel.linkTtlMinutes`** (default 15) set the link security level.
+- **`SiteConfig.preview.host` is optional.** The documented practice supplies it from
+  `PREVIEW_HOST`, so a correct config used to fail typecheck. (#72)
+- **`marked` peer is `^16.4.2 || ^17.0.0 || ^18.0.0`** — it was two majors behind `latest`, so
+  a consumer on a current marked got a peer violation on a fresh install. (#60)
+- **The live-example docs now state that `test()` bodies run concurrently** within a fence,
+  and give the rule that follows: steps that depend on each other belong in one `test()`.
+  (#43)
+- **`llms.txt` carries the browser-control affordance** when a project sets `haltijaDev`, so
+  an agent learns it can drive the running page instead of inferring behaviour from source.
+  (#18)
+- **Host bootstrap in `doc-site-system.md` now gives the actual commands** rather than
+  describing the danger and leaving the dangerous step as an exercise.
+- **`svg2DataUrl`: two real fixes, and one that is NOT done.** It wrote `strokeWidth` /
+  `strokeLinecap` / `strokeLinejoin` — names SVG ignores — on any element carrying inline
+  style, and explicit `fill` / `stroke` / `strokeWidth` arguments were clobbered by the style
+  pass. Both fixed.
+
+  **[#68](https://github.com/tonioloewald/tosijs-ui/issues/68) is NOT closed by this.** Most
+  icons carry their styling on the **root** `<svg>`, which this does not touch, so a
+  `stroked` icon — about 280 of ~287 — still serializes with no stroke at all and renders as
+  a solid black wedge. Verified after the fix: `svg2DataUrl(icons.chevronRight())` emits no
+  `stroke` and no `stroke-width`. Prefer inline `<svg>` over a data URL for stroked icons
+  until this lands.
+
+- **`acquireBuildLock` / `lockDecision`** in `build-lock.ts` — the
+  output-tree lock behind the concurrent-build refusal. **Internal**: not exported from
+  `tosijs-ui/site`, so do not build on it yet. Say so if you want it public.
+- New **`tosijs-caddy-install`** bin — installs the Caddy snippets the deploy/tunnel bins
+  need, **refuses** to install a template with placeholders left in it, keeps the outgoing
+  config as `Caddyfile.bak`, and is dry-run by default. That refusal was the reason this
+  existed as a private script; shipping the template without it was the wrong half to keep.
+- The unit lane now covers `bin/` — `bunfig.toml`'s test root was `./src`, so tests anywhere
+  else were silently never collected.
+
+> **Versioning note.** This is a patch that adds public API. Minors are for breaking changes
+> and feature rollouts; additive, non-breaking extensions ship as patches. The contract you
+> rely on is unchanged: **a patch never breaks you.**
+
 ## 1.9.8
 
 **Grouped tables can now say how much of a group is showing.** The piece missing from 1.9.7's
@@ -54,14 +164,23 @@ know anything about grouping. It is additive to the filter's own result, so a fi
 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.
+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** — transparent text plus `display: none` on
+element children, via `.tr:not(.table-cluster-first) .cluster-repeat`. Deliberately not
+`visibility: hidden`, which also stops the cell painting its **background**: a pinned
+column's background is the only thing masking the columns scrolling underneath it, so
+repeated cells there became windows onto the scrolled content. And never `display: none` on
+the cell itself — 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.
 
+Group ids are **memoized per render** in a `WeakMap` — the id is computed several times for
+one row in a single pass (clustering, parity, first-of-group, counts, then again per stamped
+row), and the inferred form does a `JSON.stringify` each time. The map is replaced on every
+render rather than kept, so a cached id can never outlive the values it came from.
+
 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

package/bin/caddy-install.ts

@@ -0,0 +1,204 @@
+#!/usr/bin/env bun
+/*
+Install the Caddy snippets `tosijs-deploy` / `tosijs-tunnel` depend on.
+
+  tosijs-caddy-install                      # DRY RUN — shows the diff, changes nothing
+  tosijs-caddy-install --go                 # substitute, validate, install, reload
+  tosijs-caddy-install --host=me@1.2.3.4 --go
+  tosijs-caddy-install --template=./my-Caddyfile --go
+
+Both deploy bins write a fragment ending in `import preview_site` / `import tunnel_site`,
+and those snippets have to exist on the box first — otherwise `caddy validate` fails on
+every deploy forever, per project, and nothing routes.
+
+This existed only as an inline `package.json` script in the tosijs-ui repo, so adopters got
+the template and the warning but not the tool. That is the wrong half to keep private: the
+template is inert text, while the VALUE here is the refusal to install it with placeholders
+intact. Installing `{{ACME_EMAIL}}` and `__PREVIEW_TOKEN__` verbatim gives you a preview host
+whose invite gate is a literal string published in a public repo, issuing certificates under
+someone else's Let's Encrypt account. A hand-rolled `sed` pipeline has no such guard.
+
+Three deliberate properties:
+
+  DRY RUN BY DEFAULT. This replaces `/etc/caddy/Caddyfile` wholesale. If the box serves
+  anything else through Caddy, that is destructive — so the dry run prints a diff against
+  the live file and you get to look at it before `--go`.
+
+  THE SECRET NEVER LEAVES THE BOX. Substitution happens remotely, reading
+  `/etc/caddy/preview.env`. `PREVIEW_TOKEN` is never transmitted, never appears in argv on
+  this machine, and is redacted out of the diff before it is printed.
+
+  VALIDATE BEFORE SWAP. `caddy fmt` then `caddy validate` run against a scratch file; the
+  live config is replaced by an atomic `mv` only once it is known to parse. A rejected
+  config leaves the running site untouched.
+*/
+
+import { existsSync, readFileSync } from 'fs'
+import { resolveSiteConfig } from './resolve-site-config'
+
+const siteConfig = await resolveSiteConfig()
+
+const args = process.argv.slice(2)
+const flag = (name: string): string | undefined => {
+  const hit = args.find((a) => a.startsWith(`--${name}=`))
+  return hit ? hit.slice(name.length + 3) : undefined
+}
+const has = (name: string): boolean => args.includes(`--${name}`)
+
+/*
+Reject anything we do not understand, BEFORE reaching the network.
+
+An unrecognised flag used to be ignored, so `--status` — which this bin has never had — read
+as "no flags at all" and the bin went straight on to ssh into the configured host. A tool
+that contacts someone's server must not treat an unknown instruction as consent to proceed.
+*/
+const KNOWN = ['--go', '--help']
+const unknown = args.filter(
+  (a) => !KNOWN.includes(a) && !/^--(host|template)=/.test(a)
+)
+if (unknown.length || has('help')) {
+  const bad = unknown.length
+  console.error(
+    (bad ? `\nUnknown option(s): ${unknown.join(' ')}\n` : '') +
+      `\ntosijs-caddy-install — install the Caddy snippets the deploy/tunnel bins need\n\n` +
+      `  tosijs-caddy-install                 DRY RUN — shows the diff, changes nothing\n` +
+      `  tosijs-caddy-install --go            substitute, validate, install, reload\n` +
+      `  --host=user@box                      override the configured preview host\n` +
+      `  --template=./path/to/Caddyfile       use your own template\n`
+  )
+  process.exit(bad ? 1 : 0)
+}
+
+const host =
+  flag('host') ??
+  process.env.PREVIEW_HOST ??
+  // Legacy alias. This repo's own `deploy:index` script still asks for PREVIEW_SSH,
+  // so someone who exported the only variable it ever mentioned would otherwise be
+  // told "No preview host" with nothing pointing at why.
+  process.env.PREVIEW_SSH ??
+  siteConfig.preview?.host
+const go = has('go')
+
+if (!host) {
+  console.error(
+    `\nNo preview host.\n\n` +
+      `  Set one once in your site config:\n` +
+      `      preview: { host: 'user@example.com' }\n\n` +
+      `  ...or pass it per-run:\n` +
+      `      tosijs-caddy-install --host=user@example.com --go\n` +
+      `      PREVIEW_HOST=user@example.com tosijs-caddy-install\n`
+  )
+  process.exit(1)
+}
+
+/*
+The template ships inside the package, so the default is resolved relative to THIS file
+rather than to the cwd — an adopter runs the bin from their own project, where `deploy/` is
+their business and not ours.
+*/
+const templatePath =
+  flag('template') ?? new URL('../deploy/Caddyfile', import.meta.url).pathname
+
+if (!existsSync(templatePath)) {
+  console.error(
+    `\nNo Caddyfile template at ${templatePath}\n\n` +
+      `  The package ships one at node_modules/tosijs-ui/deploy/Caddyfile.\n` +
+      `  Pass your own with --template=./path/to/Caddyfile\n`
+  )
+  process.exit(1)
+}
+
+const template = readFileSync(templatePath, 'utf8')
+
+// The template is delivered inside a quoted heredoc, so it is copied verbatim with no shell
+// expansion. A template containing the delimiter would truncate the file silently — refuse
+// rather than install something that is not what was read.
+const EOF_MARKER = 'TOSIJS_CADDY_TEMPLATE_EOF'
+if (template.split('\n').some((line) => line.trim() === EOF_MARKER)) {
+  console.error(
+    `\nTemplate contains the line \`${EOF_MARKER}\`, which is used as the transfer\n` +
+      `delimiter. Rename that line in ${templatePath}.\n`
+  )
+  process.exit(1)
+}
+
+const remoteScript = `set -euo pipefail
+umask 077
+cat > /etc/caddy/Caddyfile.tpl <<'${EOF_MARKER}'
+${template}
+${EOF_MARKER}
+
+if [ ! -f /etc/caddy/preview.env ]; then
+  echo "No /etc/caddy/preview.env on this box." >&2
+  echo "Create it with PREVIEW_TOKEN=, ACME_EMAIL= and PREVIEW_DOMAIN=." >&2
+  exit 1
+fi
+set -a; . /etc/caddy/preview.env; set +a
+: "\${PREVIEW_TOKEN:?set PREVIEW_TOKEN in /etc/caddy/preview.env}"
+: "\${ACME_EMAIL:?set ACME_EMAIL in /etc/caddy/preview.env}"
+: "\${PREVIEW_DOMAIN:?set PREVIEW_DOMAIN in /etc/caddy/preview.env}"
+
+sed -e "s|__PREVIEW_TOKEN__|\$PREVIEW_TOKEN|g" \\
+    -e "s|{{ACME_EMAIL}}|\$ACME_EMAIL|g" \\
+    -e "s|{{PREVIEW_DOMAIN}}|\$PREVIEW_DOMAIN|g" \\
+    /etc/caddy/Caddyfile.tpl > /etc/caddy/Caddyfile.new
+
+if grep -qE '\\{\\{|__PREVIEW_TOKEN__' /etc/caddy/Caddyfile.new; then
+  echo "Unsubstituted placeholders remain — refusing to install:" >&2
+  grep -nE '\\{\\{|__PREVIEW_TOKEN__' /etc/caddy/Caddyfile.new >&2
+  rm -f /etc/caddy/Caddyfile.new
+  exit 1
+fi
+
+caddy fmt --overwrite /etc/caddy/Caddyfile.new
+caddy validate --config /etc/caddy/Caddyfile.new
+
+if [ "${go ? '1' : '0'}" = "1" ]; then
+  # Keep the outgoing config. This replaces a file that may be serving OTHER sites, and
+  # "validated" only means it parses — it does not mean it is the config you wanted.
+  if [ -f /etc/caddy/Caddyfile ]; then
+    cp -p /etc/caddy/Caddyfile /etc/caddy/Caddyfile.bak
+  fi
+  mv /etc/caddy/Caddyfile.new /etc/caddy/Caddyfile
+  systemctl reload caddy
+  echo "Installed /etc/caddy/Caddyfile and reloaded caddy."
+  echo "Previous config saved as /etc/caddy/Caddyfile.bak"
+else
+  echo "--- would change /etc/caddy/Caddyfile (token redacted) ---"
+  if [ -f /etc/caddy/Caddyfile ]; then
+    diff -u /etc/caddy/Caddyfile /etc/caddy/Caddyfile.new \\
+      | sed "s|\$PREVIEW_TOKEN|***REDACTED***|g" || true
+  else
+    echo "(no existing /etc/caddy/Caddyfile — this would create it)"
+  fi
+  rm -f /etc/caddy/Caddyfile.new
+  echo "--- dry run: nothing changed. Re-run with --go to install. ---"
+fi`
+
+console.log(
+  `${
+    go ? 'Installing' : 'Checking'
+  } Caddy config on ${host} from ${templatePath}\n`
+)
+
+// The script goes over stdin rather than as an argv string: it contains the template
+// verbatim, and quoting an arbitrary file through a shell argument is a bug waiting to
+// happen.
+const proc = Bun.spawn(['ssh', host, 'bash', '-s'], {
+  stdin: new TextEncoder().encode(remoteScript),
+  stdout: 'inherit',
+  stderr: 'inherit',
+})
+const exitCode = await proc.exited
+
+if (exitCode !== 0) {
+  console.error(`\nFailed (exit ${exitCode}). Nothing was installed.\n`)
+  process.exit(exitCode)
+}
+
+if (!go) {
+  console.log(
+    `\nNext: re-run with --go once the diff above looks right.\n` +
+      `Then \`tosijs-deploy --go\` and \`tosijs-tunnel\` will validate.\n`
+  )
+}

package/bin/deploy-preview.ts

@@ -51,7 +51,14 @@ const preview = siteConfig.preview
 // Precedence: explicit flag > env > site config. The config is the "just works"
 // default; the flag exists so you can push a one-off somewhere else without editing
 // (and committing) a config file.
-const host = flag('host') ?? process.env.PREVIEW_HOST ?? preview?.host
+const host =
+  flag('host') ??
+  process.env.PREVIEW_HOST ??
+  // Legacy alias. This repo's own `deploy:index` script still asks for PREVIEW_SSH,
+  // so someone who exported the only variable it ever mentioned would otherwise be
+  // told "No preview host" with nothing pointing at why.
+  process.env.PREVIEW_SSH ??
+  preview?.host
 const remotePath =
   flag('path') ??
   process.env.PREVIEW_PATH ??

package/bin/tunnel.ts

@@ -5,7 +5,7 @@ Expose THIS machine's dev server at an authenticated public URL.
   tosijs-tunnel          # open the tunnel (foreground; Ctrl-C closes it)
   tosijs-tunnel --status # is one already up?
   tosijs-tunnel --close  # close any tunnel this project opened
-  tosijs-tunnel --link   # ask the dev server to print a fresh single-use edit link
+  tosijs-tunnel --link   # ask the dev server to print a fresh edit link
 
 (In this repo `bun run tunnel` is a shortcut for the same thing.)
 
@@ -49,7 +49,14 @@ const flag = (n: string) => {
 }
 
 const preview = siteConfig.preview
-const host = flag('host') ?? process.env.PREVIEW_HOST ?? preview?.host
+const host =
+  flag('host') ??
+  process.env.PREVIEW_HOST ??
+  // Legacy alias. This repo's own `deploy:index` script still asks for PREVIEW_SSH,
+  // so someone who exported the only variable it ever mentioned would otherwise be
+  // told "No preview host" with nothing pointing at why.
+  process.env.PREVIEW_SSH ??
+  preview?.host
 const localPort = Number(
   flag('port') ?? resolveDevPort(siteConfig, process.env)
 )

package/dist/data-table.d.ts

@@ -96,7 +96,11 @@ export declare class TosiTable extends WebComponent {
             background: string;
         };
         ':host .tr:not(.table-cluster-first) .cluster-repeat': {
-            visibility: string;
+            color: string;
+            userSelect: string;
+        };
+        ':host .tr:not(.table-cluster-first) .cluster-repeat > *': {
+            display: string;
         };
         ':host .tr.table-cluster-odd': {
             _tosiTableBg: string;
@@ -155,6 +159,7 @@ export declare class TosiTable extends WebComponent {
         nohide: boolean;
         noreorder: boolean;
         localized: boolean;
+        nopreservescroll: boolean;
     };
     selectionChanged: SelectCallback;
     rowRendered: ((item: any, cells: HTMLElement[]) => void) | null;
@@ -200,6 +205,7 @@ export declare class TosiTable extends WebComponent {
     get nonRepeatingGroupedRowCells(): string[] | null;
     set nonRepeatingGroupedRowCells(props: string[] | null);
     /** The grouping function in force, or null when the table is ungrouped. */
+    private _groupIdMemo;
     private get groupIdFn();
     /**
      * This row's group id, or null when the table is ungrouped.
@@ -223,6 +229,24 @@ export declare class TosiTable extends WebComponent {
     get rowGroupCounts(): Map<string, GroupCount>;
     private _grouping;
     private _rowGroupCounts;
+    /**
+     * Keep the reader in place across a re-render (default `true`).
+     *
+     * Set `false` when a render means "here is a different dataset" rather than "here is the
+     * same data, re-viewed" — then starting at the top is the correct answer.
+     *
+     * Backed by the `nopreservescroll` ATTRIBUTE so it is settable from markup like every
+     * other boolean here (`nosort`, `nohide`, `noreorder`). The inverted name is not
+     * gratuitous: this defaults to `true`, and a presence-only attribute can only ever turn
+     * something ON — so a `preservescroll` attribute could never express "off", which is the
+     * only thing anyone needs to say. Getting this wrong is unfixable after release without a
+     * rename, so it is settled here rather than later.
+     */
+    get preserveScroll(): boolean;
+    set preserveScroll(value: boolean);
+    /** In-flight scroll restore, so a newer one supersedes it and gestures can cancel it. */
+    private _scrollRestore;
+    private _scrollAnchor;
     get sort(): SortCallback | undefined;
     set sort(sortFunc: SortCallback | undefined);
     get columns(): ColumnOptions[];
@@ -269,6 +293,8 @@ export declare class TosiTable extends WebComponent {
     private updateSelection;
     private findCell;
     private _pendingFocus;
+    private captureScrollAnchor;
+    private restoreScrollAnchor;
     private handleScrollEnd;
     private focusCell;
     private handleKeyNav;