Pagination: responsive part round 2

scss/_pagination.scss

@@ -105,6 +105,21 @@
   }
 }
 
+// Boosted mod
+.page-ellipsis {
+  display: flex;
+
+  &::after {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: calc((var(--#{$prefix}pagination-icon-size) + var(--#{$prefix}pagination-border-width) * 2)); // stylelint-disable-line function-disallowed-list
+    content: "...";
+    background-color: var(--#{$prefix}pagination-bg);
+  }
+}
+// End mod
+
 .page-item {
   &:not(:first-child) .page-link {
     margin-left: $pagination-margin-start;
@@ -182,24 +197,18 @@
     margin-left: var(--#{$prefix}pagination-margin-x-first-last);
   }
 
-  @include media-breakpoint-down(sm) {
-    @include pagination-max-items(4);
-  }
-
-  @include media-breakpoint-between(sm, md) {
-    @include pagination-max-items(6);
-  }
-
-  @include media-breakpoint-between(md, lg) {
-    @include pagination-max-items(8);
-  }
+  @if $enable-responsive-pagination {
+    @include media-breakpoint-down(sm) {
+      @include pagination-max-items(3);
+    }
 
-  @include media-breakpoint-between(lg, xl) {
-    @include pagination-max-items(10);
-  }
+    @include media-breakpoint-between(sm, md) {
+      @include pagination-max-items(10);
+    }
 
-  @include media-breakpoint-up(xl) {
-    @include pagination-max-items(12);
+    @include media-breakpoint-up(md) {
+      @include pagination-max-items(12);
+    }
   }
   // End mod
 }

scss/_variables.scss

@@ -422,23 +422,24 @@ $orange-filter:         invert(46%) sepia(60%) saturate(2878%) hue-rotate(6deg)
 //
 // Quickly modify global styling by enabling or disabling optional features.
 
-$enable-caret:                true !default;
-$enable-rounded:              false !default;
-$enable-shadows:              false !default;
-$enable-gradients:            false !default;
-$enable-transitions:          true !default;
-$enable-reduced-motion:       true !default;
-$enable-smooth-scroll:        true !default;
-$enable-grid-classes:         true !default;
-$enable-container-classes:    true !default;
-$enable-cssgrid:              false !default;
-$enable-button-pointers:      true !default;
-$enable-rfs:                  false !default;
-$enable-validation-icons:     true !default;
-$enable-negative-margins:     false !default;
-$enable-deprecation-messages: false !default;
-$enable-important-utilities:  true !default;
-$enable-fixed-header:         true !default; // Boosted mod: used to apply scroll-padding-top
+$enable-caret:                  true !default;
+$enable-rounded:                false !default;
+$enable-shadows:                false !default;
+$enable-gradients:              false !default;
+$enable-transitions:            true !default;
+$enable-reduced-motion:         true !default;
+$enable-smooth-scroll:          true !default;
+$enable-grid-classes:           true !default;
+$enable-container-classes:      true !default;
+$enable-cssgrid:                false !default;
+$enable-button-pointers:        true !default;
+$enable-rfs:                    false !default;
+$enable-validation-icons:       true !default;
+$enable-negative-margins:       false !default;
+$enable-deprecation-messages:   false !default;
+$enable-important-utilities:    true !default;
+$enable-fixed-header:           true !default; // Boosted mod: used to apply scroll-padding-top
+$enable-responsive-pagination:  false !default; // Boosted mod: used to apply smart responsive pagination behavior
 
 $enable-dark-mode:            true !default;
 $color-mode-type:             data !default; // `data` or `media-query`

scss/mixins/_pagination.scss

@@ -11,17 +11,86 @@
 
 // scss-docs-start pagination-max-items-mixin
 // Boosted mod
-// Ensure we only display `n` items:
-// - the first `n/2` items
-// - the last `n/2` items
-// - including the .active one (so maybe not the `n/2`th last item)
-@mixin pagination-max-items($pagination-max-items) {
+// The pagination list ((m) items) should display exactly (n) items and is built in 3 parts:
+// - the begining of the list is made of the first (n/2) items
+// - the end of the list is made of the last (n/2) items (or (n/2 - 1) depending on the active element)
+// - the last part of the list is made of the active element
+// - n should be greater than 0:
+//   - between 0 and 6 included, it displays the smallest version
+//   - above 7 included, it displays at least two arrows, the first, the active and the last and might have 2 three dots
+@mixin pagination-max-items($pagination-max-items: 12) {
   display: none;
 
-  &.active,
-  &:nth-child(-n+#{$pagination-max-items * .5}),
-  &:nth-last-child(-n+#{$pagination-max-items * .5}) {
-    display: list-item;
+  @if $pagination-max-items >= 7 {
+    // this determines the number of displayed numbers required at the beginning and end of a list
+    $half-first-items: $pagination-max-items * .5;
+    $half-last-items: $pagination-max-items * .5;
+    @if $pagination-max-items % 2 != 0 {
+      $half-first-items: ($pagination-max-items - 1) * .5;
+      $half-last-items: ($pagination-max-items + 1) * .5;
+    }
+
+    // rule 0: don't display any item unless they are part of the following list:
+    //  - the active item
+    //  - the (n/2 - 1) first items
+    //  - the (n/2) last items
+    //  - the (n/2) first item where m equals n
+    &.active,
+    &:nth-child(-n + #{$half-first-items - 1}),
+    &:nth-last-child(-n + #{$half-last-items}),
+    &:nth-child(#{$half-first-items}):nth-last-child(#{$half-last-items + 1}) {
+      display: flex;
+    }
+
+    // rule 1: display `...` on:
+    //  - the (n/2 - 1) first item if not the last child
+    //  - the active item when it's:
+    //    - not in (n/2 - 1) first items
+    //    - not in (n/2) last items
+    //    - not the (n/2) first item when m equals n
+    &:nth-child(#{$half-first-items - 1}):not(:last-child),
+    &:nth-child(#{$half-first-items - 1}) ~ .active:not(:nth-last-child(-n + #{$half-last-items})):not(:nth-child(#{$half-first-items}):nth-last-child(#{$half-last-items + 1})) {
+      &::after {
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        width: calc((var(--#{$prefix}pagination-icon-size) + var(--#{$prefix}pagination-border-width) * 2)); // stylelint-disable-line function-disallowed-list
+        content: "...";
+        background-color: var(--#{$prefix}pagination-bg);
+      }
+    }
+
+    // rule 2: cover the three dots when:
+    //  - the (n/2) first item when:
+    //    - it's the active item
+    //    - it's in a list where m is less or equal n
+    &.active:nth-child(#{$half-first-items}),
+    &:nth-child(#{$half-first-items}):nth-last-child(-n + #{$half-last-items + 1}) {
+      margin-left: calc(-1 * (var(--#{$prefix}pagination-icon-size) + var(--#{$prefix}pagination-border-width) * 2)); // stylelint-disable-line function-disallowed-list
+    }
+
+    // rule 3: remove some extra items due to three dots:
+    //  - the (n/2) last item when it follows the active item situated between the (n/2 - 1) first item and (n/2 + 1) last item (excluded) and m doesn't equal n
+    //  - the (n/2 - 1) last item when it follows the active item situated between the (n/2) first item and (n/2) last item (excluded)
+    &:nth-child(#{$half-first-items}) ~ .active:not(:nth-last-child(#{$half-last-items})) ~ :nth-last-child(#{$half-last-items - 1}),
+    &:nth-child(#{$half-first-items - 1}) ~ .active:not(:nth-child(#{$half-first-items}):nth-last-child(#{$half-last-items + 1})) ~ :nth-last-child(#{$half-last-items}) {
+      display: none;
+    }
+  } @else {
+    // smallest version of the pagination
+    &.active,
+    &:first-child,
+    &:last-child {
+      display: flex;
+    }
+
+    &.active .page-link {
+      --bs-pagination-padding-y: 0;
+      --bs-pagination-padding-x: .625rem;
+      color: var(--#{$prefix}pagination-color);
+      background-color: var(--#{$prefix}pagination-bg);
+      border-color: transparent;
+    }
   }
 }
 // scss-docs-end pagination-max-items-mixin

site/assets/scss/_component-examples.scss

@@ -407,3 +407,24 @@
     @include border-top-radius(calc(var(--bs-border-radius) + 1px));
   }
 }
+
+// Boosted mod: allow to display smart responsive pagination behavior in the docs
+// when `$enable-responsive-pagination` is enabled (see site/assets/scss/docs.scss)
+.bd-example-responsive-pagination {
+  // scss-docs-start pagination-mixin-use
+  .page-item {
+    @include media-breakpoint-down(sm) {
+      @include pagination-max-items(3);
+    }
+
+    @include media-breakpoint-between(sm, md) {
+      @include pagination-max-items(10);
+    }
+
+    @include media-breakpoint-up(md) {
+      @include pagination-max-items(12);
+    }
+  }
+  // scss-docs-end pagination-mixin-use
+}
+// End mod

site/assets/scss/docs.scss

@@ -24,6 +24,17 @@
 
 // Load Bootstrap variables and mixins
 @import "../../../scss/functions";
+
+// Boosted mod
+// To display a smart responsive pagination example in our docs, we can enable `$enable-responsive-pagination` here.
+// It won't have any effects on the normal use cases since boosted.css is generated with `$enable-responsive-pagination: false` by default.
+// Since for this docs.scss we don't import "_pagination.scss" the definition of this variable requires a replay of the mixins
+// related to the smart responsive pagination (see site/assets/scss/_component-examples.scss).
+// fusv-disable
+$enable-responsive-pagination: true;
+// fusv-enable
+// End mod
+
 @import "../../../scss/variables";
 @import "../../../scss/mixins";
 

site/content/docs/5.3/components/pagination.md

@@ -121,18 +121,92 @@ Or with `.justify-content-end`:
 <!-- Boosted mod -->
 ## Responsive behavior
 
-To avoid pagination wrapping or overflowing, we limit the number or pagination item to display depending on breakpoint.
+By default, every item is visible. Here is an example with our basic responsive behavior.
 
 {{< example >}}
 <nav aria-label="Page navigation example">
-  <ul class="pagination">
-    <li class="page-item disabled"><a class="page-link">Previous</a></li>
+  <ul class="pagination justify-content-center">
+    <li class="page-item"><a class="page-link" href="#" aria-label="Previous"></a></li>
     <li class="page-item"><a class="page-link" href="#">1</a></li>
     <li class="page-item"><a class="page-link" href="#">2</a></li>
     <li class="page-item"><a class="page-link" href="#">3</a></li>
     <li class="page-item"><a class="page-link" href="#">4</a></li>
     <li class="page-item active" aria-current="page">
-      <a class="page-link" href="#">5</a>
+      <span class="page-link">5</span>
+    </li>
+    <li class="page-item"><a class="page-link" href="#">6</a></li>
+    <li class="page-item"><a class="page-link" href="#">7</a></li>
+    <li class="page-item"><a class="page-link" href="#">8</a></li>
+    <li class="page-item"><a class="page-link" href="#">9</a></li>
+    <li class="page-item"><a class="page-link" href="#">10</a></li>
+    <li class="page-item"><a class="page-link" href="#" aria-label="Next"></a></li>
+  </ul>
+</nav>
+{{< /example >}}
+
+You may use `.page-ellipsis` to build your own custom pagination. It places `...` right after the number it's applied on.
+
+{{< example class="px-0 px-sm-3" >}}
+<nav aria-label="Page navigation example with ellipsis">
+  <ul class="pagination justify-content-center">
+    <li class="page-item"><a class="page-link" href="#" aria-label="Previous"></a></li>
+    <li class="page-item page-ellipsis"><a class="page-link" href="#">1</a></li>
+    <li class="page-item page-ellipsis active" aria-current="page">
+      <span class="page-link">5</span>
+    </li>
+    <li class="page-item"><a class="page-link" href="#">10</a></li>
+    <li class="page-item"><a class="page-link" href="#" aria-label="Next"></a></li>
+  </ul>
+</nav>
+{{< /example >}}
+
+{{< callout warning >}}
+**Heads up—our smart responsive pagination is opt-out as of v5.3.0!**
+
+It means that it is disabled by default in order to have a lighter CSS bundle. We included it here in our documentation's CSS for this specific use case just as a demonstration of the rendering.
+
+<details class="border-top border-bottom border-1 border-light">
+<summary class="fw-bold p-2 mb-0">
+{{< markdown >}}
+Enable the responsive pagination by setting `$enable-responsive-pagination: true;`
+{{< /markdown >}}
+</summary>
+{{< markdown >}}
+
+```scss
+// Required
+@import "../node_modules/boosted/scss/functions";
+
+// Activate responsive pagination
+$enable-responsive-pagination: true;
+
+// Required
+@import "../node_modules/boosted/scss/variables";
+@import "../node_modules/boosted/scss/mixins";
+@import "../node_modules/boosted/scss/grid";
+
+// Optional Boosted components here
+@import "../node_modules/boosted/scss/pagination";
+```
+Then, recompile your Sass.
+{{< /markdown >}}
+</details>
+{{< /callout >}}
+
+The following example uses our smart responsive pagination. To avoid pagination wrapping or overflowing, we limit the number of displayed pagination items depending on the breakpoints by displaying automatically some ellipsis.
+
+Given that container queries lack adequate support, we offer an alternative solution that relies on page breakpoints. Nonetheless, our solution remains flexible and can be tailored to specific requirements using our [Sass mixin](#usage).
+
+{{< example class="bd-example-responsive-pagination px-0 px-sm-3" >}}
+<nav aria-label="Smart responsive page navigation example">
+  <ul class="pagination justify-content-center">
+    <li class="page-item"><a class="page-link" href="#" aria-label="Previous"></a></li>
+    <li class="page-item"><a class="page-link" href="#">1</a></li>
+    <li class="page-item"><a class="page-link" href="#">2</a></li>
+    <li class="page-item"><a class="page-link" href="#">3</a></li>
+    <li class="page-item"><a class="page-link" href="#">4</a></li>
+    <li class="page-item active" aria-current="page">
+      <span class="page-link"><span class="d-sm-none">Page</span>&nbsp;<span class="test">5</span>&nbsp;<span class="d-sm-none">of 10</span></span>
     </li>
     <li class="page-item"><a class="page-link" href="#">6</a></li>
     <li class="page-item"><a class="page-link" href="#">7</a></li>
@@ -198,4 +272,22 @@ Variables for the [dark pagination](#dark-variant):
 {{< scss-docs name="pagination-mixin" file="scss/mixins/_pagination.scss" >}}
 
 <!-- Boosted mod: responsive behavior -->
+The mixin is used to display a specified number of items, with the option to display a smaller version of the pagination if there are more items than the specified number. Under 7, it will display the smallest version.
+
+The `$pagination-max-items` parameter is used to specify the maximum number of items to be displayed, and defaults to 12 if not specified. The mixin needs to be applied on top of `.page-item` element.
+
+Overall, the mixin is a useful tool for controlling the display of items on a webpage and improving user experience by avoiding overwhelming them with too much content at once.
+
+See below how to use it for a proper [usage](#usage).
+
 {{< scss-docs name="pagination-max-items-mixin" file="scss/mixins/_pagination.scss" >}}
+
+#### Usage
+
+Here's an example of how you can use our responsive mixin to specify breakpoint `pagination-max-items` numbers for specific elements. This is the default behavior for our page-specific elements.
+
+Be sure to use unrelated media queries, otherwise there might be issues with some overlapping rules due to half-hardcoded Sass rules.
+
+{{< scss-docs name="pagination-mixin-use" file="site/assets/scss/_component-examples.scss" >}}
+
+<!-- Will maybe need a specific example page -->

site/content/docs/5.3/customize/options.md

@@ -32,4 +32,5 @@ You can find and customize these variables for key global options in Boosted's `
 | `$enable-important-utilities`  | `true` (default) or `false`           | Enables the `!important` suffix in utility classes. |
 | `$enable-smooth-scroll`        | `true` (default) or `false`           | Applies `scroll-behavior: smooth` globally, except for users asking for reduced motion through [`prefers-reduced-motion` media query]({{< docsref "/getting-started/accessibility#reduced-motion" >}}) |
 | `$enable-fixed-header`         | `true` (default) or `false`           | Set `scroll-padding-top` rule to root element, preventing focus from being hidden under a fixed header. |
+| `$enable-responsive-pagination` | `true` or `false` (default)          | Enables an automatic CSS responsive handling for the pagination meaning you may not handle it in the backend. |
 {{< /bs-table >}}

site/content/docs/5.3/migration.md

@@ -89,6 +89,11 @@ Learn more by reading the new [color modes documentation]({{< docsref "/customiz
 - **Orange footer**
   - <span class="badge bg-warning">Warning</span> For accessibility reasons, having a `aria-labelledby` on the collapse element in the accordions used in Orange footer is not necessary and can be removed. Be careful to not remove the corresponding `id` if used for other purposes. Please reflect these modifications into your websites.
 
+- **Pagination**
+  - <span class="badge bg-success">New</span> Added `.page-ellipsis` to help building your pagination.
+  - <span class="badge bg-warning">Warning</span> Modifications to the Sass mixin `pagination-max-items` have been made to ensure it can handle odd numbers without failing. Additionally, slight adjustments to its behavior to enhance its suitability for smaller viewports were made. The active element was also replaced from an `<a>` to a `<span>` to address design and accessibility issues. Please reflect these modifications in your websites.
+  - <span class="badge bg-danger">Breaking</span> A new variable `$enable-responsive-pagination` which alters the default behavior of our responsive component was introduced. Please check whether you need to modify it to suit your needs.
+
 - **Progress bars**
   - The markup for [progress bars]({{< docsref "/components/progress" >}}) has been updated in v5.3.0. Due to the placement of `role` and various `aria-` attributes on the inner `.progress-bar` element, **some screen readers were not announcing zero value progress bars**. Now, `role="progressbar"` and the relevant `aria-*` attributes are on the outer `.progress` element, leaving the `.progress-bar` purely for the visual presentation of the bar and optional label.