@uniai-fe/uds-primitives 0.3.20 → 0.3.22

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);
@@ -2730,6 +2751,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 +2913,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.20",
+  "version": "0.3.22",
   "description": "UNIAI Design System; Primitives Components Package",
   "type": "module",
   "private": false,

package/src/components/dropdown/markup/Template.tsx

@@ -31,9 +31,7 @@ const normalizeSelectedIdsByMode = (
  * @param {DropdownTemplateProps} props Dropdown template props
  * @param {ReactNode} props.trigger trigger 요소
  * @param {DropdownTemplateItem[]} props.items 렌더링할 menu item 리스트
- * @param {string[]} [props.selectedIds] 선택된 item id 배열
  * @param {(payload: DropdownTemplateChangePayload) => void} [props.onChange] 선택 결과 변경 콜백
- * @param {(item: DropdownTemplateItem) => void} [props.onSelect] item 선택 콜백
  * @param {"small" | "medium" | "large"} [props.size="medium"] menu size scale
  * @param {"match" | "fit-content" | "max-content" | string | number} [props.width="match"] panel width 옵션
  * @param {DropdownMenuProps} [props.rootProps] Dropdown.Root 전달 props
@@ -44,9 +42,7 @@ const normalizeSelectedIdsByMode = (
 const DropdownTemplate = ({
   trigger,
   items,
-  selectedIds,
   onChange,
-  onSelect,
   size = "medium",
   width = "match",
   rootProps,
@@ -55,15 +51,7 @@ const DropdownTemplate = ({
   alt,
 }: DropdownTemplateProps) => {
   /**
-   * 1) 선택 상태 모드 결정
-   * - selectedIds prop이 들어오면 외부가 상태를 소유하는 controlled 모드다.
-   * - selectedIds prop이 없으면 Template 내부 state가 상태를 소유하는 uncontrolled 모드다.
-   * - 이 분기 기준은 렌더마다 동일해야 하므로 가장 먼저 계산한다.
-   */
-  const isSelectionControlled = selectedIds !== undefined;
-
-  /**
-   * 2) 선택 정책(single/multiple) 결정
+   * 1) 선택 정책(single/multiple) 결정
    * - item 중 하나라도 multiple=true이면 multiple 정책으로 해석한다.
    * - multiple 정책에서는 item id 배열 전체를 유지한다.
    * - single 정책에서는 언제나 최대 1개 id만 유지한다.
@@ -71,7 +59,7 @@ const DropdownTemplate = ({
   const isMultiple = items.some(item => item.multiple);
 
   /**
-   * 3) uncontrolled 초기 선택값 계산
+   * 2) 초기 선택값 계산
    * - source of truth: items[].selected
    * - multiple: selected=true인 모든 id를 초기값으로 사용한다.
    * - single: selected=true가 여러 개여도 첫 번째 id 하나만 사용한다.
@@ -86,9 +74,8 @@ const DropdownTemplate = ({
   }, [isMultiple, items]);
 
   /**
-   * 4) uncontrolled 내부 state 선언
-   * - controlled 모드에서는 이 state가 실제 화면 결정에 사용되지 않는다.
-   * - uncontrolled 모드에서는 이 state가 선택 결과의 단일 source가 된다.
+   * 3) 내부 선택 state 선언
+   * - Template은 items[].selected를 초기값으로 받아 내부 상태를 관리한다.
    * - 초기값은 selectedIdsFromItems를 그대로 사용한다.
    */
   const [uncontrolledSelectedIds, setUncontrolledSelectedIds] = useState<
@@ -96,19 +83,14 @@ const DropdownTemplate = ({
   >(() => selectedIdsFromItems);
 
   /**
-   * 5) options(items) 변경 동기화
-   * - controlled 모드에서는 외부 selectedIds를 신뢰해야 하므로 내부 state를 건드리지 않는다.
-   * - uncontrolled 모드에서는 내부 state를 items 변경에 맞춰 정합성 보정한다.
+   * 4) options(items) 변경 동기화
+   * - 내부 state를 items 변경에 맞춰 정합성 보정한다.
    *   1) 기존 선택 id 중 현재 items에 존재하는 id만 필터링한다.
    *   2) 유효 id가 남아 있으면 그대로 유지한다(single은 1개만 유지).
    *   3) 유효 id가 없으면 selectedIdsFromItems(초기 선택 규칙)로 재초기화한다.
    * - 이 effect는 외부 데이터 재조회/필터 변경 시 stale id를 자동 정리하는 역할을 한다.
    */
   useEffect(() => {
-    if (isSelectionControlled) {
-      return;
-    }
-
     setUncontrolledSelectedIds(previousSelectedIds => {
       const itemIdSet = new Set(items.map(item => item.id));
       const filteredIds = previousSelectedIds.filter(selectedId =>
@@ -128,38 +110,36 @@ const DropdownTemplate = ({
 
       return nextSelectedIds;
     });
-  }, [isMultiple, isSelectionControlled, items, selectedIdsFromItems]);
+  }, [isMultiple, items, selectedIdsFromItems]);
 
   /**
-   * 6) 최종 선택 id 계산
-   * - controlled: selectedIds prop을 그대로 사용한다(single은 첫 id만 허용).
-   * - uncontrolled: 내부 state(uncontrolledSelectedIds)를 그대로 사용한다.
+   * 5) 최종 선택 id 계산
+   * - 내부 state(uncontrolledSelectedIds)를 single/multiple 정책으로 정규화한다.
    * - 렌더/이벤트/selected 스타일 계산은 이 값만 참조한다.
    */
   const resolvedSelectedIds = normalizeSelectedIdsByMode(
-    isSelectionControlled ? (selectedIds ?? []) : uncontrolledSelectedIds,
+    uncontrolledSelectedIds,
     isMultiple,
   );
 
   /**
-   * 7) empty panel 분기
+   * 6) empty panel 분기
    * - item이 비어 있으면 alt 또는 기본 문구를 disabled item으로 렌더링한다.
    * - 별도 li를 만들지 않고 MenuItem을 재사용해 구조를 통일한다.
    */
   const hasItems = items.length > 0;
 
   /**
-   * 8) item 선택 처리
+   * 7) item 선택 처리
    * - 클릭된 item(id) 기준으로 다음 선택 배열을 계산한다.
    * - multiple: 토글(add/remove)
    * - single: 클릭한 id 하나로 교체
-   * - uncontrolled 모드면 내부 state를 즉시 반영한다.
+   * - 내부 state를 즉시 반영한다.
    * - onChange(payload)로 "현재 결과 전체"를 전달한다.
-   * - onSelect(item)은 하위호환을 위해 마지막에 유지 호출한다.
    */
   const handleItemSelect = (itemId: string) => {
     /**
-     * 8-1) 클릭된 item 조회
+     * 7-1) 클릭된 item 조회
      * - items 목록에 없는 id면 안전하게 종료한다.
      * - 외부 데이터 race 조건에서 방어적으로 동작하기 위한 가드다.
      */
@@ -170,7 +150,7 @@ const DropdownTemplate = ({
     }
 
     /**
-     * 8-2) 다음 selectedIds 계산
+     * 7-2) 다음 selectedIds 계산
      * - wasSelected: 토글 기준 값
      * - nextSelectedIds: 모드 정책을 적용한 다음 상태
      * - nextSelectedItems: payload 전달용 상세 데이터
@@ -186,16 +166,13 @@ const DropdownTemplate = ({
     );
 
     /**
-     * 8-3) 내부 state 업데이트(uncontrolled 전용)
-     * - controlled 모드에서는 외부 selectedIds prop이 곧 source of truth이므로
-     *   내부 state를 갱신하지 않는다.
+     * 7-3) 내부 state 업데이트
+     * - Template 내부 선택 상태를 즉시 반영한다.
      */
-    if (!isSelectionControlled) {
-      setUncontrolledSelectedIds(nextSelectedIds);
-    }
+    setUncontrolledSelectedIds(nextSelectedIds);
 
     /**
-     * 8-4) 신규 계약 이벤트(onChange)
+     * 7-4) 선택 결과 이벤트(onChange)
      * - 서비스/상위 컴포넌트가 선택 결과 전체를 즉시 사용할 수 있게
      *   현재 item + 선택 결과 배열을 함께 제공한다.
      */
@@ -206,17 +183,10 @@ const DropdownTemplate = ({
       selectedItems: nextSelectedItems,
       multiple: isMultiple,
     });
-
-    /**
-     * 8-5) legacy 계약 이벤트(onSelect)
-     * - 하위호환 경로를 유지하기 위해 onChange 이후 동일 선택을 전달한다.
-     * - 추후 마이그레이션 완료 시 제거 대상이다.
-     */
-    onSelect?.(currentItem);
   };
 
   /**
-   * 9) 렌더 구성
+   * 8) 렌더 구성
    * - Root → Trigger → Container → MenuList depth를 유지한다.
    * - 각 item은 resolvedSelectedIds 기준으로 selected 스타일을 결정한다.
    * - disabled item은 select 이벤트를 차단하고 상태만 노출한다.

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

@@ -167,9 +167,7 @@ export interface DropdownTemplateChangePayload {
  * Dropdown template props
  * @property {ReactNode} trigger trigger 요소
  * @property {DropdownTemplateItem[]} items 렌더링할 menu item 리스트
- * @property {string[]} [selectedIds] 선택된 item id 배열
  * @property {(payload: DropdownTemplateChangePayload) => void} [onChange] 선택 결과 변경 콜백
- * @property {(item: DropdownTemplateItem) => void} [onSelect] item 선택 콜백
  * @property {DropdownSize} [size="medium"] surface height scale
  * @property {DropdownPanelWidth} [width="match"] panel width 옵션
  * @property {DropdownMenuProps} [rootProps] Root 에 전달할 props
@@ -180,20 +178,10 @@ export interface DropdownTemplateChangePayload {
 export interface DropdownTemplateProps {
   trigger: ReactNode;
   items: DropdownTemplateItem[];
-  /**
-   * 선택된 item id 배열
-   * @deprecated onChange + items[].selected 기반 계약을 우선 사용한다.
-   */
-  selectedIds?: string[];
   /**
    * 선택 결과 변경 콜백
    */
   onChange?: (payload: DropdownTemplateChangePayload) => void;
-  /**
-   * item 선택 콜백
-   * @deprecated onChange로 대체되며 하위호환을 위해 유지된다.
-   */
-  onSelect?: (item: DropdownTemplateItem) => void;
   size?: DropdownSize;
   width?: DropdownPanelWidth;
   /**

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/select/markup/Default.tsx

@@ -41,7 +41,6 @@ const SELECT_CUSTOM_OPTION_VALUE = "CUSTOM";
  * @param {"default" | "focused" | "error" | "disabled"} [props.state="default"] trigger state
  * @param {boolean} [props.block] block 레이아웃 여부
  * @param {FormFieldWidth} [props.width] container width
- * @param {boolean} [props.isOpen] legacy open alias
  * @param {boolean} [props.disabled] disabled 여부
  * @param {boolean} [props.readOnly] readOnly 여부
  * @param {"button" | "submit" | "reset"} [props.buttonType] trigger button type
@@ -74,7 +73,6 @@ const SelectDefault = forwardRef<HTMLElement, SelectDefaultComponentProps>(
       state = "default",
       block,
       width,
-      isOpen,
       disabled,
       readOnly,
       buttonType,
@@ -182,7 +180,7 @@ const SelectDefault = forwardRef<HTMLElement, SelectDefaultComponentProps>(
 
     // 12) open 제어형/비제어형 계약은 공용 hook으로 통합 처리한다.
     const { open: dropdownOpen, setOpen } = useSelectDropdownOpenState({
-      open: open ?? isOpen,
+      open,
       defaultOpen,
       onOpen,
     });

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

@@ -33,7 +33,6 @@ const SELECT_MULTIPLE_ALL_OPTION_BASE_ID = "__select_multiple_all__";
  * @param {"default" | "focused" | "disabled"} [props.state="default"] 시각 상태
  * @param {boolean} [props.block] block 여부
  * @param {FormFieldWidth} [props.width] container width preset
- * @param {boolean} [props.isOpen] dropdown open 여부
  * @param {boolean} [props.disabled] disabled 여부
  * @param {boolean} [props.readOnly] readOnly 여부
  * @param {SelectDropdownExtension} [props.dropdown] dropdown 확장 옵션
@@ -57,7 +56,6 @@ const SelectMultipleTrigger = forwardRef<
       state = "default",
       block,
       width,
-      isOpen,
       disabled,
       readOnly,
       tags,
@@ -257,7 +255,7 @@ const SelectMultipleTrigger = forwardRef<
      * - open/defaultOpen/onOpen 계약을 hook으로 통합 처리한다.
      */
     const { open: dropdownOpen, setOpen } = useSelectDropdownOpenState({
-      open: open ?? isOpen,
+      open,
       defaultOpen,
       onOpen,
     });

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

@@ -73,13 +73,13 @@ export interface SelectValueOptions {
 
 /**
  * Select; 상태 옵션
- * @property {boolean} [isOpen] dropdown open 여부
+ * @property {boolean} [open] dropdown open 여부
  */
 export interface SelectComponentState {
   /**
    * dropdown open 여부
    */
-  isOpen?: boolean;
+  open?: boolean;
 }
 
 /**
@@ -295,7 +295,7 @@ export interface SelectCustomOptionExtension {
  * @property {ReactNode} [placeholder] placeholder 텍스트
  * @property {ReactNode[]} [tags] multi select 태그 리스트
  * @property {boolean} [multiple] multi select 여부
- * @property {boolean} [isOpen] dropdown open 여부
+ * @property {boolean} [open] dropdown open 여부
  * @property {FormFieldWidth} [width] width preset 옵션
  */
 export type SelectProps = SelectStyleOptions &
@@ -311,7 +311,7 @@ export type SelectProps = SelectStyleOptions &
  * @property {SelectSize} [size] size scale
  * @property {SelectState} [state] visual state
  * @property {boolean} [block] block 여부
- * @property {boolean} [isOpen] dropdown open 여부
+ * @property {boolean} [open] dropdown open 여부
  * @property {boolean} [disabled] disabled 여부
  * @property {boolean} [readOnly] readOnly 여부
  * @property {SelectTriggerButtonType} [buttonType] button type
@@ -362,7 +362,7 @@ export interface SelectMultipleAllOptionProps {
  * @property {SelectSize} [size] size scale
  * @property {SelectState} [state] visual state
  * @property {boolean} [block] block 여부
- * @property {boolean} [isOpen] dropdown open 여부
+ * @property {boolean} [open] dropdown open 여부
  * @property {boolean} [disabled] disabled 여부
  * @property {boolean} [readOnly] readOnly 여부
  * @property {FormFieldWidth} [width] width preset 옵션

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

@@ -129,7 +129,7 @@ export interface SelectTriggerDefaultProps extends HTMLAttributes<HTMLElement> {
   /**
    * dropdown open 여부
    */
-  isOpen?: boolean;
+  open?: boolean;
   /**
    * disabled 여부
    */
@@ -190,7 +190,7 @@ export interface SelectTriggerMultipleProps extends HTMLAttributes<HTMLElement>
   /**
    * dropdown open 여부
    */
-  isOpen?: boolean;
+  open?: boolean;
   /**
    * disabled 여부
    */