## 1. Project Overview & Quickstart (addyosmani/platform.min.js)

# platform.min.js

Open-source repository addyosmani/platform.min.js

### Repository Details
- **Repository:** [addyosmani/platform.min.js](https://github.com/addyosmani/platform.min.js)
- **Primary Language:** Code

*Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.*

## 2. Official Technical Reference & Guides (addyosmani/docs)

## File: README.md

Polymer docs are mostly in Markdown with some HTML. [Jekyll][jekyll] is used to generate the static HTML for the site. The output is generated into a folder called `_site` and served from Google App Engine.

## Prereqs and installation requirements

We use Jekyll 1.4.2+ and [Grunt][grunt] to generate the documentation. You'll need to install the requirements before working on the docs (these instructions assume [NPM is already installed](http://nodejs.org/download/)):

    sudo gem install jekyll
    sudo gem install kramdown
    sudo npm install grunt-cli
    npm install

You'll also need the App Engine SDK to run the dev_appserver and preview the docs locally. [Download the SDK](https://developers.google.com/appengine/downloads).

### Check out the documentation

Checkout this repo:

    git clone https://github.com/Polymer/docs.git --recursive

Create a directory `polymer-all/projects` and run the `pull-all-projects.sh` script in that directory:

    cd docs/polymer-all
    mkdir projects; cd projects
    ../tools/bin/pull-all-projects.sh

This populates `projects` with a bunch of repositories. You'll periodically need to re-run `pull-all-projects.sh` whenever the site is released.

Next, create a `components` folder in the top level `docs` directory and run `pull-all-polymer.sh` and `pull-all-elements.sh` in it:

    cd ../..
    mkdir components; cd components
    ../polymer-all/tools/bin/pull-all-polymer.sh
    ../polymer-all/tools/bin/pull-all-elements.sh

**Note:** these scripts can take some time to download.

You should now be able to build the docs successfully. Run this in the main folder:

    grunt docs

## Making edits and previewing changes

This repo (`Polymer/docs`) is where the documentation source files live. To make a change:

1. First, up the App Engine dev server in this folder (`dev_appserver.py .`) to preview the docs.
1. Make your edits.
1. To build the docs, run `grunt` in base of the docs diretory you checked out. This starts up jekyll and watches for changes as you make edits. Be sure to run `npm install` in your docs directory if it's a new checkout. It can take some time for the docs to fully regenerate and be copied to the output folder...keep refreshing!

Jekyll generates the static site in a folder named `_site`. **Note**: If you're not running jekyll to rebuild the site, you won't see your changes in the dev server.

Once your changes look good, `git commit` them and push.

## Building and pushing the docs

**Note**: only project owners can publish the documentation.

If you have things checked out correctly in `components` and `polymer-all`, you should be able to generate the prodcution documentation using:

    grunt docs

It's a good idea to do this before pushing the docs, as it runs a number of grunt tasks. Verify things went well.

Last step is to push the docs to App Engine. In your `Polymer/docs` directory, run:

    ./scripts/deploy_site.sh

This script builds the site, api docs, runs Vulcanizer over the imports, and deploys to App Engine.

## Polymer release

When we push a new version of Polymer, the site should be updated to use it. In addition,
the element reference and other projects will need updating.

First, update the submodules in /docs:

    git submodule foreach git pull origin master
    git submodule update

Update the projects:

    cd polymer-all/projects
    ../tools/bin/pull-all-projects.sh
    
Then, update the elements and polyfills:

    cd components
    ../polymer-all/tools/bin/pull-all-polymer.sh
    ../polymer-all/tools/bin/pull-all-elements.sh

Once these are updated, you need to update some versions for the docs:

- Increment the version in `app.yaml`;
- Update the Polymer release version in `_config.yml`.
- Add a link point link to the release notes in `changelog.md`.

Build the docs:

    grunt docs
    
At this point, run the dev server and preview things locally to make sure nothing is terribly
broken after Polymer and the elements have been updated. 

Lastly, run the deploy script:

    ./scripts/deploy_site.sh

Last thing is to switch the app version in the App Engine admin console. To make the docs live, hit up https://appengine.google.com/deployment?&app_id=s~polymer-project and select the version you just deployed.

[jekyll]: http://jekyllrb.com/
[grunt]: http://gruntjs.com/

---

## File: doc_themes/footstrap/README.md

yuidoc-bootstrap-theme
======================

A revamped yuidoc theme with bootstrap

---

## File: doc_themes/bootstrap/README.md

yuidoc-bootstrap-theme
======================

A revamped yuidoc theme with bootstrap

---

## File: docs/polymer/databinding.md

---
layout: default
title: Data-binding
---

## Introduction

{{site.project_title}} supports two-way data binding and uses the term to describe a way to write _dynamic_ HTML _using_ HTML. A set of platform technologies and "prollyfills" enable this behavior:

* [HTML Template element](http://www.html5rocks.com/tutorials/webcomponents/template/) (`<template>`)
* [Template Bindings](/platform/template.html) (_prollyfill_) - describes how `<template>` manages instance fragments.
* [`Node.bind()`](/platform/node_bind.html) (_prollyfill_) - describes how DOM nodes are bound to data values.
* [`Object.observe()`](http://updates.html5rocks.com/2012/11/Respond-to-change-with-Object-observe)
* [Mutation Observers](https://developer.mozilla.org/en-US/docs/DOM/MutationObserver)

When used together, these primitives extend HTML and the DOM APIs to support a sensible
separation between the UI (DOM) of application and its underlying data (model). Updates to the model are reflected in the DOM and user input into the DOM is immediately assigned to the model.

## The basics

{{site.project_title}}'s data-binding features hinge on the `<template>` element and double mustache {%raw%}`{{}}`{%endraw%} syntax.

- [Expressions](/docs/polymer/expressions.html)
- [Filters](/docs/polymer/filters.html)

### An example

There's plenty of detail, but it all hinges on the `<template>` element. Let's walk through a simple example which demonstrates the basics.

{%raw%}
    
      <template>
        
          <template id="greeting" repeat="{{s in salutations}}">
            <li>{{s.what}}: </li>
          </template>
        
      </template>
      <script>
        Polymer('greeting-tag', {
          ready: function() {
            this.salutations = [
              {what: 'Hello', who: 'World'},
              {what: 'GoodBye', who: 'DOM APIs'},
              {what: 'Hello', who: 'Declarative'},
              {what: 'GoodBye', who: 'Imperative'}
            ];
          }
        });
      </script>
    
{%endraw%}

{%comment%}
    <script src="platform.min.js"></script>
    
      <template id="greeting" repeat="{{ salutations }}">
        <li>{{ what }}: </li>
      </template>
    
    <script>
    var t = document.getElementById('greeting');
    var model = {
      salutations: [
        { what: 'Hello', who: 'World' },
        { what: 'GoodBye', who: 'DOM APIs' },
        { what: 'Hello', who: 'Declarative' },
        { what: 'GoodBye', who: 'Imperative' }
      ]
    };
    t.model = model;

    // Needed to detect model changes if Object.observe() is not available.
    Platform.performMicrotaskCheckpoint();
    </script>
    
{%endcomment%}

This example should look mostly familiar to anyone who knows HTML, but there are a couple novel things going on:

#### The `<template>` element

The [HTML Template element](http://www.html5rocks.com/tutorials/webcomponents/template/) allows you to declare chunks of inert HTML that may be cloned, activated, and used at some laster point.

If you loaded the above example without `<script src="platform.min.js"></script>`, that's about all `<template>` would do.

However, [Template Binding](/platform/template.html) teaches `<template>` some new tricks:

* Instruct DOM nodes to derive their value from JavaScript data by binding them to the data provided.
* Maintain a fragment of DOM (or "instance fragment") for each item in an array.
* Conditionally stamp out one or more instance fragments, based on whether  some data value is true or not.
* ...And lots more.

But back to the example. Our template...

{%raw%}
    <template id="greeting" repeat="{{ salutations }}">
      <li>{{ what }}: </li>
    </template>
{%endraw%}

...defines what each instance will look like when stamped out. In this case, it contains a `<li>` with a text node and an `` as its children. The mustaches {%raw%}`{{}}`{%endraw%} mean _"bind data here"_. The {%raw%}`repeat="{{ salutations }}"`{%endraw%} tells the template to ensure there is one instance fragment for each element in the salutations array.

In `<script>`, we create a model:

    var model = {
      salutations: [
        { what: 'Hello', who: 'World' },
        { what: 'GoodBye', who: 'DOM APIs' },
        { what: 'Hello', who: 'Declarative' },
        { what: 'GoodBye', who: 'Imperative' }
      ]
    };

Notice that this is just JavaScript data: _there’s no need to import your data into special observable objects_. The template is set in motion by binding the model data to it:

    t.model = model;

Now the template is off to the races. Here's the result:



and here's what the DOM looks like:



You can see that the template stamped out four instances immediately following its position in the document. All nodes within an instance have a property called `templateInstance` which points to an instance descriptor. The descriptor indicates the extent (first and last nodes) of the instance, as well as the `model` data for which the instance was produced:



Now, remember we said data-binding teaches the DOM to derive its values from JavaScript data? If we change a value in our model, the DOM observes the change and updates accordingly:



However, the DOM doesn’t just observe data in the model, if DOM elements which collect user input are bound, they _push_ the collected value into the model:



Lastly, let's look at what happens when we alter the contents of the `model.salutations` array:



The `<template>` is `repeat`ing which means that it ensures there is one instance for each item in the array. We removed two elements from the middle of salutations and inserted one in their place. The `<template>` responded by removing the two corresponding instances and creating a new one in the right location.

Getting the idea? Data-binding allows you author your HTML _using_ HTML which contains information about _where data goes_ and directives which _control the document's structure_ -- all depending on the data you provide it.

### Where to go from here?

If you are new to data-binding, the best to place to go is to the look at the [How-To examples](https://github.com/Polymer/TemplateBinding/tree/master/examples/how_to). These are little examples which succinctly demonstrate how to use data-binding to accomplish things that frequently are required for real web apps:

_Binding to DOM values:_

* [Binding to text values](https://github.com/Polymer/TemplateBinding/tree/master/examples/how_to/bind_to_text.html): How to insert values into the DOM that render as text.
* [Binding to attributes](https://github.com/Polymer/TemplateBinding/tree/master/examples/how_to/bind_to_attributes.html): How to insert values into element attributes
* [Conditional attributes](https://github.com/Polymer/TemplateBinding/tree/master/examples/how_to/conditional_attributes.html): How to bind to attributes such that the attribute is only present if the binding value is “truthy”.
* [Binding to input elements](https://github.com/Polymer/TemplateBinding/tree/master/examples/how_to/bind_to_input_elements.html): How to bind bi-directionally with input elements.
* [Custom bindings](https://github.com/Polymer/TemplateBinding/tree/master/examples/how_to/custom_syntax.html): How to implement a custom element which has a specialized interpretation of a binding.

_Using `<template>` to produce DOM structures:_

* [Conditionals](https://github.com/Polymer/TemplateBinding/tree/master/examples/how_to/conditional_template.html): How to control whether instance fragments are produced based on the value of a binding.
* [Nested templates](https://github.com/Polymer/TemplateBinding/tree/master/examples/how_to/nested_templates.html): How to accomplish nested template production.
* [Re-using templates](https://github.com/Polymer/TemplateBinding/tree/master/examples/how_to/template_ref.html): How to define a template once and use it in more than one location.
* [Recursive templates](https://github.com/Polymer/TemplateBinding/tree/master/examples/how_to/recursive_templates.html): How to produce tree-structure DOM whose depth is dependent on the data to which it is bound.

#### Advanced Topics


  **IMPORTANT**: The advanced topics documentation have yet to be created.


* DOM Stability: {{site.project_title}} makes every effort to maintain the state of DOM nodes (event listeners, expandos, etc...). Understand why this is important and how it works.
* Imperative DOM mutation: You should rarely need to directly manipulate the DOM, but if you do, it's allowed. Learn the simple rules of how {{site.project_title}} will react if you manipulate the DOM it is managing.
* Asynchronous processing model: {{site.project_title}} responds asynchronously to changes in data and DOM. Learn why this is good and what it means for your application.
* Chained observation

---

## File: docs/polymer/expressions.md

---
layout: default
title: Expressions
---



{% include toc.html %}

Within a `` you can use {{site.project_title}}'s [expression library](https://github.com/polymer/polymer-expressions) to write inline expressions, statements, named scopes, and iterative markup, anywhere {%raw%}`{{}}`{%endraw%} bindings are used.

## Inline expressions

{{site.project_title}} supports expressions in {%raw%}`{{}}`{%endraw%} with a strict
subset of the JavaScript language. In order to use this feature, it's
important to understand its behavior and limitations:

- The goal for inline expressions is to allow the expression of simple value
concepts and relationships. It is generally bad practice to put complex logic
into your HTML (view).
- Expressions are never run (e.g. `eval`) as page script. They cannot access any
global state (e.g. `window`). They are parsed and converted to a simple
interpreted form which is provided the present values of paths contained in
the expression.

The specific subset of JavaScript which is supported is:

| Feature | Example | Explanation
|---------|
|Identifiers & paths | `foo`, `foo.bar.baz` | These values are treated as relative to the local model, extracted, observed for changes and cause the expression to be re-evaluated if one or more has changed.
| Logical not operator | `!` |
| Unary operators | `+foo`, `-bar` | Converted to `Number`. Or converted to `Number`, then negated.
| Binary operators | `foo + bar`, `foo - bar`, `foo * bar` | Supported: `+`, `-`, `*`, `/`, `%`
| Comparators | `foo < bar`, `foo != bar`, `foo == bar` | Supported: `<`, `>`, `<=`, `>=`, `==`, `!=`, `===`, `!==`
| Logical comparators | `foo && bar || baz` | Supported: `||`, `&&`
| Ternary operator | `a ? b : c` |
| Grouping (parenthesis) | `(a + b) * (c + d)` |
| Literal values | numbers, strings, `null`, `undefined` | Escaped strings and non-decimal numbers are not supported. |
| Array & Object initializers | `[foo, 1]`, `{id: 1, foo: bar}` |
{: .table }

### Statements

Expressions are parsed when they're within a mustache ({% raw %}`{{}}`{% endraw %}).
The expression can be a single statement, or an object.

Whenever the value of one or more paths in the expression change, the value of the expression re-evaluated and the result inserted as the value of the mustache:

{% raw %}
    Jill has {{ daughter.children.length + son.children.length }} grandchildren
{% endraw %}

may result in:

    Jill has 100 grandchildren

### Filters

{{site.project_title}} supports [filters](/docs/polymer/filters.html) for for use
with expressions.

## Single-use bindings

Experimental

Anywhere you use {% raw %}`{{}}`{% endraw %} in expressions, you can now use double brackets (`[[]]`)
to setup a one-time binding. The binding becomes inactive after {{site.project_title}}
sets its value for the first time.

Example:

    

One time bindings can potentially be a performance win if you don't need the overhead of setting up property observation.

## Named scopes

Named scopes are useful for referencing a model value from an "outer" model "scope".
For example:

{% raw %}
    <template repeat="{{ user in users }}">
      {{ user.name }}
      <template repeat="{{ file in user.files }}">
        {{ user.name }} owners {{ file.name }}
      </template>
    </template>
{% endraw %}

You can also use the key/value notation to get at the index of the current iteration:

{% raw %}
    <template repeat="{{ user, i in users }}">
      {{ user.name }}
      <template repeat="{{ file, j in user.files }}">
        {{ i }}:{{ j }} {{ user.name }} owners {{ file.name }}
      </template>
    </template>
{% endraw %}

The scope naming is available (but optional) inside the `template`, `bind`, and `repeat` directives.

{% raw %}
- `bind` syntax: `<template bind="{{ expression as identifier }}">`
- `repeat` syntax: `<template repeat="{{ identifier in expression }}">`, `<template repeat="{{ val, i in expression }}">`
{% endraw %}

**Note:** that `expression` can be a simple identifier, a path or a full
expression (including Object and Array literals).
{: .alert .alert-info }

### Nested scoping rules

If a `<template>` using a named scoped contains children `<template>`s,
all ancestor scopes are visible, up-to and including the first ancestor **not** using a named scope.

{% raw %}
    <template bind="{{ foo as foo }}">
      
      <template bind="{{ foo.bar as bar }}">
        
        <template bind="{{ bar.bat }}">
          
          <template bind="{{ boo as bot }}">
            
          </template>
        </template>
      </template>
    </template>
{% endraw %}

## Binding to attributes

Binding expressions to certain attributes can produce side effects in browsers that don't implement `<template>` natively. For example, running {% raw %}``{% endraw %} under the polyfill produces a network request that 404s.

In addition, browsers such as IE sanitize certain attributes, disallowing {% raw %}`{{}}`{% endraw %} replacements in their text.

To counterattack these side effects, bindings in certain attributes can be prefixed with "_":

{% raw %}
    
    
    <a _href="{{ url }}">Link</a>
    
{% endraw %}

---

## File: docs/polymer/filters.md

---
layout: default
title: Filters
---

{{site.project_title}} supports several default filters for working with data. They're used in {% raw %}`{{}}`{% endraw %} [expressions](/docs/polymer/filters.html) by piping an object (containing key/value pairs) to the filter:

{% raw %}
    {{ {...} | filterName }}
{% endraw %}

The value of the mustache will include the space-separated keys from the object whose corresponding expressions are truthy.

## tokenList

The `tokenList` filter is useful for binding to the `class` attribute. It allows you
to dynamically set/remove class names based on the object passed to it. If the object
key is truthy, the name will be applied as a class. 

For example:

{% raw %}
     
{% endraw %}

results in the follow if `user.selected == true` and `user.type == 'super'`:

     

## styleObject

For simple property values, {{site.project_title}} allows you to bind to the `style`
attribute directory:

{% raw %}
    {{color}}
{% endraw %}

If the element's `color` property is "red", this results in the following:

    red

However, for the non-literal case (the binded value is an object) use the `styleObject` filter:

{% raw %}
    ...

    
    {{color}}
{% endraw %}

In this examples `styles` is an object of the form `{color: 'red', background: 'blue'}`.

---

## File: docs/polymer/styling.md

---
layout: default
title: Styling reference
---

{% include toc.html %}

**Note:** styling {{site.project_title}} elements is no different than styling custom elements.
For a complete guide on the basics, see "[A Guide to Styling Elements](/articles/styling-elements.html)".
{: .alert }

In addition to the [standard features for styling Custom Elements](/articles/styling-elements.html), {{site.project_title}} contains extra goodies for fully controlling element styling. This document outlines those features, including FOUC prevention, the specifics on how the the Shadow DOM polyfill applies styles, and workarounds for current limitations.

## Inheriting / resetting outside styles

{{site.project_title}} has first-class support for Shadow DOM's `applyAuthorStyles` and `resetStyleInheritance`. To use with your element, define either in your `prototype`:

    Polymer('x-foo', {
      applyAuthorStyles: true,
      resetStyleInheritance: true
      ...
    });

For more information, see "[A Guide to Styling Elements](/articles/styling-elements.html#inheriting--resetting-outside-styles)".

## FOUC prevention

Before custom elements [upgrade](http://www.html5rocks.com/tutorials/webcomponents/customelements/#upgrades) they may display incorrectly. To help mitigate [FOUC](http://en.wikipedia.org/wiki/Flash_of_unstyled_content) issues, {{site.project_title}} provides
a polyfill solution for the [`:unresolved` pseudo class](/articles/styling-elements.html#preventing-fouc). The `[unresolved]` attribute initially hides the element it's applied to:

    <x-foo unresolved>If you see me, elements are upgraded!</x-foo>
    
    

Class name | Behavior when applied to an element
|-
`[unresolved]` | Makes the element `opacity: 0; display: block; overflow: hidden`.
`[resolved]` | Fades-in the element over 200ms.
{: .table }

Upon [`WebComponentsReady`](/polymer.html#WebComponentsReady) firing, {{site.project_title}} runs the following steps:

1. removes the `[unresolved]` attribute from elements that have it
2. adds the `[resolved]` attribute
3. removes `[resolved]` on the first `transitionend` event the element receives

### Unveiling elements after boot time {#unveilafterboot}

The veiling process can be used to prevent FOUC at times other than page load. To do so, apply the `[unresolved]` attribute to the desired elements and swap it out for the `[resolved]` attribute when the elements should be displayed. For example,

    element.setAttribute('unresolved', '');

    // ... some time late ...
    element.setAttribute('resolved', '');
    element.removeAttribute('unresolved');

## Polyfill styling directives

When running under the polyfill, {{site.project_title}} has `@polyfill-*`
directives to give you more control for how Shadow DOM styling is shimmed.

### @polyfill {#at-polyfill}

The `@polyfill` directive is used to replace a native CSS selector with one that
will work under the polyfill. For example, targeting distributed nodes using `::content` only works under native Shadow DOM. Instead, you can tell {{site.project_title}} to replace said
rules with ones compatible with the polyfill.

To replace native rules, place `@polyfill` inside a CSS comment above the 
style rule you want to replace. The string next to `"@polyfill"` indicates a
CSS selector to replace the next style rule with. For example:

    /* @polyfill .bar */
    ::content .bar {
      color: red;
    }
    
    /* @polyfill :host > .bar */
    ::content .bar {
      color: blue;
    }

    /* @polyfill .container > * */
    ::content > * {
      border: 1px solid black;
    }

Under native Shadow DOM nothing changes. Under the polyfill the native selector 
s replaced with the one in the `@polyfill` comment above it:

    x-foo .bar {
      color: red;
    }
    
    x-foo > .bar {
      color: blue;
    }

    x-foo .container > * {
      border: 1px solid black;
    }


**Tip:** If you use a CSS preprocessor, be careful that it doesn't strip out the `@polyfill` comments.
{: .alert .alert-error }

### @polyfill-rule {#at-polyfill-rule}

The `@polyfill-rule` directive is used to create a style rule that should apply *only* when the Shadow DOM polyfill is in use. It's a useful catch-all when it's not possible to write a rule that can automatically morph between native Shadow DOM and polyfill Shadow DOM. Because of the simulated styling {{site.project_title}} provides, you should rarely need to use this directive.

To create a rule that only applies under the polyfill, place the `@polyfill-rule` directive entirely inside a CSS comment:

    /* @polyfill-rule .foo {
      background: red;
    } */
     
    /* @polyfill-rule :host.foo .bar {
      background: blue;
    } */

This has no effect under native Shadow DOM but under the polyfill, the comment is removed and the selector prefixed with the element name:

    x-foo .foo {
      background: red;
    }
    
    x-foo.foo .bar {
      background: blue;
    }

### @polyfill-unscoped-rule {#at-polyfill-unscoped-rule}

`@polyfill-unscoped-rule` is exactly the same as `@polyfill-rule` except that the rules inside it are not scoped by the polyfill. The rule you write is exactly what will be applied.

`@polyfill-unscoped-rule` should only be needed in rare cases. {{site.project_title}} uses CSSOM to modify styles and there are a several known rules that don't round-trip correctly via CSSOM (on some browsers). One example using CSS `calc()` in Safari. It's only in these rare cases that `@polyfill-unscoped-rule` should be used.

{%comment%}
## Making styles global

According to CSS spec, certain @-rules like `@keyframe` and `@font-face`
cannot be defined in a `<style scoped>`. Therefore, they will not work in Shadow DOM.
Instead, you'll need to declare their definitions outside the element. 

Stylesheets and `<style>` elements in an HTML import are included in the main document automatically:

    <link rel="stylesheet" href="animations.css">

    
      <template>...</template>
    

Example of defining a global `<style>`:

    <style>
      @-webkit-keyframes blink {
        to { opacity: 0; }
      }
    </style>

    
      <template>
        <style>
          :host {
            -webkit-animation: blink 1s cubic-bezier(1.0,0,0,1.0) infinite 1s;
          }
        </style>
        ...
      </template>
    

{{site.project_title}} also supports making a `<style>` or inline stylesheet global using the
`polymer-scope="global"` attribute.

**Example:** making a stylesheet global

    
      <template>
        <link rel="stylesheet" href="fonts.css" polymer-scope="global">
        ...
      </template>
    

Stylsheets that use `polymer-scope="global"` are moved to the `<head>` of the main page. This happens once.

**Example:** Define and use CSS animations in an element

    
      <template>
        <style polymer-scope="global">
          @-webkit-keyframes blink {
            to { opacity: 0; }
          }
        </style>
        <style>
          :host {
            -webkit-animation: blink 1s cubic-bezier(1.0,0,0,1.0) infinite 1s;
          }
        </style>
        ...
      </template>
    

**Note:** `polymer-scope="global"` should only be used for stylesheets or `<style>`
that contain rules which need to be in the global scope (e.g. `@keyframe` and `@font-face`).
{: .alert .alert-error}
{%endcomment%}

## Polyfill details

### Handling scoped styles

Native Shadow DOM gives us style encapsulation for free via scoped styles. For browsers
that lack native support, {{site.project_title}}'s polyfills attempt to shim _some_
of the scoping behavior.

Because polyfilling the styling behaviors of Shadow DOM is difficult, {{site.project_title}}
has opted to favor practicality and performance over correctness. For example,
the polyfill's do not protect Shadow DOM elements against document level CSS.
 
When {{site.project_title}} processes element definitions, it looks for `<style>` elements
and stylesheets. It removes these from the custom element's Shadow DOM `<template>`, rejiggers them according to the rules below, and appends a `<style>` element to the main document with the reformulated rules.

#### Reformatting rules

1. **Replace `:host`, including `:host(<compound selector>)` by prefixing with the element's tag name**

      For example, these rules inside an `x-foo`:

        
          <template>
            <style>
              :host { ... }
              :host:hover { ... }
              :host(.foo) > .bar { ... }
            </style>
          ...

      becomes:

        
          <template>
            <style>
              x-foo { ... }
              x-foo:hover { ... }
              x-foo.foo > .bar, .foo x-foo > bar {...}
            </style>
          ...

1. **Prepend selectors with the element name, creating a descendant selector**.
This ensures styling does not leak outside the element's shadowRoot (e.g. upper bound encapsulation).

      For example, this rule inside an `x-foo`:

        
          <template>
            <style>
              div { ... }
            </style>
          ...

      becomes:

        
          <template>
            <style>
              x-foo div { ... }
            </style>
          ...

      Note, this technique does not enforce lower bound encapsulation. For that,
      you need to [forcing strict styling](#strictstyling).

1. **Replace `^` and `^^`** with a `<space>` character.

### Forcing strict styling {#strictstyling}

By default, {{site.project_title}} does not enforce lower bound styling encapsulation.
The lower bound is the boundary between insertion points and the shadow host's children.

You can turn lower bound encapsulation by setting `Platform.ShadowCSS.strictStyling`:

    Platform.ShadowCSS.strictStyling = true

This isn't the yet the default because it requires that you add the custom element's name as an attribute on all DOM nodes in the shadowRoot (e.g. ``).

---

## File: docs/elements/index.md

---
layout: default
title: Polymer element reference
---

**Note:** These elements and their documentation are very early.
The "source" links below point to commented code where you can learn more about
how to use the element.
{: .alert .alert-info}

{% include toc.html %}

## Elements

> Utility elements that do not render UI

Install everything:

    bower install Polymer/polymer-elements

---

<section class="element-list">
{%comment%}
{% include_external /polymer-elements/docs/classes/polymer-file.html %}
{%endcomment%}

{% directory dir:components tag:div glob:polymer-* blacklistglob:polymer-ui-* blacklist:"polymer-dev polymer-expressions polymer-elements polymer-ui-elements" %}
</section>

---

## UI Elements

> Basic UI components

Install everything:

    bower install Polymer/polymer-ui-elements

<section class="element-list">
{% directory dir:components tag:div glob:polymer-ui-* blacklist:"polymer-ui-elements" %}
</section>

---

## File: docs/elements/other.md

---
layout: default
title: Toolkit-UI Elements
---

Old and possibly outdated UI experiments.

**Repository:** [github.com/Polymer/toolkit-ui](https://github.com/Polymer/toolkit-ui)

<section class="element-list">
{% directory branch:master dir:polymer-all/toolkit-ui/elements tag:div glob:g-* %}
</section>

---

## More Elements

Extra components and wrappers for third-party code.

**Repository:** [github.com/Polymer/more-elements](https://github.com/Polymer/more-elements)