@uniai-fe/uds-templates 0.12.0 → 0.12.2

package/README.md

@@ -39,6 +39,32 @@ 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 미지원·요청 거부는 전체화면 시청을 차단하지 않는다.
+진입 요청 대기 중 대상이 교체·제거되면 늦게 열린 이전 대상의 전체화면을 종료하고
+`false`를 반환한다. 다른 대상이 소유한 전체화면은 유지한다.
+
+`useCctvFullscreen({ fallback: "viewport" })`는 표준 Fullscreen API 미지원 시
+페이지 안 전체창 확대를 허용한다. `isFullscreenSupported`와 `isFullscreen`은
+표준 API의 의미를 유지하며, 전체창 확대는 `isViewportExpanded`로 구분한다.
+옵션을 생략하면 기존 동작을 유지하고, 표준 API 요청이 거부된 경우에는 확대하지 않는다.
+
+서비스는 같은 `targetRef` container에 `isViewportExpanded`에 따른 viewport 고정,
+크기·안전 영역·반응형 스타일을 적용한다. 브라우저 UI를 숨기거나 기기 방향을 강제하지 않는다.
+진입·종료 action은 두 방식을 처리하므로 버튼의 활성 상태에는
+`isFullscreen || isViewportExpanded`를 사용한다. 전체창 확대를 선택한 서비스는
+표준 API 지원 여부로 해당 버튼을 숨기지 않는다.
+
+Hook은 전체창 확대 동안 배경 scroll과 대상 바깥의 focus를 제한한다. 확대 종료 버튼,
+Escape, 대상 교체·제거 또는 unmount로 종료하면 기존 overflow·inert·tabindex와
+연결된 진입 control의 focus를 복원한다. 카메라 전환은 container를 유지하며, DOM을
+다른 부모로 이동하거나 영상을 다시 만들지 않는다. 같은 document에서는 한 Hook만
+전체창 확대를 소유한다.
+
 ## 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.2",
   "description": "UNIAI Design System; UI Templates Package",
   "type": "module",
   "private": false,
@@ -70,14 +70,14 @@
     "@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/uds-primitives": "0.12.5",
     "@uniai-fe/util-jotai": "0.3.0",
-    "@uniai-fe/util-rtc": "0.2.1",
-    "@uniai-fe/util-next": "0.5.0"
+    "@uniai-fe/util-api": "0.2.1",
+    "@uniai-fe/util-next": "0.5.0",
+    "@uniai-fe/next-devkit": "0.4.0",
+    "@uniai-fe/util-functions": "0.4.3",
+    "@uniai-fe/util-rtc": "0.2.1"
   },
   "scripts": {
     "check:pre-commit": "pnpm --dir ../../.. run check:pre-commit",

package/src/cctv/hooks/useFullscreen.ts

@@ -1,31 +1,50 @@
 "use client";
 
 import { useCallback, useEffect, useRef, useState } from "react";
-import type { UseCctvFullscreenReturn } from "../types";
+import type {
+  UseCctvFullscreenParams,
+  UseCctvFullscreenReturn,
+} from "../types";
+
+// 같은 document의 viewer들이 배경 잠금과 focus 복원 책임을 동시에 갖지 않도록 제한한다.
+const viewportOwners = new WeakMap<Document, HTMLElement>();
 
 /**
  * CCTV; service-owned viewer container fullscreen state
  * @hook
  * @desc 대상 element의 표준 Fullscreen API 지원 여부와 실제 document 상태를 동기화한다.
  * 요청 실패는 기존 viewer를 유지하며, 외부 종료 후에는 진입 전 focus를 복원한다.
+ * 지원 환경에서는 진입 후 가로 방향을 요청하고 종료·대상 제거 시 기본 방향 정책으로 돌려준다.
+ * 방향 요청 실패는 전체화면 성공에 영향을 주지 않으며 종료 후 세로 방향을 강제하지 않는다.
+ * fallback이 "viewport"이면 표준 API 미지원 시 전체창 확대 상태와 배경 scroll·focus를 관리한다.
+ * 실제 확대 layout은 서비스가 isViewportExpanded로 적용하며 영상 DOM을 이동하거나 다시 만들지 않는다.
+ * 표준 API 요청 거부는 전체창 확대로 전환하지 않는다.
+ * @param {UseCctvFullscreenParams} options 미지원 환경의 확대 정책
+ * @property {"viewport"} [options.fallback] "viewport"는 전체창 확대를 허용한다. 생략하면 표준 API만 사용한다.
  * @return {UseCctvFullscreenReturn} 대상 ref callback과 전체화면 상태·action
  */
-export function useCctvFullscreen(): UseCctvFullscreenReturn {
+export function useCctvFullscreen({
+  fallback,
+}: UseCctvFullscreenParams = {}): UseCctvFullscreenReturn {
   const [targetElement, setTargetElement] = useState<HTMLElement | null>(null);
   const [isFullscreen, setIsFullscreen] = useState(false);
+  const [isViewportExpanded, setIsViewportExpanded] = 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 viewportSessionRef = useRef<{
+    target: HTMLElement;
+    release: () => void;
+  } | null>(null);
 
-  /**
-   * service가 선택한 전체화면 대상 element를 hook lifecycle에 연결한다.
-   */
-  const targetRef = useCallback((element: HTMLElement | null) => {
-    targetElementRef.current = element;
-    setTargetElement(element);
-
-    if (element === null) {
-      setIsFullscreen(false);
+  const releaseOrientation = useCallback(() => {
+    const unlock = unlockOrientationRef.current;
+    unlockOrientationRef.current = null;
+    try {
+      unlock?.();
+    } catch {
+      // 숨겨진 document 등에서 해제가 거부돼도 전체화면 종료와 focus 복원을 유지한다.
     }
   }, []);
 
@@ -37,10 +56,37 @@ export function useCctvFullscreen(): UseCctvFullscreenReturn {
     entryFocusRef.current = null;
 
     if (entryFocus?.isConnected) {
-      entryFocus.focus();
+      entryFocus.focus({ preventScroll: true });
     }
   }, []);
 
+  const exitViewportExpansion = useCallback(() => {
+    const session = viewportSessionRef.current;
+    if (!session) return false;
+    viewportSessionRef.current = null;
+    session.release();
+    setIsViewportExpanded(false);
+    restoreEntryFocus();
+    return true;
+  }, [restoreEntryFocus]);
+
+  /**
+   * service가 선택한 전체화면 대상 element를 hook lifecycle에 연결한다.
+   */
+  const targetRef = useCallback(
+    (element: HTMLElement | null) => {
+      if (targetElementRef.current !== element) {
+        releaseOrientation();
+        exitViewportExpansion();
+      }
+      targetElementRef.current = element;
+      setTargetElement(element);
+
+      if (element === null) setIsFullscreen(false);
+    },
+    [exitViewportExpansion, releaseOrientation],
+  );
+
   useEffect(() => {
     if (targetElement === null) return;
 
@@ -54,6 +100,7 @@ export function useCctvFullscreen(): UseCctvFullscreenReturn {
       setIsFullscreen(nextIsFullscreen);
 
       if (!nextIsFullscreen && wasFullscreenRef.current) {
+        releaseOrientation();
         restoreEntryFocus();
       }
 
@@ -79,6 +126,10 @@ export function useCctvFullscreen(): UseCctvFullscreenReturn {
         synchronizeFullscreenState,
       );
 
+      releaseOrientation();
+      if (viewportSessionRef.current?.target === targetElement) {
+        exitViewportExpansion();
+      }
       if (ownerDocument.fullscreenElement === targetElement) {
         void ownerDocument.exitFullscreen().catch(() => undefined);
       }
@@ -89,45 +140,182 @@ export function useCctvFullscreen(): UseCctvFullscreenReturn {
 
       wasFullscreenRef.current = false;
     };
-  }, [restoreEntryFocus, targetElement]);
+  }, [
+    exitViewportExpansion,
+    releaseOrientation,
+    restoreEntryFocus,
+    targetElement,
+  ]);
 
   /**
-   * 현재 service target의 표준 전체화면 진입을 요청한다.
+   * 표준 API를 우선하며 미지원일 때만 선택한 전체창 확대를 시작한다.
    */
   const enterFullscreen = useCallback(async () => {
     const target = targetElementRef.current;
 
+    if (target === null) return false;
+
     if (
-      target === null ||
-      !target.ownerDocument.fullscreenEnabled ||
-      typeof target.requestFullscreen !== "function"
+      target.ownerDocument.fullscreenElement === target ||
+      viewportSessionRef.current?.target === target
     ) {
-      return false;
-    }
-
-    if (target.ownerDocument.fullscreenElement === target) {
       return true;
     }
 
-    const activeElement = target.ownerDocument.activeElement;
+    const ownerDocument = target.ownerDocument;
+    if (viewportOwners.has(ownerDocument)) return false;
+    const isNativeSupported =
+      ownerDocument.fullscreenEnabled &&
+      typeof target.requestFullscreen === "function";
+    if (
+      !isNativeSupported &&
+      (fallback !== "viewport" ||
+        !target.isConnected ||
+        ownerDocument.fullscreenElement)
+    ) {
+      return false;
+    }
+    const activeElement = ownerDocument.activeElement;
+    const ElementConstructor = ownerDocument.defaultView?.HTMLElement;
     entryFocusRef.current =
-      typeof HTMLElement !== "undefined" && activeElement instanceof HTMLElement
+      ElementConstructor && activeElement instanceof ElementConstructor
         ? activeElement
         : null;
 
+    if (!isNativeSupported) {
+      const restores: (() => void)[] = [];
+      viewportOwners.set(ownerDocument, target);
+
+      // 기존 modal의 잠금과 inline style은 해당 속성만 보관해 종료 시 복원한다.
+      for (const element of [
+        ownerDocument.documentElement,
+        ownerDocument.body,
+      ]) {
+        const overflow = element.style.overflow;
+        const priority = element.style.getPropertyPriority("overflow");
+        element.style.setProperty("overflow", "hidden");
+        restores.push(() =>
+          element.style.setProperty("overflow", overflow, priority),
+        );
+      }
+      for (
+        let branch: HTMLElement = target;
+        branch.parentElement;
+        branch = branch.parentElement
+      ) {
+        for (const sibling of branch.parentElement.children) {
+          if (
+            sibling === branch ||
+            !ElementConstructor ||
+            !(sibling instanceof ElementConstructor)
+          )
+            continue;
+          const inert = sibling.getAttribute("inert");
+          sibling.setAttribute("inert", "");
+          restores.push(() => {
+            if (inert === null) sibling.removeAttribute("inert");
+            else sibling.setAttribute("inert", inert);
+          });
+        }
+      }
+      const tabIndex = target.getAttribute("tabindex");
+      target.setAttribute("tabindex", "-1");
+      restores.push(() => {
+        if (tabIndex === null) target.removeAttribute("tabindex");
+        else target.setAttribute("tabindex", tabIndex);
+      });
+
+      const onFocus = () => {
+        if (!target.contains(ownerDocument.activeElement))
+          target.focus({ preventScroll: true });
+      };
+      const onKeyDown = (event: KeyboardEvent) => {
+        if (event.key === "Escape") {
+          event.preventDefault();
+          event.stopPropagation();
+          exitViewportExpansion();
+        } else if (event.key === "Tab") {
+          const controls = Array.from(
+            target.querySelectorAll<HTMLElement>(
+              'button:not([disabled]), [href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])',
+            ),
+          ).filter(
+            element =>
+              element.tabIndex >= 0 &&
+              element.getClientRects().length > 0 &&
+              !element.closest("[inert]"),
+          );
+          const first = controls[0];
+          const last = controls.at(-1);
+          if (
+            !first ||
+            ownerDocument.activeElement === target ||
+            (event.shiftKey
+              ? ownerDocument.activeElement === first
+              : ownerDocument.activeElement === last)
+          ) {
+            event.preventDefault();
+            (event.shiftKey ? (last ?? target) : (first ?? target)).focus({
+              preventScroll: true,
+            });
+          }
+        }
+      };
+      ownerDocument.addEventListener("keydown", onKeyDown, true);
+      ownerDocument.addEventListener("focusin", onFocus);
+      viewportSessionRef.current = {
+        target,
+        release: () => {
+          ownerDocument.removeEventListener("keydown", onKeyDown, true);
+          ownerDocument.removeEventListener("focusin", onFocus);
+          restores.reverse().forEach(restore => restore());
+          viewportOwners.delete(ownerDocument);
+        },
+      };
+      onFocus();
+      setIsViewportExpanded(true);
+      return true;
+    }
+
     try {
       await target.requestFullscreen();
+      // 대상 정리 뒤 완료된 요청은 이전 화면을 남기지 않되 새 대상의 전체화면은 보존한다.
+      if (targetElementRef.current !== target) {
+        if (ownerDocument.fullscreenElement === target) {
+          await ownerDocument.exitFullscreen().catch(() => undefined);
+        }
+        return false;
+      }
+      const orientation = target.ownerDocument.defaultView?.screen.orientation;
+      if (
+        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;
     }
-  }, []);
+  }, [exitViewportExpansion, fallback]);
 
   /**
    * 다른 element의 전체화면은 건드리지 않고 현재 target 소유 상태만 종료한다.
    */
   const exitFullscreen = useCallback(async () => {
+    if (exitViewportExpansion()) return true;
     const target = targetElementRef.current;
 
     if (
@@ -140,11 +328,12 @@ export function useCctvFullscreen(): UseCctvFullscreenReturn {
 
     try {
       await target.ownerDocument.exitFullscreen();
+      releaseOrientation();
       return true;
     } catch {
       return false;
     }
-  }, []);
+  }, [exitViewportExpansion, releaseOrientation]);
 
   /**
    * 현재 document 소유 상태에 따라 target의 진입 또는 종료 action을 선택한다.
@@ -152,7 +341,10 @@ export function useCctvFullscreen(): UseCctvFullscreenReturn {
   const toggleFullscreen = useCallback(async () => {
     const target = targetElementRef.current;
 
-    if (target?.ownerDocument.fullscreenElement === target) {
+    if (
+      viewportSessionRef.current ||
+      target?.ownerDocument.fullscreenElement === target
+    ) {
       return exitFullscreen();
     }
 
@@ -163,9 +355,10 @@ export function useCctvFullscreen(): UseCctvFullscreenReturn {
     targetRef,
     isFullscreenSupported:
       targetElement !== null &&
-      targetElement.ownerDocument.fullscreenEnabled &&
+      targetElement.ownerDocument.fullscreenEnabled === true &&
       typeof targetElement.requestFullscreen === "function",
     isFullscreen,
+    isViewportExpanded,
     enterFullscreen,
     exitFullscreen,
     toggleFullscreen,

package/src/cctv/types/hook.ts

@@ -13,14 +13,26 @@ import type {
 import type { UseFormReturn } from "react-hook-form";
 import type { CctvBaseContext } from "./context";
 
+/**
+ * CCTV; 전체화면 미지원 환경의 확대 정책
+ * @property {"viewport"} [fallback] "viewport"는 표준 API 미지원 시 서비스의 전체창 확대 스타일을 사용한다. 생략하면 표준 API만 사용한다.
+ */
+export interface UseCctvFullscreenParams {
+  /**
+   * "viewport"는 미지원 환경의 전체창 확대를 허용한다. 생략하면 기존 viewer를 유지한다.
+   */
+  fallback?: "viewport";
+}
+
 /**
  * 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과 성공 여부
+ * @property {boolean} isViewportExpanded 표준 전체화면 대신 서비스의 전체창 확대 스타일을 적용할 상태
+ * @property {() => Promise<boolean>} enterFullscreen 대상 전체화면 또는 허용한 전체창 확대 진입 action과 성공 여부
+ * @property {() => Promise<boolean>} exitFullscreen 현재 대상 소유 전체화면·전체창 확대 종료 action과 성공 여부
+ * @property {() => Promise<boolean>} toggleFullscreen 현재 대상의 전체화면·전체창 확대 진입·종료 action과 성공 여부
  */
 export interface UseCctvFullscreenReturn {
   /**
@@ -36,17 +48,21 @@ export interface UseCctvFullscreenReturn {
    */
   isFullscreen: boolean;
   /**
-   * 대상 전체화면 진입 action
+   * 서비스가 대상 container에 전체창 확대 스타일을 적용할 상태. 브라우저 전체화면 상태와 구분한다.
+   */
+  isViewportExpanded: boolean;
+  /**
+   * 대상 전체화면 또는 허용한 전체창 확대 진입 action
    * @return 진입 요청 성공 여부
    */
   enterFullscreen: () => Promise<boolean>;
   /**
-   * 현재 대상 소유 전체화면 종료 action
+   * 현재 대상 소유 전체화면·전체창 확대 종료 action
    * @return 종료 요청 성공 여부
    */
   exitFullscreen: () => Promise<boolean>;
   /**
-   * 현재 대상의 전체화면 진입·종료 action
+   * 현재 대상의 전체화면·전체창 확대 진입·종료 action
    * @return 요청 성공 여부
    */
   toggleFullscreen: () => Promise<boolean>;