@instructure/emotion 8.18.1-snapshot.3 → 8.19.0

package/src/InstUISettingsProvider/index.tsx

@@ -23,35 +23,45 @@
  */
 
 import React, { useContext } from 'react'
-import { TextDirectionContext } from '@instructure/ui-i18n'
+import PropTypes from 'prop-types'
 import { ThemeProvider } from '@emotion/react'
-import { ThemeOrOverride } from '../EmotionTypes'
-import { getTheme } from '../EmotionThemeProvider'
+
+import { TextDirectionContext } from '@instructure/ui-i18n'
 import { DeterministicIdContextProvider } from '@instructure/ui-react-utils'
+
+import { getTheme } from '../EmotionThemeProvider'
+
+import type { ThemeOrOverride } from '../EmotionTypes'
 import type { DeterministicIdProviderValue } from '@instructure/ui-react-utils'
 
 type InstUIProviderProps = {
+  children?: React.ReactNode
+
+  /**
+   * A full theme or an override object
+   */
   theme?: ThemeOrOverride
-  dir?: 'ltr' | 'rtl' // TODO allow "auto" too
+
+  /**
+   * The text direction to use in the descendants. If not provided, it uses the following in this priority order:
+   *   - The value given in a parent `TextDirectionContext`
+   *   - The `dir` prop of `document.documentElement` or its `direction` CSS prop
+   *   - The default `ltr`
+   */
+  dir?: 'ltr' | 'rtl'
+
+  /**
+   * A [Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) which keeps track of specific InstUI components. (generally this is used for deterministic id generation for [SSR](/#server-side-rendering))
+   */
   instanceCounterMap?: DeterministicIdProviderValue
 }
 
-/**
- * @typedef InstUISettingsProviderSettings
- * @type {object}
- * @property {string} theme - A full theme or an override object
- * @property {string} dir - The text direction to use in the descendants. If not
- * given it uses the following in this priority order:
- *   - The value given in a parent `TextDirectionContext`
- *   - The `dir` prop of `document.documentElement` or its `direction` CSS prop
- *   - `ltr`
- * @property {Map<string, number>} instanceCounterMap - a Map to keep track of instances
- */
-
 /**
  * ---
  * category: components/utilities
  * ---
+ * @module InstUISettingsProvider
+ * @tsProps
  *
  * Wrapper for emotion js's [ThemeProvider](https://emotion.sh/docs/theming#themeprovider-reactcomponenttype).
  *
@@ -101,24 +111,19 @@ type InstUIProviderProps = {
  *    //read our [SSR](/#server-side-rendering) guide
  *    const counter = generateInstanceCounterMap()
  *    counter.set("Alert", 5)
- *   <InstUISettingsProvider instanceCounterMap={counter}
+ *   <InstUISettingsProvider instanceCounterMap={counter}>
  *     //this Alert's rendered DOM Node will have [id="Alert_5"] on it
  *     <Alert>Test!</Alert>
  *   </InstUISettingsProvider>
  * </InstUISettingsProvider>
  * ```
- *
- * @module InstUISettingsProvider
- *
- * @param {InstUISettingsProviderSettings} settings - A settings object
- * @returns {ReactElement} The settings provider
  */
 function InstUISettingsProvider({
   children,
   theme = {},
   dir,
   instanceCounterMap
-}: React.PropsWithChildren<InstUIProviderProps>) {
+}: InstUIProviderProps) {
   const finalDir = dir || useContext(TextDirectionContext)
 
   if (process.env.NODE_ENV !== 'production' && finalDir === 'auto') {
@@ -138,10 +143,18 @@ function InstUISettingsProvider({
   )
 }
 
+InstUISettingsProvider.propTypes = {
+  /* eslint-disable react/require-default-props */
+  children: PropTypes.node,
+  theme: PropTypes.object,
+  dir: PropTypes.oneOf(['ltr', 'rtl']),
+  instanceCounterMap: PropTypes.instanceOf(Map)
+  /* eslint-enable react/require-default-props */
+}
+
 InstUISettingsProvider.defaultProps = {
-  theme: {},
-  dir: undefined,
-  instanceCounterMap: undefined
+  theme: {}
 }
+
 export default InstUISettingsProvider
 export { InstUISettingsProvider }

package/src/getComponentThemeOverride.ts

@@ -27,7 +27,7 @@ import type {
   Overrides,
   ComponentOverride
 } from './EmotionTypes'
-import type { ComponentTheme } from '@instructure/shared-types'
+import type { BaseTheme, ComponentTheme } from '@instructure/shared-types'
 import type { WithStyleProps } from './withStyle'
 
 type ComponentName = keyof ComponentOverride | undefined
@@ -43,26 +43,46 @@ type ComponentName = keyof ComponentOverride | undefined
  * @param {*} displayName - Name of the component
  * @param {*} componentId - componentId of the component
  * @param {*} props - The component's props object
+ * @param {*} componentTheme - The component's default theme
  * @returns {object} The calculated theme override object
  */
 const getComponentThemeOverride = (
   theme: ThemeOrOverride,
   displayName: string,
   componentId?: string,
-  props?: { [k: string]: unknown } & WithStyleProps
-): ComponentTheme => {
-  let componentOverride: ComponentTheme = {}
-  const overrides = (theme as Overrides).componentOverrides
+  props?: { [k: string]: unknown } & WithStyleProps,
+  componentTheme?: ComponentTheme
+): Partial<ComponentTheme> => {
   const name = displayName as ComponentName
   const id = componentId as ComponentName
 
-  if (overrides) {
-    componentOverride = (name && overrides[name]) || (id && overrides[id]) || {}
+  const { themeOverride } = props as WithStyleProps
+  const { componentOverrides } = theme as Overrides
+
+  let overridesFromTheme: Partial<ComponentTheme> = {}
+  let overrideFromComponent: Partial<ComponentTheme> = {}
+
+  if (componentOverrides) {
+    overridesFromTheme =
+      (name && componentOverrides[name]) || (id && componentOverrides[id]) || {}
+  }
+
+  if (themeOverride) {
+    if (typeof themeOverride === 'function') {
+      overrideFromComponent = themeOverride(
+        componentTheme || {},
+        // the `theme` technically could be a partial theme / override object too,
+        // but we want to display all possible options
+        theme as BaseTheme
+      )
+    } else {
+      overrideFromComponent = themeOverride
+    }
   }
 
   return {
-    ...componentOverride,
-    ...(props?.themeOverride ?? {})
+    ...overridesFromTheme,
+    ...overrideFromComponent
   }
 }
 

package/src/withStyle.tsx

@@ -68,7 +68,9 @@ type WithStylePrivateProps<
     }
 
 type ThemeOverrideProp<Theme extends ComponentTheme | null = ComponentTheme> = {
-  themeOverride?: Partial<Theme>
+  themeOverride?:
+    | Partial<Theme>
+    | ((componentTheme: Theme, currentTheme: BaseTheme) => Partial<Theme>)
 }
 
 type WithStyleProps<
@@ -90,7 +92,7 @@ const defaultValues = {
  *
  * A decorator or higher order component that makes a component themeable.
  *
- * It adds a `makeStyles` function and the generated `styles` object to the decorated Component's props.
+ * It adds a `makeStyles` function and the generated `styles` object to the decorated Component's props. If it has an own theme, it also adds the `themeOverride` prop to the component.
  *
  * As a HOC:
  *
@@ -99,7 +101,6 @@ const defaultValues = {
  * import generateStyle from './styles'
  * import generateComponentTheme from './theme'
  *
- *
  * export default withStyle(generateStyle, generateComponentTheme)(ExampleComponent)
  * ```
  *
@@ -112,10 +113,12 @@ const defaultValues = {
  * [InstUISettingsProvider](#InstUISettingsProvider) component, and/or set
  * explicitly via its `themeOverride` prop.
  *
- * InstUISettingsProvider provides a theme object with [global theme variables](#canvas).
+ * InstUISettingsProvider provides a theme object with global theme variables (e.g. the [canvas theme](/#canvas)).
  * These variables are mapped to the component's own variables in `theme.js` (see [@instructure/emotion](#emotion) package documentation for more info).
  *
- * With the `themeOverride` prop you can directly set/override the component theme variables declared in theme.js.
+ * With the `themeOverride` prop you can directly set/override the component theme variables declared in theme.js. It accepts an object or a function. The function has the component's theme and the currently active main theme as its parameter.
+ *
+ * See more about the overrides on the [Using theme overrides](/#using-theme-overrides) docs page.
  *
  * ```js
  * // ExampleComponent/theme.js
@@ -142,6 +145,12 @@ const defaultValues = {
  * }}>
  *  {// component theme override}
  *   <ExampleComponent themeOverride={{ hoverColor: '#eee' }} />
+ *
+ *  {// component theme override with function}
+ *   <ExampleComponent themeOverride={(componentTheme, currentTheme) => ({
+ *     hoverBackground: componentTheme.background,
+ *     activeBackground: currentTheme.colors.backgroundBrand
+ *   })} />
  * </InstUISettingsProvider>
  * ```
  *
@@ -181,26 +190,27 @@ const withStyle = decorator(
           `Manually passing the "makeStyles" property is not allowed on the ${displayName} component. Styles are calculated by the @withStyle decorator.`
         )
       }
+
       const componentProps: Props = {
         ...ComposedComponent.defaultProps,
         ...props,
         ...defaultValues
       }
 
+      let componentTheme: ComponentTheme =
+        typeof generateComponentTheme === 'function'
+          ? generateComponentTheme(theme as BaseTheme)
+          : {}
+
       const themeOverride = getComponentThemeOverride(
         theme,
         displayName,
         ComposedComponent.componentId,
-        componentProps
+        componentProps,
+        componentTheme
       )
 
-      const componentTheme: ComponentTheme =
-        typeof generateComponentTheme === 'function'
-          ? {
-              ...generateComponentTheme(theme as BaseTheme),
-              ...themeOverride
-            }
-          : {}
+      componentTheme = { ...componentTheme, ...themeOverride }
 
       const [styles, setStyles] = useState(
         generateStyle ? generateStyle(componentTheme, componentProps, {}) : {}