Merge remote-tracking branch 'origin/master' into URH-96/use-detect-device

Author: bicochan

docs/pages/docs/hooks/_meta.json

@@ -1,6 +1,12 @@
 {
-  "useTranslation": "useTranslation",
+  "useDeepCompareEffect": "useDeepCompareEffect",
+  "useDetectDevice": "useDetectDevice",
+  "useKeyCombination": "useKeyCombination",
+  "useLongPress": "useLongPress",
   "useMousePosition": "useMousePosition",
+  "useScrollLock": "useScrollLock",
+  "useSound": "useSound",
   "useTimer": "useTimer",
-  "useDetectDevice": "useDetectDevice"
+  "useToggle": "useToggle",
+  "useTranslation": "useTranslation"
 }

docs/pages/docs/hooks/useDeepCompareEffect.mdx

@@ -0,0 +1,46 @@
+# useDeepCompareEffect
+
+## Introduce
+
+의존성 배열의 깊은 비교를 통해 변화를 감지하고 콜백을 실행시키는 훅입니다.
+
+```ts
+const useDeepCompareEffect = (callback: () => void, dependencies: unknown[]) => void
+```
+
+### Props
+
+- `callback` : 의존성 배열의 변화가 감지되었을 때 실행할 콜백 함수
+- `dependencies` : 의존성 배열
+
+## Examples
+
+```tsx copy filename="TestComponent.tsx"
+function App() {
+  const [, setCount] = useState(0);
+  const effectCountRef = useRef(0);
+  const deepCompareCountRef = useRef(0);
+
+  useEffect(() => {
+    effectCountRef.current += 1;
+    // 빈 객체는 매번 새로운 참조를 갖기 때문에 effectCount는 계속 증가
+  }, [{}]);
+
+  useDeepCompareEffect(() => {
+    deepCompareCountRef.current += 1;
+    // 빈 객체를 같은 값으로 판단해 deepCompareCountRef는 한 번(첫 시도)만 증가
+  }, [{}]);
+
+  return (
+    <div>
+      <p>effectCount: {effectCountRef.current}</p>
+      <p>deepCompareCount: {deepCompareCountRef.current}</p>
+      <p>
+        <button type="button" onClick={() => setCount((c) => c + 1)}>
+          리렌더링 발생
+        </button>
+      </p>
+    </div>
+  );
+}
+```

docs/pages/docs/hooks/useKeyCombination.mdx

@@ -0,0 +1,76 @@
+# useKeyCombination
+
+## Introduce
+
+지정된 키 조합을 눌렀을 때 콜백 함수를 호출하는 훅입니다.
+
+- 지정된 키들을 모두 눌렀을 때 콜백 함수를 호출하며, 필요에 따라 기본 동작을 막을 수도 있습니다.
+- 예를 들어, `Ctrl + K` 키 조합을 감지하여 특정 작업을 실행하고자 할 때 사용할 수 있습니다.
+
+```ts
+interface UseKeyCombinationProps {
+  shortcutKeys: string[];
+  callback: () => void;
+  isPrevent?: boolean;
+}
+
+const useKeyCombination = ({
+  shortcutKeys,
+  callback,
+  isPrevent = false,
+}: UseKeyCombinationProps): void
+```
+
+### Props
+
+- `shortcutKeys` : 키 조합을 나타내는 키 코드의 배열
+- `callback` : 키 조합이 감지되었을 때 실행할 콜백 함수
+- `isPrevent` : true로 설정하면 키 조합이 눌렸을 때 기본 동작 방지 (기본값: false)
+
+## Examples
+
+```tsx copy filename="TestComponent.tsx"
+import { useCallback, useRef, useState } from 'react';
+import useKeyCombination from './hooks/useKeyCombination';
+
+function TestComponent() {
+  const [bold, setBold] = useState(false);
+  const [isSave, setIsSave] = useState(false);
+  const input = useRef<HTMLInputElement>(null);
+
+  const keyActions = {
+    toggleBold: {
+      shortcutKeys: ['ControlLeft', 'KeyB'],
+      callback: useCallback(() => {
+        setBold((state) => !state);
+      }, [setBold]),
+    },
+    save: {
+      shortcutKeys: ['MetaLeft', 'KeyS'],
+      callback: useCallback(() => setIsSave((state) => !state), [setIsSave]),
+      isPrevent: true,
+    },
+    search: {
+      shortcutKeys: ['MetaLeft', 'KeyK'],
+      callback: useCallback(() => input.current?.focus(), []),
+    },
+  };
+
+  useKeyCombination(keyActions.toggleBold);
+  useKeyCombination(keyActions.save);
+  useKeyCombination(keyActions.search);
+
+  return (
+    <div>
+      <input type="text" ref={input} placeholder="Press command + K" />
+      <div>USE-REACT-HOOKS</div>
+      <ul>
+        <li style={{ fontWeight: bold ? 'bold' : 'normal' }}>
+          command + B : Bold
+        </li>
+        <li>command + S: {isSave ? 'SAVE!' : 'Not saved yet'}</li>
+      </ul>
+    </div>
+  );
+}
+```

docs/pages/docs/hooks/useLongPress.mdx

@@ -0,0 +1,55 @@
+# useLongPress
+
+## Introduce
+
+사용자가 요소를 길게 눌렀을 때 콜백 함수를 호출합니다.
+
+```ts
+export type Fn = () => void;
+
+export interface UseLongPressReturns {
+  onMouseDown: Fn;
+  onMouseUp: Fn;
+  onMouseLeave: Fn;
+  onTouchStart: Fn;
+  onTouchEnd: Fn;
+}
+
+const useLongPress = (callback: Fn, delay: number = 500): UseLongPressReturns
+```
+
+사용자가 요소를 지정한 시간 이상 누르고 있을 때 콜백 함수가 호출되며, 마우스와 터치 이벤트를 모두 지원합니다.
+
+### Props
+
+- `callback` : 사용자가 요소를 길게 눌렀을 때 호출될 콜백 함수
+- `delay` : 사용자가 요소를 길게 눌러야 하는 시간(밀리초, 기본값 500ms)
+
+### Returns
+
+- UseLongPressReturns : 요소에 연결될 이벤트 핸들러 객체. 다음 다섯 가지 이벤트가 반환됩니다.
+  - onMouseDown
+  - onMouseUp
+  - onMouseLeave
+  - onTouchStart
+  - onTouchEnd
+
+## Examples
+
+```tsx copy filename="TestComponent.tsx"
+function TestComponent() {
+  const [isLongPressed, setLongPressed] = useState(false);
+
+  const attrs = useLongPress(() => {
+    setLongPressed(true);
+  });
+
+  return (
+    <div>
+      <h1>{isLongPressed ? '✨ LONG PRESS ✨' : 'USE-REACT-HOOKS'}</h1>
+      <button {...attrs}>PRESS</button>
+      <button onClick={() => setLongPressed(false)}>RESET</button>
+    </div>
+  );
+}
+```

docs/pages/docs/hooks/useScrollLock.mdx

@@ -0,0 +1,44 @@
+# useScrollLock
+
+## Introduce
+
+페이지의 스크롤을 잠궈 사용자가 스크롤할 수 없도록 합니다.
+
+(스크롤 바가 비활성화된 상태로, UI형태가 유지된 형태)
+
+```ts
+const useScrollLock = (props: boolean): void
+```
+
+### Props
+
+boolean 값으로 스크롤의 잠금 여부를 관리합니다.
+
+## Examples
+
+```tsx copy filename="TestComponent.tsx"
+
+const TestComponent = () => {
+  const [isModalOpen, setIsModalOpen] = useState<boolean>(false);
+
+  useScrollLock(isModalOpen);
+
+  const openModal = () => {
+    setIsModalOpen(true);
+  };
+
+  const closeModal = () => {
+    setIsModalOpen(false);
+  };
+
+  return (
+    <div style={styles.container}>
+      {isModalOpen && (
+        <div style={styles.modal}>
+          <div style={styles.modalContent}>
+     ...
+    </div>
+  );
+};
+
+```