@uniai-fe/uds-templates 0.5.29 → 0.6.0

package/README.md

@@ -57,15 +57,12 @@ Next.js 서비스에서 primitives와 동일한 방식으로 **Raw TypeScript**
   - `WeatherPageHeaderForecast`
   - `WeatherPageHeaderAlert`
   - `WeatherPageHeaderNextDays`
+  - `useWeather`
+  - `useWeatherAlert`
   - `weatherCoordinate`
-  - `useWeatherKorea`
-  - `useOpenWeatherMap`
-  - `resolveWeatherProvider`
-  - `WEATHER_PROVIDER_CAPABILITIES`
+  - `weatherFarmIdx`
   - `WeatherPageHeaderContainerProps`
   - `WeatherPageHeaderTexts`
-  - `WeatherProviderKey`
-  - `WeatherProviderCapability`
 - `/service-inquiry`
   - `ServiceInquiry.Form`
   - `ServiceInquiry.OpenButton`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniai-fe/uds-templates",
-  "version": "0.5.29",
+  "version": "0.6.0",
   "description": "UNIAI Design System; UI Templates Package",
   "type": "module",
   "private": false,

package/src/weather/_legacy/apis/index.ts

@@ -0,0 +1,4 @@
+export * from "./korea/client";
+export * from "./korea/server";
+export * from "./open-weather-map/client";
+export * from "./open-weather-map/server";

package/src/weather/_legacy/data/response.ts

@@ -0,0 +1,36 @@
+import type { API_Res_WeatherKoreaBase } from "../types";
+
+const API_RES_RAW = {
+  response: {
+    header: {
+      resultCode: "",
+      resultMsg: "",
+    },
+    body: {
+      dataType: "",
+      items: {
+        item: [],
+      },
+      pageNo: 0,
+      numOfRows: 0,
+      totalCount: 0,
+    },
+  },
+};
+
+const API_RES_BASE: API_Res_WeatherKoreaBase = {
+  sky: null,
+  drop: null,
+  rainAmount: null,
+  snowAmount: null,
+  windSpeed: null,
+  condition: null,
+  conditionName: null,
+};
+
+const WEATHER_KOREA_RESPONSE = {
+  API_RES_RAW,
+  API_RES_BASE,
+};
+
+export default WEATHER_KOREA_RESPONSE;

package/src/weather/_legacy/hooks/index.ts

@@ -0,0 +1,5 @@
+import useOpenWeatherMap from "./useOpenWeatherMap";
+import useWeatherKorea from "./useWeatherKorea";
+import useWeatherKoreaAlert from "./useWeatherKoreaAlert";
+
+export { useOpenWeatherMap, useWeatherKorea, useWeatherKoreaAlert };

package/src/weather/{hooks → _legacy/hooks}/useOpenWeatherMap.ts

@@ -1,11 +1,11 @@
 "use client";
 
 import { useAtomValue } from "jotai";
-import { weatherCoordinate } from "../jotai";
 import {
   useQueryWeatherOpenWeatherMapForecast,
   useQueryWeatherOpenWeatherMapNow,
 } from "../apis/open-weather-map/client";
+import { weatherCoordinate } from "../../jotai";
 import type {
   WeatherApiLocaleOptions,
   WeatherOpenWeatherMapParams,

package/src/weather/{hooks → _legacy/hooks}/useWeatherKorea.ts

@@ -1,13 +1,13 @@
 "use client";
 
-import { useState, useEffect } from "react";
+import { useEffect, useState } from "react";
 import { useAtomValue } from "jotai";
 import {
   useQueryWeatherKoreaForecast,
   useQueryWeatherKoreaNow,
-} from "../apis/korea/client"; // 클라이언트 전용 API만 import해 Storybook 번들에서 server 코드를 배제한다.
+} from "../apis/korea/client";
+import { weatherCoordinate } from "../../jotai/coordinate";
 import type { API_Req_WeatherKorea } from "../types";
-import { weatherCoordinate } from "../jotai/coordinate";
 import { getWeatherBaseMoments } from "../utils/date-time";
 import { getWeatherGridLocation } from "../utils/location";
 
@@ -35,10 +35,7 @@ export default function useWeatherKorea({
       coordinate.lat !== null ||
       coordinate.lng !== null;
 
-    if (!hasInjectedCoordinate) {
-      // 변경 설명: 초기 mount에서 coordinate 주입 전에는 geolocation/web API 준비를 시도하지 않는다.
-      return;
-    }
+    if (!hasInjectedCoordinate) return;
 
     const nowMoments = getWeatherBaseMoments("now");
     const forecastMoments = getWeatherBaseMoments("forecast");

package/src/weather/{hooks → _legacy/hooks}/useWeatherKoreaAlert.ts

@@ -2,8 +2,8 @@
 
 import { useMemo } from "react";
 import { useAtomValue } from "jotai";
-import { useQueryWeatherKoreaAlert } from "../apis/korea/client"; // server 번들을 피하기 위해 client 모듈에서 직접 import한다.
-import { weatherFarmIdx } from "../jotai/farm-idx";
+import { useQueryWeatherKoreaAlert } from "../apis/korea/client";
+import { weatherFarmIdx } from "../../jotai/farm-idx";
 
 type UseWeatherKoreaAlertOptions = {
   enabled?: boolean;
@@ -13,8 +13,6 @@ export default function useWeatherKoreaAlert({
   enabled = true,
 }: UseWeatherKoreaAlertOptions = {}) {
   const farm_idx = useAtomValue(weatherFarmIdx);
-
-  // 특보 조회 식별자는 템플릿이 보정하지 않고, 서비스가 주입한 값만 그대로 사용한다.
   const { data, isFetching } = useQueryWeatherKoreaAlert(
     {
       farm_idx,

package/src/weather/_legacy/types/api.ts

@@ -0,0 +1,221 @@
+import type {
+  KMA_Res_WeatherNow,
+  KMA_Res_WeatherForecast,
+  KMA_Res_Base,
+  KMA_Req_BaseGridCoordinate,
+  KMA_Req_BaseMoments,
+  KMA_Res_AlertType,
+  KMA_Res_AlertLevel,
+  KMA_Res_AlertCommand,
+  KMA_Res_WeatherItem,
+} from "./korea";
+
+export type API_Req_WeatherKoreaGrid = KMA_Req_BaseGridCoordinate;
+export type API_Req_WeatherKoreaMoments = KMA_Req_BaseMoments;
+
+/**
+ * 기상청 API; 날씨 요청.
+ */
+export type API_Req_WeatherKorea = API_Req_WeatherKoreaGrid &
+  Partial<API_Req_WeatherKoreaMoments>;
+
+/**
+ * 기상청 API; 특보 요청 파라미터
+ * @property {number | null} farm_idx 농장 식별자
+ */
+export type API_Req_WeatherKoreaAlert = { farm_idx: number | null };
+
+/**
+ * 기상청 API; 특보 응답 타입 - 지역별 특보정보
+ */
+export type API_Res_WeatherKoreaAlertEach = {
+  /**
+   * 상위 지역 코드
+   * @see https://apihub.kma.go.kr/api/typ01/url/wrn_reg.php?tmfc=0&authKey=njld-D40Rb25Xfg-NAW9hA
+   */
+  upper_region_code: string;
+  /**
+   * 상위 지역 이름
+   * @see https://apihub.kma.go.kr/api/typ01/url/wrn_reg.php?tmfc=0&authKey=njld-D40Rb25Xfg-NAW9hA
+   */
+  upper_region_name: string;
+  /**
+   * 특보 지역 코드
+   * @see https://apihub.kma.go.kr/api/typ01/url/wrn_reg.php?tmfc=0&authKey=njld-D40Rb25Xfg-NAW9hA
+   */
+  alert_region_code: string;
+  /**
+   * 특보 지역 이름
+   * @see https://apihub.kma.go.kr/api/typ01/url/wrn_reg.php?tmfc=0&authKey=njld-D40Rb25Xfg-NAW9hA
+   */
+  alert_region_name: string;
+  /**
+   * 특보 발표시간
+   * - yyyymmddhhmm
+   */
+  announcement_time: string;
+  /**
+   * 특보 발효시간
+   * - yyyymmddhhmm
+   */
+  effective_time: string;
+  /** * 특보 종류 (한글) */
+  alert_type: KMA_Res_AlertType;
+  /**
+   * 특보 수준 (한글)
+   * - 경보, 주의, 예비
+   */
+  alert_level: KMA_Res_AlertLevel;
+  /**
+   * 특보 명령 (한글)
+   * - 발표, 변경, 해제
+   */
+  alert_command: KMA_Res_AlertCommand;
+  /**
+   * 특보 해제 예고시점 (한글)
+   * - dd일 오전/오후/밤(HH시 ~ HH시)
+   */
+  cancel_notice_time: string;
+};
+/**
+ * 기상청 API; 특보 응답 타입
+ */
+export type API_Res_WeatherKoreaAlert = {
+  /** * 특보 발표 시간 */
+  api_announcement_time: string | null;
+  /** * 총 특보 개수 */
+  total_count: number;
+  /** * 지역별 특보 */
+  alerts: API_Res_WeatherKoreaAlertEach[];
+};
+
+/**
+ * 기상청 API; 기초 정보
+ * @property {string} condition - 개황 정보
+ */
+export type API_Res_WeatherKoreaBase = {
+  /**
+   * 하늘상태 코드
+   * - 1(맑음)
+   * - 2(구름조금)
+   * - 3(구름많음)
+   * - 4(흐림)
+   */
+  sky: string | null;
+  /**
+   * 강수형태 코드
+   * - 0(없음)
+   * - 1(비)
+   * - 2(비/눈)
+   * - 3(눈)
+   * - 4(소나기)
+   */
+  drop: string | null;
+  /**
+   * 강수량 코드
+   * - 1(약한 비); 3mm/h 미만
+   * - 2(보통 비); 3mm/h 이상 15mm/h 미만
+   * - 3(강한 비); 15mm/h 이상
+   */
+  rainAmount: string | null;
+  /**
+   * 강설량 코드
+   * - 1(보통 눈); 1cm/h 미만
+   * - 2(많은 눈); 1cm/h 이상
+   */
+  snowAmount: string | null;
+  /**
+   * 풍속 코드
+   * - 1(약한 바람); 4m/s 미만
+   * - 2(약간 강한 바람); 4m/s 이상 9m/s 미만
+   * - 3(강한 바람); 9m/s 이상
+   */
+  windSpeed: string | null;
+  /**
+   * 날씨 상태 코드
+   * - sky-1(맑음)
+   * - sky-2(구름조금)
+   * - sky-3(구름많음)
+   * - sky-4(흐림)
+   * - drop-rain-shower(소나기)
+   * - drop-rain(비)
+   * - drop-rain-1(약한 비)
+   * - drop-rain-2(보통 비)
+   * - drop-rain-3(강한 비)
+   * - drop-rain-snow(비/눈)
+   * - drop-rain-snow-1(약한 비/눈)
+   * - drop-rain-snow-2(보통 비/눈)
+   * - drop-rain-snow-3(강한 비/눈)
+   * - drop-snow(눈)
+   * - drop-snow-1(보통 눈)
+   * - drop-snow-2(많은 눈)
+   */
+  condition: string | null;
+  /** 날씨 상태 텍스트 */
+  conditionName: string | null;
+};
+
+/**
+ * 기상청 API; 오늘 날씨
+ * @property {number|string|null} temperature 기온(℃)
+ * @property {number|string|null} max_temperature 최고기온(℃)
+ * @property {number|string|null} min_temperature 최저기온(℃)
+ * @property {number|string|null} humidity 습도(%)
+ */
+export type API_Res_WeatherKoreaToday = API_Res_WeatherKoreaBase & {
+  /** 기온(℃) */
+  temperature: number | string | null;
+  /** 최고 기온(℃) */
+  max_temperature: number | string | null;
+  /** 최저 기온(℃) */
+  min_temperature: number | string | null;
+  /** 습도(%) */
+  humidity: number | string | null;
+};
+
+/**
+ * 기상청 API; 내일/모레 날씨
+ * @property {number|string|null} max_temperature 최고기온(℃)
+ * @property {number|string|null} min_temperature 최저기온(℃)
+ */
+export type API_Res_WeatherKoreaNextDays = API_Res_WeatherKoreaBase & {
+  /** 최고 기온(℃) */
+  max_temperature: number | string | null;
+  /** 최저 기온(℃) */
+  min_temperature: number | string | null;
+};
+
+/**
+ * 기상청 API; 원본 응답
+ * @property {RAW} raw API 원본 데이터
+ */
+export type API_Res_WeatherKoreaRaw<RAW = KMA_Res_Base<KMA_Res_WeatherItem>> = {
+  /** API 원본 */
+  raw: RAW;
+};
+
+/**
+ * 기상청 API; 초단기 실황 구조
+ * @property {API_Res_WeatherKoreaToday} today 오늘 데이터
+ */
+export type API_Res_WeatherKoreaNow =
+  API_Res_WeatherKoreaRaw<KMA_Res_WeatherNow> & {
+    /** 오늘 날씨 */
+    today: API_Res_WeatherKoreaToday;
+  };
+
+/**
+ * 기상청 API; 단기 예보 구조
+ * @property {API_Res_WeatherKoreaToday} today 오늘 데이터
+ * @property {API_Res_WeatherKoreaNextDays} day_1 내일 데이터
+ * @property {API_Res_WeatherKoreaNextDays} day_2 모레 데이터
+ */
+export type API_Res_WeatherKoreaForecast =
+  API_Res_WeatherKoreaRaw<KMA_Res_WeatherForecast> & {
+    /** 오늘 날씨 */
+    today: API_Res_WeatherKoreaToday;
+    /** 내일 날씨 */
+    day_1: API_Res_WeatherKoreaNextDays;
+    /** 모레 날씨 */
+    day_2: API_Res_WeatherKoreaNextDays;
+  };

package/src/weather/_legacy/types/base.ts

@@ -0,0 +1,70 @@
+/**
+ * 위경도 좌표.
+ * @property {number | null} latitude 위도
+ * @property {number | null} longitude 경도
+ */
+export type GeoCoordinate = {
+  /** 위도 */
+  latitude: number | null;
+  /** 경도 */
+  longitude: number | null;
+};
+
+/**
+ * 날씨 API에서 사용하는 위경도 좌표.
+ * @property {number | null} lat 위도
+ * @property {number | null} lng 경도
+ */
+export type WeatherGeoCoordinate = {
+  /** 위도 */
+  lat: number | null;
+  /** 경도 */
+  lng: number | null;
+};
+
+/**
+ * 날씨 API locale 요청 옵션.
+ * @property {string} [locale] 요청 언어 코드. 기본 지원값은 ko, en, ja이며 타입은 확장 가능한 string으로 유지한다.
+ */
+export interface WeatherApiLocaleOptions {
+  /**
+   * 요청 언어 코드. 기본 지원값은 ko, en, ja이며 타입은 확장 가능한 string으로 유지한다.
+   */
+  locale?: string;
+}
+
+/**
+ * OpenWeatherMap 요청 파라미터.
+ * @property {number | null} lat 위도
+ * @property {number | null} lng 경도
+ * @property {string} [locale] 요청 언어 코드
+ */
+export type WeatherOpenWeatherMapParams = WeatherGeoCoordinate &
+  WeatherApiLocaleOptions;
+
+/**
+ * 좌표와 주소 정보를 함께 담는 구조.
+ * @property {string | null} address 좌표 주소
+ */
+export type WeatherCoordinate = {
+  /** 좌표 주소 */
+  address: string | null;
+} & WeatherGeoCoordinate;
+
+/**
+ * 날씨 로직에서 사용하는 날짜 기준값 모음.
+ * @property {Date} now 현재 시각
+ * @property {string} today 오늘 날짜(yyyymmdd)
+ * @property {string} tomorrow 내일 날짜(yyyymmdd)
+ * @property {string} dayAfterTomorrow 모레 날짜(yyyymmdd)
+ */
+export type WeatherUtilDateTimeMoments = {
+  /** 현재 시각 */
+  now: Date;
+  /** 오늘 날짜(yyyymmdd) */
+  today: string;
+  /** 내일 날짜(yyyymmdd) */
+  tomorrow: string;
+  /** 모레 날짜(yyyymmdd) */
+  dayAfterTomorrow: string;
+};

package/src/weather/_legacy/types/index.ts

@@ -0,0 +1,4 @@
+export type * from "./base";
+export type * from "./api";
+export type * from "./korea";
+export type * from "./open-weather-map";

package/src/weather/_legacy/utils/index.ts

@@ -0,0 +1,5 @@
+export * from "./date-time";
+export * from "./location";
+export * from "./weather";
+export * from "./locale";
+export * from "./validate";

package/src/weather/_legacy/utils/locale.ts

@@ -0,0 +1,28 @@
+const OPEN_WEATHER_MAP_LANG_BY_LOCALE: Record<string, string> = {
+  ko: "kr",
+  en: "en",
+  ja: "ja",
+};
+
+/**
+ * Weather Locale; locale 기준 키 정규화
+ * @param {string} [locale] locale 코드
+ * @return {string} 전달된 locale의 기본 언어 코드
+ * @example
+ * getWeatherLocaleKey("ko-KR")
+ */
+export const getWeatherLocaleKey = (locale?: string): string =>
+  locale?.trim().toLowerCase().split(/[-_]/)[0] || "ko";
+
+/**
+ * Weather Locale; OpenWeatherMap API lang 값 변환
+ * @param {string} [locale] locale 코드
+ * @return {string} OpenWeatherMap lang 파라미터
+ * @example
+ * getOpenWeatherMapLang("ko")
+ */
+export const getOpenWeatherMapLang = (locale?: string): string => {
+  const localeKey = getWeatherLocaleKey(locale);
+
+  return OPEN_WEATHER_MAP_LANG_BY_LOCALE[localeKey] ?? localeKey;
+};

package/src/weather/_legacy/utils/location.ts

@@ -0,0 +1,139 @@
+import type {
+  GeoCoordinate,
+  KMA_GridCoordinate,
+  KMA_Req_BaseGridCoordinate,
+  WeatherCoordinate,
+} from "../types";
+
+/**
+ * 날씨 도구; 접속위치 추출
+ * @util
+ * @return {GeoCoordinate}}
+ */
+export const userLocation = async (): Promise<GeoCoordinate> => {
+  if (typeof window === "undefined" || !window.navigator.geolocation) {
+    return { latitude: null, longitude: null };
+  }
+
+  try {
+    const position = await new Promise<GeolocationPosition>(
+      (resolve, reject) => {
+        window.navigator.geolocation.getCurrentPosition(resolve, reject);
+      },
+    );
+    return {
+      latitude: position.coords.latitude,
+      longitude: position.coords.longitude,
+    };
+  } catch (error) {
+    console.error("[userLocation] 위치 정보 에러", error);
+    return { latitude: null, longitude: null };
+  }
+};
+
+/**
+ * 날씨 도구; 위경도 -> 격자 좌표 변환
+ * @util
+ * @param {GeoCoordinate} coordinate 위경도 좌표
+ * @param {number} coordinate.latitude 위도
+ * @param {number} coordinate.longitude 경도
+ * @return {KMA_GridCoordinate} 격자 좌표
+ * @see https://apihub.kma.go.kr/
+ */
+export function convertCoordinateToGrid({
+  latitude,
+  longitude,
+}: GeoCoordinate): KMA_GridCoordinate {
+  const res: KMA_GridCoordinate = { x: 0, y: 0 };
+
+  if (latitude === null || longitude === null) return res;
+
+  const RE = 6371.00877;
+  const GRID = 5.0;
+  const SLAT1 = 30.0;
+  const SLAT2 = 60.0;
+  const ORIGIN_LONGITUDE = 126.0;
+  const ORIGIN_LATITUDE = 38.0;
+  const XO = 43;
+  const YO = 136;
+
+  const RADIAN = Math.PI / 180.0;
+  const re = RE / GRID;
+  const slat1 = SLAT1 * RADIAN;
+  const slat2 = SLAT2 * RADIAN;
+  const origin_longitude = ORIGIN_LONGITUDE * RADIAN;
+  const origin_latitude = ORIGIN_LATITUDE * RADIAN;
+
+  const sn =
+    Math.log(Math.cos(slat1) / Math.cos(slat2)) /
+    Math.log(
+      Math.tan(Math.PI * 0.25 + slat2 * 0.5) /
+        Math.tan(Math.PI * 0.25 + slat1 * 0.5),
+    );
+
+  const sf = Math.tan(Math.PI * 0.25 + slat1 * 0.5);
+  const sfPow = (Math.pow(sf, sn) * Math.cos(slat1)) / sn;
+
+  const ro =
+    (re * sfPow) /
+    Math.pow(Math.tan(Math.PI * 0.25 + origin_latitude * 0.5), sn);
+
+  const ra =
+    (re * sfPow) /
+    Math.pow(Math.tan(Math.PI * 0.25 + latitude * RADIAN * 0.5), sn);
+  let theta = longitude * RADIAN - origin_longitude;
+  if (theta > Math.PI) theta -= 2.0 * Math.PI;
+  if (theta < -Math.PI) theta += 2.0 * Math.PI;
+  theta *= sn;
+
+  res.x = Math.floor(ra * Math.sin(theta) + XO + 0.5);
+  res.y = Math.floor(ro - ra * Math.cos(theta) + YO + 0.5);
+
+  return res;
+}
+
+/**
+ * 날씨 도구; 위도/경도 -> 기상청 격자 좌표 변환
+ * @util
+ * @param {WeatherCoordinate} [coordinate] 사용자 위치 이외의 특정 위도/경도 좌표
+ * @param {number} coordinate.lat 위도
+ * @param {number} coordinate.lng 경도
+ * @return {KMA_Req_BaseGridCoordinate} 기상청 격자 좌표
+ */
+export async function getWeatherGridLocation(
+  coordinate?: WeatherCoordinate,
+): Promise<KMA_Req_BaseGridCoordinate> {
+  const res: KMA_Req_BaseGridCoordinate = { nx: 0, ny: 0 };
+
+  if (typeof window === "undefined") return res;
+
+  const geo: GeoCoordinate = {
+    latitude: coordinate?.lat ?? null,
+    longitude: coordinate?.lng ?? null,
+  };
+  const hasInjectedAddress =
+    typeof coordinate?.address === "string" && coordinate.address.trim() !== "";
+
+  if (
+    typeof window !== "undefined" &&
+    !hasInjectedAddress &&
+    (typeof coordinate === "undefined" ||
+      geo.latitude === null ||
+      geo.longitude === null)
+  ) {
+    const { latitude, longitude } = await userLocation();
+
+    if (latitude === null || longitude === null) return res;
+    geo.latitude = latitude;
+    geo.longitude = longitude;
+  }
+
+  const grid = convertCoordinateToGrid(geo);
+
+  if (grid.x === 0 || grid.y === 0) return res;
+
+  res.nx = grid.x;
+  res.ny = grid.y;
+
+  return res;
+}