snice 2.2.3 → 2.3.0

package/dist/index.cjs

@@ -1,5 +1,5 @@
 /*!
- * snice v2.2.2
+ * snice v2.2.3
  * Imperative TypeScript framework for building vanilla web components with decorators, routing, and controllers. No virtual DOM, no build complexity.
  * (c) 2024
  * Released under the MIT License.
@@ -1340,7 +1340,18 @@ function parseAttributeValue(attributeValue, propertyOptions, currentValue, init
     const typeToUse = propertyOptions.type || detectType(initialValue);
     switch (typeToUse) {
         case Boolean:
-            return attributeValue !== null && attributeValue !== 'false';
+            // Boolean semantics per user specification:
+            // - No attribute = false
+            // - String "false" = false
+            // - String "true" = true
+            // - Empty string = true (attribute exists like <element bool-attr>)
+            // - Any other value = true
+            if (attributeValue === null)
+                return false; // No attribute
+            if (attributeValue === 'false')
+                return false; // String "false"
+            // All other cases (including empty string) = true (attribute exists)
+            return true;
         case Number:
             return attributeValue !== null ? Number(attributeValue) : null;
         case String:
@@ -1356,6 +1367,20 @@ function parseAttributeValue(attributeValue, propertyOptions, currentValue, init
             }
         case SimpleArray:
             return SimpleArray.parse(attributeValue);
+        case Array:
+            try {
+                return attributeValue ? JSON.parse(attributeValue) : [];
+            }
+            catch {
+                return [];
+            }
+        case Object:
+            try {
+                return attributeValue ? JSON.parse(attributeValue) : {};
+            }
+            catch {
+                return {};
+            }
         default:
             // If no type specified and can't detect, try to infer from current value type
             if (typeof currentValue === 'number' && attributeValue !== null) {
@@ -1366,6 +1391,40 @@ function parseAttributeValue(attributeValue, propertyOptions, currentValue, init
             }
     }
 }
+/**
+ * Converts a property value to its attribute string representation
+ * @param value - The property value to convert
+ * @param propertyOptions - The options from @property decorator
+ * @param initialValue - The default value assigned to the property field (used for type detection)
+ * @returns The string representation for the HTML attribute, or null if value should remove attribute
+ */
+function valueToAttribute(value, propertyOptions, initialValue) {
+    // Handle null/undefined/false values and empty arrays
+    if (value === null || value === undefined || value === false ||
+        (propertyOptions?.type === SimpleArray && Array.isArray(value) && value.length === 0)) {
+        return null;
+    }
+    // Use custom converter if provided
+    if (propertyOptions.converter?.toAttribute) {
+        return propertyOptions.converter.toAttribute(value, propertyOptions.type);
+    }
+    // Use explicit type or detect from initial value
+    const typeToUse = propertyOptions.type || detectType(initialValue);
+    switch (typeToUse) {
+        case Date:
+            return value instanceof Date ? value.toISOString() : String(value);
+        case BigInt:
+            return typeof value === 'bigint' ? value.toString() + 'n' : String(value);
+        case SimpleArray:
+            return Array.isArray(value) ? SimpleArray.serialize(value) : String(value);
+        case Array:
+            return Array.isArray(value) ? JSON.stringify(value) : String(value);
+        case Object:
+            return typeof value === 'object' && value !== null ? JSON.stringify(value) : String(value);
+        default:
+            return String(value);
+    }
+}
 
 /**
  * Applies core element functionality to a constructor
@@ -1464,36 +1523,8 @@ function applyElementFunctionality(constructor) {
             }
             // Mark that properties have been initialized
             this[PROPERTIES_INITIALIZED] = true;
-            // Reflect properties that were explicitly set before connection
-            // AND also reflect initial values that have reflect: true
-            if (properties) {
-                for (const [propName, propOptions] of properties) {
-                    const wasExplicitlySet = this[EXPLICITLY_SET_PROPERTIES] && this[EXPLICITLY_SET_PROPERTIES].has(propName);
-                    const hasInitialValue = propName in this[PROPERTY_VALUES];
-                    if (propOptions.reflect && hasInitialValue && (wasExplicitlySet || this[PROPERTY_VALUES][propName] !== undefined)) {
-                        const value = this[PROPERTY_VALUES][propName];
-                        const attributeName = typeof propOptions.attribute === 'string' ? propOptions.attribute : propName.toLowerCase();
-                        if (value !== null && value !== undefined && value !== false &&
-                            !(propOptions.type === SimpleArray && Array.isArray(value) && value.length === 0)) {
-                            // Handle special types for reflection
-                            let attributeValue;
-                            if (value instanceof Date) {
-                                attributeValue = value.toISOString();
-                            }
-                            else if (typeof value === 'bigint') {
-                                attributeValue = value.toString() + 'n';
-                            }
-                            else if (propOptions.type === SimpleArray && Array.isArray(value)) {
-                                attributeValue = SimpleArray.serialize(value);
-                            }
-                            else {
-                                attributeValue = String(value);
-                            }
-                            this.setAttribute(attributeName, attributeValue);
-                        }
-                    }
-                }
-            }
+            // Properties are now stateless and read from DOM attributes only
+            // Initial values are not automatically reflected
             // Clean up any existing event handlers first (for reconnection)
             cleanupEventHandlers(this);
             // Create shadow root if it doesn't exist
@@ -1650,30 +1681,34 @@ function applyElementFunctionality(constructor) {
                                 this[PROPERTY_VALUES] = {};
                             }
                             this[PROPERTY_VALUES][propName] = parsedValue;
-                            // Call watchers manually since we bypassed the setter
-                            const watchers = constructor[PROPERTY_WATCHERS];
-                            if (watchers) {
-                                // Call specific property watchers
-                                if (watchers.has(propName)) {
-                                    const propertyWatchers = watchers.get(propName);
-                                    for (const watcher of propertyWatchers) {
-                                        try {
-                                            watcher.method.call(this, currentValue, parsedValue, propName);
-                                        }
-                                        catch (error) {
-                                            console.error(`Error in @watch('${propName}') method ${watcher.methodName}:`, error);
+                            // Only call watchers if this attribute change didn't originate from a property setter
+                            const isFromPropertySetter = this._settingFromProperty?.has(name.toLowerCase());
+                            if (!isFromPropertySetter) {
+                                // Call watchers manually since we bypassed the setter
+                                const watchers = constructor[PROPERTY_WATCHERS];
+                                if (watchers) {
+                                    // Call specific property watchers
+                                    if (watchers.has(propName)) {
+                                        const propertyWatchers = watchers.get(propName);
+                                        for (const watcher of propertyWatchers) {
+                                            try {
+                                                watcher.method.call(this, currentValue, parsedValue, propName);
+                                            }
+                                            catch (error) {
+                                                console.error(`Error in @watch('${propName}') method ${watcher.methodName}:`, error);
+                                            }
                                         }
                                     }
-                                }
-                                // Call wildcard watchers (watching "*")
-                                if (watchers.has('*')) {
-                                    const wildcardWatchers = watchers.get('*');
-                                    for (const watcher of wildcardWatchers) {
-                                        try {
-                                            watcher.method.call(this, currentValue, parsedValue, propName);
-                                        }
-                                        catch (error) {
-                                            console.error(`Error in @watch('*') method ${watcher.methodName}:`, error);
+                                    // Call wildcard watchers (watching "*")
+                                    if (watchers.has('*')) {
+                                        const wildcardWatchers = watchers.get('*');
+                                        for (const watcher of wildcardWatchers) {
+                                            try {
+                                                watcher.method.call(this, currentValue, parsedValue, propName);
+                                            }
+                                            catch (error) {
+                                                console.error(`Error in @watch('*') method ${watcher.methodName}:`, error);
+                                            }
                                         }
                                     }
                                 }
@@ -1729,13 +1764,6 @@ function property(options) {
             context.metadata[PROPERTIES] = new Map();
         }
         context.metadata[PROPERTIES].set(propertyKey, options || {});
-        // Warn about problematic reflection usage at decoration time
-        if (options?.reflect && options?.type === Array) {
-            console.warn(`⚠️  Property '${propertyKey}' uses reflect:true with Array type.`);
-        }
-        if (options?.reflect && options?.type === Object) {
-            console.warn(`⚠️  Property '${propertyKey}' uses reflect:true with Object type.`);
-        }
         // Return a field initializer function for new decorators
         return function (initialValue) {
             // Detect type from initial value if not explicitly provided
@@ -1752,60 +1780,51 @@ function property(options) {
             if (!Object.hasOwnProperty.call(this.constructor.prototype, propertyKey)) {
                 const descriptor = {
                     get() {
-                        if (!this[PROPERTY_VALUES]) {
-                            this[PROPERTY_VALUES] = {};
-                        }
-                        // If we have a stored value, return it
-                        if (this[PROPERTY_VALUES][propertyKey] !== undefined) {
-                            return this[PROPERTY_VALUES][propertyKey];
-                        }
-                        // Otherwise check attribute and parse it, or return initial value
+                        // Always read from DOM attribute - no internal state
                         const attributeName = typeof finalOptions?.attribute === 'string' ? finalOptions?.attribute : propertyKey.toLowerCase();
                         const attrValue = this.getAttribute?.(attributeName);
-                        // If attribute exists or we have a type that needs special handling for null (like Boolean)
-                        if (attrValue !== null || finalOptions?.type === Boolean) {
+                        // If attribute exists, parse it
+                        if (attrValue !== null) {
                             return parseAttributeValue(attrValue, finalOptions || {}, undefined, initialValue);
                         }
+                        // For Boolean properties that have been explicitly set via attribute,
+                        // follow HTML boolean attribute semantics (absence = false)
+                        const inferredType = finalOptions?.type || detectType(initialValue);
+                        if (inferredType === Boolean && this[EXPLICITLY_SET_PROPERTIES]?.has(propertyKey)) {
+                            return false;
+                        }
+                        // Otherwise return initial value
                         return initialValue;
                     },
                     set(newValue) {
+                        // Get old value from stored state for change detection
                         if (!this[PROPERTY_VALUES]) {
                             this[PROPERTY_VALUES] = {};
                         }
-                        if (!this[EXPLICITLY_SET_PROPERTIES]) {
-                            this[EXPLICITLY_SET_PROPERTIES] = new Set();
-                        }
                         const oldValue = this[PROPERTY_VALUES][propertyKey];
+                        // Check if value actually changed
                         if (oldValue === newValue)
                             return;
-                        const isInitialDefaultValue = oldValue === undefined && !this[PROPERTIES_INITIALIZED];
-                        if (oldValue !== undefined || (isInitialDefaultValue && newValue !== null && newValue !== undefined)) {
-                            this[EXPLICITLY_SET_PROPERTIES].add(propertyKey);
-                        }
+                        // Update stored value
                         this[PROPERTY_VALUES][propertyKey] = newValue;
-                        if (finalOptions?.reflect && this.setAttribute && this[PROPERTIES_INITIALIZED] && this[EXPLICITLY_SET_PROPERTIES].has(propertyKey)) {
-                            const attributeName = typeof finalOptions.attribute === 'string' ? finalOptions.attribute : propertyKey.toLowerCase();
-                            if (newValue === null || newValue === undefined || newValue === false ||
-                                (finalOptions?.type === SimpleArray && Array.isArray(newValue) && newValue.length === 0)) {
-                                this.removeAttribute(attributeName);
-                            }
-                            else {
-                                let attributeValue;
-                                if (newValue instanceof Date) {
-                                    attributeValue = newValue.toISOString();
-                                }
-                                else if (typeof newValue === 'bigint') {
-                                    attributeValue = newValue.toString() + 'n';
-                                }
-                                else if (finalOptions?.type === SimpleArray && Array.isArray(newValue)) {
-                                    attributeValue = SimpleArray.serialize(newValue);
-                                }
-                                else {
-                                    attributeValue = String(newValue);
-                                }
-                                this.setAttribute(attributeName, attributeValue);
-                            }
+                        // Always reflect to DOM - properties are always backed by attributes
+                        const attributeName = typeof finalOptions.attribute === 'string' ? finalOptions.attribute : propertyKey.toLowerCase();
+                        const attributeValue = valueToAttribute(newValue, finalOptions, initialValue);
+                        // Flag to prevent attributeChangedCallback from triggering watchers for this change
+                        if (!this._settingFromProperty)
+                            this._settingFromProperty = new Set();
+                        this._settingFromProperty.add(attributeName.toLowerCase());
+                        if (attributeValue === null) {
+                            this.removeAttribute?.(attributeName);
+                        }
+                        else {
+                            this.setAttribute?.(attributeName, attributeValue);
                         }
+                        // Remove the flag after a short delay to allow attributeChangedCallback to run
+                        setTimeout(() => {
+                            this._settingFromProperty?.delete(attributeName.toLowerCase());
+                        }, 0);
+                        // Trigger watchers directly with proper parsed values
                         const constructor = this.constructor;
                         const watchers = constructor[PROPERTY_WATCHERS];
                         if (watchers) {