Rename modifiers (snake_case) | missing doc

Author: xDeSwa

src/LiveComponent/CHANGELOG.md

@@ -1,5 +1,16 @@
 # CHANGELOG
 
+## 2.28.0
+
+- `LiveComponent` Add new `data-model` modifiers:
+    - `min_length(N)`, `max_length(N)`: restrict updates based on input length
+    - `min_value(N)`, `max_value(N)`: restrict updates based on numeric value
+    - Useful with `debounce()` to avoid unnecessary Ajax requests
+
+```twig
+<input data-model="debounce(300)|min_length(3)|name" type="text">
+```
+
 ## 2.27.0
 
 -  Add events assertions in `InteractsWithLiveComponents`:

src/LiveComponent/assets/dist/live_controller.js

@@ -2364,16 +2364,16 @@ function getModelBinding (modelDirective) {
             case 'debounce':
                 debounce = modifier.value ? Number.parseInt(modifier.value) : true;
                 break;
-            case 'minlength':
+            case 'min_length':
                 minLength = modifier.value ? Number.parseInt(modifier.value) : null;
                 break;
-            case 'maxlength':
+            case 'max_length':
                 maxLength = modifier.value ? Number.parseInt(modifier.value) : null;
                 break;
-            case 'minvalue':
+            case 'min_value':
                 minValue = modifier.value ? Number.parseFloat(modifier.value) : null;
                 break;
-            case 'maxvalue':
+            case 'max_value':
                 maxValue = modifier.value ? Number.parseFloat(modifier.value) : null;
                 break;
             default:

src/LiveComponent/assets/src/Directive/get_model_binding.ts

@@ -48,22 +48,22 @@ export default function (modelDirective: Directive): ModelBinding {
 
                 break;
 
-            case 'minlength':
+            case 'min_length':
                 minLength = modifier.value ? Number.parseInt(modifier.value) : null;
 
                 break;
 
-            case 'maxlength':
+            case 'max_length':
                 maxLength = modifier.value ? Number.parseInt(modifier.value) : null;
 
                 break;
 
-            case 'minvalue':
+            case 'min_value':
                 minValue = modifier.value ? Number.parseFloat(modifier.value) : null;
 
                 break;
 
-            case 'maxvalue':
+            case 'max_value':
                 maxValue = modifier.value ? Number.parseFloat(modifier.value) : null;
 
                 break;

src/LiveComponent/assets/test/Directive/get_model_binding.test.ts

@@ -47,8 +47,8 @@ describe('get_model_binding', () => {
         });
     });
 
-    it('parses minlength and maxlength modifiers', () => {
-        const directive = parseDirectives('minlength(3)|maxlength(20)|username')[0];
+    it('parses min_length and max_length modifiers', () => {
+        const directive = parseDirectives('min_length(3)|max_length(20)|username')[0];
         expect(getModelBinding(directive)).toEqual({
             modelName: 'username',
             innerModelName: null,
@@ -62,8 +62,8 @@ describe('get_model_binding', () => {
         });
     });
 
-    it('parses minvalue and maxvalue modifiers', () => {
-        const directive = parseDirectives('minvalue(18)|maxvalue(65)|age')[0];
+    it('parses min_value and max_value modifiers', () => {
+        const directive = parseDirectives('min_value(18)|max_value(65)|age')[0];
         expect(getModelBinding(directive)).toEqual({
             modelName: 'age',
             innerModelName: null,
@@ -78,7 +78,7 @@ describe('get_model_binding', () => {
     });
 
     it('handles mixed modifiers correctly', () => {
-        const directive = parseDirectives('on(change)|norender|debounce(100)|minvalue(18)|maxvalue(65)|age:years')[0];
+        const directive = parseDirectives('on(change)|norender|debounce(100)|min_value(18)|max_value(65)|age:years')[0];
         expect(getModelBinding(directive)).toEqual({
             modelName: 'age',
             innerModelName: 'years',
@@ -93,7 +93,7 @@ describe('get_model_binding', () => {
     });
 
     it('handles empty modifier values gracefully', () => {
-        const directive = parseDirectives('minlength|maxlength|username')[0];
+        const directive = parseDirectives('min_length|max_length|username')[0];
         const binding = getModelBinding(directive);
         expect(binding.minLength).toBeNull();
         expect(binding.maxLength).toBeNull();

src/LiveComponent/assets/test/controller/model.test.ts

@@ -977,12 +977,12 @@ describe('LiveController data-model Tests', () => {
         expect(test.element).toHaveTextContent('Rating is: 5');
     });
 
-    it('does not update model if input value length is less than minlength', async () => {
+    it('does not update model if input value length is less than min_length', async () => {
         const test = await createTest(
             { username: '' },
             (data: any) => `
             <div ${initComponent(data)}>
-                <input data-model="minlength(3)|username" value="${data.username}" />
+                <input data-model="min_length(3)|username" value="${data.username}" />
                 Username: ${data.username}
             </div>
         `
@@ -994,12 +994,12 @@ describe('LiveController data-model Tests', () => {
         expect(test.component.valueStore.getOriginalProps()).toEqual({ username: '' });
     });
 
-    it('updates model if input value length satisfies minlength', async () => {
+    it('updates model if input value length satisfies min_length', async () => {
         const test = await createTest(
             { username: '' },
             (data: any) => `
             <div ${initComponent(data)}>
-                <input data-model="minlength(3)|username" value="${data.username}" />
+                <input data-model="min_length(3)|username" value="${data.username}" />
                 Username: ${data.username}
             </div>
         `
@@ -1011,12 +1011,12 @@ describe('LiveController data-model Tests', () => {
         await waitFor(() => expect(test.element).toHaveTextContent('Username: abc'));
     });
 
-    it('does not update model if input value length exceeds maxlength', async () => {
+    it('does not update model if input value length exceeds max_length', async () => {
         const test = await createTest(
             { username: '' },
             (data: any) => `
             <div ${initComponent(data)}>
-                <input data-model="maxlength(5)|username" value="${data.username}" />
+                <input data-model="max_length(5)|username" value="${data.username}" />
                 Username: ${data.username}
             </div>
         `
@@ -1026,12 +1026,12 @@ describe('LiveController data-model Tests', () => {
         expect(test.component.valueStore.getOriginalProps()).toEqual({ username: '' });
     });
 
-    it('updates model if number input value is within minvalue/maxvalue range', async () => {
+    it('updates model if number input value is within min_value/max_value range', async () => {
         const test = await createTest(
             { age: '' },
             (data: any) => `
             <div ${initComponent(data)}>
-                <input data-model="minvalue(18)|maxvalue(65)|age" type="number" />
+                <input data-model="min_value(18)|max_value(65)|age" type="number" />
                 Age: ${data.age}
             </div>
         `
@@ -1046,12 +1046,12 @@ describe('LiveController data-model Tests', () => {
         await waitFor(() => expect(test.element).toHaveTextContent('Age: 30'));
     });
 
-    it('does not update model if number input value is less than minvalue', async () => {
+    it('does not update model if number input value is less than min_value', async () => {
         const test = await createTest(
             { age: '' },
             (data: any) => `
             <div ${initComponent(data)}>
-                <input data-model="minvalue(18)|age" type="number" />
+                <input data-model="min_value(18)|age" type="number" />
                 Age: ${data.age}
             </div>
         `
@@ -1064,12 +1064,12 @@ describe('LiveController data-model Tests', () => {
         expect(test.component.valueStore.getOriginalProps()).toEqual({ age: '' });
     });
 
-    it('does not update model if number input value exceeds maxvalue', async () => {
+    it('does not update model if number input value exceeds max_value', async () => {
         const test = await createTest(
             { age: '' },
             (data: any) => `
             <div ${initComponent(data)}>
-                <input data-model="maxvalue(65)|age" type="number" />
+                <input data-model="max_value(65)|age" type="number" />
                 Age: ${data.age}
             </div>
         `

src/LiveComponent/doc/index.rst

@@ -384,6 +384,56 @@ This can be useful along with a button that triggers a render on click:
     <input data-model="norender|coupon">
     <button data-action="live#$render">Apply</button>
 
+Input Model Validation Modifiers
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. versionadded:: 2.28
+
+When binding data using the ``data-model`` directive, you can apply input validation modifiers such as:
+
+- ``min_length(<value>)``: Ensures the input length is at least the given number of characters.
+- ``max_length(<value>)``: Ensures the input length does not exceed the given number of characters.
+- ``min_value(<value>)``: Ensures the input value is not less than the given numeric value.
+- ``max_value(<value>)``: Ensures the input value is not greater than the given numeric value.
+
+These modifiers help reduce unnecessary server requests and provide a lightweight form of frontend validation.
+
+Example:
+
+.. code-block:: html
+
+    <input data-model="min_length(3)|username" type="text" value="" />
+    <input data-model="min_value(10)|max_value(100)|quantity" type="number" value="20" />
+
+In the example above:
+
+- The first input will not trigger a model update until at least 3 characters are entered.
+- The second input will only trigger updates when the number is between 10 and 100 (inclusive).
+
+Supported Input Types
+---------------------
+
+These modifiers are only evaluated on compatible input types:
+
+- ``min_length``, ``max_length``: Only valid for ``<input type="text">``, ``type="email"``, ``type="password"``, ``type="search"``, ``type="url"``, and ``<textarea>`` elements.
+- ``min_value``, ``max_value``: Only valid for ``<input type="number">``, ``type="range"``, and similar numeric fields.
+
+Combining with debounce
+-----------------------
+
+These validation modifiers can be combined with ``debounce``:
+
+.. code-block:: html
+
+    <input data-model="min_length(4)|debounce(300)|comment" type="text" />
+
+This prevents sending multiple Ajax requests for short inputs and ensures only meaningful data changes are transmitted after 300ms of inactivity. It's especially useful for reducing server load and avoiding over-rendering while typing.
+
+Why is this feature useful?
+---------------------------
+
+Imagine a user typing in a search input or numeric field. Without these modifiers, each keystroke could trigger a re-render and Ajax request. With modifiers like ``min_length(3)`` or ``min_value(5)``, you ensure that only valid, actionable data reaches the server — improving performance and user experience.
+
 Forcing a Re-Render Explicitly
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~