@watcha-authentic/react-slider 0.0.1 → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 @edge-effect#dark1451
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,154 @@
+# @watcha-authentic/react-slider
+
+[![npm version](https://img.shields.io/npm/v/@watcha-authentic/react-slider)](https://www.npmjs.com/package/@watcha-authentic/react-slider)
+
+리액트기반 슬라이더 컴포넌트입니다. 드래그/스와이프, 키보드 네비게이션을 지원하며 무한 루프 슬라이더를 제공합니다.
+
+## 피어 종속성
+
+이 패키지는 다음 패키지들을 피어 종속성으로 요구합니다.
+
+```bash
+pnpm add react@>=18.0.0 react-dom@>=18.0.0
+```
+
+## 설치
+
+```bash
+pnpm add @watcha-authentic/react-slider react@>=18.0.0 react-dom@>=18.0.0
+```
+
+## 사용 예
+
+### 기본 사용
+
+```tsx
+import { Slider } from "@watcha-authentic/react-slider";
+import "@watcha-authentic/react-slider/style.css";
+
+const items = [
+  { id: 1, title: "Item 1" },
+  { id: 2, title: "Item 2" },
+  { id: 3, title: "Item 3" },
+];
+
+function App() {
+  return (
+    <Slider
+      items={items}
+      onItemKey={(item) => item.id}
+      onCreateItemView={(item) => <div>{item.title}</div>}
+      onIndexChange={(newIndex, cause) =>
+        console.log("Index changed:", newIndex, cause)
+      }
+    />
+  );
+}
+```
+
+### Ref를 사용한 네비게이션
+
+`ref`를 통해 `doNext()`와 `doPrev()` 메서드를 사용하여 슬라이더를 제어할 수 있습니다.
+
+```tsx
+import { Slider, type SliderRef } from "@watcha-authentic/react-slider";
+import { useRef } from "react";
+
+function App() {
+  const sliderRef = useRef<SliderRef>(null);
+
+  const handlePrev = () => {
+    sliderRef.current?.doPrev();
+  };
+
+  const handleNext = () => {
+    sliderRef.current?.doNext();
+  };
+
+  return (
+    <>
+      <button onClick={handlePrev}>Previous</button>
+      <button onClick={handleNext}>Next</button>
+      <Slider
+        ref={sliderRef}
+        items={items}
+        onItemKey={(item) => item.id}
+        onCreateItemView={(item) => <div>{item.title}</div>}
+        defaultIndex={0}
+      />
+    </>
+  );
+}
+```
+
+### 스타일 import
+
+CSS 스타일을 import하여 사용할 수 있습니다:
+
+```tsx
+import "@watcha-authentic/react-slider/style.css";
+```
+
+### Context 사용
+
+아이템 내부에서 슬라이더 컨텍스트를 사용하여 포커스 상태나 전환 애니메이션을 처리할 수 있습니다.
+
+```tsx
+import { Slider, useSliderContext } from "@watcha-authentic/react-slider";
+
+function CustomItem({ item }: { item: { id: number; title: string } }) {
+  useSliderContext({
+    onFocus: (isAutoSlide) => {
+      console.log("Item focused", isAutoSlide);
+    },
+    onBlur: () => {
+      console.log("Item blurred");
+    },
+    onTransitionChange: (t, immediate) => {
+      // t: 0 ~ 1 사이의 값 (0: fade in, 1: fade out)
+      // immediate: true면 실시간 값 변경, false면 애니메이션 트리거 가능
+    },
+  });
+
+  return <div>{item.title}</div>;
+}
+
+function App() {
+  return (
+    <Slider
+      items={items}
+      onItemKey={(item) => item.id}
+      onCreateItemView={(item) => <CustomItem item={item} />}
+    />
+  );
+}
+```
+
+## 주요 Props
+
+### `defaultIndex?: number`
+
+- 초기 인덱스를 설정합니다.
+- 기본값은 `0`입니다.
+- **참고**: `index` prop은 제거되었습니다. 슬라이더 제어는 `ref`의 `doNext()`와 `doPrev()` 메서드를 사용하거나 `onIndexChange` 콜백을 통해 처리하세요.
+
+### `ref: React.Ref<SliderRef>`
+
+- `SliderRef` 타입의 ref를 전달하면 다음 메서드에 접근할 수 있습니다:
+  - `doNext()`: 다음 슬라이드로 이동
+  - `doPrev()`: 이전 슬라이드로 이동
+- 또한 `HTMLUListElement`의 모든 속성과 메서드도 사용할 수 있습니다.
+
+### `onIndexChange?: (newIndex: number, cause: SlideTriggerEvent) => void`
+
+- 인덱스가 변경될 때 호출되는 콜백입니다.
+- `cause`: 슬라이드 원인 (`'swipe'`: 키보드 네비게이션, `'drag'`: 드래그/스와이프, `'pending'`: 초기 상태)
+
+### 기타 Props
+
+- `items`: 슬라이더에 표시할 아이템 배열
+- `onCreateItemView`: 각 아이템을 렌더링하는 함수
+- `onItemKey`: 각 아이템의 고유 키를 반환하는 함수
+- `animationDuration`: 애니메이션 지속 시간 (기본값: 500ms)
+- `enableDrag`: 드래그 기능 활성화 여부 (기본값: true)
+- `visibleCount`: 중앙 기준 좌우로 보여줄 요소 개수 (기본값: 1)

package/dist/cjs/component/context/slider-context-provider.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "SliderItemContextProvider", {
+    enumerable: true,
+    get: function() {
+        return SliderItemContextProvider;
+    }
+});
+const _jsxruntime = require("react/jsx-runtime");
+const _slidercontext = require("./slider-context");
+const SliderItemContextProvider = ({ children, immediate, isFocused, itemIndex, slideTriggerEvent, transition })=>{
+    const value = {
+        immediate,
+        isFocused,
+        itemIndex,
+        slideTriggerEvent,
+        transition
+    };
+    return /*#__PURE__*/ (0, _jsxruntime.jsx)(_slidercontext.SliderItemContext.Provider, {
+        value: value,
+        children: children
+    });
+};

package/dist/cjs/component/context/slider-context.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "SliderItemContext", {
+    enumerable: true,
+    get: function() {
+        return SliderItemContext;
+    }
+});
+const _react = /*#__PURE__*/ _interop_require_default(require("react"));
+function _interop_require_default(obj) {
+    return obj && obj.__esModule ? obj : {
+        default: obj
+    };
+}
+const SliderItemContext = /*#__PURE__*/ _react.default.createContext(null);

package/dist/cjs/component/hook/use-slider-context.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "useSliderContext", {
+    enumerable: true,
+    get: function() {
+        return useSliderContext;
+    }
+});
+const _reacteventcallback = require("@watcha-authentic/react-event-callback");
+const _react = /*#__PURE__*/ _interop_require_wildcard(require("react"));
+const _slidercontext = require("../context/slider-context");
+function _getRequireWildcardCache(nodeInterop) {
+    if (typeof WeakMap !== "function") return null;
+    var cacheBabelInterop = new WeakMap();
+    var cacheNodeInterop = new WeakMap();
+    return (_getRequireWildcardCache = function(nodeInterop) {
+        return nodeInterop ? cacheNodeInterop : cacheBabelInterop;
+    })(nodeInterop);
+}
+function _interop_require_wildcard(obj, nodeInterop) {
+    if (!nodeInterop && obj && obj.__esModule) {
+        return obj;
+    }
+    if (obj === null || typeof obj !== "object" && typeof obj !== "function") {
+        return {
+            default: obj
+        };
+    }
+    var cache = _getRequireWildcardCache(nodeInterop);
+    if (cache && cache.has(obj)) {
+        return cache.get(obj);
+    }
+    var newObj = {
+        __proto__: null
+    };
+    var hasPropertyDescriptor = Object.defineProperty && Object.getOwnPropertyDescriptor;
+    for(var key in obj){
+        if (key !== "default" && Object.prototype.hasOwnProperty.call(obj, key)) {
+            var desc = hasPropertyDescriptor ? Object.getOwnPropertyDescriptor(obj, key) : null;
+            if (desc && (desc.get || desc.set)) {
+                Object.defineProperty(newObj, key, desc);
+            } else {
+                newObj[key] = obj[key];
+            }
+        }
+    }
+    newObj.default = obj;
+    if (cache) {
+        cache.set(obj, newObj);
+    }
+    return newObj;
+}
+const useSliderContext = (callbacks)=>{
+    const context = _react.default.useContext(_slidercontext.SliderItemContext);
+    if (!context) {
+        throw new Error("useSliderContext must be used within SliderItemContextProvider");
+    }
+    const stableOnBlur = (0, _reacteventcallback.useEventCallback)(callbacks.onBlur);
+    const stableOnFocus = (0, _reacteventcallback.useEventCallback)(callbacks.onFocus);
+    const stableOnInitialState = (0, _reacteventcallback.useEventCallback)(callbacks.onInitialState);
+    const stableOnTransitionChange = (0, _reacteventcallback.useEventCallback)(callbacks.onTransitionChange);
+    const prevFocusedRef = (0, _react.useRef)(null);
+    /**
+   * - 초기 마운트 또는 상태 변경시 콜백 호출
+   */ (0, _react.useLayoutEffect)(()=>{
+        const isInitialMount = prevFocusedRef.current === null;
+        if (prevFocusedRef.current !== context.isFocused) {
+            if (isInitialMount) {
+                // 초기 마운트 시 onInitialState 호출
+                stableOnInitialState(context.isFocused);
+            } else {
+                // 상태 변경 시 onBlur/onFocus 호출
+                if (context.isFocused) {
+                    stableOnFocus(context.slideTriggerEvent === "swipe");
+                } else {
+                    stableOnBlur();
+                }
+            }
+            prevFocusedRef.current = context.isFocused;
+        }
+    }, [
+        context.isFocused,
+        context.slideTriggerEvent,
+        stableOnBlur,
+        stableOnFocus,
+        stableOnInitialState
+    ]);
+    /**
+   * - transition 값 변경 시 콜백 호출
+   */ (0, _react.useLayoutEffect)(()=>{
+        stableOnTransitionChange(context.transition, context.immediate);
+    }, [
+        context.transition,
+        context.immediate,
+        stableOnTransitionChange
+    ]);
+};