@uniai-fe/uds-primitives 0.0.15 → 0.0.17

package/src/components/pagination/markup/Carousel.tsx

@@ -9,68 +9,86 @@ import {
 } from "../utils";
 
 /**
- * Carousel indicator Pagination. 점 형태로 현재 위치만 표시한다.
- * @component
- * @param {PaginationCarouselProps} props
- * @param {number} props.total 전체 step 수.
+ * @component PaginationCarousel
+ * @description
+ *  Carousel(dot) indicator를 렌더한다. total/current는 normalizePaginationState로 보정하고,
+ *  onPageChange가 없으면 버튼을 disabled 처리해 pointer/cursor를 제거한다.
+ *  priority prop은 data attribute로 노출되어 SCSS에서 primary/secondary(active color) 토큰을 분기한다.
+ * @param {PaginationCarouselProps} props Carousel 구성 옵션.
+ * @param {number} props.total 전체 step 개수.
  * @param {number} [props.current=1] 현재 step index(1-indexed).
- * @param {(page: number) => void} [props.onPageChange]
- *  전달 시 dot를 클릭해 이동할 수 있고, 생략하면 모든 dot가 disabled 된다.
- * @param {string} [props.className] `.pagination` root className.
+ * @param {(page: number) => void} [props.onPageChange] dot를 클릭해 이동시키는 핸들러. 미제공 시 인터랙션이 비활성화된다.
+ * @param {string} [props.className] `.pagination` 루트 className merge 용도.
+ * @param {PaginationCarouselProps["priority"]} [props.priority=\"primary\"] active dot 색상 priority.
+ * @returns {JSX.Element} dot indicator `<ul>`.
  */
 const PaginationCarousel = forwardRef<
   HTMLUListElement,
   PaginationCarouselProps
->(({ total, current = 1, onPageChange, className, ...restProps }, ref) => {
-  const { total: normalizedTotal, current: normalizedCurrent } =
-    normalizePaginationState({ total, current });
-  const pages = createPaginationPages(normalizedTotal);
-  const allowInteraction = typeof onPageChange === "function";
-  const rootClassName = composePaginationClassName({
-    variant: "carousel",
-    className,
-  });
+>(
+  (
+    {
+      total,
+      current = 1,
+      onPageChange,
+      className,
+      priority = "primary",
+      ...restProps
+    },
+    ref,
+  ) => {
+    const { total: normalizedTotal, current: normalizedCurrent } =
+      normalizePaginationState({ total, current });
+    const pages = createPaginationPages(normalizedTotal);
+    const allowInteraction = typeof onPageChange === "function";
+    const rootClassName = composePaginationClassName({
+      variant: "carousel",
+      className,
+    });
 
-  const handleClick = (page: number) => {
-    if (!allowInteraction || page === normalizedCurrent) {
-      return;
-    }
-    onPageChange?.(page);
-  };
+    const handleClick = (page: number) => {
+      if (!allowInteraction || page === normalizedCurrent) {
+        return;
+      }
+      onPageChange?.(page);
+    };
 
-  return (
-    <ul
-      {...restProps}
-      ref={ref}
-      className={rootClassName}
-      data-variant="carousel"
-      data-interactive={allowInteraction ? "true" : "false"}
-    >
-      {pages.map(page => {
-        const isActive = page === normalizedCurrent;
-        return (
-          <li
-            key={page}
-            className={PAGINATION_ITEM_CLASSNAME}
-            data-active={isActive ? "true" : undefined}
-          >
-            <button
-              type="button"
-              className={PAGINATION_BUTTON_CLASSNAME}
+    // priority data attr는 primary/secondary dot 색상을 분기한다.
+    return (
+      <ul
+        {...restProps}
+        ref={ref}
+        className={rootClassName}
+        data-variant="carousel"
+        data-interactive={allowInteraction ? "true" : "false"}
+        data-priority={priority}
+      >
+        {pages.map(page => {
+          const isActive = page === normalizedCurrent;
+          return (
+            <li
+              key={page}
+              className={PAGINATION_ITEM_CLASSNAME}
               data-active={isActive ? "true" : undefined}
-              aria-label={`Step ${page}`}
-              disabled={!allowInteraction}
-              tabIndex={allowInteraction ? 0 : -1}
-              onClick={allowInteraction ? () => handleClick(page) : undefined}
             >
-              <span className="pagination-dot" aria-hidden="true" />
-            </button>
-          </li>
-        );
-      })}
-    </ul>
-  );
-});
+              <button
+                type="button"
+                className={PAGINATION_BUTTON_CLASSNAME}
+                data-active={isActive ? "true" : undefined}
+                aria-label={`Step ${page}`}
+                disabled={!allowInteraction}
+                tabIndex={allowInteraction ? 0 : -1}
+                onClick={allowInteraction ? () => handleClick(page) : undefined}
+              >
+                <span className="pagination-dot" aria-hidden="true" />
+              </button>
+            </li>
+          );
+        })}
+      </ul>
+    );
+  },
+);
 
 PaginationCarousel.displayName = "PaginationCarousel";
 

package/src/components/pagination/markup/Count.tsx

@@ -7,13 +7,16 @@ import {
 } from "../utils";
 
 /**
- * Count(step) indicator; `1/5` 형태로 현재 위치만 표시한다.
- * @component
- * @param {PaginationCountProps} props
+ * @component PaginationCount
+ * @description
+ *  Count(step) indicator를 `current/total` pill 형태로 렌더한다. 실제로는 disabled button을 사용해
+ *  시각적 일관성을 유지하고, normalizePaginationState로 total/current를 보정한다.
+ * @param {PaginationCountProps} props Count variant 구성 옵션.
  * @param {number} props.total 전체 step 수.
- * @param {number} [props.current=1] 현재 step position.
- * @param {"small" | "xsmall"} [props.size="small"] 높이/타이포 크기 옵션.
- * @param {string} [props.className] `.pagination` root className.
+ * @param {number} [props.current=1] 현재 위치(1-indexed).
+ * @param {PaginationCountProps["size"]} [props.size=\"small\"] 높이/타이포 크기.
+ * @param {string} [props.className] `.pagination` 루트 className merge 용도.
+ * @returns {JSX.Element} count indicator `<div>`.
  */
 const PaginationCount = forwardRef<HTMLDivElement, PaginationCountProps>(
   ({ total, current = 1, size = "small", className, ...restProps }, ref) => {

package/src/components/pagination/markup/Pagination.tsx

@@ -9,15 +9,17 @@ import {
 } from "../utils";
 
 /**
- * 숫자 페이지형 Pagination.
- * @component
- * @param {PaginationProps} props
- * @param {number} props.total 전체 페이지 개수(1 이상으로 자동 보정).
- * @param {number} [props.current=1] 현재 페이지. total 범위를 벗어나면 자동 조정된다.
- * @param {(page: number) => void} [props.onPageChange]
- *  페이지 버튼 클릭 핸들러. 전달되지 않으면 모든 버튼이 disabled 처리되어 cursor가 제거된다.
- * @param {string} [props.className] `.pagination` root className.
- * @param {React.AriaAttributes} [props.aria-*] ul element에 전달될 기타 속성.
+ * @component Pagination
+ * @description
+ *  List variant pagination을 구현한다. total/current 값을 보정해 최소 1~total 범위의 페이지 버튼을 렌더하고,
+ *  onPageChange가 없으면 data-interactive 값을 false로 지정해 전부 disabled 상태로 노출한다.
+ * @param {PaginationProps} props Pagination 구성 옵션.
+ * @param {number} props.total 전체 페이지 개수. 1 미만이면 자동으로 1로 보정된다.
+ * @param {number} [props.current=1] 현재 활성 페이지(1-indexed). total 범위를 벗어나면 자동 조정된다.
+ * @param {(page: number) => void} [props.onPageChange] 페이지 변경 핸들러. 미제공 시 버튼은 disabled 처리되고 tabIndex가 -1이 된다.
+ * @param {string} [props.className] `.pagination` 루트 className merge 용도.
+ * @param {React.AriaAttributes} [props.aria-*] ARIA 속성은 그대로 `<ul>`에 전달된다.
+ * @returns {JSX.Element} 페이지 네비게이터 `<ul>`.
  * @example
  * ```tsx
  * <Pagination total={10} current={3} onPageChange={setPage} />

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

@@ -13,6 +13,10 @@
   --pagination-dot-size: 8px;
   --pagination-dot-bg: var(--color-cool-gray-85, #d2d3d7);
   --pagination-dot-active-bg: var(--color-primary-default, #0061ff);
+  --pagination-dot-active-bg-secondary: var(
+    --color-bg-surface-heavy,
+    #313235
+  ); // semantic surface heavy
   --pagination-carousel-height: 8px;
   --pagination-carousel-dot-width: 8px;
   --pagination-carousel-active-width: 20px;
@@ -94,6 +98,14 @@
   align-items: center;
 }
 
+// secondary priority일 때 active dot 컬러를 재정의한다.
+.pagination--variant-carousel[data-priority="secondary"] {
+  --pagination-dot-active-bg: var(
+    --pagination-dot-active-bg-secondary,
+    var(--color-secondary-strong, #ccdeff)
+  );
+}
+
 .pagination--variant-carousel .pagination-button {
   width: auto;
   height: var(--pagination-carousel-height);

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

@@ -2,9 +2,12 @@ import type { ComponentPropsWithoutRef } from "react";
 
 export const PAGINATION_VARIANTS = ["list", "carousel", "count"] as const;
 export const PAGINATION_COUNT_SIZES = ["small", "xsmall"] as const;
+export const PAGINATION_CAROUSEL_PRIORITIES = ["primary", "secondary"] as const;
 
 export type PaginationVariant = (typeof PAGINATION_VARIANTS)[number];
 export type PaginationCountSize = (typeof PAGINATION_COUNT_SIZES)[number];
+export type PaginationCarouselPriority =
+  (typeof PAGINATION_CAROUSEL_PRIORITIES)[number];
 
 type NativeListProps = ComponentPropsWithoutRef<"ul">;
 type NativeDivProps = ComponentPropsWithoutRef<"div">;
@@ -28,7 +31,9 @@ interface PaginationInteractiveProps {
 }
 
 /**
- * 숫자 페이지용 Pagination props
+ * 숫자 페이지용 Pagination props.
+ * native `<ul>` 속성과 state/interaction 옵션(total/current/onPageChange)을 함께 받는다.
+ * onPageChange가 전달되지 않으면 버튼이 disabled 상태가 되며 focus 방지를 위해 tabIndex가 -1로 설정된다.
  */
 export interface PaginationProps
   extends
@@ -37,16 +42,24 @@ export interface PaginationProps
     PaginationInteractiveProps {}
 
 /**
- * Carousel 점 indicator props
+ * Carousel(dot) indicator props.
+ * native `<ul>` 속성과 total/current/onPageChange + priority 옵션을 함께 받아 dot 상태를 제어한다.
+ * priority는 SCSS data attribute 기반으로 semantic primary/secondary active 색상을 선택한다.
  */
 export interface PaginationCarouselProps
   extends
     Omit<NativeListProps, "children" | "onChange">,
     PaginationBaseProps,
-    PaginationInteractiveProps {}
+    PaginationInteractiveProps {
+  /**
+   * dot active 색상 priority. primary(semantic primary standard) 또는 secondary(semantic surface heavy) 옵션을 제공한다.
+   */
+  priority?: PaginationCarouselPriority;
+}
 
 /**
- * Count(step) indicator props
+ * Count(step) indicator props.
+ * `<div>` 래퍼에 disabled button을 내장해 `current/total` 텍스트만 출력하며 size로 높이/타이포를 전환한다.
  */
 export interface PaginationCountProps
   extends Omit<NativeDivProps, "children">, PaginationBaseProps {

package/src/components/input/markup/text/Identification.tsx

@@ -1,159 +0,0 @@
-import {
-  ClipboardEvent,
-  ChangeEvent,
-  forwardRef,
-  useImperativeHandle,
-  KeyboardEvent,
-  ReactNode,
-  useCallback,
-  useMemo,
-  useRef,
-  useState,
-} from "react";
-import type { InputState } from "../../types";
-
-/**
- * IdentificationInput props. 고정 길이 숫자 코드 입력에 필요한 label/helper/state/onComplete를 제공한다.
- * @property {number} [length=6] 입력칸 개수(4~8 사이로 자동 보정).
- * @property {ReactNode} [label] 상단 라벨.
- * @property {ReactNode} [helper] helper 텍스트.
- * @property {InputState} [state="default"] 시각 상태.
- * @property {(code: string) => void} [onComplete] 모든 셀이 채워졌을 때 호출.
- */
-export interface IdentificationInputProps {
-  length?: number;
-  label?: ReactNode;
-  helper?: ReactNode;
-  state?: InputState;
-  onComplete?: (code: string) => void;
-}
-
-/**
- * IdentificationInput — 인증번호 입력 UI. 개별 입력칸을 제공하고 focus 이동/붙여넣기 등을 처리한다.
- * @component
- * @param {IdentificationInputProps} props
- * @param {number} [props.length=6] 입력 필드 길이. 4~8 범위로 자동 보정된다.
- * @param {ReactNode} [props.label] 상단 label 콘텐츠.
- * @param {ReactNode} [props.helper] helper 텍스트.
- * @param {InputState} [props.state] 시각 상태.
- * @param {(code: string) => void} [props.onComplete] 모든 셀이 채워졌을 때 호출되는 콜백.
- */
-const IdentificationInput = forwardRef<
-  HTMLInputElement[],
-  IdentificationInputProps
->(({ length = 6, label, helper, state, onComplete }, forwardedRef) => {
-  const safeLength = Math.max(4, Math.min(8, length));
-  const [values, setValues] = useState(() =>
-    Array.from({ length: safeLength }, () => ""),
-  );
-  const inputRefs = useRef<Array<HTMLInputElement | null>>(
-    Array(safeLength).fill(null),
-  );
-
-  const focusCell = useCallback((index: number) => {
-    const ref = inputRefs.current[index];
-    ref?.focus();
-    ref?.select();
-  }, []);
-
-  const updateValues = useCallback(
-    (index: number, digit: string) => {
-      setValues(prev => {
-        const next = [...prev];
-        next[index] = digit;
-        if (!next.includes("")) {
-          onComplete?.(next.join(""));
-        }
-        return next;
-      });
-    },
-    [onComplete],
-  );
-
-  const handleChange = useCallback(
-    (index: number) => (event: ChangeEvent<HTMLInputElement>) => {
-      const digit = event.target.value.replace(/\D/g, "").slice(-1);
-      updateValues(index, digit);
-      if (digit && index < safeLength - 1) {
-        focusCell(index + 1);
-      }
-    },
-    [focusCell, safeLength, updateValues],
-  );
-
-  const handleKeyDown = useCallback(
-    (index: number) => (event: KeyboardEvent<HTMLInputElement>) => {
-      if (event.key === "Backspace" && !values[index] && index > 0) {
-        updateValues(index - 1, "");
-        focusCell(index - 1);
-        event.preventDefault();
-      }
-    },
-    [focusCell, updateValues, values],
-  );
-
-  const handlePaste = useCallback(
-    (event: ClipboardEvent<HTMLInputElement>) => {
-      const digits = event.clipboardData.getData("text").replace(/\D/g, "");
-      if (!digits) {
-        return;
-      }
-      event.preventDefault();
-      setValues(prev => {
-        const next = [...prev];
-        for (let i = 0; i < safeLength; i += 1) {
-          next[i] = digits[i] ?? next[i];
-        }
-        if (!next.includes("")) {
-          onComplete?.(next.join(""));
-        }
-        return next;
-      });
-    },
-    [onComplete, safeLength],
-  );
-
-  const helperNode = useMemo(() => helper, [helper]);
-
-  // forwardRef 사용자는 각 셀 DOM 배열을 직접 제어할 수 있도록 노출한다.
-  useImperativeHandle(
-    forwardedRef,
-    () =>
-      inputRefs.current.filter((element): element is HTMLInputElement =>
-        Boolean(element),
-      ),
-    [],
-  );
-
-  return (
-    <div className="one-time-code" data-state={state}>
-      {label ? <div className="one-time-code__label">{label}</div> : null}
-      <div className="one-time-code__fields">
-        {values.map((value, index) => (
-          <input
-            key={`identification-${index}`}
-            ref={element => {
-              inputRefs.current[index] = element;
-            }}
-            type="text"
-            inputMode="numeric"
-            className="one-time-code__input"
-            maxLength={1}
-            value={value}
-            onChange={handleChange(index)}
-            onKeyDown={handleKeyDown(index)}
-            onPaste={handlePaste}
-            aria-label={`${index + 1}번째 인증번호 숫자`}
-          />
-        ))}
-      </div>
-      {helperNode ? (
-        <div className="one-time-code__helper">{helperNode}</div>
-      ) : null}
-    </div>
-  );
-});
-
-IdentificationInput.displayName = "IdentificationInput";
-
-export { IdentificationInput };