An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
'use client';
/**
* @file useSegmentedTouchTracking.ts
* @input The radiogroup element, the selection motion controller and whether
* the control is enabled
* @output useSegmentedTouchTracking (a press of any pointer, landing to
* lift, and its ClickWait), and segmentTargetAt, measureSegments,
* measureLiftArea and liftTargetAt, the segment a pointer counts for
* @position Internal to SegmentedControl; drives useSegmentedSelectionMotion.ts
*
* SYNC: When modified, update:
* - /packages/core/src/SegmentedControl/useSegmentedSelectionMotion.ts
* - /packages/core/src/SegmentedControl/__tests__/SegmentedControl.interaction.browser.spec.ts
*/
import {useRef, useState, type RefObject} from 'react';
import {PanGestureRecognizer} from '../gestures/PanGestureRecognizer';
import {useGestureRecognizer} from '../gestures/useGestureRecognizer';
import {usePressTracker} from '../gestures/usePressTracker';
import {
createActionGroupTracker,
type ActionGroupTarget,
type ActionGroupTracker,
} from '../hooks/actionGroupTracker';
import {lockSelection} from '../gestures/selectionLock';
import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
import {awaitBrowserClick, clickForLift} from '../utils/browserClickWait';
import {HIT_INSET_PROPERTIES, type HitInsets} from '../utils/hitArea';
import {
SEGMENT_SELECTOR,
type SegmentedSelectionMotion,
} from './useSegmentedSelectionMotion';
/**
* A tap's click still to come. Until it runs, a focus move the tap causes
* selects nothing. A key press, the next press or a cancel ends the wait.
*/
export interface ClickWait {
readonly isAwaiting: () => boolean;
readonly end: () => void;
}
/** A ref to nothing: hooks given it attach nothing. */
const DETACHED: RefObject<HTMLElement | null> = {current: null};
/** The control's box as measured when the finger landed: viewport px. */
export interface ControlBounds {
readonly left: number;
readonly top: number;
readonly right: number;
readonly bottom: number;
}
/** A segment as measured when the finger landed: its viewport span, px. */
export interface SegmentSpan {
readonly element: HTMLElement;
readonly left: number;
readonly right: number;
}
/** Every segment of `track`, disabled ones included, measured once. */
export function measureSegments(track: HTMLElement): SegmentSpan[] {
return Array.from(
track.querySelectorAll<HTMLElement>(SEGMENT_SELECTOR),
element => {
const rect = element.getBoundingClientRect();
return {element, left: rect.left, right: rect.right};
},
);
}
function isDisabled(element: HTMLElement): boolean {
return (
element.hasAttribute('disabled') ||
element.getAttribute('aria-disabled') === 'true'
);
}
/**
* The segment a finger at viewport `x` counts for: the one under it, else the
* nearest. A gap between two segments splits at its middle, as UIKit's
* segments share an edge. Past the ends, the end segment counts. The result is
* null when that segment is disabled.
*/
export function segmentTargetAt(
x: number,
segments: ReadonlyArray<SegmentSpan>,
): HTMLElement | null {
let best: SegmentSpan | null = null;
let distance = Infinity;
for (const segment of segments) {
const d = Math.max(segment.left - x, 0, x - segment.right);
if (d < distance) {
distance = d;
best = segment;
}
}
return best != null && !isDisabled(best.element) ? best.element : null;
}
/**
* The segment a lift at viewport (`x`, `y`) commits: inside any box of the
* control's lift `area`, the one `segmentTargetAt` counts it for; outside
* them, none. A press that slides off cancels, because the control selects
* rather than toggles: a second press would not undo it.
*/
export function liftTargetAt(
x: number,
y: number,
area: ReadonlyArray<ControlBounds>,
segments: ReadonlyArray<SegmentSpan>,
): HTMLElement | null {
const isInside = area.some(
box => x >= box.left && x <= box.right && y >= box.top && y <= box.bottom,
);
return isInside ? segmentTargetAt(x, segments) : null;
}
const NO_AREA: ReadonlyArray<ControlBounds> = [];
/** A measured hit inset on `element`, px (0 when none is written). */
function hitInset(element: HTMLElement, side: keyof HitInsets): number {
const value = Number.parseFloat(
element.style.getPropertyValue(HIT_INSET_PROPERTIES[side]),
);
return Number.isFinite(value) ? value : 0;
}
/**
* The boxes a lift may commit in: the control's own box, and each segment's
* box grown by its own touch hit band (utils/hitArea), so a tap on a band
* selects its segment. Each band is kept apart: a band a neighbor clamped
* stays clamped, though another segment's band reaches further. Under a fine
* pointer no band is written, and the segments sit inside the control's box.
*/
export function measureLiftArea(
track: HTMLElement,
segments: ReadonlyArray<SegmentSpan>,
): ReadonlyArray<ControlBounds> {
const {left, top, right, bottom} = track.getBoundingClientRect();
return [
{left, top, right, bottom},
...segments.map(({element}) => {
const box = element.getBoundingClientRect();
return {
left: box.left - hitInset(element, 'left'),
top: box.top - hitInset(element, 'top'),
right: box.right + hitInset(element, 'right'),
bottom: box.bottom + hitInset(element, 'bottom'),
};
}),
];
}
/**
* Tracks a press on the control as UIKit's segmented control does. The press
* tracker reports the press from landing to lift. It never claims the
* pointer, so a vertical drag still scrolls the page. A horizontal pan
* carries the lens. It claims the pointer only past its slop, and the lift
* still ends the press.
*
* The lift decides the segment, wherever the press began. Inside the control,
* or on a segment's touch hit band, the segment under the pointer counts,
* else the nearest one. Outside them, nothing counts.
*
* A tap gets the browser's own click. A drag gets no click from the browser,
* so the tracker clicks the segment at the lift. Either way the item's
* `onClick` runs once and can cancel the selection. A mouse and a pen are
* tracked as a finger is. Keyboard and assistive technology keep the click.
*/
export function useSegmentedTouchTracking(
trackRef: RefObject<HTMLElement | null>,
motion: SegmentedSelectionMotion,
isEnabled: boolean,
): ClickWait {
/** The horizontal pan began for this touch: it is a drag, not a tap. */
const isDraggingRef = useRef(false);
/** The segments as the finger found them (disabled ones too). */
const segmentsRef = useRef<SegmentSpan[]>([]);
/** The lift area as the finger found it: a lift outside it cancels. */
const areaRef = useRef<ReadonlyArray<ControlBounds>>(NO_AREA);
const trackerRef = useRef<ActionGroupTracker | null>(null);
const tracker = (trackerRef.current ??= createActionGroupTracker(() => ({
roots: () => [trackRef.current],
itemSelector: SEGMENT_SELECTOR,
highlightExpansion: 0,
// The press controller writes the shared press paint on the touched
// segment, as everywhere under a finger. The tracker paints nothing of its
// own. A held lens shows the selected face.
paintsHighlight: false,
resolveTarget: (
x: number,
y: number,
_targets: ReadonlyArray<ActionGroupTarget>,
) => liftTargetAt(x, y, areaRef.current, segmentsRef.current),
onActivated: (item, cancelled) => {
const track = trackRef.current;
const value = item.dataset.value;
if (track != null && value != null) {
motion.clicked(track, value, cancelled);
}
},
swallowsNativeClick: true,
})));
/** Click waits still running: an unmount ends them. */
const pendingClicksRef = useRef<Set<() => void>>(new Set());
/**
* A tap lifted and its click has not run. After a direct click, the
* browser's late copy can still move focus, so the wait then lasts until the
* next key or press.
*/
const clickToComeRef = useRef(false);
const [clickWait] = useState<ClickWait>(() => ({
isAwaiting: () => clickToComeRef.current,
end: () => {
clickToComeRef.current = false;
},
}));
// Ends the tracker's window listeners and any click wait on unmount.
useIsomorphicLayoutEffect(() => {
const pendingClicks = pendingClicksRef.current;
return () => {
tracker.dispose();
clickWait.end();
for (const end of [...pendingClicks]) {
end();
}
};
}, [tracker, clickWait]);
// Every pointer type is tracked. A disabled control attaches nothing.
const attachRef = isEnabled ? trackRef : DETACHED;
usePressTracker(attachRef, {
isEnabled: () => isEnabled,
onControlEvent: (event, touch) => {
const track = trackRef.current;
if (track == null) {
return;
}
switch (event) {
case 'touchDown': {
clickWait.end();
isDraggingRef.current = false;
segmentsRef.current = measureSegments(track);
areaRef.current = measureLiftArea(track, segmentsRef.current);
tracker.begin(touch.x, touch.y);
motion.begin(track, tracker.beganOn, touch.pointerType === 'touch');
break;
}
case 'touchUpInside':
case 'touchUpOutside': {
// The lift decides, wherever the press began. A lift outside the
// control commits nothing.
tracker.move(touch.x, touch.y);
const lifted = tracker.highlighted;
const isTap =
event === 'touchUpInside' &&
!isDraggingRef.current &&
lifted != null &&
lifted === tracker.beganOn;
const value = motion.release(lifted);
if (value != null && isTap && lifted != null) {
// A tap: the browser's own click commits it.
tracker.cancel();
clickToComeRef.current = true;
const pending = pendingClicksRef.current;
const endWait = awaitBrowserClick(lifted, {
onClicked: isCancelled => {
pending.delete(endWait);
clickWait.end();
motion.clicked(track, value, isCancelled);
},
onNoClick: () => {
pending.delete(endWait);
motion.clicked(track, value, clickForLift(lifted));
},
});
pending.add(endWait);
} else if (value != null) {
// No click comes from the browser for a drag: the segment's own
// click, inside the lift's event; its onClick may veto it.
tracker.end();
} else {
tracker.cancel();
}
break;
}
case 'touchCancel':
clickWait.end();
tracker.cancel();
motion.cancel();
break;
case 'touchDragInside':
case 'touchDragOutside':
case 'touchDragEnter':
case 'touchDragExit':
// The horizontal pan carries the lens.
break;
}
},
});
useGestureRecognizer(
attachRef,
() =>
new PanGestureRecognizer({
name: 'segmented-control-drag',
direction: 'horizontal',
cancelsTouchesInView: false,
// No title is selectable under a held finger, as in UIKit. A hold on
// the track does something: a drag carries the lens and commits where
// it lifts. So this recognizer brings the lock, and the host turns off
// text selection and the callout on the track while a finger is down.
selectionLock: lockSelection,
}),
recognizer => {
if (recognizer.state === 'began') {
isDraggingRef.current = true;
}
if (recognizer.state === 'began' || recognizer.state === 'changed') {
const {x, y} = recognizer.location();
// The lens chases the finger, then the tracker moves the highlight.
motion.drag(x);
tracker.move(x, y);
}
},
{isEnabled},
);
return clickWait;
}