@uniai-fe/uds-templates 0.5.15 → 0.5.17

package/README.md

@@ -156,6 +156,7 @@ Next.js 서비스에서 primitives와 동일한 방식으로 **Raw TypeScript**
 5. 비로그인 기본 버튼은 `ServiceInquiry.OpenButton`, 로그인 후 page-frame 진입 버튼은 `ServiceInquiry.NavButton`, 그 외 커스텀 버튼은 `ServiceInquiry.useOpen`으로 모달 open을 연결한다.
 6. modal footer confirm이 `ServiceInquiry.Form` submit 진입을 담당한다.
 7. 실제 submit은 서비스 앱의 `useMutation + Next.js route handler + Modal.Alert` 조합으로 처리한다.
+8. 표시 문구는 field별 `label`/`placeholder`/`helper`/`requiredMessage`, `inquiryTypeField.options`, `dialogOptions`, `NavButton.label`, `OpenButton.ariaLabel`로 필요한 항목만 주입한다.
 
 `service-inquiry`는 구조와 request context까지만 제공하고, 네트워크 상태/재시도/성공·실패 피드백은 서비스 앱이 소유합니다.
 

package/dist/styles.css

@@ -1962,6 +1962,9 @@
   font-weight: var(--service-inquiry-type-font-weight-default);
   line-height: 1.4;
 }
+.service-inquiry-type-option :where(.chip-label) {
+  line-height: 1.4;
+}
 
 .service-inquiry-type-option:where([data-selected=true]) {
   background-color: var(--service-inquiry-type-bg-selected);

package/package.json

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

package/src/auth/login/markup/Container.tsx

@@ -13,6 +13,7 @@ import type { AuthLoginProps } from "../types";
  * @property {React.ReactNode} [props.footer] 하단 슬롯
  * @property {AuthLoginFieldOptions} props.fieldOptions 입력 필드 옵션
  * @property {AuthLoginLinkOptions} [props.linkOptions] 계정 찾기/회원가입 링크
+ * @property {AuthLoginTexts} [props.texts] 로그인 템플릿 기본 문구 옵션
  * @property {() => void} [props.onFindPasswordLinkClick] 비밀번호 찾기 버튼 클릭 핸들러
  */
 export default function AuthLoginContainer({
@@ -21,6 +22,7 @@ export default function AuthLoginContainer({
   footer,
   linkOptions,
   fieldOptions,
+  texts,
   onFindPasswordLinkClick,
 }: AuthLoginProps) {
   return (
@@ -29,10 +31,14 @@ export default function AuthLoginContainer({
       header={header}
       footer={footer}
     >
-      <AuthLoginFormField {...fieldOptions} />
+      <AuthLoginFormField
+        {...fieldOptions}
+        texts={{ ...texts, ...fieldOptions.texts }}
+      />
       {/* 링크 옵션이 부분적으로만 넘어와도 내부에서 존재하는 항목만 렌더링한다. */}
       <AuthLoginLinkButtons
         linkOptions={linkOptions}
+        texts={texts}
         onFindPasswordClick={onFindPasswordLinkClick}
       />
     </AuthContainer>

package/src/auth/login/markup/FormField.tsx

@@ -14,12 +14,14 @@ import AuthLoginFormFieldPassword from "./Password";
  * @param {AuthLoginFieldOptions} props
  * @property {AuthLoginIdFieldOptions} [props.idField] 아이디 필드 옵션
  * @property {AuthLoginPasswordFieldOptions} [props.passwordField] 비밀번호 필드 옵션
+ * @property {AuthLoginFieldTexts} [props.texts] 로그인 form 기본 문구 옵션
  * @property {React.FormHTMLAttributes<HTMLFormElement>} [props.formAttr] <form> attr
  * @property {SubmitHandler<AuthLoginFormValues>} props.onLogin 로그인 콜백
  */
 export default function AuthLoginFormField({
   idField,
   passwordField,
+  texts,
   formAttr,
   onLogin,
 }: AuthLoginFieldOptions) {
@@ -73,6 +75,10 @@ export default function AuthLoginFormField({
       ? { text: passwordHelperNode, state: helpers.password.state }
       : undefined;
 
+  const idLabel = idField?.label ?? texts?.idLabel ?? "아이디";
+  const passwordLabel =
+    passwordField?.label ?? texts?.passwordLabel ?? "비밀번호";
+
   return (
     <form className="auth-login-form" {...formAttr} onSubmit={onSubmit}>
       <div className="auth-login-fields">
@@ -80,10 +86,13 @@ export default function AuthLoginFormField({
         <AuthLoginFormFieldId
           register={register.id}
           helper={idHelper}
-          label={idField?.label ?? "아이디"}
+          label={idLabel}
           placeholder={
             idField?.placeholder ??
-            `${idField?.label ?? "아이디"}를 입력해 주세요`
+            texts?.idPlaceholder ??
+            (typeof idLabel === "string" || typeof idLabel === "number"
+              ? `${idLabel}를 입력해 주세요`
+              : "아이디를 입력해 주세요")
           }
           inputProps={idField?.inputProps}
           templateProps={idField?.templateProps}
@@ -92,8 +101,12 @@ export default function AuthLoginFormField({
         <AuthLoginFormFieldPassword
           register={register.password}
           helper={passwordHelper}
-          label={passwordField?.label ?? "비밀번호"}
-          placeholder={passwordField?.placeholder ?? "비밀번호를 입력해 주세요"}
+          label={passwordLabel}
+          placeholder={
+            passwordField?.placeholder ??
+            texts?.passwordPlaceholder ??
+            "비밀번호를 입력해 주세요"
+          }
           inputProps={passwordField?.inputProps}
           templateProps={passwordField?.templateProps}
         />
@@ -105,7 +118,7 @@ export default function AuthLoginFormField({
           block
           disabled={disabled}
         >
-          로그인
+          {texts?.submit ?? "로그인"}
         </Button.Default>
       </div>
     </form>

package/src/auth/login/markup/LinkButtons.tsx

@@ -1,21 +1,20 @@
 import Link from "next/link";
 import { Button, Divider } from "@uniai-fe/uds-primitives";
-import type { AuthLoginLinkOptions } from "../types";
+import type { AuthLoginLinkButtonsProps } from "../types";
 
 /**
  * 로그인 링크 버튼 묶음; 전달된 링크만 선택적으로 렌더링한다.
  * @component
- * @param {{ linkOptions?: AuthLoginLinkOptions; onFindPasswordClick?: () => void; }} props
- * @param {AuthLoginLinkOptions} [props.linkOptions] 로그인 링크 옵션
+ * @param {AuthLoginLinkButtonsProps} props
+ * @param {AuthLoginLinkOptions} [props.linkOptions] 계정 관련 링크 옵션
+ * @param {AuthLoginLinkTexts} [props.texts] 링크/버튼 문구 옵션
  * @param {() => void} [props.onFindPasswordClick] 비밀번호 찾기 커스텀 클릭 핸들러
  */
 export default function AuthLoginLinkButtons({
   linkOptions,
+  texts,
   onFindPasswordClick,
-}: {
-  linkOptions?: AuthLoginLinkOptions;
-  onFindPasswordClick?: () => void;
-}) {
+}: AuthLoginLinkButtonsProps) {
   const hrefFindId = linkOptions?.find?.id;
   const hrefFindPassword = linkOptions?.find?.password;
   const hrefSignup = linkOptions?.signup;
@@ -33,7 +32,7 @@ export default function AuthLoginLinkButtons({
               href={hrefFindId}
               className="auth-login-find-account-button auth-find-id-button"
             >
-              <span>아이디 찾기</span>
+              <span>{texts?.findId ?? "아이디 찾기"}</span>
             </Link>
           )}
           {hrefFindId && hrefFindPassword && <Divider />}
@@ -45,14 +44,14 @@ export default function AuthLoginLinkButtons({
                 className="auth-login-find-account-button auth-find-password-button"
                 onClick={onFindPasswordClick}
               >
-                <span>비밀번호 찾기</span>
+                <span>{texts?.findPassword ?? "비밀번호 찾기"}</span>
               </button>
             ) : (
               <Link
                 href={hrefFindPassword}
                 className="auth-login-find-account-button auth-find-password-button"
               >
-                <span>비밀번호 찾기</span>
+                <span>{texts?.findPassword ?? "비밀번호 찾기"}</span>
               </Link>
             ))}
         </div>
@@ -67,7 +66,7 @@ export default function AuthLoginLinkButtons({
             priority="tertiary"
             size="small"
           >
-            회원가입
+            {texts?.signup ?? "회원가입"}
           </Button.Rounded>
         </div>
       )}

package/src/auth/login/types/props.ts

@@ -216,10 +216,71 @@ export interface AuthLoginIdFieldOptions extends AuthLoginFieldProps<InputProps>
  */
 export interface AuthLoginPasswordFieldOptions extends AuthLoginFieldProps<InputPasswordProps> {}
 
+/**
+ * 로그인 필드 문구 옵션
+ * @property {ReactNode} [idLabel] 아이디 필드 기본 라벨
+ * @property {string} [idPlaceholder] 아이디 필드 기본 placeholder
+ * @property {ReactNode} [passwordLabel] 비밀번호 필드 기본 라벨
+ * @property {string} [passwordPlaceholder] 비밀번호 필드 기본 placeholder
+ * @property {ReactNode} [submit] submit 버튼 라벨
+ */
+export interface AuthLoginFieldTexts {
+  /**
+   * 아이디 필드 기본 라벨
+   */
+  idLabel?: ReactNode;
+  /**
+   * 아이디 필드 기본 placeholder
+   */
+  idPlaceholder?: string;
+  /**
+   * 비밀번호 필드 기본 라벨
+   */
+  passwordLabel?: ReactNode;
+  /**
+   * 비밀번호 필드 기본 placeholder
+   */
+  passwordPlaceholder?: string;
+  /**
+   * submit 버튼 라벨
+   */
+  submit?: ReactNode;
+}
+
+/**
+ * 로그인 링크 문구 옵션
+ * @property {ReactNode} [findId] 아이디 찾기 링크 라벨
+ * @property {ReactNode} [findPassword] 비밀번호 찾기 링크 라벨
+ * @property {ReactNode} [signup] 회원가입 버튼 라벨
+ */
+export interface AuthLoginLinkTexts {
+  /**
+   * 아이디 찾기 링크 라벨
+   */
+  findId?: ReactNode;
+  /**
+   * 비밀번호 찾기 링크 라벨
+   */
+  findPassword?: ReactNode;
+  /**
+   * 회원가입 버튼 라벨
+   */
+  signup?: ReactNode;
+}
+
+/**
+ * 로그인 템플릿 문구 옵션
+ * @extends AuthLoginFieldTexts
+ * @extends AuthLoginLinkTexts
+ */
+export interface AuthLoginTexts
+  extends AuthLoginFieldTexts, AuthLoginLinkTexts {}
+
 /**
  * 로그인 필드 옵션; form attr + 제출 핸들러 포함
  * @property {AuthLoginIdFieldOptions} [idField] 로그인 아이디 필드 옵션
  * @property {AuthLoginPasswordFieldOptions} [passwordField] 로그인 비밀번호 필드 옵션
+ * @property {AuthLoginFieldTexts} [texts] 로그인 form 기본 문구 옵션
  * @property {React.FormHTMLAttributes<HTMLFormElement>} [formAttr] <form /> attributes
  * @property {SubmitHandler<Record<string, string>>} onLogin 로그인 콜백 이벤트
  */
@@ -232,6 +293,10 @@ export interface AuthLoginFieldOptions {
    * 비밀번호 필드 설정
    */
   passwordField?: AuthLoginPasswordFieldOptions;
+  /**
+   * 로그인 form 기본 문구 옵션
+   */
+  texts?: AuthLoginFieldTexts;
   /**
    * form attr
    */
@@ -271,6 +336,27 @@ export interface AuthLoginLinkOptions {
   signup?: string;
 }
 
+/**
+ * 로그인 링크 버튼 props
+ * @property {AuthLoginLinkOptions} [linkOptions] 계정 관련 링크 옵션
+ * @property {AuthLoginLinkTexts} [texts] 링크/버튼 문구 옵션
+ * @property {() => void} [onFindPasswordClick] 비밀번호 찾기 링크버튼 클릭 콜백 이벤트
+ */
+export interface AuthLoginLinkButtonsProps {
+  /**
+   * 계정 관련 링크 옵션
+   */
+  linkOptions?: AuthLoginLinkOptions;
+  /**
+   * 링크/버튼 문구 옵션
+   */
+  texts?: AuthLoginLinkTexts;
+  /**
+   * 비밀번호 찾기 링크버튼 클릭 콜백 이벤트
+   */
+  onFindPasswordClick?: () => void;
+}
+
 /**
  * 로그인 템플릿 props; 컨테이너와 필드/링크 옵션을 조합한다.
  * @template TFields
@@ -279,6 +365,7 @@ export interface AuthLoginLinkOptions {
  * @property {ReactNode} [footer] 하단 콘텐츠
  * @property {AuthLoginFieldOptions} [fieldOptions] 입력 필드 옵션
  * @property {AuthLoginLinkOptions} [linkOptions] 계정관련 링크 옵션
+ * @property {AuthLoginTexts} [texts] 로그인 템플릿 기본 문구 옵션
  * @property {() => void} [onFindPasswordLinkClick] 비밀번호 찾기 링크버튼 클릭 콜백 이벤트
  */
 export interface AuthLoginProps extends Omit<AuthContainerProps, "children"> {
@@ -290,6 +377,10 @@ export interface AuthLoginProps extends Omit<AuthContainerProps, "children"> {
    * 링크 옵션
    */
   linkOptions?: AuthLoginLinkOptions;
+  /**
+   * 로그인 템플릿 기본 문구 옵션
+   */
+  texts?: AuthLoginTexts;
   /**
    * 비밀번호 찾기 링크 클릭 핸들러
    */

package/src/cctv/components/cam-list/Item.tsx

@@ -57,7 +57,13 @@ export default function CCTVCamListItem({
         footerOptions={{ activeTitle: true, activeOpenButton: true, cam }}
         // 변경 설명: list item custom overlay는 template seam 하나만 따라간다.
         renderOverlay={renderOverlay}
-        {...{ isError, overlayMessage, isLive }}
+        {...{
+          isError,
+          overlayMessage,
+          isLive,
+          canReconnect: rtcCtx.canReconnect,
+          reconnectStream: rtcCtx.reconnectStream,
+        }}
       />
     </li>
   );

package/src/cctv/components/pagination/list/Item.tsx

@@ -59,7 +59,13 @@ export default function CCTVPaginationListItem({
             title: cam.cam_name,
           }}
           footerOptions={{ cam }}
-          {...{ isError, overlayMessage, isLive }}
+          {...{
+            isError,
+            overlayMessage,
+            isLive,
+            canReconnect: rtcCtx.canReconnect,
+            reconnectStream: rtcCtx.reconnectStream,
+          }}
         />
       </button>
     </li>

package/src/cctv/components/video/Template.tsx

@@ -18,6 +18,8 @@ import type { CctvVideoTemplateProps } from "../../types/props";
  * @property {React.ReactNode} [overlayMessage]
  * @property {boolean} [isLive]
  * @property {CctvCompanyCameraData} [cam]
+ * @property {boolean} [canReconnect]
+ * @property {CctvRtcReconnectTrigger} [reconnectStream]
  * @property {CctvVideoRenderOverlay} [renderOverlay]
  * @property {React.Ref<HTMLVideoElement>} ref
  */
@@ -31,6 +33,8 @@ const CCTVVideoTemplate = forwardRef<HTMLVideoElement, CctvVideoTemplateProps>(
       isError,
       isLive,
       overlayMessage,
+      canReconnect,
+      reconnectStream,
       renderOverlay,
     },
     ref,
@@ -56,6 +60,8 @@ const CCTVVideoTemplate = forwardRef<HTMLVideoElement, CctvVideoTemplateProps>(
             isError,
             isLive,
             overlayMessage,
+            canReconnect,
+            reconnectStream,
           })
         : defaultOverlay;
 

package/src/cctv/components/viewer/desktop/Video.tsx

@@ -57,7 +57,13 @@ export default function CCTVViewerDesktopVideo({
       footerOptions={{ activeTitle: false }}
       // 변경 설명: viewer video는 service custom overlay를 직접 수용하는 첫 public entry다.
       renderOverlay={renderOverlay}
-      {...{ isError, overlayMessage, isLive }}
+      {...{
+        isError,
+        overlayMessage,
+        isLive,
+        canReconnect: rtcCtx.canReconnect,
+        reconnectStream: rtcCtx.reconnectStream,
+      }}
     />
   );
 }

package/src/cctv/hooks/useRtcStream.ts

@@ -10,11 +10,17 @@ import {
   useCctvApiUrl,
   useCctvRtcStreamRegistry,
 } from "../components/Provider";
-import type { UseCctvRtcStreamParams, UseCctvRtcStreamReturn } from "../types";
+import type {
+  CctvRtcReconnectTrigger,
+  UseCctvRtcStreamParams,
+  UseCctvRtcStreamReturn,
+} from "../types";
 import { cctvRtcLiveRegistryAtom } from "../jotai/rtc";
 import { getIsLive } from "../utils/video-state";
 import { useFormContext, useWatch } from "react-hook-form";
 
+const AUTO_RECONNECT_INTERVAL_MS = 3000;
+
 /**
  * CCTV 영상 스트림을 WebRTC로 연결하는 커스텀 훅.
  * @hook
@@ -31,7 +37,9 @@ import { useFormContext, useWatch } from "react-hook-form";
  *   isStreaming, // 현재 스트림 연결 절차가 진행 중인지 여부
  *   isTokenLoading, // 토큰 발급 요청이 진행 중인지 여부
  *   isTokenError, // 토큰 발급 요청이 실패했는지 여부
+ *   canReconnect, // 재연결 가능한 종료 상태 여부
  *   refetchToken, // 토큰 발급을 재시도하는 함수
+ *   reconnectStream, // 재연결 trigger 함수
  * }
  */
 export function useCctvRtcStream({
@@ -51,6 +59,7 @@ export function useCctvRtcStream({
   const videoRef = useRef<HTMLVideoElement | null>(null);
   const activeStreamKeyRef = useRef<string | null>(null);
   const activeStreamIdentityKeyRef = useRef<string | null>(null);
+  const lastAutoReconnectAtRef = useRef(0);
 
   // RTCPeerConnectionState를 관찰해 UI에 노출하기 위한 상태값.
   const [connectionState, setConnectionState] =
@@ -61,6 +70,7 @@ export function useCctvRtcStream({
 
   // 현재 스트림 연결 절차가 진행 중인지 여부.
   const [isStreaming, setStreaming] = useState(false);
+  const [hasConnected, setHasConnected] = useState(false);
 
   // react-hook-form 컨텍스트에서 username을 추적한다.
   const { control } = useFormContext();
@@ -74,6 +84,7 @@ export function useCctvRtcStream({
     url: tokenUrl ?? contextTokenUrl,
   });
 
+  const { refetch: refetchRtcToken } = tokenQuery;
   const isTokenLoading = tokenQuery.isFetching;
   const isTokenError = tokenQuery.isError;
 
@@ -111,6 +122,10 @@ export function useCctvRtcStream({
     return [username, cam.company_id, cam.cam_id, endpoint].join("|");
   }, [cam?.cam_id, cam?.company_id, endpoint, username]);
 
+  useEffect(() => {
+    setHasConnected(false);
+  }, [streamIdentityKey]);
+
   // 토큰과 endpoint가 준비되면 WebRTC 스트림을 연결한다.
   useEffect(() => {
     const currentVideo = videoRef.current;
@@ -154,6 +169,7 @@ export function useCctvRtcStream({
       setConnectionState(snapshot.connectionState);
       setStreamError(snapshot.streamError);
       setStreaming(snapshot.isStreaming);
+      if (snapshot.connectionState === "connected") setHasConnected(true);
       if (snapshot.stream && currentVideo.srcObject !== snapshot.stream) {
         currentVideo.srcObject = snapshot.stream;
       }
@@ -162,6 +178,7 @@ export function useCctvRtcStream({
     setConnectionState(snapshot.connectionState);
     setStreamError(snapshot.streamError);
     setStreaming(snapshot.isStreaming);
+    if (snapshot.connectionState === "connected") setHasConnected(true);
 
     if (snapshot.stream && currentVideo.srcObject !== snapshot.stream) {
       currentVideo.srcObject = snapshot.stream;
@@ -182,17 +199,65 @@ export function useCctvRtcStream({
     cam?.cam_online,
   ]);
 
-  const refetchToken = useCallback<typeof tokenQuery.refetch>(
+  const reconnectStream = useCallback<CctvRtcReconnectTrigger>(
     async options => {
-      const result = await tokenQuery.refetch(options);
+      const result = await refetchRtcToken(options);
       if (result.isSuccess && streamIdentityKey) {
         streamRegistry.closeByIdentity(streamIdentityKey);
       }
       return result;
     },
-    [streamIdentityKey, streamRegistry, tokenQuery],
+    [refetchRtcToken, streamIdentityKey, streamRegistry],
   );
 
+  const canReconnect = useMemo(() => {
+    if (!cam?.cam_online) return false;
+    if (!hasConnected) return false;
+    if (!streamIdentityKey) return false;
+    if (isTokenLoading || isStreaming) return false;
+    if (isTokenError || streamError) return true;
+    if (connectionState === "failed") return true;
+    if (connectionState === "disconnected") return true;
+    if (connectionState === "closed") return true;
+    return false;
+  }, [
+    cam?.cam_online,
+    connectionState,
+    hasConnected,
+    isStreaming,
+    isTokenError,
+    isTokenLoading,
+    streamError,
+    streamIdentityKey,
+  ]);
+
+  const refetchToken = reconnectStream;
+
+  useEffect(() => {
+    if (typeof window === "undefined" || typeof document === "undefined")
+      return;
+
+    const reconnectOnFocus = () => {
+      if (document.visibilityState !== "visible") return;
+      if (!canReconnect) return;
+
+      const now = Date.now();
+      if (now - lastAutoReconnectAtRef.current < AUTO_RECONNECT_INTERVAL_MS)
+        return;
+
+      lastAutoReconnectAtRef.current = now;
+      void reconnectStream();
+    };
+
+    window.addEventListener("focus", reconnectOnFocus);
+    document.addEventListener("visibilitychange", reconnectOnFocus);
+
+    return () => {
+      window.removeEventListener("focus", reconnectOnFocus);
+      document.removeEventListener("visibilitychange", reconnectOnFocus);
+    };
+  }, [canReconnect, reconnectStream]);
+
   const liveState = useMemo(
     () =>
       cam
@@ -257,6 +322,8 @@ export function useCctvRtcStream({
     isStreaming,
     isTokenLoading,
     isTokenError,
+    canReconnect,
     refetchToken,
+    reconnectStream,
   };
 }

package/src/cctv/types/hook.ts

@@ -1,4 +1,8 @@
-import type { UseQueryResult } from "@tanstack/react-query";
+import type {
+  QueryObserverResult,
+  RefetchOptions,
+  UseQueryResult,
+} from "@tanstack/react-query";
 import type { API_Res_CctvCompany, API_Res_CctvRtcToken } from "./api";
 import type {
   CctvCompanyCameraData,
@@ -9,6 +13,13 @@ import type {
 import type { UseFormReturn } from "react-hook-form";
 import type { CctvBaseContext } from "./context";
 
+/**
+ * CCTV; RTC stream 재연결 trigger
+ */
+export type CctvRtcReconnectTrigger = (
+  options?: RefetchOptions,
+) => Promise<QueryObserverResult<API_Res_CctvRtcToken>>;
+
 /**
  * CCTV; useCctvRtcStream params
  * @property {CctvCompanyCameraData} [cam] 스트리밍 카메라 정보
@@ -77,17 +88,27 @@ export interface UseCctvRtcStreamState extends UseCctvRtcStreamError {
  * @property {boolean} isStreaming startWhepStream 진행 여부
  * @property {boolean} isTokenLoading 토큰 발급 요청 진행 여부
  * @property {boolean} isTokenError 토큰 발급 실패 여부
+ * @property {boolean} canReconnect 재연결 가능한 종료 상태 여부
  * @property {() => Promise<void>} refetchToken 토큰 재발급 함수
+ * @property {() => Promise<QueryObserverResult<API_Res_CctvRtcToken>>} reconnectStream 재연결 trigger 함수
  */
 export interface UseCctvRtcStreamReturn extends UseCctvRtcStreamState {
   /**
    * <video /> ref
    */
   videoRef: React.RefObject<HTMLVideoElement | null>;
+  /**
+   * 재연결 가능한 종료 상태 여부
+   */
+  canReconnect: boolean;
   /**
    * 토큰 재발급 함수
    */
-  refetchToken: UseQueryResult<API_Res_CctvRtcToken>["refetch"];
+  refetchToken: CctvRtcReconnectTrigger;
+  /**
+   * 재연결 trigger 함수
+   */
+  reconnectStream: CctvRtcReconnectTrigger;
 }
 
 /**

package/src/cctv/types/props.ts

@@ -1,4 +1,5 @@
 import type { CctvCompanyCameraData, CctvCompanyCameraList } from "./list";
+import type { CctvRtcReconnectTrigger } from "./hook";
 
 /**
  * CCTV; custom overlay render context
@@ -8,6 +9,8 @@ import type { CctvCompanyCameraData, CctvCompanyCameraList } from "./list";
  * @property {boolean | undefined} [isError] 영상 에러 상태 여부
  * @property {boolean | undefined} [isLive] 영상 live 상태 여부
  * @property {React.ReactNode} [overlayMessage] 기본 안내/에러 메시지 콘텐츠
+ * @property {boolean | undefined} [canReconnect] 재연결 가능한 종료 상태 여부
+ * @property {CctvRtcReconnectTrigger | undefined} [reconnectStream] 재연결 trigger 함수
  */
 export interface CctvVideoRenderOverlayContext {
   /**
@@ -34,6 +37,14 @@ export interface CctvVideoRenderOverlayContext {
    * 기본 안내/에러 메시지 콘텐츠
    */
   overlayMessage?: React.ReactNode;
+  /**
+   * 재연결 가능한 종료 상태 여부
+   */
+  canReconnect?: boolean;
+  /**
+   * 재연결 trigger 함수
+   */
+  reconnectStream?: CctvRtcReconnectTrigger;
 }
 
 /**
@@ -115,6 +126,8 @@ export interface CctvVideoOverlayFooterProps {
  * @property {boolean} [isError] 에러 상태 여부
  * @property {boolean} [isLive] 영상이 정상적으로 재생 중인지 여부
  * @property {React.ReactNode} [overlayMessage] 에러/안내 메시지 콘텐츠
+ * @property {boolean} [canReconnect] 재연결 가능한 종료 상태 여부
+ * @property {CctvRtcReconnectTrigger} [reconnectStream] 재연결 trigger 함수
  */
 export interface CctvVideoStateProps {
   /**
@@ -129,6 +142,14 @@ export interface CctvVideoStateProps {
    * 오버레이 메시지 콘텐츠
    */
   overlayMessage?: React.ReactNode;
+  /**
+   * 재연결 가능한 종료 상태 여부
+   */
+  canReconnect?: boolean;
+  /**
+   * 재연결 trigger 함수
+   */
+  reconnectStream?: CctvRtcReconnectTrigger;
 }
 
 /**

package/src/cctv/types/video-state.ts

@@ -11,6 +11,7 @@ import type { UseCctvRtcStreamError, UseCctvRtcStreamState } from "./hook";
  * @property {boolean} isTokenLoading 토큰 발급 요청 진행 여부
  * @property {boolean} isTokenError 토큰 발급 실패 여부
  * @property {string | null} streamError 스트림 오류 메시지
+ * @property {boolean} [canReconnect] 재연결 가능한 종료 상태 여부
  */
 export interface CctvVideoOverlayMessageParams extends UseCctvRtcStreamState {
   /**
@@ -25,6 +26,10 @@ export interface CctvVideoOverlayMessageParams extends UseCctvRtcStreamState {
    * 서버에서 cam 리스트를 가져오는 중인지 여부
    */
   isFetching?: boolean;
+  /**
+   * 재연결 가능한 종료 상태 여부
+   */
+  canReconnect?: boolean;
 }
 
 /**
@@ -48,10 +53,15 @@ export interface CctvVideoLiveParams extends UseCctvRtcStreamState {
  * @property {CctvCompanyCameraData} [cam] 카메라 데이터
  * @property {boolean} isTokenError 토큰 발급 실패 여부
  * @property {string | null} streamError 스트림 오류 메시지
+ * @property {boolean} [canReconnect] 재연결 가능한 종료 상태 여부
  */
 export interface CctvVideoErrorParams extends UseCctvRtcStreamError {
   /**
    * 카메라 데이터
    */
   cam?: CctvCompanyCameraData;
+  /**
+   * 재연결 가능한 종료 상태 여부
+   */
+  canReconnect?: boolean;
 }

package/src/cctv/utils/video-state.ts

@@ -8,6 +8,8 @@ export const CCTV_MESSAGE = {
   selectCam: "카메라를 선택하세요.",
   fetching: "CCTV 데이터를 불러오는 중입니다.",
   preparing: "스트림을 준비하고 있습니다.",
+  sessionEnded:
+    "장시간 미사용으로 연결이 종료되었습니다. 계속 확인하시려면 다시 연결해 주세요.",
   tokenError: "토큰을 발급하지 못했습니다.",
   offline: "CCTV 연결 오류",
 } as const;
@@ -34,6 +36,7 @@ const RTC_PREPARING_STATES = new Set<RTCPeerConnectionState>([
  */
 export function getOverlayMessage({
   cam,
+  canReconnect,
   connectionState,
   hasCamProp = false,
   isFetching = false,
@@ -48,6 +51,7 @@ export function getOverlayMessage({
   }
 
   if (!cam.cam_online) return CCTV_MESSAGE.offline;
+  if (canReconnect) return CCTV_MESSAGE.sessionEnded;
   // 에러 상태가 준비 상태와 겹칠 때는 에러 문구가 최종 표시 계약을 우선한다.
   if (isTokenError) return CCTV_MESSAGE.tokenError;
   if (streamError) return streamError;
@@ -95,11 +99,13 @@ export function getIsLive({
  */
 export function getIsError({
   cam,
+  canReconnect,
   isTokenError,
   streamError,
 }: CctvVideoErrorParams): boolean {
   if (!cam) return true;
   if (!cam.cam_online) return true;
+  if (canReconnect) return true;
   if (isTokenError) return true;
   if (streamError) return true;
   return false;

package/src/edge-case/components/NotFound.tsx

@@ -3,13 +3,35 @@
 import { clsx } from "clsx";
 import { Alternate } from "@uniai-fe/uds-primitives";
 import NotFoundIcon from "../img/404.svg";
-import type { EdgeCaseNotFoundProps } from "../types";
+import type { EdgeCaseNotFoundProps, EdgeCaseNotFoundTexts } from "../types";
+
+const DEFAULT_NOT_FOUND_TEXTS: Required<EdgeCaseNotFoundTexts> = {
+  title: "이 페이지를 찾을 수 없습니다.",
+  description: (
+    <>
+      페이지가 이동되었거나 삭제되었을 수 있습니다.
+      <br />
+      페이지 주소를 다시 확인해 주세요.
+    </>
+  ),
+  inquiryPrefix: "관련된 문의사항은 ",
+  inquiryAction: "문의하기",
+  inquirySuffix: (
+    <>
+      를 통해
+      <br />
+      접수해 주시길 바랍니다.
+    </>
+  ),
+  prevAction: "이전 페이지로",
+};
 
 /**
  * Edge Case Not Found; not-found 상태 화면 템플릿
  * @component
  * @param {EdgeCaseNotFoundProps} props
  * @param {string} [props.className] 최상위 edge-case container className override다.
+ * @param {EdgeCaseNotFoundTexts} [props.texts] not-found 기본 문구 override다.
  * @param {string} [props.inquiryHref] 문의 text action을 link로 렌더링할 href다.
  * @param {() => void} [props.onInquiry] 문의 text action을 button으로 렌더링할 콜백이다.
  * @param {string} [props.fallbackHref] onPrev가 없을 때 사용할 fallback href다.
@@ -19,11 +41,17 @@ import type { EdgeCaseNotFoundProps } from "../types";
  */
 export default function EdgeCaseNotFound({
   className,
+  texts,
   inquiryHref,
   onInquiry,
   fallbackHref = "/",
   onPrev,
 }: EdgeCaseNotFoundProps) {
+  const resolvedTexts = {
+    ...DEFAULT_NOT_FOUND_TEXTS,
+    ...texts,
+  };
+
   // 변경: data-edge-case forwarding이 없는 설치본에서도 NotFound preset 스타일이 적용되도록 class hook을 병행한다.
   return (
     <Alternate.Layout.Container
@@ -39,35 +67,29 @@ export default function EdgeCaseNotFound({
         />
       </Alternate.Layout.Figure>
       <Alternate.Layout.Title as="h1">
-        이 페이지를 찾을 수 없습니다.
+        {resolvedTexts.title}
       </Alternate.Layout.Title>
       <Alternate.Layout.Contents>
-        <p>
-          페이지가 이동되었거나 삭제되었을 수 있습니다.
-          <br />
-          페이지 주소를 다시 확인해 주세요.
-        </p>
+        <p>{resolvedTexts.description}</p>
         {/* 변경: NotFound 본문 줄바꿈은 폭 제한이 아니라 Figma fixed copy의 br로 고정한다. */}
         {onInquiry || inquiryHref ? (
           <p>
-            관련된 문의사항은{" "}
+            {resolvedTexts.inquiryPrefix}
             <Alternate.Layout.TextButton href={inquiryHref} onClick={onInquiry}>
-              문의하기
+              {resolvedTexts.inquiryAction}
             </Alternate.Layout.TextButton>
-            를 통해
-            <br />
-            접수해 주시길 바랍니다.
+            {resolvedTexts.inquirySuffix}
           </p>
         ) : null}
       </Alternate.Layout.Contents>
       {/* 변경: router/history 판정은 내부에서 실행하지 않고 onPrev 또는 fallback href만 연결한다. */}
       {onPrev ? (
         <Alternate.Layout.Button onClick={onPrev}>
-          이전 페이지로
+          {resolvedTexts.prevAction}
         </Alternate.Layout.Button>
       ) : (
         <Alternate.Layout.Button as="a" href={fallbackHref}>
-          이전 페이지로
+          {resolvedTexts.prevAction}
         </Alternate.Layout.Button>
       )}
     </Alternate.Layout.Container>

package/src/edge-case/types/index.ts

@@ -65,6 +65,7 @@ export interface EdgeCaseLoadingProps {
 /**
  * Edge Case Not Found Props; not-found 상태 화면 템플릿 props
  * @property {string} [className] 최상위 edge-case container className override다.
+ * @property {EdgeCaseNotFoundTexts} [texts] not-found 기본 문구 override다.
  * @property {string} [inquiryHref] 문의 text action을 link로 렌더링할 href다.
  * @property {() => void} [onInquiry] 문의 text action을 button으로 렌더링할 콜백이다.
  * @property {string} [fallbackHref] onPrev가 없을 때 사용할 fallback href다.
@@ -75,6 +76,10 @@ export interface EdgeCaseNotFoundProps {
    * 최상위 edge-case container className override다.
    */
   className?: string;
+  /**
+   * not-found 기본 문구 override다.
+   */
+  texts?: EdgeCaseNotFoundTexts;
   /**
    * 문의 text action을 link로 렌더링할 href다.
    */
@@ -92,3 +97,39 @@ export interface EdgeCaseNotFoundProps {
    */
   onPrev?: () => void;
 }
+
+/**
+ * Edge Case Not Found Texts; not-found preset 문구
+ * @property {ReactNode} [title] 대표 제목 문구다.
+ * @property {ReactNode} [description] 설명 문구다.
+ * @property {ReactNode} [inquiryPrefix] 문의 action 앞 문구다.
+ * @property {ReactNode} [inquiryAction] 문의 text action 문구다.
+ * @property {ReactNode} [inquirySuffix] 문의 action 뒤 문구다.
+ * @property {ReactNode} [prevAction] 이전 페이지 action 문구다.
+ */
+export interface EdgeCaseNotFoundTexts {
+  /**
+   * 대표 제목 문구다.
+   */
+  title?: ReactNode;
+  /**
+   * 설명 문구다.
+   */
+  description?: ReactNode;
+  /**
+   * 문의 action 앞 문구다.
+   */
+  inquiryPrefix?: ReactNode;
+  /**
+   * 문의 text action 문구다.
+   */
+  inquiryAction?: ReactNode;
+  /**
+   * 문의 action 뒤 문구다.
+   */
+  inquirySuffix?: ReactNode;
+  /**
+   * 이전 페이지 action 문구다.
+   */
+  prevAction?: ReactNode;
+}

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

@@ -39,17 +39,33 @@ const ServiceInquiryForm = ({
 }: ServiceInquiryFormProps) => {
   const form = useFormContext<ServiceInquiryFormValues>();
   const selectedInquiryType = form.watch("inquiry_type");
+  const inquiryTypeOptions =
+    inquiryTypeField?.options ?? DEFAULT_INQUIRY_TYPE_OPTIONS;
+  const farmNameState = form.getFieldState("farm_name", form.formState);
+  const contactState = form.getFieldState("contact", form.formState);
+  const inquiryTypeState = form.getFieldState("inquiry_type", form.formState);
+  const textState = form.getFieldState("text", form.formState);
 
   // 변경 설명: Modal.Dialog confirm 기본 submit과 연결되도록 form.handleSubmit 결과를 그대로 onSubmit에 바인딩한다.
   const handleSubmit = form.handleSubmit(onSubmit);
 
   useEffect(() => {
-    form.register("inquiry_type");
-    if (!form.getValues("inquiry_type")) {
-      // 변경 설명: 문의 유형은 선택형 form 상태로 유지하고, 서비스 앱이 필요하면 submit 경계에서 user_context로 접어 보낸다.
-      form.setValue("inquiry_type", "접속이 안 돼요");
+    form.register("inquiry_type", {
+      required:
+        inquiryTypeField?.required === false
+          ? false
+          : (inquiryTypeField?.requiredMessage ?? "문의 유형을 선택해 주세요"),
+    });
+    if (!form.getValues("inquiry_type") && inquiryTypeOptions[0]) {
+      // 변경 설명: 문의 유형 값은 options에 주입된 표시값을 그대로 form value로 사용한다.
+      form.setValue("inquiry_type", inquiryTypeOptions[0]);
     }
-  }, [form]);
+  }, [
+    form,
+    inquiryTypeField?.required,
+    inquiryTypeField?.requiredMessage,
+    inquiryTypeOptions,
+  ]);
 
   return (
     <form
@@ -64,6 +80,7 @@ const ServiceInquiryForm = ({
               "service-inquiry-field-farm-name",
             )}
             width="full"
+            state={farmNameState.invalid ? "error" : undefined}
             headerProps={{
               required: farmNameField?.required ?? true,
               ...(typeof farmNameField?.label === "string"
@@ -77,14 +94,21 @@ const ServiceInquiryForm = ({
                           : farmNameField.label,
                     }),
             }}
-            footer={farmNameField?.helper}
+            footer={farmNameState.error?.message ?? farmNameField?.helper}
           >
             <Input.Base
               type="text"
               block={true}
+              state={farmNameState.invalid ? "error" : undefined}
               readOnly={farmNameField?.mode === "readonly"}
               placeholder={farmNameField?.placeholder ?? "이름을 입력해 주세요"}
-              register={form.register("farm_name")}
+              register={form.register("farm_name", {
+                required:
+                  farmNameField?.required === false
+                    ? false
+                    : (farmNameField?.requiredMessage ??
+                      "이름을 입력해 주세요"),
+              })}
             />
           </Form.Field.Template>
         ) : null}
@@ -96,6 +120,7 @@ const ServiceInquiryForm = ({
               "service-inquiry-field-contact",
             )}
             width="full"
+            state={contactState.invalid ? "error" : undefined}
             headerProps={{
               required: contactField?.required ?? true,
               ...(typeof contactField?.label === "string"
@@ -110,6 +135,7 @@ const ServiceInquiryForm = ({
                     }),
             }}
             footer={
+              contactState.error?.message ??
               contactField?.helper ??
               "필요한 경우 입력하신 연락처로 연락 드립니다."
             }
@@ -117,11 +143,18 @@ const ServiceInquiryForm = ({
             <Input.Base
               type="text"
               block={true}
+              state={contactState.invalid ? "error" : undefined}
               readOnly={contactField?.mode === "readonly"}
               placeholder={
                 contactField?.placeholder ?? "연락처를 입력해 주세요"
               }
-              register={form.register("contact")}
+              register={form.register("contact", {
+                required:
+                  contactField?.required === false
+                    ? false
+                    : (contactField?.requiredMessage ??
+                      "연락처를 입력해 주세요"),
+              })}
             />
           </Form.Field.Template>
         ) : null}
@@ -133,6 +166,7 @@ const ServiceInquiryForm = ({
               "service-inquiry-field-inquiry-type",
             )}
             width="full"
+            state={inquiryTypeState.invalid ? "error" : undefined}
             headerProps={{
               required: inquiryTypeField?.required ?? true,
               ...(typeof inquiryTypeField?.label === "string"
@@ -146,32 +180,30 @@ const ServiceInquiryForm = ({
                           : inquiryTypeField.label,
                     }),
             }}
-            footer={inquiryTypeField?.helper}
+            footer={inquiryTypeState.error?.message ?? inquiryTypeField?.helper}
           >
             <div className="service-inquiry-type-grid">
-              {(inquiryTypeField?.options ?? DEFAULT_INQUIRY_TYPE_OPTIONS).map(
-                inquiryType => {
-                  return (
-                    <Chip.ClickableStyle
-                      key={inquiryType}
-                      className="service-inquiry-type-option"
-                      chipStyle="filter"
-                      fill="solid"
-                      selected={selectedInquiryType === inquiryType}
-                      // 변경 설명: inquiry_type은 영문 key 변환 없이 선택된 한글 label 원문을 form 값으로 유지한다.
-                      onClick={() =>
-                        form.setValue("inquiry_type", inquiryType, {
-                          shouldDirty: true,
-                          shouldTouch: true,
-                          shouldValidate: true,
-                        })
-                      }
-                    >
-                      {inquiryType}
-                    </Chip.ClickableStyle>
-                  );
-                },
-              )}
+              {inquiryTypeOptions.map(inquiryType => {
+                return (
+                  <Chip.ClickableStyle
+                    key={inquiryType}
+                    className="service-inquiry-type-option"
+                    chipStyle="filter"
+                    fill="solid"
+                    selected={selectedInquiryType === inquiryType}
+                    // 변경 설명: inquiry_type은 변환 없이 선택된 label 원문을 form 값으로 유지한다.
+                    onClick={() =>
+                      form.setValue("inquiry_type", inquiryType, {
+                        shouldDirty: true,
+                        shouldTouch: true,
+                        shouldValidate: true,
+                      })
+                    }
+                  >
+                    {inquiryType}
+                  </Chip.ClickableStyle>
+                );
+              })}
             </div>
           </Form.Field.Template>
         ) : null}
@@ -183,6 +215,7 @@ const ServiceInquiryForm = ({
               "service-inquiry-field-text",
             )}
             width="full"
+            state={textState.invalid ? "error" : undefined}
             headerProps={{
               required: textField?.required ?? true,
               ...(typeof textField?.label === "string"
@@ -196,17 +229,24 @@ const ServiceInquiryForm = ({
                           : textField.label,
                     }),
             }}
-            footer={textField?.helper}
+            footer={textState.error?.message ?? textField?.helper}
           >
             <Input.TextArea
               block={true}
+              state={textState.invalid ? "error" : undefined}
               placeholder={
                 textField?.placeholder ??
                 "어떤 문제가 있었는지 적어주세요.\n예: 화면이 멈췄어요."
               }
               height={160}
               maxLength={10000}
-              register={form.register("text")}
+              register={form.register("text", {
+                required:
+                  textField?.required === false
+                    ? false
+                    : (textField?.requiredMessage ??
+                      "문의 내용을 입력해 주세요"),
+              })}
             />
           </Form.Field.Template>
         ) : null}

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

@@ -10,6 +10,7 @@ import clsx from "clsx";
  * @component
  * @param {UseOpenServiceInquiryOptions} props 문의 모달 열기 props
  * @param {string} [props.className]
+ * @param {string} [props.ariaLabel] button aria-label
  * @param {string} [props.stackKey] modal stack key
  * @param {ServiceInquiryFormProps} props.formProps 문의 form props
  * @param {Partial<DialogTemplateOptions<ServiceInquiryFormValues>>} [props.dialogOptions] 문의 모달 preset 위에 덮어쓸 dialog option
@@ -21,6 +22,7 @@ import clsx from "clsx";
  */
 export default function ServiceInquiryOpenButton({
   className,
+  ariaLabel = "문의하기",
   stackKey,
   formProps,
   dialogOptions,
@@ -38,6 +40,7 @@ export default function ServiceInquiryOpenButton({
       className={clsx("service-inquiry-open-button", className)}
       priority="tertiary"
       size="large"
+      aria-label={ariaLabel}
       // 변경 설명: 기본 제공 버튼은 고정 원형 `?` 버튼 사양으로 렌더링한다.
       onClick={openServiceInquiry}
     >

package/src/service-inquiry/styles/form.scss

@@ -36,6 +36,11 @@
   font-size: var(--service-inquiry-type-font-size);
   font-weight: var(--service-inquiry-type-font-weight-default);
   line-height: 1.4;
+
+  :where(.chip-label) {
+    // 변경 설명: Chip 기본 label은 ellipsis를 위해 overflow hidden + line-height 1em을 갖기 때문에, service-inquiry의 큰 영문 라벨 descender가 잘리지 않도록 line-height만 모듈 범위에서 보정한다.
+    line-height: 1.4;
+  }
 }
 
 .service-inquiry-type-option:where([data-selected="true"]) {

package/src/service-inquiry/types/form-context.ts

@@ -1,12 +1,8 @@
 /**
  * Service Inquiry Form; 문의 유형 값
- * @typedef {"접속이 안 돼요" | "화면이 멈춰요" | "데이터가 안나와요" | "기타"} ServiceInquiryType
+ * @typedef {string} ServiceInquiryType
  */
-export type ServiceInquiryType =
-  | "접속이 안 돼요"
-  | "화면이 멈춰요"
-  | "데이터가 안나와요"
-  | "기타";
+export type ServiceInquiryType = string;
 
 /**
  * Service Inquiry Form; 사용자 입력값

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

@@ -26,6 +26,7 @@ export type ServiceInquiryFieldMode = "editable" | "readonly";
  * @property {ReactNode} [label] field label
  * @property {ReactNode} [helper] field helper
  * @property {boolean} [required] required 표시 여부
+ * @property {string} [requiredMessage] required validation message
  */
 export interface ServiceInquiryFieldBaseProps {
   /**
@@ -40,6 +41,10 @@ export interface ServiceInquiryFieldBaseProps {
    * required 표시 여부
    */
   required?: boolean;
+  /**
+   * required validation message
+   */
+  requiredMessage?: string;
 }
 
 /**
@@ -163,6 +168,7 @@ export interface UseOpenServiceInquiryOptions extends ServiceInquiryCreateModalO
 /**
  * Service Inquiry Button props; 버튼 옵션
  * @property {string} [className]
+ * @property {string} [ariaLabel] button aria-label
  * @property {string} [stackKey] modal stack key
  * @property {ServiceInquiryFormProps} formProps 문의 form props
  * @property {Partial<DialogTemplateOptions<ServiceInquiryFormValues>>} [dialogOptions] 문의 모달 preset 위에 덮어쓸 dialog option
@@ -173,6 +179,10 @@ export interface ServiceInquiryOpenButtonProps extends UseOpenServiceInquiryOpti
    * button className
    */
   className?: string;
+  /**
+   * button aria-label
+   */
+  ariaLabel?: string;
 }
 
 /**