tosijs-ui 1.12.2 → 1.12.3

package/CHANGELOG.md

@@ -1,5 +1,94 @@
 # Changelog
 
+## 1.12.3
+
+### Back now has layout coverage, because a reader noticed before the tests did
+
+Reported from the keyboard as "sometimes the full-screen page and the full-screen page with the
+nav open look like different history entries". Measured, it is neither history nor
+inconsistent: the nav toggle creates **no** history entry (`history.length` unchanged across
+repeated toggles, URL unchanged). What happens is that **Back re-asserts the page's declared
+layout** and discards the override — so leaving a page with the nav open and returning finds it
+closed.
+
+That is defensible and it is what ships: a full-screen page is full-screen whenever you arrive
+at it. Whether Back should instead restore what you left is now an open decision in `TODO.md`,
+with the measurements attached, rather than whatever fell out of the implementation.
+
+The gap the report exposed was in the tests, not the feature: `doc-system.pw.ts` already covered
+Back for URL, title and content, but nothing checked its effect on **layout**, and every layout
+test reached its pages by clicking links. Both directions are covered now — and labelled by what
+they actually do, since one is a genuine regression test (dropping `removeAttribute('data-layout')`
+on navigation fails it) and the other is a contract tripwire that survives every mutation tried
+against it. A test that cannot fail is usually decoration; that one is deliberate, and saying so
+is the difference.
+
+### The dev server sends `Cache-Control: no-store` on everything
+
+It previously sent no `Cache-Control` at all, and that is not neutral: a browser may invent a
+freshness lifetime when you decline to state one, and Safari is the most willing to. So the dev
+server would rebuild correctly while the browser kept serving the previous build — which
+presents as "my fix did not work", and is only escaped by emptying the cache by hand. It cost
+exactly that here: a bug was reported against code that had already been fixed.
+
+All three of the file-server's exits are covered — injected HTML, compressed assets, and
+binaries that stream untouched — because they are separate responses and adding the header to
+the obvious one is precisely how the other two get missed. Each is independently
+mutation-verified.
+
+**Dev server only.** The built site in `docs/` is unaffected; it is a static site for a real
+host, and telling a CDN never to store it would be actively wrong.
+
+### `layout: "full-screen"` — and `<tosi-sidenav alwaysCompact>` underneath it
+
+`full-width` shipped in 1.12.2 and `full-screen` did not, because it needed something from the
+sidenav that did not exist. It exists now, and it is one line rather than a new layout.
+
+**`<tosi-sidenav>` gained `navVisible`** — the one control a "show me the navigation" button
+needs. Read it, flip it:
+
+```js
+sidenav.navVisible = !sidenav.navVisible
+```
+
+It resolves what hiding the nav _means_ at the current width — forcing compact on a wide screen,
+simply showing the content on a narrow one — so no caller has to know, and a narrow-screen
+request does not outstay itself when the window is widened. `layout: "full-screen"` uses the
+same property, so the feature is general rather than something the doc-browser knows a trick
+about.
+
+**And `alwaysCompact` underneath it.** Compact mode already shows the nav _or_ the content
+and takes turns between them — which is precisely what a full-screen page wants — so this just
+removes the width test rather than adding a second way to lay out. It is a named state and not a
+`minSize` no viewport can reach, because the second one works and reads as a bug to the next
+person.
+
+**`layout: "full-screen"`** then means: no reading measure, no nav, no gutter, and a content area
+with a real height — so a demo, a canvas or an embedded app can ask for `height: 100%` and get
+it. There is a [demo page](/full-screen-demo/), and the navigation button works there: it
+returns you to the normal layout rather than replacing the content with a full-screen nav, and
+it **stays offered** so you can go back. Riding `compact` directly, as it used to, meant the
+button vanished on its own click and stranded you in the normal layout.
+
+Two inline styles were quietly breaking the promise. `.doc-content` receives both its
+`max-width` and its `padding` inline from the doc-browser, so no stylesheet could override
+either — a full-screen page rendered inset by 32px, in a box that collapsed to its content
+height instead of filling. `padding` now routes through `--doc-content-padding`, the way the
+measure already did.
+
+Navigating away restores the nav, and a reader's override lasts until they navigate rather than
+beyond it — **including Back**, so a full-screen page is full-screen whenever you arrive at it.
+That is predictable, but it does mean leaving a page with the nav open and returning finds it
+closed; whether Back should instead restore what you left is noted in `TODO.md` as a decision
+rather than left to whatever fell out of the implementation. Both directions are mutation-verified, which caught a test that _looked_ like it
+covered the second one and did not: it routed through a prose page, which reset the state as a
+side effect.
+
+Before hydration there is no sidenav at all, just static markup, so a stylesheet rule covers the
+first paint. Those rules select `.doc-nav.doc-nav` — the class deliberately repeated — because
+the pre-hydration layout further down the same sheet has identical specificity, and winning on
+source order works right up until someone reorders the spec.
+
 ## 1.12.2
 
 ### `haltijaDev: 'tunnel'` — let an agent drive a page running in a headset (#104)

package/dist/doc-browser.d.ts

@@ -22,8 +22,8 @@ export interface Doc {
     path: string;
     pin?: string;
     hidden?: boolean;
-    /** `'full-width'` drops the reading measure. See `Doc.layout` in docs.ts. */
-    layout?: 'full-width';
+    /** `'full-width'` drops the reading measure; `'full-screen'` also puts the nav away. */
+    layout?: 'full-width' | 'full-screen';
     testStatus?: 'passed' | 'failed' | 'pending';
     bakes?: Array<[string, {
         dialect: string;

package/dist/doc-browser.js

@@ -422,6 +422,16 @@ export function createDocBrowser(options) {
             docs,
             currentDoc,
             compact: false,
+            /*
+            Whether to OFFER the navigation button — deliberately not the same thing as `compact`.
+      
+            The button used to ride `compact` directly, which is right for a responsive page: wide
+            enough to show the nav beside the content, and there is nothing to toggle. But opening the
+            nav on a full-screen page leaves compact mode by design, and the button would vanish with
+            it — stranding the reader in the normal layout with no way back to full screen. So it is
+            offered whenever the layout is compact OR the page asked to be full-screen.
+            */
+            navToggle: false,
         },
     });
     const app = state[stateKey];
@@ -576,13 +586,58 @@ export function createDocBrowser(options) {
     // sidenav')`, which returns the FIRST sidenav in the document (an OUTER instance
     // when this one is an embedded, memory-routed browser).
     let sidenav = null;
+    /*
+    `full-screen` uses the sidenav's OWN compact behaviour rather than a new state.
+  
+    `<tosi-sidenav>` already does exactly what full-screen wants: compact mode shows the nav OR the
+    content, with `contentVisible` picking which. `alwaysCompact` keeps it in that mode at any
+    width, and `contentVisible` gives the page the whole box.
+  
+    Remembered rather than applied directly, because the sidenav is not there yet when the first
+    doc renders — `sidenav` is captured from its own change event, which fires on a state CHANGE
+    and so may never fire at all on a normal-width page.
+    */
+    let wantsFullScreen = false;
+    /*
+    What we last PUSHED onto the sidenav, so the user's own toggle is not overwritten.
+  
+    The first version applied the layout on every call, and `applyFullScreen` is called from the
+    sidenav's change handler — so clicking "navigation" flipped `contentVisible`, the sidenav
+    changed state, the handler fired, and the layout was re-applied on top. The nav button looked
+    live and did nothing. Applying only on TRANSITION means a full-screen page sets itself up once
+    and then leaves the reader alone.
+    */
+    let appliedFullScreen = null;
+    /** Offer the button when there is something to toggle: a compact layout, or a full-screen page. */
+    const refreshNavToggle = () => {
+        app.navToggle = (Boolean(sidenav?.compact) || wantsFullScreen);
+    };
+    const applyFullScreen = () => {
+        /*
+        Resolved from THIS browser's own container when the change event has not introduced it yet.
+        Scoped rather than `document.querySelector('tosi-sidenav')`, which returns the first in the
+        document — for a nested doc-browser, the HOST's.
+        */
+        if (!sidenav && typeof container !== 'undefined' && container) {
+            sidenav = container.querySelector(TosiSidenav.tagName);
+        }
+        if (!sidenav)
+            return;
+        if (appliedFullScreen === wantsFullScreen)
+            return;
+        // The same one control the nav button uses — the layout is just asking for the nav to be
+        // away, and the sidenav decides how that is achieved.
+        sidenav.navVisible = !wantsFullScreen;
+        appliedFullScreen = wantsFullScreen;
+        refreshNavToggle();
+    };
     const headerContent = [
         button({
             class: 'iconic',
             style: { color: vars.linkColor },
             title: 'navigation',
             bind: {
-                value: app.compact,
+                value: app.navToggle,
                 binding: {
                     toDOM(element, compact) {
                         element.style.display = compact ? '' : 'none';
@@ -593,8 +648,10 @@ export function createDocBrowser(options) {
                 },
             },
             onClick() {
+                // Read it, flip it. `<tosi-sidenav>` resolves what that means at this width; a
+                // button should not have to know, and this one used to.
                 if (sidenav)
-                    sidenav.contentVisible = !sidenav.contentVisible;
+                    sidenav.navVisible = !sidenav.navVisible;
             },
         }, icons.menu()),
         span({ style: { flex: '0 0 10px' } }),
@@ -651,7 +708,13 @@ export function createDocBrowser(options) {
         // doc-browser (no doc-system stylesheet) working.
         maxWidth: 'var(--doc-content-max-width, 44em)',
         margin: 'auto',
-        padding: '0 1em',
+        /*
+        Through a variable, for the same reason `maxWidth` is: this is an INLINE style, so a
+        stylesheet cannot override it, and `layout: "full-screen"` needs to. A full-screen page that
+        keeps a 1em gutter is not full screen — it is a demo inset by 32px, which is exactly what it
+        looked like.
+        */
+        padding: 'var(--doc-content-padding, 0 1em)',
         overflow: 'hidden',
     });
     // Adoption is zero-flash hydration of a statically pre-rendered page: it only
@@ -743,6 +806,25 @@ export function createDocBrowser(options) {
                 else
                     layoutHost.removeAttribute('data-layout');
             }
+            /*
+            `full-screen` also collapses the nav, and that has to go through the COMPONENT rather than
+            CSS: `<tosi-sidenav>` writes its column widths as inline properties, so a stylesheet has
+            nothing to override. The pre-hydration rule in doc-system-styles.ts handles the static
+            markup, which has a plain `<nav>` and no sidenav yet; this handles the hydrated page. Two
+            rules for two genuinely different DOMs, not two fixes for one bug.
+            */
+            wantsFullScreen = doc.layout === 'full-screen';
+            /*
+            Forced on every navigation. Without this, opening the nav on one full-screen page (which
+            turns `alwaysCompact` off) would leave the NEXT full-screen page not full-screen, because
+            the wish had not changed and the transition check would skip it. A reader's override is
+            meant to last until they navigate, not beyond it.
+            */
+            appliedFullScreen = null;
+            applyFullScreen();
+            // applyFullScreen returns early when there is no sidenav yet; the button state still has
+            // to follow the doc, so this does not ride on that path succeeding.
+            refreshNavToggle();
         }
         rewriteContentLinks();
         // Stamp each example with its source file (for the source↔doc map). doc.path
@@ -1249,6 +1331,9 @@ export function createDocBrowser(options) {
             sidenav = event.target.closest(TosiSidenav.tagName);
             if (sidenav)
                 app.compact = sidenav.compact;
+            refreshNavToggle();
+            // The sidenav has just introduced itself; give it the layout the doc asked for.
+            applyFullScreen();
         },
     }, searchField, navContent, div({
         style: {

package/dist/doc-system/doc-system-styles.js

@@ -108,6 +108,51 @@ export function docSystemStyleSpec(theme = {}) {
         'tosi-doc-system[data-layout="full-width"]': {
             _docContentMaxWidth: 'none',
         },
+        /*
+        `full-screen` — no measure, and no chrome.
+    
+        These rules are for the PRE-HYDRATION page, whose markup is a plain `<nav class="doc-nav">`
+        with no inline styles, so hiding it here works and works on first paint. Once the bundle
+        loads, the nav becomes a slotted node inside `<tosi-sidenav>` carrying its own inline
+        `display`, and CSS can no longer touch it — the doc-browser sets `sidenav.navHidden`
+        instead. Different DOM before and after hydration, so genuinely two rules rather than a
+        belt-and-braces duplicate.
+        */
+        'tosi-doc-system[data-layout="full-screen"]': {
+            _docContentMaxWidth: 'none',
+        },
+        'tosi-doc-system[data-layout="full-screen"] .doc-content': {
+            padding: '0',
+            /*
+            A definite height, so a child asking for `height: 100%` gets one.
+      
+            "The content is the viewport" is the promise this layout makes, and a demo, a canvas or an
+            embedded app is the reason to use it — all of which want to FILL, not to sit in a tall
+            box. Without a height here `100%` on a child resolves against `auto` and collapses to its
+            content.
+            */
+            height: '100%',
+            overflow: 'auto',
+            /*
+            The gutter goes too. `.doc-content`'s padding is an INLINE style set by the doc-browser,
+            so this is set through the variable it reads rather than declared here, where it would
+            simply lose.
+            */
+            _docContentPadding: '0',
+        },
+        /*
+        `.doc-nav.doc-nav` — the class twice, on purpose.
+    
+        `tosi-doc-system:not(:defined) .doc-nav` (the pre-hydration layout, further down this same
+        sheet) has IDENTICAL specificity to the single-class form, so which one wins is decided by
+        source order, and it sits later. Winning on position works until someone reorders the spec,
+        at which point the nav quietly comes back on full-screen pages with nothing to point at.
+        Repeating the class costs one selector token and settles it on specificity, wherever these
+        rules end up living.
+        */
+        'tosi-doc-system[data-layout="full-screen"] > .doc-nav.doc-nav, tosi-doc-system[data-layout="full-screen"] > .doc-navbar.doc-navbar': {
+            display: 'none',
+        },
         '.darkmode': {
             ...invertLuminance(colors),
             /*
@@ -190,7 +235,7 @@ export function docSystemStyleSpec(theme = {}) {
             display: 'block',
             maxWidth: vars.docContentMaxWidth,
             margin: 'auto',
-            padding: '0 1em',
+            padding: 'var(--doc-content-padding, 0 1em)',
             // Must match doc-browser's inline style EXACTLY, `overflow` included: it
             // establishes a block formatting context, which stops the <h1>'s top margin
             // collapsing out of the box. Without it the static content sits 10px lower

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

@@ -832,6 +832,29 @@ export async function devServer(config, opts = {}) {
         });
     }
     // disk, and non-HTML assets are streamed untouched.
+    /*
+    NOTHING the dev server serves may be cached. Ever.
+  
+    None of the file paths below sent `Cache-Control`, so browsers applied HEURISTIC caching —
+    they are free to invent a freshness lifetime when you decline to state one, and Safari is the
+    most willing to. The result is a dev server that rebuilds correctly while the browser keeps
+    showing the previous build, which presents as "the fix did not work" and costs whoever is
+    looking at it far more than a re-download. It cost exactly that here: a bug was reported
+    against code that had already been fixed.
+  
+    `no-store` rather than `no-cache`: no-cache still stores and revalidates, which needs
+    validators we do not emit, and a dev server has nothing to gain from the round trip. The cost
+    is re-fetching the bundle on a full page load — a doc site navigates client-side after that,
+    and the responses are brotli/gzip compressed anyway.
+  
+    Deliberately NOT applied to the built output: `docs/` is a static site for a real host, and
+    telling a CDN never to store it would be actively wrong. This is the dev server only.
+    */
+    const NO_CACHE = {
+        'Cache-Control': 'no-store, must-revalidate',
+        Pragma: 'no-cache',
+        Expires: '0',
+    };
     async function respondFile(filePath, request, viaTunnel = false) {
         /*
         WHICH loader, decided per request rather than once at boot.
@@ -864,6 +887,7 @@ export async function devServer(config, opts = {}) {
             return new Response(body, {
                 headers: {
                     'Content-Type': 'text/html; charset=utf-8',
+                    ...NO_CACHE,
                     ...(encoding
                         ? { 'Content-Encoding': encoding, Vary: 'Accept-Encoding' }
                         : {}),
@@ -881,14 +905,16 @@ export async function devServer(config, opts = {}) {
             return new Response(bytes, {
                 headers: {
                     'Content-Type': file.type || 'application/octet-stream',
+                    ...NO_CACHE,
                     '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));
+        // compressed, and re-encoding them only makes them bigger. Still uncacheable: an icon or a
+        // font you just changed is no more welcome stale than a script is.
+        return new Response(Bun.file(filePath), { headers: { ...NO_CACHE } });
     }
     async function handleTestReport(request) {
         try {

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

@@ -45,14 +45,12 @@ export interface Doc {
      * frontmatter. Unset means the reading column, so nothing changes for a corpus that does not
      * ask.
      *
-     * `'full-screen'` — chrome out of the way entirely — is NOT implemented yet and is rejected
-     * rather than half-honoured. It needs `<tosi-side-nav>` to expose a collapsed state: the nav
-     * width and the nav's own `display` are both set as INLINE styles, which a stylesheet cannot
-     * override without `!important`, and a value that drops the measure while leaving the chrome
-     * exactly where it was is the kind of partial success that gets reported as a bug. Tracked in
-     * TODO.md.
+     * `'full-screen'` drops the measure AND puts the nav away, so the page is the whole viewport —
+     * for a demo, a canvas, an embedded app. It needed `<tosi-sidenav navHidden>` to exist first:
+     * the nav width and the nav's own `display` are both INLINE styles, so no stylesheet could
+     * reach them from out here.
      */
-    layout?: 'full-width';
+    layout?: 'full-width' | 'full-screen';
     headTitle?: string;
     description?: string;
     keywords?: string | string[];

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

@@ -150,11 +150,8 @@ export function parseFrontmatter(content) {
             `wide` — and silently keeping the reading column is the behaviour that gets reported as
             "the metadata does nothing", so say so instead.
             */
-            if (val === 'full-width')
+            if (val === 'full-width' || val === 'full-screen')
                 data.layout = val;
-            else if (val === 'full-screen')
-                console.error(`layout: full-screen is not implemented yet (see TODO.md) — ignoring it rather than ` +
-                    `dropping the measure and leaving the chrome in place`);
             else if (val)
                 console.error(`unknown layout ${JSON.stringify(val)} in frontmatter`);
         }