@utilitywarehouse/hearth-react-native 0.4.2 → 0.5.0

package/src/components/Carousel/Carousel.docs.mdx

@@ -0,0 +1,389 @@
+import { Canvas, Controls, Meta, Story } from '@storybook/addon-docs/blocks';
+import { BodyText, Box, Center } from '../../';
+import {
+  BackToTopButton,
+  DocComponentWrap,
+  UsageWrap,
+  ViewFigmaButton,
+} from '../../../docs/components';
+import { Carousel, CarouselControls, CarouselItem } from './';
+import * as Stories from './Carousel.stories';
+
+<Meta title="Components / Carousel" />
+
+<ViewFigmaButton url="https://www.figma.com/design/6NKZXZhFSExXrcbBgc6zTR/Hearth-Components---Tokens?node-id=5190-621" />
+
+<BackToTopButton />
+
+# Carousel
+
+Carousels provide users with a dynamic and interactive way to browse through a series of content items, such as images, articles, or products. It allows users to view multiple items within a confined space, enabling efficient content discovery and engagement.
+
+Carousel Controls are used to clearly indicate multiple pieces of content and to allow a user to navigate between them.
+
+- [Playground](#playground)
+- [Usage](#usage)
+  - [Basic Usage](#basic-usage)
+  - [Carousel with Built-in Controls](#carousel-with-built-in-controls)
+  - [Carousel with Navigation Buttons](#carousel-with-navigation-buttons)
+  - [Carousel with Custom Controls](#carousel-with-custom-controls)
+  - [Controlling Carousel via Ref](#controlling-carousel-via-ref)
+  - [Centered Fixed-Width Items](#centered-fixed-width-items)
+- [Props](#props)
+- [Accessibility](#accessibility)
+
+## Playground
+
+<Canvas of={Stories.Playground} />
+
+<Controls of={Stories.Playground} />
+
+## Usage
+
+- The `Carousel` component is to be used for presenting scrollable data
+- The `Carousel` scrolls horizontally only and works on both web and native platforms
+- Most `Carousel` behaviour is predefined for a standardised behaviour and experience across apps
+- Pagination controls are built-in by default and can be customised or hidden
+- The carousel prevents scrolling more than one item at a time for a consistent user experience
+- Some props can be modified to offer customised behaviour
+
+## Basic Usage
+
+<UsageWrap>
+  <Center flex={1}>
+    <Carousel width={300}>
+      <CarouselItem>
+        <Box p="100" aspectRatio={1.6} backgroundColor="purple800">
+          <BodyText color="white">I'm a Carousel item!</BodyText>
+        </Box>
+      </CarouselItem>
+      <CarouselItem>
+        <Box p="100" aspectRatio={1.6} backgroundColor="red800">
+          <BodyText color="white">I'm another Carousel item!</BodyText>
+        </Box>
+      </CarouselItem>
+    </Carousel>
+  </Center>
+</UsageWrap>
+
+```jsx
+import { BodyText, Box, Carousel, CarouselItem } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => (
+  <Carousel width={300}>
+    <CarouselItem>
+      <Box p="100" aspectRatio={1.6} backgroundColor="purple800">
+        <BodyText color="white">I'm a Carousel item!</BodyText>
+      </Box>
+    </CarouselItem>
+    <CarouselItem>
+      <Box p="100" aspectRatio={1.6} backgroundColor="red800">
+        <BodyText color="white">I'm another Carousel item!</BodyText>
+      </Box>
+    </CarouselItem>
+  </Carousel>
+);
+```
+
+### Carousel with Built-in Controls
+
+The `Carousel` component includes built-in pagination controls by default. You can customise their appearance or hide them entirely using props.
+
+<UsageWrap>
+  <Center flex={1}>
+    <Carousel width={300}>
+      <CarouselItem>
+        <Box p="100" aspectRatio={1.6} backgroundColor="purple800">
+          <BodyText color="white">I'm a Carousel item!</BodyText>
+        </Box>
+      </CarouselItem>
+      <CarouselItem>
+        <Box p="100" aspectRatio={1.6} backgroundColor="red800">
+          <BodyText color="white">I'm another Carousel item!</BodyText>
+        </Box>
+      </CarouselItem>
+    </Carousel>
+  </Center>
+</UsageWrap>
+
+```jsx
+import { BodyText, Box, Carousel, CarouselItem } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => (
+  <Carousel width={300}>
+    <CarouselItem>
+      <Box p="100" aspectRatio={1.6} backgroundColor="purple800">
+        <BodyText color="white">I'm a Carousel item!</BodyText>
+      </Box>
+    </CarouselItem>
+    <CarouselItem>
+      <Box p="100" aspectRatio={1.6} backgroundColor="red800">
+        <BodyText color="white">I'm another Carousel item!</BodyText>
+      </Box>
+    </CarouselItem>
+  </Carousel>
+);
+```
+
+### Carousel with Navigation Buttons
+
+Add previous and next navigation buttons to the controls by setting `showNavigation` to `true`.
+
+<UsageWrap>
+  <Center flex={1}>
+    <Carousel width={300} showNavigation>
+      <CarouselItem>
+        <Box p="100" aspectRatio={1.6} backgroundColor="purple800">
+          <BodyText color="white">I'm a Carousel item!</BodyText>
+        </Box>
+      </CarouselItem>
+      <CarouselItem>
+        <Box p="100" aspectRatio={1.6} backgroundColor="red800">
+          <BodyText color="white">I'm another Carousel item!</BodyText>
+        </Box>
+      </CarouselItem>
+    </Carousel>
+  </Center>
+</UsageWrap>
+
+```jsx
+import { BodyText, Box, Carousel, CarouselItem } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => (
+  <Carousel width={300} showNavigation>
+    <CarouselItem>
+      <Box p="100" aspectRatio={1.6} backgroundColor="purple800">
+        <BodyText color="white">I'm a Carousel item!</BodyText>
+      </Box>
+    </CarouselItem>
+    <CarouselItem>
+      <Box p="100" aspectRatio={1.6} backgroundColor="red800">
+        <BodyText color="white">I'm another Carousel item!</BodyText>
+      </Box>
+    </CarouselItem>
+  </Carousel>
+);
+```
+
+### Carousel with Custom Controls
+
+The `CarouselControls` component is to be used in conjunction with the `Carousel` component. This component requires no props and automatically utilises the carousel context. When custom controls are provided, the built-in controls are automatically hidden.
+
+<UsageWrap>
+  <Center flex={1}>
+    <Carousel width={300}>
+      <CarouselItem>
+        <Box p="100" aspectRatio={1.6} backgroundColor="purple800">
+          <BodyText color="white">I'm a Carousel item!</BodyText>
+        </Box>
+      </CarouselItem>
+      <CarouselItem>
+        <Box p="100" aspectRatio={1.6} backgroundColor="red800">
+          <BodyText color="white">I'm another Carousel item!</BodyText>
+        </Box>
+      </CarouselItem>
+      <CarouselControls style={{ marginTop: 16 }} />
+    </Carousel>
+  </Center>
+</UsageWrap>
+
+```jsx
+import { BodyText, Box, Carousel, CarouselControls } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => (
+  <Carousel width={300}>
+    <CarouselItem>
+      <Box p="100" aspectRatio={1.6} backgroundColor="purple800">
+        <BodyText color="white">I'm a Carousel item!</BodyText>
+      </Box>
+    </CarouselItem>
+    <CarouselItem>
+      <Box p="100" aspectRatio={1.6} backgroundColor="red800">
+        <BodyText color="white">I'm another Carousel item!</BodyText>
+      </Box>
+    </CarouselItem>
+    <CarouselControls style={{ marginTop: 16 }} />
+  </Carousel>
+);
+```
+
+### Controlling Carousel via Ref
+
+You can control the carousel programmatically using a ref. The carousel exposes `scrollToIndex` and `scrollToOffset` methods.
+
+```jsx
+import { useRef } from 'react';
+import {
+  BodyText,
+  Box,
+  Carousel,
+  CarouselItem,
+  Button,
+} from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => {
+  const carouselRef = useRef(null);
+
+  const goToSlide = index => {
+    carouselRef.current?.scrollToIndex({ index, animated: true });
+  };
+
+  return (
+    <>
+      <Carousel ref={carouselRef} width={300}>
+        <CarouselItem>
+          <Box p="100" aspectRatio={1.6} backgroundColor="purple800">
+            <BodyText color="white">Slide 1</BodyText>
+          </Box>
+        </CarouselItem>
+        <CarouselItem>
+          <Box p="100" aspectRatio={1.6} backgroundColor="red800">
+            <BodyText color="white">Slide 2</BodyText>
+          </Box>
+        </CarouselItem>
+      </Carousel>
+      <Button onPress={() => goToSlide(1)}>Go to Slide 2</Button>
+    </>
+  );
+};
+```
+
+### Centered Fixed-Width Items
+
+You can create a carousel with centered items that are smaller than the viewport width, showing partial views of adjacent items.
+
+```jsx
+import { BodyText, Box, Carousel, CarouselItem } from '@utilitywarehouse/hearth-react-native';
+
+const MyComponent = () => {
+  const carouselWidth = 400;
+  const itemWidth = carouselWidth * 0.8;
+
+  return (
+    <Carousel width={carouselWidth} itemWidth={itemWidth} centered showOverflow>
+      <CarouselItem>
+        <Box p="100" aspectRatio={1.6} backgroundColor="purple800">
+          <BodyText color="white">I'm a Carousel item!</BodyText>
+        </Box>
+      </CarouselItem>
+      <CarouselItem>
+        <Box p="100" aspectRatio={1.6} backgroundColor="red800">
+          <BodyText color="white">I'm another Carousel item!</BodyText>
+        </Box>
+      </CarouselItem>
+    </Carousel>
+  );
+};
+```
+
+## Props
+
+### `Carousel`
+
+This wraps a carousel in dynamic context context, automatically providing all functionality for `CarouselItem`, and `CarouselControls`.
+
+The `Carousel` component automatically updates the carousel context when interacted with.
+
+The `Carousel` component accepts most props from the React Native `FlatList` component, while other props are predfined and cannot be modified. There are also some additional carousel specific props:
+
+| Name                         | Type            | Default | Description                                                                                                                    |
+| ---------------------------- | --------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| children?                    | ReactElement[]  | -       | Accepts React elements to render as carousel items. To function correctly, these should be `CarouselItem` components.          |
+| width                        | number          | -       | Carousel viewport width (required)                                                                                             |
+| disabled?                    | boolean         | false   | Enable or disable the carousel                                                                                                 |
+| inverted?                    | boolean         | false   | Invert the carousel control colours (for brand backgrounds)                                                                    |
+| centered?                    | boolean         | false   | Center items within the carousel viewport (use with `itemWidth` for peek effect)                                               |
+| itemWidth?                   | number          | -       | Specify the width of carousel items if different from `width`. Useful for revealing the previous/next item within the viewport |
+| inactiveItemOpacity?         | number          | 1       | Fade items outside of the active carousel viewport (use in conjunction with `showOverflow`)                                    |
+| showOverflow?                | boolean         | false   | Visually reveal the items outside of the carousel viewport                                                                     |
+| showControls?                | boolean         | true    | Show or hide the built-in pagination controls                                                                                  |
+| showNavigation?              | boolean         | false   | Show previous/next navigation buttons in the controls                                                                          |
+| controlsStyle?               | ViewStyle       | -       | Style the pagination controls container                                                                                        |
+| controlsItemStyle?           | ViewStyle       | -       | Style the pagination dots                                                                                                      |
+| controlsActiveItemStyle?     | ViewStyle       | -       | Style the active pagination dot                                                                                                |
+| controlsAccessibilityHidden? | boolean         | true    | Hide controls from screen readers by default                                                                                   |
+| onSnapToItem?                | (index) => void | -       | Callback each time a new item is focused in the carousel viewport                                                              |
+| ref?                         | CarouselRef     | -       | Ref to control carousel programmatically (exposes `scrollToIndex` and `scrollToOffset`)                                        |
+
+For more information about any of the above props from the `FlatList` component, see the React Native FlatList [documentation](https://reactnative.dev/docs/flatlist).
+
+### `CarouselItem`
+
+The `CarouselItem` component automatically receives props from the parent `CarouselItems` component. Please ensure that you always wrap each of your carousel items in `CarouselItem`.
+
+| Name      | Type          | Default | Description                                                                                                                       |
+| --------- | ------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| children? | ReactElement  | -       | Display any content within each carousel item.                                                                                    |
+| key?      | number/string | -       | Provides a unique render key for each carousel item. If no `key` is provided then it will fall back to the `id`, then array index |
+
+### `CarouselControls`
+
+The `CarouselControls` component automatically receives props from the parent `Carousel` component. Please ensure that you always wrap the `CarouselControls` component within the `Carousel` component.
+
+The controls are interactive - clicking on any pagination dot will navigate to that carousel item.
+
+| Name                 | Type       | Default | Description                                                                         |
+| -------------------- | ---------- | ------- | ----------------------------------------------------------------------------------- |
+| style?               | ViewStyle  | -       | Style the pagination component                                                      |
+| itemStyle?           | ViewStyle  | -       | Style the pagination item                                                           |
+| activeItemStyle?     | ViewStyle  | -       | Style the active pagination item                                                    |
+| showNavigation?      | boolean    | false   | Show previous/next navigation buttons                                               |
+| accessibilityHidden? | boolean    | true    | Hide controls from screen readers (inherits from Carousel context if not specified) |
+| onPressPrev?         | () => void | -       | Callback when previous button is pressed                                            |
+| onPressNext?         | () => void | -       | Callback when next button is pressed                                                |
+
+## Accessibility
+
+By default, carousel controls are hidden from screen readers (`controlsAccessibilityHidden={true}`). This is because the carousel items themselves should be accessible, and the controls are primarily for visual navigation.
+
+### Screen Reader Navigation
+
+When using a screen reader, users will navigate through the carousel items in order automatically. The screen reader will focus on the content of each `CarouselItem` sequentially, allowing users to swipe through items naturally.
+
+**Important:** You must add appropriate accessibility labels and hints to the content within each carousel item. The carousel itself does not automatically provide accessibility labels for item content.
+
+```jsx
+<Carousel width={300}>
+  <CarouselItem>
+    <Box p="100" aspectRatio={1.6} backgroundColor="purple800">
+      <BodyText
+        color="white"
+        accessibilityLabel="Special offer: 20% off your next bill"
+        accessibilityHint="Double tap to view offer details"
+      >
+        20% Off!
+      </BodyText>
+    </Box>
+  </CarouselItem>
+  <CarouselItem>
+    <Box p="100" aspectRatio={1.6} backgroundColor="red800">
+      <BodyText
+        color="white"
+        accessibilityLabel="Refer a friend and earn rewards"
+        accessibilityHint="Double tap to learn more about referrals"
+      >
+        Refer & Earn
+      </BodyText>
+    </Box>
+  </CarouselItem>
+</Carousel>
+```
+
+### Making Controls Accessible
+
+To make controls accessible to screen readers:
+
+```jsx
+// Make controls visible to screen readers globally
+<Carousel width={300} controlsAccessibilityHidden={false}>
+  {/* items */}
+</Carousel>
+
+// Or override for custom controls
+<Carousel width={300}>
+  {/* items */}
+  <CarouselControls accessibilityHidden={false} />
+</Carousel>
+```
+
+The navigation buttons (when `showNavigation` is enabled) include proper accessibility labels for screen readers.

package/src/components/Carousel/Carousel.props.ts

@@ -0,0 +1,89 @@
+import { ReactElement } from 'react';
+import { FlatListProps, PressableProps, ViewProps, ViewStyle } from 'react-native';
+
+export interface CarouselRef {
+  scrollToIndex: (params: { index: number; animated?: boolean | null }) => void;
+  scrollToOffset: (params: { offset: number; animated?: boolean | null }) => void;
+}
+
+export interface CarouselContextValue {
+  activeIndex: number;
+  numItems: number;
+  setActiveIndex: (index: number) => void;
+  setNumItems: (count: number) => void;
+  controlsAccessibilityHidden?: boolean;
+  inverted?: boolean;
+  disabled?: boolean;
+}
+
+export interface CarouselItemProps extends ViewProps {
+  active?: boolean;
+  key?: string | number;
+  inactiveOpacity?: number;
+  width?: number;
+}
+
+export interface CarouselProps
+  extends Omit<
+    FlatListProps<ReactElement<CarouselItemProps>>,
+    | 'accessibilityActions'
+    | 'accessibilityLabel'
+    | 'accessibilityRole'
+    | 'accessible'
+    | 'bounces'
+    | 'children'
+    | 'data'
+    | 'decelerationRate'
+    | 'getItemLayout'
+    | 'horizontal'
+    | 'pagingEnabled'
+    | 'onAccessibilityAction'
+    | 'onViewableItemsChanged'
+    | 'overScrollMode'
+    | 'renderItem'
+    | 'showsHorizontalScrollIndicator'
+    | 'snapToInterval'
+    | 'snapToAlignment'
+    | 'viewabilityConfig'
+    | 'style'
+  > {
+  activeIndex?: number;
+  centered?: boolean;
+  disabled?: boolean;
+  inactiveItemOpacity?: number;
+  itemWidth?: number;
+  onSnapToItem?: (index: number) => void;
+  showOverflow?: boolean;
+  width: number;
+  children?: ViewProps['children'];
+  itemsStyle?: FlatListProps<ReactElement<CarouselItemProps>>['style'];
+  style?: ViewStyle;
+  showControls?: boolean;
+  showNavigation?: boolean;
+  controlsStyle?: ViewProps['style'];
+  controlsItemStyle?: ViewProps['style'];
+  controlsActiveItemStyle?: ViewProps['style'];
+  controlsAccessibilityHidden?: boolean;
+  ref?: React.Ref<CarouselRef>;
+  inverted?: boolean;
+}
+
+export interface CarouselProviderProps {
+  initialActiveIndex?: number;
+}
+
+export interface CarouselControlsProps extends ViewProps {
+  itemStyle?: ViewProps['style'];
+  activeItemStyle?: ViewProps['style'];
+  showNavigation?: boolean;
+  onPressPrev?: () => void;
+  onPressNext?: () => void;
+  accessibilityHidden?: boolean;
+}
+
+export interface CarouselControlsItemProps extends Omit<PressableProps, 'style'> {
+  active: boolean;
+  index: number;
+  style?: ViewProps['style'];
+  activeStyle?: ViewProps['style'];
+}