jy-headless 0.3.6 → 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/Input/index.d.ts

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

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

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

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;