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 3 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
3 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
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

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

View check run for this annotation

Claude / Claude Code Review

HIG URL fragment #Mobility points to wrong section for 44pt touch target citation 

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.
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;

/**
* 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?

}
Loading