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

package/src/effects/compose.ts

@@ -0,0 +1,98 @@
+import type {
+  TextMotionAnyEffect,
+  TextMotionAnyEffectDescriptor,
+  TextMotionEffect,
+  TextMotionEffectDescriptorOptions,
+} from '../types/recipe';
+import type { TextMotionRendererCapability } from '../types/renderer';
+
+import {
+  attachTextMotionEffectDescriptor,
+  readTextMotionEffectDescriptor,
+} from '../recipe/descriptors';
+
+const DEFAULT_EFFECT_OPTIONS: TextMotionEffectDescriptorOptions = {};
+const NATIVE_TEXT_CAPABILITIES: readonly ['native-text'] = ['native-text'];
+
+function uniqueCapabilities<Capabilities extends TextMotionRendererCapability>(
+  capabilities: readonly Capabilities[],
+): readonly Capabilities[] {
+  return Array.from(new Set(capabilities));
+}
+
+/** Compose multiple effects into one ordered effect. */
+export function composeTextMotionEffects<Capabilities extends TextMotionRendererCapability>(
+  effects: readonly TextMotionEffect<Capabilities>[],
+): TextMotionEffect<Capabilities> {
+  const descriptors = effects.map(readTextMotionEffectDescriptor);
+  const requiredCapabilities = uniqueCapabilities(
+    descriptors.flatMap((descriptor) => descriptor.requiredCapabilities),
+  );
+
+  const composed = {
+    and<NextCapabilities extends TextMotionRendererCapability, NextName extends string>(
+      effect: TextMotionEffect<NextCapabilities, NextName>,
+    ) {
+      return composeTextMotionEffects<Capabilities | NextCapabilities>([...effects, effect]);
+    },
+  } as TextMotionEffect<Capabilities>;
+
+  return attachTextMotionEffectDescriptor<Capabilities, TextMotionEffectDescriptorOptions, string>(
+    composed,
+    {
+      kind: 'effect',
+      name: descriptors.map((descriptor) => descriptor.name).join('+'),
+      requiredCapabilities,
+      effects,
+    },
+  );
+}
+
+/** Create a custom native-text effect without descriptor options. */
+export function createTextMotionEffect<Name extends string>(
+  name: Name,
+): TextMotionEffect<'native-text', Name>;
+
+/** Create a custom native-text effect with typed descriptor options. */
+export function createTextMotionEffect<
+  Name extends string,
+  Options extends TextMotionEffectDescriptorOptions,
+>(name: Name, options: Options): TextMotionEffect<'native-text', Name>;
+
+/** Create a custom effect with typed descriptor options and renderer capabilities. */
+export function createTextMotionEffect<
+  Name extends string,
+  Options extends TextMotionEffectDescriptorOptions,
+  Capabilities extends TextMotionRendererCapability,
+>(
+  name: Name,
+  options: Options,
+  requiredCapabilities: readonly Capabilities[],
+): TextMotionEffect<Capabilities, Name>;
+
+/** Create a custom text-motion effect for built-in or custom renderers. */
+export function createTextMotionEffect(
+  name: string,
+  options: TextMotionEffectDescriptorOptions = DEFAULT_EFFECT_OPTIONS,
+  requiredCapabilities: readonly TextMotionRendererCapability[] = NATIVE_TEXT_CAPABILITIES,
+): TextMotionAnyEffect {
+  const effect = {
+    and<NextCapabilities extends TextMotionRendererCapability, NextName extends string>(
+      nextEffect: TextMotionEffect<NextCapabilities, NextName>,
+    ) {
+      return composeTextMotionEffects<TextMotionRendererCapability | NextCapabilities>([
+        effect,
+        nextEffect,
+      ]);
+    },
+  } as TextMotionAnyEffect;
+
+  const descriptor: TextMotionAnyEffectDescriptor = {
+    kind: 'effect',
+    name,
+    options,
+    requiredCapabilities,
+  };
+
+  return attachTextMotionEffectDescriptor(effect, descriptor);
+}

package/src/effects/fade.ts

@@ -0,0 +1,22 @@
+import { createTextMotionEffect } from './compose';
+import { validateFiniteEffectNumber } from './validation';
+
+/** Options for {@link fade}. */
+export type FadeOptions = {
+  /** Starting opacity. Defaults to `0`. */
+  from?: number;
+  /** Ending opacity. Defaults to `1`. */
+  to?: number;
+};
+
+/** Fade each token between opacity values. */
+export function fade(options: FadeOptions = {}) {
+  return createTextMotionEffect(
+    'fade',
+    {
+      from: validateFiniteEffectNumber(options.from ?? 0, 'fade from'),
+      to: validateFiniteEffectNumber(options.to ?? 1, 'fade to'),
+    },
+    ['style-transform'],
+  );
+}

package/src/effects/index.ts

@@ -0,0 +1,9 @@
+export { composeTextMotionEffects, createTextMotionEffect } from './compose';
+export { fade, type FadeOptions } from './fade';
+export { lineReveal, type LineRevealOptions } from './lineReveal';
+export { pulse, type PulseOptions } from './pulse';
+export { rise, type RiseOptions } from './rise';
+export { scale, type ScaleOptions } from './scale';
+export { shake, type ShakeOptions } from './shake';
+export { slide, type SlideOptions } from './slide';
+export { typewriter } from './typewriter';

package/src/effects/lineReveal.ts

@@ -0,0 +1,28 @@
+import type { TextMotionLineMaskCapability } from '../types/renderer';
+
+import { createTextMotionRendererCapability } from '../types/renderer';
+import { createTextMotionEffect } from './compose';
+import { validateFiniteEffectNumber } from './validation';
+
+const LINE_MASK_CAPABILITY: TextMotionLineMaskCapability =
+  createTextMotionRendererCapability('line-mask');
+
+/** Options for {@link lineReveal}. */
+export type LineRevealOptions = {
+  /** Initial downward offset in points. Defaults to `16`. */
+  y?: number;
+  /** Initial opacity before each rendered line reveals. Defaults to `0`. */
+  fromOpacity?: number;
+};
+
+/** Reveal each React Native rendered line through an `overlayText()` line mask. */
+export function lineReveal(options: LineRevealOptions = {}) {
+  return createTextMotionEffect(
+    'lineReveal',
+    {
+      fromOpacity: validateFiniteEffectNumber(options.fromOpacity ?? 0, 'lineReveal fromOpacity'),
+      y: validateFiniteEffectNumber(options.y ?? 16, 'lineReveal y'),
+    },
+    [LINE_MASK_CAPABILITY, 'style-transform'],
+  );
+}

package/src/effects/pulse.ts

@@ -0,0 +1,19 @@
+import { createTextMotionEffect } from './compose';
+import { validateFiniteEffectNumber } from './validation';
+
+/** Options for {@link pulse}. */
+export type PulseOptions = {
+  /** Peak pulse scale reached around the middle of the motion. Defaults to `1.04`. */
+  scale?: number;
+};
+
+/** Briefly emphasize each token by scaling it up and returning to its final scale. */
+export function pulse(options: PulseOptions = {}) {
+  return createTextMotionEffect(
+    'pulse',
+    {
+      scale: validateFiniteEffectNumber(options.scale ?? 1.04, 'pulse scale'),
+    },
+    ['style-transform'],
+  );
+}

package/src/effects/rise.ts

@@ -0,0 +1,19 @@
+import { createTextMotionEffect } from './compose';
+import { validateFiniteEffectNumber } from './validation';
+
+/** Options for {@link rise}. */
+export type RiseOptions = {
+  /** Initial downward offset in pixels. Defaults to `12`. */
+  y?: number;
+};
+
+/** Move each token upward from a vertical offset. */
+export function rise(options: RiseOptions = {}) {
+  return createTextMotionEffect(
+    'rise',
+    {
+      y: validateFiniteEffectNumber(options.y ?? 12, 'rise y'),
+    },
+    ['style-transform'],
+  );
+}

package/src/effects/scale.ts

@@ -0,0 +1,22 @@
+import { createTextMotionEffect } from './compose';
+import { validateFiniteEffectNumber } from './validation';
+
+/** Options for {@link scale}. */
+export type ScaleOptions = {
+  /** Starting scale. Defaults to `0.96`. */
+  from?: number;
+  /** Ending scale. Defaults to `1`. */
+  to?: number;
+};
+
+/** Scale each token between two scale values. */
+export function scale(options: ScaleOptions = {}) {
+  return createTextMotionEffect(
+    'scale',
+    {
+      from: validateFiniteEffectNumber(options.from ?? 0.96, 'scale from'),
+      to: validateFiniteEffectNumber(options.to ?? 1, 'scale to'),
+    },
+    ['style-transform'],
+  );
+}

package/src/effects/shake.ts

@@ -0,0 +1,19 @@
+import { createTextMotionEffect } from './compose';
+import { validateFiniteEffectNumber } from './validation';
+
+/** Options for {@link shake}. */
+export type ShakeOptions = {
+  /** Initial horizontal offset in pixels. Defaults to `4`. */
+  x?: number;
+};
+
+/** Offset each token horizontally for a shake-like entrance. */
+export function shake(options: ShakeOptions = {}) {
+  return createTextMotionEffect(
+    'shake',
+    {
+      x: validateFiniteEffectNumber(options.x ?? 4, 'shake x'),
+    },
+    ['style-transform'],
+  );
+}

package/src/effects/slide.ts

@@ -0,0 +1,22 @@
+import { createTextMotionEffect } from './compose';
+import { validateFiniteEffectNumber } from './validation';
+
+/** Options for {@link slide}. */
+export type SlideOptions = {
+  /** Initial horizontal offset in pixels. Defaults to `0`. */
+  x?: number;
+  /** Initial vertical offset in pixels. Defaults to `12`. */
+  y?: number;
+};
+
+/** Move each token from an x/y offset into place. */
+export function slide(options: SlideOptions = {}) {
+  return createTextMotionEffect(
+    'slide',
+    {
+      x: validateFiniteEffectNumber(options.x ?? 0, 'slide x'),
+      y: validateFiniteEffectNumber(options.y ?? 12, 'slide y'),
+    },
+    ['style-transform'],
+  );
+}

package/src/effects/typewriter.ts

@@ -0,0 +1,16 @@
+import { createTextMotionEffect } from './compose';
+
+/**
+ * Reveal each native-text token when its local progress becomes positive.
+ *
+ * Keeps the final token layout in place. Combine with `graphemes()`, `stagger(seconds)`,
+ * and `.motion({ kind: 'timing', options: { duration: 0 } })` for instant character reveals.
+ * The splitter and timeline determine the reveal units and order; whitespace does not
+ * consume a motion index. Other effects retain their own opacity and transforms.
+ *
+ * External `progress` follows the recipe timeline, not the fraction of visible characters.
+ * Decreasing progress can hide tokens again. Requires `nativeText()`.
+ */
+export function typewriter() {
+  return createTextMotionEffect('typewriter');
+}

package/src/effects/validation.ts

@@ -0,0 +1,9 @@
+const ERROR_PREFIX = '@react-native-motion-kit/text-motion';
+
+export function validateFiniteEffectNumber(value: number, label: string): number {
+  if (Number.isFinite(value)) {
+    return value;
+  }
+
+  throw new Error(`${ERROR_PREFIX} ${label} must be a finite number.`);
+}

package/src/index.tsx

@@ -0,0 +1,46 @@
+export { parentLabelPolicy } from './accessibility';
+export { useTextMotionControls } from './controls';
+export { fade, lineReveal, pulse, rise, scale, shake, slide, typewriter } from './effects';
+export { defineTextMotion } from './recipe';
+export { nativeText, overlayText } from './renderers';
+export { custom, graphemes, lines, words } from './split';
+export { parallel, sequence, stagger, wave } from './timeline';
+export type { ParentLabelPolicyOptions } from './accessibility';
+export type { TextMotionControls } from './controls';
+export type {
+  FadeOptions,
+  LineRevealOptions,
+  PulseOptions,
+  RiseOptions,
+  ScaleOptions,
+  ShakeOptions,
+  SlideOptions,
+} from './effects';
+export type { NativeTextRendererOptions, OverlayTextRendererOptions } from './renderers';
+export type {
+  TextMotionCustomSplit,
+  TextMotionCustomSplitResult,
+  TextMotionCustomSplitToken,
+} from './split';
+export type {
+  TextMotionStaggerFrom,
+  TextMotionStaggerOptions,
+  TextMotionWaveOptions,
+} from './timeline';
+export type {
+  TextMotionAccessibilityPolicy,
+  TextMotionComponent,
+  TextMotionComponentAccessibilityProps,
+  TextMotionComponentProps,
+  TextMotionComponentTextProps,
+  TextMotionEffect,
+  TextMotionMotionConfig,
+  TextMotionSpringOptions,
+  TextMotionTimingOptions,
+  TextMotionRenderer,
+  TextMotionRendererCapability,
+  TextMotionRendererProps,
+  TextMotionSplitter,
+  TextMotionTimeline,
+  TextMotionToken,
+} from './types';

package/src/presets/index.ts

@@ -0,0 +1,42 @@
+import type { TextMotionSplitRenderableRecipeBuilder } from '../recipe/recipe';
+
+import { fade, pulse, rise, scale } from '../effects';
+import { defineTextMotion } from '../recipe';
+import { nativeText } from '../renderers';
+import { words } from '../split';
+import { stagger, wave } from '../timeline';
+
+type NativeTextPresetBuilder = TextMotionSplitRenderableRecipeBuilder<
+  'native-text' | 'style-transform'
+>;
+
+/** Editorial title reveal with centered stagger, rise, fade, and subtle scale. */
+export function editorialRise(): NativeTextPresetBuilder {
+  return defineTextMotion()
+    .split(words())
+    .layout(nativeText())
+    .timeline(stagger(0.032, { from: 'center' }))
+    .effect(
+      rise({ y: 14 })
+        .and(fade())
+        .and(scale({ from: 0.98 })),
+    );
+}
+
+/** Soft wave reveal for friendly product copy. */
+export function softWave(): NativeTextPresetBuilder {
+  return defineTextMotion()
+    .split(words())
+    .layout(nativeText())
+    .timeline(wave({ amplitude: 0.06, wavelength: 5 }))
+    .effect(fade().and(rise({ y: 8 })));
+}
+
+/** Gentle emphasis preset for small labels and inline highlight copy. */
+export function gentleEmphasis(): NativeTextPresetBuilder {
+  return defineTextMotion()
+    .split(words())
+    .layout(nativeText())
+    .timeline(stagger(0.024))
+    .effect(pulse({ scale: 1.06 }).and(fade()));
+}

package/src/recipe/component.tsx

@@ -0,0 +1,88 @@
+import type {
+  TextMotionComponent,
+  TextMotionComponentProps,
+  TextMotionInternalRecipeConfig,
+  TextMotionRendererCapability,
+} from '../types';
+import type { TextMotionToken } from '../types/token';
+
+import {
+  flattenTextMotionEffectDescriptors,
+  readTextMotionRendererDescriptor,
+  readTextMotionSplitterDescriptor,
+} from './descriptors';
+
+function validateTextMotionRendererCapabilities(
+  recipe: TextMotionInternalRecipeConfig<TextMotionRendererCapability>,
+  renderer: ReturnType<typeof readTextMotionRendererDescriptor>,
+): void {
+  flattenTextMotionEffectDescriptors(recipe.effects).forEach((effect) => {
+    effect.requiredCapabilities.forEach((capability) => {
+      if (renderer.capabilities.includes(capability)) {
+        return;
+      }
+
+      throw new Error(
+        `@react-native-motion-kit/text-motion effect "${effect.name}" requires capability "${capability}", but renderer "${renderer.kind}" does not provide it.`,
+      );
+    });
+  });
+}
+
+function createDefaultToken(text: string): TextMotionToken<'custom'> {
+  return {
+    id: 'token-0',
+    index: 0,
+    metadata: { reason: 'default-unsplit-token' },
+    sourceRange: { start: 0, end: text.length },
+    text,
+    unit: 'custom',
+  };
+}
+
+export function createTextMotionComponent(
+  recipe: TextMotionInternalRecipeConfig<TextMotionRendererCapability>,
+): TextMotionComponent {
+  function TextMotionComponent({ children, ...textProps }: TextMotionComponentProps) {
+    if (typeof children !== 'string') {
+      throw new Error(
+        '@react-native-motion-kit/text-motion expects a string child. Pass plain text or split non-string content before rendering.',
+      );
+    }
+
+    const splitter = recipe.splitter
+      ? readTextMotionSplitterDescriptor(recipe.splitter)
+      : undefined;
+    const renderer = recipe.renderer
+      ? readTextMotionRendererDescriptor(recipe.renderer)
+      : undefined;
+    const rendererMotionUnit = renderer?.motionUnit ?? 'source-token';
+
+    if (recipe.splitter && rendererMotionUnit === 'rendered-line') {
+      throw new Error(
+        '@react-native-motion-kit/text-motion rendered-line renderers cannot be combined with .split(...). Remove the splitter or choose a source-token renderer such as nativeText().',
+      );
+    }
+
+    const tokens = splitter ? splitter.split(children) : [createDefaultToken(children)];
+    const Renderer = renderer?.Component;
+
+    if (!Renderer) {
+      throw new Error(
+        '@react-native-motion-kit/text-motion requires a renderer. Add .layout(nativeText()) or another renderer before .component().',
+      );
+    }
+
+    validateTextMotionRendererCapabilities(recipe, renderer);
+
+    return (
+      <Renderer recipe={recipe} textProps={textProps} tokens={tokens}>
+        {children}
+      </Renderer>
+    );
+  }
+
+  TextMotionComponent.displayName = 'TextMotionComponent';
+
+  return TextMotionComponent;
+}

package/src/recipe/defineTextMotion.ts

@@ -0,0 +1,6 @@
+import { createTextMotionRecipeBuilder, type TextMotionRecipeBuilder } from './recipe';
+
+/** Start a composable text motion recipe. */
+export function defineTextMotion(): TextMotionRecipeBuilder {
+  return createTextMotionRecipeBuilder();
+}

package/src/recipe/descriptors.ts

@@ -0,0 +1,158 @@
+import type {
+  TextMotionAnyEffect,
+  TextMotionAnyEffectDescriptor,
+  TextMotionAnyTimeline,
+  TextMotionAnyTimelineDescriptor,
+  TextMotionEffect,
+  TextMotionEffectDescriptor,
+  TextMotionEffectDescriptorOptions,
+  TextMotionTimeline,
+  TextMotionTimelineDescriptor,
+  TextMotionTimelineDescriptorOptions,
+} from '../types/recipe';
+import type {
+  TextMotionRenderer,
+  TextMotionRendererCapability,
+  TextMotionRendererDescriptor,
+  TextMotionRenderedLineRenderer,
+  TextMotionSourceTokenRenderer,
+} from '../types/renderer';
+import type {
+  TextMotionSplitter,
+  TextMotionSplitterDescriptor,
+  TextMotionTokenUnit,
+} from '../types/token';
+
+const effectDescriptors = new WeakMap<TextMotionAnyEffect, TextMotionAnyEffectDescriptor>();
+const timelineDescriptors = new WeakMap<TextMotionAnyTimeline, TextMotionAnyTimelineDescriptor>();
+const splitterDescriptors = new WeakMap<TextMotionSplitter, TextMotionSplitterDescriptor>();
+const rendererDescriptors = new WeakMap<
+  TextMotionRenderer<TextMotionRendererCapability, unknown>,
+  TextMotionRendererDescriptor<TextMotionRendererCapability, unknown>
+>();
+
+type TextMotionRendererHandle<
+  Capabilities extends TextMotionRendererCapability,
+  Recipe,
+  MotionUnit extends 'source-token' | 'rendered-line',
+> = MotionUnit extends 'rendered-line'
+  ? TextMotionRenderedLineRenderer<Capabilities, Recipe>
+  : TextMotionSourceTokenRenderer<Capabilities, Recipe>;
+
+export function attachTextMotionEffectDescriptor<
+  RequiredCapabilities extends TextMotionRendererCapability,
+  Options extends TextMotionEffectDescriptorOptions,
+  Name extends string,
+>(
+  effect: TextMotionEffect<RequiredCapabilities, Name>,
+  descriptor: TextMotionEffectDescriptor<RequiredCapabilities, Options, Name>,
+): TextMotionEffect<RequiredCapabilities, Name> {
+  effectDescriptors.set(effect, descriptor);
+
+  return effect;
+}
+
+export function readTextMotionEffectDescriptor<
+  RequiredCapabilities extends TextMotionRendererCapability,
+  Name extends string,
+>(
+  effect: TextMotionEffect<RequiredCapabilities, Name>,
+): TextMotionEffectDescriptor<RequiredCapabilities, TextMotionEffectDescriptorOptions, Name> {
+  const descriptor = effectDescriptors.get(effect);
+
+  if (descriptor) {
+    return descriptor as TextMotionEffectDescriptor<
+      RequiredCapabilities,
+      TextMotionEffectDescriptorOptions,
+      Name
+    >;
+  }
+
+  throw new Error('@react-native-motion-kit/text-motion received an unknown effect handle.');
+}
+
+export function flattenTextMotionEffectDescriptors(
+  effects: readonly TextMotionAnyEffect[],
+): readonly TextMotionAnyEffectDescriptor[] {
+  return effects.flatMap((effect) => {
+    const descriptor = readTextMotionEffectDescriptor(effect);
+
+    return descriptor.effects
+      ? flattenTextMotionEffectDescriptors(descriptor.effects)
+      : [descriptor];
+  });
+}
+
+export function createTextMotionTimelineHandle<
+  Options extends TextMotionTimelineDescriptorOptions,
+  Name extends string,
+>(descriptor: TextMotionTimelineDescriptor<Options, Name>): TextMotionTimeline<Name> {
+  const timeline = {} as TextMotionTimeline<Name>;
+  timelineDescriptors.set(timeline, descriptor);
+
+  return timeline;
+}
+
+export function readTextMotionTimelineDescriptor(
+  timeline: TextMotionAnyTimeline,
+): TextMotionAnyTimelineDescriptor {
+  const descriptor = timelineDescriptors.get(timeline);
+
+  if (descriptor) {
+    return descriptor;
+  }
+
+  throw new Error('@react-native-motion-kit/text-motion received an unknown timeline handle.');
+}
+
+export function createTextMotionSplitterHandle<Unit extends TextMotionTokenUnit>(
+  descriptor: TextMotionSplitterDescriptor<Unit>,
+): TextMotionSplitter<Unit> {
+  const splitter = {} as TextMotionSplitter<Unit>;
+  splitterDescriptors.set(splitter, descriptor);
+
+  return splitter;
+}
+
+export function readTextMotionSplitterDescriptor<Unit extends TextMotionTokenUnit>(
+  splitter: TextMotionSplitter<Unit>,
+): TextMotionSplitterDescriptor<Unit> {
+  const descriptor = splitterDescriptors.get(splitter);
+
+  if (descriptor) {
+    return descriptor as TextMotionSplitterDescriptor<Unit>;
+  }
+
+  throw new Error('@react-native-motion-kit/text-motion received an unknown splitter handle.');
+}
+
+export function createTextMotionRendererHandle<
+  Capabilities extends TextMotionRendererCapability,
+  Recipe,
+  MotionUnit extends 'source-token' | 'rendered-line' = 'source-token',
+>(
+  descriptor: TextMotionRendererDescriptor<Capabilities, Recipe, MotionUnit>,
+): TextMotionRendererHandle<Capabilities, Recipe, MotionUnit> {
+  const renderer = {} as TextMotionRendererHandle<Capabilities, Recipe, MotionUnit>;
+  rendererDescriptors.set(
+    renderer,
+    descriptor as TextMotionRendererDescriptor<TextMotionRendererCapability, unknown>,
+  );
+
+  return renderer;
+}
+
+export function readTextMotionRendererDescriptor<
+  Capabilities extends TextMotionRendererCapability,
+  Recipe,
+>(
+  renderer: TextMotionRenderer<Capabilities, Recipe>,
+): TextMotionRendererDescriptor<Capabilities, Recipe> {
+  const descriptor = rendererDescriptors.get(renderer);
+
+  if (descriptor) {
+    return descriptor as TextMotionRendererDescriptor<Capabilities, Recipe>;
+  }
+
+  throw new Error('@react-native-motion-kit/text-motion received an unknown renderer handle.');
+}

package/src/recipe/index.ts

@@ -0,0 +1,3 @@
+export { createTextMotionComponent } from './component';
+export { defineTextMotion } from './defineTextMotion';
+export type { TextMotionRecipeBuilder, TextMotionRenderableRecipeBuilder } from './recipe';