tosijs-ui 1.6.9 → 1.6.11

package/README.md

@@ -67,7 +67,7 @@ npm add tosijs-ui
 Then import the component `elementCreator` and create elements. A `tosijs`
 `elementCreator` is syntax sugar around `document.createElement()`.
 
-```ts
+```typescript
 import { tosiTable } from 'tosijs-ui'
 
 document.body.append(tosiTable())

package/dist/doc-browser.js

@@ -274,6 +274,40 @@ export function createDocBrowser(options) {
                 ? document.location.search.substring(1).split('&')[0]
                 : '';
     };
+    // Resolve a content-link anchor to one of our docs' filenames, in either the
+    // legacy `?filename` form or a clean `/slug/` path — or null for external
+    // links, in-page anchors, mailto:, downloads, etc. Used to navigate internal
+    // doc links client-side (via go()) instead of triggering a full page reload,
+    // and to canonicalize their hrefs for the current routing mode.
+    const docFilenameForHref = (anchor) => {
+        const raw = anchor.getAttribute('href') || '';
+        if (raw === '' || raw.startsWith('#'))
+            return null;
+        let url;
+        try {
+            url = new URL(raw, document.location.href);
+        }
+        catch {
+            return null;
+        }
+        if (url.origin !== document.location.origin)
+            return null; // external
+        const known = (filename) => docs.some((doc) => doc.filename === filename) ? filename : null;
+        // Legacy `?filename` form: a single bare filename, not a real query string.
+        const query = url.search.replace(/^\?/, '');
+        if (query !== '' && !query.includes('=') && !query.includes('&')) {
+            const filename = known(decodeURIComponent(query));
+            if (filename)
+                return filename;
+        }
+        // Clean `/slug/` path form (only meaningful when slugs are in play).
+        if (!memoryRouting && routing !== 'query') {
+            const filename = known(filenameForPath(url.pathname, slugMap));
+            if (filename)
+                return filename;
+        }
+        return null;
+    };
     const docName = filenameFromLocation() || docs[0]?.filename || 'README.md';
     const currentDoc = docs.find((doc) => doc.filename === docName) || docs[0];
     const { app } = tosi({
@@ -512,6 +546,20 @@ export function createDocBrowser(options) {
     // 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.
+    // Canonicalize internal content links to the current routing mode's href and
+    // tag them — so copy-link / right-click / no-JS land on the right page, and a
+    // left-click can be short-circuited to client-side nav. Authored docs use the
+    // routing-agnostic `?filename` form (the only one resolvable in every mode);
+    // this rewrites them to `/slug/` on the static path-routed site, etc.
+    const rewriteContentLinks = () => {
+        for (const anchor of docContent.querySelectorAll('a')) {
+            const filename = docFilenameForHref(anchor);
+            if (filename !== null) {
+                anchor.setAttribute('href', hrefFor(filename));
+                anchor.dataset.docLink = filename;
+            }
+        }
+    };
     let adoptInitialContent = contentElement !== undefined && !memoryRouting;
     const showDoc = (doc) => {
         if (adoptInitialContent) {
@@ -520,6 +568,7 @@ export function createDocBrowser(options) {
         else {
             docContent.innerHTML = renderDocMarkdown(doc.text);
         }
+        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).
         LiveExample.insertExamples(docContent, context, doc.path || undefined);
@@ -554,6 +603,28 @@ export function createDocBrowser(options) {
         }
         navigateTo(filename);
     };
+    // Intercept clicks on internal doc links anywhere in the rendered content so
+    // they navigate client-side instead of reloading the page. Plain left-clicks
+    // only — modified clicks / middle-clicks / new-tab / download links fall
+    // through to the browser. Works for both freshly-rendered and statically
+    // pre-rendered (adopted) content, resolving the href at click time.
+    docContent.addEventListener('click', (event) => {
+        if (event.defaultPrevented ||
+            event.button !== 0 ||
+            event.metaKey ||
+            event.ctrlKey ||
+            event.shiftKey ||
+            event.altKey)
+            return;
+        const anchor = event.target.closest('a');
+        if (!anchor || anchor.target === '_blank' || anchor.hasAttribute('download'))
+            return;
+        const filename = docFilenameForHref(anchor);
+        if (filename === null)
+            return;
+        event.preventDefault();
+        go(filename);
+    });
     // ── Edit page source (Foundation B / #4) ──────────────────────────────────
     // The "view source" affordance opens a menu: edit the whole source file in a
     // code editor that fills the content area, preview the result in-browser, and
@@ -656,6 +727,7 @@ export function createDocBrowser(options) {
         editUI.view = view;
         if (view === 'preview') {
             docContent.innerHTML = renderDocMarkdown(docMarkdownFromSource(editUI.editor.value, editUI.doc.path));
+            rewriteContentLinks();
             LiveExample.insertExamples(docContent, context, editUI.doc.path || undefined);
         }
         else if (view === 'diff') {

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

@@ -12,6 +12,14 @@ export interface DocLike {
 export declare function buildSlugMap(docs: DocLike[]): Record<string, string>;
 /** site-root-relative path for a slug: '' -> '/', 'button' -> '/button/' */
 export declare function pathForSlug(slug: string): string;
+/**
+ * Rewrite legacy `?<filename>` (and `/?<filename>`) doc links in an HTML string
+ * to resolved hrefs. Used by the static generator so the pre-rendered pages have
+ * clean links for no-JS readers, crawlers, and the brief window before the
+ * doc-browser hydrates. `hrefFor` returns the target href for a known filename,
+ * or null to leave the link untouched (unknown filename / a real query string).
+ */
+export declare function rewriteDocLinks(html: string, hrefFor: (filename: string) => string | null): string;
 /**
  * Map a legacy `?<filename>` query (the old doc-browser's query-param routing,
  * e.g. `?button.ts`, `?README.md`) to the new slug path (`/button/`, `/`).

package/dist/doc-system/routing.js

@@ -46,6 +46,19 @@ export function buildSlugMap(docs) {
 export function pathForSlug(slug) {
     return slug === '' ? '/' : `/${slug}/`;
 }
+/**
+ * Rewrite legacy `?<filename>` (and `/?<filename>`) doc links in an HTML string
+ * to resolved hrefs. Used by the static generator so the pre-rendered pages have
+ * clean links for no-JS readers, crawlers, and the brief window before the
+ * doc-browser hydrates. `hrefFor` returns the target href for a known filename,
+ * or null to leave the link untouched (unknown filename / a real query string).
+ */
+export function rewriteDocLinks(html, hrefFor) {
+    return html.replace(/href="\/?\?([^"&=]+)"/g, (match, query) => {
+        const href = hrefFor(decodeURIComponent(query));
+        return href === null ? match : `href="${href}"`;
+    });
+}
 /**
  * Map a legacy `?<filename>` query (the old doc-browser's query-param routing,
  * e.g. `?button.ts`, `?README.md`) to the new slug path (`/button/`, `/`).

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

@@ -10,7 +10,7 @@ the IIFE bundle loads.
 Build-time only (uses Bun.write). Shares slug + markdown rendering with the runtime
 component (src/doc-system/*) so static and hydrated output agree.
 */
-import { buildSlugMap, pathForSlug } from '../routing';
+import { buildSlugMap, pathForSlug, rewriteDocLinks } from '../routing';
 import { buildNavTree, navOpenPath } from '../nav-tree';
 import { renderDocMarkdown, docDescription } from '../render';
 const escapeAttr = (s) => s
@@ -93,7 +93,12 @@ function pageHtml(doc, config, slugMap, configAttr) {
         : doc.keywords || '';
     const canonical = baseUrl + withBase(basePath, pathForSlug(slugMap[doc.filename]));
     const imageAbs = absUrl(baseUrl, withBase(basePath, doc.image || config.ogImage || ''));
-    const body = renderDocMarkdown(doc.text);
+    // 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(renderDocMarkdown(doc.text), (filename) => slugMap[filename] !== undefined
+        ? withBase(basePath, pathForSlug(slugMap[filename]))
+        : null);
     const nav = navHtml(config.docs, slugMap, doc.filename, basePath);
     const navbar = linkListHtml('doc-navbar', config.navbarLinks);
     const jsonLd = baseUrl

package/dist/doc-system/site/make-llms-txt.d.ts

@@ -1,11 +1,38 @@
+/** A doc as it appears in the extracted corpus (docs.json). */
+interface CorpusDoc {
+    title?: string;
+    filename: string;
+    text?: string;
+    description?: string;
+    hidden?: boolean;
+}
+interface LlmsEntry {
+    title: string;
+    description: string;
+    /** rendered-doc URL (corpus mode) or dist/*.js path (legacy scan) */
+    link: string;
+}
 export interface LlmsTxtMeta {
     name?: string;
     description?: string;
-    /** site origin, used for the Docs link */
+    /** site origin, used for the Docs link and to make page links absolute */
     baseUrl?: string;
     /** project links — `github` / `npm` (or any) become Source/npm links */
     projectLinks?: Record<string, string | undefined>;
     /** optional framing line(s) under the description */
     tagline?: string;
 }
-export declare function generateLlmsTxt(outputPath: string, meta?: LlmsTxtMeta): void;
+/**
+ * Build entries from the extracted corpus — every doc that was actually
+ * extracted (`.md`, `.ts`/`.js`/`.css` doc comments, auto-created sections),
+ * linking to its rendered URL. This is what the build uses: it reflects the real
+ * docs and needs no `dist/` library output.
+ */
+export declare function entriesFromCorpus(corpus: CorpusDoc[], meta: LlmsTxtMeta): LlmsEntry[];
+/**
+ * Write an `llms.txt` index. Pass the extracted `corpus` (the build does) to
+ * index every doc by its rendered URL; omit it to fall back to the legacy
+ * `src/*.ts`-with-`dist/*.js` scan.
+ */
+export declare function generateLlmsTxt(outputPath: string, meta?: LlmsTxtMeta, corpus?: CorpusDoc[]): void;
+export {};

package/dist/doc-system/site/make-llms-txt.js

@@ -1,5 +1,6 @@
 import * as fs from 'fs';
 import * as path from 'path';
+import { buildSlugMap, pathForSlug } from '../routing';
 const SRC = 'src';
 const DIST = 'dist';
 function extractTitle(text) {
@@ -33,19 +34,37 @@ function extractDescription(text) {
     }
     return '';
 }
-export function generateLlmsTxt(outputPath, meta = {}) {
-    // package.json supplies fallback name/version/description, but a doc site
-    // isn't guaranteed to have one (or it may be unreadable) — degrade gracefully
-    // rather than aborting the whole build.
-    let pkg = {};
+/**
+ * Build entries from the extracted corpus — every doc that was actually
+ * extracted (`.md`, `.ts`/`.js`/`.css` doc comments, auto-created sections),
+ * linking to its rendered URL. This is what the build uses: it reflects the real
+ * docs and needs no `dist/` library output.
+ */
+export function entriesFromCorpus(corpus, meta) {
+    const slugMap = buildSlugMap(corpus);
+    const base = (meta.baseUrl ?? '').replace(/\/$/, '');
+    return corpus
+        .filter((doc) => doc.title && !doc.hidden)
+        .map((doc) => ({
+        title: doc.title,
+        description: doc.description?.trim() || extractDescription(doc.text ?? ''),
+        link: base + pathForSlug(slugMap[doc.filename]),
+    }))
+        .sort((a, b) => a.title.localeCompare(b.title));
+}
+/**
+ * Legacy fallback when no corpus is passed (e.g. running this file directly):
+ * scan `src/*.ts` for doc-comment blocks that have a built `dist/*.js` sibling.
+ */
+function entriesFromSrcScan() {
+    const entries = [];
+    let files = [];
     try {
-        pkg = JSON.parse(fs.readFileSync('package.json', 'utf8'));
+        files = fs.readdirSync(SRC).filter((f) => f.endsWith('.ts'));
     }
     catch {
-        console.warn('llms.txt: no readable package.json — using config values only');
+        return entries;
     }
-    const docs = [];
-    const files = fs.readdirSync(SRC).filter((f) => f.endsWith('.ts'));
     for (const file of files) {
         const content = fs.readFileSync(path.join(SRC, file), 'utf8');
         const match = content.match(/\/\*#([\s\S]+?)\*\//);
@@ -53,21 +72,36 @@ export function generateLlmsTxt(outputPath, meta = {}) {
             continue;
         const markdown = match[1].trim();
         const title = extractTitle(markdown);
-        const description = extractDescription(markdown);
         if (!title)
             continue;
         const distFile = file.replace(/\.ts$/, '.js');
-        const distPath = path.join(DIST, distFile);
-        if (!fs.existsSync(distPath))
+        if (!fs.existsSync(path.join(DIST, distFile)))
             continue;
-        docs.push({
+        entries.push({
             title,
-            description,
-            srcFile: `src/${file}`,
-            distFile: `dist/${distFile}`,
+            description: extractDescription(markdown),
+            link: `dist/${distFile}`,
         });
     }
-    docs.sort((a, b) => a.title.localeCompare(b.title));
+    return entries.sort((a, b) => a.title.localeCompare(b.title));
+}
+/**
+ * Write an `llms.txt` index. Pass the extracted `corpus` (the build does) to
+ * index every doc by its rendered URL; omit it to fall back to the legacy
+ * `src/*.ts`-with-`dist/*.js` scan.
+ */
+export function generateLlmsTxt(outputPath, meta = {}, corpus) {
+    // package.json supplies fallback name/version/description, but a doc site
+    // isn't guaranteed to have one (or it may be unreadable) — degrade gracefully
+    // rather than aborting the whole build.
+    let pkg = {};
+    try {
+        pkg = JSON.parse(fs.readFileSync('package.json', 'utf8'));
+    }
+    catch {
+        console.warn('llms.txt: no readable package.json — using config values only');
+    }
+    const entries = corpus ? entriesFromCorpus(corpus, meta) : entriesFromSrcScan();
     const name = meta.name ?? pkg.name ?? '';
     const description = meta.description ?? pkg.description ?? '';
     const links = [];
@@ -89,24 +123,22 @@ export function generateLlmsTxt(outputPath, meta = {}) {
         '',
         '## Documentation',
         '',
-        'Each component\'s full documentation (with live code examples) is',
-        'embedded in its distributed JS file as inline comments. Read the',
-        'relevant dist/*.js file for complete docs, usage examples, and API.',
+        'Full documentation, with live code examples, is at the links below.',
         '',
-        '## Components and Utilities',
+        '## Pages',
         '',
     ];
-    for (const doc of docs) {
-        lines.push(`- ${doc.distFile} — ${doc.title}`);
-        if (doc.description) {
-            lines.push(`  ${doc.description}`);
+    for (const entry of entries) {
+        lines.push(`- ${entry.link} — ${entry.title}`);
+        if (entry.description) {
+            lines.push(`  ${entry.description}`);
         }
     }
     lines.push('');
     fs.writeFileSync(outputPath, lines.join('\n'), 'utf8');
-    console.log(`llms.txt generated (${docs.length} entries)`);
+    console.log(`llms.txt generated (${entries.length} entries)`);
 }
-// Allow running directly
+// Allow running directly (no corpus — uses the legacy src/*.ts scan)
 if (import.meta.main) {
     generateLlmsTxt('dist/llms.txt');
 }

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

@@ -19,6 +19,7 @@ import { extractDocs } from './docs';
 import { ensureSections } from './sections';
 import { generateLlmsTxt } from './make-llms-txt';
 import { generateSite } from './generate-site';
+import { findOutputDirOverlap } from './output-guard';
 // Module specifiers contain regex metacharacters (`/`, `.`, `@`, …), so escape
 // before interpolating into the require-shim detector below.
 const escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
@@ -39,10 +40,20 @@ export async function buildSite(config) {
     console.time('prebuild');
     // Project-specific codegen (version stamp, icon data, …) before anything else.
     await config.prebuild?.();
+    // Guard before the destructive `rm -rf`: if a docPath overlaps the output dir,
+    // wiping the output would delete the source docs we're about to extract.
+    const docPaths = config.docPaths ?? ['src', 'README.md'];
+    const overlap = findOutputDirOverlap(docPaths, config.outputDir ?? 'docs', PROJECT_ROOT);
+    if (overlap) {
+        throw new Error(`doc-site build: docPath "${overlap}" overlaps outputDir "${config.outputDir ?? 'docs'}". ` +
+            'buildSite() runs `rm -rf <outputDir>` before extracting docs, so this would ' +
+            'delete your source docs first (producing an empty site with no error). Move the ' +
+            "source docs out of the output dir, or set a different outputDir (e.g. outputDir: 'site').");
+    }
     await $ `rm -rf ${PUBLIC}`.text();
     await $ `mkdir ${PUBLIC}`.text();
     const extract = () => extractDocs({
-        paths: config.docPaths ?? ['src', 'README.md'],
+        paths: docPaths,
         // Skip the build's own output dir by path (not by the name 'docs', so a
         // source dir like src/docs is still scanned).
         ignore: ['node_modules', 'dist', 'build', PUBLIC],
@@ -139,8 +150,11 @@ export async function buildSite(config) {
         console.log(`${scriptName}: ${(bundleFile.byteLength / 1024).toFixed(1)}kb (${(bundleGzip.length / 1024).toFixed(1)}kb gzip)`);
     }
     if (config.llmsTxt !== false) {
+        // Drive llms.txt from the extracted corpus (every doc, by rendered URL) — not
+        // a re-scan of src/*.ts — so it works regardless of doc source (.md, etc.)
+        // and whether the project emits a dist/ library.
+        const corpus = JSON.parse(await Bun.file(DOCS_JSON).text());
         if (typeof config.llmsTxt === 'function') {
-            const corpus = JSON.parse(await Bun.file(DOCS_JSON).text());
             await Bun.write('llms.txt', config.llmsTxt(corpus));
         }
         else {
@@ -149,7 +163,7 @@ export async function buildSite(config) {
                 description: config.description,
                 baseUrl: config.baseUrl,
                 projectLinks: config.projectLinks,
-            });
+            }, corpus);
         }
         // Also place it at the served web root so {baseUrl}/llms.txt resolves (the
         // root copy stays for the npm package's `files`).

package/dist/doc-system/site/output-guard.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Return the first `docPaths` entry that overlaps `outputDir` (the same
+ * directory, or either nested inside the other), or null if none overlap.
+ *
+ * `buildSite()` runs `rm -rf <outputDir>` before it extracts docs, so an overlap
+ * means the source docs get deleted *before* they're read — silently producing
+ * an empty site with no error. Callers throw an actionable message instead.
+ */
+export declare function findOutputDirOverlap(docPaths: string[], outputDir: string, root?: string): string | null;

package/dist/doc-system/site/output-guard.js

@@ -0,0 +1,22 @@
+import * as path from 'path';
+/**
+ * Return the first `docPaths` entry that overlaps `outputDir` (the same
+ * directory, or either nested inside the other), or null if none overlap.
+ *
+ * `buildSite()` runs `rm -rf <outputDir>` before it extracts docs, so an overlap
+ * means the source docs get deleted *before* they're read — silently producing
+ * an empty site with no error. Callers throw an actionable message instead.
+ */
+export function findOutputDirOverlap(docPaths, outputDir, root = '.') {
+    // Compare as directory prefixes (trailing separator) so '/docs' doesn't
+    // falsely match '/docs-site', while genuine nesting ('/docs' vs '/docs/api')
+    // and exact matches still do.
+    const withSep = (p) => (p.endsWith(path.sep) ? p : p + path.sep);
+    const out = withSep(path.resolve(root, outputDir));
+    for (const docPath of docPaths) {
+        const resolved = withSep(path.resolve(root, docPath));
+        if (resolved.startsWith(out) || out.startsWith(resolved))
+            return docPath;
+    }
+    return null;
+}