@lumx/react 3.0.7 → 3.1.0

package/dist/src/components/slideshow/Slides.tsx

@@ -0,0 +1,124 @@
+import React, { Children, CSSProperties, forwardRef } from 'react';
+import chunk from 'lodash/chunk';
+
+import classNames from 'classnames';
+
+import { FULL_WIDTH_PERCENT } from '@lumx/react/components/slideshow/constants';
+import { Comp, GenericProps, HasTheme } from '@lumx/react/utils/type';
+import { getRootClassName, handleBasicClasses } from '@lumx/react/utils/className';
+import { buildSlideShowGroupId, SlideshowItemGroup } from './SlideshowItemGroup';
+
+export interface SlidesProps extends GenericProps, HasTheme {
+    /** current slide active */
+    activeIndex: number;
+    /** slides id to be added to the wrapper */
+    id?: string;
+    /** Whether the automatic rotation of the slideshow is enabled or not. */
+    autoPlay?: boolean;
+    /** Whether the image has to fill its container height or not. */
+    fillHeight?: boolean;
+    /** Number of slides to group together. */
+    groupBy?: number;
+    /** whether the slides are currently playing or not */
+    isAutoPlaying?: boolean;
+    /** id to be passed in into the slides */
+    slidesId?: string;
+    /** callback to change whether the slideshow is playing or not */
+    toggleAutoPlay: () => void;
+    /** component to be rendered after the slides */
+    afterSlides?: React.ReactNode;
+    /** Whether the slides have controls linked */
+    hasControls?: boolean;
+    /**
+     * Accessible label to set on a slide group.
+     * Receives the group position starting from 1 and the total number of groups.
+     * */
+    slideGroupLabel?: (groupPosition: number, groupTotal: number) => string;
+}
+
+/**
+ * Component display name.
+ */
+const COMPONENT_NAME = 'Slideshow';
+
+/**
+ * Component default class name and class prefix.
+ */
+const CLASSNAME = getRootClassName(COMPONENT_NAME);
+
+/**
+ * Slides component.
+ *
+ * @param  props Component props.
+ * @param  ref   Component ref.
+ * @return React element.
+ */
+export const Slides: Comp<SlidesProps, HTMLDivElement> = forwardRef((props, ref) => {
+    const {
+        activeIndex,
+        id,
+        className,
+        theme,
+        fillHeight,
+        groupBy,
+        isAutoPlaying,
+        toggleAutoPlay,
+        slidesId,
+        children,
+        afterSlides,
+        hasControls,
+        slideGroupLabel,
+        ...forwardedProps
+    } = props;
+    const wrapperRef = React.useRef<HTMLDivElement>(null);
+    const startIndexVisible = activeIndex;
+    const endIndexVisible = startIndexVisible + 1;
+
+    // Inline style of wrapper element.
+    const wrapperStyle: CSSProperties = { transform: `translateX(-${FULL_WIDTH_PERCENT * activeIndex}%)` };
+
+    const groups = React.useMemo(() => {
+        const childrenArray = Children.toArray(children);
+        return groupBy && groupBy > 1 ? chunk(childrenArray, groupBy) : childrenArray;
+    }, [children, groupBy]);
+
+    return (
+        <section
+            id={id}
+            ref={ref}
+            {...forwardedProps}
+            className={classNames(className, handleBasicClasses({ prefix: CLASSNAME, theme }), {
+                [`${CLASSNAME}--fill-height`]: fillHeight,
+                [`${CLASSNAME}--group-by-${groupBy}`]: Boolean(groupBy),
+            })}
+            aria-roledescription="carousel"
+        >
+            <div
+                id={slidesId}
+                className={`${CLASSNAME}__slides`}
+                onMouseEnter={toggleAutoPlay}
+                onMouseLeave={toggleAutoPlay}
+                aria-live={isAutoPlaying ? 'off' : 'polite'}
+            >
+                <div ref={wrapperRef} className={`${CLASSNAME}__wrapper`} style={wrapperStyle}>
+                    {groups.map((group, index) => (
+                        <SlideshowItemGroup
+                            key={index}
+                            id={slidesId && buildSlideShowGroupId(slidesId, index)}
+                            role={hasControls ? 'tabpanel' : 'group'}
+                            label={slideGroupLabel ? slideGroupLabel(index + 1, groups.length) : undefined}
+                            isDisplayed={index >= startIndexVisible && index < endIndexVisible}
+                        >
+                            {group}
+                        </SlideshowItemGroup>
+                    ))}
+                </div>
+            </div>
+
+            {afterSlides}
+        </section>
+    );
+});
+
+Slides.displayName = COMPONENT_NAME;
+Slides.className = CLASSNAME;

package/dist/src/components/slideshow/Slideshow.stories.tsx

@@ -0,0 +1,212 @@
+import React from 'react';
+import range from 'lodash/range';
+import { AspectRatio, Button, FlexBox, ImageBlock, Slideshow, SlideshowItem, Orientation } from '@lumx/react';
+import { boolean, number } from '@storybook/addon-knobs';
+import { thumbnailsKnob } from '@lumx/react/stories/knobs/thumbnailsKnob';
+
+export default { title: 'LumX components/slideshow/Slideshow' };
+
+export const Simple = ({ theme }: any) => {
+    const images = thumbnailsKnob(6);
+    const activeIndex = number('Active index', 0);
+    const groupBy = number('Group by', 1);
+    const autoPlay = boolean('Autoplay', false);
+    const interval = number('Autoplay interval (in milliseconds)', 1000);
+
+    return (
+        <Slideshow
+            aria-label="Simple carousel example"
+            activeIndex={activeIndex}
+            autoPlay={autoPlay}
+            interval={interval}
+            slideshowControlsProps={{
+                nextButtonProps: { label: 'Next' },
+                previousButtonProps: { label: 'Previous' },
+            }}
+            theme={theme}
+            groupBy={groupBy}
+            style={{ width: '50%' }}
+            slideGroupLabel={(currentGroup, totalGroup) => `${currentGroup} of ${totalGroup}`}
+        >
+            {images.map(({ image, alt }, index) => (
+                <SlideshowItem key={`${image}-${index}`}>
+                    <ImageBlock
+                        thumbnailProps={{ aspectRatio: AspectRatio.horizontal, loading: 'eager' }}
+                        image={image}
+                        alt={alt}
+                        theme={theme}
+                    />
+                </SlideshowItem>
+            ))}
+        </Slideshow>
+    );
+};
+
+export const SimpleWithAutoPlay = ({ theme }: any) => {
+    const images = thumbnailsKnob(6);
+    const activeIndex = number('Active index', 0);
+    const groupBy = number('Group by', 1);
+    const interval = number('Autoplay interval (in milliseconds)', 1000);
+
+    return (
+        <Slideshow
+            aria-label="Simple with autoplay example"
+            activeIndex={activeIndex}
+            autoPlay
+            interval={interval}
+            slideshowControlsProps={{
+                nextButtonProps: { label: 'Next' },
+                previousButtonProps: { label: 'Previous' },
+                playButtonProps: { label: 'Play/Pause' },
+            }}
+            theme={theme}
+            groupBy={groupBy}
+            style={{ width: '50%' }}
+            slideGroupLabel={(currentGroup, totalGroup) => `${currentGroup} of ${totalGroup}`}
+        >
+            {images.map(({ image, alt }, index) => (
+                <SlideshowItem key={`${image}-${index}`}>
+                    <ImageBlock
+                        thumbnailProps={{ aspectRatio: AspectRatio.horizontal, loading: 'eager' }}
+                        image={image}
+                        alt={alt}
+                        theme={theme}
+                    />
+                </SlideshowItem>
+            ))}
+        </Slideshow>
+    );
+};
+
+export const ResponsiveSlideShowSwipe = () => {
+    const slides = range(5);
+    return (
+        <>
+            In responsive mode
+            <ul>
+                <li>The slideshow is swipe-able (horizontal left/right)</li>
+                <li>The vertical scroll should still be possible</li>
+                <li>Clicking on elements inside a slide should work correctly</li>
+            </ul>
+            <FlexBox vAlign="center">
+                <Slideshow
+                    aria-label="Responsive SlideShow Swipe"
+                    activeIndex={0}
+                    slideshowControlsProps={{
+                        nextButtonProps: { label: 'Next' },
+                        previousButtonProps: { label: 'Previous' },
+                    }}
+                    slideGroupLabel={(currentGroup, totalGroup) => `${currentGroup} of ${totalGroup}`}
+                >
+                    {slides.map((slide) => (
+                        <SlideshowItem key={`${slide}`}>
+                            <FlexBox
+                                style={{ border: '1px solid grey', maxWidth: 300, height: 300 }}
+                                hAlign="center"
+                                vAlign="center"
+                            >
+                                <Button onClick={() => alert(`Clicked button ${slide}`)}>Button {slide}</Button>
+                            </FlexBox>
+                        </SlideshowItem>
+                    ))}
+                </Slideshow>
+            </FlexBox>
+            {
+                /* Line padding to test the vertical scroll.*/
+                range(100).map((i) => (
+                    <br key={i} />
+                ))
+            }
+        </>
+    );
+};
+
+const slides = [
+    {
+        id: 0,
+        src: 'https://www.w3.org/WAI/ARIA/apg/example-index/carousel/images/foyleswarslide__800x600.jpg',
+        alt: 'A man in a suit and fedora and a woman with coiffed hair look sternly into the camera.',
+        title: 'Foyle’s War Revisited',
+        subtitle: '8 pm Sunday, March 8, on TV: Sneak peek at the final season',
+        link: '#',
+    },
+    {
+        id: 1,
+        src: 'https://www.w3.org/WAI/ARIA/apg/example-index/carousel/images/britcomdavidslide__800x600.jpg',
+        alt: 'British flag with WILL-TV host David Thiel.',
+        title: 'Great Britain Vote: 7 pm Sat.',
+        link: '#',
+    },
+    {
+        id: 2,
+        src: 'https://www.w3.org/WAI/ARIA/apg/example-index/carousel/images/mag800-2__800x600.jpg',
+        alt: 'Mid-American Gardener panelists on the set.',
+        title: 'Mid-American Gardener: Thursdays at 7 pm',
+        subtitle: 'Watch the latest episode',
+        link: '#',
+    },
+    {
+        id: 3,
+        src: 'https://www.w3.org/WAI/ARIA/apg/example-index/carousel/images/foyleswarslide__800x600.jpg',
+        alt: 'A man in a suit and fedora and a woman with coiffed hair look sternly into the camera.',
+        title: 'Foyle’s War Revisited',
+        subtitle: '8 pm Sunday, March 8, on TV: Sneak peek at the final season',
+        link: '#',
+    },
+    {
+        id: 4,
+        src: 'https://www.w3.org/WAI/ARIA/apg/example-index/carousel/images/britcomdavidslide__800x600.jpg',
+        alt: 'British flag with WILL-TV host David Thiel.',
+        title: 'Great Britain Vote: 7 pm Sat.',
+        link: '#',
+    },
+    {
+        id: 5,
+        src: 'https://www.w3.org/WAI/ARIA/apg/example-index/carousel/images/mag800-2__800x600.jpg',
+        alt: 'Mid-American Gardener panelists on the set.',
+        title: 'Mid-American Gardener: Thursdays at 7 pm',
+        subtitle: 'Watch the latest episode',
+        link: '#',
+    },
+];
+export const WithComplexContent = () => (
+    <Slideshow
+        aria-label="Carousel with complex content"
+        activeIndex={0}
+        groupBy={2}
+        slideshowControlsProps={{
+            nextButtonProps: { label: 'Next' },
+            previousButtonProps: { label: 'Previous' },
+            playButtonProps: { label: 'Play/Pause' },
+            paginationItemProps: (index) => ({ label: `Slide ${index + 1}` }),
+        }}
+        slideGroupLabel={(currentGroup, totalGroup) => `${currentGroup} of ${totalGroup}`}
+    >
+        {range(number('Slides', 6)).map((nb) => {
+            const slide = slides[nb % slides.length];
+
+            return (
+                <SlideshowItem key={slide.id}>
+                    <a href={slide.link}>
+                        <ImageBlock
+                            thumbnailProps={{ aspectRatio: AspectRatio.horizontal, loading: 'eager' }}
+                            image={slide.src}
+                            alt={slide.alt}
+                        />
+                    </a>
+                    <FlexBox orientation={Orientation.vertical}>
+                        <h3>
+                            <a href={slide.link}>{slide.title}</a>
+                            {/* Add a non focusable element to test that it stays that way after a page change. */}
+                            <button type="button" tabIndex={-1} aria-hidden="true">
+                                Not focusable
+                            </button>
+                            <button type="button">Focusable</button>
+                        </h3>
+                        {slide.subtitle && <p>{slide.subtitle}</p>}
+                    </FlexBox>
+                </SlideshowItem>
+            );
+        })}
+    </Slideshow>
+);

package/dist/src/components/slideshow/Slideshow.test.tsx

@@ -0,0 +1,39 @@
+import React, { ReactElement } from 'react';
+import pick from 'lodash/pick';
+
+import { mount, shallow } from 'enzyme';
+import 'jest-enzyme';
+
+import { commonTestsSuite, itShouldRenderStories, Wrapper } from '@lumx/react/testing/utils';
+import { Slideshow, SlideshowProps } from './Slideshow';
+import { SlideshowControls } from './SlideshowControls';
+import * as stories from './Slideshow.stories';
+
+const CLASSNAME = Slideshow.className as string;
+
+const setup = ({ ...propsOverride }: Partial<SlideshowProps> = {}, shallowRendering = true) => {
+    const props: SlideshowProps = {
+        slideshowControlsProps: {
+            nextButtonProps: { label: 'Next' },
+            previousButtonProps: { label: 'Prev' },
+        },
+        ...propsOverride,
+    };
+
+    const renderer: (el: ReactElement) => Wrapper = shallowRendering ? shallow : mount;
+    const wrapper: Wrapper = renderer(<Slideshow {...props} />);
+
+    return { props, wrapper };
+};
+
+describe(`<${Slideshow.displayName}>`, () => {
+    // 1. Test render via snapshot.
+    describe('Snapshots and structure', () => {
+        itShouldRenderStories(pick(stories, ['default', 'Simple']), {
+            or: [Slideshow, { path: [Slideshow, SlideshowControls] }],
+        });
+    });
+
+    // Common tests suite.
+    commonTestsSuite(setup, { prop: 'wrapper' }, { className: CLASSNAME });
+});

package/dist/src/components/slideshow/Slideshow.tsx

@@ -0,0 +1,170 @@
+import React, { forwardRef } from 'react';
+
+import { SlideshowControls, SlideshowControlsProps, Theme, Slides, SlidesProps } from '@lumx/react';
+import { DEFAULT_OPTIONS } from '@lumx/react/hooks/useSlideshowControls';
+import { Comp, GenericProps } from '@lumx/react/utils/type';
+import { useFocusWithin } from '@lumx/react/hooks/useFocusWithin';
+import { mergeRefs } from '@lumx/react/utils/mergeRefs';
+import { buildSlideShowGroupId } from './SlideshowItemGroup';
+
+/**
+ * Defines the props of the component.
+ */
+export interface SlideshowProps
+    extends GenericProps,
+        Pick<SlidesProps, 'autoPlay' | 'slidesId' | 'id' | 'theme' | 'fillHeight' | 'groupBy' | 'slideGroupLabel'> {
+    /** current slide active */
+    activeIndex?: SlidesProps['activeIndex'];
+    /** Interval between each slide when automatic rotation is enabled. */
+    interval?: number;
+    /** Props to pass to the slideshow controls (minus those already set by the Slideshow props). */
+    slideshowControlsProps?: Pick<
+        SlideshowControlsProps,
+        'nextButtonProps' | 'previousButtonProps' | 'paginationItemProps'
+    > &
+        Omit<
+            SlideshowControlsProps,
+            | 'activeIndex'
+            | 'onPaginationClick'
+            | 'onNextClick'
+            | 'onPreviousClick'
+            | 'slidesCount'
+            | 'parentRef'
+            | 'theme'
+        >;
+    /** Callback when slide changes */
+    onChange?(index: number): void;
+}
+
+/**
+ * Component default props.
+ */
+const DEFAULT_PROPS: Partial<SlideshowProps> = {
+    ...DEFAULT_OPTIONS,
+    theme: Theme.light,
+};
+
+/**
+ * Slideshow component.
+ *
+ * @param  props Component props.
+ * @param  ref   Component ref.
+ * @return React element.
+ */
+export const Slideshow: Comp<SlideshowProps, HTMLDivElement> = forwardRef((props, ref) => {
+    const {
+        activeIndex,
+        autoPlay,
+        children,
+        className,
+        fillHeight,
+        groupBy,
+        interval,
+        onChange,
+        slideshowControlsProps,
+        theme,
+        id,
+        slidesId,
+        slideGroupLabel,
+        ...forwardedProps
+    } = props;
+    // Number of slideshow items.
+    const itemsCount = React.Children.count(children);
+
+    const {
+        activeIndex: currentIndex,
+        slideshowId,
+        setSlideshow,
+        isAutoPlaying,
+        slideshowSlidesId,
+        slidesCount,
+        onNextClick,
+        onPaginationClick,
+        onPreviousClick,
+        slideshow,
+        stopAutoPlay,
+        startAutoPlay,
+        toggleAutoPlay,
+        toggleForcePause,
+    } = SlideshowControls.useSlideshowControls({
+        activeIndex,
+        defaultActiveIndex: DEFAULT_PROPS.activeIndex as number,
+        autoPlay: Boolean(autoPlay),
+        itemsCount,
+        groupBy,
+        id,
+        interval,
+        onChange,
+        slidesId,
+    });
+
+    useFocusWithin({
+        element: slideshow,
+        onFocusIn: stopAutoPlay,
+        onFocusOut: startAutoPlay,
+    });
+
+    const showControls = slideshowControlsProps && slidesCount > 1;
+
+    return (
+        <Slides
+            activeIndex={currentIndex}
+            id={slideshowId}
+            className={className}
+            theme={theme}
+            fillHeight={fillHeight}
+            groupBy={groupBy}
+            isAutoPlaying={isAutoPlaying}
+            autoPlay={autoPlay}
+            slidesId={slideshowSlidesId}
+            toggleAutoPlay={toggleAutoPlay}
+            ref={mergeRefs(ref, setSlideshow)}
+            hasControls={showControls}
+            slideGroupLabel={slideGroupLabel}
+            afterSlides={
+                slideshowControlsProps && slidesCount > 1 ? (
+                    <div className={`${Slides.className}__controls`}>
+                        <SlideshowControls
+                            {...slideshowControlsProps}
+                            activeIndex={currentIndex}
+                            onPaginationClick={onPaginationClick}
+                            onNextClick={onNextClick}
+                            onPreviousClick={onPreviousClick}
+                            slidesCount={slidesCount}
+                            parentRef={slideshow}
+                            theme={theme}
+                            isAutoPlaying={isAutoPlaying}
+                            nextButtonProps={{
+                                'aria-controls': slideshowSlidesId,
+                                ...slideshowControlsProps.nextButtonProps,
+                            }}
+                            previousButtonProps={{
+                                'aria-controls': slideshowSlidesId,
+                                ...slideshowControlsProps.previousButtonProps,
+                            }}
+                            playButtonProps={
+                                autoPlay
+                                    ? {
+                                          'aria-controls': slideshowSlidesId,
+                                          onClick: toggleForcePause,
+                                          ...slideshowControlsProps.playButtonProps,
+                                      }
+                                    : undefined
+                            }
+                            paginationItemProps={(index) => ({
+                                'aria-controls': buildSlideShowGroupId(slideshowSlidesId, index),
+                                ...slideshowControlsProps.paginationItemProps?.(index),
+                            })}
+                        />
+                    </div>
+                ) : undefined
+            }
+            {...forwardedProps}
+        >
+            {children}
+        </Slides>
+    );
+});
+
+Slideshow.displayName = 'Slideshow';
+Slideshow.defaultProps = DEFAULT_PROPS;

package/dist/src/components/slideshow/SlideshowControls.stories.tsx

@@ -0,0 +1,112 @@
+import React from 'react';
+
+import { AspectRatio, ImageBlock, Slides, SlideshowControls, SlideshowItem } from '@lumx/react';
+import { thumbnailsKnob } from '@lumx/react/stories/knobs/thumbnailsKnob';
+import { useFocusWithin } from '@lumx/react/hooks/useFocusWithin';
+
+export default { title: 'LumX components/slideshow/Slideshow controls' };
+
+export const Simple = () => {
+    const {
+        activeIndex,
+        slidesCount,
+        onNextClick,
+        onPreviousClick,
+        onPaginationClick,
+    } = SlideshowControls.useSlideshowControls({
+        itemsCount: 9,
+    });
+
+    return (
+        <SlideshowControls
+            activeIndex={activeIndex}
+            slidesCount={slidesCount}
+            onNextClick={onNextClick}
+            onPreviousClick={onPreviousClick}
+            onPaginationClick={onPaginationClick}
+            nextButtonProps={{ label: 'Next' }}
+            previousButtonProps={{ label: 'Previous' }}
+            paginationItemLabel={(index) => `Slide ${index}`}
+        />
+    );
+};
+
+export const ControllingSlideshow = ({ theme }: any) => {
+    const images = thumbnailsKnob(6);
+
+    const {
+        activeIndex: currentIndex,
+        slideshowId,
+        setSlideshow,
+        isAutoPlaying,
+        slideshowSlidesId,
+        slidesCount,
+        onNextClick,
+        onPaginationClick,
+        onPreviousClick,
+        slideshow,
+        stopAutoPlay,
+        startAutoPlay,
+        toggleAutoPlay,
+        toggleForcePause,
+    } = SlideshowControls.useSlideshowControls({
+        activeIndex: 0,
+        defaultActiveIndex: 0,
+        autoPlay: true,
+        itemsCount: 6,
+        groupBy: 1,
+    });
+
+    useFocusWithin({
+        element: slideshow,
+        onFocusIn: stopAutoPlay,
+        onFocusOut: startAutoPlay,
+    });
+
+    return (
+        <Slides
+            activeIndex={currentIndex}
+            id={slideshowId}
+            ref={setSlideshow}
+            theme={theme}
+            isAutoPlaying={isAutoPlaying}
+            slidesId={slideshowSlidesId}
+            toggleAutoPlay={toggleAutoPlay}
+            groupBy={1}
+            style={{ width: '50%' }}
+            afterSlides={
+                <div className={`${Slides.className}__controls`}>
+                    <SlideshowControls
+                        activeIndex={currentIndex}
+                        onPaginationClick={onPaginationClick}
+                        onNextClick={onNextClick}
+                        onPreviousClick={onPreviousClick}
+                        slidesCount={slidesCount}
+                        parentRef={slideshow}
+                        theme={theme}
+                        isAutoPlaying={isAutoPlaying}
+                        nextButtonProps={{ label: 'Next', 'aria-controls': slideshowSlidesId }}
+                        previousButtonProps={{ label: 'Previous', 'aria-controls': slideshowSlidesId }}
+                        playButtonProps={{
+                            label: 'Play/Pause',
+                            'aria-controls': slideshowSlidesId,
+                            onClick: toggleForcePause,
+                        }}
+                        paginationItemLabel={(index) => `Slide ${index}`}
+                    />
+                </div>
+            }
+        >
+            {images.map(({ image, alt }, index) => (
+                <SlideshowItem key={`${image}-${index}`}>
+                    <ImageBlock
+                        thumbnailProps={{ aspectRatio: AspectRatio.horizontal, loading: 'eager' }}
+                        image={image}
+                        alt={alt}
+                        theme={theme}
+                    />
+                </SlideshowItem>
+            ))}
+        </Slides>
+    );
+};