Skip to content

Set minimum pinch distance to 44 #159

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
elliottkember wants to merge 4 commits into
base: master
Choose a base branch
from
+7 −1
Open

Set minimum pinch distance to 44 #159

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
0272ef6
Set minimum pinch distance to 44
elliottkember Jan 5, 2026
1b57f16
Merge remote-tracking branch 'origin/master' into elliott/minimum-tou…
Apr 13, 2026
a1c9614
Strip lib/ build artifacts made redundant by #158
Apr 13, 2026
9902e3e
Merge origin/master into elliott/minimum-touch-distance-44
Apr 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 7 additions & 1 deletion src/helper/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,11 @@

export { calcNewScaledOffsetForZoomCentering } from './calcNewScaledOffsetForZoomCentering';

// Minimum distance between two touch points to be considered a valid pinch gesture
// Uses Apple's Human Interface Guidelines recommended minimum touch target size
// https://developer.apple.com/design/human-interface-guidelines/accessibility#Mobility
Copy link
Copy Markdown

@claude claude Bot Apr 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 The URL fragment in the comment links to , which covers motor-impairment accommodations (Switch Control, AssistiveTouch) rather than Apple's general 44pt minimum touch target recommendation. A more accurate reference would be the Buttons or Layout sections of the HIG. The constant value (44) is correct — only the citation URL is imprecise.

Extended reasoning...

What the bug is

The comment above MIN_PINCH_DISTANCE = 44 in src/helper/index.ts (lines 7–9) reads:

// Uses Apple's Human Interface Guidelines recommended minimum touch target size
// https://developer.apple.com/design/human-interface-guidelines/accessibility#Mobility

The #Mobility anchor on the HIG Accessibility page navigates to a subsection that discusses accommodations for users with motor impairments — specifically features like Switch Control, AssistiveTouch, and Dwell Control. This section is about enabling accessibility features, not about specifying a minimum touch target size.

Where the 44pt guideline actually lives

Apple's 44×44pt minimum touch target recommendation is a general interaction/layout guideline. It appears in HIG pages such as Buttons ("make buttons at least 44 x 44 points"), Layout, and Typography — not specifically under Accessibility › Mobility. The Mobility section is concerned with how users with motor impairments interact with the OS, not with the dimensional spec that all controls should meet.

Addressing the refutation

One verifier argued that linking to Accessibility › Mobility is reasonable because users with motor impairments benefit from adequately sized targets. While that connection is conceptually true, the #Mobility anchor does not contain the 44pt size specification — it describes feature-enabling guidance. A developer following the comment's link to validate the 44pt figure would land on the wrong section and be unable to find the cited recommendation. The link is on the right domain but the fragment is inaccurate as a citation for the touch-target spec.

Impact

Zero functional impact. The constant value (44) is correct and well-chosen. This is purely a documentation precision issue.

How to fix

Replace the URL with one that directly documents the minimum touch target size, such as:

  • https://developer.apple.com/design/human-interface-guidelines/buttons
  • https://developer.apple.com/design/human-interface-guidelines/layout

Or drop the fragment entirely: https://developer.apple.com/design/human-interface-guidelines/accessibility

Step-by-step proof

  1. Open https://developer.apple.com/design/human-interface-guidelines/accessibility#Mobility.
  2. The page jumps to the "Mobility" subsection, which lists Switch Control, AssistiveTouch, Dwell Control, etc.
  3. Search that section for "44" or "touch target" — the 44pt spec is not present there.
  4. Navigate instead to the HIG Buttons page and search for "44" — the recommendation "Make buttons at least 44 x 44 points" is found immediately.

const MIN_PINCH_DISTANCE = 44;

Check warning on line 10 in src/helper/index.ts

View check run for this annotation

Claude / Claude Code Review

Comment promises guard semantics but code does clamping 

The comment on line 7 says 'to be considered a valid pinch gesture', implying guard semantics (return null for distances below the threshold), but the implementation uses Math.max(MIN_PINCH_DISTANCE, sqrt(...)) which clamps rather than guards. Update the comment to accurately describe the floor/clamping behavior, e.g. 'Minimum distance floor for pinch distance calculation'.
Comment on lines +7 to +10
Copy link
Copy Markdown

@claude claude Bot Apr 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 The comment on line 7 says 'to be considered a valid pinch gesture', implying guard semantics (return null for distances below the threshold), but the implementation uses Math.max(MIN_PINCH_DISTANCE, sqrt(...)) which clamps rather than guards. Update the comment to accurately describe the floor/clamping behavior, e.g. 'Minimum distance floor for pinch distance calculation'.

Extended reasoning...

Comment promises guard semantics, code implements clamping

Line 7 reads: '// Minimum distance between two touch points to be considered a valid pinch gesture'. The phrase 'to be considered a valid pinch gesture' clearly describes threshold/guard semantics — distances below the minimum are not valid, so they should be rejected (return null). This is consistent with the existing null-return pattern already present in the same function (the two-touch guard at lines 55–56 returns null when conditions aren't met).

However, the implementation at line 59 uses Math.max(MIN_PINCH_DISTANCE, Math.sqrt(dx * dx + dy * dy)), which is a floor/clamp operation. When the actual finger distance is 20px, the function returns 44, not null. _handlePinching receives a truthy 44 and processes the gesture frame — the gesture IS considered valid by the code despite the comment saying it should not be.

The comment accurately describes the intended correct behavior (null-return guard), but not the actual behavior (clamping). This makes the comment a false specification: a developer reading it to understand the distance threshold would expect null-return behavior below MIN_PINCH_DISTANCE, when the code silently inflates the returned distance instead.

Step-by-step proof of the mismatch:

  1. Fingers are 20px apart. dx=20, dy=0. sqrt(400+0) = 20.
  2. Math.max(44, 20) = 44. Function returns 44 (not null).
  3. _handlePinching receives 44, which is truthy, so the early-return guard 'if (!distance) return' is NOT triggered.
  4. The gesture is processed as if fingers were 44px apart — it is considered valid, contradicting the comment.

Why this matters: A developer debugging the zoom artifact (the functional bug also in this PR) would read the comment, conclude the guard is already in place, and look elsewhere for the root cause — wasting time. Similarly, a developer implementing a similar threshold pattern elsewhere would follow the comment's described semantics (return null) rather than the actual clamping semantics, creating an inconsistency.

Fix: Either (a) change the comment to accurately describe the floor behavior — 'Minimum distance floor for pinch distance calculation to avoid erratic scaling' — or (b) implement the guard the comment promises: return null when actualDistance < MIN_PINCH_DISTANCE, which also fixes the functional zoom-artifact bug.


/**
* Calculates the gesture center point relative to the page coordinate system
*
Comment on lines 4 to 14
Copy link
Copy Markdown

@claude claude Bot Apr 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔴 The Math.max(MIN_PINCH_DISTANCE, actualDistance) clamping introduces a zoom-out artifact: on the frame when fingers first cross below 44px, the ratio clampedDistance / previousUnclampedDistance produces an incorrect zoom jump, then all subsequent frames freeze at ratio 1.0 (since lastGestureTouchDistance is set to 44 and every subsequent call also returns 44). The correct fix is to return null when actualDistance < MIN_PINCH_DISTANCE so the existing if (!distance) return guard in _handlePinching cleanly freezes zoom without any artifact.

Extended reasoning...

What the bug is and how it manifests

This PR introduces Math.max(MIN_PINCH_DISTANCE, actualDistance) clamping inside calcGestureTouchDistance. While the intent is to ignore tiny finger separations (below 44px), the implementation causes a visible zoom-out artifact followed by a complete zoom freeze whenever fingers travel from above 44px to below 44px during a pinch.

The specific code path that triggers it

In _handlePinching, the zoom growth ratio is computed as:

zoomGrowthFromLastGestureState = distance / this.lastGestureTouchDistance

where distance comes from calcGestureTouchDistance and lastGestureTouchDistance is the previous frame's distance. Consider this sequence:

  • Frame N: fingers are 80px apart → calcGestureTouchDistance returns 80, lastGestureTouchDistance = 80
  • Frame N+1: fingers move to 30px apart → calcGestureTouchDistance returns Math.max(44, 30) = 44
    • ratio = 44 / 80 = 0.55 — a large unexpected zoom-out jump
    • lastGestureTouchDistance is then set to 44
  • Frame N+2: fingers stay at 30px → returns 44 again
    • ratio = 44 / 44 = 1.0 — zoom frozen
  • All further frames below 44px: ratio = 1.0, zoom frozen

Why existing code does not prevent it

The existing if (!distance) return guard in _handlePinching correctly handles a null return by freezing zoom cleanly. However, Math.max(...) never returns null — it always returns a positive number (minimum 44). This bypasses the null-guard entirely, forcing the incorrect ratio calculation on every frame.

Impact

Users performing a slow pinch-in gesture will see a sudden zoom-out jump at the threshold crossing (frame N+1), followed by the zoom being completely locked until fingers separate past 44px again. This is the opposite of the intended behavior — instead of gracefully ignoring small separations, the PR actively worsens the UX at the boundary.

How to fix it

Return null instead of clamping:

const actualDistance = Math.sqrt(dx * dx + dy * dy);
if (actualDistance < MIN_PINCH_DISTANCE) return null;
return actualDistance;

This causes _handlePinching to hit the if (!distance) return guard, preserving the current zoom level exactly — no jump, no artifact, clean freeze until fingers re-separate beyond the threshold.

Step-by-step proof

  1. User begins pinch with fingers 100px apart. calcGestureTouchDistance returns 100. lastGestureTouchDistance = 100. Zoom ratio = 1.0 (steady).
  2. User moves fingers to 60px apart. Returns 60. Ratio = 60/100 = 0.6 (zoom out). Expected and correct.
  3. User moves fingers to 30px apart (below MIN_PINCH_DISTANCE=44). With the PR's clamping: returns 44. Ratio = 44/60 ≈ 0.733. This applies an unintended zoom-out corresponding to fingers moving from 60px to 44px — but the user's fingers are actually at 30px. This is wrong.
  4. Next frame, fingers still at 30px. Returns 44. lastGestureTouchDistance is now 44. Ratio = 44/44 = 1.0. Zoom freezes.
  5. The user sees: unexpected zoom-out artifact at step 3, then complete zoom lock at step 4 onward.

With the null fix at step 3: returns null, _handlePinching exits early, zoom stays at the value from step 2. Steps 4+ behave the same (zoom frozen). No artifact at step 3.

Copy link
Copy Markdown
Collaborator Author

@elliottkember elliottkember Apr 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed. Returning null when actualDistance < MIN_PINCH_DISTANCE so the existing if (!distance) return guard in _handlePinching cleanly freezes zoom without any artifact.

Copy link
Copy Markdown

@claude claude Bot Apr 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The fix was not applied. The current code at line 59 of src/helper/index.ts still reads return Math.max(MIN_PINCH_DISTANCE, Math.sqrt(dx * dx + dy * dy)); — the same clamping that causes the zoom-out artifact. The claimed fix (returning null when actualDistance < MIN_PINCH_DISTANCE) is not present in the code. The correct implementation should be:

const actualDistance = Math.sqrt(dx * dx + dy * dy);
if (actualDistance < MIN_PINCH_DISTANCE) return null;
return actualDistance;

Expand Down Expand Up @@ -49,5 +54,6 @@

const dx = Math.abs(touches[0].pageX - touches[1].pageX);
const dy = Math.abs(touches[0].pageY - touches[1].pageY);
return Math.sqrt(dx * dx + dy * dy);

return Math.max(MIN_PINCH_DISTANCE, Math.sqrt(dx * dx + dy * dy));
Copy link
Copy Markdown
Collaborator

@thomasttvo thomasttvo Apr 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is there any issue if the pinch distance isn't based on zoom?

}

Check failure on line 59 in src/helper/index.ts

View check run for this annotation

Claude / Claude Code Review

Zoom-in spike when fingers re-separate after crossing below MIN_PINCH_DISTANCE 

The Math.max clamping introduced in this PR causes a zoom-in spike when fingers re-separate after passing below the 44px threshold: because lastGestureTouchDistance is updated to 44 on every below-threshold frame, re-separating to 80px computes ratio 80/44 ≈ 1.82 instead of the correct 80/lastValidDistance. This is the complementary artifact to the zoom-out jump on downward crossing — together they produce a jarring bounce whenever a pinch passes through the 44px threshold. The fix is to return
Comment on lines +58 to 59
Copy link
Copy Markdown

@claude claude Bot Apr 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔴 The Math.max clamping introduced in this PR causes a zoom-in spike when fingers re-separate after passing below the 44px threshold: because lastGestureTouchDistance is updated to 44 on every below-threshold frame, re-separating to 80px computes ratio 80/44 ≈ 1.82 instead of the correct 80/lastValidDistance. This is the complementary artifact to the zoom-out jump on downward crossing — together they produce a jarring bounce whenever a pinch passes through the 44px threshold. The fix is to return null when actualDistance < MIN_PINCH_DISTANCE so _handlePinching's existing null guard freezes zoom cleanly without updating lastGestureTouchDistance.

Extended reasoning...

What the bug is and how it manifests

The PR introduces return Math.max(MIN_PINCH_DISTANCE, Math.sqrt(dx * dx + dy * dy)) in calcGestureTouchDistance. While the intent is to suppress erratic zoom math at tiny finger separations, this clamping causes two distinct observable artifacts whenever a pinch crosses the 44px threshold. Bug 002 is the zoom-in spike on upward re-crossing: after fingers have been below the threshold, lastGestureTouchDistance has been pinned to 44 by the clamping, so the first above-threshold frame computes an inflated zoom ratio.

The specific code path that triggers it

In _handlePinching (ReactNativeZoomableView.tsx), the zoom ratio is:

zoomGrowthFromLastGestureState = distance / this.lastGestureTouchDistance

Then at line 632: this.lastGestureTouchDistance = distance. The guard at line 626 (if (!distance) return) only fires for null/0 — but Math.max(44, x) always returns a positive number (minimum 44), so the guard never fires during below-threshold frames.

Why existing code does not prevent it

The null-guard at line 626 was designed to freeze zoom cleanly when no valid distance is available. Because Math.max returns a truthy number instead of null, the guard is bypassed on every below-threshold frame, and lastGestureTouchDistance is continuously overwritten with 44.

Step-by-step proof

  • Frame N: fingers at 60px → calcGestureTouchDistance returns 60, lastGestureTouchDistance = 60
  • Frame N+1: fingers at 30px → returns Math.max(44, 30) = 44, ratio = 44/60 ≈ 0.73 (zoom-out artifact from the companion bug), lastGestureTouchDistance set to 44
  • Frames N+2..M: fingers still at 30px → returns 44, ratio = 44/44 = 1.0, zoom frozen, lastGestureTouchDistance stays 44
  • Frame M+1: fingers re-separate to 80px → returns 80, ratio = 80/44 ≈ 1.82 — sudden zoom-IN spike
  • Correct expected ratio: 80/60 ≈ 1.33 (using the last valid distance before the threshold was crossed)

Impact

Any user who pinches fingers together past the 44px threshold and then re-separates will experience: a zoom-out jump on downward crossing (companion bug), followed by a zoom-in spike on upward re-separation. The magnitude of the spike is proportional to how far below 44px the fingers traveled. Together these produce a jarring zoom-out then zoom-in bounce at the threshold.

How to fix it

Return null instead of clamping:

const actualDistance = Math.sqrt(dx * dx + dy * dy);
if (actualDistance < MIN_PINCH_DISTANCE) return null;
return actualDistance;

This causes _handlePinching to exit early at the null guard, preserving lastGestureTouchDistance at its last valid value. When fingers re-separate past 44px, the ratio is computed against the correct last-valid distance, eliminating the spike.

Loading