@lumx/react 3.0.7 → 3.1.0

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

@@ -0,0 +1,241 @@
+import React, { forwardRef, 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 { Comp, GenericProps, HasTheme } from '@lumx/react/utils/type';
+import { getRootClassName, handleBasicClasses } from '@lumx/react/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 { 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,
+    theme: Theme.light,
+};
+
+/**
+ * SlideshowControls component.
+ *
+ * @param  props Component props.
+ * @param  ref   Component ref.
+ * @return React element.
+ */
+const InternalSlideshowControls: Comp<SlideshowControlsProps, HTMLDivElement> = forwardRef((props, ref) => {
+    const {
+        activeIndex,
+        className,
+        nextButtonProps,
+        onNextClick,
+        onPaginationClick,
+        onPreviousClick,
+        parentRef,
+        previousButtonProps,
+        paginationProps,
+        slidesCount,
+        theme,
+        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/dist/src/components/slideshow/SlideshowItem.tsx

@@ -0,0 +1,52 @@
+import React, { forwardRef } from 'react';
+
+import classNames from 'classnames';
+
+import { Comp, GenericProps } from '@lumx/react/utils/type';
+import { getRootClassName, handleBasicClasses } from '@lumx/react/utils/className';
+
+/**
+ * Defines the props of the component.
+ */
+export interface SlideshowItemProps extends GenericProps {
+    /** interval in which slides are automatically shown */
+    interval?: number;
+}
+
+/**
+ * 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: Comp<SlideshowItemProps, HTMLDivElement> = forwardRef((props, ref) => {
+    const { className, children, ...forwardedProps } = props;
+    return (
+        <div
+            ref={ref}
+            className={classNames(
+                className,
+                handleBasicClasses({
+                    prefix: CLASSNAME,
+                }),
+            )}
+            {...forwardedProps}
+        >
+            {children}
+        </div>
+    );
+});
+
+SlideshowItem.displayName = COMPONENT_NAME;
+SlideshowItem.className = CLASSNAME;

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

@@ -0,0 +1,64 @@
+import React, { forwardRef } from 'react';
+
+import classNames from 'classnames';
+import { mergeRefs } from '@lumx/react/utils/mergeRefs';
+
+import { Comp, GenericProps } from '@lumx/react/utils/type';
+import { getRootClassName, handleBasicClasses } from '@lumx/react/utils/className';
+import { useSlideFocusManagement } from './useSlideFocusManagement';
+
+/**
+ * Defines the props of the component.
+ */
+export interface SlideshowItemGroupProps extends GenericProps {
+    role?: 'tabpanel' | 'group';
+    label?: string;
+    isDisplayed?: boolean;
+}
+
+/**
+ * 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: Comp<SlideshowItemGroupProps, HTMLDivElement> = forwardRef((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,
+                handleBasicClasses({
+                    prefix: CLASSNAME,
+                }),
+            )}
+            aria-roledescription="slide"
+            aria-label={label}
+            {...forwardedProps}
+        >
+            {children}
+        </div>
+    );
+});
+
+SlideshowItemGroup.displayName = COMPONENT_NAME;
+SlideshowItemGroup.className = CLASSNAME;

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

@@ -0,0 +1,157 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`<Slideshow> Snapshots and structure should render story 'Simple' 1`] = `
+[
+  <Slideshow
+    activeIndex={0}
+    afterSlides={
+      <div
+        className="lumx-slideshow__controls"
+      >
+        <SlideshowControls
+          activeIndex={0}
+          isAutoPlaying={false}
+          nextButtonProps={
+            {
+              "aria-controls": "slideshow-slides2",
+              "label": "Next",
+            }
+          }
+          onNextClick={[Function]}
+          onPaginationClick={[Function]}
+          onPreviousClick={[Function]}
+          paginationItemProps={[Function]}
+          parentRef={null}
+          previousButtonProps={
+            {
+              "aria-controls": "slideshow-slides2",
+              "label": "Previous",
+            }
+          }
+          slidesCount={6}
+          theme="light"
+        />
+      </div>
+    }
+    aria-label="Simple carousel example"
+    autoPlay={false}
+    groupBy={1}
+    hasControls={true}
+    id="slideshow1"
+    isAutoPlaying={false}
+    slideGroupLabel={[Function]}
+    slidesId="slideshow-slides2"
+    style={
+      {
+        "width": "50%",
+      }
+    }
+    theme="light"
+    toggleAutoPlay={[Function]}
+  >
+    <SlideshowItem
+      key="/demo-assets/landscape1.jpg-0"
+    >
+      <ImageBlock
+        align="left"
+        alt="Image 1"
+        captionPosition="below"
+        image="/demo-assets/landscape1.jpg"
+        theme="light"
+        thumbnailProps={
+          {
+            "aspectRatio": "horizontal",
+            "loading": "eager",
+          }
+        }
+      />
+    </SlideshowItem>
+    <SlideshowItem
+      key="/demo-assets/landscape1-s200.jpg-1"
+    >
+      <ImageBlock
+        align="left"
+        alt="Image 2"
+        captionPosition="below"
+        image="/demo-assets/landscape1-s200.jpg"
+        theme="light"
+        thumbnailProps={
+          {
+            "aspectRatio": "horizontal",
+            "loading": "eager",
+          }
+        }
+      />
+    </SlideshowItem>
+    <SlideshowItem
+      key="/demo-assets/landscape2.jpg-2"
+    >
+      <ImageBlock
+        align="left"
+        alt="Image 3"
+        captionPosition="below"
+        image="/demo-assets/landscape2.jpg"
+        theme="light"
+        thumbnailProps={
+          {
+            "aspectRatio": "horizontal",
+            "loading": "eager",
+          }
+        }
+      />
+    </SlideshowItem>
+    <SlideshowItem
+      key="/demo-assets/landscape3.jpg-3"
+    >
+      <ImageBlock
+        align="left"
+        alt="Image 4"
+        captionPosition="below"
+        image="/demo-assets/landscape3.jpg"
+        theme="light"
+        thumbnailProps={
+          {
+            "aspectRatio": "horizontal",
+            "loading": "eager",
+          }
+        }
+      />
+    </SlideshowItem>
+    <SlideshowItem
+      key="/demo-assets/portrait1.jpg-4"
+    >
+      <ImageBlock
+        align="left"
+        alt="Image 5"
+        captionPosition="below"
+        image="/demo-assets/portrait1.jpg"
+        theme="light"
+        thumbnailProps={
+          {
+            "aspectRatio": "horizontal",
+            "loading": "eager",
+          }
+        }
+      />
+    </SlideshowItem>
+    <SlideshowItem
+      key="/demo-assets/portrait1-s200.jpg-5"
+    >
+      <ImageBlock
+        align="left"
+        alt="Image 6"
+        captionPosition="below"
+        image="/demo-assets/portrait1-s200.jpg"
+        theme="light"
+        thumbnailProps={
+          {
+            "aspectRatio": "horizontal",
+            "loading": "eager",
+          }
+        }
+      />
+    </SlideshowItem>
+  </Slideshow>,
+  null,
+]
+`;

package/dist/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/dist/src/components/slideshow/index.ts

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

package/dist/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]);
+}

package/dist/src/components/slideshow/usePaginationVisibleRange.ts

@@ -0,0 +1,37 @@
+import { useMemo, useRef } from 'react';
+import { EDGE_FROM_ACTIVE_INDEX, PAGINATION_ITEMS_MAX } from '@lumx/react/components/slideshow/constants';
+
+type Range = { min: number; max: number };
+
+/**
+ * Calculate the currently visible pagination "bullet" range.
+ */
+export function usePaginationVisibleRange(activeIndex: number, slideCount: number): Range {
+    const previousVisibleRangeRef = useRef<Range>();
+    return useMemo(() => {
+        const lastSlide = slideCount - 1;
+        const { current: previousVisibleRange } = previousVisibleRangeRef;
+        let newVisibleRange: Range;
+        if (activeIndex === previousVisibleRange?.max && activeIndex < lastSlide) {
+            newVisibleRange = { min: previousVisibleRange.min + 1, max: previousVisibleRange.max + 1 };
+        } else if (activeIndex === previousVisibleRange?.min && activeIndex > 0) {
+            newVisibleRange = { min: previousVisibleRange.min - 1, max: previousVisibleRange.max - 1 };
+        } else {
+            const deltaItems = PAGINATION_ITEMS_MAX - 1;
+            let min = activeIndex - EDGE_FROM_ACTIVE_INDEX;
+            let max = activeIndex + EDGE_FROM_ACTIVE_INDEX;
+
+            if (activeIndex > lastSlide - EDGE_FROM_ACTIVE_INDEX) {
+                min = lastSlide - deltaItems;
+                max = lastSlide;
+            } else if (activeIndex < deltaItems) {
+                min = 0;
+                max = deltaItems;
+            }
+
+            newVisibleRange = { min, max };
+        }
+        previousVisibleRangeRef.current = newVisibleRange;
+        return newVisibleRange;
+    }, [activeIndex, slideCount]);
+}