@energysage/es-ds-components 0.0.1 → 3.0.0-alpha.10

package/components/es-carousel.vue

@@ -0,0 +1,316 @@
+<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
+*/
+
+import Carousel from 'primevue/carousel';
+import sassBreakpoints from '@energysage/es-ds-styles/scss/modules/breakpoints.module.scss';
+import type { EsCarouselBreakpointsInterface } from '../types';
+
+interface IProps {
+    autoPlay?: boolean;
+    autoPlayInterval?: number;
+    breakpoints?: EsCarouselBreakpointsInterface;
+    circular?: boolean;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    items: Array<any>;
+    numScroll?: number;
+    numVisible?: number;
+    showArrows?: boolean;
+    showDots?: boolean;
+}
+const props = withDefaults(defineProps<IProps>(), {
+    autoPlay: false,
+    autoPlayInterval: 2000,
+    breakpoints: () => ({}),
+    circular: false,
+    items: () => [],
+    numScroll: 1,
+    numVisible: 1,
+    showArrows: true,
+    showDots: true,
+});
+
+const emit = defineEmits<{
+    update: [value: number];
+}>();
+
+// get the breakpoint pixel numbers from the SASS variables in es-ds-styles
+const parseSassBreakpoint = (breakpoint: string) => parseInt(breakpoint.replace('px', ''), 10);
+const BREAKPOINTS = {
+    SM: parseSassBreakpoint(sassBreakpoints.sm),
+    MD: parseSassBreakpoint(sassBreakpoints.md),
+    LG: parseSassBreakpoint(sassBreakpoints.lg),
+    XL: parseSassBreakpoint(sassBreakpoints.xl),
+    XXL: parseSassBreakpoint(sassBreakpoints.xxl),
+};
+
+// lower breakpoint values propagate to higher breakpoints unless overridden
+const numVisibleXs = computed(() => props.numVisible);
+const numVisibleSm = computed(() => props.breakpoints?.sm?.numVisible || numVisibleXs.value);
+const numVisibleMd = computed(() => props.breakpoints?.md?.numVisible || numVisibleSm.value);
+const numVisibleLg = computed(() => props.breakpoints?.lg?.numVisible || numVisibleMd.value);
+const numVisibleXl = computed(() => props.breakpoints?.xl?.numVisible || numVisibleLg.value);
+const numVisibleXxl = computed(() => props.breakpoints?.xxl?.numVisible || numVisibleXl.value);
+
+// lower breakpoint values propagate to higher breakpoints unless overridden
+const numScrollXs = computed(() => props.numScroll);
+const numScrollSm = computed(() => props.breakpoints?.sm?.numScroll || numScrollXs.value);
+const numScrollMd = computed(() => props.breakpoints?.md?.numScroll || numScrollSm.value);
+const numScrollLg = computed(() => props.breakpoints?.lg?.numScroll || numScrollMd.value);
+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));
+
+const responsiveOptions = computed(() => {
+    // if no special breakpoints are defined, don't pass in any responsive options
+    if (!Object.keys(props.breakpoints).length) {
+        return undefined;
+    }
+
+    return [
+        // XXL breakpoint
+        {
+            // max width of XXL is infinite, so let's use 9999px
+            breakpoint: '9999px',
+            numScroll: numScrollXxl.value,
+            numVisible: numVisibleXxl.value,
+        },
+        // XL breakpoint
+        {
+            // max width of XL is XXL minus one
+            breakpoint: `${BREAKPOINTS.XXL - 1}px`,
+            numScroll: numScrollXl.value,
+            numVisible: numVisibleXl.value,
+        },
+        // LG breakpoint
+        {
+            // max width of LG is XL minus one
+            breakpoint: `${BREAKPOINTS.XL - 1}px`,
+            numScroll: numScrollLg.value,
+            numVisible: numVisibleLg.value,
+        },
+        // MD breakpoint
+        {
+            // max width of MD is LG minus one
+            breakpoint: `${BREAKPOINTS.LG - 1}px`,
+            numScroll: numScrollMd.value,
+            numVisible: numVisibleMd.value,
+        },
+        // SM breakpoint
+        {
+            // max width of SM is MD minus one
+            breakpoint: `${BREAKPOINTS.MD - 1}px`,
+            numScroll: numScrollSm.value,
+            numVisible: numVisibleSm.value,
+        },
+        // XS breakpoint
+        // (this is necessary to avoid weird behavior on mobile)
+        {
+            // max width of XS is SM minus one
+            breakpoint: `${BREAKPOINTS.SM - 1}px`,
+            numScroll: props.numScroll,
+            numVisible: props.numVisible,
+        },
+    ];
+});
+
+const autoplayInterval = ref(props.autoPlay ? props.autoPlayInterval : 0);
+const isMounted = ref(false);
+const key = ref('');
+
+const stopAutoplay = () => {
+    if (autoplayInterval.value > 0) {
+        autoplayInterval.value = 0;
+        key.value = 'stopAutoplay';
+    }
+};
+
+onMounted(() => {
+    /**
+     * avoids an unavoidable SSR issue with responsive carousels (SSR can't know the breakpoint
+     * and therefore how many items need to be displayed per page) where circular carousels have
+     * their last few items cloned and inserted before the first item in the list, meaning on initial
+     * page render, you see those cloned last items listed first rather than the first item.
+     *
+     * then, upon hydration, the items change and the first item is then listed first.
+     *
+     * this workaround disables circular functionality for SSR, and swaps to the user-provided
+     * setting for it on mount.
+     */
+    isMounted.value = true;
+
+    document.addEventListener('keyup', (e) => {
+        if (e.key === 'Escape') {
+            // Stop carousel when user presses Escape key, in lieu of pause button
+            // https://www.w3.org/WAI/WCAG22/Techniques/general/G187.html
+            stopAutoplay();
+        }
+    });
+});
+</script>
+
+<template>
+    <carousel
+        :key="key"
+        :autoplay-interval="autoplayInterval"
+        :circular="isMounted && props.circular"
+        :num-scroll="props.numScroll"
+        :num-visible="props.numVisible"
+        :responsive-options="responsiveOptions"
+        :show-indicators="props.showDots"
+        :show-navigators="props.showArrows"
+        :value="props.items"
+        :pt="{
+            container: {
+                class: 'd-flex',
+            },
+            indicator: {
+                class: 'es-carousel-dot',
+            },
+            indicators: {
+                class: 'es-carousel-dots d-flex justify-content-center mt-100',
+            },
+            itemsContent: {
+                class: 'w-100 overflow-hidden',
+            },
+            itemsContainer: {
+                class: 'd-flex',
+            },
+            item: {
+                class: 'es-carousel-item',
+            },
+            itemCloned: {
+                class: 'es-carousel-item',
+            },
+            previousButton: {
+                class: 'es-carousel-arrow es-carousel-prev-arrow btn btn-outline-primary px-sm-50',
+            },
+            nextButton: {
+                class: 'es-carousel-arrow es-carousel-next-arrow btn btn-outline-primary px-sm-50',
+            },
+        }"
+        @update:page="(value: number) => emit('update', value)">
+        <template #item="item">
+            <slot
+                name="item"
+                :item="item.data" />
+        </template>
+        <template #previousicon>
+            <icon-chevron-left />
+        </template>
+        <template #nexticon>
+            <icon-chevron-right />
+        </template>
+    </carousel>
+</template>
+
+<style lang="scss" scoped>
+@use '@energysage/es-ds-styles/scss/variables' as variables;
+@use '@energysage/es-ds-styles/scss/mixins/breakpoints' as breakpoints;
+
+:deep(.es-carousel-item) {
+    flex: 1 0 calc(100% / v-bind(numVisibleXs));
+    padding: 0 v-bind(paddingXs);
+}
+
+@include breakpoints.media-breakpoint-up(sm) {
+    :deep(.es-carousel-item) {
+        flex: 1 0 calc(100% / v-bind(numVisibleSm));
+        padding: 0 v-bind(paddingSm);
+    }
+}
+
+@include breakpoints.media-breakpoint-up(md) {
+    :deep(.es-carousel-item) {
+        flex: 1 0 calc(100% / v-bind(numVisibleMd));
+        padding: 0 v-bind(paddingMd);
+    }
+}
+
+@include breakpoints.media-breakpoint-up(lg) {
+    :deep(.es-carousel-item) {
+        flex: 1 0 calc(100% / v-bind(numVisibleLg));
+        padding: 0 v-bind(paddingLg);
+    }
+}
+
+@include breakpoints.media-breakpoint-up(xl) {
+    :deep(.es-carousel-item) {
+        flex: 1 0 calc(100% / v-bind(numVisibleXl));
+        padding: 0 v-bind(paddingXl);
+    }
+}
+
+@include breakpoints.media-breakpoint-up(xxl) {
+    :deep(.es-carousel-item) {
+        flex: 1 0 calc(100% / v-bind(numVisibleXxl));
+        padding: 0 v-bind(paddingXxl);
+    }
+}
+
+:deep(.es-carousel-arrow) {
+    background: unset;
+    border: unset;
+    box-shadow: none;
+    color: variables.$gray-900;
+    height: auto;
+
+    &:hover {
+        color: variables.$gray-700;
+    }
+    &:focus {
+        color: variables.$gray-900;
+    }
+    &:not(:disabled):not(.disabled):active {
+        background: unset;
+        box-shadow: none;
+        color: variables.$gray-700;
+    }
+    &:disabled {
+        color: variables.$gray-400;
+    }
+}
+
+:deep(.es-carousel-dots) {
+    gap: 0.7rem;
+    padding-left: 0;
+}
+
+:deep(.es-carousel-dot) {
+    list-style-type: none;
+    margin-bottom: 0;
+
+    &[data-p-highlight='true'] button {
+        background-color: variables.$orange-800;
+    }
+
+    button {
+        background-color: variables.$gray-100;
+        border: none;
+        border-radius: 50%;
+        height: 0.875rem;
+        width: 0.875rem;
+
+        &:hover {
+            opacity: 0.8;
+        }
+    }
+}
+</style>

package/components/es-col.vue

@@ -0,0 +1,27 @@
+<script setup lang="ts">
+const props = defineProps<{
+    cols?: string;
+    sm?: string;
+    md?: string;
+    lg?: string;
+    xl?: string;
+    xxl?: string;
+}>();
+
+const undefinedSize = !(props.cols || props.sm || props.md || props.lg || props.xl || props.xxl);
+</script>
+
+<template>
+    <div
+        :class="{
+            col: undefinedSize,
+            [`col-${cols}`]: cols,
+            [`col-sm${sm ? `-${sm}` : ''}`]: sm !== undefined,
+            [`col-md${md ? `-${md}` : ''}`]: md !== undefined,
+            [`col-lg${lg ? `-${lg}` : ''}`]: lg !== undefined,
+            [`col-xl${xl ? `-${xl}` : ''}`]: xl !== undefined,
+            [`col-xxl${xxl ? `-${xxl}` : ''}`]: xxl !== undefined,
+        }">
+        <slot />
+    </div>
+</template>

package/components/es-collapse.vue

@@ -0,0 +1,83 @@
+<script setup lang="ts">
+import Panel from 'primevue/panel';
+
+const emit = defineEmits(['toggled', 'userClick']);
+
+const model = defineModel<boolean>();
+const props = defineProps({
+    border: {
+        type: Boolean,
+        default: true,
+    },
+    isProgrammaticUntilUserInput: {
+        type: Boolean,
+        default: true,
+    },
+    visible: {
+        type: Boolean,
+        default: false,
+    },
+});
+
+const userDeterminedState: Ref<boolean | null> = ref(null);
+
+// directly determines the expanded/collapsed state of the panel
+const expanded = computed(() => {
+    // if we are meant to start ignoring the programmatic incoming state as soon as the
+    // user interacts with the collapse, and if the user has interacted with the collapse,
+    // use the value from the user's interaction
+    if (props.isProgrammaticUntilUserInput && userDeterminedState.value !== null) {
+        return userDeterminedState.value;
+    }
+
+    // otherwise, use the one-way visible prop or the two-way v-model value
+    return props.visible || model.value;
+});
+
+const onClick = ({ value }: { value: boolean }) => {
+    // save the state toggled by the user
+    // convert from "collapsed" semantics internal to the primevue panel
+    // to the "expanded" semantics exposed by this component
+    userDeterminedState.value = !value;
+
+    // inform the v-model (if any) that the state has changed
+    model.value = !value;
+
+    // emit events indicating the state has changed
+    emit('toggled', !value);
+    emit('userClick', !value);
+};
+</script>
+
+<template>
+    <panel
+        :collapsed="!expanded"
+        :pt="{
+            header: 'align-items-center d-flex justify-content-between position-relative py-100',
+            icons: 'h-100 position-absolute w-100',
+            root: border ? 'border-bottom border-top' : '',
+            toggler: {
+                // eslint-disable-next-line max-len
+                class: 'es-collapse-toggler align-items-center btn btn-link d-flex h-100 inline justify-content-end rounded-0 p-0 position-absolute text-body w-100',
+            },
+            // https://vuejs.org/guide/built-ins/transition
+            transition: {
+                enterActiveClass: 'es-collapse-enter-active',
+                enterFromClass: 'es-collapse-enter-from',
+                enterToClass: 'es-collapse-enter-to',
+                leaveActiveClass: 'es-collapse-leave-active',
+                leaveFromClass: 'es-collapse-leave-from',
+                leaveToClass: 'es-collapse-leave-to',
+            },
+        }"
+        toggleable
+        @toggle="onClick">
+        <template #header>
+            <slot name="title" />
+        </template>
+        <template #togglericon>
+            <icon-chevron-down />
+        </template>
+        <slot />
+    </panel>
+</template>

package/components/es-container.vue

@@ -0,0 +1,14 @@
+<script setup lang="ts">
+interface IProps {
+    fluid?: boolean;
+}
+const props = withDefaults(defineProps<IProps>(), {
+    fluid: false,
+});
+</script>
+
+<template>
+    <div :class="props.fluid ? 'container-fluid' : 'container'">
+        <slot />
+    </div>
+</template>

package/components/es-cta-banner.vue

@@ -0,0 +1,95 @@
+<script setup lang="ts">
+const props = defineProps({
+    dark: {
+        type: Boolean,
+        default: false,
+    },
+    hasButton: {
+        type: Boolean,
+        default: false,
+    },
+    // default or wide
+    variant: {
+        type: String,
+        default: 'default',
+    },
+});
+
+const lgFirst = computed(() => {
+    if (props.variant === 'wide') {
+        return props.hasButton ? '8' : '6';
+    }
+
+    return props.hasButton ? '7' : '4';
+});
+
+const lgSecond = computed(() => {
+    if (props.variant === 'wide') {
+        return props.hasButton ? '4' : '6';
+    }
+
+    return props.hasButton ? '5' : '8';
+});
+
+const xxlFirst = computed(() => {
+    if (props.variant === 'wide') {
+        return props.hasButton ? '8' : '6';
+    }
+
+    return props.hasButton ? '8' : '5';
+});
+
+const xxlSecond = computed(() => {
+    if (props.variant === 'wide') {
+        return props.hasButton ? '4' : '6';
+    }
+
+    return props.hasButton ? '4' : '7';
+});
+</script>
+
+<template>
+    <es-card
+        :class="[
+            {
+                'bg-dark-blue border-dark-blue text-white': dark,
+                'px-100 px-lg-200': variant === 'default',
+                'px-100 px-lg-300': variant === 'wide',
+            },
+        ]"
+        v-bind="$attrs">
+        <es-row>
+            <es-col
+                class="mb-200 my-lg-auto text-center text-lg-left"
+                :lg="lgFirst"
+                :xxl="xxlFirst">
+                <!-- avoiding use of an <h2> tag here for long-form content SEO reasons,
+                    but preserving heading semantics for screen readers -->
+                <div
+                    role="heading"
+                    aria-level="2"
+                    class="font-weight-semibold"
+                    :class="{
+                        'font-size-300': variant === 'default',
+                        'mb-50': $slots.subtitle,
+                        'mb-0': !$slots.subtitle,
+                        'text-white': dark,
+                        h2: variant === 'wide',
+                    }">
+                    <slot name="heading"> Easily find what solar costs in your area </slot>
+                </div>
+                <p
+                    v-if="$slots.subtitle"
+                    class="mb-0">
+                    <slot name="subtitle" />
+                </p>
+            </es-col>
+            <es-col
+                class="d-flex justify-content-center justify-content-lg-end my-auto"
+                :lg="lgSecond"
+                :xxl="xxlSecond">
+                <slot name="cta" />
+            </es-col>
+        </es-row>
+    </es-card>
+</template>

package/components/es-cta-card.vue

@@ -0,0 +1,60 @@
+<script setup lang="ts">
+const props = defineProps({
+    imageFirst: {
+        type: Boolean,
+        default: false,
+    },
+    horizontalPadding: {
+        type: String,
+        default: 'px-100',
+    },
+    verticalSpacing: {
+        type: String,
+        default: 'mb-150',
+    },
+});
+</script>
+
+<template>
+    <es-card
+        class="align-items-center d-flex flex-column py-200 text-center"
+        :class="props.horizontalPadding"
+        v-bind="$attrs">
+        <!-- avoiding use of an <h2> tag here for long-form content SEO reasons,
+            but preserving heading semantics for screen readers -->
+        <div
+            role="heading"
+            aria-level="2"
+            class="font-weight-semibold font-size-300"
+            :class="[{ 'order-1': props.imageFirst }, props.verticalSpacing]">
+            <slot name="heading"> Easily find what solar costs in your area </slot>
+        </div>
+        <div
+            v-if="$slots.image"
+            class="mx-auto w-100"
+            :class="props.verticalSpacing">
+            <slot name="image" />
+        </div>
+        <div
+            class="w-100"
+            :class="{ 'order-2': props.imageFirst }">
+            <div
+                v-if="$slots.subtitle"
+                class="es-cta-card-subtitle"
+                :class="props.verticalSpacing">
+                <slot name="subtitle" />
+            </div>
+            <slot name="cta" />
+        </div>
+    </es-card>
+</template>
+
+<style lang="scss" scoped>
+.es-cta-card {
+    &-subtitle {
+        :deep(p:last-child) {
+            margin-bottom: 0;
+        }
+    }
+}
+</style>

package/components/es-data-table-simple.vue

@@ -0,0 +1,73 @@
+<script setup lang="ts">
+const props = defineProps({
+    fields: {
+        type: Array,
+        default: null,
+    },
+    items: {
+        type: Array,
+        default: () => [],
+    },
+    tableClass: {
+        type: [Array, String],
+        default: null,
+    },
+    striped: {
+        type: Boolean,
+        default: false,
+    },
+});
+
+const isSingleCol = computed(() => !props.fields);
+const computedItems: ComputedRef<any[]> = computed(() => {
+    if (!props.items.length && !useSlots().default) {
+        throw new Error('Neither items prop nor slot content is defined.');
+    }
+    // If there are no fields, just return the items as a single-column array
+    if (!props.fields) {
+        return props.items;
+    }
+    if (props.fields.length !== props.items.length) {
+        throw new Error('The number of fields and items must be the same.');
+    }
+    // If fields and items are both present, map them together
+    return props.fields.map((field, index) => [field, props.items[index]]);
+});
+</script>
+<template>
+    <div
+        :class="tableClass"
+        class="table-responsive">
+        <table
+            v-if="$slots.default || items.length"
+            class="table table-borderless"
+            :class="{ 'table-striped': striped }">
+            <template v-if="$slots.default">
+                <slot />
+            </template>
+            <tbody v-else>
+                <template v-if="isSingleCol">
+                    <tr
+                        v-for="(item, index) in computedItems"
+                        :key="`${index}${item}`">
+                        <td>
+                            {{ item }}
+                        </td>
+                    </tr>
+                </template>
+                <template v-else>
+                    <tr
+                        v-for="(item, index) in computedItems"
+                        :key="`${index}${item[0]}`">
+                        <td class="col-sm-7">
+                            {{ item[0] }}
+                        </td>
+                        <td class="col-sm-4">
+                            <b>{{ item[1] }}</b>
+                        </td>
+                    </tr>
+                </template>
+            </tbody>
+        </table>
+    </div>
+</template>