@jsenv/dom 0.1.0

package/src/size/resolve_css_size.js

@@ -0,0 +1,32 @@
+export const resolveCSSSize = (
+  size,
+  { availableSize, fontSize, autoIsRelativeToFont } = {},
+) => {
+  if (typeof size === "string") {
+    if (size === "auto") {
+      return autoIsRelativeToFont ? fontSize : availableSize;
+    }
+    if (size.endsWith("%")) {
+      return availableSize * (parseFloat(size) / 100);
+    }
+    if (size.endsWith("px")) {
+      return parseFloat(size);
+    }
+    if (size.endsWith("em")) {
+      return parseFloat(size) * fontSize;
+    }
+    if (size.endsWith("rem")) {
+      return (
+        parseFloat(size) * getComputedStyle(document.documentElement).fontSize
+      );
+    }
+    if (size.endsWith("vw")) {
+      return (parseFloat(size) / 100) * window.innerWidth;
+    }
+    if (size.endsWith("vh")) {
+      return (parseFloat(size) / 100) * window.innerHeight;
+    }
+    return parseFloat(size);
+  }
+  return size;
+};

package/src/style/dom_styles.js

@@ -0,0 +1,97 @@
+import { elementToOwnerWindow } from "../utils.js";
+
+export const getComputedStyle = (element) =>
+  elementToOwnerWindow(element).getComputedStyle(element);
+
+export const getStyle = (element, name) =>
+  getComputedStyle(element).getPropertyValue(name);
+
+const isCamelCase = (str) => {
+  // Check if string contains lowercase letter followed by uppercase letter (camelCase pattern)
+  return /[a-z][A-Z]/.test(str);
+};
+const kebabCase = (str) => {
+  // Convert camelCase to kebab-case by inserting a hyphen before uppercase letters
+  // and converting the uppercase letter to lowercase
+  return str.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase();
+};
+export const setStyle = (element, name, value) => {
+  if (import.meta.dev) {
+    if (isCamelCase(name)) {
+      console.warn(
+        `setStyle: style name "${name}" should be in kebab-case, not camelCase. Use "${kebabCase(name)}" instead.`,
+      );
+    }
+  }
+
+  const prevValue = element.style[name];
+  if (prevValue) {
+    element.style.setProperty(name, value);
+    return () => {
+      element.style.setProperty(name, prevValue);
+    };
+  }
+  element.style.setProperty(name, value);
+  return () => {
+    element.style.removeProperty(name);
+  };
+};
+export const forceStyle = (element, name, value) => {
+  const inlineStyleValue = element.style[name];
+  if (inlineStyleValue === value) {
+    return () => {};
+  }
+  const computedStyleValue = getStyle(element, name);
+  if (computedStyleValue === value) {
+    return () => {};
+  }
+  const restoreStyle = setStyle(element, name, value);
+  return restoreStyle;
+};
+
+export const addWillChange = (element, property) => {
+  const currentWillChange = element.style.willChange;
+  const willChangeValues = currentWillChange
+    ? currentWillChange
+        .split(",")
+        .map((v) => v.trim())
+        .filter(Boolean)
+    : [];
+
+  if (willChangeValues.includes(property)) {
+    // Property already exists, return no-op
+    return () => {};
+  }
+
+  willChangeValues.push(property);
+  element.style.willChange = willChangeValues.join(", ");
+  // Return function to remove only this property
+  return () => {
+    const newValues = willChangeValues.filter((v) => v !== property);
+    if (newValues.length === 0) {
+      element.style.removeProperty("will-change");
+    } else {
+      element.style.willChange = newValues.join(", ");
+    }
+  };
+};
+
+const createSetMany = (setter) => {
+  return (element, description) => {
+    const cleanupCallbackSet = new Set();
+    for (const name of Object.keys(description)) {
+      const value = description[name];
+      const restoreStyle = setter(element, name, value);
+      cleanupCallbackSet.add(restoreStyle);
+    }
+    return () => {
+      for (const cleanupCallback of cleanupCallbackSet) {
+        cleanupCallback();
+      }
+      cleanupCallbackSet.clear();
+    };
+  };
+};
+
+export const setStyles = createSetMany(setStyle);
+export const forceStyles = createSetMany(forceStyle);

package/src/style/style_composition.js

@@ -0,0 +1,78 @@
+import { parseCSSTransform, stringifyCSSTransform } from "./style_parsing.js";
+
+// Merge two style objects, handling special cases like transform
+export const mergeStyles = (stylesA, stylesB) => {
+  const result = { ...stylesA };
+  for (const key of Object.keys(stylesB)) {
+    if (key === "transform") {
+      result[key] = mergeOneStyle(stylesA[key], stylesB[key], key);
+    } else {
+      result[key] = stylesB[key];
+    }
+  }
+  return result;
+};
+
+// Merge a single style property value with an existing value
+export const mergeOneStyle = (
+  existingValue,
+  newValue,
+  propertyName,
+  context = "js",
+) => {
+  if (propertyName === "transform") {
+    // Matrix parsing is now handled automatically in parseCSSTransform
+
+    // Determine the types
+    const existingIsString =
+      typeof existingValue === "string" && existingValue !== "none";
+    const newIsString = typeof newValue === "string" && newValue !== "none";
+    const existingIsObject =
+      typeof existingValue === "object" && existingValue !== null;
+    const newIsObject = typeof newValue === "object" && newValue !== null;
+
+    // Case 1: Both are objects - merge directly
+    if (existingIsObject && newIsObject) {
+      const merged = { ...existingValue, ...newValue };
+      return context === "css" ? stringifyCSSTransform(merged) : merged;
+    }
+
+    // Case 2: New is object, existing is string - parse existing and merge
+    if (newIsObject && existingIsString) {
+      const parsedExisting = parseCSSTransform(existingValue);
+      const merged = { ...parsedExisting, ...newValue };
+      return context === "css" ? stringifyCSSTransform(merged) : merged;
+    }
+
+    // Case 3: New is string, existing is object - parse new and merge
+    if (newIsString && existingIsObject) {
+      const parsedNew = parseCSSTransform(newValue);
+      const merged = { ...existingValue, ...parsedNew };
+      return context === "css" ? stringifyCSSTransform(merged) : merged;
+    }
+
+    // Case 4: Both are strings - parse both and merge
+    if (existingIsString && newIsString) {
+      const parsedExisting = parseCSSTransform(existingValue);
+      const parsedNew = parseCSSTransform(newValue);
+      const merged = { ...parsedExisting, ...parsedNew };
+      return context === "css" ? stringifyCSSTransform(merged) : merged;
+    }
+
+    // Case 5: New is object, no existing or existing is none/null
+    if (newIsObject) {
+      return context === "css" ? stringifyCSSTransform(newValue) : newValue;
+    }
+
+    // Case 6: New is string, no existing or existing is none/null
+    if (newIsString) {
+      if (context === "css") {
+        return newValue; // Already a string
+      }
+      return parseCSSTransform(newValue); // Convert to object
+    }
+  }
+
+  // For all other properties, simple replacement
+  return newValue;
+};

package/src/style/style_controller.js

@@ -0,0 +1,345 @@
+/**
+ * Style Controller System
+ *
+ * Solves CSS style manipulation problems in JavaScript:
+ *
+ * ## Main problems:
+ * 1. **Temporary style override**: Code wants to read current style, force another style,
+ *    then restore original. With inline styles this is ugly and loses original info.
+ * 2. **Multiple code parts**: When different parts of code want to touch styles simultaneously,
+ *    they step on each other (rare but happens).
+ * 3. **Transform composition**: CSS transforms are especially painful - you want to keep
+ *    existing transforms but force specific parts (e.g., keep `rotate(45deg)` but override
+ *    `translateX`). Native CSS overwrites the entire transform property.
+ *
+ * ## Solution:
+ * Controller pattern + Web Animations API to preserve inline styles. Code that sets
+ * inline styles expects to find them unchanged - we use animations for clean override:
+ *
+ * ```js
+ * const controller = createStyleController("myFeature");
+ *
+ * // Smart value conversion (100 → "100px", 45 → "45deg")
+ * controller.set(element, {
+ *   transform: { translateX: 100, rotate: 45 }, // Individual transform properties
+ *   opacity: 0.5
+ * });
+ *
+ * // Transform objects merged intelligently
+ * controller.set(element, {
+ *   transform: { translateX: 50 } // Merges with existing transforms
+ * });
+ *
+ * // Get underlying value without this controller's influence
+ * const originalOpacity = controller.getUnderlyingValue(element, "opacity");
+ * const originalTranslateX = controller.getUnderlyingValue(element, "transform.translateX"); // Magic dot notation!
+ * const actualWidth = controller.getUnderlyingValue(element, "rect.width"); // Layout measurements
+ *
+ * controller.delete(element, "opacity"); // Only removes opacity, keeps transform
+ * controller.clear(element); // Removes all styles from this controller only
+ * controller.clearAll(); // Cleanup when done
+ * ```
+ *
+ * **Key features:**
+ * - **Transform composition**: Intelligently merges transform components instead of overwriting
+ * - **Magic properties**: Access transform components with dot notation (e.g., "transform.translateX")
+ * - **Layout measurements**: Access actual rendered dimensions with rect.* (e.g., "rect.width")
+ * - **getUnderlyingValue()**: Read the "natural" value without this controller's influence
+ * - **Smart units**: Numeric values get appropriate units automatically (px, deg, unitless)
+ *
+ * **Transform limitations:**
+ * - **3D Transforms**: Complex `matrix3d()` transforms are preserved as-is and cannot be decomposed
+ *   into individual properties. Only `matrix3d()` that represent simple 2D transforms are converted
+ *   to object notation. Magic properties like "transform.rotateX" work only with explicit CSS functions,
+ *   not with complex 3D matrices.
+ *
+ * Multiple controllers can safely manage the same element without conflicts.
+ */
+
+import { mergeOneStyle, mergeStyles } from "./style_composition.js";
+import { normalizeStyle, normalizeStyles } from "./style_parsing.js";
+
+// Global registry to track which controllers are managing each element's styles
+const elementControllerSetRegistry = new WeakMap(); // element -> Set<controller>
+
+// Top-level helpers for controller attachment tracking
+const onElementControllerAdded = (element, controller) => {
+  if (!elementControllerSetRegistry.has(element)) {
+    elementControllerSetRegistry.set(element, new Set());
+  }
+  const elementControllerSet = elementControllerSetRegistry.get(element);
+  elementControllerSet.add(controller);
+};
+const onElementControllerRemoved = (element, controller) => {
+  const elementControllerSet = elementControllerSetRegistry.get(element);
+  if (elementControllerSet) {
+    elementControllerSet.delete(controller);
+
+    // Clean up empty element registry
+    if (elementControllerSet.size === 0) {
+      elementControllerSetRegistry.delete(element);
+    }
+  }
+};
+
+export const createStyleController = (name = "anonymous") => {
+  // Store element data for this controller: element -> { styles, animation }
+  const elementWeakMap = new WeakMap();
+
+  const set = (element, stylesToSet) => {
+    if (!element || typeof element !== "object") {
+      throw new Error("Element must be a valid DOM element");
+    }
+    if (!stylesToSet || typeof stylesToSet !== "object") {
+      throw new Error("styles must be an object");
+    }
+
+    const normalizedStylesToSet = normalizeStyles(stylesToSet, "js");
+    const elementData = elementWeakMap.get(element);
+    if (!elementData) {
+      const animation = createAnimationForStyles(
+        element,
+        normalizedStylesToSet,
+        name,
+      );
+      elementWeakMap.set(element, {
+        styles: normalizedStylesToSet,
+        animation,
+      });
+      onElementControllerAdded(element, controller);
+      return;
+    }
+
+    const { styles, animation } = elementData;
+    const mergedStyles = mergeStyles(styles, normalizedStylesToSet);
+    elementData.styles = mergedStyles;
+    updateAnimationStyles(animation, mergedStyles);
+  };
+
+  const get = (element, propertyName) => {
+    const elementData = elementWeakMap.get(element);
+    if (!elementData) {
+      return undefined;
+    }
+    const { styles } = elementData;
+    if (propertyName === undefined) {
+      return { ...styles };
+    }
+    if (propertyName.startsWith("transform.")) {
+      const transformProp = propertyName.slice("transform.".length);
+      return styles.transform?.[transformProp];
+    }
+    return styles[propertyName];
+  };
+
+  const deleteMethod = (element, propertyName) => {
+    const elementData = elementWeakMap.get(element);
+    if (!elementData) {
+      return;
+    }
+    const { styles, animation } = elementData;
+    const hasStyle = Object.hasOwn(styles, propertyName);
+    if (!hasStyle) {
+      return;
+    }
+    delete styles[propertyName];
+    const isEmpty = Object.keys(styles).length === 0;
+    // Clean up empty controller
+    if (isEmpty) {
+      animation.cancel();
+      elementWeakMap.delete(element);
+      onElementControllerRemoved(element, controller);
+      return;
+    }
+    updateAnimationStyles(animation, styles);
+  };
+
+  const commit = (element) => {
+    const elementData = elementWeakMap.get(element);
+    if (!elementData) {
+      return; // Nothing to commit on this element for this controller
+    }
+    const { styles, animation } = elementData;
+    // Cancel our animation permanently since we're committing styles to inline
+    // (Keep this BEFORE getComputedStyle to prevent computedStyle reading our animation styles)
+    animation.cancel();
+    // Now read the true underlying styles (without our animation influence)
+    const computedStyles = getComputedStyle(element);
+    // Convert controller styles to CSS and commit to inline styles
+    const cssStyles = normalizeStyles(styles, "css");
+    for (const [key, value] of Object.entries(cssStyles)) {
+      // Merge with existing computed styles for all properties
+      const existingValue = computedStyles[key];
+      element.style[key] = mergeOneStyle(existingValue, value, key, "css");
+    }
+    // Clear this controller's styles since they're now inline
+    elementWeakMap.delete(element);
+    // Clean up controller from element registry
+    onElementControllerRemoved(element, controller);
+  };
+
+  const clear = (element) => {
+    const elementData = elementWeakMap.get(element);
+    if (!elementData) {
+      return;
+    }
+    const { animation } = elementData;
+    animation.cancel();
+    elementWeakMap.delete(element);
+    onElementControllerRemoved(element, controller);
+  };
+
+  const getUnderlyingValue = (element, propertyName) => {
+    const elementControllerSet = elementControllerSetRegistry.get(element);
+
+    const normalizeValueForJs = (value) => {
+      // Use normalizeStyle to handle all property types including transform dot notation
+      return normalizeStyle(value, propertyName, "js");
+    };
+
+    const getFromOtherControllers = () => {
+      if (!elementControllerSet || elementControllerSet.size <= 1) {
+        return undefined;
+      }
+
+      let resultValue;
+      for (const otherController of elementControllerSet) {
+        if (otherController === controller) continue;
+        const otherStyles = otherController.get(element);
+        if (propertyName in otherStyles) {
+          resultValue = mergeOneStyle(
+            resultValue,
+            otherStyles[propertyName],
+            propertyName,
+          );
+        }
+      }
+
+      // Note: For CSS width/height properties, we can trust the values from other controllers
+      // because we assume box-sizing: border-box. If the element used content-box,
+      // the CSS width/height would differ from getBoundingClientRect() due to padding/borders,
+      // but since controllers set the final rendered size, the CSS value is what matters.
+      // For actual layout measurements, use rect.* properties instead.
+      return normalizeValueForJs(resultValue);
+    };
+
+    const getFromDOM = () => {
+      // Handle transform dot notation
+      if (propertyName.startsWith("transform.")) {
+        const transformValue = getComputedStyle(element).transform;
+        return normalizeValueForJs(transformValue);
+      }
+      // For all other CSS properties, use computed styles
+      const computedValue = getComputedStyle(element)[propertyName];
+      return normalizeValueForJs(computedValue);
+    };
+
+    const getFromDOMLayout = () => {
+      // For rect.* properties that reflect actual layout, always read from DOM
+      // These represent the actual rendered dimensions, bypassing any controller influence
+      if (propertyName === "rect.width") {
+        return element.getBoundingClientRect().width;
+      }
+      if (propertyName === "rect.height") {
+        return element.getBoundingClientRect().height;
+      }
+      if (propertyName === "rect.left") {
+        return element.getBoundingClientRect().left;
+      }
+      if (propertyName === "rect.top") {
+        return element.getBoundingClientRect().top;
+      }
+      if (propertyName === "rect.right") {
+        return element.getBoundingClientRect().right;
+      }
+      if (propertyName === "rect.bottom") {
+        return element.getBoundingClientRect().bottom;
+      }
+      return undefined;
+    };
+
+    const getWhileDisablingThisController = (fn) => {
+      const elementData = elementWeakMap.get(element);
+      if (!elementData) {
+        return fn();
+      }
+      const { styles, animation } = elementData;
+      // Temporarily cancel our animation to read underlying value
+      animation.cancel();
+      const underlyingValue = fn();
+      // Restore our animation
+      elementData.animation = createAnimationForStyles(element, styles, name);
+      return underlyingValue;
+    };
+
+    if (typeof propertyName === "function") {
+      return getWhileDisablingThisController(propertyName);
+    }
+
+    // Handle computed layout properties (rect.*) - always read from DOM, bypass controllers
+    if (propertyName.startsWith("rect.")) {
+      return getWhileDisablingThisController(getFromDOMLayout);
+    }
+    if (!elementControllerSet || !elementControllerSet.has(controller)) {
+      // This controller is not applied, just read current value
+      return getFromDOM();
+    }
+    // Check if other controllers would provide this style
+    const valueFromOtherControllers = getFromOtherControllers();
+    if (valueFromOtherControllers !== undefined) {
+      return valueFromOtherControllers;
+    }
+    return getWhileDisablingThisController(getFromDOM);
+  };
+
+  const clearAll = () => {
+    // Remove this controller from all elements and clean up animations
+    for (const [
+      element,
+      elementControllerSet,
+    ] of elementControllerSetRegistry) {
+      if (!elementControllerSet.has(controller)) {
+        continue;
+      }
+      const elementData = elementWeakMap.get(element);
+      if (!elementData) {
+        continue;
+      }
+      const { animation } = elementData;
+      animation.cancel();
+      elementWeakMap.delete(element);
+      onElementControllerRemoved(element, controller);
+    }
+  };
+  const controller = {
+    name,
+    set,
+    get,
+    delete: deleteMethod,
+    getUnderlyingValue,
+    commit,
+    clear,
+    clearAll,
+  };
+
+  return controller;
+};
+
+const createAnimationForStyles = (element, styles, id) => {
+  const cssStylesToSet = normalizeStyles(styles, "css");
+  const animation = element.animate([cssStylesToSet], {
+    duration: 0,
+    fill: "forwards",
+  });
+  animation.id = id; // Set a debug name for this animation
+  animation.play();
+  animation.pause();
+  return animation; // Return the created animation
+};
+
+const updateAnimationStyles = (animation, styles) => {
+  const cssStyles = normalizeStyles(styles, "css");
+  animation.effect.setKeyframes([cssStyles]);
+  animation.play();
+  animation.pause();
+};