@uniai-fe/uds-templates 0.5.0 → 0.5.1

package/README.md

@@ -98,6 +98,14 @@ Next.js 서비스에서 primitives와 동일한 방식으로 **Raw TypeScript**
   - `MobileFrameProps`
   - `PageFrameDesktopNavProps`
   - `SitemapDataType`
+- `/edge-case`
+  - `EdgeCase`
+  - `EdgeCase.Empty`
+  - `EdgeCase.Loading`
+  - `EdgeCase.NotFound`
+  - `EdgeCaseEmptyProps`
+  - `EdgeCaseLoadingProps`
+  - `EdgeCaseNotFoundProps`
 
 ## 현재 제공 템플릿/모듈
 
@@ -126,6 +134,9 @@ Next.js 서비스에서 primitives와 동일한 방식으로 **Raw TypeScript**
   - finder/viewer/video/pagination 조합과 rtc/company-list API helper를 제공한다.
 - `/page-frame/**`
   - mobile/desktop private route frame, nav/header/popup 조합을 제공한다.
+- `/edge-case/**`
+  - empty/loading/not-found 화면 상태 템플릿을 제공한다.
+  - primitives `Alternate.Layout.*`를 조합하며, 실제 routing/history 판정은 서비스 앱이 소유한다.
 
 각 템플릿의 상세한 범위와 의사결정은 `CONTEXT-*.md` 문서에서 관리합니다.
 
@@ -225,6 +236,7 @@ export default function LoginPage() {
 
 - Modal CSS 변수 네임스페이스를 `--modal-*`, `--modal-alert-*`, `--modal-dialog-*` 세 축으로 통일했다. 기존 `--dialog-*` 이름을 사용하지 말고, Auth 템플릿이 Alert을 호출할 때에는 반드시 `Modal.Alert` 팩토리를 통해 렌더링한다.
 - Auth(회원가입/아이디 찾기/비밀번호 찾기) 템플릿은 이메일 인증 타이머 5분, alert 문구, readonly 이메일 필드, 완료 단계 헤더 제거 등 최신 플로우를 반영했다. 모듈에서 `window.alert`/`window.confirm`을 호출하지 않고, 서비스 앱이 Modal helper를 주입하는 구조를 README와 `CONTEXT-AUTH*.md`에 명시했다.
+- Edge Case 템플릿은 `EdgeCase.Empty`, `EdgeCase.Loading`, `EdgeCase.NotFound` namespace로 공개한다. `NotFound`는 `onPrev` 또는 `fallbackHref="/"`를 연결하지만 `router.back()`이나 service-origin 판정은 실행하지 않는다.
 
 ### 토큰 스코프 & ThemeProvider
 

package/dist/styles.css

@@ -1923,3 +1923,52 @@
 .page-frame-inquiry-button {
   margin-top: auto;
 }
+
+.edge-case {
+  width: 100%;
+}
+
+.edge-case:where([data-edge-case=not-found]) {
+  --alternate-layout-gap: var(--spacing-gap-3);
+  --alternate-layout-figure-size: 128px;
+  --alternate-layout-title-color: var(--color-label-standard);
+  --alternate-layout-title-font-size: var(--font-heading-xsmall-size);
+  --alternate-layout-title-line-height: var(--font-heading-xsmall-line-height);
+  --alternate-layout-title-letter-spacing: var(
+    --font-heading-xsmall-letter-spacing
+  );
+  --alternate-layout-title-font-weight: var(--font-heading-xsmall-weight);
+  --alternate-layout-contents-font-size: var(--font-body-xsmall-size);
+  --alternate-layout-contents-line-height: var(--font-body-xsmall-line-height);
+  --alternate-layout-contents-letter-spacing: var(
+    --font-body-xsmall-letter-spacing
+  );
+  --alternate-layout-contents-font-weight: var(--font-body-xsmall-weight);
+  --button-default-font-label-medium-size: var(--font-label-small-size);
+  --button-default-font-label-medium-line-height: var(
+    --font-label-small-line-height
+  );
+  --button-default-font-label-medium-letter-spacing: var(
+    --font-label-small-letter-spacing
+  );
+  --button-default-font-label-medium-weight: var(--font-label-small-weight);
+  --button-default-font-weight: var(--font-label-small-weight);
+  min-height: 0;
+  padding: calc(var(--spacing-padding-11) + var(--spacing-padding-7)) var(--spacing-padding-8);
+  border: 1px solid var(--color-border-assistive);
+  border-radius: var(--theme-radius-large-1);
+  background: var(--color-common-100);
+  justify-content: flex-start;
+}
+.edge-case:where([data-edge-case=not-found]) :where(.alternate-layout-figure) {
+  margin-bottom: var(--spacing-gap-3);
+}
+.edge-case:where([data-edge-case=not-found]) :where(.alternate-layout-contents) {
+  white-space: nowrap;
+}
+.edge-case:where([data-edge-case=not-found]) :where(.alternate-layout-contents) :where(p + p) {
+  margin-top: var(--spacing-gap-3);
+}
+.edge-case:where([data-edge-case=not-found]) :where(.alternate-layout-button) {
+  margin-top: var(--spacing-gap-3);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniai-fe/uds-templates",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "UNIAI Design System; UI Templates Package",
   "type": "module",
   "private": false,
@@ -70,7 +70,7 @@
   },
   "devDependencies": {
     "@svgr/webpack": "^8.1.0",
-    "@tanstack/react-query": "^5.97.0",
+    "@tanstack/react-query": "^5.99.0",
     "@types/node": "^24.10.2",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
@@ -88,9 +88,9 @@
     "eslint": "^9.39.2",
     "jotai": "^2.19.1",
     "next": "^15.5.11",
-    "prettier": "^3.8.2",
+    "prettier": "^3.8.3",
     "react-hook-form": "^7.72.1",
     "sass": "^1.99.0",
-    "typescript": "~5.9.3"
+    "typescript": "5.9.3"
   }
 }

package/src/edge-case/EdgeCase.tsx

@@ -0,0 +1,16 @@
+import { EdgeCaseEmpty, EdgeCaseLoading, EdgeCaseNotFound } from "./components";
+
+/**
+ * Edge Case; empty/loading/not-found 화면 상태 namespace
+ * @desc
+ * - `EdgeCase.Empty`: 빈 상태 화면 조합이다.
+ * - `EdgeCase.Loading`: 로딩 상태 화면 조합이다.
+ * - `EdgeCase.NotFound`: not-found 상태 화면 조합이다.
+ */
+const EdgeCase = {
+  Empty: EdgeCaseEmpty,
+  Loading: EdgeCaseLoading,
+  NotFound: EdgeCaseNotFound,
+};
+
+export default EdgeCase;

package/src/edge-case/components/Empty.tsx

@@ -0,0 +1,42 @@
+"use client";
+
+import { clsx } from "clsx";
+import { Alternate } from "@uniai-fe/uds-primitives";
+import type { EdgeCaseEmptyProps } from "../types";
+
+/**
+ * Edge Case Empty; 빈 상태 화면 템플릿
+ * @component
+ * @param {EdgeCaseEmptyProps} props
+ * @param {string} [props.className] 최상위 edge-case container className override다.
+ * @param {React.ReactNode} [props.figure] 빈 상태를 보조하는 visual 콘텐츠다.
+ * @param {React.ReactNode} props.title 빈 상태 제목 콘텐츠다.
+ * @param {React.ReactNode} [props.description] 빈 상태 설명 콘텐츠다.
+ * @param {React.ReactNode} [props.children] 하단에 주입할 custom action 또는 보조 콘텐츠다.
+ * @example
+ * <EdgeCase.Empty title="조회 결과가 없습니다." description="다른 조건으로 다시 검색해 주세요." />
+ */
+export default function EdgeCaseEmpty({
+  className,
+  figure,
+  title,
+  description,
+  children,
+}: EdgeCaseEmptyProps) {
+  return (
+    <Alternate.Layout.Container
+      className={clsx("edge-case", className)}
+      data-edge-case="empty"
+    >
+      {figure ? (
+        <Alternate.Layout.Figure>{figure}</Alternate.Layout.Figure>
+      ) : null}
+      <Alternate.Layout.Title>{title}</Alternate.Layout.Title>
+      {description ? (
+        <Alternate.Layout.Contents>{description}</Alternate.Layout.Contents>
+      ) : null}
+      {/* 변경: templates는 action 정책을 확정하지 않고 소비 측 주입 지점만 연다. */}
+      {children}
+    </Alternate.Layout.Container>
+  );
+}

package/src/edge-case/components/Loading.tsx

@@ -0,0 +1,42 @@
+"use client";
+
+import { clsx } from "clsx";
+import { Alternate } from "@uniai-fe/uds-primitives";
+import type { EdgeCaseLoadingProps } from "../types";
+
+/**
+ * Edge Case Loading; 로딩 상태 화면 템플릿
+ * @component
+ * @param {EdgeCaseLoadingProps} props
+ * @param {string} [props.className] 최상위 edge-case container className override다.
+ * @param {React.ReactNode} [props.figure] 로딩 상태 visual 콘텐츠다.
+ * @param {React.ReactNode} [props.title] 로딩 상태 제목 콘텐츠다.
+ * @param {React.ReactNode} [props.description] 로딩 상태 설명 콘텐츠다.
+ * @param {React.ReactNode} [props.children] 하단에 주입할 custom action 또는 보조 콘텐츠다.
+ * @example
+ * <EdgeCase.Loading title="불러오는 중입니다." />
+ */
+export default function EdgeCaseLoading({
+  className,
+  figure,
+  title,
+  description,
+  children,
+}: EdgeCaseLoadingProps) {
+  return (
+    <Alternate.Layout.Container
+      className={clsx("edge-case", className)}
+      data-edge-case="loading"
+    >
+      <Alternate.Layout.Figure>
+        {figure ?? <Alternate.LoadingIcon size="large" direction="vertical" />}
+      </Alternate.Layout.Figure>
+      {title ? <Alternate.Layout.Title>{title}</Alternate.Layout.Title> : null}
+      {description ? (
+        <Alternate.Layout.Contents>{description}</Alternate.Layout.Contents>
+      ) : null}
+      {/* 변경: 로딩 취소/재시도 같은 정책은 서비스 앱이 children으로 주입한다. */}
+      {children}
+    </Alternate.Layout.Container>
+  );
+}

package/src/edge-case/components/NotFound.tsx

@@ -0,0 +1,74 @@
+"use client";
+
+import { clsx } from "clsx";
+import { Alternate } from "@uniai-fe/uds-primitives";
+import NotFoundIcon from "../img/404.svg";
+import type { EdgeCaseNotFoundProps } from "../types";
+
+/**
+ * Edge Case Not Found; not-found 상태 화면 템플릿
+ * @component
+ * @param {EdgeCaseNotFoundProps} props
+ * @param {string} [props.className] 최상위 edge-case container className override다.
+ * @param {string} [props.inquiryHref] 문의 text action을 link로 렌더링할 href다.
+ * @param {() => void} [props.onInquiry] 문의 text action을 button으로 렌더링할 콜백이다.
+ * @param {string} [props.fallbackHref] onPrev가 없을 때 사용할 fallback href다.
+ * @param {() => void} [props.onPrev] 이전 페이지 이동을 소비 앱에서 실행하는 콜백이다.
+ * @example
+ * <EdgeCase.NotFound onPrev={() => router.back()} />
+ */
+export default function EdgeCaseNotFound({
+  className,
+  inquiryHref,
+  onInquiry,
+  fallbackHref = "/",
+  onPrev,
+}: EdgeCaseNotFoundProps) {
+  return (
+    <Alternate.Layout.Container
+      className={clsx("edge-case", className)}
+      data-edge-case="not-found"
+    >
+      <Alternate.Layout.Figure>
+        <NotFoundIcon
+          width={128}
+          height={128}
+          viewBox="0 0 128 128"
+          aria-hidden="true"
+        />
+      </Alternate.Layout.Figure>
+      <Alternate.Layout.Title as="h1">
+        이 페이지를 찾을 수 없습니다.
+      </Alternate.Layout.Title>
+      <Alternate.Layout.Contents>
+        <p>
+          페이지가 이동되었거나 삭제되었을 수 있습니다.
+          <br />
+          페이지 주소를 다시 확인해 주세요.
+        </p>
+        {/* 변경: NotFound 본문 줄바꿈은 폭 제한이 아니라 Figma fixed copy의 br로 고정한다. */}
+        {onInquiry || inquiryHref ? (
+          <p>
+            관련된 문의사항은{" "}
+            <Alternate.Layout.TextButton href={inquiryHref} onClick={onInquiry}>
+              문의하기
+            </Alternate.Layout.TextButton>
+            를 통해
+            <br />
+            접수해 주시길 바랍니다.
+          </p>
+        ) : null}
+      </Alternate.Layout.Contents>
+      {/* 변경: router/history 판정은 내부에서 실행하지 않고 onPrev 또는 fallback href만 연결한다. */}
+      {onPrev ? (
+        <Alternate.Layout.Button onClick={onPrev}>
+          이전 페이지로
+        </Alternate.Layout.Button>
+      ) : (
+        <Alternate.Layout.Button as="a" href={fallbackHref}>
+          이전 페이지로
+        </Alternate.Layout.Button>
+      )}
+    </Alternate.Layout.Container>
+  );
+}

package/src/edge-case/components/index.tsx

@@ -0,0 +1,3 @@
+export { default as EdgeCaseEmpty } from "./Empty";
+export { default as EdgeCaseLoading } from "./Loading";
+export { default as EdgeCaseNotFound } from "./NotFound";

package/src/edge-case/img/404.svg

@@ -0,0 +1,3 @@
+<svg width="128" height="128" viewBox="0 0 128 128" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path fill-rule="evenodd" clip-rule="evenodd" d="M60.6598 32.877C62.1862 30.3743 65.8137 30.3743 67.3401 32.877L103.419 92.0324C105.013 94.6459 103.137 97.9999 100.08 98H27.9197C24.8631 97.9996 22.9866 94.6458 24.5805 92.0324L60.6598 32.877ZM64.5227 81.3305C63.1717 81.3306 62.0762 82.4281 62.0762 83.7819C62.0762 85.1357 63.1716 86.2331 64.5227 86.2333C65.8736 86.2329 66.9693 85.1355 66.9693 83.7819C66.9692 82.4283 65.8735 81.3309 64.5227 81.3305ZM64.5227 49.5599C63.2257 49.5601 62.1737 50.6141 62.1736 51.9137V75.4471C62.1736 76.7467 63.2257 77.8007 64.5227 77.8008C65.8195 77.8004 66.8718 76.7466 66.8718 75.4471V51.9137C66.8717 50.6143 65.8195 49.5603 64.5227 49.5599Z" fill="#F43625"/>
+</svg>

package/src/edge-case/index.scss

@@ -0,0 +1 @@
+@use "./styles/index.scss" as edgeCaseStyles;

package/src/edge-case/index.tsx

@@ -0,0 +1,11 @@
+import "./index.scss";
+
+/**
+ * Edge Case; 화면 단위 예외 상태 템플릿 엔트리
+ * @desc
+ * - `EdgeCase.Empty`: 빈 상태 화면 조합이다.
+ * - `EdgeCase.Loading`: 로딩 상태 화면 조합이다.
+ * - `EdgeCase.NotFound`: not-found 상태 화면 조합이다.
+ */
+export { default as EdgeCase } from "./EdgeCase";
+export type * from "./types";

package/src/edge-case/styles/edge-case.scss

@@ -0,0 +1,56 @@
+.edge-case {
+  width: 100%;
+}
+
+.edge-case:where([data-edge-case="not-found"]) {
+  --alternate-layout-gap: var(--spacing-gap-3);
+  --alternate-layout-figure-size: 128px;
+  --alternate-layout-title-color: var(--color-label-standard);
+  --alternate-layout-title-font-size: var(--font-heading-xsmall-size);
+  --alternate-layout-title-line-height: var(--font-heading-xsmall-line-height);
+  --alternate-layout-title-letter-spacing: var(
+    --font-heading-xsmall-letter-spacing
+  );
+  --alternate-layout-title-font-weight: var(--font-heading-xsmall-weight);
+  --alternate-layout-contents-font-size: var(--font-body-xsmall-size);
+  --alternate-layout-contents-line-height: var(--font-body-xsmall-line-height);
+  --alternate-layout-contents-letter-spacing: var(
+    --font-body-xsmall-letter-spacing
+  );
+  --alternate-layout-contents-font-weight: var(--font-body-xsmall-weight);
+  --button-default-font-label-medium-size: var(--font-label-small-size);
+  --button-default-font-label-medium-line-height: var(
+    --font-label-small-line-height
+  );
+  --button-default-font-label-medium-letter-spacing: var(
+    --font-label-small-letter-spacing
+  );
+  --button-default-font-label-medium-weight: var(--font-label-small-weight);
+  --button-default-font-weight: var(--font-label-small-weight);
+
+  min-height: 0;
+  padding: calc(var(--spacing-padding-11) + var(--spacing-padding-7))
+    var(--spacing-padding-8);
+  border: 1px solid var(--color-border-assistive);
+  border-radius: var(--theme-radius-large-1);
+  background: var(--color-common-100);
+  justify-content: flex-start;
+
+  :where(.alternate-layout-figure) {
+    // 변경: not-found preset은 Alternate.Layout gap을 유지하되 Figma root gap 12px만 figure/button 쪽 margin으로 보정한다.
+    margin-bottom: var(--spacing-gap-3);
+  }
+
+  :where(.alternate-layout-contents) {
+    white-space: nowrap;
+
+    :where(p + p) {
+      // 변경: inquiry variant의 문의 문단은 Figma Text frame의 두 번째 content group gap 6px을 따른다.
+      margin-top: var(--spacing-gap-3);
+    }
+  }
+
+  :where(.alternate-layout-button) {
+    margin-top: var(--spacing-gap-3);
+  }
+}

package/src/edge-case/styles/index.scss

@@ -0,0 +1 @@
+@use "./edge-case.scss";

package/src/edge-case/types/index.ts

@@ -0,0 +1,94 @@
+import type { ReactNode } from "react";
+
+/**
+ * Edge Case Empty Props; 빈 상태 화면 템플릿 props
+ * @property {string} [className] 최상위 edge-case container className override다.
+ * @property {ReactNode} [figure] 빈 상태를 보조하는 visual 콘텐츠다.
+ * @property {ReactNode} title 빈 상태 제목 콘텐츠다.
+ * @property {ReactNode} [description] 빈 상태 설명 콘텐츠다.
+ * @property {ReactNode} [children] 하단에 주입할 custom action 또는 보조 콘텐츠다.
+ */
+export interface EdgeCaseEmptyProps {
+  /**
+   * 최상위 edge-case container className override다.
+   */
+  className?: string;
+  /**
+   * 빈 상태를 보조하는 visual 콘텐츠다.
+   */
+  figure?: ReactNode;
+  /**
+   * 빈 상태 제목 콘텐츠다.
+   */
+  title: ReactNode;
+  /**
+   * 빈 상태 설명 콘텐츠다.
+   */
+  description?: ReactNode;
+  /**
+   * 하단에 주입할 custom action 또는 보조 콘텐츠다.
+   */
+  children?: ReactNode;
+}
+
+/**
+ * Edge Case Loading Props; 로딩 상태 화면 템플릿 props
+ * @property {string} [className] 최상위 edge-case container className override다.
+ * @property {ReactNode} [figure] 로딩 상태 visual 콘텐츠다. 없으면 Alternate.LoadingIcon을 사용한다.
+ * @property {ReactNode} [title] 로딩 상태 제목 콘텐츠다.
+ * @property {ReactNode} [description] 로딩 상태 설명 콘텐츠다.
+ * @property {ReactNode} [children] 하단에 주입할 custom action 또는 보조 콘텐츠다.
+ */
+export interface EdgeCaseLoadingProps {
+  /**
+   * 최상위 edge-case container className override다.
+   */
+  className?: string;
+  /**
+   * 로딩 상태 visual 콘텐츠다. 없으면 Alternate.LoadingIcon을 사용한다.
+   */
+  figure?: ReactNode;
+  /**
+   * 로딩 상태 제목 콘텐츠다.
+   */
+  title?: ReactNode;
+  /**
+   * 로딩 상태 설명 콘텐츠다.
+   */
+  description?: ReactNode;
+  /**
+   * 하단에 주입할 custom action 또는 보조 콘텐츠다.
+   */
+  children?: ReactNode;
+}
+
+/**
+ * Edge Case Not Found Props; not-found 상태 화면 템플릿 props
+ * @property {string} [className] 최상위 edge-case container className override다.
+ * @property {string} [inquiryHref] 문의 text action을 link로 렌더링할 href다.
+ * @property {() => void} [onInquiry] 문의 text action을 button으로 렌더링할 콜백이다.
+ * @property {string} [fallbackHref] onPrev가 없을 때 사용할 fallback href다.
+ * @property {() => void} [onPrev] 이전 페이지 이동을 소비 앱에서 실행하는 콜백이다.
+ */
+export interface EdgeCaseNotFoundProps {
+  /**
+   * 최상위 edge-case container className override다.
+   */
+  className?: string;
+  /**
+   * 문의 text action을 link로 렌더링할 href다.
+   */
+  inquiryHref?: string;
+  /**
+   * 문의 text action을 button으로 렌더링할 콜백이다.
+   */
+  onInquiry?: () => void;
+  /**
+   * onPrev가 없을 때 사용할 fallback href다.
+   */
+  fallbackHref?: string;
+  /**
+   * 이전 페이지 이동을 소비 앱에서 실행하는 콜백이다.
+   */
+  onPrev?: () => void;
+}

package/src/index.scss

@@ -10,3 +10,4 @@
 @use "./weather/index.scss" as weatherStyles;
 @use "./cctv/index.scss" as cctvStyles;
 @use "./service-inquiry/index.scss" as serviceInquiryStyles;
+@use "./edge-case/index.scss" as edgeCaseStyles;

package/src/index.tsx

@@ -7,5 +7,6 @@ export * from "./modal";
 export * from "./weather";
 export * from "./cctv";
 export * from "./service-inquiry";
+export * from "./edge-case";
 
 export type * from "./types";