@enigmax/icons 0.1.1 → 0.2.0

package/README.md

@@ -3,9 +3,6 @@
 Icons for React. 391 icons in 36 categories, each in its own module, so a
 bundle carries only the ones it renders.
 
-Bold duotone is the weight that ships today. The package is built to hold more
-than one, so nothing in its name, its exports or its API is tied to that weight.
-
 ```tsx
 import { IconMapPin } from "@enigmax/icons";
 
@@ -13,10 +10,9 @@ import { IconMapPin } from "@enigmax/icons";
 ```
 
 The icons are filled, not stroked: colour comes from the surrounding text
-colour (`currentColor`), and the lighter half of each glyph is the same colour
-at 50% opacity. There is no line to widen, so `stroke` is accepted and ignored
-rather than forwarded into the SVG attribute of that name, which takes a colour
-and would paint the icon with an invalid value until it disappeared.
+colour (`currentColor`). There is no line to widen, so `stroke` is accepted and
+ignored rather than forwarded into the SVG attribute of that name, which takes
+a colour and would paint the icon with an invalid value until it disappeared.
 
 ## Only what you use
 
@@ -36,13 +32,44 @@ import * as icons from "@enigmax/icons/categories";
 Categories come from the set's own taxonomy: `arrows`, `devices`, `map`,
 `security`, `ui`, `weather`, and thirty more.
 
+## Weights
+
+Bold duotone is the weight that ships today, and it is addressable by name:
+
+```tsx
+import { IconMapPin } from "@enigmax/icons";               // the default weight
+import { IconMapPin } from "@enigmax/icons/bold-duotone";  // the same icon, named
+```
+
+**A weight is a build dimension, not a prop.** A `weight` prop would have to
+reach every body at runtime, which puts all of them in the bundle for any icon
+the app imports and destroys the one thing this package is for. So each weight
+is generated into its own directory with its own subpath, and an app pays only
+for the weights it actually imports. Two weights of the same icon are two
+imports, and a project that uses one never downloads the other.
+
+Adding one is three steps and no breaking change:
+
+1. Declare it in `icon-map.json` under `weights.available`.
+2. Give every icon its name in that weight under `glyphs`, e.g.
+   `"IconSun": { "glyph": "sun-bold-duotone", "glyphs": { "outline": "sun-linear" }, "category": "Weather" }`.
+   Names are written out per weight rather than derived by swapping a suffix: a
+   set is free to name a weight's glyph anything, and guessing it produces an
+   icon that silently renders nothing.
+3. `node generate.mjs --set <set.json> --weight outline`.
+
+The default weight keeps the root paths, so nothing that already imports from
+this package changes when a weight is added. A weight that is declared but
+incomplete fails the test suite rather than shipping: half a weight renders
+some icons and vanishes the rest, which reads as a broken page.
+
 ## Conventions
 
 An external link is marked with the **diagonal arrow pointing up and to the
 right** (`IconExternalLink`), not the box-with-an-arrow-leaving-it glyph: the
 latter reads as clutter at small sizes in a filled set.
 
-Brand marks (`IconBrandGithub`, `IconBrandDiscord`, …) are re-exported from
+Brand marks (`IconBrandGithub`, `IconBrandDiscord`, ...) are re-exported from
 `@tabler/icons-react`, an optional peer dependency. This set has no brand
 marks, and drawing a company's logo by hand is worse than shipping the real
 one. Install `@tabler/icons-react` only if you import a brand mark.
@@ -50,12 +77,12 @@ one. Install `@tabler/icons-react` only if you import a brand mark.
 ## Regenerating
 
 ```sh
-node generate.mjs --set <path/to/set.json>
+node generate.mjs --set <path/to/set.json> [--weight <name>]
 ```
 
 Edit `icon-map.json` to add, remove or re-point an icon, then regenerate. A
-name that is not in the set fails the run rather than rendering an empty square
-forever.
+name that is not in the set, or an icon with no name for the weight being
+generated, fails the run rather than rendering an empty square forever.
 
 ## Licence
 

package/generate.mjs

@@ -8,7 +8,17 @@
 // fetched at install time - the bodies are written here as plain strings.
 //
 // Usage:
-//   node generate.mjs --set <path/to/icons.json> [--out src]
+//   node generate.mjs --set <path/to/icons.json> [--weight <name>] [--out src]
+//
+// WEIGHT IS A BUILD DIMENSION, NOT A PROP. A `weight` prop would have to reach
+// every body at runtime, which puts all of them in the bundle for any icon the
+// app imports and destroys the one thing this package is for. So each weight is
+// generated into its own directory and addressed by its own subpath, and an app
+// pays only for the weights it actually imports.
+//
+// The DEFAULT weight (declared in icon-map.json) is written to the root of
+// `--out` so the package's main entry keeps working unchanged; every other
+// weight is written to `<out>/<weight>/`.
 //
 // The set is a build-time input, not a dependency of the published package: it
 // is read here and the ~400 bodies the map names are copied out. The full set
@@ -25,10 +35,9 @@ const arg = (flag, fallback) => {
     return i !== -1 && process.argv[i + 1] ? process.argv[i + 1] : fallback;
 };
 
-const OUT = resolve(HERE, arg("--out", "src"));
 const SET = arg("--set", null);
 if (!SET || !existsSync(SET)) {
-    console.error("usage: node generate.mjs --set <path/to/icons.json> [--out src]");
+    console.error("usage: node generate.mjs --set <path/to/icons.json> [--weight <name>] [--out src]");
     process.exit(1);
 }
 
@@ -48,7 +57,7 @@ export type IconProps = {
      * Accepted and ignored. These icons are filled, not stroked, so there is no
      * line to widen - and forwarding a number into the SVG \`stroke\` attribute,
      * which takes a COLOUR, paints the icon with an invalid value until it
-     * disappears. Kept in the signature so a stroked set can be swapped out
+     * disappears. Kept in the signature so a stroked weight can be swapped in
      * without touching the call sites that pass it.
      */
     stroke?: number | string;
@@ -65,8 +74,8 @@ export type Icon = ForwardRefExoticComponent<IconProps & RefAttributes<SVGSVGEle
  *
  * The body is a constant written by the generator, never anything a caller
  * supplies, which is what makes dangerouslySetInnerHTML the right tool here
- * rather than a hole. Both paths of a duotone glyph carry fill="currentColor",
- * so colour comes from the surrounding text colour and nothing else.
+ * rather than a hole. Every path carries fill="currentColor", so colour comes
+ * from the surrounding text colour and nothing else.
  */
 export function icon(name: string, body: string): Icon {
     const Component = forwardRef<SVGSVGElement, IconProps>(
@@ -90,34 +99,70 @@ export function icon(name: string, body: string): Icon {
 }
 `;
 
-const { icons, brands } = JSON.parse(readFileSync(MAP, "utf8"));
+const { icons, brands, weights } = JSON.parse(readFileSync(MAP, "utf8"));
+const defaultWeight = weights?.default ?? "bold-duotone";
+const available = weights?.available ?? [defaultWeight];
+
+const WEIGHT = arg("--weight", defaultWeight);
+if (!available.includes(WEIGHT)) {
+    console.error(`Unknown weight '${WEIGHT}'. icon-map.json declares: ${available.join(", ")}.`);
+    console.error("Add it to `weights.available` and give each icon its name under `glyphs` first.");
+    process.exit(1);
+}
+
+const isDefault = WEIGHT === defaultWeight;
+// The default weight owns the root of the output so the package's main entry is
+// unchanged by this ever growing; another weight gets a directory of its own.
+const OUT = resolve(HERE, arg("--out", "src"), isDefault ? "" : WEIGHT);
+const FACTORY_IMPORT = isDefault ? "../icon" : "../../icon";
+
+/**
+ * What this icon is called in the requested weight.
+ *
+ * `glyph` is the default weight's name and every icon has one; another weight
+ * reads `glyphs[weight]`, which is written out per icon rather than derived by
+ * swapping a suffix - a set is free to name a weight's glyph anything at all,
+ * and guessing it produces an icon that silently renders nothing.
+ */
+const glyphFor = (spec) => (isDefault ? spec.glyph : spec.glyphs?.[WEIGHT]);
+
 const drawings = JSON.parse(readFileSync(SET, "utf8")).icons;
 
-// A name that is not in the set does not throw at runtime - it renders an empty
-// square forever - so it has to fail here instead.
-const missing = Object.entries(icons).filter(([, spec]) => !drawings[spec.glyph]);
+// A name that is missing, or not in the set, does not throw at runtime - it
+// renders an empty square forever - so it has to fail here instead.
+const unnamed = Object.entries(icons).filter(([, spec]) => !glyphFor(spec));
+if (unnamed.length > 0) {
+    console.error(`${unnamed.length} icon(s) have no name for weight '${WEIGHT}':`);
+    for (const [name] of unnamed.slice(0, 10)) console.error(`    ${name}`);
+    process.exit(1);
+}
+const missing = Object.entries(icons).filter(([, spec]) => !drawings[glyphFor(spec)]);
 if (missing.length > 0) {
     console.error("Names not present in the icon set:");
-    for (const [name, spec] of missing.slice(0, 10)) console.error(`    ${name} -> ${spec.glyph}`);
+    for (const [name, spec] of missing.slice(0, 10)) console.error(`    ${name} -> ${glyphFor(spec)}`);
     process.exit(1);
 }
 
-rmSync(OUT, { recursive: true, force: true });
+rmSync(resolve(OUT, "icons"), { recursive: true, force: true });
+rmSync(resolve(OUT, "categories"), { recursive: true, force: true });
 mkdirSync(resolve(OUT, "icons"), { recursive: true });
 mkdirSync(resolve(OUT, "categories"), { recursive: true });
 
-writeFileSync(resolve(OUT, "icon.tsx"), FACTORY, "utf8");
+// One factory for every weight: it is the same component either way, so a second
+// weight must not ship a second copy of it.
+if (isDefault) writeFileSync(resolve(OUT, "icon.tsx"), FACTORY, "utf8");
 
 const names = Object.keys(icons).sort();
 const byCategory = new Map();
 let bytes = 0;
 
 for (const name of names) {
-    const { glyph, category } = icons[name];
+    const { category } = icons[name];
+    const glyph = glyphFor(icons[name]);
     const body = drawings[glyph].body;
     bytes += body.length;
     const file = `// ${name} - ${glyph}. GENERATED, do not hand-edit.
-import { icon } from "../icon";
+import { icon } from "${FACTORY_IMPORT}";
 
 export const ${name} = icon(${JSON.stringify(name)}, ${JSON.stringify(body)});
 `;
@@ -135,26 +180,28 @@ for (const category of categories) {
 }
 
 const index = [
-    "// GENERATED, do not hand-edit. Run: node generate.mjs --set <set.json>",
+    `// GENERATED, do not hand-edit. Run: node generate.mjs --set <set.json> --weight ${WEIGHT}`,
     "//",
     "// Import from the root for a single icon (the bundler keeps only that module),",
     "// or from a category when you want the group:",
     "//   import { IconMapPin } from \"@<scope>/icons\";",
     "//   import { IconMapPin } from \"@<scope>/icons/categories/map\";",
     "",
-    "export type { Icon, IconProps } from \"./icon\";",
-    "",
 ];
+if (isDefault) index.push("export type { Icon, IconProps } from \"./icon\";", "");
 for (const name of names) index.push(`export { ${name} } from "./icons/${name}";`);
-index.push("", "// Brand marks keep their real logo: this set has none, and drawing one by hand");
-index.push("// is worse than shipping the real mark.", "export {");
-// No comma after the last entry: a trailing one in a named export list is a style
-// violation here, and the generator is the only thing that writes this file.
-const sortedBrands = [...brands].sort();
-for (const [position, brand] of sortedBrands.entries()) {
-    index.push(`    ${brand}${position === sortedBrands.length - 1 ? "" : ","}`);
+if (isDefault) {
+    index.push("", "// Brand marks keep their real logo: this set has none, and drawing one by hand");
+    index.push("// is worse than shipping the real mark.", "export {");
+    // No comma after the last entry: a trailing one in a named export list is a style
+    // violation here, and the generator is the only thing that writes this file.
+    const sortedBrands = [...brands].sort();
+    for (const [position, brand] of sortedBrands.entries()) {
+        index.push(`    ${brand}${position === sortedBrands.length - 1 ? "" : ","}`);
+    }
+    index.push("} from \"@tabler/icons-react\";");
 }
-index.push("} from \"@tabler/icons-react\";", "");
+index.push("");
 writeFileSync(resolve(OUT, "index.ts"), index.join("\n"), "utf8");
 
 // A namespace export needs an identifier, so the category's display name becomes
@@ -166,6 +213,7 @@ for (const category of categories) {
 }
 writeFileSync(resolve(OUT, "categories", "index.ts"), `${catIndex.join("\n")}\n`, "utf8");
 
+const brandNote = isDefault ? `, ${brands.length} brand re-exports` : "";
 process.stdout.write(
-    `${names.length} icons in ${categories.length} categories, ${brands.length} brand re-exports, ${(bytes / 1024).toFixed(0)} KB of bodies\n`,
+    `${WEIGHT}: ${names.length} icons in ${categories.length} categories${brandNote}, ${(bytes / 1024).toFixed(0)} KB of bodies\n`,
 );

package/icon-map.json

@@ -1,4 +1,8 @@
 {
+ "weights": {
+  "default": "bold-duotone",
+  "available": ["bold-duotone"]
+ },
  "icons": {
   "IconAbc": {
    "glyph": "text-bold-duotone",

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@enigmax/icons",
-    "version": "0.1.1",
+    "version": "0.2.0",
     "description": "Icon set for React, one module per icon so a bundle carries only what it renders.",
     "type": "module",
     "main": "./dist/index.js",
@@ -21,6 +21,22 @@
         "./categories/*": {
             "types": "./dist/categories/*.d.ts",
             "import": "./dist/categories/*.js"
+        },
+        "./bold-duotone": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        },
+        "./bold-duotone/icons/*": {
+            "types": "./dist/icons/*.d.ts",
+            "import": "./dist/icons/*.js"
+        },
+        "./bold-duotone/categories": {
+            "types": "./dist/categories/index.d.ts",
+            "import": "./dist/categories/index.js"
+        },
+        "./bold-duotone/categories/*": {
+            "types": "./dist/categories/*.d.ts",
+            "import": "./dist/categories/*.js"
         }
     },
     "files": [