tosijs-ui 1.16.35 → 1.16.36

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 1.16.36
+
+One additive site option. Nothing changes for a site that does not set it.
+
+- **A page can be served at a second path (#3513).** `aliases: { readme: '' }` in the site
+  config also writes the root page to `/readme/`, with its stylesheet, bundle and `docs.json`
+  references worked out for that depth, and the browser opens it as the README. Before this a
+  host rewrite was the only way, and it served the page one level down with every relative
+  reference 404ing, so the page rendered but never hydrated. An alias page's canonical link
+  names the page's own path, aliases stay out of the sitemap and the nav, and relative images
+  and links in the page are rewritten to reach the same files. An alias is one lowercase path
+  segment with no dot; the build fails on one that is not, that takes a page's own path or a
+  static folder's, or that names no page.
+
 ## 1.16.35
 
 Board follow-ups from 1.16.32 and 1.16.33, plus one tunnel feature. Nothing to change in an

package/dist/doc-browser.d.ts

@@ -102,6 +102,11 @@ export interface DocBrowserOptions {
      * doc). Lets a host mount the browser already pointed at a specific doc.
      */
     initialRoute?: string;
+    /**
+     * Path routing only: extra paths a doc is served at, `{ alias: slug }` (`''` is the root
+     * page). The site build passes its `aliases` here, so `/readme/` opens the README.
+     */
+    aliases?: Record<string, 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).

package/dist/doc-browser.js

@@ -354,7 +354,7 @@ const logoMarkStyleSpec = {
 // tosi() registry key (see stateKey below) and two browsers can't share state.
 let docBrowserSeq = 0;
 export function createDocBrowser(options) {
-    const { docs, context = {}, projectName = '', projectLinks = {}, logo, navSize = 200, minSize = 600, routing = 'query', initialRoute, onRouteChange, searchShortcut = 'mod+k', navbarLinks, contentElement, } = options;
+    const { docs, context = {}, projectName = '', projectLinks = {}, logo, navSize = 200, minSize = 600, routing = 'query', initialRoute, aliases = {}, onRouteChange, searchShortcut = 'mod+k', 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).
@@ -381,7 +381,7 @@ export function createDocBrowser(options) {
         if (memoryRouting)
             return initialRoute ? filenameForSlug(initialRoute) : '';
         return routing === 'path'
-            ? filenameForPath(document.location.pathname, slugMap)
+            ? filenameForPath(document.location.pathname, slugMap, aliases)
             : document.location.search !== ''
                 ? document.location.search.substring(1).split('&')[0]
                 : '';
@@ -414,7 +414,7 @@ export function createDocBrowser(options) {
         }
         // Clean `/slug/` path form (only meaningful when slugs are in play).
         if (!memoryRouting && routing !== 'query') {
-            const filename = known(filenameForPath(url.pathname, slugMap));
+            const filename = known(filenameForPath(url.pathname, slugMap, aliases));
             if (filename)
                 return filename;
         }

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

@@ -48,6 +48,8 @@ export declare class TosiDocSystem extends TosiDocSystem_base {
     private initPrefs;
     private initLocale;
     private settingsButton;
+    /** The site's `aliases`, which the build writes into the config attribute (board #3513). */
+    private configAliases;
     private parseLinks;
     connectedCallback(): void;
     render(): void;

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

@@ -485,6 +485,16 @@ export class TosiDocSystem extends withAttributes({
     // ---- Lifecycle -----------------------------------------------------------
     // Parse a declarative <ul class="..."> of <li><a href data-icon?>label</a> into
     // LinkItem[]. Returns [] when the list is absent.
+    /** The site's `aliases`, which the build writes into the config attribute (board #3513). */
+    configAliases() {
+        try {
+            const { aliases } = JSON.parse(this.config || '{}');
+            return aliases && typeof aliases === 'object' ? aliases : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
     parseLinks(selector) {
         const list = this.querySelector(selector);
         if (!list)
@@ -570,6 +580,7 @@ export class TosiDocSystem extends withAttributes({
         this.browser = createDocBrowser({
             docs: this.corpus,
             routing: memory ? 'memory' : 'path',
+            aliases: memory ? undefined : this.configAliases(),
             initialRoute: memory ? this.route || undefined : undefined,
             onRouteChange: memory
                 ? (slug) => {

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

@@ -55,8 +55,21 @@ export declare function slugForPath(pathname: string): string;
 /**
  * Resolve a browser location.pathname to a doc filename, using a slug map.
  * Returns '' if nothing matches (caller falls back to the first/README doc).
+ *
+ * `aliases` ({ alias path -> slug }, the site config's `aliases`) are a doc's extra paths: a
+ * page's own slug wins, so an alias never takes a path from a page.
+ */
+export declare function filenameForPath(pathname: string, slugMap: Record<string, string>, aliases?: Record<string, string>): string;
+/**
+ * Check a site's `aliases` against its slug map, and return the problems in words (empty when
+ * there are none). An alias is one lowercase path segment with no dot, takes no page's own
+ * path, and names a page.
+ *
+ * Lowercase because on a case-insensitive filesystem (macOS, Windows) writing `Guide/` replaces
+ * `guide/`, and a crawler at `/guide/` then got another page. No dot because every file the
+ * build writes at the root has one (`docs.json`, `sitemap.xml`, `llms.txt`).
  */
-export declare function filenameForPath(pathname: string, slugMap: Record<string, string>): string;
+export declare function aliasProblems(aliases: Record<string, string>, slugMap: Record<string, string>): string[];
 /** Turn a human name/title into a slug: 'Form Components' -> 'form-components'. */
 export declare function slugify(s: string): string;
 /**

package/dist/doc-system/routing.js

@@ -133,14 +133,47 @@ export function slugForPath(pathname) {
 /**
  * Resolve a browser location.pathname to a doc filename, using a slug map.
  * Returns '' if nothing matches (caller falls back to the first/README doc).
+ *
+ * `aliases` ({ alias path -> slug }, the site config's `aliases`) are a doc's extra paths: a
+ * page's own slug wins, so an alias never takes a path from a page.
  */
-export function filenameForPath(pathname, slugMap) {
+export function filenameForPath(pathname, slugMap, aliases = {}) {
     const slug = slugForPath(pathname);
-    for (const [filename, docSlug] of Object.entries(slugMap)) {
-        if (docSlug === slug)
-            return filename;
+    const find = (wanted) => {
+        for (const [filename, docSlug] of Object.entries(slugMap)) {
+            if (docSlug === wanted)
+                return filename;
+        }
+        return '';
+    };
+    const own = find(slug);
+    return own || (Object.hasOwn(aliases, slug) ? find(aliases[slug]) : '');
+}
+/**
+ * Check a site's `aliases` against its slug map, and return the problems in words (empty when
+ * there are none). An alias is one lowercase path segment with no dot, takes no page's own
+ * path, and names a page.
+ *
+ * Lowercase because on a case-insensitive filesystem (macOS, Windows) writing `Guide/` replaces
+ * `guide/`, and a crawler at `/guide/` then got another page. No dot because every file the
+ * build writes at the root has one (`docs.json`, `sitemap.xml`, `llms.txt`).
+ */
+export function aliasProblems(aliases, slugMap) {
+    const slugs = new Set(Object.values(slugMap));
+    const folded = new Set([...slugs].map((s) => s.toLowerCase()));
+    const problems = [];
+    for (const [alias, target] of Object.entries(aliases)) {
+        if (!/^[a-z0-9][a-z0-9_-]*$/.test(alias)) {
+            problems.push(`"${alias}" is not one lowercase path segment (a-z, 0-9, "_", "-")`);
+        }
+        else if (folded.has(alias)) {
+            problems.push(`"${alias}" is already a page's own path`);
+        }
+        if (!slugs.has(target)) {
+            problems.push(`"${alias}" names "${target}", which is no page's slug ('' is the root page)`);
+        }
     }
-    return '';
+    return problems;
 }
 /** Turn a human name/title into a slug: 'Form Components' -> 'form-components'. */
 export function slugify(s) {

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

@@ -6,6 +6,8 @@ declare global {
 }
 export interface GenerateSiteConfig {
     docs: Doc[];
+    /** `SiteConfig.aliases`: { alias path -> slug } (board #3513) */
+    aliases?: Record<string, string>;
     /**
      * Mirrors `SiteConfig.liveExamples`. The static highlighter needs it so it skips the
      * fences that will become live examples — a highlighted block hands the example markup
@@ -130,4 +132,10 @@ export declare function pageDepth(slug: string): number;
  */
 export declare function relativeUrl(depth: number, p: string): string;
 export declare function withStamp(url: string, stamp?: string): string;
+/**
+ * Rewrite the relative `href`/`src` references in rendered page HTML, written for a page at
+ * `fromPath` ('/' or '/slug/'), so they reach the same files from a page at `depth`. Rooted
+ * (`/x`), external, `#`, `?` and `data:`-style references are left alone.
+ */
+export declare function rebaseRelativeRefs(html: string, fromPath: string, depth: number): string;
 export declare function generateSite(config: GenerateSiteConfig): Promise<number>;

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

@@ -12,10 +12,11 @@ component (src/doc-system/*) so static and hydrated output agree.
 */
 import { pageTitle } from '../doc-title.js';
 import { highlightHtml } from '../highlight.js';
-import { buildSlugMap, pathForSlug, rewriteDocLinks, withBase, wikilinkTargets, } from '../routing.js';
+import { aliasProblems, buildSlugMap, pathForSlug, rewriteDocLinks, withBase, wikilinkTargets, } from '../routing.js';
 import { buildNavTree, navOpenPath } from '../nav-tree.js';
 import { renderDocMarkdown, docDescription, } from '../render.js';
 import { bareNameLinks, deadInPageAnchors, missingWikilinks, misconfigured, } from './build-warnings.js';
+import { existsSync } from 'fs';
 const escapeAttr = (s) => s
     .replace(/&/g, '&')
     .replace(/</g, '&lt;')
@@ -111,11 +112,14 @@ export function relativeUrl(depth, p) {
     const rel = '../'.repeat(depth) + p.slice(1);
     return rel === '' ? './' : rel;
 }
-async function pageHtml(doc, config, slugMap, configAttr, wikilinks) {
+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] ?? '') {
     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(slugMap[doc.filename] ?? '');
+    const depth = pageDepth(at);
+    const own = slugMap[doc.filename] ?? '';
     const localizedAttr = config.localizedStrings
         ? ` localized="${escapeAttr(relativeUrl(depth, localizedUrl))}"`
         : '';
@@ -142,7 +146,7 @@ async function pageHtml(doc, config, slugMap, configAttr, wikilinks) {
     // Rewrite legacy `?filename` content links to clean `/slug/` paths so the
     // static HTML is correct for no-JS readers and crawlers (the doc-browser also
     // does this client-side after hydration).
-    const body = rewriteDocLinks(await highlightHtml(renderDocMarkdown(doc.text, {
+    const rendered = rewriteDocLinks(await highlightHtml(renderDocMarkdown(doc.text, {
         bakes: bakes?.get(doc.filename),
         wikilinks,
     }), 
@@ -151,6 +155,11 @@ async function pageHtml(doc, config, slugMap, configAttr, wikilinks) {
     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
+        ? rendered
+        : rebaseRelativeRefs(rendered, pathForSlug(own), depth);
     const nav = navHtml(config.docs, slugMap, doc.filename, depth);
     const navbar = linkListHtml('doc-navbar', config.navbarLinks);
     const jsonLd = baseUrl
@@ -289,6 +298,19 @@ export function withStamp(url, stamp) {
         return url;
     return `${url}?v=${encodeURIComponent(stamp)}`;
 }
+/**
+ * Rewrite the relative `href`/`src` references in rendered page HTML, written for a page at
+ * `fromPath` ('/' or '/slug/'), so they reach the same files from a page at `depth`. Rooted
+ * (`/x`), external, `#`, `?` and `data:`-style references are left alone.
+ */
+export function rebaseRelativeRefs(html, fromPath, depth) {
+    return html.replace(/(\s(?:href|src|poster)=")([^"]*)"/g, (match, attr, ref) => {
+        if (!ref || /^(?:[a-z][a-z0-9+.-]*:|\/|#|\?)/i.test(ref))
+            return match;
+        const rooted = new URL(ref, `https://x${fromPath}`);
+        return `${attr}${relativeUrl(depth, rooted.pathname + rooted.search + rooted.hash)}"`;
+    });
+}
 export async function generateSite(config) {
     const { docs, outputDir } = config;
     const slugMap = buildSlugMap(docs);
@@ -303,8 +325,19 @@ export async function generateSite(config) {
         }
         seen.set(slug, doc.filename);
     }
+    // A wrong alias fails the build like a `home` that names no page: it is a typo or a
+    // renamed page, and a site with a dead path is not one to ship quietly.
+    const aliases = config.aliases ?? {};
+    const problems = aliasProblems(aliases, slugMap);
+    if (problems.length) {
+        throw new Error(`generate-site: aliases are wrong:\n${problems
+            .map((p) => `    ${p}`)
+            .join('\n')}`);
+    }
     const configAttr = escapeAttr(JSON.stringify({
         projectName: config.projectName,
+        // The browser needs them too, or an alias page hydrates as whichever doc comes first.
+        ...(Object.keys(aliases).length ? { aliases } : {}),
         projectLinks: config.projectLinks,
         logo: config.logo,
         bookVolumes: config.bookVolumes,
@@ -341,6 +374,26 @@ export async function generateSite(config) {
         }
         count += 1;
     }
+    /*
+    Each alias is the page again, written where the alias is served, so its relative references
+    (stylesheet, bundle, docs.json, nav links) resolve from there. A host rewrite to the original
+    page cannot do that: it serves the same bytes at a different depth and the page never
+    hydrates (board #3513). The canonical link stays the page's own path.
+    */
+    for (const [alias, target] of Object.entries(aliases)) {
+        const doc = docs.find((d) => slugMap[d.filename] === target);
+        const dir = `${outputDir}/${alias}`;
+        // The output folder starts empty, so anything already here is a static file or folder, or
+        // one the build wrote (`tjs/`, `_chunks/`): an alias must not write into it.
+        if (existsSync(dir)) {
+            throw new Error(`generate-site: the alias "${alias}" names /${alias}/, which the site already has ` +
+                `(a static file or folder, or one the build writes); choose another name`);
+        }
+        await Bun.write(`${dir}/index.html`, await pageHtml(doc, config, slugMap, configAttr, wikilinks, alias));
+        if (hasMarkdownPage(doc, config)) {
+            await Bun.write(`${dir}/index.md`, doc.text.trimEnd() + '\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` +

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

@@ -1491,6 +1491,7 @@ export async function buildSite(config, opts = {}) {
             const pageCount = await generateSite({
                 liveExamples: config.liveExamples,
                 docs,
+                aliases: config.aliases,
                 outputDir: PUBLIC,
                 projectName: config.name,
                 bookVolumes: printCoverManifestUrl(config),

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

@@ -61,6 +61,16 @@ export interface SiteConfig {
      * names no page. A doc can also claim the root itself with `{"home": true}`.
      */
     home?: string;
+    /**
+     * Extra paths a page is served at, as `{ alias: slug }`; `''` is the root page. With
+     * `aliases: { readme: '' }` the README (the root page) is also written to `/readme/`, with its
+     * stylesheet, bundle and `docs.json` references computed for that depth, and the browser
+     * opens it as the README. Each alias page's canonical link names the page's own path, and
+     * aliases stay out of the sitemap and the nav; relative references in the page are rewritten
+     * to reach the same files. An alias is one lowercase path segment with no dot; the build fails
+     * on one that is not, that takes a page's own path or a static folder's, or that names no page.
+     */
+    aliases?: Record<string, string>;
     /**
      * Directories to skip while scanning `docPaths` — by basename (skipped wherever it
      * appears) or by path (skipped only at that location). Added to the built-in