pure-glyf 0.1.0

package/README.md

@@ -0,0 +1,265 @@
+# pure-glyf
+
+**Vite plugin and runtime to compile SVG icons into tree-shakeable CSS masks for modern web applications.**
+
+`pure-glyf` takes a different approach to icon management. Instead of inlining SVGs (bloating your DOM) or using sprites (complexity), it converts your SVGs into CSS classes that inject their styles on demand. The result? Zero runtime overhead for unused icons, perfect tree-shaking, and a developer experience that feels like magic.
+
+---
+
+## Features
+
+- 🌳 **True Tree-Shaking**: Only the icons you actually import end up in your final bundle.
+- 🚀 **Zero Runtime Overhead**: Icons are just strings (CSS class names). No heavy JS objects or runtime parsers.
+- ⚡ **On-Demand Injection**: CSS for an icon is only injected into the page when you import it.
+- 🧩 **Vite Integration**: A dedicated Vite plugin automates the entire process.
+- 🎨 **Themable**: Icons automatically inherit `currentColor`.
+- 🖥️ **SSR Ready**: Built-in support for server-side rendering (critical CSS extraction).
+- 🏷️ **Type-Safe**: Generated TypeScript definitions for your specific icon set.
+
+## Why pure-glyf?
+
+| Method | JS Bundle Size | DOM Size | Tree Shaking | Developer Experience |
+| :--- | :--- | :--- | :--- | :--- |
+| **Inline SVGs** | ❌ Heavy | ❌ Bloated | ✅ Good | 😐 Verbose JSX |
+| **SVG Sprites** | ✅ Light | ✅ Light | ❌ Hard | 😫 Manual Management |
+| **Icon Fonts** | ✅ Light | ✅ Light | ❌ None | 😐 FOUT / Accessibility |
+| **pure-glyf** | ✅ **Minimal** | ✅ **Minimal** | ✅ **Perfect** | 😍 **Auto-generated** |
+
+## Installation
+
+```bash
+npm install pure-glyf
+# or
+pnpm add pure-glyf
+# or
+yarn add pure-glyf
+```
+
+## Usage
+
+### 1. Structure Your Icons
+
+Place your SVG files in a directory. You can have multiple directories (e.g., for different icon sets).
+
+```
+src/
+  assets/
+    icons/
+      home.svg
+      user.svg
+      settings.svg
+```
+
+#### Using Icons from npm
+You can also source icons directly from installed packages (e.g., `@tabler/icons`, `@mdi/svg`, `heroicons`). Just install them as dev dependencies!
+
+### 2. Configure Vite
+
+Add `pureGlyfPlugin` to your `vite.config.ts`.
+
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite';
+import { pureGlyfPlugin } from 'pure-glyf/plugin';
+
+export default defineConfig({
+  plugins: [
+    pureGlyfPlugin({
+      icons: {
+        // 1. Local icons
+        // Usage: 'custom' + 'Home' -> customHome
+        custom: './src/assets/icons',
+        
+        // 2. Common Icon Libraries (examples)
+        
+        // Tabler Icons (Install: pnpm add -D @tabler/icons) - outline
+        // Usage: tablerHome, tablerUser
+        tabler: './node_modules/@tabler/icons/icons/outline',
+
+        // -- or --
+
+        // Tabler Icons (Install: pnpm add -D @tabler/icons) - all icons
+        // Usage: tablerOutlineHome, tablerFilledUser
+        tabler: './node_modules/@tabler/icons/icons',
+        
+        // Material Design Icons (Install: pnpm add -D @mdi/svg)
+        // Usage: mdiAccount, mdiHome
+        mdi: './node_modules/@mdi/svg/svg',
+        
+        // Heroicons (Install: pnpm add -D heroicons)
+        // Usage: heroHome, heroUser
+        hero: './node_modules/heroicons/24/outline',
+        
+        // Lucide (Install: pnpm add -D lucide-static)
+        // Usage: lucHome, lucUser
+        luc: './node_modules/lucide-static/icons',
+      },
+      dts: 'src/pure-glyf-icons.d.ts' 
+    })
+  ]
+});
+```
+
+### 3. Configure Rollup (Alternative)
+
+If you are using Rollup without Vite, use the plugin directly.
+
+> **Note**: You must use `@rollup/plugin-node-resolve` so Rollup can resolve the `pure-glyf` runtime.
+
+```javascript
+// rollup.config.js
+import resolve from '@rollup/plugin-node-resolve';
+import { pureGlyfPlugin } from 'pure-glyf/plugin';
+
+export default {
+  // ...
+  plugins: [
+    resolve(), // Required to resolve 'pure-glyf' runtime
+    pureGlyfPlugin({
+       icons: {
+         // ... same configuration as Vite
+         myIcon: './src/assets/icons'
+       }
+    })
+  ]
+};
+```
+
+### 3. Mount Styles
+
+In your application's entry point (e.g., `main.tsx` or `index.ts`), call `mount()` to set up the style injection system.
+
+```typescript
+// You can import 'mount' from the main package OR the virtual module
+import { mount } from 'pure-glyf'; 
+// import { mount } from 'pure-glyf/icons'; // Also works!
+
+mount(); // Injects the base styles and prepares the style tag
+```
+
+### 4. Use Icons
+
+Import icons from the virtual module `pure-glyf/icons`. The export name is `[Prefix][PascalCaseFilename]`.
+
+```tsx
+import { customHome, customUser } from 'pure-glyf/icons';
+
+function App() {
+  // 'customHome' is just a string: "pure-glyf-icon glyf-custom-home"
+  
+  return (
+    <nav>
+      {/* Use it as a class name on any element (usually <span> or <i>) */}
+      <span className={customHome} />
+      
+      <button>
+        <i className={customUser} /> Profile
+      </button>
+    </nav>
+  );
+}
+```
+
+## Configuration
+
+The `pureGlyfPlugin` accepts the following options:
+
+### `icons` (Required)
+A record mapping prefixes to directory paths.
+- **Key**: The prefix for the generated variable names (e.g., `tabler` -> `tablerHome`).
+- **Value**: The relative path to the directory containing `.svg` files.
+
+### `dts` (Optional)
+Path to generate the TypeScript declaration file. 
+- **Default**: `pure-glyf.d.ts` in the project root.
+- **Recommendation**: Set this to a path included in your `tsconfig.json` (e.g., `src/pure-glyf-icons.d.ts`).
+
+## styling
+
+Icons are rendered as CSS masks. They inherit the text color (`currentColor`) by default.
+
+### Default Styles
+Every icon comes with the `.pure-glyf-icon` class:
+
+```css
+.pure-glyf-icon {
+  display: inline-block;
+  width: 1em;
+  height: 1em;
+  background-color: currentColor; /* Matches text color */
+  mask-size: contain;
+  mask-repeat: no-repeat;
+  mask-position: center;
+}
+```
+
+### Custom Sizing & Coloring
+Since they are just elements with a background color, you style them with standard CSS:
+
+```css
+.my-huge-icon {
+  font-size: 3rem; /* 3x normal text size */
+  color: #ff0000;  /* Red icon */
+}
+```
+
+## Server-Side Rendering (SSR)
+
+`pure-glyf` supports SSR by allowing you to extract the CSS required for the rendered page.
+
+```typescript
+import { sheet } from 'pure-glyf';
+import { renderToString } from 'react-dom/server';
+
+// 1. Render your app
+const html = renderToString(<App />);
+
+// 2. Extract the accumulated CSS
+// 'sheet' contains the base styles + styles for all icons used during render
+const css = sheet;
+
+// 3. Inject into your HTML template
+const fullHtml = `
+  <!DOCTYPE html>
+  <html>
+    <head>
+      <style>${css}</style>
+    </head>
+    <body>
+      <div id="root">${html}</div>
+    </body>
+  </ul>
+`;
+```
+
+## Architecture & Performance
+
+`pure-glyf` uses a hybrid strategy to deliver the best developer experience without compiling performance costs.
+
+### Development Mode: Parallel Parsing
+In development, decoding thousands of Data URIs in JavaScript can be slow (blocking the main thread).
+- **Mechanism**: The plugin moves all icon CSS into a separate virtual CSS module (`pure-glyf/icons.css`).
+- **Benefit**: This offloads parsing to the browser's native CSS engine, which runs in parallel. The main JavaScript module remains tiny and instant to load.
+- **Result**: Near-instant HMR and page reloads, even with huge icon sets like Material Design or Tabler.
+
+### Production Mode: Perfect Tree-Shaking
+In production, we prioritize bundle size.
+- **Mechanism**: Icons are compiled into side-effect-free IIFEs (Immediately Invoked Function Expressions) annotated with `/*#__PURE__*/`.
+- **Logic**: 
+  ```javascript
+  export const myIcon = /*#__PURE__*/ (() => {
+      injectCSS("..."); // Only runs if 'myIcon' is actually used
+      return "pure-glyf-icon glyf-my-icon";
+  })();
+  ```
+- **Benefit**: If you don't import `myIcon`, your bundler (Vite/Rollup/Esbuild) completely removes the code *and* the associated CSS string.
+
+### The Virtual Module `pure-glyf/icons`
+The plugin orchestrates everything by creating a virtual module `pure-glyf/icons`. This module re-exports the core runtime functions for convenience:
+- `mount()`: Injects the styles.
+- `sheet`: Access the accumulated CSS string.
+- `onInject()`: Subscribe to new style injections.
+
+## License
+
+MIT

package/dist/generator.d.ts

@@ -0,0 +1,10 @@
+export interface IconDef {
+    name: string;
+    css: string;
+}
+export interface GeneratorResult {
+    code: string;
+    css: string;
+    dts: string;
+}
+export declare function generateIconsCode(config: Record<string, string>, isDev?: boolean): GeneratorResult;

package/dist/icons.d.ts

@@ -0,0 +1,2 @@
+export declare const home_icon: string;
+export declare const star_icon: string;

package/dist/index.cjs

@@ -0,0 +1,13 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const n=new Set;exports.sheet=`
+.pure-glyf-icon {
+    display: inline-block;
+    width: 1em;
+    height: 1em;
+    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;
+}`;let t=null;function r(){typeof document>"u"||t||(t=document.createElement("style"),t.textContent=exports.sheet,document.head.appendChild(t))}const o=new Set;function c(e){o.add(e)}function a(e){n.has(e)||(n.add(e),exports.sheet+=e,t&&(t.textContent=exports.sheet),o.forEach(i=>i(e)))}exports.injectCSS=a;exports.mount=r;exports.onInject=c;

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { injectCSS, sheet, mount, onInject } from './inject';

package/dist/index.js

@@ -0,0 +1,30 @@
+const o = /* @__PURE__ */ new Set();
+let n = `
+.pure-glyf-icon {
+    display: inline-block;
+    width: 1em;
+    height: 1em;
+    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;
+}`, t = null;
+function a() {
+  typeof document > "u" || t || (t = document.createElement("style"), t.textContent = n, document.head.appendChild(t));
+}
+const i = /* @__PURE__ */ new Set();
+function c(e) {
+  i.add(e);
+}
+function d(e) {
+  o.has(e) || (o.add(e), n += e, t && (t.textContent = n), i.forEach((r) => r(e)));
+}
+export {
+  d as injectCSS,
+  a as mount,
+  c as onInject,
+  n as sheet
+};

package/dist/inject.d.ts

@@ -0,0 +1,20 @@
+/**
+ * CSS injection utility for pure-glyf icons.
+ *
+ * Uses a deduplication set to ensure each CSS rule is only injected once.
+ * Exports `sheet` for SSR usage.
+ * styles are NOT injected automatically. You must call `mount()` to inject them into the DOM.
+ */
+/**
+ * Accumulated CSS string for Server-Side Rendering (SSR).
+ * Reset it if needed between requests in a server environment.
+ */
+export declare let sheet: string;
+/**
+ * Mounts the styles to the DOM.
+ * If the style tag already exists, it does nothing.
+ * If not, it creates it and populates it with the current accumulated CSS.
+ */
+export declare function mount(): void;
+export declare function onInject(callback: (css: string) => void): void;
+export declare function injectCSS(css: string): void;

package/dist/plugin.cjs

@@ -0,0 +1,6 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const d=require("node:fs"),p=require("node:path");function C(c){return c.replace(/[-_./\\]+(.)/g,(r,s)=>s.toUpperCase()).replace(/^./,r=>r.toUpperCase())}function I(c){return`data:image/svg+xml,${c.replace(/"/g,"'").replace(/%/g,"%25").replace(/#/g,"%23").replace(/{/g,"%7B").replace(/}/g,"%7D").replace(/</g,"%3C").replace(/>/g,"%3E").replace(/\s+/g," ")}`}function y(c,r){let s=[];return d.existsSync(c)&&d.readdirSync(c).forEach(i=>{const a=p.join(c,i),l=d.statSync(a);l&&l.isDirectory()?s=s.concat(y(a,r)):i.endsWith(".svg")&&s.push(p.relative(r,a))}),s}function P(c,r=!1){const s=[];for(const[n,e]of Object.entries(c)){const o=p.resolve(process.cwd(),e);if(!d.existsSync(o)){console.warn(`[pure-glyf] Warning: Icon directory not found: ${o}`);continue}y(o,o).forEach(g=>{const S=p.join(o,g),v=d.readFileSync(S,"utf-8"),m=g.replace(/\.svg$/,""),$=C(m),j=n+$,x=`glyf-${n.toLowerCase()}-${m.replace(/[^a-zA-Z0-9-]/g,"-")}`,h=I(v),w=`.${x}{mask-image:url("${h}");-webkit-mask-image:url("${h}");}`;s.push({name:j,css:w})})}const u=["import { injectCSS, mount, sheet, onInject } from 'pure-glyf';","export { mount, sheet, onInject };",""];let i="",a;r?(u.unshift("import 'pure-glyf/icons.css';"),i=s.map(n=>n.css).join(""),a=s.map(n=>{const e=n.css.match(/^\s*\.(\S+)\{/),o=e?e[1]:"error-class";return`export const ${n.name} = "pure-glyf-icon ${o}";`})):a=s.map(n=>{const e=n.css.match(/^\s*\.(\S+)\{/),o=e?e[1]:"error-class";return`export const ${n.name} = /*#__PURE__*/ (() => {
+    injectCSS(\`${n.css}\`);
+    return "pure-glyf-icon ${o}";
+})();`});const l=u.concat(a).join(`
+`),t=["declare module 'pure-glyf/icons' {","    export function mount(): void;","    export const sheet: string;","    export function onInject(callback: (css: string) => void): void;"];s.forEach(n=>{t.push(`    export const ${n.name}: string;`)}),t.push("}");const f=t.join(`
+`);return{code:l,css:i,dts:f}}function b(c){const r="pure-glyf/icons",s="\0"+r,u="pure-glyf/icons.css",i="\0"+u,a=c.dts||"pure-glyf.d.ts";let l=null,t=null,f=!1;function n(){try{if(l=P(c.icons,f),d.writeFileSync(p.resolve(process.cwd(),a),l.dts),t){const e=t.moduleGraph.getModuleById(s);e&&(t.moduleGraph.invalidateModule(e),t.ws.send({type:"full-reload",path:"*"}))}}catch(e){console.error("[pure-glyf] Generation failed:",e)}}return{name:"vite-plugin-pure-glyf",enforce:"pre",configResolved(e){f=e.command==="serve"},configureServer(e){t=e,Object.values(c.icons).forEach(o=>{t==null||t.watcher.add(p.resolve(o))}),t==null||t.watcher.on("change",o=>{o.endsWith(".svg")&&n()}),t==null||t.watcher.on("add",o=>{o.endsWith(".svg")&&n()}),t==null||t.watcher.on("unlink",o=>{o.endsWith(".svg")&&n()})},buildStart(){n()},resolveId(e){if(e===r)return s;if(e===u)return i},load(e){if(e===s)return l.code;if(e===i)return l.css}}}exports.pureGlyfPlugin=b;

package/dist/plugin.d.ts

@@ -0,0 +1,14 @@
+import type { Plugin } from 'vite';
+export interface PureGlyfConfig {
+    /**
+     * Map of Prefix -> Directory Path
+     * Example: { 'Tabler': './icons/tabler', 'MyIcon': './src/assets' }
+     */
+    icons: Record<string, string>;
+    /**
+     * Path to write the d.ts file to.
+     * Defaults to 'pure-glyf.d.ts' in the project root.
+     */
+    dts?: string;
+}
+export declare function pureGlyfPlugin(config: PureGlyfConfig): Plugin;

package/dist/plugin.js

@@ -0,0 +1,111 @@
+import p from "node:fs";
+import d from "node:path";
+function C(c) {
+  return c.replace(/[-_./\\]+(.)/g, (r, n) => n.toUpperCase()).replace(/^./, (r) => r.toUpperCase());
+}
+function I(c) {
+  return `data:image/svg+xml,${c.replace(/"/g, "'").replace(/%/g, "%25").replace(/#/g, "%23").replace(/{/g, "%7B").replace(/}/g, "%7D").replace(/</g, "%3C").replace(/>/g, "%3E").replace(/\s+/g, " ")}`;
+}
+function y(c, r) {
+  let n = [];
+  return p.existsSync(c) && p.readdirSync(c).forEach((i) => {
+    const a = d.join(c, i), l = p.statSync(a);
+    l && l.isDirectory() ? n = n.concat(y(a, r)) : i.endsWith(".svg") && n.push(d.relative(r, a));
+  }), n;
+}
+function P(c, r = !1) {
+  const n = [];
+  for (const [s, e] of Object.entries(c)) {
+    const o = d.resolve(process.cwd(), e);
+    if (!p.existsSync(o)) {
+      console.warn(`[pure-glyf] Warning: Icon directory not found: ${o}`);
+      continue;
+    }
+    y(o, o).forEach((g) => {
+      const S = d.join(o, g), v = p.readFileSync(S, "utf-8"), m = g.replace(/\.svg$/, ""), $ = C(m), x = s + $, j = `glyf-${s.toLowerCase()}-${m.replace(/[^a-zA-Z0-9-]/g, "-")}`, h = I(v), w = `.${j}{mask-image:url("${h}");-webkit-mask-image:url("${h}");}`;
+      n.push({ name: x, css: w });
+    });
+  }
+  const u = [
+    "import { injectCSS, mount, sheet, onInject } from 'pure-glyf';",
+    "export { mount, sheet, onInject };",
+    ""
+  ];
+  let i = "", a;
+  r ? (u.unshift("import 'pure-glyf/icons.css';"), i = n.map((s) => s.css).join(""), a = n.map((s) => {
+    const e = s.css.match(/^\s*\.(\S+)\{/), o = e ? e[1] : "error-class";
+    return `export const ${s.name} = "pure-glyf-icon ${o}";`;
+  })) : a = n.map((s) => {
+    const e = s.css.match(/^\s*\.(\S+)\{/), o = e ? e[1] : "error-class";
+    return `export const ${s.name} = /*#__PURE__*/ (() => {
+    injectCSS(\`${s.css}\`);
+    return "pure-glyf-icon ${o}";
+})();`;
+  });
+  const l = u.concat(a).join(`
+`), t = [
+    "declare module 'pure-glyf/icons' {",
+    "    export function mount(): void;",
+    "    export const sheet: string;",
+    "    export function onInject(callback: (css: string) => void): void;"
+  ];
+  n.forEach((s) => {
+    t.push(`    export const ${s.name}: string;`);
+  }), t.push("}");
+  const f = t.join(`
+`);
+  return { code: l, css: i, dts: f };
+}
+function _(c) {
+  const r = "pure-glyf/icons", n = "\0" + r, u = "pure-glyf/icons.css", i = "\0" + u, a = c.dts || "pure-glyf.d.ts";
+  let l = null, t = null, f = !1;
+  function s() {
+    try {
+      if (l = P(c.icons, f), p.writeFileSync(d.resolve(process.cwd(), a), l.dts), t) {
+        const e = t.moduleGraph.getModuleById(n);
+        e && (t.moduleGraph.invalidateModule(e), t.ws.send({
+          type: "full-reload",
+          path: "*"
+        }));
+      }
+    } catch (e) {
+      console.error("[pure-glyf] Generation failed:", e);
+    }
+  }
+  return {
+    name: "vite-plugin-pure-glyf",
+    enforce: "pre",
+    configResolved(e) {
+      f = e.command === "serve";
+    },
+    configureServer(e) {
+      t = e, Object.values(c.icons).forEach((o) => {
+        t == null || t.watcher.add(d.resolve(o));
+      }), t == null || t.watcher.on("change", (o) => {
+        o.endsWith(".svg") && s();
+      }), t == null || t.watcher.on("add", (o) => {
+        o.endsWith(".svg") && s();
+      }), t == null || t.watcher.on("unlink", (o) => {
+        o.endsWith(".svg") && s();
+      });
+    },
+    buildStart() {
+      s();
+    },
+    resolveId(e) {
+      if (e === r)
+        return n;
+      if (e === u)
+        return i;
+    },
+    load(e) {
+      if (e === n)
+        return l.code;
+      if (e === i)
+        return l.css;
+    }
+  };
+}
+export {
+  _ as pureGlyfPlugin
+};

package/package.json

@@ -0,0 +1,61 @@
+{
+	"name": "pure-glyf",
+	"version": "0.1.0",
+	"description": "Vite plugin and runtime for compiling SVGs into tree-shakeable CSS masks",
+	"type": "module",
+	"keywords": [
+		"icons",
+		"svg",
+		"css",
+		"tree-shaking",
+		"vite-plugin"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/eddow/pure-glyf.git"
+	},
+	"bugs": {
+		"url": "https://github.com/eddow/pure-glyf/issues"
+	},
+	"homepage": "https://github.com/eddow/pure-glyf#readme",
+	"author": "eddow <eddow@ownk.com>",
+	"sideEffects": false,
+	"main": "./dist/index.cjs",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"require": "./dist/index.cjs"
+		},
+		"./plugin": {
+			"types": "./dist/plugin.d.ts",
+			"import": "./dist/plugin.js",
+			"require": "./dist/plugin.cjs"
+		},
+		"./inject": {
+			"types": "./dist/inject.d.ts",
+			"import": "./dist/inject.js",
+			"require": "./dist/inject.cjs"
+		}
+	},
+	"files": [
+		"dist"
+	],
+	"scripts": {
+		"dev": "vite",
+		"build": "vite build && tsc --emitDeclarationOnly",
+		"build:watch": "vite build --watch",
+		"preview": "vite preview"
+	},
+	"devDependencies": {
+		"@types/node": "^25.0.9",
+		"tsx": "^4.21.0",
+		"typescript": "^5.7.0",
+		"vite": "^6.0.0",
+		"vite-plugin-dts": "^4.0.0"
+	},
+	"license": "MIT",
+	"packageManager": "pnpm@10.7.1+sha512.2d92c86b7928dc8284f53494fb4201f983da65f0fb4f0d40baafa5cf628fa31dae3e5968f12466f17df7e97310e30f343a648baea1b9b350685dafafffdf5808"
+}