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

package/src/utils/useSpacingScale.js

@@ -0,0 +1,108 @@
+import { useViewport } from '../ViewportProvider'
+import { useThemeTokens } from '../ThemeProvider'
+import { resolveResponsiveProp } from './useResponsiveProp'
+/**
+ * @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
+ */
+
+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 }
+}
+
+/**
+ * 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 && (spaceValue?.space ?? resolveResponsiveProp(spaceValue, viewport, 0))
+
+  const { size } = useThemeTokens('spacingScale', tokens, variant, {
+    space: typeof space === 'number' ? space : 0,
+    viewport
+  })
+  return Math.max(size - subtract, 0)
+}
+
+export default useSpacingScale

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

@@ -1,9 +1,10 @@
 /* eslint-disable react/no-multi-comp */
 import React from 'react'
-import { StyleSheet, Text, View } from 'react-native'
+import { StyleSheet, 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
 
@@ -39,23 +44,20 @@ A11yTextAsHeading.args = { ...defaultArgs, heading: true }
 
 export const A11yTextInButton = (args) => (
   <Button onPress={() => {}}>
-    {({ textStyles }) => (
-      <>
-        <A11yText {...args} />
-        <Text style={textStyles}>A11yText sandwich</Text>
-        <A11yText {...args} />
-      </>
-    )}
+    <A11yText {...args} />
+    A11yText sandwich
+    <A11yText {...args} />
   </Button>
 )
 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

package/stories/ActivityIndicator/ActivityIndicator.stories.jsx

@@ -1,5 +1,7 @@
+/* eslint-disable react/no-multi-comp */
 import React from 'react'
 import { ActivityIndicator } from '../../lib'
+import { EachParentType, parentTypesParams } from '../supports'
 
 export default {
   title: 'Base/ActivityIndicator',
@@ -9,5 +11,12 @@ export default {
   }
 }
 
-export const Story = (args) => <ActivityIndicator {...args} />
-Story.storyName = 'ActivityIndicator'
+export const Default = (args) => <ActivityIndicator {...args} />
+Default.storyName = 'ActivityIndicator'
+
+export const ParentTypes = (args) => (
+  <EachParentType {...args}>
+    {({ label }) => <ActivityIndicator {...args} label={label} />}
+  </EachParentType>
+)
+ParentTypes.parameters = parentTypesParams

package/stories/Box/Box.stories.jsx

@@ -2,21 +2,26 @@
 import React from 'react'
 
 import { View, StyleSheet } from 'react-native'
-import { Box } from '../../lib'
-import { Placeholder } from '../supports'
+import { Box, Typography } from '../../lib'
+import {
+  spacingObjectArg,
+  Container,
+  Placeholder,
+  EachParentType,
+  parentTypesParams
+} from '../supports'
 
 export default {
   title: 'Base/Box',
-  component: Box,
-  parameters: {
-    padded: false
-  }
+  component: Box
 }
 
 const Template = (args) => (
-  <Box {...args}>
-    <Placeholder>Box</Placeholder>
-  </Box>
+  <Container margin={0} padding={0} borderWidth={1} offWhite>
+    <Box {...args}>
+      <Placeholder>Box</Placeholder>
+    </Box>
+  </Container>
 )
 
 const ScrollTemplate = (args) => (
@@ -68,39 +73,49 @@ const ScrollTemplate = (args) => (
   </View>
 )
 
-const spacings = { xs: 2, sm: 4, md: 6, lg: 8, xl: 10 }
-
 const styles = StyleSheet.create({
   fixedHeight: { height: 200, overflow: 'hidden' }
 })
+
+export const Default = (args) => <Box {...args} />
+Default.storyName = 'Box'
+Default.args = { children: <Typography>Box</Typography> }
+// By default the JSX object is shown as a huge human-unreadable JSON tree control; turn it off
+Default.argTypes = { children: { control: { disable: true } } }
+
 export const Top = Template.bind({})
 Top.args = {
-  top: spacings
+  top: spacingObjectArg
 }
 
 export const Bottom = Template.bind({})
 Bottom.args = {
-  bottom: spacings
+  bottom: spacingObjectArg
 }
 
 export const Left = Template.bind({})
 Left.args = {
-  left: spacings
+  left: spacingObjectArg
 }
 
 export const Right = Template.bind({})
 Right.args = {
-  right: spacings
+  right: spacingObjectArg
 }
 
 export const Horizontal = Template.bind({})
 Horizontal.args = {
-  horizontal: spacings
+  horizontal: spacingObjectArg
 }
 
 export const Vertical = Template.bind({})
 Vertical.args = {
-  vertical: spacings
+  vertical: spacingObjectArg
+}
+
+export const AllSides = Template.bind({})
+AllSides.args = {
+  space: spacingObjectArg
 }
 
 export const Scroll = ScrollTemplate.bind({})
@@ -112,3 +127,17 @@ export const NoScroll = ScrollTemplate.bind({})
 NoScroll.args = {
   scroll: false
 }
+
+export const ParentTypes = (args) => (
+  <EachParentType componentThemeName="Box" {...args}>
+    {({ label, variant }) => (
+      <Container key={label} margin={0} padding={0} borderWidth={1} dark>
+        <Box {...args} variant={variant}>
+          <Placeholder>{label}</Placeholder>
+        </Box>
+      </Container>
+    )}
+  </EachParentType>
+)
+ParentTypes.args = { space: 2 }
+ParentTypes.parameters = parentTypesParams

package/stories/Button/Button.stories.jsx

@@ -1,9 +1,11 @@
+/* eslint-disable react/no-multi-comp */
 import React from 'react'
-import { Button as ButtonComponent, useTheme } from '../../lib'
-import { Container, useVariants, parentTypes } from '../supports'
+import { Button, useTheme } from '../../lib'
+import { Container, useVariants, EachParentType, parentTypesParams } from '../supports'
 import { getComponentTheme } from '../../lib/ThemeProvider/utils'
 
-export const Button = ButtonComponent
+export const Default = (args) => <Button {...args} />
+Default.storyName = 'Button'
 
 const defaultLabel = "I'm a button"
 
@@ -14,7 +16,8 @@ export default {
     // eslint-disable-next-line no-console
     onPress: () => console.log('Button pressed'),
     children: defaultLabel,
-    variant: {} // @TODO work out why this isn't coming from jsdoc
+    variant: {}, // @TODO work out why this isn't coming from jsdoc
+    tokens: {}
   }
 }
 
@@ -52,20 +55,18 @@ LongLabelButtonVariants.args = {
   children: 'This button has a label that is much longer than is considered advisable'
 }
 
-export const ButtonParentTypes = (args) => {
-  const variants = useVariants('Button')
-  return Object.entries(parentTypes).map(([parentLabel, ParentType]) => (
-    <Container borderWidth={1} key={parentLabel} offWhite>
-      <ParentType>
-        {variants.map(([key, value, variantLabel]) => {
-          const label = `${parentLabel}: ${variantLabel}`
-          return (
-            <Button {...args} key={label} variant={{ [key]: value }}>
-              {label}
-            </Button>
-          )
-        })}
-      </ParentType>
-    </Container>
-  ))
+export const ShortLabelButtonVariants = VariantsTemplate.bind({})
+ShortLabelButtonVariants.args = {
+  children: 'k'
 }
+
+export const ParentTypes = (args) => (
+  <EachParentType componentThemeName="Button" {...args}>
+    {({ label, variant }) => (
+      <Button {...args} key={label} variant={variant}>
+        {label}
+      </Button>
+    )}
+  </EachParentType>
+)
+ParentTypes.parameters = parentTypesParams

package/stories/Button/ButtonGroup.stories.jsx

@@ -59,7 +59,8 @@ const ControlledTemplate = ({ values, ...args }) => {
 
 ControlledTemplate.propTypes = ButtonGroup.propTypes
 
-export const ButtonGroupMaxOne = UncontrolledTemplate.bind({})
+export const Default = UncontrolledTemplate.bind({})
+Default.storyName = 'ButtonGroup'
 
 export const ButtonGroupMaxThree = UncontrolledTemplate.bind({})
 ButtonGroupMaxThree.args = { maxValues: 3 }

package/stories/Button/ButtonLink.stories.jsx

@@ -6,7 +6,7 @@ export default {
   title: 'Base/ButtonLink',
   component: ButtonLink,
   args: {
-    label: "I'm a button link",
+    children: "I'm a button link",
     href: 'https://telus.com',
     target: '_blank',
     rel: 'nofollow'
@@ -18,11 +18,13 @@ const Template = (args) => {
   return variants.map(([key, value, label]) => (
     <Container key={`${key}:${value}`} dark={key === 'inverse'}>
       <ButtonLink {...args} href="https://telus.com" variant={{ [key]: value }}>
-        {args.label || `Button ${label}`}
+        {args.label || `ButtonLink ${label}`}
       </ButtonLink>
     </Container>
   ))
 }
 
-export const ButtonLinkStory = Template.bind({})
-ButtonLinkStory.storyName = 'ButtonLink'
+export const Default = (args) => <ButtonLink {...args} />
+Default.storyName = 'ButtonLink'
+
+export const Variants = Template.bind({})

package/stories/Card/Card.stories.jsx

@@ -0,0 +1,62 @@
+/* eslint-disable react/no-multi-comp */
+import React from 'react'
+import { StyleSheet, Text, View } from 'react-native'
+
+import { Card } from '../../lib'
+import { Container, useVariants, EachParentType, parentTypesParams } from '../supports'
+
+export default {
+  title: 'Base/Card',
+  component: Card
+}
+
+const styles = StyleSheet.create({
+  cardContent: {
+    padding: 4,
+    borderWidth: 1,
+    borderColor: '#C12335',
+    borderStyle: 'dashed',
+    backgroundColor: '#FFF6F8'
+  }
+})
+
+export const Default = (args) => (
+  <Card {...args}>
+    <View style={styles.cardContent}>
+      <Text>This is a card</Text>
+    </View>
+  </Card>
+)
+Default.storyName = 'Card'
+Default.argTypes = {
+  children: { table: { disable: true } }
+}
+
+export const CardVariants = (args) => {
+  const variants = useVariants('Card')
+  const cardVariants = variants.map(([key, value, label]) => (
+    <Container key={`${key}:${value}`} padding={16}>
+      <Card {...args} variant={{ [key]: value }}>
+        <View style={styles.cardContent}>
+          <Text>
+            Card with
+            {` ${label}`}
+          </Text>
+        </View>
+      </Card>
+    </Container>
+  ))
+
+  return cardVariants
+}
+
+export const ParentTypes = (args) => (
+  <EachParentType componentThemeName="Card" {...args}>
+    {({ label, variant }) => (
+      <Card {...args} variant={variant} key={label}>
+        <Text>{label}</Text>
+      </Card>
+    )}
+  </EachParentType>
+)
+ParentTypes.parameters = parentTypesParams

package/stories/Checkbox/Checkbox.stories.jsx

@@ -0,0 +1,94 @@
+/* eslint-disable react/no-multi-comp */
+import React from 'react'
+
+import { Checkbox, CheckboxGroup, Typography } from '../../lib'
+import { Container, EachParentType, parentTypesParams } from '../supports'
+
+export default {
+  title: 'Base/Checkbox',
+  component: Checkbox,
+  argTypes: {
+    checked: {
+      control: { type: 'radio' },
+      options: [true, false, undefined]
+    }
+  },
+  args: {
+    label: 'Checkbox',
+    checked: undefined
+  }
+}
+
+const Template = (args) => (
+  <Container>
+    <Checkbox {...args} />
+  </Container>
+)
+
+export const Default = Template.bind({})
+Default.argTypes = {
+  checked: { table: { disable: true } }
+}
+
+export const Controlled = Template.bind({})
+Controlled.argTypes = {
+  defaultChecked: { table: { disable: true } }
+}
+Controlled.args = {
+  checked: false,
+  defaultChecked: undefined
+}
+
+export const Inactive = Template.bind({})
+Inactive.argTypes = {
+  inactive: { table: { disable: true } }
+}
+Inactive.args = {
+  inactive: true
+}
+
+export const WithFeedback = Template.bind({})
+WithFeedback.argTypes = {
+  feedback: { table: { disable: true } }
+}
+WithFeedback.args = {
+  feedback: 'Something happened'
+}
+
+export const CheckboxGroupStory = (args) => <CheckboxGroup {...args} />
+CheckboxGroupStory.storyName = 'CheckboxGroup'
+CheckboxGroupStory.args = {
+  items: [
+    {
+      label: 'Checkbox 1'
+    },
+    {
+      label: 'Checkbox 2'
+    },
+    {
+      label: 'Checkbox 3'
+    },
+    {
+      label: 'Checkbox 4'
+    }
+  ],
+  legend: 'Choose checkboxes.',
+  hint: 'Of the checkboxes below, choose some.',
+  tooltip: 'Decide which checkboxes you like best, then press them.',
+  name: 'example'
+}
+
+export const ParentTypes = (args) => (
+  <EachParentType componentThemeName="Checkbox" {...args}>
+    {({ label, variant }) => (
+      <Container key={label}>
+        <Typography>{`${label} `}</Typography>
+        <Checkbox {...args} variant={variant} />
+      </Container>
+    )}
+  </EachParentType>
+)
+ParentTypes.parameters = parentTypesParams
+ParentTypes.args = {
+  defaultChecked: undefined
+}

package/stories/Divider/Divider.stories.jsx

@@ -1,12 +1,17 @@
+/* eslint-disable react/no-multi-comp */
 import React from 'react'
 import { View, StyleSheet } from 'react-native'
 import { Divider, Typography } from '../../lib'
+import { EachParentType, parentTypesParams } from '../supports'
 
 export default {
   title: 'Base/Divider',
   component: Divider
 }
 
+export const Default = (args) => <Divider {...args} />
+Default.storyName = 'Divider'
+
 const Template = ({ vertical, ...rest }) => (
   <View style={vertical ? styles.row : styles.column}>
     <View style={vertical ? styles.contentRow : styles.contentColumn}>
@@ -24,8 +29,27 @@ const Template = ({ vertical, ...rest }) => (
 
 Template.propTypes = Divider.propTypes
 
-export const Story = Template.bind({})
-Story.storyName = 'Divider'
+export const Horizontal = Template.bind({})
+
+export const Vertical = Template.bind({})
+Vertical.args = { vertical: true }
+
+export const ParentTypes = (args) => (
+  <EachParentType componentThemeName="Divider" {...args}>
+    {({ label, variant, index }) =>
+      label.match(/Row/) ? (
+        <Typography>{index ? '' : 'Skipping Row examples; see Vertical story. '}</Typography>
+      ) : (
+        <>
+          <Typography>{`"${label}" is below this moderately lengthy text appearing before the Divider.`}</Typography>
+          <Divider {...args} variant={variant} />
+          <Typography>{`"${label}" is above.`}</Typography>
+        </>
+      )
+    }
+  </EachParentType>
+)
+ParentTypes.parameters = parentTypesParams
 
 const styles = StyleSheet.create({
   row: {