feat(focus): Add focus ring component.

PiperOrigin-RevId: 481651148

Author: joyzhong

Diff for: packages/material-components-web/package.json

@@ -35,6 +35,7 @@
     "@material/fab": "^14.0.0",
     "@material/feature-targeting": "^14.0.0",
     "@material/floating-label": "^14.0.0",
+    "@material/focus": "^14.0.0",
     "@material/focus-ring": "^14.0.0",
     "@material/form-field": "^14.0.0",
     "@material/icon-button": "^14.0.0",

Diff for: packages/mdc-focus/README.md

@@ -0,0 +1,38 @@
+# Focus
+
+This package contains focus-related utilities.
+
+## Focus rings
+
+To add a focus ring to an element, ensure the following requirements:
+- The focus ring should be a child of the element which it is offset from.
+- The element which the focus ring is offset from should have a
+  non-static `position` CSS value. This is because the focus ring has
+  `position: absolute` and is then positioned relative to its container
+  element.
+- The focus ring can be shown in Sass via `focus-ring-theme.show-focus-ring()`.
+
+
+See the following example:
+
+```html
+<button class="mdc-button">
+	<span>Click me!</span>
+	<div class="mdc-focus-ring"></div>
+</button>
+```
+
+```scss
+.mdc-button {
+  position: relative;
+}
+
+.mdc-focus-ring {
+  @include focus-ring-theme.static-styles();
+  @include focus-ring-theme.theme-styles(focus-ring-theme.$light-theme);
+}
+
+.mdc-button:focus-visible .mdc-focus-ring {
+  @include focus-ring-theme.show-focus-ring();
+}
+```

Diff for: packages/mdc-focus/_focus-ring-theme.scss

@@ -0,0 +1,70 @@
+@use 'sass:map';
+@use '@material/theme/keys';
+@use '@material/theme/theme';
+
+$_custom-property-prefix: 'focus-ring';
+
+$light-theme: (
+  offset-horizontal: 2px,
+  offset-vertical: 2px,
+  ring-color: 'secondary',
+  ring-border-start-start-radius: 'inherit',
+  ring-border-start-end-radius: 'inherit',
+  ring-border-end-end-radius: 'inherit',
+  ring-border-end-start-radius: 'inherit',
+  track-width: 3px,
+);
+
+@mixin theme($theme) {
+  @include theme.validate-theme($light-theme, $theme);
+  @include keys.declare-custom-properties($theme, $_custom-property-prefix);
+}
+
+@mixin theme-styles($theme) {
+  @include theme.validate-theme-styles($light-theme, $theme);
+  $theme: keys.create-theme-properties($theme, $_custom-property-prefix);
+
+  $_border-width: map.get($theme, 'track-width');
+  $_border-color: map.get($theme, 'ring-color');
+  $_border-start-start-radius: map.get(
+    $theme,
+    'ring-border-start-start-radius'
+  );
+  $_border-start-end-radius: map.get($theme, 'ring-border-start-end-radius');
+  $_border-end-end-radius: map.get($theme, 'ring-border-end-end-radius');
+  $_border-end-start-radius: map.get($theme, 'ring-border-end-start-radius');
+  $_offset-vertical: map.get($theme, 'offset-vertical');
+  $_offset-horizontal: map.get($theme, 'offset-horizontal');
+
+  @include theme.property(
+    border,
+    'border-width solid border-color',
+    $replace: (border-width: $_border-width, border-color: $_border-color)
+  );
+  @include theme.property(
+    border-start-start-radius,
+    $_border-start-start-radius
+  );
+  @include theme.property(border-start-end-radius, $_border-start-end-radius);
+  @include theme.property(border-end-end-radius, $_border-end-end-radius);
+  @include theme.property(border-end-start-radius, $_border-end-start-radius);
+  @include theme.property(
+    inset-block,
+    'calc(-1 * (offset-vertical + border-width))',
+    $replace: (offset-vertical: $_offset-vertical, border-width: $_border-width)
+  );
+  @include theme.property(
+    inset-inline,
+    'calc(-1 * (offset-horizontal + border-width))',
+    $replace: (
+      offset-horizontal: $_offset-horizontal,
+      border-width: $_border-width
+    )
+  );
+}
+
+/// This should be applied to the focus ring element when the focus ring
+/// should be shown (e.g. based on `:focus-visible` pseudoclass).
+@mixin show-focus-ring() {
+  display: block;
+}

Diff for: packages/mdc-focus/_focus-ring.scss

@@ -0,0 +1,5 @@
+@mixin static-styles() {
+  display: none;
+  pointer-events: none;
+  position: absolute;
+}

Diff for: packages/mdc-focus/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@material/focus",
+  "description": "The Material Components Web focus ring utilities",
+  "version": "14.0.0",
+  "license": "MIT",
+  "keywords": [
+    "material components",
+    "material design",
+    "focus",
+    "focusring"
+  ],
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/material-components/material-components-web.git",
+    "directory": "packages/mdc-focus"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@material/theme": "^14.0.0"
+  }
+}