panelui-native 0.51.1 → 0.53.0

package/src/components/tabs/index.tsx

@@ -140,6 +140,16 @@ const MEASURE_WIDTH = 400;
 
 export type TabsVariant = 'segmented' | 'underline' | 'pill' | 'expanding';
 
+/**
+ * How much of an inactive panel survives a switch away from it.
+ *
+ * `false` unmounts it. `true` keeps it mounted but takes it out of layout, so
+ * it costs nothing to have around. `'measured'` keeps it laid out at full size
+ * as well — the expensive option, and the only one a child that sizes itself
+ * from its parent can be built inside while it is hidden.
+ */
+export type TabsKeepMounted = boolean | 'measured';
+
 const tabsVariants = tv({
   slots: {
     list: 'flex-row',
@@ -246,7 +256,7 @@ interface TabsContextValue {
   variant: TabsVariant;
   scrollable: boolean;
   setScrollable: (scrollable: boolean) => void;
-  keepMounted: boolean;
+  keepMounted: TabsKeepMounted;
   swipeable: boolean;
   /**
    * How far the visible panel is displaced from its resting place, in points.
@@ -292,8 +302,29 @@ export interface TabsProps extends ViewProps {
    * Keep inactive panels mounted and hidden instead of unmounting them, so a
    * scroll position or a half-filled form survives a switch away and back.
    * Costs the render of every panel up front.
+   *
+   * `true` hides a kept panel with `display: none`, which also takes it out of
+   * layout: it is mounted, but it has no size. That is what makes it cheap, and
+   * it is enough for a panel whose content sizes itself — a column of views, a
+   * form, a `ScrollView` of known children.
+   *
+   * It is *not* enough for a child that decides what to render by measuring the
+   * space it has been given. A virtualised list asks its parent how tall it is
+   * and fills that many rows; asked inside a panel of zero height it answers
+   * zero rows, and the whole first render still lands on the frame the tab
+   * becomes visible — the stall this flag looks like it should have avoided.
+   *
+   * `'measured'` is for that case. A kept panel stays laid out at the full size
+   * of the tab set, and is hidden by not being drawn rather than by being
+   * removed from layout: a list inside it measures, renders its rows and
+   * settles while it is still hidden, so becoming visible costs nothing.
+   *
+   * The trade is real and is why it is not the default — every kept panel lays
+   * out and draws, up front and on every size change, so a five-tab set builds
+   * five panels' worth of rows to show one. Reach for it when a panel is slow
+   * to appear and its content is virtualised; leave it at `true` otherwise.
    */
-  keepMounted?: boolean;
+  keepMounted?: TabsKeepMounted;
   /**
    * Move between tabs by dragging sideways on the panel, as well as by
    * pressing the triggers.
@@ -310,7 +341,9 @@ export interface TabsProps extends ViewProps {
    * something is moving*, so a panel that is slow to build stops being a pause
    * before it appears and starts being a stutter in the movement. If a swipe
    * feels heavier than a press on the same tab set, the panel is expensive to
-   * mount; `keepMounted` is the answer, not turning this off.
+   * mount — and the answer is whichever `keepMounted` actually keeps its
+   * content built, which for a virtualised list is `'measured'` rather than
+   * `true`. Turning this off hides the cost rather than removing it.
    */
   swipeable?: boolean;
   children: ReactNode;
@@ -928,11 +961,41 @@ function TabsContent({ className, value, children, style, ...props }: TabsConten
 
   if (!active && !context.keepMounted) return null;
 
+  /*
+   * Under `keepMounted='measured'` a hidden panel keeps its size instead of
+   * losing it. It is taken out of the flow and stretched over the tab set, so
+   * it is laid out at the same size as the visible panel without contributing
+   * its height to the parent, and it is hidden by being transparent rather
+   * than by `display: none`.
+   *
+   * That distinction is the whole point: `display: none` lays a panel out at
+   * zero size, and a child that sizes itself from its parent — a virtualised
+   * list deciding how many rows to render — renders nothing at all inside one.
+   * Given a real size while still hidden, it builds its rows now rather than on
+   * the frame the tab is switched to.
+   *
+   * `opacity: 0` is set once and never animated, so it costs a composite and
+   * not a per-frame redraw; the negative `zIndex` keeps it behind the visible
+   * panel rather than over it, whatever order the panels are written in.
+   */
+  const measured = context.keepMounted === 'measured';
+  const hiddenStyle = measured
+    ? ({
+        position: 'absolute',
+        top: 0,
+        left: 0,
+        right: 0,
+        bottom: 0,
+        opacity: 0,
+        zIndex: -1,
+      } as const)
+    : ({ display: 'none' } as const);
+
   /*
    * Hidden rather than unmounted under `keepMounted`, and hidden thoroughly:
-   * `display: none` takes it out of layout, and the accessibility props take
-   * it out of the reading order too. A screen reader walking through three
-   * panels of a tab set it cannot see is worse than no tabs at all.
+   * it is not drawn, it takes no touches, and the accessibility props take it
+   * out of the reading order too. A screen reader walking through three panels
+   * of a tab set it cannot see is worse than no tabs at all.
    */
   const panel = (
     <Animated.View
@@ -953,19 +1016,21 @@ function TabsContent({ className, value, children, style, ...props }: TabsConten
         // window would be most of the way across it.
         //
         // Zero is ignored. Every panel reports into the same value, and a
-        // kept-mounted one is `display: none` — it measures as nothing, and
-        // letting it say so would leave the visible panel with no width.
+        // panel kept with `display: none` measures as nothing — letting it say
+        // so would leave the visible panel with no width. A `'measured'` one
+        // is stretched over the tab set and reports the same width as the
+        // visible panel, so it is agreeing rather than overwriting.
         const measured = event.nativeEvent.layout.width;
         if (measured > 0) width.value = measured;
       }}
       /*
        * The follow style goes on the panel that is moving, and only that one.
-       * Under `keepMounted` every other panel is `display: none` and cannot be
-       * seen to move — but an animated style still subscribes them all to the
-       * offset, so a five-tab set ran five mappers per frame to reposition four
-       * views nobody was looking at.
+       * Under `keepMounted` every other panel is hidden and cannot be seen to
+       * move — but an animated style still subscribes them all to the offset,
+       * so a five-tab set ran five mappers per frame to reposition four views
+       * nobody was looking at.
        */
-      style={[!active && { display: 'none' }, swipeable && active && followStyle, style]}
+      style={[!active && hiddenStyle, swipeable && active && followStyle, style]}
       pointerEvents={active ? 'auto' : 'none'}
       accessibilityElementsHidden={!active}
       importantForAccessibility={active ? 'auto' : 'no-hide-descendants'}
@@ -976,9 +1041,10 @@ function TabsContent({ className, value, children, style, ...props }: TabsConten
     </Animated.View>
   );
 
-  // Only the visible panel carries the gesture. A kept-mounted panel is
-  // `display: none` and takes no touches anyway, but attaching a detector to
-  // each of them would put several competing recognisers in the same tree.
+  // Only the visible panel carries the gesture. A kept-mounted panel takes no
+  // touches anyway — `pointerEvents` is off on it whichever way it is hidden —
+  // but attaching a detector to each of them would put several competing
+  // recognisers in the same tree.
   if (!swipeable || !active) return panel;
 
   return <GestureDetector gesture={pan}>{panel}</GestureDetector>;

package/src/components/time-picker/index.tsx

@@ -153,6 +153,58 @@ const timePickerVariants = tv({
   },
 });
 
+/**
+ * The times a face may offer, and where a value sits among them.
+ *
+ * A scale or a list that runs the whole day while the picker only accepts part
+ * of it is a control that invites a choice in order to refuse it: the finger
+ * reaches the end, the root clamps, and the row springs back to where it
+ * started having said nothing about why. Offering only what will be accepted
+ * means the end of the scale *is* the last bookable time, and dragging to it
+ * picks it.
+ *
+ * The position is the nearest row rather than a division, because a filtered
+ * list no longer starts at midnight and its indices are its own.
+ */
+function useBoundedTimes(
+  minuteStep: number,
+  minTime: TimeValue | undefined,
+  maxTime: TimeValue | undefined,
+  value: TimeValue
+) {
+  const times = useMemo(() => {
+    const all = timesOfDay(minuteStep);
+    if (!minTime && !maxTime) return all;
+    const low = minTime ? timeToMinutes(minTime) : Number.NEGATIVE_INFINITY;
+    const high = maxTime ? timeToMinutes(maxTime) : Number.POSITIVE_INFINITY;
+    const kept = all.filter((time) => {
+      const at = timeToMinutes(time);
+      return at >= low && at <= high;
+    });
+    // A span too narrow to contain a single step would leave nothing to scroll.
+    // The bounds are the caller's mistake there, and an empty face is worse.
+    return kept.length > 0 ? kept : all;
+  }, [minuteStep, minTime, maxTime]);
+
+  const index = useMemo(() => {
+    const target = timeToMinutes(value);
+    let nearest = 0;
+    let smallest = Number.POSITIVE_INFINITY;
+    for (let i = 0; i < times.length; i += 1) {
+      const time = times[i];
+      if (!time) continue;
+      const away = Math.abs(timeToMinutes(time) - target);
+      if (away < smallest) {
+        smallest = away;
+        nearest = i;
+      }
+    }
+    return nearest;
+  }, [times, value]);
+
+  return { times, index };
+}
+
 /* -------------------------------------------------------------------------- */
 /* One snapping column                                                        */
 /* -------------------------------------------------------------------------- */
@@ -161,6 +213,12 @@ interface ColumnProps<T> {
   items: readonly T[];
   /** Index of the selected item. Drives the scroll position. */
   index: number;
+  /**
+   * Bumped every time the root has looked at a reported time, whether or not
+   * it accepted one. See `Column`'s resync effect for why the index alone is
+   * not enough to know a column is resting somewhere it should not be.
+   */
+  syncToken: number;
   onIndexChange: (index: number) => void;
   label: (item: T) => string;
   disabled?: boolean;
@@ -183,6 +241,7 @@ interface ColumnProps<T> {
 function Column<T>({
   items,
   index,
+  syncToken,
   onIndexChange,
   label,
   disabled,
@@ -208,24 +267,135 @@ function Column<T>({
     offset.value = event.contentOffset.y;
   });
 
+  /*
+   * Whether the list is still moving, and whether it owes itself a correction
+   * once it stops.
+   *
+   * Nothing may scroll the column programmatically while it is gliding. A
+   * `scrollTo` issued against a running deceleration fights it, and the list
+   * stops dead somewhere between two rows and takes no further touches — a
+   * flick reads as the wheel freezing. So a correction that arrives mid-flight
+   * is remembered rather than performed, and applied at the moment the list
+   * comes to rest.
+   */
+  const moving = useRef(false);
+  const owedResync = useRef(false);
+  const settleTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  // The effect below closes over `index`; `atRest` runs from a scroll handler
+  // long after that render, so it needs the current one rather than the one it
+  // captured.
+  const latestIndex = useRef(index);
+  latestIndex.current = index;
+
+  const cancelTimer = useCallback(() => {
+    if (settleTimer.current === null) return;
+    clearTimeout(settleTimer.current);
+    settleTimer.current = null;
+  }, []);
+
+  /*
+   * Unanimated, and that is load-bearing rather than a matter of taste.
+   *
+   * An animated programmatic scroll raises the same begin and end momentum
+   * events a finger does, so the correction reports itself as a gesture, which
+   * commits, which corrects again — the column rides up and down and never
+   * settles. Placing it outright raises nothing, so the correction ends where
+   * it starts. It is also the honest movement: this is the row that was always
+   * holding, not a journey to it.
+   */
+  const snapTo = useCallback((to: number) => {
+    resting.current = to;
+    ref.current?.scrollTo({ y: to * ROW_HEIGHT, animated: false });
+  }, []);
+
+  /*
+   * Runs on the token as well as the index, and that is the whole point.
+   *
+   * A reported row can be refused — by `minTime`, by `maxTime`, or by a step
+   * the root rounds to. When it is, the value does not change, so `index` does
+   * not change either, and an effect watching the index alone never learns that
+   * anything happened. The column was left resting on a row the picker had not
+   * accepted, showing one time while reporting another, and no later drag could
+   * put it right: it had already recorded that row as where it sits.
+   *
+   * The token changes on every reported time, refused or not, so the column is
+   * always told to check itself, and the check is the same one it always was.
+   */
   useEffect(() => {
     if (index === resting.current) return;
-    resting.current = index;
-    ref.current?.scrollTo({ y: index * ROW_HEIGHT, animated: true });
-  }, [index]);
-
-  const settle = useCallback(
-    (event: NativeSyntheticEvent<NativeScrollEvent>) => {
-      const next = Math.round(event.nativeEvent.contentOffset.y / ROW_HEIGHT);
+    if (moving.current) {
+      owedResync.current = true;
+      return;
+    }
+    snapTo(index);
+  }, [index, syncToken, snapTo]);
+
+  /** The list has genuinely stopped. Pay off a correction if one is owed. */
+  const atRest = useCallback(() => {
+    cancelTimer();
+    moving.current = false;
+    if (!owedResync.current) return;
+    owedResync.current = false;
+    if (latestIndex.current !== resting.current) snapTo(latestIndex.current);
+  }, [cancelTimer, snapTo]);
+
+  const startMoving = useCallback(() => {
+    cancelTimer();
+    moving.current = true;
+  }, [cancelTimer]);
+
+  const settleAt = useCallback(
+    (y: number) => {
+      const next = Math.round(y / ROW_HEIGHT);
       const clamped = Math.min(Math.max(next, 0), items.length - 1);
       if (clamped === resting.current) return;
       resting.current = clamped;
+      /*
+       * This report supersedes any correction that was owed. The correction was
+       * worked out against a row the column has now left, and paying it off
+       * afterwards would drag the column back to a row nobody chose.
+       */
+      owedResync.current = false;
       selectionTick();
       onIndexChange(clamped);
     },
     [items.length, onIndexChange]
   );
 
+  /*
+   * A flick reports once, when it stops — not twice.
+   *
+   * Momentum begins a frame *after* the drag ends, so the end of a drag cannot
+   * tell a flick from a release by itself. It arms a short timer, and momentum
+   * starting cancels it; a drag that stops dead has no momentum to cancel it
+   * and settles on the timer. Reporting the release offset directly, as this
+   * used to, committed a row the finger was in the middle of flying past, and
+   * the picker then had two answers for one gesture.
+   */
+  const onDragEnd = useCallback(
+    (event: NativeSyntheticEvent<NativeScrollEvent>) => {
+      const y = event.nativeEvent.contentOffset.y;
+      cancelTimer();
+      settleTimer.current = setTimeout(() => {
+        settleAt(y);
+        atRest();
+      }, 80);
+    },
+    [atRest, cancelTimer, settleAt]
+  );
+
+  const onMomentumEnd = useCallback(
+    (event: NativeSyntheticEvent<NativeScrollEvent>) => {
+      cancelTimer();
+      settleAt(event.nativeEvent.contentOffset.y);
+      atRest();
+    },
+    [atRest, cancelTimer, settleAt]
+  );
+
+  useEffect(() => cancelTimer, [cancelTimer]);
+
   const selectedItem = items[index];
 
   return (
@@ -242,11 +412,14 @@ function Column<T>({
       snapToOffsets={snapToOffsets}
       disableIntervalMomentum
       decelerationRate="fast"
-      /* Both, because only one of them fires: a flick ends in momentum, and a
-         slow drag released on a snap point ends without any. Missing the drag
-         case leaves a column that looks settled and has reported nothing. */
-      onMomentumScrollEnd={settle}
-      onScrollEndDrag={settle}
+      /* Both ends are wired, because only one of them fires: a flick ends in
+         momentum, and a slow drag released on a snap point ends without any.
+         Missing the drag case leaves a column that looks settled and has
+         reported nothing. */
+      onScrollBeginDrag={startMoving}
+      onScrollEndDrag={onDragEnd}
+      onMomentumScrollBegin={startMoving}
+      onMomentumScrollEnd={onMomentumEnd}
       /* The rows fade rather than unmount, so a recycled row would pop in at
          full opacity mid-scroll. A day of minutes is 60 views; keeping them
          all is cheaper than the flicker. */
@@ -284,11 +457,19 @@ function ColumnRow({
 }) {
   const slots = timePickerVariants();
 
+  /*
+   * The row either side of the centre stays a number you can read. It used to
+   * drop to just over half opacity and shrink by an eighth at one row out,
+   * which on a settling column reads as the digits smearing rather than as
+   * depth — and the neighbours are exactly the rows being compared against
+   * while choosing. The far rows still fall away, since that fall is what makes
+   * the column look like a wheel instead of a list.
+   */
   const style = useAnimatedStyle(() => {
     const distance = Math.abs(offset.value / ROW_HEIGHT - index);
     return {
-      opacity: interpolate(distance, [0, 1, 2], [1, 0.55, 0.2], 'clamp'),
-      transform: [{ scale: interpolate(distance, [0, 1], [1, 0.88], 'clamp') }],
+      opacity: interpolate(distance, [0, 1, 2], [1, 0.75, 0.25], 'clamp'),
+      transform: [{ scale: interpolate(distance, [0, 1], [1, 0.94], 'clamp') }],
     };
   });
 
@@ -311,8 +492,22 @@ function ColumnRow({
 interface FaceProps {
   value: TimeValue;
   onValueChange: (value: TimeValue) => void;
+  /**
+   * Bumped every time the root has looked at a reported time, so a face can
+   * tell "nothing changed because nothing was reported" from "nothing changed
+   * because what I reported was refused". Only the scrolling faces use it.
+   */
+  syncToken: number;
   hourCycle: HourCycle;
   minuteStep: number;
+  /**
+   * The span the picker will accept, so a face that lists whole times can
+   * offer only those. A face that does not list whole times — the wheel, whose
+   * columns each hold one part of one — ignores these and is corrected by the
+   * root instead.
+   */
+  minTime?: TimeValue;
+  maxTime?: TimeValue;
   locale?: string;
   disabled?: boolean;
   /** Ruler face only — the other two never draw a number of their own. */
@@ -322,6 +517,7 @@ interface FaceProps {
 function WheelFace({
   value,
   onValueChange,
+  syncToken,
   hourCycle,
   minuteStep,
   locale,
@@ -376,7 +572,17 @@ function WheelFace({
   const setMeridiem = useCallback(
     (index: number) => {
       const next = index === 0 ? 'am' : 'pm';
-      if (next === meridiemOf(value.hour)) return;
+      /*
+       * Reported even when the column came back to the half it started on.
+       * Staying silent there left the root with nothing to answer, so a column
+       * dragged away and released short of a swap had no way to be told to sit
+       * back down — the other two columns had the same hole, and this is the
+       * same fix.
+       */
+      if (next === meridiemOf(value.hour)) {
+        onValueChange({ ...value });
+        return;
+      }
       onValueChange({
         ...value,
         hour: next === 'pm' ? value.hour + 12 : value.hour - 12,
@@ -397,6 +603,7 @@ function WheelFace({
       <Column
         items={hours}
         index={hourIndex}
+        syncToken={syncToken}
         onIndexChange={setHour}
         label={(hour) => (hourCycle === 24 ? padTwo(hour) : String(hour))}
         disabled={disabled}
@@ -406,6 +613,7 @@ function WheelFace({
       <Column
         items={minutes}
         index={minuteIndex}
+        syncToken={syncToken}
         onIndexChange={setMinute}
         label={padTwo}
         disabled={disabled}
@@ -416,6 +624,7 @@ function WheelFace({
         <Column
           items={meridiems}
           index={meridiemIndex}
+          syncToken={syncToken}
           onIndexChange={setMeridiem}
           label={(entry) => entry}
           disabled={disabled}
@@ -535,17 +744,16 @@ function handEnd(turn: number, length: number) {
 function ClockFaceLayout({
   value,
   onValueChange,
+  syncToken,
   hourCycle,
   minuteStep,
+  minTime,
+  maxTime,
   locale,
   disabled,
 }: FaceProps) {
   const slots = timePickerVariants();
-  const times = useMemo(() => timesOfDay(minuteStep), [minuteStep]);
-  const index = Math.min(
-    times.length - 1,
-    Math.round(timeToMinutes(value) / minuteStep)
-  );
+  const { times, index } = useBoundedTimes(minuteStep, minTime, maxTime, value);
 
   const setIndex = useCallback(
     (next: number) => {
@@ -561,6 +769,7 @@ function ClockFaceLayout({
       <Column
         items={times}
         index={index}
+        syncToken={syncToken}
         onIndexChange={setIndex}
         label={(time) => formatTime(time, { hourCycle, locale })}
         disabled={disabled}
@@ -590,19 +799,18 @@ function ClockFaceLayout({
 function RulerFace({
   value,
   onValueChange,
+  syncToken,
   hourCycle,
   minuteStep,
+  minTime,
+  maxTime,
   locale,
   disabled,
   readout = 'default',
 }: FaceProps) {
   const slots = timePickerVariants({ readout });
   const ref = useRef<ScrollView>(null);
-  const times = useMemo(() => timesOfDay(minuteStep), [minuteStep]);
-  const index = Math.min(
-    times.length - 1,
-    Math.round(timeToMinutes(value) / minuteStep)
-  );
+  const { times, index } = useBoundedTimes(minuteStep, minTime, maxTime, value);
   const resting = useRef(index);
   /*
    * Measured, not assumed: the scroller is narrower than the panel by whatever
@@ -622,18 +830,58 @@ function RulerFace({
     [times]
   );
 
+  // The scale runs the same rest-and-resync machinery the wheel's columns do,
+  // on the other axis and for the same two reasons: a refused tick moves
+  // nothing and has to be corrected, and a correction must never be scrolled
+  // into a scale that is still gliding.
+  const moving = useRef(false);
+  const owedResync = useRef(false);
+  const settleTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const latestIndex = useRef(index);
+  latestIndex.current = index;
+
+  const cancelTimer = useCallback(() => {
+    if (settleTimer.current === null) return;
+    clearTimeout(settleTimer.current);
+    settleTimer.current = null;
+  }, []);
+
+  // Unanimated, for the reason given on the wheel's columns: an animated
+  // programmatic scroll reports itself as a gesture and the correction loops.
+  const snapTo = useCallback((to: number) => {
+    resting.current = to;
+    ref.current?.scrollTo({ x: to * TICK_SPACING, animated: false });
+  }, []);
+
   useEffect(() => {
     if (index === resting.current) return;
-    resting.current = index;
-    ref.current?.scrollTo({ x: index * TICK_SPACING, animated: true });
-  }, [index]);
-
-  const settle = useCallback(
-    (event: NativeSyntheticEvent<NativeScrollEvent>) => {
-      const next = Math.round(event.nativeEvent.contentOffset.x / TICK_SPACING);
+    if (moving.current) {
+      owedResync.current = true;
+      return;
+    }
+    snapTo(index);
+  }, [index, syncToken, snapTo]);
+
+  const atRest = useCallback(() => {
+    cancelTimer();
+    moving.current = false;
+    if (!owedResync.current) return;
+    owedResync.current = false;
+    if (latestIndex.current !== resting.current) snapTo(latestIndex.current);
+  }, [cancelTimer, snapTo]);
+
+  const startMoving = useCallback(() => {
+    cancelTimer();
+    moving.current = true;
+  }, [cancelTimer]);
+
+  const settleAt = useCallback(
+    (x: number) => {
+      const next = Math.round(x / TICK_SPACING);
       const clamped = Math.min(Math.max(next, 0), times.length - 1);
       if (clamped === resting.current) return;
       resting.current = clamped;
+      owedResync.current = false;
       selectionTick();
       const time = times[clamped];
       if (time) onValueChange(time);
@@ -641,6 +889,29 @@ function RulerFace({
     [onValueChange, times]
   );
 
+  const onDragEnd = useCallback(
+    (event: NativeSyntheticEvent<NativeScrollEvent>) => {
+      const x = event.nativeEvent.contentOffset.x;
+      cancelTimer();
+      settleTimer.current = setTimeout(() => {
+        settleAt(x);
+        atRest();
+      }, 80);
+    },
+    [atRest, cancelTimer, settleAt]
+  );
+
+  const onMomentumEnd = useCallback(
+    (event: NativeSyntheticEvent<NativeScrollEvent>) => {
+      cancelTimer();
+      settleAt(event.nativeEvent.contentOffset.x);
+      atRest();
+    },
+    [atRest, cancelTimer, settleAt]
+  );
+
+  useEffect(() => cancelTimer, [cancelTimer]);
+
   const stepsPerHour = Math.max(1, Math.round(60 / minuteStep));
 
   /*
@@ -678,8 +949,10 @@ function RulerFace({
           snapToOffsets={snapToOffsets}
           disableIntervalMomentum
           decelerationRate="fast"
-          onMomentumScrollEnd={settle}
-          onScrollEndDrag={settle}
+          onScrollBeginDrag={startMoving}
+          onScrollEndDrag={onDragEnd}
+          onMomentumScrollBegin={startMoving}
+          onMomentumScrollEnd={onMomentumEnd}
           accessibilityRole="adjustable"
           accessibilityLabel="Time"
           accessibilityValue={{ text: formatTime(value, { hourCycle, locale }) }}
@@ -879,10 +1152,29 @@ function TimePickerRoot({
    * itself using — putting both here means every layout is bounded by the same
    * rule and none of them has to carry it.
    */
+  /*
+   * Counts refusals, not reports.
+   *
+   * A face has no way of knowing that the row it landed on was bounded away by
+   * `minTime` or `maxTime`, or rounded to a different one by the step — from
+   * where it stands, a refusal and a value that simply did not move are the
+   * same silence. This changes when a report was refused, which is the one
+   * thing the faces were missing, and is what lets a column put itself back on
+   * the row that actually holds.
+   *
+   * Only on refusal, though. Bumping it on every report re-rendered all three
+   * columns each time any one of them settled, for no answer any of them
+   * needed.
+   */
+  const [refusals, setRefusals] = useState(0);
+
   const commit = useCallback(
     (next: TimeValue) => {
       const bounded = clampTime(roundToStep(next, step), minTime, maxTime);
-      if (isSameTime(bounded, selected)) return;
+      if (isSameTime(bounded, selected)) {
+        setRefusals((count) => count + 1);
+        return;
+      }
       if (!isValueControlled) setInternalValue(bounded);
       onValueChange?.(bounded);
     },
@@ -898,7 +1190,10 @@ function TimePickerRoot({
   const face: FaceProps = {
     value: draft,
     onValueChange: commit,
+    syncToken: refusals,
     hourCycle,
+    minTime,
+    maxTime,
     minuteStep: step,
     locale,
     disabled,