fix(load-script): submodule 로드 완료 대기 + URL 쉼표 인코딩 수정 (#159)

0.2.0(v2 재작성)에서 submodules 옵션이 무력화되던 두 회귀 수정:
- buildUrl: URLSearchParams가 쉼표를 %2C로 인코딩 → maps-geocoder.js 청크 404. raw 쉼표로 append 복원.
- loadScript: onJSContentLoaded 대기 복원 → submodule attach 완료 후 resolve.

회귀 방지 테스트 7개 포함. Closes #158

Co-authored-by: changgihong <changgihong@users.noreply.github.com>

Author: changgihong

packages/react-naver-maps/src/__tests__/load-script.spec.ts

@@ -1,5 +1,9 @@
 import { describe, test, expect } from 'vitest';
-import { getClientParam } from '../load-script.js';
+import {
+  buildUrl,
+  getClientParam,
+  waitForJsContentLoaded,
+} from '../load-script.js';
 
 describe('getClientParam', () => {
   test('ncpKeyId 전달 시 ["ncpKeyId", value] 반환', () => {
@@ -34,3 +38,86 @@ describe('getClientParam', () => {
     expect(() => getClientParam({} as any)).toThrow('인증 키가 필요합니다');
   });
 });
+
+describe('buildUrl', () => {
+  test('submodules 전달 시 raw `,` 가 URL 에 보존됨 (URL-encoded `%2C` 아님)', () => {
+    const url = buildUrl({
+      ncpKeyId: 'test-key',
+      submodules: ['geocoder', 'drawing'],
+    });
+    expect(url).toContain('submodules=geocoder,drawing');
+    expect(url).not.toContain('%2C');
+  });
+
+  test('submodules 미전달 시 submodules 쿼리 자체가 추가되지 않음', () => {
+    const url = buildUrl({ ncpKeyId: 'test-key' });
+    expect(url).not.toContain('submodules');
+  });
+
+  test('인증 키 파라미터는 URLSearchParams 통과 (특수문자 안전)', () => {
+    const url = buildUrl({ ncpKeyId: 'a b+c' });
+    expect(url).toContain('ncpKeyId=a+b%2Bc');
+  });
+});
+
+describe('waitForJsContentLoaded', () => {
+  test('jsContentLoaded=true 이면 즉시 resolve', async () => {
+    const maps = { jsContentLoaded: true } as unknown as typeof naver.maps;
+    await expect(waitForJsContentLoaded(maps)).resolves.toBe(maps);
+  });
+
+  test('jsContentLoaded=false 면 onJSContentLoaded 콜백 발화까지 대기', async () => {
+    const maps = {
+      jsContentLoaded: false,
+      onJSContentLoaded: undefined as undefined | (() => void),
+    } as unknown as typeof naver.maps & {
+      onJSContentLoaded: undefined | (() => void);
+    };
+
+    const promise = waitForJsContentLoaded(maps);
+
+    let resolved = false;
+    promise.then(() => {
+      resolved = true;
+    });
+
+    // 콜백 발화 전: promise 가 아직 pending 이어야 함
+    await Promise.resolve();
+    expect(resolved).toBe(false);
+
+    // 콜백 발화
+    maps.onJSContentLoaded?.();
+    await expect(promise).resolves.toBe(maps);
+  });
+
+  test('기존 onJSContentLoaded 핸들러가 있으면 chain 보호 (prev 호출 후 resolve)', async () => {
+    let prevCalled = false;
+    const maps = {
+      jsContentLoaded: false,
+      onJSContentLoaded: () => {
+        prevCalled = true;
+      },
+    } as unknown as typeof naver.maps;
+
+    const promise = waitForJsContentLoaded(maps);
+
+    // waitForJsContentLoaded 가 새로 등록한 콜백 발화
+    (maps as any).onJSContentLoaded();
+    await promise;
+
+    expect(prevCalled).toBe(true);
+  });
+
+  test('기존 onJSContentLoaded 핸들러가 throw 해도 waitForJsContentLoaded 의 Promise resolve 는 진행됨', async () => {
+    const maps = {
+      jsContentLoaded: false,
+      onJSContentLoaded: () => {
+        throw new Error('prev throws');
+      },
+    } as unknown as typeof naver.maps;
+
+    const promise = waitForJsContentLoaded(maps);
+    (maps as any).onJSContentLoaded();
+    await expect(promise).resolves.toBe(maps);
+  });
+});

packages/react-naver-maps/src/load-script.ts

@@ -54,13 +54,19 @@ export function getClientParam(options: LoadOptions): [string, string] {
   );
 }
 
-function buildUrl(options: LoadOptions): string {
+/** @internal exported for tests */
+export function buildUrl(options: LoadOptions): string {
   const [paramName, paramValue] = getClientParam(options);
   const params = new URLSearchParams({ [paramName]: paramValue });
+  let url = `https://oapi.map.naver.com/openapi/v3/maps.js?${params.toString()}`;
   if (options.submodules?.length) {
-    params.set('submodules', options.submodules.join(','));
+    // Naver Maps 로더는 submodules 쿼리 값을 raw `,` 로 split 해서
+    // 각 `maps-{name}.js` 청크를 로드합니다. URLSearchParams 가 `,` 를
+    // `%2C` 로 percent-encode 하면 로더가 전체 문자열을 하나의 submodule
+    // 이름으로 취급해 `maps-{joined}%2C{...}.js` 에 요청 → 404 발생.
+    url += `&submodules=${options.submodules.join(',')}`;
   }
-  return `https://oapi.map.naver.com/openapi/v3/maps.js?${params.toString()}`;
+  return url;
 }
 
 function cacheKey(options: LoadOptions): string {
@@ -69,6 +75,26 @@ function cacheKey(options: LoadOptions): string {
   return `${paramValue}:${sub}`;
 }
 
+/** @internal exported for tests */
+export function waitForJsContentLoaded(
+  maps: typeof naver.maps,
+): Promise<typeof naver.maps> {
+  if (maps.jsContentLoaded) return Promise.resolve(maps);
+  return new Promise((resolve) => {
+    const prev = maps.onJSContentLoaded;
+    maps.onJSContentLoaded = () => {
+      if (typeof prev === 'function') {
+        try {
+          prev();
+        } catch {
+          // chained handler 의 에러가 submodule resolution 을 막지 않도록 swallow
+        }
+      }
+      resolve(maps);
+    };
+  });
+}
+
 export function loadScript(options: LoadOptions): Promise<typeof naver.maps> {
   if (typeof document === 'undefined') {
     return new Promise<typeof naver.maps>(() => {});
@@ -80,7 +106,7 @@ export function loadScript(options: LoadOptions): Promise<typeof naver.maps> {
 
   const promise = new Promise<typeof naver.maps>((resolve, reject) => {
     if (typeof naver !== 'undefined' && naver.maps) {
-      resolve(naver.maps);
+      waitForJsContentLoaded(naver.maps).then(resolve);
       return;
     }
 
@@ -89,7 +115,7 @@ export function loadScript(options: LoadOptions): Promise<typeof naver.maps> {
     script.async = true;
     script.addEventListener('load', () => {
       if (typeof naver !== 'undefined' && naver.maps) {
-        resolve(naver.maps);
+        waitForJsContentLoaded(naver.maps).then(resolve);
       } else {
         reject(new Error('naver.maps not available after script load'));
       }