@kiva/kv-components 3.13.2 → 3.14.0

package/CHANGELOG.md

@@ -3,6 +3,23 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [3.14.0](https://github.com/kiva/kv-ui-elements/compare/@kiva/kv-components@3.13.2...@kiva/kv-components@3.14.0) (2023-04-17)
+
+
+### Bug Fixes
+
+* call userEvent directly ([461774f](https://github.com/kiva/kv-ui-elements/commit/461774f4e6596030b806d03084486e961011f8be))
+
+
+### Features
+
+* event guidelines ([37c1635](https://github.com/kiva/kv-ui-elements/commit/37c16351f8a29b3949745cc2786d394049bd6d5c))
+* move KvPagination component to kv-elements ([5f24d6a](https://github.com/kiva/kv-ui-elements/commit/5f24d6aae4bdb2909fb61c666b6a3d64dd76da99))
+
+
+
+
+
 ## [3.13.2](https://github.com/kiva/kv-ui-elements/compare/@kiva/kv-components@3.13.1...@kiva/kv-components@3.13.2) (2023-04-14)
 
 **Note:** Version bump only for package @kiva/kv-components

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kiva/kv-components",
-  "version": "3.13.2",
+  "version": "3.14.0",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -69,5 +69,5 @@
       "optional": true
     }
   },
-  "gitHead": "4c0fd566bb167fb765adf4bd92dccb4bb0814059"
+  "gitHead": "fb5b0f2e5f92a57add53608ac3eddb0e100620be"
 }

package/tests/unit/specs/components/KvPagination.spec.js

@@ -0,0 +1,132 @@
+import { render } from '@testing-library/vue';
+import userEvent from '@testing-library/user-event';
+import KvPagination from '../../../../vue/KvPagination.vue';
+
+global.scrollTo = jest.fn();
+
+describe('KvPagination', () => {
+	afterEach(jest.clearAllMocks);
+
+	it('should render arrows disabled by default', async () => {
+		const { getByLabelText, emitted } = render(KvPagination, { props: { limit: 10, total: 0 } });
+
+		await userEvent.click(getByLabelText('Previous page'));
+		await userEvent.click(getByLabelText('Next page'));
+
+		expect(emitted()['page-changed']).toBe(undefined);
+	});
+
+	it('should render aria current page label', () => {
+		const { getByText } = render(KvPagination, { props: { limit: 10, total: 30 } });
+
+		getByText("You're on page");
+	});
+
+	it('should render fewer pages', () => {
+		const { getByLabelText } = render(KvPagination, { props: { limit: 10, total: 30 } });
+
+		getByLabelText('Page 1');
+		getByLabelText('Page 2');
+		getByLabelText('Page 3');
+	});
+
+	it('should render more pages', () => {
+		const { getByLabelText } = render(KvPagination, { props: { limit: 10, total: 1000 } });
+
+		getByLabelText('Page 1');
+		getByLabelText('Page 2');
+		getByLabelText('Page 3');
+		getByLabelText('Page 4');
+		getByLabelText('Page 100');
+	});
+
+	it('should render fourth selected', () => {
+		const { getByLabelText } = render(
+			KvPagination, { props: { limit: 10, total: 1000, offset: 30 } },
+		);
+
+		getByLabelText('Page 1');
+		getByLabelText('Page 3');
+		getByLabelText('Page 4');
+		getByLabelText('Page 5');
+		getByLabelText('Page 100');
+	});
+
+	it('should render last selected', () => {
+		const { getByLabelText } = render(
+			KvPagination, { props: { limit: 10, total: 1000, offset: 990 } },
+		);
+
+		getByLabelText('Page 1');
+		getByLabelText('Page 97');
+		getByLabelText('Page 98');
+		getByLabelText('Page 99');
+		getByLabelText('Page 100');
+	});
+
+	it('should render fourth to last last selected', () => {
+		const { getByLabelText } = render(
+			KvPagination, { props: { limit: 10, total: 1000, offset: 960 } },
+		);
+
+		getByLabelText('Page 1');
+		getByLabelText('Page 96');
+		getByLabelText('Page 97');
+		getByLabelText('Page 98');
+		getByLabelText('Page 100');
+	});
+
+	it('should render more extra pages', () => {
+		const { getByLabelText } = render(
+			KvPagination, { props: { limit: 10, total: 1000, extraPages: 6 } },
+		);
+
+		getByLabelText('Page 1');
+		getByLabelText('Page 2');
+		getByLabelText('Page 3');
+		getByLabelText('Page 4');
+		getByLabelText('Page 5');
+		getByLabelText('Page 6');
+		getByLabelText('Page 7');
+		getByLabelText('Page 100');
+	});
+
+	it('should emit page click', async () => {
+		const { getByLabelText, emitted } = render(
+			KvPagination, { props: { limit: 10, total: 1000 } },
+		);
+
+		await userEvent.click(getByLabelText('Page 2'));
+
+		expect(global.scrollTo).toHaveBeenCalledTimes(1);
+		expect(emitted()['page-changed']).toEqual([[{ pageOffset: 10 }]]);
+	});
+
+	it('should not emit current page click', async () => {
+		const { getByLabelText, emitted } = render(KvPagination, { props: { limit: 10, total: 1000 } });
+
+		await userEvent.click(getByLabelText('Page 1'));
+
+		expect(emitted()['page-changed']).toBe(undefined);
+	});
+
+	it('should emit previous click', async () => {
+		const { getByLabelText, emitted } = render(
+			KvPagination, { props: { limit: 10, total: 1000, offset: 10 } },
+		);
+
+		await userEvent.click(getByLabelText('Previous page'));
+
+		expect(global.scrollTo).toHaveBeenCalledTimes(1);
+		expect(emitted()['page-changed']).toEqual([[{ pageOffset: 0 }]]);
+	});
+
+	it('should emit next click', async () => {
+		const { getByLabelText, emitted } = render(KvPagination, { props: { limit: 10, total: 1000 } });
+
+		await userEvent.click(getByLabelText('Next page'));
+
+		expect(global.scrollTo).toHaveBeenCalledTimes(1);
+		expect(emitted()['page-changed']).toEqual([[{ pageOffset: 10 }]]);
+	});
+});

package/vue/KvPagination.vue

@@ -0,0 +1,198 @@
+<template>
+	<nav aria-label="Pagination">
+		<ul
+			class="tw-text-center tw-mx-auto tw-my-1.5 tw-flex tw-justify-between tw-items-center"
+			style="max-width: 17rem;"
+		>
+			<li>
+				<a
+					class="tw-cursor-pointer tw-flex"
+					:class="linkClass(0)"
+					aria-label="Previous page"
+					@click="!isCurrent(0) && clickPrevious()"
+				>
+					<kv-material-icon
+						:icon="mdiChevronLeft"
+						class="tw-h-4 tw-w-4"
+					/>
+					<span class="tw-sr-only">Previous page</span>
+				</a>
+			</li>
+			<li
+				v-for="(n, i) in numbers"
+				:key="i"
+				:aria-hidden="isEllipsis(n)"
+			>
+				<template v-if="isEllipsis(n)">
+					...
+				</template>
+				<a
+					v-else
+					class="tw-cursor-pointer"
+					:class="linkClass(n)"
+					:aria-label="`Page ${n + 1}`"
+					@click="!isCurrent(n) && clickPage(n)"
+				>
+					<span
+						v-if="isCurrent(n)"
+						class="tw-sr-only"
+					>You're on page</span>
+					{{ n + 1 }}
+				</a>
+			</li>
+			<li>
+				<a
+					class="tw-cursor-pointer tw-flex"
+					:class="linkClass(totalPages ? totalPages - 1 : 0)"
+					aria-label="Next page"
+					@click="totalPages && !isCurrent(totalPages - 1) && clickNext()"
+				>
+					<kv-material-icon
+						:icon="mdiChevronRight"
+						class="tw-h-4 tw-w-4"
+					/>
+					<span class="tw-sr-only">Next page</span>
+				</a>
+			</li>
+		</ul>
+	</nav>
+</template>
+
+<script>
+import { mdiChevronLeft, mdiChevronRight } from '@mdi/js';
+import KvMaterialIcon from './KvMaterialIcon.vue';
+
+export default {
+	name: 'KvPagination',
+	components: {
+		KvMaterialIcon,
+	},
+	props: {
+		limit: {
+			type: Number,
+			required: true,
+			validator: (value) => value > 0,
+		},
+		total: {
+			type: Number,
+			required: true,
+			validator: (value) => value >= 0,
+		},
+		offset: {
+			type: Number,
+			default: 0,
+			validator: (value) => value >= 0,
+		},
+		extraPages: {
+			type: Number,
+			default: 3,
+			validator: (value) => value > 0,
+		},
+		scrollToTop: {
+			type: Boolean,
+			default: true,
+		},
+		kvTrackFunction: {
+			type: Function,
+			default: () => {},
+		},
+		trackEventCategory: {
+			type: String,
+			default: '',
+		},
+	},
+	data() {
+		return {
+			mdiChevronLeft,
+			mdiChevronRight,
+		};
+	},
+	computed: {
+		current() {
+			const page = this.offset / this.limit;
+
+			// This component uses a 0-based page index
+			return page < this.totalPages ? page : 0;
+		},
+		totalPages() {
+			return Math.ceil(this.total / this.limit);
+		},
+		numbers() {
+			// If less than the max, there will be no ellipsis, so just return the numbers
+			if (this.totalPages < (this.extraPages + 2)) {
+				return this.range(0, this.totalPages - 1);
+			}
+
+			const numbers = [];
+
+			// Add the 'middle' block of numbers based upon the current page
+			if ([0, 1, 2].includes(this.current)) {
+				numbers.push(...this.range(1, this.extraPages));
+			} else if ([this.totalPages - 3, this.totalPages - 2, this.totalPages - 1]
+				.includes(this.current)) {
+				numbers.push(...this.range(this.totalPages - this.extraPages - 1, this.totalPages - 2));
+			} else {
+				const delta = Math.floor(this.extraPages / 2);
+				numbers.push(...this.range(this.current - delta, this.current + delta));
+			}
+
+			// Add a placeholder for first ellipsis
+			if (numbers[1] !== 2) {
+				numbers.splice(0, 0, -1);
+			}
+
+			// Add a placeholder for second ellipsis
+			const totalNumbers = numbers.length;
+			if (numbers[totalNumbers - 1] !== this.totalPages - 2) {
+				numbers.splice(totalNumbers, 0, -1);
+			}
+
+			// Add first and last pages
+			numbers.unshift(0);
+			numbers.push(this.totalPages - 1);
+
+			return numbers;
+		},
+	},
+	methods: {
+		range(start, end) {
+			return [...Array(end - start + 1)].map((_, n) => n + start);
+		},
+		isCurrent(number) {
+			return number === this.current;
+		},
+		isEllipsis(number) {
+			return number === -1;
+		},
+		linkClass(number) {
+			return { 'tw-text-tertiary': this.isCurrent(number), 'tw-pointer-events-none': this.isCurrent(number) };
+		},
+		pageChange(number) {
+			if (this.scrollToTop && window.scrollTo) {
+				window.scrollTo({ top: 0, left: 0, behavior: 'smooth' });
+			}
+
+			this.$emit('page-changed', { pageOffset: number * this.limit });
+		},
+		clickPage(number) {
+			this.pageChange(number);
+
+			this.kvTrackFunction(this.trackEventCategory, 'click', 'pagination-number', null, number + 1);
+		},
+		clickPrevious() {
+			const previous = this.current - 1;
+
+			this.pageChange(previous);
+
+			this.kvTrackFunction(this.trackEventCategory, 'click', 'pagination-previous', null, previous + 1);
+		},
+		clickNext() {
+			const next = this.current + 1;
+
+			this.pageChange(next);
+
+			this.kvTrackFunction(this.trackEventCategory, 'click', 'pagination-next', null, next + 1);
+		},
+	},
+};
+</script>

package/vue/stories/KvPagination.stories.js

@@ -0,0 +1,70 @@
+import KvPagination from '../KvPagination.vue';
+
+export default {
+	title: 'KvPagination',
+	component: KvPagination,
+};
+
+const story = (args) => {
+	const template = (_args, { argTypes }) => ({
+		props: Object.keys(argTypes),
+		components: { KvPagination },
+		template: `<kv-pagination
+			:limit="limit"
+			:total="total"
+			:offset="offset"
+			:extra-pages="extraPages"
+			:kv-track-function="kvTrackMock"
+			:track-event-category="trackEventCategory"
+			/>`,
+		methods: {
+			kvTrackMock(
+				category,
+				action,
+				label,
+				property,
+				value,
+			) {
+				console.log(category, action, label, property, value);
+			},
+		},
+	});
+	template.args = args;
+	return template;
+};
+
+export const Default = story({ limit: 10, total: 0, trackEventCategory: 'blog-articles' });
+
+export const FewerPages = story({ limit: 10, total: 30, trackEventCategory: 'blog-articles' });
+
+export const MorePages = story({ limit: 10, total: 1000, trackEventCategory: 'blog-articles' });
+
+export const SecondSelected = story({
+	limit: 10, total: 1000, offset: 10, trackEventCategory: 'blog-articles',
+});
+
+export const ThirdSelected = story({
+	limit: 10, total: 1000, offset: 20, trackEventCategory: 'blog-articles',
+});
+
+export const FourthSelected = story({
+	limit: 10, total: 1000, offset: 30, trackEventCategory: 'blog-articles',
+});
+
+export const LastSelected = story({
+	limit: 10, total: 1000, offset: 990, trackEventCategory: 'blog-articles',
+});
+
+export const SecondToLastSelected = story({
+	limit: 10, total: 1000, offset: 980, trackEventCategory: 'blog-articles',
+});
+
+export const ThirdToLastSelected = story({
+	limit: 10, total: 1000, offset: 970, trackEventCategory: 'blog-articles',
+});
+
+export const FourthToLastSelected = story({
+	limit: 10, total: 1000, offset: 960, trackEventCategory: 'blog-articles',
+});
+
+export const MoreExtraPages = story({ limit: 10, total: 1000, extraPages: 6 });