tosijs-ui 1.16.3 → 1.16.5

package/CHANGELOG.md

@@ -1,5 +1,100 @@
 # Changelog
 
+## 1.16.5
+
+A patch, mostly found by using the doc site on an iPhone: menus that stay on screen as Safari's
+toolbars come and go, a code panel that fits the visible screen, and a REPL that completes as
+you type (touchably, case-insensitively, with `$` and `$$`). Also quiet under tosijs 1.10.7's
+long-list advice, and `pinnedTopRows` now works from the element creator. `dist/iife.js` grows
+by 3.6 kB gzip (478.7 → 482.2 kB), including the move to tosijs 1.10.7, which it bundles.
+
+**One read-side change to check for:** `<tosi-table>`'s `pinnedTopRows` and `pinnedBottomRows`
+now read as `null` rather than `undefined` when unset (typed `any[] | null`). That is what makes
+them work when passed to the element creator. Code that tested `table.pinnedTopRows ===
+undefined` should test `== null` instead; truthiness checks are unaffected.
+
+### `$` and `$$` in the REPL
+
+As in a browser console: `$('.thing')` returns the first match and `$$('.thing')` an array of all
+of them, within the example's own preview. An example's own `$`, or a page's jQuery, takes
+precedence.
+
+### The Console tab's REPL completes as you type
+
+Typing a name, or a dot after a value, opens a list of suggestions above the prompt: the
+value's properties (prototype chain included) or the names in scope (the example's own,
+`preview`, `console`, the page's modules, globals). Tap one, or use ↓/↑ and Enter; Tab takes the
+highlighted or first suggestion, and Escape closes the list. Rows are touch-sized, so it works
+on a phone, where there is no Tab key and no browser console at all. Matching ignores case, and
+the field turns off iOS's auto-capitalisation and autocorrect; the example's own names rank
+above globals.
+
+### Quiet under tosijs 1.10.7's long-list advice; `pinnedTopRows` works from the creator
+
+tosijs 1.10.7 warns once about any list binding of more than 10 items that has neither
+`virtual` nor a `nonVirtualReason`. tosijs-ui builds some lists its users can't reach, so it now
+gives the reason itself:
+
+- `<tosi-table>`'s pinned rows, which are always on screen;
+- its body under `rowHeight: 0`, which is the author choosing to render every row (the table's
+  own warning still fires past 1,000 rows);
+- the doc browser's flat nav in `routing: 'query'`.
+
+While testing this, `tosiTable({ pinnedTopRows: [...] })` (and `pinnedBottomRows`) turned out to
+be silently ignored when passed to the element creator: the getter returned `undefined` when
+unset, so tosijs set an attribute instead. It now returns `null` when unset, and the creator
+works (see the note at the top of these notes). The dev dependency moves to tosijs 1.10.7; the peer range is unchanged (`^1.10.3`).
+
+### Menus stay inside the screen on iPhone as Safari's toolbars come and go
+
+A menu's room was measured once, when it opened. Mobile Safari then shows and hides its toolbars
+(and the keyboard comes and goes) as you touch the page, which changes the visible area without
+a window resize, so a menu measured a moment earlier ran under the toolbar. Open floats (menus,
+tooltips, hint lists) are now re-fitted to their anchor whenever the visible viewport changes.
+Draggable floats are left where they are. Reported by the maintainer on an iPhone (the other
+half of #2460).
+
+### The Console tab's REPL is reachable on iPhone
+
+A full-screen example (the code panel, or maximized) was sized `100vh`, which on iPhone Safari is
+the height without the browser toolbar, so the bottom of the panel sat under it, and that is
+where the Console tab's REPL input lives. It is now sized to the visible viewport (`100dvh`).
+
+## 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

package/dist/data-table.d.ts

@@ -243,10 +243,10 @@ export declare class TosiTable extends TosiTable_base {
     private _nonRepeatingGroupedRowCells;
     private _pinnedTopRows?;
     private _pinnedBottomRows?;
-    get pinnedTopRows(): any[] | undefined;
-    set pinnedTopRows(rows: any[] | undefined);
-    get pinnedBottomRows(): any[] | undefined;
-    set pinnedBottomRows(rows: any[] | undefined);
+    get pinnedTopRows(): any[] | null;
+    set pinnedTopRows(rows: any[] | null | undefined);
+    get pinnedBottomRows(): any[] | null;
+    set pinnedBottomRows(rows: any[] | null | undefined);
     get effectivePinnedTopData(): any[];
     get effectivePinnedBottomData(): any[];
     private get effectiveBaseData();

package/dist/data-table.js

@@ -1578,15 +1578,20 @@ export class TosiTable extends withAttributes({
     // count-based slicing.
     _pinnedTopRows;
     _pinnedBottomRows;
+    /*
+    `null`, not `undefined`, when unset: tosijs's element creator assigns a prop as a PROPERTY only
+    when the instance's current value isn't `undefined`, and otherwise as an attribute — so
+    `tosiTable({ pinnedTopRows: [...] })` was silently ignored (tosijs board #2464).
+    */
     get pinnedTopRows() {
-        return this._pinnedTopRows;
+        return this._pinnedTopRows ?? null;
     }
     set pinnedTopRows(rows) {
         this._pinnedTopRows = rows ? tosiValue(rows) : undefined;
         this.queueRender();
     }
     get pinnedBottomRows() {
-        return this._pinnedBottomRows;
+        return this._pinnedBottomRows ?? null;
     }
     set pinnedBottomRows(rows) {
         this._pinnedBottomRows = rows ? tosiValue(rows) : undefined;
@@ -2364,7 +2369,11 @@ export class TosiTable extends withAttributes({
         the visible data, so they have no parity, and blanking their non-repeating cells
         would empty a pinned header/summary row purely because it is not in `firstRows`.
         */
-        (_elements, item) => this.buildRow(item, cols, stickyInfo, rowClass, false), {});
+        (_elements, item) => this.buildRow(item, cols, stickyInfo, rowClass, false), 
+        // tosijs warns about long unvirtualised lists (1.10.7); the author can't reach this one
+        {
+            nonVirtualReason: 'pinned rows are always on screen, so every one is rendered (a handful by design)',
+        });
         return div({
             class: `tbody tbody-${region}`,
             role: 'rowgroup',
@@ -3338,7 +3347,17 @@ export class TosiTable extends withAttributes({
         // The visible-rows listBinding is bound directly to .scroll-area so
         // virtualisation observes the same scroll container that sticky cells
         // stick against.
-        const visibleBinding = this.rowData.visible.listBinding((_elements, item) => this.buildRow(item, cols, stickyInfo), this.rowHeight > 0 ? { virtual: { height: this.rowHeight } } : {});
+        const visibleBinding = this.rowData.visible.listBinding((_elements, item) => this.buildRow(item, cols, stickyInfo), this.rowHeight > 0
+            ? { virtual: { height: this.rowHeight } }
+            : /*
+              `rowHeight: 0` IS the author saying "render every row" (documented for small tables
+              and variable row heights), so say so to tosijs rather than have it warn about a choice
+              already made. A table big enough for that to hurt still gets <tosi-table>'s own
+              warning past NON_VIRTUAL_ROW_ADVICE rows (#84).
+              */
+                {
+                    nonVirtualReason: 'rowHeight: 0 — the author chose to render every row (<tosi-table> warns past 1,000)',
+                });
         this._scrollArea = div({ class: 'scroll-area', part: 'visibleRows' }, ...[
             this._head,
             this._tbodyTop,

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) {
@@ -1422,6 +1490,9 @@ export function createDocBrowser(options) {
                 idPath: 'filename',
                 hiddenProp: 'hidden',
                 value: app.docs,
+                // the flat nav (query routing) lists every doc so the search can filter it and a
+                // reader can scan it; the site's author can't reach this binding to say so
+                nonVirtualReason: 'doc navigation: every doc is listed so search can filter it',
             },
         }, template(a({
             class: 'doc-link',
@@ -1462,7 +1533,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 +1546,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/site/site-config.d.ts

@@ -130,8 +130,8 @@ 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}`.
      */

package/dist/float.d.ts

@@ -1,4 +1,5 @@
 import { ElementCreator } from 'tosijs';
+import type { FloatPosition } from './pop-float.js';
 declare const TosiFloat_base: import("tosijs").WithAttributes<{
     drag: boolean;
     remainOnResize: "hide" | "remove" | "remain";
@@ -12,6 +13,11 @@ export declare class TosiFloat extends TosiFloat_base {
      * (the page, or a scroller containing it) triggers `remainOnScroll`. `null`: any scroll does.
      */
     anchor: Element | null;
+    /**
+     * The position it was asked for against its anchor (set by `positionFloat`), so it can be
+     * re-fitted when the visible viewport changes. `null`: never positioned against an anchor.
+     */
+    anchorPosition: FloatPosition | null;
     content: HTMLSlotElement;
     static shadowStyleSpec: {
         ':host': {

package/dist/float.js

@@ -106,6 +106,13 @@ export class TosiFloat extends withAttributes({
      * (the page, or a scroller containing it) triggers `remainOnScroll`. `null`: any scroll does.
      */
     anchor = null;
+    /**
+     * The position it was asked for against its anchor (set by `positionFloat`), so it can be
+     * re-fitted when the visible viewport changes. `null`: never positioned against an anchor.
+     */
+    // typed FloatPosition, not string: as `string` it accepted the CSS position '' / 'fixed'
+    // that a shadowed variable stored there (1.16.5 review B1), and the compiler said nothing
+    anchorPosition = null;
     content = slot();
     static shadowStyleSpec = {
         ':host': {