@uniai-fe/uds-templates 0.11.7 → 0.12.1

package/README.md

@@ -39,6 +39,13 @@ import { Frame, Modal } from "@uniai-fe/uds-templates";
 
 `@uniai-fe/uds-templates/src/**`와 export map에 없는 category path는 public API가 아니다.
 
+### CCTV 전체화면
+
+`useCctvFullscreen`은 서비스가 지정한 container를 전체화면으로 전환한다.
+화면 방향 API를 지원하면 전체화면 동안 `landscape`를 요청하며, 종료·대상 제거 시
+고정을 해제해 기본 방향 정책으로 돌아간다. 세로 방향 복귀를 강제하지 않는다.
+방향 API 미지원·요청 거부는 전체화면 시청을 차단하지 않는다.
+
 ## Styles
 
 CSS consumer는 dependency order대로 각 public entry를 로드한다.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniai-fe/uds-templates",
-  "version": "0.11.7",
+  "version": "0.12.1",
   "description": "UNIAI Design System; UI Templates Package",
   "type": "module",
   "private": false,
@@ -67,17 +67,17 @@
     "react-hook-form": "^7.84.0",
     "sass": "^1.101.7",
     "typescript": "6.0.3",
-    "@uniai-fe/react-hooks": "0.3.0",
-    "@uniai-fe/tsconfig": "0.2.0",
-    "@uniai-fe/uds-primitives": "0.12.5",
-    "@uniai-fe/uds-foundation": "0.6.0",
-    "@uniai-fe/util-functions": "0.4.3",
+    "@uniai-fe/next-devkit": "0.4.0",
     "@uniai-fe/eslint-config": "0.4.2",
+    "@uniai-fe/uds-primitives": "0.12.5",
     "@uniai-fe/util-jotai": "0.3.0",
-    "@uniai-fe/util-next": "0.5.0",
+    "@uniai-fe/react-hooks": "0.3.0",
+    "@uniai-fe/util-api": "0.2.1",
+    "@uniai-fe/tsconfig": "0.2.0",
     "@uniai-fe/util-rtc": "0.2.1",
-    "@uniai-fe/next-devkit": "0.4.0",
-    "@uniai-fe/util-api": "0.2.1"
+    "@uniai-fe/util-functions": "0.4.3",
+    "@uniai-fe/uds-foundation": "0.6.0",
+    "@uniai-fe/util-next": "0.5.0"
   },
   "scripts": {
     "check:pre-commit": "pnpm --dir ../../.. run check:pre-commit",

package/src/cctv/hooks/index.tsx

@@ -1,5 +1,11 @@
 import useCctvCompanyData from "./useCompanyData";
 import useCctvContext from "./useContext";
 import { useCctvRtcStream } from "./useRtcStream";
+import { useCctvFullscreen } from "./useFullscreen";
 
-export { useCctvContext, useCctvCompanyData, useCctvRtcStream };
+export {
+  useCctvContext,
+  useCctvCompanyData,
+  useCctvRtcStream,
+  useCctvFullscreen,
+};

package/src/cctv/hooks/useFullscreen.ts

@@ -0,0 +1,212 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import type { UseCctvFullscreenReturn } from "../types";
+
+/**
+ * CCTV; service-owned viewer container fullscreen state
+ * @hook
+ * @desc 대상 element의 표준 Fullscreen API 지원 여부와 실제 document 상태를 동기화한다.
+ * 요청 실패는 기존 viewer를 유지하며, 외부 종료 후에는 진입 전 focus를 복원한다.
+ * 지원 환경에서는 진입 후 가로 방향을 요청하고 종료·대상 제거 시 기본 방향 정책으로 돌려준다.
+ * 방향 요청 실패는 전체화면 성공에 영향을 주지 않으며 종료 후 세로 방향을 강제하지 않는다.
+ * @return {UseCctvFullscreenReturn} 대상 ref callback과 전체화면 상태·action
+ */
+export function useCctvFullscreen(): UseCctvFullscreenReturn {
+  const [targetElement, setTargetElement] = useState<HTMLElement | null>(null);
+  const [isFullscreen, setIsFullscreen] = useState(false);
+  const targetElementRef = useRef<HTMLElement | null>(null);
+  const entryFocusRef = useRef<HTMLElement | null>(null);
+  const wasFullscreenRef = useRef(false);
+  const unlockOrientationRef = useRef<(() => void) | null>(null);
+
+  const releaseOrientation = useCallback(() => {
+    const unlock = unlockOrientationRef.current;
+    unlockOrientationRef.current = null;
+    try {
+      unlock?.();
+    } catch {
+      // 숨겨진 document 등에서 해제가 거부돼도 전체화면 종료와 focus 복원을 유지한다.
+    }
+  }, []);
+
+  /**
+   * service가 선택한 전체화면 대상 element를 hook lifecycle에 연결한다.
+   */
+  const targetRef = useCallback(
+    (element: HTMLElement | null) => {
+      if (targetElementRef.current !== element) releaseOrientation();
+      targetElementRef.current = element;
+      setTargetElement(element);
+
+      if (element === null) {
+        setIsFullscreen(false);
+      }
+    },
+    [releaseOrientation],
+  );
+
+  /**
+   * 외부 종료 후에도 사용자가 시작한 control로 keyboard focus를 돌려보낸다.
+   */
+  const restoreEntryFocus = useCallback(() => {
+    const entryFocus = entryFocusRef.current;
+    entryFocusRef.current = null;
+
+    if (entryFocus?.isConnected) {
+      entryFocus.focus();
+    }
+  }, []);
+
+  useEffect(() => {
+    if (targetElement === null) return;
+
+    const ownerDocument = targetElement.ownerDocument;
+
+    // request Promise가 아니라 browser event를 실제 전체화면 상태의 기준으로 사용한다.
+    const synchronizeFullscreenState = () => {
+      const nextIsFullscreen =
+        ownerDocument.fullscreenElement === targetElement;
+
+      setIsFullscreen(nextIsFullscreen);
+
+      if (!nextIsFullscreen && wasFullscreenRef.current) {
+        releaseOrientation();
+        restoreEntryFocus();
+      }
+
+      wasFullscreenRef.current = nextIsFullscreen;
+    };
+
+    ownerDocument.addEventListener(
+      "fullscreenchange",
+      synchronizeFullscreenState,
+    );
+    ownerDocument.addEventListener(
+      "fullscreenerror",
+      synchronizeFullscreenState,
+    );
+
+    return () => {
+      ownerDocument.removeEventListener(
+        "fullscreenchange",
+        synchronizeFullscreenState,
+      );
+      ownerDocument.removeEventListener(
+        "fullscreenerror",
+        synchronizeFullscreenState,
+      );
+
+      releaseOrientation();
+      if (ownerDocument.fullscreenElement === targetElement) {
+        void ownerDocument.exitFullscreen().catch(() => undefined);
+      }
+
+      if (wasFullscreenRef.current) {
+        restoreEntryFocus();
+      }
+
+      wasFullscreenRef.current = false;
+    };
+  }, [releaseOrientation, restoreEntryFocus, targetElement]);
+
+  /**
+   * 현재 service target의 표준 전체화면 진입을 요청한다.
+   */
+  const enterFullscreen = useCallback(async () => {
+    const target = targetElementRef.current;
+
+    if (
+      target === null ||
+      !target.ownerDocument.fullscreenEnabled ||
+      typeof target.requestFullscreen !== "function"
+    ) {
+      return false;
+    }
+
+    if (target.ownerDocument.fullscreenElement === target) {
+      return true;
+    }
+
+    const activeElement = target.ownerDocument.activeElement;
+    entryFocusRef.current =
+      typeof HTMLElement !== "undefined" && activeElement instanceof HTMLElement
+        ? activeElement
+        : null;
+
+    try {
+      await target.requestFullscreen();
+      const orientation = target.ownerDocument.defaultView?.screen.orientation;
+      if (
+        targetElementRef.current === target &&
+        target.ownerDocument.fullscreenElement === target &&
+        typeof orientation?.lock === "function" &&
+        typeof orientation.unlock === "function"
+      ) {
+        // 대기 중에도 종료가 pending lock을 취소할 수 있도록 먼저 소유권을 기록한다.
+        const unlock = () => orientation.unlock();
+        unlockOrientationRef.current = unlock;
+        try {
+          await orientation.lock("landscape");
+        } catch {
+          // 이전 요청의 거부가 이후 전체화면 세션의 해제 책임을 지우지 않도록 구분한다.
+          if (unlockOrientationRef.current === unlock) {
+            unlockOrientationRef.current = null;
+          }
+        }
+      }
+      return true;
+    } catch {
+      entryFocusRef.current = null;
+      return false;
+    }
+  }, []);
+
+  /**
+   * 다른 element의 전체화면은 건드리지 않고 현재 target 소유 상태만 종료한다.
+   */
+  const exitFullscreen = useCallback(async () => {
+    const target = targetElementRef.current;
+
+    if (
+      target === null ||
+      target.ownerDocument.fullscreenElement !== target ||
+      typeof target.ownerDocument.exitFullscreen !== "function"
+    ) {
+      return false;
+    }
+
+    try {
+      await target.ownerDocument.exitFullscreen();
+      releaseOrientation();
+      return true;
+    } catch {
+      return false;
+    }
+  }, [releaseOrientation]);
+
+  /**
+   * 현재 document 소유 상태에 따라 target의 진입 또는 종료 action을 선택한다.
+   */
+  const toggleFullscreen = useCallback(async () => {
+    const target = targetElementRef.current;
+
+    if (target?.ownerDocument.fullscreenElement === target) {
+      return exitFullscreen();
+    }
+
+    return enterFullscreen();
+  }, [enterFullscreen, exitFullscreen]);
+
+  return {
+    targetRef,
+    isFullscreenSupported:
+      targetElement !== null &&
+      targetElement.ownerDocument.fullscreenEnabled &&
+      typeof targetElement.requestFullscreen === "function",
+    isFullscreen,
+    enterFullscreen,
+    exitFullscreen,
+    toggleFullscreen,
+  };
+}

package/src/cctv/types/hook.ts

@@ -13,6 +13,45 @@ import type {
 import type { UseFormReturn } from "react-hook-form";
 import type { CctvBaseContext } from "./context";
 
+/**
+ * CCTV; useCctvFullscreen return
+ * @property {React.RefCallback<HTMLElement>} targetRef 전체화면 대상 viewer container ref callback
+ * @property {boolean} isFullscreenSupported 대상과 브라우저의 표준 Fullscreen API 지원 여부
+ * @property {boolean} isFullscreen 현재 대상이 실제 전체화면인지 여부
+ * @property {() => Promise<boolean>} enterFullscreen 대상 전체화면 진입 action과 성공 여부
+ * @property {() => Promise<boolean>} exitFullscreen 현재 대상 소유 전체화면 종료 action과 성공 여부
+ * @property {() => Promise<boolean>} toggleFullscreen 현재 대상의 전체화면 진입·종료 action과 성공 여부
+ */
+export interface UseCctvFullscreenReturn {
+  /**
+   * 전체화면 대상 viewer container ref callback
+   */
+  targetRef: React.RefCallback<HTMLElement>;
+  /**
+   * 대상과 브라우저의 표준 Fullscreen API 지원 여부
+   */
+  isFullscreenSupported: boolean;
+  /**
+   * 현재 대상이 실제 전체화면인지 여부
+   */
+  isFullscreen: boolean;
+  /**
+   * 대상 전체화면 진입 action
+   * @return 진입 요청 성공 여부
+   */
+  enterFullscreen: () => Promise<boolean>;
+  /**
+   * 현재 대상 소유 전체화면 종료 action
+   * @return 종료 요청 성공 여부
+   */
+  exitFullscreen: () => Promise<boolean>;
+  /**
+   * 현재 대상의 전체화면 진입·종료 action
+   * @return 요청 성공 여부
+   */
+  toggleFullscreen: () => Promise<boolean>;
+}
+
 /**
  * CCTV; RTC stream 재연결 trigger
  */