define-element 1.0.0 → 1.1.0

package/README.md

@@ -2,10 +2,9 @@
 
 A custom element to define custom elements.
 
-* Components as content, not code — paste into any page, CMS, or markdown
-* No class, no build, no framework — one `<script>` tag
-* Typed props, scoped styles, shadow DOM, slots, lifecycle
-* Pluggable template engine — native components for [sprae](https://github.com/dy/sprae), [Alpine](https://alpinejs.dev), [petite-vue](https://github.com/vuejs/petite-vue), [template-parts](https://github.com/nicegist/template-parts) and others
+* [Declarative Custom Elements](https://github.com/WICG/webcomponents/blob/gh-pages/proposals/Declarative-Custom-Elements-Strawman.md) reference implemetation
+* Typed props, scoped styles, shadow DOM, slots, lifecycle — one `<script>` tag
+* Native web components for [sprae](https://github.com/dy/sprae), [alpine](https://alpinejs.dev), [petite-vue](https://github.com/vuejs/petite-vue), [template-parts](https://github.com/nicegist/template-parts) and others
 
 
 ```html
@@ -150,15 +149,26 @@ Add `shadowrootmode` to the template for encapsulation. Slots work natively:
 
 ## Processor
 
-Pluggable template engine. Without a processor, templates are static HTML. Set `.processor` to a `(root, state) => state` function — called once per instance after template content is cloned into `root`.
+Pluggable template engine. Without a processor, templates are static HTML (cloned automatically). With a processor, the processor owns template mounting — it receives an empty `root` with `root.template` pointing to the original `<template>` element, and is responsible for cloning/rendering content.
 
-`root` is the render target — the element itself (light DOM) or its `shadowRoot` (shadow DOM), with template content already cloned in. The original `<template>` element is available as `root.template` for processors that need it.
+```js
+processor(root, state) => state
+```
+
+- `root` — element (light DOM) or shadowRoot (shadow DOM), empty
+- `root.template` — original `<template>` element (shared across instances)
+- `state` — `{ propName: value }` from prop defaults + instance attributes
+- Returns reactive state object (stored as `el.state`)
 
 ```js
-import sprae from 'sprae'
+let DE = customElements.get('define-element')
 
-// sprae matches the signature directly — returns a reactive store
-customElements.get('define-element').processor = sprae
+// sprae — clone template, then sprae processes content reactively
+import sprae from 'sprae'
+DE.processor = (root, state) => {
+  root.appendChild(root.template.content.cloneNode(true))
+  return sprae(root, state)
+}
 ```
 
 ```html
@@ -176,22 +186,26 @@ customElements.get('define-element').processor = sprae
 No `<script>` needed — [sprae](https://github.com/dy/sprae) updates the template automatically when state changes. Other processors:
 
 ```js
-let DE = customElements.get('define-element')
-
-// @github/template-parts ({{x}} interpolation, W3C Template Instantiation proposal)
+// @github/template-parts — renders directly from template, no pre-clone needed
 import { TemplateInstance } from '@github/template-parts'
 DE.processor = (root, state) => {
   root.replaceChildren(new TemplateInstance(root.template, state))
   return state
 }
 
-// petite-vue (v-text, v-bind, {{ }})
+// petite-vue
 import { createApp, reactive } from 'petite-vue'
-DE.processor = (root, state) => (createApp(state).mount(root), reactive(state))
+DE.processor = (root, state) => {
+  root.appendChild(root.template.content.cloneNode(true))
+  let r = reactive(state)
+  createApp(r).mount(root)
+  return r
+}
 
-// Alpine.js (x-text, x-bind, @click)
+// Alpine.js
 import Alpine from 'alpinejs'
 DE.processor = (root, state) => {
+  root.appendChild(root.template.content.cloneNode(true))
   let r = Alpine.reactive(state)
   Alpine.addScopeToNode(root, r)
   Alpine.initTree(root)
@@ -217,7 +231,7 @@ The [W3C Declarative Custom Elements proposal](https://github.com/WICG/webcompon
 
 The gap: no lightweight way to define a custom element as HTML — components as content, not as code. Paste a `<define-element>` block into any page, CMS, or markdown file and it works. No npm, no import maps, no build step. One `<script>` tag.
 
-This ~265-line polyfill is evidence that the W3C proposal is implementable and useful. Ship it natively.
+This ~270-line reference implementation is evidence that the W3C proposal is implementable and useful. Ship it natively.
 
 
 ## Alternatives

package/define-element.js

@@ -105,10 +105,6 @@ function define(el) {
           root = this.shadowRoot || this.attachShadow({ mode: shadowMode })
         }
 
-        if (tpl && !root.firstChild) {
-          root.appendChild(tpl.content.cloneNode(true))
-        }
-
         // inject style
         if (styleText) {
           if (shadowMode) {
@@ -131,13 +127,7 @@ function define(el) {
           }
         }
 
-        // collect parts
-        this.part = {}
-        root.querySelectorAll('[part]').forEach(p =>
-          this.part[p.getAttribute('part')] = p
-        )
-
-        // expose original template on root for processors that need it
+        // expose original template for processors
         if (tpl) root.template = tpl
 
         // build initial state from prop defaults + current attributes
@@ -148,15 +138,25 @@ function define(el) {
           state[p.name] = attrVal != null ? coerce(attrVal) : this._de_props[p.name]
         }
 
-        // run processor (per-definition > global)
+        // run processor or clone template
         let p = DefineElement.processor
         if (p) {
+          // processor owns template mounting — no pre-clone
           let result = p(root, state)
           this.state = result || state
         } else {
+          if (tpl && !root.firstChild) {
+            root.appendChild(tpl.content.cloneNode(true))
+          }
           this.state = state
         }
 
+        // collect parts (after processor, since it populates root)
+        this.part = {}
+        root.querySelectorAll('[part]').forEach(p =>
+          this.part[p.getAttribute('part')] = p
+        )
+
         // run script (errors in injected scripts don't throw — browser reports via onerror)
         if (scriptText) runScript(scriptText, this)
       }
@@ -173,6 +173,7 @@ function define(el) {
     }
 
     attributeChangedCallback(name, oldVal, newVal) {
+      if (this._de_reflecting) return
       let def = propMap[name]
       if (!def) return
 
@@ -197,9 +198,13 @@ function define(el) {
         let val = coerce(v)
         this._de_props[p.name] = val
         if (this._de_init && this.state) this.state[p.name] = val
+        // skip reflection for functions — can't round-trip through attributes
+        if (typeof val === 'function') return
         let s = serialize(val, p.type)
+        this._de_reflecting = true
         if (s == null) this.removeAttribute(p.name)
         else this.setAttribute(p.name, s)
+        this._de_reflecting = false
       },
       enumerable: true,
       configurable: true
@@ -262,3 +267,5 @@ class DefineElement extends HTMLElement {
 DefineElement.processor = null
 
 customElements.define('define-element', DefineElement)
+
+export { DefineElement, define }

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "define-element",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "A custom element to define custom elements",
   "type": "module",
   "main": "define-element.js",
   "unpkg": "define-element.js",
-  "files": ["define-element.js"],
+  "files": [
+    "define-element.js"
+  ],
   "sideEffects": true,
   "scripts": {
     "test": "node -r ./test/register.cjs test/test.js"