@janga/norna 0.7.18 → 0.7.23

package/src/lib/sectionContent.ts

@@ -2,15 +2,7 @@ import { markdownToHtml } from 'satteri';
 import projectConfig from '../../scripts/lib/project-config.mjs';
 import {
 	formatHeadingIdentifierIssue,
-	getHeadingIdentifierIssues,
 } from '../../scripts/lib/heading-ids.mjs';
-import { getBodySections } from '../../scripts/lib/site-content.mjs';
-import {
-	extractInlineNoteDiagnostics,
-	extractNornaMarkdownBlocks,
-	splitNornaMarkdownBlockMarkers,
-	splitNornaRenderedCodeBlocks,
-} from '../../scripts/lib/norna-markdown-blocks.mjs';
 import { applyBasePathToHtml } from './basePath';
 import type { SitePage } from './sitePages';
 
@@ -32,18 +24,31 @@ type CardListLayout = 'image-top' | 'image-left' | 'image-right';
 type CardListFlow = 'grid' | 'stack';
 type CardListSize = 's' | 'm' | 'l' | 'xl';
 type CardListWidth = 'text' | 'narrow' | 'normal' | 'wide';
+type ParsedImageBlock = {
+	type: 'image-stack' | 'image-carousel';
+	images: Array<{ image: string; alt?: string; caption?: string }>;
+};
+type ParsedCardListBlock = {
+	type: 'card-list';
+	layout: CardListLayout;
+	flow: CardListFlow;
+	size: CardListSize;
+	width?: CardListWidth;
+	cards: CardListItem[];
+};
+type ParsedNornaBlock = ParsedImageBlock | ParsedCardListBlock;
 type InlineNote = {
 	markdown: string;
 	number: number;
 	id: string;
 	referenceId: string;
+	html?: string;
 };
 type SectionContentBlock =
 	| { type: 'html'; html: string }
 	| { type: 'image-stack'; images: ManagedImage[] }
 	| { type: 'image-carousel'; images: ManagedImage[] }
-	| { type: 'card-list'; layout: CardListLayout; flow: CardListFlow; size: CardListSize; width: CardListWidth; cards: CardListItem[] }
-	| { type: 'note'; html: string; number?: number; id?: string; referenceId?: string };
+	| { type: 'card-list'; layout: CardListLayout; flow: CardListFlow; size: CardListSize; width?: CardListWidth; cards: CardListItem[] };
 export type ResolvedSection = {
 	id: string | null;
 	title: string;
@@ -62,57 +67,9 @@ export type HeadingNavigation = SectionNavigation & {
 	parentId: string | null;
 };
 
-const contentHeadingRegex = /<h([12])\b([^>]*)>([\s\S]*?)<\/h\1>/gi;
 const explicitHeadingIdRegex = /\s*\{#([a-z0-9-]+)\}\s*$/;
 const imageProvenanceCommentRegex = /<!--\s*norna-image-provenance:[\s\S]*?-->/gi;
 
-const stripTags = (html: string) => html.replace(/<[^>]*>/g, '');
-
-const decodeHtmlEntities = (value: string) =>
-	value
-		.replace(/&amp;/g, '&')
-		.replace(/&lt;/g, '<')
-		.replace(/&gt;/g, '>')
-		.replace(/&quot;/g, '"')
-		.replace(/&#39;/g, "'");
-
-const getHeadingTitle = (headingHtml: string) =>
-	decodeHtmlEntities(stripTags(headingHtml)).replace(explicitHeadingIdRegex, '').trim();
-
-const getHeadingTitleHtml = (headingHtml: string) =>
-	prepareContentHtml(headingHtml.replace(explicitHeadingIdRegex, '').trim());
-
-export const getHeadingNavigation = async (
-	markdown: string,
-	sourceLabel = 'Markdown',
-): Promise<HeadingNavigation[]> => {
-	const bodyStructure = await getBodySections(markdown);
-	const issues = getHeadingIdentifierIssues(bodyStructure.headings);
-	if (issues.length > 0) throw new Error(formatHeadingIdentifierIssue(issues[0], sourceLabel));
-
-	let parentId: string | null = null;
-	return bodyStructure.headings.flatMap((heading) => {
-		if (heading.depth === 1 || !heading.id) return [];
-		if (heading.depth === 2) parentId = heading.id;
-
-		return [{
-			depth: heading.depth,
-			id: heading.id,
-			parentId: heading.depth === 3 ? parentId : null,
-			title: heading.title,
-		}];
-	});
-};
-
-export const getSectionNavigation = async (
-	markdown: string,
-	sourceLabel = 'Markdown',
-): Promise<SectionNavigation[]> => (
-	(await getHeadingNavigation(markdown, sourceLabel))
-		.filter((heading) => heading.depth === 2)
-		.map(({ id, title }) => ({ id, title }))
-);
-
 const stripImageProvenanceComments = (html: string) => html.replace(imageProvenanceCommentRegex, '');
 
 const prepareContentHtml = (html: string) =>
@@ -121,62 +78,6 @@ const prepareContentHtml = (html: string) =>
 		stripImageProvenanceComments(html),
 	);
 
-const htmlVoidElements = new Set([
-	'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link',
-	'meta', 'param', 'source', 'track', 'wbr',
-]);
-
-// Keep notes aligned with the Markdown block immediately before them instead of
-// aligning them with a whole run of paragraphs rendered as one HTML fragment.
-const splitHtmlIntoBlocks = (html: string) => {
-	const tagRegex = /<!--[\s\S]*?-->|<\/?([a-z][\w:-]*)(?:\s[^<>]*?)?\/?>/gi;
-	const blocks: string[] = [];
-	let blockStart = -1;
-	let depth = 0;
-	let cursor = 0;
-
-	for (const match of html.matchAll(tagRegex)) {
-		const start = match.index ?? 0;
-		const token = match[0] ?? '';
-		const tagName = match[1]?.toLowerCase();
-		if (!tagName) continue;
-
-		const isClosing = /^<\//.test(token);
-		const isSelfClosing = /\/\s*>$/.test(token) || htmlVoidElements.has(tagName);
-
-		if (isClosing) {
-			if (depth > 0) depth -= 1;
-			if (depth === 0 && blockStart >= 0) {
-				blocks.push(html.slice(blockStart, start + token.length));
-				cursor = start + token.length;
-				blockStart = -1;
-			}
-			continue;
-		}
-
-		if (depth === 0) {
-			if (blockStart < 0) blockStart = start;
-			if (isSelfClosing) {
-				blocks.push(html.slice(blockStart, start + token.length));
-				cursor = start + token.length;
-				blockStart = -1;
-			}
-		}
-
-		if (!isSelfClosing) depth += 1;
-	}
-
-	if (blockStart >= 0) {
-		blocks.push(html.slice(blockStart).trim());
-		cursor = html.length;
-	}
-
-	const prefix = html.slice(0, blocks.length > 0 ? html.indexOf(blocks[0]!) : html.length).trim();
-	const suffix = html.slice(cursor).trim();
-	return [prefix, ...blocks, suffix].filter(Boolean);
-};
-
-const inlineNoteMarkerRegex = /^\s*<norna-inline-note\s+data-note-index="(\d+)"\s*><\/norna-inline-note>\s*$/i;
 const noteDeclarationParagraphRegex = /<p>\s*\{note:\s*[\s\S]*?\}\s*<\/p>/gi;
 const htmlCodeRegionRegex = /<pre\b[\s\S]*?<\/pre>|<code\b[\s\S]*?<\/code>/gi;
 
@@ -201,32 +102,22 @@ const applyInlineNoteMarkup = (html: string, notes: InlineNote[]) => {
 		if (!note) return '{note-ref}';
 
 		referenceIndex += 1;
-		return `\u2060<sup class="section-note-ref"><a id="${note.referenceId}" href="#${note.id}" aria-label="Note ${note.number}" aria-describedby="${note.id}" data-note-id="${note.id}">${note.number}</a></sup>`;
+		return [
+			'\u2060',
+			`<sup class="section-note-ref"><a id="${note.referenceId}" href="#${note.id}" aria-label="Note ${note.number}" aria-describedby="${note.id}">${note.number}</a></sup>`,
+			`<span class="section-note section-note-margin" id="${note.id}" aria-label="Note ${note.number}" role="note">`,
+			`<a class="section-note-number" href="#${note.referenceId}" aria-label="Note ${note.number}">${note.number}</a>`,
+			`<span class="section-note-content">${note.html ?? ''}</span>`,
+			'</span>',
+		].join('');
 	}));
 
-	let noteIndex = 0;
-	return withReferences.replace(noteDeclarationParagraphRegex, () => {
-		const marker = `<norna-inline-note data-note-index="${noteIndex}"></norna-inline-note>`;
-		noteIndex += 1;
-		return marker;
-	});
-};
-
-const getRawMarkdownSections = (bodySections: Awaited<ReturnType<typeof getBodySections>>['sections']) => {
-	const sections = new Map<string, string>();
-
-	for (const section of bodySections) {
-		const id = section.isPageTitle ? '__page-title' : section.id;
-		if (!id) continue;
-		sections.set(id, section.text);
-	}
-
-	return sections;
+	return withReferences.replace(noteDeclarationParagraphRegex, '');
 };
 
 const applyH3HeadingIds = (
 	html: string,
-	headings: Awaited<ReturnType<typeof getBodySections>>['headings'],
+	headings: Array<{ id: string | null }>,
 ) => {
 	let headingIndex = 0;
 	const result = html.replace(/<h3\b([^>]*)>([\s\S]*?)<\/h3>/gi, (_match, attributes, headingHtml) => {
@@ -260,47 +151,89 @@ const renderInlineNoteMarkdown = async (markdown: string) => {
 		throw new Error('Inline notes cannot contain images. Use a Norna image block with a caption instead.');
 	}
 
-	return prepareContentHtml(result.html);
+	const inlineHtml = result.html.trim();
+	const paragraph = inlineHtml.match(/^<p>([\s\S]*)<\/p>$/i);
+	if (!paragraph) {
+		throw new Error('Inline notes support inline Markdown only. Move headings, lists, and separate paragraphs into the page content.');
+	}
+
+	return paragraph[1] ?? '';
+};
+
+const renderHeadingTitleHtml = async (headingSource: string) => {
+	const headingMarkdown = headingSource
+		.replace(/^#{1,6}[ \t]+/, '')
+		.replace(explicitHeadingIdRegex, '')
+		.trim();
+	const result = await markdownToHtml(headingMarkdown, {
+		features: {
+			gfm: true,
+			smartPunctuation: true,
+		},
+	});
+	const paragraph = result.html.trim().match(/^<p>([\s\S]*)<\/p>$/i);
+	if (!paragraph) throw new Error('Markdown heading could not be rendered as inline content.');
+	return prepareContentHtml(paragraph[1] ?? '');
+};
+
+const splitRenderedRegions = (html: string, regionCount: number) => {
+	const markerRegex = /<norna-region\s+data-index="(\d+)"\s*><\/norna-region>/g;
+	const markers = Array.from(html.matchAll(markerRegex));
+	if (markers.length !== regionCount) {
+		throw new Error(`Rendered Markdown contains ${markers.length} page region markers, but ${regionCount} regions were parsed.`);
+	}
+
+	return markers.map((marker, position) => {
+		const index = Number.parseInt(marker[1] ?? '', 10);
+		if (index !== position) throw new Error(`Rendered page region ${position + 1} has unexpected index ${index}.`);
+		const start = (marker.index ?? 0) + marker[0].length;
+		const end = markers[position + 1]?.index ?? html.length;
+		return html.slice(start, end).trim();
+	});
+};
+
+const splitNornaBlockMarkers = (html: string, blocks: ParsedNornaBlock[]) => {
+	const result: Array<{ type: 'html'; html: string } | ParsedNornaBlock> = [];
+	const markerRegex = /<norna-block\s+data-index="(\d+)"\s*><\/norna-block>/g;
+	const seen = new Set<number>();
+	let cursor = 0;
+
+	for (const match of html.matchAll(markerRegex)) {
+		const start = match.index ?? 0;
+		if (start > cursor) result.push({ type: 'html', html: html.slice(cursor, start) });
+
+		const index = Number.parseInt(match[1] ?? '', 10);
+		const block = blocks[index];
+		if (!block) throw new Error(`Rendered Norna block ${index + 1} has no matching parsed block.`);
+		seen.add(index);
+		result.push(block);
+		cursor = start + match[0].length;
+	}
+
+	if (cursor < html.length) result.push({ type: 'html', html: html.slice(cursor) });
+	if (seen.size !== blocks.length) {
+		throw new Error(`Rendered Markdown contains ${seen.size} Norna block markers, but ${blocks.length} blocks were parsed.`);
+	}
+
+	return result.filter((block) => block.type !== 'html' || block.html.trim());
 };
 
 const resolveContentBlocks = async (
 	html: string,
-	rawMarkdown: string,
+	blocks: ParsedNornaBlock[],
 	page: SitePage,
 	inlineNotes: InlineNote[] = [],
 ) => {
-	const rawBlocks = extractNornaMarkdownBlocks(rawMarkdown);
-	const renderedHtml = applyInlineNoteMarkup(html, inlineNotes);
-	const splitBlocks = rawBlocks.length > 0
-		? splitNornaRenderedCodeBlocks(renderedHtml, rawBlocks)
-		: splitNornaMarkdownBlockMarkers(renderedHtml);
-	const hasNotes = inlineNotes.length > 0;
-	const contentBlocks = hasNotes
-		? splitBlocks.flatMap((block) => block.type === 'html'
-			? splitHtmlIntoBlocks(block.html).map((htmlBlock) => ({ type: 'html' as const, html: htmlBlock }))
-			: [block])
-		: splitBlocks;
+	const renderedNotes = await Promise.all(inlineNotes.map(async (note) => ({
+		...note,
+		html: await renderInlineNoteMarkdown(note.markdown),
+	})));
+	const renderedHtml = applyInlineNoteMarkup(html, renderedNotes);
+	const splitBlocks = splitNornaBlockMarkers(renderedHtml, blocks);
 	const resolvedBlocks: SectionContentBlock[] = [];
 
-	for (const block of contentBlocks) {
+	for (const block of splitBlocks) {
 		if (block.type === 'html') {
-			const inlineNoteMarker = block.html.match(inlineNoteMarkerRegex);
-			if (inlineNoteMarker) {
-				const note = inlineNotes[Number(inlineNoteMarker[1])];
-				if (!note) {
-					throw new Error('Norna inline note markup could not be matched to its note text.');
-				}
-
-				resolvedBlocks.push({
-					type: 'note',
-					html: await renderInlineNoteMarkdown(note.markdown),
-					number: note.number,
-					id: note.id,
-					referenceId: note.referenceId,
-				});
-				continue;
-			}
-
 			resolvedBlocks.push({ type: 'html', html: prepareContentHtml(block.html) });
 			continue;
 		}
@@ -334,46 +267,32 @@ const resolveContentBlocks = async (
 
 export const getSectionsContent = async (
 	html: string,
-	rawMarkdown: string,
 	page: SitePage,
-	sourceLabel = 'Markdown',
 ) => {
-	const matches = Array.from(html.matchAll(contentHeadingRegex));
-	const bodyStructure = await getBodySections(rawMarkdown);
-	const headingIdentifierIssues = getHeadingIdentifierIssues(bodyStructure.headings);
+	const pageDocument = page.markdownDocument;
+	const sourceLabel = page.contentLabel;
+	const headingIdentifierIssues = pageDocument.headingIssues;
 	if (headingIdentifierIssues.length > 0) {
 		throw new Error(formatHeadingIdentifierIssue(headingIdentifierIssues[0], sourceLabel));
 	}
-	const rawSections = getRawMarkdownSections(bodyStructure.sections);
 	const sections: ResolvedSection[] = [];
 	const sectionIds = new Set<string>();
 	let nextNoteNumber = 1;
-	const pageHeadingCount = matches.filter((match) => match[1] === '1').length;
+	const pageHeadingCount = pageDocument.pageHeadings.length;
 
-	if (pageHeadingCount !== 1 || matches[0]?.[1] !== '1') {
+	if (pageHeadingCount !== 1 || pageDocument.regions[0]?.kind !== 'page-intro') {
 		throw new Error('Each Norna page must start with exactly one Markdown H1 page title, for example "# About".');
 	}
+	const renderedRegions = splitRenderedRegions(html, pageDocument.regions.length);
 
-	for (let index = 0; index < matches.length; index += 1) {
-		const match = matches[index];
-		const bodySection = bodyStructure.sections[index];
-		const headingLevel = Number.parseInt(match[1] ?? '', 10) as 1 | 2;
-		const headingHtml = match[3] ?? '';
-		if (!bodySection || bodySection.level !== headingLevel) {
-			throw new Error('Markdown H1/H2 headings could not be matched to the rendered page content.');
-		}
+	for (let index = 0; index < renderedRegions.length; index += 1) {
+		const bodySection = pageDocument.regions[index];
+		if (!bodySection) throw new Error(`Parsed page region ${index + 1} is missing.`);
+		const headingLevel = bodySection.heading.depth as 1 | 2;
 		const id = bodySection.id;
-		const contentStart = (match.index ?? 0) + match[0].length;
-		const nextMatch = matches[index + 1];
-		const contentEnd = nextMatch?.index ?? html.length;
-		const nextBodySection = bodyStructure.sections[index + 1];
-		const h3Headings = bodyStructure.headings.filter((heading) => (
-			heading.depth === 3
-			&& heading.index > bodySection.index
-			&& heading.index < (nextBodySection?.index ?? Number.POSITIVE_INFINITY)
-		));
-		const content = applyH3HeadingIds(html.slice(contentStart, contentEnd).trim(), h3Headings);
-		const title = getHeadingTitle(headingHtml);
+		const h3Headings = bodySection.headings.filter((heading) => heading.depth === 3);
+		const content = applyH3HeadingIds(renderedRegions[index] ?? '', h3Headings);
+		const title = bodySection.title;
 
 		if (headingLevel === 2 && !id) throw new Error(`Section heading "${title}" cannot produce an automatic ASCII id.`);
 
@@ -382,15 +301,14 @@ export const getSectionsContent = async (
 		}
 
 		if (id) sectionIds.add(id);
-		const rawSection = rawSections.get(id ?? '__page-title') ?? '';
-		const inlineNoteDiagnostics = extractInlineNoteDiagnostics(rawSection, {
-			label: 'Markdown section',
-		});
-		if (inlineNoteDiagnostics.errors.length > 0) {
-			throw new Error(inlineNoteDiagnostics.errors[0].message);
+		if (bodySection.blockErrors.length > 0) {
+			throw new Error(bodySection.blockErrors[0].message);
+		}
+		if (bodySection.noteErrors.length > 0) {
+			throw new Error(bodySection.noteErrors[0].message);
 		}
 
-		const inlineNotes = inlineNoteDiagnostics.notes.map((note) => {
+		const inlineNotes = bodySection.notes.map((note) => {
 			const number = nextNoteNumber;
 			nextNoteNumber += 1;
 			const pageKey = page.pageId || 'home';
@@ -406,9 +324,9 @@ export const getSectionsContent = async (
 		sections.push({
 			id,
 			title,
-			titleHtml: getHeadingTitleHtml(headingHtml),
+			titleHtml: await renderHeadingTitleHtml(bodySection.heading.source),
 			headingLevel,
-			contentBlocks: await resolveContentBlocks(content, rawSection, page, inlineNotes),
+			contentBlocks: await resolveContentBlocks(content, bodySection.blocks, page, inlineNotes),
 		});
 	}
 

package/src/lib/siteNavigation.ts

@@ -1,36 +1,36 @@
 import type { HeadingNavigation, SectionNavigation } from './sectionContent';
-import type { SitePage } from './sitePages';
+import type { SiteNode, SitePage } from './sitePages';
 
-export type PageNavigationEntry = {
-	page: SitePage;
+export type SiteNavigationEntry = {
+	node: SiteNode;
 	headings: HeadingNavigation[];
 	sections: SectionNavigation[];
 };
 
-export type PageNavigationNode = PageNavigationEntry & {
-	children: PageNavigationNode[];
+export type SiteNavigationNode = SiteNavigationEntry & {
+	children: SiteNavigationNode[];
 };
 
-export const getPageNavigationTree = (entries: PageNavigationEntry[]) => {
-	const nodes = new Map<string, PageNavigationNode>();
-	const roots: PageNavigationNode[] = [];
+export const getSiteNavigationTree = (entries: SiteNavigationEntry[]) => {
+	const nodes = new Map<string, SiteNavigationNode>();
+	const roots: SiteNavigationNode[] = [];
 
 	for (const entry of entries) {
-		nodes.set(entry.page.pagePath, { ...entry, children: [] });
+		nodes.set(entry.node.pagePath, { ...entry, children: [] });
 	}
 
 	for (const entry of entries) {
-		const node = nodes.get(entry.page.pagePath);
+		const node = nodes.get(entry.node.pagePath);
 		if (!node) continue;
 
-		if (entry.page.isHome || entry.page.parentPagePath === null) {
+		if (entry.node.isHome || entry.node.parentPagePath === null) {
 			roots.push(node);
 			continue;
 		}
 
-		const parent = nodes.get(entry.page.parentPagePath);
+		const parent = nodes.get(entry.node.parentPagePath);
 		if (!parent) {
-			throw new Error(`Page "${entry.page.pathname}" has no parent page "${entry.page.parentPagePath}".`);
+			throw new Error(`Site node "${entry.node.pagePath}" has no parent node "${entry.node.parentPagePath}".`);
 		}
 
 		parent.children.push(node);
@@ -39,11 +39,29 @@ export const getPageNavigationTree = (entries: PageNavigationEntry[]) => {
 	return roots;
 };
 
-export const getListedPageNavigationTree = (entries: PageNavigationEntry[]) => {
-	const filterListed = (nodes: PageNavigationNode[]): PageNavigationNode[] => nodes.flatMap((node) => {
-		if (!node.page.isHome && !node.page.navigation.listed) return [];
-		return [{ ...node, children: filterListed(node.children) }];
+export const getListedSiteNavigationTree = (entries: SiteNavigationEntry[]) => {
+	const filterListed = (nodes: SiteNavigationNode[]): SiteNavigationNode[] => nodes.flatMap((node) => {
+		if (!node.node.isHome && !node.node.navigation.listed) return [];
+		const children = filterListed(node.children);
+		if (node.node.kind === 'category' && children.length === 0) return [];
+		return [{ ...node, children }];
 	});
 
-	return filterListed(getPageNavigationTree(entries));
+	return filterListed(getSiteNavigationTree(entries));
 };
+
+export const getFirstPageInNavigationNode = (node: SiteNavigationNode): SitePage | null => {
+	if (node.node.kind === 'page') return node.node;
+
+	for (const child of node.children) {
+		const page = getFirstPageInNavigationNode(child);
+		if (page) return page;
+	}
+
+	return null;
+};
+
+export const flattenSiteNavigationTree = (nodes: SiteNavigationNode[]): SiteNavigationNode[] => nodes.flatMap((node) => [
+	node,
+	...flattenSiteNavigationTree(node.children),
+]);