From 2867b09923eb0fc53f167c53aab38001ad9f5651 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Rodrigo=20Gir=C3=A3o=20Serr=C3=A3o?=
 <5621605+rodrigogiraoserrao@users.noreply.github.com>
Date: Fri, 6 Jan 2023 16:38:49 +0000
Subject: [PATCH] Update visibility reference.

---
 docs/styles/visibility.md | 72 +++++++++++++++++++++++++++++++--------
 1 file changed, 58 insertions(+), 14 deletions(-)

diff --git a/docs/styles/visibility.md b/docs/styles/visibility.md
index d864487b0..fbed34e8b 100644
--- a/docs/styles/visibility.md
+++ b/docs/styles/visibility.md
@@ -1,24 +1,42 @@
 # Visibility
 
-The `visibility` rule may be used to make a widget invisible while still reserving spacing for it.
+The `visibility` rule determines whether a widget is visible or not.
 
 ## Syntax
 
-```
-visibility: [visible|hidden];
-```
+--8<-- "docs/snippets/syntax_block_start.md"
+visibility: hidden | visible;
+--8<-- "docs/snippets/syntax_block_end.md"
+
+`visibility` takes one of two values to set the visibility of a widget.
 
 ### Values
 
-| Value               | Description                            |
-|---------------------|----------------------------------------|
-| `visible` (default) | The widget will be displayed as normal |
-| `hidden`            | The widget will be invisible           |
+| Value               | Description                             |
+|---------------------|-----------------------------------------|
+| `hidden`            | The widget will be invisible.           |
+| `visible` (default) | The widget will be displayed as normal. |
 
-## Example
+### Visibility inheritance
+
+!!! note
+
+    Children of an invisible container _can_ be visible.
+
+By default, children inherit the visibility of their parents.
+So, if a container is set to be invisible, its children widgets will also be invisible by default.
+However, those widgets can be made visible if their visibility is explicitly set to `visibility: visible`.
+This is shown in the second example below.
+
+## Examples
 
 Note that the second widget is hidden, while leaving a space where it would have been rendered.
 
+=== "Output"
+
+    ```{.textual path="docs/examples/styles/visibility.py"}
+    ```
+
 === "visibility.py"
 
     ```python
@@ -31,19 +49,45 @@ Note that the second widget is hidden, while leaving a space where it would have
     --8<-- "docs/examples/styles/visibility.css"
     ```
 
+The next example shows the interaction of the `visibility` rule with invisible containers that have visible children.
+The app below has three rows with a `Horizontal` container per row and three placeholders per row.
+The containers all have a white background, and then:
+
+ - the top container is visible by default (we can see the white background around the placeholders);
+ - the middle container is invisible and the children placeholders inherited that setting;
+ - the bottom container is invisible _but_ the children placeholders are visible because they were set to be visible.
+
 === "Output"
 
-    ```{.textual path="docs/examples/styles/visibility.py"}
+    ```{.textual path="docs/examples/styles/visibility_containers.py"}
     ```
 
+=== "visibility_containers.py"
+
+    ```python
+    --8<-- "docs/examples/styles/visibility_containers.py"
+    ```
+
+=== "visibility_containers.css"
+
+    ```css hl_lines="2-3 6 8-10 12-14 16-18"
+    --8<-- "docs/examples/styles/visibility_containers.css"
+    ```
+
+    1. The padding and the white background let us know when the `Horizontal` is visible.
+    2. The top `Horizontal` is visible by default, and so are its children.
+    3. The middle `Horizontal` is made invisible and its children will inherit that setting.
+    4. The bottom `Horizontal` is made invisible...
+    5. ... but its children override that setting and become visible.
+
 ## CSS
 
 ```sass
-/* Widget is on screen */
-visibility: visible;
-
-/* Widget is not on the screen */
+/* Widget is invisible */
 visibility: hidden;
+
+/* Widget is visible */
+visibility: visible;
 ```
 
 ## Python