Add pagination functionality and support for pagination component in TNA Frontend

CHANGELOG.md

@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Added option in Flask Talisman to add Adobe Typekit CSP rules with `allow_typekit_content_security_policy=True`
 - Added `extra_headers` parameter in `Talisman` to update or add any global response headers
+- New pagination functions for populating pagination components
 
 ### Changed
 

docs/component.md

@@ -0,0 +1,57 @@
+# Component
+
+## `paginate()`
+
+Creates a pagination object in accordance with the [pages to show in a pagination component](https://design-system.nationalarchives.gov.uk/components/pagination/#number-of-page-links) in the National Archives Design System.
+
+### Arguments
+
+| Argument       | Description                                                | Default |
+| -------------- | ---------------------------------------------------------- | ------- |
+| `pages`        | The total number of pages to paginate                      | [none]  |
+| `current_page` | The number of the current page                             | [none]  |
+| `around`       | The number of items to always show around the current page | `1`     |
+
+### Example
+
+```python
+from tna_utilities.component import paginate
+
+print(paginate(42, 7))
+# [1, "...", 6, 7, 8, "...", 42]
+
+print(paginate(42, 7, around=2))
+# [1, "...", 5, 6, 7, 8, 9, "...", 42]
+```
+
+## `tna_frontend_pagination_items()`
+
+Creates an object that be used directly in a [National Archives pagination component](https://design-system.nationalarchives.gov.uk/components/pagination/).
+
+### Arguments
+
+| Argument       | Description                                                                     | Default                                                            |
+| -------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| `pages`        | The total number of pages to paginate                                           | [none]                                                             |
+| `current_page` | The number of the current page                                                  | [none]                                                             |
+| `base_url`     | The base URL including the blank query string for the page                      | [none]                                                             |
+| `around`       | The number of items to always show around the current page                      | `1`                                                                |
+| `transformer`  | A function to create the item given a number and whether it is the current page | `tna_utilities.component.tna_frontend_pagination_item_transformer` |
+| `ellipsis`     | A dictionary to use in place of an ellipsis                                     | `{"ellipsis": True}`                                               |
+
+### Example
+
+```python
+from tna_utilities.component import paginate
+
+print(tna_frontend_pagination_items(42, 6, "?page="))
+# [
+#     {"number": 1, "current": False, "href": "?page=1"},
+#     {"ellipsis": True},
+#     {"number": 5, "current": False, "href": "?page=5"},
+#     {"number": 6, "current": True, "href": "?page=6"},
+#     {"number": 7, "current": False, "href": "?page=7"},
+#     {"ellipsis": True},
+#     {"number": 42, "current": False, "href": "?page=42"},
+# ]
+```