@telus-uds/components-base 3.29.1 → 3.31.0

package/src/Scroll/index.js

@@ -0,0 +1,5 @@
+import Scroll from './Scroll'
+
+export default Scroll
+export { default as ScrollItem } from './ScrollItem'
+export { ScrollProvider, useScroll } from './ScrollContext'

package/src/TextInput/TextInputBase.jsx

@@ -256,7 +256,8 @@ const TextInputBase = React.forwardRef(
 
     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/src/index.js

@@ -49,6 +49,7 @@ export { default as QuickLinksFeature } from './QuickLinksFeature'
 export { default as Radio, RadioGroup } from './Radio'
 export { default as RadioCard, RadioCardGroup } from './RadioCard'
 export { default as Responsive } from './Responsive'
+export { default as Scroll, ScrollItem } from './Scroll'
 export { default as Search } from './Search'
 export { default as Select } from './Select'
 export { default as Shortcuts, ShortcutsItem } from './Shortcuts'

package/src/utils/animation/index.js

@@ -1,2 +1,2 @@
-/* eslint-disable import/prefer-default-export */
+export { default as useAnimatedValue } from './useAnimatedValue'
 export { default as useVerticalExpandAnimation } from './useVerticalExpandAnimation'

package/src/utils/animation/useAnimatedValue.js

@@ -0,0 +1,37 @@
+import React from 'react'
+import { Animated, Easing } from 'react-native'
+
+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 = (targetValue, duration = ANIMATION_DURATION) => {
+  const [currentValue, setCurrentValue] = React.useState(targetValue)
+  const animatedValue = React.useRef(new Animated.Value(targetValue)).current
+
+  React.useEffect(() => {
+    const id = animatedValue.addListener(({ value }) => setCurrentValue(value))
+    return () => animatedValue.removeListener(id)
+  }, [animatedValue])
+
+  React.useEffect(() => {
+    const animation = Animated.timing(animatedValue, {
+      toValue: targetValue,
+      duration,
+      easing: Easing.inOut(Easing.quad),
+      useNativeDriver: false
+    })
+    animation.start()
+    return () => animation.stop()
+  }, [targetValue, animatedValue, duration])
+
+  return currentValue
+}
+
+export default useAnimatedValue

package/src/utils/children.jsx

@@ -47,8 +47,11 @@ export const unpackFragment = (child) => {
 
 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
+// 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 || child.type?.name === 'FootnoteLink'
+  isStringOrNumber(child) ||
+  child.type === A11yText ||
+  child.type?.__UDS_COMPONENT_NAME__ === 'FootnoteLink'
 const combineKeys = (childrenArray) =>
   childrenArray.reduce((newKey, child) => `${newKey}${child.key || ''}`, '')
 

package/src/utils/useOverlaidPosition.js

@@ -54,11 +54,6 @@ function getOverlaidPosition({
   offsets = {},
   align
 }) {
-  // 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 = {}
 
@@ -68,40 +63,44 @@ function getOverlaidPosition({
   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.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
     })
 
@@ -149,6 +148,34 @@ const useOverlaidPosition = ({
 
   const [windowDimensions, setWindowDimensions] = useState(null)
 
+  const hasRemeasuredRef = useRef(false)
+
+  const applySourceLayout = useCallback((dims, x, y, width, height) => {
+    setWindowDimensions(dims)
+    setSourceLayout({ x, y, width, height })
+  }, [])
+
+  const measureSourceOnWeb = useCallback(
+    (windowDims) => {
+      const el = sourceRef.current
+      if (!el) return
+      const domNode = el._nativeTag ?? el
+      const dims = windowDims ?? Dimensions.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 = useCallback(
     ({
       nativeEvent: {
@@ -173,12 +200,14 @@ const useOverlaidPosition = ({
   const readyToShow = Boolean(isShown && sourceRef.current)
   useEffect(() => {
     const handleDimensionsChange = ({ window }) => {
-      const measurementFunction = Platform.OS === 'web' ? 'measureInWindow' : 'measure'
-
-      sourceRef.current?.[measurementFunction]((x, y, width, height) => {
-        setWindowDimensions(window)
-        setSourceLayout({ x, y, width, height })
-      })
+      if (Platform.OS === 'web') {
+        measureSourceOnWeb(window)
+      } else {
+        sourceRef.current?.measure((x, y, width, height) => {
+          setWindowDimensions(window)
+          setSourceLayout({ x, y, width, height })
+        })
+      }
     }
 
     let subscription
@@ -192,6 +221,7 @@ const useOverlaidPosition = ({
       }
       setSourceLayout(null)
       setTargetDimensions(null)
+      hasRemeasuredRef.current = false
     }
 
     if (readyToShow) {
@@ -202,19 +232,29 @@ const useOverlaidPosition = ({
     }
 
     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.
+  useEffect(() => {
+    if (!isShown || !sourceRef.current || !targetDimensions || Platform.OS !== 'web') return
+
+    measureSourceOnWeb()
+    hasRemeasuredRef.current = true
+  }, [targetDimensions, isShown, measureSourceOnWeb])
 
   useEffect(() => {
     if (Platform.OS !== 'web') {
       return undefined
     }
 
-    const handleScroll = debounce(() => {
-      sourceRef.current?.measureInWindow((x, y, width, height) => {
-        setWindowDimensions(window)
-        setSourceLayout({ x, y, width, height })
-      })
-    }, DEBOUNCE_DELAY)
+    const handleScroll = debounce(measureSourceOnWeb, DEBOUNCE_DELAY)
 
     window.addEventListener('scroll', handleScroll)
 
@@ -222,9 +262,19 @@ const useOverlaidPosition = ({
       window.removeEventListener('scroll', handleScroll)
       handleScroll.cancel()
     }
-  }, [sourceRef])
+  }, [measureSourceOnWeb])
 
-  const isReady = Boolean(isShown && sourceLayout && windowDimensions && targetDimensions)
+  // 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.OS !== 'web' || hasRemeasuredRef.current)
+  )
 
   const overlaidPosition = isReady
     ? getOverlaidPosition({
@@ -234,7 +284,7 @@ const useOverlaidPosition = ({
         offsets,
         align
       })
-    : {}
+    : { top: 0, left: 0 }
 
   return {
     overlaidPosition,

package/types/Scroll.d.ts

@@ -0,0 +1,66 @@
+import type { ComponentType, ReactNode } from 'react'
+import type { SemanticTag } from './Common'
+
+export interface ScrollDictionary {
+  accessibilityLabel: string
+  instructionText: string
+  progressBarLabel: string
+}
+
+export interface ScrollProps {
+  /**
+   * Scroll items to display. Should be `ScrollItem` components.
+   */
+  children: ReactNode
+  /**
+   * Theme tokens for customizing the Scroll appearance.
+   */
+  tokens?: ScrollTokens
+  /**
+   * Variant for the Scroll component.
+   */
+  variant?: ScrollVariant
+  /**
+   * Select English or French copy for accessible labels.
+   */
+  copy?: 'en' | 'fr'
+  /**
+   * Override the default dictionary by passing the complete dictionary object for `en` and `fr`.
+   */
+  dictionary?: {
+    en: ScrollDictionary
+    fr: ScrollDictionary
+  }
+  /**
+   * Accessibility label for the scrollable region.
+   */
+  accessibilityLabel?: string
+}
+
+export type ScrollVariant = {}
+
+export interface ScrollTokens {
+  itemGap?: number
+  progressBarColor?: string
+  progressBarHeight?: number
+  progressHitAreaHeight?: number
+  progressSpacing?: number
+  progressTrackColor?: string
+  progressTrackHeight?: number
+}
+
+export interface ScrollItemProps {
+  /**
+   * Content of the scroll item.
+   */
+  children: ReactNode
+  /**
+   * Sets the HTML tag of the outer container. Defaults to `'li'`.
+   */
+  tag?: SemanticTag
+}
+
+declare const Scroll: ComponentType<ScrollProps>
+export declare const ScrollItem: ComponentType<ScrollItemProps>
+
+export default Scroll

package/types/index.d.ts

@@ -45,6 +45,15 @@ export { LinkProps, LinkSize, LinkAndTextButtonVariants, LinkTokens } from './Li
 export { default as List } from './List'
 export { ListVariants, ListTokens, ListProps, ListItemProps, ListItemTokens } from './List'
 
+export { default as Scroll, ScrollItem } from './Scroll'
+export type {
+  ScrollProps,
+  ScrollTokens,
+  ScrollVariant,
+  ScrollItemProps,
+  ScrollDictionary
+} from './Scroll'
+
 export { default as Search } from './Search'
 export { SearchTokens, SearchProps } from './Search'