State instanceid context

app/docs/md/elements/state/context.md

@@ -0,0 +1,77 @@
+---
+title: Context
+---
+
+The context object enables passing state to child elements without needing to resort to passing attributes down through multiple elements.
+
+## Set parent context
+
+The context object is passed as a key on the state object. Add data to the context object and it will be available to child elements.
+
+[Follow along by checking out the context demo from GitHub →](https://github.com/enhance-dev/context-demo)
+
+Given this markup you can use the context object to pass state directly to a deeply nested child element. Consider the page structure in the example below:
+
+<doc-code filename="app/pages/index.html">
+
+```html
+<context-parent>
+  <my-container>
+    <my-container>
+      <my-container>
+        <context-heading></context-heading>
+      </my-container>
+    </my-container>
+  </my-container>
+</context-parent>
+```
+
+</doc-code>
+
+
+Add a heading key to the context object in the parent element:
+
+<doc-code filename="app/pages/index.html">
+
+```javascript
+export default function ContextParent({ html, state }) {
+  const { context } = state
+  context.heading = 'Heading set via context'
+  return html`
+<style>
+ :host {
+   display: block;
+   height: 100dvh;
+   padding-top: 3rem;
+   text-align: center;
+   font-family: sans-serif;
+ }
+</style>
+<slot></slot>
+  `
+}
+```
+
+</doc-code>
+
+Render the heading passed via context in the deeply nested child element:
+<doc-code filenam="app/elements/context/heading.mjs">
+
+```javascript
+export default function ContextHeading({ html, state }) {
+  const { context } = state
+  const { heading='Default heading' } = context
+  return html`
+<style>
+  :host > h1 {
+    font-size: 1.5rem;
+  }
+</style>
+<h1>${heading}</h1>
+  `
+}
+```
+
+</doc-code>
+
+

app/docs/md/elements/state/index.md

@@ -38,10 +38,12 @@ export default function MyElement ({ html, state }) {
 
 </doc-code>
 
-The state object contains two top level entries:
+The state object contains four top level entries:
 
 - `attrs`, which contains all the key value pairs of attributes passed into your custom element’s instance
 - `store`, which contains the global state of your Enhance application
+- `instanceID`, which is a unique ID per instance of Custom Element
+- `context`, which is an Object that can be used to pass state to child elements to avoid prop drilling.
 
 These two different entries allow you to work with both basic and complex state in powerful ways without the need for complex abstractions or third party libraries.
 

app/docs/md/elements/state/instance-id.md

@@ -0,0 +1,23 @@
+---
+title: Instance ID
+---
+
+`instanceID` is a unique identifier that is generated per Custom Element instance. This enables you to differentiate between multiple instances of the same element on a page. It can also be useful when using a string based diffing library like [Morphdom](https://github.com/patrick-steele-idem/morphdom) which keys on unique identifiers to know when to update versus replace an element.
+
+```javascript
+export default function MyCard({ html, state }) {
+  const { attrs={}, instanceID='' } = state
+  const { content='', heading='' } = attrs
+
+  return html`
+<figure id="figure-${instanceID}">
+  <h2>${heading}</h2>
+  <p>${content}</p>
+</figure>
+  `
+}
+```
+
+<doc-callout mark="ℹ️">
+  Pro tip: As in the example above, prefix the id with the element name in order to use the id with multiple child elements.
+</doc-callout>

app/docs/nav-data.mjs

@@ -82,7 +82,15 @@ export const data = [
         path: '/docs/elements/state/',
         label: 'State',
         hasChildren: true,
-        items: ['attributes', 'store'],
+        items: [
+          'attributes',
+          'store',
+          {
+            slug: 'instance-id',
+            label: 'Instance ID',
+          },
+          'context',
+        ],
       },
     ],
   },

scripts/dictionary.txt

@@ -48,6 +48,7 @@ lowercas(e|ed)
 MDN
 MDN's
 mixi(n|ns)
+Morphdom
 natively
 Netlify
 polyfills