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

package/src/TextInput/TextArea.jsx

@@ -0,0 +1,78 @@
+import React, { useState } from 'react'
+
+import { Platform } from 'react-native'
+import { getTokensPropType, variantProp } from '../utils'
+import InputSupports from '../InputSupports'
+import TextInputBase from './TextInputBase'
+import { useThemeTokens } from '../ThemeProvider'
+import inputSupportProps from '../InputSupports/propTypes'
+import textInputPropTypes from './propTypes'
+
+/**
+ * Use to collect long-form information such as product feedback or support queries.
+ * Due to React Native's implementation of `TextInput` it's not possible to access the current value by passing a ref.
+ * The `TextArea` height will automatically increase when new lines are added - this behavior can be limited within the theme.
+ *
+ * ## Controlled component
+ * If it is required that the state of the `TextArea` be controlled by the application or other external methods,
+ * `value` and `onChange` props must be passed to the `TextArea`.
+ * If the `TextArea` value should not be changed by user input, a `readOnly` prop must be provided.
+ *
+ * ## Uncontrolled component
+ * If it is not necessary to control the `TextArea` state, you can create one without a value prop.
+ * In this case its value can be accessed within the `onChange` callback.
+ *
+ * ## Getting feedback for entered values
+ * Use the `feedback` prop to give the user feedback regarding their input.
+ * You can affirm that the user's input 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.
+ *
+ * ## Supplying a hint
+ * Use the `hint` prop to succinctly clarify attributes of the expected input data, such as the expected format,
+ * or an indicator that the field is optional.
+ * It is a more usable and accessible option than the HTML `placeholder` attribute.
+ */
+function TextArea({ tokens, variant = {}, ...remainingProps }) {
+  const themeTokens = useThemeTokens('TextArea', tokens, variant)
+  const [inputHeight, setInputHeight] = useState()
+
+  // adjust the text area's height as new lines are added to the content
+  const onHeightChange = ({
+    nativeEvent: {
+      contentSize: { height }
+    }
+  }) => {
+    // on native this is happens out of the box
+    if (Platform.OS === 'web') {
+      setInputHeight(height)
+    }
+  }
+
+  const { props: supportsProps, rest } = inputSupportProps.select(remainingProps)
+
+  const inputProps = {
+    ...rest,
+    variant: { ...variant, validation: supportsProps.validation },
+    multiline: true,
+    onContentSizeChange: onHeightChange,
+    height: inputHeight,
+    tokens: themeTokens
+  }
+
+  return (
+    <InputSupports {...supportsProps}>
+      {({ a11yProps, inputId }) => (
+        <TextInputBase {...inputProps} {...a11yProps} nativeID={inputId} />
+      )}
+    </InputSupports>
+  )
+}
+
+TextArea.propTypes = {
+  ...inputSupportProps.types,
+  ...textInputPropTypes,
+  tokens: getTokensPropType('TextArea', 'TextInput'), // TODO: support both TextArea and TextInput tokens
+  variant: variantProp.propType
+}
+
+export default TextArea

package/src/TextInput/TextInput.jsx

@@ -0,0 +1,52 @@
+import React from 'react'
+
+import { getTokensPropType, variantProp } from '../utils'
+import InputSupports from '../InputSupports'
+import TextInputBase from './TextInputBase'
+import inputSupportProps from '../InputSupports/propTypes'
+import textInputPropTypes from './propTypes'
+
+/**
+ * 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({ tokens, variant = {}, ...remainingProps }) {
+  const { props: supportsProps, rest } = inputSupportProps.select(remainingProps)
+
+  const inputProps = {
+    ...rest,
+    tokens,
+    variant: { ...variant, validation: supportsProps.validation }
+  }
+
+  return (
+    <InputSupports {...supportsProps}>
+      {({ a11yProps, inputId }) => (
+        <TextInputBase {...inputProps} {...a11yProps} nativeID={inputId} />
+      )}
+    </InputSupports>
+  )
+}
+
+TextInput.propTypes = {
+  ...inputSupportProps.types,
+  ...textInputPropTypes,
+  tokens: getTokensPropType('TextInput'),
+  variant: variantProp.propType
+}
+
+export default TextInput

package/src/TextInput/TextInputBase.jsx

@@ -0,0 +1,211 @@
+import React, { useState } from 'react'
+import { Platform, StyleSheet, TextInput as NativeTextInput, View } from 'react-native'
+
+import PropTypes from 'prop-types'
+import { applyTextStyles, useThemeTokens, applyOuterBorder } from '../ThemeProvider'
+import { getTokensPropType, useInputValue, variantProp } from '../utils'
+
+const selectInputStyles = (
+  {
+    backgroundColor,
+    color,
+    borderWidth = 0,
+    borderColor,
+    borderRadius,
+    paddingTop = 0,
+    paddingBottom = 0,
+    paddingLeft,
+    paddingRight = 0,
+    fontName,
+    fontSize,
+    fontWeight,
+    lineHeight,
+    icon,
+    iconSize = 0,
+    minLines,
+    maxLines,
+    width,
+    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 })
+
+  function linesToHeight(lines) {
+    const { lineHeight: absoluteLineHeight } = textStyles
+
+    return lines !== undefined ? lines * absoluteLineHeight + paddingTop + paddingBottom : undefined
+  }
+
+  const minHeight = linesToHeight(minLines)
+  const maxHeight = linesToHeight(maxLines)
+
+  const webStyles = Platform.select({
+    web: {
+      outline: 'none',
+      cursor: inactive ? 'not-allowed' : undefined,
+      resize: minHeight !== maxHeight ? 'vertical' : 'none' // does nothing for an input, only needed for textarea
+    }
+  })
+
+  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),
+    minHeight,
+    maxHeight,
+    width,
+    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
+})
+
+function TextInputBase({
+  value,
+  height,
+  initialValue,
+  inactive,
+  readOnly,
+  onChange,
+  onChangeText,
+  onFocus,
+  onBlur,
+  onMouseOver,
+  onMouseOut,
+  tokens,
+  variant = {},
+  ...remainingProps
+}) {
+  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 = (event) => {
+    const text = event.nativeEvent?.text || event.target?.value
+    setValue(text, event)
+    if (typeof onChangeText === 'function') onChangeText(text, event)
+  }
+
+  const states = { focus: isFocused, hover: isHovered, inactive }
+
+  const themeTokens = useThemeTokens('TextInput', tokens, variant, states)
+
+  const { icon: IconComponent } = themeTokens
+
+  const inputProps = {
+    ...remainingProps,
+    editable: !inactive,
+    onFocus: handleFocus,
+    onBlur: handleBlur,
+    onMouseOver: handleMouseOver,
+    onMouseOut: handleMouseOut,
+    onChange: handleChangeText,
+    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
+  }
+
+  const nativeInputStyle = selectInputStyles({ ...themeTokens, height }, inactive)
+
+  return (
+    <View style={selectOuterBorderStyles(themeTokens)}>
+      <NativeTextInput style={nativeInputStyle} {...inputProps} />
+      {IconComponent && (
+        <View
+          pointerEvents="none" // avoid hijacking input press events
+          style={[staticStyles.iconContainer, selectIconContainerStyles(themeTokens)]}
+        >
+          <IconComponent {...selectIconTokens(themeTokens)} />
+        </View>
+      )}
+    </View>
+  )
+}
+
+TextInputBase.propTypes = {
+  value: PropTypes.string,
+  height: PropTypes.number,
+  initialValue: PropTypes.string,
+  inactive: PropTypes.bool,
+  readOnly: PropTypes.bool,
+  onChange: PropTypes.func,
+  onChangeText: PropTypes.func,
+  onFocus: PropTypes.func,
+  onBlur: PropTypes.func,
+  onMouseOver: PropTypes.func,
+  onMouseOut: PropTypes.func,
+  tokens: getTokensPropType('TextInput', 'TextArea'),
+  variant: variantProp.propType
+}
+
+export default TextInputBase
+
+const staticStyles = StyleSheet.create({
+  iconContainer: {
+    position: 'absolute',
+    right: 0,
+    bottom: 0
+  }
+})

package/src/TextInput/index.js

@@ -0,0 +1,4 @@
+import TextInput from './TextInput'
+import TextArea from './TextArea'
+
+export { TextInput, TextArea }

package/src/TextInput/propTypes.js

@@ -0,0 +1,29 @@
+import PropTypes from 'prop-types'
+
+const textInputPropTypes = {
+  /**
+   * If the input'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 input.
+   * Updating `initialValue` will **not** update the actual value.
+   */
+  initialValue: PropTypes.string,
+  /**
+   * 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
+}
+
+export default textInputPropTypes

package/src/ThemeProvider/ThemeProvider.jsx

@@ -1,18 +1,20 @@
 import React, { createContext, useState } from 'react'
 import PropTypes from 'prop-types'
+import { validateThemeTokensVersion } from './utils'
 
 export const uninitialisedError = new Error('Theme context used outside of ThemeProvider')
 
 export const ThemeContext = createContext(uninitialisedError)
 export const ThemeSetterContext = createContext(uninitialisedError)
 
-// TODO: develop this as theme metadata is added
-// https://github.com/telus/universal-design-system/issues/92
-export const themeType = PropTypes.object
-
 const ThemeProvider = ({ children, defaultTheme }) => {
   const [theme, setTheme] = useState(defaultTheme)
 
+  // Validate the theme tokens version on every render.
+  // This will intentionally break the application when attempting to use an invalid theme.
+  // This will surface an incompatibility quickly rather than allowing the potential for strange bugs due to missing or incompatible tokens.
+  validateThemeTokensVersion(theme)
+
   return (
     <ThemeSetterContext.Provider value={setTheme}>
       <ThemeContext.Provider value={theme}>{children}</ThemeContext.Provider>
@@ -21,10 +23,12 @@ const ThemeProvider = ({ children, defaultTheme }) => {
 }
 
 ThemeProvider.propTypes = {
-  // TODO: implement a custom propType that validates schema version
-  // https://github.com/telus/universal-design-system/issues/92
   children: PropTypes.node.isRequired,
-  defaultTheme: themeType.isRequired
+  defaultTheme: PropTypes.shape({
+    metadata: PropTypes.shape({
+      themeTokensVersion: PropTypes.string.isRequired
+    }).isRequired
+  }).isRequired
 }
 
 export default ThemeProvider

package/src/ThemeProvider/useSetTheme.js

@@ -4,6 +4,10 @@ import { ThemeSetterContext } from './ThemeProvider'
 const useSetTheme = () => {
   // Replace current theme with provided object
   const setTheme = useContext(ThemeSetterContext)
+  // Fail fast if dev uses useSetTheme outside of ThemeProvider
+  if (setTheme instanceof Error) {
+    throw setTheme
+  }
 
   // Merge provided object into current theme
   const editTheme = useCallback(

package/src/ThemeProvider/useThemeTokens.js

@@ -1,10 +1,37 @@
 import { useCallback } from 'react'
 import useTheme from './useTheme'
-import { getComponentTheme, getThemeTokens } from './utils'
+import { getComponentTheme, getThemeTokens, resolveThemeTokens, mergeAppearances } from './utils'
+/**
+ * @typedef {import('../utils/propTypes.js').AppearanceSet} AppearanceSet
+ * @typedef {import('../utils/propTypes.js').TokensProp} TokensProp
+ * @typedef {import('../utils/propTypes.js').TokensSet} TokensSet
+ */
 
 /**
  * Returns a complete set of theme tokens for a component based on which of the
  * component's theme rules apply to the current set of theme appearances.
+ *
+ * When applying theme tokens as styles to a component, don't spread the theme tokens
+ * object, explicitly select each property. This way, if new theme tokens are added to the
+ * component's theme in a minor or patch release of the theme package, the appearance
+ * of the component in sites and apps will only change when the component itself is updated.
+ *
+ * @example
+ * const seletContainerTokens = ({ color, width, height }) => ({
+ *   backgroundColor: color, width, height
+ * })
+ * const MyComponent = ({ tokens, variant, children }) => {
+ *   const viewport = useViewport()
+ *   const themeTokens = useThemeTokens('MyComponent', tokens, variant, { viewport })
+ *   const style = seletContainerTokens(themeTokens)
+ *   return <View style={style}>{children}</View>
+ * }
+ *
+ * @param {string} componentName - the name as defined in the theme schema of the component whose theme is to be used
+ * @param {TokensProp} [tokens] - every themed component should accept an optional `tokens` prop allowing theme tokens to be overridden
+ * @param {AppearanceSet} [variants] - every themed component should accept an optional `variants` prop specifying theme variants
+ * @param {AppearanceSet} [states] - optional object containing current theme appearances dictated by user action or context
+ * @returns {TokensSet} - the currently-applicable resolved set of theme tokens to apply
  */
 export const useThemeTokens = (componentName, tokens = {}, variants = {}, states = {}) => {
   const theme = useTheme()
@@ -14,16 +41,67 @@ export const useThemeTokens = (componentName, tokens = {}, variants = {}, states
 }
 
 /**
- * Returns a memoised function that behaves the same as useThemeTokens hook,
- * allowing tokens to be obtained inside callbacks and such other places where
- * calling useThemeTokens directly would be disallowed by React's hook rules.
+ * Returns a memoised tokens getter function that gets tokens similar to calling useThemeTokens.
+ * Scenarios where `useThemeTokensCallback` should be used instead of `useThemeTokens` include:
+ *
+ * - Where tokens are to be obtained from state that is accessible only in scopes like callbacks
+ *   and render functions, where calling useThemeTokens directly would be disallowed by React's hook rules.
+ * - Passing a tokens getter down via a child component's `tokens` prop, applying rules using the
+ *   child component's current state. Consider wrapping the returned tokens in `selectTokens()`.
+ *
+ * The function returned by `useThemeTokens` may be called with an object of state appearances to get an object
+ * of tokens, or may be passed as a `tokens` prop to other themed components or `useThemeTokens`/`useThemeTokensCallback`
+ * hooks.
+ *
+ * @example
+ * // Resolving tokens inside Pressable's style function, based on Pressable state
+ * const PressMe = ({ tokens, variant, children }) => {
+ *   const getTokens = useThemeTokensCallback('PressMe', tokens, variant)
+ *   const getPressableStyle = ({ pressed }) => {
+ *     const { color, width, height } = getTokens({ pressed })
+ *     return { backgroundColor: color, width, height }
+ *   }
+ *   return <Pressable style={getPressableStyle}>{children}</Pressable>
+ * }
+ *
+ * @example
+ * // Setting the theme in a parent and resolving it in a child based on child's state
+ * const MenuButton = ({ tokens, variant, ...buttonProps }) => {
+ *   // Define what theme, variant etc we want in this component...
+ *   const getTokens = useThemeTokensCallback('Button', tokens, variant)
+ *   // ...resolve them in another component based on its state (e.g. press, hover...)
+ *   return <ButtonBase tokens={getTokens} accessibilityRole="menuitem" {...buttonProps} />
+ * }
+ *
+ * @example
+ * // Chaining multiple themes together, sharing the same variants and state
+ * const GlowingLink = ({ tokens, variant, children }) => {
+ *   // applies a small theme for a glowing effect, using same variants and states as "link"
+ *   const getGlowTokens = useThemeCallback('GlowingLink', tokens, variant)
+ *   // applies link state to get "Link" theme tokens and merge "GlowingLink" tokens on top
+ *   const getTokens = useThemeCallback('Link', getGlowTokens, variant)
+ *   // renders a link with both themes applied, both based on current link state
+ *   return <LinkBase tokens={getTokens}>{children}</LinkBase>
+ * }
+ *
+ * @param {string} componentName - the name as defined in the theme schema of the component whose theme is to be used
+ * @param {TokensProp} [tokens] - every themed component should accept a `tokens` prop allowing theme tokens to be overridden
+ * @param {AppearanceSet} [variants] - variants passed in as props that don't change dynamically
+ * @returns {(states: AppearanceSet, tokenOverrides?: TokensProp) => TokensSet}
+ *    - callback function that returning an overridable tokens set for current state. Only pass
+ *      tokenOverrides in rare cases where tokens overrides are also generated outside hook scope,
+ *      e.g. if one theme tokens callback needs to pass certain token overrides to another.
  */
-export const useThemeTokensCallback = (componentName) => {
+export const useThemeTokensCallback = (componentName, tokens = {}, variants = {}) => {
   const theme = useTheme()
   const componentTheme = getComponentTheme(theme, componentName)
   const getThemeTokensCallback = useCallback(
-    (tokens, variants, states) => getThemeTokens(componentTheme, tokens, variants, states),
-    [componentTheme]
+    (states, tokenOverrides) => {
+      const appearances = mergeAppearances(variants, states)
+      const resolvedTokens = resolveThemeTokens(tokens, appearances, tokenOverrides)
+      return getThemeTokens(componentTheme, resolvedTokens, appearances)
+    },
+    [componentTheme, tokens, variants]
   )
   return getThemeTokensCallback
 }

package/src/ThemeProvider/utils/styles.js

@@ -9,6 +9,7 @@ import { fontBasePixels } from '@telus-uds/system-constants'
 // Make design tokens fit React Native's text styles' specific requirements and quirks
 export function applyTextStyles({
   fontSize,
+  fontScaleCap,
   lineHeight,
   letterSpacing,
   fontWeight = '400',
@@ -27,7 +28,7 @@ export function applyTextStyles({
     styles.lineHeight = lineHeight * (fontSize || fontBasePixels)
   }
 
-  if (typeof letterSpacing === 'number') {
+  if (typeof letterSpacing === 'number' && letterSpacing) {
     // Same as for line heights - React Native expects absolute letter spacing value
     styles.letterSpacing = letterSpacing * (fontSize || fontBasePixels)
   }
@@ -133,7 +134,19 @@ export function verticalAlignRow(verticalAlign, reverse = false) {
   }
 }
 
-// React Native Views behave like flex blocks. There's no CSS 'display' and they can't inline themselves
-export function applyLayoutStyles() {
-  // TODO: map design tokens to styles that implement inline, stretch, center, etc
-}
+/**
+ * Use on an outer container to create an outer border with an optional gap around it
+ * that matches the border radius of any inner border.
+ */
+export const applyOuterBorder = ({
+  outerBorderColor,
+  outerBorderWidth = 0,
+  outerBorderGap = 0,
+  borderRadius = 0
+}) => ({
+  margin: 0 - outerBorderWidth - outerBorderGap,
+  padding: outerBorderGap,
+  borderRadius: borderRadius + outerBorderGap + outerBorderWidth,
+  borderWidth: outerBorderWidth,
+  borderColor: outerBorderColor
+})