goodchuck-utils 1.1.0 → 1.3.0

package/src/form/__tests__/formatter.test.ts

@@ -0,0 +1,97 @@
+import { describe, it, expect } from 'vitest';
+import {
+  formatPhoneNumber,
+  formatBusinessNumber,
+  formatCreditCard,
+  extractNumbers,
+  formatCurrency,
+  maskResidentNumber,
+  maskCreditCard,
+} from '../formatter';
+
+describe('Form Formatters', () => {
+  describe('formatPhoneNumber', () => {
+    it('should format phone numbers correctly', () => {
+      expect(formatPhoneNumber('01012345678')).toBe('010-1234-5678');
+      expect(formatPhoneNumber('0212345678')).toBe('021-2345-678');
+      expect(formatPhoneNumber('010')).toBe('010');
+      expect(formatPhoneNumber('0101234')).toBe('010-1234');
+    });
+
+    it('should handle already formatted numbers', () => {
+      expect(formatPhoneNumber('010-1234-5678')).toBe('010-1234-5678');
+    });
+
+    it('should limit to 11 digits', () => {
+      expect(formatPhoneNumber('010123456789999')).toBe('010-1234-5678');
+    });
+  });
+
+  describe('formatBusinessNumber', () => {
+    it('should format business numbers correctly', () => {
+      expect(formatBusinessNumber('1234567890')).toBe('123-45-67890');
+      expect(formatBusinessNumber('123')).toBe('123');
+      expect(formatBusinessNumber('12345')).toBe('123-45');
+    });
+
+    it('should limit to 10 digits', () => {
+      expect(formatBusinessNumber('12345678901234')).toBe('123-45-67890');
+    });
+  });
+
+  describe('formatCreditCard', () => {
+    it('should format credit card numbers', () => {
+      expect(formatCreditCard('1234567890123456')).toBe('1234-5678-9012-3456');
+      expect(formatCreditCard('1234')).toBe('1234');
+    });
+  });
+
+  describe('extractNumbers', () => {
+    it('should extract only numbers', () => {
+      expect(extractNumbers('abc123def456')).toBe('123456');
+      expect(extractNumbers('010-1234-5678')).toBe('01012345678');
+      expect(extractNumbers('no numbers')).toBe('');
+    });
+  });
+
+  describe('formatCurrency', () => {
+    it('should format numbers with commas', () => {
+      expect(formatCurrency(1234567)).toBe('1,234,567원');
+      expect(formatCurrency(1000)).toBe('1,000원');
+      expect(formatCurrency(0)).toBe('0원');
+    });
+
+    it('should handle string input', () => {
+      expect(formatCurrency('1234567')).toBe('1,234,567원');
+    });
+
+    it('should allow custom currency', () => {
+      expect(formatCurrency(1000, '달러')).toBe('1,000달러');
+    });
+
+    it('should handle invalid input', () => {
+      expect(formatCurrency('invalid')).toBe('0원');
+    });
+  });
+
+  describe('maskResidentNumber', () => {
+    it('should mask resident registration number', () => {
+      expect(maskResidentNumber('1234561234567')).toBe('123456-*******');
+      expect(maskResidentNumber('123456-1234567')).toBe('123456-*******');
+    });
+
+    it('should handle partial input', () => {
+      expect(maskResidentNumber('12345')).toBe('12345');
+    });
+  });
+
+  describe('maskCreditCard', () => {
+    it('should mask credit card number', () => {
+      expect(maskCreditCard('1234567890123456')).toBe('1234-****-****-3456');
+    });
+
+    it('should handle partial input', () => {
+      expect(maskCreditCard('1234567')).toBe('1234567');
+    });
+  });
+});

package/src/form/__tests__/helpers.test.ts

@@ -0,0 +1,53 @@
+import { describe, it, expect } from 'vitest';
+import {
+  hasFormErrors,
+  getChangedFields,
+  removeEmptyValues,
+} from '../helpers';
+
+describe('Form State Helpers', () => {
+  describe('hasFormErrors', () => {
+    it('should detect errors', () => {
+      expect(hasFormErrors({ email: 'error' })).toBe(true);
+      expect(hasFormErrors({})).toBe(false);
+    });
+  });
+
+  describe('getChangedFields', () => {
+    it('should return only changed fields', () => {
+      const original = { name: 'John', email: 'john@example.com', age: 30 };
+      const current = { name: 'Jane', email: 'john@example.com', age: 31 };
+      const changed = getChangedFields(original, current);
+
+      expect(changed).toEqual({ name: 'Jane', age: 31 });
+    });
+
+    it('should return empty object when nothing changed', () => {
+      const original = { name: 'John' };
+      const current = { name: 'John' };
+      expect(getChangedFields(original, current)).toEqual({});
+    });
+  });
+
+  describe('removeEmptyValues', () => {
+    it('should remove null, undefined, and empty strings', () => {
+      const input = {
+        name: 'John',
+        email: '',
+        age: null,
+        phone: undefined,
+        address: 'Seoul',
+      };
+
+      expect(removeEmptyValues(input)).toEqual({
+        name: 'John',
+        address: 'Seoul',
+      });
+    });
+
+    it('should keep zero values', () => {
+      const input = { count: 0, active: false };
+      expect(removeEmptyValues(input)).toEqual({ count: 0, active: false });
+    });
+  });
+});

package/src/form/__tests__/validation.test.ts

@@ -0,0 +1,84 @@
+import { describe, it, expect } from 'vitest';
+import {
+  isEmail,
+  isPhoneNumber,
+  isUrl,
+  isStrongPassword,
+  isBusinessNumber,
+} from '../validation';
+
+describe('Form Validation', () => {
+  describe('isEmail', () => {
+    it('should validate correct email formats', () => {
+      expect(isEmail('test@example.com')).toBe(true);
+      expect(isEmail('user.name@domain.co.kr')).toBe(true);
+      expect(isEmail('test+tag@example.com')).toBe(true);
+    });
+
+    it('should reject invalid email formats', () => {
+      expect(isEmail('invalid')).toBe(false);
+      expect(isEmail('test@')).toBe(false);
+      expect(isEmail('@example.com')).toBe(false);
+      expect(isEmail('test @example.com')).toBe(false);
+    });
+  });
+
+  describe('isPhoneNumber', () => {
+    it('should validate Korean phone numbers', () => {
+      expect(isPhoneNumber('010-1234-5678')).toBe(true);
+      expect(isPhoneNumber('01012345678')).toBe(true);
+      expect(isPhoneNumber('02-1234-5678')).toBe(true);
+      expect(isPhoneNumber('031-123-4567')).toBe(true);
+    });
+
+    it('should reject invalid phone numbers', () => {
+      expect(isPhoneNumber('123-456-7890')).toBe(false);
+      expect(isPhoneNumber('010-12-3456')).toBe(false);
+    });
+  });
+
+  describe('isUrl', () => {
+    it('should validate URLs', () => {
+      expect(isUrl('https://example.com')).toBe(true);
+      expect(isUrl('http://test.co.kr')).toBe(true);
+      expect(isUrl('https://example.com/path?query=1')).toBe(true);
+    });
+
+    it('should reject invalid URLs', () => {
+      expect(isUrl('not-a-url')).toBe(false);
+      expect(isUrl('example.com')).toBe(false);
+    });
+  });
+
+  describe('isStrongPassword', () => {
+    it('should validate strong passwords', () => {
+      expect(isStrongPassword('Password123!')).toBe(true);
+      expect(isStrongPassword('Str0ng#Pass')).toBe(true);
+    });
+
+    it('should reject weak passwords', () => {
+      expect(isStrongPassword('short')).toBe(false);
+      expect(isStrongPassword('NoNumbers!')).toBe(false);
+      expect(isStrongPassword('nouppercas3!')).toBe(false);
+      expect(isStrongPassword('NOLOWERCASE1!')).toBe(false);
+      expect(isStrongPassword('NoSpecialChar1')).toBe(false);
+    });
+
+    it('should respect custom options', () => {
+      expect(isStrongPassword('simple', { minLength: 6, requireUppercase: false, requireNumbers: false, requireSpecialChars: false })).toBe(true);
+      expect(isStrongPassword('PASSWORD', { requireLowercase: false, requireNumbers: false, requireSpecialChars: false })).toBe(true);
+    });
+  });
+
+  describe('isBusinessNumber', () => {
+    it('should validate 10-digit business numbers', () => {
+      expect(isBusinessNumber('1234567890')).toBe(true);
+      expect(isBusinessNumber('123-45-67890')).toBe(true);
+    });
+
+    it('should reject invalid business numbers', () => {
+      expect(isBusinessNumber('123456789')).toBe(false);
+      expect(isBusinessNumber('12345678901')).toBe(false);
+    });
+  });
+});

package/src/form/formatter.ts

@@ -0,0 +1,85 @@
+/**
+ * Form Formatter Utilities
+ */
+
+/**
+ * 전화번호 포맷팅 (010-1234-5678)
+ */
+export function formatPhoneNumber(value: string): string {
+  const cleaned = value.replace(/[^0-9]/g, '');
+
+  if (cleaned.length <= 3) return cleaned;
+  if (cleaned.length <= 7) {
+    return `${cleaned.slice(0, 3)}-${cleaned.slice(3)}`;
+  }
+  if (cleaned.length <= 11) {
+    return `${cleaned.slice(0, 3)}-${cleaned.slice(3, 7)}-${cleaned.slice(7)}`;
+  }
+
+  return `${cleaned.slice(0, 3)}-${cleaned.slice(3, 7)}-${cleaned.slice(7, 11)}`;
+}
+
+/**
+ * 사업자등록번호 포맷팅 (123-45-67890)
+ */
+export function formatBusinessNumber(value: string): string {
+  const cleaned = value.replace(/[^0-9]/g, '');
+
+  if (cleaned.length <= 3) return cleaned;
+  if (cleaned.length <= 5) {
+    return `${cleaned.slice(0, 3)}-${cleaned.slice(3)}`;
+  }
+  if (cleaned.length <= 10) {
+    return `${cleaned.slice(0, 3)}-${cleaned.slice(3, 5)}-${cleaned.slice(5)}`;
+  }
+
+  return `${cleaned.slice(0, 3)}-${cleaned.slice(3, 5)}-${cleaned.slice(5, 10)}`;
+}
+
+/**
+ * 신용카드 번호 포맷팅 (1234-5678-9012-3456)
+ */
+export function formatCreditCard(value: string): string {
+  const cleaned = value.replace(/[^0-9]/g, '');
+  const groups = cleaned.match(/.{1,4}/g);
+  return groups ? groups.join('-') : cleaned;
+}
+
+/**
+ * 숫자만 추출
+ */
+export function extractNumbers(value: string): string {
+  return value.replace(/[^0-9]/g, '');
+}
+
+/**
+ * 통화 포맷팅 (천 단위 콤마)
+ * @param value - 숫자 값
+ * @param currency - 통화 기호 (기본값: '원')
+ */
+export function formatCurrency(value: number | string, currency: string = '원'): string {
+  const num = typeof value === 'string' ? parseFloat(value) : value;
+  if (isNaN(num)) return '0' + currency;
+
+  return num.toLocaleString('ko-KR') + currency;
+}
+
+/**
+ * 주민등록번호 앞자리만 표시 (123456-*******)
+ */
+export function maskResidentNumber(value: string): string {
+  const cleaned = value.replace(/[^0-9]/g, '');
+  if (cleaned.length < 6) return cleaned;
+
+  return `${cleaned.slice(0, 6)}-${'*'.repeat(7)}`;
+}
+
+/**
+ * 카드번호 마스킹 (1234-****-****-5678)
+ */
+export function maskCreditCard(value: string): string {
+  const cleaned = value.replace(/[^0-9]/g, '');
+  if (cleaned.length < 12) return value;
+
+  return `${cleaned.slice(0, 4)}-****-****-${cleaned.slice(-4)}`;
+}

package/src/form/helpers.ts

@@ -0,0 +1,44 @@
+/**
+ * Form State Helpers
+ */
+
+/**
+ * 폼 에러가 있는지 확인
+ */
+export function hasFormErrors(errors: Record<string, any>): boolean {
+  return Object.keys(errors).length > 0;
+}
+
+/**
+ * 변경된 필드만 추출
+ */
+export function getChangedFields<T extends Record<string, any>>(
+  original: T,
+  current: T
+): Partial<T> {
+  const changed: Partial<T> = {};
+
+  for (const key in current) {
+    if (current[key] !== original[key]) {
+      changed[key] = current[key];
+    }
+  }
+
+  return changed;
+}
+
+/**
+ * 빈 값 제거 (null, undefined, 빈 문자열)
+ */
+export function removeEmptyValues<T extends Record<string, any>>(obj: T): Partial<T> {
+  const result: Partial<T> = {};
+
+  for (const key in obj) {
+    const value = obj[key];
+    if (value !== null && value !== undefined && value !== '') {
+      result[key] = value;
+    }
+  }
+
+  return result;
+}

package/src/form/index.ts

@@ -0,0 +1,14 @@
+/**
+ * Form Utilities
+ *
+ * This module provides utilities for form validation, formatting, and state management.
+ */
+
+// Validation utilities
+export * from './validation';
+
+// Formatter utilities
+export * from './formatter';
+
+// Helper utilities
+export * from './helpers';

package/src/form/validation.ts

@@ -0,0 +1,72 @@
+/**
+ * Form Validation Utilities
+ */
+
+/**
+ * 이메일 형식 검증
+ */
+export function isEmail(value: string): boolean {
+  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+  return emailRegex.test(value);
+}
+
+/**
+ * 한국 전화번호 형식 검증
+ * 010-1234-5678, 01012345678, 02-1234-5678 등 허용
+ */
+export function isPhoneNumber(value: string): boolean {
+  const phoneRegex = /^(01[016789]|02|0[3-9]{1}[0-9]{1})-?[0-9]{3,4}-?[0-9]{4}$/;
+  return phoneRegex.test(value.replace(/\s/g, ''));
+}
+
+/**
+ * URL 형식 검증
+ */
+export function isUrl(value: string): boolean {
+  try {
+    new URL(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 비밀번호 강도 검증
+ * @param value - 검증할 비밀번호
+ * @param options - 검증 옵션
+ */
+export function isStrongPassword(
+  value: string,
+  options: {
+    minLength?: number;
+    requireUppercase?: boolean;
+    requireLowercase?: boolean;
+    requireNumbers?: boolean;
+    requireSpecialChars?: boolean;
+  } = {}
+): boolean {
+  const {
+    minLength = 8,
+    requireUppercase = true,
+    requireLowercase = true,
+    requireNumbers = true,
+    requireSpecialChars = true,
+  } = options;
+
+  if (value.length < minLength) return false;
+  if (requireUppercase && !/[A-Z]/.test(value)) return false;
+  if (requireLowercase && !/[a-z]/.test(value)) return false;
+  if (requireNumbers && !/[0-9]/.test(value)) return false;
+  if (requireSpecialChars && !/[!@#$%^&*(),.?":{}|<>]/.test(value)) return false;
+
+  return true;
+}
+
+/**
+ * 한국 사업자등록번호 형식 검증 (10자리)
+ */
+export function isBusinessNumber(value: string): boolean {
+  const cleaned = value.replace(/[^0-9]/g, '');
+  return cleaned.length === 10;
+}

package/src/hooks/index.ts

@@ -0,0 +1,14 @@
+/**
+ * React Hooks
+ *
+ * This module provides React hooks for common use cases.
+ * Note: Requires React as a peer dependency.
+ */
+
+// Storage hooks
+export * from './useLocalStorage';
+export * from './useSessionStorage';
+
+// UI/UX hooks
+export * from './useMediaQuery';
+export * from './useClickOutside';

package/src/hooks/useClickOutside.ts

@@ -0,0 +1,114 @@
+import { useEffect, RefObject } from 'react';
+
+/**
+ * 요소 외부 클릭을 감지하는 hook
+ *
+ * @param ref - 외부 클릭을 감지할 요소의 ref
+ * @param handler - 외부 클릭 시 실행할 콜백 함수
+ * @param enabled - hook 활성화 여부 (기본값: true)
+ *
+ * @example
+ * function Dropdown() {
+ *   const [isOpen, setIsOpen] = useState(false);
+ *   const dropdownRef = useRef<HTMLDivElement>(null);
+ *
+ *   useClickOutside(dropdownRef, () => setIsOpen(false));
+ *
+ *   return (
+ *     <div ref={dropdownRef}>
+ *       <button onClick={() => setIsOpen(!isOpen)}>Toggle</button>
+ *       {isOpen && <div>Dropdown Content</div>}
+ *     </div>
+ *   );
+ * }
+ *
+ * @example
+ * // 조건부 활성화
+ * useClickOutside(modalRef, handleClose, isModalOpen);
+ */
+export function useClickOutside<T extends HTMLElement = HTMLElement>(
+  ref: RefObject<T>,
+  handler: (event: MouseEvent | TouchEvent) => void,
+  enabled: boolean = true
+): void {
+  useEffect(() => {
+    if (!enabled) {
+      return;
+    }
+
+    const listener = (event: MouseEvent | TouchEvent) => {
+      const element = ref.current;
+
+      // ref가 없거나, 클릭한 요소가 ref 내부인 경우 무시
+      if (!element || element.contains(event.target as Node)) {
+        return;
+      }
+
+      // 외부 클릭 시 handler 실행
+      handler(event);
+    };
+
+    // mousedown과 touchstart 이벤트 모두 처리 (모바일 지원)
+    document.addEventListener('mousedown', listener);
+    document.addEventListener('touchstart', listener);
+
+    return () => {
+      document.removeEventListener('mousedown', listener);
+      document.removeEventListener('touchstart', listener);
+    };
+  }, [ref, handler, enabled]);
+}
+
+/**
+ * 여러 요소의 외부 클릭을 감지하는 hook
+ *
+ * @param refs - 외부 클릭을 감지할 요소들의 ref 배열
+ * @param handler - 외부 클릭 시 실행할 콜백 함수
+ * @param enabled - hook 활성화 여부 (기본값: true)
+ *
+ * @example
+ * function Modal() {
+ *   const modalRef = useRef<HTMLDivElement>(null);
+ *   const triggerRef = useRef<HTMLButtonElement>(null);
+ *
+ *   // 모달과 트리거 버튼 외부 클릭 시 닫기
+ *   useClickOutsideMultiple(
+ *     [modalRef, triggerRef],
+ *     () => setIsOpen(false)
+ *   );
+ * }
+ */
+export function useClickOutsideMultiple<T extends HTMLElement = HTMLElement>(
+  refs: RefObject<T>[],
+  handler: (event: MouseEvent | TouchEvent) => void,
+  enabled: boolean = true
+): void {
+  useEffect(() => {
+    if (!enabled) {
+      return;
+    }
+
+    const listener = (event: MouseEvent | TouchEvent) => {
+      // 모든 ref를 확인하여 하나라도 내부 클릭이면 무시
+      const isInside = refs.some((ref) => {
+        const element = ref.current;
+        return element && element.contains(event.target as Node);
+      });
+
+      if (isInside) {
+        return;
+      }
+
+      // 모든 요소 외부 클릭 시 handler 실행
+      handler(event);
+    };
+
+    document.addEventListener('mousedown', listener);
+    document.addEventListener('touchstart', listener);
+
+    return () => {
+      document.removeEventListener('mousedown', listener);
+      document.removeEventListener('touchstart', listener);
+    };
+  }, [refs, handler, enabled]);
+}

package/src/hooks/useLocalStorage.ts

@@ -0,0 +1,112 @@
+import { useState, useEffect, useCallback, Dispatch, SetStateAction } from 'react';
+
+/**
+ * localStorage와 동기화되는 state hook
+ *
+ * @param key - localStorage 키
+ * @param initialValue - 초기값
+ * @returns [storedValue, setValue, removeValue]
+ *
+ * @example
+ * const [name, setName, removeName] = useLocalStorage('username', 'Guest');
+ *
+ * // 값 설정
+ * setName('John');
+ *
+ * // 값 제거
+ * removeName();
+ */
+export function useLocalStorage<T>(
+  key: string,
+  initialValue: T
+): [T, Dispatch<SetStateAction<T>>, () => void] {
+  // SSR 안전성 체크
+  const isBrowser = typeof window !== 'undefined';
+
+  // 초기값을 localStorage에서 가져오기
+  const readValue = useCallback((): T => {
+    if (!isBrowser) {
+      return initialValue;
+    }
+
+    try {
+      const item = window.localStorage.getItem(key);
+      return item ? (JSON.parse(item) as T) : initialValue;
+    } catch (error) {
+      console.warn(`Error reading localStorage key "${key}":`, error);
+      return initialValue;
+    }
+  }, [initialValue, key, isBrowser]);
+
+  const [storedValue, setStoredValue] = useState<T>(readValue);
+
+  // 값 설정 함수
+  const setValue: Dispatch<SetStateAction<T>> = useCallback(
+    (value) => {
+      if (!isBrowser) {
+        console.warn(
+          `Tried setting localStorage key "${key}" even though environment is not a client`
+        );
+        return;
+      }
+
+      try {
+        // useState와 동일하게 함수형 업데이트 지원
+        const newValue = value instanceof Function ? value(storedValue) : value;
+
+        // localStorage에 저장
+        window.localStorage.setItem(key, JSON.stringify(newValue));
+
+        // state 업데이트
+        setStoredValue(newValue);
+
+        // storage event 발생 (다른 탭/윈도우에 알림)
+        window.dispatchEvent(new Event('local-storage'));
+      } catch (error) {
+        console.warn(`Error setting localStorage key "${key}":`, error);
+      }
+    },
+    [key, storedValue, isBrowser]
+  );
+
+  // 값 제거 함수
+  const removeValue = useCallback(() => {
+    if (!isBrowser) {
+      return;
+    }
+
+    try {
+      window.localStorage.removeItem(key);
+      setStoredValue(initialValue);
+      window.dispatchEvent(new Event('local-storage'));
+    } catch (error) {
+      console.warn(`Error removing localStorage key "${key}":`, error);
+    }
+  }, [key, initialValue, isBrowser]);
+
+  // 다른 탭/윈도우의 변경사항 감지
+  useEffect(() => {
+    if (!isBrowser) {
+      return;
+    }
+
+    const handleStorageChange = (e: StorageEvent | Event) => {
+      if ('key' in e && e.key && e.key !== key) {
+        return;
+      }
+      setStoredValue(readValue());
+    };
+
+    // storage event 리스너 (다른 탭의 변경사항)
+    window.addEventListener('storage', handleStorageChange);
+    // 같은 페이지 내의 변경사항
+    window.addEventListener('local-storage', handleStorageChange);
+
+    return () => {
+      window.removeEventListener('storage', handleStorageChange);
+      window.removeEventListener('local-storage', handleStorageChange);
+    };
+  }, [key, readValue, isBrowser]);
+
+  return [storedValue, setValue, removeValue];
+}