@uniai-fe/uds-templates 0.1.33 → 0.1.35

package/dist/styles.css

@@ -55,12 +55,12 @@
   rgba(0, 0, 0, 0.2) 100%
   );
   /* Live State */
-  --cctv-live-state-bg-active: var(--color-cool-gray-10);
-  --cctv-live-state-dot-active: var(--color-feedback-new);
-  --cctv-live-state-text-active: var(--color-common-99);
-  --cctv-live-state-bg-disabled: var(--color-cool-gray-55);
-  --cctv-live-state-dot-disabled: var(--color-border-strong);
-  --cctv-live-state-text-disabled: var(--color-label-disabled);
+  --cctv-live-state-bg-on: var(--color-cool-gray-10);
+  --cctv-live-state-dot-on: var(--color-feedback-new);
+  --cctv-live-state-text-on: var(--color-common-99);
+  --cctv-live-state-bg-off: var(--color-cool-gray-55);
+  --cctv-live-state-dot-off: var(--color-border-strong);
+  --cctv-live-state-text-off: var(--color-label-disabled);
   /* Error */
   --cctv-error-text-color: var(--color-label-disabled);
   --cctv-error-icon-color: var(--color-label-disabled);
@@ -1028,6 +1028,9 @@
   width: 100%;
   height: fit-content;
 }
+.cctv-video-overlay-header.empty {
+  height: calc(var(--font-heading-xsmall-size) * 1.5);
+}
 
 .cctv-video-overlay-header-upper,
 .cctv-video-overlay-header-lower {
@@ -1038,23 +1041,24 @@
 
 .cctv-video-live-state {
   --theme-badge-font-weight: 400;
+  --badge-fill-bg-color: var(--cctv-live-state-bg-off);
+  --badge-fill-label-color: var(--cctv-live-state-text-off);
   margin-right: 4px;
 }
+.cctv-video-live-state.on {
+  --badge-fill-bg-color: var(--cctv-live-state-bg-on);
+  --badge-fill-label-color: var(--cctv-live-state-text-on);
+}
+.cctv-video-live-state.on .cctv-video-live-state-dot {
+  background: var(--cctv-live-state-dot-on);
+}
 
 .cctv-video-live-state-dot {
   width: 4px;
   height: 4px;
   margin-right: 4px;
   border-radius: 4px;
-  background: var(--cctv-live-state-dot-active);
-}
-
-.cctv-video-live-state:where(.disabled) {
-  --badge-fill-bg-color: var(--cctv-live-state-bg-disabled);
-  --badge-fill-label-color: var(--cctv-live-state-text-disabled);
-}
-.cctv-video-live-state:where(.disabled) .cctv-video-live-state-dot {
-  background: var(--cctv-live-state-dot-disabled);
+  background: var(--cctv-live-state-dot-off);
 }
 
 .cctv-video-close-button {

package/package.json

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

package/src/cctv/apis/server.ts

@@ -163,12 +163,14 @@ export async function getServerCompanyList({
     // searchParams,
   };
 
-  if (!queryUrl && !username)
+  if (!queryUrl && !username) {
+    nextAPILog("GET", routeUrl, query_url, { searchParams });
     return {
       res: alternateResponse,
       ...API_OPTION,
       options: { status: 400, statusText: "유저 아이디를 확인할 수 없습니다." },
     };
+  }
 
   // 요청 URL 구성
   const url = generateBackendQueryUrl_GET({
@@ -242,6 +244,7 @@ export async function getServerCctvToken({
   };
 
   if (!reqBody || !reqBody.username || !reqBody.company_id || !reqBody.cam_id) {
+    nextAPILog("POST", routeUrl, query_url, { reqBody });
     return {
       res: alternateResponse,
       ...API_OPTION,
@@ -270,11 +273,10 @@ export async function getServerCctvToken({
     path,
   };
 
+  nextAPILog("POST", routeUrl, query_url, { bodyData });
+
   try {
-    const res = await fetchWithBody<
-      API_Req_CctvRtcTokenOrigin,
-      API_Res_CctvRtcToken
-    >({
+    const res = await fetchWithBody<string, API_Res_CctvRtcToken>({
       method: "POST",
       routeUrl,
       ...API_OPTION,
@@ -283,7 +285,7 @@ export async function getServerCctvToken({
         "Content-Type": "application/json",
         ...(headers || {}),
       },
-      bodyData,
+      body: JSON.stringify(bodyData),
       alternateResponse,
     });
 

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

@@ -1,45 +1,31 @@
+"use client";
+
 import clsx from "clsx";
-import type { CctvCompanyCameraList } from "../../types";
-import CCTVVideoContainer from "../video/Container";
-import CCTVVideoOverlayBody from "../video/overlay/body/Container";
-import CCTVVideoError from "../video/overlay/body/Error";
-import CCTVVideoOverlayContainer from "../video/overlay/Container";
-import CCTVVideoOverlayFooter from "../video/overlay/footer/Container";
-import CCTVVideoOverlayHeader from "../video/overlay/header/Container";
-import CCTVVideoContents from "../video/Video";
+import type { CctvCompanyCameraData } from "../../types";
 import { useCctvRtcStream } from "../../hooks";
 import { useMemo } from "react";
+import CCTVVideoTemplate from "../video/Template";
+import {
+  getOverlayMessage,
+  getIsLive,
+  getIsError,
+} from "../../utils/video-state";
 
 export default function CCTVCamListItem({
   className,
   ...cam
-}: { className?: string } & Omit<CctvCompanyCameraList, "renderKey">) {
-  const { videoRef, isTokenLoading, isTokenError, isStreaming, streamError } =
-    useCctvRtcStream({
-      cam,
-      companyId: cam.company_id,
-    });
-
-  const overlayMessage = (() => {
-    if (!cam.cam_online) return "CCTV 연결 오류";
-    if (isTokenLoading || isStreaming) return "스트림을 준비하고 있습니다.";
-    if (isTokenError) return "토큰을 발급하지 못했습니다.";
-    if (streamError) return streamError;
-    return null;
-  })();
+}: {
+  className?: string;
+} & CctvCompanyCameraData) {
+  const { videoRef, ...rtcCtx } = useCctvRtcStream({ cam });
 
-  const isError = useMemo(
-    () => !cam.cam_online || isTokenError || streamError,
-    [cam.cam_online, isTokenError, streamError],
+  const isLive = useMemo(() => getIsLive({ cam, ...rtcCtx }), [cam, rtcCtx]);
+  const isError = useMemo(() => getIsError({ cam, ...rtcCtx }), [cam, rtcCtx]);
+  const overlayMessage = useMemo(
+    () => getOverlayMessage({ cam, hasCamProp: true, ...rtcCtx }),
+    [cam, rtcCtx],
   );
 
-  const disabledLiveState = useMemo(() => {
-    if (!cam.cam_online) return true;
-    if (isTokenLoading || isTokenError) return true;
-    if (streamError) return true;
-    return false;
-  }, [cam.cam_online, isTokenLoading, isTokenError, streamError]);
-
   return (
     <li
       className={clsx(
@@ -49,23 +35,18 @@ export default function CCTVCamListItem({
         isError && "is-error",
       )}
     >
-      <CCTVVideoContainer>
-        <CCTVVideoContents ref={videoRef} muted />
-        <CCTVVideoOverlayContainer>
-          <CCTVVideoOverlayHeader
-            activeLiveState
-            activeTitle={false}
-            liveStateDisabled={disabledLiveState}
-            title={cam.cam_name}
-          />
-          <CCTVVideoOverlayBody className={isError ? "is-error" : undefined}>
-            {disabledLiveState ? (
-              <CCTVVideoError>{overlayMessage}</CCTVVideoError>
-            ) : null}
-          </CCTVVideoOverlayBody>
-          <CCTVVideoOverlayFooter activeTitle activeOpenButton cam={cam} />
-        </CCTVVideoOverlayContainer>
-      </CCTVVideoContainer>
+      <CCTVVideoTemplate
+        ref={videoRef}
+        className="cctv-cam-list-video-container"
+        headerOptions={{
+          activeLiveState: true,
+          activeTitle: false,
+          isLive,
+          title: cam.cam_name,
+        }}
+        footerOptions={{ activeTitle: true, activeOpenButton: true, cam }}
+        {...{ isError, overlayMessage, isLive }}
+      />
     </li>
   );
 }

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

@@ -1,48 +1,31 @@
 "use client";
 
 import clsx from "clsx";
-import CCTVVideoContainer from "../../video/Container";
-import CCTVVideoContents from "../../video/Video";
-import CCTVVideoOverlayContainer from "../../video/overlay/Container";
-import CCTVVideoOverlayFooter from "../../video/overlay/footer/Container";
-import CCTVVideoOverlayBody from "../../video/overlay/body/Container";
-import CCTVVideoError from "../../video/overlay/body/Error";
-import type { CctvCompanyCameraList } from "../../../types";
+import type { CctvCompanyCameraData } from "../../../types";
 import { useCallback, useMemo } from "react";
 import { useCctvRtcStream } from "../../../hooks";
-import CCTVVideoOverlayHeader from "../../video/overlay/header/Container";
+import CCTVVideoTemplate from "../../video/Template";
+import {
+  getOverlayMessage,
+  getIsLive,
+  getIsError,
+} from "../../../utils/video-state";
 
 export default function CCTVPaginationListItem({
   className,
   ...cam
 }: {
   className?: string;
-} & Omit<CctvCompanyCameraList, "renderKey">) {
-  const { videoRef, isTokenLoading, isTokenError, isStreaming, streamError } =
-    useCctvRtcStream({
-      cam,
-      companyId: cam.company_id,
-    });
+} & CctvCompanyCameraData) {
+  const { videoRef, ...rtcCtx } = useCctvRtcStream({ cam });
 
-  const overlayMessage = (() => {
-    if (!cam.cam_online) return "CCTV 연결 오류";
-    if (isTokenLoading || isStreaming) return "스트림을 준비하고 있습니다.";
-    if (isTokenError) return "토큰을 발급하지 못했습니다.";
-    if (streamError) return streamError;
-    return null;
-  })();
-
-  const isError = useMemo(
-    () => !cam.cam_online || isTokenError || streamError,
-    [cam.cam_online, isTokenError, streamError],
+  const isLive = useMemo(() => getIsLive({ cam, ...rtcCtx }), [cam, rtcCtx]);
+  const isError = useMemo(() => getIsError({ cam, ...rtcCtx }), [cam, rtcCtx]);
+  const overlayMessage = useMemo(
+    () => getOverlayMessage({ cam, hasCamProp: true, ...rtcCtx }),
+    [cam, rtcCtx],
   );
 
-  const disabledLiveState = useMemo(() => {
-    if (isTokenLoading || isTokenError) return true;
-    if (streamError) return true;
-    return false;
-  }, [isTokenLoading, isTokenError, streamError]);
-
   const handleSelect = useCallback(() => {
     if (typeof cam.onSelect === "function") cam.onSelect();
   }, [cam]);
@@ -63,18 +46,12 @@ export default function CCTVPaginationListItem({
         aria-pressed={cam.selected}
         aria-label={`${cam.cam_name} 선택`}
       >
-        <CCTVVideoContainer>
-          <CCTVVideoContents ref={videoRef} muted />
-          <CCTVVideoOverlayContainer>
-            <CCTVVideoOverlayHeader />
-            <CCTVVideoOverlayBody className={isError ? "is-error" : undefined}>
-              {disabledLiveState ? (
-                <CCTVVideoError>{overlayMessage}</CCTVVideoError>
-              ) : null}
-            </CCTVVideoOverlayBody>
-            <CCTVVideoOverlayFooter cam={cam} />
-          </CCTVVideoOverlayContainer>
-        </CCTVVideoContainer>
+        <CCTVVideoTemplate
+          ref={videoRef}
+          className="cctv-pagination-list-video-container"
+          footerOptions={{ cam }}
+          {...{ isError, overlayMessage, isLive }}
+        />
       </button>
     </li>
   );

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

@@ -0,0 +1,49 @@
+import { forwardRef } from "react";
+import CCTVVideoContainer from "./Container";
+import CCTVVideoContents from "./Video";
+import CCTVVideoOverlayContainer from "./overlay/Container";
+import CCTVVideoOverlayHeader from "./overlay/header/Container";
+import CCTVVideoOverlayBody from "./overlay/body/Container";
+import CCTVVideoError from "./overlay/body/Error";
+import CCTVVideoOverlayFooter from "./overlay/footer/Container";
+import type { CctvVideoTemplateProps } from "../../types/props";
+
+/**
+ * CCTV; Video Template
+ * @component
+ * @property {string} [className]
+ * @property {CctvVideoOverlayHeaderProps} [headerOptions]
+ * @property {CctvVideoOverlayFooterProps} [footerOptions]
+ * @property {boolean} [isError]
+ * @property {string | null} [overlayMessage]
+ * @property {boolean} [isLive]
+ * @property {React.Ref<HTMLVideoElement>} ref
+ */
+const CCTVVideoTemplate = forwardRef(
+  (
+    {
+      className,
+      headerOptions,
+      footerOptions,
+      isError,
+      isLive,
+      overlayMessage,
+    }: CctvVideoTemplateProps,
+    ref: React.Ref<HTMLVideoElement | null>,
+  ) => {
+    return (
+      <CCTVVideoContainer className={className}>
+        <CCTVVideoContents ref={ref} muted />
+        <CCTVVideoOverlayContainer>
+          <CCTVVideoOverlayHeader {...headerOptions} />
+          <CCTVVideoOverlayBody className={isError ? "is-error" : undefined}>
+            {!isLive ? <CCTVVideoError>{overlayMessage}</CCTVVideoError> : null}
+          </CCTVVideoOverlayBody>
+          <CCTVVideoOverlayFooter {...footerOptions} />
+        </CCTVVideoOverlayContainer>
+      </CCTVVideoContainer>
+    );
+  },
+);
+
+export default CCTVVideoTemplate;

package/src/cctv/components/video/overlay/footer/Container.tsx

@@ -1,19 +1,14 @@
 import clsx from "clsx";
 import CCTVVideoOpenButton from "./OpenButton";
 import CCTVVideoOverlayTitle from "../Title";
-import type { CctvCompanyCameraList } from "../../../../types";
+import type { CctvVideoOverlayFooterProps } from "../../../../types";
 
 export default function CCTVVideoOverlayFooter({
   className,
   activeTitle = true,
   activeOpenButton,
   cam,
-}: {
-  className?: string;
-  activeTitle?: boolean;
-  activeOpenButton?: boolean;
-  cam?: Omit<CctvCompanyCameraList, "renderKey">;
-}) {
+}: CctvVideoOverlayFooterProps) {
   // console.log(cam);
   return (
     <footer className={clsx("cctv-video-overlay-footer", className)}>

package/src/cctv/components/video/overlay/footer/OpenButton.tsx

@@ -2,11 +2,9 @@
 
 import { useCallback } from "react";
 import ViewerOpenIcon from "../../../../img/viewer-open.svg";
-import type { CctvCompanyCameraList } from "../../../../types";
+import type { CctvCompanyCameraData } from "../../../../types";
 
-export default function CCTVVideoOpenButton({
-  ...cam
-}: Omit<CctvCompanyCameraList, "renderKey">) {
+export default function CCTVVideoOpenButton({ ...cam }: CctvCompanyCameraData) {
   const onOpen = useCallback(() => {
     if (typeof cam.onSelect === "function") cam.onSelect();
   }, [cam]);

package/src/cctv/components/video/overlay/header/Container.tsx

@@ -2,6 +2,7 @@ import clsx from "clsx";
 import CCTVVideoLiveState from "./LiveState";
 import CCTVVideoCloseButton from "./CloseButton";
 import CCTVVideoOverlayTitle from "../Title";
+import type { CctvVideoOverlayHeaderProps } from "../../../../types/props";
 
 export default function CCTVVideoOverlayHeader({
   className,
@@ -9,29 +10,20 @@ export default function CCTVVideoOverlayHeader({
   activeCloseButton,
   activeTitle,
   title,
-  activeTime,
-  liveStateDisabled,
-}: {
-  className?: string;
-  activeLiveState?: boolean;
-  activeCloseButton?: boolean;
-  activeTitle?: boolean;
-  title?: React.ReactNode;
-  activeTime?: boolean;
-  liveStateDisabled?: boolean;
-}) {
+  isLive,
+}: CctvVideoOverlayHeaderProps) {
   const showUpper = activeLiveState || activeCloseButton;
-  const showLower = activeTitle || activeTime;
-
-  if (!showUpper && !showLower) return null;
+  const showLower = activeTitle;
 
   return (
-    <header className={clsx("cctv-video-overlay-header", className)}>
+    <header
+      className={clsx("cctv-video-overlay-header", className, {
+        empty: !showUpper && !showLower,
+      })}
+    >
       {showUpper && (
         <div className="cctv-video-overlay-header-upper">
-          {activeLiveState && (
-            <CCTVVideoLiveState disabled={liveStateDisabled} />
-          )}
+          {activeLiveState && <CCTVVideoLiveState isLive={isLive} />}
           {activeCloseButton && <CCTVVideoCloseButton />}
         </div>
       )}

package/src/cctv/components/video/overlay/header/LiveState.tsx

@@ -4,15 +4,15 @@ import clsx from "clsx";
 import { Badge } from "@uniai-fe/uds-primitives";
 
 export default function CCTVVideoLiveState({
-  disabled = false,
+  isLive = false,
 }: {
-  disabled?: boolean;
+  isLive?: boolean;
 }) {
   return (
     <Badge
       size="xsmall"
       intent="tertiary"
-      className={clsx("cctv-video-live-state", { disabled })}
+      className={clsx("cctv-video-live-state", { on: isLive == true })}
     >
       <figure className="cctv-video-live-state-dot"></figure>
       <span>Live</span>

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

@@ -2,7 +2,10 @@ import clsx from "clsx";
 import CCTVViewerContainer from "../Container";
 import CCTVViewerDesktopPagination from "./Pagination";
 import CCTVViewerDesktopVideo from "./Video";
-import type { CctvCompanyCameraList } from "../../../types";
+import type {
+  CctvCompanyCameraData,
+  CctvCompanyCameraList,
+} from "../../../types";
 
 export default function CCTVViewerDesktopContainer({
   className,
@@ -12,7 +15,7 @@ export default function CCTVViewerDesktopContainer({
 }: {
   className?: string;
   children?: React.ReactNode;
-  selectedCam?: Omit<CctvCompanyCameraList, "renderKey">;
+  selectedCam?: CctvCompanyCameraData;
   camList?: CctvCompanyCameraList[];
 }) {
   return (

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

@@ -3,81 +3,49 @@
 import { useMemo } from "react";
 
 import { useCctvContext, useCctvRtcStream } from "../../../hooks";
-import CCTVVideoContainer from "../../video/Container";
-import CCTVVideoOverlayBody from "../../video/overlay/body/Container";
-import CCTVVideoError from "../../video/overlay/body/Error";
-import CCTVVideoOverlayContainer from "../../video/overlay/Container";
-import CCTVVideoOverlayFooter from "../../video/overlay/footer/Container";
-import CCTVVideoOverlayHeader from "../../video/overlay/header/Container";
-import CCTVVideoContents from "../../video/Video";
-import CCTVViewerDesktopPlaceholder from "./Placeholder";
-import type { CctvCompanyCameraList } from "../../../types";
+import type { CctvCompanyCameraData } from "../../../types";
+import CCTVVideoTemplate from "../../video/Template";
+import {
+  getOverlayMessage,
+  getIsLive,
+  getIsError,
+} from "../../../utils/video-state";
 
 export default function CCTVViewerDesktopVideo({
-  cam,
+  cam: propsCam,
 }: {
-  cam?: Omit<CctvCompanyCameraList, "renderKey">;
+  cam?: CctvCompanyCameraData;
 }) {
-  const { selectedCam, selectedCompany, selectedCompanyId, isFetching } =
-    useCctvContext();
+  const { selectedCam, isFetching } = useCctvContext();
 
   // props의 cam이 들어오면 우선 적용
   // cam이 부여되어있으면 selectedCam 무시
   // cam이 없다면 selectedCam 적용
-  const camData = useMemo(() => cam ?? selectedCam, [cam, selectedCam]);
-  // console.log("CCTVViewerDesktopVideo camData:", camData);
+  const cam = useMemo(() => propsCam ?? selectedCam, [propsCam, selectedCam]);
 
-  const isCamOffline = useMemo(() => !camData?.cam_online, [camData]);
+  const { videoRef, ...rtcCtx } = useCctvRtcStream({ cam });
 
-  const activeCompanyId =
-    camData?.company_id ?? selectedCompany?.company_id ?? selectedCompanyId;
-
-  const { videoRef, isTokenLoading, isTokenError, isStreaming, streamError } =
-    useCctvRtcStream({
-      cam: camData,
-      companyId: activeCompanyId,
-    });
-
-  const overlayMessage = useMemo(() => {
-    if (!camData) return null;
-    if (!camData.cam_online) return "CCTV 연결 오류";
-    if (isTokenLoading || isStreaming) return "스트림을 준비하고 있습니다.";
-    if (isTokenError) return "토큰을 발급하지 못했습니다.";
-    if (streamError) return streamError;
-    return null;
-  }, [camData, isTokenError, isTokenLoading, isStreaming, streamError]);
-
-  if (!cam && isFetching && !camData) {
-    return (
-      <CCTVViewerDesktopPlaceholder message="CCTV 데이터를 불러오는 중입니다." />
-    );
-  }
-
-  if (!camData && !cam) {
-    return (
-      <CCTVViewerDesktopPlaceholder message="좌측 목록에서 카메라를 선택하세요." />
-    );
-  }
+  const isLive = useMemo(() => getIsLive({ cam, ...rtcCtx }), [cam, rtcCtx]);
+  const isError = useMemo(() => getIsError({ cam, ...rtcCtx }), [cam, rtcCtx]);
+  const overlayMessage = useMemo(
+    () =>
+      getOverlayMessage({ cam, hasCamProp: !!propsCam, isFetching, ...rtcCtx }),
+    [propsCam, cam, isFetching, rtcCtx],
+  );
 
   return (
-    <CCTVVideoContainer className="cctv-viewer-desktop-video-container">
-      <CCTVVideoContents ref={videoRef} />
-      <CCTVVideoOverlayContainer>
-        <CCTVVideoOverlayHeader
-          activeLiveState
-          activeTitle
-          activeCloseButton
-          liveStateDisabled={isCamOffline}
-        />
-        {overlayMessage ? (
-          <CCTVVideoOverlayBody
-            className={isCamOffline ? "is-error" : undefined}
-          >
-            {isCamOffline ? <CCTVVideoError /> : overlayMessage}
-          </CCTVVideoOverlayBody>
-        ) : null}
-        <CCTVVideoOverlayFooter activeTitle={false} />
-      </CCTVVideoOverlayContainer>
-    </CCTVVideoContainer>
+    <CCTVVideoTemplate
+      ref={videoRef}
+      className="cctv-viewer-desktop-video-container"
+      headerOptions={{
+        activeLiveState: true,
+        activeTitle: true,
+        activeCloseButton: true,
+        isLive,
+        title: cam?.cam_name,
+      }}
+      footerOptions={{ activeTitle: false }}
+      {...{ isError, overlayMessage, isLive }}
+    />
   );
 }

package/src/cctv/hooks/useCompanyData.tsx

@@ -4,28 +4,48 @@ import { useEffect, useMemo } from "react";
 import { useQueryCctvCompanyList } from "../apis";
 import { useCctvApiUrl } from "../components/Provider";
 import useCctvContext from "./useContext";
-
+import type { 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 응답 데이터
+ *   isFetching, // 데이터 로딩 중 상태
+ *   isError, // 데이터 로딩 에러 상태
+ *   ...rest, // react-query useQuery 반환값
+ * }
+ */
 export default function useCctvCompanyData(params?: {
   username?: string;
   url?: string;
-}) {
+}): UseCctvCompanyDataReturn {
+  // 외부에서 username/url을 덮어쓸 수 있도록 받고, 없으면 Provider 값을 사용한다.
   const { username, url } = params || {};
 
   const { listUrl } = useCctvApiUrl();
   const resolvedUrl = useMemo(() => url ?? listUrl, [url, listUrl]);
   const { username: contextUsername, setValue } = useCctvContext();
 
+  // 사용자/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);
     }
   }, [data, setValue]);
 
+  // 로딩/에러 상태를 form state로도 전달해 다른 훅에서 활용할 수 있게 한다.
   useEffect(() => {
     setValue("isFetching", Boolean(isFetching));
   }, [isFetching, setValue]);
@@ -34,5 +54,10 @@ export default function useCctvCompanyData(params?: {
     setValue("isError", Boolean(isError));
   }, [isError, setValue]);
 
-  return { data, isFetching, isError, ...rest };
+  return {
+    data,
+    isFetching,
+    isError: Boolean(isError),
+    ...rest,
+  };
 }