@uniai-fe/uds-primitives 0.3.3 → 0.3.5

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

@@ -0,0 +1,372 @@
+import type * as React from "react";
+
+/**
+ * Carousel Types; 방향 타입
+ * @typedef {"prev" | "next"} CarouselDirection
+ */
+export type CarouselDirection = "prev" | "next";
+
+/**
+ * Carousel Types; 버튼 배치 타입
+ * @typedef {"outside" | "inside"} CarouselButtonPlacement
+ */
+export type CarouselButtonPlacement = "outside" | "inside";
+
+/**
+ * Carousel Types; Hook 옵션
+ * @property {boolean} [optional] true면 Provider 미존재 시 null 반환
+ */
+export interface CarouselHookOptions {
+  /**
+   * true면 Provider 미존재 시 null 반환
+   */
+  optional?: boolean;
+}
+
+/**
+ * Carousel Types; Hook optional 반환 강제 옵션
+ * @property {true} optional Provider 미존재 시 null 반환을 허용하는 옵션
+ */
+export interface CarouselHookOptionalOptions {
+  /**
+   * Provider 미존재 시 null 반환을 허용하는 옵션
+   */
+  optional: true;
+}
+
+/**
+ * Carousel Types; Provider props
+ * @property {React.ReactNode} children Carousel 하위 콘텐츠
+ * @property {number} [buttonMoveCount=1] Prev/Next 기본 viewport page 이동 개수
+ * @property {number} [visibleCount] viewport 내 표시 item 개수 고정값
+ * @property {(index: number) => void} [onIndexChange] 현재 index 변경 콜백
+ */
+export interface CarouselProviderProps {
+  /**
+   * Carousel 하위 콘텐츠
+   */
+  children: React.ReactNode;
+  /**
+   * Prev/Next 기본 viewport page 이동 개수
+   */
+  buttonMoveCount?: number;
+  /**
+   * viewport 내 표시 item 개수 고정값
+   */
+  visibleCount?: number;
+  /**
+   * 현재 index 변경 콜백
+   */
+  onIndexChange?: (index: number) => void;
+}
+
+/**
+ * Carousel Types; Provider Controller 파라미터
+ * @property {number} [buttonMoveCount] Prev/Next 기본 viewport page 이동 개수
+ * @property {number} [visibleCount] viewport 내 표시 item 개수 고정값
+ * @property {(index: number) => void} [onIndexChange] 현재 index 변경 콜백
+ */
+export interface CarouselProviderControllerParams {
+  /**
+   * Prev/Next 기본 viewport page 이동 개수
+   */
+  buttonMoveCount?: number;
+  /**
+   * viewport 내 표시 item 개수 고정값
+   */
+  visibleCount?: number;
+  /**
+   * 현재 index 변경 콜백
+   */
+  onIndexChange?: (index: number) => void;
+}
+
+/**
+ * Carousel Types; Context 값
+ * @property {React.RefObject<HTMLDivElement | null>} viewportRef viewport ref
+ * @property {React.RefObject<HTMLUListElement | null>} trackRef track ref
+ * @property {() => void} onPrev 이전 이동 핸들러
+ * @property {() => void} onNext 다음 이동 핸들러
+ * @property {(count: number) => void} onPrevBy count 단위 이전 이동
+ * @property {(count: number) => void} onNextBy count 단위 다음 이동
+ * @property {(count: number) => void} moveBy count 단위 이동
+ * @property {(index: number) => void} moveTo 지정 index 이동
+ * @property {(count: number) => void} registerItemCount 아이템 개수 등록
+ * @property {number} itemCount 총 item 개수
+ * @property {number} visibleCount viewport 내 가시 item 개수
+ * @property {number} currentIndex 현재 index
+ * @property {number} focusIndex 포커스 index
+ * @property {number} maxIndex 이동 가능한 마지막 index
+ * @property {boolean} isReachStart 시작 지점 도달 여부
+ * @property {boolean} isReachEnd 마지막 지점 도달 여부
+ */
+export interface CarouselContextValue {
+  /**
+   * viewport ref
+   */
+  viewportRef: React.RefObject<HTMLDivElement | null>;
+  /**
+   * track ref
+   */
+  trackRef: React.RefObject<HTMLUListElement | null>;
+  /**
+   * 이전 이동 핸들러
+   */
+  onPrev: () => void;
+  /**
+   * 다음 이동 핸들러
+   */
+  onNext: () => void;
+  /**
+   * count 단위 이전 이동
+   */
+  onPrevBy: (count: number) => void;
+  /**
+   * count 단위 다음 이동
+   */
+  onNextBy: (count: number) => void;
+  /**
+   * count 단위 이동
+   */
+  moveBy: (count: number) => void;
+  /**
+   * 지정 index 이동
+   */
+  moveTo: (index: number) => void;
+  /**
+   * 아이템 개수 등록
+   */
+  registerItemCount: (count: number) => void;
+  /**
+   * 총 item 개수
+   */
+  itemCount: number;
+  /**
+   * viewport 내 가시 item 개수
+   */
+  visibleCount: number;
+  /**
+   * 현재 index
+   */
+  currentIndex: number;
+  /**
+   * 포커스 index
+   */
+  focusIndex: number;
+  /**
+   * 이동 가능한 마지막 index
+   */
+  maxIndex: number;
+  /**
+   * 시작 지점 도달 여부
+   */
+  isReachStart: boolean;
+  /**
+   * 마지막 지점 도달 여부
+   */
+  isReachEnd: boolean;
+}
+
+/**
+ * Carousel Types; Container props
+ * @property {React.ReactNode} children Carousel 콘텐츠
+ * @property {boolean} [activeButton=true] Prev/Next 자동 렌더링 여부
+ * @property {string} [className] 컨테이너 className
+ * @property {CarouselButtonPlacement} [buttonPlacement="outside"] 버튼 배치 방식
+ * @property {number} [buttonMoveCount=1] 버튼 클릭 시 이동 viewport page 개수
+ * @property {number} [visibleCount] viewport 내 표시 item 개수 고정값
+ * @property {(index: number) => void} [onIndexChange] 현재 index 변경 콜백
+ */
+export interface CarouselContainerProps {
+  /**
+   * Carousel 콘텐츠
+   */
+  children: React.ReactNode;
+  /**
+   * Prev/Next 버튼 자동 렌더링 여부
+   */
+  activeButton?: boolean;
+  /**
+   * 컨테이너 className
+   */
+  className?: string;
+  /**
+   * 버튼 배치 방식
+   */
+  buttonPlacement?: CarouselButtonPlacement;
+  /**
+   * 버튼 클릭 시 이동 viewport page 개수
+   */
+  buttonMoveCount?: number;
+  /**
+   * viewport 내 표시 item 개수 고정값
+   */
+  visibleCount?: number;
+  /**
+   * 현재 index 변경 콜백
+   */
+  onIndexChange?: (index: number) => void;
+}
+
+/**
+ * Carousel Types; Control props
+ * @property {React.ReactNode} children 버튼 사이에 배치할 콘텐츠
+ * @property {string} [className] 컨트롤 래퍼 className
+ * @property {CarouselButtonPlacement} [buttonPlacement="outside"] 버튼 배치 방식
+ * @property {number} [buttonMoveCount=1] 버튼 클릭 시 이동 viewport page 개수
+ */
+export interface CarouselControlProps {
+  /**
+   * 버튼 사이에 배치할 콘텐츠
+   */
+  children: React.ReactNode;
+  /**
+   * 컨트롤 래퍼 className
+   */
+  className?: string;
+  /**
+   * 버튼 배치 방식
+   */
+  buttonPlacement?: CarouselButtonPlacement;
+  /**
+   * 버튼 클릭 시 이동 viewport page 개수
+   */
+  buttonMoveCount?: number;
+}
+
+/**
+ * Carousel Types; Track props
+ * @property {React.ReactNode} children track item 목록
+ * @property {string} [className] viewport className
+ * @property {string} [trackClassName] track className
+ * @property {string} [itemClassName] 각 item에 공통으로 부여할 className
+ */
+export interface CarouselTrackProps extends Omit<
+  React.ComponentPropsWithoutRef<"div">,
+  "children"
+> {
+  /**
+   * track item 목록
+   */
+  children: React.ReactNode;
+  /**
+   * viewport className
+   */
+  className?: string;
+  /**
+   * track className
+   */
+  trackClassName?: string;
+  /**
+   * 각 item에 공통으로 부여할 className
+   */
+  itemClassName?: string;
+}
+
+/**
+ * Carousel Types; Button 공통 시각 props
+ * @property {React.ReactNode} [children] 버튼 콘텐츠 완전 교체 슬롯
+ * @property {React.ReactNode} [label] 기본 아이콘 조합에서 사용할 레이블
+ * @property {string} [className] 버튼 className
+ * @property {boolean} [disabled] 비활성 상태
+ */
+export interface CarouselButtonVisualProps extends Omit<
+  React.ComponentPropsWithoutRef<"button">,
+  "children" | "onClick"
+> {
+  /**
+   * 버튼 콘텐츠 완전 교체 슬롯
+   */
+  children?: React.ReactNode;
+  /**
+   * 기본 아이콘 조합에서 사용할 레이블
+   */
+  label?: React.ReactNode;
+  /**
+   * 버튼 className
+   */
+  className?: string;
+  /**
+   * 비활성 상태
+   */
+  disabled?: boolean;
+}
+
+/**
+ * Carousel Types; 이동 버튼 아이콘 래퍼 props
+ * @property {string} [className] 아이콘 래퍼 className
+ * @property {React.ReactNode} children 아이콘 래퍼 내부 콘텐츠
+ */
+export interface CarouselButtonIconFigureProps {
+  /**
+   * 아이콘 래퍼 className
+   */
+  className?: string;
+  /**
+   * 아이콘 래퍼 내부 콘텐츠
+   */
+  children: React.ReactNode;
+}
+
+/**
+ * Carousel Types; Base button props
+ * @extends CarouselButtonVisualProps
+ * @property {React.ReactNode} [children] 버튼 콘텐츠 완전 교체 슬롯
+ * @property {React.ReactNode} [label] 기본 아이콘 조합에서 사용할 레이블
+ * @property {string} [className] 버튼 className
+ * @property {boolean} [disabled] 비활성 상태
+ * @property {CarouselDirection} direction 버튼 방향
+ * @property {() => void} onMove 버튼 클릭 이동 핸들러
+ */
+export interface CarouselBaseButtonProps extends CarouselButtonVisualProps {
+  /**
+   * 버튼 방향
+   */
+  direction: CarouselDirection;
+  /**
+   * 버튼 클릭 이동 핸들러
+   */
+  onMove: () => void;
+}
+
+/**
+ * Carousel Types; Prev button props
+ * @extends CarouselButtonVisualProps
+ * @property {React.ReactNode} [children] 버튼 콘텐츠 완전 교체 슬롯
+ * @property {React.ReactNode} [label] 기본 아이콘 조합에서 사용할 레이블
+ * @property {string} [className] 버튼 className
+ * @property {boolean} [disabled] 비활성 상태
+ * @property {() => void} [onPrev] 이전 이동 핸들러
+ * @property {number} [moveCount=1] 버튼 클릭 시 이동 viewport page 개수
+ */
+export interface CarouselPrevButtonProps extends CarouselButtonVisualProps {
+  /**
+   * 이전 이동 핸들러
+   */
+  onPrev?: () => void;
+  /**
+   * 버튼 클릭 시 이동 viewport page 개수
+   */
+  moveCount?: number;
+}
+
+/**
+ * Carousel Types; Next button props
+ * @extends CarouselButtonVisualProps
+ * @property {React.ReactNode} [children] 버튼 콘텐츠 완전 교체 슬롯
+ * @property {React.ReactNode} [label] 기본 아이콘 조합에서 사용할 레이블
+ * @property {string} [className] 버튼 className
+ * @property {boolean} [disabled] 비활성 상태
+ * @property {() => void} [onNext] 다음 이동 핸들러
+ * @property {number} [moveCount=1] 버튼 클릭 시 이동 viewport page 개수
+ */
+export interface CarouselNextButtonProps extends CarouselButtonVisualProps {
+  /**
+   * 다음 이동 핸들러
+   */
+  onNext?: () => void;
+  /**
+   * 버튼 클릭 시 이동 viewport page 개수
+   */
+  moveCount?: number;
+}

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

@@ -0,0 +1 @@
+export { normalizePositiveInteger, resolveIndexFromScrollLeft } from "./math";

package/src/components/carousel/utils/math.ts

@@ -0,0 +1,62 @@
+/**
+ * Carousel Utils; 양수 정수 정규화 유틸
+ * @param {number | undefined} value 입력값
+ * @param {number} fallback 유효하지 않을 때 사용할 기본값
+ * @returns {number} 1 이상의 정수
+ * @example
+ * normalizePositiveInteger(undefined, 1); // 1
+ * normalizePositiveInteger(2.9, 1); // 2
+ */
+export const normalizePositiveInteger = (
+  value: number | undefined,
+  fallback: number,
+): number => {
+  if (typeof value !== "number" || Number.isNaN(value)) {
+    return fallback;
+  }
+
+  return Math.max(1, Math.floor(value));
+};
+
+/**
+ * Carousel Utils; scrollLeft 기준 현재 index 계산 유틸
+ * @param {object} params 계산 파라미터
+ * @param {HTMLCollection} params.panels track children 목록
+ * @param {number} params.scrollLeft viewport scrollLeft
+ * @param {number} params.maxIndex 최대 index
+ * @returns {number} 계산된 현재 index
+ * @example
+ * const index = resolveIndexFromScrollLeft({
+ *   panels: track.children,
+ *   scrollLeft: viewport.scrollLeft,
+ *   maxIndex: 5,
+ * });
+ */
+export const resolveIndexFromScrollLeft = ({
+  panels,
+  scrollLeft,
+  maxIndex,
+}: {
+  panels: HTMLCollection;
+  scrollLeft: number;
+  maxIndex: number;
+}): number => {
+  if (!panels.length) {
+    return 0;
+  }
+
+  let resolvedIndex = 0;
+  const threshold = 1;
+
+  // viewport 좌측 edge를 기준으로 마지막으로 지나온 panel index를 선택한다.
+  for (let index = 0; index < panels.length; index += 1) {
+    const panel = panels[index] as HTMLElement;
+    if (panel.offsetLeft <= scrollLeft + threshold) {
+      resolvedIndex = index;
+      continue;
+    }
+    break;
+  }
+
+  return Math.min(resolvedIndex, maxIndex);
+};

package/src/index.scss

@@ -2,6 +2,7 @@
 @use "./components/badge";
 @use "./components/button";
 @use "./components/calendar";
+@use "./components/carousel";
 @use "./components/checkbox";
 @use "./components/chip";
 @use "./components/divider";

package/src/index.tsx

@@ -7,6 +7,7 @@ export * from "./components/alternate";
 export * from "./components/badge";
 export * from "./components/button";
 export * from "./components/calendar";
+export * from "./components/carousel";
 export * from "./components/checkbox";
 export * from "./components/chip";
 export * from "./components/divider";