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

package/src/Pagination/usePagination.js

@@ -0,0 +1,69 @@
+/**
+ * Handles configurable truncating of pagination items.
+ *
+ * @param {object} props
+ * @param {React.Element[]} items
+ * @param {number} truncateAbove
+ */
+function usePagination({ items, truncateAbove }) {
+  const activeItemIndex = Math.max(
+    items.findIndex((item) => item.props.isActive),
+    0 // default to the first item if none is marked as active
+  )
+
+  const getItemProps = (index) => {
+    const { onPress, href, hrefAttrs, variant, tokens } = items[index]?.props ?? {}
+    return { onPress, href, hrefAttrs, variant, tokens }
+  }
+
+  const windowSize = truncateAbove > 4 ? 3 : 1
+  const truncateEnabled = items.length > truncateAbove
+
+  const truncateWindowStart = windowSize
+  const truncateWindowEnd = items.length - 1 - windowSize
+
+  // basically how many items next to the currently active one do we want to render
+  const activeWindowStart = activeItemIndex - (windowSize - 1) / 2
+  const activeWindowEnd = activeItemIndex + (windowSize - 1) / 2
+
+  const isFirstActive = activeItemIndex === 0
+  const isLastActive = activeItemIndex === items.length - 1
+
+  // start truncating when the active item is within the truncate window
+  const isLeftTruncated = truncateEnabled && activeItemIndex >= truncateWindowStart
+  const isRightTruncated = truncateEnabled && activeItemIndex <= truncateWindowEnd
+
+  function shouldRenderEllipsis(itemIndex) {
+    const isNextToFirst = itemIndex === 1
+    const isNextToLast = itemIndex === items.length - 2
+
+    return (isLeftTruncated && isNextToFirst) || (isRightTruncated && isNextToLast)
+  }
+
+  function shouldRenderButton(itemIndex) {
+    const isFirst = itemIndex === 0
+    const isLast = itemIndex === items.length - 1
+    const isInActiveWindow = itemIndex >= activeWindowStart && itemIndex <= activeWindowEnd
+
+    return (
+      isFirst ||
+      isLast ||
+      isInActiveWindow ||
+      (!isLeftTruncated && itemIndex <= truncateWindowStart) ||
+      (!isRightTruncated && itemIndex >= truncateWindowEnd)
+    )
+  }
+
+  return {
+    showPrevious: !isFirstActive,
+    showNext: !isLastActive,
+    shouldRenderButton,
+    shouldRenderEllipsis,
+    isItemActive: (itemIndex) => itemIndex === activeItemIndex,
+    getItemProps,
+    nextItemProps: getItemProps(activeItemIndex + 1),
+    previousItemProps: getItemProps(activeItemIndex - 1)
+  }
+}
+
+export default usePagination

package/src/Progress/Progress.jsx

@@ -0,0 +1,77 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+import { View } from 'react-native'
+
+import { a11yProps } from '../utils/propTypes'
+import { useThemeTokens } from '../ThemeProvider'
+import { getTokensPropType, variantProp } from '../utils'
+
+const selectProgressStyles = ({
+  backgroundColor,
+  borderWidth,
+  borderColor,
+  borderRadius,
+  height
+}) => ({
+  backgroundColor,
+  borderWidth,
+  borderColor,
+  borderRadius,
+  height
+})
+
+/**
+ * The `Progress` is a container for displaying one or several `ProgressBar`s.
+ *
+ * ## Props
+ *
+ * - Use `children` prop to pass one or multiple `ProgressBar`s. Note that in case of stacked progress bars
+ *   each next will be displayed on top of the previous one.
+ *
+ * ## Tokens
+ *
+ * - Use the following tokens to customize the appearance:
+ *   - `backgroundColor` for the background color of the progress container,
+ *   - `borderColor` to control the color of the border,
+ *   - `borderRadius` for the rounded corners,
+ *   - `borderWidth` to change the border width.
+ *   - `height` to control the height of the progress bars displayed within the progress bar container.
+ *
+ * ## Variants
+ *
+ * - Use the `size` variant to control the height of your progress bars:  passing `'mini'` will make your
+ *   progress bar container narrower.
+ *
+ * ## Usability and A11y guidelines
+ *
+ * `Progress` component accepts the standard accessibility properties, however it's more important to make sure
+ * its children (instances of `ProgressBar`) receive the accessibility properties specific to the `progressbar`
+ * role.
+ *
+ */
+const Progress = ({ children, tokens, variant, ...rest }) => {
+  const themeTokens = useThemeTokens('Progress', tokens, variant)
+
+  return (
+    <View style={selectProgressStyles(themeTokens)} {...a11yProps.select(rest)}>
+      {children}
+    </View>
+  )
+}
+
+Progress.propTypes = {
+  /**
+   * Use the `children` prop to supply one or several `ProgressBar`s.
+   */
+  children: PropTypes.node.isRequired,
+  /**
+   * Progress tokens.
+   */
+  tokens: getTokensPropType('Progress'),
+  /**
+   * Progress variant.
+   */
+  variant: variantProp.propType
+}
+
+export default Progress

package/src/Progress/ProgressBar.jsx

@@ -0,0 +1,110 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+import { StyleSheet, View } from 'react-native'
+
+import ProgressBarBackground from './ProgressBarBackground'
+import { a11yProps } from '../utils/propTypes'
+import { useThemeTokens } from '../ThemeProvider'
+import { getTokensPropType, variantProp } from '../utils'
+
+const selectBarStyles = (
+  { backgroundColor, borderRadius, outlineWidth, outlineColor },
+  percentage
+) => ({
+  backgroundColor,
+  borderRadius,
+  outlineWidth,
+  outlineColor,
+  width: `${percentage}%`
+})
+
+/**
+ * The `ProgressBar` is a visual representation of linear progression.
+ * It provides simple but important information at a quick glance.
+ *
+ * ## Props
+ *
+ * - Use `percentage` prop to indicate completion
+ *
+ * ## Tokens
+ *
+ * - Use the following tokens to customize the appearance:
+ *   - `backgroundColor` for the background color of the progress bar,
+ *   - `borderRadius` for the rounded corners,
+ *   - `outlineColor` to control the color of the border (outline),
+ *   - `outlineWidth` to change the outline width.
+ *
+ * ## Variants
+ *
+ * - Use the following variants to render specific types of progress bars:
+ *   - `negative`: set to `true` if you wish to use the negative theming for progress bar filling,
+ *   - `inactive`: set to `true` if you wish to style the progress bar as inactive.
+ *
+ * ## Usability and A11y guidelines
+ *
+ * `ProgressBar` component accepts all the standard accessibility properties including the ones that
+ * are specific to the `progressbar` role. By default the following props are used:
+ *
+ * - `accessibilityRole` (`role`): `progressbar`,
+ * - `accessibilityValue.min` (`aria-valuemin`): `0`,
+ * - `accessibilityValue.max` (`aria-valuemax`): `100`,
+ * - `accessibilityValue.now` (`aria-valuenow`): `percentage`,
+ * - `accessibilityValue.text` (`aria-valuetext`): `%{percentage}%`,
+ *
+ */
+const ProgressBar = ({ children = null, percentage = 0, tokens, variant, ...rest }) => {
+  const themeTokens = useThemeTokens('ProgressBar', tokens, variant)
+  if (percentage < 0) {
+    throw new Error('ProgressBar: `percentage` must be a positive number')
+  } else if (percentage > 100) {
+    throw new Error('ProgressBar: `percentage` cannot exceed 100')
+  }
+  const accessibilityProps = {
+    accessibilityRole: 'progressbar',
+    accessibilityValue: {
+      min: 0,
+      max: 100,
+      now: percentage,
+      text: `${percentage}%`
+    },
+    ...a11yProps.select(rest)
+  }
+
+  return percentage > 0 ? (
+    <View
+      style={[staticStyles.bar, selectBarStyles(themeTokens, percentage)]}
+      {...accessibilityProps}
+    >
+      {children ?? <ProgressBarBackground variant={variant} />}
+    </View>
+  ) : null
+}
+
+ProgressBar.propTypes = {
+  /**
+   * Optional children that can be used to customize the progress bar filling.
+   */
+  children: PropTypes.node,
+  /**
+   * Accessibility label for the progress bar.
+   */
+  accessibilityLabel: PropTypes.string.isRequired,
+  /**
+   * Percentage of completion.
+   */
+  percentage: PropTypes.number,
+  /**
+   * Progress bar tokens.
+   */
+  tokens: getTokensPropType('ProgressBar'),
+  /**
+   * Progress bar variant.
+   */
+  variant: variantProp.propType
+}
+
+export default ProgressBar
+
+const staticStyles = StyleSheet.create({
+  bar: { height: '100%', outlineStyle: 'solid', overflow: 'hidden', position: 'absolute' }
+})

package/src/Progress/ProgressBarBackground.jsx

@@ -0,0 +1,34 @@
+import React from 'react'
+import { ImageBackground, StyleSheet } from 'react-native'
+
+import { variantProp } from '../utils'
+
+const inactiveBackground = `%3Csvg xmlns='http://www.w3.org/2000/svg' width='100%25' height='24'%3E%3Cdefs%3E%3Cpattern id='DisabledProgress7' patternUnits='userSpaceOnUse' width='8' height='8'%3E%3Crect width='8' height='8' fill='%23B2B9BF'%3E%3C/rect%3E%3Ccircle cx='4' cy='4' r='2' fill='%23676E73' stroke='%23676E73' stroke-width='0'%3E%3C/circle%3E%3Ccircle cx='0' cy='0' r='2' fill='%23676E73' stroke='%23676E73' stroke-width='0'%3E%3C/circle%3E%3Ccircle cx='0' cy='8' r='2' fill='%23676E73' stroke='%23676E73' stroke-width='0'%3E%3C/circle%3E%3Ccircle cx='8' cy='0' r='2' fill='%23676E73' stroke='%23676E73' stroke-width='0'%3E%3C/circle%3E%3Ccircle cx='8' cy='8' r='2' fill='%23676E73' stroke='%23676E73' stroke-width='0'%3E%3C/circle%3E%3C/pattern%3E%3C/defs%3E%3Cpath d='M 0 0 L 0 140 L 2000 2000 L 2000 0 Z' style='fill: url("%23DisabledProgress7");'%3E%3C/path%3E%3C/svg%3E`
+const negativeBackground = `%3Csvg xmlns='http://www.w3.org/2000/svg' width='100%25' height='24'%3E%3Cdefs%3E%3Cpattern id='NegativeProgress6' patternUnits='userSpaceOnUse' width='8' height='8'%3E%3Crect width='8' height='8' fill='%23C12335'%3E%3C/rect%3E%3Cpath d='M 0,8 l 8,-8 M -2,2 l 4,-4 M 6,10 l 4,-4' stroke-width='2' shape-rendering='auto' stroke='%23e7adb4' stroke-linecap='square'%3E%3C/path%3E%3C/pattern%3E%3C/defs%3E%3Cpath d='M 0 0 L 0 140 L 2000 2000 L 2000 0 Z' style='fill: url("%23NegativeProgress6");'%3E%3C/path%3E%3C/svg%3E`
+const ProgressBarBackground = ({ variant }) => {
+  let source = null
+  if (variant?.inactive) {
+    source = inactiveBackground
+  } else if (variant?.negative) {
+    source = negativeBackground
+  } else {
+    return null
+  }
+  return (
+    <ImageBackground
+      source={{ uri: `data:image/svg+xml,${source}` }}
+      style={staticStyles.imageBackground}
+    />
+  )
+}
+
+ProgressBarBackground.propTypes = {
+  /**
+   * Progress bar variant.
+   */
+  variant: variantProp.propType
+}
+
+export default ProgressBarBackground
+
+const staticStyles = StyleSheet.create({ imageBackground: { height: '100%' } })

package/src/Progress/index.js

@@ -0,0 +1,6 @@
+import Progress from './Progress'
+import ProgressBar from './ProgressBar'
+
+Progress.Bar = ProgressBar
+
+export default Progress

package/src/Radio/Radio.jsx

@@ -0,0 +1,233 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+import { Pressable, StyleSheet, Text, View } from 'react-native'
+
+// @todo move `LabelContent` outside of the `InputLabel` and fix
+// the issue with the cursor not being pointer on Web
+import RadioLabel from '../InputLabel/LabelContent'
+import RadioButton, { selectRadioButtonTokens } from './RadioButton'
+import { applyShadowToken, applyTextStyles, useThemeTokensCallback } from '../ThemeProvider'
+import { getTokensPropType, useInputValue, useUniqueId, variantProp } from '../utils'
+import { a11yProps } from '../utils/propTypes'
+import StackView from '../StackView'
+
+const selectContainerStyles = ({
+  containerBackgroundColor,
+  containerBorderRadius,
+  containerOpacity,
+  containerPaddingBottom,
+  containerPaddingLeft,
+  containerPaddingRight,
+  containerPaddingTop,
+  containerShadow
+}) => ({
+  backgroundColor: containerBackgroundColor,
+  borderRadius: containerBorderRadius,
+  opacity: containerOpacity,
+  paddingBottom: containerPaddingBottom,
+  paddingLeft: containerPaddingLeft,
+  paddingRight: containerPaddingRight,
+  paddingTop: containerPaddingTop,
+  ...applyShadowToken(containerShadow)
+})
+const selectDescriptionStyles = ({
+  containerPaddingLeft = 0,
+  descriptionFontSize,
+  descriptionLineHeight,
+  descriptionMarginLeft,
+  inputSize,
+  labelMarginLeft = 0
+}) => ({
+  marginLeft: descriptionMarginLeft ?? containerPaddingLeft + inputSize + labelMarginLeft,
+  ...applyTextStyles({ fontSize: descriptionFontSize, lineHeight: descriptionLineHeight })
+})
+const selectLabelStyles = ({
+  labelColor,
+  labelFontName,
+  labelFontSize,
+  labelFontWeight,
+  labelMarginLeft,
+  labelLineHeight
+}) =>
+  applyTextStyles({
+    color: labelColor,
+    fontName: labelFontName,
+    fontWeight: labelFontWeight,
+    fontSize: labelFontSize,
+    lineHeight: labelLineHeight,
+    marginLeft: labelMarginLeft
+  })
+
+/**
+ * Basic Radio component.
+ *
+ * ## Component API
+ *
+ * Use `label` prop to provide a label for the radio button. For a disabled `Radio` set the `inactive` prop to `true`.
+ *
+ * ### Controlled version
+ *
+ * If the radio button is controlled from outside, it needs to receive `checked` and `onChange` props.
+ *
+ * ### Uncontrolled version
+ *
+ * In case of uncontrolled radio button you can use `defaultChecked` prop to provide the initial value.
+ * Whenever the radio button gets toggled, it calls the `onChange` callback with the new value (boolean).
+ *
+ * ### Using within forms
+ *
+ * You can pass `name` and `value` props if you need a particular radio button to be a part of a radio group
+ * on a form.
+ *
+ * ### Validation
+ *
+ * You can mark a radio button as failing validation by setting the `error` prop to `true`.
+ *
+ * ## A11y guidelines
+ *
+ * Radio component accepts all the common accessibility props, but also sets some defaults, including
+ * accessibility role `'radio'` and accessibility state that depends on the other props (`checked`, `inactive`)
+ * or the internal state in case of uncontrolled radio button.
+ *
+ */
+const Radio = ({
+  checked,
+  defaultChecked,
+  description,
+  error = false,
+  id,
+  inactive,
+  label,
+  name: inputName,
+  onChange,
+  tokens,
+  value,
+  variant,
+  ...rest
+}) => {
+  const { currentValue: isChecked, setValue: setIsChecked, isControlled } = useInputValue(
+    {
+      value: checked,
+      initialValue: defaultChecked,
+      onChange
+    },
+    'useRadioValue'
+  )
+  const getTokens = useThemeTokensCallback('Radio', tokens, {
+    checked: isChecked,
+    inactive,
+    error,
+    ...variant
+  })
+  const handleChange = (event) => {
+    if (!inactive && !isChecked) {
+      setIsChecked(true, event)
+    }
+  }
+  const handleKeyDown = (event) => {
+    // The expected keyboard shortcut for activating a radio is the Space key
+    if (event?.key === ' ') handleChange(event)
+  }
+  const accessibilityProps = a11yProps.select(rest)
+  const uniqueId = useUniqueId('radio')
+  const inputId = id ?? uniqueId
+
+  return (
+    <Pressable
+      disabled={inactive}
+      onKeyDown={handleKeyDown}
+      onPress={handleChange}
+      accessibilityRole="radio"
+      accessibilityState={{ checked: isChecked, disabled: inactive }}
+      {...accessibilityProps}
+    >
+      {({ focused: focus, hovered: hover, pressed }) => {
+        const stateTokens = getTokens({ focus, hover, pressed })
+
+        return (
+          <StackView space={0}>
+            <View style={[staticStyles.container, selectContainerStyles(stateTokens)]}>
+              <RadioButton
+                tokens={selectRadioButtonTokens(stateTokens)}
+                isControlled={isControlled}
+                isChecked={isChecked}
+                inactive={inactive}
+                defaultChecked={defaultChecked}
+                inputId={inputId}
+                handleChange={handleChange}
+                name={inputName}
+                value={value}
+              />
+              {Boolean(label) && (
+                <Text style={selectLabelStyles(stateTokens)}>
+                  <RadioLabel forId={inputId}>{label}</RadioLabel>
+                </Text>
+              )}
+            </View>
+            {Boolean(description) && (
+              <Text style={selectDescriptionStyles(getTokens())}>{description}</Text>
+            )}
+          </StackView>
+        )
+      }}
+    </Pressable>
+  )
+}
+
+Radio.propTypes = {
+  ...a11yProps.propTypes,
+  /**
+   * Use `checked` for controlled Radio. For uncontrolled Radio, use the `defaultChecked` prop.
+   */
+  checked: PropTypes.bool,
+  /**
+   * Use `defaultChecked` to provide the initial value for an uncontrolled Radio.
+   */
+  defaultChecked: PropTypes.bool,
+  /**
+   * An optional radio button description.
+   */
+  description: PropTypes.string,
+  /**
+   * Radio button ID.
+   */
+  id: PropTypes.string,
+  /**
+   * Whether the corresponding input is disabled or active.
+   */
+  inactive: PropTypes.bool,
+  /**
+   * The label.
+   */
+  label: PropTypes.string,
+  /**
+   * Associate this radio button with a group (set as the name attribute).
+   */
+  name: PropTypes.string,
+  /**
+   * Whether the underlying input triggered a validation error or not.
+   */
+  error: PropTypes.bool,
+  /**
+   * The value. Must be unique within the group.
+   */
+  value: PropTypes.oneOfType([PropTypes.string, PropTypes.number, PropTypes.bool]),
+  /**
+   * Callback called when a controlled radio button gets interacted with.
+   */
+  onChange: PropTypes.func,
+  /**
+   * Radio tokens.
+   */
+  tokens: getTokensPropType('Radio'),
+  /**
+   * Radio variant.
+   */
+  variant: variantProp.propType
+}
+
+export default Radio
+
+const staticStyles = StyleSheet.create({
+  container: { flexDirection: 'row', alignItems: 'center' }
+})

package/src/Radio/RadioButton.jsx

@@ -0,0 +1,131 @@
+import React from 'react'
+import PropTypes from 'prop-types'
+import { StyleSheet, View } from 'react-native'
+
+import RadioInput from './RadioInput'
+import { applyOuterBorder, resolveThemeTokens, validateThemeTokens } from '../ThemeProvider'
+import { getTokensSetPropType, selectTokens } from '../utils'
+
+// TODO: roll out a standard approach to token sets
+// https://github.com/telus/universal-design-system/issues/782
+const tokenKeys = [
+  'checkedBackgroundColor',
+  'checkedSize',
+  'inputBackgroundColor',
+  'inputBorderColor',
+  'inputBorderWidth',
+  'inputOutlineColor',
+  'inputOutlineWidth',
+  'inputSize',
+  'outerBorderColor',
+  'outerBorderWidth',
+  'outerBorderGap',
+  'inputSize'
+]
+
+export const selectRadioButtonTokens = (themeTokens, prefix) =>
+  selectTokens(tokenKeys, themeTokens, prefix)
+
+const getBorderRadius = (inputSize) => inputSize / 2
+
+const selectCheckedStyles = ({ checkedBackgroundColor, checkedSize }) => ({
+  backgroundColor: checkedBackgroundColor,
+  borderRadius: checkedSize / 2,
+  height: checkedSize,
+  width: checkedSize
+})
+
+const selectInputStyles = ({
+  inputBackgroundColor,
+  inputBorderColor,
+  inputBorderWidth,
+  inputOutlineColor,
+  inputOutlineWidth,
+  inputSize
+}) => ({
+  borderColor: inputBorderColor,
+  borderRadius: getBorderRadius(inputSize),
+  borderWidth: inputBorderWidth,
+  backgroundColor: inputBackgroundColor,
+  outlineStyle: 'solid',
+  outlineColor: inputOutlineColor,
+  outlineWidth: inputOutlineWidth,
+  height: inputSize,
+  width: inputSize
+})
+
+const selectOuterBorderStyles = ({
+  outerBorderColor,
+  outerBorderWidth,
+  outerBorderGap,
+  inputSize
+}) => ({
+  ...applyOuterBorder({
+    outerBorderColor,
+    outerBorderWidth,
+    outerBorderGap,
+    borderRadius: getBorderRadius(inputSize)
+  })
+})
+
+/**
+ * The visual toggle of a radio input. Is not interactive on its own, should be used inside
+ * an interactive parent that passes down props when interacted with.
+ */
+const RadioButton = ({
+  isChecked,
+  tokens,
+  inactive,
+  defaultChecked,
+  inputId,
+  isControlled,
+  handleChange,
+  name: inputName,
+  value
+}) => {
+  const themeTokens = validateThemeTokens(
+    resolveThemeTokens(tokens, { checked: isChecked }),
+    getTokensSetPropType(tokenKeys),
+    'RadioButton'
+  )
+
+  return (
+    <View style={selectOuterBorderStyles(themeTokens)}>
+      <View
+        style={[staticStyles.defaultInputStyles, selectInputStyles(themeTokens, isChecked)]}
+        testID="Radio-Input"
+      >
+        {/* Add a real input on Web, skip on native platforms */}
+        <RadioInput
+          checked={isChecked}
+          defaultChecked={defaultChecked}
+          disabled={inactive}
+          id={inputId}
+          isControlled={isControlled}
+          onChange={handleChange}
+          name={inputName}
+          value={value}
+        />
+        {isChecked && <View style={selectCheckedStyles(themeTokens)} testID="Radio-Checked" />}
+      </View>
+    </View>
+  )
+}
+
+RadioButton.propTypes = {
+  isChecked: PropTypes.bool,
+  tokens: getTokensSetPropType(tokenKeys, { allowFunction: true }),
+  inactive: PropTypes.bool,
+  defaultChecked: PropTypes.bool,
+  inputId: PropTypes.string,
+  isControlled: PropTypes.bool,
+  handleChange: PropTypes.func,
+  name: PropTypes.string,
+  value: PropTypes.bool
+}
+
+const staticStyles = StyleSheet.create({
+  defaultInputStyles: { alignItems: 'center', justifyContent: 'center' }
+})
+
+export default RadioButton