feat(react): useFocus 신규 훅 추가

docs/docs/react/hooks/useFocus.mdx

@@ -0,0 +1,69 @@
+import { useFocus } from '@modern-kit/react';
+
+# useFocus
+
+대상 요소를 기준으로 포커스 상태를 반환하고, 포커스 상태에 따른 액션을 정의할 수 있는 커스텀 훅입니다.
+
+<br />
+
+## Code
+[🔗 실제 구현 코드 확인](https://github.com/modern-agile-team/modern-kit/blob/main/packages/react/src/hooks/useFocus/index.ts)
+
+## Interface
+```ts title="typescript"
+
+interface UseFocusProps {
+  focusAction?: (event: FocusEvent) => void;
+  blurAction?: (event: FocusEvent) => void;
+}
+
+interface UseFocusReturnType<T extends HTMLElement> {
+  ref: RefObject<T>;
+  isFocus: boolean;
+  setFocus: () => void;
+}
+
+const useFocus<T extends HTMLElement>({
+  focusAction = noop,
+  blurAction = noop,
+}: UseFocusProps = {}): UseFocusReturnType<T>
+```
+
+## Usage
+```tsx title="typescript"
+import { useFocus } from '@modern-kit/react';
+
+const Example = () => {
+  const { ref, isFocus, setFocus } = useFocus<HTMLInputElement>({
+    focusAction: () => console.log("focus"),
+    blurAction: () => console.log("blur"),
+  });
+
+  return (
+    <div>
+      <input ref={ref} />
+      <button onClick={() => setFocus()}>focus trigger</button>
+      <div>{isFocus ? 'Focus' : 'Blur'}</div>
+    </div>
+  )
+};
+```
+
+## Example
+
+export const Example = () => {
+  const { ref, isFocus, setFocus } = useFocus({
+    focusAction: () => console.log("focus"),
+    blurAction: () => console.log("blur"),
+  });
+
+  return (
+    <div>
+      <input ref={ref} />
+      <button onClick={() => setFocus()}>focus trigger</button>
+      <div>{isFocus ? 'Focus' : 'Blur'}</div>
+    </div>
+  )
+};
+
+<Example />

packages/react/src/hooks/index.ts

@@ -11,6 +11,7 @@ export * from './useDebouncedState';
 export * from './useDocumentTitle';
 export * from './useEventListener';
 export * from './useFileReader';
+export * from './useFocus';
 export * from './useForceUpdate';
 export * from './useHover';
 export * from './useImageStatus';

packages/react/src/hooks/useFocus/index.ts

@@ -0,0 +1,77 @@
+import { noop } from '@modern-kit/utils';
+import { RefObject, useRef, useState, useCallback } from 'react';
+import { useEventListener } from '../../hooks/useEventListener';
+
+interface UseFocusProps {
+  focusAction?: (event: FocusEvent) => void;
+  blurAction?: (event: FocusEvent) => void;
+}
+
+interface UseFocusReturnType<T extends HTMLElement> {
+  ref: RefObject<T>;
+  isFocus: boolean;
+  setFocus: () => void;
+}
+
+/**
+ * @description 대상 요소를 기준으로 포커스 상태를 반환하고, 포커스 상태에 따른 액션을 정의할 수 있는 커스텀 훅입니다.
+ *
+ * @template T - HTML 엘리먼트 타입을 지정합니다.
+ * @param {{
+ *  focusAction?: (event: FocusEvent) => void;
+ *  blurAction?: (event: FocusEvent) => void;
+ * }} props - 포커스 상태에 따른 콜백 함수를 포함한 선택적 속성입니다.
+ * - `focusAction`: 요소에 포커스가 들어올 때 호출되는 함수입니다. 기본값은 `noop` 함수입니다.
+ * - `blurAction`: 요소에서 포커스가 빠져나갈 때 호출되는 함수입니다. 기본값은 `noop` 함수입니다.
+ *
+ * @returns {UseFocusReturnType<T>} `ref`, `isFocus`, `setFocus`를 포함한 객체를 반환합니다.
+ * - `ref`: 추적할 대상 요소의 참조입니다.
+ * - `isFocus`: 요소가 포커스 상태인지 여부를 나타내는 불리언 값입니다.
+ * - `setFocus`: 요소에 포커스를 참 값으로 설정하는 함수입니다.
+ *
+ * @example
+ * const { ref, isFocused, setFocus } = useFocus<HTMLInputElement>({
+ *   focusAction: () => console.log("focus"),
+ *   blurAction: () => console.log("blur")
+ * });
+ *
+ * <input ref={ref} />
+ * <button onClick={() => setFocus()}>focus trigger</button>
+ * <div>{isFocused ? 'focus' : 'blur'}</div>
+ */
+export function useFocus<T extends HTMLElement>({
+  focusAction = noop,
+  blurAction = noop,
+}: UseFocusProps = {}): UseFocusReturnType<T> {
+  const [isFocus, setIsFocus] = useState(false);
+
+  const ref = useRef<T>(null);
+
+  const onFocus = useCallback(
+    (event: FocusEvent) => {
+      setIsFocus(true);
+      focusAction(event);
+    },
+    [focusAction]
+  );
+
+  const onBlur = useCallback(
+    (event: FocusEvent) => {
+      setIsFocus(false);
+      blurAction(event);
+    },
+    [blurAction]
+  );
+
+  const setFocus = useCallback(() => {
+    if (ref.current) {
+      ref.current.focus();
+      setIsFocus(true);
+    }
+  }, []);
+
+  useEventListener(ref, 'focus', onFocus);
+  useEventListener(ref, 'blur', onBlur);
+
+  return { ref, isFocus, setFocus };
+}

packages/react/src/hooks/useFocus/useFocus.spec.tsx

@@ -0,0 +1,107 @@
+import { describe, it, expect, Mock, vi } from 'vitest';
+import { useFocus } from '.';
+import { renderSetup } from '../../utils/test/renderSetup';
+import { act, screen } from '@testing-library/react';
+
+const TestComponent = ({
+  focusMockFn,
+  blurMockFn,
+  connectedRef,
+}: {
+  focusMockFn?: Mock<any, any>;
+  blurMockFn?: Mock<any, any>;
+  connectedRef?: boolean;
+}) => {
+  const { ref, isFocus, setFocus } = useFocus<HTMLInputElement>({
+    focusAction: focusMockFn,
+    blurAction: blurMockFn,
+  });
+
+  return (
+    <div>
+      <input ref={connectedRef ? ref : undefined} role="focus-target" />
+      <button role="target-trigger" onClick={() => setFocus()} />
+      <div role="target-status">{isFocus ? 'Focus' : 'Blur'}</div>
+    </div>
+  );
+};
+
+describe('useFocus', () => {
+  it('should trigger callback at target focus and blur', async () => {
+    const focusMockFn = vi.fn();
+    const blurMockFn = vi.fn();
+
+    const { user } = renderSetup(
+      <TestComponent
+        focusMockFn={focusMockFn}
+        blurMockFn={blurMockFn}
+        connectedRef
+      />
+    );
+
+    const focusTarget = screen.getByRole('focus-target');
+    const targetTrigger = screen.getByRole('target-trigger');
+    const targetStatus = screen.getByRole('target-status');
+
+    await act(async () => {
+      await user.click(targetTrigger);
+    });
+    expect(focusTarget).toHaveFocus();
+    expect(targetStatus.textContent).toBe('Focus');
+    expect(focusMockFn).toBeCalled();
+
+    await act(async () => {
+      await user.click(targetStatus);
+    });
+    expect(focusTarget).not.toHaveFocus();
+    expect(targetStatus.textContent).toBe('Blur');
+    expect(blurMockFn).toBeCalled();
+  });
+
+  it('should not throw error when ref is not connected', async () => {
+    const focusMockFn = vi.fn();
+    const blurMockFn = vi.fn();
+
+    const { user } = renderSetup(
+      <TestComponent focusMockFn={focusMockFn} blurMockFn={blurMockFn} />
+    );
+
+    const focusTarget = screen.getByRole('focus-target');
+    const targetTrigger = screen.getByRole('target-trigger');
+    const targetStatus = screen.getByRole('target-status');
+
+    await act(async () => {
+      await user.click(targetTrigger);
+    });
+    expect(focusTarget).not.toHaveFocus();
+    expect(targetStatus.textContent).toBe('Blur');
+    expect(focusMockFn).not.toBeCalled();
+
+    await act(async () => {
+      await user.click(targetStatus);
+    });
+    expect(focusTarget).not.toHaveFocus();
+    expect(targetStatus.textContent).toBe('Blur');
+    expect(blurMockFn).not.toBeCalled();
+  });
+
+  it('should not throw error when focusAction and blurAction is not provided', async () => {
+    const { user } = renderSetup(<TestComponent connectedRef />);
+
+    const focusTarget = screen.getByRole('focus-target');
+    const targetTrigger = screen.getByRole('target-trigger');
+    const targetStatus = screen.getByRole('target-status');
+
+    await act(async () => {
+      await user.click(targetTrigger);
+    });
+    expect(focusTarget).toHaveFocus();
+    expect(targetStatus.textContent).toBe('Focus');
+
+    await act(async () => {
+      await user.click(targetStatus);
+    });
+    expect(focusTarget).not.toHaveFocus();
+    expect(targetStatus.textContent).toBe('Blur');
+  });
+});