@telus-uds/components-base 1.8.3 → 1.9.0

package/lib-module/Checkbox/CheckboxGroup.js

@@ -0,0 +1,233 @@
+import React, { forwardRef } from 'react';
+import PropTypes from 'prop-types';
+import ABBPropTypes from 'airbnb-prop-types';
+import { useViewport } from '../ViewportProvider';
+import { useThemeTokens } from '../ThemeProvider';
+import { a11yProps, containUniqueFields, focusHandlerProps, getTokensPropType, selectSystemProps, useMultipleInputValues, variantProp, viewProps } from '../utils';
+import { getStackedContent } from '../StackView';
+import Checkbox from './Checkbox';
+import Fieldset from '../Fieldset';
+import { jsx as _jsx } from "react/jsx-runtime";
+const [selectProps, selectedSystemPropTypes] = selectSystemProps([a11yProps, viewProps]);
+const [selectItemProps, selectedItemPropTypes] = selectSystemProps([a11yProps, focusHandlerProps, viewProps]);
+/**
+ * A group of Checkboxs that behave as a fieldset. Use when users select any number of choices from options.
+ *
+ * ## Component API
+ *
+ * Use the `items` prop to pass an array of objects describing each Checkbox in the group:
+ *
+ *  - `label`: main text passed to CheckboxGroup's `label` prop
+ *  - `id`: identifier used to store which CheckboxGroup is selected (uses `label` if undefinded)
+ *  - `onChange`: optional function called on selection, in addition to updating the group's selection state
+ *
+ * ### Controlled version
+ *
+ * If the selection state is controlled from outside, it needs to receive `checkedId` and `onChange` props.
+ *
+ * ### Uncontrolled version
+ *
+ * If the CheckboxGroup manages its own state, you can use `initialCheckedId` prop to provide the initial value.
+ * Whenever the radio card gets toggled, it calls the `onChange` callback with the new value (string).
+ *
+ * ### Use in forms
+ *
+ * For web forms, the `name` prop may be used to define the name of the group's `fieldset` and input elements.
+ *
+ * ### Validation
+ *
+ * Validation state may be set by passing 'error' or 'success' to the `validation` prop.
+ *
+ * ## A11y guidelines
+ *
+ * CheckboxGroup accepts all the common accessibility props, and controls the accessibility state
+ * of children like Checkbox and Feedback based on current state.
+ *
+ * @example
+ * ```jsx
+ * <CheckboxGroup
+ *   initialCheckedId="check1"
+ *   items={[
+ *     { label: 'Checkbox 1', id: 'check1' },
+ *     { label: 'Checkbox 2', id: 'check2' },
+ *     { label: 'Checkbox 3', id: 'check3' }
+ *   ]}
+ *   legend="Checkboxes"
+ *   hint="Choose from these options"
+ * />
+ * ```
+ */
+
+const CheckboxGroup = /*#__PURE__*/forwardRef((_ref, ref) => {
+  let {
+    tokens,
+    radioTokens,
+    variant,
+    items = [],
+    legend,
+    tooltip,
+    hint,
+    validation,
+    feedback,
+    initialCheckedIds,
+    checkedIds,
+    onChange,
+    readOnly,
+    name: inputGroupName,
+    inactive,
+    ...rest
+  } = _ref;
+  const viewport = useViewport();
+  const {
+    space,
+    fieldSpace
+  } = useThemeTokens('CheckboxGroup', tokens, variant, {
+    viewport
+  });
+  const {
+    currentValues,
+    toggleOneValue
+  } = useMultipleInputValues({
+    values: checkedIds,
+    initialValues: initialCheckedIds,
+    onChange,
+    readOnly: readOnly || inactive
+  });
+  const uniqueFields = ['id', 'label'];
+
+  if (!containUniqueFields(items, uniqueFields)) {
+    throw new Error("CheckboxGroup items must have unique ".concat(uniqueFields.join(', ')));
+  }
+
+  const checkboxes = items.map((_ref2, index) => {
+    let {
+      label,
+      id,
+      onChange: itemOnChange,
+      ref: itemRef,
+      ...itemRest
+    } = _ref2;
+    const checkboxId = id || "Checkbox[".concat(index, "]");
+
+    const handleChange = (newCheckedState, event) => {
+      if (typeof itemOnChange === 'function') itemOnChange(newCheckedState, event);
+      toggleOneValue(checkboxId, event);
+    };
+
+    return /*#__PURE__*/_jsx(Checkbox, {
+      ref: itemRef,
+      id: checkboxId,
+      checked: currentValues.includes(checkboxId),
+      onChange: handleChange,
+      inactive: inactive,
+      label: label,
+      name: inputGroupName,
+      tokens: radioTokens,
+      variant: variant,
+      ...selectItemProps(itemRest)
+    }, checkboxId);
+  });
+  return /*#__PURE__*/_jsx(Fieldset, {
+    ref: ref,
+    name: inputGroupName,
+    legend: legend,
+    tooltip: tooltip,
+    hint: hint,
+    space: fieldSpace,
+    feedback: feedback,
+    inactive: inactive,
+    validation: validation,
+    ...selectProps(rest),
+    children: getStackedContent(checkboxes, {
+      space,
+      direction: 'column'
+    })
+  });
+});
+CheckboxGroup.displayName = 'CheckboxGroup';
+CheckboxGroup.propTypes = { ...selectedSystemPropTypes,
+
+  /**
+   * Optional theme token overrides for the outer CheckboxGroup component
+   */
+  tokens: getTokensPropType('CheckboxGroup'),
+
+  /**
+   * Optional theme token overrides for each inner Checkbox component
+   */
+  radioTokens: getTokensPropType('Checkbox'),
+
+  /**
+   * Theme variants, shared between both CheckboxGroup and Checkbox
+   */
+  variant: variantProp.propType,
+
+  /**
+   * Array of objects containing specifics for each Checkbox to be rendered in the group.
+   */
+  items: PropTypes.arrayOf(PropTypes.exact({ ...selectedItemPropTypes,
+    label: PropTypes.string,
+    id: PropTypes.string,
+    onChange: PropTypes.func,
+    ref: ABBPropTypes.ref()
+  })),
+
+  /**
+   * Main text used to describe this group, used in Fieldset's Legend element.
+   */
+  legend: PropTypes.string,
+
+  /**
+   * Optional additional text giving more detail to help a user make a choice.
+   */
+  hint: PropTypes.string,
+
+  /**
+   * Optional tooltip text content to include alongside the legend and hint.
+   */
+  tooltip: PropTypes.string,
+
+  /**
+   * Current validation status of the group, passed to the feedback element if there is one.
+   */
+  validation: PropTypes.oneOf(['error', 'success']),
+
+  /**
+   * If provided, a Feedback element is rendered containing this text.
+   */
+  feedback: PropTypes.string,
+
+  /**
+   * If provided, the checkboxed with this ids are selected on first render.
+   */
+  initialCheckedIds: PropTypes.arrayOf(PropTypes.string),
+
+  /**
+   * If not undefined, the checkboxes with these ids is selected, and the
+   * element's selection state will be controlled by its parent using the `onChange` function.
+   */
+  checkedIds: PropTypes.arrayOf(PropTypes.string),
+
+  /**
+   * Function to call on change in selection state. Is required if the selection state is controlled
+   * by a parent using checkedId and the input is not readOnly.
+   */
+  onChange: PropTypes.func,
+
+  /**
+   * If true, the checkboxes cannot be selected by the user and simply show their current state.
+   */
+  readOnly: PropTypes.bool,
+
+  /**
+   * If true, the checkboxes cannot be interacted with, elements are set as `disabled` and if the
+   * theme supports `inactive` appearances rules, these are applied.
+   */
+  inactive: PropTypes.bool,
+
+  /**
+   * On Web, this is passed to the `name` attribute of the fieldset and each checkbox input.
+   */
+  name: PropTypes.string
+};
+export default CheckboxGroup;

package/lib-module/Checkbox/CheckboxInput.js

@@ -0,0 +1,60 @@
+import React, { forwardRef } from 'react';
+import PropTypes from 'prop-types';
+/**
+ * On Web we need to include an actual input but hide it.
+ */
+
+import { jsx as _jsx } from "react/jsx-runtime";
+const CheckboxInput = /*#__PURE__*/forwardRef((_ref, ref) => {
+  let {
+    checked,
+    defaultChecked,
+    disabled,
+    id,
+    isControlled,
+    name,
+    onChange,
+    value
+  } = _ref;
+
+  const handleClick = event => {
+    // Cancel the click dispatched via the label tag, since it's already wrapped
+    // in <Pressable>
+    event.preventDefault();
+    event.stopPropagation();
+  };
+
+  return /*#__PURE__*/_jsx("input", {
+    checked: isControlled ? checked : undefined,
+    defaultChecked: isControlled ? undefined : defaultChecked,
+    disabled: disabled,
+    hidden: true,
+    id: id,
+    name: name,
+    onChange: onChange,
+    onClick: handleClick,
+    ref: ref,
+    type: "checkbox",
+    value: value
+  });
+});
+CheckboxInput.displayName = 'CheckboxInput';
+CheckboxInput.propTypes = {
+  checked: PropTypes.bool,
+  defaultChecked: PropTypes.bool,
+  disabled: PropTypes.bool,
+  id: PropTypes.string.isRequired,
+  isControlled: PropTypes.bool.isRequired,
+  name: PropTypes.string,
+  onChange: PropTypes.func,
+  value: PropTypes.string
+};
+CheckboxInput.defaultProps = {
+  checked: undefined,
+  defaultChecked: undefined,
+  disabled: false,
+  name: undefined,
+  onChange: () => {},
+  value: undefined
+};
+export default CheckboxInput;

package/lib-module/Checkbox/CheckboxInput.native.js

@@ -0,0 +1,6 @@
+/**
+ * There's no checkbox input on native platforms, so this is a noop.
+ */
+const CheckboxInput = () => null;
+
+export default CheckboxInput;

package/lib-module/Checkbox/index.js

@@ -0,0 +1,3 @@
+import Checkbox from './Checkbox';
+export default Checkbox;
+export { default as CheckboxGroup } from './CheckboxGroup';

package/lib-module/Divider/Divider.js

@@ -0,0 +1,124 @@
+import React, { forwardRef } 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 Platform from "react-native-web/dist/exports/Platform";
+import { useThemeTokens } from '../ThemeProvider';
+import Spacer from '../Spacer';
+import { a11yProps, getTokensPropType, selectSystemProps, spacingProps, variantProp, viewProps } from '../utils';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Fragment as _Fragment } from "react/jsx-runtime";
+import { jsxs as _jsxs } from "react/jsx-runtime";
+const [selectProps, selectedSystemPropTypes] = selectSystemProps([a11yProps, viewProps]);
+/**
+ * @typedef {import('../utils/props/spacingProps.js').SpacingIndex} SpacingIndex
+ * @typedef {import('../utils/props/spacingProps.js').SpacingObject} SpacingObject
+ */
+
+/**
+ * A basic divider component, horizontal by default. Color and thickness can be controlled by theme.
+ * Divider is based on the flexbox model and uses `alignSelf: flex` to span its flex parent.
+ *
+ * ## Vertical
+ *
+ * Vertical dividers can be created by passing a `vertical` boolean prop.
+ * Note that for a vertical divider the parent flex element **must** have flex direction set to row.
+ * This is the default for web but not for React Native.
+ *
+ * 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 = /*#__PURE__*/forwardRef((_ref, ref) => {
+  let {
+    variant,
+    vertical = false,
+    space,
+    tokens,
+    ...rest
+  } = _ref;
+  const {
+    color,
+    width
+  } = useThemeTokens('Divider', tokens, variant);
+  const borderStyles = vertical ? {
+    borderRightColor: color,
+    borderRightWidth: width
+  } : {
+    borderBottomColor: color,
+    borderBottomWidth: width
+  };
+  const a11y = Platform.OS === 'web' ? // There are aria attributes for dividers on web
+  {
+    'aria-orientation': vertical ? 'vertical' : 'horizontal',
+    accessibilityRole: 'separator'
+  } : // There are no such equivalent attributes for native
+  {};
+  const {
+    testID,
+    ...selectedProps
+  } = selectProps({ ...a11y,
+    ...rest
+  });
+
+  const divider = /*#__PURE__*/_jsx(View, {
+    ref: ref,
+    style: [styles.divider, borderStyles],
+    testID: testID,
+    ...selectedProps
+  });
+
+  if (!space) return divider;
+  const spacerProps = {
+    space,
+    direction: vertical ? 'row' : 'column'
+  };
+  return /*#__PURE__*/_jsxs(_Fragment, {
+    children: [/*#__PURE__*/_jsx(Spacer, { ...spacerProps,
+      testID: testID ? "".concat(testID, "-Spacer-before") : undefined
+    }), divider, /*#__PURE__*/_jsx(Spacer, { ...spacerProps,
+      testID: testID ? "".concat(testID, "-Spacer-after") : undefined
+    })]
+  });
+});
+Divider.displayName = 'Divider';
+Divider.propTypes = { ...selectedSystemPropTypes,
+  tokens: getTokensPropType('Divider'),
+  space: spacingProps.types.spacingValue,
+  variant: variantProp.propType,
+
+  /**
+   * By default, the divider is a horizontal line the full width of its parent.
+   * With `vertical` prop and when inside a container with { flexDirection: row }, draws a full height vertical line.
+   */
+  vertical: PropTypes.bool
+};
+const styles = StyleSheet.create({
+  divider: {
+    alignSelf: 'stretch'
+  }
+});
+export default Divider;

package/lib-module/Divider/index.js

@@ -0,0 +1,2 @@
+import Divider from './Divider';
+export default Divider;

package/lib-module/ExpandCollapse/Accordion.js

@@ -0,0 +1,15 @@
+import React, { forwardRef } from 'react';
+import ExpandCollapse from './ExpandCollapse';
+/**
+ * 'Accordion' is a shorthand for an ExpandCollapse where only one item may be open at a time
+ */
+
+import { jsx as _jsx } from "react/jsx-runtime";
+const Accordion = /*#__PURE__*/forwardRef((props, ref) => /*#__PURE__*/_jsx(ExpandCollapse, {
+  ref: ref,
+  ...props,
+  maxOpen: 1
+}));
+Accordion.displayName = 'Accordion';
+Accordion.propTypes = ExpandCollapse.propTypes;
+export default Accordion;

package/lib-module/ExpandCollapse/Control.js

@@ -0,0 +1,136 @@
+import React, { forwardRef } from 'react';
+import Pressable from "react-native-web/dist/exports/Pressable";
+import View from "react-native-web/dist/exports/View";
+import PropTypes from 'prop-types';
+import { useThemeTokensCallback, verticalAlignRow } from '../ThemeProvider';
+import { a11yProps, getTokensPropType, selectSystemProps, variantProp, viewProps } from '../utils';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Fragment as _Fragment } from "react/jsx-runtime";
+import { jsxs as _jsxs } from "react/jsx-runtime";
+const [selectProps, selectedSystemPropTypes] = selectSystemProps([a11yProps, viewProps]);
+
+function selectContainerStyles(_ref) {
+  let {
+    backgroundColor,
+    borderColor,
+    borderWidth,
+    borderStyle,
+    paddingLeft,
+    paddingRight,
+    paddingTop,
+    paddingBottom,
+    justifyContent,
+    verticalAlign,
+    iconPosition
+  } = _ref;
+  return {
+    backgroundColor,
+    borderTopColor: borderColor,
+    borderTopWidth: borderWidth,
+    borderTopStyle: borderStyle,
+    paddingLeft,
+    paddingRight,
+    paddingTop,
+    paddingBottom,
+    justifyContent,
+    ...verticalAlignRow(verticalAlign, iconPosition === 'right')
+  };
+} // TODO: use stack / spacer when available
+
+
+function selectIconContainerStyles(_ref2) {
+  let {
+    iconGap,
+    iconPosition
+  } = _ref2;
+  const paddingSide = iconPosition === 'right' ? 'paddingLeft' : 'paddingRight';
+  return {
+    [paddingSide]: iconGap
+  };
+}
+
+function selectIconTokens(tokens) {
+  return {
+    color: tokens.iconColor,
+    size: tokens.iconSize
+  };
+}
+
+const ExpandCollapseControl = /*#__PURE__*/forwardRef((_ref3, ref) => {
+  let {
+    onPress,
+    isExpanded,
+    children,
+    tokens,
+    accessibilityRole = 'button',
+    variant,
+    ...rest
+  } = _ref3;
+  const getTokens = useThemeTokensCallback('ExpandCollapseControl', tokens, variant);
+  const selectedProps = selectProps({ ...rest,
+    accessibilityRole
+  });
+  selectedProps.accessibilityState = { ...(selectedProps.accessibilityState || {}),
+    expanded: isExpanded
+  };
+
+  const getControlState = _ref4 => {
+    let {
+      pressed,
+      hovered,
+      focused
+    } = _ref4;
+    return {
+      pressed,
+      hover: hovered,
+      focus: focused,
+      expanded: isExpanded
+    };
+  };
+
+  const getControlTokens = pressableState => getTokens(getControlState(pressableState));
+
+  const getPressableStyle = pressableState => selectContainerStyles(getControlTokens(pressableState));
+
+  return /*#__PURE__*/_jsx(Pressable, {
+    ref: ref,
+    ...selectedProps,
+    onPress: onPress,
+    style: getPressableStyle,
+    children: pressableState => {
+      const {
+        icon: IconComponent,
+        ...themeTokens
+      } = getControlTokens(pressableState);
+      return /*#__PURE__*/_jsxs(_Fragment, {
+        children: [IconComponent && /*#__PURE__*/_jsx(View, {
+          style: selectIconContainerStyles(themeTokens),
+          children: /*#__PURE__*/_jsx(IconComponent, { ...selectIconTokens(themeTokens)
+          })
+        }), typeof children === 'function' ? children(getControlState(pressableState)) : children]
+      });
+    }
+  });
+});
+ExpandCollapseControl.displayName = 'ExpandCollapseControl';
+ExpandCollapseControl.propTypes = { ...selectedSystemPropTypes,
+  tokens: getTokensPropType('ExpandCollapseControl'),
+  variant: variantProp.propType,
+
+  /**
+   * ExpandCollapseControl's children are the content within the button that opens or closes this panel. May
+   * accept a render function that recieves the control state: { pressed, hover, focus, expanded }
+   */
+  children: PropTypes.oneOfType([PropTypes.node, PropTypes.func]),
+
+  /**
+   * Whether the linked ExpandCollapsePanel is opened or closed. Allows themes to set `expanded` styles.
+   */
+  isExpanded: PropTypes.bool,
+
+  /**
+   * Function called when the ExpandCollapse is pressed.
+   */
+  onPress: PropTypes.func.isRequired
+};
+export default ExpandCollapseControl;

package/lib-module/ExpandCollapse/ExpandCollapse.js

@@ -0,0 +1,95 @@
+import React, { forwardRef } from 'react';
+import View from "react-native-web/dist/exports/View";
+import PropTypes from 'prop-types';
+import { useThemeTokens } from '../ThemeProvider';
+import { a11yProps, getTokensPropType, selectSystemProps, useMultipleInputValues, variantProp, viewProps } from '../utils';
+import { jsx as _jsx } from "react/jsx-runtime";
+const [selectProps, selectedSystemPropTypes] = selectSystemProps([a11yProps, viewProps]);
+
+function selectBorderStyles(tokens) {
+  return {
+    borderBottomWidth: tokens.borderWidth,
+    borderBottomStyle: tokens.borderStyle,
+    borderBottomColor: tokens.borderColor
+  };
+}
+/**
+ * Flexible base component for lists where some or all items are collapsible headers.
+ *
+ * Pass a render function as `children` which takes and passes `openIds` and `onToggle` props to
+ * <ExpandCollapse.Panel> children, and assign the panels explicit `panelId` props. The panels may be
+ * nested (they do not need to be direct children), and non-interactive items may be included too.
+ */
+
+
+const ExpandCollapse = /*#__PURE__*/forwardRef((_ref, ref) => {
+  let {
+    children,
+    tokens,
+    variant,
+    maxOpen,
+    open,
+    initialOpen,
+    onChange,
+    ...rest
+  } = _ref;
+  const {
+    currentValues: openIds,
+    toggleOneValue: onToggle,
+    resetValues,
+    setValues,
+    unsetValues
+  } = useMultipleInputValues({
+    maxValues: maxOpen,
+    values: open,
+    initialValues: initialOpen,
+    onChange
+  });
+  const themeTokens = useThemeTokens('ExpandCollapse', tokens, variant);
+  return /*#__PURE__*/_jsx(View, {
+    ref: ref,
+    style: selectBorderStyles(themeTokens),
+    ...selectProps(rest),
+    children: typeof children === 'function' ? children({
+      openIds,
+      onToggle,
+      resetValues,
+      setValues,
+      unsetValues
+    }) : children
+  });
+});
+ExpandCollapse.displayName = 'ExpandCollapse';
+ExpandCollapse.propTypes = { ...selectedSystemPropTypes,
+  variant: variantProp.propType,
+  tokens: getTokensPropType('ExpandCollapse'),
+
+  /**
+   * ExpandCollapse usually takes a render function to which it passes an object with properties
+   * { openIds, onToggle, resetValues, setValues, unsetValues }. openIds (array of ids) and
+   * onToggle (function) will usually be passed to `<ExpandCollapse.Panel>`
+   */
+  children: PropTypes.oneOfType([PropTypes.func, PropTypes.node]).isRequired,
+
+  /**
+   * If set, enforces a specific maximum number of open items, closing already-open items when new
+   * items are opened. By default, any number of items may be open at once.
+   */
+  maxOpen: PropTypes.number,
+
+  /**
+   * If passed, the item or items that are expanded will be controlled by a parent component
+   */
+  open: PropTypes.arrayOf(PropTypes.string),
+
+  /**
+   * Function called when which panels are currently open changes. Necessary if `open` is passed.
+   */
+  onChange: PropTypes.func,
+
+  /**
+   * Allows items with specified ids to be open by default on first load. Should not be used with `open`.
+   */
+  initialOpen: PropTypes.arrayOf(PropTypes.string)
+};
+export default ExpandCollapse;