Content-and-sidebar layout

<!--
	A fixed-width rail beside a fluid main column, parted by one full-height hairline. The rail is
	a labelled aside or nav; with sticky set it rides that hairline below the page header and
	scrolls on its own when it is taller than the screen. Below the breakpoint the two stack and
	the hairline turns horizontal. The breakpoint is a container query on the root (56rem), so
	the layout measures the column it sits in, not the viewport.

	The DOM order follows mobilePosition (sidebar first for 'before'), so stacked reading and
	focus order match what is on screen; side only places the columns once side by side.
-->
<script lang="ts">
	import type { Snippet } from 'svelte';

	interface Props {
		/** Supplementary content: a table of contents, filters, section navigation, related links. */
		sidebar: Snippet;
		/** Main content. */
		children: Snippet;
		/** Accessible name for the sidebar landmark, such as "On this page" or "Filters". */
		sidebarLabel: string;
		/** Which side the sidebar takes once side by side, in the writing direction. */
		side?: 'start' | 'end';
		/** Sidebar width once side by side: sm 14rem, md 18rem, lg 22rem. */
		sidebarWidth?: 'sm' | 'md' | 'lg';
		/** Keep the sidebar in view while the main column scrolls, with its own scroll when tall. */
		sticky?: boolean;
		/** Landmark element: nav for links that navigate, aside for filters and related content. */
		sidebarElement?: 'aside' | 'nav';
		/** Where the sidebar sits when stacked. Defaults to before for a start sidebar, after for an end one. */
		mobilePosition?: 'before' | 'after';
		/** Draw the hairline between the sidebar and the main column. */
		divider?: boolean;
		/** Extra classes for the root element. */
		class?: string;
	}

	let {
		sidebar,
		children,
		sidebarLabel,
		side = 'start',
		sidebarWidth = 'md',
		sticky = false,
		sidebarElement = 'aside',
		mobilePosition,
		divider = true,
		class: className
	}: Props = $props();

	/* Width presets, read by the grid template as --_width. Add a size here to add a preset. */
	const WIDTH = {
		sm: '[--_width:14rem]',
		md: '[--_width:18rem]',
		lg: '[--_width:22rem]'
	} as const;

	// Unknown values fall back to the defaults rather than rendering an unstyled grid.
	const end = $derived(side === 'end');
	const element = $derived(sidebarElement === 'nav' ? 'nav' : 'aside');
	const before = $derived(mobilePosition ? mobilePosition !== 'after' : !end);
	const widthClass = $derived(Object.hasOwn(WIDTH, sidebarWidth) ? WIDTH[sidebarWidth] : WIDTH.md);
	/* A blank label would leave an unnamed landmark. */
	const label = $derived(
		sidebarLabel?.trim() || (element === 'nav' ? 'Section navigation' : 'Related information')
	);

	let rail = $state<HTMLElement>();
	let scrollable = $state(false);

	/*
	 * A sticky rail that overflows is a scroll container. When nothing inside it can take focus,
	 * it becomes a tab stop itself so the keyboard can scroll it; when links or fields are inside,
	 * tabbing to them scrolls it already and an extra stop would only be noise.
	 */
	$effect(() => {
		if (!sticky || !rail) return;
		const target = rail;
		const candidates =
			'a[href], area[href], button, input, select, textarea, summary, iframe, [tabindex], [contenteditable]';
		/* In the tab order for real: not tabindex=-1, not disabled (fieldsets included), not inert, rendered. */
		const tabbable = (el: HTMLElement) =>
			el.tabIndex >= 0 &&
			!el.matches(':disabled') &&
			!el.closest('[inert]') &&
			el.getClientRects().length > 0;
		const measure = () => {
			const overflows = target.scrollHeight > target.clientHeight + 1;
			scrollable =
				overflows && ![...target.querySelectorAll<HTMLElement>(candidates)].some(tabbable);
		};
		measure();
		const resize = new ResizeObserver(measure);
		resize.observe(target);
		if (target.firstElementChild) resize.observe(target.firstElementChild);
		// Content, text and the attributes that move an element in or out of the tab order.
		const mutate = new MutationObserver((records) => {
			if (records.every((r) => r.target === target && r.attributeName === 'tabindex')) return;
			measure();
		});
		mutate.observe(target, {
			childList: true,
			subtree: true,
			characterData: true,
			attributes: true,
			attributeFilter: [
				'disabled',
				'href',
				'tabindex',
				'hidden',
				'inert',
				'contenteditable',
				'class',
				'style'
			]
		});
		return () => {
			resize.disconnect();
			mutate.disconnect();
			scrollable = false;
		};
	});
</script>

{#snippet railRegion()}
	<!-- The track stretches to the row's height and carries the hairline; the landmark rides inside it. -->
	<div
		class={[
			'min-w-0',
			end ? '@4xl:col-start-2' : '@4xl:col-start-1',
			'@4xl:row-start-1',
			divider && [
				'border-(--_hairline)',
				before ? 'border-b pb-8' : 'border-t pt-8',
				'@4xl:border-t-0 @4xl:border-b-0 @4xl:pt-0 @4xl:pb-0',
				end ? '@4xl:border-s' : '@4xl:border-e'
			]
		]}
		data-sidebar-layout-track
	>
		<svelte:element
			this={element}
			bind:this={rail}
			aria-label={label}
			tabindex={scrollable ? 0 : undefined}
			class={[
				'sidebar-layout__rail min-w-0 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-(--_accent)',
				divider && (end ? '@4xl:ps-8' : '@4xl:pe-8'),
				sticky && [
					'@4xl:sticky @4xl:top-(--_top) @4xl:max-h-(--_max-height) @4xl:overflow-y-auto @4xl:overscroll-contain',
					/*
					 * A scroller clips its children, focus rings included. Four pixels of padding, taken
					 * back by a negative margin, give a 2 px ring at a 2 px offset room on every side the
					 * divider padding does not already cover, without moving the content edge.
					 */
					'@4xl:-my-1 @4xl:py-1',
					!divider ? '@4xl:-mx-1 @4xl:px-1' : end ? '@4xl:-me-1 @4xl:pe-1' : '@4xl:-ms-1 @4xl:ps-1'
				]
			]}
			data-sticky={sticky ? '' : undefined}
		>
			<div>{@render sidebar()}</div>
		</svelte:element>
	</div>
{/snippet}

{#snippet mainRegion()}
	<!-- min-w-0 and the minmax(0, 1fr) track keep a wide table or code block from pushing the rail off screen. -->
	<div
		class={['min-w-0', end ? '@4xl:col-start-1' : '@4xl:col-start-2', '@4xl:row-start-1']}
		data-sidebar-layout-main
	>
		{@render children()}
	</div>
{/snippet}

<!-- Inline-size containment ignores content width, so the root claims its parent's width. -->
<div class={['sidebar-layout @container w-full min-w-0', widthClass, className]}>
	<div
		class={[
			'grid grid-cols-1 gap-y-8',
			end
				? '@4xl:grid-cols-[minmax(0,1fr)_var(--_width)]'
				: '@4xl:grid-cols-[var(--_width)_minmax(0,1fr)]',
			divider ? '@4xl:gap-x-8' : '@4xl:gap-x-12'
		]}
	>
		{#if before}
			{@render railRegion()}
			{@render mainRegion()}
		{:else}
			{@render mainRegion()}
			{@render railRegion()}
		{/if}
	</div>
</div>

<style>
	/* Public tokens: set --sidebar-layout-* on the layout or any ancestor to retone it. */
	.sidebar-layout {
		--_accent: var(--sidebar-layout-accent, #18181b);
		--_hairline: var(--sidebar-layout-hairline, rgb(0 0 0 / 0.08));
		--_offset: var(--sidebar-layout-offset, 0px);

		/*
		 * Formulas for the sticky rail. The offset is the height of whatever sticks above it: the
		 * larger of --sidebar-layout-offset and site-shell-01's measured header height (or that
		 * shell's estimate before JavaScript runs), so inside that shell it needs no setting. The
		 * rail stops 2rem below the offset and ends 2rem above the bottom of the screen, so its
		 * last item is never cut off.
		 */
		--_top: calc(
			max(var(--_offset), var(--_site-shell-header, var(--_site-shell-estimate, 0px))) + 2rem
		);
		--_max-height: calc(100dvh - var(--_top) - 2rem);
	}

	/*
	 * Scrollbar and edge fade for the scrolling rail, which only scrolls once side by side (the
	 * same 56rem container width as the @4xl: utilities). Stacked, none of this applies, so a mask
	 * never clips the focus rings of links that run the full width. A thin scrollbar in the
	 * hairline's tone sits against the divider, and its gutter is reserved so nothing jumps.
	 */
	@container (min-width: 56rem) {
		.sidebar-layout__rail[data-sticky] {
			scrollbar-width: thin;
			scrollbar-color: color-mix(in srgb, var(--_hairline), currentColor 12%) transparent;
			scrollbar-gutter: stable;
		}
	}

	/*
	 * When the rail overflows, its top and bottom edges fade to say there is more. Scroll-driven,
	 * so it needs no listener: a rail that does not scroll has no active timeline and no fade, and
	 * each fade clears as that end is reached.
	 */
	@property --_fade-start {
		syntax: '<length>';
		inherits: false;
		initial-value: 0px;
	}
	@property --_fade-end {
		syntax: '<length>';
		inherits: false;
		initial-value: 0px;
	}
	@supports (animation-timeline: scroll()) {
		@container (min-width: 56rem) {
			.sidebar-layout__rail[data-sticky] {
				mask-image: linear-gradient(
					to bottom,
					transparent,
					#000 var(--_fade-start),
					#000 calc(100% - var(--_fade-end)),
					transparent
				);
				animation: sidebar-layout-fade linear both;
				animation-timeline: scroll(self block);
			}
			/* Masks reach descendants too, so the fade lifts while anything inside has keyboard focus. */
			.sidebar-layout__rail[data-sticky]:focus-visible,
			.sidebar-layout__rail[data-sticky]:has(:focus-visible) {
				mask-image: none;
			}
		}
	}
	@keyframes sidebar-layout-fade {
		0% {
			--_fade-start: 0px;
			--_fade-end: 2rem;
		}
		4% {
			--_fade-start: 2rem;
		}
		96% {
			--_fade-end: 2rem;
		}
		100% {
			--_fade-start: 2rem;
			--_fade-end: 0px;
		}
	}
</style>

<!--
	A fixed-width rail beside a fluid main column, parted by one full-height hairline. The rail is
	a labelled aside or nav; with sticky set it rides that hairline below the page header and
	scrolls on its own when it is taller than the screen. Below the breakpoint the two stack and
	the hairline turns horizontal. The breakpoint is a container query on the root (56rem), so
	the layout measures the column it sits in, not the viewport.

	The DOM order follows mobilePosition (sidebar first for 'before'), so stacked reading and
	focus order match what is on screen; side only places the columns once side by side.
-->
<script lang="ts">
	import type { Snippet } from 'svelte';

	interface Props {
		/** Supplementary content: a table of contents, filters, section navigation, related links. */
		sidebar: Snippet;
		/** Main content. */
		children: Snippet;
		/** Accessible name for the sidebar landmark, such as "On this page" or "Filters". */
		sidebarLabel: string;
		/** Which side the sidebar takes once side by side, in the writing direction. */
		side?: 'start' | 'end';
		/** Sidebar width once side by side: sm 14rem, md 18rem, lg 22rem. */
		sidebarWidth?: 'sm' | 'md' | 'lg';
		/** Keep the sidebar in view while the main column scrolls, with its own scroll when tall. */
		sticky?: boolean;
		/** Landmark element: nav for links that navigate, aside for filters and related content. */
		sidebarElement?: 'aside' | 'nav';
		/** Where the sidebar sits when stacked. Defaults to before for a start sidebar, after for an end one. */
		mobilePosition?: 'before' | 'after';
		/** Draw the hairline between the sidebar and the main column. */
		divider?: boolean;
		/** Extra classes for the root element. */
		class?: string;
	}

	let {
		sidebar,
		children,
		sidebarLabel,
		side = 'start',
		sidebarWidth = 'md',
		sticky = false,
		sidebarElement = 'aside',
		mobilePosition,
		divider = true,
		class: className
	}: Props = $props();

	/* Width presets, read by the grid template as --_width. Add a size here to add a preset. */
	const WIDTH = {
		sm: '[--_width:14rem]',
		md: '[--_width:18rem]',
		lg: '[--_width:22rem]'
	} as const;

	// Unknown values fall back to the defaults rather than rendering an unstyled grid.
	const end = $derived(side === 'end');
	const element = $derived(sidebarElement === 'nav' ? 'nav' : 'aside');
	const before = $derived(mobilePosition ? mobilePosition !== 'after' : !end);
	const widthClass = $derived(Object.hasOwn(WIDTH, sidebarWidth) ? WIDTH[sidebarWidth] : WIDTH.md);
	/* A blank label would leave an unnamed landmark. */
	const label = $derived(
		sidebarLabel?.trim() || (element === 'nav' ? 'Section navigation' : 'Related information')
	);

	let rail = $state<HTMLElement>();
	let scrollable = $state(false);

	/*
	 * A sticky rail that overflows is a scroll container. When nothing inside it can take focus,
	 * it becomes a tab stop itself so the keyboard can scroll it; when links or fields are inside,
	 * tabbing to them scrolls it already and an extra stop would only be noise.
	 */
	$effect(() => {
		if (!sticky || !rail) return;
		const target = rail;
		const candidates =
			'a[href], area[href], button, input, select, textarea, summary, iframe, [tabindex], [contenteditable]';
		/* In the tab order for real: not tabindex=-1, not disabled (fieldsets included), not inert, rendered. */
		const tabbable = (el: HTMLElement) =>
			el.tabIndex >= 0 &&
			!el.matches(':disabled') &&
			!el.closest('[inert]') &&
			el.getClientRects().length > 0;
		const measure = () => {
			const overflows = target.scrollHeight > target.clientHeight + 1;
			scrollable =
				overflows && ![...target.querySelectorAll<HTMLElement>(candidates)].some(tabbable);
		};
		measure();
		const resize = new ResizeObserver(measure);
		resize.observe(target);
		if (target.firstElementChild) resize.observe(target.firstElementChild);
		// Content, text and the attributes that move an element in or out of the tab order.
		const mutate = new MutationObserver((records) => {
			if (records.every((r) => r.target === target && r.attributeName === 'tabindex')) return;
			measure();
		});
		mutate.observe(target, {
			childList: true,
			subtree: true,
			characterData: true,
			attributes: true,
			attributeFilter: [
				'disabled',
				'href',
				'tabindex',
				'hidden',
				'inert',
				'contenteditable',
				'class',
				'style'
			]
		});
		return () => {
			resize.disconnect();
			mutate.disconnect();
			scrollable = false;
		};
	});
</script>

{#snippet railRegion()}
	<!-- The track stretches to the row's height and carries the hairline; the landmark rides inside it. -->
	<div
		class={[
			'min-w-0',
			end ? '@4xl:col-start-2' : '@4xl:col-start-1',
			'@4xl:row-start-1',
			divider && [
				'border-(--_hairline)',
				before ? 'border-b pb-8' : 'border-t pt-8',
				'@4xl:border-t-0 @4xl:border-b-0 @4xl:pt-0 @4xl:pb-0',
				end ? '@4xl:border-s' : '@4xl:border-e'
			]
		]}
		data-sidebar-layout-track
	>
		<svelte:element
			this={element}
			bind:this={rail}
			aria-label={label}
			tabindex={scrollable ? 0 : undefined}
			class={[
				'sidebar-layout__rail min-w-0 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-(--_accent)',
				divider && (end ? '@4xl:ps-8' : '@4xl:pe-8'),
				sticky && [
					'@4xl:sticky @4xl:top-(--_top) @4xl:max-h-(--_max-height) @4xl:overflow-y-auto @4xl:overscroll-contain',
					/*
					 * A scroller clips its children, focus rings included. Four pixels of padding, taken
					 * back by a negative margin, give a 2 px ring at a 2 px offset room on every side the
					 * divider padding does not already cover, without moving the content edge.
					 */
					'@4xl:-my-1 @4xl:py-1',
					!divider ? '@4xl:-mx-1 @4xl:px-1' : end ? '@4xl:-me-1 @4xl:pe-1' : '@4xl:-ms-1 @4xl:ps-1'
				]
			]}
			data-sticky={sticky ? '' : undefined}
		>
			<div>{@render sidebar()}</div>
		</svelte:element>
	</div>
{/snippet}

{#snippet mainRegion()}
	<!-- min-w-0 and the minmax(0, 1fr) track keep a wide table or code block from pushing the rail off screen. -->
	<div
		class={['min-w-0', end ? '@4xl:col-start-1' : '@4xl:col-start-2', '@4xl:row-start-1']}
		data-sidebar-layout-main
	>
		{@render children()}
	</div>
{/snippet}

<!-- Inline-size containment ignores content width, so the root claims its parent's width. -->
<div class={['sidebar-layout @container w-full min-w-0', widthClass, className]}>
	<div
		class={[
			'grid grid-cols-1 gap-y-8',
			end
				? '@4xl:grid-cols-[minmax(0,1fr)_var(--_width)]'
				: '@4xl:grid-cols-[var(--_width)_minmax(0,1fr)]',
			divider ? '@4xl:gap-x-8' : '@4xl:gap-x-12'
		]}
	>
		{#if before}
			{@render railRegion()}
			{@render mainRegion()}
		{:else}
			{@render mainRegion()}
			{@render railRegion()}
		{/if}
	</div>
</div>

<style>
	/* Public tokens: set --sidebar-layout-* on the layout or any ancestor to retone it. */
	.sidebar-layout {
		--_accent: var(--sidebar-layout-accent, #18181b);
		--_hairline: var(--sidebar-layout-hairline, rgb(0 0 0 / 0.08));
		--_offset: var(--sidebar-layout-offset, 0px);

		/*
		 * Formulas for the sticky rail. The offset is the height of whatever sticks above it: the
		 * larger of --sidebar-layout-offset and site-shell-01's measured header height (or that
		 * shell's estimate before JavaScript runs), so inside that shell it needs no setting. The
		 * rail stops 2rem below the offset and ends 2rem above the bottom of the screen, so its
		 * last item is never cut off.
		 */
		--_top: calc(
			max(var(--_offset), var(--_site-shell-header, var(--_site-shell-estimate, 0px))) + 2rem
		);
		--_max-height: calc(100dvh - var(--_top) - 2rem);
	}

	/*
	 * Scrollbar and edge fade for the scrolling rail, which only scrolls once side by side (the
	 * same 56rem container width as the @4xl: utilities). Stacked, none of this applies, so a mask
	 * never clips the focus rings of links that run the full width. A thin scrollbar in the
	 * hairline's tone sits against the divider, and its gutter is reserved so nothing jumps.
	 */
	@container (min-width: 56rem) {
		.sidebar-layout__rail[data-sticky] {
			scrollbar-width: thin;
			scrollbar-color: color-mix(in srgb, var(--_hairline), currentColor 12%) transparent;
			scrollbar-gutter: stable;
		}
	}

	/*
	 * When the rail overflows, its top and bottom edges fade to say there is more. Scroll-driven,
	 * so it needs no listener: a rail that does not scroll has no active timeline and no fade, and
	 * each fade clears as that end is reached.
	 */
	@property --_fade-start {
		syntax: '<length>';
		inherits: false;
		initial-value: 0px;
	}
	@property --_fade-end {
		syntax: '<length>';
		inherits: false;
		initial-value: 0px;
	}
	@supports (animation-timeline: scroll()) {
		@container (min-width: 56rem) {
			.sidebar-layout__rail[data-sticky] {
				mask-image: linear-gradient(
					to bottom,
					transparent,
					#000 var(--_fade-start),
					#000 calc(100% - var(--_fade-end)),
					transparent
				);
				animation: sidebar-layout-fade linear both;
				animation-timeline: scroll(self block);
			}
			/* Masks reach descendants too, so the fade lifts while anything inside has keyboard focus. */
			.sidebar-layout__rail[data-sticky]:focus-visible,
			.sidebar-layout__rail[data-sticky]:has(:focus-visible) {
				mask-image: none;
			}
		}
	}
	@keyframes sidebar-layout-fade {
		0% {
			--_fade-start: 0px;
			--_fade-end: 2rem;
		}
		4% {
			--_fade-start: 2rem;
		}
		96% {
			--_fade-end: 2rem;
		}
		100% {
			--_fade-start: 2rem;
			--_fade-end: 0px;
		}
	}
</style>