@uniai-fe/uds-primitives 0.1.13 → 0.2.1

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

@@ -0,0 +1,46 @@
+"use client";
+
+import {
+  createContext,
+  useContext,
+  useMemo,
+  useRef,
+  type ReactNode,
+} from "react";
+
+import type { DropdownContextValue } from "../../types";
+
+/**
+ * Dropdown 전용 context; trigger ref를 공유한다.
+ */
+const DropdownContext = createContext<DropdownContextValue | null>(null);
+
+/**
+ * Dropdown context provider
+ * @component
+ * @param {ReactNode} props.children dropdown 하위 노드
+ */
+const DropdownProvider = ({ children }: { children: ReactNode }) => {
+  const triggerRef = useRef<HTMLElement | null>(null);
+  const value = useMemo<DropdownContextValue>(() => ({ triggerRef }), []);
+
+  return (
+    <DropdownContext.Provider value={value}>
+      {children}
+    </DropdownContext.Provider>
+  );
+};
+
+/**
+ * Dropdown context hook; scope 내에서만 호출해야 한다.
+ * @param {string} componentName 오류 메시지용 컴포넌트 명
+ */
+const useDropdownContext = (componentName: string) => {
+  const context = useContext(DropdownContext);
+  if (!context) {
+    throw new Error(`${componentName} must be used within Dropdown.Container`);
+  }
+  return context;
+};
+
+export { DropdownContext, DropdownProvider, useDropdownContext };

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

@@ -0,0 +1,30 @@
+"use client";
+
+import * as DropdownMenu 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 {ReactNode} props.children Dropdown 하위 node
+ * @param {boolean} [props.modal=false] Radix modal 모드
+ */
+const DropdownRoot = ({
+  children,
+  modal = false,
+  ...rootProps
+}: DropdownRootProps & { children: ReactNode }) => {
+  return (
+    <DropdownProvider>
+      <DropdownMenu.Root modal={modal} {...rootProps}>
+        {children}
+      </DropdownMenu.Root>
+    </DropdownProvider>
+  );
+};
+
+export default DropdownRoot;

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

@@ -0,0 +1,34 @@
+"use client";
+
+import * as DropdownMenu 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 {boolean} [props.asChild=true] asChild 패턴 유지 여부
+ */
+const DropdownTrigger = forwardRef<HTMLElement, DropdownTriggerProps>(
+  ({ asChild = true, children, ...rest }, ref) => {
+    const { triggerRef } = useDropdownContext("Dropdown.Trigger");
+
+    return (
+      <DropdownMenu.Trigger
+        {...rest}
+        asChild={asChild}
+        ref={mergeRefs(ref, triggerRef)}
+      >
+        {children}
+      </DropdownMenu.Trigger>
+    );
+  },
+);
+
+DropdownTrigger.displayName = "DropdownTrigger";
+
+export default DropdownTrigger;

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

@@ -0,0 +1,25 @@
+import DropdownContainer from "./Container";
+import DropdownMenuItem from "./MenuItem";
+import DropdownMenuList from "./MenuList";
+import DropdownRoot from "./Root";
+import { DropdownProvider } from "./Provider";
+import DropdownTrigger from "./Trigger";
+
+/**
+ * Dropdown; 기초 컴포넌트
+ * - Provider
+ * - Root
+ * - Container
+ * - Menu
+ *     - Item
+ *     - List
+ * - Panel
+ * - Trigger
+ */
+export const DropdownFoundation = {
+  Provider: DropdownProvider,
+  Root: DropdownRoot,
+  Container: DropdownContainer,
+  Menu: { Item: DropdownMenuItem, List: DropdownMenuList },
+  Trigger: DropdownTrigger,
+};

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

@@ -1,4 +1,10 @@
+import { DropdownFoundation } from "./foundation";
+import DropdownTemplate from "./Template";
+
 /**
- * TODO(dropdown): SOT 및 사용자 제약에 따라 컴포넌트를 구현한다.
+ * Dropdown namespace export
  */
-export {};
+export const Dropdown = {
+  ...DropdownFoundation,
+  Template: DropdownTemplate,
+};

package/src/components/dropdown/styles/dropdown.scss

@@ -0,0 +1,166 @@
+.dropdown-panel {
+  display: flex;
+  flex-direction: column;
+  gap: var(--dropdown-panel-gap);
+  padding: var(--dropdown-panel-padding);
+  border-radius: var(--dropdown-panel-radius);
+  border: 1px solid var(--dropdown-panel-border-color);
+  background-color: var(--dropdown-panel-background);
+  box-shadow: var(--dropdown-panel-shadow);
+  max-height: var(--dropdown-panel-max-height);
+  overflow-y: auto;
+}
+
+.dropdown-panel-small {
+  --dropdown-option-height-current: var(--dropdown-option-height-small);
+  --dropdown-text-size-current: var(--dropdown-text-small-size);
+  --dropdown-text-line-height-current: var(--dropdown-text-small-line-height);
+  --dropdown-text-letter-spacing-current: var(
+    --dropdown-text-small-letter-spacing
+  );
+}
+
+.dropdown-panel-medium {
+  --dropdown-option-height-current: var(--dropdown-option-height-medium);
+  --dropdown-text-size-current: var(--dropdown-text-medium-size);
+  --dropdown-text-line-height-current: var(--dropdown-text-medium-line-height);
+  --dropdown-text-letter-spacing-current: var(
+    --dropdown-text-medium-letter-spacing
+  );
+}
+
+.dropdown-panel-large {
+  --dropdown-option-height-current: var(--dropdown-option-height-large);
+  --dropdown-text-size-current: var(--dropdown-text-large-size);
+  --dropdown-text-line-height-current: var(--dropdown-text-large-line-height);
+  --dropdown-text-letter-spacing-current: var(
+    --dropdown-text-large-letter-spacing
+  );
+}
+
+.dropdown-menu-list {
+  display: flex;
+  flex-direction: column;
+  gap: var(--dropdown-panel-gap);
+  list-style: none;
+  padding: 0;
+  margin: 0;
+}
+
+.dropdown-menu-item {
+  width: 100%;
+}
+
+.dropdown-menu-item-trigger {
+  display: flex;
+  align-items: center;
+  gap: var(--dropdown-option-gap-inline);
+  width: 100%;
+  min-height: var(
+    --dropdown-option-height-current,
+    var(--dropdown-option-height-medium)
+  );
+  padding: var(--dropdown-option-padding-block)
+    var(--dropdown-option-padding-inline);
+  border-radius: var(--dropdown-option-radius);
+  background-color: transparent;
+  color: var(--dropdown-option-color);
+  cursor: pointer;
+  font-size: var(--dropdown-option-font-size, var(--dropdown-text-medium-size));
+  font-weight: var(--dropdown-option-font-weight, var(--dropdown-text-weight));
+  line-height: var(
+    --dropdown-option-line-height,
+    var(--dropdown-text-medium-line-height)
+  );
+
+  &[data-state="selected"] {
+    background-color: var(--dropdown-option-bg-selected);
+    color: var(--dropdown-option-color-selected);
+  }
+
+  &[data-highlighted],
+  &:hover {
+    background-color: var(--dropdown-option-bg-hover);
+    color: var(--dropdown-option-color-hover);
+  }
+
+  &[data-state="selected"]:hover {
+    background-color: var(--dropdown-option-bg-selected);
+    color: var(--dropdown-option-color-selected);
+  }
+
+  &[data-disabled],
+  &:disabled {
+    color: var(--dropdown-option-color-disabled);
+    cursor: not-allowed;
+    background-color: var(--dropdown-option-bg-disabled);
+  }
+
+  &[data-disabled] .dropdown-menu-item-label,
+  &:disabled .dropdown-menu-item-label {
+    color: var(--dropdown-option-color-disabled);
+  }
+
+  &[data-disabled] .dropdown-menu-item-description,
+  &:disabled .dropdown-menu-item-description {
+    color: var(--dropdown-option-color-disabled);
+  }
+}
+
+.dropdown-menu-item-left,
+.dropdown-menu-item-right {
+  display: inline-flex;
+  align-items: center;
+  color: inherit;
+}
+
+.dropdown-menu-item-body {
+  display: flex;
+  flex-direction: column;
+  gap: 0.2rem;
+  flex: 1 1 auto;
+  min-width: 0;
+}
+
+.dropdown-menu-item-label {
+  display: inline-flex;
+  align-items: center;
+  min-width: 0;
+  color: inherit;
+  font-size: var(
+    --dropdown-text-size-current,
+    var(--dropdown-text-medium-size)
+  );
+  line-height: var(
+    --dropdown-text-line-height-current,
+    var(--dropdown-text-medium-line-height)
+  );
+  letter-spacing: var(
+    --dropdown-text-letter-spacing-current,
+    var(--dropdown-text-medium-letter-spacing)
+  );
+  font-weight: var(--dropdown-text-weight);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.dropdown-menu-item-description {
+  font-size: var(--dropdown-description-size);
+  line-height: var(--dropdown-description-line-height);
+  color: var(--dropdown-description-color);
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.dropdown-menu-item-trigger[data-state="selected"] .dropdown-menu-item-label {
+  font-weight: var(--dropdown-text-weight-selected);
+}
+.dropdown-menu-item-trigger[data-multiple="true"] {
+  align-items: center;
+}
+.dropdown-menu-item-checkbox {
+  width: var(--theme-checkbox-frame-size-medium);
+  height: var(--theme-checkbox-frame-size-medium);
+  padding: 0;
+}

package/src/components/dropdown/styles/index.scss

@@ -0,0 +1,2 @@
+@use "./variables.scss";
+@use "./dropdown.scss";

package/src/components/dropdown/styles/variables.scss

@@ -0,0 +1,40 @@
+:root {
+  --dropdown-panel-background: var(--color-common-100);
+  --dropdown-panel-border-color: var(--color-border-standard-cool-gray);
+  --dropdown-panel-radius: var(--theme-radius-large-1);
+  --dropdown-panel-shadow: 0px 4px 22px rgba(19, 22, 32, 0.12);
+  --dropdown-panel-padding: var(--spacing-padding-3);
+  --dropdown-panel-gap: var(--spacing-gap-2);
+  --dropdown-panel-max-height: 32rem;
+
+  --dropdown-option-radius: var(--theme-radius-medium-1);
+  --dropdown-option-gap-inline: var(--spacing-gap-3);
+  --dropdown-option-padding-inline: var(--spacing-padding-6);
+  --dropdown-option-padding-block: var(--spacing-padding-2);
+  --dropdown-option-color: var(--color-label-standard);
+  --dropdown-option-color-hover: var(--color-label-strong);
+  --dropdown-option-color-selected: var(--color-primary-default);
+  --dropdown-option-color-disabled: var(--color-label-disabled);
+  --dropdown-option-bg-hover: var(--color-surface-standard);
+  --dropdown-option-bg-selected: var(--color-surface-static-blue);
+  --dropdown-option-bg-disabled: transparent;
+
+  --dropdown-text-small-size: 15px;
+  --dropdown-text-small-line-height: 24px;
+  --dropdown-text-small-letter-spacing: 0;
+  --dropdown-text-medium-size: 16px;
+  --dropdown-text-medium-line-height: 24px;
+  --dropdown-text-medium-letter-spacing: 0;
+  --dropdown-text-large-size: 19px;
+  --dropdown-text-large-line-height: 26px;
+  --dropdown-text-large-letter-spacing: 0;
+  --dropdown-text-weight: 400;
+  --dropdown-text-weight-selected: 600;
+  --dropdown-description-color: var(--color-label-neutral);
+  --dropdown-description-size: 14px;
+  --dropdown-description-line-height: 22px;
+
+  --dropdown-option-height-small: var(--theme-size-medium-1, 40px);
+  --dropdown-option-height-medium: var(--theme-size-medium-2, 48px);
+  --dropdown-option-height-large: var(--theme-size-medium-3, 56px);
+}

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

@@ -0,0 +1,31 @@
+import type { DropdownMenuProps } from "@radix-ui/react-dropdown-menu";
+
+/**
+ * Dropdown size scale
+ * @typedef {"small" | "medium" | "large"} DropdownSize
+ */
+export type DropdownSize = "small" | "medium" | "large";
+
+/**
+ * Dropdown panel width 옵션
+ * - "match": trigger width 추적
+ * - "fit-content" | "max-content": 고정 넓이 프리셋
+ * - string/number: min-width 커스텀 값
+ */
+export type DropdownPanelWidth =
+  | "match"
+  | "fit-content"
+  | "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/index.ts

@@ -1,4 +1,2 @@
-/**
- * TODO(dropdown): variant/slot 타입 정의를 작성한다.
- */
-export {};
+export type * from "./base";
+export type * from "./props";

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

@@ -0,0 +1,170 @@
+import type {
+  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;
+
+/**
+ * Dropdown Container props
+ * @property {DropdownSize} [size="medium"] option 높이 스케일
+ * @property {DropdownPanelWidth} [width="match"] dropdown panel width 옵션
+ * @property {HTMLElement | null} [portalContainer] portal을 렌더링할 DOM 컨테이너
+ */
+export interface DropdownContainerProps extends DropdownMenuContentProps {
+  /**
+   * option 높이 스케일
+   */
+  size?: DropdownSize;
+  /**
+   * trigger 너비에 맞춰 dropdown 너비를 맞출지 여부
+   */
+  width?: DropdownPanelWidth;
+  /**
+   * portal을 렌더링할 DOM 컨테이너
+   */
+  portalContainer?: HTMLElement | null;
+}
+
+/**
+ * Dropdown menu item props
+ * @property {ReactNode} [label] 옵션 라벨
+ * @property {ReactNode} [description] 보조 텍스트
+ * @property {ReactNode} [left] 좌측 콘텐츠
+ * @property {ReactNode} [right] 우측 콘텐츠
+ * @property {boolean} [isSelected] 선택 상태 여부
+ * @property {boolean} [multiple] multi select 스타일 여부
+ * @property {CheckboxProps} [checkboxProps] multiple 시 Checkbox 커스터마이징 옵션
+ */
+export interface DropdownMenuItemProps extends RadixDropdownMenuItemProps {
+  /**
+   * 옵션 라벨
+   */
+  label?: ReactNode;
+  /**
+   * 보조 텍스트
+   */
+  description?: ReactNode;
+  /**
+   * 좌측 콘텐츠
+   */
+  left?: ReactNode;
+  /**
+   * 우측 콘텐츠
+   */
+  right?: ReactNode;
+  /**
+   * 선택 상태 여부
+   */
+  isSelected?: boolean;
+  /**
+   * multi select 스타일 여부
+   */
+  multiple?: boolean;
+  /**
+   * Checkbox 커스터마이징 props
+   */
+  checkboxProps?: CheckboxProps;
+}
+
+/**
+ * Dropdown menu list props
+ */
+export interface DropdownMenuListProps extends HTMLAttributes<HTMLUListElement> {}
+
+/**
+ * Dropdown context value; trigger ref 공유용
+ * @property {React.MutableRefObject<HTMLElement | null>} triggerRef trigger DOM ref
+ */
+export interface DropdownContextValue {
+  /**
+   * trigger DOM ref
+   */
+  triggerRef: MutableRefObject<HTMLElement | null>;
+}
+
+/**
+ * Dropdown template item
+ * @property {string} id 고유 식별자
+ * @property {ReactNode} label 옵션 라벨
+ * @property {ReactNode} [description] 보조 텍스트
+ * @property {boolean} [disabled] 비활성 여부
+ * @property {ReactNode} [left] 좌측 콘텐츠
+ * @property {ReactNode} [right] 우측 콘텐츠
+ * @property {boolean} [multiple] multi select 스타일 여부
+ */
+export interface DropdownTemplateItem {
+  /**
+   * 고유 식별자
+   */
+  id: string;
+  /**
+   * 옵션 라벨
+   */
+  label: ReactNode;
+  /**
+   * 보조 텍스트
+   */
+  description?: ReactNode;
+  /**
+   * 비활성 여부
+   */
+  disabled?: boolean;
+  /**
+   * 좌측 콘텐츠
+   */
+  left?: ReactNode;
+  /**
+   * 우측 콘텐츠
+   */
+  right?: ReactNode;
+  /**
+   * multi select 스타일 여부
+   */
+  multiple?: boolean;
+}
+
+/**
+ * Dropdown template props
+ * @property {ReactNode} trigger trigger 요소
+ * @property {DropdownTemplateItem[]} items 렌더링할 menu item 리스트
+ * @property {string[]} [selectedIds] 선택된 item id 배열
+ * @property {DropdownSize} [size="medium"] surface height scale
+ * @property {DropdownPanelWidth} [width="match"] panel width 옵션
+ * @property {DropdownRootProps} [rootProps] Root 에 전달할 props
+ * @property {DropdownContainerProps} [containerProps] Container 에 전달할 props
+ * @property {DropdownMenuListProps} [menuListProps] MenuList 에 전달할 props
+ */
+export interface DropdownTemplateProps {
+  trigger: ReactNode;
+  items: DropdownTemplateItem[];
+  selectedIds?: string[];
+  onSelect?: (item: DropdownTemplateItem) => void;
+  size?: DropdownSize;
+  width?: DropdownPanelWidth;
+  /**
+   * Root 에 전달할 props
+   */
+  rootProps?: DropdownRootProps;
+  /**
+   * Container 에 전달할 props
+   */
+  containerProps?: Omit<DropdownContainerProps, "children" | "size" | "width">;
+  /**
+   * MenuList 에 전달할 props
+   */
+  menuListProps?: DropdownMenuListProps;
+}

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

@@ -1,4 +1 @@
-/**
- * TODO(dropdown): 토큰 매핑과 클래스명 유틸을 구현한다.
- */
-export {};
+export { mergeRefs } from "./refs";

package/src/components/dropdown/utils/refs.ts

@@ -0,0 +1,20 @@
+import type { ForwardedRef } from "react";
+
+/**
+ * 다중 ref를 병합하는 헬퍼
+ * @param {ForwardedRef<T>[]} refs 연결할 refs
+ * @return {(node: T | null) => void} merged ref
+ */
+const mergeRefs = <T>(...refs: (ForwardedRef<T> | null | undefined)[]) => {
+  return (node: T | null) => {
+    refs.forEach(ref => {
+      if (typeof ref === "function") {
+        ref(node);
+      } else if (ref && typeof ref === "object") {
+        (ref as { current: T | null }).current = node;
+      }
+    });
+  };
+};
+
+export { mergeRefs };

package/src/components/form/index.scss

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

package/src/components/form/index.tsx

@@ -1,3 +1,19 @@
-import FormProvider from "./Provider";
+import FormProvider from "./markup/Provider";
+import { FormField } from "./markup/form-field";
 
-export const Form = { Provider: FormProvider };
+import "./index.scss";
+
+export type * from "./types";
+
+/**
+ * Form
+ * @component
+ * @desc
+ * - Form.Provider: Form 컨텍스트 제공 컴포넌트
+ * - Form.Field: Form 필드 컴포넌트
+ *   - Form.Field.Container: Form 필드의 컨테이너 컴포넌트
+ *   - Form.Field.Header: Form 필드의 헤더 컴포넌트
+ *   - Form.Field.Body: Form 필드의 본문 컴포넌트
+ *   - Form.Field.Footer: Form 필드의 푸터 컴포넌트
+ */
+export const Form = { Provider: FormProvider, Field: FormField };

package/src/components/form/markup/form-field/Body.tsx

@@ -0,0 +1,18 @@
+import clsx from "clsx";
+
+/**
+ * Form; field body
+ * @component
+ * @param {object} props
+ * @property {string} [className]
+ * @property {React.ReactNode} [children]
+ */
+export default function FormFieldBody({
+  className,
+  children,
+}: {
+  className?: string;
+  children?: React.ReactNode;
+}) {
+  return <div className={clsx("form-field-body", className)}>{children}</div>;
+}