@telus-uds/components-base 3.29.1 → 3.31.0

package/lib/cjs/Scroll/ScrollProgress.js

@@ -0,0 +1,99 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _react = _interopRequireDefault(require("react"));
+var _propTypes = _interopRequireDefault(require("prop-types"));
+var _View = _interopRequireDefault(require("react-native-web/dist/cjs/exports/View"));
+var _utils = require("../utils");
+var _Progress = _interopRequireDefault(require("../Progress"));
+var _jsxRuntime = require("react/jsx-runtime");
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+const MAX_PERCENTAGE = 100;
+const BORDER_RADIUS_DIVISOR = 2;
+const staticProgressTokens = {
+  borderWidth: 0,
+  borderColor: 'transparent'
+};
+const staticProgressBarTokens = {
+  gradient: null,
+  outlineWidth: 0
+};
+const selectProgressTokens = _ref => {
+  let {
+    progressTrackHeight,
+    progressBarHeight,
+    progressTrackColor
+  } = _ref;
+  return {
+    height: progressTrackHeight,
+    barHeight: progressBarHeight,
+    backgroundColor: progressTrackColor,
+    borderRadius: progressTrackHeight / BORDER_RADIUS_DIVISOR
+  };
+};
+const selectBarTokens = _ref2 => {
+  let {
+    progressBarColor,
+    progressBarHeight
+  } = _ref2;
+  return {
+    backgroundColor: progressBarColor,
+    borderRadius: progressBarHeight / BORDER_RADIUS_DIVISOR
+  };
+};
+const ScrollProgress = /*#__PURE__*/_react.default.forwardRef((_ref3, ref) => {
+  let {
+    pressableState,
+    getTokens,
+    thumbWrapperStyle,
+    getCopy
+  } = _ref3;
+  const state = (0, _utils.resolvePressableState)(pressableState);
+  const themeTokens = getTokens(state);
+  const animatedBarHeight = (0, _utils.useAnimatedValue)(themeTokens.progressBarHeight);
+  const animatedTokens = {
+    ...themeTokens,
+    progressBarHeight: animatedBarHeight
+  };
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)(_Progress.default, {
+    tokens: {
+      ...staticProgressTokens,
+      ...selectProgressTokens(animatedTokens)
+    },
+    children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_View.default, {
+      ref: ref,
+      style: thumbWrapperStyle,
+      children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_Progress.default.Bar, {
+        percentage: MAX_PERCENTAGE,
+        tokens: {
+          ...staticProgressBarTokens,
+          ...selectBarTokens(animatedTokens)
+        },
+        accessibilityLabel: getCopy('progressBarLabel')
+      })
+    })
+  });
+});
+ScrollProgress.displayName = 'ScrollProgress';
+ScrollProgress.propTypes = {
+  /**
+   * State object from Pressable's render callback containing hovered, pressed, and focused states
+   */
+  pressableState: _propTypes.default.object.isRequired,
+  /**
+   * Theme token resolver callback from useThemeTokensCallback that accepts appearance state
+   */
+  getTokens: _propTypes.default.func.isRequired,
+  /**
+   * Style array for the thumb wrapper containing static and dynamic position styles
+   */
+  thumbWrapperStyle: _propTypes.default.oneOfType([_propTypes.default.object, _propTypes.default.array]).isRequired,
+  /**
+   * Copy resolver function from useCopy for retrieving localized strings
+   */
+  getCopy: _propTypes.default.func.isRequired
+};
+var _default = exports.default = ScrollProgress;

package/lib/cjs/Scroll/dictionary.js

@@ -0,0 +1,18 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _default = exports.default = {
+  en: {
+    accessibilityLabel: 'Scrollable content',
+    instructionText: 'Use Tab, arrow keys, or space bar to navigate',
+    progressBarLabel: 'Scroll position'
+  },
+  fr: {
+    accessibilityLabel: 'Contenu défilable',
+    instructionText: "Utilisez Tab, les touches fléchées ou la barre d'espace pour naviguer",
+    progressBarLabel: 'Position de défilement'
+  }
+};

package/lib/cjs/Scroll/index.js

@@ -0,0 +1,29 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "ScrollItem", {
+  enumerable: true,
+  get: function () {
+    return _ScrollItem.default;
+  }
+});
+Object.defineProperty(exports, "ScrollProvider", {
+  enumerable: true,
+  get: function () {
+    return _ScrollContext.ScrollProvider;
+  }
+});
+exports.default = void 0;
+Object.defineProperty(exports, "useScroll", {
+  enumerable: true,
+  get: function () {
+    return _ScrollContext.useScroll;
+  }
+});
+var _Scroll = _interopRequireDefault(require("./Scroll"));
+var _ScrollItem = _interopRequireDefault(require("./ScrollItem"));
+var _ScrollContext = require("./ScrollContext");
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+var _default = exports.default = _Scroll.default;

package/lib/cjs/TextInput/TextInputBase.js

@@ -279,7 +279,8 @@ const TextInputBase = /*#__PURE__*/_react.default.forwardRef((_ref8, ref) => {
   }, [element, pattern]);
   const handleChangeText = event => {
     const text = event.nativeEvent?.text ?? event.target?.value;
-    let filteredText = isNumeric ? text?.replace(/[^\d]/g, '') || undefined : text;
+    // Do NOT use `|| undefined`: empty string is falsy and would break the controlled contract
+    let filteredText = isNumeric ? text?.replace(/[^\d]/g, '') ?? '' : text;
     if (type === 'card' && filteredText) {
       const formattedValue = filteredText.replace(/[^a-zA-Z0-9]/g, '');
       const regex = new RegExp(`([a-zA-Z0-9]{4})(?=[a-zA-Z0-9])`, 'g');

package/lib/cjs/index.js

@@ -57,6 +57,8 @@ var _exportNames = {
   RadioCard: true,
   RadioCardGroup: true,
   Responsive: true,
+  Scroll: true,
+  ScrollItem: true,
   Search: true,
   Select: true,
   Shortcuts: true,
@@ -422,6 +424,18 @@ Object.defineProperty(exports, "Responsive", {
     return _Responsive.default;
   }
 });
+Object.defineProperty(exports, "Scroll", {
+  enumerable: true,
+  get: function () {
+    return _Scroll.default;
+  }
+});
+Object.defineProperty(exports, "ScrollItem", {
+  enumerable: true,
+  get: function () {
+    return _Scroll.ScrollItem;
+  }
+});
 Object.defineProperty(exports, "Search", {
   enumerable: true,
   get: function () {
@@ -756,6 +770,7 @@ var _QuickLinksFeature = _interopRequireDefault(require("./QuickLinksFeature"));
 var _Radio = _interopRequireWildcard(require("./Radio"));
 var _RadioCard = _interopRequireWildcard(require("./RadioCard"));
 var _Responsive = _interopRequireDefault(require("./Responsive"));
+var _Scroll = _interopRequireWildcard(require("./Scroll"));
 var _Search = _interopRequireDefault(require("./Search"));
 var _Select = _interopRequireDefault(require("./Select"));
 var _Shortcuts = _interopRequireWildcard(require("./Shortcuts"));

package/lib/cjs/utils/animation/index.js

@@ -3,11 +3,18 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
+Object.defineProperty(exports, "useAnimatedValue", {
+  enumerable: true,
+  get: function () {
+    return _useAnimatedValue.default;
+  }
+});
 Object.defineProperty(exports, "useVerticalExpandAnimation", {
   enumerable: true,
   get: function () {
     return _useVerticalExpandAnimation.default;
   }
 });
+var _useAnimatedValue = _interopRequireDefault(require("./useAnimatedValue"));
 var _useVerticalExpandAnimation = _interopRequireDefault(require("./useVerticalExpandAnimation"));
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }

package/lib/cjs/utils/animation/useAnimatedValue.js

@@ -0,0 +1,46 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _react = _interopRequireDefault(require("react"));
+var _Animated = _interopRequireDefault(require("react-native-web/dist/cjs/exports/Animated"));
+var _Easing = _interopRequireDefault(require("react-native-web/dist/cjs/exports/Easing"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+const ANIMATION_DURATION = 200;
+
+/**
+ * Smoothly animates a numeric value to a new target using a quadratic ease-in-out
+ * curve. Returns the current interpolated value as a plain number so
+ * consumers can use it in non-Animated style props.
+ *
+ * @param {number} targetValue - The value to animate towards.
+ * @param {number} [duration=ANIMATION_DURATION] - Animation duration in ms.
+ */
+const useAnimatedValue = function (targetValue) {
+  let duration = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : ANIMATION_DURATION;
+  const [currentValue, setCurrentValue] = _react.default.useState(targetValue);
+  const animatedValue = _react.default.useRef(new _Animated.default.Value(targetValue)).current;
+  _react.default.useEffect(() => {
+    const id = animatedValue.addListener(_ref => {
+      let {
+        value
+      } = _ref;
+      return setCurrentValue(value);
+    });
+    return () => animatedValue.removeListener(id);
+  }, [animatedValue]);
+  _react.default.useEffect(() => {
+    const animation = _Animated.default.timing(animatedValue, {
+      toValue: targetValue,
+      duration,
+      easing: _Easing.default.inOut(_Easing.default.quad),
+      useNativeDriver: false
+    });
+    animation.start();
+    return () => animation.stop();
+  }, [targetValue, animatedValue, duration]);
+  return currentValue;
+};
+var _default = exports.default = useAnimatedValue;

package/lib/cjs/utils/children.js

@@ -54,7 +54,8 @@ const unpackFragment = child => {
 exports.unpackFragment = unpackFragment;
 const isStringOrNumber = child => typeof child === 'string' || typeof child === 'number';
 // Wrap an A11yText with neighouring text strings so it doesn't split them into multiple <Text>s
-const isWrapable = child => isStringOrNumber(child) || child.type === _A11yText.default || child.type?.name === 'FootnoteLink';
+// Check displayName first as it is explicitly set and reliable regardless of export style (named vs default)
+const isWrapable = child => isStringOrNumber(child) || child.type === _A11yText.default || child.type?.__UDS_COMPONENT_NAME__ === 'FootnoteLink';
 const combineKeys = childrenArray => childrenArray.reduce((newKey, child) => `${newKey}${child.key || ''}`, '');
 
 // Group wrappable children for one `<Text>` parent, merging adjacent text nodes

package/lib/cjs/utils/useOverlaidPosition.js

@@ -61,46 +61,45 @@ function getOverlaidPosition(_ref2) {
     offsets = {},
     align
   } = _ref2;
-  // Web-only: this will be difficult to mimic on native because there's no global scroll position.
-  // TODO: wire something in e.g. a scroll ref accessible from a provider included in Allium provider
-  // that can be passed to the appropriate ScrollView?
-  const {
-    scrollX = 0,
-    scrollY = 0
-  } = typeof window === 'object' ? window : {};
-
   // Will have top, bottom, left and/or right offsets depending on `align`
   const positioning = {};
   const verticalOffset = offsets.vertical ?? 0;
   const horizontalOffset = offsets.horizontal ?? 0;
   if (align.top) positioning.top = getPosition({
     edge: getEdgeType(align, 'top'),
-    fromEdge: sourceLayout.y + scrollY + verticalOffset,
+    fromEdge: sourceLayout.y + verticalOffset,
     sourceSize: sourceLayout.height
   });
   if (align.middle) positioning.top = getPosition({
     edge: getEdgeType(align, 'middle'),
-    fromEdge: sourceLayout.y + scrollY + verticalOffset - targetDimensions.height / 2,
-    sourceSize: sourceLayout.height
-  });
-  if (align.bottom) positioning.bottom = getPosition({
-    edge: getEdgeType(align, 'bottom'),
-    fromEdge: windowDimensions.height - (sourceLayout.y + scrollY + sourceLayout.height - verticalOffset),
+    fromEdge: sourceLayout.y + verticalOffset - targetDimensions.height / 2,
     sourceSize: sourceLayout.height
   });
+  if (align.bottom) {
+    if (_Platform.default.OS !== 'web') {
+      // On native, position:absolute is parent-relative, so use negative top offset instead of window-based bottom math.
+      positioning.top = sourceLayout.y - targetDimensions.height - verticalOffset;
+    } else {
+      positioning.bottom = getPosition({
+        edge: getEdgeType(align, 'bottom'),
+        fromEdge: windowDimensions.height - (sourceLayout.y + sourceLayout.height - verticalOffset),
+        sourceSize: sourceLayout.height
+      });
+    }
+  }
   if (align.left) positioning.left = getPosition({
     edge: getEdgeType(align, 'left'),
-    fromEdge: sourceLayout.x + scrollX + horizontalOffset,
+    fromEdge: sourceLayout.x + horizontalOffset,
     sourceSize: sourceLayout.width
   });
   if (align.center) positioning.left = getPosition({
     edge: getEdgeType(align, 'center'),
-    fromEdge: sourceLayout.x + scrollX + horizontalOffset - targetDimensions.width / 2,
+    fromEdge: sourceLayout.x + horizontalOffset - targetDimensions.width / 2,
     sourceSize: sourceLayout.width
   });
   if (align.right) positioning.right = getPosition({
     edge: getEdgeType(align, 'right'),
-    fromEdge: windowDimensions.width - (sourceLayout.x + scrollX + sourceLayout.width - horizontalOffset),
+    fromEdge: windowDimensions.width - (sourceLayout.x + sourceLayout.width - horizontalOffset),
     sourceSize: sourceLayout.width
   });
   if (!(align.left && align.right)) {
@@ -141,6 +140,32 @@ const useOverlaidPosition = _ref3 => {
   const targetRef = (0, _react.useRef)(null);
   const [targetDimensions, setTargetDimensions] = (0, _react.useState)(null);
   const [windowDimensions, setWindowDimensions] = (0, _react.useState)(null);
+  const hasRemeasuredRef = (0, _react.useRef)(false);
+  const applySourceLayout = (0, _react.useCallback)((dims, x, y, width, height) => {
+    setWindowDimensions(dims);
+    setSourceLayout({
+      x,
+      y,
+      width,
+      height
+    });
+  }, []);
+  const measureSourceOnWeb = (0, _react.useCallback)(windowDims => {
+    const el = sourceRef.current;
+    if (!el) return;
+    const domNode = el._nativeTag ?? el;
+    const dims = windowDims ?? _Dimensions.default.get('window');
+    const rect = typeof domNode.getBoundingClientRect === 'function' ? domNode.getBoundingClientRect() : null;
+    if (rect) {
+      const x = rect.left + (typeof window.scrollX === 'number' ? window.scrollX : 0);
+      const y = rect.top + (typeof window.scrollY === 'number' ? window.scrollY : 0);
+      applySourceLayout(dims, x, y, rect.width, rect.height);
+    } else {
+      el.measureInWindow((mx, my, width, height) => {
+        applySourceLayout(dims, mx, my, width, height);
+      });
+    }
+  }, [applySourceLayout]);
   const onTargetLayout = (0, _react.useCallback)(_ref4 => {
     let {
       nativeEvent: {
@@ -171,16 +196,19 @@ const useOverlaidPosition = _ref3 => {
       let {
         window
       } = _ref5;
-      const measurementFunction = _Platform.default.OS === 'web' ? 'measureInWindow' : 'measure';
-      sourceRef.current?.[measurementFunction]((x, y, width, height) => {
-        setWindowDimensions(window);
-        setSourceLayout({
-          x,
-          y,
-          width,
-          height
+      if (_Platform.default.OS === 'web') {
+        measureSourceOnWeb(window);
+      } else {
+        sourceRef.current?.measure((x, y, width, height) => {
+          setWindowDimensions(window);
+          setSourceLayout({
+            x,
+            y,
+            width,
+            height
+          });
         });
-      });
+      }
     };
     let subscription;
     const unsubscribe = () => {
@@ -193,6 +221,7 @@ const useOverlaidPosition = _ref3 => {
       }
       setSourceLayout(null);
       setTargetDimensions(null);
+      hasRemeasuredRef.current = false;
     };
     if (readyToShow) {
       subscription = _Dimensions.default.addEventListener('change', handleDimensionsChange);
@@ -203,36 +232,48 @@ const useOverlaidPosition = _ref3 => {
       unsubscribe();
     }
     return unsubscribe;
-  }, [readyToShow]);
+  }, [readyToShow, measureSourceOnWeb]);
+
+  // Re-measure source when targetDimensions first becomes available.
+  // Without this, there is a race condition: getBoundingClientRect() resolves faster than
+  // measureInWindow used to, so sourceLayout may be set before the dropdown has rendered
+  // and reported its dimensions via onTargetLayout. When targetDimensions finally arrives,
+  // sourceLayout is stale (no scroll has occurred to trigger handleScroll).
+  // Setting hasRemeasuredRef.current=true here also prevents the blink: isReady (on web)
+  // won't become true until this effect completes, guaranteeing the dropdown is always shown
+  // at its final correct position without an intermediate incorrect-position frame.
+  (0, _react.useEffect)(() => {
+    if (!isShown || !sourceRef.current || !targetDimensions || _Platform.default.OS !== 'web') return;
+    measureSourceOnWeb();
+    hasRemeasuredRef.current = true;
+  }, [targetDimensions, isShown, measureSourceOnWeb]);
   (0, _react.useEffect)(() => {
     if (_Platform.default.OS !== 'web') {
       return undefined;
     }
-    const handleScroll = (0, _lodash.default)(() => {
-      sourceRef.current?.measureInWindow((x, y, width, height) => {
-        setWindowDimensions(window);
-        setSourceLayout({
-          x,
-          y,
-          width,
-          height
-        });
-      });
-    }, DEBOUNCE_DELAY);
+    const handleScroll = (0, _lodash.default)(measureSourceOnWeb, DEBOUNCE_DELAY);
     window.addEventListener('scroll', handleScroll);
     return () => {
       window.removeEventListener('scroll', handleScroll);
       handleScroll.cancel();
     };
-  }, [sourceRef]);
-  const isReady = Boolean(isShown && sourceLayout && windowDimensions && targetDimensions);
+  }, [measureSourceOnWeb]);
+
+  // On web, require hasRemeasuredRef to be true before declaring isReady. This ensures
+  // the dropdown is never shown with an intermediate stale position (the blink).
+  // On native, hasRemeasuredRef stays false (the web-only effect never runs), so we skip
+  // that check to preserve the original native behaviour.
+  const isReady = Boolean(isShown && sourceLayout && windowDimensions && targetDimensions && (_Platform.default.OS !== 'web' || hasRemeasuredRef.current));
   const overlaidPosition = isReady ? getOverlaidPosition({
     sourceLayout,
     targetDimensions,
     windowDimensions,
     offsets,
     align
-  }) : {};
+  }) : {
+    top: 0,
+    left: 0
+  };
   return {
     overlaidPosition,
     sourceRef,

package/lib/esm/Autocomplete/Autocomplete.js

@@ -119,6 +119,7 @@ const Autocomplete = /*#__PURE__*/React.forwardRef((_ref2, ref) => {
     value,
     helpText = '',
     loadingLabel,
+    dropdownPosition = 'bottom',
     tokens,
     ...rest
   } = _ref2;
@@ -174,6 +175,13 @@ const Autocomplete = /*#__PURE__*/React.forwardRef((_ref2, ref) => {
     isShown: isExpanded || hintExpansionEnabled,
     offsets: {
       vertical: Platform.OS !== 'web' && (hint || inputLabel) ? 28 : 4
+    },
+    align: dropdownPosition === 'top' ? {
+      center: 'center',
+      bottom: 'top'
+    } : {
+      center: 'center',
+      top: 'bottom'
     }
   });
   const targetRef = React.useRef(null);
@@ -526,6 +534,10 @@ Autocomplete.propTypes = {
   /**
    * Input value for controlled usage
    */
-  value: PropTypes.string
+  value: PropTypes.string,
+  /**
+   * Controls whether the dropdown renders above or below the input. Defaults to 'bottom'.
+   */
+  dropdownPosition: PropTypes.oneOf(['top', 'bottom'])
 };
 export default Autocomplete;

package/lib/esm/Autocomplete/constants.js

@@ -1,5 +1,5 @@
 export const DEFAULT_MIN_TO_SUGGESTION = 1;
 export const DEFAULT_MAX_SUGGESTIONS = 5;
-export const DEFAULT_MAX_DROPDOWN_HEIGHT = 336; // Approximately 7 items (48px each)
+export const DEFAULT_MAX_DROPDOWN_HEIGHT = 500;
 export const INPUT_LEFT_PADDING = 16;
 export const MIN_LISTBOX_WIDTH = 288;

package/lib/esm/Carousel/Carousel.js

@@ -1170,9 +1170,14 @@ Carousel.propTypes = {
    * An array of objects containing information on the thumbnails to be rendered as navigation panel
    */
   thumbnails: PropTypes.arrayOf(PropTypes.shape({
+    /** Accessibility label for the thumbnail image, used by assistive technologies. */
     accessibilityLabel: PropTypes.string,
+    /** Alternative text for the thumbnail image, displayed when the image cannot be rendered. */
     alt: PropTypes.string,
-    src: PropTypes.string
+    /** When true, renders a play icon overlay on the thumbnail to indicate that the slide contains a video. */
+    isVideo: PropTypes.bool,
+    /** URL or path of the thumbnail image. When used with `isVideo`, this should be the video's poster/preview image. */
+    src: PropTypes.oneOfType([PropTypes.string, PropTypes.number])
   })),
   /**
    * Minimal part of slide width must be swiped for changing index.