@ihabdevteam/core 0.231.0 → 0.233.0

package/dist/ihabdevteam-core.d.ts

@@ -1626,7 +1626,7 @@ export declare function copyText(text: string): Promise<boolean>;
  *
  * 값은 손으로 적고 `test/coreVersion.test.ts` 가 package.json 과 어긋나면 운다.
  */
-export declare const CORE_VERSION = "0.231.0";
+export declare const CORE_VERSION = "0.233.0";
 
 /** @public */
 declare const coreDefault: Record<string, unknown>;
@@ -7630,11 +7630,34 @@ export declare interface TextFieldProps {
      * 자동완성 후보 목록 — 지정하면 콤보박스(입력 중 후보 드롭다운 + 키보드 네비게이션)로 동작한다.
      * 필터링은 현재 값 기준으로 동작하므로 controlled(value+onChange) 사용을 전제로 한다.
      */
-    suggestions?: string[];
+    /** 자동완성 후보. 글자 묶음, 또는 `{ id, label, hint? }` 줄 묶음(말귀 요청 ㊻). */
+    suggestions?: (string | TextFieldSuggestion)[];
+    /** 거르는 법. `false` 면 **안 거른다**(부르는 쪽이 이미 걸러 준 것). 기본은 `label` 에
+     *  글자가 들어 있나. 초성 찾기처럼 셈이 다른 자리에서 바꾼다. */
+    filterSuggestions?: false | ((suggestions: (string | TextFieldSuggestion)[], value: string) => (string | TextFieldSuggestion)[]);
+    /** 주면 **고를 때 칸에 값을 안 넣고** 고른 줄을 그대로 준다 — '값 채우기' 가 아니라
+     *  '어디로 가기' 인 자리에 쓴다. */
+    onSelectSuggestion?: (item: string | TextFieldSuggestion) => void;
+    /** 목록이 뜨면 첫 줄을 바로 짚는다. 기본 거짓 — `useComboboxSuggestions` 의 같은 이름 참고. */
+    autoActiveFirst?: boolean;
     /** 포커스 시 입력이 비어 있어도 전체 후보 목록을 표시 (suggestions와 함께 사용) */
     openOnFocus?: boolean;
 }
 
+/**
+ * 후보 한 줄 — 글자 하나로는 못 담는 자리(말귀 요청 ㊻, 2026-10-01).
+ *
+ * `label` 이 줄에 적히고 **거르기의 기본 대상**이며, `hint` 는 그 오른쪽에 흐리게 서는
+ * 갈래 글자(`숙제` · `나의 단어표` 같은 것)다. `id` 는 고른 뒤 부르는 쪽이 무엇을 골랐는지
+ * 알아보는 열쇠 — 이름이 같은 두 줄을 가릴 수 있어야 한다.
+ * @public
+ */
+export declare interface TextFieldSuggestion {
+    id: string;
+    label: string;
+    hint?: string;
+}
+
 /**
  * 테마 유틸리티
  * - 'light' | 'dark' | 'auto'
@@ -9145,21 +9168,39 @@ export declare interface UseCalendarMonthResult {
  * `handleCompositionEnd` 를 걸어야 한다(TextField 는 건다). 걸지 않으면 지금처럼 매 값마다 다시 거른다.
  * @public
  */
-export declare function useComboboxSuggestions({ value, onChange, suggestions, openOnFocus, }: {
+export declare function useComboboxSuggestions<T extends string | TextFieldSuggestion = string>({ value, onChange, suggestions, openOnFocus, filterSuggestions, onSelectSuggestion, autoActiveFirst, }: {
     value: string;
     onChange?: (value: string) => void;
-    suggestions: string[];
+    /** 글자 묶음, 또는 `{ id, label, hint? }` 줄 묶음 */
+    suggestions: T[];
     openOnFocus?: boolean;
+    /** 거르는 법을 바꾼다. `false` 면 **안 거른다** — 부르는 쪽이 이미 걸러 준 것으로 본다.
+     *  기본은 `label` 에 글자가 들어 있나(대소문자 무시)다. 초성 찾기처럼 셈이 다른 자리에서
+     *  쓴다(`matchesChoseongSearch` 는 이 꾸러미의 `utils` 에 있다). */
+    filterSuggestions?: false | ((suggestions: T[], value: string) => T[]);
+    /** 주면 **고를 때 칸에 값을 안 넣는다** — 고른 줄을 그대로 받는다. 고르는 것이 '값 채우기'
+     *  가 아니라 '어디로 가기' 인 자리(화면 찾기 등)에 쓴다. */
+    onSelectSuggestion?: (item: T) => void;
+    /** 목록이 뜨면 **첫 줄을 바로 짚는다**(ARIA 의 automatic selection).
+     *
+     *  기본은 거짓 — 아무것도 안 짚은 채 열리고, 그 상태의 Enter 는 제안을 안 고른다
+     *  (친 글자를 그대로 쓰겠다는 뜻이다). 자유롭게 치는 칸에서는 그쪽이 맞다.
+     *  **고르는 것이 '어디로 가기' 인 칸에서는 참이 맞다** — 치자마자 Enter 로 첫 줄에 가고,
+     *  `aria-expanded` 가 참인데 짚은 줄이 없어 낭독기에 "목록이 떴다" 만 가고 **뭐가 떴는지는
+     *  안 가는** 것도 함께 풀린다(말귀가 그래서 손수 0 으로 시작하게 두고 있었다).
+     *  `onSelectSuggestion` 과 **묶지 않았다** — 고르는 것이 가기인데도 친 글자를 그대로
+     *  쓰고 싶은 칸이 있다(검색어를 그대로 보내는 자리). 서로 다른 결정이다. */
+    autoActiveFirst?: boolean;
 }): {
     listId: string;
     open: boolean;
     activeIdx: number;
-    filtered: string[];
+    filtered: T[];
     handleFocus: () => void;
     handleBlur: () => void;
     handleInput: () => void;
     handleKeyDown: (e: KeyboardEvent_2<HTMLInputElement | HTMLTextAreaElement>) => void;
-    handleSelect: (item: string) => void;
+    handleSelect: (item: T) => void;
     /** 입력칸의 onCompositionStart 에 건다 — 조합 중에는 걸리는 후보가 0 건이 되어도 직전 목록을 둔다 */
     handleCompositionStart: () => void;
     /** 입력칸의 onCompositionEnd 에 건다 — 조합이 끝나면 목록을 다시 계산한다 */

package/dist/packages/core/src/components/BulkBar.js

@@ -96,5 +96,9 @@ export default function BulkBar({ count, actions, onClear, clearLabel: clearLabe
            단추가 Tab 순서와 낭독기에 남아, 보이지 않는 '선택 해제'·'삭제' 에 포커스가 갔다.
            inert 로 포커스·낭독기에서 함께 뺀다(보이는 모양은 CSS 그대로). aria-hidden 은
            inert 를 모르는 오래된 브라우저를 위한 덧댐이다. */
-        inert: !show || undefined, "aria-hidden": show ? undefined : true, children: [_jsx("span", { ref: contentRef, className: "bulk-bar__count body-2", role: "status", children: content ?? _jsx("b", { children: t('common.selectedCount', { count }) }) }), max !== undefined && (_jsx(Badge, { size: "small", fill: "soft", variant: "main", label: `${count} / ${max}` })), _jsxs("div", { className: `bulk-bar__actions${stacked ? ' bulk-bar__actions--stacked' : ''}`, children: [_jsx(Button, { htmlType: "button", size: 40, label: clearLabel, onClick: onClear }), actions.map((a, i) => (_jsx(Button, { htmlType: "button", size: 40, variant: a.variant ?? 'default', icon: a.icon, label: a.label, onClick: a.onClick }, i)))] })] }));
+        inert: !show || undefined, "aria-hidden": show ? undefined : true, children: [_jsx("span", { ref: contentRef, className: "bulk-bar__count body-2", role: "status", children: content ?? _jsx("b", { children: t('common.selectedCount', { count }) }) }), max !== undefined && (
+            /* 보이는 것은 `3 / 20` 이지만 낭독기로는 **맨 숫자 둘**이라 뜻이 안 선다.
+               위 `role="status"` 가 고른 수는 말하는데 **천장(max)은 여기에만 있다**
+               (말귀 요청 ㊼ 를 받고 코어 안을 같은 눈으로 훑다가 나왔다). */
+            _jsx(Badge, { size: "small", fill: "soft", variant: "main", label: `${count} / ${max}`, "aria-label": t('common.selectedOfMax', { count, max, defaultValue: `최대 ${max}개 중 ${count}개` }) })), _jsxs("div", { className: `bulk-bar__actions${stacked ? ' bulk-bar__actions--stacked' : ''}`, children: [_jsx(Button, { htmlType: "button", size: 40, label: clearLabel, onClick: onClear }), actions.map((a, i) => (_jsx(Button, { htmlType: "button", size: 40, variant: a.variant ?? 'default', icon: a.icon, label: a.label, onClick: a.onClick }, i)))] })] }));
 }

package/dist/packages/core/src/components/TextField.css

@@ -236,6 +236,9 @@
   padding: 8px 12px;
   cursor: pointer;
   color: var(--color-darkGray);
+  /* 이름과 갈래(`hint`)가 한 줄에 선다 — 글자 하나만 주는 쪽에서는 자식이 하나라 그대로다 */
+  display: flex;
+  align-items: center;
 }
 .text-field__suggestion.is-active,
 .text-field__suggestion:hover {
@@ -288,3 +291,34 @@
   align-self: flex-end;
   margin-bottom: var(--spacing-s);
 }
+
+/* 후보 줄 — 이름과 갈래(`hint`)가 한 줄에 선다(말귀 요청 ㊻, 2026-10-01).
+   갈래는 오른쪽 끝에 흐리게. 이름이 길면 이름이 먼저 줄고 갈래는 안 줄인다 —
+   `숙제` 와 `나의 단어표` 를 가리는 것이 이 글자가 선 까닭이라 잘리면 뜻이 없다. */
+.text-field__suggestion-label {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.text-field__suggestion-hint {
+  color: var(--color-lightGray);
+  flex-shrink: 0;
+  margin-left: 8px;
+  white-space: nowrap;
+}
+
+/* **들리기만 하는 칸** — 고를 것이 없다는 말이 여기로 간다.
+   늘 서 있고 글만 드나든다(사는 영역을 세웠다 치웠다 하면 낭독기가 첫 글을 놓친다). */
+.text-field__status {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  margin: -1px;
+  padding: 0;
+  overflow: hidden;
+  clip: rect(0 0 0 0);
+  white-space: nowrap;
+  border: 0;
+}

package/dist/packages/core/src/components/TextField.d.ts

@@ -1,4 +1,5 @@
 import { type Ref, type FocusEvent, type KeyboardEvent } from 'react';
+import { type TextFieldSuggestion } from './useComboboxSuggestions';
 import './TextField.css';
 /** @public */
 export interface TextFieldProps {
@@ -99,7 +100,16 @@ export interface TextFieldProps {
      * 자동완성 후보 목록 — 지정하면 콤보박스(입력 중 후보 드롭다운 + 키보드 네비게이션)로 동작한다.
      * 필터링은 현재 값 기준으로 동작하므로 controlled(value+onChange) 사용을 전제로 한다.
      */
-    suggestions?: string[];
+    /** 자동완성 후보. 글자 묶음, 또는 `{ id, label, hint? }` 줄 묶음(말귀 요청 ㊻). */
+    suggestions?: (string | TextFieldSuggestion)[];
+    /** 거르는 법. `false` 면 **안 거른다**(부르는 쪽이 이미 걸러 준 것). 기본은 `label` 에
+     *  글자가 들어 있나. 초성 찾기처럼 셈이 다른 자리에서 바꾼다. */
+    filterSuggestions?: false | ((suggestions: (string | TextFieldSuggestion)[], value: string) => (string | TextFieldSuggestion)[]);
+    /** 주면 **고를 때 칸에 값을 안 넣고** 고른 줄을 그대로 준다 — '값 채우기' 가 아니라
+     *  '어디로 가기' 인 자리에 쓴다. */
+    onSelectSuggestion?: (item: string | TextFieldSuggestion) => void;
+    /** 목록이 뜨면 첫 줄을 바로 짚는다. 기본 거짓 — `useComboboxSuggestions` 의 같은 이름 참고. */
+    autoActiveFirst?: boolean;
     /** 포커스 시 입력이 비어 있어도 전체 후보 목록을 표시 (suggestions와 함께 사용) */
     openOnFocus?: boolean;
 }

package/dist/packages/core/src/components/TextField.js

@@ -13,7 +13,7 @@ import { useIsoLayoutEffect } from '../hooks/useIsoLayoutEffect';
 import './TextField.css';
 /** @public */
 export default function TextField(props) {
-    const { value, defaultValue, name, inputRef, onChange, label, ariaLabel, required, placeholder, ghostText, ghostHint, type = 'text', disabled = false, readOnly = false, error, helperText, maxLength, size = 48, variant = 'input', fullWidth = false, newline = false, multiline = false, rows = 3, leftIcon, rightIcon, clearable = false, list, showCount = true, className = '', onFocus, onBlur, onKeyDown, onEnter, inputMode, autoComplete, autoFocus, suggestions: suggestionsProp, openOnFocus = false, } = props;
+    const { value, defaultValue, name, inputRef, onChange, label, ariaLabel, required, placeholder, ghostText, ghostHint, type = 'text', disabled = false, readOnly = false, error, helperText, maxLength, size = 48, variant = 'input', fullWidth = false, newline = false, multiline = false, rows = 3, leftIcon, rightIcon, clearable = false, list, showCount = true, className = '', onFocus, onBlur, onKeyDown, onEnter, inputMode, autoComplete, autoFocus, suggestions: suggestionsProp, filterSuggestions, onSelectSuggestion, autoActiveFirst, openOnFocus = false, } = props;
     // 읽기 전용·꺼진 칸은 후보로 값을 바꾸지 못한다 — 전에는 ↓·Enter·후보 누름으로 onChange 가 나갔다
     const suggestions = readOnly || disabled ? undefined : suggestionsProp;
     const { t } = useTranslation();
@@ -41,6 +41,9 @@ export default function TextField(props) {
         onChange,
         suggestions: suggestions ?? [],
         openOnFocus,
+        filterSuggestions,
+        onSelectSuggestion,
+        autoActiveFirst,
     });
     /* 후보 목록이 지금 DOM 에 있는가 — 아래 렌더 조건과 **같은 식**이어야 한다 */
     const 목록떴나 = !!suggestions && combobox.open && combobox.filtered.length > 0;
@@ -266,10 +269,12 @@ export default function TextField(props) {
                                 setInnerLen(0);
                             }
                             onChange?.('');
-                        }, tabIndex: -1 })), rightIcon && !showClear && (_jsx("span", { className: "text-field__icon text-field__icon--right", children: _jsx(Icon, { icon: rightIcon, label: "", className: "", svgClassName: "text-field__icon-svg", size: iconSize }) }))] }), 목록떴나 && (typeof document === 'undefined' ? null : createPortal(_jsx("ul", { id: combobox.listId, className: "text-field__suggestions", role: "listbox", style: listStyle ?? { position: 'fixed', visibility: 'hidden' }, "data-tooltip-ignore": true, children: combobox.filtered.map((s, i) => (_jsx("li", { id: `${combobox.listId}-option-${i}`, role: "option", "aria-selected": i === combobox.activeIdx, className: `text-field__suggestion body-2${i === combobox.activeIdx ? ' is-active' : ''}`, 
+                        }, tabIndex: -1 })), rightIcon && !showClear && (_jsx("span", { className: "text-field__icon text-field__icon--right", children: _jsx(Icon, { icon: rightIcon, label: "", className: "", svgClassName: "text-field__icon-svg", size: iconSize }) }))] }), !!suggestions && (_jsx("span", { className: "text-field__status", role: "status", "aria-live": "polite", children: combobox.open && (value ?? '').length > 0 && combobox.filtered.length === 0
+                    ? t('common.noMatches', '맞는 항목이 없습니다')
+                    : '' })), 목록떴나 && (typeof document === 'undefined' ? null : createPortal(_jsx("ul", { id: combobox.listId, className: "text-field__suggestions", role: "listbox", style: listStyle ?? { position: 'fixed', visibility: 'hidden' }, "data-tooltip-ignore": true, children: combobox.filtered.map((s, i) => (_jsx("li", { id: `${combobox.listId}-option-${i}`, role: "option", "aria-selected": i === combobox.activeIdx, className: `text-field__suggestion body-2${i === combobox.activeIdx ? ' is-active' : ''}`, 
                     // 선택은 click 에서 한다. onMouseDown 만 두면 마우스로는 눌리지만 스크린리더가
                     // 이 option 을 활성화할 때는 click 만 발생해 아무 일도 일어나지 않는다.
                     // mousedown 에서는 기본 동작(포커스 이동 → 입력 blur)을 막아, click 이 도달하기
                     // 전에 목록이 닫히지 않게 한다 — blur 쪽 120ms 딜레이에 기대지 않아도 된다.
-                    onMouseDown: e => e.preventDefault(), onClick: () => { combobox.handleSelect(s); autoRef.current?.focus(); }, children: s }, `${s}-${i}`))) }), document.body)), (helperText || error) && (_jsx("div", { className: "text-field__footer", children: _jsx("span", { id: helperId, className: "text-field__helper caption-1", role: error ? 'alert' : undefined, children: error || helperText }) }))] }));
+                    onMouseDown: e => e.preventDefault(), onClick: () => { combobox.handleSelect(s); autoRef.current?.focus(); }, children: typeof s === 'string' ? s : (_jsxs(_Fragment, { children: [_jsx("span", { className: "text-field__suggestion-label", children: s.label }), s.hint && _jsx("span", { className: "text-field__suggestion-hint caption-1", children: s.hint })] })) }, typeof s === 'string' ? `${s}-${i}` : s.id))) }), document.body)), (helperText || error) && (_jsx("div", { className: "text-field__footer", children: _jsx("span", { id: helperId, className: "text-field__helper caption-1", role: error ? 'alert' : undefined, children: error || helperText }) }))] }));
 }

package/dist/packages/core/src/components/Word/WordTableButton.js

@@ -27,5 +27,5 @@ export default function WordTableButton({ items, name, description, createdAt, c
     return (_jsxs("div", { className: cx('word-table-button', selected ? 'word-table-button--selected' : '', !hasStoreFooter ? 'word-table-button--no-footer' : '', className), role: "button", tabIndex: 0, "aria-label": code ? `${name} (${code})` : name, onClick: renaming ? undefined : onClick, onKeyDown: handleKey, children: [isNew && _jsx("span", { className: "word-table-button__new-dot", "aria-label": t('myWordTable.newBadge', '새로 만든 표') }), _jsx(WordTableThumbnail, { items: items, className: "word-table-button__thumb" }), _jsxs("div", { className: "word-table-button__info", children: [_jsxs("div", { className: "word-table-button__info-text", children: [titleNode ?? _jsx("div", { className: "word-table-button__title h4", children: name }), description && _jsx("div", { className: "word-table-button__desc body-3", children: description })] }), onMore && !renaming && (_jsx(Button, { htmlType: "button", className: "word-table-button__more", size: 32, type: "dot", variant: "transparent-gray", useBorder: false, icon: "ellipsis", 
                         /* 하드코딩 '더보기'였다(영어 화면에서도 한국어로 남았다). 목록에 표가
                            여러 개면 이름이 같은 버튼이 여러 개이기도 해서 이름을 함께 넣는다. */
-                        ariaLabel: t('common.moreFor', { name }), onClick: (e) => { e.stopPropagation(); onMore(e); } }))] }), (code || createdAt || published || shared) && (_jsxs("div", { className: "word-table-button__meta-row", children: [_jsx("span", { className: "word-table-button__meta-left", children: _jsx("span", { className: "word-table-button__meta caption-1", children: createdAt ? formatRelativeTime(createdAt, t) : '' }) }), _jsxs("span", { className: "word-table-button__meta-right", children: [(published || shared) && (_jsxs("span", { className: "word-table-button__badges", children: [published && (_jsx(Badge, { className: "word-table-button__badge", size: "small", variant: "main", fill: "soft", iconLeft: "book-marked", label: publishedLabel ?? t('myWordTable.publishedBadge', '발행됨') })), shared && (_jsx(Badge, { className: "word-table-button__badge", size: "small", fill: "soft", iconLeft: "link", label: sharedLabel ?? t('myWordTable.sharedBadge', '공유 중') }))] })), code && _jsx("span", { className: "word-table-button__code caption-1", children: code })] })] })), hasStoreFooter && (_jsxs("div", { className: "word-table-button__footer", children: [_jsxs("span", { className: "word-table-button__store-by", children: [publisherName && (_jsx("button", { className: "training-card__publisher body-4", type: "button", onClick: (e) => { e.stopPropagation(); onPublisherClick?.(); }, children: publisherName })), publishedAt && _jsx("span", { className: "training-card__date body-4", children: formatRelativeTime(publishedAt, t) })] }), _jsxs("span", { className: "word-table-button__store-stats", children: [likeCount != null && _jsx(Badge, { size: "small", fill: "soft", variant: "like", iconLeft: "heart", label: String(likeCount) }), downloadCount != null && _jsx(Badge, { size: "small", fill: "soft", variant: "main", iconLeft: "download", label: String(downloadCount) })] })] }))] }));
+                        ariaLabel: t('common.moreFor', { name }), onClick: (e) => { e.stopPropagation(); onMore(e); } }))] }), (code || createdAt || published || shared) && (_jsxs("div", { className: "word-table-button__meta-row", children: [_jsx("span", { className: "word-table-button__meta-left", children: _jsx("span", { className: "word-table-button__meta caption-1", children: createdAt ? formatRelativeTime(createdAt, t) : '' }) }), _jsxs("span", { className: "word-table-button__meta-right", children: [(published || shared) && (_jsxs("span", { className: "word-table-button__badges", children: [published && (_jsx(Badge, { className: "word-table-button__badge", size: "small", variant: "main", fill: "soft", iconLeft: "book-marked", label: publishedLabel ?? t('myWordTable.publishedBadge', '발행됨') })), shared && (_jsx(Badge, { className: "word-table-button__badge", size: "small", fill: "soft", iconLeft: "link", label: sharedLabel ?? t('myWordTable.sharedBadge', '공유 중') }))] })), code && _jsx("span", { className: "word-table-button__code caption-1", children: code })] })] })), hasStoreFooter && (_jsxs("div", { className: "word-table-button__footer", children: [_jsxs("span", { className: "word-table-button__store-by", children: [publisherName && (_jsx("button", { className: "training-card__publisher body-4", type: "button", onClick: (e) => { e.stopPropagation(); onPublisherClick?.(); }, children: publisherName })), publishedAt && _jsx("span", { className: "training-card__date body-4", children: formatRelativeTime(publishedAt, t) })] }), _jsxs("span", { className: "word-table-button__store-stats", children: [likeCount != null && (_jsx(Badge, { size: "small", fill: "soft", variant: "like", iconLeft: "heart", label: String(likeCount), "aria-label": t('common.likeCount', { count: likeCount, defaultValue: `좋아요 ${likeCount}` }) })), downloadCount != null && (_jsx(Badge, { size: "small", fill: "soft", variant: "main", iconLeft: "download", label: String(downloadCount), "aria-label": t('common.downloadCount', { count: downloadCount, defaultValue: `가져간 수 ${downloadCount}` }) }))] })] }))] }));
 }

package/dist/packages/core/src/components/useComboboxSuggestions.d.ts

@@ -1,4 +1,17 @@
 import { type KeyboardEvent } from 'react';
+/**
+ * 후보 한 줄 — 글자 하나로는 못 담는 자리(말귀 요청 ㊻, 2026-10-01).
+ *
+ * `label` 이 줄에 적히고 **거르기의 기본 대상**이며, `hint` 는 그 오른쪽에 흐리게 서는
+ * 갈래 글자(`숙제` · `나의 단어표` 같은 것)다. `id` 는 고른 뒤 부르는 쪽이 무엇을 골랐는지
+ * 알아보는 열쇠 — 이름이 같은 두 줄을 가릴 수 있어야 한다.
+ * @public
+ */
+export interface TextFieldSuggestion {
+    id: string;
+    label: string;
+    hint?: string;
+}
 /**
  * TextField의 `suggestions` 옵션이 쓰는 자동완성 콤보박스 상태/키보드 로직.
  * 순수 입력(값 관리)과 분리해서, 자동완성이 필요 없는 TextField 사용처는
@@ -8,21 +21,39 @@ import { type KeyboardEvent } from 'react';
  * `handleCompositionEnd` 를 걸어야 한다(TextField 는 건다). 걸지 않으면 지금처럼 매 값마다 다시 거른다.
  * @public
  */
-export declare function useComboboxSuggestions({ value, onChange, suggestions, openOnFocus, }: {
+export declare function useComboboxSuggestions<T extends string | TextFieldSuggestion = string>({ value, onChange, suggestions, openOnFocus, filterSuggestions, onSelectSuggestion, autoActiveFirst, }: {
     value: string;
     onChange?: (value: string) => void;
-    suggestions: string[];
+    /** 글자 묶음, 또는 `{ id, label, hint? }` 줄 묶음 */
+    suggestions: T[];
     openOnFocus?: boolean;
+    /** 거르는 법을 바꾼다. `false` 면 **안 거른다** — 부르는 쪽이 이미 걸러 준 것으로 본다.
+     *  기본은 `label` 에 글자가 들어 있나(대소문자 무시)다. 초성 찾기처럼 셈이 다른 자리에서
+     *  쓴다(`matchesChoseongSearch` 는 이 꾸러미의 `utils` 에 있다). */
+    filterSuggestions?: false | ((suggestions: T[], value: string) => T[]);
+    /** 주면 **고를 때 칸에 값을 안 넣는다** — 고른 줄을 그대로 받는다. 고르는 것이 '값 채우기'
+     *  가 아니라 '어디로 가기' 인 자리(화면 찾기 등)에 쓴다. */
+    onSelectSuggestion?: (item: T) => void;
+    /** 목록이 뜨면 **첫 줄을 바로 짚는다**(ARIA 의 automatic selection).
+     *
+     *  기본은 거짓 — 아무것도 안 짚은 채 열리고, 그 상태의 Enter 는 제안을 안 고른다
+     *  (친 글자를 그대로 쓰겠다는 뜻이다). 자유롭게 치는 칸에서는 그쪽이 맞다.
+     *  **고르는 것이 '어디로 가기' 인 칸에서는 참이 맞다** — 치자마자 Enter 로 첫 줄에 가고,
+     *  `aria-expanded` 가 참인데 짚은 줄이 없어 낭독기에 "목록이 떴다" 만 가고 **뭐가 떴는지는
+     *  안 가는** 것도 함께 풀린다(말귀가 그래서 손수 0 으로 시작하게 두고 있었다).
+     *  `onSelectSuggestion` 과 **묶지 않았다** — 고르는 것이 가기인데도 친 글자를 그대로
+     *  쓰고 싶은 칸이 있다(검색어를 그대로 보내는 자리). 서로 다른 결정이다. */
+    autoActiveFirst?: boolean;
 }): {
     listId: string;
     open: boolean;
     activeIdx: number;
-    filtered: string[];
+    filtered: T[];
     handleFocus: () => void;
     handleBlur: () => void;
     handleInput: () => void;
     handleKeyDown: (e: KeyboardEvent<HTMLInputElement | HTMLTextAreaElement>) => void;
-    handleSelect: (item: string) => void;
+    handleSelect: (item: T) => void;
     /** 입력칸의 onCompositionStart 에 건다 — 조합 중에는 걸리는 후보가 0 건이 되어도 직전 목록을 둔다 */
     handleCompositionStart: () => void;
     /** 입력칸의 onCompositionEnd 에 건다 — 조합이 끝나면 목록을 다시 계산한다 */

package/dist/packages/core/src/components/useComboboxSuggestions.js

@@ -1,5 +1,9 @@
 'use client';
 import { useCallback, useEffect, useId, useMemo, useRef, useState } from 'react';
+/** 글자 하나든 한 줄이든 **줄에 적히는 말**을 꺼낸다 */
+function 라벨(x) {
+    return typeof x === 'string' ? x : x.label;
+}
 /**
  * TextField의 `suggestions` 옵션이 쓰는 자동완성 콤보박스 상태/키보드 로직.
  * 순수 입력(값 관리)과 분리해서, 자동완성이 필요 없는 TextField 사용처는
@@ -9,7 +13,7 @@ import { useCallback, useEffect, useId, useMemo, useRef, useState } from 'react'
  * `handleCompositionEnd` 를 걸어야 한다(TextField 는 건다). 걸지 않으면 지금처럼 매 값마다 다시 거른다.
  * @public
  */
-export function useComboboxSuggestions({ value, onChange, suggestions, openOnFocus = false, }) {
+export function useComboboxSuggestions({ value, onChange, suggestions, openOnFocus = false, filterSuggestions, onSelectSuggestion, autoActiveFirst = false, }) {
     const listId = useId();
     const [open, setOpen] = useState(false);
     const [activeIdx, setActiveIdx] = useState(-1);
@@ -18,10 +22,16 @@ export function useComboboxSuggestions({ value, onChange, suggestions, openOnFoc
         if (!suggestions.length)
             return [];
         const v = value ?? '';
+        /* **안 거르는 쪽**(`false`)은 빈 값에서도 그대로 낸다 — 부르는 쪽이 이미 고른 것이라
+           여기서 또 비우면 그 셈을 버리는 꼴이다. */
+        if (filterSuggestions === false)
+            return suggestions;
         if (!v)
             return openOnFocus ? suggestions : [];
-        return suggestions.filter(s => s.toLowerCase().includes(v.toLowerCase()));
-    }, [suggestions, value, openOnFocus]);
+        if (typeof filterSuggestions === 'function')
+            return filterSuggestions(suggestions, v);
+        return suggestions.filter(s => 라벨(s).toLowerCase().includes(v.toLowerCase()));
+    }, [suggestions, value, openOnFocus, filterSuggestions]);
     /* **한글 조합 중에는 0 건이 되어도 직전 목록을 둔다.** '사'→'삭'→'사고' 로 치는 동안 중간값 '삭' 에 걸리는 후보가 없어
        목록이 한 박자 사라졌다 돌아왔다(깜빡임·스크린리더가 목록 닫힘을 알림). 조합이 끝나면(compositionend) 다시 계산한다.
        부르는 쪽이 suggestions 를 값으로 미리 거른 경우(matchesWordQuery 순위 등)도 같다 — 순위 규칙은 건드리지 않는다. */
@@ -34,21 +44,26 @@ export function useComboboxSuggestions({ value, onChange, suggestions, openOnFoc
     const handleCompositionEnd = useCallback(() => set조합중(false), []);
     // 메뉴가 닫히면 활성 인덱스를 리셋하는 의도된 동기화다
     // eslint-disable-next-line react-hooks/set-state-in-effect
+    const 처음짚는자리 = autoActiveFirst ? 0 : -1;
     useEffect(() => { if (!open)
-        setActiveIdx(-1); }, [open]);
+        setActiveIdx(처음짚는자리); }, [open, 처음짚는자리]);
     useEffect(() => () => { if (blurTimerRef.current)
         clearTimeout(blurTimerRef.current); }, []);
     /* 입력으로 후보가 줄면 가리키던 번호가 목록 밖에 남는다 — 그 채로 Enter 를 누르면 filtered[3] 같은
        없는 칸을 골라 onChange(undefined) 가 나갔다. 밖이면 '안 가리킴' 으로 본다. */
-    const safeIdx = activeIdx < filtered.length ? activeIdx : -1;
+    const safeIdx = activeIdx < filtered.length ? activeIdx : 처음짚는자리 < filtered.length ? 처음짚는자리 : -1;
     const handleSelect = useCallback((item) => {
-        onChange?.(item);
+        /* 고르는 것이 '값 채우기' 가 아닌 자리가 있다 — 그때는 칸을 안 건드린다 */
+        if (onSelectSuggestion)
+            onSelectSuggestion(item);
+        else
+            onChange?.(라벨(item));
         setOpen(false);
-    }, [onChange]);
+    }, [onChange, onSelectSuggestion]);
     const handleFocus = useCallback(() => setOpen(true), []);
     /* 글자를 치면 목록을 다시 연다 — 고르거나 Esc 로 닫은 뒤에는 포커스를 뺐다 넣어야만 열렸다.
        새 글자에는 새 후보가 서므로 가리킴도 처음으로 돌린다. */
-    const handleInput = useCallback(() => { setOpen(true); setActiveIdx(-1); }, []);
+    const handleInput = useCallback(() => { setOpen(true); setActiveIdx(처음짚는자리); }, [처음짚는자리]);
     // blur가 리스트 항목의 onMouseDown보다 먼저 발생하는 걸 막기 위한 딜레이
     const handleBlur = useCallback(() => {
         blurTimerRef.current = setTimeout(() => setOpen(false), 120);
@@ -61,11 +76,12 @@ export function useComboboxSuggestions({ value, onChange, suggestions, openOnFoc
         if (e.key === 'ArrowDown') {
             e.preventDefault();
             setOpen(true);
-            setActiveIdx(i => Math.min(filtered.length - 1, (i < filtered.length ? i : -1) + 1));
+            setActiveIdx(i => Math.min(filtered.length - 1, (i < filtered.length ? i : 처음짚는자리) + 1));
         }
         else if (e.key === 'ArrowUp') {
             e.preventDefault();
-            setActiveIdx(i => Math.max(-1, (i < filtered.length ? i : filtered.length) - 1));
+            /* 첫 줄을 늘 짚는 칸에서는 **안 짚은 상태로 못 올라간다** — 그 상태가 없다 */
+            setActiveIdx(i => Math.max(처음짚는자리, (i < filtered.length ? i : filtered.length) - 1));
         }
         else if (e.key === 'Enter') {
             // 한글 조합을 끝내는 Enter는 선택이 아니다 — 조합 중엔 제안을 고르지 않는다
@@ -78,7 +94,7 @@ export function useComboboxSuggestions({ value, onChange, suggestions, openOnFoc
                 setOpen(false);
             } // 제안이 열렸을 때만 소비(상위 팝업 ESC보다 우선하지 않도록)
         }
-    }, [filtered, safeIdx, open, handleSelect]);
+    }, [filtered, safeIdx, open, handleSelect, 처음짚는자리]);
     return {
         listId, open, activeIdx: safeIdx, filtered, handleFocus, handleBlur, handleInput, handleKeyDown, handleSelect,
         /** 입력칸의 onCompositionStart 에 건다 — 조합 중에는 걸리는 후보가 0 건이 되어도 직전 목록을 둔다 */

package/dist/packages/core/src/components.d.ts

@@ -123,7 +123,7 @@ export { default as Loader } from './components/Loader';
 export { default as SegmentedControl } from './components/SegmentedControl';
 export { default as TextField } from './components/TextField';
 export type { TextFieldProps } from './components/TextField';
-export { useComboboxSuggestions } from './components/useComboboxSuggestions';
+export { useComboboxSuggestions, type TextFieldSuggestion } from './components/useComboboxSuggestions';
 export { default as Dropdown } from './components/Dropdown';
 export type { DropdownProps, DropdownOption } from './components/Dropdown';
 export { useAnchoredMenu } from './hooks/useAnchoredMenu';

package/dist/packages/core/src/i18n/locales/en.json

@@ -27,6 +27,9 @@
         "reset": "Reset",
         "update": "Update",
         "download": "Download",
+        "likeCount": "{{count}} likes",
+        "selectedOfMax": "{{count}} of {{max}}",
+        "downloadCount": "{{count}} downloads",
         "search": "Search",
         "empty": "No data.",
         "yes": "Yes",
@@ -49,6 +52,7 @@
         "continue": "Continue",
         "notification": "Notice",
         "emptyList": "No items",
+        "noMatches": "No matching items",
         "menu": "Menu",
         "resetSelection": "Reset Selection",
         "pageSizeLabel": "Show {{n}}",

package/dist/packages/core/src/i18n/locales/ko.json

@@ -3,6 +3,7 @@
         "statusFilter": "상태 필터",
         "pageSizeSelect": "페이지당 표시 개수",
         "selectedCount": "{{count}}개 선택됨",
+        "selectedOfMax": "최대 {{max}}개 중 {{count}}개",
         "cancel": "취소",
         "info": "설명",
         "errorState": {
@@ -25,6 +26,8 @@
         "reset": "초기화",
         "update": "업데이트",
         "download": "다운로드",
+        "likeCount": "좋아요 {{count}}",
+        "downloadCount": "가져간 수 {{count}}",
         "search": "검색",
         "empty": "데이터가 없습니다.",
         "yes": "예",
@@ -48,6 +51,7 @@
         "continue": "계속",
         "notification": "알림",
         "emptyList": "항목이 없습니다.",
+        "noMatches": "맞는 항목이 없습니다",
         "menu": "메뉴",
         "resetSelection": "선택 초기화",
         "pageSizeLabel": "{{n}}개씩 보기",

package/dist/packages/core/src/version.d.ts

@@ -46,4 +46,4 @@
  *
  * 값은 손으로 적고 `test/coreVersion.test.ts` 가 package.json 과 어긋나면 운다.
  */
-export declare const CORE_VERSION = "0.231.0";
+export declare const CORE_VERSION = "0.233.0";

package/dist/packages/core/src/version.js

@@ -46,4 +46,4 @@
  *
  * 값은 손으로 적고 `test/coreVersion.test.ts` 가 package.json 과 어긋나면 운다.
  */
-export const CORE_VERSION = '0.231.0';
+export const CORE_VERSION = '0.233.0';