@uniai-fe/uds-primitives 0.12.4 → 0.12.6

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

@@ -1,25 +1,29 @@
 import type {
+  CSSProperties,
   ComponentPropsWithRef,
   ComponentPropsWithoutRef,
   ElementType,
+  HTMLAttributes,
+  ReactElement,
   ReactNode,
+  Ref,
 } from "react";
 
 /**
- * SlotComponentRestProps; as/children/className을 제외한 원본 요소 props.
+ * SlotComponentRestProps; as/asChild/children/className을 제외한 원본 요소 props.
  * @typedef SlotComponentRestProps
  * @template C
  * @desc
  * - HTML/React 공통 속성과 data-* 커스텀 속성을 그대로 포함한다.
- * - SlotComponent 내부에서 as/children/className을 재정의하기 위해 제외한다.
+ * - SlotComponent 내부에서 as/asChild/children/className을 재정의하기 위해 제외한다.
  */
 export type SlotComponentRestProps<C extends ElementType> = Omit<
   ComponentPropsWithoutRef<C>,
-  "as" | "children" | "className"
+  "as" | "asChild" | "children" | "className"
 >;
 
 /**
- * PolymorphicRef; 전달된 as 요소의 ref 타입.
+ * PolymorphicRef; as로 렌더링된 요소의 ref 타입.
  * @typedef PolymorphicRef
  * @template C
  */
@@ -27,40 +31,132 @@ export type PolymorphicRef<C extends ElementType> =
   ComponentPropsWithRef<C>["ref"];
 
 /**
- * SlotComponentProps; as 기반 슬롯 래퍼 공통 props.
- * @typedef SlotComponentProps
+ * SlotElementProps; asChild 병합에 사용하는 element props
+ * @property {string} [className] 병합할 className.
+ * @property {React.Ref<unknown>} [ref] 병합할 callback 또는 object ref.
+ * @property {React.CSSProperties} [style] 병합할 inline style.
+ * @desc Slot과 child의 임의 props를 보존하면서 className, ref와 style 병합 계약을 명시한다.
+ */
+export type SlotElementProps = Record<string, unknown> & {
+  /**
+   * 병합할 className.
+   */
+  className?: string;
+  /**
+   * 병합할 callback 또는 object ref.
+   */
+  ref?: Ref<unknown>;
+  /**
+   * 병합할 inline style.
+   */
+  style?: CSSProperties;
+};
+
+/**
+ * SlotAsChildProps; 단일 child를 wrapper 없이 렌더링하는 Slot props
+ * @property {true} asChild wrapper 제거를 활성화하는 discriminator.
+ * @property {never} [as] asChild variant에서 허용하지 않는 렌더 요소 override.
+ * @property {React.ReactElement} children props와 ref를 병합할 단일 non-Fragment ReactElement.
+ * @property {string} [className] Slot className 다음에 child className을 합칠 값.
+ * @desc React.HTMLAttributes<HTMLElement>를 Slot-side 공통 속성으로 제공하고 element 전용 속성은 child가 소유한다.
+ */
+export type SlotAsChildProps = Omit<
+  HTMLAttributes<HTMLElement>,
+  "children" | "className"
+> & {
+  /**
+   * literal true이면 단일 ReactElement를 wrapper 없이 렌더링한다.
+   */
+  asChild: true;
+  /**
+   * asChild가 true이면 as를 함께 사용할 수 없다.
+   */
+  as?: never;
+  /**
+   * props를 병합할 단일 non-Fragment ReactElement. 그 외 입력은 runtime에서 예외를 던진다.
+   */
+  children: ReactElement;
+  /**
+   * Slot className 다음에 child className을 합친다.
+   */
+  className?: string;
+};
+
+/**
+ * SlotAsElementProps; as 요소를 렌더링하는 Slot props
  * @template C
- * @property {ElementType} [as] 렌더링할 요소. 기본값은 div.
- * @property {React.ReactNode} [children] 그대로 전달되는 children.
- * @property {string} [className] 추가 className.
- * @desc
- * - ComponentPropsWithoutRef<C>를 확장하므로 React/HTML 공통 속성과 사용자 정의 data 속성 모두 전달된다.
- * - as/children/className은 Slot에서 직접 제어하기 위해 재정의한다.
+ * @property {false} [asChild] as 기반 렌더링을 유지하는 discriminator.
+ * @property {C} [as="div"] 렌더링할 요소.
+ * @property {React.ReactNode} [children] 렌더링할 children.
+ * @property {string} [className] 렌더링한 요소에 전달할 className.
+ * @desc SlotComponentRestProps<C>를 확장해 as 요소의 native props를 보존한다.
  */
-export type SlotComponentProps<C extends ElementType> =
+export type SlotAsElementProps<C extends ElementType> =
   SlotComponentRestProps<C> & {
     /**
-     * 교체할 요소. 기본은 'div'.
+     * literal false 또는 생략이면 as 요소를 렌더링한다.
+     */
+    asChild?: false;
+    /**
+     * 교체할 요소. 기본은 div.
      */
     as?: C;
     /**
-     * 전달할 children.
+     * 전달할 ReactNode.
      */
     children?: ReactNode;
     /**
-     * 추가 className.
+     * 렌더링한 요소에 전달할 className.
      */
     className?: string;
   };
 
+/**
+ * SlotComponentProps; as 또는 asChild 기반 슬롯 렌더링 props.
+ * @typedef SlotComponentProps
+ * @template C
+ * @property {ElementType} [as] asChild가 false일 때 렌더링할 요소. 기본값은 div이며 true variant에서는 허용하지 않는다.
+ * @property {true | false} [asChild] true이면 단일 ReactElement를 wrapper 없이 렌더링하고, false 또는 생략이면 as 요소를 렌더링한다.
+ * @property {React.ReactElement | React.ReactNode} [children] asChild가 true이면 필수인 단일 non-Fragment ReactElement, false 또는 생략이면 선택적인 ReactNode.
+ * @property {string} [className] 두 variant의 공통 className. asChild에서는 Slot className 다음에 child className을 합친다.
+ * @desc
+ * - asChild가 true이면 Slot-side props는 React.HTMLAttributes<HTMLElement>로 제한하고, anchor/button 같은 element 전용 props는 child에 둔다.
+ * - asChild가 false이면 ComponentPropsWithoutRef<C>를 확장하므로 as 요소의 React/HTML 속성을 전달한다.
+ * - as/asChild/children/className은 Slot에서 직접 제어하기 위해 재정의한다.
+ * - asChild와 as는 함께 사용할 수 없다.
+ * - asChild의 일반 props와 같은 style property는 child가 우선한다.
+ * - 같은 event handler는 모든 인자를 child, Slot 순서로 전달하고 child 반환값을 보존하며, 첫 번째 인자의 defaultPrevented가 true일 때만 Slot handler를 생략한다.
+ * - child ref와 전달된 ref를 합치며 React 19 callback cleanup이 있으면 cleanup 없는 나머지 ref는 null로 해제한다.
+ */
+export type SlotComponentProps<C extends ElementType> =
+  SlotAsChildProps | SlotAsElementProps<C>;
+
 /**
  * SlotComponentType; SlotComponent의 forwardRef 타입 시그니처.
  * @typedef SlotComponentType
- * @template C
- * @param {SlotComponentProps<C>} props 공통 슬롯 props.
- * @param {PolymorphicRef<C>} [props.ref] 전달될 ref.
- * @returns {React.ReactNode} 렌더링된 노드.
+ * @desc asChild와 as variant의 public callable contract를 각각 제공한다.
  */
-export type SlotComponentType = <C extends ElementType = "div">(
-  props: SlotComponentProps<C> & { ref?: PolymorphicRef<C> },
-) => ReactNode;
+export type SlotComponentType = {
+  /**
+   * SlotComponentType; asChild로 단일 HTML child를 렌더링하는 signature.
+   * @property {true} asChild wrapper 제거를 활성화한다.
+   * @property {React.ReactElement} children props와 ref를 병합할 단일 non-Fragment ReactElement.
+   * @property {React.Ref<HTMLElement>} [ref] 실제 HTML element까지 전달할 ref.
+   * @desc Slot-side props는 표준 HTMLAttributes로 제한하고 element 전용 props는 child가 소유한다.
+   * @return {React.ReactNode} 병합된 단일 child.
+   */
+  (props: SlotAsChildProps & { ref?: Ref<HTMLElement> }): ReactNode;
+  /**
+   * SlotComponentType; as로 렌더링 요소를 교체하는 signature.
+   * @template C
+   * @property {C} [as="div"] 렌더링할 요소.
+   * @property {false} [asChild=false] as 기반 렌더링을 유지한다.
+   * @property {React.ReactNode} [children] 렌더링할 children.
+   * @property {PolymorphicRef<C>} [ref] as 요소에 전달할 ref.
+   * @desc as 요소의 ComponentPropsWithoutRef<C>와 ref type을 보존한다.
+   * @return {React.ReactNode} as 요소로 렌더링된 노드.
+   */
+  <C extends ElementType = "div">(
+    props: SlotAsElementProps<C> & { ref?: PolymorphicRef<C> },
+  ): ReactNode;
+};

package/src/components/table/types/foundation.ts

@@ -1,5 +1,5 @@
 import type { ComponentPropsWithoutRef, ElementType } from "react";
-import type { SlotComponentProps, SlotTextProps } from "../../slot";
+import type { SlotComponentRestProps, SlotTextProps } from "../../slot";
 
 export const TABLE_CELL_ALIGN_OPTIONS = ["left", "center", "right"] as const;
 export const TABLE_CELL_ALIGN_Y_OPTIONS = ["top", "center", "bottom"] as const;
@@ -155,7 +155,7 @@ export interface TableColumnData<
  * @property {boolean} [scrollable=false] true면 외부 스크롤 래퍼를 추가한다.
  * @property {"x" | "y" | "both"} [scrollAxis="x"] scrollable일 때 스크롤 축
  * @property {ElementType} [scrollAs="div"] scrollable wrapper element
- * @property {Omit<SlotComponentProps<ElementType>, "as" | "children" | "className">} [scrollProps] scrollable wrapper native props
+ * @property {SlotComponentRestProps<ElementType> & { asChild?: never }} [scrollProps] asChild를 허용하지 않아 wrapper element를 보존하는 scrollable wrapper native props
  * @property {string} [scrollClassName] 스크롤 래퍼 className
  * @property {React.ReactNode} [footer] footer 노드
  * @property {React.ReactNode} [children] body 콘텐츠
@@ -184,12 +184,14 @@ export interface TableContainerProps<
    */
   scrollAs?: ElementType;
   /**
-   * scrollable wrapper native props
+   * asChild를 허용하지 않아 wrapper element를 보존하는 scrollable wrapper native props
    */
-  scrollProps?: Omit<
-    SlotComponentProps<ElementType>,
-    "as" | "children" | "className"
-  >;
+  scrollProps?: SlotComponentRestProps<ElementType> & {
+    /**
+     * Table scroll wrapper에서는 wrapper 제거를 허용하지 않는다.
+     */
+    asChild?: never;
+  };
   /**
    * 스크롤 래퍼 className
    */

package/src/components/time-picker/markup/Footer.tsx

@@ -5,11 +5,11 @@ import type { TimePickerFooterProps } from "../types";
  * TimePicker Footer; 삭제와 적용 action을 렌더한다.
  * @component
  * @param {TimePickerFooterProps} props
- * @param {boolean} props.clearable 삭제 action 노출 여부
- * @param {boolean} props.disabled 비활성화 여부
- * @param {() => void} props.onClear 삭제 핸들러
- * @param {() => void} props.onApply 적용 핸들러
- * @returns {ReactNode} TimePicker footer
+ * @property {boolean} props.clearable 삭제 action 노출 여부
+ * @property {boolean} props.disabled 비활성화 여부
+ * @property {() => void} props.onClear 삭제 핸들러
+ * @property {() => void} props.onApply 적용 핸들러
+ * @desc clearable 상태에 따라 삭제 action을 노출하고 적용 action을 유지한다.
  * @example
  * <TimePickerFooter
  *   clearable

package/src/components/time-picker/markup/HourSection.tsx

@@ -12,13 +12,13 @@ const PERIOD_OPTIONS = [
  * TimePicker Hour Section; 오전·오후와 시 선택 grid를 렌더한다.
  * @component
  * @param {TimePickerHourSectionProps} props
- * @param {"12h" | "24h"} props.format 표시 형식
- * @param {number | null} props.selectedHour 선택한 표시 시
- * @param {"am" | "pm"} props.period 오전·오후
- * @param {boolean} props.disabled 비활성화 여부
- * @param {(hours: number) => void} props.onHourSelect 시 선택 핸들러
- * @param {(period: "am" | "pm") => void} props.onPeriodChange 오전·오후 변경 핸들러
- * @returns {ReactNode} 시간 선택 section
+ * @property {"12h" | "24h"} props.format 표시 형식
+ * @property {number | null} props.selectedHour 선택한 표시 시
+ * @property {"am" | "pm"} props.period 오전·오후
+ * @property {boolean} props.disabled 비활성화 여부
+ * @property {(hours: number) => void} props.onHourSelect 시 선택 핸들러
+ * @property {(period: "am" | "pm") => void} props.onPeriodChange 오전·오후 변경 핸들러
+ * @desc 12시간제와 24시간제에 맞는 시 목록과 period control을 렌더한다.
  * @example
  * <TimePickerHourSection
  *   format="12h"

package/src/components/time-picker/markup/MinuteSection.tsx

@@ -8,11 +8,11 @@ const MINUTES = Array.from({ length: 12 }, (_, index) => index * 5);
  * TimePicker Minute Section; 1분 stepper와 5분 선택 grid를 렌더한다.
  * @component
  * @param {TimePickerMinuteSectionProps} props
- * @param {number | null} props.selectedMinute 선택한 분
- * @param {boolean} props.disabled 비활성화 여부
- * @param {(amount: 1 | -1) => void} props.onMinuteStep 1분 증감 핸들러
- * @param {(minutes: number) => void} props.onMinuteSelect 분 선택 핸들러
- * @returns {ReactNode} 분 선택 section
+ * @property {number | null} props.selectedMinute 선택한 분
+ * @property {boolean} props.disabled 비활성화 여부
+ * @property {(amount: 1 | -1) => void} props.onMinuteStep 1분 증감 핸들러
+ * @property {(minutes: number) => void} props.onMinuteSelect 분 선택 핸들러
+ * @desc 5분 간격 빠른 선택과 1분 단위 미세 조정을 함께 제공한다.
  * @example
  * <TimePickerMinuteSection
  *   selectedMinute={30}

package/src/components/time-picker/markup/Summary.tsx

@@ -4,8 +4,8 @@ import type { TimePickerSummaryProps } from "../types";
  * TimePicker Summary; 현재 선택한 시간을 표시한다.
  * @component
  * @param {TimePickerSummaryProps} props
- * @param {string} props.summary 선택한 시간 표시값
- * @returns {ReactNode} 선택 시간 요약
+ * @property {string} props.summary 선택한 시간 표시값
+ * @desc TimePicker panel 상단에 현재 선택값 또는 빈 상태를 표시한다.
  * @example
  * <TimePickerSummary summary="09:30 오전" />
  */

package/src/components/time-picker/markup/Template.tsx

@@ -11,17 +11,17 @@ import TimePickerSummary from "./Summary";
  * TimePicker Template; Figma의 시간·분 선택과 footer action을 렌더한다.
  * @component
  * @param {TimePickerTemplateProps} props
- * @param {string} props.value 24시간 형식 시간 값
- * @param {"12h" | "24h"} props.format 표시 형식
- * @param {boolean} props.clearable 삭제 action 노출 여부
- * @param {boolean} props.disabled 비활성화 여부
- * @param {(hours: number) => void} props.onHourSelect 시 선택 핸들러
- * @param {(minutes: number) => void} props.onMinuteSelect 분 선택 핸들러
- * @param {(period: "am" | "pm") => void} props.onPeriodChange 오전·오후 변경 핸들러
- * @param {(amount: 1 | -1) => void} props.onMinuteStep 1분 증감 핸들러
- * @param {() => void} props.onClear 삭제 핸들러
- * @param {() => void} props.onApply 적용 핸들러
- * @returns {ReactNode} 시간 선택 panel
+ * @property {string} props.value 24시간 형식 시간 값
+ * @property {"12h" | "24h"} props.format 표시 형식
+ * @property {boolean} props.clearable 삭제 action 노출 여부
+ * @property {boolean} props.disabled 비활성화 여부
+ * @property {(hours: number) => void} props.onHourSelect 시 선택 핸들러
+ * @property {(minutes: number) => void} props.onMinuteSelect 분 선택 핸들러
+ * @property {(period: "am" | "pm") => void} props.onPeriodChange 오전·오후 변경 핸들러
+ * @property {(amount: 1 | -1) => void} props.onMinuteStep 1분 증감 핸들러
+ * @property {() => void} props.onClear 삭제 핸들러
+ * @property {() => void} props.onApply 적용 핸들러
+ * @desc 24시간 저장값을 표시 형식에 맞춰 시·분 선택 section과 action에 배분한다.
  * @example
  * <TimePicker.Template
  *   value="09:30"

package/src/components/time-picker/types/time-picker.ts

@@ -21,6 +21,7 @@ export type TimePickerUnit = "hours" | "minutes" | "seconds";
  * @property {number} hours 시
  * @property {number} minutes 분
  * @property {number} seconds 초
+ * @desc 24시간 저장값의 정규화된 시·분·초 숫자 구성
  */
 export interface TimePickerParts {
   /**
@@ -49,6 +50,7 @@ export interface TimePickerParts {
  * @property {(amount: 1 | -1) => void} onMinuteStep 1분 증감 핸들러
  * @property {() => void} onClear 삭제 핸들러
  * @property {() => void} onApply 적용 핸들러
+ * @desc TimePicker panel의 선택값, 표시 형식과 action 계약
  */
 export interface TimePickerTemplateProps {
   /**
@@ -96,6 +98,7 @@ export interface TimePickerTemplateProps {
 /**
  * TimePicker Summary props.
  * @property {string} summary 선택한 시간 표시값
+ * @desc panel 상단의 현재 선택값 표시 계약
  */
 export interface TimePickerSummaryProps {
   /**
@@ -112,6 +115,7 @@ export interface TimePickerSummaryProps {
  * @property {boolean} disabled 비활성화 여부
  * @property {(hours: number) => void} onHourSelect 시 선택 핸들러
  * @property {(period: "am" | "pm") => void} onPeriodChange 오전·오후 변경 핸들러
+ * @desc 표시 형식별 시 목록과 오전·오후 선택 계약
  */
 export interface TimePickerHourSectionProps {
   /**
@@ -146,6 +150,7 @@ export interface TimePickerHourSectionProps {
  * @property {boolean} disabled 비활성화 여부
  * @property {(amount: 1 | -1) => void} onMinuteStep 1분 증감 핸들러
  * @property {(minutes: number) => void} onMinuteSelect 분 선택 핸들러
+ * @desc 분 quick select와 1분 step action 계약
  */
 export interface TimePickerMinuteSectionProps {
   /**
@@ -172,6 +177,7 @@ export interface TimePickerMinuteSectionProps {
  * @property {boolean} disabled 비활성화 여부
  * @property {() => void} onClear 삭제 핸들러
  * @property {() => void} onApply 적용 핸들러
+ * @desc 삭제 노출 여부와 panel footer action 계약
  */
 export interface TimePickerFooterProps {
   /**

package/src/components/time-picker/utils/time.ts

@@ -12,8 +12,10 @@ const wrapTimePart = (value: number, limit: number) =>
 
 /**
  * TimePicker Utility; 24시간 문자열을 시간 값으로 파싱한다.
+ * @utility
  * @param {string} value HH:mm 또는 HH:mm:ss 값
- * @returns {TimePickerParts | null} 파싱 결과
+ * @desc 형식 또는 시·분·초 범위가 유효하지 않으면 null을 반환한다.
+ * @return {TimePickerParts | null} 파싱 결과
  */
 export const parseTimeValue = (value: string): TimePickerParts | null => {
   const match = /^(\d{2}):(\d{2})(?::(\d{2}))?$/.exec(value);
@@ -33,9 +35,11 @@ export const parseTimeValue = (value: string): TimePickerParts | null => {
 
 /**
  * TimePicker Utility; 시간 값을 24시간 문자열로 직렬화한다.
+ * @utility
  * @param {TimePickerParts} parts 시간 값
  * @param {boolean} withSeconds 초 포함 여부
- * @returns {string} HH:mm 또는 HH:mm:ss 값
+ * @desc 각 단위를 두 자리로 맞추고 withSeconds에 따라 초를 포함한다.
+ * @return {string} HH:mm 또는 HH:mm:ss 값
  */
 export const serializeTimeValue = (
   parts: TimePickerParts,
@@ -47,11 +51,13 @@ export const serializeTimeValue = (
 
 /**
  * TimePicker Utility; 지정 단위만 순환 증감한다.
+ * @utility
  * @param {string} value 시간 값
- * @param {TimePickerUnit} unit 증감 단위
+ * @param {"hours" | "minutes" | "seconds"} unit 증감 단위
  * @param {number} amount 증감량
  * @param {boolean} withSeconds 초 포함 여부
- * @returns {string} 증감한 시간 값
+ * @desc 빈 값은 00:00 기준으로 시작하고 시는 24, 분·초는 60을 경계로 순환한다.
+ * @return {string} 증감한 시간 값
  */
 export const stepTimeValue = (
   value: string,
@@ -73,27 +79,33 @@ export const stepTimeValue = (
 
 /**
  * TimePicker Utility; 저장 시를 표시 시로 변환한다.
+ * @utility
  * @param {number} hours 24시간 시 값
- * @param {TimePickerFormat} format 표시 형식
- * @returns {number} 표시 시 값
+ * @param {"12h" | "24h"} format 표시 형식
+ * @desc 12시간제에서는 0시와 12시를 12로 표시한다.
+ * @return {number} 표시 시 값
  */
 export const toDisplayHour = (hours: number, format: TimePickerFormat) =>
   format === "12h" ? hours % 12 || 12 : hours;
 
 /**
  * TimePicker Utility; 24시간 시 값의 오전·오후를 반환한다.
+ * @utility
  * @param {number} hours 24시간 시 값
- * @returns {TimePickerPeriod} 오전·오후
+ * @desc 12시 이상을 pm, 그 미만을 am으로 분류한다.
+ * @return {"am" | "pm"} 오전·오후
  */
 export const getTimePeriod = (hours: number): TimePickerPeriod =>
   hours >= 12 ? "pm" : "am";
 
 /**
  * TimePicker Utility; 오전·오후를 24시간 저장값에 반영한다.
+ * @utility
  * @param {string} value 시간 값
- * @param {TimePickerPeriod} period 오전·오후
+ * @param {"am" | "pm"} period 오전·오후
  * @param {boolean} withSeconds 초 포함 여부
- * @returns {string} 변경한 시간 값
+ * @desc 기존 분·초를 보존하고 선택한 period에 맞춰 저장 시만 변환한다.
+ * @return {string} 변경한 시간 값
  */
 export const setTimePeriod = (
   value: string,

package/src/index.scss

@@ -15,10 +15,8 @@
 @use "./components/pagination";
 @use "./components/pop-over";
 @use "./components/radio";
-@use "./components/scrollbar";
 @use "./components/segmented-control";
 @use "./components/select";
-@use "./components/spinner";
 @use "./components/switch";
 @use "./components/tab";
 @use "./components/table";

package/src/index.tsx

@@ -20,15 +20,21 @@ export * from "./components/navigation";
 export * from "./components/pagination";
 export * from "./components/pop-over";
 export * from "./components/radio";
-export * from "./components/scrollbar";
 export * from "./components/segmented-control";
 export * from "./components/select";
 export * from "./components/slot";
-export * from "./components/spinner";
 export * from "./components/switch";
 export * from "./components/tab";
 export * from "./components/table";
 export * from "./components/time-picker";
 export * from "./components/toast";
 export * from "./components/tooltip";
+export {
+  isSameSelectedValue,
+  isSameSelectedValueList,
+  normalizeSelectedValuesByMode,
+  normalizeSingleSelectedValue,
+  toSelectedValueKey,
+} from "./utils";
 export type * from "./types";
+export type { SelectedValue } from "./utils";

package/src/types/index.ts

@@ -1,4 +1 @@
-/**
- * shared types placeholder: variant/slot 타입을 정의하고 각 카테고리에서 import한다.
- */
-export * from "./form-field";
+export type * from "./form-field";

package/src/utils/index.ts

@@ -1,4 +1,8 @@
-/**
- * shared utils placeholder: 토큰 매핑 및 className 헬퍼를 정의한다.
- */
-export * from "./selected-values";
+export {
+  isSameSelectedValue,
+  isSameSelectedValueList,
+  normalizeSelectedValuesByMode,
+  normalizeSingleSelectedValue,
+  toSelectedValueKey,
+} from "./selected-values";
+export type { SelectedValue } from "./selected-values";

package/src/utils/selected-values.ts

@@ -1,25 +1,25 @@
-/**
- * Selected Values Utils; value 기반 선택 비교/정규화 유틸
- */
-
 /**
  * Select/Dropdown value 원시 타입
  */
 export type SelectedValue = string | number;
 
 /**
- * value를 비교 키 문자열로 정규화
+ * Selected Values; value를 비교 키 문자열로 정규화
+ * @function
  * @param {SelectedValue | undefined} value 비교 대상 value
- * @returns {string} 정규화된 키 문자열
+ * @desc Select와 Dropdown이 문자열·숫자 value를 같은 비교 축으로 다룰 수 있게 한다.
+ * @return {string} 정규화된 키 문자열
  */
 export const toSelectedValueKey = (value?: SelectedValue): string =>
   value === undefined ? "" : String(value);
 
 /**
- * 단일 value 동등성 비교
+ * Selected Values; 단일 value 동등성 비교
+ * @function
  * @param {SelectedValue | undefined} previousValue 이전 value
  * @param {SelectedValue | undefined} nextValue 다음 value
- * @returns {boolean} 동등 여부
+ * @desc 문자열·숫자 표현 차이를 정규화한 뒤 두 선택값의 동등성을 판정한다.
+ * @return {boolean} 동등 여부
  */
 export const isSameSelectedValue = (
   previousValue?: SelectedValue,
@@ -28,10 +28,12 @@ export const isSameSelectedValue = (
   toSelectedValueKey(previousValue) === toSelectedValueKey(nextValue);
 
 /**
- * value 배열 동등성 비교
+ * Selected Values; value 배열 동등성 비교
+ * @function
  * @param {SelectedValue[]} previousValues 이전 value 배열
  * @param {SelectedValue[]} nextValues 다음 value 배열
- * @returns {boolean} 동등 여부
+ * @desc 선택 순서를 포함해 두 value 배열이 같은지 판정한다.
+ * @return {boolean} 동등 여부
  */
 export const isSameSelectedValueList = (
   previousValues: SelectedValue[],
@@ -43,19 +45,23 @@ export const isSameSelectedValueList = (
   );
 
 /**
- * 단일 선택 value 정규화
+ * Selected Values; 단일 선택 value 정규화
+ * @function
  * @param {SelectedValue[]} selectedValues 선택 value 배열
- * @returns {SelectedValue | undefined} 단일 선택 결과
+ * @desc 선택 배열의 첫 value를 단일 선택 결과로 사용한다.
+ * @return {SelectedValue | undefined} 단일 선택 결과
  */
 export const normalizeSingleSelectedValue = (
   selectedValues: SelectedValue[],
 ): SelectedValue | undefined => selectedValues[0];
 
 /**
- * 모드 기반 value 배열 정규화
+ * Selected Values; 모드 기반 value 배열 정규화
+ * @function
  * @param {SelectedValue[]} selectedValues 선택 value 배열
  * @param {boolean} multiple 다중 선택 모드 여부
- * @returns {SelectedValue[]} 모드 규칙 적용 결과
+ * @desc 다중 선택은 전체 배열을 유지하고 단일 선택은 첫 value만 유지한다.
+ * @return {SelectedValue[]} 모드 규칙 적용 결과
  */
 export const normalizeSelectedValuesByMode = (
   selectedValues: SelectedValue[],

package/src/components/scrollbar/hooks/index.ts

@@ -1,4 +0,0 @@
-/**
- * Scrollbar Hooks; 현재 공개된 훅이 없는 placeholder 엔트리
- */
-export {};

package/src/components/scrollbar/index.scss

@@ -1 +0,0 @@
-@use "./styles/index.scss";

package/src/components/scrollbar/index.tsx

@@ -1,4 +0,0 @@
-/**
- * Scrollbar; 현재 public export가 없는 placeholder 카테고리 배럴
- */
-export * from "./markup";

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

@@ -1,4 +0,0 @@
-/**
- * Scrollbar Markup; 현재 공개된 컴포넌트가 없는 placeholder 엔트리
- */
-export {};

package/src/components/scrollbar/types/index.ts

@@ -1,4 +0,0 @@
-/**
- * Scrollbar Types; 현재 공개된 타입이 없는 placeholder 엔트리
- */
-export {};

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

@@ -1,4 +0,0 @@
-/**
- * Scrollbar Utils; 현재 공개된 유틸이 없는 placeholder 엔트리
- */
-export {};

package/src/components/spinner/hooks/index.ts

@@ -1,4 +0,0 @@
-/**
- * Spinner Hooks; 현재 공개된 훅이 없는 placeholder 엔트리
- */
-export {};

package/src/components/spinner/index.scss

@@ -1 +0,0 @@
-@use "./styles/index.scss";

package/src/components/spinner/index.tsx

@@ -1,4 +0,0 @@
-/**
- * Spinner; 현재 public export가 없는 placeholder 카테고리 배럴
- */
-export * from "./markup";

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

@@ -1,4 +0,0 @@
-/**
- * Spinner Markup; 현재 공개된 컴포넌트가 없는 placeholder 엔트리
- */
-export {};