bitboss-ui 2.1.113 → 2.1.115

package/dist/ai/BbPagination.md

@@ -0,0 +1,562 @@
+# BbPagination
+
+## Template & Script
+
+```vue
+<template>
+	<div
+		ref="outercontainer"
+		class="bb-pagination"
+		:class="{
+			[`bb-pagination--${align}`]: true,
+			'bb-pagination--disabled': disabled,
+		}"
+	>
+		<nav :aria-label="label">
+			<ul ref="innercontainer" class="bb-pagination__pages">
+				<li>
+					<BaseButton v-bind="previousAttributes">
+						<slot name="previous">
+							<span class="bb-pagination__page-label sr-only">{{
+								t('pagination.previous').value
+							}}</span>
+							<svg
+								class="bb-pagination__page-chevron"
+								viewBox="0 0 24 24"
+								xmlns="http://www.w3.org/2000/svg"
+							>
+								<path
+									d="M7.41 8.58L12 13.17l4.59-4.59L18 10l-6 6l-6-6z"
+									fill="currentColor"
+								/>
+							</svg>
+						</slot>
+					</BaseButton>
+				</li>
+				<li v-for="item in items" :key="item.key">
+					<BaseButton v-bind="itemAttributes(item)">
+						<template v-if="item.ellipsis === true">
+							<slot name="ellipsis">
+								<span class="bb-pagination__page-label">{{
+									props.ellipsis
+								}}</span>
+							</slot>
+						</template>
+						<template v-else>
+							<slot
+								:active="item.active"
+								:disabled="item.disabled"
+								:item="item.key"
+								name="item"
+							>
+								<span class="bb-pagination__page-label">{{ item.key }}</span>
+							</slot>
+						</template>
+					</BaseButton>
+				</li>
+				<li>
+					<BaseButton v-bind="nextAttributes">
+						<slot name="next">
+							<span class="bb-pagination__page-label sr-only">{{
+								t('pagination.next').value
+							}}</span>
+							<svg
+								class="bb-pagination__page-chevron"
+								viewBox="0 0 24 24"
+								xmlns="http://www.w3.org/2000/svg"
+							>
+								<path
+									d="M7.41 8.58L12 13.17l4.59-4.59L18 10l-6 6l-6-6z"
+									fill="currentColor"
+								/>
+							</svg>
+						</slot>
+					</BaseButton>
+				</li>
+			</ul>
+		</nav>
+	</div>
+</template>
+
+<script setup lang="ts">
+import { BaseButton } from '@/index';
+import { computed, nextTick, onBeforeUnmount, onMounted, ref } from 'vue';
+import { debounce } from '@/utilities/functions/debounce';
+import { useLocale } from '@/composables/useLocale';
+import { useRoute } from '@/composables/useRoute';
+import type {
+	BbPaginationProps,
+	BbPaginationEvents,
+	BbPaginationSlots,
+} from './types';
+export type { BbPaginationProps, BbPaginationEvents, BbPaginationSlots };
+
+const props = withDefaults(defineProps<BbPaginationProps>(), {
+	align: 'right',
+	ellipsis: '...',
+	label: 'Paginazione',
+	maxSize: 6,
+	querykey: 'page',
+	totalPages: 1,
+});
+
+defineSlots<BbPaginationSlots>();
+
+const { t } = useLocale();
+
+const model = defineModel<number>({ default: 1 });
+
+const route = useRoute();
+
+const totalPages = computed(() => +props.totalPages);
+const start = ref(1);
+const maxSize = ref(+props.maxSize);
+
+const outercontainer = ref<HTMLElement>();
+const innercontainer = ref<HTMLElement>();
+
+const buttonFootprint = ref<number>(Infinity);
+
+/**
+ * Adjusts how many buttons to show.
+ * if current buttons can't fit subtract maxSize until they do or until minimum is reached
+ * if more buttons could fit add buttons until the don't
+ * If minimum or maximum is reached just quit until next resize
+ */
+const adjustMaxElements = () => {
+	if (outercontainer.value && innercontainer.value) {
+		/* If some buttons do not fit */
+		if (outercontainer.value.clientWidth < innercontainer.value.clientWidth) {
+			if (maxSize.value - 1 > 3) {
+				maxSize.value--;
+				nextTick(adjustMaxElements);
+			} else {
+				maxSize.value = 3;
+			}
+			/* If all current buttons do fit */
+		} else {
+			/* If some buttons have been hidden */
+			if (maxSize.value < +props.maxSize) {
+				if (
+					/* If there is enough space to fit one */
+					outercontainer.value.clientWidth - innercontainer.value.clientWidth >
+					buttonFootprint.value
+				) {
+					maxSize.value = Math.min(maxSize.value + 1, +props.maxSize);
+					nextTick(adjustMaxElements);
+				}
+			}
+		}
+	}
+};
+if (globalThis.ResizeObserver) {
+	const observer = new ResizeObserver(debounce(adjustMaxElements, 200));
+	onMounted(() => {
+		if (outercontainer.value && innercontainer.value) {
+			const button = outercontainer.value.querySelectorAll(
+				'.bb-pagination__page'
+			)[1];
+			if (button) {
+				/* Compute the footprint necessary to render a new button */
+				const gapString = getComputedStyle(innercontainer.value).columnGap;
+				const numberAsString = gapString.replaceAll(/\D/g, '');
+				const gap = Number(numberAsString);
+				buttonFootprint.value = button.clientWidth + gap;
+			}
+			observer.observe(outercontainer.value);
+		}
+	});
+	onBeforeUnmount(() => {
+		observer.disconnect();
+	});
+}
+
+const range = computed(() => {
+	if (
+		totalPages.value <= 0 ||
+		isNaN(totalPages.value) ||
+		totalPages.value > Number.MAX_SAFE_INTEGER
+	)
+		return [];
+
+	if (maxSize.value <= 1) return [model.value];
+
+	if (totalPages.value <= maxSize.value) {
+		return createRange(totalPages.value, start.value);
+	}
+
+	const even = maxSize.value % 2 === 0;
+	const middle = even ? maxSize.value / 2 : Math.floor(maxSize.value / 2);
+	const left = even ? middle : middle + 1;
+	const right = totalPages.value - middle;
+
+	if (left - model.value >= 0) {
+		return [
+			...createRange(Math.max(1, maxSize.value - 1), start.value),
+			props.ellipsis,
+			totalPages.value,
+		];
+	} else if (model.value - right >= (even ? 1 : 0)) {
+		const rangeLength = maxSize.value - 1;
+		const rangeStart = totalPages.value - rangeLength + start.value;
+		return [
+			start.value,
+			props.ellipsis,
+			...createRange(rangeLength, rangeStart),
+		];
+	} else {
+		const rangeLength = Math.max(1, maxSize.value - 3);
+		const rangeStart =
+			rangeLength === 1
+				? model.value
+				: model.value - Math.ceil(rangeLength / 2) + start.value;
+		return [
+			start.value,
+			props.ellipsis,
+			...createRange(rangeLength, rangeStart),
+			props.ellipsis,
+			totalPages.value,
+		];
+	}
+});
+
+type Item =
+	| {
+			active: boolean;
+			key: string;
+			page: string;
+			ellipsis: true;
+			disabled: boolean;
+	  }
+	| {
+			active: boolean;
+			key: number;
+			page: number;
+			ellipsis: false;
+			disabled: boolean;
+	  };
+
+const items = computed<Item[]>(() => {
+	return range.value.map((item, index) => {
+		if (typeof item === 'string') {
+			return {
+				active: false,
+				key: `ellipsis-${index}`,
+				page: item,
+				ellipsis: true,
+				disabled: true,
+			};
+		} else {
+			const active = item === model.value;
+			return {
+				active,
+				key: item,
+				page: item,
+				ellipsis: false,
+				disabled: !!props.disabled || +props.totalPages < 2 || props.loading,
+			};
+		}
+	});
+});
+
+const createRange = (length: number, start = 0): number[] => {
+	return Array.from({ length }, (_, k) => start + k);
+};
+
+const previousAttributes = computed(() => {
+	const base: { [key: string]: any } = {
+		disabled: model.value <= 1 || props.loading || props.disabled,
+		onClick: () => {
+			if (model.value > 1) {
+				model.value = model.value - 1;
+			}
+		},
+		class: 'bb-pagination__page bb-pagination__page--previous',
+	};
+
+	if (props.navigation) {
+		const previousPage = (model.value - 1).toString();
+		if (route.value) {
+			base.to = {
+				path: route.value?.path,
+				query: { ...route.value?.query, [props.querykey]: previousPage },
+			};
+			base.replace = props.replace;
+		} else {
+			const url = new URL(globalThis.location.href);
+			url.searchParams.set(props.querykey, previousPage);
+			base.href = url.toString();
+		}
+	}
+
+	return base;
+});
+
+const itemAttributes = (item: Item) => {
+	const base: { [key: string]: any } = {
+		class: ['bb-pagination__page'],
+		disabled: item.disabled,
+		onClick: () => {
+			if (typeof item.key === 'number') {
+				model.value = item.key;
+			}
+		},
+	};
+	if (item.active) {
+		base.class.push('bb-pagination__page--active');
+	}
+	if (item.ellipsis) {
+		base.class.push('bb-pagination__page--ellipsis');
+	}
+
+	if (props.navigation) {
+		const page = item.key.toString();
+		if (route.value) {
+			base.to = {
+				path: route.value?.path,
+				query: { ...route.value?.query, [props.querykey]: page },
+			};
+			base.replace = props.replace;
+		} else {
+			const url = new URL(globalThis.location.href);
+			url.searchParams.set(props.querykey, page);
+			base.href = url.toString();
+		}
+	}
+	return base;
+};
+
+const nextAttributes = computed(() => {
+	const base: { [key: string]: any } = {
+		disabled:
+			model.value >= totalPages.value || props.loading || props.disabled,
+		onClick: () => {
+			if (model.value < totalPages.value) {
+				model.value = model.value + 1;
+			}
+		},
+		class: 'bb-pagination__page bb-pagination__page--next',
+	};
+
+	if (props.navigation) {
+		const nextPage = (model.value + 1).toString();
+		if (route.value) {
+			base.to = {
+				path: route.value?.path,
+				query: { ...route.value?.query, [props.querykey]: nextPage },
+			};
+			base.replace = props.replace;
+		} else {
+			const url = new URL(globalThis.location.href);
+			url.searchParams.set(props.querykey, nextPage);
+			base.href = url.toString();
+		}
+	}
+
+	return base;
+});
+</script>
+
+<style lang="postcss">
+@import './index.css';
+</style>
+```
+
+## Types
+
+```ts
+import type { CommonProps } from '@/types/CommonProps';
+
+export type BbPaginationProps = Pick<CommonProps, 'disabled' | 'loading'> & {
+	/**
+	 * Alignment of the pagination control.
+	 *
+	 * @defaultValue `'right'`
+	 */
+	align?: 'left' | 'right' | 'center';
+	/**
+	 * String of text displayed in place of hidden pages.
+	 *
+	 * @defaultValue `'...'`
+	 */
+	ellipsis?: string;
+	/**
+	 * Label of the pagination navigation landmark.
+	 *
+	 * @defaultValue `'Paginazione'`
+	 */
+	label?: string;
+	/**
+	 * Maximum number of clickable pages displayed at all times.
+	 * This has a tolerance of +/- 1 for odd / even numbering.
+	 * It does not include ellipses.
+	 *
+	 * @defaultValue `6`
+	 */
+	maxSize?: number | string;
+	/**
+	 * Synchronizes the current page with the URL.
+	 */
+	navigation?: boolean;
+
+	/**
+	 * Replaces history rather than pushing it when changing page.
+	 */
+	replace?: boolean;
+	/**
+	 * Defines the query key to reference for maintaining navigation.
+	 *
+	 * @defaultValue `'page'`
+	 */
+	querykey?: string;
+	/**
+	 * Total number of pages.
+	 *
+	 * @defaultValue `1`
+	 */
+	totalPages?: number | string;
+};
+
+export type BbPaginationEvents = {
+	/** Emitted when the active page changes. Payload is the new page number (1-based). */
+	(e: 'update:modelValue', value: number): void;
+};
+
+/** Props exposed by the `item` slot. */
+export type BbPaginationItemSlotProps = {
+	/** Whether this is the currently active page. */
+	active: boolean;
+	/** Whether this page button is disabled. */
+	disabled: boolean;
+	/** The page number this button represents. */
+	item: number;
+};
+
+export type BbPaginationSlots = {
+	/**
+	 * Replaces the default "previous page" button content.
+	 */
+	previous?: (props: object) => any;
+	/**
+	 * Replaces the default "next page" button content.
+	 */
+	next?: (props: object) => any;
+	/**
+	 * Replaces the default page number button content for each individual page.
+	 */
+	item?: (props: BbPaginationItemSlotProps) => any;
+	/**
+	 * Replaces the default `…` ellipsis shown when pages overflow the visible range.
+	 */
+	ellipsis?: (props: object) => any;
+};
+```
+
+## Styles
+
+```css
+.bb-pagination {
+	--color: var(--bb-primary);
+	--text-color: var(--bb-text);
+	--contrasting: var(--bb-contrasting);
+	--radius: var(--bb-radius);
+	--size: 32px;
+	overflow: hidden;
+	padding: var(--bb-ring-size) 0px;
+
+	width: 100%;
+
+	&--disabled {
+		--color: color-mix(in srgb, var(--bb-panel), var(--bb-text) 10%);
+		--text-color: color-mix(in srgb, var(--bb-panel), var(--bb-text) 40%);
+		--contrasting: color-mix(in srgb, var(--bb-panel), var(--bb-text) 40%);
+	}
+
+	&--left {
+	}
+	&--right {
+		.bb-pagination__pages {
+			margin-left: auto;
+		}
+	}
+	&--center {
+		.bb-pagination__pages {
+			margin-left: auto;
+			margin-right: auto;
+		}
+	}
+
+	.bb-pagination__pages {
+		align-items: center;
+		column-gap: 8px;
+		display: flex;
+		justify-content: center;
+		width: max-content;
+
+		li {
+			display: flex;
+
+			.bb-pagination__page {
+				align-items: center;
+				border-color: transparent;
+				border-radius: var(--radius);
+				border-width: 1px;
+				color: var(--text-color);
+				display: inline-flex;
+				font-size: 14px;
+				font-weight: 500;
+				justify-content: center;
+				min-height: var(--size);
+				min-width: var(--size);
+				padding: 4px;
+
+				&:not(.bb-pagination__page--active) {
+					transition-duration: 0s;
+				}
+
+				&--active {
+					background-color: var(--color);
+					border-color: var(--color);
+					color: var(--contrasting);
+				}
+
+				&--ellipsis {
+				}
+
+				&:hover:not(.bb-pagination__page--active):not(:disabled) {
+					--text-color: var(--color);
+					background-color: color-mix(in srgb, var(--color), transparent 85%);
+				}
+
+				&:focus-visible {
+					background-color: var(--color);
+					color: var(--contrasting);
+				}
+
+				&.bb-pagination__page--next,
+				&.bb-pagination__page--previous {
+					.bb-pagination__page-label {
+					}
+				}
+
+				&.bb-pagination__page--previous {
+					.bb-pagination__page-chevron {
+						rotate: 90deg;
+					}
+				}
+
+				&.bb-pagination__page--next {
+					.bb-pagination__page-chevron {
+						rotate: -90deg;
+					}
+				}
+
+				svg {
+					display: inline-block;
+					width: 20px; /* 1.75rem = 28px */
+				}
+			}
+		}
+	}
+}
+```