@kiva/kv-components 3.105.2 → 3.106.0

package/CHANGELOG.md

@@ -3,6 +3,25 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [3.106.0](https://github.com/kiva/kv-ui-elements/compare/@kiva/kv-components@3.105.3...@kiva/kv-components@3.106.0) (2024-11-01)
+
+
+### Features
+
+* basic vertical carousel ([6a40563](https://github.com/kiva/kv-ui-elements/commit/6a405637ee4186d3cb5a7dbf71f87d8a04d46d86))
+
+
+
+
+
+## [3.105.3](https://github.com/kiva/kv-ui-elements/compare/@kiva/kv-components@3.105.2...@kiva/kv-components@3.105.3) (2024-10-28)
+
+**Note:** Version bump only for package @kiva/kv-components
+
+
+
+
+
 ## [3.105.2](https://github.com/kiva/kv-ui-elements/compare/@kiva/kv-components@3.105.1...@kiva/kv-components@3.105.2) (2024-10-25)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kiva/kv-components",
-  "version": "3.105.2",
+  "version": "3.106.0",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -83,5 +83,5 @@
       "optional": true
     }
   },
-  "gitHead": "1eb69b9a5626681003c8bf9569e64e3fc51801c4"
+  "gitHead": "c195fd4d6bf8055879846dc5821873e9bc336f1c"
 }

package/utils/carousels.js

@@ -0,0 +1,190 @@
+/* eslint-disable import/prefer-default-export */
+import {
+	computed,
+	onMounted,
+	onUnmounted,
+	ref,
+	toRefs,
+	nextTick,
+} from 'vue-demi';
+import EmblaCarousel from 'embla-carousel';
+import { throttle } from './throttle';
+
+export function carouselUtil(props, { emit, slots }, extraEmblaOptions) {
+	const {
+		emblaOptions,
+		slidesToScroll,
+	} = toRefs(props);
+	const rootEl = ref(null);
+	const embla = ref(null);
+	const slides = ref([]);
+	const startIndex = emblaOptions.value?.startIndex ?? 0;
+	const currentIndex = ref(startIndex);
+	// The indicator count may differ from the slide count when multiple slides are in view
+	const slideIndicatorCount = ref(0);
+
+	const componentSlotKeys = computed(() => {
+		const keys = Object.keys(slots);
+		return keys;
+	});
+
+	const nextIndex = computed(() => {
+		const nextSlideIndex = currentIndex.value + 1;
+		if (nextSlideIndex < slides.value.length) {
+			return nextSlideIndex;
+		}
+		return 0;
+	});
+
+	const previousIndex = computed(() => {
+		const previousSlideIndex = currentIndex.value - 1;
+		if (previousSlideIndex >= 0) {
+			return previousSlideIndex;
+		}
+		return slides.value.length - 1;
+	});
+
+	/**
+	 * Jump to a specific slide index
+	 *
+	 * @param {Number} num Index of slide to show
+	 * @public This is a public method
+	 */
+	const goToSlide = (index) => {
+		embla.value.scrollTo(index);
+	};
+	const handleUserInteraction = async (index, interactionType) => {
+		if (index !== null && typeof index !== 'undefined') {
+			await nextTick(); // wait for embla.
+			goToSlide(index);
+		}
+		/**
+		 * Fires when the user interacts with the carousel.
+		 * Contains the interaction type (swipe-left, click-left-arrow, etc.)
+		 * @event interact-carousel
+		 * @type {Event}
+		 */
+		emit('interact-carousel', interactionType);
+	};
+
+	/**
+	 * Returns number of slides in the carousel
+	 *
+	 * @returns {Number}
+	 */
+	const slideIndicatorListLength = () => {
+		const indicator = embla.value ? embla.value.scrollSnapList().length : 0;
+		slideIndicatorCount.value = indicator;
+		return indicator;
+	};
+
+	/**
+	 * Reinitialize the carousel.
+	 * Used after adding slides dynamically.
+	 *
+	 * @public This is a public method
+	 */
+	const reInitVisible = () => {
+		const slidesInView = embla.value.slidesInView(true).length;
+		if (slidesInView) {
+			embla.value.reInit({
+				slidesToScroll: slidesInView,
+				inViewThreshold: 0.9,
+			});
+		}
+	};
+	const reInit = () => {
+		embla.value.reInit();
+		if (slidesToScroll.value === 'visible') {
+			reInitVisible();
+		}
+		slides.value = embla.value.slideNodes();
+		slideIndicatorListLength();
+	};
+	const onCarouselContainerClick = (e) => {
+		// If we're dragging, block click handlers within slides
+		if (embla.value && !embla.value.clickAllowed()) {
+			e.preventDefault();
+			e.stopPropagation();
+		}
+	};
+	/**
+	 * If the slide is not completely in view in the carousel
+	 * it should be aria-hidden
+	 *
+	 * @param {Number} index The current index of the slide
+	 * @returns {Boolean}
+	 */
+	const isAriaHidden = (index) => {
+		if (embla.value) {
+			return !embla.value.slidesInView(true).includes(index);
+		}
+		return false;
+	};
+
+	onMounted(async () => {
+		embla.value = EmblaCarousel(rootEl.value, {
+			loop: true,
+			containScroll: 'trimSnaps',
+			inViewThreshold: 0.9,
+			align: 'start',
+			...extraEmblaOptions,
+			...emblaOptions.value,
+		});
+
+		if (slidesToScroll.value === 'visible') {
+			reInitVisible();
+
+			embla.value.on(
+				'resize',
+				throttle(() => {
+					embla.value.reInit({
+						slidesToScroll: embla.value.slidesInView(true).length || 'auto',
+						inViewThreshold: 0.9,
+					});
+					slides.value = embla.value.slideNodes();
+					slideIndicatorListLength();
+				}, 250),
+			);
+		}
+
+		// get slide components
+		slides.value = embla.value.slideNodes();
+		slideIndicatorListLength();
+
+		embla?.value?.on('select', () => {
+			currentIndex.value = embla.value.selectedScrollSnap();
+			/**
+			 * The index of the slide that the carousel has changed to
+			 * @event change
+			 * @type {Event}
+			 */
+			nextTick(() => {
+				emit('change', currentIndex);
+			});
+		});
+	});
+
+	onUnmounted(async () => {
+		embla?.value?.off('select');
+		embla?.value?.destroy();
+	});
+
+	return {
+		rootEl,
+		embla,
+		slides,
+		currentIndex,
+		componentSlotKeys,
+		nextIndex,
+		previousIndex,
+		slideIndicatorCount,
+		handleUserInteraction,
+		goToSlide,
+		reInit,
+		reInitVisible,
+		onCarouselContainerClick,
+		isAriaHidden,
+		slideIndicatorListLength,
+	};
+}

package/vue/KvCarousel.vue

@@ -23,7 +23,7 @@
 				:aria-current="currentIndex === index ? 'true' : 'false'"
 				:aria-hidden="isAriaHidden(index)? 'true' : 'false'"
 				:tab-index="isAriaHidden(index) ? '-1' : false"
-				:class="{ 'tw-w-full': !multipleSlidesVisible || slideMaxWidth, 'cirle-slide': inCircle }"
+				:class="{ 'tw-w-full': !multipleSlidesVisible || slideMaxWidth, 'circle-slide': inCircle }"
 				:style="slideMaxWidth ? `max-width:${slideMaxWidth}` :''"
 			>
 				<slot
@@ -146,22 +146,13 @@
 </template>
 
 <script>
-import {
-	computed,
-	onMounted,
-	onUnmounted,
-	ref,
-	toRefs,
-	nextTick,
-} from 'vue-demi';
-import EmblaCarousel from 'embla-carousel';
 import {
 	mdiChevronLeft,
 	mdiChevronRight,
 	mdiArrowLeft,
 	mdiArrowRight,
 } from '@mdi/js';
-import { throttle } from '../utils/throttle';
+import { carouselUtil } from '../utils/carousels';
 
 import KvMaterialIcon from './KvMaterialIcon.vue';
 
@@ -236,183 +227,43 @@ export default {
 	],
 	setup(props, { emit, slots }) {
 		const {
-			emblaOptions,
-			slidesToScroll,
-		} = toRefs(props);
-		const rootEl = ref(null);
-		const embla = ref(null);
-		const slides = ref([]);
-		const startIndex = emblaOptions.value?.startIndex ?? 0;
-		const currentIndex = ref(startIndex);
-		// The indicator count may differ from the slide count when multiple slides are in view
-		const slideIndicatorCount = ref(0);
-
-		const componentSlotKeys = computed(() => {
-			const keys = Object.keys(slots);
-			return keys;
-		});
-
-		const nextIndex = computed(() => {
-			const nextSlideIndex = currentIndex.value + 1;
-			if (nextSlideIndex < slides.value.length) {
-				return nextSlideIndex;
-			}
-			return 0;
-		});
-
-		const previousIndex = computed(() => {
-			const previousSlideIndex = currentIndex.value - 1;
-			if (previousSlideIndex >= 0) {
-				return previousSlideIndex;
-			}
-			return slides.value.length - 1;
-		});
-
-		/**
-		 * Jump to a specific slide index
-		 *
-		 * @param {Number} num Index of slide to show
-		 * @public This is a public method
-		 */
-		const goToSlide = (index) => {
-			embla.value.scrollTo(index);
-		};
-		const handleUserInteraction = async (index, interactionType) => {
-			if (index !== null && typeof index !== 'undefined') {
-				await nextTick(); // wait for embla.
-				goToSlide(index);
-			}
-			/**
-			 * Fires when the user interacts with the carousel.
-			 * Contains the interaction type (swipe-left, click-left-arrow, etc.)
-			 * @event interact-carousel
-			 * @type {Event}
-			 */
-			emit('interact-carousel', interactionType);
-		};
-
-		/**
-		 * Returns number of slides in the carousel
-		 *
-		 * @returns {Number}
-		 */
-		const slideIndicatorListLength = () => {
-			const indicator = embla.value ? embla.value.scrollSnapList().length : 0;
-			slideIndicatorCount.value = indicator;
-			return indicator;
-		};
-
-		/**
-		 * Reinitialize the carousel.
-		 * Used after adding slides dynamically.
-		 *
-		 * @public This is a public method
-		 */
-		const reInitVisible = () => {
-			const slidesInView = embla.value.slidesInView(true).length;
-			if (slidesInView) {
-				embla.value.reInit({
-					slidesToScroll: slidesInView,
-					inViewThreshold: 0.9,
-				});
-			}
-		};
-		const reInit = () => {
-			embla.value.reInit();
-			if (slidesToScroll.value === 'visible') {
-				reInitVisible();
-			}
-			slides.value = embla.value.slideNodes();
-			slideIndicatorListLength();
-		};
-		const onCarouselContainerClick = (e) => {
-			// If we're dragging, block click handlers within slides
-			if (embla.value && !embla.value.clickAllowed()) {
-				e.preventDefault();
-				e.stopPropagation();
-			}
-		};
-		/**
-		 * If the slide is not completely in view in the carousel
-		 * it should be aria-hidden
-		 *
-		 * @param {Number} index The current index of the slide
-		 * @returns {Boolean}
-		 */
-		const isAriaHidden = (index) => {
-			if (embla.value) {
-				return !embla.value.slidesInView(true).includes(index);
-			}
-			return false;
-		};
-
-		onMounted(async () => {
-			embla.value = EmblaCarousel(rootEl.value, {
-				loop: true,
-				containScroll: 'trimSnaps',
-				inViewThreshold: 0.9,
-				align: 'start',
-				...emblaOptions.value,
-			});
-
-			if (slidesToScroll.value === 'visible') {
-				reInitVisible();
-
-				embla.value.on(
-					'resize',
-					throttle(() => {
-						embla.value.reInit({
-							slidesToScroll: embla.value.slidesInView(true).length || 'auto',
-							inViewThreshold: 0.9,
-						});
-						slides.value = embla.value.slideNodes();
-						slideIndicatorListLength();
-					}, 250),
-				);
-			}
-
-			// get slide components
-			slides.value = embla.value.slideNodes();
-			slideIndicatorListLength();
-
-			embla?.value?.on('select', () => {
-				currentIndex.value = embla.value.selectedScrollSnap();
-				/**
-				 * The index of the slide that the carousel has changed to
-				 * @event change
-				 * @type {Event}
-				 */
-				nextTick(() => {
-					emit('change', currentIndex);
-				});
-			});
-		});
-
-		onUnmounted(async () => {
-			embla?.value?.off('select');
-			embla?.value?.destroy();
-		});
+			componentSlotKeys,
+			currentIndex,
+			embla,
+			goToSlide,
+			handleUserInteraction,
+			isAriaHidden,
+			nextIndex,
+			onCarouselContainerClick,
+			previousIndex,
+			reInit,
+			reInitVisible,
+			rootEl,
+			slideIndicatorCount,
+			slideIndicatorListLength,
+			slides,
+		} = carouselUtil(props, { emit, slots });
 
 		return {
-			rootEl,
-			mdiChevronLeft,
-			mdiChevronRight,
+			componentSlotKeys,
+			currentIndex,
+			embla,
+			goToSlide,
+			handleUserInteraction,
+			isAriaHidden,
 			mdiArrowLeft,
 			mdiArrowRight,
-			embla,
-			slides,
-			currentIndex,
-			componentSlotKeys,
+			mdiChevronLeft,
+			mdiChevronRight,
 			nextIndex,
+			onCarouselContainerClick,
 			previousIndex,
-			slideIndicatorCount,
-			handleUserInteraction,
-			goToSlide,
 			reInit,
 			reInitVisible,
-			onCarouselContainerClick,
-			isAriaHidden,
+			rootEl,
+			slideIndicatorCount,
 			slideIndicatorListLength,
+			slides,
 		};
 	},
 };
@@ -425,17 +276,17 @@ export default {
 	}
 }
 
-.cirle-slide {
+.circle-slide {
 	width: auto;
 }
 
-.cirle-slide.is-selected {
+.circle-slide.is-selected {
 	opacity: 1;
 	transform: scale(1.2);
 	max-width: 300px;
 }
 
-.cirle-slide:not(.is-selected) {
+.circle-slide:not(.is-selected) {
 	opacity: 0.5;
 	transform: scale(0.7);
 }

package/vue/KvMap.vue

@@ -203,6 +203,8 @@ export default {
 	},
 	async mounted() {
 		if (this.countriesData) {
+			// current source data is from https://geojson.xyz/ under "admin 0 countries"
+			// https://d2ad6b4ur7yvpq.cloudfront.net/naturalearth-3.3.0/ne_110m_admin_0_countries.geojson
 			this.countriesBorders = await import('../data/ne_110m_admin_0_countries.json');
 		}
 

package/vue/KvVerticalCarousel.vue

@@ -0,0 +1,156 @@
+<template>
+	<div>
+		<section
+			ref="rootEl"
+			aria-label="carousel"
+			class="kv-carousel tw-overflow-hidden tw-relative"
+		>
+			<!-- Carousel Content -->
+			<div
+				class="tw-flex tw-flex-col tw-gap-y-1"
+				:style="`height: ${heightStyle}`"
+				@click.capture="onCarouselContainerClick"
+			>
+				<div
+					v-for="(slotName, index) in componentSlotKeys"
+					:key="index"
+					role="group"
+					:aria-label="`slide ${index + 1} of ${componentSlotKeys.length}`"
+					:aria-current="currentIndex === index ? 'true' : 'false'"
+					:aria-hidden="isAriaHidden(index)? 'true' : 'false'"
+					:tab-index="isAriaHidden(index) ? '-1' : false"
+				>
+					<slot
+						:name="slotName"
+					></slot>
+				</div>
+			</div>
+		</section>
+		<!-- Carousel Controls -->
+		<div
+			class="kv-carousel__controls tw-flex
+			tw-justify-between md:tw-justify-center tw-items-center tw-gap-2
+			tw-mt-2 tw-w-full"
+		>
+			<button
+				class="tw-text-primary
+					tw-rounded-full
+					tw-border-2 tw-border-primary
+					tw-h-4 tw-w-4
+					tw-flex tw-items-center tw-justify-center
+					disabled:tw-opacity-low disabled:tw-cursor-default"
+				:disabled="embla && !embla.canScrollPrev()"
+				@click="handleUserInteraction(previousIndex, 'click-left-arrow')"
+			>
+				<kv-material-icon
+					class="tw-w-4"
+					:icon="mdiChevronUp"
+				/>
+				<span class="tw-sr-only">Show previous slide</span>
+			</button>
+			<button
+				class="tw-text-primary
+					tw-rounded-full
+					tw-border-2 tw-border-primary
+					tw-h-4 tw-w-4
+					tw-flex tw-items-center tw-justify-center
+					disabled:tw-opacity-low disabled:tw-cursor-default"
+				:disabled="embla && !embla.canScrollNext()"
+				@click="handleUserInteraction(nextIndex, 'click-right-arrow')"
+			>
+				<kv-material-icon
+					class="tw-w-4"
+					:icon="mdiChevronDown"
+				/>
+				<span class="tw-sr-only">Show next slide</span>
+			</button>
+		</div>
+	</div>
+</template>
+
+<script>
+import {
+	mdiChevronUp,
+	mdiChevronDown,
+} from '@mdi/js';
+import { carouselUtil } from '../utils/carousels';
+import KvMaterialIcon from './KvMaterialIcon.vue';
+
+export default {
+	components: {
+		KvMaterialIcon,
+	},
+	props: {
+		/**
+		 * Height style declaration of the vertical carousel.
+		 * */
+		heightStyle: {
+			type: String,
+			default: '400px;',
+		},
+		/**
+		 * Options for the embla carousel - // https://davidcetinkaya.github.io/embla-carousel/api#options
+		 * */
+		emblaOptions: {
+			type: Object,
+			default() {
+				return {};
+			},
+		},
+		/**
+		 * The type of logic to implement when deciding how many slides
+		 * to scroll when pressing the next/prev button
+		 * `visible, auto`
+		 * */
+		slidesToScroll: {
+			type: String,
+			default: 'auto',
+			validator: (value) => ['visible', 'auto'].indexOf(value) !== -1,
+		},
+	},
+	emits: [
+		'change',
+		'interact-carousel',
+	],
+	setup(props, { emit, slots }) {
+		const {
+			componentSlotKeys,
+			currentIndex,
+			embla,
+			goToSlide,
+			handleUserInteraction,
+			isAriaHidden,
+			nextIndex,
+			onCarouselContainerClick,
+			previousIndex,
+			reInit,
+			reInitVisible,
+			rootEl,
+			slideIndicatorCount,
+			slides,
+		} = carouselUtil(props, { emit, slots }, { axis: 'y' });
+
+		return {
+			componentSlotKeys,
+			currentIndex,
+			embla,
+			goToSlide,
+			handleUserInteraction,
+			isAriaHidden,
+			mdiChevronDown,
+			mdiChevronUp,
+			nextIndex,
+			onCarouselContainerClick,
+			previousIndex,
+			reInit,
+			reInitVisible,
+			rootEl,
+			slideIndicatorCount,
+			slides,
+		};
+	},
+};
+</script>
+
+<style scoped>
+</style>

package/vue/stories/KvVerticalCarousel.stories.js

@@ -0,0 +1,168 @@
+import KvVerticalCarousel from '../KvVerticalCarousel.vue';
+import KvButton from '../KvButton.vue';
+
+const randomHexColor = (index) => {
+	const defaultColor = '96d4b3';
+	const colorArray = [
+		'D5573B',
+		'885053',
+		'777DA7',
+		'94C9A9',
+		'C6ECAE',
+		'C490D1',
+		'A0D2DB',
+		'7D8CC4',
+		'726DA8',
+	];
+	return colorArray?.[index] || defaultColor;
+};
+
+// This is not an actual loan card template, just a vague
+// approximation to make testing in the stories nicer
+const generateLoanCardTemplate = (index) => {
+	const amounts = [
+		'100',
+		'2,255',
+		'50',
+		'41,900',
+	];
+	const cardCopy = [
+		'A loan of $5,450 helps a member to buy flour, eggs, lard, sugar, sweets and other...',
+		'A loan of $1,125 helps to face the financial problem of covering tuition fees.',
+		'A loan of $450 helps to purchase store goods for resale.',
+	];
+
+	return `
+		<div style="width: 336px">
+			<img src="https://placehold.co/336x252/${randomHexColor(index)}/000000" class="tw-w-full tw-rounded tw-mb-2">
+			<h3>Card Title</h3>
+			<h4 class="tw-my-1">$${amounts?.[index] || amounts?.[1]} to go</h4>
+			<p class="tw-mt-1 tw-mb-9">${cardCopy?.[index] || cardCopy?.[1]}</p>
+			<kv-button
+				variant="primary"
+			>
+				Read more
+			</kv-button>
+		</div>`;
+};
+
+const defaultCarouselSlides = `
+	<template #slide1>
+		<img src="https://placehold.co/400x150/${randomHexColor(1)}/000000">
+	</template>
+	<template #slide2>
+		<img src="https://placehold.co/400x150/${randomHexColor(2)}/000000">
+	</template>
+	<template #slide3>
+		<img src="https://placehold.co/400x150/${randomHexColor(3)}/000000">
+	</template>
+	<template #slide4>
+		<img src="https://placehold.co/400x150/${randomHexColor(4)}/000000">
+	</template>
+`;
+
+export default {
+	title: 'KvVerticalCarousel',
+	component: KvVerticalCarousel,
+};
+
+export const Default = () => ({
+	components: {
+		KvVerticalCarousel,
+	},
+	template: `
+		<div style="width: 400px;">
+			<kv-vertical-carousel height-style="310px" class="tw-w-full">
+				${defaultCarouselSlides}
+			</kv-vertical-carousel>
+		</div>
+	`,
+});
+
+export const LoopFalse = () => ({
+	components: {
+		KvVerticalCarousel,
+	},
+	template: `
+		<div style="width: 400px;">
+			<kv-vertical-carousel height-style="400px" class="tw-w-full">
+				${defaultCarouselSlides}
+			</kv-vertical-carousel>
+		</div>
+	`,
+});
+
+export const MultipleLoanCards = () => ({
+	components: {
+		KvVerticalCarousel,
+		KvButton,
+	},
+	template: `
+		<kv-vertical-carousel
+			:embla-options="{ loop: false }"
+			:multiple-slides-visible="true"
+			style="max-width: 600px;"
+			height-style="510px"
+			class="tw-w-full"
+		>
+			<template #slide1>
+				${generateLoanCardTemplate(1)}
+			</template>
+			<template #slide2>
+				${generateLoanCardTemplate(2)}
+			</template>
+			<template #slide3>
+				${generateLoanCardTemplate(3)}
+			</template>
+			<template #slide4>
+				${generateLoanCardTemplate(4)}
+			</template>
+			<template #slide5>
+				${generateLoanCardTemplate(5)}
+			</template>
+		</kv-vertical-carousel>
+	`,
+});
+
+export const CustomStartIndex = () => ({
+	components: {
+		KvVerticalCarousel,
+		KvButton,
+	},
+	template: `
+		<kv-vertical-carousel
+			:embla-options="{ loop: false, align: 'center', startIndex: 1 }"
+			:multiple-slides-visible="true"
+			slides-to-scroll="visible"
+			style="max-width: 1072px;"
+		>
+			<template #slide1>
+				${generateLoanCardTemplate(1)}
+			</template>
+			<template #slide2>
+				${generateLoanCardTemplate(2)}
+			</template>
+			<template #slide3>
+				${generateLoanCardTemplate(3)}
+			</template>
+			<template #slide4>
+				${generateLoanCardTemplate(4)}
+			</template>
+			<template #slide5>
+				${generateLoanCardTemplate(5)}
+			</template>
+			<template #slide6>
+				${generateLoanCardTemplate(6)}
+			</template>
+			<template #slide7>
+				${generateLoanCardTemplate(7)}
+			</template>
+			<template #slide8>
+				${generateLoanCardTemplate(8)}
+			</template>
+			<template #slide9>
+				${generateLoanCardTemplate(9)}
+			</template>
+		</kv-vertical-carousel>
+	`,
+});