@uniai-fe/uds-primitives 0.0.15 → 0.0.16

package/dist/styles.css

@@ -2626,6 +2626,10 @@ figure.chip {
   --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
+  );
   --pagination-carousel-height: 8px;
   --pagination-carousel-dot-width: 8px;
   --pagination-carousel-active-width: 20px;
@@ -2701,6 +2705,13 @@ figure.chip {
   align-items: center;
 }
 
+.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniai-fe/uds-primitives",
-  "version": "0.0.15",
+  "version": "0.0.16",
   "description": "UNIAI Design System; Primitives Components Package",
   "type": "module",
   "private": false,

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 {