jy-headless 0.3.0 → 0.3.7

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/Input/index.d.ts

@@ -0,0 +1,2 @@
+export * from './NumberInput';
+export * from './TextInput';

package/Popover/Popover.d.ts

@@ -1,2 +1,2 @@
-import { HoverProps } from './Popover.type';
-export declare const Popover: ({ children, direction, popover, domNode, rootId, key }: HoverProps) => import("react/jsx-runtime").JSX.Element;
+import { PopoverProps } from './Popover.type';
+export declare const Popover: ({ direction, popover, children, key, gap, autoFlip }: PopoverProps) => import("react/jsx-runtime").JSX.Element;

package/Popover/Popover.js

@@ -1,75 +1,28 @@
-import { jsxs, jsx } from 'react/jsx-runtime';
-import { useState, useRef, useCallback, useLayoutEffect } from 'react';
-import { createPortal } from 'react-dom';
+import { jsxs } from 'react/jsx-runtime';
+import { useState, useRef } from 'react';
+import usePortal from '../hooks/usePortal.js';
 
-const Popover = ({ children, direction, popover, domNode, rootId, key }) => {
+const Popover = ({ direction = 'top', popover, children, key, gap = 0, autoFlip = true }) => {
     const [visible, setVisible] = useState(false);
-    const [position, setPosition] = useState({ top: 0, left: 0 });
-    const rootDom = domNode ?? document.getElementById(rootId ?? 'root');
     const targetRef = useRef(null);
     const popoverRef = useRef(null);
-    const getPopoverPosition = useCallback((targetRect, popoverRect) => {
-        let top = 0;
-        let left = 0;
-        switch (direction) {
-            case 'top-left':
-                top = targetRect.top - popoverRect.height;
-                left = targetRect.left;
-                break;
-            case 'top-center':
-            case 'top':
-                top = targetRect.top - popoverRect.height;
-                left = targetRect.left + (targetRect.width - popoverRect.width) / 2;
-                break;
-            case 'top-right':
-                top = targetRect.top - popoverRect.height;
-                left = targetRect.right - popoverRect.width;
-                break;
-            case 'left':
-                top = targetRect.top + (targetRect.height - popoverRect.height) / 2;
-                left = targetRect.left - popoverRect.width;
-                break;
-            case 'right':
-                top = targetRect.top + (targetRect.height - popoverRect.height) / 2;
-                left = targetRect.right;
-                break;
-            case 'bottom-left':
-                top = targetRect.bottom;
-                left = targetRect.left;
-                break;
-            case 'bottom-center':
-            case 'bottom':
-                top = targetRect.bottom;
-                left = targetRect.left + (targetRect.width - popoverRect.width) / 2;
-                break;
-            case 'bottom-right':
-                top = targetRect.bottom;
-                left = targetRect.right - popoverRect.width;
-                break;
-        }
-        return { top, left };
-    }, [direction]);
+    const { portal, rootDom } = usePortal({
+        content: popover,
+        key,
+        visible,
+        targetRef,
+        popoverRef,
+        direction,
+        gap,
+        autoFlip,
+    });
     const handleMouseEnter = () => {
         setVisible(true);
     };
     const handleMouseLeave = () => {
         setVisible(false);
     };
-    useLayoutEffect(() => {
-        if (visible && targetRef.current && popoverRef.current) {
-            const targetRect = targetRef.current.getBoundingClientRect();
-            const popoverRect = popoverRef.current.getBoundingClientRect();
-            const { top, left } = getPopoverPosition(targetRect, popoverRect);
-            setPosition({ top: top + window.scrollY, left: left + window.scrollX });
-        }
-    }, [visible, popover, getPopoverPosition]);
-    return (jsxs("span", { onMouseEnter: handleMouseEnter, onMouseLeave: handleMouseLeave, ref: targetRef, children: [children, rootDom &&
-                visible &&
-                createPortal(jsx("span", { ref: popoverRef, style: {
-                        position: 'absolute',
-                        top: `${position.top}px`,
-                        left: `${position.left}px`,
-                    }, children: popover }), rootDom, key)] }));
+    return (jsxs("span", { onMouseEnter: handleMouseEnter, onMouseLeave: handleMouseLeave, ref: targetRef, children: [children, rootDom && visible && portal] }));
 };
 
 export { Popover };

package/Popover/Popover.type.d.ts

@@ -1,9 +1,12 @@
 import { ReactNode } from 'react';
-export interface HoverProps {
+import { Direction } from '../hooks';
+export interface PopoverProps {
     children: ReactNode;
     popover: ReactNode;
-    direction: 'top-left' | 'top-center' | 'top' | 'top-right' | 'left' | 'right' | 'bottom-left' | 'bottom' | 'bottom-center' | 'bottom-right';
-    rootId?: string;
+    direction: Direction;
+    targetId?: string;
     domNode?: Element;
     key?: string;
+    gap?: number;
+    autoFlip?: boolean;
 }

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.js

@@ -0,0 +1,176 @@
+import { jsx } from 'react/jsx-runtime';
+import { createContext, useContext, useState, useRef, useEffect, useMemo } from 'react';
+import usePortal from '../hooks/usePortal.js';
+
+const SelectContext = createContext(null);
+/**
+ * Select Context 접근 훅
+ *
+ * @throws Select 외부에서 사용할 경우 에러
+ */
+const useSelectContext = () => {
+    const ctx = useContext(SelectContext);
+    if (!ctx)
+        throw new Error('Select components must be used within <Select>');
+    return ctx;
+};
+/**
+ * Select 루트 컨테이너
+ *
+ * - 상태 관리 담당
+ * - Context Provider 역할
+ */
+const SelectContainer = ({ value, onChange, multiple = false, children }) => {
+    const [open, setOpen] = useState(false);
+    const triggerRef = useRef(null);
+    const optionRefs = useRef([]);
+    const [focusedIndex, setFocusedIndex] = useState(-1);
+    const toggleValue = (v) => {
+        if (!multiple) {
+            onChange([v]);
+            setOpen(false);
+            return;
+        }
+        onChange(value.includes(v)
+            ? value.filter(i => i !== v)
+            : [...value, v]);
+    };
+    return (jsx(SelectContext.Provider, { value: {
+            open,
+            setOpen,
+            value,
+            toggleValue,
+            multiple,
+            triggerRef,
+            optionRefs,
+            focusedIndex,
+            setFocusedIndex,
+        }, children: children }));
+};
+/**
+ * Select 트리거 버튼
+ *
+ * - 클릭 시 Options 열림
+ * - 최초 포커스를 첫 옵션으로 이동
+ */
+const Trigger = (props) => {
+    const { open, setOpen, triggerRef, setFocusedIndex } = useSelectContext();
+    return (jsx("div", { ref: triggerRef, role: 'button', "aria-expanded": open, onClick: (e) => {
+            setOpen(!open);
+            setFocusedIndex(0);
+            props.onClick?.(e);
+        }, ...props }));
+};
+/**
+ * Options 드롭다운 영역
+ *
+ * 기능:
+ * - 외부 클릭 시 닫힘
+ * - ESC 키 닫기
+ * - ↑ ↓ 키 포커스 이동
+ * - portal 렌더링
+ */
+const Options = ({ children, ...props }) => {
+    const { open, triggerRef, setOpen, setFocusedIndex, optionRefs } = useSelectContext();
+    const popoverRef = useRef(null);
+    const triggerWidth = triggerRef.current?.getBoundingClientRect().width;
+    useEffect(() => {
+        if (!open)
+            return;
+        const handleOutsideClick = (e) => {
+            const target = e.target;
+            if (triggerRef.current?.contains(target) ||
+                popoverRef.current?.contains(target)) {
+                return;
+            }
+            setOpen(false);
+        };
+        document.addEventListener('mousedown', handleOutsideClick);
+        return () => {
+            document.removeEventListener('mousedown', handleOutsideClick);
+        };
+    }, [open, setOpen, triggerRef]);
+    useEffect(() => {
+        if (!open)
+            return;
+        const handleKeyDown = (e) => {
+            e.preventDefault();
+            if (e.key === 'Escape') {
+                setOpen(false);
+                setFocusedIndex(-1);
+            }
+            if (e.key === 'ArrowUp') {
+                setFocusedIndex(prev => prev - 1 < 0 ? optionRefs.current.length - 1 : prev - 1);
+            }
+            if (e.key === 'ArrowDown') {
+                setFocusedIndex(prev => prev + 1 >= optionRefs.current.length ? 0 : prev + 1);
+            }
+        };
+        document.addEventListener('keydown', handleKeyDown);
+        return () => {
+            optionRefs.current = [];
+            document.removeEventListener('keydown', handleKeyDown);
+        };
+    }, [open]);
+    const { portal } = usePortal({
+        visible: open,
+        targetRef: triggerRef,
+        popoverRef,
+        direction: 'bottom',
+        gap: 4,
+        content: (jsx("div", { ref: popoverRef, style: { width: triggerWidth }, ...props, children: children })),
+    });
+    return open ? portal : null;
+};
+/**
+ * 개별 선택 옵션
+ *
+ * 기능:
+ * - 선택 상태 표시
+ * - 포커스 관리
+ * - disabled 지원
+ */
+const Option = ({ value, disabled, children, ...props }) => {
+    const { value: selected, toggleValue, optionRefs, focusedIndex } = useSelectContext();
+    const isSelected = selected.includes(value);
+    const [index, setIndex] = useState(null);
+    const isFocused = useMemo(() => focusedIndex === index, [focusedIndex, index]);
+    const ref = useRef(null);
+    useEffect(() => {
+        if (ref.current && index === null) {
+            setIndex(optionRefs.current.length);
+            optionRefs.current[optionRefs.current.length] = ref.current;
+        }
+    }, []);
+    useEffect(() => {
+        ref.current?.setAttribute('data-focused', String(focusedIndex === index));
+        if (focusedIndex === index) {
+            ref.current?.focus();
+        }
+    }, [focusedIndex, index]);
+    return (jsx("div", { ref: ref, role: 'option', "aria-selected": isSelected, "aria-disabled": disabled, "data-focused": isFocused, onClick: () => {
+            if (!disabled)
+                toggleValue(value);
+        }, ...props, children: children }));
+};
+/**
+ * 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>
+ */
+Object.assign(SelectContainer, {
+    Trigger,
+    Options,
+    Option,
+});
+
+export { useSelectContext };

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/Select/index.d.ts

@@ -0,0 +1 @@
+export * from './Select';

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;