From 9eea01f5a1a9e3590b38861c325dc2b8fe844cfd Mon Sep 17 00:00:00 2001
From: darrenburns <darrenburns@users.noreply.github.com>
Date: Fri, 19 Aug 2022 13:07:22 +0100
Subject: [PATCH] Docs scrollbar gutter (#695)

* Add scrollbar-gutter docs

* Add scrollbar-gutter docs

* Add syntax and values section

* Rewording
---
 .pre-commit-config.yaml                  |  3 +-
 docs/examples/styles/scrollbar_gutter.py | 28 ++++++++++++++
 docs/styles/scrollbar_gutter.md          | 47 ++++++++++++++++++++++++
 mkdocs.yml                               |  5 ++-
 4 files changed, 80 insertions(+), 3 deletions(-)
 create mode 100644 docs/examples/styles/scrollbar_gutter.py
 create mode 100644 docs/styles/scrollbar_gutter.md

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index e4369ce2e6..b65350ed6f 100644
--- a/.pre-commit-config.yaml
+++ b/.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:
diff --git a/docs/examples/styles/scrollbar_gutter.py b/docs/examples/styles/scrollbar_gutter.py
new file mode 100644
index 0000000000..18d25ae793
--- /dev/null
+++ b/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()
diff --git a/docs/styles/scrollbar_gutter.md b/docs/styles/scrollbar_gutter.md
new file mode 100644
index 0000000000..d7be5f89f1
--- /dev/null
+++ b/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"
+```
diff --git a/mkdocs.yml b/mkdocs.yml
index d35b2d6765..1c85c5ba0d 100644
--- a/mkdocs.yml
+++ b/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