@telus-uds/components-base 1.3.0 → 1.5.0

package/lib-module/StackView/StackWrap.js

@@ -0,0 +1,48 @@
+import React, { forwardRef } from 'react';
+import Platform from "react-native-web/dist/exports/Platform";
+import StackWrapBox from './StackWrapBox';
+import StackWrapGap from './StackWrapGap'; // In Jest/CI/SSR, global CSS isn't always available and doesn't always have .supports method
+
+import { jsx as _jsx } from "react/jsx-runtime";
+
+const cssSupports = (...args) => {
+  var _window$CSS;
+
+  return typeof window !== 'undefined' && typeof ((_window$CSS = window.CSS) === null || _window$CSS === void 0 ? void 0 : _window$CSS.supports) === 'function' && window.CSS.supports(...args);
+}; // 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 = /*#__PURE__*/forwardRef((props, ref) => {
+  const {
+    space
+  } = props; // Don't apply separate gap if `null` or `undefined`, so can be unset in Storybook etc
+
+  const gap = props.gap ?? space;
+  const canUseCSSGap = Platform.OS === 'web' && gap === space && cssSupports('gap', exampleGapValue);
+  return canUseCSSGap ?
+  /*#__PURE__*/
+  // If possible, use the cleaner implementation that applies CSS `gap` styles to the container.
+  _jsx(StackWrapGap, {
+    ref: ref,
+    ...props
+  }) :
+  /*#__PURE__*/
+  // Else, use the fallback implementation which renders a `Box` component around each child.
+  _jsx(StackWrapBox, {
+    ref: ref,
+    ...props
+  });
+});
+StackWrap.displayName = 'StackWrap';
+StackWrap.propTypes = StackWrapBox.propTypes;
+export default StackWrap;

package/lib-module/StackView/StackWrap.native.js

@@ -0,0 +1,3 @@
+import StackWrapBox from './StackWrapBox'; // No support for CSS `gap` on React Native, so always use the fallback "box" implementation.
+
+export default StackWrapBox;

package/lib-module/StackView/StackWrapBox.js

@@ -0,0 +1,114 @@
+import React, { forwardRef } from 'react';
+import PropTypes from 'prop-types';
+import View from "react-native-web/dist/exports/View";
+import { a11yProps, getA11yPropsFromHtmlTag, getTokensPropType, layoutTags, responsiveProps, selectSystemProps, spacingProps, useSpacingScale, useResponsiveProp, viewProps } from '../utils';
+import { useThemeTokens } from '../ThemeProvider';
+import { useViewport } from '../ViewportProvider';
+import getStackedContent from './getStackedContent';
+import { staticStyles, selectFlexStyles } from './common';
+import { jsx as _jsx } from "react/jsx-runtime";
+const [selectProps, selectedSystemPropTypes] = selectSystemProps([a11yProps, viewProps]);
+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 = /*#__PURE__*/forwardRef(({
+  space = 1,
+  gap = space,
+  direction: directionProp = 'row',
+  children,
+  tokens,
+  variant,
+  tag,
+  accessibilityRole,
+  ...rest
+}, ref) => {
+  const viewport = useViewport();
+  const direction = useResponsiveProp(directionProp, 'row');
+  const themeTokens = useThemeTokens('StackView', tokens, variant, {
+    viewport
+  });
+  const flexStyles = selectFlexStyles(themeTokens);
+  const selectedProps = selectProps({ ...getA11yPropsFromHtmlTag(tag, accessibilityRole),
+    ...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 /*#__PURE__*/_jsx(View, {
+    ref: ref,
+    ...selectedProps,
+    style: [flexStyles, staticStyles.wrap, staticStyles[direction], offsetStyle],
+    children: content
+  });
+});
+StackWrapBox.displayName = 'StackWrapBox';
+StackWrapBox.propTypes = { ...selectedSystemPropTypes,
+  tokens: getTokensPropType('StackView'),
+
+  /**
+   * Sets the `flexDirection` of the container
+   */
+  direction: responsiveProps.getTypeOptionallyByViewport(PropTypes.oneOf(['column', 'row', 'row-reverse', 'column-reverse'])),
+
+  /**
+   * The size of the space between items 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 size of the space between lines of content, according to the theme's spacing scale. By default, matches `space`.
+   * 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).
+   */
+  gap: spacingProps.types.spacingValue,
+
+  /**
+   * Optional semantic HTML tag, to apply to the container on web. Does not change styling.
+   *
+   * In native apps, if a header tag is provided ("h1", "h2" etc) and accessibilityRole prop
+   * is not defined, the accessibilityRole will default to "heading".
+   */
+  tag: PropTypes.oneOf(layoutTags),
+
+  /**
+   * 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/lib-module/StackView/StackWrapGap.js

@@ -0,0 +1,58 @@
+import React, { forwardRef } from 'react';
+import View from "react-native-web/dist/exports/View";
+import StackWrapBox from './StackWrapBox';
+import { a11yProps, getA11yPropsFromHtmlTag, selectSystemProps, useSpacingScale, useResponsiveProp, viewProps } from '../utils';
+import { useThemeTokens } from '../ThemeProvider';
+import { useViewport } from '../ViewportProvider';
+import getStackedContent from './getStackedContent';
+import { staticStyles, selectFlexStyles } from './common';
+import { jsx as _jsx } from "react/jsx-runtime";
+const [selectProps] = selectSystemProps([a11yProps, viewProps]);
+/**
+ * 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 = /*#__PURE__*/forwardRef(({
+  space = 1,
+  tokens,
+  variant,
+  direction: directionProp = 'row',
+  children,
+  tag,
+  accessibilityRole,
+  ...rest
+}, ref) => {
+  const viewport = useViewport();
+  const direction = useResponsiveProp(directionProp, 'row');
+  const themeTokens = useThemeTokens('StackView', tokens, variant, {
+    viewport
+  });
+  const flexStyles = selectFlexStyles(themeTokens);
+  const selectedProps = selectProps({ ...getA11yPropsFromHtmlTag(tag, accessibilityRole),
+    ...rest
+  });
+  const size = useSpacingScale(space);
+  const gapStyle = {
+    gap: size
+  };
+  const content = getStackedContent(children, {
+    direction,
+    space: 0
+  });
+  return /*#__PURE__*/_jsx(View, {
+    ref: ref,
+    ...selectedProps,
+    style: [flexStyles, staticStyles.wrap, staticStyles[direction], gapStyle],
+    children: content
+  });
+});
+StackWrapGap.displayName = 'StackWrapGap';
+StackWrapGap.propTypes = StackWrapBox.propTypes;
+export default StackWrapGap;

package/lib-module/StackView/common.js

@@ -0,0 +1,32 @@
+import StyleSheet from "react-native-web/dist/exports/StyleSheet";
+export const selectFlexStyles = ({
+  alignItems,
+  justifyContent,
+  flexGrow,
+  flexShrink
+}) => ({
+  alignItems,
+  justifyContent,
+  flexGrow,
+  flexShrink
+});
+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/lib-module/StackView/getStackedContent.js

@@ -0,0 +1,123 @@
+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/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 { createElement as _createElement } from "react";
+import { jsx as _jsx } from "react/jsx-runtime";
+
+const getStackedContent = (children, {
+  divider,
+  space,
+  direction = 'column',
+  box,
+  preserveFragments = false
+}) => {
+  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 = 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,
+      key: testID,
+      space
+    };
+    const separator = divider ? /*#__PURE__*/_jsx(Divider, {
+      vertical: direction.startsWith('row'),
+      ...dividerProps,
+      ...commonProps
+    }) : /*#__PURE__*/_jsx(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 => {
+  var _child$props;
+
+  // 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 === null || child === void 0 ? void 0 : child.type) === Fragment) return unpackFragment((_child$props = child.props) === null || _child$props === void 0 ? void 0 : _child$props.children); // Stop unpacking as soon as any non-fragment child is found
+
+  return child;
+};
+
+export default getStackedContent;

package/lib-module/StackView/index.js

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

package/lib-module/StepTracker/Step.js

@@ -0,0 +1,229 @@
+import React from 'react';
+import PropTypes from 'prop-types';
+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 Icon from '../Icon';
+import { a11yProps, getTokensPropType, selectSystemProps, variantProp, viewProps } from '../utils';
+import { applyTextStyles } from '../ThemeProvider';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { jsxs as _jsxs } from "react/jsx-runtime";
+const [selectProps, selectedSystemPropTypes] = selectSystemProps([a11yProps, viewProps]);
+
+const selectCompletedIconTokens = ({
+  completedIconColor,
+  completedIconSize
+}) => ({
+  size: completedIconSize,
+  color: completedIconColor
+});
+
+const selectConnectorStyles = ({
+  connectorColor,
+  connectorHeight,
+  connectorMinWidth,
+  connectorCompletedHeight,
+  connectorCompletedColor
+}, isCompleted) => ({
+  backgroundColor: connectorColor,
+  height: connectorHeight,
+  minWidth: connectorMinWidth,
+  ...(isCompleted && {
+    height: connectorCompletedHeight,
+    backgroundColor: connectorCompletedColor
+  })
+});
+
+const selectCurrentInnerStyles = ({
+  knobCurrentInnerColor,
+  knobCurrentInnerSize
+}) => ({
+  backgroundColor: knobCurrentInnerColor,
+  borderRadius: knobCurrentInnerSize / 2,
+  height: knobCurrentInnerSize,
+  width: knobCurrentInnerSize
+});
+
+const selectKnobStyles = ({
+  knobBackgroundColor,
+  knobBorderColor,
+  knobBorderWidth,
+  knobCompletedBackgroundColor,
+  knobCompletedBorderColor,
+  knobCompletedPaddingLeft,
+  knobCompletedPaddingTop,
+  knobCurrentBackgroundColor,
+  knobCurrentBorderColor,
+  knobCurrentBorderWidth,
+  knobCurrentPaddingLeft,
+  knobCurrentPaddingTop,
+  knobSize
+}, isCompleted, isCurrent) => ({
+  backgroundColor: knobBackgroundColor,
+  borderColor: knobBorderColor,
+  borderRadius: knobSize / 2,
+  borderWidth: knobBorderWidth,
+  height: knobSize,
+  width: knobSize,
+  ...(isCompleted && {
+    backgroundColor: knobCompletedBackgroundColor,
+    borderColor: knobCompletedBorderColor,
+    paddingLeft: knobCompletedPaddingLeft,
+    paddingTop: knobCompletedPaddingTop
+  }),
+  ...(isCurrent && {
+    backgroundColor: knobCurrentBackgroundColor,
+    borderColor: knobCurrentBorderColor,
+    borderWidth: knobCurrentBorderWidth,
+    paddingLeft: knobCurrentPaddingLeft,
+    paddingTop: knobCurrentPaddingTop
+  })
+});
+
+const selectLabelContainerStyles = ({
+  labelDirection,
+  labelGap,
+  labelMarginTop,
+  labelPaddingLeft,
+  labelPaddingRight
+}) => ({
+  marginTop: labelMarginTop,
+  paddingLeft: labelPaddingLeft,
+  paddingRight: labelPaddingRight,
+  flexDirection: labelDirection,
+  gap: labelGap
+});
+
+const selectLabelStyles = ({
+  labelColor,
+  labelCurrentColor,
+  labelCurrentFontWeight,
+  labelFontSize,
+  labelFontWeight,
+  labelFontName,
+  labelLineHeight
+}, isCurrent) => applyTextStyles({
+  color: isCurrent ? labelCurrentColor : labelColor,
+  fontSize: labelFontSize,
+  lineHeight: labelLineHeight,
+  fontWeight: isCurrent ? labelCurrentFontWeight : labelFontWeight,
+  fontName: labelFontName
+});
+
+const getStepTestID = (isCompleted, isCurrent) => {
+  let testID = 'StepTracker-Step';
+
+  if (isCompleted) {
+    testID += '-Completed';
+  } else if (isCurrent) {
+    testID += '-Current';
+  }
+
+  return testID;
+};
+/**
+ * A single step of a StepTracker.
+ */
+
+
+const Step = ({
+  label,
+  name,
+  status = 0,
+  stepCount = 0,
+  stepIndex = 0,
+  tokens,
+  ...rest
+}) => {
+  const {
+    completedIcon,
+    showStepLabel,
+    showStepName,
+    ...themeTokens
+  } = tokens;
+  const isFirst = stepIndex === 0;
+  const isLast = stepIndex === stepCount - 1;
+  const isCompleted = status > stepIndex;
+  const isCurrent = status === stepIndex;
+  const isActive = isCompleted || isCurrent;
+  return /*#__PURE__*/_jsxs(StackView, {
+    space: 0,
+    tokens: {
+      alignItems: 'stretch',
+      flexGrow: 1
+    },
+    accessibilityLabel: label,
+    accessibilityLevel: 2,
+    accessibilityCurrent: status === stepIndex,
+    ...selectProps(rest),
+    children: [/*#__PURE__*/_jsxs(StackView, {
+      direction: "row",
+      space: 0,
+      tokens: {
+        alignItems: 'center',
+        flexGrow: 0
+      },
+      children: [/*#__PURE__*/_jsx(View, {
+        style: [staticStyles.connector, !isFirst && selectConnectorStyles(themeTokens, isActive)]
+      }), /*#__PURE__*/_jsxs(View, {
+        style: [staticStyles.knob, selectKnobStyles(themeTokens, isCompleted, isCurrent)],
+        testID: getStepTestID(isCompleted, isCurrent),
+        children: [isCompleted && completedIcon && /*#__PURE__*/_jsx(Icon, {
+          icon: completedIcon,
+          tokens: selectCompletedIconTokens(themeTokens)
+        }), isCurrent && /*#__PURE__*/_jsx(View, {
+          style: selectCurrentInnerStyles(themeTokens)
+        })]
+      }), /*#__PURE__*/_jsx(View, {
+        style: [staticStyles.connector, !isLast && selectConnectorStyles(themeTokens, isCompleted)]
+      })]
+    }), showStepLabel && /*#__PURE__*/_jsxs(View, {
+      style: [staticStyles.stepLabelContainer, selectLabelContainerStyles(tokens)],
+      children: [showStepName && /*#__PURE__*/_jsx(Text, {
+        style: [staticStyles.centeredText, selectLabelStyles(tokens, isCurrent)],
+        children: name
+      }), /*#__PURE__*/_jsx(StackView, {
+        direction: "row",
+        children: /*#__PURE__*/_jsx(Text, {
+          style: [staticStyles.centeredText, tokens.labelDirection === 'column' && staticStyles.wrappingLabel, selectLabelStyles(tokens, isCurrent)],
+          children: label
+        })
+      })]
+    })]
+  });
+};
+
+Step.propTypes = { ...selectedSystemPropTypes,
+  label: PropTypes.string.isRequired,
+  name: PropTypes.string.isRequired,
+  status: PropTypes.number.isRequired,
+  stepCount: PropTypes.number.isRequired,
+  stepIndex: PropTypes.number.isRequired,
+  tokens: getTokensPropType('StepTracker'),
+  variant: variantProp.propType
+};
+export default Step;
+const staticStyles = StyleSheet.create({
+  centeredText: {
+    textAlign: 'center'
+  },
+  connector: {
+    flex: 1,
+    height: 1
+  },
+  completedKnob: {
+    backgroundColor: 'transparent',
+    textAlign: 'center'
+  },
+  knob: {
+    borderWidth: 1
+  },
+  stepLabelContainer: {
+    justifyContent: 'center'
+  },
+  wrappingLabel: {
+    width: 0,
+    flex: 1
+  }
+});