@blastlabs/utils 1.21.0 → 2.1.0

package/README.md

@@ -74,25 +74,64 @@ function App() {
 #### FormDevTools
 
 react-hook-form의 상태를 실시간으로 시각화하는 개발용 컴포넌트입니다.
+DevPanel과 통합하거나 별도로 사용할 수 있습니다.
 
+**DevPanel과 함께 사용 (권장):**
 ```tsx
+import { DevToolsProvider, DevPanel, useRegisterForm } from '@blastlabs/utils/components/dev';
 import { useForm } from 'react-hook-form';
+
+// Layout.tsx - Provider로 감싸기
+function Layout() {
+  return (
+    <DevToolsProvider>
+      <YourApp />
+    </DevToolsProvider>
+  );
+}
+
+// 페이지에서 form 등록
+function MyFormPage() {
+  const form = useForm({
+    defaultValues: { username: '', email: '' }
+  });
+
+  // form을 DevPanel에 등록
+  useRegisterForm(form);
+
+  return (
+    <form>
+      <input {...form.register('username')} />
+      <input {...form.register('email')} />
+      <button>Submit</button>
+    </form>
+  );
+}
+
+// App.tsx - DevPanel 렌더링
+function App() {
+  return (
+    <div>
+      {import.meta.env.DEV && <DevPanel />}
+    </div>
+  );
+}
+```
+
+**별도 사용:**
+```tsx
 import { FormDevTools } from '@blastlabs/utils/components/dev';
 
 function MyForm() {
   const form = useForm({
-    defaultValues: {
-      username: '',
-      email: '',
-      age: 0,
-    }
+    defaultValues: { username: '', email: '' }
   });
 
   return (
-    <form onSubmit={form.handleSubmit(onSubmit)}>
+    <form>
       <input {...form.register('username')} />
       <input {...form.register('email')} />
-      <button type="submit">Submit</button>
+      <button>Submit</button>
 
       {import.meta.env.DEV && <FormDevTools form={form} />}
     </form>
@@ -105,9 +144,64 @@ function MyForm() {
 - 에러(errors) 상태 확인
 - 변경된 필드(dirtyFields) 추적
 - 터치된 필드(touchedFields) 확인
-- Mock 데이터 생성 기능
 - 드래그 & 리사이즈 가능한 패널
 
+#### DevPanel
+
+여러 개발 도구를 하나의 패널에서 통합 관리하는 컴포넌트입니다.
+
+```tsx
+import { DevToolsProvider, DevPanel, useRegisterForm } from '@blastlabs/utils/components/dev';
+
+// Layout.tsx - 앱 상단에서 한 번만 감싸기
+function Layout() {
+  return (
+    <DevToolsProvider>
+      <YourApp />
+    </DevToolsProvider>
+  );
+}
+
+// 페이지에서 form 등록
+function MyFormPage() {
+  const form = useForm({
+    defaultValues: { username: '', email: '' }
+  });
+
+  // Form DevTools 사용을 위해 form 등록
+  useRegisterForm(form);
+
+  return (
+    <form>
+      <input {...form.register('username')} />
+      <input {...form.register('email')} />
+      <button>Submit</button>
+    </form>
+  );
+}
+
+// App.tsx - DevPanel 렌더링
+function App() {
+  return (
+    <div>
+      {import.meta.env.DEV && <DevPanel />}
+    </div>
+  );
+}
+```
+
+**주요 기능:**
+- 📝 Form DevTools - react-hook-form 상태 시각화 (form 등록 필요)
+- 🌍 Timezone DevTools - 타임존 정보 확인
+- 📐 Window Size - 윈도우 크기 표시 (토글 가능)
+- 🔍 Z-Index Debugger - z-index 값 시각화 (토글 가능)
+- 각 도구 독립적 토글
+- 드래그 & 리사이즈 가능한 패널
+
+**주의사항:**
+- DevPanel을 사용하려면 앱 상단에서 DevToolsProvider로 감싸야 합니다
+- Form DevTools를 사용하려면 페이지에서 useRegisterForm로 form을 등록해야 합니다
+
 #### ApiLogger
 
 API 요청/응답을 로깅하고 모니터링하는 컴포넌트입니다.

package/bin/Makefile

@@ -0,0 +1,23 @@
+.PHONY: help all init-routes init-ai-rules generate-entity
+
+help:
+	@echo "blastlabs CLI Tools"
+	@echo ""
+	@echo "Usage: make <command>"
+	@echo ""
+	@echo "Available commands:"
+	@echo "  make all             - Run all CLI commands"
+	@echo "  make init-routes     - Initialize routes folder structure"
+	@echo "  make init-ai-rules   - Initialize AI rules files"
+	@echo "  make generate-entity - Generate entity scaffold"
+
+all: init-routes init-ai-rules generate-entity
+
+init-routes:
+	node init-routes.cjs
+
+init-ai-rules:
+	node init-ai-rules.cjs
+
+generate-entity:
+	node generate-entity.cjs

package/bin/init-routes.cjs

@@ -0,0 +1,422 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+
+// routes 폴더 구조와 내용을 정의
+const routesStructure = {
+  "base.ts": `/**
+ * 기본 라우트 경로
+ */
+
+export const BASE_ROUTES = {
+  HOME: '/',
+} as const;
+`,
+  "types.ts": `/**
+ * 라우트 경로 관련 타입 정의
+ */
+
+import type { ROUTE_PATH } from './index';
+
+/**
+ * 라우트 경로 타입
+ */
+export type RoutePath = typeof ROUTE_PATH;
+`,
+  "auth.ts": `/**
+ * 인증 관련 라우트 경로
+ */
+
+import { createRoute } from './utils/helpers';
+
+const AUTH_BASE = '/auth';
+
+export const AUTH_ROUTES = {
+  ROOT: AUTH_BASE,
+  LOGIN: createRoute(AUTH_BASE, '/login'),
+  REGISTER: createRoute(AUTH_BASE, '/register'),
+  FORGOT_PASSWORD: createRoute(AUTH_BASE, '/forgot-password'),
+  RESET_PASSWORD: createRoute(AUTH_BASE, '/reset-password'),
+  VERIFY_EMAIL: createRoute(AUTH_BASE, '/verify-email'),
+  VERIFY_OTP: createRoute(AUTH_BASE, '/verify-otp'),
+} as const;
+`,
+  "post.ts": `/**
+ * 게시글 관련 라우트 경로
+ */
+
+import { createRoute } from './utils/helpers';
+
+const POST_BASE = '/post';
+
+export const POST_ROUTES = {
+  ROOT: POST_BASE,
+  LIST: POST_BASE,
+  CREATE: createRoute(POST_BASE, '/create'),
+  DETAIL: createRoute(POST_BASE, '/[id]'),
+} as const;
+`,
+  "users.example.ts": `/**
+ * 사용자 관련 라우트 경로 예시
+ * 복사해서 사용하세요
+ */
+
+import { createRoute } from './utils/helpers';
+
+const USERS_BASE = '/users';
+
+export const USERS_ROUTES = {
+  ROOT: USERS_BASE,
+  LIST: USERS_BASE,
+  DETAIL: createRoute(USERS_BASE, '/[id]'),
+  CREATE: createRoute(USERS_BASE, '/create'),
+  EDIT: createRoute(USERS_BASE, '/[id]/edit'),
+} as const;
+`,
+  "index.ts": `/**
+ * 애플리케이션 라우트 경로 상수
+ * Next.js App Router 기준으로 작성되었습니다.
+ *
+ * 사용 예시:
+ * - ROUTE_PATH.HOME
+ * - ROUTE_PATH.AUTH.LOGIN
+ * - withParam(ROUTE_PATH.USERS.DETAIL, { id: '123' })
+ */
+
+import { BASE_ROUTES } from './base';
+import { AUTH_ROUTES } from './auth';
+import { POST_ROUTES } from './post';
+
+/**
+ * 라우트 경로 상수 객체
+ */
+export const ROUTE_PATH = {
+  ...BASE_ROUTES,
+  AUTH: AUTH_ROUTES,
+  POST: POST_ROUTES,
+} as const;
+
+// 유틸리티 함수 재내보내기
+export { withParam, withQuery } from './utils/helpers';
+
+// 타입 내보내기
+export type { RoutePath } from './types';
+`,
+  "utils": {
+    "helpers.ts": `/**
+ * 라우트 경로 관련 유틸리티 함수
+ */
+
+/**
+ * 동적 라우트 파라미터를 포함한 경로를 생성하는 헬퍼 함수
+ * @param path - 기본 경로 (예: '/users/[id]')
+ * @param params - 파라미터 객체 (예: { id: '123' })
+ * @returns 실제 경로 (예: '/users/123')
+ *
+ * @example
+ * \`\`\`ts
+ * const userPath = withParam('/users/[id]', { id: '123' });
+ * // '/users/123'
+ * \`\`\`
+ */
+export function withParam<T extends string>(
+  path: T,
+  params: Record<string, string | number>,
+): string {
+  let result: string = path;
+  for (const [key, value] of Object.entries(params)) {
+    result = result.replace(\`[\${key}]\`, String(value));
+  }
+  return result;
+}
+
+/**
+ * 쿼리 파라미터를 포함한 경로를 생성하는 헬퍼 함수
+ * @param path - 기본 경로
+ * @param query - 쿼리 파라미터 객체
+ * @returns 쿼리 파라미터가 포함된 경로
+ *
+ * @example
+ * \`\`\`ts
+ * const searchPath = withQuery('/search', { q: 'test', page: 1 });
+ * // '/search?q=test&page=1'
+ * \`\`\`
+ */
+export function withQuery(
+  path: string,
+  query: Record<string, string | number | boolean | null | undefined>,
+): string {
+  const searchParams = new URLSearchParams();
+  for (const [key, value] of Object.entries(query)) {
+    if (value !== null && value !== undefined) {
+      searchParams.append(key, String(value));
+    }
+  }
+  const queryString = searchParams.toString();
+  return queryString ? \`\${path}?\${queryString}\` : path;
+}
+
+/**
+ * 라우트 경로를 생성하는 헬퍼 함수
+ * @param base - 기본 경로
+ * @param path - 추가 경로
+ * @returns 합쳐진 경로
+ *
+ * @example
+ * \`\`\`ts
+ * const route = createRoute('/auth', '/login');
+ * // '/auth/login'
+ * \`\`\`
+ */
+export function createRoute(base: string, path: string): string {
+  return \`\${base}\${path.startsWith('/') ? path : \`/\${path}\`}\`;
+}
+`,
+    "helpers.test.ts": `import { describe, it, expect } from 'vitest';
+import { withParam, withQuery, createRoute } from './helpers';
+
+describe('withParam', () => {
+  it('단일 파라미터를 변환한다', () => {
+    const result = withParam('/users/[id]', { id: '123' });
+    expect(result).toBe('/users/123');
+  });
+
+  it('여러 파라미터를 변환한다', () => {
+    const result = withParam('/posts/[postId]/comments/[commentId]', {
+      postId: '456',
+      commentId: '789'
+    });
+    expect(result).toBe('/posts/456/comments/789');
+  });
+
+  it('숫자 파라미터를 처리한다', () => {
+    const result = withParam('/users/[id]', { id: 123 });
+    expect(result).toBe('/users/123');
+  });
+});
+
+describe('withQuery', () => {
+  it('단일 쿼리 파라미터를 추가한다', () => {
+    const result = withQuery('/search', { q: 'test' });
+    expect(result).toBe('/search?q=test');
+  });
+
+  it('여러 쿼리 파라미터를 추가한다', () => {
+    const result = withQuery('/search', { q: 'test', page: 1 });
+    expect(result).toBe('/search?q=test&page=1');
+  });
+
+  it('null과 undefined을 무시한다', () => {
+    const result = withQuery('/search', { q: 'test', page: null, limit: undefined });
+    expect(result).toBe('/search?q=test');
+  });
+
+  it('빈 쿼리 객체는 경로를 변경하지 않는다', () => {
+    const result = withQuery('/search', {});
+    expect(result).toBe('/search');
+  });
+
+  it('boolean 파라미터를 처리한다', () => {
+    const result = withQuery('/users', { expanded: true });
+    expect(result).toBe('/users?expanded=true');
+  });
+});
+
+describe('createRoute', () => {
+  it('기본 경로와 하위 경로를 합친다', () => {
+    const result = createRoute('/auth', '/login');
+    expect(result).toBe('/auth/login');
+  });
+
+  it('슬래시 없는 하위 경로도 처리한다', () => {
+    const result = createRoute('/auth', 'login');
+    expect(result).toBe('/auth/login');
+  });
+});
+`
+  },
+  "README.md": `# 라우터 구조
+
+라우트 경로를 도메인별로 분리하여 관리하는 구조입니다.
+
+## 폴더 구조
+
+\`\`\`
+routes/
+├── utils/           # 유틸리티 함수
+│   └── helpers.ts   # withParam, withQuery, createRoute 등
+├── types.ts         # 타입 정의
+├── base.ts          # 기본 라우트 (HOME 등)
+├── auth.ts          # 인증 관련 라우트
+├── post.ts          # 게시글 관련 라우트
+├── users.example.ts # 확장 예시 파일
+└── index.ts         # 모든 라우트 통합 및 내보내기
+\`\`\`
+
+## 사용 방법
+
+### 기본 사용
+
+\`\`\`typescript
+import { ROUTE_PATH } from '@/app/routes';
+
+// 기본 라우트
+ROUTE_PATH.HOME              // '/'
+
+// 인증 라우트
+ROUTE_PATH.AUTH.LOGIN        // '/auth/login'
+ROUTE_PATH.AUTH.REGISTER     // '/auth/register'
+
+// 게시글 라우트
+ROUTE_PATH.POST.CREATE       // '/post/create'
+\`\`\`
+
+### 동적 라우트 파라미터
+
+\`\`\`typescript
+import { ROUTE_PATH, withParam } from '@/app/routes';
+
+// 단일 파라미터
+const postPath = withParam(ROUTE_PATH.POST.DETAIL, { id: '123' });
+// 결과: '/post/123'
+
+// 여러 파라미터 (파라미터가 여러 개인 경우)
+const customPath = withParam('/posts/[postId]/comments/[commentId]', {
+  postId: '456',
+  commentId: '789'
+});
+// 결과: '/posts/456/comments/789'
+\`\`\`
+
+### 파라미터와 쿼리 조합
+
+\`\`\`typescript
+import { ROUTE_PATH, withParam, withQuery } from '@/app/routes';
+
+// withParam으로 파라미터 변환 후 withQuery로 쿼리 추가
+const detailPath = withQuery(
+  withParam(ROUTE_PATH.POST.DETAIL, { id: '123' }),
+  { tab: 'edit', expanded: true }
+);
+// 결과: '/post/123?tab=edit&expanded=true'
+\`\`\`
+
+## 새로운 라우트 그룹 추가하기
+
+### 1. 새로운 라우트 파일 생성
+
+예: \`products.ts\`
+
+\`\`\`typescript
+import { createRoute } from './utils/helpers';
+
+const PRODUCTS_BASE = '/products';
+
+export const PRODUCTS_ROUTES = {
+  ROOT: PRODUCTS_BASE,
+  LIST: PRODUCTS_BASE,
+  DETAIL: createRoute(PRODUCTS_BASE, '/[id]'),
+  CREATE: createRoute(PRODUCTS_BASE, '/create'),
+} as const;
+\`\`\`
+
+### 2. index.ts에 추가
+
+\`\`\`typescript
+import { PRODUCTS_ROUTES } from './products'; // 추가
+
+export const ROUTE_PATH = {
+  ...BASE_ROUTES,
+  AUTH: AUTH_ROUTES,
+  POST: POST_ROUTES,
+  PRODUCTS: PRODUCTS_ROUTES, // 추가
+} as const;
+\`\`\`
+
+### 3. 사용하기
+
+\`\`\`typescript
+import { ROUTE_PATH } from '@/app/routes';
+
+ROUTE_PATH.PRODUCTS.LIST      // '/products'
+ROUTE_PATH.PRODUCTS.DETAIL    // '/products/[id]'
+\`\`\`
+
+## 파일 역할
+
+- **base.ts**: 애플리케이션 전체에서 공통으로 사용되는 기본 라우트 (HOME 등)
+- **auth.ts**: 인증 관련 라우트
+- **post.ts**: 게시글 관련 라우트
+- **[domain].ts**: 특정 도메인(예: users, products, orders)의 라우트
+- **utils/helpers.ts**: 라우트 생성 및 조작을 위한 유틸리티 함수
+- **types.ts**: 라우트 관련 타입 정의
+- **index.ts**: 모든 라우트를 통합하여 내보내는 진입점
+
+## 원칙
+
+1. **도메인별 분리**: 각 도메인은 별도 파일로 관리
+2. **일관된 네이밍**: 모든 라우트 그룹은 \`[DOMAIN]_ROUTES\` 형태로 명명
+3. **타입 안전성**: \`as const\`를 사용하여 타입 추론 최적화
+4. **재사용 가능한 유틸리티**: \`createRoute\`, \`withParam\`, \`withQuery\` 등을 활용
+`
+};
+
+// 디렉토리와 파일을 재귀적으로 생성하는 함수
+function createDirectoryStructure(basePath, structure) {
+  // basePath가 존재하지 않으면 생성
+  if (!fs.existsSync(basePath)) {
+    fs.mkdirSync(basePath, { recursive: true });
+  }
+
+  for (const [name, content] of Object.entries(structure)) {
+    const fullPath = path.join(basePath, name);
+
+    if (typeof content === 'object') {
+      // 디렉토리인 경우
+      if (!fs.existsSync(fullPath)) {
+        fs.mkdirSync(fullPath, { recursive: true });
+      }
+      createDirectoryStructure(fullPath, content);
+    } else {
+      // 파일인 경우
+      fs.writeFileSync(fullPath, content, 'utf8');
+    }
+  }
+}
+
+// CLI 실행
+function main() {
+  const targetDir = process.cwd();
+  const routesPath = path.join(targetDir, 'src', 'app', 'routes');
+
+  // 이미 routes 폴더가 있는지 확인
+  if (fs.existsSync(routesPath)) {
+    console.log('⚠️  src/app/routes 폴더가 이미 존재합니다.');
+    console.log('📂 기존 폴더를 삭제하고 다시 생성하려면 수동으로 삭제 후 다시 실행하세요.');
+    process.exit(1);
+  }
+
+  // routes 폴더 생성
+  createDirectoryStructure(routesPath, routesStructure);
+
+  console.log('✅ routes 폴더가 성공적으로 생성되었습니다!\\n');
+  console.log('📍 위치: src/app/routes\\n');
+  console.log('생성된 파일들:');
+  console.log('📁 routes/');
+  console.log('├── utils/');
+  console.log('│   ├── helpers.ts');
+  console.log('│   └── helpers.test.ts');
+  console.log('├── base.ts');
+  console.log('├── types.ts');
+  console.log('├── auth.ts');
+  console.log('├── post.ts');
+  console.log('├── users.example.ts');
+  console.log('├── index.ts');
+  console.log('└── README.md\\n');
+  console.log('사용 방법:');
+  console.log("  import { ROUTE_PATH, withParam, withQuery } from '@/app/routes';");
+  console.log("  ROUTE_PATH.AUTH.LOGIN  // '/auth/login'");
+}
+
+main();

package/dist/components/dev/DevPanel.d.ts

@@ -5,26 +5,31 @@ type Props = {
 };
 /**
  * 개발자 도구 패널
- * 여러 개발용 도구를 하나의 패널에서 관리할 수 있습니다.
+ * Layout에 한 번만 배치하고, 페이지에서 hook으로 form을 주입받습니다.
  *
  * @example
  * ```tsx
- * // Vite 프로젝트
+ * // Layout.tsx (한 번만)
  * import { DevPanel } from '@blastlabs/utils/components/dev';
  *
- * function App() {
+ * function Layout() {
  *   return (
- *     <div>
- *       {import.meta.env.DEV && <DevPanel />}
- *     </div>
+ *     <>
+ *       <Outlet />
+ *       <DevPanel />
+ *     </>
  *   );
  * }
- * ```
  *
- * @example
- * ```tsx
- * // Create React App 프로젝트
- * {process.env.NODE_ENV === 'development' && <DevPanel position="top-left" />}
+ * // 페이지에서 form 주입
+ * import { useRegisterForm } from '@blastlabs/utils/components/dev';
+ *
+ * function MyPage() {
+ *   const form = useForm();
+ *   useRegisterForm(form);
+ *
+ *   return <form>...</form>;
+ * }
  * ```
  */
 export default function DevPanel({ position }: Props): React.JSX.Element;

package/dist/components/dev/DevPanel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DevPanel.d.ts","sourceRoot":"","sources":["../../../src/components/dev/DevPanel.tsx"],"names":[],"mappings":"AAAA,OAAO,KAA0C,MAAM,OAAO,CAAC;AAG/D,KAAK,KAAK,GAAG;IACX,qCAAqC;IACrC,QAAQ,CAAC,EAAE,UAAU,GAAG,WAAW,GAAG,aAAa,GAAG,cAAc,CAAC;CACtE,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,OAAO,UAAU,QAAQ,CAAC,EAAE,QAAyB,EAAE,EAAE,KAAK,qBA6OpE"}
+{"version":3,"file":"DevPanel.d.ts","sourceRoot":"","sources":["../../../src/components/dev/DevPanel.tsx"],"names":[],"mappings":"AACA,OAAO,KAA6C,MAAM,OAAO,CAAC;AAOlE,KAAK,KAAK,GAAG;IACX,qCAAqC;IACrC,QAAQ,CAAC,EAAE,UAAU,GAAG,WAAW,GAAG,aAAa,GAAG,cAAc,CAAC;CACtE,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,CAAC,OAAO,UAAU,QAAQ,CAAC,EAAE,QAAyB,EAAE,EAAE,KAAK,qBAkPpE"}