From c8c0f452dc9d31a12ede0c459df1691f9d4fcf7a Mon Sep 17 00:00:00 2001
From: Ruben Sousa <ruben@rubensousa.com>
Date: Mon, 17 Jun 2024 01:56:55 +0200
Subject: [PATCH] Add scrollbar docs

---
 README.MD                  |  1 +
 docs/index.md              |  1 +
 docs/recipes/scrollbars.md | 64 ++++++++++++++++++++++++++++++++++++++
 mkdocs.yml                 |  3 +-
 4 files changed, 68 insertions(+), 1 deletion(-)
 create mode 100644 docs/recipes/scrollbars.md

diff --git a/README.MD b/README.MD
index 77843079..4fa7c458 100644
--- a/README.MD
+++ b/README.MD
@@ -25,6 +25,7 @@ Why should you use this library?
 | Prefetching upcoming items       | ✅                | ❌        | ✅          |
 | Reverse layout                   | ✅                | ❌        | ✅          |
 | Testing library                  | ✅                | ❌        | ✅          |
+| Scrollbars                       | ✅                | ❌        | ❌          |
 | Drag and Drop                    | ✅                | ❌        | ❌          |
 | Infinite layout with loop        | ✅                | ❌        | ❌          |
 | Smooth alignment changes         | ✅                | ❌        | ❌          |
diff --git a/docs/index.md b/docs/index.md
index b788b410..83c37cb3 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -27,6 +27,7 @@ Why should you use this library?
 | Prefetching upcoming items        | ✅                | ❌        | ✅          |
 | Reverse layout                    | ✅                | ❌        | ✅          |
 | Testing library                   | ✅                | ❌        | ✅          |
+| Scrollbars                        | ✅                | ❌        | ❌          |
 | Drag and Drop                     | ✅                | ❌        | ❌          |
 | Infinite layout with loop         | ✅                | ❌        | ❌          |
 | Smooth alignment changes          | ✅                | ❌        | ❌          |
diff --git a/docs/recipes/scrollbars.md b/docs/recipes/scrollbars.md
new file mode 100644
index 00000000..129025de
--- /dev/null
+++ b/docs/recipes/scrollbars.md
@@ -0,0 +1,64 @@
+# Scrollbar Recipe
+
+Scrollbars are composed of two parts:
+
+1. Thumb: the main indicator for the current scroll position
+2. Track: the background of the scrollbar
+
+
+!!! note
+    Unfortunately, scrollbars can only be defined in XML. You can create a style for re-usability.
+
+## Defining scrollbar appearance
+
+Thumb example:
+
+```xml linenums="1"
+<shape xmlns:android="http://schemas.android.com/apk/res/android"
+    android:shape="rectangle">
+
+    <corners android:radius="4dp" />
+    <solid android:color="@color/white" />
+
+</shape>
+```
+
+Track example:
+
+```xml linenums="1"
+<shape xmlns:android="http://schemas.android.com/apk/res/android"
+    android:shape="rectangle">
+
+    <solid android:color="@color/black" />
+
+</shape>
+
+```
+
+## `DpadRecyclerView` scrollbar configuration
+
+To apply the above scrollbar appearance, place this in your `DpadRecyclerView` XML definition
+
+```xml linenums="1" hl_lines="6-8"
+<com.rubensousa.dpadrecyclerview.DpadRecyclerView
+    android:id="@+id/recyclerView"
+    android:layout_width="match_parent"
+    android:layout_height="match_parent"
+    android:scrollbarSize="6dp"
+    android:scrollbarThumbVertical="@drawable/scrollbar_thumb"
+    android:scrollbarTrackVertical="@drawable/scrollbar_track"
+    android:scrollbars="vertical" />
+```
+
+!!! note
+    Replace "Vertical" with "Horizontal" for horizontal scrollbars
+
+
+By default, the scrollbar is only shown after scrolling and then disappears. 
+You can force it to always appear by using this attribute:
+
+```xml linenums="1"
+<com.rubensousa.dpadrecyclerview.DpadRecyclerView
+    android:scrollbarAlwaysDrawVerticalTrack="true" />
+```
+
diff --git a/mkdocs.yml b/mkdocs.yml
index 39113265..2fddc5c3 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -60,11 +60,12 @@ nav:
   - 'Testing': testing.md
   - 'XML attributes': xml.md
   - 'Recipes':
+      - 'Alignment': recipes/alignment.md
       - 'Layout': recipes/layout.md
       - 'Spacing': recipes/spacing.md
-      - 'Alignment': recipes/alignment.md
       - 'Focus': recipes/focus.md
       - 'Scrolling': recipes/scrolling.md
+      - 'Scrollbars': recipes/scrollbars.md
       - 'Drag and drop': recipes/dragdrop.md
   - 'Changelog': changelog.md
   - 'API': api/
\ No newline at end of file