Problem/Motivation
Current #states DX is the same as it is with Renderable array - developer should remember all states and conditions, nesting of the arrays, or every time refers to the documentation how to build #states array.
Proposed resolution
Create FormElementStateBuilder class that would be easy to convert into the correct array.
Multiple states and conditions also should be covered with new functionality.
Document states and conditions in the code as interfaces. It should improve DX in creating #states for the form elements.
So instead of:
'#states' => [
'visible' => [
':input[name="remote_checkbox"]' => ['checked' => TRUE],
],
],
we can use:
use Drupal\Core\Form\States\FormElementStateBuilder;
// ...
$states = new FormElementStateBuilder();
// ...
'#states' => $states->addStates(
$states->state()->setVisible(
$states->watch(':input[name="remote_checkbox"]')->isChecked(),
)
),
and use all benefits of auto-completion and documenting of the constants.
Remaining tasks
Implement API.
Add states and conditions documentation
#3022838: Document states and conditions in the code →
.
Add tests.
Update documentation to refer to the new API.
User interface changes
none
API changes
New class FormElementStatesBuilder - states container and components provider.
New class FormElementState - represent a single state which can contain multiple remote conditions
New class FormElementWatcher - container of the specific selector and expected remote condition to react.
New class FormElementWatcherConditionGroup - wrapper for Watcher instances which must be a part of AND, OR, or XOR logic.
Data model changes
none