@apt.today/react-seoul-icons 1.1.0 → 1.2.1

package/README.md

@@ -10,29 +10,18 @@
 
 대한민국 광역자치단체(시/도) 및 기초자치단체(시/군/구) 로고 아이콘을 React 컴포넌트로 제공하는 라이브러리입니다.
 
-🌐 [데모 페이지](https://myriky.github.io/apt-today-react-seoul-icons/)
+[데모 페이지](https://myriky.github.io/apt-today-react-seoul-icons/)
 
-## 지원 행정구역
-
-### 시도 (광역시/도)
+### 데모 사이트 배포
 
-| 시도       | 코드 | 컴포넌트명 |
-| ---------- | ---- | ---------- |
-| 서울특별시 | `11` | `Seoul`    |
-| 부산광역시 | `26` | `Busan`    |
-| 대구광역시 | `27` | `Daegu`    |
-| 인천광역시 | `28` | `Incheon`  |
-| 울산광역시 | `31` | `Ulsan`    |
-| 경기도     | `41` | `Gyeonggi` |
+데모는 **main 브랜치에 push될 때마다** [GitHub Actions](.github/workflows/deploy.yml)가 예제 앱을 빌드해 자동으로 갱신합니다.  
+처음 한 번 저장소 **Settings → Pages**에서 Source를 **GitHub Actions**로 선택해두면, 이후 main에 머지·푸시할 때마다 데모가 자동 배포됩니다.
 
-### 시군구
+로컬에서 수동 배포하려면 (Pages 소스가 gh-pages 브랜치인 경우):
 
-- **서울특별시**: 25개 자치구 (강남구, 종로구, 마포구 등)
-- **경기도**: 13개 시 (수원시, 고양시, 용인시, 화성시, 성남시, 안양시, 광명시, 과천시, 구리시, 남양주시, 하남시, 의왕시, 김포시)
-- **부산광역시**: 해운대구
-- **대구광역시**: 수성구
-- **인천광역시**: 연수구
-- **울산광역시**: 남구
+```bash
+cd example && yarn deploy
+```
 
 ## 설치
 
@@ -40,410 +29,202 @@
 npm install @apt.today/react-seoul-icons
 ```
 
-또는
-
 ```bash
 yarn add @apt.today/react-seoul-icons
 ```
 
 ## 사용법
 
-### 개별 컴포넌트 Import
+### 컴포넌트 직접 사용
+
+아이콘을 직접 import해서 React 컴포넌트로 사용합니다.
 
 ```tsx
-import {
-  Seoul,
-  GangnamGu,
-  JongnoGu,
-  MapoGu,
-} from "@apt.today/react-seoul-icons";
+import { GangnamGu, Seoul, MapoGu } from "@apt.today/react-seoul-icons";
 
 function App() {
   return (
     <div>
       <Seoul width={64} height={64} />
       <GangnamGu className="w-12 h-12" />
-      <JongnoGu style={{ width: 48, height: 48 }} />
-      <MapoGu width={48} height={48} />
+      <MapoGu style={{ width: 48, height: 48 }} />
     </div>
   );
 }
 ```
 
-### 시도 아이콘 사용
-
-```tsx
-import {
-  Seoul,
-  Busan,
-  Incheon,
-  Gyeonggi,
-  getSidoIcon,
-} from "@apt.today/react-seoul-icons";
+### 유틸리티로 동적 조회
 
-function App() {
-  // 직접 Import
-  return <Seoul width={64} height={64} />;
-
-  // 또는 코드로 가져오기
-  const SeoulIcon = getSidoIcon(11);
-  return SeoulIcon && <SeoulIcon width={64} height={64} />;
-}
-```
-
-### 시군구 아이콘 사용
+코드나 이름으로 아이콘을 동적으로 가져올 때는 `utils`를 사용합니다.
 
 ```tsx
-import { getSigunguIcon, getSigunguBySido } from "@apt.today/react-seoul-icons";
+import { utils } from "@apt.today/react-seoul-icons";
 
-function App() {
-  // 코드로 시군구 아이콘 가져오기
-  const GangnamIcon = getSigunguIcon(11680);
+// 코드로 아이콘 가져오기 (시도 2자리 / 시군구 5자리 자동 판별)
+const SeoulIcon = utils.getIcon(11);      // 서울특별시
+const GangnamIcon = utils.getIcon(11680); // 강남구
 
-  // 시도별 시군구 목록 가져오기
-  const seoulDistricts = getSigunguBySido(11);
-  const gyeonggiCities = getSigunguBySido(41);
+// 이름으로 아이콘 검색
+const Icon = utils.findByName("강남구");
+const Icon2 = utils.findByName("강남");
+const Icon3 = utils.findByName("서울특별시 강남구");
+const Icon4 = utils.findByName("서울 강남구");
 
-  return (
-    <div>
-      {GangnamIcon && <GangnamIcon width={48} height={48} />}
-      {seoulDistricts.map((d) => (
-        <d.component key={d.code} width={32} height={32} />
-      ))}
-    </div>
-  );
-}
+// 중복 이름(중구 등)은 region 옵션으로 구분
+const JungGu = utils.findByName("중구", { region: "서울" });
 ```
 
-### 전체 Import (네임스페이스)
+### 지역별 목록 조회
 
 ```tsx
-import * as SeoulIcons from "@apt.today/react-seoul-icons";
+import { utils } from "@apt.today/react-seoul-icons";
 
-function App() {
-  return (
-    <div>
-      <SeoulIcons.Seoul width={64} />
-      <SeoulIcons.GangnamGu width={48} />
-      <SeoulIcons.JongnoGu className="w-12 h-12" />
-    </div>
-  );
-}
-```
-
-### 동적 아이콘 렌더링 (컴포넌트 이름 기반)
+// 시도별 시군구 목록
+const seoulIcons = utils.getByRegion(11);      // 코드로
+const gyeonggiIcons = utils.getByRegion("경기"); // 이름으로
 
-```tsx
-import * as SeoulIcons from "@apt.today/react-seoul-icons";
+// 전체 시도 목록
+const regions = utils.getAllRegions();
 
-const districts = ["GangnamGu", "MapoGu", "JongnoGu"];
+// 전체 시군구 목록
+const allIcons = utils.getAll();
 
-function App() {
+function DistrictList() {
   return (
-    <div className="flex gap-4">
-      {districts.map((name) => {
-        const Icon = SeoulIcons[name as keyof typeof SeoulIcons] as React.FC<
-          React.SVGProps<SVGSVGElement>
-        >;
-        return <Icon key={name} width={48} height={48} />;
-      })}
+    <div className="grid grid-cols-5 gap-4">
+      {seoulIcons.map((icon) => (
+        <div key={icon.code} className="flex flex-col items-center">
+          <icon.component className="w-12 h-12" />
+          <span>{icon.name}</span>
+        </div>
+      ))}
     </div>
   );
 }
 ```
 
-### 행정구역 코드로 아이콘 가져오기 ⭐
+### API 응답에서 동적으로 사용
 
 ```tsx
-import { getSidoIcon, getSigunguIcon } from "@apt.today/react-seoul-icons";
+import { utils } from "@apt.today/react-seoul-icons";
 
-function App() {
-  // 시도 아이콘
-  const SeoulIcon = getSidoIcon(11);
-  const BusanIcon = getSidoIcon(26);
-
-  // 시군구 아이콘
-  const GangnamIcon = getSigunguIcon(11680);
-  const HaeundaeIcon = getSigunguIcon(26350);
+// 행정구역 코드를 받은 경우
+function DistrictIcon({ code }: { code: number }) {
+  const Icon = utils.getIcon(code);
+  if (!Icon) return null;
+  return <Icon width={48} height={48} />;
+}
 
-  return (
-    <div>
-      {SeoulIcon && <SeoulIcon width={64} height={64} />}
-      {GangnamIcon && <GangnamIcon width={48} height={48} />}
-    </div>
-  );
+// 지역명을 받은 경우
+function DistrictIconByName({ name }: { name: string }) {
+  const Icon = utils.findByName(name);
+  if (!Icon) return null;
+  return <Icon width={48} height={48} />;
 }
 ```
 
-### 이름으로 아이콘 가져오기
+## API
 
-```tsx
-import { getSigunguIconByName } from "@apt.today/react-seoul-icons";
-
-// 다양한 형식 지원
-const Icon1 = getSigunguIconByName("강남구"); // ✅
-const Icon2 = getSigunguIconByName("강남"); // ✅
-const Icon3 = getSigunguIconByName("서울특별시 강남구"); // ✅
-
-// 중복되는 이름(남구 등)은 sidoCode 옵션 필요
-const UlsanNam = getSigunguIconByName("남구", { sidoCode: 31 }); // ✅ 울산 남구
-```
+### 아이콘 컴포넌트
 
-### 모든 지역 정보 가져오기
+모든 아이콘 컴포넌트는 `React.SVGProps<SVGSVGElement>`를 지원합니다.
 
 ```tsx
-import {
-  getAllSidoInfo,
-  getAllSigunguInfo,
-  getSigunguBySido,
-} from "@apt.today/react-seoul-icons";
-
-// 모든 시도 정보
-const allSido = getAllSidoInfo();
-
-// 모든 시군구 정보
-const allSigungu = getAllSigunguInfo();
-
-// 특정 시도의 시군구만 가져오기
-const seoulDistricts = getSigunguBySido(11);
-const gyeonggiCities = getSigunguBySido(41);
-
-function App() {
-  return (
-    <div>
-      {seoulDistricts.map((district) => (
-        <div key={district.code}>
-          <district.component width={48} height={48} />
-          <span>{district.name}</span>
-          <code>{district.code}</code>
-        </div>
-      ))}
-    </div>
-  );
-}
+<GangnamGu width={48} height={48} />
+<GangnamGu className="w-12 h-12" />
+<GangnamGu style={{ width: 48 }} />
 ```
 
-## API 레퍼런스
-
-### 시도 관련 함수
-
-| 함수                | 설명                        | 반환 타입               |
-| ------------------- | --------------------------- | ----------------------- |
-| `getSidoIcon(code)` | 시도 코드로 아이콘 가져오기 | `Component \| null`     |
-| `getSidoInfo(code)` | 시도 코드로 정보 가져오기   | `SidoInfo \| undefined` |
-| `getAllSidoInfo()`  | 모든 시도 정보 가져오기     | `SidoInfo[]`            |
-
-### 시군구 관련 함수
+### utils
 
-| 함수                                   | 설명                            | 반환 타입                  |
-| -------------------------------------- | ------------------------------- | -------------------------- |
-| `getSigunguIcon(code)`                 | 시군구 코드로 아이콘 가져오기   | `Component \| null`        |
-| `getSigunguInfo(code)`                 | 시군구 코드로 정보 가져오기     | `SigunguInfo \| undefined` |
-| `getSigunguBySido(sidoCode)`           | 특정 시도의 시군구 목록         | `SigunguInfo[]`            |
-| `getSigunguIconByName(name, options?)` | 이름으로 시군구 아이콘 가져오기 | `Component \| null`        |
-| `getAllSigunguInfo()`                  | 모든 시군구 정보 가져오기       | `SigunguInfo[]`            |
-
-### 기존 호환 함수 (Deprecated)
-
-| 함수                            | 설명                            | 반환 타입                   |
-| ------------------------------- | ------------------------------- | --------------------------- |
-| `getIconByCode(code)`           | 행정구역 코드로 아이콘 가져오기 | `Component \| undefined`    |
-| `getIconByName(name, options?)` | 이름으로 아이콘 가져오기        | `Component \| undefined`    |
-| `getDistrictInfo(code)`         | 행정구역 코드로 정보 가져오기   | `DistrictInfo \| undefined` |
-| `getNameByCode(code)`           | 행정구역 코드로 이름 가져오기   | `string \| undefined`       |
-| `getAllDistrictInfo()`          | 모든 지역 정보 가져오기         | `readonly DistrictInfo[]`   |
-| `getDistrictsByRegion(region)`  | 특정 시/도의 지역 정보          | `DistrictInfo[]`            |
-| `getAllCodes()`                 | 모든 행정구역 코드 목록         | `number[]`                  |
-| `isValidCode(code)`             | 유효한 코드인지 확인            | `boolean`                   |
+| 메서드 | 설명 | 반환 타입 |
+| --- | --- | --- |
+| `utils.getIcon(code)` | 시도/시군구 코드로 아이콘 가져오기 | `IconComponent \| null` |
+| `utils.findByName(name, options?)` | 이름으로 아이콘 검색 | `IconComponent \| null` |
+| `utils.getInfo(code)` | 코드로 상세 정보 가져오기 | `IconInfo \| RegionInfo \| null` |
+| `utils.getByRegion(codeOrName)` | 특정 시도의 시군구 목록 | `IconInfo[]` |
+| `utils.getAllRegions()` | 모든 시도 정보 | `RegionInfo[]` |
+| `utils.getAvailableRegions()` | 아이콘이 있는 시도만 | `RegionInfo[]` |
+| `utils.getRegionsWithIcons()` | 시군구가 있는 시도만 | `RegionInfo[]` |
+| `utils.getAll()` | 모든 시군구 아이콘 정보 | `IconInfo[]` |
+| `utils.isValid(code)` | 유효한 코드인지 확인 | `boolean` |
 
 ### 타입
 
 ```tsx
-import type {
-  SidoCode, // 11 | 26 | 27 | 28 | 31 | 41 | ...
-  SidoInfo, // 시도 정보 객체
-  SigunguCode, // 11110 | 11140 | ...
-  SigunguInfo, // 시군구 정보 객체
-} from "@apt.today/react-seoul-icons";
-```
-
-### SidoInfo 타입
-
-```tsx
-interface SidoInfo {
-  code: SidoCode; // 시도 코드 (예: 11)
-  name: string; // 전체 이름 (예: "서울특별시")
-  shortName: string; // 짧은 이름 (예: "서울")
-  englishName: string; // 영문 이름 (예: "Seoul")
-  component: Component | null;
+import type { IconComponent, IconInfo, RegionInfo } from "@apt.today/react-seoul-icons";
+
+// IconComponent
+type IconComponent = React.ComponentType<React.SVGProps<SVGSVGElement>>;
+
+// IconInfo - 시군구 아이콘 정보
+interface IconInfo {
+  code: number;          // 시군구 코드 (예: 11680)
+  regionCode: number;    // 소속 시도 코드 (예: 11)
+  regionName: string;    // 소속 시도명 (예: "서울특별시")
+  name: string;          // 이름 (예: "강남구")
+  shortName: string;     // 단축명 (예: "강남")
+  componentName: string; // 컴포넌트명 (예: "GangnamGu")
+  component: IconComponent;
 }
-```
 
-### SigunguInfo 타입
-
-```tsx
-interface SigunguInfo {
-  code: SigunguCode; // 시군구 코드 (예: 11680)
-  sidoCode: SidoCode; // 소속 시도 코드 (예: 11)
-  name: string; // 이름 (예: "강남구")
-  shortName: string; // 짧은 이름 (예: "강남")
-  component: Component;
+// RegionInfo - 시도 정보
+interface RegionInfo {
+  code: number;               // 시도 코드 (예: 11)
+  name: string;               // 전체 이름 (예: "서울특별시")
+  shortName: string;          // 단축명 (예: "서울")
+  englishName: string;        // 영문명 (예: "Seoul")
+  component: IconComponent | null;
 }
 ```
 
-## 행정구역 코드표
-
-### 시도 코드
-
-| 코드 | 시도       | 컴포넌트명 |
-| ---- | ---------- | ---------- |
-| `11` | 서울특별시 | `Seoul`    |
-| `26` | 부산광역시 | `Busan`    |
-| `27` | 대구광역시 | `Daegu`    |
-| `28` | 인천광역시 | `Incheon`  |
-| `31` | 울산광역시 | `Ulsan`    |
-| `41` | 경기도     | `Gyeonggi` |
-
-### 서울특별시 시군구 (25개)
-
-| 코드    | 행정구   | 컴포넌트명       |
-| ------- | -------- | ---------------- |
-| `11110` | 종로구   | `JongnoGu`       |
-| `11140` | 중구     | `JungGu`         |
-| `11170` | 용산구   | `YongsanGu`      |
-| `11200` | 성동구   | `SeongdongGu`    |
-| `11215` | 광진구   | `GwangjinGu`     |
-| `11230` | 동대문구 | `DongdaemunGu`   |
-| `11260` | 중랑구   | `JungnangGu`     |
-| `11290` | 성북구   | `SeongbukGu`     |
-| `11305` | 강북구   | `GangbukGu`      |
-| `11320` | 도봉구   | `DobongGu`       |
-| `11350` | 노원구   | `NowonGu`        |
-| `11380` | 은평구   | `EunpyeongGu`    |
-| `11410` | 서대문구 | `SeodaemunGu`    |
-| `11440` | 마포구   | `MapoGu`         |
-| `11470` | 양천구   | `YangcheonGu`    |
-| `11500` | 강서구   | `GangseoGu`      |
-| `11530` | 구로구   | `GuroGu`         |
-| `11545` | 금천구   | `GeumcheonGu`    |
-| `11560` | 영등포구 | `YeongdeungpoGu` |
-| `11590` | 동작구   | `DongjakGu`      |
-| `11620` | 관악구   | `GwanakGu`       |
-| `11650` | 서초구   | `SeochoGu`       |
-| `11680` | 강남구   | `GangnamGu`      |
-| `11710` | 송파구   | `SongpaGu`       |
-| `11740` | 강동구   | `GangdongGu`     |
-
-### 경기도 시군구 (13개)
-
-| 코드    | 시군구   | 컴포넌트명      |
-| ------- | -------- | --------------- |
-| `41110` | 수원시   | `SuwonSi`       |
-| `41130` | 성남시   | `SeongnamSi`    |
-| `41170` | 안양시   | `AnyangSi`      |
-| `41210` | 광명시   | `GwangmyeongSi` |
-| `41280` | 고양시   | `GoyangSi`      |
-| `41290` | 과천시   | `GwacheonSi`    |
-| `41310` | 구리시   | `GuriSi`        |
-| `41360` | 남양주시 | `NamyangjuSi`   |
-| `41430` | 의왕시   | `UiwangSi`      |
-| `41450` | 하남시   | `HanamSi`       |
-| `41460` | 용인시   | `YonginSi`      |
-| `41570` | 김포시   | `GimpoSi`       |
-| `41590` | 화성시   | `HwaseongSi`    |
-
-### 부산광역시 시군구
-
-| 코드    | 시군구   | 컴포넌트명   |
-| ------- | -------- | ------------ |
-| `26350` | 해운대구 | `HaeundaeGu` |
-
-### 대구광역시 시군구
-
-| 코드    | 시군구 | 컴포넌트명  |
-| ------- | ------ | ----------- |
-| `27260` | 수성구 | `SuseongGu` |
-
-### 인천광역시 시군구
-
-| 코드    | 시군구 | 컴포넌트명 |
-| ------- | ------ | ---------- |
-| `28185` | 연수구 | `YeonsuGu` |
-
-### 울산광역시 시군구
-
-| 코드    | 시군구 | 컴포넌트명 |
-| ------- | ------ | ---------- |
-| `31140` | 남구   | `NamGu`    |
-
-## Props
-
-모든 컴포넌트는 SVG 요소의 표준 props를 지원합니다:
-
-```tsx
-interface IconProps extends React.SVGProps<SVGSVGElement> {}
-```
-
-일반적으로 사용되는 props:
-
-- `className`: CSS 클래스명
-- `style`: 인라인 스타일
-- `width`: 너비
-- `height`: 높이
-- `fill`: 색상 (일부 아이콘은 고정 색상)
-- `onClick`: 클릭 이벤트 핸들러
-
-## 예제
+## 지원 행정구역
 
-### Tailwind CSS와 함께 사용
+### 시도 (광역시/도)
 
-```tsx
-import { GangnamGu } from "@apt.today/react-seoul-icons";
+| 시도 | 코드 | 컴포넌트명 |
+| --- | --- | --- |
+| 서울특별시 | `11` | `Seoul` |
+| 부산광역시 | `26` | `Busan` |
+| 대구광역시 | `27` | `Daegu` |
+| 인천광역시 | `28` | `Incheon` |
+| 울산광역시 | `31` | `Ulsan` |
+| 경기도 | `41` | `Gyeonggi` |
 
-function Example() {
-  return <GangnamGu className="w-16 h-16 text-blue-500 hover:text-blue-700" />;
-}
-```
+### 시군구
 
-### API 응답에서 동적으로 사용
+- **서울특별시**: 25개 자치구 (강남구, 종로구, 마포구 등)
+- **경기도**: 14개 시 (수원시, 고양시, 용인시, 화성시, 성남시, 안양시, 광명시, 과천시, 구리시, 남양주시, 하남시, 의왕시, 김포시, 파주시)
+- **부산광역시**: 해운대구
+- **대구광역시**: 수성구
+- **인천광역시**: 연수구
+- **울산광역시**: 남구
 
-```tsx
-import { getSidoIcon, getSigunguIcon } from "@apt.today/react-seoul-icons";
+## v1에서 마이그레이션
 
-// API에서 행정구역 코드를 받은 경우
-function DistrictIcon({ code }: { code: number }) {
-  const Icon = getSigunguIcon(code);
-  if (!Icon) return null;
-  return <Icon width={48} height={48} />;
-}
+v2에서는 API가 `utils` 네임스페이스로 통합되었습니다.
 
-// 시도 아이콘
-function SidoIcon({ code }: { code: number }) {
-  const Icon = getSidoIcon(code);
-  if (!Icon) return null;
-  return <Icon width={64} height={64} />;
-}
-```
+| v1 | v2 |
+| --- | --- |
+| `getSidoIcon(11)` | `utils.getIcon(11)` |
+| `getSigunguIcon(11680)` | `utils.getIcon(11680)` |
+| `getIconByCode(11680)` | `utils.getIcon(11680)` |
+| `getIconByName("강남구")` | `utils.findByName("강남구")` |
+| `getSigunguIconByName("강남구")` | `utils.findByName("강남구")` |
+| `getAllDistrictInfo()` | `utils.getAll()` |
+| `getAllSigunguInfo()` | `utils.getAll()` |
+| `getDistrictsByRegion("서울")` | `utils.getByRegion("서울")` |
+| `getSigunguBySido(11)` | `utils.getByRegion(11)` |
+| `getAllSidoInfo()` | `utils.getAllRegions()` |
+| `type SidoInfo` | `type RegionInfo` |
+| `type SigunguInfo` | `type IconInfo` |
+| `type DistrictInfo` | `type IconInfo` |
 
-### 지역 목록 렌더링
+아이콘 컴포넌트의 직접 import는 변경 없이 동일합니다:
 
 ```tsx
-import { getSigunguBySido } from "@apt.today/react-seoul-icons";
-
-function DistrictList() {
-  const seoulDistricts = getSigunguBySido(11);
-
-  return (
-    <div className="grid grid-cols-5 gap-4">
-      {seoulDistricts.map((district) => (
-        <div key={district.code} className="flex flex-col items-center">
-          <district.component className="w-12 h-12" />
-          <span>{district.name}</span>
-        </div>
-      ))}
-    </div>
-  );
-}
+// v1과 v2 모두 동일
+import { GangnamGu, Seoul } from "@apt.today/react-seoul-icons";
 ```
 
 ## 라이선스
@@ -456,7 +237,7 @@ function DistrictList() {
 
 본 라이브러리의 소스 코드는 MIT 라이선스를 따릅니다.
 
-자세한 내용은 [LICENSE](./LICENSE) 파일을 참고하세요
+자세한 내용은 [LICENSE](./LICENSE) 파일을 참고하세요.
 
 ## About apt.today
 
@@ -464,12 +245,6 @@ function DistrictList() {
 
 **apt.today**는 부동산 정보를 제공하는 서비스로, 전국 지자체별 고시공고문, 모집공고문, 토지거래허가내역을 비롯한 다양한 아파트 관련 정보를 확인 할 수 있는 플랫폼입니다.
 
-본 아이콘 라이브러리는 apt.today 서비스에서 각 행정구역의 데이터를 시각적으로 표현하기 위해 개발되었으며, 누구나 자유롭게 사용할 수 있도록 오픈소스로 공개되었습니다.
-
-### 관련 프로젝트
-
-- 🏢 [apt.today](https://apt.today) - 손 쉽게 찾는 부동산 정보, 오늘의 아파트
-
 ## 기여
 
 이슈 제보 및 풀 리퀘스트는 언제나 환영합니다!