Skip to content

Commit

Permalink
Replace dox with documentation.js and improve all the docs
Browse files Browse the repository at this point in the history
  • Loading branch information
bhousel committed Sep 15, 2016
1 parent 2d2b9b5 commit 770c133
Show file tree
Hide file tree
Showing 26 changed files with 1,873 additions and 61 deletions.
88 changes: 45 additions & 43 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# spritezero

[![npm version](https://badge.fury.io/js/spritezero.svg)](https://badge.fury.io/js/spritezero)
[![build status](https://secure.travis-ci.org/mapbox/spritezero.svg)](http://travis-ci.org/mapbox/spritezero)

## spritezero

Small opinionated sprites.

Why is this different than sprite generation libraries like [spritesmith](https://github.com/Ensighten/spritesmith)?
Expand All @@ -13,54 +13,60 @@ based on SVG graphics alone, therefore making it possible to support @2x
and higher-dpi sprites from the same source.


## API

###`generateLayout(imgs, ratio, format, callback)`

Pack a list of images with width and height into a sprite layout.
Uses [shelf-pack](https://github.com/mapbox/shelf-pack).

**Parameters**

| parameter | type | description |
| ---------- | ----------------- | -------------------------------------- |
| `imgs` | Array\.\<Object\> | array of `{ svg: Buffer, id: String }` |
| `scale` | number | pixel scale. default is 1, retina is 2 |
| `format` | boolean | format this layout for Mapbox GL |
| `callback` | function | accepts two arguments, `err` and `layout` Object |

**Returns** results of `callback`

---
### Usage
```js
var spritezero = require('spritezero');
var fs = require('fs');
var glob = require('glob');
var path = require('path');

[1, 2, 4].forEach(function(pxRatio) {
var svgs = glob.sync(path.resolve(path.join(__dirname, 'input/*.svg')))
.map(function(f) {
return {
svg: fs.readFileSync(f),
id: path.basename(f).replace('.svg', '')
};
});
var pngPath = path.resolve(path.join(__dirname, 'output/sprite@' + pxRatio + '.png'));
var jsonPath = path.resolve(path.join(__dirname, 'output/sprite@' + pxRatio + '.json'));

// Pass `true` in the layout parameter to generate a data layout
// suitable for exporting to a JSON sprite manifest file.
spritezero.generateLayout(svgs, pxRatio, true, function(err, dataLayout) {
if (err) return;
fs.writeFileSync(jsonPath, JSON.stringify(dataLayout)));
});

// Pass `false` in the layout parameter to generate an image layout
// suitable for exporting to a PNG sprite image file.
spritezero.generateLayout(svgs, pxRatio, false, function(err, imageLayout) {
spritezero.generateImage(imageLayout, function(err, image) {
if (err) return;
fs.writeFileSync(pngPath, image);
});
});

});

###`generateLayoutUnique(imgs, ratio, format, callback)`

Identical to `generateLayout(imgs, ratio, format, callback)` but maps identical images to a single
image while preserving the reference in the Mapbox GL layout.

---

###`generateImage(packing, callback)`
```

Generate a PNG image with positioned icons on a sprite.

**Parameters**
### Documentation

| parameter | type | description |
| ---------- | -------- | ----------- |
| `packing` | Object | |
| `callback` | Function | |
Complete API documentation is here: http://mapbox.github.io/spritezero/


## Installation
### Installation

Requires [nodejs](http://nodejs.org/).
Requires [nodejs](http://nodejs.org/) v4.0.0 or greater.

```sh
```bash
$ npm install spritezero
```

## Executable

### Executable

[spritezero-cli](https://github.com/mapbox/spritezero-cli) is an executable for bundling and creating your own sprites from a folder of svg's:

Expand All @@ -74,8 +80,4 @@ spritezero [output filename] [input directory]
--ratio=[n] pixel ratio
```

## Tests

```sh
$ npm test
```
197 changes: 197 additions & 0 deletions docs/assets/anchor.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,197 @@
/*!
* AnchorJS - v1.2.1 - 2015-07-02
* https://github.com/bryanbraun/anchorjs
* Copyright (c) 2015 Bryan Braun; Licensed MIT
*/

function AnchorJS(options) {
'use strict';

this.options = options || {};

this._applyRemainingDefaultOptions = function(opts) {
this.options.icon = this.options.hasOwnProperty('icon') ? opts.icon : '\ue9cb'; // Accepts characters (and also URLs?), like '#', '¶', '❡', or '§'.
this.options.visible = this.options.hasOwnProperty('visible') ? opts.visible : 'hover'; // Also accepts 'always'
this.options.placement = this.options.hasOwnProperty('placement') ? opts.placement : 'right'; // Also accepts 'left'
this.options.class = this.options.hasOwnProperty('class') ? opts.class : ''; // Accepts any class name.
};

this._applyRemainingDefaultOptions(options);

this.add = function(selector) {
var elements,
elsWithIds,
idList,
elementID,
i,
roughText,
tidyText,
index,
count,
newTidyText,
readableID,
anchor;

this._applyRemainingDefaultOptions(this.options);

// Provide a sensible default selector, if none is given.
if (!selector) {
selector = 'h1, h2, h3, h4, h5, h6';
} else if (typeof selector !== 'string') {
throw new Error('The selector provided to AnchorJS was invalid.');
}

elements = document.querySelectorAll(selector);
if (elements.length === 0) {
return false;
}

this._addBaselineStyles();

// We produce a list of existing IDs so we don't generate a duplicate.
elsWithIds = document.querySelectorAll('[id]');
idList = [].map.call(elsWithIds, function assign(el) {
return el.id;
});

for (i = 0; i < elements.length; i++) {

if (elements[i].hasAttribute('id')) {
elementID = elements[i].getAttribute('id');
} else {
roughText = elements[i].textContent;

// Refine it so it makes a good ID. Strip out non-safe characters, replace
// spaces with hyphens, truncate to 32 characters, and make toLowerCase.
//
// Example string: // '⚡⚡⚡ Unicode icons are cool--but they definitely don't belong in a URL fragment.'
tidyText = roughText.replace(/[^\w\s-]/gi, '') // ' Unicode icons are cool--but they definitely dont belong in a URL fragment'
.replace(/\s+/g, '-') // '-Unicode-icons-are-cool--but-they-definitely-dont-belong-in-a-URL-fragment'
.replace(/-{2,}/g, '-') // '-Unicode-icons-are-cool-but-they-definitely-dont-belong-in-a-URL-fragment'
.substring(0, 64) // '-Unicode-icons-are-cool-but-they-definitely-dont-belong-in-a-URL'
.replace(/^-+|-+$/gm, '') // 'Unicode-icons-are-cool-but-they-definitely-dont-belong-in-a-URL'
.toLowerCase(); // 'unicode-icons-are-cool-but-they-definitely-dont-belong-in-a-url'

// Compare our generated ID to existing IDs (and increment it if needed)
// before we add it to the page.
newTidyText = tidyText;
count = 0;
do {
if (index !== undefined) {
newTidyText = tidyText + '-' + count;
}
// .indexOf is supported in IE9+.
index = idList.indexOf(newTidyText);
count += 1;
} while (index !== -1);
index = undefined;
idList.push(newTidyText);

// Assign it to our element.
// Currently the setAttribute element is only supported in IE9 and above.
elements[i].setAttribute('id', newTidyText);

elementID = newTidyText;
}

readableID = elementID.replace(/-/g, ' ');

// The following code builds the following DOM structure in a more effiecient (albeit opaque) way.
// '<a class="anchorjs-link ' + this.options.class + '" href="#' + elementID + '" aria-label="Anchor link for: ' + readableID + '" data-anchorjs-icon="' + this.options.icon + '"></a>';
anchor = document.createElement('a');
anchor.className = 'anchorjs-link ' + this.options.class;
anchor.href = '#' + elementID;
anchor.setAttribute('aria-label', 'Anchor link for: ' + readableID);
anchor.setAttribute('data-anchorjs-icon', this.options.icon);

if (this.options.visible === 'always') {
anchor.style.opacity = '1';
}

if (this.options.icon === '\ue9cb') {
anchor.style.fontFamily = 'anchorjs-icons';
anchor.style.fontStyle = 'normal';
anchor.style.fontVariant = 'normal';
anchor.style.fontWeight = 'normal';
anchor.style.lineHeight = 1;
}

if (this.options.placement === 'left') {
anchor.style.position = 'absolute';
anchor.style.marginLeft = '-1em';
anchor.style.paddingRight = '0.5em';
elements[i].insertBefore(anchor, elements[i].firstChild);
} else { // if the option provided is `right` (or anything else).
anchor.style.paddingLeft = '0.375em';
elements[i].appendChild(anchor);
}
}

return this;
};

this.remove = function(selector) {
var domAnchor,
elements = document.querySelectorAll(selector);
for (var i = 0; i < elements.length; i++) {
domAnchor = elements[i].querySelector('.anchorjs-link');
if (domAnchor) {
elements[i].removeChild(domAnchor);
}
}
return this;
};

this._addBaselineStyles = function() {
// We don't want to add global baseline styles if they've been added before.
if (document.head.querySelector('style.anchorjs') !== null) {
return;
}

var style = document.createElement('style'),
linkRule =
' .anchorjs-link {' +
' opacity: 0;' +
' text-decoration: none;' +
' -webkit-font-smoothing: antialiased;' +
' -moz-osx-font-smoothing: grayscale;' +
' }',
hoverRule =
' *:hover > .anchorjs-link,' +
' .anchorjs-link:focus {' +
' opacity: 1;' +
' }',
anchorjsLinkFontFace =
' @font-face {' +
' font-family: "anchorjs-icons";' +
' font-style: normal;' +
' font-weight: normal;' + // Icon from icomoon; 10px wide & 10px tall; 2 empty below & 4 above
' src: url(data:application/x-font-ttf;charset=utf-8;base64,AAEAAAALAIAAAwAwT1MvMg8SBTUAAAC8AAAAYGNtYXAWi9QdAAABHAAAAFRnYXNwAAAAEAAAAXAAAAAIZ2x5Zgq29TcAAAF4AAABNGhlYWQEZM3pAAACrAAAADZoaGVhBhUDxgAAAuQAAAAkaG10eASAADEAAAMIAAAAFGxvY2EAKACuAAADHAAAAAxtYXhwAAgAVwAAAygAAAAgbmFtZQ5yJ3cAAANIAAAB2nBvc3QAAwAAAAAFJAAAACAAAwJAAZAABQAAApkCzAAAAI8CmQLMAAAB6wAzAQkAAAAAAAAAAAAAAAAAAAABEAAAAAAAAAAAAAAAAAAAAABAAADpywPA/8AAQAPAAEAAAAABAAAAAAAAAAAAAAAgAAAAAAADAAAAAwAAABwAAQADAAAAHAADAAEAAAAcAAQAOAAAAAoACAACAAIAAQAg6cv//f//AAAAAAAg6cv//f//AAH/4xY5AAMAAQAAAAAAAAAAAAAAAQAB//8ADwABAAAAAAAAAAAAAgAANzkBAAAAAAEAAAAAAAAAAAACAAA3OQEAAAAAAQAAAAAAAAAAAAIAADc5AQAAAAACADEARAJTAsAAKwBUAAABIiYnJjQ/AT4BMzIWFxYUDwEGIicmND8BNjQnLgEjIgYPAQYUFxYUBw4BIwciJicmND8BNjIXFhQPAQYUFx4BMzI2PwE2NCcmNDc2MhcWFA8BDgEjARQGDAUtLXoWOR8fORYtLTgKGwoKCjgaGg0gEhIgDXoaGgkJBQwHdR85Fi0tOAobCgoKOBoaDSASEiANehoaCQkKGwotLXoWOR8BMwUFLYEuehYXFxYugC44CQkKGwo4GkoaDQ0NDXoaShoKGwoFBe8XFi6ALjgJCQobCjgaShoNDQ0NehpKGgobCgoKLYEuehYXAAEAAAABAACiToc1Xw889QALBAAAAAAA0XnFFgAAAADRecUWAAAAAAJTAsAAAAAIAAIAAAAAAAAAAQAAA8D/wAAABAAAAAAAAlMAAQAAAAAAAAAAAAAAAAAAAAUAAAAAAAAAAAAAAAACAAAAAoAAMQAAAAAACgAUAB4AmgABAAAABQBVAAIAAAAAAAIAAAAAAAAAAAAAAAAAAAAAAAAADgCuAAEAAAAAAAEADgAAAAEAAAAAAAIABwCfAAEAAAAAAAMADgBLAAEAAAAAAAQADgC0AAEAAAAAAAUACwAqAAEAAAAAAAYADgB1AAEAAAAAAAoAGgDeAAMAAQQJAAEAHAAOAAMAAQQJAAIADgCmAAMAAQQJAAMAHABZAAMAAQQJAAQAHADCAAMAAQQJAAUAFgA1AAMAAQQJAAYAHACDAAMAAQQJAAoANAD4YW5jaG9yanMtaWNvbnMAYQBuAGMAaABvAHIAagBzAC0AaQBjAG8AbgBzVmVyc2lvbiAxLjAAVgBlAHIAcwBpAG8AbgAgADEALgAwYW5jaG9yanMtaWNvbnMAYQBuAGMAaABvAHIAagBzAC0AaQBjAG8AbgBzYW5jaG9yanMtaWNvbnMAYQBuAGMAaABvAHIAagBzAC0AaQBjAG8AbgBzUmVndWxhcgBSAGUAZwB1AGwAYQByYW5jaG9yanMtaWNvbnMAYQBuAGMAaABvAHIAagBzAC0AaQBjAG8AbgBzRm9udCBnZW5lcmF0ZWQgYnkgSWNvTW9vbi4ARgBvAG4AdAAgAGcAZQBuAGUAcgBhAHQAZQBkACAAYgB5ACAASQBjAG8ATQBvAG8AbgAuAAAAAwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==) format("truetype");' +
' }',
pseudoElContent =
' [data-anchorjs-icon]::after {' +
' content: attr(data-anchorjs-icon);' +
' }',
firstStyleEl;

style.className = 'anchorjs';
style.appendChild(document.createTextNode('')); // Necessary for Webkit.

// We place it in the head with the other style tags, if possible, so as to
// not look out of place. We insert before the others so these styles can be
// overridden if necessary.
firstStyleEl = document.head.querySelector('[rel="stylesheet"], style');
if (firstStyleEl === undefined) {
document.head.appendChild(style);
} else {
document.head.insertBefore(style, firstStyleEl);
}

style.sheet.insertRule(linkRule, style.sheet.cssRules.length);
style.sheet.insertRule(hoverRule, style.sheet.cssRules.length);
style.sheet.insertRule(pseudoElContent, style.sheet.cssRules.length);
style.sheet.insertRule(anchorjsLinkFontFace, style.sheet.cssRules.length);
};
}

var anchors = new AnchorJS();
12 changes: 12 additions & 0 deletions docs/assets/bass-addons.css
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
.input {
font-family: inherit;
display: block;
width: 100%;
height: 2rem;
padding: .5rem;
margin-bottom: 1rem;
border: 1px solid #ccc;
font-size: .875rem;
border-radius: 3px;
box-sizing: border-box;
}
Loading

0 comments on commit 770c133

Please sign in to comment.