feat(theming): enhance focus utilities with additional parameter overrides (#1549)

- feat: add `boxShadow` retention to `getFocusBoxShadow`
- fix: prevent `focusStyles` from overriding existing `styles: { boxShadow: ... }`
- feat: add `spacerHue` and `spacerShade` color overrides to `getFocusBoxShadow` and `focusStyles`

Author: jzempel

packages/theming/.size-snapshot.json

@@ -1,13 +1,13 @@
 {
   "index.cjs.js": {
-    "bundled": 20997,
-    "minified": 13418,
-    "gzipped": 5145
+    "bundled": 21255,
+    "minified": 13544,
+    "gzipped": 5198
   },
   "index.esm.js": {
-    "bundled": 20004,
-    "minified": 12515,
-    "gzipped": 5036,
+    "bundled": 20262,
+    "minified": 12641,
+    "gzipped": 5090,
     "treeshaked": {
       "rollup": {
         "code": 3918,

packages/theming/src/utils/focusStyles.spec.tsx

@@ -20,6 +20,8 @@ interface IStyledDivProps extends ThemeProps<DefaultTheme> {
   selector?: string;
   shade?: number;
   shadowWidth?: 'sm' | 'md';
+  spacerHue?: Hue;
+  spacerShade?: number;
   spacerWidth?: null | 'xs' | 'sm';
   styles?: CSSObject;
 }
@@ -76,6 +78,18 @@ describe('focusStyles', () => {
     );
   });
 
+  it('renders spacer color as expected', () => {
+    const { container } = render(<StyledDiv spacerHue="red" spacerShade={400} />);
+
+    expect(container.firstChild).toHaveStyleRule(
+      'box-shadow',
+      expect.stringContaining(`${DEFAULT_THEME.shadowWidths.xs} ${PALETTE.red[400]}`),
+      {
+        modifier: '&:focus-visible'
+      }
+    );
+  });
+
   it('renders selector as expected', () => {
     const { container } = render(<StyledDiv selector="&:focus-within" />);
 
@@ -124,8 +138,9 @@ describe('focusStyles', () => {
   });
 
   it('renders user provided styles', () => {
+    const dropShadow = DEFAULT_THEME.shadows.lg('4px', '8px', PALETTE.black);
     const { container } = render(
-      <StyledDiv styles={{ backgroundColor: 'black', color: 'white' }} />
+      <StyledDiv styles={{ backgroundColor: 'black', boxShadow: dropShadow, color: 'white' }} />
     );
 
     expect(container.firstChild).toHaveStyleRule('background-color', 'black', {
@@ -134,5 +149,12 @@ describe('focusStyles', () => {
     expect(container.firstChild).toHaveStyleRule('color', 'white', {
       modifier: '&:focus-visible'
     });
+    expect(container.firstChild).toHaveStyleRule(
+      'box-shadow',
+      expect.stringContaining(dropShadow),
+      {
+        modifier: '&:focus-visible'
+      }
+    );
   });
 });

packages/theming/src/utils/focusStyles.ts

@@ -51,13 +51,13 @@ export const focusStyles = ({
   selector = SELECTOR_FOCUS_VISIBLE,
   shadowWidth = 'md',
   spacerWidth = 'xs',
-  styles,
+  styles: { boxShadow, ...styles } = {},
   theme,
   ...options
 }: FocusStylesParameters) => {
-  const boxShadow = condition
-    ? getFocusBoxShadow({ shadowWidth, spacerWidth, theme, ...options })
-    : undefined;
+  const _boxShadow = condition
+    ? getFocusBoxShadow({ boxShadow, shadowWidth, spacerWidth, theme, ...options })
+    : boxShadow;
   let outline;
   let outlineOffset;
 
@@ -82,7 +82,7 @@ export const focusStyles = ({
     ${selector} {
       outline: ${outline}; /* [2] */
       outline-offset: ${outlineOffset};
-      box-shadow: ${boxShadow};
+      box-shadow: ${_boxShadow};
       ${styles}
     }
   `;

packages/theming/src/utils/getFocusBoxShadow.spec.ts

@@ -45,9 +45,33 @@ describe('getFocusBoxShadow', () => {
     );
   });
 
+  it('overrides spacer color as expected', () => {
+    const spacerHue = 'successHue';
+    const spacerShade = 400;
+    const boxShadow = getFocusBoxShadow({
+      theme: DEFAULT_THEME,
+      spacerHue,
+      spacerShade
+    });
+
+    expect(boxShadow).toContain(
+      `${DEFAULT_THEME.shadowWidths.xs} ${getColor(spacerHue, spacerShade, DEFAULT_THEME)}`
+    );
+  });
+
   it('knocks out spacer as expected', () => {
     const boxShadow = getFocusBoxShadow({ theme: DEFAULT_THEME, spacerWidth: null });
 
     expect(boxShadow).not.toContain(`${DEFAULT_THEME.shadowWidths.xs} ${PALETTE.white}`);
   });
+
+  it('combines with existing box-shadow as expected', () => {
+    const dropShadow = DEFAULT_THEME.shadows.lg('4px', '8px', PALETTE.black);
+    const boxShadow = getFocusBoxShadow({
+      theme: DEFAULT_THEME,
+      boxShadow: dropShadow
+    });
+
+    expect(boxShadow).toContain(dropShadow);
+  });
 });

packages/theming/src/utils/getFocusBoxShadow.ts

@@ -10,10 +10,13 @@ import { IGardenTheme } from '../types';
 import { DEFAULT_SHADE, Hue, getColor } from './getColor';
 
 export type FocusBoxShadowParameters = {
+  boxShadow?: string;
   inset?: boolean;
   hue?: Hue;
   shade?: number;
   shadowWidth?: 'sm' | 'md';
+  spacerHue?: Hue;
+  spacerShade?: number;
   spacerWidth?: null | 'xs' | 'sm';
   theme: IGardenTheme;
 };
@@ -22,21 +25,27 @@ export type FocusBoxShadowParameters = {
  * Get a CSS `box-shadow` property value for focus state styling. The `hue` and
  * `shade` are used to determine the color of the focus ring.
  *
+ * @param {string} [options.boxShadow] Provides an existing `box-shadow` (a drop shadow, for example) to be retained along with the focus ring
  * @param {boolean} [options.inset=false] Determines whether the `box-shadow` is inset
  * @param {string|Object} [options.hue='primaryHue'] Provides a theme object `palette` hue or `color` key, or any valid CSS color notation
- * @param {number} [options.shade=600] Selects a shade for the given hue
+ * @param {number} [options.shade=600] Selects a shade for the given `hue`
  * @param {string} [options.shadowWidth='md'] Provides a theme object `shadowWidth` key for the cumulative width of the `box-shadow`
+ * @param {string|Object} [options.spacerHue='background'] Provides a theme object `palette` hue or `color` key, or any valid CSS color notation
+ * @param {number} [options.spacerShade=600] Selects a shade for the given `spacerHue`
  * @param {string} [options.spacerWidth='xs'] Provides a theme object `shadowWidth` for the white spacer, or `null` to remove
  * @param {Object} options.theme Provides values used to resolve the desired color
  *
  * @returns A `box-shadow` property value for the given options. Default is a
  * 3px `blue[600]` ring with a 1px white spacer overlay.
  */
 export const getFocusBoxShadow = ({
+  boxShadow,
   inset = false,
   hue = 'primaryHue',
   shade = DEFAULT_SHADE,
   shadowWidth = 'md',
+  spacerHue = 'background',
+  spacerShade = DEFAULT_SHADE,
   spacerWidth = 'xs',
   theme = DEFAULT_THEME
 }: FocusBoxShadowParameters) => {
@@ -47,7 +56,11 @@ export const getFocusBoxShadow = ({
     return `${inset ? 'inset' : ''} ${shadow}`;
   }
 
-  return `
-    ${inset ? 'inset' : ''} ${theme.shadows[spacerWidth](theme.colors.background)},
+  const spacerColor = getColor(spacerHue, spacerShade, theme);
+
+  const retVal = `
+    ${inset ? 'inset' : ''} ${theme.shadows[spacerWidth](spacerColor!)},
     ${inset ? 'inset' : ''} ${shadow}`;
+
+  return boxShadow ? `${retVal}, ${boxShadow}` : retVal;
 };