@fusion.dev/helix-icons 0.205.2 → 0.207.0

package/README.md

@@ -53,9 +53,9 @@ import { peak } from './icons'
 <helix-icon icon={peak} />
 ```
 
-Any set, not only ours. A subset of Phosphor larger than the 120 here is the
-same command against the package it resolves from, and `--suffix` is for a set
-that spells a weight into the file name:
+The command reads any set of SVG files. More of Phosphor than this package
+carries is the same command against the package it resolves from, and
+`--suffix` is for a set that spells a weight into the file name:
 
 ```sh
 npx helix-icons build \
@@ -67,6 +67,40 @@ npx helix-icons build \
 so nothing can drop any of it: ask for it when you want names in markup, and
 leave it off when you import.
 
+An `--out` path ending in `.js` or `.mjs` gets JavaScript, with the type in a
+JSDoc comment. Any other path gets TypeScript.
+
+### From a script
+
+The command is also a module, `@fusion.dev/helix-icons/build`, for a build
+script of your own:
+
+```js
+import { build } from '@fusion.dev/helix-icons/build'
+
+const written = build({
+  out: 'src/icons.ts',
+  sources: [{ directory: 'brand-icons' }],
+})
+```
+
+`build` writes the module and returns how many icons it holds. Its options are
+the command's flags:
+
+- `sources`: where the SVG files are, searched in order, each as
+  `{ directory, suffix }`;
+- `names`: the icons to build, and every icon in the sources when left out;
+- `out`: where to write the module;
+- `index`: whether to also write the record `<helix-icon name>` reads;
+- `typeImport`: where the module imports `HelixIcon` from.
+
+It throws where the command fails:
+
+- a source that is not a directory;
+- a name with no file, or with a file in two sources;
+- sources with no SVG files, when `names` is left out;
+- an `out` path ending in `.cjs`.
+
 Phosphor is MIT and its notice travels in `LICENSE` beside ours.
 
 [Documentation](https://fusion.dev/helix)

package/dist/build.d.ts

@@ -40,7 +40,13 @@ export interface BuildOptions {
      * pointing at their own folder of drawings usually means.
      */
     names?: string[];
-    /** Where to write the module. */
+    /**
+     * Where to write the module, creating its directory where there is none.
+     *
+     * A `.js` or `.mjs` path gets JavaScript, with the type in a JSDoc comment.
+     * Any other gets TypeScript, and a `.cjs` path is refused, the module being
+     * an ES module.
+     */
     out: string;
     sources: IconSource[];
     /**
@@ -59,6 +65,8 @@ export interface BuildOptions {
 /**
  * Writes the module, and says how many glyphs are in it.
  *
- * @throws where a name resolves to no file, or to more than one.
+ * @throws where a source is not a directory, where a name resolves to no file
+ * or to more than one, where the sources hold no glyph and no names were given,
+ * and where `out` is a `.cjs` file.
  */
 export declare function build(options: BuildOptions): number;

package/dist/build.js

@@ -1,5 +1,5 @@
-import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
 import { optimize } from 'svgo';
 const SVGO = {
     multipass: true,
@@ -9,9 +9,6 @@ const camel = (slug) => slug.replace(/-([a-z0-9])/g, (_, char) => char.toUpperCa
 const namesIn = (sources) => {
     const found = new Set();
     for (const { directory, suffix = '' } of sources) {
-        if (!existsSync(directory)) {
-            continue;
-        }
         for (const file of readdirSync(directory)) {
             if (!file.endsWith('.svg')) {
                 continue;
@@ -51,23 +48,35 @@ const drawn = (slug, sources) => {
 };
 export function build(options) {
     const { index = false, out, sources, typeImport = '@fusion.dev/helix-icons' } = options;
+    if (out.endsWith('.cjs')) {
+        throw new Error(`icons: ${out} is a CommonJS file, and the module is an ES module. Name it .js, .mjs, or .ts.`);
+    }
+    for (const { directory } of sources) {
+        if (!existsSync(directory) || !statSync(directory).isDirectory()) {
+            throw new Error(`icons: no directory at ${directory}`);
+        }
+    }
     const names = options.names ?? namesIn(sources);
+    if (options.names === undefined && names.length === 0) {
+        const where = sources
+            .map(({ directory, suffix = '' }) => suffix === '' ? directory : `${directory} (named *${suffix}.svg)`)
+            .join(', ');
+        throw new Error(`icons: no SVG files in ${where}`);
+    }
     const entries = names.map((slug) => drawn(slug, sources));
+    const script = /\.m?js$/.test(out);
+    const icon = script ? `import('${typeImport}').HelixIcon` : 'HelixIcon';
+    const declared = (name, type) => script ? `/** @type {${type}} */\nexport const ${name} =` : `export const ${name}: ${type} =`;
     const body = entries
-        .map(({ camel: name, content, slug, viewBox }) => `export const ${name}: HelixIcon = {\n  content: '${content.replace(/'/g, "\\'")}',\n  name: '${slug}',\n  viewBox: '${viewBox}',\n}`)
+        .map(({ camel: name, content, slug, viewBox }) => `${declared(name, icon)} {\n  content: '${content.replace(/'/g, "\\'")}',\n  name: '${slug}',\n  viewBox: '${viewBox}',\n}`)
         .join('\n\n');
     const record = entries.map(({ camel: name, slug }) => `  '${slug}': ${name},`).join('\n');
-    writeFileSync(out, `// Generated by @fusion.dev/helix-icons. Do not edit.
-import type { HelixIcon } from '${typeImport}'
-
-${body}
-${index
-        ? `
-/** Every icon, by name, for lookup from a \`name\` attribute. */
-export const icons: Record<string, HelixIcon> = {
-${record}
-}
-`
-        : ''}`);
+    const lookup = 'Every icon, by name, for lookup from a `name` attribute.';
+    const indexed = script
+        ? `/**\n * ${lookup}\n *\n * @type {Record<string, ${icon}>}\n */\nexport const icons =`
+        : `/** ${lookup} */\nexport const icons: Record<string, HelixIcon> =`;
+    const head = script ? '' : `import type { HelixIcon } from '${typeImport}'\n`;
+    mkdirSync(dirname(out), { recursive: true });
+    writeFileSync(out, `// Generated by @fusion.dev/helix-icons. Do not edit.\n${head}\n${body}\n${index ? `\n${indexed} {\n${record}\n}\n` : ''}`);
     return entries.length;
 }

package/dist/cli.js

@@ -9,61 +9,81 @@ const USAGE = `helix-icons build --source <dir> [--suffix <text>] [--list <file>
                     before it: --source …/bold --suffix -bold reads caret-down-bold.svg.
   --list <file>     Names to build, one per line, # for a comment. Default: every
                     glyph the sources hold.
-  --out <file>      Where to write the module. Default: icons.generated.ts
+  --out <file>      Where to write the module: JavaScript for a .js or .mjs file,
+                    TypeScript otherwise. Default: icons.generated.ts
   --index           Also write the record \`<helix-icon name>\` reads. It names every
                     glyph, so nothing can drop any of it: for markup, not for imports.
   --type-import <s> Where the module imports \`HelixIcon\` from.
-                    Default: @fusion.dev/helix-icons`;
+                    Default: @fusion.dev/helix-icons
+  -h, --help        Print this.`;
 const after = (argv, at) => {
     const value = argv[at + 1];
     return value === undefined || value.startsWith('--') ? undefined : value;
 };
+const refuse = (message, usage = false) => {
+    console.error(`helix-icons: ${message}`);
+    if (usage) {
+        console.error(`\n${USAGE}`);
+    }
+    return 1;
+};
 export function main(argv) {
-    if (argv[0] !== 'build' || argv.includes('--help')) {
+    if (argv.includes('--help') || argv.includes('-h')) {
         console.log(USAGE);
-        return argv[0] === 'build' ? 0 : 1;
+        return 0;
+    }
+    if (argv[0] !== 'build') {
+        return refuse(argv[0] === undefined ? 'needs a command' : `${argv[0]} is not a command`, true);
     }
     const sources = [];
     let list;
     let out = 'icons.generated.ts';
     let index = false;
     let typeImport;
-    for (const [at, flag] of argv.entries()) {
+    for (let at = 1; at < argv.length; at += 1) {
+        const flag = argv[at];
+        if (flag === '--index') {
+            index = true;
+            continue;
+        }
+        const value = after(argv, at);
         switch (flag) {
-            case '--source': {
-                const directory = after(argv, at);
-                if (directory === undefined) {
-                    console.error('helix-icons: --source needs a directory');
-                    return 1;
+            case '--source':
+                if (value === undefined) {
+                    return refuse('--source needs a directory');
                 }
-                sources.push({ directory: resolve(directory) });
+                sources.push({ directory: resolve(value) });
                 break;
-            }
             case '--suffix': {
-                const suffix = after(argv, at);
                 const last = sources.at(-1);
-                if (suffix === undefined || last === undefined) {
-                    console.error('helix-icons: --suffix names what a file carries, after the --source it is for');
-                    return 1;
+                if (value === undefined || last === undefined) {
+                    return refuse('--suffix names what a file carries, after the --source it is for');
                 }
-                last.suffix = suffix;
+                last.suffix = value;
                 break;
             }
             case '--list':
-                list = after(argv, at);
+                if (value === undefined) {
+                    return refuse('--list needs a file');
+                }
+                list = value;
                 break;
             case '--out':
-                out = after(argv, at) ?? out;
-                break;
-            case '--index':
-                index = true;
+                if (value === undefined) {
+                    return refuse('--out needs a file');
+                }
+                out = value;
                 break;
             case '--type-import':
-                typeImport = after(argv, at);
+                if (value === undefined) {
+                    return refuse('--type-import needs the module to import the type from');
+                }
+                typeImport = value;
                 break;
             default:
-                break;
+                return refuse(`${flag} is not an option of build`, true);
         }
+        at += 1;
     }
     if (sources.length === 0) {
         console.error('helix-icons: needs at least one --source\n');

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-icons",
   "description": "Helix icon set.",
-  "version": "0.205.2",
+  "version": "0.207.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -25,6 +25,7 @@
       "types": "./dist/build.d.ts",
       "default": "./dist/build.js"
     },
+    "./package.json": "./package.json",
     "./regular": {
       "types": "./dist/regular.d.ts",
       "default": "./dist/regular.js"