@uniai-fe/uds-templates 0.4.7 → 0.4.9

package/README.md

@@ -107,7 +107,7 @@ Next.js 서비스에서 primitives와 동일한 방식으로 **Raw TypeScript**
   - ui-legacy 스택 기반 모달 Provider/Root/Container + 템플릿(`Modal.Alert`, `Modal.Dialog`)
   - Storybook(`apps/design-storybook/src/stories/templates/modal`)에서 Alert/Confirm 케이스를 검증한다.
 - `/service-inquiry/**`
-  - 문의 입력 전용 form, 기본 원형 `?` open button, 커스텀 trigger용 open hook, 페이지 context 등록 hook, request context 조립 hook, modal preset factory를 제공한다.
+  - 문의 입력 전용 form, 기본 원형 `?` open button, 커스텀 trigger용 open hook, 페이지 context 등록 hook, request context 조립 hook, 네트워크 오류 수집 hook, modal preset factory를 제공한다.
   - submit transport, React Query mutation, Next.js route handler, 에러 피드백(`Modal.Alert`)은 서비스 앱이 소유한다.
   - 모듈 내부 Jotai registry를 사용하므로, layout 고정 버튼 1개와 페이지별 context 등록 hook 조합으로 ready-to-use 구성이 가능하다.
   - 로그인 후 `farm_name`, `contact`를 auto-fill + readonly로 보여야 할 때는 `formContextOptions.defaultValues`와 `farmNameField.mode`, `contactField.mode`를 함께 전달한다.
@@ -124,10 +124,11 @@ Next.js 서비스에서 primitives와 동일한 방식으로 **Raw TypeScript**
 
 1. 서비스 앱이 `react-hook-form`으로 `defaultValues`와 `onSubmit`을 준비한다.
 2. layout 고정 버튼은 `ServiceInquiry.useUserContext()`로 모듈 내부 registry 기반 `requestContext`를 읽는다.
-3. 각 페이지/폼은 `ServiceInquiry.useProvideContext({ labels, userContext })`로 `ServiceInquiryProvidedContext`를 등록한다.
-4. 기본 버튼은 `ServiceInquiry.OpenButton`, 커스텀 버튼은 `ServiceInquiry.useOpen`으로 모달 open을 연결한다.
-5. modal footer confirm이 `ServiceInquiry.Form` submit 진입을 담당한다.
-6. 실제 submit은 서비스 앱의 `useMutation + Next.js route handler + Modal.Alert` 조합으로 처리한다.
+3. 서비스 앱은 네트워크 오류가 발생했을 때 `ServiceInquiry.useNetworkError().reportNetworkError(...)`만 호출하고, 모듈이 이를 `user_context.network_errors`에 자동 병합한다.
+4. 각 페이지/폼은 `ServiceInquiry.useProvideContext({ labels, userContext })`로 `ServiceInquiryProvidedContext`를 등록한다.
+5. 기본 버튼은 `ServiceInquiry.OpenButton`, 커스텀 버튼은 `ServiceInquiry.useOpen`으로 모달 open을 연결한다.
+6. modal footer confirm이 `ServiceInquiry.Form` submit 진입을 담당한다.
+7. 실제 submit은 서비스 앱의 `useMutation + Next.js route handler + Modal.Alert` 조합으로 처리한다.
 
 `service-inquiry`는 구조와 request context까지만 제공하고, 네트워크 상태/재시도/성공·실패 피드백은 서비스 앱이 소유합니다.
 

package/dist/styles.css

@@ -1764,5 +1764,5 @@
   left: var(--service-inquiry-button-pos-left);
   right: var(--service-inquiry-button-pos-right);
   bottom: var(--service-inquiry-button-pos-bottom);
-  z-index: 100;
+  z-index: 700;
 }

package/package.json

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

package/src/service-inquiry/components/OpenButton.tsx

@@ -2,12 +2,14 @@
 
 import { Button } from "@uniai-fe/uds-primitives";
 import { useOpenServiceInquiry } from "../hooks";
-import type { UseOpenServiceInquiryOptions } from "../types";
+import type { ServiceInquiryOpenButtonProps } from "../types";
+import clsx from "clsx";
 
 /**
  * Service Inquiry Open Button; 문의 모달 trigger adapter
  * @component
  * @param {UseOpenServiceInquiryOptions} props 문의 모달 열기 props
+ * @param {string} [props.className]
  * @param {string} props.stackKey modal stack key
  * @param {ServiceInquiryFormProps} props.formProps 문의 form props
  * @param {Partial<DialogTemplateOptions<ServiceInquiryFormValues>>} [props.dialogOptions] 문의 모달 preset 위에 덮어쓸 dialog option
@@ -19,11 +21,12 @@ import type { UseOpenServiceInquiryOptions } from "../types";
  * />
  */
 const ServiceInquiryOpenButton = ({
+  className,
   stackKey,
   formProps,
   dialogOptions,
   onOpen,
-}: UseOpenServiceInquiryOptions) => {
+}: ServiceInquiryOpenButtonProps) => {
   const { openServiceInquiry } = useOpenServiceInquiry({
     stackKey,
     formProps,
@@ -33,7 +36,7 @@ const ServiceInquiryOpenButton = ({
 
   return (
     <Button.Rounded
-      className="service-inquiry-open-button"
+      className={clsx("service-inquiry-open-button", className)}
       priority="tertiary"
       size="large"
       // 변경 설명: 기본 제공 버튼은 고정 원형 `?` 버튼 사양으로 렌더링한다.

package/src/service-inquiry/hooks/index.ts

@@ -1,3 +1,4 @@
 export * from "./useOpen";
+export * from "./useNetworkError";
 export * from "./useProvideContext";
 export * from "./useUserContext";

package/src/service-inquiry/hooks/useNetworkError.ts

@@ -0,0 +1,46 @@
+"use client";
+
+import { useAtom } from "jotai";
+import { serviceInquiryNetworkErrorsAtom } from "../jotai";
+import type {
+  ServiceInquiryNetworkError,
+  UseServiceInquiryNetworkErrorReturn,
+} from "../types";
+
+/**
+ * Service Inquiry Hook; 네트워크 오류 수집 Hook
+ * @hook
+ * @returns {UseServiceInquiryNetworkErrorReturn} 최근 오류 목록과 기록/초기화 함수
+ * @example
+ * const { reportNetworkError } = useServiceInquiryNetworkError();
+ * reportNetworkError({ route: "/api/v2/login", message: "timeout" });
+ */
+export function useServiceInquiryNetworkError(): UseServiceInquiryNetworkErrorReturn {
+  const [networkErrors, setNetworkErrors] = useAtom(
+    serviceInquiryNetworkErrorsAtom,
+  );
+
+  const reportNetworkError: UseServiceInquiryNetworkErrorReturn["reportNetworkError"] =
+    (nextError: ServiceInquiryNetworkError) => {
+      setNetworkErrors(currentErrors =>
+        [
+          {
+            ...nextError,
+            timestamp: nextError.timestamp ?? new Date().toISOString(),
+          },
+          ...currentErrors,
+        ].slice(0, 5),
+      );
+    };
+
+  const clearNetworkErrors: UseServiceInquiryNetworkErrorReturn["clearNetworkErrors"] =
+    () => {
+      setNetworkErrors([]);
+    };
+
+  return {
+    networkErrors,
+    reportNetworkError,
+    clearNetworkErrors,
+  };
+}

package/src/service-inquiry/index.tsx

@@ -2,11 +2,16 @@ import "./index.scss";
 import ServiceInquiryForm from "./components/Form";
 import ServiceInquiryOpenButton from "./components/OpenButton";
 import {
+  useServiceInquiryNetworkError,
   useOpenServiceInquiry,
   useProvideServiceInquiryContext,
   useServiceInquiryUserContext,
 } from "./hooks";
 import { createServiceInquiryModal } from "./utils/modal-option";
+import {
+  getServiceInquiryDebugHeaders,
+  parseResponseWithServiceInquiryDebug,
+} from "./utils/network-debug";
 
 /**
  * Service Inquiry; 문의 form + modal option 엔트리
@@ -16,17 +21,23 @@ export const ServiceInquiry = {
   Form: ServiceInquiryForm,
   OpenButton: ServiceInquiryOpenButton,
   useOpen: useOpenServiceInquiry,
+  useNetworkError: useServiceInquiryNetworkError,
   useProvideContext: useProvideServiceInquiryContext,
   useUserContext: useServiceInquiryUserContext,
   createModal: createServiceInquiryModal,
+  getNetworkDebugHeaders: getServiceInquiryDebugHeaders,
+  parseResponseDebug: parseResponseWithServiceInquiryDebug,
 };
 
 export {
   ServiceInquiryForm,
   ServiceInquiryOpenButton,
+  useServiceInquiryNetworkError,
   useOpenServiceInquiry,
   useProvideServiceInquiryContext,
   useServiceInquiryUserContext,
   createServiceInquiryModal,
+  getServiceInquiryDebugHeaders,
+  parseResponseWithServiceInquiryDebug,
 };
 export type * from "./types";

package/src/service-inquiry/jotai/context.ts

@@ -2,6 +2,7 @@
 
 import { atom } from "jotai";
 import type {
+  ServiceInquiryNetworkError,
   ServiceInquiryRequestContext,
   ServiceInquiryProvidedContext,
   ServiceInquiryUserContext,
@@ -22,6 +23,14 @@ export const serviceInquiryProvidedContextRegistryAtom = atom<
 export const serviceInquiryAdditionalUserContextAtom =
   atom<ServiceInquiryUserContext | null>(null);
 
+/**
+ * Service Inquiry State; 최근 네트워크 오류 목록
+ * @state
+ */
+export const serviceInquiryNetworkErrorsAtom = atom<
+  ServiceInquiryNetworkError[]
+>([]);
+
 /**
  * Service Inquiry State; registry 병합 context
  * @state
@@ -64,16 +73,22 @@ export const serviceInquiryRequestContextAtom =
   atom<ServiceInquiryRequestContext>(get => {
     const providedContext = get(serviceInquiryProvidedContextAtom);
     const additionalUserContext = get(serviceInquiryAdditionalUserContextAtom);
+    const networkErrors = get(serviceInquiryNetworkErrorsAtom);
 
     return {
       labels: providedContext.labels ?? [],
       // 변경 설명: page_path는 서비스 입력값이 아니라 모듈이 현재 페이지 URL 전체를 자동 수집하는 시스템 필드로 고정한다.
       page_path: typeof window === "undefined" ? "" : window.location.href,
       user_context:
-        providedContext.userContext || additionalUserContext
+        providedContext.userContext ||
+        additionalUserContext ||
+        networkErrors.length > 0
           ? {
               ...(providedContext.userContext ?? {}),
               ...(additionalUserContext ?? {}),
+              ...(networkErrors.length > 0
+                ? { network_errors: networkErrors }
+                : {}),
             }
           : null,
     };

package/src/service-inquiry/styles/open-button.scss

@@ -7,5 +7,5 @@
   left: var(--service-inquiry-button-pos-left);
   right: var(--service-inquiry-button-pos-right);
   bottom: var(--service-inquiry-button-pos-bottom);
-  z-index: 100;
+  z-index: 700;
 }

package/src/service-inquiry/types/hooks.ts

@@ -19,6 +19,94 @@ export interface ServiceInquiryProvidedContext {
   userContext?: ServiceInquiryUserContext | null;
 }
 
+/**
+ * Service Inquiry Hook; 네트워크 오류 헤더 요약
+ * @property {string} [uniai_native_domain] 응답 헤더 `Uniai-Native-Domain`
+ * @property {string} [uniai_native_path] 응답 헤더 `Uniai-Native-Path`
+ * @property {string} [uniai_native_url] 응답 헤더 `Uniai-Native-URL`
+ * @property {string} [content_type] 응답 헤더 `content-type`
+ * @property {boolean} [has_authorization] 요청 헤더에 Authorization 존재 여부
+ */
+export interface ServiceInquiryNetworkErrorHeaders {
+  /**
+   * 응답 헤더 `Uniai-Native-Domain`
+   */
+  uniai_native_domain?: string;
+  /**
+   * 응답 헤더 `Uniai-Native-Path`
+   */
+  uniai_native_path?: string;
+  /**
+   * 응답 헤더 `Uniai-Native-URL`
+   */
+  uniai_native_url?: string;
+  /**
+   * 응답 헤더 `content-type`
+   */
+  content_type?: string;
+  /**
+   * 요청 헤더에 Authorization 존재 여부
+   */
+  has_authorization?: boolean;
+}
+
+/**
+ * Service Inquiry Hook; 네트워크 오류 기록
+ * @property {string} [route] 요청 route 또는 endpoint
+ * @property {number} [code] HTTP status code
+ * @property {string} [state] 서비스 레이어 상태 문자열
+ * @property {string} [message] 사용자/운영 확인용 오류 메시지
+ * @property {ServiceInquiryNetworkErrorHeaders} [headers] 선택 수집된 request/response 헤더 정보
+ * @property {string} [timestamp] 오류 기록 시각
+ */
+export interface ServiceInquiryNetworkError {
+  /**
+   * 요청 route 또는 endpoint
+   */
+  route?: string;
+  /**
+   * HTTP status code
+   */
+  code?: number;
+  /**
+   * 서비스 레이어 상태 문자열
+   */
+  state?: string;
+  /**
+   * 사용자/운영 확인용 오류 메시지
+   */
+  message?: string;
+  /**
+   * 선택 수집된 request/response 헤더 정보
+   */
+  headers?: ServiceInquiryNetworkErrorHeaders;
+  /**
+   * 오류 기록 시각
+   */
+  timestamp?: string;
+}
+
+/**
+ * Service Inquiry Hook; 네트워크 오류 수집 훅 반환값
+ * @property {ServiceInquiryNetworkError[]} networkErrors 누적된 최근 네트워크 오류 목록
+ * @property {(nextError: ServiceInquiryNetworkError) => void} reportNetworkError 네트워크 오류 1건 기록
+ * @property {() => void} clearNetworkErrors 누적된 네트워크 오류 초기화
+ */
+export interface UseServiceInquiryNetworkErrorReturn {
+  /**
+   * 누적된 최근 네트워크 오류 목록
+   */
+  networkErrors: ServiceInquiryNetworkError[];
+  /**
+   * 네트워크 오류 1건 기록
+   */
+  reportNetworkError: (nextError: ServiceInquiryNetworkError) => void;
+  /**
+   * 누적된 네트워크 오류 초기화
+   */
+  clearNetworkErrors: () => void;
+}
+
 /**
  * Service Inquiry Hook; user_context 훅 반환값
  * @property {ServiceInquiryRequestContext} requestContext form submit에 바로 사용할 request context

package/src/service-inquiry/types/props.ts

@@ -134,6 +134,18 @@ export interface UseOpenServiceInquiryOptions extends ServiceInquiryCreateModalO
   onOpen?: () => void;
 }
 
+/**
+ * Service Inquiry Button props; 버튼 옵션
+ * @property {string} [className]
+ * @property {string} stackKey modal stack key
+ * @property {ServiceInquiryFormProps} formProps 문의 form props
+ * @property {Partial<DialogTemplateOptions<ServiceInquiryFormValues>>} [dialogOptions] 문의 모달 preset 위에 덮어쓸 dialog option
+ * @property {() => void} [onOpen] 모달 open 직전 콜백
+ */
+export interface ServiceInquiryOpenButtonProps extends UseOpenServiceInquiryOptions {
+  className?: string;
+}
+
 /**
  * Service Inquiry Hook; 문의 모달 열기 훅 반환값
  * @property {() => void} openServiceInquiry 문의 모달 open 함수

package/src/service-inquiry/utils/network-debug.ts

@@ -0,0 +1,112 @@
+import type { ServiceInquiryNetworkErrorHeaders } from "../types";
+
+/**
+ * Service Inquiry Utility; Authorization 헤더 존재 여부 판별
+ * @param {HeadersInit} [requestHeaders] 요청 헤더
+ * @returns {boolean} Authorization 헤더 존재 여부
+ * @example
+ * const hasAuthorization = resolveServiceInquiryHasAuthorization({
+ *   Authorization: "Bearer token",
+ * });
+ */
+const resolveServiceInquiryHasAuthorization = (
+  requestHeaders?: HeadersInit,
+): boolean => {
+  if (!requestHeaders) {
+    return false;
+  }
+
+  return new Headers(requestHeaders).has("Authorization");
+};
+
+/**
+ * Service Inquiry Utility; 선택 디버그 헤더 추출
+ * @param {Headers} responseHeaders 응답 헤더
+ * @param {HeadersInit} [requestHeaders] 요청 헤더
+ * @returns {ServiceInquiryNetworkErrorHeaders | undefined} service-inquiry에 기록할 최소 헤더 정보
+ * @example
+ * const headers = pickServiceInquiryDebugHeaders(response.headers, {
+ *   Authorization: "Bearer token",
+ * });
+ */
+const pickServiceInquiryDebugHeaders = (
+  responseHeaders: Headers,
+  requestHeaders?: HeadersInit,
+): ServiceInquiryNetworkErrorHeaders | undefined => {
+  const headers: ServiceInquiryNetworkErrorHeaders = {
+    uniai_native_domain:
+      responseHeaders.get("Uniai-Native-Domain") ?? undefined,
+    uniai_native_path: responseHeaders.get("Uniai-Native-Path") ?? undefined,
+    uniai_native_url: responseHeaders.get("Uniai-Native-URL") ?? undefined,
+    content_type: responseHeaders.get("content-type") ?? undefined,
+    has_authorization: resolveServiceInquiryHasAuthorization(requestHeaders),
+  };
+
+  if (
+    !headers.uniai_native_domain &&
+    !headers.uniai_native_path &&
+    !headers.uniai_native_url &&
+    !headers.content_type &&
+    !headers.has_authorization
+  ) {
+    return undefined;
+  }
+
+  return headers;
+};
+
+/**
+ * Service Inquiry Utility; 응답 payload에 디버그 헤더 주입
+ * @param {Response} response fetch 응답 객체
+ * @param {HeadersInit} [requestHeaders] 요청 헤더
+ * @returns {Promise<ResponseData>} 선택 디버그 헤더가 포함된 응답 payload
+ * @example
+ * const payload = await parseResponseWithServiceInquiryDebug(response, {
+ *   Authorization: "Bearer token",
+ * });
+ */
+export async function parseResponseWithServiceInquiryDebug<
+  ResponseData extends object,
+>(response: Response, requestHeaders?: HeadersInit): Promise<ResponseData> {
+  const payload = (await response.json()) as ResponseData;
+  const headers = pickServiceInquiryDebugHeaders(
+    response.headers,
+    requestHeaders,
+  );
+
+  if (!headers) {
+    return payload;
+  }
+
+  // 변경 설명: service-inquiry 네트워크 기록에 필요한 최소 header 정보만 응답 payload에 숨겨서 전달한다.
+  return Object.assign(payload, {
+    _service_inquiry_debug: {
+      headers,
+    },
+  });
+}
+
+/**
+ * Service Inquiry Utility; 응답 payload에서 디버그 헤더 읽기
+ * @param {unknown} response service 응답 payload
+ * @returns {ServiceInquiryNetworkErrorHeaders | undefined} 숨겨서 실은 디버그 헤더
+ * @example
+ * const headers = getServiceInquiryDebugHeaders(response);
+ */
+export function getServiceInquiryDebugHeaders(
+  response: unknown,
+): ServiceInquiryNetworkErrorHeaders | undefined {
+  if (!response || typeof response !== "object") {
+    return undefined;
+  }
+
+  const debugData = (
+    response as {
+      _service_inquiry_debug?: {
+        headers?: ServiceInquiryNetworkErrorHeaders;
+      };
+    }
+  )._service_inquiry_debug;
+
+  return debugData?.headers;
+}