@jsenv/dom 0.5.3 → 0.6.0

package/dist/jsenv_dom.js

@@ -1,6 +1,107 @@
 import { signal, effect } from "@preact/signals";
 import { useState, useLayoutEffect } from "preact/hooks";
 
+/**
+ * Generates a unique signature for various types of elements that can be used for identification in logs.
+ *
+ * This function handles different types of elements and returns an appropriate identifier:
+ * - For DOM elements: Creates a CSS selector using tag name, data-ui-name, ID, classes, or parent hierarchy
+ * - For React/Preact elements (JSX): Returns JSX-like representation with type and props
+ * - For functions: Returns function name and optional underlying element reference in brackets
+ * - For null/undefined: Returns the string representation
+ *
+ * The returned signature for DOM elements is a valid CSS selector that can be copy-pasted
+ * into browser dev tools to locate the element in the DOM.
+ *
+ * @param {HTMLElement|Object|Function|null|undefined} element - The element to generate a signature for
+ * @returns {string} A unique identifier string in various formats depending on element type
+ *
+ * @example
+ * // For DOM element with data-ui-name
+ * // <div data-ui-name="header">
+ * getElementSignature(element) // Returns: `div[data-ui-name="header"]`
+ *
+ * @example
+ * // For DOM element with ID
+ * // <div id="main" class="container active">
+ * getElementSignature(element) // Returns: "div#main"
+ *
+ * @example
+ * // For DOM element with classes only
+ * // <button class="btn primary">
+ * getElementSignature(element) // Returns: "button.btn.primary"
+ *
+ * @example
+ * // For DOM element without distinguishing features (uses parent hierarchy)
+ * // <p> inside <section id="content">
+ * getElementSignature(element) // Returns: "section#content > p"
+ *
+ * @example
+ * // For React/Preact element with props
+ * // <MyComponent id="widget" />
+ * getElementSignature(element) // Returns: `<MyComponent id="widget" />`
+ *
+ * @example
+ * // For named function with underlying element reference
+ * const MyComponent = () => {}; MyComponent.underlyingElementId = "div#main";
+ * getElementSignature(MyComponent) // Returns: "[function MyComponent for div#main]"
+ *
+ * @example
+ * // For anonymous function without underlying element
+ * const anonymousFunc = () => {};
+ * getElementSignature(anonymousFunc) // Returns: "[function]"
+ *
+ * @example
+ * // For named function without underlying element
+ * function namedHandler() {}
+ * getElementSignature(namedHandler) // Returns: "[function namedHandler]"
+ *
+ * @example
+ * // For null/undefined
+ * getElementSignature(null) // Returns: "null"
+ */
+const getElementSignature = (element) => {
+  if (!element) {
+    return String(element);
+  }
+  if (typeof element === "function") {
+    const functionName = element.name;
+    const functionLabel = functionName
+      ? `function ${functionName}`
+      : "function";
+    const underlyingElementId = element.underlyingElementId;
+    if (underlyingElementId) {
+      return `[${functionLabel} for ${underlyingElementId}]`;
+    }
+    return `[${functionLabel}]`;
+  }
+  if (element.props) {
+    const type = element.type;
+    const id = element.props.id;
+    if (id) {
+      return `<${type} id="${id}" />`;
+    }
+    return `<${type} />`;
+  }
+
+  const tagName = element.tagName.toLowerCase();
+  const dataUIName = element.getAttribute("data-ui-name");
+  if (dataUIName) {
+    return `${tagName}[data-ui-name="${dataUIName}"]`;
+  }
+  const elementId = element.id;
+  if (elementId) {
+    return `${tagName}#${elementId}`;
+  }
+  const className = element.className;
+  if (className) {
+    return `${tagName}.${className.split(" ").join(".")}`;
+  }
+
+  const parentSignature = getElementSignature(element.parentElement);
+  return `${parentSignature} > ${tagName}`;
+};
+
 const createIterableWeakSet = () => {
   const objectWeakRefSet = new Set();
 
@@ -102,22 +203,26 @@ const createPubSub = (clearOnPublish = false) => {
 
 const createValueEffect = (value) => {
   const callbackSet = new Set();
-  const previousValueCleanupSet = new Set();
+  const valueCleanupSet = new Set();
+
+  const cleanup = () => {
+    for (const valueCleanup of valueCleanupSet) {
+      valueCleanup();
+    }
+    valueCleanupSet.clear();
+  };
 
   const updateValue = (newValue) => {
     if (newValue === value) {
       return;
     }
-    for (const cleanup of previousValueCleanupSet) {
-      cleanup();
-    }
-    previousValueCleanupSet.clear();
+    cleanup();
     const oldValue = value;
     value = newValue;
     for (const callback of callbackSet) {
       const returnValue = callback(newValue, oldValue);
       if (typeof returnValue === "function") {
-        previousValueCleanupSet.add(returnValue);
+        valueCleanupSet.add(returnValue);
       }
     }
   };
@@ -129,7 +234,7 @@ const createValueEffect = (value) => {
     };
   };
 
-  return [updateValue, addEffect];
+  return [updateValue, addEffect, cleanup];
 };
 
 // https://github.com/davidtheclark/tabbable/blob/master/index.js
@@ -433,6 +538,9 @@ const normalizeNumber = (value, context, unit, propertyName) => {
 
 // Normalize styles for DOM application
 const normalizeStyles = (styles, context = "js") => {
+  if (!styles) {
+    return {};
+  }
   if (typeof styles === "string") {
     styles = parseStyleString(styles);
     return styles;
@@ -681,6 +789,29 @@ const mergeStyles = (stylesA, stylesB, context = "js") => {
   return result;
 };
 
+const appendStyles = (
+  stylesAObject,
+  stylesBNormalized,
+  context = "js",
+) => {
+  const aKeys = Object.keys(stylesAObject);
+  const bKeys = Object.keys(stylesBNormalized);
+  for (const bKey of bKeys) {
+    const aHasKey = aKeys.includes(bKey);
+    if (aHasKey) {
+      stylesAObject[bKey] = mergeOneStyle(
+        stylesAObject[bKey],
+        stylesBNormalized[bKey],
+        bKey,
+        context,
+      );
+    } else {
+      stylesAObject[bKey] = stylesBNormalized[bKey];
+    }
+  }
+  return stylesAObject;
+};
+
 // Merge a single style property value with an existing value
 const mergeOneStyle = (
   existingValue,
@@ -4211,391 +4342,9 @@ const getDragCoordinates = (
   return [leftRelativeToScrollContainer, topRelativeToScrollContainer];
 };
 
-/* eslint-disable */
-// construct-style-sheets-polyfill@3.1.0
-// to keep in sync with https://github.com/calebdwilliams/construct-style-sheets
-// copy pasted into jsenv codebase to inject this code with more ease
-(function () {
-
-  if (typeof document === "undefined" || "adoptedStyleSheets" in document) {
-    return;
-  }
-
-  var hasShadyCss = "ShadyCSS" in window && !ShadyCSS.nativeShadow;
-  var bootstrapper = document.implementation.createHTMLDocument("");
-  var closedShadowRootRegistry = new WeakMap();
-  var _DOMException = typeof DOMException === "object" ? Error : DOMException;
-  var defineProperty = Object.defineProperty;
-  var forEach = Array.prototype.forEach;
-
-  var importPattern = /@import.+?;?$/gm;
-  function rejectImports(contents) {
-    var _contents = contents.replace(importPattern, "");
-    if (_contents !== contents) {
-      console.warn(
-        "@import rules are not allowed here. See https://github.com/WICG/construct-stylesheets/issues/119#issuecomment-588352418",
-      );
-    }
-    return _contents.trim();
-  }
-  function isElementConnected(element) {
-    return "isConnected" in element
-      ? element.isConnected
-      : document.contains(element);
-  }
-  function unique(arr) {
-    return arr.filter(function (value, index) {
-      return arr.indexOf(value) === index;
-    });
-  }
-  function diff(arr1, arr2) {
-    return arr1.filter(function (value) {
-      return arr2.indexOf(value) === -1;
-    });
-  }
-  function removeNode(node) {
-    node.parentNode.removeChild(node);
-  }
-  function getShadowRoot(element) {
-    return element.shadowRoot || closedShadowRootRegistry.get(element);
-  }
-
-  var cssStyleSheetMethods = [
-    "addRule",
-    "deleteRule",
-    "insertRule",
-    "removeRule",
-  ];
-  var NonConstructedStyleSheet = CSSStyleSheet;
-  var nonConstructedProto = NonConstructedStyleSheet.prototype;
-  nonConstructedProto.replace = function () {
-    return Promise.reject(
-      new _DOMException(
-        "Can't call replace on non-constructed CSSStyleSheets.",
-      ),
-    );
-  };
-  nonConstructedProto.replaceSync = function () {
-    throw new _DOMException(
-      "Failed to execute 'replaceSync' on 'CSSStyleSheet': Can't call replaceSync on non-constructed CSSStyleSheets.",
-    );
-  };
-  function isCSSStyleSheetInstance(instance) {
-    return typeof instance === "object"
-      ? proto$1.isPrototypeOf(instance) ||
-          nonConstructedProto.isPrototypeOf(instance)
-      : false;
-  }
-  function isNonConstructedStyleSheetInstance(instance) {
-    return typeof instance === "object"
-      ? nonConstructedProto.isPrototypeOf(instance)
-      : false;
-  }
-  var $basicStyleElement = new WeakMap();
-  var $locations = new WeakMap();
-  var $adoptersByLocation = new WeakMap();
-  var $appliedMethods = new WeakMap();
-  function addAdopterLocation(sheet, location) {
-    var adopter = document.createElement("style");
-    $adoptersByLocation.get(sheet).set(location, adopter);
-    $locations.get(sheet).push(location);
-    return adopter;
-  }
-  function getAdopterByLocation(sheet, location) {
-    return $adoptersByLocation.get(sheet).get(location);
-  }
-  function removeAdopterLocation(sheet, location) {
-    $adoptersByLocation.get(sheet).delete(location);
-    $locations.set(
-      sheet,
-      $locations.get(sheet).filter(function (_location) {
-        return _location !== location;
-      }),
-    );
-  }
-  function restyleAdopter(sheet, adopter) {
-    requestAnimationFrame(function () {
-      adopter.textContent = $basicStyleElement.get(sheet).textContent;
-      $appliedMethods.get(sheet).forEach(function (command) {
-        return adopter.sheet[command.method].apply(adopter.sheet, command.args);
-      });
-    });
-  }
-  function checkInvocationCorrectness(self) {
-    if (!$basicStyleElement.has(self)) {
-      throw new TypeError("Illegal invocation");
-    }
-  }
-  function ConstructedStyleSheet() {
-    var self = this;
-    var style = document.createElement("style");
-    bootstrapper.body.appendChild(style);
-    $basicStyleElement.set(self, style);
-    $locations.set(self, []);
-    $adoptersByLocation.set(self, new WeakMap());
-    $appliedMethods.set(self, []);
-  }
-  var proto$1 = ConstructedStyleSheet.prototype;
-  proto$1.replace = function replace(contents) {
-    try {
-      this.replaceSync(contents);
-      return Promise.resolve(this);
-    } catch (e) {
-      return Promise.reject(e);
-    }
-  };
-  proto$1.replaceSync = function replaceSync(contents) {
-    checkInvocationCorrectness(this);
-    if (typeof contents === "string") {
-      var self_1 = this;
-      $basicStyleElement.get(self_1).textContent = rejectImports(contents);
-      $appliedMethods.set(self_1, []);
-      $locations.get(self_1).forEach(function (location) {
-        if (location.isConnected()) {
-          restyleAdopter(self_1, getAdopterByLocation(self_1, location));
-        }
-      });
-    }
-  };
-  defineProperty(proto$1, "cssRules", {
-    configurable: true,
-    enumerable: true,
-    get: function cssRules() {
-      checkInvocationCorrectness(this);
-      return $basicStyleElement.get(this).sheet.cssRules;
-    },
-  });
-  defineProperty(proto$1, "media", {
-    configurable: true,
-    enumerable: true,
-    get: function media() {
-      checkInvocationCorrectness(this);
-      return $basicStyleElement.get(this).sheet.media;
-    },
-  });
-  cssStyleSheetMethods.forEach(function (method) {
-    proto$1[method] = function () {
-      var self = this;
-      checkInvocationCorrectness(self);
-      var args = arguments;
-      $appliedMethods.get(self).push({ method: method, args: args });
-      $locations.get(self).forEach(function (location) {
-        if (location.isConnected()) {
-          var sheet = getAdopterByLocation(self, location).sheet;
-          sheet[method].apply(sheet, args);
-        }
-      });
-      var basicSheet = $basicStyleElement.get(self).sheet;
-      return basicSheet[method].apply(basicSheet, args);
-    };
-  });
-  defineProperty(ConstructedStyleSheet, Symbol.hasInstance, {
-    configurable: true,
-    value: isCSSStyleSheetInstance,
-  });
-
-  var defaultObserverOptions = {
-    childList: true,
-    subtree: true,
-  };
-  var locations = new WeakMap();
-  function getAssociatedLocation(element) {
-    var location = locations.get(element);
-    if (!location) {
-      location = new Location(element);
-      locations.set(element, location);
-    }
-    return location;
-  }
-  function attachAdoptedStyleSheetProperty(constructor) {
-    defineProperty(constructor.prototype, "adoptedStyleSheets", {
-      configurable: true,
-      enumerable: true,
-      get: function () {
-        return getAssociatedLocation(this).sheets;
-      },
-      set: function (sheets) {
-        getAssociatedLocation(this).update(sheets);
-      },
-    });
-  }
-  function traverseWebComponents(node, callback) {
-    var iter = document.createNodeIterator(
-      node,
-      NodeFilter.SHOW_ELEMENT,
-      function (foundNode) {
-        return getShadowRoot(foundNode)
-          ? NodeFilter.FILTER_ACCEPT
-          : NodeFilter.FILTER_REJECT;
-      },
-      null,
-      false,
-    );
-    for (var next = void 0; (next = iter.nextNode()); ) {
-      callback(getShadowRoot(next));
-    }
-  }
-  var $element = new WeakMap();
-  var $uniqueSheets = new WeakMap();
-  var $observer = new WeakMap();
-  function isExistingAdopter(self, element) {
-    return (
-      element instanceof HTMLStyleElement &&
-      $uniqueSheets.get(self).some(function (sheet) {
-        return getAdopterByLocation(sheet, self);
-      })
-    );
-  }
-  function getAdopterContainer(self) {
-    var element = $element.get(self);
-    return element instanceof Document ? element.body : element;
-  }
-  function adopt(self) {
-    var styleList = document.createDocumentFragment();
-    var sheets = $uniqueSheets.get(self);
-    var observer = $observer.get(self);
-    var container = getAdopterContainer(self);
-    observer.disconnect();
-    sheets.forEach(function (sheet) {
-      styleList.appendChild(
-        getAdopterByLocation(sheet, self) || addAdopterLocation(sheet, self),
-      );
-    });
-    container.insertBefore(styleList, null);
-    observer.observe(container, defaultObserverOptions);
-    sheets.forEach(function (sheet) {
-      restyleAdopter(sheet, getAdopterByLocation(sheet, self));
-    });
-  }
-  function Location(element) {
-    var self = this;
-    self.sheets = [];
-    $element.set(self, element);
-    $uniqueSheets.set(self, []);
-    $observer.set(
-      self,
-      new MutationObserver(function (mutations, observer) {
-        if (!document) {
-          observer.disconnect();
-          return;
-        }
-        mutations.forEach(function (mutation) {
-          if (!hasShadyCss) {
-            forEach.call(mutation.addedNodes, function (node) {
-              if (!(node instanceof Element)) {
-                return;
-              }
-              traverseWebComponents(node, function (root) {
-                getAssociatedLocation(root).connect();
-              });
-            });
-          }
-          forEach.call(mutation.removedNodes, function (node) {
-            if (!(node instanceof Element)) {
-              return;
-            }
-            if (isExistingAdopter(self, node)) {
-              adopt(self);
-            }
-            if (!hasShadyCss) {
-              traverseWebComponents(node, function (root) {
-                getAssociatedLocation(root).disconnect();
-              });
-            }
-          });
-        });
-      }),
-    );
-  }
-  Location.prototype = {
-    isConnected: function () {
-      var element = $element.get(this);
-      return element instanceof Document
-        ? element.readyState !== "loading"
-        : isElementConnected(element.host);
-    },
-    connect: function () {
-      var container = getAdopterContainer(this);
-      $observer.get(this).observe(container, defaultObserverOptions);
-      if ($uniqueSheets.get(this).length > 0) {
-        adopt(this);
-      }
-      traverseWebComponents(container, function (root) {
-        getAssociatedLocation(root).connect();
-      });
-    },
-    disconnect: function () {
-      $observer.get(this).disconnect();
-    },
-    update: function (sheets) {
-      var self = this;
-      var locationType =
-        $element.get(self) === document ? "Document" : "ShadowRoot";
-      if (!Array.isArray(sheets)) {
-        throw new TypeError(
-          "Failed to set the 'adoptedStyleSheets' property on " +
-            locationType +
-            ": Iterator getter is not callable.",
-        );
-      }
-      if (!sheets.every(isCSSStyleSheetInstance)) {
-        throw new TypeError(
-          "Failed to set the 'adoptedStyleSheets' property on " +
-            locationType +
-            ": Failed to convert value to 'CSSStyleSheet'",
-        );
-      }
-      if (sheets.some(isNonConstructedStyleSheetInstance)) {
-        throw new TypeError(
-          "Failed to set the 'adoptedStyleSheets' property on " +
-            locationType +
-            ": Can't adopt non-constructed stylesheets",
-        );
-      }
-      self.sheets = sheets;
-      var oldUniqueSheets = $uniqueSheets.get(self);
-      var uniqueSheets = unique(sheets);
-      var removedSheets = diff(oldUniqueSheets, uniqueSheets);
-      removedSheets.forEach(function (sheet) {
-        removeNode(getAdopterByLocation(sheet, self));
-        removeAdopterLocation(sheet, self);
-      });
-      $uniqueSheets.set(self, uniqueSheets);
-      if (self.isConnected() && uniqueSheets.length > 0) {
-        adopt(self);
-      }
-    },
-  };
+const installImportMetaCss = (importMeta) => {
+  const stylesheet = new CSSStyleSheet({ baseUrl: importMeta.url });
 
-  window.CSSStyleSheet = ConstructedStyleSheet;
-  attachAdoptedStyleSheetProperty(Document);
-  if ("ShadowRoot" in window) {
-    attachAdoptedStyleSheetProperty(ShadowRoot);
-    var proto = Element.prototype;
-    var attach_1 = proto.attachShadow;
-    proto.attachShadow = function attachShadow(init) {
-      var root = attach_1.call(this, init);
-      if (init.mode === "closed") {
-        closedShadowRootRegistry.set(this, root);
-      }
-      return root;
-    };
-  }
-  var documentLocation = getAssociatedLocation(document);
-  if (documentLocation.isConnected()) {
-    documentLocation.connect();
-  } else {
-    document.addEventListener(
-      "DOMContentLoaded",
-      documentLocation.connect.bind(documentLocation),
-    );
-  }
-})();
-
-const installImportMetaCss = importMeta => {
-  const stylesheet = new CSSStyleSheet({
-    baseUrl: importMeta.url
-  });
   let called = false;
   // eslint-disable-next-line accessor-pairs
   Object.defineProperty(importMeta, "css", {
@@ -4606,8 +4355,11 @@ const installImportMetaCss = importMeta => {
       }
       called = true;
       stylesheet.replaceSync(value);
-      document.adoptedStyleSheets = [...document.adoptedStyleSheets, stylesheet];
-    }
+      document.adoptedStyleSheets = [
+        ...document.adoptedStyleSheets,
+        stylesheet,
+      ];
+    },
   });
 };
 
@@ -5666,15 +5418,6 @@ const getScrollport = (scrollBox, scrollContainer) => {
   };
 };
 
-const getElementSelector = (element) => {
-  const tagName = element.tagName.toLowerCase();
-  const id = element.id ? `#${element.id}` : "";
-  const className = element.className
-    ? `.${element.className.split(" ").join(".")}`
-    : "";
-  return `${tagName}${id}${className}`;
-};
-
 installImportMetaCss(import.meta);const setupConstraintFeedbackLine = () => {
   const constraintFeedbackLine = createConstraintFeedbackLine();
 
@@ -6700,7 +6443,7 @@ const createObstacleConstraintsFromQuerySelector = (
 
         // obstacleBounds are already in scrollable-relative coordinates, no conversion needed
         const obstacleObject = createObstacleContraint(obstacleBounds, {
-          name: `${obstacleBounds.isSticky ? "sticky " : ""}obstacle (${getElementSelector(obstacle)})`,
+          name: `${obstacleBounds.isSticky ? "sticky " : ""}obstacle (${getElementSignature(obstacle)})`,
           element: obstacle,
         });
         return obstacleObject;
@@ -6978,9 +6721,9 @@ const createStickyFrontierOnAxis = (
     const hasOpposite = frontier.hasAttribute(oppositeAttrName);
     // Check if element has both sides (invalid)
     if (hasPrimary && hasOpposite) {
-      const elementSelector = getElementSelector(frontier);
+      const elementSignature = getElementSignature(frontier);
       console.warn(
-        `Sticky frontier element (${elementSelector}) has both ${primarySide} and ${oppositeSide} attributes. 
+        `Sticky frontier element (${elementSignature}) has both ${primarySide} and ${oppositeSide} attributes. 
   A sticky frontier should only have one side attribute.`,
       );
       continue;
@@ -7003,7 +6746,7 @@ const createStickyFrontierOnAxis = (
       element: frontier,
       side: hasPrimary ? primarySide : oppositeSide,
       bounds: frontierBounds,
-      name: `sticky_frontier_${hasPrimary ? primarySide : oppositeSide} (${getElementSelector(frontier)})`,
+      name: `sticky_frontier_${hasPrimary ? primarySide : oppositeSide} (${getElementSignature(frontier)})`,
     };
     matchingStickyFrontiers.push(stickyFrontierObject);
   }
@@ -10948,7 +10691,7 @@ const initUITransition = (container) => {
       debug(
         "transition",
         `Cloned previous child for ${isPhaseTransition ? "phase" : "content"} transition:`,
-        previousChild.getAttribute("data-ui-name") || "unnamed",
+        getElementSignature(previousChild),
       );
       cleanup = () => oldChild.remove();
     } else {
@@ -11000,7 +10743,7 @@ const initUITransition = (container) => {
       if (localDebug.transition) {
         const updateLabel =
           childUIName ||
-          (firstChild ? "data-ui-name not specified" : "cleared/empty");
+          (firstChild ? getElementSignature(firstChild) : "cleared/empty");
         console.group(`UI Update: ${updateLabel} (reason: ${reason})`);
       }
 
@@ -11604,7 +11347,7 @@ const initUITransition = (container) => {
           debug(
             "transition",
             `Attribute change detected: ${attributeName} on`,
-            target.getAttribute("data-ui-name") || "element",
+            getElementSignature(target),
           );
         }
       }
@@ -11976,4 +11719,4 @@ const crossFade = {
   },
 };
 
-export { EASING, activeElementSignal, addActiveElementEffect, addAttributeEffect, addWillChange, allowWheelThrough, canInterceptKeys, captureScrollState, createDragGestureController, createDragToMoveGestureController, createHeightTransition, createIterableWeakSet, createOpacityTransition, createPubSub, createStyleController, createTimelineTransition, createTransition, createTranslateXTransition, createValueEffect, createWidthTransition, cubicBezier, dragAfterThreshold, elementIsFocusable, elementIsVisibleForFocus, elementIsVisuallyVisible, findAfter, findAncestor, findBefore, findDescendant, findFocusable, getAvailableHeight, getAvailableWidth, getBorderSizes, getContrastRatio, getDefaultStyles, getDragCoordinates, getDropTargetInfo, getFirstVisuallyVisibleAncestor, getFocusVisibilityInfo, getHeight, getInnerHeight, getInnerWidth, getMarginSizes, getMaxHeight, getMaxWidth, getMinHeight, getMinWidth, getPaddingSizes, getPositionedParent, getPreferedColorScheme, getScrollContainer, getScrollContainerSet, getScrollRelativeRect, getSelfAndAncestorScrolls, getStyle, getVisuallyVisibleInfo, getWidth, initFlexDetailsSet, initFocusGroup, initPositionSticky, initUITransition, isScrollable, mergeStyles, normalizeStyles, parseCSSColor, pickLightOrDark, pickPositionRelativeTo, prefersDarkColors, prefersLightColors, preventFocusNav, preventFocusNavViaKeyboard, resolveCSSColor, resolveCSSSize, setAttribute, setAttributes, setStyles, startDragToResizeGesture, stickyAsRelativeCoords, stringifyCSSColor, trapFocusInside, trapScrollInside, useActiveElement, useAvailableHeight, useAvailableWidth, useMaxHeight, useMaxWidth, useResizeStatus, visibleRectEffect };
+export { EASING, activeElementSignal, addActiveElementEffect, addAttributeEffect, addWillChange, allowWheelThrough, appendStyles, canInterceptKeys, captureScrollState, createDragGestureController, createDragToMoveGestureController, createHeightTransition, createIterableWeakSet, createOpacityTransition, createPubSub, createStyleController, createTimelineTransition, createTransition, createTranslateXTransition, createValueEffect, createWidthTransition, cubicBezier, dragAfterThreshold, elementIsFocusable, elementIsVisibleForFocus, elementIsVisuallyVisible, findAfter, findAncestor, findBefore, findDescendant, findFocusable, getAvailableHeight, getAvailableWidth, getBorderSizes, getContrastRatio, getDefaultStyles, getDragCoordinates, getDropTargetInfo, getElementSignature, getFirstVisuallyVisibleAncestor, getFocusVisibilityInfo, getHeight, getInnerHeight, getInnerWidth, getMarginSizes, getMaxHeight, getMaxWidth, getMinHeight, getMinWidth, getPaddingSizes, getPositionedParent, getPreferedColorScheme, getScrollContainer, getScrollContainerSet, getScrollRelativeRect, getSelfAndAncestorScrolls, getStyle, getVisuallyVisibleInfo, getWidth, initFlexDetailsSet, initFocusGroup, initPositionSticky, initUITransition, isScrollable, mergeStyles, normalizeStyles, parseCSSColor, pickLightOrDark, pickPositionRelativeTo, prefersDarkColors, prefersLightColors, preventFocusNav, preventFocusNavViaKeyboard, resolveCSSColor, resolveCSSSize, setAttribute, setAttributes, setStyles, startDragToResizeGesture, stickyAsRelativeCoords, stringifyCSSColor, trapFocusInside, trapScrollInside, useActiveElement, useAvailableHeight, useAvailableWidth, useMaxHeight, useMaxWidth, useResizeStatus, visibleRectEffect };

package/index.js

@@ -1,3 +1,5 @@
+export { getElementSignature } from "./src/element_signature.js";
+
 // state management
 export { createIterableWeakSet } from "./src/iterable_weak_set.js";
 export { createPubSub } from "./src/pub_sub.js";
@@ -5,7 +7,7 @@ export { createValueEffect } from "./src/value_effect.js";
 
 // style
 export { addWillChange, getStyle, setStyles } from "./src/style/dom_styles.js";
-export { mergeStyles } from "./src/style/style_composition.js";
+export { appendStyles, mergeStyles } from "./src/style/style_composition.js";
 export { createStyleController } from "./src/style/style_controller.js";
 export { getDefaultStyles } from "./src/style/style_default.js";
 export { normalizeStyles } from "./src/style/style_parsing.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/dom",
-  "version": "0.5.3",
+  "version": "0.6.0",
   "description": "DOM utilities for writing frontend code",
   "repository": {
     "type": "git",

package/src/element_signature.js

@@ -0,0 +1,100 @@
+/**
+ * Generates a unique signature for various types of elements that can be used for identification in logs.
+ *
+ * This function handles different types of elements and returns an appropriate identifier:
+ * - For DOM elements: Creates a CSS selector using tag name, data-ui-name, ID, classes, or parent hierarchy
+ * - For React/Preact elements (JSX): Returns JSX-like representation with type and props
+ * - For functions: Returns function name and optional underlying element reference in brackets
+ * - For null/undefined: Returns the string representation
+ *
+ * The returned signature for DOM elements is a valid CSS selector that can be copy-pasted
+ * into browser dev tools to locate the element in the DOM.
+ *
+ * @param {HTMLElement|Object|Function|null|undefined} element - The element to generate a signature for
+ * @returns {string} A unique identifier string in various formats depending on element type
+ *
+ * @example
+ * // For DOM element with data-ui-name
+ * // <div data-ui-name="header">
+ * getElementSignature(element) // Returns: `div[data-ui-name="header"]`
+ *
+ * @example
+ * // For DOM element with ID
+ * // <div id="main" class="container active">
+ * getElementSignature(element) // Returns: "div#main"
+ *
+ * @example
+ * // For DOM element with classes only
+ * // <button class="btn primary">
+ * getElementSignature(element) // Returns: "button.btn.primary"
+ *
+ * @example
+ * // For DOM element without distinguishing features (uses parent hierarchy)
+ * // <p> inside <section id="content">
+ * getElementSignature(element) // Returns: "section#content > p"
+ *
+ * @example
+ * // For React/Preact element with props
+ * // <MyComponent id="widget" />
+ * getElementSignature(element) // Returns: `<MyComponent id="widget" />`
+ *
+ * @example
+ * // For named function with underlying element reference
+ * const MyComponent = () => {}; MyComponent.underlyingElementId = "div#main";
+ * getElementSignature(MyComponent) // Returns: "[function MyComponent for div#main]"
+ *
+ * @example
+ * // For anonymous function without underlying element
+ * const anonymousFunc = () => {};
+ * getElementSignature(anonymousFunc) // Returns: "[function]"
+ *
+ * @example
+ * // For named function without underlying element
+ * function namedHandler() {}
+ * getElementSignature(namedHandler) // Returns: "[function namedHandler]"
+ *
+ * @example
+ * // For null/undefined
+ * getElementSignature(null) // Returns: "null"
+ */
+export const getElementSignature = (element) => {
+  if (!element) {
+    return String(element);
+  }
+  if (typeof element === "function") {
+    const functionName = element.name;
+    const functionLabel = functionName
+      ? `function ${functionName}`
+      : "function";
+    const underlyingElementId = element.underlyingElementId;
+    if (underlyingElementId) {
+      return `[${functionLabel} for ${underlyingElementId}]`;
+    }
+    return `[${functionLabel}]`;
+  }
+  if (element.props) {
+    const type = element.type;
+    const id = element.props.id;
+    if (id) {
+      return `<${type} id="${id}" />`;
+    }
+    return `<${type} />`;
+  }
+
+  const tagName = element.tagName.toLowerCase();
+  const dataUIName = element.getAttribute("data-ui-name");
+  if (dataUIName) {
+    return `${tagName}[data-ui-name="${dataUIName}"]`;
+  }
+  const elementId = element.id;
+  if (elementId) {
+    return `${tagName}#${elementId}`;
+  }
+  const className = element.className;
+  if (className) {
+    return `${tagName}.${className.split(" ").join(".")}`;
+  }
+
+  const parentSignature = getElementSignature(element.parentElement);
+  return `${parentSignature} > ${tagName}`;
+};

package/src/interaction/drag/drag_constraint.js

@@ -1,8 +1,8 @@
+import { getElementSignature } from "../../element_signature.js";
 import {
   addScrollToRect,
   getScrollRelativeRect,
 } from "../../position/dom_coords.js";
-import { getElementSelector } from "../element_log.js";
 import { setupConstraintFeedbackLine } from "./constraint_feedback_line.js";
 import { setupDragDebugMarkers } from "./drag_debug_markers.js";
 
@@ -333,7 +333,7 @@ const createObstacleConstraintsFromQuerySelector = (
 
         // obstacleBounds are already in scrollable-relative coordinates, no conversion needed
         const obstacleObject = createObstacleContraint(obstacleBounds, {
-          name: `${obstacleBounds.isSticky ? "sticky " : ""}obstacle (${getElementSelector(obstacle)})`,
+          name: `${obstacleBounds.isSticky ? "sticky " : ""}obstacle (${getElementSignature(obstacle)})`,
           element: obstacle,
         });
         return obstacleObject;

package/src/interaction/drag/sticky_frontiers.js

@@ -1,5 +1,5 @@
+import { getElementSignature } from "../../element_signature.js";
 import { getScrollRelativeRect } from "../../position/dom_coords.js";
-import { getElementSelector } from "../element_log.js";
 
 export const applyStickyFrontiersToAutoScrollArea = (
   autoScrollArea,
@@ -127,9 +127,9 @@ const createStickyFrontierOnAxis = (
     const hasOpposite = frontier.hasAttribute(oppositeAttrName);
     // Check if element has both sides (invalid)
     if (hasPrimary && hasOpposite) {
-      const elementSelector = getElementSelector(frontier);
+      const elementSignature = getElementSignature(frontier);
       console.warn(
-        `Sticky frontier element (${elementSelector}) has both ${primarySide} and ${oppositeSide} attributes. 
+        `Sticky frontier element (${elementSignature}) has both ${primarySide} and ${oppositeSide} attributes. 
   A sticky frontier should only have one side attribute.`,
       );
       continue;
@@ -152,7 +152,7 @@ const createStickyFrontierOnAxis = (
       element: frontier,
       side: hasPrimary ? primarySide : oppositeSide,
       bounds: frontierBounds,
-      name: `sticky_frontier_${hasPrimary ? primarySide : oppositeSide} (${getElementSelector(frontier)})`,
+      name: `sticky_frontier_${hasPrimary ? primarySide : oppositeSide} (${getElementSignature(frontier)})`,
     };
     matchingStickyFrontiers.push(stickyFrontierObject);
   }

package/src/style/style_composition.js

@@ -33,6 +33,29 @@ export const mergeStyles = (stylesA, stylesB, context = "js") => {
   return result;
 };
 
+export const appendStyles = (
+  stylesAObject,
+  stylesBNormalized,
+  context = "js",
+) => {
+  const aKeys = Object.keys(stylesAObject);
+  const bKeys = Object.keys(stylesBNormalized);
+  for (const bKey of bKeys) {
+    const aHasKey = aKeys.includes(bKey);
+    if (aHasKey) {
+      stylesAObject[bKey] = mergeOneStyle(
+        stylesAObject[bKey],
+        stylesBNormalized[bKey],
+        bKey,
+        context,
+      );
+    } else {
+      stylesAObject[bKey] = stylesBNormalized[bKey];
+    }
+  }
+  return stylesAObject;
+};
+
 // Merge a single style property value with an existing value
 export const mergeOneStyle = (
   existingValue,

package/src/style/style_parsing.js

@@ -151,6 +151,9 @@ const normalizeNumber = (value, context, unit, propertyName) => {
 
 // Normalize styles for DOM application
 export const normalizeStyles = (styles, context = "js") => {
+  if (!styles) {
+    return {};
+  }
   if (typeof styles === "string") {
     styles = parseStyleString(styles);
     return styles;

package/src/ui_transition/ui_transition.js

@@ -41,6 +41,7 @@
  * - Independent content updates in the slot without affecting ongoing animations
  */
 
+import { getElementSignature } from "../element_signature.js";
 import { getHeight } from "../size/get_height.js";
 import { getInnerWidth } from "../size/get_inner_width.js";
 import { getWidth } from "../size/get_width.js";
@@ -461,7 +462,7 @@ export const initUITransition = (container) => {
       debug(
         "transition",
         `Cloned previous child for ${isPhaseTransition ? "phase" : "content"} transition:`,
-        previousChild.getAttribute("data-ui-name") || "unnamed",
+        getElementSignature(previousChild),
       );
       cleanup = () => oldChild.remove();
     } else {
@@ -513,7 +514,7 @@ export const initUITransition = (container) => {
       if (localDebug.transition) {
         const updateLabel =
           childUIName ||
-          (firstChild ? "data-ui-name not specified" : "cleared/empty");
+          (firstChild ? getElementSignature(firstChild) : "cleared/empty");
         console.group(`UI Update: ${updateLabel} (reason: ${reason})`);
       }
 
@@ -1117,7 +1118,7 @@ export const initUITransition = (container) => {
           debug(
             "transition",
             `Attribute change detected: ${attributeName} on`,
-            target.getAttribute("data-ui-name") || "element",
+            getElementSignature(target),
           );
         }
       }

package/src/value_effect.js

@@ -1,21 +1,25 @@
 export const createValueEffect = (value) => {
   const callbackSet = new Set();
-  const previousValueCleanupSet = new Set();
+  const valueCleanupSet = new Set();
+
+  const cleanup = () => {
+    for (const valueCleanup of valueCleanupSet) {
+      valueCleanup();
+    }
+    valueCleanupSet.clear();
+  };
 
   const updateValue = (newValue) => {
     if (newValue === value) {
       return;
     }
-    for (const cleanup of previousValueCleanupSet) {
-      cleanup();
-    }
-    previousValueCleanupSet.clear();
+    cleanup();
     const oldValue = value;
     value = newValue;
     for (const callback of callbackSet) {
       const returnValue = callback(newValue, oldValue);
       if (typeof returnValue === "function") {
-        previousValueCleanupSet.add(returnValue);
+        valueCleanupSet.add(returnValue);
       }
     }
   };
@@ -27,5 +31,5 @@ export const createValueEffect = (value) => {
     };
   };
 
-  return [updateValue, addEffect];
+  return [updateValue, addEffect, cleanup];
 };

package/src/interaction/element_log.js

@@ -1,8 +0,0 @@
-export const getElementSelector = (element) => {
-  const tagName = element.tagName.toLowerCase();
-  const id = element.id ? `#${element.id}` : "";
-  const className = element.className
-    ? `.${element.className.split(" ").join(".")}`
-    : "";
-  return `${tagName}${id}${className}`;
-};