@mystravil/hardpoint 0.0.0-stage → 0.2.0

package/dist/components/ImageViewer.svelte.d.ts

@@ -0,0 +1,55 @@
+import type { Snippet } from 'svelte';
+import { Dialog as BitsDialog } from 'bits-ui';
+export type ImageViewerTriggerSnippetProps = {
+    /**
+     * Spread onto the button that opens the viewer, usually around a
+     * thumbnail, so the image opens from the keyboard too.
+     */
+    props: Record<string, unknown>;
+};
+/**
+ * Attributes and handlers not listed here go to the viewer element (Bits
+ * UI `Dialog.Content`), among them `onOpenAutoFocus`, `onCloseAutoFocus`,
+ * `onEscapeKeydown` and `onInteractOutside`.
+ */
+export type ImageViewerProps = Omit<BitsDialog.ContentProps, 'child' | 'children' | 'forceMount' | 'ref' | 'title'> & {
+    open?: boolean;
+    /** The image's URL. A different URL while open starts a new load at scale 1. */
+    src: string;
+    /**
+     * The text alternative, required. It also names the viewer when there
+     * is no `title`, so it should describe the image, never be empty.
+     */
+    alt: string;
+    /**
+     * A line in the top bar, shown as written (a file name, a caption) on
+     * one line, cut with an ellipsis. It names the viewer when set.
+     */
+    title?: string;
+    /** The button that opens the viewer: spread `props` onto it. */
+    trigger?: Snippet<[ImageViewerTriggerSnippetProps]>;
+    /**
+     * Shows the Download button, which saves `src` under this file name
+     * through a link with `download`. A `data:` URL becomes a `blob:` URL
+     * first. Browsers ignore `download` on a link to another origin, so an
+     * image from another origin needs `ondownload`.
+     */
+    downloadName?: string;
+    /**
+     * Shows the Download button and replaces the built-in save, for an app
+     * with its own save picker or confirmation. While its promise is
+     * pending, another press does nothing. Errors are the app's to catch.
+     */
+    ondownload?: () => void | Promise<void>;
+    /** The close button's accessible name. */
+    closeLabel?: string;
+    /** The Download button's label. */
+    downloadLabel?: string;
+    /** The spinner's label while the image loads. */
+    loadingLabel?: string;
+    /** The viewer element. */
+    ref?: HTMLElement | null;
+};
+declare const ImageViewer: import("svelte").Component<ImageViewerProps, {}, "ref" | "open">;
+type ImageViewer = ReturnType<typeof ImageViewer>;
+export default ImageViewer;

package/dist/components/KeyValueList.svelte

@@ -0,0 +1,114 @@
+<script lang="ts" module>
+	import type { Snippet } from 'svelte';
+	import type { HTMLAttributes } from 'svelte/elements';
+
+	export type KeyValueItem = {
+		/** The caps label in the first column. A fixed string the app defines. */
+		key: string;
+		/** The value in Geist Mono. */
+		value: string | number;
+	};
+
+	/** Items may carry extra fields (an `href`, a status) that the `value` snippet reads. */
+	export type KeyValueListProps<T extends KeyValueItem = KeyValueItem> = Omit<
+		HTMLAttributes<HTMLDListElement>,
+		'children'
+	> & {
+		items: T[];
+		/**
+		 * The label column's width from 600px up: any CSS width. Defaults to
+		 * `9rem`. Below 600px the label stacks over the value.
+		 */
+		keyWidth?: string;
+		/** Renders one value, for a link or a status. Default: the text. */
+		value?: Snippet<[T]>;
+	};
+</script>
+
+<script lang="ts" generics="T extends KeyValueItem = KeyValueItem">
+	import { onMount, untrack } from 'svelte';
+	import { useMotion } from '../motion/index.js';
+
+	let { items, keyWidth, value, class: className, ...rest }: KeyValueListProps<T> = $props();
+
+	// Expressive stagger (motion rule 7), as in Table: only the items of the
+	// first render enter, by their index. Any change to `items` (a new array
+	// or a changed length) ends the entrance, and so does its last animation.
+	const motion = useMotion();
+	const firstItems = untrack(() => items);
+	const firstCount = untrack(() => items.length);
+	let entering = $state.raw(motion.expressive);
+	let root: HTMLDListElement;
+
+	$effect.pre(() => {
+		if (items !== firstItems || items.length !== firstCount) entering = false;
+	});
+
+	onMount(() => {
+		if (!entering) return;
+		const running = root
+			.getAnimations({ subtree: true })
+			.filter((a) => a instanceof CSSAnimation && a.animationName === 'hp-enter');
+		Promise.allSettled(running.map((a) => a.finished)).then(() => {
+			entering = false;
+		});
+	});
+</script>
+
+<!--
+	A caps label column and a Geist Mono value column, without separators
+	(BRIEF, visual rule 6; da3-53). Compact widths stack each label over its
+	value. Extra attributes and `class` go to the <dl>.
+-->
+<dl
+	{...rest}
+	bind:this={root}
+	class={['hp-key-value-list', className]}
+	style:--key-value-list-key-width={keyWidth}
+>
+	{#each items as item, i}
+		<div class={[entering && 'hp-enter']} style:--i={entering ? i : undefined}>
+			<dt class="hp-label">{item.key}</dt>
+			<dd>{#if value}{@render value(item)}{:else}{item.value}{/if}</dd>
+		</div>
+	{/each}
+</dl>
+
+<style>
+	.hp-key-value-list {
+		display: grid;
+		gap: var(--space-3);
+	}
+	div {
+		display: grid;
+		/* matches the approved specimen */
+		gap: 2px;
+	}
+	dt {
+		color: var(--muted);
+	}
+	/* 16px on touch, the dense 14px on fine pointers. A long identifier or
+	   path breaks anywhere rather than widen the page. */
+	dd {
+		font-family: var(--mono);
+		font-size: var(--type-body);
+		line-height: 24px;
+		overflow-wrap: anywhere;
+	}
+	@media (pointer: fine) {
+		dd {
+			font-size: var(--type-dense);
+			line-height: 20px;
+		}
+	}
+	@media (min-width: 600px) {
+		.hp-key-value-list {
+			gap: var(--space-2);
+		}
+		div {
+			grid-template-columns: var(--key-value-list-key-width, 9rem) minmax(0, 1fr);
+			align-items: baseline;
+			gap: var(--space-4);
+		}
+	}
+</style>

package/dist/components/KeyValueList.svelte.d.ts

@@ -0,0 +1,43 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+export type KeyValueItem = {
+    /** The caps label in the first column. A fixed string the app defines. */
+    key: string;
+    /** The value in Geist Mono. */
+    value: string | number;
+};
+/** Items may carry extra fields (an `href`, a status) that the `value` snippet reads. */
+export type KeyValueListProps<T extends KeyValueItem = KeyValueItem> = Omit<HTMLAttributes<HTMLDListElement>, 'children'> & {
+    items: T[];
+    /**
+     * The label column's width from 600px up: any CSS width. Defaults to
+     * `9rem`. Below 600px the label stacks over the value.
+     */
+    keyWidth?: string;
+    /** Renders one value, for a link or a status. Default: the text. */
+    value?: Snippet<[T]>;
+};
+declare function $$render<T extends KeyValueItem = KeyValueItem>(): {
+    props: KeyValueListProps<T>;
+    exports: {};
+    bindings: "";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<T extends KeyValueItem = KeyValueItem> {
+    props(): ReturnType<typeof $$render<T>>['props'];
+    events(): ReturnType<typeof $$render<T>>['events'];
+    slots(): ReturnType<typeof $$render<T>>['slots'];
+    bindings(): "";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <T extends KeyValueItem = KeyValueItem>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<T>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<T>['props']>, ReturnType<__sveltets_Render<T>['events']>, ReturnType<__sveltets_Render<T>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<T>['bindings']>;
+    } & ReturnType<__sveltets_Render<T>['exports']>;
+    <T extends KeyValueItem = KeyValueItem>(internal: unknown, props: ReturnType<__sveltets_Render<T>['props']> & {}): ReturnType<__sveltets_Render<T>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const KeyValueList: $$IsomorphicComponent;
+type KeyValueList<T extends KeyValueItem = KeyValueItem> = InstanceType<typeof KeyValueList<T>>;
+export default KeyValueList;

package/dist/components/ListDetail.svelte

@@ -0,0 +1,218 @@
+<script lang="ts" module>
+	import type { Snippet } from 'svelte';
+	import type { HTMLAttributes } from 'svelte/elements';
+
+	/** From which width the panes sit side by side: 600px, 900px or 1200px. */
+	export type ListDetailBreakpoint = 'medium' | 'expanded' | 'large';
+
+	/** What the `list` and `detail` snippets receive. */
+	export type ListDetailSnippetProps = {
+		/**
+		 * True below `splitFrom`, where one pane shows at a time. Show the
+		 * detail's back control only then.
+		 */
+		stacked: boolean;
+	};
+
+	export type ListDetailProps = Omit<HTMLAttributes<HTMLDivElement>, 'children'> & {
+		/** The list pane's content: the items, and any filter over them. */
+		list: Snippet<[ListDetailSnippetProps]>;
+		/**
+		 * The detail pane's content: the open item. Side by side with nothing
+		 * open, render an empty state here.
+		 */
+		detail: Snippet<[ListDetailSnippetProps]>;
+		/**
+		 * Which pane shows while stacked: the detail when true, the list when
+		 * false (default). Side by side both show and this changes nothing.
+		 * Bindable.
+		 */
+		showDetail?: boolean;
+		/**
+		 * From which width the panes sit side by side; narrower, one shows at
+		 * a time. Default `expanded` (900px).
+		 */
+		splitFrom?: ListDetailBreakpoint;
+		/** The root element. */
+		ref?: HTMLDivElement | null;
+	};
+</script>
+
+<script lang="ts">
+	import { untrack } from 'svelte';
+	import { MediaQuery } from 'svelte/reactivity';
+
+	let {
+		list,
+		detail,
+		showDetail = $bindable(false),
+		splitFrom = 'expanded',
+		ref = $bindable(null),
+		class: className,
+		...rest
+	}: ListDetailProps = $props();
+
+	// The CSS below lays the panes out from the same widths before any script
+	// runs; this query only tells the snippets and the focus rules.
+	const widths: Record<ListDetailBreakpoint, number> = { medium: 600, expanded: 900, large: 1200 };
+	const split = $derived(new MediaQuery(`min-width: ${widths[splitFrom]}px`, true));
+	const stacked = $derived(!split.current);
+	/** The one pane on screen while stacked; null side by side. */
+	const alone = $derived(stacked ? (showDetail ? 'detail' : 'list') : null);
+
+	let listPane = $state<HTMLDivElement | null>(null);
+	let detailPane = $state<HTMLDivElement | null>(null);
+
+	// ---- The list keeps its place ------------------------------------------
+
+	// A pane that is not shown is display: none, which drops its scroll box.
+	// Some browsers then reset its offset, so the list remembers the offset it
+	// had while it showed and puts it back when it shows again.
+	let listTop = 0;
+	function onListScroll() {
+		if (listPane && listPane.getClientRects().length > 0) listTop = listPane.scrollTop;
+	}
+	$effect(() => {
+		const showsList = alone !== 'detail';
+		untrack(() => {
+			if (showsList && listPane && listPane.scrollTop !== listTop) listPane.scrollTop = listTop;
+		});
+	});
+
+	// ---- Focus follows the pane that shows ---------------------------------
+
+	// When the stacked view switches panes, the app's own update runs first:
+	// the check waits a task, past the app's effects and an `await tick()`,
+	// so an app that focuses a title, an input or the item that was open
+	// keeps that focus. Only if focus is then outside the pane on screen
+	// does the pane itself take it. When the window narrows to one pane,
+	// focus moves only if the pane that hid held it. Side by side the app
+	// owns focus. A new switch before the check cancels it.
+	let before: 'list' | 'detail' | null | undefined;
+	$effect(() => {
+		const now = alone;
+		return untrack(() => {
+			const was = before;
+			before = now;
+			if (was === undefined || now === null || was === now) return;
+			const shown = now === 'list' ? listPane : detailPane;
+			const hidden = now === 'list' ? detailPane : listPane;
+			const timer = setTimeout(() => {
+				if (!shown) return;
+				const active = document.activeElement;
+				if (active && shown.contains(active)) return;
+				const lost = !active || active === document.body || !!hidden?.contains(active);
+				if (was === null && !lost) return;
+				shown.focus({ preventScroll: true });
+			});
+			return () => clearTimeout(timer);
+		});
+	});
+</script>
+
+<!--
+	The list-detail layout: a list of items beside the open item. From
+	`splitFrom` (900px by default) the list is a column of
+	`--list-detail-width` at the left and the detail fills the rest; below
+	it the two are separate screens and `showDetail` picks the one that
+	shows. The other pane stays mounted, out of the layout, the
+	accessibility tree and the tab order, so its state and the list's scroll
+	position survive. Switching cuts, as page changes do (motion rule 1).
+
+	The root fills the height its container gives it, or
+	`--list-detail-height`; each pane scrolls inside itself. The panes pad
+	their content by `--gutter`, and the root keeps the side safe areas, so
+	the layout is built to reach the window's edges under the app's header.
+	No frame and no divider: the gutters between the panes group them.
+
+	Extra attributes and `class` go to the root, `div.hp-list-detail`, which
+	carries `data-split-from`, `data-stacked` (below `splitFrom`) and
+	`data-show-detail`. The panes are `div.hp-list-detail-list` and
+	`div.hp-list-detail-detail`, each with `tabindex="-1"`.
+-->
+<div
+	{...rest}
+	bind:this={ref}
+	class={['hp-list-detail', className]}
+	data-split-from={splitFrom}
+	data-stacked={stacked || undefined}
+	data-show-detail={showDetail || undefined}
+>
+	<div bind:this={listPane} class="pane hp-list-detail-list" tabindex="-1" onscroll={onListScroll}>
+		{@render list({ stacked })}
+	</div>
+	<div bind:this={detailPane} class="pane hp-list-detail-detail" tabindex="-1">
+		{@render detail({ stacked })}
+	</div>
+</div>
+
+<style>
+	/* A row of two panes. The side safe areas sit outside them, so a tint
+	   that reaches into a gutter stops short of a notch. min-height: 0 lets
+	   the root shrink as a flex or grid item. */
+	.hp-list-detail {
+		display: flex;
+		box-sizing: border-box;
+		height: var(--list-detail-height, 100%);
+		min-height: 0;
+		padding: 0 env(safe-area-inset-right) 0 env(safe-area-inset-left);
+	}
+
+	/* Each pane is a scroller of its own. The page edges come from
+	   --gutter, as everywhere; the bottom safe area keeps the last item
+	   clear of the home indicator. A stable scrollbar gutter keeps the
+	   content still when filtering or a new item changes whether a pane
+	   overflows. */
+	.pane {
+		flex: 1 1 0;
+		min-width: 0;
+		box-sizing: border-box;
+		padding: var(--space-4) var(--gutter) calc(var(--space-4) + env(safe-area-inset-bottom));
+		overflow-y: auto;
+		overscroll-behavior: contain;
+		scrollbar-gutter: stable;
+	}
+	/* Focus lands on a pane only from the switch above, as <main> takes it
+	   from a skip link: no contour, since the pane is not a control. */
+	.pane:focus {
+		outline: none;
+	}
+
+	/* ---- Stacked: one pane at a time --------------------------------- */
+
+	.hp-list-detail[data-show-detail] > .hp-list-detail-list,
+	.hp-list-detail:not([data-show-detail]) > .hp-list-detail-detail {
+		display: none;
+	}
+
+	/* ---- Side by side: from splitFrom -------------------------------- */
+
+	/* Later and as specific as the rules above, so both panes show. */
+	@media (min-width: 600px) {
+		.hp-list-detail[data-split-from='medium'] > .pane {
+			display: block;
+		}
+		.hp-list-detail[data-split-from='medium'] > .hp-list-detail-list {
+			flex: none;
+			width: var(--list-detail-width);
+		}
+	}
+	@media (min-width: 900px) {
+		.hp-list-detail[data-split-from='expanded'] > .pane {
+			display: block;
+		}
+		.hp-list-detail[data-split-from='expanded'] > .hp-list-detail-list {
+			flex: none;
+			width: var(--list-detail-width);
+		}
+	}
+	@media (min-width: 1200px) {
+		.hp-list-detail[data-split-from='large'] > .pane {
+			display: block;
+		}
+		.hp-list-detail[data-split-from='large'] > .hp-list-detail-list {
+			flex: none;
+			width: var(--list-detail-width);
+		}
+	}
+</style>

package/dist/components/ListDetail.svelte.d.ts

@@ -0,0 +1,37 @@
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+/** From which width the panes sit side by side: 600px, 900px or 1200px. */
+export type ListDetailBreakpoint = 'medium' | 'expanded' | 'large';
+/** What the `list` and `detail` snippets receive. */
+export type ListDetailSnippetProps = {
+    /**
+     * True below `splitFrom`, where one pane shows at a time. Show the
+     * detail's back control only then.
+     */
+    stacked: boolean;
+};
+export type ListDetailProps = Omit<HTMLAttributes<HTMLDivElement>, 'children'> & {
+    /** The list pane's content: the items, and any filter over them. */
+    list: Snippet<[ListDetailSnippetProps]>;
+    /**
+     * The detail pane's content: the open item. Side by side with nothing
+     * open, render an empty state here.
+     */
+    detail: Snippet<[ListDetailSnippetProps]>;
+    /**
+     * Which pane shows while stacked: the detail when true, the list when
+     * false (default). Side by side both show and this changes nothing.
+     * Bindable.
+     */
+    showDetail?: boolean;
+    /**
+     * From which width the panes sit side by side; narrower, one shows at
+     * a time. Default `expanded` (900px).
+     */
+    splitFrom?: ListDetailBreakpoint;
+    /** The root element. */
+    ref?: HTMLDivElement | null;
+};
+declare const ListDetail: import("svelte").Component<ListDetailProps, {}, "ref" | "showDetail">;
+type ListDetail = ReturnType<typeof ListDetail>;
+export default ListDetail;

package/dist/components/LoadRegion.svelte

@@ -0,0 +1,219 @@
+<script lang="ts" module>
+	import type { Snippet } from 'svelte';
+	import type { HTMLAttributes } from 'svelte/elements';
+
+	export type LoadRegionProps = Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'placeholder'> & {
+		/** True while the content loads: the region shows `placeholder` and is `aria-busy`. */
+		loading: boolean;
+		/**
+		 * The text of the status line, such as `Loading tasks`, then `5 tasks`.
+		 * The line is visually hidden, stays mounted outside the region and is
+		 * a `role="status"` region, so each change is announced. Leave it empty
+		 * while an error state announces itself.
+		 */
+		status: string;
+		/**
+		 * The skeleton layout shown while loading, rendered inside an
+		 * `aria-hidden`, `inert` wrapper. Give it the content's own layout
+		 * container: during a reveal it lies under the content in a box of its
+		 * own, so a grid or gap set on the region would not reach it.
+		 */
+		placeholder: Snippet;
+		/** The content, and also any empty or error state. */
+		children: Snippet;
+		/** The region element. A page moves focus here when the content replaces the focused control. */
+		ref?: HTMLDivElement | null;
+	};
+</script>
+
+<script lang="ts">
+	import { untrack } from 'svelte';
+	import { duration } from '../motion/transitions.js';
+
+	let {
+		loading,
+		status,
+		placeholder,
+		children,
+		ref = $bindable(null),
+		class: className,
+		...rest
+	}: LoadRegionProps = $props();
+
+	// ---- Reveal (BRIEF, motion rule 2) -------------------------------------
+
+	// When a load ends after its skeletons became visible and --dur-reveal is
+	// more than 0ms, the content crossfades in over the skeletons for
+	// --dur-reveal on --settle. The placeholder stays mounted under the
+	// content, unchanged. The content lies on top on an opaque backdrop (the
+	// colour behind the region) and fades in from 0, so every pixel moves in
+	// a straight line from the placeholder's to the content's: a bar turns
+	// into its text, and a part drawn the same in both layers (a tag, a
+	// label, a table's band) does not change at all. Then the placeholder
+	// goes. At 0ms, for a load that ends within --skeleton-delay, on the
+	// first render and for any change that is not a load ending, the content
+	// replaces the placeholder in one frame. Opacity only: the skeletons
+	// mirror the layout, so nothing moves. Quiet motion, so it runs in both
+	// tiers; it is only a fade, so reduced motion keeps it.
+
+	type Phase = 'loading' | 'reveal' | 'content';
+	let phase = $state<Phase>(untrack(() => (loading ? 'loading' : 'content')));
+	// Counts loads. A new load remounts the placeholder, so its skeletons
+	// wait out --skeleton-delay again, also when it cuts a reveal short.
+	let load = $state(0);
+
+	/** When the running load began, or null between loads. */
+	let began: number | null = untrack(() => (loading ? performance.now() : null));
+	/** --skeleton-delay when the load began, as the skeletons read it; null until read. */
+	let delay: number | null = null;
+	/** The running reveal's timing, read from the region when the load ended. */
+	let timing: KeyframeAnimationOptions = {};
+
+	// Before the DOM update, so a reveal keeps the placeholder mounted (its
+	// skeletons stay visible) while the content mounts on top. Only `loading`
+	// is tracked.
+	$effect.pre(() => {
+		const busy = loading;
+		untrack(() => {
+			const node = ref;
+			if (busy) {
+				if (phase !== 'loading') {
+					began = performance.now();
+					delay = node ? duration(node, '--skeleton-delay') : null;
+					load += 1;
+					phase = 'loading';
+				}
+				return;
+			}
+			if (phase !== 'loading') return;
+			const elapsed = began === null ? -1 : performance.now() - began;
+			began = null;
+			// Read now, so a token retuned during the load applies.
+			const ms = node ? duration(node, '--dur-reveal') : 0;
+			const wait = delay ?? (node ? duration(node, '--skeleton-delay') : 0);
+			if (!node || ms <= 0 || elapsed < wait) {
+				phase = 'content';
+				return;
+			}
+			const settle = getComputedStyle(node).getPropertyValue('--settle').trim();
+			timing = {
+				duration: ms,
+				easing: CSS.supports('transition-timing-function', settle) ? settle : 'ease-out'
+			};
+			phase = 'reveal';
+		});
+	});
+
+	/** The solid colour behind `node`: the first background colour up the tree that is not transparent. */
+	function backdrop(node: Element): string {
+		for (let el: Element | null = node; el; el = el.parentElement) {
+			const colour = getComputedStyle(el).backgroundColor;
+			// Transparent is `rgba(…, 0)`, or `… / 0)` in the newer colour syntaxes.
+			if (colour !== 'transparent' && !/^rgba\(.*,\s*0\)$|\/\s*0\)$/.test(colour)) return colour;
+		}
+		// Nothing paints: the browser's canvas shows through.
+		return 'Canvas';
+	}
+
+	// After the DOM update, in the same flush, so the content's first frame
+	// is already at opacity 0. The cleanup cancels the fade when a new load
+	// starts or the region goes away.
+	$effect(() => {
+		if (phase !== 'reveal') return;
+		return untrack(() => {
+			const node = ref;
+			const content = node?.querySelector<HTMLElement>(':scope > .hp-load-region-content');
+			if (!node || !content) {
+				phase = 'content';
+				return;
+			}
+			content.style.backgroundColor = backdrop(node);
+			const fade = content.animate([{ opacity: 0 }, { opacity: 1 }], timing);
+			fade.onfinish = () => (phase = 'content');
+			return () => {
+				fade.cancel();
+				content.style.removeProperty('background-color');
+			};
+		});
+	});
+</script>
+
+<!--
+	A region that loads (BRIEF, motion rule 2): skeleton blocks while the
+	content loads, then the content. It owns the loading pattern of the
+	states docs: a visually hidden `role="status"` line before the region
+	that stays mounted, `aria-busy` on the region while `loading`, and the
+	`placeholder` in an `aria-hidden`, `inert` wrapper. When a load that
+	showed skeletons ends and `--dur-reveal` is more than 0ms, the content
+	crossfades in over the skeletons; see the script. Both layers are
+	`display: contents` at rest, so they add no box. During a reveal the
+	region is `position: relative`, the placeholder lies under the content
+	(`position: absolute; inset: 0`) and the content is a block on the
+	colour behind the region, so keep the region's own layout inside the
+	snippets and give their roots no outer margin. Focus is the page's job:
+	when the content replaces the focused control, the page moves focus to
+	`ref` or to the control needed next. Extra attributes and `class` go to
+	the region, `div.hp-load-region` (`tabindex="-1"`), which carries
+	`data-revealing` during a reveal.
+-->
+<p class="hp-visually-hidden" role="status">{status}</p>
+<div
+	{...rest}
+	bind:this={ref}
+	class={['hp-load-region', className]}
+	tabindex="-1"
+	aria-busy={loading}
+	data-revealing={phase === 'reveal' ? '' : undefined}
+>
+	{#key load}
+		{#if phase !== 'content'}
+			<div class="hp-load-region-placeholder" aria-hidden="true" inert>
+				{@render placeholder()}
+			</div>
+		{/if}
+	{/key}
+	{#if !loading}
+		<div class="hp-load-region-content">
+			{@render children()}
+		</div>
+	{/if}
+</div>
+
+<style>
+	/* Focus lands here only from the page's own code, when the content
+	   replaces the focused control, as <main> takes it from the skip link:
+	   no contour, since the region is not a control. */
+	.hp-load-region:focus {
+		outline: none;
+	}
+	/* At rest neither layer adds a box. */
+	.hp-load-region-placeholder,
+	.hp-load-region-content {
+		display: contents;
+	}
+
+	/* ---- Reveal: the content over the placeholder ------------------------ */
+
+	.hp-load-region[data-revealing] {
+		position: relative;
+	}
+	/* Under the content, over the content's area. Its own stacking context
+	   keeps a sticky table band (z-index) under the content too. Taller
+	   placeholder rows are cut at the region's bottom edge; a band's bleed
+	   into the gutter stays. */
+	.hp-load-region[data-revealing] > .hp-load-region-placeholder {
+		display: block;
+		position: absolute;
+		inset: 0;
+		isolation: isolate;
+		overflow-x: visible;
+		overflow-y: clip;
+	}
+	/* A box for the fade, painted after the placeholder. The script gives it
+	   the colour behind the region, so it covers the placeholder as it fades
+	   in. */
+	.hp-load-region[data-revealing] > .hp-load-region-content {
+		display: block;
+		position: relative;
+	}
+</style>