p-elements-core 1.2.30 → 1.2.32-rc-10

package/src/decorators/property.ts

@@ -1,150 +1,822 @@
-type PropertyType = "string" | "number" | "boolean" | "object";
-
-export interface AttributeConverter<T> {
-  fromAttribute?(value: string | null): T;
-  toAttribute?(value: T): string;
-}
-
-export interface PropertyOptions {
-  type?: PropertyType;
-  reflect?: boolean;
-  attribute?: string;
-  readonly?: boolean;
-  converter?: AttributeConverter<any>;
-}
-
-export interface PropertyInfo extends PropertyOptions {
-  name: string;
-}
-
-const typeToStringValue = <T>(type: PropertyType, value: T): string => {
-  if (value === undefined) {
-    return undefined;
-  }
-  else if (value === null) {
-    return null;
-  }
-  switch (type) {
-    case "string":
-      return value.toString();
-    case "number":
-      return value.toString();
-    case "object":
-      return JSON.stringify(value);
-  }
-};
-
-export const property = (propertyOptions: PropertyOptions) => {
-  return (target: any, name: string) => {
-    const ctor = target.constructor as any;
-    const sym = Symbol(name + "_PropertyDecorator");
-    if (ctor && !ctor.observedAttributes) {
-      ctor.observedAttributes = [];
-    }
-    if (ctor && !ctor.__properties__) {
-      ctor.__properties__ = [];
-    }
-    ctor.__properties__.push(name);
-    if (
-      propertyOptions.attribute &&
-      !propertyOptions.readonly &&
-      ctor.observedAttributes.indexOf(propertyOptions.attribute) === -1
-    ) {
-      ctor.observedAttributes.push(propertyOptions.attribute);
-    }
-    Object.defineProperty(target, `__property_${name}__`, {
-      configurable: true,
-      enumerable: true,
-      get: function () {
-        return propertyOptions;
-      },
-    });
-
-    if (propertyOptions.readonly === true) {
-      Object.defineProperty(target, name, {
-        get: function () {
-          return this[sym];
-        },
-        set: function (value) {
-          this[sym] = value;
-          this?.scheduleRender();
-          delete this[name];
-          Object.defineProperty(this, name, {
-            configurable: true,
-            enumerable: true,
-            get: function () {
-              return this[sym];
-            },
-            set: function () {
-              throw new Error("Cannot set read-only property");
-            },
-          });
-          Object.seal(this[sym]);
-        },
-      });
-      return;
-    }
-
-    Object.defineProperty(target, name, {
-      configurable: true,
-      enumerable: true,
-      get: function () {
-        return this[sym];
-      },
-      set: function (value) {
-        const oldValue = this[sym];
-        const skipSetValue = this?.shouldUpdate && !this.shouldUpdate(name, oldValue, value);
-        const elementToSetAttribute = this.isCustomElementController ? this.hostElement : this;
-        const attributeValue = propertyOptions.converter
-        ? propertyOptions.converter.toAttribute(value)
-        : typeToStringValue(propertyOptions.type, value);
-        if (skipSetValue) {
-          this[sym] = oldValue;
-          requestAnimationFrame(() => {
-            elementToSetAttribute.setAttribute(propertyOptions.attribute, oldValue)
-          });
-        } else {
-          this[sym] = value;
-        }
-        const handleChange = () => {
-          if (this[sym] !== oldValue) {
-            this?.scheduleRender && this.scheduleRender();
-            this?.updated && this.updated(name, oldValue, this[sym]);
-          }
-        };
-        if (propertyOptions.reflect && propertyOptions.attribute && elementToSetAttribute._canReflect) {
-          if (propertyOptions.type !== "boolean") {            
-            if (value === undefined || value === null) {
-              elementToSetAttribute.removeAttribute(propertyOptions.attribute);
-              handleChange();
-              return;
-            }
-            if (
-              elementToSetAttribute.getAttribute(propertyOptions.attribute) === attributeValue + ""	
-            ) {
-              handleChange();
-              return;
-            }
-            if (attributeValue !== null) {
-              elementToSetAttribute.setAttribute(propertyOptions.attribute, attributeValue + "");
-            } else {
-              elementToSetAttribute.removeAttribute(propertyOptions.attribute);
-            }
-          } else {
-            
-            if (value && !elementToSetAttribute.hasAttribute(propertyOptions.attribute)) {
-              elementToSetAttribute.setAttribute(propertyOptions.attribute, "");
-            } else if (!value && elementToSetAttribute.hasAttribute(propertyOptions.attribute)) {
-              elementToSetAttribute.removeAttribute(propertyOptions.attribute);
-            }
-            handleChange();
-            return;
-          }
-        }
-        handleChange();
-        this?.scheduleRender && this.scheduleRender();
-      },
-    });
-  };
-};
-
+/**
+ * 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));
+    }
+  }
+}
+
+const alreadLogedNodeNames = new Set<string>();
+
+function logConnectedCallback(nodeName: string) {
+  if (!alreadLogedNodeNames.has(nodeName)) {
+    alreadLogedNodeNames.add(nodeName);
+    if (typeof console !== "undefined" && console.info) {
+      console.info(
+        `[CustomElement] connectedCallback called for <${nodeName.toLocaleLowerCase()}>`,
+      );
+    }
+  }
+}
+
+/**
+ * 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) {
+                  // log this once per nodeName
+                  logConnectedCallback(this.nodeName);
+                }
+              } else {
+                processPendingUpdates(this);
+                if (typeof console !== "undefined" && console.info) {
+                  console.info(
+                    `[p-elements-core] 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);
+            }
+            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);
+              }
+              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);
+      }
+    }
+  };
+}