@uniai-fe/uds-primitives 0.3.47 → 0.3.49

package/src/components/select/markup/multiple/Multiple.tsx

@@ -11,10 +11,11 @@ import type { SelectDropdownOption } from "../../types/option";
 import { SelectMultipleSelectedChip } from "./SelectedChip";
 import { SelectTriggerBase, SelectTriggerSelected } from "../foundation";
 import { useSelectDropdownOpenState } from "../../hooks";
-
-const isSameIdList = (previousIds: string[], nextIds: string[]) =>
-  previousIds.length === nextIds.length &&
-  previousIds.every((selectedId, index) => selectedId === nextIds[index]);
+import {
+  isSameSelectedValue,
+  isSameSelectedValueList,
+  toSelectedValueKey,
+} from "../../../../utils/selected-values";
 // 변경: synthetic "전체" 옵션 id의 기본 키다. 실제 items id와 충돌하면 suffix를 붙여 회피한다.
 const SELECT_MULTIPLE_ALL_OPTION_BASE_ID = "__select_multiple_all__";
 
@@ -31,7 +32,7 @@ const SELECT_MULTIPLE_ALL_OPTION_BASE_ID = "__select_multiple_all__";
  * @param {React.ReactNode} [props.placeholder] placeholder 텍스트
  * @param {"primary" | "secondary" | "table"} [props.priority="primary"] priority scale
  * @param {"xsmall" | "small" | "medium" | "large"} [props.size="medium"] size scale
- * @param {"default" | "focused" | "disabled"} [props.state="default"] 시각 상태
+ * @param {"default" | "focused" | "error" | "disabled"} [props.state="default"] 시각 상태
  * @param {boolean} [props.block] block 여부
  * @param {FormFieldWidth} [props.width] container width preset
  * @param {boolean} [props.disabled] disabled 여부
@@ -79,28 +80,35 @@ export function SelectMultipleTrigger<OptionData = unknown>({
     priority !== "primary" && size === "xsmall" ? "small" : size;
 
   /**
-   * 3) option 조회 최적화 맵 생성
-   * - selected id -> option 조회를 반복하므로 id 기반 맵을 생성한다.
+   * 3) option 조회/선택 계산 맵 생성
+   * - value 기반 선택 비교를 위해 value key -> option 맵을 생성한다.
    * - label 계산, tag 파생, payload selectedOptions 계산에 공통 사용한다.
    */
   const optionMap = useMemo(
-    () => new Map(items.map(option => [option.id, option])),
+    () =>
+      new Map(items.map(option => [toSelectedValueKey(option.value), option])),
     [items],
   );
+  /**
+   * value 배열을 value key 배열로 변환한다.
+   */
+  const toValueKeys = (values: Array<string | number>): string[] =>
+    values.map(value => toSelectedValueKey(value));
   // 변경: 전체 선택 대상은 disabled option을 제외한 "선택 가능 옵션"으로 한정한다.
   const selectableOptions = useMemo(
     () => items.filter(option => !option.disabled),
     [items],
   );
-  // 변경: 전체 선택 토글 계산을 위해 선택 가능 옵션 id 배열을 별도로 보관한다.
-  const selectableOptionIds = useMemo(
-    () => selectableOptions.map(option => option.id),
+  // 변경: 전체 선택 토글 계산을 위해 선택 가능 옵션 value 배열을 별도로 보관한다.
+  const selectableOptionValues = useMemo(
+    () => selectableOptions.map(option => option.value),
     [selectableOptions],
   );
-  // 변경: 전체 해제 시 빠른 membership 체크를 위해 Set 형태도 함께 보관한다.
-  const selectableOptionIdSet = useMemo(
-    () => new Set(selectableOptionIds),
-    [selectableOptionIds],
+  // 변경: 전체 해제 시 빠른 membership 체크를 위해 value key Set을 함께 보관한다.
+  const selectableOptionValueKeySet = useMemo(
+    () =>
+      new Set(selectableOptionValues.map(value => toSelectedValueKey(value))),
+    [selectableOptionValues],
   );
   const allOptionId = useMemo(() => {
     // 현재 전달된 옵션 id 집합을 먼저 만든다.
@@ -125,8 +133,8 @@ export function SelectMultipleTrigger<OptionData = unknown>({
    * 4) uncontrolled 초기 선택값 계산
    * - items[].selected를 다중 선택 초기값으로 그대로 반영한다.
    */
-  const selectedIdsFromOptions = useMemo(
-    () => items.filter(option => option.selected).map(option => option.id),
+  const selectedValuesFromOptions = useMemo(
+    () => items.filter(option => option.selected).map(option => option.value),
     [items],
   );
 
@@ -135,55 +143,51 @@ export function SelectMultipleTrigger<OptionData = unknown>({
    * - controlled 모드에서는 source로 사용되지 않는다.
    * - uncontrolled 모드에서는 최종 선택 배열을 내부 state가 소유한다.
    */
-  const [uncontrolledSelectedOptionIds, setUncontrolledSelectedOptionIds] =
-    useState<string[]>(() => selectedIdsFromOptions);
+  const [uncontrolledSelectedValues, setUncontrolledSelectedValues] = useState<
+    Array<string | number>
+  >(() => selectedValuesFromOptions);
 
   /**
    * 6) items 변경 시 내부 state 정합성 보정
-   * - 기존 선택 id 중 현재 items에 남아있는 id만 유지한다.
-   * - 남은 id가 없으면 selectedIdsFromOptions(초기 선택 규칙)로 재동기화한다.
+   * - source of truth를 items[].selected(value)로 고정해 외부 선택 상태를 즉시 반영한다.
    */
   useEffect(() => {
-    setUncontrolledSelectedOptionIds(previousSelectedIds => {
-      const optionIdSet = new Set(items.map(option => option.id));
-      const filteredIds = previousSelectedIds.filter(selectedId =>
-        optionIdSet.has(selectedId),
-      );
-      const nextSelectedIds =
-        filteredIds.length > 0 ? filteredIds : selectedIdsFromOptions;
+    setUncontrolledSelectedValues(previousSelectedValues => {
+      const nextSelectedValues = selectedValuesFromOptions;
 
       // 동일한 선택 결과면 기존 배열 참조를 유지해 재렌더 루프를 방지한다.
-      if (isSameIdList(previousSelectedIds, nextSelectedIds)) {
-        return previousSelectedIds;
+      if (isSameSelectedValueList(previousSelectedValues, nextSelectedValues)) {
+        return previousSelectedValues;
       }
 
-      return nextSelectedIds;
+      return nextSelectedValues;
     });
-  }, [items, selectedIdsFromOptions]);
+  }, [selectedValuesFromOptions]);
 
   /**
-   * 7) 최종 선택 id 계산
+   * 7) 최종 선택 value 계산
    * - 내부 state 사용
    */
-  const resolvedSelectedIds = useMemo(() => {
-    // 변경: 실제 option id만 유지해 내부 synthetic all-option id가 상태에 저장되지 않도록 차단한다.
-    // 이 필터 덕분에 최종 선택 상태는 "실 데이터 옵션"만 source of truth로 유지된다.
-    return uncontrolledSelectedOptionIds.filter(selectedId =>
-      optionMap.has(selectedId),
-    );
-  }, [optionMap, uncontrolledSelectedOptionIds]);
-  const selectedIdSet = useMemo(
-    () => new Set(resolvedSelectedIds),
-    [resolvedSelectedIds],
+  const resolvedSelectedValues = useMemo(
+    () =>
+      uncontrolledSelectedValues.filter(selectedValue =>
+        optionMap.has(toSelectedValueKey(selectedValue)),
+      ),
+    [optionMap, uncontrolledSelectedValues],
+  );
+  const selectedValueKeySet = useMemo(
+    () =>
+      new Set(resolvedSelectedValues.map(value => toSelectedValueKey(value))),
+    [resolvedSelectedValues],
   );
   const isAllSelectableOptionsSelected = useMemo(
-    // 선택 가능 옵션이 1개 이상이고, 그 id가 전부 selectedIdSet에 포함될 때만 true다.
+    // 선택 가능 옵션이 1개 이상이고, 그 value key가 전부 선택되었을 때만 true다.
     () =>
-      selectableOptionIds.length > 0 &&
-      selectableOptionIds.every(selectableId =>
-        selectedIdSet.has(selectableId),
+      selectableOptionValues.length > 0 &&
+      selectableOptionValues.every(selectableValue =>
+        selectedValueKeySet.has(toSelectedValueKey(selectableValue)),
       ),
-    [selectableOptionIds, selectedIdSet],
+    [selectableOptionValues, selectedValueKeySet],
   );
   const selectAllOption = useMemo<SelectDropdownOption<OptionData>>(
     // 변경: "전체" 옵션은 렌더링을 위한 synthetic option 객체다.
@@ -194,9 +198,9 @@ export function SelectMultipleTrigger<OptionData = unknown>({
       label: selectAllLabel,
       multiple: true,
       // 선택 가능한 옵션이 하나도 없으면 "전체" 항목도 disabled로 처리한다.
-      disabled: selectableOptionIds.length === 0,
+      disabled: selectableOptionValues.length === 0,
     }),
-    [allOptionId, selectAllLabel, selectableOptionIds.length],
+    [allOptionId, selectAllLabel, selectableOptionValues.length],
   );
 
   /**
@@ -206,42 +210,38 @@ export function SelectMultipleTrigger<OptionData = unknown>({
    */
   const resolvedDisplayLabel =
     displayLabel ??
-    (resolvedSelectedIds.length > 0
-      ? optionMap.get(resolvedSelectedIds[0])?.label
+    (resolvedSelectedValues.length > 0
+      ? optionMap.get(toSelectedValueKey(resolvedSelectedValues[0]))?.label
       : undefined);
 
   /**
    * 9) tag 파생 계산
    * - 외부 tags가 주어지면 해당 값을 그대로 사용한다(외부 커스텀 우선).
-   * - tags 미지정이면 selected ids 기반으로 option label을 자동 tag로 변환한다.
+   * - tags 미지정이면 selected values 기반으로 option label을 자동 tag로 변환한다.
    */
   const derivedTags = useMemo<SelectMultipleTag[]>(() => {
     if (tags && tags.length > 0) {
       return tags;
     }
 
-    if (optionMap.size === 0 || resolvedSelectedIds.length === 0) {
+    if (optionMap.size === 0 || resolvedSelectedValues.length === 0) {
       return [];
     }
 
-    return resolvedSelectedIds
-      .map(selectedId => optionMap.get(selectedId))
+    return resolvedSelectedValues
+      .map(selectedValue => optionMap.get(toSelectedValueKey(selectedValue)))
       .filter((option): option is NonNullable<typeof option> => Boolean(option))
       .map(option => ({
         label: option.label,
         removable: false,
       }));
-  }, [tags, resolvedSelectedIds, optionMap]);
+  }, [tags, resolvedSelectedValues, optionMap]);
 
   /**
    * 10) placeholder/label 표시 상태 계산
    * - label 값이 비어 있으면 placeholder 표시로 간주한다.
    */
   const hasTags = derivedTags.length > 0;
-  const hasLabel =
-    resolvedDisplayLabel !== undefined &&
-    resolvedDisplayLabel !== null &&
-    resolvedDisplayLabel !== "";
 
   /**
    * 11) dropdown open 상태 관리
@@ -282,11 +282,6 @@ export function SelectMultipleTrigger<OptionData = unknown>({
   const shouldRenderSelectAllOption = Boolean(
     showSelectAllOption && hasOptions,
   );
-  const renderedOptions = useMemo(
-    // 변경: all-option은 dropdown 첫 행 고정 요구사항에 맞춰 항상 배열 맨 앞에 주입한다.
-    () => (shouldRenderSelectAllOption ? [selectAllOption, ...items] : items),
-    [items, selectAllOption, shouldRenderSelectAllOption],
-  );
   const MAX_VISIBLE_TAGS = 3;
   const visibleTags = hasTags ? derivedTags.slice(0, MAX_VISIBLE_TAGS) : [];
   const overflowCount = hasTags
@@ -295,50 +290,64 @@ export function SelectMultipleTrigger<OptionData = unknown>({
 
   /**
    * 15) option 선택 처리(multiple toggle)
-   * - 이미 선택된 id면 제거, 아니면 추가한다.
+   * - 이미 선택된 value면 제거, 아니면 추가한다.
    * - onSelectOption/onSelectChange 콜백으로 상호작용과 값 변경을 분리해 전달한다.
    */
-  const handleOptionSelect = (optionId: string, event: Event) => {
+  const handleOptionSelect = (
+    option: SelectDropdownOption<OptionData>,
+    event: Event,
+  ) => {
     // 현재 클릭된 옵션이 synthetic all-option인지 먼저 판별한다.
     const isSelectAllOption =
-      shouldRenderSelectAllOption && optionId === allOptionId;
+      shouldRenderSelectAllOption && option.id === allOptionId;
     if (isSelectAllOption) {
       // all-option 클릭 분기
       // - 이미 전체 선택 상태면: selectable option들만 제거(전체 해제)
       // - 일부 선택 상태면: selectable option들을 전부 합집합으로 추가(전체 선택)
-      const nextSelectedOptionIds = isAllSelectableOptionsSelected
-        ? resolvedSelectedIds.filter(
-            selectedId => !selectableOptionIdSet.has(selectedId),
+      const nextSelectedValues = isAllSelectableOptionsSelected
+        ? resolvedSelectedValues.filter(
+            selectedValue =>
+              !selectableOptionValueKeySet.has(
+                toSelectedValueKey(selectedValue),
+              ),
+          )
+        : Array.from(
+            new Set([
+              ...toValueKeys(resolvedSelectedValues),
+              ...toValueKeys(selectableOptionValues),
+            ]),
           )
-        : Array.from(new Set([...resolvedSelectedIds, ...selectableOptionIds]));
-      const didChange = !isSameIdList(
-        resolvedSelectedIds,
-        nextSelectedOptionIds,
+            // 변경: toValuesFromKeys 1회성 헬퍼는 제거하고 선택 시점에서 즉시 복원한다.
+            .map(valueKey => optionMap.get(valueKey)?.value)
+            .filter((value): value is string | number => value !== undefined);
+      const didChange = !isSameSelectedValueList(
+        resolvedSelectedValues,
+        nextSelectedValues,
       );
 
       onSelectOption?.(selectAllOption, undefined, event);
       if (didChange) {
-        setUncontrolledSelectedOptionIds(nextSelectedOptionIds);
+        setUncontrolledSelectedValues(nextSelectedValues);
         onSelectChange?.(selectAllOption, undefined, event);
       }
       return;
     }
 
     // 일반 옵션 클릭 분기
-    // 이미 선택된 id면 제거, 미선택 id면 추가하는 기본 multiple toggle 로직이다.
-    const wasSelected = selectedIdSet.has(optionId);
-    const nextSelectedOptionIds = wasSelected
-      ? resolvedSelectedIds.filter(selectedId => selectedId !== optionId)
-      : [...resolvedSelectedIds, optionId];
-    const currentOption = optionMap.get(optionId);
-
-    if (!currentOption) {
-      return;
-    }
+    // 이미 선택된 value면 제거, 미선택 value면 추가하는 기본 multiple toggle 로직이다.
+    // 변경: 1회성 optionValueKey 상수는 제거하고 판정식에 직접 사용한다.
+    const wasSelected = selectedValueKeySet.has(
+      toSelectedValueKey(option.value),
+    );
+    const nextSelectedValues = wasSelected
+      ? resolvedSelectedValues.filter(
+          selectedValue => !isSameSelectedValue(selectedValue, option.value),
+        )
+      : [...resolvedSelectedValues, option.value];
 
-    onSelectOption?.(currentOption, undefined, event);
-    setUncontrolledSelectedOptionIds(nextSelectedOptionIds);
-    onSelectChange?.(currentOption, undefined, event);
+    onSelectOption?.(option, undefined, event);
+    setUncontrolledSelectedValues(nextSelectedValues);
+    onSelectChange?.(option, undefined, event);
   };
 
   /**
@@ -398,7 +407,11 @@ export function SelectMultipleTrigger<OptionData = unknown>({
               <SelectTriggerSelected
                 label={resolvedDisplayLabel}
                 placeholder={placeholder}
-                isPlaceholder={!hasLabel}
+                isPlaceholder={
+                  resolvedDisplayLabel === undefined ||
+                  resolvedDisplayLabel === null ||
+                  resolvedDisplayLabel === ""
+                }
                 // 변경: Multiple의 Selected 뷰는 표시 전용이므로 항상 편집을 차단한다.
                 readOnly
               />
@@ -414,7 +427,10 @@ export function SelectMultipleTrigger<OptionData = unknown>({
             {hasOptions ? (
               <>
                 {/* multi select 전용 옵션을 Dropdown.Menu.Item으로 노출한다. */}
-                {renderedOptions.map(option => (
+                {(shouldRenderSelectAllOption
+                  ? [selectAllOption, ...items]
+                  : items
+                ).map(option => (
                   <Dropdown.Menu.Item
                     key={option.id}
                     label={option.label}
@@ -425,17 +441,19 @@ export function SelectMultipleTrigger<OptionData = unknown>({
                     multiple
                     isSelected={
                       // synthetic all-option의 checked 상태는 "전체가 선택되었는가"로 계산한다.
-                      // 일반 option은 기존 selectedIdSet membership으로 계산한다.
+                      // 일반 option은 기존 selectedValueKeySet membership으로 계산한다.
                       option.id === allOptionId
                         ? isAllSelectableOptionsSelected
-                        : selectedIdSet.has(option.id)
+                        : selectedValueKeySet.has(
+                            toSelectedValueKey(option.value),
+                          )
                     }
                     onSelect={event => {
                       if (option.disabled || isInteractionBlocked) {
                         event.preventDefault();
                         return;
                       }
-                      handleOptionSelect(option.id, event);
+                      handleOptionSelect(option, event);
                     }}
                   />
                 ))}

package/src/components/table/markup/Container.tsx

@@ -59,6 +59,19 @@ const TableContainer = forwardRef<HTMLTableElement, TableContainerProps>(
     // 변경: footer prop 주입 여부를 table data-attr로 노출해 grid radius 규칙 분기에 사용한다.
     const hasFooter = typeof footer !== "undefined";
 
+    const getStickyLeft = (
+      index: number,
+      unit: string = "px",
+    ): number | string => {
+      // [80, 100, 100, ..., "auto", ...]
+      const widths = resolvedColumns.map(({ width }) =>
+        typeof width === "number" ? width : 0,
+      );
+      const res = widths.slice(0, index).reduce((acc, width) => acc + width, 0);
+
+      return `${res}${unit}`;
+    };
+
     const tableNode = (
       <TableRoot
         {...tableProps}
@@ -90,8 +103,33 @@ const TableContainer = forwardRef<HTMLTableElement, TableContainerProps>(
           <TableHead>
             <TableRow>
               {resolvedColumns.map(
-                ({ key, dataKey, alignX, alignY, cellContents }) => (
-                  <TableTh key={`${key}/head`} data-key={dataKey}>
+                (
+                  { key, dataKey, alignX, alignY, sticky, width, cellContents },
+                  index,
+                ) => (
+                  <TableTh
+                    key={`${key}/head`}
+                    data-key={dataKey}
+                    className={sticky ? "table-cell-sticky" : undefined}
+                    style={
+                      sticky
+                        ? ({
+                            "--table-cell-sticky-left": getStickyLeft(
+                              index,
+                              width &&
+                                typeof width === "string" &&
+                                !isNaN(Number(width))
+                                ? width.endsWith("rem")
+                                  ? "rem"
+                                  : width.endsWith("%")
+                                    ? "%"
+                                    : "px"
+                                : "px",
+                            ),
+                          } as Record<string, number | string>)
+                        : undefined
+                    }
+                  >
                     {/* 변경: header cell 정렬은 alignX/alignY로만 제어한다. */}
                     <TableCell section="head" alignX={alignX} alignY={alignY}>
                       {/* 변경: key는 렌더 식별자이므로 헤더 노출값 fallback으로 사용하지 않는다. */}
@@ -117,6 +155,8 @@ const TableContainer = forwardRef<HTMLTableElement, TableContainerProps>(
     return (
       <div
         className={clsx("table-scroll-wrapper", scrollClassName)}
+        data-layout={tableProps?.layout ?? "line"}
+        data-role={tableProps?.role ?? "table"}
         data-scroll-axis={scrollAxis}
       >
         {tableNode}

package/src/components/table/styles/foundation.scss

@@ -1,3 +1,7 @@
+@function cellHeight($rowspan, $cell-height) {
+  @return calc(#{$rowspan} * #{$cell-height});
+}
+
 .table {
   width: 100%;
   border-collapse: collapse;
@@ -28,13 +32,30 @@
         // table cell 내부 field full-bleed 계산을 위해 padding 값을 변수로 노출한다.
         --table-cell-padding-inline: var(--table-line-cell-padding-inline);
         --table-cell-padding-block: var(--table-line-cell-padding-block);
-        border-bottom: 1px solid var(--table-border-color);
+
+        // 변경: rowspan은 숫자 배수 계산이므로 typed attr(number)로 높이를 계산한다.
+        height: cellHeight(
+          attr(rowspan number, 1),
+          var(--table-line-cell-height-head)
+        );
+
+        :where(.table-cell-content) {
+          border-bottom: 1px solid var(--table-border-color);
+        }
       }
 
       &:where(.table-td) {
         --table-cell-padding-inline: var(--table-line-cell-padding-inline);
         --table-cell-padding-block: var(--table-line-cell-padding-block);
-        border-bottom: 1px solid var(--table-border-color);
+
+        height: cellHeight(
+          attr(rowspan number, 1),
+          var(--table-line-cell-height-body)
+        );
+
+        :where(.table-cell-content) {
+          border-bottom: 1px solid var(--table-border-color);
+        }
       }
     }
 
@@ -42,9 +63,11 @@
       :where(.table-native-cell) {
         &:where(.table-th) {
           height: var(--table-line-cell-height-head);
-          border-top: 1px solid var(--table-border-color);
           background-color: var(--table-line-head-background-color);
         }
+        :where(.table-cell-content) {
+          border-top: 1px solid var(--table-border-color);
+        }
       }
     }
 
@@ -79,7 +102,9 @@
 
     // 변경: line(list) 타입에서 rowspan 셀은 기본적으로 우측 경계선을 표시한다.
     :where(.table-native-cell[rowspan]) {
-      border-right: 1px solid var(--table-border-color);
+      :where(.table-cell-content) {
+        border-right: 1px solid var(--table-border-color);
+      }
     }
   }
 
@@ -96,12 +121,24 @@
         --table-cell-padding-inline: var(--table-grid-cell-padding-inline);
         --table-cell-padding-block: var(--table-grid-cell-padding-block);
         height: var(--table-grid-cell-height);
+        &[rowspan] {
+          height: cellHeight(
+            attr(rowspan number, 1),
+            var(--table-grid-cell-height)
+          );
+        }
       }
 
       &:where(.table-td) {
         --table-cell-padding-inline: var(--table-grid-cell-padding-inline);
         --table-cell-padding-block: var(--table-grid-cell-padding-block);
         height: var(--table-grid-cell-height);
+        &[rowspan] {
+          height: cellHeight(
+            attr(rowspan number, 1),
+            var(--table-grid-cell-height)
+          );
+        }
       }
     }
 
@@ -253,46 +290,54 @@
   }
 
   // 변경: 인라인 스타일 대신 각 row의 첫 번째 th만 sticky로 고정한다.
-  :where(.table-row) {
-    > :where(.table-native-cell:first-child):where(.table-th) {
-      position: sticky;
-      left: 0;
-    }
+  :where(.table-native-cell):where(.table-th) {
+    position: sticky;
+    top: var(--table-cell-sticky-top);
+    left: var(--table-cell-sticky-left);
+    right: var(--table-cell-sticky-right);
+    bottom: var(--table-cell-sticky-bottom);
+    z-index: var(--table-cell-z-index);
   }
 
   // 변경: sticky된 첫 번째 th가 td 위에서 안정적으로 보이도록 섹션별 z-index를 50단위로 분리한다.
   :where(.table-head) {
     :where(.table-row) {
-      > :where(.table-native-cell:first-child):where(.table-th) {
-        z-index: 150;
+      > :where(.table-native-cell):where(.table-th) {
+        --table-cell-z-index: 300;
+        &:where(.table-cell-sticky) {
+          --table-cell-z-index: 400;
+        }
       }
     }
   }
 
   :where(.table-body) {
     :where(.table-row) {
-      > :where(.table-native-cell:first-child):where(.table-th) {
-        z-index: 100;
+      > :where(.table-native-cell):where(.table-th) {
+        --table-cell-z-index: 200;
+        &:where(.table-cell-sticky) {
+          --table-cell-z-index: 300;
+        }
       }
     }
   }
 
   :where(.table-foot) {
     :where(.table-row) {
-      > :where(.table-native-cell:first-child):where(.table-th) {
-        z-index: 50;
+      > :where(.table-native-cell):where(.table-th) {
+        --table-cell-z-index: 200;
       }
     }
   }
 
-  // 변경: scroll 시 index 0 컬럼의 첫 header th가 항상 최상단에 보이도록 z-index를 상향한다.
-  :where(.table-head) {
-    :where(.table-row:first-child) {
-      > :where(.table-native-cell:first-child):where(.table-th) {
-        z-index: 200;
-      }
-    }
-  }
+  // // 변경: scroll 시 index 0 컬럼의 첫 header th가 항상 최상단에 보이도록 z-index를 상향한다.
+  // :where(.table-head) {
+  //   :where(.table-row:first-child) {
+  //     > :where(.table-native-cell:first-child):where(.table-th) {
+  //       --table-cell-z-index: 300;
+  //     }
+  //   }
+  // }
 
   // 변경: footer(table-foot) 내부 셀 콘텐츠 타이포를 body와 동일한 td 스케일로 고정한다.
   :where(.table-foot .table-cell-content) {
@@ -313,7 +358,9 @@
 // 변경: optional scroll 래퍼를 통해 필요한 화면에서만 스크롤 레이어를 분리한다.
 .table-scroll-wrapper {
   width: 100%;
-  border-radius: var(--table-grid-border-radius);
+  &[data-layout="grid"] {
+    border-radius: var(--table-grid-border-radius);
+  }
 }
 
 .table-scroll-wrapper[data-scroll-axis="x"] {

package/src/components/table/styles/variables.scss

@@ -13,6 +13,11 @@
   --table-grid-row-highlight-background-color: rgba(229, 238, 255, 0.52);
   --table-cell-background-color: var(--color-surface-static-white);
 
+  --table-cell-z-index: 100;
+  --table-cell-sticky-top: 0px;
+  --table-cell-sticky-left: auto;
+  --table-cell-sticky-right: auto;
+  --table-cell-sticky-bottom: auto;
   --table-cell-content-gap: var(--spacing-gap-2);
 
   --table-line-cell-height-head: 44px;

package/src/components/table/types/foundation.ts

@@ -100,6 +100,7 @@ export interface TableColgroupProps extends ComponentPropsWithoutRef<"colgroup">
  * @property {"left" | "center" | "right" | "normal" | "start" | "end" | "flex-start" | "flex-end" | "space-between" | "space-around" | "space-evenly" | "stretch"} [alignX] 헤더 가로 정렬(CSS `justify-content` 값과 매핑)
  * @property {"top" | "center" | "bottom" | "normal" | "stretch" | "start" | "end" | "flex-start" | "flex-end" | "self-start" | "self-end" | "baseline"} [alignY] 헤더 세로 정렬(CSS `align-items` 값과 매핑)
  * @property {boolean} [required] 입력 필드 필수여부
+ * @property {boolean} [sticky] 셀 고정 여부
  */
 export interface TableColumnData<
   RowData extends Record<string, unknown> = Record<string, unknown>,
@@ -140,6 +141,10 @@ export interface TableColumnData<
    * 입력 필드 필수여부
    */
   required?: boolean;
+  /**
+   * 셀 고정 여부
+   */
+  sticky?: boolean;
 }
 
 /**

package/src/utils/index.ts

@@ -1,4 +1,4 @@
 /**
  * shared utils placeholder: 토큰 매핑 및 className 헬퍼를 정의한다.
  */
-export {};
+export * from "./selected-values";