@uniai-fe/uds-primitives 0.3.18 → 0.3.20

package/src/components/select/types/props.ts

@@ -1,5 +1,10 @@
-import type { HTMLAttributes, ReactNode } from "react";
+import type {
+  ComponentPropsWithoutRef,
+  HTMLAttributes,
+  ReactNode,
+} from "react";
 import type { DropdownMenuProps } from "@radix-ui/react-dropdown-menu";
+import type { UseFormRegisterReturn } from "react-hook-form";
 
 import type {
   DropdownContainerProps,
@@ -8,7 +13,7 @@ import type {
 } from "../../dropdown/types";
 import type { FormFieldWidth } from "../../form/types";
 import type { SelectPriority, SelectSize, SelectState } from "./base";
-import type { SelectDropdownOption, SelectOptionChangePayload } from "./option";
+import type { SelectDropdownOption } from "./option";
 import type {
   SelectTriggerDefaultProps,
   SelectTriggerMultipleProps,
@@ -24,7 +29,6 @@ import type {
 export interface SelectStyleOptions {
   /**
    * priority scale
-   * - table 우선순위는 width 미지정 시 기본 block(full)로 동작한다.
    */
   priority?: SelectPriority;
   /**
@@ -83,6 +87,7 @@ export interface SelectComponentState {
  * @property {string} [className] 사용자 정의 className
  * @property {ReactNode} children trigger/Dropdown 등 내부 콘텐츠
  * @property {boolean} [block] block 여부
+ * @property {FormFieldWidth} [width] width preset
  */
 export interface SelectContainerProps extends HTMLAttributes<HTMLDivElement> {
   /**
@@ -115,118 +120,191 @@ export interface SelectWidthOption {
 }
 
 /**
- * Select root props
- * @typedef {SelectStyleOptions & SelectValueOptions & SelectComponentState} SelectProps
- * @property {SelectPriority} [priority] priority scale
- * @property {SelectSize} [size] size scale
- * @property {SelectState} [state] visual state
- * @property {boolean} [block] block 여부
- * @property {ReactNode} [displayLabel] 선택된 라벨
- * @property {ReactNode} [placeholder] placeholder 텍스트
- * @property {ReactNode[]} [tags] multi select 태그 리스트
- * @property {boolean} [multiple] multi select 여부
- * @property {boolean} [isOpen] dropdown open 여부
- * @property {FormFieldWidth} [width] width preset 옵션
- */
-export type SelectProps = SelectStyleOptions &
-  SelectValueOptions &
-  SelectComponentState &
-  SelectWidthOption;
-
-/**
- * Select dropdown 옵션 구성 props; 옵션 모델/이벤트/하위호환 제어 축을 정의한다.
- * @property {SelectDropdownOption[]} [options] dropdown option 리스트(권장: options[].selected로 초기값 선언)
- * @property {string[]} [selectedOptionIds] 선택된 option id 리스트(legacy controlled)
- * @property {(payload: SelectOptionChangePayload) => void} [onChange] 선택 결과 변경 콜백(권장)
- * @property {(option: SelectDropdownOption) => void} [onOptionSelect] option 선택 콜백(legacy)
- * @property {SelectSize} [dropdownSize] dropdown surface size 스케일
- * @property {DropdownPanelWidth} [dropdownWidth="match"] dropdown panel width 옵션
- * @property {DropdownMenuProps} [dropdownRootProps] Dropdown.Root 전달 props(제어 props 제외)
- * @property {DropdownContainerProps} [dropdownContainerProps] Dropdown.Container 전달 props(children/size 제외)
- * @property {DropdownMenuListProps} [dropdownMenuListProps] Dropdown.Menu.List 전달 props
- * @property {ReactNode} [alt] option이 비어 있을 때 렌더링할 alternate 콘텐츠
+ * Select custom option props
+ * @property {string} [placeholder] 직접입력 모드 전용 placeholder
+ * @property {ReactNode} [optionName] dropdown의 "직접 입력" 옵션 문구
  */
-export interface SelectDropdownConfigProps {
+export interface SelectCustomOptions {
   /**
-   * dropdown option 리스트
-   * - 권장: uncontrolled 초기 선택은 options[].selected를 사용한다.
+   * 직접입력 모드 전용 placeholder
+   * - 미지정 시 Select root placeholder를 재사용한다.
    */
-  options?: SelectDropdownOption[];
+  placeholder?: string;
   /**
-   * 선택된 option id 리스트
-   * @deprecated onChange + options[].selected 기반 계약을 우선 사용한다.
+   * dropdown의 "직접 입력" 옵션 문구
+   * - 미지정 시 "직접 입력"을 기본값으로 사용한다.
    */
-  selectedOptionIds?: string[];
+  optionName?: ReactNode;
+}
+
+/**
+ * Select custom input props
+ * @property {ComponentPropsWithoutRef<"input">} [native] label input native 속성
+ */
+export interface SelectCustomInputProps extends ComponentPropsWithoutRef<"input"> {
+  placeholder?: never;
+}
+
+/**
+ * Select form register extension
+ * @property {UseFormRegisterReturn} [register] source field register(기본: hidden value input)
+ * @property {UseFormRegisterReturn} [customRegister] custom field register(직접입력 label input)
+ */
+export interface SelectFormRegisterExtension {
   /**
-   * 선택 결과 변경 콜백
-   * - 권장: payload.selectedOptions / payload.selectedValues를 직접 소비한다.
+   * source field register
+   * - Select value 제출 필드(`select-input-value`)에 연결한다.
    */
-  onChange?: (payload: SelectOptionChangePayload) => void;
+  register?: UseFormRegisterReturn;
   /**
-   * option 선택 콜백
-   * @deprecated onChange로 대체되며 하위호환을 위해 유지된다.
+   * custom field register
+   * - 직접입력 label 필드(`select-input-label`)에 연결한다.
    */
-  onOptionSelect?: (option: SelectDropdownOption) => void;
+  customRegister?: UseFormRegisterReturn;
+}
+
+/**
+ * Select callback params
+ * @property {SelectDropdownOption} [nextOption] 현재 상호작용한 option
+ * @property {SelectDropdownOption} [prevOption] 이전 기준 option
+ * @property {Event} [event] 원본 메뉴 선택 이벤트
+ */
+export type SelectCallbackParams = (
+  nextOption?: SelectDropdownOption,
+  prevOption?: SelectDropdownOption,
+  event?: Event,
+) => void;
+
+/**
+ * Select dropdown 확장 props
+ * @property {SelectSize} [size] dropdown surface size 스케일
+ * @property {DropdownPanelWidth} [width] dropdown panel width 옵션
+ * @property {Omit<DropdownMenuProps, "open" | "defaultOpen" | "onOpenChange">} [rootProps] Dropdown.Root 전달 props
+ * @property {Omit<DropdownContainerProps, "children" | "size" | "width">} [containerProps] Dropdown.Container 전달 props
+ * @property {DropdownMenuListProps} [menuListProps] Dropdown.Menu.List 전달 props
+ * @property {ReactNode} [alt] option이 비어 있을 때 렌더링할 alternate 콘텐츠
+ */
+export interface SelectDropdownExtension {
   /**
    * dropdown surface size 스케일
    */
-  dropdownSize?: SelectSize;
+  size?: SelectSize;
   /**
    * dropdown panel width 옵션
    */
-  dropdownWidth?: DropdownPanelWidth;
+  width?: DropdownPanelWidth;
   /**
    * Dropdown.Root 전달 props(제어 props 제외)
-   * - 타입 출처를 명확히 하기 위해 Radix 원본 타입을 직접 사용한다.
    */
-  dropdownRootProps?: Omit<
-    DropdownMenuProps,
-    "open" | "defaultOpen" | "onOpenChange"
-  >;
+  rootProps?: Omit<DropdownMenuProps, "open" | "defaultOpen" | "onOpenChange">;
   /**
-   * Dropdown.Container 전달 props(children/size 제외)
+   * Dropdown.Container 전달 props(children/size/width 제외)
    */
-  dropdownContainerProps?: Omit<
-    DropdownContainerProps,
-    "children" | "size" | "width"
-  >;
+  containerProps?: Omit<DropdownContainerProps, "children" | "size" | "width">;
   /**
    * Dropdown.Menu.List 전달 props
    */
-  dropdownMenuListProps?: DropdownMenuListProps;
+  menuListProps?: DropdownMenuListProps;
   /**
-   * option이 비어 있을 때 렌더링할 alternate 콘텐츠
+   * item이 비어 있을 때 렌더링할 alternate 콘텐츠
    */
   alt?: ReactNode;
 }
 
 /**
- * Select dropdown 개방 제어 props; open controlled/uncontrolled 축을 정의한다.
+ * Select dropdown 옵션 구성 props
+ * @property {SelectDropdownOption[]} [items] dropdown item 리스트(권장: items[].selected 초기값)
+ * @property {SelectCallbackParams} [onSelectOption] option 선택 액션 콜백
+ * @property {SelectCallbackParams} [onSelectChange] 선택값 변경 콜백
+ * @property {SelectDropdownExtension} [dropdown] dropdown 확장 옵션
+ */
+export interface SelectDropdownConfigProps {
+  /**
+   * dropdown item 리스트
+   */
+  items: SelectDropdownOption[];
+  /**
+   * option 선택 액션 콜백
+   */
+  onSelectOption?: SelectCallbackParams;
+  /**
+   * 선택값 변경 콜백
+   */
+  onSelectChange?: SelectCallbackParams;
+  /**
+   * dropdown 확장 옵션
+   */
+  dropdownOptions?: SelectDropdownExtension;
+}
+
+/**
+ * Select dropdown 개방 제어 props
  * @property {boolean} [open] dropdown open 상태
  * @property {boolean} [defaultOpen] uncontrolled 초기 open 상태
- * @property {(open: boolean) => void} [onOpenChange] open state change 콜백
+ * @property {(open: boolean) => void} [onOpen] open state change 콜백
  */
 export interface SelectDropdownBehaviorProps {
   /**
    * dropdown open 상태
-   * - 값이 있으면 controlled open 모드로 동작한다.
    */
   open?: boolean;
   /**
    * uncontrolled 초기 open 상태
-   * - open prop이 없을 때만 초기값으로 사용된다.
    */
   defaultOpen?: boolean;
   /**
    * open state change 콜백
-   * - controlled/uncontrolled 모두에서 호출된다.
    */
-  onOpenChange?: (open: boolean) => void;
+  onOpen?: (open: boolean) => void;
+}
+
+/**
+ * Select trigger native event props
+ * @property {HTMLAttributes<HTMLElement>} [triggerProps] trigger native 속성/이벤트
+ */
+export interface SelectTriggerEventProps {
+  /**
+   * trigger native 속성/이벤트
+   */
+  triggerProps?: HTMLAttributes<HTMLElement>;
 }
 
+/**
+ * Select custom option extension
+ * @property {SelectCustomOptions} [customOptions] 직접 입력 옵션 구성
+ * @property {SelectCustomInputProps} [inputProps] 직접 입력 input 구성
+ */
+export interface SelectCustomOptionExtension {
+  /**
+   * 직접 입력 옵션 구성
+   */
+  customOptions?: SelectCustomOptions;
+  /**
+   * 직접 입력 input 구성
+   */
+  inputProps?: SelectCustomInputProps;
+}
+
+/**
+ * Select root props
+ * @property {SelectPriority} [priority] priority scale
+ * @property {SelectSize} [size] size scale
+ * @property {SelectState} [state] visual state
+ * @property {boolean} [block] block 여부
+ * @property {ReactNode} [displayLabel] 선택된 라벨
+ * @property {ReactNode} [placeholder] placeholder 텍스트
+ * @property {ReactNode[]} [tags] multi select 태그 리스트
+ * @property {boolean} [multiple] multi select 여부
+ * @property {boolean} [isOpen] dropdown open 여부
+ * @property {FormFieldWidth} [width] width preset 옵션
+ */
+export type SelectProps = SelectStyleOptions &
+  SelectValueOptions &
+  SelectComponentState &
+  SelectWidthOption;
+
 /**
  * Select.Default 컴포넌트 props
- * @typedef {SelectTriggerDefaultProps & SelectDropdownConfigProps & SelectDropdownBehaviorProps & SelectWidthOption} SelectDefaultComponentProps
  * @property {ReactNode} [displayLabel] 선택된 라벨
  * @property {ReactNode} [placeholder] placeholder 텍스트
  * @property {SelectPriority} [priority] priority scale
@@ -238,24 +316,26 @@ export interface SelectDropdownBehaviorProps {
  * @property {boolean} [readOnly] readOnly 여부
  * @property {SelectTriggerButtonType} [buttonType] button type
  * @property {FormFieldWidth} [width] width preset 옵션
- * @property {SelectDropdownOption[]} [options] dropdown option 리스트
- * @property {string[]} [selectedOptionIds] 선택된 option id 리스트
- * @property {(payload: SelectOptionChangePayload) => void} [onChange] 선택 결과 변경 콜백
- * @property {(option: SelectDropdownOption) => void} [onOptionSelect] option 선택 콜백
- * @property {SelectSize} [dropdownSize] dropdown surface size 스케일
- * @property {DropdownPanelWidth} [dropdownWidth="match"] dropdown panel width 옵션
- * @property {Omit<DropdownMenuProps, "open" | "defaultOpen" | "onOpenChange">} [dropdownRootProps] Dropdown.Root 전달 props
- * @property {Omit<DropdownContainerProps, "children" | "size" | "width">} [dropdownContainerProps] Dropdown.Container 전달 props
- * @property {DropdownMenuListProps} [dropdownMenuListProps] Dropdown.Menu.List 전달 props
- * @property {ReactNode} [alt] option이 비어 있을 때 렌더링할 alternate 콘텐츠
+ * @property {SelectDropdownOption[]} [items] dropdown item 리스트
+ * @property {SelectCallbackParams} [onSelectOption] option 선택 액션 콜백
+ * @property {SelectCallbackParams} [onSelectChange] 선택값 변경 콜백
+ * @property {SelectDropdownExtension} [dropdown] dropdown 확장 옵션
  * @property {boolean} [open] dropdown open 상태
  * @property {boolean} [defaultOpen] uncontrolled 초기 open 상태
- * @property {(open: boolean) => void} [onOpenChange] open state change 콜백
+ * @property {(open: boolean) => void} [onOpen] open state change 콜백
+ * @property {HTMLAttributes<HTMLElement>} [triggerProps] trigger native 속성/이벤트
+ * @property {SelectCustomOptions} [customOptions] 직접 입력 옵션 구성
+ * @property {SelectCustomInputProps} [inputProps] 직접 입력 input 구성
+ * @property {UseFormRegisterReturn} [register] source field register
+ * @property {UseFormRegisterReturn} [customRegister] custom field register
  */
 export type SelectDefaultComponentProps = SelectTriggerDefaultProps &
   SelectDropdownConfigProps &
   SelectDropdownBehaviorProps &
-  SelectWidthOption;
+  SelectWidthOption &
+  SelectTriggerEventProps &
+  SelectCustomOptionExtension &
+  SelectFormRegisterExtension;
 
 /**
  * Select.Multiple 전체 선택 옵션 props
@@ -275,7 +355,6 @@ export interface SelectMultipleAllOptionProps {
 
 /**
  * Select.Multiple 컴포넌트 props
- * @typedef {SelectTriggerMultipleProps & SelectDropdownConfigProps & SelectDropdownBehaviorProps & SelectWidthOption & SelectMultipleAllOptionProps} SelectMultipleComponentProps
  * @property {ReactNode} [displayLabel] 선택된 라벨
  * @property {ReactNode} [placeholder] placeholder 텍스트
  * @property {SelectMultipleTag[]} [tags] multi select tag 리스트
@@ -287,19 +366,14 @@ export interface SelectMultipleAllOptionProps {
  * @property {boolean} [disabled] disabled 여부
  * @property {boolean} [readOnly] readOnly 여부
  * @property {FormFieldWidth} [width] width preset 옵션
- * @property {SelectDropdownOption[]} [options] dropdown option 리스트
- * @property {string[]} [selectedOptionIds] 선택된 option id 리스트
- * @property {(payload: SelectOptionChangePayload) => void} [onChange] 선택 결과 변경 콜백
- * @property {(option: SelectDropdownOption) => void} [onOptionSelect] option 선택 콜백
- * @property {SelectSize} [dropdownSize] dropdown surface size 스케일
- * @property {DropdownPanelWidth} [dropdownWidth="match"] dropdown panel width 옵션
- * @property {Omit<DropdownMenuProps, "open" | "defaultOpen" | "onOpenChange">} [dropdownRootProps] Dropdown.Root 전달 props
- * @property {Omit<DropdownContainerProps, "children" | "size" | "width">} [dropdownContainerProps] Dropdown.Container 전달 props
- * @property {DropdownMenuListProps} [dropdownMenuListProps] Dropdown.Menu.List 전달 props
- * @property {ReactNode} [alt] option이 비어 있을 때 렌더링할 alternate 콘텐츠
+ * @property {SelectDropdownOption[]} [items] dropdown item 리스트
+ * @property {SelectCallbackParams} [onSelectOption] option 선택 액션 콜백
+ * @property {SelectCallbackParams} [onSelectChange] 선택값 변경 콜백
+ * @property {SelectDropdownExtension} [dropdown] dropdown 확장 옵션
  * @property {boolean} [open] dropdown open 상태
  * @property {boolean} [defaultOpen] uncontrolled 초기 open 상태
- * @property {(open: boolean) => void} [onOpenChange] open state change 콜백
+ * @property {(open: boolean) => void} [onOpen] open state change 콜백
+ * @property {HTMLAttributes<HTMLElement>} [triggerProps] trigger native 속성/이벤트
  * @property {boolean} [showSelectAllOption] dropdown 첫 행에 "전체" 옵션 노출 여부
  * @property {ReactNode} [selectAllLabel] "전체" 옵션 라벨 커스터마이징
  */
@@ -307,4 +381,5 @@ export type SelectMultipleComponentProps = SelectTriggerMultipleProps &
   SelectDropdownConfigProps &
   SelectDropdownBehaviorProps &
   SelectWidthOption &
-  SelectMultipleAllOptionProps;
+  SelectMultipleAllOptionProps &
+  SelectTriggerEventProps;

package/src/components/select/types/trigger.ts

@@ -1,4 +1,11 @@
-import type { ElementType, HTMLAttributes, ReactNode } from "react";
+import type {
+  ComponentPropsWithoutRef,
+  ElementType,
+  HTMLAttributes,
+  ReactNode,
+} from "react";
+import type { UseFormRegisterReturn } from "react-hook-form";
+import type { SelectOptionValue } from "./option";
 
 import type {
   SelectPriority,
@@ -32,6 +39,7 @@ export interface SelectTriggerBaseProps extends HTMLAttributes<HTMLElement> {
   priority?: SelectPriority;
   /**
    * size scale
+   * - xsmall (primary 전용)
    * - small
    * - medium
    * - large
@@ -101,6 +109,7 @@ export interface SelectTriggerDefaultProps extends HTMLAttributes<HTMLElement> {
   priority?: SelectPriority;
   /**
    * size scale
+   * - xsmall (primary 전용)
    * - small
    * - medium
    * - large
@@ -161,6 +170,7 @@ export interface SelectTriggerMultipleProps extends HTMLAttributes<HTMLElement>
   priority?: SelectPriority;
   /**
    * size scale
+   * - xsmall (primary 전용)
    * - small
    * - medium
    * - large
@@ -196,6 +206,14 @@ export interface SelectTriggerMultipleProps extends HTMLAttributes<HTMLElement>
  * @property {ReactNode} [label] 표시할 라벨
  * @property {ReactNode} [placeholder] placeholder 텍스트
  * @property {boolean} [isPlaceholder] placeholder 상태 여부
+ * @property {boolean} [readOnly] readOnly 여부
+ * @property {UseFormRegisterReturn} [register] source field register
+ * @property {UseFormRegisterReturn} [customRegister] custom field register
+ * @property {ComponentPropsWithoutRef<"input">} [inputProps] label input native 속성
+ * @property {string} [valueText] label input 표시 문자열
+ * @property {SelectOptionValue | ""} [valueFieldValue] hidden value input 값
+ * @property {boolean} [shouldFocusInput] custom mode 진입 시 label input focus 여부
+ * @property {(value: string) => void} [onLabelChange] label 입력 변경 콜백
  */
 export interface SelectSelectedProps {
   /**
@@ -210,4 +228,37 @@ export interface SelectSelectedProps {
    * placeholder 상태 여부
    */
   isPlaceholder?: boolean;
+  /**
+   * readOnly 여부
+   */
+  readOnly?: boolean;
+  /**
+   * source field register
+   */
+  register?: UseFormRegisterReturn;
+  /**
+   * custom field register
+   */
+  customRegister?: UseFormRegisterReturn;
+  /**
+   * label input native 속성
+   * - placeholder는 root/customOptions 경로가 우선하므로 제외한다.
+   */
+  inputProps?: Omit<ComponentPropsWithoutRef<"input">, "placeholder">;
+  /**
+   * label input 표시 문자열
+   */
+  valueText?: string;
+  /**
+   * hidden value input 값
+   */
+  valueFieldValue?: SelectOptionValue | "";
+  /**
+   * custom mode 진입 시 label input focus 여부
+   */
+  shouldFocusInput?: boolean;
+  /**
+   * label 입력 변경 콜백
+   */
+  onLabelChange?: (value: string) => void;
 }

package/src/components/slot/index.tsx

@@ -1,6 +1,2 @@
-export { default as SlotComponent } from "./markup/Component";
-export type {
-  SlotComponentProps,
-  SlotComponentType,
-  PolymorphicRef,
-} from "./types/props";
+export * from "./markup";
+export type * from "./types";

package/src/components/slot/markup/Text.tsx

@@ -0,0 +1,34 @@
+import type { ElementType } from "react";
+import clsx from "clsx";
+import SlotBase from "./Base";
+import type { SlotTextProps } from "../types/text";
+
+/**
+ * SlotText; 텍스트 역할 children만 래핑하는 공용 슬롯.
+ * @component
+ * @param {SlotTextProps} props
+ * @param {React.ElementType} [props.as="span"] 렌더링할 요소.
+ * @param {React.ReactNode} [props.children] 문자열/숫자는 래핑하고, 그 외 ReactNode는 그대로 반환한다.
+ * @param {string} [props.className] 래핑 시 적용할 className.
+ */
+export default function SlotText<C extends ElementType = "span">({
+  as = "span" as C,
+  children,
+  className,
+  ...restProps
+}: SlotTextProps<C>) {
+  if (!["string", "number"].includes(typeof children)) {
+    return children;
+  }
+
+  // 문자열/숫자 children만 공통 slot text 마크업으로 감싼다.
+  return (
+    <SlotBase
+      as={as as ElementType}
+      className={clsx("slot-text", className)}
+      {...restProps}
+    >
+      {children}
+    </SlotBase>
+  );
+}

package/src/components/slot/markup/index.tsx

@@ -0,0 +1,7 @@
+import SlotBase from "./Base";
+import SlotText from "./Text";
+
+export const Slot = {
+  Base: SlotBase,
+  Text: SlotText,
+};

package/src/components/slot/types/index.ts

@@ -0,0 +1,2 @@
+export type * from "./props";
+export type * from "./text";

package/src/components/slot/types/text.ts

@@ -0,0 +1,24 @@
+import type { ElementType, ReactNode } from "react";
+import type { SlotComponentRestProps } from "./props";
+
+/**
+ * SlotTextProps; 텍스트 역할 children 래핑용 공통 props.
+ * @property {React.ElementType} [as] 렌더링할 요소. 기본값은 span.
+ * @property {React.ReactNode} [children] 문자열/숫자는 래핑하고 그 외 ReactNode는 그대로 반환한다.
+ * @property {string} [className] 텍스트 래퍼 className.
+ */
+export type SlotTextProps<C extends ElementType = "span"> =
+  SlotComponentRestProps<C> & {
+    /**
+     * 렌더링할 요소.
+     */
+    as?: C;
+    /**
+     * 텍스트/노드 children.
+     */
+    children?: ReactNode;
+    /**
+     * 텍스트 래퍼 className.
+     */
+    className?: string;
+  };

package/src/components/table/markup/foundation/Cell.tsx

@@ -1,6 +1,7 @@
 import clsx from "clsx";
 import { forwardRef } from "react";
 import type { TableCellContentProps } from "../../types";
+import TableText from "./Text";
 
 /**
  * Table Foundation; Cell 콘텐츠 래퍼 컴포넌트
@@ -48,18 +49,9 @@ const TableCell = forwardRef<HTMLDivElement, TableCellContentProps>(
         )}
       >
         {/* 변경: 텍스트 콘텐츠는 slot 전용 className으로 감싸 스타일 적용 범위를 고정한다. */}
-        {typeof children === "string" || typeof children === "number" ? (
-          <span
-            className={clsx(
-              "table-cell-text",
-              section && `table-${section}-cell-text`,
-            )}
-          >
-            {children}
-          </span>
-        ) : (
-          children
-        )}
+        <TableText className={clsx(section && `table-${section}-cell-text`)}>
+          {children}
+        </TableText>
       </div>
     );
   },

package/src/components/table/markup/foundation/Td.tsx

@@ -1,6 +1,7 @@
 import clsx from "clsx";
 import { forwardRef } from "react";
 import type { TableTdProps } from "../../types";
+import TableText from "./Text";
 
 /**
  * Table Foundation; Td 마크업 컴포넌트
@@ -20,13 +21,9 @@ const TableTd = forwardRef<HTMLTableCellElement, TableTdProps>(
         style={{ ...style, textAlign: "left" }}
       >
         {/* 변경: 태그 셀렉터 의존을 피하기 위해 className 기반 텍스트 노드를 사용한다. */}
-        {typeof children === "string" || typeof children === "number" ? (
-          <span className={clsx("table-native-cell-text", "table-td-text")}>
-            {children}
-          </span>
-        ) : (
-          children
-        )}
+        <TableText className={clsx("table-native-cell-text", "table-td-text")}>
+          {children}
+        </TableText>
       </td>
     );
   },

package/src/components/table/markup/foundation/Text.tsx

@@ -0,0 +1,16 @@
+import clsx from "clsx";
+import { Slot } from "../../../slot";
+import type { TableTextProps } from "../../types";
+
+/**
+ * Table Text; th/td/cell 텍스트 공통 렌더 컴포넌트.
+ * @component
+ * @param {TableTextProps} props
+ * @param {React.ReactNode} [props.children] 텍스트 콘텐츠
+ * @param {string} [props.className] table text className
+ */
+export default function TableText({ className, ...restProps }: TableTextProps) {
+  return (
+    <Slot.Text className={clsx("table-cell-text", className)} {...restProps} />
+  );
+}

package/src/components/table/markup/foundation/Th.tsx

@@ -1,6 +1,7 @@
 import clsx from "clsx";
 import { forwardRef } from "react";
 import type { TableThProps } from "../../types";
+import TableText from "./Text";
 
 /**
  * Table Foundation; Th 마크업 컴포넌트
@@ -29,13 +30,9 @@ const TableTh = forwardRef<HTMLTableCellElement, TableThProps>(
         style={style}
       >
         {/* 변경: 태그 셀렉터 의존을 피하기 위해 className 기반 텍스트 노드를 사용한다. */}
-        {typeof children === "string" || typeof children === "number" ? (
-          <span className={clsx("table-native-cell-text", "table-th-text")}>
-            {children}
-          </span>
-        ) : (
-          children
-        )}
+        <TableText className={clsx("table-native-cell-text", "table-th-text")}>
+          {children}
+        </TableText>
       </th>
     );
   },

package/src/components/table/markup/foundation/index.tsx

@@ -8,6 +8,7 @@ import TableTh from "./Th";
 import TableRoot from "./Root";
 import TableRow from "./Row";
 import TableTd from "./Td";
+import TableText from "./Text";
 
 /**
  * Table Foundation; 기초 마크업 컴포넌트 세트
@@ -27,4 +28,5 @@ export const TableFoundation = {
   Tr: TableRow,
   Th: TableTh,
   Td: TableTd,
+  Text: TableText,
 };

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

@@ -1,4 +1,5 @@
 import type { ComponentPropsWithoutRef } from "react";
+import type { SlotTextProps } from "../../slot";
 
 export const TABLE_CELL_ALIGN_OPTIONS = ["left", "center", "right"] as const;
 export const TABLE_CELL_ALIGN_Y_OPTIONS = ["top", "center", "bottom"] as const;
@@ -273,3 +274,11 @@ export interface TableHeadCellProps extends TableThProps {}
  * @deprecated `TableTdProps` 사용을 권장한다.
  */
 export interface TableCellProps extends TableTdProps {}
+
+/**
+ * Table Types; Text 렌더 props
+ * @property {React.ElementType} [as] 렌더링할 요소. 기본값은 span.
+ * @property {React.ReactNode} [children] 텍스트 콘텐츠
+ * @property {string} [className] table text className
+ */
+export type TableTextProps = SlotTextProps;