Moved documentation from the website repo to this one

doc/config.json

@@ -0,0 +1,60 @@
+{
+    "sections": [
+        {
+            "path": "getting-started",
+            "lib": "Getting started",
+            "pages": [
+                {
+                    "path": "getting-the-code",
+                    "lib": "Getting the code"
+                },
+                {
+                    "path": "using-elements",
+                    "lib": "Using elements"
+                },
+                {
+                    "path": "working-with-frameworks",
+                    "lib": "Working with frameworks"
+                },
+                {
+                    "path": "putting-into-production",
+                    "lib": "Putting into production"
+                },
+                {
+                    "path": "faq",
+                    "lib": "FAQ"
+                },
+                {
+                    "path": "contribute",
+                    "lib": "Contribute"
+                }
+            ]
+        },
+        {
+            "path": "reference",
+            "lib": "Reference",
+            "pages": [
+                {
+                    "path": "introduction",
+                    "lib": "Introduction"
+                },
+                {
+                    "path": "creating-elements",
+                    "lib": "Creating elements"
+                },
+                {
+                    "path": "lifecycle-callbacks",
+                    "lib": "Lifecycle callbacks"
+                },
+                {
+                    "path": "shadow-dom",
+                    "lib": "Shadow DOM"
+                },
+                {
+                    "path": "shadow-css",
+                    "lib": "Shadow CSS"
+                }
+            ]
+        }
+    ]
+}

doc/getting-started/contribute.md

@@ -0,0 +1,16 @@
+# Contribute
+
+## Source code
+Fork it on [Github](https://github.com/bosonic).
+
+In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality/element. Lint and test your code using Grunt.
+
+## Discussion
+For now, we've got only two ways to stay in touch: [Github](https://github.com/bosonic) and our [Twitter account](https://twitter.com/bosonic_project).
+
+We'll soon open a Google group and an IRC channel.
+
+## What do you need ?
+
+- More elements: the more the better...
+- Better documentation: if you're fluent, you can help!

doc/getting-started/faq.md

@@ -0,0 +1,36 @@
+# FAQ
+
+## Why Bosonic?
+
+When the initial Web Components spec draft was released, I ([@goldoraf](https://twitter.com/goldoraf/)) was immediately sold. At that time, my team and I were developing Single-Page Apps (commonly referred to as SPA's) for two years. We used many different JavaScript frameworks in our quest for the perfect stack. The end result of this was that we had ended up rewriting the same basic UI code over and over again. We found that each framework required the same core code but had it's own unique requirements that wouldn't allow us to share a common code base. We became convinced that there should be a better and more effective way to do this. That was when we found what we needed in Web Components.
+
+[Polymer](https://www.polymer-project.org/) and [x-tag](http://www.x-tags.org/) were soon released, and we began to experiment with them. The team & I rejected Polymer almost immediately, noting that it was too 'feature-rich' for what we needed (two-way data binding required too many performance trade offs, etc) and the elements were not as useful for our particular use cases. We are extremely thankful to the Polymer authors for their awesome work. Without their dedication and innovation in the Web Components community, we wouldn't have all of the fantastic polyfills and related projects to work with! My team began to implement some elements using x-tag and soon discovered that building an element's DOM manually was cumbersome (x-tag doesn't use the `<template>` element nor Shadow DOM). After our discoveries, we then decided to build our own tool that would better serve our needs and philosophies. This tool would aim to be lighter in file size than Polymer and contain more rich features than x-tag. After many doubts and rewrites, Bosonic was born.
+
+## Why the "reboot"?
+
+There have been a long hiatus between Bosonic's initial release and this "refresh". There are many reasons for that.
+
+First, I've been surprised by the lack of feedback from the community. It took me a long time and many conversations during conferences, meetups and other events to begin to understand why. Basically, a lot of people were confused and didn't "get" Web Components the same way I did: they believed that Web Components were proposed as a standard way for building complete apps with only Web Components and vanilla JS. I personally believe Web Components are ideal for low-level, "standard", reusable UI elements like dialogs, tabs or dropdowns, and that they should be combined with a more powerful library or framework like React, Angular or Ember in order to develop a complete application.
+
+Some people found that working with Bosonic was too complicated: the necessity of a build step was an obstacle for some to even try Bosonic. My will of Internet Explorer 9 (IE9) browser support and awesome performance is the main culprit here: I saw that build step as a necessary evil in order to achieve these goals.
+
+It's hard to stay motivated when you put many long hours into a project you believe in and then don't receive much feedback at all. It's even harder when health issues (not life-threatening, but very painful) and professional difficulties get in the mix.
+
+A few months ago, with these personal issues resolved, I began to think about what to do with Bosonic. Polymer 1.0 and its Material Design integration (in the form of their 'paper-elements' Polymer Elements) had been released. I found that the paper-elements were mostly useless for my team (again, Polymer people, you did an awesome job, but it's just not for everyone). x-tag hadn't moved at all, so I thought there was still an opportunity for Bosonic because I still thought that Web Components were important.
+
+I then realized two things: 
+- I needed to simplify Bosonic a lot: no more mandatory build step, even if it meant to drop IE9 support for a time ;
+- I needed to reformulate my value proposition: in short, I wanted Bosonic to be like Bootstrap ported to Web Components, i.e. a library of everyday UI elements, and much less a library for building Web Components.
+
+Hence the reboot :-)
+
+## What do you plan next?
+
+Lot of things.
+
+- Get IE9 (and other older browsers) support back: it'll involve a build step, but it'll be optional and shouldn't block people to try Bosonic ;
+- Release a build tool for element concatenation & CSS Variables post-processing ;
+- Refactor some elements' code into mixins applicable to all elements, not just custom elements: I found out working on Bosonic that what should be simple tasks can get really complicated when using DOM. In some ways, I miss jQuery sometimes :p ;
+- Work on elements a11y: I tried to implement a11y as best as I could, but I need testers and feedback to be sure it works fine ;
+- And of course...more elements!
+

doc/getting-started/getting-the-code.md

@@ -0,0 +1,43 @@
+# Getting the code
+
+The preferred way to install Bosonic is through [NPM](https://www.npmjs.com/package/bosonic), but you can download the Bosonic platform as a [ZIP file](https://github.com/bosonic/bosonic/releases/latest). It contains two files: `webcomponents.js`, which is the file that contains the community polyfills and `bosonic-runtime.js`, which is the Bosonic library (not the elements!).
+
+## With npm
+
+We'll assume you've already installed Node.js and NPM ([platform specific installation instructions](https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager)).
+
+If you've just setup your project and haven't created a `package.json` file, it's now time to generate one:
+
+``` bash
+npm init
+```
+
+You can now install the Bosonic package:
+
+``` bash
+npm install --save bosonic
+```
+
+Don't forget to install the `webcomponents.js` polyfills ; they're bundled with the Bosonic package as a dependency, but as you may know, npm installs dependencies in a nested hierarchy, which is not always practical.
+
+``` bash
+npm install --save webcomponents.js
+```
+
+## Installing elements
+
+Bosonic's elements are grouped in several NPM packages, but as [dnd-elements](https://github.com/bosonic/dnd-elements) and [data-elements](https://github.com/bosonic/data-elements) are still a Work-In-Progress, they aren't published yet.
+
+``` bash
+npm install --save bosonic-core-elements
+```
+
+[Bosonic Core Elements](https://github.com/bosonic/core-elements) are available as a [ZIP file](https://github.com/bosonic/core-elements/releases/latest) too.
+
+## Project setup
+
+Some elements depends on other elements ; all elements should therefore reside in the same folder when developing. If you downloaded ZIP files, extract all the files into the same folder. If you used NPM, you'll need to copy files from the installed packages into a "developement" folder. Depending on your task runner of choice, you can use [grunt-contrib-copy]() or [gulp-copy]() to do this.
+
+### Use a web server
+
+Because of the way HTML imports work, you'll need a local web server to use Bosonic elements (usage of the `file:` protocol is blocked by Cross-Origin Resource Sharing policy).

doc/getting-started/putting-into-production.md

@@ -0,0 +1,11 @@
+# Putting into production
+
+If you use several of elements in your app, you'll get a lot of network requests (one for each HTML import), and that's not necessarily good for performance (until we all start using [Http2](https://en.wikipedia.org/wiki/HTTP/2)). It's therefore often necessary in today's web applications to concatenate Web Components into a single file.
+
+## Concatenating Web Components
+
+The Polymer authors have developed a handy tool for that purpose that's called [Vulcanize](https://github.com/Polymer/vulcanize). It's a command line tool that easily integrates with your build tool of choice, that recursively pulls in all your imports, flattens their dependencies and spits out a single file.
+
+## In the future
+
+We have a specific build tool in the works that will leverage Vulcanize and include CSS Variables post-processing. It will be released in a few weeks, stay tuned!

doc/getting-started/using-elements.md

@@ -0,0 +1,135 @@
+# Using elements
+
+Now that you've decided to use Bosonic and some of its elements, it's time to put them to good use. For the sake of simplicity, we'll assume you put the downloaded files into a `lib` folder next to a blank HTML page. To use Bosonic elements, you first need to include the [`webcomponents.js`](http://webcomponents.org/polyfills/) polyfill library, and then the Bosonic runtime. Once this step is complete, you can import the element or elements you want to play with using an [HTML import](http://webcomponents.org/articles/introduction-to-html-imports/).
+
+``` html
+<!DOCTYPE html>
+<html>
+    <head>
+        <title>My Application</title>
+        <meta charset="utf-8">
+        <!-- Load the library which contains the various Web Components polyfills -->
+        <script src="lib/webcomponents.js"></script>
+        <!-- Load the Bosonic runtime -->
+        <script src="lib/bosonic-runtime.js"></script>
+        <!-- Import the element you want to play with -->
+        <link rel="import" href="lib/b-dialog.html">
+    </head>
+    <body>
+
+        <!-- Declare the element -->
+        <b-dialog>
+            <b-dialog-content>
+                <h3>Test</h3>
+                <p>Hello world!</p>
+                <button data-dialog-dismiss>Close</button>
+            </b-dialog-content>
+        </b-dialog>
+
+        <button id="show-modal">Show modal</button>
+
+        <!-- Here we add a listener on the button to open the modal when clicked -->
+        <script type="text/javascript">
+            // Custom elements need time to "upgrade", wait for WebComponentsReady before manipulating them
+            window.addEventListener("WebComponentsReady", function() {
+                var showModalButton = document.getElementById('show-modal');
+                showModalButton.addEventListener('click', function() {
+                    document.querySelector('b-dialog').showModal();
+                }, false);
+            });
+        </script>
+
+    </body>
+</html>
+```
+
+We just added a [dialog](/elements/dialogs-modals.html) into our page! As you can see in the sample above, you can manipulate your dialog element just like a native HTML one, using standard DOM features:
+
+## Attributes
+Element behavior can be modified by using specific [HTML attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes). For example, if we add a `opened` attribute to a [`b-collapsible`](/elements/collapsible.html) element, it will be opened by default:
+
+``` html
+<b-collapsible opened>
+    <div>
+        Lorem ipsum...
+    </div>
+</b-collapsible>
+```
+This attribute can be added using the DOM standard API, too:
+``` js
+var collapsible = document.querySelector('b-collapsible');
+collapsible.setAttribute('opened', '');
+```
+
+## Elements API
+Like native HTML elements, Bosonic elements expose an API: properties and methods that trigger various behaviors. In the `b-dialog` sample above, we used the `showModal()` method to open the dialog with an overlay. Similarly, we could have used the `opened` property of the `b-collapsible` element to open it:
+``` js
+var collapsible = document.querySelector('b-collapsible');
+collapsible.opened = true;
+```
+Please refer to the [elements' documentation](/elements/dialogs-modals.html) for more information about their specific APIs.
+
+## Custom events
+Bosonic elements emit various [custom events](https://developer.mozilla.org/en-US/docs/Web/API/Event) during their lifecycle. For instance, `b-collapsible` emits a `b-collapsible-show` event when it is about to be shown, event that you can listen too and even cancel:
+``` js
+var collapsible = document.querySelector('b-collapsible');
+collapsible.addEventListener('b-collapsible-show', function(event) {
+    event.preventDefault();
+});
+```
+Again, please refer to the elements documentation for more information about the events they publish.
+
+## WebComponentsReady event
+The [Custom Elements](http://webcomponents.org/polyfills/custom-elements/) polyfill handles element upgrades asynchronously. When the browser parses your page's markup, it doesn't recognize custom elements at first, they're therefore interpreted as `HTMLUnknownElement`. When `DOMContentsLoaded` is fired, the polyfill will take a look at each of the unknown elements in the page, see if they have been registered as custom elements, and then upgrade them to custom elements with APIs. Consequently, custom elements API are not available until after they have been upgraded. That's why you need to listen to the `WebComponentsReady` event (that will be fired by the polyfill) before trying to use their APIs.
+``` js
+window.addEventListener("WebComponentsReady", function() {
+    var showModalButton = document.getElementById('show-modal');
+    showModalButton.addEventListener('click', function() {
+        document.querySelector('b-dialog').showModal();
+    }, false);
+});
+```
+
+## Styling elements
+There are basically two types of elements: those that use [Shadow DOM](http://webcomponents.org/polyfills/shadow-dom/) and those that don't. The elements that don't use Shadow DOM are easy to style. They work just like standard HTML and use classic global CSS selectors:
+
+``` html
+<style>
+b-dropdown.modern {
+    border: 1px solid #ccc;
+}
+b-dropdown.modern > button {
+    background-color: #ccc;
+}
+</style>
+
+<b-dropdown class="modern">
+    <button>Dropdown</button>
+    <ul>
+        <li>plain text</li>
+        <li><a href="#">link item</a></li>
+        <hr />
+        <li><a href="#">separated link</a></li>
+    </ul>
+</b-dropdown>
+```
+
+Elements that use Shadow DOM extensively (for instance, [`b-tooltip`](/elements/tooltips.html)) can be a bit more complicated to style. The reason for that is that Shadow DOM scopes and encapsulates CSS, making it theoretically immune from style leakage. Of course,  Web Component creators want to theme their custom elements, and therefore they need to alter the CSS within the element. The Shadow DOM spec authors have provided pseudo-selectors (`/deep/` and `::shadow`) in order to achieve this, but they're not easy to use. They additionally introduce another round of problems.
+
+The Polymer authors found themselves in the quest of a better way. They decided to use [CSS Variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_variables) to achieve easy theming strategy for elements utilizing Shadow DOM. In using CSS Variables, elements declare their variables by setting some CSS properties like color or padding. Variables that can be set in an external stylesheet as seen in this example:
+
+``` html
+<style>
+:root {
+    --b-tooltip-background: red;
+}
+</style>
+
+<b-tooltip for="btn">Tooltip text</b-tooltip>
+<button id="btn">My button</button>
+```
+This is a great idea, and we've started to add some CSS variables in our elements too. Please keep in mind that CSS Variables are still an experimental feature and as of now Firefox is the only browser with a implementation of them. Polymer includes a shim in order to support CSS variables in all browsers, but it comes with a non-negligible performance cost. This is why the Bosonic team is actively developing a small build tool based on an existing CSS post-processor. This will make these CSS Variables able to work in every browser. This tool will be released in a few weeks, stay tuned!
+
+## Interoperability
+
+Bosonic is built on top of the [web components polyfill library](http://webcomponents.org/polyfills/) just like Polymer and x-tag are. This means that you can happily mix Bosonic, Polymer, and x-tag elements on the same page!