@uniai-fe/uds-templates 0.12.0 → 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.12.0",
+  "version": "0.12.1",
   "description": "UNIAI Design System; UI Templates Package",
   "type": "module",
   "private": false,
@@ -67,16 +67,16 @@
     "react-hook-form": "^7.84.0",
     "sass": "^1.101.7",
     "typescript": "6.0.3",
-    "@uniai-fe/react-hooks": "0.3.0",
-    "@uniai-fe/eslint-config": "0.4.2",
-    "@uniai-fe/tsconfig": "0.2.0",
     "@uniai-fe/next-devkit": "0.4.0",
-    "@uniai-fe/util-api": "0.2.1",
-    "@uniai-fe/uds-foundation": "0.6.0",
-    "@uniai-fe/util-functions": "0.4.3",
+    "@uniai-fe/eslint-config": "0.4.2",
     "@uniai-fe/uds-primitives": "0.12.5",
     "@uniai-fe/util-jotai": "0.3.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/util-functions": "0.4.3",
+    "@uniai-fe/uds-foundation": "0.6.0",
     "@uniai-fe/util-next": "0.5.0"
   },
   "scripts": {

package/src/cctv/hooks/useFullscreen.ts

@@ -8,6 +8,8 @@ import type { UseCctvFullscreenReturn } from "../types";
  * @hook
  * @desc 대상 element의 표준 Fullscreen API 지원 여부와 실제 document 상태를 동기화한다.
  * 요청 실패는 기존 viewer를 유지하며, 외부 종료 후에는 진입 전 focus를 복원한다.
+ * 지원 환경에서는 진입 후 가로 방향을 요청하고 종료·대상 제거 시 기본 방향 정책으로 돌려준다.
+ * 방향 요청 실패는 전체화면 성공에 영향을 주지 않으며 종료 후 세로 방향을 강제하지 않는다.
  * @return {UseCctvFullscreenReturn} 대상 ref callback과 전체화면 상태·action
  */
 export function useCctvFullscreen(): UseCctvFullscreenReturn {
@@ -16,18 +18,33 @@ export function useCctvFullscreen(): UseCctvFullscreenReturn {
   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) => {
-    targetElementRef.current = element;
-    setTargetElement(element);
-
-    if (element === null) {
-      setIsFullscreen(false);
-    }
-  }, []);
+  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를 돌려보낸다.
@@ -54,6 +71,7 @@ export function useCctvFullscreen(): UseCctvFullscreenReturn {
       setIsFullscreen(nextIsFullscreen);
 
       if (!nextIsFullscreen && wasFullscreenRef.current) {
+        releaseOrientation();
         restoreEntryFocus();
       }
 
@@ -79,6 +97,7 @@ export function useCctvFullscreen(): UseCctvFullscreenReturn {
         synchronizeFullscreenState,
       );
 
+      releaseOrientation();
       if (ownerDocument.fullscreenElement === targetElement) {
         void ownerDocument.exitFullscreen().catch(() => undefined);
       }
@@ -89,7 +108,7 @@ export function useCctvFullscreen(): UseCctvFullscreenReturn {
 
       wasFullscreenRef.current = false;
     };
-  }, [restoreEntryFocus, targetElement]);
+  }, [releaseOrientation, restoreEntryFocus, targetElement]);
 
   /**
    * 현재 service target의 표준 전체화면 진입을 요청한다.
@@ -117,6 +136,25 @@ export function useCctvFullscreen(): UseCctvFullscreenReturn {
 
     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;
@@ -140,11 +178,12 @@ export function useCctvFullscreen(): UseCctvFullscreenReturn {
 
     try {
       await target.ownerDocument.exitFullscreen();
+      releaseOrientation();
       return true;
     } catch {
       return false;
     }
-  }, []);
+  }, [releaseOrientation]);
 
   /**
    * 현재 document 소유 상태에 따라 target의 진입 또는 종료 action을 선택한다.