Mobile Gesture Guide

Major changes vs v1.0.0:

• Adds Phase 2 (preferences, haptics, batched analytics) and Phase 3 (pinch-to-zoom, multi-touch, custom gestures) coverage.
• Adds the new SwipeableCardShell primitive and the deprecation of hand-rolled *Swipeable.tsx wrappers.
• Documents prefers-reduced-motion behavior across Phase 1 hooks.
• Adds cross-references to /settings/gestures and /settings/gestures/analytics.
• Aligns CSS-var examples with production (--mobile-nav-height: 76px, --mobile-header-height: 48px).

​

Overview

• User preferences stored under pf_profiles.preferences.gestures (see PF-37 Phase 2).
• Haptic feedback via the Vibration API where supported.
• Batched analytics to pf_gesture_analytics_events (5-second flush, no PHI).
• Reduced motion via prefers-reduced-motion: reduce.
• Keyboard alternatives per WCAG 2.1.1, 2.5.1, and 2.5.2.

​

Table of Contents

1. Quick Start
2. Hooks Catalog
3. Components Catalog
4. Decision Tree — When to Use Each Pattern
5. User Preferences (Phase 2)
6. Haptic Feedback (Phase 2)
7. Analytics (Phase 2)
8. Pinch & Multi-touch (Phase 3)
9. Custom Gesture Registry (Phase 3)
10. Accessibility & Reduced Motion
11. Performance Guidelines
12. Browser Compatibility
13. Troubleshooting
14. Related Documentation

​

Quick Start

​

Import Gestures

import {
  // Phase 1 — Hooks
  useSwipeToDismiss,
  useSwipeActions,
  usePullToRefresh,
  useEdgeSwipe,
  // Phase 1 — Components
  SwipeableSheet,
  SwipeableListItem,
  PullToRefresh,
  MobilePullToRefresh,
  // Phase 2 — Preferences / haptics / analytics
  useGesturePreferences,
  useHapticFeedback,
  useGestureAnalytics,
  useGestureIntegration,
  // Phase 3 — Pinch & multi-touch
  usePinchToZoom,
  useMultiTouch,
  useDoubleTap,
  ZoomableImage,
  ZoomableImageViewer,
  // Phase 3 — Custom gestures
  useCustomGesture,
  CustomGestureProvider,
  useCustomGestureRegistry,
  // Constants
  GESTURE_THRESHOLDS,
  ANIMATION_CONFIG,
  ACTION_COLORS,
  GESTURE_ARIA_LABELS,
  // Shared list-item shell (recommended)
  SwipeableCardShell,
} from '@/platform/gestures';

​

Basic Usage

// Swipe-to-dismiss bottom sheet
<SwipeableSheet open={open} onOpenChange={setOpen} side="bottom" ariaLabelledBy="sheet-title">
  <h2 id="sheet-title">Sheet title</h2>
</SwipeableSheet>

// Mobile-only swipe-revealed actions on a list card (recommended pattern)
<SwipeableCardShell
  rightActions={[{ id: 'delete', label: 'Delete', icon: 'Trash2', colorClass: 'destructive', onClick: handleDelete }]}
>
  <NotificationItem ... />
</SwipeableCardShell>

// Pull-to-refresh that auto-disables on desktop / pointer-fine devices
<MobilePullToRefresh onRefresh={async () => await refetch()}>
  <ScrollableList />
</MobilePullToRefresh>

​

Hooks Catalog

​

Phase 1 — core gesture hooks

​

Phase 2 — preferences, haptics, analytics

​

Phase 3 — advanced gestures

​

Components Catalog

​

Why SwipeableCardShell?

import { SwipeableCardShell } from '@/platform/gestures';

<SwipeableCardShell
  leftActions={[{ id: 'complete', label: 'Complete', icon: 'Check', colorClass: 'success', onClick: onComplete }]}
  rightActions={[{ id: 'delete', label: 'Delete', icon: 'Trash2', colorClass: 'destructive', onClick: onDelete }]}
>
  <MyCard ... />
</SwipeableCardShell>

• On desktop (or when enabled === false): renders children unwrapped (zero gesture overhead).
• On mobile: wraps with SwipeableListItem and forwards all action / threshold / className props.
• Honors useGestureIntegration automatically (because the underlying hook does).

​

Decision Tree — When to Use Each Pattern

Is this a list/row that needs row-level actions?
├─ Yes → SwipeableCardShell (mobile-only, auto-disables on desktop)
└─ No
   ├─ Bottom sheet / drawer that should swipe-to-close?
   │  └─ SwipeableSheet (also adds drag handle on bottom side)
   ├─ Scrollable list / page that should refresh on pull-down?
   │  └─ MobilePullToRefresh (auto-mobile)
   ├─ Detail/edit page where left-edge swipe should go back?
   │  └─ Already wired into the mobile <main>; no per-page work needed
   ├─ Image / media that should pinch-zoom?
   │  └─ ZoomableImage or ZoomableImageViewer (full-screen modal)
   └─ Anything else (custom pattern, multi-finger, double-tap)
      └─ Phase 3 hooks (use sparingly — almost everything is covered above)

​

When NOT to use gestures

• ❌ Forms with unsaved changes (use a confirmation dialog).
• ❌ Destructive actions without undo (require confirmation or 5-second toast undo).
• ❌ Complex multi-step interactions (use a wizard).
• ❌ Desktop-only interfaces (most gestures auto-disable, but don’t go out of your way).
• ❌ When keyboard-only users are the primary audience for that surface.

​

User Preferences (Phase 2)

interface GesturePreferences {
  enabled: boolean;                      // master toggle
  sensitivity: 'low' | 'medium' | 'high';
  sensitivity_multiplier: number;        // 0.5 – 2.0
  haptic_feedback: {
    enabled: boolean;
    intensity: 'none' | 'light' | 'medium' | 'strong';
    patterns: { success: boolean; error: boolean; warning: boolean };
  };
  gesture_toggles: {
    swipe_to_dismiss: boolean;
    swipe_actions: boolean;
    pull_to_refresh: boolean;
    edge_swipe: boolean;
  };
}

useSwipeToDismiss → useGestureIntegration ─┬─ preferences.enabled
useSwipeActions   ─┘                       ├─ gesture_toggles.<type>
usePullToRefresh  ─┐                       ├─ sensitivity_multiplier (clamped 0.1–5.0)
useEdgeSwipe      ─┘                       └─ haptic_feedback.intensity / patterns

​

Haptic Feedback (Phase 2)

import { useHapticFeedback } from '@/platform/gestures';

const { vibrate } = useHapticFeedback();
vibrate('success');  // or 'tap' | 'selection' | 'warning' | 'error' | 'longPress'

​

Analytics (Phase 2)

• Append-only, user-scoped RLS (a user can only insert their own rows).
• No PHI: only gesture_type, subtype (e.g. 'left', 'right'), success: boolean, device_type, timestamp. Never patient names / MRNs / IDs.
• Batched client-side: 5-second flush + visibilitychange + beforeunload flush.

Privacy note: Do not pass any user-typed input or entity identifiers to the optional subtype parameter of trackGestureEvent. The TypeScript signature constrains it to a SwipeDirection-shaped value; do not widen it.

​

Pinch & Multi-touch (Phase 3)

import { ZoomableImage } from '@/platform/gestures';

<ZoomableImage src={signedUrl} alt="Patient ID card" maxScale={4} />

• Image lightboxes (PF-98 headshot viewer; document image viewer in @/platform/documents).
• Charts you want to zoom into.
• Signature previews.

​

Custom Gesture Registry (Phase 3)

<CustomGestureProvider>
  <YourFeature />
</CustomGestureProvider>

const registry = useCustomGestureRegistry();
useEffect(() => {
  registry.register({
    id: 'circle',
    pattern: { type: 'shape', shape: 'circle' },
    onMatch: () => console.log('Circle drawn'),
  });
  return () => registry.unregister('circle');
}, [registry]);

​

Accessibility & Reduced Motion

​

WCAG compliance

​

Keyboard alternatives

​

Reduced-motion behavior

• Snap-back: transition: none (jump cut).
• Dismiss animation: 0 ms (immediate cleanup).
• Reveal animation: 0 ms.

​

Performance Guidelines

​

Best practices

1. Use CSS transforms only. All hooks emit transform: translateX/Y(...) and never modify width/height/left/top.
2. Avoid re-renders during drag. useDrag callbacks update component state via setState; keep the consumer subtree small.
3. Don’t add will-change unless DevTools shows compositing issues — Safari has known memory regressions.
4. Batch onRefresh side effects. Resolve the promise before triggering query invalidation; the hook will hold the spinner until your promise settles.

​

Browser Compatibility

​

Known limitations

1. iOS Safari edge-swipe collision. The native iOS edge-back gesture lives in roughly the leftmost 30 px. Our useEdgeSwipe zone is 20 px. On iOS the native gesture wins — that’s fine; users still get the expected behavior, it’s just routed through the browser instead of our hook.
2. iOS Vibration API. Permanently unsupported. useHapticFeedback is a no-op there.
3. Android system back gesture (Android 10+). Coexists with our hooks; no conflicts seen in QA.

​

Troubleshooting

​

Gesture isn’t firing

1. Check the user has not disabled the gesture in /settings/gestures.
2. Check the enabled prop / option (default is true).
3. Check the threshold isn’t too high; lower it temporarily and retest.
4. Make sure touch-action on a parent isn’t pan-x/pan-y blocking the relevant axis.
5. Try wrapping the parent in <MobilePullToRefresh enabled> to confirm touch handling is reaching the area.

​

Janky animation

1. Confirm only transform / opacity change during the gesture.
2. Open Chrome DevTools → Rendering → “Paint flashing” to spot non-composited repaints.
3. Verify the consumer subtree isn’t re-rendering on every progress tick.

​

Gesture conflicts with native scroll

1. Pull-to-refresh only fires at scrollTop === 0.
2. Edge-swipe only fires inside the 20 px left zone.
3. Sheet swipe-to-dismiss respects axis (pan-x or pan-y).

​

Keyboard shortcut doesn’t work

1. Ensure the swipeable container is focusable (tabIndex={0} or focusable child).
2. Verify no parent calls event.stopPropagation() on key events.
3. For destructive actions, the keyboard handler is on the action button, not the row — focus the button via Tab.

​

Related Documentation

• PF-37 Specification
• PF-37 Phase 2/3 Integration Doc
• Mobile Navigation Guide
• UI/UX Standards
• Platform Gestures README
• Gesture Preferences Page (UI)
• Gesture Analytics Page (UI)
• WCAG 2.5.1 Pointer Gestures
• @use-gesture/react documentation