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

package/dist/cjs/src/components/forms-and-input/input-base/InputBase.js

@@ -12,11 +12,9 @@ var _color = require("../../../../constant/color");
 var _HintText = require("../../shared/hintText/HintText");
 var _Label = require("../../shared/label/Label");
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
-const validationSvgSize = {
-  xs: 14,
-  sm: 16
-};
-const generalSvgSize = {
+// 슬롯 아이콘(leadingElement/trailingElement)과 상태 아이콘(clear·validation·destructive)은 같은 크기를 쓴다.
+// slot.size 를 명시하면 그 값이 우선한다.
+const iconSvgSize = {
   xs: 14,
   sm: 20
 };
@@ -42,19 +40,26 @@ const InputBase = exports.InputBase = /*#__PURE__*/(0, _react.forwardRef)((_ref,
   } = _ref;
   const inputRef = (0, _react.useRef)(null);
   const [textCount, setTextCount] = (0, _react.useState)(0);
+  const [hasValue, setHasValue] = (0, _react.useState)(false);
+  // 값 유무는 DOM에서 읽는다 — props.value로 판정하면 uncontrolled Input에서 항상 빈 값으로 보인다.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: controlled 값이 프로그래밍적으로 바뀔 때는 input 이벤트가 나지 않아 props.value로 재동기화해야 한다
   (0, _react.useEffect)(() => {
-    if (inputRef.current && showTextCount) {
-      setTextCount(inputRef.current.value.length);
-      const handleInput = () => {
-        setTextCount(inputRef.current?.value.length ?? 0);
-      };
-      inputRef.current.addEventListener('input', handleInput);
-      return () => {
-        inputRef.current?.removeEventListener('input', handleInput);
-      };
-    }
-  }, [showTextCount]);
-  const renderOutsideSlot = slot => {
+    const input = inputRef.current;
+    if (!input) return;
+    const syncFromInput = () => {
+      const {
+        length
+      } = input.value;
+      setHasValue(length > 0);
+      setTextCount(length);
+    };
+    syncFromInput();
+    input.addEventListener('input', syncFromInput);
+    return () => {
+      input.removeEventListener('input', syncFromInput);
+    };
+  }, [props.value]);
+  const renderOutsideSlot = (slot, position) => {
     if (slot.type === 'custom' && slot.placement !== 'outside') {
       return null;
     }
@@ -68,7 +73,7 @@ const InputBase = exports.InputBase = /*#__PURE__*/(0, _react.forwardRef)((_ref,
         });
       case 'text':
         return (0, _jsxRuntime.jsx)("span", {
-          className: (0, _classnames.default)('ncua-input__leading-text', `ncua-input__leading-text--${size}`),
+          className: (0, _classnames.default)(`ncua-input__${position}-text`, `ncua-input__${position}-text--${size}`),
           children: slot.text
         });
       case 'custom':
@@ -85,10 +90,15 @@ const InputBase = exports.InputBase = /*#__PURE__*/(0, _react.forwardRef)((_ref,
           return (0, _jsxRuntime.jsx)("div", {
             className: "ncua-input__icon-wrap",
             children: (0, _jsxRuntime.jsx)(SlotIcon, {
-              className: (0, _classnames.default)(`ncua-input__${position}-icon`, slot.className),
+              className: (0, _classnames.default)(`ncua-input__${position}-icon`,
+              // color 를 지정하지 않았을 때만 상태별 색(Placeholder/Filled/Focused/Disabled)을 CSS 에 맡긴다.
+              // 지정한 경우에는 이 클래스를 붙이지 않아 지정 색이 그대로 유지된다.
+              {
+                'ncua-input__slot-icon': !slot.color
+              }, slot.className),
               color: slot.color ? _color.COLOR[slot.color] : undefined,
-              width: slot.size ?? generalSvgSize[size],
-              height: slot.size ?? generalSvgSize[size]
+              width: slot.size ?? iconSvgSize[size],
+              height: slot.size ?? iconSvgSize[size]
             })
           });
         }
@@ -109,8 +119,8 @@ const InputBase = exports.InputBase = /*#__PURE__*/(0, _react.forwardRef)((_ref,
       onClick: onClearText,
       children: (0, _jsxRuntime.jsx)(_uiAdminIcon.X, {
         className: "ncua-input__clear-icon",
-        width: validationSvgSize[size],
-        height: validationSvgSize[size]
+        width: iconSvgSize[size],
+        height: iconSvgSize[size]
       })
     });
   };
@@ -120,8 +130,8 @@ const InputBase = exports.InputBase = /*#__PURE__*/(0, _react.forwardRef)((_ref,
         className: "ncua-input__icon-wrap ncua-input__right-icon",
         children: (0, _jsxRuntime.jsx)(_uiAdminIcon.InfoCircle, {
           className: "ncua-input__destructive-icon",
-          width: validationSvgSize[size],
-          height: validationSvgSize[size]
+          width: iconSvgSize[size],
+          height: iconSvgSize[size]
         })
       });
     }
@@ -130,8 +140,8 @@ const InputBase = exports.InputBase = /*#__PURE__*/(0, _react.forwardRef)((_ref,
         className: "ncua-input__icon-wrap ncua-input__right-icon",
         children: (0, _jsxRuntime.jsx)(_uiAdminIcon.CheckCircle, {
           className: "ncua-input__validation-icon",
-          width: validationSvgSize[size],
-          height: validationSvgSize[size]
+          width: iconSvgSize[size],
+          height: iconSvgSize[size]
         })
       });
     }
@@ -156,13 +166,15 @@ const InputBase = exports.InputBase = /*#__PURE__*/(0, _react.forwardRef)((_ref,
       'is-disabled': disabled,
       'full-width': fullWidth,
       'ncua-input__trailing-button': trailingElement?.type === 'button',
-      'ncua-input__leading-text-wrap': leadingElement?.type === 'text'
+      'ncua-input__leading-text-wrap': leadingElement?.type === 'text',
+      'ncua-input__trailing-text-wrap': trailingElement?.type === 'text',
+      'has-value': hasValue
     }, className),
     children: [renderLabel(), (0, _jsxRuntime.jsxs)("div", {
       className: "ncua-input__content-wrap",
       children: [(0, _jsxRuntime.jsxs)("div", {
         className: "ncua-input__content",
-        children: [leadingElement && renderOutsideSlot(leadingElement), (0, _jsxRuntime.jsxs)("div", {
+        children: [leadingElement && renderOutsideSlot(leadingElement, 'leading'), (0, _jsxRuntime.jsxs)("div", {
           className: (0, _classnames.default)('ncua-input__field', `ncua-input__field--${size}`),
           children: [leadingElement && renderInsideSlot(leadingElement, 'left'), (0, _jsxRuntime.jsx)("input", {
             ref: node => {
@@ -178,7 +190,7 @@ const InputBase = exports.InputBase = /*#__PURE__*/(0, _react.forwardRef)((_ref,
             maxLength: maxLength,
             ...props
           }), renderClearButton(), renderStatusIcon(), trailingElement && renderInsideSlot(trailingElement, 'right')]
-        }), trailingElement && renderOutsideSlot(trailingElement)]
+        }), trailingElement && renderOutsideSlot(trailingElement, 'trailing')]
       }), showTextCount && maxLength && (0, _jsxRuntime.jsxs)("div", {
         className: "ncua-input__field-text-count",
         children: [(0, _jsxRuntime.jsx)("output", {

package/dist/cjs/src/components/forms-and-input/input-base/__tests__/InputBase.test.js

@@ -1,9 +1,11 @@
 "use strict";
 
+var _uiAdminIcon = require("@ncds/ui-admin-icon");
 var _react = require("react");
 var _client = require("react-dom/client");
 var _testUtils = require("react-dom/test-utils");
 var _vitest = require("vitest");
+var _color = require("../../../../../constant/color");
 var _InputBase = require("../InputBase");
 // @vitest-environment jsdom
 
@@ -69,4 +71,230 @@ function mountInputBase() {
     (0, _vitest.expect)(view.container.querySelector('.ncua-input__clear')).toBeNull();
     view.unmount();
   });
+});
+(0, _vitest.describe)('InputBase — 아이콘 사이즈', () => {
+  const iconSizeOf = (container, selector) => {
+    const svg = container.querySelector(selector);
+    return {
+      width: svg?.getAttribute('width'),
+      height: svg?.getAttribute('height')
+    };
+  };
+  // 슬롯 아이콘과 상태 아이콘은 같은 크기를 쓴다 — 과거 상태 아이콘만 sm=16으로 어긋나 있었다
+  _vitest.it.each([['xs', '14'], ['sm', '20']])('size=%s 일 때 슬롯 아이콘과 상태 아이콘이 모두 %spx로 렌더된다', (size, expected) => {
+    // Given/When: 슬롯 아이콘과 clear 버튼, destructive 상태를 함께 렌더하면
+    const view = mountInputBase({
+      size,
+      destructive: true,
+      clearText: true,
+      onClearText: _vitest.vi.fn(),
+      leadingElement: {
+        type: 'icon',
+        icon: _uiAdminIcon.SearchLg
+      }
+    });
+    // Then: 슬롯·clear·destructive 아이콘의 크기가 서로 어긋나지 않는다
+    const expectedSize = {
+      width: expected,
+      height: expected
+    };
+    (0, _vitest.expect)(iconSizeOf(view.container, '.ncua-input__left-icon')).toEqual(expectedSize);
+    (0, _vitest.expect)(iconSizeOf(view.container, '.ncua-input__clear-icon')).toEqual(expectedSize);
+    (0, _vitest.expect)(iconSizeOf(view.container, '.ncua-input__destructive-icon')).toEqual(expectedSize);
+    view.unmount();
+  });
+  _vitest.it.each([['xs', '14'], ['sm', '20']])('size=%s 일 때 validation 아이콘도 %spx로 렌더된다', (size, expected) => {
+    // Given/When: validation 상태로 렌더하면
+    const view = mountInputBase({
+      size,
+      validation: true
+    });
+    // Then: 다른 아이콘과 같은 크기다
+    (0, _vitest.expect)(iconSizeOf(view.container, '.ncua-input__validation-icon')).toEqual({
+      width: expected,
+      height: expected
+    });
+    view.unmount();
+  });
+  (0, _vitest.it)('slot.size를 직접 주면 기본 사이즈보다 우선한다', () => {
+    // Given/When: 슬롯에 size를 명시해 렌더하면
+    const view = mountInputBase({
+      size: 'xs',
+      leadingElement: {
+        type: 'icon',
+        icon: _uiAdminIcon.SearchLg,
+        size: 24
+      }
+    });
+    // Then: 기본값(14)이 아니라 명시한 값이 적용된다
+    (0, _vitest.expect)(iconSizeOf(view.container, '.ncua-input__left-icon')).toEqual({
+      width: '24',
+      height: '24'
+    });
+    view.unmount();
+  });
+});
+(0, _vitest.describe)('InputBase — 슬롯 아이콘 상태 색상', () => {
+  // 상태별 색은 CSS 가 결정한다. jsdom 에서는 스타일시트를 로드하지 않으므로
+  // "상태 규칙을 타는 클래스가 붙었는지" 와 "지정 색이 인라인으로 남았는지" 로 검증한다.
+  const leftIconOf = container => container.querySelector('.ncua-input__left-icon');
+  (0, _vitest.it)('color 를 지정하지 않으면 상태 색상 클래스가 붙는다', () => {
+    // Given/When: color 없이 슬롯 아이콘을 렌더하면
+    const view = mountInputBase({
+      leadingElement: {
+        type: 'icon',
+        icon: _uiAdminIcon.SearchLg
+      }
+    });
+    // Then: 상태 규칙을 타는 클래스가 붙고, 인라인 색은 지정되지 않는다
+    const icon = leftIconOf(view.container);
+    (0, _vitest.expect)(icon?.classList.contains('ncua-input__slot-icon')).toBe(true);
+    (0, _vitest.expect)(icon?.hasAttribute('color')).toBe(false);
+    view.unmount();
+  });
+  (0, _vitest.it)('color 를 지정하면 상태 색상 클래스가 붙지 않고 지정 색이 유지된다', () => {
+    // Given/When: color 를 지정해 렌더하면
+    const view = mountInputBase({
+      leadingElement: {
+        type: 'icon',
+        icon: _uiAdminIcon.SearchLg,
+        color: 'blue500'
+      }
+    });
+    // Then: 상태 규칙에서 제외되고 지정한 색이 그대로 남는다
+    const icon = leftIconOf(view.container);
+    (0, _vitest.expect)(icon?.classList.contains('ncua-input__slot-icon')).toBe(false);
+    (0, _vitest.expect)(icon?.getAttribute('color')).toBe(_color.COLOR.blue500);
+    view.unmount();
+  });
+  (0, _vitest.it)('slot.className 을 함께 주어도 상태 색상 클래스가 유지된다', () => {
+    // Given/When: className 을 추가로 넘기면
+    const view = mountInputBase({
+      leadingElement: {
+        type: 'icon',
+        icon: _uiAdminIcon.SearchLg,
+        className: 'my-icon'
+      }
+    });
+    // Then: 두 클래스가 모두 붙는다
+    const icon = leftIconOf(view.container);
+    (0, _vitest.expect)(icon?.classList.contains('ncua-input__slot-icon')).toBe(true);
+    (0, _vitest.expect)(icon?.classList.contains('my-icon')).toBe(true);
+    view.unmount();
+  });
+});
+(0, _vitest.describe)('InputBase — has-value 상태 클래스', () => {
+  const typeInto = (container, text) => {
+    const input = container.querySelector('input');
+    if (!input) throw new Error('input이 렌더되지 않았습니다');
+    (0, _testUtils.act)(() => {
+      input.value = text;
+      input.dispatchEvent(new Event('input', {
+        bubbles: true
+      }));
+    });
+  };
+  (0, _vitest.it)('값이 비어 있으면 has-value가 붙지 않는다', () => {
+    // Given/When: 빈 상태로 렌더하면
+    const view = mountInputBase();
+    // Then: 루트에 has-value가 없다
+    (0, _vitest.expect)(view.container.querySelector('.ncua-input')?.classList.contains('has-value')).toBe(false);
+    view.unmount();
+  });
+  // props.value 로 판정하면 uncontrolled 에서 영원히 빈 값으로 보인다 — 자물쇠 아이콘 색상이 반영되지 않던 원인
+  (0, _vitest.it)('uncontrolled Input에 입력하면 has-value가 붙는다', () => {
+    // Given: value를 넘기지 않은 uncontrolled 상태에서
+    const view = mountInputBase();
+    // When: 실제로 입력하면
+    typeInto(view.container, 'hello');
+    // Then: has-value가 붙는다
+    (0, _vitest.expect)(view.container.querySelector('.ncua-input')?.classList.contains('has-value')).toBe(true);
+    view.unmount();
+  });
+  (0, _vitest.it)('입력값을 지우면 has-value가 떨어진다', () => {
+    // Given: 값이 있는 상태에서
+    const view = mountInputBase();
+    typeInto(view.container, 'hello');
+    // When: 값을 비우면
+    typeInto(view.container, '');
+    // Then: has-value가 사라진다
+    (0, _vitest.expect)(view.container.querySelector('.ncua-input')?.classList.contains('has-value')).toBe(false);
+    view.unmount();
+  });
+  (0, _vitest.it)('controlled Input은 value prop만으로도 has-value가 붙는다', () => {
+    // Given/When: value를 직접 넘겨 렌더하면 (input 이벤트 없이)
+    const view = mountInputBase({
+      value: 'preset',
+      onChange: _vitest.vi.fn()
+    });
+    // Then: has-value가 붙는다
+    (0, _vitest.expect)(view.container.querySelector('.ncua-input')?.classList.contains('has-value')).toBe(true);
+    view.unmount();
+  });
+});
+(0, _vitest.describe)('InputBase — 텍스트 슬롯', () => {
+  (0, _vitest.it)('leadingElement 텍스트는 leading 클래스와 wrap 클래스가 붙는다', () => {
+    const {
+      container,
+      unmount
+    } = mountInputBase({
+      leadingElement: {
+        type: 'text',
+        text: 'https://'
+      }
+    });
+    const text = container.querySelector('.ncua-input__leading-text');
+    (0, _vitest.expect)(text?.textContent).toBe('https://');
+    (0, _vitest.expect)(container.querySelector('.ncua-input__leading-text-wrap')).not.toBeNull();
+    unmount();
+  });
+  (0, _vitest.it)('trailingElement 텍스트는 trailing 클래스와 wrap 클래스가 붙는다', () => {
+    const {
+      container,
+      unmount
+    } = mountInputBase({
+      trailingElement: {
+        type: 'text',
+        text: 'px'
+      }
+    });
+    const text = container.querySelector('.ncua-input__trailing-text');
+    (0, _vitest.expect)(text?.textContent).toBe('px');
+    (0, _vitest.expect)(container.querySelector('.ncua-input__trailing-text-wrap')).not.toBeNull();
+    // leading 클래스가 섞이면 모서리·테두리 방향이 반대가 된다
+    (0, _vitest.expect)(container.querySelector('.ncua-input__leading-text')).toBeNull();
+    unmount();
+  });
+  (0, _vitest.it)('trailingElement 텍스트는 입력 필드 뒤에 온다', () => {
+    const {
+      container,
+      unmount
+    } = mountInputBase({
+      trailingElement: {
+        type: 'text',
+        text: 'px'
+      }
+    });
+    const content = container.querySelector('.ncua-input__content');
+    const children = Array.from(content?.children ?? []);
+    const fieldIndex = children.findIndex(el => el.classList.contains('ncua-input__field'));
+    const textIndex = children.findIndex(el => el.classList.contains('ncua-input__trailing-text'));
+    (0, _vitest.expect)(fieldIndex).toBeGreaterThanOrEqual(0);
+    (0, _vitest.expect)(textIndex).toBeGreaterThan(fieldIndex);
+    unmount();
+  });
+  (0, _vitest.it)('사이즈 modifier 가 함께 붙는다', () => {
+    const {
+      container,
+      unmount
+    } = mountInputBase({
+      size: 'sm',
+      trailingElement: {
+        type: 'text',
+        text: 'px'
+      }
+    });
+    (0, _vitest.expect)(container.querySelector('.ncua-input__trailing-text--sm')).not.toBeNull();
+    unmount();
+  });
 });

package/dist/cjs/src/components/forms-and-input/password-input/PasswordInput.js

@@ -33,8 +33,9 @@ const PasswordInput = exports.PasswordInput = /*#__PURE__*/(0, _react.forwardRef
     type: isVisible ? 'text' : 'password',
     leadingElement: {
       type: 'icon',
-      icon: _uiAdminIcon.Lock01,
-      color: props.value ? 'gray600' : 'gray300'
+      icon: _uiAdminIcon.Lock01
+      // color 를 넘기지 않아 슬롯 아이콘 공통 규칙(상태별 색)을 그대로 따른다.
+      // 여기서 props.value 로 판정하면 uncontrolled Input 에서 영원히 빈 값 취급된다.
     },
     trailingElement: {
       type: 'custom',

package/dist/cjs/src/components/forms-and-input/password-input/__tests__/PasswordInput.test.js

@@ -0,0 +1,59 @@
+"use strict";
+
+var _react = require("react");
+var _client = require("react-dom/client");
+var _testUtils = require("react-dom/test-utils");
+var _vitest = require("vitest");
+var _PasswordInput = require("../PasswordInput");
+// @vitest-environment jsdom
+
+// React 18에서 act() 사용 시 필요한 플래그 (미설정 시 console.error 경고 발생)
+globalThis.IS_REACT_ACT_ENVIRONMENT = true;
+function mountPasswordInput() {
+  let props = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+  const container = document.createElement('div');
+  document.body.appendChild(container);
+  const root = (0, _client.createRoot)(container);
+  (0, _testUtils.act)(() => {
+    root.render(/*#__PURE__*/(0, _react.createElement)(_PasswordInput.PasswordInput, props));
+  });
+  const unmount = () => {
+    (0, _testUtils.act)(() => {
+      root.unmount();
+    });
+    container.remove();
+  };
+  return {
+    container,
+    unmount
+  };
+}
+(0, _vitest.describe)('PasswordInput — 자물쇠 아이콘 색상', () => {
+  // 자물쇠 색은 CSS 가 결정한다. 인라인 color 를 넘기면 상태 규칙이 무시되므로,
+  // "인라인 색이 없고 슬롯 아이콘 공통 클래스를 탄다" 는 것이 색상 반영의 전제다.
+  (0, _vitest.it)('자물쇠에 인라인 색을 넘기지 않고 슬롯 아이콘 공통 클래스를 탄다', () => {
+    // Given/When: 기본 상태로 렌더하면
+    const view = mountPasswordInput();
+    // Then: 상태 규칙을 타는 클래스가 붙고 인라인 색은 없다
+    const lockIcon = view.container.querySelector('.ncua-input__left-icon');
+    (0, _vitest.expect)(lockIcon).not.toBeNull();
+    (0, _vitest.expect)(lockIcon?.classList.contains('ncua-input__slot-icon')).toBe(true);
+    (0, _vitest.expect)(lockIcon?.hasAttribute('color')).toBe(false);
+    view.unmount();
+  });
+  // 값이 있는 채로 비활성화되면 has-value 가 살아 있어 자물쇠가 진하게 남던 문제
+  (0, _vitest.it)('값이 있는 채로 disabled 여도 자물쇠가 상태 규칙 대상으로 남는다', () => {
+    // Given/When: 값이 있는 비활성화 상태로 렌더하면
+    const view = mountPasswordInput({
+      value: 'secret',
+      disabled: true,
+      onChange: _vitest.vi.fn()
+    });
+    // Then: 루트에 is-disabled 와 has-value 가 함께 붙고, 자물쇠는 공통 클래스를 유지한다
+    const root = view.container.querySelector('.ncua-input');
+    (0, _vitest.expect)(root?.classList.contains('is-disabled')).toBe(true);
+    (0, _vitest.expect)(root?.classList.contains('has-value')).toBe(true);
+    (0, _vitest.expect)(view.container.querySelector('.ncua-input__left-icon')?.classList.contains('ncua-input__slot-icon')).toBe(true);
+    view.unmount();
+  });
+});

package/dist/cjs/src/components/index.js

@@ -388,6 +388,17 @@ Object.keys(_divider).forEach(function (key) {
     }
   });
 });
+var _ncuaScope = require("./layout/ncua-scope");
+Object.keys(_ncuaScope).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _ncuaScope[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _ncuaScope[key];
+    }
+  });
+});
 var _pageTitle = require("./layout/page-title");
 Object.keys(_pageTitle).forEach(function (key) {
   if (key === "default" || key === "__esModule") return;

package/dist/cjs/src/components/layout/ncua-scope/NcuaScope.js

@@ -0,0 +1,73 @@
+"use strict";
+'use client';
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.NcuaScope = void 0;
+var _jsxRuntime = require("react/jsx-runtime");
+var _classnames = _interopRequireDefault(require("classnames"));
+var _react = require("react");
+var _scopedCss = require("../../../generated/scoped-css");
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+// 조상에 NcuaScope 가 이미 있으면 스타일을 다시 심지 않는다 (중첩 대응).
+const NcuaStyleMountedContext = /*#__PURE__*/(0, _react.createContext)(false);
+// React 19 는 <style> 에 href·precedence 가 함께 있으면 <head> 로 올리고 href 로 중복을
+// 제거한다. 18 에는 그 기능도, 두 prop 의 타입 정의도 없어 Context 로 중첩만 막고
+// 타입은 우회한다.
+const STYLE_HOISTING_MIN_REACT_MAJOR = 19;
+const DECIMAL_RADIX = 10;
+const SUPPORTS_STYLE_HOISTING = Number.parseInt(_react.version, DECIMAL_RADIX) >= STYLE_HOISTING_MIN_REACT_MAJOR;
+const STYLE_KEY = 'ncua-scoped';
+const STYLE_HOISTING_PROPS = {
+  href: STYLE_KEY,
+  precedence: 'default'
+};
+/**
+ * NCUA 스타일을 이 엘리먼트 하위로 한정하는 경계.
+ *
+ * 다른 디자인 시스템을 전역 적용한 사용처에서 NCUA 컴포넌트를 이걸로 감싼다.
+ * 스타일을 직접 들고 있으므로 **CSS 파일을 따로 import 하지 않는다.**
+ *
+ * ```tsx
+ * import { NcuaScope, Button } from '@ncds/ui-admin';
+ *
+ * <NcuaScope>
+ *   <Button label="신청하기" hierarchy="primary" size="md" />
+ * </NcuaScope>
+ * ```
+ *
+ * `document.body` 로 portal 되는 컴포넌트(Modal · Tooltip · Dropdown · SelectBox ·
+ * Notification)는 이 경계 밖에 놓이지만, 스코프 스타일시트가 그 루트 클래스들을 함께
+ * 지정하므로 토큰을 받는다 (`base/_scope.scss` 의 `$roots`). portal 목적지는 바뀌지
+ * 않으므로 어드민에서의 기존 동작과 같다.
+ *
+ * 어드민처럼 `style.css` 를 전역 적용하는 사용처는 이 컴포넌트가 필요 없다.
+ *
+ * 중첩해서 써도 스타일은 한 번만 들어간다. React 19 에서는 형제로 여러 개를 써도
+ * href 기준으로 중복이 제거된다. React 18 에서는 형제마다 `<style>` 이 하나씩 생기므로,
+ * 스코프가 여러 곳에 필요하면 공통 조상 한 곳에서 감싸는 편이 낫다.
+ */
+const NcuaScope = exports.NcuaScope = /*#__PURE__*/(0, _react.forwardRef)((_ref, ref) => {
+  let {
+    className,
+    children
+  } = _ref;
+  const styleAlreadyMounted = (0, _react.useContext)(NcuaStyleMountedContext);
+  const shouldRenderStyle = SUPPORTS_STYLE_HOISTING || !styleAlreadyMounted;
+  return (0, _jsxRuntime.jsxs)(NcuaStyleMountedContext.Provider, {
+    value: true,
+    children: [shouldRenderStyle && (SUPPORTS_STYLE_HOISTING ? (0, _jsxRuntime.jsx)("style", {
+      ...STYLE_HOISTING_PROPS,
+      children: _scopedCss.NCUA_SCOPED_CSS
+    }) : (0, _jsxRuntime.jsx)("style", {
+      "data-ncua-scope": STYLE_KEY,
+      children: _scopedCss.NCUA_SCOPED_CSS
+    })), (0, _jsxRuntime.jsx)("div", {
+      ref: ref,
+      className: (0, _classnames.default)('ncua-scope', className),
+      children: children
+    })]
+  });
+});
+NcuaScope.displayName = 'NcuaScope';

package/dist/cjs/src/components/layout/ncua-scope/index.js

@@ -0,0 +1,16 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+var _NcuaScope = require("./NcuaScope");
+Object.keys(_NcuaScope).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _NcuaScope[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _NcuaScope[key];
+    }
+  });
+});