tosijs-ui 1.15.3 → 1.15.4

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # Changelog
 
+## 1.15.4
+
+### `libraryBundle`: a library build Node can actually load (#169)
+
+`emitLibrary` and `libraryTsconfig` run a bare `tsc`, which copies each import specifier through
+unchanged. Written in the usual bundler style (`export * from './model'`), that produces a
+`dist/` **Node refuses** (`ERR_MODULE_NOT_FOUND`), though Bun and bundlers resolve it, so it
+tends to ship unnoticed. Three projects had each written their own guard for it.
+
+The new `libraryBundle` option is the paved road:
+
+```ts
+libraryBundle: { entries: ['src/index.ts', 'src/core.ts'] }
+```
+
+`bun build` bundles the entries with code-splitting (every declared dependency and peer stays an
+import), `tsc` emits declarations only, and the build **fails** if `dist/` still has a relative
+import without a file extension. Options: `externals` (default: all declared dependencies and
+peers), `tsconfig` for the declaration pass, `target` (default `browser`). It needs `typescript`
+installed, as any TypeScript library has.
+
+`emitLibrary` and `libraryTsconfig` keep working, and now **warn** when their output has that
+problem.
+
+### Tag colours on chips and in the pick menu (#173)
+
+A Tag in `<tosi-tag-list>`'s `availableTags` can carry `background` and `color`. Chips now use
+them (they were ignored), and the pick menu shows each coloured tag's caption as a lozenge in
+those colours, with the checkmark beside it. Without a `color`, the text is black or white,
+whichever contrasts more.
+
+### Tag list fixes (#189)
+
+- A Tag object without a `caption` (the obvious way to colour chips: `{ value, color, background }`)
+  showed as a **blank row** in the pick menu; on a phone, a tall empty column. It now shows its
+  value.
+- A selected tag that was also in `availableTags` as an object appeared in the menu **twice**:
+  string tags were compared against Tag objects with `includes`. It now compares by value.
+- `<tosi-tag-list>`'s `value` is documented as `string | string[]`, but an array threw
+  `split is not a function` on render.
+
+### `emitLibrary` no longer ships `tsconfig.tsbuildinfo`
+
+Libraries built with `emitLibrary` shipped TypeScript's incremental-build cache in `dist/`: no
+use to consumers, and different on every rebuild. It is gone; rebuild and republish to drop it
+from your package.
+
 ## 1.15.3
 
 ### `<tosi-md sanitize="on">`, and a heads-up: it becomes the default in 1.16 (#179)

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

@@ -8,6 +8,7 @@ export { openDevBrowser, buildOpenPlan } from './open-browser.js';
 export type { OpenPlan, OpenPlanInput } from './open-browser.js';
 export { extractDocs, saveDocsJSON } from './docs.js';
 export type { Doc } from './docs.js';
+export type { LibraryBundle } from './library-bundle.js';
 export { generateSite } from './generate-site.js';
 export type { GenerateSiteConfig } from './generate-site.js';
 export { buildEpub, DEFAULT_BOOK_CSS } from './epub.js';

package/dist/doc-system/site/library-bundle.d.ts

@@ -0,0 +1,26 @@
+export interface LibraryBundle {
+    /** Entry points relative to the project root, e.g. `['src/index.ts', 'src/core.ts']`. */
+    entries: string[];
+    /**
+     * Packages left as imports instead of bundled (each also matches its subpaths). Default:
+     * every `dependencies`, `peerDependencies` and `optionalDependencies` name in package.json.
+     */
+    externals?: string[];
+    /** tsconfig for the declaration pass (run with `--emitDeclarationOnly`). Default: the root one. */
+    tsconfig?: string;
+    /** `bun build --target`. Default `browser`. */
+    target?: 'browser' | 'node' | 'bun';
+}
+interface PackageJsonDeps {
+    dependencies?: Record<string, string>;
+    peerDependencies?: Record<string, string>;
+    optionalDependencies?: Record<string, string>;
+}
+/** The externals to use: the configured list, or every declared runtime dependency. */
+export declare function bundleExternals(bundle: LibraryBundle, pkg: PackageJsonDeps): string[];
+/** The `bun build` argv for the JavaScript half. */
+export declare function bundleBuildArgs(bundle: LibraryBundle, pkg: PackageJsonDeps, outdir: string): string[];
+/** The `tsc` argv for the declaration half. */
+export declare function bundleDeclarationArgs(bundle: LibraryBundle, outdir: string): string[];
+export declare function extensionlessImports(dir: string): string[];
+export {};

package/dist/doc-system/site/library-bundle.js

@@ -0,0 +1,100 @@
+/*
+The bundled library build (`SiteConfig.libraryBundle`, #169).
+
+`emitLibrary` / `libraryTsconfig` run a bare `tsc`, which copies each source file's import
+specifiers into the output unchanged. Written in bundler style (`export * from './model'`), that
+output is a `dist/` Node refuses: `ERR_MODULE_NOT_FOUND .../dist/model`. Bun resolves it, so
+nothing in a Bun build or test loop notices, and it ships. tosijs-3d, tosijs-3d-ensemble and
+tosijs-virta each grew their own guard for this, in three different shapes.
+
+This is the paved road instead: `bun build` bundles the entries with splitting (its output
+imports its own chunks WITH extensions, by construction), every declared dependency and peer
+stays an import rather than being bundled, and `tsc` emits declarations only. The result is
+then scanned for relative imports without an extension, and any hit fails the build — the
+guard the three repos wrote, done once.
+
+Every heavy step runs as a CHILD process (`bun build`, `tsc`): this code also runs inside the
+long-lived dev server, where Bun.build() leaks its native arena on every call.
+*/
+import { readdirSync, readFileSync, statSync } from 'fs';
+import * as path from 'path';
+/** The externals to use: the configured list, or every declared runtime dependency. */
+export function bundleExternals(bundle, pkg) {
+    const names = bundle.externals ?? [
+        ...Object.keys(pkg.dependencies ?? {}),
+        ...Object.keys(pkg.peerDependencies ?? {}),
+        ...Object.keys(pkg.optionalDependencies ?? {}),
+    ];
+    return [...new Set(names)].sort();
+}
+/** The `bun build` argv for the JavaScript half. */
+export function bundleBuildArgs(bundle, pkg, outdir) {
+    return [
+        'bun',
+        'build',
+        ...bundle.entries,
+        '--outdir',
+        outdir,
+        '--format',
+        'esm',
+        '--splitting',
+        '--target',
+        bundle.target ?? 'browser',
+        '--sourcemap=linked',
+        ...bundleExternals(bundle, pkg).flatMap((name) => [
+            '--external',
+            name,
+            '--external',
+            `${name}/*`,
+        ]),
+    ];
+}
+/** The `tsc` argv for the declaration half. */
+export function bundleDeclarationArgs(bundle, outdir) {
+    return [
+        'bun',
+        'tsc',
+        ...(bundle.tsconfig ? ['-p', bundle.tsconfig] : []),
+        '--declaration',
+        '--emitDeclarationOnly',
+        // a root tsconfig with `noEmit: true` would otherwise emit nothing at all
+        '--noEmit',
+        'false',
+        '--outDir',
+        outdir,
+    ];
+}
+const HAS_EXTENSION = /\.(?:m?js|cjs|json)$/;
+/*
+Real imports, from Bun's parser rather than a regex: a regex also matched specifiers quoted in
+COMMENTS — four false hits in tosijs-ui's own dist, one of them this file's own doc comment.
+One Transpiler for the process: each construction costs ~40KB that is never returned, and this
+runs inside the long-lived dev server (see CLAUDE.md, "Dev servers are the most dangerous thing").
+*/
+let transpiler;
+function importsOf(source) {
+    transpiler ??= new Bun.Transpiler({ loader: 'js' });
+    return transpiler
+        .scanImports(source)
+        .map((entry) => entry.path);
+}
+export function extensionlessImports(dir) {
+    const found = [];
+    const walk = (current) => {
+        for (const name of readdirSync(current)) {
+            const full = path.join(current, name);
+            if (statSync(full).isDirectory()) {
+                walk(full);
+            }
+            else if (/\.m?js$/.test(name)) {
+                for (const specifier of importsOf(readFileSync(full, 'utf8'))) {
+                    if (/^\.{1,2}\//.test(specifier) && !HAS_EXTENSION.test(specifier)) {
+                        found.push(`${path.relative(dir, full)}: ${specifier}`);
+                    }
+                }
+            }
+        }
+    };
+    walk(dir);
+    return found;
+}

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

@@ -28,6 +28,7 @@ export declare function shouldCleanDist(config: {
     emitLibrary?: boolean;
     libraryTsconfig?: string;
     libraryBuild?: unknown;
+    libraryBundle?: unknown;
 }): boolean;
 export declare function buildSite(config: SiteConfig, opts?: {
     skipAudit?: boolean;

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

@@ -16,11 +16,12 @@ import { namedBooks, partitionByBook, DEFAULT_BOOK } from '../book-target.js';
 import { listEpubVolumes, renderEpubDownloads } from './epub-volumes.js';
 import { buildSlugMap } from '../routing.js';
 import { computeAssetStamp, missingStampInputWarning } from './asset-stamp.js';
-import { existsSync, mkdirSync, unlinkSync } from 'fs';
+import { existsSync, mkdirSync, readFileSync, unlinkSync } from 'fs';
 import { tmpdir } from 'os';
 import { $, spawn } from 'bun';
 import { extractDocs } from './docs.js';
 import { relocateSourcemaps } from './sourcemap-relocate.js';
+import { bundleBuildArgs, bundleDeclarationArgs, extensionlessImports, } from './library-bundle.js';
 import { checkExamples, formatExampleProblems, } from './check-examples.js';
 import { ensureSections } from './sections.js';
 import { generateLlmsTxt } from './make-llms-txt.js';
@@ -348,7 +349,9 @@ export function shouldCleanDist(config) {
     // even alongside the other flags — the consumer's function is the authority.
     if (config.libraryBuild)
         return false;
-    return config.emitLibrary === true || Boolean(config.libraryTsconfig);
+    return (config.emitLibrary === true ||
+        Boolean(config.libraryTsconfig) ||
+        Boolean(config.libraryBundle));
 }
 /*
 Announce-once state for the "writes outside outputDir" warning.
@@ -714,8 +717,9 @@ export async function buildSite(config, opts = {}) {
                 directory and may legitimately emit a subset, which is exactly the reported case.
               - nothing configured — NOT cleaned. Nothing here owns it.
       
-            Incidental win: `emitLibrary` runs `tsc --incremental`, whose `.tsbuildinfo` lives in
-            `dist/`. Wiping it every run meant incremental compilation never once did anything.
+            `emitLibrary` used to run `tsc --incremental`, whose `.tsbuildinfo` lived in `dist/`; wiping
+            it every run meant incremental compilation never once did anything. It no longer runs
+            incrementally at all — see the tsc call below for why moving the cache is not the fix.
             */
             if (shouldCleanDist(config)) {
                 await $ `rm -rf ${DIST}`.text();
@@ -748,6 +752,36 @@ export async function buildSite(config, opts = {}) {
                     tsconfig: config.libraryTsconfig,
                 });
             }
+            else if (config.libraryBundle) {
+                // The bundled library build (#169): child processes only, never Bun.build() here.
+                const pkg = JSON.parse(readFileSync(path.resolve(PROJECT_ROOT, 'package.json'), 'utf8'));
+                for (const [what, argv] of [
+                    ['bun build', bundleBuildArgs(config.libraryBundle, pkg, DIST)],
+                    [
+                        'tsc --emitDeclarationOnly',
+                        bundleDeclarationArgs(config.libraryBundle, DIST),
+                    ],
+                ]) {
+                    const child = spawn([...argv], { stdout: 'pipe', stderr: 'pipe' });
+                    const output = await drainChild(child);
+                    if ((await child.exited) !== 0) {
+                        console.error(output);
+                        console.error(`❌ libraryBundle: ${what} FAILED — dist/ is incomplete. Build marked failed.` +
+                            (/Script not found "tsc"/.test(output)
+                                ? ' TypeScript is not installed in this project: `bun add -d typescript`.'
+                                : ''));
+                        libraryBuildFailed = true;
+                        break;
+                    }
+                }
+                if (!libraryBuildFailed) {
+                    const bad = extensionlessImports(DIST);
+                    if (bad.length) {
+                        console.error(`❌ libraryBundle: dist/ has relative imports without a file extension, which Node cannot load:\n  ${bad.join('\n  ')}`);
+                        libraryBuildFailed = true;
+                    }
+                }
+            }
             else if (config.libraryTsconfig) {
                 // Consumer-controlled library build (handles root noEmit, removeComments,
                 // outDir, etc.). tsc output is left visible so the errors are readable.
@@ -759,13 +793,38 @@ export async function buildSite(config, opts = {}) {
                 }
             }
             else if (config.emitLibrary) {
-                const r = await $ `bun tsc --declaration --incremental --outDir dist`.nothrow();
+                /*
+                NOT --incremental. Its .tsbuildinfo lived in dist/, so it shipped in every adopter's
+                tarball (and ours), and it differs between a first and a second build — which the publish
+                workflow's "shipped files reproduce" check rightly rejects. Moving the cache elsewhere is
+                WORSE: dist/ is wiped every build (above), and tsc trusts the cache, sees nothing changed,
+                and emits nothing — measured, the second build deleted 883 files from dist/. Since dist/
+                is always clean, incremental compilation could never help here anyway.
+                */
+                const r = await $ `bun tsc --declaration --outDir dist`.nothrow();
                 if (r.exitCode !== 0) {
                     console.error(`❌ tsc --declaration FAILED (exit ${r.exitCode}) — emitted dist/*.d.ts may ` +
                         `be stale or contain type errors. Build marked failed.`);
                     libraryBuildFailed = true;
                 }
             }
+            /*
+            A bare tsc copies bundler-style specifiers into dist/ unchanged, and Node cannot load the
+            result (#169). Say so loudly on those two paths. Not a failure: it would break working
+            builds for consumers who only ever bundle, on a patch upgrade. libraryBundle fails on it.
+            */
+            if (!libraryBuildFailed &&
+                !config.libraryBuild &&
+                !config.libraryBundle &&
+                (config.libraryTsconfig || config.emitLibrary) &&
+                existsSync(DIST)) {
+                const bad = extensionlessImports(DIST);
+                if (bad.length) {
+                    console.warn(`⚠️  dist/ has ${bad.length} relative import(s) without a file extension — Node rejects them ` +
+                        `(ERR_MODULE_NOT_FOUND), even though Bun and bundlers resolve them. Use \`libraryBundle\` ` +
+                        `instead of ${config.libraryTsconfig ? 'libraryTsconfig' : 'emitLibrary'} (tosijs-ui#169). First: ${bad[0]}`);
+                }
+            }
             // The hydration bundle. If bundleEntry is set we build it (IIFE), else pages
             // load config.scriptUrl (default /iife.js) — a prebuilt/CDN bundle the
             // consumer supplies (e.g. via staticDirs or an absolute URL).

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

@@ -1,3 +1,4 @@
+import type { LibraryBundle } from './library-bundle.js';
 import type { ProjectLinks, LinkItem } from '../../doc-browser.js';
 import type { DocSystemTheme } from '../doc-system-styles.js';
 import type { Doc } from './docs.js';
@@ -192,10 +193,23 @@ export interface SiteConfig {
      */
     prebuild?: () => void | Promise<void>;
     /**
-     * Also build the library: `tsc --declaration --incremental --outDir dist`
-     * (ESM + types). Default false. Repos whose single build publishes BOTH an
-     * npm package and its doc site (the tosijs-* libs) set this true; a pure docs
-     * site omits it. Ignored when `libraryTsconfig` is set.
+     * Build the library as a BUNDLE — the recommended library build (#169). `bun build` bundles
+     * `entries` with splitting into `dist/` (declared dependencies and peers stay imports), then
+     * `tsc` emits declarations only. The output is checked for relative imports without a file
+     * extension, which Node cannot load, and the build fails on any. Owns `dist/` (cleaned each
+     * build). Takes precedence over `libraryTsconfig` / `emitLibrary`; a `libraryBuild`
+     * function takes precedence over it.
+     *
+     * ```ts
+     * libraryBundle: { entries: ['src/index.ts', 'src/core.ts'] }
+     * ```
+     */
+    libraryBundle?: LibraryBundle;
+    /**
+     * Also build the library: `tsc --declaration --outDir dist` (ESM + types). Default false.
+     * **Prefer `libraryBundle`:** a bare tsc copies bundler-style specifiers (`from './model'`)
+     * into `dist/` unchanged, and Node cannot load that; the build warns when it happens.
+     * Ignored when `libraryTsconfig` is set.
      */
     emitLibrary?: boolean;
     /**