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

package/src/Divider/Divider.jsx

@@ -2,7 +2,12 @@ import React from 'react'
 import PropTypes from 'prop-types'
 import { View, StyleSheet, Platform } from 'react-native'
 import { useThemeTokens } from '../ThemeProvider'
-import { getTokensPropType, variantProp } from '../utils/propTypes'
+import Spacer from '../Spacer'
+import { getTokensPropType, variantProp, spacingProps } from '../utils'
+/**
+ * @typedef {import('../utils/propTypes.js').SpacingIndex} SpacingIndex
+ * @typedef {import('../utils/propTypes.js').SpacingObject} SpacingObject
+ */
 
 /**
  * A basic divider component, horizontal by default. Color and thickness can be controlled by theme.
@@ -16,11 +21,31 @@ import { getTokensPropType, variantProp } from '../utils/propTypes'
  *
  * In a flexbox row, vertical dividers will automatically size to their parent height.
  *
+ * ## Space
+ *
+ * Use this to create **space either side of the divider**. For simple cases, pass a number referring to
+ * a position on the theme's spacing scale; for example, this will put a Spacer of the smallest supported
+ * size either side of the divider:
+ *
+ * ```jsx
+ * <Divider space={1} />
+ * ```
+ *
+ * `space` prop uses `useSpacingScale` and may accept a {@link SpacingObject} or a {@link SpacingIndex} number.
+ *
+ * To **reduce the length of a divider** as well as creating space between it and its neighbours, wrap it in
+ * a `Box` component. For example, this will have the second-smallest theme-supported spacing value between
+ * the dividing line and its neighbours, and will shorten the line at either end by the same amount:
+ *
+ * ```jsx
+ * <Box space={2}><Divider /></Box>
+ * ```
+ *
  * ## Accessibility
  *
  * For accessibility purposes a divider component will be described with ARIA attributes, i.e. `role="separator"` and `aria-orientation="vertical/horizontal"`.
  */
-const Divider = ({ variant, vertical = false, tokens, testID }) => {
+const Divider = ({ variant, vertical = false, space, tokens, testID }) => {
   const { color, width } = useThemeTokens('Divider', tokens, variant)
 
   const borderStyles = vertical
@@ -43,11 +68,21 @@ const Divider = ({ variant, vertical = false, tokens, testID }) => {
       : // There are no such equivalent attributes for native
         {}
 
-  return <View style={[styles.divider, borderStyles]} testID={testID} {...a11y} />
+  const divider = <View style={[styles.divider, borderStyles]} testID={testID} {...a11y} />
+  if (!space) return divider
+  const spacerProps = { space, direction: vertical ? 'row' : 'column' }
+  return (
+    <>
+      <Spacer {...spacerProps} testID={testID ? `${testID}-Spacer-before` : undefined} />
+      {divider}
+      <Spacer {...spacerProps} testID={testID ? `${testID}-Spacer-after` : undefined} />
+    </>
+  )
 }
 
 Divider.propTypes = {
   tokens: getTokensPropType('Divider'),
+  space: spacingProps.types.spacingValue,
   variant: variantProp.propType,
   /**
    * By default, the divider is a horizontal line the full width of its parent.

package/src/ExpandCollapse/Control.jsx

@@ -56,7 +56,7 @@ const ExpandCollapseControl = ({
   variant,
   rest
 }) => {
-  const getTokens = useThemeTokensCallback('ExpandCollapseControl')
+  const getTokens = useThemeTokensCallback('ExpandCollapseControl', tokens, variant)
 
   const a11y = a11yProps.select({ ...rest, accessibilityRole })
   a11y.accessibilityState = {
@@ -70,8 +70,7 @@ const ExpandCollapseControl = ({
     focus: focused,
     expanded: isExpanded
   })
-  const getControlTokens = (pressableState) =>
-    getTokens(tokens, variant, getControlState(pressableState))
+  const getControlTokens = (pressableState) => getTokens(getControlState(pressableState))
   const getPressableStyle = (pressableState) =>
     selectContainerStyles(getControlTokens(pressableState))
 
@@ -83,7 +82,7 @@ const ExpandCollapseControl = ({
           <>
             {IconComponent && (
               <View style={selectIconContainerStyles(themeTokens)}>
-                <IconComponent tokens={selectIconTokens(themeTokens)} />
+                <IconComponent {...selectIconTokens(themeTokens)} />
               </View>
             )}
             {typeof children === 'function' ? children(getControlState(pressableState)) : children}

package/src/ExpandCollapse/Panel.jsx

@@ -55,9 +55,9 @@ const ExpandCollapsePanel = ({
     expanded: isExpanded
   })
 
-  const handleControlPress = () => {
-    onToggle(panelId)
-    if (onPress) onPress(panelId)
+  const handleControlPress = (event) => {
+    onToggle(panelId, event)
+    if (onPress) onPress(panelId, event)
   }
 
   const onContainerLayout = (event) => {

package/src/Feedback/Feedback.jsx

@@ -0,0 +1,108 @@
+import React from 'react'
+import { StyleSheet, Text, View } from 'react-native'
+import PropTypes from 'prop-types'
+
+import { applyTextStyles, useThemeTokens } from '../ThemeProvider'
+import { a11yProps, getTokensPropType, selectTokens, variantProp } from '../utils'
+import StackView from '../StackView'
+
+const selectStyles = (tokens) => selectTokens('Feedback', tokens)
+
+const selectTitleTextStyles = ({ titleFontSize, ...tokens }) =>
+  applyTextStyles(selectTokens('Typography', { ...tokens, fontSize: titleFontSize }))
+const selectContentTextStyles = ({ contentFontSize, ...tokens }) =>
+  applyTextStyles(selectTokens('Typography', { ...tokens, fontSize: contentFontSize }))
+
+const selectIconTokens = ({ iconSize, iconColor }) => ({
+  size: iconSize,
+  color: iconColor
+})
+
+const selectIconContainerStyles = ({ iconGap }) => ({
+  paddingRight: iconGap
+})
+
+/**
+ * A feedback box commonly used with form fields.
+ *
+ * ### Standalone usage
+ * While its primary use is to facilitate feedback states for other form components such as `TextInput`,
+ * you may use it standalone.
+ *
+ * ### Complex content
+ * You may pass any React tree as the children of this component, bear in mind that a render function
+ * is better suited for styling children based on Feedback's variant.
+ *
+ * ### Using a render function
+ * When a function is passed for rendering content, it will receive the feedback text styles and
+ * variant as arguments.
+ *
+ * ### Accessibility
+ * All accessibility props set on this component will be applied to the outer container.
+ */
+const Feedback = ({ title, children, id, validation, tokens, variant, ...rest }) => {
+  const themeTokens = useThemeTokens('Feedback', tokens, { ...variant, validation })
+  const { space } = themeTokens
+
+  const { icon: IconComponent } = themeTokens
+
+  const titleTextStyles = selectTitleTextStyles(themeTokens)
+  const contentTextStyles = selectContentTextStyles(themeTokens)
+
+  const content =
+    typeof children === 'string' ? <Text style={contentTextStyles}>{children}</Text> : children
+
+  const accessibilityProps = a11yProps.select({
+    accessibilityRole: validation === 'error' ? 'alert' : undefined,
+    ...rest
+  })
+
+  return (
+    <View style={selectStyles(themeTokens)} {...accessibilityProps} nativeID={id}>
+      <StackView space={space}>
+        {title !== undefined && (
+          <View style={staticStyles.title}>
+            {IconComponent && (
+              <View style={selectIconContainerStyles(themeTokens)}>
+                <IconComponent {...selectIconTokens(themeTokens)} />
+              </View>
+            )}
+            <Text style={titleTextStyles}>{title}</Text>
+          </View>
+        )}
+        {content && typeof content === 'function'
+          ? content({ textStyles: contentTextStyles, variant })
+          : content}
+      </StackView>
+    </View>
+  )
+}
+
+Feedback.propTypes = {
+  /**
+   * Emphasized summary of the feedback. If an icon is set, it is rendered next to the title.
+   */
+  title: PropTypes.string,
+  /**
+   * Feedback content rendered below the title. A render function `({textStyles, variant}) => {}` is supported.
+   */
+  children: PropTypes.oneOfType([PropTypes.string, PropTypes.node, PropTypes.func]),
+  /**
+   * Use to visually mark the Feedback as valid or invalid.
+   */
+  validation: PropTypes.oneOf(['error', 'success']),
+  /** @ignore */
+  id: PropTypes.string,
+  tokens: getTokensPropType('Feedback'),
+  variant: variantProp.propType
+}
+
+export default Feedback
+
+const staticStyles = StyleSheet.create({
+  title: {
+    display: 'flex',
+    flexDirection: 'row',
+    alignItems: 'center'
+  }
+})

package/src/Feedback/index.js

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

package/src/Fieldset/Fieldset.jsx

@@ -0,0 +1,129 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+
+import Feedback from '../Feedback'
+import { spacingProps } from '../utils'
+import FieldsetContainer from './FieldsetContainer'
+import { getStackedContent } from '../StackView'
+import InputLabel from '../InputLabel'
+import useInputSupports from '../InputSupports/useInputSupports'
+import Legend from './Legend'
+
+/**
+ * An alternative to InputSupports for groups of input elements that, on web, are to be
+ * wrapped in a `<fieldset>` tag, with label content displated in a `<legend>` tag.
+ *
+ * Follows the same theming and most of the same props as InputSupports.
+ */
+const Fieldset = ({
+  space,
+  feedback,
+  feedbackPosition = 'top',
+  validation,
+  legend,
+  hint,
+  hintPosition,
+  tooltip,
+  inactive,
+  accessibilityRole,
+  name: fieldsetName,
+  children
+}) => {
+  // Skips `inputId` because a fieldset' legend describes multiple inputs
+  const { hintId, feedbackId, a11yProps } = useInputSupports({
+    feedback,
+    hint,
+    label: legend,
+    validation
+  })
+
+  const legendContent = legend && (
+    <Legend>
+      <InputLabel
+        label={legend}
+        hint={hint}
+        hintPosition={hintPosition}
+        hintId={hintId}
+        tooltip={tooltip}
+      />
+    </Legend>
+  )
+  const feedbackContent = feedback && (
+    <Feedback id={feedbackId} title={feedback} validation={validation} />
+  )
+
+  // Some accessibility patterns depend on elements being direct children, e.g. fieldset -> legend,
+  // and on MacOS voiceover, radiogroup -> radio. To allow elements to be direct children of the
+  // fieldset as much as possible, but also allow different spacing within content and between
+  // fieldset / feedback / etc, wrap resolved children in a fragment, and stack with `preserveFragments`.
+  const childContent = <>{typeof children === 'function' ? children({ a11yProps }) : children}</>
+  const orderedContent =
+    feedbackPosition === 'bottom'
+      ? [legendContent, feedbackContent, childContent]
+      : [legendContent, childContent, feedbackContent]
+  const stackedContent = getStackedContent(orderedContent, { space, preserveFragments: true })
+
+  return (
+    <FieldsetContainer
+      inactive={inactive}
+      accessibilityRole={accessibilityRole}
+      name={fieldsetName}
+    >
+      {stackedContent}
+    </FieldsetContainer>
+  )
+}
+
+Fieldset.propTypes = {
+  children: PropTypes.oneOfType([PropTypes.func, PropTypes.node]),
+  /**
+   * The accessibility role of the `<fieldset>` element itself. Other React Native accessibility
+   * props are not supported because there is not an appropriate counterpart for Fieldsets.
+   */
+  accessibilityRole: PropTypes.string,
+  /**
+   * The amout of space between legend, feedback and content; 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 text for the fieldset's legend, describing the fieldset content.
+   */
+  legend: 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,
+  /**
+   * Position of the feedback block relative to the fieldset's content.
+   */
+  feedbackPosition: PropTypes.oneOf(['above', 'below']),
+  /**
+   * If true, the fieldset is treated as inactive (setting `disabled` attribute on web).
+   */
+  inactive: PropTypes.bool,
+  /**
+   * Content of an optional `Tooltip`. If set, a tooltip button will be shown next to the label.
+   */
+  tooltip: PropTypes.string,
+  /**
+   * On web, this is passed to the `<fieldset>`'s `name` attribute.
+   */
+  name: PropTypes.string,
+  /**
+   * Use to visually mark an input as valid or invalid.
+   */
+  validation: PropTypes.oneOf(['error', 'success'])
+}
+
+export default Fieldset

package/src/Fieldset/FieldsetContainer.jsx

@@ -0,0 +1,22 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+
+import cssReset from './cssReset'
+
+/**
+ * On Web, wraps children with a HTML `<fieldset>` and sets its attributes as necessary.
+ */
+const FieldsetContainer = ({ children, inactive, accessibilityRole, name: fieldsetName }) => (
+  <fieldset disabled={inactive} style={cssReset} role={accessibilityRole} name={fieldsetName}>
+    {children}
+  </fieldset>
+)
+
+FieldsetContainer.propTypes = {
+  accessibilityRole: PropTypes.string,
+  children: PropTypes.node,
+  inactive: PropTypes.bool,
+  name: PropTypes.string
+}
+
+export default FieldsetContainer

package/src/Fieldset/FieldsetContainer.native.jsx

@@ -0,0 +1,16 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+import { View } from 'react-native'
+
+// No equivalent of `<fieldset>` on native, so just apply accessibility role to container.
+// If a11y testing finds any additional handling is needed at the container level, add it here.
+const FieldsetContainer = ({ children, accessibilityRole }) => (
+  <View accessibilityRole={accessibilityRole}>{children}</View>
+)
+
+FieldsetContainer.propTypes = {
+  children: PropTypes.node,
+  accessibilityRole: PropTypes.string
+}
+
+export default FieldsetContainer

package/src/Fieldset/Legend.jsx

@@ -0,0 +1,16 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+
+import cssReset from './cssReset'
+
+/**
+ * On Web, wraps children in HTML `<legend>` tag.
+ * On Native, `<legend>` does not exist, wraps in a width 100% block to follow <legend>'s behaviour in a flex.
+ */
+const Legend = ({ children }) => <legend style={cssReset}>{children}</legend>
+
+Legend.propTypes = {
+  children: PropTypes.node
+}
+
+export default Legend

package/src/Fieldset/Legend.native.jsx

@@ -0,0 +1,22 @@
+import React from 'react'
+import { View, StyleSheet } from 'react-native'
+import PropTypes from 'prop-types'
+
+/**
+ * On Web, wraps children in HTML `<legend>` tag.
+ * On Native, `<legend>` does not exist, wraps in a width 100% block to follow <legend>'s behaviour in a flex.
+ */
+const Legend = ({ children }) => <View style={staticStyles.stretch}>{children}</View>
+
+Legend.propTypes = {
+  children: PropTypes.node
+}
+
+const staticStyles = StyleSheet.create({
+  stretch: {
+    width: '100%',
+    flexGrow: 1
+  }
+})
+
+export default Legend

package/src/Fieldset/cssReset.js

@@ -0,0 +1,14 @@
+// React Native Web has no built-in `fieldset` or `legend` support.
+// This reset makes them consistent with other RNW views.
+// Can't use RN stylesheets because it's not an RN element (RNW's createElement tooling is unstable).
+// Using CSS `all` doesn't work well as an inline style.
+// https://github.com/necolas/react-native-web/issues/1385
+export default {
+  margin: 'unset',
+  padding: 'unset',
+  float: 'unset',
+  border: 'unset',
+  width: 'unset',
+  display: 'flex',
+  flexDirection: 'column'
+}

package/src/Fieldset/index.js

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

package/src/FlexGrid/Col/Col.jsx

@@ -6,7 +6,7 @@ import { viewports } from '@telus-uds/system-constants'
 import GutterContext from '../providers/GutterContext'
 import { useViewport } from '../../ViewportProvider'
 import applyInheritance from '../helpers'
-import { responsivePropTypeFactory } from '../../utils'
+import { responsiveProps } from '../../utils'
 
 const Col = ({
   horizontalAlign,
@@ -258,7 +258,9 @@ Col.propTypes = {
    *
    * Accepts a `PropType.string` following the [responsive prop](#/Layout?id=responsive) structure.
    */
-  horizontalAlign: responsivePropTypeFactory(PropTypes.oneOf(['left', 'center', 'right']))
+  horizontalAlign: responsiveProps.getTypeOptionallyByViewport(
+    PropTypes.oneOf(['left', 'center', 'right'])
+  )
 }
 
 export default Col

package/src/HorizontalScroll/HorizontalScroll.jsx

@@ -0,0 +1,165 @@
+import React, { useEffect, useRef, useState } from 'react'
+import PropTypes from 'prop-types'
+import { Platform, StyleSheet, View } from 'react-native'
+
+import { validateThemeTokens, resolveThemeTokens } from '../ThemeProvider'
+import { getTokensSetPropType, selectTokens, a11yProps } from '../utils'
+import ScrollViewEnd from './ScrollViewEnd'
+import { getItemPositionScrollTarget, itemPositionsPropType } from './itemPositions'
+
+const tokenKeys = [
+  'nextIcon',
+  'previousIcon',
+  'gutter',
+  'borderBottomWidth',
+  'borderBottomColor',
+  'buttonClearance'
+]
+export const selectHorizontalScrollTokens = (themeTokens, prefix) =>
+  selectTokens(tokenKeys, themeTokens, prefix)
+
+/**
+ * Base component that scrolls horizontally and displays left and right buttons if
+ * there is content to the left and the right which can be scrolled to.
+ *
+ * @TODO revist `ScrollButton` after IconButton is stable.
+ */
+const HorizontalScroll = ({ ScrollButton, tokens, itemPositions, children, ...rest }) => {
+  const {
+    nextIcon,
+    previousIcon,
+    gutter,
+    borderBottomWidth,
+    borderBottomColor,
+    buttonClearance = 0
+  } = validateThemeTokens(
+    resolveThemeTokens(tokens),
+    // Allow missing icons
+    getTokensSetPropType(tokenKeys, { partial: true }),
+    'HorizontalScroll'
+  )
+
+  const [containerWidth, setContainerWidth] = useState(0)
+  const [contentWidth, setContentWidth] = useState(0)
+  const handleContentWidth = (width) => setContentWidth(width)
+  const handleContainerLayout = ({
+    nativeEvent: {
+      layout: { width }
+    }
+  }) => setContainerWidth(width)
+
+  // Update the scroll position only when scrolling actions ends to minimally rerender
+  // and update which buttons are conditionally rendered.
+  const [scrollOffset, setScrollOffset] = useState(0)
+  const handleScrollEnd = ({
+    nativeEvent: {
+      contentOffset: { x }
+    }
+  }) => {
+    setScrollOffset(x)
+  }
+
+  const scrollMax = Math.max(0, contentWidth - containerWidth)
+  const showNextButton = scrollOffset < scrollMax
+  const showPreviousButton = scrollOffset > 0
+
+  const scrollRef = useRef(null)
+  const scrollTo = (targetX) => {
+    if (typeof scrollRef.current?.scrollTo === 'function') {
+      const x = getItemPositionScrollTarget(
+        targetX,
+        scrollMax,
+        itemPositions.positions,
+        buttonClearance
+      )
+      scrollRef.current.scrollTo({ x, animated: true })
+
+      if (Platform.OS === 'android') {
+        // React Native calls onScrollMomentumEnd after scrollTo for iOS, but not Android.
+        // See https://github.com/facebook/react-native/issues/26661
+        // There's also no callback for when scrollTo finishes.
+        setTimeout(() => setScrollOffset(x), 300)
+      }
+    }
+  }
+  // Make scrollTo and relevant co-ordinates available to any component with an interest in itemPositions.
+  // ItemPositions is a mutable ref object intended to have its properties mutated without any rerenders.
+  /* eslint-disable-next-line no-param-reassign */
+  itemPositions.scrollTo = scrollTo
+  /* eslint-disable-next-line no-param-reassign */
+  itemPositions.containerWidth = containerWidth
+  /* eslint-disable-next-line no-param-reassign */
+  itemPositions.contentWidth = contentWidth
+  /* eslint-disable-next-line no-param-reassign */
+  itemPositions.scrollOffset = scrollOffset
+
+  const hasWidths = itemPositions.contentWidth > 0 && itemPositions.contentWidth > 0
+  useEffect(() => {
+    if (hasWidths) itemPositions.setIsReady(true)
+    // itemPositions is a ref object so this should occur only when elements' widths are set in state
+  }, [hasWidths, itemPositions])
+
+  // When scrolling, allow clearance around scroll buttons, so e.g. this...
+  // (<-) Item 5   Item 6   Item 7   Item 8   It(->)
+  // ...doesn't scroll like this with Item 9 never being properly visible:
+  // (<-)em 9   Item 10  Item 11  Item 12  Item (->)
+  const scrollDistance = containerWidth - buttonClearance * 2
+  const scrollNext = () => scrollTo(scrollOffset + scrollDistance)
+  const scrollPrevious = () => scrollTo(scrollOffset - scrollDistance)
+
+  const a11y = a11yProps.select(rest)
+
+  // On Web, being scrollable in one direction prevents overflow: visible in the other direction.
+  // Apply a fixed margin gutter that tab highlight effects can overhang without getting trimmed.
+  return (
+    <View style={staticStyles.container}>
+      <ScrollViewEnd
+        onScrollEnd={handleScrollEnd}
+        ref={scrollRef}
+        horizontal
+        onContentSizeChange={handleContentWidth}
+        onLayout={handleContainerLayout}
+        showsHorizontalScrollIndicator={false}
+        contentContainerStyle={[
+          staticStyles.scrollContainer,
+          { marginBottom: gutter, borderBottomWidth, borderBottomColor }
+        ]}
+        {...a11y}
+      >
+        {children}
+      </ScrollViewEnd>
+      {showPreviousButton && (
+        <ScrollButton
+          icon={previousIcon}
+          onPress={scrollPrevious}
+          offset={gutter}
+          direction="previous"
+        />
+      )}
+      {showNextButton && (
+        <ScrollButton icon={nextIcon} onPress={scrollNext} offset={gutter} direction="next" />
+      )}
+    </View>
+  )
+}
+
+const staticStyles = StyleSheet.create({
+  scrollContainer: {
+    // Gives inner container width from content, allowing it to exceed its container's width
+    alignSelf: 'flex-start',
+    flexGrow: 1
+  },
+  container: {
+    // Vertically center the ScrollButtons buttons
+    justifyContent: 'center'
+  }
+})
+
+HorizontalScroll.propTypes = {
+  itemPositions: itemPositionsPropType,
+  ScrollButton: PropTypes.elementType,
+  tokens: getTokensSetPropType(tokenKeys, { allowFunction: true }),
+  children: PropTypes.node
+}
+
+export default HorizontalScroll