npm - @htmlplus/element - Versions diffs - 3.1.4 → 3.2.1 - Mend

@htmlplus/element 3.1.4 → 3.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (12) hide show

package/README.md +101 -10
package/dist/{client-BsD9JZY4.js → client-DgXF8gQw.js} +326 -189
package/dist/{client-5FqNUiuz.d.ts → client-JA8zqh-l.d.ts} +21 -3
package/dist/client.d.ts +1 -1
package/dist/client.js +1 -1
package/dist/constants.d.ts +3 -4
package/dist/constants.js +3 -5
package/dist/internal.d.ts +1 -1
package/dist/internal.js +1 -1
package/dist/jsx-runtime.d.ts +3 -1
package/dist/transformer.js +5 -3
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -146,6 +146,46 @@ In the `index.html` file.
 TODO
 </details>
+<details>
+  <summary>Debounce</summary>
+Ensures that the method executes only after the specified delay, resetting the timer if called again within the delay period.
+In the `my-element.tsx` file.
+```tsx
+import { Debounce, Element, State } from '@htmlplus/element';
+@Element()
+export class MyCounter {
+  @State()
+  value: number = 0;
+  @Debounce()
+  onClick() {
+    this.value++;
+  }
+  render() {
+    return (
+      <host onClick={this.onClick}>
+        Count is {this.value}
+      </host>
+    )
+  }
+}
+```
+In the `index.html` file.
+```html
+<body dir="rtl">
+  <my-counter></my-counter>
+</body>
+```
+</details>
 <details>
   <summary>Direction</summary>
@@ -540,7 +580,7 @@ export class MyButton {
   @Query('.btn')
   buttonRef!: HTMLButtonElement;
-  loadedCallback() {
+  readyCallback() {
     console.log(this.buttonRef); // <button class="btn"></button>
   }
@@ -587,7 +627,7 @@ export class MyButton {
   @QueryAll('span')
   spanRefs!: NodeList;
-  loadedCallback() {
+  readyCallback() {
     console.log(this.spanRefs); // [span, span]
   }
@@ -897,7 +937,7 @@ TODO
 <details>
   <summary>connectedCallback</summary>
-A lifecycle callback method that is called each time the element is added to the document.
+Invoked when an element is added to the document's DOM.
 ```js
 import { Element } from '@htmlplus/element';
@@ -915,7 +955,7 @@ export class MyElement {
 <details>
   <summary>disconnectedCallback</summary>
-TODO
+Invoked when an element is removed from the document's DOM.
 ```js
 import { Element } from '@htmlplus/element';
@@ -931,17 +971,40 @@ export class MyElement {
 </details>
 <details>
-  <summary>loadedCallback</summary>
+  <summary>prepareCallback</summary>
-TODO
+This lifecycle is asynchronous and is invoked before all other lifecycles.
+```js
+import { Element } from '@htmlplus/element';
+@Element()
+export class MyElement {
+  prepareCallback() {
+    return new Promise((resolve) => {
+      setTimeout(resolve, 2500);
+    })
+  }
+  connectedCallback() {
+    console.log('The element connects after 2500 milliseconds!');
+  }
+}
+```
+</details>
+<details>
+  <summary>readyCallback</summary>
+Invoked after the elements's DOM has been updated the first time, immediately before `updatedCallback` is called.
 ```js
 import { Element } from '@htmlplus/element';
 @Element()
 export class MyElement {
-  loadedCallback() {
-    console.log('Element is loaded!');
+  readyCallback() {
+    console.log('Element is ready!');
   }
 }
 ```
@@ -951,14 +1014,42 @@ export class MyElement {
 <details>
   <summary>updateCallback</summary>
-TODO
+Invoked before the element is rendered, this method receives a Map where keys represent the names of changed properties, and values hold their corresponding previous states. Modifying Properties/State within this method does not trigger an element update.
+```js
+import { Element, Property } from '@htmlplus/element';
+@Element()
+export class MyElement {
+  @Property()
+  value?: number = 0;
+  updateCallback(changes) {
+    console.log('Changed properties are: ', changes);
+  }
+}
+```
 </details>
 <details>
   <summary>updatedCallback</summary>
-TODO
+Invoked after the element is rendered, this method receives a Map where keys represent the names of changed properties, and values hold their corresponding previous states.
+```js
+import { Element, Property } from '@htmlplus/element';
+@Element()
+export class MyElement {
+  @Property()
+  value?: number = 0;
+  updatedCallback(changes) {
+    console.log('Changed properties are: ', changes);
+  }
+}
+```
 </details>

package/dist/{client-BsD9JZY4.js → client-DgXF8gQw.js} RENAMED Viewed

@@ -1,21 +1,5 @@
-import { kebabCase, camelCase, pascalCase } from 'change-case';
-import { API_HOST, STATIC_TAG, API_STACKS, API_REQUEST, API_CONNECTED, LIFECYCLE_UPDATE, STATIC_STYLE, API_STYLE, LIFECYCLE_UPDATED, API_RENDER_COMPLETED, METHOD_RENDER, TYPE_BOOLEAN, TYPE_NUMBER, TYPE_NULL, TYPE_DATE, TYPE_ARRAY, TYPE_OBJECT, TYPE_UNDEFINED, LIFECYCLE_CONNECTED, LIFECYCLE_DISCONNECTED, KEY, API_INSTANCE, MAPPER, LIFECYCLE_CONSTRUCTED, LIFECYCLE_ADOPTED, LIFECYCLE_LOADED } from './constants.js';
-const appendToMethod = (target, key, handler) => {
-    // Gets the previous function
-    const previous = target[key];
-    // Creates new function
-    function next(...parameters) {
-        // Calls the previous
-        const result = previous?.bind(this)(...parameters);
-        // Calls the appended
-        handler.bind(this)(...parameters);
-        // Returns the result
-        return result;
-    }
-    // Replaces the next with the previous one
-    target[key] = next;
-};
+import { kebabCase, pascalCase } from 'change-case';
+import { API_HOST, STATIC_TAG, API_STACKS, API_REQUEST, API_CONNECTED, LIFECYCLE_UPDATE, STATIC_STYLE, API_STYLE, LIFECYCLE_UPDATED, API_RENDER_COMPLETED, METHOD_RENDER, TYPE_BOOLEAN, TYPE_NUMBER, TYPE_NULL, TYPE_DATE, TYPE_ARRAY, TYPE_OBJECT, TYPE_UNDEFINED, LIFECYCLE_CONNECTED, LIFECYCLE_DISCONNECTED, KEY, LIFECYCLE_PREPARE, LIFECYCLE_CONSTRUCTED, LIFECYCLE_ADOPTED, LIFECYCLE_READY } from './constants.js';
 /**
  * Indicates the host of the element.
@@ -87,11 +71,12 @@ const toEvent = (input) => {
 const updateAttribute = (target, key, value) => {
     const element = host(target);
-    const name = kebabCase(key);
     if ([undefined, null, false].includes(value)) {
-        return element.removeAttribute(name);
+        element.removeAttribute(key);
+    }
+    else {
+        element.setAttribute(key, value === true ? '' : value);
     }
-    element.setAttribute(name, value === true ? '' : value);
 };
 const symbol = Symbol();
@@ -118,13 +103,13 @@ const attributes$2 = (target, attributes) => {
         if (isEvent(key))
             on(element, toEvent(key), next[key]);
         else
-            updateAttribute(element, key, next[key]);
+            updateAttribute(element, kebabCase(key), next[key]);
     }
     element[symbol] = { ...next };
 };
-const call = (target, key, ...parameters) => {
-    return target[key]?.call(target, ...parameters);
+const call = (target, key, ...args) => {
+    return target[key]?.apply(target, args);
 };
 const typeOf = (input) => {
@@ -1091,7 +1076,7 @@ tag('svg');
  * @param previous The previous value of Property/State.
  * @param callback Invoked when the rendering phase is completed.
  */
-const request = (target, name, previous, callback) => {
+const requestUpdate = (target, name, previous, callback) => {
     // Creates/Gets a stacks.
     const stacks = (target[API_STACKS] ||= new Map());
     // Creates/Updates a stack.
@@ -1204,11 +1189,27 @@ const styles$1 = (input) => {
         .join('; ');
 };
-function toDecorator(util, ...parameters) {
+const toCSSColor = (input) => {
+    return isCSSColor(input) ? input : undefined;
+};
+const toCSSUnit = (input) => {
+    if (input == null || input === '') {
+        return;
+    }
+    if (typeof input === 'number' || !isNaN(Number(input))) {
+        return `${input}px`;
+    }
+    if (/^\d+(\.\d+)?(px|pt|cm|mm|in|em|rem|%|vw|vh)$/.test(input)) {
+        return input;
+    }
+};
+function toDecorator(util, ...args) {
     return function (target, key) {
         defineProperty(target, key, {
             get() {
-                return util(this, ...parameters);
+                return util(this, ...args);
             }
         });
     };
@@ -1279,22 +1280,49 @@ const toUnit = (input, unit = 'px') => {
     return Number(input) + unit;
 };
+const wrapMethod = (mode, target, key, handler) => {
+    // Gets the original function
+    const original = target[key];
+    // Validate target property
+    if (original && typeof original !== 'function') {
+        throw new TypeError(`Property ${String(key)} is not a function`);
+    }
+    // Creates new function
+    function wrapped(...args) {
+        // Calls the handler before the original
+        if (mode == 'before') {
+            handler.apply(this, args);
+        }
+        // Calls the original
+        const result = original?.apply(this, args);
+        // Calls the handler after the original
+        if (mode == 'after') {
+            handler.apply(this, args);
+        }
+        // Returns the result
+        return result;
+    }
+    // Replaces the wrapped with the original one
+    target[key] = wrapped;
+};
 /**
  * Used to bind a method of a class to the current context,
  * making it easier to reference `this` within the method.
  */
 function Bind() {
     return function (target, key, descriptor) {
+        const original = descriptor.value;
         return {
             configurable: true,
             get() {
-                const value = descriptor?.value.bind(this);
+                const next = original.bind(this);
                 defineProperty(this, key, {
-                    value,
+                    value: next,
                     configurable: true,
                     writable: true
                 });
-                return value;
+                return next;
             }
         };
     };
@@ -1318,7 +1346,7 @@ function Provider(namespace) {
             dispatch(instance, `${prefix}:${instance[SUB]}:update`, options);
         };
         // TODO
-        appendToMethod(target, LIFECYCLE_CONNECTED, function () {
+        wrapMethod('after', target, LIFECYCLE_CONNECTED, function () {
             const cleanup = () => {
                 off(this, `${prefix}:presence`, onPresence);
                 cleanups(this).delete(prefix);
@@ -1330,7 +1358,7 @@ function Provider(namespace) {
             on(this, `${prefix}:presence`, onPresence);
             cleanups(this).set(prefix, cleanup);
         });
-        appendToMethod(target, LIFECYCLE_UPDATE, function (states) {
+        wrapMethod('after', target, LIFECYCLE_UPDATE, function (states) {
             update(this);
             if (cleanups(this).size && !states.has(SUB))
                 return;
@@ -1347,7 +1375,7 @@ function Provider(namespace) {
             on(window, `${type}:presence`, onPresence);
             cleanups(this).set(type, cleanup);
         });
-        appendToMethod(target, LIFECYCLE_DISCONNECTED, function () {
+        wrapMethod('after', target, LIFECYCLE_DISCONNECTED, function () {
             cleanups(this).forEach((cleanup) => cleanup());
         });
     };
@@ -1364,7 +1392,7 @@ function Consumer(namespace) {
             instance[key] = state;
         };
         // TODO
-        appendToMethod(target, LIFECYCLE_CONNECTED, function () {
+        wrapMethod('after', target, LIFECYCLE_CONNECTED, function () {
             // TODO
             if (SUB && this[SUB])
                 return;
@@ -1392,7 +1420,7 @@ function Consumer(namespace) {
             // TODO: When the `Provider` element is activated after the `Consumer` element.
             !connected && setTimeout(() => dispatch(this, `${prefix}:presence`, options));
         });
-        appendToMethod(target, LIFECYCLE_UPDATE, function (states) {
+        wrapMethod('after', target, LIFECYCLE_UPDATE, function (states) {
             if (cleanups(this).size && !states.has(SUB))
                 return;
             cleanups(this).get(`${prefix}:${states.get(SUB)}`)?.();
@@ -1414,12 +1442,41 @@ function Consumer(namespace) {
             cleanups(this).set(type, cleanup);
             dispatch(window, `${type}:presence`);
         });
-        appendToMethod(target, LIFECYCLE_DISCONNECTED, function () {
+        wrapMethod('after', target, LIFECYCLE_DISCONNECTED, function () {
             cleanups(this).forEach((cleanup) => cleanup());
         });
     };
 }
+/**
+ * A method decorator that applies debounce behavior to a class method.
+ * Ensures that the method executes only after the specified delay,
+ * resetting the timer if called again within the delay period.
+ *
+ * @param {number} delay - The debounce delay in milliseconds.
+ */
+function Debounce(delay = 0) {
+    return function (target, key, descriptor) {
+        const KEY = Symbol();
+        const original = descriptor.value;
+        function clear() {
+            if (!Object.hasOwn(this, KEY))
+                return;
+            clearTimeout(this[KEY]);
+            delete this[KEY];
+        }
+        function debounced(...args) {
+            clear.call(this);
+            this[KEY] = window.setTimeout(() => {
+                clear.call(this);
+                original.apply(this, args);
+            }, delay);
+        }
+        descriptor.value = debounced;
+        return Bind()(target, key, descriptor);
+    };
+}
 /**
  * Indicates whether the [Direction](https://mdn.io/css-direction)
  * of the element is `Right-To-Left` or `Left-To-Right`.
@@ -1445,6 +1502,7 @@ function Element() {
 }
 const proxy = (constructor) => {
     return class Plus extends HTMLElement {
+        #instance;
         static formAssociated = constructor['formAssociated'];
         static observedAttributes = constructor['observedAttributes'];
         constructor() {
@@ -1454,39 +1512,39 @@ const proxy = (constructor) => {
                 delegatesFocus: constructor['delegatesFocus'],
                 slotAssignment: constructor['slotAssignment']
             });
-            const instance = (this[API_INSTANCE] = new constructor());
-            instance[API_HOST] = () => this;
-            call(instance, LIFECYCLE_CONSTRUCTED);
+            this.#instance = new constructor();
+            this.#instance[API_HOST] = () => this;
+            call(this.#instance, LIFECYCLE_CONSTRUCTED);
         }
         adoptedCallback() {
-            call(this[API_INSTANCE], LIFECYCLE_ADOPTED);
+            call(this.#instance, LIFECYCLE_ADOPTED);
         }
         attributeChangedCallback(key, prev, next) {
-            // Ensures the integrity of readonly properties to prevent potential errors.
-            try {
-                const attribute = constructor[MAPPER]?.[key];
-                const property = attribute || camelCase(key);
-                this[property] = next;
+            if (prev != next) {
+                this.#instance['RAW:' + key] = next;
             }
-            catch { }
         }
         connectedCallback() {
-            const instance = this[API_INSTANCE];
             // TODO: experimental for global config
-            Object.assign(instance, getConfig('element', getTag(instance), 'property'));
-            instance[API_CONNECTED] = true;
+            Object.assign(this.#instance, getConfig('element', getTag(this.#instance), 'property'));
             const connect = () => {
-                request(instance, undefined, undefined, () => {
-                    call(instance, LIFECYCLE_LOADED);
+                this.#instance[API_CONNECTED] = true;
+                call(this.#instance, LIFECYCLE_CONNECTED);
+                requestUpdate(this.#instance, undefined, undefined, () => {
+                    call(this.#instance, LIFECYCLE_READY);
                 });
             };
-            const callback = call(instance, LIFECYCLE_CONNECTED);
-            if (!callback?.then)
+            const hasPrepare = LIFECYCLE_PREPARE in this.#instance;
+            if (!hasPrepare)
                 return connect();
-            callback.then(() => connect());
+            call(this.#instance, LIFECYCLE_PREPARE)
+                .then(() => connect())
+                .catch((error) => {
+                throw new Error(`Failed to prepare <${getTag(this.#instance)}> element before connection.`, { cause: error });
+            });
         }
         disconnectedCallback() {
-            call(this[API_INSTANCE], LIFECYCLE_DISCONNECTED);
+            call(this.#instance, LIFECYCLE_DISCONNECTED);
         }
     };
 };
@@ -1499,47 +1557,43 @@ const proxy = (constructor) => {
  */
 function Event(options = {}) {
     return function (target, key) {
-        defineProperty(target, key, {
-            get() {
-                return (detail) => {
-                    const element = host(this);
-                    const framework = getFramework(this);
-                    options.bubbles ??= false;
-                    let type = String(key);
-                    switch (framework) {
-                        // TODO: Experimental
-                        case 'blazor':
-                            options.bubbles = true;
-                            type = pascalCase(type);
-                            try {
-                                window['Blazor'].registerCustomEventType(type, {
-                                    createEventArgs: (event) => ({
-                                        detail: event.detail
-                                    })
-                                });
-                            }
-                            catch { }
-                            break;
-                        case 'qwik':
-                        case 'solid':
-                            type = pascalCase(type).toLowerCase();
-                            break;
-                        case 'react':
-                        case 'preact':
-                            type = pascalCase(type);
-                            break;
-                        default:
-                            type = kebabCase(type);
-                            break;
+        target[key] = function (detail) {
+            const element = host(this);
+            const framework = getFramework(this);
+            options.bubbles ??= false;
+            let type = String(key);
+            switch (framework) {
+                // TODO: Experimental
+                case 'blazor':
+                    options.bubbles = true;
+                    type = pascalCase(type);
+                    try {
+                        window['Blazor'].registerCustomEventType(type, {
+                            createEventArgs: (event) => ({
+                                detail: event.detail
+                            })
+                        });
                     }
-                    let event;
-                    event ||= getConfig('event', 'resolver')?.({ detail, element, framework, options, type });
-                    event && element.dispatchEvent(event);
-                    event ||= dispatch(this, type, { ...options, detail });
-                    return event;
-                };
+                    catch { }
+                    break;
+                case 'qwik':
+                case 'solid':
+                    type = pascalCase(type).toLowerCase();
+                    break;
+                case 'react':
+                case 'preact':
+                    type = pascalCase(type);
+                    break;
+                default:
+                    type = kebabCase(type);
+                    break;
             }
-        });
+            let event;
+            event ||= getConfig('event', 'resolver')?.({ detail, element, framework, options, type });
+            event && element.dispatchEvent(event);
+            event ||= dispatch(this, type, { ...options, detail });
+            return event;
+        };
     };
 }
@@ -1582,10 +1636,10 @@ function Listen(type, options) {
                     return instance;
             }
         };
-        appendToMethod(target, LIFECYCLE_CONNECTED, function () {
+        wrapMethod('before', target, LIFECYCLE_CONNECTED, function () {
             on(element(this), type, this[key], options);
         });
-        appendToMethod(target, LIFECYCLE_DISCONNECTED, function () {
+        wrapMethod('before', target, LIFECYCLE_DISCONNECTED, function () {
             off(element(this), type, this[key], options);
         });
         return Bind()(target, key, descriptor);
@@ -1597,11 +1651,9 @@ function Listen(type, options) {
  * and invoke it as needed, both internally and externally.
  */
 function Method() {
-    return function (target, key) {
-        appendToMethod(target, LIFECYCLE_CONSTRUCTED, function () {
-            defineProperty(host(this), key, {
-                get: () => this[key].bind(this)
-            });
+    return function (target, key, descriptor) {
+        wrapMethod('before', target, LIFECYCLE_CONSTRUCTED, function () {
+            host(this)[key] = this[key].bind(this);
         });
     };
 }
@@ -1612,89 +1664,110 @@ function Method() {
  */
 function Property(options) {
     return function (target, key, descriptor) {
-        // Creates a unique symbol for the lock flag.
-        const locked = Symbol();
-        // Converts property name to string.
-        const name = String(key);
-        // Calculates attribute.
-        const attribute = options?.attribute || kebabCase(name);
-        // Registers an attribute that is intricately linked to the property.
+        // Unique symbol for property storage to avoid naming conflicts
+        const KEY = Symbol();
+        // Unique symbol for the lock flag to prevent infinite loops during updates
+        const LOCKED = Symbol();
+        // Calculate attribute name from the property key if not explicitly provided
+        const attribute = options?.attribute || kebabCase(key);
+        // Store the original setter (if it exists) to preserve its behavior
+        const originalSetter = descriptor?.set;
+        // Register the attribute in the observedAttributes array for the element
         (target.constructor['observedAttributes'] ||= []).push(attribute);
-        // TODO
-        if (attribute) {
-            // TODO
-            target.constructor[MAPPER] ||= {};
-            // TODO
-            target.constructor[MAPPER][attribute] = name;
+        // Getter function to retrieve the property value
+        function get() {
+            return this[KEY];
         }
-        // TODO: This feature is an experimental
-        // When the property is a getter function.
-        if (descriptor) {
-            // Checks the reflection.
-            if (options?.reflect) {
-                // Stores the original getter function.
-                const getter = descriptor.get;
-                // Defines a new getter function.
-                descriptor.get = function () {
-                    const value = getter?.apply(this);
-                    this[locked] = true;
-                    updateAttribute(this, attribute, value);
-                    this[locked] = false;
-                    return value;
-                };
-                // TODO: Check the lifecycle
-                appendToMethod(target, LIFECYCLE_UPDATED, function () {
-                    // Calls the getter function to update the related attribute.
-                    this[key];
-                });
+        // Setter function to update the property value and trigger updates
+        function set(value) {
+            // Store the previous value
+            const previous = this[KEY];
+            // Store the new value
+            const next = value;
+            // Skip updates if the value hasn't changed and no custom setter is defined
+            if (!originalSetter && next === previous)
+                return;
+            // If a custom setter exists, call it with the new value
+            if (originalSetter) {
+                originalSetter.call(this, next);
             }
-        }
-        // When the property is normal.
-        else {
-            // Creates a unique symbol.
-            const symbol = Symbol();
-            // Defines a getter function to use in the target class.
-            function get() {
-                return this[symbol];
+            // Otherwise, update the property directly
+            else {
+                this[KEY] = next;
             }
-            // Defines a setter function to use in the target class.
-            function set(next) {
-                const previous = this[symbol];
-                if (next === previous)
+            // Request an update
+            requestUpdate(this, key, previous, (skipped) => {
+                // Skip if the update was aborted
+                if (skipped)
                     return;
-                this[symbol] = next;
-                request(this, name, previous, (skipped) => {
-                    if (skipped)
-                        return;
-                    if (!options?.reflect)
-                        return;
-                    this[locked] = true;
-                    updateAttribute(this, attribute, next);
-                    this[locked] = false;
-                });
-            }
-            // Attaches the getter and setter functions to the current property of the target class.
-            defineProperty(target, key, { get, set });
+                // If reflection is enabled, update the corresponding attribute
+                if (!options?.reflect)
+                    return;
+                // Lock to prevent infinite loops
+                this[LOCKED] = true;
+                // Update the attribute
+                updateAttribute(this, attribute, next);
+                // Unlock
+                this[LOCKED] = false;
+            });
+        }
+        // Override the property descriptor if a custom setter exists
+        if (originalSetter) {
+            descriptor.set = set;
+        }
+        // Attach the getter and setter to the target class property if no descriptor exists
+        if (!descriptor) {
+            defineProperty(target, key, { configurable: true, get, set });
         }
-        // TODO: Check the lifecycle
-        appendToMethod(target, LIFECYCLE_CONSTRUCTED, function () {
-            // Defines a getter function to use in the host element.
+        /**
+         * Define a raw property setter to handle updates that trigger from the `attributeChangedCallback`,
+         * To intercept and process raw attribute values before they are assigned to the property
+         */
+        defineProperty(target, 'RAW:' + attribute, {
+            set(value) {
+                if (!this[LOCKED]) {
+                    // Convert the raw value and set it to the corresponding property
+                    this[key] = toProperty(value, options?.type);
+                }
+            }
+        });
+        // Attach getter and setter to the host element on construction
+        wrapMethod('before', target, LIFECYCLE_CONSTRUCTED, function () {
             const get = () => {
+                if (descriptor && !descriptor.get) {
+                    throw new Error(`Property '${key}' does not have a getter. Unable to retrieve value.`);
+                }
                 return this[key];
             };
-            // Defines a setter function to use in the host element.
-            const set = descriptor
-                ? undefined
-                : (input) => {
-                    if (this[locked]) {
-                        return;
-                    }
-                    this[key] = toProperty(input, options?.type);
-                };
-            // TODO: Check the configuration.
-            // Attaches the getter and setter functions to the current property of the host element.
-            defineProperty(host(this), key, { get, set, configurable: true });
+            const set = (value) => {
+                if (descriptor && !descriptor.set) {
+                    throw new Error(`Property '${key}' does not have a setter. Unable to assign value.`);
+                }
+                this[key] = value;
+            };
+            defineProperty(host(this), key, { configurable: true, get, set });
         });
+        /**
+         * TODO: Review these behaviors again.
+         *
+         * When a property has a reflect and either a getter, a setter, or both are available,
+         * three approaches are possible:
+         *
+         * 1. Only a getter is present: The attribute updates after each render is completed.
+         * 2. Only a setter is present: The attribute updates after each setter call.
+         * 3. Both getter and setter are present: The attribute is updated via the setter call
+         *    and also after each render is completed, resulting in two attribute update processes.
+         */
+        if (options?.reflect && descriptor?.get) {
+            wrapMethod('before', target, LIFECYCLE_UPDATED, function () {
+                // Lock to prevent infinite loops
+                this[LOCKED] = true;
+                // Update the attribute
+                updateAttribute(this, attribute, this[key]);
+                // Unlock
+                this[LOCKED] = false;
+            });
+        }
     };
 }
@@ -1738,23 +1811,87 @@ function Slots() {
  */
 function State() {
     return function (target, key) {
+        const KEY = Symbol();
         const name = String(key);
-        const symbol = Symbol();
-        function get() {
-            return this[symbol];
-        }
-        function set(next) {
-            const previous = this[symbol];
-            if (next === previous)
-                return;
-            this[symbol] = next;
-            request(this, name, previous);
-        }
-        // TODO: configurable
-        defineProperty(target, key, { get, set, configurable: true });
+        defineProperty(target, key, {
+            enumerable: true,
+            configurable: true,
+            get() {
+                return this[KEY];
+            },
+            set(next) {
+                const previous = this[KEY];
+                if (next === previous)
+                    return;
+                this[KEY] = next;
+                requestUpdate(this, name, previous);
+            }
+        });
     };
 }
+// TODO: check the logic
+function Style() {
+    return function (target, key) {
+        const LAST = Symbol();
+        const SHEET = Symbol();
+        wrapMethod('before', target, LIFECYCLE_UPDATED, function () {
+            let sheet = this[SHEET];
+            let value = this[key];
+            const update = (value) => (result) => {
+                if (value && value !== this[LAST])
+                    return;
+                sheet.replaceSync(toCssString(result));
+                this[LAST] = undefined;
+            };
+            if (!sheet) {
+                sheet = new CSSStyleSheet();
+                this[SHEET] = sheet;
+                shadowRoot(this)?.adoptedStyleSheets.push(sheet);
+            }
+            if (typeof value === 'function') {
+                value = value.call(this);
+            }
+            if (value instanceof Promise) {
+                value.then(update((this[LAST] = value))).catch((error) => {
+                    throw new Error('TODO', { cause: error });
+                });
+            }
+            else {
+                update()(value);
+            }
+        });
+    };
+}
+const toCssString = (input, parent) => {
+    if (typeof input == 'string') {
+        return input.trim();
+    }
+    if (Array.isArray(input)) {
+        return input
+            .map((item) => toCssString(item, parent))
+            .filter(Boolean)
+            .join('\n');
+    }
+    if (typeof input != 'object')
+        return '';
+    let result = '';
+    for (const key of Object.keys(input)) {
+        const value = input[key];
+        const ignore = [null, undefined, false].includes(value);
+        if (ignore)
+            continue;
+        const cssKey = key.replace(/[A-Z]/g, (match) => `-${match.toLowerCase()}`);
+        if (typeof value === 'object') {
+            result += `${cssKey} {${toCssString(value, cssKey)}}`;
+        }
+        else {
+            result += `${cssKey}: ${value};`;
+        }
+    }
+    return parent ? result : `:host {${result}}`;
+};
 /**
  * Monitors `@Property` and `@State` to detect changes.
  * The decorated method will be called after any changes,
@@ -1769,7 +1906,7 @@ function Watch(keys, immediate) {
         // Gets all keys
         const all = [keys].flat().filter((item) => item);
         // Registers a lifecycle to detect changes.
-        appendToMethod(target, LIFECYCLE_UPDATED, function (states) {
+        wrapMethod('after', target, LIFECYCLE_UPDATED, function (states) {
             // Skips the logic if 'immediate' wasn't passed.
             if (!immediate && !this[API_RENDER_COMPLETED])
                 return;
@@ -1789,4 +1926,4 @@ const attributes = attributes$2;
 const html = html$1;
 const styles = styles$1;
-export { Bind as B, Consumer as C, Direction as D, Element as E, Host as H, IsRTL as I, Listen as L, Method as M, Provider as P, Query as Q, Slots as S, Watch as W, dispatch as a, isRTL as b, classes as c, direction as d, queryAll as e, off as f, getConfig as g, host as h, isCSSColor as i, setConfig as j, Event as k, Property as l, QueryAll as m, State as n, on as o, attributes as p, query as q, html as r, slots as s, toUnit as t, styles as u };
+export { Bind as B, Consumer as C, Debounce as D, Element as E, Host as H, IsRTL as I, Listen as L, Method as M, Provider as P, Query as Q, Slots as S, Watch as W, dispatch as a, toCSSUnit as b, classes as c, direction as d, isRTL as e, queryAll as f, getConfig as g, host as h, isCSSColor as i, off as j, toUnit as k, setConfig as l, Direction as m, Event as n, on as o, Property as p, query as q, QueryAll as r, slots as s, toCSSColor as t, State as u, Style as v, attributes as w, html as x, styles as y };

package/dist/{client-5FqNUiuz.d.ts → client-JA8zqh-l.d.ts} RENAMED Viewed

@@ -13,6 +13,18 @@ interface HTMLPlusElement {
 declare function Provider(namespace: string): (target: HTMLPlusElement, key: PropertyKey, descriptor: PropertyDescriptor) => void;
 declare function Consumer(namespace: string): (target: HTMLPlusElement, key: PropertyKey) => void;
+/**
+ * A method decorator that applies debounce behavior to a class method.
+ * Ensures that the method executes only after the specified delay,
+ * resetting the timer if called again within the delay period.
+ *
+ * @param {number} delay - The debounce delay in milliseconds.
+ */
+declare function Debounce(delay?: number): (target: Object, key: PropertyKey, descriptor: PropertyDescriptor) => {
+    configurable: boolean;
+    get(): any;
+};
 /**
  * Indicates whether the [Direction](https://mdn.io/css-direction)
  * of the element is `Right-To-Left` or `Left-To-Right`.
@@ -127,7 +139,7 @@ declare function Listen(type: string, options?: ListenOptions): (target: HTMLPlu
  * Provides a way to encapsulate functionality within an element
  * and invoke it as needed, both internally and externally.
  */
-declare function Method(): (target: HTMLPlusElement, key: PropertyKey) => void;
+declare function Method(): (target: HTMLPlusElement, key: PropertyKey, descriptor: PropertyDescriptor) => void;
 /**
  * The configuration for property decorator.
@@ -152,7 +164,7 @@ interface PropertyOptions {
  * Creates a reactive property, reflecting a corresponding attribute value,
  * and updates the element when the property is set.
  */
-declare function Property(options?: PropertyOptions): (target: HTMLPlusElement, key: PropertyKey, descriptor?: PropertyDescriptor) => void;
+declare function Property(options?: PropertyOptions): (target: HTMLPlusElement, key: string, descriptor?: PropertyDescriptor) => void;
 /**
  * Selects the first element in the shadow dom that matches a specified CSS selector.
@@ -188,6 +200,8 @@ declare function Slots$1(): (target: HTMLPlusElement, key: PropertyKey) => void;
  */
 declare function State(): (target: HTMLPlusElement, key: PropertyKey) => void;
+declare function Style(): (target: HTMLPlusElement, key: PropertyKey) => void;
 /**
  * Monitors `@Property` and `@State` to detect changes.
  * The decorated method will be called after any changes,
@@ -297,6 +311,10 @@ type Slots = {
  */
 declare const slots: (target: HTMLElement | HTMLPlusElement) => Slots;
+declare const toCSSColor: (input: string) => string | undefined;
+declare const toCSSUnit: (input?: number | string | null) => string | undefined;
 /**
  * Converts a value to a unit.
  */
@@ -306,4 +324,4 @@ declare const attributes: any;
 declare const html: any;
 declare const styles: any;
-export { styles as A, Bind as B, type Config as C, Direction as D, Element$1 as E, Host as H, IsRTL as I, type ListenOptions as L, Method as M, Provider as P, Query as Q, Slots$1 as S, Watch as W, dispatch as a, isRTL as b, classes as c, direction as d, queryAll as e, off as f, getConfig as g, host as h, isCSSColor as i, setConfig as j, type ConfigOptions as k, Consumer as l, type EventEmitter as m, type EventOptions as n, on as o, Event as p, query as q, Listen as r, slots as s, toUnit as t, type PropertyOptions as u, Property as v, QueryAll as w, State as x, attributes as y, html as z };
+export { State as A, Bind as B, type Config as C, Debounce as D, Element$1 as E, Style as F, attributes as G, Host as H, IsRTL as I, html as J, styles as K, type ListenOptions as L, Method as M, Provider as P, Query as Q, Slots$1 as S, Watch as W, type ConfigOptions as a, dispatch as b, classes as c, direction as d, toCSSUnit as e, isRTL as f, getConfig as g, host as h, isCSSColor as i, queryAll as j, off as k, toUnit as l, setConfig as m, Consumer as n, on as o, Direction as p, query as q, type EventEmitter as r, slots as s, toCSSColor as t, type EventOptions as u, Event as v, Listen as w, type PropertyOptions as x, Property as y, QueryAll as z };

package/dist/client.d.ts CHANGED Viewed

	@@ -1 +1 @@
1	- export { B as Bind, C as Config, k as ConfigOptions, l as Consumer, D as Direction, E as Element, p as Event, m as EventEmitter, n as EventOptions, H as Host, I as IsRTL, r as Listen, L as ListenOptions, M as Method, v as Property, u as PropertyOptions, P as Provider, Q as Query, w as QueryAll, S as Slots, x as State, W as Watch, c as classes, d as direction, a as dispatch, g as getConfig, h as host, i as isCSSColor, b as isRTL, f as off, o as on, q as query, e as queryAll, j as setConfig, s as slots, t as toUnit } from './client-~~5FqNUiuz~~.js';
1	+ export { B as Bind, C as Config, a as ConfigOptions, n as Consumer, D as Debounce, p as Direction, E as Element, v as Event, r as EventEmitter, u as EventOptions, H as Host, I as IsRTL, w as Listen, L as ListenOptions, M as Method, y as Property, x as PropertyOptions, P as Provider, Q as Query, z as QueryAll, S as Slots, A as State, F as Style, W as Watch, c as classes, d as direction, b as dispatch, g as getConfig, h as host, i as isCSSColor, f as isRTL, k as off, o as on, q as query, j as queryAll, m as setConfig, s as slots, t as toCSSColor, e as toCSSUnit, l as toUnit } from './client-JA8zqh-l.js';

package/dist/client.js CHANGED Viewed

@@ -1,3 +1,3 @@
-export { B as Bind, C as Consumer, D as Direction, E as Element, k as Event, H as Host, I as IsRTL, L as Listen, M as Method, l as Property, P as Provider, Q as Query, m as QueryAll, S as Slots, n as State, W as Watch, c as classes, d as direction, a as dispatch, g as getConfig, h as host, i as isCSSColor, b as isRTL, f as off, o as on, q as query, e as queryAll, j as setConfig, s as slots, t as toUnit } from './client-BsD9JZY4.js';
+export { B as Bind, C as Consumer, D as Debounce, m as Direction, E as Element, n as Event, H as Host, I as IsRTL, L as Listen, M as Method, p as Property, P as Provider, Q as Query, r as QueryAll, S as Slots, u as State, v as Style, W as Watch, c as classes, d as direction, a as dispatch, g as getConfig, h as host, i as isCSSColor, e as isRTL, j as off, o as on, q as query, f as queryAll, l as setConfig, s as slots, t as toCSSColor, b as toCSSUnit, k as toUnit } from './client-DgXF8gQw.js';
 import 'change-case';
 import './constants.js';

package/dist/constants.d.ts CHANGED Viewed

@@ -1,9 +1,7 @@
 declare const KEY = "htmlplus";
 declare const PACKAGE_NAME = "@htmlplus/element";
-declare const MAPPER: unique symbol;
 declare const API_CONNECTED: unique symbol;
 declare const API_HOST: unique symbol;
-declare const API_INSTANCE: unique symbol;
 declare const API_REQUEST: unique symbol;
 declare const API_RENDER_COMPLETED: unique symbol;
 declare const API_STACKS: unique symbol;
@@ -21,7 +19,8 @@ declare const LIFECYCLE_ADOPTED = "adoptedCallback";
 declare const LIFECYCLE_CONNECTED = "connectedCallback";
 declare const LIFECYCLE_CONSTRUCTED = "constructedCallback";
 declare const LIFECYCLE_DISCONNECTED = "disconnectedCallback";
-declare const LIFECYCLE_LOADED = "loadedCallback";
+declare const LIFECYCLE_READY = "readyCallback";
+declare const LIFECYCLE_PREPARE = "prepareCallback";
 declare const LIFECYCLE_UPDATE = "updateCallback";
 declare const LIFECYCLE_UPDATED = "updatedCallback";
 declare const METHOD_RENDER = "render";
@@ -47,4 +46,4 @@ declare const UTILS_STYLES_IMPORTED = "styles";
 declare const UTILS_STYLES_LOCAL = "UTILS_STYLES";
 declare const UTILS_PATH = "@htmlplus/element/internal.js";
-export { API_CONNECTED, API_HOST, API_INSTANCE, API_RENDER_COMPLETED, API_REQUEST, API_STACKS, API_STYLE, COMMENT_AUTO_ADDED, DECORATOR_CSS_VARIABLE, DECORATOR_ELEMENT, DECORATOR_EVENT, DECORATOR_METHOD, DECORATOR_PROPERTY, DECORATOR_PROPERTY_TYPE, DECORATOR_STATE, ELEMENT_HOST_NAME, KEY, LIFECYCLE_ADOPTED, LIFECYCLE_CONNECTED, LIFECYCLE_CONSTRUCTED, LIFECYCLE_DISCONNECTED, LIFECYCLE_LOADED, LIFECYCLE_UPDATE, LIFECYCLE_UPDATED, MAPPER, METHOD_RENDER, PACKAGE_NAME, STATIC_STYLE, STATIC_TAG, STYLE_IMPORTED, TYPE_ARRAY, TYPE_BIGINT, TYPE_BOOLEAN, TYPE_DATE, TYPE_ENUM, TYPE_FUNCTION, TYPE_NULL, TYPE_NUMBER, TYPE_OBJECT, TYPE_STRING, TYPE_UNDEFINED, UTILS_ATTRIBUTES_IMPORTED, UTILS_ATTRIBUTES_LOCAL, UTILS_HTML_IMPORTED, UTILS_HTML_LOCAL, UTILS_PATH, UTILS_STYLES_IMPORTED, UTILS_STYLES_LOCAL };
+export { API_CONNECTED, API_HOST, API_RENDER_COMPLETED, API_REQUEST, API_STACKS, API_STYLE, COMMENT_AUTO_ADDED, DECORATOR_CSS_VARIABLE, DECORATOR_ELEMENT, DECORATOR_EVENT, DECORATOR_METHOD, DECORATOR_PROPERTY, DECORATOR_PROPERTY_TYPE, DECORATOR_STATE, ELEMENT_HOST_NAME, KEY, LIFECYCLE_ADOPTED, LIFECYCLE_CONNECTED, LIFECYCLE_CONSTRUCTED, LIFECYCLE_DISCONNECTED, LIFECYCLE_PREPARE, LIFECYCLE_READY, LIFECYCLE_UPDATE, LIFECYCLE_UPDATED, METHOD_RENDER, PACKAGE_NAME, STATIC_STYLE, STATIC_TAG, STYLE_IMPORTED, TYPE_ARRAY, TYPE_BIGINT, TYPE_BOOLEAN, TYPE_DATE, TYPE_ENUM, TYPE_FUNCTION, TYPE_NULL, TYPE_NUMBER, TYPE_OBJECT, TYPE_STRING, TYPE_UNDEFINED, UTILS_ATTRIBUTES_IMPORTED, UTILS_ATTRIBUTES_LOCAL, UTILS_HTML_IMPORTED, UTILS_HTML_LOCAL, UTILS_PATH, UTILS_STYLES_IMPORTED, UTILS_STYLES_LOCAL };

package/dist/constants.js CHANGED Viewed

@@ -1,11 +1,8 @@
 const KEY = 'htmlplus';
 const PACKAGE_NAME = '@htmlplus/element';
-// TODO
-const MAPPER = Symbol();
 // APIs
 const API_CONNECTED = Symbol();
 const API_HOST = Symbol();
-const API_INSTANCE = Symbol();
 const API_REQUEST = Symbol();
 const API_RENDER_COMPLETED = Symbol();
 const API_STACKS = Symbol();
@@ -28,7 +25,8 @@ const LIFECYCLE_ADOPTED = 'adoptedCallback';
 const LIFECYCLE_CONNECTED = 'connectedCallback';
 const LIFECYCLE_CONSTRUCTED = 'constructedCallback';
 const LIFECYCLE_DISCONNECTED = 'disconnectedCallback';
-const LIFECYCLE_LOADED = 'loadedCallback';
+const LIFECYCLE_READY = 'readyCallback';
+const LIFECYCLE_PREPARE = 'prepareCallback';
 const LIFECYCLE_UPDATE = 'updateCallback';
 const LIFECYCLE_UPDATED = 'updatedCallback';
 // methods
@@ -59,4 +57,4 @@ const UTILS_STYLES_IMPORTED = 'styles';
 const UTILS_STYLES_LOCAL = 'UTILS_STYLES';
 const UTILS_PATH = '@htmlplus/element/internal.js';
-export { API_CONNECTED, API_HOST, API_INSTANCE, API_RENDER_COMPLETED, API_REQUEST, API_STACKS, API_STYLE, COMMENT_AUTO_ADDED, DECORATOR_CSS_VARIABLE, DECORATOR_ELEMENT, DECORATOR_EVENT, DECORATOR_METHOD, DECORATOR_PROPERTY, DECORATOR_PROPERTY_TYPE, DECORATOR_STATE, ELEMENT_HOST_NAME, KEY, LIFECYCLE_ADOPTED, LIFECYCLE_CONNECTED, LIFECYCLE_CONSTRUCTED, LIFECYCLE_DISCONNECTED, LIFECYCLE_LOADED, LIFECYCLE_UPDATE, LIFECYCLE_UPDATED, MAPPER, METHOD_RENDER, PACKAGE_NAME, STATIC_STYLE, STATIC_TAG, STYLE_IMPORTED, TYPE_ARRAY, TYPE_BIGINT, TYPE_BOOLEAN, TYPE_DATE, TYPE_ENUM, TYPE_FUNCTION, TYPE_NULL, TYPE_NUMBER, TYPE_OBJECT, TYPE_STRING, TYPE_UNDEFINED, UTILS_ATTRIBUTES_IMPORTED, UTILS_ATTRIBUTES_LOCAL, UTILS_HTML_IMPORTED, UTILS_HTML_LOCAL, UTILS_PATH, UTILS_STYLES_IMPORTED, UTILS_STYLES_LOCAL };
+export { API_CONNECTED, API_HOST, API_RENDER_COMPLETED, API_REQUEST, API_STACKS, API_STYLE, COMMENT_AUTO_ADDED, DECORATOR_CSS_VARIABLE, DECORATOR_ELEMENT, DECORATOR_EVENT, DECORATOR_METHOD, DECORATOR_PROPERTY, DECORATOR_PROPERTY_TYPE, DECORATOR_STATE, ELEMENT_HOST_NAME, KEY, LIFECYCLE_ADOPTED, LIFECYCLE_CONNECTED, LIFECYCLE_CONSTRUCTED, LIFECYCLE_DISCONNECTED, LIFECYCLE_PREPARE, LIFECYCLE_READY, LIFECYCLE_UPDATE, LIFECYCLE_UPDATED, METHOD_RENDER, PACKAGE_NAME, STATIC_STYLE, STATIC_TAG, STYLE_IMPORTED, TYPE_ARRAY, TYPE_BIGINT, TYPE_BOOLEAN, TYPE_DATE, TYPE_ENUM, TYPE_FUNCTION, TYPE_NULL, TYPE_NUMBER, TYPE_OBJECT, TYPE_STRING, TYPE_UNDEFINED, UTILS_ATTRIBUTES_IMPORTED, UTILS_ATTRIBUTES_LOCAL, UTILS_HTML_IMPORTED, UTILS_HTML_LOCAL, UTILS_PATH, UTILS_STYLES_IMPORTED, UTILS_STYLES_LOCAL };

package/dist/internal.d.ts CHANGED Viewed

	@@ -1 +1 @@
1	- export { y as attributes, z as html, A as styles } from './client-~~5FqNUiuz~~.js';
1	+ export { G as attributes, J as html, K as styles } from './client-JA8zqh-l.js';

package/dist/internal.js CHANGED Viewed

@@ -1,3 +1,3 @@
-export { p as attributes, r as html, u as styles } from './client-BsD9JZY4.js';
+export { w as attributes, x as html, y as styles } from './client-DgXF8gQw.js';
 import 'change-case';
 import './constants.js';

package/dist/jsx-runtime.d.ts CHANGED Viewed

@@ -1,6 +1,8 @@
 import 'react';
-type WithPart<K extends keyof React.JSX.IntrinsicElements> = React.JSX.IntrinsicElements[K] & { part?: string };
+type WithPart<K extends keyof React.JSX.IntrinsicElements> = React.JSX.IntrinsicElements[K] & {
+  part?: string;
+};
 declare namespace JSX {
   interface IntrinsicElements {

package/dist/transformer.js CHANGED Viewed

@@ -461,6 +461,10 @@ const customElement = (options) => {
                     name.name = '.' + name.name;
                     return;
                 }
+                if (name.name == 'disabled') {
+                    name.name = '.' + name.name;
+                    return;
+                }
                 const key = ['tabIndex', 'viewBox'];
                 if (!key.includes(name.name))
                     return;
@@ -512,9 +516,7 @@ const customElement = (options) => {
                                 return attribute.type == 'JSXSpreadAttribute';
                             });
                             if (hasSpreadAttribute) {
-                                parts.push(' ', 'ref=', t.arrowFunctionExpression([
-                                    t.identifier('$element')
-                                ], TODO(t.identifier('$element'), attributes)));
+                                parts.push(' ', 'ref=', t.arrowFunctionExpression([t.identifier('$element')], TODO(t.identifier('$element'), attributes)));
                             }
                             else {
                                 for (const attribute of attributes) {

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@htmlplus/element",
-  "version": "3.1.4",
+  "version": "3.2.1",
   "license": "MIT",
   "sideEffects": false,
   "author": "Masood Abdolian <m.abdolian@gmail.com>",