@telus-uds/components-base 0.0.2-prerelease.4 → 0.0.2-prerelease.8

package/src/SideNav/Item.jsx

@@ -58,7 +58,7 @@ const Item = ({
     accessibilityRole,
     href,
     onPress: handlePress,
-    ...hrefAttrsProp.spread(hrefAttrs),
+    hrefAttrs,
     ...rest
   })
 
@@ -105,7 +105,7 @@ Item.propTypes = {
   href: PropTypes.string,
   /**
    * On Web if href is passed, React Native Web maps this object's props to
-   * `rel`, `target` and (>= RNW 0.15.0) `download` attrs.
+   * `rel`, `target` and `download` attrs.
    */
   hrefAttrs: PropTypes.shape(hrefAttrsProp.types),
   /**

package/src/Skeleton/Skeleton.jsx

@@ -0,0 +1,98 @@
+import React from 'react'
+import { Animated, Platform } from 'react-native'
+import propTypes from 'prop-types'
+import StackView from '../StackView'
+import { useThemeTokens } from '../ThemeProvider'
+import { getTokensPropType, useSpacingScale, variantProp } from '../utils'
+import useSkeletonNativeAnimation from './useSkeletonNativeAnimation'
+import skeletonWebAnimation from './skeletonWebAnimation'
+
+const selectSkeletonStyles = ({ color, radius, fadeAnimation }) => ({
+  backgroundColor: color,
+  borderRadius: radius,
+  ...fadeAnimation
+})
+
+const selectLineStyles = ({ skeletonHeight, lineWidth }) => ({
+  width: lineWidth,
+  height: skeletonHeight
+})
+
+const selectShapeStyles = ({ skeletonHeight }) => ({
+  height: skeletonHeight,
+  width: skeletonHeight
+})
+
+const selectSquareStyles = ({ radius }) => ({
+  borderRadius: radius
+})
+
+const Skeleton = ({ tokens, variant, size, characters, lines, shape = 'line' }) => {
+  const themeTokens = useThemeTokens('Skeleton', tokens, variant)
+  const skeletonHeight = useSpacingScale(size || themeTokens.size)
+  const nativeAnimation = useSkeletonNativeAnimation()
+
+  const getAnimationBaseOnPlatform = () => {
+    if (Platform.OS !== 'web') {
+      return nativeAnimation
+    }
+
+    return skeletonWebAnimation
+  }
+
+  const getLineWidth = () => {
+    if (characters) {
+      return characters * themeTokens.baseWidth
+    }
+
+    return themeTokens.characters * themeTokens.baseWidth
+  }
+
+  const getStyledBasedOnShape = () => {
+    if (shape === 'circle') {
+      return selectShapeStyles({ skeletonHeight })
+    }
+
+    if (shape === 'box') {
+      return [
+        selectShapeStyles({ skeletonHeight }),
+        selectSquareStyles({ radius: themeTokens.squareRadius })
+      ]
+    }
+
+    return selectLineStyles({ skeletonHeight, lineWidth: getLineWidth() })
+  }
+
+  const renderSkeleton = (index = 0) => (
+    <Animated.View
+      testID="skeleton"
+      key={`skeleton-${index + 1}`}
+      style={[
+        selectSkeletonStyles({ ...themeTokens, fadeAnimation: getAnimationBaseOnPlatform() }),
+        getStyledBasedOnShape()
+      ]}
+    />
+  )
+
+  if (lines) {
+    const arrayOfSkeletons = [...Array(lines)]
+    return (
+      <StackView space={themeTokens.spaceBetweenLines}>
+        {arrayOfSkeletons.map((_, index) => renderSkeleton(index))}
+      </StackView>
+    )
+  }
+
+  return renderSkeleton()
+}
+
+Skeleton.propTypes = {
+  tokens: getTokensPropType('Skeleton'),
+  variant: variantProp.propType,
+  size: propTypes.number,
+  characters: propTypes.number,
+  lines: propTypes.number,
+  shape: propTypes.oneOf(['line', 'circle', 'box'])
+}
+
+export default Skeleton

package/src/Skeleton/index.js

@@ -0,0 +1,3 @@
+import Skeleton from './Skeleton'
+
+export default Skeleton

package/src/Skeleton/skeleton.constant.js

@@ -0,0 +1,3 @@
+export const DEFAULT_OPACITY = 1
+export const OPACITY_STOP = 0.4
+export const ANIMATION_DURATION = 1500

package/src/Skeleton/skeletonWebAnimation.js

@@ -0,0 +1,13 @@
+import { ANIMATION_DURATION, DEFAULT_OPACITY, OPACITY_STOP } from './skeleton.constant'
+
+export default {
+  animationDuration: `${ANIMATION_DURATION}ms`,
+  animationTimingFunction: 'ease-in-out',
+  animationDelay: '0.5s',
+  animationIterationCount: 'infinite',
+  animationKeyframes: {
+    '0%': { opacity: DEFAULT_OPACITY },
+    '50%': { opacity: OPACITY_STOP },
+    '100%': { opacity: DEFAULT_OPACITY }
+  }
+}

package/src/Skeleton/useSkeletonNativeAnimation.js

@@ -0,0 +1,27 @@
+import { useEffect, useRef } from 'react'
+import { Animated } from 'react-native'
+import { ANIMATION_DURATION, DEFAULT_OPACITY, OPACITY_STOP } from './skeleton.constant'
+
+const useSkeletonNativeAnimation = () => {
+  const fadeAnimation = useRef(new Animated.Value(DEFAULT_OPACITY)).current
+
+  useEffect(() => {
+    const fade = Animated.sequence([
+      Animated.timing(fadeAnimation, {
+        toValue: OPACITY_STOP,
+        duration: ANIMATION_DURATION,
+        useNativeDriver: true
+      }),
+      Animated.timing(fadeAnimation, {
+        toValue: DEFAULT_OPACITY,
+        duration: ANIMATION_DURATION,
+        useNativeDriver: true
+      })
+    ])
+    Animated.loop(fade).start()
+  }, [fadeAnimation])
+
+  return { opacity: fadeAnimation }
+}
+
+export default useSkeletonNativeAnimation

package/src/Spacer/Spacer.jsx

@@ -0,0 +1,91 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+import { StyleSheet, View } from 'react-native'
+
+import { useSpacingScale, spacingProps } from '../utils'
+/**
+ * @typedef {import('../utils/propTypes.js').SpacingValue} SpacingValue
+ * @typedef {import('../utils/propTypes.js').SpacingObject} SpacingObject
+ */
+
+const selectSizeStyle = (size, direction) => ({
+  // Only apply space in one direction at a time, else large spacers will increase the
+  // 'across' size of the parent and mess up siblings with styles like `alignItems: stretch`.
+  [direction === 'row' ? 'width' : 'height']: size
+})
+
+/**
+ * An empty element used to create a gap between components that is sized according to the theme spacing scale,
+ * passing its `space` prop ({@link SpacingValue}) to `useSpacingScale`.
+ *
+ * ## Simple spacing
+ *
+ * For most simple uses, pass a number to Spacer's `space` prop referring to an index in the theme's
+ * spacing scale. For example, for a spacer of the theme's smallest non-zero spacing size:
+ *
+ * ```jsx
+ * <Spacer space={1} />
+ * ```
+ *
+ * ## Responsive spacing
+ *
+ * Different spacing scale sizes may be chosen for different viewports by passing `space` a {@link SpacingObject}
+ * using keys for the viewports at and above which certain spacing indexes should apply.
+ *
+ * This can be useful when a Spacer is inside a layout with a shape that changes between viewports.
+ *
+ * For example, a spacer might need no width below 'md' viewport because the items it separates will be on separate lines,
+ * but may need a visible size above that viewport, and a wider size at the highest viewport:
+ *
+ * ```jsx
+ * <Spacer space={{ xs: 0, md: 2, xl: 3 }} />
+ * ```
+ *
+ * Note that themes may also define viewport-specific behaviour for indexes on the spacing scale. These viewport
+ * props should only be used where necessary to achieve a certain responsive layoutm and shouldn't be used to replace
+ * or deviate from responsive spacing behaviour in a theme that is intended to apply universally.
+ *
+ * ## More options
+ *
+ * See `useSpacingScale` hook for more options that may be used with the `space` prop.
+ *
+ * ## Accessibility
+ *
+ * Spacer has no content and is ignored by tools such as screen readers. Use `Divider` for
+ * separations between elements that may be treated as semantically meaningful on web.
+ */
+const Spacer = ({ space = 1, direction = 'column', testID }) => {
+  const size = useSpacingScale(space)
+  const sizeStyle = selectSizeStyle(size, direction)
+  return <View testID={testID} style={[staticStyles.stretch, sizeStyle]} />
+}
+
+Spacer.propTypes = {
+  /**
+   * The size of the spacer according to the theme's spacing scale.
+   * Either a number corresponding to a position on the theme's spacing scale (1 is smallest, 2 is second smallest, etc),
+   * or, a SpacingObject with viewport keys and options (see `useSpacingScale` for details).
+   */
+  space: spacingProps.types.spacingValue,
+  /**
+   * The spacer applies space in only one direction, which is controlled by the `direction` prop:
+   *
+   * - `'column'` (default) applies space vertically; has a fixed height and not width.
+   * - `'row'` applies space horizontally; has a fixed width and not height.
+   */
+  direction: PropTypes.oneOf(['column', 'row']),
+  /**
+   * @ignore
+   * In tests, the only way to select Spacers is with testID prop and getByTestId, since they have no content,
+   * no accessibility role, and there is no equivalent of nextSibling in React Native Testing Library.
+   */
+  testID: PropTypes.string
+}
+
+const staticStyles = StyleSheet.create({
+  stretch: {
+    alignSelf: 'stretch'
+  }
+})
+
+export default Spacer

package/src/Spacer/index.js

@@ -0,0 +1,3 @@
+import Spacer from './Spacer'
+
+export default Spacer

package/src/StackView/StackView.jsx

@@ -0,0 +1,111 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+import { View } from 'react-native'
+
+import Divider from '../Divider'
+import {
+  spacingProps,
+  a11yProps,
+  responsiveProps,
+  variantProp,
+  viewProps,
+  useResponsiveProp
+} from '../utils'
+import { useThemeTokens } from '../ThemeProvider'
+import { useViewport } from '../ViewportProvider'
+import getStackedContent from './getStackedContent'
+import { staticStyles, selectFlexStyles } from './common'
+
+/**
+ * StackView evenly spaces its children, by default placing `Spacer` components between them.
+ *
+ * ## Spacing
+ *
+ * StackView takes the same spacing props as `Spacer` and passes them directly to the layout components
+ * it uses for spacing.
+ *
+ * ## Direction
+ *
+ * Use `direction` to control how the children are stacked:
+ *
+ * - `'column'` (default) stacks and spaces the children vertically.
+ * - `'row'` stacks and spaces the children horizontally.
+ * - `'column-reverse'` acts the same as `'column'`, but reverses the direction.
+ * - `'row-reverse'` acts the same as `'row'`, but reverses the direction.
+ *
+ * `direction` is an optionally responsive prop and may be an object keyed by viewports. For example,
+ * `{ xs: 'column', md: 'row' } stacks as a column on `xs` and `sm` viewports and a row at 'md' and above.
+ *
+ * ## Theming, alignment and justification
+ *
+ * `StackView` is a pure layout component and has no theme styles beyond a small set of layout styles
+ * (`alignItems`, `justifyContent`, `flexGrow`) which may be set using the `tokens` prop. If the
+ * tokens prop is a function it will recieve the current viewport.
+ *
+ * All other styling such as borders, background colours, padding etc should be applied by wrapping
+ * the `StackView` in other components. For example, a `StackView` may be the child of a `Card`.
+ *
+ * ## Separator options
+ *
+ * By default, StackView inserts a `<Spacer>` component between each rendered child.
+ *
+ * With the `divider` prop, it instead renders a `Divider` instead of a `Spacer`. The gap between
+ * items will be double what it would be without this prop plus the width of the divider.
+ *
+ * ## Accessibility
+ *
+ * `StackView` may take any React Native accessibility props and applies them to the outer `View`.
+ * It applies no accessibility props of its own, unless `divider` prop is passed (`Divider` has a
+ * semantic role but only on web, not within native apps).
+ */
+const StackView = ({
+  space = 1,
+  divider,
+  direction: directionProp = 'column',
+  children,
+  variant,
+  tokens,
+  ...rest
+}) => {
+  const viewport = useViewport()
+  const direction = useResponsiveProp(directionProp, 'column')
+  const props = { ...a11yProps.select(rest), ...viewProps.select(rest) }
+  const content = getStackedContent(children, { direction, divider, space })
+  const themeTokens = useThemeTokens('StackView', tokens, variant, { viewport })
+  const flexStyles = selectFlexStyles(themeTokens)
+
+  return (
+    <View {...props} style={[flexStyles, staticStyles[direction]]}>
+      {content}
+    </View>
+  )
+}
+
+StackView.propTypes = {
+  ...a11yProps.propTypes,
+  variant: variantProp.propType,
+  /**
+   * Sets the `flexDirection` of the container and, if `divider` is used, gives the Divider the appropriate direction.
+   */
+  direction: responsiveProps.getTypeOptionallyByViewport(
+    PropTypes.oneOf(['column', 'row', 'column-reverse', 'row-reverse'])
+  ),
+  /**
+   * If true, renders a UDS `Divider` component between each item. If an object is passed,
+   * this object is passes as props to each Divider.
+   */
+  divider: PropTypes.oneOfType([PropTypes.bool, PropTypes.shape(Divider.propTypes)]),
+  /**
+   * The size of the spacer according to the theme's spacing scale.
+   * Either a number corresponding to a position on the theme's spacing scale (1 is smallest, 2 is second smallest, etc),
+   * or, a SpacingObject with viewport keys and options (see `useSpacingScale` for details).
+   */
+  space: spacingProps.types.spacingValue,
+  /**
+   * A StackView 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.
+   */
+  children: PropTypes.node
+}
+
+export default StackView

package/src/StackView/StackWrap.jsx

@@ -0,0 +1,41 @@
+import React from 'react'
+import { Platform } from 'react-native'
+
+import StackWrapBox from './StackWrapBox'
+import StackWrapGap from './StackWrapGap'
+
+// CSS.supports needs an example of the type of value you intend to use.
+// Will be an integer appended `px` after hooks and JSX styles are resolved.
+const exampleGapValue = '1px'
+
+/**
+ * StackWrap is an alternative to StackView where the spaced items are allowed to wrap.
+ *
+ * As well as providing space between the items, StackWrap provides `gap` space between
+ * wrapped lines of items. By default, this `gap` is the same as the gap between spaced items.
+ * If a different spacing is desired between wrapped lines, pass a spacing value to the `gap` prop.
+ */
+const StackWrap = (props) => {
+  const { space } = props
+  // Don't apply separate gap if `null` or `undefined`, so can be unset in Storybook etc
+  // eslint-disable-next-line react/destructuring-assignment
+  const gap = props.gap ?? space
+
+  const canUseCSSGap =
+    Platform.OS === 'web' &&
+    gap === space &&
+    // In Jest/CI, global CSS isn't always available and doesn't always have .supports method
+    typeof CSS?.supports === 'function' &&
+    CSS.supports('gap', exampleGapValue)
+
+  return canUseCSSGap ? (
+    // If possible, use the cleaner implementation that applies CSS `gap` styles to the container.
+    <StackWrapGap {...props} />
+  ) : (
+    // Else, use the fallback implementation which renders a `Box` component around each child.
+    <StackWrapBox {...props} />
+  )
+}
+StackWrap.propTypes = StackWrapBox.propTypes
+
+export default StackWrap

package/src/StackView/StackWrap.native.jsx

@@ -0,0 +1,4 @@
+import StackWrapBox from './StackWrapBox'
+
+// No support for CSS `gap` on React Native, so always use the fallback "box" implementation.
+export default StackWrapBox

package/src/StackView/StackWrapBox.jsx

@@ -0,0 +1,94 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+import { View } from 'react-native'
+
+import {
+  spacingProps,
+  a11yProps,
+  responsiveProps,
+  useSpacingScale,
+  useResponsiveProp,
+  viewProps
+} from '../utils'
+import { useThemeTokens } from '../ThemeProvider'
+import { useViewport } from '../ViewportProvider'
+import getStackedContent from './getStackedContent'
+import { staticStyles, selectFlexStyles } from './common'
+
+const offsetSides = {
+  row: 'marginBottom',
+  column: 'marginRight'
+}
+
+const gapSides = {
+  row: 'bottom',
+  column: 'right'
+}
+
+const spaceSides = {
+  row: 'right',
+  column: 'bottom'
+}
+
+/**
+ * An alternative fallback implementation of `StackWrap` that doesn't use CSS `gap`.
+ *
+ * This is not intended to be used directly. It will automatically be used instead of StackWrap in:
+ *
+ * - Native apps (no `gap` style prop in React Native).
+ * - Older (~<=2020) browsers which don't support CSS `gap`.
+ * - Cases where the `space` between items should be different to the `gap` between wrapped rows .
+ *
+ * Unlike the cleaner and more side-effect-free CSS gap StackWrap implementation, this renders a Box (View)
+ * between the container and the stacked children, and requires a negative margin on the container.
+ */
+const StackWrapBox = ({
+  space = 1,
+  gap = space,
+  direction: directionProp = 'row',
+  children,
+  tokens,
+  variant,
+  ...rest
+}) => {
+  const viewport = useViewport()
+  const direction = useResponsiveProp(directionProp, 'row')
+  const themeTokens = useThemeTokens('StackView', tokens, variant, { viewport })
+  const flexStyles = selectFlexStyles(themeTokens)
+  const props = { ...a11yProps.select(rest), ...viewProps.select(rest) }
+
+  // Mimic CSS `gap` using box spacing on the side after a wrapped row then offsetting it on the last row.
+  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 })
+
+  return (
+    <View {...props} style={[flexStyles, staticStyles.wrap, staticStyles[direction], offsetStyle]}>
+      {content}
+    </View>
+  )
+}
+
+StackWrapBox.propTypes = {
+  ...a11yProps.propTypes,
+  /**
+   * Sets the `flexDirection` of the container
+   */
+  direction: responsiveProps.getTypeOptionallyByViewport(
+    PropTypes.oneOf(['column', 'row', 'row-reverse', 'column-reverse'])
+  ),
+  /**
+   * The size of the spacer according to the theme's spacing scale.
+   * Either a number corresponding to a position on the theme's spacing scale (1 is smallest, 2 is second smallest, etc),
+   * or, a SpacingObject with viewport keys and options (see `useSpacingScale` for details).
+   */
+  space: spacingProps.types.spacingValue,
+  /**
+   * 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.
+   */
+  children: PropTypes.node
+}
+
+export default StackWrapBox

package/src/StackView/StackWrapGap.jsx

@@ -0,0 +1,49 @@
+import React from 'react'
+import { View } from 'react-native'
+
+import StackWrapBox from './StackWrapBox'
+import { a11yProps, useSpacingScale, useResponsiveProp, viewProps } from '../utils'
+import { useThemeTokens } from '../ThemeProvider'
+import { useViewport } from '../ViewportProvider'
+import getStackedContent from './getStackedContent'
+import { staticStyles, selectFlexStyles } from './common'
+
+/**
+ * The primary implementation of StackWrap.
+ *
+ * This is not intended to be used directly. It will automatically be used instead of StackWrap if:
+ *
+ * - On web, and,
+ * - On a browser that supports CSS `gap` (most browser versions from 2020 onwards), and,
+ * - The `space` between items is the same as the `gap` between wrapped rows (this is the
+ *   default if `gap` prop is undefined)
+ */
+const StackWrapGap = ({
+  space = 1,
+  tokens,
+  variant,
+  direction: directionProp = 'row',
+  children,
+  ...rest
+}) => {
+  const viewport = useViewport()
+  const direction = useResponsiveProp(directionProp, 'row')
+  const themeTokens = useThemeTokens('StackView', tokens, variant, { viewport })
+  const flexStyles = selectFlexStyles(themeTokens)
+  const props = { ...a11yProps.select(rest), ...viewProps.select(rest) }
+
+  const size = useSpacingScale(space)
+  const gapStyle = { gap: size }
+
+  const content = getStackedContent(children, { direction, space: 0 })
+
+  return (
+    <View {...props} style={[flexStyles, staticStyles.wrap, staticStyles[direction], gapStyle]}>
+      {content}
+    </View>
+  )
+}
+
+StackWrapGap.propTypes = StackWrapBox.propTypes
+
+export default StackWrapGap

package/src/StackView/common.jsx

@@ -0,0 +1,28 @@
+import { StyleSheet } from 'react-native'
+
+export const selectFlexStyles = ({ alignItems, justifyContent, flexGrow }) => ({
+  alignItems,
+  justifyContent,
+  flexGrow
+})
+
+export const staticStyles = StyleSheet.create({
+  wrap: {
+    flexShrink: 1,
+    flexWrap: 'wrap'
+  },
+  row: {
+    flexDirection: 'row'
+  },
+  'row-reverse': {
+    flexDirection: 'row-reverse'
+  },
+  column: {
+    // This is the React Native View default, but also it's very fundamental to the behaviour,
+    // so make it explicit and allow it to be tested for.
+    flexDirection: 'column'
+  },
+  'column-reverse': {
+    flexDirection: 'column-reverse'
+  }
+})