feat(emotion): [InstUISettingsProvider] should be able to access the current theme

INSTUI-4525

Author: HerrTopi

docs/guides/using-theme-overrides.md

@@ -179,6 +179,34 @@ type: code
 </InstUISettingsProvider>
 ```
 
+#### Override function
+
+The `InstUISettingsProvider` accepts a `function`. The override function's first parameter is the currently applied theme object. It should return a valid theme or override object.
+
+```js
+---
+type: example
+---
+<div>
+  <div>
+  <InstUISettingsProvider theme={
+    (theme)=>{
+      return {
+        componentOverrides: {
+          Alert:{
+            infoBorderColor:theme.colors.contrasts.red4570
+          }
+        }
+      }
+    }
+  }
+  >
+    <Alert>Overridden Alert</Alert>
+  </InstUISettingsProvider>
+</div>
+</div>
+```
+
 ### Overriding theme for a single component
 
 Themeable components (that implement the [withStyle](#withStyle) decorator) accept a `themeOverride` prop. This prop let's you override the component's own theme. It accepts an object or a function.

packages/__docs__/src/Document/index.tsx

@@ -76,7 +76,7 @@ class Document extends Component<DocumentProps, DocumentState> {
     const generateTheme = doc?.componentInstance?.generateComponentTheme
     const generateThemeFunctional =
       functionalComponentThemes[
-        doc.id as keyof typeof functionalComponentThemes
+      doc.id as keyof typeof functionalComponentThemes
       ]
     if (
       generateTheme &&
@@ -173,9 +173,9 @@ class Document extends Component<DocumentProps, DocumentState> {
   {...props}
   themeOverride={{
     ${
-      // get random theme variable
-      themeVariableKeys[Math.floor(Math.random() * themeVariableKeys.length)]
-    }: 'custom value'
+              // get random theme variable
+              themeVariableKeys[Math.floor(Math.random() * themeVariableKeys.length)]
+              }: 'custom value'
   }}
 />`}
           />

packages/emotion/src/EmotionTypes.ts

@@ -101,7 +101,11 @@ type Overrides = {
   componentOverrides?: ComponentOverride
 }
 
-type ThemeOrOverride = BaseTheme | PartialTheme | Overrides
+type BaseThemeOrOverride = BaseTheme | PartialTheme | Overrides
+
+type ThemeOrOverride =
+  | BaseThemeOrOverride
+  | ((theme: BaseTheme) => BaseThemeOrOverride)
 
 type Props = Record<string, unknown>
 type State = Record<string, unknown>
@@ -134,6 +138,7 @@ export interface StyleObject {
 }
 
 export type {
+  BaseThemeOrOverride,
   ThemeOrOverride,
   Overrides,
   ComponentOverride,

packages/emotion/src/InstUISettingsProvider/__new-tests__/InstUISettingsProvider.test.tsx

@@ -0,0 +1,43 @@
+/*
+ * 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.
+ */
+
+import { render } from '@testing-library/react'
+import { vi } from 'vitest'
+
+import '@testing-library/jest-dom'
+import { InstUISettingsProvider } from '../index'
+import { canvasHighContrast } from '@instructure/ui-themes'
+
+describe('<InstUISettingsProvider />', () => {
+  it('passes the current theme if a function is passed to theme prop', async () => {
+    const themeFn = vi.fn()
+    render(
+      <InstUISettingsProvider theme={canvasHighContrast}>
+        <InstUISettingsProvider theme={themeFn}></InstUISettingsProvider>
+      </InstUISettingsProvider>
+    )
+
+    expect(themeFn).toHaveBeenCalledWith(canvasHighContrast)
+  })
+})

packages/emotion/src/InstUISettingsProvider/index.tsx

@@ -122,7 +122,7 @@ function InstUISettingsProvider({
 InstUISettingsProvider.propTypes = {
   /* eslint-disable react/require-default-props */
   children: PropTypes.node,
-  theme: PropTypes.object,
+  theme: PropTypes.oneOf([PropTypes.object, PropTypes.func]),
   dir: PropTypes.oneOf(['ltr', 'rtl']),
   instanceCounterMap: PropTypes.instanceOf(Map),
   as: PropTypes.string

packages/emotion/src/getTheme.ts

@@ -52,25 +52,6 @@ import type {
 const getTheme =
   (themeOrOverride: ThemeOrOverride) =>
   (ancestorTheme = {} as BaseTheme) => {
-    try {
-      // If a valid InstUI theme is given, it just returns the theme.
-      if (isBaseTheme(themeOrOverride)) {
-        return themeOrOverride
-      }
-    } catch {
-      // If the prop passed is not an Object, it will throw an error.
-      // We are using this fail-safe here for the non-TS users,
-      // because the whole page can break without a theme.
-      if (process.env.NODE_ENV !== 'production') {
-        console.warn(
-          'The `theme` property provided to InstUISettingsProvider is not a valid InstUI theme object.\ntheme: ',
-          themeOrOverride
-        )
-      }
-      // eslint-disable-next-line no-param-reassign
-      themeOrOverride = {}
-    }
-
     // we need to clone the ancestor theme not to override it
     let currentTheme
     if (Object.keys(ancestorTheme).length === 0) {
@@ -86,16 +67,44 @@ const getTheme =
       currentTheme = ancestorTheme
     }
 
+    let resolvedThemeOrOverride = themeOrOverride
+
+    if (typeof resolvedThemeOrOverride === 'function') {
+      resolvedThemeOrOverride = resolvedThemeOrOverride(currentTheme)
+    }
+    try {
+      // If a valid InstUI theme is given, it just returns the theme.
+      if (isBaseTheme(resolvedThemeOrOverride)) {
+        return resolvedThemeOrOverride
+      }
+    } catch {
+      // If the prop passed is not an Object, it will throw an error.
+      // We are using this fail-safe here for the non-TS users,
+      // because the whole page can break without a theme.
+      if (process.env.NODE_ENV !== 'production') {
+        console.warn(
+          'The `theme` property provided to InstUISettingsProvider is not a valid InstUI theme object.\ntheme: ',
+          resolvedThemeOrOverride
+        )
+      }
+      resolvedThemeOrOverride = {}
+    }
+
     const themeName = currentTheme.key
 
     // we pick the overrides for the current theme from the override object
-    const specificOverrides = (themeOrOverride as Overrides)?.themeOverrides
+    const specificOverrides = (resolvedThemeOrOverride as Overrides)
+      ?.themeOverrides
     const currentThemeOverrides =
       (specificOverrides as SpecificThemeOverride)?.[themeName] ||
       specificOverrides ||
       {}
 
-    return mergeDeep(currentTheme, themeOrOverride, currentThemeOverrides)
+    return mergeDeep(
+      currentTheme,
+      resolvedThemeOrOverride,
+      currentThemeOverrides
+    )
   }
 
 export default getTheme

packages/emotion/src/useTheme.ts

@@ -27,7 +27,7 @@ import canvas from '@instructure/ui-themes'
 import { isEmpty } from '@instructure/ui-utils'
 import { ThemeRegistry } from '@instructure/theme-registry'
 
-import type { ThemeOrOverride } from './EmotionTypes'
+import type { BaseThemeOrOverride } from './EmotionTypes'
 
 /**
  * ---
@@ -40,7 +40,7 @@ import type { ThemeOrOverride } from './EmotionTypes'
  */
 const useTheme = () => {
   // This reads the theme from Emotion's ThemeContext
-  let theme = useEmotionTheme() as ThemeOrOverride
+  let theme = useEmotionTheme() as BaseThemeOrOverride
 
   if (isEmpty(theme)) {
     const globalTheme = ThemeRegistry.getCurrentTheme()