@ncds/ui-admin 1.8.4 → 1.8.6

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';
 // ──────────────────────────────────────────────

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

@@ -8,6 +8,17 @@ export type TableProps = Omit<ComponentProps<'div'>, 'ref'> & {
     maxHeight?: string | number;
     hoverable?: boolean;
     selectable?: boolean;
+    /**
+     * 가로 스크롤 활성화. 외곽에 overflow-x: auto wrapper가 추가되며,
+     * 내부의 SelectBox·Dropdown 등 floating 컴포넌트가 FloatingProvider를 통해
+     * 자동으로 React Portal 렌더로 전환된다.
+     */
+    horizontalScroll?: boolean;
+    /**
+     * 가로 스크롤 트리거 임계 너비. horizontalScroll=true 일 때만 의미가 있으며,
+     * 기본값은 1140 (14인치 모니터 + LNB 기준 디자인 권장 너비).
+     */
+    minWidth?: string | number;
     children: ReactNode;
 };
 export type TableHeaderProps = {
@@ -26,6 +37,11 @@ export type TableHeaderCellProps = Omit<ComponentProps<'th'>, 'ref'> & {
     sortDirection?: SortDirection;
     onSort?: () => void;
     width?: string | number;
+    /**
+     * 셀 최소 너비. 가로 스크롤 정책에 따라 글자수 기준으로 설정한다.
+     * 예: 제목·메인 10자 ≈ 160px, 이름·일자 5자 ≈ 80px, 버튼 xxs ≈ 40~60px, 기타 2자 ≈ 32px.
+     */
+    minWidth?: string | number;
 };
 export type TableCellProps = Omit<ComponentProps<'td'>, 'ref'> & {
     isHeader?: boolean;
@@ -40,6 +56,8 @@ export type TablePaginationProps = {
 };
 export type TableColGroupProps = {
     widths: (string | number)[];
+    /** 컬럼별 최소 너비. 가로 스크롤 시 셀이 더 좁아지지 않도록 강제한다. */
+    minWidths?: (string | number)[];
 };
 export type TableEmptyProps = {
     colSpan: number;

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

@@ -0,0 +1,25 @@
+import { type MouseEvent, type RefObject } from 'react';
+export declare const TABLE_HEADER_HEIGHT = 40;
+export declare const SCROLLBAR_THUMB_MIN_HEIGHT = 40;
+export declare const H_SCROLLBAR_THUMB_MIN_WIDTH = 40;
+export declare const H_SCROLLBAR_SIDE_GAP = 8;
+export declare const SCROLLBAR_TRACK_OFFSET = 16;
+type VerticalScrollbarOptions = {
+    enabled: boolean;
+    scrollContainerRef: RefObject<HTMLDivElement | null>;
+    scrollAreaRef: RefObject<HTMLDivElement | null>;
+    thumbRef: RefObject<HTMLDivElement | null>;
+};
+export declare const useTableVerticalScrollbar: ({ enabled, scrollContainerRef, scrollAreaRef, thumbRef, }: VerticalScrollbarOptions) => {
+    handleThumbMouseDown: (e: MouseEvent<HTMLDivElement>) => void;
+};
+type HorizontalScrollbarOptions = {
+    enabled: boolean;
+    hScrollContainerRef: RefObject<HTMLDivElement | null>;
+    hScrollbarRef: RefObject<HTMLDivElement | null>;
+    hThumbRef: RefObject<HTMLDivElement | null>;
+};
+export declare const useTableHorizontalScrollbar: ({ enabled, hScrollContainerRef, hScrollbarRef, hThumbRef, }: HorizontalScrollbarOptions) => {
+    handleHThumbMouseDown: (e: MouseEvent<HTMLDivElement>) => void;
+};
+export {};

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

@@ -0,0 +1,136 @@
+import { useEffect } from 'react';
+// ──────────────────────────────────────────────
+// 상수 — Table.tsx 와 _table.scss 양쪽에서 동기화 필요
+// ──────────────────────────────────────────────
+// $table-header-height
+export const TABLE_HEADER_HEIGHT = 40;
+// 세로/가로 thumb 최소 크기
+export const SCROLLBAR_THUMB_MIN_HEIGHT = 40;
+export const H_SCROLLBAR_THUMB_MIN_WIDTH = 40;
+// SCSS .ncua-table__h-scrollbar { left/right: var(--spacing-s) = 8px } 와 동기화
+export const H_SCROLLBAR_SIDE_GAP = 8;
+// 세로 트랙 상하 여백 합계 — top 8 + bottom 8 = 16 (header 회피분 40 은 별도 처리)
+// biome-ignore lint/style/useExportsLast: 상수는 문서 주석과 함께 상단에 정의
+export const SCROLLBAR_TRACK_OFFSET = 16;
+const startDrag = (e, options) => {
+    e.preventDefault();
+    const { axis, scrollEl, thumbEl, draggingTarget = scrollEl, sideGap = 0 } = options;
+    draggingTarget.setAttribute('data-dragging', '');
+    if (axis === 'y') {
+        const startY = e.clientY;
+        const startScrollTop = scrollEl.scrollTop;
+        const { scrollHeight, clientHeight } = scrollEl;
+        const thumbHeight = thumbEl.offsetHeight;
+        const ratio = (scrollHeight - clientHeight) / (clientHeight - thumbHeight);
+        const onMove = (ev) => {
+            scrollEl.scrollTop = startScrollTop + (ev.clientY - startY) * ratio;
+        };
+        const onUp = () => {
+            draggingTarget.removeAttribute('data-dragging');
+            document.removeEventListener('mousemove', onMove);
+            document.removeEventListener('mouseup', onUp);
+        };
+        document.addEventListener('mousemove', onMove);
+        document.addEventListener('mouseup', onUp);
+        return;
+    }
+    const startX = e.clientX;
+    const startScrollLeft = scrollEl.scrollLeft;
+    const { scrollWidth, clientWidth } = scrollEl;
+    const thumbWidth = thumbEl.offsetWidth;
+    const trackWidth = clientWidth - sideGap * 2;
+    const ratio = (scrollWidth - clientWidth) / (trackWidth - thumbWidth);
+    const onMove = (ev) => {
+        scrollEl.scrollLeft = startScrollLeft + (ev.clientX - startX) * ratio;
+    };
+    const onUp = () => {
+        draggingTarget.removeAttribute('data-dragging');
+        document.removeEventListener('mousemove', onMove);
+        document.removeEventListener('mouseup', onUp);
+    };
+    document.addEventListener('mousemove', onMove);
+    document.addEventListener('mouseup', onUp);
+};
+export const useTableVerticalScrollbar = ({ enabled, scrollContainerRef, scrollAreaRef, thumbRef, }) => {
+    useEffect(() => {
+        if (!enabled)
+            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);
+        if (scrollAreaRef.current)
+            observer.observe(scrollAreaRef.current);
+        update();
+        return () => {
+            scrollEl.removeEventListener('scroll', update);
+            observer.disconnect();
+        };
+    }, [enabled, scrollContainerRef, scrollAreaRef, thumbRef]);
+    const handleThumbMouseDown = (e) => {
+        const scrollEl = scrollContainerRef.current;
+        const thumbEl = thumbRef.current;
+        const areaEl = scrollAreaRef.current;
+        if (!scrollEl || !thumbEl)
+            return;
+        startDrag(e, { axis: 'y', scrollEl, thumbEl, draggingTarget: areaEl ?? scrollEl });
+    };
+    return { handleThumbMouseDown };
+};
+export const useTableHorizontalScrollbar = ({ enabled, hScrollContainerRef, hScrollbarRef, hThumbRef, }) => {
+    useEffect(() => {
+        if (!enabled)
+            return;
+        const hScrollEl = hScrollContainerRef.current;
+        const hScrollbarEl = hScrollbarRef.current;
+        const hThumbEl = hThumbRef.current;
+        if (!hScrollEl || !hScrollbarEl || !hThumbEl)
+            return;
+        const update = () => {
+            const { scrollLeft, scrollWidth, clientWidth } = hScrollEl;
+            if (scrollWidth <= clientWidth) {
+                hThumbEl.style.width = '0';
+                return;
+            }
+            // transform으로 스크롤 오프셋 보정 — reflow 없이 compositor-only 이동
+            hScrollbarEl.style.transform = `translateX(${scrollLeft}px)`;
+            hScrollbarEl.style.width = `${clientWidth - H_SCROLLBAR_SIDE_GAP * 2}px`;
+            const trackWidth = clientWidth - H_SCROLLBAR_SIDE_GAP * 2;
+            const thumbWidth = Math.max(H_SCROLLBAR_THUMB_MIN_WIDTH, (clientWidth / scrollWidth) * trackWidth);
+            const thumbLeft = (scrollLeft / (scrollWidth - clientWidth)) * (trackWidth - thumbWidth);
+            hThumbEl.style.width = `${thumbWidth}px`;
+            hThumbEl.style.transform = `translateX(${thumbLeft}px)`;
+        };
+        hScrollEl.addEventListener('scroll', update, { passive: true });
+        const ro = new ResizeObserver(update);
+        ro.observe(hScrollEl);
+        update();
+        return () => {
+            hScrollEl.removeEventListener('scroll', update);
+            ro.disconnect();
+        };
+    }, [enabled, hScrollContainerRef, hScrollbarRef, hThumbRef]);
+    const handleHThumbMouseDown = (e) => {
+        const hScrollEl = hScrollContainerRef.current;
+        const hThumbEl = hThumbRef.current;
+        if (!hScrollEl || !hThumbEl)
+            return;
+        startDrag(e, { axis: 'x', scrollEl: hScrollEl, thumbEl: hThumbEl, sideGap: H_SCROLLBAR_SIDE_GAP });
+    };
+    return { handleHThumbMouseDown };
+};

package/dist/temp/src/components/forms-and-input/combo-box/ComboBox.d.ts

@@ -21,6 +21,14 @@ interface ComboBoxProps extends Omit<ComponentPropsWithRef<'div'>, 'size' | 'onC
     required?: boolean;
     multiple?: boolean;
     showFooterButtons?: boolean;
+    /**
+     * 최대 선택 가능 개수 (multiple=true에서만 유효).
+     *  - `0` 이상의 정수: 제한 활성 → footer의 "전체선택" Link 미노출 (DES-SPEC-009 §3.10.1).
+     *    - `0`은 모든 새 선택을 차단한다.
+     *    - 양수는 도달 후 추가 선택을 무시한다 (이미 선택된 항목 해제는 정상).
+     *  - 음수 / 비정수 / `null` / `undefined`: 제한 없음.
+     */
+    maxSelection?: number | null;
     onEdit?: () => void;
 }
 declare const ComboBox: import("react").ForwardRefExoticComponent<Omit<ComboBoxProps, "ref"> & import("react").RefAttributes<HTMLDivElement>>;

package/dist/temp/src/components/forms-and-input/combo-box/ComboBox.js

@@ -10,13 +10,6 @@ import { SelectDropdown } from '../../select-dropdown';
 import { HintText } from '../../shared/hintText/HintText';
 import { InputBase } from '../input-base/InputBase';
 const defaultMaxHeight = 275;
-const toggleMultiSelectValue = (currentValue, optionId) => {
-    const currentValues = Array.isArray(currentValue) ? currentValue : [];
-    if (currentValues.includes(optionId)) {
-        return currentValues.filter((v) => v !== optionId);
-    }
-    return [...currentValues, optionId];
-};
 const notifyFormChange = (register, multiple, newValue) => {
     if (register?.onChange) {
         register.onChange({
@@ -27,7 +20,7 @@ const notifyFormChange = (register, multiple, newValue) => {
         });
     }
 };
-const ComboBox = forwardRef(({ placeholder = '검색하세요', id, className, hintText, children, size = 'xs', destructive = false, value, optionItems = [], onChange, onSearch, disabled = false, register, maxHeight = defaultMaxHeight, searchValue = '', label, required = false, multiple = false, showFooterButtons = false, onEdit, ...props }, ref) => {
+const ComboBox = forwardRef(({ placeholder = '검색하세요', id, className, hintText, children, size = 'xs', destructive = false, value, optionItems = [], onChange, onSearch, disabled = false, register, maxHeight = defaultMaxHeight, searchValue = '', label, required = false, multiple = false, showFooterButtons = false, maxSelection, onEdit, ...props }, ref) => {
     const internalRef = useRef(null);
     const dropdownRef = useRef(null);
     const inputRef = useRef(null);
@@ -38,7 +31,9 @@ const ComboBox = forwardRef(({ placeholder = '검색하세요', id, className, h
         if (disabled)
             return;
         if (multiple) {
-            const newValue = toggleMultiSelectValue(value ?? [], option.id);
+            const newValue = tryToggle(option.id, Array.isArray(value) ? value : []);
+            if (newValue === null)
+                return;
             onChange?.(newValue);
             notifyFormChange(register, multiple, newValue);
             return;
@@ -103,6 +98,7 @@ const ComboBox = forwardRef(({ placeholder = '검색하세요', id, className, h
         // 나머지는 useDropdown 훅에서 처리
         dropdownHandleKeyDown(e);
     };
+    // biome-ignore lint/style/noNonNullAssertion: forwardRef 패턴에서 internalRef는 첫 렌더 후 항상 존재
     useImperativeHandle(ref, () => internalRef.current, []);
     const trailingElement = {
         type: 'custom',
@@ -116,7 +112,7 @@ const ComboBox = forwardRef(({ placeholder = '검색하세요', id, className, h
         color: 'gray300',
     };
     const currentSelectedValues = multiple && Array.isArray(value) ? value : [];
-    const { buttonText: selectAllButtonText, toggleSelectAll, getSelectedTagsData, removeTag, } = useMultiSelect(currentSelectedValues, optionItems);
+    const { buttonText: selectAllButtonText, toggleSelectAll, getSelectedTagsData, removeTag, isMaxSelectionActive, tryToggle, } = useMultiSelect(currentSelectedValues, optionItems, { maxSelection });
     const handleSelectAll = () => {
         if (!multiple || !onChange)
             return;
@@ -160,7 +156,7 @@ const ComboBox = forwardRef(({ placeholder = '검색하세요', id, className, h
                 }, className), ...props, children: [_jsxs("div", { className: "ncua-combobox__content", children: [_jsx(InputBase, { ref: inputRef, size: size, label: label, required: required, placeholder: placeholder, value: inputValue, onChange: handleInputChange, onKeyDown: handleKeyDown, onClick: handleInputClick, disabled: disabled, destructive: destructive, leadingElement: leadingElement, trailingElement: trailingElement, role: "combobox", "aria-expanded": isOpen, "aria-haspopup": "listbox", "aria-controls": comboboxId, "aria-disabled": disabled, autoComplete: "off", clearText: !!inputValue, onClearText: () => {
                                     setInputValue('');
                                     onSearch?.('');
-                                } }), _jsxs(SelectDropdown, { ref: dropdownRef, isOpen: isOpen, direction: dropdownDirection, size: size, options: displayedOptions, value: value, focusedIndex: focusedIndex, maxHeight: maxHeight, listboxId: comboboxId, onOptionSelect: handleDropdownSelect, onMouseMove: handleMouseMove, isKeyboardNavigation: isKeyboardNavigation, multiple: multiple, showFooterButtons: showFooter, selectAllButtonText: selectAllButtonText, onSelectAll: handleSelectAll, onEdit: handleEdit, onComplete: handleComplete, componentType: "combobox", children: [showNoResults ? _jsx("li", { className: "ncua-select-dropdown__no-results", children: "\uC77C\uCE58\uD558\uB294 \uACB0\uACFC\uAC00 \uC5C6\uC2B5\uB2C8\uB2E4." }) : null, children] })] }), register && _jsx("input", { type: "hidden", ...register, value: hiddenInputValue }), hintText && _jsx(HintText, { destructive: destructive, children: hintText })] }), hasTags && (_jsx("div", { className: "ncua-combobox__tags", children: selectedTags.map((tag) => (_jsx(Tag, { text: tag.label, size: "sm", close: true, onButtonClick: () => handleRemoveTag(tag.id) }, tag.id))) }))] }));
+                                } }), _jsxs(SelectDropdown, { ref: dropdownRef, isOpen: isOpen, direction: dropdownDirection, size: size, options: displayedOptions, value: value, focusedIndex: focusedIndex, maxHeight: maxHeight, listboxId: comboboxId, onOptionSelect: handleDropdownSelect, onMouseMove: handleMouseMove, isKeyboardNavigation: isKeyboardNavigation, multiple: multiple, showFooterButtons: showFooter, selectAllButtonText: selectAllButtonText, showSelectAllAction: !isMaxSelectionActive, onSelectAll: handleSelectAll, onEdit: handleEdit, onComplete: handleComplete, componentType: "combobox", children: [showNoResults ? _jsx("li", { className: "ncua-select-dropdown__no-results", children: "\uC77C\uCE58\uD558\uB294 \uACB0\uACFC\uAC00 \uC5C6\uC2B5\uB2C8\uB2E4." }) : null, children] })] }), register && _jsx("input", { type: "hidden", ...register, value: hiddenInputValue }), hintText && _jsx(HintText, { destructive: destructive, children: hintText })] }), hasTags && (_jsx("div", { className: "ncua-combobox__tags", children: selectedTags.map((tag) => (_jsx(Tag, { text: tag.label, size: "sm", close: true, onButtonClick: () => handleRemoveTag(tag.id) }, tag.id))) }))] }));
 });
 ComboBox.displayName = 'ComboBox';
 export { defaultMaxHeight, ComboBox };

package/dist/temp/src/components/forms-and-input/image-file-input/ImageFileInput.js

@@ -85,7 +85,7 @@ export const ImageFileInput = forwardRef(({ size = 'sm', accept, multiple = fals
     };
     const renderImagePreview = (files = []) => {
         const showEmptySlot = maxFileCount ? files.length < maxFileCount : files.length === 0;
-        return (_jsxs("div", { className: "ncua-image-file-input__previews", children: [files.map((file, index) => (_jsx(ImagePreview, { file: file, onRemove: () => handleRemoveFile(index) }, `${file.name}-${index}`))), showEmptySlot && (_jsxs("div", { className: "ncua-image-file-input__empty-slot-wrapper", onMouseEnter: () => !disabled && setIsButtonHovered(true), onMouseLeave: () => setIsButtonHovered(false), onClick: handleBrowseClick, children: [_jsx(Button, { onlyIcon: true, size: size, className: classNames('ncua-image-file-input__preview-container'), onClick: handleBrowseClick, disabled: disabled, label: imagePreviewTooltipLabel }), isButtonHovered && !disabled && _jsx(Tooltip, { content: imagePreviewTooltipLabel, position: "bottom" })] }))] }));
+        return (_jsxs("div", { className: "ncua-image-file-input__previews", children: [files.map((file, index) => (_jsx(ImagePreview, { file: file, onRemove: () => handleRemoveFile(index) }, `${file.name}-${index}`))), showEmptySlot && (_jsxs("div", { className: "ncua-image-file-input__empty-slot-wrapper", onMouseEnter: () => !disabled && setIsButtonHovered(true), onMouseLeave: () => setIsButtonHovered(false), onClick: handleBrowseClick, children: [_jsx(Button, { onlyIcon: true, size: size, className: classNames('ncua-image-file-input__preview-container'), onClick: handleBrowseClick, disabled: disabled, label: imagePreviewTooltipLabel }), _jsx(Tooltip, { content: imagePreviewTooltipLabel, position: "bottom", tooltipType: "black", forceVisible: isButtonHovered && !disabled, disablePortal: true })] }))] }));
     };
     const renderHintList = () => {
         if (!hintItems || hintItems.length === 0)

package/dist/temp/src/components/forms-and-input/select-box/SelectBox.d.ts

@@ -19,8 +19,21 @@ type SelectBoxProps = Omit<ComponentPropsWithRef<'div'>, 'size' | 'onChange'> &
     register?: UseFormRegisterReturn;
     maxHeight?: number;
     multiple?: boolean;
+    /**
+     * 최대 선택 가능 개수 (multiple=true에서만 유효).
+     *  - `0` 이상의 정수: 제한 활성 → footer "전체선택" Link 미노출.
+     *    - `0`은 모든 새 선택을 차단한다.
+     *    - 양수는 도달 후 추가 선택을 무시한다 (이미 선택된 항목 해제는 정상).
+     *  - 음수 / 비정수 / `null` / `undefined`: 제한 없음.
+     */
+    maxSelection?: number | null;
     onEdit?: () => void;
     align?: 'left' | 'right';
+    /**
+     * 옵션 패널을 React Portal로 body에 렌더한다.
+     * 미지정 시 FloatingContext.preferPortal 값을 따른다 (DataGrid.Table horizontalScroll 내부에서는 자동 true).
+     */
+    usePortal?: boolean;
 };
 declare const SelectBox: import("react").ForwardRefExoticComponent<Omit<SelectBoxProps, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
 export type { SelectBoxProps };

package/dist/temp/src/components/forms-and-input/select-box/SelectBox.js

@@ -2,8 +2,11 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 import { ChevronDown } from '@ncds/ui-admin-icon';
 import classNames from 'classnames';
 import { forwardRef, useCallback, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState, } from 'react';
+import { createPortal } from 'react-dom';
 import { COLOR } from '../../../../constant/color';
 import { useDropdown, useScrollLock } from '../../../hooks/dropdown';
+import { useFloatingPosition } from '../../../hooks/useFloatingPosition';
+import { usePortalState } from '../../../hooks/usePortalState';
 import { useMultiSelect } from '../../../utils/dropdown/multiSelect';
 import { Tag } from '../../feedback-and-status/tag';
 import { SelectDropdown } from '../../select-dropdown';
@@ -37,9 +40,12 @@ function DisplayValue({ displayValue }) {
     }
     return (_jsxs("div", { className: "ncua-selectbox__value-container", children: [displayValue.icon && (_jsx("span", { className: "ncua-selectbox__value-icon", children: _jsx(displayValue.icon, { width: 16, height: 16 }) })), _jsx("span", { className: "ncua-selectbox__value-text", children: displayValue.label })] }));
 }
-const SelectBox = forwardRef(({ placeholder = '선택하세요', disabledPlaceholder = false, hintText, size = 'xs', type = 'default', autoWidth = true, destructive = false, value, optionItems = [], disabled = false, maxHeight = DEFAULT_MAX_HEIGHT, multiple = false, align = 'left', id, className, children, register, onChange, onEdit, ...props }, ref) => {
+const SelectBox = forwardRef(({ placeholder = '선택하세요', disabledPlaceholder = false, hintText, size = 'xs', type = 'default', autoWidth = true, destructive = false, value, optionItems = [], disabled = false, maxHeight = DEFAULT_MAX_HEIGHT, multiple = false, maxSelection, align = 'left', usePortal, id, className, children, register, onChange, onEdit, ...props }, ref
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: 옵션/멀티/태그/포탈 등 필수 분기 통합
+) => {
     const internalRef = useRef(null);
     const dropdownRef = useRef(null);
+    const { shouldPortal, portalContainer } = usePortalState(usePortal);
     const [selectedTags, setSelectedTags] = useState([]);
     const selectedOption = useMemo(() => {
         if (multiple)
@@ -55,6 +61,14 @@ const SelectBox = forwardRef(({ placeholder = '선택하세요', disabledPlaceho
     const handleOptionSelect = (option) => {
         if (disabled)
             return;
+        if (multiple) {
+            const newValue = tryToggle(option.id, Array.isArray(value) ? value : []);
+            if (newValue === null)
+                return;
+            onChange?.(newValue);
+            notifyRegister(register, newValue, multiple);
+            return;
+        }
         const newValue = computeNewValue(option, value, multiple);
         onChange?.(newValue);
         notifyRegister(register, newValue, multiple);
@@ -82,7 +96,7 @@ const SelectBox = forwardRef(({ placeholder = '선택하세요', disabledPlaceho
     }, [handleMouseMove, setFocusedIndex]);
     // Multiple select 관련 로직
     const currentSelectedValues = multiple && Array.isArray(value) ? value : [];
-    const { buttonText: selectAllButtonText, toggleSelectAll, getSelectedTagsData, removeTag, } = useMultiSelect(currentSelectedValues, optionItems);
+    const { buttonText: selectAllButtonText, toggleSelectAll, getSelectedTagsData, removeTag, isMaxSelectionActive, tryToggle, } = useMultiSelect(currentSelectedValues, optionItems, { maxSelection });
     const handleSelectAll = () => {
         if (!multiple || !onChange)
             return;
@@ -109,13 +123,26 @@ const SelectBox = forwardRef(({ placeholder = '선택하세요', disabledPlaceho
         }
     };
     useScrollLock(isOpen, dropdownRef);
+    // biome-ignore lint/correctness/useExhaustiveDependencies: optionItems 변경 시 너비 재계산 필요
     useLayoutEffect(() => {
         if (autoWidth && isOpen && dropdownRef.current && internalRef.current) {
             const dropdownWidth = dropdownRef.current.offsetWidth;
             internalRef.current.style.width = `${dropdownWidth}px`;
         }
     }, [autoWidth, isOpen, optionItems]);
+    const floatingStyle = useFloatingPosition({
+        enabled: shouldPortal,
+        isOpen,
+        triggerRef: internalRef,
+        floatingRef: dropdownRef,
+        direction: dropdownDirection,
+        align,
+        matchTriggerWidth: true,
+    });
+    // biome-ignore lint/style/noNonNullAssertion: forwardRef 패턴에서 internalRef는 항상 존재
     useImperativeHandle(ref, () => internalRef.current, []);
+    const selectDropdownNode = (_jsx(SelectDropdown, { ref: dropdownRef, isOpen: isOpen, direction: dropdownDirection, size: size, options: optionItems, value: value, focusedIndex: focusedIndex, maxHeight: maxHeight, listboxId: `selectbox-options-${id || 'default'}`, multiple: multiple, showFooterButtons: multiple, selectAllButtonText: selectAllButtonText, showSelectAllAction: !isMaxSelectionActive, componentType: "selectbox", isKeyboardNavigation: isKeyboardNavigation, activeDescendantId: activeDescendantId, align: align, className: shouldPortal ? 'ncua-select-dropdown--portal' : undefined, style: shouldPortal && floatingStyle ? floatingStyle : undefined, onOptionSelect: handleDropdownSelect, onMouseMove: handleMouseMove, onOptionHover: handleOptionHover, onSelectAll: handleSelectAll, onEdit: handleEdit, onComplete: handleComplete, children: children }));
+    const portaledDropdown = shouldPortal && portalContainer && isOpen ? createPortal(selectDropdownNode, portalContainer) : null;
     return (_jsxs(_Fragment, { children: [_jsxs("div", { ref: internalRef, className: classNames('ncua-selectbox', `ncua-selectbox--${size}`, {
                     'ncua-selectbox--open': isOpen,
                     'ncua-selectbox--disabled': disabled,
@@ -124,7 +151,7 @@ const SelectBox = forwardRef(({ placeholder = '선택하세요', disabledPlaceho
                     destructive: destructive,
                 }, className), ...props, children: [_jsxs("div", { className: classNames('ncua-selectbox__content'), onClick: toggleDropdown, onKeyDown: handleKeyDown, tabIndex: disabled ? -1 : 0, role: "combobox", "aria-expanded": isOpen, "aria-haspopup": "listbox", "aria-controls": `selectbox-options-${id || 'default'}`, "aria-disabled": disabled, "aria-label": selectedOption ? selectedOption.label : placeholder, "aria-activedescendant": activeDescendantId, children: [_jsxs("div", { className: "ncua-selectbox__content-inner", children: [_jsx("div", { className: "ncua-selectbox__value", children: _jsx(DisplayValue, { displayValue: displayValue }) }), _jsx(ChevronDown, { width: size === 'xs' ? ICON_SIZE_XS : ICON_SIZE_SM, height: size === 'xs' ? ICON_SIZE_XS : ICON_SIZE_SM, color: disabled ? COLOR.gray300 : COLOR.gray500, className: classNames('ncua-selectbox__arrow', {
                                             'ncua-selectbox__arrow--up': isOpen,
-                                        }) })] }), _jsx(SelectDropdown, { ref: dropdownRef, isOpen: isOpen, direction: dropdownDirection, size: size, options: optionItems, value: value, focusedIndex: focusedIndex, maxHeight: maxHeight, listboxId: `selectbox-options-${id || 'default'}`, multiple: multiple, showFooterButtons: multiple, selectAllButtonText: selectAllButtonText, componentType: "selectbox", isKeyboardNavigation: isKeyboardNavigation, activeDescendantId: activeDescendantId, align: align, onOptionSelect: handleDropdownSelect, onMouseMove: handleMouseMove, onOptionHover: handleOptionHover, onSelectAll: handleSelectAll, onEdit: handleEdit, onComplete: handleComplete, children: children })] }), hintText && (_jsx(HintText, { destructive: destructive, className: "ncua-hint-text", children: hintText })), register && (_jsx("input", { type: "hidden", ...register, value: multiple ? JSON.stringify(value || []) : String(value || '') }))] }), selectedTags.length > 0 && (_jsx("div", { className: "ncua-selectbox__tags", children: selectedTags.map((tag) => (_jsx(Tag, { text: tag.label, size: "sm", close: true, onButtonClick: () => handleRemoveTag(tag.id) }, tag.id))) }))] }));
+                                        }) })] }), !shouldPortal && selectDropdownNode] }), hintText && (_jsx(HintText, { destructive: destructive, className: "ncua-hint-text", children: hintText })), register && (_jsx("input", { type: "hidden", ...register, value: multiple ? JSON.stringify(value || []) : String(value || '') }))] }), selectedTags.length > 0 && (_jsx("div", { className: "ncua-selectbox__tags", children: selectedTags.map((tag) => (_jsx(Tag, { text: tag.label, size: "sm", close: true, onButtonClick: () => handleRemoveTag(tag.id) }, tag.id))) })), portaledDropdown] }));
 });
 SelectBox.displayName = 'SelectBox';
 export { DEFAULT_MAX_HEIGHT, SelectBox };

package/dist/temp/src/components/forms-and-input/slider/Slider.d.ts

@@ -11,4 +11,3 @@ export interface SliderProps {
     className?: string;
 }
 export declare const Slider: ({ min, max, step, value, onChange, labelPosition, disabled, className, }: SliderProps) => import("react/jsx-runtime").JSX.Element;
-export default Slider;