Merge branch 'angular:main' into accordion

Author: adolgachev

guides/theming.md

@@ -458,6 +458,81 @@ structure and CSS classes are considered private implementation details that may
 change at any time. CSS variables used by the Angular Material components should
 be defined through the `overrides` API instead of defined explicitly.
 
+## Strong focus indicators
+
+By default, most components indicate browser focus by changing their background color as described
+by the Material Design specification. This behavior, however, can fall short of accessibility
+requirements, such as [WCAG 4.5:1][], which require a stronger indication of browser focus.
+
+Angular Material supports rendering highly visible outlines on focused elements. Applications can
+enable these strong focus indicators via two Sass mixins:
+`strong-focus-indicators` and `strong-focus-indicators-theme`.
+
+The `strong-focus-indicators` mixin emits structural indicator styles for all components. This mixin
+should be included exactly once in an application, similar to the `core` mixin described above.
+
+The `strong-focus-indicators-theme` mixin emits only the indicator's color styles. This mixin should
+be included once per theme, similar to the theme mixins described above. Additionally, you can use
+this mixin to change the color of the focus indicators in situations in which the default color
+would not contrast sufficiently with the background color.
+
+The following example includes strong focus indicator styles in an application alongside the rest of
+the custom theme API.
+
+```scss
+@use '@angular/material' as mat;
+
+$my-theme: (
+  color: mat.$violet-palette,
+  typography: Roboto,
+  density: 0
+);
+
+@include mat.strong-focus-indicators();
+
+html {
+  color-scheme: light dark;
+  @include mat.theme($my-theme);
+  @include mat.strong-focus-indicators-theme($my-theme);
+}
+```
+
+### Customizing strong focus indicators
+
+You can pass a configuration map to `strong-focus-indicators` to customize the appearance of the
+indicators. This configuration includes `border-style`, `border-width`, and `border-radius`.
+
+You also can customize the color of indicators with `strong-focus-indicators-theme`. This mixin
+accepts either a theme, as described earlier in this guide, or a CSS color value. When providing a
+theme, the indicators will use the default hue of the primary palette.
+
+The following example includes strong focus indicator styles with custom settings alongside the rest
+of the custom theme API.
+
+```scss
+@use '@angular/material' as mat;
+
+@include mat.strong-focus-indicators((
+  border-style: dotted,
+  border-width: 4px,
+  border-radius: 2px,
+));
+
+html {
+  color-scheme: light dark;
+
+  @include mat.theme((
+    color: mat.$rose-palette,
+    typography: Roboto,
+    density: 0
+  ));
+
+  @include mat.strong-focus-indicators-theme(orange);
+}
+```
+
+[WCAG]: https://www.w3.org/WAI/standards-guidelines/wcag/glance/
+
 ## Shadow DOM
 
 Angular Material assumes that, by default, all theme styles are loaded as global

src/aria/accordion/accordion.ts

@@ -44,9 +44,9 @@ import {
   host: {
     'class': 'ng-accordion-panel',
     'role': 'region',
-    '[attr.id]': 'pattern.id()',
-    '[attr.aria-labelledby]': 'pattern.accordionTrigger()?.id()',
-    '[attr.inert]': 'pattern.hidden() ? true : null',
+    '[attr.id]': '_pattern.id()',
+    '[attr.aria-labelledby]': '_pattern.accordionTrigger()?.id()',
+    '[attr.inert]': '_pattern.hidden() ? true : null',
   },
 })
 export class AccordionPanel {
@@ -64,7 +64,7 @@ export class AccordionPanel {
     signal(undefined);
 
   /** The UI pattern instance for this panel. */
-  readonly pattern: AccordionPanelPattern = new AccordionPanelPattern({
+  readonly _pattern: AccordionPanelPattern = new AccordionPanelPattern({
     id: () => this._id,
     value: this.value,
     accordionTrigger: () => this.accordionTrigger(),
@@ -73,7 +73,7 @@ export class AccordionPanel {
   constructor() {
     // Connect the panel's hidden state to the DeferredContentAware's visibility.
     afterRenderEffect(() => {
-      this._deferredContentAware.contentVisible.set(!this.pattern.hidden());
+      this._deferredContentAware.contentVisible.set(!this._pattern.hidden());
     });
   }
 
@@ -102,17 +102,17 @@ export class AccordionPanel {
   exportAs: 'ngAccordionTrigger',
   host: {
     'class': 'ng-accordion-trigger',
-    '[attr.data-active]': 'pattern.active()',
+    '[attr.data-active]': '_pattern.active()',
     'role': 'button',
-    '[id]': 'pattern.id()',
-    '[attr.aria-expanded]': 'pattern.expanded()',
-    '[attr.aria-controls]': 'pattern.controls()',
-    '[attr.aria-disabled]': 'pattern.disabled()',
+    '[id]': '_pattern.id()',
+    '[attr.aria-expanded]': '_pattern.expanded()',
+    '[attr.aria-controls]': '_pattern.controls()',
+    '[attr.aria-disabled]': '_pattern.disabled()',
     '[attr.disabled]': 'hardDisabled() ? true : null',
-    '[attr.tabindex]': 'pattern.tabindex()',
-    '(keydown)': 'pattern.onKeydown($event)',
-    '(pointerdown)': 'pattern.onPointerdown($event)',
-    '(focusin)': 'pattern.onFocus($event)',
+    '[attr.tabindex]': '_pattern.tabindex()',
+    '(keydown)': '_pattern.onKeydown($event)',
+    '(pointerdown)': '_pattern.onPointerdown($event)',
+    '(focusin)': '_pattern.onFocus($event)',
   },
 })
 export class AccordionTrigger {
@@ -136,18 +136,18 @@ export class AccordionTrigger {
    *
    * TODO(ok7sai): Consider move this to UI patterns.
    */
-  readonly hardDisabled = computed(() => this.pattern.disabled() && this.pattern.tabindex() < 0);
+  readonly hardDisabled = computed(() => this._pattern.disabled() && this._pattern.tabindex() < 0);
 
   /** The accordion panel pattern controlled by this trigger. This is set by AccordionGroup. */
   readonly accordionPanel: WritableSignal<AccordionPanelPattern | undefined> = signal(undefined);
 
   /** The UI pattern instance for this trigger. */
-  readonly pattern: AccordionTriggerPattern = new AccordionTriggerPattern({
+  readonly _pattern: AccordionTriggerPattern = new AccordionTriggerPattern({
     id: () => this._id,
     value: this.value,
     disabled: this.disabled,
     element: () => this._elementRef.nativeElement,
-    accordionGroup: computed(() => this._accordionGroup.pattern),
+    accordionGroup: computed(() => this._accordionGroup._pattern),
     accordionPanel: this.accordionPanel,
   });
 
@@ -207,12 +207,12 @@ export class AccordionGroup {
   wrap = input(false, {transform: booleanAttribute});
 
   /** The UI pattern instance for this accordion group. */
-  readonly pattern: AccordionGroupPattern = new AccordionGroupPattern({
+  readonly _pattern: AccordionGroupPattern = new AccordionGroupPattern({
     ...this,
     // TODO(ok7sai): Consider making `activeItem` an internal state in the pattern and call
     // `setDefaultState` in the CDK.
     activeItem: signal(undefined),
-    items: computed(() => this._triggers().map(trigger => trigger.pattern)),
+    items: computed(() => this._triggers().map(trigger => trigger._pattern)),
     expandedIds: this.value,
     // TODO(ok7sai): Investigate whether an accordion should support horizontal mode.
     orientation: () => 'vertical',
@@ -227,9 +227,9 @@ export class AccordionGroup {
 
       for (const trigger of triggers) {
         const panel = panels.find(p => p.value() === trigger.value());
-        trigger.accordionPanel.set(panel?.pattern);
+        trigger.accordionPanel.set(panel?._pattern);
         if (panel) {
-          panel.accordionTrigger.set(trigger.pattern);
+          panel.accordionTrigger.set(trigger._pattern);
         }
       }
     });

src/aria/combobox/combobox.ts

@@ -8,6 +8,7 @@
 
 import {
   afterRenderEffect,
+  computed,
   contentChild,
   Directive,
   ElementRef,
@@ -37,12 +38,12 @@ import {toSignal} from '@angular/core/rxjs-interop';
     },
   ],
   host: {
-    '[attr.data-expanded]': 'pattern.expanded()',
-    '(input)': 'pattern.onInput($event)',
-    '(keydown)': 'pattern.onKeydown($event)',
-    '(pointerup)': 'pattern.onPointerup($event)',
-    '(focusin)': 'pattern.onFocusIn()',
-    '(focusout)': 'pattern.onFocusOut($event)',
+    '[attr.data-expanded]': 'expanded()',
+    '(input)': '_pattern.onInput($event)',
+    '(keydown)': '_pattern.onKeydown($event)',
+    '(pointerup)': '_pattern.onPointerup($event)',
+    '(focusin)': '_pattern.onFocusIn()',
+    '(focusout)': '_pattern.onFocusOut($event)',
   },
 })
 export class Combobox<V> {
@@ -81,8 +82,14 @@ export class Combobox<V> {
   /** The value of the first matching item in the popup. */
   readonly firstMatch = input<V | undefined>(undefined);
 
+  /** Whether the combobox is expanded. */
+  readonly expanded = computed(() => this._pattern.expanded());
+
+  /** Input element connected to the combobox, if any. */
+  readonly inputElement = computed(() => this._pattern.inputs.inputEl());
+
   /** The combobox ui pattern. */
-  readonly pattern = new ComboboxPattern<any, V>({
+  readonly _pattern = new ComboboxPattern<any, V>({
     ...this,
     textDirection: this.textDirection,
     disabled: this.disabled,
@@ -95,13 +102,13 @@ export class Combobox<V> {
 
   constructor() {
     afterRenderEffect(() => {
-      if (!this._deferredContentAware?.contentVisible() && this.pattern.isFocused()) {
+      if (!this._deferredContentAware?.contentVisible() && this._pattern.isFocused()) {
         this._deferredContentAware?.contentVisible.set(true);
       }
     });
 
     afterRenderEffect(() => {
-      if (!this._hasBeenFocused() && this.pattern.isFocused()) {
+      if (!this._hasBeenFocused() && this._pattern.isFocused()) {
         this._hasBeenFocused.set(true);
       }
     });
@@ -114,12 +121,12 @@ export class Combobox<V> {
   host: {
     'role': 'combobox',
     '[value]': 'value()',
-    '[attr.aria-expanded]': 'combobox.pattern.expanded()',
-    '[attr.aria-activedescendant]': 'combobox.pattern.activedescendant()',
-    '[attr.aria-controls]': 'combobox.pattern.popupId()',
-    '[attr.aria-haspopup]': 'combobox.pattern.hasPopup()',
-    '[attr.aria-autocomplete]': 'combobox.pattern.autocomplete()',
-    '[attr.readonly]': 'combobox.pattern.readonly()',
+    '[attr.aria-expanded]': 'combobox._pattern.expanded()',
+    '[attr.aria-activedescendant]': 'combobox._pattern.activedescendant()',
+    '[attr.aria-controls]': 'combobox._pattern.popupId()',
+    '[attr.aria-haspopup]': 'combobox._pattern.hasPopup()',
+    '[attr.aria-autocomplete]': 'combobox._pattern.autocomplete()',
+    '[attr.readonly]': 'combobox._pattern.readonly()',
   },
 })
 export class ComboboxInput {
@@ -133,16 +140,16 @@ export class ComboboxInput {
   value = model<string>('');
 
   constructor() {
-    (this.combobox.pattern.inputs.inputEl as WritableSignal<HTMLInputElement>).set(
+    (this.combobox._pattern.inputs.inputEl as WritableSignal<HTMLInputElement>).set(
       this._elementRef.nativeElement,
     );
-    this.combobox.pattern.inputs.inputValue = this.value;
+    this.combobox._pattern.inputs.inputValue = this.value;
 
     /** Focuses & selects the first item in the combobox if the user changes the input value. */
     afterRenderEffect(() => {
       this.value();
       this.combobox.popup()?.controls()?.items();
-      untracked(() => this.combobox.pattern.onFilter());
+      untracked(() => this.combobox._pattern.onFilter());
     });
   }
 }