@uniai-fe/uds-primitives 0.0.11 → 0.0.12

package/README.md

@@ -194,4 +194,6 @@ src/components/{category}/
 - `CONTEXT.md` 및 `CONTEXT-*.md`: 각 컴포넌트의 상태/진행/디자인 근거
 - `RADIX-SIZE-GUIDE.md`: primitives 사이즈 체계와 Radix 매핑 규칙
 
+* **컨벤션**: 모든 컴포넌트/스토리/문서는 slot/prefix/suffix 용어를 사용하지 않고, 레이아웃 기준(`header/body/footer`, 2단 구조는 `upper/lower`)과 `util*` 키워드를 사용한다. 인터랙션 함수는 `on*` 접두사를 사용하고, JSDoc `@param`은 depth 전체를 풀어 쓴다.
+
 필요한 컨텍스트를 확인한 뒤 컴포넌트를 import해 사용하면 됩니다.

package/dist/styles.css

@@ -2501,7 +2501,7 @@ figure.chip {
 .input-field[data-size=large] {
   min-height: var(--theme-input-height-large);
 }
-.input-field[data-appearance=secondary] {
+.input-field[data-priority=secondary] {
   border: none;
   border-bottom: var(--theme-input-border-width-default) solid var(--theme-input-border-color);
   border-radius: 0;
@@ -2509,7 +2509,7 @@ figure.chip {
   padding-block: var(--spacing-padding-4);
   background-color: transparent;
 }
-.input-field[data-appearance=tertiary] {
+.input-field[data-priority=tertiary] {
   border-radius: var(--theme-input-radius-tertiary);
   background-color: var(--theme-input-surface);
   min-height: var(--theme-input-height-tertiary);
@@ -2517,30 +2517,30 @@ figure.chip {
   row-gap: var(--spacing-gap-1);
   column-gap: var(--theme-input-gap);
 }
-.input-field[data-appearance=tertiary] .input-inline-label {
+.input-field[data-priority=tertiary] .input-inline-label {
   flex-basis: 100%;
 }
-.input-field[data-appearance=tertiary] .input-element {
+.input-field[data-priority=tertiary] .input-element {
   min-height: var(--theme-size-medium-2);
   width: auto;
   flex: 1 1 auto;
 }
-.input-field[data-appearance=tertiary] .input-element + .input-affix {
+.input-field[data-priority=tertiary] .input-element + .input-affix {
   margin-left: auto;
 }
-.input-field:not([data-appearance=secondary])[data-state=active], .input-field:not([data-appearance=secondary])[data-state=focused] {
+.input-field:not([data-priority=secondary])[data-state=active], .input-field:not([data-priority=secondary])[data-state=focused] {
   border-color: var(--theme-input-border-active);
   border-width: var(--theme-input-border-width-emphasis);
 }
-.input-field:not([data-appearance=secondary])[data-state=success] {
+.input-field:not([data-priority=secondary])[data-state=success] {
   border-color: var(--theme-input-border-success);
   border-width: var(--theme-input-border-width-emphasis);
 }
-.input-field:not([data-appearance=secondary])[data-state=error] {
+.input-field:not([data-priority=secondary])[data-state=error] {
   border-color: var(--theme-input-border-error);
   border-width: var(--theme-input-border-width-emphasis);
 }
-.input-field:not([data-appearance=secondary])[data-state=disabled] {
+.input-field:not([data-priority=secondary])[data-state=disabled] {
   border-color: var(--theme-input-border-disabled);
   border-width: var(--theme-input-border-width-default);
   background-color: var(--theme-input-surface-disabled);
@@ -2580,11 +2580,11 @@ figure.chip {
   color: var(--theme-input-label-color);
 }
 
-.input-field[data-appearance=secondary] .input-element {
+.input-field[data-priority=secondary] .input-element {
   padding-inline: 0;
 }
 
-.input-field[data-appearance=tertiary] .input-element {
+.input-field[data-priority=tertiary] .input-element {
   min-height: var(--theme-size-medium-2);
 }
 
@@ -2607,14 +2607,14 @@ figure.chip {
   min-width: 20px;
   color: var(--theme-input-helper-color);
 }
-.input-affix--prefix {
+.input-affix--left {
   order: -1;
   margin-right: var(--spacing-gap-3);
 }
-.input-affix--suffix, .input-affix--reset, .input-affix--status {
+.input-affix--right, .input-affix--clear, .input-affix--status {
   margin-left: var(--spacing-gap-3);
 }
-.input-affix--reset, .input-affix--status {
+.input-affix--clear, .input-affix--status {
   color: var(--theme-input-text-color);
 }
 .input-affix--status[data-state=error] {
@@ -2624,22 +2624,22 @@ figure.chip {
   color: var(--color-primary-default);
 }
 
-.input-field[data-appearance=secondary] {
+.input-field[data-priority=secondary] {
   border-bottom-width: var(--theme-input-border-width-default);
 }
-.input-field[data-appearance=secondary][data-state=active], .input-field[data-appearance=secondary][data-state=focused] {
+.input-field[data-priority=secondary][data-state=active], .input-field[data-priority=secondary][data-state=focused] {
   border-bottom-color: var(--theme-input-border-active);
   border-bottom-width: var(--theme-input-border-width-emphasis);
 }
-.input-field[data-appearance=secondary][data-state=success] {
+.input-field[data-priority=secondary][data-state=success] {
   border-bottom-color: var(--theme-input-border-success);
   border-bottom-width: var(--theme-input-border-width-emphasis);
 }
-.input-field[data-appearance=secondary][data-state=error] {
+.input-field[data-priority=secondary][data-state=error] {
   border-bottom-color: var(--theme-input-border-error);
   border-bottom-width: var(--theme-input-border-width-emphasis);
 }
-.input-field[data-appearance=secondary][data-state=disabled] {
+.input-field[data-priority=secondary][data-state=disabled] {
   border-bottom-color: var(--theme-input-border-underline-disabled);
   border-bottom-width: var(--theme-input-border-width-default);
 }
@@ -2671,7 +2671,7 @@ figure.chip {
   border-color: var(--theme-input-border-color);
   background-color: var(--theme-input-surface-disabled);
 }
-.input[data-state=disabled] .input-field[data-appearance=secondary] {
+.input[data-state=disabled] .input-field[data-priority=secondary] {
   background-color: transparent;
 }
 

package/package.json

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

package/src/components/input/markup/text/Base.tsx

@@ -1,4 +1,5 @@
 import clsx from "clsx";
+import type { ForwardedRef } from "react";
 import {
   ChangeEvent,
   FocusEvent,
@@ -7,6 +8,7 @@ import {
   useEffect,
   useId,
   useMemo,
+  useRef,
   useState,
 } from "react";
 import type { InputProps } from "../../types";
@@ -18,95 +20,103 @@ import {
   composeInputClassName,
 } from "../../utils";
 import ErrorIcon from "../../img/error.svg";
-import SuccessIcon from "../../img/success.svg";
 import ResetIcon from "../../img/reset.svg";
+import SuccessIcon from "../../img/success.svg";
+
+const setForwardedRef = <T,>(ref: ForwardedRef<T>, value: T | null): void => {
+  if (!ref) {
+    return;
+  }
+  if (typeof ref === "function") {
+    ref(value);
+    return;
+  }
+  ref.current = value;
+};
 
 /**
- * Native `<input>` 기반 텍스트 필드. appearance/size/state 축, prefix/suffix/reset/status 슬롯,
- * label/helperText 같은 피드백 슬롯을 모두 제공한다.
+ * Native `<input>` 기반 텍스트 필드.
+ * priority/size/state 축과 left/right/clear/status 슬롯, label/helper 피드백 슬롯을 모두 제공하며
+ * react-hook-form `register` 결과를 그대로 전달받아 내부 ref/onChange/onBlur에 병합한다.
+ *
  * @component
- * @param {InputProps} props
- * @param {"primary" | "secondary" | "tertiary"} [props.appearance="primary"] 토큰 세트.
- * @param {"small" | "medium" | "large"} [props.size="medium"] 높이/spacing 세트.
- * @param {"default" | "active" | "focused" | "success" | "error" | "disabled"} [props.state="default"] 시각 상태.
- * @param {boolean} [props.block=false] true면 width 100%.
- * @param {React.ReactNode} [props.prefix] 입력 왼쪽 추가 슬롯.
- * @param {React.ReactNode} [props.suffix] 입력 오른쪽 추가 슬롯.
- * @param {React.ReactElement} [props.resetSlot] 값 초기화 버튼 슬롯. 미지정 시 기본 reset 아이콘.
- * @param {React.ReactNode} [props.successIcon] success 상태에서 사용할 아이콘.
- * @param {React.ReactNode} [props.errorIcon] error 상태에서 사용할 아이콘.
- * @param {React.ReactNode} [props.label] 상단/inset label 콘텐츠.
- * @param {React.ReactNode} [props.helperText] helper 영역 텍스트.
- * @param {boolean} [props.hideHelperText] true면 helper 영역 숨김.
- * @param {string} [props.inputClassName] 실제 `<input>` 요소 className.
- * @param {string} [props.wrapperClassName] `.input-box` wrapper className.
- * @param {object} [props.labelProps] label attr 커스터마이즈.
- * @param {object} [props.helperTextProps] helper 영역 attr.
- * @param {boolean} [props.disabled] native disabled.
- * @param {string} [props.id] external id. label htmlFor 와 공유한다.
- * @param {string} [props.className] root `.input` className 합성용.
- * @param {"default" | "active" | "focused" | "success" | "error" | "disabled"} [props.data-simulated-state]
- *  Storybook 등에서 강제 상태 표현.
- * @param {string} [props.type="text"] native input type.
- * @param {string | number | readonly string[]} [props.defaultValue] 비제어 초기값.
- * @param {string | number | readonly string[]} [props.value] 제어형 값.
- * @param {(event: ChangeEvent<HTMLInputElement>) => void} [props.onChange] 입력 변경 핸들러.
- * @param {(event: FocusEvent<HTMLInputElement>) => void} [props.onFocus] focus 핸들러.
- * @param {(event: FocusEvent<HTMLInputElement>) => void} [props.onBlur] blur 핸들러.
+ * @param {InputProps} props Input 컴포넌트 공통 props
+ * @param {"primary" | "secondary" | "tertiary"} [props.priority="primary"] 디자인 토큰 우선순위
+ * @param {"small" | "medium" | "large"} [props.size="medium"] 높이/타이포 세트
+ * @param {"default" | "active" | "focused" | "success" | "error" | "disabled"} [props.state="default"] 시각 상태
+ * @param {boolean} [props.block=false] true면 width 100%
+ * @param {React.ReactNode} [props.left] 입력 왼쪽 슬롯(아이콘/텍스트)
+ * @param {React.ReactNode} [props.right] 입력 오른쪽 슬롯
+ * @param {React.ReactNode} [props.clearIcon] 입력값 초기화 아이콘. 지정하지 않으면 기본 Reset 아이콘
+ * @param {React.ReactNode} [props.successIcon] success 상태 아이콘 override
+ * @param {React.ReactNode} [props.errorIcon] error 상태 아이콘 override
+ * @param {React.ReactNode} [props.label] 상단 또는 inline label 콘텐츠
+ * @param {React.ReactNode} [props.helper] helper 텍스트 콘텐츠
+ * @param {boolean} [props.hideHelper] true면 helper 영역 숨김
+ * @param {string} [props.inputClassName] 실제 `<input>` 요소 className
+ * @param {string} [props.boxClassName] `.input-box` className
+ * @param {ComponentPropsWithoutRef<"label">} [props.labelProps] label 추가 속성
+ * @param {ComponentPropsWithoutRef<"div">} [props.helperProps] helper container 속성
+ * @param {boolean} [props.disabled] native disabled
+ * @param {string} [props.id] 외부 id. label htmlFor와 공유된다
+ * @param {string} [props.className] root `.input` className
+ * @param {UseFormRegisterReturn} [props.register] react-hook-form register 반환값
+ * @param {string} [props.name] native name. register 사용 시 자동으로 병합
+ * @param {InputProps["data-simulated-state"]} [props.data-simulated-state] Storybook 등에서 시각 상태 강제용
+ * @param {(event: ChangeEvent<HTMLInputElement>) => void} [props.onChange] change 핸들러
+ * @param {(event: FocusEvent<HTMLInputElement>) => void} [props.onFocus] focus 핸들러
+ * @param {(event: FocusEvent<HTMLInputElement>) => void} [props.onBlur] blur 핸들러
+ * @param {string | number | readonly string[]} [props.value] 제어형 값
+ * @param {string | number | readonly string[]} [props.defaultValue] 비제어 초기값
+ * @param {string} [props.type="text"] native input type
  */
 const Text = forwardRef<HTMLInputElement, InputProps>(
   (
     {
-      appearance = "primary",
+      priority = "primary",
       size = "medium",
       state: stateProp = "default",
       block = false,
-      prefix,
-      suffix,
-      resetSlot,
+      left,
+      right,
+      clearIcon,
       successIcon,
       errorIcon,
       label,
-      helperText,
-      hideHelperText,
+      helper,
+      hideHelper,
       inputClassName,
-      wrapperClassName,
-      helperTextProps,
+      boxClassName,
+      helperProps,
       labelProps,
       disabled,
       id,
       className,
+      register,
       "data-simulated-state": simulatedState,
-      type = "text",
-      defaultValue,
       value,
+      defaultValue,
+      name,
       onChange,
       onFocus,
       onBlur,
+      type = "text",
       ...restProps
     },
     forwardedRef,
   ) => {
     const generatedId = useId();
-    const [uncontrolledValue, setUncontrolledValue] = useState<
-      string | number | readonly string[] | undefined
-    >(defaultValue);
+    const registerRef = register?.ref;
+    const registerOnChange = register?.onChange;
+    const registerOnBlur = register?.onBlur;
+    const inputRef = useRef<HTMLInputElement | null>(null);
     const [isFocused, setIsFocused] = useState(false);
-    const resolvedState = useMemo(
-      () => (disabled ? "disabled" : stateProp),
-      [disabled, stateProp],
-    );
-    const fieldId = useMemo(
-      () => id ?? labelProps?.htmlFor ?? generatedId,
-      [generatedId, id, labelProps?.htmlFor],
-    );
-    const shouldShowHelper = Boolean(helperText) && !hideHelperText;
-    const helperElementId = useMemo(() => {
-      if (!shouldShowHelper) {
-        return undefined;
-      }
-      return helperTextProps?.id ?? `${fieldId}-helper-text`;
-    }, [fieldId, helperTextProps?.id, shouldShowHelper]);
+    const [hasValue, setHasValue] = useState(() => {
+      const initial = value ?? defaultValue;
+      return initial !== undefined && initial !== null
+        ? String(initial).length > 0
+        : false;
+    });
 
     useEffect(() => {
       if (stateProp === "disabled" || disabled) {
@@ -114,6 +124,16 @@ const Text = forwardRef<HTMLInputElement, InputProps>(
       }
     }, [disabled, stateProp]);
 
+    useEffect(() => {
+      if (value !== undefined && value !== null) {
+        setHasValue(String(value).length > 0);
+      }
+    }, [value]);
+
+    const resolvedState = useMemo(
+      () => (disabled ? "disabled" : stateProp),
+      [disabled, stateProp],
+    );
     const visualState = useMemo(() => {
       if (resolvedState === "disabled") {
         return "disabled";
@@ -124,6 +144,17 @@ const Text = forwardRef<HTMLInputElement, InputProps>(
       return isFocused ? "active" : resolvedState;
     }, [isFocused, resolvedState]);
 
+    const fieldId = useMemo(
+      () => id ?? labelProps?.htmlFor ?? generatedId,
+      [generatedId, id, labelProps?.htmlFor],
+    );
+    const helperElementId = useMemo(() => {
+      if (!helper || hideHelper) {
+        return undefined;
+      }
+      return helperProps?.id ?? `${fieldId}-helper-text`;
+    }, [fieldId, helperProps?.id, helper, hideHelper]);
+
     const defaultStatusIcon = useMemo(() => {
       if (resolvedState === "success") {
         return <SuccessIcon aria-hidden="true" />;
@@ -144,51 +175,46 @@ const Text = forwardRef<HTMLInputElement, InputProps>(
       return null;
     }, [defaultStatusIcon, errorIcon, resolvedState, successIcon]);
 
-    const defaultResetSlot = useMemo(() => {
+    const defaultClearIcon = useMemo(() => {
       if (visualState === "active") {
         return <ResetIcon aria-hidden="true" />;
       }
       return null;
     }, [visualState]);
 
-    const effectiveResetSlot = resetSlot ?? defaultResetSlot;
-    const currentValue = value ?? uncontrolledValue;
-    const hasInputValue =
-      currentValue !== undefined && currentValue !== null
-        ? String(currentValue).length > 0
-        : false;
-    const showResetSlot = Boolean(
-      effectiveResetSlot && hasInputValue && resolvedState !== "disabled",
+    const effectiveClearIcon = clearIcon ?? defaultClearIcon;
+    const showClearIcon = Boolean(
+      effectiveClearIcon && hasValue && resolvedState !== "disabled",
     );
     const isDisabled = resolvedState === "disabled";
     const labelFor = labelProps?.htmlFor ?? fieldId;
     const containerClassName = useMemo(
       () =>
         composeInputClassName({
-          appearance,
+          priority,
           size,
           state: visualState,
           block,
           className,
         }),
-      [appearance, block, className, size, visualState],
+      [priority, block, className, size, visualState],
     );
-    const boxClassName = useMemo(
+    const fieldBoxClassName = useMemo(
       () =>
         composeInputBoxClassName({
-          appearance,
+          priority,
           size,
           state: visualState,
           block,
-          className: wrapperClassName,
+          className: boxClassName,
         }),
-      [appearance, block, size, visualState, wrapperClassName],
+      [priority, block, size, visualState, boxClassName],
     );
     const helperClassName = useMemo(
-      () => clsx("input-helper-text", helperTextProps?.className),
-      [helperTextProps?.className],
+      () => clsx("input-helper-text", helperProps?.className),
+      [helperProps?.className],
     );
-    const shouldRenderInlineLabel = appearance === "tertiary" && Boolean(label);
+    const shouldRenderInlineLabel = priority === "tertiary" && Boolean(label);
     const labelClassName = useMemo(
       () =>
         clsx(
@@ -203,6 +229,15 @@ const Text = forwardRef<HTMLInputElement, InputProps>(
       [inputClassName],
     );
 
+    const mergedRef = useCallback(
+      (node: HTMLInputElement | null) => {
+        inputRef.current = node;
+        setForwardedRef(forwardedRef, node);
+        registerRef?.(node);
+      },
+      [forwardedRef, registerRef],
+    );
+
     const handleFocus = useCallback(
       (event: FocusEvent<HTMLInputElement>) => {
         setIsFocused(true);
@@ -214,25 +249,27 @@ const Text = forwardRef<HTMLInputElement, InputProps>(
     const handleBlur = useCallback(
       (event: FocusEvent<HTMLInputElement>) => {
         setIsFocused(false);
+        registerOnBlur?.(event);
         onBlur?.(event);
       },
-      [onBlur],
+      [onBlur, registerOnBlur],
     );
 
     const handleChange = useCallback(
       (event: ChangeEvent<HTMLInputElement>) => {
-        if (value === undefined) {
-          setUncontrolledValue(event.target.value);
-        }
+        setHasValue(event.currentTarget.value.length > 0);
+        registerOnChange?.(event);
         onChange?.(event);
       },
-      [onChange, value],
+      [onChange, registerOnChange],
     );
 
+    const inputName = register?.name ?? name;
+
     return (
       <div
         className={containerClassName}
-        data-appearance={appearance}
+        data-priority={priority}
         data-size={size}
         data-state={visualState}
         data-block={block ? "true" : undefined}
@@ -244,17 +281,17 @@ const Text = forwardRef<HTMLInputElement, InputProps>(
             className={labelClassName}
             htmlFor={labelFor}
             data-slot="label"
-            data-appearance={appearance}
+            data-priority={priority}
             data-state={visualState}
           >
             {label}
           </label>
         ) : null}
-        <div className={boxClassName} data-slot="box">
+        <div className={fieldBoxClassName} data-slot="box">
           <div
             className={INPUT_FIELD_CLASSNAME}
             data-state={visualState}
-            data-appearance={appearance}
+            data-priority={priority}
             data-size={size}
             data-block={block ? "true" : undefined}
           >
@@ -267,44 +304,45 @@ const Text = forwardRef<HTMLInputElement, InputProps>(
                 {label}
               </div>
             ) : null}
-            {prefix ? (
+            {left ? (
               <div
-                className={`${INPUT_AFFIX_CLASSNAME} ${INPUT_AFFIX_CLASSNAME}--prefix`}
-                data-slot="prefix"
+                className={`${INPUT_AFFIX_CLASSNAME} ${INPUT_AFFIX_CLASSNAME}--left`}
+                data-slot="left"
               >
-                {prefix}
+                {left}
               </div>
             ) : null}
             <input
               {...restProps}
               id={fieldId}
-              ref={forwardedRef}
+              ref={mergedRef}
               className={inputElementClassName}
               disabled={isDisabled}
               aria-invalid={resolvedState === "error" ? true : undefined}
               aria-describedby={helperElementId}
               type={type}
-              defaultValue={defaultValue}
               value={value}
+              defaultValue={defaultValue}
+              name={inputName}
               onChange={handleChange}
               onFocus={handleFocus}
               onBlur={handleBlur}
             />
-            {suffix ? (
+            {right ? (
               <div
-                className={`${INPUT_AFFIX_CLASSNAME} ${INPUT_AFFIX_CLASSNAME}--suffix`}
-                data-slot="suffix"
+                className={`${INPUT_AFFIX_CLASSNAME} ${INPUT_AFFIX_CLASSNAME}--right`}
+                data-slot="right"
               >
-                {suffix}
+                {right}
               </div>
             ) : null}
-            {showResetSlot ? (
+            {showClearIcon ? (
               <div
-                className={`${INPUT_AFFIX_CLASSNAME} ${INPUT_AFFIX_CLASSNAME}--reset`}
-                data-slot="reset"
+                className={`${INPUT_AFFIX_CLASSNAME} ${INPUT_AFFIX_CLASSNAME}--clear`}
+                data-slot="clear"
                 data-visible="true"
               >
-                {effectiveResetSlot}
+                {effectiveClearIcon}
               </div>
             ) : null}
             {statusSlot ? (
@@ -318,16 +356,16 @@ const Text = forwardRef<HTMLInputElement, InputProps>(
             ) : null}
           </div>
         </div>
-        {shouldShowHelper ? (
+        {helper && !hideHelper ? (
           <div
-            {...helperTextProps}
+            {...helperProps}
             className={helperClassName}
             id={helperElementId}
-            data-slot="helper-text"
-            data-appearance={appearance}
+            data-slot="helper"
+            data-priority={priority}
             data-state={visualState}
           >
-            {helperText}
+            {helper}
           </div>
         ) : null}
       </div>

package/src/components/input/markup/text/Identification.tsx

@@ -15,14 +15,14 @@ import type { InputProps } from "../../types";
  * IdentificationInput props. 고정 길이 숫자 코드 입력에 필요한 label/helper/state/onComplete를 제공한다.
  * @property {number} [length=6] 입력칸 개수(4~8 사이로 자동 보정).
  * @property {InputProps["label"]} [label] 상단 라벨.
- * @property {InputProps["helperText"]} [helperText] helper 텍스트.
+ * @property {InputProps["helper"]} [helper] helper 텍스트.
  * @property {InputProps["state"]} [state="default"] 시각 상태.
  * @property {(code: string) => void} [onComplete] 모든 셀이 채워졌을 때 호출.
  */
 export interface IdentificationInputProps {
   length?: number;
   label?: InputProps["label"];
-  helperText?: InputProps["helperText"];
+  helper?: InputProps["helper"];
   state?: InputProps["state"];
   onComplete?: (code: string) => void;
 }
@@ -33,14 +33,14 @@ export interface IdentificationInputProps {
  * @param {IdentificationInputProps} props
  * @param {number} [props.length=6] 입력 필드 길이. 4~8 범위로 자동 보정된다.
  * @param {InputProps["label"]} [props.label] 상단 label 콘텐츠.
- * @param {InputProps["helperText"]} [props.helperText] helper 텍스트.
+ * @param {InputProps["helper"]} [props.helper] helper 텍스트.
  * @param {InputProps["state"]} [props.state] 시각 상태.
  * @param {(code: string) => void} [props.onComplete] 모든 셀이 채워졌을 때 호출되는 콜백.
  */
 const IdentificationInput = forwardRef<
   HTMLInputElement[],
   IdentificationInputProps
->(({ length = 6, label, helperText, state, onComplete }, forwardedRef) => {
+>(({ length = 6, label, helper, state, onComplete }, forwardedRef) => {
   const safeLength = Math.max(4, Math.min(8, length));
   const [values, setValues] = useState(() =>
     Array.from({ length: safeLength }, () => ""),
@@ -112,7 +112,7 @@ const IdentificationInput = forwardRef<
     [onComplete, safeLength],
   );
 
-  const helperNode = useMemo(() => helperText, [helperText]);
+  const helperNode = useMemo(() => helper, [helper]);
 
   // forwardRef 사용자는 각 셀 DOM 배열을 직접 제어할 수 있도록 노출한다.
   useImperativeHandle(

package/src/components/input/markup/text/Password.tsx

@@ -5,61 +5,32 @@ import HideOffIcon from "../../img/hide-off.svg";
 import HideOnIcon from "../../img/hide-on.svg";
 
 /**
- * PasswordInput 전용 props. Text Input props에서 type/defaultValue 제약을 재정의하고 toggle 옵션을 추가한다.
+ * PasswordInput 전용 props. Text Input props에서 type을 password 전용으로 고정하고 보기/숨김 토글 옵션을 확장한다.
  * @property {boolean} [defaultVisible=false] 초기 렌더 시 비밀번호를 드러낼지 여부.
  * @property {{show: string; hide: string}} [toggleLabel] 토글 버튼에 사용할 라벨 텍스트 집합.
- * @property {string} [defaultValue] 비제어 초기값.
  */
-export interface PasswordInputProps extends Omit<
-  InputProps,
-  "type" | "defaultValue"
-> {
+export interface PasswordInputProps extends Omit<InputProps, "type"> {
   defaultVisible?: boolean;
   toggleLabel?: {
     show: string;
     hide: string;
   };
-  defaultValue?: string;
 }
 
 /**
- * PasswordInput — 기본 Text 입력을 비밀번호 토글 UX로 확장.
+ * PasswordInput — 기본 Text 입력을 비밀번호 토글 UX로 확장한다.
  * @component
  * @param {PasswordInputProps} props
- * @param {"primary" | "secondary" | "tertiary"} [props.appearance="primary"] 토큰 세트.
- * @param {"small" | "medium" | "large"} [props.size="medium"] 높이/spacing.
- * @param {"default" | "active" | "focused" | "success" | "error" | "disabled"} [props.state="default"] 시각 상태.
- * @param {boolean} [props.block=false] true면 width 100%.
- * @param {React.ReactNode} [props.prefix] prefix 슬롯(Password에서는 기본 제공하지 않음).
- * @param {React.ReactNode} [props.suffix] suffix 슬롯. 미지정 시 보기/숨김 토글 버튼 자동 배치.
- * @param {React.ReactNode} [props.successIcon] success 상태 아이콘.
- * @param {React.ReactNode} [props.errorIcon] error 상태 아이콘.
- * @param {React.ReactNode} [props.label] label 영역 콘텐츠.
- * @param {React.ReactNode} [props.helperText] helper 영역 텍스트.
- * @param {boolean} [props.hideHelperText] helper 숨김 여부.
- * @param {string} [props.inputClassName] `<input>` className.
- * @param {string} [props.wrapperClassName] `.input-box` className.
- * @param {object} [props.labelProps] label attr.
- * @param {object} [props.helperTextProps] helper attr.
- * @param {boolean} [props.disabled] native disabled.
- * @param {string} [props.id] 외부 id.
- * @param {string} [props.className] root className.
- * @param {"default" | "active" | "focused" | "success" | "error" | "disabled"} [props.data-simulated-state]
- *  Storybook 시각 상태 강제용.
- * @param {string} [props.defaultValue] 비제어 초기값.
- * @param {string | number | readonly string[]} [props.value] 제어형 값.
- * @param {(event: React.ChangeEvent<HTMLInputElement>) => void} [props.onChange] 변경 핸들러.
- * @param {(event: React.FocusEvent<HTMLInputElement>) => void} [props.onFocus] focus 핸들러.
- * @param {(event: React.FocusEvent<HTMLInputElement>) => void} [props.onBlur] blur 핸들러.
  * @param {boolean} [props.defaultVisible=false] 초기 노출 여부.
- * @param {{show: string; hide: string}} [props.toggleLabel] 토글 버튼 라벨.
+ * @param {{show: string; hide: string}} [props.toggleLabel={show:"보기",hide:"숨김"}] 토글 버튼 라벨.
+ * 나머지 props는 Text Input과 동일하다.
  */
 const PasswordInput = forwardRef<HTMLInputElement, PasswordInputProps>(
   (
     {
       defaultVisible = false,
       toggleLabel = { show: "보기", hide: "숨김" },
-      suffix,
+      right,
       defaultValue,
       ...restProps
     },
@@ -93,7 +64,7 @@ const PasswordInput = forwardRef<HTMLInputElement, PasswordInputProps>(
         ref={forwardedRef}
         type={visible ? "text" : "password"}
         defaultValue={defaultValue}
-        suffix={suffix ?? toggleButton}
+        right={right ?? toggleButton}
       />
     );
   },

package/src/components/input/markup/text/Phone.tsx

@@ -10,19 +10,13 @@ import { Text } from "./Base";
  * @property {string} [defaultValue] 비제어 초기값(숫자/포맷 모두 허용).
  * @property {(value: string, digits: string) => void} [onValueChange] 포맷팅 값/숫자만 값을 함께 전달.
  * @property {ComponentPropsWithoutRef<"input">["onChange"]} [onChange] native onChange override.
- * @property {() => void} [onRequestCode] suffix 버튼 클릭 시 호출.
- * @property {string} [requestButtonLabel="인증번호 요청"] suffix 버튼 라벨.
- * @property {boolean} [requestButtonDisabled] suffix 버튼 disabled 여부.
+ * @property {() => void} [onRequestCode] right 슬롯 버튼 클릭 시 호출.
+ * @property {string} [requestButtonLabel="인증번호 요청"] right 슬롯 버튼 라벨.
+ * @property {boolean} [requestButtonDisabled] right 슬롯 버튼 disabled 여부.
  */
 export interface PhoneInputProps extends Omit<
   InputProps,
-  | "type"
-  | "prefix"
-  | "inputMode"
-  | "pattern"
-  | "onChange"
-  | "value"
-  | "defaultValue"
+  "type" | "inputMode" | "pattern" | "onChange" | "value" | "defaultValue"
 > {
   value?: string;
   defaultValue?: string;
@@ -43,33 +37,8 @@ const formatPhoneNumber = (digits: string) => maskPhone(digits);
 /**
  * PhoneInput — 휴대폰 번호 마스킹과 인증번호 요청 버튼을 제공하는 입력.
  * @component
- * @param {PhoneInputProps} props
- * @param {"primary" | "secondary" | "tertiary"} [props.appearance="primary"] 토큰 세트.
- * @param {"small" | "medium" | "large"} [props.size="medium"] 높이/spacing.
- * @param {"default" | "active" | "focused" | "success" | "error" | "disabled"} [props.state="default"] 시각 상태.
- * @param {boolean} [props.block=false] true면 width 100%.
- * @param {React.ReactNode} [props.suffix] suffix 슬롯. 미지정 시 인증 버튼 자동 배치.
- * @param {React.ReactNode} [props.successIcon] success 상태 아이콘.
- * @param {React.ReactNode} [props.errorIcon] error 상태 아이콘.
- * @param {React.ReactNode} [props.label] label 콘텐츠.
- * @param {React.ReactNode} [props.helperText] helper 텍스트.
- * @param {boolean} [props.hideHelperText] helper 숨김 여부.
- * @param {string} [props.inputClassName] `<input>` className.
- * @param {string} [props.wrapperClassName] `.input-box` className.
- * @param {object} [props.labelProps] label attr.
- * @param {object} [props.helperTextProps] helper attr.
- * @param {boolean} [props.disabled] native disabled.
- * @param {string} [props.id] 외부 id.
- * @param {string} [props.className] root className.
- * @param {"default" | "active" | "focused" | "success" | "error" | "disabled"} [props.data-simulated-state]
- *  Storybook 시각 상태 강제용.
- * @param {string} [props.value] 제어형 값(포맷팅).
- * @param {string} [props.defaultValue] 비제어 초기값.
- * @param {(value: string, digits: string) => void} [props.onValueChange] 포맷팅/숫자 값 동시 전달.
- * @param {(event: ChangeEvent<HTMLInputElement>) => void} [props.onChange] native onChange override.
- * @param {() => void} [props.onRequestCode] 인증번호 요청 버튼 핸들러.
- * @param {string} [props.requestButtonLabel="인증번호 요청"] 버튼 라벨.
- * @param {boolean} [props.requestButtonDisabled] 버튼 disabled.
+ * @param {PhoneInputProps} props Phone 전용 props.
+ * 나머지 Text Input 공통 props(priority/size/state/helper 등)도 동일하게 사용할 수 있다.
  */
 const PhoneInput = forwardRef<HTMLInputElement, PhoneInputProps>(
   (
@@ -81,7 +50,7 @@ const PhoneInput = forwardRef<HTMLInputElement, PhoneInputProps>(
       onRequestCode,
       requestButtonLabel = "인증번호 요청",
       requestButtonDisabled,
-      suffix,
+      right,
       ...restProps
     },
     forwardedRef,
@@ -119,7 +88,7 @@ const PhoneInput = forwardRef<HTMLInputElement, PhoneInputProps>(
       if (!onRequestCode) {
         return null;
       }
-      // 휴대폰 인증 입력은 우측 suffix에 인증 버튼을 둔다.
+      // 휴대폰 인증 입력은 우측 right 슬롯에 인증 버튼을 둔다.
       return (
         <button
           type="button"
@@ -140,7 +109,7 @@ const PhoneInput = forwardRef<HTMLInputElement, PhoneInputProps>(
         inputMode="tel"
         value={formattedValue}
         onChange={handleChange}
-        suffix={suffix ?? actionButton}
+        right={right ?? actionButton}
       />
     );
   },

package/src/components/input/markup/text/Search.tsx

@@ -9,52 +9,21 @@ import SearchIcon from "../../img/search.svg";
 export interface SearchInputProps extends Omit<InputProps, "type"> {}
 
 /**
- * SearchInput — 기본 Text 입력에 검색 아이콘 prefix를 제공한다.
- * @component
- * @param {SearchInputProps} props
- * @param {"primary" | "secondary" | "tertiary"} [props.appearance="primary"] 토큰 세트.
- * @param {"small" | "medium" | "large"} [props.size="medium"] 높이/spacing.
- * @param {"default" | "active" | "focused" | "success" | "error" | "disabled"} [props.state="default"] 시각 상태.
- * @param {boolean} [props.block=false] true면 width 100%.
- * @param {React.ReactNode} [props.prefix] prefix 슬롯. 미지정 시 돋보기 아이콘이 자동 배치된다.
- * @param {React.ReactNode} [props.suffix] suffix 슬롯.
- * @param {React.ReactNode} [props.successIcon] success 상태 아이콘.
- * @param {React.ReactNode} [props.errorIcon] error 상태 아이콘.
- * @param {React.ReactNode} [props.label] label 콘텐츠.
- * @param {React.ReactNode} [props.helperText] helper 텍스트.
- * @param {boolean} [props.hideHelperText] helper 숨김 여부.
- * @param {string} [props.inputClassName] `<input>` className.
- * @param {string} [props.wrapperClassName] `.input-box` className.
- * @param {object} [props.labelProps] label attr.
- * @param {object} [props.helperTextProps] helper attr.
- * @param {boolean} [props.disabled] native disabled.
- * @param {string} [props.id] 외부 id.
- * @param {string} [props.className] root className.
- * @param {"default" | "active" | "focused" | "success" | "error" | "disabled"} [props.data-simulated-state]
- *  Storybook 시각 상태 강제용.
- * @param {string | number | readonly string[]} [props.defaultValue] 비제어 초기값.
- * @param {string | number | readonly string[]} [props.value] 제어형 값.
- * @param {(event: React.ChangeEvent<HTMLInputElement>) => void} [props.onChange] 입력 변경 핸들러.
- * @param {(event: React.FocusEvent<HTMLInputElement>) => void} [props.onFocus] focus 핸들러.
- * @param {(event: React.FocusEvent<HTMLInputElement>) => void} [props.onBlur] blur 핸들러.
+ * SearchInput — 기본 Text 입력에 검색 아이콘 left 슬롯과 type="search"를 제공한다.
+ * 다른 props(priority/size/helper 등)는 Text Input과 동일하다.
  */
 const SearchInput = forwardRef<HTMLInputElement, SearchInputProps>(
-  ({ prefix, ...restProps }, forwardedRef) => {
-    const prefixNode = useMemo(() => {
-      if (prefix) {
-        return prefix;
+  ({ left, ...restProps }, forwardedRef) => {
+    const leftNode = useMemo(() => {
+      if (left) {
+        return left;
       }
-      // 검색 input은 기본적으로 돋보기 아이콘 prefix를 노출한다.
+      // 검색 input은 기본적으로 돋보기 아이콘을 left 슬롯에 노출한다.
       return <SearchIcon aria-hidden="true" />;
-    }, [prefix]);
+    }, [left]);
 
     return (
-      <Text
-        {...restProps}
-        ref={forwardedRef}
-        type="search"
-        prefix={prefixNode}
-      />
+      <Text {...restProps} ref={forwardedRef} type="search" left={leftNode} />
     );
   },
 );

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

@@ -96,7 +96,7 @@
     min-height: var(--theme-input-height-large);
   }
 
-  &[data-appearance="secondary"] {
+  &[data-priority="secondary"] {
     border: none;
     border-bottom: var(--theme-input-border-width-default) solid
       var(--theme-input-border-color);
@@ -106,7 +106,7 @@
     background-color: transparent;
   }
 
-  &[data-appearance="tertiary"] {
+  &[data-priority="tertiary"] {
     border-radius: var(--theme-input-radius-tertiary);
     background-color: var(--theme-input-surface);
     min-height: var(--theme-input-height-tertiary);
@@ -130,7 +130,7 @@
     }
   }
 
-  &:not([data-appearance="secondary"]) {
+  &:not([data-priority="secondary"]) {
     &[data-state="active"],
     &[data-state="focused"] {
       border-color: var(--theme-input-border-active);
@@ -196,11 +196,11 @@
   color: var(--theme-input-label-color);
 }
 
-.input-field[data-appearance="secondary"] .input-element {
+.input-field[data-priority="secondary"] .input-element {
   padding-inline: 0;
 }
 
-.input-field[data-appearance="tertiary"] .input-element {
+.input-field[data-priority="tertiary"] .input-element {
   min-height: var(--theme-size-medium-2);
 }
 
@@ -225,18 +225,18 @@
   min-width: 20px;
   color: var(--theme-input-helper-color);
 
-  &--prefix {
+  &--left {
     order: -1;
     margin-right: var(--spacing-gap-3);
   }
 
-  &--suffix,
-  &--reset,
+  &--right,
+  &--clear,
   &--status {
     margin-left: var(--spacing-gap-3);
   }
 
-  &--reset,
+  &--clear,
   &--status {
     color: var(--theme-input-text-color);
   }
@@ -250,7 +250,7 @@
     color: var(--color-primary-default);
   }
 }
-.input-field[data-appearance="secondary"] {
+.input-field[data-priority="secondary"] {
   border-bottom-width: var(--theme-input-border-width-default);
 
   &[data-state="active"],
@@ -307,7 +307,7 @@
     border-color: var(--theme-input-border-color);
     background-color: var(--theme-input-surface-disabled);
 
-    &[data-appearance="secondary"] {
+    &[data-priority="secondary"] {
       background-color: transparent;
     }
   }

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

@@ -1,9 +1,10 @@
-import type { ComponentPropsWithoutRef, ReactElement, ReactNode } from "react";
+import type { ComponentPropsWithoutRef, ReactNode } from "react";
+import type { UseFormRegisterReturn } from "react-hook-form";
 
 /**
- * appearance 축은 tokens 기반 테마 계층을 지정한다.
+ * priority 축은 tokens 기반 테마 계층을 지정한다.
  */
-export const INPUT_APPEARANCES = ["primary", "secondary", "tertiary"] as const;
+export const INPUT_PRIORITIES = ["primary", "secondary", "tertiary"] as const;
 /**
  * size 축은 높이/타이포/spacing을 결정한다.
  */
@@ -20,48 +21,56 @@ export const INPUT_STATES = [
   "disabled",
 ] as const;
 
-export type InputAppearance = (typeof INPUT_APPEARANCES)[number];
+export type InputPriority = (typeof INPUT_PRIORITIES)[number];
 export type InputSize = (typeof INPUT_SIZES)[number];
 export type InputState = (typeof INPUT_STATES)[number];
 
 type NativeInputProps = ComponentPropsWithoutRef<"input">;
 
 /**
- * prefix/suffix와 status 아이콘 슬롯 정의.
+ * 좌우 슬롯과 status 아이콘 정의.
  */
-export interface InputAffix {
-  prefix?: ReactNode;
-  suffix?: ReactNode;
-  resetSlot?: ReactElement;
+export interface InputSlots {
+  left?: ReactNode;
+  right?: ReactNode;
+  clearIcon?: ReactNode;
   successIcon?: ReactNode;
   errorIcon?: ReactNode;
 }
 
 /**
- * label/helperText 등 피드백 슬롯 정의.
+ * label/helper 등 피드백 슬롯 정의.
  */
 export interface InputFeedback {
   label?: ReactNode;
-  helperText?: ReactNode;
-  hideHelperText?: boolean;
+  helper?: ReactNode;
+  hideHelper?: boolean;
 }
 
 /**
- * 텍스트 입력의 핵심 props. native input 속성에서 size/prefix/suffix는 제외하고 자체 슬롯으로 교체했다.
+ * 텍스트 입력의 핵심 props. native input 속성에서 size는 제외하고 left/right 등 슬롯을 별도로 정의한다.
  */
 export interface InputProps
-  extends
-    Omit<NativeInputProps, "prefix" | "suffix" | "size">,
-    InputAffix,
-    InputFeedback {
-  appearance?: InputAppearance;
+  extends Omit<NativeInputProps, "size">, InputSlots, InputFeedback {
+  /** semantic color/token 세트 */
+  priority?: InputPriority;
+  /** 높이/타이포 세트 */
   size?: InputSize;
+  /** 시각 상태. disabled prop과 조합된다 */
   state?: InputState;
+  /** true면 width:100% */
   block?: boolean;
+  /** 실제 `<input>` className */
   inputClassName?: string;
-  wrapperClassName?: string;
+  /** `.input-box` className */
+  boxClassName?: string;
+  /** label attr 커스터마이즈 */
   labelProps?: ComponentPropsWithoutRef<"label">;
-  helperTextProps?: ComponentPropsWithoutRef<"div">;
+  /** helper attr 커스터마이즈 */
+  helperProps?: ComponentPropsWithoutRef<"div">;
+  /** react-hook-form register 반환값 */
+  register?: UseFormRegisterReturn;
+  /** Storybook 등에서 강제 상태 표현용 */
   "data-simulated-state"?: InputState;
 }
 
@@ -69,7 +78,7 @@ export interface InputProps
  * className composer helper가 필요로 하는 파라미터 집합.
  */
 export interface InputClassNameOptions {
-  appearance: InputAppearance;
+  priority: InputPriority;
   size: InputSize;
   state: InputState;
   block: boolean;

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

@@ -11,7 +11,7 @@ const INPUT_AFFIX_CLASSNAME = "input-affix";
  * container `.input` element className을 조립한다.
  */
 const composeInputClassName = ({
-  appearance,
+  priority,
   size,
   state,
   block,
@@ -19,7 +19,7 @@ const composeInputClassName = ({
 }: InputClassNameOptions) =>
   clsx(
     INPUT_CLASSNAME,
-    `${INPUT_CLASSNAME}--appearance-${appearance}`,
+    `${INPUT_CLASSNAME}--priority-${priority}`,
     `${INPUT_CLASSNAME}--size-${size}`,
     {
       [`${INPUT_CLASSNAME}--state-${state}`]: state !== "default",
@@ -32,7 +32,7 @@ const composeInputClassName = ({
  * 박스(wrapper) `.input-box` className을 조립한다.
  */
 const composeInputBoxClassName = ({
-  appearance,
+  priority,
   size,
   state,
   block,
@@ -40,7 +40,7 @@ const composeInputBoxClassName = ({
 }: InputClassNameOptions) =>
   clsx(
     INPUT_BOX_CLASSNAME,
-    `${INPUT_BOX_CLASSNAME}--appearance-${appearance}`,
+    `${INPUT_BOX_CLASSNAME}--priority-${priority}`,
     `${INPUT_BOX_CLASSNAME}--size-${size}`,
     {
       [`${INPUT_BOX_CLASSNAME}--state-${state}`]: state !== "default",