@lumx/react 3.20.1-alpha.20 → 3.20.1-alpha.21

package/src/components/slideshow/Slideshow.tsx

@@ -0,0 +1,173 @@
+import React from 'react';
+
+import { SlideshowControls, SlideshowControlsProps, Theme, Slides, SlidesProps } from '@lumx/react';
+import { DEFAULT_OPTIONS } from '@lumx/react/hooks/useSlideshowControls';
+import { GenericProps } from '@lumx/react/utils/type';
+import { useFocusWithin } from '@lumx/react/hooks/useFocusWithin';
+import { mergeRefs } from '@lumx/react/utils/react/mergeRefs';
+import { useTheme } from '@lumx/react/utils/theme/ThemeContext';
+import { forwardRef } from '@lumx/react/utils/react/forwardRef';
+
+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;
+    /** Children */
+    children?: React.ReactNode;
+}
+
+/**
+ * Component default props.
+ */
+const DEFAULT_PROPS: Partial<SlideshowProps> = DEFAULT_OPTIONS;
+
+/**
+ * Slideshow component.
+ *
+ * @param  props Component props.
+ * @param  ref   Component ref.
+ * @return React element.
+ */
+export const Slideshow = forwardRef<SlideshowProps, HTMLDivElement>((props, ref) => {
+    const defaultTheme = useTheme() || Theme.light;
+    const {
+        activeIndex,
+        autoPlay = DEFAULT_PROPS.autoPlay,
+        children,
+        className,
+        fillHeight,
+        groupBy = DEFAULT_OPTIONS.groupBy,
+        interval = DEFAULT_PROPS.interval,
+        onChange,
+        slideshowControlsProps,
+        theme = defaultTheme,
+        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/src/components/slideshow/SlideshowControls.stories.tsx

@@ -0,0 +1,100 @@
+import { AspectRatio, ImageBlock, Slides, SlideshowControls, SlideshowItem } from '@lumx/react';
+import { useFocusWithin } from '@lumx/react/hooks/useFocusWithin';
+import { LANDSCAPE_IMAGES } from '@lumx/react/stories/controls/image';
+
+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 = ({ images = Object.values(LANDSCAPE_IMAGES) }: any) => {
+    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}
+            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}
+                        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: string, index: number) => (
+                <SlideshowItem key={`${image}-${index}`}>
+                    <ImageBlock
+                        thumbnailProps={{ aspectRatio: AspectRatio.horizontal, loading: 'eager' }}
+                        image={image}
+                        alt=""
+                    />
+                </SlideshowItem>
+            ))}
+        </Slides>
+    );
+};

package/src/components/slideshow/SlideshowControls.tsx

@@ -0,0 +1,243 @@
+import React, { RefObject, useCallback, useMemo } from 'react';
+
+import classNames from 'classnames';
+import range from 'lodash/range';
+
+import { mdiChevronLeft, mdiChevronRight, mdiPlayCircleOutline, mdiPauseCircleOutline } from '@lumx/icons';
+import { Emphasis, IconButton, IconButtonProps, Theme } from '@lumx/react';
+import { GenericProps, HasTheme } from '@lumx/react/utils/type';
+import { getRootClassName, handleBasicClasses } from '@lumx/core/js/utils/className';
+import { WINDOW } from '@lumx/react/constants';
+import { useSlideshowControls, DEFAULT_OPTIONS } from '@lumx/react/hooks/useSlideshowControls';
+import { useRovingTabIndex } from '@lumx/react/hooks/useRovingTabIndex';
+import { forwardRef } from '@lumx/react/utils/react/forwardRef';
+
+import { useTheme } from '@lumx/react/utils/theme/ThemeContext';
+import { useSwipeNavigate } from './useSwipeNavigate';
+import { PAGINATION_ITEM_SIZE, PAGINATION_ITEMS_MAX } from './constants';
+import { usePaginationVisibleRange } from './usePaginationVisibleRange';
+
+/**
+ * Defines the props of the component.
+ */
+export interface SlideshowControlsProps extends GenericProps, HasTheme {
+    /** Index of the current slide. */
+    activeIndex?: number;
+    /** Props to pass to the next button (minus those already set by the SlideshowControls props). */
+    nextButtonProps: Pick<IconButtonProps, 'label'> &
+        Omit<IconButtonProps, 'label' | 'onClick' | 'icon' | 'emphasis' | 'color'>;
+    /** Reference to the parent element on which we want to listen touch swipe. */
+    parentRef?: RefObject<HTMLDivElement> | HTMLDivElement | null;
+    /** Props to pass to the previous button (minus those already set by the SlideshowControls props). */
+    previousButtonProps: Pick<IconButtonProps, 'label'> &
+        Omit<IconButtonProps, 'label' | 'onClick' | 'icon' | 'emphasis' | 'color'>;
+    /** Props to pass to the pagination wrapper */
+    paginationProps?: Omit<React.HTMLAttributes<HTMLDivElement>, 'className' | 'style' | 'role'>;
+    /** Number of slides. */
+    slidesCount: number;
+    /** On next button click callback. */
+    onNextClick?(loopback?: boolean): void;
+    /** On pagination change callback. */
+    onPaginationClick?(index: number): void;
+    /** On previous button click callback. */
+    onPreviousClick?(loopback?: boolean): void;
+    /** whether the slideshow is currently playing */
+    isAutoPlaying?: boolean;
+    /**
+     * function to be executed in order to retrieve the label for the pagination item
+     * @deprecated Use paginationItemProps instead.
+     * */
+    paginationItemLabel?: (index: number) => string;
+    /**
+     * function to be executed in order to retrieve the props for a pagination item.
+     */
+    paginationItemProps?: (itemIndex: number) => React.HTMLAttributes<HTMLButtonElement> & { label?: string };
+    /** Props to pass to the lay button (minus those already set by the SlideshowControls props). */
+    playButtonProps?: Pick<IconButtonProps, 'label'> &
+        Omit<IconButtonProps, 'label' | 'onClick' | 'icon' | 'emphasis' | 'color'>;
+}
+
+/**
+ * Component display name.
+ */
+const COMPONENT_NAME = 'SlideshowControls';
+
+/**
+ * Component default class name and class prefix.
+ */
+const CLASSNAME = getRootClassName(COMPONENT_NAME);
+
+/**
+ * Component default props.
+ */
+const DEFAULT_PROPS: Partial<SlideshowControlsProps> = {
+    activeIndex: 0,
+};
+
+/**
+ * SlideshowControls component.
+ *
+ * @param  props Component props.
+ * @param  ref   Component ref.
+ * @return React element.
+ */
+const InternalSlideshowControls = forwardRef<SlideshowControlsProps, HTMLDivElement>((props, ref) => {
+    const defaultTheme = useTheme() || Theme.light;
+    const {
+        activeIndex = DEFAULT_PROPS.activeIndex,
+        className,
+        nextButtonProps,
+        onNextClick,
+        onPaginationClick,
+        onPreviousClick,
+        parentRef,
+        previousButtonProps,
+        paginationProps,
+        slidesCount,
+        theme = defaultTheme,
+        isAutoPlaying = false,
+        playButtonProps,
+        paginationItemLabel,
+        paginationItemProps,
+        ...forwardedProps
+    } = props;
+
+    let parent;
+    if (WINDOW) {
+        // Checking window object to avoid errors in SSR.
+        parent = parentRef instanceof HTMLElement ? parentRef : parentRef?.current;
+    }
+    const paginationRef = React.useRef(null);
+    // Listen to touch swipe navigate left & right.
+    useSwipeNavigate(
+        parent,
+        // Go next without loopback.
+        useCallback(() => onNextClick?.(false), [onNextClick]),
+        // Go previous without loopback.
+        useCallback(() => onPreviousClick?.(false), [onPreviousClick]),
+    );
+
+    /**
+     * Add roving tab index pattern to pagination items and activate slide on focus.
+     */
+    useRovingTabIndex({
+        parentRef: paginationRef,
+        elementSelector: 'button',
+        keepTabIndex: true,
+        onElementFocus: (element) => {
+            element.click();
+        },
+    });
+
+    // Pagination "bullet" range.
+    const visibleRange = usePaginationVisibleRange(activeIndex as number, slidesCount);
+
+    // Inline style of wrapper element.
+    const wrapperStyle = { transform: `translateX(-${PAGINATION_ITEM_SIZE * visibleRange.min}px)` };
+
+    return (
+        <div
+            ref={ref}
+            {...forwardedProps}
+            className={classNames(className, handleBasicClasses({ prefix: CLASSNAME, theme }), {
+                [`${CLASSNAME}--has-infinite-pagination`]: slidesCount > PAGINATION_ITEMS_MAX,
+            })}
+        >
+            <IconButton
+                {...previousButtonProps}
+                icon={mdiChevronLeft}
+                className={`${CLASSNAME}__navigation`}
+                color={theme === Theme.dark ? 'light' : 'dark'}
+                emphasis={Emphasis.low}
+                onClick={onPreviousClick}
+            />
+            <div ref={paginationRef} className={`${CLASSNAME}__pagination`}>
+                <div
+                    className={`${CLASSNAME}__pagination-items`}
+                    style={wrapperStyle}
+                    role="tablist"
+                    {...paginationProps}
+                >
+                    {useMemo(
+                        () =>
+                            range(slidesCount).map((index) => {
+                                const isOnEdge =
+                                    index !== 0 &&
+                                    index !== slidesCount - 1 &&
+                                    (index === visibleRange.min || index === visibleRange.max);
+                                const isActive = activeIndex === index;
+                                const isOutRange = index < visibleRange.min || index > visibleRange.max;
+                                const {
+                                    className: itemClassName = undefined,
+                                    label = undefined,
+                                    ...itemProps
+                                } = paginationItemProps ? paginationItemProps(index) : {};
+
+                                const ariaLabel =
+                                    label || paginationItemLabel?.(index) || `${index + 1} / ${slidesCount}`;
+
+                                return (
+                                    <button
+                                        className={classNames(
+                                            handleBasicClasses({
+                                                prefix: `${CLASSNAME}__pagination-item`,
+                                                isActive,
+                                                isOnEdge,
+                                                isOutRange,
+                                            }),
+                                            itemClassName,
+                                        )}
+                                        key={index}
+                                        type="button"
+                                        tabIndex={isActive ? undefined : -1}
+                                        role="tab"
+                                        aria-selected={isActive}
+                                        onClick={() => onPaginationClick?.(index)}
+                                        aria-label={ariaLabel}
+                                        {...itemProps}
+                                    />
+                                );
+                            }),
+                        [
+                            slidesCount,
+                            visibleRange.min,
+                            visibleRange.max,
+                            activeIndex,
+                            paginationItemProps,
+                            paginationItemLabel,
+                            onPaginationClick,
+                        ],
+                    )}
+                </div>
+            </div>
+
+            {playButtonProps ? (
+                <IconButton
+                    {...playButtonProps}
+                    icon={isAutoPlaying ? mdiPauseCircleOutline : mdiPlayCircleOutline}
+                    className={`${CLASSNAME}__play`}
+                    color={theme === Theme.dark ? 'light' : 'dark'}
+                    emphasis={Emphasis.low}
+                />
+            ) : null}
+
+            <IconButton
+                {...nextButtonProps}
+                icon={mdiChevronRight}
+                className={`${CLASSNAME}__navigation`}
+                color={theme === Theme.dark ? 'light' : 'dark'}
+                emphasis={Emphasis.low}
+                onClick={onNextClick}
+            />
+        </div>
+    );
+});
+
+InternalSlideshowControls.displayName = COMPONENT_NAME;
+InternalSlideshowControls.className = CLASSNAME;
+InternalSlideshowControls.defaultProps = DEFAULT_PROPS;
+
+export const SlideshowControls = Object.assign(InternalSlideshowControls, {
+    useSlideshowControls,
+    useSlideshowControlsDefaultOptions: DEFAULT_OPTIONS,
+});

package/src/components/slideshow/SlideshowItem.tsx

@@ -0,0 +1,44 @@
+import classNames from 'classnames';
+
+import { GenericProps } from '@lumx/react/utils/type';
+import { getRootClassName } from '@lumx/core/js/utils/className';
+import { forwardRef } from '@lumx/react/utils/react/forwardRef';
+
+/**
+ * Defines the props of the component.
+ */
+export interface SlideshowItemProps extends GenericProps {
+    /** interval in which slides are automatically shown */
+    interval?: number;
+    /** Children */
+    children?: React.ReactNode;
+}
+
+/**
+ * Component display name.
+ */
+const COMPONENT_NAME = 'SlideshowItem';
+
+/**
+ * Component default class name and class prefix.
+ */
+const CLASSNAME = getRootClassName(COMPONENT_NAME);
+
+/**
+ * SlideshowItem component.
+ *
+ * @param  props Component props.
+ * @param  ref   Component ref.
+ * @return React element.
+ */
+export const SlideshowItem = forwardRef<SlideshowItemProps, HTMLDivElement>((props, ref) => {
+    const { className, children, ...forwardedProps } = props;
+    return (
+        <div ref={ref} className={classNames(className, CLASSNAME)} {...forwardedProps}>
+            {children}
+        </div>
+    );
+});
+
+SlideshowItem.displayName = COMPONENT_NAME;
+SlideshowItem.className = CLASSNAME;

package/src/components/slideshow/SlideshowItemGroup.tsx

@@ -0,0 +1,60 @@
+import React from 'react';
+
+import classNames from 'classnames';
+import { mergeRefs } from '@lumx/react/utils/react/mergeRefs';
+import { GenericProps } from '@lumx/react/utils/type';
+import { getRootClassName } from '@lumx/core/js/utils/className';
+import { forwardRef } from '@lumx/react/utils/react/forwardRef';
+import { useSlideFocusManagement } from './useSlideFocusManagement';
+
+/**
+ * Defines the props of the component.
+ */
+export interface SlideshowItemGroupProps extends GenericProps {
+    role?: 'tabpanel' | 'group';
+    label?: string;
+    isDisplayed?: boolean;
+    children?: React.ReactNode;
+}
+
+/**
+ * Component display name.
+ */
+const COMPONENT_NAME = 'SlideshowItemGroup';
+
+/**
+ * Component default class name and class prefix.
+ */
+export const CLASSNAME = getRootClassName(COMPONENT_NAME);
+
+export const buildSlideShowGroupId = (slidesId: string, index: number) => `${slidesId}-slide-${index}`;
+
+/**
+ * SlideshowItemGroup component.
+ *
+ * @param  props Component props.
+ * @param  ref   Component ref.
+ * @return React element.
+ */
+export const SlideshowItemGroup = forwardRef<SlideshowItemGroupProps, HTMLDivElement>((props, ref) => {
+    const { className, children, role = 'group', label, isDisplayed, ...forwardedProps } = props;
+    const groupRef = React.useRef<HTMLDivElement>(null);
+
+    useSlideFocusManagement({ isSlideDisplayed: isDisplayed, slideRef: groupRef });
+
+    return (
+        <div
+            ref={mergeRefs(groupRef, ref)}
+            role={role}
+            className={classNames(className, CLASSNAME)}
+            aria-roledescription="slide"
+            aria-label={label}
+            {...forwardedProps}
+        >
+            {children}
+        </div>
+    );
+});
+
+SlideshowItemGroup.displayName = COMPONENT_NAME;
+SlideshowItemGroup.className = CLASSNAME;

package/src/components/slideshow/constants.ts

@@ -0,0 +1,24 @@
+/**
+ * Autoplay default interval in ms.
+ */
+export const AUTOPLAY_DEFAULT_INTERVAL = 5000;
+
+/**
+ * Full width size in percent.
+ */
+export const FULL_WIDTH_PERCENT = 100;
+
+/**
+ * Edge from the active index.
+ */
+export const EDGE_FROM_ACTIVE_INDEX = 2;
+
+/**
+ * Max number of pagination items.
+ */
+export const PAGINATION_ITEMS_MAX = 5;
+
+/**
+ * Size of a pagination item. Used to translate wrapper.
+ */
+export const PAGINATION_ITEM_SIZE = 12;

package/src/components/slideshow/index.ts

@@ -0,0 +1,4 @@
+export * from './Slideshow';
+export * from './SlideshowItem';
+export * from './SlideshowControls';
+export * from './Slides';

package/src/components/slideshow/useKeyNavigate.ts

@@ -0,0 +1,28 @@
+import { useEffect } from 'react';
+
+/**
+ * Listen keyboard to navigate left and right.
+ */
+export function useKeyNavigate(element?: HTMLElement | null, onNext?: () => void, onPrevious?: () => void): void {
+    useEffect(() => {
+        if (!element) return undefined;
+        const onKeyNavigate = (evt: KeyboardEvent) => {
+            let callback;
+            if (evt?.key === 'ArrowRight') {
+                callback = onNext;
+            } else if (evt?.key === 'ArrowLeft') {
+                callback = onPrevious;
+            }
+            if (!callback) return;
+
+            callback();
+            evt.preventDefault();
+            evt.stopPropagation();
+        };
+
+        element.addEventListener('keydown', onKeyNavigate);
+        return () => {
+            element.removeEventListener('keydown', onKeyNavigate);
+        };
+    }, [onPrevious, onNext, element]);
+}