panelui-native 0.78.0 → 0.79.1

package/src/components/progress-button/index.tsx

@@ -41,8 +41,10 @@
  * is a broken button — so this is a coarser indicator, not the absence of one.
  */
 import {
+  Children,
   createContext,
   forwardRef,
+  isValidElement,
   useCallback,
   useContext,
   useEffect,
@@ -62,20 +64,23 @@ import Animated, {
   Easing,
   cancelAnimation,
   runOnJS,
+  runOnUI,
   useAnimatedReaction,
   useAnimatedStyle,
   useReducedMotion,
   useSharedValue,
+  withSpring,
   withTiming,
   type SharedValue,
 } from 'react-native-reanimated';
 import { tv, type VariantProps } from 'tailwind-variants';
+import { useCSSVariable } from 'uniwind';
+import { CheckIcon, IconColorProvider } from '../../icons';
 import { Text, textChildren } from '../../primitives/text';
-import { cn } from '../../utils/cn';
 import { impactKnock, selectionTick } from '../../utils/haptics';
 import {
   DEFAULT_AUTO_RESET_DELAY,
-  DEFAULT_RELEASE_DURATION,
+  fillDuration,
   releaseDuration,
   resolveHoldDuration,
 } from './progress-button-hold';
@@ -83,6 +88,32 @@ import {
 /** How many steps the reduced-motion fill advances in. */
 const REDUCED_STEPS = 5;
 
+/**
+ * The arrival of the completed drawing.
+ *
+ * A spring rather than a timing, and slightly overshooting: the fill has just
+ * spent two seconds moving at a constant rate, and something that lands with a
+ * little weight is what tells the reader the waiting part is over.
+ */
+const DONE_SPRING = { damping: 14, stiffness: 220, mass: 0.6 } as const;
+
+/** How long the completed drawing takes to leave again on a reset. */
+const DONE_EXIT = 140;
+
+/**
+ * Which token the tick is drawn in, per variant.
+ *
+ * It sits on the finished fill, so it takes that fill's own foreground rather
+ * than the button's — the same pairing `fillLabel` uses, which is what keeps
+ * the contrast right in both themes without a hardcoded colour.
+ */
+const DONE_TINT = {
+  primary: '--color-primary-foreground',
+  secondary: '--color-background',
+  destructive: '--color-destructive-solid-foreground',
+  success: '--color-success-solid-foreground',
+} as const;
+
 const progressButtonVariants = tv({
   slots: {
     /*
@@ -94,7 +125,22 @@ const progressButtonVariants = tv({
      * a rectangle sliding out from under the button rather than as the button
      * filling up.
      */
-    root: 'relative overflow-hidden rounded-full border',
+    /*
+     * Every variant rests on the same secondary surface, and `variant` decides
+     * only what colour comes across it.
+     *
+     * Drawn as outlines they were four different buttons before anything had
+     * happened, and the one thing they all do — wait to be held — was the
+     * thing the drawing did not say. A solid ground says it: the button is
+     * unfilled, and the fill is what the hold produces.
+     *
+     * The variant is still legible at rest, because the label carries its
+     * colour. That is the half worth keeping — a destructive hold should not
+     * look like an ordinary one before it is touched — and it is also the half
+     * that survives the wipe, since the fill covers the ground the label was
+     * standing on and the second copy takes over.
+     */
+    root: 'relative overflow-hidden rounded-full border border-transparent bg-secondary',
     /*
      * The row inside the button. It is separate from `root` because the fill
      * has to sit over the whole button including its padding — a wipe that
@@ -110,25 +156,21 @@ const progressButtonVariants = tv({
   variants: {
     variant: {
       primary: {
-        root: 'border-primary bg-transparent',
         label: 'text-primary',
         fill: 'bg-primary',
         fillLabel: 'text-primary-foreground',
       },
       secondary: {
-        root: 'border-transparent bg-secondary',
         label: 'text-secondary-foreground',
         fill: 'bg-foreground',
         fillLabel: 'text-background',
       },
       destructive: {
-        root: 'border-destructive bg-transparent',
         label: 'text-destructive',
         fill: 'bg-destructive',
         fillLabel: 'text-destructive-solid-foreground',
       },
       success: {
-        root: 'border-success bg-transparent',
         label: 'text-success',
         fill: 'bg-success',
         fillLabel: 'text-success-solid-foreground',
@@ -183,6 +225,12 @@ export type ProgressButtonSize = NonNullable<ProgressButtonVariantProps['size']>
 interface ProgressButtonContextValue {
   /** `0` to `1` across the hold. */
   progress: SharedValue<number>;
+  /**
+   * `0` to `1` across the arrival of the completed drawing. Separate from
+   * `progress` because the fill has finished by the time this starts, and the
+   * two would otherwise have to share one clock running at two speeds.
+   */
+  done: SharedValue<number>;
   /** Width of the button, so the fill's copy of the label can match it. */
   width: number;
   completed: boolean;
@@ -224,6 +272,10 @@ export interface ProgressButtonProps
   autoReset?: boolean;
   /** Milliseconds to stay completed before resetting. Defaults to `1000`. */
   autoResetDelay?: number;
+  /**
+   * Dim the button and refuse the hold outright. The fill never starts, so
+   * there is no half-finished state to explain.
+   */
   disabled?: boolean;
   /**
    * A tick as the hold takes, and a knock when it completes. Off by default:
@@ -258,6 +310,7 @@ const ProgressButtonRoot = forwardRef<View, ProgressButtonProps>(function Progre
   const reducedMotion = useReducedMotion();
 
   const progress = useSharedValue(0);
+  const done = useSharedValue(0);
   const [width, setWidth] = useState(0);
   const [internalCompleted, setInternalCompleted] = useState(false);
   const resetTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
@@ -265,7 +318,19 @@ const ProgressButtonRoot = forwardRef<View, ProgressButtonProps>(function Progre
   const isControlled = completedProp !== undefined;
   const completed = isControlled ? completedProp : internalCompleted;
 
+  /*
+   * The reaction below watches a shared value, and a shared value can reach the
+   * end for reasons other than a hold — a controlled button being told it is
+   * complete fills instantly. Read from a ref rather than from `completed` so
+   * the guard sees the current answer without the reaction being rebuilt.
+   */
+  const completedRef = useRef(completed);
+  completedRef.current = completed;
+
   const finish = useCallback(() => {
+    // Already complete: the fill was set from outside, and firing the action
+    // again would run it a second time for something the reader did not do.
+    if (completedRef.current) return;
     if (!isControlled) setInternalCompleted(true);
     onCompletedChange?.(true);
     onComplete?.();
@@ -288,45 +353,91 @@ const ProgressButtonRoot = forwardRef<View, ProgressButtonProps>(function Progre
     }
   );
 
+  /*
+   * Both directions are started on the UI thread, and that is not a detail.
+   *
+   * A shared value animated on the UI thread does not report back to
+   * JavaScript, so `progress.value` read from a press handler is the value
+   * from before the hold began — zero. The release computed from it either did
+   * nothing or, worse, `cancelAnimation` wrote that stale zero back and the
+   * fill vanished on touch-up instead of travelling home.
+   *
+   * `runOnUI` puts the read where the value actually lives.
+   */
   const begin = useCallback(() => {
     if (disabled || completed) return;
     if (haptics) selectionTick();
-    cancelAnimation(progress);
-    if (reducedMotion) {
-      /*
-       * Stepped rather than smooth, and still a real indicator. What reduced
-       * motion is about is continuous movement, not the button telling you how
-       * much longer to wait — take that away and the control asks for a hold
-       * with nothing on screen to say why.
-       */
+    runOnUI(() => {
+      'worklet';
+      cancelAnimation(progress);
+      const from = progress.value;
+      if (from >= 1) return;
       progress.value = withTiming(1, {
-        duration,
-        easing: Easing.steps(REDUCED_STEPS, true),
+        // The distance still ahead, at the fill's own rate — so a press that
+        // catches the fill on its way back carries on from there rather than
+        // restarting the clock.
+        duration: fillDuration(from, duration),
+        /*
+         * Linear. A fill is constant motion, and an eased one misreports the
+         * wait: it races the first half and crawls the second, or the reverse.
+         *
+         * Under reduced motion it steps instead, and is still a real
+         * indicator — what that setting is about is continuous movement, not
+         * the button saying how much longer to wait. Take that away and the
+         * control asks for a hold with nothing on screen to say why.
+         */
+        easing: reducedMotion ? Easing.steps(REDUCED_STEPS, true) : Easing.linear,
       });
-      return;
-    }
-    // Linear. A fill is constant motion, and an eased one misreports the wait:
-    // it races the first half and crawls the second, or the reverse.
-    progress.value = withTiming(1, { duration, easing: Easing.linear });
+    })();
   }, [disabled, completed, haptics, progress, reducedMotion, duration]);
 
+  /*
+   * The fill, played backwards.
+   *
+   * Same rate, same easing, same stepping under reduced motion — only the
+   * direction differs. Let go at nine tenths of a two-second hold and the fill
+   * takes 1.8 seconds to travel home, which is the 1.8 seconds it took to get
+   * there. A fill that vanishes has been deleted; a fill that travels back has
+   * been let go, and telling those apart is the whole reason the wait is drawn
+   * on the button.
+   *
+   * Every path that empties the fill goes through here — a hold let go, an
+   * `autoReset` landing, a controlled button told it is no longer complete.
+   * They were three separate assignments and two of them snapped.
+   */
+  const rewind = useCallback(() => {
+    runOnUI(() => {
+      'worklet';
+      cancelAnimation(progress);
+      const from = progress.value;
+      if (from <= 0) {
+        progress.value = 0;
+        return;
+      }
+      progress.value = withTiming(0, {
+        duration: releaseDuration(from, duration),
+        easing: reducedMotion ? Easing.steps(REDUCED_STEPS, true) : Easing.linear,
+      });
+    })();
+  }, [progress, duration, reducedMotion]);
+
   const abandon = useCallback(() => {
-    cancelAnimation(progress);
-    if (progress.value <= 0) return;
-    progress.value = withTiming(0, {
-      // Proportional to how far it got. A fixed release makes a hold abandoned
-      // after a moment feel sticky, which reads as the button resisting.
-      duration: releaseDuration(progress.value, DEFAULT_RELEASE_DURATION),
-      easing: Easing.out(Easing.cubic),
-    });
-  }, [progress]);
+    /*
+     * A completed hold has nothing to abandon. Without this the fill drains on
+     * the release that follows a successful hold — the button empties, looks
+     * untouched, and then refuses every press after it, because `begin` bails
+     * on a completed button. That combination is a control that has silently
+     * stopped working.
+     */
+    if (completedRef.current) return;
+    rewind();
+  }, [rewind]);
 
   const reset = useCallback(() => {
-    cancelAnimation(progress);
-    progress.value = 0;
+    rewind();
     if (!isControlled) setInternalCompleted(false);
     onCompletedChange?.(false);
-  }, [progress, isControlled, onCompletedChange]);
+  }, [rewind, isControlled, onCompletedChange]);
 
   useEffect(() => {
     if (!completed || !autoReset) return;
@@ -337,19 +448,42 @@ const ProgressButtonRoot = forwardRef<View, ProgressButtonProps>(function Progre
     };
   }, [completed, autoReset, autoResetDelay, reset]);
 
-  // A controlled button told it is no longer complete has to empty its fill,
-  // or the next hold starts from a bar that is already full.
+  /*
+   * The fill follows the completed state, in both directions.
+   *
+   * A controlled button told it is complete fills without a hold, and one told
+   * it is no longer complete empties — otherwise the next hold would start from
+   * a bar that is already full.
+   */
+  useEffect(() => {
+    if (completed) {
+      cancelAnimation(progress);
+      progress.value = 1;
+      return;
+    }
+    rewind();
+  }, [completed, progress, rewind]);
+
+  /*
+   * And the completed drawing follows it too. Under reduced motion it is a
+   * swap: what that setting is about is movement, and a tick that grows is
+   * movement with nothing to report.
+   */
   useEffect(() => {
-    if (!completed) return;
-    progress.value = 1;
-  }, [completed, progress]);
+    if (reducedMotion) {
+      done.value = completed ? 1 : 0;
+      return;
+    }
+    done.value = completed ? withSpring(1, DONE_SPRING) : withTiming(0, { duration: DONE_EXIT });
+  }, [completed, done, reducedMotion]);
 
   useEffect(
     () => () => {
       cancelAnimation(progress);
+      cancelAnimation(done);
       if (resetTimer.current) clearTimeout(resetTimer.current);
     },
-    [progress]
+    [progress, done]
   );
 
   const onLayout = (event: LayoutChangeEvent) => {
@@ -358,14 +492,32 @@ const ProgressButtonRoot = forwardRef<View, ProgressButtonProps>(function Progre
     props.onLayout?.(event);
   };
 
+  /*
+   * `slots` is rebuilt every render, so it is deliberately not a dependency —
+   * including it would make this memo re-run every time and hand every consumer
+   * a new object for no change. The variant and size it is derived from are the
+   * dependencies instead.
+   */
   const context = useMemo<ProgressButtonContextValue>(
-    () => ({ progress, width, completed, variant, size, slots }),
-    [progress, width, completed, variant, size, slots]
+    () => ({ progress, done, width, completed, variant, size, slots }),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [progress, done, width, completed, variant, size]
   );
 
-  const body = children ?? (
+  /*
+   * The completed drawing is part of the button rather than something every
+   * call site has to remember, so one is added unless the caller wrote their
+   * own. A hold that lands and shows nothing is the reader wondering whether it
+   * worked, which is the thing this control exists to remove.
+   */
+  const written = Children.toArray(children);
+  const hasDone = written.some(
+    (child) => isValidElement(child) && child.type === ProgressButtonDone
+  );
+  const body = (
     <>
-      <ProgressButtonLabel>Hold to confirm</ProgressButtonLabel>
+      {written.length > 0 ? written : <ProgressButtonLabel>Hold to confirm</ProgressButtonLabel>}
+      {hasDone ? null : <ProgressButtonDone />}
     </>
   );
 
@@ -387,12 +539,18 @@ const ProgressButtonRoot = forwardRef<View, ProgressButtonProps>(function Progre
           checked: completed,
         }}
         disabled={disabled}
+        /*
+         * The spread sits above the hold rather than below it. Underneath, a
+         * caller passing `onPressIn` — reasonably, to log a tap — would replace
+         * the gesture the whole control is, and the button would simply never
+         * fill.
+         */
+        {...props}
         onPressIn={begin}
         onPressOut={abandon}
         // A few points of drift should not abandon a hold the reader is
         // still making. Fingers move.
         pressRetentionOffset={16}
-        {...props}
         onLayout={onLayout}
         className={slots.root({ className })}
       >
@@ -449,16 +607,77 @@ function ProgressButtonLabel({ className, children, ...props }: ProgressButtonLa
 }
 ProgressButtonLabel.displayName = 'ProgressButton.Label';
 
+export interface ProgressButtonDoneProps extends ViewProps {
+  className?: string;
+  /**
+   * What the button shows once the hold has landed. A tick on its own by
+   * default; children replace it, so a word beside one is
+   * `<ProgressButton.Done><CheckIcon /><Text>Paid</Text></ProgressButton.Done>`.
+   */
+  children?: ReactNode;
+}
+
+/**
+ * The drawing the button lands on.
+ *
+ * It sits over the finished fill rather than beside the label, so the button
+ * does not change width at the moment it completes — a control that resizes as
+ * it succeeds moves everything under it, and the reader's eye is on the button.
+ *
+ * One is added for you unless you write your own, because a hold that lands and
+ * shows nothing leaves the reader checking whether it worked.
+ */
+function ProgressButtonDone({ className, children, ...props }: ProgressButtonDoneProps) {
+  const { done, completed, variant, slots } = useProgressButtonContext('ProgressButton.Done');
+  const tint = useCSSVariable(DONE_TINT[variant]);
+
+  /*
+   * It carries the fill's own colour and covers the button edge to edge.
+   *
+   * The alternative — fading the label out from under it — takes the fill with
+   * it, because the fill is drawn inside the label so that the two copies of
+   * the text line up. The button would empty at the exact moment it succeeded,
+   * and the tick, drawn in the colour that reads against a full fill, would be
+   * left standing on nothing.
+   */
+  const style = useAnimatedStyle(() => ({ opacity: done.value }));
+  // The tick arrives from slightly under full size. The ground it lands on
+  // does not: a background box that grows reads as the button resizing.
+  const markStyle = useAnimatedStyle(() => ({ transform: [{ scale: 0.7 + done.value * 0.3 }] }));
+
+  return (
+    <Animated.View
+      {...props}
+      // Never takes the press: the button underneath still owns it, which is
+      // what lets a completed button be reset and held again.
+      pointerEvents="none"
+      accessibilityElementsHidden={!completed}
+      importantForAccessibility={completed ? 'auto' : 'no-hide-descendants'}
+      style={[{ position: 'absolute', top: 0, right: 0, bottom: 0, left: 0 }, style]}
+      className={slots.fill({ className: slots.content({ className }) })}
+    >
+      <Animated.View style={markStyle} className={slots.content()}>
+        <IconColorProvider color={typeof tint === 'string' ? tint : undefined}>
+          {children ?? <CheckIcon size={18} />}
+        </IconColorProvider>
+      </Animated.View>
+    </Animated.View>
+  );
+}
+ProgressButtonDone.displayName = 'ProgressButton.Done';
+
 ProgressButtonRoot.displayName = 'ProgressButton';
 
 export const ProgressButton = Object.assign(ProgressButtonRoot, {
   Label: ProgressButtonLabel,
+  Done: ProgressButtonDone,
 });
 
 export {
   DEFAULT_AUTO_RESET_DELAY,
   DEFAULT_HOLD_DURATION,
   DEFAULT_RELEASE_DURATION,
+  fillDuration,
   isComplete,
   releaseDuration,
   resolveHoldDuration,

package/src/components/progress-button/progress-button-hold.ts

@@ -8,8 +8,15 @@
 /** Milliseconds a hold has to be sustained before it counts. */
 export const DEFAULT_HOLD_DURATION = 2000;
 
-/** Milliseconds the fill takes to drain when a hold is abandoned. */
-export const DEFAULT_RELEASE_DURATION = 240;
+/**
+ * Milliseconds a complete fill takes to rewind, when the hold length is not
+ * known — the default only exists so {@link releaseDuration} has one.
+ *
+ * The component always passes the hold's own duration instead: the drain is
+ * the fill running backwards at the same rate, so a two-second hold takes two
+ * seconds to give back.
+ */
+export const DEFAULT_RELEASE_DURATION = DEFAULT_HOLD_DURATION;
 
 /** Milliseconds before an `autoReset` button offers itself again. */
 export const DEFAULT_AUTO_RESET_DELAY = 1000;
@@ -31,15 +38,24 @@ export function resolveHoldDuration(duration: number | undefined): number {
 /**
  * How long the fill should take to drain from where it is.
  *
- * Proportional to how far it got, so abandoning a hold at a tenth of the way
- * does not take the same quarter-second as abandoning it at nine tenths. A
- * fixed release makes a barely-started hold feel sticky, which reads as the
- * control resisting being let go.
+ * The fill, run backwards. `full` is the hold's own duration, so the drain
+ * covers the distance left at exactly the rate it was filled at: let go at
+ * nine tenths of a two-second hold and it takes 1.8 seconds to give back, the
+ * same 1.8 seconds it took to earn.
+ *
+ * That is the point of it. The wait was drawn on the button, so undoing the
+ * wait is worth drawing too — a fill that vanishes has been deleted, and a
+ * fill that travels back has been let go.
  */
 export function releaseDuration(
   progress: number,
   full: number = DEFAULT_RELEASE_DURATION
 ): number {
+  // A worklet, because the only runtime that knows how far the fill actually
+  // got is the one animating it. Reading a shared value from JavaScript gives
+  // the value before the animation started, so the release has to be started
+  // from the UI thread — and that means this has to run there too.
+  'worklet';
   const travelled = Math.min(1, Math.max(0, progress));
   return Math.max(80, full * travelled);
 }
@@ -53,5 +69,20 @@ export function releaseDuration(
  * button sometimes fires when the reader let go early on purpose.
  */
 export function isComplete(progress: number): boolean {
+  'worklet';
   return progress >= 1;
 }
+
+/**
+ * How long it takes to cover the distance still ahead, at the fill's own rate.
+ *
+ * A press that arrives while the fill is on its way back should carry on from
+ * where it is rather than restarting the clock — otherwise a fill picked up at
+ * halfway takes the whole hold to cover the half that is left, and the second
+ * attempt is twice as slow as the first for no reason the reader can see.
+ */
+export function fillDuration(from: number, full: number): number {
+  'worklet';
+  const remaining = Math.min(1, Math.max(0, 1 - from));
+  return Math.max(80, full * remaining);
+}