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

package/README.md

@@ -5,13 +5,13 @@ A Vite plugin that builds SVG sprite sheets from a directory of SVG files — wi
 ## 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 +46,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 +74,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 +82,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,7 +140,7 @@ 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
 

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@onedarnleyroad/vite-plugin-svg-sprite",
-  "version": "2.0.0-beta.6",
+  "version": "2.0.0-beta.8",
   "description": "Vite plugin that builds an SVG sprite sheet from a directory of SVG files",
   "type": "module",
   "exports": {
     ".": "./src/index.js"
   },
+  "scripts": {},
   "files": [
     "src"
   ],
@@ -18,6 +19,9 @@
   ],
   "author": "One Darnley Road <hello@onedarnleyroad.com>",
   "license": "MIT",
+  "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.`
+                        )
+                    }
+                }
             }
         },