@jsenv/navi 0.29.194 → 0.29.195

package/dist/jsenv_navi.js

@@ -4,7 +4,7 @@
  */
 import { installImportMetaCssBuild, windowHeightSignal, windowWidthSignal, visualViewportHeightSignal, visualViewportWidthSignal, getAppHeight, getAppWidth, coarsePointerSignal, smallTouchScreenSignal } from "./jsenv_navi_side_effects.js";
 export { disableVirtualKeyboardOverlay } from "./jsenv_navi_side_effects.js";
-import { elementIsFocusable, createIterableWeakSet, dispatchInternalCustomEvent, dispatchCustomEvent, getVisuallyVisibleInfo, getFirstVisuallyVisibleAncestor, getElementSignature, createPubSub, findEvent, createValueEffect, findFocusDelegateTarget, findFocusable, scrollIntoViewThroughScrollables, allowWheelThrough, dispatchPublicCustomEvent, resolveCSSColor, ELEMENT_SIZE_CHANGE, findSelfOrAncestorFixedPosition, visibleRectEffect, pickPositionRelativeTo, getBorderSizes, getPaddingSizes, applyNewPosition, measureLongestVisualLineWidth, chainEvent, keepTouchRefusable, waitForPressHeld, suppressClickAfterGesture, startDragToTravel, markDragSource, startDragTo, createEventGroupLogger, getKeyboardEventDefaultAction, activeElementSignal, normalizeStyle, mergeOneStyle, getPositionedParent, normalizeStyles, createGroupTransitionController, getBorderRadius, preventIntermediateScrollbar, createOpacityTransition, watchWheelTravel, scrollRoomTowards, getScrollContainer, closestOpenableAncestor, isAncestorOpen, isDisplayedDespiteClosedAncestor, observeAncestorOpenState, getAncestorOpenType, findBefore, findAfter, resolveCSSSize, hasCSSSizeUnit, releaseWheelGesture, getScrollIntoViewScopedOffsets, wheelGestureIsTakenFrom, claimWheelGesture, scrollIntoViewScoped, initFocusGroup, isTouchDrivenEvent, stringifyStyle as stringifyStyle$1, resolveOklchLightness, contrastColor, parsePositionArea, snapToPixel, trapFocusInside, trapScrollInside, getVirtualKeyboardOverlayHeight, onAncestorReopen, isPressDisputedByDrag, canScroll, measureWidestChildRow, performTabNavigation, dragAfterIntent, stickyAsRelativeCoords, createDragToMoveGestureController, getDropTargetInfo, setStyles, useActiveElement } from "@jsenv/dom";
+import { elementIsFocusable, createIterableWeakSet, dispatchInternalCustomEvent, dispatchCustomEvent, getVisuallyVisibleInfo, getFirstVisuallyVisibleAncestor, getElementSignature, createPubSub, findEvent, createValueEffect, findFocusDelegateTarget, findFocusable, scrollIntoViewThroughScrollables, allowWheelThrough, dispatchPublicCustomEvent, resolveCSSColor, ELEMENT_SIZE_CHANGE, findSelfOrAncestorFixedPosition, visibleRectEffect, pickPositionRelativeTo, getBorderSizes, getPaddingSizes, applyNewPosition, measureLongestVisualLineWidth, chainEvent, keepTouchRefusable, waitForPressHeld, suppressClickAfterGesture, startDragToTravel, markDragSource, startDragTo, installPanZoom, createEventGroupLogger, getKeyboardEventDefaultAction, activeElementSignal, normalizeStyle, mergeOneStyle, getPositionedParent, normalizeStyles, createGroupTransitionController, getBorderRadius, preventIntermediateScrollbar, createOpacityTransition, watchWheelTravel, scrollRoomTowards, getScrollContainer, closestOpenableAncestor, isAncestorOpen, isDisplayedDespiteClosedAncestor, observeAncestorOpenState, getAncestorOpenType, findBefore, findAfter, resolveCSSSize, hasCSSSizeUnit, releaseWheelGesture, getScrollIntoViewScopedOffsets, wheelGestureIsTakenFrom, claimWheelGesture, scrollIntoViewScoped, initFocusGroup, isTouchDrivenEvent, stringifyStyle as stringifyStyle$1, resolveOklchLightness, contrastColor, parsePositionArea, snapToPixel, trapFocusInside, trapScrollInside, getVirtualKeyboardOverlayHeight, onAncestorReopen, isPressDisputedByDrag, canScroll, measureWidestChildRow, performTabNavigation, dragAfterIntent, stickyAsRelativeCoords, createDragToMoveGestureController, getDropTargetInfo, setStyles, useActiveElement } from "@jsenv/dom";
 export { chainEvent, clickIsSuppressed, contrastColor, createDragGestureController, dragAfterIntent, findEvent, markDragSource, startDragTo } from "@jsenv/dom";
 import { signal, computed, effect, untracked, batch, useComputed, useSignal } from "@preact/signals";
 import { isValidElement, createContext, render, h, toChildArray, options, cloneElement, Fragment as Fragment$1 } from "preact";
@@ -10334,26 +10334,31 @@ const swipeTypeOf = (axis, pulled) => {
 };
 
 /**
- * `move`, `reorder`, `land`, `toss` — one grab, and what letting go of it means.
+ * `move`, `reorder`, `land`, `toss`, `leave` — one grab, and what letting go of
+ * it means.
  *
- * All four are the same gesture: the element is picked up and carried. What
+ * All five are the same gesture: the element is picked up and carried. What
  * differs is the answer at the release, so one detector reads them all — it is one
  * press, and something has to arbitrate it.
  *
  *   interactions={{ reorder: moveBefore, toss: remove }}
  *   interactions={{ land: swapPlaces }}
- *   interactions={{ move: remember }}
+ *   interactions={{ move: remember, leave: remove }}
  *
- * `toss` combines with `reorder` and with `land`: a task dragged onto another
- * changes places, the same task thrown far and fast is gotten rid of. The three
- * others do not combine with each other — an element either goes where it is put,
- * takes a place in a list, or comes down on a place, and no two of those answers
- * can both be true of one release.
+ * `toss` and `leave` each combine with `reorder` and with `land`: a task dragged
+ * onto another changes places, the same task thrown far and fast is gotten rid
+ * of, a marker let go of off its plan is removed. `leave` combines with `move` as
+ * well. `move`, `reorder` and `land` do not combine with each other — an element
+ * either goes where it is put, takes a place in a list, or comes down on a place,
+ * and no two of those answers can both be true of one release.
  *
  * `move` carries the element ITSELF and leaves it where it was put; the others
  * carry a copy and put the original back. That is the same difference said in
  * layout terms: something moved has a new place of its own, something reordered
- * had its place taken by the list.
+ * had its place taken by the list. Where that place is KEPT is the answer's:
+ * an application that redraws the element from state while answering (a new
+ * `left`/`top`) owns the position from then on, and the drag's own translate
+ * goes; one that draws nothing leaves it to the element, where it is baked in.
  *
  * `reorder` VS `land`: both come down on an item, and what separates them is what
  * a place IS. A row of a list is a place BETWEEN two others — free by construction,
@@ -10369,9 +10374,8 @@ const swipeTypeOf = (axis, pulled) => {
  *   }}}
  *
  * `toId` is an element and never null: a copy over nothing is a release that meant
- * nothing, and the interaction does not happen at all — unless the element says
- * `data-toss-by="release-outside"` (see below), which gives that release a
- * meaning of its own.
+ * nothing, and the interaction does not happen at all — unless the element
+ * declares `leave` (see below), which gives that release a meaning of its own.
  *
  * WHERE ON IT, in `x`, `y`, `width`, `height`: the box the copy came down in,
  * measured inside the place — its border and its scroll taken out. A place that is
@@ -10408,15 +10412,30 @@ const swipeTypeOf = (axis, pulled) => {
  *     <Plan id="plan" data-droppable>…</Plan>
  *   </div>
  *
- * HOW A TOSS IS MADE: `data-toss-by`, beside `toss`. A THROW (`"throw"`, the
- * default) is far AND fast — the flick that gets rid of something, a list's
- * gesture, and it is judged before any landing. A RELEASE OUTSIDE
- * (`"release-outside"`) has no place under it — dragging a marker off a plan and
- * letting go, deliberate and never a flick, a surface's gesture. Each is named on
- * its own because each is wrong where the other is right: on a plan a fast drag
- * that ends ON it has not asked for the thing to go, and on a list a row let go of
- * beside it is a row put back. Both at once is
- * `data-toss-by="throw release-outside"`.
+ * LET GO OF AWAY FROM EVERY PLACE: `leave`. A throw is a GESTURE — far and fast,
+ * the flick that gets rid of a row, judged before any landing. A release outside
+ * is a PLACE — the hand let go with nothing under the thing, judged after a
+ * landing was looked for. They share the outcome an application usually attaches
+ * to them and nothing else, so each has its name: `toss` is the throw, `leave` is
+ * the release outside, and neither reads the other's rules — there is no speed to
+ * a release, and on a plan a fast drag that ends ON it has not asked for the
+ * thing to go.
+ *
+ *   interactions={{
+ *     move: (event) => remember(event.detail.x, event.detail.y),
+ *     leave: () => remove(id),
+ *   }}
+ *
+ * Beside `land` or `reorder`, "outside" is away from every place. Beside `move`
+ * — the element itself travels, and nothing is a place — it is outside the
+ * surface the element stands in: the nearest `data-droppable` ancestor, or,
+ * without one, what can be seen of the scroll container. Either way it is judged
+ * on the element's box no longer overlapping it, not on the pointer, which is
+ * still well inside the frame when a 30px marker has just left it. The detail is
+ * `toss`'s, `{ id, x, y }`, the distance travelled being what an exit is animated
+ * with. A refused `leave` travels back, as a refused `move` does; picked up and
+ * put straight back down stays a cancel — it has to have gone somewhere to be
+ * away from anything.
  *
  * Nothing of the gesture is decided here. `startDragTo` owns all of it — the
  * copy carried above the page while the original keeps its place in the layout, the
@@ -10464,7 +10483,7 @@ const swipeTypeOf = (axis, pulled) => {
  *
  *   interactions={{ toss: remove, grab: () => navigator.vibrate?.(10) }}
  *
- * The four above all answer the RELEASE, and between the press and the release
+ * The five above all answer the RELEASE, and between the press and the release
  * there is one instant that counts for the hand making the gesture: the one where
  * the object stops being pressed and starts being held. `grab` is that instant,
  * and it is the same one whichever way the drag was entered — a finger held still,
@@ -10478,7 +10497,7 @@ const swipeTypeOf = (axis, pulled) => {
  *
  * It is told, not asked: `grab` reports, so what it returns is not waited on and
  * preventing its event does not call the gesture off. And it is not an interaction
- * on its own — declared without one of the four above there is no gesture for it
+ * on its own — declared without one of the five above there is no gesture for it
  * to be the beginning of.
  *
  * A `longpress` needs nothing of this: it already happens at the moment the hold
@@ -10498,6 +10517,8 @@ const REORDER = "reorder";
 // for a file being dropped on the page would get this one and read it as such.
 const LAND = "land";
 const TOSS = "toss";
+// Let go of away from every place — not a throw, which is judged on its speed.
+const LEAVE = "leave";
 // The moment the press stops being a press and becomes a hold on the object.
 const GRAB = "grab";
 
@@ -10514,13 +10535,9 @@ const DROP_CONTAINER_ATTRIBUTE = "data-drop-container";
 const AXIS_ATTRIBUTE = "data-drag-axis";
 const DELAY_ATTRIBUTE = "data-drag-delay";
 const SLOP_ATTRIBUTE = "data-drag-slop";
-const THRESHOLD_ATTRIBUTE = "data-drag-threshold";
+const THRESHOLD_ATTRIBUTE$1 = "data-drag-threshold";
 const TOSS_DISTANCE_ATTRIBUTE = "data-toss-distance";
 const TOSS_SPEED_ATTRIBUTE = "data-toss-speed";
-// How a toss is made here: "throw" (far and fast), "release-outside" (let go of
-// away from every place), or both.
-const TOSS_BY_ATTRIBUTE = "data-toss-by";
-const TOSS_BY_DEFAULT = "throw";
 
 defineInteractionDetector({
   name: "drag",
@@ -10529,6 +10546,7 @@ defineInteractionDetector({
     type === REORDER ||
     type === LAND ||
     type === TOSS ||
+    type === LEAVE ||
     type === GRAB,
   // The press is the beginning of the gesture, not an answer: nothing may read
   // it until it is known whether the hand is dragging or just pressing.
@@ -10538,7 +10556,8 @@ defineInteractionDetector({
     const canReorder = types.includes(REORDER);
     const canLand = types.includes(LAND);
     const canToss = types.includes(TOSS);
-    if (!canMove && !canReorder && !canLand && !canToss) {
+    const canLeave = types.includes(LEAVE);
+    if (!canMove && !canReorder && !canLand && !canToss && !canLeave) {
       return undefined;
     }
     const tellsWhenGrabbed = types.includes(GRAB);
@@ -10549,18 +10568,18 @@ defineInteractionDetector({
       axisHolder?.getAttribute(AXIS_ATTRIBUTE) ||
       // A list runs one way, and reordering walks it. Anything else goes wherever
       // the hand takes it: a board has places all around, a thing put somewhere has
-      // two axes to be put along, and a throw goes where it was thrown.
-      (canReorder && !canLand && !canToss ? "y" : "xy");
-    // Where the places are, and what a release away from all of them means —
-    // both read at setup for the same reason as the axes: they are what the
-    // gesture is about, and it is what holds the two sides of it that says them.
+      // two axes to be put along, a throw goes where it was thrown and a thing
+      // that leaves goes out by whichever edge.
+      (canReorder && !canLand && !canToss && !canLeave ? "y" : "xy");
+    // Where the places are, read at setup for the same reason as the axes: they
+    // are what the gesture is about, and it is what holds the two sides of it
+    // that says them.
     const dropContainer = element.closest(`[${DROP_CONTAINER_ATTRIBUTE}]`);
-    const tossByHolder = element.closest(`[${TOSS_BY_ATTRIBUTE}]`);
-    const tossBy = (
-      tossByHolder?.getAttribute(TOSS_BY_ATTRIBUTE) || TOSS_BY_DEFAULT
-    )
-      .trim()
-      .split(/\s+/);
+    // What a `leave` is outside of when nothing is a place: the surface the
+    // element stands in. Looked for above the parent — the element itself may be
+    // a place of its own (a piece that receives), which is not what it is inside.
+    const outsideOf =
+      element.parentElement.closest(`[${DROPPABLE_ATTRIBUTE}]`) || undefined;
 
     if (canReorder) {
       element.setAttribute(REORDERABLE_ATTRIBUTE, "");
@@ -10588,6 +10607,7 @@ defineInteractionDetector({
             ? `[${REORDERABLE_ATTRIBUTE}]`
             : undefined,
         containerElement: dropContainer || undefined,
+        outsideOf,
         getItemId: (itemElement) => itemElement.id,
         direction: { x: axes.includes("x"), y: axes.includes("y") },
         // Where it may go, said in the DOM. A thing that is put somewhere stays
@@ -10595,21 +10615,20 @@ defineInteractionDetector({
         // the scrollable area can be far larger than the box, and "inside the box"
         // is what a hand expects). `data-drag-free` lifts that, and so does a
         // named container of places: they are somewhere else by construction, and
-        // a copy kept in its own scroll area could never reach them. Left alone
-        // for a throw, which frees the area on its own — it has to be able to
-        // leave.
+        // a copy kept in its own scroll area could never reach them. So does
+        // "leave": a thing let go of outside has to be able to get there. Left
+        // alone for a throw, which frees the area on its own.
         areaConstraint:
-          dropContainer || element.closest(`[data-drag-free]`)
+          dropContainer || element.closest(`[data-drag-free]`) || canLeave
             ? "none"
             : canMove
               ? "scrollport"
               : undefined,
-        threshold: readConfig(THRESHOLD_ATTRIBUTE, undefined),
+        threshold: readConfig(THRESHOLD_ATTRIBUTE$1, undefined),
         longPressDelay: readConfig(DELAY_ATTRIBUTE, undefined),
         longPressSlop: readConfig(SLOP_ATTRIBUTE, undefined),
         tossDistance: readConfig(TOSS_DISTANCE_ATTRIBUTE, undefined),
         tossSpeed: readConfig(TOSS_SPEED_ATTRIBUTE, undefined),
-        tossBy,
         // The one moment the gesture has that is not a release. Said here rather
         // than from the press that led to it, because the press is only one of the
         // two ways in: a finger holds still, a mouse travels a few pixels, and it
@@ -10623,7 +10642,7 @@ defineInteractionDetector({
               });
             }
           : undefined,
-        // Handed straight back in all three cases: what `trigger` returns is a
+        // Handed straight back in every case: what `trigger` returns is a
         // promise while the answer is still going, which is what the gesture waits
         // on before it lets go of what it carries.
         onReorder: (fromId, toId, syncCloneWithDropTarget) =>
@@ -10640,6 +10659,8 @@ defineInteractionDetector({
             x: gestureInfo.layout.xDelta,
             y: gestureInfo.layout.yDelta,
           }),
+        onLeave: ({ x, y }) =>
+          trigger(LEAVE, pointerDownEvent, { id: element.id, x, y }),
         onMove: ({ x, y }) => trigger(MOVE, pointerDownEvent, { x, y }),
       });
     };
@@ -10653,6 +10674,71 @@ defineInteractionDetector({
   },
 });
 
+/**
+ * `pan`, `zoom` — a surface under the hand.
+ *
+ *   <Box
+ *     interactions={{
+ *       pan: (event) => moveCenterBy(event.detail),    // { x, y } since the last one
+ *       zoom: (event) => zoomBy(event.detail),         // { factor, x, y }
+ *     }}
+ *   />
+ *
+ * Neither is an outcome: both are a stream, reported on every frame while the
+ * hand is still moving, and navi otherwise names only what happens once (see
+ * "A gesture whose product is a value" in docs/interactions.md). They are named
+ * here because of what has to be settled BEFORE the press, which is what
+ * `interactions` exists for: `touch-action` on the surface, said from a
+ * stylesheet since a browser decides what a touch may do when it lands; the pan
+ * stepping back for what is carried ACROSS the surface (a marker declaring
+ * `move`, a handle) and for what answers the pointer on its own; the pinch not
+ * beginning as a pan under its first finger; the wheel and the pinch writing
+ * one `zoom`. A handle turned, a sun dragged around a plan have none of that to
+ * arbitrate — the handle is the whole surface of the gesture — and stay
+ * unnamed.
+ *
+ * `pan`'s detail is the movement since the previous `pan`, in px. `zoom`'s is
+ * the factor (above 1 is in) and the point of the surface it is around,
+ * measured inside its border — the point between the fingers, or under the
+ * wheel. What a pixel of pan means in the application's coordinates, and
+ * whether the zoom is continuous or stepped, is the application's.
+ *
+ * Declared alone, `zoom` leaves one pointer to whatever else reads it and takes
+ * only two fingers and the wheel; `pan` alone leaves the wheel to the page.
+ *
+ * Nothing of the gesture is decided here — `installPanZoom` in @jsenv/dom owns
+ * the pointers, the capture, the wheel burst and the click left behind. This
+ * says which names the element answers with, and hands the numbers over.
+ */
+
+
+const PAN = "pan";
+const ZOOM = "zoom";
+// The same attribute a carried element reads: how far a pointer travels before
+// it is a gesture rather than a press.
+const THRESHOLD_ATTRIBUTE = "data-drag-threshold";
+
+defineInteractionDetector({
+  name: "surface",
+  claims: (type) => type === PAN || type === ZOOM,
+  // A press on the surface may be a tap, a hold or the beginning of a pan, and
+  // nothing may read it as the first until the pointer has said which.
+  disputesPress: true,
+  setup: (element, trigger, { types, readConfig }) => {
+    const canPan = types.includes(PAN);
+    const canZoom = types.includes(ZOOM);
+    return installPanZoom(element, {
+      threshold: readConfig(THRESHOLD_ATTRIBUTE, undefined),
+      onPan: canPan
+        ? ({ event, x, y }) => trigger(PAN, event, { x, y })
+        : undefined,
+      onZoom: canZoom
+        ? ({ event, factor, x, y }) => trigger(ZOOM, event, { factor, x, y })
+        : undefined,
+    });
+  },
+});
+
 // used by form elements such as <input>, <select>, <textarea> to have their own action bound to a single parameter
 // when inside a <form> the form params are updated when the form element single param is updated
 const useActionBoundToOneParam = (action, paramsSignal) => {
@@ -19921,9 +20007,14 @@ const PSEUDO_STATE_CHILD_PROP_SET = new Set(["tabIndex", "tabindex"]);
  *   preventInitialTransition?: boolean,
  *   separator?: import("ignore:preact").ComponentChildren | ((index: number) => import("ignore:preact").ComponentChildren),
  *   selfInteractions?: string,
+ *   interactions?: { [type: string]: "request_action" | "request_ui_action" | ((event: Event) => void) | false | null | undefined },
  *   children?: import("ignore:preact").ComponentChildren,
  *   [key: string]: any,
  * }>}
+ * @param {object} [interactions] What this box answers, by interaction name
+ *   (see docs/interactions.md). A plain box has no wiring of its own: it does
+ *   nothing with `action` (that is a control's prop), so a click on it is
+ *   declared here like any other interaction: `interactions={{ click: fn }}`.
  */
 const Box = props => {
   const {