panelui-native 0.49.0 → 0.53.0

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,

package/src/icons/index.tsx

@@ -991,6 +991,28 @@ export function TrashIcon({ size = 16, color, ...props }: IconProps) {
   );
 }
 
+/**
+ * Two columns of dots — the grip on a row that can be dragged somewhere else.
+ *
+ * Dots rather than the stacked rules of a menu glyph, and two columns rather
+ * than one: the pattern has to read as a surface to take hold of from either
+ * side, and a single column reads as a divider instead.
+ */
+export function GripVerticalIcon({ size = 16, color, ...props }: IconProps) {
+  const resolved = useResolvedColor(color, '#737373');
+  return (
+    <Svg width={size} height={size} viewBox="0 0 24 24" fill="none" {...props}>
+      <Path
+        d="M9 5h.01M9 12h.01M9 19h.01M15 5h.01M15 12h.01M15 19h.01"
+        stroke={resolved}
+        strokeWidth={2.5}
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+    </Svg>
+  );
+}
+
 /** An arrow into a tray — save the thing to a file. */
 export function DownloadIcon({ size = 16, color, ...props }: IconProps) {
   const resolved = useResolvedColor(color, '#737373');

package/src/index.ts

@@ -106,6 +106,21 @@ export {
   type BarChartStatus,
   type BarChartOrientation,
 } from './components/bar-chart';
+export {
+  CandlestickChart,
+  useCandlestickChart,
+  type CandlestickChartProps,
+  type CandlestickChartHandle,
+  type CandlestickChartHeaderProps,
+  type CandlestickChartGridProps,
+  type CandlestickChartCandlesProps,
+  type CandlestickChartXAxisProps,
+  type CandlestickChartYAxisProps,
+  type CandlestickChartTooltipProps,
+  type CandlestickChartLegendProps,
+  type CandlestickChartDatum,
+  type CandlestickChartStatus,
+} from './components/candlestick-chart';
 export {
   BottomSheet,
   type BottomSheetProps,
@@ -382,6 +397,15 @@ export {
   type ComboboxSelection,
   type ComboboxPresentation,
 } from './components/combobox';
+export {
+  ContextMenu,
+  type ContextMenuProps,
+  type ContextMenuTriggerProps,
+  type ContextMenuContentProps,
+  type ContextMenuItemProps,
+  type ContextMenuPreviewProps,
+  type ContextMenuAnchor,
+} from './components/context-menu';
 export {
   Drawer,
   type DrawerProps,
@@ -608,6 +632,7 @@ export {
 } from './components/message';
 export {
   Popover,
+  usePopoverAnchor,
   type PopoverProps,
   type PopoverTriggerProps,
   type PopoverContentProps,
@@ -616,6 +641,8 @@ export {
   type PopoverPlacement,
   type PopoverAlign,
   type PopoverPresentation,
+  type PopoverAnchorRect,
+  type PopoverAnchorControls,
 } from './components/popover';
 export {
   Post,
@@ -796,6 +823,16 @@ export {
 } from './components/thinking-orb';
 export { Skeleton, type SkeletonProps } from './components/skeleton';
 export { Slider, type SliderProps } from './components/slider';
+export {
+  Sortable,
+  reorderItems,
+  useSortableItem,
+  type SortableProps,
+  type SortableItemProps,
+  type SortableHandleProps,
+  type SortableActivation,
+  type SortableReorderDetails,
+} from './components/sortable';
 export { Spinner, type SpinnerProps } from './components/spinner';
 export {
   Steps,
@@ -810,7 +847,9 @@ export {
 export { Surface, type SurfaceProps } from './components/surface';
 export {
   Swipe,
+  useSwipeGroup,
   type SwipeProps,
+  type SwipeGroupProps,
   type SwipePanelProps,
   type SwipeActionProps,
   type SwipeActionColor,

package/src/utils/haptics.ts

@@ -61,3 +61,24 @@ export function hasHaptics(): boolean {
 export function selectionTick(): void {
   void getHaptics()?.selectionAsync().catch(() => {});
 }
+
+/**
+ * The knock for a thing coming loose or landing — a row lifted out of a list,
+ * a card dropped into place.
+ *
+ * An impact rather than a selection because it marks a change of state rather
+ * than a change of value: the finger is now holding something it was not
+ * holding a moment ago, and the lightest feedback is not enough to say so.
+ * `medium` is the one that reads as picking something up without reading as an
+ * error.
+ *
+ * Falls back to a selection tick where the style constants are missing, and to
+ * nothing at all where the package is.
+ */
+export function impactKnock(): void {
+  const haptics = getHaptics();
+  if (!haptics) return;
+  void haptics
+    .impactAsync(haptics.ImpactFeedbackStyle?.Medium)
+    .catch(() => {});
+}