core-icon.html

<!--
Copyright (c) 2014 The Polymer Project Authors. All rights reserved.
This code may only be used under the BSD style license found at http://polymer.github.io/LICENSE.txt
The complete set of authors may be found at http://polymer.github.io/AUTHORS.txt
The complete set of contributors may be found at http://polymer.github.io/CONTRIBUTORS.txt
Code distributed by Google as part of the polymer project is also
subject to an additional IP rights grant found at http://polymer.github.io/PATENTS.txt
-->
<!--

The `core-icon` element displays an icon. By default an icon renders as a 24px square.

Example using src:

    <core-icon src="star.png"></core-icon>

Example setting size to 32px x 32px:

    <core-icon class="big" src="big_star.png"></core-icon>

    <style>
      .big {
        height: 32px;
        width: 32px;
      }
    </style>

The core elements include several sets of icons. 
To use the default set of icons, import  `core-icons.html` and use the `icon` attribute to specify an icon:

    <link rel="import" href="/components/core-icons/core-icons.html">

    <core-icon icon="menu"></core-icon>
    
To use a different built-in set of icons, import  `core-icons/<iconset>-icons.html`, and
specify the icon as `<iconset>:<icon>`. For example:

    <link rel="import" href="/components/core-icons/communication-icons.html">

    <core-icon icon="communication:email"></core-icon>
    
You can also create custom icon sets of bitmap or SVG icons. 

Example of using an icon named `cherry` from a custom iconset with the ID `fruit`:

    <core-icon icon="fruit:cherry"></core-icon>

See [core-iconset](https://www.polymer-project.org/0.5/docs/elements/core-iconset.html) and [core-iconset-svg](https://www.polymer-project.org/0.5/docs/elements/core-iconset-svg.html) for more information about
how to create a custom iconset.

See [core-icons](https://www.polymer-project.org/0.5/components/core-icons/demo.html) for the default set of icons.

@group Polymer Core Elements
@element core-icon
@homepage polymer.github.io
-->
<link rel="import" href="../core-iconset/core-iconset.html">

<link rel="stylesheet" href="core-icon.css" shim-shadowdom>

<polymer-element name="core-icon" attributes="src icon alt">
<script>
(function() {
  
  // mono-state
  var meta;
  
  Polymer('core-icon', {

    /**
     * The URL of an image for the icon. If the src property is specified,
     * the icon property should not be.
     *
     * @attribute src
     * @type string
     * @default ''
     */
    src: '',

    /**
     * Specifies the icon name or index in the set of icons available in
     * the icon's icon set. If the icon property is specified,
     * the src property should not be.
     *
     * @attribute icon
     * @type string
     * @default ''
     */
    icon: '',

    /**
     * Alternative text content for accessibility support.
     * If alt is present and not empty, it will set the element's role to img and add an aria-label whose content matches alt.
     * If alt is present and is an empty string, '', it will hide the element from the accessibility layer
     * If alt is not present, it will set the element's role to img and the element will fallback to using the icon attribute for its aria-label.
     * 
     * @attribute alt
     * @type string
     * @default ''
     */
    alt: null,

    observe: {
      'icon': 'updateIcon',
      'alt': 'updateAlt'
    },

    defaultIconset: 'icons',

    ready: function() {
      if (!meta) {
        meta = document.createElement('core-iconset');
      }

      // Allow user-provided `aria-label` in preference to any other text alternative.
      if (this.hasAttribute('aria-label')) {
        // Set `role` if it has not been overridden.
        if (!this.hasAttribute('role')) {
          this.setAttribute('role', 'img');
        }
        return;
      }
      this.updateAlt();
    },

    srcChanged: function() {
      var icon = this._icon || document.createElement('div');
      icon.textContent = '';
      icon.setAttribute('fit', '');
      icon.style.backgroundImage = 'url(' + this.src + ')';
      icon.style.backgroundPosition = 'center';
      icon.style.backgroundSize = '100%';
      if (!icon.parentNode) {
        this.appendChild(icon);
      }
      this._icon = icon;
    },

    getIconset: function(name) {
      return meta.byId(name || this.defaultIconset);
    },

    updateIcon: function(oldVal, newVal) {
      if (!this.icon) {
        this.updateAlt();
        return;
      }
      var parts = String(this.icon).split(':');
      var icon = parts.pop();
      if (icon) {
        var set = this.getIconset(parts.pop());
        if (set) {
          this._icon = set.applyIcon(this, icon);
          if (this._icon) {
            this._icon.setAttribute('fit', '');
          }
        }
      }
      // Check to see if we're using the old icon's name for our a11y fallback
      if (oldVal) {
        if (oldVal.split(':').pop() == this.getAttribute('aria-label')) {
          this.updateAlt();
        }
      }
    },

    updateAlt: function() {
      // Respect the user's decision to remove this element from
      // the a11y tree
      if (this.getAttribute('aria-hidden')) {
        return;
      }

      // Remove element from a11y tree if `alt` is empty, otherwise
      // use `alt` as `aria-label`.
      if (this.alt === '') {
        this.setAttribute('aria-hidden', 'true');
        if (this.hasAttribute('role')) {
          this.removeAttribute('role');
        }
        if (this.hasAttribute('aria-label')) {
          this.removeAttribute('aria-label');
        }
      } else {
        this.setAttribute('aria-label', this.alt ||
                                        this.icon.split(':').pop());
        if (!this.hasAttribute('role')) {
          this.setAttribute('role', 'img');
        }
        if (this.hasAttribute('aria-hidden')) {
          this.removeAttribute('aria-hidden');
        }
      }
    }

  });
  
})();
</script>

</polymer-element>