react-native-laminar 1.2.0 → 1.4.2

package/src/index.tsx

@@ -1,5 +1,5 @@
 import React from "react";
-import { Text } from "react-native";
+import { StyleSheet, Text, View } from "react-native";
 import { useInlineAutoWidth } from "./hooks/use-inline-auto-width";
 import { useMorphMotion } from "./hooks/use-morph-motion";
 import { useMorphTextStyle } from "./hooks/use-morph-text-style";
@@ -7,11 +7,13 @@ import {
   normalizeDisplayUnit,
   splitDisplayUnits,
 } from "./model/display-units";
-import type { MorphingTextProps } from "./types";
+import type { LaminarLeadingMap, MorphingTextProps } from "./types";
 import { MorphViewport } from "./view/morph-viewport";
 import { NumberRun } from "./view/number-run";
+import { SlotsRun } from "./view/slots-run";
 import { TextRun } from "./view/text-run";
 
+// choose the content variant and connect it to the shared viewport and measurement flow
 export const Laminar = React.memo(function Laminar({
     text,
     variant = "text",
@@ -19,6 +21,9 @@ export const Laminar = React.memo(function Laminar({
     color,
     align = "left",
     className,
+    leading,
+    leadingKey,
+    leadingGap = 0,
     style,
     containerStyle,
     fontStyle,
@@ -29,6 +34,12 @@ export const Laminar = React.memo(function Laminar({
     clipToBounds = false,
   }: Readonly<MorphingTextProps>) {
     const resolvedValue = String(text ?? "");
+    // resolve state keyed leading content before measurement and token reconciliation
+    const leadingMap = isLeadingMap(leading) ? leading : undefined;
+    const resolvedLeading: React.ReactNode = leadingMap
+      ? leadingMap[resolvedValue]
+      : (leading as React.ReactNode);
+    const resolvedLeadingKey = leadingMap ? resolvedValue : leadingKey;
     const { motionRecipe, staggerMs } = useMorphMotion({
       variant,
       animationPreset,
@@ -42,16 +53,47 @@ export const Laminar = React.memo(function Laminar({
       style,
     });
 
-    const { captureLayout, animatedWidthStyle } = useInlineAutoWidth({
-      enabled: autoSize,
-      driveToWidth: motionRecipe.driveNumber,
-    });
+    // invalidate the probe when text style, leading content, or leading spacing changes
+    const measurementKey = React.useMemo(() => {
+      const flattenedStyle = StyleSheet.flatten(textStyle);
+
+      return JSON.stringify([
+        resolvedValue,
+        flattenedStyle?.fontFamily,
+        flattenedStyle?.fontSize,
+        flattenedStyle?.fontStyle,
+        flattenedStyle?.fontWeight,
+        flattenedStyle?.fontVariant,
+        flattenedStyle?.letterSpacing,
+        flattenedStyle?.lineHeight,
+        flattenedStyle?.textTransform,
+        variant === "text" && Boolean(resolvedLeading),
+        variant === "text" ? resolvedLeadingKey : undefined,
+        variant === "text" ? leadingGap : 0,
+      ]);
+    }, [
+      leadingGap,
+      resolvedLeading,
+      resolvedLeadingKey,
+      resolvedValue,
+      textStyle,
+      variant,
+    ]);
+    const { captureLayout, animatedWidthStyle, shouldMeasure } =
+      useInlineAutoWidth({
+        enabled: autoSize,
+        driveToWidth: motionRecipe.driveNumber,
+        measurementKey,
+      });
+    // measurement uses the same normalized units as the visible text row
     const measuredValue = React.useMemo(() => {
       if (!autoSize) {
         return "";
       }
 
-      return splitDisplayUnits(resolvedValue).map(normalizeDisplayUnit).join("");
+      return splitDisplayUnits(resolvedValue)
+        .map(normalizeDisplayUnit)
+        .join("");
     }, [autoSize, resolvedValue]);
 
     return (
@@ -62,16 +104,42 @@ export const Laminar = React.memo(function Laminar({
         containerStyle={containerStyle}
         animatedWidthStyle={animatedWidthStyle}
         measurement={
-          <Text
-            numberOfLines={1}
-            onLayout={captureLayout}
-            style={textStyle}
-          >
-            {measuredValue}
-          </Text>
+          shouldMeasure ? (
+            <View
+              onLayout={captureLayout}
+              style={{ flexDirection: "row", alignSelf: "flex-start" }}
+            >
+              {variant === "text" && resolvedLeading ? (
+                <View
+                  style={{
+                    alignItems: "center",
+                    justifyContent: "center",
+                    marginRight: leadingGap,
+                  }}
+                >
+                  {resolvedLeading}
+                </View>
+              ) : null}
+              {splitDisplayUnits(measuredValue).map((unit, index) => (
+                <Text key={`${unit}-${index}`} style={textStyle}>
+                  {normalizeDisplayUnit(unit)}
+                </Text>
+              ))}
+            </View>
+          ) : undefined
         }
       >
-        {variant === "number" ? (
+        {variant === "slots" ? (
+          <SlotsRun
+            value={resolvedValue}
+            motionRecipe={motionRecipe}
+            align={align}
+            fontSize={fontSize}
+            textStyle={textStyle}
+            staggerMs={staggerMs}
+            className={className}
+          />
+        ) : variant === "number" ? (
           <NumberRun
             value={resolvedValue}
             motionRecipe={motionRecipe}
@@ -86,6 +154,9 @@ export const Laminar = React.memo(function Laminar({
             value={resolvedValue}
             motionRecipe={motionRecipe}
             align={align}
+            leading={resolvedLeading}
+            leadingKey={resolvedLeadingKey}
+            leadingGap={leadingGap}
             textStyle={textStyle}
             className={className}
           />
@@ -94,11 +165,21 @@ export const Laminar = React.memo(function Laminar({
   );
   });
 
-export const MorphingText = Laminar;
+function isLeadingMap(
+  value: MorphingTextProps["leading"]
+): value is LaminarLeadingMap {
+  // react elements are objects too, so exclude them before treating a value as a map
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    !React.isValidElement(value) &&
+    !Array.isArray(value)
+  );
+}
 
-export default Laminar;
 export type {
   LaminarAlign,
+  LaminarLeadingMap,
   LaminarProps,
   MorphAnimationPresetName,
   MorphContentVariant,

package/src/model/display-units.ts

@@ -4,6 +4,7 @@ const graphemeSegmenter =
     ? new Intl.Segmenter(undefined, { granularity: "grapheme" })
     : null;
 
+// segment graphemes when the runtime supports them so emoji and combining marks stay whole
 export const splitDisplayUnits = (input: string): string[] => {
   if (graphemeSegmenter) {
     return Array.from(
@@ -15,12 +16,14 @@ export const splitDisplayUnits = (input: string): string[] => {
   return Array.from(input);
 };
 
-// swap plain spaces so measured text keeps its width
+// replace plain spaces because native text measurement can collapse them
 export const normalizeDisplayUnit = (unit: string) =>
   unit === " " ? NBSP : unit;
 
+// numeric lanes only treat ascii digits as place-value columns
 export const isAsciiDigit = (unit: string) => unit >= "0" && unit <= "9";
 
+// leading symbols and punctuation stay attached to the left side of a number
 export const findNumericLeadLength = (units: readonly string[]) => {
   const firstDigitIndex = units.findIndex(isAsciiDigit);
 

package/src/model/numeric-lanes.ts

@@ -4,9 +4,11 @@ import {
   splitDisplayUnits,
 } from "./display-units";
 
+// strip formatting before comparing values so direction follows the displayed number
 const readNumericMagnitude = (input: string) =>
   parseFloat(input.replace(/[^0-9.-]/g, "")) || 0;
 
+// the sign controls which side of each digit lane enters and exits
 const deriveFlowDirection = (
   previousValue: string,
   nextValue: string
@@ -19,6 +21,7 @@ type ReconciledLaneState = {
   readonly direction: NumericFlowDirection;
 };
 
+// preserve right-aligned place values while allowing prefixes to grow or shrink
 export const reconcileNumericLanes = (
   previousValue: string,
   nextValue: string,

package/src/model/text-keys.ts

@@ -1,3 +1,4 @@
+// find the longest ordered set of shared units so edits keep nearby glyph identity
 const computeLcsPairs = (
   previousUnits: readonly string[],
   nextUnits: readonly string[]
@@ -9,6 +10,7 @@ const computeLcsPairs = (
     return [];
   }
 
+  // dynamic programming makes the middle edit deterministic when prefix and suffix match
   const dp = Array.from({ length: previousLength + 1 }, () =>
     new Array<number>(nextLength + 1).fill(0)
   );
@@ -54,6 +56,7 @@ type ReconciledTextGlyphState = {
   readonly nextSeed: number;
 };
 
+// reuse prefix, suffix, and lcs matches before allocating keys for new glyphs
 export const reconcileTextGlyphKeys = (
   previousUnits: readonly string[],
   nextUnits: readonly string[],

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]