bitboss-ui 2.1.135 → 3.0.0-alpha.4

package/dist/ai/BbPagination.md

@@ -1,561 +1,515 @@
 # BbPagination
 
-## Template & Script
+## Agent Contract
+
+- Safety level: **Consumer API**
+- Group: **Navigation**
+- Description: Navigates paginated data sets by page index.
+- Usage rule: Prefer this component for consumer-facing implementations.
+- Implementation source (only when the contract below is not enough): [source/BbPagination.md](./source/BbPagination.md)
+
+## Usage & Guidelines
+
+### When to use
+
+Reach for `BbPagination` when a list is too long for one screen and the user
+needs deterministic, jump-anywhere access to any page — search results, an
+invoice ledger, an audit log. Prefer it over infinite scroll whenever people
+need to _find their place again_ or reference "page 4".
+
+It is a pure page selector: it does not fetch, slice, or store your data — you
+own that and drive it from the page it reports. For hierarchy use
+`BbBreadcrumbs`; for switching peer views use `BbTabs`.
+
+### Control the current page with `v-model`
+
+`v-model` is the current page (1-based); `total-pages` sets the range (a number
+or numeric string — handy when it comes straight from an API). The control
+clamps out-of-range pages back into `1..totalPages` (assign `99` and the model
+snaps back), disables _Previous_ on page 1 and _Next_ on the last page, and
+renders the whole range when it fits. With a single page every page button is
+disabled — pagination for one page is inert by design, so consider hiding the
+control instead.
+
+**A bound page selector**
+
+```vue
+<div class="space-y-2">
+	<BbPagination v-model="state.page" :total-pages="24" />
+	<p class="text-xs text-[color:var(--bb-text-muted)]">On page {{ state.page ?? 1 }} of 24.</p>
+</div>
+```
+
+The only event is `update:modelValue` (the new 1-based page) — everything else
+(which buttons disable, where the ellipses go) is handled internally. Listen to
+the model, not to clicks.
+
+### Folding, fit and alignment
+
+Long ranges fold around the current page with ellipses — you never compute the
+window yourself. Three knobs shape the strip:
+
+- `max-size` (default 6) caps how many **page** buttons show at once — the
+  count excludes the ellipses and _Previous_/_Next_, and has a ±1 tolerance so
+  odd/even windows stay balanced around the current page.
+- The strip also **fits itself**: a `ResizeObserver` drops page buttons (never
+  below 3) when the container is too narrow and adds them back when space
+  returns, so `max-size` is a maximum, not a promise.
+- `align` places the control within its full-width row: `right` (default),
+  `center`, or `left`.
+- `ellipsis` swaps the `...` placeholder text (the ellipsis buttons themselves
+  are always disabled).
+
+**Long ranges collapse with an ellipsis**
+
+```vue
+<BbPagination
+	v-model="state.page"
+	align="center"
+	:max-size="7"
+	:total-pages="42"
+/>
+```
+
+### Wire it to your data
+
+Pagination reports the page; your code turns that into the visible slice.
+Give it the count the server reports — either `total-pages` directly, or
+`total-items` with `per-page` and the control computes
+`ceil(totalItems / perPage)` itself (when both are present, the derived count
+wins over `total-pages`). Watch the page and fetch (or slice) when it changes. If you need to freeze the control — no data yet, a
+blocking error, or to stop a user outrunning an in-flight request — set
+`disabled`. Pagination has no `loading` state of its own: it is a page selector,
+not a data-fetching surface, so keep the in-flight/loading affordance on the
+list or table it drives.
+
+**Repaginating a list**
+
+```vue
+<template>
+	<!-- Manual wire-up: the pager reports the page; you slice (or fetch) from it.
+	     Prefer this over `table-id` when the list is not a BbTable. -->
+	<div
+		class="max-w-md overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+	>
+		<ul class="divide-y divide-[color:var(--bb-border)]">
+			<li
+				v-for="invoice in pageItems"
+				:key="invoice.id"
+				class="flex items-center justify-between gap-2 px-3 py-2 text-sm"
+			>
+				<span class="font-medium tabular-nums">{{ invoice.number }}</span>
+				<span
+					class="min-w-0 flex-1 truncate text-[color:var(--bb-text-muted)]"
+					>{{ invoice.customer }}</span
+				>
+				<span
+					class="shrink-0 text-xs tabular-nums text-[color:var(--bb-text-muted)]"
+					>{{ invoice.amount }}</span
+				>
+			</li>
+		</ul>
+		<div
+			class="flex flex-wrap items-center justify-between gap-2 border-t border-[color:var(--bb-border)] px-3 py-2"
+		>
+			<p class="text-xs text-[color:var(--bb-text-muted)]" data-test="range">
+				{{ rangeStart }}–{{ rangeEnd }} of {{ invoices.length }}
+			</p>
+			<BbPagination
+				v-model="page"
+				label="Invoices pagination"
+				:per-page="perPage"
+				:total-items="invoices.length"
+			/>
+		</div>
+	</div>
+</template>
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import { BbPagination } from 'bitboss-ui';
+
+type Invoice = { id: number; number: string; customer: string; amount: string };
+
+const customers = [
+	'Northwind Traders',
+	'Globex',
+	'Initech',
+	'Umbrella',
+	'Soylent',
+	'Hooli',
+];
+const invoices: Invoice[] = Array.from({ length: 47 }, (_, index) => ({
+	id: index + 1,
+	number: `INV-${1042 + index}`,
+	customer: customers[index % customers.length],
+	amount: `€${(480 + index * 35).toLocaleString('en-IE')}.00`,
+}));
+
+const perPage = 5;
+const page = ref(1);
+
+// The page reported by BbPagination is all we need to slice the data ourselves.
+const rangeStart = computed(() => (page.value - 1) * perPage + 1);
+const rangeEnd = computed(() =>
+	Math.min(page.value * perPage, invoices.length)
+);
+const pageItems = computed(() =>
+	invoices.slice(rangeStart.value - 1, rangeEnd.value)
+);
+</script>
+```
+
+### Custom button content via slots
+
+Four slots restyle the buttons without touching their behavior: `item` receives
+`{ item, active, disabled }` for each page number, `previous` / `next` replace
+the chevrons (no scope — keep the content self-describing for screen readers),
+and `ellipsis` replaces the fold marker. The buttons stay real buttons with all
+their wiring; the slots only swap what is painted inside them.
+
+**Wordy controls for a document reader**
 
 ```vue
 <template>
 	<div
-		ref="outercontainer"
-		class="bb-pagination"
-		:class="{
-			[`bb-pagination--${align}`]: true,
-			'bb-pagination--disabled': disabled,
-		}"
+		class="max-w-sm space-y-2 rounded-[var(--bb-radius)] border border-[color:var(--bb-border)] p-3"
 	>
-		<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
+			class="rounded-[var(--bb-radius)] bg-[color:var(--bb-muted)] px-3 py-8 text-center text-sm text-[color:var(--bb-text-muted)]"
+		>
+			Sheet {{ sheet }} of 18 · Q3 board pack
+		</div>
+		<BbPagination
+			v-model="sheet"
+			align="left"
+			label="Document sheets"
+			:max-size="5"
+			:total-pages="18"
+		>
+			<template #previous><span class="px-1 text-xs">Prev</span></template>
+			<template #next><span class="px-1 text-xs">Next</span></template>
+			<template #item="{ item, active }">
+				<span
+					class="px-0.5 text-xs"
+					:class="active && 'font-semibold underline'"
+				>
+					{{ item }}
+				</span>
+			</template>
+		</BbPagination>
 	</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';
-
-const props = withDefaults(defineProps<BbPaginationProps>(), {
-	align: 'right',
-	ellipsis: '...',
-	label: 'Paginazione',
-	maxSize: 6,
-	querykey: 'page',
-	totalPages: 1,
-});
+import { ref } from 'vue';
+import { BbPagination } from 'bitboss-ui';
+
+// The reader tracks which sheet is visible; the slots only restyle the buttons.
+const sheet = ref(1);
+</script>
+```
 
-defineSlots<BbPaginationSlots>();
+### Pair with a `BbTable` through a shared id
 
-const { t } = useLocale();
+When the list is a `BbTable`, skip the manual wiring: give the table an `id`
+and the pagination the matching `table-id`. Both components publish their
+pagination props into the shared table context (see `useBbTableContext`), so
+the page count is derived automatically and the current page stays two-way
+synced. No `v-model` needed; mount order doesn't matter, and a page already
+present in the context wins at mount.
 
-const model = defineModel<number>({ default: 1 });
+The props are symmetric: `page`, `per-page`, `total-items`, and `total-pages`
+are accepted by both components, so the server's fields can be passed to
+whichever one is convenient — `total-items` on the table or on the pager both
+end up as the same shared `total`. One rule resolves conflicts: a page count
+derived from a real `total-items` always wins, and `total-pages` (on either
+side) is only a seed for when no row count is known — the common case being an
+externally paged array table, whose rows are one page and no total.
 
-const route = useRoute();
+For server paging, read the shared page with `useBbTableContext(id)` and use it
+inside the items provider. A provider table **already treats the shared page as
+a refetch trigger** — so a page turn re-runs the provider on its own; you do
+_not_ list `page` in `dependencies` (that's only for your own filters/sort). The
+table shows its own skeletons while it awaits — no watcher, no `loading` ref of
+your own. Sit the pager in the table footer:
 
-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,
-		];
-	}
-});
+**Server-paged audit log footer**
 
-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,
-			};
-		}
+```vue
+<template>
+	<!-- Server-paged table footer: the shared `audit-log` id pairs the table and
+	     pager. A provider table auto-refetches when the shared page moves, so no
+	     `dependencies` wiring is needed — the provider just reads `page` from the
+	     same context the pager drives. -->
+	<div
+		class="max-w-md overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+	>
+		<BbTable
+			id="audit-log"
+			caption="Audit log"
+			:columns="columns"
+			compact
+			item-value="id"
+			:items="fetchEvents"
+		/>
+		<div
+			class="flex flex-wrap items-center justify-between gap-2 border-t border-[color:var(--bb-border)] px-3 py-2"
+		>
+			<p class="text-xs text-[color:var(--bb-text-muted)]">
+				{{ rangeStart }}–{{ rangeEnd }} of {{ total }}
+			</p>
+			<BbPagination label="Audit log pagination" table-id="audit-log" />
+		</div>
+	</div>
+</template>
+<script setup lang="ts">
+import { computed } from 'vue';
+import { BbPagination, BbTable, useBbTableContext } from 'bitboss-ui';
+import type { BbTableColumn } from 'bitboss-ui';
+
+type AuditEvent = { id: number; action: string; actor: string; time: string };
+
+const columns: Array<BbTableColumn<AuditEvent>> = [
+	{ key: 'action', label: 'Action' },
+	{ key: 'actor', label: 'Actor' },
+	{ key: 'time', label: 'When', align: 'right', width: 120 },
+];
+
+const actions = [
+	'member.invited',
+	'api_key.created',
+	'billing.plan_changed',
+	'webhook.updated',
+	'sso.login_failed',
+	'invoice.exported',
+	'role.updated',
+];
+const actors = ['ada@acme.io', 'grace@acme.io', 'linus@acme.io'];
+const events: AuditEvent[] = Array.from({ length: 23 }, (_, index) => ({
+	id: index + 1,
+	action: actions[index % actions.length],
+	actor: actors[index % actors.length],
+	time: `2026-07-0${9 - Math.floor(index / 10)} ${String(
+		18 - (index % 10)
+	).padStart(2, '0')}:${String((index * 7) % 60).padStart(2, '0')}`,
+}));
+
+// Same id as the table: seed `perPage` on the context handle so the table
+// reads its page size from the shared context — no `:per-page` prop needed.
+// `page` and `perPage` here are the same refs the pager drives and the table
+// announces.
+const { page, perPage, total } = useBbTableContext('audit-log', { perPage: 5 });
+
+const rangeStart = computed(() => (page.value - 1) * perPage.value + 1);
+const rangeEnd = computed(() =>
+	Math.min(page.value * perPage.value, total.value)
+);
+
+/** Non-query table provider — playbook signature; page/perPage come from context. */
+const fetchEvents = (_prefill: boolean): Promise<AuditEvent[]> =>
+	new Promise((resolve) => {
+		setTimeout(() => {
+			const start = (page.value - 1) * perPage.value;
+			total.value = events.length;
+			resolve(events.slice(start, start + perPage.value));
+		}, 250);
 	});
-});
+</script>
+```
 
-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;
-});
+Any other component can join the same rendezvous with
+`useBbTableContext('audit-log')` — read `ctx.page` in a toolbar, reset it after
+a filter change — and the pager follows. Mind the id: a typo doesn't error, it
+just pairs with nothing.
+
+### URL-synced pagination
+
+Set `navigation` to reflect the current page in the URL, so a page is
+bookmarkable and survives a reload. `query-key` names the query parameter
+(default `page`). Under Vue Router or Nuxt each enabled button becomes a `to`
+link that merges the param into the current route's query (other params
+survive). Without a router it falls back to real `href`s built from
+`window.location`, so the same markup deep-links in a plain SPA too.
 
-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;
+**Pair `navigation` with `replace`.** Paging is a view control, not a journey:
+without `replace` every page click pushes a history entry, and a user who
+walked to page 12 needs eleven Backs to escape the list. `replace` keeps the
+URL current — still deep-linkable, still reload-proof — while one Back returns
+to wherever they entered the list from.
+
+One thing stays yours: **the component does not read the URL at mount** — it
+writes it. Initialize the model from the route once, and `navigation` keeps
+them in sync from then on:
+
+**URL-synced exports with replace**
+
+```vue
+<template>
+	<!-- `navigation` + `replace`: ?page stays deep-linkable; Back leaves the list
+	     instead of walking every page click. Seed v-model from the route once —
+	     the control writes the URL, it does not read it at mount. -->
+	<div
+		class="max-w-md overflow-hidden rounded-[var(--bb-radius)] border border-[color:var(--bb-border)]"
+	>
+		<ul class="divide-y divide-[color:var(--bb-border)]">
+			<li
+				v-for="row in pageItems"
+				:key="row.id"
+				class="flex items-center justify-between gap-2 px-3 py-2 text-sm"
+			>
+				<span class="font-medium">{{ row.label }}</span>
+				<span class="text-xs tabular-nums text-[color:var(--bb-text-muted)]">{{
+					row.when
+				}}</span>
+			</li>
+		</ul>
+		<div
+			class="flex flex-wrap items-center justify-between gap-2 border-t border-[color:var(--bb-border)] px-3 py-2"
+		>
+			<p class="text-xs text-[color:var(--bb-text-muted)]">
+				Page {{ page }} of {{ totalPages }}
+			</p>
+			<BbPagination
+				v-model="page"
+				label="Exports pagination"
+				navigation
+				query-key="page"
+				replace
+				:total-pages="totalPages"
+			/>
+		</div>
+	</div>
+</template>
+<script setup lang="ts">
+import { computed, ref } from 'vue';
+import { BbPagination } from 'bitboss-ui';
+
+type ExportRow = { id: number; label: string; when: string };
+
+const rows: ExportRow[] = [
+	{ id: 1, label: 'Invoices CSV · Jul 2026', when: '2 min ago' },
+	{ id: 2, label: 'Payments CSV · Q2', when: '1 hr ago' },
+	{ id: 3, label: 'Customers JSON', when: 'Yesterday' },
+	{ id: 4, label: 'Tax summary PDF', when: 'Jul 18' },
+	{ id: 5, label: 'Audit trail CSV', when: 'Jul 12' },
+	{ id: 6, label: 'Usage report XLSX', when: 'Jul 03' },
+	{ id: 7, label: 'Refunds CSV · Jun', when: 'Jun 28' },
+	{ id: 8, label: 'Team roster CSV', when: 'Jun 14' },
+	{ id: 9, label: 'Webhooks JSON', when: 'May 30' },
+	{ id: 10, label: 'Ledger dump CSV', when: 'May 09' },
+	{ id: 11, label: 'Plan changes CSV', when: 'Apr 22' },
+	{ id: 12, label: 'API keys CSV', when: 'Apr 02' },
+];
+
+const perPage = 4;
+const page = ref(1);
+const totalPages = Math.ceil(rows.length / perPage);
+
+const pageItems = computed(() => {
+	const start = (page.value - 1) * perPage;
+	return rows.slice(start, start + perPage);
 });
 </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;
-};
-```
+Seed from the route in your app (the companion above starts at page 1 for the
+preview; production code reads the query once):
 
-## 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 */
-				}
-			}
-		}
-	}
-}
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import { useRoute } from 'vue-router'; // or '#imports' in Nuxt
+
+const route = useRoute();
+const page = ref(Number(route.query.page) || 1);
+</script>
 ```
+
+Disabled buttons (the current page's _Previous_/_Next_ at the edges, and every
+button while `disabled`) never carry a link, so crawlers and middle-clicks can't
+reach invalid pages.
+
+### Works well with
+
+- `BbTable` — the shared-id pairing above; `per-page`/`total-items` on either
+  component drive the page count.
+- `useBbTableContext` — bulk-action toolbars and filters that reset `page` to 1
+  when the query changes.
+- `BbSelect` — a small page-size selector next to the pager; recompute
+  `total-pages` and clamp happens for free.
+- `BbBreadcrumbs` / `BbTabs` — siblings, not alternatives: hierarchy and peer
+  views respectively. See the component picker.
+
+### Gotchas and anti-patterns
+
+- **Name the list you're paging.** The `nav` landmark's default label follows
+  the configured locale (`pagination.label` → `'Pagination'` / `'Paginazione'`),
+  but a generic "Pagination" is a poor landmark when a page has several. Set
+  `label` to say _which_ list: `label="Invoices pagination"`.
+- **`navigation` writes the URL, it doesn't read it** — seed `v-model` from the
+  route at setup (example above) or a shared link lands on page 1.
+- **`navigation` without `replace` buries the Back button.** Every page click
+  becomes a history entry, so leaving a list the user paged through takes one
+  Back per page visited. Add `replace`: the URL stays deep-linkable and Back
+  goes back to the previous _screen_, which is what the user meant.
+- **Pages are 1-based.** Page `0` is clamped to `1`; your slicing math is
+  `(page - 1) * perPage`.
+- **Don't rebuild the window.** No manual ellipsis math, no hiding buttons with
+  CSS — `max-size` plus the container-fit behavior already handle it.
+- **Don't fetch inside the pager.** It's a selector; watch the model (or the
+  table context) and fetch in your own code.
+- **Don't feed conflicting counts to a paired table and pager.** With a
+  `table-id`, both components publish their pagination props into the shared
+  context; giving each a different `total-items` (or `total-pages`) is an
+  author error the library resolves arbitrarily. Pass each fact to one place.
+
+### Accessibility
+
+- The control is a labelled `nav` landmark — its default label is locale-aware;
+  set `label` to describe _which_ list it paginates (see the gotcha above).
+- Every control is a real `button` (or a link under `navigation`): normal Tab
+  order, Enter/Space activation, no custom keyboard model to learn. There is no
+  roving focus — each page button is a tab stop.
+- The active page carries `aria-current="page"`; _Previous_ / _Next_ ship
+  visually-hidden, locale-aware text labels behind their chevrons. If you
+  replace the `previous`/`next` slots, include accessible text (visible or
+  `sr-only`) yourself.
+- Reach for `disabled` to freeze the whole control. Pagination has no `loading`
+  state — keep the in-flight affordance on the list or table it drives.
+
+## v-model
+
+- `v-model` — type: `number \| undefined`
+
+## Props
+
+| Prop | Type | Default | Required | Description |
+| --- | --- | --- | --- | --- |
+| `align` | `"left" \| "center" \| "right" \| undefined` | `"right"` |  | Alignment of the pagination control. |
+| `disabled` | `boolean \| undefined` |  |  | Disables the component |
+| `ellipsis` | `string \| undefined` | `"..."` |  | String of text displayed in place of hidden pages. |
+| `label` | `string \| undefined` |  |  | Label of the pagination navigation landmark. When unset, falls back to the localized `pagination.label` (`'Pagination'` / `'Paginazione'`). |
+| `maxSize` | `string \| number \| undefined` | `6` |  | Maximum number of clickable pages displayed at all times. This has a tolerance of +/- 1 for odd / even numbering. It does not include ellipses. |
+| `modelValue` | `number \| undefined` | `1` |  | Used by v-model. The 1-based index of the current page — pagination starts on the first page, not page `0`. |
+| `navigation` | `boolean \| undefined` |  |  | Synchronizes the current page with the URL. Pair it with `replace` — see that prop. |
+| `perPage` | `string \| number \| undefined` |  |  | Number of items per page. Together with `totalItems` it derives the page count (`ceil(totalItems / perPage)`); when unset, one page holds everything. With a `tableId` it is also published to the shared table context, exactly like the table'… |
+| `queryKey` | `string \| undefined` | `"page"` |  | Defines the query key to reference for maintaining navigation. |
+| `replace` | `boolean \| undefined` |  |  | Replaces history rather than pushing it when changing page. Recommended default whenever `navigation` is on: the URL keeps the current page (deep-linkable, survives reload) while Back returns to the page the user came from, instead of stepp… |
+| `tableId` | `string \| undefined` |  |  | Id of a `BbTable` to pair with through the shared table context (see `useBbTableContext`). The current page is kept two-way synced with the table's context state, and the context's page count drives the control, overriding the local props. … |
+| `totalItems` | `string \| number \| undefined` |  |  | Total number of items across all pages. When set, the page count is derived as `ceil(totalItems / perPage)` and wins over `totalPages`. With a `tableId` it is also published to the shared table context, exactly like the table's own `total-i… |
+| `totalPages` | `string \| number \| undefined` |  |  | Total number of pages. A shortcut for when the server reports a page count rather than a row count — a page count derived from `totalItems` (locally or through the shared table context) always wins over it. Falls back to `1` when nothing pr… |
+
+## Events
+
+- `update:modelValue` — `(event: "update:modelValue", value: number): void`
+
+## Slots
+
+- `ellipsis` — scope: `Record<string, never>` — Replaces the default `…` ellipsis shown when pages overflow the visible range.
+- `item` — scope: `BbPaginationItemSlotProps` — Replaces the default page number button content for each individual page.
+- `next` — scope: `Record<string, never>` — Replaces the default "next page" button content.
+- `previous` — scope: `Record<string, never>` — Replaces the default "previous page" button content.
+
+## See Also
+
+- [BbTable](./BbTable.md) — Displays tabular data, configurable columns and data mapper.