react-native-laminar 1.4.1 → 1.4.3

package/src/hooks/use-inline-auto-width.ts

@@ -1,4 +1,10 @@
-import { useCallback, useEffect, useRef, useState } from "react";
+import {
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useRef,
+  useState,
+} from "react";
 import type { LayoutChangeEvent } from "react-native";
 import { useAnimatedStyle, useSharedValue } from "react-native-reanimated";
 
@@ -8,6 +14,11 @@ type Params = {
   measurementKey: string;
 };
 
+type PendingProbe = {
+  key: string;
+  width: number;
+};
+
 const WIDTH_CACHE_LIMIT = 64;
 
 // measure each content signature once and drive later changes through one width value
@@ -17,10 +28,24 @@ export const useInlineAutoWidth = ({
   measurementKey,
 }: Params) => {
   const widthValue = useSharedValue(0);
+  const hasBootstrappedWidth = useSharedValue(false);
   const measuredWidthRef = useRef<number | null>(null);
   const bootstrappedRef = useRef(false);
   const widthCacheRef = useRef(new Map<string, number>());
-  const [hasBootstrappedWidth, setHasBootstrappedWidth] = useState(false);
+  const hasCapturedVisibleLayoutRef = useRef(false);
+  const initialMeasurementKeyRef = useRef<string | null>(null);
+  const firstProbeRef = useRef<PendingProbe | null>(null);
+  const latestProbeRef = useRef<PendingProbe | null>(null);
+  const bootstrapTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const [readyMeasurementKey, setReadyMeasurementKey] = useState<string | null>(
+    null
+  );
+
+  const markMeasurementReady = useCallback((key: string) => {
+    setReadyMeasurementKey((currentKey) =>
+      currentKey === key ? currentKey : key
+    );
+  }, []);
 
   // the first measurement establishes the shell without animating from zero
   const applyWidth = useCallback(
@@ -34,7 +59,7 @@ export const useInlineAutoWidth = ({
       if (!bootstrappedRef.current) {
         bootstrappedRef.current = true;
         widthValue.value = nextWidth;
-        setHasBootstrappedWidth(true);
+        hasBootstrappedWidth.value = true;
         return;
       }
 
@@ -43,6 +68,68 @@ export const useInlineAutoWidth = ({
     [driveToWidth, widthValue]
   );
 
+  const bootstrapFromProbe = useCallback(() => {
+    bootstrapTimerRef.current = null;
+
+    if (hasCapturedVisibleLayoutRef.current) {
+      return;
+    }
+
+    const firstProbe = firstProbeRef.current;
+    if (!firstProbe) {
+      return;
+    }
+
+    // The visible layout did not arrive in time, so use the first probe as a
+    // safe fallback. A later probe can still animate from this baseline.
+    hasCapturedVisibleLayoutRef.current = true;
+    initialMeasurementKeyRef.current = firstProbe.key;
+    applyWidth(firstProbe.width);
+
+    const latestProbe = latestProbeRef.current;
+    if (latestProbe && latestProbe.key !== firstProbe.key) {
+      // The target width is already cached. Defer its animation until the
+      // ready render so the shell and the new glyph row start together.
+      markMeasurementReady(latestProbe.key);
+    } else {
+      markMeasurementReady(firstProbe.key);
+    }
+  }, [applyWidth, markMeasurementReady]);
+
+  const captureVisibleLayout = useCallback(
+    (event: LayoutChangeEvent) => {
+      if (!enabled || hasCapturedVisibleLayoutRef.current) {
+        return;
+      }
+
+      if (bootstrapTimerRef.current !== null) {
+        clearTimeout(bootstrapTimerRef.current);
+        bootstrapTimerRef.current = null;
+      }
+
+      hasCapturedVisibleLayoutRef.current = true;
+      // bootstrap from the visible tree so the first explicit width matches
+      // the geometry that was already painted to the user
+      const nextWidth = Math.max(0, event.nativeEvent.layout.width);
+      // retain the visible width for the initial key so a later cache hit does
+      // not reintroduce the probe-to-visible mismatch
+      widthCacheRef.current.delete(measurementKey);
+      widthCacheRef.current.set(measurementKey, nextWidth);
+      const firstProbe = firstProbeRef.current;
+      if (firstProbe && firstProbe.key !== measurementKey) {
+        initialMeasurementKeyRef.current = firstProbe.key;
+        applyWidth(firstProbe.width);
+        markMeasurementReady(measurementKey);
+        return;
+      }
+
+      initialMeasurementKeyRef.current = measurementKey;
+      applyWidth(nextWidth);
+      markMeasurementReady(measurementKey);
+    },
+    [applyWidth, enabled, markMeasurementReady, measurementKey]
+  );
+
   const captureLayout = useCallback(
     (event: LayoutChangeEvent) => {
       if (!enabled) {
@@ -52,49 +139,104 @@ export const useInlineAutoWidth = ({
       // round up so fractional native measurements cannot clip the final glyph
       const nextWidth = Math.max(0, Math.ceil(event.nativeEvent.layout.width));
 
-      // delete before setting so a repeated key moves to the most recent position
-      widthCacheRef.current.delete(measurementKey);
+      const isInitialMeasurement =
+        initialMeasurementKeyRef.current === measurementKey;
+
+      if (!isInitialMeasurement) {
+        // delete before setting so a repeated key moves to the most recent position
+        widthCacheRef.current.delete(measurementKey);
 
-      if (widthCacheRef.current.size >= WIDTH_CACHE_LIMIT) {
-        // map insertion order gives the lru entry at the front
-        const oldestKey = widthCacheRef.current.keys().next().value;
+        if (widthCacheRef.current.size >= WIDTH_CACHE_LIMIT) {
+          // map insertion order gives the lru entry at the front
+          const oldestKey = widthCacheRef.current.keys().next().value;
 
-        if (oldestKey !== undefined) {
-          widthCacheRef.current.delete(oldestKey);
+          if (oldestKey !== undefined) {
+            widthCacheRef.current.delete(oldestKey);
+          }
         }
+
+        widthCacheRef.current.set(measurementKey, nextWidth);
       }
 
-      widthCacheRef.current.set(measurementKey, nextWidth);
-      applyWidth(nextWidth);
+      const probe = { key: measurementKey, width: nextWidth };
+      if (!firstProbeRef.current) {
+        firstProbeRef.current = probe;
+      }
+      latestProbeRef.current = probe;
+
+      if (
+        !hasCapturedVisibleLayoutRef.current &&
+        bootstrapTimerRef.current === null
+      ) {
+        bootstrapTimerRef.current = setTimeout(bootstrapFromProbe, 0);
+      }
+
+      // Do not let the initial probe override the visible first frame.
+      if (hasCapturedVisibleLayoutRef.current && !isInitialMeasurement) {
+        // captureLayout only records the target. The cache effect applies the
+        // animation during the render that releases the new glyph row.
+        markMeasurementReady(measurementKey);
+      }
     },
-    [applyWidth, enabled, measurementKey]
+    [
+      applyWidth,
+      bootstrapFromProbe,
+      enabled,
+      markMeasurementReady,
+      measurementKey,
+    ]
   );
 
   const cachedWidth = widthCacheRef.current.get(measurementKey);
 
   // a cached width can restore the shell before the hidden probe renders again
-  useEffect(() => {
-    if (enabled && cachedWidth !== undefined) {
+  useLayoutEffect(() => {
+    if (
+      enabled &&
+      cachedWidth !== undefined &&
+      hasCapturedVisibleLayoutRef.current
+    ) {
       // promote cache hits so active states stay available longer
       widthCacheRef.current.delete(measurementKey);
       widthCacheRef.current.set(measurementKey, cachedWidth);
       applyWidth(cachedWidth);
+      markMeasurementReady(measurementKey);
     }
-  }, [applyWidth, cachedWidth, enabled, measurementKey]);
+  }, [
+    applyWidth,
+    cachedWidth,
+    enabled,
+    markMeasurementReady,
+    measurementKey,
+  ]);
+
+  useEffect(
+    () => () => {
+      if (bootstrapTimerRef.current !== null) {
+        clearTimeout(bootstrapTimerRef.current);
+      }
+    },
+    []
+  );
 
   const animatedWidthStyle = useAnimatedStyle(
     () =>
-      enabled && hasBootstrappedWidth
+      enabled && hasBootstrappedWidth.value
         ? {
             width: widthValue.value,
           }
         : {},
-    [enabled, hasBootstrappedWidth]
+    [enabled]
   );
 
   return {
     captureLayout,
+    captureVisibleLayout,
     animatedWidthStyle,
+    isReady:
+      !enabled ||
+      cachedWidth !== undefined ||
+      readyMeasurementKey === measurementKey,
     shouldMeasure: enabled && cachedWidth === undefined,
   };
 };

package/src/index.tsx

@@ -79,7 +79,13 @@ export const Laminar = React.memo(function Laminar({
       textStyle,
       variant,
     ]);
-    const { captureLayout, animatedWidthStyle, shouldMeasure } =
+    const {
+      captureLayout,
+      captureVisibleLayout,
+      animatedWidthStyle,
+      isReady: isAutoSizeReady,
+      shouldMeasure,
+    } =
       useInlineAutoWidth({
         enabled: autoSize,
         driveToWidth: motionRecipe.driveNumber,
@@ -103,9 +109,11 @@ export const Laminar = React.memo(function Laminar({
         align={align}
         containerStyle={containerStyle}
         animatedWidthStyle={animatedWidthStyle}
+        onVisibleLayout={autoSize ? captureVisibleLayout : undefined}
         measurement={
           shouldMeasure ? (
             <View
+              key={measurementKey}
               onLayout={captureLayout}
               style={{ flexDirection: "row", alignSelf: "flex-start" }}
             >
@@ -157,6 +165,7 @@ export const Laminar = React.memo(function Laminar({
             leading={resolvedLeading}
             leadingKey={resolvedLeadingKey}
             leadingGap={leadingGap}
+            ready={!autoSize || isAutoSizeReady}
             textStyle={textStyle}
             className={className}
           />

package/src/view/morph-viewport.tsx

@@ -1,5 +1,5 @@
 import React, { useMemo } from "react";
-import type { StyleProp, ViewStyle } from "react-native";
+import type { LayoutChangeEvent, StyleProp, ViewStyle } from "react-native";
 import { View } from "react-native";
 import Animated from "react-native-reanimated";
 import type { LaminarAlign } from "../types";
@@ -52,6 +52,7 @@ type MorphViewportProps = {
   readonly align: LaminarAlign;
   readonly containerStyle?: StyleProp<ViewStyle>;
   readonly animatedWidthStyle?: React.ComponentProps<typeof Animated.View>["style"];
+  readonly onVisibleLayout?: (event: LayoutChangeEvent) => void;
   readonly measurement?: React.ReactNode;
   readonly children: React.ReactNode;
 };
@@ -64,6 +65,7 @@ export const MorphViewport = React.memo(
     align,
     containerStyle,
     animatedWidthStyle,
+    onVisibleLayout,
     measurement,
     children,
   }: MorphViewportProps) => {
@@ -91,7 +93,10 @@ export const MorphViewport = React.memo(
             >
               {measurement}
             </View>
-            <Animated.View style={[resolvedViewportStyle, animatedWidthStyle]}>
+            <Animated.View
+              onLayout={onVisibleLayout}
+              style={[resolvedViewportStyle, animatedWidthStyle]}
+            >
               {children}
             </Animated.View>
           </>

package/src/view/text-run.tsx

@@ -17,6 +17,7 @@ type TextRunProps = {
   readonly leading?: ReactNode;
   readonly leadingKey?: string | number;
   readonly leadingGap?: number;
+  readonly ready?: boolean;
   readonly textStyle?: StyleProp<TextStyle>;
   readonly className?: string;
 };
@@ -30,25 +31,58 @@ export const TextRun = React.memo(
     leading,
     leadingKey,
     leadingGap = 0,
+    ready = true,
     textStyle,
     className,
   }: TextRunProps) => {
     // namespace ids per instance so repeated strings do not collide
     const scopeId = useId();
-    const lastValueRef = useRef(value);
-    const lastLeadingPresenceRef = useRef(Boolean(leading));
-    const lastLeadingKeyRef = useRef(leadingKey);
+    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 lastValueRef = useRef(visibleValue);
+    const lastLeadingPresenceRef = useRef(Boolean(visibleLeading));
+    const lastLeadingKeyRef = useRef(visibleLeadingKey);
     const hasAnimatedRef = useRef(false);
     const isLeadingSwap =
-      Boolean(leading) &&
+      Boolean(visibleLeading) &&
       lastLeadingPresenceRef.current &&
-      leadingKey !== lastLeadingKeyRef.current;
+      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 glyphs = useTextGlyphs(value, scopeId, leading, leadingKey);
+    const glyphs = useTextGlyphs(
+      visibleValue,
+      scopeId,
+      visibleLeading,
+      visibleLeadingKey
+    );
     const elementEnterTransition = useMemo(
       () =>
         createLeadingEnterTransition({
@@ -62,11 +96,11 @@ export const TextRun = React.memo(
         createLeadingExitTransition({
           durationMs: motionRecipe.durationMs,
           easing: motionRecipe.easing,
-          leadingGap,
+          leadingGap: visibleLeadingGap,
           scale: leadingSwapProgress,
         }),
       [
-        leadingGap,
+        visibleLeadingGap,
         leadingSwapProgress,
         motionRecipe.durationMs,
         motionRecipe.easing,
@@ -75,14 +109,14 @@ export const TextRun = React.memo(
 
     // mark the first value as settled and later changes as eligible for motion
     if (
-      value !== lastValueRef.current ||
-      Boolean(leading) !== lastLeadingPresenceRef.current ||
-      leadingKey !== lastLeadingKeyRef.current
+      visibleValue !== lastValueRef.current ||
+      Boolean(visibleLeading) !== lastLeadingPresenceRef.current ||
+      visibleLeadingKey !== lastLeadingKeyRef.current
     ) {
       hasAnimatedRef.current = true;
-      lastValueRef.current = value;
-      lastLeadingPresenceRef.current = Boolean(leading);
-      lastLeadingKeyRef.current = leadingKey;
+      lastValueRef.current = visibleValue;
+      lastLeadingPresenceRef.current = Boolean(visibleLeading);
+      lastLeadingKeyRef.current = visibleLeadingKey;
     }
 
     const hasAnimated = hasAnimatedRef.current;
@@ -103,7 +137,7 @@ export const TextRun = React.memo(
         }
         exitTransition={motionRecipe.exitTransition}
         elementExitTransition={elementExitTransition}
-        leadingGap={leadingGap}
+        leadingGap={visibleLeadingGap}
         align={align}
         textStyle={textStyle}
         className={className}