@uniai-fe/uds-primitives 0.12.4 → 0.12.6

package/README.md

@@ -46,6 +46,23 @@ Button은 기존 priority 범위를 유지한다.
 `Input.Time.Template`과 standalone `TimePicker.Template`, `TimePickerUtils`도 root public
 entry에서 제공한다.
 
+Select와 Dropdown이 함께 사용하는 `SelectedValue`, `toSelectedValueKey`,
+`isSameSelectedValue`, `isSameSelectedValueList`, `normalizeSingleSelectedValue`,
+`normalizeSelectedValuesByMode`도 root public entry에서 제공한다.
+
+`Slot.Base`는 `as`로 렌더링 요소를 교체하거나, `asChild`로 단일 React element에
+className, style, event handler와 ref를 병합해 wrapper 없이 렌더링한다.
+
+```tsx
+import { Slot } from "@uniai-fe/uds-primitives";
+
+<Slot.Base asChild className="card-link">
+  <a href="/docs">문서 보기</a>
+</Slot.Base>;
+```
+
+`asChild`에서 anchor/button 같은 element 전용 prop은 child에 둔다.
+
 ## Styles
 
 CSS consumer는 Foundation 다음에 Primitives를 로드한다.

package/dist/styles.css

@@ -442,8 +442,8 @@
   --dropdown-text-weight-selected-xsmall: var(--dropdown-text-weight);
   --form-field-width: auto;
   --form-field-flex: 0 0 auto;
-  --form-field-gap-x: var(--spacing-gap-5, 12px);
-  --form-field-gap-y: var(--spacing-gap-3, 6px);
+  --form-field-gap-x: var(--spacing-gap-5);
+  --form-field-gap-y: var(--spacing-gap-3);
   --form-field-label-font-size: var(--font-label-small-size);
   --form-field-label-font-weight: 400;
   --form-field-label-line-height: var(--font-label-small-line-height);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniai-fe/uds-primitives",
-  "version": "0.12.4",
+  "version": "0.12.6",
   "description": "UNIAI Design System; Primitives Components Package",
   "type": "module",
   "private": false,
@@ -46,7 +46,7 @@
     "@mantine/core": ">=8 <9",
     "@mantine/dates": ">=8 <9",
     "@mantine/hooks": ">=8 <9",
-    "@uniai-fe/uds-foundation": "^0.4.8 || ^0.5.0",
+    "@uniai-fe/uds-foundation": "^0.4.8 || ^0.5.0 || ^0.6.0",
     "@uniai-fe/util-functions": "^0.3.0 || ^0.4.0",
     "react": ">=19 <20",
     "react-daum-postcode": "^4.0.0",
@@ -63,13 +63,13 @@
     "dayjs": "^1.11.20"
   },
   "dependencies": {
-    "@radix-ui/react-checkbox": "^1.3.8",
-    "@radix-ui/react-dropdown-menu": "^2.1.21",
-    "@radix-ui/react-popover": "^1.1.20",
-    "@radix-ui/react-radio-group": "^1.4.4",
-    "@radix-ui/react-tabs": "^1.1.18",
-    "@radix-ui/react-tooltip": "^1.2.13",
-    "@radix-ui/react-visually-hidden": "^1.2.8",
+    "@radix-ui/react-checkbox": "^1.3.11",
+    "@radix-ui/react-dropdown-menu": "^2.1.24",
+    "@radix-ui/react-popover": "^1.1.23",
+    "@radix-ui/react-radio-group": "^1.4.7",
+    "@radix-ui/react-tabs": "^1.1.21",
+    "@radix-ui/react-tooltip": "^1.2.16",
+    "@radix-ui/react-visually-hidden": "^1.2.11",
     "clsx": "^2.1.1",
     "dayjs": "^1.11.21",
     "react-daum-postcode": "^4.0.0"
@@ -80,18 +80,18 @@
     "@mantine/hooks": "^8.3.18",
     "@svgr/webpack": "^8.1.0",
     "@types/node": "^24.13.3",
-    "@types/react": "^19.2.17",
-    "@types/react-dom": "^19.2.3",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.4",
     "eslint": "^9.39.5",
     "prettier": "^3.9.6",
-    "react-hook-form": "^7.82.0",
-    "sass": "^1.101.3",
+    "react-hook-form": "^7.84.0",
+    "sass": "^1.101.7",
     "typescript": "6.0.3",
-    "@uniai-fe/eslint-config": "0.4.2",
-    "@uniai-fe/uds-foundation": "0.5.0",
     "@uniai-fe/next-devkit": "0.4.0",
-    "@uniai-fe/tsconfig": "0.2.0",
-    "@uniai-fe/util-functions": "0.4.3"
+    "@uniai-fe/eslint-config": "0.4.2",
+    "@uniai-fe/uds-foundation": "0.6.0",
+    "@uniai-fe/util-functions": "0.4.3",
+    "@uniai-fe/tsconfig": "0.2.0"
   },
   "scripts": {
     "check:pre-commit": "pnpm --dir ../../.. run check:pre-commit",

package/src/components/form/markup/Provider.tsx

@@ -1,7 +1,6 @@
 "use client";
 
 import { useEffect } from "react";
-// import { useEffect } from "react";
 import {
   FormProvider as ReactHookFormProvider,
   useForm,
@@ -11,7 +10,13 @@ import {
 } from "react-hook-form";
 
 /**
- * react-hook-form; context provider
+ * Form Component; react-hook-form context provider
+ * @component
+ * @param {object} props Form provider props
+ * @property {React.ReactNode} props.children provider 하위 콘텐츠
+ * @property {UseFormProps<FormDataType>} [props.options] useForm 초기 옵션
+ * @property {(params: UseFormReturn<FormDataType>) => void | undefined} [props.callback] 생성된 form methods 전달 callback
+ * @desc useForm methods를 생성하고 React Hook Form context로 제공하며 callback이 있으면 effect에서 methods를 전달한다.
  */
 export default function FormProvider<FormDataType extends FieldValues>({
   children,
@@ -27,7 +32,6 @@ export default function FormProvider<FormDataType extends FieldValues>({
 
   useEffect(() => {
     if (typeof callback === "undefined") return;
-    // if (typeof callback !== "undefined")
     callback(formMethods);
   }, [callback, formMethods]);
 

package/src/components/form/markup/form-field/Body.tsx

@@ -6,6 +6,7 @@ import clsx from "clsx";
  * @param {object} props
  * @property {string} [className]
  * @property {React.ReactNode} [children]
+ * @desc field control과 주요 콘텐츠를 body 영역에 렌더링한다.
  */
 export default function FormFieldBody({
   className,

package/src/components/form/markup/form-field/Container.tsx

@@ -13,10 +13,12 @@ import {
  * @component
  * @param {FormFieldContainerProps} props
  * @property {React.ElementType} [as] container 태그 지정 (default: <section />)
- * @property {FormFieldWidth} [width] form field 너비 옵션
+ * @property {"full" | "fit" | "fill" | "auto" | number | string} [width] form field 너비 옵션
+ * @property {"default" | "error"} [state] visual state
  * @property {string} [className]
  * @property {React.ReactNode} [children]
  * @property {React.HTMLAttributes<HTMLElement>} [containerProps] container 속성
+ * @desc width를 data attribute와 CSS variable로 변환하고 visual state를 노출하는 field wrapper다.
  */
 const FormFieldContainer = forwardRef<HTMLElement, FormFieldContainerProps>(
   (

package/src/components/form/markup/form-field/Footer.tsx

@@ -7,6 +7,7 @@ import type { FormFieldFooterProps } from "../../types";
  * @param {FormFieldFooterProps} props
  * @property {string} [className]
  * @property {React.ReactNode} [children]
+ * @desc helper 또는 action 콘텐츠와 footer DOM 속성을 렌더링한다.
  */
 export default function FormFieldFooter({
   className,

package/src/components/form/markup/form-field/Header.tsx

@@ -10,11 +10,13 @@ import { Slot } from "../../../slot";
  * @param {FormFieldHeaderProps} props
  * @property {string} [className]
  * @property {string} [label] 필드명
+ * @property {React.ReactNode} [labelJsx] label보다 우선하는 커스텀 label JSX
  * @property {React.ElementType} [labelAs] 필드 태그 지정 (default: <h5 />)
  * @property {string} [labelId] 필드 아이디 지정
  * @property {boolean} [required] 필수 여부
  * @property {React.ReactNode} [children] 추가 헤더 내용
  * @property {React.HTMLAttributes<HTMLElement>} [labelProps] 추가 라벨 속성
+ * @desc labelJsx를 우선 렌더링하고 문자열 label은 Slot.Text로 감싸 필수 표시와 함께 구성한다.
  */
 export default function FormFieldHeader({
   className,

package/src/components/form/markup/form-field/Template.tsx

@@ -17,10 +17,11 @@ import FormFieldContainer from "./Container";
  * @property {React.ReactNode} [footer] 푸터 내용
  * @property {FormFieldHeaderProps} [headerProps] 헤더 속성
  * @property {FormFieldFooterProps} [footerProps] 푸터 속성
- * @property {FormFieldWidth} [width] form field 너비 옵션
- * @property {FormFieldState} [state] visual state
+ * @property {"full" | "fit" | "fill" | "auto" | number | string} [width] form field 너비 옵션
+ * @property {"default" | "error"} [state] visual state
  * @property {React.HTMLAttributes<HTMLElement>} [containerProps] container 속성
  * @property {React.ReactNode} children
+ * @desc Header와 Body를 렌더링하고 footer가 있으면 Footer를 추가해 field layout을 구성한다.
  */
 const FormFieldTemplate = forwardRef<HTMLElement, FormFieldTemplateProps>(
   (

package/src/components/form/markup/form-field/index.tsx

@@ -6,7 +6,7 @@ import FormFieldTemplate from "./Template";
 
 /**
  * Form; form field 컴포넌트
- * @component
+ * @namespace Form.Field
  * @desc
  * - FormField.Container: Form 필드의 컨테이너 컴포넌트
  * - FormField.Header: Form 필드의 헤더 컴포넌트

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

@@ -3,6 +3,7 @@ import { FormField } from "./form-field";
 
 /**
  * Form; provider + field layout namespace
+ * @namespace Form
  * @desc
  * - `Form.Provider`: react-hook-form provider 래퍼다.
  * - `Form.Field.Container`: field 루트 wrapper다.

package/src/components/form/styles/form-field/variables.scss

@@ -2,8 +2,8 @@
   --form-field-width: auto;
   --form-field-flex: 0 0 auto;
 
-  --form-field-gap-x: var(--spacing-gap-5, 12px);
-  --form-field-gap-y: var(--spacing-gap-3, 6px);
+  --form-field-gap-x: var(--spacing-gap-5);
+  --form-field-gap-y: var(--spacing-gap-3);
 
   --form-field-label-font-size: var(--font-label-small-size);
   --form-field-label-font-weight: 400;

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

@@ -1,18 +1,14 @@
 import type { ElementType } from "react";
 
 /**
- * Form; field container width option
- * - full: 상위 영역을 100%로 채움
- * - fit: 콘텐츠 너비에 맞춤
- * - fill: flex-grow 1 분배
- * - auto: 기본 width(auto)
- * - number: px 단위 입력, rem으로 환산
- * - string: CSS width 문자열
+ * Form Types; field container width option
+ * @desc `"full" | "fit" | "fill" | "auto" | number | string`을 허용한다. number는 px 기준 rem으로 환산하고 preset이 아닌 string은 CSS width로 사용한다.
  */
 export type FormFieldWidth = "full" | "fit" | "fill" | "auto" | number | string;
 
 /**
- * Form; field state option
+ * Form Types; field state option
+ * @desc `"default" | "error"`를 허용하며 field helper의 visual state를 지정한다.
  */
 export type FormFieldState = "default" | "error";
 
@@ -26,6 +22,7 @@ export type FormFieldState = "default" | "error";
  * @property {React.HTMLAttributes<HTMLElement>} [labelProps] label 태그 속성
  * @property {boolean} [required] 필수 표시
  * @property {React.ReactNode} [children] description 등 추가 요소
+ * @desc field label, 필수 표시와 header 추가 콘텐츠를 구성한다.
  */
 export interface FormFieldHeaderProps extends React.HTMLAttributes<HTMLElement> {
   /**
@@ -33,7 +30,7 @@ export interface FormFieldHeaderProps extends React.HTMLAttributes<HTMLElement>
    */
   className?: string;
   /**
-   * label heading 태그
+   * label heading 태그를 지정한다.
    */
   labelAs?: ElementType;
   /**
@@ -41,11 +38,11 @@ export interface FormFieldHeaderProps extends React.HTMLAttributes<HTMLElement>
    */
   labelId?: string;
   /**
-   * 기본 label 텍스트
+   * 기본 label 텍스트를 지정한다.
    */
   label?: string;
   /**
-   * 커스텀 label JSX
+   * label보다 우선하는 커스텀 label JSX를 지정한다.
    */
   labelJsx?: React.ReactNode;
   /**
@@ -66,6 +63,7 @@ export interface FormFieldHeaderProps extends React.HTMLAttributes<HTMLElement>
  * Form.Field Footer props; `Footer.tsx`에서 helper/action 영역을 담당한다.
  * @property {string} [className] footer className
  * @property {React.ReactNode} [children] footer 내용
+ * @desc field helper 또는 action을 footer 영역에 렌더링한다.
  */
 export interface FormFieldFooterProps extends React.HTMLAttributes<HTMLElement> {
   /**
@@ -81,10 +79,12 @@ export interface FormFieldFooterProps extends React.HTMLAttributes<HTMLElement>
 /**
  * Form.Field Container props; `Container.tsx`에서 wrapper와 width 옵션을 제어한다.
  * @property {string} [className] container className
- * @property {React.ElementType} [as] container 태그
- * @property {FormFieldWidth} [width] width 옵션(full/fit/fill/auto/custom)
- * @property {FormFieldState} [state] visual state
+ * @property {ElementType} [as] container 태그
+ * @property {"full" | "fit" | "fill" | "auto" | number | string} [width] width preset 또는 custom width
+ * @property {"default" | "error"} [state] visual state
  * @property {React.ReactNode} children Body에 전달될 콘텐츠
+ * @see React.HTMLAttributes<HTMLElement>
+ * @desc semantic wrapper, width와 helper visual state를 제어한다.
  */
 export interface FormFieldContainerProps extends React.HTMLAttributes<HTMLElement> {
   /**
@@ -96,11 +96,11 @@ export interface FormFieldContainerProps extends React.HTMLAttributes<HTMLElemen
    */
   as?: ElementType;
   /**
-   * width 옵션
+   * `"full" | "fit" | "fill" | "auto" | number | string` width 옵션을 지정한다.
    */
   width?: FormFieldWidth;
   /**
-   * visual state
+   * `"default" | "error"` visual state를 지정한다.
    */
   state?: FormFieldState;
   /**
@@ -115,10 +115,12 @@ export interface FormFieldContainerProps extends React.HTMLAttributes<HTMLElemen
  * @property {FormFieldHeaderProps} [headerProps] Header props
  * @property {FormFieldFooterProps} [footerProps] Footer props
  * @property {string} [className] container className
- * @property {React.ElementType} [as] container 태그
- * @property {FormFieldWidth} [width] width 옵션(full/fit/fill/auto/custom)
- * @property {FormFieldState} [state] visual state
+ * @property {ElementType} [as] container 태그
+ * @property {"full" | "fit" | "fill" | "auto" | number | string} [width] width preset 또는 custom width
+ * @property {"default" | "error"} [state] visual state
  * @property {React.ReactNode} children Body에 전달될 콘텐츠
+ * @see FormFieldContainerProps
+ * @desc Container props를 상속하고 Header, Body와 선택적 Footer를 조합한다.
  */
 export interface FormFieldTemplateProps extends FormFieldContainerProps {
   /**

package/src/components/form/utils/form-field.ts

@@ -6,8 +6,9 @@ const WIDTH_PRESETS = new Set<FormFieldWidth>(["full", "fit", "fill", "auto"]);
 /**
  * Form.Field width attr helper; preset이면 그대로 반환하고 custom이면 "custom"/기본값은 "auto".
  * @function
- * @param {FormFieldWidth} [width]
- * @returns {string}
+ * @param {"full" | "fit" | "fill" | "auto" | number | string} [width] width preset 또는 custom width
+ * @desc Form.Field width를 data-width attribute 값으로 변환한다.
+ * @return {string} preset, "custom" 또는 "auto"
  */
 export const getFormFieldWidthAttr = (width?: FormFieldWidth): string => {
   if (typeof width === "string" && WIDTH_PRESETS.has(width)) {
@@ -24,8 +25,9 @@ export const getFormFieldWidthAttr = (width?: FormFieldWidth): string => {
 /**
  * Form.Field width style helper; number/string custom 값을 CSS width 문자열로 환산한다.
  * @function
- * @param {FormFieldWidth} [width]
- * @returns {string | undefined}
+ * @param {"full" | "fit" | "fill" | "auto" | number | string} [width] width preset 또는 custom width
+ * @desc 유한한 number는 rem으로 환산하고 preset이 아닌 string은 그대로 반환한다.
+ * @return {string | undefined} custom CSS width 또는 preset/미지정일 때 undefined
  */
 export const getFormFieldWidthValue = (
   width?: FormFieldWidth,

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}