feat(material/focus-indicators): add config map to base focus indicators mixin, adjust default styles (#19206)

This is the first PR in a series of PRs to refresh the focus indicators API in preparation for formal documentation being added. This PR includes the following changes:

* The mixin mat-strong-focus-indicators (and the MDC equivalent) now both accept a $config map that developers can use to configure focus indicator styles (e.g. border-style, border-width, border-radius).
* I changed some of the default focus indicator styles (e.g. increased width from 2px -> 3px, updated some of the default offsets).
Future PRs will:
* Add per-component customization mixins.

Author: zelliott

.github/CODEOWNERS

@@ -45,7 +45,7 @@
 /src/material/core/common-behaviors/**             @jelbourn @devversion
 /src/material/core/datetime/**                     @mmalerba
 /src/material/core/error/**                        @crisbeto @mmalerba
-/src/material/core/focus-indicator/**              @jelbourn @zelliott
+/src/material/core/focus-indicators/**             @jelbourn @zelliott
 /src/material/core/gestures/**                     @jelbourn
 /src/material/core/label/**                        @mmalerba
 /src/material/core/line/**                         @jelbourn

src/dev-app/theme.scss

@@ -1,5 +1,5 @@
 @import '../material/core/theming/all-theme';
-@import '../material/core/focus-indicator/focus-indicator';
+@import '../material/core/focus-indicators/focus-indicators';
 @import '../material-experimental/column-resize/column-resize';
 @import '../material-experimental/mdc-helpers/mdc-helpers';
 @import '../material-experimental/mdc-theming/all-theme';

src/material-experimental/mdc-helpers/_mdc-helpers.scss

@@ -217,37 +217,55 @@ $mat-typography-level-mappings: (
 ///
 /// @example
 ///   .my-app {
-///     @include mat-mdc-strong-focus-indicators();
+///     @include mat-mdc-strong-focus-indicators($config);
 ///   }
-@mixin mat-mdc-strong-focus-indicators() {
-  // Base styles for the focus indicators.
+@mixin mat-mdc-strong-focus-indicators($config: ()) {
+  // Default focus indicator config.
+  $default-config: (
+    border-style: solid,
+    border-width: 3px,
+    border-radius: 4px,
+  );
+
+  // Merge default config with user config.
+  $config: map-merge($default-config, $config);
+  $border-style: map-get($config, border-style);
+  $border-width: map-get($config, border-width);
+  $border-radius: map-get($config, border-radius);
+
+  // Base styles for focus indicators.
   .mat-mdc-focus-indicator::before {
     @include mat-fill();
-
-    border-radius: $mat-focus-indicator-border-radius;
-    border: $mat-focus-indicator-border-width $mat-focus-indicator-border-style transparent;
     box-sizing: border-box;
     pointer-events: none;
+    border: $border-width $border-style transparent;
+    border-radius: $border-radius;
   }
 
   // By default, all focus indicators are flush with the bounding box of their
   // host element. For particular elements (listed below), default inset/offset
   // values are necessary to ensure that the focus indicator is sufficiently
   // contrastive and renders appropriately.
 
-  .mat-mdc-button-base .mat-mdc-focus-indicator::before,
+  .mat-mdc-unelevated-button .mat-mdc-focus-indicator::before,
+  .mat-mdc-raised-button .mat-mdc-focus-indicator::before,
+  .mdc-fab .mat-mdc-focus-indicator::before,
   .mat-mdc-focus-indicator.mdc-chip::before {
-    margin: $mat-focus-indicator-border-width * -2;
+    margin: -($border-width + 2px);
+  }
+
+  .mat-mdc-outlined-button .mat-mdc-focus-indicator::before {
+    margin: -($border-width + 3px);
   }
 
   .mat-mdc-focus-indicator.mat-mdc-chip-remove::before,
   .mat-mdc-focus-indicator.mat-chip-row-focusable-text-content::before {
-    margin: $mat-focus-indicator-border-width * -1;
+    margin: -$border-width;
   }
 
   .mat-mdc-focus-indicator.mat-mdc-tab::before,
   .mat-mdc-focus-indicator.mat-mdc-tab-link::before {
-    margin: $mat-focus-indicator-border-width * 2;
+    margin: 5px;
   }
 
   // Render the focus indicator on focus. Defining a pseudo element's
@@ -258,6 +276,8 @@ $mat-typography-level-mappings: (
   .mdc-checkbox__native-control:focus ~ .mat-mdc-focus-indicator::before,
   .mat-mdc-slide-toggle-focused .mat-mdc-focus-indicator::before,
   .mat-mdc-radio-button.cdk-focused .mat-mdc-focus-indicator::before,
+
+  // For buttons, render the focus indicator when the parent button is focused.
   .mat-mdc-button-base:focus .mat-mdc-focus-indicator::before,
 
   // For all other components, render the focus indicator on focus.
@@ -268,24 +288,24 @@ $mat-typography-level-mappings: (
 
 /// Mixin that sets the color of the focus indicators.
 ///
-/// @param {color|map} $themeOrMap
+/// @param {color|map} $theme-or-color
 ///   If theme, focus indicators are set to the primary color of the theme. If
 ///   color, focus indicators are set to that color.
 ///
 /// @example
 ///   .demo-dark-theme {
-///     @include mat-mdc-strong-focus-indicators-theme($darkThemeMap);
+///     @include mat-mdc-strong-focus-indicators-theme($dark-theme-map);
 ///   }
 ///
 /// @example
 ///   .demo-red-theme {
-///     @include mat-mdc-strong-focus-indicators-theme(#F00);
+///     @include mat-mdc-strong-focus-indicators-theme(#f00);
 ///   }
-@mixin mat-mdc-strong-focus-indicators-theme($themeOrColor) {
+@mixin mat-mdc-strong-focus-indicators-theme($theme-or-color) {
   .mat-mdc-focus-indicator::before {
     border-color: if(
-      type-of($themeOrColor) == 'map',
-      mat-color(map_get($themeOrColor, primary)),
-      $themeOrColor);
+      type-of($theme-or-color) == 'map',
+      mat-color(map_get($theme-or-color, primary)),
+      $theme-or-color);
   }
 }

src/material/core/focus-indicator/_focus-indicator.scss renamed to src/material/core/focus-indicators/_focus-indicators.scss

@@ -1,48 +1,60 @@
 @import '../theming/theming';
 @import '../style/layout-common';
 
-// Focus indicator styles.
-$mat-focus-indicator-border-radius: 4px;
-$mat-focus-indicator-border-width: 2px;
-$mat-focus-indicator-border-style: solid;
-
 /// Mixin that turns on strong focus indicators.
 ///
 /// @example
 ///   .my-app {
-///     @include mat-strong-focus-indicators();
+///     @include mat-strong-focus-indicators($config);
 ///   }
-@mixin mat-strong-focus-indicators() {
+@mixin mat-strong-focus-indicators($config: ()) {
+  // Default focus indicator config.
+  $default-config: (
+    border-style: solid,
+    border-width: 3px,
+    border-radius: 4px,
+  );
+
+  // Merge default config with user config.
+  $config: map-merge($default-config, $config);
+  $border-style: map-get($config, border-style);
+  $border-width: map-get($config, border-width);
+  $border-radius: map-get($config, border-radius);
 
-  // Base styles for the focus indicators.
+  // Base styles for focus indicators.
   .mat-focus-indicator::before {
     @include mat-fill();
-
-    border-radius: $mat-focus-indicator-border-radius;
-    border: $mat-focus-indicator-border-width $mat-focus-indicator-border-style transparent;
     box-sizing: border-box;
     pointer-events: none;
+    border: $border-width $border-style transparent;
+    border-radius: $border-radius;
   }
 
   // By default, all focus indicators are flush with the bounding box of their
   // host element. For particular elements (listed below), default inset/offset
   // values are necessary to ensure that the focus indicator is sufficiently
   // contrastive and renders appropriately.
 
-  .mat-focus-indicator.mat-button-base::before,
-  .mat-focus-indicator.mat-card::before,
+  .mat-focus-indicator.mat-flat-button::before,
+  .mat-focus-indicator.mat-raised-button::before,
+  .mat-focus-indicator.mat-fab::before,
+  .mat-focus-indicator.mat-mini-fab::before,
   .mat-focus-indicator.mat-chip::before,
   .mat-focus-indicator.mat-sort-header-button::before {
-    margin: $mat-focus-indicator-border-width * -2;
+    margin: -($border-width + 2px);
+  }
+
+  .mat-focus-indicator.mat-stroked-button::before {
+    margin: -($border-width + 3px);
   }
 
   .mat-focus-indicator.mat-calendar-body-cell::before {
-    margin: $mat-focus-indicator-border-width * -1;
+    margin: -$border-width;
   }
 
   .mat-focus-indicator.mat-tab-link::before,
   .mat-focus-indicator.mat-tab-label::before {
-    margin: $mat-focus-indicator-border-width * 2;
+    margin: 5px;
   }
 
   // Render the focus indicator on focus. Defining a pseudo element's
@@ -66,24 +78,24 @@ $mat-focus-indicator-border-style: solid;
 
 /// Mixin that sets the color of the focus indicators.
 ///
-/// @param {color|map} $themeOrMap
+/// @param {color|map} $theme-or-color
 ///   If theme, focus indicators are set to the primary color of the theme. If
 ///   color, focus indicators are set to that color.
 ///
 /// @example
 ///   .demo-dark-theme {
-///     @include mat-strong-focus-indicators-theme($darkThemeMap);
+///     @include mat-strong-focus-indicators-theme($dark-theme-map);
 ///   }
 ///
 /// @example
 ///   .demo-red-theme {
-///     @include mat-strong-focus-indicators-theme(#F00);
+///     @include mat-strong-focus-indicators-theme(#f00);
 ///   }
-@mixin mat-strong-focus-indicators-theme($themeOrColor) {
+@mixin mat-strong-focus-indicators-theme($theme-or-color) {
   .mat-focus-indicator::before {
     border-color: if(
-      type-of($themeOrColor) == 'map',
-      mat-color(map_get($themeOrColor, primary)),
-      $themeOrColor);
+      type-of($theme-or-color) == 'map',
+      mat-color(map_get($theme-or-color, primary)),
+      $theme-or-color);
   }
 }