@uniai-fe/uds-templates 0.5.4 → 0.5.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniai-fe/uds-templates",
-  "version": "0.5.4",
+  "version": "0.5.6",
   "description": "UNIAI Design System; UI Templates Package",
   "type": "module",
   "private": false,
@@ -12,7 +12,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "packageManager": "pnpm@10.33.0",
+  "packageManager": "pnpm@10.33.2",
   "engines": {
     "node": ">=24",
     "pnpm": ">=10"
@@ -70,7 +70,7 @@
   },
   "devDependencies": {
     "@svgr/webpack": "^8.1.0",
-    "@tanstack/react-query": "^5.99.0",
+    "@tanstack/react-query": "^5.100.1",
     "@types/node": "^24.10.2",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
@@ -89,7 +89,7 @@
     "jotai": "^2.19.1",
     "next": "^15.5.11",
     "prettier": "^3.8.3",
-    "react-hook-form": "^7.72.1",
+    "react-hook-form": "^7.73.1",
     "sass": "^1.99.0",
     "typescript": "5.9.3"
   }

package/src/cctv/apis/client.ts

@@ -6,31 +6,22 @@ import type {
   API_Res_CctvCompany,
   API_Res_CctvRtcToken,
 } from "../types";
-import { getQueryString } from "@uniai-fe/util-functions";
 
 export const getClientCctvCompanyList = async ({
-  username,
   url,
 }: {
-  username: string;
   url?: string;
-}) =>
-  await (
-    await fetch(
-      `${url ?? "/api/cctv/company-list"}${getQueryString({ username })}`,
-    )
-  ).json();
+}): Promise<API_Res_CctvCompany> =>
+  await (await fetch(url ?? "/api/cctv/company-list")).json();
 
 export const useQueryCctvCompanyList = ({
-  username,
   url,
 }: {
-  username: string;
   url?: string;
 }): UseQueryResult<API_Res_CctvCompany> =>
   useQuery({
-    queryKey: ["cctv_company_list", username, url],
-    queryFn: () => getClientCctvCompanyList({ username, url }),
+    queryKey: ["cctv_company_list", url],
+    queryFn: () => getClientCctvCompanyList({ url }),
   });
 
 export const postCctvRtcToken = async ({

package/src/cctv/apis/server.ts

@@ -132,46 +132,39 @@ export function classifyGroups(
 /**
  * CCTV; company-list API route.ts 로직
  * @api
- * @route /v1/users/{username}/cctvs
+ * @route /common/cctvs/{me|all}
  * @param {API_Req_GetCompanyListParams} params
  * @property {string} domain API 요청 도메인(서버)
  * @property {string} routeUrl Next.js app/api 이하 경로 url
  * @property {string} [queryUrl] 백엔드 요청 url
- * @property {URLSearchParams | object} searchParams 요청 searchParams
+ * @property {"me" | "all"} [scope] common/cctvs 조회 범위
  */
 export async function getServerCompanyList({
   domain,
   routeUrl,
   queryUrl,
-  searchParams,
+  scope = "me",
 }: API_Req_GetCompanyListParams): Promise<{
   res: API_Res_CctvCompany;
   domain: string;
   queryUrl: string;
   options?: ResponseInit;
 }> {
-  const username = searchParams.get("username") || "";
-  const query_url = queryUrl || `/v1/users/${username}/cctvs`;
+  const query_url = queryUrl || `/common/cctvs/${scope}`;
 
-  const alternateResponse = {
-    data: [],
-    total_count: 0,
+  const alternateResponse: API_Res_CctvCompany = {
+    status: "error",
+    data: {
+      items: [],
+      total_count: 0,
+    },
+    errors: [],
   };
   const API_OPTION = {
     domain,
     queryUrl: query_url,
-    // searchParams,
   };
 
-  if (!queryUrl && !username) {
-    nextAPILog("GET", routeUrl, query_url, { searchParams });
-    return {
-      res: alternateResponse,
-      ...API_OPTION,
-      options: { status: 400, statusText: "유저 아이디를 확인할 수 없습니다." },
-    };
-  }
-
   // 요청 URL 구성
   const url = generateQueryUrl({
     routeUrl,
@@ -181,12 +174,9 @@ export async function getServerCompanyList({
   try {
     const originRes: API_Res_CctvCompany = await (await fetch(url)).json();
 
-    // 응답 그룹/농장
-    const originGroups = originRes?.data || [];
-    const resGourps = classifyGroups(originGroups);
-
+    // 변경: server helper는 common/cctvs raw 응답을 유지하고 template 변환은 hook에서 처리한다.
     return {
-      res: { data: resGourps, total_count: originRes.total_count || 0 },
+      res: originRes,
       ...API_OPTION,
     };
   } catch (err) {

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/hooks/useCompanyData.tsx

@@ -1,47 +1,48 @@
 "use client";
 
 import { useEffect, useMemo } from "react";
-import { useQueryCctvCompanyList } from "../apis";
+import { classifyGroups, useQueryCctvCompanyList } from "../apis";
 import { useCctvApiUrl } from "../components/Provider";
 import useCctvContext from "./useContext";
-import type { UseCctvCompanyDataReturn } from "../types";
+import type {
+  UseCctvCompanyDataParams,
+  UseCctvCompanyDataReturn,
+} from "../types";
 
 /**
  * CCTV 회사 리스트 API를 호출해 데이터를 가져오는 훅.
  * @hook
  * @param {UseCctvCompanyDataParams} [params] 훅 파라미터
- * @property {string} [username] 사용자 계정 아이디 (Provider에서 주입된 기본값 대신 사용)
  * @property {string} [url] 회사 리스트 API URL (Provider에서 주입된 기본값 대신 사용)
  * @return {UseCctvCompanyDataReturn} 회사 리스트 쿼리 반환값
  * @desc
  * return {
- *   data, // 회사 리스트 API 응답 데이터
+ *   data, // common/cctvs 원본 API 응답 데이터
  *   isFetching, // 데이터 로딩 중 상태
  *   isError, // 데이터 로딩 에러 상태
  *   ...rest, // react-query useQuery 반환값
  * }
  */
-export default function useCctvCompanyData(params?: {
-  username?: string;
-  url?: string;
-}): UseCctvCompanyDataReturn {
-  // 외부에서 username/url을 덮어쓸 수 있도록 받고, 없으면 Provider 값을 사용한다.
-  const { username, url } = params || {};
+export default function useCctvCompanyData(
+  params?: UseCctvCompanyDataParams,
+): UseCctvCompanyDataReturn {
+  // 변경: list 조회 계약은 URL만 override 대상으로 유지한다.
+  const { url } = params || {};
 
   const { listUrl } = useCctvApiUrl();
   const resolvedUrl = useMemo(() => url ?? listUrl, [url, listUrl]);
-  const { username: contextUsername, setValue } = useCctvContext();
+  const { setValue } = useCctvContext();
 
-  // 사용자/URL에 맞춰 회사 리스트 API를 호출한다.
+  // URL에 맞춰 회사 리스트 API를 호출한다.
   const { data, isFetching, isError, ...rest } = useQueryCctvCompanyList({
-    username: username ?? contextUsername,
     url: resolvedUrl,
   });
 
   // 응답 데이터를 react-hook-form rawData 필드로 반영한다.
   useEffect(() => {
-    if (data?.data) {
-      setValue("rawData", data?.data);
+    if (data?.data?.items) {
+      // 변경: common/cctvs raw items를 template form data 계약에 맞게 재분류한다.
+      setValue("rawData", classifyGroups(data.data.items));
     }
   }, [data, setValue]);
 

package/src/cctv/types/api.ts

@@ -1,3 +1,4 @@
+import type { API_Res_Base } from "@uniai-fe/util-api";
 import type { UtilQueryBaseParams } from "@uniai-fe/util-functions";
 import type { NextRequest } from "next/server";
 
@@ -6,20 +7,25 @@ import type { NextRequest } from "next/server";
  * @property {string} domain API 요청 도메인(서버)
  * @property {string} routeUrl Next.js app/api 이하 경로 url
  * @property {string} [queryUrl] 백엔드 요청 url
- * @property {URLSearchParams} searchParams api 요청 search params
+ * @property {"me" | "all"} [scope] common/cctvs 조회 범위
  */
-export interface API_Req_GetCompanyListParams extends Omit<
-  UtilQueryBaseParams,
-  "queryUrl"
-> {
+export interface API_Req_GetCompanyListParams {
+  /**
+   * API 도메인
+   */
+  domain: string;
+  /**
+   * Next.js app/api 이하 경로 url
+   */
+  routeUrl: string;
   /**
    * 백엔드 요청 url
    */
   queryUrl?: string;
   /**
-   * api 요청 search params
+   * common/cctvs 조회 범위
    */
-  searchParams: URLSearchParams;
+  scope?: "me" | "all";
 }
 
 /**
@@ -115,15 +121,27 @@ export interface API_Res_CctvCompanyGroup {
 }
 
 /**
- * CCTV; API 업체 목록 조회 응답
- * @property {API_Res_CctvCompanyGroup[]} data
- * @property {number} total_count
+ * CCTV; common/cctvs 원본 응답 데이터
+ * @property {API_Res_CctvCompanyGroup[]} items 백엔드 원본 업체 그룹 목록
+ * @property {number} total_count 전체 업체 그룹 수
  */
-export interface API_Res_CctvCompany {
-  data: API_Res_CctvCompanyGroup[];
+export interface API_Res_CctvCompanyData {
+  /**
+   * 백엔드 원본 업체 그룹 목록
+   */
+  items: API_Res_CctvCompanyGroup[];
+  /**
+   * 전체 업체 그룹 수
+   */
   total_count: number;
 }
 
+/**
+ * CCTV; common/cctvs 원본 응답
+ * @typedef {API_Res_Base<API_Res_CctvCompanyData>} API_Res_CctvCompany
+ */
+export type API_Res_CctvCompany = API_Res_Base<API_Res_CctvCompanyData>;
+
 /**
  * CCTV; 실시간 스트리밍 토큰 요청 (Next.js API 요청)
  * @property {string} company_id 업체 id코드

package/src/cctv/types/hook.ts

@@ -92,14 +92,9 @@ export interface UseCctvRtcStreamReturn extends UseCctvRtcStreamState {
 
 /**
  * CCTV; useCctvCompanyData params
- * @property {string} [username] 사용자 계정 아이디
  * @property {string} [url] 업체 리스트 API URL
  */
 export interface UseCctvCompanyDataParams {
-  /**
-   * 사용자 계정 아이디
-   */
-  username?: string;
   /**
    * 업체 리스트 API URL
    */
@@ -108,7 +103,7 @@ export interface UseCctvCompanyDataParams {
 
 /**
  * CCTV; useCctvCompanyData return
- * @property {API_Res_CctvCompany | undefined} data 업체 리스트 API 응답 데이터
+ * @property {API_Res_CctvCompany | undefined} data common/cctvs 원본 API 응답 데이터
  * @property {boolean} isFetching 데이터 로딩 중 상태
  * @property {boolean} isError 데이터 로딩 에러 상태
  */

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;
 }