feat(cdk/focus-trap) Backwards compatible factory create method (#18336)

Optionally accept a boolean instead of a ConfigurableFocusTrapConfig
object in the ConfigurableFocusTrapFactory create method, so that
it is backwards compatible with FocusTrapFactory create.

This will enable apps to turn on the new functionality with
{provide: FocusTrapFactory, useClass: ConfigurableFocusTrapFactory}.

Author: vanessanschmitt

src/cdk/a11y/focus-trap/configurable-focus-trap-config.ts

@@ -6,6 +6,14 @@
  * found in the LICENSE file at https://angular.io/license
  */
 
- export class ConfigurableFocusTrapConfig<D = any> {
+/**
+ * Configuration for creating a ConfigurableFocusTrap.
+ */
+export class ConfigurableFocusTrapConfig {
+  /**
+   * Whether to defer the creation of FocusTrap elements to be
+   * done manually by the user. Default is to create them
+   * automatically.
+   */
   defer: boolean = false;
- }
+}

src/cdk/a11y/focus-trap/configurable-focus-trap-factory.ts

@@ -41,14 +41,28 @@ export class ConfigurableFocusTrapFactory {
   /**
    * Creates a focus-trapped region around the given element.
    * @param element The element around which focus will be trapped.
-   * @param deferCaptureElements Defers the creation of focus-capturing elements to be done
-   *     manually by the user.
+   * @param config The focus trap configuration.
    * @returns The created focus trap instance.
    */
-  create(element: HTMLElement, config: ConfigurableFocusTrapConfig =
+  create(element: HTMLElement, config?: ConfigurableFocusTrapConfig): ConfigurableFocusTrap;
+
+  /**
+   * @deprecated Pass a config object instead of the `deferCaptureElements` flag.
+   * @breaking-change 11.0.0
+   */
+  create(element: HTMLElement, deferCaptureElements: boolean): ConfigurableFocusTrap;
+
+  create(element: HTMLElement, config: ConfigurableFocusTrapConfig | boolean =
     new ConfigurableFocusTrapConfig()): ConfigurableFocusTrap {
+    let configObject: ConfigurableFocusTrapConfig;
+    if (typeof config === 'boolean') {
+      configObject = new ConfigurableFocusTrapConfig();
+      configObject.defer = config;
+    } else {
+      configObject = config;
+    }
     return new ConfigurableFocusTrap(
         element, this._checker, this._ngZone, this._document, this._focusTrapManager,
-        this._inertStrategy, config);
+        this._inertStrategy, configObject);
   }
 }

tools/public_api_guard/cdk/a11y.d.ts

@@ -69,6 +69,7 @@ export declare class ConfigurableFocusTrap extends FocusTrap implements ManagedF
 export declare class ConfigurableFocusTrapFactory {
     constructor(_checker: InteractivityChecker, _ngZone: NgZone, _focusTrapManager: FocusTrapManager, _document: any, _inertStrategy?: FocusTrapInertStrategy);
     create(element: HTMLElement, config?: ConfigurableFocusTrapConfig): ConfigurableFocusTrap;
+    create(element: HTMLElement, deferCaptureElements: boolean): ConfigurableFocusTrap;
     static ɵfac: i0.ɵɵFactoryDef<ConfigurableFocusTrapFactory>;
     static ɵprov: i0.ɵɵInjectableDef<ConfigurableFocusTrapFactory>;
 }