@uniai-fe/uds-templates 0.5.29 → 0.6.1

package/src/weather/components/page-header/Today.tsx

@@ -7,187 +7,115 @@ import { Alternate } from "@uniai-fe/uds-primitives";
 import WeatherIcon from "../icon/Weather";
 import WeatherPageHeaderAlert from "./Alert";
 import type { WeatherPageHeaderTodayProps } from "../../types";
-import { useOpenWeatherMap, useWeatherKorea } from "../../hooks";
+import { useWeather } from "../../hooks";
 import {
-  getOpenWeatherMapConditionCode,
-  getOpenWeatherMapTodayForecast,
-  isKoreaWeatherLocale,
+  isWeatherForecastResponse,
+  isWeatherNowResponse,
   resolveWeatherPageHeaderTexts,
 } from "../../utils";
 
+/**
+ * Weather Page Header; 표시 가능한 숫자값으로 변환.
+ * @util
+ * @desc weather API가 숫자 또는 문자열로 내려주는 수치 값을 number/null로 정규화한다.
+ * @param {number|string|null|undefined} value 변환할 날씨 수치 값
+ * @return {number | null} 표시 가능한 숫자 값
+ */
+const toWeatherNumber = (
+  value: number | string | null | undefined,
+): number | null => {
+  if (value === null || typeof value === "undefined" || value === "") {
+    return null;
+  }
+
+  const nextValue = Number(value);
+  return Number.isNaN(nextValue) ? null : nextValue;
+};
+
+/**
+ * Weather Page Header; 현재 날씨와 당일 최고/최저/습도를 표시하는 컴포넌트.
+ * @component
+ * @desc 통합 weather now/forecast 응답을 조합해 현재 기온, 최고/최저 기온, 습도를 표시한다.
+ * @param {WeatherPageHeaderTodayProps} [props] today props
+ * @param {string} [props.locale] 표시 언어 코드
+ * @param {Partial<WeatherPageHeaderTexts>} [props.texts] 서비스에서 주입한 표시 문구
+ * @param {WeatherPageHeaderWeather} [props.weather] 상위 container에서 준비한 통합 weather query 결과
+ */
 export default function WeatherPageHeaderToday({
   locale,
   texts: textOverrides,
-  koreaWeather,
-  openWeatherMapWeather,
+  weather,
 }: WeatherPageHeaderTodayProps = {}) {
-  const isKoreaProvider = isKoreaWeatherLocale(locale);
-  const koreaWeatherFallback = useWeatherKorea({
-    enabled: !koreaWeather && isKoreaProvider,
-  });
-  const openWeatherMapWeatherFallback = useOpenWeatherMap({
+  const weatherFallback = useWeather({
     locale,
-    enabledNow: !openWeatherMapWeather && !isKoreaProvider,
-    enabledForecast: !openWeatherMapWeather && !isKoreaProvider,
+    enabled: !weather,
   });
-  const korea = koreaWeather ?? koreaWeatherFallback;
-  const openWeatherMap = openWeatherMapWeather ?? openWeatherMapWeatherFallback;
+  const currentWeather = weather ?? weatherFallback;
   const texts = resolveWeatherPageHeaderTexts(textOverrides);
-  const openWeatherMapToday = useMemo(
-    () => getOpenWeatherMapTodayForecast(openWeatherMap.forecast),
-    [openWeatherMap.forecast],
+  const now = useMemo(
+    () =>
+      isWeatherNowResponse(currentWeather.now) ? currentWeather.now : undefined,
+    [currentWeather.now],
+  );
+  const forecast = useMemo(
+    () =>
+      isWeatherForecastResponse(currentWeather.forecast)
+        ? currentWeather.forecast
+        : undefined,
+    [currentWeather.forecast],
   );
 
-  const isFetchingAlternate = useMemo(() => {
-    if (!isKoreaProvider)
-      return openWeatherMap.isFetchingNow || openWeatherMap.isFetchingForecast;
-    if (korea.isFetchingNow) return true;
-    return false;
-  }, [
-    isKoreaProvider,
-    korea.isFetchingNow,
-    openWeatherMap.isFetchingForecast,
-    openWeatherMap.isFetchingNow,
-  ]);
-
-  const iconCode = useMemo(() => {
-    if (isKoreaProvider) {
-      const kma_now = korea.now?.today?.condition;
-      if (kma_now && !kma_now.endsWith("null")) return kma_now;
-
-      const kma_forecast = korea.forecast?.today?.condition;
-      if (kma_forecast && !kma_forecast.endsWith("null")) return kma_forecast;
-    }
-
-    return getOpenWeatherMapConditionCode(
-      openWeatherMap.now?.weather?.[0]?.icon,
-    );
-  }, [
-    isKoreaProvider,
-    korea.forecast?.today?.condition,
-    korea.now?.today?.condition,
-    openWeatherMap.now?.weather,
-  ]);
-
-  const weatherStateName = useMemo(() => {
-    if (isKoreaProvider) {
-      const kma_now = korea.now?.today?.conditionName;
-      if (kma_now && !kma_now.endsWith("null"))
-        return kma_now || texts.conditionFallbackLabel;
-
-      const kma_forecast = korea.forecast?.today?.conditionName;
-      if (kma_forecast && !kma_forecast.endsWith("null"))
-        return kma_forecast || texts.conditionFallbackLabel;
-    }
-
-    return (
-      openWeatherMap.now?.weather?.[0]?.description ||
-      texts.conditionFallbackLabel
-    );
-  }, [
-    isKoreaProvider,
-    korea.forecast?.today?.conditionName,
-    korea.now?.today?.conditionName,
-    openWeatherMap.now?.weather,
-    texts.conditionFallbackLabel,
-  ]);
-
-  const temperature = useMemo(() => {
-    if (isKoreaProvider) {
-      const kma_now = korea.now?.today?.temperature;
-      if (kma_now && !Number.isNaN(Number(kma_now))) return Number(kma_now);
-
-      const kma_forecast = korea.forecast?.today?.temperature;
-      if (kma_forecast && !Number.isNaN(Number(kma_forecast)))
-        return Number(kma_forecast);
-    }
-
-    const alt_now = openWeatherMap.now?.main?.temp;
-    return typeof alt_now === "number" ? Math.round(alt_now) : null;
-  }, [
-    isKoreaProvider,
-    korea.forecast?.today?.temperature,
-    korea.now?.today?.temperature,
-    openWeatherMap.now?.main?.temp,
-  ]);
-
-  const humidity = useMemo(() => {
-    if (isKoreaProvider) {
-      const kma_now = korea.now?.today?.humidity;
-      if (kma_now && !Number.isNaN(Number(kma_now))) return Number(kma_now);
-
-      const kma_forecast = korea.forecast?.today?.humidity;
-      if (kma_forecast && !Number.isNaN(Number(kma_forecast)))
-        return Number(kma_forecast);
-    }
-
-    const alt_now = openWeatherMap.now?.main?.humidity;
-    return typeof alt_now === "number" ? Math.round(alt_now) : null;
-  }, [
-    isKoreaProvider,
-    korea.forecast?.today?.humidity,
-    korea.now?.today?.humidity,
-    openWeatherMap.now?.main?.humidity,
-  ]);
-
-  const maxTemperature = useMemo(() => {
-    if (isKoreaProvider) {
-      const kma_forecast = korea.forecast?.today?.max_temperature;
-      if (
-        kma_forecast !== null &&
-        kma_forecast !== undefined &&
-        !Number.isNaN(Number(kma_forecast))
-      )
-        return Number(kma_forecast);
-    }
+  const iconCode = useMemo(
+    () => now?.today.condition || forecast?.today.condition || "sky-1",
+    [forecast?.today.condition, now?.today.condition],
+  );
 
-    const alt_forecast = openWeatherMapToday?.max_temperature;
-    if (
-      alt_forecast !== null &&
-      alt_forecast !== undefined &&
-      !Number.isNaN(Number(alt_forecast))
-    )
-      return Number(alt_forecast);
+  const weatherStateName = useMemo(
+    () =>
+      now?.today.conditionName ||
+      forecast?.today.conditionName ||
+      texts.conditionFallbackLabel,
+    [
+      forecast?.today.conditionName,
+      now?.today.conditionName,
+      texts.conditionFallbackLabel,
+    ],
+  );
 
-    return null;
-  }, [
-    isKoreaProvider,
-    korea.forecast?.today?.max_temperature,
-    openWeatherMapToday?.max_temperature,
-  ]);
+  const temperature = useMemo(
+    () =>
+      toWeatherNumber(now?.today.temperature) ??
+      toWeatherNumber(forecast?.today.temperature),
+    [forecast?.today.temperature, now?.today.temperature],
+  );
 
-  const minTemperature = useMemo(() => {
-    if (isKoreaProvider) {
-      const kma_forecast = korea.forecast?.today?.min_temperature;
-      if (
-        kma_forecast !== null &&
-        kma_forecast !== undefined &&
-        !Number.isNaN(Number(kma_forecast))
-      )
-        return Number(kma_forecast);
-    }
+  const humidity = useMemo(
+    () =>
+      toWeatherNumber(now?.today.humidity) ??
+      toWeatherNumber(forecast?.today.humidity),
+    [forecast?.today.humidity, now?.today.humidity],
+  );
 
-    const alt_forecast = openWeatherMapToday?.min_temperature;
-    if (
-      alt_forecast !== null &&
-      alt_forecast !== undefined &&
-      !Number.isNaN(Number(alt_forecast))
-    )
-      return Number(alt_forecast);
+  const maxTemperature = useMemo(
+    () => toWeatherNumber(forecast?.today.max_temperature),
+    [forecast?.today.max_temperature],
+  );
 
-    return null;
-  }, [
-    isKoreaProvider,
-    korea.forecast?.today?.min_temperature,
-    openWeatherMapToday?.min_temperature,
-  ]);
+  const minTemperature = useMemo(
+    () => toWeatherNumber(forecast?.today.min_temperature),
+    [forecast?.today.min_temperature],
+  );
   const alert = (
-    <WeatherPageHeaderAlert locale={locale} texts={textOverrides} />
+    <WeatherPageHeaderAlert
+      locale={locale}
+      texts={textOverrides}
+      weather={currentWeather}
+    />
   );
 
   return (
     <div className="weather-today-container">
-      {isFetchingAlternate ? (
+      {currentWeather.isFetchingNow ? (
         <>
           {alert}
           <Alternate.LoadingDefault direction="horizontal">

package/src/weather/components/page-header/index.ts

@@ -6,6 +6,11 @@ import WeatherPageHeaderNextDays from "./NextDays";
 import WeatherPageHeaderToday from "./Today";
 
 // 기존 Container 호출 계약을 유지하면서, 서비스 재조합용 하위 조각 접근도 함께 연다.
+/**
+ * Weather Page Header; 조합형 page-header namespace 컴포넌트.
+ * @component
+ * @desc 기존 container 호출 계약을 유지하고 서비스 재조합용 하위 조각을 정적 속성으로 노출한다.
+ */
 export const WeatherPageHeader = Object.assign(WeatherPageHeaderContainer, {
   Container: WeatherPageHeaderContainer,
   Address: WeatherPageHeaderAddress,

package/src/weather/data/response.ts

@@ -1,24 +1,6 @@
-import type { API_Res_WeatherKoreaBase } from "../types";
+import type { API_Res_WeatherBase } 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 = {
+const API_RES_BASE: API_Res_WeatherBase = {
   sky: null,
   drop: null,
   rainAmount: null,
@@ -28,9 +10,8 @@ const API_RES_BASE: API_Res_WeatherKoreaBase = {
   conditionName: null,
 };
 
-const WEATHER_KOREA_RESPONSE = {
-  API_RES_RAW,
+const WEATHER_RESPONSE = {
   API_RES_BASE,
 };
 
-export default WEATHER_KOREA_RESPONSE;
+export default WEATHER_RESPONSE;

package/src/weather/hooks/index.ts

@@ -1,4 +1,4 @@
-import useOpenWeatherMap from "./useOpenWeatherMap";
-import useWeatherKorea from "./useWeatherKorea";
+import useWeather from "./useWeather";
+import useWeatherAlert from "./useWeatherAlert";
 
-export { useWeatherKorea, useOpenWeatherMap };
+export { useWeather, useWeatherAlert };

package/src/weather/hooks/useWeather.ts

@@ -0,0 +1,52 @@
+"use client";
+
+import { useMemo } from "react";
+import { useAtomValue } from "jotai";
+import { useQueryWeatherSummary } from "../apis/client";
+import { weatherCoordinate, weatherFarmIdx } from "../jotai";
+import type {
+  API_Req_Weather,
+  UseWeatherOptions,
+  UseWeatherReturn,
+} from "../types";
+
+/**
+ * Weather Hook; 통합 weather summary API를 조회한다.
+ * @hook
+ * @desc weatherCoordinate/weatherFarmIdx atom 값을 통합 summary route 요청 파라미터로 변환해 조회한다.
+ * @param {UseWeatherOptions} [options] weather 조회 옵션
+ * @param {string} [options.locale] 요청 언어 코드
+ * @param {boolean} [options.enabled] query 실행 여부
+ * @return {UseWeatherReturn} 통합 weather query 결과
+ */
+export default function useWeather({
+  locale,
+  enabled = true,
+}: UseWeatherOptions = {}): UseWeatherReturn {
+  const coordinate = useAtomValue(weatherCoordinate);
+  const farm_idx = useAtomValue(weatherFarmIdx);
+  const params = useMemo<API_Req_Weather>(
+    () => ({
+      lat: coordinate.lat,
+      lng: coordinate.lng,
+      ...(farm_idx ? { farm_idx } : {}),
+      ...(locale ? { locale } : {}),
+    }),
+    [coordinate.lat, coordinate.lng, farm_idx, locale],
+  );
+  const { data, isFetching } = useQueryWeatherSummary(params, { enabled });
+
+  const alert = useMemo(() => data?.alert?.alerts || [], [data]);
+
+  return {
+    params,
+    coordinate,
+    farm_idx,
+    ...(data ? { summary: data, now: data.now, forecast: data.forecast } : {}),
+    alert,
+    isFetching,
+    isFetchingNow: isFetching,
+    isFetchingForecast: isFetching,
+    isFetchingAlert: isFetching,
+  };
+}

package/src/weather/hooks/useWeatherAlert.ts

@@ -0,0 +1,35 @@
+"use client";
+
+import { useMemo } from "react";
+import { useAtomValue } from "jotai";
+import { useQueryWeatherAlert } from "../apis/client";
+import { weatherFarmIdx } from "../jotai";
+import type { UseWeatherAlertOptions, UseWeatherAlertReturn } from "../types";
+
+/**
+ * Weather Hook; 통합 weather alert API를 조회한다.
+ * @hook
+ * @desc weatherFarmIdx atom 값을 통합 alert route 요청 파라미터로 변환해 조회한다.
+ * @param {UseWeatherAlertOptions} [options] 특보 조회 옵션
+ * @param {boolean} [options.enabled] query 실행 여부
+ * @return {UseWeatherAlertReturn} 특보 query 결과
+ */
+export default function useWeatherAlert({
+  enabled = true,
+}: UseWeatherAlertOptions = {}): UseWeatherAlertReturn {
+  const farm_idx = useAtomValue(weatherFarmIdx);
+  const { data, isFetching } = useQueryWeatherAlert(
+    {
+      farm_idx,
+    },
+    { enabled },
+  );
+
+  const alert = useMemo(() => data?.alerts || [], [data]);
+
+  return {
+    farm_idx,
+    alert,
+    isFetching,
+  };
+}

package/src/weather/index.tsx

@@ -2,12 +2,12 @@
 import "./index.scss";
 
 /**
- * Weather; page-header 템플릿과 api/hook/jotai 도구를 함께 제공하는 엔트리
+ * Weather; page-header 템플릿과 normalized API/hook/jotai 도구를 제공하는 엔트리
  */
 export * from "./utils";
 export * from "./apis";
-export * from "./jotai";
 export * from "./hooks";
+export * from "./jotai";
 export * from "./types";
 export { default as WeatherComponents } from "./components";
 export { WeatherPageHeader } from "./components";

package/src/weather/jotai/coordinate.ts

@@ -3,6 +3,10 @@
 import type { WeatherCoordinate } from "../types";
 import { atomWithReset } from "jotai/utils";
 
+/**
+ * Weather Jotai; 현재 지역 좌표 atom.
+ * @desc service app에서 주입한 주소와 위경도를 weather template 전역 상태로 보관한다.
+ */
 export const weatherCoordinate = atomWithReset<WeatherCoordinate>({
   address: null,
   lat: null,

package/src/weather/jotai/farm-idx.ts

@@ -2,4 +2,8 @@
 
 import { atomWithReset } from "jotai/utils";
 
+/**
+ * Weather Jotai; 현재 농장 식별자 atom.
+ * @desc weather alert 조회에 사용할 farm_idx를 weather template 전역 상태로 보관한다.
+ */
 export const weatherFarmIdx = atomWithReset<number | null>(null);