@apt.today/react-seoul-icons 1.0.2 → 1.2.0

package/README.md

@@ -8,9 +8,9 @@
 
 ![Seoul Icons Preview](https://myriky.github.io/apt-today-react-seoul-icons/preview.png)
 
-서울시 25개 행정구 아이콘을 React 컴포넌트로 제공하는 라이브러리입니다.
+대한민국 광역자치단체(시/도) 및 기초자치단체(시/군/구) 로고 아이콘을 React 컴포넌트로 제공하는 라이브러리입니다.
 
-🌐 [데모 페이지](https://myriky.github.io/apt-today-react-seoul-icons/)
+[데모 페이지](https://myriky.github.io/apt-today-react-seoul-icons/)
 
 ## 설치
 
@@ -18,296 +18,221 @@
 npm install @apt.today/react-seoul-icons
 ```
 
-또는
-
 ```bash
 yarn add @apt.today/react-seoul-icons
 ```
 
 ## 사용법
 
-### 개별 컴포넌트 Import
+### 컴포넌트 직접 사용
+
+아이콘을 직접 import해서 React 컴포넌트로 사용합니다.
 
 ```tsx
-import { 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>
   );
 }
 ```
 
-### 전체 Import (네임스페이스)
-
-```tsx
-import * as SeoulIcons from "@apt.today/react-seoul-icons";
+### 유틸리티로 동적 조회
 
-function App() {
-  return (
-    <div>
-      <SeoulIcons.GangnamGu width={48} />
-      <SeoulIcons.JongnoGu className="w-12 h-12" />
-    </div>
-  );
-}
-```
-
-### 동적 아이콘 렌더링 (컴포넌트 이름 기반)
+코드나 이름으로 아이콘을 동적으로 가져올 때는 `utils`를 사용합니다.
 
 ```tsx
-import * as SeoulIcons from "@apt.today/react-seoul-icons";
-
-const districts = ["GangnamGu", "MapoGu", "JongnoGu"];
-
-function App() {
-  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>
-  );
-}
-```
-
-### 행정구역 코드로 아이콘 가져오기 ⭐
+import { utils } from "@apt.today/react-seoul-icons";
 
-```tsx
-import { getIconByCode } from "@apt.today/react-seoul-icons";
+// 코드로 아이콘 가져오기 (시도 2자리 / 시군구 5자리 자동 판별)
+const SeoulIcon = utils.getIcon(11);      // 서울특별시
+const GangnamIcon = utils.getIcon(11680); // 강남구
 
-function App() {
-  const GangnamIcon = getIconByCode(11680); // 강남구
-  const JungIcon = getIconByCode(11140); // 중구
+// 이름으로 아이콘 검색
+const Icon = utils.findByName("강남구");
+const Icon2 = utils.findByName("강남");
+const Icon3 = utils.findByName("서울특별시 강남구");
+const Icon4 = utils.findByName("서울 강남구");
 
-  return (
-    <div>
-      {GangnamIcon && <GangnamIcon width={48} height={48} />}
-      {JungIcon && <JungIcon width={48} height={48} />}
-    </div>
-  );
-}
+// 중복 이름(중구 등)은 region 옵션으로 구분
+const JungGu = utils.findByName("중구", { region: "서울" });
 ```
 
-### 이름으로 아이콘 가져오기
+### 지역별 목록 조회
 
 ```tsx
-import { getIconByName } from "@apt.today/react-seoul-icons";
-
-// 다양한 형식 지원
-const Icon1 = getIconByName("강남구"); // ✅
-const Icon2 = getIconByName("강남"); // ✅
-const Icon3 = getIconByName("서울특별시 강남구"); // ✅
-const Icon4 = getIconByName("서울 강남구"); // ✅
+import { utils } from "@apt.today/react-seoul-icons";
 
-// 중복되는 이름(중구 등)은 region 옵션 필요
-const SeoulJung = getIconByName("중구", { region: "서울" }); // ✅
-const BusanJung = getIconByName("중구", { region: "부산" }); // ✅ (추후 지원)
-```
+// 시도별 시군구 목록
+const seoulIcons = utils.getByRegion(11);      // 코드로
+const gyeonggiIcons = utils.getByRegion("경기"); // 이름으로
 
-### 모든 지역 정보 가져오기
-
-```tsx
-import {
-  getAllDistrictInfo,
-  getDistrictsByRegion,
-} from "@apt.today/react-seoul-icons";
+// 전체 시도 목록
+const regions = utils.getAllRegions();
 
-// 모든 지역 정보
-const allDistricts = getAllDistrictInfo();
+// 전체 시군구 목록
+const allIcons = utils.getAll();
 
-// 서울시만 가져오기
-const seoulDistricts = getDistrictsByRegion("서울");
-
-function App() {
+function DistrictList() {
   return (
-    <div>
-      {seoulDistricts.map((district) => {
-        const Icon = district.component;
-        return (
-          <div key={district.code}>
-            <Icon width={48} height={48} />
-            <span>{district.name}</span>
-            <code>{district.code}</code>
-          </div>
-        );
-      })}
+    <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 레퍼런스
-
-### 아이콘 가져오기
-
-| 함수                            | 설명                            | 반환 타입                   |
-| ------------------------------- | ------------------------------- | --------------------------- |
-| `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`                   |
-
-### 타입
+### API 응답에서 동적으로 사용
 
 ```tsx
-import type {
-  RegionCode, // "서울" | "부산" | "대구" | ...
-  SeoulGuCode, // 11110 | 11140 | ...
-  DistrictInfo, // 지역 정보 객체
-  SeoulGuIconComponent, // SVG 컴포넌트 타입
-  GetIconByNameOptions, // { region?: RegionCode }
-} from "@apt.today/react-seoul-icons";
-```
+import { utils } from "@apt.today/react-seoul-icons";
 
-### DistrictInfo 타입
-
-```tsx
-interface DistrictInfo {
-  code: number; // 행정구역 코드 (예: 11680)
-  region: RegionCode; // 시/도 (예: "서울")
-  regionFullName: string; // 시/도 전체 이름 (예: "서울특별시")
-  name: string; // 구 이름 (예: "강남구")
-  shortName: string; // 짧은 이름 (예: "강남")
-  component: SeoulGuIconComponent; // React 컴포넌트
+// 행정구역 코드를 받은 경우
+function DistrictIcon({ code }: { code: number }) {
+  const Icon = utils.getIcon(code);
+  if (!Icon) return null;
+  return <Icon width={48} height={48} />;
 }
-```
 
-## 행정구역 코드표
-
-| 코드    | 행정구   | 컴포넌트명       |
-| ------- | -------- | ---------------- |
-| `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`     |
-
-## Props
-
-모든 컴포넌트는 SVG 요소의 표준 props를 지원합니다:
-
-```tsx
-interface IconProps extends React.SVGProps<SVGSVGElement> {}
+// 지역명을 받은 경우
+function DistrictIconByName({ name }: { name: string }) {
+  const Icon = utils.findByName(name);
+  if (!Icon) return null;
+  return <Icon width={48} height={48} />;
+}
 ```
 
-일반적으로 사용되는 props:
-
-- `className`: CSS 클래스명
-- `style`: 인라인 스타일
-- `width`: 너비
-- `height`: 높이
-- `fill`: 색상 (일부 아이콘은 고정 색상)
-- `onClick`: 클릭 이벤트 핸들러
+## API
 
-## 예제
+### 아이콘 컴포넌트
 
-### Tailwind CSS와 함께 사용
+모든 아이콘 컴포넌트는 `React.SVGProps<SVGSVGElement>`를 지원합니다.
 
 ```tsx
-import { GangnamGu } from "@apt.today/react-seoul-icons";
-
-function Example() {
-  return <GangnamGu className="w-16 h-16 text-blue-500 hover:text-blue-700" />;
-}
+<GangnamGu width={48} height={48} />
+<GangnamGu className="w-12 h-12" />
+<GangnamGu style={{ width: 48 }} />
 ```
 
-### API 응답에서 동적으로 사용
+### utils
 
-```tsx
-import { getIconByCode, getIconByName } from "@apt.today/react-seoul-icons";
+| 메서드 | 설명 | 반환 타입 |
+| --- | --- | --- |
+| `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` |
 
-// API에서 행정구역 코드를 받은 경우
-function DistrictIcon({ code }: { code: number }) {
-  const Icon = getIconByCode(code);
-  if (!Icon) return null;
-  return <Icon width={48} height={48} />;
+### 타입
+
+```tsx
+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;
 }
 
-// API에서 지역명을 받은 경우
-function DistrictIconByName({ name }: { name: string }) {
-  // "서울특별시 강남구" 같은 형식도 OK
-  const Icon = getIconByName(name);
-  if (!Icon) return null;
-  return <Icon width={48} height={48} />;
+// 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개 자치구 (강남구, 종로구, 마포구 등)
+- **경기도**: 14개 시 (수원시, 고양시, 용인시, 화성시, 성남시, 안양시, 광명시, 과천시, 구리시, 남양주시, 하남시, 의왕시, 김포시, 파주시)
+- **부산광역시**: 해운대구
+- **대구광역시**: 수성구
+- **인천광역시**: 연수구
+- **울산광역시**: 남구
+
+## v1에서 마이그레이션
+
+v2에서는 API가 `utils` 네임스페이스로 통합되었습니다.
+
+| 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 { getAllDistrictInfo } from "@apt.today/react-seoul-icons";
-
-function DistrictList() {
-  const districts = getAllDistrictInfo();
-
-  return (
-    <div className="grid grid-cols-5 gap-4">
-      {districts.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";
 ```
 
 ## 라이선스
 
 ### 아이콘 저작권
 
-본 라이브러리의 아이콘은 서울특별시 각 자치구청의 공식 심볼/로고로, 공공누리 제1유형(출처표시)에 따라 자유롭게 이용할 수 있습니다.
+본 라이브러리의 아이콘은 각 지방자치단체의 공식 심볼/로고로, 공공누리 제1유형(출처표시)에 따라 자유롭게 이용할 수 있습니다.
 
 ### 라이브러리 코드
 
 본 라이브러리의 소스 코드는 MIT 라이선스를 따릅니다.
 
-자세한 내용은 [LICENSE](./LICENSE) 파일을 참고하세요
+자세한 내용은 [LICENSE](./LICENSE) 파일을 참고하세요.
 
 ## About apt.today
 
 이 라이브러리는 [apt.today](https://apt.today) 프로젝트의 일부입니다.
 
-**apt.today**는 부동산 정보를 제공하는 서비스로, 서울특별시 지자체별 고시공고문, 모집공고문, 토지거래허가내역을 비롯한 다양한 아파트 관련 정보를 확인 할 수 있는 플랫폼입니다.
-
-본 아이콘 라이브러리는 apt.today 서비스에서 서울시 각 행정구의 데이터를 시각적으로 표현하기 위해 개발되었으며, 누구나 자유롭게 사용할 수 있도록 오픈소스로 공개되었습니다.
-
-### 관련 프로젝트
-
-- 🏢 [apt.today](https://apt.today) - 손 쉽게 찾는 부동산 정보, 오늘의 아파트
+**apt.today**는 부동산 정보를 제공하는 서비스로, 전국 지자체별 고시공고문, 모집공고문, 토지거래허가내역을 비롯한 다양한 아파트 관련 정보를 확인 할 수 있는 플랫폼입니다.
 
 ## 기여