@uniai-fe/uds-primitives 0.12.4 → 0.12.6

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

@@ -1,4 +1,9 @@
-import type { MouseEvent, ReactNode } from "react";
+import type {
+  ComponentPropsWithoutRef,
+  FocusEvent,
+  MouseEvent,
+  ReactNode,
+} from "react";
 import type { UseFormRegisterReturn } from "react-hook-form";
 import type {
   CalendarColumns,
@@ -10,7 +15,18 @@ import type {
   CalendarRangeValue,
   CalendarValue,
 } from "../../calendar";
-import type { InputPriority, InputState } from "./foundation";
+import type { FormFieldWidth } from "../../form/types/props";
+import type { InputPriority, InputSize, InputState } from "./foundation";
+
+/**
+ * Input Date hidden input props.
+ * @typedef {Omit<ComponentPropsWithoutRef<"input">, "type" | "value" | "defaultValue" | "name">} InputCalendarHiddenInputProps
+ * @desc Template이 고정하는 type, value, defaultValue와 name을 제외한 native hidden input 계약
+ */
+export type InputCalendarHiddenInputProps = Omit<
+  ComponentPropsWithoutRef<"input">,
+  "type" | "value" | "defaultValue" | "name"
+>;
 
 /**
  * Calendar trigger(Input) 영역에서 필요한 속성 묶음.
@@ -22,8 +38,14 @@ import type { InputPriority, InputState } from "./foundation";
  * @property {boolean} [disabled] disabled 여부
  * @property {boolean} [readOnly] readOnly 여부
  * @property {string} [placeholder] trigger 내부 placeholder
- * @property {InputPriority} [priority] trigger input priority
- * @property {InputState} [state] trigger input state
+ * @property {"primary" | "secondary" | "tertiary" | "table"} [priority] trigger input priority
+ * @property {"small" | "medium" | "large"} [size] trigger input size
+ * @property {"default" | "active" | "focused" | "success" | "error" | "disabled" | "loading"} [state] trigger input state
+ * @property {boolean} [block] trigger width 100% 여부
+ * @property {"full" | "fit" | "fill" | "auto" | number | string} [width] trigger width preset 또는 custom width
+ * @property {(event: FocusEvent<HTMLInputElement>) => void} [onFocus] trigger focus 핸들러
+ * @property {(event: FocusEvent<HTMLInputElement>) => void} [onBlur] trigger blur 핸들러
+ * @desc Date trigger의 표시·상호작용 입력 계약. Template의 name/register는 hidden input 저장에 사용한다.
  */
 export interface InputCalendarTriggerProps {
   /**
@@ -59,16 +81,38 @@ export interface InputCalendarTriggerProps {
    * - table일 때 Trigger는 left icon 배치를 사용한다.
    */
   priority?: InputPriority;
+  /**
+   * "small" | "medium" | "large".
+   */
+  size?: InputSize;
   /**
    * trigger input state
    */
   state?: InputState;
+  /**
+   * trigger width 100% 여부.
+   */
+  block?: boolean;
+  /**
+   * "full" | "fit" | "fill" | "auto" | number | string.
+   */
+  width?: FormFieldWidth;
+  /**
+   * trigger focus 핸들러.
+   */
+  onFocus?: (event: FocusEvent<HTMLInputElement>) => void;
+  /**
+   * trigger blur 핸들러.
+   */
+  onBlur?: (event: FocusEvent<HTMLInputElement>) => void;
 }
 
 /**
  * Trigger view에서만 사용하는 부가 props.
  * @property {string} [className] trigger root className
  * @property {string} [displayValue] 표시 값 문자열
+ * @see InputCalendarTriggerProps
+ * @desc 기본 Date trigger가 InputFoundation.Base에 전달하는 view 계약
  */
 export interface InputCalendarTriggerViewProps extends InputCalendarTriggerProps {
   /**
@@ -90,8 +134,14 @@ export interface InputCalendarTriggerViewProps extends InputCalendarTriggerProps
  * @property {boolean} [disabled] disabled 여부
  * @property {boolean} [readOnly] readOnly 여부
  * @property {(event: MouseEvent<Element>) => void} [onClick] 트리거 클릭 핸들러
- * @property {InputPriority} [priority] trigger input priority
- * @property {InputState} [state] trigger input state
+ * @property {"primary" | "secondary" | "tertiary" | "table"} [priority] trigger input priority
+ * @property {"small" | "medium" | "large"} [size] trigger input size
+ * @property {"default" | "active" | "focused" | "success" | "error" | "disabled" | "loading"} [state] trigger input state
+ * @property {boolean} [block] trigger width 100% 여부
+ * @property {"full" | "fit" | "fill" | "auto" | number | string} [width] trigger width preset 또는 custom width
+ * @property {(event: FocusEvent<HTMLInputElement>) => void} [onFocus] trigger focus 핸들러
+ * @property {(event: FocusEvent<HTMLInputElement>) => void} [onBlur] trigger blur 핸들러
+ * @desc custom Date trigger에 전달하는 표시·상호작용 계약
  */
 export interface InputCalendarTriggerRenderProps {
   /**
@@ -127,57 +177,92 @@ export interface InputCalendarTriggerRenderProps {
    * - table일 때 Trigger는 left icon 배치를 사용한다.
    */
   priority?: InputPriority;
+  /**
+   * "small" | "medium" | "large".
+   */
+  size?: InputSize;
   /**
    * trigger input state
    */
   state?: InputState;
+  /**
+   * trigger width 100% 여부.
+   */
+  block?: boolean;
+  /**
+   * "full" | "fit" | "fill" | "auto" | number | string.
+   */
+  width?: FormFieldWidth;
+  /**
+   * trigger focus 핸들러.
+   */
+  onFocus?: (event: FocusEvent<HTMLInputElement>) => void;
+  /**
+   * trigger blur 핸들러.
+   */
+  onBlur?: (event: FocusEvent<HTMLInputElement>) => void;
 }
 
 /**
  * Input Calendar core props.
- * @property {CalendarMode} [mode="date"] 날짜/시간 모드
- * @property {CalendarColumns} [columns=1] 동시에 노출할 달력 열 수
- * @property {CalendarValue} [value] 제어형 값
- * @property {CalendarValue} [defaultValue] 비제어 초기값
- * @property {CalendarOnChange} [onChange] 값 변경 핸들러(직렬화 문자열 기준)
- * @property {CalendarOnChange} [onValueChange] onChange 별칭(추가 파이프라인용)
+ * @property {"date" | "date-time" | "time"} [mode="date"] Calendar layout mode. 선택 body는 date로 유지된다.
+ * @property {1 | 2} [columns=1] 동시에 노출할 달력 열 수
+ * @property {string | null} [value] 제어형 값
+ * @property {string | null} [defaultValue] 비제어 초기값
+ * @property {(value: string | null) => void} [onChange] 값 변경 핸들러(직렬화 문자열 기준)
+ * @property {(value: string | null) => void} [onValueChange] onChange 별칭(추가 파이프라인용)
  * @property {boolean} [readOnly] 읽기 전용 여부
  * @property {boolean} [disabled] disabled 여부
  * @property {CalendarDatePickerProps} [datePickerProps] Mantine DatePicker 직접 옵션
- * @property {InputPriority} [priority] trigger input priority
- * @property {InputState} [state] trigger input state
+ * @property {string} [id] trigger id
+ * @property {string} [name] hidden input form name
+ * @property {UseFormRegisterReturn} [register] hidden input react-hook-form register 결과
+ * @property {string} [placeholder] trigger 내부 placeholder
+ * @property {(event: MouseEvent<Element>) => void} [onClick] trigger 클릭 핸들러
+ * @property {"primary" | "secondary" | "tertiary" | "table"} [priority] trigger input priority
+ * @property {"small" | "medium" | "large"} [size] trigger input size
+ * @property {"default" | "active" | "focused" | "success" | "error" | "disabled" | "loading"} [state] trigger input state
+ * @property {boolean} [block] trigger width 100% 여부
+ * @property {"full" | "fit" | "fill" | "auto" | number | string} [width] trigger width preset 또는 custom width
+ * @property {string} [form] hidden input이 연결될 form id
+ * @property {boolean} [required] hidden input required 여부
+ * @property {InputCalendarHiddenInputProps} [hiddenInputProps] Template 고정값을 제외한 hidden input native props
+ * @property {(event: FocusEvent<HTMLInputElement>) => void} [onFocus] trigger focus 핸들러
+ * @property {(event: FocusEvent<HTMLInputElement>) => void} [onBlur] trigger blur 핸들러와 RHF touched 동기화 진입점
  * @property {ReactNode} [header] 커스텀 header 콘텐츠
  * @property {ReactNode} [footer] 커스텀 footer 콘텐츠
  * @property {InputCalendarTexts} [texts] 기본 Date 문구
- * @property {unknown} [timePicker] TimePicker 확장용 예약 슬롯(현재 미구현)
+ * @property {unknown} [timePicker] 미구현 compatibility prop. 시간 선택에는 Input.Time.Template을 사용한다.
  * @property {boolean} [calendarOpened] calendar 열림 제어 여부
  * @property {(open: boolean) => void} [onCalendarOpen] calendar 열림 변경 이벤트
  * @property {ReactNode} [trigger] 커스텀 trigger 슬롯
  * @property {(props: InputCalendarTriggerRenderProps) => ReactNode} [renderTrigger] 커스텀 trigger 렌더 함수
+ * @desc 단일 날짜 trigger, Calendar와 hidden form storage를 조합하는 공개 계약
  */
 export interface InputCalendarProps extends InputCalendarTriggerProps {
   /**
-   * 날짜/시간 모드
+   * "date" | "date-time" | "time".
+   * Calendar layout의 data-mode만 지정하며 선택 body는 date로 유지된다.
    */
   mode?: CalendarMode;
   /**
-   * 동시에 노출할 달력 열 수
+   * 1 | 2.
    */
   columns?: CalendarColumns;
   /**
-   * 제어형 값
+   * string | null.
    */
   value?: CalendarValue;
   /**
-   * 비제어 초기값
+   * string | null.
    */
   defaultValue?: CalendarValue;
   /**
-   * 값 변경 핸들러
+   * (value: string | null) => void.
    */
   onChange?: CalendarOnChange;
   /**
-   * onChange 별칭; 외부 파이프라인 시 사용
+   * (value: string | null) => void. onChange 별칭으로 외부 파이프라인에 사용한다.
    */
   onValueChange?: CalendarOnChange;
   /**
@@ -205,8 +290,8 @@ export interface InputCalendarProps extends InputCalendarTriggerProps {
    */
   texts?: InputCalendarTexts;
   /**
-   * TimePicker 확장용 예약 슬롯(현재 미구현).
-   * 추후 Calendar Body 조합 확장 시점에 구체 타입을 확정한다.
+   * TimePicker 확장용 미구현 compatibility prop.
+   * @deprecated 시간 선택에는 Input.Time.Template을 사용한다.
    */
   timePicker?: unknown;
   /**
@@ -226,14 +311,26 @@ export interface InputCalendarProps extends InputCalendarTriggerProps {
    * 커스텀 trigger 렌더 함수
    */
   renderTrigger?: (props: InputCalendarTriggerRenderProps) => ReactNode;
+  /**
+   * hidden input이 연결될 form id.
+   */
+  form?: string;
+  /**
+   * hidden input required 여부.
+   */
+  required?: boolean;
+  /**
+   * Template 고정값을 제외한 hidden input native props.
+   */
+  hiddenInputProps?: InputCalendarHiddenInputProps;
 }
 
 /**
  * Input Calendar Range Template props.
- * @property {CalendarRangeValue} [value] 제어형 range 값
- * @property {CalendarRangeValue} [defaultValue] 비제어 range 초기값
- * @property {CalendarRangeOnChange} [onChange] range 값 변경 핸들러
- * @property {CalendarRangeOnChange} [onValueChange] onChange 별칭
+ * @property {[string | null, string | null]} [value] 제어형 range 값
+ * @property {[string | null, string | null]} [defaultValue] 비제어 range 초기값
+ * @property {(value: [string | null, string | null]) => void} [onChange] range 값 변경 핸들러
+ * @property {(value: [string | null, string | null]) => void} [onValueChange] onChange 별칭
  * @property {boolean} [readOnly] 읽기 전용 여부
  * @property {boolean} [disabled] disabled 여부
  * @property {CalendarRangeDatePickerProps} [datePickerProps] Mantine range DatePicker 옵션
@@ -242,8 +339,17 @@ export interface InputCalendarProps extends InputCalendarTriggerProps {
  * @property {UseFormRegisterReturn} [startRegister] 시작일 react-hook-form register 결과
  * @property {UseFormRegisterReturn} [endRegister] 종료일 react-hook-form register 결과
  * @property {string} [placeholder] trigger 내부 placeholder
- * @property {InputPriority} [priority] trigger input priority
- * @property {InputState} [state] trigger input state
+ * @property {"primary" | "secondary" | "tertiary" | "table"} [priority] trigger input priority
+ * @property {"small" | "medium" | "large"} [size] trigger input size
+ * @property {"default" | "active" | "focused" | "success" | "error" | "disabled" | "loading"} [state] trigger input state
+ * @property {boolean} [block] trigger width 100% 여부
+ * @property {"full" | "fit" | "fill" | "auto" | number | string} [width] trigger width preset 또는 custom width
+ * @property {string} [form] start/end hidden input이 연결될 공통 form id
+ * @property {boolean} [required] start/end hidden input required 여부
+ * @property {InputCalendarHiddenInputProps} [startHiddenInputProps] 시작일 hidden input native props
+ * @property {InputCalendarHiddenInputProps} [endHiddenInputProps] 종료일 hidden input native props
+ * @property {(event: FocusEvent<HTMLInputElement>) => void} [onFocus] trigger focus 핸들러
+ * @property {(event: FocusEvent<HTMLInputElement>) => void} [onBlur] trigger blur 핸들러와 RHF touched 동기화 진입점
  * @property {ReactNode} [header] 커스텀 header 콘텐츠
  * @property {ReactNode} [footer] 커스텀 footer 콘텐츠
  * @property {InputCalendarTexts} [texts] 기본 Date 문구
@@ -253,22 +359,23 @@ export interface InputCalendarProps extends InputCalendarTriggerProps {
  * @property {ReactNode} [trigger] 커스텀 trigger 슬롯
  * @property {(props: InputCalendarTriggerRenderProps) => ReactNode} [renderTrigger] 커스텀 trigger 렌더 함수
  * @property {(event: MouseEvent<Element>) => void} [onClick] trigger 클릭 핸들러
+ * @desc 기간 trigger, Calendar.Range와 start/end hidden form storage를 조합하는 공개 계약
  */
 export interface InputCalendarRangeProps {
   /**
-   * 제어형 range 값
+   * [string | null, string | null].
    */
   value?: CalendarRangeValue;
   /**
-   * 비제어 range 초기값
+   * [string | null, string | null].
    */
   defaultValue?: CalendarRangeValue;
   /**
-   * range 값 변경 핸들러
+   * (value: [string | null, string | null]) => void.
    */
   onChange?: CalendarRangeOnChange;
   /**
-   * onChange 별칭; 외부 파이프라인 시 사용
+   * (value: [string | null, string | null]) => void. onChange 별칭으로 외부 파이프라인에 사용한다.
    */
   onValueChange?: CalendarRangeOnChange;
   /**
@@ -308,10 +415,46 @@ export interface InputCalendarRangeProps {
    * - table일 때 Trigger는 left icon 배치를 사용한다.
    */
   priority?: InputPriority;
+  /**
+   * "small" | "medium" | "large".
+   */
+  size?: InputSize;
   /**
    * trigger input state
    */
   state?: InputState;
+  /**
+   * trigger width 100% 여부.
+   */
+  block?: boolean;
+  /**
+   * "full" | "fit" | "fill" | "auto" | number | string.
+   */
+  width?: FormFieldWidth;
+  /**
+   * start/end hidden input이 연결될 공통 form id.
+   */
+  form?: string;
+  /**
+   * start/end hidden input required 여부.
+   */
+  required?: boolean;
+  /**
+   * 시작일 hidden input native props.
+   */
+  startHiddenInputProps?: InputCalendarHiddenInputProps;
+  /**
+   * 종료일 hidden input native props.
+   */
+  endHiddenInputProps?: InputCalendarHiddenInputProps;
+  /**
+   * trigger focus 핸들러.
+   */
+  onFocus?: (event: FocusEvent<HTMLInputElement>) => void;
+  /**
+   * trigger blur 핸들러.
+   */
+  onBlur?: (event: FocusEvent<HTMLInputElement>) => void;
   /**
    * 커스텀 header 콘텐츠
    */

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

@@ -21,6 +21,8 @@ export type InputTimeIconPosition = "left" | "right";
 
 /**
  * Input Time hidden input props.
+ * @typedef {Omit<ComponentPropsWithoutRef<"input">, "type" | "value" | "defaultValue" | "name">} InputTimeHiddenInputProps
+ * @desc Template이 고정하는 type, value, defaultValue와 name을 제외한 native hidden input 계약
  */
 export type InputTimeHiddenInputProps = Omit<
   ComponentPropsWithoutRef<"input">,
@@ -32,6 +34,7 @@ export type InputTimeHiddenInputProps = Omit<
  * @property {string} hours 시 입력값
  * @property {string} minutes 분 입력값
  * @property {string} seconds 초 입력값
+ * @desc 입력 field에 표시하는 시·분·초 draft 문자열
  */
 export interface InputTimeDraftFields {
   /**
@@ -52,6 +55,7 @@ export interface InputTimeDraftFields {
  * Input Time 편집 중인 시간 값.
  * @property {InputTimeDraftFields} fields 시·분·초 입력값
  * @property {"am" | "pm"} period 오전·오후 구분
+ * @desc 저장값 commit 전의 field 문자열과 12시간제 period 상태
  */
 export interface InputTimeDraft {
   /**
@@ -99,6 +103,7 @@ export type InputTimeTriggerFields = InputTimeDraftFields;
  * @property {(period: "am" | "pm") => void} onPeriodChange 오전·오후 변경 핸들러
  * @property {(amount: 1 | -1) => void} onStep 활성 단위 증감 핸들러
  * @property {(event: FocusEvent<HTMLDivElement>) => void} onRootBlur root blur 핸들러
+ * @desc 시·분·초 field, period, stepper와 clock action을 렌더링하기 위한 trigger 계약
  */
 export interface InputTimeTriggerProps extends Omit<
   ComponentPropsWithoutRef<"div">,
@@ -225,8 +230,8 @@ export interface InputTimeTriggerProps extends Omit<
  * 저장값은 24시간 `HH:mm` 또는 `HH:mm:ss` 문자열을 사용한다.
  * @property {string} [value] 제어형 시간 값
  * @property {string} [defaultValue] 비제어 초기 시간 값
- * @property {(value:string)=>void} [onChange] 값 변경 핸들러
- * @property {(value:string)=>void} [onValueChange] 값 변경 별칭
+ * @property {(value: string) => void} [onChange] 값 변경 핸들러
+ * @property {(value: string) => void} [onValueChange] 값 변경 별칭
  * @property {string} [name] form name
  * @property {string} [form] form id
  * @property {UseFormRegisterReturn} [register] react-hook-form register 결과
@@ -257,8 +262,9 @@ export interface InputTimeTriggerProps extends Omit<
  * @property {string} [hoursPlaceholder] 시 placeholder
  * @property {string} [minutesPlaceholder] 분 placeholder
  * @property {string} [secondsPlaceholder] 초 placeholder
- * @property {(event:FocusEvent<HTMLInputElement>)=>void} [onFocus] focus 핸들러
- * @property {(event:FocusEvent<HTMLDivElement>)=>void} [onBlur] blur 핸들러
+ * @property {(event: FocusEvent<HTMLInputElement>) => void} [onFocus] focus 핸들러
+ * @property {(event: FocusEvent<HTMLDivElement>) => void} [onBlur] blur 핸들러
+ * @desc 시간 trigger, TimePicker panel과 24시간 문자열 hidden form storage를 조합하는 공개 계약
  */
 export interface InputTimeTemplateProps {
   /**

package/src/components/slot/index.tsx

@@ -1,9 +1,6 @@
-/**
- * Slot; polymorphic/text slot 카테고리 배럴
- * @desc
- * - `Slot.Base`: as 기반 polymorphic 마크업 래퍼다.
- * - `Slot.Text`: 텍스트 children만 래핑하는 공통 슬롯이다.
- * - `SlotComponentProps`, `SlotTextProps`: public type 계약이다.
+/*
+ * Slot public entry. Runtime namespace는 ./markup, public prop type은 ./types의
+ * 원본 선언이 계약을 소유한다.
  */
 export * from "./markup";
 export type * from "./types";

package/src/components/slot/markup/Base.tsx

@@ -1,23 +1,158 @@
-import { createElement, forwardRef, type ElementType } from "react";
+import clsx from "clsx";
+import {
+  Children,
+  cloneElement,
+  createElement,
+  Fragment,
+  forwardRef,
+  type ElementType,
+  type ReactElement,
+  type Ref,
+} from "react";
 import type {
   PolymorphicRef,
   SlotComponentProps,
   SlotComponentType,
+  SlotElementProps,
 } from "../types/props";
 
 /**
- * SlotComponent; as prop으로 요소를 교체할 수 있는 얇은 추상화.
+ * Ref utility; callback 또는 object ref에 현재 node를 전달한다.
+ * @function
+ * @param {React.Ref<unknown> | undefined} ref 갱신할 callback 또는 object ref.
+ * @param {unknown} node ref에 전달할 현재 node 또는 null.
+ * @desc callback ref가 반환한 React 19 cleanup을 그대로 보존하고 object ref는 current를 직접 갱신한다.
+ * @return {void | (() => void)} callback cleanup이 있으면 해당 함수, 그 외에는 void.
+ */
+const setRef = (
+  ref: Ref<unknown> | undefined,
+  node: unknown,
+): void | (() => void) => {
+  if (typeof ref === "function") return ref(node);
+  if (ref && typeof ref === "object") {
+    (ref as { current: unknown }).current = node;
+  }
+};
+
+/**
+ * Ref utility; child ref와 전달된 ref를 하나의 callback ref로 병합한다.
+ * @function
+ * @param {Array<React.Ref<unknown> | undefined>} refs 함께 갱신할 callback 또는 object ref 목록.
+ * @desc React 19 callback cleanup이 있으면 cleanup 없는 나머지 ref도 같은
+ * unmount에서 null로 해제한다.
+ * @return {React.RefCallback<unknown> | undefined} ref가 없으면 undefined, 있으면 병합된 callback ref.
+ */
+const mergeRefs = (...refs: (Ref<unknown> | undefined)[]) => {
+  if (refs.every(ref => ref == null)) return undefined;
+
+  return (node: unknown) => {
+    const cleanups = refs.map(ref => setRef(ref, node));
+
+    // React 19 callback ref 하나라도 cleanup을 반환하면 나머지 ref도 같은 unmount에서 해제한다.
+    if (!cleanups.some(cleanup => typeof cleanup === "function")) return;
+
+    return () => {
+      cleanups.forEach((cleanup, index) => {
+        if (typeof cleanup === "function") cleanup();
+        else setRef(refs[index], null);
+      });
+    };
+  };
+};
+
+/**
+ * Props utility; Slot과 child가 소유한 props를 asChild 계약에 따라 병합한다.
+ * @function
+ * @param {SlotElementProps} slotProps Slot.Base에 전달된 props.
+ * @param {SlotElementProps} childProps 단일 child element가 소유한 props.
+ * @desc
+ * - 일반 props와 같은 style property는 child가 우선하고, className은 Slot 다음
+ *   child 순서로 합친다.
+ * - 같은 event handler는 모든 인자를 child, Slot 순서로 전달하고 child 반환값을
+ *   보존한다. 첫 번째 인자의 defaultPrevented가 true일 때만 Slot handler를 생략한다.
+ * @return {SlotElementProps} child에 전달할 병합 props.
+ */
+const mergeSlotProps = (
+  slotProps: SlotElementProps,
+  childProps: SlotElementProps,
+): SlotElementProps => {
+  const mergedProps: SlotElementProps = { ...slotProps, ...childProps };
+
+  Object.keys(slotProps).forEach(key => {
+    const slotHandler = slotProps[key];
+    const childHandler = childProps[key];
+
+    if (
+      /^on[A-Z]/.test(key) &&
+      typeof slotHandler === "function" &&
+      typeof childHandler === "function"
+    ) {
+      mergedProps[key] = (...args: unknown[]) => {
+        const result = childHandler(...args);
+        const event = args[0];
+        const defaultPrevented =
+          typeof event === "object" &&
+          event !== null &&
+          "defaultPrevented" in event &&
+          event.defaultPrevented === true;
+
+        if (!defaultPrevented) slotHandler(...args);
+        return result;
+      };
+    }
+  });
+
+  mergedProps.className =
+    clsx(slotProps.className, childProps.className) || undefined;
+  if (slotProps.style || childProps.style) {
+    mergedProps.style = { ...slotProps.style, ...childProps.style };
+  }
+
+  return mergedProps;
+};
+
+/**
+ * SlotComponent; as로 요소를 교체하거나 asChild로 단일 child를 직접 렌더링하는 추상화.
  * @component
- * @param {SlotComponentProps} props
- * @param {ElementType} [props.as="div"] 교체할 요소.
- * @param {React.ReactNode} [props.children] children 그대로 전달된다.
- * @param {string} [props.className] className.
+ * @property {ElementType} [as="div"] asChild가 false일 때 교체할 요소.
+ * @property {true | false} [asChild=false] true이면 단일 child를 wrapper 없이 렌더링하고, false이면 as 요소를 렌더링한다.
+ * @property {React.ReactElement | React.ReactNode} [children] asChild가 true이면 필수인 단일 non-Fragment ReactElement, false이면 선택적인 ReactNode.
+ * @property {string} [className] 추가 className.
+ * @param {React.Ref<unknown>} [ref] 렌더링된 요소에 병합할 ref.
+ * @desc
+ * - asChild에서는 child의 일반 props를 우선하고 Slot className 다음에 child className을 합치며, 같은 style property는 child가 우선한다.
+ * - 같은 event handler는 모든 인자를 child, Slot 순서로 전달하고 child 반환값을 보존하며, 첫 번째 인자의 defaultPrevented가 true일 때만 Slot handler를 생략한다.
+ * - child ref와 전달된 ref를 합치며 React 19 callback cleanup이 있으면 cleanup 없는 나머지 ref는 null로 해제한다.
+ * - asChild의 child가 단일 non-Fragment ReactElement가 아니면 예외를 던진다.
+ * @return {React.ReactNode} 렌더링된 노드.
  */
 const SlotComponent = forwardRef(
   (
-    { as, children, className, ...rest }: SlotComponentProps<ElementType>,
+    {
+      as,
+      asChild,
+      children,
+      className,
+      ...rest
+    }: SlotComponentProps<ElementType>,
     ref?: PolymorphicRef<ElementType>,
   ) => {
+    if (asChild) {
+      const child = Children.only(children) as ReactElement<SlotElementProps>;
+
+      if (child.type === Fragment) {
+        throw new TypeError(
+          "Slot.Base asChild requires one non-Fragment React element.",
+        );
+      }
+
+      const childProps = child.props as SlotElementProps;
+      return cloneElement(child, {
+        ...mergeSlotProps({ ...rest, className }, childProps),
+        ref: mergeRefs(childProps.ref, ref as Ref<unknown>),
+      });
+    }
+
     const Component = (as ?? "div") as ElementType;
     return createElement(
       Component,
@@ -29,6 +164,8 @@ const SlotComponent = forwardRef(
       children,
     );
   },
-) as unknown as SlotComponentType;
+);
+
+SlotComponent.displayName = "SlotBase";
 
-export default SlotComponent;
+export default SlotComponent as unknown as SlotComponentType;

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

@@ -2,10 +2,8 @@ import SlotBase from "./Base";
 import SlotText from "./Text";
 
 /**
- * Slot; polymorphic/text slot namespace
- * @desc
- * - `Slot.Base`: as 기반 polymorphic 마크업 래퍼다.
- * - `Slot.Text`: 텍스트 children만 래핑하는 공통 슬롯이다.
+ * Slot; public markup namespace
+ * @desc Slot markup component의 public entry다.
  */
 export const Slot = {
   Base: SlotBase,