jy-headless 0.3.14 → 0.3.16

package/README.md

@@ -18,6 +18,12 @@ React용 Headless UI 라이브러리
 
 ---
 
+## 스토리북
+
+[Storybook](https://6795bdd4b570ec0f79b87452-rmxhztnaqg.chromatic.com/?path=/docs/components-autocomplete--docs) 에서
+컴포넌트를 테스트 해 볼 수 있습니다
+___
+
 ## 제공 요소
 
 ### Components

package/dist/Autocomplete/Autocomplete.d.ts

@@ -1,5 +1,108 @@
 import React from 'react';
 import type { AutocompleteInputProps, AutocompleteOptionProps, AutocompleteOptionsProps, AutocompleteProps } from './Autocomplete.type';
+/**
+ * 범용 Autocomplete(Combobox) 컴포넌트 (Compound API)
+ *
+ * - Compound 구성: <Autocomplete> + <Autocomplete.Input /> + <Autocomplete.Options /> + <Autocomplete.Option />
+ * - a11y: combobox/listbox/option role + aria-controls/activedescendant + aria-live(결과 수 안내)
+ * - 키보드: ArrowUp/Down 이동, Enter 선택, Escape 닫기, Tab 닫기
+ * - IME(한글/일본어) 조합 입력 중에는 방향키/엔터 선택 로직을 막아 UX를 보호
+ * - Options는 portal로 렌더링되며, outside click 시 닫힘
+ *
+ * ## 모드
+ * 1) items 모드 (권장)
+ * - <Autocomplete.Options items={...} renderItem={...} />
+ * - 내부에서 filterFn으로 filtered를 만들고, Options는 filtered를 가상화로 렌더
+ *
+ * 2) children 모드 (간단 리스트)
+ * - <Autocomplete.Options> 안에 <Autocomplete.Option />을 직접 나열
+ * - 소규모 옵션에만 권장 (가상화/activeIndex 기반 aria-activedescendant는 items 모드가 더 적합)
+ *
+ * @example
+ * // 1) items 모드 (기본 / 권장)
+ * const items = [
+ *   { value: 'apple', label: 'Apple' },
+ *   { value: 'banana', label: 'Banana' },
+ *   { value: 'grape', label: 'Grape' },
+ * ];
+ *
+ * const [value, setValue] = useState<string | null>(null);
+ *
+ * <Autocomplete value={value} onChange={setValue}>
+ *   <Autocomplete.Input placeholder="과일을 검색하세요" />
+ *   <Autocomplete.Options
+ *     items={items}
+ *     renderItem={(item) => <div style={{ padding: 8 }}>{item.label}</div>}
+ *   />
+ * </Autocomplete>
+ *
+ * @example
+ * // 2) 입력값(query)까지 controlled로 관리하고 싶을 때
+ * const [value, setValue] = useState<string | null>(null);
+ * const [inputValue, setInputValue] = useState('');
+ *
+ * <Autocomplete
+ *   value={value}
+ *   onChange={setValue}
+ *   inputValue={inputValue}
+ *   onInputChange={setInputValue}
+ * >
+ *   <Autocomplete.Input placeholder="검색어 제어" />
+ *   <Autocomplete.Options
+ *     items={items}
+ *     renderItem={(item) => <div style={{ padding: 8 }}>{item.label}</div>}
+ *   />
+ * </Autocomplete>
+ *
+ * @example
+ * // 3) filterFn 커스터마이징 (prefix match)
+ * const startsWithFilter = (item, query) =>
+ *   item.label.toLowerCase().startsWith(query.trim().toLowerCase());
+ *
+ * <Autocomplete value={value} onChange={setValue} filterFn={startsWithFilter}>
+ *   <Autocomplete.Input placeholder="앞글자 매칭" />
+ *   <Autocomplete.Options
+ *     items={items}
+ *     renderItem={(item) => <div style={{ padding: 8 }}>{item.label}</div>}
+ *   />
+ * </Autocomplete>
+ *
+ * @example
+ * // 4) 가상화 옵션 조정 (많은 데이터)
+ * <Autocomplete value={value} onChange={setValue}>
+ *   <Autocomplete.Input placeholder="대량 데이터" />
+ *   <Autocomplete.Options
+ *     items={bigItems}
+ *     renderItem={(item) => <div style={{ padding: 8 }}>{item.label}</div>}
+ *     itemHeight={36}
+ *     maxVisibleItems={8}
+ *     overscan={3}
+ *   />
+ * </Autocomplete>
+ *
+ * @example
+ * // 5) disabled
+ * <Autocomplete value={value} onChange={setValue} disabled>
+ *   <Autocomplete.Input placeholder="비활성화" />
+ *   <Autocomplete.Options
+ *     items={items}
+ *     renderItem={(item) => <div style={{ padding: 8 }}>{item.label}</div>}
+ *   />
+ * </Autocomplete>
+ *
+ * @example
+ * // 6) children 모드 (소규모 리스트에만 권장)
+ * const [value, setValue] = useState<string | null>(null);
+ *
+ * <Autocomplete value={value} onChange={setValue}>
+ *   <Autocomplete.Input placeholder="직접 옵션 나열" />
+ *   <Autocomplete.Options>
+ *     <Autocomplete.Option value="seoul" label="Seoul" />
+ *     <Autocomplete.Option value="busan" label="Busan" />
+ *     <Autocomplete.Option value="jeju" label="Jeju" disabled />
+ *   </Autocomplete.Options>
+ * </Autocomplete>
+ */
 export 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;

package/dist/Autocomplete/Autocomplete.js

@@ -290,6 +290,109 @@ const Option = ({ value, label, disabled, children, ...props }) => {
             setActiveIndex(-1);
         }, ...props, children: children ?? label }));
 };
+/**
+ * 범용 Autocomplete(Combobox) 컴포넌트 (Compound API)
+ *
+ * - Compound 구성: <Autocomplete> + <Autocomplete.Input /> + <Autocomplete.Options /> + <Autocomplete.Option />
+ * - a11y: combobox/listbox/option role + aria-controls/activedescendant + aria-live(결과 수 안내)
+ * - 키보드: ArrowUp/Down 이동, Enter 선택, Escape 닫기, Tab 닫기
+ * - IME(한글/일본어) 조합 입력 중에는 방향키/엔터 선택 로직을 막아 UX를 보호
+ * - Options는 portal로 렌더링되며, outside click 시 닫힘
+ *
+ * ## 모드
+ * 1) items 모드 (권장)
+ * - <Autocomplete.Options items={...} renderItem={...} />
+ * - 내부에서 filterFn으로 filtered를 만들고, Options는 filtered를 가상화로 렌더
+ *
+ * 2) children 모드 (간단 리스트)
+ * - <Autocomplete.Options> 안에 <Autocomplete.Option />을 직접 나열
+ * - 소규모 옵션에만 권장 (가상화/activeIndex 기반 aria-activedescendant는 items 모드가 더 적합)
+ *
+ * @example
+ * // 1) items 모드 (기본 / 권장)
+ * const items = [
+ *   { value: 'apple', label: 'Apple' },
+ *   { value: 'banana', label: 'Banana' },
+ *   { value: 'grape', label: 'Grape' },
+ * ];
+ *
+ * const [value, setValue] = useState<string | null>(null);
+ *
+ * <Autocomplete value={value} onChange={setValue}>
+ *   <Autocomplete.Input placeholder="과일을 검색하세요" />
+ *   <Autocomplete.Options
+ *     items={items}
+ *     renderItem={(item) => <div style={{ padding: 8 }}>{item.label}</div>}
+ *   />
+ * </Autocomplete>
+ *
+ * @example
+ * // 2) 입력값(query)까지 controlled로 관리하고 싶을 때
+ * const [value, setValue] = useState<string | null>(null);
+ * const [inputValue, setInputValue] = useState('');
+ *
+ * <Autocomplete
+ *   value={value}
+ *   onChange={setValue}
+ *   inputValue={inputValue}
+ *   onInputChange={setInputValue}
+ * >
+ *   <Autocomplete.Input placeholder="검색어 제어" />
+ *   <Autocomplete.Options
+ *     items={items}
+ *     renderItem={(item) => <div style={{ padding: 8 }}>{item.label}</div>}
+ *   />
+ * </Autocomplete>
+ *
+ * @example
+ * // 3) filterFn 커스터마이징 (prefix match)
+ * const startsWithFilter = (item, query) =>
+ *   item.label.toLowerCase().startsWith(query.trim().toLowerCase());
+ *
+ * <Autocomplete value={value} onChange={setValue} filterFn={startsWithFilter}>
+ *   <Autocomplete.Input placeholder="앞글자 매칭" />
+ *   <Autocomplete.Options
+ *     items={items}
+ *     renderItem={(item) => <div style={{ padding: 8 }}>{item.label}</div>}
+ *   />
+ * </Autocomplete>
+ *
+ * @example
+ * // 4) 가상화 옵션 조정 (많은 데이터)
+ * <Autocomplete value={value} onChange={setValue}>
+ *   <Autocomplete.Input placeholder="대량 데이터" />
+ *   <Autocomplete.Options
+ *     items={bigItems}
+ *     renderItem={(item) => <div style={{ padding: 8 }}>{item.label}</div>}
+ *     itemHeight={36}
+ *     maxVisibleItems={8}
+ *     overscan={3}
+ *   />
+ * </Autocomplete>
+ *
+ * @example
+ * // 5) disabled
+ * <Autocomplete value={value} onChange={setValue} disabled>
+ *   <Autocomplete.Input placeholder="비활성화" />
+ *   <Autocomplete.Options
+ *     items={items}
+ *     renderItem={(item) => <div style={{ padding: 8 }}>{item.label}</div>}
+ *   />
+ * </Autocomplete>
+ *
+ * @example
+ * // 6) children 모드 (소규모 리스트에만 권장)
+ * const [value, setValue] = useState<string | null>(null);
+ *
+ * <Autocomplete value={value} onChange={setValue}>
+ *   <Autocomplete.Input placeholder="직접 옵션 나열" />
+ *   <Autocomplete.Options>
+ *     <Autocomplete.Option value="seoul" label="Seoul" />
+ *     <Autocomplete.Option value="busan" label="Busan" />
+ *     <Autocomplete.Option value="jeju" label="Jeju" disabled />
+ *   </Autocomplete.Options>
+ * </Autocomplete>
+ */
 const Autocomplete = Object.assign(AutocompleteContainer, {
     Input,
     Options,

package/dist/Input/NumberInput.d.ts

@@ -1,2 +1,55 @@
 import { NumberInputProps } from './NumberInput.type';
+/**
+ * 숫자 전용 Input 컴포넌트
+ *
+ * - 숫자만 입력 가능 (콤마는 내부적으로 제거 후 처리)
+ * - max: 최대값 제한 (초과 시 자동으로 max로 보정)
+ * - useThousandsSeparator: 천단위 콤마 자동 포맷팅
+ * - 실제 onChange로 넘어가는 값은:
+ *   - useThousandsSeparator=true → 콤마가 포함된 문자열
+ *   - false → 순수 숫자 문자열
+ *
+ * @example
+ * // 1) 기본 숫자 입력
+ * <NumberInput
+ *   placeholder="숫자 입력"
+ *   onChange={(e) => console.log(e.target.value)}
+ * />
+ *
+ * @example
+ * // 2) 최대값 제한
+ * <NumberInput
+ *   max={100}
+ *   placeholder="최대 100"
+ *   onChange={(e) => console.log(e.target.value)}
+ * />
+ *
+ * @example
+ * // 3) 천단위 콤마 포맷
+ * <NumberInput
+ *   useThousandsSeparator
+ *   placeholder="금액 입력"
+ *   onChange={(e) => console.log(e.target.value)} // 10000 → "10,000"
+ * />
+ *
+ * @example
+ * // 4) max + 천단위 콤마 같이 사용
+ * <NumberInput
+ *   max={1000000}
+ *   useThousandsSeparator
+ *   placeholder="최대 1,000,000"
+ *   onChange={(e) => console.log(e.target.value)}
+ * />
+ *
+ * @example
+ * // 5) React Hook Form 등과 함께 사용할 때
+ * // - 저장 시에는 콤마 제거 후 숫자로 변환하는 게 일반적
+ * <NumberInput
+ *   useThousandsSeparator
+ *   onChange={(e) => {
+ *     const numeric = Number(e.target.value.replace(/,/g, ''));
+ *     console.log(numeric);
+ *   }}
+ * />
+ */
 export declare const NumberInput: ({ max, useThousandsSeparator, onChange, ...props }: NumberInputProps) => import("react/jsx-runtime").JSX.Element;

package/dist/Input/NumberInput.js

@@ -1,6 +1,59 @@
 import { jsx } from 'react/jsx-runtime';
 import { TextInput } from './TextInput.js';
 
+/**
+ * 숫자 전용 Input 컴포넌트
+ *
+ * - 숫자만 입력 가능 (콤마는 내부적으로 제거 후 처리)
+ * - max: 최대값 제한 (초과 시 자동으로 max로 보정)
+ * - useThousandsSeparator: 천단위 콤마 자동 포맷팅
+ * - 실제 onChange로 넘어가는 값은:
+ *   - useThousandsSeparator=true → 콤마가 포함된 문자열
+ *   - false → 순수 숫자 문자열
+ *
+ * @example
+ * // 1) 기본 숫자 입력
+ * <NumberInput
+ *   placeholder="숫자 입력"
+ *   onChange={(e) => console.log(e.target.value)}
+ * />
+ *
+ * @example
+ * // 2) 최대값 제한
+ * <NumberInput
+ *   max={100}
+ *   placeholder="최대 100"
+ *   onChange={(e) => console.log(e.target.value)}
+ * />
+ *
+ * @example
+ * // 3) 천단위 콤마 포맷
+ * <NumberInput
+ *   useThousandsSeparator
+ *   placeholder="금액 입력"
+ *   onChange={(e) => console.log(e.target.value)} // 10000 → "10,000"
+ * />
+ *
+ * @example
+ * // 4) max + 천단위 콤마 같이 사용
+ * <NumberInput
+ *   max={1000000}
+ *   useThousandsSeparator
+ *   placeholder="최대 1,000,000"
+ *   onChange={(e) => console.log(e.target.value)}
+ * />
+ *
+ * @example
+ * // 5) React Hook Form 등과 함께 사용할 때
+ * // - 저장 시에는 콤마 제거 후 숫자로 변환하는 게 일반적
+ * <NumberInput
+ *   useThousandsSeparator
+ *   onChange={(e) => {
+ *     const numeric = Number(e.target.value.replace(/,/g, ''));
+ *     console.log(numeric);
+ *   }}
+ * />
+ */
 const NumberInput = ({ max, useThousandsSeparator, onChange, ...props }) => {
     const handleChange = (e) => {
         const rawValue = e.target.value.replace(/,/g, '');

package/dist/Input/TextInput.d.ts

@@ -1,3 +1,98 @@
 import React from 'react';
 import { TextInputProps } from './TextInput.type';
+/**
+ * 범용 TextInput 컴포넌트
+ *
+ * - maxLength: (조합 입력 중이 아닐 때) 최대 길이 제한
+ * - pattern: 정규식 문자열(매 입력마다 test 통과해야 반영)
+ * - disallowPattern: "허용" 정규식(현재 구현은 test가 false면 return)
+ * - validator: 값 검증 (boolean | error message string 반환 가능)
+ * - trimWhitespace: blur 시 앞뒤 공백 제거 후 onChange 호출
+ * - debounceMs / onDebouncedChange: 디바운스된 값 콜백
+ * - throttleMs / onThrottledChange: 스로틀된 값 콜백
+ *
+ * @example
+ * // 1) 기본 사용
+ * <TextInput
+ *   placeholder="이름을 입력하세요"
+ *   onChange={(e) => console.log(e.target.value)}
+ * />
+ *
+ * @example
+ * // 2) maxLength + trimWhitespace (blur 시 공백 제거)
+ * <TextInput
+ *   maxLength={20}
+ *   trimWhitespace
+ *   placeholder="최대 20자, blur 시 공백 제거"
+ *   onChange={(e) => console.log('change:', e.target.value)}
+ * />
+ *
+ * @example
+ * // 3) pattern(문자열)로 숫자만 허용
+ * // - 입력값이 정규식에 매번 매칭되어야 반영됨
+ * <TextInput
+ *   pattern="^[0-9]*$"
+ *   inputMode="numeric"
+ *   placeholder="숫자만 입력"
+ *   onChange={(e) => console.log(e.target.value)}
+ * />
+ *
+ * @example
+ * // 4) disallowPattern(정규식)로 "허용 규칙" 적용 (현재 구현 기준)
+ * // - test가 false면 반영되지 않음
+ * // - 예: 영문/숫자/언더스코어만 허용
+ * <TextInput
+ *   disallowPattern={/^[a-zA-Z0-9_]*$/}
+ *   placeholder="영문/숫자/_ 만"
+ *   onChange={(e) => console.log(e.target.value)}
+ * />
+ *
+ * @example
+ * // 5) validator + onValidate
+ * // - validator가 false면 onChange가 호출되지 않음
+ * // - 문자열 반환 시 그 문자열이 error로 넘어감
+ * <TextInput
+ *   placeholder="이메일"
+ *   validator={(v) => {
+ *     if (!v) return true; // 빈 값은 통과(원하면 false로 바꿔도 됨)
+ *     const ok = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v);
+ *     return ok || '이메일 형식이 아니에요';
+ *   }}
+ *   onValidate={(isValid, error) => {
+ *     console.log('valid:', isValid, 'error:', error);
+ *   }}
+ *   onChange={(e) => console.log(e.target.value)}
+ * />
+ *
+ * @example
+ * // 6) debounce: 입력은 즉시 반영(onChange), 서버검색/자동완성은 디바운스로 처리
+ * <TextInput
+ *   placeholder="검색어 입력"
+ *   debounceMs={300}
+ *   onDebouncedChange={(value) => {
+ *     // fetch(`/api/search?q=${encodeURIComponent(value)}`)
+ *     console.log('debounced:', value);
+ *   }}
+ *   onChange={(e) => console.log('immediate:', e.target.value)}
+ * />
+ *
+ * @example
+ * // 7) throttle: 스크롤/리사이즈처럼 자주 쏘는 이벤트에 유용한 패턴
+ * <TextInput
+ *   placeholder="입력값 로깅(최대 200ms에 1번)"
+ *   throttleMs={200}
+ *   onThrottledChange={(value) => console.log('throttled:', value)}
+ *   onChange={(e) => console.log('immediate:', e.target.value)}
+ * />
+ *
+ * @example
+ * // 8) IME(한글/일본어) 조합 이벤트 처리 예시
+ * <TextInput
+ *   placeholder="한글 입력"
+ *   maxLength={10}
+ *   onCompositionStart={() => console.log('compose start')}
+ *   onCompositionEnd={() => console.log('compose end')}
+ *   onChange={(e) => console.log(e.target.value)}
+ * />
+ */
 export declare const TextInput: React.ForwardRefExoticComponent<TextInputProps & React.RefAttributes<HTMLInputElement>>;

package/dist/Input/TextInput.js

@@ -16,6 +16,101 @@ function mergeRefs(...refs) {
         });
     };
 }
+/**
+ * 범용 TextInput 컴포넌트
+ *
+ * - maxLength: (조합 입력 중이 아닐 때) 최대 길이 제한
+ * - pattern: 정규식 문자열(매 입력마다 test 통과해야 반영)
+ * - disallowPattern: "허용" 정규식(현재 구현은 test가 false면 return)
+ * - validator: 값 검증 (boolean | error message string 반환 가능)
+ * - trimWhitespace: blur 시 앞뒤 공백 제거 후 onChange 호출
+ * - debounceMs / onDebouncedChange: 디바운스된 값 콜백
+ * - throttleMs / onThrottledChange: 스로틀된 값 콜백
+ *
+ * @example
+ * // 1) 기본 사용
+ * <TextInput
+ *   placeholder="이름을 입력하세요"
+ *   onChange={(e) => console.log(e.target.value)}
+ * />
+ *
+ * @example
+ * // 2) maxLength + trimWhitespace (blur 시 공백 제거)
+ * <TextInput
+ *   maxLength={20}
+ *   trimWhitespace
+ *   placeholder="최대 20자, blur 시 공백 제거"
+ *   onChange={(e) => console.log('change:', e.target.value)}
+ * />
+ *
+ * @example
+ * // 3) pattern(문자열)로 숫자만 허용
+ * // - 입력값이 정규식에 매번 매칭되어야 반영됨
+ * <TextInput
+ *   pattern="^[0-9]*$"
+ *   inputMode="numeric"
+ *   placeholder="숫자만 입력"
+ *   onChange={(e) => console.log(e.target.value)}
+ * />
+ *
+ * @example
+ * // 4) disallowPattern(정규식)로 "허용 규칙" 적용 (현재 구현 기준)
+ * // - test가 false면 반영되지 않음
+ * // - 예: 영문/숫자/언더스코어만 허용
+ * <TextInput
+ *   disallowPattern={/^[a-zA-Z0-9_]*$/}
+ *   placeholder="영문/숫자/_ 만"
+ *   onChange={(e) => console.log(e.target.value)}
+ * />
+ *
+ * @example
+ * // 5) validator + onValidate
+ * // - validator가 false면 onChange가 호출되지 않음
+ * // - 문자열 반환 시 그 문자열이 error로 넘어감
+ * <TextInput
+ *   placeholder="이메일"
+ *   validator={(v) => {
+ *     if (!v) return true; // 빈 값은 통과(원하면 false로 바꿔도 됨)
+ *     const ok = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v);
+ *     return ok || '이메일 형식이 아니에요';
+ *   }}
+ *   onValidate={(isValid, error) => {
+ *     console.log('valid:', isValid, 'error:', error);
+ *   }}
+ *   onChange={(e) => console.log(e.target.value)}
+ * />
+ *
+ * @example
+ * // 6) debounce: 입력은 즉시 반영(onChange), 서버검색/자동완성은 디바운스로 처리
+ * <TextInput
+ *   placeholder="검색어 입력"
+ *   debounceMs={300}
+ *   onDebouncedChange={(value) => {
+ *     // fetch(`/api/search?q=${encodeURIComponent(value)}`)
+ *     console.log('debounced:', value);
+ *   }}
+ *   onChange={(e) => console.log('immediate:', e.target.value)}
+ * />
+ *
+ * @example
+ * // 7) throttle: 스크롤/리사이즈처럼 자주 쏘는 이벤트에 유용한 패턴
+ * <TextInput
+ *   placeholder="입력값 로깅(최대 200ms에 1번)"
+ *   throttleMs={200}
+ *   onThrottledChange={(value) => console.log('throttled:', value)}
+ *   onChange={(e) => console.log('immediate:', e.target.value)}
+ * />
+ *
+ * @example
+ * // 8) IME(한글/일본어) 조합 이벤트 처리 예시
+ * <TextInput
+ *   placeholder="한글 입력"
+ *   maxLength={10}
+ *   onCompositionStart={() => console.log('compose start')}
+ *   onCompositionEnd={() => console.log('compose end')}
+ *   onChange={(e) => console.log(e.target.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);

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

@@ -1,5 +1,108 @@
 import React from 'react';
 import type { AutocompleteInputProps, AutocompleteOptionProps, AutocompleteOptionsProps, AutocompleteProps } from './Autocomplete.type';
+/**
+ * 범용 Autocomplete(Combobox) 컴포넌트 (Compound API)
+ *
+ * - Compound 구성: <Autocomplete> + <Autocomplete.Input /> + <Autocomplete.Options /> + <Autocomplete.Option />
+ * - a11y: combobox/listbox/option role + aria-controls/activedescendant + aria-live(결과 수 안내)
+ * - 키보드: ArrowUp/Down 이동, Enter 선택, Escape 닫기, Tab 닫기
+ * - IME(한글/일본어) 조합 입력 중에는 방향키/엔터 선택 로직을 막아 UX를 보호
+ * - Options는 portal로 렌더링되며, outside click 시 닫힘
+ *
+ * ## 모드
+ * 1) items 모드 (권장)
+ * - <Autocomplete.Options items={...} renderItem={...} />
+ * - 내부에서 filterFn으로 filtered를 만들고, Options는 filtered를 가상화로 렌더
+ *
+ * 2) children 모드 (간단 리스트)
+ * - <Autocomplete.Options> 안에 <Autocomplete.Option />을 직접 나열
+ * - 소규모 옵션에만 권장 (가상화/activeIndex 기반 aria-activedescendant는 items 모드가 더 적합)
+ *
+ * @example
+ * // 1) items 모드 (기본 / 권장)
+ * const items = [
+ *   { value: 'apple', label: 'Apple' },
+ *   { value: 'banana', label: 'Banana' },
+ *   { value: 'grape', label: 'Grape' },
+ * ];
+ *
+ * const [value, setValue] = useState<string | null>(null);
+ *
+ * <Autocomplete value={value} onChange={setValue}>
+ *   <Autocomplete.Input placeholder="과일을 검색하세요" />
+ *   <Autocomplete.Options
+ *     items={items}
+ *     renderItem={(item) => <div style={{ padding: 8 }}>{item.label}</div>}
+ *   />
+ * </Autocomplete>
+ *
+ * @example
+ * // 2) 입력값(query)까지 controlled로 관리하고 싶을 때
+ * const [value, setValue] = useState<string | null>(null);
+ * const [inputValue, setInputValue] = useState('');
+ *
+ * <Autocomplete
+ *   value={value}
+ *   onChange={setValue}
+ *   inputValue={inputValue}
+ *   onInputChange={setInputValue}
+ * >
+ *   <Autocomplete.Input placeholder="검색어 제어" />
+ *   <Autocomplete.Options
+ *     items={items}
+ *     renderItem={(item) => <div style={{ padding: 8 }}>{item.label}</div>}
+ *   />
+ * </Autocomplete>
+ *
+ * @example
+ * // 3) filterFn 커스터마이징 (prefix match)
+ * const startsWithFilter = (item, query) =>
+ *   item.label.toLowerCase().startsWith(query.trim().toLowerCase());
+ *
+ * <Autocomplete value={value} onChange={setValue} filterFn={startsWithFilter}>
+ *   <Autocomplete.Input placeholder="앞글자 매칭" />
+ *   <Autocomplete.Options
+ *     items={items}
+ *     renderItem={(item) => <div style={{ padding: 8 }}>{item.label}</div>}
+ *   />
+ * </Autocomplete>
+ *
+ * @example
+ * // 4) 가상화 옵션 조정 (많은 데이터)
+ * <Autocomplete value={value} onChange={setValue}>
+ *   <Autocomplete.Input placeholder="대량 데이터" />
+ *   <Autocomplete.Options
+ *     items={bigItems}
+ *     renderItem={(item) => <div style={{ padding: 8 }}>{item.label}</div>}
+ *     itemHeight={36}
+ *     maxVisibleItems={8}
+ *     overscan={3}
+ *   />
+ * </Autocomplete>
+ *
+ * @example
+ * // 5) disabled
+ * <Autocomplete value={value} onChange={setValue} disabled>
+ *   <Autocomplete.Input placeholder="비활성화" />
+ *   <Autocomplete.Options
+ *     items={items}
+ *     renderItem={(item) => <div style={{ padding: 8 }}>{item.label}</div>}
+ *   />
+ * </Autocomplete>
+ *
+ * @example
+ * // 6) children 모드 (소규모 리스트에만 권장)
+ * const [value, setValue] = useState<string | null>(null);
+ *
+ * <Autocomplete value={value} onChange={setValue}>
+ *   <Autocomplete.Input placeholder="직접 옵션 나열" />
+ *   <Autocomplete.Options>
+ *     <Autocomplete.Option value="seoul" label="Seoul" />
+ *     <Autocomplete.Option value="busan" label="Busan" />
+ *     <Autocomplete.Option value="jeju" label="Jeju" disabled />
+ *   </Autocomplete.Options>
+ * </Autocomplete>
+ */
 export 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;

package/dist/cjs/Autocomplete/Autocomplete.js

@@ -292,6 +292,109 @@ const Option = ({ value, label, disabled, children, ...props }) => {
             setActiveIndex(-1);
         }, ...props, children: children ?? label }));
 };
+/**
+ * 범용 Autocomplete(Combobox) 컴포넌트 (Compound API)
+ *
+ * - Compound 구성: <Autocomplete> + <Autocomplete.Input /> + <Autocomplete.Options /> + <Autocomplete.Option />
+ * - a11y: combobox/listbox/option role + aria-controls/activedescendant + aria-live(결과 수 안내)
+ * - 키보드: ArrowUp/Down 이동, Enter 선택, Escape 닫기, Tab 닫기
+ * - IME(한글/일본어) 조합 입력 중에는 방향키/엔터 선택 로직을 막아 UX를 보호
+ * - Options는 portal로 렌더링되며, outside click 시 닫힘
+ *
+ * ## 모드
+ * 1) items 모드 (권장)
+ * - <Autocomplete.Options items={...} renderItem={...} />
+ * - 내부에서 filterFn으로 filtered를 만들고, Options는 filtered를 가상화로 렌더
+ *
+ * 2) children 모드 (간단 리스트)
+ * - <Autocomplete.Options> 안에 <Autocomplete.Option />을 직접 나열
+ * - 소규모 옵션에만 권장 (가상화/activeIndex 기반 aria-activedescendant는 items 모드가 더 적합)
+ *
+ * @example
+ * // 1) items 모드 (기본 / 권장)
+ * const items = [
+ *   { value: 'apple', label: 'Apple' },
+ *   { value: 'banana', label: 'Banana' },
+ *   { value: 'grape', label: 'Grape' },
+ * ];
+ *
+ * const [value, setValue] = useState<string | null>(null);
+ *
+ * <Autocomplete value={value} onChange={setValue}>
+ *   <Autocomplete.Input placeholder="과일을 검색하세요" />
+ *   <Autocomplete.Options
+ *     items={items}
+ *     renderItem={(item) => <div style={{ padding: 8 }}>{item.label}</div>}
+ *   />
+ * </Autocomplete>
+ *
+ * @example
+ * // 2) 입력값(query)까지 controlled로 관리하고 싶을 때
+ * const [value, setValue] = useState<string | null>(null);
+ * const [inputValue, setInputValue] = useState('');
+ *
+ * <Autocomplete
+ *   value={value}
+ *   onChange={setValue}
+ *   inputValue={inputValue}
+ *   onInputChange={setInputValue}
+ * >
+ *   <Autocomplete.Input placeholder="검색어 제어" />
+ *   <Autocomplete.Options
+ *     items={items}
+ *     renderItem={(item) => <div style={{ padding: 8 }}>{item.label}</div>}
+ *   />
+ * </Autocomplete>
+ *
+ * @example
+ * // 3) filterFn 커스터마이징 (prefix match)
+ * const startsWithFilter = (item, query) =>
+ *   item.label.toLowerCase().startsWith(query.trim().toLowerCase());
+ *
+ * <Autocomplete value={value} onChange={setValue} filterFn={startsWithFilter}>
+ *   <Autocomplete.Input placeholder="앞글자 매칭" />
+ *   <Autocomplete.Options
+ *     items={items}
+ *     renderItem={(item) => <div style={{ padding: 8 }}>{item.label}</div>}
+ *   />
+ * </Autocomplete>
+ *
+ * @example
+ * // 4) 가상화 옵션 조정 (많은 데이터)
+ * <Autocomplete value={value} onChange={setValue}>
+ *   <Autocomplete.Input placeholder="대량 데이터" />
+ *   <Autocomplete.Options
+ *     items={bigItems}
+ *     renderItem={(item) => <div style={{ padding: 8 }}>{item.label}</div>}
+ *     itemHeight={36}
+ *     maxVisibleItems={8}
+ *     overscan={3}
+ *   />
+ * </Autocomplete>
+ *
+ * @example
+ * // 5) disabled
+ * <Autocomplete value={value} onChange={setValue} disabled>
+ *   <Autocomplete.Input placeholder="비활성화" />
+ *   <Autocomplete.Options
+ *     items={items}
+ *     renderItem={(item) => <div style={{ padding: 8 }}>{item.label}</div>}
+ *   />
+ * </Autocomplete>
+ *
+ * @example
+ * // 6) children 모드 (소규모 리스트에만 권장)
+ * const [value, setValue] = useState<string | null>(null);
+ *
+ * <Autocomplete value={value} onChange={setValue}>
+ *   <Autocomplete.Input placeholder="직접 옵션 나열" />
+ *   <Autocomplete.Options>
+ *     <Autocomplete.Option value="seoul" label="Seoul" />
+ *     <Autocomplete.Option value="busan" label="Busan" />
+ *     <Autocomplete.Option value="jeju" label="Jeju" disabled />
+ *   </Autocomplete.Options>
+ * </Autocomplete>
+ */
 const Autocomplete = Object.assign(AutocompleteContainer, {
     Input,
     Options,

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

@@ -1,2 +1,55 @@
 import { NumberInputProps } from './NumberInput.type';
+/**
+ * 숫자 전용 Input 컴포넌트
+ *
+ * - 숫자만 입력 가능 (콤마는 내부적으로 제거 후 처리)
+ * - max: 최대값 제한 (초과 시 자동으로 max로 보정)
+ * - useThousandsSeparator: 천단위 콤마 자동 포맷팅
+ * - 실제 onChange로 넘어가는 값은:
+ *   - useThousandsSeparator=true → 콤마가 포함된 문자열
+ *   - false → 순수 숫자 문자열
+ *
+ * @example
+ * // 1) 기본 숫자 입력
+ * <NumberInput
+ *   placeholder="숫자 입력"
+ *   onChange={(e) => console.log(e.target.value)}
+ * />
+ *
+ * @example
+ * // 2) 최대값 제한
+ * <NumberInput
+ *   max={100}
+ *   placeholder="최대 100"
+ *   onChange={(e) => console.log(e.target.value)}
+ * />
+ *
+ * @example
+ * // 3) 천단위 콤마 포맷
+ * <NumberInput
+ *   useThousandsSeparator
+ *   placeholder="금액 입력"
+ *   onChange={(e) => console.log(e.target.value)} // 10000 → "10,000"
+ * />
+ *
+ * @example
+ * // 4) max + 천단위 콤마 같이 사용
+ * <NumberInput
+ *   max={1000000}
+ *   useThousandsSeparator
+ *   placeholder="최대 1,000,000"
+ *   onChange={(e) => console.log(e.target.value)}
+ * />
+ *
+ * @example
+ * // 5) React Hook Form 등과 함께 사용할 때
+ * // - 저장 시에는 콤마 제거 후 숫자로 변환하는 게 일반적
+ * <NumberInput
+ *   useThousandsSeparator
+ *   onChange={(e) => {
+ *     const numeric = Number(e.target.value.replace(/,/g, ''));
+ *     console.log(numeric);
+ *   }}
+ * />
+ */
 export declare const NumberInput: ({ max, useThousandsSeparator, onChange, ...props }: NumberInputProps) => import("react/jsx-runtime").JSX.Element;

package/dist/cjs/Input/NumberInput.js

@@ -3,6 +3,59 @@
 var jsxRuntime = require('react/jsx-runtime');
 var TextInput = require('./TextInput.js');
 
+/**
+ * 숫자 전용 Input 컴포넌트
+ *
+ * - 숫자만 입력 가능 (콤마는 내부적으로 제거 후 처리)
+ * - max: 최대값 제한 (초과 시 자동으로 max로 보정)
+ * - useThousandsSeparator: 천단위 콤마 자동 포맷팅
+ * - 실제 onChange로 넘어가는 값은:
+ *   - useThousandsSeparator=true → 콤마가 포함된 문자열
+ *   - false → 순수 숫자 문자열
+ *
+ * @example
+ * // 1) 기본 숫자 입력
+ * <NumberInput
+ *   placeholder="숫자 입력"
+ *   onChange={(e) => console.log(e.target.value)}
+ * />
+ *
+ * @example
+ * // 2) 최대값 제한
+ * <NumberInput
+ *   max={100}
+ *   placeholder="최대 100"
+ *   onChange={(e) => console.log(e.target.value)}
+ * />
+ *
+ * @example
+ * // 3) 천단위 콤마 포맷
+ * <NumberInput
+ *   useThousandsSeparator
+ *   placeholder="금액 입력"
+ *   onChange={(e) => console.log(e.target.value)} // 10000 → "10,000"
+ * />
+ *
+ * @example
+ * // 4) max + 천단위 콤마 같이 사용
+ * <NumberInput
+ *   max={1000000}
+ *   useThousandsSeparator
+ *   placeholder="최대 1,000,000"
+ *   onChange={(e) => console.log(e.target.value)}
+ * />
+ *
+ * @example
+ * // 5) React Hook Form 등과 함께 사용할 때
+ * // - 저장 시에는 콤마 제거 후 숫자로 변환하는 게 일반적
+ * <NumberInput
+ *   useThousandsSeparator
+ *   onChange={(e) => {
+ *     const numeric = Number(e.target.value.replace(/,/g, ''));
+ *     console.log(numeric);
+ *   }}
+ * />
+ */
 const NumberInput = ({ max, useThousandsSeparator, onChange, ...props }) => {
     const handleChange = (e) => {
         const rawValue = e.target.value.replace(/,/g, '');

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

@@ -1,3 +1,98 @@
 import React from 'react';
 import { TextInputProps } from './TextInput.type';
+/**
+ * 범용 TextInput 컴포넌트
+ *
+ * - maxLength: (조합 입력 중이 아닐 때) 최대 길이 제한
+ * - pattern: 정규식 문자열(매 입력마다 test 통과해야 반영)
+ * - disallowPattern: "허용" 정규식(현재 구현은 test가 false면 return)
+ * - validator: 값 검증 (boolean | error message string 반환 가능)
+ * - trimWhitespace: blur 시 앞뒤 공백 제거 후 onChange 호출
+ * - debounceMs / onDebouncedChange: 디바운스된 값 콜백
+ * - throttleMs / onThrottledChange: 스로틀된 값 콜백
+ *
+ * @example
+ * // 1) 기본 사용
+ * <TextInput
+ *   placeholder="이름을 입력하세요"
+ *   onChange={(e) => console.log(e.target.value)}
+ * />
+ *
+ * @example
+ * // 2) maxLength + trimWhitespace (blur 시 공백 제거)
+ * <TextInput
+ *   maxLength={20}
+ *   trimWhitespace
+ *   placeholder="최대 20자, blur 시 공백 제거"
+ *   onChange={(e) => console.log('change:', e.target.value)}
+ * />
+ *
+ * @example
+ * // 3) pattern(문자열)로 숫자만 허용
+ * // - 입력값이 정규식에 매번 매칭되어야 반영됨
+ * <TextInput
+ *   pattern="^[0-9]*$"
+ *   inputMode="numeric"
+ *   placeholder="숫자만 입력"
+ *   onChange={(e) => console.log(e.target.value)}
+ * />
+ *
+ * @example
+ * // 4) disallowPattern(정규식)로 "허용 규칙" 적용 (현재 구현 기준)
+ * // - test가 false면 반영되지 않음
+ * // - 예: 영문/숫자/언더스코어만 허용
+ * <TextInput
+ *   disallowPattern={/^[a-zA-Z0-9_]*$/}
+ *   placeholder="영문/숫자/_ 만"
+ *   onChange={(e) => console.log(e.target.value)}
+ * />
+ *
+ * @example
+ * // 5) validator + onValidate
+ * // - validator가 false면 onChange가 호출되지 않음
+ * // - 문자열 반환 시 그 문자열이 error로 넘어감
+ * <TextInput
+ *   placeholder="이메일"
+ *   validator={(v) => {
+ *     if (!v) return true; // 빈 값은 통과(원하면 false로 바꿔도 됨)
+ *     const ok = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v);
+ *     return ok || '이메일 형식이 아니에요';
+ *   }}
+ *   onValidate={(isValid, error) => {
+ *     console.log('valid:', isValid, 'error:', error);
+ *   }}
+ *   onChange={(e) => console.log(e.target.value)}
+ * />
+ *
+ * @example
+ * // 6) debounce: 입력은 즉시 반영(onChange), 서버검색/자동완성은 디바운스로 처리
+ * <TextInput
+ *   placeholder="검색어 입력"
+ *   debounceMs={300}
+ *   onDebouncedChange={(value) => {
+ *     // fetch(`/api/search?q=${encodeURIComponent(value)}`)
+ *     console.log('debounced:', value);
+ *   }}
+ *   onChange={(e) => console.log('immediate:', e.target.value)}
+ * />
+ *
+ * @example
+ * // 7) throttle: 스크롤/리사이즈처럼 자주 쏘는 이벤트에 유용한 패턴
+ * <TextInput
+ *   placeholder="입력값 로깅(최대 200ms에 1번)"
+ *   throttleMs={200}
+ *   onThrottledChange={(value) => console.log('throttled:', value)}
+ *   onChange={(e) => console.log('immediate:', e.target.value)}
+ * />
+ *
+ * @example
+ * // 8) IME(한글/일본어) 조합 이벤트 처리 예시
+ * <TextInput
+ *   placeholder="한글 입력"
+ *   maxLength={10}
+ *   onCompositionStart={() => console.log('compose start')}
+ *   onCompositionEnd={() => console.log('compose end')}
+ *   onChange={(e) => console.log(e.target.value)}
+ * />
+ */
 export declare const TextInput: React.ForwardRefExoticComponent<TextInputProps & React.RefAttributes<HTMLInputElement>>;

package/dist/cjs/Input/TextInput.js

@@ -18,6 +18,101 @@ function mergeRefs(...refs) {
         });
     };
 }
+/**
+ * 범용 TextInput 컴포넌트
+ *
+ * - maxLength: (조합 입력 중이 아닐 때) 최대 길이 제한
+ * - pattern: 정규식 문자열(매 입력마다 test 통과해야 반영)
+ * - disallowPattern: "허용" 정규식(현재 구현은 test가 false면 return)
+ * - validator: 값 검증 (boolean | error message string 반환 가능)
+ * - trimWhitespace: blur 시 앞뒤 공백 제거 후 onChange 호출
+ * - debounceMs / onDebouncedChange: 디바운스된 값 콜백
+ * - throttleMs / onThrottledChange: 스로틀된 값 콜백
+ *
+ * @example
+ * // 1) 기본 사용
+ * <TextInput
+ *   placeholder="이름을 입력하세요"
+ *   onChange={(e) => console.log(e.target.value)}
+ * />
+ *
+ * @example
+ * // 2) maxLength + trimWhitespace (blur 시 공백 제거)
+ * <TextInput
+ *   maxLength={20}
+ *   trimWhitespace
+ *   placeholder="최대 20자, blur 시 공백 제거"
+ *   onChange={(e) => console.log('change:', e.target.value)}
+ * />
+ *
+ * @example
+ * // 3) pattern(문자열)로 숫자만 허용
+ * // - 입력값이 정규식에 매번 매칭되어야 반영됨
+ * <TextInput
+ *   pattern="^[0-9]*$"
+ *   inputMode="numeric"
+ *   placeholder="숫자만 입력"
+ *   onChange={(e) => console.log(e.target.value)}
+ * />
+ *
+ * @example
+ * // 4) disallowPattern(정규식)로 "허용 규칙" 적용 (현재 구현 기준)
+ * // - test가 false면 반영되지 않음
+ * // - 예: 영문/숫자/언더스코어만 허용
+ * <TextInput
+ *   disallowPattern={/^[a-zA-Z0-9_]*$/}
+ *   placeholder="영문/숫자/_ 만"
+ *   onChange={(e) => console.log(e.target.value)}
+ * />
+ *
+ * @example
+ * // 5) validator + onValidate
+ * // - validator가 false면 onChange가 호출되지 않음
+ * // - 문자열 반환 시 그 문자열이 error로 넘어감
+ * <TextInput
+ *   placeholder="이메일"
+ *   validator={(v) => {
+ *     if (!v) return true; // 빈 값은 통과(원하면 false로 바꿔도 됨)
+ *     const ok = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v);
+ *     return ok || '이메일 형식이 아니에요';
+ *   }}
+ *   onValidate={(isValid, error) => {
+ *     console.log('valid:', isValid, 'error:', error);
+ *   }}
+ *   onChange={(e) => console.log(e.target.value)}
+ * />
+ *
+ * @example
+ * // 6) debounce: 입력은 즉시 반영(onChange), 서버검색/자동완성은 디바운스로 처리
+ * <TextInput
+ *   placeholder="검색어 입력"
+ *   debounceMs={300}
+ *   onDebouncedChange={(value) => {
+ *     // fetch(`/api/search?q=${encodeURIComponent(value)}`)
+ *     console.log('debounced:', value);
+ *   }}
+ *   onChange={(e) => console.log('immediate:', e.target.value)}
+ * />
+ *
+ * @example
+ * // 7) throttle: 스크롤/리사이즈처럼 자주 쏘는 이벤트에 유용한 패턴
+ * <TextInput
+ *   placeholder="입력값 로깅(최대 200ms에 1번)"
+ *   throttleMs={200}
+ *   onThrottledChange={(value) => console.log('throttled:', value)}
+ *   onChange={(e) => console.log('immediate:', e.target.value)}
+ * />
+ *
+ * @example
+ * // 8) IME(한글/일본어) 조합 이벤트 처리 예시
+ * <TextInput
+ *   placeholder="한글 입력"
+ *   maxLength={10}
+ *   onCompositionStart={() => console.log('compose start')}
+ *   onCompositionEnd={() => console.log('compose end')}
+ *   onChange={(e) => console.log(e.target.value)}
+ * />
+ */
 const TextInput = react.forwardRef(({ maxLength, onChange, pattern, onValidate, validator, onCompositionStart, onCompositionEnd, disallowPattern, trimWhitespace, debounceMs, throttleMs, onDebouncedChange, onThrottledChange, onBlur, ...props }, ref) => {
     const [isComposing, setIsComposing] = react.useState(false);
     const innerRef = react.useRef(null);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jy-headless",
-  "version": "0.3.14",
+  "version": "0.3.16",
   "description": "A lightweight and customizable headless UI library for React components",
   "main": "dist/index.js",
   "module": "dist/index.js",