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

package/lib/utils/propTypes.js

@@ -1,6 +1,11 @@
 import PropTypes from 'prop-types';
 import { Linking, Platform } from 'react-native';
 import { tokenKeys } from '@telus-uds/tools-theme';
+/**
+ * @typedef {{[key: string]: string|number|boolean}} AppearanceSet
+ * @typedef {AppearanceSet} VariantProp
+ */
+
 export const variantProp = {
   /**
    * 'variant' is an optional object prop on all themable components.
@@ -12,8 +17,11 @@ export const variantProp = {
    * the exact shape of variant props is not enforced using PropTypes.
    */
   propType: PropTypes.objectOf(PropTypes.oneOfType([PropTypes.string, PropTypes.number, PropTypes.bool]))
-};
-const tokenValueType = PropTypes.oneOfType([PropTypes.string, PropTypes.number, PropTypes.bool]);
+}; // Tokens can be primitive values (e.g. `'rgba(0,0,0,0'`, `12`), or objects of such values
+// such as tokens that describe shadow (e.g. shadow: { inset: true, color: 'rgba(...)' ... })
+
+const tokenValue = PropTypes.oneOfType([PropTypes.string, PropTypes.number, PropTypes.bool]);
+const tokenValueType = PropTypes.oneOfType([tokenValue, PropTypes.objectOf(tokenValue)]);
 
 const getTokenNames = componentName => {
   const componentTokenNames = tokenKeys[componentName];
@@ -36,15 +44,19 @@ export const selectTokens = (componentName, tokens) => {
   } : validTokens, {});
   return filteredTokens;
 };
+/**
+ * @typedef {string|number|boolean|{[key: string]:string|number|boolean}} TokenValue
+ * @typedef {{[key: string]: TokenValue}} TokensSet
+ * @typedef {(AppearanceSet) => TokensSet} TokensGetter
+ * @typedef {TokensSet|TokensGetter} TokensProp
+ */
+
 /**
  * 'tokens' is an optional object prop on all themable components. Its keys must match the
  * token keys in the component's theme schema.
  *
  * This prop is intended to be used as an 'escape hatch' for difficult or exceptional cases
  * where the main theming system doesn't apply. It is intentionally permissive about values.
- *
- * Be careful about passing a token key with value `undefined`, as this will override any tokens from
- * the theme. If a key is set on a `tokens` prop object, tokens from the theme will be overridden.
  */
 
 export const getTokensPropType = componentName => PropTypes.oneOfType([PropTypes.shape(Object.fromEntries(getTokenNames(componentName).map(key => [key, tokenValueType]))), PropTypes.func // function that takes current appearances and returns above shape
@@ -247,14 +259,88 @@ export const linkProps = {
     return Platform.OS !== 'web' && href ? () => Linking.openURL(href) : onPress;
   }
 };
-export const levelsPropType = PropTypes.oneOf([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]);
-export const responsivePropTypeFactory = propType => PropTypes.oneOfType([propType, PropTypes.shape({
+
+const getByViewport = propType => ({
   xs: propType,
   sm: propType,
   md: propType,
   lg: propType,
   xl: propType
-})]);
+});
+/**
+ * Utilities for props that allow different values to be applied at different viewports.
+ *
+ * These should apply viewport inheritance such that if a viewport is undefined, the value is
+ * taken from the next smallest viewport for which a value is available. For example, a
+ * responsive prop { xs: 2, lg: 3 } should apply 2 at sizes sm and md, and 3 at size xl.
+ *
+ * @property {Function} getByViewport - returns an object where each each viewport has a key
+ *   containing the provided argument.
+ * @property {Function} getTypeByViewport - returns a PropTypes shape validator for an object where
+ *   each viewport has a key containing the provided proptype.
+ * @property {Function} getTypeOptionallyByViewport - returns a PropTypes validator that accepts
+ *   either the provided proptype on its own, or the output of getTypeByViewport
+ */
+
+
+export const responsiveProps = {
+  getByViewport,
+  getTypeByViewport: propType => PropTypes.shape(getByViewport(propType)),
+  getTypeOptionallyByViewport: propType => PropTypes.oneOfType([propType, PropTypes.shape(getByViewport(propType))])
+};
+/**
+ * @typedef {0|1|2|3|4|5|6|7|8|9|10|11} SpacingIndex - value used to select a size on the spacing scale
+ *
+ * @typedef SpacingOptions
+ * @property {VariantProp} [SpacingOptions.variant] - optional theme scale variants e.g. compact, wide
+ * @property {number} [SpacingOptions.size] - optional override to force a particular pixel size
+ * @property {number} [SpacingOptions.subtract] - optional number to subtract from final pixel size
+ *
+ * @typedef SpacingObject
+ * @property {SpacingIndex} [SpacingObject.xs] - space scale index to use above xs viewport
+ * @property {SpacingIndex} [SpacingObject.sm] - space scale index to use above sm viewport
+ * @property {SpacingIndex} [SpacingObject.md] - space scale index to use above md viewport
+ * @property {SpacingIndex} [SpacingObject.lg] - space scale index to use above lg viewport
+ * @property {SpacingIndex} [SpacingObject.xl] - space scale index to use above xl viewport
+ * @property {SpacingIndex} [SpacingObject.space] - space scale index to use at all viewports
+ * @property {SpacingOptions} [SpacingObject.options] - optional options for this spacing
+ *
+ * @typedef {SpacingIndex|SpacingObject} SpacingValue
+ */
+
+const spacingScale = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11];
+const spacingIndexPropType = PropTypes.oneOf(spacingScale);
+const spacingObjectPropType = PropTypes.shape({ ...responsiveProps.getByViewport(spacingIndexPropType),
+  space: spacingIndexPropType,
+  options: PropTypes.shape({
+    variant: variantProp.propType,
+    size: PropTypes.number
+  })
+});
+/**
+ * Components and utilities that assign fixed space between components use a theme-defined spacing scale.
+ *
+ * They typically take one or more props of the {@link SpacingValue} type and turn it into a pixel size value
+ * using the hook `useSpacingScale`, which resolves any options or responsive behaviour and returns the
+ * appropriate value from the theme spacing scale.
+ *
+ * - see /ADRs/inter-component-spacing/README.md - ADR on this structure
+ * - see /src/utils/spacing/useSpacingScale.js - hook that processes spacing values
+ * - @see {@link SpacingIndex} - themes provide spacing scales of up to 12 sizes with optional theme rules.
+ * - @see {@link SpacingValue} - either a simple number referencing an index position on the spacing
+ *   scale, or an object with an optional `options` key and one or more spacing indexes keyed either by
+ *   viewports or `space` to apply at all viewports.
+ */
+
+export const spacingProps = {
+  scale: spacingScale,
+  types: {
+    spacingIndex: spacingIndexPropType,
+    spacingObject: spacingObjectPropType,
+    // Most spacing components and utilities take this prop / arg type:
+    spacingValue: PropTypes.oneOfType([spacingIndexPropType, spacingObjectPropType])
+  }
+};
 /**
  * Returns a prop type validator which checks whether a prop is either a component or an array of components of a given
  * type, based on their `name` property.
@@ -318,4 +404,13 @@ export const componentPropType = (passedName, checkDisplayName = false) => {
   const validate = createValidate();
   validate.isRequired = createValidate(true);
   return validate;
+};
+export const copyPropTypes = PropTypes.oneOf(['en', 'fr']);
+export const paddingProp = {
+  propType: PropTypes.shape({
+    paddingBottom: PropTypes.number,
+    paddingLeft: PropTypes.number,
+    paddingRight: PropTypes.number,
+    paddingTop: PropTypes.number
+  })
 };

package/lib/utils/spacing/index.js

@@ -0,0 +1,2 @@
+export { default as useSpacingScale } from './useSpacingScale';
+export * from './utils';

package/lib/utils/spacing/useSpacingScale.js

@@ -0,0 +1,102 @@
+import { useViewport } from '../../ViewportProvider';
+import { useThemeTokens } from '../../ThemeProvider';
+import { resolveSpacingValue, resolveSpacingOptions } from './utils';
+/**
+ * @typedef {import('@telus-uds/system-constants/viewports').Viewport} Viewport
+ * @typedef {import('../propTypes.js').SpacingValue} SpacingValue
+ * @typedef {import('../propTypes.js').SpacingIndex} SpacingIndex
+ * @typedef {import('../propTypes.js').SpacingObject} SpacingObject
+ * @typedef {import('../propTypes.js').SpacingOptions} SpacingOptions
+ */
+
+/**
+ * Pass a {@link SpacingValue}, which is one of:
+ *
+ * - A number 0-11 ({@link SpacingIndex}) pointing to an index on the theme's spacing scale
+ * - Or, an object ({@link SpacingObject}), with optional properties:
+ *   -  `xs`, `sm`, `md`, `lg`, `xl`: {@link SpacingIndex} to apply at or above these specified {@link Viewport}
+ *   - `options`: an optional {@link SpacingOptions} object, see below
+ *   - `space`: a {@link SpacingIndex} to apply to all viewports (can be used alongside `options`)
+ *
+ * ## Example
+ *
+ * If the theme's spacing scale is `[0, 4, 8, 12, 16, 24, 48]` with no theme rules:
+ *
+ * - `useSpacingScale(0)` returns `0`
+ * - `useSpacingScale(2)` returns `8`
+ * - `useSpacingScale({ xs: 3, lg: 4 })` returns `12` at 'xs', 'sm' or 'md' viewports, and `16` at 'lg' or 'xl'.
+ *
+ * These viewport properties are intended to support case-specific responsive layout changes, for example, where a
+ * grid item drops or adds spacing on a particular side at viewports where the parent changes the layout shape.
+ *
+ * ## Theming
+ *
+ * A theme's `'spacingScale'` has theme rules and appearances same as components, and may support `viewport`.
+ * For example, a theme with the following rule would change index [2] above from `8` to `12` on large viewports:
+ *
+ * ```json
+ * { if: { space: 2, viewport: ['lg', 'xl'] }, tokens: { size: 12 }}
+ * ```
+ *
+ * Setting responsive spacing in the theme is the preferred way to adapt the aesthetic tightness or looseness of
+ * a theme to the available space without changing the shape of the layout itself.
+ *
+ * ## Options
+ *
+ * Space values passed as objects may have an `options` key, with the following optional properties:
+ *
+ * - `variant`: Themes may choose to have spacing scale variants, same as variants in component themes.
+ *   For example, if a theme rule contains `{ if: { space: 2, compact: true }, tokens: { size: 6 }}`,
+ *   this tighter spacing can be accessed with:
+ *
+ * ```jsx
+ * const compactSize = useSpacingScale({ space: 2, options: { variant: { compact: true }}})`
+ * ```
+ *
+ * - `subtract`: Sometimes on-brand spacing needs to be reduced by another value to achieve an on-brand result.
+ *   For example, a component with a variable border may want to subtract its border width from its padding so
+ *   the total distance from content edge to bounding box is a valid theme value, regardless of border width:
+ *
+ * ```jsx
+ * const padding = useSpacingScale({ space: 2, options: { subtract: themeTokens.borderWidth }})
+ * ```
+ *
+ * - `size`: In exceptional cases, the theme's spacing scale may be bypassed by passing a `size` option.
+ *   This can result in layouts that may be rejected for being off-brand so should only be used as a
+ *   last resort for fixing layout problems (e.g. when working around non-branded embedded content).
+ *   Where possible, fixing layout issues using a spacing scale value and the `subtract` option is preferred.
+ *
+ * ```jsx
+ * // Comments should be included when `size` is used, stating why this off-brand size is needed
+ * const iframeOffset = useSpacingScale({ options: { size: 13 }})`
+ * ```
+ *
+ * ## References
+ *
+ * `/ADRs/inter-component-spacing/README.md` - ADR on this structure
+ *
+ * @param {SpacingValue} [spaceValue] - a {@link SpacingIndex} number, or a {@link SpacingObject}
+ * @returns {number}
+ */
+
+const useSpacingScale = spaceValue => {
+  // In future, may need to consider window height as well as width, particularly for native apps,
+  // e.g. to ensure designs don't look lost on large, tall, not-so-wide portrait screens.
+  const viewport = useViewport();
+  const {
+    tokens,
+    variant,
+    overridden,
+    subtract = 0
+  } = resolveSpacingOptions(spaceValue);
+  const space = overridden ? null : resolveSpacingValue(spaceValue, viewport);
+  const {
+    size
+  } = useThemeTokens('spacingScale', tokens, variant, {
+    space,
+    viewport
+  });
+  return Math.max(size - subtract, 0);
+};
+
+export default useSpacingScale;

package/lib/utils/spacing/utils.js

@@ -0,0 +1,32 @@
+import { viewports as systemViewports } from '@telus-uds/system-constants';
+export const resolveSpacingValue = (space, viewport) => {
+  // If spacing value has been passed as undefined or nullish, get the 0-index
+  if (!space) return 0; // Pass through simple non-responsive numbers (which may be in objects alongside options)
+
+  if (typeof space === 'number') return space;
+  if (typeof space.space === 'number') return space.space; // Get the appropriate space value for the current viewport.
+  // If no viewports available (e.g. SSR), default to the smallest.
+  // If no values are found (e.g. empty space object), default to 0.
+
+  return (viewport && systemViewports.inherit(space)[viewport]) ?? space.xs ?? 0;
+};
+export const resolveSpacingOptions = space => {
+  if (!space?.options) return {};
+  const {
+    size,
+    variant,
+    subtract = 0
+  } = space.options;
+  const overridden = typeof size === 'number'; // Might need an option that adapts the size value by current user's system font scale, so that
+  // meaningful spacing between items doesn't disappear on the highest a11y font scale settings.
+  // https://github.com/telus/universal-design-system/issues/583
+
+  return {
+    tokens: {
+      size
+    },
+    variant,
+    overridden,
+    subtract
+  };
+};

package/lib/utils/useUniqueId.js

@@ -0,0 +1,12 @@
+import { useState } from 'react';
+let id = 0;
+
+function useUniqueId(prefix = '') {
+  const [uniqueId] = useState(() => {
+    id += 1;
+    return `${prefix}-${id}`;
+  });
+  return uniqueId;
+}
+
+export default useUniqueId;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telus-uds/components-base",
-  "version": "0.0.2-prerelease.1",
+  "version": "0.0.2-prerelease.5",
   "description": "Base components",
   "keywords": [
     "base"
@@ -24,7 +24,7 @@
     "lint": "telus-standard",
     "lint:fix": "telus-standard --fix",
     "format": "prettier --write .",
-    "build": "babel --root-mode upward src --out-dir lib",
+    "build": "babel src -d lib",
     "dev": "yarn build --watch",
     "release": "standard-version"
   },
@@ -37,21 +37,18 @@
   "peerDependencies": {
     "react": "*",
     "react-native": "*",
-    "react-native-web": "^0.14.13"
+    "react-native-web": "~0.14.13"
   },
   "devDependencies": {
-    "@babel/cli": "^7.9.0",
-    "@babel/plugin-transform-react-jsx": "^7.14.9",
     "@testing-library/jest-native": "^4.0.1",
     "@testing-library/react-hooks": "^7.0.1",
     "@testing-library/react-native": "^7.2.0",
     "react-test-renderer": "^16.3.2"
   },
   "dependencies": {
-    "@telus-uds/system-constants": "^0.0.2-prerelease.0",
-    "@telus-uds/tools-theme": "^0.0.2-prerelease.0",
+    "@telus-uds/system-constants": "^0.0.2-prerelease.1",
+    "@telus-uds/tools-theme": "^0.0.2-prerelease.3",
     "lodash.merge": "^4.6.2",
     "prop-types": "^15.7.2"
-  },
-  "gitHead": "a4930bde09eae51c0c77e78c8fd1bdeb918f5bd3"
+  }
 }

package/release-context.json

@@ -1,7 +1,7 @@
 {
-  "previousReleaseTag": "@telus-uds/components-base/v0.0.2-prerelease.0",
-  "changelog": "### [0.0.2-prerelease.1](https://github.com/telus/universal-design-system/compare/@telus-uds/components-base/v0.0.2-prerelease.0...@telus-uds/components-base/v0.0.2-prerelease.1) (2021-10-04)\n\n\n### Features\n\n* **base:** add ExpandCollapse component ([#584](https://github.com/telus/universal-design-system/issues/584)) ([12f0c68](https://github.com/telus/universal-design-system/commit/12f0c68de703fc032b2e1997dda52a4c370d4a3d))\n\n\n### Bug Fixes\n\n* **base:** fix button size when in block div ([#575](https://github.com/telus/universal-design-system/issues/575)) ([da7a80a](https://github.com/telus/universal-design-system/commit/da7a80ac6ff7bddb310895a3319e7822d35be969))\n",
-  "releaseTag": "@telus-uds/components-base/v0.0.2-prerelease.1",
-  "newVersion": "0.0.2-prerelease.1",
+  "previousReleaseTag": "@telus-uds/components-base/v0.0.2-prerelease.4",
+  "changelog": "### [0.0.2-prerelease.5](https://github.com/telus/universal-design-system/compare/@telus-uds/components-base/v0.0.2-prerelease.4...@telus-uds/components-base/v0.0.2-prerelease.5) (2021-10-27)\n\n\n### Features\n\n* **allium-web:** Add `ExpandCollapseMiniControl` component ([#661](https://github.com/telus/universal-design-system/issues/661)) ([227407e](https://github.com/telus/universal-design-system/commit/227407ec6a48c0a170b8e39761ba33293f13eb3c)), closes [#605](https://github.com/telus/universal-design-system/issues/605) [#605](https://github.com/telus/universal-design-system/issues/605) [#605](https://github.com/telus/universal-design-system/issues/605) [#605](https://github.com/telus/universal-design-system/issues/605) [#605](https://github.com/telus/universal-design-system/issues/605)\n* **allium:** add Allium `Card` ([#639](https://github.com/telus/universal-design-system/issues/639)) ([f88179c](https://github.com/telus/universal-design-system/commit/f88179c503dfe574bf7bac6bb36ce4726a9af338))\n* **base, allium:** add reverse directions and switch Allium card to using `StackView` ([#676](https://github.com/telus/universal-design-system/issues/676)) ([819a15f](https://github.com/telus/universal-design-system/commit/819a15f059faa47d1bc4e96c6370e9694effc003))\n* **base:** add StackView and Spacer ([#662](https://github.com/telus/universal-design-system/issues/662)) ([cc3965e](https://github.com/telus/universal-design-system/commit/cc3965e83c1ec2fa0f0dd006a03eeeeda5384940))\n* **base:** add StackWrap component ([#666](https://github.com/telus/universal-design-system/issues/666)) ([f34fb60](https://github.com/telus/universal-design-system/commit/f34fb60d0a923b1e4b3105c21b4a762b630ab309))\n* **base:** add TextInput component ([#649](https://github.com/telus/universal-design-system/issues/649)) ([245c073](https://github.com/telus/universal-design-system/commit/245c073ed3ba3a022f989d234fbf5cf972edec25))\n* **base:** add the Feedback component ([#656](https://github.com/telus/universal-design-system/issues/656)) ([5d7a5b6](https://github.com/telus/universal-design-system/commit/5d7a5b69c870ce1077adfdb230fddd1aa120b373))\n\n\n### Bug Fixes\n\n* **base:** control stretch from a row parent ([#668](https://github.com/telus/universal-design-system/issues/668)) ([fa13c37](https://github.com/telus/universal-design-system/commit/fa13c37b2bd6b4118dbeb39bc2cdf59d13d5b151))\n* **base:** fix icon link width in block container ([#645](https://github.com/telus/universal-design-system/issues/645)) ([ff60d1d](https://github.com/telus/universal-design-system/commit/ff60d1d1d0a66b7735b902098c7ca22e442265e1))\n",
+  "releaseTag": "@telus-uds/components-base/v0.0.2-prerelease.5",
+  "newVersion": "0.0.2-prerelease.5",
   "packageName": "@telus-uds/components-base"
 }

package/src/Box/Box.jsx

@@ -1,112 +1,149 @@
 import React from 'react'
 import PropTypes from 'prop-types'
 import { View, ScrollView } from 'react-native'
-import { useViewport } from '../ViewportProvider'
-import { useTheme, useThemeTokens } from '../ThemeProvider'
-import {
-  levelsPropType,
-  responsivePropTypeFactory,
-  variantProp,
-  getTokensPropType
-} from '../utils/propTypes'
-
-const propToStyleMap = {
-  top: 'paddingTop',
-  below: 'marginBottom',
-  bottom: 'paddingBottom',
-  left: 'paddingLeft',
-  right: 'paddingRight',
-  vertical: 'paddingVertical',
-  horizontal: 'paddingHorizontal'
-}
-
-const transformPropToStyle = (key) => propToStyleMap[key]
-
-const getStyleByType = (currentViewPort, styleProp, levels) => {
-  if (typeof styleProp === 'undefined') return null
-  if (typeof styleProp === 'number') return levels[currentViewPort][styleProp]
-  const spacingValue = styleProp[currentViewPort]
-  return levels[currentViewPort][spacingValue]
-}
+import { useThemeTokens } from '../ThemeProvider'
+import { a11yProps, spacingProps, variantProp, getTokensPropType, useSpacingScale } from '../utils'
+/**
+ * @typedef {import('../utils/propTypes.js').SpacingValue} SpacingValue
+ * @typedef {import('../utils/propTypes.js').SpacingIndex} SpacingIndex
+ * @typedef {import('../utils/propTypes.js').SpacingObject} SpacingObject
+ * @typedef {import('../utils/propTypes.js').SpacingOptions} SpacingOptions
+ */
 
-const getBaseStyle = (currentViewPort, styleProps, levels) => {
-  const styleObject = {}
-  Object.entries(styleProps).forEach(([key, styleProp]) => {
-    const styleKey = transformPropToStyle(key)
-    styleObject[styleKey] = getStyleByType(currentViewPort, styleProp, levels)
+const selectBoxStyles = (tokens) => {
+  const styles = { backgroundColor: tokens.backgroundColor }
+  const paddings = ['paddingLeft', 'paddingRight', 'paddingTop', 'paddingBottom']
+  // Only set on styles if token provided because we spread this object after the spacing scale values
+  paddings.forEach((side) => {
+    if (tokens[side]) {
+      styles[side] = tokens[side]
+    }
   })
-
-  return styleObject
+  return styles
 }
 
 /**
- * A layout utility component
+ * A layout utility component. Use Box to create space (padding) around content.
+ *
+ * ## Spacing
+ *
+ * For most simple uses, pass a number to Box's `space` prop referring to an index in the theme's
+ * spacing scale. For example, for a box with the theme's smallest non-zero amount of padding on all sides:
+ *
+ * ```jsx
+ * <Box space={1}>
+ * ```
+ *
+ * #### Targetting specific sides
+ *
+ * Box allows spacing value props to be assigned to any side or all sides using the following props:
+ *
+ * - `space` sets the default for all sides, which is overridden by other props below
+ * - `horizontal` sets defaults for `left` and `right` (overriding `space` there if it is set)
+ * - `vertical` sets defaults for `top` and `bottom` (overriding `space` there if it is set)
+ * - `left` sets the left side padding, inside the box's bounds
+ * - `right` sets the right side padding, inside the box's bounds
+ * - `top` sets the top side padding, inside the box's bounds
+ * - `bottom` sets the bottom side padding, inside the box's bounds
+ *
+ * Box only controls spacing within its bounds. If space is needed around a box outside of its bounds,
+ * use `Spacer`, `StackView` or wrap the `Box` inside another `Box`.
  *
- * > TODO decide on the API we want to offer here
+ * #### Viewport-specific spacing
+ *
+ * Responsive behaviours may be set by passing any of the above props an object keyed by viewports.
+ *
+ * For example, if a theme's spacing scale is [0, 4, 8...], this below will have padding of 4px on top,
+ * bottom, and right, and its left padding will be 0px on xs, sm and md viewports and 8px on lg and xl viewports:
+ *
+ * ```jsx
+ * <Box space={1} left={{ xs: 0, lg: 2 }} />`
+ * ```
+ *
+ * #### Subtracting from spacing
+ *
+ * A parent may sometimes need to reduce the spacing size on one or more sides of a `Box` by some variable.
+ * For example, the parent may have a border on one side and want to reduce the spacing of a child box
+ * by the width of that border on that side. This can be achieved using the `subtract` option of the
+ * spacing object, for example:
+ *
+ * ```jsx
+ * <Box space={2} left={{ space: 2, options: { subtract: themeTokens.borderWidthLeft } }} />`
+ * ```
+ *
+ * See `useSpacingScale` hook for other spacing value options and documentation.
+ *
+ * ## Theming
+ *
+ * Box is intended for layout, so minimal theming is supported. Use components like `Card` for
+ * more sophisticated theming.
+ *
+ * ## Scroll
+ *
+ * If passed, the box will be scrollable. If an object is passed, it will be passed to React Native's
+ * `ScrollView` component as props.
+ *
+ * When building native iOS and Android apps, it is important to remember to ensure any screen containing
+ * text content is inside a scrollable box, as screens are not scrollable by default and even very
+ * short text will require scrolling on small devices at the highest accessibility text scaling settings.
  */
 const Box = ({
+  space,
+  horizontal = space,
+  vertical = space,
+  top = vertical,
+  bottom = vertical,
+  left = horizontal,
+  right = horizontal,
   children,
-  top,
-  below,
-  bottom,
-  left,
-  right,
-  vertical,
-  horizontal,
   variant,
   tokens,
-  scroll = false,
-  scrollProps = null
+  scroll,
+  testID,
+  ...rest
 }) => {
-  const theme = useTheme()
+  const a11y = a11yProps.select(rest)
 
-  // TODO: integrate level resolution with other tokens as part of
-  // https://github.com/telus/universal-design-system/issues/267
-  const { levels } = theme.components.Box
-
-  // TODO: update Box logic to use viewport as an appearance context and make levels themable
-  // https://github.com/telus/universal-design-system/issues/87
-  const viewport = useViewport()
-  const { backgroundColor } = useThemeTokens('Box', tokens, variant)
-  const bkgStyle = { backgroundColor }
-
-  const styleProps = {
-    below,
-    bottom,
-    left,
-    right,
-    top,
-    vertical,
-    horizontal
+  const themeTokens = useThemeTokens('Box', tokens, variant)
+  const styles = {
+    paddingLeft: useSpacingScale(left),
+    paddingRight: useSpacingScale(right),
+    paddingTop: useSpacingScale(top),
+    paddingBottom: useSpacingScale(bottom),
+    ...selectBoxStyles(themeTokens)
   }
-  const baseStyle = getBaseStyle(viewport, styleProps, levels)
-  const styles = [baseStyle, bkgStyle]
 
   if (scroll) {
+    const scrollProps = typeof scroll === 'object' ? scroll : {}
+    scrollProps.contentContainerStyle = [styles, scrollProps.contentContainerStyle]
     return (
-      <ScrollView contentContainerStyle={styles} {...scrollProps}>
+      <ScrollView {...scrollProps} {...a11y} testID={testID}>
         {children}
       </ScrollView>
     )
   }
-  return <View style={styles}>{children}</View>
+  return (
+    <View {...a11y} style={styles} testID={testID}>
+      {children}
+    </View>
+  )
 }
 
-// TODO apply props as separate
-const responsiveLevelsPropType = responsivePropTypeFactory(levelsPropType)
-
 Box.propTypes = {
-  below: responsiveLevelsPropType,
-  bottom: responsiveLevelsPropType,
-  left: responsiveLevelsPropType,
-  right: responsiveLevelsPropType,
-  top: responsiveLevelsPropType,
-  vertical: responsiveLevelsPropType,
-  horizontal: responsiveLevelsPropType,
-  scroll: PropTypes.bool,
-  scrollProps: PropTypes.object,
+  space: spacingProps.types.spacingValue,
+  vertical: spacingProps.types.spacingValue,
+  horizontal: spacingProps.types.spacingValue,
+  bottom: spacingProps.types.spacingValue,
+  left: spacingProps.types.spacingValue,
+  right: spacingProps.types.spacingValue,
+  top: spacingProps.types.spacingValue,
+  scroll: PropTypes.oneOfType([
+    PropTypes.bool,
+    ScrollView.propTypes ? PropTypes.shape(ScrollView.propTypes) : PropTypes.object
+  ]),
   variant: variantProp.propType,
   tokens: getTokensPropType('Box'),
+  testID: PropTypes.string,
   children: PropTypes.node.isRequired
 }