tosijs-ui 1.16.2 → 1.16.4

package/CHANGELOG.md

@@ -1,5 +1,88 @@
 # Changelog
 
+## 1.16.4
+
+A patch: the example console becomes a tab with a REPL, test-only examples render on deployed
+sites, and the doc nav search gets a clear button in every browser. The console's move from a
+panel under the preview to a tab changes how live examples look; it ships as a patch because
+live examples are a developer-facing tool. It does remove the panel's styling hooks: the
+`[part="console"]` element, the `-has-console` class, and `console` from the `ExampleParts`
+type. Nothing in tosijs-ui used them, and a site that styled the 1.16.2 panel should restyle
+`.example-console` in the tab instead. `dist/iife.js` grows by 1.7 kB gzip (477.0 → 478.7 kB).
+
+### The example console is a tab, and a REPL
+
+What an example logs now appears in a **Console** tab beside its code, instead of a panel under
+its preview, so the preview is never squeezed. The tab is also a REPL: type an expression and
+press Enter to evaluate it inside the example's own scope (its top-level variables and
+functions, `preview`, its `console`, the page's modules), as in the browser's console: input
+gives its value, `await` works, Shift+Enter adds a line, and ↑/↓ recall what you've entered.
+The REPL costs nothing until it's used: the first input re-runs the example once to give it
+the example's scope. The error that stopped an
+example appears there too. `exampleConsole: false` and `{"console": false}` still turn it off.
+
+### A test-only example shows its results on deployed sites too
+
+A ` ```test ` fence with nothing beside it shows its results as its body, but it ran its tests
+only when the page's test toggle was on. That toggle is off by default anywhere but localhost,
+so on every deployed site the example was an empty box. It now always runs its tests, because
+they are its content; ordinary examples still follow the toggle.
+
+### The doc navigation search has a clear button in every browser
+
+The doc system's nav search relied on `type="search"` for its clear (✕) button, which browsers
+draw inconsistently: Chromium only while the field is focused, Safari while it has text, and
+Firefox never. It now has its own ✕, shown whenever there's text, with the native one hidden so
+there's never two. Escape clears it as well.
+
+## 1.16.3
+
+A patch: iPhone menus that stay reachable, a Docs tab for live examples, and a way to declare
+your dialects once in the site config. Nothing changes for existing code, with one behaviour
+fix to know about: menus and other popped floats no longer close when an unrelated scroller
+on the page scrolls, only when a scroll moves the element they came from. `dist/iife.js` grows
+by 2.1 kB gzip (474.9 → 477.0 kB). 1.4 kB of that is the Docs tab loading its markdown renderer
+on first use: that keeps `marked` out of `tosijs-ui/live-example` for ESM apps, but the iife
+already contains the renderer, so there it only adds lazy-loading wrappers.
+
+### A Docs tab for live examples (#184)
+
+A dialect can document its source: `registerDialect(name, { …, docs(source, options) })` returns
+markdown, shown in a **Docs** tab beside the code. tjs-lang asked for it: in TJS the signature
+*is* the documentation. It's called only when someone opens the code panel, and again as they
+edit, so readers pay nothing. It works for `run` dialects too.
+
+The built-in `tjs` fills the tab from tjs-lang's own generator (`generateDocsMarkdown`) as soon
+as tjs-lang's browser bundle exports it; it doesn't yet, as of 0.14.0-rc.1. Until then, a site
+with the full tjs-lang can supply `docs` through a `tjs` override.
+
+### Declare your dialects once, in the site config (#2463)
+
+`dialects: ['ajs']` in a `tosijs-ui/site` config, plus any built-in you replace
+(`dialects: ['ajs', 'tjs']`), tells the build what your bundle registers with `registerDialect`:
+
+- The build-time highlighter leaves those fences alone, even when the name is also a Prism
+  grammar. Before, this needed a separate `registerLiveLanguage` call.
+- A replaced built-in isn't checked or pre-transpiled with the installed tjs-lang. That check
+  used to fail correct examples written for the site's own build.
+- On the page, a declared dialect that nothing registered is reported in the console, by name.
+
+### Menus on iPhone stay reachable (#2460)
+
+A long menu popped low on an iPhone ran below the visible screen, and scrolling the page to
+reach its last items dismissed it.
+
+- **Floats are sized to what's visible.** `positionFloat` now measures against
+  `window.visualViewport` instead of `100vh`/`100vw`. On Mobile Safari `100vh` is the large
+  viewport (as if the URL bar were hidden). A long menu now fits and scrolls inside itself.
+  Desktop browsers, where the two agree, see no change.
+- **Scrolling past a menu's end doesn't scroll the page** (`overscroll-behavior: contain`).
+- **A float closes only for a scroll that moves its anchor:** the page, or a scroller that
+  contains the element it was popped from. Before, any scroll anywhere closed a menu or
+  tooltip, such as a sidebar or a table re-rendering. `<tosi-float>` gained an `anchor`
+  property (`positionFloat`, and so `popFloat`, sets it); a submenu closes with its parent, and `<tosi-search-field>` now uses this rule rather than a
+  copy of its own.
+
 ## 1.16.2
 
 A patch: live examples show what they log, a spinner while a `run` dialect works, and three

package/dist/doc-browser.js

@@ -344,6 +344,44 @@ function logoMark(logo, projectLinks) {
     mark.classList.add('logo-mark');
     return mark;
 }
+// The nav search box: the field, and its own clear button over the field's right end.
+const navSearchStyleSpec = {
+    '.nav-search': {
+        position: 'relative',
+        margin: '5px',
+    },
+    '.nav-search input[type="search"]': {
+        width: '100%',
+        boxSizing: 'border-box',
+        // room for the clear button, so text never runs under it
+        paddingRight: varDefault.touchSize('44px'),
+    },
+    '.nav-search input[type="search"]::-webkit-search-cancel-button': {
+        display: 'none',
+    },
+    '.nav-search .nav-search-clear': {
+        position: 'absolute',
+        right: 0,
+        top: 0,
+        bottom: 0,
+        display: 'inline-flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        width: varDefault.touchSize('44px'),
+        padding: 0,
+        border: 'none',
+        boxShadow: 'none',
+        background: 'transparent',
+        color: 'inherit',
+        opacity: '0.5',
+    },
+    '.nav-search .nav-search-clear:hover, .nav-search .nav-search-clear:focus-visible': {
+        opacity: '1',
+    },
+    '.nav-search .nav-search-clear[hidden]': {
+        display: 'none',
+    },
+};
 const logoMarkStyleSpec = {
     '.logo-mark': {
         height: 'var(--tosi-logo-mark-size, 32px)',
@@ -565,8 +603,32 @@ export function createDocBrowser(options) {
         // section; while typing, matching sections expand via the needle branch.
         refreshNav(true);
     });
+    /*
+    The nav search's clear (✕) button. `type="search"` alone gave a clear affordance only in
+    some browsers and some states: Chromium shows its ✕ only while the field is focused, Safari
+    while it has text, Firefox never. So the field has its own, shown whenever there is text,
+    and the native one is hidden so there is never two. Escape clears too.
+    */
+    const updateSearchClear = () => {
+        searchClear.hidden = searchField.value === '';
+    };
+    const clearSearch = () => {
+        searchField.value = '';
+        updateSearchClear();
+        filterDocs();
+        searchField.focus();
+    };
+    const searchInput = () => {
+        updateSearchClear();
+        filterDocs();
+    };
+    const searchKeydown = (event) => {
+        if (event.key === 'Escape' && searchField.value !== '') {
+            event.preventDefault();
+            clearSearch();
+        }
+    };
     const searchField = input({
-        slot: 'nav',
         placeholder: 'search',
         // A placeholder is not a label: it is not a reliable accessible name, and it
         // disappears the moment anything is typed. This is the only text input in the
@@ -574,12 +636,18 @@ export function createDocBrowser(options) {
         // site built with `tosijs-ui/site`.
         'aria-label': 'Search documentation',
         type: 'search',
-        style: {
-            width: 'calc(100% - 10px)',
-            margin: '5px',
-        },
-        onInput: filterDocs,
+        onInput: searchInput,
+        onKeydown: searchKeydown,
     });
+    const searchClear = button({
+        type: 'button',
+        class: 'nav-search-clear',
+        title: 'Clear search',
+        'aria-label': 'Clear search',
+        hidden: true,
+        onClick: clearSearch,
+    }, icons.x());
+    const searchBox = div({ slot: 'nav', class: 'nav-search' }, searchField, searchClear);
     // Memory routing is decoupled from the page URL, so it ignores browser
     // back/forward (the host owns history, if any).
     if (!memoryRouting) {
@@ -1462,7 +1530,7 @@ export function createDocBrowser(options) {
             // The sidenav has just introduced itself; give it the layout the doc asked for.
             applyFullScreen();
         },
-    }, searchField, navContent, div({
+    }, searchBox, navContent, div({
         style: {
             position: 'relative',
             overflowY: 'scroll',
@@ -1475,6 +1543,7 @@ export function createDocBrowser(options) {
     StyleSheet('test-indicators', testIndicatorStyleSpec);
     // Header brand-mark sizing (icon / <img> / inline-<svg>), one CSS var each.
     StyleSheet('doc-logo-mark', logoMarkStyleSpec);
+    StyleSheet('doc-nav-search', navSearchStyleSpec);
     // Floating widget for test status
     const testWidget = button({
         class: 'test-widget',

package/dist/doc-system/example-policy.d.ts

@@ -1,5 +1,20 @@
 /** Fence languages that EXECUTE. Everything else is display-only. */
 export declare const EXECUTABLE_LANGS: Set<string>;
+/**
+ * The languages that are an example's SOURCE block (its one executable slot). `js`, `tjs` and
+ * `ts` are built in; `registerLiveLanguage` adds more (`registerDialect` in
+ * `tosijs-ui/live-example` calls it, so a registered dialect's fences run).
+ *
+ * Kept here, beside `EXECUTABLE_LANGS`, because the same fence is judged in four places
+ * (grouping, save-to-source, the highlighter, the ePub) and they must all see a registered
+ * dialect or none of them may.
+ */
+export declare const BUILT_IN_DIALECTS: ReadonlySet<string>;
+/**
+ * `SiteConfig.dialects` as the rest of the system compares it: lowercased (fence languages
+ * are lowercase), so `dialects: ['TJS']` means `tjs` everywhere, not in some places.
+ */
+export declare function normalizeDialectNames(names?: readonly string[]): string[];
 /**
  * Make fences in `lang` live examples, as an example's source block.
  *

package/dist/doc-system/example-policy.js

@@ -34,7 +34,19 @@ export const EXECUTABLE_LANGS = new Set([
  * (grouping, save-to-source, the highlighter, the ePub) and they must all see a registered
  * dialect or none of them may.
  */
-const SOURCE_LANGS = new Set(['js', 'ts', 'tjs']);
+export const BUILT_IN_DIALECTS = new Set([
+    'js',
+    'ts',
+    'tjs',
+]);
+const SOURCE_LANGS = new Set(BUILT_IN_DIALECTS);
+/**
+ * `SiteConfig.dialects` as the rest of the system compares it: lowercased (fence languages
+ * are lowercase), so `dialects: ['TJS']` means `tjs` everywhere, not in some places.
+ */
+export function normalizeDialectNames(names = []) {
+    return [...new Set(names.map((name) => name.toLowerCase()))];
+}
 /**
  * Make fences in `lang` live examples, as an example's source block.
  *

package/dist/doc-system/site/check-examples-cli.js

@@ -42,11 +42,16 @@ child always assumed 'auto', so a `:static` fence — or any fence under `liveEx
 'opt-in'` that never runs — could still hard-fail the build (review major M2).
 */
 const liveExamples = (process.env.TOSI_LIVE_EXAMPLES || 'auto');
+// Built-ins the site replaces (SiteConfig.dialects), comma-separated (#2463).
+const overriddenDialects = (process.env.TOSI_OVERRIDDEN_DIALECTS || '')
+    .split(',')
+    .filter(Boolean);
 const corpus = JSON.parse(await Bun.file(docsJson).text());
 const { problems, warnings, bakes, skipped } = await checkExamples(corpus, {
     ...(contextKeys.length ? { contextKeys } : {}),
     ...(importPrefix ? { importPrefix } : {}),
     liveExamples,
+    overriddenDialects,
 });
 // stdout is the channel — the parent parses this. Anything else this process prints
 // (warnings from the transform, say) goes to stderr so it can't corrupt the payload.

package/dist/doc-system/site/check-examples.d.ts

@@ -48,6 +48,12 @@ export declare function checkExamples(docs: Doc[], opts?: {
     importPrefix?: string;
     /** Mirrors `SiteConfig.liveExamples`. A fence that will never run must not fail a build. */
     liveExamples?: ExamplePolicy;
+    /**
+     * Built-in dialects the site replaces with its own transform (`SiteConfig.dialects`):
+     * not checked and not pre-transpiled here, because the installed tjs-lang is not what
+     * runs them, and checking would fail correct examples written for the site's own (#2463).
+     */
+    overriddenDialects?: string[];
 }): Promise<ExampleCheck>;
 /** Format problems for a build log. */
 export declare function formatExampleProblems(problems: ExampleProblem[]): string;

package/dist/doc-system/site/check-examples.js

@@ -122,6 +122,7 @@ export async function checkExamples(docs, opts = {}) {
         if (!(await transformAvailable(d)))
             unavailable.add(d);
     const skipped = new Map();
+    const overridden = new Set(opts.overriddenDialects ?? []);
     for (const doc of docs) {
         for (const block of collectCodeTokens(doc.text)) {
             /*
@@ -144,6 +145,8 @@ export async function checkExamples(docs, opts = {}) {
                 continue;
             // `test` blocks are conventional JS/TS, transpiled as plain js.
             const dialect = block.lang === 'test' ? 'js' : block.lang;
+            if (block.lang !== 'test' && overridden.has(dialect))
+                continue;
             if (unavailable.has(dialect)) {
                 skipped.set(dialect, (skipped.get(dialect) ?? 0) + 1);
                 continue;

package/dist/doc-system/site/epub-cli.js

@@ -13,10 +13,17 @@ the Bun.build note in orchestrator.ts.
 Build-time only. Never import this from browser code.
 */
 import { buildEpub } from './epub.js';
+import { BUILT_IN_DIALECTS, normalizeDialectNames, registerLiveLanguage, } from '../example-policy.js';
 const payloadPath = process.argv[2];
 if (!payloadPath) {
     console.error('epub-cli: expected a payload file path');
     process.exit(1);
 }
 const { config, opts } = JSON.parse(await Bun.file(payloadPath).text());
+// Declared dialects are live examples here too, or the ePub's example numbering (and so its
+// "run this example live" links) drifts from the page's after the first one (review F3).
+for (const name of normalizeDialectNames(config.dialects)) {
+    if (!BUILT_IN_DIALECTS.has(name))
+        registerLiveLanguage(name);
+}
 await buildEpub(config, opts ?? {});

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

@@ -11,6 +11,8 @@ runs as a SEPARATE subprocess on purpose — importing the full tosijs module or
 the icon system here would put src/icon-data.ts into `bun --watch`'s graph and
 cause an endless rebuild loop.
 */
+import { pageGlobalsHead } from './page-globals.js';
+import { BUILT_IN_DIALECTS, normalizeDialectNames, registerLiveLanguage, } from '../example-policy.js';
 import * as path from 'path';
 import { namedBooks, partitionByBook, DEFAULT_BOOK } from '../book-target.js';
 import { listEpubVolumes, renderEpubDownloads } from './epub-volumes.js';
@@ -67,6 +69,9 @@ async function buildEpubInChild(config, opts) {
             lang: config.lang,
             name: config.name,
             outputDir: config.outputDir,
+            // the ePub's "run this example live" links count examples the way the page does, so it
+            // must know the site's dialects too (1.16.3 review F3)
+            dialects: config.dialects,
         },
         opts,
     };
@@ -113,7 +118,7 @@ const escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
  * because the health-conscious path is unavailable. A child that runs and reports
  * problems is not a failure — that is the whole point of it.
  */
-async function checkExamplesInChild(docsJson, importPrefix, contextKeys = [], liveExamples = 'auto') {
+async function checkExamplesInChild(docsJson, importPrefix, contextKeys = [], liveExamples = 'auto', overriddenDialects = []) {
     const cliTs = `${import.meta.dir}/check-examples-cli.ts`;
     const cli = existsSync(cliTs)
         ? cliTs
@@ -129,6 +134,8 @@ async function checkExamplesInChild(docsJson, importPrefix, contextKeys = [], li
                 ...(importPrefix ? { TOSI_IMPORT_PREFIX: importPrefix } : {}),
                 // A fence that will never run must not fail a build (major M2).
                 TOSI_LIVE_EXAMPLES: liveExamples,
+                // Built-ins the site replaces: its transform runs them, not ours (#2463).
+                TOSI_OVERRIDDEN_DIALECTS: overriddenDialects.join(','),
             },
         });
         // Drain BOTH pipes while awaiting exit. An undrained pipe fills its buffer, the
@@ -657,7 +664,7 @@ export async function buildSite(config, opts = {}) {
             if (config.checkExamples !== false) {
                 const { problems, warnings, bakes } = await checkExamplesInChild(DOCS_JSON, resolverPrefix, typeof config.checkExamples === 'object'
                     ? config.checkExamples.contextKeys ?? []
-                    : [], config.liveExamples ?? 'auto');
+                    : [], config.liveExamples ?? 'auto', normalizeDialectNames(config.dialects).filter((name) => BUILT_IN_DIALECTS.has(name)));
                 exampleBakes = bakes;
                 // Unsupported imports don't fail the build — the code isn't broken, it just
                 // can't run in the doc environment (almost always illustrative code that
@@ -1199,18 +1206,9 @@ export async function buildSite(config, opts = {}) {
             catch {
                 // tjs-lang not installed — live examples fall back to the CDN chain
             }
-            /*
-            The example policy, stamped for the client the same way `__TJS_LOCAL_BASE` is (#140).
-            Only emitted when it differs from the default, so an `auto` site's HTML is unchanged
-            byte-for-byte and no existing corpus moves.
-            */
-            const policyHead = config.liveExamples === 'opt-in'
-                ? `<script>globalThis.__TOSI_EXAMPLE_POLICY="opt-in"</script>`
-                : '';
-            // Likewise only when switched off, so a default site's HTML does not change.
-            const consoleHead = config.exampleConsole === false
-                ? `<script>globalThis.__TOSI_EXAMPLE_CONSOLE=false</script>`
-                : '';
+            // The site config's client-side switches (example policy, example console), stamped as
+            // globals in <head> — only when they differ from the default. See page-globals.ts.
+            const globalsHead = pageGlobalsHead(config);
             // Optional (tjs-lang 0.11+): the import-resolver service worker. Lets live examples
             // import real npm packages from anywhere — bare specifiers the doc-system doesn't
             // inject become `/<prefix>/<spec>` requests the worker resolves + caches. GATED behind
@@ -1405,6 +1403,12 @@ export async function buildSite(config, opts = {}) {
                 .digest('hex')
                 .slice(0, 12);
             const docs = JSON.parse(docsJsonText);
+            // Declared dialects are live fences at build time too, so the static highlighter
+            // leaves their source alone (#2463). Idempotent: a watch rebuild re-adds the same names.
+            for (const name of normalizeDialectNames(config.dialects)) {
+                if (!BUILT_IN_DIALECTS.has(name))
+                    registerLiveLanguage(name);
+            }
             const pageCount = await generateSite({
                 liveExamples: config.liveExamples,
                 docs,
@@ -1423,13 +1427,7 @@ export async function buildSite(config, opts = {}) {
                 // instead of the classic IIFE. See the ESM hydration bundle above.
                 hydrateUrl: hydrateName ? `/${hydrateName}` : undefined,
                 bakes: exampleBakes,
-                headExtra: [
-                    config.headExtra,
-                    tjsHead,
-                    policyHead,
-                    consoleHead,
-                    importResolverHead,
-                ]
+                headExtra: [config.headExtra, tjsHead, globalsHead, importResolverHead]
                     .filter(Boolean)
                     .join('') || undefined,
                 scriptUrl: config.scriptUrl,

package/dist/doc-system/site/page-globals.d.ts

@@ -0,0 +1,6 @@
+export interface PageGlobalsConfig {
+    liveExamples?: 'auto' | 'opt-in';
+    exampleConsole?: boolean;
+    dialects?: string[];
+}
+export declare function pageGlobalsHead(config: PageGlobalsConfig): string;

package/dist/doc-system/site/page-globals.js

@@ -0,0 +1,25 @@
+/*
+The client-side switches a site config sets, stamped into each page's <head> as globals the
+bundle reads when it runs (so they must come BEFORE the bundle script — generate-site puts
+`headExtra` in <head>, and the bundle loads at the end of <body>).
+
+Each is emitted only when it differs from the default, so a default site's HTML is unchanged
+byte-for-byte when a new switch is added.
+*/
+import { normalizeDialectNames } from '../example-policy.js';
+export function pageGlobalsHead(config) {
+    return [
+        // #140: which fences run
+        config.liveExamples === 'opt-in'
+            ? `<script>globalThis.__TOSI_EXAMPLE_POLICY="opt-in"</script>`
+            : '',
+        // 1.16.2: the example console
+        config.exampleConsole === false
+            ? `<script>globalThis.__TOSI_EXAMPLE_CONSOLE=false</script>`
+            : '',
+        // 1.16.3: the dialects the site says its bundle registers, so the page can check
+        config.dialects?.length
+            ? `<script>globalThis.__TOSI_DIALECTS=${JSON.stringify(normalizeDialectNames(config.dialects)).replace(/</g, '\\u003c')}</script>`
+            : '',
+    ].join('');
+}

package/dist/doc-system/site/site-config.d.ts

@@ -130,12 +130,24 @@ export interface SiteConfig {
      */
     liveExamples?: 'auto' | 'opt-in';
     /**
-     * Show what a live example logs in a console under its preview (default `true`, 1.16.2).
-     * The panel appears only once an example logs something. `false` turns it off site-wide;
+     * Give live examples a Console tab: what the example logs, and a REPL in its scope (default
+     * `true`; a tab since 1.16.4, a panel under the preview in 1.16.2–1.16.3). `false` turns it off site-wide;
      * logs still reach the browser's devtools. One example opts out with the fence option
      * `{"console": false}`.
      */
     exampleConsole?: boolean;
+    /**
+     * The live-example dialects your bundle registers with `registerDialect` (1.16.3, #2463):
+     * your own (`['ajs']`) and any built-in you replace (`['tjs']`). Declaring them here is
+     * what keeps the build and the page in agreement:
+     *
+     * - a declared language is a live example at build time too, so the static highlighter
+     *   leaves its source alone (otherwise a name that is also a Prism grammar is tokenized);
+     * - a declared BUILT-IN (`js`, `tjs`, `ts`) is not checked or pre-transpiled by the build,
+     *   because your transform is the one that runs;
+     * - on the page, a declared dialect nobody registered is reported in the console, by name.
+     */
+    dialects?: string[];
     /** modules to leave external in the bundle, e.g. ['jolt-physics'] */
     bundleExternals?: string[];
     /**

package/dist/float.d.ts

@@ -7,6 +7,11 @@ declare const TosiFloat_base: import("tosijs").WithAttributes<{
 export declare class TosiFloat extends TosiFloat_base {
     static preferredTagName: string;
     static floats: Set<TosiFloat>;
+    /**
+     * The element this float was popped from (set by `popFloat`). Only a scroll that moves it
+     * (the page, or a scroller containing it) triggers `remainOnScroll`. `null`: any scroll does.
+     */
+    anchor: Element | null;
     content: HTMLSlotElement;
     static shadowStyleSpec: {
         ':host': {

package/dist/float.js

@@ -82,8 +82,10 @@ shadow and background and so on.
 - `remain-on-resize` 'remove' | 'hide' | 'remain' — by default, floats will hide if the window is resized
 - `remain-on-scroll` 'remain' | 'remove' | 'hide' — by default, floats will remain if the document is scrolled
 
-Note that `remain-on-scroll` behavior applies to any scrolling in the document (including within the float) so
-if you want finer-grained disappearing behavior triggered by scrolling, you might want to implement it yourself.
+A float made by `popFloat` (menus, tooltips) has an **anchor**, the element it was popped from, and only a
+scroll that MOVES the anchor (the page, or a scroller containing it) hides or removes it. Before 1.16.3 any
+scroll anywhere did, so filtering a table on every keystroke (which scrolls it) closed a menu or hint list the
+moment it opened. A float with no anchor still reacts to any scroll outside itself.
 
 To prevent dragging for an interior element (e.g. if you want a floating palette with buttons or input fields)
 just add the `no-drag` class to an element or its container.
@@ -99,6 +101,11 @@ export class TosiFloat extends withAttributes({
 }) {
     static preferredTagName = 'tosi-float';
     static floats = new Set();
+    /**
+     * The element this float was popped from (set by `popFloat`). Only a scroll that moves it
+     * (the page, or a scroller containing it) triggers `remainOnScroll`. `null`: any scroll does.
+     */
+    anchor = null;
     content = slot();
     static shadowStyleSpec = {
         ':host': {
@@ -154,6 +161,40 @@ export const XinFloat = TosiFloat;
 export const tosiFloat = TosiFloat.elementCreator();
 /** @deprecated Use tosiFloat instead */
 export const xinFloat = tosiFloat;
+/*
+Does this scroll move the anchor? The page scrolling does; so does any scroller that contains it,
+across shadow roots (a menu popped from inside a component's shadow DOM is still moved by a
+scroller around the component). Any other scroller — a table re-filtering, a sidebar — doesn't.
+*/
+function scrollMovesAnchor(scrolled, anchor) {
+    if (anchor === null)
+        return true;
+    if (scrolled === document ||
+        scrolled === document.documentElement ||
+        scrolled === document.body)
+        return true;
+    if (!(scrolled instanceof Node))
+        return true;
+    const visited = new Set(); // floats anchored inside each other must not loop
+    for (let node = anchor; node && !visited.has(node);) {
+        visited.add(node);
+        if (node === scrolled)
+            return true;
+        /*
+        A float's anchor can be INSIDE another float — a submenu's anchor is an item of its parent
+        menu, and the parent float is mounted on <body>, so walking up from it never meets the
+        scroller around the root menu button. Continue from the containing float's own anchor:
+        a chain of menus moves (and closes) together. Before this, scrolling that scroller closed
+        the parent and left the submenu on screen, orphaned (1.16.3 review B1).
+        */
+        if (node instanceof TosiFloat && node.anchor) {
+            node = node.anchor;
+            continue;
+        }
+        node = node.parentNode ?? node.host ?? null;
+    }
+    return false;
+}
 // Register the global reposition/dismiss handlers on first float connecting,
 // not at import (keeps the module side-effect-free for tree-shaking). They
 // iterate TosiFloat.floats, so they're no-ops until a float exists — registered
@@ -179,6 +220,8 @@ function ensureFloatListeners() {
             return;
         }
         Array.from(TosiFloat.floats).forEach((float) => {
+            if (!scrollMovesAnchor(event.target, float.anchor))
+                return;
             if (float.remainOnScroll === 'hide') {
                 float.hidden = true;
             }