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

package/lib/Spacer/Spacer.js

@@ -0,0 +1,117 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+
+var _react = _interopRequireDefault(require("react"));
+
+var _propTypes = _interopRequireDefault(require("prop-types"));
+
+var _StyleSheet = _interopRequireDefault(require("react-native-web/dist/cjs/exports/StyleSheet"));
+
+var _View = _interopRequireDefault(require("react-native-web/dist/cjs/exports/View"));
+
+var _utils = require("../utils");
+
+var _jsxRuntime = require("react/jsx-runtime");
+
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+
+/**
+ * @typedef {import('../utils/propTypes.js').SpacingValue} SpacingValue
+ * @typedef {import('../utils/propTypes.js').SpacingObject} SpacingObject
+ */
+const selectSizeStyle = (size, direction) => ({
+  // Only apply space in one direction at a time, else large spacers will increase the
+  // 'across' size of the parent and mess up siblings with styles like `alignItems: stretch`.
+  [direction === 'row' ? 'width' : 'height']: size
+});
+/**
+ * An empty element used to create a gap between components that is sized according to the theme spacing scale,
+ * passing its `space` prop ({@link SpacingValue}) to `useSpacingScale`.
+ *
+ * ## Simple spacing
+ *
+ * For most simple uses, pass a number to Spacer's `space` prop referring to an index in the theme's
+ * spacing scale. For example, for a spacer of the theme's smallest non-zero spacing size:
+ *
+ * ```jsx
+ * <Spacer space={1} />
+ * ```
+ *
+ * ## Responsive spacing
+ *
+ * Different spacing scale sizes may be chosen for different viewports by passing `space` a {@link SpacingObject}
+ * using keys for the viewports at and above which certain spacing indexes should apply.
+ *
+ * This can be useful when a Spacer is inside a layout with a shape that changes between viewports.
+ *
+ * For example, a spacer might need no width below 'md' viewport because the items it separates will be on separate lines,
+ * but may need a visible size above that viewport, and a wider size at the highest viewport:
+ *
+ * ```jsx
+ * <Spacer space={{ xs: 0, md: 2, xl: 3 }} />
+ * ```
+ *
+ * Note that themes may also define viewport-specific behaviour for indexes on the spacing scale. These viewport
+ * props should only be used where necessary to achieve a certain responsive layoutm and shouldn't be used to replace
+ * or deviate from responsive spacing behaviour in a theme that is intended to apply universally.
+ *
+ * ## More options
+ *
+ * See `useSpacingScale` hook for more options that may be used with the `space` prop.
+ *
+ * ## Accessibility
+ *
+ * Spacer has no content and is ignored by tools such as screen readers. Use `Divider` for
+ * separations between elements that may be treated as semantically meaningful on web.
+ */
+
+
+const Spacer = ({
+  space = 1,
+  direction = 'column',
+  testID
+}) => {
+  const size = (0, _utils.useSpacingScale)(space);
+  const sizeStyle = selectSizeStyle(size, direction);
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)(_View.default, {
+    testID: testID,
+    style: [staticStyles.stretch, sizeStyle]
+  });
+};
+
+Spacer.propTypes = {
+  /**
+   * The size of the spacer 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: _utils.spacingProps.types.spacingValue,
+
+  /**
+   * The spacer applies space in only one direction, which is controlled by the `direction` prop:
+   *
+   * - `'column'` (default) applies space vertically; has a fixed height and not width.
+   * - `'row'` applies space horizontally; has a fixed width and not height.
+   */
+  direction: _propTypes.default.oneOf(['column', 'row']),
+
+  /**
+   * @ignore
+   * In tests, the only way to select Spacers is with testID prop and getByTestId, since they have no content,
+   * no accessibility role, and there is no equivalent of nextSibling in React Native Testing Library.
+   */
+  testID: _propTypes.default.string
+};
+
+const staticStyles = _StyleSheet.default.create({
+  stretch: {
+    alignSelf: 'stretch'
+  }
+});
+
+var _default = Spacer;
+exports.default = _default;

package/lib/Spacer/index.js

@@ -0,0 +1,13 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+
+var _Spacer = _interopRequireDefault(require("./Spacer"));
+
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+
+var _default = _Spacer.default;
+exports.default = _default;

package/lib/StackView/StackView.js

@@ -0,0 +1,130 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+
+var _react = _interopRequireDefault(require("react"));
+
+var _propTypes = _interopRequireDefault(require("prop-types"));
+
+var _View = _interopRequireDefault(require("react-native-web/dist/cjs/exports/View"));
+
+var _Divider = _interopRequireDefault(require("../Divider"));
+
+var _utils = require("../utils");
+
+var _ThemeProvider = require("../ThemeProvider");
+
+var _ViewportProvider = require("../ViewportProvider");
+
+var _getStackedContent = _interopRequireDefault(require("./getStackedContent"));
+
+var _common = require("./common");
+
+var _jsxRuntime = require("react/jsx-runtime");
+
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+
+/**
+ * StackView evenly spaces its children, by default placing `Spacer` components between them.
+ *
+ * ## Spacing
+ *
+ * StackView takes the same spacing props as `Spacer` and passes them directly to the layout components
+ * it uses for spacing.
+ *
+ * ## Direction
+ *
+ * Use `direction` to control how the children are stacked:
+ *
+ * - `'column'` (default) stacks and spaces the children vertically.
+ * - `'row'` stacks and spaces the children horizontally.
+ * - `'column-reverse'` acts the same as `'column'`, but reverses the direction.
+ * - `'row-reverse'` acts the same as `'row'`, but reverses the direction.
+ *
+ * `direction` is an optionally responsive prop and may be an object keyed by viewports. For example,
+ * `{ xs: 'column', md: 'row' } stacks as a column on `xs` and `sm` viewports and a row at 'md' and above.
+ *
+ * ## Theming, alignment and justification
+ *
+ * `StackView` is a pure layout component and has no theme styles beyond a small set of layout styles
+ * (`alignItems`, `justifyContent`, `flexGrow`) which may be set using the `tokens` prop. If the
+ * tokens prop is a function it will recieve the current viewport.
+ *
+ * All other styling such as borders, background colours, padding etc should be applied by wrapping
+ * the `StackView` in other components. For example, a `StackView` may be the child of a `Card`.
+ *
+ * ## Separator options
+ *
+ * By default, StackView inserts a `<Spacer>` component between each rendered child.
+ *
+ * With the `divider` prop, it instead renders a `Divider` instead of a `Spacer`. The gap between
+ * items will be double what it would be without this prop plus the width of the divider.
+ *
+ * ## Accessibility
+ *
+ * `StackView` may take any React Native accessibility props and applies them to the outer `View`.
+ * It applies no accessibility props of its own, unless `divider` prop is passed (`Divider` has a
+ * semantic role but only on web, not within native apps).
+ */
+const StackView = ({
+  space = 1,
+  divider,
+  direction: directionProp = 'column',
+  children,
+  variant,
+  tokens,
+  ...rest
+}) => {
+  const viewport = (0, _ViewportProvider.useViewport)();
+  const direction = (0, _utils.useResponsiveProp)(directionProp, 'column');
+  const props = { ..._utils.a11yProps.select(rest),
+    ..._utils.viewProps.select(rest)
+  };
+  const content = (0, _getStackedContent.default)(children, {
+    direction,
+    divider,
+    space
+  });
+  const themeTokens = (0, _ThemeProvider.useThemeTokens)('StackView', tokens, variant, {
+    viewport
+  });
+  const flexStyles = (0, _common.selectFlexStyles)(themeTokens);
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)(_View.default, { ...props,
+    style: [flexStyles, _common.staticStyles[direction]],
+    children: content
+  });
+};
+
+StackView.propTypes = { ..._utils.a11yProps.propTypes,
+  tokens: (0, _utils.getTokensPropType)('StackView'),
+  variant: _utils.variantProp.propType,
+
+  /**
+   * Sets the `flexDirection` of the container and, if `divider` is used, gives the Divider the appropriate direction.
+   */
+  direction: _utils.responsiveProps.getTypeOptionallyByViewport(_propTypes.default.oneOf(['column', 'row', 'column-reverse', 'row-reverse'])),
+
+  /**
+   * If true, renders a UDS `Divider` component between each item. If an object is passed,
+   * this object is passes as props to each Divider.
+   */
+  divider: _propTypes.default.oneOfType([_propTypes.default.bool, _propTypes.default.shape(_Divider.default.propTypes)]),
+
+  /**
+   * The size of the spacer 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: _utils.spacingProps.types.spacingValue,
+
+  /**
+   * A StackView 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.default.node
+};
+var _default = StackView;
+exports.default = _default;

package/lib/StackView/StackWrap.js

@@ -0,0 +1,55 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+
+var _react = _interopRequireDefault(require("react"));
+
+var _Platform = _interopRequireDefault(require("react-native-web/dist/cjs/exports/Platform"));
+
+var _StackWrapBox = _interopRequireDefault(require("./StackWrapBox"));
+
+var _StackWrapGap = _interopRequireDefault(require("./StackWrapGap"));
+
+var _jsxRuntime = require("react/jsx-runtime");
+
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+
+// 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 = props => {
+  var _props$gap, _CSS;
+
+  const {
+    space
+  } = props; // Don't apply separate gap if `null` or `undefined`, so can be unset in Storybook etc
+  // eslint-disable-next-line react/destructuring-assignment
+
+  const gap = (_props$gap = props.gap) !== null && _props$gap !== void 0 ? _props$gap : space;
+  const canUseCSSGap = _Platform.default.OS === 'web' && gap === space && // In Jest/CI, global CSS isn't always available and doesn't always have .supports method
+  typeof ((_CSS = CSS) === null || _CSS === void 0 ? void 0 : _CSS.supports) === 'function' && CSS.supports('gap', exampleGapValue);
+  return canUseCSSGap ?
+  /*#__PURE__*/
+  // If possible, use the cleaner implementation that applies CSS `gap` styles to the container.
+  (0, _jsxRuntime.jsx)(_StackWrapGap.default, { ...props
+  }) :
+  /*#__PURE__*/
+  // Else, use the fallback implementation which renders a `Box` component around each child.
+  (0, _jsxRuntime.jsx)(_StackWrapBox.default, { ...props
+  });
+};
+
+StackWrap.propTypes = _StackWrapBox.default.propTypes;
+var _default = StackWrap;
+exports.default = _default;

package/lib/StackView/StackWrap.native.js

@@ -0,0 +1,14 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+
+var _StackWrapBox = _interopRequireDefault(require("./StackWrapBox"));
+
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+
+// No support for CSS `gap` on React Native, so always use the fallback "box" implementation.
+var _default = _StackWrapBox.default;
+exports.default = _default;

package/lib/StackView/StackWrapBox.js

@@ -0,0 +1,120 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+
+var _react = _interopRequireDefault(require("react"));
+
+var _propTypes = _interopRequireDefault(require("prop-types"));
+
+var _View = _interopRequireDefault(require("react-native-web/dist/cjs/exports/View"));
+
+var _utils = require("../utils");
+
+var _ThemeProvider = require("../ThemeProvider");
+
+var _ViewportProvider = require("../ViewportProvider");
+
+var _getStackedContent = _interopRequireDefault(require("./getStackedContent"));
+
+var _common = require("./common");
+
+var _jsxRuntime = require("react/jsx-runtime");
+
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+
+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 = ({
+  space = 1,
+  gap = space,
+  direction: directionProp = 'row',
+  children,
+  tokens,
+  variant,
+  ...rest
+}) => {
+  const viewport = (0, _ViewportProvider.useViewport)();
+  const direction = (0, _utils.useResponsiveProp)(directionProp, 'row');
+  const themeTokens = (0, _ThemeProvider.useThemeTokens)('StackView', tokens, variant, {
+    viewport
+  });
+  const flexStyles = (0, _common.selectFlexStyles)(themeTokens);
+  const props = { ..._utils.a11yProps.select(rest),
+    ..._utils.viewProps.select(rest)
+  }; // Mimic CSS `gap` using box spacing on the side after a wrapped row then offsetting it on the last row.
+
+  const gapSize = (0, _utils.useSpacingScale)(gap);
+  const offsetStyle = {
+    [offsetSides[direction]]: -1 * gapSize
+  };
+  const boxProps = {
+    [gapSides[direction]]: gap,
+    [spaceSides[direction]]: space
+  };
+  const content = (0, _getStackedContent.default)(children, {
+    direction,
+    space: 0,
+    box: boxProps
+  });
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)(_View.default, { ...props,
+    style: [flexStyles, _common.staticStyles.wrap, _common.staticStyles[direction], offsetStyle],
+    children: content
+  });
+};
+
+StackWrapBox.propTypes = { ..._utils.a11yProps.propTypes,
+  tokens: (0, _utils.getTokensPropType)('StackView'),
+
+  /**
+   * Sets the `flexDirection` of the container
+   */
+  direction: _utils.responsiveProps.getTypeOptionallyByViewport(_propTypes.default.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: _utils.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: _utils.spacingProps.types.spacingValue,
+
+  /**
+   * 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.default.node
+};
+var _default = StackWrapBox;
+exports.default = _default;

package/lib/StackView/StackWrapGap.js

@@ -0,0 +1,71 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+
+var _react = _interopRequireDefault(require("react"));
+
+var _View = _interopRequireDefault(require("react-native-web/dist/cjs/exports/View"));
+
+var _StackWrapBox = _interopRequireDefault(require("./StackWrapBox"));
+
+var _utils = require("../utils");
+
+var _ThemeProvider = require("../ThemeProvider");
+
+var _ViewportProvider = require("../ViewportProvider");
+
+var _getStackedContent = _interopRequireDefault(require("./getStackedContent"));
+
+var _common = require("./common");
+
+var _jsxRuntime = require("react/jsx-runtime");
+
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+
+/**
+ * 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 = ({
+  space = 1,
+  tokens,
+  variant,
+  direction: directionProp = 'row',
+  children,
+  ...rest
+}) => {
+  const viewport = (0, _ViewportProvider.useViewport)();
+  const direction = (0, _utils.useResponsiveProp)(directionProp, 'row');
+  const themeTokens = (0, _ThemeProvider.useThemeTokens)('StackView', tokens, variant, {
+    viewport
+  });
+  const flexStyles = (0, _common.selectFlexStyles)(themeTokens);
+  const props = { ..._utils.a11yProps.select(rest),
+    ..._utils.viewProps.select(rest)
+  };
+  const size = (0, _utils.useSpacingScale)(space);
+  const gapStyle = {
+    gap: size
+  };
+  const content = (0, _getStackedContent.default)(children, {
+    direction,
+    space: 0
+  });
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)(_View.default, { ...props,
+    style: [flexStyles, _common.staticStyles.wrap, _common.staticStyles[direction], gapStyle],
+    children: content
+  });
+};
+
+StackWrapGap.propTypes = _StackWrapBox.default.propTypes;
+var _default = StackWrapGap;
+exports.default = _default;

package/lib/StackView/common.js

@@ -0,0 +1,47 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.staticStyles = exports.selectFlexStyles = void 0;
+
+var _StyleSheet = _interopRequireDefault(require("react-native-web/dist/cjs/exports/StyleSheet"));
+
+function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
+
+const selectFlexStyles = ({
+  alignItems,
+  justifyContent,
+  flexGrow,
+  flexShrink
+}) => ({
+  alignItems,
+  justifyContent,
+  flexGrow,
+  flexShrink
+});
+
+exports.selectFlexStyles = selectFlexStyles;
+
+const staticStyles = _StyleSheet.default.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'
+  }
+});
+
+exports.staticStyles = staticStyles;