From 99eca5c1609dd8e947bbd87ef352eafbf94ebcb6 Mon Sep 17 00:00:00 2001
From: Matthew Phillips <matthew@matthewphillips.info>
Date: Fri, 16 Aug 2019 09:29:55 -0400
Subject: [PATCH] Add documentation for .bindings()

Closes #68
---
 .editorconfig    |  2 +-
 docs/bindings.md | 78 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 79 insertions(+), 1 deletion(-)
 create mode 100644 docs/bindings.md

diff --git a/.editorconfig b/.editorconfig
index 7d0ebad..32a5f7e 100644
--- a/.editorconfig
+++ b/.editorconfig
@@ -6,6 +6,6 @@ indent_size = 4
 trim_trailing_whitespace = false
 insert_final_newline = true
 
-[{*.json,*.yml}]
+[{*.json,*.yml,*.md}]
 indent_style = space
 indent_size = 2
diff --git a/docs/bindings.md b/docs/bindings.md
new file mode 100644
index 0000000..b985188
--- /dev/null
+++ b/docs/bindings.md
@@ -0,0 +1,78 @@
+@function can-stache-element/lifecycle-methods.bindings bindings
+@parent can-stache-element/lifecycle-methods 6
+
+Programmatically instantiate a component
+
+@signature `element.bindings([props])`
+
+Create bindings between an element's properties and parent observables. This is useful when you:
+
+- have complex logic for switching between different components (e.g. routing)
+
+The following defines `HomePage` and `MyApp` components that sets up bindings between them:
+
+```js
+class HomePage extends StacheElement {
+  static props = {
+    pageId: Number
+  }
+}
+
+class MyApp extends StacheElement {
+  static view = `{{{component}}}`
+
+  static props = {
+    componentName: String,
+    pageId: Number,
+
+    component: {
+      get() {
+        if(componentName === "home") {
+          return new HomePage().bindings({
+            pageId: value.from(this, "pageId")
+          });
+        }
+      }
+    }
+  }
+}
+```
+
+@param {Object} [props] Child properties to bind to.
+@return {can-stache-element} The StacheElement instance.
+
+@body
+
+## Use
+
+Pass an object of properties to bind to the element. For example:
+
+```js
+import {StacheElement, ObservableObject, value} from "can";
+
+const appVM = new ObservableObject({
+  association: "friend"
+});
+
+class MyGreeting extends StacheElement {
+  static view = `{{greeting}} {{subject}}`
+
+  static props = {
+    greeting: String,
+    subject: String
+  }
+}
+customElements.define("my-greeting", MyGreeting);
+
+const myGreetingInstance = new MyGreeting().bindings({
+  greeting: "Hello",
+  subject: value.bind(appVM, "association")
+}).render();
+
+console.log( myGreetingInstance );
+// logs <my-greeting>Hello friend</my-greeting>
+
+console.log( myGreetingInstance.subject );
+// logs "friend"
+```
+@codepen