jy-headless 0.3.7 → 0.3.11

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, ...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,309 @@
+import { jsxs, jsx, Fragment } from 'react/jsx-runtime';
+import { createContext, useState, useRef, useId, useMemo, useEffect, useContext } from 'react';
+import usePortal from '../hooks/usePortal.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, ...props }) => {
+    const { open, setOpen, query, setQuery, disabled, listboxId, activeIndex, setActiveIndex, filtered, commitByIndex, close, inputRef, } = useAutocomplete();
+    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);
+    };
+    const pageMove = (deltaPages) => {
+        if (!filtered.length)
+            return;
+        setOpen(true);
+        // 10개 단위 이동(관례). 필요하면 props로 빼도 됨
+        const jump = 10 * deltaPages;
+        setActiveIndex(Math.max(0, Math.min(filtered.length - 1, (activeIndex < 0 ? 0 : activeIndex) + jump)));
+    };
+    return (jsxs(Fragment, { children: [jsx("input", { 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);
+                }, onKeyDown: (e) => {
+                    if (disabled)
+                        return;
+                    switch (e.key) {
+                        case 'ArrowDown':
+                            e.preventDefault();
+                            move(1);
+                            break;
+                        case 'ArrowUp':
+                            e.preventDefault();
+                            move(-1);
+                            break;
+                        case 'Home':
+                            e.preventDefault();
+                            setOpen(true);
+                            setActiveIndex(filtered.length ? 0 : -1);
+                            break;
+                        case 'End':
+                            e.preventDefault();
+                            setOpen(true);
+                            setActiveIndex(filtered.length ? filtered.length - 1 : -1);
+                            break;
+                        case 'PageDown':
+                            e.preventDefault();
+                            pageMove(1);
+                            break;
+                        case 'PageUp':
+                            e.preventDefault();
+                            pageMove(-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,36 @@
+import { HTMLAttributes, InputHTMLAttributes, ReactNode } from 'react';
+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 InputHTMLAttributes<HTMLInputElement> {
+    /** 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/{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, ...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/cjs/Autocomplete/Autocomplete.js

@@ -0,0 +1,311 @@
+'use strict';
+
+var jsxRuntime = require('react/jsx-runtime');
+var react = require('react');
+var usePortal = require('../hooks/usePortal.js');
+
+const AutocompleteContext = react.createContext(null);
+const useAutocomplete = () => {
+    const ctx = react.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] = react.useState(false);
+    const [activeIndex, setActiveIndex] = react.useState(-1);
+    const inputRef = react.useRef(null);
+    // controlled/uncontrolled query
+    const [internalQuery, setInternalQuery] = react.useState('');
+    const query = inputValue ?? internalQuery;
+    const setQuery = (v) => {
+        onInputChange?.(v);
+        if (inputValue === undefined)
+            setInternalQuery(v);
+    };
+    const listboxId = react.useId();
+    // NOTE:
+    // - virtualization을 제대로 하려면 options data(items)가 Root에 필요하지만,
+    //   compound API 유지를 위해 Options에서 items를 주입받아 Root에서 filtered를 만들기 어렵다.
+    // 그래서 Root에서는 "filtered"를 Options에서 제공할 수 있게 설계하면 복잡해짐.
+    // ✅ 해결: Options에 items를 주면 Root가 접근할 수 있도록 "itemsRef"를 둔다.
+    const itemsRef = react.useRef([]);
+    const setItems = (items) => {
+        itemsRef.current = items;
+    };
+    const filtered = react.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 동기화
+    react.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 = react.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 (jsxRuntime.jsxs(AutocompleteContext.Provider, { value: {
+            open,
+            setOpen,
+            selectedValue: value,
+            setSelectedValue: onChange,
+            query,
+            setQuery,
+            disabled,
+            inputRef,
+            listboxId,
+            activeIndex,
+            setActiveIndex,
+            filtered,
+            statusText,
+            commitByIndex,
+            close,
+        }, children: [jsxRuntime.jsx(ItemsBridge, { onItems: setItems }), children] }));
+};
+/**
+ * Options에서 items를 주입해주기 위한 브릿지(보이지 않는 컴포넌트)
+ * - Options가 items prop을 받으면, 내부에서 window.__ 같은 걸 쓰지 않고 Root ref에 주입
+ */
+const ItemsBridgeContext = react.createContext(null);
+const ItemsBridge = ({ onItems }) => {
+    return jsxRuntime.jsx(ItemsBridgeContext.Provider, { value: onItems });
+};
+const useItemsBridge = () => react.useContext(ItemsBridgeContext);
+/**
+ * Input (Combobox Trigger)
+ * - 포커스는 input 유지
+ * - aria-activedescendant로 active option을 알려줌
+ */
+const Input = ({ onKeyDown, onFocus, onChange, ...props }) => {
+    const { open, setOpen, query, setQuery, disabled, listboxId, activeIndex, setActiveIndex, filtered, commitByIndex, close, inputRef, } = useAutocomplete();
+    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);
+    };
+    const pageMove = (deltaPages) => {
+        if (!filtered.length)
+            return;
+        setOpen(true);
+        // 10개 단위 이동(관례). 필요하면 props로 빼도 됨
+        const jump = 10 * deltaPages;
+        setActiveIndex(Math.max(0, Math.min(filtered.length - 1, (activeIndex < 0 ? 0 : activeIndex) + jump)));
+    };
+    return (jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [jsxRuntime.jsx("input", { 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);
+                }, onKeyDown: (e) => {
+                    if (disabled)
+                        return;
+                    switch (e.key) {
+                        case 'ArrowDown':
+                            e.preventDefault();
+                            move(1);
+                            break;
+                        case 'ArrowUp':
+                            e.preventDefault();
+                            move(-1);
+                            break;
+                        case 'Home':
+                            e.preventDefault();
+                            setOpen(true);
+                            setActiveIndex(filtered.length ? 0 : -1);
+                            break;
+                        case 'End':
+                            e.preventDefault();
+                            setOpen(true);
+                            setActiveIndex(filtered.length ? filtered.length - 1 : -1);
+                            break;
+                        case 'PageDown':
+                            e.preventDefault();
+                            pageMove(1);
+                            break;
+                        case 'PageUp':
+                            e.preventDefault();
+                            pageMove(-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 }), jsxRuntime.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 주입(가상화 모드)
+    react.useEffect(() => {
+        if (items && bridge)
+            bridge(items);
+    }, [items, bridge]);
+    const popoverRef = react.useRef(null);
+    const triggerWidth = inputRef.current?.getBoundingClientRect().width;
+    // outside click
+    react.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 = react.useRef(null);
+    // active option이 항상 보이게 스크롤 보정
+    react.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] = react.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: (jsxRuntime.jsx("div", { ref: popoverRef, style: { width: triggerWidth }, ...props, children: items && renderItem ? (jsxRuntime.jsx("div", { id: listboxId, role: 'listbox', ref: scrollRef, style: { maxHeight: viewportHeight, overflow: 'auto', position: 'relative' }, onScroll: (e) => setScrollTop(e.target.scrollTop), children: jsxRuntime.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 (jsxRuntime.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 모드(비가상화) */
+            jsxRuntime.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 = react.useMemo(() => {
+        if (!query.trim())
+            return true;
+        return label.toLowerCase().includes(query.trim().toLowerCase());
+    }, [label, query]);
+    react.useMemo(() => {
+        // filtered는 items 모드에서만 의미있음.
+        // children 모드는 간단히 -1 처리(aria-activedescendant는 items 모드가 권장)
+        return -1;
+    }, []);
+    if (!visible)
+        return null;
+    return (jsxRuntime.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/cjs/Autocomplete/Autocomplete.type.d.ts

@@ -0,0 +1,36 @@
+import { HTMLAttributes, InputHTMLAttributes, ReactNode } from 'react';
+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 InputHTMLAttributes<HTMLInputElement> {
+    /** 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/cjs/Autocomplete/index.d.ts

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

package/{Input → dist/cjs/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/{cjs → dist/cjs}/index.d.ts

@@ -2,3 +2,4 @@ export * from './hooks';
 export * from './Tooltip';
 export * from './Input';
 export * from './Select';
+export * from './Autocomplete';

package/{cjs → dist/cjs}/index.js

@@ -7,6 +7,7 @@ var useDebounce = require('./hooks/useDebounce.js');
 var useThrottle = require('./hooks/useThrottle.js');
 var Tooltip = require('./Tooltip/Tooltip.js');
 var Select = require('./Select/Select.js');
+require('./Autocomplete/Autocomplete.js');
 
 
 

package/{index.d.ts → dist/index.d.ts}

@@ -2,3 +2,4 @@ export * from './hooks';
 export * from './Tooltip';
 export * from './Input';
 export * from './Select';
+export * from './Autocomplete';

package/{index.js → dist/index.js}

@@ -5,3 +5,4 @@ export { useDebounce } from './hooks/useDebounce.js';
 export { useThrottle } from './hooks/useThrottle.js';
 export { Tooltip } from './Tooltip/Tooltip.js';
 export { useSelectContext } from './Select/Select.js';
+import './Autocomplete/Autocomplete.js';

package/package.json

@@ -1,57 +1,25 @@
 {
   "name": "jy-headless",
-  "version": "0.3.7",
+  "version": "0.3.11",
   "description": "A lightweight and customizable headless UI library for React components",
-  "license": "MIT",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
   "repository": "https://github.com/yCZwIqY/jy-headless",
-  "main": "./cjs/index.js",
-  "module": "./index.js",
-  "types": "./index.d.ts",
+  "scripts": {
+    "build": " rollup -c",
+    "build-publish": "pnpm run build && node setupPackage.mjs && cd dist && npm publish",
+    "storybook": "storybook dev -p 6006",
+    "build-storybook": "storybook build"
+  },
+  "files": [
+    "dist"
+  ],
   "exports": {
     ".": {
-      "import": "./index.js",
-      "require": "./cjs/index.js",
-      "types": "./index.d.ts"
-    },
-    "./Popover": {
-      "import": "./cjs/Popover/Popover.js",
-      "require": "./cjs/cjs/Popover/Popover.js",
-      "types": "./cjs/Popover/Popover.d.ts"
-    },
-    "./Select": {
-      "import": "./cjs/Select/Select.js",
-      "require": "./cjs/cjs/Select/Select.js",
-      "types": "./cjs/Select/Select.d.ts"
-    },
-    "./Tooltip": {
-      "import": "./cjs/Tooltip/Tooltip.js",
-      "require": "./cjs/cjs/Tooltip/Tooltip.js",
-      "types": "./cjs/Tooltip/Tooltip.d.ts"
-    },
-    "./cjs": {
-      "import": "./cjs/index.js",
-      "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",
-      "types": "./index.d.ts"
+      "import": "./dist/index.js",
+      "require": "./dist/cjs/index.js",
+      "types": "./dist/index.d.ts"
     }
   },
   "keywords": [
@@ -61,5 +29,53 @@
     "ui-library",
     "tailwind",
     "storybook"
-  ]
-}
+  ],
+  "author": "",
+  "license": "MIT",
+  "type": "module",
+  "devDependencies": {
+    "@babel/core": "^7.26.10",
+    "@babel/preset-env": "^7.26.7",
+    "@babel/preset-react": "^7.26.3",
+    "@chromatic-com/storybook": "3.2.4",
+    "@rollup/plugin-babel": "^6.0.4",
+    "@rollup/plugin-commonjs": "^28.0.2",
+    "@rollup/plugin-node-resolve": "^16.0.0",
+    "@storybook/addon-essentials": "^8.5.1",
+    "@storybook/addon-interactions": "^8.5.1",
+    "@storybook/addon-onboarding": "^8.5.1",
+    "@storybook/addon-postcss": "^2.0.0",
+    "@storybook/blocks": "^8.5.1",
+    "@storybook/react": "^8.5.1",
+    "@storybook/react-vite": "^8.5.1",
+    "@storybook/test": "^8.5.1",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.2.0",
+    "@types/jest": "^29.5.14",
+    "@types/react": "^19.0.7",
+    "@types/react-dom": "^19.0.3",
+    "babel-jest": "^29.7.0",
+    "chromatic": "^11.25.1",
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
+    "postcss": "^8.5.1",
+    "prettier": "^3.4.2",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "rollup": "^4.31.0",
+    "rollup-plugin-postcss": "^4.0.2",
+    "rollup-plugin-typescript2": "^0.36.0",
+    "storybook": "^8.5.1",
+    "ts-jest": "^29.2.5",
+    "typescript": "^5.7.3"
+  },
+  "dependencies": {
+    "@testing-library/user-event": "^14.6.1",
+    "rollup-plugin-peer-deps-external": "^2.2.4",
+    "tslib": "^2.8.1"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  }
+}

package/Popover/Popover.d.ts

@@ -1,2 +0,0 @@
-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,28 +0,0 @@
-import { jsxs } from 'react/jsx-runtime';
-import { useState, useRef } from 'react';
-import usePortal from '../hooks/usePortal.js';
-
-const Popover = ({ 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 { Popover };

package/Popover/Popover.type.d.ts

@@ -1,12 +0,0 @@
-import { ReactNode } from 'react';
-import { Direction } from '../hooks';
-export interface PopoverProps {
-    children: ReactNode;
-    popover: ReactNode;
-    direction: Direction;
-    targetId?: string;
-    domNode?: Element;
-    key?: string;
-    gap?: number;
-    autoFlip?: boolean;
-}

package/Popover/index.d.ts

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

package/cjs/Popover/Popover.d.ts

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

package/cjs/Popover/Popover.js

@@ -1,30 +0,0 @@
-'use strict';
-
-var jsxRuntime = require('react/jsx-runtime');
-var react = require('react');
-var usePortal = require('../hooks/usePortal.js');
-
-const Popover = ({ 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.Popover = Popover;

package/cjs/Popover/Popover.type.d.ts

@@ -1,12 +0,0 @@
-import { ReactNode } from 'react';
-import { Direction } from '../hooks';
-export interface PopoverProps {
-    children: ReactNode;
-    popover: ReactNode;
-    direction: Direction;
-    targetId?: string;
-    domNode?: Element;
-    key?: string;
-    gap?: number;
-    autoFlip?: boolean;
-}

package/cjs/Popover/index.d.ts

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

package/version.txt

@@ -1 +0,0 @@
-0.3.7