react-native-laminar 1.0.0

package/src/model/numeric-lanes.ts

@@ -0,0 +1,80 @@
+import type { NumericFlowDirection } from "../types";
+import {
+  findNumericLeadLength,
+  splitDisplayUnits,
+} from "./display-units";
+
+const readNumericMagnitude = (input: string) =>
+  parseFloat(input.replace(/[^0-9.-]/g, "")) || 0;
+
+const deriveFlowDirection = (
+  previousValue: string,
+  nextValue: string
+): NumericFlowDirection =>
+  Math.sign(readNumericMagnitude(nextValue) - readNumericMagnitude(previousValue)) as NumericFlowDirection;
+
+type ReconciledLaneState = {
+  readonly laneKeys: readonly number[];
+  readonly nextSeed: number;
+  readonly direction: NumericFlowDirection;
+};
+
+export const reconcileNumericLanes = (
+  previousValue: string,
+  nextValue: string,
+  previousKeys: readonly number[],
+  seed: number
+): ReconciledLaneState => {
+  const previousUnits = splitDisplayUnits(previousValue);
+  const nextUnits = splitDisplayUnits(nextValue);
+  const nextLaneKeys = new Array(nextUnits.length);
+  let nextSeed = seed;
+
+  const nextLeadLength = findNumericLeadLength(nextUnits);
+  const previousLeadLength = findNumericLeadLength(previousUnits);
+  const sharedLeadLength = Math.min(nextLeadLength, previousLeadLength);
+
+  for (let index = 0; index < nextLeadLength; index += 1) {
+    nextLaneKeys[index] =
+      index < sharedLeadLength && nextUnits[index] === previousUnits[index]
+        ? previousKeys[index]
+        : nextSeed++;
+  }
+
+  const previousTailUnits = previousUnits.slice(previousLeadLength);
+  const nextTailUnits = nextUnits.slice(nextLeadLength);
+  const previousTailKeys = previousKeys.slice(previousLeadLength);
+  const laneCount = Math.max(previousTailUnits.length, nextTailUnits.length);
+
+  const leftPaddedPreviousUnits = [
+    ...Array<string>(Math.max(0, laneCount - previousTailUnits.length)).fill(""),
+    ...previousTailUnits,
+  ];
+  const leftPaddedNextUnits = [
+    ...Array<string>(Math.max(0, laneCount - nextTailUnits.length)).fill(""),
+    ...nextTailUnits,
+  ];
+  const leftPaddedPreviousKeys = [
+    ...Array<number>(Math.max(0, laneCount - previousTailKeys.length)).fill(-1),
+    ...previousTailKeys,
+  ];
+
+  // pad from the left so the rightmost digits keep their place value lanes
+  const nextTailOffset = laneCount - nextTailUnits.length;
+
+  for (let index = 0; index < nextTailUnits.length; index += 1) {
+    const paddedIndex = nextTailOffset + index;
+    const nextUnit = leftPaddedNextUnits[paddedIndex];
+    const previousUnit = leftPaddedPreviousUnits[paddedIndex];
+    const previousKey = leftPaddedPreviousKeys[paddedIndex];
+
+    nextLaneKeys[nextLeadLength + index] =
+      nextUnit === previousUnit && previousKey >= 0 ? previousKey : nextSeed++;
+  }
+
+  return {
+    laneKeys: nextLaneKeys,
+    nextSeed,
+    direction: deriveFlowDirection(previousValue, nextValue),
+  };
+};

package/src/model/text-keys.ts

@@ -0,0 +1,123 @@
+const computeLcsPairs = (
+  previousUnits: readonly string[],
+  nextUnits: readonly string[]
+): readonly [number, number][] => {
+  const previousLength = previousUnits.length;
+  const nextLength = nextUnits.length;
+
+  if (previousLength === 0 || nextLength === 0) {
+    return [];
+  }
+
+  const dp = Array.from({ length: previousLength + 1 }, () =>
+    new Array<number>(nextLength + 1).fill(0)
+  );
+
+  for (let previousIndex = 1; previousIndex <= previousLength; previousIndex += 1) {
+    for (let nextIndex = 1; nextIndex <= nextLength; nextIndex += 1) {
+      dp[previousIndex][nextIndex] =
+        previousUnits[previousIndex - 1] === nextUnits[nextIndex - 1]
+          ? dp[previousIndex - 1][nextIndex - 1] + 1
+          : Math.max(dp[previousIndex - 1][nextIndex], dp[previousIndex][nextIndex - 1]);
+    }
+  }
+
+  const pairs: [number, number][] = [];
+  let previousIndex = previousLength;
+  let nextIndex = nextLength;
+
+  while (previousIndex > 0 && nextIndex > 0) {
+    if (previousUnits[previousIndex - 1] === nextUnits[nextIndex - 1]) {
+      pairs.push([previousIndex - 1, nextIndex - 1]);
+      previousIndex -= 1;
+      nextIndex -= 1;
+      continue;
+    }
+
+    if (
+      dp[previousIndex - 1][nextIndex] > dp[previousIndex][nextIndex - 1] ||
+      (dp[previousIndex - 1][nextIndex] === dp[previousIndex][nextIndex - 1] &&
+        previousIndex >= nextIndex)
+    ) {
+      previousIndex -= 1;
+    } else {
+      nextIndex -= 1;
+    }
+  }
+
+  pairs.reverse();
+  return pairs;
+};
+
+type ReconciledTextGlyphState = {
+  readonly glyphKeys: readonly string[];
+  readonly nextSeed: number;
+};
+
+export const reconcileTextGlyphKeys = (
+  previousUnits: readonly string[],
+  nextUnits: readonly string[],
+  previousKeys: readonly string[],
+  seed: number,
+  namespace: string
+): ReconciledTextGlyphState => {
+  const previousLength = previousUnits.length;
+  const nextLength = nextUnits.length;
+  const nextGlyphKeys = new Array<string>(nextUnits.length).fill("");
+  let nextSeed = seed;
+
+  let sharedPrefixLength = 0;
+  while (
+    sharedPrefixLength < previousLength &&
+    sharedPrefixLength < nextLength &&
+    previousUnits[sharedPrefixLength] === nextUnits[sharedPrefixLength]
+  ) {
+    nextGlyphKeys[sharedPrefixLength] =
+      previousKeys[sharedPrefixLength] ?? `${namespace}:c${nextSeed++}`;
+    sharedPrefixLength += 1;
+  }
+
+  let sharedSuffixLength = 0;
+  while (
+    sharedSuffixLength < previousLength - sharedPrefixLength &&
+    sharedSuffixLength < nextLength - sharedPrefixLength &&
+    previousUnits[previousLength - 1 - sharedSuffixLength] ===
+      nextUnits[nextLength - 1 - sharedSuffixLength]
+  ) {
+    const previousIndex = previousLength - 1 - sharedSuffixLength;
+    const nextIndex = nextLength - 1 - sharedSuffixLength;
+    nextGlyphKeys[nextIndex] =
+      previousKeys[previousIndex] ?? `${namespace}:c${nextSeed++}`;
+    sharedSuffixLength += 1;
+  }
+
+  const previousMiddleEnd = previousLength - sharedSuffixLength;
+  const nextMiddleEnd = nextLength - sharedSuffixLength;
+  const previousMiddleUnits = previousUnits.slice(
+    sharedPrefixLength,
+    previousMiddleEnd
+  );
+  const nextMiddleUnits = nextUnits.slice(sharedPrefixLength, nextMiddleEnd);
+
+  // lcs keeps shared middle glyphs in place when the text changes
+  const matches = computeLcsPairs(previousMiddleUnits, nextMiddleUnits);
+
+  for (const [previousIndex, nextIndex] of matches) {
+    const absolutePreviousIndex = previousIndex + sharedPrefixLength;
+    const absoluteNextIndex = nextIndex + sharedPrefixLength;
+
+    nextGlyphKeys[absoluteNextIndex] =
+      previousKeys[absolutePreviousIndex] ?? `${namespace}:c${nextSeed++}`;
+  }
+
+  for (let nextIndex = 0; nextIndex < nextGlyphKeys.length; nextIndex += 1) {
+    if (!nextGlyphKeys[nextIndex]) {
+      nextGlyphKeys[nextIndex] = `${namespace}:c${nextSeed++}`;
+    }
+  }
+
+  return {
+    glyphKeys: nextGlyphKeys,
+    nextSeed,
+  };
+};

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

@@ -0,0 +1,74 @@
+import {
+  type EntryExitAnimationFunction,
+  type WithTimingConfig,
+  withDelay,
+  withTiming,
+} from "react-native-reanimated";
+
+type TransitionParams = {
+  readonly delayMs?: number;
+  readonly durationMs: number;
+  readonly easing: NonNullable<WithTimingConfig["easing"]>;
+  readonly fromOpacity: number;
+  readonly toOpacity: number;
+  readonly fromTranslateY: number;
+  readonly toTranslateY: number;
+  readonly fromScale: number;
+  readonly toScale: number;
+};
+
+export const createShiftTransition = ({
+  delayMs = 0,
+  durationMs,
+  easing,
+  fromOpacity,
+  toOpacity,
+  fromTranslateY,
+  toTranslateY,
+  fromScale,
+  toScale,
+}: TransitionParams): EntryExitAnimationFunction => {
+  return () => {
+    "worklet";
+
+    // drive opacity and transforms from one timing path
+    const animate = (toValue: number) =>
+      delayMs > 0
+        ? withDelay(
+            delayMs,
+            withTiming(toValue, {
+              duration: durationMs,
+              easing,
+            })
+          )
+        : withTiming(toValue, {
+            duration: durationMs,
+            easing,
+          });
+
+    const initialValues: Record<string, unknown> = {
+      opacity: fromOpacity,
+      transform: [
+        { translateY: fromTranslateY },
+        { scale: fromScale },
+      ],
+    };
+
+    const animations: Record<string, unknown> = {
+      opacity: animate(toOpacity),
+      transform: [
+        { translateY: animate(toTranslateY) },
+        { scale: animate(toScale) },
+      ],
+    };
+
+    return {
+      initialValues: {
+        ...initialValues,
+      },
+      animations: {
+        ...animations,
+      },
+    };
+  };
+};

package/src/motion/preset-map.ts

@@ -0,0 +1,127 @@
+import {
+  Easing,
+  LinearTransition,
+  type EntryExitAnimationFunction,
+  type WithTimingConfig,
+  withDelay,
+  withSpring,
+  withTiming,
+} from "react-native-reanimated";
+import type {
+  MotionRecipe,
+  MorphAnimationPreset,
+  MorphAnimationPresetName,
+} from "../types";
+
+const DEFAULT_CURVE = [0.19, 1, 0.22, 1] as const;
+
+export const MOTION_PRESETS: Record<
+  MorphAnimationPresetName,
+  MorphAnimationPreset
+> = {
+  default: {
+    duration: 0.38,
+    ease: DEFAULT_CURVE,
+  },
+  smooth: {
+    type: "spring",
+    duration: 0.4,
+    bounce: 0,
+  },
+  snappy: {
+    type: "spring",
+    duration: 0.35,
+    bounce: 0.15,
+  },
+  bouncy: {
+    type: "spring",
+    duration: 0.5,
+    bounce: 0.3,
+  },
+} as const;
+
+const toMilliseconds = (seconds: number) => Math.round(seconds * 1000);
+
+const toDampingRatio = (bounce: number) =>
+  Math.max(0.55, Math.min(1, 1 - bounce));
+
+const createOpacityTransition = (
+  fromOpacity: number,
+  toOpacity: number,
+  durationMs: number,
+  easing: NonNullable<WithTimingConfig["easing"]>
+): EntryExitAnimationFunction => {
+  return () => {
+    "worklet";
+
+    return {
+      initialValues: {
+        opacity: fromOpacity,
+      },
+      animations: {
+        opacity: withTiming(toOpacity, {
+          duration: durationMs,
+          easing,
+        }),
+      },
+    };
+  };
+};
+
+export const resolveMotionRecipe = (
+  presetName: MorphAnimationPresetName = "default",
+  durationOverride?: number
+): MotionRecipe => {
+  const preset = MOTION_PRESETS[presetName];
+  const durationMs = durationOverride ?? toMilliseconds(preset.duration);
+
+  if ("type" in preset && preset.type === "spring") {
+    const dampingRatio = toDampingRatio(preset.bounce);
+    const easing = Easing.bezier(...DEFAULT_CURVE);
+
+    return {
+      durationMs,
+      easing,
+      // keep layout on timing so width and reflow stay predictable
+      layoutTransition: LinearTransition.duration(durationMs).easing(
+        easing.factory()
+      ),
+      enterTransition: createOpacityTransition(0, 1, durationMs, easing),
+      exitTransition: createOpacityTransition(1, 0, durationMs, easing),
+      driveNumber: (toValue, delayMs = 0) => {
+        const animation = withSpring(toValue, {
+          duration: durationMs,
+          dampingRatio,
+          overshootClamping: preset.bounce === 0,
+        });
+
+        return delayMs > 0 ? withDelay(delayMs, animation) : animation;
+      },
+    };
+  }
+
+  const timingPreset = preset as Extract<
+    MorphAnimationPreset,
+    { ease: readonly [number, number, number, number] }
+  >;
+  const [x1, y1, x2, y2] = timingPreset.ease;
+  const easing = Easing.bezier(x1, y1, x2, y2);
+
+  return {
+    durationMs,
+    easing,
+    layoutTransition: LinearTransition.duration(durationMs).easing(
+      easing.factory()
+    ),
+    enterTransition: createOpacityTransition(0, 1, durationMs, easing),
+    exitTransition: createOpacityTransition(1, 0, durationMs, easing),
+    driveNumber: (toValue, delayMs = 0) => {
+      const animation = withTiming(toValue, {
+        duration: durationMs,
+        easing,
+      });
+
+      return delayMs > 0 ? withDelay(delayMs, animation) : animation;
+    },
+  };
+};

package/src/types.ts

@@ -0,0 +1,60 @@
+import type { StyleProp, TextStyle, ViewStyle } from "react-native";
+import type {
+  ComplexAnimationBuilder,
+  EntryExitAnimationFunction,
+  WithTimingConfig,
+} from "react-native-reanimated";
+
+export type MorphAnimationPresetName =
+  | "default"
+  | "smooth"
+  | "snappy"
+  | "bouncy";
+
+export type MorphContentVariant = "text" | "number";
+
+type CubicBezierTuple = readonly [number, number, number, number];
+
+export type MorphAnimationPreset =
+  | {
+      readonly duration: number;
+      readonly ease: CubicBezierTuple;
+    }
+  | {
+      readonly type: "spring";
+      readonly duration: number;
+      readonly bounce: number;
+    };
+
+export type GlyphToken = {
+  readonly id: string;
+  readonly value: string;
+};
+
+export type NumericFlowDirection = -1 | 0 | 1;
+
+export type MotionRecipe = {
+  readonly durationMs: number;
+  readonly easing: NonNullable<WithTimingConfig["easing"]>;
+  readonly layoutTransition: ComplexAnimationBuilder;
+  readonly enterTransition: EntryExitAnimationFunction;
+  readonly exitTransition: EntryExitAnimationFunction;
+  readonly driveNumber: (toValue: number, delayMs?: number) => number;
+};
+
+export type MorphingTextProps = {
+  readonly text: string | number;
+  readonly variant?: MorphContentVariant;
+  readonly fontSize?: number;
+  readonly color?: string;
+  readonly style?: StyleProp<TextStyle>;
+  readonly containerStyle?: StyleProp<ViewStyle>;
+  readonly fontStyle?: StyleProp<TextStyle>;
+  readonly animationDuration?: number;
+  readonly animationPreset?: MorphAnimationPresetName;
+  readonly stagger?: number;
+  readonly autoSize?: boolean;
+  readonly clipToBounds?: boolean;
+};
+
+export type LaminarProps = MorphingTextProps;

package/src/view/glyph-run.tsx

@@ -0,0 +1,47 @@
+import React from "react";
+import { type StyleProp, type TextStyle, View } from "react-native";
+import Animated from "react-native-reanimated";
+import type {
+  ComplexAnimationBuilder,
+  EntryExitAnimationFunction,
+} from "react-native-reanimated";
+import type { GlyphToken } from "../types";
+
+const rowStyle = {
+  flexDirection: "row",
+  alignItems: "center",
+  alignSelf: "flex-start",
+} as const;
+
+export const GlyphRun = React.memo(
+  ({
+    glyphs,
+    layoutTransition,
+    enterTransition,
+    exitTransition,
+    textStyle,
+  }: Readonly<{
+    glyphs: readonly GlyphToken[];
+    layoutTransition: ComplexAnimationBuilder;
+    enterTransition?: EntryExitAnimationFunction;
+    exitTransition?: EntryExitAnimationFunction;
+    textStyle?: StyleProp<TextStyle>;
+  }>) => (
+      <View style={rowStyle}>
+        {/* 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}
+          >
+            {glyph.value}
+          </Animated.Text>
+        ))}
+      </View>
+    )
+);
+
+GlyphRun.displayName = "GlyphRun";

package/src/view/morph-viewport.tsx

@@ -0,0 +1,83 @@
+import React, { useMemo } from "react";
+import type { StyleProp, ViewStyle } from "react-native";
+import { View } from "react-native";
+import Animated from "react-native-reanimated";
+
+const shellStyle = {
+  position: "relative",
+  alignSelf: "flex-start",
+} as const;
+
+const viewportStyle = {
+  alignSelf: "flex-start",
+} as const;
+
+const measuredContentStyle: ViewStyle = {
+  position: "absolute",
+  left: 0,
+  top: 0,
+  opacity: 0,
+  alignSelf: "flex-start",
+  flexShrink: 0,
+};
+
+const clippedViewportStyle: ViewStyle = {
+  overflow: "hidden",
+};
+
+const unclippedViewportStyle: ViewStyle = {
+  overflow: "visible",
+};
+
+type MorphViewportProps = {
+  readonly autoSize: boolean;
+  readonly clipToBounds: boolean;
+  readonly containerStyle?: StyleProp<ViewStyle>;
+  readonly animatedWidthStyle?: React.ComponentProps<typeof Animated.View>["style"];
+  readonly measurement?: React.ReactNode;
+  readonly children: React.ReactNode;
+};
+
+export const MorphViewport = React.memo(
+  ({
+    autoSize,
+    clipToBounds,
+    containerStyle,
+    animatedWidthStyle,
+    measurement,
+    children,
+  }: MorphViewportProps) => {
+    const resolvedViewportStyle = useMemo(
+      () => [
+        viewportStyle,
+        clipToBounds ? clippedViewportStyle : unclippedViewportStyle,
+      ],
+      [clipToBounds]
+    );
+
+    return (
+      <View style={[shellStyle, containerStyle]}>
+        {autoSize ? (
+          <>
+            <View
+              accessibilityElementsHidden
+              collapsable={false}
+              importantForAccessibility="no-hide-descendants"
+              pointerEvents="none"
+              style={measuredContentStyle}
+            >
+              {measurement}
+            </View>
+            <Animated.View style={[resolvedViewportStyle, animatedWidthStyle]}>
+              {children}
+            </Animated.View>
+          </>
+        ) : (
+          <View style={resolvedViewportStyle}>{children}</View>
+        )}
+      </View>
+    );
+  }
+);
+
+MorphViewport.displayName = "MorphViewport";