tosijs-ui 1.17.2 → 1.17.4

package/CHANGELOG.md

@@ -1,5 +1,69 @@
 # Changelog
 
+## 1.17.4
+
+> Live examples' inline views keep their controls in the code panel's tab bar, and a site or
+> page can set the view its examples open in. Nothing to change on upgrade. Asked by tjs-lang
+> for its learn-to-program book (#252). `dist/iife.js` grows 0.6 kB (508.7 kB gzip).
+
+### Added
+
+- `SiteConfig.exampleView` (`'preview'` | `'code'` | `'console'`) sets the view every live
+  example opens in, and `exampleView` in a page's metadata or frontmatter sets it for one page.
+  The nearest setting wins (fence, then page, then site), and `"preview"` opts out of a default
+  above it, so a big example on a code-first page takes `{"view": "preview"}`. A misspelt value
+  fails the build in the site config and is reported in page metadata. `setExampleView` (from
+  `tosijs-ui/live-example`) sets it from code.
+- A refresh button in the code panel's tab bar, beside ⋮, in every view. Editing does not re-run
+  an example, and ⌘S / ⌘R were undiscoverable.
+
+### Changed
+
+- In the inline views (`{"view": "code"}`, `{"view": "console"}`) the toolbar column beside the
+  preview is gone: it stood between the preview and its code. Maximize and the new-window editor
+  are in the code panel's tab bar. "view/edit code" (the code is already open) and the tests
+  check (inline tests always run) are not shown there. Maximized and plain examples are
+  unchanged.
+
+### Fixed
+
+- `<tosi-tabs>` with more tabs than fit pushed its `after-tabs` controls past its clipped edge:
+  at phone width a live example's close button was pushed past the panel's clipped edge. The tab names now
+  scroll (swipe, trackpad, or the mouse wheel over them) and the controls stay where they are.
+  Selecting a tab scrolls it into view, and the underline follows the scroll, clipped to the
+  strip.
+
+## 1.17.3
+
+> A doc site answers `/slug` as well as `/slug/`, and a missing page gets a real 404 page.
+> Nothing to change on upgrade. On Firebase, add `"cleanUrls": true` to `firebase.json` for
+> `/slug` to serve the page; GitHub Pages, Netlify and Cloudflare Pages need nothing.
+
+### Added
+
+- Every page (and alias) is also written as `/slug.html`, with its references written for
+  `/slug`, so a host that resolves extensionless paths (GitHub Pages, Netlify, Cloudflare
+  Pages, Firebase with `cleanUrls`) answers `/slug` with the page instead of a redirect. An
+  agent's fetch tool that does not follow redirects got a "moved" stub at
+  virta.tosijs.net/start. The canonical link stays `/slug/`; a file the site already has at
+  `/slug.html` is left alone and named in a warning.
+- The build writes `404.html` (unless the site ships its own): it names the path asked for,
+  suggests the closest page, lists every page and links `llms.txt`. Every link in it is
+  absolute, since hosts serve it at whatever URL was asked for.
+
+### Fixed
+
+- After Cmd-K, the doc site's search field sat on top of a maximized live example. Opening the
+  palette raised the whole `<tosi-palette>` (its trigger included) to the page's highest
+  z-index and never put it back, and any overlay on the page (haltija's widget on a dev
+  server, a toast in an app) made that higher than the example's. The dialog never needed it:
+  `showModal()` already puts it in the top layer.
+- The dev server served `/slug` from `slug/index.html`, whose references are written for
+  `/slug/`; it now serves `slug.html`. (Its `.html` fallback looked for `slug/.html` and never
+  matched.)
+- The live-theme page showed two theme editors: its example had an `html` block and a `js`
+  block that each made one.
+
 ## 1.17.2
 
 > Components carry only the icons they draw, and `<tosi-affix>` centres a caption on its

package/dist/doc-browser.d.ts

@@ -1,6 +1,6 @@
 import { type AccessibilityMode } from './doc-system/render.js';
 import { TestResults } from './live-example/test-harness.js';
-import { type ExamplePolicy } from './doc-system/example-policy.js';
+import { type ExamplePolicy, type ExampleView } from './doc-system/example-policy.js';
 export declare const hasTestBlock: (text: string | undefined, policy?: ExamplePolicy) => boolean;
 export interface PageTestResults {
     passed: boolean;
@@ -45,6 +45,8 @@ export interface Doc {
     header?: boolean;
     /** `'full-width'` drops the reading measure; `'full-screen'` also puts the nav away. */
     layout?: 'full-width' | 'full-screen';
+    /** the view this page's live examples open in (see the site `Doc.exampleView`) */
+    exampleView?: ExampleView;
     testStatus?: 'passed' | 'failed' | 'pending';
     bakes?: Array<[string, {
         dialect: string;

package/dist/doc-browser.js

@@ -110,7 +110,7 @@ import { LiveExample, testManager, pageTestCount, enableTests, disableTests, } f
 import { highlightBlocks } from './doc-system/highlight.js';
 import { examplePolicy } from './live-example/insert-examples.js';
 import { collectCodeTokens } from './doc-system/code-fences.js';
-import { isLiveFence } from './doc-system/example-policy.js';
+import { isExampleView, isLiveFence, } from './doc-system/example-policy.js';
 import { tosiSidenav, TosiSidenav } from './side-nav.js';
 import { icons } from './icons.js';
 import { tosiPalette } from './palette.js';
@@ -957,6 +957,19 @@ export function createDocBrowser(options) {
     // render from doc text. Every navigation funnels through navigateTo() -> showDoc().
     const docContent = contentElement || div();
     docContent.classList.add('doc-content');
+    /*
+    A page's `exampleView` (#252), where its examples look for it: on the content they sit in. A
+    value the metadata block got wrong is reported, not ignored, as frontmatter's is.
+    */
+    const stampExampleView = (doc) => {
+        const view = doc.exampleView;
+        if (view !== undefined && !isExampleView(view))
+            console.error(`${doc.path || doc.filename}: unknown exampleView ${JSON.stringify(view)}`);
+        if (isExampleView(view))
+            docContent.setAttribute('data-example-view', view);
+        else
+            docContent.removeAttribute('data-example-view');
+    };
     Object.assign(docContent.style, {
         display: 'block',
         // Same var the pre-hydration `:not(:defined)` layout uses (doc-system-styles.ts).
@@ -1132,6 +1145,7 @@ export function createDocBrowser(options) {
         rewriteContentLinks();
         // Stamp each example with its source file (for the source↔doc map). doc.path
         // is the extracted file (.md, or a source file with doc comments).
+        stampExampleView(doc);
         LiveExample.insertExamples(docContent, context, doc.path || undefined);
         focusableCodeBlocks(docContent);
         /*
@@ -1370,6 +1384,7 @@ export function createDocBrowser(options) {
         if (view === 'preview') {
             docContent.innerHTML = renderDocMarkdown(docMarkdownFromSource(editUI.editor.value, editUI.doc.path), { wikilinks, accessible: !!accessibility, title: editUI.doc.title });
             rewriteContentLinks();
+            stampExampleView(editUI.doc);
             LiveExample.insertExamples(docContent, context, editUI.doc.path || undefined);
             focusableCodeBlocks(docContent);
         }

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

@@ -71,6 +71,15 @@ export declare const EXAMPLE_TABS: readonly ["js", "html", "css", "test", "conso
 export type ExampleTab = (typeof EXAMPLE_TABS)[number];
 /** Why `value` is not a list of example tabs, or undefined when it is one. */
 export declare function exampleTabsProblem(value: unknown): string | undefined;
+/**
+ * The view a live example opens in (#252): `preview` (the default), `code` (the preview beside
+ * its code) or `console` (the console beside the code). Set per fence (`{"view": "code"}`), per
+ * page (`exampleView` in its metadata) or per site (`SiteConfig.exampleView`); the nearest wins,
+ * so `preview` opts one example or page out of a default.
+ */
+export declare const EXAMPLE_VIEWS: readonly ["preview", "code", "console"];
+export type ExampleView = (typeof EXAMPLE_VIEWS)[number];
+export declare function isExampleView(value: unknown): value is ExampleView;
 /**
  * Will this fence become a live example?
  *

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

@@ -118,6 +118,16 @@ export function exampleTabsProblem(value) {
             .join(', ')} (the tabs are ${EXAMPLE_TABS.join(', ')})`
         : undefined;
 }
+/**
+ * The view a live example opens in (#252): `preview` (the default), `code` (the preview beside
+ * its code) or `console` (the console beside the code). Set per fence (`{"view": "code"}`), per
+ * page (`exampleView` in its metadata) or per site (`SiteConfig.exampleView`); the nearest wins,
+ * so `preview` opts one example or page out of a default.
+ */
+export const EXAMPLE_VIEWS = ['preview', 'code', 'console'];
+export function isExampleView(value) {
+    return EXAMPLE_VIEWS.includes(value);
+}
 /**
  * Will this fence become a live example?
  *

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

@@ -1228,10 +1228,15 @@ export async function devServer(config, opts = {}) {
         */
         if (!isUnderRoot(directory, basePath))
             return null;
-        const suffixes = ['', '.html', 'index.html'];
-        for (const suffix of suffixes) {
+        // `/slug` is the build's `slug.html` (written for that URL) before `slug/index.html`;
+        // `/slug/` is only ever the folder's index
+        const candidates = [
+            basePath,
+            ...(reqPath.endsWith('/') ? [] : [basePath + '.html']),
+            path.join(basePath, 'index.html'),
+        ];
+        for (const pathWithSuffix of candidates) {
             try {
-                const pathWithSuffix = path.join(basePath, suffix);
                 const stat = statSync(pathWithSuffix);
                 if (stat && stat.isFile()) {
                     return pathWithSuffix;

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

@@ -76,6 +76,11 @@ export interface Doc {
      * reach them from out here.
      */
     layout?: 'full-width' | 'full-screen';
+    /**
+     * The view this page's live examples open in (1.17.4, #252): `'code'`, `'console'`, or
+     * `'preview'` to opt out of the site's `exampleView`. A fence's `{"view": …}` still wins.
+     */
+    exampleView?: 'preview' | 'code' | 'console';
     headTitle?: string;
     description?: string;
     keywords?: string | string[];

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

@@ -160,6 +160,13 @@ export function parseFrontmatter(content) {
             else if (val)
                 console.error(`unknown layout ${JSON.stringify(val)} in frontmatter`);
         }
+        else if (key === 'exampleview') {
+            // Same reasoning as layout: a misspelt view would silently do nothing.
+            if (val === 'preview' || val === 'code' || val === 'console')
+                data.exampleView = val;
+            else if (val)
+                console.error(`unknown exampleView ${JSON.stringify(val)} in frontmatter`);
+        }
         else if (key === 'header') {
             if (/^(false|no|0)$/i.test(val))
                 data.header = false;

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

@@ -1,11 +1,14 @@
 import type { Doc } from './docs.js';
 import type { ProjectLinks, LinkItem } from '../../doc-browser.js';
+import { NavNode } from '../nav-tree.js';
 import { type AccessibilityMode, type ExampleBakes } from '../render.js';
 declare global {
     var Bun: any;
 }
 export interface GenerateSiteConfig {
     docs: Doc[];
+    /** whether the site serves `/llms.txt`, which the 404 page then points to */
+    llmsTxt?: boolean;
     /** `SiteConfig.aliases`: { alias path -> slug } (board #3513) */
     aliases?: Record<string, string>;
     /** `SiteConfig.searchPlaceholder` */
@@ -160,3 +163,4 @@ export declare function withStamp(url: string, stamp?: string): string;
  */
 export declare function rebaseRelativeRefs(html: string, fromPath: string, depth: number): string;
 export declare function generateSite(config: GenerateSiteConfig): Promise<number>;
+export declare function notFoundHtml(pages: NavNode<Doc>[], slugMap: Record<string, string>, config: Pick<GenerateSiteConfig, 'projectName' | 'basePath' | 'lang' | 'llmsTxt'>): string;

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

@@ -163,11 +163,12 @@ export function relativeUrl(depth, p) {
 }
 async function pageHtml(doc, config, slugMap, configAttr, wikilinks, 
 /** the slug this copy is written at: the doc's own, or an alias of it */
-at = slugMap[doc.filename] ?? '') {
+at = slugMap[doc.filename] ?? '', 
+/** the directory depth its references resolve from: 0 for the `/slug` copy (`slug.html`) */
+depth = pageDepth(at)) {
     const { projectName = '', baseUrl = '', lang = 'en', favicon = '/favicon.svg', docsUrl = '/docs.json', scriptUrl = '/iife.js', hydrateUrl, stylesUrl = '/doc-system.css', assetStamp, docsStamp, localizedUrl = '/localized-strings.txt', basePath, headExtra = '', bakes, } = config;
     // Functional URLs are emitted relative to THIS page's depth so the build is
     // mount-agnostic (issue #25); metadata URLs below stay absolute via withBase.
-    const depth = pageDepth(at);
     const own = slugMap[doc.filename] ?? '';
     const localizedAttr = config.localizedStrings
         ? ` localized="${escapeAttr(relativeUrl(depth, localizedUrl))}"`
@@ -210,9 +211,10 @@ at = slugMap[doc.filename] ?? '') {
     config.liveExamples ?? 'auto'), (filename) => slugMap[filename] !== undefined
         ? relativeUrl(depth, pathForSlug(slugMap[filename]))
         : null);
-    // A copy at an alias: what the author wrote relative to the page's own path must still reach
-    // the same file (a README's `img/logo.png` is /img/logo.png, not /readme/img/logo.png).
-    const body = at === own
+    // A copy anywhere but the page's own path (an alias, or `/slug` with no slash): what the
+    // author wrote relative to that path must still reach the same file (a README's
+    // `img/logo.png` is /img/logo.png, not /readme/img/logo.png).
+    const body = at === own && depth === pageDepth(own)
         ? rendered
         : rebaseRelativeRefs(rendered, pathForSlug(own), depth);
     const nav = navHtml(config.docs, slugMap, doc.filename, depth);
@@ -562,6 +564,35 @@ export async function generateSite(config) {
             await Bun.write(`${dir}/index.md`, doc.text.trimEnd() + '\n');
         }
     }
+    /*
+    Every page again as `slug.html`, with its references written for `/slug`, so the trailing
+    slash is optional. Hosts serve `/slug` from `slug/index.html` with a redirect, and a client
+    that does not follow it (an agent's fetch tool, onboarding from a typed URL) got a "moved"
+    stub instead of the page. With `slug.html` beside it, a host that resolves extensionless
+    paths to `.html` (GitHub Pages, Netlify, Cloudflare Pages, Firebase with `cleanUrls`)
+    answers `/slug` with the page itself. The canonical link stays `/slug/`.
+    */
+    const slashless = [
+        ...docs.map((doc) => [slugMap[doc.filename], doc]),
+        ...Object.entries(aliases).map(([alias, target]) => [alias, docs.find((d) => slugMap[d.filename] === target)]),
+    ];
+    const occupied = [];
+    for (const [at, doc] of slashless) {
+        if (at === '')
+            continue;
+        const file = `${outputDir}/${at}.html`;
+        // the output folder starts empty, so a file here is one the site ships: leave it alone
+        if (existsSync(file)) {
+            occupied.push(`    /${at}.html`);
+            continue;
+        }
+        await Bun.write(file, await pageHtml(doc, config, slugMap, configAttr, wikilinks, at, 0));
+    }
+    if (occupied.length) {
+        console.warn(`\n⚠️  These pages are served only at /slug/, because the site already has a file where\n` +
+            `    the /slug copy goes (rename the file to make the trailing slash optional):\n` +
+            `${occupied.join('\n')}\n`);
+    }
     if (danglingWikilinks.length) {
         misconfigured(config.strict, `\n⚠️  Wikilinks that reach no doc page. A target matches a page's slug (its file name)\n` +
             `    or its title; write [[slug|label]] to link one by file name, and an ordinary\n` +
@@ -631,5 +662,88 @@ export async function generateSite(config) {
             await Bun.write(robotsPath, `${base}Sitemap: ${config.baseUrl}/sitemap.xml\n`);
         }
     }
+    // A site's own 404.html (copied from its static files) wins.
+    if (!existsSync(`${outputDir}/404.html`)) {
+        await Bun.write(`${outputDir}/404.html`, notFoundHtml(flattenNav(buildNavTree(docs, slugMap)), slugMap, config));
+    }
     return count;
 }
+/*
+The page a host serves for a path the site does not have: GitHub Pages and Firebase serve
+`404.html` from the site root, at whatever URL was asked for, so nothing in it may be
+relative. It lists every page, which is what a reader without JavaScript (an agent's fetch
+tool, most often) needs to find its way, and with JavaScript it names the closest page to the
+path asked for. The script is a nicety: under a policy that blocks inline scripts, the list
+is still there.
+*/
+export function notFoundHtml(pages, slugMap, config) {
+    const { projectName = '', basePath, lang = 'en', llmsTxt } = config;
+    const href = (slug) => withBase(basePath, pathForSlug(slug));
+    const listed = pages.filter((node) => !node.doc.hidden);
+    const items = listed
+        .map((node) => `      <li><a href="${escapeAttr(href(node.slug))}">${escapeText(node.doc.title || node.slug || 'Home')}</a></li>`)
+        .join('\n');
+    const slugs = JSON.stringify(Object.values(slugMap).filter((slug) => slug !== '')).replace(/</g, '\\u003c');
+    const title = projectName
+        ? `Page not found — ${projectName}`
+        : 'Page not found';
+    return `<!DOCTYPE html>
+<html lang="${escapeAttr(lang)}">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="robots" content="noindex" />
+    <title>${escapeText(title)}</title>
+    <style>
+      body { font: 16px/1.5 system-ui, sans-serif; max-width: 40em; margin: 2em auto; padding: 0 1em; }
+      @media (prefers-color-scheme: dark) { body { background: #111; color: #eee; } a { color: #8bf; } }
+    </style>
+  </head>
+  <body>
+    <h1>Page not found</h1>
+    <p>There is no page at <code id="asked"></code> on this site.<span id="closest"></span></p>
+    <p><a href="${escapeAttr(withBase(basePath, '/'))}">Home</a>${llmsTxt
+        ? ` · <a href="${escapeAttr(withBase(basePath, '/llms.txt'))}">llms.txt</a> (every page, for agents)`
+        : ''}</p>
+    <h2>Pages</h2>
+    <ul>
+${items}
+    </ul>
+    <script>
+      ;(() => {
+        const slugs = ${slugs}
+        const base = ${JSON.stringify(withBase(basePath, '/'))}
+        const asked = decodeURIComponent(location.pathname)
+        document.getElementById('asked').textContent = asked
+        const want = asked.slice(base.length - 1).replace(/^\\/+|\\/+$/g, '').toLowerCase()
+        if (!want) return
+        const distance = (a, b) => {
+          const row = Array.from({ length: b.length + 1 }, (_, i) => i)
+          for (let i = 1; i <= a.length; i++) {
+            let prev = row[0]++
+            for (let j = 1; j <= b.length; j++) {
+              const next = Math.min(row[j] + 1, row[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1))
+              prev = row[j]
+              row[j] = next
+            }
+          }
+          return row[b.length]
+        }
+        let best = '', score = Infinity
+        for (const slug of slugs) {
+          const prefix = Math.min(want.length, slug.length) >= 3 && (slug.startsWith(want) || want.startsWith(slug))
+          const d = prefix ? 0.5 : distance(want, slug)
+          if (d < score) [best, score] = [slug, d]
+        }
+        if (score > Math.max(2, want.length / 3)) return
+        const link = document.createElement('a')
+        link.href = base + best + '/'
+        link.textContent = base + best + '/'
+        const closest = document.getElementById('closest')
+        closest.append(' Did you mean ', link, '?')
+      })()
+    </script>
+  </body>
+</html>
+`;
+}

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

@@ -1653,6 +1653,7 @@ export async function buildSite(config, opts = {}) {
             const pageCount = await generateSite({
                 liveExamples: config.liveExamples,
                 docs,
+                llmsTxt: config.llmsTxt !== false,
                 aliases: config.aliases,
                 searchPlaceholder: config.searchPlaceholder,
                 accessibility: config.accessibility,

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

@@ -1,8 +1,9 @@
-import type { ExampleTab } from '../example-policy.js';
+import type { ExampleTab, ExampleView } from '../example-policy.js';
 export interface PageGlobalsConfig {
     liveExamples?: 'auto' | 'opt-in' | 'no-code';
     exampleConsole?: boolean;
     exampleTabs?: ExampleTab[];
+    exampleView?: ExampleView;
     dialects?: string[];
 }
 /**
@@ -13,5 +14,6 @@ export interface PageGlobalsConfig {
 export declare function siteSwitchProblem(config: {
     liveExamples?: string;
     kind?: string;
+    exampleView?: string;
 }): string | null;
 export declare function pageGlobalsHead(config: PageGlobalsConfig): string;

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

@@ -6,7 +6,7 @@ bundle reads when it runs (so they must come BEFORE the bundle script — genera
 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 { exampleTabsProblem, normalizeDialectNames } from '../example-policy.js';
+import { EXAMPLE_VIEWS, exampleTabsProblem, normalizeDialectNames, } from '../example-policy.js';
 const LIVE_EXAMPLE_POLICIES = ['auto', 'opt-in', 'no-code'];
 const SITE_KINDS = ['documentation', 'book'];
 /**
@@ -19,7 +19,8 @@ export function siteSwitchProblem(config) {
         ? `SiteConfig.${name} is ${JSON.stringify(value)}; it must be one of ${allowed.map((a) => `'${a}'`).join(', ')}`
         : null;
     return (wrong('liveExamples', config.liveExamples, LIVE_EXAMPLE_POLICIES) ??
-        wrong('kind', config.kind, SITE_KINDS));
+        wrong('kind', config.kind, SITE_KINDS) ??
+        wrong('exampleView', config.exampleView, [...EXAMPLE_VIEWS]));
 }
 export function pageGlobalsHead(config) {
     // A misspelt tab would hide a tab on every example with nothing to say why.
@@ -35,6 +36,10 @@ export function pageGlobalsHead(config) {
         config.exampleTabs
             ? `<script>globalThis.__TOSI_EXAMPLE_TABS=${JSON.stringify(config.exampleTabs)}</script>`
             : '',
+        // #252: the view examples open in
+        config.exampleView && config.exampleView !== 'preview'
+            ? `<script>globalThis.__TOSI_EXAMPLE_VIEW="${config.exampleView}"</script>`
+            : '',
         // 1.16.2: the example console
         config.exampleConsole === false
             ? `<script>globalThis.__TOSI_EXAMPLE_CONSOLE=false</script>`

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

@@ -8,7 +8,7 @@ import type { EditableDataOptions } from './data-store.js';
 import type { BookManifest } from '../book-manifest.js';
 import type { AccessibilityMode } from '../render.js';
 import type { AltTextHook } from './alt-text.js';
-import type { ExampleTab } from '../example-policy.js';
+import type { ExampleTab, ExampleView } from '../example-policy.js';
 export type SiteHost = 'github-pages' | 'firebase' | 'static';
 /** Resolved paths handed to a `libraryBuild` override (see SiteConfig). */
 export interface LibraryBuildContext {
@@ -200,6 +200,14 @@ export interface SiteConfig {
      * `{"tabs": ["html"]}`. A hidden tab's block still runs; it just can't be edited.
      */
     exampleTabs?: ExampleTab[];
+    /**
+     * The view every live example opens in (1.17.4, #252): `'code'` puts the preview beside its
+     * code, `'console'` the console beside the code. Default `'preview'`, the example alone. For
+     * a book whose small examples should show their code: set it once here instead of
+     * `{"view": "code"}` on every fence. A page overrides it with `exampleView` in its metadata,
+     * and one example with the fence option `{"view": "preview"}`.
+     */
+    exampleView?: ExampleView;
     /**
      * Run script examples from same-origin modules (1.17.0, #245), for a site served under a
      * Content Security Policy without `'unsafe-eval'` (`script-src 'self'`).