@carbon/icon-helpers 0.0.1-alpha.22 → 0.0.1-alpha.26

package/README.md

@@ -1,22 +1,110 @@
-# `@carbon/icon-helpers`
+# @carbon/icon-helpers
 
-> Helpers used alongside icons for digital and software products using the Carbon Design System.
+> Helpers used alongside icons for digital and software products using
+> the Carbon Design System
 
-## Getting Started
+## Getting started
 
-Run the following command using [npm](https://www.npmjs.com/):
+To install `@carbon/icon-helpers` in your project, you will need to
+run the following command using [npm](https://www.npmjs.com/):
 
 ```bash
 npm install -S @carbon/icon-helpers
 ```
 
-If you prefer [Yarn](https://yarnpkg.com/en/), use the following command
-instead:
+If you prefer [Yarn](https://yarnpkg.com/en/), use the following
+command instead:
 
 ```bash
 yarn add @carbon/icon-helpers
 ```
 
-## 🤲 Contributing
+## Usage
 
-To learn more about how to contribute, look [here](/.github/CONTRIBUTING.md)!
+`@carbon/icon-helpers` provides a couple of helpers for rendering `<svg>` nodes in a document, or to help get the correct attributes to
+set on an `<svg>` node. These include:
+
+| Name               | Type                              | Description                                                                  |
+| ------------------ | --------------------------------- | ---------------------------------------------------------------------------- |
+| `getAttributes`    | `(attributes: Object) => Object`  | Get the attributes for an `<svg>` node                                       |
+| `formatAttributes` | `(attributes: Object) => String`  | Format the attributes into a string that can be applied to a node in the DOM |
+| `toString`         | `(descriptor: Object) => String`  | Format the given icon descriptor into a string. Useful for templates         |
+| `toSVG`            | `(descriptor: Object) => DOMNode` | Format the given icon descriptor into a DOM node                             |
+
+For most of the methods, `attributes` corresponds with whatever the
+name and value would be if you were writing the HTML for the `<svg>`.
+For example, if we wanted to set `width` and `height` we would do the
+following:
+
+```js
+const { getAttributes } = require('@carbon/icon-helpers');
+const attributes = getAttributes({ width: 20, height: 20 });
+```
+
+In order for the icon to be considered focusable, you will need to
+provide either `aria-label`, `aria-labelledby`, or `title` in the
+given `attributes` in addition to `tabindex`. For example:
+
+```js
+const { getAttributes } = require('@carbon/icon-helpers');
+const attributes = getAttributes({
+  'aria-label': 'My icon label',
+  tabindex: '0',
+});
+```
+
+### Icon descriptors
+
+An icon descriptor is the term we use to describe icon objects
+exported by `@carbon/icons`. By default, they will have the following
+shape:
+
+```js
+{
+  elem: 'svg',
+  attrs: {
+    xmlns: 'http://www.w3.org/2000/svg',
+    viewBox: '0 0 16 16',
+    width: 16,
+    height: 16,
+  },
+  content: [
+    {
+      elem: 'path',
+      attrs: {
+        d: '...',
+      },
+    },
+  ],
+  name: 'IconName',
+  size: 16,
+}
+```
+
+You can import these definitions directly from `@carbon/icons` and use
+them alongside `toSVG` or `toString` by doing:
+
+```js
+import { IconName } from '@carbon/icons';
+import { toString, toSVG } from '@carbon/icon-helpers';
+
+const iconString = toString(IconName);
+const iconSVG = toSVG({
+  ...IconName,
+  attrs: {
+    ...IconName.attrs,
+    myCustomAttribute: 'myCustomAttributeValue',
+  },
+});
+```
+
+## 🙌 Contributing
+
+We're always looking for contributors to help us fix bugs, build new
+features, or help us improve the project documentation. If you're
+interested, definitely check out our [Contributing Guide](/.github/CONTRIBUTING.md)
+! 👀
+
+## 📝 License
+
+Licensed under the [Apache 2.0 License](/LICENSE).

package/es/index.js

@@ -68,13 +68,22 @@ function _objectWithoutProperties(source, excluded) {
   return target;
 }
 
+/**
+ * Copyright IBM Corp. 2018, 2018
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
 var defaultAttributes = {
   // Reference:
   // https://github.com/IBM/carbon-components-react/issues/1392
   // https://github.com/PolymerElements/iron-iconset-svg/pull/47
   // `focusable` is a string attribute which is why we do not use a boolean here
   focusable: 'false',
-  preserveAspectRatio: 'xMidYMid meet'
+  preserveAspectRatio: 'xMidYMid meet',
+  // Reference:
+  // https://github.com/ckeditor/ckeditor5/issues/668#issuecomment-344844027
+  style: 'will-change: transform;'
 };
 /**
  * Get supplementary HTML attributes for a given <svg> element based on existing
@@ -115,6 +124,12 @@ function getAttributes() {
   return iconAttributes;
 }
 
+/**
+ * Copyright IBM Corp. 2018, 2018
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
 /**
  * Convert an icon descriptor to a String
  */
@@ -146,6 +161,12 @@ function formatAttributes(attrs) {
   }, '');
 }
 
+/**
+ * Copyright IBM Corp. 2018, 2018
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
 /**
  * Convert an icon descriptor to a DOM node.
  */
@@ -158,7 +179,8 @@ function toSVG(descriptor) {
       _descriptor$content = descriptor.content,
       content = _descriptor$content === void 0 ? [] : _descriptor$content;
   var node = document.createElementNS('http://www.w3.org/2000/svg', elem);
-  Object.keys(elem !== 'svg' ? attrs : getAttributes(attrs)).forEach(function (key) {
+  var attributes = elem !== 'svg' ? attrs : getAttributes(attrs);
+  Object.keys(attributes).forEach(function (key) {
     node.setAttribute(key, attrs[key]);
   });
 
@@ -169,4 +191,11 @@ function toSVG(descriptor) {
   return node;
 }
 
-export { getAttributes, formatAttributes, toString, toSVG };
+/**
+ * Copyright IBM Corp. 2018, 2018
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+export { defaultAttributes, getAttributes, formatAttributes, toString, toSVG };

package/lib/index.js

@@ -72,13 +72,22 @@ function _objectWithoutProperties(source, excluded) {
   return target;
 }
 
+/**
+ * Copyright IBM Corp. 2018, 2018
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
 var defaultAttributes = {
   // Reference:
   // https://github.com/IBM/carbon-components-react/issues/1392
   // https://github.com/PolymerElements/iron-iconset-svg/pull/47
   // `focusable` is a string attribute which is why we do not use a boolean here
   focusable: 'false',
-  preserveAspectRatio: 'xMidYMid meet'
+  preserveAspectRatio: 'xMidYMid meet',
+  // Reference:
+  // https://github.com/ckeditor/ckeditor5/issues/668#issuecomment-344844027
+  style: 'will-change: transform;'
 };
 /**
  * Get supplementary HTML attributes for a given <svg> element based on existing
@@ -119,6 +128,12 @@ function getAttributes() {
   return iconAttributes;
 }
 
+/**
+ * Copyright IBM Corp. 2018, 2018
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
 /**
  * Convert an icon descriptor to a String
  */
@@ -150,6 +165,12 @@ function formatAttributes(attrs) {
   }, '');
 }
 
+/**
+ * Copyright IBM Corp. 2018, 2018
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
 /**
  * Convert an icon descriptor to a DOM node.
  */
@@ -162,7 +183,8 @@ function toSVG(descriptor) {
       _descriptor$content = descriptor.content,
       content = _descriptor$content === void 0 ? [] : _descriptor$content;
   var node = document.createElementNS('http://www.w3.org/2000/svg', elem);
-  Object.keys(elem !== 'svg' ? attrs : getAttributes(attrs)).forEach(function (key) {
+  var attributes = elem !== 'svg' ? attrs : getAttributes(attrs);
+  Object.keys(attributes).forEach(function (key) {
     node.setAttribute(key, attrs[key]);
   });
 
@@ -173,6 +195,14 @@ function toSVG(descriptor) {
   return node;
 }
 
+/**
+ * Copyright IBM Corp. 2018, 2018
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+exports.defaultAttributes = defaultAttributes;
 exports.getAttributes = getAttributes;
 exports.formatAttributes = formatAttributes;
 exports.toString = toString;

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@carbon/icon-helpers",
-  "version": "0.0.1-alpha.22",
+  "description": "Helpers used alongside icons for digital and software products using the Carbon Design System",
+  "version": "0.0.1-alpha.26",
   "license": "Apache-2.0",
   "main": "lib/index.js",
   "module": "es/index.js",
@@ -26,7 +27,7 @@
     "clean": "rimraf es lib umd"
   },
   "devDependencies": {
-    "@carbon/bundler": "0.0.1-alpha.22",
+    "@carbon/bundler": "0.0.1-alpha.26",
     "rimraf": "^2.6.2"
   },
   "sideEffects": false

package/umd/index.js

@@ -74,13 +74,22 @@
     return target;
   }
 
+  /**
+   * Copyright IBM Corp. 2018, 2018
+   *
+   * This source code is licensed under the Apache-2.0 license found in the
+   * LICENSE file in the root directory of this source tree.
+   */
   var defaultAttributes = {
     // Reference:
     // https://github.com/IBM/carbon-components-react/issues/1392
     // https://github.com/PolymerElements/iron-iconset-svg/pull/47
     // `focusable` is a string attribute which is why we do not use a boolean here
     focusable: 'false',
-    preserveAspectRatio: 'xMidYMid meet'
+    preserveAspectRatio: 'xMidYMid meet',
+    // Reference:
+    // https://github.com/ckeditor/ckeditor5/issues/668#issuecomment-344844027
+    style: 'will-change: transform;'
   };
   /**
    * Get supplementary HTML attributes for a given <svg> element based on existing
@@ -121,6 +130,12 @@
     return iconAttributes;
   }
 
+  /**
+   * Copyright IBM Corp. 2018, 2018
+   *
+   * This source code is licensed under the Apache-2.0 license found in the
+   * LICENSE file in the root directory of this source tree.
+   */
   /**
    * Convert an icon descriptor to a String
    */
@@ -152,6 +167,12 @@
     }, '');
   }
 
+  /**
+   * Copyright IBM Corp. 2018, 2018
+   *
+   * This source code is licensed under the Apache-2.0 license found in the
+   * LICENSE file in the root directory of this source tree.
+   */
   /**
    * Convert an icon descriptor to a DOM node.
    */
@@ -164,7 +185,8 @@
         _descriptor$content = descriptor.content,
         content = _descriptor$content === void 0 ? [] : _descriptor$content;
     var node = document.createElementNS('http://www.w3.org/2000/svg', elem);
-    Object.keys(elem !== 'svg' ? attrs : getAttributes(attrs)).forEach(function (key) {
+    var attributes = elem !== 'svg' ? attrs : getAttributes(attrs);
+    Object.keys(attributes).forEach(function (key) {
       node.setAttribute(key, attrs[key]);
     });
 
@@ -175,6 +197,14 @@
     return node;
   }
 
+  /**
+   * Copyright IBM Corp. 2018, 2018
+   *
+   * This source code is licensed under the Apache-2.0 license found in the
+   * LICENSE file in the root directory of this source tree.
+   */
+
+  exports.defaultAttributes = defaultAttributes;
   exports.getAttributes = getAttributes;
   exports.formatAttributes = formatAttributes;
   exports.toString = toString;