@onedarnleyroad/vite-plugin-svg-sprite 2.0.0-beta.6 → 2.0.0

package/README.md

@@ -1,17 +1,20 @@
 # @onedarnleyroad/vite-plugin-svg-sprite
 
-A Vite plugin that builds SVG sprite sheets from a directory of SVG files — with content-hashed filenames and full Vite manifest integration.
+[![npm](https://img.shields.io/npm/v/@onedarnleyroad/vite-plugin-svg-sprite)](https://www.npmjs.com/package/@onedarnleyroad/vite-plugin-svg-sprite)
+[![license](https://img.shields.io/npm/l/@onedarnleyroad/vite-plugin-svg-sprite)](./LICENSE)
+
+A Vite plugin that builds **content-hashed SVG sprite sheets** at build time and registers them in **Vite's manifest** — built for server-rendered apps like **Craft CMS** (via [nystudio107's Vite plugin](https://nystudio107.com/docs/vite/)), and works with any manifest consumer. Organise icons into folders to get one sprite per folder, and reference them from templates with no JavaScript.
 
 ## Features
 
 - Combines individual SVGs into a single `<svg>` sprite with `<symbol>` elements
-- **Content-hashed output** (e.g. `sprite-DAskUDYW.svg`) so browsers never serve stale sprites
+- **Content-hashed output** (e.g. `sprite-9a3f2c1e.svg`) so browsers never serve stale sprites
 - **Vite manifest integration** — works out of the box with [nystudio107's Craft Vite plugin](https://nystudio107.com/docs/vite/) and any other manifest consumer
 - **Multiple sprites from subfolders** — organise icons into `light/`, `dark/`, etc. and get one sprite per folder
 - Namespaces internal IDs to prevent conflicts across icons
-- **Preserves outer `<svg>` attributes** on the generated `<symbol>` — `fill="currentColor"`, `stroke`, `class`, `role`, `aria-*`, `data-*`, `style` (including CSS custom properties), etc. Only the truly wrapper-specific attributes are stripped: `xmlns`, `version`, `width`, `height`, and `id` (we set our own).
-- Preserves existing `<title>` elements, or falls back to the filename
-- Strips comments and empty `<defs>` blocks
+- **Preserves outer `<svg>` attributes** on the generated `<symbol>` — `fill="currentColor"`, `stroke`, `class`, `role`, `aria-*`, `data-*`, `style` (including CSS custom properties), etc. Only the truly wrapper-specific attributes are stripped: `xmlns` (and `xmlns:*` namespace declarations such as `xmlns:xlink`), `version`, `width`, `height`, and `id` (we set our own).
+- Preserves an existing `<title>`, or synthesizes one from the filename (`arrow.svg` → `arrow icon`)
+- Strips comments, XML prolog / DOCTYPE declarations, and empty `<defs>` blocks
 
 ## Installation
 
@@ -46,7 +49,7 @@ export default defineConfig({
 | `outputDir` | `string` | `'assets'` | Output directory, relative to Vite's `build.outDir`.                         |
 | `prefix`    | `string` | `'sprite'` | Filename prefix. The dash between prefix and folder name is always added. |
 
-All paths are resolved relative to the project root.
+`inputDir` is resolved relative to the project root; `outputDir` is resolved relative to Vite's `build.outDir`.
 
 ## Subfolders
 
@@ -74,7 +77,7 @@ Each SVG becomes a `<symbol>` with `id="svg-{filename}"`. For example, `arrow.sv
 ```html
 <symbol id="svg-arrow" viewBox="0 0 24 24">
   <title>arrow icon</title>
-  <!-- ... -->
+  <path d="…"/>
 </symbol>
 ```
 
@@ -82,29 +85,56 @@ Each SVG becomes a `<symbol>` with `id="svg-{filename}"`. For example, `arrow.sv
 
 ### With Vite manifest (recommended)
 
-With `build.manifest: true` enabled, each sprite is registered in `manifest.json` keyed by its `inputDir`-relative path:
+With `build.manifest: true` enabled, each sprite is registered in `manifest.json` under a purely logical key — the root sprite is `{prefix}.svg`, and each subfolder sprite is `{prefix}-{folder}.svg`:
 
 ```json
 {
-  "src/icons/sprite.svg":       { "file": "assets/sprite-DAskUDYW.svg",       "src": "src/icons/sprite.svg",       "isEntry": false },
-  "src/icons/sprite-light.svg": { "file": "assets/sprite-light-xV7q1sYy.svg", "src": "src/icons/sprite-light.svg", "isEntry": false }
+  "sprite.svg":       { "file": "assets/sprite-9a3f2c1e.svg",       "src": "sprite.svg",       "isEntry": false },
+  "sprite-light.svg": { "file": "assets/sprite-light-4b8d70e5.svg", "src": "sprite-light.svg", "isEntry": false }
 }
 ```
 
+These keys don't correspond to real files on disk — they're the handle you pass to your manifest consumer.
+
 With Craft CMS + [nystudio107/craft-vite](https://nystudio107.com/docs/vite/):
 
 ```twig
 <svg aria-hidden="true">
-  <use href="{{ craft.vite.entry('src/icons/sprite.svg') }}#svg-arrow"></use>
+  <use href="{{ craft.vite.entry('sprite.svg') }}#svg-arrow"></use>
 </svg>
 
 <svg aria-hidden="true">
-  <use href="{{ craft.vite.entry('src/icons/sprite-light.svg') }}#svg-sun"></use>
+  <use href="{{ craft.vite.entry('sprite-light.svg') }}#svg-sun"></use>
 </svg>
 ```
 
 `entry()` resolves the hashed URL from the manifest.
 
+#### A reusable, accessible macro
+
+Rather than hand-writing the `<svg><use>` wrapper each time, wrap it in a Twig macro. Pass `folder:` for a subfolder sprite — it maps to the `sprite-{folder}.svg` manifest key for you, so templates keep the folder mental model. Icons default to decorative (`aria-hidden="true"`), and switch to a labelled `role="img"` when the icon carries meaning on its own:
+
+```twig
+{% macro icon(name, folder = null, label = null, prefix = 'sprite', class = 'icon', extra = {}) %}
+  {% set key  = folder ? "#{prefix}-#{folder}.svg" : "#{prefix}.svg" %}
+  {% set a11y = label
+    ? { role: 'img', 'aria-label': label }
+    : { 'aria-hidden': 'true', focusable: 'false' } %}
+  <svg{{ attr({ class: class }|merge(a11y)|merge(extra)) }}>
+    <use href="{{ craft.vite.entry(key) }}#svg-{{ name }}"></use>
+  </svg>
+{% endmacro %}
+```
+
+```twig
+{{ icon('arrow') }}                                   {# root sprite → entry('sprite.svg') #}
+{{ icon('sun', folder: 'light') }}                    {# subfolder → entry('sprite-light.svg') #}
+{{ icon('search', label: 'Search') }}                 {# meaningful → role="img" + aria-label #}
+<button aria-label="Close">{{ icon('x') }}</button>   {# icon-only control: label the button #}
+```
+
+Reach for `aria-hidden="true"` only when the icon is decorative — i.e. sitting next to visible text. A standalone, meaning-bearing icon needs an accessible name (via `label`, or on the enclosing control such as a button), or it's invisible to assistive tech. (`attr()` is Craft's built-in attribute renderer.)
+
 ## Development workflow
 
 Sprites are generated at build time only — the plugin does **not** run during `vite dev`. For a live-ish dev loop, run a separate build watcher alongside your usual dev server:
@@ -113,11 +143,11 @@ Sprites are generated at build time only — the plugin does **not** run during
 vite build --watch
 ```
 
-Every edit under `inputDir` triggers a rebuild (a second or two), updates `manifest.json` with the new content hash, and `craft.vite.entry('src/icons/sprite.svg')` picks up the new URL on the next request. Not instant HMR, but avoids the CORS / cross-origin complications of trying to serve sprites through a separate dev port.
+Every edit under `inputDir` triggers a rebuild (a second or two), updates `manifest.json` with the new content hash, and `craft.vite.entry('sprite.svg')` picks up the new URL on the next request. Not instant HMR, but avoids the CORS / cross-origin complications of trying to serve sprites through a separate dev port.
 
 ### Without manifest
 
-You can reference the sprite directly if you don't use a manifest — but the filename will be hashed, so you'd need to read the hash yourself or disable hashing manually. The manifest-based flow is strongly recommended.
+You can reference a sprite file directly without a manifest, but its filename is always content-hashed — there's no option to turn hashing off — so you'd have to discover the emitted name yourself (e.g. by globbing `assets/sprite-*.svg`). The manifest-based flow is strongly recommended.
 
 ## Migrating from v1
 
@@ -140,6 +170,32 @@ svgSprite({
 
 Passing `outputFile` in v2 throws an error. Update your templates to read the sprite URL from Vite's manifest instead of hard-coding the path.
 
+## How this differs from other SVG sprite plugins
+
+Several Vite plugins generate SVG sprites; they mostly split by *how the sprite reaches the page*:
+
+- **Runtime injection** (e.g. [`vite-plugin-svg-icons`](https://github.com/vbenjs/vite-plugin-svg-icons)) injects the sprite into the DOM via a virtual import. Great for SPAs; needs JavaScript to run.
+- **Import-based** plugins expose each icon as a JS module or framework component. Great when your icons live in JS/JSX.
+- **This plugin is build-time and manifest-driven.** It emits content-hashed `.svg` files and registers them in Vite's manifest under stable logical keys, so a **server-rendered** template (Craft/Twig, Laravel/Blade, etc.) resolves the hashed URL with no JavaScript — e.g. `craft.vite.entry('sprite.svg')`. It also emits one sprite per subfolder.
+
+If you want runtime/HMR injection or a virtual import, one of the others will suit you better. If you render HTML on the server and resolve assets through a Vite manifest, this is built for that.
+
+## FAQ
+
+**Does it work with Craft CMS?** Yes — it's the primary target. With [nystudio107's Craft Vite plugin](https://nystudio107.com/docs/vite/), reference a sprite with `craft.vite.entry('sprite.svg')` (see [Using the sprite](#using-the-sprite)).
+
+**How do I reference an icon in a Twig template?** Use `<use href="{{ craft.vite.entry('sprite.svg') }}#svg-{name}">`, or the reusable [`icon()` macro](#a-reusable-accessible-macro).
+
+**Can I have more than one sprite?** Yes — each subfolder of `inputDir` becomes its own sprite, keyed `sprite-{folder}.svg`. See [Subfolders](#subfolders).
+
+**Can two icons share a filename across folders?** Yes. `arrow.svg` and `brand/arrow.svg` both become `<symbol id="svg-arrow">`, but in *separate* sprite files — and you reference each by its own sprite URL (`entry('sprite.svg')#svg-arrow` vs `entry('sprite-brand.svg')#svg-arrow`), so the file URL disambiguates them and they render fine on the same page. The ids only repeat *across* files, never within one; the only thing to avoid is inlining multiple sprites into a single document and referencing by bare `#svg-arrow`.
+
+**Does it run during `vite dev` / support HMR?** No — it's build-only. Run `vite build --watch` alongside your dev server for a live-ish loop.
+
+**Does it optimise SVGs?** No — it does light cleanup (strips the XML prolog / comments / empty `<defs>`, collapses whitespace, namespaces IDs), but it doesn't touch path data, so bring source SVGs that are already production-ready. Each icon needs a `viewBox` — the plugin strips `width`/`height` and scales from it.
+
+**Why are the manifest keys `sprite.svg` and `sprite-light.svg`, not paths?** Because nystudio107's `entry()` resolves keys with a substring match, and a path-style `light/sprite.svg` would collide with the root `sprite.svg`. Basename keys avoid that.
+
 ## License
 
 MIT © [One Darnley Road](https://onedarnleyroad.com)

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@onedarnleyroad/vite-plugin-svg-sprite",
-  "version": "2.0.0-beta.6",
+  "version": "2.0.0",
   "description": "Vite plugin that builds an SVG sprite sheet from a directory of SVG files",
   "type": "module",
   "exports": {
     ".": "./src/index.js"
   },
+  "scripts": {},
   "files": [
     "src"
   ],
@@ -14,10 +15,24 @@
     "vite-plugin",
     "svg",
     "sprite",
-    "svg-sprite"
+    "svg-sprite",
+    "svg-symbols",
+    "icons",
+    "manifest",
+    "craft-cms",
+    "nystudio107"
   ],
   "author": "One Darnley Road <hello@onedarnleyroad.com>",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/onedarnleyroad/vite-plugin-svg-sprite.git"
+  },
+  "homepage": "https://github.com/onedarnleyroad/vite-plugin-svg-sprite#readme",
+  "bugs": "https://github.com/onedarnleyroad/vite-plugin-svg-sprite/issues",
+  "publishConfig": {
+    "access": "public"
+  },
   "peerDependencies": {
     "vite": ">=4.0.0"
   }

package/src/index.js

@@ -9,13 +9,13 @@ function hashContent(content) {
 const STRIP_ATTRS = new Set(['xmlns', 'version', 'width', 'height', 'id'])
 
 function extractOuterAttrs(openTag) {
-    const attrRe = /\s+([a-zA-Z_][a-zA-Z0-9_:-]*)="([^"]*)"/g
+    const attrRe = /\s+([a-zA-Z_][a-zA-Z0-9_:-]*)=(["'])([\s\S]*?)\2/g
     const kept = []
     let m
     while ((m = attrRe.exec(openTag)) !== null) {
-        const [, attr, value] = m
+        const [, attr, quote, value] = m
         if (STRIP_ATTRS.has(attr) || attr.startsWith('xmlns:')) continue
-        kept.push(`${attr}="${value}"`)
+        kept.push(`${attr}=${quote}${value}${quote}`)
     }
     return kept.join(' ')
 }
@@ -25,15 +25,16 @@ function buildSymbol(svg, name) {
     const title = existingTitle ?? `${name} icon`
 
     const cleaned = svg
+        .replace(/<\?xml[\s\S]*?\?>/gi, '')
+        .replace(/<!DOCTYPE[^>]*>/gi, '')
         .replace(/<!--[\s\S]*?-->/g, '')
         .replace(/<title[^>]*>[\s\S]*?<\/title>/gi, '')
         .replace(/<defs[^>]*>\s*<\/defs>/gi, '')
 
     const namespaced = cleaned
-        .replace(/\bid="([^"]+)"/g, `id="${name}-$1"`)
+        .replace(/(?<![\w-])id=(["'])([^"']+)\1/g, (_, q, v) => `id=${q}${name}-${v}${q}`)
         .replace(/\burl\(#([^)]+)\)/g, `url(#${name}-$1)`)
-        .replace(/\bhref="#([^"]+)"/g, `href="#${name}-$1"`)
-        .replace(/\bxlink:href="#([^"]+)"/g, `xlink:href="#${name}-$1"`)
+        .replace(/\b(xlink:href|href)=(["'])#([^"']+)\2/g, (_, attr, q, v) => `${attr}=${q}#${name}-${v}${q}`)
 
     const openTag = namespaced.match(/<svg\b[^>]*>/i)?.[0] ?? ''
     const outerAttrs = extractOuterAttrs(openTag)
@@ -68,7 +69,11 @@ function collectSpriteGroups(inputDir, prefix) {
         .filter(e => e.isFile() && e.name.toLowerCase().endsWith('.svg'))
         .map(e => e.name)
     if (rootFiles.length > 0) {
-        groups.push({ logicalName: `${prefix}.svg`, dir: absInput, files: rootFiles })
+        groups.push({
+            fileBase: prefix,
+            dir: absInput,
+            files: rootFiles,
+        })
     }
 
     for (const entry of entries) {
@@ -78,7 +83,11 @@ function collectSpriteGroups(inputDir, prefix) {
             .filter(e => e.isFile() && e.name.toLowerCase().endsWith('.svg'))
             .map(e => e.name)
         if (subFiles.length === 0) continue
-        groups.push({ logicalName: `${prefix}-${entry.name}.svg`, dir: subDir, files: subFiles })
+        groups.push({
+            fileBase: `${prefix}-${entry.name}`,
+            dir: subDir,
+            files: subFiles,
+        })
     }
 
     return groups
@@ -111,11 +120,22 @@ export default function svgSpritePlugin(options = {}) {
             emitted.length = 0
             for (const group of collectSpriteGroups(inputDir, prefix)) {
                 const source = buildSpriteSvg(group.dir, group.files)
-                const base = group.logicalName.replace(/\.svg$/, '')
-                const hashedFileName = join(outputDir, `${base}-${hashContent(source)}.svg`)
-                const key = join(inputDir, group.logicalName)
+                const hashedFileName = join(outputDir, `${group.fileBase}-${hashContent(source)}.svg`)
                 this.emitFile({ type: 'asset', fileName: hashedFileName, source })
-                emitted.push({ key, fileName: hashedFileName })
+                emitted.push({ key: `${group.fileBase}.svg`, fileName: hashedFileName })
+            }
+            // craft-vite resolves manifest keys with a first-hit substring test: if one key is a
+            // substring of another, entry() for the shorter key resolves ambiguously. Basename keys
+            // (sprite.svg, sprite-detail.svg) avoid this; warn if a prefix/folder name reintroduces it.
+            for (const a of emitted) {
+                for (const b of emitted) {
+                    if (a !== b && b.key.includes(a.key)) {
+                        this.warn(
+                            `[vite-plugin-svg-sprite] manifest key "${a.key}" is a substring of "${b.key}"; ` +
+                            `craft.vite.entry('${a.key}') may resolve ambiguously. Rename the prefix or folder to disambiguate.`
+                        )
+                    }
+                }
             }
         },