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

package/dist/esm/src/utils/portal-position/__tests__/portalPosition.tracking.test.js

@@ -0,0 +1,394 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { applyPortalPanelStyle, buildPortalPanelStyle, observeAnchorGeometry, trackPortalPosition } from '..';
+const installResizeObserverStub = () => {
+  const instances = [];
+  class ResizeObserverStub {
+    constructor(_callback) {
+      this.observe = vi.fn();
+      this.unobserve = vi.fn();
+      this.disconnect = vi.fn();
+      instances.push(this);
+    }
+  }
+  vi.stubGlobal('ResizeObserver', ResizeObserverStub);
+  return {
+    instances
+  };
+};
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+});
+const makeAnchorRect = function () {
+  let overrides = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+  return {
+    top: 100,
+    bottom: 140,
+    left: 50,
+    right: 250,
+    width: 200,
+    ...overrides
+  };
+};
+const PANEL_HEIGHT = 300;
+const PANEL_WIDTH = 180;
+const DEFAULT_OFFSET = 4;
+const EXPECTED_Z_INDEX = 1500;
+const ON_CHANGE_CALLS = {
+  initial: 1,
+  afterScroll: 2,
+  afterResize: 3
+};
+const toDomRect = rect => DOMRect.fromRect({
+  x: rect.left,
+  y: rect.top,
+  width: rect.width,
+  height: rect.bottom - rect.top
+});
+const createAnchor = function () {
+  let rect = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : makeAnchorRect();
+  const element = document.createElement('button');
+  document.body.appendChild(element);
+  const boundingRect = vi.spyOn(element, 'getBoundingClientRect').mockReturnValue(toDomRect(rect));
+  const moveTo = next => boundingRect.mockReturnValue(toDomRect(next));
+  return {
+    element,
+    moveTo
+  };
+};
+const createPanel = function () {
+  let {
+    height,
+    width
+  } = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {
+    height: PANEL_HEIGHT,
+    width: PANEL_WIDTH
+  };
+  const element = document.createElement('div');
+  document.body.appendChild(element);
+  Object.defineProperty(element, 'offsetHeight', {
+    value: height,
+    configurable: true
+  });
+  Object.defineProperty(element, 'offsetWidth', {
+    value: width,
+    configurable: true
+  });
+  return element;
+};
+const dispatchWindow = type => window.dispatchEvent(new Event(type));
+describe('observeAnchorGeometry — 구독 (E-6)', () => {
+  it('구독 직후 onChange 를 1회 호출하고 window scroll·resize 마다 다시 호출한다', () => {
+    installResizeObserverStub();
+    const anchor = createAnchor();
+    const onChange = vi.fn();
+    const cleanup = observeAnchorGeometry({
+      getAnchor: () => anchor.element,
+      getPanel: () => null,
+      onChange
+    });
+    expect(onChange).toHaveBeenCalledTimes(ON_CHANGE_CALLS.initial);
+    dispatchWindow('scroll');
+    expect(onChange).toHaveBeenCalledTimes(ON_CHANGE_CALLS.afterScroll);
+    dispatchWindow('resize');
+    expect(onChange).toHaveBeenCalledTimes(ON_CHANGE_CALLS.afterResize);
+    cleanup();
+  });
+  it('중첩 컨테이너의 scroll(비버블링) 도 capture 로 포착한다', () => {
+    installResizeObserverStub();
+    const anchor = createAnchor();
+    const container = document.createElement('div');
+    document.body.appendChild(container);
+    const onChange = vi.fn();
+    const cleanup = observeAnchorGeometry({
+      getAnchor: () => anchor.element,
+      getPanel: () => null,
+      onChange
+    });
+    container.dispatchEvent(new Event('scroll', {
+      bubbles: false
+    }));
+    expect(onChange).toHaveBeenCalledTimes(ON_CHANGE_CALLS.afterScroll);
+    cleanup();
+  });
+  it('anchor 와 panel 각각에 ResizeObserver 를 붙인다', () => {
+    const {
+      instances
+    } = installResizeObserverStub();
+    const anchor = createAnchor();
+    const panel = createPanel();
+    const cleanup = observeAnchorGeometry({
+      getAnchor: () => anchor.element,
+      getPanel: () => panel,
+      onChange: vi.fn()
+    });
+    expect(instances).toHaveLength(2);
+    expect(instances[0]?.observe).toHaveBeenCalledWith(anchor.element);
+    expect(instances[1]?.observe).toHaveBeenCalledWith(panel);
+    cleanup();
+  });
+  it('구독 시점에 panel 이 없으면 anchor 옵저버만 만든다', () => {
+    const {
+      instances
+    } = installResizeObserverStub();
+    const anchor = createAnchor();
+    const cleanup = observeAnchorGeometry({
+      getAnchor: () => anchor.element,
+      getPanel: () => null,
+      onChange: vi.fn()
+    });
+    expect(instances).toHaveLength(1);
+    cleanup();
+  });
+  it('anchor 가 null 이면 구독하지 않고 no-op cleanup 을 반환한다', () => {
+    const {
+      instances
+    } = installResizeObserverStub();
+    const addEventListener = vi.spyOn(window, 'addEventListener');
+    const onChange = vi.fn();
+    const cleanup = observeAnchorGeometry({
+      getAnchor: () => null,
+      getPanel: () => null,
+      onChange
+    });
+    expect(onChange).not.toHaveBeenCalled();
+    expect(addEventListener).not.toHaveBeenCalled();
+    expect(instances).toHaveLength(0);
+    expect(() => cleanup()).not.toThrow();
+  });
+});
+describe('observeAnchorGeometry — cleanup (E-7)', () => {
+  it('cleanup 뒤에는 이벤트가 발생해도 onChange 가 늘지 않고 옵저버가 disconnect 된다', () => {
+    const {
+      instances
+    } = installResizeObserverStub();
+    const anchor = createAnchor();
+    const panel = createPanel();
+    const onChange = vi.fn();
+    const cleanup = observeAnchorGeometry({
+      getAnchor: () => anchor.element,
+      getPanel: () => panel,
+      onChange
+    });
+    cleanup();
+    dispatchWindow('scroll');
+    dispatchWindow('resize');
+    expect(onChange).toHaveBeenCalledTimes(ON_CHANGE_CALLS.initial);
+    for (const instance of instances) {
+      expect(instance.disconnect).toHaveBeenCalledTimes(1);
+    }
+  });
+});
+describe('observeAnchorGeometry — ResizeObserver 미정의 환경 (E-8)', () => {
+  it('ResizeObserver 가 없어도 예외 없이 window 이벤트만 구독한다', () => {
+    expect('ResizeObserver' in globalThis).toBe(false);
+    const anchor = createAnchor();
+    const onChange = vi.fn();
+    let cleanup = () => undefined;
+    expect(() => {
+      cleanup = observeAnchorGeometry({
+        getAnchor: () => anchor.element,
+        getPanel: () => null,
+        onChange
+      });
+    }).not.toThrow();
+    dispatchWindow('scroll');
+    expect(onChange).toHaveBeenCalledTimes(ON_CHANGE_CALLS.afterScroll);
+    cleanup();
+  });
+});
+describe('trackPortalPosition — 측정·조립 합성', () => {
+  it('구독 직후 anchor·panel 실측값으로 조립한 style 을 onUpdate 에 동기 전달한다', () => {
+    installResizeObserverStub();
+    const rect = makeAnchorRect();
+    const anchor = createAnchor(rect);
+    const panel = createPanel();
+    const onUpdate = vi.fn();
+    const cleanup = trackPortalPosition({
+      getAnchor: () => anchor.element,
+      getPanel: () => panel,
+      direction: 'down',
+      align: 'right',
+      onUpdate
+    });
+    expect(onUpdate).toHaveBeenCalledTimes(1);
+    expect(onUpdate).toHaveBeenLastCalledWith(buildPortalPanelStyle({
+      anchorRect: rect,
+      panelHeight: PANEL_HEIGHT,
+      panelWidth: PANEL_WIDTH,
+      direction: 'down',
+      align: 'right'
+    }));
+    cleanup();
+  });
+  it('panel 이 아직 없으면 panelHeight 0 · panelWidth 는 anchor 너비로 조립한다', () => {
+    installResizeObserverStub();
+    const rect = makeAnchorRect();
+    const anchor = createAnchor(rect);
+    const onUpdate = vi.fn();
+    const cleanup = trackPortalPosition({
+      getAnchor: () => anchor.element,
+      getPanel: () => null,
+      direction: 'up',
+      align: 'right',
+      onUpdate
+    });
+    expect(onUpdate).toHaveBeenLastCalledWith({
+      position: 'fixed',
+      top: rect.top - DEFAULT_OFFSET,
+      left: rect.right - rect.width,
+      zIndex: EXPECTED_Z_INDEX
+    });
+    cleanup();
+  });
+  it('matchAnchorWidth=true 이면 minWidth 를 anchor 너비로 낸다', () => {
+    installResizeObserverStub();
+    const rect = makeAnchorRect();
+    const anchor = createAnchor(rect);
+    const panel = createPanel();
+    const onUpdate = vi.fn();
+    const cleanup = trackPortalPosition({
+      getAnchor: () => anchor.element,
+      getPanel: () => panel,
+      direction: 'down',
+      matchAnchorWidth: true,
+      onUpdate
+    });
+    expect(onUpdate.mock.lastCall?.[0].minWidth).toBe(rect.width);
+    cleanup();
+  });
+  it('scroll 이 발생하면 anchor 를 다시 측정해 갱신된 style 을 전달한다', () => {
+    installResizeObserverStub();
+    const anchor = createAnchor(makeAnchorRect());
+    const panel = createPanel();
+    const movedRect = makeAnchorRect({
+      top: 60,
+      bottom: 100
+    });
+    const onUpdate = vi.fn();
+    const cleanup = trackPortalPosition({
+      getAnchor: () => anchor.element,
+      getPanel: () => panel,
+      direction: 'down',
+      onUpdate
+    });
+    anchor.moveTo(movedRect);
+    dispatchWindow('scroll');
+    expect(onUpdate).toHaveBeenCalledTimes(2);
+    expect(onUpdate.mock.lastCall?.[0].top).toBe(movedRect.bottom + DEFAULT_OFFSET);
+    cleanup();
+  });
+  it('getPanel 이 나중에 요소를 반환하면 다음 갱신에 panelHeight 가 반영된다', () => {
+    installResizeObserverStub();
+    const rect = makeAnchorRect();
+    const anchor = createAnchor(rect);
+    const panel = createPanel();
+    const mounted = {
+      current: null
+    };
+    const onUpdate = vi.fn();
+    const cleanup = trackPortalPosition({
+      getAnchor: () => anchor.element,
+      getPanel: () => mounted.current,
+      direction: 'up',
+      onUpdate
+    });
+    expect(onUpdate.mock.lastCall?.[0].top).toBe(rect.top - DEFAULT_OFFSET);
+    mounted.current = panel;
+    dispatchWindow('scroll');
+    expect(onUpdate.mock.lastCall?.[0].top).toBe(rect.top - PANEL_HEIGHT - DEFAULT_OFFSET);
+    cleanup();
+  });
+  it('anchor 가 null 이면 onUpdate 를 호출하지 않고 리스너도 붙이지 않는다', () => {
+    installResizeObserverStub();
+    const addEventListener = vi.spyOn(window, 'addEventListener');
+    const onUpdate = vi.fn();
+    const cleanup = trackPortalPosition({
+      getAnchor: () => null,
+      getPanel: () => null,
+      direction: 'down',
+      onUpdate
+    });
+    expect(onUpdate).not.toHaveBeenCalled();
+    expect(addEventListener).not.toHaveBeenCalled();
+    expect(() => cleanup()).not.toThrow();
+  });
+  it('cleanup 뒤에는 scroll 이 발생해도 onUpdate 가 늘지 않는다', () => {
+    installResizeObserverStub();
+    const anchor = createAnchor();
+    const onUpdate = vi.fn();
+    const cleanup = trackPortalPosition({
+      getAnchor: () => anchor.element,
+      getPanel: () => null,
+      direction: 'down',
+      onUpdate
+    });
+    cleanup();
+    dispatchWindow('scroll');
+    expect(onUpdate).toHaveBeenCalledTimes(1);
+  });
+});
+describe('trackPortalPosition — direction 게터 (추가형 API)', () => {
+  it('direction 에 함수를 넘기면 갱신마다 그 반환값으로 조립한다', () => {
+    installResizeObserverStub();
+    const anchor = createAnchor();
+    const panel = createPanel();
+    const onUpdate = vi.fn();
+    let direction = 'down';
+    trackPortalPosition({
+      getAnchor: () => anchor.element,
+      getPanel: () => panel,
+      direction: () => direction,
+      onUpdate
+    });
+    direction = 'up';
+    dispatchWindow('scroll');
+    expect(onUpdate.mock.calls[0][0].top).toBe(makeAnchorRect().bottom + DEFAULT_OFFSET);
+    expect(onUpdate.mock.calls[1][0].top).toBe(makeAnchorRect().top - PANEL_HEIGHT - DEFAULT_OFFSET);
+  });
+});
+describe('applyPortalPanelStyle — vanilla 어댑터 보조', () => {
+  it('position·top·left·zIndex 를 px 단위로 element.style 에 적용한다', () => {
+    const element = document.createElement('div');
+    applyPortalPanelStyle(element, {
+      position: 'fixed',
+      top: 144,
+      left: 50,
+      zIndex: EXPECTED_Z_INDEX
+    });
+    expect(element.style.position).toBe('fixed');
+    expect(element.style.top).toBe('144px');
+    expect(element.style.left).toBe('50px');
+    expect(element.style.zIndex).toBe('1500');
+    expect(element.style.minWidth).toBe('');
+  });
+  it('minWidth 가 있으면 px 단위로 함께 적용한다', () => {
+    const element = document.createElement('div');
+    applyPortalPanelStyle(element, {
+      position: 'fixed',
+      top: 144,
+      left: 50,
+      zIndex: EXPECTED_Z_INDEX,
+      minWidth: 200
+    });
+    expect(element.style.minWidth).toBe('200px');
+  });
+  it('이전 호출에서 minWidth 가 설정된 요소에 minWidth 없는 스타일을 적용하면 minWidth 를 제거한다', () => {
+    const element = document.createElement('div');
+    applyPortalPanelStyle(element, {
+      position: 'fixed',
+      top: 0,
+      left: 0,
+      zIndex: EXPECTED_Z_INDEX,
+      minWidth: 200
+    });
+    applyPortalPanelStyle(element, {
+      position: 'fixed',
+      top: 10,
+      left: 0,
+      zIndex: EXPECTED_Z_INDEX
+    });
+    expect(element.style.minWidth).toBe('');
+  });
+});

package/dist/esm/src/utils/portal-position/index.js

@@ -0,0 +1 @@
+export * from './portalPosition';

package/dist/esm/src/utils/portal-position/portalPosition.js

@@ -0,0 +1,150 @@
+const DEFAULT_OFFSET = 4;
+const DEFAULT_GAP = 20;
+const noop = () => undefined;
+const observeElementResize = (target, onChange) => {
+  if (target === null || typeof ResizeObserver === 'undefined') {
+    return null;
+  }
+  const observer = new ResizeObserver(onChange);
+  observer.observe(target);
+  return observer;
+};
+const measurePortalPanelStyle = _ref => {
+  let {
+    getAnchor,
+    getPanel,
+    direction,
+    align,
+    offset,
+    matchAnchorWidth
+  } = _ref;
+  const anchor = getAnchor();
+  if (anchor === null) {
+    return null;
+  }
+  const panel = getPanel();
+  return buildPortalPanelStyle({
+    anchorRect: anchor.getBoundingClientRect(),
+    panelHeight: panel?.offsetHeight ?? 0,
+    // matchAnchorWidth 이면 패널 너비를 쓰지 않으므로 offsetWidth 를 읽지 않는다 — 레이아웃 강제 산출 1회 회피
+    panelWidth: matchAnchorWidth ? null : panel?.offsetWidth ?? null,
+    direction: typeof direction === 'function' ? direction() : direction,
+    align,
+    offset,
+    matchAnchorWidth
+  });
+};
+export const PORTAL_PANEL_Z_INDEX = 1500;
+export const computePortalPosition = _ref2 => {
+  let {
+    anchorRect,
+    panelHeight,
+    panelWidth,
+    direction,
+    align = 'left',
+    offset = DEFAULT_OFFSET
+  } = _ref2;
+  return {
+    top: direction === 'up' ? anchorRect.top - panelHeight - offset : anchorRect.bottom + offset,
+    left: align === 'right' ? anchorRect.right - panelWidth : anchorRect.left
+  };
+};
+export const resolveDropdownDirection = _ref3 => {
+  let {
+    anchorRect,
+    panelHeight,
+    viewportHeight,
+    gap = DEFAULT_GAP
+  } = _ref3;
+  return viewportHeight - anchorRect.bottom < panelHeight + gap ? 'up' : 'down';
+};
+export const buildPortalPanelStyle = _ref4 => {
+  let {
+    anchorRect,
+    panelHeight,
+    panelWidth,
+    direction,
+    align,
+    offset,
+    matchAnchorWidth = false
+  } = _ref4;
+  const effectivePanelWidth = matchAnchorWidth || panelWidth === null ? anchorRect.width : panelWidth;
+  const {
+    top,
+    left
+  } = computePortalPosition({
+    anchorRect,
+    panelHeight,
+    panelWidth: effectivePanelWidth,
+    direction,
+    align,
+    offset
+  });
+  const base = {
+    position: 'fixed',
+    top,
+    left,
+    zIndex: PORTAL_PANEL_Z_INDEX
+  };
+  // width 가 아니라 min-width 인 이유: 패널은 max-content 로 자연 확장하되 앵커보다 좁아지지만 않게 한다.
+  // 옵션이 짧으면 앵커 너비, 길면 자연 확장 — Portal 이전 absolute 모드와 동일한 UX.
+  return matchAnchorWidth ? {
+    ...base,
+    minWidth: anchorRect.width
+  } : base;
+};
+export const observeAnchorGeometry = _ref5 => {
+  let {
+    getAnchor,
+    getPanel,
+    onChange
+  } = _ref5;
+  const anchor = getAnchor();
+  if (anchor === null) {
+    return noop;
+  }
+  onChange();
+  window.addEventListener('scroll', onChange, {
+    passive: true,
+    capture: true
+  });
+  window.addEventListener('resize', onChange);
+  const observers = [observeElementResize(anchor, onChange), observeElementResize(getPanel(), onChange)];
+  return () => {
+    window.removeEventListener('scroll', onChange, {
+      capture: true
+    });
+    window.removeEventListener('resize', onChange);
+    for (const observer of observers) {
+      observer?.disconnect();
+    }
+  };
+};
+export const trackPortalPosition = _ref6 => {
+  let {
+    onUpdate,
+    ...measureOptions
+  } = _ref6;
+  return observeAnchorGeometry({
+    getAnchor: measureOptions.getAnchor,
+    getPanel: measureOptions.getPanel,
+    onChange: () => {
+      const style = measurePortalPanelStyle(measureOptions);
+      if (style !== null) {
+        onUpdate(style);
+      }
+    }
+  });
+};
+// TODO(#497): vanilla 어댑터 도입 시 소비
+export const applyPortalPanelStyle = (element, style) => {
+  element.style.position = style.position;
+  element.style.top = `${style.top}px`;
+  element.style.left = `${style.left}px`;
+  element.style.zIndex = String(style.zIndex);
+  if (style.minWidth === undefined) {
+    element.style.removeProperty('min-width');
+    return;
+  }
+  element.style.minWidth = `${style.minWidth}px`;
+};

package/dist/temp/assets/scripts/notification/const/sizes.d.ts

@@ -28,5 +28,5 @@ export declare const getSizes: {
     readonly featuredIcon: (isMobile: boolean) => "sm" | "md";
     readonly iconPixel: (isMobile: boolean) => "20" | "16";
     readonly closeButton: (isMobile: boolean) => "xs" | "sm";
-    readonly closeButtonSvg: (size: keyof typeof CLOSE_BUTTON_SVG_SIZES) => 16 | 20;
+    readonly closeButtonSvg: (size: keyof typeof CLOSE_BUTTON_SVG_SIZES) => 20 | 16;
 };

package/dist/temp/src/components/action/button-group/ButtonGroup.d.ts

@@ -107,7 +107,7 @@ declare const ButtonGroup: {
         "aria-description"?: string | undefined;
         "aria-details"?: string | undefined;
         "aria-disabled"?: (boolean | "true" | "false") | undefined;
-        "aria-dropeffect"?: "link" | "none" | "copy" | "execute" | "move" | "popup" | undefined;
+        "aria-dropeffect"?: "copy" | "link" | "none" | "execute" | "move" | "popup" | undefined;
         "aria-errormessage"?: string | undefined;
         "aria-expanded"?: (boolean | "true" | "false") | undefined;
         "aria-flowto"?: string | undefined;

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 { BadgeType, BadgeColor, BadgeSize, BadgeProps };
+export type { BadgeColor, BadgeProps, BadgeSize, BadgeType };

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: 16 };
+const NEW_BADGE_ICON_SIZE = { sm: 12, md: 14 };
 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

@@ -34,6 +34,12 @@ interface ComboBoxProps extends Omit<ComponentPropsWithRef<'div'>, 'size' | 'onC
      * 완료 버튼 클릭 시 호출되는 콜백 — 현재 선택된 값을 인자로 받음 (multiple 모드에서만 트리거)
      */
     onComplete?: OptionChangeHandler;
+    /**
+     * 옵션 패널을 React Portal로 body에 렌더한다. 기본값 false — 명시적으로 켠 경우에만 동작한다.
+     * SelectBox·Dropdown 과 달리 FloatingContext.preferPortal 을 따르지 않는다. 컨텍스트를 따르면
+     * Table horizontalScroll 안의 기존 ComboBox 가 옵션 지정 없이 Portal 로 전환되기 때문이다.
+     */
+    usePortal?: boolean;
 }
 declare const ComboBox: import("react").ForwardRefExoticComponent<Omit<ComboBoxProps, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
 export { defaultMaxHeight, ComboBox };