@uniai-fe/uds-templates 0.5.9 → 0.5.10

package/src/weather/types/page-header.ts

@@ -0,0 +1,277 @@
+import type {
+  API_Res_WeatherKoreaForecast,
+  API_Res_WeatherKoreaNextDays,
+  API_Res_WeatherKoreaNow,
+} from "./api";
+import type {
+  OWM_Res_Weather_Forecast,
+  OWM_Res_Weather_Now,
+} from "./open-weather-map";
+
+/**
+ * Weather Page Header; locale 옵션
+ * @property {string} [locale] 표시 언어 코드. 기본 지원값은 ko, en, ja이며 타입은 확장 가능한 string으로 유지한다.
+ */
+export interface WeatherLocaleOptions {
+  /**
+   * 표시 언어 코드. 기본 지원값은 ko, en, ja이며 타입은 확장 가능한 string으로 유지한다.
+   */
+  locale?: string;
+}
+
+/**
+ * Weather Page Header; 텍스트 옵션
+ * @property {string} currentWeatherLoading 현재 날씨 로딩 문구
+ * @property {string} forecastWeatherLoading 예보 날씨 로딩 문구
+ * @property {string} alertLoading 특보 로딩 문구
+ * @property {string} currentLabel 현재 기온 라벨
+ * @property {string} maxTemperatureLabel 최고 기온 라벨
+ * @property {string} minTemperatureLabel 최저 기온 라벨
+ * @property {string} humidityLabel 습도 라벨
+ * @property {string} tomorrowLabel 내일 라벨
+ * @property {string} dayAfterTomorrowLabel 모레 라벨
+ * @property {string} weatherIconAlt 날씨 아이콘 기본 대체 텍스트
+ * @property {string} addressIconAlt 위치 아이콘 대체 텍스트
+ * @property {string} conditionFallbackLabel 날씨 상태 fallback 텍스트
+ * @property {string} alertPreliminaryLevelLabel 예비 특보 수준 라벨
+ * @property {string} alertWatchLevelLabel 주의보 수준 라벨
+ * @property {string} alertCancelCommandLabel 특보 해제 명령 라벨
+ * @property {string} alertIssueCommandLabel 특보 발령 명령 라벨
+ */
+export interface WeatherPageHeaderTexts {
+  /**
+   * 현재 날씨 로딩 문구
+   */
+  currentWeatherLoading: string;
+  /**
+   * 예보 날씨 로딩 문구
+   */
+  forecastWeatherLoading: string;
+  /**
+   * 특보 로딩 문구
+   */
+  alertLoading: string;
+  /**
+   * 현재 기온 라벨
+   */
+  currentLabel: string;
+  /**
+   * 최고 기온 라벨
+   */
+  maxTemperatureLabel: string;
+  /**
+   * 최저 기온 라벨
+   */
+  minTemperatureLabel: string;
+  /**
+   * 습도 라벨
+   */
+  humidityLabel: string;
+  /**
+   * 내일 라벨
+   */
+  tomorrowLabel: string;
+  /**
+   * 모레 라벨
+   */
+  dayAfterTomorrowLabel: string;
+  /**
+   * 날씨 아이콘 기본 대체 텍스트
+   */
+  weatherIconAlt: string;
+  /**
+   * 위치 아이콘 대체 텍스트
+   */
+  addressIconAlt: string;
+  /**
+   * 날씨 상태 fallback 텍스트
+   */
+  conditionFallbackLabel: string;
+  /**
+   * 예비 특보 수준 라벨
+   */
+  alertPreliminaryLevelLabel: string;
+  /**
+   * 주의보 수준 라벨
+   */
+  alertWatchLevelLabel: string;
+  /**
+   * 특보 해제 명령 라벨
+   */
+  alertCancelCommandLabel: string;
+  /**
+   * 특보 발령 명령 라벨
+   */
+  alertIssueCommandLabel: string;
+}
+
+/**
+ * Weather Page Header; locale과 텍스트 override 조합 옵션
+ * @property {string} [locale] 표시 언어 코드
+ * @property {Partial<WeatherPageHeaderTexts>} [texts] 서비스에서 주입한 표시 문구
+ */
+export interface WeatherPageHeaderLocaleOptions extends WeatherLocaleOptions {
+  /**
+   * 서비스에서 주입한 표시 문구
+   */
+  texts?: Partial<WeatherPageHeaderTexts>;
+}
+
+/**
+ * Weather Page Header; KMA weather query 결과
+ * @property {API_Res_WeatherKoreaNow} [now] 현재 날씨 응답
+ * @property {API_Res_WeatherKoreaForecast} [forecast] 예보 날씨 응답
+ * @property {boolean} isFetchingNow 현재 날씨 조회 상태
+ * @property {boolean} isFetchingForecast 예보 날씨 조회 상태
+ */
+export interface WeatherPageHeaderKoreaWeather {
+  /**
+   * 현재 날씨 응답
+   */
+  now?: API_Res_WeatherKoreaNow;
+  /**
+   * 예보 날씨 응답
+   */
+  forecast?: API_Res_WeatherKoreaForecast;
+  /**
+   * 현재 날씨 조회 상태
+   */
+  isFetchingNow: boolean;
+  /**
+   * 예보 날씨 조회 상태
+   */
+  isFetchingForecast: boolean;
+}
+
+/**
+ * Weather Page Header; OpenWeatherMap query 결과
+ * @property {OWM_Res_Weather_Now} [now] 현재 날씨 응답
+ * @property {OWM_Res_Weather_Forecast} [forecast] 예보 날씨 응답
+ * @property {boolean} isFetchingNow 현재 날씨 조회 상태
+ * @property {boolean} isFetchingForecast 예보 날씨 조회 상태
+ */
+export interface WeatherPageHeaderOpenWeatherMapWeather {
+  /**
+   * 현재 날씨 응답
+   */
+  now?: OWM_Res_Weather_Now;
+  /**
+   * 예보 날씨 응답
+   */
+  forecast?: OWM_Res_Weather_Forecast;
+  /**
+   * 현재 날씨 조회 상태
+   */
+  isFetchingNow: boolean;
+  /**
+   * 예보 날씨 조회 상태
+   */
+  isFetchingForecast: boolean;
+}
+
+/**
+ * Weather Page Header; 상위 container에서 준비한 weather query 결과
+ * @property {WeatherPageHeaderKoreaWeather} [koreaWeather] KMA weather query 결과
+ * @property {WeatherPageHeaderOpenWeatherMapWeather} [openWeatherMapWeather] OpenWeatherMap query 결과
+ */
+export interface WeatherPageHeaderDataOptions {
+  /**
+   * KMA weather query 결과
+   */
+  koreaWeather?: WeatherPageHeaderKoreaWeather;
+  /**
+   * OpenWeatherMap query 결과
+   */
+  openWeatherMapWeather?: WeatherPageHeaderOpenWeatherMapWeather;
+}
+
+/**
+ * Weather Page Header; container props
+ * @property {string} [locale] 표시 언어 코드
+ * @property {Partial<WeatherPageHeaderTexts>} [texts] 서비스에서 주입한 표시 문구
+ */
+export type WeatherPageHeaderContainerProps = WeatherPageHeaderLocaleOptions;
+
+/**
+ * Weather Page Header; address props
+ * @property {string} [locale] 표시 언어 코드
+ * @property {Partial<WeatherPageHeaderTexts>} [texts] 서비스에서 주입한 표시 문구
+ */
+export type WeatherPageHeaderAddressProps = WeatherPageHeaderLocaleOptions;
+
+/**
+ * Weather Page Header; today props
+ * @property {string} [locale] 표시 언어 코드
+ * @property {Partial<WeatherPageHeaderTexts>} [texts] 서비스에서 주입한 표시 문구
+ * @property {WeatherPageHeaderKoreaWeather} [koreaWeather] KMA weather query 결과
+ * @property {WeatherPageHeaderOpenWeatherMapWeather} [openWeatherMapWeather] OpenWeatherMap query 결과
+ */
+export type WeatherPageHeaderTodayProps = WeatherPageHeaderLocaleOptions &
+  WeatherPageHeaderDataOptions;
+
+/**
+ * Weather Page Header; forecast props
+ * @property {string} [locale] 표시 언어 코드
+ * @property {Partial<WeatherPageHeaderTexts>} [texts] 서비스에서 주입한 표시 문구
+ * @property {WeatherPageHeaderKoreaWeather} [koreaWeather] KMA weather query 결과
+ * @property {WeatherPageHeaderOpenWeatherMapWeather} [openWeatherMapWeather] OpenWeatherMap query 결과
+ */
+export type WeatherPageHeaderForecastProps = WeatherPageHeaderLocaleOptions &
+  WeatherPageHeaderDataOptions;
+
+/**
+ * Weather Page Header; alert props
+ * @property {string} [locale] 표시 언어 코드
+ * @property {Partial<WeatherPageHeaderTexts>} [texts] 서비스에서 주입한 표시 문구
+ */
+export type WeatherPageHeaderAlertProps = WeatherPageHeaderLocaleOptions;
+
+/**
+ * Weather Page Header; next days props
+ * @property {string} title 날짜 라벨
+ * @property {API_Res_WeatherKoreaNextDays} [data] 예보 데이터
+ * @property {string} [locale] 표시 언어 코드
+ * @property {Partial<WeatherPageHeaderTexts>} [texts] 서비스에서 주입한 표시 문구
+ */
+export interface WeatherPageHeaderNextDaysProps extends WeatherPageHeaderLocaleOptions {
+  /**
+   * 날짜 라벨
+   */
+  title: string;
+  /**
+   * 예보 데이터
+   */
+  data?: API_Res_WeatherKoreaNextDays;
+}
+
+/**
+ * Weather Icon; 날씨 아이콘 props
+ * @property {string | null} [code] 날씨 아이콘 코드
+ * @property {string | null} [name] 날씨 상태 이름
+ * @property {string} [alt] 아이콘 대체 텍스트 fallback
+ */
+export interface WeatherIconProps {
+  /**
+   * 날씨 아이콘 코드
+   */
+  code?: string | null;
+  /**
+   * 날씨 상태 이름
+   */
+  name?: string | null;
+  /**
+   * 아이콘 대체 텍스트 fallback
+   */
+  alt?: string;
+}
+
+/**
+ * Weather Address Icon; 위치 아이콘 props
+ * @property {string} [alt] 아이콘 대체 텍스트
+ */
+export interface WeatherAddressIconProps {
+  /**
+   * 아이콘 대체 텍스트
+   */
+  alt?: string;
+}

package/src/weather/utils/index.ts

@@ -2,3 +2,4 @@ export * from "./location";
 export * from "./date-time";
 export * from "./weather";
 export * from "./alert";
+export * from "./locale";

package/src/weather/utils/locale.ts

@@ -0,0 +1,73 @@
+import type { WeatherPageHeaderTexts } from "../types";
+
+const WEATHER_PAGE_HEADER_DEFAULT_TEXTS: WeatherPageHeaderTexts = {
+  currentWeatherLoading: "현재 날씨 불러오는 중...",
+  forecastWeatherLoading: "예보 날씨 불러오는 중...",
+  alertLoading: "특보 불러오는 중...",
+  currentLabel: "현재",
+  maxTemperatureLabel: "최고:",
+  minTemperatureLabel: "최저:",
+  humidityLabel: "습도",
+  tomorrowLabel: "내일",
+  dayAfterTomorrowLabel: "모레",
+  weatherIconAlt: "날씨 아이콘",
+  addressIconAlt: "날씨 위치",
+  conditionFallbackLabel: "-",
+  alertPreliminaryLevelLabel: "예비특보",
+  alertWatchLevelLabel: "주의보",
+  alertCancelCommandLabel: "해제",
+  alertIssueCommandLabel: "발령",
+};
+
+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; KMA provider 사용 여부
+ * @param {string} [locale] locale 코드
+ * @return {boolean} KMA provider 대상 locale 여부
+ * @example
+ * isKoreaWeatherLocale("ko-KR")
+ */
+export const isKoreaWeatherLocale = (locale?: string): boolean =>
+  getWeatherLocaleKey(locale) === "ko";
+
+/**
+ * Weather Locale; page-header 텍스트 병합
+ * @param {Partial<WeatherPageHeaderTexts>} [texts] 서비스에서 주입한 텍스트
+ * @return {WeatherPageHeaderTexts} 기본 fallback과 서비스 주입 텍스트를 병합한 텍스트
+ * @example
+ * resolveWeatherPageHeaderTexts({ humidityLabel: "습도" })
+ */
+export const resolveWeatherPageHeaderTexts = (
+  texts?: Partial<WeatherPageHeaderTexts>,
+): WeatherPageHeaderTexts => ({
+  ...WEATHER_PAGE_HEADER_DEFAULT_TEXTS,
+  ...texts,
+});
+
+/**
+ * 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/utils/weather.ts

@@ -1,10 +1,13 @@
 import type {
   API_Res_WeatherKoreaBase,
   API_Res_WeatherKoreaForecast,
+  API_Res_WeatherKoreaNextDays,
   API_Res_WeatherKoreaNow,
   KMA_Res_WeatherItem,
   KMA_Res_WeatherForecast,
   KMA_Res_WeatherNow,
+  OWM_Res_Weather_Forecast,
+  OWM_Res_Weather_Forecast_Item,
 } from "../types";
 import { getMoments } from "./date-time";
 
@@ -217,6 +220,115 @@ const getWeatherCondition = ({
   };
 };
 
+/**
+ * 날씨 도구; OpenWeatherMap 아이콘 코드를 weather icon 코드로 변환
+ * @param {string} [icon] OpenWeatherMap icon 코드
+ * @return {string} weather icon 코드
+ */
+export const getOpenWeatherMapConditionCode = (icon?: string): string => {
+  switch (icon) {
+    case "01d":
+    case "01n":
+      return "sky-1";
+    case "02d":
+    case "02n":
+    case "03d":
+    case "03n":
+    case "04d":
+    case "04n":
+      return "sky-2";
+    case "09d":
+    case "09n":
+      return "drop-rain-3";
+    case "10d":
+    case "10n":
+      return "drop-rain-1";
+    case "11d":
+    case "11n":
+      return "drop-rain-thunder";
+    case "13d":
+    case "13n":
+      return "drop-snow";
+    case "50d":
+    case "50n":
+      return "sky-4";
+    default:
+      return "sky-1";
+  }
+};
+
+const getLocalDateKey = (date: Date): string => {
+  const month = String(date.getMonth() + 1).padStart(2, "0");
+  const day = String(date.getDate()).padStart(2, "0");
+
+  return `${date.getFullYear()}-${month}-${day}`;
+};
+
+const getForecastItemDateKey = (item: OWM_Res_Weather_Forecast_Item): string =>
+  item.dt_txt?.slice(0, 10) || getLocalDateKey(new Date(item.dt * 1000));
+
+const toOpenWeatherMapNextDay = (
+  items: OWM_Res_Weather_Forecast_Item[],
+): API_Res_WeatherKoreaNextDays | undefined => {
+  if (items.length === 0) return undefined;
+
+  const conditionItem =
+    items.find(item => item.dt_txt?.includes("12:00")) ||
+    items[Math.floor(items.length / 2)];
+  const temperatures = items.flatMap(item => [
+    item.main.temp_min,
+    item.main.temp_max,
+    item.main.temp,
+  ]);
+
+  return {
+    sky: null,
+    drop: null,
+    rainAmount: null,
+    snowAmount: null,
+    windSpeed: null,
+    condition: getOpenWeatherMapConditionCode(
+      conditionItem?.weather?.[0]?.icon,
+    ),
+    conditionName: conditionItem?.weather?.[0]?.description || null,
+    max_temperature:
+      temperatures.length > 0 ? Math.round(Math.max(...temperatures)) : null,
+    min_temperature:
+      temperatures.length > 0 ? Math.round(Math.min(...temperatures)) : null,
+  };
+};
+
+/**
+ * 날씨 도구; OpenWeatherMap 예보 응답을 page-header next days 형태로 변환
+ * @param {OWM_Res_Weather_Forecast} [forecast] OpenWeatherMap 예보 응답
+ * @return {{ day_1?: API_Res_WeatherKoreaNextDays; day_2?: API_Res_WeatherKoreaNextDays }} 내일/모레 예보
+ */
+export const getOpenWeatherMapNextDays = (
+  forecast?: OWM_Res_Weather_Forecast,
+): {
+  day_1?: API_Res_WeatherKoreaNextDays;
+  day_2?: API_Res_WeatherKoreaNextDays;
+} => {
+  if (!Array.isArray(forecast?.list)) return {};
+
+  const todayKey = getLocalDateKey(new Date());
+  const grouped = forecast.list.reduce<
+    Record<string, OWM_Res_Weather_Forecast_Item[]>
+  >((days, item) => {
+    const dateKey = getForecastItemDateKey(item);
+    if (dateKey === todayKey) return days;
+
+    days[dateKey] = [...(days[dateKey] || []), item];
+    return days;
+  }, {});
+  const [day1Key, day2Key] = Object.keys(grouped).sort();
+
+  return {
+    day_1: day1Key ? toOpenWeatherMapNextDay(grouped[day1Key]) : undefined,
+    day_2: day2Key ? toOpenWeatherMapNextDay(grouped[day2Key]) : undefined,
+  };
+};
+
 export function now(
   outputResponse: API_Res_WeatherKoreaNow,
   apiResponse: KMA_Res_WeatherNow,