react-native-laminar 1.1.0 → 1.4.1

package/src/hooks/use-morph-motion.ts

@@ -18,13 +18,14 @@ type MorphMotion = {
   readonly staggerMs: number;
 };
 
+// resolve one motion recipe and one shared stagger unit for a render tree
 export const useMorphMotion = ({
   variant,
   animationPreset,
   animationDuration,
   stagger,
 }: Params): MorphMotion => {
-  // numbers feel better with snappy unless you pick something else
+  // numeric variants need a quicker default because their lanes update often
   const resolvedPreset =
     animationPreset ?? (variant === "text" ? "default" : "snappy");
 

package/src/hooks/use-morph-text-style.ts

@@ -12,12 +12,14 @@ type MorphTextStyle = {
   readonly textStyle: StyleProp<TextStyle>;
 };
 
+// compose the public style layers into the style passed to every glyph
 export const useMorphTextStyle = ({
   fontSize,
   color,
   fontStyle,
   style,
 }: Params): MorphTextStyle => {
+  // keep the base layer small so caller styles can override it predictably
   const baseTextStyle = useMemo(() => {
     const nextStyle: TextStyle = {
       includeFontPadding: false,
@@ -34,6 +36,7 @@ export const useMorphTextStyle = ({
     return nextStyle;
   }, [color, fontSize]);
 
+  // preserve the merge order used by the public style contract
   const textStyle = useMemo(
     () => [baseTextStyle, fontStyle, style],
     [baseTextStyle, fontStyle, style]

package/src/hooks/use-numeric-lanes.ts

@@ -20,6 +20,7 @@ type NumericLaneSnapshot = {
   readonly leadLength: number;
 };
 
+// retain numeric lane identity across value changes without storing it in state
 export const useNumericLanes = (value: string): NumericLaneSnapshot => {
   const units = useMemo(() => splitDisplayUnits(value), [value]);
   const ledgerRef = useRef<NumericLedger>({

package/src/hooks/use-text-glyphs.ts

@@ -1,4 +1,4 @@
-import { useMemo, useRef } from "react";
+import { useMemo, useRef, type ReactNode } from "react";
 import {
   normalizeDisplayUnit,
   splitDisplayUnits,
@@ -8,28 +8,62 @@ import type { GlyphToken } from "../types";
 
 type TextGlyphLedger = {
   previousValue: string;
-  previousUnits: readonly string[];
+  previousSignatures: readonly string[];
   glyphKeys: readonly string[];
   nextSeed: number;
 };
 
+type TextGlyphUnit =
+  | { readonly kind: "text"; readonly signature: string; readonly value: string }
+  | { readonly kind: "element"; readonly signature: string; readonly element: ReactNode };
+
+// build the inline token stream that lets text and leading content share one ledger
 export const useTextGlyphs = (
   value: string,
-  namespace: string
+  namespace: string,
+  leading?: ReactNode,
+  leadingKey?: string | number
 ): readonly GlyphToken[] => {
-  const units = useMemo(() => splitDisplayUnits(value), [value]);
+  const units = useMemo<readonly TextGlyphUnit[]>(
+    () => [
+      // the map key becomes the identity when leading content is state keyed
+      ...(leading
+        ? [
+            {
+              kind: "element",
+              signature: `leading:${String(leadingKey ?? "default")}`,
+              element: leading,
+            } as const,
+          ]
+        : []),
+      ...splitDisplayUnits(value).map((unit) => ({
+        kind: "text" as const,
+        signature: `text:${unit}`,
+        value: unit,
+      })),
+    ],
+    [leading, leadingKey, value]
+  );
+  const signatures = units.map((unit) => unit.signature);
   const ledgerRef = useRef<TextGlyphLedger>({
     previousValue: value,
-    previousUnits: units,
+    previousSignatures: signatures,
     glyphKeys: units.map((_, index) => `${namespace}:c${index}`),
     nextSeed: units.length,
   });
 
-  if (value !== ledgerRef.current.previousValue) {
+  // reconcile only when a token signature changes so stable glyphs keep their views
+  if (
+    value !== ledgerRef.current.previousValue ||
+    signatures.length !== ledgerRef.current.previousSignatures.length ||
+    signatures.some(
+      (signature, index) => signature !== ledgerRef.current.previousSignatures[index]
+    )
+  ) {
     // keep ids stable so unchanged glyphs stay mounted between updates
     const nextLedger = reconcileTextGlyphKeys(
-      ledgerRef.current.previousUnits,
-      units,
+      ledgerRef.current.previousSignatures,
+      signatures,
       ledgerRef.current.glyphKeys,
       ledgerRef.current.nextSeed,
       namespace
@@ -37,7 +71,7 @@ export const useTextGlyphs = (
 
     ledgerRef.current = {
       previousValue: value,
-      previousUnits: units,
+      previousSignatures: signatures,
       glyphKeys: nextLedger.glyphKeys,
       nextSeed: nextLedger.nextSeed,
     };
@@ -45,11 +79,15 @@ export const useTextGlyphs = (
 
   const glyphKeys = ledgerRef.current.glyphKeys;
 
+  // normalize spaces at the edge where tokens become renderable glyphs
   return useMemo(
     () =>
       units.map((unit, index) => ({
         id: glyphKeys[index],
-        value: normalizeDisplayUnit(unit),
+        kind: unit.kind,
+        ...(unit.kind === "text"
+          ? { value: normalizeDisplayUnit(unit.value) }
+          : { element: unit.element }),
       })),
     [glyphKeys, units]
   );

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,17 +7,23 @@ 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",
     fontSize,
     color,
+    align = "left",
     className,
+    leading,
+    leadingKey,
+    leadingGap = 0,
     style,
     containerStyle,
     fontStyle,
@@ -28,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,
@@ -41,38 +53,97 @@ 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 (
       <MorphViewport
         autoSize={autoSize}
         clipToBounds={clipToBounds}
+        align={align}
         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}
+            align={align}
             fontSize={fontSize}
             textStyle={textStyle}
             staggerMs={staggerMs}
@@ -82,6 +153,10 @@ export const Laminar = React.memo(function Laminar({
           <TextRun
             value={resolvedValue}
             motionRecipe={motionRecipe}
+            align={align}
+            leading={resolvedLeading}
+            leadingKey={resolvedLeadingKey}
+            leadingGap={leadingGap}
             textStyle={textStyle}
             className={className}
           />
@@ -90,10 +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,7 +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];
 
@@ -28,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;
@@ -47,7 +54,14 @@ export type MorphingTextProps = {
   readonly variant?: MorphContentVariant;
   readonly fontSize?: number;
   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

@@ -5,7 +5,7 @@ import type {
   ComplexAnimationBuilder,
   EntryExitAnimationFunction,
 } from "react-native-reanimated";
-import type { GlyphToken } from "../types";
+import type { GlyphToken, LaminarAlign } from "../types";
 
 const rowStyle = {
   flexDirection: "row",
@@ -13,36 +13,69 @@ const rowStyle = {
   alignSelf: "flex-start",
 } as const;
 
+const rowAlignStyles = {
+  left: { alignSelf: "flex-start" },
+  center: { alignSelf: "center" },
+  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;
   }>) => (
-      <View style={rowStyle}>
+    // 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>
     )
 );