Merge branch 'main' of github.com:Textualize/textual into docs-updates-11sep24

Author: darrenburns

CHANGELOG.md

@@ -9,16 +9,27 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ### Added
 
+- Added `MaskedInput` widget https://github.com/Textualize/textual/pull/4783
 - Input validation for floats and integers accept embedded underscores, e.g., "1_234_567" is valid. https://github.com/Textualize/textual/pull/4784
+- Support for `"none"` value added to `dock`, `hatch` and `split` styles https://github.com/Textualize/textual/pull/4982
+- Support for `"none"` added to box and border style properties (e.g `widget.style.border = "none"`) https://github.com/Textualize/textual/pull/4982
+- Docstrings added to most style properties https://github.com/Textualize/textual/pull/4982
 
 ### Changed
 
 - Input validation for integers no longer accepts scientific notation like '1.5e2'; must be castable to int. https://github.com/Textualize/textual/pull/4784
+- Default `scrollbar-size-vertical` changed to `2` in inline styles to match Widget default CSS (unlikely to affect users) https://github.com/Textualize/textual/pull/4982
+- Removed border-right from `Toast` https://github.com/Textualize/textual/pull/4984
+- Some fixes in `RichLog` result in slightly different semantics, see docstrings for details https://github.com/Textualize/textual/pull/4978
 
 ### Fixed
 
 - Input validation of floats no longer accepts NaN (not a number). https://github.com/Textualize/textual/pull/4784
 - Fixed issues with screenshots by simplifying segments only for snapshot tests https://github.com/Textualize/textual/issues/4929
+- Fixed `RichLog.write` not respecting `width` parameter https://github.com/Textualize/textual/pull/4978
+- Fixed `RichLog` writing at wrong width when `write` occurs before width is known (e.g. in `compose` or `on_mount`) https://github.com/Textualize/textual/pull/4978
+- Fixed `RichLog.write` incorrectly shrinking width to `RichLog.min_width` when `shrink=True` (now shrinks to fit content area instead) https://github.com/Textualize/textual/pull/4978
+- Fixed flicker when setting `dark` reactive on startup https://github.com/Textualize/textual/pull/4989
 
 ## [0.79.1] - 2024-08-31
 
@@ -107,6 +118,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 - Fixed issue with Enter events causing unresponsive UI https://github.com/Textualize/textual/pull/4833
 
+
 ## [0.75.0] - 2024-08-01
 
 ### Added

docs/examples/widgets/masked_input.py

@@ -0,0 +1,32 @@
+from textual.app import App, ComposeResult
+from textual.widgets import Label, MaskedInput
+
+
+class MaskedInputApp(App):
+    # (1)!
+    CSS = """
+    MaskedInput.-valid {
+        border: tall $success 60%;
+    }
+    MaskedInput.-valid:focus {
+        border: tall $success;
+    }
+    MaskedInput {
+        margin: 1 1;
+    }
+    Label {
+        margin: 1 2;
+    }
+    """
+
+    def compose(self) -> ComposeResult:
+        yield Label("Enter a valid credit card number.")
+        yield MaskedInput(
+            template="9999-9999-9999-9999;0",  # (2)!
+        )
+
+
+app = MaskedInputApp()
+
+if __name__ == "__main__":
+    app.run()

docs/widget_gallery.md

@@ -168,6 +168,16 @@ Display a markdown document.
 ```{.textual path="docs/examples/widgets/markdown.py"}
 ```
 
+## MaskedInput
+
+A control to enter input according to a template mask.
+
+[MaskedInput reference](./widgets/masked_input.md){ .md-button .md-button--primary }
+
+
+```{.textual path="docs/examples/widgets/masked_input.py"}
+```
+
 ## OptionList
 
 Display a vertical list of options (options may be Rich renderables).

docs/widgets/masked_input.md

@@ -0,0 +1,84 @@
+# MaskedInput
+
+!!! tip "Added in version 0.80.0"
+
+A masked input derived from `Input`, allowing to restrict user input and give visual aid via a simple template mask, which also acts as an implicit *[validator][textual.validation.Validator]*.
+
+- [x] Focusable
+- [ ] Container
+
+## Example
+
+The example below shows a masked input to ease entering a credit card number.
+
+=== "Output"
+
+    ```{.textual path="docs/examples/widgets/masked_input.py"}
+    ```
+
+=== "checkbox.py"
+
+    ```python
+    --8<-- "docs/examples/widgets/masked_input.py"
+    ```
+
+## Reactive Attributes
+
+| Name       | Type  | Default | Description               |
+| ---------- | ----- | ------- | ------------------------- |
+| `template` | `str` | `""`    | The template mask string. |
+
+### The template string format
+
+A `MaskedInput` template length defines the maximum length of the input value. Each character of the mask defines a regular expression used to restrict what the user can insert in the corresponding position, and whether the presence of the character in the user input is required for the `MaskedInput` value to be considered valid, according to the following table:
+
+| Mask character | Regular expression | Required? |
+| -------------- | ------------------ | --------- |
+| `A`            | `[A-Za-z]`         | Yes       |
+| `a`            | `[A-Za-z]`         | No        |
+| `N`            | `[A-Za-z0-9]`      | Yes       |
+| `n`            | `[A-Za-z0-9]`      | No        |
+| `X`            | `[^ ]`             | Yes       |
+| `x`            | `[^ ]`             | No        |
+| `9`            | `[0-9]`            | Yes       |
+| `0`            | `[0-9]`            | No        |
+| `D`            | `[1-9]`            | Yes       |
+| `d`            | `[1-9]`            | No        |
+| `#`            | `[0-9+\-]`         | No        |
+| `H`            | `[A-Fa-f0-9]`      | Yes       |
+| `h`            | `[A-Fa-f0-9]`      | No        |
+| `B`            | `[0-1]`            | Yes       |
+| `b`            | `[0-1]`            | No        |
+
+There are some special characters that can be used to control automatic case conversion during user input: `>` converts all subsequent user input to uppercase; `<` to lowercase; `!` disables automatic case conversion. Any other character that appears in the template mask is assumed to be a separator, which is a character that is automatically inserted when user reaches its position. All mask characters can be escaped by placing `\` in front of them, allowing any character to be used as separator.
+The mask can be terminated by `;c`, where `c` is any character you want to be used as placeholder character. The `placeholder` parameter inherited by `Input` can be used to override this allowing finer grain tuning of the placeholder string.
+
+## Messages
+
+- [MaskedInput.Changed][textual.widgets.MaskedInput.Changed]
+- [MaskedInput.Submitted][textual.widgets.MaskedInput.Submitted]
+
+## Bindings
+
+The masked input widget defines the following bindings:
+
+::: textual.widgets.MaskedInput.BINDINGS
+    options:
+      show_root_heading: false
+      show_root_toc_entry: false
+
+## Component Classes
+
+The masked input widget provides the following component classes:
+
+::: textual.widgets.MaskedInput.COMPONENT_CLASSES
+    options:
+      show_root_heading: false
+      show_root_toc_entry: false
+
+---
+
+
+::: textual.widgets.MaskedInput
+    options:
+      heading_level: 2

mkdocs-nav.yml

@@ -157,6 +157,7 @@ nav:
           - "widgets/log.md"
           - "widgets/markdown_viewer.md"
           - "widgets/markdown.md"
+          - "widgets/masked_input.md"
           - "widgets/option_list.md"
           - "widgets/placeholder.md"
           - "widgets/pretty.md"

src/textual/_arrange.py

@@ -16,7 +16,7 @@
 TOP_Z = 2**31 - 1
 
 
-def _build_dock_layers(widgets: Iterable[Widget]) -> Mapping[str, Sequence[Widget]]:
+def _build_layers(widgets: Iterable[Widget]) -> Mapping[str, Sequence[Widget]]:
     """Organize widgets into layers.
 
     Args:
@@ -47,17 +47,19 @@ def arrange(
 
     placements: list[WidgetPlacement] = []
     scroll_spacing = Spacing()
-    get_dock = attrgetter("styles.dock")
-    get_split = attrgetter("styles.split")
+
+    get_dock = attrgetter("styles.is_docked")
+    get_split = attrgetter("styles.is_split")
+
     styles = widget.styles
 
     # Widgets which will be displayed
     display_widgets = [child for child in children if child.styles.display != "none"]
 
     # Widgets organized into layers
-    dock_layers = _build_dock_layers(display_widgets)
+    layers = _build_layers(display_widgets)
 
-    for widgets in dock_layers.values():
+    for widgets in layers.values():
         # Partition widgets in to split widgets and non-split widgets
         non_split_widgets, split_widgets = partition(get_split, widgets)
         if split_widgets:
@@ -162,7 +164,7 @@ def _arrange_dock_widgets(
             right = max(right, widget_width)
         else:
             # Should not occur, mainly to keep Mypy happy
-            raise AssertionError("invalid value for edge")  # pragma: no-cover
+            raise AssertionError("invalid value for dock edge")  # pragma: no-cover
 
         align_offset = dock_widget.styles._align_size(
             (widget_width, widget_height), size
@@ -220,6 +222,9 @@ def _arrange_split_widgets(
         elif split == "right":
             widget_width = int(widget_width_fraction) + margin.width
             view_region, split_region = view_region.split_vertical(-widget_width)
+        else:
+            raise AssertionError("invalid value for split edge")  # pragma: no-cover
+
         append_placement(
             _WidgetPlacement(split_region, null_spacing, split_widget, 1, True)
         )

src/textual/_styles_cache.py

@@ -313,7 +313,7 @@ def render_line(
 
         def line_post(segments: Iterable[Segment]) -> Iterable[Segment]:
             """Apply effects to segments inside the border."""
-            if styles.has_rule("hatch"):
+            if styles.has_rule("hatch") and styles.hatch != "none":
                 character, color = styles.hatch
                 if character != " " and color.a > 0:
                     hatch_style = Style.from_color(

src/textual/app.py

@@ -312,6 +312,8 @@ class App(Generic[ReturnType], DOMNode):
     App {
         background: $background;
         color: $text;
+
+        /* When a widget is maximized */
         Screen.-maximized-view {                    
             layout: vertical !important;
             hatch: right $panel;
@@ -321,6 +323,10 @@ class App(Generic[ReturnType], DOMNode):
                 dock: initial !important;
             }
         }
+        /* Fade the header title when app is blurred */
+        &:blur HeaderTitle {           
+            text-opacity: 50%;           
+        }
     }
     *:disabled:can-focus {
         opacity: 0.7;
@@ -820,6 +826,17 @@ def _context(self) -> Generator[None, None, None]:
             active_message_pump.reset(message_pump_reset_token)
             active_app.reset(app_reset_token)
 
+    def get_pseudo_classes(self) -> Iterable[str]:
+        """Pseudo classes for a widget.
+
+        Returns:
+            Names of the pseudo classes.
+        """
+        yield "focus" if self.app_focus else "blur"
+        yield "dark" if self.dark else "light"
+        if self.is_inline:
+            yield "inline"
+
     def animate(
         self,
         attribute: str,
@@ -1084,17 +1101,17 @@ def watch_dark(self, dark: bool) -> None:
         self.set_class(dark, "-dark-mode", update=False)
         self.set_class(not dark, "-light-mode", update=False)
         self._refresh_truecolor_filter(self.ansi_theme)
-        self.call_later(self.refresh_css)
+        self.call_next(self.refresh_css)
 
     def watch_ansi_theme_dark(self, theme: TerminalTheme) -> None:
         if self.dark:
             self._refresh_truecolor_filter(theme)
-            self.call_later(self.refresh_css)
+            self.call_next(self.refresh_css)
 
     def watch_ansi_theme_light(self, theme: TerminalTheme) -> None:
         if not self.dark:
             self._refresh_truecolor_filter(theme)
-            self.call_later(self.refresh_css)
+            self.call_next(self.refresh_css)
 
     @property
     def ansi_theme(self) -> TerminalTheme:
@@ -3130,7 +3147,10 @@ def refresh_css(self, animate: bool = True) -> None:
         stylesheet.set_variables(self.get_css_variables())
         stylesheet.reparse()
         stylesheet.update(self.app, animate=animate)
-        self.screen._refresh_layout(self.size)
+        try:
+            self.screen._refresh_layout(self.size)
+        except ScreenError:
+            pass
         # The other screens in the stack will need to know about some style
         # changes, as a final pass let's check in on every screen that isn't
         # the current one and update them too.
@@ -3614,6 +3634,7 @@ def post_mount() -> None:
 
     def _watch_app_focus(self, focus: bool) -> None:
         """Respond to changes in app focus."""
+        self.screen._update_styles()
         if focus:
             # If we've got a last-focused widget, if it still has a screen,
             # and if the screen is still the current screen and if nothing

src/textual/constants.py

@@ -118,3 +118,8 @@ def _get_textual_animations() -> AnimationLevel:
 
 ESCAPE_DELAY: Final[float] = _get_environ_int("ESCDELAY", 100) / 1000.0
 """The delay (in seconds) before reporting an escape key (not used if the extend key protocol is available)."""
+
+SLOW_THRESHOLD: int = _get_environ_int("TEXTUAL_SLOW_THRESHOLD", 500)
+"""The time threshold (in milliseconds) after which a warning is logged 
+if message processing exceeds this duration.
+"""

src/textual/css/_help_text.py

@@ -457,17 +457,19 @@ def dock_property_help_text(property_name: str, context: StylingContext) -> Help
     return HelpText(
         summary=f"Invalid value for [i]{property_name}[/] property",
         bullets=[
-            Bullet("The value must be one of 'top', 'right', 'bottom' or 'left'"),
+            Bullet(
+                "The value must be one of 'top', 'right', 'bottom', 'left' or 'none'"
+            ),
             *ContextSpecificBullets(
                 inline=[
                     Bullet(
-                        "The 'dock' rule aligns a widget relative to the screen.",
+                        "The 'dock' rule attaches a widget to the edge of a container.",
                         examples=[Example('header.styles.dock = "top"')],
                     )
                 ],
                 css=[
                     Bullet(
-                        "The 'dock' rule aligns a widget relative to the screen.",
+                        "The 'dock' rule attaches a widget to the edge of a container.",
                         examples=[Example("dock: top")],
                     )
                 ],