tosijs-ui 1.17.3 → 1.17.4

package/CHANGELOG.md

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

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/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/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'`).