captureKeys flag

examples/kitchen-sink/kitchen-sink.js

@@ -371,3 +371,16 @@ make( { title: 'onChange' }, gui => {
 	} );
 
 } );
+
+make( { title: '{ captureKeys: false }', captureKeys: false }, gui => {
+
+	gui.add( { String: 'I trigger window.keydown/up' }, 'String' );
+	gui.add( { Boolean: false }, 'Boolean' );
+	gui.add( { Options: 'a' }, 'Options', [ 'a', 'b', 'c' ] );
+
+	const folder = gui.addFolder( 'Folder' );
+	folder.add( { Filler: 0 }, 'Filler' );
+	folder.add( { Filler: 0 }, 'Filler' );
+	folder.add( { Filler: 0 }, 'Filler' );
+
+} );

src/Controller.js

@@ -79,10 +79,6 @@ export default class Controller {
 		this.domElement.appendChild( this.$name );
 		this.domElement.appendChild( this.$widget );
 
-		// Don't fire global key events while typing in a controller
-		this.domElement.addEventListener( 'keydown', e => e.stopPropagation() );
-		this.domElement.addEventListener( 'keyup', e => e.stopPropagation() );
-
 		this.parent.children.push( this );
 		this.parent.controllers.push( this );
 

src/GUI.js

@@ -35,6 +35,10 @@ export default class GUI {
 	 * @param {string} [options.title=Controls]
 	 * Name to display in the title bar.
 	 *
+	 * @param {boolean} [options.captureKeys=true]
+	 * Calls `stopPropagation()` on `keyup` and `keydown` events originating from the GUI. Pass
+	 * `false` to handle propagation manually.
+	 *
 	 * @param {boolean} [options.closeFolders=false]
 	 * Pass `true` to close all folders in this GUI by default.
 	 *
@@ -55,6 +59,7 @@ export default class GUI {
 		container,
 		width,
 		title = 'Controls',
+		captureKeys = true,
 		closeFolders = false,
 		injectStyles = true,
 		touchStyles = true
@@ -173,6 +178,11 @@ export default class GUI {
 			this.domElement.style.setProperty( '--width', width + 'px' );
 		}
 
+		if ( captureKeys ) {
+			this.domElement.addEventListener( 'keydown', e => e.stopPropagation() );
+			this.domElement.addEventListener( 'keyup', e => e.stopPropagation() );
+		}
+
 		this._closeFolders = closeFolders;
 
 	}

tests/capture-keys.js

@@ -0,0 +1,66 @@
+import assert from 'assert';
+import GUI from '../dist/lil-gui.esm.min.js';
+
+import CallTracker from './utils/CallTracker.js';
+
+export default () => {
+
+	const test = ( message, { captureKeys, elementToTest, expectedCalls, keyCode } ) => {
+
+		const gui = new GUI( { captureKeys } );
+
+		const keydownTracker = new CallTracker();
+		const keyupTracker = new CallTracker();
+
+		window.addEventListener( 'keydown', keydownTracker.handler );
+		window.addEventListener( 'keyup', keyupTracker.handler );
+
+		const el = elementToTest( gui );
+
+		el.$callEventListener( 'keydown', { code: keyCode } );
+		el.$callEventListener( 'keyup', { code: keyCode } );
+
+		const debug = JSON.stringify( { captureKeys, expectedCalls, keyCode }, null, 2 );
+		message = `${message}\n${debug}`;
+
+		assert.strictEqual( keydownTracker.numCalls, expectedCalls, message );
+		assert.strictEqual( keyupTracker.numCalls, expectedCalls, message );
+
+	};
+
+	test( 'key events do not propagate from controllers if captureKeys is true', {
+		captureKeys: true,
+		elementToTest: gui => gui.add( { str: '' }, 'str' ).domElement,
+		expectedCalls: 0,
+		keyCode: 'Backspace'
+	} );
+
+	test( 'captureKeys defaults to true', {
+		captureKeys: undefined,
+		elementToTest: gui => gui.add( { str: '' }, 'str' ).domElement,
+		expectedCalls: 0,
+		keyCode: 'Backspace'
+	} );
+
+	test( 'key events propagate from controllers if captureKeys is false', {
+		captureKeys: false,
+		elementToTest: gui => gui.add( { str: '' }, 'str' ).domElement,
+		expectedCalls: 1,
+		keyCode: 'Backspace'
+	} );
+
+	test( 'key events propagate from folder titles if captureKeys is false', {
+		captureKeys: false,
+		elementToTest: gui => gui.$title,
+		expectedCalls: 1,
+		keyCode: 'Backspace'
+	} );
+
+	test( 'key events do not propagate from folder titles if captureKeys is true', {
+		captureKeys: true,
+		elementToTest: gui => gui.$title,
+		expectedCalls: 0,
+		keyCode: 'Backspace'
+	} );
+
+};

tests/utils/runner.js

@@ -1,4 +1,4 @@
-import './shim.js';
+import { initShim } from './shim.js';
 import fs from 'fs';
 
 // run with --soft-fail to exit with code 0 even if tests don't pass
@@ -34,6 +34,7 @@ if ( failures > 0 ) {
 }
 
 function run( name, test ) {
+	initShim();
 	try {
 		test();
 	} catch ( e ) {

tests/utils/shim.js

@@ -1,9 +1,11 @@
 // shim just enough browser stuff to run in node
 
-// collects event listeners by name and exposes them for unit tests
-class EventTarget {
+class Element {
 
-	constructor() {
+	constructor( parentElement ) {
+		this.classList = { add() {}, remove() {}, toggle() {} };
+		this.style = { setProperty() {} };
+		this.parentElement = parentElement;
 		this.__eventListeners = {};
 	}
 
@@ -22,25 +24,38 @@ class EventTarget {
 		listeners.splice( index, 1 );
 	}
 
-	$callEventListener( name, event = {} ) {
+	$callEventListener( name, event = {}, simulatePropagation = true ) {
+
 		const listeners = this.__eventListeners[ name ];
-		if ( !listeners ) return;
-		event.preventDefault = function() {};
-		event.stopPropagation = function() {};
-		listeners.forEach( l => l( event ) );
-	}
 
-}
+		let propagate = true;
 
-class Element extends EventTarget {
-	constructor() {
-		super();
-		this.classList = { add() {}, remove() {}, toggle() {} };
-		this.style = { setProperty() {} };
-		this.parentElement = { removeChild() {} };
+		if ( !event.stopPropagation ) {
+			event.stopPropagation = () => { propagate = false; };
+		}
+
+		if ( !event.preventDefault ) {
+			event.preventDefault = () => {};
+		}
+
+		listeners?.forEach( l => l( event ) );
+
+		if ( !simulatePropagation ) return;
+
+		let parent = this.parentElement;
+		while ( propagate && parent ) {
+			parent.$callEventListener( name, event, false );
+			parent = parent.parentElement;
+		}
+
+	}
+
+	appendChild( element ) {
+		element.parentElement = this;
+	}
+	removeChild( element ) {
+		element.parentElement = undefined;
 	}
-	appendChild() {}
-	removeChild() {}
 	replaceChildren() {}
 	insertBefore() {}
 	setAttribute() {}
@@ -79,14 +94,16 @@ function createElement( tag ) {
 	return new Element();
 }
 
-global.window = new EventTarget();
-global.window.matchMedia = () => { return { matches: true }; };
-global.requestAnimationFrame = fnc => setTimeout( fnc, 100 / 6 );
-global.cancelAnimationFrame = id => clearTimeout( id );
+export function initShim() {
+	global.window = new Element();
+	global.window.matchMedia = () => { return { matches: true }; };
+	global.requestAnimationFrame = fnc => setTimeout( fnc, 100 / 6 );
+	global.cancelAnimationFrame = id => clearTimeout( id );
 
-const document = new Element();
-document.head = new Element();
-document.body = new Element();
-document.createElement = createElement;
+	const document = new Element( window );
+	document.head = new Element( document );
+	document.body = new Element( document );
+	document.createElement = createElement;
 
-global.document = document;
+	global.document = document;
+}