tosijs-ui 1.6.5 → 1.6.7

package/dist/doc-browser.d.ts

@@ -46,8 +46,12 @@ export interface LinkItem {
  * - 'query' (default, legacy): single-page app, links are `?filename`.
  * - 'path': clean per-page URLs (`/slug/`), for the static pre-rendered site
  *   driven by <tosi-doc-system>. Requires a real page to exist at each path.
+ * - 'memory': self-contained — navigation never touches window.history/location
+ *   and the instance ignores the page URL. For an embedded/nested browser (a
+ *   live demo, a floating help panel). Drive it via `initialRoute` +
+ *   `onRouteChange`, and the returned element's `.navigate(slug)` method.
  */
-export type DocRoutingMode = 'query' | 'path';
+export type DocRoutingMode = 'query' | 'path' | 'memory';
 export interface DocBrowserOptions {
     docs: Doc[];
     context?: Record<string, any>;
@@ -56,6 +60,16 @@ export interface DocBrowserOptions {
     navSize?: number;
     minSize?: number;
     routing?: DocRoutingMode;
+    /**
+     * Memory routing only: the slug to show first (instead of the page URL / first
+     * doc). Lets a host mount the browser already pointed at a specific doc.
+     */
+    initialRoute?: string;
+    /**
+     * Memory routing only: called with the current doc's slug whenever in-app
+     * navigation happens, so a host can reflect it (e.g. to an attribute).
+     */
+    onRouteChange?: (slug: string) => void;
     /**
      * Header-bar links. When provided, these replace the legacy `projectLinks` icon
      * set in the header (each renders as an icon if `icon` names a known icon, else

package/dist/doc-browser.js

@@ -239,20 +239,37 @@ const testIndicatorStyleSpec = {
     },
 };
 export function createDocBrowser(options) {
-    const { docs, context = {}, projectName = '', projectLinks = {}, navSize = 200, minSize = 600, routing = 'query', navbarLinks, contentElement, } = options;
+    const { docs, context = {}, projectName = '', projectLinks = {}, navSize = 200, minSize = 600, routing = 'query', initialRoute, onRouteChange, navbarLinks, contentElement, } = options;
+    // Memory routing is fully self-contained: it never reads or writes
+    // window.history/location, so an embedded or nested browser can't hijack the
+    // host page's URL (or recurse into it).
+    const memoryRouting = routing === 'memory';
     // Initialize testStatus on all docs so tosi can track it
     for (const doc of docs) {
         doc.testStatus = undefined;
     }
     // Routing abstraction — keeps the legacy `?filename` SPA behavior the default,
     // while letting <tosi-doc-system> drive clean `/slug/` URLs off the same docs.
-    const slugMap = routing === 'path' ? buildSlugMap(docs) : {};
-    const hrefFor = (filename) => routing === 'path' ? pathForSlug(slugMap[filename] ?? filename) : `?${filename}`;
-    const filenameFromLocation = () => routing === 'path'
-        ? filenameForPath(document.location.pathname, slugMap)
-        : document.location.search !== ''
-            ? document.location.search.substring(1).split('&')[0]
-            : '';
+    // Both path and memory routing key off slugs; only legacy query routing doesn't.
+    const slugMap = routing === 'query' ? {} : buildSlugMap(docs);
+    const slugFor = (filename) => slugMap[filename] ?? filename;
+    const filenameForSlug = (slug) => {
+        for (const d of docs)
+            if (slugFor(d.filename) === slug)
+                return d.filename;
+        return '';
+    };
+    const hrefFor = (filename) => routing === 'query' ? `?${filename}` : pathForSlug(slugFor(filename));
+    const filenameFromLocation = () => {
+        // Memory routing ignores the page URL entirely — it starts at initialRoute.
+        if (memoryRouting)
+            return initialRoute ? filenameForSlug(initialRoute) : '';
+        return routing === 'path'
+            ? filenameForPath(document.location.pathname, slugMap)
+            : document.location.search !== ''
+                ? document.location.search.substring(1).split('&')[0]
+                : '';
+    };
     const docName = filenameFromLocation() || docs[0]?.filename || 'README.md';
     const currentDoc = docs.find((doc) => doc.filename === docName) || docs[0];
     const { app } = tosi({
@@ -272,10 +289,13 @@ export function createDocBrowser(options) {
     let backgroundTestsStarted = false;
     let pagesWithTests = 0;
     let pagesTested = 0;
-    // Set up global promise for scriptable browser integration
-    window.__docTestResults = new Promise((resolve) => {
-        testResultsResolve = resolve;
-    });
+    // Set up global promise for scriptable browser integration. A memory-routed
+    // (embedded) browser must not clobber the host page's global.
+    if (!memoryRouting) {
+        window.__docTestResults = new Promise((resolve) => {
+            testResultsResolve = resolve;
+        });
+    }
     const updateDocTestStatus = (filename) => {
         const results = pageTestResults[filename];
         // Callback receives bare object, return is proxy - cast to work with both
@@ -378,9 +398,13 @@ export function createDocBrowser(options) {
         },
         onInput: filterDocs,
     });
-    window.addEventListener('popstate', () => {
-        navigateTo(filenameFromLocation());
-    });
+    // Memory routing is decoupled from the page URL, so it ignores browser
+    // back/forward (the host owns history, if any).
+    if (!memoryRouting) {
+        window.addEventListener('popstate', () => {
+            navigateTo(filenameFromLocation());
+        });
+    }
     const headerContent = [
         button({
             class: 'iconic',
@@ -459,7 +483,12 @@ export function createDocBrowser(options) {
         padding: '0 1em',
         overflow: 'hidden',
     });
-    let adoptInitialContent = contentElement !== undefined;
+    // Adoption is zero-flash hydration of a statically pre-rendered page: it only
+    // holds for the page's own path-routed instance, whose static `.doc-content`
+    // matches the initial doc. A memory-routed embed's initial doc
+    // (initialRoute/docs[0]) has no relation to whatever happens to sit inside the
+    // host element (often an empty placeholder), so always render it fresh.
+    let adoptInitialContent = contentElement !== undefined && !memoryRouting;
     const showDoc = (doc) => {
         if (adoptInitialContent) {
             adoptInitialContent = false; // leave the pre-rendered HTML untouched
@@ -482,6 +511,19 @@ export function createDocBrowser(options) {
         showDoc(doc);
         refreshNav(true);
     };
+    // User-initiated navigation: record the new location (history for path/query,
+    // the onRouteChange callback for memory) and then render the doc. Every nav
+    // click funnels through here so memory mode never touches window.history.
+    const go = (filename) => {
+        if (memoryRouting) {
+            onRouteChange?.(slugFor(filename));
+        }
+        else {
+            const href = hrefFor(filename);
+            window.history.pushState({ href }, '', href);
+        }
+        navigateTo(filename);
+    };
     // ── Hierarchical nav (path routing) ───────────────────────────────────────
     // Build nested <details> from the doc tree; current-highlight, test status,
     // search visibility, and auto-open are applied imperatively by refreshNav.
@@ -512,12 +554,10 @@ export function createDocBrowser(options) {
             // Use the href from the closure, not the event — the click can land on a
             // child of the <a> (the localized label), so event.currentTarget/target
             // isn't reliably the anchor.
-            const href = hrefFor(doc.filename);
             const nav = event.target.closest('tosi-sidenav');
             if (nav)
                 nav.contentVisible = true;
-            window.history.pushState({ href }, '', href);
-            navigateTo(String(doc.filename));
+            go(String(doc.filename));
             event.preventDefault();
             const results = pageTestResults[doc.filename];
             if (results && !results.passed) {
@@ -598,7 +638,7 @@ export function createDocBrowser(options) {
         refreshNav(true);
         return root;
     };
-    const navContent = routing === 'path'
+    const navContent = routing !== 'query'
         ? buildHierarchicalNav()
         : div({
             ...navStyle,
@@ -613,12 +653,10 @@ export function createDocBrowser(options) {
             bindDocLink: '^.filename',
             bindTestStatus: '^.testStatus',
             onClick(event) {
-                const anchor = event.target;
                 const doc = getListItem(event.target);
                 const nav = event.target.closest('tosi-sidenav');
                 nav.contentVisible = true;
-                window.history.pushState({ href: anchor.href }, '', anchor.href);
-                navigateTo(String(doc.filename));
+                go(String(doc.filename));
                 event.preventDefault();
             },
         }, tosiLocalized({ bindText: '^.title' }))));
@@ -766,9 +804,7 @@ export function createDocBrowser(options) {
                         // Navigate to the page
                         const docObj = app.docs.find((d) => String(d.filename) === filename);
                         if (docObj) {
-                            const href = hrefFor(filename);
-                            window.history.pushState({ href }, '', href);
-                            navigateTo(filename);
+                            go(filename);
                             // Scroll to failing test after render
                             setTimeout(() => {
                                 const failedExample = document.querySelector('tosi-example.-test-failed');
@@ -825,9 +861,10 @@ export function createDocBrowser(options) {
         lines.unshift(`**Summary: ${totalPassed} passed, ${totalFailed} failed**`, '');
         return lines.join('\n');
     }
-    // Detect if running as background test iframe
+    // Detect if running as background test iframe (never for an embedded browser —
+    // it shares the host page's URL but isn't the test target).
     const searchParams = new URLSearchParams(window.location.search);
-    const isTestFrame = searchParams.get('_testMode') === '1';
+    const isTestFrame = !memoryRouting && searchParams.get('_testMode') === '1';
     const testFrameFilename = isTestFrame ? filenameFromLocation() : null;
     // Listen for test completion events
     container.addEventListener('testcomplete', ((event) => {
@@ -960,8 +997,20 @@ export function createDocBrowser(options) {
             }
         }
     };
-    // Start now if enabled, and watch for toggle
-    startBackgroundTests();
-    testManager.enabled.observe(startBackgroundTests);
+    // Start now if enabled, and watch for toggle. A memory-routed (embedded)
+    // browser never spawns the test-runner iframes (they'd navigate the host site).
+    if (!memoryRouting) {
+        startBackgroundTests();
+        testManager.enabled.observe(startBackgroundTests);
+    }
+    // Memory routing: let the host drive navigation programmatically (by slug) and
+    // read the current slug back, so the browser can live in a floating panel etc.
+    if (memoryRouting) {
+        ;
+        container.navigate = (slug) => navigateTo(filenameForSlug(slug) || slug);
+        Object.defineProperty(container, 'currentSlug', {
+            get: () => slugFor(String(app.currentDoc.filename)),
+        });
+    }
     return container;
 }

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

@@ -5,6 +5,8 @@ export declare class TosiDocSystem extends Component {
         docs: string;
         config: string;
         localized: string;
+        routing: string;
+        route: string;
         accent: string;
         background: string;
         text: string;
@@ -13,6 +15,9 @@ export declare class TosiDocSystem extends Component {
     content: null;
     private corpus?;
     private browser?;
+    private appliedRoute;
+    private suppressed;
+    private nestingDepth;
     private prefs;
     private stylesApplied;
     private applyStyles;

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

@@ -31,6 +31,15 @@ language).
 - `config` — inline JSON `{ projectName, projectLinks }` baked in at build time.
 - `localized` — URL of a tab-separated translation table; when set, it powers the
   settings menu's language picker.
+- `routing` — `''` (default) drives the page with clean `/slug/` URLs. Set
+  `"memory"` for a **self-contained** instance whose navigation never touches the
+  page URL or history — for embedding the docs in a dialog, side panel, or
+  floating element. (A `<tosi-doc-system>` nested inside another one — e.g. the
+  live demo on this page — is forced to memory routing automatically, and a demo
+  nested two levels deep renders an inert placeholder instead of recursing.)
+- `route` — memory routing only: the current doc's slug. Set it to navigate the
+  embedded browser to a doc; it's reflected back here as the user clicks around,
+  so a host can observe/bind it (e.g. to remember where a help panel was left).
 - `accent` / `background` / `text` — base theme colors (most of the palette is
   derived from `accent` via color math).
 
@@ -38,6 +47,13 @@ The element is light-DOM (no shadow root) so the pre-rendered markdown remains t
 real, indexable page content until hydration replaces it with the live browser.
 Live-example modules default to the `xinjs` / `xinjsui` IIFE globals; override by
 setting the element's `context` property before it connects.
+
+A self-contained, controllable embed (e.g. docs in a floating panel):
+
+```html
+<tosi-doc-system docs="/docs.json" routing="memory" route="data-table">
+</tosi-doc-system>
+```
 */
 /*{ "parent": "Appendices" }*/
 import { Component, StyleSheet, elements, tosi, vars } from 'tosijs';
@@ -47,7 +63,7 @@ import { docSystemStyleSpec } from './doc-system-styles';
 import { icons } from '../icons';
 import { popMenu } from '../menu';
 import { i18n, setLocale, initLocalization } from '../localize';
-const { button } = elements;
+const { button, div } = elements;
 const PREFS_KEY = 'tosi-doc-system-prefs';
 export class TosiDocSystem extends Component {
     static preferredTagName = 'tosi-doc-system';
@@ -55,6 +71,15 @@ export class TosiDocSystem extends Component {
         docs: '/docs.json',
         config: '',
         localized: '',
+        // Routing mode. '' (default) → clean `/slug/` URLs that drive the page. Set
+        // 'memory' (or 'internal') for a self-contained instance that never touches
+        // the page URL — for embedding the docs in a panel, dialog, etc. A nested
+        // <tosi-doc-system> (inside a live example) is forced to 'memory' too.
+        routing: '',
+        // Memory routing only: the current doc slug. Set it to navigate the embedded
+        // browser; it's reflected back here as the user clicks around, so a host can
+        // bind/observe it (e.g. docs in a floating element).
+        route: '',
         // Base theme colors — most of the palette is derived from `accent`.
         accent: '',
         background: '',
@@ -68,6 +93,27 @@ export class TosiDocSystem extends Component {
     // The loaded corpus and the mounted browser; both also act as one-time guards.
     corpus;
     browser;
+    // Route-reflection bookkeeping (memory routing): the last slug applied to the
+    // browser, so external `route` changes navigate but internal navigation (which
+    // writes `route` back) doesn't re-navigate or loop.
+    appliedRoute = '';
+    suppressed = false;
+    // How many <tosi-doc-system> ancestors this element has, crossing shadow
+    // boundaries. 0 = the page's own; ≥1 = embedded in another (e.g. the live
+    // demo on the doc-system page). Used to force memory routing on nested
+    // instances and to stop runaway recursion (a doc page that demos itself).
+    nestingDepth() {
+        let depth = 0;
+        let node = this.parentNode;
+        while (node) {
+            if (node.nodeType === Node.ELEMENT_NODE &&
+                node.tagName === 'TOSI-DOC-SYSTEM') {
+                depth++;
+            }
+            node = node.parentNode || node.host || null;
+        }
+        return depth;
+    }
     // User theme/locale preferences (persisted to localStorage).
     prefs;
     stylesApplied = false;
@@ -224,6 +270,15 @@ export class TosiDocSystem extends Component {
     }
     connectedCallback() {
         super.connectedCallback();
+        // A doc page can demo the doc system itself. The page's browser (depth 0)
+        // and one embedded demo (depth 1) are fine, but a demo INSIDE that demo
+        // (depth ≥ 2) would recurse forever — so render an inert placeholder and
+        // stop. (Don't even fetch the corpus.)
+        if (this.nestingDepth() >= 2) {
+            this.suppressed = true;
+            this.replaceChildren(div({ class: 'doc-system-nested' }, '📖 nested doc-system preview (suppressed)'));
+            return;
+        }
         this.applyStyles();
         this.initPrefs();
         void this.initLocale();
@@ -253,8 +308,19 @@ export class TosiDocSystem extends Component {
     }
     render() {
         super.render();
-        if (this.corpus === undefined || this.browser !== undefined)
+        if (this.suppressed || this.corpus === undefined)
+            return;
+        // Already mounted: the only live input is an external `route` change (memory
+        // routing), which navigates the embedded browser. The appliedRoute guard
+        // stops the browser's own write-back to `route` from re-navigating.
+        if (this.browser !== undefined) {
+            const navigate = this.browser.navigate;
+            if (navigate && this.route && this.route !== this.appliedRoute) {
+                this.appliedRoute = this.route;
+                navigate(this.route);
+            }
             return;
+        }
         let config = {};
         if (this.config) {
             try {
@@ -264,15 +330,28 @@ export class TosiDocSystem extends Component {
                 console.warn('<tosi-doc-system> ignoring invalid config attribute');
             }
         }
+        // Nested instances (a live demo of the doc system) must never drive the page
+        // URL — force memory routing. A top-level instance opts in via the attribute.
+        const nested = this.nestingDepth() >= 1;
+        const memory = nested || this.routing === 'memory' || this.routing === 'internal';
         // Adopt the pre-rendered markdown for the landing page so it is hydrated in
         // place, never re-rendered. createDocBrowser grafts this node into its content
         // area; the static nav list (already crawled) is replaced by the reactive one.
         const contentElement = this.querySelector('.doc-content') || undefined;
         // Header-bar links are declared as a real, crawlable list in the static page.
         const navbarLinks = this.parseLinks('.doc-navbar');
+        this.appliedRoute = this.route;
         this.browser = createDocBrowser({
             docs: this.corpus,
-            routing: 'path',
+            routing: memory ? 'memory' : 'path',
+            initialRoute: memory ? this.route || undefined : undefined,
+            onRouteChange: memory
+                ? (slug) => {
+                    // Record before reflecting so the resulting render() no-ops.
+                    this.appliedRoute = slug;
+                    this.route = slug;
+                }
+                : undefined,
             context: this.context || {
                 tosijs: globalThis.xinjs,
                 'tosijs-ui': globalThis.xinjsui,
@@ -282,10 +361,13 @@ export class TosiDocSystem extends Component {
             navbarLinks: navbarLinks.length ? navbarLinks : undefined,
             contentElement,
         });
-        // Add the settings (theme + language) menu to the header.
-        const header = this.browser.querySelector('header');
-        if (header)
-            header.append(this.settingsButton());
+        // Add the settings (theme + language) menu — except in a nested demo, where
+        // a gear that retints the whole host page would be surprising.
+        if (!nested) {
+            const header = this.browser.querySelector('header');
+            if (header)
+                header.append(this.settingsButton());
+        }
         this.replaceChildren(this.browser);
     }
 }

package/dist/doc-system/site/dev-server.d.ts

@@ -4,4 +4,5 @@ declare global {
 }
 export declare function devServer(config: SiteConfig, opts?: {
     test?: boolean;
+    build?: () => unknown | Promise<unknown>;
 }): Promise<void>;

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

@@ -98,9 +98,15 @@ export async function devServer(config, opts = {}) {
         }
     }
     if (!testMode) {
-        // Rebuild on any source change. buildSite() already re-extracts docs and
-        // regenerates icon-data, so a single rebuild covers everything. Serialize
-        // builds (no overlap) and coalesce bursts.
+        // Rebuild on any source change. By default that's just buildSite(), but a
+        // consumer whose full build has steps BEYOND buildSite — e.g. a custom IIFE
+        // bundle built separately (because it needs a Bun plugin buildSite can't
+        // take) — MUST pass opts.build with their whole pipeline. buildSite() starts
+        // with `rm -rf <outputDir>`, so any artifact those extra steps produced
+        // (iife.js, etc.) is deleted on the first rebuild and, without opts.build,
+        // never regenerated — leaving the page's /iife.js to 404 into the SPA
+        // fallback (it "loads as html"). Serialize builds and coalesce bursts.
+        const runBuild = opts.build ?? (() => buildSite(config));
         let building = false;
         let pending = false;
         const rebuild = async () => {
@@ -110,7 +116,7 @@ export async function devServer(config, opts = {}) {
             }
             building = true;
             try {
-                await buildSite(config);
+                await runBuild();
             }
             catch (error) {
                 console.error('rebuild failed:', error);

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

@@ -19,6 +19,9 @@ import { extractDocs } from './docs';
 import { ensureSections } from './sections';
 import { generateLlmsTxt } from './make-llms-txt';
 import { generateSite } from './generate-site';
+// Module specifiers contain regex metacharacters (`/`, `.`, `@`, …), so escape
+// before interpolating into the require-shim detector below.
+const escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 export async function buildSite(config) {
     const PROJECT_ROOT = './';
     const PUBLIC = path.resolve(PROJECT_ROOT, config.outputDir ?? 'docs');
@@ -89,13 +92,6 @@ export async function buildSite(config) {
     // consumer supplies (e.g. via staticDirs or an absolute URL).
     const scriptName = (config.scriptUrl ?? '/iife.js').replace(/^\//, '');
     if (config.bundleEntry) {
-        // IIFE externals become a synchronous require() shim that throws at
-        // module-eval ("Dynamic require of … is not supported") — the build still
-        // succeeds, so warn rather than fail silently.
-        if (config.bundleExternals && config.bundleExternals.length > 0) {
-            console.warn(`⚠️  bundleExternals in an IIFE bundle (${config.bundleExternals.join(', ')}): Bun emits a dynamic require() shim that throws at runtime. Load these\n` +
-                `    via import() (dynamically, so the bundler keeps them async) or an importmap, not a static import.`);
-        }
         const result = await Bun.build({
             entrypoints: [config.bundleEntry],
             outdir: DIST,
@@ -111,6 +107,23 @@ export async function buildSite(config) {
                 console.error(message);
             return false;
         }
+        // Warn only when an external actually compiled to a synchronous require()
+        // shim, which throws at module-eval ("Dynamic require of … is not
+        // supported"). That only happens for a *static* `import x from 'ext'`. A
+        // *dynamic* `import('ext')` is preserved as native `import("ext")` and
+        // resolves via the page's importmap — the recommended pattern, so it must
+        // stay silent. The config alone can't tell the two apart; the emitted
+        // bundle can, so we inspect the actual output.
+        if (config.bundleExternals && config.bundleExternals.length > 0) {
+            const js = (await Promise.all(result.outputs
+                .filter((o) => o.kind === 'entry-point' || o.path.endsWith('.js'))
+                .map((o) => o.text()))).join('\n');
+            const broken = config.bundleExternals.filter((ext) => new RegExp(`(?:__require|\\brequire)\\(\\s*["'\`]${escapeRegExp(ext)}["'\`]`).test(js));
+            if (broken.length > 0) {
+                console.warn(`⚠️  bundleExternals compiled to a synchronous require() shim that throws at runtime (${broken.join(', ')}). Reference these via a dynamic import() (kept async by the bundler)\n` +
+                    `    or an importmap, not a static import.`);
+            }
+        }
         await $ `cp ${DIST}/${scriptName} ${PUBLIC}`.text();
         const bundleFile = await Bun.file(`${DIST}/${scriptName}`).arrayBuffer();
         // import.meta is illegal in a classic <script> — if it survived bundling