@enigmax/icons 0.1.0 → 0.2.0

package/LICENSE

@@ -19,12 +19,3 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
-
----
-
-The icon artwork is the Solar Icon Set by 480 Design, licensed under
-Creative Commons Attribution 4.0 International (CC BY 4.0):
-https://creativecommons.org/licenses/by/4.0/
-
-Attribution is required by that licence. Keep this notice, and surface the
-credit somewhere in any application that ships these icons.

package/README.md

@@ -1,7 +1,7 @@
 # @enigmax/icons
 
-Filled duotone icons for React. 391 icons in 36 categories, each in its own
-module, so a bundle carries only the ones it renders.
+Icons for React. 391 icons in 36 categories, each in its own module, so a
+bundle carries only the ones it renders.
 
 ```tsx
 import { IconMapPin } from "@enigmax/icons";
@@ -10,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
 
@@ -33,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.
@@ -47,18 +77,13 @@ one. Install `@tabler/icons-react` only if you import a brand mark.
 ## Regenerating
 
 ```sh
-node generate.mjs --solar <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
 
-The icon artwork is the Solar Icon Set by 480 Design, used under
-[CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). That licence
-requires attribution: keep this notice, and surface it somewhere in any app
-that ships these icons (an About or Credits screen is the usual place).
-
-The package code is MIT.
+MIT.

package/generate.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// Generate the icon package's source from icon-map.json and the Solar set.
+// Generate the icon package's source from icon-map.json and a set of drawings.
 //
 // One module per icon, one barrel per category, and a root index that re-exports
 // everything. That shape is what lets a bundler drop what an app never renders:
@@ -8,15 +8,21 @@
 // fetched at install time - the bodies are written here as plain strings.
 //
 // Usage:
-//   node generate.mjs --solar <path/to/solar-icons.json> [--out src]
+//   node generate.mjs --set <path/to/icons.json> [--weight <name>] [--out src]
 //
-// The Solar 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 is 7,759 icons, of which this keeps about five percent.
+// 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.
 //
-// Solar Icon Set by 480 Design, CC BY 4.0
-// (https://creativecommons.org/licenses/by/4.0/). The attribution the licence
-// requires ships in the package README and must not be stripped.
+// 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
+// is several thousand icons, of which this keeps about five percent.
 import { fileURLToPath } from "node:url";
 import { resolve, dirname } from "node:path";
 import { readFileSync, writeFileSync, mkdirSync, rmSync, existsSync } from "node:fs";
@@ -29,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 SOLAR = arg("--solar", null);
-if (!SOLAR || !existsSync(SOLAR)) {
-    console.error("usage: node generate.mjs --solar <path/to/solar-icons.json> [--out src]");
+const SET = arg("--set", null);
+if (!SET || !existsSync(SET)) {
+    console.error("usage: node generate.mjs --set <path/to/icons.json> [--weight <name>] [--out src]");
     process.exit(1);
 }
 
@@ -52,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;
@@ -69,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>(
@@ -94,34 +99,70 @@ export function icon(name: string, body: string): Icon {
 }
 `;
 
-const { icons, brands } = JSON.parse(readFileSync(MAP, "utf8"));
-const solar = JSON.parse(readFileSync(SOLAR, "utf8")).icons;
+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);
+}
 
-// 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]) => !solar[spec.solar]);
+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 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.solar}`);
+    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 { solar: solarName, category } = icons[name];
-    const body = solar[solarName].body;
+    const { category } = icons[name];
+    const glyph = glyphFor(icons[name]);
+    const body = drawings[glyph].body;
     bytes += body.length;
-    const file = `// ${name} - ${solarName}. GENERATED, do not hand-edit.
-import { icon } from "../icon";
+    const file = `// ${name} - ${glyph}. GENERATED, do not hand-edit.
+import { icon } from "${FACTORY_IMPORT}";
 
 export const ${name} = icon(${JSON.stringify(name)}, ${JSON.stringify(body)});
 `;
@@ -139,26 +180,28 @@ for (const category of categories) {
 }
 
 const index = [
-    "// GENERATED, do not hand-edit. Run: node generate.mjs --solar <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
@@ -170,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`,
 );