@ncds/ui-admin 1.8.24 → 1.8.25-alpha.1

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

@@ -0,0 +1,578 @@
+// @vitest-environment jsdom
+import { createElement } from 'react';
+import { createRoot } from 'react-dom/client';
+import { act } from 'react-dom/test-utils';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { FloatingProvider } from '../../../../contexts/FloatingContext';
+import { PORTAL_PANEL_Z_INDEX } from '../../../../utils/portal-position';
+import { ComboBox } from '../ComboBox';
+// @ncds/ui-admin-icon 은 react@19 를 해석해 react-dom@18 이 거부하는 엘리먼트를 만든다.
+// 아이콘은 Portal 좌표와 무관하므로 스텁으로 대체해 이 저장소 전반의 렌더 테스트 차단을 우회한다.
+vi.mock('@ncds/ui-admin-icon', () => {
+  const IconStub = () => null;
+  return {
+    CheckCircle: IconStub,
+    ChevronSelectorVertical: IconStub,
+    HelpCircle: IconStub,
+    InfoCircle: IconStub,
+    SearchLg: IconStub,
+    X: IconStub,
+    XClose: IconStub
+  };
+});
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+const PANEL_OFFSET = 4;
+const ANCHOR_TOP = 100;
+const ANCHOR_LEFT = 50;
+const ANCHOR_WIDTH = 320;
+const ANCHOR_HEIGHT = 40;
+const ANCHOR_BOTTOM = ANCHOR_TOP + ANCHOR_HEIGHT;
+/** hintText 가 있을 때 루트가 __content 보다 더 차지하는 높이 */
+const HINT_TEXT_HEIGHT = 40;
+/** viewport 하단이라 direction='up' 으로 열리는 anchor 위치 */
+const LOW_ANCHOR_TOP = 700;
+const SCROLLED_ANCHOR_TOP = 60;
+const GROWN_PANEL_HEIGHT = 200;
+const createOptions = () => [{
+  id: 'apple',
+  label: '사과'
+}, {
+  id: 'banana',
+  label: '바나나'
+}, {
+  id: 'cherry',
+  label: '체리'
+}];
+const stubRect = (element, _ref) => {
+  let {
+    top,
+    left,
+    width,
+    height
+  } = _ref;
+  vi.spyOn(element, 'getBoundingClientRect').mockReturnValue(DOMRect.fromRect({
+    x: left,
+    y: top,
+    width,
+    height
+  }));
+};
+/**
+ * 루트와 __content 의 기하를 함께 고정한다. `extraRootHeight` 는 hintText 처럼 루트에만
+ * 얹히는 높이로, 두 박스의 bottom 을 갈라 anchor 기준을 구별할 수 있게 한다.
+ */
+const stubAnchorGeometry = _ref2 => {
+  let {
+    root,
+    content,
+    top = ANCHOR_TOP,
+    extraRootHeight = 0
+  } = _ref2;
+  stubRect(content, {
+    top,
+    left: ANCHOR_LEFT,
+    width: ANCHOR_WIDTH,
+    height: ANCHOR_HEIGHT
+  });
+  stubRect(root, {
+    top,
+    left: ANCHOR_LEFT,
+    width: ANCHOR_WIDTH,
+    height: ANCHOR_HEIGHT + extraRootHeight
+  });
+};
+const installResizeObserverStub = () => {
+  const callbacks = [];
+  class ResizeObserverStub {
+    constructor(callback) {
+      this.observe = vi.fn();
+      this.unobserve = vi.fn();
+      this.disconnect = vi.fn();
+      callbacks.push(callback);
+    }
+  }
+  vi.stubGlobal('ResizeObserver', ResizeObserverStub);
+  return {
+    triggerAll: () => {
+      for (const callback of callbacks) {
+        callback([], {});
+      }
+    }
+  };
+};
+const requireElement = (scope, selector) => {
+  const element = scope.querySelector(selector);
+  if (element === null) {
+    throw new Error(`요소를 찾을 수 없습니다: ${selector}`);
+  }
+  return element;
+};
+// 마운트한 트리는 afterEach 가 일괄 정리한다. 실패한 단언이 unmount 호출을 건너뛰어도
+// 다음 테스트로 잔여 DOM 이 흘러가지 않게 한다.
+const pendingCleanups = [];
+const mountComboBox = function () {
+  let {
+    props = {},
+    floating
+  } = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+  const container = document.createElement('div');
+  document.body.appendChild(container);
+  const reactRoot = createRoot(container);
+  const comboBox = /*#__PURE__*/createElement(ComboBox, {
+    optionItems: createOptions(),
+    ...props
+  });
+  const tree = floating ? /*#__PURE__*/createElement(FloatingProvider, {
+    value: floating
+  }, comboBox) : comboBox;
+  act(() => {
+    reactRoot.render(tree);
+  });
+  pendingCleanups.push(() => {
+    act(() => {
+      reactRoot.unmount();
+    });
+    container.remove();
+  });
+  return {
+    container,
+    root: requireElement(container, '.ncua-combobox'),
+    content: requireElement(container, '.ncua-combobox__content'),
+    input: requireElement(container, 'input[role="combobox"]'),
+    inlinePanels: () => container.querySelectorAll('.ncua-select-dropdown'),
+    portalPanels: () => document.body.querySelectorAll(':scope > .ncua-select-dropdown'),
+    open: () => {
+      act(() => {
+        requireElement(container, '.ncua-input__right-icon').click();
+      });
+    },
+    typeSearch: text => {
+      const input = requireElement(container, 'input[role="combobox"]');
+      const valueSetter = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value')?.set;
+      act(() => {
+        valueSetter?.call(input, text);
+        input.dispatchEvent(new Event('input', {
+          bubbles: true
+        }));
+      });
+    },
+    pressEscape: () => {
+      act(() => {
+        requireElement(container, 'input[role="combobox"]').dispatchEvent(new KeyboardEvent('keydown', {
+          key: 'Escape',
+          bubbles: true
+        }));
+      });
+    }
+  };
+};
+const mousedownOn = element => {
+  act(() => {
+    element.dispatchEvent(new MouseEvent('mousedown', {
+      bubbles: true
+    }));
+  });
+};
+const clickButtonByLabel = (scope, label) => {
+  const button = [...scope.querySelectorAll('button')].find(candidate => candidate.textContent?.includes(label));
+  if (button === undefined) {
+    throw new Error(`버튼을 찾을 수 없습니다: ${label}`);
+  }
+  act(() => {
+    button.click();
+  });
+};
+afterEach(() => {
+  for (const cleanup of pendingCleanups.splice(0)) {
+    cleanup();
+  }
+  document.body.innerHTML = '';
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+});
+describe('C-1 ComboBox Portal 마운트 위치', () => {
+  it('usePortal 미지정이면 옵션 패널이 __content 내부에만 렌더된다', () => {
+    // Given: usePortal 을 지정하지 않은 ComboBox 가 마운트된 상태에서
+    const view = mountComboBox();
+    // When: 옵션 패널을 연다
+    view.open();
+    // Then: 패널은 __content 내부에 1개만 존재하고 body 직속에는 없다
+    expect(view.content.querySelectorAll('.ncua-select-dropdown')).toHaveLength(1);
+    expect(view.portalPanels()).toHaveLength(0);
+  });
+  it('usePortal 이 true 면 옵션 패널이 컨테이너 직속으로만 렌더된다', () => {
+    // Given: usePortal={true} 인 ComboBox 가 마운트된 상태에서
+    const view = mountComboBox({
+      props: {
+        usePortal: true
+      }
+    });
+    // When: 옵션 패널을 연다
+    view.open();
+    // Then: __content 내부에는 패널이 없고 portalContainer 직속에 1개 존재한다
+    expect(view.content.querySelectorAll('.ncua-select-dropdown')).toHaveLength(0);
+    expect(view.portalPanels()).toHaveLength(1);
+  });
+  it('패널을 닫으면 Portal 노드가 DOM 에서 제거된다', () => {
+    // Given: Portal 모드로 열린 ComboBox 에서
+    const view = mountComboBox({
+      props: {
+        usePortal: true
+      }
+    });
+    view.open();
+    expect(view.portalPanels()).toHaveLength(1);
+    // When: Escape 로 패널을 닫으면
+    view.pressEscape();
+    // Then: Portal 노드가 문서에 잔류하지 않는다
+    expect(view.portalPanels()).toHaveLength(0);
+  });
+});
+describe('C-2 FloatingContext 미위임 — 기존 동작 보존', () => {
+  it('usePortal 미지정이면 preferPortal 컨텍스트 안에서도 인라인을 유지한다', () => {
+    // Given: preferPortal: true 컨텍스트 안에서 usePortal 을 지정하지 않은 ComboBox 가
+    const view = mountComboBox({
+      floating: {
+        preferPortal: true
+      }
+    });
+    // When: 옵션 패널을 연다
+    view.open();
+    // Then: 컨텍스트를 따르지 않고 인라인 렌더가 유지된다 — Table horizontalScroll 안의
+    // 기존 ComboBox 가 옵션 지정 없이 Portal 로 전환되지 않아야 한다
+    expect(view.portalPanels()).toHaveLength(0);
+    expect(view.content.querySelectorAll('.ncua-select-dropdown')).toHaveLength(1);
+  });
+  it('usePortal={true} 를 명시하면 컨텍스트와 무관하게 Portal 로 렌더된다', () => {
+    // Given: 컨텍스트 없이 usePortal={true} 만 명시한 ComboBox 가
+    const view = mountComboBox({
+      props: {
+        usePortal: true
+      }
+    });
+    // When: 옵션 패널을 연다
+    view.open();
+    // Then: Portal 렌더가 선택된다
+    expect(view.portalPanels()).toHaveLength(1);
+    expect(view.content.querySelectorAll('.ncua-select-dropdown')).toHaveLength(0);
+  });
+  it('usePortal={false} 를 명시해도 preferPortal 컨텍스트 안에서 인라인을 유지한다', () => {
+    // Given: preferPortal: true 컨텍스트 안에서 usePortal={false} 를 명시한 ComboBox 가
+    const view = mountComboBox({
+      props: {
+        usePortal: false
+      },
+      floating: {
+        preferPortal: true
+      }
+    });
+    // When: 옵션 패널을 연다
+    view.open();
+    // Then: 인라인 렌더가 유지된다
+    expect(view.portalPanels()).toHaveLength(0);
+    expect(view.content.querySelectorAll('.ncua-select-dropdown')).toHaveLength(1);
+  });
+});
+describe('C-3 Portal 패널 스타일', () => {
+  it('--portal 클래스와 anchor rect 파생 fixed 좌표를 함께 부여한다', () => {
+    // Given: anchor 기하가 고정된 Portal 모드 ComboBox 에서
+    const view = mountComboBox({
+      props: {
+        usePortal: true
+      }
+    });
+    stubAnchorGeometry({
+      root: view.root,
+      content: view.content
+    });
+    // When: 옵션 패널을 연다
+    view.open();
+    // Then: 패널이 --portal 클래스와 anchor 파생 좌표·최소 너비를 갖는다
+    const panel = view.portalPanels()[0];
+    expect(panel.classList.contains('ncua-select-dropdown--portal')).toBe(true);
+    expect(panel.style.position).toBe('fixed');
+    expect(panel.style.top).toBe(`${ANCHOR_BOTTOM + PANEL_OFFSET}px`);
+    expect(panel.style.left).toBe(`${ANCHOR_LEFT}px`);
+    expect(panel.style.minWidth).toBe(`${ANCHOR_WIDTH}px`);
+    expect(panel.style.zIndex).toBe(String(PORTAL_PANEL_Z_INDEX));
+  });
+});
+describe('C-4 anchor 박스는 .ncua-combobox__content 다', () => {
+  it('label·hintText 를 함께 지정해도 좌표 기준이 __content 의 rect 다', () => {
+    // Given: hintText 때문에 루트가 __content 보다 아래까지 차지하는 ComboBox 에서
+    const view = mountComboBox({
+      props: {
+        usePortal: true,
+        label: '과일',
+        hintText: '안내 문구'
+      }
+    });
+    stubAnchorGeometry({
+      root: view.root,
+      content: view.content,
+      extraRootHeight: HINT_TEXT_HEIGHT
+    });
+    // When: 옵션 패널을 연다
+    view.open();
+    // Then: top 은 __content 의 bottom 기준이며 루트 bottom 기준값보다 작다
+    const panel = view.portalPanels()[0];
+    expect(panel.style.top).toBe(`${ANCHOR_BOTTOM + PANEL_OFFSET}px`);
+    expect(panel.style.top).not.toBe(`${ANCHOR_BOTTOM + HINT_TEXT_HEIGHT + PANEL_OFFSET}px`);
+  });
+});
+describe('C-5 외부 클릭 판정', () => {
+  it('Portal 패널 내부 mousedown 은 패널을 닫지 않는다', () => {
+    // Given: Portal 모드로 열린 ComboBox 에서
+    const view = mountComboBox({
+      props: {
+        usePortal: true
+      }
+    });
+    view.open();
+    // When: Portal 패널 내부를 mousedown 하면
+    mousedownOn(view.portalPanels()[0]);
+    // Then: 패널이 유지된다
+    expect(view.portalPanels()).toHaveLength(1);
+  });
+  it('패널·트리거 밖 mousedown 은 패널을 닫는다', () => {
+    // Given: Portal 모드로 열린 ComboBox 에서
+    const view = mountComboBox({
+      props: {
+        usePortal: true
+      }
+    });
+    view.open();
+    // When: 문서 본문을 mousedown 하면
+    mousedownOn(document.body);
+    // Then: 패널이 닫힌다
+    expect(view.portalPanels()).toHaveLength(0);
+  });
+});
+describe('C-6 multiple footer 버튼', () => {
+  it('Portal 모드에서 "선택 완료" 클릭이 onComplete 를 1회 호출하고 패널을 닫는다', () => {
+    // Given: multiple Portal 모드로 열린 ComboBox 에서
+    const onComplete = vi.fn();
+    const view = mountComboBox({
+      props: {
+        usePortal: true,
+        multiple: true,
+        value: ['apple'],
+        onComplete
+      }
+    });
+    view.open();
+    // When: Portal 패널의 "선택 완료" 버튼을 클릭하면
+    clickButtonByLabel(view.portalPanels()[0], '선택 완료');
+    // Then: onComplete 가 1회 호출되고 패널이 닫힌다
+    expect(onComplete).toHaveBeenCalledTimes(1);
+    expect(view.portalPanels()).toHaveLength(0);
+  });
+  it('Portal 모드에서 "전체 선택" 클릭이 onChange 를 호출한다', () => {
+    // Given: multiple Portal 모드로 열린 ComboBox 에서
+    const onChange = vi.fn();
+    const view = mountComboBox({
+      props: {
+        usePortal: true,
+        multiple: true,
+        value: [],
+        onChange
+      }
+    });
+    view.open();
+    // When: Portal 패널의 "전체 선택" 버튼을 클릭하면
+    clickButtonByLabel(view.portalPanels()[0], '전체 선택');
+    // Then: onChange 가 호출된다
+    expect(onChange).toHaveBeenCalled();
+  });
+});
+describe('C-7 usePortal props 누출', () => {
+  it('usePortal 을 전달해도 루트 div 에 DOM 속성으로 누출되지 않는다', () => {
+    // Given: console.error 를 감시하는 상태에서
+    const consoleErrorSpy = vi.spyOn(console, 'error');
+    // When: usePortal 을 전달해 렌더하면
+    const view = mountComboBox({
+      props: {
+        usePortal: true
+      }
+    });
+    // Then: 루트에 useportal 속성이 없고 usePortal 에 대한 unknown prop 경고도 발생하지 않는다.
+    // 경고 전체가 아니라 usePortal 을 언급한 것만 본다 — 무관한 React 경고까지 잡으면
+    // 이 케이스가 다른 컴포넌트의 결함으로 깨진다.
+    const portalPropWarnings = consoleErrorSpy.mock.calls.filter(args => args.some(arg => typeof arg === 'string' && arg.toLowerCase().includes('useportal')));
+    expect(view.root.hasAttribute('useportal')).toBe(false);
+    expect(portalPropWarnings).toEqual([]);
+  });
+});
+describe('C-8 좌표 추적', () => {
+  it('window scroll 이후 anchor 이동분이 top 에 반영된다', () => {
+    // Given: Portal 모드로 열려 좌표가 산출된 ComboBox 에서
+    installResizeObserverStub();
+    const view = mountComboBox({
+      props: {
+        usePortal: true
+      }
+    });
+    stubAnchorGeometry({
+      root: view.root,
+      content: view.content
+    });
+    view.open();
+    expect(view.portalPanels()[0].style.top).toBe(`${ANCHOR_BOTTOM + PANEL_OFFSET}px`);
+    // When: anchor 가 위로 이동한 뒤 window scroll 이 발생하면
+    stubAnchorGeometry({
+      root: view.root,
+      content: view.content,
+      top: SCROLLED_ANCHOR_TOP
+    });
+    act(() => {
+      window.dispatchEvent(new Event('scroll'));
+    });
+    // Then: top 이 재산출된다
+    expect(view.portalPanels()[0].style.top).toBe(`${SCROLLED_ANCHOR_TOP + ANCHOR_HEIGHT + PANEL_OFFSET}px`);
+  });
+  it('패널 ResizeObserver 발화 시 direction=up 의 top 이 패널 높이로 재산출된다', () => {
+    // Given: 트리거가 viewport 하단에 있어 direction='up' 으로 열린 Portal ComboBox 에서
+    const resizeObserver = installResizeObserverStub();
+    const view = mountComboBox({
+      props: {
+        usePortal: true
+      }
+    });
+    stubAnchorGeometry({
+      root: view.root,
+      content: view.content,
+      top: LOW_ANCHOR_TOP
+    });
+    view.open();
+    const panel = view.portalPanels()[0];
+    expect(panel.style.top).toBe(`${LOW_ANCHOR_TOP - PANEL_OFFSET}px`);
+    // When: 검색 결과 변화로 패널 높이가 커지고 ResizeObserver 가 발화하면
+    Object.defineProperty(panel, 'offsetHeight', {
+      value: GROWN_PANEL_HEIGHT,
+      configurable: true
+    });
+    act(() => {
+      resizeObserver.triggerAll();
+    });
+    // Then: top 이 늘어난 높이만큼 위로 재산출된다
+    expect(panel.style.top).toBe(`${LOW_ANCHOR_TOP - GROWN_PANEL_HEIGHT - PANEL_OFFSET}px`);
+  });
+});
+describe('C-9 기본 경로 회귀 기준선', () => {
+  it('검색어를 입력하면 패널이 열리고 옵션이 노출된다', () => {
+    // Given: usePortal 을 지정하지 않은 ComboBox 에서
+    const onSearch = vi.fn();
+    const view = mountComboBox({
+      props: {
+        onSearch
+      }
+    });
+    // When: 검색어를 입력하면
+    view.typeSearch('사');
+    // Then: onSearch 가 호출되고 인라인 패널에 옵션이 노출된다
+    expect(onSearch).toHaveBeenCalledWith('사');
+    expect(view.content.querySelectorAll('.ncua-select-dropdown__option')).toHaveLength(createOptions().length);
+  });
+  it('옵션을 선택하면 onChange 가 호출되고 선택 태그가 표시된다', () => {
+    // Given: 옵션이 노출된 기본 모드 ComboBox 에서
+    const onChange = vi.fn();
+    const view = mountComboBox({
+      props: {
+        onChange
+      }
+    });
+    view.open();
+    // When: 첫 옵션을 클릭하면
+    act(() => {
+      requireElement(view.content, '.ncua-select-dropdown__option').click();
+    });
+    // Then: onChange 가 선택 값으로 호출되고 태그가 표시된다
+    expect(onChange).toHaveBeenCalledWith('apple');
+    expect(view.container.querySelectorAll('.ncua-combobox__tags .ncua-tag')).toHaveLength(1);
+  });
+  it('Escape 를 누르면 인라인 패널이 닫힌다', () => {
+    // Given: 열려 있는 기본 모드 ComboBox 에서
+    const view = mountComboBox();
+    view.open();
+    expect(view.inlinePanels()).toHaveLength(1);
+    // When: Escape 를 누르면
+    view.pressEscape();
+    // Then: 패널이 닫힌다
+    expect(view.inlinePanels()).toHaveLength(0);
+  });
+});
+describe('C-11 hintText + Portal 모드에서 direction 판정 기준은 contentRef', () => {
+  it('root 가 content 보다 아래까지 차지해도 direction 판정은 contentRef.bottom 기준이다', () => {
+    // Given: hintText 때문에 root.bottom 이 content.bottom 보다 HINT_TEXT_HEIGHT(40px) 더 아래인 ComboBox 에서
+    // content.top = 570, content.bottom = 610, root.bottom = 650 (ANCHOR_HEIGHT + HINT_TEXT_HEIGHT)
+    // jsdom viewport = 768, panelHeight = 120(3개×40), gap = 20
+    //   content 기준: 768 - 610 = 158 ≥ 140 → 'down' (패널이 아래에 열려야 함)
+    //   root 기준:    768 - 650 = 118 < 140 → 'up'   (잘못된 판정)
+    const BOUNDARY_TOP = 570;
+    const view = mountComboBox({
+      props: {
+        usePortal: true,
+        hintText: '안내 문구'
+      }
+    });
+    stubAnchorGeometry({
+      root: view.root,
+      content: view.content,
+      top: BOUNDARY_TOP,
+      extraRootHeight: HINT_TEXT_HEIGHT
+    });
+    // When: 옵션 패널을 연다
+    view.open();
+    // Then: direction 이 'down' 이어야 한다 — contentRef 기준으로 패널이 아래에 들어가는 높이
+    const panel = view.portalPanels()[0];
+    expect(panel.classList.contains('ncua-select-dropdown--down')).toBe(true);
+    expect(panel.classList.contains('ncua-select-dropdown--up')).toBe(false);
+  });
+});
+describe('C-10 portalContainer: null → document.body 대체', () => {
+  it('portalContainer: null 컨텍스트에서도 예외 없이 렌더되고 document.body 에 Portal 패널이 1개 생긴다', () => {
+    // Given: portalContainer 를 null 로 내린 컨텍스트에서 usePortal 을 명시로 켠 ComboBox 가
+    // usePortalState 는 null ?? document.body 로 대체하므로 portalContainer 는 document.body 가 된다
+    const view = mountComboBox({
+      props: {
+        usePortal: true
+      },
+      floating: {
+        preferPortal: true,
+        portalContainer: null
+      }
+    });
+    // When: 옵션 패널을 연다 (렌더 예외가 전파되면 이 호출이 throw 한다)
+    view.open();
+    // Then: 인라인 패널이 없고 document.body 에 Portal 패널이 1개 존재한다
+    expect(view.content.querySelectorAll('.ncua-select-dropdown')).toHaveLength(0);
+    expect(view.portalPanels()).toHaveLength(1);
+  });
+});
+describe('C-12 루트 이벤트 핸들러 버블링', () => {
+  it.each([['인라인', false], ['Portal', true]])('%s 모드에서 패널 내부 mousedown·keydown 이 소비자 루트 핸들러로 전파된다', (_label, usePortal) => {
+    // Given: 루트에 onMouseDown·onKeyDown 을 넘긴 ComboBox 가 열린 상태에서
+    const onMouseDown = vi.fn();
+    const onKeyDown = vi.fn();
+    const view = mountComboBox({
+      props: {
+        usePortal,
+        onMouseDown,
+        onKeyDown
+      }
+    });
+    view.open();
+    const panel = usePortal ? view.portalPanels()[0] : view.inlinePanels()[0];
+    // When: 패널 내부에서 mousedown·keydown 이 발생하면
+    mousedownOn(panel);
+    act(() => {
+      panel.dispatchEvent(new KeyboardEvent('keydown', {
+        key: 'a',
+        bubbles: true
+      }));
+    });
+    // Then: React 합성 이벤트가 인라인과 같은 트리 경로로 루트까지 버블링된다
+    expect(onMouseDown).toHaveBeenCalledTimes(1);
+    expect(onKeyDown).toHaveBeenCalledTimes(1);
+  });
+});

package/dist/esm/src/components/navigation/bread-crumb/BreadCrumb.js

@@ -4,11 +4,15 @@ import classNames from 'classnames';
 const BreadcrumbItem = _ref => {
   let {
     href,
+    ariaLabel,
     children
   } = _ref;
   const ElementType = href ? 'a' : 'span';
   return _jsx(ElementType, {
     href: href,
+    // <span> 은 generic role 이라 aria-label 이 무시될 수 있다. 링크는 이미 이름을 지원하므로 그대로 둔다
+    role: !href && ariaLabel ? 'img' : undefined,
+    "aria-label": ariaLabel,
     className: "ncua-breadcrumb__item",
     children: children
   });
@@ -16,23 +20,27 @@ const BreadcrumbItem = _ref => {
 const BreadCrumb = _ref2 => {
   let {
     items,
+    showHomeIcon = true,
     className
   } = _ref2;
   if (!items || items.length === 0) return null;
   const renderItem = (item, index) => {
     const isLast = index === items.length - 1;
-    const content = index === 0 ? _jsx(Home01, {
-      width: 16,
-      height: 16,
-      color: "gray500"
-    }) : item.label;
+    // 아이콘 여부는 한 곳에서만 판정한다 — 콘텐츠·모디파이어·aria-label 이 모두 이 값을 따른다
+    const isHome = showHomeIcon && index === 0;
     return _jsx("li", {
       className: classNames('ncua-breadcrumb__list-item', {
+        'ncua-breadcrumb__list-item--home': isHome,
         'ncua-breadcrumb__list-item--active': isLast
       }),
       children: _jsx(BreadcrumbItem, {
         href: isLast ? undefined : item.href,
-        children: content
+        ariaLabel: isHome ? item.label : undefined,
+        children: isHome ? _jsx(Home01, {
+          width: 16,
+          height: 16,
+          color: "gray500"
+        }) : item.label
       })
     }, index);
   };