@react-native-motion-kit/text-motion 0.0.0-stage → 0.1.1

package/src/renderers/rendererMotion.ts

@@ -0,0 +1,483 @@
+import {
+  ReduceMotion,
+  withDelay,
+  withSpring,
+  withTiming,
+  type SharedValue,
+} from 'react-native-reanimated';
+
+import type {
+  TextMotionAnyEffect,
+  TextMotionAnyEffectDescriptor,
+  TextMotionEffectDescriptorOptions,
+  TextMotionInternalRecipeConfig,
+  TextMotionMotionConfig,
+} from '../types/recipe';
+
+import {
+  flattenTextMotionEffectDescriptors,
+  readTextMotionTimelineDescriptor,
+} from '../recipe/descriptors';
+
+export const TEXT_MOTION_CONTROLLED_ITEM_TIMELINE_SPAN = 1;
+
+export type TextMotionStyleTransformState = {
+  opacity: number;
+  scale: number;
+  translateX: number;
+  translateY: number;
+};
+
+export type TextMotionStyleTransformStatePair = {
+  initial: TextMotionStyleTransformState;
+  pulseScale: number;
+  revealOnStart?: true;
+  target: TextMotionStyleTransformState;
+};
+
+export type TextMotionOverlayStyleTransformStatePair = {
+  frame: TextMotionStyleTransformStatePair;
+  revealContent: TextMotionStyleTransformStatePair;
+};
+
+export type TextMotionItemMotion = {
+  delayMs: number;
+  initial: TextMotionStyleTransformState;
+  target: TextMotionStyleTransformState;
+  motion?: TextMotionMotionConfig;
+  pulseScale: number;
+  reducedMotion: 'final-state' | 'system';
+  revealOnStart?: true;
+};
+
+export type TextMotionControlledProgressPlan = {
+  itemDelaySeconds: number;
+  totalTimelineSpan: number;
+};
+
+type TextMotionControlledProgressInput = TextMotionControlledProgressPlan & {
+  progress: number;
+};
+
+type TextMotionNumberTransform = (value: number) => number;
+type TextMotionStyleStateTransform = (
+  state: TextMotionStyleTransformState,
+) => TextMotionStyleTransformState;
+
+type EffectStyleStateChange = {
+  initial?: TextMotionStyleStateTransform;
+  pulseScale?: TextMotionNumberTransform;
+  revealOnStart?: true;
+  target?: TextMotionStyleStateTransform;
+};
+
+type EffectStyleStateResolver = (effect: TextMotionAnyEffectDescriptor) => EffectStyleStateChange;
+type TextMotionStyleNumberKey = keyof TextMotionStyleTransformState;
+
+const DEFAULT_STYLE_STATE: TextMotionStyleTransformState = {
+  opacity: 1,
+  scale: 1,
+  translateX: 0,
+  translateY: 0,
+};
+
+const REDUCE_MOTION_CONFIG_BY_POLICY = {
+  'final-state': ReduceMotion.Never,
+  system: ReduceMotion.System,
+} as const satisfies Record<TextMotionItemMotion['reducedMotion'], ReduceMotion>;
+
+const preserveStyleState: TextMotionStyleStateTransform = (state) => state;
+const preserveNumber: TextMotionNumberTransform = (value) => value;
+
+const effectStyleStateResolvers: Record<string, EffectStyleStateResolver> = {
+  typewriter() {
+    return { revealOnStart: true };
+  },
+  fade(effect) {
+    return {
+      initial: setStyleNumber('opacity', numberOption(effect.options, 'from', 0)),
+      target: setStyleNumber('opacity', numberOption(effect.options, 'to', 1)),
+    };
+  },
+  lineReveal(effect) {
+    return {
+      initial: composeStyleTransforms(
+        setStyleNumber('opacity', numberOption(effect.options, 'fromOpacity', 0)),
+        mapStyleNumber(
+          'translateY',
+          (translateY) => translateY + numberOption(effect.options, 'y', 16),
+        ),
+      ),
+      target: preserveStyleState,
+    };
+  },
+  pulse(effect) {
+    return {
+      pulseScale: (scale) => scale * numberOption(effect.options, 'scale', 1.04),
+    };
+  },
+  rise(effect) {
+    return {
+      initial: mapStyleNumber(
+        'translateY',
+        (translateY) => translateY + numberOption(effect.options, 'y', 12),
+      ),
+      target: preserveStyleState,
+    };
+  },
+  scale(effect) {
+    return {
+      initial: mapStyleNumber(
+        'scale',
+        (scale) => scale * numberOption(effect.options, 'from', 0.96),
+      ),
+      target: mapStyleNumber('scale', (scale) => scale * numberOption(effect.options, 'to', 1)),
+    };
+  },
+  shake(effect) {
+    return {
+      initial: mapStyleNumber(
+        'translateX',
+        (translateX) => translateX + numberOption(effect.options, 'x', 4),
+      ),
+      target: preserveStyleState,
+    };
+  },
+  slide(effect) {
+    return {
+      initial: composeStyleTransforms(
+        mapStyleNumber(
+          'translateX',
+          (translateX) => translateX + numberOption(effect.options, 'x', 0),
+        ),
+        mapStyleNumber(
+          'translateY',
+          (translateY) => translateY + numberOption(effect.options, 'y', 12),
+        ),
+      ),
+      target: preserveStyleState,
+    };
+  },
+};
+
+const overlayFrameEffectStyleStateResolvers: Record<string, EffectStyleStateResolver> = {
+  ...effectStyleStateResolvers,
+  lineReveal(effect) {
+    return {
+      initial: setStyleNumber('opacity', numberOption(effect.options, 'fromOpacity', 0)),
+      target: preserveStyleState,
+    };
+  },
+};
+
+const overlayRevealContentEffectStyleStateResolvers: Record<string, EffectStyleStateResolver> = {
+  fade: preserveEffectStyleState,
+  lineReveal(effect) {
+    return {
+      initial: mapStyleNumber(
+        'translateY',
+        (translateY) => translateY + numberOption(effect.options, 'y', 16),
+      ),
+      target: preserveStyleState,
+    };
+  },
+  pulse: preserveEffectStyleState,
+  rise: preserveEffectStyleState,
+  scale: preserveEffectStyleState,
+  shake: preserveEffectStyleState,
+  slide: preserveEffectStyleState,
+};
+
+function numberOption(
+  options: TextMotionEffectDescriptorOptions | undefined,
+  key: string,
+  fallback: number,
+): number {
+  const value = options?.[key];
+
+  if (value === undefined) {
+    return fallback;
+  }
+
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    return value;
+  }
+
+  throw new Error(
+    `@react-native-motion-kit/text-motion effect option "${key}" must be a finite number.`,
+  );
+}
+
+function validateDelaySeconds(delay: number): number {
+  if (Number.isFinite(delay) && delay >= 0) {
+    return delay;
+  }
+
+  throw new Error(
+    '@react-native-motion-kit/text-motion timeline delay must be a finite number greater than or equal to 0.',
+  );
+}
+
+function createDelayMs(delaySeconds: number): number {
+  const delayMs = Math.round(delaySeconds * 1000);
+
+  if (Number.isSafeInteger(delayMs)) {
+    return delayMs;
+  }
+
+  throw new Error(
+    '@react-native-motion-kit/text-motion timeline delay must convert to a safe integer millisecond value.',
+  );
+}
+
+function createDefaultStyleStatePair(): TextMotionStyleTransformStatePair {
+  return {
+    initial: { ...DEFAULT_STYLE_STATE },
+    pulseScale: 1,
+    target: { ...DEFAULT_STYLE_STATE },
+  };
+}
+
+function mapStyleNumber(
+  key: TextMotionStyleNumberKey,
+  mapValue: (value: number) => number,
+): TextMotionStyleStateTransform {
+  return (state) => {
+    const nextState: TextMotionStyleTransformState = {
+      ...state,
+    };
+
+    nextState[key] = mapValue(state[key]);
+
+    return nextState;
+  };
+}
+
+function setStyleNumber(
+  key: TextMotionStyleNumberKey,
+  value: number,
+): TextMotionStyleStateTransform {
+  return mapStyleNumber(key, () => value);
+}
+
+function composeStyleTransforms(
+  ...transforms: readonly TextMotionStyleStateTransform[]
+): TextMotionStyleStateTransform {
+  return (state) => transforms.reduce((current, transform) => transform(current), state);
+}
+
+function preserveEffectStyleState(): EffectStyleStateChange {
+  return {};
+}
+
+function resolveEffectStyleStateChange(
+  effect: TextMotionAnyEffectDescriptor,
+  unsupportedEffectSubject: string,
+  resolvers: Record<string, EffectStyleStateResolver> = effectStyleStateResolvers,
+): EffectStyleStateChange {
+  const resolver = resolvers[effect.name];
+
+  if (resolver) {
+    return resolver(effect);
+  }
+
+  throw new Error(
+    `${unsupportedEffectSubject} does not implement the "${effect.name}" effect. Use a built-in style-transform effect or a renderer that handles this effect.`,
+  );
+}
+
+function applyResolvedEffectStyleStateChange(
+  styleState: TextMotionStyleTransformStatePair,
+  effectStyleStateChange: EffectStyleStateChange,
+): TextMotionStyleTransformStatePair {
+  const initial = effectStyleStateChange.initial ?? preserveStyleState;
+  const pulseScale = effectStyleStateChange.pulseScale ?? preserveNumber;
+  const target = effectStyleStateChange.target ?? preserveStyleState;
+
+  return {
+    ...styleState,
+    ...(effectStyleStateChange.revealOnStart ? { revealOnStart: true } : {}),
+    initial: initial(styleState.initial),
+    pulseScale: pulseScale(styleState.pulseScale),
+    target: target(styleState.target),
+  };
+}
+
+function applyDelay(animation: number, delayMs: number, reduceMotion: ReduceMotion): number {
+  return delayMs > 0 ? withDelay(delayMs, animation, reduceMotion) : animation;
+}
+
+export function createTextMotionStyleTransformStatePair(
+  effects: readonly TextMotionAnyEffect[],
+  unsupportedEffectSubject = 'style-transform renderer',
+): TextMotionStyleTransformStatePair {
+  return createResolvedTextMotionStyleTransformStatePair(
+    effects,
+    unsupportedEffectSubject,
+    effectStyleStateResolvers,
+  );
+}
+
+function createResolvedTextMotionStyleTransformStatePair(
+  effects: readonly TextMotionAnyEffect[],
+  unsupportedEffectSubject: string,
+  resolvers: Record<string, EffectStyleStateResolver>,
+): TextMotionStyleTransformStatePair {
+  return flattenTextMotionEffectDescriptors(effects).reduce<TextMotionStyleTransformStatePair>(
+    (styleState, effect) =>
+      applyResolvedEffectStyleStateChange(
+        styleState,
+        resolveEffectStyleStateChange(effect, unsupportedEffectSubject, resolvers),
+      ),
+    createDefaultStyleStatePair(),
+  );
+}
+
+export function createOverlayTextStyleTransformStatePair(
+  effects: readonly TextMotionAnyEffect[],
+): TextMotionOverlayStyleTransformStatePair {
+  return {
+    frame: createResolvedTextMotionStyleTransformStatePair(
+      effects,
+      'overlayText()',
+      overlayFrameEffectStyleStateResolvers,
+    ),
+    revealContent: createResolvedTextMotionStyleTransformStatePair(
+      effects,
+      'overlayText()',
+      overlayRevealContentEffectStyleStateResolvers,
+    ),
+  };
+}
+
+export function createTextMotionDelaySecondsByItemIndex(
+  recipe: TextMotionInternalRecipeConfig,
+  count: number,
+): readonly number[] {
+  const timeline = recipe.timeline ? readTextMotionTimelineDescriptor(recipe.timeline) : undefined;
+
+  return Array.from({ length: count }, (_, index) =>
+    validateDelaySeconds(timeline?.delayFor(index, count) ?? 0),
+  );
+}
+
+export function createTextMotionItemMotion(
+  recipe: TextMotionInternalRecipeConfig,
+  styleState: TextMotionStyleTransformStatePair,
+  delaySeconds: number,
+): TextMotionItemMotion {
+  return {
+    ...styleState,
+    delayMs: createDelayMs(delaySeconds),
+    motion: recipe.motion,
+    reducedMotion: recipe.accessibility?.reducedMotion ?? 'system',
+  };
+}
+
+export function createTextMotionControlledProgressPlan(
+  itemIndex: number,
+  delaySecondsByItemIndex: readonly number[],
+  totalTimelineSpan: number,
+): TextMotionControlledProgressPlan {
+  return {
+    itemDelaySeconds: delaySecondsByItemIndex[itemIndex] ?? 0,
+    totalTimelineSpan,
+  };
+}
+
+export function clampTextMotionProgress(progress: number): number {
+  'worklet';
+
+  if (!Number.isFinite(progress)) {
+    return 0;
+  }
+
+  return Math.min(1, Math.max(0, progress));
+}
+
+export function createTextMotionControlledTimelineSpan(
+  delaySecondsByItemIndex: readonly number[],
+): number {
+  const maxDelaySeconds = delaySecondsByItemIndex.reduce(
+    (maxDelay, delaySeconds) => Math.max(maxDelay, delaySeconds),
+    0,
+  );
+
+  return maxDelaySeconds + TEXT_MOTION_CONTROLLED_ITEM_TIMELINE_SPAN;
+}
+
+export function mapTextMotionControlledProgressToItemProgress({
+  progress,
+  itemDelaySeconds,
+  totalTimelineSpan,
+}: TextMotionControlledProgressInput): number {
+  'worklet';
+
+  const virtualTime = clampTextMotionProgress(progress) * totalTimelineSpan;
+  const itemProgress = (virtualTime - itemDelaySeconds) / TEXT_MOTION_CONTROLLED_ITEM_TIMELINE_SPAN;
+
+  return clampTextMotionProgress(itemProgress);
+}
+
+export function resolveTextMotionReduceMotionConfig(
+  reducedMotion: TextMotionItemMotion['reducedMotion'],
+) {
+  return REDUCE_MOTION_CONFIG_BY_POLICY[reducedMotion];
+}
+
+export function shouldRenderTextMotionFinalState(
+  reducedMotionEnabled: boolean,
+  reducedMotion: TextMotionItemMotion['reducedMotion'],
+): boolean {
+  return reducedMotionEnabled && reducedMotion !== 'system';
+}
+
+export function createTextMotionProgressAnimation({
+  delayMs,
+  motion,
+  reducedMotion,
+}: Pick<TextMotionItemMotion, 'delayMs' | 'motion' | 'reducedMotion'>): number {
+  const reduceMotion = resolveTextMotionReduceMotionConfig(reducedMotion);
+
+  if (motion?.kind === 'spring') {
+    const animation = withSpring(1, {
+      ...motion.options,
+      reduceMotion,
+    });
+
+    return applyDelay(animation, delayMs, reduceMotion);
+  }
+
+  const timingOptions = motion?.kind === 'timing' ? motion.options : undefined;
+  const animation = withTiming(1, {
+    duration: 300,
+    ...timingOptions,
+    reduceMotion,
+  });
+
+  return applyDelay(animation, delayMs, reduceMotion);
+}
+
+export function readTextMotionProgressForAnimatedStyle({
+  controlledProgressPlan,
+  progress,
+  renderFinalState,
+}: {
+  controlledProgressPlan?: TextMotionControlledProgressPlan;
+  progress: SharedValue<number>;
+  renderFinalState: boolean;
+}): number {
+  'worklet';
+
+  const rawProgress = renderFinalState ? 1 : progress.value;
+
+  if (!controlledProgressPlan) {
+    return Number.isFinite(rawProgress) ? rawProgress : 0;
+  }
+
+  return mapTextMotionControlledProgressToItemProgress({
+    progress: rawProgress,
+    itemDelaySeconds: controlledProgressPlan.itemDelaySeconds,
+    totalTimelineSpan: controlledProgressPlan.totalTimelineSpan,
+  });
+}

package/src/split/createToken.ts

@@ -0,0 +1,26 @@
+import type { TextMotionSourceRange, TextMotionToken, TextMotionTokenUnit } from '../types';
+
+type CreateTokenInput<Unit extends TextMotionTokenUnit> = {
+  index: number;
+  metadata?: Record<string, unknown>;
+  sourceRange: TextMotionSourceRange;
+  text: string;
+  unit: Unit;
+};
+
+export function createTextMotionToken<Unit extends TextMotionTokenUnit>({
+  index,
+  metadata,
+  sourceRange,
+  text,
+  unit,
+}: CreateTokenInput<Unit>): TextMotionToken<Unit> {
+  return {
+    id: `${unit}-${index}-${sourceRange.start}-${sourceRange.end}`,
+    index,
+    metadata,
+    sourceRange,
+    text,
+    unit,
+  };
+}

package/src/split/custom.ts

@@ -0,0 +1,92 @@
+import type {
+  TextMotionSourceRange,
+  TextMotionSplitContext,
+  TextMotionSplitter,
+  TextMotionToken,
+} from '../types';
+
+import { createTextMotionSplitterHandle } from '../recipe/descriptors';
+import { createTextMotionToken } from './createToken';
+
+/** Token object returned by a custom splitter when source metadata matters. */
+export type TextMotionCustomSplitToken = {
+  /** Optional metadata copied into the generated token. */
+  metadata?: Record<string, unknown>;
+  /** Explicit source range in the original input. */
+  sourceRange?: TextMotionSourceRange;
+  /** Text content for the token. */
+  text: string;
+};
+
+/** Result item returned by a custom splitter. */
+export type TextMotionCustomSplitResult = string | TextMotionCustomSplitToken;
+
+/** Custom split function used by {@link custom}. */
+export type TextMotionCustomSplit = (
+  input: string,
+  context?: TextMotionSplitContext,
+) => readonly TextMotionCustomSplitResult[];
+
+type CustomSplitAccumulator = {
+  cursor: number;
+  tokens: TextMotionToken<'custom'>[];
+};
+
+function findSourceRange(input: string, text: string, cursor: number) {
+  const start = input.indexOf(text, cursor);
+  const safeStart = start >= 0 ? start : cursor;
+
+  return {
+    end: safeStart + text.length,
+    start: safeStart,
+  };
+}
+
+function normalizeCustomSplitResult(
+  input: string,
+  result: TextMotionCustomSplitResult,
+  index: number,
+  cursor: number,
+) {
+  const text = typeof result === 'string' ? result : result.text;
+  const sourceRange =
+    typeof result === 'string' || !result.sourceRange
+      ? findSourceRange(input, text, cursor)
+      : result.sourceRange;
+
+  return {
+    cursor: sourceRange.end,
+    token: createTextMotionToken({
+      index,
+      metadata: typeof result === 'string' ? undefined : result.metadata,
+      sourceRange,
+      text,
+      unit: 'custom',
+    }),
+  };
+}
+
+/** Build a splitter from an app-defined split function. */
+export function custom(split: TextMotionCustomSplit): TextMotionSplitter<'custom'> {
+  return createTextMotionSplitterHandle({
+    kind: 'custom',
+    split(input, context): readonly TextMotionToken<'custom'>[] {
+      const initialAccumulator: CustomSplitAccumulator = {
+        cursor: 0,
+        tokens: [],
+      };
+
+      return split(input, context).reduce((accumulator, result, index) => {
+        const normalized = normalizeCustomSplitResult(input, result, index, accumulator.cursor);
+
+        // Keep the token accumulator mutable so custom split normalization stays linear.
+        accumulator.tokens.push(normalized.token);
+
+        return {
+          cursor: normalized.cursor,
+          tokens: accumulator.tokens,
+        };
+      }, initialAccumulator).tokens;
+    },
+  });
+}

package/src/split/graphemes.ts

@@ -0,0 +1,27 @@
+import type { TextMotionSplitter } from '../types';
+
+import { createTextMotionSplitterHandle } from '../recipe/descriptors';
+import { createTextMotionToken } from './createToken';
+import { createSegmenter } from './segmenter';
+
+/** Split text into grapheme-aware tokens for character-level motion. */
+export function graphemes(): TextMotionSplitter<'grapheme'> {
+  return createTextMotionSplitterHandle({
+    kind: 'grapheme',
+    split(input, context) {
+      const segmenter = createSegmenter('grapheme', context?.locale);
+
+      return Array.from(segmenter.segment(input), (segment, index) =>
+        createTextMotionToken({
+          index,
+          sourceRange: {
+            start: segment.index,
+            end: segment.index + segment.segment.length,
+          },
+          text: segment.segment,
+          unit: 'grapheme',
+        }),
+      );
+    },
+  });
+}

package/src/split/index.ts

@@ -0,0 +1,9 @@
+export {
+  custom,
+  type TextMotionCustomSplit,
+  type TextMotionCustomSplitResult,
+  type TextMotionCustomSplitToken,
+} from './custom';
+export { graphemes } from './graphemes';
+export { lines } from './lines';
+export { words } from './words';

package/src/split/lines.ts

@@ -0,0 +1,35 @@
+import type { TextMotionSplitter, TextMotionToken } from '../types';
+
+import { createTextMotionSplitterHandle } from '../recipe/descriptors';
+import { createTextMotionToken } from './createToken';
+
+const LINE_SEGMENT_PATTERN = /[^\n]*\n|[^\n]+/g;
+
+function lineParts(input: string) {
+  if (input.length === 0) {
+    return [{ start: 0, text: '' }];
+  }
+
+  return Array.from(input.matchAll(LINE_SEGMENT_PATTERN), (match) => ({
+    start: match.index ?? 0,
+    text: match[0] ?? '',
+  }));
+}
+
+/** Split on newline boundaries. This is experimental and does not measure rendered line wraps. */
+export function lines(): TextMotionSplitter<'line'> {
+  return createTextMotionSplitterHandle({
+    kind: 'line',
+    split(input): readonly TextMotionToken<'line'>[] {
+      return lineParts(input).map(({ start, text }, index) =>
+        createTextMotionToken({
+          index,
+          metadata: { experimental: true, mapping: 'newline-only' },
+          sourceRange: { start, end: start + text.length },
+          text,
+          unit: 'line',
+        }),
+      );
+    },
+  });
+}