gulp-stacksvg 1.0.0

package/LICENSE

@@ -0,0 +1,11 @@
+MIT License
+===========
+
+Copyright 2022 Sergey Artemov <firefoxic.dev@gmail.com>
+Copyright 2014–2021 Andrey Kuzmin <unsoundscapes@gmail.com>
+
+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:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,144 @@
+# gulp-stacksvg
+
+<img align="right" width="130" height="175" title="SVG Superman" src="https://raw.githubusercontent.com/firefoxic/gulp-stacksvg/master/svg-superman.png">
+
+[![Test Status][test-image]][test-url]
+[![License: MIT][license-image]][license-url]
+[![NPM version][npm-image]][npm-url]
+[![Vulnerabilities count][vulnerabilities-image]][vulnerabilities-url]
+
+Combine svg files into one with stack method.
+Read more about this in [the Simurai article](https://simurai.com/blog/2012/04/02/svg-stacks).
+
+## Installation
+
+```shell
+npm install gulp-stacksvg --save-dev
+```
+
+### Avalable options
+
+| Option      | Description                                                                          | Default     |
+|-------------|--------------------------------------------------------------------------------------|-------------|
+| `output`    | Sets the stack file name. Accepts values ​​both with and without the `.svg` extension. | `stack.svg` |
+| `separator` | Replaces the directory separator for the `id` attribute.                             | `_`         |
+| `spacer`    | Joins space-separated words for the `id` attribute.                                  | `-`         |
+
+## Usage
+
+The following script will combine all svg sources into single svg file with stack method.
+
+```js
+import { stacksvg } from "gulp-stacksvg"
+import gulp from "gulp"
+
+const { src, dest } = gulp
+
+function makeStack () {
+	return src(`./src/icons/**/*.svg`)
+		.pipe(stacksvg())
+		.pipe(dest(`./dest/icons`))
+}
+```
+
+### Inlining stacksvg result into markup
+
+You just don't have to want it.
+
+### Editing id attributes
+
+If you need to add prefix to each id, please use [gulp-rename](https://github.com/hparra/gulp-rename):
+
+```js
+import { stacksvg } from "gulp-stacksvg"
+import rename from "gulp-rename"
+import gulp from "gulp"
+
+const { src, dest } = gulp
+
+function makeStack () {
+	return src(`./src/icons/**/*.svg`, { base: `src/icons` })
+		.pipe(rename({ prefix: `icon-` }))
+		.pipe(stacksvg())
+		.pipe(dest(`./dest/icons`))
+}
+```
+
+### Transform svg sources or combined svg
+
+To transform either svg sources or combined svg you may pipe your files through [gulp-cheerio](https://github.com/KenPowers/gulp-cheerio).
+
+An example below removes all fill attributes from svg sources before combining them.
+Please note that you have to set `xmlMode: true` to parse svgs as xml file.
+
+```js
+import { stacksvg } from "gulp-stacksvg"
+import cheerio from "gulp-cheerio"
+import gulp from "gulp"
+
+const { src, dest } = gulp
+
+function makeStack () {
+	return src(`./src/icons/**/*.svg`)
+		.pipe(cheerio({
+			run: ($) => {
+				$(`[fill]`).removeAttr(`fill`)
+			},
+			parserOptions: { xmlMode: true }
+		}))
+		.pipe(stacksvg())
+		.pipe(dest(`./dest/icons`))
+}
+```
+
+## Possible rendering issues with Clipping Paths in SVG
+
+If you're running into issues with SVGs not rendering correctly in some browsers (see issue #47), the issue might be that clipping paths might not have been properly intersected in the SVG file. There are currently three ways of fixing this issue:
+
+### Correcting the Clipping Path in the SVG
+
+If you have the source file, simply converting the clipping path to a nice coded shape will fix this issue. Select the object, open up the Pathfinder panel, and click the Intersect icon.
+
+### Editing the SVG Code
+
+If you don't have the source file or an SVG Editor (Adobe Illustrator etc.), you can manually edit the SVG code in the file. Wrapping the `<clipPath>` into a `<defs>` will fix this issue. Here's an example:
+
+```diff
+<defs>
+	<path d="M28.4 30.5l5.3 5c0-.1 7-6.9 7-6.9l-4-6.8-8.3 8.7z" id="a"/>
++	<clipPath id="b">
++		<use overflow="visible" href="#a"/>
++	</clipPath>
+</defs>
+-<clipPath id="b">
+-	<use overflow="visible" xlink:href="#a"/>
+-</clipPath>
+```
+
+Or you can go further and reduce the size by removing the `<use>` element, like this:
+
+```diff
+<defs>
+-	<path d="M28.4 30.5l5.3 5c0-.1 7-6.9 7-6.9l-4-6.8-8.3 8.7z" id="a"/>
+	<clipPath id="b">
+-		<use overflow="visible" href="#a"/>
++		<path d="M28.4 30.5l5.3 5c0-.1 7-6.9 7-6.9l-4-6.8-8.3 8.7z"/>
+	</clipPath>
+</defs>
+```
+
+### Using gulp-cheerio to automate this
+
+Another possible solution would be to write a transformation with [gulp-cheerio](https://github.com/KenPowers/gulp-cheerio). Check this issue <https://github.com/firefoxic/gulp-stacksvg/issues/98> for the instructions.
+
+[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
+
+[npm-url]: https://npmjs.org/package/gulp-stacksvg
+[npm-image]: https://badge.fury.io/js/gulp-stacksvg.svg
+
+[license-url]: https://github.com/firefoxic/gulp-stacksvg/blob/main/LICENSE
+[license-image]: https://img.shields.io/badge/License-MIT-limegreen.svg
+
+[vulnerabilities-url]: https://snyk.io/test/github/firefoxic/gulp-stacksvg
+[vulnerabilities-image]: https://snyk.io/test/github/firefoxic/gulp-stacksvg/badge.svg

package/index.js

@@ -0,0 +1,199 @@
+import { load } from "cheerio"
+import { basename, extname, sep } from "path"
+import { Transform } from "stream"
+import fancyLog from "fancy-log"
+import PluginError from "plugin-error"
+import Vinyl from "vinyl"
+
+const presentationAttributes = new Set([
+	`alignment-baseline`,
+	`baseline-shift`,
+	`clip-path`,
+	`clip-rule`,
+	`clip`,
+	`color-interpolation-filters`,
+	`color-interpolation`,
+	`color-profile`,
+	`color-rendering`,
+	`color`,
+	`cursor`,
+	`d`,
+	`direction`,
+	`display`,
+	`dominant-baseline`,
+	`enable-background`,
+	`fill-opacity`,
+	`fill-rule`,
+	`fill`,
+	`filter`,
+	`flood-color`,
+	`flood-opacity`,
+	`font-family`,
+	`font-size-adjust`,
+	`font-size`,
+	`font-stretch`,
+	`font-style`,
+	`font-variant`,
+	`font-weight`,
+	`glyph-orientation-horizontal`,
+	`glyph-orientation-vertical`,
+	`image-rendering`,
+	`kerning`,
+	`letter-spacing`,
+	`lighting-color`,
+	`marker-end`,
+	`marker-mid`,
+	`marker-start`,
+	`mask`,
+	`opacity`,
+	`overflow`,
+	`pointer-events`,
+	`shape-rendering`,
+	`solid-color`,
+	`solid-opacity`,
+	`stop-color`,
+	`stop-opacity`,
+	`stroke-dasharray`,
+	`stroke-dashoffset`,
+	`stroke-linecap`,
+	`stroke-linejoin`,
+	`stroke-miterlimit`,
+	`stroke-opacity`,
+	`stroke-width`,
+	`stroke`,
+	`style`,
+	`text-anchor`,
+	`text-decoration`,
+	`text-rendering`,
+	`transform`,
+	`unicode-bidi`,
+	`vector-effect`,
+	`visibility`,
+	`word-spacing`,
+	`writing-mode`
+])
+
+export function stacksvg (options) {
+
+	options = options || {}
+
+	const ids = {}
+	const namespaces = {}
+	const separator = options.separator ?? `_`
+	const spacer = options.spacer ?? `-`
+
+	let resultSvg = `<?xml version="1.0" encoding="UTF-8"?><svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"><style>:root{visibility:hidden}:target{visibility:visible}</style><defs/></svg>`
+	let isEmpty = true
+	let fileName = options.output || `stack.svg`
+
+	fileName = fileName.endsWith(`.svg`) ? fileName : `${fileName}.svg`
+
+	const $ = load(resultSvg, { xmlMode: true })
+	const $combinedSvg = $(`svg`)
+	const $combinedDefs = $(`defs`)
+	const stream = new Transform({ objectMode: true })
+
+	stream._transform = function transform (file, _, cb) {
+
+		if (file.isStream()) {
+			return cb(new PluginError(`gulp-stacksvg`, `Streams are not supported!`))
+		}
+
+		if (file.isNull()) {return cb()}
+
+
+		const $svg = load(file.contents.toString(), { xmlMode: true })(`svg`)
+
+		if ($svg.length === 0) {return cb()}
+
+		const idAttr = basename(
+			file.relative.split(sep).join(separator).replace(/\s/g, spacer),
+			extname(file.relative)
+		)
+		const viewBoxAttr = $svg.attr(`viewBox`)
+		const widthAttr = $svg.attr(`width`)
+		const heightAttr = $svg.attr(`height`)
+		const preserveAspectRatioAttr = $svg.attr(`preserveAspectRatio`)
+		const $icon = $(`<svg/>`)
+
+		if (idAttr in ids) {
+			return cb(new PluginError(`gulp-stacksvg`, `File name should be unique: ${idAttr}`))
+		}
+
+		ids[idAttr] = true
+
+		if (file && isEmpty) {
+			isEmpty = false
+		}
+
+		$icon.attr(`id`, idAttr)
+		if (viewBoxAttr) {
+			$icon.attr(`viewBox`, viewBoxAttr)
+		} else if (widthAttr && heightAttr) {
+			$icon.attr(`viewBox`, `0 0 ${widthAttr.replace(/[^0-9]/g,``)} ${heightAttr.replace(/[^0-9]/g,``)}`)
+		}
+		if (preserveAspectRatioAttr) {
+			$icon.attr(`preserveAspectRatio`, preserveAspectRatioAttr)
+		}
+
+		const attrs = $svg[0].attribs
+		for (let attrName in attrs) {
+			if (attrName.match(/xmlns:.+/)) {
+				const storedNs = namespaces[attrName]
+				const attrNs = attrs[attrName]
+
+				if (storedNs !== undefined) {
+					if (storedNs !== attrNs) {
+						fancyLog.info(
+							`${attrName} namespace appeared multiple times with different value. Keeping the first one : "${storedNs}".\nEach namespace must be unique across files.`
+						)
+					}
+				} else {
+					for (let nsName in namespaces) {
+						if (namespaces[nsName] === attrNs) {
+							fancyLog.info(`Same namespace value under different names : ${nsName} and ${attrName}.\nKeeping both.`)
+						}
+					}
+					namespaces[attrName] = attrNs
+				}
+			}
+		}
+
+		const $defs = $svg.find(`defs`)
+		if ($defs.length > 0) {
+			$combinedDefs.append($defs.contents())
+			$defs.remove()
+		}
+
+		let $groupWrap = null
+		for (let [name, value] of Object.entries($svg.attr())) {
+			if (!presentationAttributes.has(name)) {continue}
+			if (!$groupWrap) {$groupWrap = $(`<g/>`)}
+			$groupWrap.attr(name, value)
+		}
+
+		if ($groupWrap) {
+			$groupWrap.append($svg.contents())
+			$icon.append($groupWrap)
+		} else {
+			$icon.append($svg.contents())
+		}
+		$combinedSvg.append($icon)
+		cb()
+	}
+
+	stream._flush = function flush (cb) {
+		if (isEmpty) {return cb()}
+		if ($combinedDefs.contents().length === 0) {
+			$combinedDefs.remove()
+		}
+		for (let nsName in namespaces) {
+			$combinedSvg.attr(nsName, namespaces[nsName])
+		}
+		const file = new Vinyl({ path: fileName, contents: Buffer.from($.xml()) })
+		this.push(file)
+		cb()
+	}
+
+	return stream
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+	"name": "gulp-stacksvg",
+	"version": "1.0.0",
+	"type": "module",
+	"description": "Combine svg files into one with stack method",
+	"main": "index.js",
+	"files": [
+		"index.js"
+	],
+	"scripts": {
+		"lint": "eslint ./",
+		"test": "gulp build && mocha",
+		"pretest": "npm run lint",
+		"preversion": "npm test",
+		"postversion": "npm publish",
+		"postpublish": "git push origin --all; git push origin --tags"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git://github.com/firefoxic/gulp-stacksvg"
+	},
+	"author": {
+		"name": "Sergey Artemov",
+		"email": "firefoxic.dev@gmail.com"
+	},
+	"license": "MIT",
+	"bugs": {
+		"url": "https://github.com/firefoxic/gulp-stacksvg/issues"
+	},
+	"homepage": "https://github.com/firefoxic/gulp-stacksvg",
+	"dependencies": {
+		"cheerio": "^1.0.0-rc.12",
+		"fancy-log": "^2.0.0",
+		"plugin-error": "^2.0.0",
+		"vinyl": "^2.2.1"
+	},
+	"devDependencies": {
+		"eslint": "^8.22.0",
+		"finalhandler": "^1.2.0",
+		"gulp": "^4.0.2",
+		"mocha": "^10.0.0",
+		"puppeteer": "^16.2.0",
+		"serve-static": "^1.15.0",
+		"sinon": "^14.0.0"
+	},
+	"engines": {
+		"node": "16"
+	},
+	"engineStrict": true,
+	"keywords": [
+		"gulpplugin",
+		"svg",
+		"icon",
+		"stack",
+		"sprite"
+	]
+}