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

package/src/ThemeProvider/useThemeTokens.js

@@ -1,10 +1,21 @@
 import { useCallback } from 'react'
 import useTheme from './useTheme'
-import { getComponentTheme, getThemeTokens } from './utils'
+import { getComponentTheme, getThemeTokens, resolveTokens, mergeAppearances } from './utils'
+/**
+ * @typedef {import('../utils/propTypes.js').AppearanceSet} AppearanceSet
+ * @typedef {import('../utils/propTypes.js').TokensProp} TokensProp
+ * @typedef {import('../utils/propTypes.js').TokensSet} TokensSet
+ */
 
 /**
  * Returns a complete set of theme tokens for a component based on which of the
  * component's theme rules apply to the current set of theme appearances.
+ *
+ * @param {string} componentName - the name as defined in the theme schema of the component whose theme is to be used
+ * @param {TokensProp} [tokens] - every themed component should accept an optional `tokens` prop allowing theme tokens to be overridden
+ * @param {AppearanceSet} [variants] - every themed component should accept an optional `variants` prop specifying theme variants
+ * @param {AppearanceSet} [states] - optional object containing current theme appearances dictated by user action or context
+ * @returns {TokensSet} - the currently-applicable resolved set of theme tokens to apply
  */
 export const useThemeTokens = (componentName, tokens = {}, variants = {}, states = {}) => {
   const theme = useTheme()
@@ -14,16 +25,32 @@ export const useThemeTokens = (componentName, tokens = {}, variants = {}, states
 }
 
 /**
- * Returns a memoised function that behaves the same as useThemeTokens hook,
- * allowing tokens to be obtained inside callbacks and such other places where
- * calling useThemeTokens directly would be disallowed by React's hook rules.
+ * Returns a memoised tokens getter function that gets tokens similar to calling useThemeTokens.
+ * Scenarios where useThemeTokensCallback should be used instead of useThemeTokens include:
+ *
+ * - Where tokens to be obtained from state accessible only in scopes like callbacks and render functions,
+ *   where calling useThemeTokens directly would be disallowed by React's hook rules.
+ * - Passing a tokens getter down via a child component's `tokens` prop, applying rules using the
+ *   child component's current state. Consider wrapping the returned tokens in `selectTokens()`.
+ *
+ * @param {string} componentName - the name as defined in the theme schema of the component whose theme is to be used
+ * @param {TokensProp} [tokens] - every themed component should accept a `tokens` prop allowing theme tokens to be overridden
+ * @param {AppearanceSet} [variants] - variants passed in as props that don't change dynamically
+ * @returns {(states: AppearanceSet, tokenOverrides?: TokensProp) => TokensSet}
+ *    - callback function that returning an overridable tokens set for current state. Only pass
+ *      tokenOverrides in rare cases where tokens overrides are also generated outside hook scope,
+ *      e.g. if one theme tokens callback needs to pass certain token overrides to another.
  */
-export const useThemeTokensCallback = (componentName) => {
+export const useThemeTokensCallback = (componentName, tokens = {}, variants = {}) => {
   const theme = useTheme()
   const componentTheme = getComponentTheme(theme, componentName)
   const getThemeTokensCallback = useCallback(
-    (tokens, variants, states) => getThemeTokens(componentTheme, tokens, variants, states),
-    [componentTheme]
+    (states, tokenOverrides) => {
+      const appearances = mergeAppearances(variants, states)
+      const resolvedTokens = resolveTokens(tokens, tokenOverrides, appearances)
+      return getThemeTokens(componentTheme, resolvedTokens, appearances)
+    },
+    [componentTheme, tokens, variants]
   )
   return getThemeTokensCallback
 }

package/src/ThemeProvider/utils/theme-tokens.js

@@ -1,3 +1,9 @@
+/**
+ * @typedef {import('../../utils/propTypes.js').AppearanceSet} AppearanceSet
+ * @typedef {import('../../utils/propTypes.js').TokensProp} TokensProp
+ * @typedef {import('../../utils/propTypes.js').TokensSet} TokensSet
+ */
+
 /**
  * General utilities around working with theme tokens
  */
@@ -30,24 +36,48 @@ export const doesThemeConditionApply = ([key, value], appearances) => {
 export const doesThemeRuleApply = (rule, appearances) =>
   Object.entries(rule.if).every((condition) => doesThemeConditionApply(condition, appearances))
 
-const mergeTokens = (tokensProp, themeTokens, appearances) => {
-  const overrideTokens = typeof tokensProp === 'function' ? tokensProp(appearances) : tokensProp
-  return Object.entries(overrideTokens).reduce(
+/**
+ * Turns a tokens prop and an optional tokens override prop (either or both of which may be a tokens getter function)
+ * into one tokens set object where overrides are applied over the resolved default tokens.
+ *
+ * @param {TokensProp} defaultTokens - a set of tokens or tokens getter function which may be overridden
+ * @param {TokensProp} [tokenOverrides] - optional set of tokens or tokens getter function to override the default
+ * @param {AppearanceSet} [appearances] - optional appearance set to pass to tokens getter functions
+ * @returns {TokensSet} - object containing resolved tokens with overrides applied
+ */
+export const resolveTokens = (defaultTokens, tokenOverrides, appearances = {}) => {
+  const resolve = (tokens) => (typeof tokens === 'function' ? tokens(appearances) : tokens)
+  if (!tokenOverrides) return resolve(defaultTokens)
+
+  return Object.entries(resolve(tokenOverrides)).reduce(
     (mergedTokens, [tokenName, tokenValue]) =>
       tokenValue === undefined ? mergedTokens : { ...mergedTokens, [tokenName]: tokenValue },
-    themeTokens
+    resolve(defaultTokens)
   )
 }
 
+/**
+ * Merges variants over states. Must be merged in that order to allow static showcases of a state,
+ * e.g. `<Button variant={{ pressed: true }} />` where button's pressed state is `false` by default.
+ * Returns an empty object if both variants and states are undefined.
+ *
+ * @param {AppearanceSet} [variants]
+ * @param {AppearanceSet} [states]
+ * @returns {AppearanceSet}
+ */
+export const mergeAppearances = (variants = {}, states) =>
+  states ? { ...states, ...variants } : variants
+
 export const getThemeTokens = (
   { rules = [], tokens: defaultThemeTokens = {} },
   tokensProp,
   variants = {},
-  states = {}
+  states
 ) => {
-  const appearances = { ...states, ...variants }
+  const appearances = mergeAppearances(variants, states)
   // TODO: if in dev mode, validate the appearances and provided propTokens
 
+  // Get the theme's default tokens set and merge tokens from applicable theme rules over it
   const themeTokens = rules.reduce(
     (mergedTokens, rule) =>
       doesThemeRuleApply(rule, appearances)
@@ -58,8 +88,7 @@ export const getThemeTokens = (
         : mergedTokens,
     defaultThemeTokens
   )
-
-  return tokensProp ? mergeTokens(tokensProp, themeTokens, appearances) : themeTokens
+  return resolveTokens(themeTokens, tokensProp, appearances)
 }
 
 export const toArray = (strOrArr) => (Array.isArray(strOrArr) ? strOrArr : [strOrArr])

package/src/ToggleSwitch/ToggleSwitch.jsx

@@ -4,43 +4,29 @@ import { Platform, View, StyleSheet } from 'react-native'
 
 import ButtonBase from '../Button/ButtonBase'
 import { useThemeTokensCallback, applyShadowToken } from '../ThemeProvider'
-import { a11yProps, pressProps, variantProp, getTokensPropType } from '../utils/propTypes'
+import {
+  a11yProps,
+  pressProps,
+  variantProp,
+  getTokensPropType,
+  selectTokens
+} from '../utils/propTypes'
 import { useInputValue } from '../utils/input'
 
-const selectButtonTokens = ({
-  borderColor,
-  borderWidth,
-  borderRadius,
-  outerBorderColor,
-  outerBorderWidth,
-  outerBorderGap,
-  outerBorderRadius,
-  outerBackgroundColor,
-  backgroundColor,
-  opacity,
-  paddingLeft,
-  paddingRight,
-  paddingTop,
-  paddingBottom,
-  shadow
-}) => ({
-  borderColor,
-  borderWidth,
-  borderRadius,
-  outerBorderColor,
-  outerBorderWidth,
-  outerBorderGap,
-  outerBorderRadius,
-  outerBackgroundColor,
-  backgroundColor,
-  opacity,
-  paddingLeft,
-  paddingRight,
-  paddingTop,
-  paddingBottom,
-  shadow,
-  width: null // make it wrap around our track width
+const selectButtonTokens = (tokens) =>
+  selectTokens('Button', {
+    ...tokens,
+    // Width tokens are applied to our inner track. Disable Button width token so it wraps our track width.
+    width: null
+  })
+
+// Map and rename icon-specific tokens to name used within Icon
+const selectIconTokens = ({ iconSize, iconColor, iconOpacity }) => ({
+  opacity: iconOpacity,
+  size: iconSize,
+  color: iconColor
 })
+
 const selectTrackStyles = ({ trackBorderWidth, trackBorderColor, trackBorderRadius, width }) => ({
   borderWidth: trackBorderWidth,
   borderColor: trackBorderColor,
@@ -68,11 +54,6 @@ const selectSwitchStyles = ({
     web: { transition: 'transform 200ms' }
   })
 })
-const selectIconTokens = ({ iconSize, iconColor, iconOpacity }) => ({
-  opacity: iconOpacity,
-  size: iconSize,
-  color: iconColor
-})
 
 const ToggleSwitch = ({
   value,
@@ -83,7 +64,7 @@ const ToggleSwitch = ({
   variant,
   accessibilityRole = 'switch'
 }) => {
-  const getTokens = useThemeTokensCallback('ToggleSwitch')
+  const getTokens = useThemeTokensCallback('ToggleSwitch', tokens, variant)
 
   const { currentValue, setValue } = useInputValue({
     value,
@@ -93,8 +74,7 @@ const ToggleSwitch = ({
 
   const handlePress = () => setValue(!currentValue)
 
-  const getButtonTokens = (buttonState) =>
-    selectButtonTokens(getTokens(tokens, variant, buttonState))
+  const getButtonTokens = (buttonState) => selectButtonTokens(getTokens(buttonState))
 
   return (
     <ButtonBase
@@ -106,7 +86,7 @@ const ToggleSwitch = ({
       onPress={handlePress}
     >
       {(buttonState) => {
-        const themeTokens = getTokens(tokens, variant, buttonState)
+        const themeTokens = getTokens(buttonState)
         const IconComponent = themeTokens.icon
         const switchStyles = selectSwitchStyles(themeTokens)
         const trackStyles = selectTrackStyles(themeTokens)

package/src/Typography/Typography.jsx

@@ -33,8 +33,6 @@ const selectTextStyles = ({
   color,
   lineHeight,
   fontName,
-  marginTop,
-  marginBottom,
   textAlign,
   textTransform
 }) =>
@@ -44,8 +42,6 @@ const selectTextStyles = ({
     color,
     lineHeight,
     fontName,
-    marginTop,
-    marginBottom,
     textAlign,
     textTransform
   })

package/src/index.js

@@ -1,19 +1,26 @@
 export { default as ActivityIndicator } from './ActivityIndicator'
 export { default as Box } from './Box'
 export * from './Button'
+export { default as Card } from './Card'
 export { default as Divider } from './Divider'
 export { default as ExpandCollapse, Accordion } from './ExpandCollapse'
+export { default as Feedback } from './Feedback'
 export { default as FlexGrid } from './FlexGrid'
 export { default as Icon } from './Icon'
 export * from './Icon'
 export * from './Link'
+export { default as Pagination } from './Pagination'
 export { default as SideNav } from './SideNav'
+export { default as Spacer } from './Spacer'
+export { default as StackView } from './StackView'
+export * from './StackView'
+export { default as TextInput } from './TextInput'
 export { default as ToggleSwitch } from './ToggleSwitch'
 export { default as Typography } from './Typography'
 
 export { default as A11yInfoProvider, useA11yInfo } from './A11yInfoProvider'
 export { default as BaseProvider } from './BaseProvider'
 export { default as ViewportProvider, useViewport } from './ViewportProvider'
-export { default as ThemeProvider, useTheme, useSetTheme } from './ThemeProvider'
+export { default as ThemeProvider, useTheme, useSetTheme, useThemeTokens } from './ThemeProvider'
 
 export * from './utils'

package/src/utils/index.js

@@ -1,3 +1,4 @@
 export * from './animation'
 export * from './input'
 export * from './propTypes'
+export * from './spacing'

package/src/utils/input.js

@@ -55,6 +55,7 @@ Consumers of this hook must be one of:
  *   currentValue: any
  *   setValue: (value: any) => void
  *   resetValue: () => void
+ *   isControlled: bool
  * }}
  */
 
@@ -81,7 +82,7 @@ export const useInputValue = (props = {}, hookName = 'useInputValue') => {
   )
   const resetValue = useCallback(() => setValue(initializedValue), [initializedValue, setValue])
 
-  return { currentValue, setValue, resetValue }
+  return { currentValue, setValue, resetValue, isControlled }
 }
 
 /**

package/src/utils/propTypes.js

@@ -2,6 +2,10 @@ 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.
@@ -17,7 +21,10 @@ export const variantProp = {
   )
 }
 
-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]
@@ -40,15 +47,18 @@ export const selectTokens = (componentName, tokens) => {
   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([
@@ -251,19 +261,87 @@ export const linkProps = {
   }
 }
 
-export const levelsPropType = PropTypes.oneOf([0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11])
+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))])
+}
 
-export const responsivePropTypeFactory = (propType) =>
-  PropTypes.oneOfType([
-    propType,
-    PropTypes.shape({
-      xs: propType,
-      sm: propType,
-      md: propType,
-      lg: propType,
-      xl: 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
@@ -347,3 +425,14 @@ export const componentPropType = (passedName, checkDisplayName = false) => {
 
   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/src/utils/spacing/index.js

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

package/src/utils/spacing/useSpacingScale.js

@@ -0,0 +1,93 @@
+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/src/utils/spacing/utils.js

@@ -0,0 +1,28 @@
+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/src/utils/useUniqueId.js

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

package/stories/A11yText/A11yText.stories.jsx

@@ -4,6 +4,7 @@ import { StyleSheet, Text, View } from 'react-native'
 
 import A11yText from '../../lib/A11yText'
 import { Button, Typography } from '../../lib'
+import { EachParentType, parentTypesParams } from '../supports'
 
 const defaultArgs = {
   text: 'This text is for screen readers,',
@@ -31,6 +32,10 @@ const Template = (args) => (
   </>
 )
 
+export const Default = (args) => <A11yText {...args} />
+Default.storyName = 'A11yText'
+Default.args = defaultArgs
+
 export const A11yTextInText = Template.bind({})
 A11yTextInText.args = defaultArgs
 
@@ -50,12 +55,13 @@ export const A11yTextInButton = (args) => (
 )
 A11yTextInButton.args = defaultArgs
 
-export const A11yTextInRow = (args) => (
-  <View style={styles.row}>
-    <Template {...args} />
-  </View>
+export const ParentTypes = (args) => (
+  <EachParentType {...args}>
+    {({ label }) => <Template {...args} key={label} text={label} />}
+  </EachParentType>
 )
-A11yTextInRow.args = defaultArgs
+ParentTypes.args = defaultArgs
+ParentTypes.parameters = parentTypesParams
 
 const styles = StyleSheet.create({
   // Use borders so any hairline gaps created by A11yText are visible