Load more button

<!--
	A load-more control for the foot of a list. The list's closing hairline doubles as its progress
	track: one full-width rule whose filled share is how much of the list is showing, with the count
	and a single wide button centred beneath it. The consumer owns the list; onLoadMore appends the
	next page to it and reports what happened, and this control shows pending, failure and the end.
-->
<script lang="ts" module>
	export type LoadMoreResult =
		{ ok: true; added: number; hasMore: boolean } | { ok: false; message: string };
</script>

<script lang="ts">
	import { tick } from 'svelte';

	interface Props {
		/** Fetch the next page, append it to your own list, then report what happened. */
		onLoadMore: () => Promise<LoadMoreResult>;
		/** Whether more items exist. A result's hasMore takes over until this prop changes. */
		hasMore: boolean;
		/** Items currently in the list. Keep it in step as you append. */
		shown?: number;
		/** Total items, when the backend knows it. */
		total?: number;
		/** Button label at rest. */
		label?: string;
		/** Button label while onLoadMore is pending. */
		pendingLabel?: string;
		/** Button label after a failure; the next press retries. */
		retryLabel?: string;
		/** Replaces the button once nothing remains. */
		endLabel?: string;
		/** Shown when onLoadMore rejects or returns an empty message. */
		errorMessage?: string;
		/** Returns the first newly added item; focus moves there after a successful load. */
		focusTarget?: () => HTMLElement | null;
		/** Draw the closing rule as a progress track from shown and total. */
		showProgress?: boolean;
		/** Count text, for other wording or languages. Defaults to "Showing 12 of 48". */
		formatCount?: (shown: number, total?: number) => string;
		/** Announcement after a load. Defaults to "12 more items loaded". */
		formatLoaded?: (added: number) => string;
		/** Extra classes for placement (margins, max width). */
		class?: string;
	}

	let {
		onLoadMore,
		hasMore,
		shown,
		total,
		label = 'Load more',
		pendingLabel = 'Loading',
		retryLabel = 'Try again',
		endLabel = 'You have reached the end',
		errorMessage = 'Those items did not load. Check your connection and try again.',
		focusTarget,
		showProgress = false,
		formatCount,
		formatLoaded = (added: number) => `${added} more ${added === 1 ? 'item' : 'items'} loaded`,
		class: className
	}: Props = $props();

	const uid = $props.id();

	/* A result's hasMore overrides the prop until the consumer passes a new value. */
	let more = $derived(hasMore);
	let pending = $state(false);
	let failure = $state<string | null>(null);
	let announcement = $state('');

	let button = $state<HTMLButtonElement | null>(null);
	let end = $state<HTMLElement | null>(null);
	/** Set when the button held focus as it was replaced, so focus can land on the end line. */
	let focusEnd = $state(false);
	/** Cleared on destroy, so a request that settles later touches neither state nor focus. */
	let alive = true;

	/* A failure belongs to the button; once the list has ended it no longer applies. */
	const error = $derived(more ? failure : null);
	/* An empty list has nothing to count: "Showing 0" is noise, so the count needs one item. */
	const hasCount = $derived(shown !== undefined && shown > 0);
	const describedBy = $derived(
		[error && `${uid}-error`, hasCount && `${uid}-count`].filter(Boolean).join(' ') || undefined
	);
	const ratio = $derived(
		shown !== undefined && total !== undefined && total > 0
			? Math.min(1, Math.max(0, shown / total))
			: null
	);
	const progressVisible = $derived(showProgress && ratio !== null);

	async function announce(message: string) {
		// Clear first, so the same message twice in a row is still announced.
		announcement = '';
		await tick();
		if (alive) announcement = message;
	}

	async function load() {
		if (pending || !more) return;
		pending = true;
		failure = null;
		let result: LoadMoreResult;
		try {
			result = await onLoadMore();
		} catch {
			result = { ok: false, message: '' };
		}
		if (!alive) return;
		pending = false;

		if (!result.ok) {
			failure = result.message || errorMessage;
			announce(failure);
			return;
		}

		more = result.hasMore;
		const message = formatLoaded(result.added) + (result.hasMore ? '' : `. ${endLabel}`);
		await tick();
		if (!alive) return;
		announce(message);

		const target = result.added > 0 ? focusTarget?.() : null;
		if (target) {
			if (target.tabIndex < 0 && !target.hasAttribute('tabindex')) {
				target.setAttribute('tabindex', '-1');
			}
			target.focus();
		}
	}

	$effect(() => () => {
		alive = false;
	});

	/* However the list ends (a result or the prop), a focused button hands focus to the end line
	   instead of letting it fall to <body>. Pre-effects run before the button leaves the DOM. */
	$effect.pre(() => {
		if (!more && button && document.activeElement === button) focusEnd = true;
	});
	$effect(() => {
		if (focusEnd && end) {
			focusEnd = false;
			end.focus();
		}
	});
</script>

<div
	class={['load-more-button flex w-full flex-col items-center text-center', className]}
	style:--_progress={ratio ?? 0}
>
	{#if progressVisible}
		<!-- The closing rule: a hairline track with the shown share filled in the accent. The count
		     below says the same thing in words, so the bar itself stays out of the accessibility tree. -->
		<div class="relative mb-6 h-[3px] w-full" aria-hidden="true">
			<span class="absolute inset-x-0 top-px h-px bg-(--_hairline)"></span>
			<span class="load-more-button__fill absolute inset-0 bg-(--_accent)"></span>
		</div>
	{/if}

	{#if hasCount}
		<p id="{uid}-count" class="mb-3 text-sm leading-5 text-pretty text-(--_muted) tabular-nums">
			{#if formatCount}
				{formatCount(shown!, total)}
			{:else if total !== undefined}
				Showing <span class="font-medium text-(--_ink)">{shown}</span> of
				<span class="font-medium text-(--_ink)">{total}</span>
			{:else}
				Showing <span class="font-medium text-(--_ink)">{shown}</span>
			{/if}
		</p>
	{/if}

	<!-- The button and the end line share one cell. An invisible copy of the button's box stays
	     mounted in it, so the cell keeps the button's size (a wrapped label included) after the
	     button itself is gone, and ending the list moves nothing. -->
	<div class="grid w-full place-items-center sm:w-auto">
		<span
			class="invisible col-start-1 row-start-1 grid min-h-10 w-full place-items-center px-5 py-2 text-sm leading-5 font-medium sm:w-auto sm:min-w-44 pointer-coarse:min-h-11"
			aria-hidden="true"
		>
			{@render labels()}
		</span>
		{#if more}
			<button
				bind:this={button}
				type="button"
				class={[
					'col-start-1 row-start-1 grid min-h-10 w-full cursor-pointer place-items-center rounded-lg px-5 py-2 text-sm leading-5 font-medium select-none sm:w-auto sm:min-w-44 pointer-coarse:min-h-11',
					'bg-(--_surface) text-(--_ink) shadow-(--_edge) hover:bg-(--_surface-hover)',
					'transition-[background-color,scale] duration-150 ease-(--_ease) active:scale-[.98] active:duration-[80ms] motion-reduce:transition-[background-color] motion-reduce:active:scale-100',
					'outline-offset-2 outline-(--_accent) focus-visible:outline-2',
					'aria-busy:cursor-progress aria-busy:hover:bg-(--_surface) aria-busy:active:scale-100'
				]}
				aria-busy={pending ? 'true' : undefined}
				aria-disabled={pending ? 'true' : undefined}
				aria-describedby={describedBy}
				onclick={load}
			>
				{@render labels()}
			</button>
		{:else}
			<p
				bind:this={end}
				tabindex="-1"
				class="col-start-1 row-start-1 flex items-start gap-2 rounded-sm text-start text-sm leading-5 text-pretty text-(--_muted) outline-offset-2 outline-(--_accent) focus-visible:outline-2"
			>
				<!-- The check says "you have seen it all"; an empty list has seen nothing, so it goes. -->
				{#if shown !== 0}
					<span class="grid h-lh shrink-0 place-items-center" aria-hidden="true">
						<svg class="size-4" viewBox="0 0 16 16" fill="none">
							<path
								d="M3.25 8.5 6.5 11.5l6.25-7"
								stroke="currentColor"
								stroke-width="1.75"
								stroke-linecap="round"
								stroke-linejoin="round"
							/>
						</svg>
					</span>
				{/if}
				<span>{endLabel}</span>
			</p>
		{/if}
	</div>

	<!-- Failures sit below the button in a lane reserved for three lines on phones and two above sm:,
	     so neither the button nor
	     anything under the control moves when one appears or clears. -->
	<div
		class="mt-3 grid min-h-15 w-full place-items-start justify-center text-sm leading-5 sm:min-h-10"
	>
		{#if error}
			<p
				id="{uid}-error"
				class="flex max-w-md items-start gap-2 text-start text-balance break-words text-(--_error)"
			>
				<span class="grid h-lh shrink-0 place-items-center" aria-hidden="true">
					<svg class="size-4" viewBox="0 0 16 16" fill="none">
						<circle cx="8" cy="8" r="6.25" stroke="currentColor" stroke-width="1.75" />
						<path
							d="M8 4.75v3.5M8 10.75v.5"
							stroke="currentColor"
							stroke-width="1.75"
							stroke-linecap="round"
						/>
					</svg>
				</span>
				<span>{error}</span>
			</p>
		{/if}
	</div>

	<!-- One persistent polite region for every outcome; filled only after a press. -->
	<p class="sr-only" role="status" aria-live="polite">{announcement}</p>
</div>

{#snippet labels()}
	<!-- Every label sits in one cell, so the button is as wide as its longest state and never
	     changes width; the hidden ones are visibility: hidden, which also keeps them out of
	     the accessible name. -->
	<span class={['col-start-1 row-start-1', (pending || error) && 'invisible']}>{label}</span>
	<span class={['col-start-1 row-start-1 flex items-center gap-2', !pending && 'invisible']}>
		<svg
			class="size-4 shrink-0 animate-spin text-(--_muted) motion-reduce:animate-pulse"
			viewBox="0 0 16 16"
			fill="none"
			aria-hidden="true"
		>
			<circle
				cx="8"
				cy="8"
				r="6.25"
				stroke="currentColor"
				stroke-opacity="0.25"
				stroke-width="1.75"
			/>
			<path
				d="M14.25 8A6.25 6.25 0 0 0 8 1.75"
				stroke="currentColor"
				stroke-width="1.75"
				stroke-linecap="round"
			/>
		</svg>
		{pendingLabel}…
	</span>
	<span class={['col-start-1 row-start-1', (!error || pending) && 'invisible']}>{retryLabel}</span>
{/snippet}

<style>
	/* Public tokens: set --load-more-button-* on the control or any ancestor to retone it. */
	.load-more-button {
		--_accent: var(--load-more-button-accent, #1d4ed8);
		--_ink: var(--load-more-button-ink, #18181b);
		--_muted: var(--load-more-button-muted, #52525b);
		--_hairline: var(--load-more-button-hairline, rgb(0 0 0 / 0.1));
		--_surface: var(--load-more-button-surface, #ffffff);
		--_error: var(--load-more-button-error, #b91c1c);
		/* The button's own edge clears 3:1 on white and on its hover fill; the rule stays a hairline. */
		--_control-border: var(--load-more-button-control-border, #88888f);

		/* Formulas read by utilities: hover moves the fill one step toward the ink. */
		--_surface-hover: color-mix(in oklab, var(--_surface) 95%, var(--_ink));
		--_edge: inset 0 0 0 1px var(--_control-border), 0 1px 2px rgb(0 0 0 / 0.05);
		--_ease: cubic-bezier(0.2, 0, 0, 1);
	}

	/* The fill grows from the inline start. transform-origin has no logical keyword, so the
	   direction flip lives here with the transition and its reduced-motion override. */
	.load-more-button__fill {
		transform: scaleX(var(--_progress));
		transform-origin: left center;
		transition: transform 250ms cubic-bezier(0.16, 1, 0.3, 1);
	}
	.load-more-button__fill:dir(rtl) {
		transform-origin: right center;
	}
	@media (prefers-reduced-motion: reduce) {
		.load-more-button__fill {
			transition: none;
		}
	}
</style>

<!--
	A load-more control for the foot of a list. The list's closing hairline doubles as its progress
	track: one full-width rule whose filled share is how much of the list is showing, with the count
	and a single wide button centred beneath it. The consumer owns the list; onLoadMore appends the
	next page to it and reports what happened, and this control shows pending, failure and the end.
-->
<script lang="ts" module>
	export type LoadMoreResult =
		{ ok: true; added: number; hasMore: boolean } | { ok: false; message: string };
</script>

<script lang="ts">
	import { tick } from 'svelte';

	interface Props {
		/** Fetch the next page, append it to your own list, then report what happened. */
		onLoadMore: () => Promise<LoadMoreResult>;
		/** Whether more items exist. A result's hasMore takes over until this prop changes. */
		hasMore: boolean;
		/** Items currently in the list. Keep it in step as you append. */
		shown?: number;
		/** Total items, when the backend knows it. */
		total?: number;
		/** Button label at rest. */
		label?: string;
		/** Button label while onLoadMore is pending. */
		pendingLabel?: string;
		/** Button label after a failure; the next press retries. */
		retryLabel?: string;
		/** Replaces the button once nothing remains. */
		endLabel?: string;
		/** Shown when onLoadMore rejects or returns an empty message. */
		errorMessage?: string;
		/** Returns the first newly added item; focus moves there after a successful load. */
		focusTarget?: () => HTMLElement | null;
		/** Draw the closing rule as a progress track from shown and total. */
		showProgress?: boolean;
		/** Count text, for other wording or languages. Defaults to "Showing 12 of 48". */
		formatCount?: (shown: number, total?: number) => string;
		/** Announcement after a load. Defaults to "12 more items loaded". */
		formatLoaded?: (added: number) => string;
		/** Extra classes for placement (margins, max width). */
		class?: string;
	}

	let {
		onLoadMore,
		hasMore,
		shown,
		total,
		label = 'Load more',
		pendingLabel = 'Loading',
		retryLabel = 'Try again',
		endLabel = 'You have reached the end',
		errorMessage = 'Those items did not load. Check your connection and try again.',
		focusTarget,
		showProgress = false,
		formatCount,
		formatLoaded = (added: number) => `${added} more ${added === 1 ? 'item' : 'items'} loaded`,
		class: className
	}: Props = $props();

	const uid = $props.id();

	/* A result's hasMore overrides the prop until the consumer passes a new value. */
	let more = $derived(hasMore);
	let pending = $state(false);
	let failure = $state<string | null>(null);
	let announcement = $state('');

	let button = $state<HTMLButtonElement | null>(null);
	let end = $state<HTMLElement | null>(null);
	/** Set when the button held focus as it was replaced, so focus can land on the end line. */
	let focusEnd = $state(false);
	/** Cleared on destroy, so a request that settles later touches neither state nor focus. */
	let alive = true;

	/* A failure belongs to the button; once the list has ended it no longer applies. */
	const error = $derived(more ? failure : null);
	/* An empty list has nothing to count: "Showing 0" is noise, so the count needs one item. */
	const hasCount = $derived(shown !== undefined && shown > 0);
	const describedBy = $derived(
		[error && `${uid}-error`, hasCount && `${uid}-count`].filter(Boolean).join(' ') || undefined
	);
	const ratio = $derived(
		shown !== undefined && total !== undefined && total > 0
			? Math.min(1, Math.max(0, shown / total))
			: null
	);
	const progressVisible = $derived(showProgress && ratio !== null);

	async function announce(message: string) {
		// Clear first, so the same message twice in a row is still announced.
		announcement = '';
		await tick();
		if (alive) announcement = message;
	}

	async function load() {
		if (pending || !more) return;
		pending = true;
		failure = null;
		let result: LoadMoreResult;
		try {
			result = await onLoadMore();
		} catch {
			result = { ok: false, message: '' };
		}
		if (!alive) return;
		pending = false;

		if (!result.ok) {
			failure = result.message || errorMessage;
			announce(failure);
			return;
		}

		more = result.hasMore;
		const message = formatLoaded(result.added) + (result.hasMore ? '' : `. ${endLabel}`);
		await tick();
		if (!alive) return;
		announce(message);

		const target = result.added > 0 ? focusTarget?.() : null;
		if (target) {
			if (target.tabIndex < 0 && !target.hasAttribute('tabindex')) {
				target.setAttribute('tabindex', '-1');
			}
			target.focus();
		}
	}

	$effect(() => () => {
		alive = false;
	});

	/* However the list ends (a result or the prop), a focused button hands focus to the end line
	   instead of letting it fall to <body>. Pre-effects run before the button leaves the DOM. */
	$effect.pre(() => {
		if (!more && button && document.activeElement === button) focusEnd = true;
	});
	$effect(() => {
		if (focusEnd && end) {
			focusEnd = false;
			end.focus();
		}
	});
</script>

<div
	class={['load-more-button flex w-full flex-col items-center text-center', className]}
	style:--_progress={ratio ?? 0}
>
	{#if progressVisible}
		<!-- The closing rule: a hairline track with the shown share filled in the accent. The count
		     below says the same thing in words, so the bar itself stays out of the accessibility tree. -->
		<div class="relative mb-6 h-[3px] w-full" aria-hidden="true">
			<span class="absolute inset-x-0 top-px h-px bg-(--_hairline)"></span>
			<span class="load-more-button__fill absolute inset-0 bg-(--_accent)"></span>
		</div>
	{/if}

	{#if hasCount}
		<p id="{uid}-count" class="mb-3 text-sm leading-5 text-pretty text-(--_muted) tabular-nums">
			{#if formatCount}
				{formatCount(shown!, total)}
			{:else if total !== undefined}
				Showing <span class="font-medium text-(--_ink)">{shown}</span> of
				<span class="font-medium text-(--_ink)">{total}</span>
			{:else}
				Showing <span class="font-medium text-(--_ink)">{shown}</span>
			{/if}
		</p>
	{/if}

	<!-- The button and the end line share one cell. An invisible copy of the button's box stays
	     mounted in it, so the cell keeps the button's size (a wrapped label included) after the
	     button itself is gone, and ending the list moves nothing. -->
	<div class="grid w-full place-items-center sm:w-auto">
		<span
			class="invisible col-start-1 row-start-1 grid min-h-10 w-full place-items-center px-5 py-2 text-sm leading-5 font-medium sm:w-auto sm:min-w-44 pointer-coarse:min-h-11"
			aria-hidden="true"
		>
			{@render labels()}
		</span>
		{#if more}
			<button
				bind:this={button}
				type="button"
				class={[
					'col-start-1 row-start-1 grid min-h-10 w-full cursor-pointer place-items-center rounded-lg px-5 py-2 text-sm leading-5 font-medium select-none sm:w-auto sm:min-w-44 pointer-coarse:min-h-11',
					'bg-(--_surface) text-(--_ink) shadow-(--_edge) hover:bg-(--_surface-hover)',
					'transition-[background-color,scale] duration-150 ease-(--_ease) active:scale-[.98] active:duration-[80ms] motion-reduce:transition-[background-color] motion-reduce:active:scale-100',
					'outline-offset-2 outline-(--_accent) focus-visible:outline-2',
					'aria-busy:cursor-progress aria-busy:hover:bg-(--_surface) aria-busy:active:scale-100'
				]}
				aria-busy={pending ? 'true' : undefined}
				aria-disabled={pending ? 'true' : undefined}
				aria-describedby={describedBy}
				onclick={load}
			>
				{@render labels()}
			</button>
		{:else}
			<p
				bind:this={end}
				tabindex="-1"
				class="col-start-1 row-start-1 flex items-start gap-2 rounded-sm text-start text-sm leading-5 text-pretty text-(--_muted) outline-offset-2 outline-(--_accent) focus-visible:outline-2"
			>
				<!-- The check says "you have seen it all"; an empty list has seen nothing, so it goes. -->
				{#if shown !== 0}
					<span class="grid h-lh shrink-0 place-items-center" aria-hidden="true">
						<svg class="size-4" viewBox="0 0 16 16" fill="none">
							<path
								d="M3.25 8.5 6.5 11.5l6.25-7"
								stroke="currentColor"
								stroke-width="1.75"
								stroke-linecap="round"
								stroke-linejoin="round"
							/>
						</svg>
					</span>
				{/if}
				<span>{endLabel}</span>
			</p>
		{/if}
	</div>

	<!-- Failures sit below the button in a lane reserved for three lines on phones and two above sm:,
	     so neither the button nor
	     anything under the control moves when one appears or clears. -->
	<div
		class="mt-3 grid min-h-15 w-full place-items-start justify-center text-sm leading-5 sm:min-h-10"
	>
		{#if error}
			<p
				id="{uid}-error"
				class="flex max-w-md items-start gap-2 text-start text-balance break-words text-(--_error)"
			>
				<span class="grid h-lh shrink-0 place-items-center" aria-hidden="true">
					<svg class="size-4" viewBox="0 0 16 16" fill="none">
						<circle cx="8" cy="8" r="6.25" stroke="currentColor" stroke-width="1.75" />
						<path
							d="M8 4.75v3.5M8 10.75v.5"
							stroke="currentColor"
							stroke-width="1.75"
							stroke-linecap="round"
						/>
					</svg>
				</span>
				<span>{error}</span>
			</p>
		{/if}
	</div>

	<!-- One persistent polite region for every outcome; filled only after a press. -->
	<p class="sr-only" role="status" aria-live="polite">{announcement}</p>
</div>

{#snippet labels()}
	<!-- Every label sits in one cell, so the button is as wide as its longest state and never
	     changes width; the hidden ones are visibility: hidden, which also keeps them out of
	     the accessible name. -->
	<span class={['col-start-1 row-start-1', (pending || error) && 'invisible']}>{label}</span>
	<span class={['col-start-1 row-start-1 flex items-center gap-2', !pending && 'invisible']}>
		<svg
			class="size-4 shrink-0 animate-spin text-(--_muted) motion-reduce:animate-pulse"
			viewBox="0 0 16 16"
			fill="none"
			aria-hidden="true"
		>
			<circle
				cx="8"
				cy="8"
				r="6.25"
				stroke="currentColor"
				stroke-opacity="0.25"
				stroke-width="1.75"
			/>
			<path
				d="M14.25 8A6.25 6.25 0 0 0 8 1.75"
				stroke="currentColor"
				stroke-width="1.75"
				stroke-linecap="round"
			/>
		</svg>
		{pendingLabel}…
	</span>
	<span class={['col-start-1 row-start-1', (!error || pending) && 'invisible']}>{retryLabel}</span>
{/snippet}

<style>
	/* Public tokens: set --load-more-button-* on the control or any ancestor to retone it. */
	.load-more-button {
		--_accent: var(--load-more-button-accent, #1d4ed8);
		--_ink: var(--load-more-button-ink, #18181b);
		--_muted: var(--load-more-button-muted, #52525b);
		--_hairline: var(--load-more-button-hairline, rgb(0 0 0 / 0.1));
		--_surface: var(--load-more-button-surface, #ffffff);
		--_error: var(--load-more-button-error, #b91c1c);
		/* The button's own edge clears 3:1 on white and on its hover fill; the rule stays a hairline. */
		--_control-border: var(--load-more-button-control-border, #88888f);

		/* Formulas read by utilities: hover moves the fill one step toward the ink. */
		--_surface-hover: color-mix(in oklab, var(--_surface) 95%, var(--_ink));
		--_edge: inset 0 0 0 1px var(--_control-border), 0 1px 2px rgb(0 0 0 / 0.05);
		--_ease: cubic-bezier(0.2, 0, 0, 1);
	}

	/* The fill grows from the inline start. transform-origin has no logical keyword, so the
	   direction flip lives here with the transition and its reduced-motion override. */
	.load-more-button__fill {
		transform: scaleX(var(--_progress));
		transform-origin: left center;
		transition: transform 250ms cubic-bezier(0.16, 1, 0.3, 1);
	}
	.load-more-button__fill:dir(rtl) {
		transform-origin: right center;
	}
	@media (prefers-reduced-motion: reduce) {
		.load-more-button__fill {
			transition: none;
		}
	}
</style>