@instructure/emotion 8.18.1-snapshot.3 → 8.19.1-snapshot.1

package/CHANGELOG.md

@@ -3,6 +3,12 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [8.19.0](https://github.com/instructure/instructure-ui/compare/v8.18.0...v8.19.0) (2022-03-16)
+
+### Features
+
+- **emotion:** themeOverride prop to accept function ([505f0bf](https://github.com/instructure/instructure-ui/commit/505f0bfad12aaa4f3d1607a85409f5541246e879))
+
 # [8.18.0](https://github.com/instructure/instructure-ui/compare/v8.17.0...v8.18.0) (2022-02-23)
 
 **Note:** Version bump only for package @instructure/emotion

package/README.md

@@ -83,7 +83,46 @@ export default Button
 
 Themeable components inject their themed styles into the document when they are mounted.
 
-A themeable component’s theme can be configured by wrapping it in an [InstUISettingsProvider](#InstUISettingsProvider) component, and/or set explicitly via its `themeOverride` prop (see [withStyle](#withStyle/#applying-themes) documentation).
+A themeable component’s theme can be configured by wrapping it in an [InstUISettingsProvider](#InstUISettingsProvider) component, and/or set explicitly via its `themeOverride` prop.
+
+#### themeOverride prop
+
+The themeable components accept a `themeOverride` prop which let's you override it's component theme object. It accepts an override object or a function, which has the current `componentTheme` as its parameter.
+
+**See more on the [withStyle](#withStyle/#applying-themes) and [Using theme overrides](/#using-theme-overrides) doc pages for more info.**
+
+```js
+---
+example: true
+---
+<div>
+  <Button color='primary' themeOverride={{ primaryBackground: "purple" }}>
+    Button
+  </Button>
+  <Button
+    color='primary'
+    margin="0 0 0 small"
+    themeOverride={(componentTheme) => ({
+      primaryBackground: componentTheme.successBackground,
+      primaryBorderColor: componentTheme.successBorderColor
+    })}
+  >
+    Button
+  </Button>
+  <Button
+    color='primary'
+    margin="0 0 0 small"
+    themeOverride={(_componentTheme, currentTheme) => ({
+      primaryBackground: currentTheme.colors.backgroundWarning,
+      primaryBorderColor: currentTheme.colors.backgroundLightest,
+      borderWidth: currentTheme.borders.widthLarge,
+      borderStyle: 'dashed'
+    })}
+  >
+    Button
+  </Button>
+</div>
+```
 
 #### InstUISettingsProvider
 

package/es/InstUISettingsProvider/index.js

@@ -22,27 +22,18 @@
  * SOFTWARE.
  */
 import React, { useContext } from 'react';
-import { TextDirectionContext } from '@instructure/ui-i18n';
+import PropTypes from 'prop-types';
 import { ThemeProvider } from '@emotion/react';
-import { getTheme } from '../EmotionThemeProvider';
+import { TextDirectionContext } from '@instructure/ui-i18n';
 import { DeterministicIdContextProvider } from '@instructure/ui-react-utils';
-
-/**
- * @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
- */
+import { getTheme } from '../EmotionThemeProvider';
 
 /**
  * ---
  * category: components/utilities
  * ---
+ * @module InstUISettingsProvider
+ * @tsProps
  *
  * Wrapper for emotion js's [ThemeProvider](https://emotion.sh/docs/theming#themeprovider-reactcomponenttype).
  *
@@ -92,17 +83,12 @@ import { DeterministicIdContextProvider } from '@instructure/ui-react-utils';
  *    //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(_ref) {
   let children = _ref.children,
@@ -123,10 +109,17 @@ function InstUISettingsProvider(_ref) {
   }, children)));
 }
 
+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: void 0,
-  instanceCounterMap: void 0
+  theme: {}
 };
 export default InstUISettingsProvider;
 export { InstUISettingsProvider };

package/es/getComponentThemeOverride.js

@@ -33,22 +33,35 @@
  * @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, displayName, componentId, props) => {
-  var _props$themeOverride;
-
-  let componentOverride = {};
-  const overrides = theme.componentOverrides;
+const getComponentThemeOverride = (theme, displayName, componentId, props, componentTheme) => {
   const name = displayName;
   const id = componentId;
+  const _ref = props,
+        themeOverride = _ref.themeOverride;
+  const _ref2 = theme,
+        componentOverrides = _ref2.componentOverrides;
+  let overridesFromTheme = {};
+  let overrideFromComponent = {};
+
+  if (componentOverrides) {
+    overridesFromTheme = name && componentOverrides[name] || id && componentOverrides[id] || {};
+  }
 
-  if (overrides) {
-    componentOverride = name && overrides[name] || id && overrides[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);
+    } else {
+      overrideFromComponent = themeOverride;
+    }
   }
 
-  return { ...componentOverride,
-    ...((_props$themeOverride = props === null || props === void 0 ? void 0 : props.themeOverride) !== null && _props$themeOverride !== void 0 ? _props$themeOverride : {})
+  return { ...overridesFromTheme,
+    ...overrideFromComponent
   };
 };
 

package/es/withStyle.js

@@ -41,7 +41,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:
  *
@@ -50,7 +50,6 @@ const defaultValues = {
  * import generateStyle from './styles'
  * import generateComponentTheme from './theme'
  *
- *
  * export default withStyle(generateStyle, generateComponentTheme)(ExampleComponent)
  * ```
  *
@@ -63,10 +62,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
@@ -93,6 +94,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>
  * ```
  *
@@ -120,10 +127,11 @@ const withStyle = decorator((ComposedComponent, generateStyle, generateComponent
       ...props,
       ...defaultValues
     };
-    const themeOverride = getComponentThemeOverride(theme, displayName, ComposedComponent.componentId, componentProps);
-    const componentTheme = typeof generateComponentTheme === 'function' ? { ...generateComponentTheme(theme),
+    let componentTheme = typeof generateComponentTheme === 'function' ? generateComponentTheme(theme) : {};
+    const themeOverride = getComponentThemeOverride(theme, displayName, ComposedComponent.componentId, componentProps, componentTheme);
+    componentTheme = { ...componentTheme,
       ...themeOverride
-    } : {};
+    };
 
     const _useState = useState(generateStyle ? generateStyle(componentTheme, componentProps, {}) : {}),
           _useState2 = _slicedToArray(_useState, 2),

package/lib/InstUISettingsProvider/index.js

@@ -1,5 +1,7 @@
 "use strict";
 
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault").default;
+
 var _interopRequireWildcard = require("@babel/runtime/helpers/interopRequireWildcard").default;
 
 Object.defineProperty(exports, "__esModule", {
@@ -10,14 +12,16 @@ exports.default = void 0;
 
 var _react = _interopRequireWildcard(require("react"));
 
-var _TextDirectionContext = require("@instructure/ui-i18n/lib/TextDirectionContext.js");
+var _propTypes = _interopRequireDefault(require("prop-types"));
 
 var _react2 = require("@emotion/react");
 
-var _EmotionThemeProvider = require("../EmotionThemeProvider");
+var _TextDirectionContext = require("@instructure/ui-i18n/lib/TextDirectionContext.js");
 
 var _uiReactUtils = require("@instructure/ui-react-utils");
 
+var _EmotionThemeProvider = require("../EmotionThemeProvider");
+
 /*
  * The MIT License (MIT)
  *
@@ -42,22 +46,12 @@ var _uiReactUtils = require("@instructure/ui-react-utils");
  * SOFTWARE.
  */
 
-/**
- * @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).
  *
@@ -107,17 +101,12 @@ var _uiReactUtils = require("@instructure/ui-react-utils");
  *    //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(_ref) {
   let children = _ref.children,
@@ -138,10 +127,17 @@ function InstUISettingsProvider(_ref) {
   }, children)));
 }
 
+InstUISettingsProvider.propTypes = {
+  /* eslint-disable react/require-default-props */
+  children: _propTypes.default.node,
+  theme: _propTypes.default.object,
+  dir: _propTypes.default.oneOf(['ltr', 'rtl']),
+  instanceCounterMap: _propTypes.default.instanceOf(Map)
+  /* eslint-enable react/require-default-props */
+
+};
 InstUISettingsProvider.defaultProps = {
-  theme: {},
-  dir: void 0,
-  instanceCounterMap: void 0
+  theme: {}
 };
 var _default = InstUISettingsProvider;
 exports.default = _default;

package/lib/getComponentThemeOverride.js

@@ -40,22 +40,35 @@ exports.getComponentThemeOverride = exports.default = void 0;
  * @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, displayName, componentId, props) => {
-  var _props$themeOverride;
-
-  let componentOverride = {};
-  const overrides = theme.componentOverrides;
+const getComponentThemeOverride = (theme, displayName, componentId, props, componentTheme) => {
   const name = displayName;
   const id = componentId;
+  const _ref = props,
+        themeOverride = _ref.themeOverride;
+  const _ref2 = theme,
+        componentOverrides = _ref2.componentOverrides;
+  let overridesFromTheme = {};
+  let overrideFromComponent = {};
+
+  if (componentOverrides) {
+    overridesFromTheme = name && componentOverrides[name] || id && componentOverrides[id] || {};
+  }
 
-  if (overrides) {
-    componentOverride = name && overrides[name] || id && overrides[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);
+    } else {
+      overrideFromComponent = themeOverride;
+    }
   }
 
-  return { ...componentOverride,
-    ...((_props$themeOverride = props === null || props === void 0 ? void 0 : props.themeOverride) !== null && _props$themeOverride !== void 0 ? _props$themeOverride : {})
+  return { ...overridesFromTheme,
+    ...overrideFromComponent
   };
 };
 

package/lib/withStyle.js

@@ -59,7 +59,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:
  *
@@ -68,7 +68,6 @@ const defaultValues = {
  * import generateStyle from './styles'
  * import generateComponentTheme from './theme'
  *
- *
  * export default withStyle(generateStyle, generateComponentTheme)(ExampleComponent)
  * ```
  *
@@ -81,10 +80,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
@@ -111,6 +112,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>
  * ```
  *
@@ -138,10 +145,11 @@ const withStyle = (0, _decorator.decorator)((ComposedComponent, generateStyle, g
       ...props,
       ...defaultValues
     };
-    const themeOverride = (0, _getComponentThemeOverride.getComponentThemeOverride)(theme, displayName, ComposedComponent.componentId, componentProps);
-    const componentTheme = typeof generateComponentTheme === 'function' ? { ...generateComponentTheme(theme),
+    let componentTheme = typeof generateComponentTheme === 'function' ? generateComponentTheme(theme) : {};
+    const themeOverride = (0, _getComponentThemeOverride.getComponentThemeOverride)(theme, displayName, ComposedComponent.componentId, componentProps, componentTheme);
+    componentTheme = { ...componentTheme,
       ...themeOverride
-    } : {};
+    };
 
     const _useState = (0, _react.useState)(generateStyle ? generateStyle(componentTheme, componentProps, {}) : {}),
           _useState2 = (0, _slicedToArray2.default)(_useState, 2),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instructure/emotion",
-  "version": "8.18.1-snapshot.3+c6a2ad87e",
+  "version": "8.19.1-snapshot.1+243eb1698",
   "description": "A UI component library made by Instructure Inc.",
   "author": "Instructure, Inc. Engineering and Product Design",
   "module": "./es/index.js",
@@ -25,21 +25,21 @@
   "dependencies": {
     "@babel/runtime": "^7.13.10",
     "@emotion/react": "^11",
-    "@instructure/console": "8.18.1-snapshot.3+c6a2ad87e",
-    "@instructure/shared-types": "8.18.1-snapshot.3+c6a2ad87e",
-    "@instructure/ui-decorator": "8.18.1-snapshot.3+c6a2ad87e",
-    "@instructure/ui-i18n": "8.18.1-snapshot.3+c6a2ad87e",
-    "@instructure/ui-react-utils": "8.18.1-snapshot.3+c6a2ad87e",
-    "@instructure/ui-themes": "8.18.1-snapshot.3+c6a2ad87e",
-    "@instructure/ui-utils": "8.18.1-snapshot.3+c6a2ad87e",
+    "@instructure/console": "8.19.1-snapshot.1+243eb1698",
+    "@instructure/shared-types": "8.19.1-snapshot.1+243eb1698",
+    "@instructure/ui-decorator": "8.19.1-snapshot.1+243eb1698",
+    "@instructure/ui-i18n": "8.19.1-snapshot.1+243eb1698",
+    "@instructure/ui-react-utils": "8.19.1-snapshot.1+243eb1698",
+    "@instructure/ui-themes": "8.19.1-snapshot.1+243eb1698",
+    "@instructure/ui-utils": "8.19.1-snapshot.1+243eb1698",
     "emotion-theming": "^11",
     "hoist-non-react-statics": "^3.3.2",
     "lodash": "^4",
     "prop-types": "^15"
   },
   "devDependencies": {
-    "@instructure/ui-babel-preset": "8.18.1-snapshot.3+c6a2ad87e",
-    "@instructure/ui-test-utils": "8.18.1-snapshot.3+c6a2ad87e",
+    "@instructure/ui-babel-preset": "8.19.1-snapshot.1+243eb1698",
+    "@instructure/ui-test-utils": "8.19.1-snapshot.1+243eb1698",
     "@types/lodash": "^4.14.171",
     "cpy-cli": "^3.1.1"
   },
@@ -50,5 +50,5 @@
     "access": "public"
   },
   "sideEffects": false,
-  "gitHead": "c6a2ad87e2c3baae81798304250fbf9291057393"
+  "gitHead": "243eb169866e654e9aaaaaba4a96a6778c06ccdf"
 }

package/src/EmotionThemeProvider/README.md

@@ -2,7 +2,18 @@
 describes: EmotionThemeProvider
 ---
 
-#### DEPRECATED. Please use [InstUISettingsProvider](#InstUISettingsProvider) instead. It has the same functionality and adds text direction configuration.
+```js
+---
+embed: true
+---
+<ToggleBlockquote
+  summary="DEPRECATED"
+>
+  <ToggleBlockquote.Paragraph>
+    This component is depreacted. Please use <Link href="#InstUISettingsProvider">InstUISettingsProvider</Link> instead. It has the same functionality and adds additional configuration.
+  </ToggleBlockquote.Paragraph>
+</ToggleBlockquote>
+```
 
 The `<EmotionThemeProvider/>` component provides a way to set the theme for our app or override the default theme properties for all themeable child components using the [withStyle](#withStyle) decorator.
 

package/src/InstUISettingsProvider/README.md

@@ -0,0 +1,110 @@
+---
+describes: InstUISettingsProvider
+---
+
+The `<InstUISettingsProvider/>` component provides a way to add global configuration to our app. It can be used to apply and handle themes (for all themeable child components that use the [withStyle](#withStyle) decorator), setting the global text direction, etc.
+
+Note that `<InstUISettingsProvider/>` components can be nested!
+
+Table of Contents:
+
+- [Theme management](/#InstUISettingsProvider/#theme-management)
+  - [Applying theme to the application](/#InstUISettingsProvider/#theme-management-applying-theme-to-the-application)
+  - [Nesting theme providers](/#InstUISettingsProvider/#theme-management-nesting-theme-providers)
+  - [Theme overrides](/#InstUISettingsProvider/#theme-management-theme-overrides)
+- [Text direction management](/#InstUISettingsProvider/#text-direction-management)
+- [Server Side Rendering support](/#InstUISettingsProvider/#server-side-rendering-support)
+- [Properties](/#InstUISettingsProvider/#InstUISettingsProviderProperties)
+
+### Theme management
+
+`<InstUISettingsProvider/>` is a wrapper for the [ThemeProvider](https://emotion.sh/docs/theming#themeprovider-reactcomponenttype) of Emotion library that we use under the hood for theming and applying css styles to our components.
+
+#### Applying theme to the application
+
+The `theme` prop applies the given theme. It handles either a full theme, or an overrides object. Theme properties will fall back to the parent theme, or the default `canvas` theme when they are not set.
+
+To apply a theme to whole app, you need to import `<InstUISettingsProvider/>` and the theme you want to use from `@instructure/ui-themes` (or use your own compatible theme), and wrap your app in the theme provider.
+
+```js
+import React from 'react'
+import ReactDOM from 'react-dom'
+
+import { instructure } from '@instructure/ui-themes'
+import { InstUISettingsProvider } from '@instructure/emotion'
+
+import { App } from './App'
+
+ReactDOM.render(
+  <InstUISettingsProvider theme={instructure}>
+    <App />
+  </InstUISettingsProvider>,
+  document.getElementById('app')
+)
+```
+
+#### Nesting theme providers
+
+```js
+<InstUISettingsProvider theme={canvas}>
+  <Heading>I should have "canvas" font family.</Heading>
+
+  <InstUISettingsProvider theme={instructure}>
+    <Heading>I should have "instructure" font family.</Heading>
+  </InstUISettingsProvider>
+</InstUISettingsProvider>
+```
+
+#### Theme overrides
+
+There are multiple ways to override themes in InstUI. You can read about how these work on the dedicated docs page: [Using theme overrides](/#using-theme-overrides).
+
+### Text direction management
+
+The `dir` prop sets the text direction for its descendants. It wraps its children in a [TextDirectionContext.Provider](/#TextDirectionContext), so that the text direction context can be consumed by child components that have implemented [textDirectionContextConsumer](#textDirectionContextConsumer).
+
+If no `dir` prop is supplied, it will fall back to its parent context if it
+exists. Otherwise, it queries for and uses the documentElement `dir` attribute and defaults to `ltr` if it is not found.
+
+```js
+---
+example: true
+---
+<InstUISettingsProvider dir="ltr">
+  <div>LTR text</div>
+  <Badge count={105} countUntil={100} margin="small medium 0 0">
+    <Button>LTR Badge</Button>
+  </Badge>
+
+  <InstUISettingsProvider dir="rtl">
+    <View as="div">
+      <div>Nested RTL text</div>
+      <Badge count={105} countUntil={100} margin="small medium 0 0">
+        <Button>Nested RTL Badge</Button>
+      </Badge>
+    </View>
+  </InstUISettingsProvider>
+
+  <div>LTR text</div>
+  <div>LTR text</div>
+</InstUISettingsProvider>
+```
+
+### Server Side Rendering support
+
+The `instanceCounterMap` prop is used for deterministic id generation. The prop accepts a [Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) (generated by the `generateInstanceCounterMap` util) that keeps the id-s of the components in sync on both the frontend and backend.
+
+See more info on the [Server Side Rendering (SSR)](/#server-side-rendering) docs page.
+
+```jsx
+import { InstUISettingsProvider } from '@instructure/emotion'
+import { generateInstanceCounterMap } from '@instructure/ui-react-utils'
+
+const counter = generateInstanceCounterMap()
+counter.set('Alert', 5)
+
+;<InstUISettingsProvider instanceCounterMap={counter}>
+  // this Alert's rendered DOM Node will have [id="Alert_5"] on it
+  <Alert>Test!</Alert>
+</InstUISettingsProvider>
+```