@telus-uds/components-base 2.4.0 → 3.0.0

package/lib/esm/StackView/getStackedContent.js

@@ -0,0 +1,121 @@
+import React, { createElement as _createElement } 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/props/spacingProps.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
+ *  - `preserveFragments`: if true, adds no space between top-level elements that were passed inside a nested fragment
+ * @param {SpacingValue} [options.space]
+ * @param {boolean | object} [options.divider]
+ * @param {"row" | "column" | "row-reverse" | "column-reverse"} [options.direction]
+ * @param {boolean} [options.preserveFragments]
+ * @returns {ReactElement[]}
+ */
+import { jsx as _jsx } from "react/jsx-runtime";
+const getStackedContent = (children, _ref) => {
+  let {
+    divider,
+    space,
+    direction = 'column',
+    box,
+    preserveFragments = false
+  } = _ref;
+  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 topLevelChildren = preserveFragments ? children : unpackFragment(children);
+  const validChildren = React.Children.toArray(topLevelChildren).filter(Boolean);
+  const content = validChildren.reduce((newChildren, child, index) => {
+    const boxID = `Stack-Box-${index}`;
+    const item = box ?
+    /*#__PURE__*/
+    // If wrapped in Box, that Box needs a key.
+    // If possible, use an existing content key; use an index-based key only if necessary.
+    _createElement(Box, {
+      ...boxProps,
+      key: child.key || boxID,
+      testID: boxID
+    }, child) : child;
+    if (!index || !space && !divider) return [...newChildren, item];
+    const testID = `Stack-${divider ? 'Divider' : 'Spacer'}-${index}`;
+    const commonProps = {
+      testID,
+      space
+    };
+    const separator = divider ? /*#__PURE__*/_jsx(Divider, {
+      vertical: direction.startsWith('row'),
+      ...dividerProps,
+      ...commonProps
+    }, testID) : /*#__PURE__*/_jsx(Spacer, {
+      direction: direction.startsWith('row') ? 'row' : 'column',
+      ...commonProps
+    }, testID);
+    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 (React.Children.count(child) > 1) return React.Children.map(child, unpackFragment);
+
+  // When a fragment is found, unpack its children to the top level and check them
+  if (child?.type === React.Fragment) return unpackFragment(child.props?.children);
+
+  // Stop unpacking as soon as any non-fragment child is found
+  return child;
+};
+export default getStackedContent;

package/lib/esm/StepTracker/StepTracker.js

@@ -0,0 +1,213 @@
+import React from 'react';
+import PropTypes from 'prop-types';
+import Platform from "react-native-web/dist/exports/Platform";
+import StyleSheet from "react-native-web/dist/exports/StyleSheet";
+import Text from "react-native-web/dist/exports/Text";
+import View from "react-native-web/dist/exports/View";
+import StackView from '../StackView';
+import { applyTextStyles, useTheme, useThemeTokens } from '../ThemeProvider';
+import { a11yProps, getTokensPropType, selectSystemProps, variantProp, viewProps } from '../utils';
+import { useViewport } from '../ViewportProvider';
+import useCopy from '../utils/useCopy';
+import Step from './Step';
+import defaultDictionary from './dictionary';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const [selectProps, selectedSystemPropTypes] = selectSystemProps([a11yProps, viewProps]);
+const selectContainerStyles = _ref => {
+  let {
+    containerPaddingBottom,
+    containerPaddingLeft,
+    containerPaddingRight,
+    containerPaddingTop
+  } = _ref;
+  return {
+    paddingBottom: containerPaddingBottom,
+    paddingLeft: containerPaddingLeft,
+    paddingRight: containerPaddingRight,
+    paddingTop: containerPaddingTop
+  };
+};
+const selectStepTrackerLabelContainerStyles = _ref2 => {
+  let {
+    labelMarginTop
+  } = _ref2;
+  return {
+    marginTop: labelMarginTop
+  };
+};
+const selectStepTrackerLabelStyles = (_ref3, themeOptions) => {
+  let {
+    labelColor,
+    labelFontSize,
+    labelFontWeight,
+    labelFontName,
+    labelLineHeight
+  } = _ref3;
+  return applyTextStyles({
+    color: labelColor,
+    fontSize: labelFontSize,
+    lineHeight: labelLineHeight,
+    fontWeight: labelFontWeight,
+    fontName: labelFontName,
+    themeOptions
+  });
+};
+
+/**
+ * StepTracker component shows the current position in a sequence of steps.
+ *
+ * ## Component API
+ *
+ * - `current` prop allows to control the current step, 0-based number;
+ * - use `copy` and `dictionary` props to internationalize the labels;
+ * - `steps` is and array of strings defining step titles;
+ * - tokens and variant props define the appearance of the `StepTracker`:
+ *
+ * ## Usability and A11y guidelines
+ *
+ * Keep in mind that in its current implementation this is not an interactive
+ * component and can't be used to navigate between steps. The application
+ * must provide its own navigation mechanism and state control. That is the
+ * main reason the component assumes the `progressbar` role in terms of
+ * accessibility. This also makes it extremely important to make sure you
+ * set a11y on controls used to modify the state of the step tracker.
+ *
+ * You can pass standard a11y props to the `StepTracker` component, including
+ * the ones that are specific to the `progressbar` role. By default the
+ * following props are used:
+ *
+ * - `accessibilityRole` (`role`): `progressbar`,
+ * - `accessibilityLabel` (`aria-label`): `Step I of N: <Current Step Label>`,
+ * - `accessibilityLevel` (`aria-level`): 1,
+ * - `accessibilityValue.min` (`aria-valuemin`): `0`,
+ * - `accessibilityValue.max` (`aria-valuemax`): `steps.length - 1`,
+ * - `accessibilityValue.now` (`aria-valuenow`): `current`,
+ * - `accessibilityValue.text` (`aria-valuetext`): `<Current Step Label>`,
+ *
+ */
+const StepTracker = /*#__PURE__*/React.forwardRef((_ref4, ref) => {
+  let {
+    current = 0,
+    copy = 'en',
+    dictionary = defaultDictionary,
+    steps = [],
+    tokens,
+    variant,
+    ...rest
+  } = _ref4;
+  const viewport = useViewport();
+  const {
+    showStepTrackerLabel,
+    ...themeTokens
+  } = useThemeTokens('StepTracker', tokens, variant, {
+    viewport
+  });
+  const {
+    textStepTrackerLabel
+  } = themeTokens;
+  const getCopy = useCopy({
+    dictionary,
+    copy
+  });
+  const stepTrackerLabel = showStepTrackerLabel ? (typeof copy === 'string' ? getCopy(textStepTrackerLabel ?? 1).stepTrackerLabel : getCopy('stepTrackerLabel')).replace('%{stepNumber}', current < steps.length ? current + 1 : steps.length).replace('%{stepCount}', steps.length).replace('%{stepLabel}', current < steps.length ? steps[current] : steps[steps.length - 1]) : getCopy('stepTrackerLabel');
+  const getStepLabel = index => {
+    if (themeTokens.showStepLabel) {
+      return getCopy(index + 1)?.stepLabel.replace('%{stepNumber}', index + 1);
+    }
+    return '';
+  };
+  const {
+    themeOptions
+  } = useTheme();
+  if (!steps.length) return null;
+  const selectedProps = selectProps({
+    accessibilityLabel: stepTrackerLabel,
+    accessibilityRole: 'progressbar',
+    accessibilityValue: {
+      min: 0,
+      max: steps.length - 1,
+      now: current,
+      text: steps[current]
+    },
+    ...rest
+  });
+  const stepsContainerAccessibilityRole = Platform.OS === 'web' ? 'list' : 'tablist';
+  const stepAccessibilityRole = Platform.OS === 'web' ? 'listitem' : 'tab';
+  return /*#__PURE__*/_jsx(View, {
+    ref: ref,
+    style: selectContainerStyles(themeTokens),
+    ...selectedProps,
+    children: /*#__PURE__*/_jsxs(StackView, {
+      space: 0,
+      children: [/*#__PURE__*/_jsx(View, {
+        style: staticStyles.stepsContainer,
+        accessibilityRole: stepsContainerAccessibilityRole,
+        children: steps.map((label, index) => {
+          return /*#__PURE__*/_jsx(Step, {
+            status: current,
+            label: label,
+            name: getStepLabel(index),
+            stepIndex: index,
+            stepCount: steps.length,
+            tokens: themeTokens,
+            accessibilityRole: stepAccessibilityRole,
+            accessibilityCurrent: current === index && Platform.OS === 'web' && 'step'
+          }, label);
+        })
+      }), showStepTrackerLabel && /*#__PURE__*/_jsx(View, {
+        style: [staticStyles.stepTrackerLabelContainer, selectStepTrackerLabelContainerStyles(themeTokens)],
+        children: /*#__PURE__*/_jsx(Text, {
+          style: selectStepTrackerLabelStyles(themeTokens, themeOptions),
+          accessibilityRole: "header",
+          accessibilityLevel: 2,
+          children: stepTrackerLabel
+        })
+      })]
+    })
+  });
+});
+StepTracker.displayName = 'StepTracker';
+
+// If a language dictionary entry is provided, it must contain every key
+const dictionaryContentShape = PropTypes.shape({
+  stepLabel: PropTypes.string.isRequired,
+  stepTrackerLabel: PropTypes.string.isRequired
+});
+StepTracker.propTypes = {
+  ...selectedSystemPropTypes,
+  /**
+   * The current step, 0-based number
+   */
+  current: PropTypes.number,
+  /**
+   * The language to use for the labels
+   */
+  copy: PropTypes.oneOfType([PropTypes.oneOf(['en', 'fr']), dictionaryContentShape]),
+  /**
+   * Custom dictionary containing the labels to use for the steps
+   */
+  dictionary: PropTypes.shape({
+    en: dictionaryContentShape,
+    fr: dictionaryContentShape
+  }),
+  /**
+   * An array of strings defining the step titles
+   */
+  steps: PropTypes.arrayOf(PropTypes.string),
+  tokens: getTokensPropType('StepTracker'),
+  variant: variantProp.propType
+};
+export default StepTracker;
+const staticStyles = StyleSheet.create({
+  stepsContainer: {
+    alignItems: 'flex-start',
+    flexDirection: 'row',
+    justifyContent: 'space-evenly',
+    flexGrow: 1
+  },
+  stepTrackerLabelContainer: {
+    textAlign: 'center',
+    flexDirection: 'row',
+    justifyContent: 'center'
+  }
+});

package/lib/esm/TabBar/TabBar.js

@@ -0,0 +1,125 @@
+import React from 'react';
+import PropTypes from 'prop-types';
+import View from "react-native-web/dist/exports/View";
+import StyleSheet from "react-native-web/dist/exports/StyleSheet";
+import TabBarItem from './TabBarItem';
+import { useThemeTokens } from '../ThemeProvider';
+import { variantProp, getTokensPropType, selectSystemProps, a11yProps, viewProps } from '../utils';
+import { jsx as _jsx } from "react/jsx-runtime";
+const selectTabBarContainerStyles = _ref => {
+  let {
+    paddingTop,
+    paddingBottom,
+    borderTopWidth,
+    borderTopColor,
+    backgroundColor
+  } = _ref;
+  return {
+    paddingTop,
+    paddingBottom,
+    borderTopWidth,
+    borderTopColor,
+    backgroundColor
+  };
+};
+const selectTabBarItemContainerStyles = _ref2 => {
+  let {
+    paddingLeft,
+    paddingRight,
+    gap
+  } = _ref2;
+  return {
+    paddingLeft,
+    paddingRight,
+    gap
+  };
+};
+const [selectProps, selectedSystemPropTypes] = selectSystemProps([a11yProps, viewProps]);
+
+/**
+ * TabBar component renders a navigation bar with multiple TabBarItems.
+ * It allows users to switch between different views or sections.
+ *
+ * @component
+ * @example
+ * const items = [
+ *   { id: '1', label: 'Home', icon: <HomeIcon />, iconActive: <HomeActiveIcon /> },
+ *   { id: '2', label: 'Profile', icon: <ProfileIcon />, iconActive: <ProfileActiveIcon /> },
+ * ]
+ * return (
+ *   <TabBar
+ *     items={items}
+ *     initiallySelectedItem="1"
+ *     onChange={(itemId) => console.log(itemId)}
+ *   />
+ * )
+ */
+
+const TabBar = /*#__PURE__*/React.forwardRef((_ref3, ref) => {
+  let {
+    items = [],
+    initiallySelectedItem = '0',
+    onChange,
+    variant,
+    tokens,
+    ...rest
+  } = _ref3;
+  const [isSelected, setIsSelected] = React.useState(initiallySelectedItem);
+  const themeTokens = useThemeTokens('TabBar', tokens, variant);
+  const handlePress = itemId => {
+    setIsSelected(itemId);
+    onChange?.(itemId);
+  };
+  return /*#__PURE__*/_jsx(View, {
+    ref: ref,
+    style: [styles.tabBar, selectTabBarContainerStyles(themeTokens)],
+    ...selectProps(rest),
+    children: /*#__PURE__*/_jsx(View, {
+      style: [styles.tabBarItem, selectTabBarItemContainerStyles(themeTokens)],
+      children: items.map((item, index) => /*#__PURE__*/_jsx(TabBarItem, {
+        label: item.label,
+        href: item.href,
+        isSelected: isSelected === item.id,
+        icon: item.icon,
+        iconActive: item.iconActive,
+        onPress: () => handlePress(item.id),
+        id: `tab-item-${index}`,
+        accessibilityRole: "tablist"
+      }, item.id))
+    })
+  });
+});
+TabBar.displayName = 'TabBar';
+TabBar.propTypes = {
+  ...selectedSystemPropTypes,
+  /** Array of TabBarItems to be displayed in TabBar */
+  items: PropTypes.arrayOf(PropTypes.shape({
+    id: PropTypes.string.isRequired,
+    icon: PropTypes.node,
+    iconActive: PropTypes.node,
+    label: PropTypes.string.isRequired,
+    href: PropTypes.string
+  })).isRequired,
+  /** Id of the initially selected item. */
+  initiallySelectedItem: PropTypes.number,
+  /** Callback function to handle item selection change. */
+  onChange: PropTypes.func,
+  /** Variant of TabBar for styling purposes. */
+  variant: variantProp.propType,
+  /** Tokens for theming and styling. */
+  tokens: getTokensPropType('TabBar')
+};
+const styles = StyleSheet.create({
+  tabBar: {
+    flex: 1,
+    justifyContent: 'center',
+    alignItems: 'center'
+  },
+  tabBarItem: {
+    flex: 1,
+    flexDirection: 'row',
+    justifyContent: 'space-between',
+    width: '100%'
+  }
+});
+export default TabBar;

package/lib/esm/Tabs/Tabs.js

@@ -0,0 +1,179 @@
+import React from 'react';
+import Platform from "react-native-web/dist/exports/Platform";
+import PropTypes from 'prop-types';
+import ABBPropTypes from 'airbnb-prop-types';
+import { useThemeTokens } from '../ThemeProvider';
+import StackView from '../StackView';
+import { a11yProps, getTokensPropType, focusHandlerProps, pressProps, selectSystemProps, useHash, useInputValue, variantProp, viewProps, withLinkRouter } from '../utils';
+import HorizontalScroll, { horizontalScrollUtils, HorizontalScrollButton } from '../HorizontalScroll';
+import TabsItem from './TabsItem';
+import { jsx as _jsx } from "react/jsx-runtime";
+const [selectProps, selectedSystemPropTypes] = selectSystemProps([a11yProps, viewProps]);
+const [selectItemProps, selectedItemPropTypes] = selectSystemProps([a11yProps, focusHandlerProps, pressProps, viewProps]);
+const {
+  selectHorizontalScrollTokens,
+  useItemPositions
+} = horizontalScrollUtils;
+const getDefaultTabItemAccessibilityRole = parentRole => {
+  switch (parentRole) {
+    case 'tablist':
+      return 'tab';
+    case 'navigation':
+      return 'link';
+    default:
+      return undefined;
+  }
+};
+const getStackViewTokens = variant => {
+  const equalWidth = variant?.equalWidth;
+  return Platform.select({
+    web: {
+      justifyContent: equalWidth ? 'space-evenly' : 'flex-start',
+      width: equalWidth ? '100%' : 'auto'
+    },
+    default: {}
+  });
+};
+
+/**
+ * Tabs renders a horizontally-scrolling menu of selectable buttons which may link
+ * to a page or control what content is displayed on this page.
+ *
+ * If you are using Tabs to navigate to a new page (web-only) you should pass
+ * `navigation`as the `accessibilityRole` to te Tabs component, this will cause
+ * TabItems to default to a role of link and obtain aria-current behaviour.
+ */
+const Tabs = /*#__PURE__*/React.forwardRef((_ref, ref) => {
+  let {
+    tokens,
+    itemTokens,
+    scrollButtonTokens,
+    variant,
+    value,
+    initialValue,
+    onChange,
+    items = [],
+    LinkRouter,
+    linkRouterProps,
+    ...rest
+  } = _ref;
+  const {
+    space,
+    ...themeTokens
+  } = useThemeTokens('Tabs', tokens, variant);
+  const {
+    currentValue,
+    setValue
+  } = useInputValue({
+    value,
+    initialValue,
+    onChange
+  });
+  const [itemPositions, isPositioningReady] = useItemPositions();
+  useHash(React.useCallback((hash, event) => {
+    const hashItem = hash && items.find(_ref2 => {
+      let {
+        href
+      } = _ref2;
+      return hash === href;
+    });
+    const hashId = hashItem && (hashItem.id || hashItem.label);
+    if (hashId) setTimeout(setValue(hashId, event), 500);
+  }, [items, setValue]), isPositioningReady);
+  const restProps = selectProps(rest);
+  const parentAccessibilityRole = restProps.accessibilityRole ?? 'tablist';
+  const defaultTabItemAccessibiltyRole = getDefaultTabItemAccessibilityRole(parentAccessibilityRole);
+  const stackViewTokens = getStackViewTokens(variant);
+  return /*#__PURE__*/_jsx(HorizontalScroll, {
+    ref: ref,
+    ScrollButton: HorizontalScrollButton,
+    itemPositions: itemPositions,
+    tokens: selectHorizontalScrollTokens(themeTokens),
+    scrollButtonTokens: scrollButtonTokens,
+    accessibilityRole: parentAccessibilityRole,
+    ...restProps,
+    children: /*#__PURE__*/_jsx(StackView, {
+      space: space,
+      direction: "row",
+      tokens: stackViewTokens,
+      children: items.map((_ref3, index) => {
+        let {
+          href,
+          label,
+          id,
+          accessibilityRole = defaultTabItemAccessibiltyRole,
+          onPress,
+          ref: itemRef,
+          LinkRouter: ItemLinkRouter = LinkRouter,
+          linkRouterProps: itemLinkRouterProps,
+          render,
+          ...itemRest
+        } = _ref3;
+        const itemId = id ?? label;
+        const isSelected = Boolean(currentValue && currentValue === itemId);
+        const handlePress = event => {
+          if (typeof onPress === 'function') onPress(event);
+          setValue(itemId, event);
+        };
+        const itemProps = selectItemProps(itemRest);
+        return /*#__PURE__*/_jsx(TabsItem, {
+          ref: itemRef,
+          id: itemId,
+          href: href,
+          variant: variant,
+          tokens: itemTokens,
+          onPress: handlePress,
+          selected: isSelected,
+          itemPositions: itemPositions,
+          index: index,
+          accessibilityRole: accessibilityRole,
+          LinkRouter: ItemLinkRouter,
+          linkRouterProps: {
+            ...linkRouterProps,
+            ...itemLinkRouterProps
+          },
+          render: render,
+          ...itemProps,
+          children: label
+        }, itemId);
+      })
+    })
+  });
+});
+Tabs.displayName = 'Tabs';
+Tabs.propTypes = {
+  ...selectedSystemPropTypes,
+  ...withLinkRouter.PropTypes,
+  /**
+   * Array of `TabsItem`s
+   */
+  items: PropTypes.arrayOf(PropTypes.shape({
+    ...selectedItemPropTypes,
+    ...withLinkRouter.PropTypes,
+    href: PropTypes.string,
+    label: PropTypes.string,
+    id: PropTypes.string,
+    ref: ABBPropTypes.ref(),
+    render: PropTypes.func
+  })),
+  /**
+   * `id` property of the current tab in the items array
+   */
+  value: PropTypes.string,
+  initialValue: PropTypes.string,
+  /**
+   * Callback for when the selected tab changes
+   */
+  onChange: PropTypes.func,
+  tokens: getTokensPropType('Tabs'),
+  /**
+   * Custom tokens for `TabsItem`
+   */
+  itemTokens: getTokensPropType('TabsItem'),
+  /**
+   * Custom tokens for `HorizontalScrollButton`
+   */
+  scrollButtonTokens: getTokensPropType('HorizontalScrollButton'),
+  variant: variantProp.propType
+};
+export default Tabs;