React Useful Kit

유용한 React 컴포넌트와 훅들을 모아놓은 라이브러리입니다.

설치

npm install react-useful-kit
# 또는
yarn add react-useful-kit
# 또는
pnpm add react-useful-kit

요구사항

• React 19.0.0 이상
• React DOM 19.0.0 이상

특징

✅ CSS 수동 주입: CSS 파일을 선택적으로 import하여 커스터마이징 용이
✅ TypeScript 완전 지원: 타입 안전성 보장
✅ 경량: 최소한의 의존성으로 번들 크기 최적화
✅ 합성 컴포넌트 패턴: 유연하고 직관적인 API 제공

목차

• React Useful Kit
  • 설치
  • 요구사항
  • 특징
  • 목차
  • 사용법
    • Modal 컴포넌트
    • useAlertModal 훅
    • useDeepEffect 훅
  • CSS 스타일
    • 커스터마이징
  • API 문서
    • Modal 컴포넌트
      • Modal
      • Modal.Trigger
      • Modal.Content
      • Modal.Close
    • useAlertModal 훅

사용법

Modal 컴포넌트

합성 컴포넌트 패턴을 사용하여 유연하고 직관적인 모달을 구현할 수 있습니다.

import React from 'react'
import { Modal } from 'react-useful-kit'

function App() {
  return (
    <div>
      <Modal>
        <Modal.Trigger>
          <button>모달 열기</button>
        </Modal.Trigger>
        <Modal.Content>
          <h2>모달 제목</h2>
          <p>모달 내용입니다!</p>
          <Modal.Close />
        </Modal.Content>
      </Modal>
    </div>
  )
}

useAlertModal 훅

함수 호출만으로 간편하게 확인/취소 모달을 표시할 수 있습니다.

import React from 'react'
import { useAlertModal } from 'react-useful-kit'

function App() {
  const { alert } = useAlertModal()

  const handleSimpleAlert = () => {
    alert('간단한 알림 메시지')
  }

  const handleConfirmAlert = () => {
    alert({
      title: '확인',
      message: '정말로 삭제하시겠습니까?',
      showCancel: true,
      confirmText: '삭제',
      cancelText: '취소',
      onConfirm: () => {
        console.log('삭제됨')
      },
      onCancel: () => {
        console.log('취소됨')
      },
    })
  }

  return (
    <div>
      <button onClick={handleSimpleAlert}>간단한 Alert</button>
      <button onClick={handleConfirmAlert}>확인/취소 Alert</button>
    </div>
  )
}

useDeepEffect 훅

의존성 배열을 깊은 비교로 처리하는 useEffect 훅입니다. 일반적인 useEffect는 의존성 배열의 참조만 비교하지만, useDeepEffect는 값 자체를 깊게 비교하여 실제로 값이 변경된 경우에만 effect를 실행합니다.

import React, { useState } from 'react'
import { useDeepEffect } from 'react-useful-kit'

function App() {
  const [user, setUser] = useState({ name: 'John', age: 30 })
  const [items, setItems] = useState([1, 2, 3])

  // 일반 useEffect는 user 객체 참조가 바뀔 때마다 실행되지만
  // useDeepEffect는 user 객체의 실제 값이 변경될 때만 실행됩니다
  useDeepEffect(() => {
    console.log('User 정보가 변경되었습니다:', user)
  }, [user])

  // 배열도 깊은 비교가 가능합니다
  useDeepEffect(() => {
    console.log('Items가 변경되었습니다:', items)
  }, [items])

  const updateUserReference = () => {
    // 같은 값으로 새 객체 생성 (참조만 변경) - useDeepEffect 실행 안됨
    setUser({ ...user })
  }

  const updateUserValue = () => {
    // 실제 값 변경 - useDeepEffect 실행됨
    setUser(prev => ({ ...prev, age: prev.age + 1 }))
  }

  return (
    <div>
      <p>User: {JSON.stringify(user)}</p>
      <p>Items: [{items.join(', ')}]</p>
      <button onClick={updateUserReference}>참조만 변경 (실행 안됨)</button>
      <button onClick={updateUserValue}>값 변경 (실행됨)</button>
    </div>
  )
}

CSS 스타일

CSS 파일을 수동으로 import하여 사용하세요:

import 'react-useful-kit/dist/react-useful-kit.css'

이렇게 하면 사용자가 원하는 시점에 스타일을 로드할 수 있고, 커스터마이징도 더 쉽게 할 수 있습니다.

커스터마이징

다음 CSS 클래스를 사용하여 스타일을 커스터마이징할 수 있습니다:

/* Modal 스타일 */
.react-useful-kit-modal-overlay {
  /* 오버레이 */
}
.react-useful-kit-modal-content {
  /* 모달 콘텐츠 */
}
.react-useful-kit-modal-close {
  /* 닫기 버튼 */
}

/* Alert Modal 스타일 */
.react-useful-kit-alert-modal-content {
  /* Alert 콘텐츠 */
}
.react-useful-kit-alert-modal-title {
  /* Alert 제목 */
}
.react-useful-kit-alert-modal-message {
  /* Alert 메시지 */
}
.react-useful-kit-alert-modal-button-container {
  /* 버튼 컨테이너 */
}
.react-useful-kit-alert-modal-confirm-button {
  /* 확인 버튼 */
}
.react-useful-kit-alert-modal-cancel-button {
  /* 취소 버튼 */
}

API 문서

Modal 컴포넌트

합성 컴포넌트 패턴으로 구현된 모달 컴포넌트입니다.

Modal

모달 컨텍스트를 제공하는 루트 컴포넌트입니다.

Modal.Trigger

모달을 여는 트리거 요소입니다.

• 자식 요소에 onClick 이벤트를 추가하여 모달을 엽니다
• 기존 onClick 이벤트가 있다면 먼저 실행한 후 모달을 엽니다

Modal.Content

모달 내용을 렌더링하는 컴포넌트입니다.

Props:

• className?: string - 추가 CSS 클래스
• overlay?: boolean - 오버레이 표시 여부 (기본값: true)
• isDefaultOpen?: boolean - 초기 열림 상태 (기본값: false)

Modal.Close

모달을 닫는 요소입니다.

• children이 없으면 기본 닫기 버튼을 렌더링합니다
• children이 있으면 해당 요소에 클릭 이벤트를 추가하여 모달을 닫습니다

Props:

• className?: string - 추가 CSS 클래스
• children?: ReactElement - 커스텀 닫기 요소

useAlertModal 훅

함수형 모달을 위한 훅입니다.

const { alert } = useAlertModal()

// 간단한 사용법 alert('메시지')

// 상세한 옵션 alert({ title?: string message: string confirmText?: string cancelText?: string showCancel?: boolean onConfirm?: () => void onCancel?: () => void })

### useDeepEffect 훅

의존성 배열을 깊은 비교로 처리하는 `useEffect` 훅입니다.

```tsx
useDeepEffect(effect: React.EffectCallback, deps?: React.DependencyList)
```

**매개변수:**

- `effect`: 실행할 effect 함수
- `deps`: 의존성 배열 (깊은 비교가 적용됨)

**특징:**

- 객체와 배열의 실제 값 변경을 감지합니다
- 참조만 변경되고 값이 동일한 경우 effect를 실행하지 않습니다
- 중첩된 객체나 배열도 올바르게 비교합니다
- Date, RegExp 객체도 지원합니다

**사용 시나리오:**

- 복잡한 객체나 배열이 의존성으로 사용될 때
- 불필요한 effect 실행을 방지하고 성능을 최적화하고 싶을 때
- React의 기본 얕은 비교로는 부족한 경우

### 추가 Exports

#### `useModal`

모달 컨텍스트에 접근할 수 있는 훅입니다.

#### `renderToBody`

컴포넌트를 document.body에 렌더링하는 유틸리티 함수입니다.

#### `deepEqual`

두 값을 깊은 비교하는 유틸리티 함수입니다. `useDeepEffect`에서 내부적으로 사용되며, 직접 사용할 수도 있습니다.

```tsx
import { deepEqual } from 'react-useful-kit'

const obj1 = { a: 1, b: [2, 3] }
const obj2 = { a: 1, b: [2, 3] }

console.log(deepEqual(obj1, obj2)) // true
```

#### `AlertOptions` (타입)

useAlertModal에서 사용하는 옵션 타입입니다.

## 타입 지원

이 라이브러리는 TypeScript로 작성되었으며 완전한 타입 지원을 제공합니다. 모든 컴포넌트와 훅에 대한 타입 정의가 포함되어 있어 개발 시 자동완성과 타입 체크를 받을 수 있습니다.

## 기여하기

이슈나 풀 리퀘스트는 [GitHub 저장소](https://github.com/shlee9999/react-useful-kit)에서 환영합니다.

## 라이센스

MIT © [shlee9999](https://github.com/shlee9999)