@skyscanner/backpack-web 37.9.0 → 37.9.1

package/bpk-component-card-list/src/BpkCardList.js

@@ -28,6 +28,7 @@ const getClassName = cssModules(STYLES);
 const DEFAULT_ITEMS = 3;
 const BpkCardList = props => {
   const {
+    accessibilityLabels,
     accessoryDesktop,
     accessoryMobile,
     buttonContent,
@@ -74,6 +75,7 @@ const BpkCardList = props => {
             children: [layoutMobile === LAYOUTS.rail && /*#__PURE__*/_jsx(BpkCardListRowRailContainer, {
               initiallyShownCards: initiallyShownCardsMobile,
               layout: layoutMobile,
+              accessibilityLabels: accessibilityLabels,
               isMobile: true,
               children: cardList
             }), layoutMobile === LAYOUTS.stack && /*#__PURE__*/_jsx(BpkCardListGridStack, {
@@ -92,6 +94,7 @@ const BpkCardList = props => {
               accessory: accessoryDesktop,
               initiallyShownCards: initiallyShownCardsDesktop,
               layout: layoutDesktop,
+              accessibilityLabels: accessibilityLabels,
               children: cardList
             }), layoutDesktop === LAYOUTS.grid && accessoryDesktop !== ACCESSORY_DESKTOP_TYPES.pagination && /*#__PURE__*/_jsx(BpkCardListGridStack, {
               accessory: accessoryDesktop,

package/bpk-component-card-list/src/BpkCardListRowRail/BpkCardListCarousel.js

@@ -25,12 +25,14 @@ import { jsx as _jsx } from "react/jsx-runtime";
 const getClassName = cssModules(STYLES);
 const BpkCardListCarousel = props => {
   const {
+    carouselLabel = (initiallyShownCards, childrenLength) => `Entering Carousel with ${initiallyShownCards} slides shown at a time, ${childrenLength} slides in total. Please use Pagination below with the Previous and Next buttons to navigate, or the slide dot buttons at the end to jump to slides.`,
     children,
     currentIndex,
     initiallyShownCards,
     isMobile = false,
     layout,
-    setCurrentIndex
+    setCurrentIndex,
+    slideLabel = (index, childrenLength) => `slide ${index + 1} of ${childrenLength}`
   } = props;
   const shownNumberStyle = {
     '--initially-shown-cards': initiallyShownCards
@@ -63,14 +65,16 @@ const BpkCardListCarousel = props => {
   }, [root]);
   useUpdateCurrentIndexByVisibility(isMobile, visibilityList, setCurrentIndex, stateScrollingLockRef, openSetStateLockTimeoutRef);
   useScrollToCard(currentIndex, root, cardRefs, stateScrollingLockRef);
+
+  // Similar to Virtual Scrolling to improve performance
   const firstVisibleIndex = Math.max(0, visibilityList.indexOf(1));
   const lastVisibleIndex = firstVisibleIndex + initiallyShownCards - 1;
   const renderList = visibilityList.map((_, index) => index >= firstVisibleIndex - RENDER_BUFFER_SIZE && index <= lastVisibleIndex + RENDER_BUFFER_SIZE ? 1 : 0);
-  const carouselAriaLabel = `Entering Carousel with ${initiallyShownCards} slides shown at a time, ${childrenLength} slides in total. Please use Pagination below with the Previous and Next buttons to navigate, or the slide dot buttons at the end to jump to slides.`;
   return /*#__PURE__*/_jsx("div", {
     className: getClassName(`bpk-card-list-row-rail__${layout}`),
     "data-testid": "bpk-card-list-row-rail__carousel",
-    "aria-label": carouselAriaLabel
+    "aria-label": carouselLabel(initiallyShownCards, childrenLength),
+    "aria-roledescription": "carousel"
     // eslint-disable-next-line jsx-a11y/no-noninteractive-tabindex
     ,
     tabIndex: 0,
@@ -83,17 +87,16 @@ const BpkCardListCarousel = props => {
         observerVisibility(el, index);
         setA11yTabIndex(el, index, visibilityList);
       };
-      const slideAriaLabel = `slide ${index + 1} of ${childrenLength}`;
       const cardStyle = isMobile ? {
         ...shownNumberStyle,
-        visibility: renderList[index] === 1 ? 'visible' : 'hidden'
+        visibility: renderList[index] === 1 ? 'visible' : 'hidden' // for mobile, {renderList[index] === 1 && card} will cause reflowing and bugs, implementing visibility improvement instead
       } : shownNumberStyle;
       return /*#__PURE__*/_jsx("div", {
         className: getClassName(`bpk-card-list-row-rail__${layout}__card`),
         ref: cardRefCallback,
         style: cardStyle,
         role: "group",
-        "aria-label": slideAriaLabel,
+        "aria-label": slideLabel(index, childrenLength),
         "aria-current": index === currentIndex ? 'true' : 'false',
         children: isMobile ? card : renderList[index] === 1 && card
       }, `carousel-card-${index.toString()}`);

package/bpk-component-card-list/src/BpkCardListRowRail/BpkCardListRowRailContainer.js

@@ -25,6 +25,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 const getClassName = cssModules(STYLES);
 const BpkCardListRowRailContainer = props => {
   const {
+    accessibilityLabels,
     accessory,
     children,
     initiallyShownCards,
@@ -37,13 +38,11 @@ const BpkCardListRowRailContainer = props => {
   const accessoryContent = layout === LAYOUTS.row && accessory === ACCESSORY_DESKTOP_TYPES.pagination ? /*#__PURE__*/_jsx(BpkPageIndicator, {
     currentIndex: currentIndex,
     totalIndicators: totalIndicators,
-    onClick: (_e, index) => {
-      setCurrentIndex(index);
-    },
+    onClick: (_e, index) => setCurrentIndex(index),
     showNav: true,
-    indicatorLabel: "Go to slide",
-    prevNavLabel: "Previous slide",
-    nextNavLabel: "Next slide"
+    indicatorLabel: accessibilityLabels?.indicatorLabel ?? 'Go to slide',
+    prevNavLabel: accessibilityLabels?.prevNavLabel ?? 'Previous slide',
+    nextNavLabel: accessibilityLabels?.nextNavLabel ?? 'Next slide'
   }) : null;
   return /*#__PURE__*/_jsxs("div", {
     className: getClassName('bpk-card-list-row-rail'),
@@ -54,6 +53,8 @@ const BpkCardListRowRailContainer = props => {
       currentIndex: currentIndex,
       setCurrentIndex: setCurrentIndex,
       isMobile: isMobile,
+      carouselLabel: accessibilityLabels?.carouselLabel,
+      slideLabel: accessibilityLabels?.slideLabel,
       children: children
     }), accessoryContent && showAccessory && /*#__PURE__*/_jsx("div", {
       role: "region",

package/bpk-component-card-list/src/BpkCardListRowRail/utils.d.ts

@@ -1,4 +1,15 @@
+/**
+ * Typically used to prevent useScrollToCard() from being called, to prevent scrollings caused by state changes, so as to avoid cyclic dependencies.
+ * @param stateScrollingLockRef - Ref to the state that indicates if scrollIntoView should be locked
+ * @param openSetStateLockTimeoutRef - Ref to the timeout that releases the lock after a delay. Should be renewed every time another scroll action is triggered, with a new lock is added.
+ */
 export declare const lockScroll: (stateScrollingLockRef: React.MutableRefObject<boolean>, openSetStateLockTimeoutRef: React.MutableRefObject<NodeJS.Timeout | null>) => void;
+/**
+ * Only sets the tabIndex of focusable elements as 0 if the card is visible, otherwise sets it to -1, including all its children.
+ * For example, if there is a button inside a card which is not shown, it cannot be focused as well.
+ * @param el - Card container element, typically a div used to wrap the card content.
+ * @param index - Current container index
+ */
 export declare const setA11yTabIndex: (el: HTMLDivElement | null, index: number, visibilityList: number[]) => void;
 export declare const useUpdateCurrentIndexByVisibility: (isMobile: boolean, visibilityList: number[], setCurrentIndex: (index: number) => void, stateScrollingLockRef: React.MutableRefObject<boolean>, openSetStateLockTimeoutRef: React.MutableRefObject<NodeJS.Timeout | null>) => void;
 export declare const useScrollToCard: (currentIndex: number, container: HTMLElement | null, cardRefs: React.MutableRefObject<Array<HTMLDivElement | null>>, stateScrollingLockRef: React.MutableRefObject<boolean>) => void;

package/bpk-component-card-list/src/BpkCardListRowRail/utils.js

@@ -18,6 +18,13 @@
 
 import { useEffect, useRef, useMemo } from 'react';
 import { RELEASE_LOCK_DELAY } from "./constants";
+
+/**
+ * Typically used to prevent useScrollToCard() from being called, to prevent scrollings caused by state changes, so as to avoid cyclic dependencies.
+ * @param stateScrollingLockRef - Ref to the state that indicates if scrollIntoView should be locked
+ * @param openSetStateLockTimeoutRef - Ref to the timeout that releases the lock after a delay. Should be renewed every time another scroll action is triggered, with a new lock is added.
+ */
+
 export const lockScroll = (stateScrollingLockRef, openSetStateLockTimeoutRef) => {
   // eslint-disable-next-line no-param-reassign
   stateScrollingLockRef.current = true;
@@ -30,6 +37,14 @@ export const lockScroll = (stateScrollingLockRef, openSetStateLockTimeoutRef) =>
     stateScrollingLockRef.current = false;
   }, RELEASE_LOCK_DELAY);
 };
+
+/**
+ * Only sets the tabIndex of focusable elements as 0 if the card is visible, otherwise sets it to -1, including all its children.
+ * For example, if there is a button inside a card which is not shown, it cannot be focused as well.
+ * @param el - Card container element, typically a div used to wrap the card content.
+ * @param index - Current container index
+ */
+
 export const setA11yTabIndex = (el, index, visibilityList) => {
   if (!el) return;
   const focusableElements = el.querySelectorAll('a, button, input, textarea, select, [tabindex]:not([tabindex="-1"])');
@@ -40,19 +55,19 @@ export const setA11yTabIndex = (el, index, visibilityList) => {
 };
 export const useUpdateCurrentIndexByVisibility = (isMobile, visibilityList, setCurrentIndex, stateScrollingLockRef, openSetStateLockTimeoutRef) => {
   useEffect(() => {
-    if (isMobile) return;
+    if (isMobile) return; // No pagination on mobile, so no need to update the current index
     if (!visibilityList || visibilityList.length === 0) return;
     const firstVisibleIndex = visibilityList.findIndex(visibility => visibility === 1);
     if (firstVisibleIndex !== -1) {
       setCurrentIndex(firstVisibleIndex);
-      lockScroll(stateScrollingLockRef, openSetStateLockTimeoutRef);
+      lockScroll(stateScrollingLockRef, openSetStateLockTimeoutRef); // prevent scrollIntoView from being called immediately after the current index is set
     }
   }, [visibilityList]);
 };
 export const useScrollToCard = (currentIndex, container, cardRefs, stateScrollingLockRef) => {
   useEffect(() => {
     const isVisible = container && container.getBoundingClientRect().bottom > 0 && container.getBoundingClientRect().bottom <= window.innerHeight;
-    if (!isVisible) return; // Escape from scrollIntoView if the container is not visible
+    if (!isVisible) return; // Escape from scrollIntoView if the container is not visible, otherwise the webpage will scroll down to the last rendered & non-visible container
 
     if (stateScrollingLockRef.current && stateScrollingLockRef.current === true) return;
     const targetCard = cardRefs.current[currentIndex];

package/bpk-component-card-list/src/common-types.d.ts

@@ -21,6 +21,13 @@ type ExpandProps = {
     collapsed: boolean;
     onExpandToggle: () => void;
 };
+type AccessibilityLabels = {
+    indicatorLabel?: string;
+    prevNavLabel?: string;
+    nextNavLabel?: string;
+    carouselLabel?: (initiallyShownCards: number, childrenLength: number) => string;
+    slideLabel?: (index: number, childrenLength: number) => string;
+};
 type CardListBaseProps = {
     title: string;
     description?: string;
@@ -37,6 +44,7 @@ type CardListBaseProps = {
     onExpandClick?: () => void;
     buttonHref?: string;
     expandText?: string;
+    accessibilityLabels?: AccessibilityLabels;
 };
 type CardListGridStackProps = {
     children: ReactElement[];
@@ -55,6 +63,7 @@ type CardListRowRailProps = {
     layout: typeof LAYOUTS.row | typeof LAYOUTS.rail;
     accessory?: typeof ACCESSORY_DESKTOP_TYPES.pagination;
     isMobile?: boolean;
+    accessibilityLabels?: AccessibilityLabels;
 };
 type CardListCarouselProps = {
     children: Array<ReactElement<HTMLDivElement | HTMLAnchorElement>>;
@@ -63,6 +72,8 @@ type CardListCarouselProps = {
     currentIndex: number;
     setCurrentIndex: Dispatch<SetStateAction<number>>;
     isMobile?: boolean;
+    carouselLabel?: (initiallyShownCards: number, childrenLength: number) => string;
+    slideLabel?: (index: number, childrenLength: number) => string;
 };
 type CardListProps = CardListBaseProps;
 export default CardListProps;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyscanner/backpack-web",
-  "version": "37.9.0",
+  "version": "37.9.1",
   "description": "Backpack Design System web library",
   "repository": {
     "type": "git",
@@ -22,7 +22,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@floating-ui/react": "^0.27.8",
+    "@floating-ui/react": "^0.26.12",
     "@popperjs/core": "^2.11.8",
     "@radix-ui/react-compose-refs": "^1.1.1",
     "@radix-ui/react-slider": "1.1.2",