@telus-uds/components-base 2.0.0 → 2.0.1

package/src/utils/ssr-media-query/utils/inject.js

@@ -0,0 +1,43 @@
+import React from 'react'
+import { Platform } from 'react-native'
+
+const rules = {}
+let styleSheet
+
+if (typeof window !== 'undefined' && typeof document !== 'undefined') {
+  styleSheet = (() => {
+    const style = document.createElement('style')
+    style.id = 'RNMQCSS'
+    style.appendChild(document.createTextNode(''))
+    document.head.appendChild(style)
+    return style.sheet
+  })()
+}
+export const hasCss = (id, text) => {
+  return !!rules[id] && !!rules[id].text?.includes?.(text)
+}
+
+export const addCss = (id, text) => {
+  if (!hasCss(id, text)) {
+    rules[id] = rules?.[id] || {}
+    rules[id].text = (rules[id]?.text || '') + text
+    if (styleSheet) {
+      styleSheet.insertRule(text, Object.keys(rules).length - 1)
+    }
+  }
+}
+
+export const flush = () => {
+  if (Platform.OS === 'web') {
+    return React.createElement('style', {
+      id: 'rnmq',
+      key: 'rnmq',
+      dangerouslySetInnerHTML: {
+        __html: Object.keys(rules)
+          .map((key) => rules[key].text)
+          .join('\n')
+      }
+    })
+  }
+  return {}
+}

package/src/utils/ssr.jsx

@@ -1,5 +1,6 @@
 import React from 'react'
 import { AppRegistry } from 'react-native'
+import { flush } from './ssr-media-query/utils/inject'
 /** @typedef {import('react').ComponentType} ReactComponent */
 /** @typedef {import('react').ReactElement} ReactElement */
 
@@ -80,7 +81,8 @@ export const ssrStyles = (appName = 'UDS app', { styleGetters = [], collectStyle
      */
     getStyles: (...existingStyles) => {
       if (!hasAppRendered) throw new Error('Called getStyles before renderApp in ssrStyles')
-      return [...existingStyles, ...styleGetters.flatMap((getter) => getter())]
+
+      return [...existingStyles, ...styleGetters.flatMap((getter) => getter()), flush()]
     }
   }
 }

package/src/utils/transformGradient.js

@@ -0,0 +1,17 @@
+/**
+ * Transforms a gradient object into a CSS gradient string.
+ *
+ * @param {Object} gradient - The gradient object to transform.
+ * @param {string} gradient.type - The type of gradient (linear or radial).
+ * @param {number} gradient.angle - The angle of the linear gradient in degrees.
+ * @param {Array} gradient.stops - An array of gradient stops.
+ * @param {string} gradient.stops[].color - The color of the gradient stop.
+ * @param {number} gradient.stops[].stop - The position of the gradient stop as a percentage.
+ * @returns {string} The CSS gradient string.
+ */
+export const transformGradient = (gradient) =>
+  `${gradient.type}-gradient(${gradient.angle}deg, ${gradient.stops[0].color} ${
+    gradient.stops[0].stop * 100
+  }%, ${gradient.stops[1].color} ${gradient.stops[1].stop * 100}%)`
+
+export default { transformGradient }

package/src/utils/useOverlaidPosition.js

@@ -0,0 +1,224 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+import { Dimensions, Platform } from 'react-native'
+
+const adjustHorizontalToFit = (initialOffset, windowWidth, sourceWidth) => {
+  const offset = Math.max(0, initialOffset)
+  const otherEdgeOverflow = Math.max(0, offset + sourceWidth - windowWidth)
+  const tooWideBy = Math.max(0, otherEdgeOverflow - offset)
+
+  const adjusted = {
+    offset: Math.max(0, offset - otherEdgeOverflow)
+  }
+  if (tooWideBy) adjusted.width = Math.max(0, sourceWidth - tooWideBy)
+
+  return adjusted
+}
+
+const getPosition = ({ edge, fromEdge, sourceSize }) => {
+  switch (edge) {
+    case 'near':
+      return fromEdge
+    case 'mid':
+      return fromEdge + sourceSize / 2
+    case 'far':
+      return fromEdge + sourceSize
+    default:
+      return 0
+  }
+}
+
+const getEdgeType = (align, alignSide) => {
+  const alignTo = align[alignSide]
+  const edge =
+    (['center', 'middle'].includes(alignTo) && 'mid') || (alignSide === alignTo ? 'near' : 'far')
+  return edge
+}
+
+/**
+ * Based on UDS's private getTooltipPosition but generalised.
+ *
+ * Used for absolute positioning of the tooltip. Since the tooltip is always centered relatively
+ * to the source (button) and we have a limited set of positions, an easy and consistent way
+ * of positioning it is to check all of the possible positions and pick one that will be rendered
+ * within the window bounds. This way we can also rely on the tooltip being actually rendered
+ * before it is shown, which makes it account for the width being limiting in styles, custom font
+ * rendering, etc.
+ */
+function getOverlaidPosition({
+  sourceLayout,
+  targetDimensions,
+  windowDimensions,
+  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 = {}
+
+  if (align.top)
+    positioning.top = getPosition({
+      edge: getEdgeType(align, 'top'),
+      fromEdge: sourceLayout.y + scrollY + (offsets.vertical ?? 0),
+      sourceSize: sourceLayout.height
+    })
+  if (align.middle)
+    positioning.top = getPosition({
+      edge: getEdgeType(align, 'middle'),
+      fromEdge: sourceLayout.y + scrollY + (offsets.vertical ?? 0) - targetDimensions.height / 2,
+      sourceSize: sourceLayout.height
+    })
+  if (align.bottom)
+    positioning.bottom = getPosition({
+      edge: getEdgeType(align, 'bottom'),
+      fromEdge:
+        windowDimensions.height -
+        (sourceLayout.y + scrollY + sourceLayout.height - (offsets.vertical ?? 0)),
+      sourceSize: sourceLayout.height
+    })
+
+  if (align.left)
+    positioning.left = getPosition({
+      edge: getEdgeType(align, 'left'),
+      fromEdge: sourceLayout.x + scrollX + (offsets.horizontal ?? 0),
+      sourceSize: sourceLayout.width
+    })
+  if (align.center)
+    positioning.left = getPosition({
+      edge: getEdgeType(align, 'center'),
+      fromEdge: sourceLayout.x + scrollX + (offsets.horizontal ?? 0) - targetDimensions.width / 2,
+      sourceSize: sourceLayout.width
+    })
+  if (align.right)
+    positioning.right = getPosition({
+      edge: getEdgeType(align, 'right'),
+      fromEdge:
+        windowDimensions.width -
+        (sourceLayout.x + scrollX + sourceLayout.width - (offsets.horizontal ?? 0)),
+      sourceSize: sourceLayout.width
+    })
+
+  if (!(align.left && align.right)) {
+    // Check if the position and/or width need adjusting to fit on the screen
+    const side = align.right ? 'right' : 'left'
+    const adjusted = adjustHorizontalToFit(
+      positioning[side],
+      windowDimensions.width,
+      sourceLayout.width
+    )
+    if (typeof adjusted.width === 'number') positioning.width = adjusted.width
+    if (typeof adjusted.offset === 'number') {
+      positioning[side] = adjusted.offset
+    }
+  }
+
+  return positioning
+}
+
+/**
+ * Positions an element in a modal or portal so that it appears tooltip-like below the
+ * target element.
+ *
+ * @TODO - add support for positioning other than 'below' like UDS's tooltip (this is not
+ * a small task because UDS's tooltip logic only really works for short text - it might be
+ * better to use a third-party library).
+ */
+const useOverlaidPosition = ({
+  isShown = false,
+  offsets,
+  // By default, align the overlaid target's `top` to the bottom of the source, and center horizontally.
+  align = {
+    center: 'center',
+    top: 'bottom'
+  }
+}) => {
+  // Element in main document flow that the targetRef element is positioned around
+  const sourceRef = useRef(null)
+  const [sourceLayout, setSourceLayout] = useState(null)
+
+  // Element in a modal or portal overlay positioned to appear adjacent to sourceRef
+  const targetRef = useRef(null)
+  const [targetDimensions, setTargetDimensions] = useState(null)
+
+  const [windowDimensions, setWindowDimensions] = useState(null)
+
+  const onTargetLayout = useCallback(
+    ({
+      nativeEvent: {
+        layout: { width, height }
+      }
+    }) => {
+      // NOTE: UDS's Tooltip logic injects some additional width to allow for antialiasing etc of text,
+      // avoiding adding unnecessary line breaks to text that is slightly wider than it thinks it is.
+      // That is probably something specific to text tooltips that doesn't belong in a generic hook.
+      setTargetDimensions((previousDimensions) => {
+        // Re-render on first non-zero width / height: avoid infinite loops on changes, or mispositioning
+        // if user scrolls while a slidedown animation is changing the height and recalculating position.
+        if (!previousDimensions && width && height) {
+          return { width, height }
+        }
+        return previousDimensions
+      })
+    },
+    []
+  )
+
+  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 })
+      })
+    }
+
+    let subscription
+    const unsubscribe = () => {
+      if (typeof subscription?.remove === 'function') {
+        // React Native >=0.65.0
+        subscription.remove()
+      } else if (typeof Dimensions.remove === 'function') {
+        // React Native <0.65.0
+        Dimensions.remove('change', handleDimensionsChange)
+      }
+      setSourceLayout(null)
+      setTargetDimensions(null)
+    }
+
+    if (readyToShow) {
+      subscription = Dimensions.addEventListener('change', handleDimensionsChange)
+      handleDimensionsChange({ window: Dimensions.get('window') })
+    } else {
+      unsubscribe()
+    }
+
+    return unsubscribe
+  }, [readyToShow])
+
+  const isReady = Boolean(isShown && sourceLayout && windowDimensions && targetDimensions)
+
+  const overlaidPosition = isReady
+    ? getOverlaidPosition({
+        sourceLayout,
+        targetDimensions,
+        windowDimensions,
+        offsets,
+        align
+      })
+    : {}
+
+  return {
+    overlaidPosition,
+    sourceRef,
+    targetRef,
+    onTargetLayout,
+    isReady
+  }
+}
+
+export default useOverlaidPosition

package/src/utils/withLinkRouter.jsx

@@ -1,4 +1,4 @@
-import React, { forwardRef } from 'react'
+import React from 'react'
 import PropTypes from 'prop-types'
 import hasOwnProperty from './hasOwnProperty'
 
@@ -17,7 +17,7 @@ import hasOwnProperty from './hasOwnProperty'
  * @example A LinkRouter component to be used with link-like components might look like:
  *
  * ```jsx
- * const LinkLinkRouter = forwardRef(({ Component, linkRouterProps: { to, options }, href, ...rest }, ref) => {
+ * const LinkLinkRouter = React.forwardRef(({ Component, linkRouterProps: { to, options }, href, ...rest }, ref) => {
  *   const { href: resolvedHref, onClick } = useSomeRouterHook({ to, href, options })
  *   return <Component href={resolvedHref} onPress={onClick} {...rest} />
  * })
@@ -31,7 +31,7 @@ import hasOwnProperty from './hasOwnProperty'
  * ```
  */
 const withLinkRouter = (Component) => {
-  const wrappedComponent = forwardRef(({ LinkRouter, linkRouterProps, ...props }, ref) => {
+  const wrappedComponent = React.forwardRef(({ LinkRouter, linkRouterProps, ...props }, ref) => {
     if (!LinkRouter) return <Component {...props} ref={ref} />
     return (
       <LinkRouter linkRouterProps={linkRouterProps} Component={Component} ref={ref} {...props} />

package/types/Badge.d.ts

@@ -0,0 +1,28 @@
+export interface BadgeProps {
+  text: string
+  borderColor?: string
+  textColor?: string
+}
+
+type BadgeVariants = {
+  alternative?: boolean
+  inverse?: boolean
+  outline?: boolean
+  purpose?: 'offer' | 'editorial'
+}
+
+export type BadgeTokens = {
+  backgroundColor?: string
+  borderColor?: string
+  borderRadius?: number
+  borderWidth?: number
+  color?: string
+  fontName?: string
+  fontSize?: number
+  fontWeight?: number
+  gradient?: string
+  paddingBottom?: number
+  paddingLeft?: number
+  paddingRight?: number
+  paddingTop?: number
+}

package/types/Box.d.ts

@@ -0,0 +1,52 @@
+import { ReactNode, ReactElement } from 'react'
+import { ScrollViewProps } from 'react-native'
+import { ResponsiveSpacing, SemanticTag } from './Common'
+
+type BoxVariants = {
+  background?:
+    | 'lightest'
+    | 'lighter'
+    | 'light'
+    | 'dark'
+    | 'darker'
+    | 'darkest'
+    | 'critical'
+    | 'danger'
+    | 'warning'
+    | 'positive'
+    | 'black'
+    | 'featurePrimary'
+    | 'featureSecondary'
+    | 'featureNeutral'
+    | 'featureBrand'
+}
+
+type BoxTokens = {
+  backgroundColor?: string
+  gradient?: string
+  borderWidth?: number
+  borderColor?: string
+  borderTopLeftRadius?: number
+  borderTopRightRadius?: number
+  borderBottomLeftRadius?: number
+  borderBottomRightRadius?: number
+}
+
+export interface BoxProps {
+  children: ReactNode | ReactElement
+  horizontal?: ResponsiveSpacing | number
+  vertical?: ResponsiveSpacing | number
+  top?: ResponsiveSpacing | number
+  bottom?: ResponsiveSpacing | number
+  left?: ResponsiveSpacing | number
+  right?: ResponsiveSpacing | number
+  variant?: BoxVariants
+  tokens?: BoxTokens
+  space?: ResponsiveSpacing | number
+  flex?: number
+  scroll?: boolean | ScrollViewProps
+  tag?: SemanticTag
+  testID?: string
+  accessibilityLabel?: string
+  accessible?: boolean
+}

package/types/Checkbox.d.ts

@@ -0,0 +1,47 @@
+import { StyleProp, ViewStyle, TextStyle } from 'react-native'
+import { Tokens, Variant } from '../ThemeProvider'
+
+type CheckboxProps = {
+  checked?: boolean
+  defaultChecked?: boolean
+  error?: boolean
+  feedback?: string
+  id?: string
+  inactive?: boolean
+  label?: string
+  name?: string
+  onChange?: (value: boolean, event: any) => void
+  tokens?: Tokens
+  value?: string | number | boolean
+  variant?: Variant
+  style?: StyleProp<ViewStyle>
+  labelStyle?: StyleProp<TextStyle>
+  containerStyle?: StyleProp<ViewStyle>
+}
+
+type CheckboxTokens = {
+  containerBackgroundColor?: string
+  feedbackMarginBottom?: number
+  feedbackMarginTop?: number
+  feedbackPosition?: string
+  icon?: string
+  iconBackgroundColor?: string
+  iconColor?: string
+  iconSize?: number
+  inputBackgroundColor?: string
+  inputBorderColor?: string
+  inputBorderRadius?: number | string
+  inputBorderWidth?: number | string
+  inputHeight?: number
+  inputOutlineColor?: string
+  inputOutlineOffset?: number
+  inputOutlineWidth?: number | string
+  inputShadow?: string
+  inputWidth?: number
+  labelColor?: string
+  labelFontName?: string
+  labelFontSize?: number
+  labelFontWeight?: number
+  labelLineHeight?: number
+  labelMarginLeft?: number
+}

package/types/CheckboxCardGroup.d.ts

@@ -0,0 +1,72 @@
+import * as React from 'react'
+import { Direction, ResponsiveDirection } from './Common'
+
+type CheckboxCardGroupProps = {
+  copy?: 'en' | 'fr'
+  variant?: 'fullWidth'
+  legend?: string
+  tooltip?: string
+  hint?: string
+  hintPosition?: 'inline' | 'below'
+  validation?: 'error' | 'success'
+  feedback?: string
+  initialCheckedIds?: string[]
+  checkedIds?: string[]
+  onChange?: (checkedIds: string[]) => void
+  readOnly?: boolean
+  inactive?: boolean
+}
+
+type CheckboxCardGroupTokens = {
+  borderBottomLeftRadius?: number
+  borderBottomRightRadius?: number
+  borderTopLeftRadius?: number
+  borderTopRightRadius?: number
+  direction?: Direction | ResponsiveDirection
+  fieldSpace?: number
+  outlineOffset?: number
+  outlineWidth?: number
+  showIcon?: boolean
+  space?: number
+}
+
+type checkboxCardTokens = {
+  outerBorderColer?: string
+  outerBorderWidth?: number
+  outerBorderGap?: number
+  flex?: number
+  backgroundColor?: string
+  borderColor?: string
+  borderRadius?: number
+  borderWidth?: number
+  paddingBottom?: number
+  paddingLeft?: number
+  paddingRight?: number
+  paddingTop?: number
+  minWidth?: number
+  shadow?: string
+  contentAlignItems?: string
+  contentJustifyContent?: string
+  contentFlexGrow?: number
+  contentFlexShrink?: number
+  checkboxCheckedBackgroundColor?: string
+  checkboxCheckedSize?: number
+  checkboxInputBackgroundColor?: string
+  checkboxInputBorderColor?: string
+  checkboxInputBorderWidth?: number
+  checkboxInputOutlineColor?: string
+  checkboxInputOutlineWidth?: number
+  checkboxInputSize?: number
+  checkboxOuterBorderColor?: string
+  checkboxOuterBorderWidth?: number
+  checkboxOuterBorderGap?: number
+  fontSize?: number
+  fontName?: string
+  lineHeight?: number
+  color?: string
+  letterSpacing?: string
+  textTransform?: string
+  fontWeight?: number
+  checkboxSpace?: number
+  contentSpace?: number
+}

package/types/ChevronLink.d.ts

@@ -0,0 +1,47 @@
+import { IconProps, IconPositionLeftRight } from './Icon'
+import { LinkAndTextButtonVariants } from './Link'
+
+type ChevronLinkTokens = {
+  fontSize?: number
+  color?: string
+  outerBorderColor?: string
+  leftIcon?: IconProps
+  rightIcon?: IconProps
+  iconDisplace?: number
+  iconSize?: number
+  iconSpace?: number
+  textLine?: string
+  textLineStyle?: string
+  outerBorderWidth?: number
+  outerBorderOutline?: string
+  borderRadius?: number
+  blockFontName?: string
+  blockFontWeight?: number
+  blockFontSize?: number
+  blockLineHeight?: number
+  icon?: IconProps
+  iconTranslateX?: number
+  iconTranslateY?: number
+  alignSelf?: 'auto' | 'flex-start' | 'flex-end' | 'center' | 'stretch' | 'baseline'
+}
+export interface ChevronLinkProps {
+  testID?: string
+  children?: React.ReactNode
+  onPress?: () => void
+  onPressIn?: () => void
+  onPressOut?: () => void
+  disabled?: boolean
+  href?: string
+  hrefAttrs?: HrefProps
+  accessibilityRole?: string
+  accessibilityLabel?: string
+  tokens?: ChevronLinkTokens
+  direction?: IconPositionLeftRight
+  variant?: LinkAndTextButtonVariants
+}
+
+export interface HrefProps {
+  download: string
+  rel: string
+  target: string
+}

package/types/Common.d.ts

@@ -0,0 +1,106 @@
+import React from 'react'
+
+export type TextTransform = {
+  CAPITALIZE: 'capitalize'
+  LOWERCASE: 'lowercase'
+  UPPERCASE: 'uppercase'
+  NONE: 'none'
+}
+
+export type LetterSpacing = {
+  NORMAL: 'normal'
+  LENGTH: number
+}
+
+export type CopyType = {
+  EN: 'en'
+  FR: 'fr'
+}
+
+export type Size = {
+  margin?: number
+  padding?: number
+  height?: number | string
+  width?: number | string
+}
+
+export type Position = 'auto' | 'above' | 'below' | 'right' | 'left'
+
+export type DisplaySize = {
+  LARGE: 'large'
+  MEDIUM: 'medium'
+  SMALL: 'small'
+  MICRO: 'micro'
+}
+
+export enum Sizes {
+  xs = 'xs',
+  sm = 'sm',
+  md = 'md',
+  lg = 'lg',
+  xl = 'xl'
+}
+
+export type ResponsiveSpacing = {
+  [key in Sizes]?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11
+}
+
+export type Direction = 'column' | 'row' | 'column-reverse' | 'row-reverse'
+
+export type ResponsiveDirection = {
+  [key in Sizes]?: Direction
+}
+
+export type SemanticTag =
+  | 'h1'
+  | 'h2'
+  | 'h3'
+  | 'h4'
+  | 'h5'
+  | 'h6'
+  | 'article'
+  | 'aside'
+  | 'blockquote'
+  | 'footer'
+  | 'figure'
+  | 'form'
+  | 'header'
+  | 'ul'
+  | 'li'
+  | 'main'
+  | 'nav'
+  | 'section'
+  | 'label'
+
+type headingType = {
+  H1: 'h1'
+  H2: 'h2'
+  H3: 'h1'
+  H4: 'h2'
+  H5: 'h1'
+  H6: 'h2'
+}
+
+type tagType = {
+  HEADING: headingType
+  BLOCKQUOTE: 'blockquote'
+  CODE: 'code'
+  DEL: 'del'
+  EM: 'em'
+  INS: 'ins'
+  LI: 'li'
+  STRONG: 'strong'
+  LABEL: 'label'
+}
+
+type alignType = {
+  AUTO: 'auto'
+  LEFT: 'left'
+  RIGHT: 'right'
+  CENTER: 'center'
+  JUSTIFY: 'justify'
+}
+
+export type FlexAlign = 'flex-start' | 'flex-end' | 'center' | 'stretch' | 'baseline'
+
+export type FlexJustify = 'flex-start' | 'flex-end' | 'center' | 'space-between' | 'space-around'

package/types/Divider.d.ts

@@ -0,0 +1,19 @@
+import { ResponsiveSpacing, Size } from './Common'
+type DividerVariants = {
+  weight?: 'regular' | 'thick'
+  decorative?: boolean
+  inverse?: boolean
+}
+
+export interface DividerProps {
+  testID?: string
+  vertical?: boolean
+  space?: number | ResponsiveSpacing
+  tokens?: DividerTokens
+  variant?: DividerVariants
+}
+
+export interface DividerTokens {
+  width?: Size
+  color?: string
+}