wrec 0.4.1 → 0.4.3

package/README.md

@@ -37,37 +37,38 @@ Here are the steps:
    ```
 
 1. Create the file `my-counter.js` containing the following.
-   The comments `/*css*/` and `/*html*/` trigger the VS Code extension
-   "es6-string-html" to add syntax highlighting to the CSS and HTML strings.
+   The tagged template literals with the tags `css` and `html` trigger the VS Code extension
+   "Prettier" to add syntax highlighting and format the CSS and HTML strings.
 
    ```js
-   import Wrec from "wrec";
+   import Wrec, { css, html } from "wrec";
 
    class MyCounter extends Wrec {
      static properties = {
        count: { type: Number },
      };
 
-     static css = /*css*/ `
+     static css = css`
        .counter {
          display: flex;
          align-items: center;
          gap: 0.5rem;
        }
-   
+
        button {
          background-color: lightgreen;
        }
-   
+
        button:disabled {
          background-color: gray;
        }
      `;
 
-     static html = /*html*/ `
+     static html = html`
        <div>
-         <button onClick="decrement" type="button"
-           disabled="this.count === 0">-</button>
+         <button onClick="decrement" type="button" disabled="this.count === 0">
+           -
+         </button>
          <span>this.count</span>
          <button onClick="this.count++" type="button">+</button>
          <span>(this.count < 10 ? "single" : "double") + " digit"</span>
@@ -103,15 +104,21 @@ Here are the steps:
 
 ## More Detail
 
+When the value of an attribute is a Boolean,
+wrec adds the attribute to the element with no value
+or removes the attribute from the element.
+This is commonly used for attributes like `disabled`.
+
 To wire event listeners,
 Wrec looks for attributes whose name begins with "on".
 It assumes the remainder of the attribute name is an event name.
 It also assumes that the value of the attribute is either
 a method name that should be called or code that should be executed
 when that event is dispatched.
-For example, the attribute `onclick="increment"` causes Wrec to
+For example, with the attribute `onclick="increment"`,
+if `increment` is a method in the component, wrec will
 add an event listener to the element containing the attribute
-for "click" events and calls `this.increment(event)`.
+for "click" events and call `this.increment(event)`.
 Alternatively, the attribute `onclick="this.count++"`
 adds an event listener that increments `this.count`
 when the element is clicked.
@@ -129,16 +136,31 @@ Only attribute values and text content
 that refer to modified web component properties are updated.
 Attribute values and text content that contain references to properties
 must be valid JavaScript expressions that are NOT surrounded by `${...}`.
-For an example of this kind of web component, see `demo/hello-world.js`.
+For an example of this kind of web component, see `examples/hello-world.js`.
+
+Wrec evaluates JavaScript expressions in the context of a web component instance
+which can be referred to with the `this` keyword in the expressions.
 
 Wrec supports conditional and iterative generation of HTML.
-See `demo/temperature-eval.js` for an example of a web component
+See `examples/temperature-eval.js` for an example of a web component
 that conditionally decides what to render based on an attribute value.
-See `demo/radio-group.js` for an example of a web component
+See `examples/radio-group.js` for an example of a web component
 that iterates over values in a comma-delimited attribute value
 to determine what to render.
 
-Wrec supports two-way data binding for HTML form elements.
+Data binding in Lit is not two-way like in wrec.
+A Lit component cannot simply pass one of its properties to
+a child Lit component and have the child can update the property.
+The child must dispatch custom events that
+the parent listens for so it can update its own state.
+For an example of this, see
+[wrec-compare](https://github.com/mvolkmann/lit-examples/blob/main/wrec-compare/binding-demo.ts).
+
+Wrec supports two-way data binding.
+See the example component binding-demo
+and the components it renders.
+
+Wrec two-way data binding can be used with HTML form elements.
 
 - `input` and `select` elements can have a `value` attribute
   whose value is "this.somePropertyName".
@@ -149,7 +171,7 @@ In all these cases, if the user changes the value of the form element,
 the specified property is updated.
 When the property is updated,
 the displayed value of the form element is updated.
-For examples, see `demo/data-bind.js`.
+For examples, see `examples/data-bind.js`.
 
 Web components that extend `Wrec` can contribute values to
 form submissions by adding the following line to their class definition.
@@ -184,7 +206,7 @@ to any domain except that of your web app:
 
 ## More Examples
 
-Check out the web app in the `demo` directory.
+Check out the web app in the `examples` directory.
 To run it, cd to that directory, enter `npm install`,
 enter `npm run dev`, and browse localhost:5173.
 
@@ -194,5 +216,17 @@ The next two uses the Wrec library.
 Compare the files `counter-vanilla.js` and `counter-wrec.js`
 to see how much using Wrec simplifies the code.
 
-The `demo` app renders several other web components that are built with wrec.
+The `examples` app renders several other
+web components that are built with wrec.
 Examine their code for more examples of wrec usage.
+
+## Tests
+
+wrec has an extensive set of Playwright tests.
+To run them:
+
+1. Clone the wrec repository.
+1. cd to the `examples` directory.
+1. Enter `npm install`.
+1. Enter `npm run testui`.
+1. Click the right pointing triangle.

package/dist/wrec.min.js

@@ -1 +1 @@
-const FIRST_CHAR="a-zA-Z_$",OTHER_CHAR=FIRST_CHAR+"0-9",IDENTIFIER=`[${FIRST_CHAR}][${OTHER_CHAR}]*`,REFERENCE_RE=new RegExp(`^this.${IDENTIFIER}$`),REFERENCES_RE=new RegExp(`this.${IDENTIFIER}`,"g"),SKIP=5;class Wrec extends HTMLElement{static#t=document.createElement("template");#e=new Map;#s;#r;#o=new Map;constructor(){super(),this.attachShadow({mode:"open"});this.constructor["#propertyToExpressionsMap"]||(this.constructor["#propertyToExpressionsMap"]=new Map),this.constructor.formAssociated&&(this.#r=this.attachInternals(),this.#s=new FormData,this.#r.setFormValue(this.#s))}attributeChangedCallback(t,e,s){const r=this.#n(t,s);this[t]=r,this.#i(t,r)}#a(t,e,s){t.addEventListener("input",t=>{this[e]=t.target.value});let r=this.#o.get(e);r||(r=[],this.#o.set(e,r)),r.push(s?{element:t,attrName:s}:t)}buildDOM(){const t=this.constructor;let e=t.css?`<style>${t.css}</style>`:"";e+=t.html,Wrec.#t.innerHTML=e,this.shadowRoot.replaceChildren(Wrec.#t.content.cloneNode(!0))}connectedCallback(){this.#c(),this.buildDOM(),requestAnimationFrame(()=>{this.#l(this.shadowRoot),this.#h(this.shadowRoot),this.constructor.processed=!0})}#c(){const t=this.constructor.properties,{observedAttributes:e}=this.constructor;for(const[s,r]of Object.entries(t))this.#u(s,r,e)}#u(t,e,s){const r=s.includes(t)&&this.hasAttribute(t)?this.#p(t):e.value;this["_"+t]=r,Object.defineProperty(this,t,{enumerable:!0,get(){return this["_"+t]},set(e){if(e===this["_"+t])return;if(this["_"+t]=e,this.hasAttribute(t)){e!==this.#p(t)&&this.#m(this,t,e)}this.#d(t);const s=this.propertyToParentPropertyMap,r=s?s.get(t):null;if(r){this.getRootNode().host.setAttribute(r,e)}this.#i(t,e)}})}#f(t){const e=t.localName.includes("-");for(const s of t.getAttributeNames()){const r=t.getAttribute(s);if(REFERENCE_RE.test(r)){const o=r.substring(SKIP);if(t[o]=this[o],"value"===s&&this.#a(t,o,s),e){let e=t.propertyToParentPropertyMap;e||(e=new Map,t.propertyToParentPropertyMap=e),e.set(s,o)}}this.#E(r,t,s)}}#b(expression){return(()=>eval(expression)).call(this)}#g(t){const{localName:e}=t;if("style"===e)return;const s=t.textContent.trim();if("textarea"===e&&REFERENCE_RE.test(s)){const e=s.substring(SKIP);this.#a(t,e),t.textContent=this[e]}else this.#E(s,t)}#p(t){return this.#n(t,this.getAttribute(t))}#n(t,e){const s=this.constructor.properties[t].type;return s===Number?Number(e):s===Boolean?Boolean(e):e}#h(t){const e=t.querySelectorAll("*");for(const t of e)this.#f(t),t.firstElementChild||this.#g(t)}static get observedAttributes(){return Object.keys(this.properties||{})}#d(t){const e=this.constructor["#propertyToExpressionsMap"].get(t)||[];for(const t of e){const e=this.#b(t),s=this.#e.get(t)||[];for(const t of s)if(t instanceof Element)this.#R(t,e);else{const{element:s,attrName:r}=t;this.#m(s,r,e)}}requestAnimationFrame(()=>{this.#A(t)})}static register(){const t=Wrec.#v(this.name);customElements.get(t)||customElements.define(t,this)}#E(t,e,s){const r=t.match(REFERENCES_RE);if(!r)return;this.constructor.processed||r.forEach(e=>{const s=e.substring(SKIP),r=this.constructor["#propertyToExpressionsMap"];let o=r.get(s);o||(o=[],r.set(s,o)),o.push(t)});let o=this.#e.get(t);o||(o=[],this.#e.set(t,o)),o.push(s?{element:e,attrName:s}:e);const n=this.#b(t);s?this.#m(e,s,n):this.#R(e,n)}static#v=t=>t.replace(/([a-z0-9])([A-Z])/g,"$1-$2").toLowerCase();#i(t,e){this.#s&&(this.#s.set(t,e),this.#r.setFormValue(this.#s))}#m(t,e,s){const r=t.getAttribute(e);"boolean"==typeof s?s?r!==e&&t.setAttribute(e,e):t.removeAttribute(e):r!==s&&t.setAttribute(e,s)}#A(t){const e=this[t],s=this.#o.get(t)||[];for(const t of s)if(t instanceof Element)"textarea"===t.localName?t.value=e:t.textContent=e;else{const{element:s,attrName:r}=t;this.#m(s,r,e),s[r]=e}}#R(t,e){const{localName:s}=t;"textarea"===s?t.value=e:"string"==typeof e&&e.trim().startsWith("<")?(t.innerHTML=e,this.#l(t),this.#h(t)):t.textContent=e}#l(root){const elements=root.querySelectorAll("*");for(const element of elements)for(const attr of element.attributes){const{name:name}=attr;if(name.startsWith("on")){const eventName=name.slice(2).toLowerCase(),{value:value}=attr,fn="function"==typeof this[value]?t=>this[value](t):()=>eval(value);element.addEventListener(eventName,fn),element.removeAttribute(name)}}}}export default Wrec;
+const FIRST_CHAR="a-zA-Z_$",OTHER_CHAR=FIRST_CHAR+"0-9",IDENTIFIER=`[${FIRST_CHAR}][${OTHER_CHAR}]*`,REFERENCE_RE=new RegExp(`^this.${IDENTIFIER}$`),REFERENCES_RE=new RegExp(`this.${IDENTIFIER}`,"g"),SKIP=5;class Wrec extends HTMLElement{static#t=document.createElement("template");#e=new Map;#s;#r;#o=new Map;constructor(){super(),this.attachShadow({mode:"open"});this.constructor["#propertyToExpressionsMap"]||(this.constructor["#propertyToExpressionsMap"]=new Map),this.constructor.formAssociated&&(this.#r=this.attachInternals(),this.#s=new FormData,this.#r.setFormValue(this.#s))}attributeChangedCallback(t,e,s){const r=this.#n(t,s);this[t]=r,this.#i(t,r)}#a(t,e,s){t.addEventListener("input",t=>{this[e]=t.target.value});let r=this.#o.get(e);r||(r=[],this.#o.set(e,r)),r.push(s?{element:t,attrName:s}:t)}buildDOM(){const t=this.constructor;let e=t.css?`<style>${t.css}</style>`:"";e+=t.html,Wrec.#t.innerHTML=e,this.shadowRoot.replaceChildren(Wrec.#t.content.cloneNode(!0))}connectedCallback(){this.#c(),this.buildDOM(),requestAnimationFrame(()=>{this.#l(this.shadowRoot),this.#h(this.shadowRoot),this.constructor.processed=!0})}#c(){const t=this.constructor.properties,{observedAttributes:e}=this.constructor;for(const[s,r]of Object.entries(t))this.#p(s,r,e)}#p(t,e,s){const r=s.includes(t)&&this.hasAttribute(t)?this.#u(t):e.value,o="#"+t;this[o]=r,Object.defineProperty(this,t,{enumerable:!0,get(){return this[o]},set(e){if(e===this[o])return;if(this[o]=e,this.hasAttribute(t)){e!==this.#u(t)&&this.#m(this,t,e)}this.#d(t);const s=this.propertyToParentPropertyMap,r=s?s.get(t):null;if(r){this.getRootNode().host.setAttribute(r,e)}this.#i(t,e)}})}#f(t){const e=t.localName.includes("-");for(const s of t.getAttributeNames()){const r=t.getAttribute(s);if(REFERENCE_RE.test(r)){const o=r.substring(SKIP),n=this[o];if(!n){const t=this.constructor.name;throw new Error(`component ${t} missing property "${o}"`)}if(t[o]=n,"value"===s&&this.#a(t,o,s),e){let e=t.propertyToParentPropertyMap;e||(e=new Map,t.propertyToParentPropertyMap=e),e.set(s,o)}}this.#E(r,t,s)}}#b(expression){return(()=>eval(expression)).call(this)}#g(t){const{localName:e}=t;if("style"===e)return;const s=t.textContent.trim();if("textarea"===e&&REFERENCE_RE.test(s)){const e=s.substring(SKIP);this.#a(t,e),t.textContent=this[e]}else this.#E(s,t)}#u(t){return this.#n(t,this.getAttribute(t))}#n(t,e){const s=this.constructor.properties[t].type;return s===Number?Number(e):s===Boolean?Boolean(e):e}#h(t){const e=t.querySelectorAll("*");for(const t of e)this.#f(t),t.firstElementChild||this.#g(t)}static get observedAttributes(){return Object.keys(this.properties||{})}#d(t){const e=this.constructor["#propertyToExpressionsMap"].get(t)||[];for(const t of e){const e=this.#b(t),s=this.#e.get(t)||[];for(const t of s)if(t instanceof Element)this.#R(t,e);else{const{element:s,attrName:r}=t;this.#m(s,r,e)}}requestAnimationFrame(()=>{this.#A(t)})}static register(){const t=Wrec.#y(this.name);customElements.get(t)||customElements.define(t,this)}#E(t,e,s){const r=t.match(REFERENCES_RE);if(!r)return;this.constructor.processed||r.forEach(e=>{const s=e.substring(SKIP),r=this.constructor["#propertyToExpressionsMap"];let o=r.get(s);o||(o=[],r.set(s,o)),o.push(t)});let o=this.#e.get(t);o||(o=[],this.#e.set(t,o)),o.push(s?{element:e,attrName:s}:e);const n=this.#b(t);s?this.#m(e,s,n):this.#R(e,n)}static#y=t=>t.replace(/([a-z0-9])([A-Z])/g,"$1-$2").toLowerCase();#i(t,e){this.#s&&(this.#s.set(t,e),this.#r.setFormValue(this.#s))}#m(t,e,s){const r=t.getAttribute(e);"boolean"==typeof s?s?r!==e&&t.setAttribute(e,e):t.removeAttribute(e):r!==s&&t.setAttribute(e,s)}#A(t){const e=this[t],s=this.#o.get(t)||[];for(const t of s)if(t instanceof Element)"textarea"===t.localName?t.value=e:t.textContent=e;else{const{element:s,attrName:r}=t;this.#m(s,r,e),s[r]=e}}#R(t,e){const{localName:s}=t;"textarea"===s?t.value=e:"string"==typeof e&&e.trim().startsWith("<")?(t.innerHTML=e,this.#l(t),this.#h(t)):t.textContent=e}#l(root){const elements=root.querySelectorAll("*");for(const element of elements)for(const attr of element.attributes){const{name:name}=attr;if(name.startsWith("on")){const eventName=name.slice(2).toLowerCase(),{value:value}=attr,fn="function"==typeof this[value]?t=>this[value](t):()=>eval(value);element.addEventListener(eventName,fn),element.removeAttribute(name)}}}}export default Wrec;export const css=String.raw;export const html=String.raw;

package/package.json

@@ -2,7 +2,7 @@
   "name": "wrec",
   "description": "a small library that greatly simplifies building web components",
   "author": "R. Mark Volkmann",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "license": "MIT",
   "repository": {
     "type": "git",