kor-mapi 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dylan Yi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.eng.md

@@ -0,0 +1,124 @@
+# kor-mapi
+
+[한국어](README.md) | [English](README.eng.md)
+
+A provider-agnostic Korean map facade that abstracts **Naver Maps**, **Kakao Maps**, and **Google Maps** behind a single unified TypeScript API.
+
+## Why
+
+South Korea restricted Google's map data export for 19 years. That restriction was conditionally lifted in February 2026, and Google Maps is expected to offer full Korean navigation coverage within months. In the meantime, apps serving Korean users have relied on Naver or Kakao — each with their own SDK, coordinate conventions, zoom scales, and event models.
+
+`kor-mapi` lets you write map code once and switch providers with a single config change. Three are supported for now, with plans to add others like VWorld in the future as Google's Korean data matures.
+
+## Current Status: v0.1 — Tier 1 Complete
+
+The following features are implemented and work identically across all three providers:
+
+| #   | Feature                   | API                                                                           |
+| --- | ------------------------- | ----------------------------------------------------------------------------- |
+| 1   | **Initialization**        | `KorMap.create({ provider, container, apiKey, center, zoom })`                |
+| 2   | **Camera / viewport**     | `setCenter`, `getCenter`, `setZoom`, `getZoom`, `fitBounds`, `panTo`, `panBy` |
+| 3   | **Map types**             | `setMapType(MapTypeId.ROADMAP \| SATELLITE \| HYBRID \| TERRAIN)`             |
+| 4   | **Markers**               | `new Marker({ position, icon, title, draggable, opacity, zIndex })`           |
+| 5   | **InfoWindows**           | `new InfoWindow({ content })` → `open(map, anchor?)` / `close()`              |
+| 6   | **Vector overlays**       | `Polyline`, `Polygon`, `Circle`, `Rectangle` with unified stroke/fill styles  |
+| 7   | **Events**                | `map.on('click' \| 'zoom_changed' \| 'center_changed' \| 'idle' \| ...)`      |
+| 8   | **Custom tile layers**    | `new TileLayer({ getTileUrl(coord, zoom) })` — works with VWORLD etc.         |
+| 9   | **Marker clustering**     | `new MarkerClusterer(map, markers, options)` — grid-based, zero dependencies  |
+
+**Provider-specific notes:**
+
+- Zoom is normalized to the Naver/Google standard of 7–19. Kakao's inverse 1–13 scale is internally converted. Note that the zoom levels of the three maps are not perfectly identical, so some variance is expected.
+- Kakao's `idle` event (missing from the SDK) is synthesized via a 150ms debounce on `center_changed` + `zoom_changed`.
+- Google markers use `AdvancedMarkerElement` (the current non-deprecated API). A `mapId` defaults to `'DEMO_MAP_ID'` for development; set `config.mapId` in production.
+- Kakao has no standalone terrain base map — `MapTypeId.TERRAIN` falls back to `ROADMAP`.
+- `map.native` gives direct access to the underlying provider object (`naver.maps.Map`, `kakao.maps.Map`, or `google.maps.Map`).
+
+## Out of Scope: Geocoding, Search, and Routing
+
+Geocoding, address search, POI search, and routing are **intentionally not part of the `kor-mapi` unified API**.
+
+Each provider has fundamentally different service APIs — different data models, result structures, transport mechanisms (client SDK vs. REST-only), and Korean-specific data quality. A common-denominator facade would force lossy type conversions and hide provider capabilities that users actually care about. Naver and Kakao routing is also REST-only and requires a server-side proxy, making it a different integration concern from map rendering.
+
+Use `map.native` to access provider services directly:
+
+```ts
+// Kakao — best for Korean addresses and POI
+const map = await KorMap.create<'kakao'>({ provider: 'kakao', ... });
+const geocoder = new window.kakao.maps.services.Geocoder();
+const places = new window.kakao.maps.services.Places();
+
+// Google — global coverage
+const map = await KorMap.create<'google'>({ provider: 'google', ... });
+const geocoder = new window.google.maps.Geocoder();
+```
+
+## Not Yet Implemented (Tier 2 / v0.2+)
+
+Traffic layer, heatmap, drawing tools, map styles, elevation, street view, tilt/heading, multi-language switching, transit layer, administrative boundary overlays, and routing.
+
+## Usage
+
+```ts
+import { KorMap, Marker, InfoWindow, MapTypeId } from "kor-mapi";
+
+const map = await KorMap.create({
+  provider: "kakao", // 'naver' | 'kakao' | 'google'
+  container: "map",
+  apiKey: "YOUR_APP_KEY",
+  center: { lat: 37.5665, lng: 126.978 },
+  zoom: 12,
+});
+
+const marker = new Marker({ position: { lat: 37.5665, lng: 126.978 } });
+marker.setMap(map);
+
+const iw = new InfoWindow({ content: "<b>Seoul City Hall</b>" });
+marker.on("click", () => iw.open(map, marker));
+
+map.on("zoom_changed", () => console.log(map.getZoom()));
+```
+
+Switch to Naver or Google by changing `provider` — everything else stays the same.
+
+## Demo
+
+Since all three providers require API keys, register your app in each developer console, obtain keys, and set them in the `.env` file.
+
+```bash
+cp demo/.env.example demo/.env
+# fill in one or more API keys
+npm run demo
+# open http://localhost:3000
+```
+
+The demo shows all three providers side-by-side with synchronized camera, shared toolbar controls (map type, marker, polyline, circle), and a unified event log.
+
+## Architecture
+
+Stratified Adapter pattern: `KorMap` facade → `IMapProvider` interface → `NaverAdapter` / `KakaoAdapter` / `GoogleAdapter`. Each adapter handles SDK loading (dynamic `<script>` injection), coordinate translation, event name mapping, and provider-specific quirks. Zero production dependencies — all three SDKs are loaded at runtime.
+
+```
+src/
+  core/
+    KorMap.ts        ← facade + create() factory
+    types.ts         ← all public interfaces and enums
+    overlays.ts      ← Marker, InfoWindow, Polyline, Polygon, Circle, Rectangle, TileLayer
+    errors.ts        ← KorMapError hierarchy
+  providers/
+    base/            ← IMapProvider interface
+    naver/           ← NaverAdapter + NaverLoader
+    kakao/           ← KakaoAdapter + KakaoLoader
+    google/          ← GoogleAdapter + GoogleLoader
+  utils/
+    coordinateUtils.ts  ← zoom normalization across providers
+```
+
+## Commands
+
+```bash
+npm run build       # build with tsup
+npm test            # run tests (vitest)
+npm run typecheck   # tsc --noEmit
+npm run demo        # Vite dev server at localhost:3000
+```

package/README.md

@@ -0,0 +1,126 @@
+# kor-mapi
+
+[한국어](README.md) | [English](README.eng.md)
+
+**네이버 지도**, **카카오맵**, **구글 지도** API를 하나의 API로 추상화한 한국 지도 파사드입니다.
+
+## 배경
+
+한국은 19년간 구글에 대한 지도 데이터 반출을 제한했는데 이 제한이 2026년 2월에 조건부로 해제됐고 구글 지도는 수개월 내에 한국 지도 완성도를 상당히 높일 것으로 예상됩니다. 그동안 한국 사용자를 대상으로 하는 앱들은 각자 다른 SDK의 네이버, 카카오, 구글 등에 의존해왔는데 개인적으로 이러한 난립은 개발자에게 도움이 되지 않는다고 생각되어 이 프로젝트를 만들게 됐습니다.
+
+`kor-mapi`를 사용하면 지도 코드를 한 번만 작성하고 설정 하나만 바꿔 공급자를 전환할 수 있습니다. 구글 지도 완성도를 고려하여 세 가지를 지원하고 있으나 향후 VWorld 등 다른
+공급자로도 확대할 생각이 있습니다.
+
+## 현재 상태: v0.1 — Tier 1 구현 완료
+
+아래 기능들이 세 공급자 모두에서 동일하게 동작합니다:
+
+| #   | 기능                      | API                                                                           |
+| --- | ------------------------- | ----------------------------------------------------------------------------- |
+| 1   | **초기화**                | `KorMap.create({ provider, container, apiKey, center, zoom })`                |
+| 2   | **카메라 / 뷰포트**       | `setCenter`, `getCenter`, `setZoom`, `getZoom`, `fitBounds`, `panTo`, `panBy` |
+| 3   | **지도 유형**             | `setMapType(MapTypeId.ROADMAP \| SATELLITE \| HYBRID \| TERRAIN)`             |
+| 4   | **마커**                  | `new Marker({ position, icon, title, draggable, opacity, zIndex })`           |
+| 5   | **정보창**                | `new InfoWindow({ content })` → `open(map, anchor?)` / `close()`              |
+| 6   | **벡터 오버레이**         | `Polyline`, `Polygon`, `Circle`, `Rectangle` — 통합 선/채우기 스타일          |
+| 7   | **이벤트**                | `map.on('click' \| 'zoom_changed' \| 'center_changed' \| 'idle' \| ...)`      |
+| 8   | **커스텀 타일 레이어**    | `new TileLayer({ getTileUrl(coord, zoom) })` — 브이월드 등 지원               |
+| 9   | **마커 클러스터링**       | `new MarkerClusterer(map, markers, options)` — 격자 기반, 외부 의존성 없음    |
+
+**공급자별 주요 사항:**
+
+- 줌은 네이버/구글을 표준으로 7 ~ 19로 제한했으며 카카오는 역방향 1–13 범위로 내부적으로 변환됩니다. 세 지도의 줌 배율이 완전히 동일하지는 않으므로 약간의 오차는 감안하세요.
+- 카카오 SDK에 없는 `idle` 이벤트는 `center_changed` + `zoom_changed`를 150ms 디바운스하여 합성합니다.
+- 구글 마커는 현재 권고되는 `AdvancedMarkerElement`를 사용합니다. `mapId`는 기본값으로 `'DEMO_MAP_ID'`가 사용되며, 운영 환경에서는 `config.mapId`를 설정하시기 바랍니다.
+- 카카오에는 독립적인 지형도 기본 지도가 없어 `MapTypeId.TERRAIN`은 `ROADMAP`으로 대체됩니다.
+- `map.native`로 기반 공급자 객체(`naver.maps.Map`, `kakao.maps.Map`, `google.maps.Map`)에 직접 접근할 수 있습니다.
+
+## 범위 외: 지오코딩, 검색, 경로 탐색
+
+지오코딩, 주소 검색, 장소/POI 검색, 경로 탐색은 **`kor-mapi` 통합 API에서 의도적으로 제외**됩니다.
+
+각 공급자의 서비스 API는 데이터 모델, 결과 구조, 전송 방식(클라이언트 SDK vs REST 전용)이 근본적으로 다릅니다. 공통 분모 파사드를 만들면 각 공급자가 제공하는 고유한 기능(지번/도로명 주소 상세 정보, POI 카테고리 체계 등)을 숨기고 오히려 개발자에게 불필요한 학습 비용을 강요하게 됩니다. 또한 네이버와 카카오의 경로 탐색은 REST 전용이며 서버 측 프록시가 필요하므로 지도 렌더링과는 다른 통합 방식을 요구합니다.
+
+`map.native`를 통해 각 공급자의 서비스에 직접 접근하세요:
+
+```ts
+// 카카오 — 한국 주소 및 POI 검색에 최적
+const map = await KorMap.create<'kakao'>({ provider: 'kakao', ... });
+const geocoder = new window.kakao.maps.services.Geocoder();
+const places = new window.kakao.maps.services.Places();
+
+// 구글 — 글로벌 커버리지
+const map = await KorMap.create<'google'>({ provider: 'google', ... });
+const geocoder = new window.google.maps.Geocoder();
+```
+
+## 미구현 항목 (Tier 2 / v0.2+)
+
+교통 레이어, 히트맵, 그리기 도구, 지도 스타일, 고도, 거리뷰/로드뷰, 기울기/방향, 다국어 전환, 대중교통 레이어, 행정구역 경계 오버레이, 경로 탐색.
+
+## 사용법
+
+```ts
+import { KorMap, Marker, InfoWindow, MapTypeId } from "kor-mapi";
+
+const map = await KorMap.create({
+  provider: "kakao", // 'naver' | 'kakao' | 'google'
+  container: "map",
+  apiKey: "YOUR_APP_KEY",
+  center: { lat: 37.5665, lng: 126.978 },
+  zoom: 12,
+});
+
+const marker = new Marker({ position: { lat: 37.5665, lng: 126.978 } });
+marker.setMap(map);
+
+const iw = new InfoWindow({ content: "<b>서울시청</b>" });
+marker.on("click", () => iw.open(map, marker));
+
+map.on("zoom_changed", () => console.log(map.getZoom()));
+```
+
+네이버, 카카오, 구글에 따라 `provider` 값만 바꾸면 되며 나머지 코드는 그대로 유지됩니다.
+
+## 데모
+
+각 공급자 모두 API 키가 필요하므로 각 개발 콘솔에서 앱을 등록하고 키를 발급한 다음
+`.env` 파일에 설정하세요.
+
+```bash
+cp demo/.env.example demo/.env
+# .env 파일에 API 키를 하나 이상 설정하세요
+npm run demo
+# http://localhost:3000 에서 확인
+```
+
+데모는 세 공급자를 나란히 표시하며 위치/배율 동기화, 공통 툴바(지도 유형, 마커, 폴리라인, 원), 통합 이벤트 로그를 제공합니다.
+
+## 아키텍처
+
+계층적 어댑터 패턴: `KorMap` 파사드 → `IMapProvider` 인터페이스 → `NaverAdapter` / `KakaoAdapter` / `GoogleAdapter`. 각 어댑터는 SDK 동적 로딩(`<script>` 주입), 좌표 변환, 이벤트 이름 매핑, 공급자별 특이사항을 처리합니다. 운영 의존성 없음 — 세 SDK 모두 런타임에 동적으로 로드됩니다.
+
+```
+src/
+  core/
+    KorMap.ts        ← 파사드 + create() 팩토리
+    types.ts         ← 모든 공개 인터페이스 및 열거형
+    overlays.ts      ← Marker, InfoWindow, Polyline, Polygon, Circle, Rectangle, TileLayer
+    errors.ts        ← KorMapError 계층
+  providers/
+    base/            ← IMapProvider 인터페이스
+    naver/           ← NaverAdapter + NaverLoader
+    kakao/           ← KakaoAdapter + KakaoLoader
+    google/          ← GoogleAdapter + GoogleLoader
+  utils/
+    coordinateUtils.ts  ← 공급자 간 줌 정규화
+```
+
+## 명령어
+
+```bash
+npm run build       # tsup으로 빌드
+npm test            # 테스트 실행 (vitest)
+npm run typecheck   # tsc --noEmit
+npm run demo        # localhost:3000에서 Vite 개발 서버 실행
+```