@iconify/tools 1.3.17 → 2.0.0-dev.2

package/README.md

@@ -1,576 +0,0 @@
-# Iconify Tools
-
-This library is a collection of tools for importing, exporting and processing SVG images. 
-
-Its main purpose is to convert icon sets and fonts to Iconify JSON collections, but it can be used for other purposes.
-
-## Installation
-
-First install it by running this command:
-
-```
-npm install @iconify/tools --save
-```
-
-Then you can use it in your Node.js files:
-
-```
-const tools = require('@iconify/tools');
-```
-
-## What tools are available?
-
-* Import SVG from various sources
-* Export SVG to various formats
-* Optimize images
-* Crop images
-* Clean up images
-* Get/change color palette
-* Find shapes, get lengths of shapes
-* Convert shapes to paths
-
-## Core
-
-Core of tools are SVG and Collections classes. All tools create or manipulate instances of SVG or Collection classes.
-
-All tools are based on Promises. If you are not familiar with JavaScript Promises, do read up. There are many tutorials
-available online. Make sure you are reading something from 2016 or newer, not tutorials for old implementations.
-
-### SVG class
-
-SVG class represents one SVG image. It is a simple class, it does not manipulate anything, except for
-cleaning up junk code that could otherwise cause XML parser to fail.
-
-You can find code in src/svg.js
-
-Creating SVG instance is easy:
-
-```
-let svg = new tools.SVG('<svg ...></svg>');
-```
-
-That code will load SVG from string, extract image dimensions and clean up a bit, removing all junk image editors left
-behind.
-
-SVG instance has multiple methods to get SVG as string:
-
-* svg.toString() - returns SVG as string
-* svg.toMinifiedString() - same as toString(), but without white spaces
-* svg.getBody() - returns body as string: child elements of `<svg>` element.
-
-Then you can get dimensions:
-
-* svg.getDimensions() - returns object containing width and height properties
-* svg.width - returns width
-* svg.height - returns height
-
-Last method replaces content of SVG instance:
-
-* svg.load(content) - same as constructor, but instead of making new instance it changes existing instance.
-
-You can see usage examples in unit tests: tests/core/svg_test.js
-
-### Collection class
-
-Collection is a set of SVG instances.
-
-You can find code in src/collection.js
-
-To create Collection instance use this:
-
-```
-let collection = new tools.Collection();
-```
-
-That will create empty collection.
-
-To clone another collection add collection as parameter to constructor:
-
-```
-let newCollection = new tools.Collection(oldCollection);
-```
-
-To add/remove items there are several methods:
-
-* collection.add('icon-name', svg) - add new item to collection
-* collection.remove('icon-name') - remove item from collection
-* collection.rename('old-name', 'new-name') - rename item
-
-where "svg" is instance of SVG class
-
-To access any item use this:
-
-* collection.items['item-name']
-
-There are other helpful functions:
-
-* collection.length() - returns number of items in collection
-* collection.keys() - returns list of all icon names
-
-Then there are main functions that are used to manipulate SVG instances in collection:
-
-* collection.forEach(callback) - iterates through all SVG instances. Callback function arguments: (svg, name), where svg is SVG instance, name is icon name.
-* collection.promiseAll(promise) - runs promise on all items in collection. It is similar to Promise.all()
-* collection.promiseEach(promise, stopOnError) - runs promise on all items in collection, but only one at a time.
-
-How to use forEach():
-
-```
-collection.forEach((svg, name) {
-    console.log('Found icon ' + name + ': ' + svg.toString());
-});
-```
-
-How to use promiseAll() and promiseEach():
-
-```
-collection.promiseAll((svg, name) => {
-    return new Promise((fulfill, reject) {
-        // do stuff to "svg" variable
-        fulfill('Result for icon ' + name);
-    });
-}).then(results => {
-    // Results of all promises as object. Key = icon name, value = result for that icon
-
-    Object.keys(results).forEach(name => {
-        console.log('Result for icon ' + name + ':', results[name]);
-    });
-}).catch(err => {
-    console.error('Promise failed:', err);
-});
-```
-
-promiseAll() and promiseEach() are almost identical. First argument is callback that returns Promise for one icon.
-
-The only difference is promiseAll() runs all promises at the same time using Promise.all() function, promiseEach() runs promises one after another. It is better to use promiseEach() when dealing with large collections.
-
-You can find examples throughout this library and unit tests. Everything in this library is based on promises.
-
-## Importing
-
-There are several importers available. Some import one file, some import collections.
-
-### Importing one SVG file
-
-```
-tools.ImportSVG('path-to-file.svg').then(svg => {
-    // SVG was imported
-    // Variable 'svg' is instance of SVG class
-    console.log(svg.toString());
-}).catch(err => {
-    console.error(err);
-});
-```
-
-### Importing directory
-
-```
-tools.ImportDir('directory').then(collection => {
-    // Collection was imported
-    // Variable 'collection' is instance of Collection class
-    console.log('Found icons: ' + collection.keys().join(', '));
-}).catch(err => {
-    console.error(err);
-});
-```
-
-There are several options available for importing directory, options should be passed as second parameter to ImportDir
-function:
-
-* 'include-subdirs' - check subdirectories. Default = true
-* keywordCallback - custom callback to get image name from file. It is a function with 2 arguments: function(file_without_extension, filename). Function should return string. See default function in src/import/dir.js for example
-* ignoreDuplicates - if true, when files with duplicate keywords are found script will log a error message.
-* ignoreFiles - array of files to ignore. Values are keywords, not file names.
-* contentCallback - callback to change content. Use it if content contains some weird stuff you need to remove before importing SVG. function(content). Function should return modified content as string.
-
-```
-tools.ImportDir('directory', {
-    'include-subdirs': false,
-    ignoreFiles: ['bad-icon'],
-    keywordCallback: (file, filename) => 'prefix-' + file
-}).then(collection => {
-    // Collection was imported
-    // Variable 'collection' is instance of Collection class
-    console.log('Found icons: ' + collection.keys().join(', '));
-}).catch(err => {
-    console.error(err);
-});
-```
-
-### Importing WebIcon
-
-WebIcon format is one big SVG image that contains multiple images.
-
-```
-tools.ImportWebIcon('path-to-file.svg').then(collection => {
-    // Collection was imported
-    // Variable 'collection' is instance of Collection class
-    console.log('Found icons: ' + collection.keys().join(', '));
-}).catch(err => {
-    console.error(err);
-});
-```
-
-### Importing SVG font
-
-There are many popular glyph fonts, such as FontAwesome, that are not available as individual files. This importer will
-import SVG font as collection. It will not import keywords though for each icon - that is different for every
-collection and should be done separately.
-
-```
-tools.ImportFont('path-to-file.svg').then(collection => {
-    // Collection was imported
-    // Variable 'collection' is instance of Collection class
-    console.log('Found icons: ' + collection.keys().join(', '));
-}).catch(err => {
-    console.error(err);
-});
-```
-
-There are several options available for importing SVG font, options should be passed as second parameter to ImportFont
-function:
-
-* ignoreCharacters - list of characters to ignore. Array
-* characterChanges - changes for each character, object. Key is character's hexadecimal code, value is list of changes for that character.
-* fontChanges - changes for all characters
-
-Keys for characterChanges and fontChanges objects are similar:
-
-* height, width - custom height and width
-* left, bottom - custom left and bottom indexes. Why bottom instead of top? SVG fonts flip icons vertically, so height is counted from bottom
-
-Each value can be a number or a function(oldValue) that should return new value.
-
-Example:
-
-```
-tools.ImportFont('path-to-file.svg', {
-    fontChanges: {
-        height = height => Math.ceil(height / 16) * 16 // Round up height to 16px grid
-    },
-    characterChanges: {
-        f19c: { width: 1920 },
-        f0fc: { left: 64, width: 1600 },
-    }
-}).then(collection => {
-    // Collection was imported
-    // Variable 'collection' is instance of Collection class
-    console.log('Found icons: ' + collection.keys().join(', '));
-}).catch(err => {
-    console.error(err);
-});
-```
-
-If you are going to crop images after import, there is no point in worrying about fixing characters. Crop will fix it (unless font is really badly messed up).
-
-## Exporting
-
-There are several exporters available that work with Collection or SVG instances:
-
-### Exporting SVG
-
-Exports one SVG instance.
-
-```
-tools.ExportSVG(svg, 'filename.svg').then(() => {
-    console.log('Exported!');
-}).catch(err => {
-    console.error(err);
-});
-```
-
-### Exporting collection to directory
-
-```
-tools.ExportDir(collection, 'directory').then(count => {
-    console.log('Exported ' + count + ' files');
-}).catch(err => {
-    console.error(err);
-});
-```
-
-### Exporting collection to JSON file
-
-This is main export function, it exports collection to JSON format used by Iconify.
-
-```
-tools.ExportJSON(collection, 'filename.json').then(json => {
-    console.log('Exported collection. JSON data: ' + JSON.stringify(json));
-}).catch(err => {
-    console.error(err);
-});
-```
-
-### Exporting image to PNG
-
-You can also export images to PNG.
-
-Important: this function requires PhantomJS to be installed and accessible from command line!
-
-```
-tools.ExportPNG(svg, 'filename.png', {
-    // options object here
-}).then(() => {
-    console.log('Exported filename.png');
-}).catch(err => {
-    console.error(err);
-});
-```
-
-Options object has following properties:
-* width, height: dimensions of PNG image. Default = same as SVG dimensions.
-* color: color for monotone images that use currentColor (see ChangePalette function). Default = '#000'
-* background: background color, default = 'transparent'
-
-
-## Manipulating
-
-Most functions require SVG to be optimized. Therefore before doing anything else, you should optimize icon.
-
-### SVGO optimization
-
-This module optimizes SVG images, removing any unnecessary code and cleaning up stuff. It does not merge shapes to avoid
-potential problems with images that rely on specific order of shapes.
-
-```
-tools.SVGO(svg).then(svg => {
-    // svg variable is the same as in argument. Optimizer does not create new instance of SVG class
-    console.log('Optimized SVG');
-}).catch(err => {
-    console.error(err);
-});
-```
-
-Want to optimize entire collection? Use collection's promiseAll function:
-
-```
-collection.promiseAll(svg => tools.SVGO(svg)).then(results => {
-    console.log('Optimized entire collection');
-}).catch(err => {
-    console.error(err);
-});
-```
-
-### Cropping images
-
-This module crops SVG icons imported from fonts.
-
-Important! This function requires PhantomJS to be installed. See http://phantomjs.org/
-
-How to crop one image:
-
-```
-tools.Crop(svg).then(svg => {
-    console.log('Cropped SVG: ' + svg.toString());
-}).catch(err => {
-    console.error(err);
-});
-```
-
-How to crop entire collection:
-
-```
-tools.Crop(collection).then(collection => {
-    console.log('Cropped ' + svg.length() + ' images');
-}).catch(err => {
-    console.error(err);
-});
-```
-
-How does crop work? By drawing SVG on canvas and checking all 4 sides for transparent pixels. First it appends space on
-all sides of SVG, until all sides have nothing but empty pixels. Then it slowly cuts all sides until it reaches pixels
-that aren't empty. Process doesn't take long because script checks pixels in bulk by zooming in.
-
-When it crops SVG or Collection instance (like in examples above), each SVG instance receives additional properties
-that you might want to use later: _cropData. _cropData is an object with list of cropped edges: left, top, right, bottom.
-
-Node.js is not a browser, it does not support canvas and cannot render SVG images. Because of that calculations are
-done in PhantomJS and script requires PhantomJS to be installed.
-
-### Tags validation
-
-This module checks elements used in SVG image, changes stylesheet into inline style and removes useless attributes.
-
-Stylesheet parser is very simple, it parses only basic stylesheets that are generated by some image editors. If SVG
-contains fishy elements that aren't vector images, such as bitmaps or scripts, it will reject with error message.
-
-Important! Before running this function you need to optimize SVG image using tools.SVGO()
-
-Usage:
-
-```
-tools.Tags(svg).then(svg => {
-    console.log('Cleaned up tags in SVG: ' + svg.toString());
-}).catch(err => {
-    console.error(err);
-});
-```
-
-This function is used for optimizing SVG images that contain a lot of junk code.
-
-### Extracting palette from SVG
-
-If you don't know if SVG is colored or monotone or maybe doesn't have any colors at all, this tool will find all colors
-used in SVG and return you array of used colors.
-
-Result is object with 2 properties:
-
-* colors - array of color strings
-* notices - array of error messages
-
-Usage:
-
-```
-tools.GetPalette(svg).then(result => {
-    console.log('Colors used in SVG: ' + result.colors.join(', ');
-    if (result.notices.length) {
-        result.notices.forEach(notice => console.warn(notice));
-    }
-}).catch(err => {
-    console.error(err);
-});
-```
-
-Using it with collection:
-
-```
-collection.promiseAll(svg => tools.GetPalette(svg)).then(result => {
-    Object.keys(results).forEach(key => {
-        console.log('Colors found in image ' + key + ': ' + result[key].colors.join(', ');
-    });
-}).catch(err => {
-    console.error(err);
-});
-```
-
-### Replacing palette in SVG
-
-This tool can be used to change colors in SVG or add colors to shapes that are missing color values.
-
-```
-tools.ChangePalette(svg, {
-    '#ff8000': '#0080ff',
-    '#123': '#234'
-}).then(svg => {
-    // Variable "svg" in result is the same as in first parameter of ChangePalette.
-    // Function changes existing SVG instance 
-    console.log('Changed palette');
-}).catch(err => {
-    console.error(err);
-});
-```
-
-Code above will change #ff8000 to #0080ff and #123 to #234. 
-
-But there are more options:
-
-```
-tools.ChangePalette(svg, 'red').then(svg => {
-    console.log('Added palette to elements without palette');
-}).catch(err => {
-    console.error(err);
-});
-```
-
-Code above will add color "red" to all elements that do not have color. It is identical to this:
-
-```
-tools.ChangePalette(svg, {
-    add: 'red'
-}).then(svg => {
-    console.log('Added palette to elements without palette');
-}).catch(err => {
-    console.error(err);
-});
-```
-
-You can also change all colors by using keyword "default":
-
-```
-tools.ChangePalette(svg, {
-    default: 'green'
-}).then(svg => {
-    console.log('Changed all colors to green');
-}).catch(err => {
-    console.error(err);
-});
-```
-
-Or you can combine all those attributes:
-
-```
-tools.ChangePalette(svg, {
-    default: 'green',
-    add: '#000',
-    '#123': '#234
-}).then(svg => {
-    console.log('Changed all colors to green, except for #123 that was changed to #234, added black color to elements without color');
-}).catch(err => {
-    console.error(err);
-});
-```
-
-Primary use of this tool in Iconify is to replace all colors in monotone with "currentColor" keyword and add it to shapes that are missing color values:
-
-```
-collection.promiseAll(svg => tools.ChangePalette(svg, {
-    default: 'currentColor',
-    add: 'currentColor'
-})).then(() => {
-    console.log('Changed color to currentColor');
-}).catch(err => {
-    console.error(err);
-});
-```
-
-## Indexing shapes and getting shape lengths
-
-If you are doing stroke animations, you might need to index shapes (add unique class names for them to apply different
-animations to different shapes) and get length of those shapes.
-
-tools.IndexShapes adds custom attribute to all shapes:
-
-```
-tools.IndexShapes(svg, {
-    // Attribute to set
-    shapeAttribute: 'data-shape-index',
-    // Attribute value. {index} is replaced with index, incrementing with each shape
-    shapeAttributeValue: '{index}',
-}).then(shapesCount => {
-    console.log('Added data-shape-index attribute to ' + shapesCount + ' shapes.');
-}).catch(err => {
-    console.error(err);
-});
-```
-
-You can also get those shapes by setting option returnNodes to true. Instead of number of shapes Promise will return
-array of nodes. Each node is cheerio node object. See cheerio documentation for details. 
-
-tools.ShapeLengths counts lengths of all shapes. It also returns all nodes, so you can change shapes (add/remove 
-attributes or class name):
-
-```
-tools.ShapeLength(svg).then(results => {
-    console.log('Found ' + results.length + ' shapes:');
-    results.forEach(result => {
-        console.log('Shape ' + result.$node.get(0).tagName + ' has length of ' + result.length);
-    });
-}).catch(err => {
-    console.error(err);
-});
-```
-
-## Sample
-
-In directory "sample" you will find a sample script that parses the directory of SVG images. It optimizes images, exports
-them as optimized SVG images and as JSON collection.
-
-## More tools
-
-If you need any other tool to help with custom SVG icon sets development, suggest it by opening an issue on GitHub repository.
-
-## License
-
-Library is released with MIT license.
-
-© 2016 - 2019 Vjacheslav Trushkin

package/license.txt

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2016 - 2019 Vjacheslav Trushkin
-
-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/sample/parse.js

@@ -1,74 +0,0 @@
-/**
- * This is a sample file showing how to optimize SVG files.
- *
- * In directory "source" there are several unoptimized SVG files exported from Sketch.
- *
- * Run this file in Node.js: node parse
- *
- * It will optimize SVG images from directory "source" and save them to "optimized/svg".
- * It will also save icons as JSON collection in SimpleSVG format, which you can use to add custom icons to SimpleSVG.
- */
-"use strict";
-
-const fs = require('fs');
-// const tools = require('simple-svg-tools');
-const tools = require('../src/modules');
-
-let collection;
-let sourceDir = 'source';
-
-// Create directories
-try {
-    fs.mkdirSync('optimized');
-} catch (err) {
-}
-try {
-    fs.mkdirSync('optimized/svg');
-} catch (err) {
-}
-
-// Do stuff
-tools.ImportDir(sourceDir).then(result => {
-    collection = result;
-    console.log('Found ' + collection.length() + ' icons.');
-
-    // SVGO optimization
-    return collection.promiseAll(svg => tools.SVGO(svg));
-}).then(() => {
-    // Clean up tags
-    return collection.promiseAll(svg => tools.Tags(svg));
-}).then(() => {
-    // Get palette
-    return collection.promiseAll(svg => tools.GetPalette(svg));
-}).then(results => {
-    // Replace colors. Remove this bit if all your images are supposed to have preset color palette.
-    let promises = [];
-
-    Object.keys(results).forEach(key => {
-        if (results[key].colors.length < 2) {
-            // Add/change color for images with less than 2 colors
-            promises.push(tools.ChangePalette(collection.items[key], {
-                add: 'currentColor',
-                default: 'currentColor'
-            }));
-        }
-    });
-
-    return Promise.all(promises);
-}).then(() => {
-    // SVGO optimization again. Might make files smaller after color/tags changes
-    return collection.promiseAll(svg => tools.SVGO(svg));
-}).then(() => {
-    // Export as optimized SVG icons
-    return tools.ExportDir(collection, 'optimized/svg');
-}).then(() => {
-    // Export as JSON
-    return tools.ExportJSON(collection, 'optimized/icons.json', {
-        minify: false,
-        optimize: true
-    });
-}).then(() => {
-    console.log('Parsed ' + collection.length() + ' icons.');
-}).catch(err => {
-    console.log(err);
-});

package/sample/source/icon-close.svg

@@ -1,15 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<svg width="128px" height="128px" viewBox="0 0 128 128" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
-    <!-- Generator: Sketch 43.1 (39012) - http://www.bohemiancoding.com/sketch -->
-    <title>icon-close</title>
-    <desc>Created with Sketch.</desc>
-    <defs></defs>
-    <g id="Page-1" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd">
-        <g id="16x16-(144)-fill" transform="translate(-152.000000, -8.000000)">
-            <g id="_slices" transform="translate(8.000000, 8.000000)"></g>
-            <g id="close" transform="translate(152.000000, 8.000000)" fill-rule="nonzero" fill="#000000">
-                <path d="M52.6862915,64 L2.34314575,114.343146 C-0.781048584,117.46734 -0.781048584,122.53266 2.34314575,125.656854 C5.46734008,128.781049 10.5326599,128.781049 13.6568542,125.656854 L64,75.3137085 L114.343146,125.656854 C117.46734,128.781049 122.53266,128.781049 125.656854,125.656854 C128.781049,122.53266 128.781049,117.46734 125.656854,114.343146 L75.3137085,64 L125.656854,13.6568542 C128.781049,10.5326599 128.781049,5.46734008 125.656854,2.34314575 C122.53266,-0.781048584 117.46734,-0.781048584 114.343146,2.34314575 L64,52.6862915 L13.6568542,2.34314575 C10.5326599,-0.781048584 5.46734008,-0.781048584 2.34314575,2.34314575 C-0.781048584,5.46734008 -0.781048584,10.5326599 2.34314575,13.6568542 L52.6862915,64 Z" id="Combined-Shape"></path>
-            </g>
-        </g>
-    </g>
-</svg>

package/sample/source/icon-confirm.svg

@@ -1,14 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<svg width="128px" height="128px" viewBox="0 0 128 128" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
-    <!-- Generator: Sketch 43.1 (39012) - http://www.bohemiancoding.com/sketch -->
-    <title>icon-confirm</title>
-    <desc>Created with Sketch.</desc>
-    <defs></defs>
-    <g id="Page-1" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd">
-        <g id="16x16-(144)-fill" transform="translate(-296.000000, -8.000000)" fill-rule="nonzero" fill="#000000">
-            <g id="confirm" transform="translate(296.000000, 15.000000)">
-                <path d="M54.7566014,92.4428929 L13.6568542,51.3431458 C10.5326599,48.2189514 5.46734008,48.2189514 2.34314575,51.3431458 C-0.781048584,54.4673401 -0.781048584,59.5326599 2.34314575,62.6568542 L50.3431458,110.656854 C53.9128834,114.226592 59.8560698,113.6381 62.6564024,109.437602 L126.656402,13.4376016 C129.107222,9.76137206 128.113831,4.79441732 124.437602,2.34359765 C120.761372,-0.107222028 115.794417,0.886168921 113.343598,4.56239843 L54.7566014,92.4428929 Z" id="Line"></path>
-            </g>
-        </g>
-    </g>
-</svg>