goodchuck-utils 1.2.0 → 1.4.0

package/dist/hooks/useClickOutside.js

@@ -0,0 +1,94 @@
+import { useEffect } 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(ref, handler, enabled = true) {
+    useEffect(() => {
+        if (!enabled) {
+            return;
+        }
+        const listener = (event) => {
+            const element = ref.current;
+            // ref가 없거나, 클릭한 요소가 ref 내부인 경우 무시
+            if (!element || element.contains(event.target)) {
+                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(refs, handler, enabled = true) {
+    useEffect(() => {
+        if (!enabled) {
+            return;
+        }
+        const listener = (event) => {
+            // 모든 ref를 확인하여 하나라도 내부 클릭이면 무시
+            const isInside = refs.some((ref) => {
+                const element = ref.current;
+                return element && element.contains(event.target);
+            });
+            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/dist/hooks/useLocalStorage.d.ts

@@ -0,0 +1,19 @@
+import { 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 declare function useLocalStorage<T>(key: string, initialValue: T): [T, Dispatch<SetStateAction<T>>, () => void];
+//# sourceMappingURL=useLocalStorage.d.ts.map

package/dist/hooks/useLocalStorage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useLocalStorage.d.ts","sourceRoot":"","sources":["../../src/hooks/useLocalStorage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoC,QAAQ,EAAE,cAAc,EAAE,MAAM,OAAO,CAAC;AAEnF;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAC/B,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,CAAC,GACd,CAAC,CAAC,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,IAAI,CAAC,CA0F9C"}

package/dist/hooks/useLocalStorage.js

@@ -0,0 +1,91 @@
+import { useState, useEffect, useCallback } 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(key, initialValue) {
+    // SSR 안전성 체크
+    const isBrowser = typeof window !== 'undefined';
+    // 초기값을 localStorage에서 가져오기
+    const readValue = useCallback(() => {
+        if (!isBrowser) {
+            return initialValue;
+        }
+        try {
+            const item = window.localStorage.getItem(key);
+            return item ? JSON.parse(item) : initialValue;
+        }
+        catch (error) {
+            console.warn(`Error reading localStorage key "${key}":`, error);
+            return initialValue;
+        }
+    }, [initialValue, key, isBrowser]);
+    const [storedValue, setStoredValue] = useState(readValue);
+    // 값 설정 함수
+    const setValue = 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) => {
+            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];
+}

package/dist/hooks/useMediaQuery.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 미디어 쿼리 매칭 여부를 반환하는 hook
+ *
+ * @param query - CSS 미디어 쿼리 문자열
+ * @returns 미디어 쿼리 매칭 여부
+ *
+ * @example
+ * // 모바일 체크
+ * const isMobile = useMediaQuery('(max-width: 768px)');
+ *
+ * @example
+ * // 태블릿 체크
+ * const isTablet = useMediaQuery('(min-width: 769px) and (max-width: 1024px)');
+ *
+ * @example
+ * // 데스크톱 체크
+ * const isDesktop = useMediaQuery('(min-width: 1025px)');
+ *
+ * @example
+ * // 다크모드 체크
+ * const isDarkMode = useMediaQuery('(prefers-color-scheme: dark)');
+ *
+ * @example
+ * // 가로 모드 체크
+ * const isLandscape = useMediaQuery('(orientation: landscape)');
+ */
+export declare function useMediaQuery(query: string): boolean;
+/**
+ * 일반적인 브레이크포인트를 위한 헬퍼 hook들
+ */
+/**
+ * 모바일 디바이스 체크 (768px 이하)
+ * @example
+ * const isMobile = useIsMobile();
+ * if (isMobile) return <MobileView />;
+ */
+export declare function useIsMobile(): boolean;
+/**
+ * 태블릿 디바이스 체크 (769px ~ 1024px)
+ * @example
+ * const isTablet = useIsTablet();
+ */
+export declare function useIsTablet(): boolean;
+/**
+ * 데스크톱 디바이스 체크 (1025px 이상)
+ * @example
+ * const isDesktop = useIsDesktop();
+ */
+export declare function useIsDesktop(): boolean;
+/**
+ * 다크모드 체크
+ * @example
+ * const isDarkMode = useIsDarkMode();
+ */
+export declare function useIsDarkMode(): boolean;
+//# sourceMappingURL=useMediaQuery.d.ts.map

package/dist/hooks/useMediaQuery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useMediaQuery.d.ts","sourceRoot":"","sources":["../../src/hooks/useMediaQuery.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CA8CpD;AAED;;GAEG;AAEH;;;;;GAKG;AACH,wBAAgB,WAAW,IAAI,OAAO,CAErC;AAED;;;;GAIG;AACH,wBAAgB,WAAW,IAAI,OAAO,CAErC;AAED;;;;GAIG;AACH,wBAAgB,YAAY,IAAI,OAAO,CAEtC;AAED;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,OAAO,CAEvC"}

package/dist/hooks/useMediaQuery.js

@@ -0,0 +1,104 @@
+import { useState, useEffect } from 'react';
+/**
+ * 미디어 쿼리 매칭 여부를 반환하는 hook
+ *
+ * @param query - CSS 미디어 쿼리 문자열
+ * @returns 미디어 쿼리 매칭 여부
+ *
+ * @example
+ * // 모바일 체크
+ * const isMobile = useMediaQuery('(max-width: 768px)');
+ *
+ * @example
+ * // 태블릿 체크
+ * const isTablet = useMediaQuery('(min-width: 769px) and (max-width: 1024px)');
+ *
+ * @example
+ * // 데스크톱 체크
+ * const isDesktop = useMediaQuery('(min-width: 1025px)');
+ *
+ * @example
+ * // 다크모드 체크
+ * const isDarkMode = useMediaQuery('(prefers-color-scheme: dark)');
+ *
+ * @example
+ * // 가로 모드 체크
+ * const isLandscape = useMediaQuery('(orientation: landscape)');
+ */
+export function useMediaQuery(query) {
+    // SSR 안전성을 위한 초기값 설정
+    const getMatches = (query) => {
+        if (typeof window !== 'undefined') {
+            return window.matchMedia(query).matches;
+        }
+        return false;
+    };
+    const [matches, setMatches] = useState(getMatches(query));
+    useEffect(() => {
+        if (typeof window === 'undefined') {
+            return;
+        }
+        const mediaQuery = window.matchMedia(query);
+        // 초기 상태 설정
+        setMatches(mediaQuery.matches);
+        // 미디어 쿼리 변경 감지 (최신 API)
+        const handleChange = (event) => {
+            setMatches(event.matches);
+        };
+        // 이벤트 리스너 등록
+        // addEventListener를 지원하는 브라우저
+        if (mediaQuery.addEventListener) {
+            mediaQuery.addEventListener('change', handleChange);
+        }
+        else {
+            // 구형 브라우저 지원 (deprecated)
+            mediaQuery.addListener(handleChange);
+        }
+        // 클린업
+        return () => {
+            if (mediaQuery.removeEventListener) {
+                mediaQuery.removeEventListener('change', handleChange);
+            }
+            else {
+                mediaQuery.removeListener(handleChange);
+            }
+        };
+    }, [query]);
+    return matches;
+}
+/**
+ * 일반적인 브레이크포인트를 위한 헬퍼 hook들
+ */
+/**
+ * 모바일 디바이스 체크 (768px 이하)
+ * @example
+ * const isMobile = useIsMobile();
+ * if (isMobile) return <MobileView />;
+ */
+export function useIsMobile() {
+    return useMediaQuery('(max-width: 768px)');
+}
+/**
+ * 태블릿 디바이스 체크 (769px ~ 1024px)
+ * @example
+ * const isTablet = useIsTablet();
+ */
+export function useIsTablet() {
+    return useMediaQuery('(min-width: 769px) and (max-width: 1024px)');
+}
+/**
+ * 데스크톱 디바이스 체크 (1025px 이상)
+ * @example
+ * const isDesktop = useIsDesktop();
+ */
+export function useIsDesktop() {
+    return useMediaQuery('(min-width: 1025px)');
+}
+/**
+ * 다크모드 체크
+ * @example
+ * const isDarkMode = useIsDarkMode();
+ */
+export function useIsDarkMode() {
+    return useMediaQuery('(prefers-color-scheme: dark)');
+}

package/dist/hooks/useSessionStorage.d.ts

@@ -0,0 +1,19 @@
+import { Dispatch, SetStateAction } from 'react';
+/**
+ * sessionStorage와 동기화되는 state hook
+ *
+ * @param key - sessionStorage 키
+ * @param initialValue - 초기값
+ * @returns [storedValue, setValue, removeValue]
+ *
+ * @example
+ * const [token, setToken, removeToken] = useSessionStorage('auth-token', '');
+ *
+ * // 값 설정
+ * setToken('abc123');
+ *
+ * // 값 제거
+ * removeToken();
+ */
+export declare function useSessionStorage<T>(key: string, initialValue: T): [T, Dispatch<SetStateAction<T>>, () => void];
+//# sourceMappingURL=useSessionStorage.d.ts.map

package/dist/hooks/useSessionStorage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSessionStorage.d.ts","sourceRoot":"","sources":["../../src/hooks/useSessionStorage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoC,QAAQ,EAAE,cAAc,EAAE,MAAM,OAAO,CAAC;AAEnF;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,CAAC,GACd,CAAC,CAAC,EAAE,QAAQ,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,IAAI,CAAC,CAoF9C"}

package/dist/hooks/useSessionStorage.js

@@ -0,0 +1,85 @@
+import { useState, useEffect, useCallback } from 'react';
+/**
+ * sessionStorage와 동기화되는 state hook
+ *
+ * @param key - sessionStorage 키
+ * @param initialValue - 초기값
+ * @returns [storedValue, setValue, removeValue]
+ *
+ * @example
+ * const [token, setToken, removeToken] = useSessionStorage('auth-token', '');
+ *
+ * // 값 설정
+ * setToken('abc123');
+ *
+ * // 값 제거
+ * removeToken();
+ */
+export function useSessionStorage(key, initialValue) {
+    // SSR 안전성 체크
+    const isBrowser = typeof window !== 'undefined';
+    // 초기값을 sessionStorage에서 가져오기
+    const readValue = useCallback(() => {
+        if (!isBrowser) {
+            return initialValue;
+        }
+        try {
+            const item = window.sessionStorage.getItem(key);
+            return item ? JSON.parse(item) : initialValue;
+        }
+        catch (error) {
+            console.warn(`Error reading sessionStorage key "${key}":`, error);
+            return initialValue;
+        }
+    }, [initialValue, key, isBrowser]);
+    const [storedValue, setStoredValue] = useState(readValue);
+    // 값 설정 함수
+    const setValue = useCallback((value) => {
+        if (!isBrowser) {
+            console.warn(`Tried setting sessionStorage key "${key}" even though environment is not a client`);
+            return;
+        }
+        try {
+            // useState와 동일하게 함수형 업데이트 지원
+            const newValue = value instanceof Function ? value(storedValue) : value;
+            // sessionStorage에 저장
+            window.sessionStorage.setItem(key, JSON.stringify(newValue));
+            // state 업데이트
+            setStoredValue(newValue);
+            // storage event 발생
+            window.dispatchEvent(new Event('session-storage'));
+        }
+        catch (error) {
+            console.warn(`Error setting sessionStorage key "${key}":`, error);
+        }
+    }, [key, storedValue, isBrowser]);
+    // 값 제거 함수
+    const removeValue = useCallback(() => {
+        if (!isBrowser) {
+            return;
+        }
+        try {
+            window.sessionStorage.removeItem(key);
+            setStoredValue(initialValue);
+            window.dispatchEvent(new Event('session-storage'));
+        }
+        catch (error) {
+            console.warn(`Error removing sessionStorage key "${key}":`, error);
+        }
+    }, [key, initialValue, isBrowser]);
+    // 같은 페이지 내의 변경사항 감지
+    useEffect(() => {
+        if (!isBrowser) {
+            return;
+        }
+        const handleStorageChange = () => {
+            setStoredValue(readValue());
+        };
+        // 같은 페이지 내의 변경사항
+        window.addEventListener('session-storage', handleStorageChange);
+        return () => {
+            window.removeEventListener('session-storage', handleStorageChange);
+        };
+    }, [key, readValue, isBrowser]);
+    return [storedValue, setValue, removeValue];
+}

package/dist/index.d.ts

@@ -1,2 +1,4 @@
 export * from './date';
+export * from './form';
+export * from './string';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,QAAQ,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,QAAQ,CAAC;AAGvB,cAAc,QAAQ,CAAC;AAGvB,cAAc,UAAU,CAAC"}

package/dist/index.js

@@ -1,7 +1,12 @@
 // Date utilities
 export * from './date';
-// String utilities (placeholder for future)
-// export * from './string';
+// Form utilities
+export * from './form';
+// String utilities
+export * from './string';
+// React Hooks (import separately: 'goodchuck-utils/hooks')
+// Note: Hooks are not exported from main entry to avoid React dependency for non-React users
+// export * from './hooks';
 // Array utilities (placeholder for future)
 // export * from './array';
 // Object utilities (placeholder for future)

package/dist/string/__tests__/case.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=case.test.d.ts.map

package/dist/string/__tests__/case.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"case.test.d.ts","sourceRoot":"","sources":["../../../src/string/__tests__/case.test.ts"],"names":[],"mappings":""}

package/dist/string/__tests__/case.test.js

@@ -0,0 +1,61 @@
+import { describe, it, expect } from 'vitest';
+import { capitalize, capitalizeWords, camelCase, pascalCase, snakeCase, kebabCase, constantCase, } from '../case';
+describe('String Case Conversion', () => {
+    describe('capitalize', () => {
+        it('should capitalize first letter', () => {
+            expect(capitalize('hello')).toBe('Hello');
+            expect(capitalize('hello world')).toBe('Hello world');
+            expect(capitalize('HELLO')).toBe('HELLO');
+        });
+        it('should handle empty string', () => {
+            expect(capitalize('')).toBe('');
+        });
+    });
+    describe('capitalizeWords', () => {
+        it('should capitalize each word', () => {
+            expect(capitalizeWords('hello world')).toBe('Hello World');
+            expect(capitalizeWords('the quick brown fox')).toBe('The Quick Brown Fox');
+        });
+    });
+    describe('camelCase', () => {
+        it('should convert to camelCase', () => {
+            expect(camelCase('hello world')).toBe('helloWorld');
+            expect(camelCase('hello-world')).toBe('helloWorld');
+            expect(camelCase('hello_world')).toBe('helloWorld');
+            expect(camelCase('Hello World')).toBe('helloWorld');
+        });
+        it('should handle already camelCase strings', () => {
+            expect(camelCase('helloWorld')).toBe('helloworld');
+        });
+    });
+    describe('pascalCase', () => {
+        it('should convert to PascalCase', () => {
+            expect(pascalCase('hello world')).toBe('HelloWorld');
+            expect(pascalCase('hello-world')).toBe('HelloWorld');
+            expect(pascalCase('hello_world')).toBe('HelloWorld');
+        });
+    });
+    describe('snakeCase', () => {
+        it('should convert to snake_case', () => {
+            expect(snakeCase('helloWorld')).toBe('hello_world');
+            expect(snakeCase('Hello World')).toBe('hello_world');
+            expect(snakeCase('hello-world')).toBe('hello_world');
+            expect(snakeCase('HelloWorld')).toBe('hello_world');
+        });
+    });
+    describe('kebabCase', () => {
+        it('should convert to kebab-case', () => {
+            expect(kebabCase('helloWorld')).toBe('hello-world');
+            expect(kebabCase('Hello World')).toBe('hello-world');
+            expect(kebabCase('hello_world')).toBe('hello-world');
+            expect(kebabCase('HelloWorld')).toBe('hello-world');
+        });
+    });
+    describe('constantCase', () => {
+        it('should convert to CONSTANT_CASE', () => {
+            expect(constantCase('helloWorld')).toBe('HELLO_WORLD');
+            expect(constantCase('Hello World')).toBe('HELLO_WORLD');
+            expect(constantCase('hello-world')).toBe('HELLO_WORLD');
+        });
+    });
+});

package/dist/string/__tests__/manipulation.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=manipulation.test.d.ts.map

package/dist/string/__tests__/manipulation.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manipulation.test.d.ts","sourceRoot":"","sources":["../../../src/string/__tests__/manipulation.test.ts"],"names":[],"mappings":""}