BREAKING CHANGE(web-twig): Rename message prop to validationText in F…

…orm Fields #DS-676

 ## Migration Guide

- Instead of the `message` prop, use `validationText`.
- The `validationState` prop is now required when using `validationText`. If `validationState` is not set, `validationText` won't render.
- To show a permanent helper, use `helperText`.

 ## Other Notable Changes

- Introduce `ValidationText` component.
- Improve demos of related components.

- `<… validationState="danger" message="error" …>` → `<… validationState="danger" validationText="error" …>`
- `<… message="Check this field" …>` → `<… helperText="Check this field" …>`

List of affected components:
- Checkbox
- TextField
- TextArea
- TextFieldBase
- Select

Please refer back to these instructions or reach out to our team
if you encounter any issues during migration.

packages/web-twig/src/Resources/components/CheckboxField/CheckboxField.stories.twig

@@ -2,43 +2,79 @@
 
 {% block content %}
 
-    <script>
-        const inputs = ['checkboxfield14', 'checkboxfield15', 'checkboxfield16', 'checkboxfield17'];
+    <section class="docs-Section">
+        <h2 class="docs-Heading">Default</h2>
 
-        window.addEventListener('DOMContentLoaded', function () {
-            inputs.forEach(function (input) {
-                const checkbox = document.getElementById(input);
-                checkbox.indeterminate = true;
-            });
-        });
-    </script>
+        <div class="docs-FormFieldGrid">
+            {% include '@components/CheckboxField/stories/CheckboxFieldDefault.twig' %}
+        </div>
+    </section>
+
+    <section class="docs-Section">
+        <h2 class="docs-Heading">Indeterminate</h2>
+
+        <div class="docs-FormFieldGrid">
+            {% include '@components/CheckboxField/stories/CheckboxFieldIndeterminate.twig' %}
+        </div>
+    </section>
+
+    <section class="docs-Section">
+        <h2 class="docs-Heading">Required</h2>
 
-    <div class="docs-FormFieldGrid">
+        <div class="docs-FormFieldGrid">
+            {% include '@components/CheckboxField/stories/CheckboxFieldRequired.twig' %}
+        </div>
+    </section>
 
-        {# CheckboxField Default #}
-        {% include '@components/CheckboxField/stories/CheckboxField.twig' %}
+    <section class="docs-Section">
+        <h2 class="docs-Heading">Hidden Label</h2>
 
-        {# CheckboxField Disabled #}
-        {% include '@components/CheckboxField/stories/CheckboxFieldDisabled.twig' %}
+        <div class="docs-FormFieldGrid">
+            {% include '@components/CheckboxField/stories/CheckboxFieldHiddenLabel.twig' %}
+        </div>
+    </section>
 
-        {# CheckboxField Indeterminate State #}
-        {% include '@components/CheckboxField/stories/CheckboxFieldIndeterminate.twig' %}
+    <section class="docs-Section">
+        <h2 class="docs-Heading">Helper Text</h2>
 
-        {# CheckboxField Hidden Label #}
-        {% include '@components/CheckboxField/stories/CheckboxFieldHiddenLabel.twig' %}
+        <div class="docs-FormFieldGrid">
+            {% include '@components/CheckboxField/stories/CheckboxFieldHelperText.twig' %}
+        </div>
+    </section>
 
-        {# CheckboxField Helper Text #}
-        {% include '@components/CheckboxField/stories/CheckboxFieldHelperText.twig' %}
+    <section class="docs-Section">
+        <h2 class="docs-Heading">Disabled</h2>
 
-        {# CheckboxField Required #}
-        {% include '@components/CheckboxField/stories/CheckboxFieldRequired.twig' %}
+        <div class="docs-FormFieldGrid">
+            {% include '@components/CheckboxField/stories/CheckboxFieldDisabled.twig' %}
+        </div>
+    </section>
 
-        {# CheckboxField Item #}
-        {% include '@components/CheckboxField/stories/CheckboxFieldItem.twig' %}
+    <section class="docs-Section">
+        <h2 class="docs-Heading">Validation State with Validation Text</h2>
 
-        {# CheckboxField Validation State #}
-        {% include '@components/CheckboxField/stories/CheckboxFieldValidationState.twig' %}
+        <div class="docs-FormFieldGrid">
+            {% include '@components/CheckboxField/stories/CheckboxFieldValidation.twig' %}
+        </div>
+    </section>
 
-    </div>
+    <section class="docs-Section">
+        <h2 class="docs-Heading">Item</h2>
+
+        <div class="docs-FormFieldGrid">
+            {% include '@components/CheckboxField/stories/CheckboxFieldItem.twig' %}
+        </div>
+    </section>
+
+    <script>
+        const inputs = ['checkboxfieldIndeterminate', 'checkboxFieldDisabledIndeterminate'];
+
+        window.addEventListener('DOMContentLoaded', function () {
+            inputs.forEach(function (input) {
+                const checkbox = document.getElementById(input);
+                checkbox.indeterminate = true;
+            });
+        });
+    </script>
 
 {% endblock %}

packages/web-twig/src/Resources/components/CheckboxField/CheckboxField.twig

@@ -1,5 +1,6 @@
 {# API #}
 {%- set props = props | default([]) -%}
+{%- set _helperText = props.helperText | default(null) -%}
 {%- set _id = props.id | default(null) -%}
 {%- set _inputProps = props.inputProps | default([]) -%}
 {%- set _isChecked = props.isChecked | default(false) | boolprop -%}
@@ -8,27 +9,26 @@
 {%- set _isLabelHidden = props.isLabelHidden | default(false) | boolprop -%}
 {%- set _isRequired = props.isRequired | default(false) | boolprop -%}
 {%- set _label = props.label | default(null) -%}
-{%- set _unsafeLabel = props.UNSAFE_label | default(null) -%}
-{%- set _message = props.message | default(null) -%}
-{%- set _unsafeMessage = props.UNSAFE_message | default(null) -%}
 {%- set _name = props.name | default(null) -%}
+{%- set _unsafeHelperText = props.UNSAFE_helperText | default(null) -%}
+{%- set _unsafeLabel = props.UNSAFE_label | default(null) -%}
+{%- set _unsafeValidationText = props.UNSAFE_validationText | default(null) -%}
 {%- set _validationState = props.validationState | default(null) -%}
+{%- set _validationText = props.validationText | default(null) -%}
 {%- set _value = props.value | default(null) -%}
-{%- set _helperText = props.helperText | default(null) -%}
-{%- set _unsafeHelperText = props.UNSAFE_helperText | default(null) -%}
 
 {# Class names #}
 {%- set _inputClassName = _spiritClassPrefix ~ 'CheckboxField__input' -%}
 {%- set _labelClassName = _spiritClassPrefix ~ 'CheckboxField__label' -%}
 {%- set _labelHiddenClassName = _isLabelHidden ? _spiritClassPrefix ~ 'CheckboxField__label--hidden' : null -%}
 {%- set _labelRequiredClassName = _isRequired ? _spiritClassPrefix ~ 'CheckboxField__label--required' : null -%}
-{%- set _messageClassName = _spiritClassPrefix ~ 'CheckboxField__message' -%}
 {%- set _rootClassName = _spiritClassPrefix ~ 'CheckboxField' -%}
 {%- set _rootDisabledClassName = _isDisabled ? _spiritClassPrefix ~ 'CheckboxField--disabled' : null -%}
 {%- set _rootItemClassName = _isItem ? _spiritClassPrefix ~ 'CheckboxField--item' : null -%}
 {%- set _rootValidationStateClassName = _validationState ? _spiritClassPrefix ~ 'CheckboxField--' ~ _validationState : null -%}
 {%- set _textClassName = _spiritClassPrefix ~ 'CheckboxField__text' -%}
 {%- set _helperTextClassName = _spiritClassPrefix ~ 'CheckboxField__helperText' -%}
+{%- set _validationTextClassName = _spiritClassPrefix ~ 'CheckboxField__validationText' -%}
 
 {# Attributes #}
 {%- set _checkedAttr = _isChecked ? 'checked' : null -%}
@@ -58,31 +58,12 @@
         <span {{ classProp(_labelClassName) }}>{% if _unsafeLabel %}{{ _unsafeLabel | raw }}{% else %}{{ _label }}{% endif %}</span>
         {% if _helperText and not _unsafeHelperText %}<span class="{{ _helperTextClassName }}">{{ _helperText }}</span>{% endif %}
         {% if _unsafeHelperText %}<span class="{{ _helperTextClassName }}">{{ _unsafeHelperText | raw }}</span>{% endif %}
-        {% if _message and not _unsafeMessage %}
-            {%- if _message is iterable -%}
-                <ul class="{{ _messageClassName }}">
-                    {% for _messageItem in _message %}
-                        <li>{{ _messageItem }}</li>
-                    {% endfor %}
-                </ul>
-            {% else %}
-                <span class="{{ _messageClassName }}">
-                    {{ _message }}
-                </span>
-            {%- endif -%}
-        {% endif %}
-        {% if _unsafeMessage %}
-            {%- if _unsafeMessage is iterable -%}
-                <ul class="{{ _messageClassName }}">
-                    {% for _messageItem in _unsafeMessage %}
-                    <li>{{ _messageItem | raw }}</li>
-                    {% endfor %}
-                </ul>
-            {% else %}
-                <span class="{{ _messageClassName }}">
-                    {{ _unsafeMessage | raw }}
-                </span>
-            {%- endif -%}
-        {% endif %}
+        <ValidationText
+            className="{{ _validationTextClassName }}"
+            elementType="span"
+            validationState="{{ _validationState }}"
+            validationText="{{ _validationText }}"
+            UNSAFE_validationText="{{ _unsafeValidationText }}"
+        />
     </span>
 </label>

packages/web-twig/src/Resources/components/CheckboxField/README.md

@@ -5,18 +5,18 @@ This is Twig implementation of the [CheckboxField] component.
 Basic example usage:
 
 ```html
-<CheckboxField id="example" label="Label" name="example" />
+<CheckboxField id="checkboxfieldDefault" label="Label" name="checkboxfieldDefault" />
 ```
 
 Advanced example usage:
 
 ```html
 <CheckboxField
-  id="example2"
+  id="checkboxfieldAdvanced"
   isChecked
   isRequired
-  message="validation failed"
-  name="example2"
+  validationText="validation text"
+  name="checkboxfieldAdvanced"
   validationState="danger"
   helperText="Helper text"
 />
@@ -25,37 +25,37 @@ Advanced example usage:
 Without lexer:
 
 ```twig
-{% include "@spirit/checkboxField.twig" with { props: {
-    id: "example",
+{% embed "@spirit/checkboxField.twig" with { props: {
+    id: "checkboxfieldEmbed",
     label: "some label",
-    name: "example",
+    name: "checkboxfieldEmbed",
     isRequired: "true",
     validationState: "danger",
-    message: "validation failed",
+    validationText: "validation text",
     helperText: "Helper text",
 }} %}
 ```
 
 ## API
 
-| Prop name           | Type                                           | Default | Required | Description                                     |
-| ------------------- | ---------------------------------------------- | ------- | -------- | ----------------------------------------------- |
-| `id`                | `string`                                       | `null`  | no       | Input and label identification                  |
-| `inputProps`        | `string[]`                                     | `[]`    | no       | Pass additional attributes to the input element |
-| `isChecked`         | `bool`                                         | `false` | no       | If true, input is checked                       |
-| `isDisabled`        | `bool`                                         | `false` | no       | If true, input is disabled                      |
-| `isItem`            | `bool`                                         | `false` | no       | To render in [Item][item] mode                  |
-| `isLabelHidden`     | `bool`                                         | `false` | no       | If true, label is hidden                        |
-| `isRequired`        | `bool`                                         | `false` | no       | If true, input is required                      |
-| `label`             | `string`                                       | —       | yes\*    | Label text                                      |
-| `UNSAFE_label`      | `string`                                       | —       | yes\*    | Unescaped label text (allows HTML)              |
-| `message`           | `string`, `string[]`                           | `null`  | no\*\*   | Validation message                              |
-| `UNSAFE_message`    | `string`, `string[]`                           | `null`  | no\*\*   | Unescaped validation message                    |
-| `helperText`        | `string`                                       | `null`  | no\*\*   | Custom helper text                              |
-| `UNSAFE_helperText` | `string`                                       | `null`  | no\*\*   | Unescaped custom helper text                    |
-| `name`              | `string`                                       | `null`  | no       | Input name                                      |
-| `validationState`   | [Validation dictionary][dictionary-validation] | `null`  | no       | Type of validation state.                       |
-| `value`             | `string`                                       | `null`  | no       | Input value                                     |
+| Prop name               | Type                                           | Default | Required | Description                                     |
+| ----------------------- | ---------------------------------------------- | ------- | -------- | ----------------------------------------------- |
+| `helperText`            | `string`                                       | `null`  | no\*\*   | Custom helper text                              |
+| `id`                    | `string`                                       | `null`  | no       | Input and label identification                  |
+| `inputProps`            | `string[]`                                     | `[]`    | no       | Pass additional attributes to the input element |
+| `isChecked`             | `bool`                                         | `false` | no       | If true, input is checked                       |
+| `isDisabled`            | `bool`                                         | `false` | no       | If true, input is disabled                      |
+| `isItem`                | `bool`                                         | `false` | no       | To render in [Item][item] mode                  |
+| `isLabelHidden`         | `bool`                                         | `false` | no       | If true, label is hidden                        |
+| `isRequired`            | `bool`                                         | `false` | no       | If true, input is required                      |
+| `label`                 | `string`                                       | —       | yes\*    | Label text                                      |
+| `name`                  | `string`                                       | `null`  | no       | Input name                                      |
+| `UNSAFE_helperText`     | `string`                                       | `null`  | no\*\*   | Unescaped custom helper text                    |
+| `UNSAFE_label`          | `string`                                       | —       | yes\*    | Unescaped label text (allows HTML)              |
+| `UNSAFE_validationText` | `string`, `string[]`                           | `null`  | no\*\*   | Unescaped validation text                       |
+| `validationState`       | [Validation dictionary][dictionary-validation] | `null`  | no       | Type of validation state.                       |
+| `validationText`        | `string`, `string[]`                           | `null`  | no\*\*   | Validation text                                 |
+| `value`                 | `string`                                       | `null`  | no       | Input value                                     |
 
 \*: Label is required. You can use the `label` for simple text or `UNSAFE_label` for HTML content.
 \*\*: Props with and without `UNSAFE_` prefix are mutually exclusive.

packages/web-twig/src/Resources/components/CheckboxField/stories/CheckboxFieldDefault.twig

@@ -0,0 +1,11 @@
+<CheckboxField
+    id="checkboxfieldDefault"
+    label="Checkbox Label"
+    name="checkboxfieldDefault"
+/>
+<CheckboxField
+    id="checkboxfieldDefaultChecked"
+    isChecked
+    label="Checkbox Label"
+    name="checkboxfieldDefaultChecked"
+/>

packages/web-twig/src/Resources/components/CheckboxField/stories/CheckboxFieldDisabled.twig

@@ -1,13 +1,23 @@
 <CheckboxField
-    id="checkboxfield3"
+    id="checkboxfieldDisabled"
     isDisabled
-    label="Checkbox unselected"
-    name="checkboxfield3"
+    label="Checkbox Label"
+    name="checkboxfieldDisabled"
 />
+
 <CheckboxField
-    id="checkboxfield7"
+    helperText="Helper text"
+    id="checkboxfieldDisabledHelperText"
     isChecked
     isDisabled
-    label="Checkbox selected"
-    name="checkboxfield7"
+    isRequired
+    label="Checkbox Label"
+    name="checkboxfieldDisabledHelperText"
+/>
+
+<CheckboxField
+    id="checkboxFieldDisabledIndeterminate"
+    isDisabled
+    label="Checkbox Label"
+    name="checkboxFieldDisabledIndeterminate"
 />

packages/web-twig/src/Resources/components/CheckboxField/stories/CheckboxFieldHelperText.twig

@@ -1,58 +1,6 @@
 <CheckboxField
     helperText="Helper text"
-    id="checkboxfield20"
-    isItem
-    label="Checkbox Item with helper text"
-    name="checkboxfield20"
-/>
-<CheckboxField
-    helperText="Helper text"
-    id="checkboxfield21"
-    isChecked
-    isItem
-    label="Checkbox Item with helper text checked"
-    name="checkboxfield21"
-/>
-<CheckboxField
-    helperText="Helper text"
-    id="checkboxfield2"
-    label="Checkbox unselected with helper text"
-    name="checkboxfield2"
-/>
-<CheckboxField
-    helperText="Helper text"
-    id="checkboxfield4"
-    isDisabled
-    label="Checkbox disabled unselected with helper text"
-    name="checkboxfield4"
-/>
-<CheckboxField
-    helperText="Helper text"
-    id="checkboxfield6"
-    isChecked
-    label="Checkbox selected with helper text"
-    name="checkboxfield6"
-/>
-<CheckboxField
-    helperText="Helper text"
-    id="checkboxfield8"
-    isChecked
-    isDisabled
-    label="Checkbox disabled selected with helper text"
-    name="checkboxfield8"
-/>
-<CheckboxField
-    helperText="Helper text"
-    id="checkboxfield12"
-    isDisabled
-    isRequired
-    label="Label of disabled input"
-    name="checkboxfield12"
-/>
-<CheckboxField
-    helperText="Helper text"
-    id="checkboxfield17"
-    isDisabled
-    label="Label of input with indeterminate"
-    name="checkboxfield17"
+    id="checkboxfieldHelperText"
+    label="Checkbox Label"
+    name="checkboxfieldHelperText"
 />

packages/web-twig/src/Resources/components/CheckboxField/stories/CheckboxFieldHiddenLabel.twig

@@ -1,6 +1,6 @@
 <CheckboxField
-    id="checkboxfield10"
-    label="Label Hidden"
-    name="checkboxfield10"
-    value="Filled"
+    id="checkboxfieldHiddenLabel"
+    label="Checkbox Label"
+    name="checkboxfieldHiddenLabel"
+    isLabelHidden
 />