@telus-uds/components-base 1.12.1 → 1.14.1

package/lib/RadioCard/RadioCardGroup.js

@@ -92,6 +92,7 @@ const RadioCardGroup = /*#__PURE__*/(0, _react.forwardRef)((_ref, ref) => {
     legend,
     tooltip,
     hint,
+    hintPosition = 'inline',
     validation,
     feedback,
     initialCheckedId,
@@ -136,6 +137,7 @@ const RadioCardGroup = /*#__PURE__*/(0, _react.forwardRef)((_ref, ref) => {
     legend: legend,
     tooltip: tooltip,
     hint: hint,
+    hintPosition: hintPosition,
     space: fieldSpace,
     feedback: feedback,
     inactive: inactive || readOnly,
@@ -221,6 +223,11 @@ RadioCardGroup.propTypes = { ...selectedSystemPropTypes,
    */
   hint: _propTypes.default.string,
 
+  /**
+   * Position of the hint relative to label. Use `below` to display a larger hint below the label.
+   */
+  hintPosition: _propTypes.default.oneOf(['inline', 'below']),
+
   /**
    * Optional tooltip text content to include alongside the legend and hint.
    */

package/lib/SkipLink/SkipLink.js

@@ -0,0 +1,216 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+
+var _react = _interopRequireWildcard(require("react"));
+
+var _Platform = _interopRequireDefault(require("react-native-web/dist/cjs/exports/Platform"));
+
+var _Pressable = _interopRequireDefault(require("react-native-web/dist/cjs/exports/Pressable"));
+
+var _StyleSheet = _interopRequireDefault(require("react-native-web/dist/cjs/exports/StyleSheet"));
+
+var _Text = _interopRequireDefault(require("react-native-web/dist/cjs/exports/Text"));
+
+var _propTypes = _interopRequireDefault(require("prop-types"));
+
+var _ThemeProvider = require("../ThemeProvider");
+
+var _utils = require("../utils");
+
+var _jsxRuntime = require("react/jsx-runtime");
+
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+
+function _getRequireWildcardCache(nodeInterop) { if (typeof WeakMap !== "function") return null; var cacheBabelInterop = new WeakMap(); var cacheNodeInterop = new WeakMap(); return (_getRequireWildcardCache = function (nodeInterop) { return nodeInterop ? cacheNodeInterop : cacheBabelInterop; })(nodeInterop); }
+
+function _interopRequireWildcard(obj, nodeInterop) { if (!nodeInterop && obj && obj.__esModule) { return obj; } if (obj === null || typeof obj !== "object" && typeof obj !== "function") { return { default: obj }; } var cache = _getRequireWildcardCache(nodeInterop); if (cache && cache.has(obj)) { return cache.get(obj); } var newObj = {}; var hasPropertyDescriptor = Object.defineProperty && Object.getOwnPropertyDescriptor; for (var key in obj) { if (key !== "default" && Object.prototype.hasOwnProperty.call(obj, key)) { var desc = hasPropertyDescriptor ? Object.getOwnPropertyDescriptor(obj, key) : null; if (desc && (desc.get || desc.set)) { Object.defineProperty(newObj, key, desc); } else { newObj[key] = obj[key]; } } } newObj.default = obj; if (cache) { cache.set(obj, newObj); } return newObj; }
+
+const [selectProps, selectedSystemPropTypes] = (0, _utils.selectSystemProps)([_utils.a11yProps, _utils.linkProps]); // ensure explicit selection of tokens
+
+const selectStyles = _ref => {
+  let {
+    backgroundColor,
+    outlineColor,
+    outlineOffset,
+    outlineStyle,
+    outlineWidth,
+    paddingHorizontal,
+    paddingVertical,
+    borderRadius
+  } = _ref;
+  return {
+    backgroundColor,
+    outlineColor,
+    outlineOffset,
+    outlineStyle,
+    outlineWidth,
+    paddingHorizontal,
+    paddingVertical,
+    borderRadius
+  };
+};
+
+const selectTextStyles = _ref2 => {
+  let {
+    color
+  } = _ref2;
+  return {
+    color
+  };
+};
+/**
+ * A generic Skip link component, unstyled by default.
+ * A Skip link component help keyboard-only users, screen reader users to skip
+ * sections and navigate to the content they want.
+ *
+ * ## Component API
+ *
+ * For common uses, pass a `href` that is a # link to a DOM id that can be skipped to (web only).
+ *
+ * The element with this ID should be focusable, e.g. `<Box nativeID="skip-target" focusable>`.
+ *
+ * Other custom behaviour may be set by passing an `onPress` function, and routers may be integrated
+ * in the same way as other navigation-related components by passing a `LinkRouter`; but a # anchor
+ * href on web and/or a `targetRef` for cross-platform applications is the recommended approach.
+ *
+ * ## Visible styling
+ *
+ * When focused, the skip link shows as a visible element similar to a simplified ButtonLink using
+ * UDS theming. The `tokens` prop may be used to override these styles.
+ *
+ * To control the background of a skip link, the following tokens can be used:
+ *
+ * - `backgroundColor`
+ * *
+ * In order to control the color of the skip link text, the following tokens can be used:
+ *
+ * - `color`
+ *
+ * ### Padding
+ *
+ * The following padding tokens can be used:
+ *
+ * - `paddingHorizontal`
+ * - `paddingVertical`
+ *
+ * ### Outline
+ *
+ * The following tokens to control the outline:
+ *
+ * - `outlineColor`
+ * - `outlineOffset`
+ * - `outlineStyle`
+ * - `outlineWidth`
+ *
+ * ## Usability and A11y guidelines
+ *
+ * - The skip link component is visually hidden until a keyboard press activates it.
+ * - Usually, you should place the skip link immediately after the opening <body> tag.
+ * - This lets users bypass top-level navigation links and jump to the main content on a page.
+ * - Also consider using SkipLink before a complex feature containing many focusable elements.
+ *
+ * ## Accessibility
+ *
+ * Skip link supports all the common a11y and link props.
+ */
+
+
+const SkipLink = /*#__PURE__*/(0, _react.forwardRef)((_ref3, ref) => {
+  let {
+    tokens,
+    variant,
+    href,
+    children,
+    ...rawRest
+  } = _ref3;
+
+  const {
+    onPress,
+    ...rest
+  } = _utils.clickProps.toPressProps(rawRest);
+
+  const getTokens = (0, _ThemeProvider.useThemeTokensCallback)('SkipLink', tokens, variant);
+  const defaultTokens = getTokens();
+
+  const resolveLinkTokens = pressState => (0, _utils.resolvePressableTokens)(defaultTokens, pressState);
+
+  const handlePress = event => {
+    if (typeof onPress === 'function') onPress(event); // TODO - support native apps with something based on refs and/or setAccessibilityFocus
+  };
+
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)(_Pressable.default, {
+    ref: ref,
+    accessibilityRole: "link",
+    onPress: handlePress,
+    href: href,
+    style: _ref4 => {
+      let {
+        focused: focus
+      } = _ref4;
+      const themeTokens = getTokens({
+        focus
+      });
+      const skipLinkStyle = selectStyles(themeTokens);
+      return [staticStyles.absolute, skipLinkStyle, !focus && staticStyles.hidden];
+    },
+    ...selectProps(rest),
+    children: pressState => {
+      const themeTokens = resolveLinkTokens(pressState);
+      const textStyles = selectTextStyles(themeTokens);
+      return /*#__PURE__*/(0, _jsxRuntime.jsx)(_Text.default, {
+        style: [textStyles, staticStyles.baseline],
+        children: children
+      });
+    }
+  });
+});
+SkipLink.displayName = 'SkipLink';
+SkipLink.propTypes = { ...selectedSystemPropTypes,
+
+  /**
+   * The text content shown or read out when the SkipLink is focused, usually a string.
+   */
+  children: _propTypes.default.node,
+
+  /**
+   * The target to skip to. Usually an anchor link to a section id (e.g. href="#main-section").
+   */
+  href: _propTypes.default.string,
+  tokens: (0, _utils.getTokensPropType)('SkipLink'),
+  variant: _utils.variantProp.propType
+};
+
+const staticStyles = _StyleSheet.default.create({
+  baseline: {
+    alignSelf: 'baseline'
+  },
+  absolute: {
+    margin: 0,
+    position: 'absolute',
+    top: 0,
+    left: 0
+  },
+  hidden: {
+    overflow: 'hidden',
+    ..._Platform.default.select({
+      web: {
+        clip: 'rect(0 0 0 0)',
+        clipPath: 'inset(50%)'
+      },
+      default: {
+        // width / height of 0 would make it non-focusable
+        height: 1,
+        width: 1,
+        opacity: 0
+      }
+    })
+  }
+});
+
+var _default = (0, _utils.withLinkRouter)(SkipLink);
+
+exports.default = _default;

package/lib/SkipLink/index.js

@@ -0,0 +1,13 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+
+var _SkipLink = _interopRequireDefault(require("./SkipLink"));
+
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+
+var _default = _SkipLink.default;
+exports.default = _default;

package/lib/ThemeProvider/ThemeProvider.js

@@ -11,6 +11,8 @@ var _propTypes = _interopRequireDefault(require("prop-types"));
 
 var _utils = require("./utils");
 
+var _responsiveProps = _interopRequireDefault(require("../utils/props/responsiveProps"));
+
 var _jsxRuntime = require("react/jsx-runtime");
 
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
@@ -65,9 +67,12 @@ ThemeProvider.propTypes = {
    * - `forceAbsoluteFontSizing`: available on web only; when set to true, allows
    *   using absolute font sizing (in pixels, doesn't scale) instead of the
    *   relative sizing (in `rem`, scales depending on the browser settings)
+   * - `contentMaxWidth`: allows configuration of the content max width to be used in components
+   *   such as Footnote and Notification to avoid content to stretch width more then the page's width
    */
   themeOptions: _propTypes.default.shape({
-    forceAbsoluteFontSizing: _propTypes.default.bool
+    forceAbsoluteFontSizing: _propTypes.default.bool,
+    contentMaxWidth: _responsiveProps.default.getTypeOptionallyByViewport(_propTypes.default.number)
   })
 };
 var _default = ThemeProvider;

package/lib/ToggleSwitch/ToggleSwitchGroup.js

@@ -49,6 +49,7 @@ const ToggleSwitchGroup = /*#__PURE__*/(0, _react.forwardRef)((_ref, ref) => {
     inactive = false,
     feedback,
     hint,
+    hintPosition = 'inline',
     tooltip,
     legend,
     name: inputGroupName,
@@ -134,6 +135,7 @@ const ToggleSwitchGroup = /*#__PURE__*/(0, _react.forwardRef)((_ref, ref) => {
     legend: legend,
     tooltip: tooltip,
     hint: hint,
+    hintPosition: hintPosition,
     space: fieldSpace,
     feedback: feedback,
     inactive: inactive,
@@ -216,6 +218,11 @@ ToggleSwitchGroup.propTypes = { ...selectedSystemPropTypes,
    */
   hint: _propTypes.default.string,
 
+  /**
+   * Position of the hint relative to label. Use `below` to display a larger hint below the label.
+   */
+  hintPosition: _propTypes.default.oneOf(['inline', 'below']),
+
   /**
    * Optional tooltip text content to include alongside the legend and hint.
    */

package/lib/index.js

@@ -34,6 +34,7 @@ var _exportNames = {
   Select: true,
   SideNav: true,
   Skeleton: true,
+  SkipLink: true,
   Spacer: true,
   StackView: true,
   StepTracker: true,
@@ -249,6 +250,12 @@ Object.defineProperty(exports, "Skeleton", {
     return _Skeleton.default;
   }
 });
+Object.defineProperty(exports, "SkipLink", {
+  enumerable: true,
+  get: function () {
+    return _SkipLink.default;
+  }
+});
 Object.defineProperty(exports, "Spacer", {
   enumerable: true,
   get: function () {
@@ -524,6 +531,8 @@ var _SideNav = _interopRequireDefault(require("./SideNav"));
 
 var _Skeleton = _interopRequireDefault(require("./Skeleton"));
 
+var _SkipLink = _interopRequireDefault(require("./SkipLink"));
+
 var _Spacer = _interopRequireDefault(require("./Spacer"));
 
 var _StackView = _interopRequireWildcard(require("./StackView"));

package/lib-module/Button/ButtonBase.js

@@ -7,6 +7,7 @@ import Platform from "react-native-web/dist/exports/Platform";
 import { applyTextStyles, applyShadowToken, applyOuterBorder, useTheme } from '../ThemeProvider';
 import buttonPropTypes from './propTypes';
 import { a11yProps, clickProps, focusHandlerProps, getCursorStyle, linkProps, resolvePressableState, resolvePressableTokens, selectSystemProps, viewProps, wrapStringsInText, withLinkRouter } from '../utils';
+import { IconText } from '../Icon';
 import { jsx as _jsx } from "react/jsx-runtime";
 const [selectProps, selectedSystemPropTypes] = selectSystemProps([a11yProps, focusHandlerProps, linkProps, viewProps]);
 
@@ -167,7 +168,18 @@ const selectWebOnlyStyles = (inactive, themeTokens, _ref7) => {
   });
 };
 
-const ButtonBase = /*#__PURE__*/forwardRef((_ref8, ref) => {
+const selectItemIconTokens = _ref8 => {
+  let {
+    color,
+    iconSize
+  } = _ref8;
+  return {
+    size: iconSize,
+    color
+  };
+};
+
+const ButtonBase = /*#__PURE__*/forwardRef((_ref9, ref) => {
   let {
     id,
     href,
@@ -178,8 +190,11 @@ const ButtonBase = /*#__PURE__*/forwardRef((_ref8, ref) => {
     // alias for inactive
     inactive = disabled,
     selected = false,
+    icon,
+    iconPosition = icon ? 'left' : undefined,
+    iconProps,
     ...rawRest
-  } = _ref8;
+  } = _ref9;
   const {
     onPress,
     ...rest
@@ -216,10 +231,15 @@ const ButtonBase = /*#__PURE__*/forwardRef((_ref8, ref) => {
       const themeTokens = resolveButtonTokens(pressableState);
       const containerStyles = selectInnerContainerStyles(themeTokens);
       const borderStyles = selectBorderStyles(themeTokens);
-      const textStyles = [selectTextStyles(themeTokens, themeOptions), staticStyles.text]; // If the container has a width set, fill it instead of sizing from content.
+      const textStyles = [selectTextStyles(themeTokens, themeOptions), staticStyles.text];
+      const iconTokens = selectItemIconTokens(themeTokens);
+      const {
+        iconSpace
+      } = themeTokens; // If the container has a width set, fill it instead of sizing from content.
       // If in future we support text alignments other than center, add here.
 
       const stretchStyles = themeTokens.width ? staticStyles.stretch : staticStyles.align;
+      const IconComponent = icon || themeTokens.icon;
       return /*#__PURE__*/_jsx(View, {
         id: id,
         style: [containerStyles, borderStyles, stretchStyles, staticStyles.row, Platform.select({
@@ -230,10 +250,18 @@ const ButtonBase = /*#__PURE__*/forwardRef((_ref8, ref) => {
             transition: 'background-color 200ms, border-color 200ms'
           }
         })],
-        children: wrapStringsInText(typeof children === 'function' ? children({ ...resolvePressableState(pressableState, extraButtonState),
-          textStyles
-        }) : children, {
-          style: textStyles
+        children: /*#__PURE__*/_jsx(IconText, {
+          icon: IconComponent,
+          iconPosition: iconPosition,
+          space: iconSpace,
+          iconProps: { ...iconProps,
+            tokens: iconTokens
+          },
+          children: wrapStringsInText(typeof children === 'function' ? children({ ...resolvePressableState(pressableState, extraButtonState),
+            textStyles
+          }) : children, {
+            style: textStyles
+          })
         })
       });
     }

package/lib-module/Button/ButtonGroup.js

@@ -26,6 +26,7 @@ const ButtonGroup = /*#__PURE__*/forwardRef((_ref, ref) => {
     legend,
     tooltip,
     hint,
+    hintPosition = 'inline',
     validation,
     feedback,
     name: inputGroupName,
@@ -77,6 +78,7 @@ const ButtonGroup = /*#__PURE__*/forwardRef((_ref, ref) => {
     legend: legend,
     tooltip: tooltip,
     hint: hint,
+    hintPosition: hintPosition,
     space: fieldSpace,
     feedback: feedback,
     readOnly: readOnly,
@@ -208,6 +210,11 @@ ButtonGroup.propTypes = { ...selectedSystemPropTypes,
    */
   hint: PropTypes.string,
 
+  /**
+   * Position of the hint relative to label. Use `below` to display a larger hint below the label.
+   */
+  hintPosition: PropTypes.oneOf(['inline', 'below']),
+
   /**
    * Optional tooltip text content to include alongside the legend and hint.
    */

package/lib-module/Button/propTypes.js

@@ -2,6 +2,7 @@ import PropTypes from 'prop-types';
 import ABBPropTypes from 'airbnb-prop-types';
 import { variantProp, getTokensPropType } from '../utils/props';
 import A11yText from '../A11yText';
+import { iconComponentPropTypes } from '../Icon';
 export const textAndA11yText = ABBPropTypes.childrenOf(PropTypes.oneOfType([ABBPropTypes.elementType(A11yText), PropTypes.string]));
 const buttonPropTypes = {
   tokens: getTokensPropType('Button'),
@@ -31,6 +32,22 @@ const buttonPropTypes = {
    * Function called when the button is pressed. Required unless the button has a href.
    */
   onPress: PropTypes.func,
+
+  /**
+   * Optional variant that may be passed down to the link's icon if there is one
+   */
+  iconProps: PropTypes.exact(iconComponentPropTypes),
+
+  /**
+   * When `icon` is provided, use `iconPosition` to place the Icon to the left or right side of the button.
+   */
+  iconPosition: PropTypes.oneOf(['left', 'right']),
+
+  /**
+   * A function component for an SVG icon to render inside the link. Inherits size and color from
+   * the link and any Typography the link is nested inside.
+   */
+  icon: PropTypes.func,
   variant: variantProp.propType
 };
 export default buttonPropTypes;

package/lib-module/Carousel/Carousel.js

@@ -7,12 +7,15 @@ import Platform from "react-native-web/dist/exports/Platform";
 import PropTypes from 'prop-types';
 import { useThemeTokens } from '../ThemeProvider';
 import { useViewport } from '../ViewportProvider';
-import { getTokensPropType, getA11yPropsFromHtmlTag, layoutTags, variantProp, selectSystemProps, a11yProps, viewProps, useCopy } from '../utils';
+import { getTokensPropType, getA11yPropsFromHtmlTag, layoutTags, variantProp, selectSystemProps, a11yProps, viewProps, useCopy, unpackFragment } from '../utils';
 import { useA11yInfo } from '../A11yInfoProvider';
 import { CarouselProvider } from './CarouselContext';
 import CarouselItem from './CarouselItem';
 import IconButton from '../IconButton';
-import CarouselStepTracker from './CarouselStepTracker/CarouselStepTracker';
+import SkipLink from '../SkipLink';
+import A11yText from '../A11yText';
+import CarouselStepTracker from './CarouselStepTracker';
+import CarouselThumbnailNavigation from './CarouselThumbnailNavigation';
 import dictionary from './dictionary';
 import { jsx as _jsx } from "react/jsx-runtime";
 import { jsxs as _jsxs } from "react/jsx-runtime";
@@ -134,11 +137,18 @@ const Carousel = /*#__PURE__*/React.forwardRef((_ref, ref) => {
     onAnimationStart,
     onAnimationEnd,
     onIndexChanged,
+    skipLinkHref,
+    refocus,
+    title = 'carousel',
     springConfig = undefined,
-    panelNavigation = /*#__PURE__*/_jsx(CarouselStepTracker, {}),
+    thumbnails = undefined,
+    panelNavigation = thumbnails ? /*#__PURE__*/_jsx(CarouselThumbnailNavigation, {
+      thumbnails: thumbnails
+    }) : /*#__PURE__*/_jsx(CarouselStepTracker, {}),
     tag = 'ul',
-    accessibilityRole = 'adjustable',
-    accessibilityLabel = 'carousel',
+    accessibilityRole,
+    accessibilityLabel = title,
+    accessibilityLiveRegion = 'polite',
     copy,
     ...rest
   } = _ref;
@@ -167,7 +177,7 @@ const Carousel = /*#__PURE__*/React.forwardRef((_ref, ref) => {
     dictionary,
     copy
   });
-  const childrenArray = React.Children.toArray(children);
+  const childrenArray = unpackFragment(children);
   const systemProps = selectProps({ ...rest,
     accessibilityRole,
     accessibilityLabel,
@@ -186,6 +196,7 @@ const Carousel = /*#__PURE__*/React.forwardRef((_ref, ref) => {
     width: 0
   });
   const [previousNextNavigationButtonWidth, setPreviousNextNavigationButtonWidth] = React.useState(0);
+  const firstFocusRef = React.useRef(null);
   const pan = React.useRef(new Animated.ValueXY()).current;
   const animatedX = React.useRef(0);
   const animatedY = React.useRef(0);
@@ -285,10 +296,13 @@ const Carousel = /*#__PURE__*/React.forwardRef((_ref, ref) => {
     return calcDelta;
   }, [containerLayout.width, activeIndex, animate, children.length, onIndexChanged]);
   const fixOffsetAndGo = React.useCallback(delta => {
+    var _firstFocusRef$curren;
+
     updateOffset();
     handleAnimationStart(activeIndex);
     updateIndex(delta);
-  }, [updateIndex, updateOffset, activeIndex, handleAnimationStart]);
+    if (refocus) (_firstFocusRef$curren = firstFocusRef.current) === null || _firstFocusRef$curren === void 0 ? void 0 : _firstFocusRef$curren.focus();
+  }, [updateIndex, updateOffset, activeIndex, handleAnimationStart, refocus]);
   const goToNeighboring = React.useCallback(function () {
     let toPrev = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : false;
     fixOffsetAndGo(toPrev ? -1 : 1);
@@ -371,17 +385,20 @@ const Carousel = /*#__PURE__*/React.forwardRef((_ref, ref) => {
     raised: true
   };
   const getCopyWithPlaceholders = React.useCallback(copyKey => {
-    const copyText = getCopy(copyKey).replace(/%\{itemLabel\}/g, itemLabel).replace(/%\{stepNumber\}/g, activeIndex + 1).replace(/%\{stepCount\}/g, childrenArray.length); // First word might be a lowercase placeholder: capitalize the first letter
+    const copyText = getCopy(copyKey).replace(/%\{title\}/g, title).replace(/%\{itemLabel\}/g, itemLabel).replace(/%\{stepNumber\}/g, activeIndex + 1).replace(/%\{stepCount\}/g, childrenArray.length); // First word might be a lowercase placeholder: capitalize the first letter
 
     return "".concat(copyText[0].toUpperCase()).concat(copyText.slice(1));
-  }, [activeIndex, childrenArray.length, itemLabel, getCopy]);
+  }, [activeIndex, childrenArray.length, itemLabel, getCopy, title]);
   return /*#__PURE__*/_jsxs(CarouselProvider, {
     activeIndex: activeIndex,
-    totalItems: childrenArray.length,
-    width: containerLayout.width,
     goTo: goTo,
     getCopyWithPlaceholders: getCopyWithPlaceholders,
+    itemLabel: itemLabel,
+    totalItems: childrenArray.length,
     themeTokens: themeTokens,
+    firstFocusRef: firstFocusRef,
+    refocus: refocus,
+    width: containerLayout.width,
     children: [/*#__PURE__*/_jsxs(View, {
       style: staticStyles.root,
       onLayout: onContainerLayout,
@@ -397,6 +414,17 @@ const Carousel = /*#__PURE__*/React.forwardRef((_ref, ref) => {
           variant: previousNextIconButtonVariants,
           accessibilityLabel: getCopyWithPlaceholders('iconButtonLabel').replace('%{targetStep}', activeIndex)
         })
+      }), Boolean(skipLinkHref) && /*#__PURE__*/_jsx(SkipLink, {
+        ref: firstFocusRef,
+        href: skipLinkHref,
+        children: getCopyWithPlaceholders('skipLink')
+      }), /*#__PURE__*/_jsx(A11yText // Read the current slide position to screen readers on slide.
+      // If it's set to refocus and doesn't have a SkipLink to focus to, focus this.
+      , {
+        ref: !skipLinkHref && refocus ? firstFocusRef : null,
+        accessibilityLiveRegion: !skipLinkHref && refocus ? undefined : 'polite',
+        focusable: !skipLinkHref && refocus,
+        text: getCopyWithPlaceholders('stepTrackerLabel')
       }), /*#__PURE__*/_jsx(View, {
         style: selectContainerStyles(containerLayout.width),
         children: /*#__PURE__*/_jsx(Animated.View, {
@@ -409,6 +437,9 @@ const Carousel = /*#__PURE__*/React.forwardRef((_ref, ref) => {
           }]),
           ...panResponder.panHandlers,
           ...getA11yPropsFromHtmlTag(tag),
+          // In iframes on Mac (e.g. in Storybook), this content may be misread or read twice.
+          // This is a known Voiceover bug: https://github.com/phetsims/a11y-research/issues/132
+          accessibilityLiveRegion: accessibilityLiveRegion,
           children: childrenArray.map((element, index) => {
             const hidden = !isAnimating && index !== activeIndex;
             const clonedElement = /*#__PURE__*/React.cloneElement(element, {
@@ -468,6 +499,15 @@ Carousel.propTypes = { ...selectedSystemPropTypes,
    */
   springConfig: PropTypes.object,
 
+  /**
+   * An array of objects containing information on the thumbnails to be rendered as navigation panel
+   */
+  thumbnails: PropTypes.arrayOf(PropTypes.shape({
+    accessibilityLabel: PropTypes.string,
+    alt: PropTypes.string,
+    src: PropTypes.string
+  })),
+
   /**
    * Minimal part of slide width must be swiped for changing index.
    * Otherwise animation restore current slide. Default value 0.2 means that 20% must be swiped for change index
@@ -497,6 +537,21 @@ Carousel.propTypes = { ...selectedSystemPropTypes,
    */
   onIndexChanged: PropTypes.func,
 
+  /**
+   * If this is a complex carousel with a lot of focusable content, pass a href for a skip link. Typically, this will be an anchor link
+   * with the ID of a focusable element immediately after the Carousel, e.g. `'#section-2-heading'`.
+   */
+  skipLinkHref: PropTypes.string,
+
+  /**
+   * If true, whenever a new slide comes into view, the focus of the Carousel switches to the start.
+   *
+   * Pass this as true when using carousel items that contain interactive content, so a user can easily tab into that content.
+   *
+   * If skipLinkHref is passed, the focus target will be the SkipLink; if not, it'll be an empty element before the slide content.
+   */
+  refocus: PropTypes.bool,
+
   /**
    * Use this to render a custom panel navigation element instead of the default StepTracker's based navigation
    * You can make use of `useCarousel` within your custom panel navigation component to hook into various Carousel states such as: