@ncds/ui-admin 1.8.21-alpha.4 → 1.8.21-alpha.5

package/dist/esm/assets/scripts/notification/MessageNotification.js

@@ -1,7 +1,8 @@
 import { FeaturedIcon } from '../featuredIcon';
 import { sanitizeHtml } from '../utils/sanitize';
-import { CLASS_NAMES, FLOATING_ICON_MAP, MESSAGE_SIZES, SVG_ICONS } from './const';
-import { bindNotificationEvents, createWrapperElement, renderActions, renderSupportingText, setupAutoClose } from './utils';
+import { CLASS_NAMES, FLOATING_ICON_MAP, MESSAGE_SIZES } from './const';
+import { buildMessageTemplate } from './messageTemplate';
+import { bindNotificationEvents, createWrapperElement, setupAutoClose } from './utils';
 export class MessageNotification {
   constructor(options) {
     this.options = {
@@ -41,11 +42,14 @@ export class MessageNotification {
         svgString: iconSvg,
         theme: 'light-circle',
         color: actualColor,
-        size: MESSAGE_SIZES.FEATURED_ICON
+        size: MESSAGE_SIZES.FEATURED_ICON,
+        // React 구현과 동일하게 `__icon`(flex-shrink: 0)을 부여한다.
+        // 누락 시 긴 타이틀에서 아이콘이 찌그러진다.
+        className: CLASS_NAMES.MESSAGE.ICON
       });
       featuredIconElement = this.featuredIcon.getElement();
     }
-    wrapper.innerHTML = sanitizeHtml(this.buildTemplate({
+    wrapper.innerHTML = sanitizeHtml(buildMessageTemplate({
       title,
       supportingText,
       actions,
@@ -61,50 +65,6 @@ export class MessageNotification {
     }
     return wrapper;
   }
-  buildTemplate(params) {
-    const {
-      title,
-      supportingText,
-      actions,
-      onClose,
-      onHidePermanently
-    } = params;
-    return `
-      <div class="${CLASS_NAMES.MESSAGE.CONTAINER}">
-        <div class="${CLASS_NAMES.MESSAGE.CONTENT}">
-          <div class="${CLASS_NAMES.MESSAGE.CONTENT_WRAPPER}">
-            <div class="${CLASS_NAMES.MESSAGE.TEXT_CONTAINER}">
-              <span class="${CLASS_NAMES.MESSAGE.TITLE}">${title}</span>
-              ${renderSupportingText(supportingText, CLASS_NAMES.MESSAGE.SUPPORTING_TEXT)}
-            </div>
-          </div>
-          <div class="${CLASS_NAMES.MESSAGE.ACTIONS_CONTAINER}">
-            ${actions && actions.length > 0 ? renderActions(actions, CLASS_NAMES.MESSAGE.ACTIONS) : ''}
-          </div>
-          <div class="${CLASS_NAMES.MESSAGE.ACTIONS_CONTAINER}">
-            ${this.renderHidePermanentlyButton(onHidePermanently)}
-            ${this.renderCloseButton(onClose)}
-          </div>
-        </div>
-      </div>
-    `;
-  }
-  renderHidePermanentlyButton(onHidePermanently) {
-    if (!onHidePermanently) return '';
-    return `
-      <button type="button" class="${CLASS_NAMES.COMMON.ACTION_BUTTON} ${CLASS_NAMES.COMMON.ACTION_BUTTON}--text ${CLASS_NAMES.MESSAGE.HIDE_LINK}" data-hide-permanently="true">
-        다시 보지 않기
-      </button>
-    `;
-  }
-  renderCloseButton(onClose) {
-    if (!onClose) return '';
-    return `
-      <button type="button" class="${CLASS_NAMES.MESSAGE.CLOSE_BUTTON}" aria-label="알림 닫기">
-        ${SVG_ICONS['x-close'](MESSAGE_SIZES.CLOSE_BUTTON).replace('stroke="currentColor"', `stroke="#2F2F30"`)}
-      </button>
-    `;
-  }
   bindEvents() {
     bindNotificationEvents(this.element, this.options.actions, this.options.onClose, () => this.remove());
     // 다시보지 않기 버튼 이벤트 바인딩

package/dist/esm/assets/scripts/notification/const/classNames.js

@@ -35,6 +35,9 @@ export const CLASS_NAMES = {
     SUPPORTING_TEXT: 'ncua-message-notification__supporting-text',
     ACTIONS_CONTAINER: 'ncua-message-notification__actions-container',
     ACTIONS: 'ncua-message-notification__actions',
+    // 다시 보지 않기 + 닫기 그룹 전용 래퍼. ACTIONS_CONTAINER를 재사용하면
+    // 해당 클래스의 gap(12px)이 그룹 내부에도 적용되어 8px 규격이 깨진다.
+    FOOTER_CONTAINER: 'ncua-message-notification__footer-container',
     HIDE_LINK: 'ncua-message-notification__hide-link',
     CLOSE_BUTTON: 'ncua-message-notification__close-button'
   },

package/dist/esm/assets/scripts/notification/const/index.js

@@ -1,4 +1,5 @@
-export { SVG_ICONS, FLOATING_ICON_MAP, FULL_WIDTH_ICON_MAP, ICON_MAP } from './icons';
+// Re-export all constants and types from separate files
 export { CLASS_NAMES } from './classNames';
-export { FEATURED_ICON_SIZES, ICON_PIXEL_SIZES, CLOSE_BUTTON_SIZES, CLOSE_BUTTON_SVG_SIZES, FULL_WIDTH_SIZES, MESSAGE_SIZES, getSizes } from './sizes';
+export { FLOATING_ICON_MAP, FULL_WIDTH_ICON_MAP, ICON_MAP, SVG_ICONS } from './icons';
+export { CLOSE_BUTTON_SIZES, CLOSE_BUTTON_SVG_SIZES, FEATURED_ICON_SIZES, FULL_WIDTH_SIZES, getSizes, ICON_PIXEL_SIZES, MESSAGE_SIZES } from './sizes';
 export { MESSAGE_CLOSE_ICON_COLORS } from './types';

package/dist/esm/assets/scripts/notification/const/sizes.js

@@ -26,9 +26,11 @@ export const FULL_WIDTH_SIZES = {
   CLOSE_BUTTON: '20'
 };
 // Message 알림 고정 사이즈
+// FEATURED_ICON(원 크기)과 ICON_PIXEL(내부 SVG 크기)은 항상 짝을 맞춰야 한다.
+// 'md' = 40px 원 / 20px 아이콘 (FeaturedIcon iconSizeMap 기준)
 export const MESSAGE_SIZES = {
-  FEATURED_ICON: 'lg',
-  ICON_PIXEL: '24',
+  FEATURED_ICON: 'md',
+  ICON_PIXEL: '20',
   CLOSE_BUTTON: '20'
 };
 // 사이즈 유틸리티 함수들

package/dist/esm/assets/scripts/notification/messageTemplate.js

@@ -0,0 +1,71 @@
+import { CLASS_NAMES, MESSAGE_SIZES, SVG_ICONS } from './const';
+import { renderActions, renderSupportingText } from './utils';
+/**
+ * message 타입 액션 버튼 사이즈. TO-BE 규격 28px이며 React `<Button size="xs">`와 같다.
+ * floating / full-width는 이 값을 쓰지 않고 `renderActions`의 기본값('sm')을 유지한다.
+ */
+const ACTION_BUTTON_SIZE = 'xs';
+/**
+ * Message Notification의 마크업을 만든다.
+ * React 구현(`src/components/overlays/notification/MessageNotification.tsx`)과
+ * 동일한 클래스 트리를 산출해야 한다 — SCSS 한 벌을 두 구현이 공유한다.
+ */
+export function buildMessageTemplate(params) {
+  const {
+    title,
+    supportingText,
+    actions,
+    onClose,
+    onHidePermanently
+  } = params;
+  return `
+    <div class="${CLASS_NAMES.MESSAGE.CONTAINER}">
+      <div class="${CLASS_NAMES.MESSAGE.CONTENT}">
+        <div class="${CLASS_NAMES.MESSAGE.CONTENT_WRAPPER}">
+          <div class="${CLASS_NAMES.MESSAGE.TEXT_CONTAINER}">
+            <span class="${CLASS_NAMES.MESSAGE.TITLE}">${title}</span>
+            ${renderSupportingText(supportingText, CLASS_NAMES.MESSAGE.SUPPORTING_TEXT)}
+          </div>
+        </div>
+        ${renderActionsContainer(actions, onClose, onHidePermanently)}
+      </div>
+    </div>
+  `;
+}
+/**
+ * 액션 버튼 그룹과 닫기 그룹을 함께 감싸는 우측 영역.
+ * 이 컨테이너의 gap(12px)이 두 그룹 사이 간격을 만든다.
+ * 표시할 요소가 하나도 없으면 빈 컨테이너를 남기지 않는다.
+ */
+function renderActionsContainer(actions, onClose, onHidePermanently) {
+  const actionsHtml = renderActions(actions ?? [], CLASS_NAMES.MESSAGE.ACTIONS, ACTION_BUTTON_SIZE);
+  const footerHtml = renderFooterContainer(onClose, onHidePermanently);
+  if (!actionsHtml && !footerHtml) return '';
+  return `<div class="${CLASS_NAMES.MESSAGE.ACTIONS_CONTAINER}">${actionsHtml}${footerHtml}</div>`;
+}
+/** 다시 보지 않기 + 닫기 그룹. 전용 래퍼를 쓰는 이유는 `CLASS_NAMES.MESSAGE.FOOTER_CONTAINER` 참조. */
+function renderFooterContainer(onClose, onHidePermanently) {
+  if (!onHidePermanently && !onClose) return '';
+  return `
+    <div class="${CLASS_NAMES.MESSAGE.FOOTER_CONTAINER}">
+      ${renderHidePermanentlyButton(onHidePermanently)}
+      ${renderCloseButton(onClose)}
+    </div>
+  `;
+}
+function renderHidePermanentlyButton(onHidePermanently) {
+  if (!onHidePermanently) return '';
+  return `
+    <button type="button" class="${CLASS_NAMES.COMMON.ACTION_BUTTON} ${CLASS_NAMES.MESSAGE.HIDE_LINK}" data-hide-permanently="true">
+      다시 보지 않기
+    </button>
+  `;
+}
+function renderCloseButton(onClose) {
+  if (!onClose) return '';
+  return `
+    <button type="button" class="${CLASS_NAMES.MESSAGE.CLOSE_BUTTON}" aria-label="알림 닫기">
+      ${SVG_ICONS['x-close'](MESSAGE_SIZES.CLOSE_BUTTON).replace('stroke="currentColor"', 'stroke="#2F2F30"')}
+    </button>
+  `;
+}

package/dist/esm/assets/scripts/notification/utils.js

@@ -45,16 +45,51 @@ export function renderSupportingText(supportingText, className, supportTextLink)
   // unsafe URL이거나 link가 없으면 링크 없이 텍스트만 렌더링
   return `<span class="${className}">${supportingText}</span>`;
 }
+/** 액션 버튼 색상을 지정하지 않았을 때의 기본값. React `MessageNotificationParts`와 같다. */
+const DEFAULT_ACTION_HIERARCHY = 'text';
+/**
+ * 액션 버튼의 색상 수식자를 현행 어휘로 정규화한다.
+ *
+ * 구 어휘(`'link'` / `'link-gray'`)는 Link 컴포넌트의 색상 이름을 빌려 쓴 것이라
+ * `ncua-btn--link`에 대응하는 CSS가 존재하지 않았다. 기존 CDN 사용처를 깨지 않기 위해
+ * 타입에서 제거하는 대신 이 지점에서 실제 Button 테마로 매핑한다.
+ *
+ * 렌더(`renderActions`)와 이벤트 바인딩(`bindNotificationEvents`)이 이 함수를 함께 써야
+ * `data-action` 키가 어긋나지 않는다.
+ */
+export function resolveActionHierarchy(hierarchy) {
+  switch (hierarchy) {
+    case undefined:
+      return DEFAULT_ACTION_HIERARCHY;
+    case 'link':
+      return 'text';
+    case 'link-gray':
+      return 'text-gray';
+    default:
+      return hierarchy;
+  }
+}
+/** 액션 버튼의 클릭 라우팅 키. 렌더와 바인딩이 같은 규칙으로 만들어야 한다. */
+function buildActionKey(action) {
+  return `${action.label}-${resolveActionHierarchy(action.hierarchy)}`;
+}
+/**
+ * 액션 버튼 그룹 HTML을 만든다.
+ *
+ * `size` 기본값 'sm'은 floating / full-width 타입의 기존 렌더링을 그대로 보존하기 위한 것이다.
+ * message 타입만 TO-BE 규격(28px)에 맞춰 'xs'를 넘긴다 — React `<Button size="xs">`와 동일.
+ */
 export function renderActions(actions, wrapperClass) {
+  let size = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : 'sm';
   // 액션이 없으면 빈 문자열 반환
   if (!actions || actions.length === 0) {
     return '';
   }
   const buttonsHtml = actions.map(action => {
     const buttonHtml = `
-      <button 
-        class="ncua-btn ncua-btn--sm ncua-btn--${action.hierarchy || 'text'}"
-        data-action="${action.label}-${action.hierarchy}"
+      <button
+        class="ncua-btn ncua-btn--${size} ncua-btn--${resolveActionHierarchy(action.hierarchy)}"
+        data-action="${buildActionKey(action)}"
       >
         ${action.label}
       </button>`;
@@ -80,7 +115,7 @@ export function bindNotificationEvents(element, actions, onClose, onRemove) {
       if (actionData) {
         let matchedAction = null;
         for (const action of actions) {
-          const expectedDataAction = `${action.label}-${action.hierarchy || 'link'}`;
+          const expectedDataAction = buildActionKey(action);
           if (actionData === expectedDataAction) {
             matchedAction = action;
             break;

package/dist/esm/src/components/overlays/notification/MessageNotification.js

@@ -1,10 +1,9 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { AlertCircle, AlertTriangle, CheckCircle, Pin02, XClose } from '@ncds/ui-admin-icon';
+import { AlertCircle, AlertTriangle, CheckCircle, Pin02 } from '@ncds/ui-admin-icon';
 import classNames from 'classnames';
 import { forwardRef } from 'react';
 import { COLOR } from '../../../../constant/color';
-import { Button } from '../../action/button';
-import { FeaturedIcon } from '../../image-and-icons/featured-icon/FeaturedIcon';
+import { MessageNotificationActions, MessageNotificationContent } from './MessageNotificationParts';
 const iconMap = {
   neutral: Pin02,
   error: AlertTriangle,
@@ -31,14 +30,6 @@ const MessageNotification = /*#__PURE__*/forwardRef((_ref, ref) => {
   } = _ref;
   // message 타입은 neutral, error, warning, success 4가지 색상만 지원
   const validColor = color === 'info' ? 'neutral' : color;
-  const iconColor = validColor;
-  const featuredIconProps = {
-    icon: Icon || iconMap[validColor] || Pin02,
-    size: 'lg',
-    color: iconColor,
-    theme: 'light-circle'
-  };
-  const closeIconColor = COLOR[iconColorMap[validColor] || 'gray700'];
   return _jsx("div", {
     ref: ref,
     className: classNames('ncua-message-notification', `ncua-message-notification--${validColor}`, className),
@@ -48,50 +39,17 @@ const MessageNotification = /*#__PURE__*/forwardRef((_ref, ref) => {
       className: "ncua-message-notification__container",
       children: _jsxs("div", {
         className: "ncua-message-notification__content",
-        children: [_jsxs("div", {
-          className: "ncua-message-notification__content-wrapper",
-          children: [iconMap[validColor] && _jsx(FeaturedIcon, {
-            ...featuredIconProps,
-            className: "ncua-message-notification__icon"
-          }), _jsxs("div", {
-            className: "ncua-message-notification__text-container",
-            children: [_jsx("span", {
-              className: "ncua-message-notification__title",
-              children: title
-            }), supportingText && _jsx("span", {
-              className: "ncua-message-notification__supporting-text",
-              children: supportingText
-            })]
-          })]
-        }), _jsx("div", {
-          className: "ncua-message-notification__actions-container",
-          children: actions && _jsx("div", {
-            className: "ncua-message-notification__actions",
-            children: actions.map(action => _jsx(Button, {
-              size: "xs",
-              hierarchy: action.hierarchy || 'text',
-              label: action.label,
-              onClick: action?.onClick
-            }, `${action.label}-${action.hierarchy}`))
-          })
-        }), _jsxs("div", {
-          className: "ncua-message-notification__footer-container",
-          children: [onHidePermanently && _jsx("button", {
-            type: "button",
-            className: classNames('ncua-notification__action-button', 'ncua-notification__action-button--link', 'ncua-message-notification__hide-link'),
-            onClick: onHidePermanently,
-            children: "\uB2E4\uC2DC \uBCF4\uC9C0 \uC54A\uAE30"
-          }), onClose && _jsx("button", {
-            type: "button",
-            className: "ncua-message-notification__close-button",
-            onClick: onClose,
-            "aria-label": "\uC54C\uB9BC \uB2EB\uAE30",
-            children: _jsx(XClose, {
-              width: 20,
-              height: 20,
-              color: closeIconColor
-            })
-          })]
+        children: [_jsx(MessageNotificationContent, {
+          title: title,
+          supportingText: supportingText,
+          icon: Icon || iconMap[validColor],
+          iconColor: validColor,
+          showIcon: Boolean(iconMap[validColor])
+        }), _jsx(MessageNotificationActions, {
+          actions: actions,
+          onClose: onClose,
+          onHidePermanently: onHidePermanently,
+          closeIconColor: COLOR[iconColorMap[validColor] || 'gray700']
         })]
       })
     })

package/dist/esm/src/components/overlays/notification/MessageNotificationParts.js

@@ -0,0 +1,83 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Pin02, XClose } from '@ncds/ui-admin-icon';
+import { Button } from '../../action/button';
+import { FeaturedIcon } from '../../image-and-icons/featured-icon/FeaturedIcon';
+/** 아이콘 + 제목/서포팅 텍스트 영역. */
+const MessageNotificationContent = _ref => {
+  let {
+    title,
+    supportingText,
+    icon,
+    iconColor,
+    showIcon
+  } = _ref;
+  const featuredIconProps = {
+    icon: icon || Pin02,
+    size: 'md',
+    color: iconColor,
+    theme: 'light-circle'
+  };
+  return _jsxs("div", {
+    className: "ncua-message-notification__content-wrapper",
+    children: [showIcon && _jsx(FeaturedIcon, {
+      ...featuredIconProps,
+      className: "ncua-message-notification__icon"
+    }), _jsxs("div", {
+      className: "ncua-message-notification__text-container",
+      children: [_jsx("span", {
+        className: "ncua-message-notification__title",
+        children: title
+      }), supportingText && _jsx("span", {
+        className: "ncua-message-notification__supporting-text",
+        children: supportingText
+      })]
+    })]
+  });
+};
+/**
+ * 액션 버튼 그룹 + 닫기 그룹을 감싸는 우측 영역.
+ * 이 컨테이너의 gap(12px)이 두 그룹 사이 간격을 만든다.
+ * 표시할 요소가 하나도 없으면 빈 컨테이너를 남기지 않는다.
+ */
+const MessageNotificationActions = _ref2 => {
+  let {
+    actions,
+    onClose,
+    onHidePermanently,
+    closeIconColor
+  } = _ref2;
+  const hasActions = Boolean(actions?.length);
+  const hasFooter = Boolean(onHidePermanently || onClose);
+  if (!hasActions && !hasFooter) return null;
+  return _jsxs("div", {
+    className: "ncua-message-notification__actions-container",
+    children: [hasActions && _jsx("div", {
+      className: "ncua-message-notification__actions",
+      children: actions?.map(action => _jsx(Button, {
+        size: "xs",
+        hierarchy: action.hierarchy || 'text',
+        label: action.label,
+        onClick: action?.onClick
+      }, `${action.label}-${action.hierarchy}`))
+    }), hasFooter && _jsxs("div", {
+      className: "ncua-message-notification__footer-container",
+      children: [onHidePermanently && _jsx("button", {
+        type: "button",
+        className: "ncua-notification__action-button ncua-message-notification__hide-link",
+        onClick: onHidePermanently,
+        children: "\uB2E4\uC2DC \uBCF4\uC9C0 \uC54A\uAE30"
+      }), onClose && _jsx("button", {
+        type: "button",
+        className: "ncua-message-notification__close-button",
+        onClick: onClose,
+        "aria-label": "\uC54C\uB9BC \uB2EB\uAE30",
+        children: _jsx(XClose, {
+          width: 20,
+          height: 20,
+          color: closeIconColor
+        })
+      })]
+    })]
+  });
+};
+export { MessageNotificationActions, MessageNotificationContent };

package/dist/esm/src/components/overlays/notification/__tests__/MessageNotification.test.js

@@ -0,0 +1,243 @@
+// @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 { MessageNotification } from '../MessageNotification';
+// React 18에서 act() 사용 시 필요한 플래그 (미설정 시 console.error 경고 발생)
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+const SELECTOR = {
+  ROOT: '.ncua-message-notification',
+  CONTENT: '.ncua-message-notification__content',
+  CONTENT_WRAPPER: '.ncua-message-notification__content-wrapper',
+  ICON: '.ncua-message-notification__icon',
+  ACTIONS_CONTAINER: '.ncua-message-notification__actions-container',
+  ACTIONS: '.ncua-message-notification__actions',
+  FOOTER_CONTAINER: '.ncua-message-notification__footer-container',
+  HIDE_LINK: '.ncua-message-notification__hide-link',
+  CLOSE_BUTTON: '.ncua-message-notification__close-button'
+};
+const mounted = [];
+function renderMessageNotification() {
+  let props = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+  const container = document.createElement('div');
+  document.body.appendChild(container);
+  const root = createRoot(container);
+  act(() => {
+    root.render(/*#__PURE__*/createElement(MessageNotification, {
+      title: '알림 제목',
+      ...props
+    }));
+  });
+  mounted.push({
+    root,
+    container
+  });
+  return container;
+}
+afterEach(() => {
+  for (const {
+    root,
+    container
+  } of mounted.splice(0)) {
+    act(() => {
+      root.unmount();
+    });
+    container.remove();
+  }
+});
+describe('MessageNotification (React) — DOM 구조 계약', () => {
+  it('U-1: __footer-container가 __actions-container의 자식으로 렌더된다', () => {
+    // Given: 다시 보지 않기·닫기 핸들러가 주어지고
+    // When: MessageNotification을 렌더하면
+    const container = renderMessageNotification({
+      onHidePermanently: vi.fn(),
+      onClose: vi.fn()
+    });
+    // Then: footer-container는 actions-container의 직계 자식이다 (content의 직계 자식이 아니다)
+    const actionsContainer = container.querySelector(SELECTOR.ACTIONS_CONTAINER);
+    const footerContainer = container.querySelector(SELECTOR.FOOTER_CONTAINER);
+    expect(actionsContainer).not.toBeNull();
+    expect(footerContainer).not.toBeNull();
+    expect(footerContainer?.parentElement).toBe(actionsContainer);
+  });
+  it('U-2: actions 지정 시 __actions와 __footer-container가 __actions-container 안에 순서대로 공존한다', () => {
+    // Given: 액션 버튼 2개와 다시 보지 않기·닫기 핸들러가 주어지고
+    const actions = [{
+      label: '조회하기',
+      hierarchy: 'text',
+      onClick: vi.fn()
+    }, {
+      label: '포인트 충전',
+      hierarchy: 'text-gray',
+      onClick: vi.fn()
+    }];
+    // When: 렌더하면
+    const container = renderMessageNotification({
+      actions,
+      onHidePermanently: vi.fn(),
+      onClose: vi.fn()
+    });
+    // Then: actions-container의 자식은 [actions, footer-container] 순서다
+    const actionsContainer = container.querySelector(SELECTOR.ACTIONS_CONTAINER);
+    const actionsGroup = container.querySelector(SELECTOR.ACTIONS);
+    const footerContainer = container.querySelector(SELECTOR.FOOTER_CONTAINER);
+    expect(actionsContainer).not.toBeNull();
+    expect(Array.from(actionsContainer?.children ?? [])).toEqual([actionsGroup, footerContainer]);
+  });
+  it('U-3: onHidePermanently·onClose·actions 미지정 시 빈 컨테이너가 남지 않는다', () => {
+    // Given/When: 우측 그룹에 표시할 요소가 하나도 없는 상태로 렌더하면
+    const container = renderMessageNotification();
+    // Then: actions-container도 footer-container도 렌더되지 않는다
+    expect(container.querySelector(SELECTOR.ACTIONS_CONTAINER)).toBeNull();
+    expect(container.querySelector(SELECTOR.FOOTER_CONTAINER)).toBeNull();
+    // 본문 영역은 그대로 유지된다
+    expect(container.querySelector(SELECTOR.CONTENT_WRAPPER)).not.toBeNull();
+  });
+  it('U-3-a: actions만 지정하면 actions-container만 남고 footer-container는 없다', () => {
+    // Given/When: 액션 버튼만 있고 닫기 그룹이 없으면
+    const container = renderMessageNotification({
+      actions: [{
+        label: '조회하기',
+        hierarchy: 'text',
+        onClick: vi.fn()
+      }]
+    });
+    // Then: actions-container는 존재하고 그 자식은 actions 그룹 하나뿐이다
+    const actionsContainer = container.querySelector(SELECTOR.ACTIONS_CONTAINER);
+    const actionsGroup = container.querySelector(SELECTOR.ACTIONS);
+    expect(actionsContainer).not.toBeNull();
+    expect(container.querySelector(SELECTOR.FOOTER_CONTAINER)).toBeNull();
+    expect(Array.from(actionsContainer?.children ?? [])).toEqual([actionsGroup]);
+  });
+  it('U-3-b: onClose만 지정하면 footer-container에 닫기 버튼만 담긴다', () => {
+    // Given/When: 닫기 핸들러만 지정하면
+    const container = renderMessageNotification({
+      onClose: vi.fn()
+    });
+    // Then: footer-container에는 닫기 버튼 1개만 존재하고 hide-link는 없다
+    const footerContainer = container.querySelector(SELECTOR.FOOTER_CONTAINER);
+    expect(footerContainer?.children).toHaveLength(1);
+    expect(footerContainer?.querySelector(SELECTOR.CLOSE_BUTTON)).not.toBeNull();
+    expect(footerContainer?.querySelector(SELECTOR.HIDE_LINK)).toBeNull();
+  });
+  it('U-4: FeaturedIcon이 md 사이즈(40px 원 / 20px 아이콘)로 렌더된다', () => {
+    // Given/When: error 색상으로 렌더하면
+    const container = renderMessageNotification({
+      color: 'error'
+    });
+    // Then: featured-icon은 --md 수식자를 가지며 내부 SVG는 20px다
+    const icon = container.querySelector(SELECTOR.ICON);
+    expect(icon).not.toBeNull();
+    expect(icon?.classList.contains('ncua-featured-icon--md')).toBe(true);
+    expect(icon?.classList.contains('ncua-featured-icon--lg')).toBe(false);
+    expect(icon?.querySelector('svg')?.getAttribute('width')).toBe('20');
+  });
+  it('hide-link는 구현별 수식자(--link/--text) 없이 공통 클래스 2개만 갖는다', () => {
+    // Given/When: 다시 보지 않기 핸들러를 지정해 렌더하면
+    const container = renderMessageNotification({
+      onHidePermanently: vi.fn()
+    });
+    // Then: SCSS 미정의 수식자 --link에 의존하지 않는다
+    const hideLink = container.querySelector(SELECTOR.HIDE_LINK);
+    expect(hideLink?.className.split(' ').filter(Boolean).sort()).toEqual(['ncua-message-notification__hide-link', 'ncua-notification__action-button']);
+  });
+});
+describe('MessageNotification (React) — 공개 API 회귀 방지', () => {
+  it('지원하지 않는 color("info")는 neutral로 폴백한다', () => {
+    // Given/When: message 타입이 지원하지 않는 info 색상을 넘기면
+    const container = renderMessageNotification({
+      color: 'info'
+    });
+    // Then: neutral 수식자로 렌더되고 info 수식자는 없다
+    const root = container.querySelector(SELECTOR.ROOT);
+    expect(root?.classList.contains('ncua-message-notification--neutral')).toBe(true);
+    expect(root?.classList.contains('ncua-message-notification--info')).toBe(false);
+  });
+  it('닫기/다시 보지 않기 클릭 시 핸들러가 호출되고 접근성 속성이 유지된다', () => {
+    // Given: 핸들러를 지정해 렌더하고
+    const onClose = vi.fn();
+    const onHidePermanently = vi.fn();
+    const container = renderMessageNotification({
+      onClose,
+      onHidePermanently
+    });
+    // When: 각 버튼을 클릭하면
+    act(() => {
+      container.querySelector(SELECTOR.CLOSE_BUTTON)?.click();
+      container.querySelector(SELECTOR.HIDE_LINK)?.click();
+    });
+    // Then: 핸들러가 각각 1회 호출되고 role/aria-label이 유지된다
+    expect(onClose).toHaveBeenCalledTimes(1);
+    expect(onHidePermanently).toHaveBeenCalledTimes(1);
+    expect(container.querySelector(SELECTOR.ROOT)?.getAttribute('role')).toBe('alert');
+    expect(container.querySelector(SELECTOR.CLOSE_BUTTON)?.getAttribute('aria-label')).toBe('알림 닫기');
+  });
+});
+describe('MessageNotification (React) — 액션 버튼 색상(hierarchy)', () => {
+  const SIZE_MODIFIER = /^ncua-btn--(xs|sm|md|lg|xl)$/;
+  /** 사이즈를 제외한 `ncua-btn--*` 수식자 = 색상(hierarchy) 수식자. */
+  function buttonHierarchyModifiers(root) {
+    return Array.from(root.querySelectorAll('.ncua-btn')).map(button => Array.from(button.classList).find(name => name.startsWith('ncua-btn--') && !SIZE_MODIFIER.test(name)) ?? '');
+  }
+  it('Figma TO-BE 조합(secondary-gray / secondary)을 ncua-btn 수식자로 반영한다', () => {
+    // Given/When: 조회하기 secondary-gray, 포인트 충전 secondary로 렌더하면
+    const container = renderMessageNotification({
+      actions: [{
+        label: '조회하기',
+        hierarchy: 'secondary-gray',
+        onClick: vi.fn()
+      }, {
+        label: '포인트 충전',
+        hierarchy: 'secondary',
+        onClick: vi.fn()
+      }]
+    });
+    // Then: ButtonTheme와 동일한 수식자가 순서대로 붙는다
+    expect(buttonHierarchyModifiers(container)).toEqual(['ncua-btn--secondary-gray', 'ncua-btn--secondary']);
+  });
+  it('text / text-gray도 계속 지원한다', () => {
+    // Given/When: 기존 어휘로 렌더하면
+    const container = renderMessageNotification({
+      actions: [{
+        label: '조회하기',
+        hierarchy: 'text',
+        onClick: vi.fn()
+      }, {
+        label: '포인트 충전',
+        hierarchy: 'text-gray',
+        onClick: vi.fn()
+      }]
+    });
+    // Then: 기존 수식자가 그대로 유지된다 (회귀 방지)
+    expect(buttonHierarchyModifiers(container)).toEqual(['ncua-btn--text', 'ncua-btn--text-gray']);
+  });
+  it('hierarchy를 생략하면 기본값 text로 렌더한다', () => {
+    // Given/When: 색상을 지정하지 않은 액션을 렌더하면
+    const container = renderMessageNotification({
+      actions: [{
+        label: '확인',
+        onClick: vi.fn()
+      }]
+    });
+    // Then: Button의 기본값(secondary-gray)이 아니라 알림의 기본값 text가 적용된다
+    expect(buttonHierarchyModifiers(container)).toEqual(['ncua-btn--text']);
+  });
+  it('액션 버튼 클릭 시 onClick이 호출된다', () => {
+    // Given: secondary 색상 액션을 렌더하고
+    const onClick = vi.fn();
+    const container = renderMessageNotification({
+      actions: [{
+        label: '포인트 충전',
+        hierarchy: 'secondary',
+        onClick
+      }]
+    });
+    // When: 버튼을 클릭하면
+    act(() => {
+      container.querySelector('.ncua-btn')?.click();
+    });
+    // Then: 핸들러가 1회 호출된다
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
+});