@opentrons/components 0.1.6-alpha.16 → 0.1.6-alpha.18

package/src/primitives/README.md

@@ -0,0 +1,188 @@
+Primitive components are base-level components that apply very little inherent styling (usually CSS resets) and expose simple props to customize styling or behavior at a low level.
+
+## style props
+
+Style props will pass their value directly into CSS, but for safety, try to use the value constants defined in `components/src/styles`.
+
+### color
+
+| prop name         | css property       |
+| ----------------- | ------------------ |
+| `color`           | `color`            |
+| `backgroundColor` | `background-color` |
+| `opacity`         | `opacity`          |
+
+```js static
+import { Box, C_DARK_GRAY, C_WHITE } from '@opentrons/components'
+
+const GrayBox = () => <Box color={C_WHITE} backgroundColor={C_DARK_GRAY} />
+```
+
+### typography
+
+| prop name       | css property     |
+| --------------- | ---------------- |
+| `fontSize`      | `font-size`      |
+| `fontWeight`    | `font-weight`    |
+| `fontStyle`     | `font-style`     |
+| `lineHeight`    | `line-height`    |
+| `textAlign`     | `text-align`     |
+| `textTransform` | `text-transform` |
+
+```js static
+import {
+  Text,
+  FONT_SIZE_HEADER,
+  FONT_WEIGHT_SEMIBOLD,
+  LINE_HEIGHT_TITLE,
+} from '@opentrons/components'
+
+const Heading = () => (
+  <Text
+    fontSize={FONT_SIZE_HEADER}
+    fontWeight={FONT_WEIGHT_SEMIBOLD}
+    lineHeight={LINE_HEIGHT_TITLE}
+  />
+)
+```
+
+### spacing
+
+| prop name       | css property                       |
+| --------------- | ---------------------------------- |
+| `margin`        | `margin`                           |
+| `marginX`       | `margin-left` and `margin-right`   |
+| `marginY`       | `margin-top` and `margin-bottom`   |
+| `marginTop`     | `margin-top`                       |
+| `marginRight`   | `margin-right`                     |
+| `marginBottom`  | `margin-bottom`                    |
+| `marginLeft`    | `margin-left`                      |
+| `padding`       | `padding`                          |
+| `paddingX`      | `padding-left` and `padding-right` |
+| `paddingY`      | `padding-top` and `padding-bottom` |
+| `paddingTop`    | `padding-top`                      |
+| `paddingRight`  | `padding-right`                    |
+| `paddingBottom` | `padding-bottom`                   |
+| `paddingLeft`   | `padding-left`                     |
+
+```js static
+import { Box, SPACING_AUTO, SPACING_3 } from '@opentrons/components'
+
+const Heading = () => <Box marginX={SPACING_AUTO} paddingY={SPACING_3} />
+```
+
+Note: If you specify both of a shorthand prop and the explicit prop (e.g. `marginX` and `marginLeft`), the more explicit prop will be preferred.
+
+### borders
+
+| prop name      | css property    |
+| -------------- | --------------- |
+| `border`       | `border`        |
+| `borderTop`    | `border-top`    |
+| `borderRight`  | `border-right`  |
+| `borderBottom` | `border-bottom` |
+| `borderLeft`   | `border-left`   |
+| `borderRadius` | `border-radius` |
+| `borderWidth`  | `border-width`  |
+| `borderColor`  | `border-color`  |
+
+```js static
+import {
+  Box,
+  BORDER_SOLID_LIGHT,
+  BORDER_RADIUS_DEFAULT,
+} from '@opentrons/components'
+
+const Heading = () => (
+  <Box border={BORDER_SOLID_LIGHT} borderRadius={BORDER_RADIUS_DEFAULT} />
+)
+```
+
+### flexbox
+
+| prop name        | css property      |
+| ---------------- | ----------------- |
+| `flex`           | `flex`            |
+| `alignItems`     | `align-items`     |
+| `justifyContent` | `justify-content` |
+| `flexDirection`  | `flex-direction`  |
+| `flexWrap`       | `flex-wrap`       |
+
+```js static
+import {
+  Flex,
+  ALIGN_ITEMS_CENTER,
+  JUSTIFY_CONTENT_CENTER,
+} from '@opentrons/components'
+
+const Heading = () => (
+  <Flex
+    alignItems={ALIGN_ITEMS_CENTER}
+    justifyContent={JUSTIFY_CONTENT_CENTER}
+  />
+)
+```
+
+### layout
+
+| prop name   | css property         |
+| ----------- | -------------------- |
+| `display`   | `display`            |
+| `size`      | `width` and `height` |
+| `width`     | `width`              |
+| `minWidth`  | `min-width`          |
+| `maxWidth`  | `max-width`          |
+| `height`    | `height`             |
+| `minHeight` | `min-height`         |
+| `maxHeight` | `max-height`         |
+| `overflow`  | `overflow`           |
+| `overflowX` | `overflow-x`         |
+| `overflowY` | `overflow-y`         |
+
+```js static
+import { Box, SIZE_4, OVERFLOW_HIDDEN } from '@opentrons/components'
+
+const Heading = () => <Box size={SIZE_4} overflow={OVERFLOW_HIDDEN} />
+```
+
+### position
+
+| prop name  | css property |
+| ---------- | ------------ |
+| `position` | `position`   |
+| `zIndex`   | `z-index`    |
+| `top`      | `top`        |
+| `right`    | `right`      |
+| `bottom`   | `bottom`     |
+| `left`     | `left`       |
+
+```js static
+import { Box, POSITION_ABSOLUTE } from '@opentrons/components'
+
+const Fill = () => (
+  <Box position={POSITION_ABSOLUTE} top={0} right={0} bottom={0} left={0} />
+)
+```
+
+## creating custom primitives
+
+If you find yourself in a place where...
+
+- You need a primitive that doesn't yet exist, and
+- It doesn't make sense to add that primitive to the library
+
+...you can create your own primitive with the style props above using `styleProps` (to apply the styles based on props) and `isntStyleProp` (to ensure style props don't get passed down to the DOM):
+
+```js static
+import styled from 'styled-components'
+import { styleProps, isntStyleProp, C_DARK_GRAY } from '@opentrons/components'
+
+import type { PrimitiveComponent } from '@opentrons/components'
+
+export const Gray: PrimitiveComponent<'div'> = styled.div.withConfig({
+  shouldForwardProp: isntStyleProp,
+})`
+  color: ${C_DARK_GRAY};
+  ${styleProps}
+`
+```

package/src/primitives/Svg.stories.tsx

@@ -0,0 +1,36 @@
+import type * as React from 'react'
+import { Svg as SvgComponent } from './Svg'
+
+import type { Story, Meta } from '@storybook/react'
+
+export default {
+  title: 'Library/Atoms/Svg',
+} as Meta
+
+const Template: Story<React.ComponentProps<typeof SvgComponent>> = args => (
+  <SvgComponent {...args} />
+)
+export const Svg = Template.bind({})
+Svg.args = {
+  svgWidth: '300',
+  svgHeight: '300',
+  children: [
+    <rect
+      key="rect"
+      height="40"
+      width="40"
+      x="50"
+      y="50"
+      fill="red"
+      stroke="rebeccapurple"
+    />,
+    <circle
+      key="circle"
+      cx="140"
+      cy="140"
+      r="40"
+      fill="green"
+      stroke="black"
+    />,
+  ],
+}

package/src/primitives/Svg.tsx

@@ -0,0 +1,68 @@
+import styled from 'styled-components'
+
+import { styleProps, isntStyleProp } from './style-props'
+
+import type { StyleProps, PrimitiveComponent } from './types'
+
+export interface SvgProps extends StyleProps {
+  /** attach a width attribute to the <svg> element */
+  svgWidth?: string | number
+  /** attach a height attribute to the <svg> element */
+  svgHeight?: string | number
+  /**
+   * internal helper prop to remap width style-prop to CSS
+   * @internal
+   */
+  _cssWidth?: string | number
+  /**
+   * internal helper prop to remap height style-prop to CSS
+   * @internal
+   */
+  _cssHeight?: string | number
+}
+
+const SVG_VERSION = '1.1'
+const SVG_NAMESPACE = 'http://www.w3.org/2000/svg'
+
+const SVG_PROPS = ['svgWidth', 'svgHeight', '_cssWidth', '_cssHeight']
+
+/**
+ * SVG primitive
+ *
+ * @component
+ */
+export const Svg: PrimitiveComponent<'svg', SvgProps> = styled.svg
+  .withConfig({
+    shouldForwardProp: p => {
+      return (
+        // do not forward style-props or Svg-props to the underlying <svg>
+        (isntStyleProp(p) && !SVG_PROPS.includes(p)) ||
+        // unlike other primitives, allow width and height to be forwarded
+        p === 'width' ||
+        p === 'height'
+      )
+    },
+  })
+  .attrs(
+    (props: SvgProps): React.ComponentProps<PrimitiveComponent<'svg'>> => ({
+      version: SVG_VERSION,
+      xmlns: SVG_NAMESPACE,
+      // map the explicit svgWidth/Height props to width/height attrs
+      width: props.svgWidth,
+      height: props.svgHeight,
+      // map width and height style props to internal style props
+      _cssWidth: props.width,
+      _cssHeight: props.height,
+    })
+  )`
+  ${(props: Partial<SvgProps>) => {
+    const { width, height, ...otherProps } = props
+
+    // replace width and height attrs with internal style props
+    return styleProps({
+      ...otherProps,
+      width: otherProps._cssWidth,
+      height: otherProps._cssHeight,
+    })
+  }}
+`

package/src/primitives/Text.stories.tsx

@@ -0,0 +1,17 @@
+import type * as React from 'react'
+import { Text as TextComponent } from './Text'
+
+import type { Story, Meta } from '@storybook/react'
+
+export default {
+  title: 'Library/Atoms/Text',
+} as Meta
+
+const Template: Story<React.ComponentProps<typeof TextComponent>> = args => (
+  <TextComponent {...args} />
+)
+export const Text = Template.bind({})
+Text.args = {
+  children: 'This is a bunch text of text',
+  color: 'grey',
+}

package/src/primitives/Text.tsx

@@ -0,0 +1,18 @@
+import styled from 'styled-components'
+
+import { styleProps, isntStyleProp } from './style-props'
+
+import type { PrimitiveComponent } from './types'
+
+/**
+ * Text primitive
+ *
+ * @component
+ */
+export const Text: PrimitiveComponent<'p'> = styled.p.withConfig({
+  shouldForwardProp: isntStyleProp,
+})`
+  margin-top: 0;
+  margin-bottom: 0;
+  ${styleProps}
+`

package/src/primitives/__tests__/Box.test.tsx

@@ -0,0 +1,4 @@
+import { describe, it } from 'vitest'
+describe('Box primitive component', () => {
+  it.todo('replace deprecated enzyme test')
+})

package/src/primitives/__tests__/Btn.test.tsx

@@ -0,0 +1,4 @@
+import { describe, it } from 'vitest'
+describe('Btn primitive component', () => {
+  it.todo('replace deprecated enzyme test')
+})

package/src/primitives/__tests__/Flex.test.tsx

@@ -0,0 +1,4 @@
+import { describe, it } from 'vitest'
+describe('Flex primitive component', () => {
+  it.todo('replace deprecated enzyme test')
+})

package/src/primitives/__tests__/Link.test.tsx

@@ -0,0 +1,4 @@
+import { describe, it } from 'vitest'
+describe('Link primitive component', () => {
+  it.todo('replace deprecated enzyme test')
+})

package/src/primitives/__tests__/Svg.test.tsx

@@ -0,0 +1,4 @@
+import { describe, it } from 'vitest'
+describe('Svg primitive component', () => {
+  it.todo('replace deprecated enzyme test')
+})

package/src/primitives/__tests__/Text.test.tsx

@@ -0,0 +1,4 @@
+import { describe, it } from 'vitest'
+describe('Text primitive component', () => {
+  it.todo('replace deprecated enzyme test')
+})

package/src/primitives/__tests__/primitives.test.tsx

@@ -0,0 +1,4 @@
+import { describe, it } from 'vitest'
+describe('primitive components with style props', () => {
+  it.todo('replace deprecated enzyme test')
+})

package/src/primitives/__tests__/style-props.test.tsx

@@ -0,0 +1,4 @@
+import { describe, it } from 'vitest'
+describe('style props', () => {
+  it.todo('replace deprecated enzyme test')
+})

package/src/primitives/index.ts

@@ -0,0 +1,10 @@
+export * from './style-props'
+export * from './Box'
+export * from './Btn'
+export * from './Flex'
+export * from './ForeignObject'
+export * from './Link'
+export * from './Svg'
+export * from './Text'
+
+export * from './types'

package/src/primitives/style-props.ts

@@ -0,0 +1,197 @@
+// common styling props you can apply to any primitive component
+// props are string type for flexibility, but try to use constants for safety
+
+import pick from 'lodash/pick'
+
+import type * as Types from './types'
+
+import type { CSSObject } from 'styled-components'
+
+const COLOR_PROPS = ['color', 'backgroundColor', 'opacity'] as const
+
+const TYPOGRAPHY_PROPS = [
+  'fontSize',
+  'fontWeight',
+  'fontStyle',
+  'lineHeight',
+  'textAlign',
+  'textTransform',
+  'textDecoration',
+  'textOverflow',
+] as const
+
+const SPACING_PROPS = [
+  'margin',
+  'marginX',
+  'marginY',
+  'marginTop',
+  'marginRight',
+  'marginBottom',
+  'marginLeft',
+  'padding',
+  'paddingX',
+  'paddingY',
+  'paddingTop',
+  'paddingRight',
+  'paddingBottom',
+  'paddingLeft',
+] as const
+
+const BORDER_PROPS = [
+  'border',
+  'borderTop',
+  'borderRight',
+  'borderBottom',
+  'borderLeft',
+  'borderRadius',
+  'borderWidth',
+  'borderColor',
+  'boxShadow',
+] as const
+
+const FLEXBOX_PROPS = [
+  'flex',
+  'alignItems',
+  'justifyContent',
+  'flexDirection',
+  'flexGrow',
+  'flexWrap',
+  'alignSelf',
+  'whiteSpace',
+  'gap',
+] as const
+
+const GRID_PROPS = [
+  'columnGap',
+  'gridGap',
+  'gridTemplateAreas',
+  'gridTemplateRows',
+  'gridTemplateColumns',
+  'gridArea',
+  'gridRow',
+  'gridColumn',
+] as const
+
+const LAYOUT_PROPS = [
+  'display',
+  'size',
+  'width',
+  'minWidth',
+  'maxWidth',
+  'height',
+  'minHeight',
+  'maxHeight',
+  'overflow',
+  'overflowX',
+  'overflowY',
+  'whiteSpace',
+  'wordSpacing',
+  'cursor',
+  'overflowWrap',
+] as const
+
+const POSITION_PROPS = [
+  'position',
+  'zIndex',
+  'top',
+  'right',
+  'bottom',
+  'left',
+  'transform',
+  'transformOrigin',
+  'filter',
+] as const
+
+const TRANSITION_PROPS = ['transition'] as const
+
+const STYLE_PROPS = [
+  ...COLOR_PROPS,
+  ...TYPOGRAPHY_PROPS,
+  ...SPACING_PROPS,
+  ...BORDER_PROPS,
+  ...FLEXBOX_PROPS,
+  ...GRID_PROPS,
+  ...LAYOUT_PROPS,
+  ...POSITION_PROPS,
+  ...TRANSITION_PROPS,
+]
+
+const colorStyles = (props: Types.StyleProps): CSSObject => {
+  return pick(props, COLOR_PROPS) as CSSObject
+}
+
+const typographyStyles = (props: Types.StyleProps): CSSObject => {
+  return pick(props, TYPOGRAPHY_PROPS) as CSSObject
+}
+
+const spacingStyles = (props: Types.StyleProps): CSSObject => {
+  const { marginX, marginY, paddingX, paddingY, ...styles } = pick(
+    props,
+    SPACING_PROPS
+  )
+
+  if (marginX != null) {
+    styles.marginRight = styles.marginRight ?? marginX
+    styles.marginLeft = styles.marginLeft ?? marginX
+  }
+  if (marginY != null) {
+    styles.marginTop = styles.marginTop ?? marginY
+    styles.marginBottom = styles.marginBottom ?? marginY
+  }
+  if (paddingX != null) {
+    styles.paddingRight = styles.paddingRight ?? paddingX
+    styles.paddingLeft = styles.paddingLeft ?? paddingX
+  }
+  if (paddingY != null) {
+    styles.paddingTop = styles.paddingTop ?? paddingY
+    styles.paddingBottom = styles.paddingBottom ?? paddingY
+  }
+
+  return styles as CSSObject
+}
+
+const borderStyles = (props: Types.StyleProps): CSSObject => {
+  return pick(props, BORDER_PROPS) as CSSObject
+}
+
+const flexboxStyles = (props: Types.StyleProps): CSSObject => {
+  return pick(props, FLEXBOX_PROPS) as CSSObject
+}
+
+const gridStyles = (props: Types.StyleProps): CSSObject => {
+  return pick(props, GRID_PROPS) as CSSObject
+}
+
+const layoutStyles = (props: Types.StyleProps): CSSObject => {
+  const { size, ...styles } = pick(props, LAYOUT_PROPS) as CSSObject
+
+  if (size != null) {
+    styles.width = styles.width ?? ((size as unknown) as typeof styles.width)
+    styles.height = styles.height ?? ((size as unknown) as typeof styles.height)
+  }
+
+  return styles
+}
+
+const positionStyles = (props: Types.StyleProps): CSSObject => {
+  return pick(props, POSITION_PROPS) as CSSObject
+}
+
+const transitionStyles = (props: Types.StyleProps): CSSObject => {
+  return pick(props, TRANSITION_PROPS)
+}
+
+export const styleProps = (props: Types.StyleProps): CSSObject => ({
+  ...colorStyles(props),
+  ...typographyStyles(props),
+  ...spacingStyles(props),
+  ...borderStyles(props),
+  ...flexboxStyles(props),
+  ...gridStyles(props),
+  ...layoutStyles(props),
+  ...positionStyles(props),
+  ...transitionStyles(props),
+})
+
+export const isntStyleProp = (prop: string | React.ReactText): boolean =>
+  !STYLE_PROPS.includes(prop as typeof STYLE_PROPS[number])