@uniai-fe/uds-templates 0.5.3 → 0.5.5

package/package.json

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

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

@@ -2,17 +2,25 @@
 
 import clsx from "clsx";
 import CCTVCamListItem from "./Item";
-import type { CctvCompanyCameraList } from "../../types";
+import type { CctvCamListContainerProps } from "../../types";
 import { useCctvContext } from "../../hooks";
 import { useMemo } from "react";
 
+/**
+ * CCTV; cam-list container
+ * @component
+ * @param {CctvCamListContainerProps} props
+ * @param {string} [props.className] 루트 컨테이너 클래스
+ * @param {CctvCompanyCameraList[]} [props.list] 외부에서 직접 주입하는 카메라 리스트
+ * @param {CctvVideoRenderOverlay} [props.renderOverlay] 각 item video overlay를 교체하는 custom render 함수
+ * @example
+ * <CCTV.CamList.Container renderOverlay={({ cam }) => <div>{cam?.cam_name}</div>} />
+ */
 export default function CCTVCamListContainer({
   className,
   list,
-}: {
-  className?: string;
-  list?: CctvCompanyCameraList[];
-}) {
+  renderOverlay,
+}: CctvCamListContainerProps) {
   const { cams } = useCctvContext();
   const camList = useMemo(() => list ?? cams, [list, cams]);
   // console.log("CCTVCamListContainer camList:", { list, camList });
@@ -28,7 +36,12 @@ export default function CCTVCamListContainer({
     <div className={clsx("cctv-cam-list-container", className)}>
       <ul className="cctv-cam-list-track">
         {camList.map(({ renderKey, ...cam }) => (
-          <CCTVCamListItem key={renderKey} {...cam} />
+          <CCTVCamListItem
+            key={renderKey}
+            {...cam}
+            // 변경 설명: container에서 받은 overlay seam을 item까지 그대로 전달한다.
+            renderOverlay={renderOverlay}
+          />
         ))}
       </ul>
     </div>

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

@@ -1,22 +1,30 @@
 "use client";
 
 import clsx from "clsx";
-import type { CctvCompanyCameraData } from "../../types";
 import { useCctvRtcStream } from "../../hooks";
 import { useMemo } from "react";
 import CCTVVideoTemplate from "../video/Template";
+import type { CctvCamListItemProps } from "../../types";
 import {
   getOverlayMessage,
   getIsLive,
   getIsError,
 } from "../../utils/video-state";
 
+/**
+ * CCTV; cam-list item
+ * @component
+ * @param {CctvCamListItemProps} props
+ * @param {string} [props.className] 루트 아이템 클래스
+ * @param {CctvVideoRenderOverlay} [props.renderOverlay] item video overlay를 교체하는 custom render 함수
+ * @example
+ * <CCTV.CamList.Item {...cam} renderOverlay={({ headerOptions }) => <div>{headerOptions?.title}</div>} />
+ */
 export default function CCTVCamListItem({
   className,
+  renderOverlay,
   ...cam
-}: {
-  className?: string;
-} & CctvCompanyCameraData) {
+}: CctvCamListItemProps) {
   const { videoRef, ...rtcCtx } = useCctvRtcStream({ cam });
 
   const isLive = useMemo(() => getIsLive({ cam, ...rtcCtx }), [cam, rtcCtx]);
@@ -37,6 +45,7 @@ export default function CCTVCamListItem({
     >
       <CCTVVideoTemplate
         ref={videoRef}
+        cam={cam}
         className="cctv-cam-list-video-container"
         headerOptions={{
           activeLiveState: true,
@@ -46,6 +55,8 @@ export default function CCTVCamListItem({
           title: cam.cam_name,
         }}
         footerOptions={{ activeTitle: true, activeOpenButton: true, cam }}
+        // 변경 설명: list item custom overlay는 template seam 하나만 따라간다.
+        renderOverlay={renderOverlay}
         {...{ isError, overlayMessage, isLive }}
       />
     </li>

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

@@ -15,32 +15,54 @@ import type { CctvVideoTemplateProps } from "../../types/props";
  * @property {CctvVideoOverlayHeaderProps} [headerOptions]
  * @property {CctvVideoOverlayFooterProps} [footerOptions]
  * @property {boolean} [isError]
- * @property {string | null} [overlayMessage]
+ * @property {React.ReactNode} [overlayMessage]
  * @property {boolean} [isLive]
+ * @property {CctvCompanyCameraData} [cam]
+ * @property {CctvVideoRenderOverlay} [renderOverlay]
  * @property {React.Ref<HTMLVideoElement>} ref
  */
 const CCTVVideoTemplate = forwardRef<HTMLVideoElement, CctvVideoTemplateProps>(
   (
     {
+      cam,
       className,
       headerOptions,
       footerOptions,
       isError,
       isLive,
       overlayMessage,
+      renderOverlay,
     },
     ref,
   ) => {
+    // 변경 설명: custom overlay가 없을 때는 기존 overlay 조립을 그대로 유지한다.
+    const defaultOverlay = (
+      <CCTVVideoOverlayContainer>
+        <CCTVVideoOverlayHeader {...headerOptions} />
+        <CCTVVideoOverlayBody className={isError ? "is-error" : undefined}>
+          {!isLive ? <CCTVVideoError>{overlayMessage}</CCTVVideoError> : null}
+        </CCTVVideoOverlayBody>
+        <CCTVVideoOverlayFooter {...footerOptions} isLive={isLive} />
+      </CCTVVideoOverlayContainer>
+    );
+
+    // 변경 설명: service는 기존 public 타입 기반 ctx만 받아 overlay를 교체할 수 있다.
+    const overlayNode =
+      typeof renderOverlay === "function"
+        ? renderOverlay({
+            cam,
+            headerOptions,
+            footerOptions,
+            isError,
+            isLive,
+            overlayMessage,
+          })
+        : defaultOverlay;
+
     return (
       <CCTVVideoContainer className={className} isError={isError}>
         <CCTVVideoContents ref={ref} muted />
-        <CCTVVideoOverlayContainer>
-          <CCTVVideoOverlayHeader {...headerOptions} />
-          <CCTVVideoOverlayBody className={isError ? "is-error" : undefined}>
-            {!isLive ? <CCTVVideoError>{overlayMessage}</CCTVVideoError> : null}
-          </CCTVVideoOverlayBody>
-          <CCTVVideoOverlayFooter {...footerOptions} isLive={isLive} />
-        </CCTVVideoOverlayContainer>
+        {overlayNode}
       </CCTVVideoContainer>
     );
   },

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

@@ -1,9 +1,11 @@
 import CCTVVideoContainer from "./Container";
 import { CCTVVideoOverlay } from "./overlay";
+import CCTVVideoTemplate from "./Template";
 import CCTVVideoContents from "./Video";
 
 export const CCTVVideo = {
   Container: CCTVVideoContainer,
   Contents: CCTVVideoContents,
+  Template: CCTVVideoTemplate,
   Overlay: CCTVVideoOverlay,
 };

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

@@ -2,22 +2,27 @@ import clsx from "clsx";
 import CCTVViewerContainer from "../Container";
 import CCTVViewerDesktopPagination from "./Pagination";
 import CCTVViewerDesktopVideo from "./Video";
-import type {
-  CctvCompanyCameraData,
-  CctvCompanyCameraList,
-} from "../../../types";
+import type { CctvViewerDesktopContainerProps } from "../../../types";
 
+/**
+ * CCTV; viewer desktop container
+ * @component
+ * @param {CctvViewerDesktopContainerProps} props
+ * @param {string} [props.className] 루트 컨테이너 클래스
+ * @param {React.ReactNode} [props.children] 기본 조립 대신 직접 주입하는 children
+ * @param {CctvCompanyCameraData} [props.selectedCam] 외부에서 직접 주입하는 선택 카메라 데이터
+ * @param {CctvCompanyCameraList[]} [props.camList] 외부에서 직접 주입하는 pagination 카메라 리스트
+ * @param {CctvVideoRenderOverlay} [props.renderOverlay] main video overlay를 교체하는 custom render 함수
+ * @example
+ * <CCTV.Viewer.Desktop.Container renderOverlay={({ isLive }) => <div>{String(isLive)}</div>} />
+ */
 export default function CCTVViewerDesktopContainer({
   className,
   children,
   selectedCam,
   camList,
-}: {
-  className?: string;
-  children?: React.ReactNode;
-  selectedCam?: CctvCompanyCameraData;
-  camList?: CctvCompanyCameraList[];
-}) {
+  renderOverlay,
+}: CctvViewerDesktopContainerProps) {
   return (
     <CCTVViewerContainer
       className={clsx("cctv-viewer-desktop-container", className)}
@@ -30,6 +35,8 @@ export default function CCTVViewerDesktopContainer({
             {...(typeof selectedCam !== "undefined"
               ? { cam: selectedCam }
               : {})}
+            // 변경 설명: container에서 받은 seam을 main viewer video로 전달한다.
+            renderOverlay={renderOverlay}
           />
           <CCTVViewerDesktopPagination
             {...(typeof camList !== "undefined" ? { list: camList } : {})}

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

@@ -3,7 +3,7 @@
 import { useMemo } from "react";
 
 import { useCctvContext, useCctvRtcStream } from "../../../hooks";
-import type { CctvCompanyCameraData } from "../../../types";
+import type { CctvViewerDesktopVideoProps } from "../../../types";
 import CCTVVideoTemplate from "../../video/Template";
 import {
   getOverlayMessage,
@@ -11,11 +11,19 @@ import {
   getIsError,
 } from "../../../utils/video-state";
 
+/**
+ * CCTV; viewer desktop video
+ * @component
+ * @param {CctvViewerDesktopVideoProps} props
+ * @param {CctvCompanyCameraData} [props.cam] 외부에서 직접 주입하는 선택 카메라 데이터
+ * @param {CctvVideoRenderOverlay} [props.renderOverlay] main video overlay를 교체하는 custom render 함수
+ * @example
+ * <CCTV.Viewer.Desktop.Video renderOverlay={({ cam }) => <div>{cam?.cam_name}</div>} />
+ */
 export default function CCTVViewerDesktopVideo({
   cam: propsCam,
-}: {
-  cam?: CctvCompanyCameraData;
-}) {
+  renderOverlay,
+}: CctvViewerDesktopVideoProps) {
   const { selectedCam, isFetching } = useCctvContext();
 
   // props의 cam이 들어오면 우선 적용
@@ -36,6 +44,7 @@ export default function CCTVViewerDesktopVideo({
   return (
     <CCTVVideoTemplate
       ref={videoRef}
+      cam={cam}
       className="cctv-viewer-desktop-video-container"
       headerOptions={{
         activeLiveState: true,
@@ -46,6 +55,8 @@ export default function CCTVViewerDesktopVideo({
         title: cam?.cam_name,
       }}
       footerOptions={{ activeTitle: false }}
+      // 변경 설명: viewer video는 service custom overlay를 직접 수용하는 첫 public entry다.
+      renderOverlay={renderOverlay}
       {...{ isError, overlayMessage, isLive }}
     />
   );

package/src/cctv/types/props.ts

@@ -1,4 +1,47 @@
-import type { CctvCompanyCameraData } from "./list";
+import type { CctvCompanyCameraData, CctvCompanyCameraList } from "./list";
+
+/**
+ * CCTV; custom overlay render context
+ * @property {CctvCompanyCameraData | undefined} [cam] 현재 overlay가 참조하는 카메라 데이터
+ * @property {CctvVideoOverlayHeaderProps | undefined} [headerOptions] 기본 헤더 표시 옵션
+ * @property {CctvVideoOverlayFooterProps | undefined} [footerOptions] 기본 푸터 표시 옵션
+ * @property {boolean | undefined} [isError] 영상 에러 상태 여부
+ * @property {boolean | undefined} [isLive] 영상 live 상태 여부
+ * @property {React.ReactNode} [overlayMessage] 기본 안내/에러 메시지 콘텐츠
+ */
+export interface CctvVideoRenderOverlayContext {
+  /**
+   * 현재 overlay가 참조하는 카메라 데이터
+   */
+  cam?: CctvCompanyCameraData;
+  /**
+   * 기본 헤더 표시 옵션
+   */
+  headerOptions?: CctvVideoOverlayHeaderProps;
+  /**
+   * 기본 푸터 표시 옵션
+   */
+  footerOptions?: CctvVideoOverlayFooterProps;
+  /**
+   * 영상 에러 상태 여부
+   */
+  isError?: boolean;
+  /**
+   * 영상 live 상태 여부
+   */
+  isLive?: boolean;
+  /**
+   * 기본 안내/에러 메시지 콘텐츠
+   */
+  overlayMessage?: React.ReactNode;
+}
+
+/**
+ * CCTV; custom overlay render 함수
+ */
+export type CctvVideoRenderOverlay = (
+  context: CctvVideoRenderOverlayContext,
+) => React.ReactNode;
 
 /**
  * CCTV; <CctvVideoOverlayHeader /> props
@@ -96,8 +139,13 @@ export interface CctvVideoStateProps {
  * @property {boolean} [isError] 에러 상태 여부
  * @property {boolean} [isLive] 영상이 정상적으로 재생 중인지 여부
  * @property {React.ReactNode} [overlayMessage] 에러/안내 메시지 콘텐츠
+ * @property {CctvVideoRenderOverlay} [renderOverlay] custom overlay 렌더 함수
  */
 export interface CctvVideoTemplateProps extends CctvVideoStateProps {
+  /**
+   * 현재 overlay가 참조하는 카메라 데이터
+   */
+  cam?: CctvCompanyCameraData;
   className?: string;
   /**
    * <CCtvVideoOverlayHeader /> 속성
@@ -107,4 +155,102 @@ export interface CctvVideoTemplateProps extends CctvVideoStateProps {
    * <CctvVideoOverlayFooter /> 속성
    */
   footerOptions?: CctvVideoOverlayFooterProps;
+  /**
+   * custom overlay 렌더 함수
+   */
+  renderOverlay?: CctvVideoRenderOverlay;
+}
+
+/**
+ * CCTV; cam-list item props
+ * @property {string} [className] 루트 아이템 클래스
+ * @property {CctvVideoRenderOverlay} [renderOverlay] custom overlay 렌더 함수
+ * @property {boolean} selected 카메라 선택 상태
+ * @property {() => void} [onSelect] 카메라 선택 핸들러
+ * @property {string} cam_id 카메라 id코드
+ * @property {string} cam_name 카메라 별칭
+ * @property {boolean} cam_online 카메라 online 여부
+ * @property {string} [cam_rtc] 카메라 rtc 경로
+ * @property {string} [cam_rtcp] 카메라 rtcp 경로
+ * @property {boolean} [cam_shared] 카메라 외부공유 여부
+ * @property {string} [company_id] 소속 업체 id
+ * @property {string} [company_name] 소속 업체명
+ */
+export interface CctvCamListItemProps extends CctvCompanyCameraData {
+  /**
+   * 루트 아이템 클래스
+   */
+  className?: string;
+  /**
+   * custom overlay 렌더 함수
+   */
+  renderOverlay?: CctvVideoRenderOverlay;
+}
+
+/**
+ * CCTV; cam-list container props
+ * @property {string} [className] 루트 컨테이너 클래스
+ * @property {CctvCompanyCameraList[]} [list] 외부 주입 카메라 리스트
+ * @property {CctvVideoRenderOverlay} [renderOverlay] custom overlay 렌더 함수
+ */
+export interface CctvCamListContainerProps {
+  /**
+   * 루트 컨테이너 클래스
+   */
+  className?: string;
+  /**
+   * 외부 주입 카메라 리스트
+   */
+  list?: CctvCompanyCameraList[];
+  /**
+   * custom overlay 렌더 함수
+   */
+  renderOverlay?: CctvVideoRenderOverlay;
+}
+
+/**
+ * CCTV; viewer desktop video props
+ * @property {CctvCompanyCameraData} [cam] 외부에서 직접 주입하는 카메라 데이터
+ * @property {CctvVideoRenderOverlay} [renderOverlay] custom overlay 렌더 함수
+ */
+export interface CctvViewerDesktopVideoProps {
+  /**
+   * 외부에서 직접 주입하는 카메라 데이터
+   */
+  cam?: CctvCompanyCameraData;
+  /**
+   * custom overlay 렌더 함수
+   */
+  renderOverlay?: CctvVideoRenderOverlay;
+}
+
+/**
+ * CCTV; viewer desktop container props
+ * @property {string} [className] 루트 컨테이너 클래스
+ * @property {React.ReactNode} [children] 기본 video/pagination 대신 직접 주입할 children
+ * @property {CctvCompanyCameraData} [selectedCam] 외부에서 직접 주입하는 선택 카메라 데이터
+ * @property {CctvCompanyCameraData[]} [camList] 외부에서 직접 주입하는 카메라 리스트
+ * @property {CctvVideoRenderOverlay} [renderOverlay] viewer video용 custom overlay 렌더 함수
+ */
+export interface CctvViewerDesktopContainerProps {
+  /**
+   * 루트 컨테이너 클래스
+   */
+  className?: string;
+  /**
+   * 기본 video/pagination 대신 직접 주입할 children
+   */
+  children?: React.ReactNode;
+  /**
+   * 외부에서 직접 주입하는 선택 카메라 데이터
+   */
+  selectedCam?: CctvCompanyCameraData;
+  /**
+   * 외부에서 직접 주입하는 카메라 리스트
+   */
+  camList?: CctvCompanyCameraList[];
+  /**
+   * viewer video용 custom overlay 렌더 함수
+   */
+  renderOverlay?: CctvVideoRenderOverlay;
 }

package/src/page-frame/desktop/components/header/util/Button.tsx

@@ -3,12 +3,12 @@
 import clsx from "clsx";
 import { Button, type TextButtonProps } from "@uniai-fe/uds-primitives";
 
-export default function PageHeaderUtilityButton({
+export default function PageHeaderUtilityButton<CustomButtonProps>({
   as,
   className,
   children,
   ...props
-}: Omit<TextButtonProps, "size" | "priority">) {
+}: Omit<TextButtonProps & CustomButtonProps, "size" | "priority">) {
   return (
     <Button.Text
       as={as ?? "button"}

package/src/page-frame/desktop/components/header/util/Logout.tsx

@@ -1,7 +1,7 @@
 "use client";
 
 import Image from "next/image";
-import Link from "next/link";
+import Link, { type LinkProps } from "next/link";
 import assetsUrl from "../../../../../asset-url";
 import PageHeaderUtilityItem from "./Item";
 import PageHeaderUtilityButton from "./Button";
@@ -18,10 +18,11 @@ export default function PageHeaderLogoutButton({
     <PageHeaderUtilityItem
       className={clsx("page-header-util-logout", className)}
     >
-      <PageHeaderUtilityButton
+      <PageHeaderUtilityButton<LinkProps>
         href={path}
         as={Link}
         className="page-header-logout-button"
+        prefetch={false}
       >
         <figure>
           <Image

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

@@ -13,7 +13,7 @@ import type {
  * @returns {UseServiceInquiryNetworkErrorReturn} 최근 오류 목록과 기록/초기화 함수
  * @example
  * const { reportNetworkError } = useServiceInquiryNetworkError();
- * reportNetworkError({ route: "/api/v2/login", message: "timeout" });
+ * reportNetworkError({ route: "/api/login", message: "timeout" });
  */
 export function useServiceInquiryNetworkError(): UseServiceInquiryNetworkErrorReturn {
   const [networkErrors, setNetworkErrors] = useAtom(