polygerrit-ui/app/mixins/keyboard-shortcut-mixin/keyboard-shortcut-mixin.ts - gerrit - Git at Google

 /**
  * @license
  * Copyright (C) 2016 The Android Open Source Project
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
  * http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
 import {IronA11yKeysBehavior} from '@polymer/iron-a11y-keys-behavior/iron-a11y-keys-behavior';
 import {mixinBehaviors} from '@polymer/polymer/lib/legacy/class';
 import {property} from '@polymer/decorators';
 import {PolymerElement} from '@polymer/polymer';
 import {check, Constructor} from '../../utils/common-util';
 import {isModifierPressed} from '../../utils/dom-util';
 import {IronKeyboardEvent} from '../../types/events';
 import {appContext} from '../../services/app-context';
 import {
   Shortcut,
   ShortcutSection,
   SPECIAL_SHORTCUT,
 } from '../../services/shortcuts/shortcuts-config';
 import {
   ShortcutListener,
   SectionView,
 } from '../../services/shortcuts/shortcuts-service';

 export {
   Shortcut,
   ShortcutSection,
   SPECIAL_SHORTCUT,
   ShortcutListener,
   SectionView,
 };

 // The maximum age of a keydown event to be used in a jump navigation. This
 // is only for cases when the keyup event is lost.
 const GO_KEY_TIMEOUT_MS = 1000;

 const V_KEY_TIMEOUT_MS = 1000;

 interface IronA11yKeysMixinConstructor {
   // Note: this is needed to have same interface as other mixins
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   new (...args: any[]): IronA11yKeysBehavior;
 }
 /**
  * @polymer
  * @mixinFunction
  */
 const InternalKeyboardShortcutMixin = <
   T extends Constructor<PolymerElement> & IronA11yKeysMixinConstructor
 >(
   superClass: T
 ) => {
   /**
    * @polymer
    * @mixinClass
    */
   class Mixin extends superClass {
     @property({type: Number})
     _shortcut_go_key_last_pressed: number | null = null;

     @property({type: Number})
     _shortcut_v_key_last_pressed: number | null = null;

     @property({type: Object})
     _shortcut_go_table: Map<string, string> = new Map<string, string>();

     @property({type: Object})
     _shortcut_v_table: Map<string, string> = new Map<string, string>();

     Shortcut = Shortcut;

     ShortcutSection = ShortcutSection;

     private readonly shortcuts = appContext.shortcutsService;

     /** Used to disable shortcuts when the element is not visible. */
     private observer?: IntersectionObserver;

     /**
      * Enabling shortcuts only when the element is visible (see `observer`
      * above) is a great feature, but often what you want is for the *page* to
      * be visible, not the specific child element that registers keyboard
      * shortcuts. An example is the FileList in the ChangeView. So we allow
      * a broader observer target to be specified here, and fall back to
      * `this` as the default.
      */
     @property({type: Object})
     observerTarget: Element = this;

     /** Are shortcuts currently enabled? True only when element is visible. */
     private bindingsEnabled = false;

     modifierPressed(e: IronKeyboardEvent) {
       /* We are checking for g/v as modifiers pressed. There are cases such as
        * pressing v and then /, where we want the handler for / to be triggered.
        * TODO(dhruvsri): find a way to support that keyboard combination
        */
       return (
         isModifierPressed(e) || !!this._inGoKeyMode() || !!this.inVKeyMode()
       );
     }

     _addOwnKeyBindings(shortcut: Shortcut, handler: string) {
       const bindings = this.shortcuts.getBindingsForShortcut(shortcut);
       if (!bindings) {
         return;
       }
       if (bindings[0] === SPECIAL_SHORTCUT.DOC_ONLY) {
         return;
       }
       if (bindings[0] === SPECIAL_SHORTCUT.GO_KEY) {
         bindings
           .slice(1)
           .forEach(binding => this._shortcut_go_table.set(binding, handler));
       } else if (bindings[0] === SPECIAL_SHORTCUT.V_KEY) {
         // for each binding added with the go/v key, we set the handler to be
         // handleVKeyAction. handleVKeyAction then looks up in th
         // shortcut_table to see what the relevant handler should be
         bindings
           .slice(1)
           .forEach(binding => this._shortcut_v_table.set(binding, handler));
       } else {
         this.addOwnKeyBinding(bindings.join(' '), handler);
       }
     }

     override connectedCallback() {
       super.connectedCallback();
       this.createVisibilityObserver();
       this.enableBindings();
     }

     override disconnectedCallback() {
       this.destroyVisibilityObserver();
       this.disableBindings();
       super.disconnectedCallback();
     }

     /**
      * Creates an intersection observer that enables bindings when the
      * element is visible and disables them when the element is hidden.
      */
     private createVisibilityObserver() {
       if (!this.hasKeyboardShortcuts()) return;
       if (this.observer) return;
       this.observer = new IntersectionObserver(entries => {
         check(entries.length === 1, 'Expected one observer entry.');
         const isVisible = entries[0].isIntersecting;
         if (isVisible) {
           this.enableBindings();
         } else {
           this.disableBindings();
         }
       });
       this.observer.observe(this.observerTarget);
     }

     private destroyVisibilityObserver() {
       if (this.observer) this.observer.unobserve(this.observerTarget);
     }

     /**
      * Enables all the shortcuts returned by keyboardShortcuts().
      * This is a private method being called when the element becomes
      * connected or visible.
      */
     private enableBindings() {
       if (!this.hasKeyboardShortcuts()) return;
       if (this.bindingsEnabled) return;
       this.bindingsEnabled = true;

       const shortcuts = new Map<string, string>(
         Object.entries(this.keyboardShortcuts())
       );
       this.shortcuts.attachHost(this, shortcuts);

       for (const [key, value] of shortcuts.entries()) {
         this._addOwnKeyBindings(key as Shortcut, value);
       }

       // each component that uses this behaviour must be aware if go key is
       // pressed or not, since it needs to check it as a modifier
       this.addOwnKeyBinding('g:keydown', '_handleGoKeyDown');
       this.addOwnKeyBinding('g:keyup', '_handleGoKeyUp');

       // If any of the shortcuts utilized GO_KEY, then they are handled
       // directly by this behavior.
       if (this._shortcut_go_table.size > 0) {
         this._shortcut_go_table.forEach((_, key) => {
           this.addOwnKeyBinding(key, '_handleGoAction');
         });
       }

       this.addOwnKeyBinding('v:keydown', '_handleVKeyDown');
       this.addOwnKeyBinding('v:keyup', '_handleVKeyUp');
       if (this._shortcut_v_table.size > 0) {
         this._shortcut_v_table.forEach((_, key) => {
           this.addOwnKeyBinding(key, '_handleVAction');
         });
       }
     }

     /**
      * Disables all the shortcuts returned by keyboardShortcuts().
      * This is a private method being called when the element becomes
      * disconnected or invisible.
      */
     private disableBindings() {
       if (!this.bindingsEnabled) return;
       this.bindingsEnabled = false;
       if (this.shortcuts.detachHost(this)) {
         this.removeOwnKeyBindings();
       }
     }

     private hasKeyboardShortcuts() {
       return Object.entries(this.keyboardShortcuts()).length > 0;
     }

     keyboardShortcuts() {
       return {};
     }

     _handleVKeyDown(e: IronKeyboardEvent) {
       if (this.shortcuts.shouldSuppress(e)) return;
       this._shortcut_v_key_last_pressed = Date.now();
     }

     _handleVKeyUp() {
       setTimeout(() => {
         this._shortcut_v_key_last_pressed = null;
       }, V_KEY_TIMEOUT_MS);
     }

     private inVKeyMode() {
       return !!(
         this._shortcut_v_key_last_pressed &&
         Date.now() - this._shortcut_v_key_last_pressed <= V_KEY_TIMEOUT_MS
       );
     }

     _handleVAction(e: IronKeyboardEvent) {
       if (
         !this.inVKeyMode() ||
         !this._shortcut_v_table.has(e.detail.key) ||
         this.shortcuts.shouldSuppress(e)
       ) {
         return;
       }
       e.preventDefault();
       const handler = this._shortcut_v_table.get(e.detail.key);
       if (handler) {
         // TODO(TS): should fix this
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         (this as any)[handler](e);
       }
     }

     _handleGoKeyDown(e: IronKeyboardEvent) {
       if (this.shortcuts.shouldSuppress(e)) return;
       this._shortcut_go_key_last_pressed = Date.now();
     }

     _handleGoKeyUp() {
       // Set go_key_last_pressed to null `GO_KEY_TIMEOUT_MS` after keyup event
       // so that users can trigger `g + i` by pressing g and i quickly.
       setTimeout(() => {
         this._shortcut_go_key_last_pressed = null;
       }, GO_KEY_TIMEOUT_MS);
     }

     _inGoKeyMode() {
       return !!(
         this._shortcut_go_key_last_pressed &&
         Date.now() - this._shortcut_go_key_last_pressed <= GO_KEY_TIMEOUT_MS
       );
     }

     _handleGoAction(e: IronKeyboardEvent) {
       if (
         !this._inGoKeyMode() ||
         !this._shortcut_go_table.has(e.detail.key) ||
         this.shortcuts.shouldSuppress(e)
       ) {
         return;
       }
       e.preventDefault();
       const handler = this._shortcut_go_table.get(e.detail.key);
       if (handler) {
         // TODO(TS): should fix this
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         (this as any)[handler](e);
       }
     }
   }

   return Mixin as T &
     Constructor<
       KeyboardShortcutMixinInterface & KeyboardShortcutMixinInterfaceTesting
     >;
 };

 // The following doesn't work (IronA11yKeysBehavior crashes):
 // const KeyboardShortcutMixin = superClass => {
 //    class Mixin extends mixinBehaviors([IronA11yKeysBehavior], superClass) {
 //    ...
 //    }
 //    return Mixin;
 // }
 // This is a workaround
 export const KeyboardShortcutMixin = <T extends Constructor<PolymerElement>>(
   superClass: T
 ): T &
   Constructor<
     KeyboardShortcutMixinInterface & KeyboardShortcutMixinInterfaceTesting
   > =>
   InternalKeyboardShortcutMixin(
     // TODO(TS): mixinBehaviors in some lib is returning: `new () => T` instead
     // which will fail the type check due to missing IronA11yKeysBehavior interface
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     mixinBehaviors([IronA11yKeysBehavior], superClass) as any
   );

 /** The interface corresponding to KeyboardShortcutMixin */
 export interface KeyboardShortcutMixinInterface {
   keyboardShortcuts(): {[key: string]: string | null};
   modifierPressed(event: IronKeyboardEvent): boolean;
 }

 export interface KeyboardShortcutMixinInterfaceTesting {
   _shortcut_go_key_last_pressed: number | null;
   _shortcut_v_key_last_pressed: number | null;
   _shortcut_go_table: Map<string, string>;
   _shortcut_v_table: Map<string, string>;
   _handleGoAction: (e: IronKeyboardEvent) => void;
 }
	/**
	* @license
	* Copyright (C) 2016 The Android Open Source Project
	*
	* Licensed under the Apache License, Version 2.0 (the "License");
	* you may not use this file except in compliance with the License.
	* You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software
	* distributed under the License is distributed on an "AS IS" BASIS,
	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	* See the License for the specific language governing permissions and
	* limitations under the License.
	*/
	import {IronA11yKeysBehavior} from '@polymer/iron-a11y-keys-behavior/iron-a11y-keys-behavior';
	import {mixinBehaviors} from '@polymer/polymer/lib/legacy/class';
	import {property} from '@polymer/decorators';
	import {PolymerElement} from '@polymer/polymer';
	import {check, Constructor} from '../../utils/common-util';
	import {isModifierPressed} from '../../utils/dom-util';
	import {IronKeyboardEvent} from '../../types/events';
	import {appContext} from '../../services/app-context';
	import {
	Shortcut,
	ShortcutSection,
	SPECIAL_SHORTCUT,
	} from '../../services/shortcuts/shortcuts-config';
	import {
	ShortcutListener,
	SectionView,
	} from '../../services/shortcuts/shortcuts-service';

	export {
	Shortcut,
	ShortcutSection,
	SPECIAL_SHORTCUT,
	ShortcutListener,
	SectionView,
	};

	// The maximum age of a keydown event to be used in a jump navigation. This
	// is only for cases when the keyup event is lost.
	const GO_KEY_TIMEOUT_MS = 1000;

	const V_KEY_TIMEOUT_MS = 1000;

	interface IronA11yKeysMixinConstructor {
	// Note: this is needed to have same interface as other mixins
	// eslint-disable-next-line @typescript-eslint/no-explicit-any
	new (...args: any[]): IronA11yKeysBehavior;
	}
	/**
	* @polymer
	* @mixinFunction
	*/
	const InternalKeyboardShortcutMixin = <
	T extends Constructor<PolymerElement> & IronA11yKeysMixinConstructor
	>(
	superClass: T
	) => {
	/**
	* @polymer
	* @mixinClass
	*/
	class Mixin extends superClass {
	@property({type: Number})
	_shortcut_go_key_last_pressed: number \| null = null;

	@property({type: Number})
	_shortcut_v_key_last_pressed: number \| null = null;

	@property({type: Object})
	_shortcut_go_table: Map<string, string> = new Map<string, string>();

	@property({type: Object})
	_shortcut_v_table: Map<string, string> = new Map<string, string>();

	Shortcut = Shortcut;

	ShortcutSection = ShortcutSection;

	private readonly shortcuts = appContext.shortcutsService;

	/** Used to disable shortcuts when the element is not visible. */
	private observer?: IntersectionObserver;

	/**
	* Enabling shortcuts only when the element is visible (see `observer`
	* above) is a great feature, but often what you want is for the page to
	* be visible, not the specific child element that registers keyboard
	* shortcuts. An example is the FileList in the ChangeView. So we allow
	* a broader observer target to be specified here, and fall back to
	* `this` as the default.
	*/
	@property({type: Object})
	observerTarget: Element = this;

	/** Are shortcuts currently enabled? True only when element is visible. */
	private bindingsEnabled = false;

	modifierPressed(e: IronKeyboardEvent) {
	/* We are checking for g/v as modifiers pressed. There are cases such as
	* pressing v and then /, where we want the handler for / to be triggered.
	* TODO(dhruvsri): find a way to support that keyboard combination
	*/
	return (
	isModifierPressed(e) \|\| !!this._inGoKeyMode() \|\| !!this.inVKeyMode()
	);
	}

	_addOwnKeyBindings(shortcut: Shortcut, handler: string) {
	const bindings = this.shortcuts.getBindingsForShortcut(shortcut);
	if (!bindings) {
	return;
	}
	if (bindings[0] === SPECIAL_SHORTCUT.DOC_ONLY) {
	return;
	}
	if (bindings[0] === SPECIAL_SHORTCUT.GO_KEY) {
	bindings
	.slice(1)
	.forEach(binding => this._shortcut_go_table.set(binding, handler));
	} else if (bindings[0] === SPECIAL_SHORTCUT.V_KEY) {
	// for each binding added with the go/v key, we set the handler to be
	// handleVKeyAction. handleVKeyAction then looks up in th
	// shortcut_table to see what the relevant handler should be
	bindings
	.slice(1)
	.forEach(binding => this._shortcut_v_table.set(binding, handler));
	} else {
	this.addOwnKeyBinding(bindings.join(' '), handler);
	}
	}

	override connectedCallback() {
	super.connectedCallback();
	this.createVisibilityObserver();
	this.enableBindings();
	}

	override disconnectedCallback() {
	this.destroyVisibilityObserver();
	this.disableBindings();
	super.disconnectedCallback();
	}

	/**
	* Creates an intersection observer that enables bindings when the
	* element is visible and disables them when the element is hidden.
	*/
	private createVisibilityObserver() {
	if (!this.hasKeyboardShortcuts()) return;
	if (this.observer) return;
	this.observer = new IntersectionObserver(entries => {
	check(entries.length === 1, 'Expected one observer entry.');
	const isVisible = entries[0].isIntersecting;
	if (isVisible) {
	this.enableBindings();
	} else {
	this.disableBindings();
	}
	});
	this.observer.observe(this.observerTarget);
	}

	private destroyVisibilityObserver() {
	if (this.observer) this.observer.unobserve(this.observerTarget);
	}

	/**
	* Enables all the shortcuts returned by keyboardShortcuts().
	* This is a private method being called when the element becomes
	* connected or visible.
	*/
	private enableBindings() {
	if (!this.hasKeyboardShortcuts()) return;
	if (this.bindingsEnabled) return;
	this.bindingsEnabled = true;

	const shortcuts = new Map<string, string>(
	Object.entries(this.keyboardShortcuts())
	);
	this.shortcuts.attachHost(this, shortcuts);

	for (const [key, value] of shortcuts.entries()) {
	this._addOwnKeyBindings(key as Shortcut, value);
	}

	// each component that uses this behaviour must be aware if go key is
	// pressed or not, since it needs to check it as a modifier
	this.addOwnKeyBinding('g:keydown', '_handleGoKeyDown');
	this.addOwnKeyBinding('g:keyup', '_handleGoKeyUp');

	// If any of the shortcuts utilized GO_KEY, then they are handled
	// directly by this behavior.
	if (this._shortcut_go_table.size > 0) {
	this._shortcut_go_table.forEach((_, key) => {
	this.addOwnKeyBinding(key, '_handleGoAction');
	});
	}

	this.addOwnKeyBinding('v:keydown', '_handleVKeyDown');
	this.addOwnKeyBinding('v:keyup', '_handleVKeyUp');
	if (this._shortcut_v_table.size > 0) {
	this._shortcut_v_table.forEach((_, key) => {
	this.addOwnKeyBinding(key, '_handleVAction');
	});
	}
	}

	/**
	* Disables all the shortcuts returned by keyboardShortcuts().
	* This is a private method being called when the element becomes
	* disconnected or invisible.
	*/
	private disableBindings() {
	if (!this.bindingsEnabled) return;
	this.bindingsEnabled = false;
	if (this.shortcuts.detachHost(this)) {
	this.removeOwnKeyBindings();
	}
	}

	private hasKeyboardShortcuts() {
	return Object.entries(this.keyboardShortcuts()).length > 0;
	}

	keyboardShortcuts() {
	return {};
	}

	_handleVKeyDown(e: IronKeyboardEvent) {
	if (this.shortcuts.shouldSuppress(e)) return;
	this._shortcut_v_key_last_pressed = Date.now();
	}

	_handleVKeyUp() {
	setTimeout(() => {
	this._shortcut_v_key_last_pressed = null;
	}, V_KEY_TIMEOUT_MS);
	}

	private inVKeyMode() {
	return !!(
	this._shortcut_v_key_last_pressed &&
	Date.now() - this._shortcut_v_key_last_pressed <= V_KEY_TIMEOUT_MS
	);
	}

	_handleVAction(e: IronKeyboardEvent) {
	if (
	!this.inVKeyMode() \|\|
	!this._shortcut_v_table.has(e.detail.key) \|\|
	this.shortcuts.shouldSuppress(e)
	) {
	return;
	}
	e.preventDefault();
	const handler = this._shortcut_v_table.get(e.detail.key);
	if (handler) {
	// TODO(TS): should fix this
	// eslint-disable-next-line @typescript-eslint/no-explicit-any
	(this as any)[handler](e);
	}
	}

	_handleGoKeyDown(e: IronKeyboardEvent) {
	if (this.shortcuts.shouldSuppress(e)) return;
	this._shortcut_go_key_last_pressed = Date.now();
	}

	_handleGoKeyUp() {
	// Set go_key_last_pressed to null `GO_KEY_TIMEOUT_MS` after keyup event
	// so that users can trigger `g + i` by pressing g and i quickly.
	setTimeout(() => {
	this._shortcut_go_key_last_pressed = null;
	}, GO_KEY_TIMEOUT_MS);
	}

	_inGoKeyMode() {
	return !!(
	this._shortcut_go_key_last_pressed &&
	Date.now() - this._shortcut_go_key_last_pressed <= GO_KEY_TIMEOUT_MS
	);
	}

	_handleGoAction(e: IronKeyboardEvent) {
	if (
	!this._inGoKeyMode() \|\|
	!this._shortcut_go_table.has(e.detail.key) \|\|
	this.shortcuts.shouldSuppress(e)
	) {
	return;
	}
	e.preventDefault();
	const handler = this._shortcut_go_table.get(e.detail.key);
	if (handler) {
	// TODO(TS): should fix this
	// eslint-disable-next-line @typescript-eslint/no-explicit-any
	(this as any)[handler](e);
	}
	}
	}

	return Mixin as T &
	Constructor<
	KeyboardShortcutMixinInterface & KeyboardShortcutMixinInterfaceTesting
	>;
	};

	// The following doesn't work (IronA11yKeysBehavior crashes):
	// const KeyboardShortcutMixin = superClass => {
	// class Mixin extends mixinBehaviors([IronA11yKeysBehavior], superClass) {
	// ...
	// }
	// return Mixin;
	// }
	// This is a workaround
	export const KeyboardShortcutMixin = <T extends Constructor<PolymerElement>>(
	superClass: T
	): T &
	Constructor<
	KeyboardShortcutMixinInterface & KeyboardShortcutMixinInterfaceTesting
	> =>
	InternalKeyboardShortcutMixin(
	// TODO(TS): mixinBehaviors in some lib is returning: `new () => T` instead
	// which will fail the type check due to missing IronA11yKeysBehavior interface
	// eslint-disable-next-line @typescript-eslint/no-explicit-any
	mixinBehaviors([IronA11yKeysBehavior], superClass) as any
	);

	/** The interface corresponding to KeyboardShortcutMixin */
	export interface KeyboardShortcutMixinInterface {
	keyboardShortcuts(): {[key: string]: string \| null};
	modifierPressed(event: IronKeyboardEvent): boolean;
	}

	export interface KeyboardShortcutMixinInterfaceTesting {
	_shortcut_go_key_last_pressed: number \| null;
	_shortcut_v_key_last_pressed: number \| null;
	_shortcut_go_table: Map<string, string>;
	_shortcut_v_table: Map<string, string>;
	_handleGoAction: (e: IronKeyboardEvent) => void;
	}