Character counter

<!--
	A soft-limit counter for the footer of a text field: a small ring that fills toward the limit
	beside the count in words. Near the limit both turn to the warning colour; past it the ring
	closes into an error mark and the text states the excess. It never truncates or blocks typing,
	and the field describes itself with the counter's id. Screen readers hear a debounced polite
	update only once the text is near the limit, never on every keystroke and never on load.
-->
<script lang="ts" module>
	export type CharacterCounterMode = 'remaining' | 'used';
	export type CharacterCounterCountBy = 'grapheme' | 'code-unit' | 'word';
	export type CharacterCounterAlignment = 'start' | 'end';
	export type CharacterCounterState = 'under' | 'near' | 'at' | 'over';

	export interface CharacterCounterMessages {
		/** Remaining mode: n units left, for example '38 characters remaining'. */
		remaining?: (n: number) => string;
		/** Used mode: count against the limit, for example '42 of 280 characters'. */
		used?: (count: number, limit: number) => string;
		/** Either mode, past the limit: n units too many, for example '3 characters too many'. */
		over?: (n: number) => string;
	}

	let segmenter: Intl.Segmenter | null | undefined;

	/**
	 * Counts text the way the counter does, so a submit handler or the server check can agree with
	 * it. Graphemes use Intl.Segmenter (a family emoji is one) and fall back to code points; words
	 * are runs of non-space characters, which is approximate for scripts written without spaces.
	 */
	export function countText(text: string, countBy: CharacterCounterCountBy = 'grapheme'): number {
		if (!text) return 0;
		if (countBy === 'code-unit') return text.length;
		if (countBy === 'word') return text.match(/\S+/g)?.length ?? 0;
		if (segmenter === undefined) {
			segmenter =
				typeof Intl !== 'undefined' && 'Segmenter' in Intl
					? new Intl.Segmenter(undefined, { granularity: 'grapheme' })
					: null;
		}
		return segmenter ? [...segmenter.segment(text)].length : [...text].length;
	}
</script>

<script lang="ts">
	interface Props {
		/** The text to count: the field's current value. */
		value: string;
		/** The configured maximum, in the unit countBy names. Rounded down; anything but a positive number reads as 0. */
		limit: number;
		/** Id of the counter text, for the field's aria-describedby. Defaults to one per instance. */
		id?: string;
		/** 'remaining' shows '38 characters remaining'; 'used' shows '42 of 280 characters'. */
		mode?: CharacterCounterMode;
		/** What one unit is: a grapheme (what a person sees as a character), a UTF-16 code unit, or a word. */
		countBy?: CharacterCounterCountBy;
		/** Warn and start announcing once this many units or fewer remain. */
		announceThreshold?: number;
		/** Message builders, for other languages or other wording. */
		messages?: CharacterCounterMessages;
		/** Which edge of the field's footer the counter sits on. */
		alignment?: CharacterCounterAlignment;
		/** Bindable, read-only: true while the text is over the limit, for blocking submit. */
		over?: boolean;
		/** Extra classes on the root, for placement. */
		class?: string;
	}

	let {
		value,
		limit,
		id,
		mode = 'remaining',
		countBy = 'grapheme',
		announceThreshold = 20,
		messages,
		alignment = 'end',
		over = $bindable(false),
		class: className
	}: Props = $props();

	const uid = $props.id();
	const countId = $derived(id ?? `${uid}-count`);

	const plural = (n: number) =>
		countBy === 'word' ? (n === 1 ? 'word' : 'words') : n === 1 ? 'character' : 'characters';
	const format = (n: number) => n.toLocaleString('en-US');

	/* NaN, Infinity, negatives and fractions would print nonsense, so the limit is a whole number. */
	const max = $derived(Number.isFinite(limit) && limit > 0 ? Math.floor(limit) : 0);
	const count = $derived(countText(value ?? '', countBy));
	const remaining = $derived(max - count);
	const status: CharacterCounterState = $derived(
		remaining < 0
			? 'over'
			: remaining === 0
				? 'at'
				: remaining <= announceThreshold
					? 'near'
					: 'under'
	);
	/* Ring progress out of 100; a limit of zero reads as full. */
	const progress = $derived(max > 0 ? Math.min(100, (count / max) * 100) : 100);

	const text = $derived.by(() => {
		if (remaining < 0)
			return messages?.over?.(-remaining) ?? `${format(-remaining)} ${plural(-remaining)} too many`;
		if (mode === 'used')
			return messages?.used?.(count, max) ?? `${format(count)} of ${format(max)} ${plural(max)}`;
		return (
			messages?.remaining?.(remaining) ?? `${format(remaining)} ${plural(remaining)} remaining`
		);
	});

	$effect.pre(() => {
		const isOver = remaining < 0;
		if (over !== isOver) over = isOver;
	});

	/*
	 * The visible text updates on every keystroke. The live region gets a copy only after typing has
	 * paused for a second and only within the threshold, as GOV.UK's character count does, and it
	 * stays empty on load so focusing the page does not read it. Only an edit to the value schedules
	 * one, and every edit restarts the pause, even one that leaves the count unchanged.
	 */
	let announcement = $state('');
	let lastValue: string | undefined;
	$effect(() => {
		const current = value ?? '';
		const message = text;
		const edited = lastValue !== undefined && current !== lastValue;
		lastValue = current;
		if (remaining > announceThreshold) {
			announcement = '';
			return;
		}
		if (!edited) return;
		const timer = setTimeout(() => (announcement = message), 1000);
		return () => clearTimeout(timer);
	});
</script>

<div
	class={[
		'character-counter flex min-w-0',
		alignment === 'end' ? 'justify-end' : 'justify-start',
		className
	]}
	data-state={status}
>
	<p
		id={countId}
		class={[
			'flex min-w-0 items-start gap-2 text-start text-[13px] leading-5 text-pretty break-words tabular-nums',
			status === 'under' && 'text-(--_muted)',
			(status === 'near' || status === 'at') && 'text-(--_warning)',
			status === 'over' && 'font-medium text-(--_danger)'
		]}
	>
		<!-- The ring repeats the text as a shape, so it is hidden; it closes into an error mark when over. -->
		<span class="grid h-lh shrink-0 place-items-center" aria-hidden="true">
			<!-- The ring starts at twelve o'clock and runs with the reading direction. -->
			<svg class="character-counter__ring size-4 rtl:-scale-x-100" viewBox="0 0 16 16" fill="none">
				<circle cx="8" cy="8" r="6.25" stroke="var(--_hairline)" stroke-width="1.75" />
				{#if progress > 0}
					<circle
						class={[
							'character-counter__progress origin-center -rotate-90',
							status === 'under' ? 'stroke-(--_accent)' : 'stroke-current'
						]}
						cx="8"
						cy="8"
						r="6.25"
						stroke-width="1.75"
						stroke-linecap={progress < 100 ? 'round' : undefined}
						pathLength="100"
						stroke-dasharray={progress < 100 ? `${progress} 100` : undefined}
					/>
				{/if}
				{#if status === 'over'}
					<path d="M8 4.75v3.5" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" />
					<circle cx="8" cy="11" r="1" fill="currentColor" />
				{/if}
			</svg>
		</span>
		<span class="min-w-0">{text}</span>
	</p>
	<span class="sr-only" aria-live="polite" aria-atomic="true">{announcement}</span>
</div>

<style>
	/* Public tokens: set --character-counter-* on the counter or any ancestor to retone it. */
	.character-counter {
		--_accent: var(--character-counter-accent, #1d4ed8);
		--_muted: var(--character-counter-muted, #52525b);
		/* A meter track rather than a boundary, so a step firmer than a hairline: an empty ring still reads. */
		--_hairline: var(--character-counter-hairline, rgb(0 0 0 / 0.16));
		/* amber-700 and red-700: 5.0:1 and 6.5:1 on white, so the text clears 4.5:1. */
		--_warning: var(--character-counter-warning, #b45309);
		--_danger: var(--character-counter-danger, #b91c1c);
	}

	/* Forced colours: two elements change, the track to GrayText and the arc to the text colour. */
	@media (forced-colors: active) {
		.character-counter__ring circle:first-child {
			stroke: GrayText;
		}
		.character-counter__progress {
			stroke: currentColor;
		}
	}
</style>

<!--
	A soft-limit counter for the footer of a text field: a small ring that fills toward the limit
	beside the count in words. Near the limit both turn to the warning colour; past it the ring
	closes into an error mark and the text states the excess. It never truncates or blocks typing,
	and the field describes itself with the counter's id. Screen readers hear a debounced polite
	update only once the text is near the limit, never on every keystroke and never on load.
-->
<script lang="ts" module>
	export type CharacterCounterMode = 'remaining' | 'used';
	export type CharacterCounterCountBy = 'grapheme' | 'code-unit' | 'word';
	export type CharacterCounterAlignment = 'start' | 'end';
	export type CharacterCounterState = 'under' | 'near' | 'at' | 'over';

	export interface CharacterCounterMessages {
		/** Remaining mode: n units left, for example '38 characters remaining'. */
		remaining?: (n: number) => string;
		/** Used mode: count against the limit, for example '42 of 280 characters'. */
		used?: (count: number, limit: number) => string;
		/** Either mode, past the limit: n units too many, for example '3 characters too many'. */
		over?: (n: number) => string;
	}

	let segmenter: Intl.Segmenter | null | undefined;

	/**
	 * Counts text the way the counter does, so a submit handler or the server check can agree with
	 * it. Graphemes use Intl.Segmenter (a family emoji is one) and fall back to code points; words
	 * are runs of non-space characters, which is approximate for scripts written without spaces.
	 */
	export function countText(text: string, countBy: CharacterCounterCountBy = 'grapheme'): number {
		if (!text) return 0;
		if (countBy === 'code-unit') return text.length;
		if (countBy === 'word') return text.match(/\S+/g)?.length ?? 0;
		if (segmenter === undefined) {
			segmenter =
				typeof Intl !== 'undefined' && 'Segmenter' in Intl
					? new Intl.Segmenter(undefined, { granularity: 'grapheme' })
					: null;
		}
		return segmenter ? [...segmenter.segment(text)].length : [...text].length;
	}
</script>

<script lang="ts">
	interface Props {
		/** The text to count: the field's current value. */
		value: string;
		/** The configured maximum, in the unit countBy names. Rounded down; anything but a positive number reads as 0. */
		limit: number;
		/** Id of the counter text, for the field's aria-describedby. Defaults to one per instance. */
		id?: string;
		/** 'remaining' shows '38 characters remaining'; 'used' shows '42 of 280 characters'. */
		mode?: CharacterCounterMode;
		/** What one unit is: a grapheme (what a person sees as a character), a UTF-16 code unit, or a word. */
		countBy?: CharacterCounterCountBy;
		/** Warn and start announcing once this many units or fewer remain. */
		announceThreshold?: number;
		/** Message builders, for other languages or other wording. */
		messages?: CharacterCounterMessages;
		/** Which edge of the field's footer the counter sits on. */
		alignment?: CharacterCounterAlignment;
		/** Bindable, read-only: true while the text is over the limit, for blocking submit. */
		over?: boolean;
		/** Extra classes on the root, for placement. */
		class?: string;
	}

	let {
		value,
		limit,
		id,
		mode = 'remaining',
		countBy = 'grapheme',
		announceThreshold = 20,
		messages,
		alignment = 'end',
		over = $bindable(false),
		class: className
	}: Props = $props();

	const uid = $props.id();
	const countId = $derived(id ?? `${uid}-count`);

	const plural = (n: number) =>
		countBy === 'word' ? (n === 1 ? 'word' : 'words') : n === 1 ? 'character' : 'characters';
	const format = (n: number) => n.toLocaleString('en-US');

	/* NaN, Infinity, negatives and fractions would print nonsense, so the limit is a whole number. */
	const max = $derived(Number.isFinite(limit) && limit > 0 ? Math.floor(limit) : 0);
	const count = $derived(countText(value ?? '', countBy));
	const remaining = $derived(max - count);
	const status: CharacterCounterState = $derived(
		remaining < 0
			? 'over'
			: remaining === 0
				? 'at'
				: remaining <= announceThreshold
					? 'near'
					: 'under'
	);
	/* Ring progress out of 100; a limit of zero reads as full. */
	const progress = $derived(max > 0 ? Math.min(100, (count / max) * 100) : 100);

	const text = $derived.by(() => {
		if (remaining < 0)
			return messages?.over?.(-remaining) ?? `${format(-remaining)} ${plural(-remaining)} too many`;
		if (mode === 'used')
			return messages?.used?.(count, max) ?? `${format(count)} of ${format(max)} ${plural(max)}`;
		return (
			messages?.remaining?.(remaining) ?? `${format(remaining)} ${plural(remaining)} remaining`
		);
	});

	$effect.pre(() => {
		const isOver = remaining < 0;
		if (over !== isOver) over = isOver;
	});

	/*
	 * The visible text updates on every keystroke. The live region gets a copy only after typing has
	 * paused for a second and only within the threshold, as GOV.UK's character count does, and it
	 * stays empty on load so focusing the page does not read it. Only an edit to the value schedules
	 * one, and every edit restarts the pause, even one that leaves the count unchanged.
	 */
	let announcement = $state('');
	let lastValue: string | undefined;
	$effect(() => {
		const current = value ?? '';
		const message = text;
		const edited = lastValue !== undefined && current !== lastValue;
		lastValue = current;
		if (remaining > announceThreshold) {
			announcement = '';
			return;
		}
		if (!edited) return;
		const timer = setTimeout(() => (announcement = message), 1000);
		return () => clearTimeout(timer);
	});
</script>

<div
	class={[
		'character-counter flex min-w-0',
		alignment === 'end' ? 'justify-end' : 'justify-start',
		className
	]}
	data-state={status}
>
	<p
		id={countId}
		class={[
			'flex min-w-0 items-start gap-2 text-start text-[13px] leading-5 text-pretty break-words tabular-nums',
			status === 'under' && 'text-(--_muted)',
			(status === 'near' || status === 'at') && 'text-(--_warning)',
			status === 'over' && 'font-medium text-(--_danger)'
		]}
	>
		<!-- The ring repeats the text as a shape, so it is hidden; it closes into an error mark when over. -->
		<span class="grid h-lh shrink-0 place-items-center" aria-hidden="true">
			<!-- The ring starts at twelve o'clock and runs with the reading direction. -->
			<svg class="character-counter__ring size-4 rtl:-scale-x-100" viewBox="0 0 16 16" fill="none">
				<circle cx="8" cy="8" r="6.25" stroke="var(--_hairline)" stroke-width="1.75" />
				{#if progress > 0}
					<circle
						class={[
							'character-counter__progress origin-center -rotate-90',
							status === 'under' ? 'stroke-(--_accent)' : 'stroke-current'
						]}
						cx="8"
						cy="8"
						r="6.25"
						stroke-width="1.75"
						stroke-linecap={progress < 100 ? 'round' : undefined}
						pathLength="100"
						stroke-dasharray={progress < 100 ? `${progress} 100` : undefined}
					/>
				{/if}
				{#if status === 'over'}
					<path d="M8 4.75v3.5" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" />
					<circle cx="8" cy="11" r="1" fill="currentColor" />
				{/if}
			</svg>
		</span>
		<span class="min-w-0">{text}</span>
	</p>
	<span class="sr-only" aria-live="polite" aria-atomic="true">{announcement}</span>
</div>

<style>
	/* Public tokens: set --character-counter-* on the counter or any ancestor to retone it. */
	.character-counter {
		--_accent: var(--character-counter-accent, #1d4ed8);
		--_muted: var(--character-counter-muted, #52525b);
		/* A meter track rather than a boundary, so a step firmer than a hairline: an empty ring still reads. */
		--_hairline: var(--character-counter-hairline, rgb(0 0 0 / 0.16));
		/* amber-700 and red-700: 5.0:1 and 6.5:1 on white, so the text clears 4.5:1. */
		--_warning: var(--character-counter-warning, #b45309);
		--_danger: var(--character-counter-danger, #b91c1c);
	}

	/* Forced colours: two elements change, the track to GrayText and the arc to the text colour. */
	@media (forced-colors: active) {
		.character-counter__ring circle:first-child {
			stroke: GrayText;
		}
		.character-counter__progress {
			stroke: currentColor;
		}
	}
</style>