@uniai-fe/uds-primitives 0.2.1 → 0.2.3

package/src/components/input/utils/address.ts

@@ -0,0 +1,165 @@
+import { string } from "@uniai-fe/util-functions";
+import type { Address } from "react-daum-postcode";
+
+import type {
+  AddressResolvedValue,
+  AddressSearchResult,
+  AddressStructure,
+} from "../types/address";
+
+/**
+ * 객체 여부 체크 util.
+ */
+const isObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null;
+
+/**
+ * react-daum-postcode AddressSearchResult 유사 객체인지 검사한다.
+ */
+const isAddressSearchResultLike = (
+  value: unknown,
+): value is Partial<AddressSearchResult> =>
+  isObject(value) && typeof value.address === "string";
+
+/**
+ * AddressStructure 형태인지 검사한다.
+ */
+const isAddressStructureLike = (
+  value: unknown,
+): value is Partial<AddressStructure> =>
+  isObject(value) &&
+  ("main" in value || "extras" in value) &&
+  (typeof value.main === "string" || Array.isArray(value.extras));
+
+/**
+ * 문자열 파트 배열을 안전하게 변환한다.
+ */
+const toAddressParts = (items: unknown[] | undefined): string[] => {
+  if (!Array.isArray(items)) return [];
+  return items
+    .map(item => string(item, ""))
+    .filter((segment): segment is string => segment.length > 0);
+};
+
+/**
+ * AddressStructure에서 main/extras를 순서대로 병합한다.
+ */
+const mergeStructureParts = (
+  structure: AddressStructure | Partial<AddressStructure>,
+): string[] => {
+  const mainPart =
+    typeof structure.main === "string" ? structure.main : undefined;
+  const extras = toAddressParts(structure.extras);
+  return [mainPart, ...extras].filter(
+    (part): part is string => typeof part === "string" && part.length > 0,
+  );
+};
+
+/**
+ * Template/Base 컴포넌트에서 사용하는 주소 문자열 정규화.
+ * @function
+ * @param {unknown} value RHF watch 값 혹은 addressInput.value override
+ * @returns {AddressResolvedValue} 문자열과 파트 배열
+ */
+export const resolveAddressValue = (value: unknown): AddressResolvedValue => {
+  if (typeof value === "string") {
+    return {
+      text: value,
+      parts: value.length > 0 ? [value] : [],
+    };
+  }
+
+  if (Array.isArray(value)) {
+    const parts = toAddressParts(value);
+    return {
+      text: parts.join(" "),
+      parts,
+    };
+  }
+
+  if (isAddressSearchResultLike(value)) {
+    const base = value.address ?? "";
+    const parts =
+      value.addressParts && value.addressParts.length > 0
+        ? toAddressParts(value.addressParts)
+        : value.addressStructure
+          ? mergeStructureParts(value.addressStructure)
+          : base
+            ? [base]
+            : [];
+    return {
+      text: base,
+      parts,
+    };
+  }
+
+  if (isAddressStructureLike(value)) {
+    const parts = mergeStructureParts(value);
+    return {
+      text: parts.join(" "),
+      parts,
+    };
+  }
+
+  if (isObject(value) && "text" in value) {
+    const textValue =
+      typeof (value as { text?: unknown }).text === "string"
+        ? (value as { text: string }).text
+        : "";
+    const parts = Array.isArray((value as { parts?: unknown[] }).parts)
+      ? toAddressParts((value as { parts: unknown[] }).parts)
+      : textValue
+        ? [textValue]
+        : [];
+    return {
+      text: textValue,
+      parts,
+    };
+  }
+
+  return { text: "", parts: [] };
+};
+
+/**
+ * react-daum-postcode Address 데이터를 AddressSearchResult 형식으로 변환한다.
+ * `address` 필드는 우편번호 서비스에서 내려준 최종 문자열(도로명 + 추가 항목)을 그대로 유지하고,
+ * 분해 정보(`addressParts`, `addressStructure`)를 추가로 제공한다.
+ * @function
+ * @see https://www.juso.go.kr/addrlink/devAddrLinkRequestGuide.do
+ * @param {Address} data 우편번호 서비스 선택 결과
+ * @returns {AddressSearchResult} 변환된 주소 정보 객체
+ * @example
+ * ```ts
+ * const result = createAddressSearchResult(data);
+ * console.log(result.address); // "서울시 강남구 ... (OO동)"
+ * console.log(result.addressParts); // ["서울시 강남구 ...", "OO동"]
+ * ```
+ */
+export const createAddressSearchResult = (
+  data: Address,
+): AddressSearchResult => {
+  const extraParts: string[] = [];
+
+  if (data.addressType === "R") {
+    if (data.bname) extraParts.push(data.bname);
+    if (data.buildingName) extraParts.push(data.buildingName);
+  }
+
+  const baseAddress = data.address;
+  const labelExtras =
+    extraParts.length > 0 ? ` (${extraParts.join(", ")})` : "";
+  const parts = [baseAddress, ...extraParts].filter(part => part.length > 0);
+
+  return {
+    address: `${baseAddress}${labelExtras}`,
+    addressParts: parts,
+    addressStructure: {
+      main: baseAddress,
+      extras: [...extraParts],
+    },
+    zipCode: data.zonecode,
+    buildingName: data.buildingName || undefined,
+    district: data.bname || undefined,
+    raw: data,
+  };
+};

package/src/components/input/utils/date.ts

@@ -0,0 +1,61 @@
+import { dayjs } from "../../../init/dayjs";
+import type { CalendarColumns, CalendarValue } from "../../calendar";
+
+const DATE_FORMAT = "YYYY-MM-DD";
+
+/**
+ * Calendar에 빈 값을 선언한다.
+ * @returns {CalendarValue} null 직렬화 값
+ */
+export const createEmptyValue = (): CalendarValue => null;
+
+/**
+ * Date 객체를 YYYY-MM-DD 문자열로 포맷한다.
+ * @param {Date | string | null} date 포맷 대상
+ * @returns {CalendarValue} 포맷 결과
+ */
+const formatDate = (date: Date | string | null) =>
+  date ? dayjs(date).format(DATE_FORMAT) : null;
+
+/**
+ * Mantine DatePicker에 전달할 Date 객체를 만든다.
+ * @param {CalendarValue} value YYYY-MM-DD 문자열
+ * @returns {Date | null} DatePicker value
+ */
+export const mapValueToPicker = (value: CalendarValue) =>
+  value ? dayjs(value).toDate() : null;
+
+/**
+ * DatePicker 반환 값을 문자열로 직렬화한다.
+ * @param {Date | null} value DatePicker 값
+ * @returns {CalendarValue} 직렬화 문자열
+ */
+export const parseValueFromPicker = (value: Date | null) =>
+  formatDate(value ?? null);
+
+/**
+ * 오늘 날짜를 YYYY-MM-DD 문자열로 반환한다.
+ * @returns {CalendarValue} 오늘 값
+ */
+export const getTodayValue = (): CalendarValue => dayjs().format(DATE_FORMAT);
+
+/**
+ * hidden input 직렬화용 문자열.
+ * @param {CalendarValue} value 현재 값
+ * @returns {string} 직렬화된 문자열
+ */
+export const serializeCalendarValue = (value: CalendarValue) => value ?? "";
+
+/**
+ * trigger에 표시할 문자열을 계산한다.
+ * @param {CalendarValue} value 현재 값
+ * @returns {string} 표시 문자열
+ */
+export const formatTriggerValue = (value: CalendarValue) => value ?? "";
+
+/**
+ * columns 값을 Mantine numberOfColumns와 맞춘다.
+ * @param {CalendarColumns} columns 열 개수
+ * @returns {number} numberOfColumns 값
+ */
+export const mapColumnsToNumber = (columns: CalendarColumns) => columns;

package/src/components/input/utils/index.tsx

@@ -1 +1,3 @@
 export * from "./verification";
+export * from "./date";
+export * from "./address";

package/src/components/pop-over/index.scss

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

package/src/components/pop-over/index.tsx

@@ -0,0 +1,4 @@
+import "./index.scss";
+
+export * from "./markup";
+export type * from "./types";

package/src/components/pop-over/markup/Content.tsx

@@ -0,0 +1,77 @@
+"use client";
+
+import * as PopOverPrimitive from "@radix-ui/react-popover";
+import clsx from "clsx";
+import { forwardRef } from "react";
+import type { PopOverContentProps } from "../types";
+
+/**
+ * PopOver Content.
+ * @component
+ * @param {PopOverContentProps} props Content props
+ * @param {React.ReactNode} [props.children] Content 내부 콘텐츠
+ * @param {string} [props.className] Content className
+ * @param {boolean} [props.withPortal=true] Portal 사용 여부
+ * @param {HTMLElement | null} [props.portalContainer] Portal 컨테이너
+ * @param {number} [props.sideOffset=4] Trigger와 Content 간격
+ * @param {PopOverContentWidth} [props.width="fit-content"] Content width 옵션
+ * @example
+ * <PopOver.Content sideOffset={6}>popover content</PopOver.Content>
+ */
+const PopOverContent = forwardRef<HTMLDivElement, PopOverContentProps>(
+  (
+    {
+      children,
+      className,
+      withPortal = true,
+      portalContainer,
+      sideOffset = 4,
+      width = "fit-content",
+      style,
+      ...restProps
+    },
+    ref,
+  ) => {
+    const resolvedWidth =
+      width === "match"
+        ? "var(--radix-popover-trigger-width)"
+        : typeof width === "number"
+          ? `${width}px`
+          : width;
+    const resolvedWidthToken =
+      width === "match" || width === "fit-content" || width === "max-content"
+        ? width
+        : "custom";
+
+    // Content 노드는 portal 여부에 따라 동일 노드를 재사용한다.
+    const contentNode = (
+      <PopOverPrimitive.Content
+        ref={ref}
+        className={clsx("pop-over-content", className)}
+        sideOffset={sideOffset}
+        data-width={resolvedWidthToken}
+        style={{
+          ...style,
+          width: resolvedWidth,
+        }}
+        {...restProps}
+      >
+        {children}
+      </PopOverPrimitive.Content>
+    );
+
+    if (!withPortal) {
+      return contentNode;
+    }
+
+    return (
+      <PopOverPrimitive.Portal container={portalContainer ?? undefined}>
+        {contentNode}
+      </PopOverPrimitive.Portal>
+    );
+  },
+);
+
+PopOverContent.displayName = "PopOverContent";
+
+export default PopOverContent;

package/src/components/pop-over/markup/Root.tsx

@@ -0,0 +1,28 @@
+"use client";
+
+import * as PopOverPrimitive from "@radix-ui/react-popover";
+import type { PopOverRootProps } from "../types";
+
+/**
+ * PopOver Root.
+ * @component
+ * @param {PopOverRootProps} props Root props
+ * @param {React.ReactNode} props.children PopOver 하위 노드
+ * @param {boolean} [props.open] 제어형 open 상태
+ * @param {boolean} [props.defaultOpen] 비제어 초기 open 상태
+ * @param {(open: boolean) => void} [props.onOpenChange] open 상태 변경 핸들러
+ * @param {boolean} [props.modal] Radix modal 모드
+ * @example
+ * <PopOver.Root>
+ *   <PopOver.Trigger asChild><button>open</button></PopOver.Trigger>
+ *   <PopOver.Content>content</PopOver.Content>
+ * </PopOver.Root>
+ */
+export default function PopOverRoot({
+  children,
+  ...restProps
+}: PopOverRootProps) {
+  return (
+    <PopOverPrimitive.Root {...restProps}>{children}</PopOverPrimitive.Root>
+  );
+}

package/src/components/pop-over/markup/Trigger.tsx

@@ -0,0 +1,26 @@
+"use client";
+
+import * as PopOverPrimitive from "@radix-ui/react-popover";
+import { forwardRef } from "react";
+import type { PopOverTriggerProps } from "../types";
+
+/**
+ * PopOver Trigger.
+ * @component
+ * @param {PopOverTriggerProps} props Trigger props
+ * @param {React.ReactNode} [props.children] Trigger 콘텐츠
+ * @param {boolean} [props.asChild] child 노드를 Trigger element로 사용할지 여부
+ * @example
+ * <PopOver.Trigger asChild><button>open</button></PopOver.Trigger>
+ */
+const PopOverTrigger = forwardRef<HTMLButtonElement, PopOverTriggerProps>(
+  ({ children, ...restProps }, ref) => (
+    <PopOverPrimitive.Trigger ref={ref} {...restProps}>
+      {children}
+    </PopOverPrimitive.Trigger>
+  ),
+);
+
+PopOverTrigger.displayName = "PopOverTrigger";
+
+export default PopOverTrigger;

package/src/components/pop-over/markup/index.tsx

@@ -0,0 +1,17 @@
+import PopOverContent from "./Content";
+import PopOverRoot from "./Root";
+import PopOverTrigger from "./Trigger";
+
+export { PopOverRoot, PopOverTrigger, PopOverContent };
+
+/**
+ * PopOver namespace.
+ * - Root
+ * - Trigger
+ * - Content
+ */
+export const PopOver = {
+  Root: PopOverRoot,
+  Trigger: PopOverTrigger,
+  Content: PopOverContent,
+};

package/src/components/pop-over/styles/base.scss

@@ -0,0 +1,5 @@
+.pop-over-content {
+  position: relative;
+  z-index: 50;
+  outline: none;
+}

package/src/components/pop-over/styles/content.scss

@@ -0,0 +1,24 @@
+.pop-over-content {
+  // PopOver 공통 surface 스킨(배경/라운드/그림자)은 Content에서 기본 제공한다.
+  width: fit-content;
+  max-width: min(100vw - 24px, max-content);
+  box-sizing: border-box;
+  background-color: var(--color-common-100);
+  border-radius: var(--theme-radius-large-2);
+  overflow: hidden;
+  box-shadow:
+    0 4px 20px rgba(0, 0, 0, 0.16),
+    0 0 2px rgba(0, 0, 0, 0.12);
+}
+
+.pop-over-content[data-width="match"] {
+  width: var(--radix-popover-trigger-width);
+}
+
+.pop-over-content[data-width="fit-content"] {
+  width: fit-content;
+}
+
+.pop-over-content[data-width="max-content"] {
+  width: max-content;
+}

package/src/components/pop-over/styles/index.scss

@@ -0,0 +1,2 @@
+@use "./base.scss";
+@use "./content.scss";

package/src/components/pop-over/types/index.ts

@@ -0,0 +1 @@
+export type * from "./pop-over";

package/src/components/pop-over/types/pop-over.ts

@@ -0,0 +1,86 @@
+import type {
+  PopoverContentProps as RadixPopOverContentProps,
+  PopoverProps as RadixPopOverProps,
+  PopoverTriggerProps as RadixPopOverTriggerProps,
+} from "@radix-ui/react-popover";
+import type { ReactNode } from "react";
+
+/**
+ * PopOver Content width 옵션.
+ * @property {"match"} width trigger width와 동일
+ * @property {"fit-content"} width 콘텐츠 기준 폭
+ * @property {"max-content"} width 최대 콘텐츠 폭
+ * @property {number} width px 단위 폭
+ * @property {string} width CSS width 문자열
+ */
+export type PopOverContentWidth =
+  | "match"
+  | "fit-content"
+  | "max-content"
+  | number
+  | string;
+
+/**
+ * PopOver Root props.
+ * @property {ReactNode} children PopOver 하위 노드
+ * @property {boolean} [open] 제어형 open 상태
+ * @property {boolean} [defaultOpen] 비제어 초기 open 상태
+ * @property {(open: boolean) => void} [onOpenChange] open 상태 변경 핸들러
+ * @property {boolean} [modal] Radix modal 모드
+ * @see Radix PopoverProps
+ */
+export interface PopOverRootProps extends RadixPopOverProps {
+  /**
+   * PopOver 하위 노드
+   */
+  children: ReactNode;
+}
+
+/**
+ * PopOver Trigger props.
+ * @property {ReactNode} [children] Trigger 콘텐츠
+ * @property {boolean} [asChild] child 노드를 trigger로 사용할지 여부
+ * @see Radix PopoverTriggerProps
+ */
+export interface PopOverTriggerProps extends RadixPopOverTriggerProps {
+  /**
+   * Trigger 콘텐츠
+   */
+  children?: ReactNode;
+}
+
+/**
+ * PopOver Content props.
+ * @property {ReactNode} [children] Content 내부 콘텐츠
+ * @property {string} [className] Content className
+ * @property {boolean} [withPortal=true] Portal 사용 여부
+ * @property {HTMLElement | null} [portalContainer] Portal 컨테이너
+ * @property {number} [sideOffset=4] trigger와 content 사이 간격
+ * @property {PopOverContentWidth} [width="fit-content"] content width 옵션
+ * @see Radix PopoverContentProps
+ */
+export interface PopOverContentProps extends Omit<
+  RadixPopOverContentProps,
+  "children"
+> {
+  /**
+   * Content 내부 콘텐츠
+   */
+  children?: ReactNode;
+  /**
+   * Content className
+   */
+  className?: string;
+  /**
+   * Portal 사용 여부
+   */
+  withPortal?: boolean;
+  /**
+   * Portal 컨테이너
+   */
+  portalContainer?: HTMLElement | null;
+  /**
+   * content width 옵션
+   */
+  width?: PopOverContentWidth;
+}

package/src/components/radio/markup/Radio.tsx

@@ -26,7 +26,7 @@ const RADIO_HELPER_CLASSNAME = "radio-helper";
  * @example
  * <Radio value="option" />
  */
-export const Radio = forwardRef<HTMLButtonElement, RadioProps>(function Radio(
+const Radio = forwardRef<HTMLButtonElement, RadioProps>(function Radio(
   { size = "medium", className, disabled, ...restProps },
   ref,
 ) {
@@ -49,6 +49,9 @@ export const Radio = forwardRef<HTMLButtonElement, RadioProps>(function Radio(
   );
 });
 
+// forwardRef Tooltip 유지를 위해 displayName 지정.
+Radio.displayName = "Radio";
+
 /**
  * RadioField component; label/helper wrapper for single radioItem
  * @component
@@ -66,7 +69,7 @@ export const Radio = forwardRef<HTMLButtonElement, RadioProps>(function Radio(
  * @example
  * <RadioField label="옵션" helperText="필수" value="option" />
  */
-export const RadioField = forwardRef<HTMLButtonElement, RadioFieldProps>(
+const RadioField = forwardRef<HTMLButtonElement, RadioFieldProps>(
   function RadioField(
     {
       label,
@@ -133,3 +136,8 @@ export const RadioField = forwardRef<HTMLButtonElement, RadioFieldProps>(
     );
   },
 );
+
+// forwardRef Tooltip 유지를 위해 displayName 지정.
+RadioField.displayName = "RadioField";
+
+export { Radio, RadioField };

package/src/components/radio/markup/RadioCard.tsx

@@ -30,7 +30,7 @@ const RADIO_CARD_INDICATOR_CLASSNAME = "radio-card-indicator";
  * @example
  * <RadioCard title="행복1농장" value="farm-1" />
  */
-export const RadioCard = forwardRef<HTMLButtonElement, RadioCardProps>(
+const RadioCard = forwardRef<HTMLButtonElement, RadioCardProps>(
   function RadioCard(
     {
       title,
@@ -74,3 +74,8 @@ export const RadioCard = forwardRef<HTMLButtonElement, RadioCardProps>(
     );
   },
 );
+
+// forwardRef Tooltip 유지를 위해 displayName 지정.
+RadioCard.displayName = "RadioCard";
+
+export { RadioCard };

package/src/components/radio/markup/RadioCardGroup.tsx

@@ -22,7 +22,7 @@ const RADIO_CARD_GROUP_CLASSNAME = "radio-card-group";
  * @example
  * <RadioCardGroup options={[{ id: "farm-1", title: "농장" }]} value="farm-1" />
  */
-export const RadioCardGroup = forwardRef<
+const RadioCardGroup = forwardRef<
   ElementRef<typeof RadixRadioGroup.Root>,
   RadioCardGroupProps
 >(function RadioCardGroup(
@@ -81,3 +81,8 @@ export const RadioCardGroup = forwardRef<
     </RadixRadioGroup.Root>
   );
 });
+
+// forwardRef Tooltip 유지를 위해 displayName 지정.
+RadioCardGroup.displayName = "RadioCardGroup";
+
+export { RadioCardGroup };

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

@@ -36,6 +36,7 @@ const SelectDefault = forwardRef<HTMLElement, SelectDefaultComponentProps>(
       size = "medium",
       state = "default",
       block,
+      width,
       isOpen,
       disabled,
       buttonType,
@@ -86,6 +87,7 @@ const SelectDefault = forwardRef<HTMLElement, SelectDefaultComponentProps>(
       <Container
         className={clsx("select-trigger-container", className)}
         block={block}
+        width={width}
       >
         <Dropdown.Root
           open={dropdownOpen}

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

@@ -3,6 +3,10 @@
 import clsx from "clsx";
 
 import type { SelectContainerProps } from "../../types/props";
+import {
+  getFormFieldWidthAttr,
+  getFormFieldWidthValue,
+} from "../../../form/utils/form-field";
 
 /**
  * Select trigger/container wrapper
@@ -16,12 +20,31 @@ export default function SelectContainer({
   className,
   children,
   block = false,
+  width,
+  style,
+  ...restProps
 }: SelectContainerProps) {
+  const widthAttr =
+    width !== undefined
+      ? getFormFieldWidthAttr(width)
+      : block
+        ? "full"
+        : undefined;
+  const widthValue =
+    width !== undefined ? getFormFieldWidthValue(width) : undefined;
+  const mergedStyle =
+    widthValue !== undefined
+      ? { ...(style ?? {}), ["--select-width" as const]: widthValue }
+      : style;
+
   return (
     <div
       className={clsx("select select-container", className, {
         "select-block": block,
       })}
+      data-width={widthAttr}
+      style={mergedStyle}
+      {...restProps}
     >
       {/** dropdown root 및 dropdown menu 등 포함 예정 */}
       {children}

package/src/components/select/markup/multiple/Multiple.tsx

@@ -38,6 +38,7 @@ const SelectMultipleTrigger = forwardRef<
       size = "medium",
       state = "default",
       block,
+      width,
       isOpen,
       disabled,
       tags,
@@ -113,6 +114,7 @@ const SelectMultipleTrigger = forwardRef<
       <Container
         className={clsx("select-trigger-multiple", className)}
         block={block}
+        width={width}
       >
         <Dropdown.Root
           open={dropdownOpen}