# `lib-*` (라이브러리) Repository README 작성 가이드

`lib-*` 접두사를 사용하는 저장소는 다른 애플리케이션에서 가져다 쓸 수 있는 재사용 가능한 코드 패키지(라이브러리)를 관리합니다. 좋은 라이브러리 README는 사용자가 최소한의 노력으로 라이브러리를 설치하고, 핵심 기능을 빠르게 활용할 수 있도록 돕는 '퀵스타트 가이드'와 'API 명세서'의 역할을 동시에 수행해야 합니다.

---

### 1. 라이브러리 소개 (Library Introduction)
- **한 줄 요약**: 이 라이브러리가 어떤 문제를 해결하는지, 어떤 기능을 제공하는지 한 문장으로 명확하게 설명합니다.
    - 예시: "React 애플리케이션에서 복잡한 폼(Form) 상태를 쉽게 관리하고 유효성을 검사하는 경량 라이브러리입니다."
- **주요 특징 (Features)**: 라이브러리의 핵심적인 장점을 3~4가지 항목으로 강조합니다.
    - 예시:
        - 🚀 제로 의존성(Zero-dependency) 및 작은 번들 크기
        - 🎨 손쉬운 커스텀 유효성 검사 규칙 추가
        - 📦 TypeScript 기반의 완벽한 타입 지원
        -  hooking 기반의 직관적인 API

### 2. 설치 (Installation)
- **목적**: 사용자가 자신의 프로젝트에 라이브러리를 추가하는 방법을 안내합니다.
- **패키지 매니저별 명령어**: `npm`, `yarn`, `pnpm` 등 주요 패키지 매니저에 대한 설치 명령어를 모두 제공합니다.
  ```bash
  # npm
  npm install @my-org/react-form-validator

  # yarn
  yarn add @my-org/react-form-validator

  # pnpm
  pnpm add @my-org/react-form-validator
  ```
- **피어 의존성 (Peer Dependencies)**: 라이브러리가 정상적으로 동작하기 위해 반드시 필요한 다른 패키지(예: `react`, `react-dom`)가 있다면, 명확하게 명시하고 설치를 안내합니다.

### 3. 기본 사용법 (Basic Usage / Quick Start)
- **가장 중요한 섹션**: 라이브러리의 핵심 기능을 보여주는 최소한의 'Hello, World!' 예제 코드를 제공하여 사용자가 즉시 따라 해볼 수 있도록 합니다.
- **코드 예시**:
  ```jsx
  import React from 'react';
  import { useForm, validateEmail } from '@my-org/react-form-validator';

  function MyForm() {
    const { register, handleSubmit, errors } = useForm();

    const onSubmit = (data) => {
      console.log('Form data:', data);
    };

    return (
      <form onSubmit={handleSubmit(onSubmit)}>
        <input
          {...register('email', { required: true, validate: validateEmail })}
          placeholder="이메일"
        />
        {errors.email && <p>올바른 이메일을 입력해주세요.</p>}

        <button type="submit">제출</button>
      </form>
    );
  }
  ```

### 4. API 참고 (API Reference)
- **목적**: 라이브러리가 제공하는 주요 함수, 컴포넌트, 훅(Hook) 등의 상세한 명세를 제공합니다.
- **구성**:
    - **`useForm()` Hook**:
        - **`register(name, options)`**:
            - `name` (string, required): 입력 필드의 이름
            - `options` (object): `required`, `minLength`, `validate` 등 유효성 검사 규칙
        - **`handleSubmit(callback)`**:
            - `callback` (function, required): 유효성 검사를 통과했을 때 폼 데이터를 인자로 받아 실행되는 함수
        - **`errors` (object)**: 각 필드의 유효성 검사 실패 정보를 담고 있는 객체
- **팁**: 내용이 길어질 경우, 별도의 `API.md` 파일로 분리하고 README에서는 해당 파일로 링크를 거는 것이 좋습니다.

### 5. 고급 사용법 및 레시피 (Advanced Usage & Recipes)
- **목적**: 기본적인 사용법을 넘어, 실제 애플리케이션에서 마주할 수 있는 복잡한 시나리오에 대한 해결책을 제공합니다.
- **예시**:
    - 비동기 유효성 검사 방법
    - 동적 폼 필드 처리하기
    - 외부 UI 라이브러리(예: `Material-UI`, `Ant Design`)와 통합하기

### 6. 버전 호환성 (Version Compatibility)
- **목적**: 라이브러리가 특정 버전의 프레임워크나 환경에서만 동작하는 경우, 이를 명확히 표기하여 사용자의 혼란을 방지합니다.
- **예시 (표 활용)**:

| 라이브러리 버전 | React 버전 호환성 |
|-----------------|---------------------|
| `2.x`           | `^18.0.0`           |
| `1.x`           | `^16.8.0` OR `^17.0.0` |