@jsenv/dom 0.17.36 → 0.17.38

package/dist/jsenv_dom.js

@@ -7524,6 +7524,29 @@ const getScrollbarState = (
  * @param {"start"|"center"|"end"|"nearest"} [options.inline="nearest"] - Horizontal alignment.
  */
 const scrollIntoViewScoped = (
+  el,
+  { container = getScrollContainer(el), ...rest } = {},
+) => {
+  if (!container) {
+    return;
+  }
+  container.scrollTo(
+    getScrollIntoViewScopedOffsets(el, { container, ...rest }),
+  );
+};
+
+/**
+ * Where the container would have to be scrolled for `el` to be in view — the
+ * measure scrollIntoViewScoped acts on, handed out on its own for whoever must
+ * stand BETWEEN two such answers rather than land on one: a row of tabs
+ * scrolled the same fraction of the way as the slides it names are travelling
+ * (see navi's <Nav>).
+ *
+ * @param {Element} el
+ * @param {object} options - the same as scrollIntoViewScoped's.
+ * @returns {{left: number, top: number}}
+ */
+const getScrollIntoViewScopedOffsets = (
   el,
   {
     container = getScrollContainer(el),
@@ -7531,10 +7554,6 @@ const scrollIntoViewScoped = (
     inline = "nearest",
   } = {},
 ) => {
-  if (!container) {
-    return;
-  }
-
   const containerRect = container.getBoundingClientRect();
   const elRect = el.getBoundingClientRect();
   const style = getComputedStyle(el);
@@ -7609,10 +7628,10 @@ const scrollIntoViewScoped = (
     }
   }
 
-  container.scrollTo({
+  return {
     left: newScrollLeft,
     top: newScrollTop,
-  });
+  };
 };
 
 /**
@@ -13401,18 +13420,78 @@ const DRAG_FLICK_DISTANCE = 8;
 // way. Let go and it comes back — a wall one can lean on, never walk through.
 const DRAG_RESISTANCE = 0.3;
 
-// What a drag must not start on: something that reads the pointer itself, whole,
-// with no axis left to share. A button or a link is not in the list — dragging
-// from one travels, and the click it would have made is swallowed on the way
-// out. A drag SOURCE is not either: it says which way it goes and only takes
-// that (see DRAG_SOURCE_AXES_ATTRIBUTE) — but a dedicated handle is, being a
-// place whose only purpose is to be taken hold of, from the first pixel. And so
-// is an element naming `drag` among its own interactions: it said the grab is
-// ITS, here, rather than the box's — and one that named only the click said
-// nothing to this gesture and is passed through (see DRAG_IGNORED_SELECTOR in
-// drag_to.js). And so is a popover or a dialog: a layer OVER the box, whose
-// press only bubbles through the box because the layer is anchored in it.
-const DRAG_EXCLUDED_SELECTOR = ["input", "textarea", "select", '[contenteditable=""]', '[contenteditable="true"]', "[data-drag-handle]", "[data-no-drag-travel]", '[data-self-interactions~="drag"]', '[data-self-interactions~="*"]', "[popover]", "dialog"].join(",");
+// The gestures a browser ALREADY answers where a pointer goes down, named here
+// rather than guessed at from a tag: what is native is the whole reason a travel
+// must not start there. A caret dragged through text, a thumb pushed along its
+// rail, a menu fed by everything that follows the press — taking the press from
+// one of those takes away something the element cannot offer a second time, and
+// a travel is never worth that.
+//
+// What is NOT in the list has nothing to lose. A button or a link is out on
+// purpose: dragging from one travels, and the click it would have made is
+// swallowed on the way out. So are the inputs that read the press and nothing
+// after it (a checkbox, a radio, a colour, a file) — buttons by another name.
+// Which matters more than it looks: a selectable row is covered by an invisible
+// radio of its own, so excluding every input at once means a list of rows inside
+// a travelling box that no finger can push.
+//
+// Every entry answers "never", and the entry is where a softer answer would be
+// written if one turned out to be worth it — per hand, since that is where these
+// gestures differ. The one that comes to mind is a travel a MOUSE could still
+// ask for by holding still first, a hold meaning nothing to a mouse in a text
+// field: it is not here because the browser has already begun a selection at the
+// press, and nothing hands that back mid-gesture — the travel would drag a
+// selection along with it. With a finger the hold is the selection UI itself, so
+// there is nothing to take there either.
+const PRESSED_INPUT_TYPES = ['[type="checkbox"]', '[type="radio"]', '[type="button"]', '[type="submit"]', '[type="reset"]', '[type="image"]', '[type="color"]', '[type="file"]'].join(",");
+const NATIVE_POINTER_GESTURES = [{
+  // The value follows the pointer, pixel by pixel: a thumb along its rail, a
+  // spinner clicked up and down. There is no moment in that which could be
+  // given away — the gesture IS the pointer.
+  selector: 'input[type="range"],input[type="number"]'
+}, {
+  // The text answers the pointer, and differently per hand: a mouse drags a
+  // caret through it (a selection), a finger drags the field's own content
+  // sideways when it overflows, and a finger held still opens the selection
+  // UI. Three things a field is for, against one travel that has a whole box
+  // to start from.
+  selector: [`input:not(${PRESSED_INPUT_TYPES},[type="range"],[type="number"])`, "textarea", '[contenteditable=""]', '[contenteditable="true"]'].join(",")
+}, {
+  // A menu opens under the pointer and the browser keeps the rest of the
+  // gesture: dragged over, it picks an option.
+  selector: "select"
+}];
+
+// …and what an element says against its own tag. Every line above is about what
+// an element DOES, and a tag only says what it IS: a picker's façade is an
+// <input> that opens a popup on the press and reads nothing at all as the
+// pointer moves (it selects its own text on mousedown, and that is the whole of
+// it). Only the element knows that, so only the element can say it — and having
+// said it, it is a button by another name like the others, and a travel starts
+// there like anywhere else.
+//
+// Said rather than found, and said on the element the pointer lands on: a
+// promise about a gesture has to be readable before the gesture exists, from
+// nothing but the DOM under the finger. And it is a promise: an element that
+// says it while the browser still answers the pointer there (a range, a field
+// that can really be typed in) has not made a travel possible, it has taken the
+// gesture the user was making away from them.
+const PRESS_ONLY_ATTRIBUTE = "data-press-only";
+const NATIVE_POINTER_GESTURE_SELECTOR = NATIVE_POINTER_GESTURES.map(({
+  selector
+}) => `:is(${selector}):not([${PRESS_ONLY_ATTRIBUTE}])`).join(",");
+
+// What a drag must not start on: what answers the pointer natively (above),
+// plus what has said the gesture is its own. A drag SOURCE is not in the list:
+// it says which way it goes and only takes that (see DRAG_SOURCE_AXES_ATTRIBUTE)
+// — but a dedicated handle is, being a place whose only purpose is to be taken
+// hold of, from the first pixel. And so is an element naming `drag` among its
+// own interactions: it said the grab is ITS, here, rather than the box's — and
+// one that named only the click said nothing to this gesture and is passed
+// through (see DRAG_IGNORED_SELECTOR in drag_to.js). And so is a popover or a
+// dialog: a layer OVER the box, whose press only bubbles through the box because
+// the layer is anchored in it.
+const DRAG_EXCLUDED_SELECTOR = [NATIVE_POINTER_GESTURE_SELECTOR, "[data-drag-handle]", "[data-no-drag-travel]", '[data-self-interactions~="drag"]', '[data-self-interactions~="*"]', "[popover]", "dialog"].join(",");
 
 // Which axes a box travels on, one attribute per gesture, said in the DOM by
 // whoever owns the box: it is what a box ABOVE another reads to know the
@@ -14198,6 +14277,42 @@ const isPressExcluded = (target, element) => {
   return Boolean(excluded) && !excluded.contains(element);
 };
 
+/**
+ * Whether a press landing on `element` may become the gesture of something
+ * around it — a box that travels by drag, an object carried out of a list. Or
+ * of the element itself, when the element is that box: the gesture is still one
+ * the press is being asked for.
+ *
+ * The question a control that acts ON THE PRESS has to ask before it acts: a
+ * picker opening its popup at the pointerdown, the way a native select does,
+ * is right only while nothing else disputes that press. Where a box above
+ * travels, the finger going down is the beginning of something that is not yet
+ * a choice — answering there both answers for a user who has chosen nothing and
+ * takes the press from a gesture that could then never form. What such a control
+ * does instead is wait for the click, which the browser only delivers if the
+ * press stayed a press: a gesture swallows the one it leaves behind.
+ *
+ * Asked of the DOM at the press rather than worked out at render, because that
+ * is where the answer lives: the box above says what it travels by
+ * (DRAG_AXES_ATTRIBUTE, DRAG_SOURCE_AXES_ATTRIBUTE), and whether the press is
+ * takeable at all is the same question the gesture itself asks a moment later —
+ * a field the travel would never have started on disputes nothing, and a control
+ * inside one goes on acting on the press.
+ *
+ * @param {Element} element Where the press landed.
+ * @returns {boolean}
+ */
+const isPressDisputedByDrag = element => {
+  if (!element || typeof element.closest !== "function") {
+    return false;
+  }
+  const dragged = element.closest(`[${DRAG_AXES_ATTRIBUTE}],[${DRAG_SOURCE_AXES_ATTRIBUTE}]`);
+  if (!dragged) {
+    return false;
+  }
+  return !isPressExcluded(element, dragged);
+};
+
 // Shared by navi's own use_displayed_layout_effect.js (rich "navi_displayed"
 // CustomEvent, open transitions only) and visible_rect.js (needs both
 // directions: hide when a container closes, recheck when it reopens) — the
@@ -20059,4 +20174,4 @@ const useResizeStatus = (elementRef, { as = "number" } = {}) => {
   };
 };
 
-export { EASING, ELEMENT_SIZE_CHANGE, activeElementSignal, addActiveElementEffect, addAttributeEffect, allowWheelThrough, appendStyles, applyNewPosition, canScroll, captureScrollState, chainEvent, claimWheelGesture, clickIsSuppressed, closestOpenableAncestor, contrastColor, createBackgroundColorTransition, createBackgroundTransition, createBorderRadiusTransition, createBorderTransition, createDragGestureController, createDragToMoveGestureController, createEventGroupLogger, createGroupTransitionController, createHeightTransition, createIterableWeakSet, createOpacityTransition, createPubSub, createStyleController, createTimelineTransition, createTransition, createTranslateXTransition, createValueEffect, createWidthTransition, cubicBezier, dispatchCustomEvent, dispatchInternalCustomEvent, dispatchPublicCustomEvent, dragAfterIntent, elementIsFocusable, elementIsVisibleForFocus, elementIsVisuallyVisible, findAfter, findAncestor, findBefore, findDescendant, findEvent, findFocusDelegateTarget, findFocusable, findSelfOrAncestorFixedPosition, formatEventSideEffect, getAncestorOpenType, 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, getPositioningScrollOffset, getPreferedColorScheme, getScrollBox, getScrollContainer, getScrollContainerSet, getScrollRelativeRect, getSelfAndAncestorScrolls, getStyle, getTranslateX, getTranslateXWithoutTransition, getTranslateY, getVirtualKeyboardOverlayHeight, getVisuallyVisibleInfo, getWidth, getWidthWithoutTransition, hasCSSSizeUnit, initFlexDetailsSet, initFocusGroup, initPositionSticky, isAncestorOpen, isDisplayedDespiteClosedAncestor, isPrimaryButtonEvent, isSameColor, isScrollable, isTouchDrivenEvent, markDragSource, measureLongestVisualLineWidth, measureScrollbar, measureWidestChildRow, mergeOneStyle, mergeTwoStyles, normalizeKeyboardKey, normalizeStyle, normalizeStyles, observeAncestorOpenState, onAncestorReopen, parsePositionArea, parseStyle, performTabNavigation, pickPositionRelativeTo, prefersDarkColors, prefersLightColors, preventFocusNav, preventFocusNavViaKeyboard, preventIntermediateScrollbar, releaseWheelGesture, resolveCSSColor, resolveCSSSize, resolveColorLuminance, resolveOklchLightness, scrollIntoViewScoped, scrollIntoViewWithStickyAwareness, scrollRoomTowards, setAttribute, setAttributes, setStyles, setVirtualKeyboardOverlaysContent, snapToPixel, startDragTo, startDragToResizeGesture, startDragToTravel, stickyAsRelativeCoords, stringifyStyle, subscribeVirtualKeyboardGeometryChange, subscribeVisualViewportResizeSettled, subscribeWindowResizeSettled, suppressClickAfterGesture, trapFocusInside, trapScrollInside, useActiveElement, useAvailableHeight, useAvailableWidth, useMaxHeight, useMaxWidth, useResizeStatus, visibleRectEffect, waitForPressHeld, watchWheelTravel, wheelGestureIsTakenFrom };
+export { EASING, ELEMENT_SIZE_CHANGE, activeElementSignal, addActiveElementEffect, addAttributeEffect, allowWheelThrough, appendStyles, applyNewPosition, canScroll, captureScrollState, chainEvent, claimWheelGesture, clickIsSuppressed, closestOpenableAncestor, contrastColor, createBackgroundColorTransition, createBackgroundTransition, createBorderRadiusTransition, createBorderTransition, createDragGestureController, createDragToMoveGestureController, createEventGroupLogger, createGroupTransitionController, createHeightTransition, createIterableWeakSet, createOpacityTransition, createPubSub, createStyleController, createTimelineTransition, createTransition, createTranslateXTransition, createValueEffect, createWidthTransition, cubicBezier, dispatchCustomEvent, dispatchInternalCustomEvent, dispatchPublicCustomEvent, dragAfterIntent, elementIsFocusable, elementIsVisibleForFocus, elementIsVisuallyVisible, findAfter, findAncestor, findBefore, findDescendant, findEvent, findFocusDelegateTarget, findFocusable, findSelfOrAncestorFixedPosition, formatEventSideEffect, getAncestorOpenType, 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, getPositioningScrollOffset, getPreferedColorScheme, getScrollBox, getScrollContainer, getScrollContainerSet, getScrollIntoViewScopedOffsets, getScrollRelativeRect, getSelfAndAncestorScrolls, getStyle, getTranslateX, getTranslateXWithoutTransition, getTranslateY, getVirtualKeyboardOverlayHeight, getVisuallyVisibleInfo, getWidth, getWidthWithoutTransition, hasCSSSizeUnit, initFlexDetailsSet, initFocusGroup, initPositionSticky, isAncestorOpen, isDisplayedDespiteClosedAncestor, isPressDisputedByDrag, isPrimaryButtonEvent, isSameColor, isScrollable, isTouchDrivenEvent, markDragSource, measureLongestVisualLineWidth, measureScrollbar, measureWidestChildRow, mergeOneStyle, mergeTwoStyles, normalizeKeyboardKey, normalizeStyle, normalizeStyles, observeAncestorOpenState, onAncestorReopen, parsePositionArea, parseStyle, performTabNavigation, pickPositionRelativeTo, prefersDarkColors, prefersLightColors, preventFocusNav, preventFocusNavViaKeyboard, preventIntermediateScrollbar, releaseWheelGesture, resolveCSSColor, resolveCSSSize, resolveColorLuminance, resolveOklchLightness, scrollIntoViewScoped, scrollIntoViewWithStickyAwareness, scrollRoomTowards, setAttribute, setAttributes, setStyles, setVirtualKeyboardOverlaysContent, snapToPixel, startDragTo, startDragToResizeGesture, startDragToTravel, stickyAsRelativeCoords, stringifyStyle, subscribeVirtualKeyboardGeometryChange, subscribeVisualViewportResizeSettled, subscribeWindowResizeSettled, suppressClickAfterGesture, trapFocusInside, trapScrollInside, useActiveElement, useAvailableHeight, useAvailableWidth, useMaxHeight, useMaxWidth, useResizeStatus, visibleRectEffect, waitForPressHeld, watchWheelTravel, wheelGestureIsTakenFrom };

package/package.json

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