gulp-stacksvg 2.0.3 → 4.0.0

package/LICENSE.md

@@ -1,7 +1,7 @@
 # MIT License
 
-Copyright © 2022-2023 Sergey Artemov <firefoxic.dev@gmail.com>
-Copyright © 2014–2021 Andrey Kuzmin <unsoundscapes@gmail.com>
+Copyright © Sergey Artemov <firefoxic.dev@gmail.com>, 2022
+Copyright © Andrey Kuzmin <unsoundscapes@gmail.com>, 2014
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

package/README.md

@@ -1,71 +1,63 @@
 <!-- markdownlint-disable MD007 -->
 # gulp-stacksvg
 
-[![Test Status][test-image]][test-url]
 [![License: MIT][license-image]][license-url]
+[![Changelog][changelog-image]][changelog-url]
 [![NPM version][npm-image]][npm-url]
-[![Vulnerabilities count][vulnerabilities-image]][vulnerabilities-url]
+[![Test Status][test-image]][test-url]
 
-The gulp plugin to combine svg files into one using the stack method.
+The gulp plugin to combine svg files into one using the stack method.
 
 ## Installation
 
 ```shell
-npm install gulp-stacksvg --save-dev
+pnpm add -D gulp gulp-stacksvg
 ```
 
 ## Usage
 
-The following script will combine all SVG sources into a single SVG file with stack method.
+Add the following to your `gulpfile.js`:
 
 ```js
 import { stacksvg } from "gulp-stacksvg"
-import gulp from "gulp"
-
-const { src, dest } = gulp
+import { dest, src } from "gulp"
 
-function makeStack () {
-	return src(`./src/icons/**/*.svg`)
-		.pipe(stacksvg({ output: `sprite` }))
-		.pipe(dest(`./dest/icons`))
+export function createStack () {
+	return src(`./src/shared/icons/**/*.svg`)
+		.pipe(stacksvg())
+		.pipe(dest(`./dist/shared/icons`))
 }
 ```
 
-### Available options
+To combine all icons from `./src/shared/icons/` into the `./dist/shared/icons/stack.svg` run:
 
-| Option      | Description                                                                          | Default |
-|-------------|--------------------------------------------------------------------------------------|---------|
-| `output`    | Sets the stack file name. Accepts values ​both with and without the `.svg` extension. | `stack` |
-| `separator` | Replaces the directory separator for the `id` attribute.                             | `_`     |
-| `spacer`    | Joins space-separated words for the `id` attribute.                                  | `-`     |
-
-### Inlining stacksvg result into markup
-
-You just don't have to want it.
+```shell
+pnpm exec gulp createStack
+```
 
-## Why a stack?
+## Why a stack?
 
-Unlike all other methods for assembling a sprite, the stack does not limit us in choosing how to insert a vector into a page. Take a look at [the results](https://demos.frontend-design.ru/sprite/src/) of different ways to display fragments of different types of sprites.
+Unlike all other methods for assembling a sprite, the stack does not limit us in choosing how to insert a vector into a page. Take a look at [the results](https://demos.frontend-design.ru/sprite/src/) of different ways to display fragments of different types of sprites.
 
-We can use the stack in all four possible ways:
+We can use the stack in all four possible ways:
 
-- in markup:
+- in markup:
 
-	- in `src` of `img` tag — static,
-	- in the `href` of the `use` tag — with the possibility of repainting,
+	- in `src` of `img` tag — static,
+	- in the `href` of the `use` tag — with the possibility of repainting,
 
-- in styles:
+- in styles:
 
-	- in `url()` properties `background` — static,
-	- in `url()` properties `mask` — with the possibility of repainting.
+	- in `url()` properties `background` — static,
+	- in `url()` properties `mask` — with the possibility of repainting.
 
-[Demo page](https://firefoxic.github.io/gulp-stacksvg/example/) to prove it.
+[Demo page](https://firefoxic.github.io/gulp-stacksvg/example/) to prove it.
 
-## Stack under the hood
+## Stack under the hood
 
-This method was first mentioned in a Simurai [article](https://simurai.com/blog/2012/04/02/svg-stacks) on April 2, 2012. But even it uses unnecessarily complex code transformations.
+This method was first mentioned in a Simurai [article](https://simurai.com/blog/2012/04/02/svg-stacks) on April 2, 2012. But even it uses unnecessarily complex code transformations.
 
-This can be done much easier. In general, the stack is arranged almost like a symbol sprite, but without changing the icon tag (it remains the `svg` tag, as in the original icon files) and with the addition of a tiny bit of style.
+This can be done much easier. In general, the stack is arranged almost like a symbol sprite, but without changing the icon tag (it remains the `svg` tag, as in the original icon files) and with the addition of a tiny bit of style.
 
 ```xml
 <svg xmlns="http://www.w3.org/2000/svg">
@@ -101,13 +93,13 @@ This can be done much easier. In general, the stack is arranged almost like a sy
 </svg>
 ```
 
-The magic is in the stack inner style, which shows only the fragment requested by the link, hiding everything else:
+The magic is in the stack inner style, which shows only the fragment requested by the link, hiding everything else:
 
 ```css
 :root svg:not(:target) { display: none }
 ```
 
-And now the icons from the external sprite are available in the styles <img width="16" height="16" title="heart" src="https://raw.githubusercontent.com/firefoxic/gulp-stacksvg/main/docs/example/stack.svg#heart-red" alt="heart">
+And now the icons from the external sprite are available in the styles <img width="16" height="16" title="heart" src="https://raw.githubusercontent.com/firefoxic/gulp-stacksvg/main/docs/example/stack.svg#heart-red" alt="heart">
 
 ```html
 <button class="button button--icon_heart" type="button">
@@ -120,46 +112,41 @@ And now the icons from the external sprite are available in the styles <img widt
 	display: inline-flex;
 	align-items: center;
 	gap: 0.5em;
-}
 
-.button--icon_heart {
-	--icon: url("../icons/stack.svg#heart");
-}
-
-.button:hover {
-	--fill: red;
-}
-
-.button::before {
-	content: "";
-	width: 1em;
-	height: 1em;
-	/* icon shape */
-	mask: var(--icon) no-repeat center / contain;
-	/* icon color */
-	background: var(--fill, orangered);
+	&:hover {
+		--fill: red;
+	}
+
+	&::before {
+		content: "";
+		width: 1em;
+		height: 1em;
+		/* icon shape */
+		mask: var(--icon) no-repeat center / contain;
+		/* icon color */
+		background: var(--fill, orangered);
+	}
+
+	&:where(.button--icon_heart) {
+		--icon: url("../icons/stack.svg#heart");
+	}
 }
 ```
 
-> ⚠️ Note:
-> We still need the [autoprefixer](https://github.com/postcss/autoprefixer) for the mask property.
-
-For an icon inserted via `mask`, simply change the `background`. Moreover, unlike `use`, you can draw anything in the background under the mask, for example, a gradient.
+For an icon inserted via `mask`, simply change the `background`. Moreover, unlike `use`, you can draw anything in the background under the mask, for example, a gradient.
 
-## Useful links
+## More info
 
-- [Changelog](CHANGELOG.md)
-- [License](LICENSE)
 - [SVG sprites: old-school, modern, unknown, and forgotten](https://pepelsbey.dev/articles/svg-sprites/#forgotten-stacks) by [Vadim Makeev](https://mastodon.social/@pepelsbey)
 
-[test-url]: https://github.com/firefoxic/gulp-stacksvg/actions
-[test-image]: https://github.com/firefoxic/gulp-stacksvg/actions/workflows/test.yml/badge.svg?branch=main
+[license-url]: https://github.com/firefoxic/gulp-stacksvg/blob/main/LICENSE.md
+[license-image]: https://img.shields.io/badge/License-MIT-limegreen.svg
 
-[npm-url]: https://www.npmjs.com/package/gulp-stacksvg
-[npm-image]: https://badge.fury.io/js/gulp-stacksvg.svg
+[changelog-url]: https://github.com/firefoxic/gulp-stacksvg/blob/main/CHANGELOG.md
+[changelog-image]: https://img.shields.io/badge/CHANGELOG-md-limegreen
 
-[license-url]: https://github.com/firefoxic/gulp-stacksvg/blob/main/LICENSE
-[license-image]: https://img.shields.io/badge/License-MIT-limegreen.svg
+[npm-url]: https://npmjs.com/package/gulp-stacksvg
+[npm-image]: https://badge.fury.io/js/gulp-stacksvg.svg
 
-[vulnerabilities-url]: https://snyk.io/test/github/firefoxic/gulp-stacksvg
-[vulnerabilities-image]: https://snyk.io/test/github/firefoxic/gulp-stacksvg/badge.svg
+[test-url]: https://github.com/firefoxic/gulp-stacksvg/actions
+[test-image]: https://github.com/firefoxic/gulp-stacksvg/actions/workflows/test.yml/badge.svg?branch=main

package/lib/index.js

@@ -1,6 +1,6 @@
-import { basename, extname, sep } from "node:path"
-import { Transform } from "node:stream"
 import { createHmac } from "node:crypto"
+import { Transform } from "node:stream"
+import { basename, extname, sep } from "node:path"
 
 import { parse } from "node-html-parser"
 import PluginError from "plugin-error"
@@ -19,17 +19,11 @@ const excessAttrs = [
 const xlink = `http://www.w3.org/1999/xlink`
 
 /**
- * Combine svg files into one using the stack method.
- *
- * @param {Object} [options] - The option object.
- * @param {string} [options.output=stack] - The name of the output file.
- * @param {string} [options.separator=_] - The symbol that will replace the directory separator for the fragment id.
- * @param {string} [options.spacer=-] - The character that will replace the whitespace characters for the fragment id.
+ * Gulp plugin for combining SVG icons into a single file.
  *
- * @returns {Object} A stream containing a stack of svg icons.
+ * @exports {function} stacksvg - Gulp plugin.
  */
-export function stacksvg ( { output = `stack`, separator = `_`, spacer = `-` } = {}) {
-
+export function stacksvg () {
 	let isEmpty = true
 	const ids = {}
 	const namespaces = new Map([[`http://www.w3.org/2000/svg`, `xmlns`]])
@@ -37,8 +31,14 @@ export function stacksvg ( { output = `stack`, separator = `_`, spacer = `-` } =
 	const rootSvg = stack.querySelector(`svg`)
 	const stream = new Transform({ objectMode: true })
 
+	/**
+	 * Transform function for the plugin.
+	 *
+	 * @param {Vinyl} file - Gulp file object.
+	 * @param {string} [enc=null] - Encoding to use when writing the file.
+	 * @param {function} cb - Callback function.
+	 */
 	function transform (file, _, cb) {
-
 		if (file.isStream()) {
 			return cb(new PluginError(`gulp-stacksvg`, `Streams are not supported!`))
 		}
@@ -53,7 +53,7 @@ export function stacksvg ( { output = `stack`, separator = `_`, spacer = `-` } =
 		isEmpty = false
 
 		const iconId = basename(
-			file.relative.split(sep).join(separator).replace(/\s/g, spacer),
+			file.relative.split(sep).join(`_`).replace(/\s/g, `-`),
 			extname(file.relative),
 		)
 
@@ -75,16 +75,30 @@ export function stacksvg ( { output = `stack`, separator = `_`, spacer = `-` } =
 		excessAttrs.forEach((attr) => iconSvg.removeAttribute(attr))
 		iconSvg.querySelectorAll(`[id]`).forEach(changeInnerId)
 
+		/**
+		 * Update the id of a child element if it has the same id.
+		 *
+		 * @param {Element} targetElem - Child element to update.
+		 * @param {string} suffix - Suffix to append to the id.
+		 */
 		function changeInnerId (targetElem, suffix) {
 			let oldId = targetElem.id
 			let newId = `${iconId}_${suffix}`
+
 			targetElem.setAttribute(`id`, newId)
 			iconSvg.querySelectorAll(`*`).forEach(updateUsingId)
 
+			/**
+			 * Update the id of a child element if it has the same id.
+			 *
+			 * @param {Element} elem - Child element to update.
+			 */
 			function updateUsingId (elem) {
 				if (~elem.rawAttrs.search(`#${oldId}`)) {
+					// eslint-disable-next-line guard-for-in
 					for (let attr in elem._attrs) {
 						let attrValue = elem._attrs[attr].replace(`#${oldId}`, `#${newId}`)
+
 						elem.setAttribute(attr, attrValue)
 					}
 				}
@@ -98,6 +112,7 @@ export function stacksvg ( { output = `stack`, separator = `_`, spacer = `-` } =
 				let nsId = attrs[attrName]
 				let oldNsAlias = attrName.slice(6)
 				let newNsAlias = oldNsAlias
+
 				if (namespaces.has(nsId)) {
 					if (namespaces.get(nsId) !== attrName) {
 						newNsAlias = namespaces.get(nsId).slice(6)
@@ -114,13 +129,14 @@ export function stacksvg ( { output = `stack`, separator = `_`, spacer = `-` } =
 							break
 						}
 					}
+
 					iconDom.querySelectorAll(`*`).some((elem) => {
 						if (
 							elem.rawTagName.startsWith(`${newNsAlias}:`)
-							||
-							Object.keys(elem._attrs).some((attr) => attr.startsWith(`${newNsAlias}:`))
+							|| Object.keys(elem._attrs).some((attr) => attr.startsWith(`${newNsAlias}:`))
 						) {
 							namespaces.set(nsId, `xmlns:${newNsAlias}`)
+
 							return true
 						}
 					})
@@ -131,9 +147,15 @@ export function stacksvg ( { output = `stack`, separator = `_`, spacer = `-` } =
 		}
 
 		rootSvg.appendChild(iconSvg)
+
 		cb()
 	}
 
+	/**
+	 * Flush function for the plugin.
+	 *
+	 * @param {function} cb - Callback function.
+	 */
 	function flush (cb) {
 		if (isEmpty) {
 			return cb()
@@ -143,11 +165,10 @@ export function stacksvg ( { output = `stack`, separator = `_`, spacer = `-` } =
 			rootSvg.setAttribute(nsAttr, nsId)
 		}
 
-		output = output.endsWith(`.svg`) ? output : `${output}.svg`
-
-		const file = new Vinyl({ path: output, contents: Buffer.from(stack.toString()) })
+		const file = new Vinyl({ path: `stack.svg`, contents: Buffer.from(stack.toString()) })
 
 		this.push(file)
+
 		cb()
 	}
 
@@ -158,18 +179,20 @@ export function stacksvg ( { output = `stack`, separator = `_`, spacer = `-` } =
 }
 
 /**
- * Change the old namespace alias to the new one for the elements and attributes of the icon.
+ * Changes the namespace alias of an element and all its children.
  *
- * @param {object} iconDom - The DOM of the icon.
- * @param {string} oldAlias - The old namespace alias.
- * @param {string} newAlias - The new namespace alias.
+ * @param {Element} iconDom - Element to modify.
+ * @param {string} oldAlias - Old namespace alias to replace.
+ * @param {string} newAlias - New namespace alias.
  */
 function changeNsAlias (iconDom, oldAlias, newAlias) {
 	iconDom.querySelectorAll(`*`).forEach((elem) => {
 		let prefix = newAlias === `` ? `` : `${newAlias}:`
+
 		if (elem.rawTagName.startsWith(`${oldAlias}:`)) {
 			elem.rawTagName = `${prefix}${elem.rawTagName.slice((oldAlias.length + 1))}`
 		}
+
 		for (let name of Object.keys(elem._attrs)) {
 			if (name.startsWith(`${oldAlias}:`)) {
 				elem.setAttribute(`${prefix}${name.slice((oldAlias.length + 1))}`, elem._attrs[name])
@@ -180,11 +203,10 @@ function changeNsAlias (iconDom, oldAlias, newAlias) {
 }
 
 /**
- * Get the hash sum of the passed string.
- *
- * @param {string} str - An arbitrary line of code.
+ * Get a hash for a given string.
  *
- * @returns {string} The first 7 characters of the hash sum.
+ * @param {string} str - String to hash.
+ * @returns {string} Hash of the string.
  */
 function getHash (str) {
 	return createHmac(`sha1`, `xmlns`)

package/package.json

@@ -1,53 +1,55 @@
 {
   "name": "gulp-stacksvg",
-  "description": "The gulp plugin to combine svg files into one using the stack method.",
-  "version": "2.0.3",
-  "type": "module",
-  "exports": "./lib/index.js",
-  "files": [
-    "./lib/index.js"
-  ],
-  "dependencies": {
-    "node-html-parser": "^6.1.11",
-    "plugin-error": "^2.0.1",
-    "vinyl": "^3.0.0"
-  },
-  "engines": {
-    "node": "^16.20.0 || ^18.16.0"
-  },
+  "description": "The gulp plugin to combine svg files into one using the stack method.",
+  "version": "4.0.0",
   "license": "MIT",
   "author": {
     "name": "Sergey Artemov",
     "email": "firefoxic.dev@gmail.com"
   },
-  "homepage": "https://github.com/firefoxic/gulp-stacksvg",
+  "homepage": "https://github.com/firefoxic/gulp-stacksvg#readme",
   "bugs": {
     "url": "https://github.com/firefoxic/gulp-stacksvg/issues"
   },
   "repository": {
     "type": "git",
-    "url": "git://github.com/firefoxic/gulp-stacksvg"
+    "url": "git://github.com/firefoxic/gulp-stacksvg.git"
+  },
+  "type": "module",
+  "exports": "./lib/index.js",
+  "files": [
+    "./lib/"
+  ],
+  "engines": {
+    "node": "^18.18.2 || ^20.9.0"
+  },
+  "dependencies": {
+    "node-html-parser": "^6.1.13",
+    "plugin-error": "^2.0.1",
+    "vinyl": "^3.0.0"
+  },
+  "devDependencies": {
+    "@firefoxic/eslint-config": "^1.0.0",
+    "@firefoxic/update-changelog": "^0.1.0",
+    "eslint": "^9.2.0",
+    "gulp": "^5.0.0",
+    "husky": "^9.0.11"
   },
   "keywords": [
+    "gulp",
     "gulpplugin",
     "svg",
     "icon",
+    "sprite",
     "stack",
-    "sprite"
+    "vector"
   ],
-  "devDependencies": {
-    "editorconfig-checker": "^5.1.1",
-    "eslint": "^8.52.0",
-    "gulp": "^4.0.2",
-    "husky": "^8.0.3"
-  },
   "scripts": {
-    "lint:ec": "ec",
-    "lint:es": "eslint ./",
-    "lint": "pnpm /^lint:/",
+    "lint": "eslint",
     "test": "node --test",
     "pretest": "pnpm lint",
     "preversion": "pnpm test",
+    "version": "update-changelog && git add CHANGELOG.md",
     "postversion": "pnpm publish"
   }
 }