@uniai-fe/uds-primitives 0.7.4 → 0.7.5

package/package.json

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

package/src/components/calendar/markup/Root.tsx

@@ -1,9 +1,13 @@
 "use client";
 
 import clsx from "clsx";
-import { forwardRef } from "react";
+import { forwardRef, useId } from "react";
 import { PopOver } from "../../pop-over";
 import type { CalendarRootProps } from "../types";
+import {
+  getCalendarTriggerClassName,
+  isOwnCalendarTriggerTarget,
+} from "../utils";
 import CalendarContainer from "./layout/Container";
 import CalendarCore from "./Core";
 
@@ -62,6 +66,8 @@ const CalendarRoot = forwardRef<HTMLElement, CalendarRootProps>(
   ) => {
     // disabled/readOnly 상태에서는 PopOver 토글을 막는다.
     const isInteractive = !disabled && !readOnly;
+    const triggerId = useId();
+    const triggerClassName = getCalendarTriggerClassName(triggerId);
 
     const calendarNode = (
       <CalendarContainer
@@ -99,7 +105,8 @@ const CalendarRoot = forwardRef<HTMLElement, CalendarRootProps>(
         <PopOver.Trigger
           asChild
           disabled={!isInteractive}
-          className={clsx("calendar-trigger", className)}
+          className={clsx("calendar-trigger", triggerClassName, className)}
+          data-calendar-trigger-id={triggerId}
         >
           {/* children은 asChild 계약상 단일 element여야 하며, 해당 요소가 props를 DOM으로 전달해야 한다. */}
           {children}
@@ -113,9 +120,8 @@ const CalendarRoot = forwardRef<HTMLElement, CalendarRootProps>(
           withPortal={withPortal}
           portalContainer={portalContainer}
           onInteractOutside={event => {
-            // 변경 설명: trigger 클릭은 outside dismiss에서 제외해 close 후 즉시 reopen 경합을 방지한다.
-            const nextTarget = event.target as HTMLElement | null;
-            if (nextTarget?.closest(".calendar-trigger")) {
+            // 자기 trigger 클릭만 outside dismiss에서 제외해 close 후 즉시 reopen 경합을 방지한다.
+            if (isOwnCalendarTriggerTarget(event.target, triggerId)) {
               event.preventDefault();
             }
           }}

package/src/components/calendar/markup/range/Root.tsx

@@ -1,9 +1,13 @@
 "use client";
 
 import clsx from "clsx";
-import { forwardRef } from "react";
+import { forwardRef, useId } from "react";
 import { PopOver } from "../../../pop-over";
 import type { CalendarRangeRootProps } from "../../types";
+import {
+  getCalendarTriggerClassName,
+  isOwnCalendarTriggerTarget,
+} from "../../utils";
 import CalendarContainer from "../layout/Container";
 import CalendarRangeCore from "./Core";
 
@@ -60,6 +64,8 @@ const CalendarRangeRoot = forwardRef<HTMLElement, CalendarRangeRootProps>(
   ) => {
     // disabled/readOnly 상태에서는 range PopOver 토글을 막는다.
     const isInteractive = !disabled && !readOnly;
+    const triggerId = useId();
+    const triggerClassName = getCalendarTriggerClassName(triggerId);
 
     const calendarNode = (
       <CalendarContainer
@@ -97,7 +103,8 @@ const CalendarRangeRoot = forwardRef<HTMLElement, CalendarRangeRootProps>(
         <PopOver.Trigger
           asChild
           disabled={!isInteractive}
-          className={clsx("calendar-trigger", className)}
+          className={clsx("calendar-trigger", triggerClassName, className)}
+          data-calendar-trigger-id={triggerId}
         >
           {/* children은 asChild 계약상 단일 element여야 하며, 해당 요소가 props를 DOM으로 전달해야 한다. */}
           {children}
@@ -111,9 +118,8 @@ const CalendarRangeRoot = forwardRef<HTMLElement, CalendarRangeRootProps>(
           withPortal={withPortal}
           portalContainer={portalContainer}
           onInteractOutside={event => {
-            // 변경 설명: trigger 클릭은 outside dismiss에서 제외해 close 후 즉시 reopen 경합을 방지한다.
-            const nextTarget = event.target as HTMLElement | null;
-            if (nextTarget?.closest(".calendar-trigger")) {
+            // 자기 trigger 클릭만 outside dismiss에서 제외해 close 후 즉시 reopen 경합을 방지한다.
+            if (isOwnCalendarTriggerTarget(event.target, triggerId)) {
               event.preventDefault();
             }
           }}

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

@@ -1 +1,2 @@
+export * from "./trigger";
 export * from "./value-mapper";

package/src/components/calendar/utils/trigger.ts

@@ -0,0 +1,26 @@
+/**
+ * Calendar Utils; Trigger DOM 식별 className 생성 함수.
+ * React rendering key가 아니라 Radix PopOver trigger DOM을 식별하기 위한 className을 만든다.
+ * @param {string} triggerId React useId로 생성한 Calendar Root 인스턴스 식별자
+ * @returns {string} CSS selector에 사용할 수 있는 trigger className
+ */
+export const getCalendarTriggerClassName = (triggerId: string): string =>
+  `calendar-trigger-${triggerId.replaceAll(":", "")}`;
+
+/**
+ * Calendar Utils; 자기 trigger outside interaction 판별 함수.
+ * PopOver content 밖 interaction 중 현재 Calendar Root의 trigger 클릭만 dismiss 예외로 처리한다.
+ * @param {EventTarget | null} target PopOver outside interaction target
+ * @param {string} triggerId React useId로 생성한 Calendar Root 인스턴스 식별자
+ * @returns {boolean} target이 현재 Calendar Root의 trigger 내부이면 true
+ */
+export const isOwnCalendarTriggerTarget = (
+  target: EventTarget | null,
+  triggerId: string,
+): boolean => {
+  if (!(target instanceof HTMLElement)) {
+    return false;
+  }
+
+  return Boolean(target.closest(`[data-calendar-trigger-id="${triggerId}"]`));
+};

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

@@ -45,6 +45,7 @@ const INPUT_DATE_TABLE_FORMAT = "YY-MM-DD";
  * @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 슬롯
@@ -71,6 +72,7 @@ const InputDateTemplate = forwardRef<HTMLDivElement, InputCalendarProps>(
       footer,
       texts,
       calendarOpened,
+      onCalendarOpen,
       onClick: triggerOnClick,
       id,
       trigger,
@@ -82,6 +84,20 @@ const InputDateTemplate = forwardRef<HTMLDivElement, InputCalendarProps>(
     const [internalCalendarOpen, setInternalCalendarOpen] = useState(false);
     const resolvedCalendarOpen = calendarOpened ?? internalCalendarOpen;
 
+    /**
+     * Input Date Template; Calendar open 상태 변경 전달 함수.
+     * 비제어 사용을 위해 내부 상태를 갱신하고, 제어형 사용을 위해 외부 owner에게 next open 값을 전달한다.
+     * @param {boolean} nextOpen 다음 calendar open 상태
+     * @returns {void}
+     */
+    const handleCalendarOpenChange = useCallback(
+      (nextOpen: boolean) => {
+        setInternalCalendarOpen(nextOpen);
+        onCalendarOpen?.(nextOpen);
+      },
+      [onCalendarOpen],
+    );
+
     // useUncontrolled로 제어형/비제어 값을 모두 허용한다.
     const [calendarValue, setCalendarValue] = useUncontrolled<CalendarValue>({
       value,
@@ -93,7 +109,12 @@ const InputDateTemplate = forwardRef<HTMLDivElement, InputCalendarProps>(
       },
     });
 
-    // react-hook-form register onChange를 수동 호출해 값 직렬화를 맞춘다.
+    /**
+     * Input Date Template; RHF hidden input 변경 이벤트 동기화 함수.
+     * trigger 표시값과 form 저장값을 분리하기 위해 CalendarValue를 직렬화한 synthetic change를 register에 전달한다.
+     * @param {CalendarValue} nextValue 다음 calendar 선택 값
+     * @returns {void}
+     */
     const emitRegisterChange = useCallback(
       (nextValue: CalendarValue) => {
         if (!register?.onChange) {
@@ -115,6 +136,12 @@ const InputDateTemplate = forwardRef<HTMLDivElement, InputCalendarProps>(
       [register],
     );
 
+    /**
+     * Input Date Template; calendar value 갱신 함수.
+     * 내부/제어형 value pipeline을 갱신한 뒤 RHF register 저장값을 같은 CalendarValue 기준으로 동기화한다.
+     * @param {CalendarValue} nextValue 다음 calendar 선택 값
+     * @returns {void}
+     */
     const updateValue = useCallback(
       (nextValue: CalendarValue) => {
         setCalendarValue(nextValue);
@@ -133,10 +160,22 @@ const InputDateTemplate = forwardRef<HTMLDivElement, InputCalendarProps>(
     );
     const serializedCalendarValue = serializeCalendarValue(calendarValue);
 
+    /**
+     * Input Date Template; trigger click 위임 함수.
+     * Calendar Root의 PopOver toggle은 asChild trigger props가 담당하고, 이 함수는 소비자가 넘긴 trigger onClick만 보존한다.
+     * @param {ReactMouseEvent<Element>} event trigger click event
+     * @returns {void}
+     */
     const handleTriggerClick = (event: ReactMouseEvent<Element>) => {
       triggerOnClick?.(event);
     };
 
+    /**
+     * Input Date Template; Calendar Core change adapter 함수.
+     * Calendar.Root의 onChange 값을 Template value/RHF 동기화 pipeline으로 연결한다.
+     * @param {CalendarValue} nextValue 다음 calendar 선택 값
+     * @returns {void}
+     */
     const handleCalendarChange = (nextValue: CalendarValue) => {
       updateValue(nextValue);
     };
@@ -147,8 +186,8 @@ const InputDateTemplate = forwardRef<HTMLDivElement, InputCalendarProps>(
         disabled={disabled}
         onClear={() => updateValue(createEmptyValue())}
         onToday={() => updateValue(getTodayValue())}
-        // 변경: Apply 버튼 클릭 시 calendar를 닫는다.
-        onApply={() => setInternalCalendarOpen(false)}
+        // Apply 버튼 클릭 시 calendar를 닫는다.
+        onApply={() => handleCalendarOpenChange(false)}
         texts={texts}
       />
     );
@@ -194,7 +233,7 @@ const InputDateTemplate = forwardRef<HTMLDivElement, InputCalendarProps>(
           header={header}
           footer={footerContent}
           open={resolvedCalendarOpen}
-          onOpenChange={setInternalCalendarOpen}
+          onOpenChange={handleCalendarOpenChange}
         >
           {triggerNode}
         </Calendar.Root>

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

@@ -3,6 +3,7 @@
 import type { ChangeEvent, MouseEvent as ReactMouseEvent } from "react";
 import { forwardRef, useCallback, useMemo, useState } from "react";
 import { useUncontrolled } from "@mantine/hooks";
+import type { UseFormRegisterReturn } from "react-hook-form";
 import { Calendar } from "../../../../calendar";
 import type {
   InputCalendarRangeProps,
@@ -48,6 +49,7 @@ const INPUT_DATE_RANGE_TABLE_FORMAT = "YY-MM-DD";
  * @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 렌더 함수
@@ -81,6 +83,7 @@ const InputDateRangeTemplate = forwardRef<HTMLElement, InputCalendarRangeProps>(
       footer,
       texts,
       calendarOpened,
+      onCalendarOpen,
       onClick: triggerOnClick,
       id,
       trigger,
@@ -92,6 +95,20 @@ const InputDateRangeTemplate = forwardRef<HTMLElement, InputCalendarRangeProps>(
     const [internalCalendarOpen, setInternalCalendarOpen] = useState(false);
     const resolvedCalendarOpen = calendarOpened ?? internalCalendarOpen;
 
+    /**
+     * Input Date Range Template; Calendar open 상태 변경 전달 함수.
+     * 비제어 range calendar 상태를 갱신하고, 제어형 owner가 열림 상태를 조율할 수 있게 next open 값을 전달한다.
+     * @param {boolean} nextOpen 다음 range calendar open 상태
+     * @returns {void}
+     */
+    const handleCalendarOpenChange = useCallback(
+      (nextOpen: boolean) => {
+        setInternalCalendarOpen(nextOpen);
+        onCalendarOpen?.(nextOpen);
+      },
+      [onCalendarOpen],
+    );
+
     // Calendar.Range tuple 계약을 그대로 유지하며 제어형/비제어 값을 모두 허용한다.
     const [calendarValue, setCalendarValue] =
       useUncontrolled<CalendarRangeValue>({
@@ -104,11 +121,23 @@ const InputDateRangeTemplate = forwardRef<HTMLElement, InputCalendarRangeProps>(
         },
       });
 
-    // react-hook-form register onChange를 start/end 각각 호출해 hidden input 저장값을 맞춘다.
+    /**
+     * Input Date Range Template; RHF hidden input 변경 이벤트 동기화 함수.
+     * range tuple의 start/end 값을 각각 직렬화해 startRegister/endRegister에 synthetic change로 전달한다.
+     * @param {CalendarRangeValue} nextValue 다음 range calendar 선택 값
+     * @returns {void}
+     */
     const emitRegisterChange = useCallback(
       (nextValue: CalendarRangeValue) => {
+        /**
+         * Input Date Range Template; 단일 range endpoint register 동기화 함수.
+         * start 또는 end register 한쪽에 직렬화 값을 전달한다.
+         * @param {UseFormRegisterReturn | undefined} register RHF register 결과
+         * @param {CalendarValue} nextCalendarValue 다음 start/end 선택 값
+         * @returns {void}
+         */
         const emit = (
-          register: typeof startRegister | typeof endRegister | undefined,
+          register: UseFormRegisterReturn | undefined,
           nextCalendarValue: CalendarValue,
         ) => {
           if (!register?.onChange) {
@@ -136,6 +165,12 @@ const InputDateRangeTemplate = forwardRef<HTMLElement, InputCalendarRangeProps>(
       [endRegister, startRegister],
     );
 
+    /**
+     * Input Date Range Template; range value 갱신 함수.
+     * Calendar.Range tuple 값을 갱신하고 start/end hidden input 저장값을 같은 tuple 기준으로 동기화한다.
+     * @param {CalendarRangeValue} nextValue 다음 range calendar 선택 값
+     * @returns {void}
+     */
     const updateValue = useCallback(
       (nextValue: CalendarRangeValue) => {
         setCalendarValue(nextValue);
@@ -155,10 +190,22 @@ const InputDateRangeTemplate = forwardRef<HTMLElement, InputCalendarRangeProps>(
     const serializedStartValue = serializeCalendarValue(calendarValue[0]);
     const serializedEndValue = serializeCalendarValue(calendarValue[1]);
 
+    /**
+     * 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}
+     */
     const handleTriggerClick = (event: ReactMouseEvent<Element>) => {
       triggerOnClick?.(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}
+     */
     const handleCalendarChange = (nextValue: CalendarRangeValue) => {
       updateValue(nextValue);
     };
@@ -190,7 +237,7 @@ const InputDateRangeTemplate = forwardRef<HTMLElement, InputCalendarRangeProps>(
             className="input-date-range-apply-button"
             disabled={disabled}
             label={texts?.apply}
-            onClick={() => setInternalCalendarOpen(false)}
+            onClick={() => handleCalendarOpenChange(false)}
           />
         </InputDateFooterUtilContainer>
       </InputDateFooterTemplateContainer>
@@ -234,7 +281,7 @@ const InputDateRangeTemplate = forwardRef<HTMLElement, InputCalendarRangeProps>(
           header={header}
           footer={footerContent}
           open={resolvedCalendarOpen}
-          onOpenChange={setInternalCalendarOpen}
+          onOpenChange={handleCalendarOpenChange}
         >
           {triggerNode}
         </Calendar.Range.Root>

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

@@ -151,6 +151,7 @@ export interface InputCalendarTriggerRenderProps {
  * @property {InputCalendarTexts} [texts] 기본 Date 문구
  * @property {unknown} [timePicker] TimePicker 확장용 예약 슬롯(현재 미구현)
  * @property {boolean} [calendarOpened] calendar 열림 제어 여부
+ * @property {(open: boolean) => void} [onCalendarOpen] calendar 열림 변경 이벤트
  * @property {ReactNode} [trigger] 커스텀 trigger 슬롯
  * @property {(props: InputCalendarTriggerRenderProps) => ReactNode} [renderTrigger] 커스텀 trigger 렌더 함수
  */
@@ -213,6 +214,10 @@ export interface InputCalendarProps extends InputCalendarTriggerProps {
    * - 지정되면 제어형(open state controlled)으로 동작한다.
    */
   calendarOpened?: boolean;
+  /**
+   * calendar 열림 변경 이벤트
+   */
+  onCalendarOpen?: (open: boolean) => void;
   /**
    * 커스텀 trigger 슬롯
    */
@@ -243,6 +248,7 @@ export interface InputCalendarProps extends InputCalendarTriggerProps {
  * @property {ReactNode} [footer] 커스텀 footer 콘텐츠
  * @property {InputCalendarTexts} [texts] 기본 Date 문구
  * @property {boolean} [calendarOpened] calendar 열림 제어 여부
+ * @property {(open: boolean) => void} [onCalendarOpen] calendar 열림 변경 이벤트
  * @property {string} [id] trigger id
  * @property {ReactNode} [trigger] 커스텀 trigger 슬롯
  * @property {(props: InputCalendarTriggerRenderProps) => ReactNode} [renderTrigger] 커스텀 trigger 렌더 함수
@@ -323,6 +329,10 @@ export interface InputCalendarRangeProps {
    * - 지정되면 제어형(open state controlled)으로 동작한다.
    */
   calendarOpened?: boolean;
+  /**
+   * calendar 열림 변경 이벤트
+   */
+  onCalendarOpen?: (open: boolean) => void;
   /**
    * trigger id
    */