tosijs-ui 1.6.10 → 1.6.12

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+## 1.6.12
+
+Packaging improvements for independent, tree-shakeable consumption. All changes
+are **additive — no breaking changes**; one minor behavioral edge case is noted
+below.
+
+### Added
+
+- **Subpath exports**, so an app can import only what it needs without the barrel
+  dragging in dev tools:
+  - curated: `tosijs-ui/icons`, `tosijs-ui/code-editor`, `tosijs-ui/live-example`,
+    `tosijs-ui/doc-browser`, `tosijs-ui/diff`, `tosijs-ui/theme`
+  - per-component wildcard: `import { tosiRating } from 'tosijs-ui/rating'`
+    (resolves `dist/rating.js`, registering just that element)
+
+  The full barrel `import 'tosijs-ui'` is unchanged and still registers every
+  `<tosi-*>` element.
+
+### Changed
+
+- **`menu`, `tooltip`, and `float` now inject their stylesheet and register their
+  global listeners on first use, not at import.** Importing these modules (or the
+  barrel) no longer has import-time side effects. This also fixes a latent bug
+  where the menu `keydown` handler attached to `document.body` at import time,
+  which may not exist yet.
+
+### Possible edge case
+
+If you imported `menu` / `tooltip` / `float` **purely for the side effect** — i.e.
+you hand-author markup with the internal classes (`.tosi-menu`, `.tosi-tooltip`,
+…) and relied on a bare `import` injecting the stylesheet, **without** ever
+calling the API (`popMenu`, `popDropMenu`, `initTooltips`, `showTooltip`) or using
+the `<tosi-*>` element — those styles now apply only once the API/element is first
+used. Normal usage (the element creators, the `<tosi-*>` elements, and the
+`popMenu`/`initTooltips` entry points) is unaffected.

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;
+}

package/dist/float.js

@@ -131,6 +131,7 @@ export class TosiFloat extends WebComponent {
     };
     connectedCallback() {
         super.connectedCallback();
+        ensureFloatListeners();
         TosiFloat.floats.add(this);
         const PASSIVE = { passive: true };
         this.addEventListener('touchstart', this.reposition, PASSIVE);
@@ -147,27 +148,37 @@ export const XinFloat = TosiFloat;
 export const tosiFloat = TosiFloat.elementCreator();
 /** @deprecated Use tosiFloat instead */
 export const xinFloat = tosiFloat;
-window.addEventListener('resize', () => {
-    Array.from(TosiFloat.floats).forEach((float) => {
-        if (float.remainOnResize === 'hide') {
-            float.hidden = true;
-        }
-        else if (float.remainOnResize === 'remove') {
-            float.remove();
-        }
-    });
-}, { passive: true });
-document.addEventListener('scroll', (event) => {
-    if (event.target instanceof HTMLElement &&
-        event.target.closest(TosiFloat.tagName)) {
+// Register the global reposition/dismiss handlers on first float connecting,
+// not at import (keeps the module side-effect-free for tree-shaking). They
+// iterate TosiFloat.floats, so they're no-ops until a float exists — registered
+// once, no teardown needed.
+let floatListenersRegistered = false;
+function ensureFloatListeners() {
+    if (floatListenersRegistered)
         return;
-    }
-    Array.from(TosiFloat.floats).forEach((float) => {
-        if (float.remainOnScroll === 'hide') {
-            float.hidden = true;
-        }
-        else if (float.remainOnScroll === 'remove') {
-            float.remove();
+    floatListenersRegistered = true;
+    window.addEventListener('resize', () => {
+        Array.from(TosiFloat.floats).forEach((float) => {
+            if (float.remainOnResize === 'hide') {
+                float.hidden = true;
+            }
+            else if (float.remainOnResize === 'remove') {
+                float.remove();
+            }
+        });
+    }, { passive: true });
+    document.addEventListener('scroll', (event) => {
+        if (event.target instanceof HTMLElement &&
+            event.target.closest(TosiFloat.tagName)) {
+            return;
         }
-    });
-}, { passive: true, capture: true });
+        Array.from(TosiFloat.floats).forEach((float) => {
+            if (float.remainOnScroll === 'hide') {
+                float.hidden = true;
+            }
+            else if (float.remainOnScroll === 'remove') {
+                float.remove();
+            }
+        });
+    }, { passive: true, capture: true });
+}