@uniai-fe/uds-primitives 0.1.13 → 0.2.0

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

@@ -0,0 +1,39 @@
+"use client";
+
+import clsx from "clsx";
+import type { FormFieldHeaderProps } from "../../types";
+
+/**
+ * Form; field header
+ * @component
+ * @param {FormFieldHeaderProps} props
+ * @property {string} [className]
+ * @property {string} [label] 필드명
+ * @property {React.ElementType} [labelAs] 필드 태그 지정 (default: <h5 />)
+ * @property {string} [labelId] 필드 아이디 지정
+ * @property {boolean} [required] 필수 여부
+ * @property {React.ReactNode} [children] 추가 헤더 내용
+ * @property {React.HTMLAttributes<HTMLElement>} [labelProps] 추가 라벨 속성
+ */
+export default function FormFieldHeader({
+  className,
+  label,
+  labelAs: LabelTag = "h5",
+  labelId,
+  labelProps = {},
+  required,
+  children,
+  ...headerAttrs
+}: FormFieldHeaderProps) {
+  return (
+    <header className={clsx("form-field-header", className)} {...headerAttrs}>
+      {label && (
+        <LabelTag className="form-field-label" {...labelProps} id={labelId}>
+          <span>{label}</span>
+          {required && <span className="form-field-required">*</span>}
+        </LabelTag>
+      )}
+      {children}
+    </header>
+  );
+}

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

@@ -0,0 +1,56 @@
+"use client";
+
+import { forwardRef } from "react";
+
+import type { FormFieldTemplateProps } from "../../types/props";
+import FormFieldHeader from "./Header";
+import FormFieldBody from "./Body";
+import FormFieldFooter from "./Footer";
+import FormFieldContainer from "./Container";
+
+/**
+ * Form; field template
+ * @component
+ * @param {FormFieldTemplateProps} props
+ * @property {string} [className]
+ * @property {React.ElementType} [as] container 태그 지정 (default: <section />)
+ * @property {React.ReactNode} [footer] 푸터 내용
+ * @property {FormFieldHeaderProps} [headerProps] 헤더 속성
+ * @property {FormFieldFooterProps} [footerProps] 푸터 속성
+ * @property {FormFieldWidth} [width] form field 너비 옵션
+ * @property {React.HTMLAttributes<HTMLElement>} [containerProps] container 속성
+ * @property {React.ReactNode} children
+ */
+const FormFieldTemplate = forwardRef<HTMLElement, FormFieldTemplateProps>(
+  (
+    {
+      className,
+      as,
+      footer,
+      headerProps,
+      footerProps,
+      children,
+      width,
+      ...containerProps
+    },
+    forwardedRef,
+  ) => {
+    return (
+      <FormFieldContainer
+        ref={forwardedRef}
+        as={as}
+        className={className}
+        width={width}
+        {...containerProps}
+      >
+        <FormFieldHeader {...headerProps} />
+        <FormFieldBody>{children}</FormFieldBody>
+        {footer && <FormFieldFooter {...footerProps}>{footer}</FormFieldFooter>}
+      </FormFieldContainer>
+    );
+  },
+);
+
+FormFieldTemplate.displayName = "FormFieldTemplate";
+
+export default FormFieldTemplate;

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

@@ -0,0 +1,22 @@
+import FormFieldContainer from "./Container";
+import FormFieldHeader from "./Header";
+import FormFieldBody from "./Body";
+import FormFieldFooter from "./Footer";
+import FormFieldTemplate from "./Template";
+
+/**
+ * Form; form field 컴포넌트
+ * @component
+ * @desc
+ * - FormField.Container: Form 필드의 컨테이너 컴포넌트
+ * - FormField.Header: Form 필드의 헤더 컴포넌트
+ * - FormField.Body: Form 필드의 본문 컴포넌트
+ * - FormField.Footer: Form 필드의 푸터 컴포넌트
+ */
+export const FormField = {
+  Container: FormFieldContainer,
+  Header: FormFieldHeader,
+  Body: FormFieldBody,
+  Footer: FormFieldFooter,
+  Template: FormFieldTemplate,
+};

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

@@ -0,0 +1,67 @@
+.form-field-container {
+  display: block;
+  width: var(--form-field-width);
+  flex: var(--form-field-flex);
+
+  &[data-width="auto"] {
+    --form-field-width: auto;
+    --form-field-flex: 0 0 auto;
+  }
+
+  &[data-width="fill"] {
+    --form-field-width: auto;
+    --form-field-flex: 1 1 0%;
+  }
+
+  &[data-width="full"] {
+    --form-field-width: 100%;
+    --form-field-flex: 0 0 100%;
+  }
+
+  &[data-width="fit"] {
+    --form-field-width: fit-content;
+    --form-field-flex: 0 0 auto;
+  }
+
+  &[data-width="custom"] {
+    --form-field-flex: 0 0 auto;
+  }
+}
+
+.form-field-header {
+  margin-bottom: var(--form-field-gap-y);
+}
+
+.form-field-label {
+  display: flex;
+  align-items: center;
+  gap: var(--spacing-gap-1);
+
+  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 {
+    color: var(--form-field-label-color);
+  }
+}
+
+.form-field-required {
+  color: var(--color-feedback-error);
+}
+
+.form-field-body {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--form-field-gap-x);
+  width: 100%;
+}
+
+.form-field-footer {
+  margin-top: var(--form-field-gap-y);
+  font-size: var(--form-field-helper-font-size);
+  line-height: var(--form-field-helper-line-height);
+  p,
+  span {
+    color: var(--form-field-helper-color);
+  }
+}

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

@@ -0,0 +1,17 @@
+:root {
+  --form-field-width: auto;
+  --form-field-flex: 0 0 auto;
+
+  --form-field-gap-x: var(--spacing-gap-5, 12px);
+  --form-field-gap-y: var(--spacing-gap-3, 6px);
+
+  --form-field-label-font-size: var(--font-label-small-size);
+  --form-field-label-font-weight: 400;
+  --form-field-label-line-height: var(--font-label-small-line-height);
+  --form-field-label-color: var(--color-label-standard);
+
+  --form-field-helper-font-size: var(--font-caption-medium-size);
+  --form-field-helper-font-weight: 400;
+  --form-field-helper-line-height: var(--font-caption-medium-line-height);
+  --form-field-helper-color: var(--color-label-neutral);
+}

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

@@ -0,0 +1,2 @@
+@use "./form-field/variables.scss";
+@use "./form-field/layout.scss";

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

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

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

@@ -0,0 +1,125 @@
+import type { ElementType } from "react";
+
+/**
+ * Form; field container width option
+ * - full: 상위 영역을 100%로 채움
+ * - fit: 콘텐츠 너비에 맞춤
+ * - fill: flex-grow 1 분배
+ * - auto: 기본 width(auto)
+ * - number: px 단위 입력, rem으로 환산
+ * - string: CSS width 문자열
+ */
+export type FormFieldWidth = "full" | "fit" | "fill" | "auto" | number | string;
+
+/**
+ * Form.Field Header props; `Header.tsx`에서 label/description/meta를 제어한다.
+ * @property {string} [className] 헤더 wrapper className
+ * @property {React.ElementType} [labelAs] heading 태그 지정 (default: h5)
+ * @property {string} [labelId] label DOM id
+ * @property {string} [label] 기본 label 텍스트
+ * @property {React.ReactNode} [labelJsx] label JSX 대체
+ * @property {React.HTMLAttributes<HTMLElement>} [labelProps] label 태그 속성
+ * @property {boolean} [required] 필수 표시
+ * @property {React.ReactNode} [children] description 등 추가 요소
+ */
+export interface FormFieldHeaderProps extends React.HTMLAttributes<HTMLElement> {
+  /**
+   * 헤더 wrapper className
+   */
+  className?: string;
+  /**
+   * label heading 태그
+   */
+  labelAs?: ElementType;
+  /**
+   * label DOM id
+   */
+  labelId?: string;
+  /**
+   * 기본 label 텍스트
+   */
+  label?: string;
+  /**
+   * 커스텀 label JSX
+   */
+  labelJsx?: React.ReactNode;
+  /**
+   * label 태그 추가 속성
+   */
+  labelProps?: React.HTMLAttributes<HTMLElement>;
+  /**
+   * 필수 여부
+   */
+  required?: boolean;
+  /**
+   * description 등 추가 요소
+   */
+  children?: React.ReactNode;
+}
+
+/**
+ * Form.Field Footer props; `Footer.tsx`에서 helper/action 영역을 담당한다.
+ * @property {string} [className] footer className
+ * @property {React.ReactNode} [children] footer 내용
+ */
+export interface FormFieldFooterProps extends React.HTMLAttributes<HTMLElement> {
+  /**
+   * footer className
+   */
+  className?: string;
+  /**
+   * footer 내용
+   */
+  children?: React.ReactNode;
+}
+
+/**
+ * Form.Field Container props; `Container.tsx`에서 wrapper와 width 옵션을 제어한다.
+ * @property {string} [className] container className
+ * @property {React.ElementType} [as] container 태그
+ * @property {FormFieldWidth} [width] width 옵션(full/fit/fill/auto/custom)
+ * @property {React.ReactNode} children Body에 전달될 콘텐츠
+ */
+export interface FormFieldContainerProps extends React.HTMLAttributes<HTMLElement> {
+  /**
+   * container className
+   */
+  className?: string;
+  /**
+   * container 태그
+   */
+  as?: ElementType;
+  /**
+   * width 옵션
+   */
+  width?: FormFieldWidth;
+  /**
+   * 필드 children
+   */
+  children: React.ReactNode;
+}
+
+/**
+ * Form.Field Template props; `Template.tsx`에서 Header/Footer 조합을 제공한다.
+ * @property {React.ReactNode} [footer] Footer helper 내용
+ * @property {FormFieldHeaderProps} [headerProps] Header props
+ * @property {FormFieldFooterProps} [footerProps] Footer props
+ * @property {string} [className] container className
+ * @property {React.ElementType} [as] container 태그
+ * @property {FormFieldWidth} [width] width 옵션(full/fit/fill/auto/custom)
+ * @property {React.ReactNode} children Body에 전달될 콘텐츠
+ */
+export interface FormFieldTemplateProps extends FormFieldContainerProps {
+  /**
+   * Footer helper 내용
+   */
+  footer?: React.ReactNode;
+  /**
+   * Header props
+   */
+  headerProps?: FormFieldHeaderProps;
+  /**
+   * Footer props
+   */
+  footerProps?: FormFieldFooterProps;
+}

package/src/components/form/utils/form-field.ts

@@ -0,0 +1,42 @@
+import { styleBaseSize } from "@uniai-fe/util-functions";
+import type { FormFieldWidth } from "../types";
+
+const WIDTH_PRESETS = new Set<FormFieldWidth>(["full", "fit", "fill", "auto"]);
+
+/**
+ * Form.Field width attr helper; preset이면 그대로 반환하고 custom이면 "custom"/기본값은 "auto".
+ * @function
+ * @param {FormFieldWidth} [width]
+ * @returns {string}
+ */
+export const getFormFieldWidthAttr = (width?: FormFieldWidth): string => {
+  if (typeof width === "string" && WIDTH_PRESETS.has(width)) {
+    return width;
+  }
+
+  if (typeof width === "number" || typeof width === "string") {
+    return "custom";
+  }
+
+  return "auto";
+};
+
+/**
+ * Form.Field width style helper; number/string custom 값을 CSS width 문자열로 환산한다.
+ * @function
+ * @param {FormFieldWidth} [width]
+ * @returns {string | undefined}
+ */
+export const getFormFieldWidthValue = (
+  width?: FormFieldWidth,
+): string | undefined => {
+  if (typeof width === "number" && Number.isFinite(width)) {
+    return styleBaseSize("rem", width);
+  }
+
+  if (typeof width === "string" && !WIDTH_PRESETS.has(width)) {
+    return width;
+  }
+
+  return undefined;
+};

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

@@ -1,4 +1 @@
-/**
- * TODO(input): 접근성/상태 계산 hook을 정의한다.
- */
-export {};
+export { useDigitField } from "./useDigitField";

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

@@ -0,0 +1,63 @@
+"use client";
+
+import { ChangeEvent, useCallback, useEffect, useMemo, useState } from "react";
+import type { UseDigitFieldOptions, UseDigitFieldResult } from "../types";
+
+/**
+ * 숫자 입력값만 유지하도록 정규화한다.
+ * @param {string | undefined} value 원본 문자열
+ * @returns {string} 숫자만 남긴 문자열
+ */
+export const normalizeDigits = (value?: string) =>
+  (value ?? "").replace(/\D/g, "");
+
+/**
+ * 숫자 기반 입력 필드의 제어/비제어 값을 일관되게 다룬다.
+ * @hook
+ * @param {UseDigitFieldOptions} options value/defaultValue/maxLength 옵션
+ */
+export const useDigitField = ({
+  value,
+  defaultValue,
+  maxLength,
+}: UseDigitFieldOptions): UseDigitFieldResult => {
+  const limit = maxLength ?? Number.POSITIVE_INFINITY;
+  const isControlled = value !== undefined;
+  const clampDigits = useCallback(
+    (raw: string) => normalizeDigits(raw).slice(0, limit),
+    [limit],
+  );
+  const [innerDigits, setInnerDigits] = useState(() =>
+    clampDigits(defaultValue ?? ""),
+  );
+
+  // uncontrolled 값이 있고 maxLength가 줄어들면 즉시 잘라낸다.
+  useEffect(() => {
+    if (isControlled) {
+      return;
+    }
+    setInnerDigits(prev => clampDigits(prev));
+  }, [clampDigits, isControlled]);
+
+  const resolvedDigits = useMemo(() => {
+    const target = isControlled ? (value ?? "") : innerDigits;
+    return clampDigits(target);
+  }, [clampDigits, innerDigits, isControlled, value]);
+
+  const handleDigitsChange = useCallback(
+    (event: ChangeEvent<HTMLInputElement>) => {
+      const digitsOnly = clampDigits(event.currentTarget.value);
+      if (!isControlled) {
+        setInnerDigits(digitsOnly);
+      }
+      return digitsOnly;
+    },
+    [clampDigits, isControlled],
+  );
+
+  return {
+    digits: resolvedDigits,
+    isControlled,
+    handleDigitsChange,
+  };
+};

package/src/components/input/img/calendar/calendar.svg

@@ -0,0 +1,7 @@
+<svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+<rect x="20.2" y="6.8" width="13.4" height="16.4" rx="1.2" transform="rotate(90 20.2 6.8)" stroke="#BCBEC2" stroke-width="1.6"/>
+<path d="M4 10C9.33333 10 20 10 20 10" stroke="#BCBEC2" stroke-width="1.6"/>
+<path d="M7 13L9 13" stroke="#BCBEC2" stroke-width="1.6"/>
+<path d="M8.8 4C8.8 3.55817 8.44183 3.2 8 3.2C7.55817 3.2 7.2 3.55817 7.2 4L8 4L8.8 4ZM8 4L7.2 4L7.2 6L8 6L8.8 6L8.8 4L8 4Z" fill="#BCBEC2"/>
+<path d="M16.8 4C16.8 3.55817 16.4418 3.2 16 3.2C15.5582 3.2 15.2 3.55817 15.2 4L16 4L16.8 4ZM16 4L15.2 4L15.2 6L16 6L16.8 6L16.8 4L16 4Z" fill="#BCBEC2"/>
+</svg>

package/src/components/input/img/calendar/chevron-down.svg

@@ -0,0 +1,3 @@
+<svg width="20" height="10" viewBox="0 0 20 10" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M6.66669 3.33325L10 6.66659L13.3334 3.33325" stroke="#94989E" stroke-width="1.25" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

package/src/components/input/img/calendar/chevron-left.svg

@@ -0,0 +1,3 @@
+<svg width="20" height="20" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M12.5 3.33325L5.83333 9.99992L12.5 16.6666" stroke="#94989E" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

package/src/components/input/img/calendar/chevron-right.svg

@@ -0,0 +1,3 @@
+<svg width="20" height="20" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M7.5 16.6667L14.1667 10.0001L7.5 3.33342" stroke="#94989E" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

package/src/components/input/img/calendar/chevron-up.svg

@@ -0,0 +1,3 @@
+<svg width="20" height="10" viewBox="0 0 20 10" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M6.66669 6.66675L10 3.33341L13.3334 6.66675" stroke="#94989E" stroke-width="1.25" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

package/src/components/input/index.tsx

@@ -5,5 +5,6 @@ import "./index.scss";
 
 export * from "./markup";
 export * from "./hooks";
-export type * from "./types";
 export * from "./utils";
+
+export type * from "./types";