feat: Add merging array of variants

CHANGELOG.md

@@ -969,6 +969,7 @@ Theme UI is now written in TypeScript, and the emitted types differ from
 
 ### `@theme-ui/core`
 
+- Add ability to use arrays to merge variants. Issues #1209 #1208, PR #1226
 - Make ThemeProvider `theme` prop required
 
 ### `@theme-ui/editor`

packages/components/index.d.ts

@@ -2,7 +2,7 @@ import * as React from 'react'
 import { StyledComponent } from '@emotion/styled'
 import { Interpolation } from '@emotion/react'
 import { SpaceProps, ColorProps, MarginProps } from 'styled-system'
-import { ResponsiveStyleValue, ThemeUIStyleObject } from '@theme-ui/css'
+import { ResponsiveStyleValue, ThemeUIStyleObject, VariantProperty } from '@theme-ui/css'
 
 type Omit<T, K> = Pick<T, Exclude<keyof T, K>>
 
@@ -20,7 +20,7 @@ type ForwardRef<T, P> = React.ForwardRefExoticComponent<
 
 export interface BoxOwnProps extends SpaceProps, ColorProps {
   as?: React.ElementType
-  variant?: string
+  variant?: VariantProperty.Variant
   css?: Interpolation<any>
   sx?: ThemeUIStyleObject
 }

packages/components/src/Box.js

@@ -1,5 +1,6 @@
 import styled from '@emotion/styled'
-import { css, get } from '@theme-ui/css'
+import { css, getVariantValue } from '@theme-ui/css'
+import deepmerge from 'deepmerge'
 import { createShouldForwardProp } from '@styled-system/should-forward-prop'
 import space from '@styled-system/space'
 import color from '@styled-system/color'
@@ -17,7 +18,7 @@ const shouldForwardProp = createShouldForwardProp(boxSystemProps)
 const sx = (props) => css(props.sx)(props.theme)
 const base = (props) => css(props.__css)(props.theme)
 const variant = ({ theme, variant, __themeKey = 'variants' }) =>
-  css(get(theme, __themeKey + '.' + variant, get(theme, variant)))
+  css(getVariantValue(theme, variant, __themeKey))
 
 export const Box = styled('div', {
   shouldForwardProp,

packages/components/test/__snapshots__/index.js.snap

@@ -180,6 +180,43 @@ exports[`Box renders 1`] = `
 </div>
 `;
 
+exports[`Box renders with variant array derived variant from theme merge 1`] = `
+.emotion-0 {
+  box-sizing: border-box;
+  margin: 0;
+  min-width: 0;
+  -webkit-appearance: none;
+  -moz-appearance: none;
+  -ms-appearance: none;
+  appearance: none;
+  display: inline-block;
+  text-align: center;
+  line-height: inherit;
+  -webkit-text-decoration: none;
+  text-decoration: none;
+  font-size: inherit;
+  padding-left: 16px;
+  padding-right: 16px;
+  padding-top: 8px;
+  padding-bottom: 8px;
+  color: white;
+  background-color: var(--theme-ui-colors-primary, #0cf);
+  border: 0;
+  border-radius: 4px;
+  color: var(--theme-ui-colors-background, #fefefe);
+  border: 2px solid undefined;
+  background-color: transparent;
+  border-bottom-left-radius: 5px 85px;
+  border-bottom-right-radius: 75px 5px;
+  border-top-left-radius: 85px 5px;
+  border-top-right-radius: 5px 75px;
+}
+
+<button
+  className="emotion-0"
+/>
+`;
+
 exports[`Button hidden 1`] = `
 .emotion-0 {
   box-sizing: border-box;

packages/components/test/index.js

@@ -52,6 +52,10 @@ const theme = {
       p: 4,
       bg: 'highlight',
     },
+    bop: {
+      m: 1,
+      bg: 'muted',
+    },
   },
   cards: {
     primary: {
@@ -146,6 +150,131 @@ describe('Box', () => {
     expect(json).toHaveStyleRule('background-color', 'highlight')
     expect(json).toHaveStyleRule('padding', '32px')
   })
+  it('renders with variant prop as a function', () => {
+    const json = renderJSON(
+      <ThemeProvider theme={theme}>
+        <Box variant={(theme) => `boxes.${Object.keys(theme.boxes)[0]}`} />
+      </ThemeProvider>
+    )
+    expect(json).toHaveStyleRule('background-color', 'highlight')
+    expect(json).toHaveStyleRule('padding', '32px')
+  })
+  test('renders with variant array', () => {
+    const json = renderJSON(
+      <ThemeProvider theme={theme}>
+        <Box variant={['boxes.beep', 'boxes.bop']} />
+      </ThemeProvider>
+    )
+    expect(json).toHaveStyleRule('background-color', 'muted')
+    expect(json).toHaveStyleRule('padding', '32px')
+    expect(json).toHaveStyleRule('margin', '4px')
+  })
+
+  test('renders with variant array function merge', () => {
+    const json = renderJSON(
+      <ThemeProvider
+        theme={{
+          colors: {
+            shadow: '#333333',
+          },
+          boxes: {
+            beep: {
+              border: (t) => `1px solid ${t.colors.shadow}`,
+            },
+            bop: {
+              border: (t) => `2px solid ${t.colors.shadow}`,
+            },
+          },
+        }}>
+        <Box variant={['boxes.beep', 'boxes.bop']} />
+      </ThemeProvider>
+    )
+    expect(json).toHaveStyleRule(
+      'border',
+      '2px solid var(--theme-ui-colors-shadow, #333333)'
+    )
+  })
+
+  test('renders with variant array derived variant from theme merge', () => {
+    jest.spyOn(global.Math, 'random').mockReturnValue(0.4)
+
+    const lighten = (color, amount) => {
+      if (color === '#0cf' && amount === 0.25) {
+        return '#80e5ff'
+      }
+    }
+
+    const sketchyBorders = [
+      {
+        borderBottomLeftRadius: '5px 85px',
+        borderBottomRightRadius: '75px 5px',
+        borderTopLeftRadius: '85px 5px',
+        borderTopRightRadius: '5px 75px',
+      },
+      {
+        borderBottomLeftRadius: '61px 8px',
+        borderBottomRightRadius: '6px 68px',
+        borderTopLeftRadius: '41px 8px',
+        borderTopRightRadius: '3px 68px',
+      },
+      {
+        borderBottomLeftRadius: '75px 5px',
+        borderBottomRightRadius: '5px 85px',
+        borderTopLeftRadius: '5px 75px',
+        borderTopRightRadius: '85px 5px',
+      },
+    ]
+    const randomNumber = () => 0.321
+    const borderIndex = Math.floor(randomNumber() * sketchyBorders.length)
+    const json = renderJSON(
+      <ThemeProvider
+        theme={{
+          colors: {
+            primary: '#0cf',
+            text: '#000',
+            background: '#fefefe',
+          },
+          buttons: {
+            primary: (t) => {
+              const backgroundColor = lighten(t?.colors?.primary, 0.25)
+
+              return {
+                color: 'background',
+                border: `2px solid ${backgroundColor}`,
+                backgroundColor,
+              }
+            },
+            ghost: {
+              backgroundColor: 'transparent',
+            },
+            sketchy: (t) => {
+              return sketchyBorders[borderIndex]
+            },
+          },
+        }}>
+        <Button variant={['primary', 'ghost', 'sketchy']} />
+      </ThemeProvider>
+    )
+
+    expect(json).toMatchSnapshot()
+
+    expect(json).toHaveStyleRule(
+      'border-bottom-left-radius',
+      sketchyBorders[borderIndex].borderBottomLeftRadius
+    )
+    expect(json).toHaveStyleRule(
+      'border-bottom-right-radius',
+      sketchyBorders[borderIndex].borderBottomRightRadius
+    )
+
+    expect(json).toHaveStyleRule(
+      'color',
+      'var(--theme-ui-colors-background, #fefefe)'
+    )
+    expect(json).toHaveStyleRule('background-color', 'transparent')
+
+    jest.spyOn(global.Math, 'random').mockRestore()
+  })
 
   test('renders with base styles', () => {
     const json = renderJSON(

packages/css/package.json

@@ -14,7 +14,8 @@
   },
   "dependencies": {
     "@emotion/react": "^11.4.1",
-    "csstype": "^3.0.9"
+    "csstype": "^3.0.9",
+    "deepmerge": "^4.2.2"
   },
   "preconstruct": {
     "entrypoints": [

packages/css/src/index.ts

@@ -1,9 +1,11 @@
+import deepmerge from 'deepmerge'
 import type {
   CSSObject,
   ThemeUIStyleObject,
   ThemeDerivedStyles,
   Theme,
   ThemeUICSSObject,
+  VariantProperty,
 } from './types'
 
 export * from './types'
@@ -53,14 +55,41 @@ export function get(
   return hasDefault(obj) ? obj[THEME_UI_DEFAULT_KEY] : obj
 }
 
+export const getValue = (
+  theme: Theme,
+  key: string,
+  _themeKey?: string
+): ThemeUICSSObject => {
+  const defValue = _themeKey ? get(theme, key) : undefined
+  const value = get(
+    theme,
+    _themeKey ? `${_themeKey}.${key}` : key,
+    typeof defValue === 'function' ? defValue(theme) : defValue
+  )
+  return typeof value === 'function' ? value(theme) : value
+}
+export const getVariantValue = (
+  theme: Theme,
+  variant: VariantProperty.Variant,
+  _themeKey?: string
+): ThemeUICSSObject => {
+  const key = typeof variant === 'function' ? variant(theme) : variant
+  if (Array.isArray(key)) {
+    return deepmerge.all(
+      key.map((v) => getValue(theme, v, _themeKey) || {}),
+      { arrayMerge: (_dest, src) => src }
+    ) as ThemeUICSSObject
+  }
+  return getValue(theme, key, _themeKey)
+}
+
 export const getObjectWithVariants = (obj: any, theme: Theme): CSSObject => {
   if (obj && obj['variant']) {
     let result: CSSObject = {}
     for (const key in obj) {
       const x = obj[key]
       if (key === 'variant') {
-        const val = typeof x === 'function' ? x(theme) : x
-        const variant = getObjectWithVariants(get(theme, val as string), theme)
+        const variant = getObjectWithVariants(getVariantValue(theme, x), theme)
         result = { ...result, ...variant }
       } else {
         result[key] = x as CSSObject

packages/css/src/types.ts

@@ -446,6 +446,10 @@ export type ThemeUICSSProperties = {
   >
 }
 
+export declare namespace VariantProperty {
+  export type Variant = string | string[] | ((theme: Theme) => string)
+}
+
 export interface VariantProperty {
   /**
    * **`Variants`** can be useful for applying complex styles to a component based on a single prop.
@@ -468,7 +472,7 @@ export interface VariantProperty {
    *
    * @see https://styled-system.com/variants
    */
-  variant?: string
+  variant?: VariantProperty.Variant
 }
 
 export interface ThemeDerivedStyles {

packages/css/test/index.ts

@@ -384,7 +384,34 @@ test('handles responsive variants', () => {
     },
   })
 })
+test('merge array of variant', () => {
+  const result = css({
+    variant: ['buttons.primary', 'buttons.round'],
+  })(theme)
+  expect(result).toEqual({
+    padding: 16,
+    fontWeight: 600,
+    color: 'white',
+    width: '100%',
+    height: '100%',
+    overflow: 'hidden',
+    borderRadius: '50%',
+    backgroundColor: 'tomato',
+  })
+})
 
+it('invoke variants as a function', () => {
+  const result = css({
+    variant: (theme: Theme) => `buttons.${Object.keys(theme.buttons!)[3]}`,
+  })(theme)
+  expect(result).toEqual({
+    width: '100%',
+    height: '100%',
+    overflow: 'hidden',
+    borderRadius: '50%',
+    backgroundColor: 'tomato',
+  })
+})
 test('handles negative margins from scale', () => {
   const result = css({
     mt: -3,

packages/docs/src/pages/components/variants.mdx

@@ -62,7 +62,30 @@ For example, a secondary button style can be added to `theme.buttons.secondary`
 <Button variant="secondary">Secondary</Button>
 ```
 
-## Example Theme
+## Combining multiple variants
+
+If you want to combine multiple variants on the same element, pass an array of variants with the `variant` prop.
+Variant styles are merged from left to right, so if some of the styles conflict, those of the variant passed later will render.
+
+```jsx live=true
+<Text variant={['caps', 'heading']}>Title text</Text>
+```
+
+## Variant as a function
+
+If you need to determine variants at run-time, pass a function to the `variant` prop.
+
+```jsx live=true
+<Box
+  variant={(theme) => {
+    const buttonVariant = Object.keys(theme.buttons)[0]
+    return `buttons.${buttonVariant}`
+  }}>
+  some text
+</Box>
+```
+
+## Example theme
 
 ```js
 // example theme