Alternating feature sections

<script lang="ts" module>
	/**
	 * Width and height are the file's intrinsic size. They reserve the frame's shape before the file
	 * loads. Use alt: '' only when the row's copy already says everything the image shows.
	 */
	export interface AlternatingFeatureMedia {
		src: string;
		alt: string;
		width: number;
		height: number;
	}

	export interface AlternatingFeatureLink {
		/** Visible link text. The row's heading is added as its description. */
		label: string;
		href: string;
	}

	export interface AlternatingFeature {
		/** Row heading, one level below the section heading. */
		title: string;
		/** One to three sentences of plain text. */
		body: string;
		/** Short label above the row heading, set in the accent. */
		eyebrow?: string;
		/** Supporting points, one short line each. */
		points?: string[];
		/** The row's picture. Omit it and the row spans the full width as a heading-and-copy split. */
		media?: AlternatingFeatureMedia;
		/** One text link under the copy. */
		link?: AlternatingFeatureLink;
	}
</script>

<script lang="ts">
	interface Props {
		/** Rows in order. */
		items: AlternatingFeature[];
		/** Section heading. Omitted, the rows start the section. */
		title?: string;
		/** One or two sentences under the section heading. */
		description?: string;
		/** Which side the first row's media takes from the lg breakpoint; later rows alternate. */
		startWith?: 'media-start' | 'media-end';
		/** Section heading level. Rows use one level below it, or this level when there is no title. */
		headingLevel?: 2 | 3;
		/** Frame shape for every row: the file's own ratio, 16:9 or 1:1. */
		mediaAspect?: 'auto' | 'video' | 'square';
		/** Numbers the rows 01, 02, 03 and renders them as an ordered list, for a product tour. */
		numbered?: boolean;
	}

	let {
		items,
		title,
		description,
		startWith = 'media-end',
		headingLevel = 2,
		mediaAspect = 'auto',
		numbered = false
	}: Props = $props();

	const uid = $props.id();

	const sectionTag = $derived(headingLevel === 3 ? 'h3' : 'h2');
	const rowTag = $derived(!title ? sectionTag : headingLevel === 3 ? 'h4' : 'h3');

	/*
	 * Alternation counts media rows only, so a text-only row in the middle never leaves two frames
	 * on the same side one after the other.
	 */
	const rows = $derived.by(() => {
		let mediaIndex = 0;
		return items.map((item) => {
			if (!item.media) return { item, start: false };
			const first = mediaIndex++ % 2 === 0;
			return { item, start: first === (startWith === 'media-start') };
		});
	});

	/* Reserve the frame's shape before the file loads; a missing or zero size falls back to 4:3. */
	function ratio(media: AlternatingFeatureMedia) {
		if (mediaAspect === 'video') return '16 / 9';
		if (mediaAspect === 'square') return '1 / 1';
		return media.width > 0 && media.height > 0 ? `${media.width} / ${media.height}` : '4 / 3';
	}

	const pad = (n: number) => String(n).padStart(2, '0');
</script>

{#snippet head(item: AlternatingFeature, i: number)}
	{#if numbered || item.eyebrow}
		<p
			class="alternating-features__eyebrow alternating-features__tracked mb-2 flex items-baseline gap-x-2 text-xs/4 font-medium tracking-[0.06em] break-words uppercase"
		>
			{#if numbered}
				<!-- The ordered list already announces the number. -->
				<span class="shrink-0 text-[var(--_muted)] tabular-nums" aria-hidden="true"
					>{pad(i + 1)}</span
				>
			{/if}
			{#if item.eyebrow}
				<span class="min-w-0 flex-1 text-balance text-[var(--_accent)]">{item.eyebrow}</span>
			{/if}
		</p>
	{/if}
	<svelte:element
		this={rowTag}
		id="{uid}-row-{i}"
		class="alternating-features__tracked alternating-features__heading text-2xl/[1.2] font-semibold tracking-[-0.02em] text-balance break-words text-[var(--_ink)]"
	>
		{item.title}
	</svelte:element>
{/snippet}

{#snippet copy(item: AlternatingFeature, i: number)}
	<p
		class="alternating-features__prose max-w-[35rem] text-base/6 text-pretty break-words text-[var(--_muted)] sm:text-lg/7"
	>
		{item.body}
	</p>
	{#if item.points?.length}
		<ul role="list" class="mt-6 flex max-w-[35rem] flex-col gap-2">
			{#each item.points as point, p (p)}
				<li
					class="alternating-features__prose flex gap-2 text-base/6 break-words text-[var(--_ink)]"
				>
					<!-- One line tall, so the mark stays level with the first line of a wrapped point. -->
					<span class="flex h-lh shrink-0 items-center text-[var(--_accent)]" aria-hidden="true">
						<svg
							class="size-4"
							viewBox="0 0 16 16"
							fill="none"
							stroke="currentColor"
							stroke-width="1.75"
							stroke-linecap="round"
							stroke-linejoin="round"
						>
							<path d="m3.5 8.5 3 3 6-7" />
						</svg>
					</span>
					<span class="min-w-0">{point}</span>
				</li>
			{/each}
		</ul>
	{/if}
	{#if item.link}
		<!-- The 44 px box adds 10 px above the label, so mt-4 reads as the 24 px text-to-action gap. -->
		<a
			href={item.link.href}
			class="alternating-features__link mt-4 flex min-h-11 w-fit max-w-full items-center rounded-sm text-base/6 font-medium text-[var(--_accent)] focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--_accent)]"
			aria-describedby="{uid}-row-{i}"
		>
			<!-- The arrow is joined to the last word (U+2060) so it follows a wrapped label. -->
			<span class="min-w-0 [overflow-wrap:anywhere]"
				>{item.link.label}&#8288;<svg
					class="alternating-features__arrow ms-2 inline-block size-4 align-[-0.1875em] rtl:-scale-x-100"
					viewBox="0 0 16 16"
					fill="none"
					stroke="currentColor"
					stroke-width="1.75"
					stroke-linecap="round"
					stroke-linejoin="round"
					aria-hidden="true"
				>
					<path d="M3 8h10M9 4l4 4-4 4" />
				</svg></span
			>
		</a>
	{/if}
{/snippet}

<!-- With no rows there is nothing to introduce, so the section renders nothing rather than a lone heading. -->
{#if items.length}
	<section
		class="alternating-features px-4 py-16 sm:px-6 sm:py-24 lg:px-8 lg:py-32"
		aria-labelledby={title ? `${uid}-title` : undefined}
	>
		<div class="mx-auto max-w-7xl">
			{#if title}
				<div class="mb-16 max-w-2xl text-start">
					<svelte:element
						this={sectionTag}
						id="{uid}-title"
						class="alternating-features__tracked alternating-features__heading text-3xl/[1.15] font-semibold tracking-[-0.02em] text-balance break-words text-[var(--_ink)] sm:text-4xl/[1.15]"
					>
						{title}
					</svelte:element>
					{#if description}
						<p
							class="alternating-features__prose mt-4 max-w-[35rem] text-base/6 text-pretty break-words text-[var(--_muted)] sm:text-lg/7"
						>
							{description}
						</p>
					{/if}
				</div>
			{/if}

			<svelte:element
				this={numbered ? 'ol' : 'ul'}
				role="list"
				class="flex flex-col gap-20 lg:gap-32"
			>
				{#each rows as { item, start }, i (i)}
					<li
						class={[
							'alternating-features__row grid',
							item.media
								? [
										'items-center gap-6 lg:gap-16',
										start
											? 'lg:grid-cols-[minmax(0,7fr)_minmax(0,5fr)]'
											: 'lg:grid-cols-[minmax(0,5fr)_minmax(0,7fr)]'
									]
								: 'gap-4 lg:grid-cols-[minmax(0,5fr)_minmax(0,7fr)] lg:gap-16'
						]}
					>
						{#if item.media}
							<!-- The copy comes first in the DOM at every width; start only moves it with the grid. -->
							<div class={['min-w-0 text-start', start && 'lg:col-start-2 lg:row-start-1']}>
								{@render head(item, i)}
								<div class="mt-4">{@render copy(item, i)}</div>
							</div>
							<figure class={['m-0 min-w-0', start && 'lg:col-start-1 lg:row-start-1']}>
								<div
									class="relative overflow-hidden rounded-[var(--_frame-radius)] bg-[var(--_surface)]"
									style:aspect-ratio={ratio(item.media)}
								>
									<img
										class="absolute inset-0 size-full object-cover"
										src={item.media.src}
										alt={item.media.alt}
										width={item.media.width || undefined}
										height={item.media.height || undefined}
										loading="lazy"
										decoding="async"
									/>
									<!-- The hairline sits over the image so a pale picture still has an edge. -->
									<span
										class="pointer-events-none absolute inset-0 rounded-[inherit] ring-1 ring-[var(--_hairline)] ring-inset"
										aria-hidden="true"
									></span>
								</div>
							</figure>
						{:else}
							<!-- No media: the heading takes the narrow column and the copy the wide one. -->
							<div class="min-w-0 text-start">
								{@render head(item, i)}
							</div>
							<div class="min-w-0 text-start">
								{@render copy(item, i)}
							</div>
						{/if}
					</li>
				{/each}
			</svelte:element>
		</div>
	</section>
{/if}

<style>
	/* Public tokens: set --alternating-features-* on this section or any ancestor to retone it. */
	.alternating-features {
		--_accent: var(--alternating-features-accent, #18181b);
		--_ink: var(--alternating-features-ink, #18181b);
		--_muted: var(--alternating-features-muted, #52525b);
		--_hairline: var(--alternating-features-hairline, rgb(0 0 0 / 0.08));
		--_frame-radius: var(--alternating-features-frame-radius, 16px);
		/* The frame's fill, seen before the image paints: one quiet step off a white page. */
		--_surface: var(--alternating-features-surface, rgb(24 24 27 / 0.04));
	}

	/* Hover is only on the link: the label underlines and the arrow steps along the reading direction. */
	.alternating-features__link {
		text-decoration-line: underline;
		text-decoration-color: transparent;
		text-decoration-thickness: 1px;
		text-underline-offset: 4px;
		transition-property: text-decoration-color, transform;
		transition-duration: 150ms;
		transition-timing-function: cubic-bezier(0.2, 0, 0, 1);
	}
	.alternating-features__link:hover {
		text-decoration-color: color-mix(in oklab, var(--_accent) 45%, transparent);
	}
	.alternating-features__link:active {
		transform: translateY(1px);
		transition-duration: 80ms;
	}
	.alternating-features__arrow {
		transition: translate 150ms cubic-bezier(0.2, 0, 0, 1);
	}
	/* The nudge follows the reading direction; the arrow's own flip is a separate scale. */
	.alternating-features__link {
		--_nudge: 2px;
	}
	.alternating-features__link:dir(rtl) {
		--_nudge: -2px;
	}
	.alternating-features__link:hover .alternating-features__arrow {
		translate: var(--_nudge) 0;
	}

	/* Arabic and Hebrew are never letter-spaced, and CJK is not tightened. */
	.alternating-features__tracked:dir(rtl),
	.alternating-features__tracked:is(:lang(ja), :lang(zh), :lang(ko)) {
		letter-spacing: 0;
	}
	/* Uppercase does nothing for Hebrew or Arabic, so the eyebrow takes a step up in size instead. */
	.alternating-features__eyebrow:dir(rtl) {
		font-size: 0.8125rem;
	}
	/*
	 * Japanese and Chinese have no spaces: break between phrases where the browser can, keep
	 * closing punctuation on its line, and never break mid-word. Korean spaces its words.
	 */
	:is(.alternating-features__heading, .alternating-features__prose):is(:lang(ja), :lang(zh)) {
		word-break: normal;
		word-break: auto-phrase;
		line-break: strict;
	}
	.alternating-features__heading:lang(ko) {
		word-break: keep-all;
	}

	@media (prefers-reduced-motion: reduce) {
		.alternating-features__link:active {
			transform: none;
		}
		.alternating-features__link {
			--_nudge: 0px;
		}
		.alternating-features__link:dir(rtl) {
			--_nudge: 0px;
		}
	}
</style>

<script lang="ts" module>
	/**
	 * Width and height are the file's intrinsic size. They reserve the frame's shape before the file
	 * loads. Use alt: '' only when the row's copy already says everything the image shows.
	 */
	export interface AlternatingFeatureMedia {
		src: string;
		alt: string;
		width: number;
		height: number;
	}

	export interface AlternatingFeatureLink {
		/** Visible link text. The row's heading is added as its description. */
		label: string;
		href: string;
	}

	export interface AlternatingFeature {
		/** Row heading, one level below the section heading. */
		title: string;
		/** One to three sentences of plain text. */
		body: string;
		/** Short label above the row heading, set in the accent. */
		eyebrow?: string;
		/** Supporting points, one short line each. */
		points?: string[];
		/** The row's picture. Omit it and the row spans the full width as a heading-and-copy split. */
		media?: AlternatingFeatureMedia;
		/** One text link under the copy. */
		link?: AlternatingFeatureLink;
	}
</script>

<script lang="ts">
	interface Props {
		/** Rows in order. */
		items: AlternatingFeature[];
		/** Section heading. Omitted, the rows start the section. */
		title?: string;
		/** One or two sentences under the section heading. */
		description?: string;
		/** Which side the first row's media takes from the lg breakpoint; later rows alternate. */
		startWith?: 'media-start' | 'media-end';
		/** Section heading level. Rows use one level below it, or this level when there is no title. */
		headingLevel?: 2 | 3;
		/** Frame shape for every row: the file's own ratio, 16:9 or 1:1. */
		mediaAspect?: 'auto' | 'video' | 'square';
		/** Numbers the rows 01, 02, 03 and renders them as an ordered list, for a product tour. */
		numbered?: boolean;
	}

	let {
		items,
		title,
		description,
		startWith = 'media-end',
		headingLevel = 2,
		mediaAspect = 'auto',
		numbered = false
	}: Props = $props();

	const uid = $props.id();

	const sectionTag = $derived(headingLevel === 3 ? 'h3' : 'h2');
	const rowTag = $derived(!title ? sectionTag : headingLevel === 3 ? 'h4' : 'h3');

	/*
	 * Alternation counts media rows only, so a text-only row in the middle never leaves two frames
	 * on the same side one after the other.
	 */
	const rows = $derived.by(() => {
		let mediaIndex = 0;
		return items.map((item) => {
			if (!item.media) return { item, start: false };
			const first = mediaIndex++ % 2 === 0;
			return { item, start: first === (startWith === 'media-start') };
		});
	});

	/* Reserve the frame's shape before the file loads; a missing or zero size falls back to 4:3. */
	function ratio(media: AlternatingFeatureMedia) {
		if (mediaAspect === 'video') return '16 / 9';
		if (mediaAspect === 'square') return '1 / 1';
		return media.width > 0 && media.height > 0 ? `${media.width} / ${media.height}` : '4 / 3';
	}

	const pad = (n: number) => String(n).padStart(2, '0');
</script>

{#snippet head(item: AlternatingFeature, i: number)}
	{#if numbered || item.eyebrow}
		<p
			class="alternating-features__eyebrow alternating-features__tracked mb-2 flex items-baseline gap-x-2 text-xs/4 font-medium tracking-[0.06em] break-words uppercase"
		>
			{#if numbered}
				<!-- The ordered list already announces the number. -->
				<span class="shrink-0 text-[var(--_muted)] tabular-nums" aria-hidden="true"
					>{pad(i + 1)}</span
				>
			{/if}
			{#if item.eyebrow}
				<span class="min-w-0 flex-1 text-balance text-[var(--_accent)]">{item.eyebrow}</span>
			{/if}
		</p>
	{/if}
	<svelte:element
		this={rowTag}
		id="{uid}-row-{i}"
		class="alternating-features__tracked alternating-features__heading text-2xl/[1.2] font-semibold tracking-[-0.02em] text-balance break-words text-[var(--_ink)]"
	>
		{item.title}
	</svelte:element>
{/snippet}

{#snippet copy(item: AlternatingFeature, i: number)}
	<p
		class="alternating-features__prose max-w-[35rem] text-base/6 text-pretty break-words text-[var(--_muted)] sm:text-lg/7"
	>
		{item.body}
	</p>
	{#if item.points?.length}
		<ul role="list" class="mt-6 flex max-w-[35rem] flex-col gap-2">
			{#each item.points as point, p (p)}
				<li
					class="alternating-features__prose flex gap-2 text-base/6 break-words text-[var(--_ink)]"
				>
					<!-- One line tall, so the mark stays level with the first line of a wrapped point. -->
					<span class="flex h-lh shrink-0 items-center text-[var(--_accent)]" aria-hidden="true">
						<svg
							class="size-4"
							viewBox="0 0 16 16"
							fill="none"
							stroke="currentColor"
							stroke-width="1.75"
							stroke-linecap="round"
							stroke-linejoin="round"
						>
							<path d="m3.5 8.5 3 3 6-7" />
						</svg>
					</span>
					<span class="min-w-0">{point}</span>
				</li>
			{/each}
		</ul>
	{/if}
	{#if item.link}
		<!-- The 44 px box adds 10 px above the label, so mt-4 reads as the 24 px text-to-action gap. -->
		<a
			href={item.link.href}
			class="alternating-features__link mt-4 flex min-h-11 w-fit max-w-full items-center rounded-sm text-base/6 font-medium text-[var(--_accent)] focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-[var(--_accent)]"
			aria-describedby="{uid}-row-{i}"
		>
			<!-- The arrow is joined to the last word (U+2060) so it follows a wrapped label. -->
			<span class="min-w-0 [overflow-wrap:anywhere]"
				>{item.link.label}&#8288;<svg
					class="alternating-features__arrow ms-2 inline-block size-4 align-[-0.1875em] rtl:-scale-x-100"
					viewBox="0 0 16 16"
					fill="none"
					stroke="currentColor"
					stroke-width="1.75"
					stroke-linecap="round"
					stroke-linejoin="round"
					aria-hidden="true"
				>
					<path d="M3 8h10M9 4l4 4-4 4" />
				</svg></span
			>
		</a>
	{/if}
{/snippet}

<!-- With no rows there is nothing to introduce, so the section renders nothing rather than a lone heading. -->
{#if items.length}
	<section
		class="alternating-features px-4 py-16 sm:px-6 sm:py-24 lg:px-8 lg:py-32"
		aria-labelledby={title ? `${uid}-title` : undefined}
	>
		<div class="mx-auto max-w-7xl">
			{#if title}
				<div class="mb-16 max-w-2xl text-start">
					<svelte:element
						this={sectionTag}
						id="{uid}-title"
						class="alternating-features__tracked alternating-features__heading text-3xl/[1.15] font-semibold tracking-[-0.02em] text-balance break-words text-[var(--_ink)] sm:text-4xl/[1.15]"
					>
						{title}
					</svelte:element>
					{#if description}
						<p
							class="alternating-features__prose mt-4 max-w-[35rem] text-base/6 text-pretty break-words text-[var(--_muted)] sm:text-lg/7"
						>
							{description}
						</p>
					{/if}
				</div>
			{/if}

			<svelte:element
				this={numbered ? 'ol' : 'ul'}
				role="list"
				class="flex flex-col gap-20 lg:gap-32"
			>
				{#each rows as { item, start }, i (i)}
					<li
						class={[
							'alternating-features__row grid',
							item.media
								? [
										'items-center gap-6 lg:gap-16',
										start
											? 'lg:grid-cols-[minmax(0,7fr)_minmax(0,5fr)]'
											: 'lg:grid-cols-[minmax(0,5fr)_minmax(0,7fr)]'
									]
								: 'gap-4 lg:grid-cols-[minmax(0,5fr)_minmax(0,7fr)] lg:gap-16'
						]}
					>
						{#if item.media}
							<!-- The copy comes first in the DOM at every width; start only moves it with the grid. -->
							<div class={['min-w-0 text-start', start && 'lg:col-start-2 lg:row-start-1']}>
								{@render head(item, i)}
								<div class="mt-4">{@render copy(item, i)}</div>
							</div>
							<figure class={['m-0 min-w-0', start && 'lg:col-start-1 lg:row-start-1']}>
								<div
									class="relative overflow-hidden rounded-[var(--_frame-radius)] bg-[var(--_surface)]"
									style:aspect-ratio={ratio(item.media)}
								>
									<img
										class="absolute inset-0 size-full object-cover"
										src={item.media.src}
										alt={item.media.alt}
										width={item.media.width || undefined}
										height={item.media.height || undefined}
										loading="lazy"
										decoding="async"
									/>
									<!-- The hairline sits over the image so a pale picture still has an edge. -->
									<span
										class="pointer-events-none absolute inset-0 rounded-[inherit] ring-1 ring-[var(--_hairline)] ring-inset"
										aria-hidden="true"
									></span>
								</div>
							</figure>
						{:else}
							<!-- No media: the heading takes the narrow column and the copy the wide one. -->
							<div class="min-w-0 text-start">
								{@render head(item, i)}
							</div>
							<div class="min-w-0 text-start">
								{@render copy(item, i)}
							</div>
						{/if}
					</li>
				{/each}
			</svelte:element>
		</div>
	</section>
{/if}

<style>
	/* Public tokens: set --alternating-features-* on this section or any ancestor to retone it. */
	.alternating-features {
		--_accent: var(--alternating-features-accent, #18181b);
		--_ink: var(--alternating-features-ink, #18181b);
		--_muted: var(--alternating-features-muted, #52525b);
		--_hairline: var(--alternating-features-hairline, rgb(0 0 0 / 0.08));
		--_frame-radius: var(--alternating-features-frame-radius, 16px);
		/* The frame's fill, seen before the image paints: one quiet step off a white page. */
		--_surface: var(--alternating-features-surface, rgb(24 24 27 / 0.04));
	}

	/* Hover is only on the link: the label underlines and the arrow steps along the reading direction. */
	.alternating-features__link {
		text-decoration-line: underline;
		text-decoration-color: transparent;
		text-decoration-thickness: 1px;
		text-underline-offset: 4px;
		transition-property: text-decoration-color, transform;
		transition-duration: 150ms;
		transition-timing-function: cubic-bezier(0.2, 0, 0, 1);
	}
	.alternating-features__link:hover {
		text-decoration-color: color-mix(in oklab, var(--_accent) 45%, transparent);
	}
	.alternating-features__link:active {
		transform: translateY(1px);
		transition-duration: 80ms;
	}
	.alternating-features__arrow {
		transition: translate 150ms cubic-bezier(0.2, 0, 0, 1);
	}
	/* The nudge follows the reading direction; the arrow's own flip is a separate scale. */
	.alternating-features__link {
		--_nudge: 2px;
	}
	.alternating-features__link:dir(rtl) {
		--_nudge: -2px;
	}
	.alternating-features__link:hover .alternating-features__arrow {
		translate: var(--_nudge) 0;
	}

	/* Arabic and Hebrew are never letter-spaced, and CJK is not tightened. */
	.alternating-features__tracked:dir(rtl),
	.alternating-features__tracked:is(:lang(ja), :lang(zh), :lang(ko)) {
		letter-spacing: 0;
	}
	/* Uppercase does nothing for Hebrew or Arabic, so the eyebrow takes a step up in size instead. */
	.alternating-features__eyebrow:dir(rtl) {
		font-size: 0.8125rem;
	}
	/*
	 * Japanese and Chinese have no spaces: break between phrases where the browser can, keep
	 * closing punctuation on its line, and never break mid-word. Korean spaces its words.
	 */
	:is(.alternating-features__heading, .alternating-features__prose):is(:lang(ja), :lang(zh)) {
		word-break: normal;
		word-break: auto-phrase;
		line-break: strict;
	}
	.alternating-features__heading:lang(ko) {
		word-break: keep-all;
	}

	@media (prefers-reduced-motion: reduce) {
		.alternating-features__link:active {
			transform: none;
		}
		.alternating-features__link {
			--_nudge: 0px;
		}
		.alternating-features__link:dir(rtl) {
			--_nudge: 0px;
		}
	}
</style>