react-native-laminar 1.4.4 → 1.5.0

package/src/view/number-run.tsx

@@ -1,7 +1,10 @@
-import React, { useMemo, useRef } from "react";
+import React, { useMemo, useRef, type ReactNode } from "react";
 import { type StyleProp, type TextStyle, View } from "react-native";
+import Animated from "react-native-reanimated";
+import { useLeadingAnimation } from "../hooks/use-leading-animation";
 import { useNumericLanes } from "../hooks/use-numeric-lanes";
 import type { LaminarAlign, MotionRecipe } from "../types";
+import { LeadingElement } from "./leading-element";
 import { NumberLane } from "./number-lane";
 
 const rowStyle = {
@@ -24,6 +27,10 @@ type NumberRunProps = {
   readonly textStyle?: StyleProp<TextStyle>;
   readonly staggerMs: number;
   readonly className?: string;
+  readonly leading?: ReactNode;
+  readonly leadingKey?: string | number;
+  readonly leadingGap?: number;
+  readonly ready?: boolean;
 };
 
 // arrange numeric lanes from left to right while the hook preserves their identities
@@ -36,16 +43,59 @@ export const NumberRun = React.memo(
     textStyle,
     staggerMs,
     className,
+    leading,
+    leadingKey,
+    leadingGap = 0,
+    ready = true,
   }: Readonly<NumberRunProps>) => {
+    const hasDisplayedRef = useRef(false);
+    const displayedValueRef = useRef(value);
+    const displayedLeadingRef = useRef(leading);
+    const displayedLeadingKeyRef = useRef(leadingKey);
+    const displayedLeadingGapRef = useRef(leadingGap);
+    const shouldDisplayTarget = ready || !hasDisplayedRef.current;
+    const visibleValue = shouldDisplayTarget
+      ? value
+      : displayedValueRef.current;
+    const visibleLeading = shouldDisplayTarget
+      ? leading
+      : displayedLeadingRef.current;
+    const visibleLeadingKey = shouldDisplayTarget
+      ? leadingKey
+      : displayedLeadingKeyRef.current;
+    const visibleLeadingGap = shouldDisplayTarget
+      ? leadingGap
+      : displayedLeadingGapRef.current;
+
+    if (shouldDisplayTarget) {
+      hasDisplayedRef.current = true;
+      displayedValueRef.current = value;
+      displayedLeadingRef.current = leading;
+      displayedLeadingKeyRef.current = leadingKey;
+      displayedLeadingGapRef.current = leadingGap;
+    }
+
+    const {
+      elementEnterTransition,
+      elementExitTransition,
+      isLeadingChange,
+      isLeadingSwap,
+    } = useLeadingAnimation({
+      leading: visibleLeading,
+      leadingKey: visibleLeadingKey,
+      leadingGap: visibleLeadingGap,
+      motionRecipe,
+    });
     // the hook owns lane identity while this component owns row placement and timing
-    const { units, laneKeys, direction, leadLength } = useNumericLanes(value);
-    const lastValueRef = useRef(value);
+    const { units, laneKeys, direction, leadLength } =
+      useNumericLanes(visibleValue);
+    const lastValueRef = useRef(visibleValue);
     const hasAnimatedRef = useRef(false);
 
     // skip enter animations on first paint so the number feels settled
-    if (value !== lastValueRef.current) {
+    if (visibleValue !== lastValueRef.current || isLeadingChange) {
       hasAnimatedRef.current = true;
-      lastValueRef.current = value;
+      lastValueRef.current = visibleValue;
     }
 
     // scale travel from the font while keeping a minimum visible movement
@@ -57,28 +107,46 @@ export const NumberRun = React.memo(
 
     return (
       <View style={[rowStyle, rowAlignStyles[align]]}>
-        {units.map((unit, index) => {
-          const inLead = index < leadLength;
-          const laneKey = inLead
-            ? `lead:${index}`
-            : `lane:${units.length - 1 - index}`;
+        <LeadingElement
+          leading={visibleLeading}
+          leadingKey={visibleLeadingKey}
+          leadingGap={visibleLeadingGap}
+          enterTransition={
+            hasAnimated ? motionRecipe.enterTransition : undefined
+          }
+          elementEnterTransition={
+            isLeadingSwap ? elementEnterTransition : undefined
+          }
+          exitTransition={motionRecipe.exitTransition}
+          elementExitTransition={elementExitTransition}
+        />
+        <Animated.View
+          layout={isLeadingChange ? motionRecipe.layoutTransition : undefined}
+          style={rowStyle}
+        >
+          {units.map((unit, index) => {
+            const inLead = index < leadLength;
+            const laneKey = inLead
+              ? `lead:${index}`
+              : `lane:${units.length - 1 - index}`;
 
-          return (
-            <NumberLane
-              key={laneKey}
-              unit={unit}
-              tokenKey={laneKeys[index]}
-              isLead={inLead}
-              hasAnimated={hasAnimated}
-              delayMs={index * staggerMs}
-              direction={direction}
-              travelDistance={travelDistance}
-              motionRecipe={motionRecipe}
-              textStyle={textStyle}
-              className={className}
-            />
-          );
-        })}
+            return (
+              <NumberLane
+                key={laneKey}
+                unit={unit}
+                tokenKey={laneKeys[index]}
+                isLead={inLead}
+                hasAnimated={hasAnimated}
+                delayMs={index * staggerMs}
+                direction={direction}
+                travelDistance={travelDistance}
+                motionRecipe={motionRecipe}
+                textStyle={textStyle}
+                className={className}
+              />
+            );
+          })}
+        </Animated.View>
       </View>
     );
   }

package/src/view/slot-shadow.tsx

@@ -0,0 +1,99 @@
+import React from "react";
+import MaskedView from "@react-native-masked-view/masked-view";
+import { LinearGradient } from "expo-linear-gradient";
+import { StyleSheet } from "react-native";
+
+const DEFAULT_SHADOW_COLOR = "#ffffff";
+// The reference digit viewport fades across roughly one third of its visible row.
+const DEFAULT_SHADOW_SIZE_RATIO = 0.28;
+
+const transparentColor = (color: string) => {
+  const value = color.trim();
+
+  if (value.startsWith("#")) {
+    const hex = value.slice(1);
+    const expanded =
+      hex.length === 3 || hex.length === 4
+        ? hex
+            .slice(0, 3)
+            .split("")
+            .map((channel) => channel + channel)
+            .join("")
+        : hex.slice(0, 6);
+
+    if (expanded.length === 6 && /^[0-9a-f]+$/i.test(expanded)) {
+      return `rgba(${Number.parseInt(expanded.slice(0, 2), 16)}, ${Number.parseInt(
+        expanded.slice(2, 4),
+        16
+      )}, ${Number.parseInt(expanded.slice(4, 6), 16)}, 0)`;
+    }
+  }
+
+  const channels = value.match(/\d+(?:\.\d+)?%?/g);
+  if ((value.startsWith("rgb(") || value.startsWith("rgba(")) && channels) {
+    const rgb = channels.slice(0, 3).map((channel) => {
+      if (channel.endsWith("%")) {
+        return Math.round((Number.parseFloat(channel) / 100) * 255);
+      }
+
+      return Number.parseFloat(channel);
+    });
+
+    if (rgb.length === 3 && rgb.every(Number.isFinite)) {
+      return `rgba(${rgb.join(", ")}, 0)`;
+    }
+  }
+
+  // Keep the fallback light so an unknown color never introduces a dark edge.
+  return "rgba(255, 255, 255, 0)";
+};
+
+type SlotShadowProps = {
+  readonly slotHeight: number;
+  readonly viewportHeight: number;
+  readonly color?: string;
+  readonly size?: number;
+  readonly children: React.ReactElement;
+};
+
+// Keep the mask mounted for the lifetime of the viewport. The gradient controls
+// content alpha at the clipping edges instead of painting over the glyphs.
+export const SlotShadow = React.memo(function SlotShadow({
+  slotHeight,
+  viewportHeight,
+  color = DEFAULT_SHADOW_COLOR,
+  size,
+  children,
+}: SlotShadowProps) {
+  const edgeSize = Math.min(
+    Math.max(4, size ?? slotHeight * DEFAULT_SHADOW_SIZE_RATIO),
+    viewportHeight / 2
+  );
+  const fadeColor = transparentColor(color);
+  const fadeRatio = edgeSize / viewportHeight;
+
+  return (
+    <MaskedView
+      pointerEvents="none"
+      style={styles.container}
+      maskElement={
+        <LinearGradient
+          colors={[fadeColor, color, color, fadeColor]}
+          locations={[0, fadeRatio, 1 - fadeRatio, 1]}
+          start={{ x: 0, y: 0 }}
+          end={{ x: 0, y: 1 }}
+          style={styles.mask}
+        />
+      }
+    >
+      {children}
+    </MaskedView>
+  );
+});
+
+SlotShadow.displayName = "SlotShadow";
+
+const styles = StyleSheet.create({
+  container: StyleSheet.absoluteFillObject,
+  mask: StyleSheet.absoluteFillObject,
+});

package/src/view/slots-run.tsx

@@ -1,4 +1,4 @@
-import React, { useEffect, useMemo, useRef } from "react";
+import React, { useEffect, useMemo, useRef, type ReactNode } from "react";
 import {
   StyleSheet,
   Text,
@@ -11,9 +11,17 @@ import Animated, {
   useAnimatedStyle,
   useSharedValue,
 } from "react-native-reanimated";
+import { useLeadingAnimation } from "../hooks/use-leading-animation";
 import { useNumericLanes } from "../hooks/use-numeric-lanes";
 import { isAsciiDigit } from "../model/display-units";
-import type { LaminarAlign, MotionRecipe, NumericFlowDirection } from "../types";
+import type {
+  LaminarAlign,
+  LaminarShadow,
+  MotionRecipe,
+  NumericFlowDirection,
+} from "../types";
+import { LeadingElement } from "./leading-element";
+import { SlotShadow } from "./slot-shadow";
 
 const rowStyle = {
   flexDirection: "row",
@@ -64,7 +72,7 @@ const equalStyleValue = (left: unknown, right: unknown) =>
     left.length === right.length &&
     left.every((value, index) => value === right[index]));
 
-// prevent every parent update from rebuilding the thirty-text reel
+// prevent every parent update from rebuilding the bounded reel
 const areSlotReelPropsEqual = (
   previous: SlotReelProps,
   next: SlotReelProps
@@ -151,6 +159,7 @@ type SlotColumnProps = {
   readonly slotHeight: number;
   readonly textStyle?: StyleProp<TextStyle>;
   readonly className?: string;
+  readonly shadow?: LaminarShadow;
 };
 
 function SlotColumn({
@@ -162,6 +171,7 @@ function SlotColumn({
   slotHeight,
   textStyle,
   className,
+  shadow = false,
 }: SlotColumnProps) {
   // cumulative positions let the reel move across digit wraparound without jumps
   const spinInDistance = Math.max(digit, 1);
@@ -173,13 +183,19 @@ function SlotColumn({
   const cumulativeRef = useRef(digit);
   const previousDigitRef = useRef(digit);
   const initialRef = useRef(true);
+  const drivenTargetRef = useRef<number | null>(null);
   const exitStateRef = useRef({
     digit,
     direction,
     motionRecipe,
     target: digit,
   });
-
+  const shadowOptions =
+    shadow !== null && typeof shadow === "object"
+      ? shadow
+      : shadow
+        ? {}
+        : undefined;
   if (digit !== previousDigitRef.current) {
     const previousDigit = previousDigitRef.current;
     let digitDelta: number;
@@ -228,6 +244,7 @@ function SlotColumn({
       initialRef.current = false;
 
       if (!animateIn) {
+        drivenTargetRef.current = cumulativeRef.current;
         return;
       }
     }
@@ -251,23 +268,46 @@ function SlotColumn({
       target,
     };
 
+    // A direction change can rerender every column even when this column's
+    // digit is unchanged. Keep the idle reel untouched in that case.
+    if (drivenTargetRef.current === target) {
+      return;
+    }
+
+    drivenTargetRef.current = target;
+
     current.value = motionRecipe.driveNumber(target, delayMs);
   }, [animateIn, current, delayMs, digit, direction, motionRecipe]);
 
+  const reel = (
+    <SlotReel
+      current={current}
+      slotHeight={slotHeight}
+      textStyle={textStyle}
+      className={className}
+    />
+  );
+
   return (
-    <View style={slotFrameStyle}>
+    <View style={[slotFrameStyle, { height: slotHeight }]}>
       <Text
         style={[textStyle, slotProbeStyle, { lineHeight: slotHeight }]}
         className={className}
       >
         0
       </Text>
-      <SlotReel
-        current={current}
-        slotHeight={slotHeight}
-        textStyle={textStyle}
-        className={className}
-      />
+      {shadowOptions ? (
+        <SlotShadow
+          slotHeight={slotHeight}
+          viewportHeight={slotHeight}
+          color={shadowOptions.color}
+          size={shadowOptions.size}
+        >
+          {reel}
+        </SlotShadow>
+      ) : (
+        reel
+      )}
     </View>
   );
 }
@@ -280,6 +320,11 @@ type SlotsRunProps = {
   readonly textStyle?: StyleProp<TextStyle>;
   readonly staggerMs: number;
   readonly className?: string;
+  readonly leading?: ReactNode;
+  readonly leadingKey?: string | number;
+  readonly leadingGap?: number;
+  readonly ready?: boolean;
+  readonly shadow?: LaminarShadow;
 };
 
 // render text prefixes beside reusable digit reels
@@ -292,10 +337,53 @@ export const SlotsRun = React.memo(
     textStyle,
     staggerMs,
     className,
+    leading,
+    leadingKey,
+    leadingGap = 0,
+    ready = true,
+    shadow = false,
   }: Readonly<SlotsRunProps>) => {
+    const hasDisplayedRef = useRef(false);
+    const displayedValueRef = useRef(value);
+    const displayedLeadingRef = useRef(leading);
+    const displayedLeadingKeyRef = useRef(leadingKey);
+    const displayedLeadingGapRef = useRef(leadingGap);
+    const shouldDisplayTarget = ready || !hasDisplayedRef.current;
+    const visibleValue = shouldDisplayTarget
+      ? value
+      : displayedValueRef.current;
+    const visibleLeading = shouldDisplayTarget
+      ? leading
+      : displayedLeadingRef.current;
+    const visibleLeadingKey = shouldDisplayTarget
+      ? leadingKey
+      : displayedLeadingKeyRef.current;
+    const visibleLeadingGap = shouldDisplayTarget
+      ? leadingGap
+      : displayedLeadingGapRef.current;
+
+    if (shouldDisplayTarget) {
+      hasDisplayedRef.current = true;
+      displayedValueRef.current = value;
+      displayedLeadingRef.current = leading;
+      displayedLeadingKeyRef.current = leadingKey;
+      displayedLeadingGapRef.current = leadingGap;
+    }
+
+    const {
+      elementEnterTransition,
+      elementExitTransition,
+      isLeadingChange,
+      isLeadingSwap,
+    } = useLeadingAnimation({
+      leading: visibleLeading,
+      leadingKey: visibleLeadingKey,
+      leadingGap: visibleLeadingGap,
+      motionRecipe,
+    });
     // numeric lane identity decides which columns stay mounted as values change
-    const { units, direction, leadLength } = useNumericLanes(value);
-    const lastValueRef = useRef(value);
+    const { units, direction, leadLength } = useNumericLanes(visibleValue);
+    const lastValueRef = useRef(visibleValue);
     const hasAnimatedRef = useRef(false);
     // derive one stable row height so every reel position shares the same baseline
     const slotHeight = useMemo(() => {
@@ -315,9 +403,9 @@ export const SlotsRun = React.memo(
       );
     }, [fontSize, textStyle]);
 
-    if (value !== lastValueRef.current) {
+    if (visibleValue !== lastValueRef.current || isLeadingChange) {
       hasAnimatedRef.current = true;
-      lastValueRef.current = value;
+      lastValueRef.current = visibleValue;
     }
 
     const digitCount = units.filter(isAsciiDigit).length;
@@ -326,57 +414,74 @@ export const SlotsRun = React.memo(
 
     return (
       <View style={[rowStyle, rowAlignStyles[align]]}>
-        {units.map((unit, index) => {
-          const inLead = index < leadLength;
-          const laneKey = inLead
-            ? `lead:${index}`
-            : `slot:${units.length - 1 - index}`;
+        <LeadingElement
+          leading={visibleLeading}
+          leadingKey={visibleLeadingKey}
+          leadingGap={visibleLeadingGap}
+          enterTransition={
+            hasAnimated ? motionRecipe.enterTransition : undefined
+          }
+          elementEnterTransition={
+            isLeadingSwap ? elementEnterTransition : undefined
+          }
+          exitTransition={motionRecipe.exitTransition}
+          elementExitTransition={elementExitTransition}
+        />
+        <Animated.View
+          layout={isLeadingChange ? motionRecipe.layoutTransition : undefined}
+          style={rowStyle}
+        >
+          {units.map((unit, index) => {
+            const inLead = index < leadLength;
+            const laneKey = inLead
+              ? `lead:${index}`
+              : `slot:${units.length - 1 - index}`;
+
+            if (inLead || !isAsciiDigit(unit)) {
+              return (
+                <Animated.Text
+                  key={laneKey}
+                  layout={
+                    hasAnimated ? motionRecipe.layoutTransition : undefined
+                  }
+                  exiting={!inLead ? motionRecipe.exitTransition : undefined}
+                  style={textStyle}
+                  className={className}
+                >
+                  {unit}
+                </Animated.Text>
+              );
+            }
+
+            const delayMs = (digitCount - 1 - digitIndex) * staggerMs;
+            digitIndex += 1;
 
-          if (inLead || !isAsciiDigit(unit)) {
             return (
-              <Animated.Text
+              <Animated.View
                 key={laneKey}
                 layout={
                   hasAnimated ? motionRecipe.layoutTransition : undefined
                 }
-                exiting={!inLead ? motionRecipe.exitTransition : undefined}
-                style={textStyle}
-                className={className}
+                entering={
+                  hasAnimated ? motionRecipe.enterTransition : undefined
+                }
+                exiting={motionRecipe.exitTransition}
               >
-                {unit}
-              </Animated.Text>
+                <SlotColumn
+                  digit={Number(unit)}
+                  direction={direction}
+                  delayMs={delayMs}
+                  animateIn={hasAnimated}
+                  motionRecipe={motionRecipe}
+                  slotHeight={slotHeight}
+                  textStyle={textStyle}
+                  className={className}
+                  shadow={shadow}
+                />
+              </Animated.View>
             );
-          }
-
-          const delayMs = (digitCount - 1 - digitIndex) * staggerMs;
-          digitIndex += 1;
-
-          return (
-            <Animated.View
-              key={laneKey}
-              layout={
-                hasAnimated ? motionRecipe.layoutTransition : undefined
-              }
-              entering={
-                hasAnimated ? motionRecipe.enterTransition : undefined
-              }
-              exiting={
-                motionRecipe.exitTransition
-              }
-            >
-              <SlotColumn
-                digit={Number(unit)}
-                direction={direction}
-                delayMs={delayMs}
-                animateIn={hasAnimated}
-                motionRecipe={motionRecipe}
-                slotHeight={slotHeight}
-                textStyle={textStyle}
-                className={className}
-              />
-            </Animated.View>
-          );
-        })}
+          })}
+        </Animated.View>
       </View>
     );
   }

package/src/view/text-run.tsx

@@ -1,12 +1,8 @@
-import React, { useId, useLayoutEffect, useMemo, useRef } from "react";
+import React, { useId, useRef } from "react";
 import type { ReactNode } from "react";
 import type { StyleProp, TextStyle } from "react-native";
-import { useSharedValue } from "react-native-reanimated";
 import { useTextGlyphs } from "../hooks/use-text-glyphs";
-import {
-  createLeadingEnterTransition,
-  createLeadingExitTransition,
-} from "../motion/entry-exit-builders";
+import { useLeadingAnimation } from "../hooks/use-leading-animation";
 import type { LaminarAlign, MotionRecipe } from "../types";
 import { GlyphRun } from "./glyph-run";
 
@@ -67,62 +63,29 @@ export const TextRun = React.memo(
     }
 
     const lastValueRef = useRef(visibleValue);
-    const lastLeadingPresenceRef = useRef(Boolean(visibleLeading));
-    const lastLeadingKeyRef = useRef(visibleLeadingKey);
     const hasAnimatedRef = useRef(false);
-    const isLeadingSwap =
-      Boolean(visibleLeading) &&
-      lastLeadingPresenceRef.current &&
-      visibleLeadingKey !== lastLeadingKeyRef.current;
-    const isLeadingChange =
-      Boolean(visibleLeading) !== lastLeadingPresenceRef.current ||
-      (Boolean(visibleLeading) &&
-        visibleLeadingKey !== lastLeadingKeyRef.current);
-    // update the worklet flag after commit so render never writes a shared value
-    const leadingSwapProgress = useSharedValue(0);
-    useLayoutEffect(() => {
-      leadingSwapProgress.value = isLeadingSwap ? 1 : 0;
-    }, [isLeadingSwap, leadingSwapProgress]);
+    const {
+      elementEnterTransition,
+      elementExitTransition,
+      isLeadingChange,
+      isLeadingSwap,
+    } = useLeadingAnimation({
+      leading: visibleLeading,
+      leadingKey: visibleLeadingKey,
+      leadingGap: visibleLeadingGap,
+      motionRecipe,
+    });
     const glyphs = useTextGlyphs(
       visibleValue,
       scopeId,
       visibleLeading,
       visibleLeadingKey
     );
-    const elementEnterTransition = useMemo(
-      () =>
-        createLeadingEnterTransition({
-          durationMs: motionRecipe.durationMs,
-          easing: motionRecipe.easing,
-        }),
-      [motionRecipe.durationMs, motionRecipe.easing]
-    );
-    const elementExitTransition = useMemo(
-      () =>
-        createLeadingExitTransition({
-          durationMs: motionRecipe.durationMs,
-          easing: motionRecipe.easing,
-          leadingGap: visibleLeadingGap,
-          scale: leadingSwapProgress,
-        }),
-      [
-        visibleLeadingGap,
-        leadingSwapProgress,
-        motionRecipe.durationMs,
-        motionRecipe.easing,
-      ]
-    );
 
     // mark the first value as settled and later changes as eligible for motion
-    if (
-      visibleValue !== lastValueRef.current ||
-      Boolean(visibleLeading) !== lastLeadingPresenceRef.current ||
-      visibleLeadingKey !== lastLeadingKeyRef.current
-    ) {
+    if (visibleValue !== lastValueRef.current || isLeadingChange) {
       hasAnimatedRef.current = true;
       lastValueRef.current = visibleValue;
-      lastLeadingPresenceRef.current = Boolean(visibleLeading);
-      lastLeadingKeyRef.current = visibleLeadingKey;
     }
 
     const hasAnimated = hasAnimatedRef.current;