@utilitywarehouse/hearth-react-native 0.4.2 → 0.5.0

package/src/components/Carousel/Carousel.tsx

@@ -0,0 +1,444 @@
+import {
+  Children,
+  cloneElement,
+  ReactElement,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+import {
+  FlatList,
+  NativeScrollEvent,
+  NativeSyntheticEvent,
+  Platform,
+  ScrollView,
+  View,
+  ViewStyle,
+  ViewToken,
+} from 'react-native';
+import { StyleSheet } from 'react-native-unistyles';
+
+import CarouselContext from './Carousel.context';
+import { CarouselItemProps, CarouselProps } from './Carousel.props';
+import { CarouselControls } from './CarouselControls';
+import { CarouselItem } from './CarouselItem';
+
+const Carousel = ({
+  centered = false,
+  children,
+  disabled = false,
+  inactiveItemOpacity = 1,
+  itemWidth,
+  onSnapToItem,
+  showOverflow = false,
+  style,
+  width,
+  itemsStyle,
+  activeIndex: initialActiveIndex = 0,
+  showControls = true,
+  showNavigation = false,
+  controlsStyle,
+  controlsItemStyle,
+  controlsActiveItemStyle,
+  controlsAccessibilityHidden = true,
+  inverted = false,
+  ref,
+  ...props
+}: CarouselProps) => {
+  const [activeIndex, setActiveIndex] = useState(initialActiveIndex);
+  const [numItems, setNumItems] = useState(0);
+
+  const scrollViewRef = useRef<ScrollView>(null);
+  const flatListRef = useRef<FlatList>(null);
+  const isWeb = Platform.OS === 'web';
+  const isProgrammaticScroll = useRef(false);
+
+  // Expose scroll methods through ref
+  useImperativeHandle(
+    ref,
+    () => ({
+      scrollToIndex: ({ index, animated = true }: { index: number; animated?: boolean | null }) => {
+        if (isWeb && scrollViewRef.current) {
+          isProgrammaticScroll.current = true;
+          const itemWidthValue = itemWidth || width;
+          const offset = centered ? (width - (itemWidth || width)) / 2 : 0;
+          const scrollX = index * itemWidthValue - offset;
+          scrollViewRef.current.scrollTo({ x: scrollX, animated: animated ?? true });
+          setTimeout(() => {
+            isProgrammaticScroll.current = false;
+          }, 500);
+        } else if (flatListRef.current) {
+          flatListRef.current.scrollToIndex({ index, animated: animated ?? true });
+        }
+        setActiveIndex(index);
+      },
+      scrollToOffset: ({
+        offset,
+        animated = true,
+      }: {
+        offset: number;
+        animated?: boolean | null;
+      }) => {
+        if (isWeb && scrollViewRef.current) {
+          isProgrammaticScroll.current = true;
+          scrollViewRef.current.scrollTo({ x: offset, animated: animated ?? true });
+          setTimeout(() => {
+            isProgrammaticScroll.current = false;
+          }, 500);
+        } else if (flatListRef.current) {
+          flatListRef.current.scrollToOffset({ offset, animated: animated ?? true });
+        }
+      },
+    }),
+    [isWeb, itemWidth, width, centered]
+  );
+
+  // Recursively check if CarouselControls exists in the children tree
+  const hasCarouselControlsInTree = (node: React.ReactNode): boolean => {
+    if (!node) return false;
+
+    if (typeof node === 'object' && 'type' in node) {
+      if (
+        node.type === CarouselControls ||
+        (node.type as any)?.displayName === 'CarouselControls'
+      ) {
+        return true;
+      }
+
+      // Check children recursively
+      if ('props' in node && node.props && typeof node.props === 'object') {
+        const props = node.props as { children?: React.ReactNode };
+        if (props.children) {
+          const childArray = Children.toArray(props.children);
+          return childArray.some(child => hasCarouselControlsInTree(child));
+        }
+      }
+    }
+
+    return false;
+  };
+
+  // Filter only CarouselItem children for the carousel
+  const { carouselItems, otherChildren, hasCarouselControls } = useMemo(() => {
+    const childrenArray = Children.toArray(children);
+    const carouselItems: Array<ReactElement<CarouselItemProps>> = [];
+    const otherChildren: Array<React.ReactNode> = [];
+
+    childrenArray.forEach(child => {
+      if (
+        typeof child === 'object' &&
+        'type' in child &&
+        (child.type === CarouselItem || (child.type as any)?.displayName === 'CarouselItem')
+      ) {
+        carouselItems.push(child as ReactElement<CarouselItemProps>);
+      } else {
+        otherChildren.push(child);
+      }
+    });
+
+    // Recursively check if any CarouselControls exist in the tree
+    const hasCarouselControls = childrenArray.some(child => hasCarouselControlsInTree(child));
+
+    return { carouselItems, otherChildren, hasCarouselControls };
+  }, [children]);
+
+  const innerMargin: number = width - (itemWidth || width);
+  const containerStyles: ViewStyle = {
+    marginHorizontal: centered ? innerMargin / 2 : 0,
+    overflow: showOverflow ? 'visible' : 'hidden',
+  };
+
+  const context = useMemo(
+    () => ({
+      activeIndex,
+      numItems: carouselItems.length,
+      setActiveIndex,
+      setNumItems,
+      controlsAccessibilityHidden,
+      inverted,
+      disabled,
+    }),
+    [
+      activeIndex,
+      carouselItems.length,
+      setActiveIndex,
+      setNumItems,
+      controlsAccessibilityHidden,
+      inverted,
+      disabled,
+    ]
+  );
+
+  // On web, we need to prevent overflow from expanding the container
+  const webContainerStyles: ViewStyle = isWeb
+    ? {
+        width,
+        maxWidth: width,
+        overflow: 'hidden', // Always clip on web to prevent expansion
+      }
+    : {};
+
+  // For web centered layouts, add padding to content container
+  const webContentContainerStyle: ViewStyle =
+    isWeb && centered
+      ? {
+          paddingHorizontal: innerMargin / 2,
+        }
+      : {};
+
+  useEffect(() => {
+    setNumItems((carouselItems || []).length);
+  }, [carouselItems, setNumItems]);
+
+  // Set initial scroll position on web
+  useEffect(() => {
+    if (isWeb && scrollViewRef.current && initialActiveIndex > 0) {
+      // Use setTimeout to ensure ScrollView is mounted
+      setTimeout(() => {
+        if (scrollViewRef.current) {
+          const itemWidthValue = itemWidth || width;
+          const offset = centered ? innerMargin / 2 : 0;
+          const scrollX = initialActiveIndex * itemWidthValue - offset;
+          scrollViewRef.current.scrollTo({ x: scrollX, animated: false });
+        }
+      }, 0);
+    }
+  }, [isWeb, initialActiveIndex, itemWidth, width, centered, innerMargin]);
+
+  // Scroll to active index when it changes (for programmatic navigation)
+  useEffect(() => {
+    if (!isProgrammaticScroll.current) {
+      isProgrammaticScroll.current = true;
+
+      if (isWeb && scrollViewRef.current) {
+        const itemWidthValue = itemWidth || width;
+        const offset = centered ? innerMargin / 2 : 0;
+        const scrollX = activeIndex * itemWidthValue - offset;
+
+        scrollViewRef.current.scrollTo({ x: scrollX, animated: true });
+      } else if (
+        !isWeb &&
+        flatListRef.current &&
+        activeIndex >= 0 &&
+        activeIndex < carouselItems.length
+      ) {
+        flatListRef.current.scrollToIndex({ index: activeIndex, animated: true });
+      }
+
+      setTimeout(() => {
+        isProgrammaticScroll.current = false;
+      }, 500);
+    }
+  }, [activeIndex, isWeb, itemWidth, width, centered, innerMargin, carouselItems.length]);
+
+  // Web scroll handler - track scroll position
+  const handleWebScroll = useCallback(
+    (event: NativeSyntheticEvent<NativeScrollEvent>) => {
+      if (!isWeb || isProgrammaticScroll.current) return;
+
+      const scrollX = event.nativeEvent.contentOffset.x;
+      const itemWidthValue = itemWidth || width;
+
+      // For centered layouts, account for the padding offset
+      const offset = centered ? innerMargin / 2 : 0;
+      const index = Math.round((scrollX + offset) / itemWidthValue);
+
+      if (index >= 0 && index < carouselItems.length && index !== activeIndex) {
+        setActiveIndex?.(index);
+      }
+    },
+    [
+      activeIndex,
+      centered,
+      innerMargin,
+      isWeb,
+      itemWidth,
+      carouselItems.length,
+      setActiveIndex,
+      width,
+    ]
+  );
+
+  // Web scroll end handler - update when scroll completes
+  const handleWebScrollEnd = useCallback(
+    (event: NativeSyntheticEvent<NativeScrollEvent>) => {
+      if (!isWeb || isProgrammaticScroll.current) return;
+
+      const scrollX = event.nativeEvent.contentOffset.x;
+      const itemWidthValue = itemWidth || width;
+
+      // For centered layouts, account for the padding offset
+      const offset = centered ? innerMargin / 2 : 0;
+      const index = Math.round((scrollX + offset) / itemWidthValue);
+
+      if (index >= 0 && index < carouselItems.length) {
+        setActiveIndex?.(index);
+        onSnapToItem?.(index);
+      }
+    },
+    [
+      centered,
+      innerMargin,
+      isWeb,
+      itemWidth,
+      carouselItems.length,
+      onSnapToItem,
+      setActiveIndex,
+      width,
+    ]
+  );
+
+  // Native viewable items handler
+  const handleViewableItemsChanged = useCallback(
+    ({ viewableItems }: { viewableItems: Array<ViewToken> }) => {
+      if (!viewableItems.length) {
+        return;
+      }
+
+      const index = viewableItems[viewableItems.length - 1].index || 0;
+
+      setActiveIndex?.(index);
+      onSnapToItem?.(index);
+    },
+    [onSnapToItem, setActiveIndex]
+  );
+
+  const controls = (
+    <CarouselControls
+      style={[styles.controls, controlsStyle]}
+      itemStyle={controlsItemStyle}
+      activeItemStyle={controlsActiveItemStyle}
+      showNavigation={showNavigation}
+      accessibilityHidden={controlsAccessibilityHidden}
+    />
+  );
+
+  // Render for web using ScrollView with scroll snap
+  if (isWeb) {
+    return (
+      <CarouselContext.Provider value={context}>
+        <View style={style}>
+          <ScrollView
+            horizontal
+            onScroll={handleWebScroll}
+            onMomentumScrollEnd={handleWebScrollEnd}
+            onScrollEndDrag={handleWebScrollEnd}
+            ref={scrollViewRef as any}
+            scrollEnabled={!disabled}
+            pointerEvents={disabled ? 'none' : 'auto'}
+            scrollEventThrottle={16}
+            showsHorizontalScrollIndicator={false}
+            snapToInterval={itemWidth || width}
+            snapToAlignment={centered ? 'center' : 'start'}
+            decelerationRate="fast"
+            style={[styles.webContainer, webContainerStyles, itemsStyle]}
+            contentContainerStyle={[styles.webContentContainer, webContentContainerStyle]}
+            {...props}
+          >
+            {carouselItems.map((item, index) =>
+              cloneElement(item, {
+                active: index === activeIndex,
+                inactiveOpacity: inactiveItemOpacity,
+                key: item?.key || item.props?.id || index,
+                width: itemWidth || width,
+                style: [
+                  item.props?.style,
+                  styles.webItem,
+                  centered ? styles.webItemCentered : styles.webItemStart,
+                ],
+              })
+            )}
+          </ScrollView>
+          {showControls && !hasCarouselControls && controls}
+          {otherChildren}
+        </View>
+      </CarouselContext.Provider>
+    );
+  }
+
+  // Render for native using FlatList
+  return (
+    <CarouselContext.Provider value={context}>
+      <View style={style}>
+        <FlatList<ReactElement<CarouselItemProps>>
+          ref={flatListRef as any}
+          bounces={false} // Prevents bouncing at the start and end of carousel scrolling (iOS only)
+          data={carouselItems}
+          decelerationRate="fast"
+          disableIntervalMomentum // Prevents scrolling more than one item at a time
+          getItemLayout={(_, index) => ({
+            length: itemWidth || width,
+            offset: (itemWidth || width) * index,
+            index,
+          })}
+          horizontal
+          initialScrollIndex={activeIndex}
+          pagingEnabled
+          onViewableItemsChanged={handleViewableItemsChanged}
+          overScrollMode="never" // Prevents stretching of first and last items when reaching each end of the carousel (Android only)
+          removeClippedSubviews={!showOverflow}
+          renderItem={({ index, item }) =>
+            cloneElement(item, {
+              active: index === activeIndex,
+              inactiveOpacity: inactiveItemOpacity,
+              key: item?.key || item.props?.id || index,
+              width: itemWidth || width,
+            })
+          }
+          scrollEnabled={!disabled}
+          showsHorizontalScrollIndicator={false}
+          snapToInterval={itemWidth || width}
+          snapToAlignment="center"
+          style={[itemsStyle, containerStyles]}
+          viewabilityConfig={{ itemVisiblePercentThreshold: 51 }}
+          {...props}
+        />
+        {showControls && !hasCarouselControls && controls}
+        {otherChildren}
+      </View>
+    </CarouselContext.Provider>
+  );
+};
+
+Carousel.displayName = 'Carousel';
+
+const styles = StyleSheet.create(theme => ({
+  controls: {
+    marginTop: theme.space['200'],
+  },
+  webContainer: {
+    _web: {
+      scrollSnapType: 'x mandatory',
+      WebkitOverflowScrolling: 'touch',
+      overflowX: 'scroll',
+      overflowY: 'hidden',
+    },
+  },
+  webContentContainer: {
+    _web: {
+      display: 'flex',
+      flexDirection: 'row',
+    },
+  },
+  webItem: {
+    _web: {
+      scrollSnapStop: 'always',
+      flexShrink: 0,
+    },
+  },
+  webItemCentered: {
+    _web: {
+      scrollSnapAlign: 'center',
+    },
+  },
+  webItemStart: {
+    _web: {
+      scrollSnapAlign: 'start',
+    },
+  },
+}));
+
+export default Carousel;

package/src/components/Carousel/CarouselControlItem.tsx

@@ -0,0 +1,87 @@
+import { createPressable } from '@gluestack-ui/pressable';
+import { useContext } from 'react';
+import { Pressable, View } from 'react-native';
+import { StyleSheet } from 'react-native-unistyles';
+import CarouselContext from './Carousel.context';
+import { CarouselControlsItemProps } from './Carousel.props';
+
+export const CarouselControlItemRoot = ({
+  active,
+  style,
+  index,
+  activeStyle,
+  onPress,
+  disabled,
+  ...props
+}: CarouselControlsItemProps & { states?: { active?: boolean; disabled?: boolean } }) => {
+  const { inverted, numItems } = useContext(CarouselContext);
+  styles.useVariants({ active, inverted });
+  return (
+    <Pressable
+      style={[styles.item, active && activeStyle]}
+      onPress={onPress}
+      disabled={disabled}
+      accessibilityLabel={`Page ${index + 1} of ${numItems}`}
+      {...props}
+    >
+      <View style={[styles.circle, style]} />
+    </Pressable>
+  );
+};
+
+const CarouselControlItem = createPressable({
+  Root: CarouselControlItemRoot,
+});
+
+CarouselControlItem.displayName = 'CarouselControlItem';
+
+const styles = StyleSheet.create(theme => ({
+  item: {
+    width: 24,
+    height: 24,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  circle: {
+    width: theme.components.carouselControl.size,
+    height: theme.components.carouselControl.size,
+    borderRadius: theme.borderRadius.full,
+    borderColor: theme.color.interactive.functional.border.subtle,
+    borderWidth: theme.borderWidth[2],
+    backgroundColor: 'transparent',
+    paddingTop: theme.space['100'],
+    overflow: 'hidden',
+    _hover: {
+      backgroundColor: theme.color.interactive.functional.surface.subtle.hover,
+    },
+    variants: {
+      active: {
+        true: {
+          backgroundColor: theme.color.interactive.functional.foreground.subtle,
+          _hover: {
+            backgroundColor: theme.color.interactive.functional.foreground.subtle,
+          },
+        },
+      },
+      inverted: {
+        true: {
+          borderColor: theme.color.interactive.functional.border.inverted,
+          _hover: {
+            backgroundColor: theme.color.interactive.functional.surface.subtle.inverted.hover,
+          },
+        },
+      },
+    },
+    compoundVariants: [
+      {
+        active: true,
+        inverted: true,
+        styles: {
+          backgroundColor: theme.color.interactive.functional.foreground.inverted,
+        },
+      },
+    ],
+  },
+}));
+
+export default CarouselControlItem;

package/src/components/Carousel/CarouselControls.tsx

@@ -0,0 +1,150 @@
+import { nanoid } from 'nanoid/non-secure';
+import { FC, useContext, useEffect, useMemo } from 'react';
+import { StyleSheet } from 'react-native-unistyles';
+import { View } from 'react-native';
+import {
+  ChevronLeftSmallIcon,
+  ChevronRightSmallIcon,
+} from '@utilitywarehouse/hearth-react-native-icons';
+import { UnstyledIconButton } from '../UnstyledIconButton';
+import CarouselContext from './Carousel.context';
+import { CarouselControlsProps } from './Carousel.props';
+import CarouselControlItem from './CarouselControlItem';
+
+export const CarouselControls: FC<CarouselControlsProps> = ({
+  testID = 'pagination',
+  style,
+  itemStyle,
+  activeItemStyle,
+  showNavigation = false,
+  onPressPrev,
+  onPressNext,
+  accessibilityHidden,
+  ...props
+}) => {
+  const context = useContext(CarouselContext);
+  const {
+    activeIndex = 0,
+    numItems = 0,
+    setActiveIndex,
+    controlsAccessibilityHidden,
+    disabled = false,
+  } = context;
+
+  const isAccessibilityHidden = accessibilityHidden ?? controlsAccessibilityHidden ?? true;
+
+  styles.useVariants({ showNavigation });
+
+  useEffect(() => {
+    if (!Object.keys(context).length) {
+      console.warn(
+        'CarouselControls must be a child of Carousel. Pagination will not be displayed.'
+      );
+    }
+  }, [context]);
+
+  const keys = useMemo(() => {
+    return Array(numItems)
+      .fill(null)
+      .map(() => nanoid());
+  }, [numItems]);
+
+  const handlePrev = () => {
+    if (activeIndex > 0) {
+      setActiveIndex(activeIndex - 1);
+      onPressPrev?.();
+    }
+  };
+
+  const handleNext = () => {
+    if (activeIndex < numItems - 1) {
+      setActiveIndex(activeIndex + 1);
+      onPressNext?.();
+    }
+  };
+
+  const handleItemPress = (index: number) => {
+    setActiveIndex(index);
+  };
+
+  if (!Object.keys(context).length) {
+    return null;
+  }
+
+  return (
+    <View
+      style={[styles.root, style]}
+      testID={testID}
+      importantForAccessibility={isAccessibilityHidden ? 'no-hide-descendants' : 'auto'}
+      accessibilityElementsHidden={isAccessibilityHidden}
+      {...props}
+    >
+      {showNavigation && (
+        <UnstyledIconButton
+          icon={ChevronLeftSmallIcon}
+          onPress={handlePrev}
+          disabled={disabled || activeIndex === 0}
+          accessibilityLabel="Previous"
+          style={styles.button}
+          inverted={context.inverted}
+        />
+      )}
+      <View style={styles.dotsContainer}>
+        {keys.map((_, index) => (
+          <CarouselControlItem
+            active={index === activeIndex}
+            index={index}
+            key={keys[index]}
+            style={itemStyle}
+            activeStyle={activeItemStyle}
+            onPress={() => handleItemPress(index)}
+            disabled={disabled}
+          />
+        ))}
+      </View>
+      {showNavigation && (
+        <UnstyledIconButton
+          icon={ChevronRightSmallIcon}
+          onPress={handleNext}
+          disabled={disabled || activeIndex === numItems - 1}
+          accessibilityLabel="Next"
+          style={styles.button}
+          inverted={context.inverted}
+        />
+      )}
+    </View>
+  );
+};
+
+const styles = StyleSheet.create(theme => ({
+  root: {
+    width: '100%',
+    alignSelf: 'center',
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: theme.components.carouselControl.gap,
+    justifyContent: 'space-between',
+    variants: {
+      showNavigation: {
+        true: {
+          justifyContent: 'space-between',
+        },
+        false: {
+          justifyContent: 'center',
+        },
+      },
+    },
+  },
+  dotsContainer: {
+    flexDirection: 'row',
+    gap: theme.components.carouselControl.gap,
+  },
+  button: {
+    width: 24,
+    height: 24,
+  },
+}));
+
+CarouselControls.displayName = 'CarouselControls';
+
+export default CarouselControls;