p-elements-core 1.2.32-rc2 → 1.2.32-rc4

package/src/decorators/property.ts

@@ -1,684 +1,789 @@
-/**
- * Supported property type constructors for reactive properties.
- * These constructors are used to convert attribute values to the correct JavaScript type.
- *
- * @typedef {StringConstructor | NumberConstructor | BooleanConstructor | ObjectConstructor | ArrayConstructor} PropertyType
- */
-type PropertyType =
-  | StringConstructor
-  | NumberConstructor
-  | BooleanConstructor
-  | ObjectConstructor
-  | ArrayConstructor;
-
-/**
- * Legacy string-based property types (deprecated).
- * Maintained for backward compatibility. Use PropertyType constructors instead.
- *
- * @typedef {('string' | 'number' | 'boolean' | 'object' | 'array')} oldPropertyType
- * @deprecated Use PropertyType constructors (String, Number, Boolean, Object, Array) instead
- */
-type oldPropertyType = "string" | "number" | "boolean" | "object" | "array";
-
-/**
- * Configuration options for the @property decorator.
- * Defines how a property should sync with HTML attributes and trigger updates.
- *
- * @interface PropertyOptions
- *
- * @example
- * ```typescript
- * @property({ type: String, reflect: true })
- * name = 'default';
- *
- * @property({ type: Number, attribute: 'data-count' })
- * count = 0;
- *
- * @property({ type: Boolean })
- * active = false;
- * ```
- */
-export interface PropertyOptions {
-  /**
-   * The type constructor for converting attribute values to property values.
-   * Use String, Number, Boolean, Object, or Array.
-   * @type {PropertyType | oldPropertyType}
-   */
-  type?: PropertyType | oldPropertyType;
-
-  /**
-   * The HTML attribute name to sync with, or false to disable attribute syncing.
-   * - `true` (default): Use kebab-case version of property name
-   * - `string`: Use specific attribute name
-   * - `false`: No attribute syncing
-   * @type {string | boolean}
-   */
-  attribute?: string | boolean;
-
-  /**
-   * Whether to reflect property changes back to the HTML attribute.
-   * When true, setting the property will update the attribute.
-   * @type {boolean}
-   * @default false
-   */
-  reflect?: boolean;
-
-  readonly?: boolean;
-
-  /**
-   * Custom converter for complex attribute/property transformations.
-   * @type {AttributeConverter<any>}
-   */
-  converter?: AttributeConverter<any>;
-}
-
-/**
- * PropertyOptions extended with the property name.
- * Used internally to track registered properties.
- *
- * @typedef {PropertyOptions & { name: string }} PropertyOptionsWithName
- */
-export type PropertyOptionsWithName = PropertyOptions & {name: string};
-
-/**
- * Track which elements are currently updating attributes from property setters.
- * Prevents infinite loops when reflection is enabled (property → attribute → property).
- *
- * @type {WeakSet<HTMLElement>}
- * @private
- */
-const settingAttributes = new WeakSet<HTMLElement>();
-
-/**
- * Queue of pending attribute reflections for elements not yet connected to the DOM.
- * Attribute reflections are deferred until the element is connected.
- *
- * @type {WeakMap<HTMLElement, Map<string, {value: any, type: any, converter?: AttributeConverter<any>}>>}
- * @private
- */
-const pendingAttributeReflections = new WeakMap<
-  HTMLElement,
-  Map<string, {value: any; type: any; converter?: AttributeConverter<any>}>
->();
-
-/**
- * Queue of pending update callbacks for elements not yet connected to the DOM.
- * Updates are deferred until the element is connected to avoid calling lifecycle
- * methods on unattached elements.
- *
- * @type {WeakMap<HTMLElement, Array<{propertyKey: string, oldValue: any, newValue: any}>>}
- * @private
- */
-const pendingUpdates = new WeakMap<
-  HTMLElement,
-  Array<{propertyKey: string; oldValue: any; newValue: any}>
->();
-
-/**
- * Checks if an element is currently updating its attributes from property setters.
- * Used to prevent circular updates during property reflection.
- *
- * @param {HTMLElement} element - The element to check
- * @returns {boolean} True if the element is currently setting attributes
- *
- * @example
- * ```typescript
- * if (!isSettingAttribute(this)) {
- *   // Safe to update property from attribute
- * }
- * ```
- */
-export function isSettingAttribute(element: HTMLElement): boolean {
-  return settingAttributes.has(element);
-}
-
-/**
- * Process any pending update callbacks for an element.
- * Should be called when the element connects to the DOM to trigger
- * deferred lifecycle callbacks.
- *
- * @param {any} element - The element with pending updates
- * @returns {void}
- *
- * @example
- * ```typescript
- * connectedCallback() {
- *   processPendingUpdates(this);
- * }
- * ```
- */
-export function processPendingUpdates(element: any): void {
-  // Process pending attribute reflections first
-  const pendingReflections = pendingAttributeReflections.get(element);
-  if (pendingReflections) {
-    settingAttributes.add(element);
-    try {
-      pendingReflections.forEach((reflection, attributeName) => {
-        updateAttribute(
-          element,
-          attributeName,
-          reflection.value,
-          reflection.type,
-          reflection.converter,
-        );
-      });
-    } finally {
-      settingAttributes.delete(element);
-    }
-    pendingAttributeReflections.delete(element);
-  }
-
-  // Process pending updated callbacks
-  const pending = pendingUpdates.get(element);
-  if (pending && element.updated) {
-    const pendingLength = pending.length;
-    let i = 0;
-    while (i < pendingLength) {
-      const update = pending[i];
-      element.updated(update.propertyKey, update.oldValue, update.newValue);
-      i = i + 1;
-    }
-    pendingUpdates.delete(element);
-  }
-}
-
-/**
- * Interface for custom attribute conversion functions.
- *
- * @interface AttributeConverter
- * @template T The type of the property value
- * @description Provides custom conversion logic between HTML attribute strings
- * and JavaScript property values for complex data types or custom formatting.
- */
-export interface AttributeConverter<T> {
-  /**
-   * Converts an HTML attribute string value to a JavaScript property value.
-   *
-   * @param {string | null} value - The attribute value to convert
-   * @returns {T} The converted JavaScript value
-   * @optional
-   *
-   * @example
-   * ```typescript
-   * fromAttribute: (value: string | null) => {
-   *   return value ? JSON.parse(value) : null;
-   * }
-   * ```
-   */
-  fromAttribute?(value: string | null): T;
-
-  /**
-   * Converts a JavaScript property value to an HTML attribute string.
-   *
-   * @param {T} value - The JavaScript value to convert
-   * @returns {string} The converted attribute string
-   * @optional
-   *
-   * @example
-   * ```typescript
-   * toAttribute: (value: object) => {
-   *   return JSON.stringify(value);
-   * }
-   * ```
-   */
-  toAttribute?(value: T): string;
-}
-
-/**
- * Converts legacy string-based type to PropertyType constructor.
- * Provides backward compatibility for old string type declarations.
- *
- * @param {PropertyType | oldPropertyType | undefined} type - The type to normalize
- * @returns {PropertyType} The normalized PropertyType constructor (defaults to String)
- * @private
- *
- * @example
- * ```typescript
- * normalizeType('string') // Returns String constructor
- * normalizeType(Number) // Returns Number constructor
- * ```
- */
-function normalizeType(
-  type: PropertyType | oldPropertyType | undefined,
-): PropertyType {
-  if (typeof type === "string") {
-    switch (type) {
-      case "string":
-        return String;
-      case "number":
-        return Number;
-      case "boolean":
-        return Boolean;
-      case "object":
-        return Object;
-      case "array":
-        return Array;
-      default:
-        return null;
-    }
-  }
-  return type;
-}
-
-/**
- * Converts a property value to the specified type.
- * Uses custom converter if provided, otherwise performs standard type conversion.
- *
- * @param {any} value - The value to convert
- * @param {PropertyType} [type] - The target type constructor
- * @param {AttributeConverter<any>} [converter] - Optional custom converter
- * @returns {any} The converted value
- * @private
- *
- * @example
- * ```typescript
- * convertPropertyValue('42', Number) // Returns 42
- * convertPropertyValue('true', Boolean) // Returns true
- * convertPropertyValue('{"a":1}', Object) // Returns {a: 1}
- * ```
- */
-function convertPropertyValue(
-  value: any,
-  type?: PropertyType,
-  converter?: AttributeConverter<any>,
-): any {
-  // Use custom converter if provided
-  if (converter && converter.fromAttribute && typeof value === "string") {
-    return converter.fromAttribute(value);
-  }
-
-  // Preserve null/undefined
-  if (value === null || value === undefined) {
-    return value;
-  }
-
-  // Standard type conversion
-  switch (type) {
-    case String:
-      return String(value);
-    case Number:
-      return Number(value);
-    case Boolean:
-      return Boolean(value);
-    case Object:
-      return typeof value === "object" ? value : JSON.parse(String(value));
-    case Array:
-      return Array.isArray(value) ? value : JSON.parse(String(value));
-    default:
-      return value;
-  }
-}
-
-/**
- * Converts a camelCase string to kebab-case.
- * Used to derive HTML attribute names from JavaScript property names.
- *
- * @param {string} str - The camelCase string to convert
- * @returns {string} The kebab-case string
- * @private
- *
- * @example
- * ```typescript
- * camelToKebabCase('myProperty') // Returns 'my-property'
- * camelToKebabCase('isActive') // Returns 'is-active'
- * ```
- */
-function camelToKebabCase(str: string): string {
-  return str.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase();
-}
-
-/**
- * Calculates the HTML attribute name based on property options.
- *
- * @param {string} propertyKey - The JavaScript property name
- * @param {string | boolean | undefined} attribute - The attribute option from PropertyOptions
- * @returns {string | undefined} The attribute name, or undefined if attribute syncing is disabled
- * @private
- *
- * @example
- * ```typescript
- * getAttributeName('myProp', true) // Returns 'my-prop'
- * getAttributeName('myProp', 'data-value') // Returns 'data-value'
- * getAttributeName('myProp', false) // Returns undefined
- * ```
- */
-function getAttributeName(
-  propertyKey: string,
-  attribute: string | boolean | undefined,
-): string | undefined {
-  if (attribute === false) return undefined;
-  if (attribute === true) return camelToKebabCase(propertyKey);
-  if (typeof attribute === "string") return attribute;
-  return undefined;
-}
-
-/**
- * Updates the element's HTML attribute based on the property value.
- * Handles special cases for Boolean, Object, and Array types.
- *
- * @param {HTMLElement} element - The element to update
- * @param {string} attributeName - The attribute name to update
- * @param {any} value - The property value to reflect
- * @param {PropertyType} [type] - The property type constructor
- * @param {AttributeConverter<any>} [converter] - Optional custom converter
- * @returns {void}
- * @private
- *
- * @example
- * ```typescript
- * updateAttribute(element, 'active', true, Boolean) // Sets empty attribute
- * updateAttribute(element, 'count', 5, Number) // Sets attribute='5'
- * ```
- */
-function updateAttribute(
-  element: HTMLElement,
-  attributeName: string,
-  value: any,
-  type?: PropertyType,
-  converter?: AttributeConverter<any>,
-): void {
-  if (type === Boolean) {
-    if (value) {
-      element.setAttribute(attributeName, "");
-    } else {
-      element.removeAttribute(attributeName);
-    }
-  } else if (type === Object || type === Array) {
-    if (converter && converter.toAttribute) {
-      element.setAttribute(attributeName, converter.toAttribute(value));
-    } else {
-      element.setAttribute(attributeName, JSON.stringify(value));
-    }
-  } else {
-    // Treat null/undefined as absence of attribute instead of the string "null"
-    if (value === null || value === undefined) {
-      element.removeAttribute(attributeName);
-    } else {
-      element.setAttribute(attributeName, String(value));
-    }
-  }
-}
-
-/**
- * Class field decorator that creates a reactive property with automatic attribute syncing.
- *
- * Features:
- * - Automatic type conversion between attributes and properties
- * - Optional property → attribute reflection
- * - Custom converters for complex types
- * - Automatic observedAttributes registration
- * - Deferred updates for disconnected elements
- * - Lifecycle integration (updated, shouldUpdate, renderNow)
- *
- * @decorator
- * @param {PropertyOptions} [options={}] - Configuration options for the property
- * @returns {(target: any, propertyKey: string) => void} The decorator function
- *
- * @example
- * Basic usage with different types:
- * ```typescript
- * class MyElement extends BaseComponent {
- *   @property({ type: String })
- *   name = 'default';
- *
- *   @property({ type: Number })
- *   count = 0;
- *
- *   @property({ type: Boolean })
- *   active = false;
- * }
- * ```
- *
- * @example
- * With reflection (property changes update attribute):
- * ```typescript
- * class MyElement extends BaseComponent {
- *   @property({ type: String, reflect: true })
- *   status = 'pending';
- *
- *   updateStatus() {
- *     this.status = 'complete'; // Also updates status="complete" attribute
- *   }
- * }
- * ```
- *
- * @example
- * Custom attribute name and converter:
- * ```typescript
- * class MyElement extends BaseComponent {
- *   @property({
- *     type: Object,
- *     attribute: 'data-config',
- *     converter: {
- *       fromAttribute: (value) => value ? JSON.parse(value) : {},
- *       toAttribute: (value) => JSON.stringify(value)
- *     }
- *   })
- *   config = {};
- * }
- * ```
- *
- * @example
- * Property without attribute syncing:
- * ```typescript
- * class MyElement extends BaseComponent {
- *   @property({ attribute: false })
- *   internalState = null; // No attribute created or observed
- * }
- * ```
- */
-export function property(
-  options: PropertyOptions = {},
-): (target: any, propertyKey: string) => void {
-  const {type: rawType, attribute = true, reflect = false, converter, readonly = false} = options;
-
-  const type = normalizeType(rawType);
-
-  return (target: any, propertyKey: string): void => {
-    // Use WeakMap to store instance-specific values
-    const instanceMap = new WeakMap<any, any>();
-    const attributeName = getAttributeName(propertyKey, attribute);
-
-    Object.defineProperty(target, propertyKey, {
-      get(this: any) {
-        // On first access, check if an HTML attribute exists and use that instead
-        if (
-          !instanceMap.has(this) &&
-          attributeName &&
-          this.hasAttribute &&
-          this.hasAttribute(attributeName)
-        ) {
-          const attrValue = this.getAttribute(attributeName);
-          if (attrValue !== null) {
-            let convertedValue: any;
-            if (converter && converter.fromAttribute) {
-              convertedValue = converter.fromAttribute(attrValue);
-            } else if (type === Boolean) {
-              convertedValue = true;
-            } else if (type === Number) {
-              convertedValue = Number(attrValue);
-            } else {
-              convertedValue = attrValue;
-            }
-            instanceMap.set(this, convertedValue);
-
-            // Trigger update for initial HTML attribute
-            if (typeof this.renderNow === "function") {
-              this.renderNow();
-            }
-
-            return convertedValue;
-          }
-        }
-
-        // Return the value if it exists, otherwise return default for type
-        if (instanceMap.has(this)) {
-          return instanceMap.get(this);
-        }
-        // Return type-appropriate default for undefined values
-        if (type === Boolean) {
-          return false;
-        }
-        return undefined;
-      },
-      set(this: any, value: any) {
-        // If readonly is true and value already exists, prevent setting
-        if (readonly && instanceMap.has(this)) {
-          return;
-        }
-        
-        const oldValue = instanceMap.get(this);
-        let convertedValue: any;
-        let isRenderOnSet = false;
-
-        if ((type === null || type === undefined) && value !== oldValue) {
-          isRenderOnSet = true;
-        }
-
-
-        // On first set, check if an HTML attribute exists and use that instead of the default
-        if (
-          !instanceMap.has(this) &&
-          attributeName &&
-          this.hasAttribute &&
-          this.hasAttribute(attributeName)
-        ) {
-          
-          const attrValue = this.getAttribute(attributeName);
-          if (attrValue !== null) {
-            if (converter && converter.fromAttribute) {
-              convertedValue = converter.fromAttribute(attrValue);
-            } else if (type === Boolean) {
-              convertedValue = true;
-            } else if (type === Number) {
-              convertedValue = Number(attrValue);
-            } else {
-              convertedValue = attrValue;
-            }
-            instanceMap.set(this, convertedValue);
-
-            // Trigger update for initial HTML attribute only if connected
-            if (this.isConnected) {
-              
-              if (typeof this.renderNow === "function") {
-                this.renderNow();
-              }
-              // Call updated callback
-              if (this.updated) {
-                this.updated(propertyKey, oldValue, convertedValue);
-              }
-            } else {
-              
-              // Queue for later when element connects
-              if (this.updated) {
-                if (!pendingUpdates.has(this)) {
-                  pendingUpdates.set(this, []);
-                }
-                pendingUpdates
-                  .get(this)!
-                  .push({propertyKey, oldValue, newValue: convertedValue});
-              }
-            }
-           
-            return;
-          }
-        }
-        if (isRenderOnSet) {
-          convertedValue = value;
-        } else {
-          convertedValue = convertPropertyValue(value, type, converter);
-        }
-
-        if (oldValue === convertedValue) {
-          return;
-        }
-
-        const shouldUpdate = this.shouldUpdate
-          ? this.shouldUpdate(propertyKey, oldValue, convertedValue)
-          : true;
-
-        instanceMap.set(this, shouldUpdate ? convertedValue : oldValue);
-
-        // Update attribute if reflect is enabled
-        if (reflect && attributeName !== undefined) {
-          if (this.isConnected) {
-            // Element is connected, update attribute immediately
-            settingAttributes.add(this);
-            try {
-              updateAttribute(
-                this,
-                attributeName,
-                shouldUpdate ? convertedValue : oldValue,
-                type,
-                converter,
-              );
-            } finally {
-              settingAttributes.delete(this);
-            }
-          } else {
-            // Element not connected yet, queue for later
-            if (!pendingAttributeReflections.has(this)) {
-              pendingAttributeReflections.set(this, new Map());
-            }
-            pendingAttributeReflections.get(this)!.set(attributeName, {
-              value: shouldUpdate ? convertedValue : oldValue,
-              type,
-              converter,
-            });
-          }
-          
-
-        }
-
-        // Trigger update only if connected
-        if (this.isConnected) {
-          if (typeof this.renderNow === "function") {
-            this.renderNow();
-          }
-          // Call updated callback
-          if (this.updated) {
-            this.updated(propertyKey, oldValue, convertedValue);
-          }
-        } else {
-          // Queue updated callback for later when element connects
-          if (this.updated) {
-            if (!pendingUpdates.has(this)) {
-              pendingUpdates.set(this, []);
-            }
-            pendingUpdates
-              .get(this)!
-              .push({propertyKey, oldValue, newValue: convertedValue});
-          }
-        }
-
-        // Call renderNow if @RenderOnSet is used and value changed
-        if (isRenderOnSet && typeof this.renderNow === "function" ) {
-          this.renderNow();
-        }
-        
-      },
-      configurable: true,
-    });
-
-    // Register property info for attribute change detection
-    if (!target.constructor._propertyInfo) {
-      target.constructor._propertyInfo = new Map<string, PropertyOptions>();
-    }
-    target.constructor._propertyInfo.set(propertyKey, {
-      ...options,
-      name: propertyKey,
-      attribute: attributeName,
-      type,
-    });
-
-    // Register observed attributes
-    if (attributeName) {
-      if (!target.constructor.observedAttributes) {
-        target.constructor.observedAttributes = [];
-      }
-      if (!target.constructor.observedAttributes.includes(attributeName)) {
-        target.constructor.observedAttributes.push(attributeName);
-      }
-    }
-  };
-}
+/**
+ * Supported property type constructors for reactive properties.
+ * These constructors are used to convert attribute values to the correct JavaScript type.
+ *
+ * @typedef {StringConstructor | NumberConstructor | BooleanConstructor | ObjectConstructor | ArrayConstructor} PropertyType
+ */
+type PropertyType =
+  | StringConstructor
+  | NumberConstructor
+  | BooleanConstructor
+  | ObjectConstructor
+  | ArrayConstructor;
+
+/**
+ * Legacy string-based property types (deprecated).
+ * Maintained for backward compatibility. Use PropertyType constructors instead.
+ *
+ * @typedef {('string' | 'number' | 'boolean' | 'object' | 'array')} oldPropertyType
+ * @deprecated Use PropertyType constructors (String, Number, Boolean, Object, Array) instead
+ */
+type oldPropertyType = "string" | "number" | "boolean" | "object" | "array";
+
+/**
+ * Configuration options for the @property decorator.
+ * Defines how a property should sync with HTML attributes and trigger updates.
+ *
+ * @interface PropertyOptions
+ *
+ * @example
+ * ```typescript
+ * @property({ type: String, reflect: true })
+ * name = 'default';
+ *
+ * @property({ type: Number, attribute: 'data-count' })
+ * count = 0;
+ *
+ * @property({ type: Boolean })
+ * active = false;
+ * ```
+ */
+export interface PropertyOptions {
+  /**
+   * The type constructor for converting attribute values to property values.
+   * Use String, Number, Boolean, Object, or Array.
+   * @type {PropertyType | oldPropertyType}
+   */
+  type?: PropertyType | oldPropertyType;
+
+  /**
+   * The HTML attribute name to sync with, or false to disable attribute syncing.
+   * - `true` (default): Use kebab-case version of property name
+   * - `string`: Use specific attribute name
+   * - `false`: No attribute syncing
+   * @type {string | boolean}
+   */
+  attribute?: string | boolean;
+
+  /**
+   * Whether to reflect property changes back to the HTML attribute.
+   * When true, setting the property will update the attribute.
+   * @type {boolean}
+   * @default false
+   */
+  reflect?: boolean;
+
+  readonly?: boolean;
+
+  /**
+   * Custom converter for complex attribute/property transformations.
+   * @type {AttributeConverter<any>}
+   */
+  converter?: AttributeConverter<any>;
+}
+
+/**
+ * PropertyOptions extended with the property name.
+ * Used internally to track registered properties.
+ *
+ * @typedef {PropertyOptions & { name: string }} PropertyOptionsWithName
+ */
+export type PropertyOptionsWithName = PropertyOptions & {name: string};
+
+/**
+ * Track which elements are currently updating attributes from property setters.
+ * Prevents infinite loops when reflection is enabled (property → attribute → property).
+ *
+ * @type {WeakSet<HTMLElement>}
+ * @private
+ */
+const settingAttributes = new WeakSet<HTMLElement>();
+
+/**
+ * Queue of pending attribute reflections for elements not yet connected to the DOM.
+ * Attribute reflections are deferred until the element is connected.
+ *
+ * @type {WeakMap<HTMLElement, Map<string, {value: any, type: any, converter?: AttributeConverter<any>}>>}
+ * @private
+ */
+const pendingAttributeReflections = new WeakMap<
+  HTMLElement,
+  Map<string, {value: any; type: any; converter?: AttributeConverter<any>}>
+>();
+
+/**
+ * Queue of pending update callbacks for elements not yet connected to the DOM.
+ * Updates are deferred until the element is connected to avoid calling lifecycle
+ * methods on unattached elements.
+ *
+ * @type {WeakMap<HTMLElement, Array<{propertyKey: string, oldValue: any, newValue: any}>>}
+ * @private
+ */
+const pendingUpdates = new WeakMap<
+  HTMLElement,
+  Array<{propertyKey: string; oldValue: any; newValue: any}>
+>();
+
+/**
+ * Checks if an element is currently updating its attributes from property setters.
+ * Used to prevent circular updates during property reflection.
+ *
+ * @param {HTMLElement} element - The element to check
+ * @returns {boolean} True if the element is currently setting attributes
+ *
+ * @example
+ * ```typescript
+ * if (!isSettingAttribute(this)) {
+ *   // Safe to update property from attribute
+ * }
+ * ```
+ */
+export function isSettingAttribute(element: HTMLElement): boolean {
+  return settingAttributes.has(element);
+}
+
+/**
+ * Process any pending update callbacks for an element.
+ * Should be called when the element connects to the DOM to trigger
+ * deferred lifecycle callbacks.
+ *
+ * @param {any} element - The element with pending updates
+ * @returns {void}
+ *
+ * @example
+ * ```typescript
+ * connectedCallback() {
+ *   processPendingUpdates(this);
+ * }
+ * ```
+ */
+export function processPendingUpdates(element: any): void {
+  // Process pending attribute reflections first
+  const pendingReflections = pendingAttributeReflections.get(element);
+  if (pendingReflections) {
+    settingAttributes.add(element);
+    try {
+      pendingReflections.forEach((reflection, attributeName) => {
+        updateAttribute(
+          element,
+          attributeName,
+          reflection.value,
+          reflection.type,
+          reflection.converter,
+        );
+      });
+    } finally {
+      settingAttributes.delete(element);
+    }
+    pendingAttributeReflections.delete(element);
+  }
+
+  // Process pending updated callbacks
+  const pending = pendingUpdates.get(element);
+  if (pending && element.updated) {
+    const pendingLength = pending.length;
+    let i = 0;
+    while (i < pendingLength) {
+      const update = pending[i];
+      element.updated(update.propertyKey, update.oldValue, update.newValue);
+      i = i + 1;
+    }
+    pendingUpdates.delete(element);
+  }
+}
+
+/**
+ * Interface for custom attribute conversion functions.
+ *
+ * @interface AttributeConverter
+ * @template T The type of the property value
+ * @description Provides custom conversion logic between HTML attribute strings
+ * and JavaScript property values for complex data types or custom formatting.
+ */
+export interface AttributeConverter<T> {
+  /**
+   * Converts an HTML attribute string value to a JavaScript property value.
+   *
+   * @param {string | null} value - The attribute value to convert
+   * @returns {T} The converted JavaScript value
+   * @optional
+   *
+   * @example
+   * ```typescript
+   * fromAttribute: (value: string | null) => {
+   *   return value ? JSON.parse(value) : null;
+   * }
+   * ```
+   */
+  fromAttribute?(value: string | null): T;
+
+  /**
+   * Converts a JavaScript property value to an HTML attribute string.
+   *
+   * @param {T} value - The JavaScript value to convert
+   * @returns {string} The converted attribute string
+   * @optional
+   *
+   * @example
+   * ```typescript
+   * toAttribute: (value: object) => {
+   *   return JSON.stringify(value);
+   * }
+   * ```
+   */
+  toAttribute?(value: T): string;
+}
+
+/**
+ * Converts legacy string-based type to PropertyType constructor.
+ * Provides backward compatibility for old string type declarations.
+ *
+ * @param {PropertyType | oldPropertyType | undefined} type - The type to normalize
+ * @returns {PropertyType} The normalized PropertyType constructor (defaults to String)
+ * @private
+ *
+ * @example
+ * ```typescript
+ * normalizeType('string') // Returns String constructor
+ * normalizeType(Number) // Returns Number constructor
+ * ```
+ */
+function normalizeType(
+  type: PropertyType | oldPropertyType | undefined,
+): PropertyType {
+  if (typeof type === "string") {
+    switch (type) {
+      case "string":
+        return String;
+      case "number":
+        return Number;
+      case "boolean":
+        return Boolean;
+      case "object":
+        return Object;
+      case "array":
+        return Array;
+      default:
+        return null;
+    }
+  }
+  return type;
+}
+
+/**
+ * Converts a property value to the specified type.
+ * Uses custom converter if provided, otherwise performs standard type conversion.
+ *
+ * @param {any} value - The value to convert
+ * @param {PropertyType} [type] - The target type constructor
+ * @param {AttributeConverter<any>} [converter] - Optional custom converter
+ * @returns {any} The converted value
+ * @private
+ *
+ * @example
+ * ```typescript
+ * convertPropertyValue('42', Number) // Returns 42
+ * convertPropertyValue('true', Boolean) // Returns true
+ * convertPropertyValue('{"a":1}', Object) // Returns {a: 1}
+ * ```
+ */
+function convertPropertyValue(
+  value: any,
+  type?: PropertyType,
+  converter?: AttributeConverter<any>,
+): any {
+  // Use custom converter if provided
+  if (converter && converter.fromAttribute && typeof value === "string") {
+    return converter.fromAttribute(value);
+  }
+
+  // Preserve null/undefined
+  if (value === null || value === undefined) {
+    return value;
+  }
+
+  // Standard type conversion
+  switch (type) {
+    case String:
+      return String(value);
+    case Number:
+      return Number(value);
+    case Boolean:
+      return Boolean(value);
+    case Object:
+      return typeof value === "object" ? value : JSON.parse(String(value));
+    case Array:
+      return Array.isArray(value) ? value : JSON.parse(String(value));
+    default:
+      return value;
+  }
+}
+
+/**
+ * Converts a camelCase string to kebab-case.
+ * Used to derive HTML attribute names from JavaScript property names.
+ *
+ * @param {string} str - The camelCase string to convert
+ * @returns {string} The kebab-case string
+ * @private
+ *
+ * @example
+ * ```typescript
+ * camelToKebabCase('myProperty') // Returns 'my-property'
+ * camelToKebabCase('isActive') // Returns 'is-active'
+ * ```
+ */
+function camelToKebabCase(str: string): string {
+  return str.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase();
+}
+
+/**
+ * Calculates the HTML attribute name based on property options.
+ *
+ * @param {string} propertyKey - The JavaScript property name
+ * @param {string | boolean | undefined} attribute - The attribute option from PropertyOptions
+ * @returns {string | undefined} The attribute name, or undefined if attribute syncing is disabled
+ * @private
+ *
+ * @example
+ * ```typescript
+ * getAttributeName('myProp', true) // Returns 'my-prop'
+ * getAttributeName('myProp', 'data-value') // Returns 'data-value'
+ * getAttributeName('myProp', false) // Returns undefined
+ * ```
+ */
+function getAttributeName(
+  propertyKey: string,
+  attribute: string | boolean | undefined,
+): string | undefined {
+  if (attribute === false) return undefined;
+  if (attribute === true) return camelToKebabCase(propertyKey);
+  if (typeof attribute === "string") return attribute;
+  return undefined;
+}
+
+/**
+ * Updates the element's HTML attribute based on the property value.
+ * Handles special cases for Boolean, Object, and Array types.
+ *
+ * @param {HTMLElement} element - The element to update
+ * @param {string} attributeName - The attribute name to update
+ * @param {any} value - The property value to reflect
+ * @param {PropertyType} [type] - The property type constructor
+ * @param {AttributeConverter<any>} [converter] - Optional custom converter
+ * @returns {void}
+ * @private
+ *
+ * @example
+ * ```typescript
+ * updateAttribute(element, 'active', true, Boolean) // Sets empty attribute
+ * updateAttribute(element, 'count', 5, Number) // Sets attribute='5'
+ * ```
+ */
+function updateAttribute(
+  element: HTMLElement,
+  attributeName: string,
+  value: any,
+  type?: PropertyType,
+  converter?: AttributeConverter<any>,
+): void {
+  if (type === Boolean) {
+    if (value) {
+      element.setAttribute(attributeName, "");
+    } else {
+      element.removeAttribute(attributeName);
+    }
+  } else if (type === Object || type === Array) {
+    if (converter && converter.toAttribute) {
+      element.setAttribute(attributeName, converter.toAttribute(value));
+    } else {
+      element.setAttribute(attributeName, JSON.stringify(value));
+    }
+  } else {
+    // Treat null/undefined as absence of attribute instead of the string "null"
+    if (value === null || value === undefined) {
+      element.removeAttribute(attributeName);
+    } else {
+      element.setAttribute(attributeName, String(value));
+    }
+  }
+}
+
+/**
+ * Class field decorator that creates a reactive property with automatic attribute syncing.
+ *
+ * Features:
+ * - Automatic type conversion between attributes and properties
+ * - Optional property → attribute reflection
+ * - Custom converters for complex types
+ * - Automatic observedAttributes registration
+ * - Deferred updates for disconnected elements
+ * - Lifecycle integration (updated, shouldUpdate, renderNow)
+ *
+ * @decorator
+ * @param {PropertyOptions} [options={}] - Configuration options for the property
+ * @returns {(target: any, propertyKey: string) => void} The decorator function
+ *
+ * @example
+ * Basic usage with different types:
+ * ```typescript
+ * class MyElement extends BaseComponent {
+ *   @property({ type: String })
+ *   name = 'default';
+ *
+ *   @property({ type: Number })
+ *   count = 0;
+ *
+ *   @property({ type: Boolean })
+ *   active = false;
+ * }
+ * ```
+ *
+ * @example
+ * With reflection (property changes update attribute):
+ * ```typescript
+ * class MyElement extends BaseComponent {
+ *   @property({ type: String, reflect: true })
+ *   status = 'pending';
+ *
+ *   updateStatus() {
+ *     this.status = 'complete'; // Also updates status="complete" attribute
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * Custom attribute name and converter:
+ * ```typescript
+ * class MyElement extends BaseComponent {
+ *   @property({
+ *     type: Object,
+ *     attribute: 'data-config',
+ *     converter: {
+ *       fromAttribute: (value) => value ? JSON.parse(value) : {},
+ *       toAttribute: (value) => JSON.stringify(value)
+ *     }
+ *   })
+ *   config = {};
+ * }
+ * ```
+ *
+ * @example
+ * Property without attribute syncing:
+ * ```typescript
+ * class MyElement extends BaseComponent {
+ *   @property({ attribute: false })
+ *   internalState = null; // No attribute created or observed
+ * }
+ * ```
+ */
+export function property(
+  options: PropertyOptions = {},
+): (target: any, propertyKey: string) => void {
+  const {type: rawType, attribute = true, reflect = false, converter, readonly = false} = options;
+
+  const type = normalizeType(rawType);
+
+  return (target: any, propertyKey: string): void => {
+    // Use WeakMap to store instance-specific values
+    const instanceMap = new WeakMap<any, any>();
+    const attributeName = getAttributeName(propertyKey, attribute);
+
+    // --- Patch lifecycle methods ONLY if defined in derived class ---
+    // Only patch once per class
+    if (!target.__p_elements_core_lifecycle_patch_applied) {
+      // Patch connectedCallback
+      if (Object.prototype.hasOwnProperty.call(target, 'connectedCallback') && typeof target.connectedCallback === 'function') {
+        const originalConnected = target.connectedCallback;
+        target.connectedCallback = function patchedConnectedCallback(...args: any[]) {
+          const PATCHED_FLAG = '__p_elements_core_pending_updates_called';
+          if (!this[PATCHED_FLAG]) {
+            let superCalled = false;
+            const origProcess = processPendingUpdates;
+            const self = this;
+            function wrappedProcessPendingUpdates(element: any) {
+              if (element === self) {
+                superCalled = true;
+              }
+              return origProcess(element);
+            }
+            (globalThis as any).__origProcessPendingUpdates = processPendingUpdates;
+            (globalThis as any).processPendingUpdates = wrappedProcessPendingUpdates;
+            try {
+              if (originalConnected) {
+                originalConnected.apply(this, args);
+              }
+            } finally {
+              (globalThis as any).processPendingUpdates = (globalThis as any).__origProcessPendingUpdates;
+              delete (globalThis as any).__origProcessPendingUpdates;
+            }
+            if (!superCalled) {
+              let baseProto = Object.getPrototypeOf(target);
+              let baseConnected = baseProto && baseProto.connectedCallback;
+              if (typeof baseConnected === 'function') {
+                baseConnected.apply(this, args);
+                if (typeof console !== 'undefined' && console.info) {
+                  console.info(`[p-elements-core] connectedCallback: called base automatically for <${this.nodeName}>`);
+                }
+              } else {
+                processPendingUpdates(this);
+                if (typeof console !== 'undefined' && console.info) {
+                  console.info(`[p-elements-core] connectedCallback: called processPendingUpdates automatically for <${this.nodeName}>`);
+                }
+              }
+            }
+            this[PATCHED_FLAG] = true;
+          } else if (originalConnected) {
+            originalConnected.apply(this, args);
+          }
+        };
+      }
+
+      // Patch disconnectedCallback
+      if (Object.prototype.hasOwnProperty.call(target, 'disconnectedCallback') && typeof target.disconnectedCallback === 'function') {
+        const originalDisconnected = target.disconnectedCallback;
+        target.disconnectedCallback = function patchedDisconnectedCallback(...args: any[]) {
+          const PATCHED_FLAG = '__p_elements_core_disconnected_called';
+          if (!this[PATCHED_FLAG]) {
+            let superCalled = false;
+            const baseProto = Object.getPrototypeOf(target);
+            const baseDisconnected = baseProto && baseProto.disconnectedCallback;
+            if (originalDisconnected) {
+              originalDisconnected.apply(this, args);
+              superCalled = true;
+            }
+            if (!superCalled && typeof baseDisconnected === 'function') {
+              baseDisconnected.apply(this, args);
+                if (typeof console !== 'undefined' && console.info) {
+                  console.info(`[p-elements-core] disconnectedCallback: called base automatically for <${this.nodeName}>`);
+                }
+            }
+            this[PATCHED_FLAG] = true;
+          } else if (originalDisconnected) {
+            originalDisconnected.apply(this, args);
+          }
+        };
+      }
+
+      // Patch attributeChangedCallback
+      if (Object.prototype.hasOwnProperty.call(target, 'attributeChangedCallback') && typeof target.attributeChangedCallback === 'function') {
+        const originalAttributeChanged = target.attributeChangedCallback;
+        target.attributeChangedCallback = function patchedAttributeChangedCallback(...args: any[]) {
+          const PATCHED_FLAG = '__p_elements_core_attribute_changed_called';
+          if (!this[PATCHED_FLAG]) {
+            let superCalled = false;
+            const baseProto = Object.getPrototypeOf(target);
+            const baseAttributeChanged = baseProto && baseProto.attributeChangedCallback;
+            if (originalAttributeChanged) {
+              originalAttributeChanged.apply(this, args);
+              superCalled = true;
+            }
+            if (!superCalled && typeof baseAttributeChanged === 'function') {
+              baseAttributeChanged.apply(this, args);
+                if (typeof console !== 'undefined' && console.info) {
+                  console.info(`[p-elements-core] attributeChangedCallback: called base automatically for <${this.nodeName}>`);
+                }
+            }
+            this[PATCHED_FLAG] = true;
+          } else if (originalAttributeChanged) {
+            originalAttributeChanged.apply(this, args);
+          }
+        };
+      }
+
+      target.__p_elements_core_lifecycle_patch_applied = true;
+    }
+
+    Object.defineProperty(target, propertyKey, {
+      get(this: any) {
+        // On first access, check if an HTML attribute exists and use that instead
+        if (
+          !instanceMap.has(this) &&
+          attributeName &&
+          this.hasAttribute &&
+          this.hasAttribute(attributeName)
+        ) {
+          const attrValue = this.getAttribute(attributeName);
+          if (attrValue !== null) {
+            let convertedValue: any;
+            if (converter && converter.fromAttribute) {
+              convertedValue = converter.fromAttribute(attrValue);
+            } else if (type === Boolean) {
+              convertedValue = true;
+            } else if (type === Number) {
+              convertedValue = Number(attrValue);
+            } else {
+              convertedValue = attrValue;
+            }
+            instanceMap.set(this, convertedValue);
+
+            // Trigger update for initial HTML attribute
+            if (typeof this.renderNow === "function") {
+              this.renderNow();
+            }
+
+            return convertedValue;
+          }
+        }
+
+        // Return the value if it exists, otherwise return default for type
+        if (instanceMap.has(this)) {
+          return instanceMap.get(this);
+        }
+        // Return type-appropriate default for undefined values
+        if (type === Boolean) {
+          return false;
+        }
+        return undefined;
+      },
+      set(this: any, value: any) {
+        // If readonly is true and value already exists, prevent setting
+        if (readonly && instanceMap.has(this)) {
+          return;
+        }
+
+        const oldValue = instanceMap.get(this);
+        let convertedValue: any;
+        let isRenderOnSet = false;
+
+        if ((type === null || type === undefined) && value !== oldValue) {
+          isRenderOnSet = true;
+        }
+
+
+        // On first set, check if an HTML attribute exists and use that instead of the default
+        if (
+          !instanceMap.has(this) &&
+          attributeName &&
+          this.hasAttribute &&
+          this.hasAttribute(attributeName)
+        ) {
+
+          const attrValue = this.getAttribute(attributeName);
+          if (attrValue !== null) {
+            if (converter && converter.fromAttribute) {
+              convertedValue = converter.fromAttribute(attrValue);
+            } else if (type === Boolean) {
+              convertedValue = true;
+            } else if (type === Number) {
+              convertedValue = Number(attrValue);
+            } else {
+              convertedValue = attrValue;
+            }
+            instanceMap.set(this, convertedValue);
+
+            // Trigger update for initial HTML attribute only if connected
+            if (this.isConnected) {
+
+              if (typeof this.renderNow === "function") {
+                this.renderNow();
+              }
+              // Call updated callback
+              if (this.updated) {
+                this.updated(propertyKey, oldValue, convertedValue);
+              }
+            } else {
+
+              // Queue for later when element connects
+              if (this.updated) {
+                if (!pendingUpdates.has(this)) {
+                  pendingUpdates.set(this, []);
+                }
+                pendingUpdates
+                  .get(this)!
+                  .push({propertyKey, oldValue, newValue: convertedValue});
+              }
+            }
+
+            return;
+          }
+        }
+        if (isRenderOnSet) {
+          convertedValue = value;
+        } else {
+          convertedValue = convertPropertyValue(value, type, converter);
+        }
+
+        if (oldValue === convertedValue) {
+          return;
+        }
+
+        const shouldUpdate = this.shouldUpdate
+          ? this.shouldUpdate(propertyKey, oldValue, convertedValue)
+          : true;
+
+        instanceMap.set(this, shouldUpdate ? convertedValue : oldValue);
+
+        // Update attribute if reflect is enabled
+        if (reflect && attributeName !== undefined) {
+          if (this.isConnected) {
+            // Element is connected, update attribute immediately
+            settingAttributes.add(this);
+            try {
+              updateAttribute(
+                this,
+                attributeName,
+                shouldUpdate ? convertedValue : oldValue,
+                type,
+                converter,
+              );
+            } finally {
+              settingAttributes.delete(this);
+            }
+          } else {
+            // Element not connected yet, queue for later
+            if (!pendingAttributeReflections.has(this)) {
+              pendingAttributeReflections.set(this, new Map());
+            }
+            pendingAttributeReflections.get(this)!.set(attributeName, {
+              value: shouldUpdate ? convertedValue : oldValue,
+              type,
+              converter,
+            });
+          }
+
+
+        }
+
+        // Trigger update only if connected
+        if (this.isConnected) {
+          if (typeof this.renderNow === "function") {
+            this.renderNow();
+          }
+          // Call updated callback
+          if (this.updated) {
+            this.updated(propertyKey, oldValue, convertedValue);
+          }
+        } else {
+          // Queue updated callback for later when element connects
+          if (this.updated) {
+            if (!pendingUpdates.has(this)) {
+              pendingUpdates.set(this, []);
+            }
+            pendingUpdates
+              .get(this)!
+              .push({propertyKey, oldValue, newValue: convertedValue});
+          }
+        }
+
+        // Call renderNow if @RenderOnSet is used and value changed
+        if (isRenderOnSet && typeof this.renderNow === "function" ) {
+          this.renderNow();
+        }
+
+      },
+      configurable: true,
+    });
+
+    // Register property info for attribute change detection
+    if (!target.constructor._propertyInfo) {
+      target.constructor._propertyInfo = new Map<string, PropertyOptions>();
+    }
+    target.constructor._propertyInfo.set(propertyKey, {
+      ...options,
+      name: propertyKey,
+      attribute: attributeName,
+      type,
+    });
+
+    // Register observed attributes
+    if (attributeName) {
+      if (!target.constructor.observedAttributes) {
+        target.constructor.observedAttributes = [];
+      }
+      if (!target.constructor.observedAttributes.includes(attributeName)) {
+        target.constructor.observedAttributes.push(attributeName);
+      }
+    }
+  };
+}