@fusion.dev/helix-icons 0.99.0 → 0.101.0

package/README.md

@@ -38,6 +38,35 @@ an attribute would put every weight in the lookup `<helix-icon name>` reads.
 Every Helix component that draws a mark also offers a slot over it, so you can
 put your own drawing in one place without replacing the package.
 
+## Your own set
+
+The generator that builds this set is the package's own command, so a folder of
+SVG files becomes a module the element draws from:
+
+```sh
+npx helix-icons build --source ./brand-icons --out src/icons.ts
+```
+
+```tsx
+import { peak } from './icons'
+
+<helix-icon icon={peak} />
+```
+
+Any set, not only ours. A subset of Phosphor larger than the 108 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:
+
+```sh
+npx helix-icons build \
+  --source node_modules/@phosphor-icons/core/assets/bold --suffix -bold \
+  --list mine.txt --out src/icons.ts
+```
+
+`--index` also writes the record `<helix-icon name>` reads. It names every glyph,
+so nothing can drop any of it: ask for it when you want names in markup, and
+leave it off when you import.
+
 Phosphor is MIT and its notice travels in `LICENSE` beside ours.
 
 [Documentation](https://fusion.dev/helix)

package/dist/build.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Turns a directory of SVG files into the module `<helix-icon>` draws from.
+ *
+ * **Published, because the shape is ours and the tool that makes it should
+ * travel with it.** An icon is `{ content, name, viewBox }`, so any set answers
+ * it, and until this shipped the only way to get one was to hand-write the
+ * objects or to send a pull request against this package. A consumer's own
+ * drawings, a subset of Phosphor larger than the hundred and eight here, or
+ * another library's set are all the same job, and it is this one.
+ *
+ * **A directory and a suffix, rather than knowledge of anybody's layout.** The
+ * sets differ in how they name a file for a weight: Phosphor writes
+ * `caret-down-bold.svg` and leaves regular bare, and another library will do
+ * something else. So the caller says which directories to look in and what a
+ * file is called, and this stays a reader of files.
+ *
+ * **Sources are a precedence, and a name in two of them is an error.** A
+ * precedence decides silently: the glyph on the page would be whichever
+ * directory sat higher, and nothing about it looks wrong afterwards. This is the
+ * rule the Helix set has always been built under, and it is the consumer's now
+ * as well.
+ */
+/** One place to look for glyphs, and what a file is called when it is there. */
+export interface IconSource {
+    /** Where the SVG files are. */
+    directory: string;
+    /**
+     * What sits between the name and `.svg`, for a set that spells a weight into
+     * the file name. Phosphor's bold is `caret-down-bold.svg`; its regular, and
+     * most other sets, are bare.
+     */
+    suffix?: string;
+}
+/** What to build, and where to put it. */
+export interface BuildOptions {
+    /**
+     * The names to resolve, in the order they should be written.
+     *
+     * Left out, every glyph in the sources is taken, which is what a consumer
+     * pointing at their own folder of drawings usually means.
+     */
+    names?: string[];
+    /** Where to write the module. */
+    out: string;
+    sources: IconSource[];
+    /**
+     * Also write the record `<helix-icon name>` reads.
+     *
+     * **Off by default, and the default is the point.** The record names every
+     * glyph, so no bundler can drop any of it: it is what a consumer pays for the
+     * convenience of naming an icon in markup. A module built for import does not
+     * need one, and one that has it charges everybody for a door they may not
+     * use.
+     */
+    index?: boolean;
+    /** Where the emitted module imports `HelixIcon` from. */
+    typeImport?: string;
+}
+/**
+ * Writes the module, and says how many glyphs are in it.
+ *
+ * @throws where a name resolves to no file, or to more than one.
+ */
+export declare function build(options: BuildOptions): number;

package/dist/build.js

@@ -0,0 +1,73 @@
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { optimize } from 'svgo';
+const SVGO = {
+    multipass: true,
+    plugins: [{ name: 'preset-default', params: { overrides: { cleanupIds: false } } }],
+};
+const camel = (slug) => slug.replace(/-([a-z0-9])/g, (_, char) => char.toUpperCase());
+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;
+            }
+            const bare = file.slice(0, -'.svg'.length);
+            if (suffix === '' || bare.endsWith(suffix)) {
+                found.add(suffix === '' ? bare : bare.slice(0, -suffix.length));
+            }
+        }
+    }
+    return [...found].sort();
+};
+const sourceFor = (slug, sources) => {
+    const candidates = sources
+        .map(({ directory, suffix = '' }) => join(directory, `${slug}${suffix}.svg`))
+        .filter((file) => existsSync(file));
+    if (candidates.length > 1) {
+        throw new Error(`icons: "${slug}" resolves to ${candidates.length} files, and the order between them is a ` +
+            `silent decision:\n  ${candidates.join('\n  ')}\n` +
+            'Rename one, or name the sources in the order you mean.');
+    }
+    if (candidates.length === 0) {
+        throw new Error(`icons: no SVG for "${slug}" in ${sources.map((one) => one.directory).join(', ')}`);
+    }
+    return readFileSync(candidates[0], 'utf8');
+};
+const drawn = (slug, sources) => {
+    const source = optimize(sourceFor(slug, sources), SVGO).data;
+    const viewBox = /viewBox="([^"]+)"/.exec(source)?.[1] ?? '0 0 256 256';
+    const content = source
+        .replace(/^[\s\S]*?<svg[^>]*>/, '')
+        .replace(/<\/svg>[\s\S]*$/, '')
+        .replace(/<title>[\s\S]*?<\/title>/g, '')
+        .replace(/\s+/g, ' ')
+        .trim();
+    return { camel: camel(slug), content, slug, viewBox };
+};
+export function build(options) {
+    const { index = false, out, sources, typeImport = '@fusion.dev/helix-icons' } = options;
+    const names = options.names ?? namesIn(sources);
+    const entries = names.map((slug) => drawn(slug, sources));
+    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}`)
+        .join('\n\n');
+    const record = entries.map(({ camel: name }) => `  [${name}.name]: ${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}
+}
+`
+        : ''}`);
+    return entries.length;
+}

package/dist/cli.d.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * `helix-icons build`, which turns SVG files into the module the element draws.
+ *
+ * ```sh
+ * helix-icons build --source ./brand-icons --out src/icons.ts
+ * helix-icons build --source node_modules/@phosphor-icons/core/assets/regular \
+ *   --list mine.txt --out src/icons.ts
+ * ```
+ *
+ * **A flag per source, in the order they are searched**, so a set that keeps
+ * its weights in separate folders is two flags rather than a convention this
+ * has to know. `--suffix` applies to the source before it, because that is what
+ * it is about: Phosphor's bold folder names a file `caret-down-bold.svg` and its
+ * regular folder names the same glyph `caret-down.svg`.
+ */
+export declare function main(argv: string[]): number;

package/dist/cli.js

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { build } from './build.js';
+const USAGE = `helix-icons build --source <dir> [--suffix <text>] [--list <file>] [--out <file>]
+
+  --source <dir>    Where SVG files are. Repeat for a fallback, searched in order.
+  --suffix <text>   What a file name carries after the icon's name, for the source
+                    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
+  --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`;
+const after = (argv, at) => {
+    const value = argv[at + 1];
+    return value === undefined || value.startsWith('--') ? undefined : value;
+};
+export function main(argv) {
+    if (argv[0] !== 'build' || argv.includes('--help')) {
+        console.log(USAGE);
+        return argv[0] === 'build' ? 0 : 1;
+    }
+    const sources = [];
+    let list;
+    let out = 'icons.generated.ts';
+    let index = false;
+    let typeImport;
+    for (const [at, flag] of argv.entries()) {
+        switch (flag) {
+            case '--source': {
+                const directory = after(argv, at);
+                if (directory === undefined) {
+                    console.error('helix-icons: --source needs a directory');
+                    return 1;
+                }
+                sources.push({ directory: resolve(directory) });
+                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;
+                }
+                last.suffix = suffix;
+                break;
+            }
+            case '--list':
+                list = after(argv, at);
+                break;
+            case '--out':
+                out = after(argv, at) ?? out;
+                break;
+            case '--index':
+                index = true;
+                break;
+            case '--type-import':
+                typeImport = after(argv, at);
+                break;
+            default:
+                break;
+        }
+    }
+    if (sources.length === 0) {
+        console.error('helix-icons: needs at least one --source\n');
+        console.error(USAGE);
+        return 1;
+    }
+    let names;
+    if (list !== undefined) {
+        if (!existsSync(list)) {
+            console.error(`helix-icons: no list at ${list}`);
+            return 1;
+        }
+        names = readFileSync(list, 'utf8')
+            .split('\n')
+            .map((line) => line.trim())
+            .filter((line) => line !== '' && !line.startsWith('#'))
+            .sort();
+    }
+    try {
+        const many = build({
+            index,
+            out: resolve(out),
+            sources,
+            ...(names ? { names } : {}),
+            ...(typeImport ? { typeImport } : {}),
+        });
+        console.log(`helix-icons: ${many} written to ${out}`);
+        return 0;
+    }
+    catch (why) {
+        console.error(why instanceof Error ? why.message : String(why));
+        return 1;
+    }
+}
+if (process.argv[1]?.includes('helix-icons') || process.argv[1]?.endsWith('cli.js')) {
+    process.exit(main(process.argv.slice(2)));
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-icons",
   "description": "Helix icon set.",
-  "version": "0.99.0",
+  "version": "0.101.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -21,6 +21,10 @@
       "types": "./dist/bold.d.ts",
       "default": "./dist/bold.js"
     },
+    "./build": {
+      "types": "./dist/build.d.ts",
+      "default": "./dist/build.js"
+    },
     "./regular": {
       "types": "./dist/regular.d.ts",
       "default": "./dist/regular.js"
@@ -31,16 +35,22 @@
     "raw"
   ],
   "sideEffects": false,
+  "bin": {
+    "helix-icons": "./dist/cli.js"
+  },
   "scripts": {
     "build": "bun run icons && tsc -p tsconfig.build.json && tsc -p tsconfig.types.json",
     "icons": "bun scripts/build-icons.mjs",
+    "test": "bun test src",
     "typecheck": "bun run icons && tsc -p tsconfig.json --noEmit"
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
-  "devDependencies": {
-    "@phosphor-icons/core": "^2.1.1",
+  "dependencies": {
     "svgo": "^4.1.0"
   },
+  "devDependencies": {
+    "@phosphor-icons/core": "^2.1.1"
+  },
   "homepage": "https://fusion.dev",
   "keywords": [
     "icons",