From 9f78d6c993fcbed01bae8bb97b9e6b097cc1a4ba Mon Sep 17 00:00:00 2001
From: Donghyun Lee <shubug@naver.com>
Date: Sat, 17 Jan 2026 20:22:34 +0900
Subject: [PATCH 1/7] refactor: improve 'useIntersectionObserver' hook

---
 .../useIntersectionObserver.spec.tsx          | 144 +++++++++---------
 .../useIntersectionObserver.ts                |  23 +--
 2 files changed, 83 insertions(+), 84 deletions(-)

diff --git a/src/hooks/useIntersectionObserver/useIntersectionObserver.spec.tsx b/src/hooks/useIntersectionObserver/useIntersectionObserver.spec.tsx
index 7f6791c..955badd 100644
--- a/src/hooks/useIntersectionObserver/useIntersectionObserver.spec.tsx
+++ b/src/hooks/useIntersectionObserver/useIntersectionObserver.spec.tsx
@@ -1,4 +1,4 @@
-import { type RefObject, useEffect } from 'react';
+import { useEffect } from 'react';
 import { act, render, screen } from '@testing-library/react';
 
 import { useIntersectionObserver } from './useIntersectionObserver';
@@ -11,9 +11,9 @@ class MockIntersectionObserver {
     this.callback = callback;
   }
 
-  observe = (element: Element) => {
+  observe = jest.fn((element: Element) => {
     this.elements.push(element);
-  };
+  });
 
   unobserve = jest.fn((element: Element) => {
     this.elements = this.elements.filter(el => el !== element);
@@ -52,122 +52,107 @@ Object.defineProperty(window, 'IntersectionObserver', {
   value: mockIntersectionObserver,
 });
 
-describe('useIntersectionObserver hook', () => {
+describe('useIntersectionObserver', () => {
   beforeEach(() => {
     mockIntersectionObserver.mockClear();
   });
 
   const TestComponent = ({
     options,
-    onIntersect,
+    onChange,
   }: {
     options?: Parameters<typeof useIntersectionObserver>[0];
-    onIntersect?: (isIntersecting: boolean) => void;
+    onChange?: (isIntersecting: boolean) => void;
   }) => {
     const [ref, isIntersecting] = useIntersectionObserver<HTMLDivElement>(options);
 
     useEffect(() => {
-      onIntersect?.(isIntersecting);
-    }, [isIntersecting, onIntersect]);
+      onChange?.(isIntersecting);
+    }, [isIntersecting, onChange]);
 
-    return <div ref={ref as RefObject<HTMLDivElement>} data-testid="target-element" />;
+    return <div ref={ref} data-testid="target" />;
   };
 
-  it('should handle null ref without crashing', () => {
-    const NullRefComponent = () => {
-      useIntersectionObserver<HTMLDivElement>();
-      return null;
-    };
+  it('returns initial isIntersecting as false', () => {
+    let value: boolean | undefined;
 
-    act(() => {
-      render(<NullRefComponent />);
-    });
+    render(<TestComponent onChange={v => (value = v)} />);
+
+    expect(value).toBe(false);
   });
 
-  it('should return a ref and initial isIntersecting state as false', () => {
-    let initialIsIntersecting: boolean | undefined;
+  it('sets isIntersecting to true when intersection occurs', () => {
+    let value = false;
 
-    act(() => {
-      render(<TestComponent onIntersect={val => (initialIsIntersecting = val)} />);
-    });
+    render(<TestComponent onChange={v => (value = v)} />);
 
-    expect(initialIsIntersecting).toBe(false);
+    const target = screen.getByTestId('target');
+    const observer = mockIntersectionObserver.mock.results[0].value as MockIntersectionObserver;
+
+    observer.trigger([{ isIntersecting: true, target }]);
+
+    expect(value).toBe(true);
   });
 
-  it('should set isIntersecting to true when the element intersects', () => {
-    let intersected = false;
+  it('toggles isIntersecting when repeat is true', () => {
+    let value = false;
 
-    act(() => {
-      render(<TestComponent onIntersect={val => (intersected = val)} />);
-    });
+    render(<TestComponent options={{ repeat: true }} onChange={v => (value = v)} />);
+
+    const target = screen.getByTestId('target');
+    const observer = mockIntersectionObserver.mock.results[0].value as MockIntersectionObserver;
 
-    const targetElement = screen.getByTestId('target-element');
-    const observerInstance = mockIntersectionObserver.mock.results[0].value;
+    observer.trigger([{ isIntersecting: true, target }]);
+    expect(value).toBe(true);
 
-    observerInstance.trigger([{ isIntersecting: true, target: targetElement }]);
-    expect(intersected).toBe(true);
+    observer.trigger([{ isIntersecting: false, target }]);
+    expect(value).toBe(false);
   });
 
-  it('should toggle isIntersecting when repeat is true', () => {
-    let intersected = false;
+  it('does not update state when isIntersecting value does not change', () => {
+    const onChange = jest.fn();
 
-    act(() => {
-      render(<TestComponent options={{ repeat: true }} onIntersect={val => (intersected = val)} />);
-    });
+    render(<TestComponent onChange={onChange} />);
 
-    const targetElement = screen.getByTestId('target-element');
-    const observerInstance = mockIntersectionObserver.mock.results[0].value;
+    const target = screen.getByTestId('target');
+    const observer = mockIntersectionObserver.mock.results[0].value as MockIntersectionObserver;
 
-    observerInstance.trigger([{ isIntersecting: true, target: targetElement }]);
-    expect(intersected).toBe(true);
+    observer.trigger([{ isIntersecting: false, target }]);
+    expect(onChange).toHaveBeenCalledTimes(1);
 
-    observerInstance.trigger([{ isIntersecting: false, target: targetElement }]);
-    expect(intersected).toBe(false);
+    observer.trigger([{ isIntersecting: true, target }]);
+    expect(onChange).toHaveBeenCalledTimes(2);
+
+    observer.trigger([{ isIntersecting: true, target }]);
+    expect(onChange).toHaveBeenCalledTimes(2);
   });
 
-  it('should not toggle back when repeat is false', () => {
-    let intersected = false;
+  it('unobserves after first intersection when repeat is false', () => {
+    let value = false;
 
-    act(() => {
-      render(<TestComponent options={{ repeat: false }} onIntersect={val => (intersected = val)} />);
-    });
+    render(<TestComponent options={{ repeat: false }} onChange={v => (value = v)} />);
 
-    const targetElement = screen.getByTestId('target-element');
-    const observerInstance = mockIntersectionObserver.mock.results[0].value;
+    const target = screen.getByTestId('target');
+    const observer = mockIntersectionObserver.mock.results[0].value as MockIntersectionObserver;
 
-    observerInstance.trigger([{ isIntersecting: true, target: targetElement }]);
-    expect(intersected).toBe(true);
+    observer.trigger([{ isIntersecting: true, target }]);
 
-    observerInstance.trigger([{ isIntersecting: false, target: targetElement }]);
-    expect(intersected).toBe(false);
+    expect(value).toBe(true);
+    expect(observer.unobserve).toHaveBeenCalledWith(target);
   });
 
-  it('should disconnect the observer on unmount', () => {
-    let unmount: () => void;
+  it('disconnects observer on unmount', () => {
+    const { unmount } = render(<TestComponent />);
 
-    act(() => {
-      ({ unmount } = render(<TestComponent />));
-    });
+    const observer = mockIntersectionObserver.mock.results[0].value as MockIntersectionObserver;
 
-    const observerInstance = mockIntersectionObserver.mock.results[0].value;
+    unmount();
 
-    act(() => {
-      unmount();
-    });
-
-    expect(observerInstance.disconnect).toHaveBeenCalled();
+    expect(observer.disconnect).toHaveBeenCalled();
   });
 
-  it('should pass correct options to IntersectionObserver', () => {
-    const options = {
-      threshold: 0.5,
-      rootMargin: '10px',
-      repeat: true,
-    };
-
-    act(() => {
-      render(<TestComponent options={options} />);
-    });
+  it('passes correct options to IntersectionObserver', () => {
+    render(<TestComponent options={{ threshold: 0.5, rootMargin: '10px', repeat: true }} />);
 
     expect(mockIntersectionObserver).toHaveBeenCalledWith(expect.any(Function), {
       threshold: 0.5,
@@ -175,4 +160,13 @@ describe('useIntersectionObserver hook', () => {
       rootMargin: '10px',
     });
   });
+
+  it('does nothing if ref is never attached', () => {
+    const NoRefComponent = () => {
+      useIntersectionObserver<HTMLDivElement>();
+      return null;
+    };
+
+    expect(() => render(<NoRefComponent />)).not.toThrow();
+  });
 });
diff --git a/src/hooks/useIntersectionObserver/useIntersectionObserver.ts b/src/hooks/useIntersectionObserver/useIntersectionObserver.ts
index a7d86f5..ae2a9ab 100644
--- a/src/hooks/useIntersectionObserver/useIntersectionObserver.ts
+++ b/src/hooks/useIntersectionObserver/useIntersectionObserver.ts
@@ -1,4 +1,4 @@
-import { type RefObject, useEffect, useRef, useState } from 'react';
+import { type RefCallback, useCallback, useEffect, useState } from 'react';
 
 type UseIntersectionObserverProps = IntersectionObserverInit & {
   repeat?: boolean;
@@ -17,28 +17,33 @@ type UseIntersectionObserverProps = IntersectionObserverInit & {
  * @param {string} [options.rootMargin='0%'] - Margin around the root. Can have values similar to the CSS margin property, e.g. "10px 20px 30px 40px" (top, right, bottom, left).
  * @param {boolean} [options.repeat=true] - If true, the observer will keep observing the element. If false, the observer will unobserve after the first intersection. Defaults to true.
  *
- * @returns {[RefObject<T | null>, boolean]} A tuple containing:
- * - `ref`: A RefObject to be attached to the DOM element you want to observe.
+ * @returns {[RefCallback<T>, boolean]} A tuple containing:
+ * - `ref`: A RefCallback to be attached to the DOM element you want to observe.
  * - `isIntersecting`: A boolean indicating whether the observed element is currently intersecting with its root.
  */
 export const useIntersectionObserver = <T extends Element>(
   options: UseIntersectionObserverProps = {}
-): [RefObject<T | null>, boolean] => {
+): [RefCallback<T>, boolean] => {
   const { threshold = 0, root = null, rootMargin = '0%', repeat = true } = options;
-  const ref = useRef<T>(null);
+
+  const [element, setElement] = useState<T | null>(null);
   const [isIntersecting, setIsIntersecting] = useState(false);
 
+  const ref = useCallback((node: T | null) => {
+    setElement(node);
+  }, []);
+
   useEffect(() => {
-    const element = ref.current;
     if (!element) return;
 
     const observer = new IntersectionObserver(
       ([entry]) => {
         const isVisible = entry.isIntersecting;
-        setIsIntersecting(isVisible);
+
+        setIsIntersecting(prev => (prev === isVisible ? prev : isVisible));
 
         if (isVisible && !repeat) {
-          observer.unobserve(element);
+          observer.unobserve(entry.target);
         }
       },
       { threshold, root, rootMargin }
@@ -49,7 +54,7 @@ export const useIntersectionObserver = <T extends Element>(
     return () => {
       observer.disconnect();
     };
-  }, [threshold, root, rootMargin, repeat]);
+  }, [element, threshold, root, rootMargin, repeat]);
 
   return [ref, isIntersecting];
 };

From 7e764769244a4b43f02de8682cb8f5e932feb8a0 Mon Sep 17 00:00:00 2001
From: Donghyun Lee <shubug@naver.com>
Date: Sat, 17 Jan 2026 20:52:24 +0900
Subject: [PATCH 2/7] refactor: improve 'useAnimateChildren' hook

---
 .../AnimatedSpan.spec.tsx                     |   8 +-
 .../AnimatedSpan.tsx                          |   6 +-
 src/hooks/useAnimateChildren/index.ts         |   2 +
 .../useAnimateChildren.spec.tsx               | 151 +++++++++
 .../useAnimateChildren/useAnimateChildren.tsx | 138 ++++++++
 src/hooks/useAnimatedChildren/index.ts        |   2 -
 .../useAnimatedChildren.spec.tsx              | 308 ------------------
 .../useAnimatedChildren.tsx                   | 115 -------
 .../useTextMotionAnimation.spec.tsx           |  12 +-
 .../useTextMotionAnimation.ts                 |   6 +-
 10 files changed, 307 insertions(+), 441 deletions(-)
 rename src/hooks/{useAnimatedChildren => useAnimateChildren}/AnimatedSpan.spec.tsx (93%)
 rename src/hooks/{useAnimatedChildren => useAnimateChildren}/AnimatedSpan.tsx (94%)
 create mode 100644 src/hooks/useAnimateChildren/index.ts
 create mode 100644 src/hooks/useAnimateChildren/useAnimateChildren.spec.tsx
 create mode 100644 src/hooks/useAnimateChildren/useAnimateChildren.tsx
 delete mode 100644 src/hooks/useAnimatedChildren/index.ts
 delete mode 100644 src/hooks/useAnimatedChildren/useAnimatedChildren.spec.tsx
 delete mode 100644 src/hooks/useAnimatedChildren/useAnimatedChildren.tsx

diff --git a/src/hooks/useAnimatedChildren/AnimatedSpan.spec.tsx b/src/hooks/useAnimateChildren/AnimatedSpan.spec.tsx
similarity index 93%
rename from src/hooks/useAnimatedChildren/AnimatedSpan.spec.tsx
rename to src/hooks/useAnimateChildren/AnimatedSpan.spec.tsx
index ba65816..f5a5180 100644
--- a/src/hooks/useAnimatedChildren/AnimatedSpan.spec.tsx
+++ b/src/hooks/useAnimateChildren/AnimatedSpan.spec.tsx
@@ -31,11 +31,11 @@ describe('AnimatedSpan component', () => {
     expect(span).toHaveStyle({ animation: 'fade-in 1s ease-out 0.5s both' });
   });
 
-  it('renders <br> when text is newline character', () => {
-    const { container } = renderSpan('\n');
+  // it('renders <br> when text is newline character', () => {
+  //   const { container } = renderSpan('\n');
 
-    expect(container.querySelector('br')).toBeInTheDocument();
-  });
+  //   expect(container.querySelector('br')).toBeInTheDocument();
+  // });
 
   it('renders empty span when text is empty string', () => {
     const { span } = renderSpan('');
diff --git a/src/hooks/useAnimatedChildren/AnimatedSpan.tsx b/src/hooks/useAnimateChildren/AnimatedSpan.tsx
similarity index 94%
rename from src/hooks/useAnimatedChildren/AnimatedSpan.tsx
rename to src/hooks/useAnimateChildren/AnimatedSpan.tsx
index 098b1a2..c7f0402 100644
--- a/src/hooks/useAnimatedChildren/AnimatedSpan.tsx
+++ b/src/hooks/useAnimateChildren/AnimatedSpan.tsx
@@ -21,9 +21,9 @@ type Props = {
 export const AnimatedSpan: FC<Props> = ({ text, style, onAnimationEnd }) => {
   const handleAnimationEnd = useAnimationEndCallback(onAnimationEnd);
 
-  if (text === '\n') {
-    return <br />;
-  }
+  // if (text === '\n') {
+  //   return <br />;
+  // }
 
   return (
     <span style={style} aria-hidden="true" onAnimationEnd={handleAnimationEnd}>
diff --git a/src/hooks/useAnimateChildren/index.ts b/src/hooks/useAnimateChildren/index.ts
new file mode 100644
index 0000000..69b4ef0
--- /dev/null
+++ b/src/hooks/useAnimateChildren/index.ts
@@ -0,0 +1,2 @@
+export { AnimatedSpan } from './AnimatedSpan';
+export { useAnimateChildren } from './useAnimateChildren';
diff --git a/src/hooks/useAnimateChildren/useAnimateChildren.spec.tsx b/src/hooks/useAnimateChildren/useAnimateChildren.spec.tsx
new file mode 100644
index 0000000..3af4ec9
--- /dev/null
+++ b/src/hooks/useAnimateChildren/useAnimateChildren.spec.tsx
@@ -0,0 +1,151 @@
+import { cloneElement, isValidElement, type ReactNode } from 'react';
+import { fireEvent, render, renderHook } from '@testing-library/react';
+
+import type { AnimationOrder, Motion } from '../../types';
+import { splitReactNode } from '../../utils/splitReactNode';
+
+import { useAnimateChildren } from './useAnimateChildren';
+
+const renderAnimatedHook = (
+  nodes: ReactNode[],
+  options?: {
+    initialDelay?: number;
+    animationOrder?: AnimationOrder;
+    motion?: Motion;
+    onAnimationEnd?: () => void;
+  }
+) => {
+  const { initialDelay = 0, animationOrder = 'first-to-last', motion = {}, onAnimationEnd } = options ?? {};
+
+  const hookResult = renderHook(() =>
+    useAnimateChildren({
+      nodes,
+      initialDelay,
+      animationOrder,
+      motion,
+      onAnimationEnd,
+    })
+  );
+
+  const elements = Array.isArray(hookResult.result.current) ? hookResult.result.current : [hookResult.result.current];
+
+  const renderResult = render(
+    <>{elements.map((child, index) => (isValidElement(child) ? cloneElement(child, { key: index }) : child))}</>
+  );
+
+  return {
+    ...renderResult,
+    spans: renderResult.container.querySelectorAll('span'),
+  };
+};
+
+describe('useAnimateChildren', () => {
+  const split = 'character';
+  const motion: Motion = {};
+
+  it('creates AnimatedSpan elements for string children', () => {
+    const { nodes } = splitReactNode('Hey', split);
+    const { spans } = renderAnimatedHook(nodes);
+
+    expect(spans).toHaveLength(3);
+    expect(Array.from(spans).map(s => s.textContent)).toEqual(['H', 'e', 'y']);
+  });
+
+  it('handles number children correctly', () => {
+    const { nodes } = splitReactNode(123, split);
+    const { spans } = renderAnimatedHook(nodes);
+
+    expect(spans).toHaveLength(3);
+    expect(Array.from(spans).map(s => s.textContent)).toEqual(['1', '2', '3']);
+  });
+
+  it('returns empty result for empty string', () => {
+    const { nodes } = splitReactNode('', split);
+    const { spans } = renderAnimatedHook(nodes);
+
+    expect(spans).toHaveLength(0);
+  });
+
+  it('preserves nested React element structure', () => {
+    const { nodes } = splitReactNode(<p>Hello</p>, split);
+    const { container } = renderAnimatedHook(nodes);
+
+    const paragraph = container.querySelector('p');
+    const spans = paragraph?.querySelectorAll('span') ?? [];
+
+    expect(paragraph).toBeInTheDocument();
+    expect(
+      Array.from(spans)
+        .map(s => s.textContent)
+        .join('')
+    ).toBe('Hello');
+  });
+
+  it('returns unknown node types as-is', () => {
+    const unknownNode = Symbol('unknown');
+    const { result } = renderHook(() =>
+      useAnimateChildren({
+        nodes: [unknownNode as any],
+        initialDelay: 0,
+        animationOrder: 'first-to-last',
+        motion: {},
+      })
+    );
+
+    expect(result.current).toEqual([unknownNode]);
+  });
+
+  it('splits text by word when split type is "word"', () => {
+    const { nodes } = splitReactNode('Hello World', 'word');
+    const { spans } = renderAnimatedHook(nodes);
+
+    expect(Array.from(spans).map(s => s.textContent)).toEqual(['Hello', ' ', 'World']);
+  });
+
+  // it('renders <br /> for newline characters', () => {
+  //   const { nodes } = splitReactNode('A\nB', split);
+  //   const { container } = renderAnimatedHook(nodes);
+
+  //   expect(container.querySelector('br')).toBeInTheDocument();
+  // });
+
+  it('calls onAnimationEnd only when the last animation ends', () => {
+    const onAnimationEnd = jest.fn();
+    const { nodes } = splitReactNode('ABC', split);
+
+    const { spans } = renderAnimatedHook(nodes, { onAnimationEnd });
+
+    fireEvent.animationEnd(spans[0]);
+    fireEvent.animationEnd(spans[1]);
+
+    expect(onAnimationEnd).not.toHaveBeenCalled();
+
+    fireEvent.animationEnd(spans[2]);
+
+    expect(onAnimationEnd).toHaveBeenCalledTimes(1);
+  });
+
+  it('updates onAnimationEnd callback when it changes', () => {
+    const firstCallback = jest.fn();
+    const secondCallback = jest.fn();
+    const { nodes } = splitReactNode('A', split);
+
+    const { rerender } = renderHook(
+      ({ onAnimationEnd }) =>
+        useAnimateChildren({
+          nodes,
+          initialDelay: 0,
+          animationOrder: 'first-to-last',
+          motion,
+          onAnimationEnd,
+        }),
+      {
+        initialProps: { onAnimationEnd: firstCallback },
+      }
+    );
+
+    rerender({ onAnimationEnd: secondCallback });
+
+    expect(secondCallback).not.toHaveBeenCalled();
+  });
+});
diff --git a/src/hooks/useAnimateChildren/useAnimateChildren.tsx b/src/hooks/useAnimateChildren/useAnimateChildren.tsx
new file mode 100644
index 0000000..7883d61
--- /dev/null
+++ b/src/hooks/useAnimateChildren/useAnimateChildren.tsx
@@ -0,0 +1,138 @@
+import { Children, cloneElement, type ReactNode, type RefObject, useEffect, useMemo, useRef } from 'react';
+
+import type { AnimationOrder, Motion } from '../../types';
+import { countNodes } from '../../utils/countNodes';
+import { generateAnimation } from '../../utils/generateAnimation';
+import { calculateSequenceIndex, isLastNode } from '../../utils/sequenceHelpers';
+import { isElementWithChildren, isTextNode } from '../../utils/typeGuards';
+
+import { AnimatedSpan } from './AnimatedSpan';
+
+type UseAnimatedChildrenParams = {
+  nodes: ReactNode[];
+  initialDelay: number;
+  animationOrder: AnimationOrder;
+  motion: Motion;
+  onAnimationEnd?: () => void;
+};
+
+type AnimateResult = {
+  animatedNodes: ReactNode[];
+  nextSequenceIndex: number;
+};
+
+/**
+ * @description
+ * `useAnimateChildren` is a custom hook that animates an array of React nodes.
+ * It manages the animation sequence index to apply delays correctly.
+ *
+ * @param {ReactNode[]} nodes - The array of React nodes to be animated.
+ * @param {number} initialDelay - The initial delay before the animation starts, in seconds.
+ * @param {AnimationOrder} animationOrder - Defines the order in which the animation sequence is applied. Defaults to `'first-to-last'`.
+ * @param {Motion} motion - The motion configuration object, which is a result of merging custom motion and presets.
+ * @param {() => void} onAnimationEnd - Callback function that is called when the animation ends.
+ *
+ * @returns {ReactNode[]} An array of animated React nodes.
+ */
+export const useAnimateChildren = ({
+  nodes,
+  initialDelay,
+  animationOrder,
+  motion,
+  onAnimationEnd,
+}: UseAnimatedChildrenParams): ReactNode[] => {
+  const onAnimationEndRef = useRef(onAnimationEnd);
+
+  useEffect(() => {
+    onAnimationEndRef.current = onAnimationEnd;
+  }, [onAnimationEnd]);
+
+  const animatedChildren = useMemo(() => {
+    const totalTextNodeCount = countNodes(nodes);
+
+    const { animatedNodes } = animateNodeTree({
+      nodes,
+      startSequenceIndex: 0,
+      totalTextNodeCount,
+      initialDelay,
+      animationOrder,
+      motion,
+      onAnimationEndRef,
+    });
+
+    return animatedNodes;
+  }, [nodes, initialDelay, animationOrder, motion]);
+
+  return animatedChildren;
+};
+
+type AnimateNodeTreeParams = {
+  nodes: ReactNode[];
+  startSequenceIndex: number;
+  totalTextNodeCount: number;
+  initialDelay: number;
+  animationOrder: AnimationOrder;
+  motion: Motion;
+  onAnimationEndRef?: RefObject<(() => void) | undefined>;
+};
+
+const animateNodeTree = ({
+  nodes,
+  startSequenceIndex,
+  totalTextNodeCount,
+  initialDelay,
+  animationOrder,
+  motion,
+  onAnimationEndRef,
+}: AnimateNodeTreeParams): AnimateResult => {
+  let sequenceIndex = startSequenceIndex;
+
+  const animatedNodes = nodes.map((node, key) => {
+    if (isTextNode(node)) {
+      const rawSequenceIndex = sequenceIndex++;
+      const orderedSequenceIndex = calculateSequenceIndex(rawSequenceIndex, totalTextNodeCount, animationOrder);
+
+      const shouldTriggerAnimationEnd = isLastNode(orderedSequenceIndex, totalTextNodeCount);
+
+      const { style } = generateAnimation(motion, orderedSequenceIndex, initialDelay);
+
+      return (
+        <AnimatedSpan
+          key={key}
+          text={String(node)}
+          style={style}
+          onAnimationEnd={shouldTriggerAnimationEnd ? () => onAnimationEndRef?.current?.() : undefined}
+        />
+      );
+    }
+
+    if (isElementWithChildren(node)) {
+      const childNodes = Children.toArray(node.props.children);
+
+      const { animatedNodes: animatedChildren, nextSequenceIndex } = animateNodeTree({
+        nodes: childNodes,
+        startSequenceIndex: sequenceIndex,
+        totalTextNodeCount,
+        initialDelay,
+        animationOrder,
+        motion,
+        onAnimationEndRef,
+      });
+
+      sequenceIndex = nextSequenceIndex;
+
+      return cloneElement(node, {
+        ...node.props,
+        children: animatedChildren,
+        key,
+      });
+    }
+
+    return node;
+  });
+
+  return {
+    animatedNodes,
+    nextSequenceIndex: sequenceIndex,
+  };
+};
diff --git a/src/hooks/useAnimatedChildren/index.ts b/src/hooks/useAnimatedChildren/index.ts
deleted file mode 100644
index 5f5da9f..0000000
--- a/src/hooks/useAnimatedChildren/index.ts
+++ /dev/null
@@ -1,2 +0,0 @@
-export { AnimatedSpan } from './AnimatedSpan';
-export { useAnimatedChildren } from './useAnimatedChildren';
diff --git a/src/hooks/useAnimatedChildren/useAnimatedChildren.spec.tsx b/src/hooks/useAnimatedChildren/useAnimatedChildren.spec.tsx
deleted file mode 100644
index e6a8b8e..0000000
--- a/src/hooks/useAnimatedChildren/useAnimatedChildren.spec.tsx
+++ /dev/null
@@ -1,308 +0,0 @@
-import { cloneElement, isValidElement, type ReactNode } from 'react';
-import { fireEvent, render, renderHook } from '@testing-library/react';
-
-import type { AnimationOrder, Motion } from '../../types';
-import * as generateAnimationModule from '../../utils/generateAnimation';
-import { splitReactNode } from '../../utils/splitReactNode';
-
-import { useAnimatedChildren } from './useAnimatedChildren';
-
-const renderAnimatedNode = (
-  children: ReactNode,
-  split: 'character' | 'word',
-  resolvedMotion: Motion = {},
-  initialDelay = 0,
-  animationOrder: AnimationOrder = 'first-to-last'
-) => {
-  const { nodes } = splitReactNode(children, split);
-  const { result } = renderHook(() => useAnimatedChildren({ nodes, initialDelay, animationOrder, resolvedMotion }));
-  const childrenArray = Array.isArray(result.current) ? result.current : [result.current];
-  const { container } = render(
-    <>{childrenArray.map((child, index) => (isValidElement(child) ? cloneElement(child, { key: index }) : child))}</>
-  );
-
-  return container.querySelectorAll('span');
-};
-
-describe('useAnimatedChildren hook', () => {
-  const split = 'character';
-  const resolvedMotion: Motion = {};
-
-  it('generates animated spans for string children', () => {
-    const spans = renderAnimatedNode('Hey', split, resolvedMotion);
-
-    expect(spans).toHaveLength(3);
-    expect(Array.from(spans).map(s => s.textContent)).toEqual(['H', 'e', 'y']);
-  });
-
-  it('handles number children', () => {
-    const spans = renderAnimatedNode(123, split, resolvedMotion);
-
-    expect(spans).toHaveLength(3);
-    expect(Array.from(spans).map(s => s.textContent)).toEqual(['1', '2', '3']);
-  });
-
-  it('handles empty string gracefully', () => {
-    const spans = renderAnimatedNode('', split, resolvedMotion);
-
-    expect(spans).toHaveLength(0);
-  });
-
-  it('handles nested React elements with text', () => {
-    const { nodes } = splitReactNode(<p>Hello</p>, split);
-    const { result } = renderHook(() =>
-      useAnimatedChildren({ nodes, initialDelay: 0, animationOrder: 'first-to-last', resolvedMotion })
-    );
-    const { container } = render(
-      <>
-        {Array.isArray(result.current)
-          ? result.current.map((child: ReactNode, index: number) =>
-              isValidElement(child) ? cloneElement(child, { key: index }) : child
-            )
-          : result.current}
-      </>
-    );
-
-    const p = container.querySelector('p');
-    const spans = p?.querySelectorAll('span') ?? [];
-
-    expect(p).toBeInTheDocument();
-    expect(spans).toHaveLength(5);
-    expect(
-      Array.from(spans)
-        .map(s => s.textContent)
-        .join('')
-    ).toBe('Hello');
-  });
-
-  it('handles React element without children', () => {
-    const { nodes } = splitReactNode(<span />, split);
-    const { result } = renderHook(() =>
-      useAnimatedChildren({ nodes, initialDelay: 0, animationOrder: 'first-to-last', resolvedMotion })
-    );
-    const { container } = render(
-      <>
-        {Array.isArray(result.current)
-          ? result.current.map((child: ReactNode, index: number) =>
-              isValidElement(child) ? cloneElement(child, { key: index }) : child
-            )
-          : result.current}
-      </>
-    );
-
-    const span = container.querySelector('span');
-
-    expect(span).toBeInTheDocument();
-    expect(span?.textContent).toBe('');
-  });
-
-  it('handles unknown node types gracefully', () => {
-    const { nodes } = splitReactNode([null, true] as any, split);
-    const { result } = renderHook(() =>
-      useAnimatedChildren({ nodes, initialDelay: 0, animationOrder: 'first-to-last', resolvedMotion })
-    );
-    const { container } = render(
-      <>
-        {Array.isArray(result.current)
-          ? result.current.map((child: ReactNode, index: number) =>
-              isValidElement(child) ? cloneElement(child, { key: index }) : child
-            )
-          : result.current}
-      </>
-    );
-
-    expect(container.textContent).toBe('');
-  });
-
-  it('splits by word when split type is "word"', () => {
-    const spans = renderAnimatedNode('Hello World', 'word', resolvedMotion);
-
-    expect(spans).toHaveLength(3);
-    expect(Array.from(spans).map(s => s.textContent)).toEqual(['Hello', ' ', 'World']);
-  });
-
-  it('returns unknown node types as-is', () => {
-    const unknownNode = Symbol('unknown');
-    const { result } = renderHook(() =>
-      useAnimatedChildren({
-        nodes: [unknownNode as any],
-        initialDelay: 0,
-        animationOrder: 'first-to-last',
-        resolvedMotion,
-      })
-    );
-
-    expect(result.current).toEqual([unknownNode]);
-  });
-
-  it('calls onAnimationEnd callback when last node animation ends', () => {
-    const onAnimationEndMock = jest.fn();
-    const { nodes } = splitReactNode('Hi', 'character');
-
-    renderHook(() =>
-      useAnimatedChildren({
-        nodes,
-        initialDelay: 0,
-        animationOrder: 'first-to-last',
-        resolvedMotion,
-        onAnimationEnd: onAnimationEndMock,
-      })
-    );
-
-    expect(onAnimationEndMock).toBeDefined();
-  });
-
-  it('creates handleAnimationEnd function for last node', () => {
-    const onAnimationEndMock = jest.fn();
-    const { nodes } = splitReactNode('A', 'character');
-
-    const { result } = renderHook(() =>
-      useAnimatedChildren({
-        nodes,
-        initialDelay: 0,
-        animationOrder: 'first-to-last',
-        resolvedMotion,
-        onAnimationEnd: onAnimationEndMock,
-      })
-    );
-
-    const animatedNodes = result.current;
-
-    expect(animatedNodes).toHaveLength(1);
-    expect(onAnimationEndMock).toBeDefined();
-  });
-
-  it('creates handleAnimationEnd function for last node in multi-character text', () => {
-    const onAnimationEndMock = jest.fn();
-    const { nodes } = splitReactNode('ABC', 'character');
-
-    const { result } = renderHook(() =>
-      useAnimatedChildren({
-        nodes,
-        initialDelay: 0,
-        animationOrder: 'first-to-last',
-        resolvedMotion,
-        onAnimationEnd: onAnimationEndMock,
-      })
-    );
-
-    const animatedNodes = result.current;
-
-    expect(animatedNodes).toHaveLength(3);
-    expect(onAnimationEndMock).toBeDefined();
-  });
-
-  it('triggers onAnimationEnd callback when last node animation ends', () => {
-    const onAnimationEndMock = jest.fn();
-    const { nodes } = splitReactNode('A', 'character');
-
-    const { result } = renderHook(() =>
-      useAnimatedChildren({
-        nodes,
-        initialDelay: 0,
-        animationOrder: 'first-to-last',
-        resolvedMotion,
-        onAnimationEnd: onAnimationEndMock,
-      })
-    );
-
-    const { container } = render(
-      <>
-        {Array.isArray(result.current)
-          ? result.current.map((child: ReactNode, index: number) =>
-              isValidElement(child) ? cloneElement(child, { key: index }) : child
-            )
-          : result.current}
-      </>
-    );
-
-    const spans = container.querySelectorAll('span');
-    const lastSpan = spans[spans.length - 1];
-
-    fireEvent.animationEnd(lastSpan!);
-
-    expect(onAnimationEndMock).toBeDefined();
-  });
-
-  it('updates onAnimationEnd callback when it changes', () => {
-    const onAnimationEndMock1 = jest.fn();
-    const onAnimationEndMock2 = jest.fn();
-    const { nodes } = splitReactNode('A', 'character');
-
-    const { rerender } = renderHook(
-      ({ onAnimationEnd }) =>
-        useAnimatedChildren({
-          nodes,
-          initialDelay: 0,
-          animationOrder: 'first-to-last',
-          resolvedMotion,
-          onAnimationEnd,
-        }),
-      {
-        initialProps: { onAnimationEnd: onAnimationEndMock1 },
-      }
-    );
-
-    rerender({ onAnimationEnd: onAnimationEndMock2 });
-
-    expect(onAnimationEndMock2).toBeDefined();
-  });
-});
-
-describe('useAnimatedChildren animationIndex calculation', () => {
-  const initialDelay = 0;
-  const resolvedMotion: Motion = {};
-  const generateAnimationSpy = jest.spyOn(generateAnimationModule, 'generateAnimation');
-
-  beforeEach(() => {
-    generateAnimationSpy.mockClear();
-  });
-
-  it('calculates animationIndex in first-to-last order', () => {
-    const text = 'ABC';
-    const { nodes } = splitReactNode(text, 'character');
-
-    renderHook(() => useAnimatedChildren({ nodes, initialDelay, animationOrder: 'first-to-last', resolvedMotion }));
-
-    const calls = generateAnimationSpy.mock.calls;
-
-    expect(calls[0][1]).toBe(0);
-    expect(calls[1][1]).toBe(1);
-    expect(calls[2][1]).toBe(2);
-  });
-
-  it('calculates animationIndex in last-to-first order', () => {
-    const text = 'ABC';
-    const { nodes } = splitReactNode(text, 'character');
-
-    renderHook(() => useAnimatedChildren({ nodes, initialDelay, animationOrder: 'last-to-first', resolvedMotion }));
-
-    const calls = generateAnimationSpy.mock.calls;
-
-    expect(calls[0][1]).toBe(2);
-    expect(calls[1][1]).toBe(1);
-    expect(calls[2][1]).toBe(0);
-  });
-});
-
-describe('AnimatedSpan newline handling', () => {
-  it('renders br element for newline characters in text', () => {
-    const { nodes } = splitReactNode('A\nB', 'character');
-    const { result } = renderHook(() =>
-      useAnimatedChildren({ nodes, initialDelay: 0, animationOrder: 'first-to-last', resolvedMotion: {} })
-    );
-    const { container } = render(
-      <>
-        {Array.isArray(result.current)
-          ? result.current.map((child: ReactNode, index: number) =>
-              isValidElement(child) ? cloneElement(child, { key: index }) : child
-            )
-          : result.current}
-      </>
-    );
-
-    const brElement = container.querySelector('br');
-
-    expect(brElement).toBeInTheDocument();
-  });
-});
diff --git a/src/hooks/useAnimatedChildren/useAnimatedChildren.tsx b/src/hooks/useAnimatedChildren/useAnimatedChildren.tsx
deleted file mode 100644
index e310703..0000000
--- a/src/hooks/useAnimatedChildren/useAnimatedChildren.tsx
+++ /dev/null
@@ -1,115 +0,0 @@
-import { Children, cloneElement, type ReactNode, type RefObject, useEffect, useMemo, useRef } from 'react';
-
-import type { AnimationOrder, Motion } from '../../types';
-import { countNodes } from '../../utils/countNodes';
-import { generateAnimation } from '../../utils/generateAnimation';
-import { calculateSequenceIndex, isLastNode } from '../../utils/sequenceHelpers';
-import { isElementWithChildren, isTextNode } from '../../utils/typeGuards';
-
-import { AnimatedSpan } from './AnimatedSpan';
-
-type UseAnimatedChildrenProps = {
-  nodes: ReactNode[];
-  initialDelay: number;
-  animationOrder: AnimationOrder;
-  resolvedMotion: Motion;
-  onAnimationEnd?: () => void;
-};
-
-type WrapResult = {
-  nodes: ReactNode[];
-  nextSequenceIndex: number;
-};
-
-/**
- * @description
- * `useAnimatedChildren` is a custom hook that animates an array of React nodes.
- * It manages the animation sequence index to apply delays correctly.
- *
- * @param {ReactNode[]} nodes - The array of React nodes to be animated.
- * @param {number} initialDelay - The initial delay before the animation starts, in seconds.
- * @param {AnimationOrder} animationOrder - Defines the order in which the animation sequence is applied. Defaults to `'first-to-last'`.
- * @param {Motion} resolvedMotion - The motion configuration object, which is a result of merging custom motion and presets.
- * @param {() => void} onAnimationEnd - Callback function that is called when the animation ends.
- *
- * @returns {ReactNode[]} An array of animated React nodes.
- */
-export const useAnimatedChildren = ({
-  nodes,
-  initialDelay,
-  animationOrder,
-  resolvedMotion,
-  onAnimationEnd,
-}: UseAnimatedChildrenProps): ReactNode[] => {
-  const onAnimationEndRef = useRef(onAnimationEnd);
-
-  useEffect(() => {
-    onAnimationEndRef.current = onAnimationEnd;
-  }, [onAnimationEnd]);
-
-  const animatedChildren = useMemo(() => {
-    const totalNodes = countNodes(nodes);
-
-    const { nodes: animatedNodes } = wrapWithAnimatedSpan(
-      nodes,
-      0,
-      initialDelay,
-      animationOrder,
-      resolvedMotion,
-      totalNodes,
-      onAnimationEndRef
-    );
-
-    return animatedNodes;
-  }, [nodes, initialDelay, animationOrder, resolvedMotion]);
-
-  return animatedChildren;
-};
-
-const wrapWithAnimatedSpan = (
-  nodes: ReactNode[],
-  currentSequenceIndex: number,
-  initialDelay: number,
-  animationOrder: AnimationOrder,
-  resolvedMotion: Motion,
-  totalNodes: number,
-  onAnimationEndRef?: RefObject<(() => void) | undefined>
-): WrapResult => {
-  let sequenceIndex = currentSequenceIndex;
-
-  const animatedNodes = nodes.map((node, key) => {
-    if (isTextNode(node)) {
-      const currentIndex = sequenceIndex++;
-      const calculatedSequenceIndex = calculateSequenceIndex(currentIndex, totalNodes, animationOrder);
-      const isLast = isLastNode(calculatedSequenceIndex, totalNodes);
-      const handleAnimationEnd = isLast ? () => onAnimationEndRef?.current?.() : undefined;
-      const { style } = generateAnimation(resolvedMotion, calculatedSequenceIndex, initialDelay);
-
-      return <AnimatedSpan key={key} text={String(node)} style={style} onAnimationEnd={handleAnimationEnd} />;
-    }
-
-    if (isElementWithChildren(node)) {
-      const childArray = Children.toArray(node.props.children);
-      const { nodes: animatedChildren, nextSequenceIndex } = wrapWithAnimatedSpan(
-        childArray,
-        sequenceIndex,
-        initialDelay,
-        animationOrder,
-        resolvedMotion,
-        totalNodes,
-        onAnimationEndRef
-      );
-      sequenceIndex = nextSequenceIndex;
-
-      return cloneElement(node, {
-        ...node.props,
-        children: animatedChildren,
-        key,
-      });
-    }
-
-    return node;
-  });
-
-  return { nodes: animatedNodes, nextSequenceIndex: sequenceIndex };
-};
diff --git a/src/hooks/useTextMotionAnimation/useTextMotionAnimation.spec.tsx b/src/hooks/useTextMotionAnimation/useTextMotionAnimation.spec.tsx
index e53ada7..4c289c8 100644
--- a/src/hooks/useTextMotionAnimation/useTextMotionAnimation.spec.tsx
+++ b/src/hooks/useTextMotionAnimation/useTextMotionAnimation.spec.tsx
@@ -2,7 +2,7 @@ import { renderHook } from '@testing-library/react';
 
 import type { Preset, TextMotionProps } from '../../types';
 import { splitReactNode } from '../../utils/splitReactNode';
-import { useAnimatedChildren } from '../useAnimatedChildren';
+import { useAnimateChildren } from '../useAnimateChildren';
 import { useIntersectionObserver } from '../useIntersectionObserver';
 import { useResolvedMotion } from '../useResolvedMotion';
 
@@ -10,13 +10,13 @@ import { useTextMotionAnimation } from './useTextMotionAnimation';
 
 jest.mock('../useIntersectionObserver');
 jest.mock('../useResolvedMotion');
-jest.mock('../useAnimatedChildren');
+jest.mock('../useAnimateChildren');
 jest.mock('../../utils/splitReactNode');
 
 describe('useTextMotionAnimation', () => {
   const mockUseIntersectionObserver = useIntersectionObserver as jest.Mock;
   const mockUseResolvedMotion = useResolvedMotion as jest.Mock;
-  const mockUseAnimatedChildren = useAnimatedChildren as jest.Mock;
+  const mockUseAnimatedChildren = useAnimateChildren as jest.Mock;
   const mockSplitReactNode = splitReactNode as jest.Mock;
 
   const defaultProps: TextMotionProps = {
@@ -69,7 +69,7 @@ describe('useTextMotionAnimation', () => {
     expect(mockUseResolvedMotion).toHaveBeenCalledWith({ motion: undefined, preset });
   });
 
-  it('should call useAnimatedChildren with correct props when animating', () => {
+  it('should call useAnimateChildren with correct props when animating', () => {
     const props = { ...defaultProps, initialDelay: 1, animationOrder: 'last-to-first' as const };
     renderHook(() => useTextMotionAnimation(props));
 
@@ -77,12 +77,12 @@ describe('useTextMotionAnimation', () => {
       nodes: ['H', 'e', 'l', 'l', 'o'],
       initialDelay: 1,
       animationOrder: 'last-to-first',
-      resolvedMotion: {},
+      motion: {},
       onAnimationEnd: undefined,
     });
   });
 
-  it('should call useAnimatedChildren with original children when not animating', () => {
+  it('should call useAnimateChildren with original children when not animating', () => {
     mockUseIntersectionObserver.mockReturnValue([null, false]);
     const props = { ...defaultProps, trigger: 'scroll' as const };
     renderHook(() => useTextMotionAnimation(props));
diff --git a/src/hooks/useTextMotionAnimation/useTextMotionAnimation.ts b/src/hooks/useTextMotionAnimation/useTextMotionAnimation.ts
index 0d82865..52898f4 100644
--- a/src/hooks/useTextMotionAnimation/useTextMotionAnimation.ts
+++ b/src/hooks/useTextMotionAnimation/useTextMotionAnimation.ts
@@ -2,7 +2,7 @@ import { useMemo } from 'react';
 
 import type { TextMotionProps } from '../../types';
 import { splitReactNode } from '../../utils/splitReactNode';
-import { useAnimatedChildren } from '../useAnimatedChildren';
+import { useAnimateChildren } from '../useAnimateChildren';
 import { useIntersectionObserver } from '../useIntersectionObserver';
 import { useResolvedMotion } from '../useResolvedMotion';
 
@@ -34,11 +34,11 @@ export const useTextMotionAnimation = (props: TextMotionProps) => {
 
   const resolvedMotion = useResolvedMotion({ motion, preset });
 
-  const animatedChildren = useAnimatedChildren({
+  const animatedChildren = useAnimateChildren({
     nodes: shouldAnimate ? nodes : [children],
     initialDelay,
     animationOrder,
-    resolvedMotion,
+    motion: resolvedMotion,
     onAnimationEnd,
   });
 

From c6f221c3dacad7f1bf3fae9c90d8f6699c92004c Mon Sep 17 00:00:00 2001
From: Donghyun Lee <shubug@naver.com>
Date: Sat, 17 Jan 2026 21:08:05 +0900
Subject: [PATCH 3/7] refactor: rename 'useResolveMotion' hook

---
 .../useAnimateChildren/useAnimateChildren.tsx | 20 +++++++++----------
 src/hooks/useResolveMotion/index.ts           |  2 ++
 .../motionMap.ts                              |  0
 .../useResolveMotion.spec.ts}                 | 14 ++++++-------
 .../useResolveMotion.ts}                      |  4 ++--
 src/hooks/useResolvedMotion/index.ts          |  2 --
 .../useTextMotionAnimation.spec.tsx           | 10 +++++-----
 .../useTextMotionAnimation.ts                 |  4 ++--
 8 files changed, 28 insertions(+), 28 deletions(-)
 create mode 100644 src/hooks/useResolveMotion/index.ts
 rename src/hooks/{useResolvedMotion => useResolveMotion}/motionMap.ts (100%)
 rename src/hooks/{useResolvedMotion/useResolvedMotion.spec.ts => useResolveMotion/useResolveMotion.spec.ts} (72%)
 rename src/hooks/{useResolvedMotion/useResolvedMotion.ts => useResolveMotion/useResolveMotion.ts} (86%)
 delete mode 100644 src/hooks/useResolvedMotion/index.ts

diff --git a/src/hooks/useAnimateChildren/useAnimateChildren.tsx b/src/hooks/useAnimateChildren/useAnimateChildren.tsx
index 7883d61..c7ae008 100644
--- a/src/hooks/useAnimateChildren/useAnimateChildren.tsx
+++ b/src/hooks/useAnimateChildren/useAnimateChildren.tsx
@@ -21,6 +21,16 @@ type AnimateResult = {
   nextSequenceIndex: number;
 };
 
+type AnimateNodeTreeParams = {
+  nodes: ReactNode[];
+  startSequenceIndex: number;
+  totalTextNodeCount: number;
+  initialDelay: number;
+  animationOrder: AnimationOrder;
+  motion: Motion;
+  onAnimationEndRef?: RefObject<(() => void) | undefined>;
+};
+
 /**
  * @description
  * `useAnimateChildren` is a custom hook that animates an array of React nodes.
@@ -66,16 +76,6 @@ export const useAnimateChildren = ({
   return animatedChildren;
 };
 
-type AnimateNodeTreeParams = {
-  nodes: ReactNode[];
-  startSequenceIndex: number;
-  totalTextNodeCount: number;
-  initialDelay: number;
-  animationOrder: AnimationOrder;
-  motion: Motion;
-  onAnimationEndRef?: RefObject<(() => void) | undefined>;
-};
-
 const animateNodeTree = ({
   nodes,
   startSequenceIndex,
diff --git a/src/hooks/useResolveMotion/index.ts b/src/hooks/useResolveMotion/index.ts
new file mode 100644
index 0000000..a89f96b
--- /dev/null
+++ b/src/hooks/useResolveMotion/index.ts
@@ -0,0 +1,2 @@
+export { motionMap } from './motionMap';
+export { useResolveMotion } from './useResolveMotion';
diff --git a/src/hooks/useResolvedMotion/motionMap.ts b/src/hooks/useResolveMotion/motionMap.ts
similarity index 100%
rename from src/hooks/useResolvedMotion/motionMap.ts
rename to src/hooks/useResolveMotion/motionMap.ts
diff --git a/src/hooks/useResolvedMotion/useResolvedMotion.spec.ts b/src/hooks/useResolveMotion/useResolveMotion.spec.ts
similarity index 72%
rename from src/hooks/useResolvedMotion/useResolvedMotion.spec.ts
rename to src/hooks/useResolveMotion/useResolveMotion.spec.ts
index 45ca243..8c29cef 100644
--- a/src/hooks/useResolvedMotion/useResolvedMotion.spec.ts
+++ b/src/hooks/useResolveMotion/useResolveMotion.spec.ts
@@ -3,18 +3,18 @@ import { renderHook } from '@testing-library/react';
 import type { Motion, Preset } from '../../types';
 
 import { DELAY, DURATION } from './motionMap';
-import { useResolvedMotion } from './useResolvedMotion';
+import { useResolveMotion } from './useResolveMotion';
 
-describe('useResolvedMotion hook', () => {
+describe('useResolveMotion hook', () => {
   it('returns empty object when motion is undefined', () => {
-    const { result } = renderHook(() => useResolvedMotion({}));
+    const { result } = renderHook(() => useResolveMotion({}));
 
     expect(result.current).toEqual({});
   });
 
   it('returns empty object when motion has no keys', () => {
     const motion: Motion = {};
-    const { result } = renderHook(() => useResolvedMotion({ motion }));
+    const { result } = renderHook(() => useResolveMotion({ motion }));
 
     expect(result.current).toEqual({});
   });
@@ -24,14 +24,14 @@ describe('useResolvedMotion hook', () => {
       fade: { variant: 'out', duration: 1, delay: 0.5 },
       slide: { variant: 'up', duration: 2, delay: 1 },
     };
-    const { result } = renderHook(() => useResolvedMotion({ motion }));
+    const { result } = renderHook(() => useResolveMotion({ motion }));
 
     expect(result.current).toStrictEqual(motion);
   });
 
   it('returns preset-based motion when preset is provided', () => {
     const preset: Preset[] = ['fade-in'];
-    const { result } = renderHook(() => useResolvedMotion({ preset }));
+    const { result } = renderHook(() => useResolveMotion({ preset }));
 
     expect(result.current).toEqual({
       fade: { variant: 'in', duration: DURATION, delay: DELAY },
@@ -40,7 +40,7 @@ describe('useResolvedMotion hook', () => {
 
   it('merges multiple presets correctly when multiple presets are provided', () => {
     const preset: Preset[] = ['fade-in', 'slide-up'];
-    const { result } = renderHook(() => useResolvedMotion({ preset }));
+    const { result } = renderHook(() => useResolveMotion({ preset }));
 
     expect(result.current).toEqual({
       fade: { variant: 'in', duration: DURATION, delay: DELAY },
diff --git a/src/hooks/useResolvedMotion/useResolvedMotion.ts b/src/hooks/useResolveMotion/useResolveMotion.ts
similarity index 86%
rename from src/hooks/useResolvedMotion/useResolvedMotion.ts
rename to src/hooks/useResolveMotion/useResolveMotion.ts
index c413cbd..aa75967 100644
--- a/src/hooks/useResolvedMotion/useResolvedMotion.ts
+++ b/src/hooks/useResolveMotion/useResolveMotion.ts
@@ -11,7 +11,7 @@ type UseResolvedMotionProps = {
 
 /**
  * @description
- * `useResolvedMotion` is a custom hook that resolves the motion configuration.
+ * `useResolveMotion` is a custom hook that resolves the motion configuration.
  * It either uses the provided `motion` object or generates a configuration from the `preset` array.
  * If a `preset` is provided, it will be mapped to a `Motion` object.
  * If a `motion` object is provided, it will be deep-copied.
@@ -22,7 +22,7 @@ type UseResolvedMotionProps = {
  *
  * @returns {Motion} The resolved motion configuration object.
  */
-export const useResolvedMotion = ({ motion, preset }: UseResolvedMotionProps): Motion => {
+export const useResolveMotion = ({ motion, preset }: UseResolvedMotionProps): Motion => {
   const resolvedMotion = useMemo(() => {
     if (preset) {
       return mergePresets(preset);
diff --git a/src/hooks/useResolvedMotion/index.ts b/src/hooks/useResolvedMotion/index.ts
deleted file mode 100644
index 8df6182..0000000
--- a/src/hooks/useResolvedMotion/index.ts
+++ /dev/null
@@ -1,2 +0,0 @@
-export { motionMap } from './motionMap';
-export { useResolvedMotion } from './useResolvedMotion';
diff --git a/src/hooks/useTextMotionAnimation/useTextMotionAnimation.spec.tsx b/src/hooks/useTextMotionAnimation/useTextMotionAnimation.spec.tsx
index 4c289c8..36bab12 100644
--- a/src/hooks/useTextMotionAnimation/useTextMotionAnimation.spec.tsx
+++ b/src/hooks/useTextMotionAnimation/useTextMotionAnimation.spec.tsx
@@ -4,18 +4,18 @@ import type { Preset, TextMotionProps } from '../../types';
 import { splitReactNode } from '../../utils/splitReactNode';
 import { useAnimateChildren } from '../useAnimateChildren';
 import { useIntersectionObserver } from '../useIntersectionObserver';
-import { useResolvedMotion } from '../useResolvedMotion';
+import { useResolveMotion } from '../useResolveMotion';
 
 import { useTextMotionAnimation } from './useTextMotionAnimation';
 
 jest.mock('../useIntersectionObserver');
-jest.mock('../useResolvedMotion');
+jest.mock('../useResolveMotion');
 jest.mock('../useAnimateChildren');
 jest.mock('../../utils/splitReactNode');
 
 describe('useTextMotionAnimation', () => {
   const mockUseIntersectionObserver = useIntersectionObserver as jest.Mock;
-  const mockUseResolvedMotion = useResolvedMotion as jest.Mock;
+  const mockUseResolvedMotion = useResolveMotion as jest.Mock;
   const mockUseAnimatedChildren = useAnimateChildren as jest.Mock;
   const mockSplitReactNode = splitReactNode as jest.Mock;
 
@@ -55,14 +55,14 @@ describe('useTextMotionAnimation', () => {
     expect(result3.current.shouldAnimate).toBe(false);
   });
 
-  it('should call useResolvedMotion with motion prop', () => {
+  it('should call useResolveMotion with motion prop', () => {
     const motion = { fade: { variant: 'in' as const, duration: 1, delay: 1 } };
     const props = { ...defaultProps, motion };
     renderHook(() => useTextMotionAnimation(props));
     expect(mockUseResolvedMotion).toHaveBeenCalledWith({ motion, preset: undefined });
   });
 
-  it('should call useResolvedMotion with preset prop', () => {
+  it('should call useResolveMotion with preset prop', () => {
     const preset: Preset[] = ['slide-up'];
     const props = { ...defaultProps, preset };
     renderHook(() => useTextMotionAnimation(props));
diff --git a/src/hooks/useTextMotionAnimation/useTextMotionAnimation.ts b/src/hooks/useTextMotionAnimation/useTextMotionAnimation.ts
index 52898f4..0e894f4 100644
--- a/src/hooks/useTextMotionAnimation/useTextMotionAnimation.ts
+++ b/src/hooks/useTextMotionAnimation/useTextMotionAnimation.ts
@@ -4,7 +4,7 @@ import type { TextMotionProps } from '../../types';
 import { splitReactNode } from '../../utils/splitReactNode';
 import { useAnimateChildren } from '../useAnimateChildren';
 import { useIntersectionObserver } from '../useIntersectionObserver';
-import { useResolvedMotion } from '../useResolvedMotion';
+import { useResolveMotion } from '../useResolveMotion';
 
 /**
  * @description
@@ -32,7 +32,7 @@ export const useTextMotionAnimation = (props: TextMotionProps) => {
 
   const { nodes, text } = useMemo(() => splitReactNode(children, split), [children, split]);
 
-  const resolvedMotion = useResolvedMotion({ motion, preset });
+  const resolvedMotion = useResolveMotion({ motion, preset });
 
   const animatedChildren = useAnimateChildren({
     nodes: shouldAnimate ? nodes : [children],

From 66cbadc8d88543ca5bfd1224bad6c22945437143 Mon Sep 17 00:00:00 2001
From: Donghyun Lee <shubug@naver.com>
Date: Sat, 17 Jan 2026 23:42:55 +0900
Subject: [PATCH 4/7] refactor: improve 'useTextMotionController' hook

---
 src/components/TextMotion/TextMotion.spec.tsx | 69 +++++++++----------
 src/components/TextMotion/TextMotion.tsx      | 43 ++++++------
 src/hooks/useController/index.ts              |  1 +
 .../useController.spec.tsx}                   | 32 ++++-----
 src/hooks/useController/useController.ts      | 67 ++++++++++++++++++
 src/hooks/useTextMotionAnimation/index.ts     |  1 -
 .../useTextMotionAnimation.ts                 | 51 --------------
 src/styles/motion.scss                        |  6 +-
 src/utils/splitReactNode/splitReactNode.ts    |  2 +-
 9 files changed, 140 insertions(+), 132 deletions(-)
 create mode 100644 src/hooks/useController/index.ts
 rename src/hooks/{useTextMotionAnimation/useTextMotionAnimation.spec.tsx => useController/useController.spec.tsx} (74%)
 create mode 100644 src/hooks/useController/useController.ts
 delete mode 100644 src/hooks/useTextMotionAnimation/index.ts
 delete mode 100644 src/hooks/useTextMotionAnimation/useTextMotionAnimation.ts

diff --git a/src/components/TextMotion/TextMotion.spec.tsx b/src/components/TextMotion/TextMotion.spec.tsx
index 3fe63d8..ec24e15 100644
--- a/src/components/TextMotion/TextMotion.spec.tsx
+++ b/src/components/TextMotion/TextMotion.spec.tsx
@@ -2,27 +2,26 @@ import { type FC, type ReactNode } from 'react';
 import { render, screen } from '@testing-library/react';
 
 import { DEFAULT_ARIA_LABEL } from '../../constants';
-import * as useTextMotionAnimation from '../../hooks/useTextMotionAnimation';
+import * as useController from '../../hooks/useController';
 
 import { TextMotion } from './TextMotion';
 
-jest.mock('../../hooks/useTextMotionAnimation', () => ({
-  useTextMotionAnimation: jest.fn(() => ({
-    shouldAnimate: false,
+jest.mock('../../hooks/useController', () => ({
+  useController: jest.fn(() => ({
+    canAnimate: false,
     targetRef: { current: null },
     animatedChildren: [],
     text: '',
   })),
 }));
 
-// Helper to drive component scenarios by mocking the hook return
 const MockTextMotion: FC<{
   children: ReactNode;
-  hookReturn?: Partial<ReturnType<typeof useTextMotionAnimation.useTextMotionAnimation>>;
+  hookReturn?: Partial<ReturnType<typeof useController.useController>>;
   onAnimationStart?: () => void;
 }> = ({ children, hookReturn, onAnimationStart }) => {
-  (useTextMotionAnimation.useTextMotionAnimation as unknown as jest.Mock).mockReturnValueOnce({
-    shouldAnimate: false,
+  (useController.useController as unknown as jest.Mock).mockReturnValueOnce({
+    canAnimate: false,
     targetRef: { current: null },
     animatedChildren: [],
     text: typeof children === 'string' ? children : '',
@@ -35,19 +34,17 @@ const MockTextMotion: FC<{
 describe('TextMotion component', () => {
   const TEXT = 'Hello';
   const consoleWarnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
-  const useTextMotionAnimationSpy = jest.spyOn(useTextMotionAnimation, 'useTextMotionAnimation');
+  const useControllerSpy = jest.spyOn(useController, 'useController');
 
   beforeEach(() => {
     consoleWarnSpy.mockClear();
-    useTextMotionAnimationSpy.mockClear();
+    useControllerSpy.mockClear();
   });
 
-  it('should call useTextMotionAnimation with default trigger and repeat', () => {
+  it('should call useController with default trigger and repeat', () => {
     render(<TextMotion trigger="scroll">{TEXT}</TextMotion>);
 
-    expect(useTextMotionAnimationSpy).toHaveBeenCalledWith(
-      expect.objectContaining({ children: 'Hello', trigger: 'scroll' })
-    );
+    expect(useControllerSpy).toHaveBeenCalledWith(expect.objectContaining({ children: 'Hello', trigger: 'scroll' }));
   });
 
   it('should respect the repeat prop when provided', () => {
@@ -57,19 +54,17 @@ describe('TextMotion component', () => {
       </TextMotion>
     );
 
-    expect(useTextMotionAnimationSpy).toHaveBeenCalledWith(
-      expect.objectContaining({ trigger: 'scroll', repeat: false })
-    );
+    expect(useControllerSpy).toHaveBeenCalledWith(expect.objectContaining({ trigger: 'scroll', repeat: false }));
   });
 
-  it('renders spans when shouldAnimate is true (e.g., trigger="on-load")', () => {
+  it('renders spans when canAnimate is true (e.g., trigger="on-load")', () => {
     const animatedChildren = Array.from(TEXT).map((ch, i) => (
       <span key={i} aria-hidden="true">
         {ch}
       </span>
     ));
 
-    render(<MockTextMotion hookReturn={{ shouldAnimate: true, text: TEXT, animatedChildren }}>{TEXT}</MockTextMotion>);
+    render(<MockTextMotion hookReturn={{ canAnimate: true, text: TEXT, animatedChildren }}>{TEXT}</MockTextMotion>);
 
     const container = screen.getByLabelText(TEXT);
     const spans = container.querySelectorAll<HTMLSpanElement>('span[aria-hidden="true"]');
@@ -78,25 +73,25 @@ describe('TextMotion component', () => {
     expect(container).toHaveClass('text-motion');
   });
 
-  it('renders plain text when shouldAnimate is false', () => {
-    render(<MockTextMotion hookReturn={{ shouldAnimate: false, text: TEXT }}>{TEXT}</MockTextMotion>);
+  it('renders plain text when canAnimate is false', () => {
+    render(<MockTextMotion hookReturn={{ canAnimate: false, text: TEXT }}>{TEXT}</MockTextMotion>);
 
     const container = screen.getByText(TEXT);
     const spans = container.querySelectorAll<HTMLSpanElement>('span[aria-hidden="true"]');
 
     expect(container.textContent).toBe(TEXT);
     expect(spans.length).toBe(0);
-    expect(container).toHaveClass('text-motion-inanimate');
+    expect(container).toHaveClass('text-motion-inactive');
   });
 
-  it('renders spans when shouldAnimate is true', () => {
+  it('renders spans when canAnimate is true', () => {
     const animatedChildren = Array.from(TEXT).map((ch, i) => (
       <span key={i} aria-hidden="true">
         {ch}
       </span>
     ));
 
-    render(<MockTextMotion hookReturn={{ shouldAnimate: true, text: TEXT, animatedChildren }}>{TEXT}</MockTextMotion>);
+    render(<MockTextMotion hookReturn={{ canAnimate: true, text: TEXT, animatedChildren }}>{TEXT}</MockTextMotion>);
 
     const container = screen.getByLabelText(TEXT);
     const spans = container.querySelectorAll<HTMLSpanElement>('span[aria-hidden="true"]');
@@ -116,7 +111,7 @@ describe('TextMotion component', () => {
   });
 
   it('uses DEFAULT_ARIA_LABEL when text is empty while animating', () => {
-    render(<MockTextMotion hookReturn={{ shouldAnimate: true, text: '', animatedChildren: [] }}>{''}</MockTextMotion>);
+    render(<MockTextMotion hookReturn={{ canAnimate: true, text: '', animatedChildren: [] }}>{''}</MockTextMotion>);
 
     const container = screen.getByLabelText(DEFAULT_ARIA_LABEL);
     const spans = container.querySelectorAll<HTMLSpanElement>('span[aria-hidden="true"]');
@@ -125,7 +120,7 @@ describe('TextMotion component', () => {
   });
 
   it('explicitly verifies aria-label when animating with empty text', () => {
-    render(<MockTextMotion hookReturn={{ shouldAnimate: true, text: '', animatedChildren: [] }}>{''}</MockTextMotion>);
+    render(<MockTextMotion hookReturn={{ canAnimate: true, text: '', animatedChildren: [] }}>{''}</MockTextMotion>);
     const animatedContainer = screen.getByLabelText(DEFAULT_ARIA_LABEL);
 
     expect(animatedContainer).toBeInTheDocument();
@@ -133,18 +128,18 @@ describe('TextMotion component', () => {
   });
 
   it('uses DEFAULT_ARIA_LABEL when not animating and text is falsy', () => {
-    render(<MockTextMotion hookReturn={{ shouldAnimate: false, text: '' }}>{null}</MockTextMotion>);
+    render(<MockTextMotion hookReturn={{ canAnimate: false, text: '' }}>{null}</MockTextMotion>);
 
     const container = screen.getByLabelText(DEFAULT_ARIA_LABEL);
     expect(container).toBeInTheDocument();
-    expect(container).toHaveClass('text-motion-inanimate');
+    expect(container).toHaveClass('text-motion-inactive');
   });
 
-  it('calls onAnimationStart when shouldAnimate is true', () => {
+  it('calls onAnimationStart when canAnimate is true', () => {
     const onAnimationStart = jest.fn();
 
     render(
-      <MockTextMotion hookReturn={{ shouldAnimate: true, text: TEXT }} onAnimationStart={onAnimationStart}>
+      <MockTextMotion hookReturn={{ canAnimate: true, text: TEXT }} onAnimationStart={onAnimationStart}>
         {TEXT}
       </MockTextMotion>
     );
@@ -152,11 +147,11 @@ describe('TextMotion component', () => {
     expect(onAnimationStart).toHaveBeenCalledTimes(1);
   });
 
-  it('does not call onAnimationStart when shouldAnimate is false', () => {
+  it('does not call onAnimationStart when canAnimate is false', () => {
     const onAnimationStart = jest.fn();
 
     render(
-      <MockTextMotion hookReturn={{ shouldAnimate: false, text: TEXT }} onAnimationStart={onAnimationStart}>
+      <MockTextMotion hookReturn={{ canAnimate: false, text: TEXT }} onAnimationStart={onAnimationStart}>
         {TEXT}
       </MockTextMotion>
     );
@@ -164,11 +159,11 @@ describe('TextMotion component', () => {
     expect(onAnimationStart).not.toHaveBeenCalled();
   });
 
-  it('calls onAnimationStart when shouldAnimate is true (e.g., intersecting)', () => {
+  it('calls onAnimationStart when canAnimate is true (e.g., intersecting)', () => {
     const onAnimationStart = jest.fn();
 
     render(
-      <MockTextMotion hookReturn={{ shouldAnimate: true, text: TEXT }} onAnimationStart={onAnimationStart}>
+      <MockTextMotion hookReturn={{ canAnimate: true, text: TEXT }} onAnimationStart={onAnimationStart}>
         {TEXT}
       </MockTextMotion>
     );
@@ -185,7 +180,7 @@ describe('TextMotion with different split options (component-level via hook mock
       </span>
     ));
 
-    render(<MockTextMotion hookReturn={{ shouldAnimate: true, text: 'Hi', animatedChildren }}>Hi</MockTextMotion>);
+    render(<MockTextMotion hookReturn={{ canAnimate: true, text: 'Hi', animatedChildren }}>Hi</MockTextMotion>);
 
     const container = screen.getByLabelText('Hi');
     const spans = container.querySelectorAll<HTMLSpanElement>('span[aria-hidden="true"]');
@@ -203,7 +198,7 @@ describe('TextMotion with different split options (component-level via hook mock
     ));
 
     render(
-      <MockTextMotion hookReturn={{ shouldAnimate: true, text: 'Hello World', animatedChildren }}>
+      <MockTextMotion hookReturn={{ canAnimate: true, text: 'Hello World', animatedChildren }}>
         Hello World
       </MockTextMotion>
     );
@@ -247,7 +242,7 @@ describe('TextMotion with different split options (component-level via hook mock
     ));
 
     render(
-      <MockTextMotion hookReturn={{ shouldAnimate: true, text: 'Hello World!', animatedChildren }}>
+      <MockTextMotion hookReturn={{ canAnimate: true, text: 'Hello World!', animatedChildren }}>
         Hello <strong>World</strong>!
       </MockTextMotion>
     );
diff --git a/src/components/TextMotion/TextMotion.tsx b/src/components/TextMotion/TextMotion.tsx
index eb6d2ea..61d084a 100644
--- a/src/components/TextMotion/TextMotion.tsx
+++ b/src/components/TextMotion/TextMotion.tsx
@@ -4,7 +4,7 @@ import '../../styles/motion.scss';
 import { type FC, memo, useEffect, useRef } from 'react';
 
 import { DEFAULT_ARIA_LABEL } from '../../constants';
-import { useTextMotionAnimation } from '../../hooks/useTextMotionAnimation';
+import { useController } from '../../hooks/useController';
 import { useValidation } from '../../hooks/useValidation';
 import type { TextMotionProps } from '../../types';
 import { getAriaLabel } from '../../utils/accessibility';
@@ -69,40 +69,39 @@ import { getAriaLabel } from '../../utils/accessibility';
  * }
  */
 export const TextMotion: FC<TextMotionProps> = memo(props => {
-  const { as: Tag = 'span', children, onAnimationStart } = props;
+  const { as: Component = 'span', children, onAnimationStart } = props;
+
   useValidation({ componentName: 'TextMotion', props });
 
-  const { shouldAnimate, targetRef, animatedChildren, text } = useTextMotionAnimation(props);
+  const { canAnimate, targetRef, animatedChildren, text } = useController(props);
 
-  const onAnimationStartRef = useRef(onAnimationStart);
+  const animationStartCallbackRef = useRef(onAnimationStart);
 
   useEffect(() => {
-    onAnimationStartRef.current = onAnimationStart;
+    animationStartCallbackRef.current = onAnimationStart;
   }, [onAnimationStart]);
 
+  // Trigger animation start callback when animation becomes active.
   useEffect(() => {
-    if (shouldAnimate) {
-      onAnimationStartRef.current?.();
-    }
-  }, [shouldAnimate]);
+    if (!canAnimate) return;
+    animationStartCallbackRef.current?.();
+  }, [canAnimate]);
 
-  if (!shouldAnimate) {
-    const ariaProps = getAriaLabel(text || DEFAULT_ARIA_LABEL);
+  const ariaProps = getAriaLabel(text || DEFAULT_ARIA_LABEL);
 
+  if (!canAnimate) {
     return (
-      <Tag ref={targetRef} className="text-motion-inanimate" {...ariaProps}>
+      <Component ref={targetRef} className="text-motion-inactive" {...ariaProps}>
         {children}
-      </Tag>
+      </Component>
     );
   }
 
-  return (() => {
-    const ariaProps = getAriaLabel(text || DEFAULT_ARIA_LABEL);
-
-    return (
-      <Tag ref={targetRef} className="text-motion" {...ariaProps}>
-        {animatedChildren}
-      </Tag>
-    );
-  })();
+  return (
+    <Component ref={targetRef} className="text-motion" {...ariaProps}>
+      {animatedChildren}
+    </Component>
+  );
 });
+
+TextMotion.displayName = 'TextMotion';
diff --git a/src/hooks/useController/index.ts b/src/hooks/useController/index.ts
new file mode 100644
index 0000000..1d4af79
--- /dev/null
+++ b/src/hooks/useController/index.ts
@@ -0,0 +1 @@
+export { useController } from './useController';
diff --git a/src/hooks/useTextMotionAnimation/useTextMotionAnimation.spec.tsx b/src/hooks/useController/useController.spec.tsx
similarity index 74%
rename from src/hooks/useTextMotionAnimation/useTextMotionAnimation.spec.tsx
rename to src/hooks/useController/useController.spec.tsx
index 36bab12..488d32a 100644
--- a/src/hooks/useTextMotionAnimation/useTextMotionAnimation.spec.tsx
+++ b/src/hooks/useController/useController.spec.tsx
@@ -6,14 +6,14 @@ import { useAnimateChildren } from '../useAnimateChildren';
 import { useIntersectionObserver } from '../useIntersectionObserver';
 import { useResolveMotion } from '../useResolveMotion';
 
-import { useTextMotionAnimation } from './useTextMotionAnimation';
+import { useController } from './useController';
 
 jest.mock('../useIntersectionObserver');
 jest.mock('../useResolveMotion');
 jest.mock('../useAnimateChildren');
 jest.mock('../../utils/splitReactNode');
 
-describe('useTextMotionAnimation', () => {
+describe('useController', () => {
   const mockUseIntersectionObserver = useIntersectionObserver as jest.Mock;
   const mockUseResolvedMotion = useResolveMotion as jest.Mock;
   const mockUseAnimatedChildren = useAnimateChildren as jest.Mock;
@@ -35,43 +35,43 @@ describe('useTextMotionAnimation', () => {
   });
 
   it('should call splitReactNode with children and split type', () => {
-    renderHook(() => useTextMotionAnimation({ ...defaultProps, split: 'word' }));
+    renderHook(() => useController({ ...defaultProps, split: 'word' }));
     expect(mockSplitReactNode).toHaveBeenCalledWith('Hello', 'word');
   });
 
-  it('should determine shouldAnimate based on trigger and intersection', () => {
+  it('should determine canAnimate based on trigger and intersection', () => {
     // trigger="on-load"
-    const { result: result1 } = renderHook(() => useTextMotionAnimation({ ...defaultProps, trigger: 'on-load' }));
-    expect(result1.current.shouldAnimate).toBe(true);
+    const { result: result1 } = renderHook(() => useController({ ...defaultProps, trigger: 'on-load' }));
+    expect(result1.current.canAnimate).toBe(true);
 
     // trigger="scroll" and is intersecting
     mockUseIntersectionObserver.mockReturnValue([null, true]);
-    const { result: result2 } = renderHook(() => useTextMotionAnimation({ ...defaultProps, trigger: 'scroll' }));
-    expect(result2.current.shouldAnimate).toBe(true);
+    const { result: result2 } = renderHook(() => useController({ ...defaultProps, trigger: 'scroll' }));
+    expect(result2.current.canAnimate).toBe(true);
 
     // trigger="scroll" and is not intersecting
     mockUseIntersectionObserver.mockReturnValue([null, false]);
-    const { result: result3 } = renderHook(() => useTextMotionAnimation({ ...defaultProps, trigger: 'scroll' }));
-    expect(result3.current.shouldAnimate).toBe(false);
+    const { result: result3 } = renderHook(() => useController({ ...defaultProps, trigger: 'scroll' }));
+    expect(result3.current.canAnimate).toBe(false);
   });
 
   it('should call useResolveMotion with motion prop', () => {
     const motion = { fade: { variant: 'in' as const, duration: 1, delay: 1 } };
     const props = { ...defaultProps, motion };
-    renderHook(() => useTextMotionAnimation(props));
+    renderHook(() => useController(props));
     expect(mockUseResolvedMotion).toHaveBeenCalledWith({ motion, preset: undefined });
   });
 
   it('should call useResolveMotion with preset prop', () => {
     const preset: Preset[] = ['slide-up'];
     const props = { ...defaultProps, preset };
-    renderHook(() => useTextMotionAnimation(props));
+    renderHook(() => useController(props));
     expect(mockUseResolvedMotion).toHaveBeenCalledWith({ motion: undefined, preset });
   });
 
   it('should call useAnimateChildren with correct props when animating', () => {
     const props = { ...defaultProps, initialDelay: 1, animationOrder: 'last-to-first' as const };
-    renderHook(() => useTextMotionAnimation(props));
+    renderHook(() => useController(props));
 
     expect(mockUseAnimatedChildren).toHaveBeenCalledWith({
       nodes: ['H', 'e', 'l', 'l', 'o'],
@@ -85,7 +85,7 @@ describe('useTextMotionAnimation', () => {
   it('should call useAnimateChildren with original children when not animating', () => {
     mockUseIntersectionObserver.mockReturnValue([null, false]);
     const props = { ...defaultProps, trigger: 'scroll' as const };
-    renderHook(() => useTextMotionAnimation(props));
+    renderHook(() => useController(props));
 
     expect(mockUseAnimatedChildren).toHaveBeenCalledWith(
       expect.objectContaining({
@@ -99,9 +99,9 @@ describe('useTextMotionAnimation', () => {
     mockSplitReactNode.mockReturnValue({ nodes: ['Test'], text: 'Test' });
     mockUseAnimatedChildren.mockReturnValue(['Animated Test']);
 
-    const { result } = renderHook(() => useTextMotionAnimation(defaultProps));
+    const { result } = renderHook(() => useController(defaultProps));
 
-    expect(result.current.shouldAnimate).toBe(true);
+    expect(result.current.canAnimate).toBe(true);
     expect(result.current.targetRef).toBe('ref');
     expect(result.current.animatedChildren).toEqual(['Animated Test']);
     expect(result.current.text).toBe('Test');
diff --git a/src/hooks/useController/useController.ts b/src/hooks/useController/useController.ts
new file mode 100644
index 0000000..e13faed
--- /dev/null
+++ b/src/hooks/useController/useController.ts
@@ -0,0 +1,67 @@
+import { type ReactNode, type RefCallback, useMemo } from 'react';
+
+import type { TextMotionProps } from '../../types';
+import { splitReactNode } from '../../utils/splitReactNode';
+import { useAnimateChildren } from '../useAnimateChildren';
+import { useIntersectionObserver } from '../useIntersectionObserver';
+import { useResolveMotion } from '../useResolveMotion';
+
+type UseControllerResult = {
+  canAnimate: boolean;
+  targetRef: RefCallback<Element | null>;
+  animatedChildren: ReactNode[];
+  text: string;
+};
+
+/**
+ * @description
+ * `useController` orchestrates the full animation flow for TextMotion.
+ *
+ * Responsibilities:
+ * - Determines whether animation should run based on trigger strategy
+ * - Splits ReactNode children into animatable units
+ * - Resolves motion configuration (preset + custom)
+ * - Delegates animation rendering to `useAnimateChildren`
+ *
+ * @param {TextMotionProps} props - Props passed from the TextMotion component
+ * @returns {UseControllerResult}
+ */
+export const useController = (props: TextMotionProps): UseControllerResult => {
+  const {
+    children,
+    split = 'character',
+    trigger = 'scroll',
+    repeat = true,
+    initialDelay = 0,
+    animationOrder = 'first-to-last',
+    motion,
+    preset,
+    onAnimationEnd,
+  } = props;
+
+  const [targetRef, isIntersecting] = useIntersectionObserver({ repeat });
+
+  const isScrollTriggered = trigger === 'scroll';
+  const canAnimate = !isScrollTriggered || isIntersecting;
+
+  const { nodes: splitNodes, text } = useMemo(() => splitReactNode(children, split), [children, split]);
+
+  const resolvedMotion = useResolveMotion({ motion, preset });
+
+  const animationNodes = canAnimate ? splitNodes : [children];
+
+  const animatedChildren = useAnimateChildren({
+    nodes: animationNodes,
+    initialDelay,
+    animationOrder,
+    motion: resolvedMotion,
+    onAnimationEnd,
+  });
+
+  return {
+    canAnimate,
+    targetRef,
+    animatedChildren,
+    text,
+  };
+};
diff --git a/src/hooks/useTextMotionAnimation/index.ts b/src/hooks/useTextMotionAnimation/index.ts
deleted file mode 100644
index 356f4c7..0000000
--- a/src/hooks/useTextMotionAnimation/index.ts
+++ /dev/null
@@ -1 +0,0 @@
-export { useTextMotionAnimation } from './useTextMotionAnimation';
diff --git a/src/hooks/useTextMotionAnimation/useTextMotionAnimation.ts b/src/hooks/useTextMotionAnimation/useTextMotionAnimation.ts
deleted file mode 100644
index 0e894f4..0000000
--- a/src/hooks/useTextMotionAnimation/useTextMotionAnimation.ts
+++ /dev/null
@@ -1,51 +0,0 @@
-import { useMemo } from 'react';
-
-import type { TextMotionProps } from '../../types';
-import { splitReactNode } from '../../utils/splitReactNode';
-import { useAnimateChildren } from '../useAnimateChildren';
-import { useIntersectionObserver } from '../useIntersectionObserver';
-import { useResolveMotion } from '../useResolveMotion';
-
-/**
- * @description
- * `useTextMotionAnimation` is a custom hook that animates the children of the TextMotion component.
- * It returns the animated children, the target reference, and the text.
- *
- * @param {TextMotionProps} props - The props of the TextMotion component.
- * @returns {Object} An object containing the animated children, the target reference, and the text.
- */
-export const useTextMotionAnimation = (props: TextMotionProps) => {
-  const {
-    children,
-    split = 'character',
-    trigger = 'scroll',
-    repeat = true,
-    initialDelay = 0,
-    animationOrder = 'first-to-last',
-    motion,
-    preset,
-    onAnimationEnd,
-  } = props;
-
-  const [targetRef, isIntersecting] = useIntersectionObserver({ repeat });
-  const shouldAnimate = trigger === 'on-load' || isIntersecting;
-
-  const { nodes, text } = useMemo(() => splitReactNode(children, split), [children, split]);
-
-  const resolvedMotion = useResolveMotion({ motion, preset });
-
-  const animatedChildren = useAnimateChildren({
-    nodes: shouldAnimate ? nodes : [children],
-    initialDelay,
-    animationOrder,
-    motion: resolvedMotion,
-    onAnimationEnd,
-  });
-
-  return {
-    shouldAnimate,
-    targetRef,
-    animatedChildren,
-    text,
-  };
-};
diff --git a/src/styles/motion.scss b/src/styles/motion.scss
index 620a267..6a6c9c5 100644
--- a/src/styles/motion.scss
+++ b/src/styles/motion.scss
@@ -1,10 +1,8 @@
-.text-motion span,
-.node-motion span {
+.text-motion span {
   display: inline-block;
   white-space: pre;
 }
 
-.text-motion-inanimate,
-.node-motion-inanimate {
+.text-motion-inactive {
   visibility: hidden;
 }
diff --git a/src/utils/splitReactNode/splitReactNode.ts b/src/utils/splitReactNode/splitReactNode.ts
index 0a84518..5d5f9dc 100644
--- a/src/utils/splitReactNode/splitReactNode.ts
+++ b/src/utils/splitReactNode/splitReactNode.ts
@@ -2,7 +2,7 @@ import { cloneElement, type ReactNode } from 'react';
 
 import type { Split } from '../../types';
 import { splitText } from '../splitText';
-import { isElementWithChildren, isNonRenderableNode, isTextNode } from '../typeGuards/typeGuards';
+import { isElementWithChildren, isNonRenderableNode, isTextNode } from '../typeGuards';
 
 type SplitResult = {
   nodes: ReactNode[];

From b638c07144bcdee16aba15667dc2be9ad94d754d Mon Sep 17 00:00:00 2001
From: Donghyun Lee <shubug@naver.com>
Date: Sun, 18 Jan 2026 15:25:52 +0900
Subject: [PATCH 5/7] refactor: improve 'useValidation' hook

---
 src/components/TextMotion/TextMotion.tsx      |   4 +-
 .../useValidation/useValidation.spec.tsx      |  99 ++++---------
 src/hooks/useValidation/useValidation.ts      |  38 +----
 .../useValidation/validateProps.spec.tsx      | 140 ++++++++++++++++++
 src/hooks/useValidation/validateProps.ts      |  97 ++++++++++++
 src/hooks/useValidation/validation.spec.tsx   | 137 -----------------
 src/hooks/useValidation/validation.ts         | 129 ----------------
 7 files changed, 278 insertions(+), 366 deletions(-)
 create mode 100644 src/hooks/useValidation/validateProps.spec.tsx
 create mode 100644 src/hooks/useValidation/validateProps.ts
 delete mode 100644 src/hooks/useValidation/validation.spec.tsx
 delete mode 100644 src/hooks/useValidation/validation.ts

diff --git a/src/components/TextMotion/TextMotion.tsx b/src/components/TextMotion/TextMotion.tsx
index 61d084a..d5b23ea 100644
--- a/src/components/TextMotion/TextMotion.tsx
+++ b/src/components/TextMotion/TextMotion.tsx
@@ -71,7 +71,7 @@ import { getAriaLabel } from '../../utils/accessibility';
 export const TextMotion: FC<TextMotionProps> = memo(props => {
   const { as: Component = 'span', children, onAnimationStart } = props;
 
-  useValidation({ componentName: 'TextMotion', props });
+  useValidation(props);
 
   const { canAnimate, targetRef, animatedChildren, text } = useController(props);
 
@@ -81,7 +81,7 @@ export const TextMotion: FC<TextMotionProps> = memo(props => {
     animationStartCallbackRef.current = onAnimationStart;
   }, [onAnimationStart]);
 
-  // Trigger animation start callback when animation becomes active.
+  // Trigger animation start callback when animation becomes active
   useEffect(() => {
     if (!canAnimate) return;
     animationStartCallbackRef.current?.();
diff --git a/src/hooks/useValidation/useValidation.spec.tsx b/src/hooks/useValidation/useValidation.spec.tsx
index f87a556..2805481 100644
--- a/src/hooks/useValidation/useValidation.spec.tsx
+++ b/src/hooks/useValidation/useValidation.spec.tsx
@@ -2,106 +2,69 @@ import { render } from '@testing-library/react';
 
 import type { TextMotionProps } from '../../types';
 
-import { handleValidation, useValidation } from './useValidation';
+import { useValidation } from './useValidation';
 
-describe('useValidation hook', () => {
-  const TestComponent = ({ props }: { props: any }) => {
-    useValidation({ componentName: 'TextMotion', props });
+describe('useValidation (TextMotion)', () => {
+  const ORIGINAL_ENV = process.env.NODE_ENV;
+
+  beforeEach(() => {
+    process.env.NODE_ENV = 'development';
+  });
 
+  afterEach(() => {
+    process.env.NODE_ENV = ORIGINAL_ENV;
+    jest.restoreAllMocks();
+  });
+
+  const TestComponent = ({ props }: { props: TextMotionProps }) => {
+    useValidation(props);
     return <div>Test</div>;
   };
 
-  it('should throw an error for invalid TextMotionProps', () => {
-    const props: Partial<TextMotionProps> = {
-      split: 'invalid-split' as any,
-    };
+  it('throws an error and logs when props are invalid (dev)', () => {
+    const props = {
+      split: 'invalid' as any,
+    } as TextMotionProps;
 
     const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
 
-    expect(() => render(<TestComponent props={props} />)).toThrow();
-
-    expect(consoleErrorSpy).toHaveBeenCalledWith(
-      'TextMotion validation errors:',
-      expect.arrayContaining(['split prop must be one of: character, word'])
-    );
+    expect(() => render(<TestComponent props={props} />)).toThrow(/TextMotion:/);
 
-    consoleErrorSpy.mockRestore();
+    expect(consoleErrorSpy).toHaveBeenCalled();
   });
 
-  it('should not throw for valid TextMotionProps', () => {
+  it('does not throw for valid props (dev)', () => {
     const props: TextMotionProps = {
-      children: <span>Hello</span>,
+      children: 'Hello',
       split: 'word',
       trigger: 'on-load',
       repeat: true,
       initialDelay: 0,
       animationOrder: 'first-to-last',
-      motion: undefined,
     };
 
     expect(() => render(<TestComponent props={props} />)).not.toThrow();
   });
-});
-
-describe('handleValidation', () => {
-  const ORIGINAL_ENV = process.env.NODE_ENV;
-
-  afterEach(() => {
-    jest.restoreAllMocks();
-    process.env.NODE_ENV = ORIGINAL_ENV;
-  });
-
-  it('should throw an error when errors are present in non-production', () => {
-    process.env.NODE_ENV = 'development';
-
-    const errors: string[] = ['some validation error'];
-    const warnings: string[] = [];
-
-    const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
-
-    expect(() => handleValidation('TextMotion', errors, warnings)).toThrow('TextMotion: some validation error');
-    expect(consoleErrorSpy).toHaveBeenCalledWith('TextMotion validation errors:', errors);
-  });
 
-  it('should log warnings when only warnings are present in non-production', () => {
-    process.env.NODE_ENV = 'development';
-
-    const errors: string[] = [];
-    const warnings: string[] = ['some validation warning'];
+  it('logs warnings but does not throw when only warnings exist', () => {
+    const props = {} as TextMotionProps;
 
     const consoleWarnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
 
-    handleValidation('TextMotion', errors, warnings);
-
-    expect(consoleWarnSpy).toHaveBeenCalledWith('TextMotion validation warnings:', warnings);
-  });
-
-  it('should not log anything when no errors or warnings in non-production', () => {
-    process.env.NODE_ENV = 'development';
-
-    const errors: string[] = [];
-    const warnings: string[] = [];
-
-    const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
-    const consoleWarnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
-
-    handleValidation('TextMotion', errors, warnings);
-
-    expect(consoleErrorSpy).not.toHaveBeenCalled();
-    expect(consoleWarnSpy).not.toHaveBeenCalled();
+    expect(() => render(<TestComponent props={props} />)).not.toThrow();
+    expect(consoleWarnSpy).toHaveBeenCalled();
   });
 
-  it('should not throw or log in production', () => {
+  it('does nothing in production environment', () => {
     process.env.NODE_ENV = 'production';
 
-    const errors: string[] = ['some validation error'];
-    const warnings: string[] = ['some validation warning'];
+    const props = {
+      split: 'invalid' as any,
+    } as TextMotionProps;
 
     const consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
-    const consoleWarnSpy = jest.spyOn(console, 'warn').mockImplementation(() => {});
 
-    expect(() => handleValidation('TextMotion', errors, warnings)).not.toThrow();
+    expect(() => render(<TestComponent props={props} />)).not.toThrow();
     expect(consoleErrorSpy).not.toHaveBeenCalled();
-    expect(consoleWarnSpy).not.toHaveBeenCalled();
   });
 });
diff --git a/src/hooks/useValidation/useValidation.ts b/src/hooks/useValidation/useValidation.ts
index 8b182af..07a3e91 100644
--- a/src/hooks/useValidation/useValidation.ts
+++ b/src/hooks/useValidation/useValidation.ts
@@ -2,50 +2,28 @@ import { useEffect } from 'react';
 
 import type { TextMotionProps } from '../../types';
 
-import { validateTextMotionProps } from './validation';
-
-type UseValidationProps = {
-  componentName: 'TextMotion';
-  props: TextMotionProps;
-};
+import { validateProps } from './validateProps';
 
 /**
  * @description
  * Validates the props of the TextMotion component.
  * It checks for required props, invalid values, and logs warnings or throws errors in non-production environments.
  *
- * @param {'TextMotion'} componentName - The name of the component to validate.
  * @param {TextMotionProps} props - The props to validate.
  */
-export const useValidation = ({ componentName, props }: UseValidationProps) => {
+export const useValidation = (props: TextMotionProps) => {
   useEffect(() => {
-    const { errors, warnings } = validateTextMotionProps(props);
+    if (process.env.NODE_ENV === 'production') return;
 
-    if (errors.length > 0 || warnings.length > 0) {
-      handleValidation(componentName, errors, warnings);
-    }
-  }, [componentName, props]);
-};
+    const { errors, warnings } = validateProps(props);
 
-/**
- * @description
- * Handles validation errors and warnings by logging them to the console.
- * In a non-production environment, it will throw an error if there are any validation errors.
- *
- * @param {string} componentName - The name of the component being validated.
- * @param {string[]} errors - A list of validation error messages.
- * @param {string[]} warnings - A list of validation warning messages.
- */
-export const handleValidation = (componentName: string, errors: string[], warnings: string[]) => {
-  if (process.env.NODE_ENV !== 'production') {
     if (errors.length > 0) {
-      console.error(`${componentName} validation errors:`, errors);
-
-      throw new Error(`${componentName}: ${errors.join(', ')}`);
+      console.error('TextMotion validation errors:', errors);
+      throw new Error(`TextMotion: ${errors.join(' ')}`);
     }
 
     if (warnings.length > 0) {
-      console.warn(`${componentName} validation warnings:`, warnings);
+      console.warn('TextMotion validation warnings:', warnings);
     }
-  }
+  }, [props]);
 };
diff --git a/src/hooks/useValidation/validateProps.spec.tsx b/src/hooks/useValidation/validateProps.spec.tsx
new file mode 100644
index 0000000..e9999fc
--- /dev/null
+++ b/src/hooks/useValidation/validateProps.spec.tsx
@@ -0,0 +1,140 @@
+import type { TextMotionProps } from '../../types';
+
+import { validateProps } from './validateProps';
+
+describe('validateProps (TextMotion)', () => {
+  it('returns no errors or warnings for valid props', () => {
+    const props: TextMotionProps = {
+      children: 'Hello World',
+      split: 'word',
+      trigger: 'scroll',
+      repeat: false,
+      initialDelay: 0,
+      animationOrder: 'last-to-first',
+      motion: {
+        custom: { name: 'custom-animation', duration: 1, delay: 0 },
+      },
+    };
+
+    const result = validateProps(props);
+
+    expect(result.errors).toHaveLength(0);
+    expect(result.warnings).toHaveLength(0);
+  });
+
+  it('warns when children is empty', () => {
+    const result = validateProps({} as TextMotionProps);
+
+    expect(result.warnings).toContain('children prop is empty.');
+  });
+
+  it('accepts all valid split values', () => {
+    (['character', 'word'] as const).forEach(split => {
+      const result = validateProps({ children: 'text', split });
+
+      expect(result.errors).toHaveLength(0);
+    });
+  });
+
+  it('handles undefined or null motion configs safely', () => {
+    const props: TextMotionProps = {
+      children: 'text',
+      motion: {
+        custom: undefined,
+      },
+    };
+
+    const result = validateProps(props);
+
+    expect(result.errors).toHaveLength(0);
+    expect(result.warnings).toHaveLength(0);
+  });
+
+  it('collects motion errors and warnings together', () => {
+    const props: TextMotionProps = {
+      children: 'text',
+      motion: {
+        fade: { variant: 'in', duration: 0, delay: -2 },
+        slide: { variant: 'up', duration: 20, delay: 0 },
+      },
+    };
+
+    const { errors, warnings } = validateProps(props);
+
+    expect(errors).toHaveLength(2);
+    expect(errors.some(e => e.includes('fade.duration'))).toBe(true);
+    expect(errors.some(e => e.includes('fade.delay'))).toBe(true);
+
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]).toContain('slide.duration is very long');
+  });
+
+  it('errors on invalid trigger', () => {
+    const props = { children: 'test', trigger: 'invalid' as any };
+
+    const { errors } = validateProps(props as TextMotionProps);
+
+    expect(errors.some(e => e.includes('trigger must be one of'))).toBe(true);
+  });
+
+  it('errors on invalid repeat type', () => {
+    const props = { children: 'test', repeat: 'nope' as any };
+
+    const { errors } = validateProps(props as TextMotionProps);
+
+    expect(errors).toContain('repeat must be a boolean.');
+  });
+
+  it('errors on negative initialDelay', () => {
+    const props = { children: 'test', initialDelay: -1 };
+
+    const { errors } = validateProps(props as TextMotionProps);
+
+    expect(errors).toContain('initialDelay must be greater than or equal to 0.');
+  });
+
+  it('errors on invalid animationOrder', () => {
+    const props = { children: 'test', animationOrder: 'invalid' as any };
+
+    const { errors } = validateProps(props as TextMotionProps);
+
+    expect(errors.some(e => e.includes('animationOrder must be one of'))).toBe(true);
+  });
+
+  it('errors when preset is not an array', () => {
+    const props = { children: 'test', preset: 'invalid' as any };
+
+    const { errors } = validateProps(props as TextMotionProps);
+
+    expect(errors).toContain('preset must be an array.');
+  });
+
+  it('errors when onAnimationStart is not a function', () => {
+    const props = { children: 'test', onAnimationStart: 'nope' as any };
+
+    const { errors } = validateProps(props as TextMotionProps);
+
+    expect(errors).toContain('onAnimationStart must be a function.');
+  });
+
+  it('errors when onAnimationEnd is not a function', () => {
+    const props = { children: 'test', onAnimationEnd: 'nope' as any };
+
+    const { errors } = validateProps(props as TextMotionProps);
+
+    expect(errors).toContain('onAnimationEnd must be a function.');
+  });
+
+  it('errors when custom.name is empty', () => {
+    const props: TextMotionProps = {
+      children: 'test',
+      motion: {
+        custom: { name: '', duration: 1, delay: 0 },
+      },
+    };
+
+    const { errors } = validateProps(props);
+
+    expect(errors).toContain('custom.name must be a non-empty string.');
+  });
+});
diff --git a/src/hooks/useValidation/validateProps.ts b/src/hooks/useValidation/validateProps.ts
new file mode 100644
index 0000000..3cfe404
--- /dev/null
+++ b/src/hooks/useValidation/validateProps.ts
@@ -0,0 +1,97 @@
+import type { CustomAnimation, Motion, TextMotionProps } from '../../types';
+
+export type ValidationResult = {
+  errors: string[];
+  warnings: string[];
+};
+
+const ALLOWED_SPLITS = ['character', 'word'] as const;
+const ALLOWED_TRIGGERS = ['on-load', 'scroll'] as const;
+const ALLOWED_ANIMATION_ORDERS = ['first-to-last', 'last-to-first'] as const;
+
+const MAX_RECOMMENDED_DURATION = 10;
+
+/**
+ * @description
+ * Validates props for the TextMotion component.
+ * This utility is intentionally scoped to TextMotion only.
+ */
+export const validateProps = (props: TextMotionProps): ValidationResult => {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  if (props.children === undefined || props.children === null) {
+    warnings.push('children prop is empty.');
+  }
+
+  if (props.split && !ALLOWED_SPLITS.includes(props.split)) {
+    errors.push(`split must be one of: ${ALLOWED_SPLITS.join(', ')}`);
+  }
+
+  if (props.trigger && !ALLOWED_TRIGGERS.includes(props.trigger)) {
+    errors.push(`trigger must be one of: ${ALLOWED_TRIGGERS.join(', ')}`);
+  }
+
+  if (props.repeat !== undefined && typeof props.repeat !== 'boolean') {
+    errors.push('repeat must be a boolean.');
+  }
+
+  if (props.initialDelay !== undefined && props.initialDelay < 0) {
+    errors.push('initialDelay must be greater than or equal to 0.');
+  }
+
+  if (props.animationOrder && !ALLOWED_ANIMATION_ORDERS.includes(props.animationOrder)) {
+    errors.push(`animationOrder must be one of: ${ALLOWED_ANIMATION_ORDERS.join(', ')}`);
+  }
+
+  if (props.motion) {
+    const motionResult = validateMotionProps(props.motion);
+    errors.push(...motionResult.errors);
+    warnings.push(...motionResult.warnings);
+  }
+
+  if (props.preset && !Array.isArray(props.preset)) {
+    errors.push('preset must be an array.');
+  }
+
+  if (props.onAnimationStart && typeof props.onAnimationStart !== 'function') {
+    errors.push('onAnimationStart must be a function.');
+  }
+
+  if (props.onAnimationEnd && typeof props.onAnimationEnd !== 'function') {
+    errors.push('onAnimationEnd must be a function.');
+  }
+
+  return { errors, warnings };
+};
+
+const validateMotionProps = (motion: Motion): ValidationResult => {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  Object.entries(motion).forEach(([key, config]) => {
+    if (config === undefined || config === null) return;
+
+    if (config.duration <= 0) {
+      errors.push(`${key}.duration must be greater than 0.`);
+    }
+
+    if (config.delay < 0) {
+      errors.push(`${key}.delay must be greater than or equal to 0.`);
+    }
+
+    if (config.duration > MAX_RECOMMENDED_DURATION) {
+      warnings.push(`${key}.duration is very long (${config.duration}s).`);
+    }
+
+    if (key === 'custom') {
+      const custom = config as CustomAnimation;
+
+      if (!custom.name || typeof custom.name !== 'string') {
+        errors.push('custom.name must be a non-empty string.');
+      }
+    }
+  });
+
+  return { errors, warnings };
+};
diff --git a/src/hooks/useValidation/validation.spec.tsx b/src/hooks/useValidation/validation.spec.tsx
deleted file mode 100644
index ccf8ed0..0000000
--- a/src/hooks/useValidation/validation.spec.tsx
+++ /dev/null
@@ -1,137 +0,0 @@
-import type { TextMotionProps } from '../../types';
-
-import { validateTextMotionProps } from './validation';
-
-describe('validation utility', () => {
-  describe('validateTextMotionProps', () => {
-    it('should return no errors or warnings for valid props', () => {
-      const props: TextMotionProps = {
-        children: 'Hello World',
-        split: 'word',
-        trigger: 'scroll',
-        repeat: false,
-        initialDelay: 0,
-        animationOrder: 'last-to-first',
-        motion: { custom: { name: 'custom-animation', duration: 1, delay: 0 } },
-      };
-      const { errors, warnings } = validateTextMotionProps(props);
-
-      expect(errors).toHaveLength(0);
-      expect(warnings).toHaveLength(0);
-    });
-
-    it('should return a warning if children prop is empty', () => {
-      const props = {} as TextMotionProps;
-      const { warnings } = validateTextMotionProps(props);
-
-      expect(warnings).toContain('children prop is empty');
-    });
-
-    // it('should return a warning for "line" split with non-string children', () => {
-    //   const props: TextMotionProps = {
-    //     children: [<div key="1" />],
-    //     split: 'line',
-    //   };
-    //   const { warnings } = validateTextMotionProps(props);
-
-    //   expect(warnings).toContain('split="line" is only applicable when children is a string.');
-    // });
-
-    it('should accept valid split values', () => {
-      (['character', 'word'] as const).forEach(split => {
-        const props: TextMotionProps = { children: 'hello', split };
-        const { errors } = validateTextMotionProps(props);
-
-        expect(errors).toHaveLength(0);
-      });
-    });
-
-    it('should handle null or undefined motion config values', () => {
-      const props: TextMotionProps = {
-        children: 'hello',
-        motion: {
-          custom: undefined,
-        },
-      };
-      const { errors, warnings } = validateTextMotionProps(props);
-
-      expect(errors).toHaveLength(0);
-      expect(warnings).toHaveLength(0);
-    });
-
-    it('should validate motion config errors and warnings together', () => {
-      const props: TextMotionProps = {
-        children: 'hello',
-        motion: {
-          fade: { variant: 'in', duration: 0, delay: -2 },
-          slide: { variant: 'up', duration: 20, delay: 0 },
-        },
-      };
-      const { errors, warnings } = validateTextMotionProps(props);
-
-      expect(errors).toEqual(['fade.duration must be greater than 0', 'fade.delay must be non-negative']);
-      expect(warnings).toEqual(['slide.duration is very long (20s)']);
-    });
-  });
-
-  describe('validateCommonProps', () => {
-    it('should return an error for invalid trigger', () => {
-      const props: Partial<TextMotionProps> = { children: 'test', trigger: 'invalid' as any };
-      const { errors } = validateTextMotionProps(props as TextMotionProps);
-
-      expect(errors).toContain('trigger prop must be one of: on-load, scroll');
-    });
-
-    it('should return an error for invalid repeat type', () => {
-      const props: Partial<TextMotionProps> = { children: 'test', repeat: 'not-a-boolean' as any };
-      const { errors } = validateTextMotionProps(props as TextMotionProps);
-
-      expect(errors).toContain('repeat prop must be a boolean');
-    });
-
-    it('should return an error for negative initialDelay', () => {
-      const props: Partial<TextMotionProps> = { children: 'test', initialDelay: -1 };
-      const { errors } = validateTextMotionProps(props as TextMotionProps);
-
-      expect(errors).toContain('initialDelay prop must be non-negative');
-    });
-
-    it('should return an error for invalid animationOrder', () => {
-      const props: Partial<TextMotionProps> = { children: 'test', animationOrder: 'invalid' as any };
-      const { errors } = validateTextMotionProps(props as TextMotionProps);
-
-      expect(errors).toContain('animationOrder prop must be one of: first-to-last, last-to-first');
-    });
-
-    it('should return an error for invalid preset type', () => {
-      const props: Partial<TextMotionProps> = { children: 'test', preset: 'not-an-array' as any };
-      const { errors } = validateTextMotionProps(props as TextMotionProps);
-
-      expect(errors).toContain('preset prop must be an array');
-    });
-
-    it('should return an error for invalid onAnimationStart type', () => {
-      const props: Partial<TextMotionProps> = { children: 'test', onAnimationStart: 'not-a-function' as any };
-      const { errors } = validateTextMotionProps(props as TextMotionProps);
-
-      expect(errors).toContain('onAnimationStart prop must be a function');
-    });
-
-    it('should return an error for invalid onAnimationEnd type', () => {
-      const props: Partial<TextMotionProps> = { children: 'test', onAnimationEnd: 'not-a-function' as any };
-      const { errors } = validateTextMotionProps(props as TextMotionProps);
-
-      expect(errors).toContain('onAnimationEnd prop must be a function');
-    });
-
-    it('should return an error for empty custom.name', () => {
-      const props: Partial<TextMotionProps> = {
-        children: 'test',
-        motion: { custom: { name: '', duration: 1, delay: 0 } },
-      };
-      const { errors } = validateTextMotionProps(props as TextMotionProps);
-
-      expect(errors).toContain('custom.name must be a non-empty string');
-    });
-  });
-});
diff --git a/src/hooks/useValidation/validation.ts b/src/hooks/useValidation/validation.ts
deleted file mode 100644
index 284bb2c..0000000
--- a/src/hooks/useValidation/validation.ts
+++ /dev/null
@@ -1,129 +0,0 @@
-import type { CustomAnimation, Motion, TextMotionProps } from '../../types';
-
-export type ValidationResult = {
-  errors: string[];
-  warnings: string[];
-};
-
-/**
- * @description
- * Validates the props for the TextMotion component.
- * It warns if the 'children' prop is empty, checks the value of the 'split' prop,
- * and runs validation on the 'motion' prop.
- *
- * @param {TextMotionProps} props - The props of the TextMotion component to validate.
- * @returns {ValidationResult} An object containing arrays of errors and warnings.
- */
-export const validateTextMotionProps = (props: TextMotionProps): ValidationResult => {
-  const errors: string[] = [];
-  const warnings: string[] = [];
-
-  if (props.children === undefined || props.children === null) {
-    warnings.push('children prop is empty');
-  }
-
-  // if (props.split === 'line' && typeof props.children !== 'string') {
-  //   warnings.push('split="line" is only applicable when children is a string.');
-  // }
-
-  const common = validateCommonProps(props);
-
-  errors.push(...common.errors);
-  warnings.push(...common.warnings);
-
-  return { errors, warnings };
-};
-
-/**
- * @description
- * Validates common props for the TextMotion component.
- *
- * @param {Partial<TextMotionProps>} props - The props to validate.
- * @returns {ValidationResult} An object containing arrays of errors and warnings.
- */
-const validateCommonProps = (props: Partial<TextMotionProps>): ValidationResult => {
-  const errors: string[] = [];
-  const warnings: string[] = [];
-
-  if (props.split !== undefined && !['character', 'word'].includes(props.split)) {
-    errors.push('split prop must be one of: character, word');
-  }
-
-  if (props.trigger !== undefined && !['on-load', 'scroll'].includes(props.trigger)) {
-    errors.push('trigger prop must be one of: on-load, scroll');
-  }
-
-  if (props.repeat !== undefined && typeof props.repeat !== 'boolean') {
-    errors.push('repeat prop must be a boolean');
-  }
-
-  if (props.initialDelay !== undefined && props.initialDelay < 0) {
-    errors.push('initialDelay prop must be non-negative');
-  }
-
-  if (props.animationOrder !== undefined && !['first-to-last', 'last-to-first'].includes(props.animationOrder)) {
-    errors.push('animationOrder prop must be one of: first-to-last, last-to-first');
-  }
-
-  if (props.motion !== undefined) {
-    const motionValidation = validateMotion(props.motion);
-
-    errors.push(...motionValidation.errors);
-    warnings.push(...motionValidation.warnings);
-  }
-
-  if (props.preset !== undefined && !Array.isArray(props.preset)) {
-    errors.push('preset prop must be an array');
-  }
-
-  if (props.onAnimationStart !== undefined && typeof props.onAnimationStart !== 'function') {
-    errors.push('onAnimationStart prop must be a function');
-  }
-
-  if (props.onAnimationEnd !== undefined && typeof props.onAnimationEnd !== 'function') {
-    errors.push('onAnimationEnd prop must be a function');
-  }
-
-  return { errors, warnings };
-};
-
-/**
- * @description
- * Validates the motion configuration object.
- * It checks for positive duration, non-negative delay, and warns if the duration is too long.
- *
- * @param {Motion} motion - The motion configuration to validate.
- * @returns {ValidationResult} An object containing arrays of errors and warnings.
- */
-const validateMotion = (motion: Motion): ValidationResult => {
-  const MAX_RECOMMENDED_DURATION = 10;
-
-  const errors: string[] = [];
-  const warnings: string[] = [];
-
-  Object.entries(motion).forEach(([key, config]) => {
-    if (config === undefined || config === null) return;
-
-    if (config.duration <= 0) {
-      errors.push(`${key}.duration must be greater than 0`);
-    }
-
-    if (config.delay < 0) {
-      errors.push(`${key}.delay must be non-negative`);
-    }
-
-    if (config.duration > MAX_RECOMMENDED_DURATION) {
-      warnings.push(`${key}.duration is very long (${config.duration}s)`);
-    }
-
-    if (key === 'custom') {
-      const customConfig = config as CustomAnimation;
-
-      if (typeof customConfig.name !== 'string' || customConfig.name.trim() === '') {
-        errors.push('custom.name must be a non-empty string');
-      }
-    }
-  });
-
-  return { errors, warnings };
-};

From 598b5d7c1d95236c3d4074d0c1eec20305a0d1c4 Mon Sep 17 00:00:00 2001
From: Donghyun Lee <shubug@naver.com>
Date: Sun, 18 Jan 2026 16:57:42 +0900
Subject: [PATCH 6/7] refactor: improve minor things

---
 src/components/TextMotion/TextMotion.spec.tsx  | 18 +-----------------
 .../useAnimateChildren/useAnimateChildren.tsx  |  1 -
 src/hooks/useController/useController.spec.tsx | 18 +++++++++---------
 src/hooks/useResolveMotion/useResolveMotion.ts |  2 +-
 4 files changed, 11 insertions(+), 28 deletions(-)

diff --git a/src/components/TextMotion/TextMotion.spec.tsx b/src/components/TextMotion/TextMotion.spec.tsx
index ec24e15..b26d089 100644
--- a/src/components/TextMotion/TextMotion.spec.tsx
+++ b/src/components/TextMotion/TextMotion.spec.tsx
@@ -57,7 +57,7 @@ describe('TextMotion component', () => {
     expect(useControllerSpy).toHaveBeenCalledWith(expect.objectContaining({ trigger: 'scroll', repeat: false }));
   });
 
-  it('renders spans when canAnimate is true (e.g., trigger="on-load")', () => {
+  it('renders spans when canAnimate is true', () => {
     const animatedChildren = Array.from(TEXT).map((ch, i) => (
       <span key={i} aria-hidden="true">
         {ch}
@@ -84,22 +84,6 @@ describe('TextMotion component', () => {
     expect(container).toHaveClass('text-motion-inactive');
   });
 
-  it('renders spans when canAnimate is true', () => {
-    const animatedChildren = Array.from(TEXT).map((ch, i) => (
-      <span key={i} aria-hidden="true">
-        {ch}
-      </span>
-    ));
-
-    render(<MockTextMotion hookReturn={{ canAnimate: true, text: TEXT, animatedChildren }}>{TEXT}</MockTextMotion>);
-
-    const container = screen.getByLabelText(TEXT);
-    const spans = container.querySelectorAll<HTMLSpanElement>('span[aria-hidden="true"]');
-
-    expect(spans.length).toBe(TEXT.length);
-    expect(container).toHaveClass('text-motion');
-  });
-
   it('warns when children is empty null/undefined', () => {
     render(<TextMotion>{null}</TextMotion>);
 
diff --git a/src/hooks/useAnimateChildren/useAnimateChildren.tsx b/src/hooks/useAnimateChildren/useAnimateChildren.tsx
index c7ae008..f136208 100644
--- a/src/hooks/useAnimateChildren/useAnimateChildren.tsx
+++ b/src/hooks/useAnimateChildren/useAnimateChildren.tsx
@@ -91,7 +91,6 @@ const animateNodeTree = ({
     if (isTextNode(node)) {
       const rawSequenceIndex = sequenceIndex++;
       const orderedSequenceIndex = calculateSequenceIndex(rawSequenceIndex, totalTextNodeCount, animationOrder);
-
       const shouldTriggerAnimationEnd = isLastNode(orderedSequenceIndex, totalTextNodeCount);
 
       const { style } = generateAnimation(motion, orderedSequenceIndex, initialDelay);
diff --git a/src/hooks/useController/useController.spec.tsx b/src/hooks/useController/useController.spec.tsx
index 488d32a..c2cd00d 100644
--- a/src/hooks/useController/useController.spec.tsx
+++ b/src/hooks/useController/useController.spec.tsx
@@ -15,8 +15,8 @@ jest.mock('../../utils/splitReactNode');
 
 describe('useController', () => {
   const mockUseIntersectionObserver = useIntersectionObserver as jest.Mock;
-  const mockUseResolvedMotion = useResolveMotion as jest.Mock;
-  const mockUseAnimatedChildren = useAnimateChildren as jest.Mock;
+  const mockUseResolveMotion = useResolveMotion as jest.Mock;
+  const mockUseAnimateChildren = useAnimateChildren as jest.Mock;
   const mockSplitReactNode = splitReactNode as jest.Mock;
 
   const defaultProps: TextMotionProps = {
@@ -25,8 +25,8 @@ describe('useController', () => {
 
   beforeEach(() => {
     mockUseIntersectionObserver.mockReturnValue([null, true]);
-    mockUseResolvedMotion.mockReturnValue({});
-    mockUseAnimatedChildren.mockReturnValue([]);
+    mockUseResolveMotion.mockReturnValue({});
+    mockUseAnimateChildren.mockReturnValue([]);
     mockSplitReactNode.mockReturnValue({ nodes: ['H', 'e', 'l', 'l', 'o'], text: 'Hello' });
   });
 
@@ -59,21 +59,21 @@ describe('useController', () => {
     const motion = { fade: { variant: 'in' as const, duration: 1, delay: 1 } };
     const props = { ...defaultProps, motion };
     renderHook(() => useController(props));
-    expect(mockUseResolvedMotion).toHaveBeenCalledWith({ motion, preset: undefined });
+    expect(mockUseResolveMotion).toHaveBeenCalledWith({ motion, preset: undefined });
   });
 
   it('should call useResolveMotion with preset prop', () => {
     const preset: Preset[] = ['slide-up'];
     const props = { ...defaultProps, preset };
     renderHook(() => useController(props));
-    expect(mockUseResolvedMotion).toHaveBeenCalledWith({ motion: undefined, preset });
+    expect(mockUseResolveMotion).toHaveBeenCalledWith({ motion: undefined, preset });
   });
 
   it('should call useAnimateChildren with correct props when animating', () => {
     const props = { ...defaultProps, initialDelay: 1, animationOrder: 'last-to-first' as const };
     renderHook(() => useController(props));
 
-    expect(mockUseAnimatedChildren).toHaveBeenCalledWith({
+    expect(mockUseAnimateChildren).toHaveBeenCalledWith({
       nodes: ['H', 'e', 'l', 'l', 'o'],
       initialDelay: 1,
       animationOrder: 'last-to-first',
@@ -87,7 +87,7 @@ describe('useController', () => {
     const props = { ...defaultProps, trigger: 'scroll' as const };
     renderHook(() => useController(props));
 
-    expect(mockUseAnimatedChildren).toHaveBeenCalledWith(
+    expect(mockUseAnimateChildren).toHaveBeenCalledWith(
       expect.objectContaining({
         nodes: [defaultProps.children],
       })
@@ -97,7 +97,7 @@ describe('useController', () => {
   it('should return correct values', () => {
     mockUseIntersectionObserver.mockReturnValue(['ref', true]);
     mockSplitReactNode.mockReturnValue({ nodes: ['Test'], text: 'Test' });
-    mockUseAnimatedChildren.mockReturnValue(['Animated Test']);
+    mockUseAnimateChildren.mockReturnValue(['Animated Test']);
 
     const { result } = renderHook(() => useController(defaultProps));
 
diff --git a/src/hooks/useResolveMotion/useResolveMotion.ts b/src/hooks/useResolveMotion/useResolveMotion.ts
index aa75967..c07acad 100644
--- a/src/hooks/useResolveMotion/useResolveMotion.ts
+++ b/src/hooks/useResolveMotion/useResolveMotion.ts
@@ -14,7 +14,7 @@ type UseResolvedMotionProps = {
  * `useResolveMotion` is a custom hook that resolves the motion configuration.
  * It either uses the provided `motion` object or generates a configuration from the `preset` array.
  * If a `preset` is provided, it will be mapped to a `Motion` object.
- * If a `motion` object is provided, it will be deep-copied.
+ * If a `motion` object is provided, it will be returned as-is.
  * If neither is provided, an empty object will be returned.
  *
  * @param {Motion} [motion] - A custom motion configuration object.

From 7d6350492fba016b82ccbf7cc60e8d52c40c0a83 Mon Sep 17 00:00:00 2001
From: Donghyun Lee <shubug@naver.com>
Date: Sun, 18 Jan 2026 18:43:46 +0900
Subject: [PATCH 7/7] chore: update package version to v0.0.11

---
 package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/package.json b/package.json
index 418a999..f38abd3 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "react-textmotion",
-  "version": "0.0.10",
+  "version": "0.0.11",
   "description": "Lightweight yet powerful library that provides variable animation effects for React applications.",
   "type": "module",
   "main": "dist/index.cjs.js",