@uniai-fe/uds-templates 0.5.29 → 0.6.1

package/src/weather/apis/server.ts

@@ -0,0 +1,373 @@
+"use server";
+
+import { generateQueryUrl, nextAPILog } from "@uniai-fe/util-api";
+import { setDebugResponseHeaders } from "@uniai-fe/util-next";
+import type { NextResponse } from "next/server";
+import WEATHER_RESPONSE from "../data/response";
+import { convertWeatherCoordinateToGrid } from "../utils";
+import type {
+  API_Res_WeatherAlert,
+  API_Res_WeatherForecast,
+  API_Res_WeatherNextDays,
+  API_Res_WeatherNow,
+  API_Res_WeatherSummary,
+  API_Res_WeatherToday,
+  WeatherBackendFetchParams,
+  WeatherServerRouteParams,
+} from "../types";
+
+const QUERY_URL = {
+  now: "/avic/weather/now",
+  forecast: "/avic/weather/forecast",
+  summary: "/avic/weather/summary",
+  alert: "/avic/weather/alert",
+};
+
+const { API_RES_BASE } = WEATHER_RESPONSE;
+type WeatherBackendRouteKind = keyof typeof QUERY_URL;
+
+const BACKEND_COMMON_QUERY_KEYS = [
+  "farm_idx",
+  "lat",
+  "lng",
+  "locale",
+  "include_raw",
+] as const;
+const BACKEND_DATE_TIME_QUERY_PAIRS = {
+  now: [["base_date", "base_time"]],
+  forecast: [["base_date", "base_time"]],
+  summary: [
+    ["now_base_date", "now_base_time"],
+    ["forecast_base_date", "forecast_base_time"],
+  ],
+  alert: [],
+} as const;
+
+/**
+ * Weather backend; query 값 존재 여부 확인.
+ * @param {string | null} value 확인할 query 값
+ * @return {boolean} query 값 존재 여부
+ */
+const hasSearchParamValue = (value: string | null): value is string =>
+  value !== null && value !== "";
+
+/**
+ * Weather backend; query 값을 숫자로 변환한다.
+ * @param {URLSearchParams} searchParams service app local route query
+ * @param {string} key 숫자로 읽을 query key
+ * @return {number | null} 변환된 숫자 또는 null
+ */
+const getSearchParamNumber = (
+  searchParams: URLSearchParams,
+  key: string,
+): number | null => {
+  const value = searchParams.get(key);
+
+  if (!hasSearchParamValue(value)) return null;
+
+  const parsed = Number(value);
+
+  return Number.isFinite(parsed) ? parsed : null;
+};
+
+/**
+ * Weather backend; 재현용 date/time query를 pair 단위로 전달한다.
+ * @param {URLSearchParams} params backend 전달 query
+ * @param {URLSearchParams} searchParams service app local route query
+ * @param {WeatherBackendRouteKind} routeKind backend weather route 종류
+ */
+const setBackendDateTimeSearchParams = (
+  params: URLSearchParams,
+  searchParams: URLSearchParams,
+  routeKind: WeatherBackendRouteKind,
+): void => {
+  BACKEND_DATE_TIME_QUERY_PAIRS[routeKind].forEach(([dateKey, timeKey]) => {
+    const date = searchParams.get(dateKey);
+    const time = searchParams.get(timeKey);
+
+    if (!hasSearchParamValue(date) || !hasSearchParamValue(time)) return;
+
+    params.set(dateKey, date);
+    params.set(timeKey, time);
+  });
+};
+
+/**
+ * Weather backend; nx/ny query를 직접 값 또는 lat/lng 변환값으로 전달한다.
+ * @param {URLSearchParams} params backend 전달 query
+ * @param {URLSearchParams} searchParams service app local route query
+ */
+const setBackendGridSearchParams = (
+  params: URLSearchParams,
+  searchParams: URLSearchParams,
+): void => {
+  const providedNx = getSearchParamNumber(searchParams, "nx");
+  const providedNy = getSearchParamNumber(searchParams, "ny");
+  const { nx, ny } =
+    providedNx !== null && providedNy !== null
+      ? { nx: providedNx, ny: providedNy }
+      : convertWeatherCoordinateToGrid({
+          lat: getSearchParamNumber(searchParams, "lat"),
+          lng: getSearchParamNumber(searchParams, "lng"),
+        });
+
+  if (nx !== null && nx > 0) params.set("nx", String(nx));
+  if (ny !== null && ny > 0) params.set("ny", String(ny));
+};
+
+/**
+ * Weather backend; client route query를 backend 허용 query로 정리.
+ * @param {WeatherBackendRouteKind} routeKind backend weather route 종류
+ * @param {URLSearchParams} searchParams service app local route query
+ * @param {string} [searchParams.farm_idx] 농장 식별자
+ * @param {string} [searchParams.lat] 위도
+ * @param {string} [searchParams.lng] 경도
+ * @param {string} [searchParams.nx] backend 격자 X
+ * @param {string} [searchParams.ny] backend 격자 Y
+ * @param {string} [searchParams.base_date] 현재/예보 단일 route 재현용 날짜
+ * @param {string} [searchParams.base_time] 현재/예보 단일 route 재현용 시각
+ * @param {string} [searchParams.now_base_date] summary 현재 날씨 재현용 날짜
+ * @param {string} [searchParams.now_base_time] summary 현재 날씨 재현용 시각
+ * @param {string} [searchParams.forecast_base_date] summary 예보 날씨 재현용 날짜
+ * @param {string} [searchParams.forecast_base_time] summary 예보 날씨 재현용 시각
+ * @param {string} [searchParams.locale] 요청 언어 코드
+ * @param {string} [searchParams.include_raw] 원본 응답 포함 여부
+ * @return {URLSearchParams} backend 전달 query
+ */
+const getBackendSearchParams = (
+  routeKind: WeatherBackendRouteKind,
+  searchParams: URLSearchParams,
+): URLSearchParams => {
+  const params = new URLSearchParams();
+
+  if (routeKind === "alert") {
+    const farmIdx = searchParams.get("farm_idx");
+    if (hasSearchParamValue(farmIdx)) params.set("farm_idx", farmIdx);
+    return params;
+  }
+
+  BACKEND_COMMON_QUERY_KEYS.forEach(key => {
+    const value = searchParams.get(key);
+    if (hasSearchParamValue(value)) params.set(key, value);
+  });
+
+  setBackendGridSearchParams(params, searchParams);
+  setBackendDateTimeSearchParams(params, searchParams, routeKind);
+
+  return params;
+};
+
+/**
+ * Weather backend; 실패 시 사용할 현재 날씨 기본값 생성.
+ * @return {API_Res_WeatherToday} 현재 날씨 기본값
+ */
+const getWeatherTodayDefault = (): API_Res_WeatherToday => ({
+  ...API_RES_BASE,
+  temperature: null,
+  max_temperature: null,
+  min_temperature: null,
+  humidity: null,
+});
+
+/**
+ * Weather backend; 실패 시 사용할 내일/모레 예보 기본값 생성.
+ * @return {API_Res_WeatherNextDays} 내일/모레 예보 기본값
+ */
+const getWeatherNextDaysDefault = (): API_Res_WeatherNextDays => ({
+  ...API_RES_BASE,
+  max_temperature: null,
+  min_temperature: null,
+});
+
+/**
+ * Weather backend; 실패 시 사용할 현재 날씨 응답 생성.
+ * @return {API_Res_WeatherNow} 현재 날씨 fallback 응답
+ */
+const getWeatherNowDefault = (): API_Res_WeatherNow => ({
+  today: getWeatherTodayDefault(),
+  source: null,
+  fallback_used: true,
+});
+
+/**
+ * Weather backend; 실패 시 사용할 예보 날씨 응답 생성.
+ * @return {API_Res_WeatherForecast} 예보 날씨 fallback 응답
+ */
+const getWeatherForecastDefault = (): API_Res_WeatherForecast => ({
+  today: getWeatherTodayDefault(),
+  day_1: getWeatherNextDaysDefault(),
+  day_2: getWeatherNextDaysDefault(),
+  source: null,
+  fallback_used: true,
+});
+
+/**
+ * Weather backend; 실패 시 사용할 특보 응답 생성.
+ * @return {API_Res_WeatherAlert} 특보 fallback 응답
+ */
+const getWeatherAlertDefault = (): API_Res_WeatherAlert => ({
+  api_announcement_time: null,
+  total_count: 0,
+  alerts: [],
+});
+
+/**
+ * Weather backend; 실패 시 사용할 summary 응답 생성.
+ * @return {API_Res_WeatherSummary} summary fallback 응답
+ */
+const getWeatherSummaryDefault = (): API_Res_WeatherSummary => ({
+  now: getWeatherNowDefault(),
+  forecast: getWeatherForecastDefault(),
+  alert: getWeatherAlertDefault(),
+});
+
+/**
+ * Weather backend; backend weather route 호출과 fallback 응답 처리.
+ * @param {WeatherBackendFetchParams<Data>} params route 호출 옵션
+ * @param {string} params.domain backend API domain
+ * @param {string} params.routeUrl local route URL
+ * @param {string} params.queryUrl backend weather route URL
+ * @param {"now"|"forecast"|"summary"|"alert"} params.routeKind backend weather route 종류
+ * @param {URLSearchParams} params.searchParams client route query
+ * @param {Data} params.fallback 실패 시 반환할 fallback 응답
+ * @return {Promise<Data>} backend 응답 또는 fallback
+ */
+const fetchWeatherBackend = async <Data>({
+  domain,
+  routeUrl,
+  queryUrl,
+  routeKind,
+  searchParams,
+  fallback,
+}: WeatherBackendFetchParams<Data>): Promise<Data> => {
+  if (!domain) {
+    nextAPILog("GET", routeUrl, queryUrl, {
+      error: "환경변수를 확인하세요.",
+    });
+    return fallback;
+  }
+
+  const backendParams = getBackendSearchParams(routeKind, searchParams);
+  const url = generateQueryUrl({
+    domain,
+    routeUrl,
+    queryUrl,
+    searchParams: backendParams,
+  });
+
+  try {
+    const res = await fetch(url);
+    if (!res.ok) {
+      nextAPILog("GET", routeUrl, url, {
+        status: res.status,
+        statusText: res.statusText,
+      });
+      return fallback;
+    }
+
+    return (await res.json()) as Data;
+  } catch (error) {
+    nextAPILog("GET", routeUrl, url, { error });
+    return fallback;
+  }
+};
+
+/**
+ * Weather backend; 현재 날씨 proxy.
+ * @method GET
+ * @param {WeatherServerRouteParams} params route 호출 옵션
+ * @param {string} params.domain backend API domain
+ * @param {string} params.routeUrl service app local route URL
+ * @param {URLSearchParams} params.searchParams service app local route query
+ * @return {Promise<API_Res_WeatherNow>} 현재 날씨 응답
+ */
+export const routeWeatherNow = async ({
+  domain,
+  routeUrl,
+  searchParams,
+}: WeatherServerRouteParams): Promise<API_Res_WeatherNow> =>
+  await fetchWeatherBackend({
+    domain,
+    routeUrl,
+    queryUrl: QUERY_URL.now,
+    routeKind: "now",
+    searchParams,
+    fallback: getWeatherNowDefault(),
+  });
+
+/**
+ * Weather backend; 예보 날씨 proxy.
+ * @method GET
+ * @param {WeatherServerRouteParams} params route 호출 옵션
+ * @param {string} params.domain backend API domain
+ * @param {string} params.routeUrl service app local route URL
+ * @param {URLSearchParams} params.searchParams service app local route query
+ * @return {Promise<API_Res_WeatherForecast>} 예보 날씨 응답
+ */
+export const routeWeatherForecast = async ({
+  domain,
+  routeUrl,
+  searchParams,
+}: WeatherServerRouteParams): Promise<API_Res_WeatherForecast> =>
+  await fetchWeatherBackend({
+    domain,
+    routeUrl,
+    queryUrl: QUERY_URL.forecast,
+    routeKind: "forecast",
+    searchParams,
+    fallback: getWeatherForecastDefault(),
+  });
+
+/**
+ * Weather backend; 현재/예보/특보 summary proxy.
+ * @method GET
+ * @param {WeatherServerRouteParams} params route 호출 옵션
+ * @param {string} params.domain backend API domain
+ * @param {string} params.routeUrl service app local route URL
+ * @param {URLSearchParams} params.searchParams service app local route query
+ * @return {Promise<API_Res_WeatherSummary>} summary 응답
+ */
+export const routeWeatherSummary = async ({
+  domain,
+  routeUrl,
+  searchParams,
+}: WeatherServerRouteParams): Promise<API_Res_WeatherSummary> =>
+  await fetchWeatherBackend({
+    domain,
+    routeUrl,
+    queryUrl: QUERY_URL.summary,
+    routeKind: "summary",
+    searchParams,
+    fallback: getWeatherSummaryDefault(),
+  });
+
+/**
+ * Weather backend; 특보 proxy.
+ * @method GET
+ * @param {WeatherServerRouteParams} params route 호출 옵션
+ * @param {string} params.domain backend API domain
+ * @param {string} params.routeUrl service app local route URL
+ * @param {URLSearchParams} params.searchParams service app local route query
+ * @return {Promise<NextResponse<API_Res_WeatherAlert>>} 특보 응답
+ */
+export const routeWeatherAlert = async ({
+  domain,
+  routeUrl,
+  searchParams,
+}: WeatherServerRouteParams): Promise<NextResponse<API_Res_WeatherAlert>> => {
+  const res = await fetchWeatherBackend({
+    domain,
+    routeUrl,
+    queryUrl: QUERY_URL.alert,
+    routeKind: "alert",
+    searchParams,
+    fallback: getWeatherAlertDefault(),
+  });
+
+  return setDebugResponseHeaders<API_Res_WeatherAlert>({
+    res,
+    domain,
+    queryUrl: QUERY_URL.alert,
+    searchParams: getBackendSearchParams("alert", searchParams),
+  });
+};

package/src/weather/components/icon/Address.tsx

@@ -3,6 +3,13 @@
 import type { WeatherAddressIconProps } from "../../types";
 import MarkerIcon from "../../img/marker.svg";
 
+/**
+ * Weather Address Icon; 위치 아이콘 컴포넌트.
+ * @component
+ * @desc weather address 앞에 표시할 marker SVG를 접근성 label과 함께 렌더한다.
+ * @param {WeatherAddressIconProps} [props] 위치 아이콘 props
+ * @param {string} [props.alt] 아이콘 대체 텍스트
+ */
 export default function WeatherAddressIcon({
   alt,
 }: WeatherAddressIconProps = {}) {

package/src/weather/components/icon/Weather.tsx

@@ -9,12 +9,13 @@ import type { WeatherIconProps } from "../../types";
 // Storybook의 next/image mock과 동일한 client boundary에서 weather icon을 렌더한다.
 
 /**
- * 날씨; 아이콘
- * @desc
- * - 기상청 API 허브
- * - 2024. 11. 28. 발효 기준
- *
- * @see https://apihub.kma.go.kr/getAttachFile.do?fileName=(20241128)%EB%8B%A8%EA%B8%B0%EC%98%88%EB%B3%B4%20%EC%84%9C%EB%B9%84%EC%8A%A4%20%EA%B0%9C%EC%84%A0%EC%97%90%20%EB%94%B0%EB%A5%B8%20API%20%EB%B3%80%EA%B2%BD%EC%82%AC%ED%95%AD.pdf
+ * Weather Icon; 날씨 상태 아이콘 컴포넌트.
+ * @component
+ * @desc normalized weather condition code를 asset icon으로 렌더하고 상태 이름을 대체 텍스트로 사용한다.
+ * @param {WeatherIconProps} [props] 날씨 아이콘 props
+ * @param {string | null} [props.code] 날씨 아이콘 코드
+ * @param {string | null} [props.name] 날씨 상태 이름
+ * @param {string} [props.alt] 아이콘 대체 텍스트 fallback
  */
 export default function WeatherIcon({
   code,

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

@@ -8,6 +8,12 @@ import type { WeatherPageHeaderAddressProps } from "../../types";
 import { resolveWeatherPageHeaderTexts } from "../../utils";
 import WeatherAddressIcon from "../icon/Address";
 
+/**
+ * Weather Page Header; 현재 렌더링 시각을 표시 문자열로 변환.
+ * @util
+ * @desc 클라이언트 시각을 weather address 보조 텍스트 형식으로 변환한다.
+ * @return {string} yyyy-mm-dd hh:mm 형식의 렌더링 시각
+ */
 const getRenderedAt = (): string => {
   const now = new Date();
   const month = String(now.getMonth() + 1).padStart(2, "0");
@@ -18,6 +24,14 @@ const getRenderedAt = (): string => {
   return `${now.getFullYear()}-${month}-${date} ${hours}:${minutes}`;
 };
 
+/**
+ * Weather Page Header; 주소와 렌더링 시각을 표시하는 컴포넌트.
+ * @component
+ * @desc weatherCoordinate atom에 주입된 주소와 클라이언트 렌더링 시각을 표시한다.
+ * @param {WeatherPageHeaderAddressProps} [props] address props
+ * @param {string} [props.locale] 표시 언어 코드
+ * @param {Partial<WeatherPageHeaderTexts>} [props.texts] 서비스에서 주입한 표시 문구
+ */
 export default function WeatherPageHeaderAddress({
   texts: textOverrides,
 }: WeatherPageHeaderAddressProps = {}) {

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

@@ -3,21 +3,28 @@
 import { useMemo } from "react";
 
 import { Alternate } from "@uniai-fe/uds-primitives";
-import useWeatherKoreaAlert from "../../hooks/useWeatherKoreaAlert";
+import { useWeatherAlert } from "../../hooks";
 import type { WeatherPageHeaderAlertProps } from "../../types";
-import {
-  isKoreaWeatherLocale,
-  resolveWeatherPageHeaderTexts,
-} from "../../utils";
+import { resolveWeatherPageHeaderTexts } from "../../utils";
 
+/**
+ * Weather Page Header; 기상 특보를 표시하는 컴포넌트.
+ * @component
+ * @desc 통합 weather alert query 결과 또는 상위 weather props의 특보 목록을 표시한다.
+ * @param {WeatherPageHeaderAlertProps} [props] alert props
+ * @param {string} [props.locale] 표시 언어 코드
+ * @param {Partial<WeatherPageHeaderTexts>} [props.texts] 서비스에서 주입한 표시 문구
+ * @param {WeatherPageHeaderWeather} [props.weather] 상위 container에서 준비한 통합 weather query 결과
+ */
 export default function WeatherPageHeaderAlert({
-  locale,
   texts: textOverrides,
+  weather,
 }: WeatherPageHeaderAlertProps = {}) {
-  const isKoreaProvider = isKoreaWeatherLocale(locale);
-  const { alert, isFetching } = useWeatherKoreaAlert({
-    enabled: isKoreaProvider,
+  const alertFallback = useWeatherAlert({
+    enabled: !weather,
   });
+  const alert = weather?.alert ?? alertFallback.alert;
+  const isFetching = weather?.isFetchingAlert ?? alertFallback.isFetching;
   const texts = resolveWeatherPageHeaderTexts(textOverrides);
 
   const notice = useMemo((): string => {
@@ -42,10 +49,7 @@ export default function WeatherPageHeaderAlert({
     texts.alertWatchLevelLabel,
   ]);
 
-  if (
-    !isKoreaProvider ||
-    (!isFetching && (alert.length === 0 || !alert?.[0]?.alert_type))
-  ) {
+  if (!isFetching && (alert.length === 0 || !alert?.[0]?.alert_type)) {
     return null;
   }
 

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

@@ -5,37 +5,30 @@ import WeatherPageHeaderForecast from "./Forecast";
 import WeatherPageHeaderAddress from "./Address";
 import PageHeaderUtilityItem from "../../../page-frame/desktop/components/header/util/Item";
 import type { WeatherPageHeaderContainerProps } from "../../types";
-import { useOpenWeatherMap, useWeatherKorea } from "../../hooks";
-import { isKoreaWeatherLocale } from "../../utils";
+import { useWeather } from "../../hooks";
 
+/**
+ * Weather Page Header; address/today/forecast를 조합하는 container 컴포넌트.
+ * @component
+ * @desc 통합 weather summary query를 한 번 실행하고 address, today, forecast leaf에 전달한다.
+ * @param {WeatherPageHeaderContainerProps} [props] container props
+ * @param {string} [props.locale] 표시 언어 코드
+ * @param {Partial<WeatherPageHeaderTexts>} [props.texts] 서비스에서 주입한 표시 문구
+ */
 export default function WeatherPageHeaderContainer({
   locale,
   texts,
 }: WeatherPageHeaderContainerProps = {}) {
-  const isKoreaProvider = isKoreaWeatherLocale(locale);
-  const koreaWeather = useWeatherKorea({
-    enabled: isKoreaProvider,
-  });
-  const openWeatherMapWeather = useOpenWeatherMap({
-    locale,
-    enabledNow: !isKoreaProvider,
-    enabledForecast: !isKoreaProvider,
-  });
+  const weather = useWeather({ locale });
 
   return (
     <PageHeaderUtilityItem className="weather-page-header">
       <WeatherPageHeaderAddress locale={locale} texts={texts} />
-      <WeatherPageHeaderToday
-        locale={locale}
-        texts={texts}
-        koreaWeather={koreaWeather}
-        openWeatherMapWeather={openWeatherMapWeather}
-      />
+      <WeatherPageHeaderToday locale={locale} texts={texts} weather={weather} />
       <WeatherPageHeaderForecast
         locale={locale}
         texts={texts}
-        koreaWeather={koreaWeather}
-        openWeatherMapWeather={openWeatherMapWeather}
+        weather={weather}
       />
     </PageHeaderUtilityItem>
   );

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

@@ -1,46 +1,39 @@
 "use client";
 
-import { useMemo } from "react";
 import { Alternate } from "@uniai-fe/uds-primitives";
-import { useOpenWeatherMap, useWeatherKorea } from "../../hooks";
+import { useWeather } from "../../hooks";
 import type { WeatherPageHeaderForecastProps } from "../../types";
 import {
-  getOpenWeatherMapNextDays,
-  isKoreaWeatherLocale,
+  isWeatherForecastResponse,
   resolveWeatherPageHeaderTexts,
 } from "../../utils";
 import WeatherPageHeaderNextDays from "./NextDays";
 
+/**
+ * Weather Page Header; 내일/모레 예보를 표시하는 컴포넌트.
+ * @component
+ * @desc 통합 weather forecast 응답에서 day_1/day_2를 추출해 하루 단위 예보로 표시한다.
+ * @param {WeatherPageHeaderForecastProps} [props] forecast props
+ * @param {string} [props.locale] 표시 언어 코드
+ * @param {Partial<WeatherPageHeaderTexts>} [props.texts] 서비스에서 주입한 표시 문구
+ * @param {WeatherPageHeaderWeather} [props.weather] 상위 container에서 준비한 통합 weather query 결과
+ */
 export default function WeatherPageHeaderForecast({
   locale,
   texts: textOverrides,
-  koreaWeather,
-  openWeatherMapWeather,
+  weather,
 }: WeatherPageHeaderForecastProps = {}) {
-  const isKoreaProvider = isKoreaWeatherLocale(locale);
-  const koreaWeatherFallback = useWeatherKorea({
-    enabled: !koreaWeather && isKoreaProvider,
-  });
-  const openWeatherMapWeatherFallback = useOpenWeatherMap({
+  const weatherFallback = useWeather({
     locale,
-    enabledNow: false,
-    enabledForecast: !openWeatherMapWeather && !isKoreaProvider,
+    enabled: !weather,
   });
-  const korea = koreaWeather ?? koreaWeatherFallback;
-  const openWeatherMap = openWeatherMapWeather ?? openWeatherMapWeatherFallback;
+  const currentWeather = weather ?? weatherFallback;
   const texts = resolveWeatherPageHeaderTexts(textOverrides);
-  const openWeatherMapNextDays = useMemo(
-    () => getOpenWeatherMapNextDays(openWeatherMap.forecast),
-    [openWeatherMap.forecast],
-  );
-  const forecastDays = isKoreaProvider
-    ? korea.forecast
-    : openWeatherMapNextDays;
-  const isFetching = isKoreaProvider
-    ? korea.isFetchingForecast
-    : openWeatherMap.isFetchingForecast;
+  const forecast = isWeatherForecastResponse(currentWeather.forecast)
+    ? currentWeather.forecast
+    : undefined;
 
-  if (isFetching) {
+  if (currentWeather.isFetchingForecast) {
     return (
       <div className="weather-next-days-container">
         <Alternate.LoadingDefault direction="horizontal">
@@ -54,12 +47,12 @@ export default function WeatherPageHeaderForecast({
     <>
       <WeatherPageHeaderNextDays
         title={texts.tomorrowLabel}
-        data={forecastDays?.day_1}
+        data={forecast?.day_1}
         texts={textOverrides}
       />
       <WeatherPageHeaderNextDays
         title={texts.dayAfterTomorrowLabel}
-        data={forecastDays?.day_2}
+        data={forecast?.day_2}
         texts={textOverrides}
       />
     </>

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

@@ -4,6 +4,16 @@ import type { WeatherPageHeaderNextDaysProps } from "../../types";
 import { resolveWeatherPageHeaderTexts } from "../../utils";
 import WeatherIcon from "../icon/Weather";
 
+/**
+ * Weather Page Header; 하루 단위 예보를 표시하는 컴포넌트.
+ * @component
+ * @desc title과 normalized forecast day 데이터를 조합해 날씨 아이콘과 최저/최고 기온을 표시한다.
+ * @param {WeatherPageHeaderNextDaysProps} props next days props
+ * @param {string} props.title 날짜 라벨
+ * @param {API_Res_WeatherNextDays} [props.data] 예보 데이터
+ * @param {string} [props.locale] 표시 언어 코드
+ * @param {Partial<WeatherPageHeaderTexts>} [props.texts] 서비스에서 주입한 표시 문구
+ */
 export default function WeatherPageHeaderNextDays({
   title,
   data,