Merge remote-tracking branch 'origin/master' into URH-103

Author: bicochan

docs/pages/docs/hooks/_meta.json

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

docs/pages/docs/hooks/useConfirm.mdx

@@ -0,0 +1,74 @@
+# useConfirm
+
+## Introduce
+
+- 컨펌 로직을 담고 있는 훅입니다.
+- 컨펌 다이얼로그를 구현할 때 유용하게 사용할 수 있습니다.
+
+```ts
+interface UseConfirmReturns {
+  message?: string;
+  isOpen: boolean;
+  confirm: (message: string) => Promise<boolean>;
+  onConfirm: () => void;
+  onCancel: () => void;
+}
+
+const useConfirm = (): UseConfirmReturns
+```
+
+### Returns
+
+- `message`: 컨펌 메시지. confirm() 함수에 전달된 값을 그대로 반환.
+- `isOpen`: 컨펌 다이얼로그 open/close 상태를 제어할 수 있는 값. confirm() 함수 실행 단계에서 message를 체크하여 값을 반환.
+- `confirm`: 컨펌 로직을 실행하는 비동기 함수. 컨펌 다이얼로그를 열고 사용자의 컨펌 여부를 반환.
+- `onConfirm`: 컨펌을 실행하는 함수.
+- `onCancel`: 취소를 실행하는 함수.
+
+## Examples
+
+import { Callout } from 'nextra/components';
+
+<Callout type="info">
+  `useConfirm()`을 사용하기 전에 먼저 `ConfirmProvider`를 선언해야 합니다.
+</Callout>
+
+```tsx copy filename="App.tsx"
+import { ConfirmProvider } from '@frontend-opensource/use-react-hooks';
+
+function App() {
+  return (
+    <ConfirmProvider>
+      <TestComponent />
+    </ConfirmProvider>
+  );
+}
+```
+
+```tsx copy filename="TestComponent.tsx"
+import { useConfirm } from '@frontend-opensource/use-react-hooks';
+
+const TestComponent = () => {
+  const { message, isOpen, confirm, onConfirm, onCancel } = useConfirm();
+
+  const handleRemove = async () => {
+    if (await confirm('정말 삭제하시겠습니까?')) {
+      // 컨펌 로직
+    } else {
+      // 취소 로직
+    }
+  };
+
+  return (
+    <>
+      <button onClick={handleRemove}>삭제하기</button>
+
+      <Dialog open={isOpen}>
+        <p>{message}</p>
+        <button onClick={onConfirm}>확인</button>
+        <button onClick={onCancel}>취소</button>
+      </Dialog>
+    </>
+  );
+};
+```

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/useDetectDevice.mdx

@@ -0,0 +1,53 @@
+# useDetectDevice
+
+## Introduce
+
+현재 디바이스의 유형(moblie, desktop), OS 및 Browser를 감지합니다.
+
+import { Callout } from 'nextra/components';
+
+<Callout type="info">
+  userAgent의 업데이트로 인하여 올바르게 작동하지 않을 수 있습니다. 유의해서
+  사용해주세요.
+</Callout>
+
+```ts
+interface UseDeviceDetectReturns {
+  isMobile: boolean;
+  isDesktop: boolean;
+  os: string;
+  browser: string;
+}
+
+const useDetectDevice = (): UseDeviceDetectReturns
+```
+
+### Returns
+
+- `isMobile` : 사용 중인 디바이스의 Mobile 여부를 나타냅니다.
+- `isDesktop` : 사용 중인 디바이스의 Desktop 여부를 나타냅니다.
+- `os` : 사용 중인 디바이스의 OS 이름(문자열)을 나타냅니다.\
+  cf) Windows, macOS, Linux, Android, iOS
+- `browser` : 사용 중인 브라우저의 이름(문자열)을 나타냅니다.\
+  cf) Chrome, Safari, Whale, Edge, Firefox
+
+## Examples
+
+```tsx copy filename="TestComponent.tsx"
+const TestComponent = () => {
+
+  const { isMobile, os, browser } = useDeviceDetect();
+
+  return (
+    <div>
+      <div>
+        {isMobile && (
+          <>
+            <div>모바일 환경에 최적화된 콘텐츠</div>
+            <div>...</div>
+          </>
+        )}
+    </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>
+  );
+};
+
+```