Merge pull request #120 from primer/svg_node_api

Refactoring nodejs api and making more options available
primer · Sep 10, 2016 · 80f42e6 · 80f42e6
2 parents 115fb9c + 15a3aa6
commit 80f42e6
Show file tree

Hide file tree

Showing 7 changed files with 281 additions and 54 deletions.
diff --git a/Gruntfile.js b/Gruntfile.js
@@ -83,18 +83,23 @@ module.exports = function(grunt) {
   grunt.registerTask('svg', ['clean', 'svgmin', 'svg_sprite']);
 
   // default task, build /dist/
-  grunt.registerTask('default', [ 'svg', 'css', 'svg_json']);
+  grunt.registerTask('default', [ 'svg', 'css', 'json:svg']);
 
-  grunt.registerTask('svg_json', 'create a json object with all minimized svg', function() {
-    var result = {}
+  grunt.registerTask('json:svg', 'add svg string to data.json build', function() {
     var files = fs.readdirSync("./build/svg/")
+    var data = JSON.parse(fs.readFileSync("./lib/data.json"))
 
     files.forEach(function(file) {
       var svg = fs.readFileSync(path.resolve("./build/svg", file))
       var key = path.basename(file, ".svg")
-      result[key] = svg.toString()
+      if (data[key]) {
+        var raw = svg.toString()
+        data[key].path = /<path.+\/>/g.exec(raw)[0]
+        data[key].height = /height="(\d+)"/g.exec(raw)[1]
+        data[key].width = /width="(\d+)"/g.exec(raw)[1]
+      }
     })
 
-    fs.writeFileSync("build/svg.json", JSON.stringify(result));
+    fs.writeFileSync("build/data.json", JSON.stringify(data));
   })
 };
diff --git a/README.md b/README.md
@@ -7,6 +7,7 @@
 
 ## Install
 
+**NOTE:** The compiled files are located in `/build/`. This directory is located in the published npm package. Which means you can access it when you `npm install octicons`. You can also build this directory by following the [building octicons directions](#building-octicons). The files in the `/lib/` directory are the raw source files and are not compiled or optimized.
 
 #### NPM
 
@@ -18,12 +19,122 @@ $ npm install --save octicons
 
 ## Usage
 
-The source files included are written in [Sass][sass] (`scss`) You can simply point your sass `include-path` at your `node_modules` directory and import it like this.
+For all the usages, we recommend using the CSS located in `./build/octicons.css`. This is some simple CSS to normalize the icons and inherit colors.
+
+### Node
+
+After installing `npm install octicons` you can access the icons like this.
+
+```js
+var octicons = require("octicons")
+octicons.alert
+// { keywords: [ 'warning', 'triangle', 'exclamation', 'point' ],
+//   path: '<path d="M8.865 1.52c-.18-.31-.51-.5-.87-.5s-.69.19-.87.5L.275 13.5c-.18.31-.18.69 0 1 .19.31.52.5.87.5h13.7c.36 0 .69-.19.86-.5.17-.31.18-.69.01-1L8.865 1.52zM8.995 13h-2v-2h2v2zm0-3h-2V6h2v4z"/>',
+//   height: '16',
+//   width: '16',
+//   symbol: 'alert',
+//   options:
+//    { version: '1.1',
+//      width: '16',
+//      height: '16',
+//      viewBox: '0 0 16 16',
+//      class: 'octicon octicon-alert',
+//      'aria-hidden': 'true' },
+//   toSVG: [Function] }
+```
+
+There will be a key for every icon, with `keywords` and `svg`.
+
+#### `octicons.alert.symbol`
 
-```scss
-@import "octicons/index.scss";
+Returns the string of the symbol name
+
+```js
+octicons.x.symbol
+// "x"
 ```
 
+#### `octicons.person.path`
+
+Path returns the string representation of the path of the icon.
+
+```js
+octicons.x.path
+// <path d="M7.48 8l3.75 3.75-1.48 1.48L6 9.48l-3.75 3.75-1.48-1.48L4.52 8 .77 4.25l1.48-1.48L6 6.52l3.75-3.75 1.48 1.48z"></path>
+```
+
+#### `octicons.issue.options`
+
+This is a json object of all the `options` that will be added to the output tag.
+
+```js
+octicons.x.options
+// { version: '1.1', width: '12', height: '16', viewBox: '0 0 12 16', class: 'octicon octicon-x', 'aria-hidden': 'true' }
+```
+
+#### `octicons.alert.width`
+
+Width is the icon's true width. Based on the svg view box width. _Note, this doesn't change if you scale it up with size options, it only is the natural width of the icon_
+
+#### `octicons.alert.height`
+
+Height is the icon's true height. Based on the svg view box height. _Note, this doesn't change if you scale it up with size options, it only is the natural height of the icon_
+
+#### `keywords`
+
+Returns an array of keywords for the icon. The data [comes from the octicons repository](https://github.com/primer/octicons/blob/master/lib/data.json). Consider contributing more aliases for the icons.
+
+```js
+octicons.x.keywords
+// ["remove", "close", "delete"]
+```
+
+#### `octicons.alert.toSVG()`
+
+Returns a string of the svg tag
+
+```js
+octicons.x.toSVG()
+// <svg version="1.1" width="12" height="16" viewBox="0 0 12 16" class="octicon octicon-x" aria-hidden="true"><path d="M7.48 8l3.75 3.75-1.48 1.48L6 9.48l-3.75 3.75-1.48-1.48L4.52 8 .77 4.25l1.48-1.48L6 6.52l3.75-3.75 1.48 1.48z"/></svg>
+```
+
+The `.toSVG()` method accepts an optional `options` object. This is used to add CSS classnames, a11y options, and sizing.
+
+##### class
+
+Add more CSS classes to the `<svg>` tag.
+
+```js
+octicons.x.toSVG({ "class": "close" })
+// <svg version="1.1" width="12" height="16" viewBox="0 0 12 16" class="octicon octicon-x close" aria-hidden="true"><path d="M7.48 8l3.75 3.75-1.48 1.48L6 9.48l-3.75 3.75-1.48-1.48L4.52 8 .77 4.25l1.48-1.48L6 6.52l3.75-3.75 1.48 1.48z"/></svg>
+```
+
+##### aria-label
+
+Add accessibility `aria-label` to the icon.
+
+```js
+octicons.x.toSVG({ "aria-label": "Close the window" })
+// <svg version="1.1" width="12" height="16" viewBox="0 0 12 16" class="octicon octicon-x" aria-label="Close the window" role="img"><path d="M7.48 8l3.75 3.75-1.48 1.48L6 9.48l-3.75 3.75-1.48-1.48L4.52 8 .77 4.25l1.48-1.48L6 6.52l3.75-3.75 1.48 1.48z"/></svg>
+```
+
+##### width & height
+
+Size the SVG icon larger using `width` & `height` independently or together.
+
+```js
+octicons.x.toSVG({ "width": "" })
+// <svg version="1.1" width="12" height="16" viewBox="0 0 12 16" class="octicon octicon-x" aria-hidden="true"><path d="M7.48 8l3.75 3.75-1.48 1.48L6 9.48l-3.75 3.75-1.48-1.48L4.52 8 .77 4.25l1.48-1.48L6 6.52l3.75-3.75 1.48 1.48z"/></svg>
+```
+
+### Ruby
+
+If your environment is Ruby on Rails, we have a [octicons_helper](https://github.com/primer/octicons_helper) gem available that renders SVG in your page. The octicons_helper uses the [octicons_gem](https://github.com/primer/octicons_gem) to do the computing and reading of the SVG files.
+
+### Jekyll
+
+For jekyll, there's a [jekyll-octicons](https://github.com/primer/jekyll-octicons) plugin available. This works exactly like the octicons_helper.
+
 ## Changing, adding, or deleting icons
 
 1. Open the [Sketch document][sketch-document] in `/lib/`. Each icon exists as an artboard within our master Sketch document. If you’re adding an icon, duplicate one of the artboards and add your shapes to it. Be sure to give your artboard a name that makes sense.

diff --git a/index.js b/index.js
@@ -1,4 +1,62 @@
-module.exports = {
-  keywords: require('./lib/keywords'),
-  svg: require('./build/svg.json')
-}
+var data = require('./build/data.json')
+
+Object.keys(data).forEach(function(key) {
+
+  // Returns a string representation of html attributes
+  var htmlAttributes = function(icon, options) {
+    var attributes = []
+    var attrObj = Object.assign({}, data[key].options, options)
+
+    // If the user passed in options
+    if (options) {
+
+      // If any of the width or height is passed in
+      if(options["width"] || options["height"]) {
+        attrObj["width"] = options["width"] ? options["width"] : (parseInt(options["height"]) * data[key].options["width"] / data[key].options["height"])
+        attrObj["height"] = options["height"] ? options["height"] : (parseInt(options["width"]) * data[key].options["height"] / data[key].options["width"])
+      }
+
+      // If the user passed in class
+      if (options["class"]) {
+        attrObj["class"] = "octicon octicon-" + key + " " + options["class"]
+        attrObj["class"].trim()
+      }
+
+      // If the user passed in aria-label
+      if (options["aria-label"]) {
+        attrObj["aria-label"] = options["aria-label"]
+        attrObj["role"] = "img"
+
+        // Un-hide the icon
+        delete attrObj["aria-hidden"]
+      }
+    }
+
+    Object.keys(attrObj).forEach(function(option) {
+      attributes.push(option + "=\"" + attrObj[option] + "\"")
+    })
+
+    return attributes.join(" ").trim()
+  }
+
+  // Set the symbol for easy access
+  data[key].symbol = key
+
+  // Set all the default options
+  data[key].options = {
+    "version": "1.1",
+    "width": data[key].width,
+    "height": data[key].height,
+    "viewBox": "0 0 " + data[key].width + " " + data[key].height,
+    "class": "octicon octicon-" + key,
+    "aria-hidden": "true"
+  }
+
+  // Function to return an SVG object
+  data[key].toSVG = function(options) {
+    return "<svg " + htmlAttributes(data[key], options) + ">" + data[key].path + "</svg>"
+  }
+})
+
+// Import data into exports
+module.exports = data
diff --git a/lib/keywords.json → lib/data.json b/lib/keywords.json → lib/data.json
@@ -331,6 +331,12 @@
       "arrow"
     ]
   },
+  "ellipses": {
+    "keywords": [
+      "dot",
+      "more"
+    ]
+  },
   "ellipsis": {
     "keywords": [
       "read",
@@ -346,6 +352,11 @@
       "see"
     ]
   },
+  "file": {
+    "keywords": [
+      "file"
+    ]
+  },
   "file-binary": {
     "keywords": [
       "image",
@@ -489,6 +500,13 @@
       "world"
     ]
   },
+  "grabber": {
+    "keywords": [
+      "mover",
+      "drap",
+      "drop"
+    ]
+  },
   "graph": {
     "keywords": [
       "trend",
@@ -830,6 +848,12 @@
       "broadcast"
     ]
   },
+  "reply": {
+    "keywords": [
+      "reply all",
+      "back"
+    ]
+  },
   "repo": {
     "keywords": [
       "book",
@@ -1118,29 +1142,5 @@
       "star",
       "save"
     ]
-  },
-  "ellipses": {
-    "keywords": [
-      "dot",
-      "more"
-    ]
-  },
-  "file": {
-    "keywords": [
-      "file"
-    ]
-  },
-  "grabber": {
-    "keywords": [
-      "mover",
-      "drap",
-      "drop"
-    ]
-  },
-  "reply": {
-    "keywords": [
-      "reply all",
-      "back"
-    ]
   }
 }
diff --git a/package.json b/package.json
@@ -9,7 +9,6 @@
   "main": "index.js",
   "files": [
     "index.js",
-    "lib",
     "build"
   ],
   "repository": "https://github.com/primer/octicons.git",

diff --git a/test/index.js b/test/index.js
@@ -4,25 +4,28 @@ import fs from 'fs';
 
 const octiconsLib = fs.readdirSync("../lib/svg/");
 
-test('octicon keywords are loaded', t => {
+test('Octicons are loaded', t => {
   t.truthy(octicons, "Didn't find any octicons.");
-  t.not(octicons.keywords.length, 0, "Didn't find any keywords.")
+  t.not(Object.keys(octicons).length, 0, "Didn't find any octicons.")
 });
 
-octiconsLib.forEach( point => {
-  point = point.replace('.svg', '');
-
-  ['keywords'].forEach( filename => {
-    test(filename + '.json contains `' + point + '`', t => {
-      t.truthy(octicons[filename][point], 'Can\'t find the `' + point + '` octicon in ' + filename + '.json');
-    });
-  });
+test('Octicons have keywords', t => {
+  t.truthy(octicons, "Didn't find any octicons.");
+  Object.keys(octicons).forEach( point => {
+    t.truthy(octicons[point].keywords, 'The octicon "' + point + '" doesn\'t have any keywords')
+    t.not(octicons[point].keywords.length, 0, 'The octicon "' + point + '" doesn\'t have any keywords')
+  })
 });
 
-['keywords'].forEach( filename => {
-  Object.keys(octicons[filename]).forEach( point => {
-    test(filename + '.json has the valid octicon `' + point + '`', t => {
-      t.truthy(octiconsLib.indexOf(point+'.svg') >= 0, filename + '.json contains the deleted octicon `' + point + '`, please remove it.' );
-    });
-  });
-});
+test('Every octicon is in ./lib/data.json', t => {
+  octiconsLib.forEach( point => {
+    point = point.replace('.svg', '')
+    t.truthy(octicons[point], './lib/data.json doesn\'t include the octicon "' + point + '"')
+  })
+})
+
+test('No deprecated octicons are in ./lib/data.json', t => {
+  Object.keys(octicons).forEach( point => {
+    t.truthy(octiconsLib.indexOf(point+'.svg') >= 0, './lib/data.json contains the deleted octicon `' + point + '`, please remove it.' );
+  })
+})