jy-headless 0.3.7 → 0.3.12

package/README.md

@@ -0,0 +1,62 @@
+# jy-headless
+
+React용 Headless UI 라이브러리
+
+---
+
+## 특징
+
+* React 기반 Headless UI
+* 스타일 비강제 (디자인 시스템 자유 적용)
+* Portal 기반 레이어 UI 지원
+* 고급 입력 처리 지원
+    * debounce / throttle
+    * validate / format / parse
+    * IME 대응
+* 접근성 고려한 인터랙션 로직
+* 재사용 가능한 훅 제공
+
+---
+
+## 제공 요소
+
+### Components
+
+* Select (Compound Component, Portal 기반)
+* Autocomplete (Compound Component, Portal 기반)
+* TextInput
+* NumberInput
+* Tooltip (Portal 기반)
+
+---
+
+### Hooks
+
+* usePortal
+* useDebounce
+* useThrottle
+* (추가 예정) useOutsideClick 등
+
+---
+
+## 사용 목적
+
+* 디자인 시스템 구축
+* 커스텀 UI 라이브러리 제작
+* 접근성 + 인터랙션 로직 재사용
+* 입력 처리 로직 표준화
+
+---
+
+## 스타일링
+
+* Tailwind
+* CSS-in-JS
+* CSS Modules
+* 어떤 방식이든 자유
+
+---
+
+## 라이선스
+
+MIT

package/dist/Autocomplete/Autocomplete.d.ts

@@ -0,0 +1,8 @@
+import React from 'react';
+import type { AutocompleteInputProps, AutocompleteOptionProps, AutocompleteOptionsProps, AutocompleteProps } from './Autocomplete.type';
+declare const Autocomplete: (({ value, onChange, inputValue, onInputChange, disabled, filterFn, children, }: AutocompleteProps) => import("react/jsx-runtime").JSX.Element) & {
+    Input: ({ onKeyDown, onFocus, onChange, onCompositionStart, onCompositionEnd, ...props }: AutocompleteInputProps) => import("react/jsx-runtime").JSX.Element;
+    Options: ({ items, renderItem, itemHeight, maxVisibleItems, overscan, children, ...props }: AutocompleteOptionsProps) => React.ReactPortal | null;
+    Option: ({ value, label, disabled, children, ...props }: AutocompleteOptionProps) => import("react/jsx-runtime").JSX.Element | null;
+};
+export default Autocomplete;

package/dist/Autocomplete/Autocomplete.js

@@ -0,0 +1,297 @@
+import { jsxs, jsx, Fragment } from 'react/jsx-runtime';
+import { createContext, useState, useRef, useId, useMemo, useEffect, useContext } from 'react';
+import usePortal from '../hooks/usePortal.js';
+import TextInput from '../Input/TextInput.js';
+
+const AutocompleteContext = createContext(null);
+const useAutocomplete = () => {
+    const ctx = useContext(AutocompleteContext);
+    if (!ctx)
+        throw new Error('Autocomplete components must be used within <Autocomplete>');
+    return ctx;
+};
+const defaultFilter = (item, query) => item.label.toLowerCase().includes(query.trim().toLowerCase());
+/**
+ * Root
+ */
+const AutocompleteContainer = ({ value, onChange, inputValue, onInputChange, disabled, filterFn = defaultFilter, children, }) => {
+    const [open, setOpen] = useState(false);
+    const [activeIndex, setActiveIndex] = useState(-1);
+    const inputRef = useRef(null);
+    // controlled/uncontrolled query
+    const [internalQuery, setInternalQuery] = useState('');
+    const query = inputValue ?? internalQuery;
+    const setQuery = (v) => {
+        onInputChange?.(v);
+        if (inputValue === undefined)
+            setInternalQuery(v);
+    };
+    const listboxId = useId();
+    // NOTE:
+    // - virtualization을 제대로 하려면 options data(items)가 Root에 필요하지만,
+    //   compound API 유지를 위해 Options에서 items를 주입받아 Root에서 filtered를 만들기 어렵다.
+    // 그래서 Root에서는 "filtered"를 Options에서 제공할 수 있게 설계하면 복잡해짐.
+    // ✅ 해결: Options에 items를 주면 Root가 접근할 수 있도록 "itemsRef"를 둔다.
+    const itemsRef = useRef([]);
+    const setItems = (items) => {
+        itemsRef.current = items;
+    };
+    const filtered = useMemo(() => {
+        const src = itemsRef.current ?? [];
+        if (!query.trim())
+            return src;
+        return src.filter((it) => filterFn(it, query));
+    }, [query, filterFn]);
+    const close = () => {
+        setOpen(false);
+        setActiveIndex(-1);
+    };
+    const commitByIndex = (index) => {
+        const item = filtered[index];
+        if (!item || item.disabled)
+            return;
+        onChange(item.value);
+        setQuery(item.label);
+        close();
+    };
+    // 외부 value 변경 시 input label 동기화
+    useEffect(() => {
+        if (!value)
+            return;
+        const found = itemsRef.current.find((i) => i.value === value);
+        if (found)
+            setQuery(found.label);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [value]);
+    const statusText = useMemo(() => {
+        if (!open)
+            return '';
+        const n = filtered.length;
+        if (n === 0)
+            return 'No results.';
+        if (n === 1)
+            return '1 result available.';
+        return `${n} results available.`;
+    }, [open, filtered.length]);
+    return (jsxs(AutocompleteContext.Provider, { value: {
+            open,
+            setOpen,
+            selectedValue: value,
+            setSelectedValue: onChange,
+            query,
+            setQuery,
+            disabled,
+            inputRef,
+            listboxId,
+            activeIndex,
+            setActiveIndex,
+            filtered,
+            statusText,
+            commitByIndex,
+            close,
+        }, children: [jsx(ItemsBridge, { onItems: setItems }), children] }));
+};
+/**
+ * Options에서 items를 주입해주기 위한 브릿지(보이지 않는 컴포넌트)
+ * - Options가 items prop을 받으면, 내부에서 window.__ 같은 걸 쓰지 않고 Root ref에 주입
+ */
+const ItemsBridgeContext = createContext(null);
+const ItemsBridge = ({ onItems }) => {
+    return jsx(ItemsBridgeContext.Provider, { value: onItems });
+};
+const useItemsBridge = () => useContext(ItemsBridgeContext);
+/**
+ * Input (Combobox Trigger)
+ * - 포커스는 input 유지
+ * - aria-activedescendant로 active option을 알려줌
+ */
+// ...생략
+const Input = ({ onKeyDown, onFocus, onChange, onCompositionStart, onCompositionEnd, ...props }) => {
+    const { open, setOpen, query, setQuery, disabled, listboxId, activeIndex, setActiveIndex, filtered, commitByIndex, close, inputRef, } = useAutocomplete();
+    // ✅ IME 조합 중에는 방향키/엔터로 옵션 선택하지 않게 막기
+    const composingRef = useRef(false);
+    const activeId = activeIndex >= 0 ? `${listboxId}-opt-${activeIndex}` : undefined;
+    const move = (delta) => {
+        if (!filtered.length)
+            return;
+        setOpen(true);
+        setActiveIndex(activeIndex < 0 ? 0 : (activeIndex + delta + filtered.length) % filtered.length);
+    };
+    return (jsxs(Fragment, { children: [jsx(TextInput, { ref: inputRef, role: 'combobox', "aria-autocomplete": 'list', "aria-expanded": open, "aria-controls": listboxId, "aria-activedescendant": activeId, disabled: disabled, value: query, onFocus: (e) => {
+                    if (!disabled) {
+                        setOpen(true);
+                        setActiveIndex(filtered.length ? 0 : -1);
+                    }
+                    onFocus?.(e);
+                }, onChange: (e) => {
+                    if (disabled)
+                        return;
+                    setQuery(e.target.value);
+                    setOpen(true);
+                    setActiveIndex(0);
+                    onChange?.(e);
+                }, onCompositionStart: (e) => {
+                    composingRef.current = true;
+                    onCompositionStart?.(e);
+                }, onCompositionEnd: (e) => {
+                    composingRef.current = false;
+                    onCompositionEnd?.(e);
+                }, onKeyDown: (e) => {
+                    if (disabled)
+                        return;
+                    // ✅ 조합중이면 Autocomplete 키처리 하지 않음
+                    if (composingRef.current) {
+                        onKeyDown?.(e);
+                        return;
+                    }
+                    switch (e.key) {
+                        case 'ArrowDown':
+                            e.preventDefault();
+                            move(1);
+                            break;
+                        case 'ArrowUp':
+                            e.preventDefault();
+                            move(-1);
+                            break;
+                        case 'Enter':
+                            if (open && activeIndex >= 0) {
+                                e.preventDefault();
+                                commitByIndex(activeIndex);
+                            }
+                            break;
+                        case 'Escape':
+                            e.preventDefault();
+                            close();
+                            break;
+                        case 'Tab':
+                            close();
+                            break;
+                    }
+                    onKeyDown?.(e);
+                }, ...props }), jsx("span", { "aria-live": 'polite', style: {
+                    position: 'absolute',
+                    width: 1,
+                    height: 1,
+                    overflow: 'hidden',
+                    clip: 'rect(0 0 0 0)',
+                    whiteSpace: 'nowrap',
+                }, children: open ? `${filtered.length} results.` : '' })] }));
+};
+/**
+ * Options
+ * - portal
+ * - outside click close
+ * - virtualization (items + renderItem provided)
+ */
+const Options = ({ items, renderItem, itemHeight = 36, maxVisibleItems = 8, overscan = 3, children, ...props }) => {
+    const bridge = useItemsBridge();
+    const { open, setOpen, close, inputRef, listboxId, filtered, activeIndex, setActiveIndex, commitByIndex, } = useAutocomplete();
+    // items 주입(가상화 모드)
+    useEffect(() => {
+        if (items && bridge)
+            bridge(items);
+    }, [items, bridge]);
+    const popoverRef = useRef(null);
+    const triggerWidth = inputRef.current?.getBoundingClientRect().width;
+    // outside click
+    useEffect(() => {
+        if (!open)
+            return;
+        const onDown = (e) => {
+            const t = e.target;
+            if (inputRef.current?.contains(t) || popoverRef.current?.contains(t))
+                return;
+            close();
+        };
+        document.addEventListener('mousedown', onDown);
+        return () => document.removeEventListener('mousedown', onDown);
+    }, [open, close, inputRef]);
+    // scroll container ref for virtualization
+    const scrollRef = useRef(null);
+    // active option이 항상 보이게 스크롤 보정
+    useEffect(() => {
+        if (!open)
+            return;
+        if (!scrollRef.current)
+            return;
+        if (activeIndex < 0)
+            return;
+        const top = activeIndex * itemHeight;
+        const bottom = top + itemHeight;
+        const viewTop = scrollRef.current.scrollTop;
+        const viewBottom = viewTop + scrollRef.current.clientHeight;
+        if (top < viewTop)
+            scrollRef.current.scrollTop = top;
+        else if (bottom > viewBottom)
+            scrollRef.current.scrollTop = bottom - scrollRef.current.clientHeight;
+    }, [open, activeIndex, itemHeight]);
+    // virtualization range
+    const total = filtered.length;
+    const viewportCount = Math.min(maxVisibleItems, Math.max(1, total));
+    const viewportHeight = viewportCount * itemHeight;
+    const [scrollTop, setScrollTop] = useState(0);
+    const startIndex = Math.max(0, Math.floor(scrollTop / itemHeight) - overscan);
+    const endIndex = Math.min(total, Math.ceil((scrollTop + viewportHeight) / itemHeight) + overscan);
+    const visible = filtered.slice(startIndex, endIndex);
+    const { portal } = usePortal({
+        visible: open,
+        targetRef: inputRef,
+        popoverRef,
+        direction: 'bottom',
+        gap: 4,
+        content: (jsx("div", { ref: popoverRef, style: { width: triggerWidth }, ...props, children: items && renderItem ? (jsx("div", { id: listboxId, role: 'listbox', ref: scrollRef, style: { maxHeight: viewportHeight, overflow: 'auto', position: 'relative' }, onScroll: (e) => setScrollTop(e.target.scrollTop), children: jsx("div", { style: { height: total * itemHeight, position: 'relative' }, children: visible.map((item, i) => {
+                        const index = startIndex + i; // filtered index
+                        const isActive = index === activeIndex;
+                        const isSelected = item.value === undefined; // selection 표시를 더 강하게 원하면 ctx.selectedValue 비교해서 쓰면 됨
+                        return (jsx("div", { id: `${listboxId}-opt-${index}`, role: 'option', "aria-selected": isSelected, "aria-disabled": item.disabled, "data-active": isActive, tabIndex: -1, onMouseEnter: () => setActiveIndex(index), onMouseDown: (e) => {
+                                // 클릭 시 input blur 방지(중요)
+                                e.preventDefault();
+                            }, onClick: () => commitByIndex(index), style: {
+                                position: 'absolute',
+                                top: index * itemHeight,
+                                left: 0,
+                                right: 0,
+                                height: itemHeight,
+                                display: 'flex',
+                                alignItems: 'center',
+                            }, children: renderItem(item) }, item.value));
+                    }) }) })) : (
+            /* ✅ children 모드(비가상화) */
+            jsx("div", { id: listboxId, role: 'listbox', children: children })) })),
+    });
+    return open ? portal : null;
+};
+/**
+ * Option (children 모드 전용 / small list)
+ * - a11y option role/ids만 최소 보장
+ * - 가상화는 여기엔 적용하지 않음
+ */
+const Option = ({ value, label, disabled, children, ...props }) => {
+    const { listboxId, filtered, query, open, setOpen, setQuery, setSelectedValue, activeIndex, setActiveIndex, } = useAutocomplete();
+    // children 모드에서 필터링은 “간단 버전”
+    const visible = useMemo(() => {
+        if (!query.trim())
+            return true;
+        return label.toLowerCase().includes(query.trim().toLowerCase());
+    }, [label, query]);
+    useMemo(() => {
+        // filtered는 items 모드에서만 의미있음.
+        // children 모드는 간단히 -1 처리(aria-activedescendant는 items 모드가 권장)
+        return -1;
+    }, []);
+    if (!visible)
+        return null;
+    return (jsx("div", { role: "option", "aria-disabled": disabled, "aria-selected": false, tabIndex: -1, onMouseDown: (e) => e.preventDefault(), onClick: () => {
+            if (disabled)
+                return;
+            setSelectedValue(value);
+            setQuery(label);
+            setOpen(false);
+            setActiveIndex(-1);
+        }, ...props, children: children ?? label }));
+};
+Object.assign(AutocompleteContainer, {
+    Input,
+    Options,
+    Option,
+});

package/dist/Autocomplete/Autocomplete.type.d.ts

@@ -0,0 +1,37 @@
+import { HTMLAttributes, ReactNode } from 'react';
+import { TextInputProps } from '../Input/TextInput.type';
+export type AutocompleteItem = {
+    value: string;
+    label: string;
+    disabled?: boolean;
+};
+export interface AutocompleteProps {
+    value: string | null;
+    onChange: (v: string | null) => void;
+    inputValue?: string;
+    onInputChange?: (v: string) => void;
+    disabled?: boolean;
+    /** 옵션 필터 커스터마이즈 */
+    filterFn?: (item: AutocompleteItem, query: string) => boolean;
+    children: ReactNode;
+}
+export interface AutocompleteInputProps extends TextInputProps {
+    /** label 연결용 (없으면 aria-label 필수) */
+    'aria-label'?: string;
+}
+export interface AutocompleteOptionsProps extends HTMLAttributes<HTMLDivElement> {
+    /** ✅ 가상화 모드: 데이터 기반 */
+    items?: AutocompleteItem[];
+    /** 가상화 모드에서 항목 렌더 */
+    renderItem?: (item: AutocompleteItem) => ReactNode;
+    /** virtualization 옵션 */
+    itemHeight?: number;
+    maxVisibleItems?: number;
+    overscan?: number;
+}
+export interface AutocompleteOptionProps extends HTMLAttributes<HTMLDivElement> {
+    /** children 모드(비가상화) */
+    value: string;
+    label: string;
+    disabled?: boolean;
+}

package/dist/Autocomplete/index.d.ts

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

package/dist/Input/TextInput.d.ts

@@ -0,0 +1,4 @@
+import React from 'react';
+import { TextInputProps } from './TextInput.type';
+declare const TextInput: React.ForwardRefExoticComponent<TextInputProps & React.RefAttributes<HTMLInputElement>>;
+export default TextInput;

package/dist/Input/TextInput.js

@@ -0,0 +1,77 @@
+import { jsx } from 'react/jsx-runtime';
+import { forwardRef, useState, useRef, useMemo } from 'react';
+import 'react-dom';
+import { useDebounce } from '../hooks/useDebounce.js';
+import { useThrottle } from '../hooks/useThrottle.js';
+
+function mergeRefs(...refs) {
+    return (value) => {
+        refs.forEach((ref) => {
+            if (!ref)
+                return;
+            if (typeof ref === 'function')
+                ref(value);
+            else
+                ref.current = value;
+        });
+    };
+}
+const TextInput = forwardRef(({ maxLength, onChange, pattern, onValidate, validator, onCompositionStart, onCompositionEnd, disallowPattern, trimWhitespace, debounceMs, throttleMs, onDebouncedChange, onThrottledChange, onBlur, ...props }, ref) => {
+    const [isComposing, setIsComposing] = useState(false);
+    const innerRef = useRef(null);
+    const combinedRef = useMemo(() => mergeRefs(innerRef, ref), [ref]);
+    const debouncedChange = useDebounce((value) => onDebouncedChange?.(value), debounceMs || 0);
+    const throttledChange = useThrottle((value) => onThrottledChange?.(value), throttleMs || 0);
+    const handleCompositionStart = (e) => {
+        setIsComposing(true);
+        onCompositionStart?.(e);
+    };
+    const handleCompositionEnd = (e) => {
+        setIsComposing(false);
+        onCompositionEnd?.(e);
+    };
+    const handleChange = (e) => {
+        if (maxLength && !isComposing && e.target.value.length > maxLength)
+            return;
+        if (pattern) {
+            const regex = new RegExp(pattern);
+            if (!regex.test(e.target.value))
+                return;
+        }
+        if (disallowPattern && !disallowPattern.test(e.target.value))
+            return;
+        if (debounceMs && onDebouncedChange)
+            debouncedChange(e.target.value);
+        if (throttleMs && onThrottledChange)
+            throttledChange(e.target.value);
+        if (validator) {
+            const result = validator(e.target.value);
+            const isValid = typeof result === 'boolean' ? result : true;
+            const error = typeof result === 'string' ? result : undefined;
+            onValidate?.(isValid, error);
+            if (!isValid)
+                return;
+        }
+        onChange?.(e);
+    };
+    const handleBlur = (e) => {
+        if (trimWhitespace && innerRef.current) {
+            const trimmedValue = e.target.value.trim();
+            if (trimmedValue !== e.target.value) {
+                innerRef.current.value = trimmedValue;
+                const syntheticEvent = {
+                    ...e,
+                    target: innerRef.current,
+                    currentTarget: innerRef.current,
+                    type: 'change',
+                };
+                onChange?.(syntheticEvent);
+            }
+        }
+        onBlur?.(e);
+    };
+    return (jsx("input", { ref: combinedRef, ...props, onBlur: handleBlur, onChange: handleChange, onCompositionStart: handleCompositionStart, onCompositionEnd: handleCompositionEnd }));
+});
+TextInput.displayName = 'TextInput';
+
+export { TextInput as default };

package/{cjs → dist}/Input/TextInput.type.d.ts

@@ -1,4 +1,4 @@
-import { ChangeEvent, CompositionEvent, HTMLProps } from 'react';
+import { ChangeEvent, CompositionEvent, InputHTMLAttributes } from 'react';
 /**
  * 고급 기능을 제공하는 TextInput 컴포넌트 props
  *
@@ -9,7 +9,7 @@ import { ChangeEvent, CompositionEvent, HTMLProps } from 'react';
  * - IME(한글 입력) 대응
  * - 공백 제어
  */
-export interface TextInputProps extends HTMLProps<HTMLInputElement> {
+export interface TextInputProps extends InputHTMLAttributes<HTMLInputElement> {
     /**
      * 입력값 검증 함수
      *

package/dist/cjs/Autocomplete/Autocomplete.d.ts

@@ -0,0 +1,8 @@
+import React from 'react';
+import type { AutocompleteInputProps, AutocompleteOptionProps, AutocompleteOptionsProps, AutocompleteProps } from './Autocomplete.type';
+declare const Autocomplete: (({ value, onChange, inputValue, onInputChange, disabled, filterFn, children, }: AutocompleteProps) => import("react/jsx-runtime").JSX.Element) & {
+    Input: ({ onKeyDown, onFocus, onChange, onCompositionStart, onCompositionEnd, ...props }: AutocompleteInputProps) => import("react/jsx-runtime").JSX.Element;
+    Options: ({ items, renderItem, itemHeight, maxVisibleItems, overscan, children, ...props }: AutocompleteOptionsProps) => React.ReactPortal | null;
+    Option: ({ value, label, disabled, children, ...props }: AutocompleteOptionProps) => import("react/jsx-runtime").JSX.Element | null;
+};
+export default Autocomplete;