@telus-uds/components-base 0.0.2-prerelease.1 → 0.0.2-prerelease.10

package/src/Select/Select.jsx

@@ -0,0 +1,286 @@
+import React, { useState } from 'react'
+
+import { View, Platform, StyleSheet } from 'react-native'
+import PropTypes from 'prop-types'
+import { applyTextStyles, useThemeTokens, applyOuterBorder } from '../ThemeProvider'
+import { componentPropType, getTokensPropType, useInputValue, variantProp } from '../utils'
+import Picker from './Picker'
+import InputSupports from '../InputSupports'
+import inputSupportsProps from '../InputSupports/propTypes'
+
+const selectInputStyles = (
+  {
+    backgroundColor,
+    color,
+    borderWidth = 0,
+    borderColor,
+    borderRadius,
+    paddingTop,
+    paddingBottom,
+    paddingLeft = 0,
+    paddingRight,
+    fontName,
+    fontSize,
+    fontWeight,
+    lineHeight,
+    icon,
+    iconSize = 0,
+    validationIcon,
+    validationIconSize = 0,
+    height
+  },
+  inactive
+) => {
+  // Subtract border width from padding so overall input width/height doesn't
+  // jump around if the border width changes (avoiding NaN and negative padding)
+  const offsetBorder = (value) =>
+    typeof value === 'number' ? Math.max(0, value - borderWidth) : value
+
+  const textStyles = applyTextStyles({ fontName, fontSize, lineHeight, fontWeight })
+
+  const webStyles = Platform.select({
+    web: {
+      appearance: 'none',
+      WebkitAppearance: 'none', // since iOS Safari needs a prefix
+      outline: 'none',
+      cursor: inactive ? 'not-allowed' : undefined,
+      opacity: inactive ? 1 : undefined // override Chrome's default fadeout of a disabled select
+    }
+  })
+
+  let paddingWithIcons = paddingRight
+
+  if (Platform.OS !== 'android') {
+    if (icon) {
+      paddingWithIcons += iconSize
+    }
+
+    if (validationIcon) {
+      paddingWithIcons += validationIconSize
+    }
+  }
+
+  return {
+    backgroundColor,
+    color,
+    borderWidth,
+    borderColor,
+    borderRadius,
+    paddingLeft: offsetBorder(paddingLeft),
+    paddingRight: offsetBorder(paddingWithIcons),
+    paddingTop: offsetBorder(paddingTop),
+    paddingBottom: offsetBorder(paddingBottom),
+    height,
+    ...textStyles,
+    ...webStyles
+  }
+}
+
+const selectOuterBorderStyles = ({
+  outerBackgroundColor,
+  outerBorderWidth,
+  outerBorderColor,
+  borderRadius
+}) => ({
+  background: outerBackgroundColor,
+  ...applyOuterBorder({
+    outerBorderColor,
+    outerBorderWidth,
+    borderRadius
+  })
+})
+
+const selectIconTokens = ({ iconSize, iconColor }) => ({
+  size: iconSize,
+  color: iconColor
+})
+
+const selectIconContainerStyles = ({ paddingRight, paddingBottom }) => ({
+  paddingRight,
+  paddingBottom
+})
+
+const selectValidationIconTokens = ({ validationIconSize, validationIconColor }) => ({
+  size: validationIconSize,
+  color: validationIconColor
+})
+
+const selectValidationIconContainerStyles = ({
+  icon,
+  iconSize = 0,
+  paddingRight = 0,
+  paddingBottom
+}) => ({
+  paddingRight: icon ? paddingRight + iconSize : paddingRight,
+  paddingBottom
+})
+
+/**
+ * A basic form single-choice select component. Use in forms or individually to receive user's input.
+ *
+ * ## Usage criteria
+ * - Include a `placeholder` to provide instructions such as "Please select..." as an unselectable option (recommended)
+ * - Use when options are between 7-15 (recommended)
+ * - For options are 6 and under, use `Radio` groups or `ButtonGroup`.
+ * - For options 15 and above, look for alternatives (e.g grouping into categories, or input field with auto-complete etc.)
+ *
+ * ## Controlled component
+ * If it is required that the state of the `Select` be controlled by the application or other external methods,
+ * `value` and `onChange` props must be passed to the `Select`.
+ * If the `Select` value should not be changed by user input, a `readOnly` prop must be provided.
+ *
+ * ## Uncontrolled component
+ * If it is not necessary to control the `Select` state, you can create one without a value prop.
+ * In this case its value can be accessed within the `onChange` callback. Use the `initialValue` prop to set the
+ * default value for an uncontrolled `Select`.
+ *
+ * ## Getting feedback for entered values
+ * Use the `feedback` prop to give the user feedback regarding their selection.
+ * You can affirm that the user's selection was correct, or highlight errors that must be corrected, using the `validation` prop.
+ * Keep feedback text as brief as possible, should be limited to text and links.
+ *
+ * ## Using a tooltip
+ * When a more in-depth explanation is needed to fill out a `Select` properly, the tooltip prop may be used.
+ *
+ * ## Grouping options
+ * `Select` supports option groups. Use a `Select.Group` component to render an `<optgroup>` element with its items.
+ * NOTE: this does not work on native platforms - the grouped items will be shown at the same level as the non-grouped items.
+ *
+ */
+const Select = ({
+  value,
+  initialValue,
+  onChange,
+  children,
+  inactive,
+  readOnly,
+  placeholder,
+  validation,
+  tokens,
+  variant,
+  testID,
+  ...rest
+}) => {
+  const { currentValue, setValue } = useInputValue({
+    value,
+    initialValue,
+    onChange,
+    readOnly
+  })
+
+  const [isFocused, setIsFocused] = useState(false)
+  const handleFocus = () => setIsFocused(true)
+  const handleBlur = () => setIsFocused(false)
+
+  const [isHovered, setIsHovered] = useState(false)
+  const handleMouseOver = () => setIsHovered(true)
+  const handleMouseOut = () => setIsHovered(false)
+
+  const { props: supportsProps } = inputSupportsProps.select(rest)
+
+  const themeTokens = useThemeTokens('Select', tokens, variant, {
+    focus: isFocused,
+    hover: isHovered,
+    inactive,
+    validation
+  })
+
+  const { icon: IconComponent, validationIcon: ValidationIconComponent } = themeTokens
+
+  return (
+    <InputSupports {...supportsProps}>
+      {({ a11yProps, inputId }) => (
+        <View style={selectOuterBorderStyles(themeTokens)}>
+          <Picker
+            style={selectInputStyles(themeTokens, inactive)}
+            onFocus={handleFocus}
+            onBlur={handleBlur}
+            onMouseOver={handleMouseOver}
+            onMouseOut={handleMouseOut}
+            onChange={setValue}
+            value={currentValue}
+            inactive={inactive}
+            placeholder={placeholder !== undefined ? { label: placeholder, value: '' } : undefined}
+            {...a11yProps}
+            nativeID={inputId}
+            testID={testID}
+          >
+            {children}
+          </Picker>
+          {ValidationIconComponent && (
+            <View
+              pointerEvents="none"
+              style={[staticStyles.iconContainer, selectValidationIconContainerStyles(themeTokens)]}
+            >
+              <ValidationIconComponent tokens={selectValidationIconTokens(themeTokens)} />
+            </View>
+          )}
+          {IconComponent &&
+            Platform.OS !== 'android' && ( // we can't hide the default caret of a native picker on android
+              <View
+                pointerEvents="none"
+                style={[staticStyles.iconContainer, selectIconContainerStyles(themeTokens)]}
+              >
+                <IconComponent {...selectIconTokens(themeTokens)} />
+              </View>
+            )}
+        </View>
+      )}
+    </InputSupports>
+  )
+}
+
+Select.propTypes = {
+  ...inputSupportsProps.types,
+  /**
+   * Initial value for the uncontrolled version.
+   */
+  initialValue: PropTypes.string,
+  /**
+   * Current value to be set as selected.
+   */
+  value: PropTypes.string,
+  /**
+   * Callback to be called when the value changes.
+   */
+  onChange: PropTypes.func,
+  /**
+   * An array of items or item groups to be used as options.
+   */
+  children: componentPropType(['Item', 'Group']),
+  /**
+   * Whether the select is disabled.
+   */
+  inactive: PropTypes.bool,
+  /**
+   * Whether the select is read-only.
+   */
+  readOnly: PropTypes.bool,
+  /**
+   * A placeholder to provide instructions (such as "Please select...")
+   * as an unselectable option
+   */
+  placeholder: PropTypes.string,
+  /**
+   * Select tokens.
+   */
+  tokens: getTokensPropType('Select'),
+  /**
+   * Select variant.
+   */
+  variant: variantProp.propType,
+  /**
+   * Dedicated ID for testing.
+   */
+  testID: PropTypes.string
+}
+
+export default Select
+
+const staticStyles = StyleSheet.create({
+  iconContainer: {
+    position: 'absolute',
+    right: 0,
+    bottom: 0
+  }
+})

package/src/Select/index.js

@@ -0,0 +1,8 @@
+import Select from './Select'
+import Group from './Group'
+import Item from './Item'
+
+Select.Group = Group
+Select.Item = Item
+
+export default Select

package/src/SideNav/Item.jsx

@@ -58,18 +58,18 @@ const Item = ({
     accessibilityRole,
     href,
     onPress: handlePress,
-    ...hrefAttrsProp.spread(hrefAttrs),
+    hrefAttrs,
     ...rest
   })
 
-  const getTokens = useThemeTokensCallback('SideNavItem')
+  const getTokens = useThemeTokensCallback('SideNavItem', tokens, variant)
   const getAppearanceState = ({ hovered }) => ({
     hover: hovered,
     active: isActive,
     expanded: isExpanded
   })
   const getPressableStyle = (pressableState) =>
-    selectItemStyles(getTokens(tokens, variant, getAppearanceState(pressableState)))
+    selectItemStyles(getTokens(getAppearanceState(pressableState)))
 
   return (
     <Pressable
@@ -79,7 +79,7 @@ const Item = ({
       testID={testID}
     >
       {(pressableState) => {
-        const themeTokens = getTokens(tokens, variant, getAppearanceState(pressableState))
+        const themeTokens = getTokens(getAppearanceState(pressableState))
         return <ItemContent tokens={themeTokens}>{children}</ItemContent>
       }}
     </Pressable>
@@ -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/SideNav/ItemsGroup.jsx

@@ -28,25 +28,23 @@ const ItemsGroup = ({
   onToggle
 }) => {
   // A SideNav control uses the same style and theme as SideNavItem, with a 'parent' variant,
-  // plus control-specific tokens from the SideNavItemsGroup theme.
+  // plus control-specific tokens from the SideNavItemsGroup theme (e.g. open/close icon, etc).
   const getAppearance = (appearance) => ({ ...variant, ...appearance, active: isActive })
   const getItemAppearance = (appearance) => ({ ...getAppearance(appearance), type: 'parent' })
 
-  // TODO: refactor useThemeTokensCallback return so it has the same shape as tokens prop functions
-  // https://github.com/telus/universal-design-system/issues/588
-  const getGroupTokens = useThemeTokensCallback('SideNavItemsGroup')
-  const panelTokensGetterProp = (appearance) =>
-    selectTokens('ExpandCollapsePanel', getGroupTokens(tokens, getAppearance(appearance)))
+  const getGroupTokens = useThemeTokensCallback('SideNavItemsGroup', tokens, variant)
+  const getPanelTokens = (appearance) =>
+    selectTokens('ExpandCollapsePanel', getGroupTokens(getAppearance(appearance)))
 
-  const getItemTokens = useThemeTokensCallback('SideNavItem')
-  const controlTokensGetterProp = (appearance) =>
+  const getItemTokens = useThemeTokensCallback('SideNavItem', itemTokens, variant)
+  const getControlTokens = (appearance) =>
     selectTokens('ExpandCollapseControl', {
-      ...getItemTokens(itemTokens, getItemAppearance(appearance)),
-      ...getGroupTokens(tokens, getAppearance(appearance))
+      ...getItemTokens(getItemAppearance(appearance)), // main style from SideNavItem
+      ...getGroupTokens(getAppearance(appearance)) // control-specific tokens like icon etc
     })
 
   const controlContent = (controlState) => {
-    const currentItemTokens = getItemTokens(itemTokens, getItemAppearance(controlState))
+    const currentItemTokens = getItemTokens(getItemAppearance(controlState))
     return <ItemContent tokens={currentItemTokens}>{label}</ItemContent>
   }
 
@@ -55,8 +53,8 @@ const ItemsGroup = ({
       openIds={openGroups}
       panelId={groupId}
       onToggle={onToggle}
-      tokens={panelTokensGetterProp}
-      controlTokens={controlTokensGetterProp}
+      tokens={getPanelTokens}
+      controlTokens={getControlTokens}
       control={controlContent}
       accessibilityState={{ active: isActive }} // ExpandCollapse.Panel handles expanded state
     >

package/src/SideNav/SideNav.jsx

@@ -62,6 +62,7 @@ const SideNav = ({ children, variant = {}, tokens, accordion = true, itemTokens,
           if (child.type === ItemsGroup) {
             const { groupId = `group-${index}` } = child.props
             const isGroupActive = active.itemId !== undefined && active.groupId === groupId
+            const handleToggle = (event) => onToggle(groupId, event)
             return (
               <ItemsGroup
                 {...child.props}
@@ -72,7 +73,7 @@ const SideNav = ({ children, variant = {}, tokens, accordion = true, itemTokens,
                 itemTokens={itemTokens}
                 openGroups={openIds}
                 isActive={isGroupActive}
-                onToggle={() => onToggle(groupId)}
+                onToggle={handleToggle}
               >
                 {React.Children.map(child.props.children, (item, itemIndex) =>
                   renderItem(item, itemIndex, groupId)

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