@uniai-fe/uds-templates 0.4.26 → 0.4.28

package/README.md

@@ -50,8 +50,13 @@ Next.js 서비스에서 primitives와 동일한 방식으로 **Raw TypeScript**
   - `UseModalReturn`
 - `/weather`
   - `WeatherComponents.PageHeader`
+  - `WeatherPageHeader`
   - `WeatherPageHeaderContainer`
-  - `WeatherMockProvider`
+  - `WeatherPageHeaderAddress`
+  - `WeatherPageHeaderToday`
+  - `WeatherPageHeaderForecast`
+  - `WeatherPageHeaderAlert`
+  - `WeatherPageHeaderNextDays`
   - `weatherCoordinate`
   - `useWeatherKorea`
   - `useOpenWeatherMap`
@@ -116,7 +121,7 @@ Next.js 서비스에서 primitives와 동일한 방식으로 **Raw TypeScript**
   - modal description은 기본으로 `"사용 중 문제가 있나요? 아래 내용을 적어 문의해 주세요."`를 사용하고 특수 문구가 필요할 때만 `dialogOptions.description`으로 덮어쓴다.
   - 로그인 후 `farm_name`, `contact`를 auto-fill + readonly로 보여야 할 때는 `formContextOptions.defaultValues`와 `farmNameField.mode`, `contactField.mode`를 함께 전달한다.
 - `/weather/**`
-  - page-frame header utility에 결합되는 weather header 템플릿과 weather data hook/mock 도구를 제공한다.
+  - page-frame header utility에 결합되는 weather header 템플릿, page-header 조각 export, weather data hook/API 도구를 제공한다.
 - `/cctv/**`
   - finder/viewer/video/pagination 조합과 rtc/company-list API helper를 제공한다.
 - `/page-frame/**`

package/package.json

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

package/src/weather/apis/korea/client.ts

@@ -1,7 +1,7 @@
 "use client";
 
 import { useQuery, type UseQueryResult } from "@tanstack/react-query";
-import { getQueryString } from "@uniai-fe/util-functions";
+import { getQueryString } from "@uniai-fe/util-api";
 import type {
   API_Req_WeatherKorea,
   API_Req_WeatherKoreaAlert,

package/src/weather/apis/korea/server.ts

@@ -15,12 +15,9 @@ import WEATHER_KOREA_RESPONSE from "../../data/response";
 import { getWeatherBaseMoments } from "../../utils/date-time";
 import { extractWeatherSummary } from "../../utils";
 import type { NextResponse } from "next/server";
-import {
-  generateBackendQueryUrl_GET,
-  nextAPILog,
-} from "@uniai-fe/util-functions";
+import { generateQueryUrl, nextAPILog } from "@uniai-fe/util-api";
 
-// const { generateBackendQueryUrl_GET } = weatherApi;
+// const { generateQueryUrl } = weatherApi;
 // const weatherLog = weatherApi.logger;
 
 /**
@@ -106,7 +103,7 @@ export const routeWeatherKoreaNow = async ({
   );
 
   // 요청 URL 구성
-  const url = generateBackendQueryUrl_GET({
+  const url = generateQueryUrl({
     domain,
     routeUrl,
     queryUrl: QUERY_URL.now,
@@ -168,7 +165,7 @@ export const routeWeatherKoreaForecast = async ({
   );
 
   // 요청 URL 구성
-  const url = generateBackendQueryUrl_GET({
+  const url = generateQueryUrl({
     domain,
     routeUrl,
     queryUrl: QUERY_URL.forecast,
@@ -234,7 +231,7 @@ export const routeWeatherKoreaAlert = async ({
     // fe: "f",
     // tm: "",
   });
-  const url = generateBackendQueryUrl_GET({
+  const url = generateQueryUrl({
     domain,
     routeUrl,
     queryUrl: QUERY_URL.alert,

package/src/weather/apis/open-weather-map/client.ts

@@ -1,8 +1,13 @@
 "use client";
 
 import { useQuery, type UseQueryResult } from "@tanstack/react-query";
-import type { OWM_Res_Weather_Now, WeatherGeoCoordinate } from "../../types";
-import { getQueryString, isValidNumber } from "@uniai-fe/util-functions";
+import type {
+  OWM_Res_Weather_Forecast,
+  OWM_Res_Weather_Now,
+  WeatherGeoCoordinate,
+} from "../../types";
+import { getQueryString } from "@uniai-fe/util-api";
+import { isValidNumber } from "@uniai-fe/util-functions";
 
 /**
  * 글로벌 날씨 API; 현재 날씨 fetch
@@ -15,7 +20,7 @@ import { getQueryString, isValidNumber } from "@uniai-fe/util-functions";
  */
 export const getWeatherOpenWeatherMapNow = async (
   params: WeatherGeoCoordinate,
-) =>
+): Promise<OWM_Res_Weather_Now> =>
   await (
     await fetch(`/api/weather/open-weather-map/now${getQueryString(params)}`)
   ).json();
@@ -31,7 +36,7 @@ export const getWeatherOpenWeatherMapNow = async (
  */
 export const getWeatherOpenWeatherMapForecast = async (
   params: WeatherGeoCoordinate,
-) =>
+): Promise<OWM_Res_Weather_Forecast> =>
   await (
     await fetch(
       `/api/weather/open-weather-map/forecast${getQueryString(params)}`,
@@ -60,7 +65,7 @@ export const useQueryWeatherOpenWeatherMapNow = (
  */
 export const useQueryWeatherOpenWeatherMapForecast = (
   params: WeatherGeoCoordinate,
-) =>
+): UseQueryResult<OWM_Res_Weather_Forecast> =>
   useQuery({
     queryKey: ["weather_open_weather_map_forecast", ...Object.values(params)],
     queryFn: () => getWeatherOpenWeatherMapForecast(params),

package/src/weather/apis/open-weather-map/server.ts

@@ -1,9 +1,10 @@
 "use server";
 
-import {
-  generateBackendQueryUrl_GET,
-  nextAPILog,
-} from "@uniai-fe/util-functions";
+import { generateQueryUrl, nextAPILog } from "@uniai-fe/util-api";
+import type {
+  OWM_Res_Weather_Forecast,
+  OWM_Res_Weather_Now,
+} from "../../types";
 
 /**
  * 글로벌 날씨 API; 현재 날씨 URL
@@ -32,8 +33,8 @@ export const routeOpenWeatherMapNow = async ({
   authKey: string;
   routeUrl: string;
   searchParams: URLSearchParams;
-}): Promise<object> => {
-  const resDefault = {};
+}): Promise<OWM_Res_Weather_Now | Record<string, never>> => {
+  const resDefault: Record<string, never> = {};
 
   if (!authKey) {
     nextAPILog("GET", routeUrl, "Open Weather Map 현재날씨 API", {
@@ -54,7 +55,7 @@ export const routeOpenWeatherMapNow = async ({
     return {};
   }
 
-  const url = generateBackendQueryUrl_GET({
+  const url = generateQueryUrl({
     domain: API_BASE_CURRENT,
     routeUrl,
     queryUrl: "",
@@ -88,8 +89,8 @@ export const routeOpenWeatherMapForecast = async ({
   authKey: string;
   routeUrl: string;
   searchParams: URLSearchParams;
-}): Promise<object> => {
-  const resDefault = {};
+}): Promise<OWM_Res_Weather_Forecast | Record<string, never>> => {
+  const resDefault: Record<string, never> = {};
 
   if (!authKey) {
     nextAPILog("GET", routeUrl, "Open Weather Map 예보날씨 API", {
@@ -110,7 +111,7 @@ export const routeOpenWeatherMapForecast = async ({
     return {};
   }
 
-  const url = generateBackendQueryUrl_GET({
+  const url = generateQueryUrl({
     domain: API_BASE_FORECAST,
     routeUrl,
     queryUrl: "",

package/src/weather/components/index.tsx

@@ -1,10 +1,11 @@
-import WeatherPageHeaderContainer from "./page-header/Container";
+import { WeatherPageHeader } from "./page-header";
 
 /**
  * Weather Components; weather component namespace 집계
  */
 const Weather = {
-  PageHeader: WeatherPageHeaderContainer,
+  PageHeader: WeatherPageHeader,
 };
 
 export default Weather;
+export { WeatherPageHeader };

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

@@ -0,0 +1,25 @@
+import WeatherPageHeaderAddress from "./Address";
+import WeatherPageHeaderAlert from "./Alert";
+import WeatherPageHeaderContainer from "./Container";
+import WeatherPageHeaderForecast from "./Forecast";
+import WeatherPageHeaderNextDays from "./NextDays";
+import WeatherPageHeaderToday from "./Today";
+
+// 기존 Container 호출 계약을 유지하면서, 서비스 재조합용 하위 조각 접근도 함께 연다.
+export const WeatherPageHeader = Object.assign(WeatherPageHeaderContainer, {
+  Container: WeatherPageHeaderContainer,
+  Address: WeatherPageHeaderAddress,
+  Today: WeatherPageHeaderToday,
+  Forecast: WeatherPageHeaderForecast,
+  Alert: WeatherPageHeaderAlert,
+  NextDays: WeatherPageHeaderNextDays,
+});
+
+export {
+  WeatherPageHeaderContainer,
+  WeatherPageHeaderAddress,
+  WeatherPageHeaderToday,
+  WeatherPageHeaderForecast,
+  WeatherPageHeaderAlert,
+  WeatherPageHeaderNextDays,
+};

package/src/weather/hooks/useOpenWeatherMap.ts

@@ -6,31 +6,14 @@ import {
   useQueryWeatherOpenWeatherMapForecast,
   useQueryWeatherOpenWeatherMapNow,
 } from "../apis/open-weather-map/client";
-import { useWeatherMock } from "../context/mock";
 
 export default function useOpenWeatherMap() {
-  const mock = useWeatherMock();
   const coordinate = useAtomValue(weatherCoordinate);
-  const shouldUseMock = Boolean(mock?.openWeather);
-  // mock 모드일 때는 Query가 실행되지 않도록 NaN 좌표를 전달한다.
-  const queryCoordinate = shouldUseMock
-    ? { lat: Number.NaN, lng: Number.NaN }
-    : coordinate;
 
   const { data: now, isFetching: isFetchingNow } =
-    useQueryWeatherOpenWeatherMapNow(queryCoordinate);
+    useQueryWeatherOpenWeatherMapNow(coordinate);
   const { data: forecast, isFetching: isFetchingForecast } =
-    useQueryWeatherOpenWeatherMapForecast(queryCoordinate);
-
-  if (mock?.openWeather) {
-    return {
-      coordinate: mock.openWeather.coordinate,
-      now: mock.openWeather.now,
-      forecast: mock.openWeather.forecast,
-      isFetchingNow: mock.openWeather.isFetchingNow ?? false,
-      isFetchingForecast: mock.openWeather.isFetchingForecast ?? false,
-    };
-  }
+    useQueryWeatherOpenWeatherMapForecast(coordinate);
 
   return {
     coordinate,

package/src/weather/hooks/useWeatherKorea.ts

@@ -10,10 +10,8 @@ import type { API_Req_WeatherKorea } from "../types";
 import { weatherCoordinate } from "../jotai/coordinate";
 import { getWeatherBaseMoments } from "../utils/date-time";
 import { getWeatherGridLocation } from "../utils/location";
-import { useWeatherMock } from "../context/mock";
 
 export default function useWeatherKorea() {
-  const mock = useWeatherMock();
   const coordinate = useAtomValue(weatherCoordinate);
   const [params, setParams] = useState<{
     [categoryKey: string]: API_Req_WeatherKorea;
@@ -23,9 +21,18 @@ export default function useWeatherKorea() {
   });
 
   useEffect(() => {
-    if (mock?.korea) return;
     if (typeof window === "undefined") return;
 
+    const hasInjectedCoordinate =
+      typeof coordinate.address === "string" ||
+      coordinate.lat !== null ||
+      coordinate.lng !== null;
+
+    if (!hasInjectedCoordinate) {
+      // 변경 설명: 초기 mount에서 coordinate 주입 전에는 geolocation/web API 준비를 시도하지 않는다.
+      return;
+    }
+
     const nowMoments = getWeatherBaseMoments("now");
     const forecastMoments = getWeatherBaseMoments("forecast");
 
@@ -44,7 +51,7 @@ export default function useWeatherKorea() {
     }
 
     updater();
-  }, [coordinate, mock]);
+  }, [coordinate]);
 
   const { data: now, isFetching: isFetchingNow } = useQueryWeatherKoreaNow(
     params.now,
@@ -53,20 +60,6 @@ export default function useWeatherKorea() {
   const { data: forecast, isFetching: isFetchingForecast } =
     useQueryWeatherKoreaForecast(params.forecast);
 
-  if (mock?.korea) {
-    return {
-      params: {
-        now: { nx: 0, ny: 0 },
-        forecast: { nx: 0, ny: 0 },
-      },
-      coordinate: mock.korea.coordinate,
-      now: mock.korea.now,
-      forecast: mock.korea.forecast,
-      isFetchingNow: mock.korea.isFetchingNow ?? false,
-      isFetchingForecast: mock.korea.isFetchingForecast ?? false,
-    };
-  }
-
   return {
     params,
     coordinate,

package/src/weather/hooks/useWeatherKoreaAlert.ts

@@ -4,32 +4,19 @@ import { useMemo } from "react";
 import { useAtomValue } from "jotai";
 import { useQueryWeatherKoreaAlert } from "../apis/korea/client"; // server 번들을 피하기 위해 client 모듈에서 직접 import한다.
 import { weatherFarmIdx } from "../jotai/farm-idx";
-import { useWeatherMock } from "../context/mock";
 
 export default function useWeatherKoreaAlert() {
-  const mock = useWeatherMock();
   const farm_idx = useAtomValue(weatherFarmIdx);
-  const shouldUseMock = Boolean(mock?.koreaAlert);
-  const resolvedFarmIdx = farm_idx === 507 || !farm_idx ? 507 : (farm_idx ?? 0);
-  const queryFarmIdx = shouldUseMock ? 0 : resolvedFarmIdx;
 
+  // 특보 조회 식별자는 템플릿이 보정하지 않고, 서비스가 주입한 값만 그대로 사용한다.
   const { data, isFetching } = useQueryWeatherKoreaAlert({
-    farm_idx: queryFarmIdx,
+    farm_idx,
   });
 
   const alert = useMemo(() => data?.alerts || [], [data]);
 
-  if (mock?.koreaAlert) {
-    // WeatherMockProvider를 사용하면 네트워크 호출 없이 스토리/테스트 전용 alert 데이터를 주입할 수 있다.
-    return {
-      farm_idx: null,
-      alert: mock.koreaAlert.alert?.alerts ?? [],
-      isFetching: mock.koreaAlert.isFetching ?? false,
-    };
-  }
-
   return {
-    farm_idx: resolvedFarmIdx,
+    farm_idx,
     alert,
     isFetching,
   };

package/src/weather/index.tsx

@@ -2,13 +2,20 @@
 import "./index.scss";
 
 /**
- * Weather; page-header 템플릿과 api/hook/jotai/mock 도구를 함께 제공하는 엔트리
+ * Weather; page-header 템플릿과 api/hook/jotai 도구를 함께 제공하는 엔트리
  */
 export * from "./utils";
 export * from "./apis";
 export * from "./jotai";
 export * from "./hooks";
-export * from "./context/mock";
 export * from "./types";
 export { default as WeatherComponents } from "./components";
+export { WeatherPageHeader } from "./components";
 export { default as WeatherPageHeaderContainer } from "./components/page-header/Container";
+export {
+  WeatherPageHeaderAddress,
+  WeatherPageHeaderAlert,
+  WeatherPageHeaderForecast,
+  WeatherPageHeaderNextDays,
+  WeatherPageHeaderToday,
+} from "./components/page-header";

package/src/weather/jotai/coordinate.ts

@@ -8,9 +8,3 @@ export const weatherCoordinate = atomWithReset<WeatherCoordinate>({
   lat: null,
   lng: null,
 });
-
-export const harimCoordinate: WeatherCoordinate = {
-  address: "전북 익산시",
-  lat: 35.9372719,
-  lng: 126.9601241,
-};

package/src/weather/types/open-weather-map.ts

@@ -69,9 +69,9 @@ export type OWM_Res_Weather_Degrees = {
   /** * 습도 (%) */
   humidity: number;
   /** * 해면기압 (hPa) */
-  sea_level: number;
+  sea_level?: number;
   /** * 현지기압 (hPa) */
-  grnd_level: number;
+  grnd_level?: number;
 };
 
 /**
@@ -92,7 +92,7 @@ export type OWM_Res_Wind = {
    */
   deg: number;
   /** * 돌풍 (m/s) */
-  gust: number;
+  gust?: number;
 };
 
 /**
@@ -116,6 +116,47 @@ export type OWM_Res_Sun = {
   sunset: number; // 일몰 timestamp 1748342383;
 };
 
+/**
+ * OpenWeatherMap 도시 정보.
+ * @property {number} id 도시 식별자
+ * @property {string} name 도시 이름
+ * @property {OWM_Res_Coord} coord 도시 좌표
+ * @property {string} country 국가 코드
+ * @property {number} timezone UTC 오프셋(sec)
+ * @property {number} sunrise 일출 시각 timestamp
+ * @property {number} sunset 일몰 시각 timestamp
+ */
+export type OWM_Res_City = {
+  /** 도시 식별자 */
+  id: number;
+  /** 도시 이름 */
+  name: string;
+  /** 도시 좌표 */
+  coord: OWM_Res_Coord;
+  /** 국가 코드 */
+  country: string;
+  /** UTC 오프셋(sec) */
+  timezone: number;
+  /** 일출 시각 timestamp */
+  sunrise: number;
+  /** 일몰 시각 timestamp */
+  sunset: number;
+  /** 도시 인구 */
+  population?: number;
+};
+
+/**
+ * OpenWeatherMap 강수량 정보.
+ * @property {number} ["1h"] 1시간 강수량(mm)
+ * @property {number} ["3h"] 3시간 강수량(mm)
+ */
+export type OWM_Res_Precipitation = {
+  /** 1시간 강수량(mm) */
+  "1h"?: number;
+  /** 3시간 강수량(mm) */
+  "3h"?: number;
+};
+
 /**
  * OpenWeatherMap API 응답; 현재 날씨
  * @see https://openweathermap.org/current
@@ -155,10 +196,71 @@ export type OWM_Res_Weather_Now = {
    * @deprecated
    */
   /** 도시 이름 */
-  name: number;
+  name: string;
   /**
    * API 응답 정보
    */
   /** API 응답 코드 */
   cod: number;
 };
+
+/**
+ * OpenWeatherMap API 응답; 예보 항목
+ * @property {number} dt 데이터 연산 시각 timestamp
+ * @property {OWM_Res_Weather_Degrees} main 측정 정보
+ * @property {OWM_Res_Condition[]} weather 개황 정보
+ * @property {OWM_Res_Clouds} clouds 구름량 정보
+ * @property {OWM_Res_Wind} wind 바람 정보
+ * @property {number} visibility 시정거리(m)
+ * @property {number} pop 강수 확률(0~1)
+ * @property {{ pod: string }} sys 낮/밤 구분
+ * @property {string} dt_txt 예보 시각 문자열
+ * @property {OWM_Res_Precipitation} [rain] 강수량 정보
+ * @property {OWM_Res_Precipitation} [snow] 적설량 정보
+ */
+export type OWM_Res_Weather_Forecast_Item = {
+  /** 데이터 연산 시각 timestamp */
+  dt: number;
+  /** 측정 정보 */
+  main: OWM_Res_Weather_Degrees;
+  /** 개황 정보 */
+  weather: OWM_Res_Condition[];
+  /** 구름량 정보 */
+  clouds: OWM_Res_Clouds;
+  /** 바람 정보 */
+  wind: OWM_Res_Wind;
+  /** 시정거리(m) */
+  visibility: number;
+  /** 강수 확률(0~1) */
+  pop: number;
+  /** 낮/밤 구분 */
+  sys: { pod: string };
+  /** 예보 시각 문자열 */
+  dt_txt: string;
+  /** 강수량 정보 */
+  rain?: OWM_Res_Precipitation;
+  /** 적설량 정보 */
+  snow?: OWM_Res_Precipitation;
+};
+
+/**
+ * OpenWeatherMap API 응답; 예보 날씨
+ * @see https://openweathermap.org/forecast5
+ * @property {string} cod API 응답 코드
+ * @property {number} message 내부 메시지/계산값
+ * @property {number} cnt 예보 개수
+ * @property {OWM_Res_Weather_Forecast_Item[]} list 예보 목록
+ * @property {OWM_Res_City} city 도시 정보
+ */
+export type OWM_Res_Weather_Forecast = {
+  /** API 응답 코드 */
+  cod: string;
+  /** 내부 메시지/계산값 */
+  message: number;
+  /** 예보 개수 */
+  cnt: number;
+  /** 예보 목록 */
+  list: OWM_Res_Weather_Forecast_Item[];
+  /** 도시 정보 */
+  city: OWM_Res_City;
+};

package/src/weather/utils/location.ts

@@ -120,12 +120,15 @@ export async function getWeatherGridLocation(
     latitude: coordinate?.lat ?? null,
     longitude: coordinate?.lng ?? null,
   };
+  const hasInjectedAddress =
+    typeof coordinate?.address === "string" && coordinate.address.trim() !== "";
 
   // console.log("[getWeatherLocation] 특정 좌표지정 확인", coordinate);
 
-  // 특정 위경도 좌표를 받지 못하는 경우, 현재 사용자 위치로 지정
+  // 변경 설명: 서비스가 address만 명시적으로 주입한 경우에는 geolocation fallback을 재시도하지 않는다.
   if (
     typeof window !== "undefined" &&
+    !hasInjectedAddress &&
     (typeof coordinate === "undefined" ||
       geo.latitude === null ||
       geo.longitude === null)

package/src/weather/context/mock.tsx

@@ -1,45 +0,0 @@
-"use client";
-
-import { createContext, useContext } from "react";
-import type {
-  API_Res_WeatherKoreaAlert,
-  API_Res_WeatherKoreaForecast,
-  API_Res_WeatherKoreaNow,
-  WeatherCoordinate,
-} from "../types";
-
-type WeatherKoreaMock = {
-  now?: API_Res_WeatherKoreaNow;
-  forecast?: API_Res_WeatherKoreaForecast;
-  coordinate?: WeatherCoordinate;
-  isFetchingNow?: boolean;
-  isFetchingForecast?: boolean;
-};
-
-type OpenWeatherMock = {
-  now?: {
-    weather?: Array<{ icon?: string; description?: string }>;
-    main?: { temp?: number | null; humidity?: number | null };
-  };
-  forecast?: unknown;
-  coordinate?: WeatherCoordinate;
-  isFetchingNow?: boolean;
-  isFetchingForecast?: boolean;
-};
-
-type WeatherKoreaAlertMock = {
-  alert?: API_Res_WeatherKoreaAlert;
-  isFetching?: boolean;
-};
-
-export type WeatherMockValue = {
-  korea?: WeatherKoreaMock;
-  koreaAlert?: WeatherKoreaAlertMock;
-  openWeather?: OpenWeatherMock;
-};
-
-const WeatherMockContext = createContext<WeatherMockValue | null>(null);
-
-export const WeatherMockProvider = WeatherMockContext.Provider;
-
-export const useWeatherMock = () => useContext(WeatherMockContext);