tosijs-ui 1.6.1 → 1.6.3

package/bin/make-icon-data.js

@@ -0,0 +1,327 @@
+#!/usr/bin/env bun
+/*#
+# make-icon-data
+
+<!--{ "pin": "bottom" }-->
+
+Ingests SVG files from icon directories and generates an icon-data module
+(TypeScript or JavaScript). This is the build tool behind the `icons` system.
+
+## Usage
+
+    bun run bin/make-icon-data.js [options]
+
+### Options
+
+- `--input <dir1,dir2,...>` — directories to scan (default: `./icons`)
+- `--output <path>` — output file (default: `./src/icon-data.ts`)
+- `--optimize <true|false>` — round coordinates based on viewBox size (default: true)
+
+### Examples
+
+    bun run bin/make-icon-data.js
+    bun run bin/make-icon-data.js --input ./my-icons --output ./dist/icons.js
+    bun run bin/make-icon-data.js --optimize false
+
+## Directory conventions
+
+### Style classes
+
+Folder names control CSS classes on the generated SVGs:
+
+- `color/` — icons with baked-in colors (class `color`, fill/stroke preserved)
+- `stroked/` — stroke-only icons (class `stroked`, fill styles removed)
+- `filled/` — fill-only icons (class `filled`, stroke styles removed)
+
+### Directional folders
+
+Place icons in specially named folders to auto-generate directional
+redirects, eliminating redundant SVG files:
+
+- `right-left/` — base icon points right; generates a flipped left variant
+- `up-down/` — base icon points up; generates a flipped down variant
+- `up-down-right-left/` — base icon points right; generates down (90°),
+  left (180°), and up (270°) rotation variants
+
+For example, `chevron-right.svg` in an `up-down-right-left/` folder produces
+`chevronRight` (SVG) plus `chevronDown`, `chevronLeft`, `chevronUp` (redirects).
+
+### Comma-separated names
+
+For icons where the directional variant has a different name (not just a
+direction swap), use commas in the filename:
+
+    skip-forward,skip-back.svg    → skipForward (SVG) + skipBack (redirect)
+    refresh-cw,refresh-ccw.svg    → refreshCw (SVG) + refreshCcw (redirect)
+
+The first name is the base, additional names are mapped to the folder's
+variant suffixes in order.
+
+## SVG processing
+
+The tool automatically:
+- Strips XML declarations, namespaces, IDs, and comments
+- Removes redundant attributes (default fills, strokes)
+- Collapses whitespace
+- Rounds coordinates based on viewBox size (larger viewBox = fewer decimals)
+- Converts filenames to camelCase (`arrow-right.svg` → `arrowRight`)
+*/
+
+/*{ "parent": "Appendices" }*/
+
+import fs from 'fs'
+import path from 'path'
+
+// Default values for options
+const defaultOptions = {
+  input: './icons',
+  output: './src/icon-data.ts',
+  optimize: true, // Optimize coordinate precision based on viewBox size
+}
+const flags = Object.keys(defaultOptions)
+
+// Parse command-line arguments
+const args = process.argv.slice(2)
+const parsedArgs = {}
+for (let i = 0; i < args.length; i++) {
+  const arg = args[i]
+  if (arg.startsWith('--')) {
+    const key = arg.substring(2)
+    const value = args[i + 1]
+    if (value && !value.startsWith('--')) {
+      parsedArgs[key] = value
+      i++ // Skip the value in the next iteration
+    } else {
+      parsedArgs[key] = true // Handle boolean flags (though not used for these options currently)
+    }
+  }
+}
+
+// Combine default options with parsed arguments
+const options = { ...defaultOptions }
+for (const flag of flags) {
+  if (parsedArgs[flag] !== undefined) {
+    options[flag] = parsedArgs[flag]
+  }
+}
+
+// Destructure options for easier use
+const { input: iconDirectories, output: outputFilePath, optimize } = options
+const isTypescript = outputFilePath.endsWith('.ts')
+const shouldOptimize = optimize === true || optimize === 'true'
+
+// Calculate appropriate decimal precision based on viewBox size
+// Larger viewBox = fewer decimal places needed
+function getPrecisionForViewBox(viewBoxSize) {
+  if (viewBoxSize >= 512) return 0
+  if (viewBoxSize >= 64) return 1
+  return 2
+}
+
+// Round numbers in SVG content based on viewBox-appropriate precision
+function optimizeCoordinates(svgSource, precision) {
+  return svgSource.replace(/\d+\.\d+/g, (number) => {
+    const rounded = Number(number).toFixed(precision)
+    // Remove trailing zeros and unnecessary decimal point
+    return parseFloat(rounded).toString()
+  })
+}
+
+// Extract viewBox size from SVG
+function getViewBoxSize(svgSource) {
+  const match = svgSource.match(/viewBox="([^"]+)"/)
+  if (match) {
+    const parts = match[1].split(/\s+/)
+    if (parts.length >= 4) {
+      const width = parseFloat(parts[2])
+      const height = parseFloat(parts[3])
+      return Math.max(width, height)
+    }
+  }
+  return 24 // Default assumption
+}
+
+const typeDeclaration = isTypescript
+  ? 'export interface IconData { [key: string]: string }'
+  : '' // No type declaration for JS output
+
+const iconData = {}
+const iconRedirects = {}
+
+// Directional folder conventions:
+// right-left: base has "Right", generate "Left" as flip
+// up-down: base has "Up", generate "Down" as flip
+// up-down-right-left: base has "Right", generate Down/Left/Up via rotation
+const DIRECTION_FOLDERS = {
+  'right-left': {
+    base: 'Right',
+    variants: { Left: '0f' },
+  },
+  'up-down': {
+    base: 'Up',
+    variants: { Down: '1f' },
+  },
+  'up-down-right-left': {
+    base: 'Right',
+    variants: {
+      Down: '90r',
+      Left: '180r',
+      Up: '270r',
+    },
+  },
+}
+
+function getDirectionConfig(dir) {
+  const dirName = path.basename(dir)
+  return DIRECTION_FOLDERS[dirName] || null
+}
+
+function generateDirectionalRedirects(name, dirConfig) {
+  // Find the base direction word in the camelCase name
+  const baseDir = dirConfig.base
+  if (!name.includes(baseDir)) return
+
+  for (const [targetDir, suffix] of Object.entries(dirConfig.variants)) {
+    const redirectName = name.replace(baseDir, targetDir)
+    if (redirectName !== name) {
+      iconRedirects[redirectName] = name + suffix
+    }
+  }
+}
+
+function findIcons(dirs, ignore = []) {
+  function traverseDirectory(dir) {
+    if (!fs.existsSync(dir)) {
+      console.warn(`Warning: Directory not found: ${dir}. Skipping.`)
+      return
+    }
+    // Sort so output is reproducible across machines — readdirSync returns
+    // entries in filesystem order, which differs by OS and otherwise produces
+    // spurious reordering diffs in the generated icon-data on every build.
+    const files = fs.readdirSync(dir).sort()
+    if (ignore.includes(dir)) {
+      return
+    }
+
+    files.forEach((file) => {
+      const filePath = path.join(dir, file)
+      const stats = fs.statSync(filePath)
+
+      if (stats.isDirectory()) {
+        traverseDirectory(filePath)
+      } else if (path.extname(file) === '.svg') {
+        const content = fs.readFileSync(filePath, 'utf8')
+        const rawName = file.split('.')[0]
+        const names = rawName.split(',').map((n) =>
+          n.trim().replace(/-([a-z0-9])/g, (_, char) => char.toLocaleUpperCase())
+        )
+        const name = names[0]
+        let svgSource = content
+          .replace(/(<\?xml.*?>|<!DOCTYPE.*?>)\s?/g, '')
+          .replace(/<svg.*?>/, (a) =>
+            a.replace(
+              /\s(x|y|width|height|class|xmlns|xmlns:xlink)="[^"]+"/g,
+              ''
+            )
+          )
+          .replace(
+            /\s?\b(opacity:1;|fill="#000000"|fill="#000"|fill="none"|class="[^"]+"|stroke="currentColor"|stroke="#000000"|stroke-linejoin="[^"]+"|stroke-width="[^"]+"|(stroke-)?stroke-linecap="[^"]+")/g,
+            ''
+          )
+          .replace(/stroke-stroke/g, 'stroke')
+          .replace(/fill-fill/g, 'fill')
+          .replace(/\s+/g, ' ')
+          .replace(/>\s+</g, '><')
+          .replace(/\s(id)="[^"]+"/g, '')
+          .replace(/<!--.*?-->/g, '')
+
+        // Optimize coordinate precision based on viewBox size
+        if (shouldOptimize) {
+          const viewBoxSize = getViewBoxSize(svgSource)
+          const precision = getPrecisionForViewBox(viewBoxSize)
+          svgSource = optimizeCoordinates(svgSource, precision)
+        }
+        const classes = []
+        if (dir.includes('color')) {
+          classes.push('color')
+        } else {
+          // If not a color icon, remove fill/stroke styles
+          svgSource = svgSource.replace(/(fill|stroke)(-\w+)?:[^;]+;?/g, '')
+        }
+        if (dir.includes('stroked')) {
+          classes.push('stroked')
+          svgSource = svgSource.replace(/(fill)(-\w+)?:[^;]+;?/g, '')
+        }
+        if (dir.includes('filled')) {
+          classes.push('filled')
+          svgSource = svgSource.replace(/(stroke)(-\w+)?:[^;]+;?/g, '')
+        }
+        if (classes.length) {
+          svgSource = svgSource.replace(
+            /^<svg/,
+            `<svg class="${classes.join(' ')}"`
+          )
+        }
+        iconData[name] = svgSource
+
+        // Comma-separated names: skip-forward,skip-back.svg
+        // First name is the base, subsequent names are redirects using
+        // the folder's convention (0f for right-left, etc.)
+        const dirConfig = getDirectionConfig(dir)
+        if (names.length > 1 && dirConfig) {
+          const suffixes = Object.values(dirConfig.variants)
+          for (let n = 1; n < names.length && n - 1 < suffixes.length; n++) {
+            iconRedirects[names[n]] = name + suffixes[n - 1]
+          }
+        }
+
+        // Generate directional redirects based on folder convention
+        if (dirConfig) {
+          generateDirectionalRedirects(name, dirConfig)
+        }
+      }
+    })
+  }
+
+  dirs.forEach((dir) => {
+    traverseDirectory(dir)
+  })
+}
+
+findIcons(iconDirectories.split(','))
+
+// Manual redirects for icons that don't fit folder conventions
+const manualRedirects = {
+  arrowDownRight: 'arrowUpRight90r',
+  arrowDownLeft: 'arrowUpRight180r',
+  arrowUpLeft: 'arrowUpRight270r',
+}
+Object.assign(iconRedirects, manualRedirects)
+
+// Merge redirects — only add if the target name doesn't already have SVG data
+let redirectCount = 0
+for (const [name, redirect] of Object.entries(iconRedirects)) {
+  if (!iconData[name]) {
+    iconData[name] = redirect
+    redirectCount++
+  }
+}
+if (redirectCount > 0) {
+  console.log(`Generated ${redirectCount} directional redirects`)
+}
+
+// Ensure the output directory exists
+const outputDir = path.dirname(outputFilePath)
+if (!fs.existsSync(outputDir)) {
+  fs.mkdirSync(outputDir, { recursive: true })
+}
+
+const source =
+  (typeDeclaration ? typeDeclaration + '\n\n' : '') +
+  'export default ' +
+  JSON.stringify(iconData, null, 2).replace(/"(\w+)":/g, '$1:') +
+  (isTypescript ? ' as IconData\n' : '\n')
+
+fs.writeFileSync(outputFilePath, source, 'utf8')
+
+console.log(`Successfully generated icon data to: ${outputFilePath}`)

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

@@ -1 +1,11 @@
-export declare function generateLlmsTxt(outputPath: string): void;
+export interface LlmsTxtMeta {
+    name?: string;
+    description?: string;
+    /** site origin, used for the Docs link */
+    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;

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

@@ -33,8 +33,8 @@ function extractDescription(text) {
     }
     return '';
 }
-export function generateLlmsTxt(outputPath) {
-    const config = JSON.parse(fs.readFileSync('package.json', 'utf8'));
+export function generateLlmsTxt(outputPath, meta = {}) {
+    const pkg = JSON.parse(fs.readFileSync('package.json', 'utf8'));
     const docs = [];
     const files = fs.readdirSync(SRC).filter((f) => f.endsWith('.ts'));
     for (const file of files) {
@@ -59,17 +59,23 @@ export function generateLlmsTxt(outputPath) {
         });
     }
     docs.sort((a, b) => a.title.localeCompare(b.title));
+    const name = meta.name ?? pkg.name;
+    const description = meta.description ?? pkg.description;
+    const links = [];
+    if (meta.baseUrl)
+        links.push(`- Docs: ${meta.baseUrl}`);
+    if (meta.projectLinks?.github)
+        links.push(`- Source: ${meta.projectLinks.github}`);
+    const npm = meta.projectLinks?.npm ?? `https://www.npmjs.com/package/${pkg.name}`;
+    if (npm)
+        links.push(`- npm: ${npm}`);
     const lines = [
-        `# ${config.name} v${config.version}`,
+        `# ${name} v${pkg.version}`,
         '',
-        config.description,
+        description,
+        ...(meta.tagline ? ['', meta.tagline] : []),
         '',
-        'Web component library built on tosijs. Components augment HTML5/CSS3',
-        'rather than replacing native elements.',
-        '',
-        '- Docs: https://ui.tosijs.net',
-        '- Source: https://github.com/tonioloewald/xinjs-ui',
-        '- npm: https://www.npmjs.com/package/tosijs-ui',
+        ...links,
         '',
         '## Documentation',
         '',

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

@@ -57,7 +57,17 @@ export async function buildSite(config) {
     console.time('build');
     // Optionally also build the library (ESM + type declarations) — for repos
     // whose single build publishes both an npm package and its doc site.
-    if (config.emitLibrary) {
+    if (config.libraryTsconfig) {
+        // Consumer-controlled library build (handles root noEmit, removeComments,
+        // outDir, etc.).
+        try {
+            await $ `bun tsc -p ${config.libraryTsconfig}`;
+        }
+        catch {
+            console.log('library (tsc -p) build finished');
+        }
+    }
+    else if (config.emitLibrary) {
         try {
             await $ `bun tsc --declaration --incremental --outDir dist`;
         }
@@ -70,6 +80,13 @@ 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,
@@ -87,11 +104,32 @@ export async function buildSite(config) {
         }
         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
+        // (a branch the bundler couldn't eliminate) the IIFE will SyntaxError.
+        if (Buffer.from(bundleFile).toString('utf8').includes('import.meta')) {
+            console.warn(`⚠️  ${scriptName} contains \`import.meta\`, which is a SyntaxError in a classic <script>.\n` +
+                `    A dependency referenced it in a branch the bundler couldn't drop — mark that dep external\n` +
+                `    (+ importmap) or choose a browser-only entry point.`);
+        }
         const bundleGzip = gzipSync(Buffer.from(bundleFile));
         console.log(`${scriptName}: ${(bundleFile.byteLength / 1024).toFixed(1)}kb (${(bundleGzip.length / 1024).toFixed(1)}kb gzip)`);
     }
-    if (config.llmsTxt ?? true) {
-        generateLlmsTxt('llms.txt');
+    if (config.llmsTxt !== false) {
+        if (typeof config.llmsTxt === 'function') {
+            const corpus = JSON.parse(await Bun.file('demo/docs.json').text());
+            await Bun.write('llms.txt', config.llmsTxt(corpus));
+        }
+        else {
+            generateLlmsTxt('llms.txt', {
+                name: config.name,
+                description: config.description,
+                baseUrl: config.baseUrl,
+                projectLinks: config.projectLinks,
+            });
+        }
+        // Also place it at the served web root so {baseUrl}/llms.txt resolves (the
+        // root copy stays for the npm package's `files`).
+        await $ `cp llms.txt ${PUBLIC}/llms.txt`.text();
     }
     // Generate the static, pre-rendered doc site (one /slug/index.html per doc).
     // Runs after the static-asset copy so the generated index.html (README) wins,

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

@@ -1,5 +1,6 @@
 import type { ProjectLinks, LinkItem } from '../../doc-browser';
 import type { DocSystemTheme } from '../doc-system-styles';
+import type { Doc } from './docs';
 export type SiteHost = 'github-pages' | 'firebase' | 'static';
 export interface SiteConfig {
     /** project / brand name — header, <title> suffix, og:site_name */
@@ -82,13 +83,26 @@ export interface SiteConfig {
      */
     prebuild?: () => void | Promise<void>;
     /**
-     * Also build the library: `tsc --declaration --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.
+     * 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.
      */
     emitLibrary?: boolean;
-    /** emit llms.txt agent-discoverability index. Default true. */
-    llmsTxt?: boolean;
+    /**
+     * Path to a tsconfig for the library build, run as `tsc -p <path>` instead of
+     * the fixed `emitLibrary` command. Use this when the root tsconfig has
+     * `noEmit: true`, or to control `removeComments`/`outDir`/`declaration`
+     * yourself (e.g. keep doc comments in the published JS for AI readers).
+     */
+    libraryTsconfig?: string;
+    /**
+     * Emit llms.txt agent-discoverability index. Default true (uses `name` /
+     * `description` / `baseUrl` / `projectLinks`). Set false to skip, or pass a
+     * function for a fully custom index — it receives the doc corpus and returns
+     * the file contents.
+     */
+    llmsTxt?: boolean | ((docs: Doc[]) => string);
     /** served web-root output dir, default 'docs' */
     outputDir?: string;
     /** dev-server port, default 8787 */