@janga/norna 0.7.24 → 0.7.26

package/scripts/migrate-check.mjs

@@ -0,0 +1,19 @@
+import {
+	auditDocusaurusProject,
+	migrationCheckUsage,
+	parseMigrationCheckArgs,
+	writeMigrationReport,
+} from './lib/docusaurus-migration-audit.mjs';
+
+const parsed = parseMigrationCheckArgs(process.argv.slice(2));
+if (parsed.help) {
+	console.log(migrationCheckUsage);
+	process.exit(0);
+}
+
+const report = await auditDocusaurusProject({ sourceRoot: parsed.sourceRoot });
+await writeMigrationReport(report, parsed.reportDir, { sourceRoot: parsed.sourceRoot });
+console.log('Docusaurus migration audit written to ' + parsed.reportDir);
+console.log('Source pages: ' + report.summary.pages);
+console.log('Pages requiring attention: ' + report.summary.pagesWithFindings);
+console.log('Findings: ' + report.summary.findings);

package/scripts/sync-content-sections.mjs

@@ -233,6 +233,7 @@ try {
 const siteStructure = await getSiteStructure();
 const contentFiles = siteStructure.contentFiles;
 for (const warning of siteStructure.warnings) {
+	if (warning.code === 'empty-category') continue;
 	addIssue({
 		severity: 'warning',
 		message: warning.message,
@@ -272,6 +273,14 @@ for (const contentFile of contentFiles) {
 		prelude,
 		regions: sections,
 	} = page;
+	for (const issue of page.diagnostics.filter((candidate) => candidate.code === 'heading-inside-details')) {
+		addContentIssue(contentFile, issue);
+	}
+	for (const issue of page.noteDiagnostics) {
+		const section = sections.find((candidate) => issue.offset >= candidate.startOffset && issue.offset < candidate.endOffset);
+		if (section) addSectionIssue(contentFile, section, issue);
+		else addContentIssue(contentFile, issue);
+	}
 	const invalidHeadingLines = new Set();
 	for (const issue of headingIdentifierIssues) {
 		invalidHeadingLines.add(issue.heading.line);
@@ -362,14 +371,19 @@ for (const contentFile of contentFiles) {
 		const blockResults = { blocks: section.blocks, errors: section.blockErrors };
 		blockResultsBySection.set(section, blockResults);
 
-		for (const error of section.noteErrors) {
+		for (const error of section.tabErrors) {
+			addSectionIssue(contentFile, section, { severity: 'error', message: error.message });
+		}
+
+		for (const error of section.calloutErrors) {
 			addSectionIssue(contentFile, section, {
-				severity: 'error',
+				severity: error.severity ?? 'error',
 				message: error.message,
+				fix: error.fix,
 			});
 		}
 
-		for (const error of section.calloutErrors) {
+		for (const error of section.codeFenceErrors) {
 			addSectionIssue(contentFile, section, {
 				severity: 'error',
 				message: error.message,
@@ -377,7 +391,7 @@ for (const contentFile of contentFiles) {
 			});
 		}
 
-		for (const error of section.codeFenceErrors) {
+		for (const error of section.tableErrors) {
 			addSectionIssue(contentFile, section, {
 				severity: 'error',
 				message: error.message,
@@ -421,17 +435,32 @@ const listedNavigationTree = getListedSiteNavigationTree(siteStructure.nodes.map
 
 for (const context of contentFileContexts) {
 	const childPages = getDirectChildPages(listedNavigationTree, context.contentFile.pagePath);
-	if (childPages.length > 0) continue;
+	const warnedChildren = new Set();
 
 	for (const section of context.sections) {
 		if (!context.validSections.has(section)) continue;
 		for (const block of section.blocks) {
 			if (block.type !== 'page-list') continue;
-			addSectionIssue(context.contentFile, section, {
-				severity: 'error',
-				message: `page-list on line ${block.line} has no listed direct child pages to display. Navigation categories are not pages.`,
-				fix: 'Add a listed direct child page or remove the block.',
-			});
+			if (childPages.length === 0) {
+				addSectionIssue(context.contentFile, section, {
+					severity: 'error',
+					message: `page-list on line ${block.line} has no listed direct child pages to display. Navigation categories are not pages.`,
+					fix: 'Add a listed direct child page or remove the block.',
+				});
+				continue;
+			}
+			for (const child of childPages) {
+				const childContext = contentContextByPageDirectory.get(child.pageDirectory);
+				if (!childContext || warnedChildren.has(child.pageDirectory)) continue;
+				const description = childContext.frontmatterData.page?.description;
+				if (typeof description === 'string' && description.trim()) continue;
+				warnedChildren.add(child.pageDirectory);
+				addSectionIssue(context.contentFile, section, {
+					severity: 'warning',
+					message: `page-list on line ${block.line} includes ${childContext.contentFile.contentLabel} without a non-empty page.description.`,
+					fix: 'Add page.description to that child file\'s frontmatter. Explain what the reader will find or when to choose this page, rather than repeating its title.',
+				});
+			}
 		}
 	}
 }

package/scripts/sync-site-public.mjs

@@ -9,6 +9,8 @@ import {
 	sitePublicLabel,
 } from './lib/site-paths.mjs';
 import { getSiteStructure } from './lib/site-structure.mjs';
+import { getSiteLinkGraph } from './lib/site-link-graph.mjs';
+import { assertCategoryDestinationModel } from './lib/category-destinations.mjs';
 
 const keepAstroPublicEntries = new Set([
 	'images',
@@ -53,9 +55,12 @@ for (const generatedFile of generatedPublicFiles) {
 }
 
 const siteStructure = await getSiteStructure();
+const { categoryModel } = await getSiteLinkGraph({ siteStructure });
+const { destinations: categoryDestinations } = assertCategoryDestinationModel(categoryModel);
 const sitemapXml = createSitemapXml({
 	siteStructure,
 	siteUrl: projectConfig.site.url,
+	categoryDestinations,
 });
 
 await mkdir(astroPublicDir, { recursive: true });
@@ -79,4 +84,5 @@ for (const entry of sourceEntries) {
 await writeFile(path.join(astroPublicDir, sitemapFilename), sitemapXml);
 
 console.log(`Synced ${sitePublicLabel}/ to ${astroPublicLabel}/.`);
-console.log(`Generated ${astroPublicLabel}/${sitemapFilename} for ${siteStructure.contentFiles.length} public page${siteStructure.contentFiles.length === 1 ? '' : 's'}.`);
+const pageCount = siteStructure.contentFiles.length + categoryDestinations.filter(({ kind }) => kind === 'listing').length;
+console.log(`Generated ${astroPublicLabel}/${sitemapFilename} for ${pageCount} public page${pageCount === 1 ? '' : 's'}.`);

package/src/components/CardList.astro

@@ -32,6 +32,7 @@ const cardImageSizes = [
 const displayLink = (link: string) => withBasePath(projectConfig.site.basePath, link);
 const cardListClasses = [
 	'card-list',
+	'content-block-note-lane-boundary',
 	`card-list-layout-${layout}`,
 	`card-list-flow-${flow}`,
 	`card-list-size-${size}`,

package/src/components/CodeBlockCopyScript.astro

@@ -14,7 +14,7 @@ const labels = {
 		<Copy aria-hidden="true" data-code-copy-icon="copy" size={18} stroke-width={2} />
 		<Check aria-hidden="true" data-code-copy-icon="copied" hidden size={18} stroke-width={2} />
 		<X aria-hidden="true" data-code-copy-icon="failed" hidden size={18} stroke-width={2} />
-		<span class="visually-hidden" aria-live="polite" data-code-copy-status></span>
+		<span class="code-block-copy-status" aria-live="polite" data-code-copy-status></span>
 	</button>
 </template>
 
@@ -24,6 +24,39 @@ const labels = {
 		if (!(template instanceof HTMLTemplateElement)) return;
 
 		const resetTimers = new WeakMap();
+		const layoutUpdaters = [];
+		const prepareLayout = (wrapper, pre) => {
+			const topLevel = wrapper.parentElement?.classList.contains('section-markdown');
+			let scheduled = false;
+			const update = () => {
+				scheduled = false;
+				if (topLevel) {
+					const layout = ['prose', 'end', 'canvas'].find((candidate) => {
+						wrapper.dataset.codeLayout = candidate;
+						return pre.scrollWidth <= pre.clientWidth + 1;
+					}) ?? 'canvas';
+					wrapper.dataset.codeLayout = layout;
+				}
+				const overflow = pre.scrollWidth > pre.clientWidth + 1;
+				wrapper.dataset.codeOverflow = String(overflow);
+				if (overflow) pre.setAttribute('tabindex', '0');
+				else pre.removeAttribute('tabindex');
+			};
+			const schedule = () => {
+				if (scheduled) return;
+				scheduled = true;
+				requestAnimationFrame(update);
+			};
+			layoutUpdaters.push(schedule);
+			if ('ResizeObserver' in window) {
+				const observer = new ResizeObserver(schedule);
+				observer.observe(wrapper.parentElement);
+				const body = wrapper.closest('.section-body');
+				if (body) observer.observe(body);
+			}
+			window.addEventListener('resize', schedule, { passive: true });
+			update();
+		};
 		const copyText = async (text) => {
 			if (navigator.clipboard?.writeText) {
 				try {
@@ -45,7 +78,7 @@ const labels = {
 
 		const showState = (button, state) => {
 			button.querySelectorAll('[data-code-copy-icon]').forEach((icon) => {
-				icon.hidden = icon.getAttribute('data-code-copy-icon') !== state;
+				icon.toggleAttribute('hidden', icon.getAttribute('data-code-copy-icon') !== state);
 			});
 			const status = button.querySelector('[data-code-copy-status]');
 			if (status) status.textContent = state === 'copied' ? labels.copied : labels.failed;
@@ -54,11 +87,11 @@ const labels = {
 			clearTimeout(resetTimers.get(button));
 			resetTimers.set(button, setTimeout(() => {
 				button.querySelectorAll('[data-code-copy-icon]').forEach((icon) => {
-					icon.hidden = icon.getAttribute('data-code-copy-icon') !== 'copy';
+					icon.toggleAttribute('hidden', icon.getAttribute('data-code-copy-icon') !== 'copy');
 				});
-				if (status) status.textContent = '';
+				// Keep the live announcement available after the visual feedback ends.
 				delete button.dataset.copyState;
-			}, 2000));
+			}, state === 'copied' ? 1000 : 2000));
 		};
 
 		document.querySelectorAll('#main-content .section-markdown pre > code').forEach((code) => {
@@ -77,10 +110,14 @@ const labels = {
 
 			const button = template.content.firstElementChild?.cloneNode(true);
 			if (!(button instanceof HTMLButtonElement)) return;
-			wrapper.append(button);
+			const title = codeExample?.querySelector(':scope > .norna-code-title');
+			(title ?? wrapper).append(button);
+			prepareLayout(wrapper, pre);
 			button.addEventListener('click', async () => {
 				if (button.dataset.copyBusy === 'true') return;
 				button.dataset.copyBusy = 'true';
+				const status = button.querySelector('[data-code-copy-status]');
+				if (status) status.textContent = '';
 				try {
 					await copyText(code.textContent ?? '');
 					showState(button, 'copied');
@@ -91,6 +128,12 @@ const labels = {
 				}
 			});
 		});
+		const preferences = new MutationObserver(() => layoutUpdaters.forEach((update) => update()));
+		preferences.observe(document.documentElement, {
+			attributes: true,
+			attributeFilter: ['data-reading-width', 'data-focus-reading', 'dir'],
+		});
+		document.fonts?.ready.then(() => layoutUpdaters.forEach((update) => update()));
 
 		template.remove();
 	})();

package/src/components/ContentBlocks.astro

@@ -0,0 +1,39 @@
+---
+import CardList from './CardList.astro';
+import ImageCarousel from './ImageCarousel.astro';
+import ImageStack from './ImageStack.astro';
+import PageList from './PageList.astro';
+import type { SectionContentBlock } from '../lib/sectionContent';
+
+interface Props {
+	blocks: SectionContentBlock[];
+	title: string;
+	images: {
+		maxAvailableWidthPercent: { desktop: number; mobile: number };
+		maxAvailableHeightPercent?: { desktop: number; mobile: number };
+	};
+	cardWidth: 'text' | 'narrow' | 'normal' | 'wide';
+	prioritizeFirstImage?: boolean;
+}
+const { blocks, title, images, cardWidth, prioritizeFirstImage = false } = Astro.props;
+const firstMediaIndex = blocks.findIndex((block) => block.type === 'image-stack' || block.type === 'image-carousel');
+---
+
+{blocks.map((block, index) => {
+	if (block.type === 'html') return <div class="section-markdown" set:html={block.html} />;
+	if (block.type === 'tabs') return (
+		<div class="content-tabs content-block-note-lane-boundary" data-content-tabs>
+			<div class="content-tabs-controls" data-tabs-controls hidden></div>
+			{block.panels.map((panel, panelIndex) => (
+				<div class="content-tab-panel" data-tab-panel role="group" aria-labelledby={`norna-tabs-label-${block.index}-${panelIndex}`}>
+					<div class="content-tab-label" data-tab-label id={`norna-tabs-label-${block.index}-${panelIndex}`}>{panel.label}</div>
+					<Astro.self blocks={panel.contentBlocks} title={title} images={images} cardWidth={cardWidth} />
+				</div>
+			))}
+		</div>
+	);
+	if (block.type === 'page-list') return <PageList pages={block.pages} />;
+	if (block.type === 'card-list') return <CardList cards={block.cards} layout={block.layout} flow={block.flow} size={block.size} width={block.width ?? cardWidth} />;
+	if (block.type === 'image-carousel') return <ImageCarousel title={title} images={block.images} maxAvailableWidthPercent={images.maxAvailableWidthPercent} maxAvailableHeightPercent={images.maxAvailableHeightPercent} priorityFirstImage={prioritizeFirstImage && index === firstMediaIndex} />;
+	return <ImageStack title={title} images={block.images} maxAvailableWidthPercent={images.maxAvailableWidthPercent} priorityFirstImage={prioritizeFirstImage && index === firstMediaIndex} />;
+})}

package/src/components/ContentTabsScript.astro

@@ -0,0 +1,60 @@
+<script>
+	document.querySelectorAll<HTMLElement>('[data-content-tabs]').forEach((group, groupIndex) => {
+		const controls = group.querySelector<HTMLElement>('[data-tabs-controls]')!;
+		const panels = Array.from(group.querySelectorAll<HTMLElement>(':scope > [data-tab-panel]'));
+		const labels = panels.map((panel) => panel.querySelector<HTMLElement>('[data-tab-label]')!);
+		const buttons = panels.map((panel, index) => {
+			const button = document.createElement('button');
+			const id = `norna-tabs-${groupIndex}-${index}`;
+			button.type = 'button';
+			button.id = `${id}-tab`;
+			button.textContent = labels[index].textContent;
+			button.setAttribute('role', 'tab');
+			button.setAttribute('aria-controls', id);
+			panel.id = id;
+			panel.setAttribute('role', 'tabpanel');
+			panel.setAttribute('aria-labelledby', button.id);
+			panel.tabIndex = 0;
+			controls.append(button);
+			return button;
+		});
+		const heading = group.closest('section')?.querySelector<HTMLElement>('h1, h2');
+		controls.setAttribute('role', 'tablist');
+		if (heading?.id) controls.setAttribute('aria-labelledby', heading.id);
+		const select = (selected: number, focus = false) => {
+			buttons.forEach((button, index) => {
+				button.setAttribute('aria-selected', String(index === selected));
+				button.tabIndex = index === selected ? 0 : -1;
+				panels[index].hidden = index !== selected;
+			});
+			if (focus) buttons[selected].focus({ preventScroll: true });
+			group.dispatchEvent(new CustomEvent('norna:tab-change', { bubbles: true }));
+			window.dispatchEvent(new Event('resize'));
+		};
+		buttons.forEach((button, index) => {
+			button.addEventListener('click', () => select(index));
+			button.addEventListener('keydown', (event) => {
+				let selected = index;
+				if (event.key === 'ArrowRight') selected = (index + 1) % buttons.length;
+				else if (event.key === 'ArrowLeft') selected = (index - 1 + buttons.length) % buttons.length;
+				else if (event.key === 'Home') selected = 0;
+				else if (event.key === 'End') selected = buttons.length - 1;
+				else return;
+				event.preventDefault();
+				select(selected, true);
+			});
+		});
+		controls.hidden = false;
+		group.dataset.tabsReady = 'true';
+		select(0);
+		const revealTarget = () => {
+			let id: string;
+			try { id = decodeURIComponent(location.hash.slice(1)); } catch { return; }
+			const target = document.getElementById(id);
+			const index = panels.findIndex((panel) => target && panel.contains(target));
+			if (index >= 0) { select(index); target?.scrollIntoView(); }
+		};
+		window.addEventListener('hashchange', revealTarget);
+		revealTarget();
+	});
+</script>

package/src/components/DisplaySettings.astro

@@ -49,25 +49,23 @@ const widthOptions = [
 	<form class="display-settings-panel">
 		<p class="display-settings-title">{labels.displaySettings}</p>
 
-		{controls.appearance && (
-			<fieldset>
-				<legend>{labels.appearance}</legend>
-				<div class="display-settings-segmented">
-					{appearanceOptions.map((option) => (
-						<label>
-							<input
-								type="radio"
-								name="appearance"
-								value={option.value}
-								checked={defaults.appearance === option.value}
-								data-reader-appearance
-							/>
-							<span>{option.label}</span>
-						</label>
-					))}
-				</div>
-			</fieldset>
-		)}
+		<fieldset>
+			<legend>{labels.appearance}</legend>
+			<div class="display-settings-segmented">
+				{appearanceOptions.map((option) => (
+					<label>
+						<input
+							type="radio"
+							name="appearance"
+							value={option.value}
+							checked={defaults.appearance === option.value}
+							data-reader-appearance
+						/>
+						<span>{option.label}</span>
+					</label>
+				))}
+			</div>
+		</fieldset>
 
 		{controls.readingWidth && (
 			<fieldset>

package/src/components/ImageCarousel.astro

@@ -45,7 +45,10 @@ const carouselStyle = carouselAspectRatio
 	: undefined;
 ---
 
-<div class="managed-images" aria-label={`${projectConfig.locale.labels.images}: ${title}`}>
+<div
+	class="managed-images content-block-note-lane-boundary"
+	aria-label={`${projectConfig.locale.labels.images}: ${title}`}
+>
 	<section
 		class="managed-image-item image-carousel"
 		data-carousel

package/src/components/ImageStack.astro

@@ -1,6 +1,7 @@
 ---
 import projectConfig from '../../scripts/lib/project-config.mjs';
-import { getImageAttributes } from '../lib/generatedImages';
+import { Maximize2 } from '@lucide/astro';
+import { getImageAttributes, getImageInspectionAttributes } from '../lib/generatedImages';
 import {
 	getCaptionId,
 	getManagedImageSizes,
@@ -23,21 +24,45 @@ const { title, images, maxAvailableWidthPercent, priorityFirstImage = false } =
 const managedImageSizes = getManagedImageSizes(maxAvailableWidthPercent);
 ---
 
-<div class="image-stack" aria-label={`${projectConfig.locale.labels.images}: ${title}`}>
+<div
+	class="image-stack content-block-note-lane-boundary"
+	aria-label={`${projectConfig.locale.labels.images}: ${title}`}
+>
 	{images.map((image, itemIndex) => {
 		const isPriorityItem = priorityFirstImage && itemIndex === 0;
 		const captionId = image.caption ? getCaptionId(image, itemIndex) : undefined;
+		const inspection = getImageInspectionAttributes(image.src ?? image.image);
+		const inspectionDescription = image.alt || image.caption || `${title} ${itemIndex + 1}`;
+		const inspectionLabel = projectConfig.locale.labels.inspectImage.replace('{description}', inspectionDescription);
+		const inspectionStyle = inspection.width && inspection.height
+			? `--managed-image-intrinsic-width: ${inspection.width}px; --managed-image-aspect-ratio: ${inspection.width / inspection.height}`
+			: undefined;
 
 		return (
-			<figure class="managed-image-item">
+			<figure class="managed-image-item" data-image-stack-figure>
 				<div class="managed-image-frame">
-					<img
-						{...getImageAttributes(image.src ?? image.image, managedImageSizes)}
-						class:list={['managed-image', getImageClass(image)]}
-						alt={image.alt ?? ''}
+					<a
+						class="managed-image-inspection-link"
+						href={inspection.href}
+						aria-label={inspectionLabel}
 						aria-describedby={captionId}
-						{...getImageLoadingProps(isPriorityItem)}
-					/>
+						data-image-inspection-trigger
+						data-image-intrinsic-width={inspection.width}
+						data-image-intrinsic-height={inspection.height}
+						data-image-inspection-scalable={inspection.scalable ? 'true' : undefined}
+						style={inspectionStyle}
+					>
+						<img
+							{...getImageAttributes(image.src ?? image.image, managedImageSizes)}
+							class:list={['managed-image', getImageClass(image)]}
+							alt={image.alt ?? ''}
+							aria-describedby={captionId}
+							{...getImageLoadingProps(isPriorityItem)}
+						/>
+						<span class="managed-image-inspection-affordance" aria-hidden="true">
+							<Maximize2 size={18} stroke-width={2} />
+						</span>
+					</a>
 				</div>
 				{image.caption && (
 					<figcaption class="image-meta" id={captionId}>