@uniai-fe/uds-templates 0.10.4 → 0.11.1

package/dist/styles.css

@@ -93,9 +93,16 @@
   /* Card layout */
   --cctv-video-radius: 12px;
   --cctv-list-gap: var(--spacing-gap-5);
-  --cctv-list-item-min-width: 320px;
+  --cctv-list-item-min-width: 300px;
   --cctv-overlay-padding-x: var(--spacing-padding-8);
   --cctv-overlay-padding-y: var(--spacing-padding-6);
+  --cctv-viewer-video-radius: 16px;
+  --cctv-viewer-video-max-height: 618px;
+  --cctv-viewer-overlay-padding-x: var(--spacing-padding-11);
+  --cctv-viewer-overlay-padding-y: var(--spacing-padding-9);
+  --cctv-card-settings-bg: var(--color-common-99);
+  --cctv-card-settings-border: var(--color-border-assistive);
+  --cctv-card-height: 240px;
   --cctv-video-bg: var(--color-surface-heavy);
   --cctv-overlay-bg: linear-gradient(
     180deg,
@@ -109,12 +116,20 @@
   --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);
+  --cctv-state-dot-size: var(--spacing-gap-3);
+  /* Sensor metric */
+  --cctv-metric-bg: rgba(0, 0, 0, 0.55);
+  --cctv-metric-text: var(--color-common-99);
+  --cctv-metric-dot-normal: var(--color-feedback-success);
+  --cctv-metric-dot-attention: var(--color-feedback-new);
+  --cctv-metric-dot-unavailable: var(--color-border-strong);
   /* Error */
   --cctv-status-text-color: var(--color-common-99);
   --cctv-error-text-color: var(--color-label-disabled);
   --cctv-error-icon-color: var(--color-label-disabled);
   /* Pagination */
   --cctv-carousel-gap: var(--spacing-gap-5);
+  --cctv-pagination-item-width: 170px;
   --cctv-pagination-move-button-size: 48px;
   --cctv-pagination-move-button-active: var(--color-cool-gray-20);
   --cctv-pagination-move-button-disabled: var(--color-cool-gray-85);
@@ -1743,6 +1758,59 @@
   visibility: hidden;
 }
 
+.cctv-video-container[data-layout="card"] {
+  min-height: 0;
+  max-height: 240px;
+  aspect-ratio: 16/9;
+}
+
+.cctv-video-container[data-layout="carousel"] {
+  min-height: 0;
+  aspect-ratio: 16/9;
+}
+
+.cctv-video-card {
+  overflow: hidden;
+  border-radius: var(--cctv-video-radius);
+}
+
+.cctv-video-card[data-has-settings="true"] {
+  height: var(--cctv-card-height);
+  display: flex;
+  flex-direction: column;
+}
+.cctv-video-card[data-has-settings="true"] .cctv-video-card-media {
+  min-height: 0;
+  flex: 1;
+}
+.cctv-video-card[data-has-settings="true"]
+  .cctv-video-card-media
+  .cctv-video-container {
+  height: 100%;
+  min-height: 0;
+  aspect-ratio: auto;
+}
+.cctv-video-card[data-has-settings="true"]
+  .cctv-video-card-media
+  .cctv-video-container,
+.cctv-video-card[data-has-settings="true"]
+  .cctv-video-card-media
+  .cctv-video-box
+  video,
+.cctv-video-card[data-has-settings="true"]
+  .cctv-video-card-media
+  .cctv-video-overlay-container {
+  border-bottom-right-radius: 0;
+  border-bottom-left-radius: 0;
+}
+
+.cctv-video-card-settings {
+  flex: 0 0 auto;
+  padding: var(--spacing-padding-6) var(--spacing-padding-8);
+  background: var(--cctv-card-settings-bg);
+  box-shadow: inset 0 0 0 1px var(--cctv-card-settings-border);
+}
+
 .cctv-video-box {
   width: 100%;
   height: 100%;
@@ -1771,6 +1839,9 @@
 .cctv-video-overlay-header {
   width: 100%;
   height: fit-content;
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-gap-5);
 }
 .cctv-video-overlay-header.empty {
   height: calc(var(--font-heading-xsmall-size) * 1.5);
@@ -1799,10 +1870,10 @@
 }
 
 .cctv-video-live-state-dot {
-  width: 4px;
-  height: 4px;
-  margin-right: 4px;
-  border-radius: 4px;
+  width: var(--cctv-state-dot-size);
+  height: var(--cctv-state-dot-size);
+  margin-right: var(--spacing-gap-3);
+  border-radius: var(--cctv-state-dot-size);
   background: var(--cctv-live-state-dot-off);
 }
 
@@ -1836,7 +1907,7 @@
 }
 
 .cctv-video-header-title {
-  font-size: var(--font-heading-large-size);
+  font-size: var(--font-heading-medium-size);
 }
 
 .cctv-video-footer-title {
@@ -1917,12 +1988,52 @@
   margin-top: auto;
 }
 
+.cctv-video-metrics {
+  display: flex;
+  gap: var(--spacing-gap-4);
+  margin-left: auto;
+}
+
+.cctv-video-metric {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--spacing-gap-3);
+  padding: var(--spacing-padding-2) var(--spacing-padding-5);
+  border-radius: 999px;
+  color: var(--cctv-metric-text);
+  background: var(--cctv-metric-bg);
+  font-size: var(--font-label-small-size);
+  line-height: var(--font-label-small-line-height);
+  font-weight: var(--font-label-small-weight);
+  white-space: nowrap;
+}
+
+.cctv-video-metric-dot {
+  width: var(--cctv-state-dot-size);
+  height: var(--cctv-state-dot-size);
+  flex: 0 0 var(--cctv-state-dot-size);
+  border-radius: var(--cctv-state-dot-size);
+  background: var(--cctv-metric-dot-normal);
+}
+
+.cctv-video-metric[data-state="attention"] .cctv-video-metric-dot {
+  background: var(--cctv-metric-dot-attention);
+}
+
+.cctv-video-metric[data-state="unavailable"] .cctv-video-metric-dot {
+  background: var(--cctv-metric-dot-unavailable);
+}
+
 .cctv-video-open-button {
   flex: 0 0 auto;
   display: flex;
   align-items: center;
   justify-content: center;
   cursor: auto;
+  position: absolute;
+  top: var(--cctv-overlay-padding-y);
+  right: var(--cctv-overlay-padding-x);
+  z-index: 2;
 }
 .cctv-video-open-button svg path {
   stroke: var(--cctv-open-button-color-off);
@@ -1965,29 +2076,11 @@
 }
 
 .cctv-cam-list-item .cctv-video-container {
+  min-height: 0;
   max-height: 240px;
+  aspect-ratio: 16/9;
 }
 
-@container cctv-cam-list (min-width: 652px) {
-  .cctv-cam-list-track {
-    grid-template-columns: repeat(2, minmax(0, 1fr));
-  }
-}
-@container cctv-cam-list (min-width: 984px) {
-  .cctv-cam-list-track {
-    grid-template-columns: repeat(3, minmax(0, 1fr));
-  }
-}
-@container cctv-cam-list (min-width: 1316px) {
-  .cctv-cam-list-track {
-    grid-template-columns: repeat(4, minmax(0, 1fr));
-  }
-}
-@container cctv-cam-list (min-width: 1648px) {
-  .cctv-cam-list-track {
-    grid-template-columns: repeat(5, minmax(0, 1fr));
-  }
-}
 .cctv-pagination-container {
   width: 100%;
   display: flex;
@@ -2027,7 +2120,7 @@
 }
 
 .cctv-pagination-track > li {
-  flex: 0 0 minmax(150px, 1fr);
+  flex: 0 0 var(--cctv-pagination-item-width);
 }
 
 .cctv-pagination-list-item {
@@ -2035,6 +2128,7 @@
 }
 
 .cctv-pagination-list-item .cctv-video-container {
+  min-height: 0;
   max-height: 152px;
 }
 
@@ -2060,12 +2154,81 @@
   background: var(--cctv-pagination-move-button-disabled);
 }
 
+.cctv-viewer-desktop-container {
+  display: grid;
+  gap: var(--spacing-gap-6);
+  width: min(100%, 1216px);
+  margin: 0 auto;
+}
+
+.cctv-viewer-desktop-headline {
+  min-height: 34px;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--spacing-gap-6);
+}
+.cctv-viewer-desktop-headline h3 {
+  min-width: 0;
+  margin: 0;
+  overflow: hidden;
+  color: var(--color-label-strong);
+  font-size: var(--font-heading-medium-size);
+  line-height: 1.4;
+  font-weight: 700;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.cctv-viewer-desktop-time {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--spacing-gap-3);
+  color: var(--color-label-neutral);
+  font-size: var(--font-label-small-size);
+  line-height: var(--font-label-small-line-height);
+  font-weight: var(--font-label-small-weight);
+  white-space: nowrap;
+}
+
 .cctv-viewer-desktop-video-container {
-  max-height: 500px;
+  --cctv-video-radius: var(--cctv-viewer-video-radius);
+  --cctv-overlay-padding-x: var(--cctv-viewer-overlay-padding-x);
+  --cctv-overlay-padding-y: var(--cctv-viewer-overlay-padding-y);
+  max-height: var(--cctv-viewer-video-max-height);
+  min-height: 0;
+  aspect-ratio: 608/309;
+}
+
+.cctv-viewer-desktop-overlay-body {
+  flex-direction: row;
+  justify-content: space-between;
+}
+
+.cctv-viewer-desktop-move-button.cctv-pagination-move-button {
+  width: 42px;
+  height: 42px;
+  background: var(--cctv-pagination-move-button-active);
+}
+
+.cctv-viewer-desktop-video-container .cctv-video-overlay-footer {
+  justify-content: flex-end;
+}
+
+.cctv-visually-hidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
 }
 
 .cctv-viewer-desktop-pagination-container {
-  margin-top: var(--spacing-gap-8);
+  margin-top: var(--spacing-gap-2);
 }
 
 .service-inquiry-form {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniai-fe/uds-templates",
-  "version": "0.10.4",
+  "version": "0.11.1",
   "description": "UNIAI Design System; UI Templates Package",
   "type": "module",
   "private": false,
@@ -56,28 +56,28 @@
   },
   "devDependencies": {
     "@svgr/webpack": "^8.1.0",
-    "@tanstack/react-query": "^5.101.2",
-    "@types/node": "^24.13.2",
+    "@tanstack/react-query": "^5.101.4",
+    "@types/node": "^24.13.3",
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
-    "eslint": "^9.39.4",
+    "eslint": "^9.39.5",
     "jotai": "^2.20.2",
     "next": "16.2.10",
-    "prettier": "^3.8.5",
-    "react-hook-form": "^7.81.0",
-    "sass": "^1.101.0",
+    "prettier": "^3.9.6",
+    "react-hook-form": "^7.82.0",
+    "sass": "^1.101.3",
     "typescript": "6.0.3",
+    "@uniai-fe/react-hooks": "0.3.0",
+    "@uniai-fe/eslint-config": "0.4.2",
     "@uniai-fe/next-devkit": "0.4.0",
-    "@uniai-fe/eslint-config": "0.4.1",
     "@uniai-fe/tsconfig": "0.2.0",
-    "@uniai-fe/react-hooks": "0.3.0",
-    "@uniai-fe/util-api": "0.2.1",
-    "@uniai-fe/uds-primitives": "0.10.0",
-    "@uniai-fe/util-functions": "0.4.3",
+    "@uniai-fe/uds-primitives": "0.10.2",
     "@uniai-fe/util-jotai": "0.3.0",
-    "@uniai-fe/util-rtc": "0.2.1",
     "@uniai-fe/uds-foundation": "0.5.0",
-    "@uniai-fe/util-next": "0.5.0"
+    "@uniai-fe/util-next": "0.5.0",
+    "@uniai-fe/util-functions": "0.4.3",
+    "@uniai-fe/util-api": "0.2.1",
+    "@uniai-fe/util-rtc": "0.2.1"
   },
   "scripts": {
     "check:pre-commit": "pnpm --dir ../../.. run check:pre-commit",

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

@@ -50,15 +50,16 @@ export default function CCTVCamListItem({
         ref={videoRef}
         cam={cam}
         className="cctv-cam-list-video-container"
-        // list card에서는 live/share 상태를 header에 노출하고 제목은 footer로 내려 보낸다.
+        layout="card"
+        // list card에서는 live/share 상태와 제목을 header에 함께 노출한다.
         headerOptions={{
           activeLiveState: true,
-          activeTitle: false,
+          activeTitle: true,
           isLive,
           isShared: cam.is_public === true,
           title: cam.cam_name,
         }}
-        footerOptions={{ activeTitle: true, activeOpenButton: true, cam }}
+        footerOptions={{ activeTitle: false, activeOpenButton: true, cam }}
         // 변경 설명: list item custom overlay는 template seam 하나만 따라간다.
         renderOverlay={renderOverlay}
         {...{

package/src/cctv/components/pagination/Provider.tsx

@@ -84,8 +84,9 @@ export function CctvPaginationCarouselProvider({
   const scrollToIndex = useCallback((index: number) => {
     if (!viewportRef.current || !trackRef.current) return;
     const panel = trackRef.current.children[index] as HTMLElement | undefined;
+    const firstPanel = trackRef.current.children[0] as HTMLElement | undefined;
     if (!panel) return;
-    const targetLeft = panel.offsetLeft;
+    const targetLeft = panel.offsetLeft - (firstPanel?.offsetLeft ?? 0);
     const currentLeft = viewportRef.current.scrollLeft;
     if (Math.abs(currentLeft - targetLeft) < 1) {
       setCurrentIndex(index);
@@ -136,11 +137,14 @@ export function CctvPaginationCarouselProvider({
         const { scrollLeft } = viewport;
         const panels = trackRef.current?.children ?? [];
         if (!panels.length) return;
+        const firstOffset = (panels[0] as HTMLElement).offsetLeft;
         let closestIndex = 0;
         let smallestDistance = Number.POSITIVE_INFINITY;
         for (let i = 0; i < panels.length; i += 1) {
           const panel = panels[i] as HTMLElement;
-          const distance = Math.abs(panel.offsetLeft - scrollLeft);
+          const distance = Math.abs(
+            panel.offsetLeft - firstOffset - scrollLeft,
+          );
           if (distance < smallestDistance) {
             smallestDistance = distance;
             closestIndex = i;

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

@@ -67,6 +67,7 @@ export default function CCTVPaginationListItem({
           ref={videoRef}
           cam={cam}
           className="cctv-pagination-list-video-container"
+          layout="carousel"
           // thumbnail에서는 header live/share 상태만 보이고 footer action은 최소화한다.
           headerOptions={{
             activeLiveState: true,

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

@@ -0,0 +1,30 @@
+import clsx from "clsx";
+import type { CctvVideoCardProps } from "../../types";
+
+/**
+ * CCTV; service settings를 결합하는 video card
+ * @component
+ * @param {CctvVideoCardProps} props
+ * @param {React.ReactNode} props.children video/media 영역
+ * @param {React.ReactNode} [props.settings] media 하단 서비스 설정 영역
+ * @param {string} [props.className] 카드 루트 클래스
+ * @example
+ * <CCTV.Video.Card settings={<Controls />}><CCTV.Video.Template /></CCTV.Video.Card>
+ */
+export default function CCTVVideoCard({
+  children,
+  className,
+  settings,
+}: CctvVideoCardProps) {
+  return (
+    <section
+      className={clsx("cctv-video-card", className)}
+      data-has-settings={typeof settings !== "undefined" ? "true" : undefined}
+    >
+      <div className="cctv-video-card-media">{children}</div>
+      {typeof settings !== "undefined" ? (
+        <div className="cctv-video-card-settings">{settings}</div>
+      ) : null}
+    </section>
+  );
+}

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

@@ -4,15 +4,18 @@ export default function CCTVVideoContainer({
   className,
   children,
   isError,
+  layout,
 }: {
   className?: string;
   children: React.ReactNode;
   isError?: boolean;
+  layout?: "card" | "carousel" | "viewer";
 }) {
   return (
     <div
       className={clsx("cctv-video-container", className)}
       data-error={isError ? "true" : undefined}
+      data-layout={layout}
     >
       {children}
     </div>

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

@@ -33,6 +33,7 @@ const CCTVVideoTemplate = forwardRef<HTMLVideoElement, CctvVideoTemplateProps>(
       footerOptions,
       isError,
       isLive,
+      layout,
       overlayMessage,
       streamStage,
       canReconnect,
@@ -69,7 +70,11 @@ const CCTVVideoTemplate = forwardRef<HTMLVideoElement, CctvVideoTemplateProps>(
         : defaultOverlay;
 
     return (
-      <CCTVVideoContainer className={className} isError={isError}>
+      <CCTVVideoContainer
+        className={className}
+        isError={isError}
+        layout={layout}
+      >
         <CCTVVideoContents ref={ref} muted />
         {overlayNode}
       </CCTVVideoContainer>

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

@@ -2,10 +2,12 @@ import CCTVVideoContainer from "./Container";
 import { CCTVVideoOverlay } from "./overlay";
 import CCTVVideoTemplate from "./Template";
 import CCTVVideoContents from "./Video";
+import CCTVVideoCard from "./Card";
 
 export const CCTVVideo = {
   Container: CCTVVideoContainer,
   Contents: CCTVVideoContents,
+  Card: CCTVVideoCard,
   Template: CCTVVideoTemplate,
   Overlay: CCTVVideoOverlay,
 };

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

@@ -5,6 +5,7 @@ import type { CctvVideoOverlayFooterProps } from "../../../../types";
 
 export default function CCTVVideoOverlayFooter({
   className,
+  children,
   activeTitle = true,
   activeOpenButton,
   cam,
@@ -23,6 +24,7 @@ export default function CCTVVideoOverlayFooter({
       {activeOpenButton && cam && (
         <CCTVVideoOpenButton {...cam} isLive={isLive} />
       )}
+      {children}
     </footer>
   );
 }

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

@@ -0,0 +1,22 @@
+import type { CctvVideoMetricProps } from "../../../../types";
+
+/**
+ * CCTV; state dot을 포함한 sensor metric
+ * @component
+ * @param {CctvVideoMetricProps} props
+ * @param {React.ReactNode} props.children 표시할 센서 값
+ * @param {"normal" | "attention" | "unavailable"} [props.state="normal"] state dot 표시 상태
+ * @example
+ * <CCTV.Video.Overlay.Footer.Metric state="attention">온도 38℃</CCTV.Video.Overlay.Footer.Metric>
+ */
+export default function CCTVVideoMetric({
+  children,
+  state = "normal",
+}: CctvVideoMetricProps) {
+  return (
+    <span className="cctv-video-metric" data-state={state}>
+      <span className="cctv-video-metric-dot" aria-hidden="true" />
+      <span>{children}</span>
+    </span>
+  );
+}

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

@@ -0,0 +1,13 @@
+/**
+ * CCTV; sensor metric group
+ * @component
+ * @param {object} props
+ * @param {React.ReactNode} props.children sensor metric 목록
+ */
+export default function CCTVVideoMetrics({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return <div className="cctv-video-metrics">{children}</div>;
+}

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

@@ -21,7 +21,7 @@ export default function CCTVVideoLiveState({
       {...options}
     >
       <figure className="cctv-video-live-state-dot"></figure>
-      <span>{isShared ? "외부공유중" : "Live"}</span>
+      <span>{isShared ? "외부 공유" : "Live"}</span>
     </Badge>
   );
 }

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

@@ -3,6 +3,8 @@ import CCTVVideoError from "./body/Error";
 import CCTVVideoOverlayContainer from "./Container";
 import CCTVVideoOverlayFooter from "./footer/Container";
 import CCTVVideoOpenButton from "./footer/OpenButton";
+import CCTVVideoMetric from "./footer/Metric";
+import CCTVVideoMetrics from "./footer/Metrics";
 import CCTVVideoCloseButton from "./header/CloseButton";
 import CCTVVideoOverlayHeader from "./header/Container";
 import CCTVVideoLiveState from "./header/LiveState";
@@ -20,5 +22,7 @@ export const CCTVVideoOverlay = {
   Footer: {
     Container: CCTVVideoOverlayFooter,
     OpenButton: CCTVVideoOpenButton,
+    Metric: CCTVVideoMetric,
+    Metrics: CCTVVideoMetrics,
   },
 };

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

@@ -1,8 +1,12 @@
+"use client";
+
 import clsx from "clsx";
 import CCTVViewerContainer from "../Container";
 import CCTVViewerDesktopPagination from "./Pagination";
 import CCTVViewerDesktopVideo from "./Video";
+import CCTVViewerDesktopHeadline from "./Headline";
 import type { CctvViewerDesktopContainerProps } from "../../../types";
+import { useCctvContext } from "../../../hooks";
 
 /**
  * CCTV; viewer desktop container
@@ -21,8 +25,27 @@ export default function CCTVViewerDesktopContainer({
   children,
   selectedCam,
   camList,
+  metrics,
+  onNext,
+  onPrev,
   renderOverlay,
+  time,
 }: CctvViewerDesktopContainerProps) {
+  const context = useCctvContext();
+  const resolvedCam = selectedCam ?? context.selectedCam;
+  const resolvedList = camList ?? context.cams;
+  const currentIndex = resolvedList.findIndex(
+    cam => cam.cam_id === resolvedCam?.cam_id,
+  );
+  const resolvedPrev =
+    onPrev ??
+    (currentIndex > 0 ? resolvedList[currentIndex - 1]?.onSelect : undefined);
+  const resolvedNext =
+    onNext ??
+    (currentIndex >= 0 && currentIndex < resolvedList.length - 1
+      ? resolvedList[currentIndex + 1]?.onSelect
+      : undefined);
+
   return (
     <CCTVViewerContainer
       className={clsx("cctv-viewer-desktop-container", className)}
@@ -31,15 +54,23 @@ export default function CCTVViewerDesktopContainer({
         children
       ) : (
         <>
+          <CCTVViewerDesktopHeadline
+            title={resolvedCam?.cam_name ?? "-"}
+            time={time}
+          />
           <CCTVViewerDesktopVideo
-            {...(typeof selectedCam !== "undefined"
-              ? { cam: selectedCam }
+            {...(typeof resolvedCam !== "undefined"
+              ? { cam: resolvedCam }
               : {})}
-            // 변경 설명: container에서 받은 seam을 main viewer video로 전달한다.
+            metrics={metrics}
+            onNext={resolvedNext}
+            onPrev={resolvedPrev}
             renderOverlay={renderOverlay}
           />
           <CCTVViewerDesktopPagination
-            {...(typeof camList !== "undefined" ? { list: camList } : {})}
+            {...(typeof resolvedList !== "undefined"
+              ? { list: resolvedList }
+              : {})}
           />
         </>
       )}

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

@@ -0,0 +1,28 @@
+import ClockIcon from "../../../img/time.svg";
+
+/**
+ * CCTV; desktop viewer headline
+ * @component
+ * @param {object} props
+ * @param {React.ReactNode} props.title 선택 카메라 제목
+ * @param {React.ReactNode} [props.time] 확인 시각
+ */
+export default function CCTVViewerDesktopHeadline({
+  title,
+  time,
+}: {
+  title: React.ReactNode;
+  time?: React.ReactNode;
+}) {
+  return (
+    <header className="cctv-viewer-desktop-headline">
+      <h3>{title}</h3>
+      {typeof time !== "undefined" ? (
+        <time className="cctv-viewer-desktop-time">
+          <ClockIcon width={16} height={16} aria-hidden="true" />
+          <span>{time}</span>
+        </time>
+      ) : null}
+    </header>
+  );
+}

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

@@ -0,0 +1,60 @@
+import CCTVPaginationBaseButton from "../../pagination/buttons/Base";
+import CCTVVideoOverlayContainer from "../../video/overlay/Container";
+import CCTVVideoOverlayBody from "../../video/overlay/body/Container";
+import CCTVVideoOverlayFooter from "../../video/overlay/footer/Container";
+import CCTVVideoOverlayHeader from "../../video/overlay/header/Container";
+
+/**
+ * CCTV; desktop viewer video overlay preset
+ * @component
+ * @param {object} props
+ * @param {boolean} [props.isLive] 영상 live 상태
+ * @param {boolean} [props.isShared] 외부 공유 상태
+ * @param {React.ReactNode} [props.metrics] sensor metric 영역
+ * @param {() => void} [props.onPrev] 이전 카메라 이동 핸들러
+ * @param {() => void} [props.onNext] 다음 카메라 이동 핸들러
+ */
+export default function CCTVViewerDesktopOverlay({
+  isLive,
+  isShared,
+  metrics,
+  onNext,
+  onPrev,
+}: {
+  isLive?: boolean;
+  isShared?: boolean;
+  metrics?: React.ReactNode;
+  onPrev?: () => void;
+  onNext?: () => void;
+}) {
+  return (
+    <CCTVVideoOverlayContainer>
+      <CCTVVideoOverlayHeader
+        activeLiveState
+        isLive={isLive}
+        isShared={isShared}
+      />
+      <CCTVVideoOverlayBody className="cctv-viewer-desktop-overlay-body">
+        <CCTVPaginationBaseButton
+          className="cctv-viewer-desktop-move-button"
+          direction="prev"
+          disabled={!onPrev}
+          onMove={onPrev ?? (() => undefined)}
+        >
+          <span className="cctv-visually-hidden">이전 CCTV</span>
+        </CCTVPaginationBaseButton>
+        <CCTVPaginationBaseButton
+          className="cctv-viewer-desktop-move-button"
+          direction="next"
+          disabled={!onNext}
+          onMove={onNext ?? (() => undefined)}
+        >
+          <span className="cctv-visually-hidden">다음 CCTV</span>
+        </CCTVPaginationBaseButton>
+      </CCTVVideoOverlayBody>
+      <CCTVVideoOverlayFooter activeTitle={false}>
+        {metrics}
+      </CCTVVideoOverlayFooter>
+    </CCTVVideoOverlayContainer>
+  );
+}

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

@@ -4,6 +4,7 @@ import { useMemo } from "react";
 
 import { useCctvContext, useCctvRtcStream } from "../../../hooks";
 import type { CctvViewerDesktopVideoProps } from "../../../types";
+import CCTVViewerDesktopOverlay from "./Overlay";
 import CCTVVideoTemplate from "../../video/Template";
 import {
   getOverlayMessage,
@@ -22,6 +23,9 @@ import {
  */
 export default function CCTVViewerDesktopVideo({
   cam: propsCam,
+  metrics,
+  onNext,
+  onPrev,
   renderOverlay,
 }: CctvViewerDesktopVideoProps) {
   const { selectedCam, isFetching } = useCctvContext();
@@ -46,17 +50,25 @@ export default function CCTVViewerDesktopVideo({
       ref={videoRef}
       cam={cam}
       className="cctv-viewer-desktop-video-container"
+      layout="viewer"
       headerOptions={{
         activeLiveState: true,
-        activeTitle: true,
-        activeCloseButton: true,
         isLive,
         isShared: cam?.is_public === true,
-        title: cam?.cam_name,
       }}
       footerOptions={{ activeTitle: false }}
-      // 변경 설명: viewer video는 service custom overlay를 직접 수용하는 첫 public entry다.
-      renderOverlay={renderOverlay}
+      renderOverlay={
+        renderOverlay ??
+        (() => (
+          <CCTVViewerDesktopOverlay
+            isLive={isLive}
+            isShared={cam?.is_public === true}
+            metrics={metrics}
+            onNext={onNext}
+            onPrev={onPrev}
+          />
+        ))
+      }
       {...{
         isError,
         overlayMessage,

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

@@ -1,12 +1,16 @@
 import CCTVViewerDesktopContainer from "./desktop/Container";
 import CCTVViewerDesktopPagination from "./desktop/Pagination";
 import CCTVViewerDesktopVideo from "./desktop/Video";
+import CCTVViewerDesktopHeadline from "./desktop/Headline";
+import CCTVViewerDesktopOverlay from "./desktop/Overlay";
 
 export const CCTVViewer = {
   Desktop: {
     Container: CCTVViewerDesktopContainer,
     Video: CCTVViewerDesktopVideo,
     Pagination: CCTVViewerDesktopPagination,
+    Headline: CCTVViewerDesktopHeadline,
+    Overlay: CCTVViewerDesktopOverlay,
   },
   Mobile: {},
 };

package/src/cctv/img/time.svg

@@ -0,0 +1,4 @@
+<svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <circle cx="8" cy="8" r="6.5" fill="currentColor"/>
+  <path d="M8 4.5V8L10.5 9.5" stroke="white" stroke-width="1.25" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

package/src/cctv/styles/cam-list.scss

@@ -32,30 +32,7 @@
 }
 
 .cctv-cam-list-item .cctv-video-container {
+  min-height: 0;
   max-height: 240px;
-}
-
-// 4:3 card ratio는 video container가 책임지고, list는 320px card + 12px gap 기준으로 열 수만 조정한다.
-@container cctv-cam-list (min-width: 652px) {
-  .cctv-cam-list-track {
-    grid-template-columns: repeat(2, minmax(0, 1fr));
-  }
-}
-
-@container cctv-cam-list (min-width: 984px) {
-  .cctv-cam-list-track {
-    grid-template-columns: repeat(3, minmax(0, 1fr));
-  }
-}
-
-@container cctv-cam-list (min-width: 1316px) {
-  .cctv-cam-list-track {
-    grid-template-columns: repeat(4, minmax(0, 1fr));
-  }
-}
-
-@container cctv-cam-list (min-width: 1648px) {
-  .cctv-cam-list-track {
-    grid-template-columns: repeat(5, minmax(0, 1fr));
-  }
+  aspect-ratio: 16 / 9;
 }

package/src/cctv/styles/pagination.scss

@@ -40,7 +40,7 @@
 
 .cctv-pagination-track > li {
   // panel 너비를 고정해 viewport 이동 시 균등하게 보이도록 한다.
-  flex: 0 0 minmax(150px, 1fr);
+  flex: 0 0 var(--cctv-pagination-item-width);
 }
 
 .cctv-pagination-list-item {
@@ -48,6 +48,7 @@
 }
 
 .cctv-pagination-list-item .cctv-video-container {
+  min-height: 0;
   max-height: 152px;
 }
 

package/src/cctv/styles/variables.scss

@@ -2,11 +2,19 @@
   /* Card layout */
   --cctv-video-radius: 12px;
   --cctv-list-gap: var(--spacing-gap-5);
-  --cctv-list-item-min-width: 320px;
+  --cctv-list-item-min-width: 300px;
 
   --cctv-overlay-padding-x: var(--spacing-padding-8);
   --cctv-overlay-padding-y: var(--spacing-padding-6);
 
+  --cctv-viewer-video-radius: 16px;
+  --cctv-viewer-video-max-height: 618px;
+  --cctv-viewer-overlay-padding-x: var(--spacing-padding-11);
+  --cctv-viewer-overlay-padding-y: var(--spacing-padding-9);
+  --cctv-card-settings-bg: var(--color-common-99);
+  --cctv-card-settings-border: var(--color-border-assistive);
+  --cctv-card-height: 240px;
+
   --cctv-video-bg: var(--color-surface-heavy);
   --cctv-overlay-bg: linear-gradient(
     180deg,
@@ -21,6 +29,14 @@
   --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);
+  --cctv-state-dot-size: var(--spacing-gap-3);
+
+  /* Sensor metric */
+  --cctv-metric-bg: rgba(0, 0, 0, 0.55);
+  --cctv-metric-text: var(--color-common-99);
+  --cctv-metric-dot-normal: var(--color-feedback-success);
+  --cctv-metric-dot-attention: var(--color-feedback-new);
+  --cctv-metric-dot-unavailable: var(--color-border-strong);
 
   /* Error */
   --cctv-status-text-color: var(--color-common-99);
@@ -29,6 +45,7 @@
 
   /* Pagination */
   --cctv-carousel-gap: var(--spacing-gap-5);
+  --cctv-pagination-item-width: 170px;
   --cctv-pagination-move-button-size: 48px;
   --cctv-pagination-move-button-active: var(--color-cool-gray-20);
   --cctv-pagination-move-button-disabled: var(--color-cool-gray-85);

package/src/cctv/styles/video.scss

@@ -16,6 +16,53 @@
   }
 }
 
+.cctv-video-container[data-layout="card"] {
+  min-height: 0;
+  max-height: 240px;
+  aspect-ratio: 16 / 9;
+}
+
+.cctv-video-container[data-layout="carousel"] {
+  min-height: 0;
+  aspect-ratio: 16 / 9;
+}
+
+.cctv-video-card {
+  overflow: hidden;
+  border-radius: var(--cctv-video-radius);
+}
+
+.cctv-video-card[data-has-settings="true"] {
+  height: var(--cctv-card-height);
+  display: flex;
+  flex-direction: column;
+
+  .cctv-video-card-media {
+    min-height: 0;
+    flex: 1;
+  }
+
+  .cctv-video-card-media .cctv-video-container {
+    height: 100%;
+    min-height: 0;
+    aspect-ratio: auto;
+  }
+
+  .cctv-video-card-media .cctv-video-container,
+  .cctv-video-card-media .cctv-video-box video,
+  .cctv-video-card-media .cctv-video-overlay-container {
+    border-bottom-right-radius: 0;
+    border-bottom-left-radius: 0;
+  }
+}
+
+.cctv-video-card-settings {
+  flex: 0 0 auto;
+  padding: var(--spacing-padding-6) var(--spacing-padding-8);
+  background: var(--cctv-card-settings-bg);
+  box-shadow: inset 0 0 0 1px var(--cctv-card-settings-border);
+}
+
 .cctv-video-box {
   width: 100%;
   height: 100%;
@@ -46,6 +93,9 @@
 .cctv-video-overlay-header {
   width: 100%;
   height: fit-content;
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-gap-5);
   &.empty {
     height: calc(var(--font-heading-xsmall-size) * 1.5);
   }
@@ -75,10 +125,10 @@
   }
 }
 .cctv-video-live-state-dot {
-  width: 4px;
-  height: 4px;
-  margin-right: 4px;
-  border-radius: 4px;
+  width: var(--cctv-state-dot-size);
+  height: var(--cctv-state-dot-size);
+  margin-right: var(--spacing-gap-3);
+  border-radius: var(--cctv-state-dot-size);
   background: var(--cctv-live-state-dot-off);
 }
 
@@ -113,7 +163,7 @@
   }
 }
 .cctv-video-header-title {
-  font-size: var(--font-heading-large-size);
+  font-size: var(--font-heading-medium-size);
 }
 .cctv-video-footer-title {
   flex: 1 1 auto;
@@ -200,12 +250,52 @@
   margin-top: auto;
 }
 
+.cctv-video-metrics {
+  display: flex;
+  gap: var(--spacing-gap-4);
+  margin-left: auto;
+}
+
+.cctv-video-metric {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--spacing-gap-3);
+  padding: var(--spacing-padding-2) var(--spacing-padding-5);
+  border-radius: 999px;
+  color: var(--cctv-metric-text);
+  background: var(--cctv-metric-bg);
+  font-size: var(--font-label-small-size);
+  line-height: var(--font-label-small-line-height);
+  font-weight: var(--font-label-small-weight);
+  white-space: nowrap;
+}
+
+.cctv-video-metric-dot {
+  width: var(--cctv-state-dot-size);
+  height: var(--cctv-state-dot-size);
+  flex: 0 0 var(--cctv-state-dot-size);
+  border-radius: var(--cctv-state-dot-size);
+  background: var(--cctv-metric-dot-normal);
+}
+
+.cctv-video-metric[data-state="attention"] .cctv-video-metric-dot {
+  background: var(--cctv-metric-dot-attention);
+}
+
+.cctv-video-metric[data-state="unavailable"] .cctv-video-metric-dot {
+  background: var(--cctv-metric-dot-unavailable);
+}
+
 .cctv-video-open-button {
   flex: 0 0 auto;
   display: flex;
   align-items: center;
   justify-content: center;
   cursor: auto;
+  position: absolute;
+  top: var(--cctv-overlay-padding-y);
+  right: var(--cctv-overlay-padding-x);
+  z-index: 2;
   svg path {
     stroke: var(--cctv-open-button-color-off);
   }

package/src/cctv/styles/viewer.scss

@@ -1,7 +1,78 @@
+.cctv-viewer-desktop-container {
+  display: grid;
+  gap: var(--spacing-gap-6);
+  width: min(100%, 1216px);
+  margin: 0 auto;
+}
+
+.cctv-viewer-desktop-headline {
+  min-height: 34px;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--spacing-gap-6);
+
+  h3 {
+    min-width: 0;
+    margin: 0;
+    overflow: hidden;
+    color: var(--color-label-strong);
+    font-size: var(--font-heading-medium-size);
+    line-height: 1.4;
+    font-weight: 700;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+}
+
+.cctv-viewer-desktop-time {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--spacing-gap-3);
+  color: var(--color-label-neutral);
+  font-size: var(--font-label-small-size);
+  line-height: var(--font-label-small-line-height);
+  font-weight: var(--font-label-small-weight);
+  white-space: nowrap;
+}
+
 .cctv-viewer-desktop-video-container {
-  max-height: 500px;
+  --cctv-video-radius: var(--cctv-viewer-video-radius);
+  --cctv-overlay-padding-x: var(--cctv-viewer-overlay-padding-x);
+  --cctv-overlay-padding-y: var(--cctv-viewer-overlay-padding-y);
+
+  max-height: var(--cctv-viewer-video-max-height);
+  min-height: 0;
+  aspect-ratio: 608 / 309;
+}
+
+.cctv-viewer-desktop-overlay-body {
+  flex-direction: row;
+  justify-content: space-between;
+}
+
+.cctv-viewer-desktop-move-button.cctv-pagination-move-button {
+  width: 42px;
+  height: 42px;
+  background: var(--cctv-pagination-move-button-active);
+}
+
+.cctv-viewer-desktop-video-container .cctv-video-overlay-footer {
+  justify-content: flex-end;
+}
+
+.cctv-visually-hidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
 }
 
 .cctv-viewer-desktop-pagination-container {
-  margin-top: var(--spacing-gap-8);
+  margin-top: var(--spacing-gap-2);
 }

package/src/cctv/types/props.ts

@@ -112,6 +112,10 @@ export interface CctvVideoOverlayHeaderProps {
  */
 export interface CctvVideoOverlayFooterProps {
   className?: string;
+  /**
+   * 제목/버튼과 함께 배치할 추가 콘텐츠
+   */
+  children?: React.ReactNode;
   /**
    * 하단 타이틀 노출 여부
    */
@@ -130,6 +134,48 @@ export interface CctvVideoOverlayFooterProps {
   isLive?: boolean;
 }
 
+/**
+ * CCTV; sensor metric 표시 상태
+ */
+export type CctvVideoMetricState = "normal" | "attention" | "unavailable";
+
+/**
+ * CCTV; sensor metric props
+ * @property {React.ReactNode} children 표시할 센서 값
+ * @property {CctvVideoMetricState} [state] state dot 표시 상태
+ */
+export interface CctvVideoMetricProps {
+  /**
+   * 표시할 센서 값
+   */
+  children: React.ReactNode;
+  /**
+   * state dot 표시 상태
+   */
+  state?: CctvVideoMetricState;
+}
+
+/**
+ * CCTV; Video Card props
+ * @property {React.ReactNode} children video/media 영역
+ * @property {React.ReactNode} [settings] media 하단 서비스 설정 영역
+ * @property {string} [className] 카드 루트 클래스
+ */
+export interface CctvVideoCardProps {
+  /**
+   * video/media 영역
+   */
+  children: React.ReactNode;
+  /**
+   * media 하단 서비스 설정 영역
+   */
+  settings?: React.ReactNode;
+  /**
+   * 카드 루트 클래스
+   */
+  className?: string;
+}
+
 /**
  * CCTV; 비디오 상태 관련 props
  * @property {boolean} [isError] 에러 상태 여부
@@ -169,6 +215,7 @@ export interface CctvVideoStateProps {
 /**
  * CCTV; Video Template props
  * @property {string} [className] 루트 컨테이너에 적용할 클래스
+ * @property {"card" | "carousel" | "viewer"} [layout] 공용 video layout preset
  * @property {CctvVideoOverlayHeaderProps} [headerOptions] 헤더 구성 옵션
  * @property {CctvVideoOverlayFooterProps} [footerOptions] 푸터 구성 옵션
  * @property {boolean} [isError] 에러 상태 여부
@@ -183,6 +230,10 @@ export interface CctvVideoTemplateProps extends CctvVideoStateProps {
    */
   cam?: CctvCompanyCameraData;
   className?: string;
+  /**
+   * 공용 video layout preset
+   */
+  layout?: "card" | "carousel" | "viewer";
   /**
    * <CCtvVideoOverlayHeader /> 속성
    */
@@ -262,6 +313,18 @@ export interface CctvViewerDesktopVideoProps {
    * custom overlay 렌더 함수
    */
   renderOverlay?: CctvVideoRenderOverlay;
+  /**
+   * viewer 하단 sensor metric 영역
+   */
+  metrics?: React.ReactNode;
+  /**
+   * 이전 카메라 이동 핸들러
+   */
+  onPrev?: () => void;
+  /**
+   * 다음 카메라 이동 핸들러
+   */
+  onNext?: () => void;
 }
 
 /**
@@ -271,6 +334,10 @@ export interface CctvViewerDesktopVideoProps {
  * @property {CctvCompanyCameraData} [selectedCam] 외부에서 직접 주입하는 선택 카메라 데이터
  * @property {CctvCompanyCameraData[]} [camList] 외부에서 직접 주입하는 카메라 리스트
  * @property {CctvVideoRenderOverlay} [renderOverlay] viewer video용 custom overlay 렌더 함수
+ * @property {React.ReactNode} [time] viewer headline 확인 시각
+ * @property {React.ReactNode} [metrics] viewer 하단 sensor metric 영역
+ * @property {() => void} [onPrev] 이전 카메라 이동 핸들러
+ * @property {() => void} [onNext] 다음 카메라 이동 핸들러
  */
 export interface CctvViewerDesktopContainerProps {
   /**
@@ -293,4 +360,20 @@ export interface CctvViewerDesktopContainerProps {
    * viewer video용 custom overlay 렌더 함수
    */
   renderOverlay?: CctvVideoRenderOverlay;
+  /**
+   * viewer headline 확인 시각
+   */
+  time?: React.ReactNode;
+  /**
+   * viewer 하단 sensor metric 영역
+   */
+  metrics?: React.ReactNode;
+  /**
+   * 이전 카메라 이동 핸들러
+   */
+  onPrev?: () => void;
+  /**
+   * 다음 카메라 이동 핸들러
+   */
+  onNext?: () => void;
 }