Merge branch 'main' into multiselect

docs/widgets/input.md

@@ -5,7 +5,9 @@ A single-line text input widget.
 - [x] Focusable
 - [ ] Container
 
-## Example
+## Examples
+
+### A Simple Example
 
 The example below shows how you might create a simple form using two `Input` widgets.
 
@@ -20,10 +22,52 @@ The example below shows how you might create a simple form using two `Input` wid
     --8<-- "docs/examples/widgets/input.py"
     ```
 
+### Validating Input
+
+You can supply one or more *[validators][textual.validation.Validator]* to the `Input` widget to validate the value.
+
+When the value changes or the `Input` is submitted, all the supplied validators will run.
+
+Validation is considered to have failed if *any* of the validators fail.
+
+You can check whether the validation succeeded or failed inside an [Input.Changed][textual.widgets.Input.Changed] or
+[Input.Submitted][textual.widgets.Input.Submitted] handler by looking at the `validation_result` attribute on these events.
+
+In the example below, we show how to combine multiple validators and update the UI to tell the user
+why validation failed.
+Click the tabs to see the output for validation failures and successes.
+
+=== "input_validation.py"
+
+    ```python hl_lines="8-15 31-35 42-45 56-62"
+    --8<-- "docs/examples/widgets/input_validation.py"
+    ```
+
+    1. `Number` is a built-in `Validator`. It checks that the value in the `Input` is a valid number, and optionally can check that it falls within a range.
+    2. `Function` lets you quickly define custom validation constraints. In this case, we check the value in the `Input` is even.
+    3. `Palindrome` is a custom `Validator` defined below.
+    4. The `Input.Changed` event has a `validation_result` attribute which contains information about the validation that occurred when the value changed.
+    5. Here's how we can implement a custom validator which checks if a string is a palindrome. Note how the description passed into `self.failure` corresponds to the message seen on UI.
+    6. Textual offers default styling for the `-invalid` CSS class (a red border), which is automatically applied to `Input` when validation fails. We can also provide custom styling for the `-valid` class, as seen here. In this case, we add a green border around the `Input` to indicate successful validation.
+
+=== "Validation Failure"
+
+    ```{.textual path="docs/examples/widgets/input_validation.py" press="-,2,3"}
+    ```
+
+=== "Validation Success"
+
+    ```{.textual path="docs/examples/widgets/input_validation.py" press="4,4"}
+    ```
+
+Textual offers several [built-in validators][textual.validation] for common requirements,
+but you can easily roll your own by extending [Validator][textual.validation.Validator],
+as seen for `Palindrome` in the example above.
+
 ## Reactive Attributes
 
 | Name              | Type   | Default | Description                                                     |
-| ----------------- | ------ | ------- | --------------------------------------------------------------- |
+|-------------------|--------|---------|-----------------------------------------------------------------|
 | `cursor_blink`    | `bool` | `True`  | True if cursor blinking is enabled.                             |
 | `value`           | `str`  | `""`    | The value currently in the text input.                          |
 | `cursor_position` | `int`  | `0`     | The index of the cursor in the value string.                    |