mini-icon 1.0.0

package/README.md

@@ -0,0 +1,91 @@
+# mini-icon
+
+Build SVG icons into CSS mask classes, an SVG sprite, and TypeScript union types.
+
+## Install
+
+```bash
+npm install mini-icon
+```
+
+## CLI
+
+Add to `package.json`:
+
+```json
+{
+  "scripts": {
+    "icons": "mini-icon"
+  }
+}
+```
+
+Run:
+
+```bash
+npm run icons
+```
+
+## Config
+
+Create `mini-icon.config.js` in your project root:
+
+```js
+export default {
+  iconsDir: "_icons",
+  spriteOut: "public/icons.svg",
+  cssOut: "src/icons.css",
+  typesOut: "src/types/icon.ts",
+  htmlFile: "index.html",
+  injectSpriteLink: true,
+  spriteHref: "/icons.svg",
+};
+```
+
+JSON config (`mini-icon.config.json`) is also supported.
+
+## CLI flags
+
+```bash
+mini-icon --icons-dir assets/icons --css-out src/icons.css
+mini-icon --cwd ./apps/web
+mini-icon --inject-html --html-file index.html
+```
+
+## Programmatic API
+
+```js
+import { buildIcons } from "mini-icon";
+
+const result = buildIcons({
+  cwd: process.cwd(),
+  iconsDir: "_icons",
+  spriteOut: "public/icons.svg",
+  cssOut: "src/icons.css",
+  typesOut: "src/types/icon.ts",
+});
+
+console.log(result.names);
+```
+
+## Usage in HTML
+
+Put SVG source files in `_icons/` (or your configured folder), then:
+
+```html
+<link rel="preload" href="/icons.svg" as="image" type="image/svg+xml" />
+```
+
+```css
+@import "./icons.css";
+```
+
+```html
+<i class="icon search-lg"></i>
+```
+
+Color follows `currentColor`.
+
+## License
+
+MIT

package/bin/mini-icon.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+import { runCli } from "../src/cli.js";
+
+runCli();

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "mini-icon",
+  "version": "1.0.0",
+  "description": "Build SVG icons into CSS mask classes, SVG sprite, and TypeScript types",
+  "type": "module",
+  "license": "MIT",
+  "author": "",
+  "keywords": [
+    "svg",
+    "icons",
+    "sprite",
+    "css",
+    "mask",
+    "cli"
+  ],
+  "bin": {
+    "mini-icon": "./bin/mini-icon.js"
+  },
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node test/run.mjs"
+  }
+}

package/src/build.js

@@ -0,0 +1,186 @@
+import fs from "fs";
+import path from "path";
+
+const DEFAULTS = {
+  iconsDir: "_icons",
+  spriteOut: "public/icons.svg",
+  cssOut: "src/icons.css",
+  typesOut: "src/types/icon.ts",
+  htmlFile: null,
+  injectSpriteLink: false,
+  spriteHref: "/icons.svg",
+  spriteMarker: "<!-- icon-sprite -->",
+  cssBanner: "/* Auto-generated — do not edit. Run: mini-icon */",
+};
+
+function extractSvgParts(content) {
+  const svgOpenMatch = content.match(/<svg([^>]*)>/i);
+  const svgAttrs = svgOpenMatch?.[1] ?? "";
+  const viewBoxMatch = svgAttrs.match(/viewBox="([^"]+)"/i);
+  const viewBox = viewBoxMatch?.[1] ?? "0 0 24 24";
+
+  let inner = content.replace(/<svg[^>]*>/i, "").replace(/<\/svg>\s*$/i, "").trim();
+
+  const presentationAttrs = ["fill", "stroke", "stroke-width", "stroke-linecap", "stroke-linejoin", "fill-rule"];
+  const inherited = presentationAttrs.flatMap((attr) => {
+    const match = svgAttrs.match(new RegExp(`${attr}="([^"]*)"`, "i"));
+    return match ? [`${attr}="${match[1]}"`] : [];
+  });
+
+  if (inherited.length > 0 && !/<(?:g|path|circle|rect|line|polyline|polygon)[^>]*\bstroke=/.test(inner)) {
+    inner = `<g ${inherited.join(" ")}>${inner}</g>`;
+  }
+
+  return { viewBox, inner };
+}
+
+function toMaskSvg(content) {
+  return content
+    .replace(/currentColor/g, "#000")
+    .replace(/fill="(?!none|currentColor)[^"]*"/gi, 'fill="#000"')
+    .replace(/stroke="(?!none|currentColor)[^"]*"/gi, 'stroke="#000"');
+}
+
+function toDataUri(content) {
+  const encoded = encodeURIComponent(toMaskSvg(content)).replace(/'/g, "%27").replace(/"/g, "%22");
+  return `url("data:image/svg+xml,${encoded}")`;
+}
+
+function injectSpriteLink(htmlFile, spriteHref, spriteMarker) {
+  if (!htmlFile || !fs.existsSync(htmlFile)) return;
+
+  const linkTag = `<link rel="preload" href="${spriteHref}" as="image" type="image/svg+xml" />`;
+  let html = fs.readFileSync(htmlFile, "utf8");
+
+  if (html.includes(spriteMarker)) {
+    html = html.replace(
+      new RegExp(`${escapeRegExp(spriteMarker)}[\\s\\S]*?${escapeRegExp(spriteMarker)}`),
+      `${spriteMarker}\n    ${linkTag}\n    ${spriteMarker}`,
+    );
+  } else if (!html.includes(spriteHref)) {
+    html = html.replace("</head>", `    ${spriteMarker}\n    ${linkTag}\n    ${spriteMarker}\n  </head>`);
+  }
+
+  fs.writeFileSync(htmlFile, html);
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function resolveFromCwd(cwd, target) {
+  return path.isAbsolute(target) ? target : path.join(cwd, target);
+}
+
+/**
+ * @param {Partial<typeof DEFAULTS> & { cwd?: string }} userOptions
+ */
+export function buildIcons(userOptions = {}) {
+  const cwd = userOptions.cwd ? path.resolve(userOptions.cwd) : process.cwd();
+  const options = { ...DEFAULTS, ...userOptions };
+
+  const iconsDir = resolveFromCwd(cwd, options.iconsDir);
+  const spriteOut = resolveFromCwd(cwd, options.spriteOut);
+  const cssOut = resolveFromCwd(cwd, options.cssOut);
+  const typesOut = resolveFromCwd(cwd, options.typesOut);
+  const htmlFile = options.htmlFile ? resolveFromCwd(cwd, options.htmlFile) : null;
+
+  if (!fs.existsSync(iconsDir)) {
+    fs.mkdirSync(iconsDir, { recursive: true });
+    return {
+      ok: true,
+      createdIconsDir: true,
+      count: 0,
+      names: [],
+      outputs: {},
+      message: `Created ${options.iconsDir}/ — add .svg files and run mini-icon again.`,
+    };
+  }
+
+  const files = fs.readdirSync(iconsDir).filter((file) => file.endsWith(".svg"));
+  if (files.length === 0) {
+    return {
+      ok: false,
+      count: 0,
+      names: [],
+      outputs: {},
+      message: `No SVG files found in ${options.iconsDir}/`,
+    };
+  }
+
+  fs.mkdirSync(path.dirname(spriteOut), { recursive: true });
+  fs.mkdirSync(path.dirname(cssOut), { recursive: true });
+  fs.mkdirSync(path.dirname(typesOut), { recursive: true });
+
+  const names = [];
+  const rules = [];
+  const symbols = [];
+
+  for (const file of files.sort()) {
+    const name = path.basename(file, ".svg");
+    const content = fs.readFileSync(path.join(iconsDir, file), "utf8");
+    const { viewBox, inner } = extractSvgParts(content);
+
+    names.push(name);
+    symbols.push(`  <symbol id="${name}" viewBox="${viewBox}">${inner}</symbol>`);
+    rules.push(`.icon.${name}::before {
+  -webkit-mask-image: ${toDataUri(content)};
+  mask-image: ${toDataUri(content)};
+}`);
+  }
+
+  const sprite = `<svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" style="display:none">\n${symbols.join("\n")}\n</svg>\n`;
+  fs.writeFileSync(spriteOut, sprite);
+
+  const css = `${options.cssBanner}
+.icon {
+  display: inline-block;
+  width: 1em;
+  height: 1em;
+  min-width: 1em;
+  min-height: 1em;
+  line-height: 1;
+  flex-shrink: 0;
+  vertical-align: middle;
+  font-style: normal;
+}
+
+.icon::before {
+  content: "";
+  display: block;
+  width: 100%;
+  height: 100%;
+  background-color: currentColor;
+  mask-repeat: no-repeat;
+  mask-position: center;
+  mask-size: contain;
+  -webkit-mask-repeat: no-repeat;
+  -webkit-mask-position: center;
+  -webkit-mask-size: contain;
+}
+
+${rules.join("\n\n")}
+`;
+
+  fs.writeFileSync(cssOut, css);
+  fs.writeFileSync(typesOut, `export type Icon =\n${names.map((name) => `  | '${name}'`).join("\n")};\n`);
+
+  if (options.injectSpriteLink && htmlFile) {
+    injectSpriteLink(htmlFile, options.spriteHref, options.spriteMarker);
+  }
+
+  return {
+    ok: true,
+    count: names.length,
+    names,
+    outputs: {
+      spriteOut,
+      cssOut,
+      typesOut,
+      htmlFile: options.injectSpriteLink ? htmlFile : null,
+    },
+    message: `Built ${names.length} icon(s): ${names.join(", ")}`,
+  };
+}
+
+export { DEFAULTS };

package/src/cli.js

@@ -0,0 +1,55 @@
+import path from "path";
+import { buildIcons } from "./build.js";
+import { loadConfig, parseCliArgs } from "./load-config.js";
+
+function printHelp() {
+  console.log(`mini-icon — build SVG icons into CSS masks, sprite, and TypeScript types
+
+Usage:
+  mini-icon [options]
+
+Options:
+  --cwd <dir>           Working directory (default: process.cwd())
+  --icons-dir <path>    Source SVG folder (default: _icons)
+  --sprite-out <path>   Output sprite path (default: public/icons.svg)
+  --css-out <path>      Output CSS path (default: src/icons.css)
+  --types-out <path>    Output TypeScript path (default: src/types/icon.ts)
+  --html-file <path>    HTML file for optional sprite preload injection
+  --sprite-href <url>   Sprite href used in HTML preload (default: /icons.svg)
+  --inject-html         Inject sprite preload link into HTML
+  --no-inject-html      Disable HTML injection
+  -h, --help            Show help
+
+Config:
+  mini-icon.config.js | .mjs | .json in project root
+`);
+}
+
+export async function runCli(argv = process.argv) {
+  const { options: cliOptions, showHelp } = parseCliArgs(argv);
+  if (showHelp) {
+    printHelp();
+    return 0;
+  }
+
+  const cwd = cliOptions.cwd ?? process.cwd();
+  const fileConfig = await loadConfig(cwd);
+  const options = {
+    ...fileConfig,
+    ...cliOptions,
+    cwd,
+  };
+
+  const result = buildIcons(options);
+
+  if (result.message) {
+    if (result.ok) console.log(result.message);
+    else console.warn(result.message);
+  }
+
+  if (result.outputs?.spriteOut) {
+    console.log(`Sprite: ${path.relative(cwd, result.outputs.spriteOut)}`);
+  }
+
+  return result.ok || result.createdIconsDir ? 0 : 1;
+}

package/src/index.js

@@ -0,0 +1,3 @@
+export { buildIcons, DEFAULTS } from "./build.js";
+export { loadConfig, parseCliArgs } from "./load-config.js";
+export { runCli } from "./cli.js";

package/src/load-config.js

@@ -0,0 +1,78 @@
+import fs from "fs";
+import path from "path";
+import { pathToFileURL } from "url";
+import { DEFAULTS } from "./build.js";
+
+const CONFIG_NAMES = ["mini-icon.config.js", "mini-icon.config.mjs", "mini-icon.config.json"];
+
+export async function loadConfig(cwd = process.cwd()) {
+  for (const name of CONFIG_NAMES) {
+    const filePath = path.join(cwd, name);
+    if (!fs.existsSync(filePath)) continue;
+
+    if (name.endsWith(".json")) {
+      return {
+        ...DEFAULTS,
+        ...JSON.parse(fs.readFileSync(filePath, "utf8")),
+        configFile: filePath,
+      };
+    }
+
+    const module = await import(`${pathToFileURL(filePath).href}?t=${Date.now()}`);
+    const config = module.default ?? module.config ?? module;
+    return {
+      ...DEFAULTS,
+      ...config,
+      configFile: filePath,
+    };
+  }
+
+  return { ...DEFAULTS, configFile: null };
+}
+
+export function parseCliArgs(argv) {
+  const args = argv.slice(2);
+  const options = { cwd: process.cwd() };
+  let showHelp = false;
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+
+    if (arg === "--help" || arg === "-h") {
+      showHelp = true;
+      continue;
+    }
+
+    if (arg === "--cwd") {
+      options.cwd = path.resolve(args[index + 1] ?? process.cwd());
+      index += 1;
+      continue;
+    }
+
+    const map = {
+      "--icons-dir": "iconsDir",
+      "--sprite-out": "spriteOut",
+      "--css-out": "cssOut",
+      "--types-out": "typesOut",
+      "--html-file": "htmlFile",
+      "--sprite-href": "spriteHref",
+    };
+
+    if (arg in map) {
+      options[map[arg]] = args[index + 1];
+      index += 1;
+      continue;
+    }
+
+    if (arg === "--inject-html") {
+      options.injectSpriteLink = true;
+      continue;
+    }
+
+    if (arg === "--no-inject-html") {
+      options.injectSpriteLink = false;
+    }
+  }
+
+  return { options, showHelp };
+}