mappel 0.2.0 → 0.4.0

package/README.md

@@ -8,8 +8,11 @@ It resolves each specifier through the package's own exports map — nested cond
 
 A repo declares named layers in importmap.config.mjs, and a layer can exclude what another already resolves, so a page loads two maps and neither repeats the other. Layers can also drop a whole scope by prefix. A css specifier maps to a `.js` sibling that adds the file as a link, because a browser cannot import a stylesheet as a module. Pass `--css link` to get the specifier mapped away and the link tags printed instead.
 
+Every map is written twice: `name.json` and `name.js`, which installs the map when a page loads it with a script tag. The script must come before the first module script in the page, or it is ignored. Inline maps are registered when their element is inserted, and multiple maps in one page require Chromium 133 or newer.
+
 ```sh
 mappel                                  # every layer, to the out in the config
+mappel --no-js                          # the json only, without the script siblings
 mappel --layer min                      # one layer, to stdout
 mappel --layer min --html               # ready to paste into a page
 mappel --layer min --dist-tag alpha     # follow a channel instead of pinning
@@ -26,6 +29,7 @@ export default {
   out: 'packages/cdn/dist',        // relative to this file
   workspaces: ['packages'],
   split: { components: 'components' },   // a file per package in that layer
+  js: false,                             // skip the script siblings
   layers: {
     base: { packages: ['@scope/core', '@scope/dom'] },
     extra: { packages: ['@scope/extra'], excludes: ['base'] },

package/bin/mappel.mjs

@@ -5,14 +5,16 @@
 //   mappel --layer min              one layer, to stdout
 //   mappel --config packages/cdn/mappel.config.mjs --out dist
 //   mappel --layer min --dist-tag alpha --html
+//   mappel --no-js                  maps only, without their script siblings
 //
 // With no arguments it finds mappel.config.mjs by walking up from the current
-// directory, so a package's build script is just `mappel`.
+// directory, so a package's build script is just `mappel`. Every map is written
+// twice: `<name>.json` to read, and `<name>.js` to load from a page.
 
 import { existsSync, writeFileSync, mkdirSync } from 'node:fs';
 import { dirname, join, resolve as resolvePath } from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { buildLayer, writeAll, subpathsOf } from '../src/index.mjs';
+import { buildLayer, writeAll, writeMap, subpathsOf } from '../src/index.mjs';
 
 const argv = process.argv.slice(2);
 const flag = (name, fallback) => {
@@ -71,9 +73,12 @@ const options = {
 const layerName = flag('layer', null);
 const splitInto = flag('split', null);
 
+// Each map gets a script sibling that installs it. `--no-js` writes only JSON.
+const settings = { ...config, js: has('no-js') ? false : has('js') ? true : config.js };
+
 if (!layerName && !splitInto) {
   const out = resolvePath(flag('out', config.out ? join(base, config.out) : join(base, 'dist')));
-  const written = writeAll(config, { ...options, out });
+  const written = writeAll(settings, { ...options, out });
   for (const { file, entries, split } of written) {
     process.stderr.write(`  ${file} — ${entries} ${split ? 'files' : 'entries'}\n`);
   }
@@ -96,7 +101,7 @@ if (splitInto) {
       options,
     );
     if (Object.keys(one.imports).length === 0) continue;
-    writeFileSync(join(dir, name.split('/').pop() + '.json'), JSON.stringify({ imports: one.imports }, null, 2) + '\n');
+    writeMap(join(dir, name.split('/').pop() + '.json'), one.imports, settings);
     written += 1;
   }
   process.stderr.write(`wrote ${written} maps to ${dir}\n`);
@@ -108,7 +113,8 @@ const json = JSON.stringify({ imports }, null, 2);
 const out = flag('out', null);
 
 if (out) {
-  writeFileSync(out, json + '\n');
+  if (out.endsWith('.json')) writeMap(out, imports, settings);
+  else writeFileSync(out, json + '\n');
   process.stderr.write(`wrote ${out} — ${Object.keys(imports).length} entries\n`);
 } else if (has('html')) {
   const links =

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mappel",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "license": "MIT",
   "description": "generate the import map a page needs from a workspace: resolves every transitive subpath through each package exports map, in layers that compose",
   "type": "module",

package/src/index.mjs

@@ -49,6 +49,13 @@ export function collect(specifiers, options) {
     return `${cdn}/${name}${version}/${clean}`;
   };
 
+  // A stylesheet as a url a browser can fetch, mapped to its loader sibling: a browser cannot
+  // import a stylesheet as a module, the loader adds it as a <link>.
+  const addStylesheet = (key, pkg, dir, file) => {
+    stylesheets.add(urlFor(pkg, dir, file));
+    imports[key] = css === 'loader' ? urlFor(pkg, dir, file + '.js') : 'data:text/javascript,';
+  };
+
   const add = (spec) => {
     if (visited.has(spec)) return;
     visited.add(spec);
@@ -61,10 +68,8 @@ export function collect(specifiers, options) {
     if (!file) return void unresolved.add(spec);
 
     if (spec.endsWith('.css')) {
-      stylesheets.add(urlFor(pkg, dir, file));
-      // A browser cannot import a stylesheet as a module. The loader sibling adds
-      // it as a <link>, so importing a component still brings its styles.
-      imports[spec] = css === 'loader' ? urlFor(pkg, dir, file + '.js') : 'data:text/javascript,';
+      // Importing a component still brings its styles.
+      addStylesheet(spec, pkg, dir, file);
       return;
     }
 
@@ -78,7 +83,12 @@ export function collect(specifiers, options) {
       if (seen.has(current) || !existsSync(current)) continue;
       seen.add(current);
       for (const nested of scanImports(current)) {
-        if (nested.startsWith('.')) {
+        if (nested.startsWith('.') && nested.endsWith('.css')) {
+          // A module's own stylesheet (`import './button.css'`). The browser resolves it to a
+          // url before it reads the map, so the url is the key.
+          const file = './' + relative(dir, normalize(join(dirname(current), nested))).split('\\').join('/');
+          addStylesheet(urlFor(pkg, dir, file), pkg, dir, file);
+        } else if (nested.startsWith('.')) {
           const next = normalize(join(dirname(current), nested));
           stack.push(existsSync(next) ? next : next + '.js');
         } else if (!nested.startsWith('node:')) {
@@ -130,6 +140,32 @@ function helpers(options) {
 
 export { subpathsOf, packageDir, resolveExport };
 
+/**
+ * The script sibling of a map. A page that cannot write JSON into its own
+ * markup — a docs site, a playground, anything served as a template — gets the
+ * map by loading one classic script instead.
+ *
+ * An inline map is registered when the element is inserted, so a second file
+ * cannot merge into the first one's element and each installs its own. Several
+ * maps in one page need Chromium 133 or newer; the combined file is the way to
+ * stay on one.
+ */
+function installer(imports) {
+  const map = JSON.stringify(JSON.stringify({ imports }));
+  return `(function(){var d=document,w=function(m){if(typeof console!=='undefined')console.warn('[mappel] '+m)};
+if(d.querySelector('script[type="module"]'))w('the import map is being added after a module script and will not be used — load this file first');
+var s=d.createElement('script');s.type='importmap';s.setAttribute('data-mappel','');s.textContent=${map};
+s.addEventListener('error',function(){w('the browser rejected this import map — a page with several maps needs Chromium 133+, so use the combined map instead')});
+(d.head||d.documentElement).appendChild(s);
+(self.__mappel||(self.__mappel=[])).push(JSON.parse(s.textContent))})();
+`;
+}
+
+export function writeMap(file, imports, config = {}) {
+  writeFileSync(file, JSON.stringify({ imports }, null, 2) + '\n');
+  if (config.js !== false) writeFileSync(file.replace(/\.json$/, '.js'), installer(imports));
+}
+
 /**
  * Write every layer a config declares, plus any per-item split it asks for.
  * This is what `mappel` does with no arguments: the config says where the
@@ -143,7 +179,7 @@ export function writeAll(config, options) {
   for (const name of Object.keys(config.layers)) {
     const { imports } = buildLayer(name, config, options);
     const file = join(out, `${name}.json`);
-    writeFileSync(file, JSON.stringify({ imports }, null, 2) + '\n');
+    writeMap(file, imports, config);
     written.push({ file, entries: Object.keys(imports).length });
   }
 
@@ -163,14 +199,7 @@ export function writeAll(config, options) {
       Object.assign(imports, buildLayer(name, config, options).imports);
     }
     const file = join(out, `${combined}.json`);
-    writeFileSync(
-      file,
-      JSON.stringify(
-        { imports: Object.fromEntries(Object.entries(imports).sort(([a], [b]) => a.localeCompare(b))) },
-        null,
-        2,
-      ) + '\n',
-    );
+    writeMap(file, sorted(imports), config);
     written.push({ file, entries: Object.keys(imports).length });
   }
 
@@ -193,10 +222,7 @@ export function writeAll(config, options) {
         options,
       );
       if (Object.keys(one.imports).length === 0) continue;
-      writeFileSync(
-        join(dir, name.split('/').pop() + '.json'),
-        JSON.stringify({ imports: one.imports }, null, 2) + '\n',
-      );
+      writeMap(join(dir, name.split('/').pop() + '.json'), one.imports, config);
       count += 1;
     }
     written.push({ file: `${dir}/*.json`, entries: count, split: true });