@ruledwdl/dom 0.1.0

package/LICENSE

@@ -0,0 +1,71 @@
+GNU AFFERO GENERAL PUBLIC LICENSE
+Version 3, 19 November 2007
+
+Copyright (C) 2026 WDL Project Contributors
+
+Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
+
+Preamble
+
+The GNU Affero General Public License is a free, copyleft license for software and other kinds of works, specifically designed to ensure cooperation with the community in the case of network server software.
+
+The licenses for most software and other practical works are designed to take away your freedom to share and change the works. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change all versions of a program--to make sure it remains free software for all its users.
+
+When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for them if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs, and that you know you can do these things.
+
+Developers that use the GNU GPL protect your rights with two steps: (1) assert copyright on the software, and (2) offer you this license giving you legal permission to copy, distribute and/or modify it.
+
+A secondary benefit of defending all users' freedom is that improvements made in one version of the program, if encountered by others, can be shared. Many developers of free software are heartened and encouraged by the cooperation that will result. Particularly in the case of software on network servers, the GNU General Public License does not ensure that modified versions will be made available to the network community. Thus, this license specifically provides that modified versions must be made available over network servers.
+
+TERMS AND CONDITIONS
+
+0. Definitions.
+
+"This License" refers to version 3 of the GNU Affero General Public License.
+
+"Copyright" also means copyright-like laws that apply to other kinds of works, such as semiconductor masks.
+
+"The Program" refers to any copyrightable work licensed under this License. Each licensee is addressed as "you". "Licensees" and "recipients" may be individuals or organizations.
+
+To "modify" a work means to copy from or adapt all or part of the work in a fashion requiring copyright permission, other than the making of an exact copy. The resulting work is called a "modified version" of the earlier work or a work "based on" the earlier work.
+
+A "covered work" means either the unmodified Program or a work based on the Program.
+
+To "propagate" a work means to do anything with it that, without permission, would make you directly or secondarily liable for infringement under applicable copyright law, except executing it on a computer or modifying a private copy. Propagation includes copying, distribution (with or without modification), making available to the public, and in some countries other activities as well.
+
+To "convey" a work means any kind of propagation that enables other parties to make or receive copies. Mere interaction with a user through a computer network, with no transfer of a copy, is not conveying.
+
+1. Source Code.
+
+The "source code" for a work means the preferred form of the work for making modifications to it. "Object code" means any non-source form of a work.
+
+2. Basic Permissions.
+
+All rights granted under this License are granted for the term of copyright on the Program, and are irrevocable provided the stated conditions are met. This License explicitly affirms your unlimited permission to run the unmodified Program. The output from running a covered work is covered by this License only if the output, given its content, constitutes a covered work. This License acknowledges your rights of fair use or other equivalent, as provided by copyright law.
+
+3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+No covered work shall be deemed part of an effective technological measure under any applicable law fulfilling obligations under article 11 of the WIPO copyright treaty adopted on 20 December 1996, or similar laws prohibiting or restricting circumvention of such measures.
+
+4. Conveying Verbatim Copies.
+
+You may convey verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice; keep intact all notices stating that this License and any non-permissive terms added in accord with section 7 apply to the code; keep intact all notices of the absence of any warranty; and give all recipients a copy of this License along with the Program.
+
+5. Conveying Modified Source Versions.
+
+You may convey a work based on the Program, or the modifications to produce it from the Program, in the form of source code under the terms of section 4, provided that you also meet all of these conditions:
+
+a) The work must carry prominent notices stating that you modified it, and giving a relevant date.
+b) The work must carry prominent notices stating that it is released under this License and any conditions added under section 7.
+c) You must license the entire work, as a whole, under this License to anyone who comes into possession of a copy.
+d) If the Program has interactive user interfaces, each must display Appropriate Legal Notices; however, if the Program has interactive interfaces that do not display Appropriate Legal Notices, your work need not make them do so.
+
+6. Conveying Non-Source Forms.
+
+You may convey a covered work in object code form under the terms of sections 4 and 5, provided that you also convey the machine-readable Corresponding Source under the terms of this License.
+
+7. Remote Network Interaction; Additional Terms.
+
+Notwithstanding any other provision of this License, if you modify the Program, your modified version must prominently offer all users interacting with it remotely through a computer network an opportunity to receive the Corresponding Source of your version by providing access to the Corresponding Source from a network server at no charge, through some standard or customary means of facilitating copying of software.
+
+END OF TERMS AND CONDITIONS

package/README.md

@@ -0,0 +1,146 @@
+# `@ruledwdl/dom`
+
+> Native DOM runtime for `@ruledwdl/state` with surgical element updates driven by state events.
+
+`@ruledwdl/dom` provides fine-grained, surgical DOM updates for components managed by `@ruledwdl/state`. Whenever layer structures, attributes, variants, registry rules, or data change in state, `@ruledwdl/dom` updates the live DOM using native browser APIs (`createElement`, `insertBefore`, `remove`, `setAttribute`) without full re-renders or `innerHTML` wipes.
+
+[![npm version](https://img.shields.io/npm/v/@ruledwdl/dom.svg)](https://www.npmjs.com/package/@ruledwdl/dom)
+[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](LICENSE)
+
+---
+
+## Features
+
+- **Surgical DOM Updates**: Real-time element insertions, deletions, re-ordering, wrapping, and tag updates driven by `@ruledwdl/state` change events.
+- **Zero `innerHTML` on Mutations**: Preserves existing DOM state, focus, transitions, and event listeners during updates.
+- **Registry Scoped CSS Injection**: Automatically generates and updates `<style data-wdl-dom="...">` tags for Schema V2.1 Scoped CSS rules.
+- **Fast Live Map**: Maintains an internal `Map<semanticId, HTMLElement>` for O(1) element lookups and precision patching.
+- **Zero External Dependencies**: Pure native ESM package; works directly in modern browsers and client-side web apps.
+
+---
+
+## Installation
+
+### NPM Package
+```bash
+npm install @ruledwdl/dom @ruledwdl/state
+```
+
+```javascript
+import { ComponentManager } from '@ruledwdl/state';
+import { createWdlDom, WdlDom } from '@ruledwdl/dom';
+```
+
+---
+
+## CDN / Direct Browser Usage (No Build Step)
+
+### ESM Import via jsDelivr
+```html
+<script type="module">
+  import { ComponentManager } from 'https://cdn.jsdelivr.net/npm/@ruledwdl/state/dist/index.js';
+  import { createWdlDom } from 'https://cdn.jsdelivr.net/npm/@ruledwdl/dom/dist/wdl-dom.min.js';
+
+  const mgr = new ComponentManager();
+  const hero = mgr.create('hero', {
+    layers: 'section.hero > h1.title + p.subtitle',
+    attr: {
+      '.title': { text: 'Hello World' },
+      '.subtitle': { text: 'Reactive WDL Component' }
+    }
+  });
+
+  const dom = createWdlDom({
+    container: document.getElementById('app'),
+    component: hero
+  });
+</script>
+```
+
+### ESM Import via unpkg
+```html
+<script type="module">
+  import { ComponentManager } from 'https://unpkg.com/@ruledwdl/state/dist/index.js';
+  import { createWdlDom } from 'https://unpkg.com/@ruledwdl/dom/dist/wdl-dom.min.js';
+</script>
+```
+
+---
+
+## Quick Start Example
+
+```javascript
+import { ComponentManager } from '@ruledwdl/state';
+import { createWdlDom } from '@ruledwdl/dom';
+
+// 1. Initialize component state
+const manager = new ComponentManager();
+const hero = manager.create('hero', {
+  layers: 'section.hero > h1.title',
+  attr: {
+    '.title': { text: 'Hello RuledWDL' }
+  }
+});
+
+// 2. Mount DOM runtime
+const dom = createWdlDom({
+  container: document.querySelector('#app'),
+  component: hero
+});
+
+// 3. Surgical Mutations:
+// Prepend child
+hero.layers.prepend('hero', 'span.badge');
+hero.attr.set('badge', { text: 'New Release' });
+
+// Sibling insertion
+hero.layers.after('title', 'p.subtitle');
+hero.attr.set('subtitle', { text: 'Surgically injected subtitle' });
+
+// Child append
+hero.layers.append('hero', 'button.cta');
+hero.attr.set('cta', { text: 'Click Here', class: 'btn-primary' });
+
+// Wrap element
+hero.layers.wrap('title', 'div.title-wrapper');
+
+// Unwrap element (hoist title back)
+hero.layers.unwrap('title-wrapper');
+
+// Move element
+hero.layers.move('cta', 'title', 'before');
+
+// Variant change (adds data-variant="elevated")
+hero.variant.set('elevated');
+
+// Registry Scoped CSS update (updates <style data-wdl-dom="hero">)
+hero.registry.addRule({
+  selector: '& .cta',
+  css: { background: '#0284c7', color: '#ffffff' }
+});
+
+// 4. Teardown
+// dom.destroy();
+```
+
+---
+
+## Core API
+
+### `createWdlDom(options)`
+- `container` (`HTMLElement | string`): Container element or selector to mount into.
+- `component` (`ComponentState`): Live `ComponentState` instance from `@ruledwdl/state`.
+- `onDataBind` (`(container, path, value) => void`): Optional callback for data binding.
+- `styleTarget` (`HTMLElement | Document`): Where to inject component style tags (default: `document.head`).
+- `debug` (`boolean`): Enable console logging.
+
+### Instance Methods
+- `dom.remount()`: Rebuild the entire DOM from state snapshot.
+- `dom.getLiveMap()`: Returns a snapshot copy of `Map<semanticId, HTMLElement>`.
+- `dom.destroy()`: Removes event listeners, empties container, and cleans up style tags.
+
+---
+
+## License
+
+Licensed under the [GNU Affero General Public License v3.0 (AGPL-3.0-or-later)](./LICENSE).

package/dist/wdl-dom.min.js

@@ -0,0 +1,2 @@
+var f=new Set(["text","class","html"]);function p(l){if(typeof l!="string"){if(l&&typeof l=="object")return{tag:String(l.tag||"div").toLowerCase(),semanticId:String(l.semanticId||l.id||"").replace(/^\./,"")};throw new Error("[wdl-dom] invalid layer expression")}let e=l.trim(),i=e.match(/^([a-zA-Z][a-zA-Z0-9_-]*)(?:\.([a-zA-Z0-9_-]+))?$/);return i?{tag:i[1].toLowerCase(),semanticId:(i[2]||"").replace(/^\./,"")}:{tag:e.toLowerCase()||"div",semanticId:""}}function g(l){if(Array.isArray(l))return structuredClone(l);if(typeof l!="string"||!l.trim())return[];let e={tag:"__root__",semanticId:"",children:[]},i=[e],s=0,a=()=>i[i.length-1];for(;s<l.length;){let t=l[s];if(/\s/.test(t)){s++;continue}if(t===">"){let r=a().children[a().children.length-1];r&&i.push(r),s++;continue}if(t==="+"){s++;continue}if(t==="<"){s++,i.length>1&&i.pop();continue}let n="";for(;s<l.length&&/[a-zA-Z0-9_-]/.test(l[s]);)n+=l[s++];let o="";if(l[s]===".")for(s++;s<l.length&&/[a-zA-Z0-9_-]/.test(l[s]);)o+=l[s++];a().children.push({tag:n.toLowerCase()||"div",semanticId:o,children:[]})}return e.children}function h(l){return l==null?"":String(l).replace(/^\./,"")}var m=class{constructor(e={}){let{container:i,component:s,onDataBind:a=null,styleTarget:t=typeof document<"u"?document.head:null,debug:n=!1}=e;if(!i)throw new Error("[wdl-dom] container is required");if(!s)throw new Error("[wdl-dom] component (ComponentState) is required");if(this.container=typeof i=="string"?document.querySelector(i):i,!this.container)throw new Error("[wdl-dom] container not found");this.component=s,this.onDataBind=a,this.styleTarget=t,this.debug=n,this.liveMap=new Map,this._unsubs=[],this._styleEl=null,this._mount(),this._bindStateEvents()}remount(){this._mount()}getLiveMap(){return new Map(this.liveMap)}destroy(){this._unsubs.forEach(e=>{try{e()}catch{}}),this._unsubs=[],this.container.replaceChildren(),this.liveMap.clear(),this._styleEl&&this._styleEl.parentNode&&this._styleEl.parentNode.removeChild(this._styleEl),this._styleEl=null}_mount(){this.container.replaceChildren(),this.liveMap.clear();let e;try{e=typeof this.component.layers?.tree=="function"?this.component.layers.tree():g(this.component.layers?.list?.()??this.component.getSnapshot?.()?.layers)}catch(s){this._log("warn","tree() failed, falling back to simple parse",s);let a=this.component.getSnapshot?.()?.layers??"";e=g(a)}Array.isArray(e)||(e=[]);for(let s of e){let a=this._createElementFromNode(s);this.container.appendChild(a)}let i=this.component.attr?.list?.()??this.component.getSnapshot?.()?.attr??{};for(let[s,a]of Object.entries(i))this._applyAttrs(h(s),a);this._applyRootVariant(),this._syncRegistryStyles(),this._log("mount",`mounted ${this.liveMap.size} nodes`)}_createElementFromNode(e){let i=(e.tag||"div").toLowerCase(),s=h(e.semanticId||e.id||""),a=document.createElement(i);if(s&&(a.classList.add(s),a.setAttribute("wdl-comp",s),this.liveMap.set(s,a)),Array.isArray(e.children))for(let t of e.children)a.appendChild(this._createElementFromNode(t));return a}_bindStateEvents(){let e=this.component;if(typeof e.on!="function"){this._log("warn","component has no .on() \u2014 events will not be applied");return}let i=a=>this._onStateEvent(a),s=["layers:change","attr:change","data:change","variant:change","registry:change"];for(let a of s){let t=e.on(a,i);typeof t=="function"?this._unsubs.push(t):this._unsubs.push(()=>e.off?.(a,i))}}_onStateEvent(e){if(!(!e||!e.type))switch(this._log("event",e.type,e.action,e.targetId,e.payload),e.type){case"layers:change":this._handleLayers(e);break;case"attr:change":this._handleAttr(e);break;case"data:change":this._handleData(e);break;case"variant:change":this._handleVariant(e);break;case"registry:change":this._handleRegistry(e);break;default:this._log("warn","unknown event type",e.type)}}_handleLayers(e){let{action:i,targetId:s,payload:a}=e,t=h(s);switch(i){case"set":{this._mount();break}case"append":{let n=this.liveMap.get(t);if(!n){this._log("warn",`append: parent "${t}" not in liveMap \u2014 remounting`),this._mount();return}let o=p(a),r=this._createElementFromNode({tag:o.tag,semanticId:o.semanticId,children:[]});n.appendChild(r),this._log("op",`append <${o.tag}.${o.semanticId}> \u2192 #${t}`);break}case"prepend":{let n=this.liveMap.get(t);if(!n){this._log("warn",`prepend: parent "${t}" not in liveMap \u2014 remounting`),this._mount();return}let o=p(a),r=this._createElementFromNode({tag:o.tag,semanticId:o.semanticId,children:[]});n.insertBefore(r,n.firstChild),this._log("op",`prepend <${o.tag}.${o.semanticId}> \u2192 #${t}`);break}case"before":case"after":{let n=this.liveMap.get(t);if(!n||!n.parentNode){this._log("warn",`${i}: target "${t}" missing \u2014 remounting`),this._mount();return}let o=p(a),r=this._createElementFromNode({tag:o.tag,semanticId:o.semanticId,children:[]});i==="before"?n.parentNode.insertBefore(r,n):n.parentNode.insertBefore(r,n.nextSibling),this._log("op",`${i} <${o.tag}.${o.semanticId}> relative to #${t}`);break}case"wrap":{let n=this.liveMap.get(t);if(!n||!n.parentNode){this._log("warn",`wrap: target "${t}" missing \u2014 remounting`),this._mount();return}let o=p(a),r=this._createElementFromNode({tag:o.tag,semanticId:o.semanticId,children:[]});n.parentNode.insertBefore(r,n),r.appendChild(n),this._log("op",`wrap #${t} with <${o.tag}.${o.semanticId}>`);break}case"unwrap":{let n=this.liveMap.get(t);if(!n||!n.parentNode){this._log("warn",`unwrap: target "${t}" missing \u2014 remounting`),this._mount();return}let o=n.parentNode;for(;n.firstChild;)o.insertBefore(n.firstChild,n);n.remove(),this.liveMap.delete(t),this._log("op",`unwrap #${t}`);break}case"move":{let n=this.liveMap.get(t),{targetSemanticId:o,position:r}=a||{},c=h(o),d=this.liveMap.get(c);if(!n||!d){this._log("warn",`move: source "${t}" or target "${c}" missing \u2014 remounting`),this._mount();return}r==="before"?d.parentNode?.insertBefore(n,d):r==="after"?d.parentNode?.insertBefore(n,d.nextSibling):d.appendChild(n),this._log("op",`move #${t} -> ${r} #${c}`);break}case"remove":{let n=this.liveMap.get(t);if(!n){this._log("warn",`remove: #${t} not in liveMap`);return}for(let[o,r]of[...this.liveMap])o!==t&&n.contains(r)&&this.liveMap.delete(o);n.remove(),this.liveMap.delete(t),this._log("op",`remove #${t}`);break}case"update":{let n=this.liveMap.get(t);if(!n){this._log("warn",`update: #${t} missing \u2014 remounting`),this._mount();return}let o=a||{};if(o.tag&&o.tag.toLowerCase()!==n.tagName.toLowerCase()){let r=document.createElement(String(o.tag).toLowerCase());for(let c of n.attributes)r.setAttribute(c.name,c.value);for(;n.firstChild;)r.appendChild(n.firstChild);if(n.parentNode?.replaceChild(r,n),this.liveMap.set(t,r),o.semanticId&&h(o.semanticId)!==t){let c=h(o.semanticId);r.classList.remove(t),r.classList.add(c),r.setAttribute("wdl-comp",c),this.liveMap.delete(t),this.liveMap.set(c,r)}}else if(o.semanticId&&h(o.semanticId)!==t){let r=h(o.semanticId);n.classList.remove(t),n.classList.add(r),n.setAttribute("wdl-comp",r),this.liveMap.delete(t),this.liveMap.set(r,n)}this._log("op",`update #${t}`,o);break}default:this._log("warn",`layers: unknown action "${i}" \u2014 remounting`),this._mount()}}_handleAttr(e){let{action:i,targetId:s,payload:a}=e,t=h(s);if(i==="set"||i==="update"){this._applyAttrs(t,a||{}),this._log("op",`attr.${i} #${t}`,a);return}if(i==="remove"){let n=this.liveMap.get(t);if(!n)return;let o=a;o==null||o===""?(n.textContent="",n.className=t,this._log("op",`attr.remove entire #${t}`)):o==="text"?(n.textContent="",this._log("op",`attr.remove text from #${t}`)):o==="class"?(n.className=t,this._log("op",`attr.remove class from #${t}`)):o==="html"?(n.innerHTML="",this._log("op",`attr.remove html from #${t}`)):(n.removeAttribute(o),this._log("op",`attr.remove ${o} from #${t}`))}}_applyAttrs(e,i){if(!i||typeof i!="object")return;let s=this.liveMap.get(e);if(!s){this._log("warn",`attr: #${e} not in liveMap`);return}if(i.text!==void 0&&(s.textContent=String(i.text)),i.html!==void 0&&(s.innerHTML=String(i.html)),i.class!==void 0){let a=String(i.class).trim();s.className=a?`${e} ${a}`:e}for(let[a,t]of Object.entries(i))if(!f.has(a)){if(a==="style"&&t&&typeof t=="object"){Object.assign(s.style,t);continue}t==null?s.removeAttribute(a):s.setAttribute(a,String(t))}}_handleData(e){let{action:i,targetId:s,payload:a}=e,t=s||"";if(typeof this.onDataBind=="function")try{this.onDataBind(this.container,t,i==="remove"?void 0:a)}catch(n){this._log("warn","onDataBind error",n)}this._log("op",`data.${i} ${t}`,i==="remove"?void 0:a)}_handleVariant(e){let{targetId:i,payload:s}=e,a=h(i)||this._rootSemanticId(),t=this.liveMap.get(a);if(!t){let n=this._rootSemanticId(),o=n?this.liveMap.get(n):null;o&&(s?o.dataset.variant=String(s):delete o.dataset.variant,this._log("op",`variant \u2192 ${s||"(none)"} on #${n}`));return}s?t.dataset.variant=String(s):delete t.dataset.variant,this._log("op",`variant \u2192 ${s||"(none)"} on #${a}`)}_applyRootVariant(){let e=this.component.attr?.list?.()??this.component.getSnapshot?.()?.attr??{},i=this._rootSemanticId();if(!i)return;let s="."+i,a=e[s]?.["data-variant"]??e["."]?.["data-variant"]??null;a&&this.liveMap.has(i)&&(this.liveMap.get(i).dataset.variant=String(a))}_rootSemanticId(){for(let[i,s]of this.liveMap)if(s.parentNode===this.container)return i;let e=this.liveMap.keys().next();return e.done?"":e.value}_handleRegistry(e){this._syncRegistryStyles(),this._log("op",`registry.${e.action}`)}_syncRegistryStyles(){if(!this.styleTarget)return;let e=this.component.registry?.get?.()??this.component.getSnapshot?.()?.registry??null,i=this.component.id||this.component.getSnapshot?.()?.id||"comp";if(this._styleEl||(this._styleEl=document.createElement("style"),this._styleEl.setAttribute("data-wdl-dom",i),this.styleTarget.appendChild(this._styleEl)),!e){this._styleEl.textContent="";return}let s=Array.isArray(e.rules)?e.rules:[],a=[];if(e.vars&&typeof e.vars=="object"){let t=Object.entries(e.vars).map(([n,o])=>`--${n}: ${o};`).join(" ");t&&a.push(`:root, [wdl-comp] { ${t} }`)}for(let t of s){if(!t||!t.selector)continue;let n=typeof t.css=="string"?t.css:t.css&&typeof t.css=="object"?Object.entries(t.css).map(([c,d])=>`${u(c)}: ${d};`).join(" "):"";if(!n)continue;let o=t.selector.startsWith("&")?t.selector.replace("&",`[wdl-comp="${i}"]`):t.selector,r=t.media?`@media ${t.media} { ${o} { ${n} } }`:`${o} { ${n} }`;a.push(r)}this._styleEl.textContent=a.join(`
+`)}_log(e,...i){if(!this.debug&&e!=="warn")return;let s=`[wdl-dom:${e}]`;e==="warn"?console.warn(s,...i):console.log(s,...i)}};function u(l){return String(l).replace(/[A-Z]/g,e=>"-"+e.toLowerCase())}function _(l){return new m(l)}var y=_;export{m as WdlDom,_ as createWdlDom,y as default};