react-native-laminar 1.2.0 → 1.4.1

package/src/motion/entry-exit-builders.ts

@@ -1,9 +1,11 @@
 import {
   type EntryExitAnimationFunction,
+  type ExitAnimationsValues,
   type WithTimingConfig,
   withDelay,
   withTiming,
 } from "react-native-reanimated";
+import type { SharedValue } from "react-native-reanimated";
 
 type TransitionParams = {
   readonly delayMs?: number;
@@ -17,6 +19,40 @@ type TransitionParams = {
   readonly toScale: number;
 };
 
+type LeadingExitTransitionParams = {
+  readonly durationMs: number;
+  readonly easing: NonNullable<WithTimingConfig["easing"]>;
+  readonly leadingGap: number;
+  readonly scale?: boolean | SharedValue<number>;
+};
+
+type LeadingEnterTransitionParams = {
+  readonly durationMs: number;
+  readonly easing: NonNullable<WithTimingConfig["easing"]>;
+};
+
+// leading replacements use scale while first appearance uses the regular fade path
+export const createLeadingEnterTransition = ({
+  durationMs,
+  easing,
+}: LeadingEnterTransitionParams): EntryExitAnimationFunction => {
+  return () => {
+    "worklet";
+
+    return {
+      initialValues: {
+        opacity: 0,
+        transform: [{ scale: 0.5 }],
+      },
+      animations: {
+        opacity: withTiming(1, { duration: durationMs, easing }),
+        transform: [{ scale: withTiming(1, { duration: durationMs, easing }) }],
+      },
+    };
+  };
+};
+
+// one builder covers glyph opacity, travel, scale, and optional stagger timing
 export const createShiftTransition = ({
   delayMs = 0,
   durationMs,
@@ -72,3 +108,40 @@ export const createShiftTransition = ({
     };
   };
 };
+
+// the shared swap flag lets an exiting worklet read the current transition type
+export const createLeadingExitTransition = ({
+  durationMs,
+  easing,
+  leadingGap,
+  scale = false,
+}: LeadingExitTransitionParams): EntryExitAnimationFunction => {
+  return (values: ExitAnimationsValues) => {
+    "worklet";
+
+    const shouldScale =
+      typeof scale === "object" ? scale.value > 0.5 : scale;
+
+    return {
+      initialValues: {
+        opacity: 1,
+        originX: values.currentOriginX,
+        ...(shouldScale ? { transform: [{ scale: 1 }] } : {}),
+      },
+      animations: {
+        opacity: withTiming(0, { duration: durationMs, easing }),
+        originX: withTiming(
+          values.currentOriginX - values.currentWidth - leadingGap,
+          { duration: durationMs, easing }
+        ),
+        ...(shouldScale
+          ? {
+              transform: [
+                { scale: withTiming(0.5, { duration: durationMs, easing }) },
+              ],
+            }
+          : {}),
+      },
+    };
+  };
+};

package/src/motion/preset-map.ts

@@ -13,6 +13,7 @@ import type {
   MorphAnimationPresetName,
 } from "../types";
 
+// keep all presets on one curve family so layout and glyph motion agree
 const DEFAULT_CURVE = [0.19, 1, 0.22, 1] as const;
 
 export const MOTION_PRESETS: Record<
@@ -40,11 +41,13 @@ export const MOTION_PRESETS: Record<
   },
 } as const;
 
+// the public preset table uses seconds while reanimated timing uses milliseconds
 const toMilliseconds = (seconds: number) => Math.round(seconds * 1000);
 
 const toDampingRatio = (bounce: number) =>
   Math.max(0.55, Math.min(1, 1 - bounce));
 
+// spring and timing presets share the same opacity contract
 const createOpacityTransition = (
   fromOpacity: number,
   toOpacity: number,
@@ -68,6 +71,7 @@ const createOpacityTransition = (
   };
 };
 
+// convert a named preset into the builders consumed by every rendering variant
 export const resolveMotionRecipe = (
   presetName: MorphAnimationPresetName = "default",
   durationOverride?: number

package/src/types.ts

@@ -1,3 +1,4 @@
+import type { ReactNode } from "react";
 import type { StyleProp, TextStyle, ViewStyle } from "react-native";
 import type {
   ComplexAnimationBuilder,
@@ -11,8 +12,10 @@ export type MorphAnimationPresetName =
   | "snappy"
   | "bouncy";
 
-export type MorphContentVariant = "text" | "number";
+export type MorphContentVariant = "text" | "number" | "slots";
 export type LaminarAlign = "left" | "center" | "right";
+// text keys let leading content follow the same state as the displayed value
+export type LaminarLeadingMap = Readonly<Record<string, ReactNode>>;
 
 type CubicBezierTuple = readonly [number, number, number, number];
 
@@ -29,12 +32,15 @@ export type MorphAnimationPreset =
 
 export type GlyphToken = {
   readonly id: string;
-  readonly value: string;
+  readonly kind: "text" | "element";
+  readonly value?: string;
+  readonly element?: ReactNode;
 };
 
 export type NumericFlowDirection = -1 | 0 | 1;
 
 export type MotionRecipe = {
+  // every variant consumes the same timing and layout contract
   readonly durationMs: number;
   readonly easing: NonNullable<WithTimingConfig["easing"]>;
   readonly layoutTransition: ComplexAnimationBuilder;
@@ -50,6 +56,12 @@ export type MorphingTextProps = {
   readonly color?: string;
   readonly align?: LaminarAlign;
   readonly className?: string;
+  /** optional inline element reconciled and animated as the leading token */
+  readonly leading?: ReactNode | LaminarLeadingMap;
+  /** identity for swapping one leading element for another */
+  readonly leadingKey?: string | number;
+  /** spacing between the leading element and the first text glyph */
+  readonly leadingGap?: number;
   readonly style?: StyleProp<TextStyle>;
   readonly containerStyle?: StyleProp<ViewStyle>;
   readonly fontStyle?: StyleProp<TextStyle>;

package/src/view/glyph-run.tsx

@@ -19,38 +19,63 @@ const rowAlignStyles = {
   right: { alignSelf: "flex-end" },
 } as const;
 
+// render text and inline elements through one animated token row
 export const GlyphRun = React.memo(
   ({
     glyphs,
     layoutTransition,
     enterTransition,
+    elementEnterTransition,
     exitTransition,
+    elementExitTransition,
+    leadingGap,
     align,
     textStyle,
     className,
   }: Readonly<{
     glyphs: readonly GlyphToken[];
-    layoutTransition: ComplexAnimationBuilder;
+    layoutTransition?: ComplexAnimationBuilder;
     enterTransition?: EntryExitAnimationFunction;
+    elementEnterTransition?: EntryExitAnimationFunction;
     exitTransition?: EntryExitAnimationFunction;
+    elementExitTransition?: EntryExitAnimationFunction;
+    leadingGap?: number;
     align: LaminarAlign;
     textStyle?: StyleProp<TextStyle>;
     className?: string;
   }>) => (
+    // each token keeps its own view so reanimated can animate only changed content
       <View style={[rowStyle, rowAlignStyles[align]]}>
         {/* glyph ids decide what swaps, layout handles the row reflow */}
-        {glyphs.map((glyph) => (
-          <Animated.Text
-            key={glyph.id}
-            layout={layoutTransition}
-            entering={enterTransition}
-            exiting={exitTransition}
-            style={textStyle}
-            className={className}
-          >
-            {glyph.value}
-          </Animated.Text>
-        ))}
+        {glyphs.map((glyph, glyphIndex) =>
+          glyph.kind === "element" ? (
+            <Animated.View
+              key={glyph.id}
+              layout={layoutTransition}
+              entering={elementEnterTransition ?? enterTransition}
+              exiting={elementExitTransition ?? exitTransition}
+              style={[
+                { alignItems: "center", justifyContent: "center" },
+                glyphIndex === 0 && (leadingGap ?? 0) > 0
+                  ? { marginRight: leadingGap }
+                  : undefined,
+              ]}
+            >
+              {glyph.element}
+            </Animated.View>
+          ) : (
+            <Animated.Text
+              key={glyph.id}
+              layout={layoutTransition}
+              entering={enterTransition}
+              exiting={exitTransition}
+              style={textStyle}
+              className={className}
+            >
+              {glyph.value}
+            </Animated.Text>
+          )
+        )}
       </View>
     )
 );

package/src/view/morph-viewport.tsx

@@ -56,6 +56,7 @@ type MorphViewportProps = {
   readonly children: React.ReactNode;
 };
 
+// separate hidden measurement from visible content while sharing the shell alignment
 export const MorphViewport = React.memo(
   ({
     autoSize,
@@ -66,6 +67,7 @@ export const MorphViewport = React.memo(
     measurement,
     children,
   }: MorphViewportProps) => {
+    // compute alignment once so the animated shell and its child share one layout contract
     const resolvedViewportStyle = useMemo(
       () => [
         viewportStyle,
@@ -75,6 +77,7 @@ export const MorphViewport = React.memo(
       [align, clipToBounds]
     );
 
+    // keep measurement outside the visible viewport so it cannot affect accessibility or layout
     return (
       <View style={[shellStyle, shellAlignStyles[align], containerStyle]}>
         {autoSize ? (

package/src/view/number-lane.tsx

@@ -33,6 +33,7 @@ type NumberLaneProps = {
   readonly className?: string;
 };
 
+// render one place-value lane with a hidden layout probe and an animated token
 export const NumberLane = React.memo(
   ({
     unit,
@@ -46,6 +47,7 @@ export const NumberLane = React.memo(
     textStyle,
     className,
   }: NumberLaneProps) => {
+    // punctuation stays in place while digits travel by the shared numeric direction
     const usesDigitTravel = isAsciiDigit(unit);
     const verticalOffset =
       direction > 0
@@ -98,14 +100,17 @@ export const NumberLane = React.memo(
       ]
     );
 
+    // prefix units do not need an absolute lane or a duplicate probe
     if (isLead) {
       return <Text style={textStyle} className={className}>{unit}</Text>;
     }
 
     return (
       <Animated.View
-        layout={motionRecipe.layoutTransition}
-        entering={hasAnimated ? motionRecipe.enterTransition : undefined}
+        layout={hasAnimated ? motionRecipe.layoutTransition : undefined}
+        entering={
+          hasAnimated ? motionRecipe.enterTransition : undefined
+        }
         exiting={motionRecipe.exitTransition}
         style={laneStyle}
       >

package/src/view/number-run.tsx

@@ -26,6 +26,7 @@ type NumberRunProps = {
   readonly className?: string;
 };
 
+// arrange numeric lanes from left to right while the hook preserves their identities
 export const NumberRun = React.memo(
   ({
     value,
@@ -36,6 +37,7 @@ export const NumberRun = React.memo(
     staggerMs,
     className,
   }: Readonly<NumberRunProps>) => {
+    // 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 hasAnimatedRef = useRef(false);
@@ -46,6 +48,7 @@ export const NumberRun = React.memo(
       lastValueRef.current = value;
     }
 
+    // scale travel from the font while keeping a minimum visible movement
     const travelDistance = useMemo(
       () => Math.max(8, Math.round((fontSize ?? 16) * 0.4)),
       [fontSize]