@telus-uds/components-base 4.0.0-alpha.2 → 4.0.0-beta.1

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 @@ export 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 @@ export 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 @@ export const useOverlaidPosition = ({
       }
       setSourceLayout(null)
       setTargetDimensions(null)
+      hasRemeasuredRef.current = false
     }
 
     if (readyToShow) {
@@ -202,19 +232,29 @@ export 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 @@ export 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 @@ export const useOverlaidPosition = ({
         offsets,
         align
       })
-    : {}
+    : { top: 0, left: 0 }
 
   return {
     overlaidPosition,

package/types/A11yInfoProvider.d.ts

@@ -0,0 +1,9 @@
+import type { ComponentType, ReactNode } from 'react'
+
+export interface A11yInfoProviderProps {
+  children: ReactNode
+}
+
+declare const A11yInfoProvider: ComponentType<A11yInfoProviderProps>
+
+export { A11yInfoProvider }

package/types/A11yText.d.ts

@@ -0,0 +1,13 @@
+import type { ComponentType } from 'react'
+
+export interface A11yTextProps {
+  text: string
+  heading?: boolean
+  role?: string
+  testID?: string
+  dataSet?: Record<string, any>
+}
+
+declare const A11yText: ComponentType<A11yTextProps>
+
+export { A11yText }

package/types/ActionCard.d.ts

@@ -0,0 +1,19 @@
+import type { ComponentType, ReactNode } from 'react'
+
+export interface ActionCardProps {
+  icon?: ComponentType<any>
+  title?: string
+  children?: ReactNode
+  href?: string
+  direction?: boolean
+  accessibilityRole?: string
+  tokens?: Record<string, string | number | boolean | object>
+  variant?: Record<string, string | number | boolean | undefined>
+  testID?: string
+  dataSet?: Record<string, any>
+  onPress?: () => void
+}
+
+declare const ActionCard: ComponentType<ActionCardProps>
+
+export { ActionCard }

package/types/ActivityIndicator.d.ts

@@ -0,0 +1,13 @@
+import type { ComponentType } from 'react'
+
+export interface ActivityIndicatorProps {
+  tokens?: Record<string, string | number | boolean | object>
+  variant?: Record<string, string | number | boolean | undefined>
+  testID?: string
+  dataSet?: Record<string, any>
+  accessibilityLabel?: string
+}
+
+declare const ActivityIndicator: ComponentType<ActivityIndicatorProps>
+
+export { ActivityIndicator }

package/types/Autocomplete.d.ts

@@ -0,0 +1,27 @@
+import type { ComponentType, ReactNode } from 'react'
+
+export interface AutocompleteItem {
+  id: string
+  label: string
+  value?: string
+}
+
+export interface AutocompleteProps {
+  children?: (props: Record<string, any>) => ReactNode
+  tokens?: Record<string, string | number | boolean | object>
+  copy?: 'en' | 'fr'
+  items?: AutocompleteItem[]
+  value?: string
+  onChange?: (value: string) => void
+  onSearch?: (value: string) => void
+  onSelect?: (item: AutocompleteItem) => void
+  loading?: boolean
+  loadingMessage?: string
+  emptyText?: string
+  testID?: string
+  dataSet?: Record<string, any>
+}
+
+declare const Autocomplete: ComponentType<AutocompleteProps>
+
+export { Autocomplete }

package/types/Badge.d.ts

@@ -1,10 +1,17 @@
+import type { ComponentType, ReactNode } from 'react'
+
 export interface BadgeProps {
-  text: string
-  borderColor?: string
-  textColor?: string
+  children?: ReactNode
+  variant?: BadgeVariants
+  tokens?: BadgeTokens
+  pointerEvents?: 'all' | 'none' | 'box-only' | 'box-none'
+  onLayout?: (event: any) => void
+  nativeID?: string
+  testID?: string
+  dataSet?: Record<string, any>
 }
 
-type BadgeVariants = {
+export type BadgeVariants = {
   alternative?: boolean
   inverse?: boolean
   outline?: boolean
@@ -26,3 +33,7 @@ export type BadgeTokens = {
   paddingRight?: number
   paddingTop?: number
 }
+
+declare const Badge: ComponentType<BadgeProps>
+
+export { Badge }

package/types/BaseProvider.d.ts

@@ -0,0 +1,26 @@
+import type { ComponentType, ReactNode } from 'react'
+
+export interface ThemeMetadata {
+  themeTokensVersion: string
+  name: string
+}
+
+export interface Theme {
+  metadata: ThemeMetadata
+}
+
+export interface ThemeOptions {
+  forceAbsoluteFontSizing?: boolean
+  forceZIndex?: boolean
+  defaultViewport?: 'xs' | 'sm' | 'md' | 'lg' | 'xl'
+}
+
+export interface BaseProviderProps {
+  children: ReactNode
+  defaultTheme: Theme
+  themeOptions?: ThemeOptions
+}
+
+declare const BaseProvider: ComponentType<BaseProviderProps>
+
+export { BaseProvider }

package/types/Box.d.ts

@@ -1,8 +1,8 @@
-import { ReactNode, ReactElement } from 'react'
+import type { ComponentType, ReactNode, ReactElement } from 'react'
 import { ScrollViewProps } from 'react-native'
 import { ResponsiveSpacing, SemanticTag } from './Common'
 
-type BoxVariants = {
+export type BoxVariants = {
   background?:
     | 'lightest'
     | 'lighter'
@@ -21,7 +21,7 @@ type BoxVariants = {
     | 'featureBrand'
 }
 
-type BoxTokens = {
+export type BoxTokens = {
   backgroundColor?: string
   gradient?: string
   borderWidth?: number
@@ -49,4 +49,14 @@ export interface BoxProps {
   testID?: string
   accessibilityLabel?: string
   accessible?: boolean
+  customGradient?: (...args: any[]) => ReactNode
+  backgroundImage?: any
+  pointerEvents?: 'all' | 'none' | 'box-only' | 'box-none'
+  onLayout?: (event: any) => void
+  nativeID?: string
+  dataSet?: Record<string, any>
 }
+
+declare const Box: ComponentType<BoxProps>
+
+export { Box }

package/types/Button.d.ts

@@ -0,0 +1,35 @@
+import type { ComponentType, ReactNode } from 'react'
+import { IconProps } from './Icon'
+
+export interface ButtonProps {
+  children: ReactNode | ((state: ButtonPressableState) => ReactNode)
+  onPress?: () => void
+  inactive?: boolean
+  disabled?: boolean
+  heightFull?: boolean
+  iconPosition?: 'left' | 'right'
+  icon?: ComponentType<any>
+  iconProps?: IconProps
+  tokens?: Record<string, string | number | boolean | object>
+  variant?: Record<string, string | number | boolean | undefined>
+  accessibilityLabel?: string
+  accessibilityRole?: string
+  accessible?: boolean
+  testID?: string
+  dataSet?: Record<string, any>
+  href?: string
+  hrefAttrs?: Record<string, string>
+}
+
+export type ButtonPressableState = {
+  hovered: boolean
+  focused: boolean
+  pressed: boolean
+  inactive: boolean
+  selected: boolean
+  textStyles: Record<string, any>
+}
+
+declare const Button: ComponentType<ButtonProps>
+
+export { Button }

package/types/Card.d.ts

@@ -0,0 +1,19 @@
+import type { ComponentType, ReactNode } from 'react'
+
+export interface CardProps {
+  children?: ReactNode
+  tokens?: Record<string, string | number | boolean | object>
+  variant?: Record<string, string | number | boolean | undefined>
+  onPress?: () => void
+  id?: string
+  interactiveCard?: Record<string, any>
+  backgroundImage?: any
+  testID?: string
+  dataSet?: Record<string, any>
+  accessibilityLabel?: string
+  accessibilityRole?: string
+}
+
+declare const Card: ComponentType<CardProps>
+
+export { Card }

package/types/CardGroup.d.ts

@@ -0,0 +1,23 @@
+import type { ComponentType, ReactNode } from 'react'
+
+export interface CardGroupItem {
+  id: string
+  image?: Record<string, any>
+  dictionary?: Record<string, any>
+  [key: string]: any
+}
+
+export interface CardGroupProps {
+  copy?: 'en' | 'fr'
+  dictionary?: Record<string, any>
+  tokens?: Record<string, string | number | boolean | object>
+  variant?: Record<string, string | number | boolean | undefined>
+  items?: CardGroupItem[]
+  children?: ReactNode
+  testID?: string
+  dataSet?: Record<string, any>
+}
+
+declare const CardGroup: ComponentType<CardGroupProps>
+
+export { CardGroup }

package/types/Carousel.d.ts

@@ -0,0 +1,25 @@
+import type { ComponentType, ReactNode } from 'react'
+
+export interface CarouselProps {
+  children: ReactNode
+  tokens?: Record<string, string | number | boolean | object>
+  variant?: Record<string, string | number | boolean | undefined>
+  stepTrackerVariant?: Record<string, string | number | boolean | undefined>
+  progressBarVariant?: Record<string, string | number | boolean | undefined>
+  itemLabel?: string
+  previousNextNavigationPosition?: 'inside' | 'outside' | 'edge'
+  copy?: 'en' | 'fr'
+  testID?: string
+  dataSet?: Record<string, any>
+  accessibilityLabel?: string
+}
+
+export interface CarouselItemProps {
+  children: ReactNode
+}
+
+declare const Carousel: ComponentType<CarouselProps> & {
+  Item: ComponentType<CarouselItemProps>
+}
+
+export { Carousel }

package/types/Checkbox.d.ts

@@ -1,6 +1,7 @@
+import type { ComponentType } from 'react'
 import { StyleProp, ViewStyle, TextStyle } from 'react-native'
 
-type CheckboxTokens = {
+export type CheckboxTokens = {
   containerBackgroundColor?: string
   feedbackMarginBottom?: number
   feedbackMarginTop?: number
@@ -33,7 +34,7 @@ type CheckboxTokens = {
   descriptionFontColor?: string
 }
 
-type CheckboxProps = {
+export type CheckboxProps = {
   checked?: boolean
   defaultChecked?: boolean
   error?: boolean
@@ -50,4 +51,16 @@ type CheckboxProps = {
   style?: StyleProp<ViewStyle>
   labelStyle?: StyleProp<TextStyle>
   containerStyle?: StyleProp<ViewStyle>
+  pointerEvents?: 'all' | 'none' | 'box-only' | 'box-none'
+  onLayout?: (event: any) => void
+  nativeID?: string
+  testID?: string
+  dataSet?: Record<string, any>
+  accessibilityLabel?: string
+  accessibilityRole?: string
+  accessible?: boolean
 }
+
+declare const Checkbox: ComponentType<CheckboxProps>
+
+export { Checkbox }

package/types/CheckboxCard.d.ts

@@ -0,0 +1,20 @@
+import type { ComponentType, ReactNode } from 'react'
+
+export interface CheckboxCardProps {
+  title?: string
+  children?: ReactNode | ((state: Record<string, any>) => ReactNode)
+  checked?: boolean
+  defaultChecked?: boolean
+  inactive?: boolean
+  id?: string
+  onChange?: (checked: boolean) => void
+  tokens?: Record<string, string | number | boolean | object>
+  variant?: Record<string, string | number | boolean | undefined>
+  testID?: string
+  dataSet?: Record<string, any>
+  accessibilityLabel?: string
+}
+
+declare const CheckboxCard: ComponentType<CheckboxCardProps>
+
+export { CheckboxCard }

package/types/CheckboxCardGroup.d.ts

@@ -1,7 +1,7 @@
-import * as React from 'react'
+import type { ComponentType } from 'react'
 import { Direction, ResponsiveDirection } from './Common'
 
-type CheckboxCardGroupProps = {
+export type CheckboxCardGroupProps = {
   copy?: 'en' | 'fr'
   variant?: 'fullWidth'
   legend?: string
@@ -15,9 +15,11 @@ type CheckboxCardGroupProps = {
   onChange?: (checkedIds: string[]) => void
   readOnly?: boolean
   inactive?: boolean
+  items?: any[]
+  name?: string
 }
 
-type CheckboxCardGroupTokens = {
+export type CheckboxCardGroupTokens = {
   borderBottomLeftRadius?: number
   borderBottomRightRadius?: number
   borderTopLeftRadius?: number
@@ -30,7 +32,7 @@ type CheckboxCardGroupTokens = {
   space?: number
 }
 
-type checkboxCardTokens = {
+export type CheckboxCardTokens = {
   outerBorderColer?: string
   outerBorderWidth?: number
   outerBorderGap?: number
@@ -70,3 +72,7 @@ type checkboxCardTokens = {
   checkboxSpace?: number
   contentSpace?: number
 }
+
+declare const CheckboxCardGroup: ComponentType<CheckboxCardGroupProps>
+
+export { CheckboxCardGroup }

package/types/ChevronLink.d.ts

@@ -1,7 +1,8 @@
+import type { ComponentType, ReactNode } from 'react'
 import { IconProps, IconPositionLeftRight } from './Icon'
 import { LinkAndTextButtonVariants } from './Link'
 
-type ChevronLinkTokens = {
+export type ChevronLinkTokens = {
   fontSize?: number
   color?: string
   outerBorderColor?: string
@@ -24,9 +25,10 @@ type ChevronLinkTokens = {
   iconTranslateY?: number
   alignSelf?: 'auto' | 'flex-start' | 'flex-end' | 'center' | 'stretch' | 'baseline'
 }
+
 export interface ChevronLinkProps {
   testID?: string
-  children?: React.ReactNode
+  children?: ReactNode
   onPress?: () => void
   onPressIn?: () => void
   onPressOut?: () => void
@@ -38,6 +40,7 @@ export interface ChevronLinkProps {
   tokens?: ChevronLinkTokens
   direction?: IconPositionLeftRight
   variant?: LinkAndTextButtonVariants
+  dataSet?: Record<string, any>
 }
 
 export interface HrefProps {
@@ -45,3 +48,7 @@ export interface HrefProps {
   rel: string
   target: string
 }
+
+declare const ChevronLink: ComponentType<ChevronLinkProps>
+
+export { ChevronLink }

package/types/ColourToggle.d.ts

@@ -0,0 +1,16 @@
+import type { ComponentType } from 'react'
+
+export interface ColourToggleProps {
+  id?: string
+  colourHexCode?: string
+  colourName?: string
+  isSelected?: boolean
+  tokens?: Record<string, string | number | boolean | object>
+  onPress?: () => void
+  testID?: string
+  dataSet?: Record<string, any>
+}
+
+declare const ColourToggle: ComponentType<ColourToggleProps>
+
+export { ColourToggle }

package/types/Common.d.ts

@@ -72,7 +72,7 @@ export type SemanticTag =
   | 'section'
   | 'label'
 
-type headingType = {
+export type headingType = {
   H1: 'h1'
   H2: 'h2'
   H3: 'h1'
@@ -81,7 +81,7 @@ type headingType = {
   H6: 'h2'
 }
 
-type tagType = {
+export type tagType = {
   HEADING: headingType
   BLOCKQUOTE: 'blockquote'
   CODE: 'code'
@@ -93,7 +93,7 @@ type tagType = {
   LABEL: 'label'
 }
 
-type alignType = {
+export type alignType = {
   AUTO: 'auto'
   LEFT: 'left'
   RIGHT: 'right'
@@ -104,3 +104,7 @@ type alignType = {
 export type FlexAlign = 'flex-start' | 'flex-end' | 'center' | 'stretch' | 'baseline'
 
 export type FlexJustify = 'flex-start' | 'flex-end' | 'center' | 'space-between' | 'space-around'
+
+export type TextAlign = 'auto' | 'left' | 'right' | 'center' | 'justify'
+
+export type Variant = Record<string, string | number | boolean | undefined>