docs(scrollable-pane): add documentation for scrollable pane component (

#405) We've had this component for a while, but never documented it.
ministryofjustice · Nov 14, 2022 · 88a03c5 · 88a03c5
1 parent 071478d
commit 88a03c5
Show file tree

Hide file tree

Showing 3 changed files with 290 additions and 9 deletions.
diff --git a/docs/_includes/layouts/component.njk b/docs/_includes/layouts/component.njk
@@ -105,25 +105,29 @@
               text: 'Messages',
               href: ('/components/messages' | url)
             },
-            {
-              text: 'Ticket panel',
-              href: ('/components/ticket-panel' | url)
-            },
-            {
-              text: 'Timeline',
-              href: ('/components/timeline' | url)
-            },
             {
               text: 'Multi select',
               href: ('/components/multi-select' | url)
             },
+            {
+              text: 'Scrollable pane',
+              href: ('/components/scrollable-pane' | url)
+            },
             {
               text: 'Sortable table',
               href: ('/components/sortable-table' | url)
+            },
+            {
+              text: 'Ticket panel',
+              href: ('/components/ticket-panel' | url)
+            },
+            {
+              text: 'Timeline',
+              href: ('/components/timeline' | url)
             }
             ]
           }
-        ]
+      ]
 
         }) }}
 

diff --git a/docs/components/scrollable-pane.md b/docs/components/scrollable-pane.md
@@ -0,0 +1,18 @@
+---
+layout: layouts/component.njk
+title: Scrollable pane
+---
+
+{% example "/examples/scrollable-pane", 470 %}
+
+## When to use
+
+Use the scrollable pane component when you have content (typically tables) which unavoidably overflowing the page. It adds scroll shadows to indicate that content overflows the page.
+
+This is often used in the [filter a list](../../patterns/filter-a-list/) pattern as the filter takes up additional horizontal space, causing the pane holding the table to shrink.
+
+## When not to use
+
+Before using this, try to avoid having content that overflows the page at all. Users should be able to see all of the page's content without needing to scroll, so this component should only be used when absolutely necessary.
+
+Do not use this component to contain tables which have multi-line text. It will not allow the content to overflow vertically.
diff --git a/docs/examples/scrollable-pane/index.njk b/docs/examples/scrollable-pane/index.njk
@@ -0,0 +1,259 @@
+---
+layout: layouts/example.njk
+title: Sortable table (example)
+---
+
+{%- from "govuk/components/table/macro.njk" import govukTable -%}
+
+<div class="moj-scrollable-pane">
+  {{ govukTable({
+    caption: "Historic rainfall in June",
+    head: [
+      {
+        text: "Station"
+      },
+      {
+        text: "2022"
+      },
+      {
+        text: "2021"
+      },
+      {
+        text: "2020"
+      },
+      {
+        text: "2019"
+      },
+      {
+        text: "2018"
+      },
+      {
+        text: "2017"
+      },
+      {
+        text: "2016"
+      },
+      {
+        text: "2015"
+      },
+      {
+        text: "2014"
+      },
+      {
+        text: "2013"
+      }
+    ],
+    rows: [
+      [
+        {
+          text: "Lerwick"
+        },
+        {
+          text: "13.7mm"
+        },
+        {
+          text: "13.8mm"
+        },
+        {
+          text: "13.9mm"
+        },
+        {
+          text: "12.7mm"
+        },
+        {
+          text: "13.3mm"
+        },
+        {
+          text: "13.3mm"
+        },
+        {
+          text: "12.9mm"
+        },
+        {
+          text: "11.2mm"
+        },
+        {
+          text: "13.3mm"
+        },
+        {
+          text: "12.7mm"
+        }
+      ],
+      [
+        {
+          text: "Eskdalemuir"
+        },
+        {
+          text: "17.0mm"
+        },
+        {
+          text: "17.9mm"
+        },
+        {
+          text: "17.2mm"
+        },
+        {
+          text: "16.2mm"
+        },
+        {
+          text: "19.7mm"
+        },
+        {
+          text: "16.4mm"
+        },
+        {
+          text: "17.6mm"
+        },
+        {
+          text: "15.7mm"
+        },
+        {
+          text: "17.8mm"
+        },
+        {
+          text: "16.9mm"
+        }
+      ],
+      [
+        {
+          text: "Valley"
+        },
+        {
+          text: "17.5mm"
+        },
+        {
+          text: "17.4mm"
+        },
+        {
+          text: "17.9mm"
+        },
+        {
+          text: "17.1mm"
+        },
+        {
+          text: "20.2mm"
+        },
+        {
+          text: "17.6mm"
+        },
+        {
+          text: "18.0mm"
+        },
+        {
+          text: "16.6mm"
+        },
+        {
+          text: "18.0mm"
+        },
+        {
+          text: "17.5mm"
+        }
+      ],
+      [
+        {
+          text: "Heathrow"
+        },
+        {
+          text: "23.2mm"
+        },
+        {
+          text: "22.5mm"
+        },
+        {
+          text: "22.5mm"
+        },
+        {
+          text: "21.8mm"
+        },
+        {
+          text: "24.2mm"
+        },
+        {
+          text: "24.0mm"
+        },
+        {
+          text: "20.7mm"
+        },
+        {
+          text: "22.2mm"
+        },
+        {
+          text: "22.1mm"
+        },
+        {
+          text: "20.3mm"
+        }
+      ],
+      [
+        {
+          text: "Hurn"
+        },
+        {
+          text: "21.0mm"
+        },
+        {
+          text: "20.7mm"
+        },
+        {
+          text: "20.7mm"
+        },
+        {
+          text: "19.9mm"
+        },
+        {
+          text: "22.9mm"
+        },
+        {
+          text: "21.9mm"
+        },
+        {
+          text: "19.6mm"
+        },
+        {
+          text: "20.5mm"
+        },
+        {
+          text: "21.1mm"
+        },
+        {
+          text: "19.6mm"
+        }
+      ],
+      [
+        {
+          text: "Camborne"
+        },
+        {
+          text: "17.9mm"
+        },
+        {
+          text: "17.4mm"
+        },
+        {
+          text: "17.1mm"
+        },
+        {
+          text: "16.5mm"
+        },
+        {
+          text: "19.7mm"
+        },
+        {
+          text: "18.0mm"
+        },
+        {
+          text: "17.0mm"
+        },
+        {
+          text: "16.8mm"
+        },
+        {
+          text: "17.8mm"
+        },
+        {
+          text: "15.9mm"
+        }
+      ]
+    ]
+  }) }}
+</div>