Copy button

<!--
	Copies a supplied string and confirms it where the click happened. With showValue the value sits
	in a read-only mono field joined to the button as one control; without it the button stands
	alone, labelled or as an icon. The button's width is reserved for the longer of its two labels,
	the result is announced through a status region that is always in the tree, and a failed copy
	selects the value and floats a manual-copy note under the control without moving anything.
-->
<script lang="ts" module>
	export type CopyResult = { ok: boolean };
	export type CopyState = 'idle' | 'copied' | 'failed';
</script>

<script lang="ts">
	interface Props {
		/** The exact text written to the clipboard. An empty string disables the button. */
		value: string;
		/** The button's label and its name at rest. Icon-only buttons keep it as the name in every state, so name the object: "Copy install command". */
		label?: string;
		/** Shown in place of the label, and announced, after a successful copy. */
		copiedLabel?: string;
		/** Shown under the control and announced when copying fails. */
		errorLabel?: string;
		/** Show the value in a read-only field joined to the button. */
		showValue?: boolean;
		/** The field's accessible name, and the group's, when showValue is set. */
		valueLabel?: string;
		/** Shown in the field while value is empty. */
		placeholder?: string;
		/** Milliseconds before a successful copy returns to idle. Infinity keeps it until the next click. */
		resetAfter?: number;
		/** A square icon button; label becomes its aria-label. */
		iconOnly?: boolean;
		/** Called after every attempt, successful or not. */
		onCopy?: (result: CopyResult) => void;
		/** Replaces navigator.clipboard.writeText, for a native shell's clipboard or a test. */
		writeText?: (text: string) => Promise<void>;
		/** Extra classes on the root, for width and placement. */
		class?: string;
	}

	let {
		value,
		label = 'Copy',
		copiedLabel = 'Copied',
		errorLabel = 'Copy failed. Select the text and copy it manually.',
		showValue = false,
		valueLabel = 'Value to copy',
		placeholder,
		resetAfter = 2000,
		iconOnly = false,
		onCopy,
		writeText,
		class: className
	}: Props = $props();

	const uid = $props.id();

	let copyState = $state<CopyState>('idle');
	let announcement = $state('');
	let root = $state<HTMLElement>();
	let field = $state<HTMLInputElement>();

	let timer: ReturnType<typeof setTimeout> | undefined;
	let attempt = 0;
	let flip = false;
	let destroyed = false;

	const empty = $derived(!value);

	function clearTimer() {
		if (timer === undefined) return;
		clearTimeout(timer);
		timer = undefined;
	}

	/*
	 * A polite region only speaks when its text changes, so a repeat alternates a trailing no-break
	 * space. The last result stays in the region after the visual reset, so a reader that delivers
	 * it late still has something to read.
	 */
	const NBSP = String.fromCharCode(160);
	function announce(text: string) {
		flip = !flip;
		announcement = flip ? text : text + NBSP;
	}

	function reset() {
		clearTimer();
		copyState = 'idle';
	}

	/* Dismissing also invalidates a write still in flight, so its result cannot reopen the note. */
	function dismiss() {
		attempt++;
		reset();
	}

	function succeed() {
		clearTimer();
		copyState = 'copied';
		announce(copiedLabel);
		if (Number.isFinite(resetAfter)) timer = setTimeout(reset, Math.max(0, resetAfter));
	}

	function fail() {
		copyState = 'failed';
		announce(errorLabel);
		/*
		 * Hand the value to the keyboard, focused and selected for Ctrl+C, unless focus has already
		 * moved somewhere else on the page.
		 */
		const active = document.activeElement;
		if (field && (!active || active === document.body || root?.contains(active))) {
			field.focus();
			field.select();
			/* select() scrolls to the end; show the start, where a command says what it is. */
			field.scrollLeft = 0;
		}
	}

	function clipboardWrite(text: string): Promise<void> {
		const clipboard = typeof navigator === 'undefined' ? undefined : navigator.clipboard;
		if (!clipboard?.writeText) return Promise.reject(new Error('Clipboard API unavailable'));
		return clipboard.writeText(text);
	}

	async function copy() {
		if (empty) return;
		const current = ++attempt;
		/* A retry closes the last result at once instead of leaving it up while the write runs. */
		reset();
		const ok = await (writeText ?? clipboardWrite)(value).then(
			() => true,
			() => false
		);
		if (destroyed) return;
		/* Only the latest attempt drives the state; every attempt reports to onCopy. */
		if (current === attempt) {
			if (ok) succeed();
			else fail();
		}
		onCopy?.({ ok });
	}

	/*
	 * The failure note stays until the next attempt, Escape, or focus or a click moving elsewhere.
	 * Escape is heard on the document: Safari does not focus a button on click, so focus may never
	 * have entered the control.
	 */
	$effect(() => {
		const el = root;
		if (!el || copyState !== 'failed') return;
		const keydown = (event: KeyboardEvent) => {
			if (event.key === 'Escape') dismiss();
		};
		const focusout = (event: FocusEvent) => {
			if (!el.contains(event.relatedTarget as Node | null)) dismiss();
		};
		const pointerdown = (event: PointerEvent) => {
			if (!el.contains(event.target as Node | null)) dismiss();
		};
		document.addEventListener('keydown', keydown);
		el.addEventListener('focusout', focusout);
		document.addEventListener('pointerdown', pointerdown);
		return () => {
			document.removeEventListener('keydown', keydown);
			el.removeEventListener('focusout', focusout);
			document.removeEventListener('pointerdown', pointerdown);
		};
	});

	$effect(() => () => {
		destroyed = true;
		clearTimer();
	});
</script>

{#snippet face(compact: boolean)}
	<!-- Both marks share one cell and crossfade, so the swap never moves the label. -->
	<span class="grid size-4 shrink-0 place-items-center" aria-hidden="true">
		<svg
			viewBox="0 0 16 16"
			fill="none"
			class={[
				'size-4 transition-[opacity,scale] duration-150 ease-(--_ease) [grid-area:1/1] motion-reduce:scale-100 motion-reduce:transition-opacity',
				copyState === 'copied'
					? 'scale-75 opacity-0'
					: 'text-(--_muted) group-hover:text-(--_ink) group-disabled:text-(--_muted)'
			]}
		>
			<rect
				x="5.75"
				y="5.75"
				width="7.5"
				height="7.5"
				rx="1.5"
				stroke="currentColor"
				stroke-width="1.5"
			/>
			<path
				d="M10.25 3.5v-.25a1.5 1.5 0 0 0-1.5-1.5h-5a1.5 1.5 0 0 0-1.5 1.5v5a1.5 1.5 0 0 0 1.5 1.5h.25"
				stroke="currentColor"
				stroke-width="1.5"
				stroke-linecap="round"
			/>
		</svg>
		<svg
			viewBox="0 0 16 16"
			fill="none"
			class={[
				'size-4 text-(--_success) transition-[opacity,scale] duration-150 ease-(--_ease) [grid-area:1/1] motion-reduce:scale-100 motion-reduce:transition-opacity',
				copyState === 'copied' ? 'opacity-100' : 'scale-75 opacity-0'
			]}
		>
			<path
				d="M3.25 8.5 6.5 11.75l6.25-7.5"
				stroke="currentColor"
				stroke-width="1.75"
				stroke-linecap="round"
				stroke-linejoin="round"
			/>
		</svg>
	</span>
	{#if !iconOnly}
		<!--
			Both labels share one cell, centred, so the button is as wide as the longer one in every state
			and neither sits off to one side. The visible one is the button's name (label in name); the
			other is hidden from the tree. In a narrow joined row the labels go visually hidden, still
			naming the button, so the value keeps the width it needs to say what it is.
		-->
		<span class={['grid justify-items-center', compact && '@max-sm:sr-only']}>
			<span
				class={[
					'transition-opacity duration-150 ease-(--_ease) [grid-area:1/1]',
					copyState === 'copied' && 'opacity-0'
				]}
				aria-hidden={copyState === 'copied' ? 'true' : undefined}>{label}</span
			>
			<span
				class={[
					'transition-opacity duration-150 ease-(--_ease) [grid-area:1/1]',
					copyState !== 'copied' && 'opacity-0'
				]}
				aria-hidden={copyState !== 'copied' ? 'true' : undefined}>{copiedLabel}</span
			>
		</span>
	{/if}
{/snippet}

<div
	bind:this={root}
	class={[
		'copy-button relative',
		showValue ? '@container flex w-full min-w-0' : 'inline-flex align-middle',
		className
	]}
	role={showValue ? 'group' : undefined}
	aria-label={showValue ? valueLabel : undefined}
	data-state={copyState}
>
	{#if showValue}
		<div
			class="flex h-9 min-w-0 flex-1 rounded-lg bg-(--_fill) shadow-(--_edge) pointer-coarse:h-11"
		>
			<!--
				The field keeps the row's direction, so its corners and focus ring round the outer end in
				RTL too, while unicode-bidi: plaintext lets a left-to-right command read left to right.
			-->
			<input
				bind:this={field}
				id="{uid}-value"
				type="text"
				readonly
				{value}
				{placeholder}
				spellcheck="false"
				autocomplete="off"
				aria-label={valueLabel}
				class="min-w-0 flex-1 rounded-s-lg bg-transparent px-3 font-mono text-[13px] leading-5 text-ellipsis text-(--_ink) -outline-offset-2 outline-(--_accent) [font-variant-ligatures:none] [unicode-bidi:plaintext] placeholder:font-sans placeholder:text-(--_muted) focus-visible:outline-2"
				onfocus={(event) => event.currentTarget.select()}
			/>
			<button
				type="button"
				class={[
					'group flex h-full shrink-0 cursor-pointer items-center justify-center gap-2 rounded-e-lg border-s border-(--_hairline) text-sm leading-5 font-medium text-(--_ink) select-none',
					'transition-[color,background-color] duration-150 ease-(--_ease) hover:bg-(--_fill-hover) active:bg-(--_fill-press) active:duration-[80ms]',
					'-outline-offset-2 outline-(--_accent) focus-visible:outline-2',
					'disabled:cursor-not-allowed disabled:bg-transparent disabled:opacity-50',
					iconOnly ? 'w-9 pointer-coarse:w-11' : 'px-3 @max-sm:w-11 @max-sm:px-0'
				]}
				disabled={empty}
				aria-label={iconOnly ? label : undefined}
				aria-controls="{uid}-value"
				onclick={copy}
			>
				{@render face(true)}
			</button>
		</div>
	{:else}
		<button
			type="button"
			class={[
				'group flex h-9 shrink-0 cursor-pointer items-center justify-center gap-2 rounded-lg bg-(--_fill) text-sm leading-5 font-medium text-(--_ink) shadow-(--_edge) select-none pointer-coarse:h-11',
				'transition-[color,background-color,scale] duration-150 ease-(--_ease) hover:bg-(--_fill-hover-solid) active:scale-[.98] active:duration-[80ms] motion-reduce:transition-[color,background-color] motion-reduce:active:scale-100',
				'outline-offset-2 outline-(--_accent) focus-visible:outline-2',
				'disabled:cursor-not-allowed disabled:opacity-50 disabled:active:scale-100',
				iconOnly ? 'w-9 pointer-coarse:w-11' : 'px-3'
			]}
			disabled={empty}
			aria-label={iconOnly ? label : undefined}
			onclick={copy}
		>
			{@render face(false)}
		</button>
	{/if}

	<!-- Always in the tree, so the first result is announced as reliably as the rest. -->
	<span class="sr-only" role="status">{announcement}</span>

	<!-- The status region already speaks this; the note is the sighted half of it. -->
	<div
		class="copy-button__note pointer-events-none absolute start-0 top-full z-10 mt-2 w-max max-w-[min(18rem,calc(100vw-2rem))] gap-2 rounded-lg bg-(--_surface) px-3 py-2 text-xs leading-5 text-(--_ink) shadow-(--_shadow-note)"
		data-open={copyState === 'failed' ? '' : undefined}
		aria-hidden="true"
	>
		<span class="flex h-lh shrink-0 items-center text-(--_error)">
			<svg viewBox="0 0 16 16" fill="none" class="size-4">
				<circle cx="8" cy="8" r="6.25" stroke="currentColor" stroke-width="1.5" />
				<path d="M8 4.75v3.5" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" />
				<circle cx="8" cy="11" r=".875" fill="currentColor" />
			</svg>
		</span>
		<span class="text-balance">{errorLabel}</span>
	</div>
</div>

<style>
	/* Public tokens: set --copy-button-* on the control or any ancestor to retone it. */
	.copy-button {
		--_accent: var(--copy-button-accent, #fafafa);
		--_ink: var(--copy-button-ink, #fafafa);
		--_muted: var(--copy-button-muted, #a1a1aa);
		--_hairline: var(--copy-button-hairline, #ffffff2e);
		--_surface: var(--copy-button-surface, #09090b);
		--_success: var(--copy-button-success, #4ade80);
		--_error: var(--copy-button-error, #f87171);

		/* Formulas: fills mixed from the surface and ink, so they follow any retone. */
		--_fill: color-mix(in oklab, var(--_surface) 97%, var(--_ink));
		--_fill-hover: color-mix(in oklab, var(--_ink) 5%, transparent);
		--_fill-press: color-mix(in oklab, var(--_ink) 9%, transparent);
		--_fill-hover-solid: color-mix(in oklab, var(--_surface) 93%, var(--_ink));
		--_edge: inset 0 0 0 1px var(--_hairline);
		/* The popover elevation from DESIGN §3.5, ringed in the hairline so it reads on dark too. */
		--_shadow-note:
			0 0 0 1px var(--_hairline), 0 4px 6px -1px rgb(0 0 0 / 0.07),
			0 10px 15px -3px rgb(0 0 0 / 0.05);
		--_ease: cubic-bezier(0.2, 0, 0, 1);
	}

	/*
	 * The note's open and close run on different curves and durations, and it leaves layout entirely
	 * while closed (display: none), so a hidden note can never widen the page. Utilities cannot
	 * sequence a discrete display change with a fade. Reduced motion keeps the fade, drops the lift.
	 */
	.copy-button__note {
		display: none;
		opacity: 0;
		translate: 0 -4px;
		transition:
			opacity 150ms cubic-bezier(0.4, 0, 1, 1),
			translate 150ms cubic-bezier(0.4, 0, 1, 1),
			display 150ms allow-discrete;
	}

	.copy-button__note[data-open] {
		display: flex;
		opacity: 1;
		translate: 0 0;
		transition:
			opacity 200ms cubic-bezier(0.16, 1, 0.3, 1),
			translate 200ms cubic-bezier(0.16, 1, 0.3, 1),
			display 200ms allow-discrete;
	}

	@starting-style {
		.copy-button__note[data-open] {
			opacity: 0;
			translate: 0 -4px;
		}
	}

	@media (prefers-reduced-motion: reduce) {
		.copy-button__note,
		.copy-button__note[data-open] {
			translate: none;
		}
	}
</style>

<!--
	Copies a supplied string and confirms it where the click happened. With showValue the value sits
	in a read-only mono field joined to the button as one control; without it the button stands
	alone, labelled or as an icon. The button's width is reserved for the longer of its two labels,
	the result is announced through a status region that is always in the tree, and a failed copy
	selects the value and floats a manual-copy note under the control without moving anything.
-->
<script lang="ts" module>
	export type CopyResult = { ok: boolean };
	export type CopyState = 'idle' | 'copied' | 'failed';
</script>

<script lang="ts">
	interface Props {
		/** The exact text written to the clipboard. An empty string disables the button. */
		value: string;
		/** The button's label and its name at rest. Icon-only buttons keep it as the name in every state, so name the object: "Copy install command". */
		label?: string;
		/** Shown in place of the label, and announced, after a successful copy. */
		copiedLabel?: string;
		/** Shown under the control and announced when copying fails. */
		errorLabel?: string;
		/** Show the value in a read-only field joined to the button. */
		showValue?: boolean;
		/** The field's accessible name, and the group's, when showValue is set. */
		valueLabel?: string;
		/** Shown in the field while value is empty. */
		placeholder?: string;
		/** Milliseconds before a successful copy returns to idle. Infinity keeps it until the next click. */
		resetAfter?: number;
		/** A square icon button; label becomes its aria-label. */
		iconOnly?: boolean;
		/** Called after every attempt, successful or not. */
		onCopy?: (result: CopyResult) => void;
		/** Replaces navigator.clipboard.writeText, for a native shell's clipboard or a test. */
		writeText?: (text: string) => Promise<void>;
		/** Extra classes on the root, for width and placement. */
		class?: string;
	}

	let {
		value,
		label = 'Copy',
		copiedLabel = 'Copied',
		errorLabel = 'Copy failed. Select the text and copy it manually.',
		showValue = false,
		valueLabel = 'Value to copy',
		placeholder,
		resetAfter = 2000,
		iconOnly = false,
		onCopy,
		writeText,
		class: className
	}: Props = $props();

	const uid = $props.id();

	let copyState = $state<CopyState>('idle');
	let announcement = $state('');
	let root = $state<HTMLElement>();
	let field = $state<HTMLInputElement>();

	let timer: ReturnType<typeof setTimeout> | undefined;
	let attempt = 0;
	let flip = false;
	let destroyed = false;

	const empty = $derived(!value);

	function clearTimer() {
		if (timer === undefined) return;
		clearTimeout(timer);
		timer = undefined;
	}

	/*
	 * A polite region only speaks when its text changes, so a repeat alternates a trailing no-break
	 * space. The last result stays in the region after the visual reset, so a reader that delivers
	 * it late still has something to read.
	 */
	const NBSP = String.fromCharCode(160);
	function announce(text: string) {
		flip = !flip;
		announcement = flip ? text : text + NBSP;
	}

	function reset() {
		clearTimer();
		copyState = 'idle';
	}

	/* Dismissing also invalidates a write still in flight, so its result cannot reopen the note. */
	function dismiss() {
		attempt++;
		reset();
	}

	function succeed() {
		clearTimer();
		copyState = 'copied';
		announce(copiedLabel);
		if (Number.isFinite(resetAfter)) timer = setTimeout(reset, Math.max(0, resetAfter));
	}

	function fail() {
		copyState = 'failed';
		announce(errorLabel);
		/*
		 * Hand the value to the keyboard, focused and selected for Ctrl+C, unless focus has already
		 * moved somewhere else on the page.
		 */
		const active = document.activeElement;
		if (field && (!active || active === document.body || root?.contains(active))) {
			field.focus();
			field.select();
			/* select() scrolls to the end; show the start, where a command says what it is. */
			field.scrollLeft = 0;
		}
	}

	function clipboardWrite(text: string): Promise<void> {
		const clipboard = typeof navigator === 'undefined' ? undefined : navigator.clipboard;
		if (!clipboard?.writeText) return Promise.reject(new Error('Clipboard API unavailable'));
		return clipboard.writeText(text);
	}

	async function copy() {
		if (empty) return;
		const current = ++attempt;
		/* A retry closes the last result at once instead of leaving it up while the write runs. */
		reset();
		const ok = await (writeText ?? clipboardWrite)(value).then(
			() => true,
			() => false
		);
		if (destroyed) return;
		/* Only the latest attempt drives the state; every attempt reports to onCopy. */
		if (current === attempt) {
			if (ok) succeed();
			else fail();
		}
		onCopy?.({ ok });
	}

	/*
	 * The failure note stays until the next attempt, Escape, or focus or a click moving elsewhere.
	 * Escape is heard on the document: Safari does not focus a button on click, so focus may never
	 * have entered the control.
	 */
	$effect(() => {
		const el = root;
		if (!el || copyState !== 'failed') return;
		const keydown = (event: KeyboardEvent) => {
			if (event.key === 'Escape') dismiss();
		};
		const focusout = (event: FocusEvent) => {
			if (!el.contains(event.relatedTarget as Node | null)) dismiss();
		};
		const pointerdown = (event: PointerEvent) => {
			if (!el.contains(event.target as Node | null)) dismiss();
		};
		document.addEventListener('keydown', keydown);
		el.addEventListener('focusout', focusout);
		document.addEventListener('pointerdown', pointerdown);
		return () => {
			document.removeEventListener('keydown', keydown);
			el.removeEventListener('focusout', focusout);
			document.removeEventListener('pointerdown', pointerdown);
		};
	});

	$effect(() => () => {
		destroyed = true;
		clearTimer();
	});
</script>

{#snippet face(compact: boolean)}
	<!-- Both marks share one cell and crossfade, so the swap never moves the label. -->
	<span class="grid size-4 shrink-0 place-items-center" aria-hidden="true">
		<svg
			viewBox="0 0 16 16"
			fill="none"
			class={[
				'size-4 transition-[opacity,scale] duration-150 ease-(--_ease) [grid-area:1/1] motion-reduce:scale-100 motion-reduce:transition-opacity',
				copyState === 'copied'
					? 'scale-75 opacity-0'
					: 'text-(--_muted) group-hover:text-(--_ink) group-disabled:text-(--_muted)'
			]}
		>
			<rect
				x="5.75"
				y="5.75"
				width="7.5"
				height="7.5"
				rx="1.5"
				stroke="currentColor"
				stroke-width="1.5"
			/>
			<path
				d="M10.25 3.5v-.25a1.5 1.5 0 0 0-1.5-1.5h-5a1.5 1.5 0 0 0-1.5 1.5v5a1.5 1.5 0 0 0 1.5 1.5h.25"
				stroke="currentColor"
				stroke-width="1.5"
				stroke-linecap="round"
			/>
		</svg>
		<svg
			viewBox="0 0 16 16"
			fill="none"
			class={[
				'size-4 text-(--_success) transition-[opacity,scale] duration-150 ease-(--_ease) [grid-area:1/1] motion-reduce:scale-100 motion-reduce:transition-opacity',
				copyState === 'copied' ? 'opacity-100' : 'scale-75 opacity-0'
			]}
		>
			<path
				d="M3.25 8.5 6.5 11.75l6.25-7.5"
				stroke="currentColor"
				stroke-width="1.75"
				stroke-linecap="round"
				stroke-linejoin="round"
			/>
		</svg>
	</span>
	{#if !iconOnly}
		<!--
			Both labels share one cell, centred, so the button is as wide as the longer one in every state
			and neither sits off to one side. The visible one is the button's name (label in name); the
			other is hidden from the tree. In a narrow joined row the labels go visually hidden, still
			naming the button, so the value keeps the width it needs to say what it is.
		-->
		<span class={['grid justify-items-center', compact && '@max-sm:sr-only']}>
			<span
				class={[
					'transition-opacity duration-150 ease-(--_ease) [grid-area:1/1]',
					copyState === 'copied' && 'opacity-0'
				]}
				aria-hidden={copyState === 'copied' ? 'true' : undefined}>{label}</span
			>
			<span
				class={[
					'transition-opacity duration-150 ease-(--_ease) [grid-area:1/1]',
					copyState !== 'copied' && 'opacity-0'
				]}
				aria-hidden={copyState !== 'copied' ? 'true' : undefined}>{copiedLabel}</span
			>
		</span>
	{/if}
{/snippet}

<div
	bind:this={root}
	class={[
		'copy-button relative',
		showValue ? '@container flex w-full min-w-0' : 'inline-flex align-middle',
		className
	]}
	role={showValue ? 'group' : undefined}
	aria-label={showValue ? valueLabel : undefined}
	data-state={copyState}
>
	{#if showValue}
		<div
			class="flex h-9 min-w-0 flex-1 rounded-lg bg-(--_fill) shadow-(--_edge) pointer-coarse:h-11"
		>
			<!--
				The field keeps the row's direction, so its corners and focus ring round the outer end in
				RTL too, while unicode-bidi: plaintext lets a left-to-right command read left to right.
			-->
			<input
				bind:this={field}
				id="{uid}-value"
				type="text"
				readonly
				{value}
				{placeholder}
				spellcheck="false"
				autocomplete="off"
				aria-label={valueLabel}
				class="min-w-0 flex-1 rounded-s-lg bg-transparent px-3 font-mono text-[13px] leading-5 text-ellipsis text-(--_ink) -outline-offset-2 outline-(--_accent) [font-variant-ligatures:none] [unicode-bidi:plaintext] placeholder:font-sans placeholder:text-(--_muted) focus-visible:outline-2"
				onfocus={(event) => event.currentTarget.select()}
			/>
			<button
				type="button"
				class={[
					'group flex h-full shrink-0 cursor-pointer items-center justify-center gap-2 rounded-e-lg border-s border-(--_hairline) text-sm leading-5 font-medium text-(--_ink) select-none',
					'transition-[color,background-color] duration-150 ease-(--_ease) hover:bg-(--_fill-hover) active:bg-(--_fill-press) active:duration-[80ms]',
					'-outline-offset-2 outline-(--_accent) focus-visible:outline-2',
					'disabled:cursor-not-allowed disabled:bg-transparent disabled:opacity-50',
					iconOnly ? 'w-9 pointer-coarse:w-11' : 'px-3 @max-sm:w-11 @max-sm:px-0'
				]}
				disabled={empty}
				aria-label={iconOnly ? label : undefined}
				aria-controls="{uid}-value"
				onclick={copy}
			>
				{@render face(true)}
			</button>
		</div>
	{:else}
		<button
			type="button"
			class={[
				'group flex h-9 shrink-0 cursor-pointer items-center justify-center gap-2 rounded-lg bg-(--_fill) text-sm leading-5 font-medium text-(--_ink) shadow-(--_edge) select-none pointer-coarse:h-11',
				'transition-[color,background-color,scale] duration-150 ease-(--_ease) hover:bg-(--_fill-hover-solid) active:scale-[.98] active:duration-[80ms] motion-reduce:transition-[color,background-color] motion-reduce:active:scale-100',
				'outline-offset-2 outline-(--_accent) focus-visible:outline-2',
				'disabled:cursor-not-allowed disabled:opacity-50 disabled:active:scale-100',
				iconOnly ? 'w-9 pointer-coarse:w-11' : 'px-3'
			]}
			disabled={empty}
			aria-label={iconOnly ? label : undefined}
			onclick={copy}
		>
			{@render face(false)}
		</button>
	{/if}

	<!-- Always in the tree, so the first result is announced as reliably as the rest. -->
	<span class="sr-only" role="status">{announcement}</span>

	<!-- The status region already speaks this; the note is the sighted half of it. -->
	<div
		class="copy-button__note pointer-events-none absolute start-0 top-full z-10 mt-2 w-max max-w-[min(18rem,calc(100vw-2rem))] gap-2 rounded-lg bg-(--_surface) px-3 py-2 text-xs leading-5 text-(--_ink) shadow-(--_shadow-note)"
		data-open={copyState === 'failed' ? '' : undefined}
		aria-hidden="true"
	>
		<span class="flex h-lh shrink-0 items-center text-(--_error)">
			<svg viewBox="0 0 16 16" fill="none" class="size-4">
				<circle cx="8" cy="8" r="6.25" stroke="currentColor" stroke-width="1.5" />
				<path d="M8 4.75v3.5" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" />
				<circle cx="8" cy="11" r=".875" fill="currentColor" />
			</svg>
		</span>
		<span class="text-balance">{errorLabel}</span>
	</div>
</div>

<style>
	/* Public tokens: set --copy-button-* on the control or any ancestor to retone it. */
	.copy-button {
		--_accent: var(--copy-button-accent, #fafafa);
		--_ink: var(--copy-button-ink, #fafafa);
		--_muted: var(--copy-button-muted, #a1a1aa);
		--_hairline: var(--copy-button-hairline, #ffffff2e);
		--_surface: var(--copy-button-surface, #09090b);
		--_success: var(--copy-button-success, #4ade80);
		--_error: var(--copy-button-error, #f87171);

		/* Formulas: fills mixed from the surface and ink, so they follow any retone. */
		--_fill: color-mix(in oklab, var(--_surface) 97%, var(--_ink));
		--_fill-hover: color-mix(in oklab, var(--_ink) 5%, transparent);
		--_fill-press: color-mix(in oklab, var(--_ink) 9%, transparent);
		--_fill-hover-solid: color-mix(in oklab, var(--_surface) 93%, var(--_ink));
		--_edge: inset 0 0 0 1px var(--_hairline);
		/* The popover elevation from DESIGN §3.5, ringed in the hairline so it reads on dark too. */
		--_shadow-note:
			0 0 0 1px var(--_hairline), 0 4px 6px -1px rgb(0 0 0 / 0.07),
			0 10px 15px -3px rgb(0 0 0 / 0.05);
		--_ease: cubic-bezier(0.2, 0, 0, 1);
	}

	/*
	 * The note's open and close run on different curves and durations, and it leaves layout entirely
	 * while closed (display: none), so a hidden note can never widen the page. Utilities cannot
	 * sequence a discrete display change with a fade. Reduced motion keeps the fade, drops the lift.
	 */
	.copy-button__note {
		display: none;
		opacity: 0;
		translate: 0 -4px;
		transition:
			opacity 150ms cubic-bezier(0.4, 0, 1, 1),
			translate 150ms cubic-bezier(0.4, 0, 1, 1),
			display 150ms allow-discrete;
	}

	.copy-button__note[data-open] {
		display: flex;
		opacity: 1;
		translate: 0 0;
		transition:
			opacity 200ms cubic-bezier(0.16, 1, 0.3, 1),
			translate 200ms cubic-bezier(0.16, 1, 0.3, 1),
			display 200ms allow-discrete;
	}

	@starting-style {
		.copy-button__note[data-open] {
			opacity: 0;
			translate: 0 -4px;
		}
	}

	@media (prefers-reduced-motion: reduce) {
		.copy-button__note,
		.copy-button__note[data-open] {
			translate: none;
		}
	}
</style>