Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

chore(gestures): a pan's begin threshold can be read from each press (#9953)

Christopher Chedeau661f7914724a
diff --git a/.changeset/pan-press-threshold.md b/.changeset/pan-press-threshold.md
new file mode 100644
index 0000000000..b6cb6a8752
--- /dev/null
+++ b/.changeset/pan-press-threshold.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[chore] Internal: a pan gesture's begin threshold can be read from each press's first touch, so a mouse or a pen can begin a pan sooner than a finger. It is not exported from the package entry point, and nothing changes for existing callers.
+
+@vjeux
diff --git a/packages/core/src/gestures/PanGestureRecognizer.ts b/packages/core/src/gestures/PanGestureRecognizer.ts
index 2f65f77b71..692604e6f4 100644
--- a/packages/core/src/gestures/PanGestureRecognizer.ts
+++ b/packages/core/src/gestures/PanGestureRecognizer.ts
@@ -55,7 +55,12 @@ export interface PanGestureRecognizerOptions extends GestureRecognizerOptions<Pa
minimumNumberOfTouches?: number;
/** @default Infinity */
maximumNumberOfTouches?: number;
- hysteresis?: number;
+ /**
+ * The travel that begins the pan, px. A function gives each press its own
+ * threshold: it reads the press's first touch when that touch lands.
+ * @default UIKit's 10
+ */
+ hysteresis?: number | ((touch: GestureTouch) => number);
/** Movement that may begin the pan; anything else fails it. @default 'any' */
direction?: PanDirection;
/**
@@ -117,6 +122,11 @@ export class PanGestureRecognizer extends GestureRecognizer {
travelAtBegan: Point = ZERO;
private readonly tracker: VelocityTracker;
+ /**
+ * Read once per press. A finger that lands later keeps the press's
+ * threshold.
+ */
+ private readonly hysteresisFor: ((touch: GestureTouch) => number) | null;
/** The lift's event time once the pan ended: its release (AST-100 FR2). */
private releaseTime: number | undefined = undefined;
/** The centroid where the gesture started, in client px. */
@@ -132,7 +142,10 @@ export class PanGestureRecognizer extends GestureRecognizer {
this.minimumNumberOfTouches = options.minimumNumberOfTouches ?? 1;
this.maximumNumberOfTouches =
options.maximumNumberOfTouches ?? Number.POSITIVE_INFINITY;
- this.hysteresis = options.hysteresis ?? UIKIT_PAN.hysteresis.value;
+ const {hysteresis} = options;
+ this.hysteresisFor = typeof hysteresis === 'function' ? hysteresis : null;
+ this.hysteresis =
+ typeof hysteresis === 'number' ? hysteresis : UIKIT_PAN.hysteresis.value;
this.direction = options.direction ?? 'any';
this.axisRatio = options.axisRatio ?? 1;
this.lockAxis = options.lockAxis ?? false;
@@ -237,6 +250,10 @@ export class PanGestureRecognizer extends GestureRecognizer {
event: GestureEventContext,
): void {
if (this.numberOfTouches === touches.length) {
+ const first = touches[0];
+ if (this.hysteresisFor != null && first != null) {
+ this.hysteresis = this.hysteresisFor(first);
+ }
this.origin = centroid(this.touches.values());
this.adjust = ZERO;
this.raw = ZERO;
diff --git a/packages/core/src/gestures/README.md b/packages/core/src/gestures/README.md
index c523b58ccc..cb603f434f 100644
--- a/packages/core/src/gestures/README.md
+++ b/packages/core/src/gestures/README.md
@@ -118,7 +118,8 @@ The pan reads its numbers the way `UIPanGestureRecognizer` does, as measured
in the UIKit lab:
- It begins once the centroid has moved `hysteresis` (10 px) along either
- axis, not as a distance.
+ axis, not as a distance. A function gives each press its own threshold,
+ read from the press's first touch when it lands.
- `translation()` leaves out the travel the threshold took: a slow drag reads
zero when the pan begins, and a step that overshoots keeps only the
overshoot. A dragged surface does not jump. `totalTranslation()` is the
diff --git a/packages/core/src/gestures/ScreenEdgePanGestureRecognizer.ts b/packages/core/src/gestures/ScreenEdgePanGestureRecognizer.ts
index 85653cd918..88284b3202 100644
--- a/packages/core/src/gestures/ScreenEdgePanGestureRecognizer.ts
+++ b/packages/core/src/gestures/ScreenEdgePanGestureRecognizer.ts
@@ -76,12 +76,17 @@ interface EdgeLayout {
*/
export interface ScreenEdgePanGestureRecognizerOptions extends Omit<
PanGestureRecognizerOptions,
- 'direction' | 'allowedPointerTypes' | 'allowedScrollTypes'
+ 'direction' | 'allowedPointerTypes' | 'allowedScrollTypes' | 'hysteresis'
> {
/** The edges a touch may start from. @default ['leading'] */
edges?: ReadonlyArray<ScreenEdge>;
/** Width of the band at each edge, px. */
edgeRegion?: number;
+ /**
+ * The travel that begins the pan in its edge zone, px. It is one number for
+ * every press, since the zone sets the threshold itself. @default UIKit's 15
+ */
+ hysteresis?: number;
}
export class ScreenEdgePanGestureRecognizer extends PanGestureRecognizer {
diff --git a/packages/core/src/gestures/__tests__/PanGestureRecognizer.test.ts b/packages/core/src/gestures/__tests__/PanGestureRecognizer.test.ts
index c160b33fa1..bb47a703f3 100644
--- a/packages/core/src/gestures/__tests__/PanGestureRecognizer.test.ts
+++ b/packages/core/src/gestures/__tests__/PanGestureRecognizer.test.ts
@@ -84,6 +84,27 @@ describe('PanGestureRecognizer', () => {
expect(pan.totalTranslation()).toEqual({x: 50, y: 20});
});
+ it('reads each press’s begin threshold from its first touch', () => {
+ const h = createHarness();
+ const pan = new PanGestureRecognizer({
+ name: 'pan',
+ allowedPointerTypes: ['touch', 'mouse'],
+ hysteresis: touch => (touch.pointerType === 'mouse' ? 0 : 10),
+ });
+ h.finger(1)
+ .down(100, 100, 0, {recognizers: [pan], pointerType: 'mouse'})
+ .move(101, 100, 16);
+ expect(pan.state).toBe('began');
+ h.finger(1).up(32);
+ // The next press is a finger's: 5 px is under its threshold.
+ h.finger(2)
+ .down(100, 100, 100, {recognizers: [pan]})
+ .move(105, 100, 116);
+ expect(pan.state).toBe('possible');
+ h.finger(2).move(111, 100, 132);
+ expect(pan.state).toBe('began');
+ });
+
it('applies the hysteresis per axis, as UIKit does', () => {
const h = createHarness();
const pan = new PanGestureRecognizer({name: 'pan'});