@uniai-fe/uds-primitives 0.3.59 → 0.4.0

package/src/components/alternate/index.tsx

@@ -1,4 +1,10 @@
 /**
- * alternate 카테고리 배럴 placeholder: 실제 구현은 markup/ 하위에 추가한다.
+ * Alternate; empty/loading fallback 유닛 카테고리 배럴
+ * @desc
+ * - `Alternate.EmptyData`: 빈 데이터 안내 레이아웃이다.
+ * - `Alternate.LoadingDefault`: 로딩 아이콘과 안내 문구를 함께 렌더링한다.
+ * - `Alternate.LoadingIcon`: 단독 스피너 아이콘이다.
+ * - `Alternate.Text`: fallback 문구 스타일 슬롯이다.
  */
 export { default as Alternate } from "./markup";
+export type * from "./types";

package/src/components/alternate/markup/Label.tsx

@@ -1,9 +1,14 @@
 import { Slot } from "../../slot";
+import type { AlternateTextProps } from "../types";
 
-export default function AlternateText({
-  children,
-}: {
-  children: React.ReactNode;
-}) {
+/**
+ * Alternate Text; fallback 문구 슬롯
+ * @component
+ * @param {AlternateTextProps} props
+ * @param {React.ReactNode} props.children 렌더링할 문구 콘텐츠다.
+ * @example
+ * <Alternate.Text>데이터가 없습니다.</Alternate.Text>
+ */
+export default function AlternateText({ children }: AlternateTextProps) {
   return <Slot.Text className="alternate-text">{children}</Slot.Text>;
 }

package/src/components/alternate/markup/empty/Data.tsx

@@ -2,20 +2,23 @@
 
 import { clsx } from "clsx";
 import AlternateText from "../Label";
+import type { AlternateEmptyDataProps } from "../../types";
 
 /**
- * 차트; 데이터 없는 경우 대체 컴포넌트
+ * Alternate EmptyData; 빈 데이터 안내 레이아웃
  * @component
+ * @param {AlternateEmptyDataProps} props
+ * @param {string} [props.className] 루트 className override다.
+ * @param {"vertical" | "horizontal"} [props.direction="vertical"] 아이콘/문구 배치 방향이다.
+ * @param {React.ReactNode} [props.children] 안내 문구 콘텐츠다. 비어 있으면 기본 문구를 사용한다.
+ * @example
+ * <Alternate.EmptyData direction="horizontal">데이터가 없습니다.</Alternate.EmptyData>
  */
 export default function AlternateEmptyData({
   className,
   direction = "vertical",
   children: text,
-}: Partial<{
-  className: string;
-  direction: "vertical" | "horizontal";
-  children: React.ReactNode;
-}>) {
+}: AlternateEmptyDataProps) {
   const directionClass =
     direction === "horizontal" ? "is-horizontal" : "is-vertical";
 

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

@@ -3,6 +3,14 @@ import AlternateText from "./Label";
 import AlternateLoadingDefault from "./loading/Default";
 import AlternateLoadingIcon from "./loading/Icon";
 
+/**
+ * Alternate; empty/loading fallback namespace
+ * @desc
+ * - `Alternate.EmptyData`: 빈 데이터 안내 레이아웃이다.
+ * - `Alternate.LoadingDefault`: 로딩 안내 레이아웃이다.
+ * - `Alternate.LoadingIcon`: 단독 스피너 아이콘이다.
+ * - `Alternate.Text`: 안내 문구 슬롯이다.
+ */
 const Alternate = {
   EmptyData: AlternateEmptyData,
   LoadingDefault: AlternateLoadingDefault,

package/src/components/alternate/markup/loading/Default.tsx

@@ -3,25 +3,29 @@
 import { clsx } from "clsx";
 import AlternateLoadingIcon from "./Icon";
 import AlternateText from "../Label";
+import type { AlternateLoadingDefaultProps } from "../../types";
 
 /**
- * 데이터 로딩중 컴포넌트
+ * Alternate LoadingDefault; 로딩 안내 레이아웃
  * @component
+ * @param {AlternateLoadingDefaultProps} props
+ * @param {"vertical" | "horizontal"} [props.direction="vertical"] 아이콘/문구 배치 방향이다.
+ * @param {React.ReactNode} [props.children] 안내 문구 콘텐츠다. 비어 있으면 기본 문구를 사용한다.
+ * @example
+ * <Alternate.LoadingDefault>데이터를 불러오는 중입니다.</Alternate.LoadingDefault>
  */
 export default function AlternateLoadingDefault({
   direction = "vertical",
   children: text,
-}: Partial<{
-  direction: "vertical" | "horizontal";
-  children: React.ReactNode;
-}>) {
+}: AlternateLoadingDefaultProps) {
   const directionClass =
     direction === "horizontal" ? "is-horizontal" : "is-vertical";
 
   return (
     <div className={clsx("alternate loading", directionClass)}>
       <AlternateLoadingIcon direction={direction} />
-      {["string", "undefined"].includes(typeof text) ? (
+      {/* string/number만 Slot.Text로 감싸고, 그 외 ReactNode는 그대로 렌더링한다. */}
+      {["string", "number", "undefined"].includes(typeof text) ? (
         <AlternateText>{text || "데이터를 불러오는 중입니다."}</AlternateText>
       ) : (
         text

package/src/components/alternate/markup/loading/Icon.tsx

@@ -4,14 +4,21 @@ import { clsx } from "clsx";
 import SpinnerSmallIcon from "../../img/spinner-small-24x24.svg";
 import SpinnerMediumIcon from "../../img/spinner-medium-36x36.svg";
 import SpinnerLargeIcon from "../../img/spinner-large-52x52.svg";
+import type { AlternateLoadingIconProps } from "../../types";
 
+/**
+ * Alternate LoadingIcon; 단독 스피너 아이콘
+ * @component
+ * @param {AlternateLoadingIconProps} props
+ * @param {"small" | "medium" | "large"} [props.size="small"] 로딩 아이콘 스케일이다.
+ * @param {"vertical" | "horizontal"} [props.direction] 부모 레이아웃 방향 클래스 동기화용 값이다.
+ * @example
+ * <Alternate.LoadingIcon size="medium" />
+ */
 export default function AlternateLoadingIcon({
   size = "small",
   direction,
-}: {
-  size?: "small" | "medium" | "large";
-  direction?: "vertical" | "horizontal";
-}) {
+}: AlternateLoadingIconProps) {
   const directionClass =
     direction === "horizontal" ? "is-horizontal" : "is-vertical";
   const sizeClass = size ? `is-${size}` : undefined;

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

@@ -1,4 +1,77 @@
+import type { ReactNode } from "react";
+
 /**
- * TODO(alternate): variant/slot 타입 정의를 작성한다.
+ * Alternate Direction; fallback 레이아웃 방향 축
+ * @typedef {"vertical" | "horizontal"} AlternateDirection
  */
-export {};
+export type AlternateDirection = "vertical" | "horizontal";
+
+/**
+ * Alternate Loading Icon Size; 로딩 아이콘 스케일 축
+ * @typedef {"small" | "medium" | "large"} AlternateLoadingIconSize
+ */
+export type AlternateLoadingIconSize = "small" | "medium" | "large";
+
+/**
+ * Alternate Text Props; fallback 문구 슬롯 props
+ * @property {ReactNode} children 렌더링할 문구 콘텐츠다.
+ */
+export interface AlternateTextProps {
+  /**
+   * 렌더링할 문구 콘텐츠다.
+   */
+  children: ReactNode;
+}
+
+/**
+ * Alternate Empty Data Props; 빈 데이터 안내 레이아웃 props
+ * @property {string} [className] 루트 className override다.
+ * @property {"vertical" | "horizontal"} [direction] 아이콘/문구 배치 방향이다.
+ * @property {ReactNode} [children] 안내 문구 콘텐츠다.
+ */
+export interface AlternateEmptyDataProps {
+  /**
+   * 루트 className override다.
+   */
+  className?: string;
+  /**
+   * 아이콘/문구 배치 방향이다.
+   */
+  direction?: AlternateDirection;
+  /**
+   * 안내 문구 콘텐츠다.
+   */
+  children?: ReactNode;
+}
+
+/**
+ * Alternate Loading Default Props; 로딩 안내 레이아웃 props
+ * @property {"vertical" | "horizontal"} [direction] 아이콘/문구 배치 방향이다.
+ * @property {ReactNode} [children] 안내 문구 콘텐츠다.
+ */
+export interface AlternateLoadingDefaultProps {
+  /**
+   * 아이콘/문구 배치 방향이다.
+   */
+  direction?: AlternateDirection;
+  /**
+   * 안내 문구 콘텐츠다.
+   */
+  children?: ReactNode;
+}
+
+/**
+ * Alternate Loading Icon Props; 단독 스피너 아이콘 props
+ * @property {"small" | "medium" | "large"} [size] 로딩 아이콘 스케일이다.
+ * @property {"vertical" | "horizontal"} [direction] 부모 레이아웃 방향 클래스 동기화용 값이다.
+ */
+export interface AlternateLoadingIconProps {
+  /**
+   * 로딩 아이콘 스케일이다.
+   */
+  size?: AlternateLoadingIconSize;
+  /**
+   * 부모 레이아웃 방향 클래스 동기화용 값이다.
+   */
+  direction?: AlternateDirection;
+}

package/src/components/badge/index.tsx

@@ -1,5 +1,8 @@
 /**
- * badge 카테고리 배럴 placeholder: 실제 구현은 markup/ 하위에 추가한다.
+ * Badge; status/info label 렌더링 카테고리 배럴
+ * @desc
+ * - `Badge`: size/style/intent/tone 축을 렌더링하는 단일 leaf 컴포넌트다.
+ * - `BadgeProps`: badge public props 계약이다.
  */
 import "./index.scss";
 

package/src/components/badge/markup/Badge.tsx

@@ -4,17 +4,19 @@ import { composeBadgeClassName } from "../utils";
 import { Slot } from "../../slot";
 
 /**
- * Badge 컴포넌트; size/style/intent 축을 data attribute로 노출한다.
+ * Badge; status/info label 렌더링 leaf 컴포넌트
  * @component
  * @param {BadgeProps} props
- * @param {"xsmall" | "small"} [props.size="xsmall"] 토큰 size.
- * @param {"fill" | "outlined" | "dot"} [props.style="fill"] 시각 스타일.
+ * @param {"xsmall" | "small"} [props.size="xsmall"] 토큰 size 축이다.
+ * @param {"fill" | "outlined" | "dot"} [props.style="fill"] 시각 스타일 축이다.
  * @param {"primary" | "secondary" | "tertiary" | "gray" | "green" | "yellow" | "orange" | "red"} [props.intent="primary"]
- *  fill/outlined 스타일에서 사용되는 intent.
- * @param {"primary" | "feedback"} [props.tone="primary"] dot 스타일에 사용되는 tone.
- * @param {React.ReactNode} [props.children] 라벨 텍스트. dot 스타일에서 생략하면 점만 렌더.
- * @param {string} [props.className] figure className.
- * @param {React.CSSProperties} [props.inlineStyle] figure inline style.
+ *  fill/outlined 스타일에서 사용되는 intent 축이다.
+ * @param {"primary" | "feedback"} [props.tone="primary"] dot 스타일 전용 tone 축이다.
+ * @param {React.ReactNode} [props.children] 라벨 텍스트다. dot 스타일에서 생략하면 점만 렌더링한다.
+ * @param {string} [props.className] figure root className override다.
+ * @param {React.CSSProperties} [props.inlineStyle] figure root inline style이다.
+ * @example
+ * <Badge style="fill" intent="primary">승인됨</Badge>
  */
 const Badge = forwardRef<HTMLElementTagNameMap["figure"], BadgeProps>(
   (

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

@@ -1,4 +1,4 @@
-import type { ComponentPropsWithoutRef, ReactNode } from "react";
+import type { CSSProperties, ComponentPropsWithoutRef, ReactNode } from "react";
 
 export const BADGE_SIZES = ["xsmall", "small"] as const;
 export const BADGE_STYLES = ["fill", "outlined", "dot"] as const;
@@ -21,6 +21,15 @@ export type BadgeTone = (typeof BADGE_TONES)[number];
 
 type NativeFigureProps = Omit<ComponentPropsWithoutRef<"figure">, "style">;
 
+/**
+ * Badge Props; status/info label badge public props
+ * @property {ReactNode} [children] 표시할 라벨이다. 생략하면 dot만 렌더링한다.
+ * @property {"xsmall" | "small"} [size] Figma size 축이다.
+ * @property {"fill" | "outlined" | "dot"} [style] badge 시각 스타일 축이다.
+ * @property {"primary" | "secondary" | "tertiary" | "gray" | "green" | "yellow" | "orange" | "red"} [intent] fill/outlined 변형의 색상 의도다.
+ * @property {"primary" | "feedback"} [tone] dot 변형 전용 tone 축이다.
+ * @property {CSSProperties} [inlineStyle] 원본 figure 요소에 적용할 inline style이다.
+ */
 export interface BadgeProps extends Omit<NativeFigureProps, "children"> {
   /**
    * 표시할 라벨. 생략하면 dot 스타일만 렌더링된다.
@@ -45,11 +54,26 @@ export interface BadgeProps extends Omit<NativeFigureProps, "children"> {
   /**
    * 원본 figure 요소에 적용할 인라인 스타일.
    */
-  inlineStyle?: ComponentPropsWithoutRef<"figure">["style"];
+  inlineStyle?: CSSProperties;
 }
 
+/**
+ * Badge ClassName Options; badge root className 조합 입력값
+ * @property {"xsmall" | "small"} size badge size 축이다.
+ * @property {"fill" | "outlined" | "dot"} style badge style 축이다.
+ * @property {string} [className] 외부 className override다.
+ */
 export interface BadgeClassNameOptions {
+  /**
+   * badge size 축이다.
+   */
   size: BadgeSize;
+  /**
+   * badge style 축이다.
+   */
   style: BadgeStyle;
+  /**
+   * 외부 className override다.
+   */
   className?: string;
 }

package/src/components/button/index.tsx

@@ -1,5 +1,10 @@
 /**
- * button 카테고리 배럴 placeholder: 실제 구현은 markup/ 하위에 추가한다.
+ * Button; namespace 배럴 export
+ * @desc
+ * - `Button.Default`: fill/priority/size 축 기반 기본 버튼
+ * - `Button.Text`: text action 템플릿
+ * - `Button.Rounded`: round icon action 템플릿
+ * - `Button.Label`: button-label className 고정 래퍼
  */
 import "./index.scss";
 

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

@@ -11,27 +11,29 @@ import {
 } from "../../form/utils/form-field";
 
 /**
- * uds-foundation 토큰 위에서 block/layout/priority/slot API를 제공하는 기본 Button 컴포넌트.
+ * Button Component; Default action button
  * @component
  * @param {ButtonProps} props
- * @param {ElementType} [props.as="button"] 커스텀 요소(Renderer).
- * @param {React.ReactNode} [props.children] 문자열이면 `.button-label` span으로 감싼다.
- * @param {React.ReactNode} [props.left] 라벨 왼쪽 커스텀 슬롯.
- * @param {React.ReactNode} [props.right] 라벨 오른쪽 커스텀 슬롯.
- * @param {
- *  "solid-xlarge" | "solid-large" | "solid-medium" | "solid-small" |
- *  "outlined-xlarge" | "outlined-large" | "outlined-medium" | "outlined-small"
- * } [props.scale="solid-medium"] legacy spacing 식별자. fill/size가 없을 때만 fallback 용도로 사용한다.
- * @param {"solid" | "outlined"} [props.fill] 채움 스타일. scale과 별개로 직접 지정할 수 있다.
- * @param {"xlarge" | "large" | "medium" | "small" | "table"} [props.size] 버튼 높이/타이포 스케일. table은 셀 액션용 compact(24px) 규격이다.
- * @param {"primary" | "secondary" | "tertiary"} [props.priority="primary"] semantic color 세트.
- * @param {"default" | "readonly" | "disabled"} [props.state="default"] 내부 state. disabled prop과 조합된다.
- * @param {boolean} [props.block=false] true면 width 100%.
- * @param {boolean} [props.loading=false] true면 readonly 처리 + aria-busy.
+ * @param {ElementType} [props.as="button"] 렌더링할 요소.
+ * @param {React.ReactNode} [props.children] 문자열/숫자는 `.button-label`로 래핑하고, 그 외 ReactNode는 그대로 렌더링한다.
+ * @param {"solid-xlarge" | "solid-large" | "solid-medium" | "solid-small" | "outlined-xlarge" | "outlined-large" | "outlined-medium" | "outlined-small"} [props.scale] legacy fill/size fallback 식별자.
+ * @param {"solid" | "outlined"} props.fill 채움 스타일.
+ * @param {"xlarge" | "large" | "medium" | "small" | "table"} props.size 버튼 크기. `table`은 Table 셀 액션용 compact 규격이다.
+ * @param {"primary" | "secondary" | "tertiary"} props.priority semantic color priority.
+ * @param {"default" | "readonly" | "disabled"} [props.state="default"] 내부 상태. `disabled`/`loading`과 병합된다.
+ * @param {boolean} [props.block=false] true면 폭을 100%로 확장한다.
+ * @param {"full" | "fit" | "fill" | "auto" | number | string} [props.width] Form.Field width preset 또는 custom width.
+ * @param {boolean} [props.loading=false] true면 readonly 상태와 `aria-busy`를 강제한다.
+ * @param {React.ReactNode} [props.left] 라벨 왼쪽 콘텐츠.
+ * @param {React.ReactNode} [props.right] 라벨 오른쪽 콘텐츠.
  * @param {string} [props.className] 추가 className.
- * @param {"button" | "submit" | "reset"} [props.type="button"] button 요소일 때 type.
- * @param {boolean} [props.disabled] native disabled. state보다 우선한다.
- * @param {"hover" | "pressed"} [props.data-user-action] Story 시각 상태 고정용 data attr.
+ * @param {"button" | "submit" | "reset"} [props.type="button"] `button` 태그일 때 native type.
+ * @param {boolean} [props.disabled] native disabled. `state`보다 우선한다.
+ * @param {"hover" | "pressed"} [props["data-user-action"]] Storybook 시각 상태 고정용 data attribute.
+ * @example
+ * <Button.Default fill="solid" size="medium" priority="primary">
+ *   확인
+ * </Button.Default>
  */
 const ButtonDefault = forwardRef<HTMLElement, ButtonProps>(
   (

package/src/components/button/markup/Rounded.tsx

@@ -4,12 +4,15 @@ import type { RoundButtonProps } from "../types";
 import { ButtonDefault } from "./Base";
 
 /**
- * 원형 버튼 템플릿. size만 받으면 적절한 scale을 선택하고 라운드 전용 className을 적용한다.
+ * Button Component; Rounded action button
  * @component
  * @param {RoundButtonProps} props
- * @param {"small" | "medium" | "large"} props.size size에 따라 scale을 매핑한다.
- * @param {"primary" | "secondary" | "tertiary"} props.priority semantic color.
- * @param {boolean} [props.block] width 확장 여부.
+ * @param {"small" | "medium" | "large"} props.size 라운드 버튼 크기 축.
+ * @param {"primary" | "secondary" | "tertiary"} props.priority semantic color priority.
+ * @example
+ * <Button.Rounded size="small" priority="primary" aria-label="추가">
+ *   <span aria-hidden="true">+</span>
+ * </Button.Rounded>
  */
 const ButtonRounded = forwardRef<HTMLElement, RoundButtonProps>(
   // 라운드 전용 템플릿도 fill/size/priority를 직접 주입해 공통 규칙을 따른다.

package/src/components/button/markup/Text.tsx

@@ -4,12 +4,15 @@ import type { TextButtonProps } from "../types";
 import { ButtonDefault } from "./Base";
 
 /**
- * 텍스트 링크형 버튼 템플릿. size/priority 조합만 노출하고 나머지는 ButtonDefault에서 처리한다.
+ * Button Component; Text action button
  * @component
  * @param {TextButtonProps} props
- * @param {"small" | "medium" | "large"} props.size size에 따른 scale 파생.
- * @param {"secondary" | "tertiary"} props.priority semantic color.
- * @param {boolean} [props.block] 텍스트 버튼도 block 확장 가능.
+ * @param {"small" | "medium" | "large"} props.size 텍스트 버튼 크기 축.
+ * @param {"secondary" | "tertiary"} props.priority 텍스트 버튼 priority 축.
+ * @example
+ * <Button.Text size="medium" priority="secondary">
+ *   자세히 보기
+ * </Button.Text>
  */
 const ButtonText = forwardRef<HTMLElement, TextButtonProps>(
   // 템플릿 레벨에서 fill/size/priority를 강제해 ButtonDefault 정책과 동기화한다.

package/src/components/calendar/index.tsx

@@ -1,3 +1,11 @@
+/**
+ * Calendar; date picker 조합 카테고리 배럴
+ * @desc
+ * - `Calendar.Root`: trigger + popover + core 조합 템플릿이다.
+ * - `Calendar.Container`: Header/Body/Footer 레이아웃 컨테이너다.
+ * - `Calendar.Core`: Mantine DatePicker SOT 렌더러다.
+ * - `CalendarHooks`, `CalendarUtils`: 관련 hook/util namespace다.
+ */
 import "./index.scss";
 
 export * from "./markup";

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

@@ -7,13 +7,13 @@ import CalendarRoot from "./Root";
 import { CalendarIcon } from "./Icon";
 
 /**
- * Calendar namespace.
- * - Root
- * - Container
- * - Header
- * - Body
- * - Footer
- * - Core
+ * Calendar; date picker namespace
+ * @desc
+ * - `Calendar.Root`: trigger + popover + core 조합 템플릿이다.
+ * - `Calendar.Container`: Header/Body/Footer 레이아웃 컨테이너다.
+ * - `Calendar.Header`, `Calendar.Body`, `Calendar.Footer`: depth 고정 레이아웃 섹션이다.
+ * - `Calendar.Core`: Mantine DatePicker SOT 렌더러다.
+ * - `Calendar.Icon`: 입력/네비게이션 아이콘 namespace다.
  */
 export const Calendar = {
   Root: CalendarRoot,

package/src/components/carousel/index.tsx

@@ -1,3 +1,11 @@
+/**
+ * Carousel; viewport scroll carousel 카테고리 배럴
+ * @desc
+ * - `Carousel.Provider`: viewport/track 상태 공유 루트다.
+ * - `Carousel.Track`: viewport + track 렌더러다.
+ * - `Carousel.Control`, `Carousel.Button.*`: 이동 제어 도구다.
+ * - `useCarousel`: provider context 접근 hook이다.
+ */
 import "./index.scss";
 
 export * from "./markup";

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

@@ -6,6 +6,15 @@ import { CarouselPrevButton } from "./button/Prev";
 import { CarouselProvider } from "./Provider";
 import { CarouselTrack } from "./Track";
 
+/**
+ * Carousel; viewport scroll carousel namespace
+ * @desc
+ * - `Carousel.Provider`: viewport/track 상태 공유 루트다.
+ * - `Carousel.Container`: Provider + Control 프리셋이다.
+ * - `Carousel.Control`: Prev/Track/Next 조합 컨트롤이다.
+ * - `Carousel.Track`: viewport + track 렌더러다.
+ * - `Carousel.Button.Base|Prev|Next`: 이동 제어 leaf 버튼이다.
+ */
 export const Carousel = {
   Provider: CarouselProvider,
   Container: CarouselContainer,

package/src/components/checkbox/index.tsx

@@ -1,3 +1,10 @@
+/**
+ * Checkbox; namespace 배럴 export
+ * @desc
+ * - `Checkbox`: leaf checkbox control
+ * - `CheckboxField`: label/helper 포함 field wrapper
+ * - hooks/types는 별도 배럴로 함께 export한다
+ */
 import "./index.scss";
 
 export * from "./markup";

package/src/components/chip/index.tsx

@@ -1,5 +1,11 @@
 /**
- * chips 카테고리 배럴
+ * Chip; filter/assist/input chip 카테고리 배럴
+ * @desc
+ * - `Chip.Default`: style 분기 루트 컴포넌트다.
+ * - `Chip.ClickableStyle`: filter/assist button 렌더 전용 leaf다.
+ * - `Chip.InputStyle`: input figure 렌더 전용 leaf다.
+ * - `Chip.List`: chip 목록 템플릿이다.
+ * - `ChipProps`, `ChipListRootProps`, `ChipListItemData`: public contract 타입이다.
  */
 import "./index.scss";
 

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

@@ -4,6 +4,15 @@ import ChipInputStyle from "./InputStyle";
 import ChipLabel from "./Label";
 import { ChipListRoot } from "./ListRoot";
 
+/**
+ * Chip; filter/assist/input namespace
+ * @desc
+ * - `Chip.Default`: style 분기 루트 컴포넌트다.
+ * - `Chip.ClickableStyle`: filter/assist button 렌더 전용 leaf다.
+ * - `Chip.InputStyle`: input figure 렌더 전용 leaf다.
+ * - `Chip.Label`: chip 텍스트 슬롯이다.
+ * - `Chip.List`: chip 목록 템플릿이다.
+ */
 export const Chip = {
   Default: ChipDefault,
   ClickableStyle: ChipClickableStyle,

package/src/components/divider/index.tsx

@@ -1,5 +1,9 @@
 import "./index.scss";
 
+/**
+ * Divider; 방향 전환형 구분선 엔트리
+ */
 import { Divider } from "./markup";
+export type * from "./types";
 
 export { Divider };

package/src/components/divider/markup/Divider.tsx

@@ -1,11 +1,15 @@
 import clsx from "clsx";
+import type { DividerProps } from "../types";
 
-export function Divider({
-  className,
-  direction = "vertical",
-}: {
-  className?: string;
-  direction?: "horizontal" | "vertical";
-}) {
+/**
+ * Divider; 수평/수직 구분선 마크업
+ * @component
+ * @param {DividerProps} props
+ * @param {string} [props.className] divider 루트 className
+ * @param {"horizontal" | "vertical"} [props.direction] 구분선 방향
+ * @example
+ * <Divider direction="horizontal" />
+ */
+export function Divider({ className, direction = "vertical" }: DividerProps) {
   return <div className={clsx("divider", direction, className)}></div>;
 }

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

@@ -0,0 +1 @@
+export type { DividerDirection, DividerProps } from "./props";

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

@@ -0,0 +1,27 @@
+import type { ComponentPropsWithoutRef } from "react";
+
+/**
+ * DividerDirection; divider 방향 축
+ * @typedef {"horizontal" | "vertical"} DividerDirection
+ */
+export type DividerDirection = "horizontal" | "vertical";
+
+/**
+ * Divider Props; divider 루트 속성
+ * @property {string} [className] divider 루트 className
+ * @property {"horizontal" | "vertical"} [direction] 구분선 방향
+ * @see React.ComponentPropsWithoutRef<"div">
+ */
+export interface DividerProps extends Omit<
+  ComponentPropsWithoutRef<"div">,
+  "children"
+> {
+  /**
+   * divider 루트 className
+   */
+  className?: string;
+  /**
+   * 구분선 방향
+   */
+  direction?: DividerDirection;
+}

package/src/components/drawer/index.tsx

@@ -1,3 +1,10 @@
+/**
+ * Drawer; bottom sheet 카테고리 배럴
+ * @desc
+ * - `DrawerRoot`, `DrawerTrigger`, `DrawerPortal`, `DrawerOverlay`, `DrawerContent`: 루트/레이어 조합 축이다.
+ * - `DrawerHeader`, `DrawerBody`, `DrawerFooter`, `DrawerTitle`, `DrawerDescription`, `DrawerClose`: anatomy 도구다.
+ * - `useDrawerDrag`: handle drag 제어 hook이다.
+ */
 import "./index.scss";
 
 export * from "./markup";

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

@@ -1,3 +1,9 @@
 "use client";
 
+/**
+ * Drawer; bottom sheet markup export 배럴
+ * @desc
+ * - `DrawerRoot`, `DrawerTrigger`, `DrawerPortal`, `DrawerOverlay`, `DrawerContent`: 루트/레이어 조합 축이다.
+ * - `DrawerHeader`, `DrawerBody`, `DrawerFooter`, `DrawerTitle`, `DrawerDescription`, `DrawerClose`: anatomy 도구다.
+ */
 export * from "./Drawer";

package/src/components/dropdown/index.tsx

@@ -1,3 +1,10 @@
+/**
+ * Dropdown; namespace 배럴 export
+ * @desc
+ * - `Dropdown.Root`, `Dropdown.Trigger`, `Dropdown.Container`: foundation 레이어
+ * - `Dropdown.Menu.*`: list/item 조합 레이어
+ * - `Dropdown.Template`: items[].selected + onChange(payload) preset
+ */
 import "./index.scss";
 
 export * from "./markup";