@uniai-fe/uds-primitives 0.2.2 → 0.2.4

package/src/components/calendar/types/calendar.ts

@@ -0,0 +1,208 @@
+import type {
+  DatePickerProps as MantineDatePickerProps,
+  DatePickerStylesNames,
+} from "@mantine/dates";
+import type { ReactNode } from "react";
+
+/**
+ * Calendar 모드.
+ * @property {"date" | "date-time" | "time"} mode 날짜/시간 표시 모드
+ */
+export type CalendarMode = "date" | "date-time" | "time";
+
+/**
+ * Calendar 컬럼 수.
+ * @property {1 | 2} columns 단일/이중 컬럼 개수
+ */
+export type CalendarColumns = 1 | 2;
+
+/**
+ * Calendar value 직렬화 타입.
+ * @property {string | null} value YYYY-MM-DD 문자열 또는 null
+ */
+export type CalendarValue = string | null;
+
+/**
+ * Calendar 값 변경 핸들러.
+ * @param {CalendarValue} value 선택된 직렬화 값
+ * @example
+ * const onChange = (value: CalendarValue) => {
+ *   console.log(value);
+ * };
+ */
+export type CalendarOnChange = (value: CalendarValue) => void;
+
+/**
+ * Mantine DatePicker 공개 옵션.
+ * @property {Partial<Record<DatePickerStylesNames, string>>} [classNames] Mantine 내부 스타일 클래스 매핑
+ */
+export type CalendarDatePickerProps = Partial<
+  Omit<
+    MantineDatePickerProps<"default">,
+    | "value"
+    | "defaultValue"
+    | "onChange"
+    | "type"
+    | "numberOfColumns"
+    | "classNames"
+    | "styles"
+  >
+> & {
+  /**
+   * Mantine 내부 스타일 classNames override.
+   */
+  classNames?: Partial<Record<DatePickerStylesNames, string>>;
+};
+
+/**
+ * Calendar Grid props.
+ * @property {CalendarValue} value 현재 선택 값
+ * @property {CalendarOnChange} onChange 값 변경 핸들러
+ * @property {CalendarDatePickerProps} [datePickerProps] Mantine DatePicker 옵션
+ */
+export interface CalendarGridProps {
+  /**
+   * 현재 선택 값
+   */
+  value: CalendarValue;
+  /**
+   * 값 변경 핸들러
+   */
+  onChange: CalendarOnChange;
+  /**
+   * Mantine DatePicker 옵션
+   */
+  datePickerProps?: CalendarDatePickerProps;
+}
+
+/**
+ * Calendar Layout Container props.
+ * @property {ReactNode} [header] 상단 콘텐츠
+ * @property {ReactNode} body 본문(Calendar Grid) 콘텐츠
+ * @property {ReactNode} [footer] 하단 콘텐츠
+ * @property {CalendarMode} [mode="date"] calendar 모드
+ * @property {CalendarColumns} [columns=1] 동시 표시 컬럼 수
+ * @property {boolean} [disabled] 비활성화 상태
+ * @property {boolean} [readOnly] 읽기 전용 상태
+ */
+export interface CalendarContainerProps {
+  /**
+   * 상단 콘텐츠
+   */
+  header?: ReactNode;
+  /**
+   * 본문(Calendar Grid) 콘텐츠
+   */
+  body: ReactNode;
+  /**
+   * 하단 콘텐츠
+   */
+  footer?: ReactNode;
+  /**
+   * calendar 모드
+   */
+  mode?: CalendarMode;
+  /**
+   * 동시 표시 컬럼 수
+   */
+  columns?: CalendarColumns;
+  /**
+   * 비활성화 상태
+   */
+  disabled?: boolean;
+  /**
+   * 읽기 전용 상태
+   */
+  readOnly?: boolean;
+}
+
+/**
+ * Calendar Root props.
+ * @extends CalendarContainerProps
+ * @property {string} [className] Trigger element className override
+ * @property {CalendarValue} value 현재 선택 값
+ * @property {CalendarOnChange} onChange 값 변경 핸들러
+ * @property {CalendarDatePickerProps} [datePickerProps] Mantine DatePicker 옵션
+ * @property {ReactNode} children Trigger 슬롯(children)
+ * @property {boolean} [open] 제어형 open 상태
+ * @property {boolean} [defaultOpen] 비제어 초기 open 상태
+ * @property {(open: boolean) => void} [onOpenChange] open 상태 변경 핸들러
+ * @property {"top" | "right" | "bottom" | "left"} [side="bottom"] content 배치 방향
+ * @property {"start" | "center" | "end"} [align="start"] content 정렬 기준
+ * @property {number} [sideOffset=4] trigger와 content 간격
+ * @property {number} [alignOffset] 정렬 보정값
+ * @property {boolean} [withPortal=true] Portal 사용 여부
+ * @property {HTMLElement | null} [portalContainer] Portal 컨테이너
+ */
+export interface CalendarRootProps extends Omit<
+  CalendarContainerProps,
+  "body"
+> {
+  /**
+   * Trigger element className override
+   */
+  className?: string;
+  /**
+   * 현재 선택 값
+   */
+  value: CalendarValue;
+  /**
+   * 값 변경 핸들러
+   */
+  onChange: CalendarOnChange;
+  /**
+   * Mantine DatePicker 옵션
+   */
+  datePickerProps?: CalendarDatePickerProps;
+  /**
+   * Trigger 슬롯(children)
+   */
+  children: ReactNode;
+  /**
+   * 제어형 open 상태
+   */
+  open?: boolean;
+  /**
+   * 비제어 초기 open 상태
+   */
+  defaultOpen?: boolean;
+  /**
+   * open 상태 변경 핸들러
+   */
+  onOpenChange?: (open: boolean) => void;
+  /**
+   * content 배치 방향
+   */
+  side?: "top" | "right" | "bottom" | "left";
+  /**
+   * content 정렬 기준
+   */
+  align?: "start" | "center" | "end";
+  /**
+   * trigger와 content 간격
+   */
+  sideOffset?: number;
+  /**
+   * 정렬 보정값
+   */
+  alignOffset?: number;
+  /**
+   * Portal 사용 여부
+   */
+  withPortal?: boolean;
+  /**
+   * Portal 컨테이너
+   */
+  portalContainer?: HTMLElement | null;
+}
+
+/**
+ * Calendar 섹션 공용 props.
+ * @property {ReactNode} [children] 섹션 내부 콘텐츠
+ */
+export interface CalendarSectionProps {
+  /**
+   * 섹션 내부 콘텐츠
+   */
+  children?: ReactNode;
+}

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

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

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

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

package/src/components/calendar/utils/value-mapper.ts

@@ -0,0 +1,24 @@
+import { dayjs } from "../../../init/dayjs";
+import type { CalendarValue } from "../types";
+
+const DATE_FORMAT = "YYYY-MM-DD";
+
+/**
+ * Calendar value를 DatePicker value로 변환한다.
+ * @param {CalendarValue} value YYYY-MM-DD 문자열 값
+ * @returns {Date | null} DatePicker value
+ * @example
+ * mapValueToPicker("2026-02-13");
+ */
+export const mapValueToPicker = (value: CalendarValue) =>
+  value ? dayjs(value).toDate() : null;
+
+/**
+ * DatePicker value를 Calendar 직렬화 값으로 변환한다.
+ * @param {Date | null} value DatePicker value
+ * @returns {CalendarValue} YYYY-MM-DD 직렬화 값
+ * @example
+ * parseValueFromPicker(new Date("2026-02-13"));
+ */
+export const parseValueFromPicker = (value: Date | null): CalendarValue =>
+  value ? dayjs(value).format(DATE_FORMAT) : null;

package/src/components/input/index.scss

@@ -1,5 +1,5 @@
 @use "./styles/variables.scss" as inputVariables;
 @use "./styles/foundation.scss" as inputFoundation;
 @use "./styles/text.scss" as inputText;
-@use "./styles/calendar.scss" as inputCalendar;
+@use "./styles/date.scss" as inputDate;
 @use "./styles/address.scss" as inputAddress;

package/src/components/input/markup/date/Template.tsx

@@ -0,0 +1,181 @@
+"use client";
+
+import type { ChangeEvent, MouseEvent as ReactMouseEvent } from "react";
+import { forwardRef, useCallback, useMemo } from "react";
+import { useUncontrolled } from "@mantine/hooks";
+import clsx from "clsx";
+import { Calendar } from "../../../calendar";
+import type {
+  InputCalendarProps,
+  InputCalendarTriggerRenderProps,
+} from "../../types";
+import type { CalendarValue } from "../../../calendar";
+import {
+  createEmptyValue,
+  formatTriggerValue,
+  getTodayValue,
+  serializeCalendarValue,
+} from "../../utils/date";
+import InputDateFooterTemplate from "./footer/Template";
+import InputDateTrigger from "./Trigger";
+
+/**
+ * Input Date Template; trigger + calendar 조합.
+ * @component
+ * @param {InputCalendarProps} props
+ * @param {CalendarMode} [props.mode="date"] 날짜/시간 모드
+ * @param {CalendarColumns} [props.columns=1] 동시 노출 달력 수
+ * @param {CalendarValue} [props.value] 제어형 값
+ * @param {CalendarValue} [props.defaultValue] 비제어 초기값
+ * @param {CalendarOnChange} [props.onChange] 값 변경 이벤트
+ * @param {CalendarOnChange} [props.onValueChange] onChange alias
+ * @param {boolean} [props.readOnly] 읽기 전용 여부
+ * @param {boolean} [props.disabled] 비활성화 여부
+ * @param {CalendarDatePickerProps} [props.datePickerProps] Mantine DatePicker 옵션
+ * @param {string} [props.name] form name/RHF name
+ * @param {UseFormRegisterReturn} [props.register] RHF register
+ * @param {string} [props.placeholder="YYYY-MM-DD"] placeholder
+ * @param {ReactNode} [props.header] 패널 header 콘텐츠
+ * @param {ReactNode} [props.footer] 패널 footer 콘텐츠
+ * @param {unknown} [props.timePicker] TimePicker 확장용 예약 슬롯(현재 미구현)
+ * @param {boolean} [props.calendarOpened] calendar 열림 제어 상태
+ * @param {(event: MouseEvent<Element>) => void} [props.onClick] trigger 클릭 핸들러
+ * @param {string} [props.className] root className
+ * @param {string} [props.id] trigger id
+ * @param {ReactNode} [props.trigger] 커스텀 trigger 슬롯
+ * @param {(props: InputCalendarTriggerRenderProps) => ReactNode} [props.renderTrigger] 커스텀 trigger 렌더 함수
+ */
+const InputDateTemplate = forwardRef<HTMLDivElement, InputCalendarProps>(
+  (
+    {
+      mode = "date",
+      columns = 1,
+      value,
+      defaultValue,
+      onChange,
+      onValueChange,
+      readOnly,
+      disabled,
+      datePickerProps,
+      name,
+      register,
+      placeholder = "YYYY-MM-DD",
+      className,
+      header,
+      footer,
+      calendarOpened,
+      onClick: triggerOnClick,
+      id,
+      trigger,
+      renderTrigger,
+    },
+    ref,
+  ) => {
+    // useUncontrolled로 제어형/비제어 값을 모두 허용한다.
+    const [calendarValue, setCalendarValue] = useUncontrolled<CalendarValue>({
+      value,
+      defaultValue,
+      finalValue: createEmptyValue(),
+      onChange: next => {
+        onChange?.(next as CalendarValue);
+        onValueChange?.(next as CalendarValue);
+      },
+    });
+
+    // react-hook-form register onChange를 수동 호출해 값 직렬화를 맞춘다.
+    const emitRegisterChange = useCallback(
+      (nextValue: CalendarValue) => {
+        if (!register?.onChange) {
+          return;
+        }
+        const serialized = serializeCalendarValue(nextValue);
+        const syntheticEvent = {
+          target: {
+            name: register.name,
+            value: serialized,
+          },
+          currentTarget: {
+            name: register.name,
+            value: serialized,
+          },
+        } as unknown as ChangeEvent<HTMLInputElement>;
+        register.onChange(syntheticEvent);
+      },
+      [register],
+    );
+
+    const updateValue = useCallback(
+      (nextValue: CalendarValue) => {
+        setCalendarValue(nextValue);
+        emitRegisterChange(nextValue);
+      },
+      [emitRegisterChange, setCalendarValue],
+    );
+
+    const triggerValue = useMemo(
+      () => formatTriggerValue(calendarValue) ?? "",
+      [calendarValue],
+    );
+
+    const handleTriggerClick = (event: ReactMouseEvent<Element>) => {
+      triggerOnClick?.(event);
+    };
+
+    const handleCalendarChange = (nextValue: CalendarValue) => {
+      updateValue(nextValue);
+    };
+
+    // footer 미지정 시 기본 FooterTemplate을 연결한다.
+    const footerContent = footer ?? (
+      <InputDateFooterTemplate
+        disabled={disabled}
+        onClear={() => updateValue(createEmptyValue())}
+        onToday={() => updateValue(getTodayValue())}
+      />
+    );
+
+    const triggerRenderProps: InputCalendarTriggerRenderProps = {
+      id,
+      name: name ?? register?.name,
+      placeholder,
+      displayValue: triggerValue,
+      disabled,
+      onClick: handleTriggerClick,
+    };
+
+    const triggerNode = trigger ?? renderTrigger?.(triggerRenderProps) ?? (
+      <InputDateTrigger
+        id={id}
+        name={name ?? register?.name}
+        register={register}
+        placeholder={placeholder}
+        displayValue={triggerValue}
+        disabled={disabled}
+        onClick={handleTriggerClick}
+      />
+    );
+
+    return (
+      <Calendar.Root
+        ref={ref}
+        className={clsx("input-date-field", className)}
+        mode={mode}
+        columns={columns}
+        disabled={disabled}
+        readOnly={readOnly}
+        value={calendarValue}
+        onChange={handleCalendarChange}
+        datePickerProps={datePickerProps}
+        header={header}
+        footer={footerContent}
+        open={calendarOpened}
+      >
+        {triggerNode}
+      </Calendar.Root>
+    );
+  },
+);
+
+InputDateTemplate.displayName = "InputDateTemplate";
+
+export default InputDateTemplate;

package/src/components/input/markup/date/Trigger.tsx

@@ -0,0 +1,79 @@
+"use client";
+
+import clsx from "clsx";
+import type { MouseEvent } from "react";
+import { forwardRef } from "react";
+import { Calendar } from "../../../calendar";
+import { InputFoundation } from "../foundation";
+import type { InputCalendarTriggerViewProps } from "../../types";
+
+/**
+ * Input Date trigger field.
+ * @component
+ * @param {InputCalendarTriggerViewProps} props
+ * @param {string} [props.className] trigger className
+ * @param {string} [props.placeholder] placeholder
+ * @param {string} [props.displayValue] 표시 문자열
+ * @param {(event: MouseEvent<Element>) => void} [props.onClick] 클릭 핸들러
+ * @param {boolean} [props.disabled] disabled 여부
+ * @param {string} [props.id] input id
+ * @param {string} [props.name] form name
+ * @param {UseFormRegisterReturn} [props.register] RHF register
+ */
+const InputDateTrigger = forwardRef<
+  HTMLInputElement,
+  InputCalendarTriggerViewProps
+>(
+  (
+    {
+      className,
+      placeholder,
+      displayValue,
+      onClick,
+      disabled,
+      id,
+      name,
+      register,
+      ...restProps
+    },
+    ref,
+  ) => {
+    /**
+     * Radix `asChild`가 주입한 onClick을 보존하기 위해 restProps.onClick을 병합한다.
+     * (Input Date 자체 onClick 계약도 함께 실행)
+     */
+    const handleInputClick = (event: MouseEvent<HTMLInputElement>) => {
+      const rawOnClick = (restProps as Record<string, unknown>).onClick;
+      if (typeof rawOnClick === "function") {
+        (rawOnClick as (event: MouseEvent<HTMLInputElement>) => void)(event);
+      }
+      onClick?.(event as never);
+    };
+
+    return (
+      <InputFoundation.Base
+        {...restProps}
+        ref={ref}
+        value={displayValue}
+        readOnly
+        disabled={disabled}
+        id={id}
+        name={name ?? register?.name}
+        register={register}
+        placeholder={placeholder}
+        className={clsx("input-date-trigger-input", className)}
+        onClick={handleInputClick}
+        right={
+          // 토글 인터랙션은 input 단일 경로로 유지하고, 오른쪽 아이콘은 장식 요소로만 둔다.
+          <figure className="input-date-trigger-icon" aria-hidden="true">
+            <Calendar.Icon.Calendar />
+          </figure>
+        }
+      />
+    );
+  },
+);
+
+InputDateTrigger.displayName = "InputDateTrigger";
+
+export default InputDateTrigger;

package/src/components/input/markup/date/button/ApplyButton.tsx

@@ -0,0 +1,38 @@
+import clsx from "clsx";
+import { Button } from "../../../../button";
+import type { InputCalendarApplyButtonProps } from "../../../types";
+
+/**
+ * Calendar footer apply 버튼.
+ * @component
+ * @param {InputCalendarApplyButtonProps} props
+ * @param {string} [props.className] 추가 className
+ * @param {React.ReactNode} [props.children] override 라벨
+ * @param {React.ReactNode} [props.label] fallback 라벨
+ * @param {boolean} [props.disabled] disabled 여부
+ * @param {() => void} [props.onClick] 클릭 핸들러
+ */
+export default function InputDateApplyButton({
+  className,
+  label,
+  disabled,
+  onClick,
+  children,
+}: InputCalendarApplyButtonProps) {
+  return (
+    <Button.Default
+      className={clsx("input-date-apply-button", className)}
+      priority="primary"
+      fill="solid"
+      size="large"
+      disabled={disabled}
+      onClick={onClick}
+    >
+      {
+        children ??
+          label ??
+          "적용하기" /* children 우선, 없으면 label/기본 라벨 */
+      }
+    </Button.Default>
+  );
+}

package/src/components/input/markup/date/button/ClearButton.tsx

@@ -0,0 +1,36 @@
+import clsx from "clsx";
+import { Button } from "../../../../button";
+import type { InputCalendarInlineButtonProps } from "../../../types";
+
+/**
+ * Calendar footer clear 버튼.
+ * @component
+ * @param {InputCalendarInlineButtonProps} props
+ * @param {React.ReactNode} [props.children] 라벨
+ * @param {() => void} [props.onClick] 클릭 핸들러
+ * @param {boolean} [props.disabled] disabled 여부
+ * @param {string} [props.className] 확장 className
+ */
+export default function InputDateClearButton({
+  children,
+  onClick,
+  disabled,
+  className,
+}: InputCalendarInlineButtonProps) {
+  return (
+    <Button.Default
+      className={clsx(
+        "input-date-action-button input-date-action-clear",
+        className,
+      )}
+      priority="tertiary"
+      fill="outlined"
+      size="small"
+      onClick={onClick}
+      disabled={disabled}
+      type="button"
+    >
+      {children ?? "삭제" /* 텍스트 미지정 시 기본 라벨 */}
+    </Button.Default>
+  );
+}

package/src/components/input/markup/date/button/TodayButton.tsx

@@ -0,0 +1,36 @@
+import clsx from "clsx";
+import { Button } from "../../../../button";
+import type { InputCalendarInlineButtonProps } from "../../../types";
+
+/**
+ * Calendar footer today 버튼.
+ * @component
+ * @param {InputCalendarInlineButtonProps} props
+ * @param {React.ReactNode} [props.children] 라벨
+ * @param {() => void} [props.onClick] 클릭 핸들러
+ * @param {boolean} [props.disabled] disabled 여부
+ * @param {string} [props.className] className 확장
+ */
+export default function InputDateTodayButton({
+  children,
+  onClick,
+  disabled,
+  className,
+}: InputCalendarInlineButtonProps) {
+  return (
+    <Button.Default
+      className={clsx(
+        "input-date-action-button input-date-action-today",
+        className,
+      )}
+      priority="secondary"
+      fill="solid"
+      size="small"
+      onClick={onClick}
+      disabled={disabled}
+      type="button"
+    >
+      {children ?? "오늘" /* default 라벨 */}
+    </Button.Default>
+  );
+}

package/src/components/input/markup/date/footer/Container.tsx

@@ -0,0 +1,24 @@
+import clsx from "clsx";
+import type { InputCalendarFooterTemplateContainerProps } from "../../../types";
+
+/**
+ * FooterTemplate root container.
+ * @component
+ * @param {InputCalendarFooterTemplateContainerProps} props
+ * @param {React.ReactNode} [props.children] footer 내부 children
+ * @param {string} [props.className] container className
+ * @example
+ * <InputDateFooterTemplateContainer>
+ *   <div>...</div>
+ * </InputDateFooterTemplateContainer>
+ */
+export default function InputDateFooterTemplateContainer({
+  children,
+  className,
+}: InputCalendarFooterTemplateContainerProps) {
+  return (
+    <div className={clsx("input-date-footer-template", className)}>
+      {children}
+    </div>
+  );
+}

package/src/components/input/markup/date/footer/Template.tsx

@@ -0,0 +1,36 @@
+import type { InputCalendarFooterTemplateProps } from "../../../types";
+import InputDateApplyButton from "../button/ApplyButton";
+import InputDateClearButton from "../button/ClearButton";
+import InputDateTodayButton from "../button/TodayButton";
+import InputDateFooterTemplateContainer from "./Container";
+import InputDateFooterUtilContainer from "./UtilContainer";
+
+/**
+ * Calendar footer 기본 템플릿.
+ * @component
+ * @param {InputCalendarFooterTemplateProps} props
+ * @param {string} [props.className] root className
+ * @param {() => void} [props.onClear] clear 버튼 클릭 핸들러
+ * @param {() => void} [props.onToday] today 버튼 클릭 핸들러
+ * @param {() => void} [props.onApply] apply 버튼 클릭 핸들러
+ * @param {boolean} [props.disabled] 전체 버튼 disabled 여부
+ * @example
+ * <InputDateFooterTemplate onClear={onClear} onToday={onToday} onApply={onApply} />
+ */
+export default function InputDateFooterTemplate({
+  className,
+  onClear,
+  onToday,
+  onApply,
+  disabled,
+}: InputCalendarFooterTemplateProps) {
+  return (
+    <InputDateFooterTemplateContainer className={className}>
+      <InputDateFooterUtilContainer>
+        <InputDateClearButton disabled={disabled} onClick={onClear} />
+        <InputDateTodayButton disabled={disabled} onClick={onToday} />
+      </InputDateFooterUtilContainer>
+      <InputDateApplyButton disabled={disabled} onClick={onApply} />
+    </InputDateFooterTemplateContainer>
+  );
+}