@uniai-fe/uds-primitives 0.2.1 → 0.2.3

package/src/components/calendar/styles/mantine-calendar.scss

@@ -0,0 +1,240 @@
+.calendar-root,
+.calendar-grid {
+  // Calendar 기준 폭/패딩/컬럼 간격을 모듈 내부에서 고정한다.
+  --calendar-width: 375px;
+  --calendar-inline-padding: var(--spacing-padding-6);
+  --calendar-body-width: calc(
+    var(--calendar-width) - (var(--calendar-inline-padding) * 2)
+  );
+}
+
+.calendar-root {
+  // Calendar 내부 레이아웃 스킨(표면 스타일은 PopOver.Content가 담당).
+  padding: var(--spacing-padding-10) var(--spacing-padding-6)
+    var(--spacing-padding-6);
+  display: grid;
+  gap: var(--spacing-gap-3);
+  width: var(--calendar-width);
+  min-width: var(--calendar-width);
+  max-width: min(100vw - (var(--spacing-padding-5) * 2), 420px);
+  box-sizing: border-box;
+  z-index: 30;
+}
+
+.calendar-header {
+  margin-bottom: var(--spacing-gap-2);
+}
+
+.calendar-body {
+  display: grid;
+  gap: var(--spacing-gap-5);
+}
+
+.calendar-grid {
+  width: var(--calendar-body-width);
+}
+
+.calendar-grid table {
+  width: auto;
+}
+
+.calendar-month-level {
+  width: 100%;
+}
+
+.calendar-month-level > [data-month-level="true"],
+.calendar-month-level > [data-year-level="true"],
+.calendar-month-level > [data-decade-level="true"] {
+  width: 100%;
+}
+
+.calendar-header-row {
+  display: grid;
+  grid-template-columns: 44px 1fr 44px;
+  align-items: center;
+  width: 100%;
+  max-width: none;
+  column-gap: var(--spacing-gap-5);
+  padding: 0 var(--spacing-padding-9);
+  margin-bottom: var(--spacing-gap-5);
+  --dch-fz: var(--font-heading-small-size) !important;
+}
+
+.calendar-header-control {
+  width: 44px;
+  height: 44px;
+  border-radius: 999px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--color-label-alternative);
+  transition:
+    background-color 0.2s ease,
+    color 0.2s ease;
+}
+
+.calendar-header-control[data-direction="previous"] {
+  justify-self: start;
+}
+
+.calendar-header-control[data-direction="next"] {
+  justify-self: end;
+}
+
+.calendar-header-level {
+  justify-self: center;
+  font-size: var(--font-heading-small-size);
+  font-weight: var(--font-heading-small-weight);
+  text-align: center;
+  white-space: nowrap;
+  writing-mode: horizontal-tb;
+  letter-spacing: 0.2px;
+  /* Month/Year 헤더 텍스트는 디자인 기준에 맞춰 strong 컬러를 사용한다. */
+  color: var(--color-label-strong);
+}
+
+.calendar-header-control:where(:not([data-disabled="true"])):hover {
+  background-color: var(--color-tertiary-default);
+  color: var(--color-label-standard);
+}
+
+.calendar-month-table {
+  width: 100%;
+  max-width: 100%;
+  margin: 0 auto;
+  table-layout: fixed;
+  border-collapse: collapse;
+  border-spacing: 0;
+}
+
+.calendar-month-cell {
+  width: 46px;
+  padding: 1px;
+}
+
+.calendar-months-list {
+  width: 100%;
+  max-width: 100%;
+  margin: 0 auto;
+  table-layout: fixed;
+  border-collapse: separate;
+  border-spacing: var(--spacing-gap-3);
+}
+
+.calendar-months-list-cell {
+  padding: 0;
+}
+
+.calendar-months-list-control {
+  width: 100%;
+  min-width: 0;
+  height: 44px;
+  padding: 0 var(--spacing-padding-2);
+  border: none;
+  border-radius: var(--theme-radius-medium-3);
+  font-size: var(--font-body-medium-size);
+  font-weight: var(--font-body-medium-weight);
+  line-height: 1.5;
+  color: var(--color-label-standard);
+  text-transform: none;
+}
+
+.calendar-months-list-control[data-selected="true"] {
+  background-color: var(--color-primary-default);
+  color: var(--color-common-100);
+}
+
+.calendar-months-list-control:where(
+    :not([data-disabled="true"], [data-selected="true"])
+  ):hover {
+  background-color: var(--color-secondary-default);
+}
+
+.calendar-years-list {
+  width: 100%;
+  max-width: 100%;
+  margin: 0 auto;
+  table-layout: fixed;
+  border-collapse: separate;
+  border-spacing: var(--spacing-gap-3);
+}
+
+.calendar-years-list-cell {
+  padding: 0;
+}
+
+.calendar-years-list-control {
+  width: 100%;
+  min-width: 0;
+  height: 44px;
+  padding: 0 var(--spacing-padding-2);
+  border: none;
+  border-radius: var(--theme-radius-medium-3);
+  font-size: var(--font-body-medium-size);
+  font-weight: var(--font-body-medium-weight);
+  line-height: 1.5;
+  color: var(--color-label-standard);
+  text-transform: none;
+}
+
+.calendar-years-list-control[data-selected="true"] {
+  background-color: var(--color-primary-default);
+  color: var(--color-common-100);
+}
+
+.calendar-years-list-control:where(
+    :not([data-disabled="true"], [data-selected="true"])
+  ):hover {
+  background-color: var(--color-secondary-default);
+}
+
+.calendar-weekdays {
+  text-transform: none;
+  --wr-fz: var(--font-heading-xxsmall-size) !important;
+  --wr-spacing: 10px !important;
+}
+
+.calendar-weekday {
+  text-transform: none;
+  width: 46px;
+  min-width: 46px;
+  height: 30px;
+  padding-bottom: 5px;
+  font-size: var(--font-heading-xxsmall-size);
+  font-weight: var(--font-heading-xxsmall-weight);
+  line-height: 1.5;
+  letter-spacing: 0.2px;
+  color: var(--color-label-alternative);
+  text-align: center;
+  vertical-align: middle;
+}
+
+.calendar-day {
+  width: 44px;
+  height: 44px;
+  padding: 0;
+  border: none;
+  border-radius: var(--theme-radius-large-1);
+  font-size: var(--font-body-medium-size);
+  color: var(--color-label-standard);
+}
+
+.calendar-day[data-outside="true"] {
+  color: var(--color-label-alternative);
+}
+
+.calendar-day[data-selected="true"],
+.calendar-day[data-focused="true"] {
+  background-color: var(--color-primary-default);
+  color: var(--color-common-100);
+}
+
+.calendar-day:where(:not([data-disabled="true"])):hover {
+  background-color: var(--color-secondary-default);
+  color: var(--color-label-standard);
+  border: none;
+}
+
+.calendar-footer {
+  width: 100%;
+}

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/checkbox/markup/Checkbox.tsx

@@ -31,31 +31,32 @@ const getIndicatorIcon = (size: CheckboxSize) =>
  * @example
  * <Checkbox size="medium" checked />
  */
-export const Checkbox = forwardRef<HTMLButtonElement, CheckboxProps>(
-  function Checkbox(
-    { size = "medium", className, disabled, ...restProps },
-    ref,
-  ) {
-    const IndicatorIcon = getIndicatorIcon(size);
+const Checkbox = forwardRef<HTMLButtonElement, CheckboxProps>(function Checkbox(
+  { size = "medium", className, disabled, ...restProps },
+  ref,
+) {
+  const IndicatorIcon = getIndicatorIcon(size);
 
-    return (
-      <CheckboxPrimitive.Root
-        ref={ref}
-        disabled={disabled}
-        data-size={size}
-        data-disabled={disabled ? "true" : undefined}
-        className={clsx(CHECKBOX_CLASSNAME, className)}
-        {...restProps}
-      >
-        <span className={CHECKBOX_SURFACE_CLASSNAME} aria-hidden="true">
-          <CheckboxPrimitive.Indicator className={CHECKBOX_INDICATOR_CLASSNAME}>
-            <IndicatorIcon aria-hidden />
-          </CheckboxPrimitive.Indicator>
-        </span>
-      </CheckboxPrimitive.Root>
-    );
-  },
-);
+  return (
+    <CheckboxPrimitive.Root
+      ref={ref}
+      disabled={disabled}
+      data-size={size}
+      data-disabled={disabled ? "true" : undefined}
+      className={clsx(CHECKBOX_CLASSNAME, className)}
+      {...restProps}
+    >
+      <span className={CHECKBOX_SURFACE_CLASSNAME} aria-hidden="true">
+        <CheckboxPrimitive.Indicator className={CHECKBOX_INDICATOR_CLASSNAME}>
+          <IndicatorIcon aria-hidden />
+        </CheckboxPrimitive.Indicator>
+      </span>
+    </CheckboxPrimitive.Root>
+  );
+});
+
+// forwardRef Tooltip 유지를 위해 displayName 지정.
+Checkbox.displayName = "Checkbox";
 
 /**
  * 체크박스 필드 컴포넌트; label/helper 텍스트 래퍼
@@ -76,7 +77,7 @@ export const Checkbox = forwardRef<HTMLButtonElement, CheckboxProps>(
  * @example
  * <CheckboxField label="약관 동의" helperText="필수" checked />
  */
-export const CheckboxField = forwardRef<HTMLButtonElement, CheckboxFieldProps>(
+const CheckboxField = forwardRef<HTMLButtonElement, CheckboxFieldProps>(
   function CheckboxField(
     {
       label,
@@ -146,3 +147,8 @@ export const CheckboxField = forwardRef<HTMLButtonElement, CheckboxFieldProps>(
     );
   },
 );
+
+// forwardRef Tooltip 유지를 위해 displayName 지정.
+CheckboxField.displayName = "CheckboxField";
+
+export { Checkbox, CheckboxField };

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

@@ -2,7 +2,16 @@ import { DropdownFoundation } from "./foundation";
 import DropdownTemplate from "./Template";
 
 /**
- * Dropdown namespace export
+ * Dropdown
+ * - Provider
+ * - Root
+ * - Container
+ * - Menu
+ *     - Item
+ *     - List
+ * - Panel
+ * - Trigger
+ * - Template
  */
 export const Dropdown = {
   ...DropdownFoundation,

package/src/components/input/hooks/index.ts

@@ -1 +1,2 @@
 export { useDigitField } from "./useDigitField";
+export { useAddress, useAddressFields } from "./useAddress";