@uniai-fe/uds-primitives 0.12.7 → 0.12.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniai-fe/uds-primitives",
-  "version": "0.12.7",
+  "version": "0.12.8",
   "description": "UNIAI Design System; Primitives Components Package",
   "type": "module",
   "private": false,
@@ -87,9 +87,9 @@
     "react-hook-form": "^7.86.0",
     "sass": "^1.102.0",
     "typescript": "6.0.3",
-    "@uniai-fe/next-devkit": "0.4.1",
     "@uniai-fe/eslint-config": "0.4.3",
     "@uniai-fe/tsconfig": "0.2.0",
+    "@uniai-fe/next-devkit": "0.4.1",
     "@uniai-fe/util-functions": "0.4.3",
     "@uniai-fe/uds-foundation": "0.6.0"
   },

package/src/components/input/markup/date/Template.tsx

@@ -1,6 +1,10 @@
 "use client";
 
-import type { ChangeEvent, MouseEvent as ReactMouseEvent } from "react";
+import type {
+  ChangeEvent,
+  FocusEvent as ReactFocusEvent,
+  MouseEvent as ReactMouseEvent,
+} from "react";
 import { forwardRef, useCallback, useMemo, useState } from "react";
 import { useUncontrolled } from "@mantine/hooks";
 import { Calendar } from "../../../calendar";
@@ -26,30 +30,39 @@ const INPUT_DATE_TABLE_FORMAT = "YY-MM-DD";
  * placeholder는 format과 별도 props로 처리되며, format 변경으로 placeholder가 자동 치환되지는 않는다.
  * @component
  * @param {InputCalendarProps} props
- * @param {CalendarMode} [props.mode="date"] 날짜/시간 모드
- * @param {CalendarColumns} [props.columns=1] 동시 노출 달력 수
- * @param {CalendarValue} [props.value] 제어형 값
- * @param {CalendarValue} [props.defaultValue] 비제어 초기값
- * @param {CalendarOnChange} [props.onChange] 값 변경 이벤트
- * @param {CalendarOnChange} [props.onValueChange] onChange alias
- * @param {boolean} [props.readOnly] 읽기 전용 여부
- * @param {boolean} [props.disabled] 비활성화 여부
- * @param {CalendarDatePickerProps} [props.datePickerProps] Mantine DatePicker 옵션
- * @param {string} [props.name] form name/RHF name
- * @param {UseFormRegisterReturn} [props.register] RHF register
- * @param {string} [props.placeholder="YYYY-MM-DD"] placeholder
- * @param {"primary" | "secondary" | "tertiary" | "table"} [props.priority="primary"] trigger input priority
- * @param {"default" | "active" | "focused" | "success" | "error" | "disabled" | "loading"} [props.state="default"] trigger input state
- * @param {ReactNode} [props.header] 패널 header 콘텐츠
- * @param {ReactNode} [props.footer] 패널 footer 콘텐츠
- * @param {InputCalendarTexts} [props.texts] 기본 Date 문구
- * @param {unknown} [props.timePicker] TimePicker 확장용 예약 슬롯(현재 미구현)
- * @param {boolean} [props.calendarOpened] calendar 열림 제어 상태
- * @param {(open: boolean) => void} [props.onCalendarOpen] calendar 열림 변경 이벤트
- * @param {(event: MouseEvent<Element>) => void} [props.onClick] trigger 클릭 핸들러
- * @param {string} [props.id] trigger id
- * @param {ReactNode} [props.trigger] 커스텀 trigger 슬롯
- * @param {(props: InputCalendarTriggerRenderProps) => ReactNode} [props.renderTrigger] 커스텀 trigger 렌더 함수
+ * @property {"date" | "date-time" | "time"} [props.mode="date"] Calendar layout mode. 선택 body는 date로 유지된다.
+ * @property {1 | 2} [props.columns=1] 동시 노출 달력 수
+ * @property {string | null} [props.value] 제어형 날짜 값
+ * @property {string | null} [props.defaultValue] 비제어 초기 날짜 값
+ * @property {(value: string | null) => void} [props.onChange] 값 변경 이벤트
+ * @property {(value: string | null) => void} [props.onValueChange] onChange alias
+ * @property {boolean} [props.readOnly] 읽기 전용 여부
+ * @property {boolean} [props.disabled] 비활성화 여부
+ * @property {CalendarDatePickerProps} [props.datePickerProps] Mantine DatePicker 옵션
+ * @property {string} [props.name] hidden input form name
+ * @property {string} [props.form] hidden input form id
+ * @property {UseFormRegisterReturn} [props.register] hidden input RHF register
+ * @property {boolean} [props.required] hidden input required 여부
+ * @property {InputCalendarHiddenInputProps} [props.hiddenInputProps] Template 고정값을 제외한 hidden input native props
+ * @property {string} [props.placeholder="YYYY-MM-DD"] placeholder
+ * @property {"primary" | "secondary" | "tertiary" | "table"} [props.priority="primary"] trigger input priority
+ * @property {"small" | "medium" | "large"} [props.size="medium"] trigger input size
+ * @property {"default" | "active" | "focused" | "success" | "error" | "disabled" | "loading"} [props.state="default"] trigger input state
+ * @property {boolean} [props.block=false] trigger width 100% 여부
+ * @property {"full" | "fit" | "fill" | "auto" | number | string} [props.width] trigger width preset 또는 custom width
+ * @property {(event: FocusEvent<HTMLInputElement>) => void} [props.onFocus] trigger focus 핸들러
+ * @property {(event: FocusEvent<HTMLInputElement>) => void} [props.onBlur] trigger blur 핸들러
+ * @property {ReactNode} [props.header] 패널 header 콘텐츠
+ * @property {ReactNode} [props.footer] 패널 footer 콘텐츠
+ * @property {InputCalendarTexts} [props.texts] 기본 Date 문구
+ * @property {unknown} [props.timePicker] 미구현 compatibility prop
+ * @property {boolean} [props.calendarOpened] calendar 열림 제어 상태
+ * @property {(open: boolean) => void} [props.onCalendarOpen] calendar 열림 변경 이벤트
+ * @property {(event: MouseEvent<Element>) => void} [props.onClick] trigger 클릭 핸들러
+ * @property {string} [props.id] trigger id
+ * @property {ReactNode} [props.trigger] 커스텀 trigger 슬롯
+ * @property {(props: InputCalendarTriggerRenderProps) => ReactNode} [props.renderTrigger] 커스텀 trigger 렌더 함수
+ * @desc 날짜 표시 trigger, Calendar panel과 YYYY-MM-DD hidden form storage를 조합한다.
  */
 const InputDateTemplate = forwardRef<HTMLDivElement, InputCalendarProps>(
   (
@@ -64,10 +77,18 @@ const InputDateTemplate = forwardRef<HTMLDivElement, InputCalendarProps>(
       disabled,
       datePickerProps,
       name,
+      form,
       register,
+      required,
+      hiddenInputProps,
       placeholder = "YYYY-MM-DD",
       priority = "primary",
+      size = "medium",
       state = "default",
+      block = false,
+      width,
+      onFocus,
+      onBlur,
       header,
       footer,
       texts,
@@ -88,7 +109,7 @@ const InputDateTemplate = forwardRef<HTMLDivElement, InputCalendarProps>(
      * Input Date Template; Calendar open 상태 변경 전달 함수.
      * 비제어 사용을 위해 내부 상태를 갱신하고, 제어형 사용을 위해 외부 owner에게 next open 값을 전달한다.
      * @param {boolean} nextOpen 다음 calendar open 상태
-     * @returns {void}
+     * @return {void}
      */
     const handleCalendarOpenChange = useCallback(
       (nextOpen: boolean) => {
@@ -113,7 +134,7 @@ const InputDateTemplate = forwardRef<HTMLDivElement, InputCalendarProps>(
      * Input Date Template; RHF hidden input 변경 이벤트 동기화 함수.
      * trigger 표시값과 form 저장값을 분리하기 위해 CalendarValue를 직렬화한 synthetic change를 register에 전달한다.
      * @param {CalendarValue} nextValue 다음 calendar 선택 값
-     * @returns {void}
+     * @return {void}
      */
     const emitRegisterChange = useCallback(
       (nextValue: CalendarValue) => {
@@ -140,7 +161,7 @@ const InputDateTemplate = forwardRef<HTMLDivElement, InputCalendarProps>(
      * Input Date Template; calendar value 갱신 함수.
      * 내부/제어형 value pipeline을 갱신한 뒤 RHF register 저장값을 같은 CalendarValue 기준으로 동기화한다.
      * @param {CalendarValue} nextValue 다음 calendar 선택 값
-     * @returns {void}
+     * @return {void}
      */
     const updateValue = useCallback(
       (nextValue: CalendarValue) => {
@@ -164,17 +185,33 @@ const InputDateTemplate = forwardRef<HTMLDivElement, InputCalendarProps>(
      * Input Date Template; trigger click 위임 함수.
      * Calendar Root의 PopOver toggle은 asChild trigger props가 담당하고, 이 함수는 소비자가 넘긴 trigger onClick만 보존한다.
      * @param {ReactMouseEvent<Element>} event trigger click event
-     * @returns {void}
+     * @return {void}
      */
     const handleTriggerClick = (event: ReactMouseEvent<Element>) => {
       triggerOnClick?.(event);
     };
 
+    /**
+     * Input Date Template; trigger blur와 RHF touched 상태 동기화 함수.
+     * 표시 trigger는 form name을 소유하지 않으므로 직렬화된 hidden input 값을 synthetic blur event로 전달한다.
+     * @utility
+     * @param {ReactFocusEvent<HTMLInputElement>} event trigger blur event
+     * @desc 소비자 blur callback과 hidden input register blur를 같은 날짜 값으로 동기화한다.
+     * @return {void}
+     */
+    const handleTriggerBlur = (event: ReactFocusEvent<HTMLInputElement>) => {
+      register?.onBlur({
+        target: { name: register.name, value: serializedCalendarValue },
+        type: "blur",
+      });
+      onBlur?.(event);
+    };
+
     /**
      * Input Date Template; Calendar Core change adapter 함수.
      * Calendar.Root의 onChange 값을 Template value/RHF 동기화 pipeline으로 연결한다.
      * @param {CalendarValue} nextValue 다음 calendar 선택 값
-     * @returns {void}
+     * @return {void}
      */
     const handleCalendarChange = (nextValue: CalendarValue) => {
       updateValue(nextValue);
@@ -201,7 +238,12 @@ const InputDateTemplate = forwardRef<HTMLDivElement, InputCalendarProps>(
       readOnly,
       onClick: handleTriggerClick,
       priority,
+      size,
       state,
+      block,
+      width,
+      onFocus,
+      onBlur: handleTriggerBlur,
     };
 
     const triggerNode = trigger ?? renderTrigger?.(triggerRenderProps) ?? (
@@ -214,6 +256,11 @@ const InputDateTemplate = forwardRef<HTMLDivElement, InputCalendarProps>(
         readOnly={readOnly}
         onClick={handleTriggerClick}
         priority={priority}
+        size={size}
+        block={block}
+        width={width}
+        onFocus={onFocus}
+        onBlur={handleTriggerBlur}
       />
     );
 
@@ -228,7 +275,7 @@ const InputDateTemplate = forwardRef<HTMLDivElement, InputCalendarProps>(
           readOnly={readOnly}
           value={calendarValue}
           onChange={handleCalendarChange}
-          // 변경: Mantine DatePicker는 valueFormat prop을 지원하지 않으므로 옵션을 그대로 전달한다.
+          // Mantine DatePicker는 valueFormat prop을 지원하지 않으므로 옵션을 그대로 전달한다.
           datePickerProps={datePickerProps}
           header={header}
           footer={footerContent}
@@ -239,11 +286,14 @@ const InputDateTemplate = forwardRef<HTMLDivElement, InputCalendarProps>(
         </Calendar.Root>
         {(register?.name || name) && (
           <input
-            // 변경: trigger 표시값과 저장값을 분리하기 위해 form 참여는 hidden input만 담당한다.
+            // trigger 표시값과 form 저장값을 분리해 hidden input만 form에 참여한다.
+            {...hiddenInputProps}
+            {...register}
             type="hidden"
             value={serializedCalendarValue}
             name={register?.name ?? name}
-            {...register}
+            form={form ?? hiddenInputProps?.form}
+            required={required ?? hiddenInputProps?.required}
           />
         )}
       </>

package/src/components/input/markup/date/Trigger.tsx

@@ -19,17 +19,23 @@ import type { InputCalendarTriggerViewProps } from "../../types";
  * 그 외 priority에서는 기존처럼 right 슬롯을 유지한다.
  * @component
  * @param {InputCalendarTriggerViewProps} props
- * @param {string} [props.className] trigger className
- * @param {string} [props.placeholder] placeholder
- * @param {string} [props.displayValue] 표시 문자열
- * @param {(event: MouseEvent<Element>) => void} [props.onClick] 클릭 핸들러
- * @param {boolean} [props.disabled] disabled 여부
- * @param {boolean} [props.readOnly] readOnly 여부
- * @param {"primary" | "secondary" | "tertiary" | "table"} [props.priority] trigger input priority
- * @param {"default" | "active" | "focused" | "success" | "error" | "disabled" | "loading"} [props.state] trigger input state
- * @param {string} [props.id] input id
- * @param {string} [props.name] form name
- * @param {UseFormRegisterReturn} [props.register] RHF register
+ * @property {string} [props.className] trigger className
+ * @property {string} [props.placeholder] placeholder
+ * @property {string} [props.displayValue] 표시 문자열
+ * @property {(event: MouseEvent<Element>) => void} [props.onClick] 클릭 핸들러
+ * @property {boolean} [props.disabled] disabled 여부
+ * @property {boolean} [props.readOnly] readOnly 여부
+ * @property {"primary" | "secondary" | "tertiary" | "table"} [props.priority] trigger input priority
+ * @property {"small" | "medium" | "large"} [props.size] trigger input size
+ * @property {"default" | "active" | "focused" | "success" | "error" | "disabled" | "loading"} [props.state] trigger input state
+ * @property {boolean} [props.block] trigger width 100% 여부
+ * @property {"full" | "fit" | "fill" | "auto" | number | string} [props.width] trigger width preset 또는 custom width
+ * @property {(event: FocusEvent<HTMLInputElement>) => void} [props.onFocus] trigger focus 핸들러
+ * @property {(event: FocusEvent<HTMLInputElement>) => void} [props.onBlur] trigger blur 핸들러
+ * @property {string} [props.id] input id
+ * @property {string} [props.name] form name
+ * @property {UseFormRegisterReturn} [props.register] RHF register
+ * @desc Date 값을 직접 편집하지 않고 Calendar 선택값을 표시하는 기본 trigger다.
  */
 const InputDateTrigger = forwardRef<
   HTMLInputElement,
@@ -44,7 +50,12 @@ const InputDateTrigger = forwardRef<
       disabled,
       readOnly,
       priority,
+      size,
       state,
+      block,
+      width,
+      onFocus,
+      onBlur,
       id,
       name,
       register,
@@ -90,7 +101,7 @@ const InputDateTrigger = forwardRef<
       triggerInputRef.current?.click();
     };
 
-    // 변경: Date trigger는 기본적으로 직접 타이핑을 막고, 달력 선택을 단일 입력 경로로 유지한다.
+    // Date trigger는 직접 타이핑을 막아 달력 선택을 단일 입력 경로로 유지한다.
     const shouldBlockTyping = !disabled && !readOnly;
 
     const handleKeyDown = (event: KeyboardEvent<HTMLInputElement>) => {
@@ -170,9 +181,14 @@ const InputDateTrigger = forwardRef<
         name={name ?? register?.name}
         register={register}
         priority={priority}
+        size={size}
         state={state}
+        block={block}
+        width={width}
         placeholder={placeholder}
         className={clsx("input-date-trigger-input", className)}
+        onFocus={onFocus}
+        onBlur={onBlur}
         onClick={handleInputClick}
         onKeyDown={handleKeyDown}
         onBeforeInput={handleBeforeInput}

package/src/components/input/markup/date/range/Template.tsx

@@ -1,6 +1,10 @@
 "use client";
 
-import type { ChangeEvent, MouseEvent as ReactMouseEvent } from "react";
+import type {
+  ChangeEvent,
+  FocusEvent as ReactFocusEvent,
+  MouseEvent as ReactMouseEvent,
+} from "react";
 import { forwardRef, useCallback, useMemo, useState } from "react";
 import { useUncontrolled } from "@mantine/hooks";
 import type { UseFormRegisterReturn } from "react-hook-form";
@@ -31,29 +35,39 @@ const INPUT_DATE_RANGE_TABLE_FORMAT = "YY-MM-DD";
  * form 저장은 start/end hidden input 2개로 분리한다.
  * @component
  * @param {InputCalendarRangeProps} props range date props
- * @param {CalendarRangeValue} [props.value] 제어형 range 값
- * @param {CalendarRangeValue} [props.defaultValue] 비제어 range 초기값
- * @param {CalendarRangeOnChange} [props.onChange] range 값 변경 이벤트
- * @param {CalendarRangeOnChange} [props.onValueChange] onChange alias
- * @param {boolean} [props.readOnly] 읽기 전용 여부
- * @param {boolean} [props.disabled] 비활성화 여부
- * @param {CalendarRangeDatePickerProps} [props.datePickerProps] Mantine range DatePicker 옵션
- * @param {string} [props.startName] 시작일 hidden input name
- * @param {string} [props.endName] 종료일 hidden input name
- * @param {UseFormRegisterReturn} [props.startRegister] 시작일 RHF register
- * @param {UseFormRegisterReturn} [props.endRegister] 종료일 RHF register
- * @param {string} [props.placeholder="YYYY-MM-DD ~ YYYY-MM-DD"] placeholder
- * @param {"primary" | "secondary" | "tertiary" | "table"} [props.priority="primary"] trigger input priority
- * @param {"default" | "active" | "focused" | "success" | "error" | "disabled" | "loading"} [props.state="default"] trigger input state
- * @param {ReactNode} [props.header] 패널 header 콘텐츠
- * @param {ReactNode} [props.footer] 패널 footer 콘텐츠
- * @param {InputCalendarTexts} [props.texts] 기본 Date 문구
- * @param {boolean} [props.calendarOpened] calendar 열림 제어 상태
- * @param {(open: boolean) => void} [props.onCalendarOpen] calendar 열림 변경 이벤트
- * @param {string} [props.id] trigger id
- * @param {ReactNode} [props.trigger] 커스텀 trigger 슬롯
- * @param {(props: InputCalendarTriggerRenderProps) => ReactNode} [props.renderTrigger] 커스텀 trigger 렌더 함수
- * @param {(event: MouseEvent<Element>) => void} [props.onClick] trigger 클릭 핸들러
+ * @property {[string | null, string | null]} [props.value] 제어형 range 값
+ * @property {[string | null, string | null]} [props.defaultValue] 비제어 range 초기값
+ * @property {(value: [string | null, string | null]) => void} [props.onChange] range 값 변경 이벤트
+ * @property {(value: [string | null, string | null]) => void} [props.onValueChange] onChange alias
+ * @property {boolean} [props.readOnly] 읽기 전용 여부
+ * @property {boolean} [props.disabled] 비활성화 여부
+ * @property {CalendarRangeDatePickerProps} [props.datePickerProps] Mantine range DatePicker 옵션
+ * @property {string} [props.startName] 시작일 hidden input name
+ * @property {string} [props.endName] 종료일 hidden input name
+ * @property {string} [props.form] start/end hidden input form id
+ * @property {UseFormRegisterReturn} [props.startRegister] 시작일 RHF register
+ * @property {UseFormRegisterReturn} [props.endRegister] 종료일 RHF register
+ * @property {boolean} [props.required] start/end hidden input required 여부
+ * @property {InputCalendarHiddenInputProps} [props.startHiddenInputProps] 시작일 hidden input native props
+ * @property {InputCalendarHiddenInputProps} [props.endHiddenInputProps] 종료일 hidden input native props
+ * @property {string} [props.placeholder="YYYY-MM-DD ~ YYYY-MM-DD"] placeholder
+ * @property {"primary" | "secondary" | "tertiary" | "table"} [props.priority="primary"] trigger input priority
+ * @property {"small" | "medium" | "large"} [props.size="medium"] trigger input size
+ * @property {"default" | "active" | "focused" | "success" | "error" | "disabled" | "loading"} [props.state="default"] trigger input state
+ * @property {boolean} [props.block=false] trigger width 100% 여부
+ * @property {"full" | "fit" | "fill" | "auto" | number | string} [props.width] trigger width preset 또는 custom width
+ * @property {(event: FocusEvent<HTMLInputElement>) => void} [props.onFocus] trigger focus 핸들러
+ * @property {(event: FocusEvent<HTMLInputElement>) => void} [props.onBlur] trigger blur 핸들러
+ * @property {ReactNode} [props.header] 패널 header 콘텐츠
+ * @property {ReactNode} [props.footer] 패널 footer 콘텐츠
+ * @property {InputCalendarTexts} [props.texts] 기본 Date 문구
+ * @property {boolean} [props.calendarOpened] calendar 열림 제어 상태
+ * @property {(open: boolean) => void} [props.onCalendarOpen] calendar 열림 변경 이벤트
+ * @property {string} [props.id] trigger id
+ * @property {ReactNode} [props.trigger] 커스텀 trigger 슬롯
+ * @property {(props: InputCalendarTriggerRenderProps) => ReactNode} [props.renderTrigger] 커스텀 trigger 렌더 함수
+ * @property {(event: MouseEvent<Element>) => void} [props.onClick] trigger 클릭 핸들러
+ * @desc 기간 표시 trigger, Calendar.Range panel과 start/end hidden form storage를 조합한다.
  * @example
  * <Input.Date.Range.Template
  *   startName="start_date"
@@ -74,11 +88,20 @@ const InputDateRangeTemplate = forwardRef<HTMLElement, InputCalendarRangeProps>(
       datePickerProps,
       startName,
       endName,
+      form,
       startRegister,
       endRegister,
+      required,
+      startHiddenInputProps,
+      endHiddenInputProps,
       placeholder = "YYYY-MM-DD ~ YYYY-MM-DD",
       priority = "primary",
+      size = "medium",
       state = "default",
+      block = false,
+      width,
+      onFocus,
+      onBlur,
       header,
       footer,
       texts,
@@ -99,7 +122,7 @@ const InputDateRangeTemplate = forwardRef<HTMLElement, InputCalendarRangeProps>(
      * Input Date Range Template; Calendar open 상태 변경 전달 함수.
      * 비제어 range calendar 상태를 갱신하고, 제어형 owner가 열림 상태를 조율할 수 있게 next open 값을 전달한다.
      * @param {boolean} nextOpen 다음 range calendar open 상태
-     * @returns {void}
+     * @return {void}
      */
     const handleCalendarOpenChange = useCallback(
       (nextOpen: boolean) => {
@@ -125,7 +148,7 @@ const InputDateRangeTemplate = forwardRef<HTMLElement, InputCalendarRangeProps>(
      * Input Date Range Template; RHF hidden input 변경 이벤트 동기화 함수.
      * range tuple의 start/end 값을 각각 직렬화해 startRegister/endRegister에 synthetic change로 전달한다.
      * @param {CalendarRangeValue} nextValue 다음 range calendar 선택 값
-     * @returns {void}
+     * @return {void}
      */
     const emitRegisterChange = useCallback(
       (nextValue: CalendarRangeValue) => {
@@ -134,7 +157,7 @@ const InputDateRangeTemplate = forwardRef<HTMLElement, InputCalendarRangeProps>(
          * start 또는 end register 한쪽에 직렬화 값을 전달한다.
          * @param {UseFormRegisterReturn | undefined} register RHF register 결과
          * @param {CalendarValue} nextCalendarValue 다음 start/end 선택 값
-         * @returns {void}
+         * @return {void}
          */
         const emit = (
           register: UseFormRegisterReturn | undefined,
@@ -169,7 +192,7 @@ const InputDateRangeTemplate = forwardRef<HTMLElement, InputCalendarRangeProps>(
      * Input Date Range Template; range value 갱신 함수.
      * Calendar.Range tuple 값을 갱신하고 start/end hidden input 저장값을 같은 tuple 기준으로 동기화한다.
      * @param {CalendarRangeValue} nextValue 다음 range calendar 선택 값
-     * @returns {void}
+     * @return {void}
      */
     const updateValue = useCallback(
       (nextValue: CalendarRangeValue) => {
@@ -194,17 +217,37 @@ const InputDateRangeTemplate = forwardRef<HTMLElement, InputCalendarRangeProps>(
      * Input Date Range Template; trigger click 위임 함수.
      * Calendar.Range Root의 PopOver toggle은 asChild trigger props가 담당하고, 이 함수는 소비자가 넘긴 trigger onClick만 보존한다.
      * @param {ReactMouseEvent<Element>} event trigger click event
-     * @returns {void}
+     * @return {void}
      */
     const handleTriggerClick = (event: ReactMouseEvent<Element>) => {
       triggerOnClick?.(event);
     };
 
+    /**
+     * Input Date Range Template; trigger blur와 start/end RHF touched 상태 동기화 함수.
+     * 표시 trigger는 저장 endpoint를 소유하지 않으므로 직렬화한 start/end 값을 각 register에 전달한다.
+     * @utility
+     * @param {ReactFocusEvent<HTMLInputElement>} event trigger blur event
+     * @desc 소비자 blur callback과 두 hidden input register blur를 같은 range 값으로 동기화한다.
+     * @return {void}
+     */
+    const handleTriggerBlur = (event: ReactFocusEvent<HTMLInputElement>) => {
+      startRegister?.onBlur({
+        target: { name: startRegister.name, value: serializedStartValue },
+        type: "blur",
+      });
+      endRegister?.onBlur({
+        target: { name: endRegister.name, value: serializedEndValue },
+        type: "blur",
+      });
+      onBlur?.(event);
+    };
+
     /**
      * Input Date Range Template; Calendar Range Core change adapter 함수.
      * Calendar.Range.Root의 onChange 값을 Template tuple/RHF 동기화 pipeline으로 연결한다.
      * @param {CalendarRangeValue} nextValue 다음 range calendar 선택 값
-     * @returns {void}
+     * @return {void}
      */
     const handleCalendarChange = (nextValue: CalendarRangeValue) => {
       updateValue(nextValue);
@@ -232,7 +275,7 @@ const InputDateRangeTemplate = forwardRef<HTMLElement, InputCalendarRangeProps>(
           >
             {texts?.clear ?? "삭제하기"}
           </InputDateClearButton>
-          {/* 변경: range footer는 삭제/적용을 같은 row에 두고 Apply 폭을 content 기준으로 줄인다. */}
+          {/* range footer는 삭제/적용을 같은 row에 두고 Apply 폭을 content 기준으로 줄인다. */}
           <InputDateApplyButton
             className="input-date-range-apply-button"
             disabled={disabled}
@@ -252,7 +295,12 @@ const InputDateRangeTemplate = forwardRef<HTMLElement, InputCalendarRangeProps>(
       readOnly,
       onClick: handleTriggerClick,
       priority,
+      size,
       state,
+      block,
+      width,
+      onFocus,
+      onBlur: handleTriggerBlur,
     };
 
     const triggerNode = trigger ?? renderTrigger?.(triggerRenderProps) ?? (
@@ -265,6 +313,11 @@ const InputDateRangeTemplate = forwardRef<HTMLElement, InputCalendarRangeProps>(
         readOnly={readOnly}
         onClick={handleTriggerClick}
         priority={priority}
+        size={size}
+        block={block}
+        width={width}
+        onFocus={onFocus}
+        onBlur={handleTriggerBlur}
       />
     );
 
@@ -287,20 +340,26 @@ const InputDateRangeTemplate = forwardRef<HTMLElement, InputCalendarRangeProps>(
         </Calendar.Range.Root>
         {(startRegister?.name || startName) && (
           <input
-            // 변경: range 시작일 저장값은 trigger 표시와 분리해 hidden input이 담당한다.
+            // range 시작일 저장값은 trigger 표시와 분리해 hidden input이 담당한다.
+            {...startHiddenInputProps}
+            {...startRegister}
             type="hidden"
             value={serializedStartValue}
             name={startRegister?.name ?? startName}
-            {...startRegister}
+            form={form ?? startHiddenInputProps?.form}
+            required={required ?? startHiddenInputProps?.required}
           />
         )}
         {(endRegister?.name || endName) && (
           <input
-            // 변경: range 종료일 저장값은 trigger 표시와 분리해 hidden input이 담당한다.
+            // range 종료일 저장값은 trigger 표시와 분리해 hidden input이 담당한다.
+            {...endHiddenInputProps}
+            {...endRegister}
             type="hidden"
             value={serializedEndValue}
             name={endRegister?.name ?? endName}
-            {...endRegister}
+            form={form ?? endHiddenInputProps?.form}
+            required={required ?? endHiddenInputProps?.required}
           />
         )}
       </>