From ce7cedb9506c80c65cdf1ac13cdc8bc5496f1ca6 Mon Sep 17 00:00:00 2001
From: ericdouglaspratt <eric.pratt@energysage.com>
Date: Mon, 25 Nov 2024 15:14:48 -0500
Subject: [PATCH 1/3] feat: fixed EsCarousel arrows and allowed customization

---
 es-ds-components/components/es-carousel.vue | 340 +++++++++++++++++---
 es-ds-docs/pages/organisms/carousel.vue     | 138 +++++---
 2 files changed, 398 insertions(+), 80 deletions(-)

diff --git a/es-ds-components/components/es-carousel.vue b/es-ds-components/components/es-carousel.vue
index 09e64fd71..079f4231b 100644
--- a/es-ds-components/components/es-carousel.vue
+++ b/es-ds-components/components/es-carousel.vue
@@ -1,40 +1,59 @@
 <script setup lang="ts">
 /*
     TODO:
-     - responsive carousels briefly show mobile amount of dots on desktop, until hydration
-        - i think we may be able to fix this with CSS, because we know how many dots there should be
-        - (something PrimeVue Carousel should really be doing)
      - circular has quirky behavior when numVisible doesn't match numScroll
         - you can see this in the circular autoplay example
         - i'm not sure if this is fixable
+     - figure out peek behavior
+     - prop to position the arrows at the bottom two corners of a full-width slide, like homepage
 */
 
 import Carousel from 'primevue/carousel';
 import sassBreakpoints from '@energysage/es-ds-styles/scss/modules/breakpoints.module.scss';
 import type { EsCarouselBreakpointsInterface } from '../types';
 
+// this isn't set in a SASS variable so we can't import it, but it's
+// defined as a constant here so we can easily change it if we need to
+const BASE_FONT_SIZE = 16;
+
+// constants that contribute to dots and arrows positioning
+const DOT_SIZE = 14;
+const DOT_SPACING = 16;
+const ARROW_BUTTON_PADDING = 8;
+
+// the number of "dots" apart the arrows should be when dots are hidden
+const ARROW_SPACING_WHEN_NO_DOTS = 1;
+
 interface IProps {
+    arrowSize?: 'sm' | 'lg';
     autoPlay?: boolean;
     autoPlayInterval?: number;
     breakpoints?: EsCarouselBreakpointsInterface;
     circular?: boolean;
+    controlGap?: number;
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     items: Array<any>;
     numScroll?: number;
     numVisible?: number;
     showArrows?: boolean;
     showDots?: boolean;
+    slideGap?: number;
+    variant?: 'default' | 'brand';
 }
 const props = withDefaults(defineProps<IProps>(), {
+    arrowSize: 'sm',
     autoPlay: false,
-    autoPlayInterval: 2000,
+    autoPlayInterval: 4000,
     breakpoints: () => ({}),
     circular: false,
+    controlGap: 24,
     items: () => [],
     numScroll: 1,
     numVisible: 1,
     showArrows: true,
     showDots: true,
+    slideGap: 16,
+    variant: 'default',
 });
 
 const emit = defineEmits<{
@@ -67,16 +86,82 @@ const numScrollLg = computed(() => props.breakpoints?.lg?.numScroll || numScroll
 const numScrollXl = computed(() => props.breakpoints?.xl?.numScroll || numScrollLg.value);
 const numScrollXxl = computed(() => props.breakpoints?.xxl?.numScroll || numScrollXl.value);
 
-// in order to enable full-width carousels with one item
-// but also ensure there is some space between items when more than one is visible
-// only apply horizontal padding to carousel items on breakpoints where more than one item is visible
-const DEFAULT_PADDING = '0.5rem';
-const paddingXs = computed(() => (numVisibleXs.value === 1 ? '0' : DEFAULT_PADDING));
-const paddingSm = computed(() => (numVisibleSm.value === 1 ? '0' : DEFAULT_PADDING));
-const paddingMd = computed(() => (numVisibleMd.value === 1 ? '0' : DEFAULT_PADDING));
-const paddingLg = computed(() => (numVisibleLg.value === 1 ? '0' : DEFAULT_PADDING));
-const paddingXl = computed(() => (numVisibleXl.value === 1 ? '0' : DEFAULT_PADDING));
-const paddingXxl = computed(() => (numVisibleXxl.value === 1 ? '0' : DEFAULT_PADDING));
+// allow customizable spacing between slides
+// but since that's done as side padding around each slide, which moves them in from the container edge
+// to get slides to left and right align with page content
+// we apply a negative margin to either side to bring the container edges back out to match
+const sidePadding = computed(() => `${props.slideGap / 2 / BASE_FONT_SIZE}rem`);
+const negativeMargin = computed(() => `-${sidePadding.value}`);
+
+// size of dots and spacing between dots
+const dotSize = `${DOT_SIZE / BASE_FONT_SIZE}rem`;
+const dotSpacing = `${DOT_SPACING / BASE_FONT_SIZE}rem`;
+
+// arrow padding
+const arrowPadding = `${ARROW_BUTTON_PADDING / BASE_FONT_SIZE}rem`;
+
+// arrow size
+const arrowSize = computed(() => (props.arrowSize === 'lg' ? 32 : 24));
+const arrowSizePx = computed(() => `${arrowSize.value}px`);
+const arrowButtonSize = computed(() => arrowSize.value + ARROW_BUTTON_PADDING * 2);
+
+// vertical positioning for the arrows
+const distanceFromCarouselBottomToCenterOfDots = computed(() => props.controlGap + DOT_SIZE / 2);
+const arrowPositionBottom = computed(
+    () => `-${distanceFromCarouselBottomToCenterOfDots.value + arrowButtonSize.value / 2}px`,
+);
+const dotsMarginTop = computed(() => `${props.controlGap / BASE_FONT_SIZE}rem`);
+
+// the number of dots visible at each breakpoint
+const numDotsXs = computed(() =>
+    props.showDots ? Math.ceil(props.items.length / numVisibleXs.value) : ARROW_SPACING_WHEN_NO_DOTS,
+);
+const numDotsSm = computed(() =>
+    props.showDots ? Math.ceil(props.items.length / numVisibleSm.value) : ARROW_SPACING_WHEN_NO_DOTS,
+);
+const numDotsMd = computed(() =>
+    props.showDots ? Math.ceil(props.items.length / numVisibleMd.value) : ARROW_SPACING_WHEN_NO_DOTS,
+);
+const numDotsLg = computed(() =>
+    props.showDots ? Math.ceil(props.items.length / numVisibleLg.value) : ARROW_SPACING_WHEN_NO_DOTS,
+);
+const numDotsXl = computed(() =>
+    props.showDots ? Math.ceil(props.items.length / numVisibleXl.value) : ARROW_SPACING_WHEN_NO_DOTS,
+);
+const numDotsXxl = computed(() =>
+    props.showDots ? Math.ceil(props.items.length / numVisibleXxl.value) : ARROW_SPACING_WHEN_NO_DOTS,
+);
+
+// calculate the arrow position from center based on the number of dots
+const calculateArrowPosition = (numDots: number): number =>
+    (numDots * DOT_SIZE) / 2 + (numDots * DOT_SPACING) / 2 + DOT_SPACING;
+
+// determine how much from center we need to move the arrow buttons, based on how many dots there are
+const arrowPositionXs = computed(() => calculateArrowPosition(numDotsXs.value));
+const arrowPositionSm = computed(() => calculateArrowPosition(numDotsSm.value));
+const arrowPositionMd = computed(() => calculateArrowPosition(numDotsMd.value));
+const arrowPositionLg = computed(() => calculateArrowPosition(numDotsLg.value));
+const arrowPositionXl = computed(() => calculateArrowPosition(numDotsXl.value));
+const arrowPositionXxl = computed(() => calculateArrowPosition(numDotsXxl.value));
+
+// prev button horizontal position
+const prevArrowTranslateXs = computed(() => `-${arrowPositionXs.value + arrowButtonSize.value}px`);
+const prevArrowTranslateSm = computed(() => `-${arrowPositionSm.value + arrowButtonSize.value}px`);
+const prevArrowTranslateMd = computed(() => `-${arrowPositionMd.value + arrowButtonSize.value}px`);
+const prevArrowTranslateLg = computed(() => `-${arrowPositionLg.value + arrowButtonSize.value}px`);
+const prevArrowTranslateXl = computed(() => `-${arrowPositionXl.value + arrowButtonSize.value}px`);
+const prevArrowTranslateXxl = computed(() => `-${arrowPositionXxl.value + arrowButtonSize.value}px`);
+
+// next arrow horizontal position
+const nextArrowTranslateXs = computed(() => `${arrowPositionXs.value}px`);
+const nextArrowTranslateSm = computed(() => `${arrowPositionSm.value}px`);
+const nextArrowTranslateMd = computed(() => `${arrowPositionMd.value}px`);
+const nextArrowTranslateLg = computed(() => `${arrowPositionLg.value}px`);
+const nextArrowTranslateXl = computed(() => `${arrowPositionXl.value}px`);
+const nextArrowTranslateXxl = computed(() => `${arrowPositionXxl.value}px`);
+
+// extra space to add below the carousel for the arrows when arrows are on but dots are off
+const arrowsOnlyBottomSpacing = computed(() => `${props.controlGap + arrowButtonSize.value}px`);
 
 const responsiveOptions = computed(() => {
     // if no special breakpoints are defined, don't pass in any responsive options
@@ -153,6 +238,9 @@ onMounted(() => {
      *
      * this workaround disables circular functionality for SSR, and swaps to the user-provided
      * setting for it on mount.
+     *
+     * this flag is also used to hide the extra dots from the mobile view on larger breakpoints
+     * before hydration occurs and the number of dots is adjusted to the breakpoint.
      */
     isMounted.value = true;
 
@@ -171,6 +259,18 @@ onMounted(() => {
         :key="key"
         :autoplay-interval="autoplayInterval"
         :circular="isMounted && props.circular"
+        class="es-carousel"
+        :class="{
+            'es-carousel--brand': props.variant === 'brand',
+            'arrows-only': props.showArrows && !props.showDots,
+            'before-mount': !isMounted,
+            dots: props.showDots,
+            [`num-dots-sm-${numDotsSm}`]: true,
+            [`num-dots-md-${numDotsMd}`]: true,
+            [`num-dots-lg-${numDotsLg}`]: true,
+            [`num-dots-xl-${numDotsXl}`]: true,
+            [`num-dots-xxl-${numDotsXxl}`]: true,
+        }"
         :num-scroll="props.numScroll"
         :num-visible="props.numVisible"
         :responsive-options="responsiveOptions"
@@ -179,13 +279,16 @@ onMounted(() => {
         :value="props.items"
         :pt="{
             container: {
-                class: 'd-flex',
+                class: 'es-carousel-container d-flex position-relative',
             },
             indicator: {
                 class: 'es-carousel-dot',
             },
             indicators: {
-                class: 'es-carousel-dots d-flex justify-content-center mt-100',
+                class: 'es-carousel-dots d-flex justify-content-center',
+            },
+            indicatorButton: {
+                class: 'd-block',
             },
             itemsContent: {
                 class: 'w-100 overflow-hidden',
@@ -200,10 +303,10 @@ onMounted(() => {
                 class: 'es-carousel-item',
             },
             previousButton: {
-                class: 'es-carousel-arrow es-carousel-prev-arrow btn btn-outline-primary px-sm-50',
+                class: 'es-carousel-arrow es-carousel-prev-arrow btn btn-outline-primary position-absolute px-sm-50',
             },
             nextButton: {
-                class: 'es-carousel-arrow es-carousel-next-arrow btn btn-outline-primary px-sm-50',
+                class: 'es-carousel-arrow es-carousel-next-arrow btn btn-outline-primary position-absolute px-sm-50',
             },
         }"
         @update:page="(value: number) => emit('update', value)">
@@ -224,53 +327,180 @@ onMounted(() => {
 <style lang="scss" scoped>
 @use '@energysage/es-ds-styles/scss/variables' as variables;
 @use '@energysage/es-ds-styles/scss/mixins/breakpoints' as breakpoints;
+@use 'sass:map';
+
+/**
+    solution for PrimeVue initially displaying the mobile breakpoint's number of dots on page load
+    until hydration, when it then adjusts to the actual breakpoint and corrects the number of dots
 
+    generate CSS classes for each breakpoint that hide the dots that should be hidden before mount
+*/
+$num-dots-supported: 8;
+.es-carousel.before-mount {
+    @each $breakpoint in map.keys(variables.$grid-breakpoints) {
+        @include breakpoints.media-breakpoint-up($breakpoint) {
+            $infix: breakpoints.breakpoint-infix($breakpoint, variables.$grid-breakpoints);
+            @for $i from 1 through $num-dots-supported {
+                &.num-dots#{$infix}-#{$i} :deep(.es-carousel-dot:nth-child(#{$i}) ~ .es-carousel-dot) {
+                    display: none;
+                }
+            }
+        }
+    }
+}
+
+/* arrows are positioned absolutely, so when arrows are shown but dots are not, we need to reserve space for them */
+.es-carousel.arrows-only {
+    padding-bottom: v-bind(arrowsOnlyBottomSpacing);
+}
+
+/* ensure there's enough space between the dots (when present) and the next content on the page */
+.es-carousel.dots {
+    padding-bottom: 0.25rem;
+}
+
+/* make the carousel card edges align with page content */
+:deep(.es-carousel-container) {
+    margin-left: v-bind(negativeMargin);
+    margin-right: v-bind(negativeMargin);
+}
+
+/* card sizing, based on num visible at each breakpoint */
 :deep(.es-carousel-item) {
     flex: 1 0 calc(100% / v-bind(numVisibleXs));
-    padding: 0 v-bind(paddingXs);
-}
+    padding: 0 v-bind(sidePadding);
 
-@include breakpoints.media-breakpoint-up(sm) {
-    :deep(.es-carousel-item) {
+    @include breakpoints.media-breakpoint-up(sm) {
         flex: 1 0 calc(100% / v-bind(numVisibleSm));
-        padding: 0 v-bind(paddingSm);
     }
-}
 
-@include breakpoints.media-breakpoint-up(md) {
-    :deep(.es-carousel-item) {
+    @include breakpoints.media-breakpoint-up(md) {
         flex: 1 0 calc(100% / v-bind(numVisibleMd));
-        padding: 0 v-bind(paddingMd);
     }
-}
 
-@include breakpoints.media-breakpoint-up(lg) {
-    :deep(.es-carousel-item) {
+    @include breakpoints.media-breakpoint-up(lg) {
         flex: 1 0 calc(100% / v-bind(numVisibleLg));
-        padding: 0 v-bind(paddingLg);
     }
-}
 
-@include breakpoints.media-breakpoint-up(xl) {
-    :deep(.es-carousel-item) {
+    @include breakpoints.media-breakpoint-up(xl) {
         flex: 1 0 calc(100% / v-bind(numVisibleXl));
-        padding: 0 v-bind(paddingXl);
     }
-}
 
-@include breakpoints.media-breakpoint-up(xxl) {
-    :deep(.es-carousel-item) {
+    @include breakpoints.media-breakpoint-up(xxl) {
         flex: 1 0 calc(100% / v-bind(numVisibleXxl));
-        padding: 0 v-bind(paddingXxl);
     }
 }
 
+/* previous arrow horizontal positioning at each breakpoint */
+:deep(.es-carousel-prev-arrow) {
+    transform: translateX(v-bind(prevArrowTranslateXs));
+
+    /* keep the "shift 1px down on click" transform from removing our transform */
+    &:not(:disabled):not(.disabled):active {
+        transform: translateX(v-bind(prevArrowTranslateXs)) translateY(1px);
+    }
+
+    @include breakpoints.media-breakpoint-up(sm) {
+        transform: translateX(v-bind(prevArrowTranslateSm));
+
+        &:not(:disabled):not(.disabled):active {
+            transform: translateX(v-bind(prevArrowTranslateSm)) translateY(1px);
+        }
+    }
+
+    @include breakpoints.media-breakpoint-up(md) {
+        transform: translateX(v-bind(prevArrowTranslateMd));
+
+        &:not(:disabled):not(.disabled):active {
+            transform: translateX(v-bind(prevArrowTranslateMd)) translateY(1px);
+        }
+    }
+
+    @include breakpoints.media-breakpoint-up(lg) {
+        transform: translateX(v-bind(prevArrowTranslateLg));
+
+        &:not(:disabled):not(.disabled):active {
+            transform: translateX(v-bind(prevArrowTranslateLg)) translateY(1px);
+        }
+    }
+
+    @include breakpoints.media-breakpoint-up(xl) {
+        transform: translateX(v-bind(prevArrowTranslateXl));
+
+        &:not(:disabled):not(.disabled):active {
+            transform: translateX(v-bind(prevArrowTranslateXl)) translateY(1px);
+        }
+    }
+
+    @include breakpoints.media-breakpoint-up(xxl) {
+        transform: translateX(v-bind(prevArrowTranslateXxl));
+
+        &:not(:disabled):not(.disabled):active {
+            transform: translateX(v-bind(prevArrowTranslateXxl)) translateY(1px);
+        }
+    }
+}
+
+/* next arrow horizontal positioning at each breakpoint */
+:deep(.es-carousel-next-arrow) {
+    transform: translateX(v-bind(nextArrowTranslateXs));
+
+    /* keep the "shift 1px down on click" transform from removing our transform */
+    &:not(:disabled):not(.disabled):active {
+        transform: translateX(v-bind(nextArrowTranslateXs)) translateY(1px);
+    }
+
+    @include breakpoints.media-breakpoint-up(sm) {
+        transform: translateX(v-bind(nextArrowTranslateSm));
+
+        &:not(:disabled):not(.disabled):active {
+            transform: translateX(v-bind(nextArrowTranslateSm)) translateY(1px);
+        }
+    }
+
+    @include breakpoints.media-breakpoint-up(md) {
+        transform: translateX(v-bind(nextArrowTranslateMd));
+
+        &:not(:disabled):not(.disabled):active {
+            transform: translateX(v-bind(nextArrowTranslateMd)) translateY(1px);
+        }
+    }
+
+    @include breakpoints.media-breakpoint-up(lg) {
+        transform: translateX(v-bind(nextArrowTranslateLg));
+
+        &:not(:disabled):not(.disabled):active {
+            transform: translateX(v-bind(nextArrowTranslateLg)) translateY(1px);
+        }
+    }
+
+    @include breakpoints.media-breakpoint-up(xl) {
+        transform: translateX(v-bind(nextArrowTranslateXl));
+
+        &:not(:disabled):not(.disabled):active {
+            transform: translateX(v-bind(nextArrowTranslateXl)) translateY(1px);
+        }
+    }
+
+    @include breakpoints.media-breakpoint-up(xxl) {
+        transform: translateX(v-bind(nextArrowTranslateXxl));
+
+        &:not(:disabled):not(.disabled):active {
+            transform: translateX(v-bind(nextArrowTranslateXxl)) translateY(1px);
+        }
+    }
+}
+
+/* prev/next arrow button styling */
 :deep(.es-carousel-arrow) {
     background: unset;
     border: unset;
+    bottom: v-bind(arrowPositionBottom);
     box-shadow: none;
     color: variables.$gray-900;
     height: auto;
+    left: 50%;
+    padding: v-bind(arrowPadding);
 
     &:hover {
         color: variables.$gray-700;
@@ -286,13 +516,39 @@ onMounted(() => {
     &:disabled {
         color: variables.$gray-400;
     }
+
+    svg {
+        /* use !important to override the inline style on svg icons */
+        height: v-bind(arrowSizePx) !important;
+        width: v-bind(arrowSizePx) !important;
+    }
+}
+
+/* prev/next arrow button styling for the "brand" variant */
+.es-carousel--brand {
+    :deep(.es-carousel-arrow) {
+        color: variables.$blue-600;
+
+        &:hover {
+            color: variables.$blue-700;
+        }
+        &:not(:disabled):not(.disabled):active {
+            color: variables.$blue-800;
+        }
+        &:disabled {
+            color: variables.$gray-400;
+        }
+    }
 }
 
+/* dots container */
 :deep(.es-carousel-dots) {
-    gap: 0.7rem;
+    gap: v-bind(dotSpacing);
     padding-left: 0;
+    margin-top: v-bind(dotsMarginTop);
 }
 
+/* each individual dot */
 :deep(.es-carousel-dot) {
     list-style-type: none;
     margin-bottom: 0;
@@ -305,9 +561,9 @@ onMounted(() => {
         background-color: variables.$gray-100;
         border: none;
         border-radius: 50%;
-        height: 0.875rem;
+        height: v-bind(dotSize);
         padding: 0;
-        width: 0.875rem;
+        width: v-bind(dotSize);
 
         &:hover {
             opacity: 0.8;
diff --git a/es-ds-docs/pages/organisms/carousel.vue b/es-ds-docs/pages/organisms/carousel.vue
index 5cd25babc..2e0ebae10 100644
--- a/es-ds-docs/pages/organisms/carousel.vue
+++ b/es-ds-docs/pages/organisms/carousel.vue
@@ -14,7 +14,14 @@ const SAMPLE_IMAGES = [
     'https://a-us.storyblok.com/f/1006159/810x473/a3a6b6d667/adding-solar-panels.jpg?cv=1728482273086',
 ];
 
-const basicExampleItems = SAMPLE_IMAGES.map((image, index) => ({
+// only six items to showcase best practices around not showing too many dots
+const basicExampleItems = SAMPLE_IMAGES.slice(0, 6).map((image, index) => ({
+    heading: `Item ${index + 1}`,
+    url: image,
+}));
+
+// use the full twelve items for the slideshow example since there's no dots
+const slideShowItems = SAMPLE_IMAGES.map((image, index) => ({
     heading: `Item ${index + 1}`,
     url: image,
 }));
@@ -36,6 +43,7 @@ onMounted(async () => {
 });
 
 const propTableRows = [
+    ['arrowSize', 'String', '"sm"', 'Takes either "sm" or "lg". Small size is 24px, large size is 32px.'],
     [
         'autoPlay',
         'Boolean',
@@ -45,7 +53,7 @@ const propTableRows = [
     [
         'autoPlayInterval',
         'Number',
-        '2000',
+        '4000',
         'If autoPlay is true, this determines the number of milliseconds between transitions.',
     ],
     [
@@ -60,6 +68,12 @@ const propTableRows = [
         'true',
         'Whether the carousel should stop paging at either end or start over from the beginning.',
     ],
+    [
+        'controlGap',
+        'Number',
+        '24',
+        'The spacing, in pixels, between the carousel slides and the controls that appear below.',
+    ],
     [
         'items',
         'Array',
@@ -78,8 +92,15 @@ const propTableRows = [
         '1',
         'The number of items visible at any one time. This is also used as the default mobile value when using breakpoints.',
     ],
-    ['showArrows', 'Boolean', 'true', 'Whether to show the arrows on either side of the carousel.'],
-    ['showDots', 'Boolean', 'true', 'Whether to show the dots at the bottom of the carousel.'],
+    ['showArrows', 'Boolean', 'true', 'Whether to show the arrows below the carousel.'],
+    ['showDots', 'Boolean', 'true', 'Whether to show the dots below the carousel.'],
+    ['slideGap', 'Number', '16', 'The spacing, in pixels, between each carousel slide.'],
+    [
+        'variant',
+        'String',
+        '"default"',
+        'Takes either "default" or "brand". Default means gray arrows, brand means blue arrows.',
+    ],
 ];
 
 const eventTableRows = [['update', 'value (Number)', 'Emitted when the visible page of the carousel changes.']];
@@ -100,9 +121,8 @@ const eventTableRows = [['update', 'value (Number)', 'Emitted when the visible p
         <div class="my-500">
             <h2>Basic example</h2>
             <p class="mb-200">
-                This example shows a responsive carousel with twelve items, rendered as cards with an image and
-                subtitle. Mobile sees one card at a time, which then increases to two, three, and four as the viewport
-                width increases.
+                This example shows a responsive carousel with six items, rendered as cards with an image and subtitle.
+                Mobile sees one card at a time, which then increases to two and three as the viewport width increases.
             </p>
             <es-carousel
                 :breakpoints="{
@@ -114,10 +134,6 @@ const eventTableRows = [['update', 'value (Number)', 'Emitted when the visible p
                         numScroll: 3,
                         numVisible: 3,
                     },
-                    xxl: {
-                        numScroll: 4,
-                        numVisible: 4,
-                    },
                 }"
                 :items="basicExampleItems">
                 <template #item="{ item }">
@@ -134,16 +150,9 @@ const eventTableRows = [['update', 'value (Number)', 'Emitted when the visible p
         </div>
 
         <div class="my-500">
-            <h2>Circular example</h2>
-            <p>
-                This example shows the same responsive carousel but with circular behavior turned on, meaning the user
-                can continue paging in one direction forever and the items from the beginning of the list will be
-                repeated once the end of the list is reached.
-            </p>
+            <h2>No dots</h2>
             <p class="mb-200">
-                Unless paging is done in a rapid-fire succession (the carousel needs a split second to add more hidden
-                items after a page transition completes), the next set of items will always appear to come from the
-                same direction as all previous items, even when circling back to the beginning of the list.
+                When dots are turned off, the arrows are spaced out more but still appear below the carousel.
             </p>
             <es-carousel
                 :breakpoints="{
@@ -155,13 +164,41 @@ const eventTableRows = [['update', 'value (Number)', 'Emitted when the visible p
                         numScroll: 3,
                         numVisible: 3,
                     },
-                    xxl: {
-                        numScroll: 4,
-                        numVisible: 4,
+                }"
+                :items="basicExampleItems"
+                :show-dots="false">
+                <template #item="{ item }">
+                    <es-card class="text-center">
+                        <nuxt-img
+                            class="mb-50 w-100"
+                            :src="item.url" />
+                        <p class="font-weight-semibold mb-0">
+                            {{ item.heading }}
+                        </p>
+                    </es-card>
+                </template>
+            </es-carousel>
+        </div>
+
+        <div class="my-500">
+            <h2>Customization</h2>
+            <p class="mb-200">
+                This example shows the ability to customize the gap between slides, the gap between the slides and the
+                controls, and the size and color of the arrow button icons.
+            </p>
+            <es-carousel
+                arrow-size="lg"
+                :breakpoints="{
+                    sm: {
+                        numScroll: 2,
+                        numVisible: 2,
                     },
                 }"
-                circular
-                :items="basicExampleItems">
+                :control-gap="48"
+                :items="basicExampleItems"
+                :show-dots="false"
+                :slide-gap="32"
+                variant="brand">
                 <template #item="{ item }">
                     <es-card class="text-center">
                         <nuxt-img
@@ -176,25 +213,26 @@ const eventTableRows = [['update', 'value (Number)', 'Emitted when the visible p
         </div>
 
         <div class="my-500">
-            <h2>Circular autoplay with hidden arrows and dots</h2>
+            <h2>Circular behavior</h2>
             <p>
-                This example shows the same twelve items, but with autoplay turned on, circular behavior enabled, the
-                arrows and dots hidden, and simplified to show a single item at a time on all breakpoints. The autoplay
-                interval has also been increased from the default two seconds to four seconds.
+                This setting allows the user to continue paging in one direction forever and the items from the
+                beginning of the list will be repeated once the end of the list is reached. It's recommended to show
+                the dots when the circular setting is enabled so the user knows when the end of the list is reached.
             </p>
             <p class="mb-200">
-                Pressing the Esc key will stop the autoplay and reset the carousel to the first item. This is an
-                important accessibility feature for screen readers, because the contents of each new slide brought into
-                view by autoplay are automatically read aloud, no matter where the user is on the page, which can be
-                distracting while trying to read through another part of the page.
+                Unless paging is done in a rapid-fire succession (the carousel needs a split second to add more hidden
+                items after a page transition completes), the next set of items will always appear to come from the
+                same direction as all previous items, even when circling back to the beginning of the list.
             </p>
             <es-carousel
-                auto-play
-                :auto-play-interval="4000"
+                :breakpoints="{
+                    sm: {
+                        numScroll: 2,
+                        numVisible: 2,
+                    },
+                }"
                 circular
-                :items="basicExampleItems"
-                :show-arrows="false"
-                :show-dots="false">
+                :items="basicExampleItems">
                 <template #item="{ item }">
                     <es-card class="text-center">
                         <nuxt-img
@@ -208,6 +246,30 @@ const eventTableRows = [['update', 'value (Number)', 'Emitted when the visible p
             </es-carousel>
         </div>
 
+        <div class="my-500">
+            <h2>Autoplay with circular behavior</h2>
+            <p>This example shows autoplay behavior with circular mode enabled, to show a slideshow of images.</p>
+            <p class="mb-200">
+                Pressing the Esc key will stop the autoplay and reset the carousel to the first item. This is an
+                important accessibility feature for screen readers, because the contents of each new slide brought into
+                view by autoplay are automatically read aloud, no matter where the user is on the page, which can be
+                distracting while trying to read through another part of the page.
+            </p>
+            <es-carousel
+                auto-play
+                circular
+                :items="slideShowItems"
+                :show-arrows="false"
+                :show-dots="false">
+                <template #item="{ item }">
+                    <nuxt-img
+                        :alt="item.heading"
+                        class="mb-50 w-100"
+                        :src="item.url" />
+                </template>
+            </es-carousel>
+        </div>
+
         <div class="mb-500">
             <h2>EsCarousel props</h2>
             <ds-prop-table :rows="propTableRows" />

From 23b8248494a5125cdf454e95dd14573cd540626d Mon Sep 17 00:00:00 2001
From: ericdouglaspratt <eric.pratt@energysage.com>
Date: Wed, 27 Nov 2024 05:32:48 -0500
Subject: [PATCH 2/3] refactor: removed props references in template

---
 es-ds-components/components/es-carousel.vue | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/es-ds-components/components/es-carousel.vue b/es-ds-components/components/es-carousel.vue
index 079f4231b..840eb7d75 100644
--- a/es-ds-components/components/es-carousel.vue
+++ b/es-ds-components/components/es-carousel.vue
@@ -258,25 +258,25 @@ onMounted(() => {
     <carousel
         :key="key"
         :autoplay-interval="autoplayInterval"
-        :circular="isMounted && props.circular"
+        :circular="isMounted && circular"
         class="es-carousel"
         :class="{
-            'es-carousel--brand': props.variant === 'brand',
-            'arrows-only': props.showArrows && !props.showDots,
+            'es-carousel--brand': variant === 'brand',
+            'arrows-only': showArrows && !showDots,
             'before-mount': !isMounted,
-            dots: props.showDots,
+            dots: showDots,
             [`num-dots-sm-${numDotsSm}`]: true,
             [`num-dots-md-${numDotsMd}`]: true,
             [`num-dots-lg-${numDotsLg}`]: true,
             [`num-dots-xl-${numDotsXl}`]: true,
             [`num-dots-xxl-${numDotsXxl}`]: true,
         }"
-        :num-scroll="props.numScroll"
-        :num-visible="props.numVisible"
+        :num-scroll="numScroll"
+        :num-visible="numVisible"
         :responsive-options="responsiveOptions"
-        :show-indicators="props.showDots"
-        :show-navigators="props.showArrows"
-        :value="props.items"
+        :show-indicators="showDots"
+        :show-navigators="showArrows"
+        :value="items"
         :pt="{
             container: {
                 class: 'es-carousel-container d-flex position-relative',

From 7f6ecfcd83f501d217b28b62f9515268b1601af7 Mon Sep 17 00:00:00 2001
From: ericdouglaspratt <eric.pratt@energysage.com>
Date: Wed, 27 Nov 2024 05:49:47 -0500
Subject: [PATCH 3/3] fix: circular carousel prev arrow no longer appears
 disabled briefly before mount

---
 es-ds-components/components/es-carousel.vue | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/es-ds-components/components/es-carousel.vue b/es-ds-components/components/es-carousel.vue
index 840eb7d75..f4d14d533 100644
--- a/es-ds-components/components/es-carousel.vue
+++ b/es-ds-components/components/es-carousel.vue
@@ -264,6 +264,7 @@ onMounted(() => {
             'es-carousel--brand': variant === 'brand',
             'arrows-only': showArrows && !showDots,
             'before-mount': !isMounted,
+            circular: circular,
             dots: showDots,
             [`num-dots-sm-${numDotsSm}`]: true,
             [`num-dots-md-${numDotsMd}`]: true,
@@ -349,6 +350,14 @@ $num-dots-supported: 8;
     }
 }
 
+/* prevent the prev arrow from looking disabled on circular carousels on first paint */
+.es-carousel.before-mount.circular :deep(.es-carousel-prev-arrow:disabled) {
+    color: variables.$gray-900;
+}
+.es-carousel.es-carousel--brand.before-mount.circular :deep(.es-carousel-prev-arrow:disabled) {
+    color: variables.$blue-900;
+}
+
 /* arrows are positioned absolutely, so when arrows are shown but dots are not, we need to reserve space for them */
 .es-carousel.arrows-only {
     padding-bottom: v-bind(arrowsOnlyBottomSpacing);