@uniai-fe/uds-templates 0.12.1 → 0.12.3

package/README.md

@@ -45,6 +45,31 @@ import { Frame, Modal } from "@uniai-fe/uds-templates";
 화면 방향 API를 지원하면 전체화면 동안 `landscape`를 요청하며, 종료·대상 제거 시
 고정을 해제해 기본 방향 정책으로 돌아간다. 세로 방향 복귀를 강제하지 않는다.
 방향 API 미지원·요청 거부는 전체화면 시청을 차단하지 않는다.
+표준 API 요청 성공 여부를 반환하며, 진입 요청 대기 중 대상이 교체·제거되면
+해당 대상의 가로 방향 고정을 추가로 요청하지 않는다.
+
+`useCctvFullscreen({ fallback: "viewport" })`는 iPhone·iPad에서 표준 Fullscreen API를
+호출하지 않고 페이지 안 전체창 확대로 바로 진입한다. Mac·Windows·Android와 그 외 환경은
+표준 API를 사용하며, 미지원·요청 거부 시 전체창 확대로 전환하지 않는다.
+기기 판정은 기존 `checkAppleDevice`와 iPhone·iPad UA를 사용하고, Macintosh UA의 iPad는
+`maxTouchPoints > 1`로 보완한다. UA·터치 정보에 기반한 판정이므로 위장된 UA까지 보장하지 않는다.
+`isFullscreenSupported`와 `isFullscreen`은
+표준 API의 의미를 유지하며, 전체창 확대는 `isViewportExpanded`로 구분한다.
+옵션을 생략하면 iPhone·iPad도 표준 API만 사용한다.
+전체창 확대는 현재 연결된 대상만 허용하며, 다른 viewer가 전체화면·전체창 확대를 소유하면
+진입하지 않는다.
+
+서비스는 같은 `targetRef` container에 `isViewportExpanded`에 따른 viewport 고정,
+크기·안전 영역·반응형 스타일을 적용한다. 브라우저 UI를 숨기거나 기기 방향을 강제하지 않는다.
+진입·종료 action은 두 방식을 처리하므로 버튼의 활성 상태에는
+`isFullscreen || isViewportExpanded`를 사용한다. 전체창 확대를 선택한 서비스는
+표준 API 지원 여부로 해당 버튼을 숨기지 않는다.
+
+Hook은 전체창 확대 동안 배경 scroll과 대상 바깥의 focus를 제한한다. 확대 종료 버튼,
+Escape, 대상 교체·제거 또는 unmount로 종료하면 기존 overflow·inert·tabindex와
+연결된 진입 control의 focus를 복원한다. 카메라 전환은 container를 유지하며, DOM을
+다른 부모로 이동하거나 영상을 다시 만들지 않는다. 같은 document에서는 한 Hook만
+전체창 확대를 소유한다.
 
 ## Styles
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniai-fe/uds-templates",
-  "version": "0.12.1",
+  "version": "0.12.3",
   "description": "UNIAI Design System; UI Templates Package",
   "type": "module",
   "private": false,
@@ -68,16 +68,16 @@
     "sass": "^1.101.7",
     "typescript": "6.0.3",
     "@uniai-fe/next-devkit": "0.4.0",
+    "@uniai-fe/react-hooks": "0.3.0",
+    "@uniai-fe/tsconfig": "0.2.0",
     "@uniai-fe/eslint-config": "0.4.2",
+    "@uniai-fe/uds-foundation": "0.6.0",
     "@uniai-fe/uds-primitives": "0.12.5",
-    "@uniai-fe/util-jotai": "0.3.0",
-    "@uniai-fe/react-hooks": "0.3.0",
+    "@uniai-fe/util-next": "0.5.0",
     "@uniai-fe/util-api": "0.2.1",
-    "@uniai-fe/tsconfig": "0.2.0",
+    "@uniai-fe/util-jotai": "0.3.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"
+    "@uniai-fe/util-functions": "0.4.3"
   },
   "scripts": {
     "check:pre-commit": "pnpm --dir ../../.. run check:pre-commit",

package/src/cctv/hooks/useFullscreen.ts

@@ -1,24 +1,43 @@
 "use client";
 
 import { useCallback, useEffect, useRef, useState } from "react";
-import type { UseCctvFullscreenReturn } from "../types";
+import { checkAppleDevice } from "@uniai-fe/util-functions/runtime-env";
+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를 복원한다.
+ * 외부 종료 후에는 진입 전 focus를 복원하며, 표준 API 요청 실패는 기존 viewer를 유지한다.
  * 지원 환경에서는 진입 후 가로 방향을 요청하고 종료·대상 제거 시 기본 방향 정책으로 돌려준다.
  * 방향 요청 실패는 전체화면 성공에 영향을 주지 않으며 종료 후 세로 방향을 강제하지 않는다.
+ * fallback이 "viewport"이면 iPhone·iPad에서 표준 API 대신 전체창 확대와 배경 scroll·focus를 관리한다.
+ * 그 외 환경과 옵션을 생략한 호출은 표준 API를 사용한다.
+ * 실제 확대 layout은 서비스가 isViewportExpanded로 적용하며 영상 DOM을 이동하거나 다시 만들지 않는다.
+ * @param {UseCctvFullscreenParams} options iPhone·iPad의 확대 정책
+ * @property {"viewport"} [options.fallback] "viewport"는 iPhone·iPad에서 전체창 확대를 사용한다. 생략하면 표준 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);
 
   const releaseOrientation = useCallback(() => {
     const unlock = unlockOrientationRef.current;
@@ -30,22 +49,6 @@ export function useCctvFullscreen(): UseCctvFullscreenReturn {
     }
   }, []);
 
-  /**
-   * 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를 돌려보낸다.
    */
@@ -54,10 +57,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;
 
@@ -98,6 +128,9 @@ export function useCctvFullscreen(): UseCctvFullscreenReturn {
       );
 
       releaseOrientation();
+      if (viewportSessionRef.current?.target === targetElement) {
+        exitViewportExpansion();
+      }
       if (ownerDocument.fullscreenElement === targetElement) {
         void ownerDocument.exitFullscreen().catch(() => undefined);
       }
@@ -108,32 +141,150 @@ export function useCctvFullscreen(): UseCctvFullscreenReturn {
 
       wasFullscreenRef.current = false;
     };
-  }, [releaseOrientation, restoreEntryFocus, targetElement]);
+  }, [
+    exitViewportExpansion,
+    releaseOrientation,
+    restoreEntryFocus,
+    targetElement,
+  ]);
 
   /**
-   * 현재 service target의 표준 전체화면 진입을 요청한다.
+   * iPhone·iPad의 선택한 전체창 확대와 나머지 환경의 표준 전체화면을 구분한다.
    */
   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;
+    const deviceNavigator = ownerDocument.defaultView?.navigator;
+    const userAgent = deviceNavigator?.userAgent ?? "";
+    // iPad의 데스크톱 UA는 Mac과 같으므로 Macintosh UA에 한해 다중 터치 정보를 보완한다.
+    const isIPhoneOrIPad: boolean =
+      checkAppleDevice(userAgent) &&
+      (/\((?:iPhone|iPad)(?:;|\))/i.test(userAgent) ||
+        (/Macintosh/i.test(userAgent) &&
+          (deviceNavigator?.maxTouchPoints ?? 0) > 1));
+    const useViewport: boolean = fallback === "viewport" && isIPhoneOrIPad;
+    const isNativeSupported =
+      ownerDocument.fullscreenEnabled &&
+      typeof target.requestFullscreen === "function";
+    if (!useViewport && !isNativeSupported) 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 (useViewport) {
+      if (
+        !target.isConnected ||
+        ownerDocument.fullscreenElement ||
+        viewportOwners.has(ownerDocument)
+      )
+        return false;
+      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();
       const orientation = target.ownerDocument.defaultView?.screen.orientation;
@@ -160,12 +311,13 @@ export function useCctvFullscreen(): UseCctvFullscreenReturn {
       entryFocusRef.current = null;
       return false;
     }
-  }, []);
+  }, [exitViewportExpansion, fallback]);
 
   /**
    * 다른 element의 전체화면은 건드리지 않고 현재 target 소유 상태만 종료한다.
    */
   const exitFullscreen = useCallback(async () => {
+    if (exitViewportExpansion()) return true;
     const target = targetElementRef.current;
 
     if (
@@ -183,7 +335,7 @@ export function useCctvFullscreen(): UseCctvFullscreenReturn {
     } catch {
       return false;
     }
-  }, [releaseOrientation]);
+  }, [exitViewportExpansion, releaseOrientation]);
 
   /**
    * 현재 document 소유 상태에 따라 target의 진입 또는 종료 action을 선택한다.
@@ -191,7 +343,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();
     }
 
@@ -202,9 +357,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; iPhone·iPad의 확대 정책
+ * @property {"viewport"} [fallback] "viewport"는 iPhone·iPad에서 표준 API 대신 서비스의 전체창 확대 스타일을 사용한다. 그 외 환경과 생략한 호출은 표준 API만 사용한다.
+ */
+export interface UseCctvFullscreenParams {
+  /**
+   * "viewport"는 iPhone·iPad에서 전체창 확대로 바로 진입한다. 그 외 환경과 생략한 호출은 표준 API만 사용한다.
+   */
+  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>;