@uniai-fe/uds-primitives 0.3.21 → 0.3.23

package/README.md

@@ -114,6 +114,13 @@ function Templates() {
 
 - TextInput Base 컴포넌트의 `clear` 버튼 로직을 pointer 이벤트 기반으로 재작성해 모바일 터치 환경에서도 안정적으로 입력값이 초기화되도록 했다.
 - react-hook-form `register`와 연계된 값도 동일하게 초기화되며, focus가 빠지면 clear 버튼이 자동으로 숨겨진다.
+- `Input.TextArea`를 추가했다.
+  - `height?: number | string`으로 높이를 직접 제어한다. (기본 `128px`)
+  - `length?: number`을 주면 `0 / n자` 카운터가 우측 하단에 노출된다.
+  - 기본 `resize`는 비활성(`none`)이며, `size` 축은 Input 기본 size token(`--input-default-*`)을 재사용한다.
+- Select/Dropdown 계약을 `items` 중심으로 정렬했다.
+  - Select: `items`, `onSelectChange`, `dropdownOptions`, `open/defaultOpen/onOpen`
+  - Dropdown.Template: `items[].selected + onChange(payload)`
 
 ## 스타일 내보내기
 

package/dist/styles.css

@@ -361,6 +361,27 @@
   --input-tertiary-radius-base: var(--theme-radius-large-2);
   --input-table-radius-base: 0;
   --input-tertiary-element-min-height: var(--theme-size-medium-2);
+  --input-textarea-min-height: calc(var(--input-default-height-medium) * 2);
+  --input-textarea-height: 128px;
+  /* TextArea size token은 Input 기본 size token을 재할당해 축을 일치시킨다. */
+  --input-textarea-radius-small: var(--input-default-radius-base);
+  --input-textarea-radius-medium: var(--input-default-radius-base);
+  --input-textarea-radius-large: var(--input-default-radius-base);
+  --input-textarea-padding-inline-small: var(--spacing-padding-6);
+  --input-textarea-padding-inline-medium: var(--spacing-padding-6);
+  --input-textarea-padding-inline-large: var(--spacing-padding-6);
+  --input-textarea-padding-block-small: var(--spacing-padding-5);
+  --input-textarea-padding-block-medium: var(--spacing-padding-5);
+  --input-textarea-padding-block-large: var(--spacing-padding-6);
+  --input-textarea-gap-small: var(--input-default-gap);
+  --input-textarea-gap-medium: var(--input-default-gap);
+  --input-textarea-gap-large: var(--input-default-gap);
+  --input-textarea-counter-font-size: var(--font-label-medium-size);
+  --input-textarea-counter-line-height: var(--font-label-medium-line-height);
+  --input-textarea-counter-font-weight: var(--font-label-medium-weight);
+  --input-textarea-counter-letter-spacing: var(
+  --font-label-medium-letter-spacing
+  );
   --input-table-text-small-size: var(--font-body-xxsmall-size);
   --input-table-text-small-line-height: var(--font-body-xxsmall-line-height);
   --input-table-text-small-weight: var(--font-body-xxsmall-weight);
@@ -2288,6 +2309,9 @@ figure.chip {
   font-weight: var(--dropdown-option-font-weight, var(--dropdown-text-weight));
   line-height: var(--dropdown-option-line-height, var(--dropdown-text-medium-line-height));
 }
+.dropdown-menu-item-trigger span {
+  user-select: none;
+}
 .dropdown-menu-item-trigger[data-state=selected] {
   background-color: var(--dropdown-option-bg-selected);
   color: var(--dropdown-option-color-selected);
@@ -2314,7 +2338,7 @@ figure.chip {
 
 .dropdown-menu-item-left,
 .dropdown-menu-item-right {
-  display: inline-flex;
+  display: flex;
   align-items: center;
   color: inherit;
 }
@@ -2328,7 +2352,7 @@ figure.chip {
 }
 
 .dropdown-menu-item-label {
-  display: inline-flex;
+  display: flex;
   align-items: center;
   min-width: 0;
   color: inherit;
@@ -2730,6 +2754,47 @@ figure.chip {
   min-width: 0;
 }
 
+.input[data-input-type=textarea] .input-field {
+  --input-textarea-radius: var(--input-textarea-radius-medium);
+  --input-textarea-padding-inline: var(--input-textarea-padding-inline-medium);
+  --input-textarea-padding-block: var(--input-textarea-padding-block-medium);
+  --input-textarea-gap: var(--input-textarea-gap-medium);
+  align-items: stretch;
+  flex-direction: column;
+  gap: var(--input-textarea-gap);
+  border-radius: var(--input-textarea-radius);
+  padding: var(--input-textarea-padding-block) var(--input-textarea-padding-inline);
+}
+.input[data-input-type=textarea] .input-field[data-size=small] {
+  --input-textarea-radius: var(--input-textarea-radius-small);
+  --input-textarea-padding-inline: var(--input-textarea-padding-inline-small);
+  --input-textarea-padding-block: var(--input-textarea-padding-block-small);
+  --input-textarea-gap: var(--input-textarea-gap-small);
+}
+.input[data-input-type=textarea] .input-field[data-size=large] {
+  --input-textarea-radius: var(--input-textarea-radius-large);
+  --input-textarea-padding-inline: var(--input-textarea-padding-inline-large);
+  --input-textarea-padding-block: var(--input-textarea-padding-block-large);
+  --input-textarea-gap: var(--input-textarea-gap-large);
+}
+
+.input-textarea-element {
+  min-height: var(--input-textarea-min-height);
+  height: var(--input-textarea-height);
+  resize: none;
+  margin: 0;
+}
+
+.input-textarea-length {
+  margin: 0;
+  align-self: flex-end;
+  color: var(--input-placeholder-color);
+  font-size: var(--input-textarea-counter-font-size);
+  line-height: var(--input-textarea-counter-line-height);
+  font-weight: var(--input-textarea-counter-font-weight);
+  letter-spacing: var(--input-textarea-counter-letter-spacing);
+}
+
 .input-field-utilities {
   display: flex;
   align-items: center;
@@ -2851,11 +2916,15 @@ figure.chip {
 .input[data-state=error] .input-helper-text {
   color: var(--input-label-error-color);
 }
+.input[data-state=error] .input-textarea-length {
+  color: var(--input-label-error-color);
+}
 
 .input[data-state=disabled] .input-label,
 .input[data-state=disabled] .input-inline-label,
 .input[data-state=disabled] .input-helper-text,
-.input[data-state=disabled] .input-affix {
+.input[data-state=disabled] .input-affix,
+.input[data-state=disabled] .input-textarea-length {
   color: var(--input-helper-disabled-color);
 }
 .input[data-state=disabled] .input-field {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniai-fe/uds-primitives",
-  "version": "0.3.21",
+  "version": "0.3.23",
   "description": "UNIAI Design System; Primitives Components Package",
   "type": "module",
   "private": false,

package/src/components/dropdown/markup/foundation/MenuItem.tsx

@@ -7,6 +7,7 @@ import { forwardRef } from "react";
 import type { DropdownMenuItemProps } from "../../types/props";
 import { Checkbox } from "../../../checkbox/markup/Checkbox";
 import type { CheckboxProps } from "../../../checkbox/types";
+import { Slot } from "../../../slot";
 
 /**
  * Dropdown Foundation; Menu Item 옵션 렌더링 컴포넌트
@@ -42,13 +43,10 @@ const DropdownMenuItem = forwardRef<HTMLDivElement, DropdownMenuItemProps>(
     ref,
   ) => {
     const labelContent = label ?? children;
-    // 변경: label/children이 string|number일 때만 준비된 label span으로 매핑하고, 그 외 ReactNode는 그대로 렌더링한다.
-    const resolvedLabelContent =
-      typeof labelContent === "string" || typeof labelContent === "number" ? (
-        <span className="dropdown-menu-item-label">{labelContent}</span>
-      ) : (
-        labelContent
-      );
+    // 변경: label 렌더링을 Slot.Text 경로로 통일해 string|number만 공통 래핑 규칙을 적용한다.
+    const resolvedLabelContent = (
+      <Slot.Text className="dropdown-menu-item-label">{labelContent}</Slot.Text>
+    );
     const hasDescription = Boolean(description);
     const shouldRenderCheckbox = multiple && !left;
 

package/src/components/dropdown/styles/dropdown.scss

@@ -98,6 +98,10 @@
     var(--dropdown-text-medium-line-height)
   );
 
+  span {
+    user-select: none;
+  }
+
   &[data-state="selected"] {
     background-color: var(--dropdown-option-bg-selected);
     color: var(--dropdown-option-color-selected);
@@ -134,7 +138,8 @@
 
 .dropdown-menu-item-left,
 .dropdown-menu-item-right {
-  display: inline-flex;
+  // 변경: inline-* 금지 규칙에 맞춰 정렬 컨테이너를 flex로 통일한다.
+  display: flex;
   align-items: center;
   color: inherit;
 }
@@ -148,7 +153,8 @@
 }
 
 .dropdown-menu-item-label {
-  display: inline-flex;
+  // 변경: inline-* 금지 규칙에 맞춰 라벨 렌더 박스를 flex로 유지한다.
+  display: flex;
   align-items: center;
   min-width: 0;
   color: inherit;

package/src/components/input/markup/foundation/TextArea.tsx

@@ -0,0 +1,236 @@
+"use client";
+
+import clsx from "clsx";
+import type { CSSProperties, ChangeEvent, FocusEvent } from "react";
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useId,
+  useMemo,
+  useState,
+} from "react";
+import type { InputTextAreaProps } from "../../types";
+import {
+  getFormFieldWidthAttr,
+  getFormFieldWidthValue,
+} from "../../../form/utils/form-field";
+
+/**
+ * Native `<textarea>` 기반 텍스트 영역.
+ * Input.Base와 동일한 priority/size/state/width/register 계약을 사용한다.
+ *
+ * @component
+ * @param {InputTextAreaProps} props TextArea 컴포넌트 공통 props
+ */
+const InputTextArea = forwardRef<HTMLTextAreaElement, InputTextAreaProps>(
+  (
+    {
+      priority = "primary",
+      size = "medium",
+      state: stateProp = "default",
+      block = false,
+      width,
+      inlineLabel,
+      inputClassName,
+      boxClassName: boxClassNameProp,
+      disabled,
+      id,
+      className,
+      register,
+      "data-simulated-state": simulatedState,
+      height,
+      length,
+      maxLength,
+      value,
+      defaultValue,
+      name,
+      onChange,
+      onFocus,
+      onBlur,
+      ...restProps
+    },
+    ref,
+  ) => {
+    const isReadOnly = restProps.readOnly === true;
+    // table priority는 width 지정이 없으면 셀 가로폭을 기본으로 채운다.
+    const isTablePriority = priority === "table";
+    const resolvedBlock = block || (isTablePriority && width === undefined);
+    // tertiary는 디자인 계약상 small 단일 사이즈만 사용한다.
+    const resolvedSize = priority === "tertiary" ? "small" : size;
+    const generatedId = useId();
+    const registerRef = register?.ref;
+    const registerOnChange = register?.onChange;
+    const registerOnBlur = register?.onBlur;
+    const registerName = register?.name;
+    const [isFocused, setIsFocused] = useState(false);
+    const [currentLength, setCurrentLength] = useState(() => {
+      const initial = value ?? defaultValue;
+      return initial !== undefined && initial !== null
+        ? String(initial).length
+        : 0;
+    });
+
+    useEffect(() => {
+      if (disabled || stateProp === "disabled" || isReadOnly) {
+        setIsFocused(false);
+      }
+    }, [disabled, isReadOnly, stateProp]);
+
+    useEffect(() => {
+      if (value !== undefined && value !== null) {
+        setCurrentLength(String(value).length);
+      }
+    }, [value]);
+
+    const currentState = disabled ? "disabled" : stateProp;
+    const isDisabled =
+      currentState === "disabled" || currentState === "loading";
+    // tertiary는 status feedback(success/error/active/focused) 컬러를 적용하지 않는다.
+    const visualState =
+      priority === "tertiary"
+        ? isDisabled
+          ? "disabled"
+          : "default"
+        : !isDisabled && isFocused
+          ? "active"
+          : currentState;
+
+    const setTextAreaRef = useCallback(
+      (node: HTMLTextAreaElement | null) => {
+        if (typeof ref === "function") {
+          ref(node);
+        } else if (ref) {
+          ref.current = node;
+        }
+        registerRef?.(node);
+      },
+      [ref, registerRef],
+    );
+
+    const handleFocus = (event: FocusEvent<HTMLTextAreaElement>) => {
+      if (!isReadOnly) {
+        setIsFocused(true);
+      }
+      onFocus?.(event);
+    };
+
+    const handleBlur = (event: FocusEvent<HTMLTextAreaElement>) => {
+      setIsFocused(false);
+      registerOnBlur?.(event);
+      onBlur?.(event);
+    };
+
+    const handleChange = (event: ChangeEvent<HTMLTextAreaElement>) => {
+      setCurrentLength(event.currentTarget.value.length);
+      registerOnChange?.(event);
+      onChange?.(event);
+    };
+
+    const textAreaName = registerName ?? name;
+    const widthAttr =
+      width !== undefined
+        ? getFormFieldWidthAttr(width)
+        : resolvedBlock
+          ? "full"
+          : undefined;
+    const widthValue =
+      width !== undefined ? getFormFieldWidthValue(width) : undefined;
+    // height는 runtime 값이므로 CSS variable을 인라인 주입한다.
+    const resolvedHeight = useMemo(() => {
+      if (typeof height === "number") {
+        return `${height}px`;
+      }
+      if (typeof height === "string" && height.length > 0) {
+        return height;
+      }
+      return "128px";
+    }, [height]);
+    const containerStyle = {
+      ...(widthValue !== undefined
+        ? ({ ["--input-width" as const]: widthValue } as CSSProperties)
+        : {}),
+      ["--input-textarea-height" as const]: resolvedHeight,
+    } as CSSProperties;
+    const showLength = typeof length === "number";
+    const resolvedMaxLength = maxLength ?? length;
+
+    return (
+      <div
+        className={clsx(
+          "input",
+          "input-type-textarea",
+          `input-priority-${priority}`,
+          `input-size-${resolvedSize}`,
+          `input-state-${visualState}`,
+          resolvedBlock && "input-block",
+          className,
+        )}
+        data-input-type="textarea"
+        data-priority={priority}
+        data-size={resolvedSize}
+        data-state={visualState}
+        data-readonly={isReadOnly ? "true" : undefined}
+        data-block={resolvedBlock ? "true" : undefined}
+        {...(simulatedState ? { "data-simulated-state": simulatedState } : {})}
+        data-width={widthAttr}
+        style={containerStyle}
+      >
+        <div
+          className={clsx(
+            "input-box",
+            `input-box-priority-${priority}`,
+            `input-box-size-${resolvedSize}`,
+            `input-box-state-${visualState}`,
+            resolvedBlock && "input-box-block",
+            boxClassNameProp,
+          )}
+          data-slot="box"
+        >
+          <div
+            className="input-field"
+            data-state={visualState}
+            data-priority={priority}
+            data-size={resolvedSize}
+            data-readonly={isReadOnly ? "true" : undefined}
+            data-block={resolvedBlock ? "true" : undefined}
+          >
+            <div className="input-field-control">
+              {priority === "tertiary" && inlineLabel ? (
+                // tertiary 라벨은 FormField header가 아니라 input border 내부에 노출한다.
+                <span className="input-inline-label">{inlineLabel}</span>
+              ) : null}
+              <textarea
+                {...restProps}
+                id={id ?? generatedId}
+                ref={setTextAreaRef}
+                className={clsx(
+                  "input-element",
+                  "input-textarea-element",
+                  inputClassName,
+                )}
+                disabled={isDisabled}
+                aria-invalid={currentState === "error" ? true : undefined}
+                name={textAreaName}
+                maxLength={resolvedMaxLength}
+                value={value}
+                defaultValue={defaultValue}
+                onChange={handleChange}
+                onFocus={handleFocus}
+                onBlur={handleBlur}
+              />
+            </div>
+            {showLength ? (
+              // length prop이 있을 때만 카운터를 노출한다.
+              <p className="input-textarea-length">{`${currentLength} / ${length}자`}</p>
+            ) : null}
+          </div>
+        </div>
+      </div>
+    );
+  },
+);
+
+InputTextArea.displayName = "TextArea";
+
+export default InputTextArea;

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

@@ -1,4 +1,5 @@
 import InputBase from "./Input";
+import InputTextArea from "./TextArea";
 import InputBaseSideSlot from "./SideSlot";
 import InputBaseUtil from "./Utility";
 import InputBaseUtilityButton from "./Button";
@@ -6,6 +7,7 @@ import { InputStatusIcon } from "./StatusIcon";
 
 export const InputFoundation = {
   Base: InputBase,
+  TextArea: InputTextArea,
   Util: InputBaseUtil,
   SideSlot: InputBaseSideSlot,
   Icon: InputStatusIcon,

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

@@ -277,6 +277,51 @@
   min-width: 0;
 }
 
+.input[data-input-type="textarea"] .input-field {
+  // TextArea는 size별로 radius/spacing을 분기해 input과 동일한 스케일 감각을 유지한다.
+  --input-textarea-radius: var(--input-textarea-radius-medium);
+  --input-textarea-padding-inline: var(--input-textarea-padding-inline-medium);
+  --input-textarea-padding-block: var(--input-textarea-padding-block-medium);
+  --input-textarea-gap: var(--input-textarea-gap-medium);
+  align-items: stretch;
+  flex-direction: column;
+  gap: var(--input-textarea-gap);
+  border-radius: var(--input-textarea-radius);
+  padding: var(--input-textarea-padding-block)
+    var(--input-textarea-padding-inline);
+
+  &[data-size="small"] {
+    --input-textarea-radius: var(--input-textarea-radius-small);
+    --input-textarea-padding-inline: var(--input-textarea-padding-inline-small);
+    --input-textarea-padding-block: var(--input-textarea-padding-block-small);
+    --input-textarea-gap: var(--input-textarea-gap-small);
+  }
+
+  &[data-size="large"] {
+    --input-textarea-radius: var(--input-textarea-radius-large);
+    --input-textarea-padding-inline: var(--input-textarea-padding-inline-large);
+    --input-textarea-padding-block: var(--input-textarea-padding-block-large);
+    --input-textarea-gap: var(--input-textarea-gap-large);
+  }
+}
+
+.input-textarea-element {
+  min-height: var(--input-textarea-min-height);
+  height: var(--input-textarea-height);
+  resize: none;
+  margin: 0;
+}
+
+.input-textarea-length {
+  margin: 0;
+  align-self: flex-end;
+  color: var(--input-placeholder-color);
+  font-size: var(--input-textarea-counter-font-size);
+  line-height: var(--input-textarea-counter-line-height);
+  font-weight: var(--input-textarea-counter-font-weight);
+  letter-spacing: var(--input-textarea-counter-letter-spacing);
+}
+
 .input-field-utilities {
   display: flex;
   align-items: center;
@@ -421,13 +466,18 @@
   .input-helper-text {
     color: var(--input-label-error-color);
   }
+
+  .input-textarea-length {
+    color: var(--input-label-error-color);
+  }
 }
 
 .input[data-state="disabled"] {
   .input-label,
   .input-inline-label,
   .input-helper-text,
-  .input-affix {
+  .input-affix,
+  .input-textarea-length {
     color: var(--input-helper-disabled-color);
   }
 

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

@@ -21,6 +21,27 @@
   --input-tertiary-radius-base: var(--theme-radius-large-2);
   --input-table-radius-base: 0;
   --input-tertiary-element-min-height: var(--theme-size-medium-2);
+  --input-textarea-min-height: calc(var(--input-default-height-medium) * 2);
+  --input-textarea-height: 128px;
+  /* TextArea size token은 Input 기본 size token을 재할당해 축을 일치시킨다. */
+  --input-textarea-radius-small: var(--input-default-radius-base);
+  --input-textarea-radius-medium: var(--input-default-radius-base);
+  --input-textarea-radius-large: var(--input-default-radius-base);
+  --input-textarea-padding-inline-small: var(--spacing-padding-6);
+  --input-textarea-padding-inline-medium: var(--spacing-padding-6);
+  --input-textarea-padding-inline-large: var(--spacing-padding-6);
+  --input-textarea-padding-block-small: var(--spacing-padding-5);
+  --input-textarea-padding-block-medium: var(--spacing-padding-5);
+  --input-textarea-padding-block-large: var(--spacing-padding-6);
+  --input-textarea-gap-small: var(--input-default-gap);
+  --input-textarea-gap-medium: var(--input-default-gap);
+  --input-textarea-gap-large: var(--input-default-gap);
+  --input-textarea-counter-font-size: var(--font-label-medium-size);
+  --input-textarea-counter-line-height: var(--font-label-medium-line-height);
+  --input-textarea-counter-font-weight: var(--font-label-medium-weight);
+  --input-textarea-counter-letter-spacing: var(
+    --font-label-medium-letter-spacing
+  );
   --input-table-text-small-size: var(--font-body-xxsmall-size);
   --input-table-text-small-line-height: var(--font-body-xxsmall-line-height);
   --input-table-text-small-weight: var(--font-body-xxsmall-weight);

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

@@ -1,4 +1,5 @@
 export type * from "./foundation";
+export type * from "./textarea";
 export type * from "./text";
 export type * from "./date";
 export type * from "./verification";

package/src/components/input/types/textarea.ts

@@ -0,0 +1,73 @@
+import type { ComponentPropsWithoutRef, ReactNode } from "react";
+import type { UseFormRegisterReturn } from "react-hook-form";
+import type { FormFieldWidth } from "../../form/types/props";
+import type { InputPriority, InputSize, InputState } from "./foundation";
+
+type NativeTextAreaProps = ComponentPropsWithoutRef<"textarea">;
+
+/**
+ * Input TextArea; textarea base props
+ * @property {NativeTextAreaProps} ... <textarea /> native attrs
+ * @property {InputPriority} [priority] 스타일 카테고리 타입
+ * @property {InputSize} [size] 스타일 사이즈 타입
+ * @property {InputState} [state] input 상태
+ * @property {boolean} [block] width: 100% 여부
+ * @property {ReactNode} [inlineLabel] tertiary 내부 라벨
+ * @property {string} [inputClassName] 실제 `<textarea>` className
+ * @property {string} [boxClassName] `.input-box` className
+ * @property {UseFormRegisterReturn} [register] react-hook-form register 반환값
+ * @property {FormFieldWidth} [width] width preset 옵션
+ * @property {InputState} [data-simulated-state] Storybook 시각 상태 강제용
+ * @property {number | string} [height] textarea 높이(px 또는 CSS length)
+ * @property {number} [length] 카운터 최대 글자수(지정 시 우측 하단 카운터 노출)
+ */
+export interface InputTextAreaProps extends Omit<NativeTextAreaProps, "size"> {
+  /**
+   * semantic color/token 세트
+   */
+  priority?: InputPriority;
+  /**
+   * 높이/타이포 세트
+   */
+  size?: InputSize;
+  /**
+   * 시각 상태. disabled prop과 조합된다
+   */
+  state?: InputState;
+  /**
+   * true면 width:100%
+   */
+  block?: boolean;
+  /**
+   * tertiary priority에서 border 내부 상단에 배치할 라벨 텍스트/노드
+   */
+  inlineLabel?: ReactNode;
+  /**
+   * 실제 `<textarea>` className
+   */
+  inputClassName?: string;
+  /**
+   * `.input-box` className
+   */
+  boxClassName?: string;
+  /**
+   * react-hook-form register 반환값
+   */
+  register?: UseFormRegisterReturn;
+  /**
+   * width preset 옵션
+   */
+  width?: FormFieldWidth;
+  /**
+   * Storybook 등에서 강제 상태 표현용
+   */
+  "data-simulated-state"?: InputState;
+  /**
+   * textarea 높이(px 또는 CSS length)
+   */
+  height?: number | string;
+  /**
+   * 카운터 최대 글자수(지정 시 우측 하단 카운터 노출)
+   */
+  length?: number;
+}

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

@@ -21,12 +21,30 @@ export default function SlotText<C extends ElementType = "span">({
     return children;
   }
 
+  // 변경: rest spread로 유입될 수 있는 className 충돌을 제거해 slot-text 클래스가 항상 유지되도록 한다.
+  const restPropsRecord = restProps as Record<string, unknown>;
+  const restClassName =
+    typeof restPropsRecord.className === "string"
+      ? restPropsRecord.className
+      : undefined;
+  const mergedClassName = clsx("slot-text", restClassName, className);
+  const normalizedRestProps = { ...restPropsRecord };
+  delete normalizedRestProps.className;
+
+  const hasCustomTitle =
+    "title" in normalizedRestProps &&
+    typeof normalizedRestProps.title !== "undefined";
+
+  // 변경: 텍스트 children은 기본 title을 자동 주입해 native tooltip 경로를 보장한다.
+  const nativeTitleProps = hasCustomTitle ? {} : { title: String(children) };
+
   // 문자열/숫자 children만 공통 slot text 마크업으로 감싼다.
   return (
     <SlotBase
       as={as as ElementType}
-      className={clsx("slot-text", className)}
-      {...restProps}
+      className={mergedClassName}
+      {...nativeTitleProps}
+      {...normalizedRestProps}
     >
       {children}
     </SlotBase>