Docs scrollbar gutter (#695)

* Add scrollbar-gutter docs

* Add scrollbar-gutter docs

* Add syntax and values section

* Rewording

.pre-commit-config.yaml

@@ -2,11 +2,12 @@
 # See https://pre-commit.com/hooks.html for more hooks
 repos:
 -   repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v3.2.0
+    rev: v4.3.0
     hooks:
     -   id: trailing-whitespace
     -   id: end-of-file-fixer
     -   id: check-yaml
+        args: ['--unsafe']
 -   repo: https://github.com/psf/black
     rev: 22.3.0
     hooks:

docs/examples/styles/scrollbar_gutter.py

@@ -0,0 +1,28 @@
+from textual.app import App
+from textual.widgets import Static
+
+TEXT = """I must not fear.
+Fear is the mind-killer.
+Fear is the little-death that brings total obliteration.
+I will face my fear.
+I will permit it to pass over me and through me.
+And when it has gone past, I will turn the inner eye to see its path.
+Where the fear has gone there will be nothing. Only I will remain."""
+
+
+class ScrollbarGutterApp(App):
+    CSS = """
+    Screen {
+        scrollbar-gutter: stable;
+    }
+    Static {
+        color: floralwhite;
+        background: darkmagenta;
+    }
+    """
+
+    def compose(self):
+        yield Static(TEXT)
+
+
+app = ScrollbarGutterApp()

docs/styles/scrollbar_gutter.md

@@ -0,0 +1,47 @@
+# Scrollbar gutter
+
+The `scrollbar-gutter` rule allows authors to reserve space for the vertical scrollbar.
+
+Setting the value to `stable` prevents unwanted layout changes when the scrollbar becomes visible.
+
+## Syntax
+
+```
+scrollbar-gutter: [auto|stable];
+```
+
+### Values
+
+| Value            | Description                                      |
+|------------------|--------------------------------------------------|
+| `auto` (default) | No space is reserved for the vertical scrollbar. |
+| `stable`         | Space is reserved for the vertical scrollbar.    |
+
+## Example
+
+In the example below, notice the gap reserved for the scrollbar on the right side of the
+terminal window.
+
+=== "scrollbar_gutter.py"
+
+    ```python
+    --8<-- "docs/examples/styles/scrollbar_gutter.py"
+    ```
+
+=== "Output"
+
+    ```{.textual path="docs/examples/styles/scrollbar_gutter.py"}
+    ```
+
+## CSS
+
+```sass
+/* Reserve space for vertical scrollbar */
+scrollbar-gutter: stable;
+```
+
+## Python
+
+```python
+self.styles.scrollbar_gutter = "stable"
+```

mkdocs.yml

@@ -10,7 +10,7 @@ nav:
   - Events:
     - "events/mount.md"
     - "events/resize.md"
-  - Styles:    
+  - Styles:
     - "styles/background.md"
     - "styles/border.md"
     - "styles/box_sizing.md"
@@ -28,6 +28,7 @@ nav:
     - "styles/padding.md"
     - "styles/scrollbar.md"
     - "styles/scrollbar_size.md"
+    - "styles/scrollbar_gutter.md"
     - "styles/text_style.md"
     - "styles/tint.md"
     - "styles/visibility.md"
@@ -60,7 +61,7 @@ markdown_extensions:
   - pymdownx.superfences
   - pymdownx.snippets
   - pymdownx.tabbed:
-      alternate_style: true 
+      alternate_style: true
   - pymdownx.snippets
   - markdown.extensions.attr_list