@blastlabs/utils 1.12.0 → 1.13.0

package/README.md

@@ -1,15 +1,17 @@
-# goodchuck-utils
+# @blastlabs/utils
+
+> **⚠️ 주의: 이 라이브러리는 사내 개발용이며, 현재 테스트 단계입니다.**
 
 React 프로젝트에서 자주 사용하는 유틸리티 훅(Hooks)과 개발용 컴포넌트 모음입니다.
 
 ## 설치
 
 ```bash
-npm install goodchuck-utils
+npm install @blastlabs/utils
 # or
-yarn add goodchuck-utils
+yarn add @blastlabs/utils
 # or
-pnpm add goodchuck-utils
+pnpm add @blastlabs/utils
 ```
 
 ## 기능
@@ -19,7 +21,7 @@ pnpm add goodchuck-utils
 프로젝트에서 자주 사용하는 커스텀 훅들을 제공합니다.
 
 ```typescript
-import { useDebounce, useToggle, useCopyToClipboard } from 'goodchuck-utils/hooks';
+import { useDebounce, useToggle, useCopyToClipboard } from '@blastlabs/utils/hooks';
 ```
 
 #### 사용 가능한 Hooks
@@ -38,7 +40,7 @@ import { useDebounce, useToggle, useCopyToClipboard } from 'goodchuck-utils/hook
 개발 환경에서만 사용하는 유틸리티 컴포넌트들입니다.
 
 ```typescript
-import { DevPanel, FormDevTools, ApiLogger } from 'goodchuck-utils/components/dev';
+import { DevPanel, FormDevTools, ApiLogger } from '@blastlabs/utils/components/dev';
 ```
 
 #### IdSelector
@@ -46,7 +48,7 @@ import { DevPanel, FormDevTools, ApiLogger } from 'goodchuck-utils/components/de
 개발 환경에서 여러 계정으로 빠르게 로그인할 수 있는 컴포넌트입니다.
 
 ```tsx
-import { IdSelector } from 'goodchuck-utils/components/dev';
+import { IdSelector } from '@blastlabs/utils/components/dev';
 
 const devAccounts = [
   { id: 'admin', pw: 'admin123', memo: '관리자' },
@@ -75,7 +77,7 @@ react-hook-form의 상태를 실시간으로 시각화하는 개발용 컴포넌
 
 ```tsx
 import { useForm } from 'react-hook-form';
-import { FormDevTools } from 'goodchuck-utils/components/dev';
+import { FormDevTools } from '@blastlabs/utils/components/dev';
 
 function MyForm() {
   const form = useForm({
@@ -112,7 +114,7 @@ API 요청/응답을 로깅하고 모니터링하는 컴포넌트입니다.
 
 ```tsx
 import axios from 'axios';
-import { ApiLogger, addApiLog } from 'goodchuck-utils/components/dev';
+import { ApiLogger, addApiLog } from '@blastlabs/utils/components/dev';
 
 // Axios interceptor 설정
 axios.interceptors.request.use(
@@ -178,7 +180,7 @@ function App() {
 여러 개발 도구를 하나의 패널에서 관리할 수 있는 통합 컴포넌트입니다.
 
 ```tsx
-import { DevPanel } from 'goodchuck-utils/components/dev';
+import { DevPanel } from '@blastlabs/utils/components/dev';
 
 function App() {
   return (
@@ -200,7 +202,7 @@ function App() {
 페이지의 모든 z-index 값을 시각화하고 디버깅하는 도구입니다.
 
 ```tsx
-import { ZIndexDebugger } from 'goodchuck-utils/components/dev';
+import { ZIndexDebugger } from '@blastlabs/utils/components/dev';
 
 function App() {
   return (
@@ -222,7 +224,7 @@ function App() {
 현재 윈도우 크기를 화면에 표시하는 간단한 컴포넌트입니다.
 
 ```tsx
-import { WindowSizeDisplay } from 'goodchuck-utils/components/dev';
+import { WindowSizeDisplay } from '@blastlabs/utils/components/dev';
 
 function App() {
   return (
@@ -250,7 +252,7 @@ function App() {
 모든 컴포넌트와 훅은 TypeScript로 작성되었으며, 타입 정의가 포함되어 있습니다.
 
 ```typescript
-import type { FormDevToolsProps, ApiLogEntry } from 'goodchuck-utils/components/dev';
+import type { FormDevToolsProps, ApiLogEntry } from '@blastlabs/utils/components/dev';
 ```
 
 ## 주의사항
@@ -258,6 +260,11 @@ import type { FormDevToolsProps, ApiLogEntry } from 'goodchuck-utils/components/
 - **개발용 컴포넌트(`components/dev`)는 프로덕션 환경에서 제외하는 것을 권장합니다.**
 - 개발 환경 구분을 위해 `import.meta.env.DEV` (Vite) 또는 `process.env.NODE_ENV === 'development'` (CRA)를 사용하세요.
 
+## 문의
+
+- goodchuck852@gmail.com
+- taehyunyang@blast-team.com
+
 ## 라이선스
 
 ISC

package/bin/entity-generator-guide.md

@@ -0,0 +1,126 @@
+# 엔티티 자동 생성 스크립트 사용법
+
+## 개요
+
+`generate-entity.cjs` 스크립트를 사용하여 새로운 엔티티의 기본 구조를 자동으로 생성할 수 있습니다.
+
+## 사용법
+
+```bash
+# entities 폴더로 이동
+cd apps/admin/src/entities
+
+# 엔티티 생성
+node generate-entity.cjs <entity-name>
+```
+
+## 예시
+
+```bash
+# user-profile 엔티티 생성
+node generate-entity.cjs user-profile
+
+# my-entity 엔티티 생성
+node generate-entity.cjs my-entity
+
+# product-review 엔티티 생성
+node generate-entity.cjs product-review
+```
+
+## 생성되는 파일 구조
+
+```
+{entity-name}/
+├── index.ts                           # 엔티티 메인 export 파일
+├── api/
+│   ├── get-{entity-name}-list.ts      # API 호출 함수
+│   ├── {entity-name}-queries.ts       # React Query 설정
+│   ├── index.ts                       # API 모듈 export
+│   ├── mapper/
+│   │   └── map-{entity-name}.ts       # 데이터 매핑 함수
+│   └── query/
+│       └── {entity-name}-list-query.ts # 쿼리 타입 정의
+└── model/
+    └── {entity-name}.ts               # Zod 스키마 및 타입
+```
+
+## 자동 생성 후 추가 작업
+
+스크립트 실행 후 다음 작업들을 수동으로 완료해야 합니다:
+
+### 1. query-keys.ts 파일 업데이트
+
+```typescript
+export const {ENTITY_NAME}_QUERY_KEYS = {
+  all: ["{entity-name}"] as const,
+  lists: () => [...{ENTITY_NAME}_QUERY_KEYS.all, "list"] as const,
+  list: (filters: {EntityName}ListParams) =>
+    [...{ENTITY_NAME}_QUERY_KEYS.lists(), filters] as const,
+  details: () => [...{ENTITY_NAME}_QUERY_KEYS.all, "detail"] as const,
+  detail: (id: number) => [...{ENTITY_NAME}_QUERY_KEYS.details(), id] as const,
+};
+```
+
+### 2. model/{entity-name}.ts 수정
+
+실제 API 응답 구조에 맞게 Zod 스키마를 수정해주세요:
+
+```typescript
+export const {EntityName}Schema = z.object({
+  id: z.number(),
+  // 실제 필드들 추가
+  name: z.string(),
+  description: z.string().nullable(),
+  createDate: z.string(),
+  updateDate: z.string(),
+});
+```
+
+### 3. api/mapper/map-{entity-name}.ts 수정
+
+API 응답 데이터를 모델에 맞게 매핑하는 로직을 수정해주세요:
+
+```typescript
+export const map{EntityName} = (item: {EntityName}) => {
+  const res = {EntityName}Schema.safeParse({
+    id: item.id,
+    name: item.name,
+    description: item.description,
+    createDate: item.createDate,
+    updateDate: item.updateDate,
+  });
+  // ...
+};
+```
+
+### 4. api/get-{entity-name}-list.ts 수정
+
+실제 API 엔드포인트 메서드명으로 변경해주세요:
+
+```typescript
+export const get{EntityName}List = (filters: {EntityName}ListQuery) => {
+  const customApi = createInstance(import.meta.env.VITE_BASE_URL);
+  // 실제 API 메서드명으로 변경
+  return customApi.default.admin{EntityName}List(filters);
+};
+```
+
+### 5. api/query/{entity-name}-list-query.ts 수정
+
+필요한 필터링 옵션을 추가해주세요:
+
+```typescript
+export type {EntityName}ListQuery = {
+  limit?: number;
+  offset?: number;
+  search?: string;
+  status?: string;
+  // 추가 필터 옵션들...
+};
+```
+
+## 참고사항
+
+- 엔티티 이름은 kebab-case로 입력해주세요 (예: `user-profile`, `product-review`)
+- 생성된 파일들은 기본 템플릿이므로 실제 API 구조에 맞게 수정이 필요합니다
+- popular-product, popular-review 폴더를 참고하여 패턴을 확인할 수 있습니다

package/bin/generate-entity.cjs

@@ -0,0 +1,282 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+
+// 엔티티 이름을 kebab-case로 변환
+function toKebabCase(str) {
+  return str.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase();
+}
+
+// 엔티티 이름을 PascalCase로 변환
+function toPascalCase(str) {
+  return str
+    .split("-")
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join("");
+}
+
+// 엔티티 이름을 camelCase로 변환
+function toCamelCase(str) {
+  const pascalCase = toPascalCase(str);
+  return pascalCase.charAt(0).toLowerCase() + pascalCase.slice(1);
+}
+
+function createEntityStructure(entityName, targetDir) {
+  const kebabName = toKebabCase(entityName);
+  const pascalName = toPascalCase(kebabName);
+  const camelName = toCamelCase(kebabName);
+
+  // 현재 작업 디렉토리 기준으로 생성
+  const basePath = path.join(targetDir, kebabName);
+
+  // 디렉토리 생성
+  const dirs = [
+    basePath,
+    path.join(basePath, "api"),
+    path.join(basePath, "api", "mapper"),
+    path.join(basePath, "api", "query"),
+    path.join(basePath, "model"),
+  ];
+
+  dirs.forEach((dir) => {
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+  });
+
+  // 파일 템플릿 생성
+  createFiles(basePath, kebabName, pascalName, camelName);
+
+  console.log(`✅ ${kebabName} 엔티티가 성공적으로 생성되었습니다!`);
+  console.log(`📍 위치: ${basePath}`);
+  console.log(`\n생성된 파일들:`);
+  console.log(`📁 ${kebabName}/`);
+  console.log(`├── index.ts`);
+  console.log(`├── api/`);
+  console.log(`│   ├── get-${kebabName}-list.ts`);
+  console.log(`│   ├── get-${kebabName}-detail.ts`);
+  console.log(`│   ├── ${kebabName}-queries.ts`);
+  console.log(`│   ├── index.ts`);
+  console.log(`│   ├── mapper/`);
+  console.log(`│   │   ├── map-${kebabName}.ts`);
+  console.log(`│   │   └── map-${kebabName}-detail.ts`);
+  console.log(`│   └── query/`);
+  console.log(`│       └── ${kebabName}-list-query.ts`);
+  console.log(`└── model/`);
+  console.log(`    ├── ${kebabName}.ts`);
+  console.log(`    └── ${kebabName}-detail.ts`);
+
+  console.log(`\n⚠️  추가 작업이 필요합니다:`);
+  console.log(
+    `1. query-keys.ts 파일에 ${pascalName.toUpperCase()}_QUERY_KEYS 추가`,
+  );
+  console.log(`2. API 스키마에 맞게 model과 mapper 수정`);
+  console.log(`3. 실제 API 엔드포인트에 맞게 get-${kebabName}-list.ts 수정`);
+}
+
+function createFiles(basePath, kebabName, pascalName, camelName) {
+  // index.ts
+  const indexContent = `export * as ${camelName}Api from "./api";
+`;
+
+  // api/index.ts
+  const apiIndexContent = `export { get${pascalName}List } from "./get-${kebabName}-list";
+export { get${pascalName}Detail } from "./get-${kebabName}-detail";
+export { ${camelName}Queries } from "./${kebabName}-queries";
+`;
+
+  // api/get-{entity}-list.ts
+  const getListContent = `// TODO: API 클라이언트 import 추가
+// import { apiClient } from "@/shared/api";
+import { ${pascalName}ListQuery } from "./query/${kebabName}-list-query";
+
+export const get${pascalName}List = async (filters: ${pascalName}ListQuery) => {
+  // TODO: 실제 API 호출로 변경 필요
+  // return apiClient.get("/api/${kebabName}", { params: filters });
+  throw new Error("API 호출 구현 필요");
+};
+`;
+
+  // api/get-{entity}-detail.ts
+  const getDetailContent = `// TODO: API 클라이언트 import 추가
+// import { apiClient } from "@/shared/api";
+
+export const get${pascalName}Detail = async (id: number) => {
+  // TODO: 실제 API 호출로 변경 필요
+  // return apiClient.get(\`/api/${kebabName}/\${id}\`);
+  throw new Error("API 호출 구현 필요");
+};
+`;
+
+  // api/{entity}-queries.ts
+  const queriesContent = `import { queryOptions } from "@tanstack/react-query";
+import { ${pascalName}ListQuery } from "./query/${kebabName}-list-query";
+import { get${pascalName}List } from "./get-${kebabName}-list";
+import { get${pascalName}Detail } from "./get-${kebabName}-detail";
+import { map${pascalName} } from "./mapper/map-${kebabName}";
+import { map${pascalName}Detail } from "./mapper/map-${kebabName}-detail";
+
+export const ${camelName}Queries = {
+  all: () => ["${kebabName}"],
+  lists: () => [...${camelName}Queries.all(), "list"],
+  list: (filters: ${pascalName}ListQuery) =>
+    queryOptions({
+      queryKey: [...${camelName}Queries.lists(), filters],
+      queryFn: () => get${pascalName}List(filters),
+      select: (data) => {
+        return {
+          ...data,
+          items: data.items.map(map${pascalName}),
+        };
+      },
+    }),
+  details: () => [...${camelName}Queries.all(), "detail"],
+  detail: (id: number) =>
+    queryOptions({
+      queryKey: [...${camelName}Queries.details(), id],
+      queryFn: () => get${pascalName}Detail(id),
+      select: (data) => map${pascalName}Detail(data),
+    }),
+};
+`;
+
+  // api/mapper/map-{entity}.ts
+  const mapperContent = `import { ${pascalName}Schema } from "../../model/${kebabName}";
+
+// TODO: API 응답 타입을 실제 타입으로 변경
+type ${pascalName}Response = {
+  id: number;
+  createDate: string;
+  updateDate: string;
+};
+
+export const map${pascalName} = (item: ${pascalName}Response) => {
+  const res = ${pascalName}Schema.safeParse({
+    id: item.id,
+    // TODO: 실제 API 응답 구조에 맞게 매핑 수정 필요
+    createDate: item.createDate,
+    updateDate: item.updateDate,
+  });
+  if (!res.success) {
+    console.error(res.error);
+    return undefined;
+  }
+  return res.data;
+};
+`;
+
+  // api/mapper/map-{entity}-detail.ts
+  const mapperDetailContent = `import { ${pascalName}DetailSchema } from "../../model/${kebabName}-detail";
+
+// TODO: API 응답 타입을 실제 타입으로 변경
+type ${pascalName}DetailResponse = {
+  id: number;
+  createDate: string;
+  updateDate: string;
+};
+
+export const map${pascalName}Detail = (item: ${pascalName}DetailResponse) => {
+  const res = ${pascalName}DetailSchema.safeParse({
+    id: item.id,
+    // TODO: 실제 API 응답 구조에 맞게 매핑 수정 필요
+    createDate: item.createDate,
+    updateDate: item.updateDate,
+  });
+  if (!res.success) {
+    console.error(res.error);
+    return undefined;
+  }
+  return res.data;
+};
+`;
+
+  // api/query/{entity}-list-query.ts
+  const queryContent = `export type ${pascalName}ListQuery = {
+  limit?: number;
+  offset?: number;
+  // TODO: 추가 필터링 옵션이 필요한 경우 여기에 추가
+};
+`;
+
+  // model/{entity}.ts
+  const modelContent = `import { z } from "zod";
+
+export const ${pascalName}Schema = z.object({
+  id: z.number(),
+  createDate: z.string(),
+  updateDate: z.string(),
+  // TODO: 실제 데이터 구조에 맞게 스키마 수정 필요
+});
+
+export type ${pascalName}Type = z.infer<typeof ${pascalName}Schema>;
+`;
+
+  //model/{entity}-detail.ts
+  const detailContent = `import { z } from "zod";
+
+export const ${pascalName}DetailSchema = z.object({
+  id: z.number(),
+  createDate: z.string(),
+  updateDate: z.string(),
+});
+
+export type ${pascalName}DetailType = z.infer<typeof ${pascalName}DetailSchema>;
+`;
+
+  // 파일 쓰기
+  fs.writeFileSync(path.join(basePath, "index.ts"), indexContent);
+  fs.writeFileSync(path.join(basePath, "api", "index.ts"), apiIndexContent);
+  fs.writeFileSync(
+    path.join(basePath, "api", `get-${kebabName}-list.ts`),
+    getListContent,
+  );
+  fs.writeFileSync(
+    path.join(basePath, "api", `get-${kebabName}-detail.ts`),
+    getDetailContent,
+  );
+  fs.writeFileSync(
+    path.join(basePath, "api", `${kebabName}-queries.ts`),
+    queriesContent,
+  );
+  fs.writeFileSync(
+    path.join(basePath, "api", "mapper", `map-${kebabName}.ts`),
+    mapperContent,
+  );
+  fs.writeFileSync(
+    path.join(basePath, "api", "mapper", `map-${kebabName}-detail.ts`),
+    mapperDetailContent,
+  );
+  fs.writeFileSync(
+    path.join(basePath, "api", "query", `${kebabName}-list-query.ts`),
+    queryContent,
+  );
+  fs.writeFileSync(
+    path.join(basePath, "model", `${kebabName}.ts`),
+    modelContent,
+  );
+  fs.writeFileSync(
+    path.join(basePath, "model", `${kebabName}-detail.ts`),
+    detailContent,
+  );
+}
+
+// CLI 실행
+const args = process.argv.slice(2);
+
+if (args.length === 0) {
+  console.log("@blastlabs/utils - FSD Entity Generator\n");
+  console.log("사용법: npx blastlabs-generate-entity <entity-name>\n");
+  console.log("⚠️  entities 폴더 내에서 실행해주세요!\n");
+  console.log("예시:");
+  console.log("  cd src/entities");
+  console.log("  npx blastlabs-generate-entity user");
+  console.log("  npx blastlabs-generate-entity my-new-entity");
+  console.log("  npx blastlabs-generate-entity MyNewEntity");
+  process.exit(1);
+}
+
+const entityName = args[0];
+const targetDir = process.cwd();
+
+createEntityStructure(entityName, targetDir);

package/dist/components/auth/AuthGuard.d.ts

@@ -0,0 +1,95 @@
+import React from 'react';
+import { ReactNode } from 'react';
+import { UseAuthOptions } from '../../hooks/auth';
+type AuthGuardProps = {
+    /** 인증된 경우 렌더링할 컴포넌트 */
+    children: ReactNode;
+    /** 로딩 중 표시할 컴포넌트 */
+    fallback?: ReactNode;
+    /** 인증되지 않은 경우 호출되는 콜백 (리다이렉트 로직 구현) */
+    onUnauthenticated?: () => void;
+    /** 로딩 완료 후 인증되지 않은 경우 렌더링할 컴포넌트 (onUnauthenticated가 없을 때) */
+    unauthenticatedFallback?: ReactNode;
+    /** useAuth 훅 옵션 (선택사항) */
+    authOptions?: UseAuthOptions;
+};
+/**
+ * 인증 가드 컴포넌트
+ * 인증이 필요한 페이지를 보호하는 컴포넌트
+ *
+ * 내부적으로 useAuth 훅을 호출하여 localStorage/sessionStorage에서 인증 상태를 확인합니다.
+ * 각 AuthGuard는 독립적으로 동작하며, storage를 통해 자동으로 동기화됩니다.
+ *
+ * @example
+ * ```tsx
+ * // 기본 사용 (localStorage 자동 로드)
+ * import { AuthGuard } from '@blastlabs/utils';
+ * import { useRouter } from 'next/navigation';
+ *
+ * function ProtectedPage() {
+ *   const router = useRouter();
+ *
+ *   return (
+ *     <AuthGuard
+ *       authOptions={{ autoLoadUser: true }}
+ *       onUnauthenticated={() => router.push('/login')}
+ *       fallback={<LoadingSpinner />}
+ *     >
+ *       <YourProtectedContent />
+ *     </AuthGuard>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // React Router에서 사용
+ * import { useNavigate } from 'react-router-dom';
+ *
+ * function ProtectedPage() {
+ *   const navigate = useNavigate();
+ *
+ *   return (
+ *     <AuthGuard
+ *       authOptions={{ autoLoadUser: true }}
+ *       onUnauthenticated={() => navigate('/login')}
+ *     >
+ *       <YourProtectedContent />
+ *     </AuthGuard>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // 리다이렉트 없이 대체 UI 표시
+ * <AuthGuard
+ *   authOptions={{ autoLoadUser: true }}
+ *   unauthenticatedFallback={
+ *     <div>
+ *       <h1>로그인이 필요합니다</h1>
+ *       <Link to="/login">로그인 페이지로 이동</Link>
+ *     </div>
+ *   }
+ * >
+ *   <YourProtectedContent />
+ * </AuthGuard>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // 여러 페이지에서 사용해도 storage로 자동 동기화
+ * // Page1.tsx
+ * <AuthGuard authOptions={{ autoLoadUser: true }} onUnauthenticated={...}>
+ *   <Page1Content />
+ * </AuthGuard>
+ *
+ * // Page2.tsx - 동일한 인증 상태 공유 (localStorage 사용)
+ * <AuthGuard authOptions={{ autoLoadUser: true }} onUnauthenticated={...}>
+ *   <Page2Content />
+ * </AuthGuard>
+ * ```
+ */
+export declare function AuthGuard({ children, fallback, onUnauthenticated, unauthenticatedFallback, authOptions, }: AuthGuardProps): React.JSX.Element | null;
+export {};
+//# sourceMappingURL=AuthGuard.d.ts.map

package/dist/components/auth/AuthGuard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AuthGuard.d.ts","sourceRoot":"","sources":["../../../src/components/auth/AuthGuard.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,SAAS,EAAa,MAAM,OAAO,CAAC;AAC7C,OAAO,EAA0B,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAE1E,KAAK,cAAc,GAAG;IACpB,uBAAuB;IACvB,QAAQ,EAAE,SAAS,CAAC;IACpB,oBAAoB;IACpB,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,uCAAuC;IACvC,iBAAiB,CAAC,EAAE,MAAM,IAAI,CAAC;IAC/B,6DAA6D;IAC7D,uBAAuB,CAAC,EAAE,SAAS,CAAC;IACpC,0BAA0B;IAC1B,WAAW,CAAC,EAAE,cAAc,CAAC;CAC9B,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4EG;AACH,wBAAgB,SAAS,CAAC,EACxB,QAAQ,EACR,QAAQ,EACR,iBAAiB,EACjB,uBAAuB,EACvB,WAAW,GACZ,EAAE,cAAc,4BA0BhB"}