feat(theming): add :focus-visible scoping <div> knock-out option to T…

…hemeProvider (#897)

packages/theming/.size-snapshot.json

@@ -1,20 +1,20 @@
 {
   "index.cjs.js": {
-    "bundled": 22430,
-    "minified": 14157,
-    "gzipped": 5188
+    "bundled": 22511,
+    "minified": 14210,
+    "gzipped": 5201
   },
   "index.esm.js": {
-    "bundled": 21591,
-    "minified": 13393,
-    "gzipped": 5068,
+    "bundled": 21652,
+    "minified": 13429,
+    "gzipped": 5080,
     "treeshaked": {
       "rollup": {
         "code": 3408,
         "import_statements": 146
       },
       "webpack": {
-        "code": 7327
+        "code": 7361
       }
     }
   }

packages/theming/src/elements/ThemeProvider.spec.tsx

@@ -0,0 +1,28 @@
+/**
+ * Copyright Zendesk, Inc.
+ *
+ * Use of this source code is governed under the Apache License, Version 2.0
+ * found at http://www.apache.org/licenses/LICENSE-2.0.
+ */
+
+import React from 'react';
+import { render } from 'garden-test-utils';
+import ThemeProvider from './ThemeProvider';
+
+describe('ThemeProvider', () => {
+  it('renders a :focus-visible scoping <div> by default', () => {
+    const { container } = render(<ThemeProvider />);
+
+    expect(container.firstChild!.nodeName).toBe('DIV');
+  });
+
+  it('only renders children when focusVisibleRef is null', () => {
+    const { container } = render(
+      <ThemeProvider focusVisibleRef={null}>
+        <button />
+      </ThemeProvider>
+    );
+
+    expect(container.firstChild!.nodeName).toBe('BUTTON');
+  });
+});

packages/theming/src/elements/ThemeProvider.tsx

@@ -13,7 +13,19 @@ import DEFAULT_THEME from './theme';
 import { useDocument } from '../utils/useDocument';
 
 interface IGardenThemeProviderProps extends Partial<ThemeProps<DefaultTheme>> {
-  focusVisibleRef?: React.RefObject<HTMLElement>;
+  /**
+   * Provides values for component styling. See styled-components
+   * [`ThemeProvider`](https://styled-components.com/docs/api#themeprovider)
+   * for details.
+   */
+  theme?: DefaultTheme;
+  /**
+   * Provides a reference to the DOM node used to scope a `:focus-visible`
+   * polyfill. If left `undefined`, a scoping `<div>` will be rendered.
+   * Assigning `null` (on a nested `ThemeProvider`, for example) prevents the
+   * added polyfill and scoping `<div>`.
+   */
+  focusVisibleRef?: React.RefObject<HTMLElement> | null;
 }
 
 const GardenThemeProvider: React.FunctionComponent<IGardenThemeProviderProps> = ({
@@ -24,13 +36,18 @@ const GardenThemeProvider: React.FunctionComponent<IGardenThemeProviderProps> =
 }) => {
   const scopeRef = useRef<HTMLDivElement>(null);
   const relativeDocument = useDocument(theme);
-  const controlledScopeRef = getControlledValue(focusVisibleRef, scopeRef);
+  const controlledScopeRef =
+    focusVisibleRef === null ? React.createRef() : getControlledValue(focusVisibleRef, scopeRef);
 
   useFocusVisible({ scope: controlledScopeRef, relativeDocument });
 
   return (
     <ThemeProvider theme={theme!} {...other}>
-      {focusVisibleRef ? (children as any) : <div ref={scopeRef}>{children as any}</div>}
+      {focusVisibleRef === undefined ? (
+        <div ref={scopeRef}>{children as any}</div>
+      ) : (
+        (children as any)
+      )}
     </ThemeProvider>
   );
 };
@@ -39,5 +56,4 @@ GardenThemeProvider.defaultProps = {
   theme: DEFAULT_THEME
 };
 
-/** @component */
 export default GardenThemeProvider;

packages/theming/styleguide.config.js

@@ -28,7 +28,7 @@ module.exports = {
       content: '../../packages/theming/README.md'
     },
     {
-      name: 'Elements',
+      name: 'Examples',
       sections: [
         {
           name: 'ThemeProvider',
@@ -44,6 +44,10 @@ module.exports = {
         }
       ]
     },
+    {
+      name: 'Elements',
+      components: '../../packages/theming/src/elements/[A-Z]*.{ts,tsx}'
+    },
     {
       name: 'Utils',
       components: '../../packages/theming/src/utils/*.{ts,tsx}'