@poodle64/ui 2026.10.17 → 2026.10.18

package/dist/components/ui/document-reader/document-reader.svelte

@@ -0,0 +1,336 @@
+<script lang="ts" module>
+	/** One heading of the body, as the contents list shows it. */
+	export type DocumentReaderHeading = { id: string; text: string; level: 2 | 3 };
+
+	/** A heading's id from its text: lower case, words joined by hyphens. */
+	export function slugify(text: string): string {
+		return (
+			text
+				.toLowerCase()
+				.normalize('NFKD')
+				.replace(/[̀-ͯ]/g, '')
+				.replace(/[^a-z0-9]+/g, '-')
+				.replace(/^-+|-+$/g, '') || 'section'
+		);
+	}
+</script>
+
+<script lang="ts">
+	/**
+	 * A document to read: its title and trail, the body at a reading measure,
+	 * and a contents list built from the body's own headings.
+	 *
+	 * One app had built this for four routes and read its library documents
+	 * through a second shell, a DocumentDetail with the body in a box under it.
+	 * DocumentDetail stays the catalogue record of a document; when there is a
+	 * body to read, this is where it is read, and the record's facts go in
+	 * `aside` or `meta`.
+	 *
+	 * The body is HTML the app has already rendered and sanitised (`html`), or
+	 * markup (`children`). The package styles it with `.ds-prose` and never
+	 * renders markdown itself, for the reason `.ds-prose` gives: sanitising is
+	 * a security boundary the package cannot see the inputs of.
+	 *
+	 * The contents list is the body's `h2` and `h3`. A heading with no id is
+	 * given one from its text, so an app's markdown pipeline needs no heading-id
+	 * plugin. A link scrolls to its heading directly rather than through the
+	 * URL fragment, because a fragment cannot find an element inside a shadow
+	 * root, and this reader appears inside elements too.
+	 *
+	 * It centres itself and carries its own measure, so its route's `measure`
+	 * only needs to leave room: `page` or wider shows the contents beside the
+	 * body, and the shift from beside to above is a container query on the
+	 * reader's own width, not the window's.
+	 */
+	import { untrack, type Snippet } from 'svelte';
+	import type { HTMLAttributes } from 'svelte/elements';
+	import ChevronRight from '@lucide/svelte/icons/chevron-right';
+	import { cn, type WithElementRef } from '../../../utils.js';
+	import Button from '../button/button.svelte';
+	import PageHeader from '../page-header/page-header.svelte';
+	import type { BreadcrumbItem } from '../breadcrumbs/breadcrumbs.svelte';
+	import ContentSkeleton from '../content-skeleton/content-skeleton.svelte';
+	import ErrorState from '../error-state/error-state.svelte';
+	import LoadingState from '../loading-state/loading-state.svelte';
+
+	let {
+		title,
+		subtitle,
+		breadcrumbs,
+		meta,
+		actions,
+		html,
+		children,
+		contents = true,
+		contentsLabel = 'On this page',
+		aside,
+		footer,
+		loading = false,
+		error = null,
+		onRetry,
+		ref = $bindable(null),
+		class: className,
+		...restProps
+	}: Omit<WithElementRef<HTMLAttributes<HTMLDivElement>>, 'title' | 'children'> & {
+		/** The document's title, as the page's heading. */
+		title?: string;
+		subtitle?: string;
+		breadcrumbs?: BreadcrumbItem[];
+		/** Facts about the document under its title: a date, a reading time, a status. */
+		meta?: Snippet;
+		actions?: Snippet;
+		/** The body, rendered and sanitised by the app. */
+		html?: string;
+		/** The body as markup, instead of `html`. */
+		children?: Snippet;
+		/** Show the contents list once the body has two headings or more. */
+		contents?: boolean;
+		contentsLabel?: string;
+		/** More for the side column, under the contents: the document's catalogue facts. */
+		aside?: Snippet;
+		/** After the body: what to read next, a completion control, related documents. */
+		footer?: Snippet;
+		/** The body is loading. With a `title` the header stands and the body is a skeleton. */
+		loading?: boolean;
+		error?: string | null;
+		onRetry?: () => void;
+	} = $props();
+
+	let article = $state<HTMLElement | null>(null);
+	let disclosure = $state<HTMLDetailsElement | null>(null);
+	let headings = $state<DocumentReaderHeading[]>([]);
+	let read = $state(false);
+	let active = $state<string | null>(null);
+
+	const showContents = $derived(contents && headings.length >= 2);
+	// The column is held while the body loads and until its headings are read
+	// (before the first paint), so a structured document never moves sideways
+	// as it arrives; one with fewer than two headings gives the room back.
+	const side = $derived(!!aside || (contents && (loading || !read || headings.length >= 2)));
+
+	/** Give every h2 and h3 an id, and read the list. */
+	function readHeadings(root: HTMLElement): DocumentReaderHeading[] {
+		const scope = root.getRootNode() as Document | ShadowRoot;
+		const taken = new Set<string>();
+		const found: DocumentReaderHeading[] = [];
+		const free = (id: string, el: HTMLElement) =>
+			!taken.has(id) && [null, el].includes(scope.getElementById(id) as HTMLElement | null);
+		for (const el of root.querySelectorAll<HTMLElement>('h2, h3')) {
+			let id = el.id;
+			if (!id || taken.has(id)) {
+				const base = slugify(el.textContent ?? '');
+				id = base;
+				for (let n = 2; !free(id, el); n++) id = `${base}-${n}`;
+				el.id = id;
+			}
+			taken.add(id);
+			found.push({ id, text: (el.textContent ?? '').trim(), level: el.tagName === 'H2' ? 2 : 3 });
+		}
+		return found;
+	}
+
+	const same = (a: DocumentReaderHeading[], b: DocumentReaderHeading[]) =>
+		a.length === b.length &&
+		a.every((h, i) => h.id === b[i]?.id && h.text === b[i]?.text && h.level === b[i]?.level);
+
+	// A link that named a heading: the router scrolled before the body existed,
+	// so the reader scrolls once the heading does. A fragment that is not valid
+	// percent-encoding names nothing.
+	let hashSought = false;
+	function seekHash(root: HTMLElement) {
+		if (hashSought) return;
+		let id = '';
+		try {
+			id = decodeURIComponent(window.location.hash.slice(1));
+		} catch {
+			hashSought = true;
+			return;
+		}
+		const el = id ? root.querySelector<HTMLElement>(`#${CSS.escape(id)}`) : null;
+		if (el) el.scrollIntoView({ block: 'start' });
+		hashSought = !id || !!el;
+	}
+
+	// The body changes when `html` does, or when the app's own markup does; a
+	// MutationObserver sees both. Attributes are not observed, so giving a
+	// heading its id does not re-run this, and a change that leaves the
+	// headings as they were leaves the list alone.
+	$effect(() => {
+		const root = article;
+		if (!root) return;
+		const update = () => {
+			const found = readHeadings(root);
+			if (!same(found, untrack(() => headings))) headings = found;
+			read = true;
+			seekHash(root);
+		};
+		update();
+		const observer = new MutationObserver(update);
+		observer.observe(root, { childList: true, subtree: true, characterData: true });
+		return () => observer.disconnect();
+	});
+
+	// The heading being read: the last one whose top has passed a line a little
+	// below the top of whatever scrolls. Scroll does not bubble but is captured
+	// at the window from any scroller in the page, and at the shadow root from
+	// one inside an element, which the window never hears. A link's own jump
+	// holds its heading for the length of the scroll it starts.
+	const READING_LINE = 96;
+	let heldUntil = 0;
+	$effect(() => {
+		const list = headings;
+		const root = article;
+		if (!root || list.length < 2) return;
+		const scopes: EventTarget[] = [window];
+		const shadow = root.getRootNode();
+		if (shadow instanceof ShadowRoot) scopes.push(shadow);
+		let frame = 0;
+		const update = () => {
+			frame = 0;
+			if (performance.now() < heldUntil) return;
+			let current: string | null = list[0]?.id ?? null;
+			for (const { id } of list) {
+				const el = root.querySelector<HTMLElement>(`#${CSS.escape(id)}`);
+				if (el && el.getBoundingClientRect().top <= READING_LINE) current = id;
+				else break;
+			}
+			active = current;
+		};
+		const onScroll = () => {
+			if (!frame) frame = requestAnimationFrame(update);
+		};
+		update();
+		for (const scope of scopes) scope.addEventListener('scroll', onScroll, { capture: true, passive: true });
+		return () => {
+			for (const scope of scopes) scope.removeEventListener('scroll', onScroll, { capture: true });
+			if (frame) cancelAnimationFrame(frame);
+		};
+	});
+
+	function go(event: MouseEvent, id: string) {
+		const el = article?.querySelector<HTMLElement>(`#${CSS.escape(id)}`);
+		if (!el) return;
+		event.preventDefault();
+		const still = window.matchMedia?.('(prefers-reduced-motion: reduce)').matches;
+		heldUntil = performance.now() + (still ? 0 : 800);
+		if (disclosure) disclosure.open = false;
+		el.scrollIntoView({ block: 'start', behavior: still ? 'auto' : 'smooth' });
+		// Move focus with the view, so the next Tab continues from the heading.
+		if (!el.hasAttribute('tabindex')) el.setAttribute('tabindex', '-1');
+		el.focus({ preventScroll: true });
+		active = id;
+	}
+</script>
+
+{#snippet contentsList()}
+	<nav aria-label={contentsLabel}>
+		<ul class="border-border flex flex-col border-l text-sm">
+			{#each headings as heading (heading.id)}
+				<li>
+					<a
+						href={`#${heading.id}`}
+						onclick={(event) => go(event, heading.id)}
+						aria-current={active === heading.id ? 'location' : undefined}
+						class={cn(
+							'focus-visible:ring-ring/50 -ml-px block border-l-2 border-transparent py-1 pr-2 leading-snug outline-none focus-visible:ring-3',
+							heading.level === 2 ? 'pl-3' : 'pl-6',
+							active === heading.id
+								? 'border-primary text-foreground font-medium'
+								: 'text-muted-foreground hover:text-foreground'
+						)}>{heading.text}</a
+					>
+				</li>
+			{/each}
+		</ul>
+	</nav>
+{/snippet}
+
+<div
+	bind:this={ref}
+	data-slot="document-reader"
+	class={cn('@container w-full text-base', className)}
+	{...restProps}
+>
+	{#if error}
+		<ErrorState message={error}>
+			{#snippet action()}
+				{#if onRetry}
+					<Button variant="outline" onclick={onRetry}>Retry</Button>
+				{/if}
+			{/snippet}
+		</ErrorState>
+	{:else if loading && !title}
+		<LoadingState message="Loading the document…" />
+	{:else}
+		<div
+			class={cn(
+				'mx-auto w-full max-w-(--ds-shell-measure-prose)',
+				side && '@5xl:max-w-[calc(var(--ds-shell-measure-prose)+16.5rem)]'
+			)}
+		>
+			{#if title || breadcrumbs?.length || meta || actions}
+				<PageHeader {title} {subtitle} {breadcrumbs} {meta} {actions} />
+			{/if}
+			{#if loading}
+				<ContentSkeleton shape="prose" label="Loading the document…" />
+			{:else}
+				<!-- One column, then two from 64rem of reader. The side column is
+				     rendered once: below 64rem it follows the body and shows only
+				     `aside`, since the contents fold into the disclosure above. -->
+				<div class="flex flex-col @5xl:flex-row @5xl:items-start @5xl:gap-10">
+					<div class="min-w-0 flex-1">
+						{#if showContents}
+							<details
+								bind:this={disclosure}
+								class="group bg-card border-border ds-edge mb-6 rounded-lg border @5xl:hidden"
+							>
+								<summary
+									class="focus-visible:ring-ring/50 flex cursor-pointer list-none items-center gap-2 rounded-lg px-3 py-2 text-sm font-medium outline-none focus-visible:ring-3 [&::-webkit-details-marker]:hidden"
+								>
+									<ChevronRight
+										class="text-muted-foreground size-4 transition-transform group-open:rotate-90"
+										aria-hidden="true"
+									/>
+									{contentsLabel}
+								</summary>
+								<div class="px-3 pb-3">{@render contentsList()}</div>
+							</details>
+						{/if}
+						<article
+							bind:this={article}
+							class="ds-prose ds-measure [&_:is(h2,h3)]:scroll-mt-4 [&_:is(h2,h3)]:outline-none"
+							data-measure="prose"
+						>
+							{#if html !== undefined}
+								{@html html}
+							{:else}
+								{@render children?.()}
+							{/if}
+						</article>
+					</div>
+					{#if side}
+						<div
+							data-slot="document-reader-side"
+							class="flex flex-col gap-8 @5xl:sticky @5xl:top-4 @5xl:max-h-[calc(100dvh-6rem)] @5xl:w-56 @5xl:shrink-0 @5xl:overflow-y-auto"
+						>
+							{#if showContents}
+								<div class="hidden flex-col gap-2 @5xl:flex">
+									<p class="text-sm font-medium" aria-hidden="true">{contentsLabel}</p>
+									{@render contentsList()}
+								</div>
+							{/if}
+							{#if aside}
+								<div class="mt-10 @5xl:mt-0">{@render aside()}</div>
+							{/if}
+						</div>
+					{/if}
+				</div>
+				{#if footer}
+					<div class="ds-measure border-border mt-12 border-t pt-6" data-measure="prose">
+						{@render footer()}
+					</div>
+				{/if}
+			{/if}
+		</div>
+	{/if}
+</div>

package/dist/components/ui/document-reader/document-reader.svelte.d.ts

@@ -0,0 +1,65 @@
+/** One heading of the body, as the contents list shows it. */
+export type DocumentReaderHeading = {
+    id: string;
+    text: string;
+    level: 2 | 3;
+};
+/** A heading's id from its text: lower case, words joined by hyphens. */
+export declare function slugify(text: string): string;
+/**
+     * A document to read: its title and trail, the body at a reading measure,
+     * and a contents list built from the body's own headings.
+     *
+     * One app had built this for four routes and read its library documents
+     * through a second shell, a DocumentDetail with the body in a box under it.
+     * DocumentDetail stays the catalogue record of a document; when there is a
+     * body to read, this is where it is read, and the record's facts go in
+     * `aside` or `meta`.
+     *
+     * The body is HTML the app has already rendered and sanitised (`html`), or
+     * markup (`children`). The package styles it with `.ds-prose` and never
+     * renders markdown itself, for the reason `.ds-prose` gives: sanitising is
+     * a security boundary the package cannot see the inputs of.
+     *
+     * The contents list is the body's `h2` and `h3`. A heading with no id is
+     * given one from its text, so an app's markdown pipeline needs no heading-id
+     * plugin. A link scrolls to its heading directly rather than through the
+     * URL fragment, because a fragment cannot find an element inside a shadow
+     * root, and this reader appears inside elements too.
+     *
+     * It centres itself and carries its own measure, so its route's `measure`
+     * only needs to leave room: `page` or wider shows the contents beside the
+     * body, and the shift from beside to above is a container query on the
+     * reader's own width, not the window's.
+     */
+import { type Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+import { type WithElementRef } from '../../../utils.js';
+import type { BreadcrumbItem } from '../breadcrumbs/breadcrumbs.svelte';
+type $$ComponentProps = Omit<WithElementRef<HTMLAttributes<HTMLDivElement>>, 'title' | 'children'> & {
+    /** The document's title, as the page's heading. */
+    title?: string;
+    subtitle?: string;
+    breadcrumbs?: BreadcrumbItem[];
+    /** Facts about the document under its title: a date, a reading time, a status. */
+    meta?: Snippet;
+    actions?: Snippet;
+    /** The body, rendered and sanitised by the app. */
+    html?: string;
+    /** The body as markup, instead of `html`. */
+    children?: Snippet;
+    /** Show the contents list once the body has two headings or more. */
+    contents?: boolean;
+    contentsLabel?: string;
+    /** More for the side column, under the contents: the document's catalogue facts. */
+    aside?: Snippet;
+    /** After the body: what to read next, a completion control, related documents. */
+    footer?: Snippet;
+    /** The body is loading. With a `title` the header stands and the body is a skeleton. */
+    loading?: boolean;
+    error?: string | null;
+    onRetry?: () => void;
+};
+declare const DocumentReader: import("svelte").Component<$$ComponentProps, {}, "ref">;
+type DocumentReader = ReturnType<typeof DocumentReader>;
+export default DocumentReader;

package/dist/components/ui/document-reader/index.d.ts

@@ -0,0 +1,2 @@
+export { default as DocumentReader, slugify, type DocumentReaderHeading } from './document-reader.svelte';
+export { default } from './document-reader.svelte';

package/dist/components/ui/document-reader/index.js

@@ -0,0 +1,2 @@
+export { default as DocumentReader, slugify } from './document-reader.svelte';
+export { default } from './document-reader.svelte';

package/dist/components/ui/page-container/index.d.ts

@@ -0,0 +1,2 @@
+export { default as PageContainer } from './page-container.svelte';
+export { default } from './page-container.svelte';

package/dist/components/ui/page-container/index.js

@@ -0,0 +1,2 @@
+export { default as PageContainer } from './page-container.svelte';
+export { default } from './page-container.svelte';

package/dist/components/ui/page-container/page-container.svelte

@@ -0,0 +1,39 @@
+<script lang="ts">
+	/**
+	 * A route's page: its header, sections and panels stacked at the one page
+	 * rhythm. Pages had written that wrapper per file (`space-y-6`, `space-y-10`,
+	 * `gap-4`, `gap-5`, `gap-10` in one app; a local PageContainer behind 56
+	 * call sites in another).
+	 *
+	 * Width is not this component's: AppShell caps the content box from the
+	 * route's `measure`, which a route declares in its load data. The container
+	 * fills that box and grows to its height, so a page holding a board or a
+	 * table can scroll inside itself.
+	 *
+	 * PageHeader carries its own bottom margin for pages written without this;
+	 * inside it the gap alone spaces the header, so the header sits at the same
+	 * distance either way.
+	 */
+	import type { Snippet } from 'svelte';
+	import type { HTMLAttributes } from 'svelte/elements';
+	import { cn, type WithElementRef } from '../../../utils.js';
+
+	let {
+		children,
+		ref = $bindable(null),
+		class: className,
+		...restProps
+	}: WithElementRef<HTMLAttributes<HTMLDivElement>> & { children: Snippet } = $props();
+</script>
+
+<div
+	bind:this={ref}
+	data-slot="page-container"
+	class={cn(
+		'flex min-h-0 w-full min-w-0 flex-1 flex-col gap-6 *:data-[slot=page-header]:mb-0',
+		className
+	)}
+	{...restProps}
+>
+	{@render children()}
+</div>

package/dist/components/ui/page-container/page-container.svelte.d.ts

@@ -0,0 +1,24 @@
+/**
+     * A route's page: its header, sections and panels stacked at the one page
+     * rhythm. Pages had written that wrapper per file (`space-y-6`, `space-y-10`,
+     * `gap-4`, `gap-5`, `gap-10` in one app; a local PageContainer behind 56
+     * call sites in another).
+     *
+     * Width is not this component's: AppShell caps the content box from the
+     * route's `measure`, which a route declares in its load data. The container
+     * fills that box and grows to its height, so a page holding a board or a
+     * table can scroll inside itself.
+     *
+     * PageHeader carries its own bottom margin for pages written without this;
+     * inside it the gap alone spaces the header, so the header sits at the same
+     * distance either way.
+     */
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+import { type WithElementRef } from '../../../utils.js';
+type $$ComponentProps = WithElementRef<HTMLAttributes<HTMLDivElement>> & {
+    children: Snippet;
+};
+declare const PageContainer: import("svelte").Component<$$ComponentProps, {}, "ref">;
+type PageContainer = ReturnType<typeof PageContainer>;
+export default PageContainer;

package/dist/components/ui/page-header/page-header.svelte

@@ -3,6 +3,7 @@
 	import type { HTMLAttributes } from 'svelte/elements';
 	import { cn, type WithElementRef } from '../../../utils.js';
 	import InfoTip from '../info-tip/info-tip.svelte';
+	import Breadcrumbs, { type BreadcrumbItem } from '../breadcrumbs/breadcrumbs.svelte';
 
 	/**
 	 * The one page-title pattern for every route. `subtitle` is a short, single
@@ -23,10 +24,11 @@
 	 * the drift this package exists to end. One component, one spacing rhythm,
 	 * two shapes.
 	 *
-	 * The trail itself stays the app's, as a snippet: a breadcrumb trail is made
-	 * of routed links, and a package with no SvelteKit runtime of its own cannot
-	 * own those (the same reasoning that makes AppShell take `currentPath` as a
-	 * prop rather than importing `$app/state`).
+	 * The trail is a list of steps (`BreadcrumbItem[]`), drawn by Breadcrumbs.
+	 * A snippet is still accepted for a trail that is not a list of links (a
+	 * record switcher in the trail's place), but a list is the default: three
+	 * apps wrote the same chevron trail by hand, one behind a 28-call-site
+	 * wrapper that existed only to turn this snippet into an array.
 	 *
 	 * `icon` and `meta` are snippets for the same reason and earn their place the
 	 * same way `breadcrumbs` did: three apps had hand-rolled the meta row and two
@@ -50,8 +52,8 @@
 	}: WithElementRef<HTMLAttributes<HTMLDivElement>> & {
 		/** A short kicker above the title. Use this OR `breadcrumbs`, not both. */
 		eyebrow?: string;
-		/** The trail above the title — the app's own routed links. */
-		breadcrumbs?: Snippet;
+		/** The trail above the title: its steps, or a snippet for a trail that is not links. */
+		breadcrumbs?: BreadcrumbItem[] | Snippet;
 		/** The glyph alone. The tinted square around it is this component's. */
 		icon?: Snippet;
 		/** Omit for a header that is a breadcrumb bar with actions. */
@@ -66,6 +68,7 @@
 
 <div
 	bind:this={ref}
+	data-slot="page-header"
 	class={cn('mb-6 flex flex-wrap items-start justify-between gap-4', className)}
 	{...restProps}
 >
@@ -83,10 +86,12 @@
 			</span>
 		{/if}
 		<div class="min-w-0">
-			{#if breadcrumbs}
+			{#if typeof breadcrumbs === 'function'}
 				<div class="text-muted-foreground mb-1.5 flex min-w-0 items-center text-sm">
 					{@render breadcrumbs()}
 				</div>
+			{:else if breadcrumbs?.length}
+				<Breadcrumbs items={breadcrumbs} class="mb-1.5" />
 			{/if}
 			{#if eyebrow}
 				<div class="text-primary text-2xs tracking-eyebrow mb-1 font-medium uppercase">

package/dist/components/ui/page-header/page-header.svelte.d.ts

@@ -1,11 +1,12 @@
 import type { Snippet } from 'svelte';
 import type { HTMLAttributes } from 'svelte/elements';
 import { type WithElementRef } from '../../../utils.js';
+import { type BreadcrumbItem } from '../breadcrumbs/breadcrumbs.svelte';
 type $$ComponentProps = WithElementRef<HTMLAttributes<HTMLDivElement>> & {
     /** A short kicker above the title. Use this OR `breadcrumbs`, not both. */
     eyebrow?: string;
-    /** The trail above the title — the app's own routed links. */
-    breadcrumbs?: Snippet;
+    /** The trail above the title: its steps, or a snippet for a trail that is not links. */
+    breadcrumbs?: BreadcrumbItem[] | Snippet;
     /** The glyph alone. The tinted square around it is this component's. */
     icon?: Snippet;
     /** Omit for a header that is a breadcrumb bar with actions. */

package/dist/components/ui/page-section/index.d.ts

@@ -0,0 +1,2 @@
+export { default as PageSection } from './page-section.svelte';
+export { default } from './page-section.svelte';

package/dist/components/ui/page-section/index.js

@@ -0,0 +1,2 @@
+export { default as PageSection } from './page-section.svelte';
+export { default } from './page-section.svelte';

package/dist/components/ui/page-section/page-section.svelte

@@ -0,0 +1,92 @@
+<script lang="ts">
+	/**
+	 * A section of a page, under its PageHeader: a heading, an optional line of
+	 * explanation, trailing actions, and the section's content at one distance
+	 * below them.
+	 *
+	 * One app had five recipes for this one role, from an 11px uppercase kicker
+	 * to a 20px display heading, and each page spaced its content from the
+	 * heading differently. The heading and the gap under it are this
+	 * component's, because those are the halves that drift.
+	 *
+	 * Level 2 is a section, in the display face one step under the page title.
+	 * Level 3 is a subsection, in the body face at a Panel title's size, so a
+	 * titled card and a subsection read as the same rank. There is no uppercase
+	 * kicker form: a small caps label above content is the column head of a
+	 * table or a nav group, never a heading.
+	 */
+	import type { Snippet } from 'svelte';
+	import type { HTMLAttributes } from 'svelte/elements';
+	import { cn, type WithElementRef } from '../../../utils.js';
+
+	let {
+		title,
+		level = 2,
+		description,
+		count,
+		actions,
+		children,
+		id,
+		ref = $bindable(null),
+		class: className,
+		...restProps
+	}: Omit<WithElementRef<HTMLAttributes<HTMLElement>>, 'title'> & {
+		title: string;
+		/** 2, a section of the page; 3, a section within one. */
+		level?: 2 | 3;
+		/** A sentence or two under the heading. It wraps. */
+		description?: string;
+		/** How many things the section holds, set beside the heading. */
+		count?: number;
+		/** Controls for the section, trailing the heading. */
+		actions?: Snippet;
+		children?: Snippet;
+		/** The heading's id, for a link to the section. One is generated otherwise. */
+		id?: string;
+	} = $props();
+
+	const fallbackId = $props.id();
+	const headingId = $derived(id ?? `section-${fallbackId}`);
+</script>
+
+<section
+	bind:this={ref}
+	aria-labelledby={headingId}
+	data-slot="page-section"
+	class={cn('flex min-w-0 flex-col', level === 2 ? 'gap-4' : 'gap-3', className)}
+	{...restProps}
+>
+	<!-- Actions share the heading's row, so on a phone they stay beside the
+	     heading rather than dropping under the description. -->
+	<header class="flex min-w-0 flex-col gap-1">
+		<div class="flex min-w-0 flex-wrap items-center gap-x-4 gap-y-2">
+			<svelte:element
+				this={`h${level}`}
+				id={headingId}
+				class={cn(
+					'flex min-w-0 items-baseline gap-2 scroll-mt-4 font-semibold',
+					level === 2
+						? 'font-display text-section tracking-[var(--ds-font-display-tracking,-0.015em)]'
+						: 'text-body leading-tight tracking-tight'
+				)}
+			>
+				<span class="min-w-0">{title}</span>
+				{#if count !== undefined}
+					<span
+						class="text-muted-foreground font-sans text-sm font-normal tracking-normal tabular-nums"
+						>{count}</span
+					>
+				{/if}
+			</svelte:element>
+			{#if actions}
+				<div class="ml-auto flex min-w-0 flex-wrap items-center justify-end gap-2">
+					{@render actions()}
+				</div>
+			{/if}
+		</div>
+		{#if description}
+			<p class="text-muted-foreground ds-measure text-sm" data-measure="prose">{description}</p>
+		{/if}
+	</header>
+	{@render children?.()}
+</section>