slick-address-kr 1.0.4 → 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,133 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.0.0] - 2026-09-02
+
+패키지가 실제로 동작하도록 고치는 릴리스입니다. 자세한 이관 방법은
+[docs/MIGRATION-v2.md](./docs/MIGRATION-v2.md)를 보세요.
+
+### Fixed
+- **깨진 패키지 진입점** 🔧
+  - `main`이 `window`를 참조하는 IIFE 파일을 가리켜
+    `import { KoreanAddressFinder } from 'slick-address-kr'` 가 실패하던 문제
+  - `exports` 맵과 ESM/CJS/IIFE 3포맷 빌드로 해결
+- **`onSelect`의 `detailAddress`가 항상 비어 있던 문제**
+- **`destroy()` 후에도 남던 `document` 리스너** (메모리 릭)
+- **자동완성 경쟁 조건** — 느린 이전 응답이 최신 결과를 덮어쓰던 문제
+- **API 에러를 빈 결과로 처리하던 문제** — "승인되지 않은 KEY"가
+  "검색 결과 없음"으로 표시됐습니다
+- **죽은 승인키 발급 링크** — 사이트 개편으로 404가 된 경로를 교체
+- **예제 파일의 옛 패키지명 import** (`korean-address-finder`)
+
+### Added
+- **키보드 네비게이션** ⌨️ — 화살표(순환 이동)/Enter/Escape.
+  v1.0.2부터 문서에 적혀 있었으나 실제 구현은 없었습니다
+- **스크린리더 지원** — ARIA combobox/listbox/option 패턴
+- **`slick-address-kr/react`** — `useKoreanAddress` 훅
+- **`slick-address-kr/vue`** — `useKoreanAddress` 컴포저블
+- **`endpoint` / `fetchFn` 옵션** — 자체 프록시 서버 연동
+- **다크모드와 `--kaf-*` CSS 변수**
+- **`address.codes`** — 상세주소·좌표 API 연동용 원본 코드 보존
+- **테스트 스위트와 CI** — 승인키 없이 전부 실행됩니다
+
+### Changed
+- **BREAKING** 루트 `korean-address-finder.js` → `dist/browser.global.js`
+  (전역 `window.KoreanAddressFinder`는 유지)
+- **BREAKING** `onSelect(address, meta)` — 상세주소 변경 시에도 호출
+- **BREAKING** `AddressApiClient.search(keyword, options)` — 옵션 객체
+- **BREAKING** `getSelectedAddress()` → `AddressResult | null`
+- **BREAKING** `exports` 필드 추가로 딥 임포트 차단
+- 요청에서 불필요한 `Content-Type` 헤더 제거 (CORS preflight 유발)
+- 라이브러리가 소비자 콘솔에 `console.error`를 쓰지 않습니다
+
+### Removed
+- 손으로 관리하던 루트 IIFE 사본 `korean-address-finder.js`
+- `.npmignore` (`files` 필드로 일원화)
+
+---
+
+## [1.0.4] - 2026-05-30
+
+### Fixed
+- **만료된 내장 테스트 API 키 제거** 🔑
+  - 더 이상 동작하지 않는 기본 dev 키(`devU01...`)를 제거
+  - API 키 미설정 시 명확한 안내 메시지와 키 발급 링크 제공
+- **XSS 방어**: API 응답값을 `innerHTML`에 삽입할 때 HTML 이스케이프 처리 추가
+- **`keypress` → `keydown`**: deprecated 이벤트를 표준 이벤트로 교체
+
+### Documentation
+- README: API 키 필수 안내 및 "승인되지 않은 KEY" 오류 해결 섹션 추가
+- README: 도메인 등록 관련 CORS 안내 보강
+- README: deno import 예제 버전 갱신 (1.0.2 → 1.0.4)
+- `package.json` files 목록의 잘못된 파일명 수정 (`README-KR.md` → `README.ko.md`)
+
+---
+
+## [1.0.3] - 2025-12-14
+
+### Changed
+- **패키지 매니저 호환성 개선**
+  - README에 pnpm, bun, deno 설치 방법 추가
+  - package.json keywords에 pnpm, bun, deno, keyboard-navigation 추가
+  - 특징 섹션에 "모든 패키지 매니저 지원" 항목 추가
+  - npm 검색 가능성 향상
+
+### Documentation
+- 설치 가이드 개선 (5가지 패키지 매니저 지원 명시)
+- 검색 키워드 최적화
+
+---
+
+## [1.0.2] - 2025-12-14
+
+### Added
+- **키보드 네비게이션 기능** 🆕
+  - 화살표 키(⬆️⬇️)로 검색 결과 탐색
+  - Enter 키로 주소 선택 및 적용
+  - ESC 키로 검색 결과 닫기
+  - 마우스 없이 빠른 주소 입력 가능
+
+- **백엔드 프록시 서버 예제** (`examples/backend-proxy/`)
+  - API 키를 서버에서 안전하게 관리
+  - localhost 테스트 시 도메인 제한 문제 해결
+  - CORS 및 Rate Limiting 포함
+
+- **향상된 예제 파일** (`examples/proxy-test.html`)
+  - 자동완성 + 키보드 네비게이션 데모
+  - 300ms 디바운싱 적용
+  - 실시간 주소 검색 시연
+
+### Changed
+- README 업데이트
+  - 키보드 네비게이션 사용법 추가
+  - 백엔드 프록시 가이드 추가
+  - 특징 섹션에 키보드 네비게이션 항목 추가
+
+### Documentation
+- API 키 관리 가이드 개선
+- 테스트 가이드 업데이트
+- 한국어 README (README.ko.md) 업데이트
+
+---
+
+## [1.0.1] - 2025-11-10
+
+### Initial Release
+- 팝업 없는 인라인 주소 검색 UI
+- 자동완성 모드 지원
+- TypeScript 지원
+- 행정안전부 도로명주소 API 연동
+- React, Vue 등 프레임워크 지원
+- 반응형 디자인
+- 커스터마이징 가능한 스타일
+
+---
+
+## 버전 히스토리
+
+- **1.0.2** (2025-12-14): 키보드 네비게이션 + 백엔드 프록시 예제 추가
+- **1.0.1** (2025-11-10): 초기 릴리스

package/README.ko.md

@@ -1,9 +1,11 @@
-# Korean Address Finder
+# Slick Address KR
 
 [English](./README.md) | **한국어**
 
 팝업 없는 한국 주소 검색 라이브러리
 
+> v1에서 올라오는 경우 [docs/MIGRATION-v2.md](./docs/MIGRATION-v2.md)를 먼저 읽으세요.
+
 ## 왜 만들었나요?
 
 다음 주소 API는 훌륭하지만, 몇 가지 불편한 점이 있습니다:
@@ -22,7 +24,7 @@
 기존 (다음 주소 API):
 페이지 → 버튼 클릭 → 새 창 열림 → 주소 선택 → 창 닫힘 → 값 전달
 
-Korean Address Finder:
+Slick Address KR:
 페이지 → 입력 → 결과 표시 → 선택 → 완료 (같은 페이지에서!)
 ```
 
@@ -30,19 +32,39 @@ Korean Address Finder:
 
 타이핑하는 즉시 결과가 표시됩니다. 검색 버튼을 누를 필요가 없습니다!
 
-### 3. 키보드 네비게이션 🆕
+### 3. 키보드 네비게이션
 
 마우스 없이 키보드만으로 주소를 빠르게 입력할 수 있습니다!
 
-- **⬇️ 화살표 키**로 검색 결과 이동
+- **⬆️⬇️ 화살표 키**로 검색 결과 사이를 순환 이동
 - **Enter**로 선택 및 적용
+- **ESC**로 결과 닫기
 - 마우스 클릭 없이 빠른 입력 가능!
 
 **데모:** `examples/proxy-test.html`에서 체험해보세요.
 
-### 4. 완전한 커스터마이징
+### 4. React / Vue 어댑터
+
+`slick-address-kr/react`의 `useKoreanAddress` 훅과 `slick-address-kr/vue`의
+동명 컴포저블을 제공합니다. 마운트·언마운트, 리렌더 시 재설치 여부를
+프레임워크 생명주기에 맞춰 자동으로 처리합니다.
+
+> **참고:** `slick-address-kr/vue`의 컴포저블은 `setup()` 시점의 옵션을
+> 한 번만 캡처합니다. React 훅과 달리 이후 `onSelect` 등을 바꿔도
+> 반영되지 않습니다. 콜백을 동적으로 바꿔야 한다면 반환된 `finder` 인스턴스를
+> 직접 조작하세요.
+
+### 5. 완전한 커스터마이징
 
-모든 스타일을 CSS로 변경할 수 있습니다. 브랜드 컬러에 맞춰 자유롭게 꾸미세요.
+모든 스타일을 CSS 변수(`--kaf-*`)와 클래스로 변경할 수 있습니다.
+`prefers-color-scheme: dark`에 맞춘 다크모드도 기본 지원합니다.
+브랜드 컬러에 맞춰 자유롭게 꾸미세요.
+
+### 6. 자체 프록시 서버 연동
+
+`endpoint`/`fetchFn` 옵션으로 API 키를 클라이언트에 노출하지 않고
+자체 서버를 통해 호출할 수 있습니다. 예제는 `examples/backend-proxy/`에
+있습니다.
 
 ## 설치 및 사용
 
@@ -56,6 +78,10 @@ Korean Address Finder:
 - 무료로 사용 가능
 - 실시간 업데이트
 
+API 키는 [주소기반산업지원서비스 검색 API 신청](https://business.juso.go.kr/jst/jstAddressApiApplicationWrite)
+페이지에서 발급받습니다. 발급 시 등록한 도메인에서만 호출이 허용되며,
+localhost 개발에는 별도의 개발용 키가 필요합니다.
+
 ## 독립적인 데이터베이스 구축
 
 완전히 독립적으로 운영하고 싶다면:
@@ -79,6 +105,9 @@ git clone https://github.com/poesis/postcodify.git
 # 자세한 내용은 Postcodify 문서 참조
 ```
 
+자세한 내용은 [docs/SELF-HOSTED-DATABASE.md](./docs/SELF-HOSTED-DATABASE.md)를
+참고하세요.
+
 ## 로드맵
 
 - [ ] 주소 유효성 검증 기능
@@ -91,7 +120,7 @@ git clone https://github.com/poesis/postcodify.git
 
 ## 기여자
 
-여러분의 기여를 기다립니다!
+여러분의 기여를 기다립니다! [CONTRIBUTING.md](./CONTRIBUTING.md)를 참고하세요.
 
 ## 라이선스