@uniai-fe/uds-templates 0.12.2 → 0.12.3

package/README.md

@@ -45,13 +45,19 @@ import { Frame, Modal } from "@uniai-fe/uds-templates";
 화면 방향 API를 지원하면 전체화면 동안 `landscape`를 요청하며, 종료·대상 제거 시
 고정을 해제해 기본 방향 정책으로 돌아간다. 세로 방향 복귀를 강제하지 않는다.
 방향 API 미지원·요청 거부는 전체화면 시청을 차단하지 않는다.
-진입 요청 대기 중 대상이 교체·제거되면 늦게 열린 이전 대상의 전체화면을 종료하고
-`false`를 반환한다. 다른 대상이 소유한 전체화면은 유지한다.
-
-`useCctvFullscreen({ fallback: "viewport" })`는 표준 Fullscreen API 미지원 시
-페이지 안 전체창 확대를 허용한다. `isFullscreenSupported`와 `isFullscreen`은
+표준 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`로 구분한다.
-옵션을 생략하면 기존 동작을 유지하고, 표준 API 요청이 거부된 경우에는 확대하지 않는다.
+옵션을 생략하면 iPhone·iPad도 표준 API만 사용한다.
+전체창 확대는 현재 연결된 대상만 허용하며, 다른 viewer가 전체화면·전체창 확대를 소유하면
+진입하지 않는다.
 
 서비스는 같은 `targetRef` container에 `isViewportExpanded`에 따른 viewport 고정,
 크기·안전 영역·반응형 스타일을 적용한다. 브라우저 UI를 숨기거나 기기 방향을 강제하지 않는다.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniai-fe/uds-templates",
-  "version": "0.12.2",
+  "version": "0.12.3",
   "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/next-devkit": "0.4.0",
     "@uniai-fe/react-hooks": "0.3.0",
-    "@uniai-fe/eslint-config": "0.4.2",
     "@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/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"
+    "@uniai-fe/util-api": "0.2.1",
+    "@uniai-fe/util-jotai": "0.3.0",
+    "@uniai-fe/util-rtc": "0.2.1",
+    "@uniai-fe/util-functions": "0.4.3"
   },
   "scripts": {
     "check:pre-commit": "pnpm --dir ../../.. run check:pre-commit",

package/src/cctv/hooks/useFullscreen.ts

@@ -1,6 +1,7 @@
 "use client";
 
 import { useCallback, useEffect, useRef, useState } from "react";
+import { checkAppleDevice } from "@uniai-fe/util-functions/runtime-env";
 import type {
   UseCctvFullscreenParams,
   UseCctvFullscreenReturn,
@@ -13,14 +14,14 @@ 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"이면 표준 API 미지원 시 전체창 확대 상태와 배경 scroll·focus를 관리한다.
+ * fallback이 "viewport"이면 iPhone·iPad에서 표준 API 대신 전체창 확대와 배경 scroll·focus를 관리한다.
+ * 그 외 환경과 옵션을 생략한 호출은 표준 API를 사용한다.
  * 실제 확대 layout은 서비스가 isViewportExpanded로 적용하며 영상 DOM을 이동하거나 다시 만들지 않는다.
- * 표준 API 요청 거부는 전체창 확대로 전환하지 않는다.
- * @param {UseCctvFullscreenParams} options 미지원 환경의 확대 정책
- * @property {"viewport"} [options.fallback] "viewport"는 전체창 확대를 허용한다. 생략하면 표준 API만 사용한다.
+ * @param {UseCctvFullscreenParams} options iPhone·iPad의 확대 정책
+ * @property {"viewport"} [options.fallback] "viewport"는 iPhone·iPad에서 전체창 확대를 사용한다. 생략하면 표준 API만 사용한다.
  * @return {UseCctvFullscreenReturn} 대상 ref callback과 전체화면 상태·action
  */
 export function useCctvFullscreen({
@@ -148,7 +149,7 @@ export function useCctvFullscreen({
   ]);
 
   /**
-   * 표준 API를 우선하며 미지원일 때만 선택한 전체창 확대를 시작한다.
+   * iPhone·iPad의 선택한 전체창 확대와 나머지 환경의 표준 전체화면을 구분한다.
    */
   const enterFullscreen = useCallback(async () => {
     const target = targetElementRef.current;
@@ -163,18 +164,19 @@ export function useCctvFullscreen({
     }
 
     const ownerDocument = target.ownerDocument;
-    if (viewportOwners.has(ownerDocument)) return false;
+    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 (
-      !isNativeSupported &&
-      (fallback !== "viewport" ||
-        !target.isConnected ||
-        ownerDocument.fullscreenElement)
-    ) {
-      return false;
-    }
+    if (!useViewport && !isNativeSupported) return false;
     const activeElement = ownerDocument.activeElement;
     const ElementConstructor = ownerDocument.defaultView?.HTMLElement;
     entryFocusRef.current =
@@ -182,7 +184,13 @@ export function useCctvFullscreen({
         ? activeElement
         : null;
 
-    if (!isNativeSupported) {
+    if (useViewport) {
+      if (
+        !target.isConnected ||
+        ownerDocument.fullscreenElement ||
+        viewportOwners.has(ownerDocument)
+      )
+        return false;
       const restores: (() => void)[] = [];
       viewportOwners.set(ownerDocument, target);
 
@@ -279,15 +287,9 @@ export function useCctvFullscreen({
 
     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 (
+        targetElementRef.current === target &&
         target.ownerDocument.fullscreenElement === target &&
         typeof orientation?.lock === "function" &&
         typeof orientation.unlock === "function"

package/src/cctv/types/hook.ts

@@ -14,12 +14,12 @@ import type { UseFormReturn } from "react-hook-form";
 import type { CctvBaseContext } from "./context";
 
 /**
- * CCTV; 전체화면 미지원 환경의 확대 정책
- * @property {"viewport"} [fallback] "viewport"는 표준 API 미지원 시 서비스의 전체창 확대 스타일을 사용한다. 생략하면 표준 API만 사용한다.
+ * CCTV; iPhone·iPad의 확대 정책
+ * @property {"viewport"} [fallback] "viewport"는 iPhone·iPad에서 표준 API 대신 서비스의 전체창 확대 스타일을 사용한다. 그 외 환경과 생략한 호출은 표준 API만 사용한다.
  */
 export interface UseCctvFullscreenParams {
   /**
-   * "viewport"는 미지원 환경의 전체창 확대를 허용한다. 생략하면 기존 viewer를 유지한다.
+   * "viewport"는 iPhone·iPad에서 전체창 확대로 바로 진입한다. 그 외 환경과 생략한 호출은 표준 API만 사용한다.
    */
   fallback?: "viewport";
 }