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

package/src/StackView/StackWrap.jsx

@@ -0,0 +1,33 @@
+import React from 'react'
+
+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
+
+  return gap === space && CSS?.supports('gap', exampleGapValue) ? (
+    // 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,82 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+import { View } from 'react-native'
+
+import { spacingProps, a11yProps, useSpacingScale } from '../utils'
+import { useThemeTokens } from '../ThemeProvider'
+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 = 'row',
+  children,
+  tokens,
+  variant,
+  ...rest
+}) => {
+  const themeTokens = useThemeTokens('StackView', tokens, variant)
+  const flexStyles = selectFlexStyles(themeTokens)
+  const a11y = a11yProps.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 {...a11y} style={[flexStyles, staticStyles.wrap, staticStyles[direction], offsetStyle]}>
+      {content}
+    </View>
+  )
+}
+
+StackWrapBox.propTypes = {
+  ...a11yProps.propTypes,
+  /**
+   * Sets the `flexDirection` of the container, or if 'inherit' returns spaced children as an array.
+   */
+  direction: PropTypes.oneOf(['column', 'row']),
+  /**
+   * 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,39 @@
+import React from 'react'
+import { View } from 'react-native'
+
+import StackWrapBox from './StackWrapBox'
+import { a11yProps, useSpacingScale } from '../utils'
+import { useThemeTokens } from '../ThemeProvider'
+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 = 'row', children, ...rest }) => {
+  const themeTokens = useThemeTokens('StackView', tokens, variant)
+  const flexStyles = selectFlexStyles(themeTokens)
+  const a11y = a11yProps.select({ ...rest })
+
+  const size = useSpacingScale(space)
+  const gapStyle = { gap: size }
+
+  const content = getStackedContent(children, { direction, space: 0 })
+
+  return (
+    <View {...a11y} 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'
+  }
+})

package/src/StackView/getStackedContent.jsx

@@ -0,0 +1,106 @@
+import React, { Children, Fragment } from 'react'
+
+import Box from '../Box'
+import Divider from '../Divider'
+import Spacer from '../Spacer'
+
+/**
+ * @typedef {import('react').ReactChildren} ReactChildren
+ * @typedef {import('react').ReactElement} ReactElement
+ * @typedef {import('../utils/propTypes.js').SpacingValue} SpacingValue
+ */
+
+/**
+ * Takes valid React Children and inserts a specified amount of space between each valid (not nullish) top
+ * level element, according to the provided `options`.
+ *
+ * Returns an array of the original elements plus inserted spacing elements.
+ * This array of elements is keyed and may be used as a component's `children` without mapping.
+ *
+ * @param {ReactChildren} children
+ * @param {object} [options] -
+ *  - `space`: amount of space to insert using the theme spacing scale (see `useSpacingScale`)
+ *  - `direction`: if 'row' or 'row-reverse', applies space horizontally, if 'column' or 'column-reverse', applies space vertically
+ *  - `box`: if truthy, wraps each valid child in a Box component; if an object, passes it to Box as props
+ *  - `divider`: if truthy, inserts Divider components; if an object, passes it to Divider as props
+ * @param {SpacingValue} [options.space]
+ * @param {boolean | object} [options.divider]
+ * @param {"row" | "column" | "row-reverse" | "column-reverse"} [options.direction]
+ * @returns {ReactElement[]}
+ */
+const getStackedContent = (children, { divider, space, direction = 'column', box }) => {
+  const boxProps = box && typeof box === 'object' ? box : { space }
+  const dividerProps = divider && typeof divider === 'object' ? divider : {}
+
+  // Avoid surprises if children contains comments, nulls, or is a variable wrapped as a fragment
+  const validChildren = Children.toArray(unpackFragment(children)).filter(Boolean)
+  const content = validChildren.reduce((newChildren, child, index) => {
+    const boxID = `Stack-Box-${index}`
+    const item = 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
+    )
+    if (!index || (!space && !divider)) return [...newChildren, item]
+
+    const testID = `Stack-${divider ? 'Divider' : 'Spacer'}-${index}`
+    const commonProps = { testID, key: testID, space }
+    const separator = divider ? (
+      <Divider vertical={direction.startsWith('row')} {...dividerProps} {...commonProps} />
+    ) : (
+      <Spacer direction={direction.startsWith('row') ? 'row' : 'column'} {...commonProps} />
+    )
+    return [...newChildren, separator, item]
+  }, [])
+
+  return content
+}
+
+/**
+ * Unpacks top-level fragments, so that common compositional patterns such as the following examples
+ * can be iterated as flat siblings (as if they were `<Child1 /><Child2 /><Child3 />`):
+ *
+ * - Setting `children` as a property wrapped in a fragment:
+ *
+ * ```jsx
+ * args.children = <><Child1 /><Child2 /><Child3 /></>
+ * ```
+ *
+ * - Defining `children` as a variable wrapped in a fragment:
+ *
+ * ```jsx
+ * const content = <><Child1 /><Child2 /><Child3 /></>
+ * if (someCondition) return <SomeWrapper>{content}</SomeWrapper>
+ * ```
+ *
+ * - Using fragments at the top level of a JSX block for conditional rendering:
+ *
+ * ```jsx
+ * <Child1 />
+ * {someCondition && (
+ *   <>
+ *     <Child2 />
+ *     <Child3 />
+ *   </>
+ * )}
+ * ```
+ *
+ * @param {ReactChildren} child
+ * @returns {ReactChildren}
+ */
+const unpackFragment = (child) => {
+  // If this level is a set of top-level siblings rather than one child, check each in turn
+  if (Children.count(child) > 1) return Children.map(child, unpackFragment)
+
+  // When a fragment is found, unpack its children to the top level and check them
+  if (child?.type === Fragment) return unpackFragment(child.props?.children)
+
+  // Stop unpacking as soon as any non-fragment child is found
+  return child
+}
+
+export default getStackedContent

package/src/StackView/index.js

@@ -0,0 +1,6 @@
+import StackView from './StackView'
+import StackWrap from './StackWrap'
+
+export default StackView
+export { StackWrap }
+export { default as getStackedContent } from './getStackedContent'

package/src/TextInput/TextInput.jsx

@@ -0,0 +1,325 @@
+import React, { useState } from 'react'
+import { View, TextInput as NativeTextInput, Platform, StyleSheet } from 'react-native'
+
+import PropTypes from 'prop-types'
+import { useThemeTokens, applyTextStyles } from '../ThemeProvider'
+import { getTokensPropType, useInputValue, variantProp } from '../utils'
+import InputLabel from '../InputLabel'
+import Feedback from '../Feedback'
+import Box from '../Box'
+import useUniqueId from '../utils/useUniqueId'
+
+const selectInputStyles = (
+  {
+    backgroundColor,
+    color,
+    borderWidth,
+    borderColor,
+    borderRadius,
+    paddingTop,
+    paddingBottom,
+    paddingLeft,
+    paddingRight = 0,
+    fontName,
+    fontSize,
+    fontWeight,
+    lineHeight,
+    icon,
+    iconSize = 0
+  },
+  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' && typeof borderWidth === 'number'
+      ? Math.max(0, value - borderWidth)
+      : value
+
+  const textStyles = applyTextStyles({ fontName, fontSize, lineHeight, fontWeight })
+  const webStyles = Platform.select({
+    web: {
+      outline: 'none',
+      cursor: inactive ? 'not-allowed' : undefined
+    }
+  })
+
+  const paddingWithIcon = iconSize + paddingRight
+
+  return {
+    backgroundColor,
+    color,
+    borderWidth,
+    borderColor,
+    borderRadius,
+    paddingLeft: offsetBorder(paddingLeft),
+    paddingRight: icon ? offsetBorder(paddingWithIcon) : offsetBorder(paddingRight),
+    paddingTop: offsetBorder(paddingTop),
+    paddingBottom: offsetBorder(paddingBottom),
+    ...textStyles,
+    ...webStyles
+  }
+}
+
+const selectOuterBorderStyles = ({
+  outerBackgroundColor,
+  outerBorderWidth = 0,
+  outerBorderColor,
+  outerBorderRadius = 0
+}) => {
+  // Use negative margins so that the outer border doesn't expand the input's bounding box
+  const margin = -1 * outerBorderWidth
+
+  // Account for the border width since we style it as an outline
+  const borderRadius = outerBorderRadius + outerBorderWidth
+
+  return {
+    background: outerBackgroundColor,
+    borderWidth: outerBorderWidth,
+    borderColor: outerBorderColor,
+    borderRadius,
+    marginTop: margin,
+    marginBottom: margin,
+    marginLeft: margin,
+    marginRight: margin
+  }
+}
+
+const selectIconTokens = ({ iconSize, iconColor }) => ({
+  size: iconSize,
+  color: iconColor
+})
+
+const joinDefined = (array) => array.filter((item) => item !== undefined).join(' ')
+
+/**
+ * A basic text input component. Use in forms or individually to receive user's input.
+ * Due to React Native's implementation of `TextInput` it's not possible to access the current value by passing a ref.
+ *
+ * ## Controlled component
+ * If it is required that the state of the `TextInput` be controlled by the application or other external methods,
+ * `value` and `onChange` props must be passed to the `TextInput`.
+ * If the `TextInput` value should not be changed by user input, a `readOnly` prop must be provided.
+ *
+ * ## Uncontrolled component
+ * If it is not necessary to control the `TextInput` state, you can create one without a value prop.
+ * In this case its value can be accessed within the `onChange` callback.
+ *
+ * NOTE: In order to support more advanced usages all additional props will be passed down to the React Native's
+ * `TextInput` component. See <a href="https://reactnative.dev/docs/textinput" target="_blank">React Native documentation</a> for
+ * supported props and <a href="https://reactnative.dev/docs/textinput" target="_blank">React Native Web documentation</a> for
+ * their implementation on the web.
+ */
+function TextInput({
+  value,
+  initialValue,
+  label,
+  hint,
+  hintPosition = 'inline',
+  feedback,
+  tooltip,
+  validation,
+  inactive,
+  readOnly,
+  onChange,
+  onChangeText,
+  onFocus,
+  onBlur,
+  onMouseOver,
+  onMouseOut,
+  tokens,
+  variant = {},
+  ...remainingProps
+}) {
+  const inputId = useUniqueId('text-input')
+  const hintId = useUniqueId('text-input-hint')
+  const feedbackId = useUniqueId('text-input-feedback')
+
+  const [isFocused, setIsFocused] = useState(false)
+  const handleFocus = (event) => {
+    setIsFocused(true)
+    if (typeof onFocus === 'function') onFocus(event)
+  }
+  const handleBlur = (event) => {
+    setIsFocused(false)
+    if (typeof onBlur === 'function') onBlur(event)
+  }
+
+  const [isHovered, setIsHovered] = useState(false)
+  const handleMouseOver = (event) => {
+    setIsHovered(true)
+    if (typeof onMouseOver === 'function') onMouseOver(event)
+  }
+  const handleMouseOut = (event) => {
+    setIsHovered(false)
+    if (typeof onMouseOut === 'function') onMouseOut(event)
+  }
+
+  const { currentValue, setValue, isControlled } = useInputValue({
+    value,
+    initialValue,
+    onChange,
+    readOnly
+  })
+
+  const handleChangeText = (text) => {
+    setValue(text)
+    if (typeof onChangeText === 'function') onChangeText(text)
+  }
+
+  const states = { focus: isFocused, hover: isHovered, inactive }
+
+  const themeTokens = useThemeTokens('TextInput', tokens, { ...variant, validation }, states)
+
+  const { icon: IconComponent } = themeTokens
+
+  const hasValidationError = validation === 'error'
+
+  const inputProps = {
+    ...remainingProps,
+    editable: !inactive,
+    onFocus: handleFocus,
+    onBlur: handleBlur,
+    onMouseOver: handleMouseOver,
+    onMouseOut: handleMouseOut,
+    onChangeText: handleChangeText,
+    accessibilityLabel: label,
+    accessibilityHint: joinDefined([!hasValidationError && feedback, hint]), // native only -> replaced with describedBy on web
+    accessibilityDescribedBy: joinDefined([
+      !hasValidationError && feedback && feedbackId, // feedback receives a11yRole=alert, so there's no need to include it here
+      hint && hintId
+    ]), // introduced in RNW 0.15.0
+    accessibilityInvalid: hasValidationError, // introduced in RNW 0.15.0
+    nativeID: inputId,
+    defaultValue: initialValue,
+    // currentValue is being updated even if the input is not controlled, passing it down to the
+    // Input could lead to changing its state from uncontrolled to controlled
+    value: isControlled ? currentValue : undefined
+  }
+
+  // TODO: use Stack instead of the Boxes
+
+  const feedbackVariant = {}
+
+  if (hasValidationError) {
+    feedbackVariant.state = 'error'
+  } else if (validation === 'success') {
+    feedbackVariant.state = 'success'
+  }
+
+  return (
+    <View>
+      {label && (
+        <Box bottom={1}>
+          <InputLabel
+            label={label}
+            hint={hint}
+            hintPosition={hintPosition}
+            hintId={hintId}
+            tooltip={tooltip}
+            forId={inputId}
+          />
+        </Box>
+      )}
+      <View style={selectOuterBorderStyles(themeTokens)}>
+        <NativeTextInput style={selectInputStyles(themeTokens, inactive)} {...inputProps} />
+        {IconComponent && (
+          <View
+            pointerEvents="none" // avoid hijacking input press events
+            style={[staticStyles.iconContainer, selectIconContainerStyles(themeTokens)]}
+          >
+            <IconComponent tokens={selectIconTokens(themeTokens)} />
+          </View>
+        )}
+      </View>
+      {feedback && (
+        <Box top={1}>
+          <Feedback
+            title={feedback}
+            variant={feedbackVariant}
+            accessibilityRole={hasValidationError ? 'alert' : undefined}
+          />
+        </Box>
+      )}
+    </View>
+  )
+}
+
+const selectIconContainerStyles = ({ paddingRight }) => ({
+  paddingRight
+})
+
+TextInput.propTypes = {
+  /**
+   * The input label.
+   */
+  label: PropTypes.string,
+  /**
+   * If the `TextInput's` state is to be controlled by a parent component, use this prop
+   * together with the `onChange` to pass down and update the lifted state.
+   */
+  value: PropTypes.string,
+  /**
+   * Use this to set the initial value of an uncontrolled `TextInput`.
+   * Updating `initialValue` will **not** update the actual value.
+   */
+  initialValue: PropTypes.string,
+  /**
+   * A short description of the expected input.
+   */
+  hint: PropTypes.string,
+  /**
+   * Position of the hint relative to label.
+   */
+  hintPosition: PropTypes.oneOf(['inline', 'below']),
+  /**
+   * A detailed description of validation error/success or additional instructions.
+   * Visual variant is determined based on the `validation` prop.
+   */
+  feedback: PropTypes.string,
+  /**
+   * Content of an optional `Tooltip`. If set, a tooltip button will be shown next to the label.
+   */
+  tooltip: PropTypes.string,
+  /**
+   * Use to visually mark an input as valid or invalid.
+   */
+  validation: PropTypes.oneOf(['error', 'success']),
+  /**
+   * Disables all user interactions with the input.
+   */
+  inactive: PropTypes.bool,
+  /**
+   * Makes it impossible to change the input's value.
+   */
+  readOnly: PropTypes.bool,
+  /**
+   * Use to react upon input's value changes. Required when the `value` prop is set.
+   * Will receive the input's value as an argument.
+   */
+  onChange: PropTypes.func,
+  /** @ignore */
+  onChangeText: PropTypes.func,
+  /** @ignore */
+  onFocus: PropTypes.func,
+  /** @ignore */
+  onBlur: PropTypes.func,
+  /** @ignore */
+  onMouseOver: PropTypes.func,
+  /** @ignore */
+  onMouseOut: PropTypes.func,
+  tokens: getTokensPropType('TextInput'),
+  variant: variantProp.propType
+}
+
+export default TextInput
+
+const staticStyles = StyleSheet.create({
+  iconContainer: {
+    position: 'absolute',
+    right: 0,
+    top: 0,
+    bottom: 0,
+    justifyContent: 'center'
+  }
+})

package/src/TextInput/index.js

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