@skyscanner/backpack-web 41.10.0 → 41.11.1-beta.1

package/bpk-component-accordion/src/BpkAccordion.js

@@ -17,7 +17,7 @@
  */
 
 import { createContext } from 'react';
-import { cssModules } from "../../bpk-react-utils";
+import { cssModules, getDataComponentAttribute } from "../../bpk-react-utils";
 import STYLES from "./BpkAccordion.module.css";
 import { jsx as _jsx } from "react/jsx-runtime";
 const getClassName = cssModules(STYLES);
@@ -41,6 +41,7 @@ const BpkAccordion = props => {
     },
     children: /*#__PURE__*/_jsx("div", {
       className: classNames,
+      ...getDataComponentAttribute('Accordion'),
       ...rest,
       children: children
     })

package/bpk-component-accordion/src/BpkAccordionItem.js

@@ -22,7 +22,7 @@ import AnimateHeight from "../../bpk-animate-height";
 import { withButtonAlignment } from "../../bpk-component-icon";
 import ChevronDownIcon from "../../bpk-component-icon/sm/chevron-down";
 import BpkText, { TEXT_STYLES } from "../../bpk-component-text";
-import { cssModules } from "../../bpk-react-utils";
+import { cssModules, getDataComponentAttribute } from "../../bpk-react-utils";
 import { BpkAccordionContext } from "./BpkAccordion";
 import STYLES from "./BpkAccordionItem.module.css";
 import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
@@ -88,6 +88,7 @@ const BpkAccordionItem = props => {
     _jsxs("div", {
       id: id,
       className: itemClassNames.join(' '),
+      ...getDataComponentAttribute('AccordionItem'),
       ...rest,
       children: [/*#__PURE__*/_jsx("div", {
         className: titleClassNames.join(' '),

package/bpk-component-aria-live/src/BpkAriaLive.js

@@ -16,7 +16,7 @@
  * limitations under the License.
  */
 
-import { cssModules } from "../../bpk-react-utils";
+import { cssModules, getDataComponentAttribute } from "../../bpk-react-utils";
 import STYLES from "./BpkAriaLive.module.css";
 import { jsx as _jsx } from "react/jsx-runtime";
 const getClassName = cssModules(STYLES);
@@ -35,6 +35,7 @@ const BpkAriaLive = ({
   return /*#__PURE__*/_jsx("div", {
     "aria-live": politenessSetting,
     className: classNames,
+    ...getDataComponentAttribute('AriaLive'),
     ...rest
   });
 };

package/bpk-component-autosuggest/src/BpkAutosuggestV2/BpkAutosuggest.js

@@ -21,7 +21,7 @@ import { useFloating, offset, shift, size, arrow as floatingArrow, FloatingArrow
 import { useCombobox } from 'downshift';
 import { surfaceHighlightDay } from '@skyscanner/bpk-foundations-web/tokens/base.es6';
 import BpkInput from "../../../bpk-component-input";
-import { cssModules } from "../../../bpk-react-utils";
+import { cssModules, getDataComponentAttribute } from "../../../bpk-react-utils";
 import STYLES from "./BpkAutosuggest.module.css";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 const getClassName = cssModules(STYLES);
@@ -536,6 +536,7 @@ const BpkAutosuggest = /*#__PURE__*/forwardRef(({
   return /*#__PURE__*/_jsxs("div", {
     ref: containerWrapperRef,
     className: getClassName(theme.container, suggestionsCount && theme.containerOpen),
+    ...getDataComponentAttribute('Autosuggest'),
     children: [renderInput(), showSuggestions && (isDesktop ? /*#__PURE__*/_jsx(FloatingPortal, {
       children: /*#__PURE__*/_jsxs("div", {
         ref: refs.setFloating,

package/bpk-component-bottom-sheet/src/BpkBottomSheet.js

@@ -23,9 +23,10 @@ import BpkCloseButton from "../../bpk-component-close-button";
 import BpkLink from "../../bpk-component-link";
 import BpkNavigationBar from "../../bpk-component-navigation-bar";
 import { TEXT_STYLES } from "../../bpk-component-text/src/BpkText";
+import BpkVisuallyHidden from "../../bpk-component-visually-hidden";
 import { BpkDialogWrapper, cssModules, getDataComponentAttribute } from "../../bpk-react-utils";
 import STYLES from "./BpkBottomSheet.module.css";
-import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 const getClassName = cssModules(STYLES);
 export const PADDING_TYPE = {
   none: 'none',
@@ -93,6 +94,8 @@ const BpkBottomSheet = ({
     }, timeoutDuration);
   }, [isAboveMobile, onClose]);
   const headingId = `bpk-bottom-sheet-heading-${id}`;
+  const hiddenTitleId = `bpk-bottom-sheet-title-hidden-${id}`;
+  const showHiddenTitle = !title && 'ariaLabel' in ariaProps && ariaProps.ariaLabel;
   const dialogClassName = getClassName('bpk-bottom-sheet', wide && 'bpk-bottom-sheet--wide');
   const contentStyle = getContentStyles(paddingStyles);
   return /*#__PURE__*/_jsx(BpkDialogWrapper, {
@@ -115,10 +118,10 @@ const BpkBottomSheet = ({
     },
     ...getDataComponentAttribute('BottomSheet'),
     children: /*#__PURE__*/_jsxs(_Fragment, {
-      children: [/*#__PURE__*/_jsx("header", {
+      children: [/*#__PURE__*/_jsxs("header", {
         className: getClassName('bpk-bottom-sheet--header-wrapper'),
-        children: /*#__PURE__*/_jsx(BpkNavigationBar, {
-          id: headingId,
+        children: [/*#__PURE__*/_jsx(BpkNavigationBar, {
+          id: showHiddenTitle ? hiddenTitleId : headingId,
           title: title,
           titleTextStyle: TEXT_STYLES.label1,
           titleTagName: title ? 'h2' : 'span',
@@ -132,7 +135,13 @@ const BpkBottomSheet = ({
             onClick: onAction,
             children: actionText
           }) : null
-        })
+        }), showHiddenTitle && /*#__PURE__*/_jsx(BpkVisuallyHidden, {
+          as: "h2",
+          children: /*#__PURE__*/_jsx("span", {
+            id: hiddenTitleId,
+            children: ariaProps.ariaLabel
+          })
+        })]
       }), /*#__PURE__*/_jsx("div", {
         className: contentStyle,
         children: children

package/bpk-component-breakpoint/src/BpkBreakpoint.js

@@ -42,7 +42,7 @@ const useLegacyWarning = (query, legacy, isClient) => useMemo(() => {
 const BpkBreakpoint = ({
   children,
   legacy = false,
-  matchSSR = false,
+  matchSSR,
   query
 }) => {
   /**
@@ -64,7 +64,7 @@ const BpkBreakpoint = ({
     return matches ? children : null;
   }
   if (typeof children === 'function') {
-    return children(matchSSR);
+    return children(!!matchSSR);
   }
   return matchSSR ? children : null;
 };

package/bpk-component-breakpoint/src/useMediaQuery.js

@@ -17,28 +17,41 @@
  */
 
 import { useEffect, useState } from 'react';
-const useMediaQuery = (query, matchSSR = false) => {
+const useMediaQuery = (query, matchSSR) => {
   const isClient = typeof window !== 'undefined' && !!window.matchMedia;
+
+  // When matchSSR is provided, we need hydration protection
+  const needsHydrationProtection = matchSSR !== undefined;
+  const [isHydrated, setIsHydrated] = useState(!needsHydrationProtection);
   const [matches, setMatches] = useState(() => {
-    // When matchSSR=true: use matchSSR value to match server-rendered HTML
-    // This prevents hydration errors when User-Agent (server) != viewport size (client)
-    if (!isClient || matchSSR) {
+    if (!isClient) {
+      return matchSSR ?? false;
+    }
+    if (needsHydrationProtection) {
       return matchSSR;
     }
     return window.matchMedia(query).matches;
   });
+
+  // Mark hydration as complete
   useEffect(() => {
-    if (isClient) {
-      const media = window.matchMedia(query);
-      setMatches(media.matches);
-      const listener = () => {
-        setMatches(media.matches);
-      };
-      media.addEventListener('change', listener);
-      return () => media.removeEventListener('change', listener);
+    if (needsHydrationProtection && !isHydrated) {
+      setIsHydrated(true);
     }
-    return () => {};
-  }, [query, isClient]);
+  }, [needsHydrationProtection, isHydrated]);
+  useEffect(() => {
+    // Wait for hydration to complete
+    if (!isClient || !isHydrated) {
+      return () => {};
+    }
+    const media = window.matchMedia(query);
+    setMatches(media.matches);
+    const listener = () => {
+      setMatches(media.matches);
+    };
+    media.addEventListener('change', listener);
+    return () => media.removeEventListener('change', listener);
+  }, [query, isClient, isHydrated]);
   return matches;
 };
 export default useMediaQuery;

package/bpk-component-bubble/src/BpkBubble.js

@@ -17,7 +17,7 @@
  */
 
 import BpkText, { TEXT_COLORS, TEXT_STYLES } from "../../bpk-component-text";
-import { cssModules } from "../../bpk-react-utils";
+import { cssModules, getDataComponentAttribute } from "../../bpk-react-utils";
 import BpkBubbleArrow from "../icons/BpkBubbleArrow";
 import STYLES from "./BpkBubble.module.css";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
@@ -26,6 +26,7 @@ const BpkBubble = ({
   children
 }) => /*#__PURE__*/_jsxs("span", {
   className: getClassName('bpk-bubble'),
+  ...getDataComponentAttribute('Bubble'),
   children: [/*#__PURE__*/_jsx(BpkText, {
     textStyle: TEXT_STYLES.label3,
     tagName: "span",

package/bpk-component-calendar/src/BpkCalendarDate.js

@@ -17,7 +17,7 @@
  */
 
 import { PureComponent } from 'react';
-import { cssModules } from "../../bpk-react-utils";
+import { cssModules, getDataComponentAttribute } from "../../bpk-react-utils";
 import STYLES from "./BpkCalendarDate.module.css";
 import { jsx as _jsx } from "react/jsx-runtime";
 const getClassName = cssModules(STYLES);
@@ -125,6 +125,7 @@ class BpkCalendarDate extends PureComponent {
       type: "button",
       style: style,
       className: classNames.join(' '),
+      ...getDataComponentAttribute('CalendarDate'),
       "aria-label": `${date.getDate()}`,
       disabled: isBlocked,
       tabIndex: isKeyboardFocusable && isFocused ? 0 : -1,

package/bpk-component-calendar/src/BpkCalendarGrid.js

@@ -17,7 +17,7 @@
  */
 
 import { Component } from 'react';
-import { cssModules, isDeviceIos } from "../../bpk-react-utils";
+import { cssModules, isDeviceIos, getDataComponentAttribute } from "../../bpk-react-utils";
 import { addCalendarGridTransition } from "./BpkCalendarGridTransition";
 import BpkCalendarWeek from "./BpkCalendarWeek";
 import { CALENDAR_SELECTION_TYPE } from "./custom-proptypes";
@@ -105,6 +105,7 @@ class BpkCalendarGrid extends Component {
     const classNames = getClassName('bpk-calendar-grid', className);
     return /*#__PURE__*/_jsx("div", {
       className: classNames,
+      ...getDataComponentAttribute('CalendarGrid'),
       "aria-hidden": !isKeyboardFocusable,
       role: "grid",
       "aria-label": formatMonth(month),

package/bpk-component-calendar/src/BpkCalendarGridHeader.js

@@ -17,7 +17,7 @@
  */
 
 import { PureComponent } from 'react';
-import { cssModules } from "../../bpk-react-utils";
+import { cssModules, getDataComponentAttribute } from "../../bpk-react-utils";
 import { orderDaysOfWeek } from "./date-utils";
 import STYLES from "./BpkCalendarGridHeader.module.css";
 import { jsx as _jsx } from "react/jsx-runtime";
@@ -57,6 +57,7 @@ class BpkCalendarGridHeader extends PureComponent {
     }
     return /*#__PURE__*/_jsx("header", {
       className: classNames.join(' '),
+      ...getDataComponentAttribute('CalendarGridHeader'),
       "aria-hidden": true,
       children: /*#__PURE__*/_jsx("ol", {
         className: getClassName('bpk-calendar-header__week'),

package/bpk-component-calendar/src/BpkCalendarGridTransition.js

@@ -17,7 +17,7 @@
  */
 
 import { Component, createElement as _createElement } from 'react';
-import { cssModules, isRTL } from "../../bpk-react-utils";
+import { cssModules, isRTL, getDataComponentAttribute } from "../../bpk-react-utils";
 import { addMonths, isSameMonth, formatIsoMonth, differenceInCalendarMonths, dateToBoundaries, startOfDay, setMonthYear, isWithinRange, getMonthRange } from "./date-utils";
 import { getCalendarGridWidth, getTransformStyles, isTransitionEndSupported } from "./utils";
 import STYLES from "./BpkCalendarGridTransition.module.css";
@@ -132,6 +132,7 @@ class BpkCalendarGridTransition extends Component {
         className: stripClassNames,
         style: getTransformStyles(transitionValue),
         onTransitionEnd: this.onMonthTransitionEnd,
+        ...getDataComponentAttribute('CalendarGridTransition'),
         children: this.state.months.map((m, index) => min && max && isWithinRange(m, {
           start: min,
           end: max

package/bpk-component-calendar/src/BpkCalendarNav.js

@@ -22,7 +22,7 @@ import ArrowLeftIcon from "../../bpk-component-icon/lg/arrow-left";
 import ArrowRightIcon from "../../bpk-component-icon/lg/arrow-right";
 // @ts-expect-error Untyped import. See `decisions/imports-ts-suppressions.md`.
 import BpkSelect from "../../bpk-component-select";
-import { cssModules } from "../../bpk-react-utils";
+import { cssModules, getDataComponentAttribute } from "../../bpk-react-utils";
 import { addMonths, formatIsoMonth, getMonthRange, getMonthsInRange, isWithinRange, parseIsoDate, startOfMonth } from "./date-utils";
 import STYLES from "./BpkCalendarNav.module.css";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
@@ -69,6 +69,7 @@ const BpkCalendarNav = ({
   const nextMonth = addMonths(baseMonth, 1);
   return /*#__PURE__*/_jsx("div", {
     className: getClassName('bpk-calendar-nav'),
+    ...getDataComponentAttribute('CalendarNav'),
     children: /*#__PURE__*/_jsxs("div", {
       style: {
         display: 'table-row'

package/bpk-component-calendar/src/BpkCalendarWeek.js

@@ -17,7 +17,7 @@
  */
 
 import { Component } from 'react';
-import { cssModules } from "../../bpk-react-utils";
+import { cssModules, getDataComponentAttribute } from "../../bpk-react-utils";
 import { SELECTION_TYPES } from "./BpkCalendarDate";
 import { CALENDAR_SELECTION_TYPE } from "./custom-proptypes";
 import { isSameDay, isSameWeek, isSameMonth, isToday, isWithinRange, startOfMonth, endOfMonth } from "./date-utils";
@@ -267,6 +267,7 @@ class BpkCalendarWeek extends Component {
     }
     return /*#__PURE__*/_jsx("div", {
       className: getClassName('bpk-calendar-week'),
+      ...getDataComponentAttribute('CalendarWeek'),
       role: "row",
       children: this.props.dates.map(date => {
         const isBlocked = minDate && maxDate ? !isWithinRange(date.val, {

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

@@ -38,6 +38,7 @@ const BpkCardList = props => {
     chipGroup,
     description,
     expandText,
+    initiallyInViewCardIndex = 0,
     initiallyShownCardsDesktop = DEFAULT_ITEMS_DESKTOP,
     initiallyShownCardsMobile = DEFAULT_ITEMS_MOBILE,
     layoutDesktop,
@@ -78,6 +79,7 @@ const BpkCardList = props => {
               initiallyShownCards: initiallyShownCardsMobile,
               layout: layoutMobile,
               accessibilityLabels: accessibilityLabels,
+              initiallyInViewCardIndex: initiallyInViewCardIndex,
               isMobile: true,
               children: cardList
             }), layoutMobile === LAYOUTS.stack && /*#__PURE__*/_jsx(BpkCardListGridStack, {
@@ -97,6 +99,7 @@ const BpkCardList = props => {
               initiallyShownCards: initiallyShownCardsDesktop,
               layout: layoutDesktop,
               accessibilityLabels: accessibilityLabels,
+              initiallyInViewCardIndex: initiallyInViewCardIndex,
               children: cardList
             }), layoutDesktop === LAYOUTS.grid && accessoryDesktop !== ACCESSORY_DESKTOP_TYPES.pagination && /*#__PURE__*/_jsx(BpkCardListGridStack, {
               accessory: accessoryDesktop,

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

@@ -20,7 +20,7 @@ import { useRef, useState, useEffect, isValidElement, Children, useMemo } from '
 import throttle from 'lodash/throttle';
 import { cssModules, getDataComponentAttribute } from "../../../bpk-react-utils";
 import { RENDER_BUFFER_SIZE } from "./constants";
-import { lockScroll, setA11yTabIndex, useScrollToCard, useIntersectionObserver } from "./utils";
+import { setA11yTabIndex, useIntersectionObserver, usePageScrollSync } from "./utils";
 import STYLES from "./BpkCardListCarousel.module.css";
 import { jsx as _jsx } from "react/jsx-runtime";
 const getClassName = cssModules(STYLES);
@@ -30,6 +30,7 @@ const BpkCardListCarousel = props => {
     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,
+    initialPageIndex,
     initiallyShownCards,
     isMobile = false,
     layout,
@@ -47,13 +48,20 @@ const BpkCardListCarousel = props => {
   const firstCardWidthRef = useRef(null);
   const firstCardHeightRef = useRef(null);
   const [visibilityList, setVisibilityList] = useState(Array(childrenLength).fill(0));
-  const stateScrollingLockRef = useRef(false);
-  const openSetStateLockTimeoutRef = useRef(null);
   const observerVisibility = useIntersectionObserver({
     root,
     threshold: 0.5
   }, setVisibilityList);
-  useScrollToCard(currentIndex * initiallyShownCards, root, cardRefs, stateScrollingLockRef);
+  usePageScrollSync({
+    currentIndex,
+    setCurrentIndex,
+    initiallyShownCards,
+    cardRefs,
+    visibilityList,
+    container: root,
+    enabled: !isMobile,
+    initialPageIndex
+  });
 
   // Similar to Virtual Scrolling to improve performance
   const firstVisibleIndex = Math.max(0, visibilityList.indexOf(1));
@@ -87,22 +95,6 @@ const BpkCardListCarousel = props => {
       }
     }
   }), [childrenLength, observerVisibility, visibilityList, firstCardWidthRef, firstCardHeightRef]);
-  useEffect(() => {
-    const container = root;
-    if (isMobile || !container) return undefined;
-    const lockScrollDuringInteraction = () => {
-      lockScroll(stateScrollingLockRef, openSetStateLockTimeoutRef);
-    };
-    container.addEventListener('wheel', lockScrollDuringInteraction);
-    container.addEventListener('touchmove', lockScrollDuringInteraction);
-    return () => {
-      container.removeEventListener('touchmove', lockScrollDuringInteraction);
-      container.removeEventListener('wheel', lockScrollDuringInteraction);
-      if (openSetStateLockTimeoutRef.current) {
-        clearTimeout(openSetStateLockTimeoutRef.current);
-      }
-    };
-  }, [root]);
   useEffect(() => {
     // update hasBeenVisibleRef to include the range of cards that should be visible
     const start = currentIndex * initiallyShownCards;
@@ -111,15 +103,6 @@ const BpkCardListCarousel = props => {
       hasBeenVisibleRef.current.add(i);
     }
   }, [currentIndex, initiallyShownCards, childrenLength, dynamicRenderBufferSize]);
-  useEffect(() => {
-    const firstVisible = visibilityList.indexOf(1);
-    if (firstVisible >= 0) {
-      const newIndex = Math.floor(firstVisible / initiallyShownCards);
-      if (newIndex !== currentIndex) {
-        setCurrentIndex(newIndex);
-      }
-    }
-  }, [initiallyShownCards]);
   useEffect(() => {
     const handleResize = throttle(() => {
       firstCardWidthRef.current = null;
@@ -149,8 +132,9 @@ const BpkCardListCarousel = props => {
       if (firstCardHeightRef.current) {
         cardDimensionStyle.height = `${firstCardHeightRef.current}px`;
       }
+      const isPageStart = index % initiallyShownCards === 0;
       const commonProps = {
-        className: getClassName(`bpk-card-list-row-rail__${layout}__card`),
+        className: getClassName(`bpk-card-list-row-rail__${layout}__card`, isPageStart && 'bpk-card-list-row-rail__card--page-start'),
         style: shownNumberStyle,
         key: `carousel-card-${index.toString()}`,
         role: 'group'
@@ -161,6 +145,7 @@ const BpkCardListCarousel = props => {
       if (!shouldRenderCard) {
         return /*#__PURE__*/_jsx("div", {
           ...commonProps,
+          ref: cardRefFns[index],
           style: {
             ...commonProps.style,
             ...cardDimensionStyle,

package/bpk-component-card-list/src/BpkCardListRowRail/BpkCardListCarousel.module.css

@@ -15,4 +15,4 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-.bpk-card-list-row-rail__row,.bpk-card-list-row-rail__rail{--spacing-offset: 0.5rem;--carousel-card-gap: 1.25rem;display:flex;overflow-x:hidden;box-sizing:border-box;gap:var(--carousel-card-gap);margin-block:-1.5rem;margin-inline:-0.5rem;padding-block:1.5rem;padding-inline:.5rem;scroll-snap-stop:always;scroll-snap-type:x mandatory;scrollbar-width:none}@media(max-width: 32rem){.bpk-card-list-row-rail__row,.bpk-card-list-row-rail__rail{--spacing-offset: 1rem;--carousel-card-gap: 1rem;overflow-x:scroll}}.bpk-card-list-row-rail__row::-webkit-scrollbar,.bpk-card-list-row-rail__rail::-webkit-scrollbar{display:none}.bpk-card-list-row-rail__row__card,.bpk-card-list-row-rail__rail__card{position:relative;flex:0 0 calc((100% - (var(--carousel-card-gap)*(var(--initially-shown-cards, 3) - 1) + var(--spacing-offset)*2/var(--initially-shown-cards, 3)))/var(--initially-shown-cards, 3));overflow:visible;box-sizing:border-box;scroll-margin-inline:var(--spacing-offset);scroll-snap-align:start}@media(max-width: 32rem){.bpk-card-list-row-rail__row__card,.bpk-card-list-row-rail__rail__card{flex:0 0 calc((100% - var(--carousel-card-gap)*(var(--initially-shown-cards, 3) - 1))/max(1,var(--initially-shown-cards, 3) - .8))}}.bpk-card-list-row-rail__rail{-webkit-overflow-scrolling:touch}@media(max-width: 32rem){.bpk-card-list-row-rail__rail{margin-inline:calc(-1*var(--spacing-offset));padding-inline:var(--spacing-offset)}}.bpk-card-list-row-rail__card-slot{display:grid;height:100%}
+.bpk-card-list-row-rail__row,.bpk-card-list-row-rail__rail{--spacing-offset: 0.5rem;--carousel-card-gap: 1.25rem;display:flex;overflow-x:scroll;box-sizing:border-box;gap:var(--carousel-card-gap);margin-block:-1.5rem;margin-inline:-0.5rem;-webkit-overflow-scrolling:touch;padding-block:1.5rem;padding-inline:.5rem;scroll-snap-type:x mandatory;scrollbar-width:none}@media(max-width: 32rem){.bpk-card-list-row-rail__row,.bpk-card-list-row-rail__rail{--spacing-offset: 1rem;--carousel-card-gap: 1rem;overflow-x:scroll}}.bpk-card-list-row-rail__row::-webkit-scrollbar,.bpk-card-list-row-rail__rail::-webkit-scrollbar{display:none}.bpk-card-list-row-rail__row__card,.bpk-card-list-row-rail__rail__card{position:relative;flex:0 0 calc((100% - (var(--carousel-card-gap)*(var(--initially-shown-cards, 3) - 1) + var(--spacing-offset)*2/var(--initially-shown-cards, 3)))/var(--initially-shown-cards, 3));overflow:visible;box-sizing:border-box;scroll-margin-inline:var(--spacing-offset);scroll-snap-align:start}@media(min-width: 32.0625rem){.bpk-card-list-row-rail__row__card,.bpk-card-list-row-rail__rail__card{scroll-snap-align:none}}@media(max-width: 32rem){.bpk-card-list-row-rail__row__card,.bpk-card-list-row-rail__rail__card{flex:0 0 calc((100% - var(--carousel-card-gap)*(var(--initially-shown-cards, 3) - 1))/max(1,var(--initially-shown-cards, 3) - .8))}}@media(min-width: 32.0625rem){.bpk-card-list-row-rail__card--page-start{scroll-snap-align:start;scroll-snap-stop:always}}.bpk-card-list-row-rail__rail{-webkit-overflow-scrolling:touch}@media(max-width: 32rem){.bpk-card-list-row-rail__rail{margin-inline:calc(-1*var(--spacing-offset));padding-inline:var(--spacing-offset)}}.bpk-card-list-row-rail__card-slot{display:grid;height:100%}

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

@@ -28,6 +28,7 @@ const BpkCardListRowRailContainer = props => {
     accessibilityLabels,
     accessory,
     children,
+    initiallyInViewCardIndex,
     initiallyShownCards,
     isMobile = false,
     layout
@@ -35,7 +36,18 @@ const BpkCardListRowRailContainer = props => {
   const childrenCount = Children.count(children);
   const totalIndicators = Math.ceil(childrenCount / initiallyShownCards);
   const showAccessory = childrenCount > initiallyShownCards;
-  const [currentIndex, setCurrentIndex] = useState(0);
+
+  // Calculate initial page from card index
+  const [initialPageIndex] = useState(() => {
+    if (initiallyInViewCardIndex < 0) {
+      return 0;
+    }
+    if (initiallyInViewCardIndex >= childrenCount) {
+      return Math.max(0, totalIndicators - 1);
+    }
+    return Math.floor(initiallyInViewCardIndex / initiallyShownCards);
+  });
+  const [currentIndex, setCurrentIndex] = useState(initialPageIndex);
   const accessoryContent = layout === LAYOUTS.row && accessory === ACCESSORY_DESKTOP_TYPES.pagination ? /*#__PURE__*/_jsx(BpkPageIndicator, {
     currentIndex: currentIndex,
     totalIndicators: totalIndicators,
@@ -57,6 +69,7 @@ const BpkCardListRowRailContainer = props => {
       isMobile: isMobile,
       carouselLabel: accessibilityLabels?.carouselLabel,
       slideLabel: accessibilityLabels?.slideLabel,
+      initialPageIndex: initialPageIndex,
       children: children
     }), accessoryContent && showAccessory && /*#__PURE__*/_jsx("div", {
       role: "region",

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

@@ -1,2 +1,2 @@
-export declare const RELEASE_LOCK_DELAY = 20;
+export declare const RELEASE_LOCK_DELAY = 200;
 export declare const RENDER_BUFFER_SIZE = 3;

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

@@ -16,5 +16,5 @@
  * limitations under the License.
  */
 
-export const RELEASE_LOCK_DELAY = 20;
+export const RELEASE_LOCK_DELAY = 200;
 export const RENDER_BUFFER_SIZE = 3;

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

@@ -1,9 +1,4 @@
-/**
- * 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;
+import type { Dispatch, SetStateAction, RefObject } from 'react';
 /**
  * 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.
@@ -11,5 +6,27 @@ export declare const lockScroll: (stateScrollingLockRef: React.MutableRefObject<
  * @param index - Current container index
  */
 export declare const setA11yTabIndex: (el: HTMLDivElement | null, index: number, visibilityList: number[]) => void;
-export declare const useScrollToCard: (currentIndex: number, container: HTMLElement | null, cardRefs: React.MutableRefObject<Array<HTMLDivElement | null>>, stateScrollingLockRef: React.MutableRefObject<boolean>) => void;
-export declare const useIntersectionObserver: ({ root, threshold }: IntersectionObserverInit, setVisibilityList: React.Dispatch<React.SetStateAction<number[]>>) => (element: HTMLElement | null, index: number) => void;
+export declare const useIntersectionObserver: ({ root, threshold }: IntersectionObserverInit, setVisibilityList: Dispatch<SetStateAction<number[]>>) => (element: HTMLElement | null, index: number) => void;
+type UsePageScrollSyncOptions = {
+    currentIndex: number;
+    setCurrentIndex: Dispatch<SetStateAction<number>>;
+    initiallyShownCards: number;
+    cardRefs: RefObject<Array<HTMLDivElement | null>>;
+    visibilityList: number[];
+    container: HTMLElement | null;
+    enabled: boolean;
+    initialPageIndex: number;
+};
+/**
+ * Provides bidirectional synchronisation between page index state and scroll position.
+ *
+ * - **State → Scroll**: When `currentIndex` changes (e.g. via pagination buttons),
+ *   the container scrolls to bring the corresponding page into view.
+ * - **Scroll → State**: When the user scrolls (via wheel or touch), `currentIndex`
+ *   is updated to reflect the first visible page.
+ *
+ * The hook uses a lock mechanism to prevent conflicts between programmatic and
+ * user-initiated scrolling.
+ */
+export declare const usePageScrollSync: ({ cardRefs, container, currentIndex, enabled, initialPageIndex, initiallyShownCards, setCurrentIndex, visibilityList, }: UsePageScrollSyncOptions) => void;
+export {};