@telus-uds/components-base 3.29.0 → 3.30.0

package/src/Scroll/ScrollProgress.jsx

@@ -0,0 +1,75 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+import { View } from 'react-native'
+
+import { resolvePressableState, useAnimatedValue } from '../utils'
+import Progress from '../Progress'
+
+const MAX_PERCENTAGE = 100
+const BORDER_RADIUS_DIVISOR = 2
+
+const staticProgressTokens = {
+  borderWidth: 0,
+  borderColor: 'transparent'
+}
+
+const staticProgressBarTokens = {
+  gradient: null,
+  outlineWidth: 0
+}
+
+const selectProgressTokens = ({ progressTrackHeight, progressBarHeight, progressTrackColor }) => ({
+  height: progressTrackHeight,
+  barHeight: progressBarHeight,
+  backgroundColor: progressTrackColor,
+  borderRadius: progressTrackHeight / BORDER_RADIUS_DIVISOR
+})
+
+const selectBarTokens = ({ progressBarColor, progressBarHeight }) => ({
+  backgroundColor: progressBarColor,
+  borderRadius: progressBarHeight / BORDER_RADIUS_DIVISOR
+})
+
+const ScrollProgress = React.forwardRef(
+  ({ pressableState, getTokens, thumbWrapperStyle, getCopy }, ref) => {
+    const state = resolvePressableState(pressableState)
+    const themeTokens = getTokens(state)
+    const animatedBarHeight = useAnimatedValue(themeTokens.progressBarHeight)
+    const animatedTokens = { ...themeTokens, progressBarHeight: animatedBarHeight }
+
+    return (
+      <Progress tokens={{ ...staticProgressTokens, ...selectProgressTokens(animatedTokens) }}>
+        <View ref={ref} style={thumbWrapperStyle}>
+          <Progress.Bar
+            percentage={MAX_PERCENTAGE}
+            tokens={{ ...staticProgressBarTokens, ...selectBarTokens(animatedTokens) }}
+            accessibilityLabel={getCopy('progressBarLabel')}
+          />
+        </View>
+      </Progress>
+    )
+  }
+)
+
+ScrollProgress.displayName = 'ScrollProgress'
+
+ScrollProgress.propTypes = {
+  /**
+   * State object from Pressable's render callback containing hovered, pressed, and focused states
+   */
+  pressableState: PropTypes.object.isRequired,
+  /**
+   * Theme token resolver callback from useThemeTokensCallback that accepts appearance state
+   */
+  getTokens: PropTypes.func.isRequired,
+  /**
+   * Style array for the thumb wrapper containing static and dynamic position styles
+   */
+  thumbWrapperStyle: PropTypes.oneOfType([PropTypes.object, PropTypes.array]).isRequired,
+  /**
+   * Copy resolver function from useCopy for retrieving localized strings
+   */
+  getCopy: PropTypes.func.isRequired
+}
+
+export default ScrollProgress

package/src/Scroll/dictionary.js

@@ -0,0 +1,12 @@
+export 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/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/StackView/StackWrapBox.jsx

@@ -58,6 +58,7 @@ const StackWrapBox = React.forwardRef(
       variant,
       tag,
       accessibilityRole,
+      itemAccessibilityRole,
       ...rest
     },
     ref
@@ -76,7 +77,12 @@ const StackWrapBox = React.forwardRef(
     const gapSize = useSpacingScale(gap)
     const offsetStyle = { [offsetSides[direction]]: -1 * gapSize }
     const boxProps = { [gapSides[direction]]: gap, [spaceSides[direction]]: space }
-    const content = getStackedContent(children, { direction, space: 0, box: boxProps })
+    const content = getStackedContent(children, {
+      direction,
+      space: 0,
+      box: boxProps,
+      itemAccessibilityRole
+    })
 
     return (
       <View
@@ -119,6 +125,12 @@ StackWrapBox.propTypes = {
    * is not defined, the accessibilityRole will default to "heading".
    */
   tag: PropTypes.oneOf(layoutTags),
+  /**
+   * Optional accessibility role to apply to each item in the stack.
+   * On web, items are wrapped (or cloned) with this role, enabling correct list semantics
+   * when the container tag is "ul" or "ol".
+   */
+  itemAccessibilityRole: PropTypes.string,
   /**
    * A StackWrap may take any children, but will have no effect if it is only passed one child or is passed children
    * wrapped in a component. If necessary, children may be wrapped in one React Fragment.

package/src/StackView/StackWrapGap.jsx

@@ -37,6 +37,7 @@ const StackWrapGap = React.forwardRef(
       children,
       tag,
       accessibilityRole,
+      itemAccessibilityRole,
       ...rest
     },
     ref
@@ -54,7 +55,7 @@ const StackWrapGap = React.forwardRef(
     const size = useSpacingScale(space)
     const gapStyle = { gap: size }
 
-    const content = getStackedContent(children, { direction, space: 0 })
+    const content = getStackedContent(children, { direction, space: 0, itemAccessibilityRole })
 
     return (
       <View

package/src/StackView/getStackedContent.jsx

@@ -32,7 +32,7 @@ import Spacer from '../Spacer'
  */
 const getStackedContent = (
   children,
-  { divider, space, direction = 'column', box, preserveFragments = false }
+  { divider, space, direction = 'column', box, preserveFragments = false, itemAccessibilityRole }
 ) => {
   const boxProps = box && typeof box === 'object' ? box : { space }
   const dividerProps = divider && typeof divider === 'object' ? divider : {}
@@ -42,15 +42,29 @@ const getStackedContent = (
   const validChildren = React.Children.toArray(topLevelChildren).filter(Boolean)
   const content = validChildren.reduce((newChildren, child, index) => {
     const boxID = `Stack-Box-${index}`
-    const item = box ? (
+
+    let item
+    if (box) {
       // If wrapped in Box, that Box needs a key.
       // If possible, use an existing content key; use an index-based key only if necessary.
-      <Box {...boxProps} key={child.key || boxID} testID={boxID}>
-        {child}
-      </Box>
-    ) : (
-      child
-    )
+      item = (
+        <Box
+          {...boxProps}
+          accessibilityRole={itemAccessibilityRole}
+          key={child.key || boxID}
+          testID={boxID}
+        >
+          {child}
+        </Box>
+      )
+    } else if (itemAccessibilityRole) {
+      item = React.cloneElement(child, {
+        accessibilityRole: itemAccessibilityRole,
+        key: child.key || boxID
+      })
+    } else {
+      item = child
+    }
     if (!index || (!space && !divider)) return [...newChildren, item]
 
     const testID = `Stack-${divider ? 'Divider' : 'Spacer'}-${index}`

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/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'