@ncds/ui-admin 1.8.25-alpha.3 → 1.8.25

package/dist/temp/src/components/feedback-and-status/badge/Badge.d.ts

@@ -16,4 +16,4 @@ type BadgeProps = {
 };
 declare const Badge: ({ label, type, color, className, leadingIcon, trailingIcon, size, }: BadgeProps) => import("react/jsx-runtime").JSX.Element;
 export { Badge };
-export type { BadgeColor, BadgeProps, BadgeSize, BadgeType };
+export type { BadgeType, BadgeColor, BadgeSize, BadgeProps };

package/dist/temp/src/components/feedback-and-status/badge/Badge.js

@@ -7,7 +7,7 @@ import { sideSlotRender } from './utils';
  */
 const BADGE_ICON_SIZE = 12;
 /** new-badge 박스 안에 들어가는 'N' 아이콘 크기. 박스는 sm 16px / md 20px 이며 아이콘은 그보다 작다(패딩 포함). */
-const NEW_BADGE_ICON_SIZE = { sm: 12, md: 14 };
+const NEW_BADGE_ICON_SIZE = { sm: 12, md: 16 };
 const Badge = ({ label, type = 'pill-outline', color = 'neutral', className, leadingIcon, trailingIcon, size = 'xs', }) => {
     // new-badge: 신규 콘텐츠 'N' 마크 전용 타입. label·color·leadingIcon·trailingIcon은 무시되고
     // 색은 --pink-600 으로 고정된다. (디자이너 명세: Icon/FeaturedIcon/Badge로 대체 불가한 전용 표시)

package/dist/temp/src/components/forms-and-input/combo-box/ComboBox.d.ts

@@ -10,7 +10,7 @@ interface ComboBoxProps extends Omit<ComponentPropsWithRef<'div'>, 'size' | 'onC
     destructive?: boolean;
     size?: Extract<Size, 'xs' | 'sm'>;
     optionItems?: OptionType[];
-    value?: OptionValue;
+    value?: OptionValue | null;
     onChange?: OptionChangeHandler;
     onSearch?: (searchValue: string) => void;
     disabled?: boolean;

package/dist/temp/src/components/forms-and-input/combo-box/ComboBox.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { ChevronSelectorVertical, SearchLg } from '@ncds/ui-admin-icon';
 import classNames from 'classnames';
-import { forwardRef, useImperativeHandle, useRef, useState } from 'react';
+import { forwardRef, useEffect, useImperativeHandle, useRef, useState, } from 'react';
 import { useDropdown } from '../../../hooks/dropdown';
 import { useFloatingPosition } from '../../../hooks/useFloatingPosition';
 import { usePortalState } from '../../../hooks/usePortalState';
@@ -23,6 +23,108 @@ const notifyFormChange = (register, multiple, newValue) => {
         });
     }
 };
+/** '' · undefined · null 이면 빈 값. 숫자 0은 빈 값이 아니다 */
+const isEmptyValue = (value) => value === '' || value == null;
+/** react-hook-form hidden input 값 — Tag 와 같은 빈 값 규칙(0은 값)을 따른다 */
+const toHiddenInputValue = (value, multiple) => {
+    if (multiple)
+        return JSON.stringify(value || []);
+    return isEmptyValue(value) ? '' : String(value);
+};
+/** SelectDropdown 은 null 을 받지 않으므로 undefined 로 바꾼다 */
+const toDropdownValue = (value) => value ?? undefined;
+/** multiple 용 — 배열이 아니면(null · undefined 포함) 빈 배열 */
+const toIdArray = (value) => (Array.isArray(value) ? value : []);
+/** 두 id 목록이 같은 id 들로 이루어졌는지 — 순서는 보지 않는다 (사용처가 onChange 값을 정렬해 돌려줘도 같은 값) */
+const isSameIds = (currentIds, nextIds) => currentIds.length === nextIds.length && currentIds.every((id) => nextIds.includes(id));
+const isSameTags = (nextTags, prevTags) => nextTags.length === prevTags.length &&
+    nextTags.every((tag, index) => tag.id === prevTags[index].id && tag.label === prevTags[index].label);
+const findOption = (optionItems, id) => optionItems.find((option) => option.id === id);
+/** 단일 모드 value 에 해당하는 옵션 — 빈 값·배열이면 없음 */
+const findSingleOption = (value, optionItems) => {
+    if (isEmptyValue(value) || Array.isArray(value))
+        return undefined;
+    return findOption(optionItems, value);
+};
+/**
+ * 단일 모드 Tag — value 와 optionItems 에서 계산한다.
+ * 검색 필터로 목록에서 빠진 경우에만, 같은 id 로 기억해 둔 Tag 를 대신 쓴다.
+ */
+const resolveSingleTag = (value, optionItems, lastResolvedTag) => {
+    if (isEmptyValue(value) || Array.isArray(value))
+        return null;
+    const found = findOption(optionItems, value);
+    if (found)
+        return { id: found.id, label: found.label };
+    return lastResolvedTag?.id === value ? lastResolvedTag : null;
+};
+/** 단일 모드 Tag 목록 (0~1개). 목록에서 찾은 Tag 를 기억해 검색 필터 중에도 라벨을 유지한다 */
+const useSingleSelectedTags = (value, optionItems, enabled) => {
+    const [lastResolvedTag, setLastResolvedTag] = useState(null);
+    const found = enabled ? findSingleOption(value, optionItems) : undefined;
+    const foundId = found?.id;
+    const foundLabel = found?.label;
+    useEffect(() => {
+        if (foundId === undefined || foundLabel === undefined)
+            return;
+        setLastResolvedTag({ id: foundId, label: foundLabel });
+    }, [foundId, foundLabel]);
+    const selectedTag = enabled ? resolveSingleTag(value, optionItems, lastResolvedTag) : null;
+    return selectedTag ? [selectedTag] : [];
+};
+/** multiple 모드 Tag — 목록에서 못 찾은 id 는 이미 표시 중인 Tag 의 라벨을 쓴다 */
+const resolveMultipleTags = (ids, optionItems, prevTags) => {
+    const nextTags = ids
+        .map((id) => {
+        const found = findOption(optionItems, id);
+        return found ? { id: found.id, label: found.label } : prevTags.find((tag) => tag.id === id);
+    })
+        .filter((tag) => tag !== undefined);
+    // 결과가 같으면 이전 배열을 그대로 돌려준다 — 새 배열로 바꾸면 effect 가 다시 렌더를 일으킨다
+    return isSameTags(nextTags, prevTags) ? prevTags : nextTags;
+};
+/**
+ * multiple 모드 Tag — 「선택 완료」·X 클릭·외부 value 변경 때만 확정 id 를 바꾼다.
+ * ComboBox 가 직접 onChange 로 내보낸 값은 markEmitted 로 기록해 두고, 그 값이 value 로 돌아오면 한 번만 무시한다(확정 아님).
+ * 바깥 값이 들어오면 남아 있던 기록도 지운다 — 오래된 기록 때문에 이후 같은 바깥 값이 무시되지 않게 하기 위함.
+ * optionItems 만 바뀌면 확정 id 는 그대로 두고 라벨만 다시 찾는다 — 「선택 완료」 전 검색으로 Tag 가 확정되지 않게 하기 위함.
+ */
+const useMultipleSelectedTags = (value, optionItems, enabled) => {
+    const [selectedTags, setSelectedTags] = useState([]);
+    const lastEmittedRef = useRef(null);
+    const committedIdsRef = useRef([]);
+    const prevValueIdsRef = useRef(null);
+    useEffect(() => {
+        if (!enabled)
+            return;
+        const ids = toIdArray(value);
+        const isEcho = lastEmittedRef.current !== null && isSameIds(ids, lastEmittedRef.current);
+        const isValueChanged = prevValueIdsRef.current === null || !isSameIds(ids, prevValueIdsRef.current);
+        prevValueIdsRef.current = ids;
+        if (isEcho) {
+            lastEmittedRef.current = null;
+        }
+        else if (isValueChanged) {
+            committedIdsRef.current = ids;
+            lastEmittedRef.current = null;
+        }
+        setSelectedTags((prev) => resolveMultipleTags(committedIdsRef.current, optionItems, prev));
+    }, [enabled, value, optionItems]);
+    /** 「선택 완료」로 Tag 를 확정한다 */
+    const commitTags = (ids) => {
+        committedIdsRef.current = ids;
+        setSelectedTags((prev) => resolveMultipleTags(ids, optionItems, prev));
+    };
+    /** X 클릭 — 확정 id 에서 그 id 만 뺀다. value 기준으로 계산하면 「선택 완료」 전에 클릭한 항목까지 확정된다 */
+    const removeCommittedTag = (tagId) => {
+        commitTags(committedIdsRef.current.filter((id) => id !== tagId));
+    };
+    /** ComboBox 가 onChange 로 내보낸 값을 기록한다 — value 로 돌아왔을 때 확정으로 보지 않기 위함 */
+    const markEmitted = (ids) => {
+        lastEmittedRef.current = ids;
+    };
+    return { selectedTags, commitTags, removeCommittedTag, markEmitted };
+};
 const ComboBox = forwardRef(({ placeholder = '검색하세요', id, className, hintText, children, size = 'xs', destructive = false, value, optionItems = [], onChange, onSearch, disabled = false, register, maxHeight = defaultMaxHeight, searchValue = '', label, required = false, multiple = false, showFooterButtons = false, maxSelection, onEdit, onComplete, usePortal = false, ...props }, ref) => {
     const internalRef = useRef(null);
     // 인라인 패널의 offset parent 가 __content 다. Portal 좌표도 같은 박스를 기준으로 잡아야
@@ -33,7 +135,8 @@ const ComboBox = forwardRef(({ placeholder = '검색하세요', id, className, h
     const { shouldPortal, portalContainer } = usePortalState(usePortal);
     const [inputValue, setInputValue] = useState(searchValue);
     const [showAllItems, setShowAllItems] = useState(false);
-    const [selectedTags, setSelectedTags] = useState([]);
+    const singleTags = useSingleSelectedTags(value, optionItems, !multiple);
+    const { selectedTags, commitTags, removeCommittedTag, markEmitted } = useMultipleSelectedTags(value, optionItems, multiple);
     const handleOptionSelect = (option) => {
         if (disabled)
             return;
@@ -41,13 +144,12 @@ const ComboBox = forwardRef(({ placeholder = '검색하세요', id, className, h
             const newValue = tryToggle(option.id, Array.isArray(value) ? value : []);
             if (newValue === null)
                 return;
+            markEmitted(newValue);
             onChange?.(newValue);
             notifyFormChange(register, multiple, newValue);
             return;
         }
         const newValue = option.id;
-        const tag = { id: option.id, label: option.label };
-        setSelectedTags([tag]);
         onChange?.(newValue);
         notifyFormChange(register, multiple, newValue);
     };
@@ -130,11 +232,12 @@ const ComboBox = forwardRef(({ placeholder = '검색하세요', id, className, h
         color: 'gray300',
     };
     const currentSelectedValues = multiple && Array.isArray(value) ? value : [];
-    const { buttonText: selectAllButtonText, toggleSelectAll, getSelectedTagsData, removeTag, isMaxSelectionActive, tryToggle, } = useMultiSelect(currentSelectedValues, optionItems, { maxSelection });
+    const { buttonText: selectAllButtonText, toggleSelectAll, removeTag, isMaxSelectionActive, tryToggle, } = useMultiSelect(currentSelectedValues, optionItems, { maxSelection });
     const handleSelectAll = () => {
         if (!multiple || !onChange)
             return;
         const newSelectedValues = toggleSelectAll();
+        markEmitted(newSelectedValues);
         onChange(newSelectedValues);
     };
     const handleEdit = () => {
@@ -143,33 +246,36 @@ const ComboBox = forwardRef(({ placeholder = '검색하세요', id, className, h
     const handleComplete = (completedValue) => {
         if (!multiple)
             return;
-        const tags = getSelectedTagsData();
-        setSelectedTags(tags);
+        commitTags(toIdArray(completedValue));
         setInputValue('');
         closeDropdown();
         onComplete?.(completedValue);
     };
     const handleRemoveTag = (tagId) => {
+        // X 버튼은 disabled 에서 숨기지만, 다른 호출 경로가 생겨도 값이 지워지지 않게 함수에서도 막는다
+        if (disabled)
+            return;
         if (!onChange)
             return;
         if (multiple) {
             const newSelectedValues = removeTag(tagId);
+            markEmitted(newSelectedValues);
             onChange(newSelectedValues);
-            setSelectedTags((prev) => prev.filter((tag) => tag.id !== tagId));
+            removeCommittedTag(tagId);
             return;
         }
         onChange('');
-        setSelectedTags([]);
     };
     const comboboxId = `combobox-options-${id || 'default'}`;
     const hasVisibleOptions = showAllItems || inputValue;
     const displayedOptions = hasVisibleOptions ? optionItems : [];
     const showNoResults = !hasVisibleOptions || optionItems.length === 0;
     const showFooter = multiple || showFooterButtons;
-    const hiddenInputValue = multiple ? JSON.stringify(value || []) : String(value || '');
-    const hasTags = selectedTags.length > 0;
+    const hiddenInputValue = toHiddenInputValue(value, multiple);
+    const tags = multiple ? selectedTags : singleTags;
+    const hasTags = tags.length > 0;
     const { className: portalPanelClassName, style: portalPanelStyle } = resolvePortalPanelBinding(shouldPortal, floatingStyle);
-    const selectDropdownNode = (_jsxs(SelectDropdown, { ref: dropdownRef, isOpen: isOpen, direction: dropdownDirection, size: size, options: displayedOptions, value: value, focusedIndex: focusedIndex, maxHeight: maxHeight, listboxId: comboboxId, onOptionSelect: handleDropdownSelect, onMouseMove: handleMouseMove, isKeyboardNavigation: isKeyboardNavigation, multiple: multiple, showFooterButtons: showFooter, selectAllButtonText: selectAllButtonText, showSelectAllAction: !isMaxSelectionActive, onSelectAll: handleSelectAll, onEdit: handleEdit, onComplete: handleComplete, componentType: "combobox", className: portalPanelClassName, style: portalPanelStyle, children: [showNoResults ? _jsx("li", { className: "ncua-select-dropdown__no-results", children: "\uC77C\uCE58\uD558\uB294 \uACB0\uACFC\uAC00 \uC5C6\uC2B5\uB2C8\uB2E4." }) : null, children] }));
+    const selectDropdownNode = (_jsxs(SelectDropdown, { ref: dropdownRef, isOpen: isOpen, direction: dropdownDirection, size: size, options: displayedOptions, value: toDropdownValue(value), focusedIndex: focusedIndex, maxHeight: maxHeight, listboxId: comboboxId, onOptionSelect: handleDropdownSelect, onMouseMove: handleMouseMove, isKeyboardNavigation: isKeyboardNavigation, multiple: multiple, showFooterButtons: showFooter, selectAllButtonText: selectAllButtonText, showSelectAllAction: !isMaxSelectionActive, onSelectAll: handleSelectAll, onEdit: handleEdit, onComplete: handleComplete, componentType: "combobox", className: portalPanelClassName, style: portalPanelStyle, children: [showNoResults ? _jsx("li", { className: "ncua-select-dropdown__no-results", children: "\uC77C\uCE58\uD558\uB294 \uACB0\uACFC\uAC00 \uC5C6\uC2B5\uB2C8\uB2E4." }) : null, children] }));
     const { inlineDropdown, portaledDropdown } = resolveDropdownMounts({
         node: selectDropdownNode,
         shouldPortal,
@@ -183,7 +289,7 @@ const ComboBox = forwardRef(({ placeholder = '검색하세요', id, className, h
                 }, className), ...props, children: [_jsxs("div", { ref: contentRef, className: "ncua-combobox__content", children: [_jsx(InputBase, { ref: inputRef, size: size, label: label, required: required, placeholder: placeholder, value: inputValue, onChange: handleInputChange, onKeyDown: handleKeyDown, onClick: handleInputClick, disabled: disabled, destructive: destructive, leadingElement: leadingElement, trailingElement: trailingElement, role: "combobox", "aria-expanded": isOpen, "aria-haspopup": "listbox", "aria-controls": comboboxId, "aria-disabled": disabled, autoComplete: "off", clearText: !!inputValue, onClearText: () => {
                                     setInputValue('');
                                     onSearch?.('');
-                                } }), inlineDropdown, portaledDropdown] }), register && _jsx("input", { type: "hidden", ...register, value: hiddenInputValue }), hintText && _jsx(HintText, { destructive: destructive, children: hintText })] }), hasTags && (_jsx("div", { className: "ncua-combobox__tags", children: selectedTags.map((tag) => (_jsx(Tag, { text: tag.label, size: "sm", close: true, onButtonClick: () => handleRemoveTag(tag.id) }, tag.id))) }))] }));
+                                } }), inlineDropdown, portaledDropdown] }), register && _jsx("input", { type: "hidden", ...register, value: hiddenInputValue }), hintText && _jsx(HintText, { destructive: destructive, children: hintText })] }), hasTags && (_jsx("div", { className: "ncua-combobox__tags", children: tags.map((tag) => (_jsx(Tag, { text: tag.label, size: "sm", close: !disabled, onButtonClick: () => handleRemoveTag(tag.id) }, tag.id))) }))] }));
 });
 ComboBox.displayName = 'ComboBox';
 export { defaultMaxHeight, ComboBox };

package/dist/temp/src/components/forms-and-input/combo-box/__tests__/ComboBox.portal.test.js

@@ -333,7 +333,7 @@ describe('C-9 기본 경로 회귀 기준선', () => {
         expect(onSearch).toHaveBeenCalledWith('사');
         expect(view.content.querySelectorAll('.ncua-select-dropdown__option')).toHaveLength(createOptions().length);
     });
-    it('옵션을 선택하면 onChange 가 호출되고 선택 태그가 표시된다', () => {
+    it('옵션을 선택하면 onChange 가 호출된다', () => {
         // Given: 옵션이 노출된 기본 모드 ComboBox 에서
         const onChange = vi.fn();
         const view = mountComboBox({ props: { onChange } });
@@ -342,9 +342,9 @@ describe('C-9 기본 경로 회귀 기준선', () => {
         act(() => {
             requireElement(view.content, '.ncua-select-dropdown__option').click();
         });
-        // Then: onChange 가 선택 값으로 호출되고 태그가 표시된다
+        // Then: onChange 가 선택 값으로 호출된다
+        // 선택 태그는 value 를 따르므로(#530) onChange 값을 value 로 돌려주는 경우의 태그 표시는 ComboBox.test.ts S-10 에서 검증한다
         expect(onChange).toHaveBeenCalledWith('apple');
-        expect(view.container.querySelectorAll('.ncua-combobox__tags .ncua-tag')).toHaveLength(1);
     });
     it('Escape 를 누르면 인라인 패널이 닫힌다', () => {
         // Given: 열려 있는 기본 모드 ComboBox 에서

package/dist/temp/src/components/forms-and-input/combo-box/__tests__/ComboBox.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/temp/src/components/forms-and-input/combo-box/__tests__/ComboBox.test.js

@@ -0,0 +1,293 @@
+// @vitest-environment jsdom
+import { createElement, useState } from 'react';
+import { createRoot } from 'react-dom/client';
+import { act } from 'react-dom/test-utils';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { ComboBox } from '../ComboBox';
+// React 18에서 act() 사용 시 필요한 플래그 (미설정 시 console.error 경고 발생)
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+const OPTIONS = [
+    { id: 1, label: '사과' },
+    { id: 2, label: '바나나' },
+    { id: 3, label: '체리' },
+];
+/** id 1·2가 빠진 목록 — 검색 필터로 optionItems가 줄어든 상황 */
+const FILTERED_OPTIONS = [{ id: 3, label: '체리' }];
+/** optionItems에 없는 id */
+const MISSING_ID = 99;
+/** 바깥에서 reset 으로 넣는 값 — 기존 선택(1·2)과 겹치지 않는 id */
+const RESET_ID = 3;
+/** 「전체 선택」 결과 — OPTIONS 의 모든 id */
+const ALL_IDS = OPTIONS.map((option) => option.id);
+let root = null;
+let container = null;
+/** 같은 root에 다시 render하면 props 변경(rerender)이 된다. */
+function render(props) {
+    if (!container) {
+        container = document.createElement('div');
+        document.body.appendChild(container);
+        root = createRoot(container);
+    }
+    act(() => {
+        root?.render(createElement(ComboBox, props));
+    });
+    return container;
+}
+/** onChange로 받은 값을 value로 되돌려주는 사용처 흉내 (controlled) */
+function Harness({ initialValue, onChangeSpy, transform, ...rest }) {
+    const [value, setValue] = useState(initialValue);
+    return createElement(ComboBox, {
+        ...rest,
+        value,
+        onChange: (next) => {
+            onChangeSpy(next);
+            setValue(transform ? transform(next) : next);
+        },
+    });
+}
+function renderHarness(props) {
+    if (!container) {
+        container = document.createElement('div');
+        document.body.appendChild(container);
+        root = createRoot(container);
+    }
+    act(() => {
+        root?.render(createElement(Harness, props));
+    });
+    return container;
+}
+function getTagTexts(el) {
+    return Array.from(el.querySelectorAll('.ncua-combobox__tags .ncua-tag .ncua-tag__text')).map((node) => node.textContent ?? '');
+}
+function getCloseButtons(el) {
+    return Array.from(el.querySelectorAll('.ncua-combobox__tags .ncua-tag__close'));
+}
+function click(target) {
+    if (!target)
+        throw new Error('클릭 대상을 찾을 수 없습니다');
+    act(() => {
+        target.click();
+    });
+}
+/** 「전체」 버튼으로 드롭다운을 연다 (입력값이 없어도 전체 목록 표시). */
+function openDropdown(el) {
+    click(el.querySelector('.ncua-input__right-icon'));
+}
+function clickOption(el, label) {
+    const option = Array.from(el.querySelectorAll('.ncua-select-dropdown__option')).find((node) => node.textContent === label);
+    click(option);
+}
+function clickButton(el, label) {
+    const button = Array.from(el.querySelectorAll('button')).find((node) => node.textContent?.includes(label));
+    click(button);
+}
+afterEach(() => {
+    act(() => {
+        root?.unmount();
+    });
+    container?.remove();
+    root = null;
+    container = null;
+});
+describe('ComboBox — 단일 모드 외부 value Tag', () => {
+    it('S-01: value에 해당하는 옵션이 있으면 Tag 1개를 라벨로 표시한다', () => {
+        const el = render({ value: 1, optionItems: OPTIONS });
+        expect(getTagTexts(el)).toEqual(['사과']);
+    });
+    it('S-02: optionItems가 늦게 도착하면 도착 시 Tag를 표시한다', () => {
+        const el = render({ value: 1, optionItems: [] });
+        expect(getTagTexts(el)).toEqual([]);
+        render({ value: 1, optionItems: OPTIONS });
+        expect(getTagTexts(el)).toEqual(['사과']);
+    });
+    it.each([
+        ['빈 문자열', ''],
+        ['undefined', undefined],
+        ['null', null],
+    ])('S-03: value가 %s이면 Tag를 표시하지 않는다', (_, value) => {
+        const el = render({ value: value, optionItems: OPTIONS });
+        expect(el.querySelector('.ncua-combobox__tags')).toBeNull();
+    });
+    it.each([
+        ['빈 문자열', ''],
+        ['undefined', undefined],
+    ])('S-04: Tag 표시 중 value가 %s로 바뀌면 Tag가 사라진다', (_, value) => {
+        const el = render({ value: 1, optionItems: OPTIONS });
+        expect(getTagTexts(el)).toEqual(['사과']);
+        render({ value, optionItems: OPTIONS });
+        expect(el.querySelector('.ncua-combobox__tags')).toBeNull();
+    });
+    it('S-05: 검색 필터로 optionItems에서 선택 항목이 빠져도 같은 라벨로 Tag를 유지한다', () => {
+        const el = render({ value: 1, optionItems: OPTIONS });
+        expect(getTagTexts(el)).toEqual(['사과']);
+        render({ value: 1, optionItems: FILTERED_OPTIONS });
+        expect(getTagTexts(el)).toEqual(['사과']);
+    });
+    it('S-06: 목록에 없는 다른 id로 바뀌면 이전 라벨을 쓰지 않고 Tag를 표시하지 않는다', () => {
+        const el = render({ value: 1, optionItems: OPTIONS });
+        expect(getTagTexts(el)).toEqual(['사과']);
+        render({ value: MISSING_ID, optionItems: OPTIONS });
+        expect(el.querySelector('.ncua-combobox__tags')).toBeNull();
+    });
+    it('S-07: value가 다른 id로 바뀌면 그 id의 라벨로 Tag를 바꾼다', () => {
+        const el = render({ value: 1, optionItems: OPTIONS });
+        render({ value: 2, optionItems: OPTIONS });
+        expect(getTagTexts(el)).toEqual(['바나나']);
+    });
+    it('S-08: disabled면 Tag는 표시하고 X 버튼은 표시하지 않는다', () => {
+        const el = render({ value: 1, optionItems: OPTIONS, disabled: true });
+        expect(getTagTexts(el)).toEqual(['사과']);
+        expect(getCloseButtons(el)).toHaveLength(0);
+    });
+    it('S-09: value가 0이어도 빈 값으로 보지 않고 Tag를 표시한다', () => {
+        const el = render({ value: 0, optionItems: [{ id: 0, label: '없음' }, ...OPTIONS] });
+        expect(getTagTexts(el)).toEqual(['없음']);
+    });
+    it.each([
+        [0, '0'],
+        [null, ''],
+    ])('S-12: register 사용 시 value가 %s이면 hidden input 값은 %j이다 (Tag 표시 규칙과 같게 0은 값으로 본다)', (value, expected) => {
+        const register = { name: 'item', onChange: vi.fn(), onBlur: vi.fn(), ref: vi.fn() };
+        const el = render({ value, register, optionItems: [{ id: 0, label: '없음' }, ...OPTIONS] });
+        expect(el.querySelector('input[type="hidden"]')?.value).toBe(expected);
+    });
+    it('S-10 (회귀): 옵션을 클릭하면 onChange(id)를 호출하고 Tag를 표시한다', () => {
+        const onChangeSpy = vi.fn();
+        const el = renderHarness({ initialValue: '', onChangeSpy, optionItems: OPTIONS });
+        openDropdown(el);
+        clickOption(el, '바나나');
+        expect(onChangeSpy).toHaveBeenCalledWith(2);
+        expect(getTagTexts(el)).toEqual(['바나나']);
+    });
+    it('S-11 (회귀): X를 클릭하면 onChange("")를 호출하고 Tag가 사라진다', () => {
+        const onChangeSpy = vi.fn();
+        const el = renderHarness({ initialValue: 1, onChangeSpy, optionItems: OPTIONS });
+        click(getCloseButtons(el)[0]);
+        expect(onChangeSpy).toHaveBeenCalledWith('');
+        expect(el.querySelector('.ncua-combobox__tags')).toBeNull();
+    });
+});
+describe('ComboBox — multiple 모드 외부 value Tag', () => {
+    it('M-01: value 배열에 해당하는 Tag를 모두 표시한다', () => {
+        const el = render({ multiple: true, value: [1, 2], optionItems: OPTIONS });
+        expect(getTagTexts(el)).toEqual(['사과', '바나나']);
+    });
+    it('M-02: optionItems가 늦게 도착하면 도착 시 Tag를 표시한다', () => {
+        const el = render({ multiple: true, value: [1, 2], optionItems: [] });
+        expect(getTagTexts(el)).toEqual([]);
+        render({ multiple: true, value: [1, 2], optionItems: OPTIONS });
+        expect(getTagTexts(el)).toEqual(['사과', '바나나']);
+    });
+    it.each([
+        ['빈 배열', []],
+        ['undefined', undefined],
+        ['null', null],
+    ])('M-03: value가 %s이면 Tag를 표시하지 않는다', (_, value) => {
+        const el = render({ multiple: true, value: value, optionItems: OPTIONS });
+        expect(el.querySelector('.ncua-combobox__tags')).toBeNull();
+    });
+    it.each([
+        ['빈 배열', []],
+        ['undefined', undefined],
+    ])('M-04: Tag 표시 중 value가 %s로 바뀌면 Tag가 사라진다', (_, value) => {
+        const el = render({ multiple: true, value: [1, 2], optionItems: OPTIONS });
+        expect(getTagTexts(el)).toEqual(['사과', '바나나']);
+        render({ multiple: true, value, optionItems: OPTIONS });
+        expect(el.querySelector('.ncua-combobox__tags')).toBeNull();
+    });
+    it('M-05: 바깥에서 value를 바꾸면(reset) 새 value로 Tag를 다시 그린다', () => {
+        const el = render({ multiple: true, value: [1, 2], optionItems: OPTIONS });
+        render({ multiple: true, value: [RESET_ID], optionItems: OPTIONS });
+        expect(getTagTexts(el)).toEqual(['체리']);
+    });
+    it('M-06: 검색 필터로 optionItems에서 선택 항목이 빠져도 Tag를 유지한다', () => {
+        const el = render({ multiple: true, value: [1, 2], optionItems: OPTIONS });
+        render({ multiple: true, value: [1, 2], optionItems: FILTERED_OPTIONS });
+        expect(getTagTexts(el)).toEqual(['사과', '바나나']);
+    });
+    it('M-07: disabled면 Tag는 표시하고 X 버튼은 표시하지 않는다', () => {
+        const el = render({ multiple: true, value: [1], optionItems: OPTIONS, disabled: true });
+        expect(getTagTexts(el)).toEqual(['사과']);
+        expect(getCloseButtons(el)).toHaveLength(0);
+    });
+    it('M-08 (회귀): 옵션을 클릭하면 onChange만 호출하고 Tag는 「선택 완료」 전까지 그대로다', () => {
+        const onChangeSpy = vi.fn();
+        const el = renderHarness({ multiple: true, initialValue: [1], onChangeSpy, optionItems: OPTIONS });
+        expect(getTagTexts(el)).toEqual(['사과']);
+        openDropdown(el);
+        clickOption(el, '바나나');
+        expect(onChangeSpy).toHaveBeenCalledWith([1, 2]);
+        expect(getTagTexts(el)).toEqual(['사과']);
+    });
+    it('M-09 (회귀): 옵션 클릭 후 「선택 완료」를 누르면 Tag를 반영하고 onComplete를 호출한다', () => {
+        const onChangeSpy = vi.fn();
+        const onComplete = vi.fn();
+        const el = renderHarness({ multiple: true, initialValue: [1], onChangeSpy, onComplete, optionItems: OPTIONS });
+        openDropdown(el);
+        clickOption(el, '바나나');
+        clickButton(el, '선택 완료');
+        expect(getTagTexts(el)).toEqual(['사과', '바나나']);
+        expect(onComplete).toHaveBeenCalledWith([1, 2]);
+    });
+    it('M-10 (회귀): X를 클릭하면 onChange(남은 배열)를 호출하고 해당 Tag만 제거한다', () => {
+        const onChangeSpy = vi.fn();
+        const el = renderHarness({ multiple: true, initialValue: [1, 2], onChangeSpy, optionItems: OPTIONS });
+        click(getCloseButtons(el)[0]);
+        expect(onChangeSpy).toHaveBeenCalledWith([2]);
+        expect(getTagTexts(el)).toEqual(['바나나']);
+    });
+    it('M-11 (회귀): 「전체 선택」을 누르면 onChange(전체 id)만 호출하고 Tag는 그대로다', () => {
+        const onChangeSpy = vi.fn();
+        const el = renderHarness({ multiple: true, initialValue: [], onChangeSpy, optionItems: OPTIONS });
+        openDropdown(el);
+        clickButton(el, '전체 선택');
+        expect(onChangeSpy).toHaveBeenCalledWith(ALL_IDS);
+        expect(el.querySelector('.ncua-combobox__tags')).toBeNull();
+    });
+    it('M-12: 클릭으로 고른 값과 같은 값을 바깥에서 비웠다가 다시 넣어도 Tag를 표시한다', () => {
+        const props = { multiple: true, optionItems: OPTIONS, onChange: vi.fn() };
+        const el = render({ ...props, value: [] });
+        openDropdown(el);
+        clickOption(el, '사과');
+        render({ ...props, value: [1] });
+        clickButton(el, '선택 완료');
+        expect(getTagTexts(el)).toEqual(['사과']);
+        render({ ...props, value: [] });
+        expect(getTagTexts(el)).toEqual([]);
+        render({ ...props, value: [1] });
+        expect(getTagTexts(el)).toEqual(['사과']);
+    });
+    it('M-13 (회귀): 클릭 후 「선택 완료」 전에 optionItems가 바뀌어도(검색) Tag는 그대로다', () => {
+        const onChangeSpy = vi.fn();
+        const el = renderHarness({ multiple: true, initialValue: [1], onChangeSpy, optionItems: OPTIONS });
+        openDropdown(el);
+        clickOption(el, '바나나');
+        renderHarness({ multiple: true, initialValue: [1], onChangeSpy, optionItems: FILTERED_OPTIONS });
+        expect(onChangeSpy).toHaveBeenCalledWith([1, 2]);
+        expect(getTagTexts(el)).toEqual(['사과']);
+    });
+    it('M-14 (회귀): 「선택 완료」 전에 클릭한 항목이 있을 때 X를 누르면 그 Tag만 빠지고 클릭한 항목은 확정되지 않는다', () => {
+        const onChangeSpy = vi.fn();
+        const el = renderHarness({ multiple: true, initialValue: [1], onChangeSpy, optionItems: OPTIONS });
+        openDropdown(el);
+        clickOption(el, '바나나');
+        click(getCloseButtons(el)[0]);
+        expect(onChangeSpy).toHaveBeenLastCalledWith([2]);
+        expect(el.querySelector('.ncua-combobox__tags')).toBeNull();
+    });
+    it('M-15 (회귀): 사용처가 onChange 값의 순서를 바꿔 돌려줘도 「선택 완료」 전에는 Tag가 그대로다', () => {
+        const onChangeSpy = vi.fn();
+        const sortIds = (value) => (Array.isArray(value) ? [...value].sort() : value);
+        const el = renderHarness({
+            multiple: true,
+            initialValue: [RESET_ID],
+            onChangeSpy,
+            transform: sortIds,
+            optionItems: OPTIONS,
+        });
+        openDropdown(el);
+        clickOption(el, '사과');
+        expect(onChangeSpy).toHaveBeenCalledWith([RESET_ID, 1]);
+        expect(getTagTexts(el)).toEqual(['체리']);
+    });
+});