@uniai-fe/uds-templates 0.3.14 → 0.4.0

package/README.md

@@ -29,6 +29,59 @@ Next.js 서비스에서 primitives와 동일한 방식으로 **Raw TypeScript**
   - **templates**는 레이아웃/플로우/상태 표현까지 담당하고,
   - API 호출, 인증 토큰 관리, 라우팅, i18n 등 비즈니스 로직은 서비스 앱에서 구현합니다.
 
+## 확인 완료 도구 목록
+
+- `/modal`
+  - `Modal.Provider`
+  - `Modal.StackProvider`
+  - `Modal.RouteReset`
+  - `Modal.useModal`
+  - `Modal.Alert`
+  - `Modal.Dialog`
+  - `createAlertModal`
+  - `createDialogModal`
+  - `modalStackAtom`
+  - `ModalState`
+  - `ModalStatePatch`
+  - `ModalProps`
+  - `ModalFooterButton`
+  - `AlertTemplateOptions`
+  - `DialogTemplateOptions`
+  - `UseModalReturn`
+- `/weather`
+  - `WeatherComponents.PageHeader`
+  - `WeatherPageHeaderContainer`
+  - `WeatherMockProvider`
+  - `weatherCoordinate`
+  - `useWeatherKorea`
+  - `useOpenWeatherMap`
+- `/cctv`
+  - `CCTV.Provider`
+  - `CCTV.CamList.Container`
+  - `CCTV.Video.Container`
+  - `CCTV.Video.Contents`
+  - `CCTV.Video.Overlay.Container`
+  - `CCTV.Pagination.Container`
+  - `CCTV.Pagination.List.Container`
+  - `CCTV.Pagination.Button.Prev`
+  - `CCTV.Pagination.Button.Next`
+  - `CCTV.Viewer.Desktop.Container`
+  - `useCctvCompanyData`
+  - `useCctvContext`
+  - `useCctvRtcStream`
+  - `getServerCompanyList`
+  - `getServerCctvToken`
+  - `postCctvRtcToken`
+- `/page-frame`
+  - `Frame`
+  - `Frame.Mobile`
+  - `MobileFrame`
+  - `Frame.Desktop`
+  - `DesktopFrame`
+  - `MobileFrameProps`
+  - `PageFrameDesktopNavProps`
+  - `SitemapDataType`
+
 ## 현재 제공 템플릿/모듈
 
 - `/auth/**`
@@ -42,6 +95,12 @@ Next.js 서비스에서 primitives와 동일한 방식으로 **Raw TypeScript**
 - `/modal/**`
   - ui-legacy 스택 기반 모달 Provider/Root/Container + 템플릿(`Modal.Alert`, `Modal.Dialog`)
   - Storybook(`apps/design-storybook/src/stories/templates/modal`)에서 Alert/Confirm 케이스를 검증한다.
+- `/weather/**`
+  - page-frame header utility에 결합되는 weather header 템플릿과 weather data hook/mock 도구를 제공한다.
+- `/cctv/**`
+  - finder/viewer/video/pagination 조합과 rtc/company-list API helper를 제공한다.
+- `/page-frame/**`
+  - mobile/desktop private route frame, nav/header/popup 조합을 제공한다.
 
 각 템플릿의 상세한 범위와 의사결정은 `CONTEXT-*.md` 문서에서 관리합니다.
 
@@ -142,7 +201,7 @@ ui-legacy에서 사용하던 모달 스택/옵션을 templates 레이어로 옮
 
 1. **Provider 1회 장착** — 서비스 레이아웃에서 `<Modal.Provider />`를 렌더합니다.
 2. **Route Reset 장착** — `<Modal.RouteReset />`을 Provider와 같은 레벨에서 렌더해 경로 변경 시 스택을 초기화합니다.
-3. **훅 사용** — `const { newModal, closeModal } = Modal.useModal();`
+3. **훅 사용** — `const { newModal, closeModal, hasBlockingModal } = Modal.useModal();`
 4. **템플릿 팩토리** — `Modal.Alert`, `Modal.Dialog`이 `ModalState` 객체를 반환하므로 `newModal(...)`에 그대로 전달합니다.
 
 ```tsx
@@ -211,6 +270,8 @@ export function ExampleActions() {
 ```
 
 - footer 버튼은 ui-legacy와 동일하게 `stackKey`, `role`, `defaultOptions/linkOptions` 구조로 관리하며, Alert(Text)/Dialog(Solid) 규격은 templates 내부에서 보장합니다.
+- `closeOnOutsideClick?: boolean`으로 overlay 클릭 닫힘을 제어할 수 있습니다. 기본값은 `true`입니다.
+- `preventRouteChange?: boolean`은 현재 열린 modal 중 route 변경 확인이 필요한 modal이 있는지 집계할 때 사용합니다. 서비스 앱은 `hasBlockingModal`을 읽어 공통 confirm UX를 연결할 수 있습니다.
 - Route Reset을 누락하면 이전 라우트의 모달 스택이 그대로 남으므로, layout 수준에서 Provider와 함께 반드시 렌더합니다.
 - 세부 가드레일·확장 기록은 `CONTEXT-MODAL.md`를 참고하고, 새 템플릿을 추가할 때 해당 문서를 선행 업데이트합니다.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniai-fe/uds-templates",
-  "version": "0.3.14",
+  "version": "0.4.0",
   "description": "UNIAI Design System; UI Templates Package",
   "type": "module",
   "private": false,

package/src/cctv/components/index.tsx

@@ -4,6 +4,9 @@ import CCTVProvider from "./Provider";
 import { CCTVVideo } from "./video";
 import { CCTVViewer } from "./viewer";
 
+/**
+ * CCTV Components; CCTV component namespace 집계
+ */
 export const CCTV = {
   Provider: CCTVProvider,
   Video: CCTVVideo,

package/src/cctv/index.tsx

@@ -1,5 +1,8 @@
 import "./index.scss";
 
+/**
+ * CCTV; viewer, cam-list, pagination, api/hook/jotai 도구를 함께 제공하는 엔트리
+ */
 export * from "./apis";
 export * from "./data";
 export * from "./components";

package/src/modal/components/alert/Template.tsx

@@ -38,6 +38,8 @@ export function createAlertModal<FormContext extends FieldValues>({
   showDelay,
   width,
   padding,
+  closeOnOutsideClick,
+  preventRouteChange,
   formContextOptions,
 }: AlertTemplateOptions<FormContext>): ModalState<FormContext> {
   const primary: ModalTemplateButtonSpec = confirm ?? {
@@ -51,6 +53,8 @@ export function createAlertModal<FormContext extends FieldValues>({
       showDelay,
       width,
       padding,
+      closeOnOutsideClick,
+      preventRouteChange,
       // 변경 설명: 템플릿 생성 시점의 FormContext 제네릭을 modalProps로 전달한다.
       formContextOptions,
       body: <AlertContents message={message} />,

package/src/modal/components/core/Root.tsx

@@ -39,8 +39,11 @@ export function ModalRoot({
   }, [modalProps.show, stackKey, updateModal]);
 
   const handleClose = useCallback(() => {
+    if (modalProps.closeOnOutsideClick === false) {
+      return;
+    }
     closeModal({ stackKey });
-  }, [closeModal, stackKey]);
+  }, [closeModal, modalProps.closeOnOutsideClick, stackKey]);
 
   const stopPropagation = useCallback(
     (event: React.MouseEvent<HTMLDivElement>) => {

package/src/modal/components/dialog/Template.tsx

@@ -78,6 +78,8 @@ export function createDialogModal<FormContext extends FieldValues>({
   showDelay,
   width,
   padding,
+  closeOnOutsideClick,
+  preventRouteChange,
   formContextOptions,
 }: DialogTemplateOptions<FormContext>): ModalState<FormContext> {
   const primary = resolveDialogPrimaryButton(confirm);
@@ -122,6 +124,8 @@ export function createDialogModal<FormContext extends FieldValues>({
       showDelay,
       width,
       padding,
+      closeOnOutsideClick,
+      preventRouteChange,
       // 변경 설명: 템플릿 생성 시점의 FormContext 제네릭을 modalProps로 전달한다.
       formContextOptions,
       header: headerNode ?? undefined,

package/src/modal/hooks/useModal.ts

@@ -29,6 +29,9 @@ const ensureDelay = (value?: number): number =>
 export function useModal(): UseModalReturn {
   const [modalStacks, updateModalStack] = useAtom(modalStackAtom);
   const modalStacksRef = useRef(modalStacks);
+  const hasBlockingModal = modalStacks.some(
+    stack => stack.modalProps.preventRouteChange === true,
+  );
 
   useEffect(() => {
     // 변경 설명: closeModal이 최신 stack 상태를 기준으로 대상을 찾도록 현재 스냅샷 ref를 동기화한다.
@@ -130,5 +133,5 @@ export function useModal(): UseModalReturn {
     [updateModalStack],
   );
 
-  return { modalStacks, newModal, updateModal, closeModal };
+  return { modalStacks, hasBlockingModal, newModal, updateModal, closeModal };
 }

package/src/modal/index.tsx

@@ -11,6 +11,9 @@ import {
   createDialogModal,
 } from "./components";
 
+/**
+ * Modal; namespace와 direct export를 함께 제공하는 modal 엔트리
+ */
 export const Modal = ModalNamespace;
 
 export {

package/src/modal/types/hooks.ts

@@ -26,6 +26,7 @@ export type CloseFlagState = {
 /**
  * useModal 훅 반환값.
  * @property {ModalState[]} modalStacks 현재 모달 스택 목록
+ * @property {boolean} hasBlockingModal route 변경 확인이 필요한 모달 존재 여부
  * @property {<FormContext extends FieldValues>(newStack: ModalState<FormContext>) => void} newModal 신규 모달 추가 함수
  * @property {<FormContext extends FieldValues>(nextStack: ModalStatePatch<FormContext>) => void} updateModal 스택 상태 갱신 함수
  * @property {(request: ModalCloseRequest) => void} closeModal close 제어 함수
@@ -35,6 +36,10 @@ export type UseModalReturn = {
    * 현재 모달 스택 목록
    */
   modalStacks: ModalState[];
+  /**
+   * route 변경 확인이 필요한 모달 존재 여부
+   */
+  hasBlockingModal: boolean;
   /**
    * 신규 모달 추가 함수
    */

package/src/modal/types/state.ts

@@ -17,6 +17,8 @@ export type ModalShowState = "init" | boolean;
  * @property {ReactNode} [footer] footer 콘텐츠
  * @property {number | string} [width] 커스텀 width
  * @property {StyleSpacingType} [padding] 커스텀 padding
+ * @property {boolean} [closeOnOutsideClick] overlay 클릭 close 허용 여부
+ * @property {boolean} [preventRouteChange] route 변경 전 확인 필요 여부
  * @property {UseFormProps<FormContext>} [formContextOptions] form context 옵션
  */
 export type ModalSections<
@@ -48,6 +50,14 @@ export type ModalSections<
    * - [상, 우, 하, 좌]
    */
   padding?: StyleSpacingType;
+  /**
+   * overlay 클릭 close 허용 여부
+   */
+  closeOnOutsideClick?: boolean;
+  /**
+   * route 변경 전 확인 필요 여부
+   */
+  preventRouteChange?: boolean;
   /**
    * form context 옵션
    * - 옵션이 활성화되면, Form.Provider 사용으로 간주하여 활성화시킴
@@ -69,6 +79,8 @@ export type ModalSections<
  * @property {ModalShowState} show 노출 상태
  * @property {number} [showDelay] close 후 제거 지연(ms)
  * @property {ModalFooterButton[]} [footerButtons] footer 버튼 스펙
+ * @property {boolean} [closeOnOutsideClick] overlay 클릭 close 허용 여부 (@see ModalSections)
+ * @property {boolean} [preventRouteChange] route 변경 전 확인 필요 여부 (@see ModalSections)
  * @property {UseFormProps<FormContext>} [formContextOptions] form context 옵션
  */
 export type ModalProps<

package/src/modal/types/templates.ts

@@ -56,6 +56,8 @@ export type ModalTemplateButtonSpec = {
  * @property {number} [showDelay] close 후 제거 지연(ms)
  * @property {number | string} [width] 커스텀 width
  * @property {StyleSpacingType} [padding] 커스텀 padding
+ * @property {boolean} [closeOnOutsideClick] overlay 클릭 close 허용 여부
+ * @property {boolean} [preventRouteChange] route 변경 전 확인 필요 여부
  */
 type ModalTemplateBase<
   FormContext extends FieldValues = Record<string, unknown>,
@@ -82,6 +84,14 @@ type ModalTemplateBase<
    * - [상, 우, 하, 좌]
    */
   padding?: StyleSpacingType;
+  /**
+   * overlay 클릭 close 허용 여부
+   */
+  closeOnOutsideClick?: boolean;
+  /**
+   * route 변경 전 확인 필요 여부
+   */
+  preventRouteChange?: boolean;
   /**
    * modal 내부 Form.Provider 옵션
    * - 타입 안정성은 Modal.Alert/Dialog 생성 시점 제네릭으로 보장한다.
@@ -99,6 +109,8 @@ type ModalTemplateBase<
  * @property {ReactNode} [footer] 커스텀 footer
  * @property {number | string} [width] 커스텀 width
  * @property {StyleSpacingType} [padding] 커스텀 padding
+ * @property {boolean} [closeOnOutsideClick] overlay 클릭 close 허용 여부
+ * @property {boolean} [preventRouteChange] route 변경 전 확인 필요 여부
  * @property {UseFormProps<FormContext>} [formContextOptions] modal 내부 Form.Provider 옵션
  */
 export type AlertTemplateOptions<
@@ -145,6 +157,8 @@ export type AlertTemplateOptions<
  * @property {ReactNode} [footer] 커스텀 footer
  * @property {number | string} [width] 커스텀 width
  * @property {StyleSpacingType} [padding] 커스텀 padding
+ * @property {boolean} [closeOnOutsideClick] overlay 클릭 close 허용 여부
+ * @property {boolean} [preventRouteChange] route 변경 전 확인 필요 여부
  * @property {UseFormProps<FormContext>} [formContextOptions] modal 내부 Form.Provider 옵션
  */
 export type DialogTemplateOptions<

package/src/page-frame/desktop/components/index.tsx

@@ -3,6 +3,9 @@ import Nav from "./nav";
 import Header from "./header";
 import Popup from "./popup";
 
+/**
+ * Page Frame Desktop Components; desktop frame namespace 집계
+ */
 const Frame = {
   Page: {
     ...Page,

package/src/page-frame/desktop/index.tsx

@@ -2,6 +2,9 @@ import "./index.scss";
 
 import Frame from "./components";
 
+/**
+ * Page Frame Desktop; desktop frame 엔트리
+ */
 export type * from "./types";
 export * from "./data/setting";
 

package/src/page-frame/index.tsx

@@ -1,6 +1,9 @@
 import { DesktopFrame } from "./desktop";
 import { MobileFrame } from "./mobile";
 
+/**
+ * Frame; desktop/mobile page-frame namespace 집계
+ */
 export * from "./mobile";
 export * from "./types";
 export * from "./desktop";

package/src/page-frame/mobile/components/index.tsx

@@ -2,6 +2,9 @@ import Page from "./page";
 import Header from "./header";
 import Navigation from "./navigation";
 
+/**
+ * Page Frame Mobile Components; mobile frame namespace 집계
+ */
 const Frame = {
   Page,
   Header,

package/src/page-frame/mobile/index.tsx

@@ -2,6 +2,9 @@ import "./index.scss";
 
 import { MobileFrame } from "./components/page/Frame";
 
+/**
+ * Page Frame Mobile; mobile frame 엔트리
+ */
 export type { MobileFrameProps } from "./types";
 export * from "./components";
 export { MobileFrame };

package/src/weather/components/index.tsx

@@ -1,5 +1,8 @@
 import WeatherPageHeaderContainer from "./page-header/Container";
 
+/**
+ * Weather Components; weather component namespace 집계
+ */
 const Weather = {
   PageHeader: WeatherPageHeaderContainer,
 };

package/src/weather/index.tsx

@@ -1,6 +1,9 @@
 // Weather UI 컴포넌트 전용 스타일을 로드한다.
 import "./styles/weather.scss";
 
+/**
+ * Weather; page-header 템플릿과 api/hook/jotai/mock 도구를 함께 제공하는 엔트리
+ */
 export * from "./utils";
 export * from "./apis";
 export * from "./jotai";