@momo-kits/carousel 0.151.1-beta.4 → 0.151.1-test.5

package/PROPS.md

@@ -0,0 +1,188 @@
+# Carousel Component Props
+
+## Overview
+The Carousel component is a customizable, performant carousel/slider component built on top of React Native's `FlatList`. It supports features like looping, autoplay, animations, and custom layouts.
+
+## Props
+
+### Data & Rendering
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `data` | `any[]` | - | ✅ | Array of data items to be rendered in the carousel |
+| `renderItem` | `(info: { item: any; index: number }) => React.ReactNode` | - | ✅ | Function that renders each carousel item |
+| `keyExtractor` | `(item: any, index: number) => string` | Auto-generated | ❌ | Function to extract unique keys for list items |
+| `firstItem` | `number` | `0` | ❌ | Index of the initial active item |
+
+### Layout & Sizing
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `itemWidth` | `number` | Auto-calculated | ❌ | Width of each carousel item. If not specified, calculated based on `visibleItem` |
+| `visibleItem` | `number` | `1` | ❌ | Number of items visible at once in the viewport |
+| `full` | `boolean` | `false` | ❌ | If `true`, items will take full container width with no margins |
+| `activeSlideOffset` | `number` | `20` | ❌ | Offset from center to determine when a slide is considered "active" |
+
+### Scrolling & Snapping
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `scrollEnabled` | `boolean` | `true` | ❌ | Enable or disable scrolling |
+| `enableSnap` | `boolean` | `true` | ❌ | Enable snapping to items after scroll |
+| `snapToInterval` | `number \| Animated.Value \| Animated.AnimatedInterpolation` | Auto-calculated | ❌ | Custom snap interval. If not provided, calculated from item dimensions |
+| `disableIntervalMomentum` | `boolean` | `true` (Android) / `false` (iOS) | ❌ | Disable momentum scrolling. Default varies by platform |
+
+### Loop Mode
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `loop` | `boolean` | `false` | ❌ | Enable infinite loop mode |
+| `loopClonesPerSide` | `number` | `3` | ❌ | Number of cloned items on each side when loop is enabled |
+
+### Autoplay
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `autoplay` | `boolean` | `false` | ❌ | Enable autoplay |
+| `autoplayDelay` | `number` | `1000` | ❌ | Delay in milliseconds before autoplay starts |
+| `autoplayInterval` | `number` | `3000` | ❌ | Interval in milliseconds between automatic slides |
+
+### Animations
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `inactiveSlideOpacity` | `number` | `1` | ❌ | Opacity value for inactive slides (0-1). Values < 1 enable opacity animation |
+| `inactiveSlideScale` | `number` | `1` | ❌ | Scale value for inactive slides (0-1). Values < 1 enable scale animation |
+| `apparitionDelay` | `number` | `0` | ❌ | Delay in milliseconds before carousel appears |
+
+### Styling
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `style` | `ViewStyle` | `{}` | ❌ | Style for the carousel container |
+| `slideStyle` | `StyleProp<ViewStyle>` | `{}` | ❌ | Style applied to each individual slide |
+| `contentContainerStyle` | `StyleProp<ViewStyle>` | `undefined` | ❌ | Style for the inner content container |
+
+### Callbacks
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `onSnapToItem` | `(index: number) => void` | - | ❌ | Callback fired when a slide snaps to position. Receives the data index (not the loop index) |
+| `onScrollIndexChanged` | `(index: number) => void` | ❌ | ❌ | Callback fired when the active index changes during scroll |
+| `onScroll` | `any` | - | ❌ | Scroll event handler (can be Animated.event) |
+| `onMomentumScrollEnd` | `(event: NativeSyntheticEvent<NativeScrollEvent>) => void` | - | ❌ | Callback fired when momentum scroll ends |
+| `onTouchStart` | `(event: any) => void` | - | ❌ | Callback fired when user touches the carousel |
+| `onTouchEnd` | `(event: GestureResponderEvent) => void` | - | ❌ | Callback fired when user releases touch |
+| `onLayout` | `(event: LayoutChangeEvent) => void` | - | ❌ | Callback fired when layout changes |
+
+### Advanced
+
+| Prop | Type | Default | Required | Description |
+|------|------|---------|----------|-------------|
+| `getItemLayout` | `(data: any, index: number) => { length: number; offset: number; index: number }` | Auto-calculated | ❌ | Custom item layout calculation for performance optimization |
+
+## Ref Methods
+
+When using a ref, the following methods are available:
+
+| Method | Parameters | Description |
+|--------|------------|-------------|
+| `snapToItem` | `index: number, animated?: boolean, fireCallback?: boolean` | Snap to a specific item by index |
+| `snapToNext` | `animated?: boolean, fireCallback?: boolean` | Snap to the next item |
+| `snapToPrev` | `animated?: boolean, fireCallback?: boolean` | Snap to the previous item |
+| `startAutoplay` | - | Start autoplay programmatically |
+| `pauseAutoPlay` | - | Pause autoplay (can be resumed) |
+| `stopAutoplay` | - | Stop autoplay completely |
+
+## Usage Example
+
+```tsx
+import { Carousel, CarouselRef } from '@momo-kits/carousel';
+import { useRef } from 'react';
+
+function MyCarousel() {
+  const carouselRef = useRef<CarouselRef>(null);
+  
+  const data = [1, 2, 3, 4, 5];
+  
+  return (
+    <Carousel
+      ref={carouselRef}
+      data={data}
+      renderItem={({ item, index }) => (
+        <View>
+          <Text>Item {item}</Text>
+        </View>
+      )}
+      // Layout
+      visibleItem={1}
+      full={false}
+      
+      // Scrolling
+      enableSnap={true}
+      loop={true}
+      
+      // Autoplay
+      autoplay={true}
+      autoplayDelay={1000}
+      autoplayInterval={3000}
+      
+      // Animations
+      inactiveSlideOpacity={0.7}
+      inactiveSlideScale={0.9}
+      
+      // Callbacks
+      onSnapToItem={(index) => console.log('Snapped to:', index)}
+    />
+  );
+}
+```
+
+## Common Patterns
+
+### Full-width Carousel with Loop
+```tsx
+<Carousel
+  data={items}
+  renderItem={renderItem}
+  full={true}
+  loop={true}
+  enableSnap={true}
+/>
+```
+
+### Multi-item Carousel
+```tsx
+<Carousel
+  data={items}
+  renderItem={renderItem}
+  visibleItem={3}
+  enableSnap={false}
+/>
+```
+
+### Autoplay with Animations
+```tsx
+<Carousel
+  data={items}
+  renderItem={renderItem}
+  autoplay={true}
+  autoplayInterval={3000}
+  loop={true}
+  inactiveSlideOpacity={0.5}
+  inactiveSlideScale={0.85}
+/>
+```
+
+## Notes
+
+- **Loop Mode**: When `loop={true}`, the carousel creates clones of items to enable seamless infinite scrolling. The number of clones is controlled by `loopClonesPerSide`.
+- **Index Handling**: Callback functions like `onSnapToItem` receive the data index (0 to data.length-1), not the internal loop index.
+- **Performance**: The component uses `PureComponent` and optimized rendering. Set `itemWidth` and `visibleItem` appropriately for best performance.
+- **Platform Differences**: Some default values differ between iOS and Android (e.g., `disableIntervalMomentum`) to provide optimal experience on each platform.
+- **Autoplay Behavior**: Autoplay automatically pauses when user touches the carousel and resumes when touch ends (if it was active before).
+- **Item Width Calculation**: 
+  - If `full={true}`: items take full container width
+  - If `itemWidth` is provided: uses that value
+  - Otherwise: calculated based on `visibleItem` count with appropriate spacing
+