@uniai-fe/uds-primitives 0.0.1

package/src/components/drawer/utils/index.tsx

@@ -0,0 +1,77 @@
+import { cloneElement, isValidElement } from "react";
+import type {
+  ComponentPropsWithoutRef,
+  ForwardedRef,
+  JSXElementConstructor,
+  ReactElement,
+  ReactNode,
+} from "react";
+
+// 다중 ref를 하나의 콜백으로 합쳐주는 유틸.
+const mergeRefs = <T,>(
+  ...refs: (ForwardedRef<T> | undefined)[]
+): ((node: T | null) => void) => {
+  return node => {
+    refs.forEach(ref => {
+      if (typeof ref === "function") {
+        ref(node);
+      } else if (ref && typeof ref === "object") {
+        (ref as { current: T | null }).current = node;
+      }
+    });
+  };
+};
+
+// 사용자 핸들러와 내부 핸들러를 병렬로 실행한다.
+const composeEventHandlers =
+  <E extends { defaultPrevented: boolean }>(
+    userHandler?: (event: E) => void,
+    ourHandler?: (event: E) => void,
+  ) =>
+  (event: E) => {
+    userHandler?.(event);
+    if (!event.defaultPrevented) {
+      ourHandler?.(event);
+    }
+  };
+
+// asChild 패턴을 지원하는 button 추상화.
+type ButtonClickEvent = Parameters<
+  NonNullable<ComponentPropsWithoutRef<"button">["onClick"]>
+>[0];
+
+type GenericElement = ReactElement<
+  Record<string, unknown>,
+  string | JSXElementConstructor<Record<string, unknown>>
+> & {
+  ref?: ForwardedRef<HTMLButtonElement>;
+};
+
+const renderButtonLike = (
+  asChild: boolean | undefined,
+  children: ReactNode,
+  props: ComponentPropsWithoutRef<"button">,
+  ref: ForwardedRef<HTMLButtonElement>,
+) => {
+  if (asChild && children && isValidElement(children)) {
+    const element = children as GenericElement;
+    const mergedOnClick = composeEventHandlers<ButtonClickEvent>(
+      element.props.onClick as ((event: ButtonClickEvent) => void) | undefined,
+      props.onClick,
+    );
+    return cloneElement(element, {
+      ...(props as Record<string, unknown>),
+      onClick: mergedOnClick,
+      ref: mergeRefs(element.ref, ref),
+    });
+  }
+
+  return (
+    <button type="button" ref={ref} {...props}>
+      {children}
+    </button>
+  );
+};
+
+export { composeEventHandlers, mergeRefs, renderButtonLike };
+export * from "./context";

package/src/components/dropdown/hooks/index.ts

@@ -0,0 +1,4 @@
+/**
+ * TODO(dropdown): 접근성/상태 계산 hook을 정의한다.
+ */
+export {};

package/src/components/dropdown/index.scss

@@ -0,0 +1 @@
+@use "./styles/index.scss";

package/src/components/dropdown/index.tsx

@@ -0,0 +1,4 @@
+/**
+ * dropdown 카테고리 배럴 placeholder: 실제 구현은 markup/ 하위에 추가한다.
+ */
+export * from "./markup";

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

@@ -0,0 +1,4 @@
+/**
+ * TODO(dropdown): SOT 및 사용자 제약에 따라 컴포넌트를 구현한다.
+ */
+export {};

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

@@ -0,0 +1,3 @@
+@use "@uniai-fe/uds-foundation/css";
+
+/* TODO(dropdown): 스타일을 SOT 토큰 값으로 정의한다. */

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

@@ -0,0 +1,4 @@
+/**
+ * TODO(dropdown): variant/slot 타입 정의를 작성한다.
+ */
+export {};

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

@@ -0,0 +1,4 @@
+/**
+ * TODO(dropdown): 토큰 매핑과 클래스명 유틸을 구현한다.
+ */
+export {};

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

@@ -0,0 +1,4 @@
+/**
+ * TODO(input): 접근성/상태 계산 hook을 정의한다.
+ */
+export {};

package/src/components/input/img/check-correct.svg

@@ -0,0 +1,3 @@
+<svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M8 2C11.3137 2 14 4.68629 14 8C14 11.3137 11.3137 14 8 14C4.68629 14 2 11.3137 2 8C2 4.68629 4.68629 2 8 2ZM10.9268 6.44141C10.7185 6.23363 10.381 6.23351 10.1729 6.44141L7.48535 9.12891L5.71094 7.35352C5.50266 7.14524 5.16433 7.14524 4.95605 7.35352C4.74799 7.56167 4.74821 7.89914 4.95605 8.10742L7.1084 10.2598C7.31665 10.468 7.655 10.4689 7.86328 10.2607L10.9277 7.19629C11.1358 6.98799 11.135 6.6496 10.9268 6.44141Z" fill="#1AB24D"/>
+</svg>

package/src/components/input/img/check-default.svg

@@ -0,0 +1,3 @@
+<svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M8 2C11.3137 2 14 4.68629 14 8C14 11.3137 11.3137 14 8 14C4.68629 14 2 11.3137 2 8C2 4.68629 4.68629 2 8 2ZM10.9268 6.44141C10.7185 6.23363 10.381 6.23351 10.1729 6.44141L7.48535 9.12891L5.71094 7.35352C5.50266 7.14524 5.16433 7.14524 4.95605 7.35352C4.74799 7.56167 4.74821 7.89914 4.95605 8.10742L7.1084 10.2598C7.31665 10.468 7.655 10.4689 7.86328 10.2607L10.9277 7.19629C11.1358 6.98799 11.135 6.6496 10.9268 6.44141Z" fill="#CACBCE"/>
+</svg>

package/src/components/input/img/check-incorrect.svg

@@ -0,0 +1,3 @@
+<svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M8 2C11.3137 2 14 4.68629 14 8C14 11.3137 11.3137 14 8 14C4.68629 14 2 11.3137 2 8C2 4.68629 4.68629 2 8 2ZM10.9268 6.44141C10.7185 6.23363 10.381 6.23351 10.1729 6.44141L7.48535 9.12891L5.71094 7.35352C5.50266 7.14524 5.16433 7.14524 4.95605 7.35352C4.74799 7.56167 4.74821 7.89914 4.95605 8.10742L7.1084 10.2598C7.31665 10.468 7.655 10.4689 7.86328 10.2607L10.9277 7.19629C11.1358 6.98799 11.135 6.6496 10.9268 6.44141Z" fill="#DA1D0B"/>
+</svg>

package/src/components/input/img/error.svg

@@ -0,0 +1,5 @@
+<svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+<circle cx="12" cy="12" r="8" fill="#DA1D0B"/>
+<path d="M12 8V13" stroke="white" stroke-width="1.6" stroke-linecap="round"/>
+<circle cx="12" cy="16" r="1" fill="white"/>
+</svg>

package/src/components/input/img/hide-off.svg

@@ -0,0 +1,4 @@
+<svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M12 6.7998C14.572 6.7998 16.9162 7.73398 18.6162 8.9082C19.4654 9.49478 20.134 10.1272 20.5811 10.707C21.0478 11.3124 21.2002 11.7634 21.2002 12C21.2002 12.2366 21.0478 12.6876 20.5811 13.293C20.134 13.8728 19.4654 14.5052 18.6162 15.0918C16.9162 16.266 14.572 17.2002 12 17.2002C9.428 17.2002 7.08378 16.266 5.38379 15.0918C4.53459 14.5052 3.86603 13.8728 3.41895 13.293C2.95218 12.6876 2.7998 12.2366 2.7998 12C2.7998 11.7634 2.95218 11.3124 3.41895 10.707C3.86603 10.1272 4.53459 9.49478 5.38379 8.9082C7.08378 7.73398 9.428 6.7998 12 6.7998Z" stroke="#BCBEC2" stroke-width="1.6"/>
+<circle cx="12" cy="12" r="3.2" stroke="#BCBEC2" stroke-width="1.6"/>
+</svg>

package/src/components/input/img/hide-on.svg

@@ -0,0 +1,6 @@
+<svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M12 6.7998C14.572 6.7998 16.9162 7.73398 18.6162 8.9082C19.4654 9.49478 20.134 10.1272 20.5811 10.707C21.0478 11.3124 21.2002 11.7634 21.2002 12C21.2002 12.2366 21.0478 12.6876 20.5811 13.293C20.134 13.8728 19.4654 14.5052 18.6162 15.0918C16.9162 16.266 14.572 17.2002 12 17.2002C9.428 17.2002 7.08378 16.266 5.38379 15.0918C4.53459 14.5052 3.86603 13.8728 3.41895 13.293C2.95218 12.6876 2.7998 12.2366 2.7998 12C2.7998 11.7634 2.95218 11.3124 3.41895 10.707C3.86603 10.1272 4.53459 9.49478 5.38379 8.9082C7.08378 7.73398 9.428 6.7998 12 6.7998Z" stroke="#BCBEC2" stroke-width="1.6"/>
+<circle cx="12" cy="12" r="3.2" stroke="#BCBEC2" stroke-width="1.6"/>
+<path d="M20 4L4 20" stroke="white" stroke-width="3.2" stroke-linecap="round"/>
+<path d="M20 4L4 20" stroke="#BCBEC2" stroke-width="1.6" stroke-linecap="round"/>
+</svg>

package/src/components/input/img/reset.svg

@@ -0,0 +1,3 @@
+<svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M12 3C16.9706 3 21 7.02944 21 12C21 16.9706 16.9706 21 12 21C7.02944 21 3 16.9706 3 12C3 7.02944 7.02944 3 12 3ZM15.04 8.95996C14.7276 8.6477 14.2215 8.64759 13.9092 8.95996L11.999 10.8691L10.0898 8.95996C9.77741 8.6477 9.27135 8.64759 8.95898 8.95996C8.64706 9.27236 8.64687 9.77853 8.95898 10.0908L10.8682 12L8.95898 13.9092C8.64685 14.2215 8.64699 14.7276 8.95898 15.04C9.27135 15.3524 9.77741 15.3523 10.0898 15.04L11.999 13.1299L13.9092 15.04C14.2215 15.3524 14.7276 15.3523 15.04 15.04C15.3523 14.7276 15.3524 14.2215 15.04 13.9092L13.1299 12L15.04 10.0908C15.3524 9.77849 15.3522 9.2724 15.04 8.95996Z" fill="#BCBEC2"/>
+</svg>

package/src/components/input/img/search.svg

@@ -0,0 +1,4 @@
+<svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+<circle cx="10.5" cy="10.5" r="6.5" stroke="#94989E" stroke-width="1.6" stroke-linecap="round"/>
+<path d="M15.6196 15.6196L19.6196 19.6196" stroke="#94989E" stroke-width="1.6" stroke-linecap="round"/>
+</svg>

package/src/components/input/img/success.svg

@@ -0,0 +1,3 @@
+<svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M12 3C16.9706 3 21 7.02944 21 12C21 16.9706 16.9706 21 12 21C7.02944 21 3 16.9706 3 12C3 7.02944 7.02944 3 12 3ZM16.3906 9.66309C16.0782 9.35097 15.5711 9.35077 15.2588 9.66309L11.2285 13.6934L8.56543 11.0303C8.25302 10.7183 7.74688 10.7181 7.43457 11.0303C7.12215 11.3427 7.12215 11.8497 7.43457 12.1621L10.6631 15.3896C10.9755 15.7021 11.4825 15.703 11.7949 15.3906L16.3906 10.7949C16.7029 10.4826 16.7026 9.97554 16.3906 9.66309Z" fill="#1A6AFF"/>
+</svg>

package/src/components/input/index.scss

@@ -0,0 +1 @@
+@use "./styles/index.scss";

package/src/components/input/index.tsx

@@ -0,0 +1,6 @@
+/**
+ * input 카테고리 배럴 placeholder: 실제 구현은 markup/ 하위에 추가한다.
+ */
+import "./index.scss";
+
+export * from "./markup";

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

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

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

@@ -0,0 +1,311 @@
+import clsx from "clsx";
+import {
+  ChangeEvent,
+  FocusEvent,
+  forwardRef,
+  useCallback,
+  useEffect,
+  useId,
+  useMemo,
+  useState,
+} from "react";
+import type { InputProps } from "../../types";
+import {
+  INPUT_AFFIX_CLASSNAME,
+  INPUT_ELEMENT_CLASSNAME,
+  INPUT_FIELD_CLASSNAME,
+  composeInputBoxClassName,
+  composeInputClassName,
+} from "../../utils";
+import ErrorIcon from "../../img/error.svg";
+import SuccessIcon from "../../img/success.svg";
+import ResetIcon from "../../img/reset.svg";
+
+/**
+ * Native `<input>` 기반 텍스트 필드. appearance/size/state 축과 label/helper 슬롯을 모두 제공한다.
+ * README와 Button 컴포넌트와 동일하게 props를 forwardRef 인자로 직접 구조분해한다.
+ */
+const Text = forwardRef<HTMLInputElement, InputProps>(
+  (
+    {
+      appearance = "primary",
+      size = "medium",
+      state: stateProp = "default",
+      block = false,
+      prefix,
+      suffix,
+      resetSlot,
+      successIcon,
+      errorIcon,
+      label,
+      helperText,
+      hideHelperText,
+      inputClassName,
+      wrapperClassName,
+      helperTextProps,
+      labelProps,
+      disabled,
+      id,
+      className,
+      "data-simulated-state": simulatedState,
+      type = "text",
+      defaultValue,
+      value,
+      onChange,
+      onFocus,
+      onBlur,
+      ...restProps
+    },
+    forwardedRef,
+  ) => {
+    const generatedId = useId();
+    const [uncontrolledValue, setUncontrolledValue] = useState<
+      string | number | readonly string[] | undefined
+    >(defaultValue);
+    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]);
+
+    useEffect(() => {
+      if (stateProp === "disabled" || disabled) {
+        setIsFocused(false);
+      }
+    }, [disabled, stateProp]);
+
+    const visualState = useMemo(() => {
+      if (resolvedState === "disabled") {
+        return "disabled";
+      }
+      if (resolvedState === "error") {
+        return "error";
+      }
+      return isFocused ? "active" : resolvedState;
+    }, [isFocused, resolvedState]);
+
+    const defaultStatusIcon = useMemo(() => {
+      if (resolvedState === "success") {
+        return <SuccessIcon aria-hidden="true" />;
+      }
+      if (resolvedState === "error") {
+        return <ErrorIcon aria-hidden="true" />;
+      }
+      return null;
+    }, [resolvedState]);
+
+    const statusSlot = useMemo(() => {
+      if (resolvedState === "success") {
+        return successIcon ?? defaultStatusIcon;
+      }
+      if (resolvedState === "error") {
+        return errorIcon ?? defaultStatusIcon;
+      }
+      return null;
+    }, [defaultStatusIcon, errorIcon, resolvedState, successIcon]);
+
+    const defaultResetSlot = 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 isDisabled = resolvedState === "disabled";
+    const labelFor = labelProps?.htmlFor ?? fieldId;
+    const containerClassName = useMemo(
+      () =>
+        composeInputClassName({
+          appearance,
+          size,
+          state: visualState,
+          block,
+          className,
+        }),
+      [appearance, block, className, size, visualState],
+    );
+    const boxClassName = useMemo(
+      () =>
+        composeInputBoxClassName({
+          appearance,
+          size,
+          state: visualState,
+          block,
+          className: wrapperClassName,
+        }),
+      [appearance, block, size, visualState, wrapperClassName],
+    );
+    const helperClassName = useMemo(
+      () => clsx("input-helper-text", helperTextProps?.className),
+      [helperTextProps?.className],
+    );
+    const shouldRenderInlineLabel = appearance === "teritary" && Boolean(label);
+    const labelClassName = useMemo(
+      () =>
+        clsx(
+          "input-label",
+          shouldRenderInlineLabel && "input-label--visually-hidden",
+          labelProps?.className,
+        ),
+      [labelProps?.className, shouldRenderInlineLabel],
+    );
+    const inputElementClassName = useMemo(
+      () => clsx(INPUT_ELEMENT_CLASSNAME, inputClassName),
+      [inputClassName],
+    );
+
+    const handleFocus = useCallback(
+      (event: FocusEvent<HTMLInputElement>) => {
+        setIsFocused(true);
+        onFocus?.(event);
+      },
+      [onFocus],
+    );
+
+    const handleBlur = useCallback(
+      (event: FocusEvent<HTMLInputElement>) => {
+        setIsFocused(false);
+        onBlur?.(event);
+      },
+      [onBlur],
+    );
+
+    const handleChange = useCallback(
+      (event: ChangeEvent<HTMLInputElement>) => {
+        if (value === undefined) {
+          setUncontrolledValue(event.target.value);
+        }
+        onChange?.(event);
+      },
+      [onChange, value],
+    );
+
+    return (
+      <div
+        className={containerClassName}
+        data-appearance={appearance}
+        data-size={size}
+        data-state={visualState}
+        data-block={block ? "true" : undefined}
+        data-simulated-state={simulatedState}
+      >
+        {label ? (
+          <label
+            {...labelProps}
+            className={labelClassName}
+            htmlFor={labelFor}
+            data-slot="label"
+            data-appearance={appearance}
+            data-state={visualState}
+          >
+            {label}
+          </label>
+        ) : null}
+        <div className={boxClassName} data-slot="box">
+          <div
+            className={INPUT_FIELD_CLASSNAME}
+            data-state={visualState}
+            data-appearance={appearance}
+            data-size={size}
+            data-block={block ? "true" : undefined}
+          >
+            {shouldRenderInlineLabel ? (
+              <div
+                className="input-inline-label"
+                aria-hidden="true"
+                data-slot="inline-label"
+              >
+                {label}
+              </div>
+            ) : null}
+            {prefix ? (
+              <div
+                className={`${INPUT_AFFIX_CLASSNAME} ${INPUT_AFFIX_CLASSNAME}--prefix`}
+                data-slot="prefix"
+              >
+                {prefix}
+              </div>
+            ) : null}
+            <input
+              {...restProps}
+              id={fieldId}
+              ref={forwardedRef}
+              className={inputElementClassName}
+              disabled={isDisabled}
+              aria-invalid={resolvedState === "error" ? true : undefined}
+              aria-describedby={helperElementId}
+              type={type}
+              defaultValue={defaultValue}
+              value={value}
+              onChange={handleChange}
+              onFocus={handleFocus}
+              onBlur={handleBlur}
+            />
+            {suffix ? (
+              <div
+                className={`${INPUT_AFFIX_CLASSNAME} ${INPUT_AFFIX_CLASSNAME}--suffix`}
+                data-slot="suffix"
+              >
+                {suffix}
+              </div>
+            ) : null}
+            {showResetSlot ? (
+              <div
+                className={`${INPUT_AFFIX_CLASSNAME} ${INPUT_AFFIX_CLASSNAME}--reset`}
+                data-slot="reset"
+                data-visible="true"
+              >
+                {effectiveResetSlot}
+              </div>
+            ) : null}
+            {statusSlot ? (
+              <div
+                className={`${INPUT_AFFIX_CLASSNAME} ${INPUT_AFFIX_CLASSNAME}--status`}
+                data-slot="status"
+                data-state={resolvedState}
+              >
+                {statusSlot}
+              </div>
+            ) : null}
+          </div>
+        </div>
+        {shouldShowHelper ? (
+          <div
+            {...helperTextProps}
+            className={helperClassName}
+            id={helperElementId}
+            data-slot="helper-text"
+            data-appearance={appearance}
+            data-state={visualState}
+          >
+            {helperText}
+          </div>
+        ) : null}
+      </div>
+    );
+  },
+);
+
+Text.displayName = "TextInput";
+
+export { Text };

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

@@ -0,0 +1,145 @@
+import {
+  ClipboardEvent,
+  ChangeEvent,
+  forwardRef,
+  useImperativeHandle,
+  KeyboardEvent,
+  useCallback,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import type { InputProps } from "../../types";
+
+export interface IdentificationInputProps {
+  length?: number;
+  label?: InputProps["label"];
+  helperText?: InputProps["helperText"];
+  state?: InputProps["state"];
+  onComplete?: (code: string) => void;
+}
+
+/**
+ * IdentificationInput — 인증번호 입력 UI. 개별 입력칸을 제공하고 focus 이동/붙여넣기 등을 처리한다.
+ * @param props.length 입력 필드 길이 (4~8 사이).
+ * @param props.onComplete 모든 셀이 채워졌을 때 호출.
+ */
+const IdentificationInput = forwardRef<
+  HTMLInputElement[],
+  IdentificationInputProps
+>(({ length = 6, label, helperText, state, onComplete }, forwardedRef) => {
+  const safeLength = Math.max(4, Math.min(8, length));
+  const [values, setValues] = useState(() =>
+    Array.from({ length: safeLength }, () => ""),
+  );
+  const inputRefs = useRef<Array<HTMLInputElement | null>>(
+    Array(safeLength).fill(null),
+  );
+
+  const focusCell = useCallback((index: number) => {
+    const ref = inputRefs.current[index];
+    ref?.focus();
+    ref?.select();
+  }, []);
+
+  const updateValues = useCallback(
+    (index: number, digit: string) => {
+      setValues(prev => {
+        const next = [...prev];
+        next[index] = digit;
+        if (!next.includes("")) {
+          onComplete?.(next.join(""));
+        }
+        return next;
+      });
+    },
+    [onComplete],
+  );
+
+  const handleChange = useCallback(
+    (index: number) => (event: ChangeEvent<HTMLInputElement>) => {
+      const digit = event.target.value.replace(/\D/g, "").slice(-1);
+      updateValues(index, digit);
+      if (digit && index < safeLength - 1) {
+        focusCell(index + 1);
+      }
+    },
+    [focusCell, safeLength, updateValues],
+  );
+
+  const handleKeyDown = useCallback(
+    (index: number) => (event: KeyboardEvent<HTMLInputElement>) => {
+      if (event.key === "Backspace" && !values[index] && index > 0) {
+        updateValues(index - 1, "");
+        focusCell(index - 1);
+        event.preventDefault();
+      }
+    },
+    [focusCell, updateValues, values],
+  );
+
+  const handlePaste = useCallback(
+    (event: ClipboardEvent<HTMLInputElement>) => {
+      const digits = event.clipboardData.getData("text").replace(/\D/g, "");
+      if (!digits) {
+        return;
+      }
+      event.preventDefault();
+      setValues(prev => {
+        const next = [...prev];
+        for (let i = 0; i < safeLength; i += 1) {
+          next[i] = digits[i] ?? next[i];
+        }
+        if (!next.includes("")) {
+          onComplete?.(next.join(""));
+        }
+        return next;
+      });
+    },
+    [onComplete, safeLength],
+  );
+
+  const helperNode = useMemo(() => helperText, [helperText]);
+
+  // forwardRef 사용자는 각 셀 DOM 배열을 직접 제어할 수 있도록 노출한다.
+  useImperativeHandle(
+    forwardedRef,
+    () =>
+      inputRefs.current.filter((element): element is HTMLInputElement =>
+        Boolean(element),
+      ),
+    [],
+  );
+
+  return (
+    <div className="one-time-code" data-state={state}>
+      {label ? <div className="one-time-code__label">{label}</div> : null}
+      <div className="one-time-code__fields">
+        {values.map((value, index) => (
+          <input
+            key={`identification-${index}`}
+            ref={element => {
+              inputRefs.current[index] = element;
+            }}
+            type="text"
+            inputMode="numeric"
+            className="one-time-code__input"
+            maxLength={1}
+            value={value}
+            onChange={handleChange(index)}
+            onKeyDown={handleKeyDown(index)}
+            onPaste={handlePaste}
+            aria-label={`${index + 1}번째 인증번호 숫자`}
+          />
+        ))}
+      </div>
+      {helperNode ? (
+        <div className="one-time-code__helper">{helperNode}</div>
+      ) : null}
+    </div>
+  );
+});
+
+IdentificationInput.displayName = "IdentificationInput";
+
+export { IdentificationInput };