@uniai-fe/uds-primitives 0.12.4 → 0.12.6

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}
           />
         )}
       </>

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

@@ -46,6 +46,14 @@ const defaultClockIcon = (
   </svg>
 );
 
+/**
+ * Input Time Utility; 24시간 저장 문자열을 trigger draft로 변환한다.
+ * @utility
+ * @param {string} value `HH:mm` 또는 `HH:mm:ss` 저장값
+ * @param {"12h" | "24h"} format 표시 형식
+ * @desc 유효하지 않거나 빈 저장값은 빈 field와 `am` period로 초기화한다.
+ * @return {InputTimeDraft} 표시용 field 문자열과 period
+ */
 const getInputTimeDraft = (
   value: string,
   format: "12h" | "24h",
@@ -73,11 +81,43 @@ const getInputTimeDraft = (
  * 저장값은 24시간 `HH:mm` 또는 `HH:mm:ss` 문자열로 유지한다.
  * @component
  * @param {InputTimeTemplateProps} props
- * @param {"primary" | "secondary" | "tertiary" | "table"} [props.priority="primary"] input priority
- * @param {"small" | "medium" | "large"} [props.size="medium"] input size
- * @param {"12h" | "24h"} [props.format="24h"] 표시 형식
- * @param {boolean} [props.withSeconds=false] 초 field 노출 여부
- * @returns {ReactNode} 시간 입력과 선택 panel
+ * @property {string} [props.value] 제어형 24시간 저장값
+ * @property {string} [props.defaultValue] 비제어 초기 24시간 저장값
+ * @property {(value: string) => void} [props.onChange] 값 변경 핸들러
+ * @property {(value: string) => void} [props.onValueChange] 값 변경 별칭
+ * @property {string} [props.name] hidden input form name
+ * @property {string} [props.form] hidden input form id
+ * @property {UseFormRegisterReturn} [props.register] hidden input react-hook-form register 결과
+ * @property {"primary" | "secondary" | "tertiary" | "table"} [props.priority="primary"] input priority
+ * @property {"small" | "medium" | "large"} [props.size="medium"] input size
+ * @property {"default" | "active" | "focused" | "success" | "error" | "disabled" | "loading"} [props.state="default"] input state
+ * @property {boolean} [props.block=false] width 100% 여부
+ * @property {"full" | "fit" | "fill" | "auto" | number | string} [props.width] width preset 또는 custom width
+ * @property {string} [props.className] root className
+ * @property {boolean} [props.disabled] disabled 여부
+ * @property {boolean} [props.readOnly=false] readOnly 여부
+ * @property {boolean} [props.required] hidden input required 여부
+ * @property {string} [props.id] trigger root id
+ * @property {"12h" | "24h"} [props.format="24h"] 표시 형식
+ * @property {boolean} [props.withSeconds=false] 초 field 노출 여부
+ * @property {boolean} [props.clearable=true] 삭제 action 노출 여부
+ * @property {number} [props.hoursStep=1] 시 증감 단위
+ * @property {number} [props.minutesStep=5] 분 증감 단위
+ * @property {number} [props.secondsStep=1] 초 증감 단위
+ * @property {ReactNode} [props.icon] clock icon override
+ * @property {"left" | "right"} [props.iconPosition] clock icon 위치
+ * @property {string} [props.iconLabel="시간 선택"] clock icon 접근성 라벨
+ * @property {InputTimeHiddenInputProps} [props.hiddenInputProps] hidden input native props
+ * @property {string} [props.hoursInputLabel="시"] 시 input 접근성 라벨
+ * @property {string} [props.minutesInputLabel="분"] 분 input 접근성 라벨
+ * @property {string} [props.secondsInputLabel="초"] 초 input 접근성 라벨
+ * @property {string} [props.amPmInputLabel="오전 또는 오후"] 오전·오후 input 접근성 라벨
+ * @property {string} [props.hoursPlaceholder="HH"] 시 placeholder
+ * @property {string} [props.minutesPlaceholder="MM"] 분 placeholder
+ * @property {string} [props.secondsPlaceholder="SS"] 초 placeholder
+ * @property {(event: FocusEvent<HTMLInputElement>) => void} [props.onFocus] field focus 핸들러
+ * @property {(event: FocusEvent<HTMLDivElement>) => void} [props.onBlur] trigger root blur 핸들러
+ * @desc 표시 draft를 편집·정규화하고 TimePicker 선택값과 hidden input 저장값을 동기화한다.
  */
 const InputTimeTemplate = forwardRef<HTMLDivElement, InputTimeTemplateProps>(
   (
@@ -136,6 +176,7 @@ const InputTimeTemplate = forwardRef<HTMLDivElement, InputTimeTemplateProps>(
       getInputTimeDraft(value ?? defaultValue ?? "", format),
     );
 
+    // 외부 value 또는 표시 형식 변경 시 저장값을 기준으로 편집 draft를 다시 계산한다.
     useEffect(() => {
       setDraft(getInputTimeDraft(timeValue, format));
     }, [format, timeValue]);
@@ -165,6 +206,13 @@ const InputTimeTemplate = forwardRef<HTMLDivElement, InputTimeTemplateProps>(
       ? { width: widthValue }
       : undefined;
 
+    /**
+     * Input Time Utility; RHF hidden input 변경 이벤트 동기화 함수.
+     * @utility
+     * @param {string} nextValue 다음 24시간 저장값
+     * @desc 표시 field와 분리된 hidden input register에 synthetic change를 전달한다.
+     * @return {void}
+     */
     const emitRegisterChange = useCallback(
       (nextValue: string) => {
         register?.onChange({
@@ -175,6 +223,13 @@ const InputTimeTemplate = forwardRef<HTMLDivElement, InputTimeTemplateProps>(
       [register],
     );
 
+    /**
+     * Input Time Utility; 시간 저장값 갱신 함수.
+     * @utility
+     * @param {string} nextValue 다음 24시간 저장값
+     * @desc draft, controlled/uncontrolled value와 RHF 저장값을 같은 값으로 동기화한다.
+     * @return {void}
+     */
     const updateValue = useCallback(
       (nextValue: string) => {
         setDraft(getInputTimeDraft(nextValue, format));
@@ -184,6 +239,13 @@ const InputTimeTemplate = forwardRef<HTMLDivElement, InputTimeTemplateProps>(
       [emitRegisterChange, format, setTimeValue],
     );
 
+    /**
+     * Input Time Utility; 완성된 trigger draft를 저장값으로 commit한다.
+     * @utility
+     * @param {InputTimeDraft} nextDraft 다음 field 문자열과 period
+     * @desc 필요한 field가 두 자리이고 범위가 유효할 때만 24시간 문자열로 직렬화한다.
+     * @return {void}
+     */
     const commitDraft = useCallback(
       (nextDraft: InputTimeDraft) => {
         const { hours, minutes, seconds } = nextDraft.fields;
@@ -224,6 +286,14 @@ const InputTimeTemplate = forwardRef<HTMLDivElement, InputTimeTemplateProps>(
       [format, updateValue, withSeconds],
     );
 
+    /**
+     * Input Time Utility; field 입력 정규화 함수.
+     * @utility
+     * @param {"hours" | "minutes" | "seconds"} unit 변경 단위
+     * @param {string} rawValue 입력 문자열
+     * @desc 숫자 두 자리만 draft에 남기고 완성된 값은 즉시 commit한다.
+     * @return {void}
+     */
     const handleFieldChange = (unit: TimePickerUnit, rawValue: string) => {
       const nextValue = rawValue.replace(/\D/g, "").slice(0, 2);
       const nextDraft = {
@@ -243,6 +313,13 @@ const InputTimeTemplate = forwardRef<HTMLDivElement, InputTimeTemplateProps>(
       onFocus?.(event);
     };
 
+    /**
+     * Input Time Utility; field blur 정규화 함수.
+     * @utility
+     * @param {"hours" | "minutes" | "seconds"} unit blur 단위
+     * @desc 빈 field는 유지하고 입력값은 단위·표시 형식 범위로 clamp한 뒤 commit한다.
+     * @return {void}
+     */
     const handleFieldBlur = (unit: TimePickerUnit) => {
       const currentValue = draft.fields[unit];
       if (!currentValue) {
@@ -262,6 +339,14 @@ const InputTimeTemplate = forwardRef<HTMLDivElement, InputTimeTemplateProps>(
       commitDraft(nextDraft);
     };
 
+    /**
+     * Input Time Utility; field 방향키 증감 함수.
+     * @utility
+     * @param {"hours" | "minutes" | "seconds"} unit 활성 단위
+     * @param {KeyboardEvent<HTMLInputElement>} event field keyboard event
+     * @desc 위·아래 방향키만 단위별 step으로 순환 증감한다.
+     * @return {void}
+     */
     const handleFieldKeyDown = (
       unit: TimePickerUnit,
       event: KeyboardEvent<HTMLInputElement>,
@@ -280,6 +365,13 @@ const InputTimeTemplate = forwardRef<HTMLDivElement, InputTimeTemplateProps>(
       updateValue(stepTimeValue(timeValue, unit, amount * step, withSeconds));
     };
 
+    /**
+     * Input Time Utility; trigger stepper 증감 함수.
+     * @utility
+     * @param {1 | -1} amount 증감 방향
+     * @desc focus된 단위가 있을 때만 해당 단위 step으로 저장값을 순환 증감한다.
+     * @return {void}
+     */
     const handleStep = (amount: 1 | -1) => {
       if (!activeUnit) {
         return;
@@ -300,6 +392,13 @@ const InputTimeTemplate = forwardRef<HTMLDivElement, InputTimeTemplateProps>(
       updateValue(nextValue);
     };
 
+    /**
+     * Input Time Utility; TimePicker 시 선택 반영 함수.
+     * @utility
+     * @param {number} hours 선택한 표시 시
+     * @desc 12시간제는 현재 draft period를 결합해 24시간 저장 시로 변환한다.
+     * @return {void}
+     */
     const handleHourSelect = (hours: number) => {
       const parts = parseTimeValue(timeValue) ?? {
         hours: 0,
@@ -324,6 +423,13 @@ const InputTimeTemplate = forwardRef<HTMLDivElement, InputTimeTemplateProps>(
       updateValue(serializeTimeValue({ ...parts, minutes }, withSeconds));
     };
 
+    /**
+     * Input Time Utility; trigger root blur와 RHF touched 상태 동기화 함수.
+     * @utility
+     * @param {FocusEvent<HTMLDivElement>} event trigger root blur event
+     * @desc root 내부 focus 이동은 무시하고 외부로 벗어날 때만 register와 소비자 callback을 호출한다.
+     * @return {void}
+     */
     const handleRootBlur = (event: FocusEvent<HTMLDivElement>) => {
       if (
         event.relatedTarget instanceof Node &&
@@ -339,6 +445,13 @@ const InputTimeTemplate = forwardRef<HTMLDivElement, InputTimeTemplateProps>(
       onBlur?.(event);
     };
 
+    /**
+     * Input Time Utility; TimePicker panel open 상태 갱신 함수.
+     * @utility
+     * @param {boolean} nextOpen 다음 open 상태
+     * @desc disabled 또는 readOnly 상태에서는 panel을 열지 않는다.
+     * @return {void}
+     */
     const handleOpenChange = (nextOpen: boolean) => {
       setIsOpen(nextOpen && !isDisabled && !readOnly);
     };

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

@@ -12,7 +12,34 @@ import type { InputTimeTriggerProps } from "../../types";
  * Input Time trigger; 시·분·초 field와 focus 단위 stepper를 렌더한다.
  * @component
  * @param {InputTimeTriggerProps} props
- * @returns {ReactNode} 시간 입력 trigger
+ * @property {InputTimeTriggerFields} props.fields 시·분·초 입력값
+ * @property {"am" | "pm"} props.period 오전·오후 구분
+ * @property {"hours" | "minutes" | "seconds" | null} props.activeUnit 현재 활성 단위
+ * @property {"primary" | "secondary" | "tertiary" | "table"} props.priority input priority
+ * @property {"small" | "medium" | "large"} props.size input size
+ * @property {"default" | "active" | "focused" | "success" | "error" | "disabled" | "loading"} props.state input state
+ * @property {"12h" | "24h"} props.format 표시 형식
+ * @property {boolean} props.withSeconds 초 field 노출 여부
+ * @property {boolean} props.disabled 비활성화 여부
+ * @property {boolean} props.readOnly 읽기 전용 여부
+ * @property {ReactNode} props.icon clock icon
+ * @property {"left" | "right"} props.iconPosition clock icon 위치
+ * @property {string} props.iconLabel clock icon 접근성 라벨
+ * @property {string} props.hoursInputLabel 시 input 접근성 라벨
+ * @property {string} props.minutesInputLabel 분 input 접근성 라벨
+ * @property {string} props.secondsInputLabel 초 input 접근성 라벨
+ * @property {string} props.amPmInputLabel 오전·오후 input 접근성 라벨
+ * @property {string} props.hoursPlaceholder 시 placeholder
+ * @property {string} props.minutesPlaceholder 분 placeholder
+ * @property {string} props.secondsPlaceholder 초 placeholder
+ * @property {(unit: "hours" | "minutes" | "seconds", value: string) => void} props.onFieldChange field 변경 핸들러
+ * @property {(unit: "hours" | "minutes" | "seconds", event: FocusEvent<HTMLInputElement>) => void} props.onFieldFocus field focus 핸들러
+ * @property {(unit: "hours" | "minutes" | "seconds") => void} props.onFieldBlur field blur 핸들러
+ * @property {(unit: "hours" | "minutes" | "seconds", event: KeyboardEvent<HTMLInputElement>) => void} props.onFieldKeyDown field keyboard 핸들러
+ * @property {(period: "am" | "pm") => void} props.onPeriodChange 오전·오후 변경 핸들러
+ * @property {(amount: 1 | -1) => void} props.onStep 활성 단위 증감 핸들러
+ * @property {(event: FocusEvent<HTMLDivElement>) => void} props.onRootBlur root blur 핸들러
+ * @desc field별 입력과 focus를 Template의 draft·commit pipeline으로 전달한다.
  */
 const InputTimeTrigger = forwardRef<HTMLDivElement, InputTimeTriggerProps>(
   (
@@ -73,7 +100,13 @@ const InputTimeTrigger = forwardRef<HTMLDivElement, InputTimeTriggerProps>(
     const onClockClick = () => {
       hoursRef.current?.focus();
     };
-    // PopOver.Trigger가 주입한 click은 clock button에서만 popup toggle로 위임한다.
+    /**
+     * Input Time Utility; PopOver trigger click 위임 함수.
+     * @utility
+     * @param {MouseEvent<HTMLDivElement>} event trigger root click event
+     * @desc field 편집 click은 panel을 toggle하지 않고 clock button click만 PopOver에 전달한다.
+     * @return {void}
+     */
     const onRootClick = (event: MouseEvent<HTMLDivElement>) => {
       if (
         event.target instanceof Element &&