slick-address-kr 1.0.4 → 2.0.1

package/dist/react/index.cjs

@@ -0,0 +1,639 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/react/index.tsx
+var react_exports = {};
+__export(react_exports, {
+  KoreanAddressFinderView: () => KoreanAddressFinderView,
+  useKoreanAddress: () => useKoreanAddress
+});
+module.exports = __toCommonJS(react_exports);
+var import_react = require("react");
+
+// src/constants.ts
+var DEFAULT_ENDPOINT = "https://business.juso.go.kr/addrlink/addrLinkApi.do";
+var API_KEY_ISSUE_URL = "https://business.juso.go.kr/jst/jstAddressApiApplicationWrite";
+
+// src/errors.ts
+var JusoApiError = class _JusoApiError extends Error {
+  constructor(code, apiMessage) {
+    const userMessage = describeJusoError(code, apiMessage);
+    super(`[${code}] ${apiMessage}`);
+    this.name = "JusoApiError";
+    this.code = code;
+    this.userMessage = userMessage;
+    this.isInputError = isInputErrorCode(code);
+    Object.setPrototypeOf(this, _JusoApiError.prototype);
+  }
+};
+var INPUT_ERROR_MESSAGES = {
+  // 검색어가 입력되지 않았습니다.
+  E0005: "\uAC80\uC0C9\uC5B4\uB97C \uC785\uB825\uD574 \uC8FC\uC138\uC694.",
+  // 주소를 상세히 입력해 주시기 바랍니다. ('서울', '서울시'처럼 시도명만 넣은 경우)
+  E0006: "\uC8FC\uC18C\uB97C \uC870\uAE08 \uB354 \uC790\uC138\uD788 \uC785\uB825\uD574 \uC8FC\uC138\uC694. (\uC608: \uD310\uAD50\uC5ED\uB85C 235)",
+  // 검색어는 두글자 이상 입력되어야 합니다.
+  E0008: "\uB450 \uAE00\uC790 \uC774\uC0C1 \uC785\uB825\uD574 \uC8FC\uC138\uC694.",
+  // 검색어는 문자와 숫자 같이 입력되어야 합니다. (숫자만 입력한 경우)
+  E0009: "\uB3C4\uB85C\uBA85\uC774\uB098 \uAC74\uBB3C\uBA85\uC744 \uD568\uAED8 \uC785\uB825\uD574 \uC8FC\uC138\uC694.",
+  // 특수문자+숫자만으로는 검색이 불가능 합니다.
+  E0012: "\uB3C4\uB85C\uBA85\uC774\uB098 \uAC74\uBB3C\uBA85\uC744 \uD568\uAED8 \uC785\uB825\uD574 \uC8FC\uC138\uC694.",
+  // SQL 예약어 또는 특수문자( %,=,>,<,[,] )는 검색이 불가능 합니다.
+  E0013: "\uD2B9\uC218\uBB38\uC790(%, =, <, > \uB4F1)\uB97C \uBE7C\uACE0 \uB2E4\uC2DC \uC785\uB825\uD574 \uC8FC\uC138\uC694."
+};
+function isInputErrorCode(code) {
+  return Object.prototype.hasOwnProperty.call(INPUT_ERROR_MESSAGES, code);
+}
+function describeJusoError(code, apiMessage) {
+  if (isInputErrorCode(code)) return INPUT_ERROR_MESSAGES[code];
+  switch (code) {
+    // 승인되지 않은 KEY 입니다. (키가 틀렸거나 비어 있는 경우)
+    case "E0001":
+      return `\uC2B9\uC778\uD0A4\uAC00 \uC62C\uBC14\uB974\uC9C0 \uC54A\uAC70\uB098 \uC774 \uB3C4\uBA54\uC778\uC5D0\uC11C \uD5C8\uC6A9\uB418\uC9C0 \uC54A\uC558\uC2B5\uB2C8\uB2E4. \uBC1C\uAE09\uBC1B\uC740 \uD0A4\uB97C \uADF8\uB300\uB85C \uB123\uC5C8\uB294\uC9C0, \uBC1C\uAE09 \uC2DC \uB4F1\uB85D\uD55C \uB3C4\uBA54\uC778\uACFC \uD604\uC7AC \uC2E4\uD589 \uC911\uC778 \uB3C4\uBA54\uC778\uC774 \uAC19\uC740\uC9C0 \uD655\uC778\uD558\uC138\uC694. \uBC1C\uAE09/\uC218\uC815: ${API_KEY_ISSUE_URL}`;
+    default:
+      return `\uC8FC\uC18C \uAC80\uC0C9\uC5D0 \uC2E4\uD328\uD588\uC2B5\uB2C8\uB2E4. (${code}) ${apiMessage}`.trim();
+  }
+}
+
+// src/api-client.ts
+var AddressApiClient = class {
+  constructor(options = {}) {
+    this.apiKey = options.apiKey ?? "";
+    this.endpoint = options.endpoint ?? DEFAULT_ENDPOINT;
+    this.usesDefaultEndpoint = this.endpoint === DEFAULT_ENDPOINT;
+    this.fetchFn = options.fetchFn ?? globalThis.fetch.bind(globalThis);
+  }
+  async search(keyword, options = {}) {
+    const trimmed = keyword?.trim() ?? "";
+    if (trimmed.length === 0) {
+      return { results: [], totalCount: 0 };
+    }
+    if (this.usesDefaultEndpoint && !this.apiKey) {
+      throw new Error(
+        `API \uD0A4\uAC00 \uC124\uC815\uB418\uC9C0 \uC54A\uC558\uC2B5\uB2C8\uB2E4. KoreanAddressFinder \uC0DD\uC131 \uC2DC apiKey \uC635\uC158\uC744 \uC804\uB2EC\uD558\uAC70\uB098, endpoint \uC635\uC158\uC73C\uB85C \uC790\uCCB4 \uD504\uB85D\uC2DC \uC11C\uBC84\uB97C \uC9C0\uC815\uD558\uC138\uC694. \uD0A4 \uBC1C\uAE09: ${API_KEY_ISSUE_URL}`
+      );
+    }
+    const params = new URLSearchParams({
+      currentPage: String(options.currentPage ?? 1),
+      countPerPage: String(options.countPerPage ?? 10),
+      keyword: trimmed,
+      resultType: "json"
+    });
+    if (this.usesDefaultEndpoint) {
+      params.set("confmKey", this.apiKey);
+    }
+    const response = await this.fetchFn(`${this.endpoint}?${params.toString()}`, {
+      method: "GET",
+      signal: options.signal
+    });
+    if (!response.ok) {
+      throw new Error(`\uC8FC\uC18C \uAC80\uC0C9 \uC694\uCCAD\uC774 \uC2E4\uD328\uD588\uC2B5\uB2C8\uB2E4 (HTTP ${response.status})`);
+    }
+    const data = await response.json();
+    return this.toSearchResult(data);
+  }
+  toSearchResult(data) {
+    const { errorCode, errorMessage } = data.results.common;
+    if (errorCode !== "0") {
+      throw new JusoApiError(errorCode, errorMessage);
+    }
+    const juso = data.results.juso ?? [];
+    const results = juso.map((item) => ({
+      roadAddress: item.roadAddr,
+      jibunAddress: item.jibunAddr,
+      zipCode: item.zipNo,
+      buildingName: item.bdNm || "",
+      sido: item.siNm,
+      sigungu: item.sggNm,
+      bname: item.emdNm,
+      extraAddress: buildExtraAddress(item),
+      codes: toCodes(item)
+    }));
+    return {
+      results,
+      totalCount: Number.parseInt(data.results.common.totalCount, 10) || 0
+    };
+  }
+};
+function toCodes(item) {
+  return {
+    admCd: item.admCd,
+    rnMgtSn: item.rnMgtSn,
+    udrtYn: item.udrtYn,
+    buldMnnm: item.buldMnnm,
+    buldSlno: item.buldSlno
+  };
+}
+function buildExtraAddress(item) {
+  const extras = [];
+  if (item.bdNm) extras.push(item.bdNm);
+  if (item.detBdNmList) extras.push(item.detBdNmList);
+  return extras.join(", ");
+}
+
+// src/address-finder.ts
+var MIN_AUTOCOMPLETE_LENGTH = 2;
+var instanceCounter = 0;
+var KoreanAddressFinder = class {
+  constructor(options = {}) {
+    // instanceCounter는 모듈 단위(=번들 단위)로 격리된다. 한 페이지에 ESM과
+    // IIFE 번들이 동시에 로드되면 카운터가 각각 0부터 시작해 id가 겹칠 수
+    // 있으므로, 짧은 무작위 접미사를 더해 번들 경계를 넘는 충돌을 막는다.
+    this.instanceId = `kaf-${++instanceCounter}-${Math.random().toString(36).slice(2, 8)}`;
+    this.activeIndex = -1;
+    this.container = null;
+    this.searchInput = null;
+    this.resultsContainer = null;
+    this.detailInput = null;
+    this.isOpen = false;
+    this.debounceTimer = null;
+    this.abortController = null;
+    this.selected = null;
+    this.results = [];
+    this.listeners = [];
+    this.destroyed = false;
+    this.apiClient = new AddressApiClient({
+      apiKey: options.apiKey,
+      endpoint: options.endpoint,
+      fetchFn: options.fetchFn
+    });
+    this.options = {
+      apiKey: options.apiKey || "",
+      countPerPage: options.countPerPage || 10,
+      currentPage: options.currentPage || 1,
+      containerId: options.containerId || "address-finder-container",
+      onSelect: options.onSelect || (() => {
+      }),
+      showDetailInput: options.showDetailInput !== false,
+      customClass: options.customClass || "",
+      autocompleteMode: options.autocompleteMode || false,
+      endpoint: options.endpoint ?? "",
+      fetchFn: options.fetchFn
+    };
+  }
+  /**
+   * 주소 검색 UI 초기화
+   */
+  init(targetElement) {
+    if (this.container) {
+      this.teardown();
+    }
+    this.destroyed = false;
+    if (targetElement) {
+      this.container = targetElement;
+    } else {
+      this.container = document.getElementById(this.options.containerId);
+    }
+    if (!this.container) {
+      throw new Error(`Container element not found: ${this.options.containerId}`);
+    }
+    this.render();
+    this.attachEventListeners();
+  }
+  /**
+   * UI 렌더링
+   */
+  render() {
+    if (!this.container) return;
+    const className = this.options.customClass ? ` ${this.escapeHtml(this.options.customClass)}` : "";
+    const listId = `${this.instanceId}-listbox`;
+    this.container.innerHTML = `
+      <div class="kaf-wrapper${className}">
+        <div class="kaf-search-box">
+          <input
+            type="text"
+            class="kaf-search-input"
+            placeholder="\uC8FC\uC18C\uB97C \uC785\uB825\uD558\uC138\uC694 (\uC608: \uD310\uAD50\uC5ED\uB85C 235)"
+            autocomplete="off"
+            role="combobox"
+            aria-autocomplete="list"
+            aria-expanded="false"
+            aria-controls="${listId}"
+          />
+          <button type="button" class="kaf-search-btn">\uAC80\uC0C9</button>
+        </div>
+        <div class="kaf-results" style="display: none;">
+          <div class="kaf-results-header">
+            <span class="kaf-results-count" aria-live="polite">\uAC80\uC0C9 \uACB0\uACFC</span>
+            <button type="button" class="kaf-close-btn" aria-label="\uAC80\uC0C9 \uACB0\uACFC \uB2EB\uAE30">\xD7</button>
+          </div>
+          <div class="kaf-results-list" id="${listId}" role="listbox" aria-label="\uC8FC\uC18C \uAC80\uC0C9 \uACB0\uACFC"></div>
+          <div class="kaf-results-message"></div>
+        </div>
+        ${this.options.showDetailInput ? `
+          <div class="kaf-detail-box" style="display: none;">
+            <input
+              type="text"
+              class="kaf-detail-input"
+              placeholder="\uC0C1\uC138\uC8FC\uC18C\uB97C \uC785\uB825\uD558\uC138\uC694"
+              aria-label="\uC0C1\uC138\uC8FC\uC18C"
+            />
+          </div>
+        ` : ""}
+        <div class="kaf-selected-address" style="display: none;"></div>
+      </div>
+    `;
+    this.searchInput = this.container.querySelector(".kaf-search-input");
+    this.resultsContainer = this.container.querySelector(".kaf-results");
+    this.detailInput = this.container.querySelector(".kaf-detail-input");
+  }
+  /**
+   * 이벤트를 등록하면서 해제 함수를 모아둔다.
+   * destroy()가 이 목록만 비우면 리스너가 남지 않는다.
+   */
+  on(target, type, handler) {
+    target.addEventListener(type, handler);
+    this.listeners.push(() => target.removeEventListener(type, handler));
+  }
+  /**
+   * 이벤트 리스너 등록
+   */
+  attachEventListeners() {
+    if (!this.container) return;
+    const searchBtn = this.container.querySelector(".kaf-search-btn");
+    if (searchBtn) {
+      this.on(searchBtn, "click", () => void this.search());
+    }
+    if (this.searchInput) {
+      this.on(
+        this.searchInput,
+        "keydown",
+        (e) => this.handleKeydown(e)
+      );
+      if (this.options.autocompleteMode) {
+        this.on(this.searchInput, "input", () => this.handleAutocomplete());
+      }
+    }
+    const closeBtn = this.container.querySelector(".kaf-close-btn");
+    if (closeBtn) {
+      this.on(closeBtn, "click", () => this.closeResults());
+    }
+    if (this.detailInput) {
+      this.on(this.detailInput, "input", () => this.emitSelect("detail-change"));
+    }
+    this.on(document, "click", (e) => {
+      if (this.isOpen && !this.container?.contains(e.target)) {
+        this.closeResults();
+      }
+    });
+  }
+  handleKeydown(event) {
+    const count = this.results.length;
+    switch (event.key) {
+      case "ArrowDown":
+        if (!this.isOpen || count === 0) return;
+        event.preventDefault();
+        this.setActiveIndex(this.activeIndex >= count - 1 ? 0 : this.activeIndex + 1);
+        return;
+      case "ArrowUp":
+        if (!this.isOpen || count === 0) return;
+        event.preventDefault();
+        this.setActiveIndex(this.activeIndex <= 0 ? count - 1 : this.activeIndex - 1);
+        return;
+      case "Enter":
+        event.preventDefault();
+        if (this.isOpen && this.activeIndex >= 0 && this.results[this.activeIndex]) {
+          this.selectAddress(this.results[this.activeIndex]);
+        } else {
+          void this.search();
+        }
+        return;
+      case "Escape":
+        if (!this.isOpen) return;
+        event.preventDefault();
+        this.closeResults();
+        return;
+      default:
+    }
+  }
+  /**
+   * 활성 항목을 옮기고 ARIA 속성과 하이라이트를 함께 갱신한다.
+   * -1은 활성 항목 없음을 뜻한다.
+   */
+  setActiveIndex(index) {
+    this.activeIndex = index;
+    const options = this.container?.querySelectorAll(".kaf-result-item");
+    options?.forEach((option, i) => {
+      const active = i === index;
+      if (active) {
+        option.setAttribute("aria-selected", "true");
+      } else {
+        option.removeAttribute("aria-selected");
+      }
+      option.classList.toggle("kaf-result-item--active", active);
+      if (active) {
+        option.scrollIntoView?.({ block: "nearest" });
+      }
+    });
+    if (this.searchInput) {
+      const active = index >= 0 ? options?.[index] : void 0;
+      if (active) {
+        this.searchInput.setAttribute("aria-activedescendant", active.id);
+      } else {
+        this.searchInput.removeAttribute("aria-activedescendant");
+      }
+    }
+  }
+  /**
+   * 자동완성 처리 (디바운스 적용)
+   */
+  handleAutocomplete() {
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+    }
+    const keyword = this.searchInput?.value.trim() ?? "";
+    if (keyword.length < MIN_AUTOCOMPLETE_LENGTH) {
+      this.debounceTimer = null;
+      this.abortController?.abort();
+      this.abortController = null;
+      this.closeResults();
+      return;
+    }
+    this.debounceTimer = window.setTimeout(() => {
+      this.search();
+    }, 300);
+  }
+  /**
+   * 현재 입력값으로 주소를 검색한다.
+   * 진행 중이던 이전 요청은 취소되며, 취소된 응답은 무시된다.
+   */
+  async search() {
+    const keyword = this.searchInput?.value.trim();
+    if (!keyword) return;
+    this.abortController?.abort();
+    const controller = new AbortController();
+    this.abortController = controller;
+    try {
+      const { results, totalCount } = await this.apiClient.search(keyword, {
+        currentPage: this.options.currentPage,
+        countPerPage: this.options.countPerPage,
+        signal: controller.signal
+      });
+      if (this.abortController !== controller) return;
+      this.displayResults(results, totalCount);
+    } catch (error) {
+      if (this.abortController !== controller) return;
+      if (error instanceof DOMException && error.name === "AbortError") return;
+      if (error instanceof JusoApiError && error.isInputError) {
+        this.showHint(error.userMessage);
+        return;
+      }
+      const message = error instanceof JusoApiError ? error.userMessage : error instanceof Error ? error.message : "\uC8FC\uC18C \uAC80\uC0C9 \uC911 \uC624\uB958\uAC00 \uBC1C\uC0DD\uD588\uC2B5\uB2C8\uB2E4.";
+      this.showError(message);
+    }
+  }
+  /**
+   * 검색 결과 표시
+   */
+  displayResults(results, totalCount) {
+    const resultsList = this.container?.querySelector(".kaf-results-list");
+    const resultsMessage = this.container?.querySelector(".kaf-results-message");
+    const resultsCount = this.container?.querySelector(".kaf-results-count");
+    if (!resultsList || !resultsMessage || !resultsCount) return;
+    this.results = results;
+    if (results.length === 0) {
+      resultsList.innerHTML = "";
+      resultsMessage.innerHTML = '<div class="kaf-no-results">\uAC80\uC0C9 \uACB0\uACFC\uAC00 \uC5C6\uC2B5\uB2C8\uB2E4.</div>';
+    } else {
+      resultsMessage.innerHTML = "";
+      resultsList.innerHTML = results.map(
+        (result, index) => `
+        <div
+          class="kaf-result-item"
+          id="${this.instanceId}-option-${index}"
+          role="option"
+          data-index="${index}"
+        >
+          <div class="kaf-result-main">
+            <span class="kaf-result-type">\uB3C4\uB85C\uBA85</span>
+            <span class="kaf-result-address">${this.escapeHtml(result.roadAddress)}</span>
+          </div>
+          <div class="kaf-result-sub">
+            <span class="kaf-result-type">\uC9C0\uBC88</span>
+            <span class="kaf-result-address">${this.escapeHtml(result.jibunAddress)}</span>
+          </div>
+          <div class="kaf-result-zipcode">\uC6B0\uD3B8\uBC88\uD638: ${this.escapeHtml(result.zipCode)}</div>
+          ${result.buildingName ? `<div class="kaf-result-building">${this.escapeHtml(result.buildingName)}</div>` : ""}
+        </div>
+      `
+      ).join("");
+      resultsList.querySelectorAll(".kaf-result-item").forEach((item, index) => {
+        item.addEventListener("click", () => this.selectAddress(results[index]));
+      });
+    }
+    this.openResults();
+    resultsCount.textContent = "";
+    resultsCount.textContent = results.length === 0 ? "\uAC80\uC0C9 \uACB0\uACFC\uAC00 \uC5C6\uC2B5\uB2C8\uB2E4." : `\uAC80\uC0C9 \uACB0\uACFC (${totalCount}\uAC74)`;
+    this.setActiveIndex(-1);
+  }
+  /**
+   * 주소 선택 처리
+   */
+  selectAddress(address) {
+    if (this.destroyed) return;
+    this.selected = address;
+    const selectedContainer = this.container?.querySelector(".kaf-selected-address");
+    if (selectedContainer) {
+      selectedContainer.innerHTML = `
+        <div class="kaf-selected-content">
+          <div class="kaf-selected-main">
+            <strong>\uB3C4\uB85C\uBA85:</strong> ${this.escapeHtml(address.roadAddress)}
+          </div>
+          <div class="kaf-selected-sub">
+            <strong>\uC6B0\uD3B8\uBC88\uD638:</strong> ${this.escapeHtml(address.zipCode)}
+          </div>
+        </div>
+      `;
+      selectedContainer.style.display = "block";
+    }
+    if (this.options.showDetailInput && this.detailInput) {
+      const detailBox = this.container?.querySelector(".kaf-detail-box");
+      if (detailBox) {
+        detailBox.style.display = "block";
+        this.detailInput.focus();
+      }
+    }
+    this.closeResults();
+    this.emitSelect("select");
+  }
+  /**
+   * getSelectedAddress()로 최신 상세주소를 채운 뒤 onSelect를 호출한다.
+   * 선택된 주소가 없으면 아무 일도 하지 않는다.
+   */
+  emitSelect(reason) {
+    const address = this.getSelectedAddress();
+    if (!address) return;
+    this.options.onSelect(address, { reason });
+  }
+  /**
+   * 검색 결과 열기
+   */
+  openResults() {
+    if (this.resultsContainer) {
+      this.resultsContainer.style.display = "block";
+      this.isOpen = true;
+      this.searchInput?.setAttribute("aria-expanded", "true");
+    }
+  }
+  /**
+   * 검색 결과 닫기
+   */
+  closeResults() {
+    if (this.resultsContainer) {
+      this.resultsContainer.style.display = "none";
+      this.isOpen = false;
+      this.searchInput?.setAttribute("aria-expanded", "false");
+      this.setActiveIndex(-1);
+    }
+  }
+  /**
+   * 검색어 안내 표시 (두 글자 이상 등)
+   *
+   * 오류가 아니라 고쳐 쓰면 되는 안내라서, 빨간 본문 없이 머리줄 한 줄로만
+   * 보여준다. 머리줄은 aria-live라 스크린리더에도 그대로 읽힌다.
+   */
+  showHint(message) {
+    const resultsList = this.container?.querySelector(".kaf-results-list");
+    const resultsMessage = this.container?.querySelector(".kaf-results-message");
+    const resultsCount = this.container?.querySelector(".kaf-results-count");
+    if (!resultsList || !resultsMessage || !resultsCount) return;
+    this.results = [];
+    resultsList.innerHTML = "";
+    resultsMessage.innerHTML = "";
+    this.openResults();
+    resultsCount.textContent = "";
+    resultsCount.textContent = message;
+    this.setActiveIndex(-1);
+  }
+  /**
+   * 에러 표시
+   */
+  showError(message) {
+    const resultsList = this.container?.querySelector(".kaf-results-list");
+    const resultsMessage = this.container?.querySelector(".kaf-results-message");
+    const resultsCount = this.container?.querySelector(".kaf-results-count");
+    if (!resultsList || !resultsMessage || !resultsCount) return;
+    this.results = [];
+    resultsList.innerHTML = "";
+    resultsMessage.innerHTML = `<div class="kaf-error">${this.escapeHtml(message)}</div>`;
+    this.openResults();
+    resultsCount.textContent = "";
+    resultsCount.textContent = message;
+    this.setActiveIndex(-1);
+  }
+  /**
+   * HTML 특수문자 이스케이프 (XSS 방지)
+   */
+  escapeHtml(value) {
+    return String(value ?? "").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+  }
+  /**
+   * 리스너와 진행 중 요청을 정리하고 DOM을 비운다.
+   * destroy()와 init()의 재마운트 양쪽이 공유하는 정리 로직이다.
+   */
+  teardown() {
+    for (const off of this.listeners) off();
+    this.listeners = [];
+    if (this.debounceTimer !== null) {
+      clearTimeout(this.debounceTimer);
+      this.debounceTimer = null;
+    }
+    this.abortController?.abort();
+    this.abortController = null;
+    if (this.container) {
+      this.container.innerHTML = "";
+    }
+    this.selected = null;
+    this.results = [];
+    this.isOpen = false;
+    this.activeIndex = -1;
+    this.searchInput = null;
+    this.resultsContainer = null;
+    this.detailInput = null;
+  }
+  /**
+   * 리스너와 진행 중 요청을 정리하고 DOM을 비운다.
+   * 여러 번 호출해도 안전하다. init()으로 다시 초기화하면 완전히
+   * 재사용할 수 있다 — destroyed 가드는 초기화되지 않은 인스턴스가 아니라
+   * "이 destroy() 호출 이후, 다음 init() 전까지"만 selectAddress()를 막는다.
+   */
+  destroy() {
+    if (this.destroyed) return;
+    this.destroyed = true;
+    this.teardown();
+  }
+  /**
+   * 선택된 주소를 돌려준다. 선택 전이면 null.
+   * detailAddress는 상세주소 입력란의 현재 값이 반영된다.
+   */
+  getSelectedAddress() {
+    if (!this.selected) return null;
+    return {
+      ...this.selected,
+      detailAddress: this.detailInput?.value ?? ""
+    };
+  }
+};
+
+// src/react/index.tsx
+var import_jsx_runtime = require("react/jsx-runtime");
+function useKoreanAddress(options = {}) {
+  const [address, setAddress] = (0, import_react.useState)(null);
+  const [finder, setFinder] = (0, import_react.useState)(null);
+  const optionsRef = (0, import_react.useRef)(options);
+  optionsRef.current = options;
+  const instanceRef = (0, import_react.useRef)(null);
+  const containerRef = (0, import_react.useCallback)((node) => {
+    if (instanceRef.current) {
+      instanceRef.current.destroy();
+      instanceRef.current = null;
+      setFinder(null);
+    }
+    if (!node) return;
+    const instance = new KoreanAddressFinder({
+      ...optionsRef.current,
+      onSelect: (selected, meta) => {
+        setAddress(selected);
+        optionsRef.current.onSelect?.(selected, meta);
+      }
+    });
+    instance.init(node);
+    instanceRef.current = instance;
+    setFinder(instance);
+  }, []);
+  (0, import_react.useEffect)(() => {
+    return () => {
+      instanceRef.current?.destroy();
+      instanceRef.current = null;
+    };
+  }, []);
+  return { containerRef, address, finder };
+}
+function KoreanAddressFinderView({
+  className,
+  ...options
+}) {
+  const { containerRef } = useKoreanAddress(options);
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className, ref: containerRef });
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  KoreanAddressFinderView,
+  useKoreanAddress
+});
+//# sourceMappingURL=index.cjs.map