@uniai-fe/uds-templates 0.5.28 → 0.6.0

package/src/weather/apis/client.ts

@@ -0,0 +1,339 @@
+"use client";
+
+import { useQuery, type UseQueryResult } from "@tanstack/react-query";
+import { getQueryString } from "@uniai-fe/util-api";
+import { isValidNumber } from "@uniai-fe/util-functions";
+import type {
+  API_Req_Weather,
+  API_Req_WeatherAlert,
+  API_Res_WeatherAlert,
+  API_Res_WeatherForecast,
+  API_Res_WeatherNow,
+  API_Res_WeatherSummary,
+  WeatherClientQueryOptions,
+  WeatherClientRouteOptions,
+} from "../types";
+
+const WEATHER_CLIENT_ROUTE_PATH = {
+  now: "/api/weather/now",
+  forecast: "/api/weather/forecast",
+  summary: "/api/weather/summary",
+  alert: "/api/weather/alert",
+} as const;
+
+/**
+ * Weather Client; query string에 포함 가능한 값인지 확인.
+ * @param {unknown} value 확인할 query 값
+ * @return {boolean} query 포함 가능 여부
+ */
+const hasQueryValue = (value: unknown): boolean =>
+  value !== null && typeof value !== "undefined" && value !== "";
+
+/**
+ * Weather Client; backend weather route query로 전달할 값만 정리.
+ * @param {API_Req_Weather} params 날씨 요청 파라미터
+ * @param {number|string|null} [params.farm_idx] 농장 식별자
+ * @param {number|null} [params.lat] 위도
+ * @param {number|null} [params.lng] 경도
+ * @param {string} [params.locale] 요청 언어 코드
+ * @param {boolean} [params.include_raw] 원본 응답 포함 여부
+ * @return {API_Req_Weather} local route query 파라미터
+ */
+export const getWeatherClientParams = ({
+  farm_idx,
+  lat,
+  lng,
+  locale,
+  include_raw,
+}: API_Req_Weather): API_Req_Weather => ({
+  ...(hasQueryValue(farm_idx) ? { farm_idx } : {}),
+  ...(hasQueryValue(lat) ? { lat } : {}),
+  ...(hasQueryValue(lng) ? { lng } : {}),
+  ...(locale ? { locale } : {}),
+  ...(typeof include_raw === "boolean" ? { include_raw } : {}),
+});
+
+/**
+ * Weather Client; route override 또는 기본 local route 경로 선택.
+ * @param {string} [routePath] service app의 local weather route 경로
+ * @param {string} fallbackRoutePath 기본 local weather route 경로
+ * @return {string} fetch에 사용할 local route 경로
+ */
+const getWeatherRoutePath = (
+  routePath: string | undefined,
+  fallbackRoutePath: string,
+): string => routePath || fallbackRoutePath;
+
+/**
+ * Weather Client; 현재/예보/summary 조회가 가능한 위치 입력인지 확인.
+ * @param {API_Req_Weather} params 날씨 요청 파라미터
+ * @param {number|null} [params.lat] 위도
+ * @param {number|null} [params.lng] 경도
+ * @return {boolean} 위치 기반 weather query 실행 가능 여부
+ */
+const isWeatherLocationAvailable = ({ lat, lng }: API_Req_Weather): boolean =>
+  lat !== null &&
+  lng !== null &&
+  typeof lat !== "undefined" &&
+  typeof lng !== "undefined" &&
+  isValidNumber(lat) &&
+  isValidNumber(lng);
+
+/**
+ * Weather Client; 특보 조회가 가능한 농장 식별자인지 확인.
+ * @param {API_Req_WeatherAlert} params 특보 요청 파라미터
+ * @param {number|string|null} params.farm_idx 농장 식별자
+ * @return {boolean} 특보 query 실행 가능 여부
+ */
+const isWeatherFarmAvailable = ({ farm_idx }: API_Req_WeatherAlert): boolean =>
+  hasQueryValue(farm_idx) && Number(farm_idx) > 0;
+
+/**
+ * Weather Client; React Query key에 사용할 weather 요청 값을 정렬.
+ * @param {API_Req_Weather} params 날씨 요청 파라미터
+ * @param {number|string|null} [params.farm_idx] 농장 식별자
+ * @param {number|null} [params.lat] 위도
+ * @param {number|null} [params.lng] 경도
+ * @param {string} [params.locale] 요청 언어 코드
+ * @param {boolean} [params.include_raw] 원본 응답 포함 여부
+ * @return {readonly unknown[]} React Query key 값
+ */
+const getWeatherQueryKeyValues = (params: API_Req_Weather) => {
+  const { farm_idx, lat, lng, locale, include_raw } =
+    getWeatherClientParams(params);
+
+  return [farm_idx, lat, lng, locale, include_raw] as const;
+};
+
+/**
+ * Weather Client; 현재 날씨 fetch.
+ * @method GET
+ * @param {API_Req_WeatherNow} params 현재 날씨 요청 파라미터
+ * @param {number|string|null} [params.farm_idx] 농장 식별자
+ * @param {number|null} [params.lat] 위도
+ * @param {number|null} [params.lng] 경도
+ * @param {string} [params.locale] 요청 언어 코드
+ * @param {boolean} [params.include_raw] 원본 응답 포함 여부
+ * @param {WeatherClientRouteOptions} [options] local route 옵션
+ * @param {string} [options.routePath] service app의 local weather route 경로
+ * @return {Promise<Data>} 현재 날씨 응답
+ */
+export const getWeatherNow = async <Data = API_Res_WeatherNow>(
+  params: API_Req_Weather,
+  options: WeatherClientRouteOptions = {},
+): Promise<Data> =>
+  await (
+    await fetch(
+      `${getWeatherRoutePath(
+        options.routePath,
+        WEATHER_CLIENT_ROUTE_PATH.now,
+      )}${getQueryString(getWeatherClientParams(params))}`,
+    )
+  ).json();
+
+/**
+ * Weather Client; 예보 날씨 fetch.
+ * @method GET
+ * @param {API_Req_WeatherForecast} params 예보 날씨 요청 파라미터
+ * @param {number|string|null} [params.farm_idx] 농장 식별자
+ * @param {number|null} [params.lat] 위도
+ * @param {number|null} [params.lng] 경도
+ * @param {string} [params.locale] 요청 언어 코드
+ * @param {boolean} [params.include_raw] 원본 응답 포함 여부
+ * @param {WeatherClientRouteOptions} [options] local route 옵션
+ * @param {string} [options.routePath] service app의 local weather route 경로
+ * @return {Promise<Data>} 예보 날씨 응답
+ */
+export const getWeatherForecast = async <Data = API_Res_WeatherForecast>(
+  params: API_Req_Weather,
+  options: WeatherClientRouteOptions = {},
+): Promise<Data> =>
+  await (
+    await fetch(
+      `${getWeatherRoutePath(
+        options.routePath,
+        WEATHER_CLIENT_ROUTE_PATH.forecast,
+      )}${getQueryString(getWeatherClientParams(params))}`,
+    )
+  ).json();
+
+/**
+ * Weather Client; summary fetch.
+ * @method GET
+ * @param {API_Req_WeatherSummary} params summary 요청 파라미터
+ * @param {number|string|null} [params.farm_idx] 농장 식별자
+ * @param {number|null} [params.lat] 위도
+ * @param {number|null} [params.lng] 경도
+ * @param {string} [params.locale] 요청 언어 코드
+ * @param {boolean} [params.include_raw] 원본 응답 포함 여부
+ * @param {WeatherClientRouteOptions} [options] local route 옵션
+ * @param {string} [options.routePath] service app의 local weather route 경로
+ * @return {Promise<Data>} summary 응답
+ */
+export const getWeatherSummary = async <Data = API_Res_WeatherSummary>(
+  params: API_Req_Weather,
+  options: WeatherClientRouteOptions = {},
+): Promise<Data> =>
+  await (
+    await fetch(
+      `${getWeatherRoutePath(
+        options.routePath,
+        WEATHER_CLIENT_ROUTE_PATH.summary,
+      )}${getQueryString(getWeatherClientParams(params))}`,
+    )
+  ).json();
+
+/**
+ * Weather Client; 특보 fetch.
+ * @method GET
+ * @param {API_Req_WeatherAlert} params 특보 요청 파라미터
+ * @param {number|string|null} params.farm_idx 농장 식별자
+ * @param {WeatherClientRouteOptions} [options] local route 옵션
+ * @param {string} [options.routePath] service app의 local weather route 경로
+ * @return {Promise<Data>} 특보 응답
+ */
+export const getWeatherAlert = async <Data = API_Res_WeatherAlert>(
+  params: API_Req_WeatherAlert,
+  options: WeatherClientRouteOptions = {},
+): Promise<Data> =>
+  await (
+    await fetch(
+      `${getWeatherRoutePath(
+        options.routePath,
+        WEATHER_CLIENT_ROUTE_PATH.alert,
+      )}${getQueryString(params)}`,
+    )
+  ).json();
+
+/**
+ * Weather Client; 현재 날씨 react query.
+ * @method GET
+ * @param {API_Req_WeatherNow} params 현재 날씨 요청 파라미터
+ * @param {number|string|null} [params.farm_idx] 농장 식별자
+ * @param {number|null} [params.lat] 위도
+ * @param {number|null} [params.lng] 경도
+ * @param {string} [params.locale] 요청 언어 코드
+ * @param {boolean} [params.include_raw] 원본 응답 포함 여부
+ * @param {WeatherClientQueryOptions} [options] query 옵션
+ * @param {boolean} [options.enabled] query 실행 여부
+ * @param {string} [options.routePath] service app의 local weather route 경로
+ * @return {UseQueryResult<Data>} 현재 날씨 query 결과
+ */
+export const useQueryWeatherNow = <Data = API_Res_WeatherNow>(
+  params: API_Req_Weather,
+  options: WeatherClientQueryOptions = {},
+): UseQueryResult<Data> => {
+  const routePath = getWeatherRoutePath(
+    options.routePath,
+    WEATHER_CLIENT_ROUTE_PATH.now,
+  );
+
+  return useQuery({
+    queryKey: ["weather_now", routePath, ...getWeatherQueryKeyValues(params)],
+    queryFn: () => getWeatherNow<Data>(params, { routePath }),
+    enabled: (options.enabled ?? true) && isWeatherLocationAvailable(params),
+    staleTime: 10 * 60 * 1000,
+    refetchInterval: 5 * 60 * 1000,
+    refetchOnWindowFocus: true,
+  });
+};
+
+/**
+ * Weather Client; 예보 날씨 react query.
+ * @method GET
+ * @param {API_Req_WeatherForecast} params 예보 날씨 요청 파라미터
+ * @param {number|string|null} [params.farm_idx] 농장 식별자
+ * @param {number|null} [params.lat] 위도
+ * @param {number|null} [params.lng] 경도
+ * @param {string} [params.locale] 요청 언어 코드
+ * @param {boolean} [params.include_raw] 원본 응답 포함 여부
+ * @param {WeatherClientQueryOptions} [options] query 옵션
+ * @param {boolean} [options.enabled] query 실행 여부
+ * @param {string} [options.routePath] service app의 local weather route 경로
+ * @return {UseQueryResult<Data>} 예보 날씨 query 결과
+ */
+export const useQueryWeatherForecast = <Data = API_Res_WeatherForecast>(
+  params: API_Req_Weather,
+  options: WeatherClientQueryOptions = {},
+): UseQueryResult<Data> => {
+  const routePath = getWeatherRoutePath(
+    options.routePath,
+    WEATHER_CLIENT_ROUTE_PATH.forecast,
+  );
+
+  return useQuery({
+    queryKey: [
+      "weather_forecast",
+      routePath,
+      ...getWeatherQueryKeyValues(params),
+    ],
+    queryFn: () => getWeatherForecast<Data>(params, { routePath }),
+    enabled: (options.enabled ?? true) && isWeatherLocationAvailable(params),
+    staleTime: 30 * 60 * 1000,
+  });
+};
+
+/**
+ * Weather Client; summary react query.
+ * @method GET
+ * @param {API_Req_WeatherSummary} params summary 요청 파라미터
+ * @param {number|string|null} [params.farm_idx] 농장 식별자
+ * @param {number|null} [params.lat] 위도
+ * @param {number|null} [params.lng] 경도
+ * @param {string} [params.locale] 요청 언어 코드
+ * @param {boolean} [params.include_raw] 원본 응답 포함 여부
+ * @param {WeatherClientQueryOptions} [options] query 옵션
+ * @param {boolean} [options.enabled] query 실행 여부
+ * @param {string} [options.routePath] service app의 local weather route 경로
+ * @return {UseQueryResult<Data>} summary query 결과
+ */
+export const useQueryWeatherSummary = <Data = API_Res_WeatherSummary>(
+  params: API_Req_Weather,
+  options: WeatherClientQueryOptions = {},
+): UseQueryResult<Data> => {
+  const routePath = getWeatherRoutePath(
+    options.routePath,
+    WEATHER_CLIENT_ROUTE_PATH.summary,
+  );
+
+  return useQuery({
+    queryKey: [
+      "weather_summary",
+      routePath,
+      ...getWeatherQueryKeyValues(params),
+    ],
+    queryFn: () => getWeatherSummary<Data>(params, { routePath }),
+    enabled: (options.enabled ?? true) && isWeatherLocationAvailable(params),
+    staleTime: 10 * 60 * 1000,
+  });
+};
+
+/**
+ * Weather Client; 특보 react query.
+ * @method GET
+ * @param {API_Req_WeatherAlert} params 특보 요청 파라미터
+ * @param {number|string|null} params.farm_idx 농장 식별자
+ * @param {WeatherClientQueryOptions} [options] query 옵션
+ * @param {boolean} [options.enabled] query 실행 여부
+ * @param {string} [options.routePath] service app의 local weather route 경로
+ * @return {UseQueryResult<Data>} 특보 query 결과
+ */
+export const useQueryWeatherAlert = <Data = API_Res_WeatherAlert>(
+  params: API_Req_WeatherAlert,
+  options: WeatherClientQueryOptions = {},
+): UseQueryResult<Data> => {
+  const farmIdx = params.farm_idx;
+  const routePath = getWeatherRoutePath(
+    options.routePath,
+    WEATHER_CLIENT_ROUTE_PATH.alert,
+  );
+
+  return useQuery({
+    queryKey: ["weather_alert", routePath, farmIdx],
+    queryFn: () => getWeatherAlert<Data>({ farm_idx: farmIdx }, { routePath }),
+    enabled:
+      (options.enabled ?? true) &&
+      isWeatherFarmAvailable({ farm_idx: farmIdx }),
+    staleTime: 60 * 60 * 1000,
+  });
+};

package/src/weather/apis/index.ts

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

package/src/weather/apis/server.ts

@@ -0,0 +1,264 @@
+"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 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;
+const BACKEND_QUERY_KEYS = [
+  "farm_idx",
+  "lat",
+  "lng",
+  "locale",
+  "include_raw",
+] as const;
+
+/**
+ * Weather backend; client route query를 backend 허용 query로 정리.
+ * @param {URLSearchParams} searchParams service app local route query
+ * @param {string} [searchParams.farm_idx] 농장 식별자
+ * @param {string} [searchParams.lat] 위도
+ * @param {string} [searchParams.lng] 경도
+ * @param {string} [searchParams.locale] 요청 언어 코드
+ * @param {string} [searchParams.include_raw] 원본 응답 포함 여부
+ * @return {URLSearchParams} backend 전달 query
+ */
+const getBackendSearchParams = (
+  searchParams: URLSearchParams,
+): URLSearchParams => {
+  const params = new URLSearchParams();
+
+  BACKEND_QUERY_KEYS.forEach(key => {
+    const value = searchParams.get(key);
+    if (value !== null && value !== "") params.set(key, value);
+  });
+
+  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 {URLSearchParams} params.searchParams client route query
+ * @param {Data} params.fallback 실패 시 반환할 fallback 응답
+ * @return {Promise<Data>} backend 응답 또는 fallback
+ */
+const fetchWeatherBackend = async <Data>({
+  domain,
+  routeUrl,
+  queryUrl,
+  searchParams,
+  fallback,
+}: WeatherBackendFetchParams<Data>): Promise<Data> => {
+  if (!domain) {
+    nextAPILog("GET", routeUrl, queryUrl, {
+      error: "환경변수를 확인하세요.",
+    });
+    return fallback;
+  }
+
+  const backendParams = getBackendSearchParams(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,
+    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,
+    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,
+    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,
+    searchParams,
+    fallback: getWeatherAlertDefault(),
+  });
+
+  return setDebugResponseHeaders<API_Res_WeatherAlert>({
+    res,
+    domain,
+    queryUrl: QUERY_URL.alert,
+    searchParams: getBackendSearchParams(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 = {}) {