feat(ui-avatar,emotion): add theming solution to functional components

Author: HerrTopi

docs/contributor-docs/themed-components.md

@@ -0,0 +1,89 @@
+---
+title: Themed components
+category: Contributor Guides
+order: 10
+---
+
+## Making InstUI-like components with theming
+
+InstUI uses [Emotion](https://emotion.sh/docs/introduction) under the hood to theme and style its components.
+If you want to read about the design behind the system and how to build `class-based` components with InstUI, please read [this](https://instructure.design/#emotion).
+
+This page will show you how to build `functional` react components with InstUI.
+
+### Anatomy of a functional InstUI component
+
+To make similar and similarly maintainable components to InstUI, you should follow a basic structure. This is not strictly necessary but recommended and this guide will assume you do use it.
+
+A fully equipped InstUI component has three files: `index.tsx`, `style.ts`, `theme.ts` and uses the `useStyles` hook.
+
+Let's take a look at the simplest example possible:
+
+```html
+---
+type: code
+---
+
+// index.tsx // /** @jsx jsx */ import { jsx, useStyle } from
+'@instructure/emotion' import generateStyle from './styles' import
+generateComponentTheme from './theme' const InstUIComponent = (props: PropsType)
+=> { const styles = useStyle({ generateStyle, generateComponentTheme,
+componentId: "InstUIComponent_id", //any unique id params: { color: props.color,
+variant: props.variant, themeOverride: props.themeOverride } }) return (
+<div css="{" styles?.root }>content</div>
+) } export default InstUIComponent
+```
+
+```html
+---
+type: code
+---
+
+// style.ts const generateStyle = ( componentTheme: componentThemeType, params:
+ParamType): AvatarStyle => { const { color, variant } = params // assuming you
+passed the `color` and `variant` to the useStyle hook const variantStyles = {
+circle: { width: '2.5em', position: 'relative', borderRadius: '100%', overflow:
+'hidden' }, rectangle: { width: '3em' } } const colorVariants = { default:
+componentTheme.defaultColor, green: componentTheme.niceGreenColor,
+nonThemedColor: "pink" } return { instUIComponent: { //for the root element's
+style label: 'instUIComponent', color: colorVariants[color], backgroundColor:
+componentTheme.bgColor, ...variantStyles[variant], }, aChildElement: { label:
+'instUIComponent_aChildElement', // this label is needed. Please prefix it with
+the root label fontWeight: "400" //you can hardcode values. Don't need to get
+them from the theme necessarily . } } } export default generateStyle
+```
+
+```html
+---
+type: code
+---
+
+// theme.ts import type { Theme } from '@instructure/ui-themes' const
+generateComponentTheme = (theme: Theme) => { const { colors } = theme // the
+theme you are using. See instUI's theme docs as well const componentVariables =
+{ defaultColor: colors?.contrasts?.white1010, niceGreenColor:
+colors.contrasts.green4570, bgColor: "purple" //this is hardcoded, but added to
+the theme, so it can be overridden } return { ...componentVariables } } export
+default generateComponentTheme
+```
+
+Let's take a look at the key parts of the examples:
+
+The `useStyle` hook calculates the styles for the component. It needs an object with:
+
+- `generateStyle` function, this function contains all the `css` information (`style.ts` file in the example).
+- `generateComponentTheme` is an optional param. This provides variables that act as the theme of the components. These can be derived from the global theme object or hardcoded. All can be overridden.
+- `componentId` depends on `generateComponentTheme`. It's mandatory if `generateComponentTheme` is provided. It must be a unique string to identify the component by and used for [component level overrides](https://instructure.design/#using-theme-overrides/#Overriding%20theme%20for%20a%20specific%20component%20in%20a%20subtree).
+- `params` is an optional object with any data you need to pass to `generateStyle`. To enable themeOverrides on the component, you must pass the `themeOverride` prop to `params`.
+
+`useStyle` returns an object with the css classes. Pass it to the DOM through emotion's `css` prop (see example).
+
+#### The `generateComponentTheme`
+
+The `generateComponentTheme` defines, calculates and exposes variables that are considered `component theme variables`. These variables will be used in the `generateStyle` method to "theme" the component's style. These variables are overwritable by the [various override methods](https://instructure.design/#using-theme-overrides).
+`generateComponentTheme` gets the `theme` as parameter. Return an object (`componentVariables`) with keys that will act as the `component theme variables`. This method will be injected to `generateStyle`.
+
+#### The `generateStyle`
+
+You define the css in the `generateStyle` method. It has access to the themes, defined in the `generateComponentTheme` (in the example: `componentTheme`) and the `params` which are passed to the `useStyle` hook.
+Note: if you set the `label` to a unique value for every css class, it makes testing and debugging much easier because emotion appends to the end of the hashed class name it generates.

packages/emotion/src/EmotionTypes.ts

@@ -116,6 +116,11 @@ type GenerateStyle = (
   state?: State
 ) => StyleObject
 
+type GenerateStyleFunctional = (
+  componentTheme: ComponentTheme,
+  params: Record<string, unknown>
+) => StyleObject
+
 type ComponentStyle<Keys extends string = string> = Record<
   Keys,
   StyleObject | string | number | undefined
@@ -139,6 +144,7 @@ export type {
   State,
   GenerateComponentTheme,
   GenerateStyle,
+  GenerateStyleFunctional,
   ComponentStyle
 }
 /*

packages/emotion/src/__tests__/useStyle.test.tsx

@@ -0,0 +1,273 @@
+/*
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 - present Instructure, Inc.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+/** @jsx jsx */
+import { useState } from 'react'
+
+import { expect, mount, stub, within } from '@instructure/ui-test-utils'
+import { jsx, InstUISettingsProvider, WithStyleProps, useStyle } from '../index'
+
+type Props = {
+  inverse?: boolean
+} & WithStyleProps<ComponentTheme>
+
+type Theme = {
+  key: string
+  colors: {
+    contrasts: {
+      grey1111: string
+      green4570: string
+      blue4570: string
+    }
+  }
+}
+
+type ComponentTheme = {
+  textColor: string
+  textColorInverse: string
+  backgroundColor: string
+}
+
+describe('useStyle', async () => {
+  const grey1111 = 'rgb(0, 128, 0)'
+  const green4570 = 'rgb(10, 10, 10)'
+  const blue4570 = 'rgb(255, 255, 0)'
+  const exampleTheme: Theme = {
+    key: 'exampleTheme',
+    colors: {
+      contrasts: {
+        grey1111,
+        green4570,
+        blue4570
+      }
+    }
+  }
+
+  const generateComponentTheme = function (theme: Theme): ComponentTheme {
+    const { colors } = theme
+    return {
+      textColor: colors.contrasts.grey1111,
+      textColorInverse: colors.contrasts.green4570,
+      backgroundColor: colors.contrasts.blue4570
+    }
+  }
+
+  type StyleParams = {
+    inverse: boolean
+    clearBackground: boolean
+    themeOverride: Props['themeOverride']
+  }
+
+  const generateStyle = function (
+    componentTheme: ComponentTheme,
+    params: StyleParams
+  ) {
+    const { inverse, clearBackground } = params
+
+    return {
+      exampleComponent: {
+        label: 'exampleComponent',
+        color: componentTheme.textColor,
+        background: componentTheme.backgroundColor,
+        insetInlineStart: '8px',
+        ...(inverse && { color: componentTheme.textColorInverse }),
+        ...(clearBackground && { background: 'transparent' })
+      }
+    }
+  }
+
+  const ThemedComponent = ({ inverse = false, themeOverride }: Props) => {
+    const [clearBackground, setClearBackground] = useState(false)
+
+    const styles = useStyle({
+      generateStyle,
+      generateComponentTheme,
+      componentId: 'ThemedComponent',
+      params: { inverse, clearBackground, themeOverride }
+    })
+
+    const handleClick = () => {
+      setClearBackground(true)
+    }
+
+    return (
+      <div css={styles!.exampleComponent}>
+        <p>Hello World</p>
+        <button onClick={handleClick}>Button</button>
+      </div>
+    )
+  }
+
+  describe('with theme provided by InstUISettingsProvider', async () => {
+    it('should add css class suffixed with label', async () => {
+      const subject = await mount(
+        <InstUISettingsProvider theme={exampleTheme}>
+          <ThemedComponent />
+        </InstUISettingsProvider>
+      )
+      const emotionClassRegex = new RegExp(/^css-.+-exampleComponent$/)
+
+      expect(subject.getDOMNode().classList[0]).to.match(emotionClassRegex)
+    })
+
+    it('should apply correct css props', async () => {
+      const subject = await mount(
+        <InstUISettingsProvider theme={exampleTheme}>
+          <ThemedComponent />
+        </InstUISettingsProvider>
+      )
+      const component = subject.getDOMNode()
+      const computedStyle = getComputedStyle(component)
+
+      expect(computedStyle.color).to.equal('rgb(0, 128, 0)')
+      expect(computedStyle.backgroundColor).to.equal('rgb(255, 255, 0)')
+    })
+
+    describe('should allow configuration through the themeOverride prop', async () => {
+      it('when it is an object', async () => {
+        const subject = await mount(
+          <InstUISettingsProvider theme={exampleTheme}>
+            <ThemedComponent
+              themeOverride={{
+                textColor: 'rgb(128, 0, 128)'
+              }}
+            />
+          </InstUISettingsProvider>
+        )
+        const component = subject.getDOMNode()
+        const computedStyle = getComputedStyle(component)
+
+        expect(computedStyle.color).to.equal('rgb(128, 0, 128)')
+        expect(computedStyle.backgroundColor).to.equal('rgb(255, 255, 0)')
+      })
+
+      it('when it is a function', async () => {
+        const subject = await mount(
+          <InstUISettingsProvider theme={exampleTheme}>
+            <ThemedComponent
+              themeOverride={(componentTheme) => ({
+                textColor: componentTheme.backgroundColor
+              })}
+            />
+          </InstUISettingsProvider>
+        )
+        const component = subject.getDOMNode()
+        const computedStyle = getComputedStyle(component)
+
+        expect(computedStyle.color).to.equal('rgb(255, 255, 0)')
+        expect(computedStyle.backgroundColor).to.equal('rgb(255, 255, 0)')
+      })
+    })
+
+    it('should ignore empty themeOverride props', async () => {
+      const subject = await mount(
+        <InstUISettingsProvider theme={exampleTheme}>
+          <ThemedComponent themeOverride={{}} />
+        </InstUISettingsProvider>
+      )
+      const component = subject.getDOMNode()
+      const computedStyle = getComputedStyle(component)
+
+      expect(computedStyle.color).to.equal('rgb(0, 128, 0)')
+      expect(computedStyle.backgroundColor).to.equal('rgb(255, 255, 0)')
+    })
+  })
+
+  describe('should update css props', async () => {
+    it('when props are updated', async () => {
+      // `setProps` can be called on the outer component,
+      // so have to add the theme ad themeOverride here, and suppress the error
+      stub(console, 'warn') // suppress "no theme provided error"
+
+      const subject = await mount(
+        <ThemedComponent
+          inverse={false}
+          themeOverride={{
+            textColor: grey1111,
+            textColorInverse: blue4570,
+            backgroundColor: green4570
+          }}
+        />
+      )
+      const component = subject.getDOMNode()
+
+      expect(getComputedStyle(component).color).to.equal(grey1111)
+
+      await subject.setProps({ inverse: true })
+
+      expect(getComputedStyle(component).color).to.equal(blue4570)
+    })
+
+    it('when state is updated', async () => {
+      const subject = await mount(
+        <InstUISettingsProvider theme={exampleTheme}>
+          <ThemedComponent />
+        </InstUISettingsProvider>
+      )
+      const main = within(subject.getDOMNode())
+      const clearBackgroundButton = await main.find('button')
+      const component = main.getDOMNode()
+
+      expect(getComputedStyle(component).backgroundColor).to.equal(
+        'rgb(255, 255, 0)'
+      )
+
+      await clearBackgroundButton.click()
+
+      expect(getComputedStyle(component).backgroundColor).to.equal(
+        'rgba(0, 0, 0, 0)'
+      )
+    })
+  })
+
+  describe('should apply bi-directional polyfill on styles object', async () => {
+    it('in default "ltr" mode', async () => {
+      const subject = await mount(
+        <InstUISettingsProvider theme={exampleTheme}>
+          <ThemedComponent />
+        </InstUISettingsProvider>
+      )
+      const component = subject.getDOMNode()
+      const computedStyle = getComputedStyle(component)
+
+      // `inset-inline-start` should be transformed to 'left' in 'ltr' mode
+      expect(computedStyle.left).to.equal('8px')
+      expect(computedStyle.right).to.equal('auto')
+    })
+
+    it('in "rtl" mode', async () => {
+      const subject = await mount(
+        <InstUISettingsProvider theme={exampleTheme} dir="rtl">
+          <ThemedComponent />
+        </InstUISettingsProvider>
+      )
+      const component = subject.getDOMNode().firstElementChild
+      const computedStyle = getComputedStyle(component!)
+
+      // `inset-inline-start` should be transformed to 'right' in 'rtl' mode
+      expect(computedStyle.left).to.equal('auto')
+      expect(computedStyle.right).to.equal('8px')
+    })
+  })
+})

packages/emotion/src/index.ts

@@ -37,6 +37,8 @@ export {
   mapSpacingToShorthand
 } from './styleUtils'
 
+export { useStyle } from './useStyle'
+
 export type { ComponentStyle, StyleObject, Overrides } from './EmotionTypes'
 export type { WithStyleProps } from './withStyle'
 export type {