feat(ui-themes,ui-utils): deprecate global theme storage, theme.use a…

…nd theme.variables

packages/emotion/src/getTheme.ts

@@ -37,15 +37,17 @@ import type {
  * ---
  * private: true
  * ---
- * Gives back the theme object for the the provider.
+ * Gives back the theme object for the provider.
  *
  * If a valid InstUI theme is given, it just returns the theme.
  *
  * If an override object is given, it returns the ancestor theme and
  * the overrides merged together.
  *
- * @param {object} themeOrOverride - A full theme or an override object
- * @returns {function} A function that returns with the theme object for the [ThemeProvider](https://emotion.sh/docs/theming#themeprovider-reactcomponenttype)
+ * @param themeOrOverride - A full theme or an override object
+ * @returns A function that returns with the theme object for the [ThemeProvider](https://emotion.sh/docs/theming#themeprovider-reactcomponenttype)
+ *    This function is called by Emotion on theme provider creation, where
+ *    `ancestorTheme` is a theme object from an ancestor `ThemeProvider`
  */
 const getTheme =
   (themeOrOverride: ThemeOrOverride) =>
@@ -71,7 +73,6 @@ const getTheme =
 
     // we need to clone the ancestor theme not to override it
     let currentTheme
-
     if (Object.keys(ancestorTheme).length === 0) {
       const globalTheme = ThemeRegistry.getCurrentTheme()
 

packages/emotion/src/useTheme.ts

@@ -36,9 +36,10 @@ import type { ThemeOrOverride } from './EmotionTypes'
  * A hook that will return the currently applied theme object from the nearest Context.
  * If there is no Context, then it tries to get the current theme from the global ThemeRegistry.
  * If there is no theme provided to the Context and ThemeRegistry it will return the default `canvas` theme.
- * @returns {object} the theme object
+ * @returns The theme object
  */
 const useTheme = () => {
+  // This reads the theme from Emotion's ThemeContext
   let theme = useEmotionTheme() as ThemeOrOverride
 
   if (isEmpty(theme)) {

packages/theme-registry/src/ThemeRegistry.ts

@@ -26,6 +26,7 @@
  * ---
  * category: utilities/themes
  * ---
+ * DEPRECATED. This will be deleted, please use InstUISettingsProvider instead.
  * A global theme registry used for registering theme objects, setting globally available themes
  * and receiving the currently used theme.
  * @module ThemeRegistry
@@ -52,7 +53,9 @@ type Registry<T extends RegisteredTheme> = {
 }
 
 type RegisteredTheme<T extends BaseTheme = BaseTheme> = T & {
+  // DEPRECATED. Use InstUISettingsProvider instead
   use(arg?: { overrides: DeepPartial<BaseThemeVariables> }): void
+  // DEPRECATED. Read its variables dirrectly from the theme object.
   variables: BaseThemeVariables
 }
 
@@ -225,7 +228,8 @@ function makeTheme<T extends BaseTheme>(theme: T): RegisteredTheme<T> {
  * Registers the passed theme into the ThemeRegistry.
  * @param {BaseTheme} theme - the theme object to register into the ThemeRegistry
  * @returns {RegisteredTheme} If the given theme is already in the ThemeRegistry then simply return that theme.
- * Otherwise returns the theme with a wrapper around it, so it can be `.use()`-ed to activate the given theme from the registry.
+ * Otherwise, returns the theme with a wrapper around it, so it can be `.use()`-ed to activate the given theme from the registry.
+ * This function also adds a `variables` prop for backwards compatibility (deprecated).
  * @module registerTheme
  */
 function registerTheme<T extends BaseTheme>(theme: T): RegisteredTheme<T> {

packages/ui-themes/src/index.ts

@@ -32,8 +32,10 @@ import type {
   UI
 } from '@instructure/shared-types'
 
-import canvasHighContrast from './themes/canvasHighContrast'
-import canvas from './themes/canvas'
+import canvasHighContrast, {
+  canvasHighContrastThemeLocal
+} from './themes/canvasHighContrast'
+import canvas, { canvasThemeLocal } from './themes/canvas'
 
 import {
   primitives,
@@ -61,7 +63,9 @@ type ThemeSpecificStyle<ComponentTheme> = {
 
 export {
   canvas,
+  canvasThemeLocal,
   canvasHighContrast,
+  canvasHighContrastThemeLocal,
   primitives,
   additionalPrimitives,
   dataVisualization

packages/ui-themes/src/themes/canvas/index.ts

@@ -67,3 +67,5 @@ const __theme: CanvasTheme = {
 const theme = ThemeRegistry.registerTheme(__theme)
 
 export default theme
+// theme without the use() function and `variables` prop
+export { __theme as canvasThemeLocal }

packages/ui-themes/src/themes/canvasHighContrast/index.ts

@@ -39,6 +39,8 @@ const __theme: CanvasHighContrastTheme = {
   ...sharedThemeTokens,
   colors
 }
-const theme = ThemeRegistry.registerTheme(__theme)
 
+const theme = ThemeRegistry.registerTheme(__theme)
 export default theme
+// theme without the use() function and `variables` prop
+export { __theme as canvasHighContrastThemeLocal }

packages/ui-utils/src/isBaseTheme.ts

@@ -39,6 +39,12 @@ const baseThemeProps: BaseThemeVariableKeys = [
   'typography'
 ]
 
+/**
+ * Checks if the given param is an object with all the keys needed for an
+ * Instructure theme.
+ * @param theme Anything. This function will throw an error if it's not a theme
+ * object.
+ */
 const isBaseTheme = (theme: any): theme is BaseTheme => {
   if (Array.isArray(theme) || typeof theme === 'function') {
     throw new Error()