tosijs-ui 1.16.3 → 1.16.4

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # 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

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/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}`.
      */