html-element-property-mixins - npm Package Compare versions

Comparing version 0.9.5 to 0.10.0

package.json

 {
   "name": "html-element-property-mixins",
-  "version": "0.9.5",
+  "version": "0.10.0",
   "description": "A collection of mixins extending HTMLElement with properties.",
@@ -5,0 +5,0 @@ "main": "src/index.js",

README.md

@@ -17,2 +17,10 @@ # # html-element-property-mixins
 
+Furthermore, we created a bunch of addons:
+
+1. **[PropertiesChangedCallback](#PropertiesChangedCallback)** Debounces / batches property changes for efficient DOM-rendering.
+2. **[PropertyChangedHandler](#PropertyChangedHandler)** enables change handlers methods for property changes.
+3. **[PropertiesChangedHandler](#PropertiesChangedHandler)** enables change handlers methods for multiple property changes.
+
+## Mixins
+
 ### ObservedProperties
@@ -290,2 +298,140 @@
 }
-```
+```
+
+If you use the [PropertyChangedHandler](#PropertyChangedHandler) addon, you can add 'changedHandler' to your config:
+
+```javascript
+class DemoElement extends PropertyChangedHandler(Properties(HTMLElement)) {
+
+  static get properties() {
+    return {
+      age: {
+        observe: true,
+        changedHandler: '_firstNameChanged',
+      }
+    }
+  }
+
+  _firstNameChanged(oldValue, newValue) {
+    //custom handler here!
+  }
+
+}
+```
+
+
+## Addons
+
+### PropertiesChangedCallback
+```javascript
+import { ObservedProperties } from 'html-element-property-mixins';
+import { PropertiesChangedCallback } from 'html-element-property-mixins/src/addons';
+
+```
+
+When declaring observed properties using the `observedProperties` array, property changes are fired each time a a property changes using the `propertyChangedCallback`. For efficiency reasons (e.g. when rendering DOM), the `propertiesChangedCallback` (plural!) can be used. This callback is debounced by cancel / requestAnimationFrame on every property change. In the following example, `render` is invoked only once:
+
+```javascript
+import { PropertiesChangedCallback } from 'html-element-property-mixins/src/addons';
+import { ObservedProperties } from 'html-element-property-mixins';
+
+class DemoElement extends PropertiesChangedCallback(ObservedProperties(HTMLElement)) {
+
+  constructor() {
+    super();
+    this._renderCount = 0;
+  }
+
+  static get observedProperties() {
+    return ['firstName', 'lastName', 'age'];
+  }
+
+  propertiesChangedCallback(propNames, oldValues, newValues) {
+    this._renderCount++;
+    this.render();
+  }
+
+  render() {
+    this.innerHTML = `
+      Hello, ${this.firstName} ${this.lastName} (${this.age} years).<br>
+      Render Count = ${this._renderCount}. 
+    `
+  }
+
+  constructor() {
+    super();
+    this.firstName = 'Amina';
+    this.lastName = 'Hamzaoui';
+    this.age = 24;
+  }
+
+}
+```
+
+### PropertyChangedHandler
+
+```javascript
+import { ObservedProperties } from 'html-element-property-mixins';
+import { PropertyChangedHandler } from 'html-element-property-mixins/src/addons';
+```
+
+Value changes to properties whitelisted in the `observedProperties` array are always notified using `propertyChangedCallback`. PropertyChangedHandler provides for custom callbacks for property changes:
+
+```javascript
+class DemoElement extends PropertyChangedHandler(ObservedProperties((HTMLElement)) {
+  static get observedProperties() {
+    return ['firstName']
+  }
+
+  static get propertyChangedHandlers() {
+    return {
+      firstName: function(newValue, oldValue) {
+        console.info('firstName changed!', newValue, oldValue);  
+      }
+    }
+  }
+}
+```
+
+Alternatively, callbacks can be passed as string references:
+```javascript
+static get propertyChangedHandlers() {
+  return { firstName: '_firstNameChanged' }
+}
+
+_firstNameChanged(newValue, oldValue) {
+  console.info('firstName changed!', newValue, oldValue);
+}
+```
+
+> **Note**: `PropertyChangedHandler` should always be used in conjunction with `ObservedProperties`.
+
+### PropertiesChangedHandler
+
+```javascript
+import { ObservedProperties } from 'html-element-property-mixins';
+import { PropertiesChangedHandler } from 'html-element-property-mixins/src/addons';
+```
+
+Its plural companion `propertiesChangedHandlers` can be used to invoke a function when one of many properties have changed. Key / value pairs are now swapped. A key refers to the handler function, the value holds an array of the observed properties.
+
+```javascript
+class DemoElement extends PropertiesChangedHandler(ObservedProperties((HTMLElement)) {
+  static get observedProperties() {
+    return ['firstName', 'lastName']
+  }
+
+  static get propertiesChangedHandlers() {
+    return {
+      _nameChanged: ['firstName', 'lastName']
+    }
+  }
+
+  _nameChanged(propNames, newValues, oldValues) {
+    console.info(newValues.firstName, newValues.lastName);
+  }
+
+}
+```
+
+> **Note**: `PropertiesChangedHandler` should always be used in conjunction with `ObservedProperties`.

src/properties-mixin.js

@@ -21,2 +21,6 @@ import { ObservedProperties } from './observed-properties-mixin.js';
 
+  static get propertyChangedHandlers() {
+    return this.__getPropertyValues.call(this, 'changedHandler');
+  }
+
   static get propertyAttributeNames() {
@@ -23,0 +27,0 @@ const propValues = {};

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

43702

increased by36.98%

Number of package files

28

increased by33.33%

Lines of code

407

increased by15.95%

Number of lines in readme file

435

increased by50.52%

No dependency changes