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

package/README.md

@@ -19,6 +19,85 @@ command instead:
 yarn add @carbon/icon-helpers
 ```
 
+## Usage
+
+`@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

package/es/index.js

@@ -83,7 +83,7 @@ var defaultAttributes = {
   preserveAspectRatio: 'xMidYMid meet',
   // Reference:
   // https://github.com/ckeditor/ckeditor5/issues/668#issuecomment-344844027
-  style: 'transform: translate3d(0, 0, 0);'
+  style: 'will-change: transform;'
 };
 /**
  * Get supplementary HTML attributes for a given <svg> element based on existing

package/lib/index.js

@@ -87,7 +87,7 @@ var defaultAttributes = {
   preserveAspectRatio: 'xMidYMid meet',
   // Reference:
   // https://github.com/ckeditor/ckeditor5/issues/668#issuecomment-344844027
-  style: 'transform: translate3d(0, 0, 0);'
+  style: 'will-change: transform;'
 };
 /**
  * Get supplementary HTML attributes for a given <svg> element based on existing

package/package.json

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

package/umd/index.js

@@ -89,7 +89,7 @@
     preserveAspectRatio: 'xMidYMid meet',
     // Reference:
     // https://github.com/ckeditor/ckeditor5/issues/668#issuecomment-344844027
-    style: 'transform: translate3d(0, 0, 0);'
+    style: 'will-change: transform;'
   };
   /**
    * Get supplementary HTML attributes for a given <svg> element based on existing