nested (#3946)

* nested

* remove debug

* patch scope

* fix nested

* docs

* clarification

* docstring

* fix test

* remove debug

* copy

* fix example

* wording

* Apply suggestions from code review

Co-authored-by: Rodrigo Girão Serrão <[email protected]>
Co-authored-by: Dave Pearson <[email protected]>

* highlighting

* wording

* wording

* check errors

* type checking:

* extra errors

* extra test [skip ci]

---------

Co-authored-by: Rodrigo Girão Serrão <[email protected]>
Co-authored-by: Dave Pearson <[email protected]>

Author: 3 people

docs/examples/guide/css/nesting01.py

@@ -0,0 +1,19 @@
+from textual.app import App, ComposeResult
+from textual.containers import Horizontal
+from textual.widgets import Static
+
+
+class NestingDemo(App):
+    """App that doesn't have nested CSS."""
+
+    CSS_PATH = "nesting01.tcss"
+
+    def compose(self) -> ComposeResult:
+        with Horizontal(id="questions"):
+            yield Static("Yes", classes="button affirmative")
+            yield Static("No", classes="button negative")
+
+
+if __name__ == "__main__":
+    app = NestingDemo()
+    app.run()

docs/examples/guide/css/nesting01.tcss

@@ -0,0 +1,24 @@
+/* Style the container */
+#questions {
+    border: heavy $primary;
+    align: center middle;
+}
+
+/* Style all buttons */
+#questions .button {
+    width: 1fr;
+    padding: 1 2;
+    margin: 1 2;
+    text-align: center;
+    border: heavy $panel;
+}
+
+/* Style the Yes button */
+#questions .button.affirmative {
+    border: heavy $success;
+}
+
+/* Style the No button */
+#questions .button.negative {
+    border: heavy $error;
+}

docs/examples/guide/css/nesting02.py

@@ -0,0 +1,19 @@
+from textual.app import App, ComposeResult
+from textual.containers import Horizontal
+from textual.widgets import Static
+
+
+class NestingDemo(App):
+    """App with nested CSS."""
+
+    CSS_PATH = "nesting02.tcss"
+
+    def compose(self) -> ComposeResult:
+        with Horizontal(id="questions"):
+            yield Static("Yes", classes="button affirmative")
+            yield Static("No", classes="button negative")
+
+
+if __name__ == "__main__":
+    app = NestingDemo()
+    app.run()

docs/examples/guide/css/nesting02.tcss

@@ -0,0 +1,24 @@
+/* Style the container */
+#questions {
+    border: heavy $primary;
+    align: center middle;
+
+    /* Style all buttons */
+    .button {
+        width: 1fr;
+        padding: 1 2;
+        margin: 1 2;
+        text-align: center;
+        border: heavy $panel;    
+
+        /* Style the Yes button */
+        &.affirmative {
+            border: heavy $success;        
+        }
+
+        /* Style the No button */
+        &.negative {
+            border: heavy $error;
+        }
+    }
+}

docs/guide/CSS.md

@@ -468,3 +468,93 @@ For instance, if we have a widget with a (CSS) class called `dialog`, we could r
 
 Note that `initial` will set the value back to the value defined in any [default css](./widgets.md#default-css).
 If you use `initial` within default css, it will treat the rule as completely unstyled.
+
+
+## Nesting CSS
+
+!!! tip "Added in version 0.47.0"
+
+CSS rule sets may be *nested*, i.e. they can contain other rule sets.
+When a rule set occurs within an existing rule set, it inherits the selector from the enclosing rule set.
+
+Let's put this into practical terms.
+The following example will display two boxes containing the text "Yes" and "No" respectively.
+These could eventually form the basis for buttons, but for this demonstration we are only interested in the CSS.
+
+=== "nesting01.tcss (no nesting)"
+
+    ```css
+    --8<-- "docs/examples/guide/css/nesting01.tcss"
+    ```
+
+=== "nesting01.py"
+
+    ```python
+    --8<-- "docs/examples/guide/css/nesting01.py"
+    ```
+
+=== "Output"
+
+    ```{.textual path="docs/examples/guide/css/nesting01.py"}
+    ```
+
+The CSS is quite straightforward; there is one rule for the container, one for all buttons, and one rule for each of the buttons.
+However it is easy to imagine this stylesheet growing more rules as we add features.
+
+Nesting allows us to group rule sets which have common selectors.
+In the example above, the rules all start with `#questions`.
+When we see a common prefix on the selectors, this is a good indication that we can use nesting.
+
+The following produces identical results to the previous example, but adds nesting of the rules.
+
+=== "nesting02.tcss (with nesting)"
+
+    ```css
+    --8<-- "docs/examples/guide/css/nesting02.tcss"
+    ```
+
+=== "nesting02.py"
+
+    ```python
+    --8<-- "docs/examples/guide/css/nesting02.py"
+    ```
+
+=== "Output"
+
+    ```{.textual path="docs/examples/guide/css/nesting02.py"}
+    ```
+
+In the first example we had a rule set that began with the selector `#questions .button`, which would match any widget with a class called "button" that is inside a container with id `questions`.
+
+In the second example, the button rule selector is simply `.button`, but it is *within* the rule set with selector `#questions`.
+The nesting means that the button rule set will inherit the selector from the outer rule set, so it is equivalent to `#questions .button`.
+
+### Nesting selector
+
+The two remaining rules are nested within the button rule, which means they will inherit their selectors from the button rule set *and* the outer `#questions` rule set.
+
+You may have noticed that the rules for the button styles contain a syntax we haven't seen before.
+The rule for the Yes button is `&.affirmative`.
+The ampersand (`&`) is known as the *nesting selector* and it tells Textual that the selector should be combined with the selector from the outer rule set.
+
+So `&.affirmative` in the example above, produces the equivalent of `#questions .button.affirmative` which selects a widget with both the `button` and `affirmative` classes.
+Without `&` it would be equivalent to `#questions .button .affirmative` (note the additional space) which would only match a widget with class `affirmative` inside a container with class `button`.
+
+
+For reference, lets see those two CSS files side-by-side:
+
+=== "nesting01.tcss"
+
+    ```css
+    --8<-- "docs/examples/guide/css/nesting01.tcss"
+    ```
+
+=== "nesting02.tcss"
+
+    ```sass
+    --8<-- "docs/examples/guide/css/nesting02.tcss"
+    ```
+
+### Why use nesting?
+
+There is no requirement to use nested CSS, but it can help to group related rule sets together (which makes it easier to edit). Nested CSS can also help you avoid some repetition in your selectors, i.e. in the nested CSS we only need to type `#questions` once, rather than four times in the non-nested CSS.

examples/dictionary.tcss

@@ -9,8 +9,7 @@ Input {
 
 #results {
     width: 100%;
-    height: auto;
-
+    height: auto;    
 }
 
 #results-container {

src/textual/css/model.py

@@ -20,6 +20,7 @@ class SelectorType(Enum):
     TYPE = 2
     CLASS = 3
     ID = 4
+    NESTED = 5
 
 
 class CombinatorType(Enum):
@@ -175,8 +176,7 @@ def _selector_to_css(cls, selectors: list[Selector]) -> str:
             elif selector.combinator == CombinatorType.CHILD:
                 tokens.append(" > ")
             tokens.append(selector.css)
-            for pseudo_class in selector.pseudo_classes:
-                tokens.append(f":{pseudo_class}")
+
         return "".join(tokens).strip()
 
     @property

src/textual/css/parse.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import dataclasses
 from functools import lru_cache
 from typing import Iterable, Iterator, NoReturn
 
@@ -29,14 +30,31 @@
     "selector_start_id": (SelectorType.ID, (1, 0, 0)),
     "selector_universal": (SelectorType.UNIVERSAL, (0, 0, 0)),
     "selector_start_universal": (SelectorType.UNIVERSAL, (0, 0, 0)),
+    "nested": (SelectorType.NESTED, (0, 0, 0)),
 }
 
 
+def _add_specificity(
+    specificity1: Specificity3, specificity2: Specificity3
+) -> Specificity3:
+    """Add specificity tuples together.
+
+    Args:
+        specificity1: Specificity triple.
+        specificity2: Specificity triple.
+
+    Returns:
+        Combined specificity.
+    """
+    a1, b1, c1 = specificity1
+    a2, b2, c2 = specificity2
+    return (a1 + a2, b1 + b2, c1 + c2)
+
+
 @lru_cache(maxsize=1024)
 def parse_selectors(css_selectors: str) -> tuple[SelectorSet, ...]:
     if not css_selectors.strip():
         return ()
-
     tokens = iter(tokenize(css_selectors, ("", "")))
 
     get_selector = SELECTOR_MAP.get
@@ -46,10 +64,13 @@ def parse_selectors(css_selectors: str) -> tuple[SelectorSet, ...]:
 
     while True:
         try:
-            token = next(tokens)
+            token = next(tokens, None)
         except EOFError:
             break
+        if token is None:
+            break
         token_name = token.name
+
         if token_name == "pseudo_class":
             selectors[-1]._add_pseudo_class(token.value.lstrip(":"))
         elif token_name == "whitespace":
@@ -143,14 +164,82 @@ def parse_rule_set(
         rule_selectors.append(selectors[:])
 
     declaration = Declaration(token, "")
-
     errors: list[tuple[Token, str | HelpText]] = []
+    nested_rules: list[RuleSet] = []
 
     while True:
         token = next(tokens)
+
         token_name = token.name
         if token_name in ("whitespace", "declaration_end"):
             continue
+        if token_name in {
+            "selector_start_id",
+            "selector_start_class",
+            "selector_start_universal",
+            "selector_start",
+            "nested",
+        }:
+            recursive_parse: list[RuleSet] = list(
+                parse_rule_set(
+                    "",
+                    tokens,
+                    token,
+                    is_default_rules=is_default_rules,
+                    tie_breaker=tie_breaker,
+                )
+            )
+
+            def combine_selectors(
+                selectors1: list[Selector], selectors2: list[Selector]
+            ) -> list[Selector]:
+                """Combine lists of selectors together, processing any nesting.
+
+                Args:
+                    selectors1: List of selectors.
+                    selectors2: Second list of selectors.
+
+                Returns:
+                    Combined selectors.
+                """
+                if selectors2 and selectors2[0].type == SelectorType.NESTED:
+                    final_selector = selectors1[-1]
+                    nested_selector = selectors2[0]
+                    merged_selector = dataclasses.replace(
+                        final_selector,
+                        pseudo_classes=list(
+                            set(
+                                final_selector.pseudo_classes
+                                + nested_selector.pseudo_classes
+                            )
+                        ),
+                        specificity=_add_specificity(
+                            final_selector.specificity, nested_selector.specificity
+                        ),
+                    )
+                    return [*selectors1[:-1], merged_selector, *selectors2[1:]]
+                else:
+                    return selectors1 + selectors2
+
+            for rule_selector in rule_selectors:
+                for rule_set in recursive_parse:
+                    nested_rule_set = RuleSet(
+                        [
+                            SelectorSet(
+                                combine_selectors(
+                                    rule_selector, recursive_selectors.selectors
+                                ),
+                                (recursive_selectors.specificity),
+                            )
+                            for recursive_selectors in rule_set.selector_set
+                        ],
+                        rule_set.styles,
+                        rule_set.errors,
+                        rule_set.is_default_rules,
+                        rule_set.tie_breaker + tie_breaker,
+                    )
+                    nested_rules.append(nested_rule_set)
+            continue
         if token_name == "declaration_name":
             try:
                 styles_builder.add_declaration(declaration)
@@ -175,9 +264,14 @@ def parse_rule_set(
         is_default_rules=is_default_rules,
         tie_breaker=tie_breaker,
     )
+
     rule_set._post_parse()
     yield rule_set
 
+    for nested_rule_set in nested_rules:
+        nested_rule_set._post_parse()
+        yield nested_rule_set
+
 
 def parse_declarations(css: str, read_from: CSSLocation) -> Styles:
     """Parse declarations and return a Styles object.
@@ -270,7 +364,6 @@ def substitute_references(
             attribute populated with information about where the tokens are being substituted to.
     """
     variables: dict[str, list[Token]] = css_variables.copy() if css_variables else {}
-
     iter_tokens = iter(tokens)
 
     while True:
@@ -357,7 +450,6 @@ def parse(
         is_default_rules: True if the rules we're extracting are
             default (i.e. in Widget.DEFAULT_CSS) rules. False if they're from user defined CSS.
     """
-
     reference_tokens = tokenize_values(variables) if variables is not None else {}
     if variable_tokens:
         reference_tokens.update(variable_tokens)

src/textual/css/stylesheet.py

@@ -248,7 +248,7 @@ def _parse_rules(
         except TokenError:
             raise
         except Exception as error:
-            raise StylesheetError(f"failed to parse css; {error}")
+            raise StylesheetError(f"failed to parse css; {error}") from None
 
         self._parse_cache[cache_key] = rules
         return rules