define-element 0.0.0 → 1.1.0

package/README.md

@@ -0,0 +1,248 @@
+# define-element [![npm](https://img.shields.io/npm/v/define-element?color=tomato)](https://npmjs.org/define-element) [![size](https://img.shields.io/bundlephobia/minzip/define-element?label=size&color=brightgreen)](https://bundlephobia.com/package/define-element) [![ci](https://github.com/dy/define-element/actions/workflows/test.yml/badge.svg)](https://github.com/dy/define-element/actions/workflows/test.yml)
+
+A custom element to define custom elements.
+
+* [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
+<define-element>
+  <x-greeting name:string="world">
+    <template>
+      <p part="msg"></p>
+    </template>
+    <script>
+      const update = () => this.part.msg.textContent = `Hello, ${this.name}!`
+      update()
+      this.onattributechanged = update
+    </script>
+    <style>:host { font-style: italic }</style>
+  </x-greeting>
+</define-element>
+
+<x-greeting></x-greeting>
+<x-greeting name="Arjuna"></x-greeting>
+```
+
+```html
+<script src="https://unpkg.com/define-element"></script>
+```
+
+or `$ npm i define-element` → `import 'define-element'`
+
+
+## Definition
+
+Elements are defined by-example inside `<define-element>`. Each child becomes a custom element. A definition can contain `<template>`, `<script>`, and `<style>`.
+
+```html
+<define-element>
+  <my-element greeting:string="hello">
+    <template>...</template>
+    <style>...</style>
+    <script>...</script>
+  </my-element>
+</define-element>
+```
+
+Multiple definitions per block. After processing, `<define-element>` removes itself. Without `<template>`, instance content is preserved as-is.
+
+
+## Props
+
+Declared as attributes with optional types:
+
+```html
+<x-widget count:number="0" label:string="Click me" active:boolean>
+```
+
+| Type | Coercion | Default |
+|------|----------|---------|
+| `:string` | `String(v)` | `""` |
+| `:number` | `Number(v)` | `0` |
+| `:boolean` | `true` unless `"false"` or `null` | `false` |
+| `:date` | `new Date(v)` | `null` |
+| `:array` | `JSON.parse(v)` | `[]` |
+| `:object` | `JSON.parse(v)` | `{}` |
+| (none) | auto-detect | as-is |
+
+Properties reflect to attributes and vice versa. Instance attributes override definition defaults.
+
+
+## Template, Parts & Script
+
+`<template>` is cloned into each instance on first connect. Elements with `part` are collected into `this.part`. `<script>` runs once per instance with `this` as the element, via script injection (no `eval`).
+
+```html
+<define-element>
+  <x-clock>
+    <template>
+      <time part="display"></time>
+    </template>
+    <script>
+      let id
+      const tick = () => this.part.display.textContent = new Date().toLocaleTimeString()
+      tick()
+      this.onconnected = () => id = setInterval(tick, 1000)
+      this.ondisconnected = () => clearInterval(id)
+    </script>
+    <style>:host { font-family: monospace; }</style>
+  </x-clock>
+</define-element>
+```
+
+| Access | Description |
+|--------|-------------|
+| `this` | The element instance |
+| `this.count` | Prop value |
+| `this.state` | Template state (from processor or plain object) |
+| `this.part.x` | DOM ref via `part="x"` |
+| `this.onconnected` | Connected callback |
+| `this.ondisconnected` | Disconnected callback |
+| `this.onadopted` | Adopted callback |
+| `this.onattributechanged` | Attribute changed callback |
+
+Script runs once on first connect. `onconnected` fires after script, including on first connect. On re-insertion, only `onconnected` fires. Async `await` is auto-detected.
+
+
+## Style
+
+`<style>` is scoped automatically. With shadow DOM, styles use [adoptedStyleSheets](https://developer.mozilla.org/en-US/docs/Web/API/ShadowRoot/adoptedStyleSheets) (shared across instances). Without shadow DOM, styles are scoped via [CSS nesting](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_nesting) under the element tag, and `:host` is rewritten to the tag name.
+
+
+## Shadow DOM & Slots
+
+Add `shadowrootmode` to the template for encapsulation. Slots work natively:
+
+```html
+<define-element>
+  <x-dialog open:boolean>
+    <template shadowrootmode="open">
+      <dialog part="dialog">
+        <header><slot name="title">Notice</slot></header>
+        <slot></slot>
+        <footer><button part="close">Close</button></footer>
+      </dialog>
+    </template>
+    <script>
+      const sync = () => this.open ? this.part.dialog.showModal() : this.part.dialog.close()
+      this.part.close.onclick = () => this.open = false
+      this.onattributechanged = sync
+      sync()
+    </script>
+    <style>
+      dialog::backdrop { background: rgba(0,0,0,.5); }
+      header { font-weight: bold; margin-bottom: .5em; }
+      footer { margin-top: 1em; text-align: right; }
+    </style>
+  </x-dialog>
+</define-element>
+
+<x-dialog open>
+  <span slot="title">Confirm</span>
+  <p>Are you sure?</p>
+</x-dialog>
+```
+
+
+## Processor
+
+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.
+
+```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
+let DE = customElements.get('define-element')
+
+// 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
+<define-element>
+  <x-counter count:number="0">
+    <template>
+      <button :onclick="count++">
+        Count: <span :text="count"></span>
+      </button>
+    </template>
+  </x-counter>
+</define-element>
+```
+
+No `<script>` needed — [sprae](https://github.com/dy/sprae) updates the template automatically when state changes. Other processors:
+
+```js
+// @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
+import { createApp, reactive } from 'petite-vue'
+DE.processor = (root, state) => {
+  root.appendChild(root.template.content.cloneNode(true))
+  let r = reactive(state)
+  createApp(r).mount(root)
+  return r
+}
+
+// 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)
+  return r
+}
+```
+
+Frameworks with their own component models (Lit, Vue, Stencil) are better used directly.
+
+
+## Progressive Enhancement
+
+Definitions are plain HTML — they render as inert content before JS loads. No flash of unstyled content, no blank page. The component markup is the fallback.
+
+For shadow DOM components, server-rendered HTML can include [Declarative Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM#declaratively_with_html) (`<template shadowrootmode>`) for instant first paint. `define-element` then hydrates behavior on top.
+
+This is not server-side rendering in the framework sense — there is no server runtime. It is HTML that works without JavaScript and gets enhanced when JavaScript arrives.
+
+
+## Why
+
+The [W3C Declarative Custom Elements proposal](https://github.com/WICG/webcomponents/blob/gh-pages/proposals/Declarative-Custom-Elements-Strawman.md) has stalled for years. JS-side solutions (Lit, FAST, Stencil) require build tools and class boilerplate. The declarative CE space is a [graveyard](./docs/alternatives.md).
+
+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 ~270-line reference implementation is evidence that the W3C proposal is implementable and useful. Ship it natively.
+
+
+## Alternatives
+
+<sup>[EPA-WG custom-element](https://github.com/EPA-WG/custom-element) · [tram-deco](https://github.com/Tram-One/tram-deco) · [tram-lite](https://github.com/Tram-One/tram-lite) · [uce-template](https://github.com/WebReflection/uce-template) · [Ponys](https://github.com/jhuddle/ponys) · [snuggsi](https://github.com/devpunks/snuggsi) · [element-modules](https://github.com/trusktr/element-modules) · [Lit](https://lit.dev) · [Stencil](https://stenciljs.com) · [FAST](https://www.fast.design) · [Catalyst](https://github.github.io/catalyst/) · [Atomico](https://atomicojs.dev) · [Minze](https://minze.dev) · [haunted](https://github.com/matthewp/haunted) · [W3C DCE Proposal](https://github.com/WICG/webcomponents/blob/gh-pages/proposals/Declarative-Custom-Elements-Strawman.md)</sup>
+
+[Detailed comparison →](./docs/alternatives.md)
+
+
+### License
+
+[Krishnized](https://github.com/krishnized/license) ISC
+
+<p align="center"><a href="https://github.com/krishnized/license">ॐ</a></p>

package/define-element.js

@@ -0,0 +1,271 @@
+/**
+ * <define-element> — a custom element to define custom elements.
+ * Processor signature: (root, state) => state
+ *
+ * @example
+ * <define-element>
+ *   <x-counter count:number="0">
+ *     <template><output part="out">0</output><button part="inc">+</button></template>
+ *     <script>this.part.inc.onclick = () => this.count++</script>
+ *   </x-counter>
+ * </define-element>
+ */
+
+// Type coercions for prop values
+const types = {
+  string: v => v == null ? '' : String(v),
+  number: v => v == null ? 0 : Number(v),
+  boolean: v => v != null && v !== 'false' && v !== false,
+  date: v => v == null ? null : new Date(v),
+  array: v => v == null ? [] : typeof v === 'string' ? JSON.parse(v) : Array.from(v),
+  object: v => v == null ? {} : typeof v === 'string' ? JSON.parse(v) : v,
+}
+
+// Serialize value to attribute string
+const serialize = (v, type) =>
+  v == null ? null :
+  type === 'boolean' ? (v ? '' : null) :
+  type === 'array' || type === 'object' ? JSON.stringify(v) :
+  type === 'date' ? v.toISOString?.() ?? String(v) :
+  String(v)
+
+// Auto-detect type from string value
+const auto = v => v == null ? v : !isNaN(v) && v !== '' ? Number(v) : v === 'true' ? true : v === 'false' ? false : v
+
+// Track which light-DOM styles have been injected
+let injectedStyles = new Set()
+
+/**
+ * Parse prop declarations from element attributes.
+ * Format: name:type="default" or name="default" (auto-detect type)
+ */
+function parseProps(el) {
+  let props = []
+  for (let { name, value } of [...el.attributes]) {
+    if (name === 'is') continue
+    let [prop, type] = name.split(':')
+    props.push({ name: prop, type: type || null, default: value })
+  }
+  return props
+}
+
+/**
+ * Define a custom element from a definition element.
+ * @param {Element} el - The definition child (e.g., <x-counter count:number="0">)
+ */
+function define(el) {
+  let tag = el.localName
+  let ext = el.getAttribute('is')
+
+  let propDefs = parseProps(el)
+  let propNames = propDefs.map(p => p.name)
+  let propMap = Object.fromEntries(propDefs.map(p => [p.name, p]))
+
+  // extract sections
+  let tpl = el.querySelector('template')
+  let shadowMode = tpl?.getAttribute('shadowrootmode') || null
+  if (shadowMode) tpl.removeAttribute('shadowrootmode')
+
+  let scriptEl = el.querySelector('script')
+  let scriptText = scriptEl?.textContent || null
+
+  let styleEl = el.querySelector('style')
+  let styleText = styleEl?.textContent || null
+
+  // shared adopted stylesheet for shadow DOM (one per definition)
+  let adoptedSheet = null
+  if (styleText && shadowMode && typeof CSSStyleSheet !== 'undefined') {
+    adoptedSheet = new CSSStyleSheet()
+    adoptedSheet.replaceSync(styleText)
+  }
+
+  // determine base class
+  let Base = ext ? document.createElement(tag).constructor : HTMLElement
+
+  let C = class extends Base {
+    static observedAttributes = propNames
+
+    constructor() {
+      super()
+      this._de_init = false
+      this._de_props = {}
+
+      for (let p of propDefs) {
+        let coerce = p.type ? types[p.type] : auto
+        this._de_props[p.name] = coerce(p.default || null)
+      }
+    }
+
+    connectedCallback() {
+      if (!this._de_init) {
+        this._de_init = true
+
+        let root = this
+        if (shadowMode) {
+          root = this.shadowRoot || this.attachShadow({ mode: shadowMode })
+        }
+
+        // inject style
+        if (styleText) {
+          if (shadowMode) {
+            if (adoptedSheet) {
+              root.adoptedStyleSheets = [adoptedSheet]
+            } else {
+              let s = document.createElement('style')
+              s.textContent = styleText
+              root.prepend(s)
+            }
+          } else {
+            // light DOM: @scope
+            let s = document.createElement('style')
+            s.textContent = scopeCSS(styleText, tag)
+            s.setAttribute('data-de', tag)
+            if (!injectedStyles.has(tag)) {
+              injectedStyles.add(tag)
+              document.head.appendChild(s)
+            }
+          }
+        }
+
+        // expose original template for processors
+        if (tpl) root.template = tpl
+
+        // build initial state from prop defaults + current attributes
+        let state = {}
+        for (let p of propDefs) {
+          let coerce = p.type ? types[p.type] : auto
+          let attrVal = this.getAttribute(p.name)
+          state[p.name] = attrVal != null ? coerce(attrVal) : this._de_props[p.name]
+        }
+
+        // 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)
+      }
+
+      this.onconnected?.()
+    }
+
+    disconnectedCallback() {
+      this.ondisconnected?.()
+    }
+
+    adoptedCallback() {
+      this.onadopted?.()
+    }
+
+    attributeChangedCallback(name, oldVal, newVal) {
+      if (this._de_reflecting) return
+      let def = propMap[name]
+      if (!def) return
+
+      let coerce = def.type ? types[def.type] : auto
+      let val = coerce(newVal)
+      this._de_props[name] = val
+
+      if (this._de_init && this.state) {
+        this.state[name] = val
+      }
+
+      this.onattributechanged?.({ attributeName: name, oldValue: oldVal, newValue: newVal })
+    }
+  }
+
+  // define props as getter/setter on prototype
+  for (let p of propDefs) {
+    let coerce = p.type ? types[p.type] : auto
+    Object.defineProperty(C.prototype, p.name, {
+      get() { return this._de_props[p.name] },
+      set(v) {
+        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
+    })
+  }
+
+  // register (skip if already defined)
+  let name = ext || tag
+  if (!customElements.get(name))
+    customElements.define(name, C, ext ? { extends: tag } : undefined)
+
+  return C
+}
+
+
+/**
+ * Execute script text via <script> element injection (no eval/new Function).
+ * Wraps in IIFE with `this` bound to element instance.
+ */
+function runScript(text, thisArg) {
+  let s = document.createElement('script')
+  let stripped = text.replace(/\/\/.*|\/\*[\s\S]*?\*\/|(['"`])(?:(?!\1)[^\\]|\\.)*\1/g, '')
+  let isAsync = /\bawait\b/.test(stripped)
+  let wrapper = isAsync
+    ? `(async function(){${text}}).call(document.currentScript._de_this)`
+    : `(function(){${text}}).call(document.currentScript._de_this)`
+  s._de_this = thisArg
+  s.textContent = wrapper
+  document.head.appendChild(s)
+  s.remove()
+}
+
+
+/** CSS scoping for light DOM via CSS nesting. :host → tag. */
+function scopeCSS(css, tag) {
+  css = css.replace(/:host\b(?:\(([^)]*)\))?/g, (_, sel) => sel ? `${tag}${sel}` : tag)
+  return `${tag} { ${css} }`
+}
+
+
+/**
+ * <define-element> — scans children for component definitions.
+ */
+class DefineElement extends HTMLElement {
+  connectedCallback() {
+    queueMicrotask(() => this._init())
+  }
+
+  _init() {
+    let defs = [...this.children].filter(c => {
+      let ln = c.localName
+      return ln !== 'template' && ln !== 'script' && ln !== 'style'
+    })
+    for (let def of defs) def.remove()
+    this.remove()
+    for (let def of defs) define(def)
+  }
+}
+
+DefineElement.processor = null
+
+customElements.define('define-element', DefineElement)
+
+export { DefineElement, define }

package/package.json

@@ -1,30 +1,42 @@
 {
   "name": "define-element",
-  "version": "0.0.0",
-  "description": "Template, defining custom elements",
-  "main": "index.js",
+  "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"
+  ],
+  "sideEffects": true,
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "node -r ./test/register.cjs test/test.js"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/spectjs/define-element.git"
+    "url": "git+https://github.com/dy/define-element.git"
   },
   "keywords": [
-    "uce-template",
-    "declarative-custom-element",
-    "vue3",
-    "reactive",
-    "spect",
     "custom-element",
     "web-components",
-    "element-props",
-    "template-parts"
+    "declarative",
+    "html",
+    "no-build",
+    "template",
+    "shadow-dom"
   ],
   "author": "dmitry iv.",
   "license": "ISC",
   "bugs": {
-    "url": "https://github.com/spectjs/define-element/issues"
+    "url": "https://github.com/dy/define-element/issues"
   },
-  "homepage": "https://github.com/spectjs/define-element#readme"
+  "homepage": "https://github.com/dy/define-element#readme",
+  "devDependencies": {
+    "@github/template-parts": "^0.7.1",
+    "alpinejs": "^3.15.8",
+    "jsdom": "^28.1.0",
+    "petite-vue": "^0.4.1",
+    "tst": "^9.2.2",
+    "wait-please": "^3.1.0"
+  }
 }