@uniai-fe/uds-templates

Primitives를 조합한 반복 화면 구조와 UI flow를 제공한다. 공통 책임과 convention은 ../DESIGN-SYSTEM-GUIDE.md를 따른다.

API 호출, 비즈니스 판단, routing, i18n, 인증·권한은 Service가 소유한다.

설치

현재 peer range는 package.json이 권위다.

pnpm add @uniai-fe/uds-foundation @uniai-fe/uds-primitives @uniai-fe/uds-templates

Raw TypeScript package를 사용하는 Next.js 앱은 현재 package contract에 맞게 transpilePackages를 설정한다.

const nextConfig = {
  transpilePackages: [
    "@uniai-fe/uds-foundation",
    "@uniai-fe/uds-primitives",
    "@uniai-fe/uds-templates",
  ],
};

export default nextConfig;

Public entries

Template component, type와 hook은 root public entry에서 가져온다. 실제 공개 범위는 package.json exports와 public barrel이 권위다.

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 미지원·요청 거부는 전체화면 시청을 차단하지 않는다. 표준 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만 전체창 확대를 소유한다.

뷰어의 영상 하단에는 CCTV.Video.Overlay.Footer.FullscreenButton을 명시적으로 조립한다. 센서 배지는 왼쪽, 버튼은 오른쪽에 배치되며 isExpanded에 따라 제공된 아이콘과 크게 보기/작게 보기 문구를 전환한다. expandLabel·collapseLabel로 서비스 번역을 주입한다. 캠 리스트나 기본 footer에 자동으로 추가되지 않는다.

<CCTV.Video.Overlay.Footer.Container activeTitle={false}>
  {metrics}
  <CCTV.Video.Overlay.Footer.FullscreenButton
    isExpanded={isFullscreen || isViewportExpanded}
    onToggle={toggleFullscreen}
    expandLabel={t("cctv.fullscreen.expand")}
    collapseLabel={t("cctv.fullscreen.collapse")}
  />
</CCTV.Video.Overlay.Footer.Container>

모달 헤더의 원형 닫기는 ModalHeaderCloseButton을 공개 entry에서 재사용할 수 있다. 기본 Dialog 헤더도 같은 32px 아이콘을 사용하며 닫기 action은 기존 계약을 유지한다.

Styles

CSS consumer는 dependency order대로 각 public entry를 로드한다.

import "@uniai-fe/uds-foundation/css";
import "@uniai-fe/uds-primitives/css";
import "@uniai-fe/uds-templates/css";

@use "@uniai-fe/uds-foundation/scss";
@use "@uniai-fe/uds-primitives/styles";
@use "@uniai-fe/uds-templates/styles";

Templates style entry는 Foundation/Primitives를 대신 로드하지 않는다.

Package-local docs

• docs/CONTEXT-INDEX.md: category별 append-only 작업 이력 routing
• docs/CONTEXT-GUIDELINES.md: 과거 전역 기록과 최신 priority delta
• docs/DESIGN-TEMPLATES-SESSION-GUIDE.md: 작업 세션 입력과 실행 순서
• docs/STORYBOOK.md: Templates Story routing
• 그 외 docs/CONTEXT*.md: category·issue별 근거와 시행착오

Commands

pnpm format:check
pnpm lint
pnpm typecheck
pnpm check