@astryxdesign/core 0.7.5 → 0.7.6-canary.0ef60dd

package/dist/gestures/SwipeGestureRecognizer.js

@@ -0,0 +1,148 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file SwipeGestureRecognizer.ts
+ * @input Touches from a GestureArena
+ * @output Exports SwipeGestureRecognizer (UISwipeGestureRecognizer), its
+ *   options and direction type
+ * @position Discrete recognizer of packages/core/src/gestures
+ *
+ * Recognized WHILE the fingers move, as UIKit's is: as soon as the centroid
+ * has travelled `minimumDistance` along an allowed direction, within
+ * `maximumDuration` of touch-down, with off-axis travel no more than
+ * `maximumSecondaryMovement` px across it. Off-axis travel past that
+ * allowance, or the distance travelled the wrong way, rules a direction out;
+ * the swipe fails once every allowed direction is ruled out, as it does for
+ * too many fingers, the duration running out, and a lift before it was
+ * recognized.
+ */
+
+import { UIKIT_SWIPE } from "../motion/uikit/gestures.js";
+import { centroid } from "./geometry.js";
+import { GestureRecognizer } from "./GestureRecognizer.js";
+const SWIPE = UIKIT_SWIPE;
+export class SwipeGestureRecognizer extends GestureRecognizer {
+  get kind() {
+    return 'swipe';
+  }
+  /** The direction of the recognized swipe. */
+  recognizedDirection = null;
+  origin = {
+    x: 0,
+    y: 0
+  };
+  /** Directions this touch's path has ruled out. */
+  ruledOut = new Set();
+  /** The centroid at the previous move. */
+  last = null;
+  constructor(options = {}) {
+    super(options);
+    const direction = options.direction ?? ['right'];
+    this.directions = typeof direction === 'string' ? [direction] : direction;
+    this.numberOfTouchesRequired = options.numberOfTouchesRequired ?? 1;
+    this.minimumDistance = options.minimumDistance ?? SWIPE.minimumDistance.value;
+    this.maximumDuration = options.maximumDuration ?? SWIPE.maximumDuration.value;
+    this.maximumSecondaryMovement = options.maximumSecondaryMovement ?? SWIPE.maximumSecondaryMovement.value;
+  }
+  get isDiscrete() {
+    return true;
+  }
+  get nativeTouchBehavior() {
+    const horizontal = this.directions.some(direction => direction === 'left' || direction === 'right');
+    const vertical = this.directions.some(direction => direction === 'up' || direction === 'down');
+    return {
+      panX: !horizontal,
+      panY: !vertical,
+      pinchZoom: true,
+      doubleTapZoom: false
+    };
+  }
+  touchesBegan(touches, event) {
+    if (this.numberOfTouches > this.numberOfTouchesRequired) {
+      this.setState('failed');
+      return;
+    }
+    if (this.numberOfTouches === touches.length) {
+      this.setTimer(event.time + this.maximumDuration, () => {
+        // A swipe already recognized, waiting on a recognizer it requires to
+        // fail, holds its recognition (spec:AST-094 FR15).
+        if (this.pending == null) {
+          this.setState('failed');
+        }
+      });
+    }
+    // Measure from where every required finger is down.
+    this.origin = centroid(this.touches.values());
+    this.last = null;
+  }
+  touchesMoved() {
+    if (this.pending != null || this.numberOfTouches !== this.numberOfTouchesRequired) {
+      return;
+    }
+    const current = centroid(this.touches.values());
+    const from = this.last ?? this.origin;
+    this.last = current;
+    for (const direction of this.directions) {
+      if (this.ruledOut.has(direction)) {
+        continue;
+      }
+      // Along and across this direction at the start and the end of the
+      // move. The path between two events is read as a straight segment, so
+      // the verdict does not depend on how far apart the events were.
+      const [along0, across0] = this.project(direction, from);
+      const [along1, across1] = this.project(direction, current);
+      const reaches = segmentCrossing(along0, along1, this.minimumDistance);
+      const strays = Math.max(segmentCrossing(across0, across1, this.maximumSecondaryMovement), segmentCrossing(-across0, -across1, this.maximumSecondaryMovement));
+      const strayAt = strays < 0 ? Infinity : strays;
+      if (reaches >= 0 && reaches <= strayAt) {
+        this.recognizedDirection = direction;
+        this.setState('ended');
+        return;
+      }
+      // Off-axis travel past the allowance, or the distance the wrong way,
+      // rules a direction out for good.
+      if (strays >= 0 || along1 <= -this.minimumDistance) {
+        this.ruledOut.add(direction);
+      }
+    }
+    if (this.directions.every(direction => this.ruledOut.has(direction))) {
+      this.setState('failed');
+    }
+  }
+
+  /** Travel along and across `direction` from the origin to `point`. */
+  project(direction, point) {
+    const dx = point.x - this.origin.x;
+    const dy = point.y - this.origin.y;
+    return direction === 'left' ? [-dx, dy] : direction === 'right' ? [dx, dy] : direction === 'up' ? [-dy, dx] : [dy, dx];
+  }
+  touchesEnded() {
+    // Recognized and waiting, it holds past the lift (FR15).
+    if (this.pending == null) {
+      this.setState('failed');
+    }
+  }
+  reset() {
+    this.recognizedDirection = null;
+    this.ruledOut.clear();
+    this.last = null;
+    this.origin = {
+      x: 0,
+      y: 0
+    };
+  }
+}
+
+/**
+ * Where on the segment from `start` to `end` (0 to 1) the value first
+ * reaches `limit`; 0 when it starts there, -1 when it never does.
+ */
+function segmentCrossing(start, end, limit) {
+  if (start >= limit) {
+    return 0;
+  }
+  if (end < limit) {
+    return -1;
+  }
+  return (limit - start) / (end - start);
+}

package/dist/gestures/TapGestureRecognizer.d.ts

@@ -11,6 +11,7 @@ export interface TapGestureRecognizerOptions extends GestureRecognizerOptions<Ta
     maximumTapDuration?: number;
 }
 export declare class TapGestureRecognizer extends GestureRecognizer {
+    get kind(): GestureRecognizer['kind'];
     numberOfTapsRequired: number;
     numberOfTouchesRequired: number;
     allowableMovement: number;

package/dist/gestures/TapGestureRecognizer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TapGestureRecognizer.d.ts","sourceRoot":"","sources":["../../src/gestures/TapGestureRecognizer.ts"],"names":[],"mappings":"AAuBA,OAAO,EACL,iBAAiB,EAEjB,KAAK,wBAAwB,EAC7B,KAAK,mBAAmB,EACzB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAC,mBAAmB,EAAE,YAAY,EAAQ,MAAM,SAAS,CAAC;AAEtE,MAAM,WAAW,2BAA4B,SAAQ,wBAAwB,CAAC,oBAAoB,CAAC;IACjG,iBAAiB;IACjB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,iBAAiB;IACjB,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,0BAA0B,CAAC,EAAE,MAAM,CAAC;IACpC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAID,qBAAa,oBAAqB,SAAQ,iBAAiB;IACzD,oBAAoB,EAAE,MAAM,CAAC;IAC7B,uBAAuB,EAAE,MAAM,CAAC;IAChC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,0BAA0B,EAAE,MAAM,CAAC;IACnC,mBAAmB,EAAE,MAAM,CAAC;IAC5B,kBAAkB,EAAE,MAAM,CAAC;IAE3B,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,iBAAiB,CAAK;IAC9B,4DAA4D;IAC5D,OAAO,CAAC,gBAAgB,CAAsB;IAC9C,0EAA0E;IAC1E,OAAO,CAAC,SAAS,CAA4B;IAC7C,OAAO,CAAC,QAAQ,CAA4B;gBAEhC,OAAO,GAAE,2BAAgC;IAerD,IAAa,UAAU,IAAI,OAAO,CAEjC;IAED,IAAa,mBAAmB,IAAI,mBAAmB,CAEtD;IAED,qDAAqD;IACrD,IAAI,aAAa,IAAI,MAAM,CAE1B;IAEQ,UAAU,IAAI,OAAO;cAIX,YAAY,CAC7B,OAAO,EAAE,aAAa,CAAC,YAAY,CAAC,EACpC,KAAK,EAAE,mBAAmB,GACzB,IAAI;cAoCY,YAAY,CAAC,OAAO,EAAE,aAAa,CAAC,YAAY,CAAC,GAAG,IAAI;cAMxD,YAAY,CAC7B,OAAO,EAAE,aAAa,CAAC,YAAY,CAAC,EACpC,KAAK,EAAE,mBAAmB,GACzB,IAAI;cA6BY,KAAK,IAAI,IAAI;CAQjC"}
+{"version":3,"file":"TapGestureRecognizer.d.ts","sourceRoot":"","sources":["../../src/gestures/TapGestureRecognizer.ts"],"names":[],"mappings":"AAuBA,OAAO,EACL,iBAAiB,EAEjB,KAAK,wBAAwB,EAC7B,KAAK,mBAAmB,EACzB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAC,mBAAmB,EAAE,YAAY,EAAQ,MAAM,SAAS,CAAC;AAEtE,MAAM,WAAW,2BAA4B,SAAQ,wBAAwB,CAAC,oBAAoB,CAAC;IACjG,iBAAiB;IACjB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,iBAAiB;IACjB,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,0BAA0B,CAAC,EAAE,MAAM,CAAC;IACpC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAID,qBAAa,oBAAqB,SAAQ,iBAAiB;IACzD,IAAa,IAAI,IAAI,iBAAiB,CAAC,MAAM,CAAC,CAE7C;IAED,oBAAoB,EAAE,MAAM,CAAC;IAC7B,uBAAuB,EAAE,MAAM,CAAC;IAChC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,0BAA0B,EAAE,MAAM,CAAC;IACnC,mBAAmB,EAAE,MAAM,CAAC;IAC5B,kBAAkB,EAAE,MAAM,CAAC;IAE3B,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,iBAAiB,CAAK;IAC9B,4DAA4D;IAC5D,OAAO,CAAC,gBAAgB,CAAsB;IAC9C,0EAA0E;IAC1E,OAAO,CAAC,SAAS,CAA4B;IAC7C,OAAO,CAAC,QAAQ,CAA4B;gBAEhC,OAAO,GAAE,2BAAgC;IAerD,IAAa,UAAU,IAAI,OAAO,CAEjC;IAED,IAAa,mBAAmB,IAAI,mBAAmB,CAEtD;IAED,qDAAqD;IACrD,IAAI,aAAa,IAAI,MAAM,CAE1B;IAEQ,UAAU,IAAI,OAAO;cAIX,YAAY,CAC7B,OAAO,EAAE,aAAa,CAAC,YAAY,CAAC,EACpC,KAAK,EAAE,mBAAmB,GACzB,IAAI;cAoCY,YAAY,CAAC,OAAO,EAAE,aAAa,CAAC,YAAY,CAAC,GAAG,IAAI;cAMxD,YAAY,CAC7B,OAAO,EAAE,aAAa,CAAC,YAAY,CAAC,EACpC,KAAK,EAAE,mBAAmB,GACzB,IAAI;cA6BY,KAAK,IAAI,IAAI;CAQjC"}

package/dist/gestures/TapGestureRecognizer.js

@@ -24,6 +24,9 @@ import { distance, travel } from "./geometry.js";
 import { GestureRecognizer, MANIPULATION } from "./GestureRecognizer.js";
 const TAP = UIKIT_TAP;
 export class TapGestureRecognizer extends GestureRecognizer {
+  get kind() {
+    return 'tap';
+  }
   tapCount = 0;
   isTapInProgress = false;
   maxTouchesThisTap = 0;

package/dist/gestures/VelocityTracker.d.ts

@@ -27,9 +27,13 @@ export declare class VelocityTracker {
      * Record a position. Timestamps must not go backwards (an older sample is
      * ignored), and a moved sample at the newest moved sample's timestamp
      * replaces it. A sample at the newest position is not motion: it changes
-     * no velocity.
+     * no velocity, unless `isMotion` says the contact moved anyway (a pinch's
+     * value holding while both fingers move, which reads as zero velocity for
+     * that interval).
      */
-    add(x: number, y: number, time: number): void;
+    add(x: number, y: number, time: number, { isMotion }?: {
+        isMotion?: boolean;
+    }): void;
     /** Record every sample in order. */
     addSamples(samples: ReadonlyArray<TouchSample>): void;
     /** The newest sample, if any. */

package/dist/gestures/VelocityTracker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"VelocityTracker.d.ts","sourceRoot":"","sources":["../../src/gestures/VelocityTracker.ts"],"names":[],"mappings":"AAqCA,OAAO,KAAK,EAAC,KAAK,EAAE,WAAW,EAAC,MAAM,SAAS,CAAC;AAEhD,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAaD,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,6CAA6C;IAC7C,OAAO,CAAC,MAAM,CAA4B;IAC1C;;;OAGG;IACH,OAAO,CAAC,KAAK,CAAqB;IAClC,0CAA0C;IAC1C,OAAO,CAAC,KAAK,CAAK;IAClB,mDAAmD;IACnD,OAAO,CAAC,GAAG,CAAe;IAC1B,OAAO,CAAC,WAAW,CAAe;gBAEtB,OAAO,GAAE,sBAA2B;IAIhD,2CAA2C;IAC3C,KAAK,IAAI,IAAI;IAQb;;;;;OAKG;IACH,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAwB7C,oCAAoC;IACpC,UAAU,CAAC,OAAO,EAAE,aAAa,CAAC,WAAW,CAAC,GAAG,IAAI;IAMrD,iCAAiC;IACjC,IAAI,UAAU,IAAI,WAAW,GAAG,IAAI,CAEnC;IAED;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,KAAK;IAOrC;;;;OAIG;IACH,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,KAAK;IAO1C,OAAO,CAAC,QAAQ;CAQjB"}
+{"version":3,"file":"VelocityTracker.d.ts","sourceRoot":"","sources":["../../src/gestures/VelocityTracker.ts"],"names":[],"mappings":"AAqCA,OAAO,KAAK,EAAC,KAAK,EAAE,WAAW,EAAC,MAAM,SAAS,CAAC;AAEhD,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAaD,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,6CAA6C;IAC7C,OAAO,CAAC,MAAM,CAA4B;IAC1C;;;OAGG;IACH,OAAO,CAAC,KAAK,CAAqB;IAClC,0CAA0C;IAC1C,OAAO,CAAC,KAAK,CAAK;IAClB,mDAAmD;IACnD,OAAO,CAAC,GAAG,CAAe;IAC1B,OAAO,CAAC,WAAW,CAAe;gBAEtB,OAAO,GAAE,sBAA2B;IAIhD,2CAA2C;IAC3C,KAAK,IAAI,IAAI;IAQb;;;;;;;OAOG;IACH,GAAG,CACD,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,IAAI,EAAE,MAAM,EACZ,EAAC,QAAgB,EAAC,GAAE;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAM,GAC5C,IAAI;IAwBP,oCAAoC;IACpC,UAAU,CAAC,OAAO,EAAE,aAAa,CAAC,WAAW,CAAC,GAAG,IAAI;IAMrD,iCAAiC;IACjC,IAAI,UAAU,IAAI,WAAW,GAAG,IAAI,CAEnC;IAED;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,KAAK;IAOrC;;;;OAIG;IACH,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,KAAK;IAO1C,OAAO,CAAC,QAAQ;CAQjB"}

package/dist/gestures/VelocityTracker.js

@@ -77,9 +77,13 @@ export class VelocityTracker {
    * Record a position. Timestamps must not go backwards (an older sample is
    * ignored), and a moved sample at the newest moved sample's timestamp
    * replaces it. A sample at the newest position is not motion: it changes
-   * no velocity.
+   * no velocity, unless `isMotion` says the contact moved anyway (a pinch's
+   * value holding while both fingers move, which reads as zero velocity for
+   * that interval).
    */
-  add(x, y, time) {
+  add(x, y, time, {
+    isMotion = false
+  } = {}) {
     if (this.newest != null && time < this.newest.time) {
       return;
     }
@@ -89,7 +93,7 @@ export class VelocityTracker {
       time
     };
     const last = this.moved[this.moved.length - 1];
-    if (last != null && x === last.x && y === last.y) {
+    if (last != null && x === last.x && y === last.y && !isMotion) {
       return;
     }
     if (last != null && time === last.time) {

package/dist/gestures/haptics.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @file haptics.ts
+ * @input A feedback kind, or a label element a real finger will tap
+ * @output Exports playHaptic (vibration where the platform has it),
+ *   attachTapHaptic (iOS Safari's tap-moment light impact) and the support
+ *   probes
+ * @position Haptics of packages/core/src/gestures; the kinds and the
+ *   vibration patterns live in the constants table (motion/uikit/gestures.ts)
+ *
+ * The web has one haptics API, `navigator.vibrate`, and iOS Safari does not
+ * implement it. iOS Safari does play a haptic in exactly one place: when a
+ * REAL tap toggles an `<input type="checkbox" switch>`, by landing on the
+ * switch or on a `<label>` tied to it (and during a native drag-flip of the
+ * switch). That haptic is UIImpactFeedbackGenerator(.light). WebKit requires
+ * a user gesture AND a trusted event for it: a `label.click()` from script
+ * does not play it (WebKit bug 309082, May 2026), so nothing can fire a
+ * haptic later from JavaScript, and mid-drag haptics (detent snaps, picker
+ * ticks) cannot exist in iOS Safari.
+ *
+ * So there are two tools:
+ *
+ * - `attachTapHaptic(label)` puts a visually hidden switch inside a label the
+ *   control renders as its tap target: every real tap on the label plays the
+ *   light impact at the moment of the tap. The switch itself never takes the
+ *   touch (`pointer-events: none`; WebKit marks a switch's `touchstart`
+ *   handled, which would stop a pan starting on it from scrolling the page),
+ *   and its own events never reach the page.
+ * - `playHaptic(kind)` vibrates where `navigator.vibrate` exists (Android
+ *   browsers) with the kind's pattern, and does nothing elsewhere.
+ *
+ * UIKit's haptics follow the system setting, not Reduce Motion, so neither
+ * tool consults `prefers-reduced-motion`.
+ */
+import { type HapticFeedbackKind } from '../motion/uikit/gestures.js';
+/** Marks the hidden switch, so click handlers can recognize and ignore it. */
+export declare const HAPTIC_SWITCH_ATTRIBUTE = "data-astryx-haptic-switch";
+/** Whether this browser vibrates at all. */
+export declare function canVibrate(): boolean;
+/** Whether this browser knows the switch control (Safari 17.4 and later). */
+export declare function supportsSwitchControl(doc?: Document): boolean;
+/**
+ * Vibrate for a feedback kind where `navigator.vibrate` exists. Returns
+ * whether anything was played. Never plays on iOS, which has no vibration
+ * API; use `attachTapHaptic` for the tap moment there.
+ */
+export declare function playHaptic(kind: HapticFeedbackKind): boolean;
+/**
+ * Make every real tap on `label` play iOS Safari's light impact, by giving it
+ * a hidden switch to toggle. Returns a function that removes the switch.
+ * Harmless where switches have no haptics.
+ *
+ * - The switch never keeps the focus: where a label's activation focuses
+ *   its control (Chromium), the focus goes on to the label's own control,
+ *   or back where it was, so it never lands on an `aria-hidden` element.
+ * - A label that already has a control keeps it: the switch takes the
+ *   label's activation (it goes first) and hands the click on to that
+ *   control, so the tap plays and the control still toggles. The control
+ *   keeps its name too: while the switch is attached it is labelled by the
+ *   label through `aria-labelledby`, unless it already names itself. A control
+ *   that is itself a switch plays on its own, and a label tied to its
+ *   control by `for` cannot be given a second one: both are left as they
+ *   are.
+ */
+export declare function attachTapHaptic(label: HTMLLabelElement): () => void;
+//# sourceMappingURL=haptics.d.ts.map

package/dist/gestures/haptics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"haptics.d.ts","sourceRoot":"","sources":["../../src/gestures/haptics.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,0BAA0B,CAAC;AAElC,8EAA8E;AAC9E,eAAO,MAAM,uBAAuB,8BAA8B,CAAC;AAEnE,4CAA4C;AAC5C,wBAAgB,UAAU,IAAI,OAAO,CAIpC;AAED,6EAA6E;AAC7E,wBAAgB,qBAAqB,CAAC,GAAG,CAAC,EAAE,QAAQ,GAAG,OAAO,CAQ7D;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAK5D;AA0BD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,gBAAgB,GAAG,MAAM,IAAI,CAuFnE"}

package/dist/gestures/haptics.js

@@ -0,0 +1,182 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file haptics.ts
+ * @input A feedback kind, or a label element a real finger will tap
+ * @output Exports playHaptic (vibration where the platform has it),
+ *   attachTapHaptic (iOS Safari's tap-moment light impact) and the support
+ *   probes
+ * @position Haptics of packages/core/src/gestures; the kinds and the
+ *   vibration patterns live in the constants table (motion/uikit/gestures.ts)
+ *
+ * The web has one haptics API, `navigator.vibrate`, and iOS Safari does not
+ * implement it. iOS Safari does play a haptic in exactly one place: when a
+ * REAL tap toggles an `<input type="checkbox" switch>`, by landing on the
+ * switch or on a `<label>` tied to it (and during a native drag-flip of the
+ * switch). That haptic is UIImpactFeedbackGenerator(.light). WebKit requires
+ * a user gesture AND a trusted event for it: a `label.click()` from script
+ * does not play it (WebKit bug 309082, May 2026), so nothing can fire a
+ * haptic later from JavaScript, and mid-drag haptics (detent snaps, picker
+ * ticks) cannot exist in iOS Safari.
+ *
+ * So there are two tools:
+ *
+ * - `attachTapHaptic(label)` puts a visually hidden switch inside a label the
+ *   control renders as its tap target: every real tap on the label plays the
+ *   light impact at the moment of the tap. The switch itself never takes the
+ *   touch (`pointer-events: none`; WebKit marks a switch's `touchstart`
+ *   handled, which would stop a pan starting on it from scrolling the page),
+ *   and its own events never reach the page.
+ * - `playHaptic(kind)` vibrates where `navigator.vibrate` exists (Android
+ *   browsers) with the kind's pattern, and does nothing elsewhere.
+ *
+ * UIKit's haptics follow the system setting, not Reduce Motion, so neither
+ * tool consults `prefers-reduced-motion`.
+ */
+
+import { HAPTIC_VIBRATION_PATTERNS } from "../motion/uikit/gestures.js";
+
+/** Marks the hidden switch, so click handlers can recognize and ignore it. */
+export const HAPTIC_SWITCH_ATTRIBUTE = 'data-astryx-haptic-switch';
+
+/** Whether this browser vibrates at all. */
+export function canVibrate() {
+  return typeof navigator !== 'undefined' && typeof navigator.vibrate === 'function';
+}
+
+/** Whether this browser knows the switch control (Safari 17.4 and later). */
+export function supportsSwitchControl(doc) {
+  const target = doc ?? (typeof document === 'undefined' ? null : document);
+  if (target == null) {
+    return false;
+  }
+  const input = target.createElement('input');
+  input.type = 'checkbox';
+  return 'switch' in input;
+}
+
+/**
+ * Vibrate for a feedback kind where `navigator.vibrate` exists. Returns
+ * whether anything was played. Never plays on iOS, which has no vibration
+ * API; use `attachTapHaptic` for the tap moment there.
+ */
+export function playHaptic(kind) {
+  if (!canVibrate()) {
+    return false;
+  }
+  return navigator.vibrate([...HAPTIC_VIBRATION_PATTERNS[kind].value]);
+}
+const VISUALLY_HIDDEN = 'position:absolute;width:1px;height:1px;margin:-1px;padding:0;border:0;' + 'overflow:hidden;clip:rect(0 0 0 0);clip-path:inset(50%);white-space:nowrap;' + 'opacity:0;pointer-events:none;';
+let nextLabelId = 0;
+
+/** A native disabled control, or one marked `aria-disabled`. */
+function isDisabledControl(control) {
+  return control.matches(':disabled') || control.getAttribute('aria-disabled') === 'true';
+}
+
+/** Whether `input` is a switch checkbox, which plays the tap haptic itself. */
+function isSwitch(input) {
+  return input.type === 'checkbox' && input.hasAttribute('switch');
+}
+function swallow(event) {
+  event.stopPropagation();
+}
+
+/**
+ * Make every real tap on `label` play iOS Safari's light impact, by giving it
+ * a hidden switch to toggle. Returns a function that removes the switch.
+ * Harmless where switches have no haptics.
+ *
+ * - The switch never keeps the focus: where a label's activation focuses
+ *   its control (Chromium), the focus goes on to the label's own control,
+ *   or back where it was, so it never lands on an `aria-hidden` element.
+ * - A label that already has a control keeps it: the switch takes the
+ *   label's activation (it goes first) and hands the click on to that
+ *   control, so the tap plays and the control still toggles. The control
+ *   keeps its name too: while the switch is attached it is labelled by the
+ *   label through `aria-labelledby`, unless it already names itself. A control
+ *   that is itself a switch plays on its own, and a label tied to its
+ *   control by `for` cannot be given a second one: both are left as they
+ *   are.
+ */
+export function attachTapHaptic(label) {
+  const existing = label.control;
+  if (existing instanceof HTMLInputElement && isSwitch(existing) || existing != null && label.htmlFor !== '') {
+    return () => {};
+  }
+  const doc = label.ownerDocument;
+  const input = doc.createElement('input');
+  input.type = 'checkbox';
+  input.setAttribute('switch', '');
+  input.setAttribute(HAPTIC_SWITCH_ATTRIBUTE, '');
+  input.setAttribute('aria-hidden', 'true');
+  input.tabIndex = -1;
+  input.style.cssText = VISUALLY_HIDDEN;
+  // The label's activation clicks the switch, and that click would bubble
+  // through the control as a second click: keep it, and the switch's
+  // change events, inside. A label with a control of its own gets that
+  // click handed on, so the control still toggles.
+  // A disabled control gives no feedback (spec:AST-094 FR23): its label's
+  // activation neither toggles the switch, so nothing plays, nor reaches
+  // the control.
+  const onClick = event => {
+    event.stopPropagation();
+    if (existing != null && isDisabledControl(existing)) {
+      event.preventDefault();
+      return;
+    }
+    existing?.click();
+  };
+  const onFocus = event => {
+    const previous = event.relatedTarget;
+    if (existing instanceof HTMLElement && existing.tabIndex >= 0 && !isDisabledControl(existing)) {
+      existing.focus({
+        preventScroll: true
+      });
+    }
+    if (doc.activeElement !== input) {
+      return;
+    }
+    if (previous instanceof HTMLElement && previous.isConnected) {
+      previous.focus({
+        preventScroll: true
+      });
+    }
+    if (doc.activeElement === input) {
+      input.blur();
+    }
+  };
+  input.addEventListener('click', onClick);
+  input.addEventListener('change', swallow);
+  input.addEventListener('input', swallow);
+  input.addEventListener('focus', onFocus);
+  // The switch becomes the label's control, so the control the label named
+  // is named through `aria-labelledby` instead (the switch is aria-hidden,
+  // so the label's text is the name).
+  let labelledControl = null;
+  let addedLabelId = false;
+  if (existing != null) {
+    label.prepend(input);
+    if (existing instanceof HTMLElement && !existing.hasAttribute('aria-labelledby') && !existing.hasAttribute('aria-label')) {
+      if (label.id === '') {
+        label.id = `astryx-haptic-label-${nextLabelId += 1}`;
+        addedLabelId = true;
+      }
+      existing.setAttribute('aria-labelledby', label.id);
+      labelledControl = existing;
+    }
+  } else {
+    label.appendChild(input);
+  }
+  return () => {
+    labelledControl?.removeAttribute('aria-labelledby');
+    if (addedLabelId) {
+      label.removeAttribute('id');
+    }
+    input.removeEventListener('click', onClick);
+    input.removeEventListener('change', swallow);
+    input.removeEventListener('input', swallow);
+    input.removeEventListener('focus', onFocus);
+    input.remove();
+  };
+}

package/dist/gestures/nativeScroll.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @file nativeScroll.ts
+ * @input An element a touch landed on
+ * @output Exports createNativeScrollProbe (the NativeScrollProbe a host gives
+ *   each touch) and parseTouchAction
+ * @position DOM half of the scroll coordination in packages/core/src/gestures
+ *
+ * Answers one question for a recognizer without letting it touch the DOM:
+ * would the browser scroll something if this finger moved that way?
+ *
+ * The browser scrolls the innermost scroller that has room, then chains
+ * outward, so the answer is "yes" while ANY scroller under the touch can
+ * still move in that direction, with three narrowings that match the
+ * browser's own:
+ *
+ * - `touch-action` between the touch target and a scroller must allow the
+ *   axis, or the browser will not pan that scroller with a finger;
+ * - an `overscroll-behavior` other than `auto` on the axis stops the chain at
+ *   that scroller (a sheet body with `contain` never scrolls the page);
+ * - a finger moving down scrolls content toward its START (scrollTop
+ *   decreasing), and horizontally the range follows the writing direction
+ *   (RTL `scrollLeft` runs from minus the overflow to zero).
+ *
+ * Styles are read once per touch, on the first question; scroll offsets are
+ * read fresh on every question, since a native scroll moves them.
+ */
+import type { NativeScrollProbe } from './types.js';
+export interface AllowedPans {
+    readonly x: boolean;
+    readonly y: boolean;
+}
+/** Which pans a `touch-action` value lets the browser perform. */
+export declare function parseTouchAction(value: string): AllowedPans;
+/**
+ * The node's parent in the flat tree: a slotted node's slot, then out of
+ * shadow roots to their hosts, so a scroller inside a shadow tree around the
+ * slot is found.
+ */
+export declare function parentAcrossShadow(node: Node): Node | null;
+/** A probe of the native scrollers under `target`. */
+export declare function createNativeScrollProbe(target: unknown): NativeScrollProbe;
+//# sourceMappingURL=nativeScroll.d.ts.map

package/dist/gestures/nativeScroll.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nativeScroll.d.ts","sourceRoot":"","sources":["../../src/gestures/nativeScroll.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,SAAS,CAAC;AAE/C,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,CAAC,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,kEAAkE;AAClE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAiB3D;AAoBD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAY1D;AAuID,sDAAsD;AACtD,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,OAAO,GAAG,iBAAiB,CAiD1E"}