@uniai-fe/uds-primitives 0.2.6 → 0.2.8

package/dist/styles.css

@@ -2743,6 +2743,10 @@ figure.chip {
   margin-bottom: var(--form-field-gap-y);
 }
 
+.form-field-required {
+  color: var(--color-feedback-error);
+}
+
 .form-field-label {
   display: flex;
   align-items: center;
@@ -2751,14 +2755,10 @@ figure.chip {
   font-weight: var(--form-field-label-font-weight);
   line-height: var(--form-field-label-line-height);
 }
-.form-field-label span {
+.form-field-label span:not(.form-field-required) {
   color: var(--form-field-label-color);
 }
 
-.form-field-required {
-  color: var(--color-feedback-error);
-}
-
 .form-field-body {
   display: flex;
   flex-wrap: wrap;

package/package.json

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

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

@@ -1,15 +1,15 @@
 "use client";
 
 import * as DropdownMenu from "@radix-ui/react-dropdown-menu";
+import type { DropdownMenuProps } from "@radix-ui/react-dropdown-menu";
 import type { ReactNode } from "react";
 
-import type { DropdownRootProps } from "../../types/base";
 import { DropdownProvider } from "./Provider";
 
 /**
  * Dropdown root; Provider와 Radix Root를 래핑한다.
  * @component
- * @param {DropdownRootProps} props Dropdown Root props
+ * @param {DropdownMenuProps} props Dropdown Root props
  * @param {ReactNode} props.children Dropdown 하위 node
  * @param {boolean} [props.modal=false] Radix modal 모드
  */
@@ -17,7 +17,7 @@ const DropdownRoot = ({
   children,
   modal = false,
   ...rootProps
-}: DropdownRootProps & { children: ReactNode }) => {
+}: DropdownMenuProps & { children: ReactNode }) => {
   return (
     <DropdownProvider>
       <DropdownMenu.Root modal={modal} {...rootProps}>

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

@@ -1,19 +1,19 @@
 "use client";
 
 import * as DropdownMenu from "@radix-ui/react-dropdown-menu";
+import type { DropdownMenuTriggerProps } from "@radix-ui/react-dropdown-menu";
 import { forwardRef } from "react";
 
-import type { DropdownTriggerProps } from "../../types/props";
 import { mergeRefs } from "../../utils";
 import { useDropdownContext } from "./Provider";
 
 /**
  * Dropdown trigger; trigger ref를 context에 공유한다.
  * @component
- * @param {DropdownTriggerProps} props Dropdown trigger props
+ * @param {DropdownMenuTriggerProps} props Dropdown trigger props
  * @param {boolean} [props.asChild=true] asChild 패턴 유지 여부
  */
-const DropdownTrigger = forwardRef<HTMLElement, DropdownTriggerProps>(
+const DropdownTrigger = forwardRef<HTMLElement, DropdownMenuTriggerProps>(
   ({ asChild = true, children, ...rest }, ref) => {
     const { triggerRef } = useDropdownContext("Dropdown.Trigger");
 

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

@@ -1,5 +1,3 @@
-import type { DropdownMenuProps } from "@radix-ui/react-dropdown-menu";
-
 /**
  * Dropdown size scale
  * @typedef {"small" | "medium" | "large"} DropdownSize
@@ -18,14 +16,3 @@ export type DropdownPanelWidth =
   | "max-content"
   | string
   | number;
-
-/**
- * Dropdown root props
- * @property {boolean} [modal] Radix modal 모드 여부
- */
-export interface DropdownRootProps extends DropdownMenuProps {
-  /**
-   * Radix modal 모드 여부
-   */
-  modal?: DropdownMenuProps["modal"];
-}

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

@@ -1,22 +1,12 @@
 import type {
+  DropdownMenuProps,
   DropdownMenuContentProps,
   DropdownMenuItemProps as RadixDropdownMenuItemProps,
-  DropdownMenuTriggerProps,
 } from "@radix-ui/react-dropdown-menu";
 import type { HTMLAttributes, MutableRefObject, ReactNode } from "react";
 
 import type { CheckboxProps } from "../../checkbox/types";
-import type {
-  DropdownPanelWidth,
-  DropdownRootProps,
-  DropdownSize,
-} from "./base";
-
-/**
- * Dropdown trigger props
- * @property {boolean} [asChild=true] trigger를 asChild 패턴으로 감쌀지 여부
- */
-export type DropdownTriggerProps = DropdownMenuTriggerProps;
+import type { DropdownPanelWidth, DropdownSize } from "./base";
 
 /**
  * Dropdown Container props
@@ -142,9 +132,10 @@ export interface DropdownTemplateItem {
  * @property {ReactNode} trigger trigger 요소
  * @property {DropdownTemplateItem[]} items 렌더링할 menu item 리스트
  * @property {string[]} [selectedIds] 선택된 item id 배열
+ * @property {(item: DropdownTemplateItem) => void} [onSelect] item 선택 콜백
  * @property {DropdownSize} [size="medium"] surface height scale
  * @property {DropdownPanelWidth} [width="match"] panel width 옵션
- * @property {DropdownRootProps} [rootProps] Root 에 전달할 props
+ * @property {DropdownMenuProps} [rootProps] Root 에 전달할 props
  * @property {DropdownContainerProps} [containerProps] Container 에 전달할 props
  * @property {DropdownMenuListProps} [menuListProps] MenuList 에 전달할 props
  */
@@ -157,8 +148,9 @@ export interface DropdownTemplateProps {
   width?: DropdownPanelWidth;
   /**
    * Root 에 전달할 props
+   * - 타입 출처를 명확히 하기 위해 Radix 원본 타입을 직접 사용한다.
    */
-  rootProps?: DropdownRootProps;
+  rootProps?: DropdownMenuProps;
   /**
    * Container 에 전달할 props
    */

package/src/components/form/styles/form-field/layout.scss

@@ -32,6 +32,10 @@
   margin-bottom: var(--form-field-gap-y);
 }
 
+.form-field-required {
+  color: var(--color-feedback-error);
+}
+
 .form-field-label {
   display: flex;
   align-items: center;
@@ -40,15 +44,11 @@
   font-size: var(--form-field-label-font-size);
   font-weight: var(--form-field-label-font-weight);
   line-height: var(--form-field-label-line-height);
-  span {
+  span:not(.form-field-required) {
     color: var(--form-field-label-color);
   }
 }
 
-.form-field-required {
-  color: var(--color-feedback-error);
-}
-
 .form-field-body {
   display: flex;
   flex-wrap: wrap;

package/src/components/select/markup/Default.tsx

@@ -8,10 +8,8 @@ import { Dropdown } from "../../dropdown/markup";
 import { SelectTriggerBase, SelectTriggerSelected } from "./foundation";
 import Container from "./foundation/Container";
 import { useSelectDropdownOpenState } from "../hooks";
-import type {
-  SelectDefaultComponentProps,
-  SelectDropdownOption,
-} from "../types/props";
+import type { SelectDropdownOption } from "../types/option";
+import type { SelectDefaultComponentProps } from "../types/props";
 
 /**
  * Select default trigger; 단일 선택 드롭다운을 렌더링한다.

package/src/components/select/types/option.ts

@@ -1,13 +1,87 @@
 import type { ReactNode } from "react";
 
 /**
- * Select option 값 타입
+ * Select option value 타입
  * @typedef {string | number} SelectOptionValue
  */
 export type SelectOptionValue = string | number;
 
 /**
- * Select option 데이터 구조; legacy SelectDataType과 호환되는 구조다.
+ * Select option data; form 상태와 직결되는 데이터 계약
+ * @property {string} id 렌더링/선택 추적용 고유 id
+ * @property {SelectOptionValue} value 실제 form value
+ * @property {ReactNode} label 사용자 노출 라벨
+ * @property {boolean} [disabled] 비활성 여부
+ * @property {OptionData} [data] 추가 데이터 payload
+ */
+export interface SelectOptionData<OptionData = unknown> {
+  /**
+   * 렌더링/선택 추적용 고유 id
+   */
+  id: string;
+  /**
+   * 실제 form value
+   */
+  value: SelectOptionValue;
+  /**
+   * 사용자 노출 라벨
+   */
+  label: ReactNode;
+  /**
+   * 비활성 여부
+   */
+  disabled?: boolean;
+  /**
+   * 추가 데이터 payload
+   */
+  data?: OptionData;
+}
+
+/**
+ * Select option render data; Dropdown.Menu.Item 렌더링 보조 정보
+ * @property {ReactNode} [description] 보조 텍스트
+ * @property {ReactNode} [left] 좌측 콘텐츠
+ * @property {ReactNode} [right] 우측 콘텐츠
+ * @property {boolean} [multiple] multi select 스타일 여부
+ */
+export interface SelectOptionRenderData {
+  /**
+   * 보조 텍스트
+   */
+  description?: ReactNode;
+  /**
+   * 좌측 콘텐츠
+   */
+  left?: ReactNode;
+  /**
+   * 우측 콘텐츠
+   */
+  right?: ReactNode;
+  /**
+   * multi select 스타일 여부
+   */
+  multiple?: boolean;
+}
+
+/**
+ * Select dropdown option; data 계약과 render 계약을 합쳐 Select 입력 모델을 구성한다.
+ * @extends SelectOptionData
+ * @extends SelectOptionRenderData
+ * @property {string} id 렌더링/선택 추적용 고유 id
+ * @property {SelectOptionValue} value 실제 form value
+ * @property {ReactNode} label 사용자 노출 라벨
+ * @property {boolean} [disabled] 비활성 여부
+ * @property {OptionData} [data] 추가 데이터 payload
+ * @property {ReactNode} [description] 보조 텍스트
+ * @property {ReactNode} [left] 좌측 콘텐츠
+ * @property {ReactNode} [right] 우측 콘텐츠
+ * @property {boolean} [multiple] multi select 스타일 여부
+ */
+export interface SelectDropdownOption<OptionData = unknown>
+  extends SelectOptionData<OptionData>, SelectOptionRenderData {}
+
+/**
+ * Select legacy option 데이터 구조; 과거 key/optionName 스키마 호환을 위해 유지한다.
  * @property {string} key 렌더링 키
  * @property {SelectOptionValue} value 실제 값
  * @property {ReactNode} optionName 사용자 노출 라벨
@@ -15,7 +89,7 @@ export type SelectOptionValue = string | number;
  * @property {boolean} [disabled] 비활성 여부
  * @property {OptionData} [data] 추가 데이터 payload
  */
-export interface SelectOption<OptionData = unknown> {
+export interface SelectLegacyOption<OptionData = unknown> {
   /**
    * 렌더링 키
    */

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

@@ -1,14 +1,14 @@
 import type { HTMLAttributes, ReactNode } from "react";
+import type { DropdownMenuProps } from "@radix-ui/react-dropdown-menu";
 
 import type {
   DropdownContainerProps,
   DropdownMenuListProps,
   DropdownPanelWidth,
-  DropdownRootProps,
-  DropdownTemplateItem,
 } from "../../dropdown/types";
 import type { FormFieldWidth } from "../../form/types";
 import type { SelectPriority, SelectSize, SelectState } from "./base";
+import type { SelectDropdownOption } from "./option";
 import type {
   SelectTriggerDefaultProps,
   SelectTriggerMultipleProps,
@@ -116,18 +116,22 @@ export interface SelectWidthOption {
 /**
  * Select root props
  * @typedef {SelectStyleOptions & SelectValueOptions & SelectComponentState} SelectProps
+ * @property {SelectPriority} [priority] priority scale
+ * @property {SelectSize} [size] size scale
+ * @property {SelectState} [state] visual state
+ * @property {boolean} [block] block 여부
+ * @property {ReactNode} [displayLabel] 선택된 라벨
+ * @property {ReactNode} [placeholder] placeholder 텍스트
+ * @property {ReactNode[]} [tags] multi select 태그 리스트
+ * @property {boolean} [multiple] multi select 여부
+ * @property {boolean} [isOpen] dropdown open 여부
+ * @property {FormFieldWidth} [width] width preset 옵션
  */
 export type SelectProps = SelectStyleOptions &
   SelectValueOptions &
   SelectComponentState &
   SelectWidthOption;
 
-/**
- * Select dropdown option; Dropdown.Template item 계약을 그대로 따른다.
- * @extends DropdownTemplateItem
- */
-export interface SelectDropdownOption extends DropdownTemplateItem {}
-
 /**
  * Select dropdown 옵션 구성 props
  * @property {SelectDropdownOption[]} [options] dropdown option 리스트
@@ -135,7 +139,7 @@ export interface SelectDropdownOption extends DropdownTemplateItem {}
  * @property {(option: SelectDropdownOption) => void} [onOptionSelect] option 선택 콜백
  * @property {SelectSize} [dropdownSize] dropdown surface size 스케일
  * @property {DropdownPanelWidth} [dropdownWidth="match"] dropdown panel width 옵션
- * @property {DropdownRootProps} [dropdownRootProps] Dropdown.Root 전달 props(제어 props 제외)
+ * @property {DropdownMenuProps} [dropdownRootProps] Dropdown.Root 전달 props(제어 props 제외)
  * @property {DropdownContainerProps} [dropdownContainerProps] Dropdown.Container 전달 props(children/size 제외)
  * @property {DropdownMenuListProps} [dropdownMenuListProps] Dropdown.Menu.List 전달 props
  */
@@ -162,9 +166,10 @@ export interface SelectDropdownConfigProps {
   dropdownWidth?: DropdownPanelWidth;
   /**
    * Dropdown.Root 전달 props(제어 props 제외)
+   * - 타입 출처를 명확히 하기 위해 Radix 원본 타입을 직접 사용한다.
    */
   dropdownRootProps?: Omit<
-    DropdownRootProps,
+    DropdownMenuProps,
     "open" | "defaultOpen" | "onOpenChange"
   >;
   /**
@@ -203,26 +208,60 @@ export interface SelectDropdownBehaviorProps {
 
 /**
  * Select.Default 컴포넌트 props
- * @extends SelectTriggerDefaultProps
- * @extends SelectDropdownConfigProps
- * @extends SelectDropdownBehaviorProps
+ * @typedef {SelectTriggerDefaultProps & SelectDropdownConfigProps & SelectDropdownBehaviorProps & SelectWidthOption} SelectDefaultComponentProps
+ * @property {ReactNode} [displayLabel] 선택된 라벨
+ * @property {ReactNode} [placeholder] placeholder 텍스트
+ * @property {SelectPriority} [priority] priority scale
+ * @property {SelectSize} [size] size scale
+ * @property {SelectState} [state] visual state
+ * @property {boolean} [block] block 여부
+ * @property {boolean} [isOpen] dropdown open 여부
+ * @property {boolean} [disabled] disabled 여부
+ * @property {SelectTriggerButtonType} [buttonType] button type
+ * @property {FormFieldWidth} [width] width preset 옵션
+ * @property {SelectDropdownOption[]} [options] dropdown option 리스트
+ * @property {string[]} [selectedOptionIds] 선택된 option id 리스트
+ * @property {(option: SelectDropdownOption) => void} [onOptionSelect] option 선택 콜백
+ * @property {SelectSize} [dropdownSize] dropdown surface size 스케일
+ * @property {DropdownPanelWidth} [dropdownWidth="match"] dropdown panel width 옵션
+ * @property {Omit<DropdownMenuProps, "open" | "defaultOpen" | "onOpenChange">} [dropdownRootProps] Dropdown.Root 전달 props
+ * @property {Omit<DropdownContainerProps, "children" | "size" | "width">} [dropdownContainerProps] Dropdown.Container 전달 props
+ * @property {DropdownMenuListProps} [dropdownMenuListProps] Dropdown.Menu.List 전달 props
+ * @property {boolean} [open] dropdown open 상태
+ * @property {boolean} [defaultOpen] uncontrolled 초기 open 상태
+ * @property {(open: boolean) => void} [onOpenChange] open state change 콜백
  */
-export interface SelectDefaultComponentProps
-  extends
-    SelectTriggerDefaultProps,
-    SelectDropdownConfigProps,
-    SelectDropdownBehaviorProps,
-    SelectWidthOption {}
+export type SelectDefaultComponentProps = SelectTriggerDefaultProps &
+  SelectDropdownConfigProps &
+  SelectDropdownBehaviorProps &
+  SelectWidthOption;
 
 /**
  * Select.Multiple 컴포넌트 props
- * @extends SelectTriggerMultipleProps
- * @extends SelectDropdownConfigProps
- * @extends SelectDropdownBehaviorProps
+ * @typedef {SelectTriggerMultipleProps & SelectDropdownConfigProps & SelectDropdownBehaviorProps & SelectWidthOption} SelectMultipleComponentProps
+ * @property {ReactNode} [displayLabel] 선택된 라벨
+ * @property {ReactNode} [placeholder] placeholder 텍스트
+ * @property {SelectMultipleTag[]} [tags] multi select tag 리스트
+ * @property {SelectPriority} [priority] priority scale
+ * @property {SelectSize} [size] size scale
+ * @property {SelectState} [state] visual state
+ * @property {boolean} [block] block 여부
+ * @property {boolean} [isOpen] dropdown open 여부
+ * @property {boolean} [disabled] disabled 여부
+ * @property {FormFieldWidth} [width] width preset 옵션
+ * @property {SelectDropdownOption[]} [options] dropdown option 리스트
+ * @property {string[]} [selectedOptionIds] 선택된 option id 리스트
+ * @property {(option: SelectDropdownOption) => void} [onOptionSelect] option 선택 콜백
+ * @property {SelectSize} [dropdownSize] dropdown surface size 스케일
+ * @property {DropdownPanelWidth} [dropdownWidth="match"] dropdown panel width 옵션
+ * @property {Omit<DropdownMenuProps, "open" | "defaultOpen" | "onOpenChange">} [dropdownRootProps] Dropdown.Root 전달 props
+ * @property {Omit<DropdownContainerProps, "children" | "size" | "width">} [dropdownContainerProps] Dropdown.Container 전달 props
+ * @property {DropdownMenuListProps} [dropdownMenuListProps] Dropdown.Menu.List 전달 props
+ * @property {boolean} [open] dropdown open 상태
+ * @property {boolean} [defaultOpen] uncontrolled 초기 open 상태
+ * @property {(open: boolean) => void} [onOpenChange] open state change 콜백
  */
-export interface SelectMultipleComponentProps
-  extends
-    SelectTriggerMultipleProps,
-    SelectDropdownConfigProps,
-    SelectDropdownBehaviorProps,
-    SelectWidthOption {}
+export type SelectMultipleComponentProps = SelectTriggerMultipleProps &
+  SelectDropdownConfigProps &
+  SelectDropdownBehaviorProps &
+  SelectWidthOption;