refactor: event managers

Author: wagnermaciel

src/cdk-experimental/listbox/listbox.ts

@@ -15,8 +15,6 @@ import {
   inject,
   input,
   model,
-  OnDestroy,
-  signal,
 } from '@angular/core';
 import {ListboxPattern, OptionPattern} from '@angular/cdk-experimental/ui-patterns';
 import {Directionality} from '@angular/cdk/bidi';

src/cdk-experimental/ui-patterns/behaviors/event-manager/event-manager.ts

@@ -28,16 +28,19 @@ export interface EventHandlerOptions {
   preventDefault: boolean;
 }
 
-/**
- * A config that specifies how to handle a particular event.
- */
+/** A basic event handler. */
+export type EventHandler<T extends Event> = (event: T) => void;
+
+/** A function that determines whether an event is to be handled. */
+export type EventMatcher<T extends Event> = (event: T) => boolean;
+
+/** A config that specifies how to handle a particular event. */
 export interface EventHandlerConfig<T extends Event> extends EventHandlerOptions {
-  handler: (event: T) => boolean | void;
+  matcher: EventMatcher<T>;
+  handler: EventHandler<T>;
 }
 
-/**
- * Bit flag representation of the possible modifier keys that can be present on an event.
- */
+/** Bit flag representation of the possible modifier keys that can be present on an event. */
 export enum ModifierKey {
   None = 0,
   Ctrl = 0b1,
@@ -46,134 +49,40 @@ export enum ModifierKey {
   Meta = 0b1000,
 }
 
+export type ModifierInputs = ModifierKey | ModifierKey[];
+
 /**
  * Abstract base class for all event managers.
  *
  * Event managers are designed to normalize how event handlers are authored and create a safety net
  * for common event handling gotchas like remembering to call preventDefault or stopPropagation.
  */
 export abstract class EventManager<T extends Event> {
-  private _submanagers: EventManager<T>[] = [];
-
   protected configs: EventHandlerConfig<T>[] = [];
-  protected beforeFns: ((event: T) => void)[] = [];
-  protected afterFns: ((event: T) => void)[] = [];
+  abstract options: EventHandlerOptions;
 
-  protected defaultHandlerOptions: EventHandlerOptions = {
-    preventDefault: false,
-    stopPropagation: false,
-  };
+  /** Runs the handlers that match with the given event. */
+  handle(event: T): void {
+    for (const config of this.configs) {
+      if (config.matcher(event)) {
+        config.handler(event);
 
-  constructor(defaultHandlerOptions?: Partial<EventHandlerOptions>) {
-    this.defaultHandlerOptions = {
-      ...this.defaultHandlerOptions,
-      ...defaultHandlerOptions,
-    };
-  }
-
-  /**
-   * Composes together multiple event managers into a single event manager that delegates to the
-   * individual managers.
-   */
-  static compose<T extends Event>(...managers: EventManager<T>[]) {
-    const composedManager = new GenericEventManager<T>();
-    composedManager._submanagers = managers;
-    return composedManager;
-  }
+        if (config.preventDefault) {
+          event.preventDefault();
+        }
 
-  /**
-   * Runs any handlers that have been configured to handle this event. If multiple handlers are
-   * configured for this event, they are run in the order they were configured. Returns
-   * `true` if the event has been handled, otherwise returns `undefined`.
-   *
-   * Note: the use of `undefined` instead of `false` in the unhandled case is necessary to avoid
-   * accidentally preventing the default behavior on an unhandled event.
-   */
-  handle(event: T): true | undefined {
-    if (!this.isHandled(event)) {
-      return undefined;
-    }
-    for (const fn of this.beforeFns) {
-      fn(event);
-    }
-    for (const submanager of this._submanagers) {
-      submanager.handle(event);
-    }
-    for (const config of this.getHandlersForKey(event)) {
-      config.handler(event);
-      if (config.stopPropagation) {
-        event.stopPropagation();
+        if (config.stopPropagation) {
+          event.stopPropagation();
+        }
       }
-      if (config.preventDefault) {
-        event.preventDefault();
-      }
-    }
-    for (const fn of this.afterFns) {
-      fn(event);
     }
-    return true;
   }
 
-  /**
-   * Configures the event manager to run a function immediately before it as about to handle
-   * any event.
-   */
-  beforeHandling(fn: (event: T) => void): this {
-    this.beforeFns.push(fn);
-    return this;
-  }
-
-  /**
-   * Configures the event manager to run a function immediately after it handles any event.
-   */
-  afterHandling(fn: (event: T) => void): this {
-    this.afterFns.push(fn);
-    return this;
-  }
-
-  /**
-   * Configures the event manager to handle specific events. (See subclasses for more).
-   */
+  /** Configures the event manager to handle specific events. (See subclasses for more). */
   abstract on(...args: [...unknown[]]): this;
-
-  /**
-   * Gets all of the handler configs that are applicable to the given event.
-   */
-  protected abstract getHandlersForKey(event: T): EventHandlerConfig<T>[];
-
-  /**
-   * Checks whether this event manager is confugred to handle the given event.
-   */
-  protected isHandled(event: T): boolean {
-    return (
-      this.getHandlersForKey(event).length > 0 || this._submanagers.some(sm => sm.isHandled(event))
-    );
-  }
-}
-
-/**
- * A generic event manager that can work with any type of event.
- */
-export class GenericEventManager<T extends Event> extends EventManager<T> {
-  /**
-   * Configures this event manager to handle all events with the given handler.
-   */
-  on(handler: (event: T) => boolean | void): this {
-    this.configs.push({
-      ...this.defaultHandlerOptions,
-      handler,
-    });
-    return this;
-  }
-
-  getHandlersForKey(_event: T): EventHandlerConfig<T>[] {
-    return this.configs;
-  }
 }
 
-/**
- * Gets bit flag representation of the modifier keys present on the given event.
- */
+/** Gets bit flag representation of the modifier keys present on the given event. */
 export function getModifiers(event: EventWithModifiers): number {
   return (
     (+event.ctrlKey && ModifierKey.Ctrl) |
@@ -187,7 +96,7 @@ export function getModifiers(event: EventWithModifiers): number {
  * Checks if the given event has modifiers that are an exact match for any of the given modifier
  * flag combinations.
  */
-export function hasModifiers(event: EventWithModifiers, modifiers: number | number[]): boolean {
+export function hasModifiers(event: EventWithModifiers, modifiers: ModifierInputs): boolean {
   const eventModifiers = getModifiers(event);
   const modifiersList = Array.isArray(modifiers) ? modifiers : [modifiers];
   return modifiersList.some(modifiers => eventModifiers === modifiers);

src/cdk-experimental/ui-patterns/behaviors/event-manager/keyboard-event-manager.ts

@@ -8,92 +8,68 @@
 
 import {Signal} from '@angular/core';
 import {
-  EventHandlerConfig,
+  EventHandler,
   EventHandlerOptions,
   EventManager,
   hasModifiers,
+  ModifierInputs,
   ModifierKey,
 } from './event-manager';
 
 /**
- * A config that specifies how to handle a particular keyboard event.
+ * Used to represent a keycode.
+ *
+ * This is used to match whether an events keycode should be handled. The ability to match using a
+ * string, Signal, or Regexp gives us more flexibility when authoring event handlers.
  */
-export interface KeyboardEventHandlerConfig extends EventHandlerConfig<KeyboardEvent> {
-  key: string | Signal<string> | RegExp;
-  modifiers: number | number[];
-}
+type KeyCode = string | Signal<string> | RegExp;
 
 /**
  * An event manager that is specialized for handling keyboard events. By default this manager stops
  * propagation and prevents default on all events it handles.
  */
-export class KeyboardEventManager extends EventManager<KeyboardEvent> {
-  override configs: KeyboardEventHandlerConfig[] = [];
-
-  protected override defaultHandlerOptions: EventHandlerOptions = {
+export class KeyboardEventManager<T extends KeyboardEvent> extends EventManager<T> {
+  options: EventHandlerOptions = {
     preventDefault: true,
     stopPropagation: true,
   };
 
-  /**
-   * Configures this event manager to handle events with a specific modifer and key combination.
-   *
-   * @param modifiers The modifier combinations that this handler should run for.
-   * @param key The key that this handler should run for (or a predicate function that takes the
-   *   event's key and returns whether to run this handler).
-   * @param handler The handler function
-   * @param options Options for whether to stop propagation or prevent default.
-   */
-  on(
-    modifiers: number | number[],
-    key: string | Signal<string> | RegExp,
-    handler: ((event: KeyboardEvent) => void) | ((event: KeyboardEvent) => boolean),
-    options?: Partial<EventHandlerOptions>,
-  ): this;
+  /** Configures this event manager to handle events with a specific key and no modifiers. */
+  on(key: KeyCode, handler: EventHandler<T>): this;
 
-  /**
-   * Configures this event manager to handle events with a specific key and no modifiers.
-   *
-   * @param key The key that this handler should run for (or a predicate function that takes the
-   *   event's key and returns whether to run this handler).
-   * @param handler The handler function
-   * @param options Options for whether to stop propagation or prevent default.
-   */
-  on(
-    key: string | Signal<string> | RegExp,
-    handler: ((event: KeyboardEvent) => void) | ((event: KeyboardEvent) => boolean),
-    options?: Partial<EventHandlerOptions>,
-  ): this;
+  /**  Configures this event manager to handle events with a specific modifer and key combination. */
+  on(modifiers: ModifierInputs, key: KeyCode, handler: EventHandler<T>): this;
 
   on(...args: any[]) {
-    const key = args.length === 3 ? args[1] : args[0];
-    const handler = args.length === 3 ? args[2] : args[1];
-    const modifiers = args.length === 3 ? args[0] : ModifierKey.None;
-
-    // TODO: Add strict type checks again when finalizing this API.
+    const {modifiers, key, handler} = this._normalizeInputs(...args);
 
     this.configs.push({
-      key,
-      handler,
-      modifiers,
-      ...this.defaultHandlerOptions,
+      handler: handler,
+      matcher: event => this._isMatch(event, key, modifiers),
+      ...this.options,
     });
 
     return this;
   }
 
-  getHandlersForKey(event: KeyboardEvent) {
-    return this.configs.filter(config => this._isKeyMatch(config, event));
-  }
+  private _normalizeInputs(...args: any[]) {
+    const key = args.length === 3 ? args[1] : args[0];
+    const handler = args.length === 3 ? args[2] : args[1];
+    const modifiers = args.length === 3 ? args[0] : ModifierKey.None;
 
-  // TODO: Make modifiers accept a signal as well.
+    return {
+      key: key as KeyCode,
+      handler: handler as EventHandler<T>,
+      modifiers: modifiers as ModifierInputs,
+    };
+  }
 
-  private _isKeyMatch(config: KeyboardEventHandlerConfig, event: KeyboardEvent) {
-    if (config.key instanceof RegExp) {
-      return config.key.test(event.key);
+  private _isMatch(event: T, key: KeyCode, modifiers: ModifierInputs) {
+    if (key instanceof RegExp) {
+      return key.test(event.key);
     }
 
-    const key = typeof config.key === 'string' ? config.key : config.key();
-    return key.toLowerCase() === event.key.toLowerCase() && hasModifiers(event, config.modifiers);
+    const keyStr = typeof key === 'string' ? key : key();
+    return keyStr.toLowerCase() === event.key.toLowerCase() && hasModifiers(event, modifiers);
   }
 }