@jsenv/dom 0.14.3 → 0.14.5

package/dist/jsenv_dom.js

@@ -208,7 +208,7 @@ const dispatchInternalCustomEvent = (
   customEventDetail,
 ) => {
   const customEvent = new CustomEvent(customEventName, {
-    detail: customEventDetail,
+    detail: customEventDetail || {},
     cancelable: true,
   });
   chainEvent(customEvent, customEventDetail?.event);
@@ -225,7 +225,7 @@ const dispatchPublicCustomEvent = (
   customEventDetail,
 ) => {
   const customEvent = new CustomEvent(customEventName, {
-    detail: customEventDetail,
+    detail: customEventDetail || {},
     bubbles: true,
     cancelable: true,
   });
@@ -241,7 +241,7 @@ const dispatchPublicCustomEvent = (
  */
 const dispatchCustomEvent = (el, customEventName, customEventDetail) => {
   const customEvent = new CustomEvent(customEventName, {
-    detail: customEventDetail,
+    detail: customEventDetail || {},
     cancelable: true,
   });
   chainEvent(customEvent, customEventDetail?.event);
@@ -253,6 +253,12 @@ const chainEvent = (customEvent, parentEvent) => {
   if (!parentEvent) {
     return customEvent;
   }
+  if (!customEvent.detail) {
+    console.warn(
+      `Event "${customEvent.type}" has no detail object. Cannot chain to parent event "${parentEvent.type}".`,
+    );
+    return customEvent;
+  }
   // Always build eventChain from the first wrapping so callers can rely on it
   // being present whenever `parentEvent` is set.
   // eventChain = [oldest, ..., parentEvent] — the full ancestor list including the direct parent.
@@ -316,15 +322,15 @@ const formatEventSideEffect = (e, sideEffect) => {
     const chain = e.detail.eventChain;
     const initiator = chain[0];
     parts.push(
-      `"${initiator.type}" on ${getElementSignature(initiator.target)}`,
+      `"${getEventLabel(initiator)}" on ${getElementSignature(initiator.target)}`,
     );
     // chain[0] is shown as initiator above; chain includes event as last element
     for (const chainedEvent of chain.slice(1)) {
-      parts.push(chainedEvent.type);
+      parts.push(getEventLabel(chainedEvent));
     }
-    parts.push(e.type);
+    parts.push(getEventLabel(e));
   } else {
-    parts.push(`"${e.type}" on ${getElementSignature(e.target)}`);
+    parts.push(`"${getEventLabel(e)}" on ${getElementSignature(e.target)}`);
   }
   return `${parts.join(" -> ")} -> ${sideEffect}`;
 };
@@ -374,8 +380,8 @@ const createEventGroupLogger = () => {
         console.groupEnd();
       }
       const label = initiator.target
-        ? `"${initiator.type}" on ${getElementSignature(initiator.target)}`
-        : `"${initiator.type}"`;
+        ? `"${getEventLabel(initiator)}" on ${getElementSignature(initiator.target)}`
+        : `"${getEventLabel(initiator)}"`;
       console.group(label);
       currentInitiator = initiator;
     }
@@ -400,12 +406,40 @@ const formatSideEffectLine = (e, prefix) => {
     // chain[0] is the root event, already shown as the group label — skip it.
     // chain includes the direct parent (e.detail.event) as its last element.
     for (const chainedEvent of chain.slice(1)) {
-      parts.push(chainedEvent.type);
+      parts.push(getEventLabel(chainedEvent));
     }
   }
   return parts.join(" -> ");
 };
 
+const getEventLabel = (e) => {
+  if (e.type === "mousedown" || e.type === "click") {
+    if (e.button !== 0) {
+      return `${e.type}:right_button`;
+    }
+    return e.type;
+  }
+  if (e.type === "keydown") {
+    const key = e.key === " " ? "space" : e.key?.toLowerCase();
+    const modifiers = [];
+    if (e.ctrlKey) {
+      modifiers.push("ctrl");
+    }
+    if (e.metaKey) {
+      modifiers.push("meta");
+    }
+    if (e.altKey) {
+      modifiers.push("alt");
+    }
+    if (e.shiftKey) {
+      modifiers.push("shift");
+    }
+    modifiers.push(key);
+    return `keydown:${modifiers.join("+")}`;
+  }
+  return e.type;
+};
+
 const createIterableWeakSet = () => {
   const objectWeakRefSet = new Set();
 
@@ -473,6 +507,15 @@ const createIterableWeakSet = () => {
   };
 };
 
+/**
+ * Creates a simple publish/subscribe pair.
+ *
+ * @param {boolean} [clearOnPublish=false] - When true, all subscribers are removed after each publish call.
+ * @returns {[publish: (...args: any[]) => any[], subscribe: (callback: Function) => () => void, clear: () => void]}
+ *   - `publish(...args)` — calls all subscribers with the given arguments and returns their return values.
+ *   - `subscribe(callback)` — registers a subscriber and returns an unsubscribe function.
+ *   - `clear()` — removes all subscribers without calling them.
+ */
 const createPubSub = (clearOnPublish = false) => {
   const callbackSet = new Set();
 
@@ -4328,10 +4371,7 @@ const elementIsFocusable = (node, { excludeAriaHidden } = {}) => {
     }
     return canFocus(node);
   }
-  if (
-    ["button", "select", "datalist", "iframe", "textarea"].indexOf(nodeName) >
-    -1
-  ) {
+  if (FOCUSABLE_NODE_NAME_SET.has(nodeName)) {
     return canFocus(node);
   }
   if (["a", "area"].indexOf(nodeName) > -1) {
@@ -4357,6 +4397,14 @@ const elementIsFocusable = (node, { excludeAriaHidden } = {}) => {
   }
   return false;
 };
+const FOCUSABLE_NODE_NAME_SET = new Set([
+  "button",
+  "select",
+  "datalist",
+  "dialog",
+  "iframe",
+  "textarea",
+]);
 
 const canInteract = (element) => {
   if (element.disabled) {
@@ -4554,7 +4602,13 @@ const DEFAULT_BEHAVIORS = [
   {
     test: (el) => el.matches("input[type='radio'], input[type='checkbox']"),
     keys: {
-      space: "activate",
+      space: (e) => {
+        if (e.target.type === "radio" && e.target.checked) {
+          // space on checked radio does nothing
+          return "";
+        }
+        return "activate";
+      },
       enter: (e) => (e.target.form ? "form_submit" : ""),
       arrowleft: "focus_nav",
       arrowright: "focus_nav",
@@ -4570,17 +4624,20 @@ const DEFAULT_BEHAVIORS = [
     keys: {
       escape: (e) => {
         if (e.target.type === "search") {
+          if (e.target.readOnly) {
+            return "";
+          }
           return e.target.value ? "clear" : "";
         }
         return "";
       },
       enter: (e) => (e.target.form ? "form_submit" : ""),
-      arrowleft: "cursor_move",
-      arrowright: "cursor_move",
-      arrowup: "cursor_move",
-      arrowdown: "cursor_move",
-      home: "cursor_move",
-      end: "cursor_move",
+      arrowleft: (e) => (e.target.readOnly ? "scroll" : "cursor_move"),
+      arrowright: (e) => (e.target.readOnly ? "scroll" : "cursor_move"),
+      arrowup: (e) => (e.target.readOnly ? "scroll" : "cursor_move"),
+      arrowdown: (e) => (e.target.readOnly ? "scroll" : "cursor_move"),
+      home: (e) => (e.target.readOnly ? "scroll" : "cursor_move"),
+      end: (e) => (e.target.readOnly ? "scroll" : "cursor_move"),
     },
     fallback: (e) => (isTypingIntent(e) ? "type" : undefined),
   },
@@ -4619,7 +4676,7 @@ const DEFAULT_BEHAVIORS = [
       ),
     keys: {
       space: "activate",
-      enter: (e) => (e.target.form ? "form_submit" : ""),
+      enter: "activate",
       arrowleft: "value_change",
       arrowright: "value_change",
       arrowup: "value_change",
@@ -4627,19 +4684,19 @@ const DEFAULT_BEHAVIORS = [
     },
   },
   {
-    // Color input: Space opens the color picker, Enter submits the form
+    // Color input: Space opens the color picker, Enter  too
     test: (el) => el.matches("input[type='color']"),
     keys: {
       space: "activate",
-      enter: (e) => (e.target.form ? "form_submit" : ""),
+      enter: "activate",
     },
   },
   {
-    // File input: Space opens the picker, Enter submits the form
+    // File input: Space opens the picker, Enter too
     test: (el) => el.matches("input[type='file']"),
     keys: {
       space: "activate",
-      enter: (e) => (e.target.form ? "form_submit" : ""),
+      enter: "activate",
     },
   },
   {
@@ -4686,7 +4743,10 @@ const DEFAULT_BEHAVIORS = [
   {
     // SELECT: don't intercept anything while the dropdown may be open
     test: (el) => el.tagName === "SELECT",
-    keys: {},
+    keys: {
+      space: "activate",
+      enter: "activate",
+    },
   },
   {
     // Non-interactive elements: browser scrolls on Space and arrow keys
@@ -11517,9 +11577,19 @@ const visibleRectEffect = (
  * @param {HTMLElement} anchor - The anchor element to position against
  * @param {object} [options]
  * @param {string} [options.positionX="center"] - Preferred X placement, with viewport fallback.
+ *   "to-the-left"   — element.right  = anchor.left   (sits entirely to the left of anchor)
+ *   "left-aligned"  — element.left   = anchor.left   (left edges aligned)
+ *   "center"        — element centered horizontally over anchor  (default)
+ *   "right-aligned" — element.right  = anchor.right  (right edges aligned)
+ *   "to-the-right"  — element.left   = anchor.right  (sits entirely to the right of anchor)
  * @param {string} [options.positionY="below"] - Preferred Y placement, with viewport fallback.
- * @param {string} [options.positionXFixed] - Force X placement, skipping the fit-check.
- * @param {string} [options.positionYFixed] - Force Y placement, skipping the fit-check.
+ *   "above"         — element.bottom = anchor.top    (sits above, no overlap)
+ *   "above-overlap" — element.bottom = anchor.bottom (sits above, overlapping anchor)
+ *   "center"        — element centered vertically over anchor
+ *   "below-overlap" — element.top    = anchor.top    (sits below, overlapping anchor)
+ *   "below"         — element.top    = anchor.bottom (sits below, no overlap)  (default)
+ * @param {string} [options.positionXFixed] - Force X placement, skipping the fit-check. Same values as positionX.
+ * @param {string} [options.positionYFixed] - Force Y placement, skipping the fit-check. Same values as positionY.
  * @param {number} [options.alignToViewportEdgeWhenAnchorNearEdge=0] - Snap to viewport left
  *   edge when anchor is within this many px of the left edge and element is wider than anchor.
  * @param {number} [options.minLeft=0] - Minimum left coordinate (document-relative).
@@ -15107,4 +15177,4 @@ const useResizeStatus = (elementRef, { as = "number" } = {}) => {
   };
 };
 
-export { EASING, activeElementSignal, addActiveElementEffect, addAttributeEffect, allowWheelThrough, appendStyles, captureScrollState, chainEvent, contrastColor, createBackgroundColorTransition, createBackgroundTransition, createBorderRadiusTransition, createBorderTransition, createDragGestureController, createDragToMoveGestureController, createEventGroupLogger, createGroupTransitionController, createHeightTransition, createIterableWeakSet, createOpacityTransition, createPubSub, createStyleController, createTimelineTransition, createTransition, createTranslateXTransition, createValueEffect, createWidthTransition, cubicBezier, dispatchCustomEvent, dispatchInternalCustomEvent, dispatchPublicCustomEvent, dragAfterThreshold, elementIsFocusable, elementIsVisibleForFocus, elementIsVisuallyVisible, findAfter, findAncestor, findBefore, findDescendant, findEvent, findFocusDelegateTarget, findFocusable, formatEventSideEffect, getAvailableHeight, getAvailableWidth, getBackground, getBackgroundColor, getBorder, getBorderRadius, getBorderSizes, getContrastRatio, getDefaultStyles, getDragCoordinates, getDropTargetInfo, getElementSignature, getFirstVisuallyVisibleAncestor, getFocusVisibilityInfo, getHeight, getHeightWithoutTransition, getInnerHeight, getInnerWidth, getKeyboardEventDefaultAction, getLuminance, getMarginSizes, getMaxHeight, getMaxWidth, getMinHeight, getMinWidth, getOpacity, getOpacityWithoutTransition, getPaddingSizes, getPositionedParent, getPreferedColorScheme, getScrollBox, getScrollContainer, getScrollContainerSet, getScrollRelativeRect, getSelfAndAncestorScrolls, getStyle, getTranslateX, getTranslateXWithoutTransition, getTranslateY, getVisuallyVisibleInfo, getWidth, getWidthWithoutTransition, hasCSSSizeUnit, initFlexDetailsSet, initFocusGroup, initPositionSticky, isSameColor, isScrollable, measureLongestVisualLineWidth, measureScrollbar, measureWidestChildRow, mergeOneStyle, mergeTwoStyles, normalizeKeyboardKey, normalizeStyle, normalizeStyles, parseStyle, pickPositionRelativeTo, prefersDarkColors, prefersLightColors, preventFocusNav, preventFocusNavViaKeyboard, preventIntermediateScrollbar, resolveCSSColor, resolveCSSSize, resolveColorLuminance, resolveOklchLightness, scrollIntoViewScoped, scrollIntoViewWithStickyAwareness, setAttribute, setAttributes, setStyles, snapToPixel, startDragToReorder, startDragToResizeGesture, stickyAsRelativeCoords, stringifyStyle, trapFocusInside, trapScrollInside, useActiveElement, useAvailableHeight, useAvailableWidth, useMaxHeight, useMaxWidth, useResizeStatus, visibleRectEffect };
+export { EASING, activeElementSignal, addActiveElementEffect, addAttributeEffect, allowWheelThrough, appendStyles, captureScrollState, chainEvent, contrastColor, createBackgroundColorTransition, createBackgroundTransition, createBorderRadiusTransition, createBorderTransition, createDragGestureController, createDragToMoveGestureController, createEventGroupLogger, createGroupTransitionController, createHeightTransition, createIterableWeakSet, createOpacityTransition, createPubSub, createStyleController, createTimelineTransition, createTransition, createTranslateXTransition, createValueEffect, createWidthTransition, cubicBezier, dispatchCustomEvent, dispatchInternalCustomEvent, dispatchPublicCustomEvent, dragAfterThreshold, elementIsFocusable, elementIsVisibleForFocus, elementIsVisuallyVisible, findAfter, findAncestor, findBefore, findDescendant, findEvent, findFocusDelegateTarget, findFocusable, formatEventSideEffect, getAvailableHeight, getAvailableWidth, getBackground, getBackgroundColor, getBorder, getBorderRadius, getBorderSizes, getContrastRatio, getDefaultStyles, getDragCoordinates, getDropTargetInfo, getElementSignature, getFirstVisuallyVisibleAncestor, getFocusVisibilityInfo, getHeight, getHeightWithoutTransition, getInnerHeight, getInnerWidth, getKeyboardEventDefaultAction, getLuminance, getMarginSizes, getMaxHeight, getMaxWidth, getMinHeight, getMinWidth, getOpacity, getOpacityWithoutTransition, getPaddingSizes, getPositionedParent, getPreferedColorScheme, getScrollBox, getScrollContainer, getScrollContainerSet, getScrollRelativeRect, getSelfAndAncestorScrolls, getStyle, getTranslateX, getTranslateXWithoutTransition, getTranslateY, getVisuallyVisibleInfo, getWidth, getWidthWithoutTransition, hasCSSSizeUnit, initFlexDetailsSet, initFocusGroup, initPositionSticky, isSameColor, isScrollable, measureLongestVisualLineWidth, measureScrollbar, measureWidestChildRow, mergeOneStyle, mergeTwoStyles, normalizeKeyboardKey, normalizeStyle, normalizeStyles, parseStyle, performTabNavigation, pickPositionRelativeTo, prefersDarkColors, prefersLightColors, preventFocusNav, preventFocusNavViaKeyboard, preventIntermediateScrollbar, resolveCSSColor, resolveCSSSize, resolveColorLuminance, resolveOklchLightness, scrollIntoViewScoped, scrollIntoViewWithStickyAwareness, setAttribute, setAttributes, setStyles, snapToPixel, startDragToReorder, startDragToResizeGesture, stickyAsRelativeCoords, stringifyStyle, trapFocusInside, trapScrollInside, useActiveElement, useAvailableHeight, useAvailableWidth, useMaxHeight, useMaxWidth, useResizeStatus, visibleRectEffect };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsenv/dom",
-  "version": "0.14.3",
+  "version": "0.14.5",
   "type": "module",
   "description": "DOM utilities for writing frontend code",
   "repository": {