@ncds/ui-admin 1.8.28-alpha.0 → 1.8.28-alpha.2

package/dist/esm/src/components/forms-and-input/select-box/__tests__/SelectBox.test.js

@@ -0,0 +1,1332 @@
+// @vitest-environment jsdom
+//
+// SelectBox (React) 인라인 패널 위험 경로 — 위험 목록표 SB-xx.
+// 포털·방향·autoWidth 는 전역 stub 이 파일 전체에 걸리므로 SelectBox.portal.test.ts 로 분리한다.
+// useDropdown·useScrollLock·useMultiSelect 는 mock 하지 않는다 — 관찰 결과가 이 훅들의 조합이다.
+// react-hook-form 은 타입만 쓰이므로 UseFormRegisterReturn 모양의 가짜 객체로 대체한다.
+import { createElement, createRef, Fragment } from 'react';
+import { createRoot } from 'react-dom/client';
+import { act } from 'react-dom/test-utils';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { COLOR } from '../../../../../constant/color';
+import { SelectBox } from '../SelectBox';
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+/** 패널을 열 때 저장되는 페이지 스크롤 위치 — 닫힐 때 scrollTo 로 복원된다 */
+const SCROLL_Y_AT_OPEN = 120;
+/** wheel 방향 — 양수 아래, 음수 위 */
+const WHEEL_DOWN = 1;
+const WHEEL_UP = -1;
+/** 패널 안 스크롤 가능한 목록 — 전체 300, 보이는 영역 100 */
+const LIST_SCROLL_HEIGHT = 300;
+const LIST_CLIENT_HEIGHT = 100;
+const LIST_MIDDLE_SCROLL_TOP = 50;
+const LIST_BOTTOM_SCROLL_TOP = LIST_SCROLL_HEIGHT - LIST_CLIENT_HEIGHT;
+/** maxSelection 양수 제한 */
+const MAX_TWO = 2;
+/** maxSelection 비활성 값 — 음수·비정수 */
+const NEGATIVE_MAX = -3;
+const FRACTIONAL_MAX = 1.5;
+const OPTIONS = [{
+  id: 'a',
+  label: 'A'
+}, {
+  id: 'b',
+  label: 'B'
+}, {
+  id: 'c',
+  label: 'C'
+}];
+const ALL_IDS = OPTIONS.map(option => option.id);
+const createRegister = function () {
+  let name = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : 'category';
+  return {
+    name,
+    onChange: vi.fn(),
+    onBlur: vi.fn(),
+    ref: vi.fn()
+  };
+};
+let root = null;
+let container = null;
+const renderElement = element => {
+  if (!container) {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  }
+  act(() => {
+    root?.render(element);
+  });
+  return container;
+};
+/** 같은 root 에 다시 render 하면 props 변경(재렌더)이 된다 */
+const render = function () {
+  let props = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+  return renderElement(/*#__PURE__*/createElement(SelectBox, {
+    optionItems: OPTIONS,
+    ...props
+  }));
+};
+beforeEach(() => {
+  // jsdom 은 scrollTo 를 구현하지 않는다 (호출 시 not implemented 오류)
+  vi.spyOn(window, 'scrollTo').mockImplementation(() => undefined);
+});
+afterEach(() => {
+  if (root) {
+    act(() => {
+      root?.unmount();
+    });
+  }
+  root = null;
+  container = null;
+  document.body.innerHTML = '';
+  vi.useRealTimers();
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+});
+const requireElement = (scope, selector) => {
+  const element = scope.querySelector(selector);
+  if (!element) throw new Error(`요소를 찾을 수 없습니다: ${selector}`);
+  return element;
+};
+const rootOf = view => requireElement(view, '.ncua-selectbox');
+const triggerOf = view => requireElement(view, '.ncua-selectbox__content');
+const panelOf = view => view.querySelector('.ncua-select-dropdown');
+const valueTextOf = view => view.querySelector('.ncua-selectbox__value-text')?.textContent ?? null;
+const optionOf = (view, label) => {
+  const option = Array.from(view.querySelectorAll('.ncua-select-dropdown__option')).find(element => element.textContent === label);
+  if (!option) throw new Error(`옵션이 없습니다: ${label}`);
+  return option;
+};
+const buttonOf = (view, text) => Array.from(view.querySelectorAll('button')).find(button => button.textContent === text) ?? null;
+const requireButton = (view, text) => {
+  const button = buttonOf(view, text);
+  if (!button) throw new Error(`버튼이 없습니다: ${text}`);
+  return button;
+};
+const tagTextsOf = view => Array.from(view.querySelectorAll('.ncua-tag__text')).map(element => element.textContent ?? '');
+const tagCloseOf = (view, label) => {
+  const tag = Array.from(view.querySelectorAll('.ncua-tag')).find(element => element.querySelector('.ncua-tag__text')?.textContent === label);
+  if (!tag) throw new Error(`태그가 없습니다: ${label}`);
+  return requireElement(tag, '.ncua-tag__close');
+};
+const click = element => {
+  act(() => {
+    element.click();
+  });
+};
+const keyDown = (element, key) => {
+  const event = new KeyboardEvent('keydown', {
+    key,
+    bubbles: true,
+    cancelable: true
+  });
+  act(() => {
+    element.dispatchEvent(event);
+  });
+  return event;
+};
+const mouseDown = element => {
+  act(() => {
+    element.dispatchEvent(new MouseEvent('mousedown', {
+      bubbles: true
+    }));
+  });
+};
+const wheel = function (element) {
+  let deltaY = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : WHEEL_DOWN;
+  const event = new WheelEvent('wheel', {
+    bubbles: true,
+    cancelable: true,
+    deltaY
+  });
+  act(() => {
+    element.dispatchEvent(event);
+  });
+  return event;
+};
+const touchMove = element => {
+  const event = new TouchEvent('touchmove', {
+    bubbles: true,
+    cancelable: true
+  });
+  act(() => {
+    element.dispatchEvent(event);
+  });
+  return event;
+};
+const open = view => {
+  click(triggerOf(view));
+};
+const defineValue = (element, key, value) => {
+  Object.defineProperty(element, key, {
+    configurable: true,
+    writable: true,
+    value
+  });
+};
+const makeScrollable = function (element) {
+  let {
+    overflowY = 'auto',
+    scrollHeight = LIST_SCROLL_HEIGHT
+  } = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+  element.style.overflowY = overflowY;
+  defineValue(element, 'scrollHeight', scrollHeight);
+  defineValue(element, 'clientHeight', LIST_CLIENT_HEIGHT);
+};
+// ── P0 ─────────────────────────────────────────────────
+describe('SelectBox — 단일 선택 (SB-01)', () => {
+  it('SB-01 옵션 click 은 onChange(id) 를 1회 부르고 register.onChange 에 value·name 을 넘긴 뒤 패널을 닫는다', () => {
+    const onChange = vi.fn();
+    const register = createRegister();
+    const view = render({
+      onChange,
+      register
+    });
+    open(view);
+    expect(panelOf(view)).not.toBeNull();
+    click(optionOf(view, 'B'));
+    expect(onChange).toHaveBeenCalledTimes(1);
+    expect(onChange).toHaveBeenCalledWith('b');
+    expect(register.onChange).toHaveBeenCalledTimes(1);
+    expect(register.onChange).toHaveBeenCalledWith({
+      target: {
+        value: 'b',
+        name: 'category'
+      }
+    });
+    expect(panelOf(view)).toBeNull();
+    expect(triggerOf(view).getAttribute('aria-expanded')).toBe('false');
+  });
+  it('SB-01 선택된 value 로 재렌더하면 트리거에 선택 라벨이 표시되고 aria-label 도 라벨이 된다', () => {
+    const view = render({
+      value: 'b',
+      onChange: vi.fn()
+    });
+    expect(valueTextOf(view)).toBe('B');
+    expect(triggerOf(view).getAttribute('aria-label')).toBe('B');
+  });
+  it('SB-01 단일 모드 옵션 click 후 패널이 닫힌 상태로 남는다', () => {
+    const view = render({
+      onChange: vi.fn()
+    });
+    open(view);
+    click(optionOf(view, 'A'));
+    expect(panelOf(view)).toBeNull();
+    expect(rootOf(view).classList.contains('ncua-selectbox--open')).toBe(false);
+  });
+  it('SB-01 onChange·register 가 없어도 옵션 click 은 오류 없이 패널을 닫는다', () => {
+    const view = render();
+    open(view);
+    click(optionOf(view, 'A'));
+    expect(panelOf(view)).toBeNull();
+  });
+});
+describe('SelectBox — 다중 선택 (SB-02)', () => {
+  it('SB-02 미포함 옵션 click 은 끝에 추가한 배열로 onChange, register 에는 JSON 문자열을 넘기고 패널은 열린 채다', () => {
+    const onChange = vi.fn();
+    const register = createRegister('tags');
+    const view = render({
+      multiple: true,
+      value: ['c'],
+      onChange,
+      register
+    });
+    open(view);
+    click(optionOf(view, 'A'));
+    expect(onChange).toHaveBeenCalledWith(['c', 'a']);
+    expect(register.onChange).toHaveBeenCalledWith({
+      target: {
+        value: '["c","a"]',
+        name: 'tags'
+      }
+    });
+    expect(panelOf(view)).not.toBeNull();
+  });
+  it('SB-02 포함된 옵션 click 은 그 id 를 제거한 배열로 onChange 를 부른다', () => {
+    const onChange = vi.fn();
+    const view = render({
+      multiple: true,
+      value: ['a', 'b'],
+      onChange
+    });
+    open(view);
+    click(optionOf(view, 'A'));
+    expect(onChange).toHaveBeenCalledWith(['b']);
+    expect(panelOf(view)).not.toBeNull();
+  });
+  it('SB-02 value 가 배열이 아니면 빈 배열 기준으로 추가한다', () => {
+    const onChange = vi.fn();
+    const view = render({
+      multiple: true,
+      value: 'a',
+      onChange
+    });
+    open(view);
+    click(optionOf(view, 'B'));
+    expect(onChange).toHaveBeenCalledWith(['b']);
+  });
+  it('SB-02 선택된 옵션에 --selected 와 aria-selected=true 가 붙고 미선택 옵션에는 없다', () => {
+    const view = render({
+      multiple: true,
+      value: ['a', 'c'],
+      onChange: vi.fn()
+    });
+    open(view);
+    expect(optionOf(view, 'A').classList.contains('ncua-select-dropdown__option--selected')).toBe(true);
+    expect(optionOf(view, 'A').getAttribute('aria-selected')).toBe('true');
+    expect(optionOf(view, 'C').classList.contains('ncua-select-dropdown__option--selected')).toBe(true);
+    expect(optionOf(view, 'C').getAttribute('aria-selected')).toBe('true');
+    expect(optionOf(view, 'B').classList.contains('ncua-select-dropdown__option--selected')).toBe(false);
+    expect(optionOf(view, 'B').getAttribute('aria-selected')).toBe('false');
+  });
+});
+describe('SelectBox — maxSelection (SB-03)', () => {
+  it('SB-03 도달하면 미선택 옵션 click 은 무시되어 onChange·register.onChange 가 호출되지 않는다', () => {
+    const onChange = vi.fn();
+    const register = createRegister();
+    const view = render({
+      multiple: true,
+      maxSelection: MAX_TWO,
+      value: ['a', 'b'],
+      onChange,
+      register
+    });
+    open(view);
+    click(optionOf(view, 'C'));
+    expect(onChange).not.toHaveBeenCalled();
+    expect(register.onChange).not.toHaveBeenCalled();
+    expect(panelOf(view)).not.toBeNull();
+  });
+  it('SB-03 도달해도 이미 선택된 옵션의 해제는 정상 동작한다', () => {
+    const onChange = vi.fn();
+    const view = render({
+      multiple: true,
+      maxSelection: MAX_TWO,
+      value: ['a', 'b'],
+      onChange
+    });
+    open(view);
+    click(optionOf(view, 'A'));
+    expect(onChange).toHaveBeenCalledWith(['b']);
+  });
+  it('SB-03 도달 전에는 추가가 허용된다', () => {
+    const onChange = vi.fn();
+    const view = render({
+      multiple: true,
+      maxSelection: MAX_TWO,
+      value: ['a'],
+      onChange
+    });
+    open(view);
+    click(optionOf(view, 'B'));
+    expect(onChange).toHaveBeenCalledWith(['a', 'b']);
+  });
+  it('SB-03 maxSelection 0 은 모든 추가를 차단한다', () => {
+    const onChange = vi.fn();
+    const view = render({
+      multiple: true,
+      maxSelection: 0,
+      value: [],
+      onChange
+    });
+    open(view);
+    click(optionOf(view, 'A'));
+    expect(onChange).not.toHaveBeenCalled();
+  });
+  it('SB-03 제한이 활성(0 이상 정수)이면 전체 선택 링크를 숨기고 편집·선택 완료 버튼은 남긴다', () => {
+    const view = render({
+      multiple: true,
+      maxSelection: MAX_TWO,
+      value: [],
+      onChange: vi.fn()
+    });
+    open(view);
+    expect(buttonOf(view, '전체 선택')).toBeNull();
+    expect(buttonOf(view, '편집')).not.toBeNull();
+    expect(buttonOf(view, '선택 완료')).not.toBeNull();
+  });
+  it.each([['음수', NEGATIVE_MAX], ['비정수', FRACTIONAL_MAX], ['null', null]])('SB-03 maxSelection 이 %s 이면 무제한 — 전체 선택 링크가 보이고 추가가 막히지 않는다', (_, maxSelection) => {
+    const onChange = vi.fn();
+    const view = render({
+      multiple: true,
+      maxSelection,
+      value: ['a', 'b'],
+      onChange
+    });
+    open(view);
+    click(optionOf(view, 'C'));
+    expect(buttonOf(view, '전체 선택')).not.toBeNull();
+    expect(onChange).toHaveBeenCalledWith(['a', 'b', 'c']);
+  });
+});
+describe('SelectBox — disabled·readOnly (SB-04)', () => {
+  it('SB-04 disabled 는 click 으로 열리지 않는다', () => {
+    const view = render({
+      disabled: true
+    });
+    const trigger = triggerOf(view);
+    click(trigger);
+    expect(panelOf(view)).toBeNull();
+    expect(trigger.getAttribute('aria-expanded')).toBe('false');
+  });
+  it.each(['ArrowDown', 'Enter', ' '])('SB-04 disabled 는 "%s" 키로 열리지 않는다', key => {
+    const view = render({
+      disabled: true
+    });
+    const trigger = triggerOf(view);
+    keyDown(trigger, key);
+    expect(panelOf(view)).toBeNull();
+    expect(trigger.getAttribute('aria-expanded')).toBe('false');
+  });
+  it('SB-04 disabled 는 tabIndex -1·aria-disabled·--disabled 와 gray300 chevron 을 갖는다', () => {
+    const view = render({
+      disabled: true
+    });
+    const trigger = triggerOf(view);
+    expect(trigger.tabIndex).toBe(-1);
+    expect(trigger.getAttribute('aria-disabled')).toBe('true');
+    expect(rootOf(view).classList.contains('ncua-selectbox--disabled')).toBe(true);
+    expect(requireElement(view, '.ncua-selectbox__arrow').getAttribute('color')).toBe(COLOR.gray300);
+  });
+  it('SB-04 readOnly 는 click 으로 열리지 않는다', () => {
+    const view = render({
+      readOnly: true
+    });
+    click(triggerOf(view));
+    expect(panelOf(view)).toBeNull();
+  });
+  it.each(['ArrowDown', 'Enter'])('SB-04 readOnly 는 "%s" 키로 열리지 않는다', key => {
+    const view = render({
+      readOnly: true
+    });
+    keyDown(triggerOf(view), key);
+    expect(panelOf(view)).toBeNull();
+  });
+  it('SB-04 readOnly 는 tabIndex 0·aria-readonly·--readonly 를 갖는다', () => {
+    const view = render({
+      readOnly: true
+    });
+    const trigger = triggerOf(view);
+    expect(trigger.tabIndex).toBe(0);
+    expect(trigger.getAttribute('aria-readonly')).toBe('true');
+    expect(trigger.getAttribute('aria-disabled')).toBe('false');
+    expect(rootOf(view).classList.contains('ncua-selectbox--readonly')).toBe(true);
+    expect(rootOf(view).classList.contains('ncua-selectbox--disabled')).toBe(false);
+    expect(requireElement(view, '.ncua-selectbox__arrow').getAttribute('color')).toBe(COLOR.gray500);
+  });
+});
+describe('SelectBox — 스크롤 잠금 (SB-05)', () => {
+  const openLocked = function () {
+    let props = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+    vi.stubGlobal('pageYOffset', SCROLL_Y_AT_OPEN);
+    const view = render({
+      onChange: vi.fn(),
+      ...props
+    });
+    open(view);
+    return view;
+  };
+  it('SB-05 열린 동안 패널 밖 wheel·touchmove 는 preventDefault 된다', () => {
+    openLocked();
+    expect(wheel(document.body).defaultPrevented).toBe(true);
+    expect(touchMove(document.body).defaultPrevented).toBe(true);
+  });
+  it.each(['PageUp', 'PageDown', 'Home', 'End', ' '])('SB-05 열린 동안 패널 밖 스크롤 키 "%s" 는 preventDefault 된다', key => {
+    openLocked();
+    expect(keyDown(document.body, key).defaultPrevented).toBe(true);
+  });
+  it('SB-05 스크롤 키가 아닌 키는 패널 밖이어도 막지 않는다', () => {
+    openLocked();
+    expect(keyDown(document.body, 'a').defaultPrevented).toBe(false);
+  });
+  it('SB-05 닫혀 있을 때는 wheel·스크롤 키를 막지 않는다', () => {
+    render();
+    expect(wheel(document.body).defaultPrevented).toBe(false);
+    expect(keyDown(document.body, 'PageDown').defaultPrevented).toBe(false);
+  });
+  it.each([['옵션 선택', view => click(optionOf(view, 'A'))], ['Escape', view => keyDown(triggerOf(view), 'Escape')], ['바깥 mousedown', () => mouseDown(document.body)], ['트리거 재클릭', view => click(triggerOf(view))]])('SB-05 %s 로 닫히면 잠금이 해제되고 scrollTo(0, 열 때 위치) 로 복원한다', (_, close) => {
+    const view = openLocked();
+    close(view);
+    expect(panelOf(view)).toBeNull();
+    expect(window.scrollTo).toHaveBeenCalledWith(0, SCROLL_Y_AT_OPEN);
+    expect(wheel(document.body).defaultPrevented).toBe(false);
+    expect(keyDown(document.body, 'PageDown').defaultPrevented).toBe(false);
+  });
+  it('SB-05 열린 채 언마운트되면 잠금이 해제되고 scrollTo 로 복원한다', () => {
+    openLocked();
+    act(() => {
+      root?.unmount();
+    });
+    root = null;
+    expect(window.scrollTo).toHaveBeenCalledWith(0, SCROLL_Y_AT_OPEN);
+    expect(wheel(document.body).defaultPrevented).toBe(false);
+  });
+  it('SB-05 패널 안이라도 스크롤 가능한 요소가 없으면 wheel·touchmove 를 막는다', () => {
+    const view = openLocked();
+    expect(wheel(optionOf(view, 'A')).defaultPrevented).toBe(true);
+    expect(touchMove(optionOf(view, 'A')).defaultPrevented).toBe(true);
+  });
+  it('SB-05 패널 안 스크롤 가능한 목록은 중간에서 wheel 을 허용하고 위·아래 끝을 넘는 방향만 막는다', () => {
+    const view = openLocked();
+    const list = requireElement(view, '.ncua-select-dropdown__options');
+    makeScrollable(list);
+    const setScrollTop = value => defineValue(list, 'scrollTop', value);
+    const option = optionOf(view, 'B');
+    setScrollTop(LIST_MIDDLE_SCROLL_TOP);
+    expect(wheel(option, WHEEL_DOWN).defaultPrevented).toBe(false);
+    expect(wheel(option, WHEEL_UP).defaultPrevented).toBe(false);
+    setScrollTop(0);
+    expect(wheel(option, WHEEL_UP).defaultPrevented).toBe(true);
+    expect(wheel(option, WHEEL_DOWN).defaultPrevented).toBe(false);
+    setScrollTop(LIST_BOTTOM_SCROLL_TOP);
+    expect(wheel(option, WHEEL_DOWN).defaultPrevented).toBe(true);
+    expect(wheel(option, WHEEL_UP).defaultPrevented).toBe(false);
+  });
+  it('SB-05 패널 안 스크롤 가능한 목록의 touchmove 는 막지 않는다', () => {
+    const view = openLocked();
+    const list = requireElement(view, '.ncua-select-dropdown__options');
+    makeScrollable(list, {
+      overflowY: 'scroll'
+    });
+    expect(touchMove(optionOf(view, 'B')).defaultPrevented).toBe(false);
+  });
+  it('SB-05 패널 루트 자체가 스크롤 가능하면 그 경계로 판정한다', () => {
+    const view = openLocked();
+    const panel = panelOf(view);
+    if (!panel) throw new Error('패널이 없습니다');
+    makeScrollable(panel);
+    defineValue(panel, 'scrollTop', 0);
+    expect(wheel(optionOf(view, 'A'), WHEEL_UP).defaultPrevented).toBe(true);
+    expect(wheel(optionOf(view, 'A'), WHEEL_DOWN).defaultPrevented).toBe(false);
+  });
+  it('SB-05 스크롤 가능하지만 내용이 넘치지 않는 목록은 스크롤 요소로 보지 않아 막는다', () => {
+    const view = openLocked();
+    const list = requireElement(view, '.ncua-select-dropdown__options');
+    makeScrollable(list, {
+      scrollHeight: LIST_CLIENT_HEIGHT
+    });
+    expect(wheel(optionOf(view, 'A')).defaultPrevented).toBe(true);
+  });
+  it('SB-05 패널 안에서 누른 스크롤 키는 막지 않는다', () => {
+    const view = openLocked();
+    expect(keyDown(optionOf(view, 'A'), 'PageDown').defaultPrevented).toBe(false);
+  });
+});
+describe('SelectBox — 전체 선택 (SB-06)', () => {
+  it('SB-06 전체 선택은 옵션 전체 id 로 onChange 를 부른다', () => {
+    const onChange = vi.fn();
+    const view = render({
+      multiple: true,
+      value: ['b'],
+      onChange
+    });
+    open(view);
+    click(requireButton(view, '전체 선택'));
+    expect(onChange).toHaveBeenCalledWith(ALL_IDS);
+    expect(panelOf(view)).not.toBeNull();
+  });
+  it('SB-06 모두 선택된 상태면 문구가 "전체 해제" 이고 click 하면 [] 로 onChange 를 부른다', () => {
+    const onChange = vi.fn();
+    const view = render({
+      multiple: true,
+      value: ALL_IDS,
+      onChange
+    });
+    open(view);
+    expect(buttonOf(view, '전체 선택')).toBeNull();
+    click(requireButton(view, '전체 해제'));
+    expect(onChange).toHaveBeenCalledWith([]);
+  });
+  it('SB-06 onChange 가 없으면 전체 선택은 무반응이다 (오류·패널 변화 없음)', () => {
+    // 현재 동작 고정 — 결함 후보: #592 (register 만 넘기는 문서 예시 형태에서 전체 선택이 !onChange 조기 반환)
+    const register = createRegister();
+    const view = render({
+      multiple: true,
+      value: [],
+      register
+    });
+    open(view);
+    click(requireButton(view, '전체 선택'));
+    expect(register.onChange).not.toHaveBeenCalled();
+    expect(panelOf(view)).not.toBeNull();
+    expect(buttonOf(view, '전체 선택')).not.toBeNull();
+  });
+});
+describe('SelectBox — register 미통지 (SB-07)', () => {
+  it('SB-07 전체 선택은 onChange 만 부르고 register.onChange 를 부르지 않는다', () => {
+    // 현재 동작 고정 — 결함 후보: #592 (react-hook-form 값 유실, handleSelectAll 이 notifyRegister 미호출)
+    const onChange = vi.fn();
+    const register = createRegister();
+    const options = [{
+      id: 0,
+      label: '영'
+    }, ...OPTIONS.slice(0, 2)];
+    const view = render({
+      multiple: true,
+      value: [],
+      optionItems: options,
+      onChange,
+      register
+    });
+    open(view);
+    click(requireButton(view, '전체 선택'));
+    expect(onChange).toHaveBeenCalledWith([0, 'a', 'b']);
+    expect(register.onChange).not.toHaveBeenCalled();
+  });
+  it('SB-07 태그 제거는 onChange 만 부르고 register.onChange 를 부르지 않는다', () => {
+    // 현재 동작 고정 — 결함 후보: #592 (react-hook-form 값 유실, handleRemoveTag 가 notifyRegister 미호출)
+    const onChange = vi.fn();
+    const register = createRegister();
+    const view = render({
+      multiple: true,
+      value: ['a', 'b'],
+      onChange,
+      register
+    });
+    open(view);
+    click(requireButton(view, '선택 완료'));
+    click(tagCloseOf(view, 'A'));
+    expect(onChange).toHaveBeenCalledWith(['b']);
+    expect(tagTextsOf(view)).toEqual(['B']);
+    expect(register.onChange).not.toHaveBeenCalled();
+  });
+  it.todo('SB-07 전체 선택·해제는 다중 선택처럼 register.onChange 에 JSON 문자열 값을 넘긴다 (#592)');
+  it.todo('SB-07 태그 제거는 register.onChange 에 제거 후 배열의 JSON 문자열을 넘긴다 (#592)');
+  it.todo('SB-07 onChange 없이 register 만 있어도 전체 선택·태그 제거가 register.onChange 로 전달된다 (#592)');
+});
+// ── P1~P3 ──────────────────────────────────────────────
+/** useDropdownKeyboard 의 scrollToFocusedOption 지연 (Arrow) */
+const ARROW_SCROLL_DELAY_MS = 100;
+/** 옵션 기하 — 포커스 옵션이 목록 아래/위로 벗어난 상황을 만든다 */
+const OPTION_HEIGHT = 40;
+const OPTION_OFFSET_TOP_BELOW = 120;
+const OPTION_OFFSET_TOP_ABOVE = 0;
+const SCROLLED_LIST_TOP = 80;
+/** chevron 크기 — xs 14, 그 외 16 */
+const CHEVRON_XS = '14';
+const CHEVRON_SM = '16';
+const CUSTOM_MAX_HEIGHT = 200;
+const mouseOver = element => {
+  act(() => {
+    element.dispatchEvent(new MouseEvent('mouseover', {
+      bubbles: true
+    }));
+  });
+};
+const focusedLabelsOf = view => Array.from(view.querySelectorAll('.ncua-select-dropdown__option--focused')).map(element => element.textContent ?? '');
+const hiddenInputOf = view => view.querySelector('input[type="hidden"]');
+const stubBox = (element, _ref) => {
+  let {
+    top,
+    height
+  } = _ref;
+  vi.spyOn(element, 'getBoundingClientRect').mockReturnValue(DOMRect.fromRect({
+    x: 0,
+    y: top,
+    width: 0,
+    height
+  }));
+};
+/** multiple 로 열고 '선택 완료' 를 눌러 태그를 만든다 */
+const completeWithTags = props => {
+  const view = render({
+    multiple: true,
+    ...props
+  });
+  open(view);
+  click(requireButton(view, '선택 완료'));
+  return view;
+};
+describe('SelectBox — react-hook-form hidden input (SB-08)', () => {
+  it('SB-08 register 가 없으면 hidden input 을 렌더하지 않는다', () => {
+    const view = render({
+      value: 'a'
+    });
+    expect(hiddenInputOf(view)).toBeNull();
+  });
+  it('SB-08 단일 모드는 name 과 String(value) 를 갖는다', () => {
+    const register = createRegister();
+    const view = render({
+      value: 'b',
+      register
+    });
+    const input = hiddenInputOf(view);
+    expect(input?.name).toBe('category');
+    expect(input?.value).toBe('b');
+    expect(register.ref).toHaveBeenCalledWith(input);
+  });
+  it('SB-08 다중 모드는 JSON.stringify(value) 를 갖는다', () => {
+    const view = render({
+      multiple: true,
+      value: ['a', 'c'],
+      register: createRegister()
+    });
+    expect(hiddenInputOf(view)?.value).toBe('["a","c"]');
+  });
+  it("SB-08 value 가 없으면 단일 '' · 다중 '[]' 이다", () => {
+    const view = render({
+      register: createRegister()
+    });
+    expect(hiddenInputOf(view)?.value).toBe('');
+    render({
+      multiple: true,
+      register: createRegister()
+    });
+    expect(hiddenInputOf(view)?.value).toBe('[]');
+  });
+});
+describe('SelectBox — 선택 완료·태그·편집 (SB-09)', () => {
+  it('SB-09 선택 완료는 onComplete(value) 를 부르고 선택 라벨로 태그를 렌더한 뒤 닫는다', () => {
+    const onComplete = vi.fn();
+    const view = completeWithTags({
+      value: ['b', 'a'],
+      onComplete,
+      onChange: vi.fn()
+    });
+    expect(onComplete).toHaveBeenCalledWith(['b', 'a']);
+    expect(tagTextsOf(view)).toEqual(['B', 'A']);
+    expect(panelOf(view)).toBeNull();
+  });
+  it('SB-09 value 가 없으면 onComplete 에 [] 를 넘기고 태그를 렌더하지 않는다', () => {
+    const onComplete = vi.fn();
+    const view = completeWithTags({
+      onComplete
+    });
+    expect(onComplete).toHaveBeenCalledWith([]);
+    expect(view.querySelector('.ncua-selectbox__tags')).toBeNull();
+  });
+  it('SB-09 onComplete 가 없어도 태그를 렌더하고 닫으며, 옵션에 없는 id 는 태그에서 빠진다', () => {
+    const view = completeWithTags({
+      value: ['a', 'zz']
+    });
+    expect(tagTextsOf(view)).toEqual(['A']);
+    expect(panelOf(view)).toBeNull();
+  });
+  it('SB-09 라벨이 빈 옵션의 태그는 id 문자열로 표시된다', () => {
+    const view = completeWithTags({
+      value: ['x'],
+      optionItems: [{
+        id: 'x',
+        label: ''
+      }]
+    });
+    expect(tagTextsOf(view)).toEqual(['x']);
+  });
+  it('SB-09 태그 X 는 그 id 를 뺀 배열로 onChange 를 부르고 그 태그를 제거한다', () => {
+    const onChange = vi.fn();
+    const view = completeWithTags({
+      value: ['a', 'b', 'c'],
+      onChange
+    });
+    click(tagCloseOf(view, 'B'));
+    expect(onChange).toHaveBeenCalledWith(['a', 'c']);
+    expect(tagTextsOf(view)).toEqual(['A', 'C']);
+  });
+  it('SB-09 onChange 가 없으면 태그 X 를 눌러도 태그가 남는다', () => {
+    // 현재 동작 고정 — 결함 후보: #592 (register 만 넘기는 문서 예시 형태에서 태그 제거가 !onChange 조기 반환)
+    const view = completeWithTags({
+      value: ['a', 'b']
+    });
+    click(tagCloseOf(view, 'A'));
+    expect(tagTextsOf(view)).toEqual(['A', 'B']);
+  });
+  it('SB-09 편집은 onEdit 을 부르고 패널은 열린 채다', () => {
+    const onEdit = vi.fn();
+    const view = render({
+      multiple: true,
+      value: [],
+      onEdit
+    });
+    open(view);
+    click(requireButton(view, '편집'));
+    expect(onEdit).toHaveBeenCalledTimes(1);
+    expect(panelOf(view)).not.toBeNull();
+  });
+  it('SB-09 onEdit 이 없어도 편집 click 은 오류 없이 패널을 유지한다', () => {
+    const view = render({
+      multiple: true,
+      value: []
+    });
+    open(view);
+    click(requireButton(view, '편집'));
+    expect(panelOf(view)).not.toBeNull();
+  });
+});
+describe('SelectBox — 태그 스냅숏 (SB-10)', () => {
+  it('SB-10 선택 완료 후 외부에서 value 를 바꿔도 태그는 완료 시점 그대로다', () => {
+    // 현재 동작 고정 — 결함 후보: #593 (태그가 selectedTags state 스냅숏이라 value 변경을 따라가지 않음)
+    const onChange = vi.fn();
+    const view = completeWithTags({
+      value: ['a', 'b'],
+      onChange
+    });
+    render({
+      multiple: true,
+      value: [],
+      onChange
+    });
+    expect(tagTextsOf(view)).toEqual(['A', 'B']);
+  });
+  it.todo('SB-10 태그는 value 에서 파생되어 외부 value 변경(초기화 등)이 즉시 반영된다 (#593)');
+});
+describe('SelectBox — 키보드 탐색 (SB-11)', () => {
+  // Arrow 키가 등록하는 scrollToFocusedOption 타이머는 언마운트 때 해제되지 않아 다음 테스트로 새어 나간다
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+  it.each(['ArrowDown', 'ArrowUp', 'Enter', ' '])('SB-11 닫힌 상태에서 "%s" 는 패널을 연다', key => {
+    const view = render();
+    const event = keyDown(triggerOf(view), key);
+    expect(panelOf(view)).not.toBeNull();
+    expect(event.defaultPrevented).toBe(true);
+  });
+  it.each(['Home', 'End', 'Escape', 'Tab'])('SB-11 닫힌 상태의 "%s" 는 패널을 열지 않는다', key => {
+    const view = render();
+    keyDown(triggerOf(view), key);
+    expect(panelOf(view)).toBeNull();
+  });
+  it('SB-11 열린 상태 ArrowDown·ArrowUp 은 순환 이동하며 --focused·aria-activedescendant 를 옮긴다', () => {
+    const view = render({
+      id: 'sb'
+    });
+    const trigger = triggerOf(view);
+    open(view);
+    expect(trigger.getAttribute('aria-activedescendant')).toBeNull();
+    keyDown(trigger, 'ArrowDown');
+    expect(focusedLabelsOf(view)).toEqual(['A']);
+    expect(trigger.getAttribute('aria-activedescendant')).toBe('selectbox-options-sb-a');
+    keyDown(trigger, 'ArrowUp');
+    expect(focusedLabelsOf(view)).toEqual(['C']);
+    keyDown(trigger, 'ArrowDown');
+    expect(focusedLabelsOf(view)).toEqual(['A']);
+    expect(trigger.getAttribute('aria-activedescendant')).toBe('selectbox-options-sb-a');
+  });
+  it('SB-11 id 가 없으면 activedescendant 는 selectbox-options-default-{optionId} 다', () => {
+    const view = render();
+    open(view);
+    keyDown(triggerOf(view), 'ArrowDown');
+    expect(triggerOf(view).getAttribute('aria-activedescendant')).toBe('selectbox-options-default-a');
+  });
+  it('SB-11 Home·End 는 첫·마지막 옵션으로 포커스를 옮긴다', () => {
+    const view = render();
+    open(view);
+    const end = keyDown(triggerOf(view), 'End');
+    expect(focusedLabelsOf(view)).toEqual(['C']);
+    expect(end.defaultPrevented).toBe(true);
+    keyDown(triggerOf(view), 'Home');
+    expect(focusedLabelsOf(view)).toEqual(['A']);
+    act(() => {
+      vi.runAllTimers();
+    });
+    expect(panelOf(view)).not.toBeNull();
+  });
+  it.each(['Enter', ' '])('SB-11 단일 모드에서 포커스 옵션을 "%s" 로 선택하면 onChange 후 닫힌다', key => {
+    const onChange = vi.fn();
+    const view = render({
+      onChange
+    });
+    open(view);
+    keyDown(triggerOf(view), 'ArrowDown');
+    keyDown(triggerOf(view), 'ArrowDown');
+    keyDown(triggerOf(view), key);
+    expect(onChange).toHaveBeenCalledWith('b');
+    expect(panelOf(view)).toBeNull();
+  });
+  it('SB-11 다중 모드에서 Enter 로 선택하면 열린 채 유지된다', () => {
+    const onChange = vi.fn();
+    const view = render({
+      multiple: true,
+      value: [],
+      onChange
+    });
+    open(view);
+    keyDown(triggerOf(view), 'ArrowDown');
+    keyDown(triggerOf(view), 'Enter');
+    expect(onChange).toHaveBeenCalledWith(['a']);
+    expect(panelOf(view)).not.toBeNull();
+  });
+  it('SB-11 열렸지만 포커스 옵션이 없으면 Enter 는 선택하지 않고 열린 채다', () => {
+    const onChange = vi.fn();
+    const view = render({
+      onChange
+    });
+    open(view);
+    keyDown(triggerOf(view), 'Enter');
+    expect(onChange).not.toHaveBeenCalled();
+    expect(panelOf(view)).not.toBeNull();
+  });
+  it('SB-11 Escape 는 열린 패널을 닫고 기본 동작을 막는다', () => {
+    const view = render();
+    open(view);
+    const event = keyDown(triggerOf(view), 'Escape');
+    expect(panelOf(view)).toBeNull();
+    expect(event.defaultPrevented).toBe(true);
+  });
+  it('SB-11 옵션 hover 는 그 옵션으로 포커스를 옮긴다', () => {
+    const view = render();
+    open(view);
+    mouseOver(optionOf(view, 'C'));
+    expect(focusedLabelsOf(view)).toEqual(['C']);
+    expect(triggerOf(view).getAttribute('aria-activedescendant')).toBe('selectbox-options-default-c');
+  });
+  it('SB-11 Arrow 이동 뒤 지연 후 포커스 옵션이 목록 아래로 벗어나 있으면 목록을 아래로 스크롤한다', () => {
+    const view = render();
+    open(view);
+    keyDown(triggerOf(view), 'ArrowDown');
+    const list = requireElement(view, '.ncua-select-dropdown__options');
+    const option = optionOf(view, 'A');
+    stubBox(list, {
+      top: 0,
+      height: LIST_CLIENT_HEIGHT
+    });
+    stubBox(option, {
+      top: OPTION_OFFSET_TOP_BELOW,
+      height: OPTION_HEIGHT
+    });
+    defineValue(option, 'offsetTop', OPTION_OFFSET_TOP_BELOW);
+    defineValue(option, 'offsetHeight', OPTION_HEIGHT);
+    defineValue(list, 'clientHeight', LIST_CLIENT_HEIGHT);
+    defineValue(list, 'scrollTop', 0);
+    act(() => {
+      vi.advanceTimersByTime(ARROW_SCROLL_DELAY_MS);
+    });
+    expect(list.scrollTop).toBe(OPTION_OFFSET_TOP_BELOW + OPTION_HEIGHT - LIST_CLIENT_HEIGHT);
+  });
+  it('SB-11 포커스 옵션이 목록 위로 벗어나 있으면 그 옵션의 offsetTop 으로 스크롤한다', () => {
+    const view = render();
+    open(view);
+    keyDown(triggerOf(view), 'ArrowDown');
+    const list = requireElement(view, '.ncua-select-dropdown__options');
+    const option = optionOf(view, 'A');
+    stubBox(list, {
+      top: SCROLLED_LIST_TOP,
+      height: LIST_CLIENT_HEIGHT
+    });
+    stubBox(option, {
+      top: 0,
+      height: OPTION_HEIGHT
+    });
+    defineValue(option, 'offsetTop', OPTION_OFFSET_TOP_ABOVE);
+    defineValue(list, 'scrollTop', SCROLLED_LIST_TOP);
+    act(() => {
+      vi.advanceTimersByTime(ARROW_SCROLL_DELAY_MS);
+    });
+    expect(list.scrollTop).toBe(OPTION_OFFSET_TOP_ABOVE);
+  });
+});
+describe('SelectBox — 열기·닫기 (SB-12)', () => {
+  it('SB-12 트리거 재클릭은 패널을 토글한다', () => {
+    const view = render();
+    open(view);
+    expect(panelOf(view)).not.toBeNull();
+    click(triggerOf(view));
+    expect(panelOf(view)).toBeNull();
+    open(view);
+    expect(panelOf(view)).not.toBeNull();
+  });
+  it('SB-12 바깥 mousedown 은 패널을 닫는다', () => {
+    const view = render();
+    const outside = document.createElement('button');
+    document.body.appendChild(outside);
+    open(view);
+    mouseDown(outside);
+    expect(panelOf(view)).toBeNull();
+  });
+  it('SB-12 트리거·패널 안 mousedown 은 패널을 유지한다', () => {
+    const view = render();
+    open(view);
+    mouseDown(triggerOf(view));
+    mouseDown(optionOf(view, 'B'));
+    expect(panelOf(view)).not.toBeNull();
+  });
+});
+describe('SelectBox — 열린 채 disabled 전환 (SB-15)', () => {
+  it('SB-15 열린 채 disabled 로 바뀌면 패널·스크롤 잠금이 유지되고 Escape·트리거 click 으로 닫히지 않는다', () => {
+    // 현재 동작 고정 — 결함 후보: #593 (vanilla setDisabled 는 닫음, React 는 열린 상태를 유지)
+    const view = render({
+      onChange: vi.fn()
+    });
+    open(view);
+    render({
+      onChange: vi.fn(),
+      disabled: true
+    });
+    keyDown(triggerOf(view), 'Escape');
+    click(triggerOf(view));
+    expect(panelOf(view)).not.toBeNull();
+    expect(rootOf(view).classList.contains('ncua-selectbox--disabled')).toBe(true);
+    expect(wheel(document.body).defaultPrevented).toBe(true);
+  });
+  it('SB-15 단일 모드는 열린 채 disabled 면 옵션 click 이 onChange 를 부르지 않고 패널만 닫는다', () => {
+    const onChange = vi.fn();
+    const view = render({
+      onChange
+    });
+    open(view);
+    render({
+      onChange,
+      disabled: true
+    });
+    click(optionOf(view, 'A'));
+    expect(onChange).not.toHaveBeenCalled();
+    expect(panelOf(view)).toBeNull();
+  });
+  it('SB-15 다중 모드는 열린 채 disabled 면 옵션 click 이 onChange 를 부르지 않고 패널이 열린 채다', () => {
+    // 현재 동작 고정 — 결함 후보: #593 (disabled 패널이 남아 다중 모드는 바깥 mousedown 전까지 잠금 유지)
+    const onChange = vi.fn();
+    const view = render({
+      onChange,
+      multiple: true,
+      value: []
+    });
+    open(view);
+    render({
+      onChange,
+      multiple: true,
+      value: [],
+      disabled: true
+    });
+    click(optionOf(view, 'A'));
+    expect(onChange).not.toHaveBeenCalled();
+    expect(panelOf(view)).not.toBeNull();
+  });
+  it('SB-15 열린 채 disabled 여도 바깥 mousedown 은 닫고 잠금을 해제한다', () => {
+    const view = render();
+    open(view);
+    render({
+      disabled: true
+    });
+    mouseDown(document.body);
+    expect(panelOf(view)).toBeNull();
+    expect(wheel(document.body).defaultPrevented).toBe(false);
+  });
+  it.todo('SB-15 열린 채 disabled 로 바뀌면 패널을 닫고 스크롤 잠금을 해제한다 (vanilla setDisabled 와 동일) (#593)');
+});
+describe('SelectBox — 표시 (SB-17)', () => {
+  it("SB-17 값이 없으면 기본 placeholder '선택하세요' 를 표시하고 aria-label 도 같다", () => {
+    const view = render();
+    expect(valueTextOf(view)).toBe('선택하세요');
+    expect(triggerOf(view).getAttribute('aria-label')).toBe('선택하세요');
+  });
+  it('SB-17 placeholder 를 지정하면 그 문구를 표시한다', () => {
+    const view = render({
+      placeholder: '카테고리'
+    });
+    expect(valueTextOf(view)).toBe('카테고리');
+    expect(triggerOf(view).getAttribute('aria-label')).toBe('카테고리');
+  });
+  it('SB-17 선택 옵션에 아이콘이 있으면 값 영역에 아이콘과 라벨을 함께 표시한다', () => {
+    const Icon = props => /*#__PURE__*/createElement('svg', {
+      'data-icon': 'opt',
+      width: props.width
+    });
+    const view = render({
+      value: 'i',
+      optionItems: [{
+        id: 'i',
+        label: '아이콘',
+        icon: Icon
+      }]
+    });
+    expect(view.querySelector('.ncua-selectbox__value-icon [data-icon="opt"]')).not.toBeNull();
+    expect(valueTextOf(view)).toBe('아이콘');
+  });
+  it('SB-17 아이콘 없는 선택 옵션은 아이콘 영역 없이 라벨만 표시한다', () => {
+    const view = render({
+      value: 'a'
+    });
+    expect(view.querySelector('.ncua-selectbox__value-icon')).toBeNull();
+    expect(view.querySelector('.ncua-selectbox__value-container')).not.toBeNull();
+  });
+  it('SB-17 multiple 은 선택값이 있어도 항상 placeholder 를 표시한다', () => {
+    const view = render({
+      multiple: true,
+      value: ['a'],
+      placeholder: '여러 개'
+    });
+    expect(valueTextOf(view)).toBe('여러 개');
+    expect(triggerOf(view).getAttribute('aria-label')).toBe('여러 개');
+  });
+  it("SB-17 타입이 다른 값('1' vs 1) 은 일치하지 않아 placeholder 를 표시한다", () => {
+    const view = render({
+      value: '1',
+      optionItems: [{
+        id: 1,
+        label: '하나'
+      }]
+    });
+    expect(valueTextOf(view)).toBe('선택하세요');
+  });
+});
+describe('SelectBox — 클래스·속성 (SB-18)', () => {
+  it('SB-18 기본 size 는 xs 이고 chevron 은 14 다', () => {
+    const view = render();
+    const arrow = requireElement(view, '.ncua-selectbox__arrow');
+    expect(rootOf(view).classList.contains('ncua-selectbox--xs')).toBe(true);
+    expect(arrow.getAttribute('width')).toBe(CHEVRON_XS);
+    expect(arrow.getAttribute('height')).toBe(CHEVRON_XS);
+  });
+  it.each(['sm', 'md'])('SB-18 size %s 는 modifier 와 chevron 16, 패널 size class 를 갖는다', size => {
+    const view = render({
+      size
+    });
+    open(view);
+    expect(rootOf(view).classList.contains(`ncua-selectbox--${size}`)).toBe(true);
+    expect(requireElement(view, '.ncua-selectbox__arrow').getAttribute('width')).toBe(CHEVRON_SM);
+    expect(panelOf(view)?.classList.contains(`ncua-select-dropdown--${size}`)).toBe(true);
+  });
+  it('SB-18 simple·multiple·destructive·className 이 루트 클래스로 반영된다', () => {
+    const view = render({
+      type: 'simple',
+      multiple: true,
+      destructive: true,
+      className: 'custom'
+    });
+    const classList = rootOf(view).classList;
+    expect(classList.contains('ncua-selectbox--simple')).toBe(true);
+    expect(classList.contains('ncua-selectbox--multiple')).toBe(true);
+    expect(classList.contains('destructive')).toBe(true);
+    expect(classList.contains('custom')).toBe(true);
+  });
+  it('SB-18 열리면 --open 과 chevron __arrow--up, 닫히면 둘 다 없다', () => {
+    const view = render();
+    const arrowUp = () => requireElement(view, '.ncua-selectbox__arrow').classList.contains('ncua-selectbox__arrow--up');
+    expect(rootOf(view).classList.contains('ncua-selectbox--open')).toBe(false);
+    expect(arrowUp()).toBe(false);
+    open(view);
+    expect(rootOf(view).classList.contains('ncua-selectbox--open')).toBe(true);
+    expect(arrowUp()).toBe(true);
+  });
+  it('SB-18 hintText 는 HintText 로 렌더되고 destructive 를 전달한다', () => {
+    const view = render({
+      hintText: '필수 항목입니다',
+      destructive: true
+    });
+    const hint = requireElement(view, '.ncua-hint-text');
+    expect(hint.textContent).toBe('필수 항목입니다');
+    expect(hint.classList.contains('destructive')).toBe(true);
+  });
+  it('SB-18 hintText 가 없으면 HintText 를 렌더하지 않는다', () => {
+    const view = render();
+    expect(view.querySelector('.ncua-hint-text')).toBeNull();
+  });
+  it('SB-18 나머지 props 는 루트 div 로 전달되고 ref 는 루트 div 를 가리킨다', () => {
+    const ref = /*#__PURE__*/createRef();
+    const view = renderElement(/*#__PURE__*/createElement(SelectBox, {
+      optionItems: OPTIONS,
+      ref,
+      'data-testid': 'sb-root',
+      title: '분류'
+    }));
+    expect(rootOf(view).getAttribute('data-testid')).toBe('sb-root');
+    expect(rootOf(view).getAttribute('title')).toBe('분류');
+    expect(ref.current).toBe(rootOf(view));
+  });
+  it('SB-18 children 은 listbox 끝에 렌더되고 maxHeight 가 목록 스타일로 들어간다', () => {
+    const view = renderElement(/*#__PURE__*/createElement(SelectBox, {
+      optionItems: OPTIONS,
+      maxHeight: CUSTOM_MAX_HEIGHT
+    }, /*#__PURE__*/createElement('li', {
+      className: 'extra'
+    }, '추가')));
+    open(view);
+    const list = requireElement(view, '.ncua-select-dropdown__options');
+    expect(list.lastElementChild?.classList.contains('extra')).toBe(true);
+    expect(list.style.maxHeight).toBe(`${CUSTOM_MAX_HEIGHT}px`);
+  });
+  it('SB-18 align right 는 패널에 --align-right 를, 기본(left) 은 붙이지 않는다', () => {
+    const view = render({
+      align: 'right'
+    });
+    open(view);
+    expect(panelOf(view)?.classList.contains('ncua-select-dropdown--align-right')).toBe(true);
+    click(triggerOf(view));
+    render({
+      align: 'left'
+    });
+    open(view);
+    expect(panelOf(view)?.classList.contains('ncua-select-dropdown--align-right')).toBe(false);
+  });
+  it('SB-18 단일 모드 패널은 --selectbox-single, 다중 모드는 --multiple 과 푸터를 갖는다', () => {
+    const view = render();
+    open(view);
+    expect(panelOf(view)?.classList.contains('ncua-select-dropdown--selectbox-single')).toBe(true);
+    expect(view.querySelector('.ncua-select-dropdown__footer')).toBeNull();
+    click(triggerOf(view));
+    render({
+      multiple: true,
+      value: []
+    });
+    open(view);
+    expect(panelOf(view)?.classList.contains('ncua-select-dropdown--multiple')).toBe(true);
+    expect(view.querySelector('.ncua-select-dropdown__footer')).not.toBeNull();
+  });
+});
+describe('SelectBox — id 연결 (SB-19)', () => {
+  it('SB-19 id 는 루트·트리거에 붙지 않고 listbox id·aria-controls 에만 쓰인다', () => {
+    // 현재 동작 고정 — 결함 후보: #593 (label for 로 연결할 요소가 없음)
+    const view = render({
+      id: 'sb'
+    });
+    open(view);
+    expect(document.getElementById('sb')).toBeNull();
+    expect(requireElement(view, '[role="listbox"]').id).toBe('selectbox-options-sb');
+    expect(triggerOf(view).getAttribute('aria-controls')).toBe('selectbox-options-sb');
+  });
+  it('SB-19 id 가 없으면 인스턴스마다 같은 listbox id(selectbox-options-default) 를 써 id 가 중복된다', () => {
+    // 현재 동작 고정 — 결함 후보: #593 (aria-controls·activedescendant 가 다른 인스턴스를 가리킬 수 있음)
+    const view = renderElement(/*#__PURE__*/createElement(Fragment, null, /*#__PURE__*/createElement(SelectBox, {
+      optionItems: OPTIONS
+    }), /*#__PURE__*/createElement(SelectBox, {
+      optionItems: OPTIONS
+    })));
+    const triggers = view.querySelectorAll('.ncua-selectbox__content');
+    click(triggers[0]);
+    click(triggers[1]);
+    const listboxIds = Array.from(view.querySelectorAll('[role="listbox"]')).map(element => element.id);
+    expect(listboxIds).toEqual(['selectbox-options-default', 'selectbox-options-default']);
+    expect(triggers[0].getAttribute('aria-controls')).toBe(triggers[1].getAttribute('aria-controls'));
+  });
+  it.todo('SB-19 id 는 포커스 가능한 트리거(role=combobox) 에 붙어 label for 로 연결된다 (#593)');
+  it.todo('SB-19 id 가 없어도 인스턴스마다 고유한 listbox id 를 만든다 (useId) (#593)');
+});
+describe('SelectBox — disabledPlaceholder (SB-20)', () => {
+  it('SB-20 disabledPlaceholder 는 렌더 결과에 아무 영향이 없다', () => {
+    // 현재 동작 고정 — 결함 후보: #593 (선언·문서화됐지만 구현에서 쓰이지 않음)
+    const withFlag = render({
+      disabled: true,
+      disabledPlaceholder: true
+    }).innerHTML;
+    const withoutFlag = render({
+      disabled: true,
+      disabledPlaceholder: false
+    }).innerHTML;
+    expect(withFlag).toBe(withoutFlag);
+  });
+  it.todo('SB-20 disabledPlaceholder 를 구현하거나 프롭·문서(select.mdx)에서 제거한다 (#593)');
+});
+describe('SelectBox — option.disabled (SB-21)', () => {
+  const OPTIONS_WITH_DISABLED = [{
+    id: 'a',
+    label: 'A'
+  }, {
+    id: 'x',
+    label: 'X',
+    disabled: true
+  }];
+  it('SB-21 disabled 옵션도 click 으로 선택되고 표시 클래스가 없다', () => {
+    // 현재 동작 고정 — 결함 후보: #593 (React OptionType 에 disabled 없음, vanilla 는 --disabled·선택 차단)
+    const onChange = vi.fn();
+    const view = render({
+      optionItems: OPTIONS_WITH_DISABLED,
+      onChange
+    });
+    open(view);
+    const option = optionOf(view, 'X');
+    expect(option.classList.contains('ncua-select-dropdown__option--disabled')).toBe(false);
+    expect(option.hasAttribute('aria-disabled')).toBe(false);
+    click(option);
+    expect(onChange).toHaveBeenCalledWith('x');
+  });
+  it('SB-21 disabled 옵션도 Enter 로 선택된다', () => {
+    // 현재 동작 고정 — 결함 후보: #593 (키보드 선택도 disabled 를 보지 않음)
+    const onChange = vi.fn();
+    const view = render({
+      optionItems: OPTIONS_WITH_DISABLED,
+      onChange
+    });
+    open(view);
+    keyDown(triggerOf(view), 'End');
+    keyDown(triggerOf(view), 'Enter');
+    expect(onChange).toHaveBeenCalledWith('x');
+  });
+  it('SB-21 전체 선택만 disabled 옵션을 제외한다', () => {
+    const onChange = vi.fn();
+    const view = render({
+      multiple: true,
+      value: [],
+      optionItems: OPTIONS_WITH_DISABLED,
+      onChange
+    });
+    open(view);
+    click(requireButton(view, '전체 선택'));
+    expect(onChange).toHaveBeenCalledWith(['a']);
+  });
+  it.todo('SB-21 option.disabled 는 --disabled·aria-disabled 로 표시되고 click·Enter 선택이 차단된다 (vanilla 와 동일) (#593)');
+});
+describe('SelectBox — 코너 (SB-22)', () => {
+  it('SB-22 열린 중 옵션이 줄어 포커스 인덱스가 개수 이상이면 activedescendant 가 사라진다', () => {
+    const view = render();
+    open(view);
+    keyDown(triggerOf(view), 'End');
+    expect(triggerOf(view).getAttribute('aria-activedescendant')).toBe('selectbox-options-default-c');
+    render({
+      optionItems: OPTIONS.slice(0, 1)
+    });
+    expect(triggerOf(view).getAttribute('aria-activedescendant')).toBeNull();
+    expect(focusedLabelsOf(view)).toEqual([]);
+  });
+  it('SB-22 빈 optionItems 도 열리고, Arrow 이동은 포커스를 만들지 않는다', () => {
+    const view = render({
+      optionItems: []
+    });
+    open(view);
+    keyDown(triggerOf(view), 'ArrowDown');
+    expect(panelOf(view)).not.toBeNull();
+    expect(view.querySelectorAll('.ncua-select-dropdown__option')).toHaveLength(0);
+    expect(triggerOf(view).getAttribute('aria-activedescendant')).toBeNull();
+  });
+  it('SB-22 optionItems 미지정이면 빈 목록으로 열린다', () => {
+    const view = renderElement(/*#__PURE__*/createElement(SelectBox, {}));
+    open(view);
+    expect(panelOf(view)).not.toBeNull();
+    expect(view.querySelectorAll('.ncua-select-dropdown__option')).toHaveLength(0);
+  });
+  it('SB-22 multiple → false 전환 뒤 태그는 남고 태그 X 는 onChange 를 부르지 않는다', () => {
+    const onChange = vi.fn();
+    const view = completeWithTags({
+      value: ['a'],
+      onChange
+    });
+    render({
+      multiple: false,
+      value: 'a',
+      onChange
+    });
+    click(tagCloseOf(view, 'A'));
+    expect(onChange).not.toHaveBeenCalled();
+    expect(tagTextsOf(view)).toEqual(['A']);
+  });
+  it('SB-22 onChange 없는 register 객체로 선택해도 오류 없이 onChange 만 호출된다', () => {
+    const onChange = vi.fn();
+    const register = {
+      name: 'category',
+      onBlur: vi.fn(),
+      ref: vi.fn()
+    };
+    const view = render({
+      register,
+      onChange
+    });
+    open(view);
+    click(optionOf(view, 'A'));
+    expect(onChange).toHaveBeenCalledWith('a');
+  });
+});
+describe('SelectBox — id 0 hidden input (SB-23)', () => {
+  it("SB-23 단일 모드에서 id 0 을 선택하면 라벨은 보이지만 hidden input 값은 '' 이다", () => {
+    // 현재 동작 고정 — 결함 후보: #593 (String(value || '') 가 0 을 빈 문자열로 바꿈)
+    const view = render({
+      value: 0,
+      optionItems: [{
+        id: 0,
+        label: '영'
+      }],
+      register: createRegister()
+    });
+    expect(valueTextOf(view)).toBe('영');
+    expect(hiddenInputOf(view)?.value).toBe('');
+  });
+  it.todo("SB-23 id 0 선택 시 hidden input 값은 '0' 이다 (String(value ?? '')) (#593)");
+});