Introduce command#disable() and command#enable()

[scofalik]

Current status on March 6, 2023

At the time of writing, Command#disable() and Command#enable() got replaced by Command#forceDisabled() and
Command#clearForceDisabled() and those are the correct way to disable or enable the command in the CKEditor 5.

Usage example:

command.isEnabled; // -> true
command.forceDisabled( 'MyFeature' );
command.isEnabled; // -> false
command.clearForceDisabled( 'MyFeature' );
command.isEnabled; // -> true

More details and examples are available in API docs:

• forceDisabled()
• clearForceDisabled()

Original issue

More and more features are using "disable all/most commands" functionality (mostly in collaboration features though). It leads to duplicating a lot of code. Additionally, it is not really intuitive to disable a command through listening to isEnabled.

Hence, I propose to add this functionality to Command API. Of course, it will need to handle multiple disabling, so one algorithm will not re-enable lock set in another algorithm. This can be simply handled through passing identifiers.

command.disable( 'myFeature' );
// ...
command.enable( 'myFeature' );

I think this is a better solution that returning enabling callback:

const enable = command.disable();
// ...
enable();

Because of how we use disabling:

// Disable all commands.
for ( const command of this.editor.commands.commands() ) {
	// Will become `command.disable( 'id' );`.
	command.on( 'set:isEnabled', forceDisable, { priority: 'highest' } );
	command.isEnabled = false;
}
// ...
for ( const command of this.editor.commands.commands() ) {
	// Will become `command.enable( 'id' );`.
	command.off( 'set:isEnabled', forceDisable );
	command.refresh();
}

If callback would be returned we would have to store all of them which doesn't make sense.

[scofalik]

When this ticket is done, we should use this new API in places where we already use commands disabling.

[Reinmar]

Please correct the docs:

1. An example would be great
2. Let's not talk about "disable stack" cause neither is this precise, nor IMO helps understanding how it works. I'd focus on explaining it shortly that a command can be disabled by multiple features (which should pass a unique id to the disable() method – e.g. the plugin name) and it will only be enabled back if all the features which disabled it enable it via enable(). Just that. Plus an example like this:

command.isEnabled; // -> true
command.disable( 'MyFeature' );
command.isEnabled; // -> false

command.enable( 'MyFeature' );
command.isEnabled; // -> true

Command disabled by multiple features:

command.disable( 'MyFeature' );
command.disable( 'OtherFeature' );

command.enable( 'MyFeature' );
command.isEnabled; // -> false

command.enable( 'OtherFeature' );
command.isEnabled; // -> true

Note: After a command is enabled, its refresh() logic decides whether isEnabled will be true. So, it may happen that the command will still be disabled.

BTW, the last sentence shows that disable()/enable() may not be the best naming.