@ncds/ui-admin 1.8.4 → 1.8.5

package/dist/temp/assets/scripts/notification/positionSync.js

@@ -0,0 +1,170 @@
+/**
+ * Floating Notification 호스트 싱글톤 + 위치 동기화
+ *
+ * 본 모듈은 다음 두 가지 책임을 가진다:
+ *   1. `.ncua-floating-notification-host` 싱글톤을 document.body 에 생성·재사용 (mountFloatingNotificationHost).
+ *   2. `.ncua-page-title` 의 rect.bottom 을 추적해 `--ncua-page-title-bottom` CSS 변수로 갱신.
+ *
+ * 두 책임을 한 파일에 두는 이유: 호스트가 처음 생성될 때 positionSync 가 함께 시작되며,
+ * React 측 훅과 vanilla 측 `NcuaNotification.show()` 가 동일 함수를 공유해 호스트 생성 로직이
+ * 한 곳에서만 유지되도록 한다.
+ *
+ * NCDS DES-SPEC-027 §5.1
+ *   · Toast top 좌표 = PageTitle.bottom + 16px (viewport 기준).
+ *   · PageTitle 이 sticky 로 Default/Fixed 변형 사이 높이가 변동(120/56px)하므로 단순 height
+ *     가 아닌 getBoundingClientRect().bottom 을 기준으로 동적 계산해야 한다.
+ *
+ * 동작 특성:
+ *   - 다중 호출 idempotent. ensure/start 가 여러 번 호출되어도 호스트와 리스너는 한 벌만.
+ *   - scroll/resize 는 rAF 로 throttle.
+ *   - PageTitle 추가/제거를 MutationObserver 로 감지해 재바인딩 — body subtree 변경마다
+ *     호출되므로 콜백 자체도 rAF 로 한 프레임당 한 번만 querySelector 가 돌도록 보호.
+ *   - SSR 가드: window/document 미정의 환경에서 ensure/start 는 no-op.
+ *
+ * 내부 상태는 모듈 최상단에 흩어진 `let` 대신 한 객체로 묶어 테스트/HMR 에서 일괄 초기화·검사하기
+ * 쉽도록 한다. 외부에는 함수만 노출되므로 캡슐화는 유지된다.
+ */
+const CSS_VAR = '--ncua-page-title-bottom';
+const PAGE_TITLE_SELECTOR = '.ncua-page-title';
+const HOST_CLASS_NAME = 'ncua-floating-notification-host';
+// add/remove EventListener 의 옵션 객체를 동일 참조로 사용해 capture/passive 미스매치를 차단.
+const SCROLL_OPTIONS = { passive: true, capture: true };
+const RESIZE_OPTIONS = { passive: true };
+const state = {
+    started: false,
+    rafId: null,
+    rebindRafId: null,
+    pageTitle: null,
+    resizeObserver: null,
+    mutationObserver: null,
+};
+/** window/document 가 사용 가능한 브라우저 환경인지 — SSR/Node 가드. */
+function isBrowserEnv() {
+    return typeof window !== 'undefined' && typeof document !== 'undefined';
+}
+function readBottomPx() {
+    if (!state.pageTitle)
+        state.pageTitle = document.querySelector(PAGE_TITLE_SELECTOR);
+    if (!state.pageTitle)
+        return 0;
+    const rect = state.pageTitle.getBoundingClientRect();
+    // viewport 기준 음수는 0으로 클램프 (PageTitle이 스크롤되어 시야에서 벗어난 경우)
+    return Math.max(0, Math.round(rect.bottom));
+}
+function flush() {
+    document.documentElement.style.setProperty(CSS_VAR, `${readBottomPx()}px`);
+    state.rafId = null;
+}
+function schedule() {
+    if (state.rafId !== null)
+        return;
+    state.rafId = window.requestAnimationFrame(flush);
+}
+/** 현재 cached pageTitle 이 여전히 DOM 에 연결되어 있는지 — body subtree 변경 시 빠른 early-return. */
+function pageTitleStillInDom() {
+    return state.pageTitle?.isConnected ?? false;
+}
+function rebindPageTitle() {
+    state.rebindRafId = null;
+    if (pageTitleStillInDom())
+        return;
+    const next = document.querySelector(PAGE_TITLE_SELECTOR);
+    if (next === state.pageTitle)
+        return;
+    state.pageTitle = next;
+    if (state.resizeObserver) {
+        state.resizeObserver.disconnect();
+        // box: 'content-box' 일관성 — startPositionSync 의 첫 observe 와 동일 옵션.
+        if (state.pageTitle)
+            state.resizeObserver.observe(state.pageTitle, { box: 'content-box' });
+    }
+    schedule();
+}
+/**
+ * MutationObserver 콜백 — body subtree 의 모든 변경마다 즉시 querySelector 를 돌리면 비싸므로
+ * 프레임당 한 번으로 throttle. 캐시된 pageTitle 이 아직 DOM 에 있으면 rebindPageTitle 안에서
+ * 추가 비용 없이 early-return 한다.
+ */
+function scheduleRebind() {
+    if (state.rebindRafId !== null)
+        return;
+    state.rebindRafId = window.requestAnimationFrame(rebindPageTitle);
+}
+/**
+ * `.ncua-floating-notification-host` 싱글톤을 보장한다.
+ * **side-effect 함수** — 단순 조회가 아니라 다음을 모두 수행:
+ *   · document.body 에 `<div class="ncua-floating-notification-host">` 를 (필요 시) append
+ *   · 첫 호출 시 startPositionSync() 로 window scroll/resize/MutationObserver/ResizeObserver 부착
+ *   · 한 번 만든 호스트는 페이지 lifetime 동안 유지 — 컴포넌트 언마운트 시에도 제거하지 않는다
+ *     (다음 토스트의 mount 비용을 줄이기 위해 의도된 설계)
+ *
+ * React 측 hook 과 vanilla 측 `NcuaNotification.show()` 가 모두 이 함수를 사용해 호스트 생성
+ * 진입점이 한 곳만 존재한다.
+ *
+ * @returns 생성되었거나 이미 존재하는 호스트 엘리먼트. SSR 환경에서는 null.
+ */
+export function mountFloatingNotificationHost() {
+    if (!isBrowserEnv())
+        return null;
+    let host = document.querySelector(`.${HOST_CLASS_NAME}`);
+    if (!host) {
+        host = document.createElement('div');
+        host.className = HOST_CLASS_NAME;
+        // 호스트는 layout container 일 뿐 — live region 책임은 각 토스트 카드의 role 에 위임.
+        document.body.appendChild(host);
+        startPositionSync();
+    }
+    return host;
+}
+/**
+ * PageTitle ↔ Floating Host 위치 동기화 시작 (idempotent).
+ * `mountFloatingNotificationHost()` 가 자동 호출하므로 일반 사용자는 직접 부를 필요 없음.
+ * SSR/테스트에서 수동 제어가 필요할 때만 export 됨.
+ */
+export function startPositionSync() {
+    if (state.started || !isBrowserEnv())
+        return;
+    state.started = true;
+    state.pageTitle = document.querySelector(PAGE_TITLE_SELECTOR);
+    window.addEventListener('scroll', schedule, SCROLL_OPTIONS);
+    window.addEventListener('resize', schedule, RESIZE_OPTIONS);
+    if (typeof ResizeObserver !== 'undefined') {
+        state.resizeObserver = new ResizeObserver(schedule);
+        // box: 'content-box' 명시 — border/padding 변경으로 인한 콜백 재호출 회피 (DOM mutation 무한 루프 방지).
+        if (state.pageTitle)
+            state.resizeObserver.observe(state.pageTitle, { box: 'content-box' });
+    }
+    if (typeof MutationObserver !== 'undefined') {
+        state.mutationObserver = new MutationObserver(scheduleRebind);
+        state.mutationObserver.observe(document.body, { childList: true, subtree: true });
+    }
+    // 첫 동기화
+    flush();
+}
+/** 동기화 중단 + 리소스 해제. 테스트 종료/HMR 정리 등에 사용. */
+export function stopPositionSync() {
+    if (!state.started)
+        return;
+    state.started = false;
+    window.removeEventListener('scroll', schedule, SCROLL_OPTIONS);
+    window.removeEventListener('resize', schedule, RESIZE_OPTIONS);
+    state.resizeObserver?.disconnect();
+    state.resizeObserver = null;
+    state.mutationObserver?.disconnect();
+    state.mutationObserver = null;
+    if (state.rafId !== null) {
+        window.cancelAnimationFrame(state.rafId);
+        state.rafId = null;
+    }
+    if (state.rebindRafId !== null) {
+        window.cancelAnimationFrame(state.rebindRafId);
+        state.rebindRafId = null;
+    }
+    state.pageTitle = null;
+    // 정리 시 CSS 변수도 초기 상태로 되돌림
+    document.documentElement.style.removeProperty(CSS_VAR);
+}
+/** 외부에서 PageTitle.bottom 값을 강제로 다시 측정해 반영하고 싶을 때. */
+export function syncNow() {
+    flush();
+}

package/dist/temp/assets/scripts/notification/utils.d.ts

@@ -0,0 +1,8 @@
+import type { NotificationAction, NotificationColor } from './const';
+export declare function createWrapperElement(baseClass: string, color: NotificationColor, className?: string): HTMLElement;
+export declare function buildClassName(baseClass: string, color: NotificationColor, className?: string): string;
+export declare function renderSupportingText(supportingText?: string, className?: string, supportTextLink?: string): string;
+export declare function renderActions(actions: NotificationAction[], wrapperClass: string): string;
+export declare function bindNotificationEvents(element: HTMLElement, actions: NotificationAction[], onClose?: () => void, onRemove?: () => void): void;
+export declare function setupAutoClose(autoClose: number, onClose?: () => void, onRemove?: () => void): number | undefined;
+export declare const isMobile: () => boolean;

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

@@ -0,0 +1,115 @@
+import { BREAKPOINT } from '../../../src/constant/breakpoint';
+import { CLASS_NAMES } from './const';
+// 공통 유틸리티 함수들
+export function createWrapperElement(baseClass, color, className) {
+    const wrapper = document.createElement('div');
+    wrapper.className = buildClassName(baseClass, color, className);
+    wrapper.setAttribute('role', 'alert');
+    return wrapper;
+}
+export function buildClassName(baseClass, color, className) {
+    const classes = [baseClass, `${baseClass}--${color}`];
+    if (className) {
+        classes.push(className);
+    }
+    return classes.join(' ');
+}
+/**
+ * http/https 프로토콜만 허용한다.
+ * javascript:, data:, file: 등 위험 프로토콜로 인한 XSS / 외부 페이로드 로딩을 차단.
+ */
+function isSafeUrl(url) {
+    try {
+        const parsed = new URL(url, window.location.origin);
+        return parsed.protocol === 'http:' || parsed.protocol === 'https:';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * HTML 속성 값에 안전하게 삽입하기 위한 최소 이스케이프.
+ * 본문(body)이 아닌 속성 컨텍스트에서의 따옴표 탈출(`" onclick="..."`)을 방지.
+ */
+function escapeHtmlAttr(str) {
+    return str.replace(/&/g, '&').replace(/"/g, '"').replace(/'/g, ''');
+}
+export function renderSupportingText(supportingText, className, supportTextLink) {
+    if (!supportingText)
+        return '';
+    // 본문(supportingText) 자체는 이 함수의 호출 결과가 wrapper.innerHTML에
+    // 들어가기 전에 DOMPurify로 sanitize되므로 별도 이스케이프하지 않는다.
+    // 이렇게 해야 <br>, <strong> 등 서식용 태그가 그대로 동작한다.
+    if (supportTextLink && isSafeUrl(supportTextLink)) {
+        const safeLink = escapeHtmlAttr(supportTextLink);
+        return `<a href="${safeLink}" class="ncua-full-width-notification__link" rel="noopener noreferrer" target="_blank"><span class="${className}">${supportingText}</span></a>`;
+    }
+    // unsafe URL이거나 link가 없으면 링크 없이 텍스트만 렌더링
+    return `<span class="${className}">${supportingText}</span>`;
+}
+export function renderActions(actions, wrapperClass) {
+    // 액션이 없으면 빈 문자열 반환
+    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}"
+      >
+        ${action.label}
+      </button>`;
+        return buttonHtml;
+    })
+        .join('');
+    return `<div class="${wrapperClass}">${buttonsHtml}</div>`;
+}
+// 공통 이벤트 처리
+export function bindNotificationEvents(element, actions, onClose, onRemove) {
+    // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: 닫기/액션 버튼 분기를 한 핸들러에 묶는 기존 구조를 유지. 분리 리팩토링은 별도 작업 범위.
+    element.addEventListener('click', (event) => {
+        const target = event.target;
+        // 닫기 버튼 클릭 처리
+        if (target.matches(`.${CLASS_NAMES.FULL_WIDTH.CLOSE_BUTTON}, .${CLASS_NAMES.FLOATING.CLOSE_BUTTON}`) ||
+            target.closest(`.${CLASS_NAMES.FULL_WIDTH.CLOSE_BUTTON}, .${CLASS_NAMES.FLOATING.CLOSE_BUTTON}`) ||
+            target.closest(`.${CLASS_NAMES.MESSAGE.CLOSE_BUTTON}`)) {
+            onClose?.();
+            onRemove?.();
+            return;
+        }
+        // 액션 버튼 클릭 처리
+        const actionButton = target.closest('.ncua-btn[data-action]');
+        if (actionButton && actions) {
+            const actionData = actionButton.getAttribute('data-action');
+            if (actionData) {
+                let matchedAction = null;
+                for (const action of actions) {
+                    const expectedDataAction = `${action.label}-${action.hierarchy || 'link'}`;
+                    if (actionData === expectedDataAction) {
+                        matchedAction = action;
+                        break;
+                    }
+                }
+                if (matchedAction?.onClick) {
+                    matchedAction.onClick();
+                }
+            }
+        }
+    });
+}
+// 자동 닫기 설정
+export function setupAutoClose(autoClose, onClose, onRemove) {
+    if (autoClose > 0) {
+        return window.setTimeout(() => {
+            onClose?.();
+            onRemove?.();
+        }, autoClose);
+    }
+    return undefined;
+}
+// Mobile detection utility
+export const isMobile = () => {
+    return window.innerWidth <= Number.parseInt(BREAKPOINT.mobile, 10);
+};

package/dist/temp/assets/scripts/shared/ButtonCloseX.d.ts

@@ -0,0 +1,5 @@
+export type ButtonCloseXSize = 'xs' | 'sm' | 'md' | 'lg';
+export type ButtonCloseXTheme = 'dark' | 'light';
+export declare const SVG_SIZE: Record<ButtonCloseXSize, number>;
+export declare const X_CLOSE_SVG: (size: string) => string;
+export declare function ButtonCloseX(size: ButtonCloseXSize, theme?: ButtonCloseXTheme, additionalClasses?: string, ariaLabel?: string, onClick?: () => void): string;

package/dist/temp/assets/scripts/shared/ButtonCloseX.js

@@ -0,0 +1,33 @@
+// 공통 X버튼 로직 (React ButtonCloseX 컴포넌트와 동일한 구조)
+// React ButtonCloseX와 동일한 SVG 사이즈 매핑
+export const SVG_SIZE = {
+    xs: 16,
+    sm: 20,
+    md: 20,
+    lg: 24,
+};
+// X버튼 SVG 아이콘
+export const X_CLOSE_SVG = (size) => `<svg width="${size}" height="${size}" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+    <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M6 18L18 6M6 6l12 12" />
+  </svg>`;
+// X버튼 렌더링 유틸리티 (React ButtonCloseX와 동일한 인터페이스)
+export function ButtonCloseX(size, theme = 'light', additionalClasses = '', ariaLabel = '닫기', onClick) {
+    const svgSize = SVG_SIZE[size];
+    const buttonId = `close-btn-${Math.random().toString(36).substr(2, 9)}`;
+    const buttonHTML = `
+    <button type="button" id="${buttonId}" class="ncua-button-close-x ncua-button-close-x--${size} ncua-button-close-x--${theme} ${additionalClasses}" aria-label="${ariaLabel}">
+      ${X_CLOSE_SVG(svgSize.toString())}
+    </button>
+  `;
+    // onClick이 제공된 경우 이벤트 바인딩
+    if (onClick) {
+        // DOM에 추가된 후 이벤트 바인딩을 위해 setTimeout 사용
+        setTimeout(() => {
+            const button = document.getElementById(buttonId);
+            if (button) {
+                button.addEventListener('click', onClick);
+            }
+        }, 0);
+    }
+    return buttonHTML;
+}

package/dist/temp/assets/scripts/utils/sanitize.d.ts

@@ -0,0 +1,22 @@
+/**
+ * HTML 문자열을 DOMPurify 기본 설정으로 sanitize한다.
+ *
+ * 제거되는 항목 (기본 설정):
+ * - `<script>`, `<iframe>`, `<object>` 등 실행 위험 태그
+ * - `onclick`, `onerror` 등 inline 이벤트 핸들러 속성
+ * - `href="javascript:..."` 같은 javascript: URL
+ *
+ * 유지되는 항목:
+ * - `<svg>`, `<button>`, `<div>`, `<span>`, `<input>` 등 일반 HTML/SVG 태그
+ * - `class`, `style`, `role`, `aria-*`, `data-*` 등 표현용 속성
+ * - SVG 표현 속성 (`viewBox`, `stroke`, `fill` 등)
+ *
+ * 이벤트 바인딩은 addEventListener로 별도 처리할 것.
+ */
+export declare function sanitizeHtml(dirty: string): string;
+/**
+ * 엘리먼트에 콘텐츠를 안전하게 설정한다.
+ * - string: sanitize 후 innerHTML 교체
+ * - HTMLElement: 기존 자식 제거 후 appendChild
+ */
+export declare function setSafeInnerHTML(element: HTMLElement, content: string | HTMLElement): void;

package/dist/temp/assets/scripts/utils/sanitize.js

@@ -0,0 +1,31 @@
+import DOMPurify from 'dompurify';
+/**
+ * HTML 문자열을 DOMPurify 기본 설정으로 sanitize한다.
+ *
+ * 제거되는 항목 (기본 설정):
+ * - `<script>`, `<iframe>`, `<object>` 등 실행 위험 태그
+ * - `onclick`, `onerror` 등 inline 이벤트 핸들러 속성
+ * - `href="javascript:..."` 같은 javascript: URL
+ *
+ * 유지되는 항목:
+ * - `<svg>`, `<button>`, `<div>`, `<span>`, `<input>` 등 일반 HTML/SVG 태그
+ * - `class`, `style`, `role`, `aria-*`, `data-*` 등 표현용 속성
+ * - SVG 표현 속성 (`viewBox`, `stroke`, `fill` 등)
+ *
+ * 이벤트 바인딩은 addEventListener로 별도 처리할 것.
+ */
+export function sanitizeHtml(dirty) {
+    return DOMPurify.sanitize(dirty);
+}
+/**
+ * 엘리먼트에 콘텐츠를 안전하게 설정한다.
+ * - string: sanitize 후 innerHTML 교체
+ * - HTMLElement: 기존 자식 제거 후 appendChild
+ */
+export function setSafeInnerHTML(element, content) {
+    if (content instanceof HTMLElement) {
+        element.replaceChildren(content);
+        return;
+    }
+    element.innerHTML = sanitizeHtml(content);
+}

package/dist/temp/src/components/data-display/data-grid/DataGrid.js

@@ -19,7 +19,7 @@ const ActionBar = ({ children, className, position = 'top', align = 'space-betwe
         'ncua-data-grid__action-bar--space-between': align === 'space-between',
     }), ...rest, children: children }));
 ActionBar.displayName = 'DataGrid.ActionBar';
-const DataGridTable = forwardRef(({ children, className, type = 'horizontal', fixedHeader, maxHeight, hoverable, selectable }, ref) => (_jsx("div", { ref: ref, className: classNames('ncua-data-grid__table', className), children: _jsx(NcuaTable, { className: "ncua-table--in-data-grid", type: type, fixedHeader: fixedHeader, maxHeight: maxHeight, hoverable: hoverable, selectable: selectable, children: children }) })));
+const DataGridTable = forwardRef(({ children, className, type = 'horizontal', fixedHeader, maxHeight, hoverable, selectable, horizontalScroll, minWidth, }, ref) => (_jsx("div", { ref: ref, className: classNames('ncua-data-grid__table', className), children: _jsx(NcuaTable, { className: "ncua-table--in-data-grid", type: type, fixedHeader: fixedHeader, maxHeight: maxHeight, hoverable: hoverable, selectable: selectable, horizontalScroll: horizontalScroll, minWidth: minWidth, children: children }) })));
 DataGridTable.displayName = 'DataGrid.Table';
 const Pagination = ({ children, className, ...rest }) => (_jsx("div", { className: classNames('ncua-data-grid__pagination', className), ...rest, children: children }));
 Pagination.displayName = 'DataGrid.Pagination';

package/dist/temp/src/components/data-display/data-grid/DataGrid.types.d.ts

@@ -29,6 +29,13 @@ export type DataGridTableProps = {
     maxHeight?: string | number;
     hoverable?: boolean;
     selectable?: boolean;
+    /**
+     * 가로 스크롤 활성화 시 외부 wrapper에 overflow-x: auto를 적용하고,
+     * 내부의 SelectBox·Dropdown이 FloatingProvider를 통해 자동으로 Portal 렌더로 전환된다.
+     */
+    horizontalScroll?: boolean;
+    /** 가로 스크롤 트리거 임계 너비. horizontalScroll=true 일 때만 의미가 있다. */
+    minWidth?: string | number;
 };
 export type DataGridPaginationProps = ComponentProps<'div'> & {
     children: ReactNode;

package/dist/temp/src/components/data-display/table/Table.d.ts

@@ -6,6 +6,8 @@ export declare const Table: import("react").ForwardRefExoticComponent<Omit<impor
     maxHeight?: string | number | undefined;
     hoverable?: boolean | undefined;
     selectable?: boolean | undefined;
+    horizontalScroll?: boolean | undefined;
+    minWidth?: string | number | undefined;
     children: ReactNode;
 } & import("react").RefAttributes<HTMLDivElement>> & {
     Header: {
@@ -24,6 +26,7 @@ export declare const Table: import("react").ForwardRefExoticComponent<Omit<impor
         sortDirection?: SortDirection | undefined;
         onSort?: (() => void) | undefined;
         width?: string | number | undefined;
+        minWidth?: string | number | undefined;
     } & import("react").RefAttributes<HTMLTableCellElement>>;
     Cell: import("react").ForwardRefExoticComponent<Omit<import("react").DetailedHTMLProps<import("react").TdHTMLAttributes<HTMLTableDataCellElement>, HTMLTableDataCellElement>, "ref"> & {
         isHeader?: boolean | undefined;
@@ -37,7 +40,7 @@ export declare const Table: import("react").ForwardRefExoticComponent<Omit<impor
         displayName: string;
     };
     ColGroup: {
-        ({ widths }: TableColGroupProps): import("react/jsx-runtime").JSX.Element;
+        ({ widths, minWidths }: TableColGroupProps): import("react/jsx-runtime").JSX.Element;
         displayName: string;
     };
     Empty: {

package/dist/temp/src/components/data-display/table/Table.js

@@ -1,13 +1,17 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { ChevronDown, ChevronSelectorVertical, ChevronUp } from '@ncds/ui-admin-icon';
 import classNames from 'classnames';
-import { Children, forwardRef, useEffect, useRef, } from 'react';
-// ──────────────────────────────────────────────
-// $table-header-height 와 동기화 — sticky thead가 차지하는 높이를 maxHeight에 보상
-const TABLE_HEADER_HEIGHT = 40;
-// 스크롤바 트랙 상하 여백 합계 (top 8px + bottom 8px) — SCSS &--fixed-header &__scrollbar 오프셋과 동기화
-const SCROLLBAR_TRACK_OFFSET = 16;
-const SCROLLBAR_THUMB_MIN_HEIGHT = 40;
+import { Children, forwardRef, useRef, } from 'react';
+import { FloatingProvider } from '../../../contexts/FloatingContext';
+import { TABLE_HEADER_HEIGHT, useTableHorizontalScrollbar, useTableVerticalScrollbar } from './useTableScrollbars';
+// 가로 스크롤 디자인 기준 폭 — 14인치 모니터 + LNB 고려한 디자인 권장 너비
+const DEFAULT_HORIZONTAL_SCROLL_MIN_WIDTH = 1140;
+const FLOATING_PORTAL_VALUE = { preferPortal: true };
+// TABLE_HEADER_HEIGHT·DEFAULT_HORIZONTAL_SCROLL_MIN_WIDTH를 CSS 커스텀 프로퍼티로 주입 — SCSS fallback 단일 소스
+const WRAPPER_STYLE = {
+    '--ncua-table-header-height': `${TABLE_HEADER_HEIGHT}px`,
+    '--ncua-table-default-min-width': `${DEFAULT_HORIZONTAL_SCROLL_MIN_WIDTH}px`,
+};
 // Sort Icons (@ncds/ui-admin-icon)
 // ──────────────────────────────────────────────
 const SORT_ICONS = {
@@ -33,12 +37,12 @@ const Row = forwardRef(({ children, className, selected, status, ...rest }, ref)
         'ncua-table__row--error': status === 'error',
     }), ...rest, children: children })));
 Row.displayName = 'Table.Row';
-const HeaderCell = forwardRef(({ children, className, sortDirection, onSort, width, style, ...rest }, ref) => {
+const HeaderCell = forwardRef(({ children, className, sortDirection, onSort, width, minWidth, style, ...rest }, ref) => {
     const isSortable = sortDirection !== undefined && onSort !== undefined;
     const SortIcon = isSortable ? SORT_ICONS[sortDirection] : undefined;
     return (_jsx("th", { ref: ref, className: classNames('ncua-table__header-cell', className, {
             'ncua-table__header-cell--sortable': isSortable,
-        }), style: { ...style, width }, "aria-sort": isSortable ? ARIA_SORT_MAP[sortDirection] : undefined, onClick: isSortable ? onSort : undefined, ...rest, children: isSortable && SortIcon ? (_jsxs("span", { className: "ncua-table__header-cell-inner", children: [_jsx("span", { className: "ncua-table__header-cell-text", children: children }), _jsx("span", { className: "ncua-table__sort-icon", children: _jsx(SortIcon, { width: 16, height: 16 }) })] })) : (children) }));
+        }), style: { ...style, width, minWidth }, "aria-sort": isSortable ? ARIA_SORT_MAP[sortDirection] : undefined, onClick: isSortable ? onSort : undefined, ...rest, children: isSortable && SortIcon ? (_jsxs("span", { className: "ncua-table__header-cell-inner", children: [_jsx("span", { className: "ncua-table__header-cell-text", children: children }), _jsx("span", { className: "ncua-table__sort-icon", children: _jsx(SortIcon, { width: 16, height: 16 }) })] })) : (children) }));
 });
 HeaderCell.displayName = 'Table.HeaderCell';
 const Cell = forwardRef(({ children, className, isHeader, ...rest }, ref) => {
@@ -52,9 +56,9 @@ const Footer = ({ children, className }) => (_jsx("div", { className: classNames
 Footer.displayName = 'Table.Footer';
 const Pagination = ({ children, className }) => (_jsx("div", { className: classNames('ncua-table__pagination', className), children: children }));
 Pagination.displayName = 'Table.Pagination';
-const ColGroup = ({ widths }) => {
+const ColGroup = ({ widths, minWidths }) => {
     const resolveColWidth = (width) => {
-        if (width === 'auto')
+        if (width === undefined || width === 'auto')
             return undefined;
         if (typeof width === 'number')
             return `${width}px`;
@@ -62,7 +66,7 @@ const ColGroup = ({ widths }) => {
     };
     return (_jsx("colgroup", { children: widths.map((width, index) => (
         // biome-ignore lint/suspicious/noArrayIndexKey: colgroup columns never reorder or change
-        _jsx("col", { style: { width: resolveColWidth(width) } }, index))) }));
+        _jsx("col", { style: { width: resolveColWidth(width), minWidth: resolveColWidth(minWidths?.[index]) } }, index))) }));
 };
 ColGroup.displayName = 'Table.ColGroup';
 const Empty = ({ colSpan, children }) => (_jsx("tr", { children: _jsx("td", { colSpan: colSpan, className: "ncua-table__empty", role: "status", "aria-live": "polite", children: children || '등록된 게시물이 없습니다.' }) }));
@@ -104,7 +108,7 @@ const sortChildren = (children) => {
 // ──────────────────────────────────────────────
 // Main Table component
 // ──────────────────────────────────────────────
-const TableComponent = forwardRef(({ type = 'horizontal', fixedHeader = false, maxHeight, hoverable = true, selectable = false, children, className, ...rest }, ref) => {
+const TableComponent = forwardRef(({ type = 'horizontal', fixedHeader = false, maxHeight, hoverable = true, selectable = false, horizontalScroll = false, minWidth, children, className, ...rest }, ref) => {
     const tableClasses = classNames('ncua-table', className, {
         'ncua-table--horizontal': type === 'horizontal',
         'ncua-table--vertical': type === 'vertical',
@@ -123,64 +127,45 @@ const TableComponent = forwardRef(({ type = 'horizontal', fixedHeader = false, m
     // Custom scrollbar refs (used only in fixed-header mode)
     const scrollContainerRef = useRef(null);
     const scrollAreaRef = useRef(null);
+    const scrollbarRef = useRef(null);
     const thumbRef = useRef(null);
-    useEffect(() => {
-        if (!fixedHeader || !maxHeight)
-            return;
-        const scrollEl = scrollContainerRef.current;
-        const thumbEl = thumbRef.current;
-        if (!scrollEl || !thumbEl)
-            return;
-        const update = () => {
-            const { scrollTop, scrollHeight, clientHeight } = scrollEl;
-            if (scrollHeight <= clientHeight) {
-                thumbEl.style.height = '0';
-                return;
-            }
-            const trackHeight = (scrollAreaRef.current?.clientHeight ?? clientHeight) - TABLE_HEADER_HEIGHT - SCROLLBAR_TRACK_OFFSET;
-            const thumbHeight = Math.max(SCROLLBAR_THUMB_MIN_HEIGHT, (clientHeight / scrollHeight) * trackHeight);
-            const thumbTop = (scrollTop / (scrollHeight - clientHeight)) * (trackHeight - thumbHeight);
-            thumbEl.style.height = `${thumbHeight}px`;
-            thumbEl.style.transform = `translateY(${thumbTop}px)`;
-        };
-        scrollEl.addEventListener('scroll', update, { passive: true });
-        const observer = new ResizeObserver(update);
-        observer.observe(scrollEl);
-        update();
-        return () => {
-            scrollEl.removeEventListener('scroll', update);
-            observer.disconnect();
-        };
-    }, [fixedHeader, maxHeight]);
-    const handleThumbMouseDown = (e) => {
-        e.preventDefault();
-        const scrollEl = scrollContainerRef.current;
-        const thumbEl = thumbRef.current;
-        const areaEl = scrollAreaRef.current;
-        if (!scrollEl || !thumbEl)
-            return;
-        areaEl?.setAttribute('data-dragging', '');
-        const startY = e.clientY;
-        const startScrollTop = scrollEl.scrollTop;
-        const { scrollHeight, clientHeight } = scrollEl;
-        const thumbHeight = thumbEl.offsetHeight;
-        const scrollRatio = (scrollHeight - clientHeight) / (clientHeight - thumbHeight);
-        const onMove = (ev) => {
-            scrollEl.scrollTop = startScrollTop + (ev.clientY - startY) * scrollRatio;
-        };
-        const onUp = () => {
-            areaEl?.removeAttribute('data-dragging');
-            document.removeEventListener('mousemove', onMove);
-            document.removeEventListener('mouseup', onUp);
+    // 가로 스크롤바 refs (horizontalScroll 모드)
+    const hScrollContainerRef = useRef(null);
+    const hScrollbarRef = useRef(null);
+    const hThumbRef = useRef(null);
+    const fixedScrollEnabled = !!(fixedHeader && maxHeight);
+    const { handleThumbMouseDown } = useTableVerticalScrollbar({
+        enabled: fixedScrollEnabled,
+        scrollContainerRef,
+        scrollAreaRef,
+        thumbRef,
+    });
+    const { handleHThumbMouseDown } = useTableHorizontalScrollbar({
+        enabled: horizontalScroll,
+        hScrollContainerRef,
+        hScrollbarRef,
+        hThumbRef,
+    });
+    // <colgroup> + <thead> + <tbody> 묶음 — fixed-header 분기와 horizontalScroll 분기 모두에서 재사용
+    const renderTable = () => (_jsxs("table", { className: "ncua-table__table", role: "table", children: [colGroupContent, headerContent, tableContent] }));
+    // fixed-header 시 scroll-area + scrollbar 래핑, 아니면 <table> 그대로.
+    // withScrollbar=false 이면 scrollbar를 제외 — horizontalScroll 분기에서 scrollbar를
+    // h-scroll-container 형제 위치에 별도 렌더해 가로 스크롤 시 viewport 우측에 자연 고정.
+    const renderScrollableArea = (includeVerticalScrollbar = true) => fixedScrollEnabled ? (_jsxs("div", { ref: scrollAreaRef, className: "ncua-table__scroll-area", children: [_jsx("div", { ref: scrollContainerRef, className: "ncua-table__scroll-container", style: scrollStyle, children: renderTable() }), includeVerticalScrollbar && (_jsx("div", { ref: scrollbarRef, className: "ncua-table__scrollbar", "aria-hidden": "true", children: _jsx("div", { ref: thumbRef, className: "ncua-table__scrollbar-thumb", onMouseDown: handleThumbMouseDown }) }))] })) : (renderTable());
+    // horizontalScroll=true 시 외곽 wrapper + FloatingProvider 부착.
+    // 핵심 — __h-scroll-container 는 <table>(또는 scroll-area) 만 감싸고, footer/pagination 은
+    // 그 바깥에서 항상 고정 위치. 세로 스크롤바는 h-scroll-container 형제로 배치되어
+    // 가로 스크롤에 영향받지 않고 .ncua-table 우측에 absolute 고정된다.
+    if (horizontalScroll) {
+        const resolvedMinWidth = minWidth ?? DEFAULT_HORIZONTAL_SCROLL_MIN_WIDTH;
+        // CSS 변수로 전달 — SCSS 에서 max(100%, var(--ncua-table-min-width)) 로 부모 너비를 항상 보장한다.
+        // (inline min-width 를 직접 주면 부모보다 작은 값에서 wrapper 가 좁아져 콘텐츠가 깨짐)
+        const innerStyle = {
+            '--ncua-table-min-width': typeof resolvedMinWidth === 'number' ? `${resolvedMinWidth}px` : resolvedMinWidth,
         };
-        document.addEventListener('mousemove', onMove);
-        document.addEventListener('mouseup', onUp);
-    };
-    if (fixedHeader && maxHeight) {
-        return (_jsxs("div", { ref: ref, className: "ncua-table-wrapper", children: [_jsxs("div", { className: tableClasses, ...rest, children: [_jsxs("div", { ref: scrollAreaRef, className: "ncua-table__scroll-area", children: [_jsx("div", { ref: scrollContainerRef, className: "ncua-table__scroll-container", style: scrollStyle, children: _jsxs("table", { className: "ncua-table__table", role: "table", children: [colGroupContent, headerContent, tableContent] }) }), _jsx("div", { className: "ncua-table__scrollbar", "aria-hidden": "true", children: _jsx("div", { ref: thumbRef, className: "ncua-table__scrollbar-thumb", onMouseDown: handleThumbMouseDown }) })] }), footerContent] }), paginationContent] }));
+        return (_jsx(FloatingProvider, { value: FLOATING_PORTAL_VALUE, children: _jsxs("div", { ref: ref, className: "ncua-table-wrapper", style: WRAPPER_STYLE, children: [_jsxs("div", { className: tableClasses, ...rest, children: [_jsxs("div", { ref: hScrollContainerRef, className: "ncua-table__h-scroll-container", children: [_jsx("div", { className: "ncua-table__h-scroll-inner", style: innerStyle, children: renderScrollableArea(false) }), _jsx("div", { ref: hScrollbarRef, className: "ncua-table__h-scrollbar", "aria-hidden": "true", children: _jsx("div", { ref: hThumbRef, className: "ncua-table__h-scrollbar-thumb", onMouseDown: handleHThumbMouseDown }) })] }), fixedScrollEnabled && (_jsx("div", { ref: scrollbarRef, className: "ncua-table__scrollbar", "aria-hidden": "true", children: _jsx("div", { ref: thumbRef, className: "ncua-table__scrollbar-thumb", onMouseDown: handleThumbMouseDown }) })), footerContent] }), paginationContent] }) }));
     }
-    const tableElement = (_jsxs("table", { className: "ncua-table__table", role: "table", children: [colGroupContent, headerContent, tableContent] }));
-    return (_jsxs("div", { ref: ref, className: "ncua-table-wrapper", children: [_jsxs("div", { className: tableClasses, ...rest, children: [tableElement, footerContent] }), paginationContent] }));
+    return (_jsxs("div", { ref: ref, className: "ncua-table-wrapper", style: WRAPPER_STYLE, children: [_jsxs("div", { className: tableClasses, ...rest, children: [renderScrollableArea(), footerContent] }), paginationContent] }));
 });
 TableComponent.displayName = 'Table';
 // ──────────────────────────────────────────────