@kiva/kv-components 3.92.1 → 3.94.0

package/CHANGELOG.md

@@ -3,6 +3,28 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [3.94.0](https://github.com/kiva/kv-ui-elements/compare/@kiva/kv-components@3.93.0...@kiva/kv-components@3.94.0) (2024-08-23)
+
+
+### Features
+
+* charts added to library ([#447](https://github.com/kiva/kv-ui-elements/issues/447)) ([575bd80](https://github.com/kiva/kv-ui-elements/commit/575bd80fb1700a38732a2b8cafbeb5cc5374764b))
+
+
+
+
+
+# [3.93.0](https://github.com/kiva/kv-ui-elements/compare/@kiva/kv-components@3.92.1...@kiva/kv-components@3.93.0) (2024-08-22)
+
+
+### Features
+
+* carousel circle effect ([c982be4](https://github.com/kiva/kv-ui-elements/commit/c982be4d088f18cb53b5d97b3071fa7dac72e1c6))
+
+
+
+
+
 ## [3.92.1](https://github.com/kiva/kv-ui-elements/compare/@kiva/kv-components@3.92.0...@kiva/kv-components@3.92.1) (2024-08-19)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kiva/kv-components",
-  "version": "3.92.1",
+  "version": "3.94.0",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -71,6 +71,8 @@
     "moment": "^2.29.4",
     "nanoid": "^3.1.23",
     "numeral": "^2.0.6",
+    "popper.js": "^1.16.1",
+    "treemap-squarify": "^1.0.1",
     "vue-demi": "^0.14.7"
   },
   "peerDependencies": {
@@ -82,5 +84,5 @@
       "optional": true
     }
   },
-  "gitHead": "52085aeb1c92162fd732cd3fe4cb9839cdd49b16"
+  "gitHead": "4d6b8d16d7fe0e5b3904b87a82484e28325cd496"
 }

package/utils/Alea.js

@@ -0,0 +1,92 @@
+/* eslint-disable no-plusplus, no-param-reassign, no-return-assign, no-bitwise, prefer-rest-params, func-names */
+
+/**
+ * The hash function used for Alea pseudo random number generator
+ *
+ * Johannes Baagøe <baagoe@baagoe.com>, 2010
+ * Licensed under the MIT license
+ *
+ * {@link https://github.com/nquinlan/better-random-numbers-for-javascript-mirror}
+ *
+ * @returns The hash of the provided data
+ */
+export function Mash() {
+	let n = 0xefc8249d;
+
+	const mash = function (data) {
+		data = data.toString();
+		for (let i = 0; i < data.length; i++) {
+			n += data.charCodeAt(i);
+			let h = 0.02519603282416938 * n;
+			n = h >>> 0;
+			h -= n;
+			h *= n;
+			n = h >>> 0;
+			h -= n;
+			n += h * 0x100000000; // 2^32
+		}
+		return (n >>> 0) * 2.3283064365386963e-10; // 2^-32
+	};
+
+	mash.version = 'Mash 0.9';
+
+	return mash;
+}
+
+/**
+ * Pseudo random number generator that returns a repeatable set of random numbers when supplied matching seeds
+ *
+ * Johannes Baagøe <baagoe@baagoe.com>, 2010
+ * Licensed under the MIT license
+ *
+ * {@link https://github.com/nquinlan/better-random-numbers-for-javascript-mirror}
+ *
+ * @returns The seeded generator function
+ */
+export default function Alea() {
+	return (function (args) {
+		let s0 = 0;
+		let s1 = 0;
+		let s2 = 0;
+		let c = 1;
+
+		if (args.length === 0) {
+			args = [+new Date()];
+		}
+
+		let mash = Mash();
+		s0 = mash(' ');
+		s1 = mash(' ');
+		s2 = mash(' ');
+
+		for (let i = 0; i < args.length; i++) {
+			s0 -= mash(args[i]);
+			if (s0 < 0) {
+				s0 += 1;
+			}
+			s1 -= mash(args[i]);
+			if (s1 < 0) {
+				s1 += 1;
+			}
+			s2 -= mash(args[i]);
+			if (s2 < 0) {
+				s2 += 1;
+			}
+		}
+
+		mash = null;
+
+		const random = function () {
+			const t = 2091639 * s0 + c * 2.3283064365386963e-10; // 2^-32
+			s0 = s1;
+			s1 = s2;
+			return s2 = t - (c = t | 0);
+		};
+
+		random.version = 'Alea 0.9';
+
+		random.args = args;
+
+		return random;
+	}(Array.prototype.slice.call(arguments)));
+}

package/utils/touchEvents.js

@@ -0,0 +1,22 @@
+// Attach a touchstart event handler to the immediate children of the body.
+// Useful for capturing the user tapping outside of a target element.
+export function onBodyTouchstart(handler) {
+	[...document.body.children].forEach((child) => child.addEventListener('touchstart', handler));
+}
+
+// Remove a touchstart event handler from the immediate children of the body
+export function offBodyTouchstart(handler) {
+	[...document.body.children].forEach((child) => child.removeEventListener('touchstart', handler));
+}
+
+// Returns true if the event target is any of the given elements or if the event target
+// is contained by any of the given elements.
+export function isTargetElement(event, elements) {
+	const els = Array.isArray(elements) ? elements : [elements];
+	for (let i = 0; i < els.length; i += 1) {
+		if (els[i] === event.target || els[i].contains(event.target)) {
+			return true;
+		}
+	}
+	return false;
+}

package/vue/KvCarousel.vue

@@ -8,7 +8,10 @@
 		<!-- Carousel Content -->
 		<div
 			class="tw-flex tw-gap-x-4"
-			:class="{ 'tw-mx-auto aside-controls-content': asideControls }"
+			:class="{
+				'tw-mx-auto aside-controls-content': asideControls,
+				'circle-carousel': inCircle
+			}"
 			@click.capture="onCarouselContainerClick"
 		>
 			<div
@@ -20,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 }"
+				:class="{ 'tw-w-full': !multipleSlidesVisible || slideMaxWidth, 'cirle-slide': inCircle }"
 				:style="slideMaxWidth ? `max-width:${slideMaxWidth}` :''"
 			>
 				<slot
@@ -219,6 +222,13 @@ export default {
 			type: Boolean,
 			default: false,
 		},
+		/**
+		 * Enables carousel slides to have a circle effect
+		 * */
+		inCircle: {
+			type: Boolean,
+			default: false,
+		},
 	},
 	emits: [
 		'change',
@@ -414,4 +424,23 @@ export default {
 		width: 82%;
 	}
 }
+
+.cirle-slide {
+	width: auto;
+}
+
+.cirle-slide.is-selected >>> img {
+	opacity: 1;
+	transform: scale(1);
+	max-width: 300px;
+}
+
+.cirle-slide:not(.is-selected) >>> img {
+	opacity: 0.5;
+	transform: scale(0.5);
+}
+
+.circle-carousel {
+	margin: 0 auto;
+}
 </style>

package/vue/KvPieChart.vue

@@ -0,0 +1,232 @@
+<template>
+	<figure
+		class="pie-chart tw-flex tw-flex-col md:tw-flex-row tw-items-center tw-justify-center tw-gap-2"
+		@mouseleave="activeSlice = null"
+	>
+		<!-- pie chart -->
+		<div class="tw-relative tw-h-full">
+			<div
+				v-if="loading"
+				class="pie-placeholder tw-h-full tw-p-2.5"
+			>
+				<div class="tw-overflow-hidden tw-rounded-full tw-h-full">
+					<kv-loading-placeholder />
+				</div>
+			</div>
+			<svg
+				v-else
+				class="tw-h-full"
+				viewBox="0 0 32 32"
+				xmlns="http://www.w3.org/2000/svg"
+				xmlns:xlink="http://www.w3.org/1999/xlink"
+			>
+				<path
+					v-for="(slice, index) in slices"
+					:key="index"
+					class="tw-origin-center tw-transition-transform"
+					:style="activeSlice === slice ? { transform: 'scale(1.1)' } : {}"
+					:d="slice.path"
+					:stroke="slice.color"
+					:stroke-width="lineWidth"
+					fill="none"
+					@mouseenter="activeSlice = slice"
+					@click="activeSlice = slice"
+				/>
+			</svg>
+			<!-- active slice -->
+			<div
+				v-if="activeSlice"
+				class="
+					tw-absolute tw-top-1/2 tw-left-1/2 -tw-translate-x-1/2 -tw-translate-y-1/2
+					tw-flex tw-flex-col tw-items-center tw-text-center"
+				style="max-width: 8.5rem;"
+			>
+				<div class="tw-font-medium tw-line-clamp-4">
+					{{ activeSlice.label }}
+				</div>
+				<div>
+					{{ activeSlice.value }} ({{ activeSlicePercent }})
+				</div>
+			</div>
+		</div>
+		<!-- key -->
+		<div
+			style="width: 14rem; height: 85%;"
+			class="tw-flex tw-flex-col tw-justify-between"
+		>
+			<ol class="tw-pl-4 md:tw-pl-0">
+				<li
+					v-for="(slice, index) in slices.slice(pageIndex * slicesPerPage, (pageIndex + 1) * slicesPerPage)"
+					:key="index"
+					class="tw-flex tw-items-center"
+					@mouseenter="activeSlice = slice"
+					@click="activeSlice = slice"
+				>
+					<div
+						class="tw-w-2 tw-h-2 tw-mr-1 tw-rounded-full tw-flex-none"
+						:style="{ backgroundColor: slice.color }"
+					></div>
+					<span class="tw-truncate">
+						{{ slice.label }}
+					</span>
+				</li>
+			</ol>
+			<!-- paging controls -->
+			<div
+				v-if="pageCount > 1"
+				class="tw-flex tw-justify-center md:tw-justify-start"
+			>
+				<button
+					:disabled="pageIndex === 0"
+					class="tw-font-medium tw-p-0.5 disabled:tw-opacity-low"
+					@click="prevPage"
+				>
+					&lt;
+				</button>
+				{{ pageIndex + 1 }} / {{ pageCount }}
+				<button
+					:disabled="pageIndex === pageCount - 1"
+					class="tw-font-medium tw-p-0.5 disabled:tw-opacity-low"
+					@click="nextPage"
+				>
+					&gt;
+				</button>
+			</div>
+		</div>
+	</figure>
+</template>
+
+<script>
+import numeral from 'numeral';
+import { ref, toRefs, computed } from 'vue-demi';
+import Alea from '../utils/Alea';
+import KvLoadingPlaceholder from './KvLoadingPlaceholder.vue';
+
+// convenience function to get point on circumference of a given circle (from https://codepen.io/grieve/pen/xwGMJp)
+function circumPointFromAngle(cx, cy, r, a) {
+	return [
+		cx + r * Math.cos(a),
+		cy + r * Math.sin(a),
+	];
+}
+
+export default {
+	name: 'PieChartFigure',
+	components: {
+		KvLoadingPlaceholder,
+	},
+	props: {
+		loading: {
+			type: Boolean,
+			default: true,
+		},
+		values: {
+			type: Array,
+			default: () => ([]),
+		},
+	},
+	setup(props) {
+		const {
+			values,
+		} = toRefs(props);
+
+		const svgSize = ref(32);
+		const lineWidth = ref(5);
+		const activeSlice = ref(null);
+		const pageIndex = ref(0);
+		const slicesPerPage = ref(10);
+
+		const activeSlicePercent = computed(() => {
+			return activeSlice.value ? numeral(activeSlice.value.percent).format('0.00%') : '';
+		});
+
+		const radius = computed(() => {
+			return (svgSize.value / 2) - (lineWidth.value / 2) - 2;
+		});
+
+		const center = computed(() => {
+			return svgSize.value / 2;
+		});
+
+		const pickColor = (index) => {
+			const rng = new Alea('loans', index, 'kiva');
+			let color = '#';
+			for (let i = 0; i < 3; i += 1) {
+				color += Math.floor(rng() * 256).toString(16).padStart(2, '0');
+			}
+			return color;
+		};
+
+		const slices = computed(() => {
+			const slicesArr = [];
+			// center point
+			const cX = center.value;
+			const cY = cX;
+			// radius
+			const r = radius.value;
+			// starting angle
+			let start = -0.25;
+			// loop through each value and create a pie slice path
+			for (let i = 0; i < values.value.length; i += 1) {
+				const value = values.value[i];
+				const end = start + value.percent;
+				const [startX, startY] = circumPointFromAngle(cX, cY, r, start * Math.PI * 2);
+				const [endX, endY] = circumPointFromAngle(cX, cY, r, end * Math.PI * 2);
+				const largeArc = value.percent > 0.5 ? 1 : 0;
+				// Draw just the outer arc of the slice
+				const path = `M ${startX} ${startY} A ${r} ${r} 0 ${largeArc} 1 ${endX} ${endY}`;
+				slicesArr.push({
+					...value,
+					path,
+					color: pickColor(i),
+				});
+				start = end;
+			}
+			return slicesArr;
+		});
+
+		const pageCount = computed(() => {
+			return Math.ceil(slices.value.length / slicesPerPage.value);
+		});
+
+		const prevPage = () => {
+			if (pageIndex.value > 0) {
+				pageIndex.value -= 1;
+			}
+		};
+		const nextPage = () => {
+			if (pageIndex.value < pageCount.value - 1) {
+				pageIndex.value += 1;
+			}
+		};
+
+		return {
+			svgSize,
+			lineWidth,
+			activeSlice,
+			pageIndex,
+			slicesPerPage,
+			activeSlicePercent,
+			radius,
+			center,
+			slices,
+			pageCount,
+			prevPage,
+			nextPage,
+		};
+	},
+};
+</script>
+
+<style lang="postcss" scoped>
+.pie-chart {
+	height: 40rem;
+	@screen md {
+		height: 20rem;
+	}
+}
+
+.pie-placeholder {
+	width: 20rem;
+}
+</style>

package/vue/KvPopper.vue

@@ -0,0 +1,178 @@
+<template>
+	<transition :name="transitionType">
+		<div
+			v-show="show"
+			class="tw-absolute"
+			:style="styles"
+			:aria-hidden="show ? 'false' : 'true'"
+		>
+			<slot></slot>
+		</div>
+	</transition>
+</template>
+
+<script>
+import {
+	onBodyTouchstart,
+	offBodyTouchstart,
+	isTargetElement,
+} from '../utils/touchEvents';
+
+export default {
+	name: 'KvPopper',
+	props: {
+		controller: {
+			validator(value) {
+				if (typeof value === 'string') return true;
+				if (typeof window === 'object'
+					&& 'HTMLElement' in window
+					&& value instanceof HTMLElement) return true;
+				return false;
+			},
+			required: true,
+		},
+		openDelay: { type: Number, default: 0 },
+		closeDelay: { type: Number, default: 200 },
+		// must be defined in our globa/transitions.scss
+		transitionType: { type: String, default: '' },
+		popperPlacement: { type: String, default: 'bottom-start' },
+		popperModifiers: { type: Object, default: () => {} },
+	},
+	data() {
+		return {
+			popper: null,
+			popperPromise: null,
+			styles: {},
+			show: false,
+			timeout: null,
+		};
+	},
+	computed: {
+		reference() {
+			return typeof this.controller === 'string' ? document.getElementById(this.controller) : this.controller;
+		},
+	},
+	watch: {
+		show(showing) {
+			if (this.reference) {
+				this.reference.setAttribute('aria-expanded', showing ? 'true' : 'false');
+			}
+			this.$emit(showing ? 'show' : 'hide');
+		},
+	},
+	mounted() {
+		this.reference.tabIndex = 0;
+		this.attachEvents();
+	},
+	updated() {
+		if (this.popper) {
+			this.popper.scheduleUpdate();
+		}
+	},
+	beforeDestroy() {
+		this.removeEvents();
+		if (this.popper) {
+			this.popper.destroy();
+		}
+	},
+	methods: {
+		open() {
+			this.initPopper().then(() => {
+				this.setTimeout(() => {
+					this.show = true;
+					this.popper.scheduleUpdate();
+					this.attachBodyEvents();
+				}, this.openDelay);
+			});
+		},
+		close() {
+			this.setTimeout(() => {
+				this.show = false;
+				this.removeBodyEvents();
+			}, this.closeDelay);
+		},
+		toggle() {
+			if (this.show) {
+				this.close();
+			} else {
+				this.open();
+			}
+		},
+		update() {
+			if (this.popper) {
+				this.popper.scheduleUpdate();
+			}
+		},
+		initPopper() {
+			// skip loading if popper already created
+			if (this.popper) return Promise.resolve();
+			// skip loading if loading already started
+			if (this.popperPromise) return this.popperPromise;
+			// import and init Popper.js
+			this.popperPromise = import('popper.js').then(({ default: Popper }) => {
+				this.popper = new Popper(this.reference, this.$el, {
+					placement: this.popperPlacement,
+					modifiers: {
+						applyStyle: (data) => {
+							this.styles = data.styles;
+							this.setAttributes(data.attributes);
+						},
+						preventOverflow: {
+							padding: 0,
+						},
+						...this.popperModifiers,
+					},
+				});
+			});
+			return this.popperPromise;
+		},
+		bodyTouchHandler(e) {
+			if (!isTargetElement(e, [this.reference, this.$el])) {
+				this.show = false;
+				this.removeBodyEvents();
+			}
+		},
+		referenceTapHandler(e) {
+			e.preventDefault();
+			this.toggle();
+		},
+		attachEvents() {
+			this.reference.addEventListener('mouseover', this.open);
+			this.reference.addEventListener('focus', this.open);
+			this.reference.addEventListener('mouseout', this.close);
+			this.reference.addEventListener('blur', this.close);
+			this.$el.addEventListener('mouseover', this.open);
+			this.$el.addEventListener('mouseout', this.close);
+			this.reference.addEventListener('touchstart', this.referenceTapHandler);
+		},
+		attachBodyEvents() {
+			onBodyTouchstart(this.bodyTouchHandler);
+		},
+		removeEvents() {
+			this.removeBodyEvents();
+			this.reference.removeEventListener('touchstart', this.referenceTapHandler);
+			this.reference.removeEventListener('mouseover', this.open);
+			this.reference.removeEventListener('mouseout', this.close);
+			this.$el.removeEventListener('mouseover', this.open);
+			this.$el.removeEventListener('mouseout', this.close);
+		},
+		removeBodyEvents() {
+			offBodyTouchstart(this.bodyTouchHandler);
+		},
+		setAttributes(attrs) {
+			Object.keys(attrs).forEach((attr) => {
+				const value = attrs[attr];
+				if (value === false) {
+					this.$el.removeAttribute(attr);
+				} else {
+					this.$el.setAttribute(attr, value);
+				}
+			});
+		},
+		setTimeout(fn, delay) {
+			window.clearTimeout(this.timeout);
+			this.timeout = window.setTimeout(fn, delay);
+		},
+	},
+};
+</script>

package/vue/KvTooltip.vue

@@ -0,0 +1,168 @@
+<template>
+	<kv-theme-provider
+		:theme="themeStyle"
+		class="kv-tailwind"
+	>
+		<kv-popper
+			:controller="controller"
+			:popper-modifiers="popperModifiers"
+			popper-placement="top"
+			transition-type="kvfastfade"
+			class="tooltip-pane tw-absolute tw-bg-primary tw-rounded tw-z-popover"
+		>
+			<div
+				class="tw-p-2.5"
+				style="max-width: 250px;"
+			>
+				<div
+					v-if="$slots.title"
+					class="tw-text-primary tw-font-medium tw-mb-1.5"
+				>
+					<slot name="title"></slot>
+				</div>
+				<div class="tw-text-primary">
+					<slot></slot>
+				</div>
+			</div>
+			<div
+				class="tooltip-arrow tw-absolute tw-w-0 tw-h-0 tw-border-solid"
+				x-arrow=""
+			></div>
+		</kv-popper>
+	</kv-theme-provider>
+</template>
+
+<script>
+import { ref, toRefs, computed } from 'vue-demi';
+import {
+	darkTheme,
+	mintTheme,
+} from '@kiva/kv-tokens/configs/kivaColors.cjs';
+import KvPopper from './KvPopper.vue';
+import KvThemeProvider from './KvThemeProvider.vue';
+
+export default {
+	name: 'KvTooltip',
+	components: {
+		KvPopper,
+		KvThemeProvider,
+	},
+	// TODO: Add prop for tooltip placement, Currently defaults to 'top' but will flip to bottom when constrained
+	props: {
+		controller: {
+			validator(value) {
+				if (typeof value === 'string') return true;
+				if (typeof window !== 'undefined'
+					&& 'HTMLElement' in window
+					&& value instanceof HTMLElement) return true;
+				return false;
+			},
+			required: true,
+		},
+		theme: {
+			type: String,
+			default: 'default',
+			validator(value) {
+				// The value must match one of these strings
+				return ['default', 'mint', 'dark'].indexOf(value) !== -1;
+			},
+		},
+	},
+	setup(props) {
+		const {
+			theme,
+		} = toRefs(props);
+
+		const popperModifiers = ref({
+			preventOverflow: {
+				padding: 10,
+			},
+		});
+
+		const themeStyle = computed(() => {
+			const themeMapper = {
+				mint: mintTheme,
+				dark: darkTheme,
+			};
+			return themeMapper[theme.value];
+		});
+
+		return {
+			darkTheme,
+			mintTheme,
+			popperModifiers,
+			themeStyle,
+		};
+	},
+};
+</script>
+
+<style lang="postcss" scoped>
+.tooltip-pane,
+.tooltip-arrow {
+	box-shadow: 0 4px 12px rgba(0, 0, 0, 0.08);
+}
+
+.tooltip-arrow {
+	@apply tw-m-1;
+	@apply tw-border-white;
+}
+
+/* Top Tooltip Arrow appears on Bottom */
+.tooltip-pane[x-placement^="top"] {
+	@apply tw-mb-1;
+}
+
+.tooltip-pane[x-placement^="top"] .tooltip-arrow {
+	border-width: 8px 8px 0 8px;
+	border-left-color: transparent;
+	border-right-color: transparent;
+	border-bottom-color: transparent;
+	left: calc(50% - 8px);
+	@apply -tw-bottom-1 tw-mt-0 tw-mb-0;
+}
+
+/* Bottom Tooltip Arrow appears on Top */
+.tooltip-pane[x-placement^="bottom"] {
+	@apply tw-mt-1;
+}
+
+.tooltip-pane[x-placement^="bottom"] .tooltip-arrow {
+	border-width: 0 8px 8px 8px;
+	border-left-color: transparent;
+	border-right-color: transparent;
+	border-top-color: transparent;
+	left: calc(50% - 8px);
+	@apply -tw-top-1 tw-mb-0 tw-mt-0;
+}
+
+/* TODO: TWEAK Inner Arrow Styles for Left + Right Orientations */
+
+/* Right Side Tooltip, Arrow appears on Left */
+.tooltip-pane[x-placement^="right"] {
+	@apply tw-ml-1;
+}
+
+.tooltip-pane[x-placement^="right"] .tooltip-arrow {
+	border-width: 8px 8px 8px 0;
+	border-left-color: transparent;
+	border-top-color: transparent;
+	border-bottom-color: transparent;
+	top: calc(50% - 8px);
+	@apply -tw-left-1 tw-ml-0 tw-mr-0;
+}
+
+/* Left Side Tooltip, Arrow appears on Right */
+.tooltip-pane[x-placement^="left"] {
+	@apply tw-mr-1;
+}
+
+.tooltip-pane[x-placement^="left"] .tooltip-arrow {
+	border-width: 8px 0 8px 8px;
+	border-top-color: transparent;
+	border-right-color: transparent;
+	border-bottom-color: transparent;
+	top: calc(50% - 8px);
+	@apply -tw-right-1 tw-ml-0 tw-mr-0;
+}
+</style>

package/vue/KvTreeMapChart.vue

@@ -0,0 +1,229 @@
+<template>
+	<figure class="treemap-figure tw-relative">
+		<!-- treemap -->
+		<div
+			v-for="(block, index) in blocks"
+			:key="`block-${index}`"
+			class="tw-absolute"
+			:style="blockPositionStyles(block)"
+		>
+			<kv-loading-placeholder
+				v-if="loading"
+				style="width: calc(100% - 0.25rem); height: calc(100% - 0.25rem);"
+			/>
+			<p
+				v-if="!loading"
+				class="tw-rounded-sm tw-box-border tw-overflow-hidden tw-text-small"
+				:class="colorClasses(index)"
+				style="width: calc(100% - 0.25rem); height: calc(100% - 0.25rem);"
+				@mouseenter="setHoverBlock(block)"
+			>
+				<span class="tw-block tw-px-1 tw-py-0.5 tw-truncate">
+					{{ block.data.label }} {{ block.data.percent }}
+				</span>
+			</p>
+		</div>
+		<!-- tooltip -->
+		<div
+			ref="tooltipController"
+			class="tw-absolute"
+			:style="blockPositionStyles(activeBlock)"
+		></div>
+		<kv-tooltip
+			v-if="!loading && tooltipControllerElement"
+			:controller="tooltipControllerElement"
+		>
+			<template #title>
+				{{ activeBlock.data.label }}
+			</template>
+			{{ activeBlock.data.value }} ({{ activeBlock.data.percent }})
+		</kv-tooltip>
+	</figure>
+</template>
+
+<script>
+import numeral from 'numeral';
+import { getTreemap } from 'treemap-squarify';
+import kvTokensPrimitives from '@kiva/kv-tokens/primitives.json';
+import { throttle } from '../utils/throttle';
+import KvTooltip from './KvTooltip.vue';
+import KvLoadingPlaceholder from './KvLoadingPlaceholder.vue';
+
+const { breakpoints } = kvTokensPrimitives;
+
+export default {
+	name: 'TreeMapFigure',
+	components: {
+		KvLoadingPlaceholder,
+		KvTooltip,
+	},
+	props: {
+		loading: {
+			type: Boolean,
+			default: true,
+		},
+		values: {
+			type: Array,
+			default: () => [],
+		},
+	},
+	data() {
+		return {
+			screenWidth: 0,
+			activeBlock: { data: {} },
+			tooltipControllerElement: null,
+		};
+	},
+	computed: {
+		activeBreakpoints() {
+			return Object.keys(breakpoints)
+				.filter((name) => this.screenWidth >= breakpoints[name]);
+		},
+		// Used to determine if blocks should be displayed in landscape or portrait orientation
+		aboveMedium() {
+			return this.activeBreakpoints.includes('md');
+		},
+		// Calculate the blocks of the treemap, but don't apply any formatting
+		rawBlocks() {
+			// Use static blocks when no data is available (either loading or no loans)
+			if (!this.values?.length) {
+				return this.loading ? [
+					{
+						x: 0, y: 0, width: 60, height: 40,
+					},
+					{ x: 60, y: 0, height: 40 },
+					{ x: 0, y: 40, width: 30 },
+					{ x: 30, y: 40 },
+				] : [
+					{ x: 0, y: 0, data: { label: 'No loans yet' } },
+				];
+			}
+
+			// Calculate treemap blocks using canvas size 100x100 to easily translate to percentages
+			const blocks = getTreemap({
+				data: this.values,
+				width: 100,
+				height: 100,
+			});
+
+			// Blocks smaller than 8% in either dimension will not display well,
+			// so combine them into one large 'Other' block
+			// If we only have 1 small block though, don't make the 'Other' block
+			const tooSmall = blocks.filter((block) => block.width <= 8 || block.height <= 8);
+			if (tooSmall.length === 1) return blocks;
+
+			const bigBlocks = blocks.filter((block) => block.width > 8 && block.height > 8);
+			return [...bigBlocks, this.reduceBlocks(tooSmall)];
+		},
+		// This is the array that is iterated over in the template
+		blocks() {
+			return this.rawBlocks.map((block) => {
+				const {
+					data, x, y, width, height,
+				} = block ?? {};
+				const { percent } = data ?? {};
+
+				return {
+					data: {
+						...data,
+						percent: numeral(percent).format('0[.]0%'),
+					},
+					// flip x/y when going between small (portrait) and medium (landscape) screens
+					x: this.aboveMedium ? x : y,
+					y: this.aboveMedium ? y : x,
+					width: this.aboveMedium ? width : height,
+					height: this.aboveMedium ? height : width,
+				};
+			});
+		},
+	},
+	mounted() {
+		this.screenWidth = window.innerWidth;
+		window.addEventListener('resize', throttle(() => {
+			this.screenWidth = window.innerWidth;
+		}, 200));
+
+		// Used by KvTooltip/KvPopper to position the tooltip
+		if (this.$refs?.tooltipController) {
+			this.tooltipControllerElement = this.$refs.tooltipController;
+		}
+	},
+	methods: {
+		// Used by the p elements in the main v-for loop to determine background and text color
+		colorClasses(index) {
+			const classes = [];
+			const total = this.blocks?.length ?? 1;
+
+			// background
+			const size = (10 - Math.round((index / total) * 9)) * 100;
+			classes.push(size === 600 ? 'tw-bg-brand' : `tw-bg-brand-${size}`);
+
+			// text
+			classes.push(size > 700 ? 'tw-text-white' : 'tw-text-black');
+
+			return classes;
+		},
+		// Used by the divs in the main v-for for block positions and the tooltip controller div to match positions
+		// with the current active block
+		blockPositionStyles(block) {
+			return {
+				left: `${block.x}%`,
+				top: `${block.y}%`,
+				width: block.width ? `${block.width}%` : null,
+				height: block.height ? `${block.height}%` : null,
+				right: block.width ? null : '0',
+				bottom: block.height ? null : '0',
+			};
+		},
+		// Combine all small blocks into a single 'Other' block that will be at the bottom right of the figure.
+		reduceBlocks(blocks) {
+			return blocks?.reduce((other, block) => {
+				/* eslint-disable no-param-reassign */
+				// Use the smallest x for the overall x
+				if (block.x < other.x) {
+					other.x = block.x;
+				}
+				// Use the smallest y for the overall y
+				if (block.y < other.y) {
+					other.y = block.y;
+				}
+				// Sum up all values and percents
+				other.data.value += block.data.value;
+				other.data.percent += block.data.percent;
+				return other;
+				/* eslint-ensable no-param-reassign */
+			}, {
+				x: 100,
+				y: 100,
+				width: 0,
+				height: 0,
+				data: {
+					label: 'Other',
+					value: 0,
+					percent: 0,
+				},
+			}) ?? [];
+		},
+		// Sets the block that will be used to position the tooltip and change the info displayed in the tooltip
+		setHoverBlock(block) {
+			this.activeBlock = block;
+		},
+	},
+};
+</script>
+
+<style lang="postcss" scoped>
+.treemap-figure {
+	height: 30rem;
+
+	/* account for every block having a 0.25rem right margin */
+	width: calc(100% + 0.25rem);
+	margin-right: -0.25rem;
+}
+
+@screen md {
+	.treemap-figure {
+		height: 20rem;
+	}
+}
+</style>

package/vue/stories/KvCarousel.stories.js

@@ -402,7 +402,23 @@ export const Dotted = () => ({
 	template: `
 		<kv-carousel
 			style="max-width: 400px;"
-			is-dotted="true"
+			:is-dotted="true"
+		>
+			${defaultCarouselSlides}
+		</kv-carousel>
+	`,
+});
+
+export const ThreeDimensional = () => ({
+	components: {
+		KvCarousel,
+	},
+	template: `
+		<kv-carousel
+			:embla-options="{ loop: false, align: 'center' }"
+			style="max-width: 600px;"
+			:is-dotted="true"
+			:in-circle="true"
 		>
 			${defaultCarouselSlides}
 		</kv-carousel>

package/vue/stories/KvPieChart.stories.js

@@ -0,0 +1,42 @@
+import KvPieChart from '../KvPieChart.vue';
+
+const genderValues = [{ label: 'Female', value: 1243, percent: 0.6467221644120708 }, { label: 'Male', value: 676, percent: 0.3517169614984391 }, { label: 'Unspecified', value: 2, percent: 0.001040582726326743 }, { label: 'Nonbinary', value: 1, percent: 0.0005202913631633715 }];
+const sectorValues = [{ label: 'Food', value: 575, percent: 0.2991675338189386 }, { label: 'Retail', value: 377, percent: 0.19614984391259105 }, { label: 'Agriculture', value: 285, percent: 0.14828303850156088 }, { label: 'Services', value: 211, percent: 0.10978147762747138 }, { label: 'Clothing', value: 183, percent: 0.09521331945889698 }, { label: 'Arts', value: 65, percent: 0.033818938605619145 }, { label: 'Housing', value: 65, percent: 0.033818938605619145 }, { label: 'Education', value: 36, percent: 0.018730489073881373 }, { label: 'Construction', value: 28, percent: 0.014568158168574402 }, { label: 'Health', value: 27, percent: 0.01404786680541103 }, { label: 'Transportation', value: 23, percent: 0.011966701352757543 }, { label: 'Personal Use', value: 19, percent: 0.009885535900104058 }, { label: 'Manufacturing', value: 13, percent: 0.006763787721123829 }, { label: 'Entertainment', value: 10, percent: 0.005202913631633715 }, { label: 'Wholesale', value: 5, percent: 0.0026014568158168575 }];
+
+export default {
+	title: 'Charts/KvPieChart',
+	component: KvPieChart,
+	args: {
+		loading: false,
+		values: genderValues,
+	},
+};
+
+const Template = (args, {
+	argTypes,
+}) => ({
+	props: Object.keys(argTypes),
+	components: {
+		KvPieChart,
+	},
+	template: `
+		<div>
+			<kv-pie-chart
+                :values="values"
+                :loading="loading"
+            />
+		</div>`,
+});
+
+export const Default = Template.bind({});
+
+export const Loading = Template.bind({});
+Loading.args = {
+	loading: true,
+	values: [],
+};
+
+export const ManyValues = Template.bind({});
+ManyValues.args = {
+	values: sectorValues,
+};

package/vue/stories/KvTooltip.stories.js

@@ -0,0 +1,26 @@
+import KvTooltip from '../KvTooltip.vue';
+
+export default {
+	title: 'KvTooltip',
+	component: KvTooltip,
+};
+
+export const Default = () => ({
+	components: {
+		KvTooltip,
+	},
+	template: `
+		<div>
+			<button id="my-cool-btn">Hover of Focus Me!</button>
+			<kv-tooltip controller="my-cool-btn">
+				<template #title>
+					What is an Experimental Field Partner?
+				</template>
+				If a Field Partner is labeled as Experimental, this means that Kiva has
+				required only a comparatively light level of due diligence and
+				monitoring, in exchange for only allowing this Field Partner access to a
+				small amount of funding through Kiva at any given time.
+			</kv-tooltip>
+		</div>
+	`,
+});

package/vue/stories/KvTreeMapChart.stories.js

@@ -0,0 +1,42 @@
+import KvTreeMapChart from '../KvTreeMapChart.vue';
+
+const genderValues = [{ label: 'Female', value: 1243, percent: 0.6467221644120708 }, { label: 'Male', value: 676, percent: 0.3517169614984391 }, { label: 'Unspecified', value: 2, percent: 0.001040582726326743 }, { label: 'Nonbinary', value: 1, percent: 0.0005202913631633715 }];
+const sectorValues = [{ label: 'Food', value: 575, percent: 0.2991675338189386 }, { label: 'Retail', value: 377, percent: 0.19614984391259105 }, { label: 'Agriculture', value: 285, percent: 0.14828303850156088 }, { label: 'Services', value: 211, percent: 0.10978147762747138 }, { label: 'Clothing', value: 183, percent: 0.09521331945889698 }, { label: 'Arts', value: 65, percent: 0.033818938605619145 }, { label: 'Housing', value: 65, percent: 0.033818938605619145 }, { label: 'Education', value: 36, percent: 0.018730489073881373 }, { label: 'Construction', value: 28, percent: 0.014568158168574402 }, { label: 'Health', value: 27, percent: 0.01404786680541103 }, { label: 'Transportation', value: 23, percent: 0.011966701352757543 }, { label: 'Personal Use', value: 19, percent: 0.009885535900104058 }, { label: 'Manufacturing', value: 13, percent: 0.006763787721123829 }, { label: 'Entertainment', value: 10, percent: 0.005202913631633715 }, { label: 'Wholesale', value: 5, percent: 0.0026014568158168575 }];
+
+export default {
+	title: 'Charts/KvTreeMapChart',
+	component: KvTreeMapChart,
+	args: {
+		loading: false,
+		values: genderValues,
+	},
+};
+
+const Template = (args, {
+	argTypes,
+}) => ({
+	props: Object.keys(argTypes),
+	components: {
+		KvTreeMapChart,
+	},
+	template: `
+		<div>
+			<kv-tree-map-chart
+                :values="values"
+                :loading="loading"
+            />
+		</div>`,
+});
+
+export const Default = Template.bind({});
+
+export const Loading = Template.bind({});
+Loading.args = {
+	loading: true,
+	values: [],
+};
+
+export const ManyValues = Template.bind({});
+ManyValues.args = {
+	values: sectorValues,
+};