feat. GR_VISUAL_02 컴포넌트 제작

layers/utils/dataUtil.ts

@@ -1,17 +1,77 @@
 import type {
   PageDataValue,
   PageDataResourceGroupResPath,
+  PageDataComponent,
 } from '#layers/types/api/pageData'
 
-// 레이아웃 타입 리턴하는 함수
+// ============================================================================
+// 페이지 데이터 관련 유틸리티
+// ============================================================================
+
+/**
+ * 페이지 데이터를 기반으로 레이아웃 타입을 결정합니다.
+ * @param pageData 페이지 데이터
+ * @returns 레이아웃 타입 ('default' | 'promotion')
+ */
 export const getLayoutType = (
   pageData: PageDataValue | null
 ): 'default' | 'promotion' => {
   return pageData?.page_type === 1 ? 'default' : 'promotion'
 }
 
-// 이미지 호스트 리턴하는 함수
-// [TODO] 환경변수 처리 수정
+// ============================================================================
+// 컴포넌트 데이터 접근 관련 유틸리티
+// ============================================================================
+
+/**
+ * 컴포넌트 그룹에 데이터가 존재하는지 확인합니다.
+ * @param source props.components 또는 group 객체
+ * @param componentName 컴포넌트 이름
+ * @returns 데이터 존재 여부
+ */
+export const hasComponentGroup = (
+  source: any,
+  componentName: string
+): boolean => {
+  if (!source) return false
+
+  const component = source[componentName] as PageDataComponent
+  return component?.groups && component.groups.length > 0
+}
+
+/**
+ * 컴포넌트 그룹의 첫 번째 데이터를 반환합니다.
+ * @param source props.components 또는 group 객체
+ * @param componentName 컴포넌트 이름
+ * @returns 첫 번째 그룹 데이터 또는 null
+ */
+export const getComponentGroup = (source: any, componentName: string) => {
+  if (!source) return null
+
+  return source[componentName]?.groups?.[0] || null
+}
+
+/**
+ * 컴포넌트 그룹의 모든 데이터를 반환합니다.
+ * @param source props.components 또는 group 객체
+ * @param componentName 컴포넌트 이름
+ * @returns 그룹 배열 데이터
+ */
+export const getComponentGroupAry = (source: any, componentName: string) => {
+  if (!source) return []
+
+  return source[componentName]?.groups || []
+}
+
+// ============================================================================
+// 리소스/이미지 처리 관련 유틸리티
+// ============================================================================
+
+/**
+ * 이미지 경로를 완전한 호스트 URL로 변환합니다.
+ * @param path 이미지 경로
+ * @returns 완전한 이미지 URL
+ */
 export const getResolvedHost = (path: string): string => {
   const config = useRuntimeConfig()
   //   const isDev = process.env.NODE_ENV === "development";
@@ -22,12 +82,12 @@ export const getResolvedHost = (path: string): string => {
   return `${rootPath}${path}`
 }
 
-// 반응형 클래스 리턴하는 함수
-export const getResponsiveClass = () => {
-  return ['bg-[image:var(--mobile-bg)]', 'sm:bg-[image:var(--pc-bg)]']
-}
-
-// 통합된 반응형 리소스 함수
+/**
+ * 반응형 리소스(이미지/비디오)를 처리하여 PC/모바일 버전을 반환합니다.
+ * @param pathArray 리소스 경로 배열
+ * @param options 리소스 타입 옵션
+ * @returns 반응형 리소스 객체 또는 null
+ */
 export const getResponsiveSrc = (
   pathArray: PageDataResourceGroupResPath,
   options: {
@@ -59,3 +119,15 @@ export const getResponsiveSrc = (
     pcSrc: resolvedImages.pc,
   }
 }
+
+// ============================================================================
+// 스타일링 관련 유틸리티
+// ============================================================================
+
+/**
+ * 반응형 배경 이미지를 위한 CSS 클래스를 반환합니다.
+ * @returns 반응형 배경 클래스 배열
+ */
+export const getResponsiveClass = () => {
+  return ['bg-[image:var(--mobile-bg)]', 'sm:bg-[image:var(--pc-bg)]']
+}