jy-headless 0.3.0 → 0.3.6

package/Input/NumberInput.d.ts

@@ -0,0 +1,3 @@
+import { NumberInputProps } from './NumberInput.type';
+declare const NumberInput: ({ max, useThousandsSeparator, onChange, ...props }: NumberInputProps) => import("react/jsx-runtime").JSX.Element;
+export default NumberInput;

package/Input/NumberInput.type.d.ts

@@ -0,0 +1,31 @@
+import { TextInputProps } from './TextInput.type';
+/**
+ * 숫자 전용 입력 컴포넌트 props
+ *
+ * TextInput을 기반으로 하며,
+ * 숫자 입력에 특화된 기능을 제공합니다.
+ */
+export interface NumberInputProps extends TextInputProps {
+    /**
+     * 최대 허용 값
+     *
+     * 초과 시:
+     * - 입력 제한
+     * - 또는 validation 에러 처리 가능
+     *
+     * @example
+     * max={100}
+     */
+    max?: number;
+    /**
+     * 천 단위 구분자 사용 여부
+     *
+     * true일 경우:
+     * 10000 → 10,000
+     *
+     * 내부 값은 parse 단계에서 콤마 제거 권장
+     *
+     * @default false
+     */
+    useThousandsSeparator?: boolean;
+}

package/Input/TextInput.d.ts

@@ -0,0 +1,3 @@
+import { TextInputProps } from './TextInput.type';
+declare const TextInput: ({ maxLength, onChange, pattern, onValidate, validator, onCompositionStart, onCompositionEnd, disallowPattern, trimWhitespace, debounceMs, throttleMs, onDebouncedChange, onThrottledChange, onBlur, ...props }: TextInputProps) => import("react/jsx-runtime").JSX.Element;
+export default TextInput;

package/Input/TextInput.type.d.ts

@@ -0,0 +1,95 @@
+import { ChangeEvent, CompositionEvent, HTMLProps } from 'react';
+/**
+ * 고급 기능을 제공하는 TextInput 컴포넌트 props
+ *
+ * 기능:
+ * - validation
+ * - formatting/parsing
+ * - debounce/throttle
+ * - IME(한글 입력) 대응
+ * - 공백 제어
+ */
+export interface TextInputProps extends HTMLProps<HTMLInputElement> {
+    /**
+     * 입력값 검증 함수
+     *
+     * return:
+     * - true → 유효
+     * - false → 유효하지 않음
+     * - string → 에러 메시지
+     *
+     * @example
+     * validator={(v) => v.length > 3 || "최소 3자 이상"}
+     */
+    validator?: (value: string) => boolean | string;
+    /**
+     * 검증 결과 콜백
+     */
+    onValidate?: (isValid: boolean, error?: string) => void;
+    /**
+     * 표시용 값 포맷팅
+     *
+     * ex) 숫자 천단위 콤마
+     */
+    format?: (value: string) => string;
+    /**
+     * 실제 값으로 변환
+     *
+     * ex) 콤마 제거
+     */
+    parse?: (value: string) => string;
+    /**
+     * 입력을 막을 패턴
+     *
+     * @example 숫자만 허용
+     * disallowPattern={/[^0-9]/g}
+     */
+    disallowPattern?: RegExp;
+    /**
+     * 공백 제거 방식
+     *
+     * - true → 전체 trim
+     * - 'leading' → 앞 공백만
+     * - 'trailing' → 뒤 공백만
+     * - 'both' → 양쪽
+     */
+    trimWhitespace?: boolean | 'leading' | 'trailing' | 'both';
+    /**
+     * IME 입력 시작 이벤트
+     *
+     * 한글/중국어 입력 시 중요
+     */
+    onCompositionStart?: (e: CompositionEvent<HTMLInputElement>) => void;
+    /**
+     * IME 입력 종료 이벤트
+     */
+    onCompositionEnd?: (e: CompositionEvent<HTMLInputElement>) => void;
+    /**
+     * IME 입력 중 이벤트
+     */
+    onCompositionUpdate?: (e: CompositionEvent<HTMLInputElement>) => void;
+    /**
+     * debounce 지연(ms)
+     *
+     * @example 300
+     */
+    debounceMs?: number;
+    /**
+     * throttle 지연(ms)
+     */
+    throttleMs?: number;
+    /**
+     * debounce 후 값 변경 콜백
+     */
+    onDebouncedChange?: (value: string) => void;
+    /**
+     * throttle 후 값 변경 콜백
+     */
+    onThrottledChange?: (value: string) => void;
+    /**
+     * 기본 onChange override
+     *
+     * ⚠️ 일반 HTML onChange와 동일
+     */
+    onChange?: (value: ChangeEvent<HTMLInputElement>) => void;
+}

package/Select/Select.d.ts

@@ -0,0 +1,51 @@
+import { Dispatch, SetStateAction } from 'react';
+import { SelectOptionProps, SelectOptionsProps, SelectProps, SelectTriggerProps } from './Select.type';
+/**
+ * Select 내부 상태 공유용 Context
+ */
+type SelectContextValue = {
+    /** 드롭다운 열림 여부 */
+    open: boolean;
+    /** 드롭다운 열기/닫기 */
+    setOpen: (v: boolean) => void;
+    /** 현재 선택된 값들 */
+    value: string[];
+    /** 값 토글 */
+    toggleValue: (v: string) => void;
+    /** 다중 선택 여부 */
+    multiple: boolean;
+    /** Trigger DOM ref */
+    triggerRef: React.RefObject<HTMLDivElement | null>;
+    /** Option DOM refs 목록 */
+    optionRefs: React.MutableRefObject<HTMLDivElement[]>;
+    /** 현재 포커스된 옵션 index */
+    focusedIndex: number | null;
+    /** 포커스 index 설정 */
+    setFocusedIndex: Dispatch<SetStateAction<number>>;
+};
+/**
+ * Select Context 접근 훅
+ *
+ * @throws Select 외부에서 사용할 경우 에러
+ */
+export declare const useSelectContext: () => SelectContextValue;
+/**
+ * Compound Select 컴포넌트
+ *
+ * 사용 예시:
+ *
+ * @example
+ * <Select value={value} onChange={setValue}>
+ *   <Select.Trigger>열기</Select.Trigger>
+ *   <Select.Options>
+ *     <Select.Option value="a">A</Select.Option>
+ *     <Select.Option value="b">B</Select.Option>
+ *   </Select.Options>
+ * </Select>
+ */
+declare const Select: (({ value, onChange, multiple, children }: SelectProps) => import("react/jsx-runtime").JSX.Element) & {
+    Trigger: (props: SelectTriggerProps) => import("react/jsx-runtime").JSX.Element;
+    Options: ({ children, ...props }: SelectOptionsProps) => import("react").ReactPortal | null;
+    Option: ({ value, disabled, children, ...props }: SelectOptionProps) => import("react/jsx-runtime").JSX.Element;
+};
+export default Select;

package/Select/Select.type.d.ts

@@ -0,0 +1,52 @@
+import { HTMLProps, ReactNode } from 'react';
+/**
+ * Select 루트 컴포넌트 props
+ */
+export interface SelectProps {
+    /**
+     * 선택된 값 목록
+     *
+     * - single 모드에서도 배열로 관리
+     */
+    value: string[];
+    /**
+     * 값 변경 시 호출
+     */
+    onChange: (v: string[]) => void;
+    /**
+     * 다중 선택 여부
+     * @default false
+     */
+    multiple?: boolean;
+    /**
+     * Select.Trigger / Select.Options 등을 포함하는 children
+     */
+    children: ReactNode;
+}
+/**
+ * Options 컨테이너 props
+ */
+export interface SelectOptionsProps extends HTMLProps<HTMLDivElement> {
+}
+/**
+ * 개별 Option props
+ */
+export interface SelectOptionProps extends HTMLProps<HTMLDivElement> {
+    /**
+     * 옵션의 실제 값
+     */
+    value: string;
+    /**
+     * 비활성화 여부
+     */
+    disabled?: boolean;
+    /**
+     * 표시될 내용
+     */
+    children: ReactNode;
+}
+/**
+ * Trigger 버튼 props
+ */
+export interface SelectTriggerProps extends HTMLProps<HTMLDivElement> {
+}

package/Tooltip/Tooltip.d.ts

@@ -0,0 +1,10 @@
+import { TooltipProps } from './Tooltip.type';
+/**
+ * 범용 Tooltip 컴포넌트
+ *
+ * @example
+ * <Tooltip popover="안녕하세요" direction="top">
+ *   <button>Hover me</button>
+ * </Tooltip>
+ */
+export declare const Tooltip: ({ direction, popover, children, key, gap, autoFlip }: TooltipProps) => import("react/jsx-runtime").JSX.Element;

package/Tooltip/Tooltip.js

@@ -0,0 +1,36 @@
+import { jsxs } from 'react/jsx-runtime';
+import { useState, useRef } from 'react';
+import usePortal from '../hooks/usePortal.js';
+
+/**
+ * 범용 Tooltip 컴포넌트
+ *
+ * @example
+ * <Tooltip popover="안녕하세요" direction="top">
+ *   <button>Hover me</button>
+ * </Tooltip>
+ */
+const Tooltip = ({ direction = 'top', popover, children, key, gap = 0, autoFlip = true }) => {
+    const [visible, setVisible] = useState(false);
+    const targetRef = useRef(null);
+    const popoverRef = useRef(null);
+    const { portal, rootDom } = usePortal({
+        content: popover,
+        key,
+        visible,
+        targetRef,
+        popoverRef,
+        direction,
+        gap,
+        autoFlip,
+    });
+    const handleMouseEnter = () => {
+        setVisible(true);
+    };
+    const handleMouseLeave = () => {
+        setVisible(false);
+    };
+    return (jsxs("span", { onMouseEnter: handleMouseEnter, onMouseLeave: handleMouseLeave, ref: targetRef, children: [children, rootDom && visible && portal] }));
+};
+
+export { Tooltip };

package/Tooltip/Tooltip.type.d.ts

@@ -0,0 +1,20 @@
+import { ReactNode } from 'react';
+import { Direction } from '../hooks';
+export interface TooltipProps {
+    /** 툴팁을 띄울 대상 요소 */
+    children: ReactNode;
+    /** 툴팁에 표시될 내용 */
+    popover: ReactNode;
+    /** 툴팁이 나타날 방향 */
+    direction: Direction;
+    /** 특정 DOM 타겟 ID (선택) */
+    targetId?: string;
+    /** 포털로 렌더링할 DOM 노드 */
+    domNode?: Element;
+    /** React key 값 */
+    key?: string;
+    /** 타겟과 툴팁 사이 간격(px) */
+    gap?: number;
+    /** 화면 밖으로 나가면 자동 반전 여부 */
+    autoFlip?: boolean;
+}

package/Tooltip/index.d.ts

@@ -0,0 +1,2 @@
+export * from './Tooltip';
+export * from './Tooltip.type';

package/cjs/Input/NumberInput.d.ts

@@ -0,0 +1,3 @@
+import { NumberInputProps } from './NumberInput.type';
+declare const NumberInput: ({ max, useThousandsSeparator, onChange, ...props }: NumberInputProps) => import("react/jsx-runtime").JSX.Element;
+export default NumberInput;

package/cjs/Input/NumberInput.type.d.ts

@@ -0,0 +1,31 @@
+import { TextInputProps } from './TextInput.type';
+/**
+ * 숫자 전용 입력 컴포넌트 props
+ *
+ * TextInput을 기반으로 하며,
+ * 숫자 입력에 특화된 기능을 제공합니다.
+ */
+export interface NumberInputProps extends TextInputProps {
+    /**
+     * 최대 허용 값
+     *
+     * 초과 시:
+     * - 입력 제한
+     * - 또는 validation 에러 처리 가능
+     *
+     * @example
+     * max={100}
+     */
+    max?: number;
+    /**
+     * 천 단위 구분자 사용 여부
+     *
+     * true일 경우:
+     * 10000 → 10,000
+     *
+     * 내부 값은 parse 단계에서 콤마 제거 권장
+     *
+     * @default false
+     */
+    useThousandsSeparator?: boolean;
+}

package/cjs/Input/TextInput.d.ts

@@ -0,0 +1,3 @@
+import { TextInputProps } from './TextInput.type';
+declare const TextInput: ({ maxLength, onChange, pattern, onValidate, validator, onCompositionStart, onCompositionEnd, disallowPattern, trimWhitespace, debounceMs, throttleMs, onDebouncedChange, onThrottledChange, onBlur, ...props }: TextInputProps) => import("react/jsx-runtime").JSX.Element;
+export default TextInput;

package/cjs/Input/TextInput.type.d.ts

@@ -0,0 +1,95 @@
+import { ChangeEvent, CompositionEvent, HTMLProps } from 'react';
+/**
+ * 고급 기능을 제공하는 TextInput 컴포넌트 props
+ *
+ * 기능:
+ * - validation
+ * - formatting/parsing
+ * - debounce/throttle
+ * - IME(한글 입력) 대응
+ * - 공백 제어
+ */
+export interface TextInputProps extends HTMLProps<HTMLInputElement> {
+    /**
+     * 입력값 검증 함수
+     *
+     * return:
+     * - true → 유효
+     * - false → 유효하지 않음
+     * - string → 에러 메시지
+     *
+     * @example
+     * validator={(v) => v.length > 3 || "최소 3자 이상"}
+     */
+    validator?: (value: string) => boolean | string;
+    /**
+     * 검증 결과 콜백
+     */
+    onValidate?: (isValid: boolean, error?: string) => void;
+    /**
+     * 표시용 값 포맷팅
+     *
+     * ex) 숫자 천단위 콤마
+     */
+    format?: (value: string) => string;
+    /**
+     * 실제 값으로 변환
+     *
+     * ex) 콤마 제거
+     */
+    parse?: (value: string) => string;
+    /**
+     * 입력을 막을 패턴
+     *
+     * @example 숫자만 허용
+     * disallowPattern={/[^0-9]/g}
+     */
+    disallowPattern?: RegExp;
+    /**
+     * 공백 제거 방식
+     *
+     * - true → 전체 trim
+     * - 'leading' → 앞 공백만
+     * - 'trailing' → 뒤 공백만
+     * - 'both' → 양쪽
+     */
+    trimWhitespace?: boolean | 'leading' | 'trailing' | 'both';
+    /**
+     * IME 입력 시작 이벤트
+     *
+     * 한글/중국어 입력 시 중요
+     */
+    onCompositionStart?: (e: CompositionEvent<HTMLInputElement>) => void;
+    /**
+     * IME 입력 종료 이벤트
+     */
+    onCompositionEnd?: (e: CompositionEvent<HTMLInputElement>) => void;
+    /**
+     * IME 입력 중 이벤트
+     */
+    onCompositionUpdate?: (e: CompositionEvent<HTMLInputElement>) => void;
+    /**
+     * debounce 지연(ms)
+     *
+     * @example 300
+     */
+    debounceMs?: number;
+    /**
+     * throttle 지연(ms)
+     */
+    throttleMs?: number;
+    /**
+     * debounce 후 값 변경 콜백
+     */
+    onDebouncedChange?: (value: string) => void;
+    /**
+     * throttle 후 값 변경 콜백
+     */
+    onThrottledChange?: (value: string) => void;
+    /**
+     * 기본 onChange override
+     *
+     * ⚠️ 일반 HTML onChange와 동일
+     */
+    onChange?: (value: ChangeEvent<HTMLInputElement>) => void;
+}

package/cjs/Select/Select.d.ts

@@ -0,0 +1,51 @@
+import { Dispatch, SetStateAction } from 'react';
+import { SelectOptionProps, SelectOptionsProps, SelectProps, SelectTriggerProps } from './Select.type';
+/**
+ * Select 내부 상태 공유용 Context
+ */
+type SelectContextValue = {
+    /** 드롭다운 열림 여부 */
+    open: boolean;
+    /** 드롭다운 열기/닫기 */
+    setOpen: (v: boolean) => void;
+    /** 현재 선택된 값들 */
+    value: string[];
+    /** 값 토글 */
+    toggleValue: (v: string) => void;
+    /** 다중 선택 여부 */
+    multiple: boolean;
+    /** Trigger DOM ref */
+    triggerRef: React.RefObject<HTMLDivElement | null>;
+    /** Option DOM refs 목록 */
+    optionRefs: React.MutableRefObject<HTMLDivElement[]>;
+    /** 현재 포커스된 옵션 index */
+    focusedIndex: number | null;
+    /** 포커스 index 설정 */
+    setFocusedIndex: Dispatch<SetStateAction<number>>;
+};
+/**
+ * Select Context 접근 훅
+ *
+ * @throws Select 외부에서 사용할 경우 에러
+ */
+export declare const useSelectContext: () => SelectContextValue;
+/**
+ * Compound Select 컴포넌트
+ *
+ * 사용 예시:
+ *
+ * @example
+ * <Select value={value} onChange={setValue}>
+ *   <Select.Trigger>열기</Select.Trigger>
+ *   <Select.Options>
+ *     <Select.Option value="a">A</Select.Option>
+ *     <Select.Option value="b">B</Select.Option>
+ *   </Select.Options>
+ * </Select>
+ */
+declare const Select: (({ value, onChange, multiple, children }: SelectProps) => import("react/jsx-runtime").JSX.Element) & {
+    Trigger: (props: SelectTriggerProps) => import("react/jsx-runtime").JSX.Element;
+    Options: ({ children, ...props }: SelectOptionsProps) => import("react").ReactPortal | null;
+    Option: ({ value, disabled, children, ...props }: SelectOptionProps) => import("react/jsx-runtime").JSX.Element;
+};
+export default Select;

package/cjs/Select/Select.type.d.ts

@@ -0,0 +1,52 @@
+import { HTMLProps, ReactNode } from 'react';
+/**
+ * Select 루트 컴포넌트 props
+ */
+export interface SelectProps {
+    /**
+     * 선택된 값 목록
+     *
+     * - single 모드에서도 배열로 관리
+     */
+    value: string[];
+    /**
+     * 값 변경 시 호출
+     */
+    onChange: (v: string[]) => void;
+    /**
+     * 다중 선택 여부
+     * @default false
+     */
+    multiple?: boolean;
+    /**
+     * Select.Trigger / Select.Options 등을 포함하는 children
+     */
+    children: ReactNode;
+}
+/**
+ * Options 컨테이너 props
+ */
+export interface SelectOptionsProps extends HTMLProps<HTMLDivElement> {
+}
+/**
+ * 개별 Option props
+ */
+export interface SelectOptionProps extends HTMLProps<HTMLDivElement> {
+    /**
+     * 옵션의 실제 값
+     */
+    value: string;
+    /**
+     * 비활성화 여부
+     */
+    disabled?: boolean;
+    /**
+     * 표시될 내용
+     */
+    children: ReactNode;
+}
+/**
+ * Trigger 버튼 props
+ */
+export interface SelectTriggerProps extends HTMLProps<HTMLDivElement> {
+}

package/cjs/Tooltip/Tooltip.d.ts

@@ -0,0 +1,10 @@
+import { TooltipProps } from './Tooltip.type';
+/**
+ * 범용 Tooltip 컴포넌트
+ *
+ * @example
+ * <Tooltip popover="안녕하세요" direction="top">
+ *   <button>Hover me</button>
+ * </Tooltip>
+ */
+export declare const Tooltip: ({ direction, popover, children, key, gap, autoFlip }: TooltipProps) => import("react/jsx-runtime").JSX.Element;

package/cjs/Tooltip/Tooltip.js

@@ -0,0 +1,38 @@
+'use strict';
+
+var jsxRuntime = require('react/jsx-runtime');
+var react = require('react');
+var usePortal = require('../hooks/usePortal.js');
+
+/**
+ * 범용 Tooltip 컴포넌트
+ *
+ * @example
+ * <Tooltip popover="안녕하세요" direction="top">
+ *   <button>Hover me</button>
+ * </Tooltip>
+ */
+const Tooltip = ({ direction = 'top', popover, children, key, gap = 0, autoFlip = true }) => {
+    const [visible, setVisible] = react.useState(false);
+    const targetRef = react.useRef(null);
+    const popoverRef = react.useRef(null);
+    const { portal, rootDom } = usePortal({
+        content: popover,
+        key,
+        visible,
+        targetRef,
+        popoverRef,
+        direction,
+        gap,
+        autoFlip,
+    });
+    const handleMouseEnter = () => {
+        setVisible(true);
+    };
+    const handleMouseLeave = () => {
+        setVisible(false);
+    };
+    return (jsxRuntime.jsxs("span", { onMouseEnter: handleMouseEnter, onMouseLeave: handleMouseLeave, ref: targetRef, children: [children, rootDom && visible && portal] }));
+};
+
+exports.Tooltip = Tooltip;

package/cjs/Tooltip/Tooltip.type.d.ts

@@ -0,0 +1,20 @@
+import { ReactNode } from 'react';
+import { Direction } from '../hooks';
+export interface TooltipProps {
+    /** 툴팁을 띄울 대상 요소 */
+    children: ReactNode;
+    /** 툴팁에 표시될 내용 */
+    popover: ReactNode;
+    /** 툴팁이 나타날 방향 */
+    direction: Direction;
+    /** 특정 DOM 타겟 ID (선택) */
+    targetId?: string;
+    /** 포털로 렌더링할 DOM 노드 */
+    domNode?: Element;
+    /** React key 값 */
+    key?: string;
+    /** 타겟과 툴팁 사이 간격(px) */
+    gap?: number;
+    /** 화면 밖으로 나가면 자동 반전 여부 */
+    autoFlip?: boolean;
+}

package/cjs/Tooltip/index.d.ts

@@ -0,0 +1,2 @@
+export * from './Tooltip';
+export * from './Tooltip.type';

package/cjs/hooks/index.d.ts

@@ -0,0 +1,3 @@
+export * from './usePortal';
+export * from './useDebounce';
+export * from './useThrottle';

package/cjs/hooks/useDebounce.d.ts

@@ -0,0 +1 @@
+export declare const useDebounce: (callback: (...args: any[]) => void, delay: number) => (...args: any[]) => void;

package/cjs/hooks/useDebounce.js

@@ -0,0 +1,24 @@
+'use strict';
+
+var react = require('react');
+
+const useDebounce = (callback, delay) => {
+    const timeoutRef = react.useRef(0);
+    react.useEffect(() => {
+        return () => {
+            if (timeoutRef.current) {
+                clearTimeout(timeoutRef.current);
+            }
+        };
+    }, []);
+    return react.useCallback((...args) => {
+        if (timeoutRef.current) {
+            clearTimeout(timeoutRef.current);
+        }
+        timeoutRef.current = setTimeout(() => {
+            callback(...args);
+        }, delay);
+    }, [callback, delay]);
+};
+
+exports.useDebounce = useDebounce;

package/cjs/hooks/usePortal.d.ts

@@ -0,0 +1,23 @@
+import { Key, ReactNode, RefObject } from 'react';
+type Position = {
+    top: number;
+    left: number;
+};
+export type Direction = 'top-left' | 'top-center' | 'top' | 'top-right' | 'left' | 'right' | 'bottom-left' | 'bottom' | 'bottom-center' | 'bottom-right';
+type UsePortalProps = {
+    content: ReactNode;
+    key?: Key | null;
+    visible?: boolean;
+    targetRef?: RefObject<HTMLElement | null>;
+    popoverRef?: RefObject<HTMLElement | null>;
+    direction?: Direction;
+    gap?: number;
+    position?: Position;
+    autoFlip?: boolean;
+};
+declare const usePortal: ({ content, key, visible, targetRef, popoverRef, direction, gap, position: customPosition, autoFlip, }: UsePortalProps) => {
+    portal: import("react").ReactPortal;
+    rootDom: HTMLElement;
+    finalDirection: Direction;
+};
+export default usePortal;

package/cjs/hooks/usePortal.js

@@ -0,0 +1,80 @@
+'use strict';
+
+var jsxRuntime = require('react/jsx-runtime');
+var react = require('react');
+var reactDom = require('react-dom');
+
+const usePortal = ({ content, key, visible = true, targetRef, popoverRef, direction = 'top', gap = 0, position: customPosition, autoFlip = true, }) => {
+    const rootDom = react.useMemo(() => document.body, []);
+    const [position, setPosition] = react.useState(customPosition || { top: 0, left: 0 });
+    const [finalDirection, setFinalDirection] = react.useState(direction);
+    const getOppositeDirection = (dir) => {
+        if (dir.startsWith('top'))
+            return dir.replace('top', 'bottom');
+        if (dir.startsWith('bottom'))
+            return dir.replace('bottom', 'top');
+        if (dir === 'left')
+            return 'right';
+        if (dir === 'right')
+            return 'left';
+        return dir;
+    };
+    const getPopoverPosition = (targetRect, popoverRect, dir) => {
+        let top = (dir.startsWith('top')
+            ? targetRect.top - popoverRect.height
+            : dir.startsWith('bottom')
+                ? targetRect.top + targetRect.height
+                : targetRect.top + targetRect.height / 2 - popoverRect.height / 2) - gap;
+        let left = dir.endsWith('left')
+            ? targetRect.left - popoverRect.width - gap
+            : (dir.endsWith('right')
+                ? targetRect.left + targetRect.width + gap
+                : targetRect.left + targetRect.width / 2 - popoverRect.width / 2);
+        return { top, left };
+    };
+    const isOutOfViewport = (pos, popoverRect) => {
+        const viewportWidth = window.innerWidth;
+        const viewportHeight = window.innerHeight;
+        return (pos.top < 0 || // 상단 밖
+            pos.left < 0 || // 좌측 밖
+            pos.top + popoverRect.height > viewportHeight + window.scrollY || // 하단 밖
+            pos.left + popoverRect.width > viewportWidth + window.scrollX // 우측 밖
+        );
+    };
+    react.useLayoutEffect(() => {
+        if (visible && targetRef?.current && popoverRef?.current) {
+            const targetRect = targetRef.current.getBoundingClientRect();
+            const popoverRect = popoverRef.current.getBoundingClientRect();
+            // 원래 방향으로 위치 계산
+            let calculatedPosition = getPopoverPosition(targetRect, popoverRect, direction);
+            let currentDirection = direction;
+            // autoFlip이 활성화되어 있고 화면 밖으로 나가면 반대 방향 시도
+            if (autoFlip && isOutOfViewport(calculatedPosition, popoverRect)) {
+                const oppositeDir = getOppositeDirection(direction);
+                const oppositePosition = getPopoverPosition(targetRect, popoverRect, oppositeDir);
+                // 반대 방향이 더 나으면 반대 방향 사용
+                if (!isOutOfViewport(oppositePosition, popoverRect)) {
+                    calculatedPosition = oppositePosition;
+                    currentDirection = oppositeDir;
+                }
+            }
+            setFinalDirection(currentDirection);
+            setPosition({
+                top: calculatedPosition.top + window.scrollY,
+                left: calculatedPosition.left + window.scrollX,
+            });
+        }
+        else if (customPosition) {
+            setPosition(customPosition);
+        }
+    }, [visible, direction, gap, customPosition, autoFlip]);
+    const wrappedContent = targetRef ? (jsxRuntime.jsx("span", { ref: popoverRef, style: {
+            position: 'absolute',
+            top: `${position.top}px`,
+            left: `${position.left}px`,
+        }, children: content })) : content;
+    const portal = reactDom.createPortal(wrappedContent, rootDom, key);
+    return { portal, rootDom, finalDirection };
+};
+
+module.exports = usePortal;

package/cjs/hooks/useThrottle.d.ts

@@ -0,0 +1 @@
+export declare const useThrottle: (callback: (...args: any[]) => void, delay: number) => (...args: any[]) => void;

package/cjs/hooks/useThrottle.js

@@ -0,0 +1,34 @@
+'use strict';
+
+var react = require('react');
+
+const useThrottle = (callback, delay) => {
+    const lastRun = react.useRef(Date.now());
+    const timeoutRef = react.useRef(0);
+    react.useEffect(() => {
+        return () => {
+            if (timeoutRef.current) {
+                clearTimeout(timeoutRef.current);
+            }
+        };
+    }, []);
+    return react.useCallback((...args) => {
+        const now = Date.now();
+        const timeSinceLastRun = now - lastRun.current;
+        if (timeSinceLastRun >= delay) {
+            callback(...args);
+            lastRun.current = now;
+        }
+        else {
+            if (timeoutRef.current) {
+                clearTimeout(timeoutRef.current);
+            }
+            timeoutRef.current = setTimeout(() => {
+                callback(...args);
+                lastRun.current = Date.now();
+            }, delay - timeSinceLastRun);
+        }
+    }, [callback, delay]);
+};
+
+exports.useThrottle = useThrottle;

package/cjs/index.d.ts

@@ -1 +1,4 @@
-export * from './Popover';
+export * from './hooks';
+export * from './Tooltip';
+export * from './Input/TextInput';
+export * from './Input/NumberInput';

package/cjs/index.js

@@ -1,7 +1,14 @@
 'use strict';
 
-var Popover = require('./Popover/Popover.js');
+require('react/jsx-runtime');
+require('react');
+require('react-dom');
+var useDebounce = require('./hooks/useDebounce.js');
+var useThrottle = require('./hooks/useThrottle.js');
+var Tooltip = require('./Tooltip/Tooltip.js');
 
 
 
-exports.Popover = Popover.Popover;
+exports.useDebounce = useDebounce.useDebounce;
+exports.useThrottle = useThrottle.useThrottle;
+exports.Tooltip = Tooltip.Tooltip;

package/hooks/index.d.ts

@@ -0,0 +1,3 @@
+export * from './usePortal';
+export * from './useDebounce';
+export * from './useThrottle';

package/hooks/useDebounce.d.ts

@@ -0,0 +1 @@
+export declare const useDebounce: (callback: (...args: any[]) => void, delay: number) => (...args: any[]) => void;

package/hooks/useDebounce.js

@@ -0,0 +1,22 @@
+import { useRef, useEffect, useCallback } from 'react';
+
+const useDebounce = (callback, delay) => {
+    const timeoutRef = useRef(0);
+    useEffect(() => {
+        return () => {
+            if (timeoutRef.current) {
+                clearTimeout(timeoutRef.current);
+            }
+        };
+    }, []);
+    return useCallback((...args) => {
+        if (timeoutRef.current) {
+            clearTimeout(timeoutRef.current);
+        }
+        timeoutRef.current = setTimeout(() => {
+            callback(...args);
+        }, delay);
+    }, [callback, delay]);
+};
+
+export { useDebounce };

package/hooks/usePortal.d.ts

@@ -0,0 +1,23 @@
+import { Key, ReactNode, RefObject } from 'react';
+type Position = {
+    top: number;
+    left: number;
+};
+export type Direction = 'top-left' | 'top-center' | 'top' | 'top-right' | 'left' | 'right' | 'bottom-left' | 'bottom' | 'bottom-center' | 'bottom-right';
+type UsePortalProps = {
+    content: ReactNode;
+    key?: Key | null;
+    visible?: boolean;
+    targetRef?: RefObject<HTMLElement | null>;
+    popoverRef?: RefObject<HTMLElement | null>;
+    direction?: Direction;
+    gap?: number;
+    position?: Position;
+    autoFlip?: boolean;
+};
+declare const usePortal: ({ content, key, visible, targetRef, popoverRef, direction, gap, position: customPosition, autoFlip, }: UsePortalProps) => {
+    portal: import("react").ReactPortal;
+    rootDom: HTMLElement;
+    finalDirection: Direction;
+};
+export default usePortal;

package/hooks/usePortal.js

@@ -0,0 +1,78 @@
+import { jsx } from 'react/jsx-runtime';
+import { useMemo, useState, useLayoutEffect } from 'react';
+import { createPortal } from 'react-dom';
+
+const usePortal = ({ content, key, visible = true, targetRef, popoverRef, direction = 'top', gap = 0, position: customPosition, autoFlip = true, }) => {
+    const rootDom = useMemo(() => document.body, []);
+    const [position, setPosition] = useState(customPosition || { top: 0, left: 0 });
+    const [finalDirection, setFinalDirection] = useState(direction);
+    const getOppositeDirection = (dir) => {
+        if (dir.startsWith('top'))
+            return dir.replace('top', 'bottom');
+        if (dir.startsWith('bottom'))
+            return dir.replace('bottom', 'top');
+        if (dir === 'left')
+            return 'right';
+        if (dir === 'right')
+            return 'left';
+        return dir;
+    };
+    const getPopoverPosition = (targetRect, popoverRect, dir) => {
+        let top = (dir.startsWith('top')
+            ? targetRect.top - popoverRect.height
+            : dir.startsWith('bottom')
+                ? targetRect.top + targetRect.height
+                : targetRect.top + targetRect.height / 2 - popoverRect.height / 2) - gap;
+        let left = dir.endsWith('left')
+            ? targetRect.left - popoverRect.width - gap
+            : (dir.endsWith('right')
+                ? targetRect.left + targetRect.width + gap
+                : targetRect.left + targetRect.width / 2 - popoverRect.width / 2);
+        return { top, left };
+    };
+    const isOutOfViewport = (pos, popoverRect) => {
+        const viewportWidth = window.innerWidth;
+        const viewportHeight = window.innerHeight;
+        return (pos.top < 0 || // 상단 밖
+            pos.left < 0 || // 좌측 밖
+            pos.top + popoverRect.height > viewportHeight + window.scrollY || // 하단 밖
+            pos.left + popoverRect.width > viewportWidth + window.scrollX // 우측 밖
+        );
+    };
+    useLayoutEffect(() => {
+        if (visible && targetRef?.current && popoverRef?.current) {
+            const targetRect = targetRef.current.getBoundingClientRect();
+            const popoverRect = popoverRef.current.getBoundingClientRect();
+            // 원래 방향으로 위치 계산
+            let calculatedPosition = getPopoverPosition(targetRect, popoverRect, direction);
+            let currentDirection = direction;
+            // autoFlip이 활성화되어 있고 화면 밖으로 나가면 반대 방향 시도
+            if (autoFlip && isOutOfViewport(calculatedPosition, popoverRect)) {
+                const oppositeDir = getOppositeDirection(direction);
+                const oppositePosition = getPopoverPosition(targetRect, popoverRect, oppositeDir);
+                // 반대 방향이 더 나으면 반대 방향 사용
+                if (!isOutOfViewport(oppositePosition, popoverRect)) {
+                    calculatedPosition = oppositePosition;
+                    currentDirection = oppositeDir;
+                }
+            }
+            setFinalDirection(currentDirection);
+            setPosition({
+                top: calculatedPosition.top + window.scrollY,
+                left: calculatedPosition.left + window.scrollX,
+            });
+        }
+        else if (customPosition) {
+            setPosition(customPosition);
+        }
+    }, [visible, direction, gap, customPosition, autoFlip]);
+    const wrappedContent = targetRef ? (jsx("span", { ref: popoverRef, style: {
+            position: 'absolute',
+            top: `${position.top}px`,
+            left: `${position.left}px`,
+        }, children: content })) : content;
+    const portal = createPortal(wrappedContent, rootDom, key);
+    return { portal, rootDom, finalDirection };
+};
+
+export { usePortal as default };

package/hooks/useThrottle.d.ts

@@ -0,0 +1 @@
+export declare const useThrottle: (callback: (...args: any[]) => void, delay: number) => (...args: any[]) => void;

package/hooks/useThrottle.js

@@ -0,0 +1,32 @@
+import { useRef, useEffect, useCallback } from 'react';
+
+const useThrottle = (callback, delay) => {
+    const lastRun = useRef(Date.now());
+    const timeoutRef = useRef(0);
+    useEffect(() => {
+        return () => {
+            if (timeoutRef.current) {
+                clearTimeout(timeoutRef.current);
+            }
+        };
+    }, []);
+    return useCallback((...args) => {
+        const now = Date.now();
+        const timeSinceLastRun = now - lastRun.current;
+        if (timeSinceLastRun >= delay) {
+            callback(...args);
+            lastRun.current = now;
+        }
+        else {
+            if (timeoutRef.current) {
+                clearTimeout(timeoutRef.current);
+            }
+            timeoutRef.current = setTimeout(() => {
+                callback(...args);
+                lastRun.current = Date.now();
+            }, delay - timeSinceLastRun);
+        }
+    }, [callback, delay]);
+};
+
+export { useThrottle };

package/index.d.ts

@@ -1 +1,4 @@
-export * from './Popover';
+export * from './hooks';
+export * from './Tooltip';
+export * from './Input/TextInput';
+export * from './Input/NumberInput';

package/index.js

@@ -1 +1,6 @@
-export { Popover } from './Popover/Popover.js';
+import 'react/jsx-runtime';
+import 'react';
+import 'react-dom';
+export { useDebounce } from './hooks/useDebounce.js';
+export { useThrottle } from './hooks/useThrottle.js';
+export { Tooltip } from './Tooltip/Tooltip.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jy-headless",
-  "version": "0.3.0",
+  "version": "0.3.6",
   "description": "A lightweight and customizable headless UI library for React components",
   "license": "MIT",
   "repository": "https://github.com/yCZwIqY/jy-headless",
@@ -18,6 +18,21 @@
       "require": "./cjs/cjs/index.js",
       "types": "./cjs/index.d.ts"
     },
+    "./useDebounce": {
+      "import": "./hooks/useDebounce.js",
+      "require": "./cjs/hooks/useDebounce.js",
+      "types": "./hooks/useDebounce.d.ts"
+    },
+    "./usePortal": {
+      "import": "./hooks/usePortal.js",
+      "require": "./cjs/hooks/usePortal.js",
+      "types": "./hooks/usePortal.d.ts"
+    },
+    "./useThrottle": {
+      "import": "./hooks/useThrottle.js",
+      "require": "./cjs/hooks/useThrottle.js",
+      "types": "./hooks/useThrottle.d.ts"
+    },
     "./index": {
       "import": "./index.js",
       "require": "./cjs/index.js",
@@ -27,6 +42,11 @@
       "import": "./Popover/Popover.js",
       "require": "./cjs/Popover/Popover.js",
       "types": "./Popover/Popover.d.ts"
+    },
+    "./Tooltip": {
+      "import": "./Tooltip/Tooltip.js",
+      "require": "./cjs/Tooltip/Tooltip.js",
+      "types": "./Tooltip/Tooltip.d.ts"
     }
   },
   "keywords": [

package/version.txt

@@ -1 +1 @@
-0.3.0
+0.3.6