Radio group

<!--
	A radio group for exactly one choice: a fieldset and legend, an optional help line, one row per
	option and a consumer-supplied group error. Every option is a native <input type="radio"> sharing
	one name, so arrow keys, the single tab stop and required validation come from the browser and the
	group submits with its form before any script runs.

	Each row is typeset on two edges: the radio sits in a mark column level with the label's first
	line, the label and its description hang from one text edge, and an optional note (a price, a
	date) sits at the row's end in tabular numerals, so options compare like lines of a price list.
-->
<script lang="ts" module>
	export interface RadioGroupOption {
		/** Submitted value; unique within the group. */
		value: string;
		/** Visible label and the radio's accessible name. */
		label: string;
		/** One short line under the label, linked to the radio with aria-describedby. */
		description?: string;
		/** A short note at the end of the label's line, such as a price or a date. */
		meta?: string;
		/** Unavailable: shown faded, skipped by arrow keys, never submitted. */
		disabled?: boolean;
	}
	export type RadioGroupOrientation = 'vertical' | 'horizontal';
	export type RadioGroupRequiredIndicator = 'required' | 'optional' | 'none';
</script>

<script lang="ts">
	interface Props {
		/** The question or group label. Always visible. */
		legend: string;
		/** The choices, in order. */
		options: RadioGroupOption[];
		/** Shared input name, so native submission includes the choice. */
		name: string;
		/** Bindable selected value. Undefined leaves every option unselected. */
		value?: string;
		/** Native required on every radio: an empty group blocks submission. */
		required?: boolean;
		/** Which marker follows the legend. Defaults to 'required' for required groups, otherwise 'none'. */
		requiredIndicator?: RadioGroupRequiredIndicator;
		/** Marker text for required groups, for other languages. */
		requiredLabel?: string;
		/** Marker text for optional groups, for other languages. */
		optionalLabel?: string;
		/** 'horizontal' sets the options in a wrapping row once the group is 24rem wide. */
		orientation?: RadioGroupOrientation;
		/** Help text under the legend, linked to the fieldset with aria-describedby. */
		description?: string;
		/** Validation message from the consumer. Sets aria-invalid; the component never validates. */
		error?: string | null;
		/** Read before the error by screen readers only, for other languages. */
		errorPrefix?: string;
		/**
		 * Hold space under the options for the error, so setting it moves nothing below: true holds one
		 * line, a number holds that many. Defaults to required.
		 */
		reserveError?: boolean | number;
		/** Disable the whole group through the fieldset. */
		disabled?: boolean;
		/** Called with the new value when the person picks an option. */
		onValueChange?: (value: string) => void;
		/** Extra classes on the outer wrapper, for placement. */
		class?: string;
	}

	let {
		legend,
		options,
		name,
		value = $bindable(),
		required = false,
		requiredIndicator,
		requiredLabel = 'Required',
		optionalLabel = 'Optional',
		orientation = 'vertical',
		description,
		error = null,
		errorPrefix = 'Error:',
		reserveError,
		disabled = false,
		onValueChange,
		class: className
	}: Props = $props();

	const uid = $props.id();
	const helpId = `${uid}-help`;
	const errorId = `${uid}-error`;

	const invalid = $derived(!!error);
	const marker = $derived(requiredIndicator ?? (required ? 'required' : 'none'));
	/* A required group is the one that gets "choose one" errors, so it holds the line by default. */
	const reserveLines = $derived(
		typeof reserveError === 'number'
			? Math.max(0, reserveError)
			: (reserveError ?? required)
				? 1
				: 0
	);

	/* Each radio is described by its own description and note, then the group error. */
	function describedBy(option: RadioGroupOption, i: number) {
		const ids = [
			option.description && `${uid}-${i}-description`,
			option.meta && `${uid}-${i}-meta`,
			invalid && errorId
		].filter(Boolean);
		return ids.length ? ids.join(' ') : undefined;
	}
</script>

<div
	class={['radio-group @container min-w-0', className]}
	data-orientation={orientation}
	data-invalid={invalid ? '' : undefined}
	style:--_error-lines={reserveLines || undefined}
>
	<fieldset
		class="m-0 min-w-0 border-0 p-0"
		aria-describedby={description ? helpId : undefined}
		{disabled}
	>
		<legend class="p-0 text-sm leading-5 font-medium text-pretty break-words text-(--_ink)">
			{legend}{#if marker === 'required'}
				<!-- The native required attribute already says so to assistive technology. The en space
				     is a break point, so a marker that wraps starts on the legend's edge. -->
				<span class="text-[13px] font-normal text-(--_muted)" aria-hidden="true"
					>&ensp;{requiredLabel}</span
				>{:else if marker === 'optional'}
				<span class="text-[13px] font-normal text-(--_muted)">&ensp;{optionalLabel}</span>{/if}
		</legend>
		{#if description}
			<p id={helpId} class="mt-1 text-[13px] leading-5 text-pretty break-words text-(--_muted)">
				{description}
			</p>
		{/if}

		<div
			class={[
				'mt-1 flex flex-col',
				orientation === 'horizontal' && '@sm:flex-row @sm:flex-wrap @sm:gap-x-6'
			]}
		>
			{#each options as option, i (option.value)}
				{@const inputId = `${uid}-${i}`}
				<!-- The label's overlay makes the whole row the click target while only the label text
				     names the radio; the description and note describe it. -->
				<div
					class={[
						'radio-group__option group/option relative grid min-w-0 grid-cols-[auto_minmax(0,1fr)_auto] content-center gap-x-3 py-2',
						'text-sm leading-5 pointer-coarse:min-h-11 pointer-coarse:text-base pointer-coarse:leading-6'
					]}
				>
					<!-- An unavailable option fades its mark, label and note; its description keeps full
					     strength, because it is where the reason lives. -->
					<span class="grid h-lh place-items-center group-has-disabled/option:opacity-50">
						<span class="grid place-items-center">
							<!-- ARIA lists aria-invalid on radiogroup rather than radio, but browsers expose it
							     on a native radio and screen readers announce it on each one as focus arrives,
							     which is where the person is when they need to hear it. -->
							<!-- svelte-ignore a11y_role_supports_aria_props_implicit -->
							<input
								type="radio"
								id={inputId}
								{name}
								value={option.value}
								bind:group={value}
								disabled={option.disabled}
								{required}
								aria-describedby={describedBy(option, i)}
								aria-invalid={invalid ? 'true' : undefined}
								onchange={() => onValueChange?.(option.value)}
								class={[
									'peer col-start-1 row-start-1 m-0 size-4 cursor-pointer appearance-none rounded-full border pointer-coarse:size-5',
									'border-(--_edge) bg-(--_surface) checked:border-(--_accent) checked:bg-(--_accent)',
									'enabled:not-checked:group-hover/option:border-(--_edge-hover) enabled:not-checked:group-active/option:border-(--_accent) disabled:cursor-not-allowed',
									'focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-(--_ring)',
									'transition-[border-color,background-color] duration-150 ease-(--_ease) motion-reduce:transition-none',
									'forced-colors:appearance-auto'
								]}
							/>
							<span
								class={[
									'pointer-events-none col-start-1 row-start-1 size-1.5 scale-0 rounded-full bg-(--_on-accent) pointer-coarse:size-2',
									'transition-transform duration-150 ease-(--_ease) peer-checked:scale-100 motion-reduce:transition-none',
									'forced-colors:hidden'
								]}
								aria-hidden="true"
							></span>
						</span>
					</span>
					<label
						for={inputId}
						class="min-w-0 cursor-pointer text-pretty break-words text-(--_ink) group-has-disabled/option:cursor-not-allowed group-has-disabled/option:opacity-50 after:absolute after:inset-0"
					>
						{option.label}
					</label>
					{#if option.meta}
						<span
							id="{uid}-{i}-meta"
							class="text-end whitespace-nowrap text-(--_ink) tabular-nums group-has-disabled/option:opacity-50"
						>
							{option.meta}
						</span>
					{/if}
					{#if option.description}
						<span
							id="{uid}-{i}-description"
							class="col-start-2 col-end-4 text-[13px] leading-5 text-pretty break-words text-(--_muted)"
						>
							{option.description}
						</span>
					{/if}
				</div>
			{/each}
		</div>

		{#if invalid}
			<p
				id={errorId}
				class="mt-1 flex min-h-(--_error-h) items-start gap-1 text-[13px] leading-5 text-(--_danger)"
			>
				<span class="grid h-lh shrink-0 place-items-center" aria-hidden="true">
					<svg class="size-3.5" 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.5"
							stroke="currentColor"
							stroke-width="1.75"
							stroke-linecap="round"
						/>
						<circle cx="8" cy="11" r="1" fill="currentColor" />
					</svg>
				</span>
				<span class="min-w-0 text-pretty break-words"
					><span class="sr-only">{`${errorPrefix} `}</span>{error}</span
				>
			</p>
		{:else if reserveLines}
			<div class="mt-1 h-(--_error-h)" aria-hidden="true"></div>
		{/if}
	</fieldset>
</div>

<style>
	/* Public tokens: set --radio-group-* on the group or any ancestor to retone it. */
	.radio-group {
		--_accent: var(--radio-group-accent, #1d4ed8);
		--_on-accent: var(--radio-group-on-accent, #ffffff);
		--_danger: var(--radio-group-danger, #b91c1c);
		--_ink: var(--radio-group-ink, #18181b);
		--_muted: var(--radio-group-muted, #52525b);
		/* 3:1 against white: the ring is the only thing marking an unselected radio (WCAG 1.4.11). */
		--_hairline: var(--radio-group-hairline, rgb(0 0 0 / 0.44));
		--_surface: var(--radio-group-surface, #ffffff);

		--_ease: cubic-bezier(0.2, 0, 0, 1);
		/* The reserved error block: reserveError's line count at the message's 20 px leading. */
		--_error-h: calc(var(--_error-lines, 0) * 1.25rem);
		--_edge: var(--_hairline);
		--_ring: var(--_accent);
		/* Hover darkens whichever edge is showing, so an invalid radio stays red under the pointer. */
		--_edge-hover: color-mix(in oklab, var(--_edge), var(--_ink) 50%);
	}

	/* Invalid: unselected radios and the focus ring carry the error colour. */
	.radio-group[data-invalid] {
		--_edge: var(--_danger);
		--_ring: var(--_danger);
	}
</style>

<!--
	A radio group for exactly one choice: a fieldset and legend, an optional help line, one row per
	option and a consumer-supplied group error. Every option is a native <input type="radio"> sharing
	one name, so arrow keys, the single tab stop and required validation come from the browser and the
	group submits with its form before any script runs.

	Each row is typeset on two edges: the radio sits in a mark column level with the label's first
	line, the label and its description hang from one text edge, and an optional note (a price, a
	date) sits at the row's end in tabular numerals, so options compare like lines of a price list.
-->
<script lang="ts" module>
	export interface RadioGroupOption {
		/** Submitted value; unique within the group. */
		value: string;
		/** Visible label and the radio's accessible name. */
		label: string;
		/** One short line under the label, linked to the radio with aria-describedby. */
		description?: string;
		/** A short note at the end of the label's line, such as a price or a date. */
		meta?: string;
		/** Unavailable: shown faded, skipped by arrow keys, never submitted. */
		disabled?: boolean;
	}
	export type RadioGroupOrientation = 'vertical' | 'horizontal';
	export type RadioGroupRequiredIndicator = 'required' | 'optional' | 'none';
</script>

<script lang="ts">
	interface Props {
		/** The question or group label. Always visible. */
		legend: string;
		/** The choices, in order. */
		options: RadioGroupOption[];
		/** Shared input name, so native submission includes the choice. */
		name: string;
		/** Bindable selected value. Undefined leaves every option unselected. */
		value?: string;
		/** Native required on every radio: an empty group blocks submission. */
		required?: boolean;
		/** Which marker follows the legend. Defaults to 'required' for required groups, otherwise 'none'. */
		requiredIndicator?: RadioGroupRequiredIndicator;
		/** Marker text for required groups, for other languages. */
		requiredLabel?: string;
		/** Marker text for optional groups, for other languages. */
		optionalLabel?: string;
		/** 'horizontal' sets the options in a wrapping row once the group is 24rem wide. */
		orientation?: RadioGroupOrientation;
		/** Help text under the legend, linked to the fieldset with aria-describedby. */
		description?: string;
		/** Validation message from the consumer. Sets aria-invalid; the component never validates. */
		error?: string | null;
		/** Read before the error by screen readers only, for other languages. */
		errorPrefix?: string;
		/**
		 * Hold space under the options for the error, so setting it moves nothing below: true holds one
		 * line, a number holds that many. Defaults to required.
		 */
		reserveError?: boolean | number;
		/** Disable the whole group through the fieldset. */
		disabled?: boolean;
		/** Called with the new value when the person picks an option. */
		onValueChange?: (value: string) => void;
		/** Extra classes on the outer wrapper, for placement. */
		class?: string;
	}

	let {
		legend,
		options,
		name,
		value = $bindable(),
		required = false,
		requiredIndicator,
		requiredLabel = 'Required',
		optionalLabel = 'Optional',
		orientation = 'vertical',
		description,
		error = null,
		errorPrefix = 'Error:',
		reserveError,
		disabled = false,
		onValueChange,
		class: className
	}: Props = $props();

	const uid = $props.id();
	const helpId = `${uid}-help`;
	const errorId = `${uid}-error`;

	const invalid = $derived(!!error);
	const marker = $derived(requiredIndicator ?? (required ? 'required' : 'none'));
	/* A required group is the one that gets "choose one" errors, so it holds the line by default. */
	const reserveLines = $derived(
		typeof reserveError === 'number'
			? Math.max(0, reserveError)
			: (reserveError ?? required)
				? 1
				: 0
	);

	/* Each radio is described by its own description and note, then the group error. */
	function describedBy(option: RadioGroupOption, i: number) {
		const ids = [
			option.description && `${uid}-${i}-description`,
			option.meta && `${uid}-${i}-meta`,
			invalid && errorId
		].filter(Boolean);
		return ids.length ? ids.join(' ') : undefined;
	}
</script>

<div
	class={['radio-group @container min-w-0', className]}
	data-orientation={orientation}
	data-invalid={invalid ? '' : undefined}
	style:--_error-lines={reserveLines || undefined}
>
	<fieldset
		class="m-0 min-w-0 border-0 p-0"
		aria-describedby={description ? helpId : undefined}
		{disabled}
	>
		<legend class="p-0 text-sm leading-5 font-medium text-pretty break-words text-(--_ink)">
			{legend}{#if marker === 'required'}
				<!-- The native required attribute already says so to assistive technology. The en space
				     is a break point, so a marker that wraps starts on the legend's edge. -->
				<span class="text-[13px] font-normal text-(--_muted)" aria-hidden="true"
					>&ensp;{requiredLabel}</span
				>{:else if marker === 'optional'}
				<span class="text-[13px] font-normal text-(--_muted)">&ensp;{optionalLabel}</span>{/if}
		</legend>
		{#if description}
			<p id={helpId} class="mt-1 text-[13px] leading-5 text-pretty break-words text-(--_muted)">
				{description}
			</p>
		{/if}

		<div
			class={[
				'mt-1 flex flex-col',
				orientation === 'horizontal' && '@sm:flex-row @sm:flex-wrap @sm:gap-x-6'
			]}
		>
			{#each options as option, i (option.value)}
				{@const inputId = `${uid}-${i}`}
				<!-- The label's overlay makes the whole row the click target while only the label text
				     names the radio; the description and note describe it. -->
				<div
					class={[
						'radio-group__option group/option relative grid min-w-0 grid-cols-[auto_minmax(0,1fr)_auto] content-center gap-x-3 py-2',
						'text-sm leading-5 pointer-coarse:min-h-11 pointer-coarse:text-base pointer-coarse:leading-6'
					]}
				>
					<!-- An unavailable option fades its mark, label and note; its description keeps full
					     strength, because it is where the reason lives. -->
					<span class="grid h-lh place-items-center group-has-disabled/option:opacity-50">
						<span class="grid place-items-center">
							<!-- ARIA lists aria-invalid on radiogroup rather than radio, but browsers expose it
							     on a native radio and screen readers announce it on each one as focus arrives,
							     which is where the person is when they need to hear it. -->
							<!-- svelte-ignore a11y_role_supports_aria_props_implicit -->
							<input
								type="radio"
								id={inputId}
								{name}
								value={option.value}
								bind:group={value}
								disabled={option.disabled}
								{required}
								aria-describedby={describedBy(option, i)}
								aria-invalid={invalid ? 'true' : undefined}
								onchange={() => onValueChange?.(option.value)}
								class={[
									'peer col-start-1 row-start-1 m-0 size-4 cursor-pointer appearance-none rounded-full border pointer-coarse:size-5',
									'border-(--_edge) bg-(--_surface) checked:border-(--_accent) checked:bg-(--_accent)',
									'enabled:not-checked:group-hover/option:border-(--_edge-hover) enabled:not-checked:group-active/option:border-(--_accent) disabled:cursor-not-allowed',
									'focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-(--_ring)',
									'transition-[border-color,background-color] duration-150 ease-(--_ease) motion-reduce:transition-none',
									'forced-colors:appearance-auto'
								]}
							/>
							<span
								class={[
									'pointer-events-none col-start-1 row-start-1 size-1.5 scale-0 rounded-full bg-(--_on-accent) pointer-coarse:size-2',
									'transition-transform duration-150 ease-(--_ease) peer-checked:scale-100 motion-reduce:transition-none',
									'forced-colors:hidden'
								]}
								aria-hidden="true"
							></span>
						</span>
					</span>
					<label
						for={inputId}
						class="min-w-0 cursor-pointer text-pretty break-words text-(--_ink) group-has-disabled/option:cursor-not-allowed group-has-disabled/option:opacity-50 after:absolute after:inset-0"
					>
						{option.label}
					</label>
					{#if option.meta}
						<span
							id="{uid}-{i}-meta"
							class="text-end whitespace-nowrap text-(--_ink) tabular-nums group-has-disabled/option:opacity-50"
						>
							{option.meta}
						</span>
					{/if}
					{#if option.description}
						<span
							id="{uid}-{i}-description"
							class="col-start-2 col-end-4 text-[13px] leading-5 text-pretty break-words text-(--_muted)"
						>
							{option.description}
						</span>
					{/if}
				</div>
			{/each}
		</div>

		{#if invalid}
			<p
				id={errorId}
				class="mt-1 flex min-h-(--_error-h) items-start gap-1 text-[13px] leading-5 text-(--_danger)"
			>
				<span class="grid h-lh shrink-0 place-items-center" aria-hidden="true">
					<svg class="size-3.5" 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.5"
							stroke="currentColor"
							stroke-width="1.75"
							stroke-linecap="round"
						/>
						<circle cx="8" cy="11" r="1" fill="currentColor" />
					</svg>
				</span>
				<span class="min-w-0 text-pretty break-words"
					><span class="sr-only">{`${errorPrefix} `}</span>{error}</span
				>
			</p>
		{:else if reserveLines}
			<div class="mt-1 h-(--_error-h)" aria-hidden="true"></div>
		{/if}
	</fieldset>
</div>

<style>
	/* Public tokens: set --radio-group-* on the group or any ancestor to retone it. */
	.radio-group {
		--_accent: var(--radio-group-accent, #1d4ed8);
		--_on-accent: var(--radio-group-on-accent, #ffffff);
		--_danger: var(--radio-group-danger, #b91c1c);
		--_ink: var(--radio-group-ink, #18181b);
		--_muted: var(--radio-group-muted, #52525b);
		/* 3:1 against white: the ring is the only thing marking an unselected radio (WCAG 1.4.11). */
		--_hairline: var(--radio-group-hairline, rgb(0 0 0 / 0.44));
		--_surface: var(--radio-group-surface, #ffffff);

		--_ease: cubic-bezier(0.2, 0, 0, 1);
		/* The reserved error block: reserveError's line count at the message's 20 px leading. */
		--_error-h: calc(var(--_error-lines, 0) * 1.25rem);
		--_edge: var(--_hairline);
		--_ring: var(--_accent);
		/* Hover darkens whichever edge is showing, so an invalid radio stays red under the pointer. */
		--_edge-hover: color-mix(in oklab, var(--_edge), var(--_ink) 50%);
	}

	/* Invalid: unselected radios and the focus ring carry the error colour. */
	.radio-group[data-invalid] {
		--_edge: var(--_danger);
		--_ring: var(--_danger);
	}
</style>