@uniai-fe/uds-primitives 0.3.59 → 0.4.0

package/src/components/dropdown/markup/Template.tsx

@@ -27,8 +27,9 @@ import {
  * @param {ReactNode} props.trigger trigger 요소
  * @param {DropdownTemplateItem[]} props.items 렌더링할 menu item 리스트
  * @param {(payload: DropdownTemplateChangePayload) => void} [props.onChange] 선택 결과 변경 콜백
- * @param {"small" | "medium" | "large"} [props.size="medium"] menu size scale
+ * @param {"xsmall" | "small" | "medium" | "large"} [props.size="medium"] menu size scale
  * @param {"match" | "fit-content" | "max-content" | string | number} [props.width="match"] panel width 옵션
+ * @param {"match" | "fit-content" | "max-content" | string | number} [props.minWidth] panel 최소 너비 옵션
  * @param {DropdownMenuProps} [props.rootProps] Dropdown.Root 전달 props
  * @param {DropdownContainerProps} [props.containerProps] Dropdown.Container 전달 props
  * @param {DropdownMenuListProps} [props.menuListProps] Dropdown.Menu.List 전달 props
@@ -40,6 +41,7 @@ const DropdownTemplate = ({
   onChange,
   size = "medium",
   width = "match",
+  minWidth,
   rootProps,
   containerProps,
   menuListProps,
@@ -199,7 +201,12 @@ const DropdownTemplate = ({
   return (
     <DropdownRoot {...rootProps}>
       <DropdownTrigger asChild>{trigger}</DropdownTrigger>
-      <DropdownContainer {...containerProps} size={size} width={width}>
+      <DropdownContainer
+        {...containerProps}
+        size={size}
+        width={width}
+        minWidth={minWidth}
+      >
         <DropdownMenuList {...menuListProps}>
           {items.length > 0 ? (
             <>

package/src/components/dropdown/markup/foundation/Container.tsx

@@ -15,6 +15,7 @@ import { useDropdownContext } from "./Provider";
  * @param {string} [props.className] panel className
  * @param {DropdownSize} [props.size="medium"] option height scale
  * @param {DropdownPanelWidth} [props.width="match"] panel width 옵션
+ * @param {DropdownPanelMinWidth} [props.minWidth] panel 최소 너비 옵션
  * @param {HTMLElement | null} [props.portalContainer] portal 컨테이너
  * @param {"start" | "center" | "end"} [props.align="start"] 정렬 기준
  * @param {"top" | "right" | "bottom" | "left"} [props.side="bottom"] 패널 위치
@@ -33,6 +34,7 @@ const DropdownContainer = forwardRef<HTMLDivElement, DropdownContainerProps>(
       className,
       size = "medium",
       width = "match",
+      minWidth,
       portalContainer,
       align = "start",
       side = "bottom",
@@ -47,29 +49,46 @@ const DropdownContainer = forwardRef<HTMLDivElement, DropdownContainerProps>(
     const [panelWidth, setPanelWidth] = useState<number>();
     const shouldMatchTriggerWidth = width === "match";
 
-    const resolvedMinWidth = useMemo(() => {
-      if (shouldMatchTriggerWidth) {
+    const resolvePanelSizeValue = (
+      value?: string | number,
+      fallbackToMatch?: boolean,
+    ): string | undefined => {
+      if (value === undefined) {
         return undefined;
       }
 
-      if (typeof width === "number") {
-        return `${width}px`;
+      if (typeof value === "number") {
+        return `${value}px`;
       }
 
-      if (typeof width === "string") {
-        if (width === "fit-content") {
+      if (typeof value === "string") {
+        if (value === "fit-content") {
           return "fit-content";
         }
-        if (width === "max-content") {
+        if (value === "max-content") {
           return "max-content";
         }
-        if (width.trim().length > 0 && width !== "match") {
-          return width;
+        if (fallbackToMatch && value === "match" && panelWidth) {
+          return `${panelWidth}px`;
+        }
+        if (value.trim().length > 0 && value !== "match") {
+          return value;
         }
       }
 
       return undefined;
-    }, [shouldMatchTriggerWidth, width]);
+    };
+    const resolvedWidth = useMemo(() => {
+      if (shouldMatchTriggerWidth) {
+        return panelWidth ? `${panelWidth}px` : undefined;
+      }
+
+      return resolvePanelSizeValue(width);
+    }, [panelWidth, shouldMatchTriggerWidth, width]);
+    const resolvedMinWidth = useMemo(() => {
+      // 변경 설명: width 계약은 기준 폭, minWidth 계약은 최소 보장 폭으로 분리한다.
+      return resolvePanelSizeValue(minWidth, true);
+    }, [minWidth, panelWidth]);
 
     useEffect(() => {
       if (!shouldMatchTriggerWidth) {
@@ -110,8 +129,7 @@ const DropdownContainer = forwardRef<HTMLDivElement, DropdownContainerProps>(
         className={clsx("dropdown-panel", `dropdown-panel-${size}`, className)}
         style={{
           ...style,
-          width:
-            shouldMatchTriggerWidth && panelWidth ? panelWidth : style?.width,
+          width: resolvedWidth ?? style?.width,
           minWidth:
             resolvedMinWidth !== undefined ? resolvedMinWidth : style?.minWidth,
         }}

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

@@ -2,16 +2,15 @@ import { DropdownFoundation } from "./foundation";
 import DropdownTemplate from "./Template";
 
 /**
- * Dropdown
- * - Provider
- * - Root
- * - Container
- * - Menu
- *     - Item
- *     - List
- * - Panel
- * - Trigger
- * - Template
+ * Dropdown; 컴포넌트 모듈
+ * @namespace Dropdown
+ * - `Dropdown.Provider`
+ * - `Dropdown.Root`
+ * - `Dropdown.Trigger`
+ * - `Dropdown.Container`
+ * - `Dropdown.Menu.Item`
+ * - `Dropdown.Menu.List`
+ * - `Dropdown.Template`
  */
 export const Dropdown = {
   ...DropdownFoundation,

package/src/components/dropdown/types/base.ts

@@ -16,3 +16,16 @@ export type DropdownPanelWidth =
   | "max-content"
   | string
   | number;
+
+/**
+ * Dropdown panel min-width 옵션
+ * - "match": trigger width를 최소 폭으로 보장
+ * - "fit-content" | "max-content": 콘텐츠 기준 최소 폭
+ * - string/number: 커스텀 최소 폭
+ */
+export type DropdownPanelMinWidth =
+  | "match"
+  | "fit-content"
+  | "max-content"
+  | string
+  | number;

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

@@ -6,7 +6,11 @@ import type {
 import type { HTMLAttributes, ReactNode, RefObject } from "react";
 
 import type { CheckboxProps } from "../../checkbox/types";
-import type { DropdownPanelWidth, DropdownSize } from "./base";
+import type {
+  DropdownPanelMinWidth,
+  DropdownPanelWidth,
+  DropdownSize,
+} from "./base";
 
 /**
  * Dropdown template value 타입
@@ -17,6 +21,7 @@ export type DropdownTemplateValue = string | number;
  * Dropdown Container props
  * @property {DropdownSize} [size="medium"] option 높이 스케일
  * @property {DropdownPanelWidth} [width="match"] dropdown panel width 옵션
+ * @property {DropdownPanelMinWidth} [minWidth] dropdown panel 최소 너비 옵션
  * @property {HTMLElement | null} [portalContainer] portal을 렌더링할 DOM 컨테이너
  */
 export interface DropdownContainerProps extends DropdownMenuContentProps {
@@ -28,6 +33,10 @@ export interface DropdownContainerProps extends DropdownMenuContentProps {
    * trigger 너비에 맞춰 dropdown 너비를 맞출지 여부
    */
   width?: DropdownPanelWidth;
+  /**
+   * dropdown 최소 너비 제약
+   */
+  minWidth?: DropdownPanelMinWidth;
   /**
    * portal을 렌더링할 DOM 컨테이너
    */
@@ -191,6 +200,7 @@ export interface DropdownTemplateChangePayload {
  * @property {(payload: DropdownTemplateChangePayload) => void} [onChange] 선택 결과 변경 콜백
  * @property {DropdownSize} [size="medium"] surface height scale
  * @property {DropdownPanelWidth} [width="match"] panel width 옵션
+ * @property {DropdownPanelMinWidth} [minWidth] panel 최소 너비 옵션
  * @property {DropdownMenuProps} [rootProps] Root 에 전달할 props
  * @property {DropdownContainerProps} [containerProps] Container 에 전달할 props
  * @property {DropdownMenuListProps} [menuListProps] MenuList 에 전달할 props
@@ -205,6 +215,10 @@ export interface DropdownTemplateProps {
   onChange?: (payload: DropdownTemplateChangePayload) => void;
   size?: DropdownSize;
   width?: DropdownPanelWidth;
+  /**
+   * panel 최소 너비 옵션
+   */
+  minWidth?: DropdownPanelMinWidth;
   /**
    * Root 에 전달할 props
    * - 타입 출처를 명확히 하기 위해 Radix 원본 타입을 직접 사용한다.
@@ -213,7 +227,10 @@ export interface DropdownTemplateProps {
   /**
    * Container 에 전달할 props
    */
-  containerProps?: Omit<DropdownContainerProps, "children" | "size" | "width">;
+  containerProps?: Omit<
+    DropdownContainerProps,
+    "children" | "size" | "width" | "minWidth"
+  >;
   /**
    * MenuList 에 전달할 props
    */

package/src/components/form/index.tsx

@@ -1,3 +1,10 @@
+/**
+ * Form; provider + field layout 카테고리 배럴
+ * @desc
+ * - `Form.Provider`: react-hook-form provider 래퍼다.
+ * - `Form.Field.*`: Container/Header/Body/Footer/Template 레이아웃 도구다.
+ * - `getFormFieldWidthAttr`, `getFormFieldWidthValue`: width 계산 util이다.
+ */
 import "./index.scss";
 
 export { Form } from "./markup";

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

@@ -2,8 +2,12 @@ import FormProvider from "./Provider";
 import { FormField } from "./form-field";
 
 /**
- * Form namespace 조립 전용 파일.
- * - index.tsx 배럴 파일에서 로직/객체 생성을 분리한다.
+ * Form; provider + field layout namespace
+ * @desc
+ * - `Form.Provider`: react-hook-form provider 래퍼다.
+ * - `Form.Field.Container`: field 루트 wrapper다.
+ * - `Form.Field.Header`, `Form.Field.Body`, `Form.Field.Footer`: depth 고정 섹션이다.
+ * - `Form.Field.Template`: 반복 조합용 필드 템플릿이다.
  */
 export const Form = {
   Provider: FormProvider,

package/src/components/info-box/index.tsx

@@ -1,3 +1,10 @@
+/**
+ * InfoBox; 안내/상태 메시지 카테고리 배럴
+ * @desc
+ * - `InfoBox`: heading/body를 렌더링하는 루트 컴포넌트다.
+ * - `InfoBoxIcon`: state별 아이콘 맵이다.
+ * - `InfoBoxProps`, `InfoBoxState`: public contract 타입이다.
+ */
 import "./index.scss";
 
 export * from "./markup";

package/src/components/info-box/markup/InfoBox.tsx

@@ -7,7 +7,7 @@ import { InfoBoxIcon } from "./Icon";
  * InfoBox Component; 안내 메시지 전용 정보 박스
  * @component
  * @param {InfoBoxProps} props
- * @param {"info"} [props.state="info"] 현재는 info 상태만 지원한다.
+ * @param {"info" | "caution" | "success" | "error"} [props.state="info"] 안내/상태 메시지 시각 축이다.
  * @param {React.ReactNode} [props.heading] 상단 제목 영역.
  * @param {React.ReactNode} [props.children] 본문 콘텐츠.
  * @param {string} [props.className] 루트 section className.

package/src/components/info-box/markup/index.ts

@@ -1,2 +1,8 @@
+/**
+ * InfoBox; 안내/상태 메시지 markup export 배럴
+ * @desc
+ * - `InfoBox`: heading/body를 렌더링하는 루트 컴포넌트다.
+ * - `InfoBoxIcon`: state별 아이콘 맵이다.
+ */
 export { default as InfoBox } from "./InfoBox";
 export * from "./Icon";

package/src/components/info-box/types/props.ts

@@ -7,7 +7,7 @@ type NativeSectionProps = Omit<ComponentPropsWithoutRef<"section">, "title">;
 
 /**
  * InfoBox Props; info-box 루트 속성
- * @property {"info" | "caution" | "success" | "error"} [state] state 값. 현재는 info만 허용한다.
+ * @property {"info" | "caution" | "success" | "error"} [state] info/caution/success/error 상태 축이다.
  * @property {ReactNode} [heading] 상단 제목 콘텐츠
  * @property {ReactNode} [children] 본문 콘텐츠
  * @property {string} [className] 루트 section className
@@ -15,7 +15,7 @@ type NativeSectionProps = Omit<ComponentPropsWithoutRef<"section">, "title">;
  */
 export interface InfoBoxProps extends Omit<NativeSectionProps, "children"> {
   /**
-   * state 값. 현재는 info만 허용한다.
+   * info/caution/success/error 상태 축이다.
    * - info, caution, success, error
    */
   state?: InfoBoxState;

package/src/components/input/index.tsx

@@ -1,5 +1,10 @@
 /**
- * input 카테고리 배럴 placeholder: 실제 구현은 markup/ 하위에 추가한다.
+ * Input; namespace 배럴 export
+ * @desc
+ * - `Input.Base`, `Input.TextArea`: foundation control
+ * - `Input.Text.*`: text scenario wrappers
+ * - `Input.Date`, `Input.Address`, `Input.File`: category presets
+ * - hooks/utils/types는 별도 배럴로 함께 export한다
  */
 import "./index.scss";
 

package/src/components/input/markup/foundation/Input.tsx

@@ -34,7 +34,7 @@ import InputBaseUtil from "./Utility";
  * @param {"default" | "active" | "focused" | "success" | "error" | "disabled" | "loading"} [props.state="default"] 시각 상태(tertiary는 disabled 외 feedback color 미적용)
  * @param {boolean} [props.block=false] true면 width 100% (`priority="table"`은 width 미지정 시 full 기본)
  * @param {React.ReactNode} [props.inlineLabel] tertiary border 내부 상단 라벨
- * @param {FormFieldWidth} [props.width] width preset
+ * @param {"full" | "fit" | "fill" | "auto" | number | string} [props.width] width preset 또는 custom width
  * @param {React.ReactNode} [props.left] 입력 왼쪽 슬롯(아이콘/텍스트)
  * @param {React.ReactNode} [props.right] 입력 오른쪽 슬롯
  * @param {React.ReactNode} [props.clear] 입력값 초기화 아이콘. 지정하지 않으면 기본 Reset 아이콘
@@ -54,7 +54,7 @@ import InputBaseUtil from "./Utility";
  * @param {string | number | readonly string[]} [props.value] 제어형 값
  * @param {string | number | readonly string[]} [props.defaultValue] 비제어 초기값
  * @param {string} [props.type="text"] native input type
- * @param {boolean} [props.readOnly] native readOnly
+ * @param {boolean} [props.readOnly] native readOnly. value가 없으면 placeholder는 alternative 토큰으로 그대로 노출된다.
  */
 const InputBase = forwardRef<HTMLInputElement, InputProps>(
   (